diff --git a/AGENTS.md b/AGENTS.md index 1c385b5..573f948 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,7 +69,9 @@ Use this check: ## Task Route - Before changing versions, dependencies, packaging or release workflows, read - `Documentation/Architecture/VersioningAndRelease.md` and use its existing project check entry points. + the [organization VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) + for version rules and `Documentation/Reference/Release.md` for release facts + and check entry points. - For repository-native documentation placement, read `Documentation/README.md` before editing. diff --git a/Documentation/Architecture/Documentation.md b/Documentation/Architecture/Documentation.md index eff4974..a37950e 100644 --- a/Documentation/Architecture/Documentation.md +++ b/Documentation/Architecture/Documentation.md @@ -6,9 +6,10 @@ CONTRIBUTING.md describes contributor checks. Current package facts belong in Documentation/Architecture/Package.md; commands, formats and operating detail belong in Documentation/Reference/. -Version and release rules belong in -Documentation/Architecture/VersioningAndRelease.md. Durable transitions or -accepted decisions may have separate history records when needed. +Version rules belong in the +[organization VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md). +[Release](../Reference/Release.md) owns release facts and procedure. Durable +transitions or accepted decisions may have separate history records when needed. GitHub-specific configuration belongs in .github/. This is a declarative package, with no Swift module or public Swift API. DocC is not applicable. diff --git a/Documentation/Architecture/README.md b/Documentation/Architecture/README.md index 0e2315b..fdb1d40 100644 --- a/Documentation/Architecture/README.md +++ b/Documentation/Architecture/README.md @@ -2,5 +2,4 @@ [Package](Package.md) describes the current components, dependencies and ownership boundaries. [Documentation](Documentation.md) describes repository documentation -roles and the API documentation scope. [Versioning and Release](VersioningAndRelease.md) -defines version authority, acceptance and publication. +roles and the API documentation scope. diff --git a/Documentation/Architecture/VersioningAndRelease.md b/Documentation/Architecture/VersioningAndRelease.md deleted file mode 100644 index ed509a0..0000000 --- a/Documentation/Architecture/VersioningAndRelease.md +++ /dev/null @@ -1,82 +0,0 @@ -# Versioning and Release - -This document owns the current version and release rules for -plugin-computer-use. Shared versioning, plugin compatibility, tags, release -contents and recovery rules belong to the organization's -[VERSIONING.md](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md). -The [release guide](../Reference/Release.md) describes this repository's -acceptance and workflow procedure. - -## Components and Version Authority - -| Shipped component | Version meaning | Authoritative source | Derived fields | Update and read-only check | -| --- | --- | --- | --- | --- | -| `computer-use.zip` plugin package | Package version | `version` in `computer-mcp-plugin.toml` | builder and release receipts, version tag, catalog entry, the App's bundled index | Edit the manifest; `release.yml` checks agreement with the tag | -| Manifest and host runtime contract | Plugin API version | `plugin_api` in `computer-mcp-plugin.toml` | release receipt and host compatibility evaluation | Package tests check the declaration; `release.yml` verifies it | - -The archive contains the README, contribution guide, manifest, license, notices, -`skills/` and `Documentation/`. Changes to tests, scripts or workflows alone do -not change the archive. - -## Dependencies and Verified Combinations - -The package is a declaration: it registers the vendor's native Computer Use MCP -client and ships no runtime code. The manifest locates that client by command -name or application bundle, and the vendor owns its installation and caller -authentication. - -The manifest owns this package's plugin API declaration and host compatibility -bounds. A host-version constraint is changed only after validating the package -against the required host. - -The builder needs only the Python 3.11 standard library. CI runs the tests and -build on Python 3.11 and 3.13. - -## Derived Metadata and Drift Checks - -`Scripts/build_package.py` verifies the plugin ID, skips hidden files and Python -caches, rejects links and special files, and produces the same archive bytes -from the same source. `Tests/test_build_package.py` checks the plugin API -declaration and pins the exact archive file set. The builder receipt prints the -ID, version and SHA-256. - -## Candidate, Acceptance and Publication - -The candidate is the `computer-use-plugin-` artifact from a successful -`master` push run of `ci.yml` for a reviewed commit. Acceptance requires a -byte-identical local rebuild, host package validation and installation of that -exact archive, and native catalog discovery with the installed vendor client. -Native actions remain subject to the vendor's caller authentication and system -permissions; acceptance records what was observed and does not assume a working -action path. - -`release.yml` calls the shared release workflow with `Scripts/build-package.sh` -and this repository's exact CI artifact name. Manual acceptance results belong -in the Release notes. After verified publication, its dependent notifier calls -`notify-catalog.yml`. - -The Computer MCP App bundles a copy of this package, pinned by version and -SHA-256 in the App repository's `Resources/PluginArchives/index.json`. Before -the first release, the host may bundle an archive reproducibly built from an -accepted commit before that plugin version is published. A host release -requires the plugin release with the same archive digest to be public first. - -## Evidence Reuse and Invalidation - -The CI artifact name binds the source commit, and the builder receipt binds the -archive SHA-256. An archive whose digest matches the accepted one keeps its -acceptance. Any change to a packaged file produces a new archive that needs the -affected checks again. - -## Entry Points and Artifact Retention - -| Operation | Existing command or explicit manual procedure | Required access | -| --- | --- | --- | -| Version update and check | Edit `computer-mcp-plugin.toml`; `python3 -m unittest discover -s Tests -p 'test_*.py'` | Local checkout | -| Candidate validation and build | `ci.yml`; locally `Scripts/build-package.sh ` | CI or local checkout | -| Release verification and publication | Dispatch `release.yml`, dry run first; manual acceptance in [Release](../Reference/Release.md) | Repository Actions; publication also needs a signed tag and release write access | -| Status and interrupted-run recovery | Rerun failed workflow jobs; follow the shared recovery rules | Repository Actions | -| Cleanup | Delete local output and evidence directories | Local checkout | - -CI keeps candidate artifacts for 14 days. The builder refuses to overwrite a -different archive. Keep local evidence outside the repository. diff --git a/Documentation/README.md b/Documentation/README.md index 2039fa7..a60e629 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -1,8 +1,8 @@ # Documentation - [Architecture](Architecture/README.md): package composition and ownership. -- [Versioning and Release](Architecture/VersioningAndRelease.md): version authority, acceptance and publication rules. -- [Release](Reference/Release.md): publishing a release and notifying the plugin catalog. +- [Release](Reference/Release.md): version sources, compatibility, acceptance and + publication. - [Root manual](../README.md): requirements, installation, validation and recovery. This package has no Swift API documentation; its interface is the contributed native MCP registration and guidance resources. diff --git a/Documentation/Reference/Release.md b/Documentation/Reference/Release.md index cf3e20e..4436838 100644 --- a/Documentation/Reference/Release.md +++ b/Documentation/Reference/Release.md @@ -1,22 +1,64 @@ # Release -This guide covers publishing an accepted package through -[`release.yml`](../../.github/workflows/release.yml) and notifying the official -plugin catalog. [Versioning and Release](../Architecture/VersioningAndRelease.md) -owns this repository's version and acceptance rules. The organization's -[VERSIONING.md](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) -and [release workflow guide](https://github.com/computer-mcp/.github/blob/master/Documentation/Reference/PluginRelease.md) -own the shared release contents, immutability and recovery contract. +Release status: [CI](https://github.com/computer-mcp/plugin-computer-use/blob/master/.github/workflows/ci.yml) +builds candidate archives on pull requests, `master` pushes and manual runs. +[`release.yml`](https://github.com/computer-mcp/plugin-computer-use/blob/master/.github/workflows/release.yml) +implements dry runs and publication; native and host acceptance are manual. -## Prerequisite +The organization [VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) +owns version rules, including tags, version choice and the changelog. This +reference records this repository's version sources, compatibility, release +procedure and checks. The shared +[release workflow guide](https://github.com/computer-mcp/.github/blob/master/Documentation/Reference/PluginRelease.md) +describes workflow verification and recovery. -Before the first release, the repository owner must enable GitHub release -immutability in repository settings. The release workflow checks that setting -before any Release write and refuses publication if it is disabled or cannot -be verified. Enabling it does not lock previously published releases; an -existing public release must itself be immutable to be accepted by the workflow. +## Components and Version Sources -## Publish +| Shipped component | Version meaning | Version source | Mirrors and derived fields | Update and read-only check | +| --- | --- | --- | --- | --- | +| `computer-use.zip` plugin package | Package version | `version` in [`computer-mcp-plugin.toml`](../../computer-mcp-plugin.toml) | builder and release receipts, release tag, catalog entry, the App's bundled index | Edit the manifest; `release.yml` checks agreement with the tag | +| Manifest and host runtime contract | Plugin API version | `plugin_api` in [`computer-mcp-plugin.toml`](../../computer-mcp-plugin.toml) | release receipt and host compatibility evaluation | Package tests check the declaration; `release.yml` verifies it | + +The archive contains the README, contribution guide, manifest, license, notices, +`skills/` and `Documentation/`. Tests, build scripts and workflows are excluded +from the archive. + +## Compatibility Surface + +The package contributes the vendor's native stdio MCP registration and portable +observe–act–verify guidance. [Package architecture](../Architecture/Package.md) +owns executable discovery and the host/vendor authority boundaries. Native +tool behavior and caller authentication belong to the vendor. + +The manifest owns the plugin API declaration and host compatibility bounds. +Validate changes to those bounds against the required host. + +## Dependencies and Verified Combinations + +The package is a declaration: it registers the vendor's native Computer Use MCP +client and ships no runtime code. The manifest locates that client by command +name or application bundle, and the vendor owns its installation and caller +authentication. + +The builder needs only the Python 3.11 standard library. CI runs the tests and +build on Python 3.11 and 3.13. Package checks do not establish compatibility of +a particular vendor client, caller or GUI target; native discovery and action +acceptance identify the combination actually observed. + +## Derived Metadata and Drift Checks + +`Scripts/build_package.py` verifies the plugin ID, skips hidden files and Python +caches, rejects links and special files, and produces the same archive bytes +from the same source. `Tests/test_build_package.py` checks the plugin API +declaration and pins the exact archive file set. The builder receipt prints the +ID, version and SHA-256. + +## Candidate, Acceptance and Publication + +Publication depends on the repository's GitHub release immutability setting. +The shared workflow checks that setting before writing a Release. + +### Publish 1. Confirm that `version` in `computer-mcp-plugin.toml` has not been released and that the reviewed `master` commit has a successful `push` run of @@ -33,7 +75,7 @@ existing public release must itself be immutable to be accepted by the workflow. archive with the selected Computer MCP host, and confirm native catalog discovery with the installed vendor client. GUI checks use a disposable, explicitly authorized target. -4. Create a signed annotated tag `vX.Y.Z` on the accepted commit and push it. +4. Create the version tag that [VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) requires on the accepted commit and push it. Create a draft GitHub Release for that tag, targeting the full commit SHA, and record the manual acceptance results and their limits in its notes. 5. Dispatch `release.yml` with `ref` set to that version tag and `publish` set @@ -46,7 +88,15 @@ The public assets are `computer-use.zip`, the shared `release-receipt.json` and `SHA256SUMS`. CI's `package-receipt.json` remains builder evidence in the CI artifact. -## Catalog notification +### App distribution + +The Computer MCP App bundles a copy of this package, pinned by version and +SHA-256 in the App repository's `Resources/PluginArchives/index.json`. Before +the first release, the host may bundle an archive reproducibly built from an +accepted commit before that plugin version is published. A host release +requires the plugin release with the same archive digest to be public first. + +### Catalog notification `release.yml` calls `notify-catalog.yml` only when `publish` is `true` and the shared release workflow reports `published: true`. Only the notifier job @@ -71,7 +121,39 @@ The website's notification action is pinned to a reviewed full commit. Publish that website commit first, then update the pin here when adopting a change to the notification contract. -## Retry +## Evidence Reuse and Invalidation + +The CI artifact name identifies the source commit, and the builder receipt records +the archive SHA-256. The release workflow verifies CI provenance and artifact +digests; `release-receipt.json` records the commit, CI run and attempt, artifact +digest and archive SHA-256. + +An archive with the accepted digest keeps its archive acceptance for the tested +combination. Reuse of manual results is reviewed against the native dependency, +selected host, check definitions and relevant environment recorded with them. +Changes to packaged files produce a new archive and require the affected checks +again. A check-only change can reuse unchanged archive bytes with fresh affected +checks. Source tests do not replace installation, native or authenticated +execution evidence. Keep failed-check output and result limits with the manual +acceptance record. + +## Entry Points and Artifact Retention + +| Operation | Existing command or explicit manual procedure | Required access | +| --- | --- | --- | +| Version update and check | Edit `computer-mcp-plugin.toml`; `python3 -m unittest discover -s Tests -p 'test_*.py'` | Local checkout | +| Candidate validation and build | `ci.yml`; locally `Scripts/build-package.sh ` | CI or local checkout | +| Native and host acceptance | Validate and install the exact archive with the selected host; verify native catalog discovery and authorized GUI behavior | Selected host, vendor client and authorized disposable target | +| Acceptance and publication | Manual checks above; dispatch `release.yml`, dry run first | Repository Actions; publication also needs a signing key and release write access | +| Status and interrupted-run recovery | Inspect CI or `release.yml`; follow [Retry](#retry) | Repository Actions | +| Cleanup | Delete obsolete local output and evidence directories | Local checkout | + +CI keeps candidate artifacts for 14 days. The builder refuses to overwrite a +different archive. Local package output belongs in ignored `dist/`; keep +manual evidence outside the repository and retain it while the acceptance +record requires it. + +### Retry For an interrupted publication, use **Re-run failed jobs** and follow the shared workflow guide's recovery rules. If verification already succeeded, the publish diff --git a/Tests/test_build_package.py b/Tests/test_build_package.py index 9efda48..afe7372 100644 --- a/Tests/test_build_package.py +++ b/Tests/test_build_package.py @@ -31,7 +31,6 @@ def test_reproducible_owned_contents(self): "Documentation/Architecture/README.md", "Documentation/Architecture/Package.md", "Documentation/Architecture/Documentation.md", - "Documentation/Architecture/VersioningAndRelease.md", "Documentation/Brand/header-dark.png", "Documentation/Brand/header-light.png", "Documentation/Reference/Release.md",