@getbags/cash 0.2.1 → 0.3.1

package/dist/parse.js

@@ -1,4 +1,47 @@
 import { walletDepositsVisible } from './deposits-visible.js';
+const VALID_CLIENTS = ['cursor', 'claude', 'codex'];
+/**
+ * Per-command usage strings - the same text the flag-error paths print, so
+ * `bags <cmd> --help` never disagrees with a bad-flag error.
+ */
+const COMMAND_USAGE = {
+    redeem: 'usage: bags redeem <code> | bags redeem --test',
+    balance: 'usage: bags balance',
+    result: 'usage: bags result <id> [--field path] [--offset N] [--limit N]',
+    discover: 'usage: bags discover [query] [--format json|pretty]',
+    search: 'usage: bags search <query> [--format json|pretty]',
+    check: 'usage: bags check <url> [flags]',
+    fetch: 'usage: bags fetch <url> [flags]',
+    sessions: 'usage: bags sessions list|close [id] [--all --yes]',
+    init: 'usage: bags init [--dry-run] [--client cursor|claude|codex] [--scope project|user]',
+    doctor: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+    fund: 'usage: bags fund [--open] [--create] [--network NAME]',
+    transactions: 'usage: bags transactions [--limit N] [--cursor C] [--format json|pretty]',
+    policies: 'usage: bags policies get|set [--key=value ...]',
+    keys: 'usage: bags keys create|list|revoke',
+    register: 'usage: bags register <origin>',
+    mcp: 'usage: bags mcp',
+};
+function parseClientList(raw) {
+    const parts = raw
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    if (parts.length === 0) {
+        return { error: 'usage: bags init [--client cursor|claude|codex] (repeatable or comma-separated)' };
+    }
+    const out = [];
+    for (const part of parts) {
+        if (part !== 'cursor' && part !== 'claude' && part !== 'codex') {
+            return {
+                error: 'usage: bags init [--client cursor|claude|codex] (repeatable or comma-separated)',
+            };
+        }
+        if (!out.includes(part))
+            out.push(part);
+    }
+    return out;
+}
 function takeFormat(rest, usage) {
     let format = 'pretty';
     const out = [];
@@ -27,13 +70,44 @@ export function parseArgs(argv) {
         return { command: 'help' };
     }
     const [cmd, ...rest] = argv;
+    // -h/--help on any command prints that command's usage (stdout, exit 0).
+    if (rest.includes('-h') || rest.includes('--help')) {
+        const known = cmd in COMMAND_USAGE;
+        if (!known)
+            return { command: 'error', message: `unknown command: ${cmd}` };
+        return { command: 'usage', message: COMMAND_USAGE[cmd] };
+    }
     switch (cmd) {
         case 'redeem': {
-            const code = rest[0];
-            if (!code || code.startsWith('-')) {
-                return { command: 'error', message: 'usage: bags redeem <code>' };
+            let code;
+            let test = false;
+            for (const arg of rest) {
+                if (arg === '--test') {
+                    test = true;
+                }
+                else if (arg.startsWith('-')) {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags redeem <code> | bags redeem --test',
+                    };
+                }
+                else if (!code) {
+                    code = arg;
+                }
+                else {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags redeem <code> | bags redeem --test',
+                    };
+                }
             }
-            return { command: 'redeem', code };
+            if (!test && !code) {
+                return {
+                    command: 'error',
+                    message: 'usage: bags redeem <code> | bags redeem --test',
+                };
+            }
+            return { command: 'redeem', code, test };
         }
         case 'balance':
             return { command: 'balance' };
@@ -199,8 +273,145 @@ export function parseArgs(argv) {
             }
             return { command: 'sessions', action, sessionId, channelId, all, yes, format: parsed.format };
         }
-        case 'init':
-            return { command: 'init' };
+        case 'init': {
+            let dryRun = false;
+            let scope = 'user';
+            const clients = [];
+            for (let i = 0; i < rest.length; i++) {
+                const arg = rest[i];
+                if (arg === '--dry-run') {
+                    dryRun = true;
+                }
+                else if (arg === '--scope') {
+                    const value = rest[++i];
+                    if (value !== 'project' && value !== 'user') {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags init [--scope project|user]',
+                        };
+                    }
+                    scope = value;
+                }
+                else if (arg.startsWith('--scope=')) {
+                    const value = arg.slice('--scope='.length);
+                    if (value !== 'project' && value !== 'user') {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags init [--scope project|user]',
+                        };
+                    }
+                    scope = value;
+                }
+                else if (arg === '--client') {
+                    const value = rest[++i];
+                    if (!value) {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags init [--client cursor|claude|codex] (repeatable or comma-separated)',
+                        };
+                    }
+                    const parsed = parseClientList(value);
+                    if ('error' in parsed)
+                        return { command: 'error', message: parsed.error };
+                    for (const c of parsed) {
+                        if (!clients.includes(c))
+                            clients.push(c);
+                    }
+                }
+                else if (arg.startsWith('--client=')) {
+                    const parsed = parseClientList(arg.slice('--client='.length));
+                    if ('error' in parsed)
+                        return { command: 'error', message: parsed.error };
+                    for (const c of parsed) {
+                        if (!clients.includes(c))
+                            clients.push(c);
+                    }
+                }
+                else if (arg.startsWith('-')) {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags init [--dry-run] [--client cursor|claude|codex] [--scope project|user]',
+                    };
+                }
+                else {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags init [--dry-run] [--client cursor|claude|codex] [--scope project|user]',
+                    };
+                }
+            }
+            // Keep only known clients (defensive; parseClientList already validates).
+            const filtered = clients.filter((c) => VALID_CLIENTS.includes(c));
+            return { command: 'init', dryRun, clients: filtered, scope };
+        }
+        case 'mcp':
+            return { command: 'mcp' };
+        case 'doctor': {
+            let scope;
+            const clients = [];
+            for (let i = 0; i < rest.length; i++) {
+                const arg = rest[i];
+                if (arg === '--scope') {
+                    const value = rest[++i];
+                    if (value !== 'project' && value !== 'user') {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+                        };
+                    }
+                    scope = value;
+                }
+                else if (arg.startsWith('--scope=')) {
+                    const value = arg.slice('--scope='.length);
+                    if (value !== 'project' && value !== 'user') {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+                        };
+                    }
+                    scope = value;
+                }
+                else if (arg === '--client') {
+                    const value = rest[++i];
+                    if (!value) {
+                        return {
+                            command: 'error',
+                            message: 'usage: bags doctor [--client cursor|claude|codex] (repeatable or comma-separated)',
+                        };
+                    }
+                    const parsed = parseClientList(value);
+                    if ('error' in parsed)
+                        return { command: 'error', message: parsed.error };
+                    for (const c of parsed) {
+                        if (!clients.includes(c))
+                            clients.push(c);
+                    }
+                }
+                else if (arg.startsWith('--client=')) {
+                    const parsed = parseClientList(arg.slice('--client='.length));
+                    if ('error' in parsed)
+                        return { command: 'error', message: parsed.error };
+                    for (const c of parsed) {
+                        if (!clients.includes(c))
+                            clients.push(c);
+                    }
+                }
+                else if (arg.startsWith('-')) {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+                    };
+                }
+                else {
+                    return {
+                        command: 'error',
+                        message: 'usage: bags doctor [--scope project|user] [--client cursor|claude|codex]',
+                    };
+                }
+            }
+            const filtered = clients.filter((c) => VALID_CLIENTS.includes(c));
+            return { command: 'doctor', clients: filtered, scope };
+        }
         case 'fund': {
             let open = false;
             let create = false;
@@ -229,6 +440,34 @@ export function parseArgs(argv) {
             }
             return { command: 'fund', open, create, network };
         }
+        case 'result': {
+            const id = rest[0];
+            if (!id || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(id))
+                return { command: 'error', message: COMMAND_USAGE.result };
+            const out = {
+                command: 'result',
+                id,
+            };
+            for (let i = 1; i < rest.length; i += 2) {
+                const flag = rest[i], value = rest[i + 1];
+                if (!value || !['--field', '--offset', '--limit'].includes(flag))
+                    return { command: 'error', message: COMMAND_USAGE.result };
+                if (flag === '--field')
+                    out.field = value;
+                else {
+                    const n = Number(value);
+                    if (!Number.isSafeInteger(n) ||
+                        n < (flag === '--offset' ? 0 : 1) ||
+                        (flag === '--limit' && n > 100))
+                        return { command: 'error', message: COMMAND_USAGE.result };
+                    if (flag === '--offset')
+                        out.offset = n;
+                    else
+                        out.limit = n;
+                }
+            }
+            return out;
+        }
         case 'transactions': {
             const parsed = takeFormat(rest, 'usage: bags transactions [--limit N] [--cursor C] [--format json|pretty]');
             if ('error' in parsed)
@@ -439,24 +678,39 @@ Usage:
   npx @getbags/cash <command>
 
 Workflow: balance → discover|search → check → fetch
-MPP streams: fetch (opens session) → sessions close
+MPP: one-shot tempo:charge; new hosted sessions are unavailable
 
 Commands:
   redeem <code>                 Redeem an invite code and save the wallet token
+  redeem --test                 Mint a sandbox wallet (no invite; Base Sepolia + Solana devnet)
   balance                       Show wallet balance and caps
-${fundLine}  discover [query]              List BAGS merchant endpoints (BAGS first)
+${fundLine}  discover [query]              List BAGS merchant endpoints (BAGS first; includes \$0.01 /api/v1)
   search <query>                NL search: BAGS catalog + ecosystem index
   check <url>                   Probe an endpoint for schema + exact quote (no pay)
   fetch <url> [flags]           Pay and proxy an x402 / MPP endpoint
-  sessions list|close           List or close open MPP tempo:session channels
+  sessions list                 List existing MPP session reservations
+  sessions close <id>           Request cleanup; unsupported close preserves the hold
+  result <id> [flags]           Read retained output without another payment
   transactions                  List wallet ledger / spend history
   policies get|set              Read or update spend policies
   keys create|list|revoke       Manage per-agent wallet keys
   register <origin>             Register an origin into the discover index
-  init                          Install the bags-cash agent skill into this repo
+  init [flags]                  Register MCP + skill + routing rule for detected clients
+  mcp                           Serve wallet tools over stdio (JSON-RPC on stdout)
+  doctor [flags]                Verify token, MCP registration, skill, and routing rule
+
+Init flags:
+  --dry-run                     Print the plan without writing files
+  --client <name>               Force cursor|claude|codex even without a marker dir (repeatable)
+  --scope project|user          Config scope (default: user — ambient on this machine)
+
+Doctor flags:
+  --client <name>               Target cursor|claude|codex (repeatable or comma-separated)
+  --scope project|user          Check one scope (default: both project and user)
 
 Hosted skill (prompt paste):
   Set up https://www.getbags.app/wallet/skill.md
+  Human install: https://www.getbags.app/wallet/install
   Onboard: https://www.getbags.app/wallet/onboard
 
 Fetch / check flags:
@@ -466,10 +720,17 @@ Fetch / check flags:
   --payment-protocol x402|mpp|auto  Force rail (default: auto)
   --format json|pretty          Machine or human output
 
-Sessions:
-  bags sessions list
-  bags sessions close <id>      Close one channel (session uuid or channel id)
-  bags sessions close --all --yes
+Result flags:
+  --field <path>                Select a retained field (e.g. response.items)
+  --offset <N>                  Array offset (default: 0)
+  --limit <N>                   Array page size (1–100; default: 20)
+
+Sessions (existing holds only; hosted close currently reports unsupported):
+  npx @getbags/cash sessions list
+  npx @getbags/cash sessions close <id>
+  npx @getbags/cash sessions close --all --yes
+
+Alias: after \`npm i -g @getbags/cash\`, \`bags\` is equivalent to \`npx @getbags/cash\`.
 
 Env:
   BAGS_API_URL                  API base URL (default: https://www.getbags.app)

package/dist/policies.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Client-side policy patch construction for `bags policies set`.
+ *
+ * The wallet policies route validates a snake_case PatchSchema
+ * (src/app/api/wallet/policies/route.ts). Zod strips unknown keys there, so a
+ * misspelled or wrong-case flag used to return 200 with an unchanged policy —
+ * a silent no-op. This module normalizes every accepted spelling to
+ * snake_case and rejects unrecognized keys before the request leaves the CLI.
+ */
+export declare class PolicyPatchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Normalize a flag key to the server's snake_case spelling.
+ * Accepts kebab-case (`per-call-cap-cents`), camelCase (`perCallCapCents`),
+ * and snake_case (`per_call_cap_cents`).
+ */
+export declare function policyKeyToSnake(key: string): string;
+/**
+ * Build the PATCH body for `bags policies set --key=value ...`.
+ *
+ * Values coerce like before: integer-looking strings become numbers,
+ * `true`/`false` become booleans, anything else stays a string. Unknown keys
+ * throw (the server would silently strip them and report success).
+ */
+export declare function policyPatchFromSets(sets: Record<string, string>): Record<string, unknown>;

package/dist/policies.js

@@ -0,0 +1,69 @@
+/**
+ * Client-side policy patch construction for `bags policies set`.
+ *
+ * The wallet policies route validates a snake_case PatchSchema
+ * (src/app/api/wallet/policies/route.ts). Zod strips unknown keys there, so a
+ * misspelled or wrong-case flag used to return 200 with an unchanged policy —
+ * a silent no-op. This module normalizes every accepted spelling to
+ * snake_case and rejects unrecognized keys before the request leaves the CLI.
+ */
+/**
+ * Exact keys the server PatchSchema accepts. Keep in sync with
+ * src/app/api/wallet/policies/route.ts.
+ */
+const VALID_POLICY_KEYS = new Set([
+    'per_call_cap_cents',
+    'daily_cap_cents',
+    'weekly_cap_cents',
+    'monthly_cap_cents',
+    'total_cap_cents',
+    'human_approval_threshold_cents',
+    'origin_allowlist',
+    'origin_blocklist',
+    'status',
+]);
+export class PolicyPatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PolicyPatchError';
+    }
+}
+/**
+ * Normalize a flag key to the server's snake_case spelling.
+ * Accepts kebab-case (`per-call-cap-cents`), camelCase (`perCallCapCents`),
+ * and snake_case (`per_call_cap_cents`).
+ */
+export function policyKeyToSnake(key) {
+    return key
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/-/g, '_')
+        .toLowerCase();
+}
+/**
+ * Build the PATCH body for `bags policies set --key=value ...`.
+ *
+ * Values coerce like before: integer-looking strings become numbers,
+ * `true`/`false` become booleans, anything else stays a string. Unknown keys
+ * throw (the server would silently strip them and report success).
+ */
+export function policyPatchFromSets(sets) {
+    const patch = {};
+    for (const [key, value] of Object.entries(sets)) {
+        const snake = policyKeyToSnake(key);
+        if (!VALID_POLICY_KEYS.has(snake)) {
+            throw new PolicyPatchError(`unknown policy key: ${key}. ` +
+                `Valid keys: ${[...VALID_POLICY_KEYS].join(', ')}. ` +
+                `Example: bags policies set --per-call-cap-cents=100`);
+        }
+        const num = Number(value);
+        patch[snake] =
+            Number.isFinite(num) && String(num) === value
+                ? num
+                : value === 'true'
+                    ? true
+                    : value === 'false'
+                        ? false
+                        : value;
+    }
+    return patch;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getbags/cash",
-  "version": "0.2.1",
-  "description": "BAGS Cash CLI — hosted agent wallet for x402 (balance → discover → check → fetch)",
+  "version": "0.3.1",
+  "description": "BAGS Cash CLI \u2014 hosted agent wallet for x402 (balance \u2192 discover \u2192 check \u2192 fetch)",
   "type": "module",
   "bin": {
     "bags": "dist/index.js"
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "vitest run",
+    "test": "bun run build && vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "bun run build"
   },
@@ -38,9 +38,14 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "^4.6.5"
+  },
   "devDependencies": {
     "@types/node": "^25.0.3",
     "typescript": "6.0.2",
-    "vitest": "^4.0.18"
-  }
+    "vitest": "^5.0.3"
+  },
+  "packageManager": "bun@1.4.2"
 }