Skip to content

RELEASE.md

Latest commit

 

History

History
241 lines (176 loc) · 6.21 KB

RELEASE.md

File metadata and controls

241 lines (176 loc) · 6.21 KB
Raw

Ripple Release Checklist

This checklist answers one question:

Can we launch this build today?

Run the release gate from the repo root:

npm run release:check

This command does not publish anything. It proves the product is ready enough for a human to make the final release decision.

What The Gate Proves

npm run release:check runs the full agent-control proof, the external install smoke, and then checks the release checklist itself.

It proves:

  • ripple init can make a fresh repo ready
  • packed @getripple/cli installs into a clean repo
  • packed @getripple/mcp installs into a clean repo
  • the installed CLI can run init -> plan -> doctor -> gate
  • the installed MCP stdio server can run workflow -> doctor -> plan -> doctor -> gate
  • all three packages can install together into one clean external repo
  • installed CLI and installed MCP both report the same boundary-crossing stop
  • authorization gates catch boundary violations
  • human approval gates block and unblock correctly
  • CI speaks the same continue, repair, human-review, and restore-readiness language
  • MCP host and MCP stdio speak the same gate language
  • npm package metadata, entry points, bins, README install commands, and npm pack --dry-run contents are valid
  • public package versions match the root version
  • release scripts and this checklist are wired together
  • public docs match the product persona and avoid forbidden overclaims

Manual Gates

These checks cannot be automated safely:

  • Review the final diff and make sure it matches the intended release.
  • Review docs/product-persona.md if the product promise, audience, or claims changed.
  • Run npm run release:identity and consciously review the public product identity.
  • Run npm run release:npm-preflight -- --live and review npm registry readiness.
  • Confirm npm account access with npm whoami.
  • Confirm the @getripple npm scope and package names are owned or available.
  • Confirm this version should be released publicly.
  • Confirm no secret, private repo path, local credential, or accidental test artifact is included.
  • Confirm the public README and package READMEs describe the product honestly.

Release Identity Review

Run:

npm run release:identity

This prints the public identity you are about to release.

Product identity:

Ripple is a local authorization gate for AI coding agents that defines what an agent may change, checks the real Git diff, and returns continue, repair, or human review.

Package identity:

@getripple/core -> local engine
@getripple/cli  -> terminal and CI interface
@getripple/mcp  -> agent-facing MCP stdio interface

Human decision:

Are these names, version, scope, public promise, alpha status, and README claims exactly what we want to publish?

Do not publish if:

  • the @getripple npm scope or package names are not controlled by you
  • the version is not the version you want public
  • the README sounds stronger than the product really is
  • the release still depends on this local machine to work
  • the package descriptions no longer match the product direction
  • you feel rushed and have not reviewed the final diff

NPM Registry Preflight

Run the dry preflight anytime:

npm run release:npm-preflight

Dry mode validates local package identity and prints the read-only registry checks. It does not hit the network.

Before publishing, run the live preflight:

npm run release:npm-preflight -- --live

Live mode runs read-only npm commands:

npm whoami
npm access ls-packages @getripple --json
npm view @getripple/core@1.0.9 version --json
npm view @getripple/cli@1.0.9 version --json
npm view @getripple/mcp@1.0.9 version --json

Expected result before publishing a new version:

npm whoami succeeds
@getripple/core@1.0.9 is not found
@getripple/cli@1.0.9 is not found
@getripple/mcp@1.0.9 is not found

Stop if:

  • npm auth fails
  • any target version already exists
  • registry checks fail for a reason other than package not found
  • you cannot confirm @getripple scope/package ownership

Publish Order

Publish the packages in dependency order:

npm publish --workspace @getripple/core
npm publish --workspace @getripple/cli
npm publish --workspace @getripple/mcp

@getripple/cli and @getripple/mcp depend on the matching @getripple/core version, so core must publish first.

External Install Smoke

Before publishing, run the local external install smoke:

npm run smoke:external-install

This does not hit the public npm registry. It packs the local packages, installs @getripple/core, @getripple/cli, and @getripple/mcp into a fresh temporary consumer repo, then verifies:

installed ripple binary -> init, plan, approve, gate stop, repair
installed MCP server    -> workflow, gate stop

After publishing, you can run the same smoke against the public registry:

npm run smoke:external-install -- --live

Post-Publish Smoke

After publishing, run the automated public install smoke:

npm run smoke:post-publish -- --live

Without --live, the command only prints the smoke plan and does not hit the network:

npm run smoke:post-publish

The live smoke creates a fresh temporary repo and verifies:

@getripple/cli -> ripple --version, init, plan, gate
@getripple/mcp -> ripple_get_agent_workflow, ripple_doctor, ripple_plan_context, ripple_gate

Manual equivalent for the CLI public install path:

npx -y @getripple/cli doctor
npx -y @getripple/cli init
npx -y @getripple/cli plan --file src/index.ts --task "smoke test Ripple" --mode file --save
npx -y @getripple/cli gate --intent latest

For MCP:

npx -y @getripple/mcp --workspace /absolute/path/to/your/repo

Then connect an MCP client with:

{
  "mcpServers": {
    "ripple": {
      "command": "npx",
      "args": [
        "-y",
        "@getripple/mcp",
        "--workspace",
        "/absolute/path/to/your/repo"
      ]
    }
  }
}

The first MCP calls to verify are:

ripple_get_agent_workflow
ripple_doctor
ripple_plan_context
ripple_gate

Release Rule

If npm run release:check fails, do not publish.

If it passes, publish only after the manual gates are reviewed by a human.