@getbags/cash 0.2.1 → 0.3.1

package/dist/doctor.d.ts

@@ -0,0 +1,47 @@
+import { type BalanceResponse } from './api.js';
+import { type ClientId, type ClientPaths, type DetectedEnvironment, type InstallScope } from './detect.js';
+export type DoctorStatus = 'pass' | 'fail' | 'warn';
+export type DoctorCheck = {
+    name: string;
+    status: DoctorStatus;
+    message: string;
+};
+export type DoctorFs = {
+    existsSync: (path: string) => boolean;
+    readFileSync: (path: string, encoding: 'utf8') => string;
+};
+export type DoctorDeps = {
+    cwd?: string;
+    home?: string;
+    /** When set, check only this scope. When omitted, check both project and user. */
+    scope?: InstallScope;
+    requestedClients?: ClientId[];
+    fs?: DoctorFs;
+    loadToken?: () => string | null;
+    fetchBalance?: (token: string) => Promise<BalanceResponse>;
+    detect?: (opts: {
+        cwd: string;
+        home: string;
+        scope: InstallScope;
+        exists: (path: string) => boolean;
+        requestedClients?: ClientId[];
+    }) => DetectedEnvironment;
+    instructionsConstant?: string;
+};
+export declare function checkTokenPresent(token: string | null): DoctorCheck;
+export declare function checkBalanceReadable(token: string | null, fetchBalance: (token: string) => Promise<BalanceResponse>): Promise<DoctorCheck>;
+export declare function checkMcpEntry(client: ClientPaths, scope: InstallScope, fs: DoctorFs): DoctorCheck;
+export declare function checkSkillInstalled(client: ClientPaths, scope: InstallScope, fs: DoctorFs): DoctorCheck;
+export declare function checkRoutingRule(client: ClientPaths, scope: InstallScope, fs: DoctorFs): DoctorCheck;
+export declare function checkInstructionsConstant(text?: string): DoctorCheck;
+/**
+ * One-line summary distinguishing agent visibility from wallet funding.
+ * Doctor's entire purpose is this distinction.
+ */
+export declare function formatDoctorSummary(checks: DoctorCheck[]): string;
+/**
+ * Run all doctor checks. Distinguishes "installed but not visible to agents"
+ * (MCP/skill/routing fails) from "visible but unfunded" (token/balance fails).
+ * By default checks both project and user scopes.
+ */
+export declare function runDoctor(deps?: DoctorDeps): Promise<DoctorCheck[]>;

package/dist/doctor.js

@@ -0,0 +1,212 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { getBalance } from './api.js';
+import { loadCredentials } from './config.js';
+import { detectClients, } from './detect.js';
+import { WALLET_MCP_INSTRUCTIONS } from './mcp-instructions.js';
+import { bagsSkillPath, inspectBagsMcpEntry, instructionsHaveRoutingRule } from './install-plan.js';
+const defaultFs = {
+    existsSync,
+    readFileSync: (path, encoding) => readFileSync(path, encoding),
+};
+function readText(fs, path) {
+    if (!fs.existsSync(path))
+        return null;
+    try {
+        return fs.readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function checkName(kind, client, scope) {
+    return `${kind}:${client}:${scope}`;
+}
+export function checkTokenPresent(token) {
+    if (token && token.length > 0) {
+        return { name: 'token', status: 'pass', message: 'wallet token present in credentials store' };
+    }
+    return {
+        name: 'token',
+        status: 'fail',
+        message: 'no wallet token; run: bags redeem --test (or bags redeem <code>)',
+    };
+}
+export async function checkBalanceReadable(token, fetchBalance) {
+    if (!token) {
+        return {
+            name: 'balance',
+            status: 'fail',
+            message: 'skipped — no token (cannot read balance/caps)',
+        };
+    }
+    try {
+        const bal = await fetchBalance(token);
+        if (bal.balance_cents <= 0) {
+            return {
+                name: 'balance',
+                status: 'warn',
+                message: `balance 0¢ (unfunded), per-call cap ${bal.per_call_cap_cents}¢, daily cap ${bal.daily_cap_cents}¢, status ${bal.status} — redeem another invite or run: bags redeem --test`,
+            };
+        }
+        return {
+            name: 'balance',
+            status: 'pass',
+            message: `balance ${bal.balance_cents}¢, per-call cap ${bal.per_call_cap_cents}¢, daily cap ${bal.daily_cap_cents}¢, status ${bal.status}`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'balance',
+            status: 'fail',
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export function checkMcpEntry(client, scope, fs) {
+    const content = readText(fs, client.mcpConfigPath);
+    const name = checkName('mcp', client.client, scope);
+    const status = inspectBagsMcpEntry(content, client.mcpConfigFormat);
+    if (status === 'clean') {
+        return {
+            name,
+            status: 'pass',
+            message: `bags-cash MCP entry present in ${client.mcpConfigPath}`,
+        };
+    }
+    if (status === 'dirty') {
+        return {
+            name,
+            status: 'fail',
+            message: `bags-cash MCP entry in ${client.mcpConfigPath} has env/headers/extra keys (possible secret) — re-run bags init to strip them`,
+        };
+    }
+    return {
+        name,
+        status: 'fail',
+        message: `bags-cash MCP entry missing in ${client.mcpConfigPath}`,
+    };
+}
+export function checkSkillInstalled(client, scope, fs) {
+    const path = bagsSkillPath(client.skillsDir);
+    const name = checkName('skill', client.client, scope);
+    if (fs.existsSync(path)) {
+        return {
+            name,
+            status: 'pass',
+            message: `skill present at ${path}`,
+        };
+    }
+    return {
+        name,
+        status: 'fail',
+        message: `skill missing at ${path}`,
+    };
+}
+export function checkRoutingRule(client, scope, fs) {
+    const content = readText(fs, client.instructionsPath);
+    const name = checkName('routing', client.client, scope);
+    if (instructionsHaveRoutingRule(content)) {
+        return {
+            name,
+            status: 'pass',
+            message: `routing-rule block present in ${client.instructionsPath}`,
+        };
+    }
+    return {
+        name,
+        status: 'fail',
+        message: `routing-rule block missing in ${client.instructionsPath}`,
+    };
+}
+export function checkInstructionsConstant(text = WALLET_MCP_INSTRUCTIONS) {
+    if (typeof text === 'string' && text.trim().length > 0) {
+        return {
+            name: 'instructions',
+            status: 'pass',
+            message: 'WALLET_MCP_INSTRUCTIONS constant is non-empty',
+        };
+    }
+    return {
+        name: 'instructions',
+        status: 'fail',
+        message: 'WALLET_MCP_INSTRUCTIONS constant is empty — MCP auto-pick will not work',
+    };
+}
+/**
+ * One-line summary distinguishing agent visibility from wallet funding.
+ * Doctor's entire purpose is this distinction.
+ */
+export function formatDoctorSummary(checks) {
+    const visibility = checks.filter((c) => /^(mcp|skill|routing):/.test(c.name));
+    const visible = visibility.length > 0 && visibility.some((c) => c.status === 'pass');
+    const visibilityOk = visibility.length > 0 && visibility.every((c) => c.status === 'pass');
+    const balance = checks.find((c) => c.name === 'balance');
+    const token = checks.find((c) => c.name === 'token');
+    const funded = balance?.status === 'pass' && token?.status === 'pass';
+    if (visibilityOk && funded) {
+        return 'Summary: wallet is visible to agents and funded.';
+    }
+    if (visible && !funded) {
+        return 'Summary: wallet is visible to agents but unfunded (or token/balance check failed) — visibility ≠ funding.';
+    }
+    if (!visible && funded) {
+        return 'Summary: wallet is funded but not visible to agents — run bags init (try --scope user).';
+    }
+    if (visibility.length === 0) {
+        return 'Summary: no agent client detected — install Cursor/Claude/Codex or pass --client to force-create, then bags init.';
+    }
+    return 'Summary: wallet is not fully visible to agents and funding is not confirmed — fix FAIL/WARN checks above.';
+}
+/**
+ * Run all doctor checks. Distinguishes "installed but not visible to agents"
+ * (MCP/skill/routing fails) from "visible but unfunded" (token/balance fails).
+ * By default checks both project and user scopes.
+ */
+export async function runDoctor(deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const home = deps.home ?? homedir();
+    const scopes = deps.scope ? [deps.scope] : ['project', 'user'];
+    const fs = deps.fs ?? defaultFs;
+    const detect = deps.detect ?? detectClients;
+    const loadToken = deps.loadToken ?? (() => loadCredentials()?.token ?? null);
+    const fetchBalance = deps.fetchBalance ?? ((token) => getBalance(token));
+    const instructions = deps.instructionsConstant ?? WALLET_MCP_INSTRUCTIONS;
+    const token = loadToken();
+    const checks = [
+        checkTokenPresent(token),
+        await checkBalanceReadable(token, fetchBalance),
+        checkInstructionsConstant(instructions),
+    ];
+    let anyClient = false;
+    const lookedForAll = [];
+    for (const scope of scopes) {
+        const env = detect({
+            cwd,
+            home,
+            scope,
+            exists: (p) => fs.existsSync(p),
+            requestedClients: deps.requestedClients,
+        });
+        for (const p of env.lookedFor) {
+            if (!lookedForAll.includes(p))
+                lookedForAll.push(p);
+        }
+        if (env.clients.length === 0)
+            continue;
+        anyClient = true;
+        for (const client of env.clients) {
+            checks.push(checkMcpEntry(client, scope, fs));
+            checks.push(checkSkillInstalled(client, scope, fs));
+            checks.push(checkRoutingRule(client, scope, fs));
+        }
+    }
+    if (!anyClient) {
+        checks.push({
+            name: 'clients',
+            status: 'fail',
+            message: `no agent client detected (looked for: ${lookedForAll.join(', ') || 'none'})`,
+        });
+    }
+    return checks;
+}

package/dist/errors.d.ts

@@ -1,2 +1,8 @@
 export declare const ERROR_REMEDIES: Record<string, string>;
 export declare function formatApiError(code: string, message: string): string;
+/**
+ * Surface the wallet API's nested upstream diagnostic (data.http_status +
+ * data.response) so PRE_PAYMENT_FAILED failures are legible from the CLI
+ * instead of requiring a raw API call to see why a merchant rejected payment.
+ */
+export declare function withUpstreamDetail(message: string, data: unknown): string;

package/dist/errors.js

@@ -26,3 +26,21 @@ export function formatApiError(code, message) {
     const line = `${code}: ${message}`;
     return remedy ? `${line}\n${remedy}` : line;
 }
+/**
+ * Surface the wallet API's nested upstream diagnostic (data.http_status +
+ * data.response) so PRE_PAYMENT_FAILED failures are legible from the CLI
+ * instead of requiring a raw API call to see why a merchant rejected payment.
+ */
+export function withUpstreamDetail(message, data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return message;
+    const record = data;
+    const status = record.http_status;
+    const response = record.response;
+    if (status === undefined && response === undefined)
+        return message;
+    const body = typeof response === 'string' ? response : response ? JSON.stringify(response) : '';
+    const head = status !== undefined ? `upstream http ${String(status)}` : 'upstream';
+    const detail = body ? `${head}: ${body.slice(0, 300)}` : head;
+    return `${message} (${detail})`;
+}

package/dist/fetch-hints.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fetch output diagnostics for failed paid attempts.
+ *
+ * A paid call can settle on-chain and then hit a merchant 4xx (e.g. a 422 for
+ * a bad request param) — money gone with nothing to show. When the 402
+ * challenge declared a bazaar input schema, point the agent at `bags check`
+ * so the retry carries the required fields.
+ */
+export declare const INPUT_SCHEMA_HINT = "this endpoint declares an input schema - run `bags check` to see required fields";
+/** True when payment settled but the upstream response was an error status. */
+export declare function isFailedPaidAttempt(payment: {
+    paid?: boolean;
+} | null | undefined, httpStatus: number): boolean;
+/** Should `bags fetch` print the input-schema hint for this fetch result? */
+export declare function shouldPrintInputSchemaHint(payment: {
+    paid?: boolean;
+    input_schema_declared?: boolean;
+} | null | undefined, httpStatus: number): boolean;

package/dist/fetch-hints.js

@@ -0,0 +1,17 @@
+/**
+ * Fetch output diagnostics for failed paid attempts.
+ *
+ * A paid call can settle on-chain and then hit a merchant 4xx (e.g. a 422 for
+ * a bad request param) — money gone with nothing to show. When the 402
+ * challenge declared a bazaar input schema, point the agent at `bags check`
+ * so the retry carries the required fields.
+ */
+export const INPUT_SCHEMA_HINT = 'this endpoint declares an input schema - run `bags check` to see required fields';
+/** True when payment settled but the upstream response was an error status. */
+export function isFailedPaidAttempt(payment, httpStatus) {
+    return payment?.paid === true && httpStatus >= 400;
+}
+/** Should `bags fetch` print the input-schema hint for this fetch result? */
+export function shouldPrintInputSchemaHint(payment, httpStatus) {
+    return isFailedPaidAttempt(payment, httpStatus) && payment?.input_schema_declared === true;
+}

package/dist/index.js

@@ -1,35 +1,19 @@
 #!/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 { checkEndpoint, createDeposit, createKey, discover, getBalance, getResult, getFund, getPolicies, getTransactions, listKeys, redeem, revokeKey, registerOrigin, search, setPolicies, listSessions, closeSessions, walletFetch, CliApiError, } from './api.js';
+import { getBaseUrl, loadCredentials, requireToken, saveCredentials } from './config.js';
+import { INPUT_SCHEMA_HINT, shouldPrintInputSchemaHint } from './fetch-hints.js';
+import { formatDoctorSummary, runDoctor } from './doctor.js';
+import { runInitCommand } from './install-command.js';
+import { runStdioServer } from './mcp-server.js';
+import { policyPatchFromSets } from './policies.js';
 import { parseArgs, USAGE } from './parse.js';
 function centsToDollars(cents) {
-    return `$${(cents / 100).toFixed(2)}`;
+    return `$${(cents / 100).toFixed(Number.isInteger(cents) ? 2 : 6).replace(/(\.\d{2,}?)0+$/, '$1')}`;
 }
 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)');
@@ -38,7 +22,9 @@ function printDiscoverTable(endpoints) {
     const rows = endpoints.map((ep) => ({
         url: ep.url,
         method: ep.method,
-        price: typeof ep.price_usd === 'number' ? `$${ep.price_usd.toFixed(2)}` : String(ep.price_usd),
+        price: typeof ep.price_usd === 'number'
+            ? `$${ep.price_usd.toFixed(6).replace(/(\.\d{2,}?)0+$/, '$1')}`
+            : String(ep.price_usd),
         merchant: ep.merchant_name ?? '',
         source: ep.source ?? 'bags',
     }));
@@ -54,37 +40,30 @@ function printDiscoverTable(endpoints) {
 function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
-function policyPatchFromSets(sets) {
-    const patch = {};
-    for (const [key, value] of Object.entries(sets)) {
-        const camel = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-        const num = Number(value);
-        patch[camel] =
-            Number.isFinite(num) && String(num) === value
-                ? num
-                : value === 'true'
-                    ? true
-                    : value === 'false'
-                        ? false
-                        : value;
-    }
-    return patch;
-}
 async function main() {
     const parsed = parseArgs(process.argv.slice(2));
     if (parsed.command === 'help') {
         console.log(USAGE);
         return;
     }
+    if (parsed.command === 'usage') {
+        console.log(parsed.message);
+        return;
+    }
     if (parsed.command === 'error') {
         fail(parsed.message);
     }
     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');
@@ -101,7 +80,7 @@ async function main() {
                 return;
             }
             case 'discover': {
-                const result = await discover(requireToken(), parsed.query);
+                const result = await discover(loadCredentials()?.token ?? '', parsed.query);
                 if (parsed.format === 'json') {
                     printJson(result);
                 }
@@ -111,7 +90,7 @@ async function main() {
                 return;
             }
             case 'search': {
-                const result = await search(requireToken(), parsed.query);
+                const result = await search(loadCredentials()?.token ?? '', parsed.query);
                 if (parsed.format === 'json') {
                     printJson(result);
                 }
@@ -178,7 +157,11 @@ async function main() {
                     payment_protocol: parsed.paymentProtocol,
                 });
                 if (result.payment?.paid) {
-                    console.error(`payment: ${centsToDollars(result.payment.amount_cents)} | tx ${result.payment.tx_hash} | ${result.payment.network}`);
+                    const upstreamNote = result.http_status >= 400 ? ` | upstream HTTP ${result.http_status}` : '';
+                    console.error(`payment: ${centsToDollars(result.payment.amount_cents)} | tx ${result.payment.tx_hash} | ${result.payment.network}${upstreamNote}`);
+                    if (shouldPrintInputSchemaHint(result.payment, result.http_status)) {
+                        console.error(INPUT_SCHEMA_HINT);
+                    }
                 }
                 else if (result.payment) {
                     console.error(`payment: not charged | tx ${result.payment.tx_hash || 'n/a'} | ${result.payment.network || 'n/a'}`);
@@ -242,6 +225,10 @@ async function main() {
                 }
                 return;
             }
+            case 'result': {
+                printJson(await getResult(requireToken(), parsed));
+                return;
+            }
             case 'transactions': {
                 try {
                     const result = await getTransactions(requireToken(), {
@@ -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;
+};