agentpack-cli 0.1.0 → 0.1.3

package/README.md

@@ -29,47 +29,66 @@ The first version is intentionally small:
 - run a minimal local MCP server for coding-agent clients
 - export a budgeted markdown handoff for manual fallback workflows
 
-## Quick Start
+## Install
+
+Agentpack requires Node.js >= 20.
 
 ```bash
 npm install -g agentpack-cli
+agentpack --version
+```
+
+If you don't have Node yet, install it through [`fnm`](https://github.com/Schniz/fnm):
+
+```bash
+brew install fnm
+fnm install 22
+fnm default 22
+echo 'eval "$(fnm env --use-on-cd --shell zsh)"' >> ~/.zshrc
+exec zsh
+```
+
+## Quick Start
+
+```bash
+cd path/to/your/repo
 agentpack init
 agentpack install codex --write
 # or: agentpack install claude --write
 # or: agentpack install cursor --write
+# or: agentpack install claude-desktop  (prints a snippet to merge manually)
 ```
 
 Restart or reconnect the coding-agent client. The generated project instructions tell the agent to load Agentpack context at the start, record durable decisions/sources/evidence while working, and checkpoint meaningful progress.
 
 Use `agentpack doctor` to verify the local setup. Use `agentpack resume --preset agent --query "<topic>"` when you want to inspect the task state yourself.
 
-For local development in this repo:
+See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) for safe Codex, Claude Code, Cursor, and Claude Desktop setup.
+See [docs/agentpack-flow.md](docs/agentpack-flow.md) for a visual execution flow.
 
-```bash
-fnm use 22
-npm ci --ignore-scripts
-npm test
-npm run mcp:smoke
-node dist/src/agentpack.js --help
-```
+## Verify a workflow-published release
 
-If `npm` is not available yet, install Node through `fnm` first:
+Versions published by the GitHub Actions release workflow ship with [npm provenance](https://docs.npmjs.com/generating-provenance-statements). To verify that tarball was built from a known commit of this repo:
 
 ```bash
-brew install fnm
-fnm install 22
-fnm default 22
+npm audit signatures
 ```
 
-Then add this to `~/.zshrc` and restart the terminal:
+For those versions, you can also inspect the attestation manually at <https://www.npmjs.com/package/agentpack-cli> under the **Provenance** tab — it links back to the exact commit, workflow run, and build environment that produced the package.
+
+## Contributing / local development
+
+Clone the repo and use Node 22:
 
 ```bash
-eval "$(fnm env --use-on-cd --shell zsh)"
+fnm use 22
+npm ci --ignore-scripts
+npm test
+npm run mcp:smoke
+node dist/src/agentpack.js --help
 ```
 
-See [docs/SETUP.md](docs/SETUP.md) for the full setup guide.
-
-This repo uses Agentpack itself through MCP. See [docs/DOGFOOD.md](docs/DOGFOOD.md) for the working protocol.
+This repo uses Agentpack itself through MCP — see [docs/DOGFOOD.md](docs/DOGFOOD.md) for the working protocol and [docs/SETUP.md](docs/SETUP.md) for the full setup guide. Release process is documented in [docs/RELEASING.md](docs/RELEASING.md).
 
 To verify the local MCP server without configuring an agent client yet:
 
@@ -79,9 +98,6 @@ npm run mcp:smoke
 
 The smoke runner creates a temporary Agentpack workspace, starts `agentpack mcp`, sends `initialize`, `tools/list`, and a short `resume` flow, then deletes the temporary workspace.
 
-See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) for safe Codex, Claude Code, and Cursor setup.
-See [docs/agentpack-flow.md](docs/agentpack-flow.md) for a visual execution flow.
-
 ## Coding-Agent Loop
 
 Agentpack's core loop is built for coding agents working in the same repo over long sessions, compaction, restarts, or handoffs:
@@ -109,7 +125,7 @@ Agentpack keeps the v0 supply chain deliberately small:
 - no telemetry
 - no network calls during normal CLI or MCP operation
 - best-effort redaction for common secret-looking values in stored context and handoff outputs
-- npm provenance prepared for future public releases
+- release workflow publishing through GitHub Actions with npm provenance and Trusted Publisher OIDC (no long-lived npm tokens)
 
 ## Core Idea
 

package/SECURITY.md

@@ -17,14 +17,27 @@ Agentpack is designed as a local-first developer tool. The default threat model
 
 The project uses a conservative npm setup:
 
+- zero runtime dependencies
 - exact dependency versions
 - committed lockfile
 - `ignore-scripts=true` for installs
-- TypeScript compiler only for builds
-- npm provenance enabled for future public releases
-- trusted publishing preferred over long-lived npm tokens
+- TypeScript compiler is the only build dependency
+- the release workflow publishes from GitHub Actions via a Trusted Publisher OIDC binding
+- versions published by that workflow ship with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) — no long-lived npm tokens are stored anywhere
 
-Before publishing, maintainers should run:
+## Verifying a release
+
+To verify a downloaded version of `agentpack-cli`:
+
+```bash
+npm audit signatures
+```
+
+For workflow-published versions, the npmjs.com page for the package also shows a **Provenance** tab linking back to the exact commit, workflow run, and build environment that produced the tarball.
+
+## Maintainer pre-publish checklist
+
+Before cutting a new release, maintainers should run:
 
 ```bash
 npm ci
@@ -33,12 +46,18 @@ npm test
 npm pack --dry-run
 ```
 
+The full release flow is documented in [docs/RELEASING.md](docs/RELEASING.md).
+
 ## Sensitive Data
 
 Agentpack redacts common secret-looking values and configured environment variable values from generated context and key local records such as source summaries, evidence, checkpoints, replay output, and MCP context responses.
 
 Redaction is best-effort, not a guarantee. Users should treat `.agentpack/` as project-sensitive data and review exported handoff files before sharing them.
 
-## Reporting
+## Reporting a vulnerability
+
+Please report security issues privately through GitHub Security Advisories:
+
+<https://github.com/ihorponom/agentpack/security/advisories/new>
 
-Until a public repository security contact exists, report issues privately to the project maintainer.
+This keeps the report hidden until a fix is ready and gives credit to the reporter. Do not open a regular issue for security problems.

package/docs/RELEASING.md

@@ -0,0 +1,80 @@
+# Releasing Agentpack
+
+Agentpack publishes to npm as `agentpack-cli` from GitHub Actions, signed with
+npm provenance via a Trusted Publisher. No `NPM_TOKEN` is stored in the repo.
+
+## One-time setup (already done)
+
+- npmjs.com → package `agentpack-cli` → Settings → Trusted Publisher:
+  - Repository: `ihorponom/agentpack`
+  - Workflow: `publish.yml`
+  - Environment: *(empty)*
+- `.github/workflows/publish.yml` requests `id-token: write` so it can present
+  a short-lived OIDC token that npm verifies against the Trusted Publisher
+  binding.
+- The publish workflow uses Node 24 so the bundled npm is new enough for
+  Trusted Publishing without upgrading npm while npm is running.
+- `publishConfig.provenance: true` in `package.json` makes workflow publishes
+  include the provenance attestation.
+
+## Cutting a release
+
+```bash
+# 1. Decide the bump and update package.json + create the git tag.
+npm version patch      # 0.1.x -> 0.1.(x+1)
+# or: npm version minor # 0.1.x -> 0.2.0
+# or: npm version major # 0.x.y -> 1.0.0
+
+# 2. Push the new commit and the tag.
+git push --follow-tags
+
+# 3. Create a GitHub Release for that tag. The publish workflow fires on
+#    release: published.
+gh release create "v$(node -p "require('./package.json').version")" \
+  --title "v$(node -p "require('./package.json').version")" \
+  --generate-notes
+```
+
+That's it. The workflow will:
+
+1. Check out the tag.
+2. Install dependencies with `npm ci`.
+3. Build (`npm run build`).
+4. Run tests (`npm test`).
+5. Verify `package.json` version matches the release tag.
+6. Publish with `npm publish --access public`.
+
+Watch the run at <https://github.com/ihorponom/agentpack/actions>. When it
+finishes, npm shows the green `Provenance` badge on the package page.
+
+## Manual fallback
+
+If a release is published while Actions is disabled, or the publish step
+fails, re-run from the Actions tab:
+
+1. GitHub → Actions → "Publish to npm" → Run workflow.
+2. Pick the tag (or `main`) and choose `dry-run: true` first to verify.
+3. Re-run with `dry-run: false`.
+
+## Pre-flight checklist
+
+Before `npm version`:
+
+- `npm test` is green locally.
+- `agentpack doctor` is clean in the repo (warnings about source-cache
+  staleness are ok; errors are not).
+- `npm pack --dry-run` shows the expected set of files and a reasonable
+  tarball size (~85 kB at the time of writing).
+- README, CHANGELOG (if any), and docs reflect the version about to ship.
+
+## Rollback
+
+`npm unpublish agentpack-cli@<version>` is allowed only within 72 hours of
+publish, and only if no other package depends on it. Prefer publishing a
+new patch version with the fix.
+
+Deprecation (recommended when a version has a bug but unpublish is closed):
+
+```bash
+npm deprecate agentpack-cli@<version> "Use <newer-version>: <reason>"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentpack-cli",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Local task-state ledger for AI coding agents.",
   "type": "module",
   "repository": {
@@ -12,7 +12,7 @@
     "url": "https://github.com/ihorponom/agentpack/issues"
   },
   "bin": {
-    "agentpack": "./dist/src/agentpack.js"
+    "agentpack": "dist/src/agentpack.js"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",