@productbrain/cli 0.1.0-beta.7 → 0.1.0-beta.9

package/dist/index.js

@@ -1,19 +1,44 @@
 #!/usr/bin/env node
 /**
- * Product Brain CLI — read-only Chain knowledge in the terminal.
- * BET-108 Slice 0: pb orient
+ * Product Brain CLI — Chain knowledge + write-back in the terminal.
+ * Read: BET-108. Write: pb session + pb capture (TEN-27, INS-80).
+ * BET-181 Slice 0: global --json / --pretty flags for agent-native output (DEC-299).
  */
 import { Command } from 'commander';
+import { setOutputMode } from './lib/runner.js';
 import { runContext } from './commands/context.js';
-import { runGet } from './commands/get.js';
+import { runGet, runGetMany } from './commands/get.js';
 import { runLogin } from './commands/login.js';
 import { runOrient } from './commands/orient.js';
 import { runSearch } from './commands/search.js';
+import { runHandshake, runHandshakeInit } from './commands/handshake.js';
+import { runSessionStart, runSessionClose, runSessionId } from './commands/session.js';
+import { runCapture } from './commands/capture.js';
+import { runUpdate } from './commands/update.js';
+import { runRelate, runUnrelate } from './commands/relate.js';
+import { runIngest } from './commands/ingest.js';
+import { runFields } from './commands/fields.js';
+import { runConstellation } from './commands/constellation.js';
 const program = new Command();
 program
     .name('pb')
-    .description('Product Brain — read-only CLI for Chain knowledge')
-    .version('0.1.0');
+    .description('Product Brain — Chain knowledge + write-back CLI')
+    .version('0.2.0')
+    // Global output mode flags (DEC-299, BET-181)
+    .option('--json', 'Output machine-readable JSON (overrides TTY auto-detection)')
+    .option('--pretty', 'Force human-readable output even when piped');
+// Apply global output mode BEFORE subcommand actions run
+program.hook('preAction', (thisCommand) => {
+    const globalOpts = program.opts();
+    if (globalOpts.json) {
+        setOutputMode('json');
+    }
+    else if (globalOpts.pretty) {
+        setOutputMode('pretty');
+    }
+    // else: 'auto' (default) — TTY detection handles it
+    void thisCommand;
+});
 program
     .command('get <entry-id>')
     .description('Display full entry by ID (data, relations, last 10 history events)')
@@ -30,9 +55,21 @@ program
         process.exit(1);
     }
 });
+program
+    .command('get-many <entry-ids...>')
+    .description('Fetch multiple entries in parallel (space-separated IDs)')
+    .action(async (entryIds) => {
+    try {
+        await runGetMany({ entryIds: entryIds.map((id) => id.trim()).filter(Boolean) });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
 program
     .command('context <entry-id>')
-    .description('Gather and display constellation context (pipe-friendly markdown when stdout is not a TTY)')
+    .description('Gather and display constellation context (pipe-friendly: JSON when piped, human text in terminal)')
     .action(async (entryId) => {
     if (!entryId?.trim()) {
         program.commands.find((c) => c.name() === 'context')?.help();
@@ -76,6 +113,26 @@ program
         process.exit(1);
     }
 });
+program
+    .command('handshake')
+    .description('Generate context files for AI developer tools (CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md)')
+    .option('--force', 'Overwrite adapter files even if they exist without auto-generated marker')
+    .option('--dry-run', 'Show what would be generated without writing files')
+    .option('--init', 'Set up Claude Code integration: team hooks + personal trust level')
+    .option('--level <level>', 'With --init: trust level (guide|work|silent|full-trust). Without --init: content tier (beginner|intermediate|expert)')
+    .action(async (opts) => {
+    try {
+        if (opts.init) {
+            await runHandshakeInit({ level: opts.level, dryRun: opts.dryRun });
+            return;
+        }
+        await runHandshake({ force: opts.force, dryRun: opts.dryRun, level: opts.level });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
 program
     .command('login')
     .description('Save your API key to ~/.config/productbrain/.env (works from any directory)')
@@ -88,5 +145,173 @@ program
         process.exit(1);
     }
 });
+// --- Write commands (require active session) ---
+const sessionCmd = program
+    .command('session')
+    .description('Manage write sessions (DEC-9: sessions required before write access)');
+sessionCmd
+    .command('start')
+    .description('Start a tracked write session (opens session, refreshes context)')
+    .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
+    .action(async (opts) => {
+    try {
+        await runSessionStart({ json: opts.json });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+sessionCmd
+    .command('id')
+    .description('Print current session ID to stdout (machine-readable, TEN-707)')
+    .action(() => {
+    try {
+        runSessionId();
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+sessionCmd
+    .command('close')
+    .description('Close the active session (wrapup, refresh context)')
+    .option('--force', 'Clear local session state even if server close fails')
+    .action(async (opts) => {
+    try {
+        await runSessionClose({ force: opts.force });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('capture [text...]')
+    .description('Capture knowledge to the Chain (requires active session)')
+    .option('-n, --name <name>', 'Entry name (defaults to capture text)')
+    .option('-d, --description <desc>', 'Entry description (defaults to capture text)')
+    .option('-c, --collection <slug>', 'Explicit collection (skip auto-classification)')
+    .option('-l, --link <entry-id>', 'Link new entry to an existing entry (TEN-705)')
+    .option('-t, --type <relation-type>', 'Relation type for --link (default: surfaces_tension_in)')
+    .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
+    .action(async (textParts = [], opts) => {
+    const text = textParts.join(' ').trim();
+    if (!text && !opts.name) {
+        program.commands.find((c) => c.name() === 'capture')?.help();
+        return;
+    }
+    try {
+        await runCapture({
+            text: text || opts.name || '',
+            name: opts.name,
+            description: opts.description,
+            collection: opts.collection,
+            link: opts.link,
+            type: opts.type,
+            json: opts.json,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// --- Update command (TEN-703) ---
+program
+    .command('update <entry-id>')
+    .description('Update fields on an existing Chain entry (requires active session)')
+    .option('-f, --field <key=value>', 'Set a data field (repeatable)', (val, prev) => [...prev, val], [])
+    .option('--name <name>', 'Update entry name')
+    .option('--status <status>', 'Update entry status (draft | active | deprecated | archived)')
+    .option('--note <text>', 'Change note for history')
+    .action(async (entryId, opts) => {
+    try {
+        await runUpdate({
+            entryId,
+            field: opts.field,
+            name: opts.name,
+            status: opts.status,
+            note: opts.note,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// --- Relate / Unrelate commands (TEN-704) ---
+program
+    .command('relate <from-id> <type> <to-id>')
+    .description('Add a typed relation between two entries (requires active session)')
+    .action(async (fromId, type, toId) => {
+    try {
+        await runRelate({ fromId, type, toId });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+program
+    .command('unrelate <from-id> <type> <to-id>')
+    .description('Remove a typed relation between two entries (requires active session)')
+    .action(async (fromId, type, toId) => {
+    try {
+        await runUnrelate({ fromId, type, toId });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// --- Ingest command (BET-81) ---
+program
+    .command('ingest <pattern>')
+    .description('Bulk ingest documents to Chain as drafts')
+    .action(async (pattern) => {
+    try {
+        await runIngest({ pattern });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// --- Fields command (BET-181 Slice 2) ---
+program
+    .command('fields <collection>')
+    .description('List all field definitions for a collection (schema discovery for agents)')
+    .action(async (collection) => {
+    if (!collection?.trim()) {
+        program.commands.find((c) => c.name() === 'fields')?.help();
+        return;
+    }
+    try {
+        await runFields({ collectionSlug: collection.trim() });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
+// --- Constellation command (BET-181 Slice 3) ---
+program
+    .command('constellation <entry-id>')
+    .description('Compound view: entry + all related entries grouped by relation type (agent-native)')
+    .action(async (entryId) => {
+    if (!entryId?.trim()) {
+        program.commands.find((c) => c.name() === 'constellation')?.help();
+        return;
+    }
+    try {
+        await runConstellation({ entryId: entryId.trim() });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
 program.parse();
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/client.d.ts

@@ -1,5 +1,24 @@
 /**
  * MCP HTTP client — POST to Convex gateway with Bearer auth.
+ *
+ * TEN-729: Detects sandbox-blocked fetch (Claude Code, Cursor, etc.) and
+ * provides an actionable error instead of the opaque "fetch failed".
+ *
+ * Sandbox proxy support: Node.js fetch (undici) ignores proxy env vars by
+ * default. We detect HTTPS_PROXY and configure a ProxyAgent so pb works in
+ * sandboxed environments (Claude Code, Cursor) without requiring
+ * NODE_OPTIONS="--use-env-proxy".
  */
 export declare function mcpCall<T = unknown>(fn: string, args?: Record<string, unknown>): Promise<T>;
+/**
+ * mcpCall variant that injects X-Agent-Session-Id header for write operations.
+ * All write commands (update, relate, unrelate, capture) should use this.
+ *
+ * After a successful write, fires a non-blocking `agent.touchSession` call to
+ * renew the session TTL — mirroring MCP server behavior (DEC-299, BET-181 Slice 1).
+ * The touch is fire-and-forget: it does not block the write response, and errors
+ * are silently swallowed. No touch is attempted if no session is active or if
+ * the write itself fails.
+ */
+export declare function mcpCallWithSession<T = unknown>(fn: string, args?: Record<string, unknown>): Promise<T>;
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EACvC,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAiBZ"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA0CH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EACvC,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAClD,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAoCZ"}

package/dist/lib/client.js

@@ -1,21 +1,115 @@
 /**
  * MCP HTTP client — POST to Convex gateway with Bearer auth.
+ *
+ * TEN-729: Detects sandbox-blocked fetch (Claude Code, Cursor, etc.) and
+ * provides an actionable error instead of the opaque "fetch failed".
+ *
+ * Sandbox proxy support: Node.js fetch (undici) ignores proxy env vars by
+ * default. We detect HTTPS_PROXY and configure a ProxyAgent so pb works in
+ * sandboxed environments (Claude Code, Cursor) without requiring
+ * NODE_OPTIONS="--use-env-proxy".
  */
 import { getConfig } from './config.js';
+import { readSession } from './session.js';
+// Configure proxy at module load — runs once, before any fetch call.
+// Node.js fetch (undici) ignores HTTPS_PROXY env vars. We detect the proxy
+// and install a ProxyAgent as the global dispatcher so all fetch() calls
+// route through the sandbox proxy automatically.
+try {
+    const _proxy = process.env.https_proxy || process.env.HTTPS_PROXY;
+    if (_proxy) {
+        const { ProxyAgent, setGlobalDispatcher } = await import('undici');
+        setGlobalDispatcher(new ProxyAgent(_proxy));
+    }
+}
+catch {
+    // undici unavailable or proxy config failed — rethrowWithGuidance handles it.
+}
+/** Detect a sandbox/network-blocked fetch and re-throw with guidance. */
+function rethrowWithGuidance(err, siteUrl) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg === 'fetch failed' || msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND')) {
+        const host = new URL(siteUrl).hostname;
+        const proxy = process.env.https_proxy || process.env.HTTPS_PROXY;
+        // When a proxy is set, the sandbox is routing traffic through it.
+        // Node.js fetch (undici) does NOT respect proxy env vars by default.
+        // The fix is --use-env-proxy (Node 22.14+), not adding the host to the allowlist.
+        const proxyHint = proxy
+            ? `A proxy is configured (${proxy}) but Node.js fetch() is not using it.\n` +
+                `Fix: set NODE_OPTIONS="--use-env-proxy" in your environment,\n` +
+                `  or re-run with: NODE_OPTIONS="--use-env-proxy" pb <command>\n`
+            : `If you are running inside an AI code editor sandbox (Claude Code, Cursor, etc.),\n` +
+                `the sandbox may be blocking outbound connections.\n\n` +
+                `Fix: add "${host}" to your sandbox network allowlist.\n` +
+                `  • Claude Code: run /sandbox → add network host\n` +
+                `  • Or re-run: pb handshake --init (configures sandbox automatically)\n`;
+        throw new Error(`Could not reach ${host}.\n\n${proxyHint}`);
+    }
+    throw err;
+}
 export async function mcpCall(fn, args = {}) {
     const { apiKey, siteUrl } = getConfig();
-    const res = await fetch(`${siteUrl}/api/mcp`, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${apiKey}`,
-        },
-        body: JSON.stringify({ fn, args }),
-    });
+    let res;
+    try {
+        res = await fetch(`${siteUrl}/api/mcp`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ fn, args }),
+        });
+    }
+    catch (err) {
+        rethrowWithGuidance(err, siteUrl);
+    }
+    const json = (await res.json());
+    if (!res.ok || json.error) {
+        throw new Error(json.error ?? res.statusText);
+    }
+    return json.data;
+}
+/**
+ * mcpCall variant that injects X-Agent-Session-Id header for write operations.
+ * All write commands (update, relate, unrelate, capture) should use this.
+ *
+ * After a successful write, fires a non-blocking `agent.touchSession` call to
+ * renew the session TTL — mirroring MCP server behavior (DEC-299, BET-181 Slice 1).
+ * The touch is fire-and-forget: it does not block the write response, and errors
+ * are silently swallowed. No touch is attempted if no session is active or if
+ * the write itself fails.
+ */
+export async function mcpCallWithSession(fn, args = {}) {
+    const { apiKey, siteUrl } = getConfig();
+    const session = readSession();
+    const headers = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (session?.sessionId) {
+        headers['X-Agent-Session-Id'] = session.sessionId;
+    }
+    let res;
+    try {
+        res = await fetch(`${siteUrl}/api/mcp`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ fn, args }),
+        });
+    }
+    catch (err) {
+        rethrowWithGuidance(err, siteUrl);
+    }
     const json = (await res.json());
     if (!res.ok || json.error) {
         throw new Error(json.error ?? res.statusText);
     }
+    // Fire-and-forget session touch — best-effort, never blocks the write response.
+    // Only touch when a session is active. Uses mcpCall (not mcpCallWithSession) to
+    // avoid recursion.
+    if (session?.sessionId) {
+        mcpCall('agent.touchSession', { sessionId: session.sessionId }).catch(() => { });
+    }
     return json.data;
 }
 //# sourceMappingURL=client.js.map

package/dist/lib/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,EAAU,EACV,OAAgC,EAAE;IAElC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS,EAAE,CAAC;IAExC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,OAAO,UAAU,EAAE;QAC5C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,aAAa,EAAE,UAAU,MAAM,EAAE;SAClC;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;KACnC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiC,CAAC;IAChE,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,CAAC,IAAS,CAAC;AACxB,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"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"}

package/dist/lib/repo-detect.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Local repo detection — reads filesystem signals to build a RepoContext.
+ * No API calls. Pure filesystem inspection.
+ */
+export interface RepoContext {
+    name: string | null;
+    description: string | null;
+    gitRemote: string | null;
+    repoSlug: string | null;
+    detectedStack: string[];
+    isMonorepo: boolean;
+}
+export declare function detectRepo(cwd?: string): RepoContext;
+//# sourceMappingURL=repo-detect.d.ts.map

package/dist/lib/repo-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-detect.d.ts","sourceRoot":"","sources":["../../src/lib/repo-detect.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,UAAU,CAAC,GAAG,SAAgB,GAAG,WAAW,CAiD3D"}

package/dist/lib/repo-detect.js

@@ -0,0 +1,58 @@
+/**
+ * Local repo detection — reads filesystem signals to build a RepoContext.
+ * No API calls. Pure filesystem inspection.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { resolve, basename } from 'path';
+import { execSync } from 'child_process';
+export function detectRepo(cwd = process.cwd()) {
+    const ctx = {
+        name: null,
+        description: null,
+        gitRemote: null,
+        repoSlug: null,
+        detectedStack: [],
+        isMonorepo: false,
+    };
+    // package.json
+    const pkgPath = resolve(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            ctx.name = pkg.name?.replace(/^@[^/]+\//, '') ?? null;
+            ctx.description = pkg.description ?? null;
+            if (pkg.workspaces)
+                ctx.isMonorepo = true;
+        }
+        catch { /* ignore parse errors */ }
+    }
+    // git remote
+    try {
+        const remote = execSync('git remote get-url origin', { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        ctx.gitRemote = remote;
+        // Extract owner/repo from SSH or HTTPS URL
+        const m = remote.match(/[:/]([^/]+\/[^/.]+?)(?:\.git)?$/);
+        if (m)
+            ctx.repoSlug = m[1];
+    }
+    catch { /* not a git repo or no remote */ }
+    // Stack detection
+    const checks = [
+        ['sveltekit', ['svelte.config.js', 'svelte.config.ts']],
+        ['convex', ['convex']],
+        ['typescript', ['tsconfig.json']],
+        ['nextjs', ['next.config.js', 'next.config.ts', 'next.config.mjs']],
+        ['vite', ['vite.config.ts', 'vite.config.js']],
+        ['react', ['src/App.tsx', 'src/App.jsx']],
+    ];
+    for (const [tech, paths] of checks) {
+        if (paths.some((p) => existsSync(resolve(cwd, p)))) {
+            ctx.detectedStack.push(tech);
+        }
+    }
+    // Fallback name from directory
+    if (!ctx.name)
+        ctx.name = basename(cwd);
+    return ctx;
+}
+//# sourceMappingURL=repo-detect.js.map

package/dist/lib/repo-detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-detect.js","sourceRoot":"","sources":["../../src/lib/repo-detect.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAWzC,MAAM,UAAU,UAAU,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE;IAC5C,MAAM,GAAG,GAAgB;QACvB,IAAI,EAAE,IAAI;QACV,WAAW,EAAE,IAAI;QACjB,SAAS,EAAE,IAAI;QACf,QAAQ,EAAE,IAAI;QACd,aAAa,EAAE,EAAE;QACjB,UAAU,EAAE,KAAK;KAClB,CAAC;IAEF,eAAe;IACf,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAC7C,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;YACtD,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC;YACtD,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,IAAI,IAAI,CAAC;YAC1C,IAAI,GAAG,CAAC,UAAU;gBAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;IACvC,CAAC;IAED,aAAa;IACb,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,2BAA2B,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACxH,GAAG,CAAC,SAAS,GAAG,MAAM,CAAC;QACvB,2CAA2C;QAC3C,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAC1D,IAAI,CAAC;YAAE,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC,CAAC,iCAAiC,CAAC,CAAC;IAE7C,kBAAkB;IAClB,MAAM,MAAM,GAA8B;QACxC,CAAC,WAAW,EAAE,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,CAAC;QACvD,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC;QACtB,CAAC,YAAY,EAAE,CAAC,eAAe,CAAC,CAAC;QACjC,CAAC,QAAQ,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,CAAC,CAAC;QACnE,CAAC,MAAM,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;QAC9C,CAAC,OAAO,EAAE,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;KAC1C,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACnC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAExC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/lib/runner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * runCliCommand — shared command runner for the Product Brain CLI.
+ *
+ * Owns:
+ *   (a) TTY detection via process.stdout.isTTY
+ *   (b) JSON vs human output branching
+ *   (c) stripConvexInternals() application in JSON mode
+ *   (d) --json and --pretty explicit overrides that take precedence over auto-detection
+ *   (e) Error handling: JSON error object in JSON mode, formatted message in TTY mode
+ *
+ * Chain: DEC-299 (JSON-default), STD-65 (agent responses: structured, parseable, minimal)
+ */
+export declare function setOutputMode(mode: 'auto' | 'json' | 'pretty'): void;
+export declare function getOutputMode(): 'auto' | 'json' | 'pretty';
+/** Returns true if the current output mode resolves to JSON. */
+export declare function isJsonMode(): boolean;
+export interface RunCliCommandOptions<T> {
+    /** The async function that performs the MCP call and returns data. */
+    fn: () => Promise<T>;
+    /** Formats data for human-readable TTY output. */
+    formatPretty: (data: T) => string;
+}
+/**
+ * Execute a CLI command with unified output handling.
+ *
+ * - JSON mode: strip Convex internals, JSON.stringify to stdout
+ * - Pretty mode: call formatPretty callback, print result
+ * - Errors: JSON error object in JSON mode, plain message in pretty mode
+ */
+export declare function runCliCommand<T>(options: RunCliCommandOptions<T>): Promise<void>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/lib/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/lib/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAEpE;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,MAAM,GAAG,QAAQ,CAE1D;AAED,gEAAgE;AAChE,wBAAgB,UAAU,IAAI,OAAO,CAKpC;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,sEAAsE;IACtE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,kDAAkD;IAClD,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBtF"}

package/dist/lib/runner.js

@@ -0,0 +1,65 @@
+/**
+ * runCliCommand — shared command runner for the Product Brain CLI.
+ *
+ * Owns:
+ *   (a) TTY detection via process.stdout.isTTY
+ *   (b) JSON vs human output branching
+ *   (c) stripConvexInternals() application in JSON mode
+ *   (d) --json and --pretty explicit overrides that take precedence over auto-detection
+ *   (e) Error handling: JSON error object in JSON mode, formatted message in TTY mode
+ *
+ * Chain: DEC-299 (JSON-default), STD-65 (agent responses: structured, parseable, minimal)
+ */
+import { stripConvexInternals } from './strip.js';
+/**
+ * Global output mode — set by the CLI entry point when --json or --pretty flags are parsed.
+ * 'auto' = detect via TTY; 'json' = force JSON; 'pretty' = force human.
+ */
+let outputMode = 'auto';
+export function setOutputMode(mode) {
+    outputMode = mode;
+}
+export function getOutputMode() {
+    return outputMode;
+}
+/** Returns true if the current output mode resolves to JSON. */
+export function isJsonMode() {
+    if (outputMode === 'json')
+        return true;
+    if (outputMode === 'pretty')
+        return false;
+    // auto: non-TTY (piped) → JSON, TTY → human
+    return !process.stdout.isTTY;
+}
+/**
+ * Execute a CLI command with unified output handling.
+ *
+ * - JSON mode: strip Convex internals, JSON.stringify to stdout
+ * - Pretty mode: call formatPretty callback, print result
+ * - Errors: JSON error object in JSON mode, plain message in pretty mode
+ */
+export async function runCliCommand(options) {
+    const json = isJsonMode();
+    try {
+        const data = await options.fn();
+        if (json) {
+            const stripped = stripConvexInternals(data);
+            process.stdout.write(JSON.stringify(stripped) + '\n');
+        }
+        else {
+            const formatted = options.formatPretty(data);
+            process.stdout.write(formatted + '\n');
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (json) {
+            process.stderr.write(JSON.stringify({ error: message }) + '\n');
+        }
+        else {
+            process.stderr.write(message + '\n');
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=runner.js.map