@getbags/cash 0.2.1 → 0.3.0

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { checkEndpoint, createDeposit, createKey, discover, getBalance, getFund, getPolicies, getTransactions, listKeys, redeem, revokeKey, registerOrigin, search, setPolicies, listSessions, closeSessions, walletFetch, CliApiError, } from './api.js';
-import { getBaseUrl, getSkillSetupPrompt, getSkillUrl, requireToken, saveCredentials } from './config.js';
+import { getBaseUrl, requireToken, saveCredentials } from './config.js';
+import { formatDoctorSummary, runDoctor } from './doctor.js';
+import { runInitCommand } from './install-command.js';
+import { runStdioServer } from './mcp-server.js';
 import { parseArgs, USAGE } from './parse.js';
 function centsToDollars(cents) {
     return `$${(cents / 100).toFixed(2)}`;
@@ -12,24 +12,6 @@ function fail(message) {
     console.error(message);
     process.exit(1);
 }
-function skillSourcePath() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    return join(here, '..', 'SKILL.md');
-}
-function installSkill() {
-    const cwd = process.cwd();
-    const candidates = [join(cwd, '.cursor', 'skills'), join(cwd, '.claude', 'skills'), join(cwd, '.agents', 'skills')];
-    const parent = candidates.find((dir) => existsSync(dir)) ?? join(cwd, '.agents', 'skills');
-    const destDir = join(parent, 'bags-cash');
-    mkdirSync(destDir, { recursive: true });
-    const dest = join(destDir, 'SKILL.md');
-    const source = skillSourcePath();
-    if (!existsSync(source)) {
-        throw new Error(`bundled SKILL.md not found at ${source}`);
-    }
-    writeFileSync(dest, readFileSync(source, 'utf8'), 'utf8');
-    return dest;
-}
 function printDiscoverTable(endpoints) {
     if (endpoints.length === 0) {
         console.log('(no endpoints)');
@@ -82,9 +64,14 @@ async function main() {
     try {
         switch (parsed.command) {
             case 'redeem': {
-                const result = await redeem(parsed.code);
+                const result = await redeem({
+                    code: parsed.code,
+                    mode: parsed.test ? 'test' : undefined,
+                });
                 saveCredentials(result.token);
-                console.log(`Redeemed. Balance: ${centsToDollars(result.balance_cents)}`);
+                console.log(parsed.test
+                    ? `Sandbox wallet ready. Balance: ${centsToDollars(result.balance_cents)} (test mode — Base Sepolia + Solana devnet only)`
+                    : `Redeemed. Balance: ${centsToDollars(result.balance_cents)}`);
                 console.log('Next steps:');
                 console.log('  npx @getbags/cash balance');
                 console.log('  npx @getbags/cash discover');
@@ -375,10 +362,41 @@ async function main() {
                 return;
             }
             case 'init': {
-                const dest = installSkill();
-                console.log(`Wrote agent skill to ${dest}`);
-                console.log(`Hosted skill: ${getSkillUrl()}`);
-                console.log(`Agent prompt: ${getSkillSetupPrompt()}`);
+                const { exitCode } = runInitCommand({
+                    dryRun: parsed.dryRun,
+                    clients: parsed.clients,
+                    scope: parsed.scope,
+                });
+                if (exitCode !== 0)
+                    process.exit(exitCode);
+                return;
+            }
+            case 'mcp': {
+                // Stdio transport owns stdout for JSON-RPC — never write logs there.
+                try {
+                    await runStdioServer();
+                }
+                catch (err) {
+                    console.error(err instanceof Error ? err.message : String(err));
+                    process.exit(1);
+                }
+                return;
+            }
+            case 'doctor': {
+                const checks = await runDoctor({
+                    scope: parsed.scope,
+                    requestedClients: parsed.clients.length > 0 ? parsed.clients : undefined,
+                });
+                let failed = false;
+                for (const check of checks) {
+                    const mark = check.status === 'pass' ? 'pass' : check.status === 'warn' ? 'WARN' : 'FAIL';
+                    console.log(`[${mark}] ${check.name}: ${check.message}`);
+                    if (check.status === 'fail')
+                        failed = true;
+                }
+                console.log(formatDoctorSummary(checks));
+                if (failed)
+                    process.exit(1);
                 return;
             }
         }

package/dist/install-apply.d.ts

@@ -0,0 +1,29 @@
+import type { PlannedOperation } from './install-plan.js';
+export type ApplyFs = {
+    existsSync: (path: string) => boolean;
+    mkdirSync: (path: string, opts: {
+        recursive: boolean;
+        mode?: number;
+    }) => void;
+    writeFileSync: (path: string, content: string, opts: {
+        encoding: 'utf8';
+        mode?: number;
+    }) => void;
+    copyFileSync: (src: string, dest: string) => void;
+    renameSync: (from: string, to: string) => void;
+    chmodSync: (path: string, mode: number) => void;
+    readFileSync?: (path: string, encoding: 'utf8') => string;
+};
+/** Strip live wallet tokens from backup payloads (defense in depth). */
+export declare function redactSecretsForBackup(content: string): string;
+/**
+ * Execute a plan produced by `planInstall`.
+ * Dry-run is implemented by not calling this function — there is no parallel path.
+ *
+ * Backups go to whatever `backupPath` the planner chose (must be under ~/.bags/backups).
+ * Writes are atomic: temp file in the same directory, then rename into place.
+ */
+export declare function applyInstallPlan(operations: PlannedOperation[], fs?: ApplyFs): {
+    written: string[];
+    backedUp: string[];
+};

package/dist/install-apply.js

@@ -0,0 +1,55 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const defaultFs = {
+    existsSync,
+    mkdirSync: (path, opts) => {
+        mkdirSync(path, opts);
+    },
+    writeFileSync: (path, content, opts) => {
+        writeFileSync(path, content, opts);
+    },
+    copyFileSync,
+    renameSync,
+    chmodSync,
+    readFileSync: (path, encoding) => readFileSync(path, encoding),
+};
+/** Strip live wallet tokens from backup payloads (defense in depth). */
+export function redactSecretsForBackup(content) {
+    return content.replace(/bag_agent_sk_[A-Za-z0-9_]+/g, 'bag_agent_sk_[REDACTED]');
+}
+function readExisting(fs, path) {
+    if (fs.readFileSync)
+        return fs.readFileSync(path, 'utf8');
+    // Fallback for injected fs that only implements copy: copy to a side channel is unavailable.
+    // Tests always provide writeFileSync-backed content via exists + prior writes.
+    throw new Error(`readFileSync required to backup ${path}`);
+}
+/**
+ * Execute a plan produced by `planInstall`.
+ * Dry-run is implemented by not calling this function — there is no parallel path.
+ *
+ * Backups go to whatever `backupPath` the planner chose (must be under ~/.bags/backups).
+ * Writes are atomic: temp file in the same directory, then rename into place.
+ */
+export function applyInstallPlan(operations, fs = defaultFs) {
+    const written = [];
+    const backedUp = [];
+    for (const op of operations) {
+        const dir = dirname(op.path);
+        fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+        if (op.backupPath && fs.existsSync(op.path)) {
+            const backupDir = dirname(op.backupPath);
+            fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+            const raw = readExisting(fs, op.path);
+            const redacted = redactSecretsForBackup(raw);
+            fs.writeFileSync(op.backupPath, redacted, { encoding: 'utf8', mode: 0o600 });
+            fs.chmodSync(op.backupPath, 0o600);
+            backedUp.push(op.backupPath);
+        }
+        const tmpPath = join(dir, `.bags-init-${process.pid}-${Date.now()}.tmp-${Math.random().toString(16).slice(2)}`);
+        fs.writeFileSync(tmpPath, op.content, { encoding: 'utf8', mode: 0o644 });
+        fs.renameSync(tmpPath, op.path);
+        written.push(op.path);
+    }
+    return { written, backedUp };
+}

package/dist/install-command.d.ts

@@ -0,0 +1,17 @@
+import { type ClientId, type InstallScope } from './detect.js';
+export type InitCommandOptions = {
+    dryRun: boolean;
+    clients: ClientId[];
+    scope: InstallScope;
+    cwd?: string;
+    home?: string;
+    /** Override stdout (tests). Defaults to console.log. */
+    log?: (line: string) => void;
+};
+/**
+ * Orchestrate `bags init`: detect clients → snapshot → plan → (optional) apply.
+ * Informational when no client is detected (does not throw).
+ */
+export declare function runInitCommand(opts: InitCommandOptions): {
+    exitCode: number;
+};

package/dist/install-command.js

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { getBaseUrl, loadCredentials } from './config.js';
+import { detectClients } from './detect.js';
+import { applyInstallPlan } from './install-apply.js';
+import { bagsSkillPath, planInstall, } from './install-plan.js';
+function skillSourcePath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', 'SKILL.md');
+}
+function readOptionalFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function loadBundledSkill() {
+    const source = skillSourcePath();
+    if (!existsSync(source)) {
+        throw new Error(`bundled SKILL.md not found at ${source}`);
+    }
+    return readFileSync(source, 'utf8');
+}
+function buildSnapshot(opts) {
+    const env = detectClients({
+        cwd: opts.cwd,
+        home: opts.home,
+        scope: opts.scope,
+        exists: existsSync,
+        requestedClients: opts.requestedClients?.length ? opts.requestedClients : undefined,
+    });
+    const files = {};
+    for (const client of env.clients) {
+        files[client.mcpConfigPath] = readOptionalFile(client.mcpConfigPath);
+        files[bagsSkillPath(client.skillsDir)] = readOptionalFile(bagsSkillPath(client.skillsDir));
+        files[client.instructionsPath] = readOptionalFile(client.instructionsPath);
+    }
+    const token = loadCredentials()?.token ?? null;
+    return {
+        scope: env.scope,
+        cwd: opts.cwd,
+        home: opts.home,
+        clients: env.clients,
+        lookedFor: env.lookedFor,
+        files,
+        hasToken: Boolean(token),
+        skillContent: loadBundledSkill(),
+        targetHost: getBaseUrl(),
+    };
+}
+function summarizeOperation(op) {
+    const backup = op.backupPath ? ` (backup ${op.backupPath})` : ' (new)';
+    return `  ${op.path}${backup}`;
+}
+function clientLabel(id) {
+    switch (id) {
+        case 'cursor':
+            return 'Cursor';
+        case 'claude':
+            return 'Claude Code';
+        case 'codex':
+            return 'Codex';
+    }
+}
+function formatClientList(labels) {
+    if (labels.length === 0)
+        return 'your agent client';
+    if (labels.length === 1)
+        return labels[0];
+    if (labels.length === 2)
+        return `${labels[0]} and ${labels[1]}`;
+    return `${labels.slice(0, -1).join(', ')}, and ${labels[labels.length - 1]}`;
+}
+function clientsWrittenTo(clients, written) {
+    const out = [];
+    for (const client of clients) {
+        const skillPath = bagsSkillPath(client.skillsDir);
+        const hit = written.some((p) => p === client.mcpConfigPath || p === skillPath || p === client.instructionsPath);
+        if (hit && !out.includes(client.client))
+            out.push(client.client);
+    }
+    return out;
+}
+function printNextSteps(opts) {
+    const { log, hasToken } = opts;
+    const names = formatClientList(opts.clientIds.map(clientLabel));
+    const steps = [];
+    if (!hasToken) {
+        steps.push('Run: bags redeem --test (or bags redeem <code>)');
+    }
+    steps.push(opts.clientIds.length > 1
+        ? `Restart ${names} so they pick up the bags-cash MCP server`
+        : `Restart ${names} so it picks up the bags-cash MCP server`);
+    steps.push('Run: bags doctor');
+    log('Next steps:');
+    for (let i = 0; i < steps.length; i++) {
+        log(`  ${i + 1}. ${steps[i]}`);
+    }
+}
+function printPlanSummary(result, opts) {
+    const { log } = opts;
+    for (const line of result.diagnostics) {
+        log(line);
+    }
+    if (result.operations.length === 0) {
+        return;
+    }
+    log(opts.dryRun ? 'Dry run — would write:' : 'Will write:');
+    for (const op of result.operations) {
+        log(summarizeOperation(op));
+    }
+}
+/**
+ * Orchestrate `bags init`: detect clients → snapshot → plan → (optional) apply.
+ * Informational when no client is detected (does not throw).
+ */
+export function runInitCommand(opts) {
+    const log = opts.log ?? ((line) => console.log(line));
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const snapshot = buildSnapshot({
+        cwd,
+        home,
+        scope: opts.scope,
+        requestedClients: opts.clients,
+    });
+    if (snapshot.clients.length === 0) {
+        const plan = planInstall(snapshot);
+        for (const line of plan.diagnostics) {
+            log(line);
+        }
+        return { exitCode: 0 };
+    }
+    const plan = planInstall(snapshot);
+    printPlanSummary(plan, { dryRun: opts.dryRun, log });
+    if (plan.operations.length === 0) {
+        // Diagnostics already said "Already configured" — reinforce per target.
+        for (const client of snapshot.clients) {
+            log(`  ${client.client}: already configured (${client.mcpConfigPath})`);
+        }
+        return { exitCode: 0 };
+    }
+    if (opts.dryRun) {
+        log('Dry run complete — no files written.');
+        return { exitCode: 0 };
+    }
+    const applied = applyInstallPlan(plan.operations);
+    log(`Wrote ${applied.written.length} file(s):`);
+    for (const path of applied.written) {
+        log(`  ${path}`);
+    }
+    if (applied.backedUp.length > 0) {
+        log(`Backed up ${applied.backedUp.length} file(s):`);
+        for (const path of applied.backedUp) {
+            log(`  ${path}`);
+        }
+    }
+    if (applied.written.length > 0) {
+        const clientIds = clientsWrittenTo(snapshot.clients, applied.written);
+        printNextSteps({
+            log,
+            hasToken: snapshot.hasToken,
+            clientIds: clientIds.length > 0 ? clientIds : snapshot.clients.map((c) => c.client),
+        });
+    }
+    return { exitCode: 0 };
+}

package/dist/install-plan.d.ts

@@ -0,0 +1,68 @@
+import type { ClientId, ClientPaths, InstallScope, McpConfigFormat } from './detect.js';
+export declare const BAGS_MCP_SERVER_NAME = "bags-cash";
+export declare const DEFAULT_MCP_STDIO: {
+    readonly command: "npx";
+    readonly args: readonly ["-y", "@getbags/cash", "mcp"];
+};
+export declare const ROUTING_RULE_START = "<!-- bags-cash-init:start -->";
+export declare const ROUTING_RULE_END = "<!-- bags-cash-init:end -->";
+/** Full fenced routing-rule block written into agent instruction files. */
+export declare const ROUTING_RULE_BLOCK: string;
+export type McpStdioEntry = {
+    command: string;
+    args: string[];
+};
+export type PlannedOperation = {
+    path: string;
+    content: string;
+    /** Present when the target already exists and will be overwritten. */
+    backupPath?: string;
+};
+export type InstallPlanResult = {
+    operations: PlannedOperation[];
+    diagnostics: string[];
+};
+export type EnvironmentSnapshot = {
+    scope: InstallScope;
+    cwd: string;
+    home: string;
+    clients: ClientPaths[];
+    lookedFor: string[];
+    /** Current file contents keyed by absolute path; `null` means missing. */
+    files: Record<string, string | null | undefined>;
+    hasToken: boolean;
+    /**
+     * Optional loaded wallet credential (tests / future callers).
+     * planInstall MUST never write this into any planned file — the token stays
+     * in ~/.bags/credentials.json and is read at MCP tool-call time.
+     */
+    loadedCredential?: string;
+    skillContent: string;
+    targetHost: string;
+    /** Unix seconds for backup suffixes; defaults unused when no backups needed. */
+    now?: number;
+    requestedClients?: ClientId[];
+    mcpStdio?: McpStdioEntry;
+};
+/**
+ * Backups live under ~/.bags/backups/ (never next to project configs).
+ * Absolute path is flattened so the original location stays identifiable.
+ */
+export declare function backupPathFor(originalPath: string, home: string, now: number): string;
+/**
+ * Pure install planner. Returns intended file writes (and backup paths) without
+ * touching the filesystem. Re-running against an already-configured snapshot
+ * yields zero operations.
+ */
+export declare function planInstall(snapshot: EnvironmentSnapshot): InstallPlanResult;
+export type BagsMcpEntryStatus = 'missing' | 'clean' | 'dirty';
+/**
+ * Inspect bags-cash MCP registration.
+ * `dirty` = entry exists but carries extra keys (env/headers/url) or wrong shape —
+ * secrets may still be in a committable file; doctor must FAIL and ask for re-init.
+ */
+export declare function inspectBagsMcpEntry(content: string | null | undefined, format: McpConfigFormat, expected?: McpStdioEntry): BagsMcpEntryStatus;
+/** True when a clean bags-cash stdio entry is present (no env/headers extras). */
+export declare function mcpConfigHasBagsEntry(content: string | null | undefined, format: McpConfigFormat, expected?: McpStdioEntry): boolean;
+export declare function instructionsHaveRoutingRule(content: string | null | undefined): boolean;
+export declare function bagsSkillPath(skillsDir: string): string;