Clear env command (#270)

A command to clear the environment and working directory

Author: rgardler-msft

.gitignore

@@ -12,4 +12,7 @@ coverage.html
 coverage.out
 
 # Ignore git repos checkout out by examples
-examples/*/.git
+examples/awesome-aks
+
+# ignore initialization files
+.openai

.vscode/launch.json

@@ -5,27 +5,66 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Launch file",
+      "name": "Debug IE",
       "type": "go",
       "request": "launch",
       "mode": "debug",
-      "cwd": "${workspaceFolder}",
-      "program": "${workspaceFolder}/cmd/ie/ie.go",
+      "program": "${workspaceRoot}/cmd/ie/ie.go",
+      "cwd": "${workspaceRoot}",
+      // Test scenarios
+      //"args": ["test", "${workspaceRoot}/docs/helloWorldDemo.md"],
+      //"args": ["test", "${workspaceRoot}/docs/prerequisitesAndIncludes.md"],
+      "args": [
+        "test",
+        "${workspaceRoot}/docs/environmentVariables.md"
+      ],
+      //"args": ["test", "${workspaceRoot}/docs/prerequisitesAndIncludes.md"],
+      "showLog": true,
+      "console": "integratedTerminal"
+    },
+    {
+      "name": "Debug EG Ask command",
+      "type": "go",
+      "request": "launch",
+      "mode": "debug",
+      "program": "${workspaceRoot}/examples/eg/main.go",
+      "cwd": "${workspaceRoot}/examples/eg",
+      "args": [
+        "write",
+        "Deploy a basic AKS cluster for testing purposes. This should focus on low cost as it is not intended for production."
+      ],
+      "showLog": true,
       "console": "integratedTerminal",
+      "envFile": "${workspaceRoot}/examples/eg/.openai"
+    },
+    {
+      "name": "Debug EG Exec Doc",
+      "type": "go",
+      "request": "launch",
+      "mode": "debug",
+      "program": "${workspaceRoot}/cmd/ie/ie.go",
+      "cwd": "${workspaceRoot}/examples/eg",
       "args": [
-        "interactive",
-        "--working-directory",
-        "${workspaceFolder}",
-        "${workspaceFolder}/${input:file}"
-      ]
+        "execute",
+        "${workspaceRoot}/examples/eg/README.md"
+      ],
+      "showLog": true,
+      "console": "integratedTerminal"
     },
-  ],
-  "inputs": [
     {
-      "id": "file",
-      "type": "promptString",
-      "description": "Enter the path to the file to process",
-      "default": "tutorial.md"
-    }
+      "name": "Debug WIP Document",
+      "type": "go",
+      "request": "launch",
+      "mode": "debug",
+      "program": "${workspaceRoot}/cmd/ie/ie.go",
+      "cwd": "${workspaceRoot}",
+      "args": [
+        "test",
+        "${workspaceRoot}/examples/AZD/aks-store-demo/aks-store-demo.md"
+      ],
+      //"args": ["test", "${workspaceRoot}/examples/AKS-Automatic/quick-kubernetes-automatic-deploy.md"],
+      "showLog": true,
+      "console": "integratedTerminal"
+    },
   ]
 }

Dockerfile

@@ -0,0 +1,36 @@
+FROM golang:1.20-alpine
+
+RUN apk update
+RUN apk add --no-cache --update \
+    bash \
+    cargo \
+    git \
+    gcc \
+    libffi-dev \
+    make \
+    musl-dev \
+    openssl-dev \
+    python3 \
+    py3-pip \
+    python3-dev
+
+WORKDIR /InnovationEngine
+
+# Create a virtual environment and install the experimental Authoring Tools and az cli
+RUN python3 -m venv /InnovationEngine/venv
+RUN /InnovationEngine/venv/bin/pip install openai azure-identity requests pygithub
+RUN /InnovationEngine/venv/bin/pip install azure-cli
+
+ENV VIRTUAL_ENV=/InnovationEngine/venv
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+
+RUN mkdir -p AuthoringTools
+RUN wget -O AuthoringTools/ada.py https://raw.githubusercontent.com/naman-msft/exec/main/tools/ada.py
+RUN chmod +x AuthoringTools/ada.py
+
+# Install the Innovation Engine
+COPY . .
+RUN make build-ie
+ENV PATH="/InnovationEngine/bin:${PATH}"
+
+CMD ["sh", "-c", "ie execute docs/helloWorldDemo.md"]

Makefile

@@ -28,6 +28,12 @@ install-ie:
 	@echo "Installing the Innovation Engine CLI..."
 	@CGO_ENABLED=0 go install -ldflags "-X $(MODULE_ROOT)/cmd/ie/commands.VERSION=dev -X $(MODULE_ROOT)/cmd/ie/commands.COMMIT=$(LATEST_COMMIT) -X $(MODULE_ROOT)/cmd/ie/commands.DATE=$(BUILD_DATE)" cmd/ie/ie.go
 
+install-ie-home:
+	@echo "Installing the Innovation Engine CLI to ~/bin..."
+	@mkdir -p ~/bin
+	@CGO_ENABLED=0 go build -ldflags "-X $(MODULE_ROOT)/cmd/ie/commands.VERSION=dev -X $(MODULE_ROOT)/cmd/ie/commands.COMMIT=$(LATEST_COMMIT) -X $(MODULE_ROOT)/cmd/ie/commands.DATE=$(BUILD_DATE)" -o ~/bin/ie cmd/ie/ie.go
+	@echo "IE installed to ~/bin/ie"
+
 # ------------------------------ Test targets ----------------------------------
 
 WITH_COVERAGE := false
@@ -82,6 +88,12 @@ test-upstream-scenarios:
 		($(MAKE) test-scenario SCENARIO="$${dir}README.md" SUBCRIPTION="$(SUBSCRIPTION)" WORKING_DIRECTORY="$${dir}" ENVIRONMENT="$(ENVIRONMENT)") || exit $$?; \
 	done
 
+test-docs:
+	@echo "Testing all documents in the docs folder"
+	for file in ./docs/*.md; do \
+		($(MAKE) test-scenario SCENARIO="$${file}") || exit $$?; \
+	done
+
 # ------------------------------- Run targets ----------------------------------
 
 run-ie: build-ie

README.md

@@ -50,9 +50,45 @@ command:
 ./bin/ie execute tutorial.md
 ```
 
+### Install to ~/bin
+
+If you want to install the Innovation Engine CLI directly to your home bin directory (so it's available system-wide), use:
+
+```bash
+make install-ie-home
+```
+
+This will build and install the `ie` binary to `~/bin/ie`. Make sure `~/bin` is in your `$PATH` by adding this to your shell profile:
+
+```bash
+export PATH="$HOME/bin:$PATH"
+```
+### Building a Container from Source
+
+```bash
+docker build -t ie .
+```
+
+Once built you can run the container and connect to it. Innovation Engine will automatically run an introductory
+document when you execute this command.
+
+```bash
+docker run -it ie
+```
+
+You can override the start command if you want to take control immediately with:
+
+```bash
+docker run -it ie /bin/sh
+```
+
 ## Testing Innovation Engine
 
-Innovation Engine is self-documenting, that is all our documentation is written to be executable. Since Innovation Engine can test the actual results of an execution against the intended reslts this means our documentation is also part of our test suite. In our `scripts` folder you will find a `test_ie.sh` script. Running this will run through all of our documentation in test mode.
+Innovation Engine is self-documenting, that is all our documentation is written to be executable. Since Innovation Engine can test the results of an execution against the intended results this means our documentation is also part of our test suite. Testing against all our documentation is easy as:
+
+```bash
+make test-docs
+```
 
 If you make any changes to the IE code (see Contributing below) we would encourage you to tun the full test suite before issuing a PR.
 
@@ -172,14 +208,27 @@ jobs:
         python3 main.py test README.md
 ```
 
+# Authoring Documents
+
+Authoring documents for use in Innovation Engine is no different from writing high quality documentation for reading. However, it does force you to follow good practice and therefore can sometimes feel a little too involved. That is  every edge case needs to be accounted for so that automated testing will reliably pass. We are therefore working on tools to help you in the authoring process.
+
+These tools are independent of Innovation Engine, however, if you build a container from source they will be included in that container. To use them you will need an Azure OpenAI key (you can use an OpenAI key if you prefer) - be sure to add them in the command below.
+
+```bash
+docker run -it \
+  -e AZURE_OPENAI_API_KEY=$AZURE_OPENAI_API_KEY \
+  -e AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT \
+  ie /bin/sh -c "python AuthoringTools/ada.py"
+```
+
 ## Contributing
 
 This is an open source project. Don't keep your code improvements,
 features and cool ideas to yourself. Please issue pull requests
 against our [GitHub repo](https://github.com/Azure/innovationengine).
 
 Be sure to use our Git pre-commit script to test your contributions
-before committing, simply run the following command: `python3 main.py test test`
+before committing, simply run the following command: `make test-docs`
 
 This project welcomes contributions and suggestions.  Most
 contributions require you to agree to a Contributor License Agreement

awesome-aks

@@ -0,0 +1 @@
+Subproject commit 7059c652e797c91d79f7e23ebc4cdd4ee83d7f8e

cmd/ie/commands/clear-env.go

@@ -0,0 +1,98 @@
+package commands
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/Azure/InnovationEngine/internal/lib"
+	"github.com/Azure/InnovationEngine/internal/logging"
+	"github.com/spf13/cobra"
+)
+
+// Register the command with our command runner.
+func init() {
+	rootCommand.AddCommand(clearEnvCommand)
+
+	// Bool flags
+	clearEnvCommand.PersistentFlags().
+		Bool("all", false, "Clear both environment variables and working directory state.")
+	clearEnvCommand.PersistentFlags().
+		Bool("working-dir", false, "Also clear the working directory state.")
+	clearEnvCommand.PersistentFlags().
+		Bool("force", false, "Force clear without confirmation prompt.")
+}
+
+var clearEnvCommand = &cobra.Command{
+	Use:   "clear-env",
+	Short: "Clear the stored environment variables and optionally working directory state.",
+	Long: `Clear the stored environment variables and optionally working directory state.
+	
+This command removes the environment state file that stores variables between
+Innovation Engine command executions. By default, it only clears environment 
+variables, but you can also clear working directory state using the flags.
+
+Examples:
+  ie clear-env                    # Clear only environment variables
+  ie clear-env --working-dir      # Clear env vars and working directory
+  ie clear-env --all              # Clear both env vars and working directory
+  ie clear-env --force            # Clear without confirmation`,
+	Run: func(cmd *cobra.Command, args []string) {
+		force, _ := cmd.Flags().GetBool("force")
+		clearAll, _ := cmd.Flags().GetBool("all")
+		clearWorkingDir, _ := cmd.Flags().GetBool("working-dir")
+
+		// Determine what to clear
+		shouldClearEnv := true // Always clear env vars
+		shouldClearWD := clearAll || clearWorkingDir
+
+		// Show confirmation unless --force is used
+		if !force {
+			fmt.Print("This will clear the stored environment state")
+			if shouldClearWD {
+				fmt.Print(" and working directory state")
+			}
+			fmt.Print(". Continue? (y/N): ")
+			
+			var response string
+			fmt.Scanln(&response)
+			if response != "y" && response != "Y" && response != "yes" {
+				fmt.Println("Operation cancelled.")
+				return
+			}
+		}
+
+		// Clear environment variables
+		if shouldClearEnv {
+			if err := lib.DeleteEnvironmentStateFile(lib.DefaultEnvironmentStateFile); err != nil {
+				// Don't error if file doesn't exist
+				if !os.IsNotExist(err) {
+					logging.GlobalLogger.Errorf("Error clearing environment variables: %s", err)
+					fmt.Printf("Error clearing environment variables: %s\n", err)
+					os.Exit(1)
+				} else {
+					fmt.Println("Environment variables state file was already clear.")
+				}
+			} else {
+				fmt.Println("Environment variables cleared successfully.")
+			}
+		}
+
+		// Clear working directory state if requested
+		if shouldClearWD {
+			if err := lib.DeleteWorkingDirectoryStateFile(lib.DefaultWorkingDirectoryStateFile); err != nil {
+				// Don't error if file doesn't exist
+				if !os.IsNotExist(err) {
+					logging.GlobalLogger.Errorf("Error clearing working directory state: %s", err)
+					fmt.Printf("Error clearing working directory state: %s\n", err)
+					os.Exit(1)
+				} else {
+					fmt.Println("Working directory state file was already clear.")
+				}
+			} else {
+				fmt.Println("Working directory state cleared successfully.")
+			}
+		}
+
+		logging.GlobalLogger.Info("Environment state cleared successfully")
+	},
+}

cmd/ie/commands/execute.go

@@ -37,7 +37,7 @@ func init() {
 var executeCommand = &cobra.Command{
 	Use:   "execute [markdown file]",
 	Args:  cobra.MinimumNArgs(1),
-	Short: "Execute the commands for an Azure deployment scenario.",
+	Short: "Execute the commands in an executable document.",
 	Run: func(cmd *cobra.Command, args []string) {
 		markdownFile := args[0]
 		if markdownFile == "" {

docs/Authoring-With-Copilot.md

@@ -0,0 +1,46 @@
+# Confgigure Copilot
+
+* CTRL+SHIFT+P
+* Type 'settings.json`
+* Select `Preferences Open User Settings`
+
+Add the following to the `settings.json` file that opens.
+
+<!-- TODO: Ensure this is updated from current user settings -->
+
+```json
+// A set of instructions that will be added to Copilot requests that generate code.
+// Instructions can come from: 
+// - a file in the workspace: `{ "file": "fileName" }`
+// - text in natural language: `{ "text": "Use underscore for field names." }`
+// 
+// Note: Keep your instructions short and precise. Poor instructions can degrade Copilot's quality and performance.
+"github.copilot.chat.codeGeneration.instructions": [
+    {
+    "text": "When writing mardown files each section should have an introductory paragraph, and optional code block and a summary paragraph."
+    },
+],
+```
+
+# Use Copilot
+
+Using Copilot to author docs is easy in Visual Studio Code.
+
+## Initial Authoring
+
+* Create a new document
+* `CTRL+I`
+* Type "Create an executable document which [Objective]"
+* Copilot will attempt to create the document for your, providing heading titles and intro paragraphs
+* Review the document, if any section is missing or needs adjustment position the cursor at that point, hit `CTRL-I`, give the instruction
+* Work through the document creating the code blocks
+
+## Testing
+
+Once you have the document in good shape and you feel it will work you can test it with Innovation Engine.
+
+* Hit CTRL-SHIFT-` to open a WSL terminal (Innovation Engine does not work in PowerShell)
+* Type `ie test filename.md`
+* The document will be executed in test mode, any failure will be reported in the terminal
+* If you want Copilot assistance with errors, position the cursor in the code block where the error occurred and paste the error message
+* Repeat until no errors occur

docs/Common/environmentVariablesFromPrerequisites.md

@@ -0,0 +1,5 @@
+This is a simple prerequisite document that sets a value on a test variable:
+
+```bash
+export ENV_VAR_TEST="Value set in Environment Variables From Prerequisite."
+```