Updating instructions (#41249)

* wording

* wording of mcp server

* this?

* update tox

* stdin issue with tox

* try to do the same for tsp-client

* needs root dir

Author: l0lawrence

.github/copilot-instructions.md

@@ -5,44 +5,102 @@
 - DO check this [website](https://azure.github.io/azure-sdk/python_design.html), and link to pages found there, if possible, when asked about guidelines, or guidance on how to write SDKs. The general guidelines for SDK in this repo are defined there.
 - DO ensure folks have the appropriate setup when working with this repository. Use the verify_setup tool in the azure-sdk-validation server.
 
-When someone asks to run validation on their library, ask them what supported environments they would like to run, such as pylint or mypy. Use the tox tool to run these.
 
 # Generating an SDK From TypeSpec
 
+## Agent Context
+- Check if there are any TypeSpec project paths in the context. If there are, use those paths to locally generate the SDK from the tsp-config.yaml file. If there 
+are no TypeSpec project paths in the context, ask the user for the path to the tsp-config.yaml file. If the user does not have a path, ask them to provide one.
 
+## Prerequisites
+- The user should have a GitHub account and be logged in to GitHub using the GitHub CLI `gh auth login`.
+- The user should have a GitHub Personal Access Token (PAT) with the `repo` scope.
 
-Initialize and validate a TypeSpec client library for Azure SDK for Python. Please:
+## Basic Rules:
+### When running tsp-client commands:
+-  If syncing from a local repo, do not grab a commit hash.
+- Do not manually create directories. The command will create the directories for you.
+- If asked to sync or generate `package-name` we need to find the path to the package's tsp-location.yaml
+ in the azure-sdk-for-python repo and run the command in the same directory.
+- If provided a url to a tspconfig.yaml ensure it has the most recent commit hash of the tspconfig.yaml file
+ instead of a branch name like `main`. If the url does not have a commit hash, use the GitHub API to get the most recent commit hash of the tspconfig.yaml file.
+  If you are unable to do this, ask the user to provide the correct url.
+   `curl -s "https://api.github.com/repos/Azure/azure-rest-api-specs/commits?path=,path to tspconfig.yaml>&per_page=1"`
+- Ensure that node, python, tox, and the required dependencies are installed in your environment (@azure-tools/typespec-client-generator-cli)
 
-1. If the typespec mcp tool is available use that for generating or initializing. If asked to update changes from local spec repo, lets find the path to that local azure-rest-api-specs repo for our tools. Otherwise please follow the instructions below to generate an SDK from TypeSpec.
-   - Ensure that node, python, and the required dependencies are installed in your environment (@azure-tools/typespec-client-generator-cli)
-   - If provided a url to a tspconfig.yaml ensure it has the most recent commit hash of the tspconfig.yaml file instead of a branch name like `main`. If the url does not have a commit hash, use the GitHub API to get the most recent commit hash of the tspconfig.yaml file. If you are unable to do this, ask the user to provide the correct url. `curl -s "https://api.github.com/repos/Azure/azure-rest-api-specs/commits?path=,path to tspconfig.yaml>&per_page=1"`  helpful.
-   - If prompted to initialize the SDK from a url or a local repo use the command `npx @azure-tools/typespec-client-generator-cli init --tsp-config [URL or local azure-rest-api-specs path to tspconfig.yaml]`. The tsp-client init command runs sync and generate under the hood, so generation is complete after the init concludes. If the tspconfig.yaml value is a path to a local file, you can mention that the user will have to populate the values in tsp-location.yaml themselves.
-   - If prompted to update the SDK use the command `npx @azure-tools/typespec-client-generator-cli update`.
-   - If prompted to generate the SDK use the command `npx @azure-tools/typespec-client-generator-cli generate`.
-   - If prompted to sync the SDK use the command `npx @azure-tools/typespec-client-generator-cli sync`.
-   - If prompted to sync with local code use the command `npx @azure-tools/typespec-client-generator-cli sync --local-spec-repo [path to local azure-rest-api-specs repo]`. 
-   - If syncing from a local repo, do not grab a commit hash.
-   - Do not manually create directories. The command will create the directories for you.
-   - If asked to sync or generate `package-name` we need to find the path to the package's tsp-location.yaml in the azure-sdk-for-python repo and run the command in the same directory.
 
-2. After generation is complete, validate the output by:
-   - Installing the newly generated package and its dev_requirements in a .venv and installing tox.
-   - Running pylint validation using tox: `tox -e pylint -c [path to tox.ini] --root .`. Or use the tox mcp tool from the azure-sdk-validation server.
-   - Running mypy type checking using tox: `tox -e mypy -c [path to tox.ini] --root .`. Or use the tox mcp tool from the azure-sdk-validation server.
-   - Running pyright validation using tox: `tox -e pyright -c [path to tox.ini] --root .`. Or use the tox mcp tool from the azure-sdk-validation server.
-   - Running verifytypes validation using tox: `tox -e verifytypes -c [path to tox.ini] --root .`. Or use the tox mcp tool from the azure-sdk-validation server.
-
-3. If any errors or warnings are found, after running all validation checks provide guidance on fixing them following Azure SDK best practices. 
+## Steps to Generate:
 
-4. After the above steps, let's use the GitHub mcp tool to create a pull request with the changes. The pull request should include:
-   - A title that describes the changes made.
-   - A description that includes the following:
-     - A summary of the changes made.
-     - A list of any issues or warnings found during validation and how they were fixed.
-     - Any additional notes or comments about the changes made.
+### Step 1: Validate the correct environment is set up
+- Check if the user has the correct environment set up. If not, guide them to set it up. 
+- Using the `verify_setup` tool in the azure-sdk-validation server is a good way to do this.
 
-Please use Python 3.9 for compatibility, and refer to the Azure SDK design guidelines (https://azure.github.io/azure-sdk/python_design.html) for any implementation decisions.
+### Step 2: Run the correct tsp-client command(s):
+- The typspec-python mcp server tools should be used to run the commands.
+- If any of the commands fail, check the error message and guide the user to fix the issue.
+   - If a command fails due to a TypeSpec error, direct the user back to the TypeSpec to fix the error.
+- If the user is generating a new package, ensure that the package name is valid and follows the naming conventions for Python packages.
 
+### Step 3: Validate the generated SDK and Fix the issues
+   - Installing the newly generated package and its dev_requirements in a .venv and installing tox.
+   - Use the tox mcp tool from the azure-sdk-validation server to run the following validations when possible:
+      - Running pylint validation using tox: `tox -e pylint -c [path to tox.ini] --root .`
+      - Running mypy type checking using tox: `tox -e mypy -c [path to tox.ini] --root .`
+      - Running pyright validation using tox: `tox -e pyright -c [path to tox.ini] --root .`
+      - Running verifytypes validation using tox: `tox -e verifytypes -c [path to tox.ini] --root .`
+   - Fix issues found during validation.
+   - If there are any issues that cannot be fixed, please ask the user to fix them and then come back to proceed with the next step.
+
+### Step 4: Post-Processing of the SDK
+- Create a CHANGELOG.md entry for the changes made. If there is no CHANGELOG.md file, create one in the root directory of the package. If the package version is not correct, update it in _version.py and the CHANGELOG entry.
+- Confirm that the package version in the most recent CHANGELOG entry is correct based on the API spec version and the last released package version. 
+
+The CHANGELOG entry should look like:
+```markdown
+# Release History
+
+## 1.0.0 (YYYY-MM-DD)
+
+### Features Added
+  - Added a new feature to do X.
+
+### Breaking Changes
+   - Changed the way Y is done, which may break existing code that relies on the old behavior.
+
+### Bugs Fixed
+   - Fixed a bug that caused Z to not work as expected.
+
+### Other Changes
+   - Updated the documentation to reflect the new changes.
+   - Refactored the code to improve readability and maintainability.
+```
+
+### Step 5: Commit and Push the Changes
+- Display the list of changed files in the repository and prompt the user to confirm the changes. Ignore uncommitted changes in .github and .vscode folders.
+   - If the user confirms:
+      - Prompt the user to commit the changes:
+         - Run `git add <changed files>` to stage the changes.
+         - Run `git commit -m "<commit message>"` to commit the changes.
+      - Push the changes to the GitHub remote, ensuring the branch name is not "main."
+         - Run `git push -u origin <branch name>` to push the changes.
+         - If the push fails due to authentication, prompt the user to run `gh auth login` and retry the push command.
+         - If the user does not confirm, prompt them to fix the changes and re-run validation.
+
+### Step 6: Manage Pull Requests
+- Check if a pull request exists for the current branch:
+   - If a pull request exists, inform the user and display its details.
+   - If no pull request exists:
+      - Ensure the current branch name is not "main." If it is, prompt the user to create a new branch using `git checkout -b <branch name>`.
+      - Push the changes to the remote branch. If the branch does not exist on GitHub, create it and push the changes.
+      - Generate a title and description for the pull request based on the changes. Prompt the user to confirm or edit them.
+      - Prompt the user to select the target branch for the pull request, defaulting to "main."
+      - Create the pull request in DRAFT mode with the specified project, target branch, title, and description.
+   - Retrieve and display the pull request summary, including its status, checks, and comments. Highlight any action items.
+   - Return the link to the pull request for the user to review.
+
+### Step 7: Finalize the Process
+ - Prompt the user to review the pull request and make any necessary changes.
+ - If the user is satisfied with the pull request guide them to go back to the TypeSpec project and make any necessary changes.
 
 
 # Pylint

.vscode/mcp.json

@@ -29,19 +29,5 @@
                 "main.py"
             ]
         },
-        "github": {
-        "command": "docker",
-        "args": [
-          "run",
-          "-i",
-          "--rm",
-          "-e",
-          "GITHUB_PERSONAL_ACCESS_TOKEN",
-          "ghcr.io/github/github-mcp-server"
-        ],
-        "env": {
-          "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:gh_token}"
-        }
-      }
     }
   }

tools/mcp/typespec-story/main.py

@@ -91,16 +91,35 @@ def run_typespec_cli_command(command: str, args: Dict[str, Any], root_dir: Optio
     logger.info(f"Running command: {' '.join(cli_args)}")
 
     try:
-        # TODO: maybe if we return and dont wait for output this will work
         # Run the command and capture the output
         if root_dir:
-            result = subprocess.run(
-                cli_args,
-                capture_output=True,
-                text=True,
-                cwd=root_dir,
-            )
+            if os.name == "nt":  # Windows
+                result = subprocess.Popen(
+                    cli_args,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    stdin=subprocess.DEVNULL,  # Explicitly close stdin
+                    text=True,
+                    cwd=root_dir,
+                )
+                result.wait()  # Wait for it to complete
+            else:
+                result = subprocess.run(
+                    cli_args,
+                    capture_output=True,
+                    text=True,
+                    cwd=root_dir,
+                )
         else:
+            if os.name == "nt":
+                result = subprocess.Popen(
+                    cli_args,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    stdin=subprocess.DEVNULL,  # Explicitly close stdin
+                    text=True
+                )
+                result.wait()
             result = subprocess.run(
                 cli_args,
                 capture_output=True,
@@ -129,7 +148,7 @@ def run_typespec_cli_command(command: str, args: Dict[str, Any], root_dir: Optio
 # Register tools for each TypeSpec client generator CLI command
 @mcp.tool("init")
 def init_tool(tsp_config_url: str) -> Dict[str, Any]:
-    """Initialize a typespec client library directory given the url.
+    """Initializes and generates a typespec client library directory given the url.
     
     Args:
         tsp_config_url: The URL to the tspconfig.yaml file.
@@ -153,7 +172,11 @@ def init_tool(tsp_config_url: str) -> Dict[str, Any]:
 
 @mcp.tool("init_local")
 def init_local_tool(tsp_config_path: str) -> Dict[str, Any]:
-    """Initialize a typespec client library directory from a local azure-rest-api-specs repo.
+    """Initializes and subsequently generates a typespec client library directory from a local azure-rest-api-specs repo.
+
+    This command is used to generate a client library from a local azure-rest-api-specs repository. No additional
+    commands are needed to generate the client library.
+
 
     Args:
         tsp_config_path: The path to the local tspconfig.yaml file.
@@ -173,7 +196,7 @@ def init_local_tool(tsp_config_path: str) -> Dict[str, Any]:
 
 @mcp.tool("generate")
 def generate_tool(project_dir: Optional[str] = None) -> Dict[str, Any]:
-    """Generate a typespec client library given the url.
+    """Generates a typespec client library given the url.
     
     Args:
         project_dir: The directory of the client library to be generated.
@@ -192,7 +215,7 @@ def generate_tool(project_dir: Optional[str] = None) -> Dict[str, Any]:
 
 @mcp.tool("update")
 def update_tool(project_dir: Optional[str] = None) -> Dict[str, Any]:
-    """Update a typespec client library.
+    """Updates and generates a typespec client library.
     
     This command looks for a tsp-location.yaml file in the current directory to sync a TypeSpec project
     and generate a client library. It calls sync and generate commands internally.
@@ -216,9 +239,9 @@ def update_tool(project_dir: Optional[str] = None) -> Dict[str, Any]:
 @mcp.tool("sync") 
 def sync_tool(project_dir: Optional[str] = None) -> Dict[str, Any]:
     """Sync a typespec client library from the remote repository.
-    
     This command looks for a tsp-location.yaml file to get the project details and sync them to a temporary directory.
-    
+    A generate or update command is then needed to generate the client library.
+
     Args:
         project_dir: The root directory where the client library will be synced.
     
@@ -238,6 +261,9 @@ def sync_tool(project_dir: Optional[str] = None) -> Dict[str, Any]:
 @mcp.tool("sync_local")
 def sync_local_tool(local_spec_repo: str, project_dir: Optional[str] = None) -> Dict[str, Any]:
     """Sync a typespec client library from a local repository.
+
+    This command looks for a tsp-location.yaml file to get the project details and sync them to a temporary directory.
+    A generate or update command is then needed to generate the client library.
     
     Args:
         local_spec_repo: The path to the local azure-rest-api-specs repository.