CLI Release Plan

This document tracks how the jup-sh CLI is being released as a public npm alpha.

Current State

The public alpha is available through npm:

npx jup-sh init
npx jup-sh pay --agent deepseek --token SOL --amount 20 --settle USDC --json

The package name and binary are:

jup-sh

Source development still supports:

npm run cli:alpha -- pay --agent deepseek --token SOL --amount 20 --settle USDC
npm run cli -- pay --agent deepseek --token SOL --amount 20 --settle USDC

The release gate is:

npm run release:check

The alpha smoke test covers the CLI contract for agents:

• init writes local config and policy files
• doctor reports local workspace state
• policy trust and policy set mutate local risk policy
• pay --json emits parseable JSON only
• auto_pay exits with code 0
• review_required exits with code 2
• rejected exits with code 1
• key payment intent fields match docs/cli-json-contract.md
• intent list, intent export, and review work after those outcomes

The package dry run is available as:

npm run alpha:pack

The detailed release checklist is in:

docs/npm-alpha-release-checklist.md

Release notes are in:

docs/releases/

Target Developer Experience

Primary public path:

npx jup-sh init
npx jup-sh policy trust api.vendor.example
npx jup-sh pay --agent deepseek --token SOL --amount 6 --settle USDC --recipient api.vendor.example --json

Installed target:

npm install -g jup-sh
jup-sh pay --agent deepseek --token SOL --amount 20 --settle USDC

The command should stay aligned with the website:

pay --agent deepseek --token SOL --amount 20 --settle USDC

Why npm / npx First

npm is the right first distribution channel because:

• the target users are agent, app, and API developers
• npx works well for trying a CLI without installation
• the website already presents the tool as a command-first developer product
• it can later wrap the Rust binary without changing the user-facing command

Cargo install and Homebrew can come later.

Packaging Approach

The current npm alpha package is a self-contained Node.js CLI. It does not require Rust or a repository checkout.

The repository still keeps Rust and TypeScript source paths for development:

rust/crates/core
rust/crates/cli
sdk/

Current npm package:

npm/
  package.json
  bin/
    jup-sh

Longer term, the npm package may wrap prebuilt Rust binaries once the CLI surface stabilizes. The public command shape should stay stable.

Release Criteria

Before moving beyond alpha, the CLI should have:

• stable command names for pay, policy, and intent
• clear JSON output for agents
• documented exit codes for pay
• documented CLI JSON contract
• no private keys, signatures, or transactions in exported review payloads
• README.md Quickstart that matches the published install path
• GitHub release notes based on CHANGELOG.md
• npm package dry-run checklist
• GitHub pre-release notes for each alpha checkpoint
• basic smoke tests for:
  • jup-sh policy show
  • jup-sh pay ...
  • jup-sh intent list
  • jup-sh intent export ...
  • npm run alpha:smoke

Current Non-Goals

The npm alpha should not include:

• wallet signing
• swap execution
• Solana Pay transaction requests
• remote backend persistence
• authentication

Proposed Milestones

Alpha 0

Source-only:

npm run cli -- ...
npm run cli:alpha -- ...

Completed.

Alpha 1

SDK risk-layer checkpoint.

Completed.

Alpha 2

First public npm alpha:

npx jup-sh ...

Completed.

Alpha 3

First-run init workflow.

Completed.

Alpha 4

Policy tuning from CLI.

Completed.

Alpha 5

Top-level Risk Review shortcut.

Completed.

Alpha 6

Local workspace diagnostics with jup-sh doctor.

Completed.

Alpha 7

Full review handoff metadata in pay --json and review --json.

Completed.

Alpha 8

Transaction Request Skeleton design checkpoint.

Draft.

Beta

Add backend intent storage or Solana Pay transaction request generation.