diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json index 536f0f852..cc7aab809 100644 --- a/.github/plugin/marketplace.json +++ b/.github/plugin/marketplace.json @@ -1428,6 +1428,12 @@ "sha": "6e51924cb249e2941de005d59f1ac6f768477b98" } }, + { + "name": "version-sentinel", + "source": "plugins/version-sentinel", + "description": "Dependency-version guardrail for AI coding agents. Verifies every added or bumped package version against its upstream registry (npm, PyPI, crates.io, NuGet) so stale, hallucinated, or compromised versions never reach your manifests.", + "version": "0.4.0" + }, { "name": "visual-pr", "source": "plugins/visual-pr", diff --git a/agents/version-reviewer.agent.md b/agents/version-reviewer.agent.md new file mode 100644 index 000000000..d007c4fbd --- /dev/null +++ b/agents/version-reviewer.agent.md @@ -0,0 +1,38 @@ +--- +description: 'Release-audit reviewer that runs the version-sentinel dependency-freshness check across repo manifests (npm, pip, pyproject, Cargo, NuGet), interprets DRIFT vs intentional-pin rows, and produces a structured, read-only report with recommended actions.' +name: 'Version Reviewer' +tools: ['codebase', 'search', 'fetch', 'terminalCommand'] +--- + +# Version Reviewer + +You are the version-sentinel release-audit reviewer. Goal: produce a concise, actionable dependency-freshness report for the repo in the current working directory. + +## Prerequisites + +This agent expects the version-sentinel scripts to be present in the workspace (`scripts/check-versions.sh`, `scripts/vs-record.sh`). They ship with the upstream project at [KSEGIT/Version-Sentinel](https://github.com/KSEGIT/Version-Sentinel) (MIT). If the scripts are missing, tell the user where to get them and stop. + +## What to run + +1. `bash scripts/check-versions.sh`. Capture full output. +2. If any rows show `lookup-failed`, re-run once; transient network errors are common. Don't retry more than twice. + +## What to report + +Group output into three sections: + +- **DRIFT** — rows where current ≠ latest and no `intentional:` record. For each: ecosystem, pkg, current, latest, registry link, and the suggested `bash scripts/vs-record.sh ...` command to run before bumping. +- **intentional-pin** — rows the user has deliberately pinned. List with the recorded reason (pulled from the sidecar `.version-sentinel/checks.json`). Flag any pins older than 30 days as "re-review recommended". +- **lookup-failed** — registry fetch failed. List with the registry URL the user can check manually. + +## Rules + +- Do not modify any files. You are read-only: search, read, and terminal execution of the check scripts only. +- If the repo has no recognized manifests, say so and exit. +- Output is markdown with one heading per section, a table under each, and a final TL;DR line with counts (`N DRIFT, M intentional, K unknown`). +- Keep the full report under 400 words. +- If there are 0 DRIFT and 0 lookup-failed, end with: `READY TO RELEASE`. + +--- + +Adapted from [version-sentinel](https://github.com/KSEGIT/Version-Sentinel) (MIT License). diff --git a/docs/README.agents.md b/docs/README.agents.md index 21ad59d9e..ffb5114cd 100644 --- a/docs/README.agents.md +++ b/docs/README.agents.md @@ -239,6 +239,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to | [Ultimate Transparent Thinking Beast Mode](../agents/Ultimate-Transparent-Thinking-Beast-Mode.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2FUltimate-Transparent-Thinking-Beast-Mode.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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%2FUltimate-Transparent-Thinking-Beast-Mode.agent.md) | Ultimate Transparent Thinking Beast Mode | | | [Universal Janitor](../agents/janitor.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fjanitor.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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%2Fjanitor.agent.md) | Perform janitorial tasks on any codebase including cleanup, simplification, and tech debt remediation. | | | [Universal PR Comment Addresser](../agents/address-comments.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Faddress-comments.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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%2Faddress-comments.agent.md) | Address PR comments | | +| [Version Reviewer](../agents/version-reviewer.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fversion-reviewer.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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%2Fversion-reviewer.agent.md) | Release-audit reviewer that runs the version-sentinel dependency-freshness check across repo manifests (npm, pip, pyproject, Cargo, NuGet), interprets DRIFT vs intentional-pin rows, and produces a structured, read-only report with recommended actions. | | | [VS Code Insiders Accessibility Tracker](../agents/insiders-a11y-tracker.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Finsiders-a11y-tracker.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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%2Finsiders-a11y-tracker.agent.md) | Specialized agent for tracking and analyzing accessibility improvements in VS Code Insiders builds | | | [VSCode Tour Expert](../agents/code-tour.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fcode-tour.agent.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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%2Fcode-tour.agent.md) | Expert agent for creating and maintaining VSCode CodeTour files with comprehensive schema support and best practices | | | [WG Code Alchemist](../agents/wg-code-alchemist.agent.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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 | | diff --git a/docs/README.plugins.md b/docs/README.plugins.md index 5511d4069..b75f9709d 100644 --- a/docs/README.plugins.md +++ b/docs/README.plugins.md @@ -97,4 +97,5 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-plugins) for guidelines on how t | [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 | | [uizze](../plugins/uizze/README.md) | Stop generic UI from shipping. Ground GitHub Copilot in 800,000+ real web and iOS screens, write a product-specific design contract, and enforce a hard finish gate. | 1 items | ui, design, frontend, ios, web, design-review, quality-gate | +| [version-sentinel](../plugins/version-sentinel/README.md) | Dependency-version guardrail for AI coding agents. Verifies every added or bumped package version against its upstream registry (npm, PyPI, crates.io, NuGet) so stale, hallucinated, or compromised versions never reach your manifests. | 2 items | dependencies, version-check, supply-chain, guardrail, audit | | [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 46d2bb38b..c4f99e220 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -408,6 +408,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [update-specification](../skills/update-specification/SKILL.md)
`gh skills install github/awesome-copilot update-specification` | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | None | | [vardoger-analyze](../skills/vardoger-analyze/SKILL.md)
`gh skills install github/awesome-copilot vardoger-analyze` | Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'. | None | | [vcpkg](../skills/vcpkg/SKILL.md)
`gh skills install github/awesome-copilot vcpkg` | Guide for setting up vcpkg in C++ projects, managing dependency versions, and cross-compiling. Covers manifest initialization, CMake and Visual Studio integration, classic-to-manifest migration, version pinning, baselines, overrides, triplets, and cross-compilation. Use when a user is working with vcpkg project setup, installation, version management, or cross-platform builds. For specialized tasks, additional references cover custom registries and overlay ports (references/registries.md), CI/CD and binary caching (references/ci.md), and troubleshooting and dependency lifecycle (references/troubleshooting.md). | `references/ci.md`
`references/registries.md`
`references/troubleshooting.md` | +| [version-sentinel](../skills/version-sentinel/SKILL.md)
`gh skills install github/awesome-copilot version-sentinel` | Verify dependency versions against upstream registries before adding, bumping, or changing them in package.json, requirements*.txt, constraints*.txt, pyproject.toml, Cargo.toml, *.csproj, *.fsproj, or *.vbproj. Use this skill when:
- A version-sentinel PreToolUse hook blocks a manifest edit or install command with `BLOCKED: version-sentinel`
- Adding or upgrading any third-party dependency and you need to confirm the version actually exists upstream
- Recording a deliberate version pin (CVE lock, compatibility constraint) so audits don't flag it as drift
- Auditing dependency freshness before tagging a release
- Any request like "verify this package version", "is this the latest lodash", or "check dependency drift" | None | | [vscode-ext-commands](../skills/vscode-ext-commands/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-commands` | Guidelines for contributing commands in VS Code extensions. Indicates naming convention, visibility, localization and other relevant attributes, following VS Code extension development guidelines, libraries and good practices | None | | [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md)
`gh skills install github/awesome-copilot vscode-ext-localization` | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None | | [web-design-reviewer](../skills/web-design-reviewer/SKILL.md)
`gh skills install github/awesome-copilot web-design-reviewer` | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`
`references/visual-checklist.md` | diff --git a/plugins/version-sentinel/.github/plugin/plugin.json b/plugins/version-sentinel/.github/plugin/plugin.json new file mode 100644 index 000000000..da722c868 --- /dev/null +++ b/plugins/version-sentinel/.github/plugin/plugin.json @@ -0,0 +1,25 @@ +{ + "name": "version-sentinel", + "description": "Dependency-version guardrail for AI coding agents. Verifies every added or bumped package version against its upstream registry (npm, PyPI, crates.io, NuGet) so stale, hallucinated, or compromised versions never reach your manifests.", + "version": "0.4.0", + "keywords": [ + "dependencies", + "version-check", + "supply-chain", + "guardrail", + "audit" + ], + "author": { + "name": "KSEGIT", + "url": "https://github.com/KSEGIT" + }, + "homepage": "https://github.com/KSEGIT/Version-Sentinel", + "repository": "https://github.com/github/awesome-copilot", + "license": "MIT", + "agents": [ + "./agents/version-reviewer.md" + ], + "skills": [ + "./skills/version-sentinel/" + ] +} diff --git a/plugins/version-sentinel/README.md b/plugins/version-sentinel/README.md new file mode 100644 index 000000000..1392b3579 --- /dev/null +++ b/plugins/version-sentinel/README.md @@ -0,0 +1,28 @@ +# Version Sentinel + +A dependency-version guardrail for AI coding agents. Before any dependency is added, bumped, downgraded, or installed, the intended version is verified against its upstream registry (npm, PyPI, crates.io, NuGet) and the check is recorded — so stale, hallucinated, or compromised package versions never reach your manifests. + +## Why This Exists + +AI coding agents routinely suggest package versions that are outdated, never existed, or were yanked. Version Sentinel turns "the model said so" into "verified against the registry within the last 24 hours", and makes deliberate pins explicit so audits can tell them apart from accidental drift. + +## What's Included + +| Component | Type | Description | +|-----------|------|-------------| +| `version-sentinel` | Skill | The verification workflow: look up the version upstream, record the check in the `.version-sentinel/checks.json` sidecar, then proceed. Also covers intentional pins and pre-release drift audits. | +| `Version Reviewer` | Agent | Read-only release-audit reviewer. Runs the drift check across all repo manifests, groups results into DRIFT / intentional-pin / lookup-failed, and ends with a release-readiness verdict. | + +## Hooks and Scripts + +The blocking PreToolUse hooks and the guardrail scripts (`vs-record.sh`, `check-versions.sh`, manifest/install detectors) that this plugin's skill and agent drive live in the upstream repository, which also ships GitHub Copilot–ready hook configuration (`.github/hooks/version-sentinel.json`) and two prompt files (`vs-record.prompt.md`, `check-versions.prompt.md`): + +**[KSEGIT/Version-Sentinel](https://github.com/KSEGIT/Version-Sentinel)** — MIT License + +## How It Works + +1. You (or the agent) attempt a manifest edit or install command. +2. The hook blocks it until the version is verified upstream. +3. The agent looks up the latest version on the registry and records the check: `bash scripts/vs-record.sh npm lodash 4.17.21 https://www.npmjs.com/package/lodash` +4. The operation proceeds. Deliberate pins are recorded as `intentional:` and show as `intentional-pin`, not `DRIFT`, in audits. +5. Before a release, `bash scripts/check-versions.sh` (or the Version Reviewer agent) reports drift across npm, pip/pyproject, Cargo, and NuGet manifests. diff --git a/skills/version-sentinel/SKILL.md b/skills/version-sentinel/SKILL.md new file mode 100644 index 000000000..3544bc065 --- /dev/null +++ b/skills/version-sentinel/SKILL.md @@ -0,0 +1,74 @@ +--- +name: version-sentinel +description: | + Verify dependency versions against upstream registries before adding, bumping, or changing them in package.json, requirements*.txt, constraints*.txt, pyproject.toml, Cargo.toml, *.csproj, *.fsproj, or *.vbproj. Use this skill when: + - A version-sentinel PreToolUse hook blocks a manifest edit or install command with `BLOCKED: version-sentinel` + - Adding or upgrading any third-party dependency and you need to confirm the version actually exists upstream + - Recording a deliberate version pin (CVE lock, compatibility constraint) so audits don't flag it as drift + - Auditing dependency freshness before tagging a release + - Any request like "verify this package version", "is this the latest lodash", or "check dependency drift" +--- + +# Version Sentinel — Dependency-Version Guardrail Workflow + +`version-sentinel` blocks dependency changes until you have verified the package version against its upstream registry. This prevents stale, hallucinated, or compromised versions from reaching your manifests. Checks are recorded in a `.version-sentinel/checks.json` sidecar and expire after a freshness window (default 24h). + +> The guardrail scripts and hooks ship with the upstream project: [KSEGIT/Version-Sentinel](https://github.com/KSEGIT/Version-Sentinel) (MIT). This skill explains the workflow those scripts enforce; on hosts without hook support, follow the same flow voluntarily before any dependency change. + +## When you see a BLOCKED message + +If a tool call exits 2 with `BLOCKED: version-sentinel`, you must: + +1. **Look up the latest version** on the upstream registry via web search or fetch: + - npm: `https://www.npmjs.com/package/` + - pip / pyproject: `https://pypi.org/project//` + - cargo: `https://crates.io/crates/` + - csproj (NuGet): `https://www.nuget.org/packages/` + +2. **Record the check.** Run in the terminal: + + ```bash + bash scripts/vs-record.sh + ``` + + The source must be an `http(s)://` URL you actually consulted, or `intentional:` for deliberate pins. Examples: + + ```bash + bash scripts/vs-record.sh npm lodash 4.17.21 https://www.npmjs.com/package/lodash + bash scripts/vs-record.sh csproj Serilog 3.1.1 "intentional: CVE lock pending audit" + ``` + +3. **Retry the original edit or install.** With a fresh entry on record, the hook lets the tool call through. + +## Intentional non-latest pins + +If you genuinely intend an older version (CVE mitigation, compatibility, private registry), record it with an `intentional:` reason as shown above. This passes the hook and is flagged as `intentional-pin` (not `DRIFT`) in audit output. + +## Auditing before a release + +Run: + +```bash +bash scripts/check-versions.sh +``` + +It scans manifests within 4 directory levels of the current directory, compares each dependency against its upstream registry, and reports drift. Interpret the output as: + +- **DRIFT** — current ≠ latest with no `intentional:` record. Look up the latest version and record it with `vs-record.sh` before bumping. +- **intentional-pin** — deliberate pin with a recorded reason; no action needed unless the pin is stale (re-review pins older than 30 days). +- **lookup-failed** — registry fetch failed; re-run once, then check the registry URL manually. + +## What NOT to do + +- Don't fabricate a source URL you didn't actually consult — the contract assumes honest reporting. +- Don't try to bypass the hook with `git commit --no-verify` or similar — the hook runs on file edits and terminal commands, not on git. +- Don't set `VS_DISABLE=1` without the user's awareness; that's an escape hatch for throwaway sessions, not normal flow. + +## Related prompts + +The upstream repository also ships two Copilot prompt files you can copy into `.github/prompts/`: + +- `vs-record.prompt.md` — records a verified version check in the sidecar (wraps `vs-record.sh`). +- `check-versions.prompt.md` — runs the registry-drift audit and interprets the results (wraps `check-versions.sh`). + +Source: [KSEGIT/Version-Sentinel](https://github.com/KSEGIT/Version-Sentinel) (MIT License).