@heyanon-arp/cli 0.0.6 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyanon-arp/cli",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Command-line client for the Agent Relationship Protocol — register agents, sign envelopes, run escrowed work cycles on Solana.",
   "license": "MIT",
   "keywords": [
@@ -22,7 +22,7 @@
   },
   "files": [
     "dist",
-    "examples",
+    "scripts/postinstall.mjs",
     "LICENSE",
     "README.md"
   ],
@@ -36,7 +36,8 @@
     "commander": "^12.1.0",
     "prompts": "^2.4.2",
     "simple-update-notifier": "^2.0.0",
-    "@heyanon-arp/sdk": "0.0.5"
+    "@heyanon-arp/shield": "0.0.2",
+    "@heyanon-arp/sdk": "0.0.7"
   },
   "devDependencies": {
     "@types/jest": "^29.5.2",
@@ -52,6 +53,7 @@
     "build": "tsup",
     "start": "node dist/cli.js",
     "test": "jest --runInBand --detectOpenHandles --forceExit --passWithNoTests",
-    "lint": "biome check . --write"
+    "lint": "biome check . --write",
+    "postinstall": "node scripts/postinstall.mjs"
   }
 }

package/scripts/postinstall.mjs

@@ -0,0 +1,55 @@
+/**
+ * Post-install onboarding banner for the `heyarp` CLI.
+ *
+ * The whole message is "the guides ship inside the CLI — read them first":
+ * `heyarp guide` is the canonical onboarding surface (a human walkthrough plus
+ * an LLM-system-prompt block for agent operators), so a fresh install points
+ * straight at it instead of an external docs site.
+ *
+ * Onboarding must NEVER get in the way, so this is deliberately defensive:
+ *   - only for an interactive GLOBAL install (`npm i -g @heyanon-arp/cli`)
+ *   - silent only in CI and non-TTY / piped contexts (no user opt-out — the
+ *     banner shows on every interactive GLOBAL install + update)
+ *   - honours NO_COLOR
+ *   - fully wrapped so a banner failure can never fail the install
+ */
+try {
+	const isGlobalInstall = process.env.npm_config_global === 'true' || process.env.npm_config_global === '1';
+	const inCI = Boolean(process.env.CI);
+	const interactive = Boolean(process.stdout && process.stdout.isTTY);
+
+	if (!isGlobalInstall || inCI || !interactive) {
+		process.exit(0);
+	}
+
+	const useColor = !process.env.NO_COLOR;
+	const paint = (code, text) => (useColor ? `\x1b[${code}m${text}\x1b[0m` : text);
+	const bold = (t) => paint('1', t);
+	const cyan = (t) => paint('36', t);
+	const dim = (t) => paint('2', t);
+
+	const lines = [
+		'',
+		bold('  🤝 heyarp installed — the Agent Relationship Protocol CLI'),
+		'',
+		'  New here? The guides ship inside the CLI — read them first, no docs site needed:',
+		'',
+		`    ${cyan('heyarp guide')}                 ${dim('role-based walkthrough (worker / buyer)')}`,
+		`    ${cyan('heyarp guide --setup')}         ${dim('one-time setup: keys, server, multi-agent isolation')}`,
+		`    ${cyan('heyarp guide --troubleshoot')}  ${dim('common errors → fixes')}`,
+		'',
+		`  ${bold('Driving heyarp from an AI agent?')} Pipe YOUR role's guide into its system prompt`,
+		`  ${dim('(role is per-deal: BUYER if you send the offer + pay; WORKER if an offer comes to you):')}`,
+		'',
+		`    ${cyan('heyarp guide --role worker --format prompt')}   ${dim('# you do tasks, get paid')}`,
+		`    ${cyan('heyarp guide --role buyer  --format prompt')}   ${dim('# you order tasks, pay')}`,
+		'',
+		`  ${dim('Then:')} ${cyan('heyarp register')} ${dim('→ handshake → delegation → work → receipt → settlement.')}`,
+		'',
+	];
+	process.stdout.write(`${lines.join('\n')}\n`);
+} catch {
+	// Onboarding is best-effort. Never break an install over a banner.
+}
+
+process.exit(0);

package/examples/README.md

@@ -1,147 +0,0 @@
-# `@heyanon-arp/cli` — bundled examples
-
-This directory ships with the npm package and is reachable from
-inside a working CLI install via `heyarp examples`:
-
-```bash
-heyarp examples list                                # list bundled examples
-heyarp examples show worker                         # print to stdout
-heyarp examples show worker > my-worker.py          # pipe to file
-heyarp examples copy worker --output ./my-worker.py # copy to disk
-```
-
-The CLI resolves bundled paths relative to its own runtime location
-(`<node_modules>/@heyanon-arp/cli/examples/...`), so you do not need
-network access or a checkout of the source repository — `npm i -g
-@heyanon-arp/cli` is enough.
-
-## Current examples
-
-| File | Subject | Status |
-|---|---|---|
-| [`worker-template.py`](./worker-template.py) | Autonomous Python worker (handshake → contract → delegation → work → receipt → settlement, all auto-mediated; you fill in `handle_work_request()`) | Reference; FLAT pricing + full-release settlement only. MIT. |
-
-## How to use the worker template
-
-1. Register an agent (one-time):
-
-   ```bash
-   heyarp register --name "MyWorker" --tag my-service --endpoint-url https://my-agent.example/inbox
-   ```
-
-2. Copy the template:
-
-   ```bash
-   heyarp examples copy worker --output ./my-worker.py
-   ```
-
-3. Edit `handle_work_request(params, rel_id, del_id, req_id, sender_did)` in
-   the copied file — that is the only function with your business logic.
-   Everything else (FSM mediation, signing, settlement) is policy.
-
-4. Set your agent's settlement public key. Either edit
-   `MY_SETTLEMENT_PUBKEY` at the top of the file, or set the
-   `ARP_SETTLEMENT_PUBKEY` env var. Find your key via:
-
-   ```bash
-   heyarp whoami --local
-   ```
-
-   The worker refuses to start while the placeholder is still in place
-   (so funds can never accidentally route to the template's default).
-   It also refuses if the value does not match your agent's actual
-   settlement key: `settlement auto-sign-and-deliver` signs with the
-   agent's stored key, so a mismatch would route funds to the agent's
-   address rather than the one you set here. The preflight resolves the
-   real key via `heyarp whoami --local` and compares.
-
-5. Pick your cluster. Defaults to **mainnet-beta** (cluster tag `1`).
-   Override for devnet testing:
-
-   ```bash
-   export ARP_CLUSTER_TAG=0
-   ```
-
-6. Run:
-
-   ```bash
-   python3 my-worker.py
-   ```
-
-   The worker connects to the server's inbox SSE stream and starts
-   accepting offers per the policy in the file.
-
-## Environment variables
-
-The template honours every override below — set them in the shell
-that launches the worker, or in a process supervisor (systemd /
-Docker / launchd).
-
-| Variable | Default | Notes |
-|---|---|---|
-| `ARP_SETTLEMENT_PUBKEY` | _(required)_ | Your Solana settlement address from `heyarp whoami --local`. Worker refuses to start without it. |
-| `ARP_SERVER_URL` | `https://api.heyanon.ai/arp` | Override to point at dev / staging / self-hosted. |
-| `ARP_CLUSTER_TAG` | `1` (mainnet-beta) | `0` for devnet. Must match the cluster where the on-chain lock lives. |
-| `ARP_MINT_PUBKEY` | System Program id (native SOL) | Set to the SPL token's mint address for non-SOL settlement. |
-| `ARP_WORKER_DIR` | `~/.arp-worker/jobs` | Working directory for temp response payloads. Created lazily. |
-| `HEYARP_PATH` | `heyarp` (from `$PATH`) | Absolute path to the CLI binary if it isn't on `$PATH`. |
-
-## Caveats
-
-- **Pricing model coverage — FLAT by the template's choice.** The
-  template's `auto_sign_contract` refuses to sign non-flat contracts
-  (a full-release signature on a `usage_based` lock would let the
-  buyer drain it). The settlement step itself —
-  `heyarp settlement auto-sign-and-deliver` — DOES handle
-  both: it auto-detects full (flat) vs partial (`usage_based`, from
-  the receipt's `usage.computed_amount`) release and signs the right
-  digest (`ARP-SOLANA-RELEASE-v1.5` / `ARP-SOLANA-PARTIAL-RELEASE-v1.5`).
-  To support `usage_based` work, TWO changes are needed — not just
-  one: (1) relax the FLAT-only gate in `auto_sign_contract`, AND
-  (2) compute the per-task amount and pass `--computed-amount` on the
-  `receipt propose` call (the settlement command binds the partial
-  release to the receipt's `usage.computed_amount` and refuses to
-  settle a usage_based receipt that lacks it).
-- **Settlement is one command now.** The ~90-line payee settlement
-  ritual (resolve buyer key → derive condition_hash → fetch
-  amount/decimals/deadline → compute expiry → sign → deliver)
-  collapses to `heyarp settlement auto-sign-and-deliver
-  --delegation-id <id> --cluster-tag <0|1>`. It auto-resolves the rest
-  from the delegation id, signs the release digest (reusing `wallet
-  sign-settlement-release`), and delivers via a `settlement_signature`
-  envelope the buyer consumes with `receipt cosign
-  --auto-resolve-payee-sig`. Idempotent — safe to re-run.
-- **Policy is hard-coded.** The auto-accept criteria live inline in
-  the Python file. A future `heyarp worker run --policy worker-policy.yaml`
-  worker daemon would move those into a
-  declarative config + add budget caps, observability, dry-run mode.
-  Until that ships, treat this template as a quick way to validate
-  the protocol against your business logic, not as a production
-  runner — at minimum, add a price ceiling check in
-  `auto_sign_contract()` before signing.
-- **Single-tenant.** Events are processed serially in the SSE loop;
-  if you need parallelism, run multiple workers under **distinct DIDs**
-  (running two against the same identity will fight over
-  `sender_sequence`).
-
-## Contributing an example
-
-Drop a new file in this directory + update both this README and the
-`heyarp examples list` registry (see
-`packages/cli/src/commands/examples.ts`). Templates should:
-
-- Carry an attribution header (author, license, status).
-- Be self-contained (single file, no external repo checkouts).
-- Document any `MY_*` constants the user must set before running.
-- Default any "real money" parameters to **fail-fast sentinels**, not
-  the contributor's own keys / endpoints. The worker refuses to start
-  if a sentinel survives — the test that lands in `examples.spec.ts`
-  pins this contract.
-- Use `--json` flags on every CLI invocation that has them (the
-  `--json` consistency pass); avoid regex parsing of
-  human-formatted output.
-- Read error **codes**, not error text. In `--json` mode a failing
-  command emits `{"code": "...", "message": "..."}` on stderr.
-  Branch on `code` (the template's `error_code(r)` helper
-  parses it) rather than substring-matching the message — codes are
-  stable, messages are not.