- "],
+ "files_updated": ["
- "]
+}
+```
+
+> [!NOTE]
+> The cached `last_synced_sha` is an **optimization hint, not a source of truth**. Because a PR opened by this workflow may later be closed or rejected before it merges to `main`, never treat a matching SHA as proof that the mirror is current — Step 1 must independently confirm the checked-out mirror actually matches upstream before taking the no-op path. Advancing the SHA here is acceptable only because that consistency check will re-detect and re-open any update that a rejected PR left unmerged.
+
+## Step 6 — Open a pull request
+
+Create a pull request with your changes using the `create-pull-request` safe output. Use `main` as the base branch for all work related to this workflow. The PR body must include:
+
+1. **What changed upstream** — a concise summary of the commits and file changes found in `github-samples/copilot-workshops` (or, on a first run, a note that this is the initial import of the workshop)
+2. **What was updated locally** — list each mirrored Learning Hub file or asset you created or edited and what changed, including any navigation wiring and any localized pages
+3. **Source links** — links to the relevant upstream files or commits on `main`
+4. A note that the markdown body of this workflow can be edited directly on GitHub.com without recompilation
+
+If there is nothing to change after your analysis, do **not** open a PR. Instead, call the `noop` safe output.
+
+## Guidelines
+
+- The canonical course content lives in `website/src/content/docs/learning-hub/copilot-workshops/` (English) and `website/src/content/docs/
Lovy Jain
kimtth
Akash Dwivedi
Suren K
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fwg-code-alchemist.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fwg-code-alchemist.agent.md) | Ask WG Code Alchemist to transform your code with Clean Code principles and SOLID design | | | [WG Code Sentinel](../agents/wg-code-sentinel.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fwg-code-sentinel.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fwg-code-sentinel.agent.md) | Ask WG Code Sentinel to review your code for security issues. | | | [WinForms Expert](../agents/WinFormsExpert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2FWinFormsExpert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2FWinFormsExpert.agent.md) | Support development of .NET (OOP) WinForms Designer compatible Apps. | | +| [Workshop TA](../agents/workshop-ta.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fworkshop-ta.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fworkshop-ta.agent.md) | Room coordinator for a multi-agent workshop. Sees all desks, routes work, tracks state, manages journals, and emits coordination signals. Not a desk — the person who sees the whole room. | | diff --git a/docs/README.plugins.md b/docs/README.plugins.md index ca23476d..6b6ab1eb 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -40,6 +40,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [cms-development](../plugins/cms-development/README.md) | Skills for CMS development across themes, plugins, admin tooling, media workflows, markdown rendering, and static export pipelines. | 3 items | cms, content-management-system, wordpress, shopify, drupal, theme, plugin, media, static-site | | [context-engineering](../plugins/context-engineering/README.md) | Tools and techniques for maximizing GitHub Copilot effectiveness through better context management. Includes guidelines for structuring code, an agent for planning multi-file changes, and prompts for context-aware development. | 4 items | context, productivity, refactoring, best-practices, architecture | | [context-matic](../plugins/context-matic/README.md) | Coding agents hallucinate APIs. ContextMatic gives them curated, versioned API and SDK docs. Ask your agent to "integrate the payments API" and it guesses — falling back on outdated training data and generic patterns that don't match your actual SDK. ContextMatic solves this by giving the agent deterministic, version-aware, SDK-native context at the exact moment it's needed. | 2 items | api-context, api-integration, mcp, sdk, apimatic, third-party-apis, sdks | +| [convert-to-md](../plugins/convert-to-md/README.md) | A collection of Copilot skills that convert common document formats into Markdown so their contents can be accurately analyzed, summarized, searched, or extracted from. Just tell Copilot what you need — the right skill is invoked automatically and the conversion happens behind the scenes. | 3 items | skills, configuration, copilot, convert-word-to-md, convert-excel-to-md, convert-pdf-to-md | | [copilot-sdk](../plugins/copilot-sdk/README.md) | Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python to help you create AI-powered applications. | 1 items | copilot-sdk, sdk, csharp, go, nodejs, typescript, python, ai, github-copilot | | [csharp-dotnet-development](../plugins/csharp-dotnet-development/README.md) | Essential prompts, instructions, and chat modes for C# and .NET development including testing, documentation, and best practices. | 9 items | csharp, dotnet, aspnet, testing | | [database-data-management](../plugins/database-data-management/README.md) | Database administration, SQL optimization, and data management tools for PostgreSQL, SQL Server, and general database development best practices. | 6 items | database, sql, postgresql, sql-server, dba, optimization, queries, data-management | @@ -92,6 +93,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [swift-mcp-development](../plugins/swift-mcp-development/README.md) | Comprehensive collection for building Model Context Protocol servers in Swift using the official MCP Swift SDK with modern concurrency features. | 2 items | swift, mcp, model-context-protocol, server-development, sdk, ios, macos, concurrency, actor, async-await | | [technical-spike](../plugins/technical-spike/README.md) | Tools for creation, management and research of technical spikes to reduce unknowns and assumptions before proceeding to specification and implementation of solutions. | 2 items | technical-spike, assumption-testing, validation, research | | [testing-automation](../plugins/testing-automation/README.md) | Comprehensive collection for writing tests, test automation, and test-driven development including unit tests, integration tests, and end-to-end testing strategies. | 9 items | testing, tdd, automation, unit-tests, integration, playwright, jest, nunit | +| [the-workshop](../plugins/the-workshop/README.md) | Stop being the switchboard between your AI agents — direct a team. The Workshop puts long-running AI agents (desks) in the same room, on the same work, each with its own memory and history, sharing one workspace so you direct the work instead of relaying it. | 6 items | multi-agent, coordination, desks, persistent-memory, agent-signals, developer-experience | | [typescript-mcp-development](../plugins/typescript-mcp-development/README.md) | Complete toolkit for building Model Context Protocol (MCP) servers in TypeScript/Node.js using the official SDK. Includes instructions for best practices, a prompt for generating servers, and an expert chat mode for guidance. | 2 items | typescript, mcp, model-context-protocol, nodejs, server-development | | [typespec-m365-copilot](../plugins/typespec-m365-copilot/README.md) | Comprehensive collection of prompts, instructions, and resources for building declarative agents and API plugins using TypeSpec for Microsoft 365 Copilot extensibility. | 3 items | typespec, m365-copilot, declarative-agents, api-plugins, agent-development, microsoft-365 | | [visual-pr](../plugins/visual-pr/README.md) | Capture, annotate, and embed screenshots and animated GIF demos in pull request descriptions. Includes Playwright-based UI capture, PIL image annotations, PR embedding workflows for GitHub and Azure DevOps, and screen recording with variable timing. | 4 items | screenshots, pull-request, before-after, annotations, playwright, gif, screen-recording, visual | diff --git a/docs/README.skills.md b/docs/README.skills.md index 0da5f9e5..0780d5e8 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -40,6 +40,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [ai-prompt-engineering-safety-review](../skills/ai-prompt-engineering-safety-review/SKILL.md)
`gh skills install github/awesome-copilot ai-prompt-engineering-safety-review` | Comprehensive AI prompt engineering safety review and improvement prompt. Analyzes prompts for safety, bias, security vulnerabilities, and effectiveness while providing detailed improvement recommendations with extensive frameworks, testing methodologies, and educational content. | None | | [ai-ready](../skills/ai-ready/SKILL.md)
`gh skills install github/awesome-copilot ai-ready` | Make any repo AI-ready — analyzes your codebase and generates AGENTS.md, copilot-instructions.md, CI workflows, issue templates, and more. Mines your PR review patterns and creates files customized to your stack. USE THIS SKILL when the user asks to "make this repo ai-ready", "set up AI config", or "prepare this repo for AI contributions". | None | | [ai-team-orchestration](../skills/ai-team-orchestration/SKILL.md)
`gh skills install github/awesome-copilot ai-team-orchestration` | Bootstrap and run a multi-agent AI development team. Use when: starting a new software project with AI agents, setting up parallel dev/QA teams, creating sprint plans, writing brainstorm prompts with distinct agent voices, recovering a project workflow, or planning sprints. | `references/anti-patterns.md`
`references/brainstorm-format.md`
`references/project-brief-template.md`
`references/sprint-plan-template.md` | +| [anti-ui-slop](../skills/anti-ui-slop/SKILL.md)
`gh skills install github/awesome-copilot anti-ui-slop` | Stop Codex, GitHub Copilot, Claude Code, and Cursor from shipping generic UI. Use UIZZE’s public catalogue of 800,000+ real web and iOS screens to extract product-specific design decisions and enforce a hard finish gate for web and iOS interfaces. | None | | [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md)
`gh skills install github/awesome-copilot appinsights-instrumentation` | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`
`examples`
`references/ASPNETCORE.md`
`references/AUTO.md`
`references/NODEJS.md`
`references/PYTHON.md`
`scripts/appinsights.ps1` | | [apple-appstore-reviewer](../skills/apple-appstore-reviewer/SKILL.md)
`gh skills install github/awesome-copilot apple-appstore-reviewer` | Serves as a reviewer of the codebase with instructions on looking for Apple App Store optimizations or rejection reasons. | None | | [arch-linux-triage](../skills/arch-linux-triage/SKILL.md)
`gh skills install github/awesome-copilot arch-linux-triage` | Triage and resolve Arch Linux issues with pacman, systemd, and rolling-release best practices. | None | @@ -76,6 +77,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [azure-smart-city-iot-solution-builder](../skills/azure-smart-city-iot-solution-builder/SKILL.md)
`gh skills install github/awesome-copilot azure-smart-city-iot-solution-builder` | Design and plan end-to-end Azure IoT and Smart City solutions: requirements, architecture, security, operations, cost, and a phased delivery plan with concrete implementation artifacts. | `references/smart-city-solution-template.md` | | [azure-static-web-apps](../skills/azure-static-web-apps/SKILL.md)
`gh skills install github/awesome-copilot azure-static-web-apps` | Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps. | None | | [batch-files](../skills/batch-files/SKILL.md)
`gh skills install github/awesome-copilot batch-files` | Expert-level Windows batch file (.bat/.cmd) skill for writing, debugging, and maintaining CMD scripts. Use when asked to "create a batch file", "write a .bat script", "automate a Windows task", "CMD scripting", "batch automation", "scheduled task script", "Windows shell script", or when working with .bat/.cmd files in the workspace. Covers cmd.exe syntax, environment variables, control flow, string processing, error handling, and integration with system tools. | `assets/executable.txt`
`assets/library.txt`
`assets/task.txt`
`references/batch-files-and-functions.md`
`references/cygwin.md`
`references/msys2.md`
`references/tools-and-resources.md`
`references/windows-commands.md`
`references/windows-subsystem-on-linux.md` | +| [bench-read](../skills/bench-read/SKILL.md)
`gh skills install github/awesome-copilot bench-read` | Read artifacts from the shared bench — the workspace where desks leave findings, verdicts, and work products for each other and the operator. | None | | [bigquery-pipeline-audit](../skills/bigquery-pipeline-audit/SKILL.md)
`gh skills install github/awesome-copilot bigquery-pipeline-audit` | Audits Python + BigQuery pipelines for cost safety, idempotency, and production readiness. Returns a structured report with exact patch locations. | None | | [boost-prompt](../skills/boost-prompt/SKILL.md)
`gh skills install github/awesome-copilot boost-prompt` | Interactive prompt refinement workflow: interrogates scope, deliverables, constraints; copies final markdown to clipboard; never writes code. Requires the Joyride extension. | None | | [brag-sheet](../skills/brag-sheet/SKILL.md)
`gh skills install github/awesome-copilot brag-sheet` | Turn vague "what did I do?" into evidence-backed impact statements for performance reviews, self-reviews, promotion packets, and weekly updates. Uniquely mines Copilot CLI session logs to reconstruct forgotten work, plus git commits and GitHub PRs. Enforces a 3-part impact contract (action → result → evidence). Works standalone with zero dependencies. Trigger for: "brag", "log work", "what did I do", "backfill my work history", "performance review", "self-review", "self assessment", "write impact statement", "review prep", "promo packet", "promotion case", "weekly update", "status report", "accomplishments", "what did I ship", "I forgot to log my work", "summarize my work", "track my wins", "what should I highlight", "end of half", "career growth", "work journal", or any request to document, summarize, or organize work accomplishments. | None | @@ -91,6 +93,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [cloud-design-patterns](../skills/cloud-design-patterns/SKILL.md)
`gh skills install github/awesome-copilot cloud-design-patterns` | Cloud design patterns for distributed systems architecture covering 42 industry-standard patterns across reliability, performance, messaging, security, and deployment categories. Use when designing, reviewing, or implementing distributed system architectures. | `references/architecture-design.md`
`references/azure-service-mappings.md`
`references/best-practices.md`
`references/deployment-operational.md`
`references/event-driven.md`
`references/messaging-integration.md`
`references/performance.md`
`references/reliability-resilience.md`
`references/security.md` | | [code-exemplars-blueprint-generator](../skills/code-exemplars-blueprint-generator/SKILL.md)
`gh skills install github/awesome-copilot code-exemplars-blueprint-generator` | Technology-agnostic prompt generator that creates customizable AI prompts for scanning codebases and identifying high-quality code exemplars. Supports multiple programming languages (.NET, Java, JavaScript, TypeScript, React, Angular, Python) with configurable analysis depth, categorization methods, and documentation formats to establish coding standards and maintain consistency across development teams. | None | | [code-tour](../skills/code-tour/SKILL.md)
`gh skills install github/awesome-copilot code-tour` | Use this skill to create CodeTour .tour files — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Trigger for: "create a tour", "make a code tour", "generate a tour", "onboarding tour", "tour for this PR", "tour for this bug", "RCA tour", "architecture tour", "explain how X works", "vibe check", "PR review tour", "contributor guide", "help someone ramp up", or any request for a structured walkthrough through code. Supports 20 developer personas (new joiner, bug fixer, architect, PR reviewer, vibecoder, security reviewer, and more), all CodeTour step types (file/line, selection, pattern, uri, commands, view), and tour-level fields (ref, isPrimary, nextTour). Works with any repository in any language. | `references/codetour-schema.json`
`references/examples.md`
`scripts/generate_from_docs.py`
`scripts/validate_tour.py` | +| [codebase-memory-mcp](../skills/codebase-memory-mcp/SKILL.md)
`gh skills install github/awesome-copilot codebase-memory-mcp` | Use when a configured codebase-memory-mcp server can assist with graph-backed code discovery, architecture orientation, symbol lookup, callers and callees, dependency or data-flow tracing, impact analysis, unfamiliar modules, or an explicit Codebase Memory request. | None | | [codeql](../skills/codeql/SKILL.md)
`gh skills install github/awesome-copilot codeql` | Comprehensive guide for setting up and configuring CodeQL code scanning via GitHub Actions workflows and the CodeQL CLI. This skill should be used when users need help with code scanning configuration, CodeQL workflow files, CodeQL CLI commands, SARIF output, security analysis setup, or troubleshooting CodeQL analysis. | `references/alert-management.md`
`references/cli-commands.md`
`references/compiled-languages.md`
`references/sarif-output.md`
`references/troubleshooting.md`
`references/workflow-configuration.md` | | [comment-code-generate-a-tutorial](../skills/comment-code-generate-a-tutorial/SKILL.md)
`gh skills install github/awesome-copilot comment-code-generate-a-tutorial` | Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial. | None | | [commit-message-storyteller](../skills/commit-message-storyteller/SKILL.md)
`gh skills install github/awesome-copilot commit-message-storyteller` | Analyzes git diffs or staged changes and generates narrative commit messages that explain WHY a change was made, not just what changed — following Conventional Commits format. Use when asked to "write a commit message", "generate a commit", "describe my changes", "what should I commit this as", "commit this", "summarize my diff", or "help me commit". Works with git diff output, staged files, or plain descriptions of changes. | `references/conventional-commits-guide.md` | @@ -100,7 +103,10 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [context-map](../skills/context-map/SKILL.md)
`gh skills install github/awesome-copilot context-map` | Generate a map of all files relevant to a task before making changes | None | | [conventional-branch](../skills/conventional-branch/SKILL.md)
`gh skills install github/awesome-copilot conventional-branch` | Create Git branches following the Conventional Branch specification (feature/, bugfix/, hotfix/, release/, chore/). Use when creating a new branch, naming a branch, or checking whether a branch name complies with the spec. | None | | [conventional-commit](../skills/conventional-commit/SKILL.md)
`gh skills install github/awesome-copilot conventional-commit` | Prompt and workflow for generating conventional commit messages using a structured XML format. Guides users to create standardized, descriptive commit messages in line with the Conventional Commits specification, including instructions, examples, and validation. | None | +| [convert-excel-to-md](../skills/convert-excel-to-md/SKILL.md)
`gh skills install github/awesome-copilot convert-excel-to-md` | Converts Excel (.xlsx) workbooks into Markdown so their contents can be accurately analyzed, summarized, searched, or extracted from. Use this skill whenever the user shares, references, or asks about a .xlsx file — even if they don't say "convert" or "markdown" explicitly. This includes requests to "read", "summarize", "review", "extract data from", "compare", "chart", or "analyze" a spreadsheet, workbook, budget, data export, or tracker. Always run the bundled conversion script to produce Markdown first; do not attempt to parse .xlsx content directly or write ad-hoc extraction code. Also use this skill for batch requests involving a whole folder of Excel workbooks. IMPORTANT: When the user references a folder or set of documents containing multiple file types (.pdf, .docx, .xlsx), invoke ALL three sibling skills — convert-pdf-to-md, convert-word-to-md, and convert-excel-to-md — so no file type is silently skipped. | `references/setup.md`
`scripts/convert_excel_to_md.py`
`scripts/requirements.txt` | +| [convert-pdf-to-md](../skills/convert-pdf-to-md/SKILL.md)
`gh skills install github/awesome-copilot convert-pdf-to-md` | Converts PDF (.pdf) documents into Markdown so their contents can be accurately analyzed, summarized, searched, or extracted from. Use this skill whenever the user shares, references, or asks about a .pdf file — even if they don't say "convert" or "markdown" explicitly. This includes requests to "read", "summarize", "review", "extract data from", "compare", or "analyze" a PDF report, paper, invoice, form, contract, or scanned document. Always run the bundled conversion script to produce Markdown first; do not attempt to parse PDF content directly or write ad-hoc extraction code. Also use this skill for batch requests involving a whole folder of PDF documents. IMPORTANT: When the user references a folder or set of documents containing multiple file types (.pdf, .docx, .xlsx), invoke ALL three sibling skills — convert-pdf-to-md, convert-word-to-md, and convert-excel-to-md — so no file type is silently skipped. | `references/setup.md`
`scripts/convert_pdf_to_md.py`
`scripts/requirements.txt` | | [convert-plaintext-to-md](../skills/convert-plaintext-to-md/SKILL.md)
`gh skills install github/awesome-copilot convert-plaintext-to-md` | Convert a text-based document to markdown following instructions from prompt, or if a documented option is passed, follow the instructions for that option. | None | +| [convert-word-to-md](../skills/convert-word-to-md/SKILL.md)
`gh skills install github/awesome-copilot convert-word-to-md` | Converts Word (.docx) documents into Markdown so their contents can be accurately analyzed, summarized, searched, or extracted from. Use this skill whenever the user shares, references, or asks about a .docx file — even if they don't say "convert" or "markdown" explicitly. This includes requests to "read", "summarize", "review", "extract data from", "compare", or "analyze" a Word document, resume, report, contract, or proposal. Always run the bundled conversion script to produce Markdown first; do not attempt to parse .docx content directly or write ad-hoc conversion code. Also use this skill for batch requests involving a whole folder of Word documents. IMPORTANT: When the user references a folder or set of documents containing multiple file types (.pdf, .docx, .xlsx), invoke ALL three sibling skills — convert-pdf-to-md, convert-word-to-md, and convert-excel-to-md — so no file type is silently skipped. | `references/setup.md`
`scripts/convert_word_to_md.py`
`scripts/requirements.txt` | | [copilot-cli-quickstart](../skills/copilot-cli-quickstart/SKILL.md)
`gh skills install github/awesome-copilot copilot-cli-quickstart` | Use this skill when someone wants to learn GitHub Copilot CLI from scratch. Offers interactive step-by-step tutorials with separate Developer and Non-Developer tracks, plus on-demand Q&A. Just say "start tutorial" or ask a question! Note: This skill targets GitHub Copilot CLI specifically and uses CLI-specific tools (ask_user, sql, fetch_copilot_cli_documentation). | None | | [copilot-instructions-blueprint-generator](../skills/copilot-instructions-blueprint-generator/SKILL.md)
`gh skills install github/awesome-copilot copilot-instructions-blueprint-generator` | Technology-agnostic blueprint generator for creating comprehensive copilot-instructions.md files that guide GitHub Copilot to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions. | None | | [copilot-pr-autopilot](../skills/copilot-pr-autopilot/SKILL.md)
`gh skills install github/awesome-copilot copilot-pr-autopilot` | Copilot left 14 review comments on your PR — half are nits. Hours of fix → reply → resolve → re-request, and each round lands MORE comments. This skill runs loop engineering: auto-triggers Copilot Code Review via GraphQL (no @copilot mention), triages every open thread (Copilot, humans, advanced-security) with a fix / decline / escalate rubric, dispatches parallel fix sub-agents that obey the repo build/test/lint conventions, commits per iteration, replies+resolves citing the pushed SHA, then re-triggers until HEAD is reviewed with zero threads awaiting the agent's reply (remaining open threads are explicit hand-offs to the human — escalated declines, design tradeoffs). You merge a clean PR; the bot runs it. Trigger phrases: "address copilot comments", "run a copilot review loop", "fix this PR", "iterate on copilot feedback". Repo-agnostic, gh CLI + PowerShell. Full autopilot needs repo Triage/Write; external PR authors get single-iteration mode plus manual re-trigger (UI 🔄 or substantive-commit push). | `references/01-request-review.md`
`references/02-wait.md`
`references/03-list-threads.md`
`references/04-triage.md`
`references/05-fix.md`
`references/06-build-test.md`
`references/07-commit-push.md`
`references/08-reply-resolve.md`
`references/09-convergence.md`
`references/10-cleanup.md`
`references/api-quirks.md`
`references/orchestration.md`
`scripts/01-request-review.ps1`
`scripts/02-check-review-status.ps1`
`scripts/03-list-open-threads.ps1`
`scripts/08-reply-and-resolve.ps1`
`scripts/09-review-round.ps1`
`scripts/10-cleanup-outdated.ps1`
`scripts/_lib.ps1`
`templates` | @@ -141,6 +147,8 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [debian-linux-triage](../skills/debian-linux-triage/SKILL.md)
`gh skills install github/awesome-copilot debian-linux-triage` | Triage and resolve Debian Linux issues with apt, systemd, and AppArmor-aware guidance. | None | | [declarative-agents](../skills/declarative-agents/SKILL.md)
`gh skills install github/awesome-copilot declarative-agents` | Complete development kit for Microsoft 365 Copilot declarative agents with three comprehensive workflows (basic, advanced, validation), TypeSpec support, and Microsoft 365 Agents Toolkit integration | None | | [dependabot](../skills/dependabot/SKILL.md)
`gh skills install github/awesome-copilot dependabot` | Comprehensive guide for configuring and managing GitHub Dependabot. Use this skill when users ask about creating or optimizing dependabot.yml files, managing Dependabot pull requests, configuring dependency update strategies, setting up grouped updates, monorepo patterns, multi-ecosystem groups, security update configuration, auto-triage rules, or any GitHub Advanced Security (GHAS) supply chain security topic related to Dependabot. For pre-commit dependency vulnerability scanning in AI coding agents via the GitHub MCP Server, this skill references the Advanced Security plugin (`advanced-security@copilot-plugins`). Use this skill when an agent needs to scan dependencies for known vulnerabilities before committing. | `references/dependabot-yml-reference.md`
`references/example-configs.md`
`references/pr-commands.md` | +| [desk-journal](../skills/desk-journal/SKILL.md)
`gh skills install github/awesome-copilot desk-journal` | Write, append, or read desk journal entries. The journal is persistent memory — what survives session boundaries. A good entry has: what was done, current state, next step. | None | +| [desk-open](../skills/desk-open/SKILL.md)
`gh skills install github/awesome-copilot desk-open` | Create and open a new desk in the workshop. Sets up the folder structure, initial journal, and desk identity so the next session that sits down finds the trail. | None | | [devops-rollout-plan](../skills/devops-rollout-plan/SKILL.md)
`gh skills install github/awesome-copilot devops-rollout-plan` | Generate comprehensive rollout plans with preflight checks, step-by-step deployment, verification signals, rollback procedures, and communication plans for infrastructure and application changes | None | | [diagnose](../skills/diagnose/SKILL.md)
`gh skills install github/awesome-copilot diagnose` | Perform a systematic diagnostic scan of an AI workflow across 5 quality dimensions — prompt quality, context efficiency, tool health, architecture fitness, and safety — producing a scored report with prioritized remediation actions. | None | | [doc-and-modernize](../skills/doc-and-modernize/SKILL.md)
`gh skills install github/awesome-copilot doc-and-modernize` | Two related workflows for a locally-cloned codebase, in one skill. Documentation mode produces a single, comprehensive, verifiable architecture document primarily by reading files on disk (local-first) — use it whenever the user wants to understand, map, document, research, or onboard onto a codebase ("research this repo", "write up the architecture", "do an architecture deep dive", "document how this codebase works", "map the system design", "create an onboarding doc"). Modernization mode generates a phased plan to modernize, migrate, upgrade, or rewrite a legacy system ("modernize this", "plan the migration", "how would we rewrite this", "how do we get off this legacy stack"); if no architecture document exists yet it first runs Documentation mode, then continues straight through to the plan. It assumes the legacy stack may be dead, runs a time-boxed feasibility spike, and picks the highest achievable rung on a safety ladder instead of demanding a fully-green legacy CI gate up front. | `references/copilot-instructions.template.md`
`references/migration-hazards.md` | @@ -234,6 +242,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [lsp-setup](../skills/lsp-setup/SKILL.md)
`gh skills install github/awesome-copilot lsp-setup` | Enable code intelligence (go-to-definition, find-references, hover, type info) for any programming language by installing and configuring an LSP server for Copilot CLI. Detects the OS, installs the right server, and generates the JSON configuration (user-level or repo-level). Use when you need deeper code understanding and no LSP server is configured, or when the user asks to set up, install, or configure an LSP server. | `references/lsp-servers.md` | | [make-repo-contribution](../skills/make-repo-contribution/SKILL.md)
`gh skills install github/awesome-copilot make-repo-contribution` | All changes to code must follow the guidance documented in the repository. Before any issue is filed, branch is made, commits generated, or pull request (or PR) created, a search must be done to ensure the right steps are followed. Whenever asked to create an issue, commit messages, to push code, or create a PR, use this skill so everything is done correctly. | `assets/issue-template.md`
`assets/pr-template.md` | | [markdown-to-html](../skills/markdown-to-html/SKILL.md)
`gh skills install github/awesome-copilot markdown-to-html` | Convert Markdown files to HTML similar to `marked.js`, `pandoc`, `gomarkdown/markdown`, or similar tools; or writing custom script to convert markdown to html and/or working on web template systems like `jekyll/jekyll`, `gohugoio/hugo`, or similar web templating systems that utilize markdown documents, converting them to html. Use when asked to "convert markdown to html", "transform md to html", "render markdown", "generate html from markdown", or when working with .md files and/or web a templating system that converts markdown to HTML output. Supports CLI and Node.js workflows with GFM, CommonMark, and standard Markdown flavors. | `references/basic-markdown-to-html.md`
`references/basic-markdown.md`
`references/code-blocks-to-html.md`
`references/code-blocks.md`
`references/collapsed-sections-to-html.md`
`references/collapsed-sections.md`
`references/gomarkdown.md`
`references/hugo.md`
`references/jekyll.md`
`references/marked.md`
`references/pandoc.md`
`references/tables-to-html.md`
`references/tables.md`
`references/writing-mathematical-expressions-to-html.md`
`references/writing-mathematical-expressions.md` | +| [markstream-install](../skills/markstream-install/SKILL.md)
`gh skills install github/awesome-copilot markstream-install` | Install and configure Markstream streaming Markdown renderers for Vue, React, Svelte, Angular, Nuxt, and Vue 2 applications. Use for package selection, minimal peer dependencies, CSS order, SSR boundaries, streaming mode, and renderer setup. | `references/scenarios.md` | | [mcp-cli](../skills/mcp-cli/SKILL.md)
`gh skills install github/awesome-copilot mcp-cli` | Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line. | None | | [mcp-copilot-studio-server-generator](../skills/mcp-copilot-studio-server-generator/SKILL.md)
`gh skills install github/awesome-copilot mcp-copilot-studio-server-generator` | Generate a complete MCP server implementation optimized for Copilot Studio integration with proper schema constraints and streamable HTTP support | None | | [mcp-create-adaptive-cards](../skills/mcp-create-adaptive-cards/SKILL.md)
`gh skills install github/awesome-copilot mcp-create-adaptive-cards` | Skill converted from mcp-create-adaptive-cards.prompt.md | None | @@ -354,6 +363,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [semantic-kernel](../skills/semantic-kernel/SKILL.md)
`gh skills install github/awesome-copilot semantic-kernel` | Create, update, refactor, explain, or review Semantic Kernel solutions using shared guidance plus language-specific references for .NET and Python. | `references/dotnet.md`
`references/python.md` | | [setup-my-iq](../skills/setup-my-iq/SKILL.md)
`gh skills install github/awesome-copilot setup-my-iq` | Create, set up, or update the personal context portfolio: structured markdown files describing
who you are, how you work, your teams, and your tool/ADO configuration. Runs the interview
workflow for first-time setup and targeted edits for updates.
Trigger this skill when the user asks to: set up their context, create or update their context
portfolio, "create my IQ", "set up my IQ", edit their profile, add/remove a stakeholder,
update ADO config, change team info, update pillars, or set up any plugin configuration.
Trigger when another skill fails to find context (missing files or TODO markers) and needs
context populated. Also trigger when the user mentions a context change in passing
(e.g., "my manager changed", "we added someone to the team") to offer a context file update.
Do NOT trigger for read-only questions like "who's on my team?" or "what's my ADO config?".
Those are answered directly from the context files referenced in the loaded custom
instructions; no skill is needed. | `assets/templates` | | [shuffle-json-data](../skills/shuffle-json-data/SKILL.md)
`gh skills install github/awesome-copilot shuffle-json-data` | Shuffle repetitive JSON objects safely by validating schema consistency before randomising entries. | None | +| [signal-write](../skills/signal-write/SKILL.md)
`gh skills install github/awesome-copilot signal-write` | Emit structured agent signals — hands-up, blocked, done, checkpoint, partnership. Signals are written as JSON to .signals/ for dashboard consumption and noted in the journal for persistence. | None | | [slang-shader-engineer](../skills/slang-shader-engineer/SKILL.md)
`gh skills install github/awesome-copilot slang-shader-engineer` | Use when working with Slang shaders, shader modules, HLSL-compatible GPU code, graphics pipelines, compute shaders, tessellation, ray tracing, parameter blocks, generics, interfaces, capabilities, cross-compilation, shader optimization, shader review, or C++ engine integration for Slang. Trigger on any mention of Slang, .slang files, slangc, SPIR-V from Slang, Slang modules, [shader("compute")], [shader("vertex")], or requests to write/review/refactor shader code with modern language features. Also trigger for Slang-to-HLSL/GLSL/Metal/CUDA cross-compile questions, or when the user says "shader" alongside "generics", "interfaces", "parameter blocks", "autodiff", or "capabilities". | `references/language-reference.md`
`references/rules-and-patterns.md`
`references/slang-documentation-full.md` | | [snowflake-semanticview](../skills/snowflake-semanticview/SKILL.md)
`gh skills install github/awesome-copilot snowflake-semanticview` | Create, alter, and validate Snowflake semantic views using Snowflake CLI (snow). Use when asked to build or troubleshoot semantic views/semantic layer definitions with CREATE/ALTER SEMANTIC VIEW, to validate semantic-view DDL against Snowflake via CLI, or to guide Snowflake CLI installation and connection setup. | None | | [sponsor-finder](../skills/sponsor-finder/SKILL.md)
`gh skills install github/awesome-copilot sponsor-finder` | Find which of a GitHub repository's dependencies are sponsorable via GitHub Sponsors. Uses deps.dev API for dependency resolution across npm, PyPI, Cargo, Go, RubyGems, Maven, and NuGet. Checks npm funding metadata, FUNDING.yml files, and web search. Verifies every link. Shows direct and transitive dependencies with OSSF Scorecard health data. Invoke with /sponsor followed by a GitHub owner/repo (e.g. "/sponsor expressjs/express"). | None | @@ -399,5 +409,6 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [winmd-api-search](../skills/winmd-api-search/SKILL.md)
`gh skills install github/awesome-copilot winmd-api-search` | Find and explore Windows desktop APIs. Use when building features that need platform capabilities — camera, file access, notifications, UI controls, AI/ML, sensors, networking, etc. Discovers the right API for a task and retrieves full type details (methods, properties, events, enumeration values). | `LICENSE.txt`
`scripts/Invoke-WinMdQuery.ps1`
`scripts/Update-WinMdCache.ps1`
`scripts/cache-generator` | | [winui3-migration-guide](../skills/winui3-migration-guide/SKILL.md)
`gh skills install github/awesome-copilot winui3-migration-guide` | UWP-to-WinUI 3 migration reference. Maps legacy UWP APIs to correct Windows App SDK equivalents with before/after code snippets. Covers namespace changes, threading (CoreDispatcher to DispatcherQueue), windowing (CoreWindow to AppWindow), dialogs, pickers, sharing, printing, background tasks, and the most common Copilot code generation mistakes. | None | | [workiq-copilot](../skills/workiq-copilot/SKILL.md)
`gh skills install github/awesome-copilot workiq-copilot` | Guides the Copilot CLI on how to use the WorkIQ CLI/MCP server to query Microsoft 365 Copilot data (emails, meetings, docs, Teams, people) for live context, summaries, and recommendations. | None | +| [workshop-create](../skills/workshop-create/SKILL.md)
`gh skills install github/awesome-copilot workshop-create` | Create a new workshop or use an existing directory as one. Handles two paths: (A) use an existing local directory the operator points at, or (B) create a new private GitHub repo in the signed-in account. Never creates a repo inside another repo. | None | | [write-coding-standards-from-file](../skills/write-coding-standards-from-file/SKILL.md)
`gh skills install github/awesome-copilot write-coding-standards-from-file` | Write a coding standards document for a project using the coding styles from the file(s) and/or folder(s) passed as arguments in the prompt. | None | | [x-twitter-scraper](../skills/x-twitter-scraper/SKILL.md)
`gh skills install github/awesome-copilot x-twitter-scraper` | Build GitHub Copilot workflows with Xquik X API SDKs, REST endpoints, MCP tools, TweetClaw OpenClaw plugin installs, signed webhooks, tweet search, user lookup, follower exports, media actions, and agent automation. | None | diff --git a/eng/clean-materialized-plugins.mjs b/eng/clean-materialized-plugins.mjs index 9379d78a..6b034276 100644 --- a/eng/clean-materialized-plugins.mjs +++ b/eng/clean-materialized-plugins.mjs @@ -6,6 +6,7 @@ import { fileURLToPath } from "url"; import { ROOT_FOLDER } from "./constants.mjs"; const PLUGINS_DIR = path.join(ROOT_FOLDER, "plugins"); +const EXTENSIONS_DIR = path.join(ROOT_FOLDER, "extensions"); const MATERIALIZED_SPECS = { agents: { path: "agents", @@ -27,6 +28,41 @@ const MATERIALIZED_SPECS = { }, }; +function copyDirRecursive(src, dest) { + fs.mkdirSync(dest, { recursive: true }); + for (const entry of fs.readdirSync(src, { withFileTypes: true })) { + const srcPath = path.join(src, entry.name); + const destPath = path.join(dest, entry.name); + if (entry.isDirectory()) { + copyDirRecursive(srcPath, destPath); + } else { + fs.copyFileSync(srcPath, destPath); + } + } +} + +function moveEntry(srcPath, destPath) { + fs.mkdirSync(path.dirname(destPath), { recursive: true }); + try { + fs.renameSync(srcPath, destPath); + return; + } catch (error) { + if (!["EXDEV", "EEXIST", "ENOTEMPTY", "EPERM"].includes(error?.code)) { + throw error; + } + } + + const stats = fs.statSync(srcPath); + if (stats.isDirectory()) { + copyDirRecursive(srcPath, destPath); + fs.rmSync(srcPath, { recursive: true, force: true }); + return; + } + + fs.copyFileSync(srcPath, destPath); + fs.rmSync(srcPath, { force: true }); +} + export function restoreManifestFromMaterializedFiles(pluginPath) { const pluginJsonPath = path.join(pluginPath, ".github/plugin", "plugin.json"); if (!fs.existsSync(pluginJsonPath)) { @@ -89,6 +125,68 @@ function cleanPlugin(pluginPath) { return { removed, manifestUpdated }; } +export function cleanMaterializedExtensionPlugin(extensionPath) { + const pluginJsonPath = path.join(extensionPath, ".github", "plugin", "plugin.json"); + let manifestUpdated = false; + if (fs.existsSync(pluginJsonPath)) { + const plugin = JSON.parse(fs.readFileSync(pluginJsonPath, "utf8")); + const extensionBundlePrefix = `extensions/${path.basename(extensionPath)}/`; + if (plugin.extensions === "extensions") { + plugin.extensions = "."; + manifestUpdated = true; + } + if (typeof plugin.logo === "string" && plugin.logo.startsWith(extensionBundlePrefix)) { + plugin.logo = plugin.logo.slice(extensionBundlePrefix.length); + manifestUpdated = true; + } + if (manifestUpdated) { + fs.writeFileSync(pluginJsonPath, JSON.stringify(plugin, null, 2) + "\n", "utf8"); + console.log(` Updated ${path.basename(extensionPath)}/.github/plugin/plugin.json`); + } + } + + const target = path.join(extensionPath, "extensions"); + if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) { + return { removed: 0, manifestUpdated }; + } + + const bundleRoot = path.join(target, path.basename(extensionPath)); + const count = countFiles(target); + if (fs.existsSync(bundleRoot) && fs.statSync(bundleRoot).isDirectory()) { + for (const entry of fs.readdirSync(bundleRoot, { withFileTypes: true })) { + moveEntry(path.join(bundleRoot, entry.name), path.join(extensionPath, entry.name)); + } + console.log(` Restored ${path.basename(extensionPath)}/ from materialized extensions bundle`); + } + + fs.rmSync(target, { recursive: true, force: true }); + console.log(` Removed ${path.basename(extensionPath)}/extensions/ (${count} files)`); + return { removed: count, manifestUpdated }; +} + +function isExtensionPluginDirectory(extensionPath) { + if (fs.existsSync(path.join(extensionPath, "extension.mjs"))) { + return true; + } + + const bundleEntry = path.join(extensionPath, "extensions", path.basename(extensionPath), "extension.mjs"); + if (fs.existsSync(bundleEntry)) { + return true; + } + + const pluginJsonPath = path.join(extensionPath, ".github", "plugin", "plugin.json"); + if (!fs.existsSync(pluginJsonPath)) { + return false; + } + + try { + const plugin = JSON.parse(fs.readFileSync(pluginJsonPath, "utf8")); + return plugin.extensions === "extensions"; + } catch { + return false; + } +} + function countFiles(dir) { let count = 0; for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { @@ -171,6 +269,25 @@ function main() { } } + if (fs.existsSync(EXTENSIONS_DIR)) { + const extensionDirs = fs.readdirSync(EXTENSIONS_DIR, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name) + .sort(); + + for (const dirName of extensionDirs) { + const extensionPath = path.join(EXTENSIONS_DIR, dirName); + if (!isExtensionPluginDirectory(extensionPath)) { + continue; + } + const { removed, manifestUpdated } = cleanMaterializedExtensionPlugin(extensionPath); + total += removed; + if (manifestUpdated) { + manifestsUpdated++; + } + } + } + console.log(); if (total === 0 && manifestsUpdated === 0) { console.log("✅ No materialized files found. Plugins are already clean."); diff --git a/eng/external-plugin-intake-state.mjs b/eng/external-plugin-intake-state.mjs index f9351281..b73c7216 100644 --- a/eng/external-plugin-intake-state.mjs +++ b/eng/external-plugin-intake-state.mjs @@ -3,6 +3,10 @@ export const EXTERNAL_PLUGIN_INTAKE_LABELS = Object.freeze({ color: "FEF2C0", description: "Public external plugin submission", }, + "external-plugin-canvas": { + color: "1D76DB", + description: "External plugin submission includes a canvas extension", + }, "awaiting-review": { color: "FBCA04", description: "Submission is waiting for automated intake validation", @@ -27,6 +31,7 @@ export const EXTERNAL_PLUGIN_INTAKE_LABELS = Object.freeze({ const EXTERNAL_PLUGIN_INTAKE_SYNC_LABELS = Object.freeze([ "external-plugin", + "external-plugin-canvas", "awaiting-review", "ready-for-review", "requires-submitter-fixes", @@ -129,6 +134,9 @@ export async function applyExternalPluginIntakeEvaluation({ rejected: new Set(["external-plugin", "rejected"]), }; const desiredLabels = desiredLabelsByState[state] ?? desiredLabelsByState.rejected; + if (evaluation.isCanvasPlugin) { + desiredLabels.add("external-plugin-canvas"); + } await syncExternalPluginIntakeLabels({ github, diff --git a/eng/external-plugin-intake.mjs b/eng/external-plugin-intake.mjs index b7ddd2d6..fa9696e1 100644 --- a/eng/external-plugin-intake.mjs +++ b/eng/external-plugin-intake.mjs @@ -54,6 +54,13 @@ const FIELD_TITLES = Object.freeze({ const LEGACY_FIELD_TITLES = Object.freeze({ immutableRef: "Immutable ref to review", }); +const EXTERNAL_CANVAS_KEYWORD = "canvas"; +const EXTERNAL_CANVAS_PREVIEW_PATH = "assets/preview.png"; +const EXTERNAL_PLUGIN_ROOT_MANIFEST_PATHS = Object.freeze([ + ".github/plugin/plugin.json", + ".plugin/plugin.json", + "plugin.json", +]); function normalizeMultilineText(value) { return String(value ?? "").replace(/\r\n/g, "\n"); @@ -116,6 +123,29 @@ function parseKeywords(value) { return keywords.length > 0 ? keywords : undefined; } +function hasCanvasKeyword(plugin) { + return (plugin?.keywords ?? []).some( + (keyword) => String(keyword).trim().toLowerCase() === EXTERNAL_CANVAS_KEYWORD, + ); +} + +function normalizeRepoRelativePath(value) { + const normalized = stripNoResponse(value); + if (!normalized || normalized === "/") { + return ""; + } + + return normalized.replace(/\\/g, "/").replace(/^\/+|\/+$/g, ""); +} + +function joinRepoPath(...segments) { + return segments + .map((segment) => String(segment ?? "").trim()) + .filter(Boolean) + .join("/") + .replace(/\/+/g, "/"); +} + function parseChecklist(value) { const checked = new Set(); const normalized = normalizeMultilineText(value); @@ -231,6 +261,33 @@ async function fetchGitHubJson(apiPath, token) { } } +function encodeRepoContentPath(value) { + return String(value) + .split("/") + .filter((segment) => segment.length > 0) + .map((segment) => encodeURIComponent(segment)) + .join("/"); +} + +async function fetchGitHubFile(repo, filePath, ref, token) { + const encodedRepo = encodeRepoPath(repo); + const encodedPath = encodeRepoContentPath(filePath); + return fetchGitHubJson( + `/repos/${encodedRepo}/contents/${encodedPath}?ref=${encodeURIComponent(ref)}`, + token, + ); +} + +function decodeGitHubFileContent(fileResponse) { + const encodedContent = fileResponse?.data?.content; + if (!encodedContent || typeof encodedContent !== "string") { + return null; + } + + const normalized = encodedContent.replace(/\n/g, ""); + return Buffer.from(normalized, "base64").toString("utf8"); +} + function encodeRepoPath(repo) { const [owner, name] = String(repo).split("/"); return `${encodeURIComponent(owner ?? "")}/${encodeURIComponent(name ?? "")}`; @@ -273,6 +330,7 @@ async function validateRemoteRepository(repo, { ref, sha }, errors, warnings, to ); } } + } if (!ref) { @@ -322,6 +380,151 @@ async function validateRemoteRepository(repo, { ref, sha }, errors, warnings, to } } +async function validateCanvasPluginMetadata(plugin, errors, warnings, token) { + const repo = plugin?.source?.repo; + const sha = plugin?.source?.sha; + const ref = plugin?.source?.ref; + const releaseLocator = sha || ref; + const releaseLocatorDescription = sha ? `commit "${sha}"` : `ref "${ref}"`; + const pluginRoot = normalizeRepoRelativePath(plugin?.source?.path); + + if (!releaseLocator) { + errors.push('submission: plugins tagged with "canvas" must provide "Ref to review" and/or "Commit SHA to review"'); + return; + } + + if (!repo) { + return; + } + + let manifest = null; + let manifestPath = null; + let sawManifestApiError = false; + + const manifestCandidates = EXTERNAL_PLUGIN_ROOT_MANIFEST_PATHS.map((relativePath) => + joinRepoPath(pluginRoot, relativePath), + ); + + for (const candidatePath of manifestCandidates) { + const response = await fetchGitHubFile(repo, candidatePath, releaseLocator, token); + if (response.kind === "notFound") { + continue; + } + + if (response.kind === "apiError") { + sawManifestApiError = true; + continue; + } + + if (response.data?.type !== "file") { + continue; + } + + const decoded = decodeGitHubFileContent(response); + if (!decoded) { + errors.push(`submission: could not decode plugin manifest "${candidatePath}" at ${releaseLocatorDescription}`); + return; + } + + try { + manifest = JSON.parse(decoded); + manifestPath = candidatePath; + break; + } catch (error) { + errors.push( + `submission: plugin manifest "${candidatePath}" at ${releaseLocatorDescription} is not valid JSON (${error.message})`, + ); + return; + } + } + + if (!manifest) { + if (sawManifestApiError) { + warnings.push( + `submission: could not verify canvas plugin manifest in GitHub repository "${repo}" at ${releaseLocatorDescription}; a maintainer should re-run intake`, + ); + return; + } + + const expectedPaths = manifestCandidates.map((candidatePath) => `"${candidatePath}"`).join(", "); + errors.push( + `submission: plugins tagged with "canvas" must include a manifest at one of ${expectedPaths} in ${releaseLocatorDescription}`, + ); + return; + } + + if (manifest.logo !== EXTERNAL_CANVAS_PREVIEW_PATH) { + errors.push( + `submission: plugins tagged with "canvas" must set "logo" to "${EXTERNAL_CANVAS_PREVIEW_PATH}" in "${manifestPath}"`, + ); + } + + if (manifest.extenions !== undefined) { + errors.push( + `submission: plugins tagged with "canvas" must use "extensions" (found misspelled key "extenions") in "${manifestPath}"`, + ); + } + + if (manifest.extensions !== undefined && manifest.extensions !== "extensions") { + errors.push( + `submission: plugins tagged with "canvas" may omit "extensions", but if provided it must be "extensions" in "${manifestPath}"`, + ); + } + + const extensionContainerPath = joinRepoPath(pluginRoot, "extensions"); + const extensionContainerResponse = await fetchGitHubFile(repo, extensionContainerPath, releaseLocator, token); + if (extensionContainerResponse.kind === "notFound") { + errors.push( + `submission: plugins tagged with "canvas" must include an "extensions" directory at ${releaseLocatorDescription}`, + ); + } else if (extensionContainerResponse.kind === "apiError") { + warnings.push( + `submission: could not verify "extensions" directory in GitHub repository "${repo}" at ${releaseLocatorDescription}; a maintainer should re-run intake`, + ); + } else if ( + !( + extensionContainerResponse.data?.type === "dir" + || Array.isArray(extensionContainerResponse.data) + ) + ) { + errors.push( + `submission: "extensions" must be a directory in ${releaseLocatorDescription}`, + ); + } + + const extensionEntryPath = joinRepoPath(pluginRoot, "extensions", "extension.mjs"); + const extensionEntryResponse = await fetchGitHubFile(repo, extensionEntryPath, releaseLocator, token); + if (extensionEntryResponse.kind === "notFound") { + errors.push( + `submission: plugins tagged with "canvas" must include "extensions/extension.mjs" at ${releaseLocatorDescription}`, + ); + } else if (extensionEntryResponse.kind === "apiError") { + warnings.push( + `submission: could not verify "extensions/extension.mjs" in GitHub repository "${repo}" at ${releaseLocatorDescription}; a maintainer should re-run intake`, + ); + } else if (extensionEntryResponse.data?.type !== "file") { + errors.push( + `submission: "extensions/extension.mjs" must be a file in ${releaseLocatorDescription}`, + ); + } + + const previewPath = joinRepoPath(pluginRoot, EXTERNAL_CANVAS_PREVIEW_PATH); + const previewResponse = await fetchGitHubFile(repo, previewPath, releaseLocator, token); + if (previewResponse.kind === "notFound") { + errors.push( + `submission: plugins tagged with "canvas" must include "${EXTERNAL_CANVAS_PREVIEW_PATH}" at ${releaseLocatorDescription}`, + ); + } else if (previewResponse.kind === "apiError") { + warnings.push( + `submission: could not verify "${EXTERNAL_CANVAS_PREVIEW_PATH}" in GitHub repository "${repo}" at ${releaseLocatorDescription}; a maintainer should re-run intake`, + ); + } else if (previewResponse.data?.type !== "file") { + errors.push( + `submission: "${EXTERNAL_CANVAS_PREVIEW_PATH}" must be a file in ${releaseLocatorDescription}`, + ); + } +} + export function parseExternalPluginIssueBody(body) { const sections = parseIssueFormSections(body); const errors = []; @@ -425,10 +628,14 @@ function normalizeQualityGateResult(rawResult) { overall_status: "not_run", vally_lint_status: "not_run", smoke_status: "not_run", + version_match_status: "not_run", + canvas_structure_status: "not_run", failure_class: "none", summary: "", vally_lint_output: "", smoke_output: "", + version_match_output: "", + canvas_structure_output: "", }; if (!rawResult || typeof rawResult !== "object" || Array.isArray(rawResult)) { @@ -444,6 +651,8 @@ function normalizeQualityGateResult(rawResult) { function buildQualityGatesCommentSection(qualityResult) { const vallyState = qualityResult.vally_lint_status || "not_run"; const smokeState = qualityResult.smoke_status || "not_run"; + const versionMatchState = qualityResult.version_match_status || "not_run"; + const canvasStructureState = qualityResult.canvas_structure_status || "not_run"; const summaryText = String(qualityResult.summary || "").trim() || "_No quality gate details were provided._"; const sections = [ @@ -453,6 +662,8 @@ function buildQualityGatesCommentSection(qualityResult) { "|---|---|", `| vally lint | ${vallyState} |`, `| install smoke test | ${smokeState} |`, + `| version match | ${versionMatchState} |`, + `| canvas structure | ${canvasStructureState} |`, "", summaryText, ]; @@ -487,6 +698,36 @@ function buildQualityGatesCommentSection(qualityResult) { ); } + const versionMatchOutput = String(qualityResult.version_match_output || "").trim(); + if (versionMatchOutput) { + sections.push( + "", + "
",
+ "
",
+ );
+ }
+
+ const canvasStructureOutput = String(qualityResult.canvas_structure_output || "").trim();
+ if (canvasStructureOutput) {
+ sections.push(
+ "",
+ "Version match output
", + "", + "```text", + versionMatchOutput, + "```", + "", + "",
+ "
",
+ );
+ }
+
return sections.join("\n");
}
@@ -587,6 +828,7 @@ export async function evaluateExternalPluginIssue({ issue, token, runId, owner,
const validationResult = validateExternalPlugin(parsed.plugin, 0, { policy: "publicSubmission" });
errors.push(...validationResult.errors.map(toSubmissionError));
warnings.push(...validationResult.warnings.map(toSubmissionError));
+ const isCanvasPlugin = hasCanvasKeyword(parsed.plugin);
if (parsed.plugin?.name) {
const matchingName = duplicateNames.find(
@@ -601,6 +843,10 @@ export async function evaluateExternalPluginIssue({ issue, token, runId, owner,
await validateRemoteRepository(parsed.plugin.source.repo, parsed.plugin.source, errors, warnings, token);
}
+ if (isCanvasPlugin) {
+ await validateCanvasPluginMetadata(parsed.plugin, errors, warnings, token);
+ }
+
const dedupedErrors = [...new Set(errors)];
const dedupedWarnings = [...new Set(warnings)];
const valid = dedupedErrors.length === 0;
@@ -668,6 +914,7 @@ export async function evaluateExternalPluginIssue({ issue, token, runId, owner,
errors: dedupedErrors,
warnings: dedupedWarnings,
plugin: parsed.plugin,
+ isCanvasPlugin,
commentBody,
commentMarker: marker,
};
diff --git a/eng/external-plugin-pr-quality-gates.mjs b/eng/external-plugin-pr-quality-gates.mjs
index e72928c5..85cd6d9c 100644
--- a/eng/external-plugin-pr-quality-gates.mjs
+++ b/eng/external-plugin-pr-quality-gates.mjs
@@ -86,7 +86,7 @@ export async function runExternalPluginPrQualityGates(plugins) {
? "No changed external plugin entries were detected in plugins/external.json."
: checkedPlugins
.map((entry) =>
- `- ${entry.name}: vally-lint=${entry.quality.vally_lint_status}, install-smoke=${entry.quality.smoke_status}, overall=${entry.quality.overall_status}`
+ `- ${entry.name}: vally-lint=${entry.quality.vally_lint_status}, install-smoke=${entry.quality.smoke_status}, version-match=${entry.quality.version_match_status}, canvas-structure=${entry.quality.canvas_structure_status}, overall=${entry.quality.overall_status}`
)
.join("\n");
diff --git a/eng/external-plugin-quality-gates.mjs b/eng/external-plugin-quality-gates.mjs
index 6b857be0..507cc28f 100644
--- a/eng/external-plugin-quality-gates.mjs
+++ b/eng/external-plugin-quality-gates.mjs
@@ -8,6 +8,7 @@ import { spawnSync } from "child_process";
import { runLint, LintConsoleReporter } from "@microsoft/vally";
const MAX_OUTPUT_LENGTH = 12000;
+const EXTERNAL_CANVAS_KEYWORD = "canvas";
const INFRA_ERROR_PATTERNS = [
/\b401\b/,
@@ -69,6 +70,12 @@ function normalizePluginPath(pluginPath) {
return normalized;
}
+function hasCanvasKeyword(plugin) {
+ return (plugin?.keywords ?? []).some(
+ (keyword) => String(keyword).trim().toLowerCase() === EXTERNAL_CANVAS_KEYWORD,
+ );
+}
+
function resolveFetchSpec(pluginSource) {
if (pluginSource.sha) {
return pluginSource.sha;
@@ -130,7 +137,10 @@ function cloneSubmissionRepository(workDir, plugin) {
throw new Error(`git checkout failed: ${checkout.output}`);
}
- return repoDir;
+ return {
+ repoDir,
+ fetchSpec,
+ };
}
// Ordered list of candidate locations for plugin.json, from most to least specific.
@@ -144,6 +154,13 @@ const PLUGIN_JSON_CANDIDATES = [
["plugin.json"],
];
+function toPosixPath(...segments) {
+ return segments
+ .filter((segment) => segment !== undefined && segment !== null && String(segment).length > 0)
+ .map((segment) => String(segment).replace(/\\/g, "/"))
+ .join("/");
+}
+
function findPluginJson(pluginRoot) {
for (const segments of PLUGIN_JSON_CANDIDATES) {
const candidate = path.join(pluginRoot, ...segments);
@@ -304,8 +321,302 @@ function runInstallSmokeGate(workDir, plugin) {
}
}
-function toOverallStatus(skillStatus, smokeStatus) {
- const states = [skillStatus, smokeStatus];
+function isMissingPathAtLocator(output) {
+ const normalized = String(output ?? "").toLowerCase();
+ return (
+ normalized.includes("does not exist in") ||
+ normalized.includes("exists on disk, but not in") ||
+ (normalized.includes("path '") && normalized.includes("not in"))
+ );
+}
+
+function fetchLocatorIntoRepo(repoDir, locator) {
+ const result = runCommand("git", ["fetch", "--depth=1", "origin", locator], { cwd: repoDir });
+ if (result.exitCode === 0) {
+ return {
+ status: "pass",
+ output: "",
+ };
+ }
+
+ const status = classifySmokeFailure(result.output);
+ return {
+ status,
+ output: `git fetch failed for "${locator}": ${result.output}`,
+ };
+}
+
+function readPluginManifestAtLocator(repoDir, locator, normalizedPluginPath) {
+ const manifestCandidates = PLUGIN_JSON_CANDIDATES.map((segments) =>
+ toPosixPath(normalizedPluginPath, ...segments)
+ );
+
+ for (const manifestPath of manifestCandidates) {
+ const showResult = runCommand("git", ["show", `${locator}:${manifestPath}`], { cwd: repoDir });
+ if (showResult.exitCode === 0) {
+ const rawShow = spawnSync("git", ["show", `${locator}:${manifestPath}`], { cwd: repoDir, encoding: "utf8" });
+ const rawStdout = String(rawShow.stdout ?? "");
+
+ try {
+ return {
+ kind: "found",
+ manifestPath,
+ manifest: JSON.parse(rawStdout),
+ };
+ } catch (error) {
+ return {
+ kind: "invalid",
+ manifestPath,
+ message: `Invalid JSON in "${manifestPath}" at "${locator}": ${error.message}`,
+ };
+ }
+ }
+
+ if (isMissingPathAtLocator(showResult.output)) {
+ continue;
+ }
+
+ return {
+ kind: "infra_error",
+ message: `Unable to read "${manifestPath}" at "${locator}": ${showResult.output}`,
+ };
+ }
+
+ return {
+ kind: "not_found",
+ message: `No plugin.json found at "${locator}". Expected one of: ${manifestCandidates.join(", ")}`,
+ };
+}
+
+function runVersionMatchGate(repoDir, plugin, primaryFetchSpec) {
+ const expectedVersion = String(plugin?.version ?? "").trim();
+ const normalizedPluginPath = normalizePluginPath(plugin?.source?.path || "/");
+ const locators = [plugin?.source?.ref, plugin?.source?.sha]
+ .filter((value) => typeof value === "string" && value.trim().length > 0)
+ .map((value) => value.trim())
+ .filter((value, index, values) => values.indexOf(value) === index);
+
+ if (locators.length === 0) {
+ return {
+ status: "not_run",
+ output: "Version match gate skipped because neither source.ref nor source.sha was provided.",
+ };
+ }
+
+ const messages = [];
+ let hasFailure = false;
+ let hasInfraError = false;
+
+ for (const locator of locators) {
+ if (locator !== primaryFetchSpec) {
+ const fetchResult = fetchLocatorIntoRepo(repoDir, locator);
+ if (fetchResult.status === "fail") {
+ hasFailure = true;
+ messages.push(`- ${locator}: ${fetchResult.output}`);
+ continue;
+ }
+
+ if (fetchResult.status === "infra_error") {
+ hasInfraError = true;
+ messages.push(`- ${locator}: ${fetchResult.output}`);
+ continue;
+ }
+ }
+
+ const manifestResult = readPluginManifestAtLocator(repoDir, locator, normalizedPluginPath);
+ if (manifestResult.kind === "not_found" || manifestResult.kind === "invalid") {
+ hasFailure = true;
+ messages.push(`- ${locator}: ${manifestResult.message}`);
+ continue;
+ }
+
+ if (manifestResult.kind === "infra_error") {
+ hasInfraError = true;
+ messages.push(`- ${locator}: ${manifestResult.message}`);
+ continue;
+ }
+
+ const actualVersion = String(manifestResult.manifest?.version ?? "").trim();
+ if (!actualVersion) {
+ hasFailure = true;
+ messages.push(`- ${locator}: "${manifestResult.manifestPath}" is missing a non-empty "version" field.`);
+ continue;
+ }
+
+ if (actualVersion !== expectedVersion) {
+ hasFailure = true;
+ messages.push(
+ `- ${locator}: external.json version "${expectedVersion}" does not match "${manifestResult.manifestPath}" version "${actualVersion}".`
+ );
+ continue;
+ }
+
+ messages.push(`- ${locator}: matched version "${expectedVersion}" at "${manifestResult.manifestPath}".`);
+ }
+
+ if (hasFailure) {
+ return {
+ status: "fail",
+ output: messages.join("\n"),
+ };
+ }
+
+ if (hasInfraError) {
+ return {
+ status: "infra_error",
+ output: messages.join("\n"),
+ };
+ }
+
+ return {
+ status: "pass",
+ output: messages.join("\n"),
+ };
+}
+
+function checkPathExistsAtLocator(repoDir, locator, repoPath, expectedType) {
+ const result = runCommand("git", ["cat-file", "-e", `${locator}:${repoPath}`], { cwd: repoDir });
+ if (result.exitCode === 0) {
+ if (!expectedType) {
+ return { exists: true, output: "" };
+ }
+
+ const typeResult = runCommand("git", ["cat-file", "-t", `${locator}:${repoPath}`], { cwd: repoDir });
+ if (typeResult.exitCode !== 0) {
+ return {
+ exists: false,
+ output: `Unable to verify path "${repoPath}" type at "${locator}": ${typeResult.output}`,
+ };
+ }
+
+ const actualType = String(typeResult.stdout ?? "").trim();
+ if (actualType !== expectedType) {
+ return {
+ exists: false,
+ output: "",
+ kindMismatch: true,
+ actualType,
+ };
+ }
+
+ return { exists: true, output: "" };
+ }
+
+ const normalizedOutput = String(result.output ?? "").toLowerCase();
+ if (
+ normalizedOutput.includes("not a valid object name")
+ || normalizedOutput.includes("path '")
+ || normalizedOutput.includes("does not exist")
+ ) {
+ return { exists: false, output: "" };
+ }
+
+ return {
+ exists: false,
+ output: `Unable to verify path "${repoPath}" at "${locator}": ${result.output}`,
+ };
+}
+
+export function runCanvasStructureGate(repoDir, plugin, primaryFetchSpec) {
+ if (!hasCanvasKeyword(plugin)) {
+ return {
+ status: "not_run",
+ output: "Canvas structure gate skipped because plugin is not tagged with \"canvas\".",
+ };
+ }
+
+ const normalizedPluginPath = normalizePluginPath(plugin?.source?.path || "/");
+ const locators = [plugin?.source?.ref, plugin?.source?.sha]
+ .filter((value) => typeof value === "string" && value.trim().length > 0)
+ .map((value) => value.trim())
+ .filter((value, index, values) => values.indexOf(value) === index);
+
+ if (locators.length === 0) {
+ return {
+ status: "not_run",
+ output: "Canvas structure gate skipped because neither source.ref nor source.sha was provided.",
+ };
+ }
+
+ const extensionsDir = toPosixPath(normalizedPluginPath, "extensions");
+ const extensionEntryPoint = toPosixPath(extensionsDir, "extension.mjs");
+
+ let hasFailure = false;
+ let hasInfraError = false;
+ const messages = [];
+
+ for (const locator of locators) {
+ if (locator !== primaryFetchSpec) {
+ const fetchResult = fetchLocatorIntoRepo(repoDir, locator);
+ if (fetchResult.status === "fail") {
+ hasFailure = true;
+ messages.push(`- ${locator}: ${fetchResult.output}`);
+ continue;
+ }
+
+ if (fetchResult.status === "infra_error") {
+ hasInfraError = true;
+ messages.push(`- ${locator}: ${fetchResult.output}`);
+ continue;
+ }
+ }
+
+ const extensionDirCheck = checkPathExistsAtLocator(repoDir, locator, extensionsDir, "tree");
+ if (extensionDirCheck.output) {
+ hasInfraError = true;
+ messages.push(`- ${locator}: ${extensionDirCheck.output}`);
+ continue;
+ }
+ if (!extensionDirCheck.exists) {
+ hasFailure = true;
+ if (extensionDirCheck.kindMismatch) {
+ messages.push(`- ${locator}: "${extensionsDir}" must be a directory.`);
+ } else {
+ messages.push(`- ${locator}: missing required canvas extension directory "${extensionsDir}".`);
+ }
+ continue;
+ }
+
+ const extensionEntryCheck = checkPathExistsAtLocator(repoDir, locator, extensionEntryPoint, "blob");
+ if (extensionEntryCheck.output) {
+ hasInfraError = true;
+ messages.push(`- ${locator}: ${extensionEntryCheck.output}`);
+ continue;
+ }
+ if (!extensionEntryCheck.exists) {
+ hasFailure = true;
+ if (extensionEntryCheck.kindMismatch) {
+ messages.push(`- ${locator}: "${extensionEntryPoint}" must be a file.`);
+ } else {
+ messages.push(`- ${locator}: missing required canvas extension entry point "${extensionEntryPoint}".`);
+ }
+ continue;
+ }
+
+ messages.push(`- ${locator}: found "${extensionsDir}" with entry point "${extensionEntryPoint}".`);
+ }
+
+ if (hasInfraError) {
+ return {
+ status: "infra_error",
+ output: messages.join("\n"),
+ };
+ }
+
+ if (hasFailure) {
+ return {
+ status: "fail",
+ output: messages.join("\n"),
+ };
+ }
+
+ return {
+ status: "pass",
+ output: messages.join("\n"),
+ };
+}
+
+function toOverallStatus(states) {
if (states.includes("infra_error")) {
return "infra_error";
}
@@ -334,26 +645,44 @@ export async function runExternalPluginQualityGates(plugin) {
overall_status: "not_run",
vally_lint_status: "not_run",
smoke_status: "not_run",
+ version_match_status: "not_run",
+ canvas_structure_status: "not_run",
failure_class: "none",
summary: "",
vally_lint_output: "",
smoke_output: "",
+ version_match_output: "",
+ canvas_structure_output: "",
};
try {
- const repoDir = cloneSubmissionRepository(workDir, plugin);
+ const { repoDir, fetchSpec } = cloneSubmissionRepository(workDir, plugin);
const normalizedPluginPath = normalizePluginPath(plugin.source?.path || "/");
const pluginRoot = normalizedPluginPath ? path.join(repoDir, normalizedPluginPath) : repoDir;
if (!fs.existsSync(pluginRoot) || !fs.statSync(pluginRoot).isDirectory()) {
result.vally_lint_status = "fail";
result.smoke_status = "fail";
+ result.version_match_status = "fail";
+ result.canvas_structure_status = hasCanvasKeyword(plugin) ? "fail" : "not_run";
result.overall_status = "fail";
result.failure_class = "submitter_fixes";
result.summary = `Plugin path "${plugin.source?.path || "/"}" was not found in the submitted repository snapshot.`;
+ result.version_match_output = result.summary;
+ if (hasCanvasKeyword(plugin)) {
+ result.canvas_structure_output = result.summary;
+ }
return result;
}
+ const versionMatchResult = runVersionMatchGate(repoDir, plugin, fetchSpec);
+ result.version_match_status = versionMatchResult.status;
+ result.version_match_output = versionMatchResult.output;
+
+ const canvasStructureResult = runCanvasStructureGate(repoDir, plugin, fetchSpec);
+ result.canvas_structure_status = canvasStructureResult.status;
+ result.canvas_structure_output = canvasStructureResult.output;
+
const vallyResult = await runVallyLintGate(pluginRoot);
result.vally_lint_status = vallyResult.status;
result.vally_lint_output = vallyResult.output;
@@ -362,11 +691,18 @@ export async function runExternalPluginQualityGates(plugin) {
result.smoke_status = smokeResult.status;
result.smoke_output = smokeResult.output;
- result.overall_status = toOverallStatus(result.vally_lint_status, result.smoke_status);
+ result.overall_status = toOverallStatus([
+ result.vally_lint_status,
+ result.smoke_status,
+ result.version_match_status,
+ result.canvas_structure_status,
+ ]);
result.failure_class = toFailureClass(result.overall_status);
result.summary = [
`- vally lint: ${result.vally_lint_status}`,
`- install smoke test: ${result.smoke_status}`,
+ `- version match: ${result.version_match_status}`,
+ `- canvas structure: ${result.canvas_structure_status}`,
`- overall: ${result.overall_status}`,
].join("\n");
diff --git a/eng/external-plugin-quality-gates.test.mjs b/eng/external-plugin-quality-gates.test.mjs
new file mode 100644
index 00000000..5f619fae
--- /dev/null
+++ b/eng/external-plugin-quality-gates.test.mjs
@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { spawnSync } from "child_process";
+import { after, test } from "node:test";
+import { runCanvasStructureGate } from "./external-plugin-quality-gates.mjs";
+
+const tempDirs = [];
+
+after(() => {
+ for (const dir of tempDirs) {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+function runGit(repoDir, ...args) {
+ const result = spawnSync("git", args, { cwd: repoDir, encoding: "utf8" });
+ if (result.status !== 0) {
+ throw new Error(`git ${args.join(" ")} failed: ${result.stdout}\n${result.stderr}`);
+ }
+ return String(result.stdout ?? "").trim();
+}
+
+function createTempRepo() {
+ const repoDir = fs.mkdtempSync(path.join(os.tmpdir(), "external-plugin-quality-"));
+ tempDirs.push(repoDir);
+
+ runGit(repoDir, "init", "-q");
+ runGit(repoDir, "config", "user.name", "Copilot Test");
+ runGit(repoDir, "config", "user.email", "copilot@example.com");
+ return repoDir;
+}
+
+function commitAll(repoDir, message) {
+ runGit(repoDir, "add", "-A");
+ runGit(repoDir, "commit", "-m", message, "--quiet");
+ return runGit(repoDir, "rev-parse", "HEAD");
+}
+
+test("runCanvasStructureGate passes when extensions/extension.mjs exists", () => {
+ const repoDir = createTempRepo();
+ fs.mkdirSync(path.join(repoDir, "extensions"), { recursive: true });
+ fs.writeFileSync(path.join(repoDir, "extensions", "extension.mjs"), "export default {};\n");
+ const sha = commitAll(repoDir, "Add canvas extension container");
+
+ const plugin = {
+ name: "canvas-plugin",
+ keywords: ["canvas"],
+ source: {
+ source: "github",
+ repo: "owner/repo",
+ sha,
+ },
+ };
+
+ const result = runCanvasStructureGate(repoDir, plugin, sha);
+ assert.equal(result.status, "pass");
+ assert.match(result.output, /found "extensions"/);
+});
+
+test("runCanvasStructureGate fails when extension entrypoint is only at repo root", () => {
+ const repoDir = createTempRepo();
+ fs.writeFileSync(path.join(repoDir, "extension.mjs"), "export default {};\n");
+ const sha = commitAll(repoDir, "Add root extension entrypoint");
+
+ const plugin = {
+ name: "canvas-plugin",
+ keywords: ["canvas"],
+ source: {
+ source: "github",
+ repo: "owner/repo",
+ sha,
+ },
+ };
+
+ const result = runCanvasStructureGate(repoDir, plugin, sha);
+ assert.equal(result.status, "fail");
+ assert.match(result.output, /missing required canvas extension directory "extensions"/);
+});
+
+test("runCanvasStructureGate fails when extension entrypoint path is a directory", () => {
+ const repoDir = createTempRepo();
+ fs.mkdirSync(path.join(repoDir, "extensions", "extension.mjs"), { recursive: true });
+ fs.writeFileSync(path.join(repoDir, "extensions", "extension.mjs", "placeholder.txt"), "not-a-module\n");
+ const sha = commitAll(repoDir, "Add invalid extension entrypoint directory");
+
+ const plugin = {
+ name: "canvas-plugin",
+ keywords: ["canvas"],
+ source: {
+ source: "github",
+ repo: "owner/repo",
+ sha,
+ },
+ };
+
+ const result = runCanvasStructureGate(repoDir, plugin, sha);
+ assert.equal(result.status, "fail");
+ assert.match(result.output, /"extensions\/extension\.mjs" must be a file/);
+});
diff --git a/eng/generate-marketplace.mjs b/eng/generate-marketplace.mjs
index 45a54b21..6c40c463 100755
--- a/eng/generate-marketplace.mjs
+++ b/eng/generate-marketplace.mjs
@@ -62,6 +62,16 @@ function collectLocalPluginsFromRoot(rootDir, sourcePrefix, includeEntry = () =>
return plugins;
}
+function hasExtensionEntryPoint(extensionDir, extensionName) {
+ const candidateEntryPoints = [
+ path.join(extensionDir, "extension.mjs"),
+ path.join(extensionDir, "extensions", "extension.mjs"),
+ path.join(extensionDir, "extensions", extensionName, "extension.mjs"),
+ ];
+
+ return candidateEntryPoints.some((entryPointPath) => fs.existsSync(entryPointPath));
+}
+
/**
* Generate marketplace.json from plugin directories
*/
@@ -78,7 +88,7 @@ function generateMarketplace() {
...collectLocalPluginsFromRoot(
EXTENSIONS_DIR,
"extensions",
- (entryName) => fs.existsSync(path.join(EXTENSIONS_DIR, entryName, "extension.mjs"))
+ (entryName) => hasExtensionEntryPoint(path.join(EXTENSIONS_DIR, entryName), entryName)
)
];
diff --git a/eng/generate-website-data.mjs b/eng/generate-website-data.mjs
index 2e646443..f6fc2082 100755
--- a/eng/generate-website-data.mjs
+++ b/eng/generate-website-data.mjs
@@ -2,7 +2,7 @@
/**
* Generate JSON metadata files for the GitHub Pages website.
- * This script extracts metadata from agents, instructions, skills, hooks, and plugins
+ * This script extracts metadata from agents, instructions, skills, and plugins
* and writes them to website/data/ for client-side search and display.
*/
@@ -14,27 +14,36 @@ import {
AGENTS_DIR,
COOKBOOK_DIR,
EXTENSIONS_DIR,
- HOOKS_DIR,
INSTRUCTIONS_DIR,
PLUGINS_DIR,
ROOT_FOLDER,
SKILLS_DIR,
- WORKFLOWS_DIR,
} from "./constants.mjs";
import { getGitFileDates } from "./utils/git-dates.mjs";
import {
parseFrontmatter,
- parseHookMetadata,
parseSkillMetadata,
- parseWorkflowMetadata,
parseYamlFile,
} from "./yaml-parser.mjs";
+import { readExternalPlugins } from "./external-plugin-validation.mjs";
const __filename = fileURLToPath(import.meta.url);
const WEBSITE_DIR = path.join(ROOT_FOLDER, "website");
const WEBSITE_DATA_DIR = path.join(WEBSITE_DIR, "public", "data");
const WEBSITE_SOURCE_DATA_DIR = path.join(WEBSITE_DIR, "data");
+const EXTERNAL_CANVAS_KEYWORD = "canvas";
+const EXTERNAL_CANVAS_PREVIEW_PATH = "assets/preview.png";
+
+function hasExtensionEntryPoint(extensionDir, extensionName) {
+ const candidateEntryPoints = [
+ path.join(extensionDir, "extension.mjs"),
+ path.join(extensionDir, "extensions", "extension.mjs"),
+ path.join(extensionDir, "extensions", extensionName, "extension.mjs"),
+ ];
+
+ return candidateEntryPoints.some((entryPointPath) => fs.existsSync(entryPointPath));
+}
/**
* Ensure the output directory exists
@@ -101,6 +110,23 @@ function normalizeText(value, fallback = "") {
return typeof value === "string" ? value.trim() : fallback;
}
+function normalizeRepoRelativePath(value) {
+ const normalized = normalizeText(value);
+ if (!normalized || normalized === "/") {
+ return "";
+ }
+
+ return normalized.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+}
+
+function joinRepoPath(...segments) {
+ return segments
+ .map((segment) => String(segment ?? "").trim())
+ .filter(Boolean)
+ .join("/")
+ .replace(/\/+/g, "/");
+}
+
/**
* Normalize an author value (npm string form or { name, url } object) to
* { name, url? } | null. Returns null when no usable name is present.
@@ -211,136 +237,6 @@ function generateAgentsData(gitDates) {
};
}
-/**
- * Generate hooks metadata
- */
-/**
- * Generate hooks metadata (similar to skills - folder-based)
- */
-function generateHooksData(gitDates) {
- const hooks = [];
-
- // Check if hooks directory exists
- if (!fs.existsSync(HOOKS_DIR)) {
- return {
- items: hooks,
- filters: {
- hooks: [],
- tags: [],
- },
- };
- }
-
- // Get all hook folders (directories)
- const hookFolders = fs.readdirSync(HOOKS_DIR).filter((file) => {
- const filePath = path.join(HOOKS_DIR, file);
- return fs.statSync(filePath).isDirectory();
- });
-
- // Track all unique values for filters
- const allHookTypes = new Set();
- const allTags = new Set();
-
- for (const folder of hookFolders) {
- const hookPath = path.join(HOOKS_DIR, folder);
- const metadata = parseHookMetadata(hookPath);
- if (!metadata) continue;
-
- const relativePath = path
- .relative(ROOT_FOLDER, hookPath)
- .replace(/\\/g, "/");
- const readmeRelativePath = `${relativePath}/README.md`;
-
- // Get all files in the hook folder recursively (for the file browser and
- // ZIP download on the detail page).
- const files = getFolderFiles(hookPath, relativePath);
-
- // Track unique values
- (metadata.hooks || []).forEach((h) => allHookTypes.add(h));
- (metadata.tags || []).forEach((t) => allTags.add(t));
-
- hooks.push({
- id: folder,
- title: metadata.name,
- description: metadata.description,
- hooks: metadata.hooks || [],
- tags: metadata.tags || [],
- assets: metadata.assets || [],
- files,
- path: relativePath,
- readmeFile: readmeRelativePath,
- readmeFileName: "README.md",
- lastUpdated: gitDates.get(readmeRelativePath) || null,
- });
- }
-
- // Sort and return with filter metadata
- const sortedHooks = hooks.sort((a, b) => a.title.localeCompare(b.title));
-
- return {
- items: sortedHooks,
- filters: {
- hooks: Array.from(allHookTypes).sort(),
- tags: Array.from(allTags).sort(),
- },
- };
-}
-
-/**
- * Generate workflows metadata (flat .md files)
- */
-function generateWorkflowsData(gitDates) {
- const workflows = [];
-
- if (!fs.existsSync(WORKFLOWS_DIR)) {
- return {
- items: workflows,
- filters: {
- triggers: [],
- },
- };
- }
-
- const workflowFiles = fs.readdirSync(WORKFLOWS_DIR).filter((file) => {
- return file.endsWith(".md") && file !== ".gitkeep";
- });
-
- const allTriggers = new Set();
-
- for (const file of workflowFiles) {
- const filePath = path.join(WORKFLOWS_DIR, file);
- const metadata = parseWorkflowMetadata(filePath);
- if (!metadata) continue;
-
- const relativePath = path
- .relative(ROOT_FOLDER, filePath)
- .replace(/\\/g, "/");
-
- (metadata.triggers || []).forEach((t) => allTriggers.add(t));
-
- const id = path.basename(file, ".md");
- workflows.push({
- id,
- title: metadata.name,
- description: metadata.description,
- triggers: metadata.triggers || [],
- path: relativePath,
- lastUpdated: gitDates.get(relativePath) || null,
- });
- }
-
- const sortedWorkflows = workflows.sort((a, b) =>
- a.title.localeCompare(b.title)
- );
-
- return {
- items: sortedWorkflows,
- filters: {
- triggers: Array.from(allTriggers).sort(),
- },
- };
-}
-
/**
* Parse applyTo field into an array of patterns
*/
@@ -565,7 +461,7 @@ function getAgentFiles(agentDir, pluginRootPath) {
* Build a lookup index of resource id -> { title, url } for the kinds that have
* dedicated detail pages, so plugin items can deep-link to them.
*/
-function buildResourceIndex({ agents, skills, instructions, hooks, extensions }) {
+function buildResourceIndex({ agents, skills, instructions, extensions }) {
const toMap = (items, urlPrefix) => {
const map = new Map();
for (const item of items || []) {
@@ -602,7 +498,6 @@ function buildResourceIndex({ agents, skills, instructions, hooks, extensions })
agent: toMap(agents, "agent"),
skill: toMap(skills, "skill"),
instruction: toMap(instructions, "instruction"),
- hook: toMap(hooks, "hook"),
extension: extensionMap,
};
}
@@ -635,7 +530,7 @@ function resolvePluginItem(item, resourceIndex) {
return {
...item,
- title: match?.title || candidateId || item.path,
+ title: match?.title || item.title || candidateId || item.path,
detailUrl: match?.url || null,
};
}
@@ -659,7 +554,7 @@ function generatePluginsData(gitDates, resourceIndex = {}) {
const extensionDirs = fs.readdirSync(EXTENSIONS_DIR, { withFileTypes: true })
.filter((entry) => {
if (!entry.isDirectory()) return false;
- return fs.existsSync(path.join(EXTENSIONS_DIR, entry.name, "extension.mjs"));
+ return hasExtensionEntryPoint(path.join(EXTENSIONS_DIR, entry.name), entry.name);
})
.map((entry) => entry.name)
.sort((a, b) => a.localeCompare(b));
@@ -749,12 +644,40 @@ function generatePluginsData(gitDates, resourceIndex = {}) {
];
});
- // Build items list from spec fields (agents, commands, skills)
+ // Parse mcpServers: supports a path to a .mcp.json file or an inline object
+ const mcpItems = [];
+ if (data.mcpServers) {
+ let mcpServersObj = null;
+ let mcpConfigPath = relPath;
+ if (typeof data.mcpServers === "string") {
+ const manifestMcpPath = data.mcpServers.replace(/^\.\//, "");
+ mcpConfigPath = manifestMcpPath ? `${relPath}/${manifestMcpPath}` : relPath;
+ const mcpJsonPath = path.join(pluginDir, manifestMcpPath);
+ if (fs.existsSync(mcpJsonPath)) {
+ try {
+ const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, "utf-8"));
+ mcpServersObj = mcpJson.mcpServers || mcpJson;
+ } catch {
+ // ignore parse errors
+ }
+ }
+ } else if (typeof data.mcpServers === "object") {
+ mcpServersObj = data.mcpServers;
+ }
+ if (mcpServersObj) {
+ for (const serverName of Object.keys(mcpServersObj)) {
+ mcpItems.push({ kind: "mcp", path: mcpConfigPath, title: serverName });
+ }
+ }
+ }
+
+ // Build items list from spec fields (agents, commands, skills, mcpServers)
const items = [
...agentItems,
...(data.commands || []).map((p) => ({ kind: "prompt", path: p })),
...(data.skills || []).map((p) => ({ kind: "skill", path: p })),
...extensionItems,
+ ...mcpItems,
].map((item) => resolvePluginItem(item, resourceIndex));
const tags = data.keywords || data.tags || [];
@@ -1162,6 +1085,67 @@ function normalizeExternalScreenshotRole(value, ref) {
};
}
+function buildExternalRepoImageUrl(repo, locator, assetPath) {
+ if (!repo || !locator || !assetPath) {
+ return null;
+ }
+
+ const encodedLocator = locator
+ .split("/")
+ .map((segment) => encodeURIComponent(segment))
+ .join("/");
+ const encodedPath = assetPath
+ .split("/")
+ .map((segment) => encodeURIComponent(segment))
+ .join("/");
+ return `https://raw.githubusercontent.com/${repo}/${encodedLocator}/${encodedPath}`;
+}
+
+function buildExternalRepoTreeUrl(repo, locator, pluginRoot) {
+ if (!repo) {
+ return null;
+ }
+
+ if (locator) {
+ const treePath = normalizeRepoRelativePath(pluginRoot);
+ const encodedLocator = locator
+ .split("/")
+ .map((segment) => encodeURIComponent(segment))
+ .join("/");
+ const encodedTreePath = treePath
+ ? treePath
+ .split("/")
+ .map((segment) => encodeURIComponent(segment))
+ .join("/")
+ : null;
+ const suffix = encodedTreePath ? `/${encodedTreePath}` : "";
+ return `https://github.com/${repo}/tree/${encodedLocator}${suffix}`;
+ }
+
+ return `https://github.com/${repo}`;
+}
+
+function hasCanvasKeyword(plugin) {
+ return normalizeExternalKeywords(plugin).some(
+ (keyword) => normalizeText(keyword).toLowerCase() === EXTERNAL_CANVAS_KEYWORD
+ );
+}
+
+function normalizeExternalKeywords(plugin) {
+ const source = Array.isArray(plugin?.keywords)
+ ? plugin.keywords
+ : Array.isArray(plugin?.tags)
+ ? plugin.tags
+ : [];
+
+ return [...new Set(
+ source
+ .filter((keyword) => typeof keyword === "string")
+ .map((keyword) => keyword.trim())
+ .filter(Boolean)
+ )].sort((a, b) => a.localeCompare(b));
+}
+
function normalizeExtensionScreenshotRole(value, relPath, ref) {
if (!value) return null;
if (typeof value === "string") {
@@ -1261,12 +1245,7 @@ function generateCanvasManifest(gitDates, commitSha) {
.readdirSync(EXTENSIONS_DIR, { withFileTypes: true })
.filter((entry) => {
if (!entry.isDirectory()) return false;
- const extensionEntryPoint = path.join(
- EXTENSIONS_DIR,
- entry.name,
- "extension.mjs"
- );
- return fs.existsSync(extensionEntryPoint);
+ return hasExtensionEntryPoint(path.join(EXTENSIONS_DIR, entry.name), entry.name);
})
.sort((a, b) => a.name.localeCompare(b.name));
@@ -1427,6 +1406,93 @@ function generateCanvasManifest(gitDates, commitSha) {
}
}
+ const seenExtensionIds = new Set(items.map((item) => String(item.id).toLowerCase()));
+ const {
+ plugins: externalPlugins,
+ errors: externalPluginErrors,
+ warnings: externalPluginWarnings,
+ } = readExternalPlugins({ policy: "marketplace" });
+ externalPluginWarnings.forEach((warning) => console.warn(`Warning: ${warning}`));
+ if (externalPluginErrors.length > 0) {
+ externalPluginErrors.forEach((error) => console.error(`Error: ${error}`));
+ throw new Error("External plugin validation failed");
+ }
+
+ for (const ext of externalPlugins) {
+ if (!hasCanvasKeyword(ext)) {
+ continue;
+ }
+
+ const name = normalizeText(ext?.name);
+ if (!name) {
+ continue;
+ }
+ const displayName = formatDisplayName(name);
+
+ const id = normalizeText(ext?.name).toLowerCase().replace(/\s+/g, "-");
+ if (seenExtensionIds.has(id)) {
+ continue;
+ }
+
+ const source = ext?.source;
+ if (source?.source !== "github" || !normalizeText(source?.repo)) {
+ console.warn(`Warning: skipping external canvas "${name}" due to missing GitHub source`);
+ continue;
+ }
+
+ const locator = normalizeText(source.sha) || normalizeText(source.ref);
+ if (!locator) {
+ console.warn(`Warning: skipping external canvas "${name}" because source.sha or source.ref is required`);
+ continue;
+ }
+
+ const pluginRoot = normalizeRepoRelativePath(source.path);
+ const previewPath = joinRepoPath(pluginRoot, EXTERNAL_CANVAS_PREVIEW_PATH);
+ const imageUrl = buildExternalRepoImageUrl(source.repo, locator, previewPath);
+ const sourceUrl = buildExternalRepoTreeUrl(source.repo, locator, pluginRoot);
+ const externalSource = normalizeText(source.repo);
+ const keywords = normalizeExternalKeywords(ext);
+
+ items.push({
+ id,
+ canvasId: id,
+ extensionId: id,
+ extensionName: name,
+ pluginName: null,
+ name: displayName,
+ version: normalizeText(ext?.version, "1.0.0"),
+ readmeFile: null,
+ description: normalizeText(ext?.description, "External canvas extension"),
+ path: null,
+ ref: null,
+ lastUpdated: null,
+ screenshots: {
+ icon: imageUrl
+ ? {
+ path: imageUrl,
+ type: getImageMimeType(EXTERNAL_CANVAS_PREVIEW_PATH),
+ }
+ : null,
+ gallery: imageUrl
+ ? {
+ path: imageUrl,
+ type: getImageMimeType(EXTERNAL_CANVAS_PREVIEW_PATH),
+ }
+ : null,
+ },
+ imageUrl,
+ assetPath: null,
+ installUrl: null,
+ installCommand: null,
+ sourceUrl,
+ externalSource,
+ external: true,
+ author: normalizeAuthor(ext?.author),
+ keywords,
+ });
+ seenExtensionIds.add(id);
+ }
+
const sortedItems = items.sort((a, b) => a.name.localeCompare(b.name));
const keywordFilters = [...new Set(sortedItems.flatMap((item) => item.keywords || []))]
.filter(Boolean)
@@ -1459,71 +1525,12 @@ function generateExtensionsData(extensionManifestData) {
return { items, filters };
}
-/**
- * Generate tools metadata from website/data/tools.yml
- */
-function generateToolsData() {
- const toolsFile = path.join(WEBSITE_SOURCE_DATA_DIR, "tools.yml");
-
- if (!fs.existsSync(toolsFile)) {
- console.warn("No tools.yml file found at", toolsFile);
- return { items: [], filters: { categories: [], tags: [] } };
- }
-
- const data = parseYamlFile(toolsFile);
-
- if (!data || !data.tools) {
- return { items: [], filters: { categories: [], tags: [] } };
- }
-
- const allCategories = new Set();
- const allTags = new Set();
-
- const tools = data.tools.map((tool) => {
- const category = tool.category || "Other";
- allCategories.add(category);
-
- const tags = tool.tags || [];
- tags.forEach((t) => allTags.add(t));
-
- return {
- id: tool.id,
- name: tool.name,
- description: tool.description || "",
- category: category,
- featured: tool.featured || false,
- requirements: tool.requirements || [],
- features: tool.features || [],
- links: tool.links || {},
- configuration: tool.configuration || null,
- tags: tags,
- };
- });
-
- // Sort with featured first, then alphabetically
- const sortedTools = tools.sort((a, b) => {
- if (a.featured && !b.featured) return -1;
- if (!a.featured && b.featured) return 1;
- return a.name.localeCompare(b.name);
- });
-
- return {
- items: sortedTools,
- filters: {
- categories: Array.from(allCategories).sort(),
- tags: Array.from(allTags).sort(),
- },
- };
-}
-
/**
* Generate a combined index for search
*/
function generateSearchIndex(
agents,
instructions,
- hooks,
- workflows,
skills,
plugins
) {
@@ -1556,33 +1563,6 @@ function generateSearchIndex(
});
}
- for (const hook of hooks) {
- index.push({
- type: "hook",
- id: hook.id,
- title: hook.title,
- description: hook.description,
- path: hook.readmeFile,
- lastUpdated: hook.lastUpdated,
- searchText: `${hook.title} ${hook.description} ${hook.hooks.join(
- " "
- )} ${hook.tags.join(" ")}`.toLowerCase(),
- });
- }
-
- for (const workflow of workflows) {
- index.push({
- type: "workflow",
- id: workflow.id,
- title: workflow.title,
- description: workflow.description,
- path: workflow.path,
- lastUpdated: workflow.lastUpdated,
- searchText: `${workflow.title} ${workflow.description
- } ${workflow.triggers.join(" ")}`.toLowerCase(),
- });
- }
-
for (const skill of skills) {
index.push({
type: "skill",
@@ -1752,8 +1732,6 @@ async function main() {
[
"agents/",
"instructions/",
- "hooks/",
- "workflows/",
"skills/",
"extensions/",
"plugins/",
@@ -1771,18 +1749,6 @@ async function main() {
`✓ Generated ${agents.length} agents (${agentsData.filters.models.length} models, ${agentsData.filters.tools.length} tools)`
);
- const hooksData = generateHooksData(gitDates);
- const hooks = hooksData.items;
- console.log(
- `✓ Generated ${hooks.length} hooks (${hooksData.filters.hooks.length} hook types, ${hooksData.filters.tags.length} tags)`
- );
-
- const workflowsData = generateWorkflowsData(gitDates);
- const workflows = workflowsData.items;
- console.log(
- `✓ Generated ${workflows.length} workflows (${workflowsData.filters.triggers.length} triggers)`
- );
-
const instructionsData = generateInstructionsData(gitDates);
const instructions = instructionsData.items;
console.log(
@@ -1804,7 +1770,6 @@ async function main() {
agents,
skills,
instructions,
- hooks,
extensions,
});
const pluginsData = generatePluginsData(gitDates, resourceIndex);
@@ -1813,12 +1778,6 @@ async function main() {
`✓ Generated ${plugins.length} plugins (${pluginsData.filters.tags.length} tags)`
);
- const toolsData = generateToolsData();
- const tools = toolsData.items;
- console.log(
- `✓ Generated ${tools.length} tools (${toolsData.filters.categories.length} categories)`
- );
-
const samplesData = generateSamplesData();
console.log(
`✓ Generated ${samplesData.totalRecipes} recipes in ${samplesData.totalCookbooks} cookbooks (${samplesData.filters.languages.length} languages, ${samplesData.filters.tags.length} tags)`
@@ -1833,8 +1792,6 @@ async function main() {
const searchIndex = generateSearchIndex(
agents,
instructions,
- hooks,
- workflows,
skills,
plugins
);
@@ -1846,16 +1803,6 @@ async function main() {
JSON.stringify(agentsData, null, 2)
);
- fs.writeFileSync(
- path.join(WEBSITE_DATA_DIR, "hooks.json"),
- JSON.stringify(hooksData, null, 2)
- );
-
- fs.writeFileSync(
- path.join(WEBSITE_DATA_DIR, "workflows.json"),
- JSON.stringify(workflowsData, null, 2)
- );
-
fs.writeFileSync(
path.join(WEBSITE_DATA_DIR, "instructions.json"),
JSON.stringify(instructionsData, null, 2)
@@ -1876,10 +1823,6 @@ async function main() {
JSON.stringify(extensionsData, null, 2)
);
- fs.writeFileSync(
- path.join(WEBSITE_DATA_DIR, "tools.json"),
- JSON.stringify(toolsData, null, 2)
- );
fs.writeFileSync(
path.join(WEBSITE_DATA_DIR, "samples.json"),
@@ -1898,11 +1841,8 @@ async function main() {
agents: agents.length,
instructions: instructions.length,
skills: skills.length,
- hooks: hooks.length,
- workflows: workflows.length,
plugins: plugins.length,
extensions: extensions.length,
- tools: tools.length,
contributors: contributorCount,
samples: samplesData.totalRecipes,
total: searchIndex.length,
diff --git a/eng/materialize-plugins.mjs b/eng/materialize-plugins.mjs
index 978c250f..905b2faf 100644
--- a/eng/materialize-plugins.mjs
+++ b/eng/materialize-plugins.mjs
@@ -2,9 +2,11 @@
import fs from "fs";
import path from "path";
+import { fileURLToPath } from "url";
import { ROOT_FOLDER } from "./constants.mjs";
const PLUGINS_DIR = path.join(ROOT_FOLDER, "plugins");
+const EXTENSIONS_DIR = path.join(ROOT_FOLDER, "extensions");
/**
* Recursively copy a directory.
@@ -22,6 +24,36 @@ function copyDirRecursive(src, dest) {
}
}
+function moveEntry(srcPath, destPath) {
+ fs.mkdirSync(path.dirname(destPath), { recursive: true });
+ try {
+ fs.renameSync(srcPath, destPath);
+ return;
+ } catch (error) {
+ if (error?.code !== "EXDEV") {
+ throw error;
+ }
+ }
+
+ const stats = fs.statSync(srcPath);
+ if (stats.isDirectory()) {
+ copyDirRecursive(srcPath, destPath);
+ fs.rmSync(srcPath, { recursive: true, force: true });
+ return;
+ }
+
+ fs.copyFileSync(srcPath, destPath);
+ fs.rmSync(srcPath, { force: true });
+}
+
+function isRelativeAssetPath(assetPath) {
+ return typeof assetPath === "string" &&
+ assetPath.length > 0 &&
+ !/^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(assetPath) &&
+ !assetPath.startsWith("data:") &&
+ !path.isAbsolute(assetPath);
+}
+
/**
* Resolve a plugin-relative path to the repo-root source file.
*
@@ -45,6 +77,59 @@ function resolveSource(relPath) {
return null;
}
+export function materializeExtensionPlugin(extensionPath) {
+ const pluginJsonPath = path.join(extensionPath, ".github", "plugin", "plugin.json");
+ if (!fs.existsSync(pluginJsonPath)) {
+ return { movedEntries: 0, manifestUpdated: false, skipped: true };
+ }
+
+ let metadata;
+ try {
+ metadata = JSON.parse(fs.readFileSync(pluginJsonPath, "utf8"));
+ } catch (err) {
+ throw new Error(`Failed to parse ${pluginJsonPath}: ${err.message}`);
+ }
+
+ const extensionContainerPath = path.join(extensionPath, "extensions");
+ const extensionBundlePath = path.join(extensionContainerPath, path.basename(extensionPath));
+ fs.rmSync(extensionContainerPath, { recursive: true, force: true });
+ fs.mkdirSync(extensionBundlePath, { recursive: true });
+
+ let movedEntries = 0;
+ for (const entry of fs.readdirSync(extensionPath, { withFileTypes: true })) {
+ if (entry.name === ".github" || entry.name === "extensions") {
+ continue;
+ }
+
+ moveEntry(
+ path.join(extensionPath, entry.name),
+ path.join(extensionBundlePath, entry.name)
+ );
+ movedEntries++;
+ }
+
+ if (isRelativeAssetPath(metadata.logo)) {
+ const normalizedLogoPath = metadata.logo.replace(/\\/g, "/").replace(/^\.\//, "");
+ const bundledLogoPath = path.join(extensionBundlePath, normalizedLogoPath);
+ if (fs.existsSync(bundledLogoPath)) {
+ const rootLogoPath = path.join(extensionPath, normalizedLogoPath);
+ fs.mkdirSync(path.dirname(rootLogoPath), { recursive: true });
+ fs.copyFileSync(bundledLogoPath, rootLogoPath);
+ }
+ }
+
+ let manifestUpdated = false;
+ if (metadata.extensions !== "extensions") {
+ metadata.extensions = "extensions";
+ manifestUpdated = true;
+ }
+ if (manifestUpdated) {
+ fs.writeFileSync(pluginJsonPath, JSON.stringify(metadata, null, 2) + "\n", "utf8");
+ }
+
+ return { movedEntries, manifestUpdated, skipped: false };
+}
+
function materializePlugins() {
console.log("Materializing plugin files...\n");
@@ -61,6 +146,8 @@ function materializePlugins() {
let totalAgents = 0;
let totalSkills = 0;
let totalExtensions = 0;
+ let totalExtensionPlugins = 0;
+ let totalExtensionPluginEntries = 0;
let warnings = 0;
let errors = 0;
@@ -185,7 +272,36 @@ function materializePlugins() {
}
}
- console.log(`\nDone. Copied ${totalAgents} agents, ${totalSkills} skills, ${totalExtensions} extensions.`);
+ if (fs.existsSync(EXTENSIONS_DIR)) {
+ const extensionDirs = fs.readdirSync(EXTENSIONS_DIR, { withFileTypes: true })
+ .filter((entry) => entry.isDirectory())
+ .map((entry) => entry.name)
+ .sort();
+
+ for (const dirName of extensionDirs) {
+ const extensionPath = path.join(EXTENSIONS_DIR, dirName);
+ if (!fs.existsSync(path.join(extensionPath, "extension.mjs"))) {
+ continue;
+ }
+
+ try {
+ const result = materializeExtensionPlugin(extensionPath);
+ if (result.skipped) {
+ continue;
+ }
+
+ totalExtensionPlugins++;
+ totalExtensionPluginEntries += result.movedEntries;
+ console.log(`✓ ${dirName}: materialized extension bundle into ./extensions (${result.movedEntries} entries)`);
+ } catch (err) {
+ console.error(`Error: Failed to materialize extension plugin ${dirName}: ${err.message}`);
+ errors++;
+ }
+ }
+ }
+
+ console.log(`\nDone. Copied ${totalAgents} agents, ${totalSkills} skills, ${totalExtensions} plugin extension refs.`);
+ console.log(`Materialized ${totalExtensionPlugins} extension plugins (${totalExtensionPluginEntries} top-level entries).`);
if (warnings > 0) {
console.log(`${warnings} warning(s).`);
}
@@ -195,4 +311,8 @@ function materializePlugins() {
}
}
-materializePlugins();
+export { materializePlugins };
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ materializePlugins();
+}
diff --git a/eng/materialize-plugins.test.mjs b/eng/materialize-plugins.test.mjs
new file mode 100644
index 00000000..d0bce457
--- /dev/null
+++ b/eng/materialize-plugins.test.mjs
@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { after, test } from "node:test";
+import { materializeExtensionPlugin } from "./materialize-plugins.mjs";
+import { cleanMaterializedExtensionPlugin } from "./clean-materialized-plugins.mjs";
+
+const tempDirs = [];
+
+after(() => {
+ for (const dir of tempDirs) {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("materializeExtensionPlugin writes extension bundles to ./extensions and preserves root logo assets", () => {
+ const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "materialize-extension-plugin-"));
+ tempDirs.push(tempDir);
+
+ const pluginDir = path.join(tempDir, "extension-plugin");
+ fs.mkdirSync(path.join(pluginDir, ".github", "plugin"), { recursive: true });
+ fs.mkdirSync(path.join(pluginDir, "assets"), { recursive: true });
+ fs.writeFileSync(path.join(pluginDir, ".github", "plugin", "plugin.json"), JSON.stringify({
+ name: "test-extension-plugin",
+ description: "test plugin",
+ version: "1.0.0",
+ logo: "assets/preview.png",
+ extensions: ".",
+ }, null, 2));
+ fs.writeFileSync(path.join(pluginDir, "extension.mjs"), "export default {};\n");
+ fs.writeFileSync(path.join(pluginDir, "README.md"), "# test\n");
+ fs.writeFileSync(path.join(pluginDir, "assets", "preview.png"), "fake-image-bytes");
+
+ const result = materializeExtensionPlugin(pluginDir);
+ const bundleRoot = path.join(pluginDir, "extensions", "extension-plugin");
+
+ assert.equal(result.skipped, false);
+ assert.equal(result.manifestUpdated, true);
+ assert.equal(result.movedEntries, 3);
+ assert.equal(fs.existsSync(path.join(bundleRoot, "extension.mjs")), true);
+ assert.equal(fs.existsSync(path.join(bundleRoot, "assets", "preview.png")), true);
+ assert.equal(fs.existsSync(path.join(bundleRoot, "README.md")), true);
+ assert.equal(fs.existsSync(path.join(pluginDir, "extensions", ".github")), false);
+ assert.equal(fs.existsSync(path.join(pluginDir, "extension.mjs")), false);
+ assert.equal(fs.existsSync(path.join(pluginDir, "README.md")), false);
+ assert.equal(fs.existsSync(path.join(pluginDir, "assets", "preview.png")), true);
+
+ const pluginManifest = JSON.parse(
+ fs.readFileSync(path.join(pluginDir, ".github", "plugin", "plugin.json"), "utf8")
+ );
+ assert.equal(pluginManifest.extensions, "extensions");
+ assert.equal(pluginManifest.logo, "assets/preview.png");
+});
+
+test("cleanMaterializedExtensionPlugin restores moved extension files to root", () => {
+ const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "clean-materialized-extension-plugin-"));
+ tempDirs.push(tempDir);
+
+ const pluginDir = path.join(tempDir, "extension-plugin");
+ fs.mkdirSync(path.join(pluginDir, ".github", "plugin"), { recursive: true });
+ fs.mkdirSync(path.join(pluginDir, "assets"), { recursive: true });
+ fs.writeFileSync(path.join(pluginDir, ".github", "plugin", "plugin.json"), JSON.stringify({
+ name: "test-extension-plugin",
+ description: "test plugin",
+ version: "1.0.0",
+ logo: "assets/preview.png",
+ extensions: ".",
+ }, null, 2));
+ fs.writeFileSync(path.join(pluginDir, "extension.mjs"), "export default {};\n");
+ fs.writeFileSync(path.join(pluginDir, "README.md"), "# test\n");
+ fs.writeFileSync(path.join(pluginDir, "assets", "preview.png"), "fake-image-bytes");
+
+ materializeExtensionPlugin(pluginDir);
+ const result = cleanMaterializedExtensionPlugin(pluginDir);
+
+ assert.equal(result.removed, 3);
+ assert.equal(result.manifestUpdated, true);
+ assert.equal(fs.existsSync(path.join(pluginDir, "extension.mjs")), true);
+ assert.equal(fs.existsSync(path.join(pluginDir, "README.md")), true);
+ assert.equal(fs.existsSync(path.join(pluginDir, "assets", "preview.png")), true);
+ assert.equal(fs.existsSync(path.join(pluginDir, "extensions")), false);
+
+ const pluginManifest = JSON.parse(
+ fs.readFileSync(path.join(pluginDir, ".github", "plugin", "plugin.json"), "utf8")
+ );
+ assert.equal(pluginManifest.extensions, ".");
+ assert.equal(pluginManifest.logo, "assets/preview.png");
+});
diff --git a/eng/validate-plugins.mjs b/eng/validate-plugins.mjs
index fc8003b3..7161df06 100755
--- a/eng/validate-plugins.mjs
+++ b/eng/validate-plugins.mjs
@@ -305,9 +305,14 @@ function validateExtensionManifest(folderName) {
errors.push("x-awesome-copilot field must not be present (use convention-based logo instead)");
}
- // Extension convention: extensions field must be "."
+ if (parsed.extenions !== undefined) {
+ errors.push('use "extensions" field (found misspelled key "extenions")');
+ }
+
+ // Extension convention: source manifests keep extensions at repository root.
+ // Materialization rewrites this to "extensions" on distribution branches.
if (parsed.extensions !== ".") {
- errors.push('extensions field must be exactly "." (extension convention)');
+ errors.push('extensions field must be exactly "." in source manifests (extension convention)');
}
return { errors, plugin: parsedPlugin };
diff --git a/extensions/accessibility-kanban/.github/plugin/plugin.json b/extensions/accessibility-kanban/.github/plugin/plugin.json
index 824a71c5..25bfbc1a 100644
--- a/extensions/accessibility-kanban/.github/plugin/plugin.json
+++ b/extensions/accessibility-kanban/.github/plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "accessibility-kanban",
"description": "Kanban board to manage accessibility issues, allow you to plan, track, and complete remediation work.",
- "version": "1.0.0",
+ "version": "1.0.2",
"author": {
"name": "Aaron Powell",
"url": "https://github.com/aaronpowell"
diff --git a/extensions/apng-studio/.github/plugin/plugin.json b/extensions/apng-studio/.github/plugin/plugin.json
index 6c46943c..9522900b 100644
--- a/extensions/apng-studio/.github/plugin/plugin.json
+++ b/extensions/apng-studio/.github/plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "apng-studio",
"description": "Interactive GitHub Copilot app canvas extension for building Animated PNG (APNG) files from frames. Draw or upload frames, tune per-frame timing and compositing, preview live, send the result to your phone by QR, and export an animated .png.",
- "version": "1.0.0",
+ "version": "1.0.2",
"author": {
"name": "Andrea Griffiths",
"url": "https://github.com/AndreaGriffiths11"
diff --git a/extensions/arcade-canvas/.github/plugin/plugin.json b/extensions/arcade-canvas/.github/plugin/plugin.json
index 8bf1d4cb..9c45471e 100644
--- a/extensions/arcade-canvas/.github/plugin/plugin.json
+++ b/extensions/arcade-canvas/.github/plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "arcade-canvas",
"description": "Play five retro Phaser mini-games in a Copilot canvas while agents work.",
- "version": "1.0.0",
+ "version": "1.0.2",
"author": {
"name": "Dan Wahlin",
"url": "https://github.com/DanWahlin"
diff --git a/extensions/backlog-swipe-triage/.github/plugin/plugin.json b/extensions/backlog-swipe-triage/.github/plugin/plugin.json
index d45e7e39..aa7f7c16 100644
--- a/extensions/backlog-swipe-triage/.github/plugin/plugin.json
+++ b/extensions/backlog-swipe-triage/.github/plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "backlog-swipe-triage",
"description": "Quickly swipe through backlog issues to triage decisions like assign, needs-info, defer, close, or ignore.",
- "version": "1.0.0",
+ "version": "1.0.2",
"author": {
"name": "James Montemagno",
"url": "https://github.com/jamesmontemagno"
diff --git a/extensions/chromium-control-canvas/.github/plugin/plugin.json b/extensions/chromium-control-canvas/.github/plugin/plugin.json
index c8a2fa72..301485a6 100644
--- a/extensions/chromium-control-canvas/.github/plugin/plugin.json
+++ b/extensions/chromium-control-canvas/.github/plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "chromium-control-canvas",
"description": "Opens a real Chromium window you can navigate and interact with from a Copilot canvas control panel and agent actions.",
- "version": "1.0.0",
+ "version": "1.0.2",
"author": {
"name": "Andrea Griffiths",
"url": "https://github.com/AndreaGriffiths11"
diff --git a/extensions/color-orb/.github/plugin/plugin.json b/extensions/color-orb/.github/plugin/plugin.json
index c162c294..e5e31f0b 100644
--- a/extensions/color-orb/.github/plugin/plugin.json
+++ b/extensions/color-orb/.github/plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "color-orb",
"description": "A visual orb that users can ask the agent to recolor while showing a live activity log in the canvas.",
- "version": "1.0.0",
+ "version": "1.0.2",
"author": {
"name": "Aaron Powell",
"url": "https://github.com/aaronpowell"
diff --git a/extensions/connector-namespaces/.github/plugin/plugin.json b/extensions/connector-namespaces/.github/plugin/plugin.json
new file mode 100644
index 00000000..a75cb84c
--- /dev/null
+++ b/extensions/connector-namespaces/.github/plugin/plugin.json
@@ -0,0 +1,19 @@
+{
+ "name": "connector-namespaces",
+ "description": "Browse, connect, and open MCP connectors from an Azure Connector Namespace.",
+ "version": "1.1.2",
+ "author": {
+ "name": "Alex Yang",
+ "url": "https://github.com/alexyaang"
+ },
+ "keywords": [
+ "azure",
+ "connector-namespace",
+ "mcp",
+ "mcp-connectors",
+ "model-context-protocol",
+ "tool-discovery"
+ ],
+ "logo": "assets/preview.png",
+ "extensions": "."
+}
diff --git a/extensions/connector-namespaces/LICENSE b/extensions/connector-namespaces/LICENSE
new file mode 100644
index 00000000..22aed37e
--- /dev/null
+++ b/extensions/connector-namespaces/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/extensions/connector-namespaces/README.md b/extensions/connector-namespaces/README.md
new file mode 100644
index 00000000..f7346247
--- /dev/null
+++ b/extensions/connector-namespaces/README.md
@@ -0,0 +1,85 @@
+# MCP Connectors — Copilot CLI Canvas Extension
+
+A GitHub Copilot CLI **canvas extension** that lets you browse and add MCP
+connectors from an Azure **Connector Namespace** directly inside a Copilot CLI
+session. Search by name or category, sign in to a connector, then restart the
+session to make its tools available to the agent.
+
+> The canvas talks to public Azure Resource Manager (`management.azure.com`)
+> using the signed-in Azure CLI account. The extension does not register its own
+> Entra application or persist Azure credentials.
+
+## Prerequisites
+
+- **GitHub Copilot CLI** (the host that loads canvas extensions).
+- **Azure CLI**, signed in with `az login`. The extension asks Azure CLI for a
+ short-lived ARM access token and refreshes it through the same broker.
+- **An Azure subscription with a Connector Namespace** — resource type
+ `Microsoft.Web/connectorGateways` (API version `2026-05-01-preview`). This is
+ a preview resource provider; you must have access to it for the catalog to
+ load. Without it the extension installs fine but has nothing to show.
+
+## Install
+
+Install it from the public Awesome Copilot repository:
+
+```
+install_extension https://github.com/github/awesome-copilot/tree/main/extensions/connector-namespaces
+```
+
+For a reproducible install, swap `main` for a reviewed commit SHA from this
+repository.
+
+The destination **scope** is chosen at install time:
+
+- **user** (default) — installs globally for you at
+ `$COPILOT_HOME/extensions/connector-namespaces/`. The usual choice for a
+ personal tool.
+- **project** — installs into the current repo.
+- **session** — scoped to a single CLI session.
+
+## Usage
+
+1. Open the **MCP Connectors** canvas from Copilot CLI.
+2. The canvas loads subscriptions from your signed-in Azure CLI account. Pick an
+ Azure **subscription** and a **Connector Namespace**. The choice is saved for
+ future sessions (change it any time via **Change namespace**).
+3. Browse or filter the connector catalog, then **Connect**. A browser tab
+ opens for Microsoft sign-in; complete it and the canvas updates on its own.
+4. Connected connectors move into **My MCPs**. Use **Sandbox** on a tile to open
+ that server directly in the namespace MCP playground.
+5. Restart the Copilot CLI session so the agent can load the connected tools.
+
+The extension registers the native `connector_namespaces_open_playground` tool,
+so GitHub Copilot can open a named connector from **My MCPs** without installing
+an additional Agent Skill.
+
+## How it works
+
+- `extension.mjs` — entry point; declares the canvas, `open_sandbox` action, and
+ native `connector_namespaces_open_playground` tool.
+- `server.mjs` — a loopback HTTP server (bound to `127.0.0.1` only) that serves
+ the canvas UI and the JSON/OAuth endpoints the iframe calls.
+- `armClient.mjs` — thin ARM client (token brokered by Azure CLI, public ARM
+ base only, SSRF-guarded path segments).
+- `catalog.mjs` — fetches and curates the connector list for a namespace.
+- `install.mjs` — the connect/install pipeline (managed-API connection, consent,
+ rollback on cancel, and native HTTPS MCP config registration).
+- `renderer.mjs` — all canvas HTML/CSS/client JS.
+- `sandbox.mjs` — builds namespace playground links and resolves named My MCPs.
+- `state.mjs` — saved namespace and connector state.
+
+## Privacy & security
+
+- ARM tokens come from `az account get-access-token`, stay in process memory,
+ and are never logged or written by the extension. Azure CLI owns sign-in and
+ credential storage.
+- All servers bind to loopback (`127.0.0.1`) and are never exposed externally.
+- ARM requests go only to `https://management.azure.com/`; path segments are
+ validated to prevent SSRF-style host smuggling.
+- The minted gateway API key is stored in the selected Copilot MCP config and
+ sent to its validated HTTPS endpoint as the `X-API-Key` header.
+
+## License
+
+[MIT](./LICENSE) © Microsoft Corporation.
diff --git a/extensions/connector-namespaces/armClient.mjs b/extensions/connector-namespaces/armClient.mjs
new file mode 100644
index 00000000..dc0f9fc4
--- /dev/null
+++ b/extensions/connector-namespaces/armClient.mjs
@@ -0,0 +1,444 @@
+// ARM API client — fetches real connector data with Azure CLI credentials.
+
+import { exec, execFile } from "node:child_process";
+import { constants as fsConstants, promises as fs } from "node:fs";
+import { homedir, platform } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+const API_VERSION = "2026-05-01-preview";
+const RG_API_VERSION = "2021-04-01";
+const MSI_API_VERSION = "2023-01-31";
+const SUBS_API_VERSION = "2020-01-01";
+
+const execFileAsync = promisify(execFile);
+const execAsync = promisify(exec);
+const ARM_RESOURCE = "https://management.azure.com/";
+const EXPIRY_SKEW_MS = 5 * 60 * 1000;
+const LEGACY_AUTH_CACHE = join(
+ process.env.COPILOT_HOME || join(homedir(), ".copilot"),
+ "extensions",
+ "connector-namespaces",
+ "artifacts",
+ "auth-cache.json",
+);
+
+let s_auth = null; // { token, expiresAt }
+let s_authInFlight = null;
+let s_legacyAuthCacheRemoved = false;
+
+export function parseAzureCliToken(stdout) {
+ let data;
+ try {
+ data = JSON.parse(stdout);
+ } catch {
+ throw new Error("Azure CLI returned invalid token JSON.");
+ }
+ const token = data?.accessToken;
+ const epochSeconds = Number(data?.expires_on);
+ const expiresAt = Number.isFinite(epochSeconds) && epochSeconds > 0
+ ? epochSeconds * 1000
+ : Date.parse(data?.expiresOn);
+ if (typeof token !== "string" || token.length === 0 || !Number.isFinite(expiresAt)) {
+ throw new Error("Azure CLI returned an incomplete ARM token.");
+ }
+ return { token, expiresAt };
+}
+
+async function removeLegacyAuthCache() {
+ if (s_legacyAuthCacheRemoved) return;
+ try {
+ await fs.unlink(LEGACY_AUTH_CACHE);
+ } catch (error) {
+ if (error?.code !== "ENOENT") {
+ throw new Error(`Could not remove the legacy connector credential cache at ${LEGACY_AUTH_CACHE}: ${error.message}`);
+ }
+ }
+ s_legacyAuthCacheRemoved = true;
+}
+
+function windowsSystemExecutable(name) {
+ const systemRoot = process.env.SystemRoot;
+ if (systemRoot && isAbsolute(systemRoot)) return join(systemRoot, "System32", name);
+ throw new Error(`Could not resolve the Windows system executable ${name}.`);
+}
+
+async function trustedExecutablePath(path, expectedName, workspaceRoot = process.cwd()) {
+ if (!isAbsolute(path) || /["\r\n]/.test(path)) return null;
+ let candidate;
+ let workspace;
+ try {
+ [candidate, workspace] = await Promise.all([
+ fs.realpath(path),
+ fs.realpath(workspaceRoot),
+ ]);
+ if (!(await fs.stat(candidate)).isFile()) return null;
+ if (platform() !== "win32") await fs.access(candidate, fsConstants.X_OK);
+ } catch {
+ return null;
+ }
+ const insensitive = platform() === "win32";
+ const normalize = (value) => insensitive ? value.toLowerCase() : value;
+ const normalizedCandidate = normalize(resolve(candidate));
+ const normalizedWorkspace = normalize(resolve(workspace));
+ const workspacePrefix = normalizedWorkspace.endsWith(sep)
+ ? normalizedWorkspace
+ : `${normalizedWorkspace}${sep}`;
+ if (
+ normalize(basename(candidate)) !== normalize(expectedName) ||
+ normalizedCandidate === normalizedWorkspace ||
+ normalizedCandidate.startsWith(workspacePrefix)
+ ) return null;
+ return candidate;
+}
+
+async function resolveWindowsAzureCli() {
+ const trustedCwd = homedir();
+ const { stdout } = await execFileAsync(
+ windowsSystemExecutable("where.exe"),
+ ["az.cmd"],
+ { cwd: trustedCwd, encoding: "utf8", windowsHide: true, timeout: 10_000, maxBuffer: 64 * 1024 },
+ );
+ for (const path of stdout.split(/\r?\n/).map((line) => line.trim())) {
+ if (/[%]/.test(path)) continue;
+ const candidate = await trustedExecutablePath(path, "az.cmd");
+ if (candidate) return candidate;
+ }
+ throw new Error("Azure CLI was not found outside the current workspace.");
+}
+
+export async function resolvePosixAzureCli(pathValue = process.env.PATH || "", workspaceRoot = process.cwd()) {
+ for (const directory of pathValue.split(delimiter)) {
+ const candidate = await trustedExecutablePath(resolve(directory || workspaceRoot, "az"), "az", workspaceRoot);
+ if (candidate) return candidate;
+ }
+ throw new Error("Azure CLI was not found outside the current workspace.");
+}
+
+export async function resolveSystemExecutable(name, workspaceRoot = process.cwd()) {
+ const candidates = platform() === "win32"
+ ? [windowsSystemExecutable(name)]
+ : [join("/usr/bin", name), join("/bin", name), join("/usr/local/bin", name)];
+ for (const path of candidates) {
+ const candidate = await trustedExecutablePath(path, name, workspaceRoot);
+ if (candidate) return candidate;
+ }
+ throw new Error(`Could not resolve the trusted system executable ${name}.`);
+}
+
+async function acquireToken() {
+ await removeLegacyAuthCache();
+ try {
+ const windows = platform() === "win32";
+ const azureCli = windows ? await resolveWindowsAzureCli() : await resolvePosixAzureCli();
+ const options = { cwd: homedir(), encoding: "utf8", windowsHide: true, timeout: 60_000, maxBuffer: 1024 * 1024 };
+ const { stdout } = windows
+ ? await execAsync(
+ `"${azureCli}" account get-access-token --resource https://management.azure.com/ --output json --only-show-errors`,
+ { ...options, shell: windowsSystemExecutable("cmd.exe") },
+ )
+ : await execFileAsync(
+ azureCli,
+ ["account", "get-access-token", "--resource", ARM_RESOURCE, "--output", "json", "--only-show-errors"],
+ options,
+ );
+ s_auth = parseAzureCliToken(stdout);
+ return s_auth.token;
+ } catch (error) {
+ const detail = String(error?.stderr || error?.message || "").trim();
+ throw new Error(
+ `Azure CLI authentication failed. Install Azure CLI and run "az login" before opening the canvas.${detail ? ` ${detail}` : ""}`,
+ );
+ }
+}
+
+export async function getToken() {
+ if (s_auth && s_auth.expiresAt - EXPIRY_SKEW_MS > Date.now()) return s_auth.token;
+ if (s_authInFlight) return s_authInFlight;
+ s_authInFlight = acquireToken().finally(() => {
+ s_authInFlight = null;
+ });
+ return s_authInFlight;
+}
+
+/**
+ * List all enabled Azure subscriptions the user has access to.
+ */
+// The set of enabled subscriptions is stable for a session, so cache it — the
+// first /setup pays the ARM round-trip once and every "Change namespace"
+// afterwards serves from memory.
+let s_subsCache = null; // { subs, expiresAt }
+const SUBS_TTL_MS = 30 * 60 * 1000;
+
+export async function listSubscriptions() {
+ const now = Date.now();
+ if (s_subsCache && s_subsCache.expiresAt > now) return s_subsCache.subs;
+ const token = await getToken();
+ const url = `https://management.azure.com/subscriptions?api-version=${SUBS_API_VERSION}`;
+ const raw = await paginateAll(url, token);
+ const subs = raw
+ .filter((s) => s.state === "Enabled")
+ .map((s) => ({ id: s.subscriptionId, name: s.displayName, tenantId: s.tenantId, state: s.state }));
+ s_subsCache = { subs, expiresAt: now + SUBS_TTL_MS };
+ return subs;
+}
+
+// ARM resource identifiers are a restricted charset (letters, digits and a few
+// punctuation chars). Validating each path segment against this allowlist before
+// it enters a URL rejects anything containing "/", "?", "#", "@" or ":" — the
+// characters that could otherwise alter the request path or redirect the host —
+// and acts as a taint barrier so config/file-derived names cannot reach fetch
+// unvalidated.
+const ARM_SEGMENT = /^[A-Za-z0-9._()-]{1,256}$/;
+
+export function armSegment(value) {
+ const s = String(value);
+ if (s === "." || s === ".." || !ARM_SEGMENT.test(s)) {
+ throw new Error(`Invalid ARM resource identifier: ${s}`);
+ }
+ return s;
+}
+
+function buildBaseUrl(subscriptionId, resourceGroup, gatewayName) {
+ return `https://management.azure.com/subscriptions/${armSegment(subscriptionId)}/resourceGroups/${armSegment(resourceGroup)}/providers/Microsoft.Web/connectorGateways/${armSegment(gatewayName)}`;
+}
+
+// Hard host allowlist: every request this client makes targets ARM and only
+// ARM. The trailing slash matters — it blocks suffix/userinfo bypasses such as
+// "https://management.azure.com.evil.com/" and "https://management.azure.com@evil.com/",
+// neither of which starts with this exact prefix. This guards the paginated
+// nextLink (a server-supplied value) which does not pass through armSegment.
+const ARM_BASE = "https://management.azure.com/";
+
+// Returns the URL only if it targets ARM, otherwise throws. Used by callers
+// (e.g. install.mjs) that build ARM URLs before handing them here.
+export function assertArmHost(rawUrl) {
+ const url = String(rawUrl);
+ if (!url.startsWith(ARM_BASE)) {
+ throw new Error(`Refusing to call non-ARM URL: ${url}`);
+ }
+ return url;
+}
+
+async function armFetch(url, token) {
+ // Guard the exact value handed to fetch so a tainted path segment or a
+ // server-supplied nextLink can never redirect the call off ARM.
+ if (!url.startsWith(ARM_BASE)) {
+ throw new Error(`Refusing to call non-ARM URL: ${url}`);
+ }
+ const res = await fetch(url, {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ "Content-Type": "application/json",
+ },
+ });
+ if (!res.ok) {
+ const body = await res.text();
+ throw new Error(`ARM ${res.status}: ${body.slice(0, 300)}`);
+ }
+ return res.json();
+}
+
+// ARM normally returns distinct nextLink URLs that terminate, but a buggy or
+// hostile endpoint could return a repeating/self-referential nextLink. Guard
+// against an unbounded loop with a seen-set and a hard page cap.
+const MAX_PAGES = 1000;
+
+async function paginateAll(url, token) {
+ const results = [];
+ const seen = new Set();
+ let nextUrl = url;
+ let pages = 0;
+ while (nextUrl) {
+ if (seen.has(nextUrl) || pages >= MAX_PAGES) break;
+ seen.add(nextUrl);
+ pages++;
+ const data = await armFetch(nextUrl, token);
+ if (data.value) results.push(...data.value);
+ nextUrl = data.nextLink || null;
+ }
+ return results;
+}
+
+/**
+ * List connector gateways in a subscription.
+ * Uses $top=10 and stops after the first page for speed.
+ * Pass fetchAll=true to paginate through everything.
+ */
+export async function listConnectorGateways(subscriptionId, { fetchAll = false } = {}) {
+ const token = await getToken();
+ const url = `https://management.azure.com/subscriptions/${armSegment(subscriptionId)}/providers/Microsoft.Web/connectorGateways?api-version=${API_VERSION}&$top=10`;
+ if (fetchAll) return { items: await paginateAll(url, token), hasMore: false };
+ // First page only — much faster
+ const data = await armFetch(url, token);
+ const items = data.value || [];
+ return { items, hasMore: !!data.nextLink };
+}
+
+/**
+ * List managed APIs (traditional connectors)
+ */
+export async function listManagedApis(subscriptionId, resourceGroup, gatewayName) {
+ const token = await getToken();
+ const url = `${buildBaseUrl(subscriptionId, resourceGroup, gatewayName)}/managedApis?api-version=${API_VERSION}`;
+ return paginateAll(url, token);
+}
+
+/**
+ * List managed hosted MCP servers
+ */
+export async function listManagedHostedMcpServers(subscriptionId, resourceGroup, gatewayName) {
+ const token = await getToken();
+ const url = `${buildBaseUrl(subscriptionId, resourceGroup, gatewayName)}/managedHostedMcpServers?api-version=${API_VERSION}`;
+ return paginateAll(url, token);
+}
+
+/**
+ * List managed MCP operations
+ */
+export async function listManagedMcpOperations(subscriptionId, resourceGroup, gatewayName) {
+ const token = await getToken();
+ const url = `${buildBaseUrl(subscriptionId, resourceGroup, gatewayName)}/managedMcpOperations?api-version=${API_VERSION}`;
+ return paginateAll(url, token);
+}
+
+// ---------------------------------------------------------------------------
+// Create connector namespace (provisioning flow)
+// ---------------------------------------------------------------------------
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Write helper (PUT/PATCH/DELETE) that mirrors armFetch's host guard but keeps
+// the parsed error body so callers can surface ARM's message verbatim.
+async function armWrite(method, url, body, extraHeaders = {}) {
+ if (!url.startsWith(ARM_BASE)) {
+ throw new Error(`Refusing to call non-ARM URL: ${url}`);
+ }
+ const token = await getToken();
+ const headers = { Authorization: `Bearer ${token}` };
+ Object.assign(headers, extraHeaders);
+ if (body !== undefined) headers["Content-Type"] = "application/json";
+ const res = await fetch(url, {
+ method,
+ headers,
+ body: body !== undefined ? JSON.stringify(body) : undefined,
+ });
+ const text = await res.text();
+ let parsed;
+ try { parsed = text ? JSON.parse(text) : undefined; } catch { parsed = text; }
+ if (!res.ok) {
+ const msg = parsed?.error?.message ?? parsed?.message ?? text ?? `HTTP ${res.status}`;
+ const err = new Error(`ARM ${method} ${res.status}: ${String(msg).slice(0, 300)}`);
+ err.status = res.status;
+ throw err;
+ }
+ return parsed;
+}
+
+/**
+ * List resource groups in a subscription (sorted by name).
+ */
+export async function listResourceGroups(subscriptionId) {
+ const token = await getToken();
+ const url = `https://management.azure.com/subscriptions/${armSegment(subscriptionId)}/resourcegroups?api-version=${RG_API_VERSION}`;
+ const items = await paginateAll(url, token);
+ return items
+ .map((rg) => ({ name: rg.name, location: rg.location }))
+ .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Create a resource group without updating an existing group on a name race.
+ */
+export async function createResourceGroup(subscriptionId, name, location) {
+ const url = `https://management.azure.com/subscriptions/${armSegment(subscriptionId)}/resourcegroups/${armSegment(name)}?api-version=${RG_API_VERSION}`;
+ return armWrite("PUT", url, { location }, { "If-None-Match": "*" });
+}
+
+/**
+ * List user-assigned managed identities across a subscription (sorted by name).
+ */
+export async function listUserAssignedIdentities(subscriptionId) {
+ const token = await getToken();
+ const url = `https://management.azure.com/subscriptions/${armSegment(subscriptionId)}/providers/Microsoft.ManagedIdentity/userAssignedIdentities?api-version=${MSI_API_VERSION}`;
+ const items = await paginateAll(url, token);
+ return items
+ .map((id) => {
+ const parts = String(id.id).split("/");
+ const rgIdx = parts.findIndex((p) => p.toLowerCase() === "resourcegroups");
+ return {
+ id: id.id,
+ name: id.name,
+ resourceGroup: rgIdx >= 0 ? parts[rgIdx + 1] || "" : "",
+ location: id.location || "",
+ };
+ })
+ .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Check whether a connector namespace name is free in the given resource group.
+ * Returns true when available (ARM 404), false when taken (200). Uses fetch
+ * directly so the 404 isn't thrown the way armFetch would.
+ */
+export async function checkConnectorGatewayNameAvailable(subscriptionId, resourceGroup, gatewayName) {
+ const token = await getToken();
+ const url = `${buildBaseUrl(subscriptionId, resourceGroup, gatewayName)}?api-version=${API_VERSION}`;
+ const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+ if (res.status === 404) return true;
+ if (res.ok) return false;
+ const body = await res.text();
+ throw new Error(`ARM ${res.status}: ${body.slice(0, 200)}`);
+}
+
+// ARM `identity` block — mirrors the portal's buildIdentityPayload so the PUT
+// body is always explicit ({ type: "None" } when nothing is configured).
+export function buildGatewayIdentity(enableSystem, userAssignedIds = []) {
+ const hasUser = userAssignedIds.length > 0;
+ const type = enableSystem && hasUser
+ ? "SystemAssigned,UserAssigned"
+ : enableSystem
+ ? "SystemAssigned"
+ : hasUser
+ ? "UserAssigned"
+ : "None";
+ const identity = { type };
+ if (hasUser) {
+ identity.userAssignedIdentities = Object.fromEntries(userAssignedIds.map((id) => [id, {}]));
+ }
+ return identity;
+}
+
+export async function waitForProvisioning(initialResult, gatewayName, fetchLatest, {
+ maxPolls = 60,
+ delay = () => sleep(3000),
+} = {}) {
+ let result = initialResult;
+ let state;
+ for (let poll = 0; poll <= maxPolls; poll++) {
+ state = result?.properties?.provisioningState;
+ if (state === "Succeeded") return result;
+ if (state === "Failed" || state === "Canceled") {
+ throw new Error(`Provisioning ${state} for "${gatewayName}".`);
+ }
+ if (poll === maxPolls) break;
+ await delay();
+ result = await fetchLatest();
+ }
+ throw new Error(`Provisioning timed out for "${gatewayName}" (last state: ${state ?? "unknown"}).`);
+}
+
+/**
+ * Create a connector namespace and poll until the
+ * provisioningState reaches a terminal value. Throws on Failed/Canceled.
+ * Returns the final resource object.
+ */
+export async function createConnectorGateway(subscriptionId, resourceGroup, gatewayName, { location, identity }) {
+ const token = await getToken();
+ const url = `${buildBaseUrl(subscriptionId, resourceGroup, gatewayName)}?api-version=${API_VERSION}`;
+ const body = { location, properties: {}, identity };
+ const result = await armWrite("PUT", url, body, { "If-None-Match": "*" });
+ // ~3 min ceiling (60 * 3s). A 202 may have no body, so every state other
+ // than explicit Succeeded enters the polling path.
+ return waitForProvisioning(result, gatewayName, () => armFetch(url, token));
+}
diff --git a/extensions/connector-namespaces/assets/preview-connected.png b/extensions/connector-namespaces/assets/preview-connected.png
new file mode 100644
index 00000000..4050d878
Binary files /dev/null and b/extensions/connector-namespaces/assets/preview-connected.png differ
diff --git a/extensions/connector-namespaces/assets/preview.png b/extensions/connector-namespaces/assets/preview.png
new file mode 100644
index 00000000..259e2794
Binary files /dev/null and b/extensions/connector-namespaces/assets/preview.png differ
diff --git a/extensions/connector-namespaces/catalog.mjs b/extensions/connector-namespaces/catalog.mjs
new file mode 100644
index 00000000..79f4165c
--- /dev/null
+++ b/extensions/connector-namespaces/catalog.mjs
@@ -0,0 +1,70 @@
+// Catalog — fetches MCP connectors from the gateway.
+//
+// The gateway exposes ~1600 managed APIs (the full Logic Apps connector
+// catalog). MCP servers are a small subset (~43) and there is no `kind` or
+// capability flag that distinguishes them. The only reliable signal is the
+// string "mcp" appearing in the API's name OR its display name — and those are
+// genuinely independent signals: `workiqsharepoint` has no "mcp" in its name
+// (display name "Work IQ SharePoint MCP"), while `hginsightsmcp` has "mcp" in
+// its name but a display name of "HG Insights Connect". Matching either keeps
+// the full set without an allowlist that has to be hand-maintained.
+
+import { listManagedApis } from "./armClient.mjs";
+import { CATEGORY } from "./categories.mjs";
+
+function isMcpServer(api) {
+ const name = api.name || "";
+ const displayName = api.properties?.generalInformation?.displayName || "";
+ return /mcp/i.test(name) || /mcp/i.test(displayName);
+}
+
+// Microsoft first-party servers (a365*/d365*/workiq* names, or a Microsoft-
+// branded display name) group under "Microsoft"; everything else is a partner
+// server. Derived rather than hardcoded so new servers categorize themselves.
+function categoryFor(name, displayName) {
+ const n = (name || "").toLowerCase();
+ const d = (displayName || "").toLowerCase();
+ const isMicrosoft =
+ /^(a365|d365|workiq)/.test(n) ||
+ d.startsWith("microsoft") ||
+ d.startsWith("work iq") ||
+ d.startsWith("dynamics 365");
+ return isMicrosoft ? CATEGORY.microsoft : CATEGORY.partner;
+}
+
+let cachedCatalog = null;
+let cacheKey = null;
+
+export function invalidateCache() {
+ cachedCatalog = null;
+ cacheKey = null;
+}
+
+export async function fetchCatalog(subscriptionId, resourceGroup, gatewayName) {
+ const key = `${subscriptionId}/${resourceGroup}/${gatewayName}`;
+ if (cachedCatalog && cacheKey === key) return cachedCatalog;
+
+ const apis = await listManagedApis(subscriptionId, resourceGroup, gatewayName);
+
+ const catalog = apis
+ .filter(isMcpServer)
+ .map((a) => {
+ const props = a.properties || {};
+ const general = props.generalInformation || {};
+ const metadata = props.metadata || {};
+ const displayName = general.displayName || a.name;
+ return {
+ id: a.name,
+ apiName: a.name,
+ displayName,
+ description: general.description || "",
+ iconUri: general.iconUri || "",
+ brandColor: metadata.brandColor || "",
+ category: categoryFor(a.name, displayName),
+ };
+ });
+
+ cachedCatalog = catalog;
+ cacheKey = key;
+ return catalog;
+}
diff --git a/extensions/connector-namespaces/categories.mjs b/extensions/connector-namespaces/categories.mjs
new file mode 100644
index 00000000..57cd9592
--- /dev/null
+++ b/extensions/connector-namespaces/categories.mjs
@@ -0,0 +1,15 @@
+// Catalog category values.
+//
+// `category` is a routing key, not display text: the renderer partitions catalog
+// items into the Microsoft vs Partners sections by comparing against these exact
+// values (see renderCatalogHtml in renderer.mjs). Kept as a frozen enum here,
+// rather than free-form strings scattered across the producer, renderer, and
+// tests, so the routing contract lives in one place.
+//
+// Zero-dependency on purpose: renderer.mjs imports this, and renderer.test.mjs
+// loads renderer.mjs as a pure string-rendering gate. Sourcing the enum from
+// catalog.mjs instead would drag armClient.mjs (the ARM SDK) into that gate.
+export const CATEGORY = Object.freeze({
+ microsoft: "Microsoft",
+ partner: "Partners",
+});
diff --git a/extensions/connector-namespaces/copilot-extension.json b/extensions/connector-namespaces/copilot-extension.json
new file mode 100644
index 00000000..3949dbe4
--- /dev/null
+++ b/extensions/connector-namespaces/copilot-extension.json
@@ -0,0 +1,4 @@
+{
+ "name": "connector-namespaces",
+ "version": 1
+}
diff --git a/extensions/connector-namespaces/createPage.mjs b/extensions/connector-namespaces/createPage.mjs
new file mode 100644
index 00000000..3eb86659
--- /dev/null
+++ b/extensions/connector-namespaces/createPage.mjs
@@ -0,0 +1,403 @@
+// Renderer for the "Create connector namespace" wizard page. Mirrors the
+// portal's CreateConnectorGatewayPage: subscription -> resource group
+// (existing or new) -> region -> name (live availability) -> managed identity
+// (system + user-assigned) -> real ARM provisioning.
+
+import { baseStyles, brandMark } from "./renderer.mjs";
+
+function esc(s) {
+ return String(s || "").replace(/[&<>"']/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" }[c]));
+}
+
+// Connector namespace regions — kept in sync with the portal's
+// CONNECTOR_NAMESPACE_REGIONS list (constants.ts).
+const REGIONS = [
+ ["australiaeast", "Australia East"], ["brazilsouth", "Brazil South"],
+ ["canadacentral", "Canada Central"], ["canadaeast", "Canada East"],
+ ["centralindia", "Central India"], ["centralus", "Central US"],
+ ["eastasia", "East Asia"], ["eastus", "East US"], ["eastus2", "East US 2"],
+ ["francecentral", "France Central"], ["germanywestcentral", "Germany West Central"],
+ ["italynorth", "Italy North"], ["japaneast", "Japan East"],
+ ["koreacentral", "Korea Central"], ["northcentralus", "North Central US"],
+ ["northeurope", "North Europe"], ["norwayeast", "Norway East"],
+ ["polandcentral", "Poland Central"], ["southafricanorth", "South Africa North"],
+ ["southcentralus", "South Central US"], ["southindia", "South India"],
+ ["southeastasia", "Southeast Asia"], ["spaincentral", "Spain Central"],
+ ["swedencentral", "Sweden Central"], ["switzerlandnorth", "Switzerland North"],
+ ["uaenorth", "UAE North"], ["uksouth", "UK South"],
+ ["westcentralus", "West Central US"], ["westus2", "West US 2"],
+ ["westus3", "West US 3"],
+];
+
+const DEFAULT_REGION = "eastus";
+
+export function renderCreateNamespaceHtml(subscriptions, preselectedSub = "", capabilityToken = "") {
+ const subOptions = subscriptions.map((s) =>
+ ``
+ ).join("");
+
+ const regionOptions = REGIONS.map(([v, l]) =>
+ ``
+ ).join("");
+
+ return `
+
+Canvas structure output
", + "", + "```text", + canvasStructureOutput, + "```", + "", + "
+
+
+${brandMark(28, "create")}Create connector namespace
+Provisions a real Azure connector namespace (Microsoft.Web/connectorGateways) in your subscription.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Pick the resource group the namespace will live in.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+`;
+}
diff --git a/extensions/connector-namespaces/extension.mjs b/extensions/connector-namespaces/extension.mjs
new file mode 100644
index 00000000..fe6f502e
--- /dev/null
+++ b/extensions/connector-namespaces/extension.mjs
@@ -0,0 +1,101 @@
+// Canvas extension entry point — MCP Connectors browser.
+
+import { joinSession, createCanvas } from "@github/copilot-sdk/extension";
+import { getServerConfig, startServer, stopServer } from "./server.mjs";
+import { getSavedConfig, loadSavedConfig, saveConfig } from "./state.mjs";
+import { fetchCatalog } from "./catalog.mjs";
+import { getInstalledState, openInBrowser, setWorkspaceRoot } from "./install.mjs";
+import { buildSandboxUrl, resolveSandboxConnector } from "./sandbox.mjs";
+
+// Load any previously saved connector namespace config on startup
+loadSavedConfig();
+
+async function openPlayground(server, instanceId) {
+ const config = instanceId ? getServerConfig(instanceId) : getSavedConfig();
+ if (!config) return { opened: false, reason: "no_namespace_configured" };
+ const catalog = await fetchCatalog(config.subscriptionId, config.resourceGroup, config.gatewayName);
+ const installedState = await getInstalledState(config);
+ const resolved = resolveSandboxConnector(catalog, installedState, server);
+ if (!resolved.connector) return { opened: false, ...resolved };
+ const url = buildSandboxUrl(config, resolved.connector.id);
+ await openInBrowser(url);
+ return { opened: true, server: resolved.connector, url };
+}
+
+const session = await joinSession({
+ tools: [
+ {
+ name: "connector_namespaces_open_playground",
+ description: "Open a named connector from My MCPs in the Azure Connector Namespace playground.",
+ parameters: {
+ type: "object",
+ properties: {
+ server: {
+ type: "string",
+ description: "Connector display name or server ID from My MCPs",
+ },
+ },
+ required: ["server"],
+ },
+ handler: async ({ server }) => JSON.stringify(await openPlayground(server)),
+ },
+ ],
+ canvases: [
+ createCanvas({
+ id: "connector-namespaces",
+ displayName: "MCP Connectors",
+ description: "Browse, connect, and open MCP connectors in the Azure Connector Namespace Sandbox.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ subscriptionId: { type: "string", description: "Azure subscription ID (optional \u2014 if omitted, uses saved config or shows picker)" },
+ resourceGroup: { type: "string", description: "Resource group name" },
+ gatewayName: { type: "string", description: "Connector namespace name" },
+ },
+ },
+ actions: [
+ {
+ name: "open_sandbox",
+ description: "Open a named connector from My MCPs in the Azure Connector Namespace Sandbox",
+ inputSchema: {
+ type: "object",
+ properties: {
+ server: {
+ type: "string",
+ description: "Connector display name or server ID from My MCPs",
+ },
+ },
+ required: ["server"],
+ },
+ handler: async (ctx) => openPlayground(ctx.input.server, ctx.instanceId),
+ },
+ ],
+ open: async (ctx) => {
+ let config;
+ // If explicit input provided, use it and save for future
+ if (ctx.input && ctx.input.subscriptionId && ctx.input.resourceGroup && ctx.input.gatewayName) {
+ config = {
+ subscriptionId: ctx.input.subscriptionId,
+ resourceGroup: ctx.input.resourceGroup,
+ gatewayName: ctx.input.gatewayName,
+ };
+ saveConfig(config);
+ }
+ // A saved config seeds a new panel only. Rehydrating an existing
+ // panel keeps its active namespace even if another panel changed
+ // the persisted default.
+ const entry = await startServer(
+ ctx.instanceId,
+ config ? { config } : { defaultConfig: getSavedConfig() },
+ );
+ return { title: "MCP Connectors", url: entry.url };
+ },
+ onClose: async (ctx) => {
+ await stopServer(ctx.instanceId);
+ },
+ }),
+ ],
+});
+
+// Tell the install pipeline where the workspace .mcp.json lives (if any).
+setWorkspaceRoot(session.workspacePath);
diff --git a/extensions/connector-namespaces/install.mjs b/extensions/connector-namespaces/install.mjs
new file mode 100644
index 00000000..74264d6f
--- /dev/null
+++ b/extensions/connector-namespaces/install.mjs
@@ -0,0 +1,1007 @@
+// Install flow — creates connection, handles OAuth, creates MCP server config,
+// mints API key, and writes to ~/.copilot/mcp-config.json.
+
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { getToken, assertArmHost, armSegment, resolveSystemExecutable } from "./armClient.mjs";
+
+const COPILOT_HOME = process.env.COPILOT_HOME || join(homedir(), ".copilot");
+
+// Two scopes the Copilot CLI reads MCP servers from:
+// profile -> ~/.copilot/mcp-config.json (private, follows you everywhere)
+// workspace ->
+
+${notice ? `${brandMark(30, "setup")}Select a Connector Namespace
+Choose which connector namespace to browse. This choice is saved for future sessions.
+${esc(notice)}
` : ""}
+
+
+
+
+
+
+
+
+
+
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+const CSS_HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+
+function iconBackgroundStyle(brandColor) {
+ const color = String(brandColor || "").trim();
+ return CSS_HEX_COLOR.test(color) ? ` style="background:${color}22"` : "";
+}
+
+export function renderCatalogHtml(instanceId, catalog, { filter, category, source, config }, capabilityToken = "") {
+ const renderItem = (c) => {
+ // Items carry their home grid so hydrateState can move them into
+ // "My MCPs" when added and back to Microsoft/Partner on remove.
+ const home = c.category === CATEGORY.microsoft ? "microsoft" : "partner";
+ const icon = c.iconUri
+ ? `Select a subscription to see available connector namespaces.
+${icon}${btn}
`;
+ };
+
+ const byName = (a, b) => a.displayName.localeCompare(b.displayName);
+ const microsoft = catalog.filter((c) => c.category === CATEGORY.microsoft).sort(byName);
+ const partner = catalog.filter((c) => c.category !== CATEGORY.microsoft).sort(byName);
+
+ const section = (key, title, rows, { collapsed, hidden }) => {
+ const cls = ["section", "collapsible"];
+ if (collapsed) cls.push("collapsed");
+ if (hidden) cls.push("is-hidden");
+ const n = rows.length;
+ return `${esc(c.displayName)}
${esc(c.description)}
`
+ + ``
+ + `
`;
+ };
+
+ // Server paints the first-run layout: My MCPs hidden+empty (filled by
+ // hydrateState), Microsoft expanded so there's something to browse, Partner
+ // collapsed. updateSections() flips to the steady layout on the first hydrate
+ // if anything is already added.
+ let sectionsHtml =
+ section("mine", "My MCPs", [], { collapsed: false, hidden: true }) +
+ section("microsoft", "Microsoft", microsoft, { collapsed: false, hidden: microsoft.length === 0 }) +
+ section("partner", "Partners", partner, { collapsed: true, hidden: partner.length === 0 });
+
+ if (!catalog.length) {
+ sectionsHtml = `${rows.map(renderItem).join("")}
`
+ + `No connectors available.
`;
+ }
+
+ return `
+
+
+
+
+
+ ${brandMark(24, "cat")}Connectors
+Namespace
+ ${esc(config.gatewayName)} · RG ${esc(config.resourceGroup)}
+
+
+
+
+
+
+
+
+
+${sectionsHtml}
+
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export function renderErrorHtml(message) {
+ return `
+Error
${esc(message)}
+`;
+}
+
+// ---------------------------------------------------------------------------
+function esc(s) {
+ return String(s ?? "").replace(/[&<>"']/g, (c) => ({"&":"&","<":"<",">":">",'"':""","'":"'"}[c]));
+}
diff --git a/extensions/connector-namespaces/renderer.test.mjs b/extensions/connector-namespaces/renderer.test.mjs
new file mode 100644
index 00000000..d0c464e4
--- /dev/null
+++ b/extensions/connector-namespaces/renderer.test.mjs
@@ -0,0 +1,393 @@
+// Regression guards for the connector-catalog renderer.
+//
+// Run: node --test extensions/connector-namespaces/renderer.test.mjs
+//
+// These tests exist because two UX bugs kept coming back:
+// 1. A `@media (prefers-reduced-motion: reduce)` rule froze functional
+// loaders without a visible fallback. Reduced motion now stops the
+// animation while forcing each loader into a visible static busy state;
+// nearby text continues to communicate progress.
+// 2. The "Restart your Copilot session" banner ignoring Dismiss. The real
+// root cause was CSS specificity: `.restart-banner{display:flex}` is an
+// author rule with the same (0,1,0) specificity as the UA
+// `[hidden]{display:none}` rule, so it overrode the hidden attribute and
+// `restartBanner.hidden=true` did nothing. The fix is a global
+// `[hidden]{display:none !important}` reset. A client-side
+// `restartDismissed` flag also keeps a late hydrateState() from re-showing
+// it. The guards below fail if either the CSS reset or the JS gate
+// disappears.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { baseStyles, renderCatalogHtml, renderSetupHtml } from "./renderer.mjs";
+import { renderCreateNamespaceHtml } from "./createPage.mjs";
+import { CATEGORY } from "./categories.mjs";
+
+// Pull the balanced body of the prefers-reduced-motion media block out of a
+// stylesheet string (non-greedy regex can't handle the nested rule braces).
+// CSS comments are stripped so the guards test declarations rather than prose.
+function reducedMotionBlock(css) {
+ const start = css.indexOf("@media (prefers-reduced-motion: reduce)");
+ if (start === -1) return null;
+ const open = css.indexOf("{", start);
+ if (open === -1) return null;
+ let depth = 0;
+ for (let i = open; i < css.length; i++) {
+ if (css[i] === "{") depth++;
+ else if (css[i] === "}" && --depth === 0) {
+ return css.slice(open + 1, i).replace(/\/\*[\s\S]*?\*\//g, "");
+ }
+ }
+ return null;
+}
+
+function catalogHtml() {
+ return renderCatalogHtml("test-instance", [], {
+ filter: "",
+ category: "all",
+ source: "",
+ config: { subscriptionId: "sub", gatewayName: "ns", resourceGroup: "rg" },
+ });
+}
+
+test("setup subscription label names its select", () => {
+ const html = renderSetupHtml([], "", "token");
+ assert.match(html, /