diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1cde56b3..af351070 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,13 +98,13 @@ Maintainers cut releases. Every bump touches 9 release surfaces in lockstep: 2. `pnpm-lock.yaml` (resolved graph after the version bump) 3. `plugin/.claude-plugin/plugin.json` 4. `plugin/plugin.json` -5. `packages/mcp/package.json` (self version; keep the source dependency as `workspace:~`) +5. `packages/mcp/package.json` (self version; keep the source dependency as `workspace:*`) 6. `src/version.ts` (extend the union, assign) 7. `src/types.ts` (`ExportData.version` union) 8. `src/functions/export-import.ts` (`supportedVersions` Set) 9. `test/export-import.test.ts` (assertion) -Then: `corepack pnpm install --lockfile-only --ignore-scripts`, package dry-runs, CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance. The MCP shim is packed and published with pnpm so `workspace:~` is rewritten to the npm consumer semver range. +Then: `corepack pnpm install --lockfile-only --ignore-scripts`, package dry-runs, CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance. The MCP shim is packed and published with pnpm so `workspace:*` is rewritten to the exact matching npm dependency version. ## Security issues diff --git a/deploy/helm/agentmemory/README.md b/deploy/helm/agentmemory/README.md index 154c4a43..bd74d313 100644 --- a/deploy/helm/agentmemory/README.md +++ b/deploy/helm/agentmemory/README.md @@ -107,7 +107,7 @@ Upgrade by setting the new image tag: ```bash helm upgrade agentmemory deploy/helm/agentmemory \ - --set image.tag=0.9.28 + --set image.tag= ``` By default, Helm deletes chart-managed PVCs on uninstall. To keep memories after uninstalling the release, either use `persistence.existingClaim` or preserve the chart-created claim with a Helm resource-policy annotation: diff --git a/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/plan.md b/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/plan.md new file mode 100644 index 00000000..d458f085 --- /dev/null +++ b/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/plan.md @@ -0,0 +1,105 @@ +# Pin MCP Core Version Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Publish future `@agentmemory/mcp` packages with an exact dependency on the matching `@agentmemory/agentmemory` version. + +**Architecture:** Keep the MCP package as a pnpm workspace shim, but switch its source dependency from `workspace:~` to `workspace:*` so pnpm packs it as an exact dependency. Bump the coordinated current version to `0.9.28` because `0.9.27` is already published with bad npm metadata and the publish workflow correctly skips existing versions. + +**Tech Stack:** TypeScript, pnpm 11 workspace protocol, Vitest, npm package tarball inspection, GitHub Actions release workflow metadata. + +--- + +## Files + +- Modify: `packages/mcp/package.json` +- Modify: `pnpm-lock.yaml` +- Modify: `package.json` +- Modify: `src/version.ts` +- Modify: `src/types.ts` +- Modify: `src/functions/export-import.ts` +- Modify: `test/export-import.test.ts` +- Modify: `test/quality-gates.test.ts` +- Modify: `test/plugin-surface-contract.test.ts` +- Modify: plugin manifests with the current package version +- Modify: OpenClaw manifests with the current package version +- Modify: deploy Dockerfiles, Helm values/chart, managed-platform image references, deploy docs, `README.md` +- Modify: `CONTRIBUTING.md` +- Modify: `AGENTS.md` + +## Task 1: Write Failing Package Contract Tests + +- [ ] Change `test/quality-gates.test.ts` so the MCP dependency test expects `workspace:*` and names the exact-publish intent. +- [ ] Change `test/plugin-surface-contract.test.ts` so the MCP package contract expects `workspace:*` and asserts the MCP package version equals root `package.json` version. +- [ ] Run `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts`. +- [ ] Expected RED: tests fail because current source still uses `workspace:~`; no implementation files changed yet. + +## Task 2: Implement Exact Workspace Dependency + +- [ ] Change `packages/mcp/package.json` dependency `@agentmemory/agentmemory` from `workspace:~` to `workspace:*`. +- [ ] Run `corepack pnpm install --lockfile-only --ignore-scripts`. +- [ ] Confirm `pnpm-lock.yaml` records `specifier: workspace:*` for `packages/mcp`. +- [ ] Rerun `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts`. +- [ ] Expected GREEN: package contract tests pass. + +## Task 3: Bump Coordinated Version To 0.9.28 + +- [ ] Update root and MCP package versions to `0.9.28`. +- [ ] Update `src/version.ts`, `src/types.ts`, `src/functions/export-import.ts`, and `test/export-import.test.ts` for current export version `0.9.28` while keeping older import versions supported. +- [ ] Update plugin and OpenClaw current-version manifests that track the root version. +- [ ] Update deploy image defaults, Helm app version/tag, and deploy docs from `0.9.27` to `0.9.28`. +- [ ] Update `AGENTS.md` current stats heading from `v0.9.27` to `v0.9.28`. +- [ ] Leave independently versioned packages alone: `integrations/filesystem-watcher/package.json`, `website/package.json`, and `plugin/opencode/plugin.json`. + +## Task 4: Update Release Process Docs + +- [ ] Update `CONTRIBUTING.md` so the release checklist says the MCP source dependency stays `workspace:*`. +- [ ] Update the release-process explanation so pnpm publish rewrites `workspace:*` to an exact npm dependency. +- [ ] Review `deploy/helm/agentmemory/README.md` so the upgrade example does not merely repeat the default image tag. + +## Task 5: Verify Package Metadata And Tests + +- [ ] Run focused tests: + +```bash +corepack pnpm exec vitest run \ + test/quality-gates.test.ts \ + test/plugin-surface-contract.test.ts \ + test/consistency.test.ts \ + test/export-import.test.ts \ + test/deploy-version-contract.test.ts \ + test/copilot-plugin.test.ts \ + test/codex-plugin.test.ts \ + test/factory-plugin.test.ts +``` + +- [ ] Pack and inspect the MCP tarball: + +```bash +PACK_DIR="$(mktemp -d)" +corepack pnpm --dir packages/mcp pack --pack-destination "$PACK_DIR" --json +tar -xOf "$PACK_DIR"/agentmemory-mcp-0.9.28.tgz package/package.json \ + | jq -r '.version, .dependencies["@agentmemory/agentmemory"]' +``` + +- [ ] Expected pack output: + +```text +0.9.28 +0.9.28 +``` + +- [ ] Run `corepack pnpm test` if dependency setup allows it. + +## Task 6: Security And Handoff + +- [ ] Run `rg -n 'workspace:~|0\.9\.27|0\.9\.28'` over touched surfaces and classify remaining historical fixtures. +- [ ] Run `git diff --check`. +- [ ] Run `osv-scanner scan source .`. +- [ ] Run `semgrep scan --config p/default --error --metrics=off .`. +- [ ] Before any commit, stage only intended files and run `gitleaks protect --staged --redact`. +- [ ] Update `docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md` with verification evidence, caveats, and final matrix status. + +## Approval Boundaries + +- Do not push, publish, create a PR, tag, deprecate npm packages, change npm dist-tags, deploy, merge, close the issue, or archive this thread without explicit current-turn approval. diff --git a/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md b/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md new file mode 100644 index 00000000..01b1bae4 --- /dev/null +++ b/docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md @@ -0,0 +1,93 @@ +# Issue 267 Pin MCP Core Version + +## Scope + +- Worktree: `/Users/A1538552/.codex/worktrees/424b/agentmemory` +- Branch: `issue/267-pin-mcp-core-version` +- Base inspected: `eacce17e` +- Remote target: `origin` (`https://github.com/wbugitlab1/agentmemory.git`) +- Issue: GitHub issue #267, `@agentmemory/mcp does not pin the matching core version, allowing fixed MCP behavior to regress` + +## Sprint Contract + +- Goal: ensure every newly published `@agentmemory/mcp@X.Y.Z` depends on exactly `@agentmemory/agentmemory@X.Y.Z`. +- Scope: MCP shim package metadata, lockfile importer, version-aligned release surfaces for the next patch release, tests, and release-process docs that describe the MCP dependency rewrite. +- Non-goals: no publishing, push, PR creation, tag, npm deprecation, dist-tag change, deployment, or remote project/account state change. +- Acceptance criteria: + - `packages/mcp/package.json` uses `workspace:*` for `@agentmemory/agentmemory`. + - Packed MCP package metadata rewrites that dependency to exact `0.9.28`. + - The coordinated current version is bumped from `0.9.27` to `0.9.28` on repo surfaces required by AGENTS.md and current tests. + - Tests guard exact MCP/core version alignment. + - Release docs no longer tell maintainers to keep `workspace:~`. +- Intended verification: + - Focused Vitest contract/version tests. + - `corepack pnpm --dir packages/mcp pack --pack-destination ... --json` plus tarball manifest inspection. + - `corepack pnpm test` if dependencies are available. + - Required security scans for manifest/lockfile/config/instruction changes. +- Known boundaries: + - Remote writes and credentialed GitHub/npm state changes require explicit current-turn approval. + - If chosen version `0.9.28` is already published, stop and choose the next unpublished patch only after recording evidence. + - Do not touch parent checkout or issue 821-830 worktrees. +- Stop conditions: + - Any branch creation conflict, unexpected unrelated dirty files in task-owned paths, repeated verification failure without a diagnosed cause, or required scanner finding not accepted by the user. + +## Validity Evidence + +- Local source at start had `packages/mcp/package.json` dependency `"@agentmemory/agentmemory": "workspace:~"`. +- Local tests `test/quality-gates.test.ts` and `test/plugin-surface-contract.test.ts` also expected `workspace:~`. +- Public unauthenticated GitHub API confirmed issue #267 is open and describes `@agentmemory/mcp@0.9.22` depending on `~0.9.0`. +- Public npm metadata check showed `npm view @agentmemory/mcp@0.9.27 dependencies --json` returns `{"@agentmemory/agentmemory":"~0.9.0"}`. +- `.github/workflows/publish.yml` skips already-published MCP package versions, so a source-only fix at `0.9.27` would not repair npm consumers. + +## Arena Synthesis + +- Candidates: `/tmp/arena-issue267/candidate-1/strategy.md`, `/tmp/arena-issue267/candidate-2/strategy.md`, `/tmp/arena-issue267/candidate-3/strategy.md`. +- Judge report: `/tmp/arena-issue267/judge.md`. +- Base: Candidate 2. +- Grafts: + - Candidate 3: explicit non-goal for npm deprecation and unrelated packages not to bump. + - Candidate 1: review Helm README examples so override text does not just repeat the new default image tag. +- Rejected: + - Keeping `workspace:~`, because pnpm publishes it as a range. + - Literal source dependency on `0.9.28`, because local workspace installs should keep linking the local root package. + - Rewriting publish skip behavior, because npm package versions are immutable and the skip is correct. + +## Feature / Verification Matrix + +| Change | Verification method | Status | Evidence | +| --- | --- | --- | --- | +| Exact MCP/core dependency | Pack tarball manifest and focused package tests | Done | RED: focused tests failed on `workspace:~`; GREEN: `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts` passed after `workspace:*`. Pack tarball inspection printed `0.9.28` and dependency `0.9.28`. | +| Coordinated version bump | Consistency/export/deploy/plugin tests and stale-string search | Done | `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts test/consistency.test.ts test/export-import.test.ts test/deploy-version-contract.test.ts test/copilot-plugin.test.ts test/codex-plugin.test.ts test/factory-plugin.test.ts` passed: 8 files, 83 tests. Stale-string search found no active `workspace:~` or `0.9.27` in source/release surfaces; remaining `0.9.27` is backward-compatible export/import support or task evidence. | +| Release-process docs | Read diff and search for `workspace:~` | Done | `CONTRIBUTING.md` now documents `workspace:*` and exact npm dependency rewrite; `deploy/helm/agentmemory/README.md` upgrade example now uses `` instead of repeating the new default tag. | +| Full repo behavior | `corepack pnpm test` or closest targeted substitute | Done | `corepack pnpm test` passed: 202 files, 2,797 tests. | +| Security gates | OSV, Semgrep, staged Gitleaks before commit | Done | `git diff --check` passed. `osv-scanner scan source .` passed with the repo's existing GHSA-8988-4f7v-96qf waiver applied and no unfiltered issues. `semgrep scan --config p/default --error --metrics=off .` passed with 0 findings. `gitleaks protect --staged --redact` passed with no leaks found. | + +## Subagent Ledger + +| Workstream | Scope | Edits allowed | Expected output | Result | Residual risk | +| --- | --- | --- | --- | --- | --- | +| Arena candidate 1 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-1/strategy.md` | Recommended `workspace:*` plus `0.9.28` | Missed some plugin surfaces | +| Arena candidate 2 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-2/strategy.md` | Chosen base; included `CONTRIBUTING.md` | Broader verification than minimum | +| Arena candidate 3 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-3/strategy.md` | Strong scope/non-goals grafted | Missed `CONTRIBUTING.md` | +| Arena judge | Score strategies | No repo edits | `/tmp/arena-issue267/judge.md` | Candidate 2 base, grafts from 1 and 3 | None known | +| Final security review | Security and supply-chain diff review | No repo edits | ACCEPT or High/Medium findings | ACCEPT; no High/Medium findings | Did not rerun already-passed commands | +| Final test coverage review | Test and verification evidence review | No repo edits | ACCEPT or High/Medium findings | Medium finding: task record still showed pending verification | Fixed in this task-record update | +| Final maintainability review | Scope and release consistency review | No repo edits | ACCEPT or High/Medium findings | Medium finding duplicated task-record evidence gap | Fixed in this task-record update | + +## Progress + +- 2026-06-19: Created and switched to branch `issue/267-pin-mcp-core-version` from detached `eacce17e`. +- 2026-06-19: Validated issue as still relevant for npm consumers using public issue metadata and public npm metadata. +- 2026-06-19: Ran arena strategy phase and recorded synthesis. +- 2026-06-19: Implemented `workspace:*` MCP dependency, `0.9.28` coordinated version bump, release-process docs, deploy/plugin/OpenClaw/version surfaces, and package contract tests. +- 2026-06-19: Verification passed: focused RED/GREEN package tests, focused version/deploy/plugin suite, MCP tarball exact dependency inspection, full `corepack pnpm test`, `git diff --check`, OSV, and Semgrep. +- 2026-06-19: Final review passed after task-record evidence gap was fixed. Security review accepted the diff; test coverage and maintainability reviewers found only this task-record update requirement. + +## Review Notes And Caveats + +- Dependency setup: first `corepack pnpm exec vitest ...` auto-install was blocked by pnpm ignored-build hardening. Per AGENTS.md, `corepack pnpm install --frozen-lockfile --ignore-scripts` was run and completed. It emitted the expected pre-build `packages/mcp` bin-link warning for missing `dist/cli.mjs`. +- OSV: the repository's existing `osv-scanner.toml` filtered GHSA-8988-4f7v-96qf for the known transitive `iii-sdk@0.11.2` OpenTelemetry 1.x issue; no unfiltered issues were found. +- `website/lib/generated-meta.json` still reports `0.9.27`; maintainability review inspected it and did not classify it as a blocking finding because website scripts regenerate metadata during normal website dev/build. It is outside this issue-scoped release-package fix. +- Staged Gitleaks passed after staging the intended issue-owned files. +- Remote writes, issue closure, PR creation, PR merge, npm publish/deprecation, tags, deployment, and thread archival have not been approved or performed. +- Mandatory archival contract from parent triage: if this valid issue later reaches a PR merge request, the approval request must bundle PR merge into `origin/main` and archiving this Codex thread after successful merge. Only after a successful merge should `set_thread_archived({ archived: true })` be called for this current thread. diff --git a/packages/mcp/package.json b/packages/mcp/package.json index bf3e3ba3..4dda3282 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -29,7 +29,7 @@ "homepage": "https://github.com/rohitg00/agentmemory#readme", "bugs": "https://github.com/rohitg00/agentmemory/issues", "dependencies": { - "@agentmemory/agentmemory": "workspace:~" + "@agentmemory/agentmemory": "workspace:*" }, "publishConfig": { "access": "public", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d2339513..d2b98206 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -83,7 +83,7 @@ importers: packages/mcp: dependencies: '@agentmemory/agentmemory': - specifier: workspace:~ + specifier: workspace:* version: link:../.. website: diff --git a/test/plugin-surface-contract.test.ts b/test/plugin-surface-contract.test.ts index 5e049532..3f82242a 100644 --- a/test/plugin-surface-contract.test.ts +++ b/test/plugin-surface-contract.test.ts @@ -117,17 +117,20 @@ describe("Package and integration manifests", () => { const pkg = readJson<{ name: string; type: string; + version: string; bin: Record; files: string[]; dependencies: Record; publishConfig: { access: string; provenance: boolean }; }>(join(repoRoot, "packages/mcp/package.json")); + const rootPkg = readJson<{ version: string }>(join(repoRoot, "package.json")); expect(pkg.name).toBe("@agentmemory/mcp"); + expect(pkg.version).toBe(rootPkg.version); expect(pkg.type).toBe("module"); expect(pkg.bin["agentmemory-mcp"]).toBe("./bin.mjs"); expect(pkg.files).toEqual(expect.arrayContaining(["bin.mjs", "README.md", "LICENSE"])); - expect(pkg.dependencies["@agentmemory/agentmemory"]).toBe("workspace:~"); + expect(pkg.dependencies["@agentmemory/agentmemory"]).toBe("workspace:*"); expect(pkg.publishConfig).toMatchObject({ access: "public", provenance: true }); expect(existsSync(join(repoRoot, "packages/mcp", pkg.bin["agentmemory-mcp"]))).toBe(true); }); diff --git a/test/quality-gates.test.ts b/test/quality-gates.test.ts index 430a3ba6..6717171c 100644 --- a/test/quality-gates.test.ts +++ b/test/quality-gates.test.ts @@ -392,10 +392,10 @@ describe("root quality gates", () => { expect(readText("website/.gitignore")).not.toMatch(/^pnpm-lock\.yaml$/m); }); - it("uses a pnpm workspace dependency for the MCP shim source package", () => { + it("uses an exact pnpm workspace dependency for the MCP shim source package", () => { const mcp = JSON.parse(readText("packages/mcp/package.json")) as PackageJson; - expect(mcp.dependencies?.["@agentmemory/agentmemory"]).toBe("workspace:~"); + expect(mcp.dependencies?.["@agentmemory/agentmemory"]).toBe("workspace:*"); }); it("keeps published Node engine guidance aligned with package manifests", () => {