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

package/dist/lib/client.js

@@ -1,21 +1,267 @@
 /**
  * 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';
-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 }),
+import { getConfig, resolveAdminConfig } from './config.js';
+import { readSession } from './session.js';
+import { CLIError, ErrorCode } from './errors.js';
+import { withSpinner } from './spinner.js';
+/**
+ * Map MCP server error codes to CLIError categories.
+ * Keeps backward compat: McpError.code is still a free string from the server,
+ * but category and guidance are derived for the global error handler.
+ */
+function mcpCodeToCategory(code) {
+    if (!code)
+        return 'internal';
+    if (code.startsWith('AUTH') || code === 'UNAUTHORIZED')
+        return 'auth';
+    if (code === 'VALIDATION_FAILED')
+        return 'validation';
+    if (code === 'SESSION_REQUIRED')
+        return 'session';
+    return 'internal';
+}
+/** Error thrown by convexCall/convexCallWithSession when the server returns a non-OK response. */
+export class McpError extends CLIError {
+    details;
+    constructor(message, code, details) {
+        super(message, {
+            code: code ?? ErrorCode.INTERNAL,
+            category: mcpCodeToCategory(code),
+        });
+        this.name = 'McpError';
+        this.details = details;
+    }
+}
+// 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;
+        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>`
+            : `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)`;
+        throw new CLIError(`Could not reach ${host}.`, {
+            code: ErrorCode.NETWORK_UNREACHABLE,
+            category: 'network',
+            guidance: proxyHint,
+        });
+    }
+    throw err;
+}
+/**
+ * Validate an API key against the server before saving it.
+ * Uses `resolveWorkspace` as a lightweight health check — if it returns data, the key works.
+ *
+ * Returns { valid: true, workspaceId } on success.
+ * Returns { valid: false, error } on auth failure (401) or other server error.
+ * Throws on network/timeout errors so the caller can distinguish "bad key" from "can't reach server".
+ */
+export async function validateKey(apiKey, siteUrl, timeoutMs = 5000) {
+    return withSpinner('Validating API key', async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(`${siteUrl}/api/aki`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({ fn: 'resolveWorkspace', args: {} }),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (res.status === 401 || res.status === 403) {
+                return { valid: false, error: 'Invalid API key.' };
+            }
+            const json = (await res.json().catch(() => ({})));
+            if (!res.ok || json.ok === false) {
+                return { valid: false, error: json.message || json.error || `Server error (${res.status})` };
+            }
+            return { valid: true, workspaceId: json.data?._id ?? 'unknown' };
+        }
+        catch (err) {
+            clearTimeout(timer);
+            // Re-throw network/timeout errors — caller handles the "offline" case
+            throw err;
+        }
     });
-    const json = (await res.json());
+}
+/**
+ * Map MCP function names to human-friendly spinner labels.
+ * Unknown functions get a generic fallback.
+ */
+const SPINNER_LABELS = {
+    orient: 'Loading workspace overview',
+    'entries.get': 'Loading entry',
+    'entries.search': 'Searching entries',
+    'entries.create': 'Creating entry',
+    'entries.update': 'Updating entry',
+    'capture-quick': 'Capturing to Chain',
+    'propose-capture': 'Preparing capture',
+    'commit-entry': 'Committing entry',
+    'agent.startSession': 'Starting session',
+    'agent.closeSession': 'Closing session',
+    'agent.touchSession': 'Refreshing session',
+    resolveWorkspace: 'Resolving workspace',
+    'onboarding.chat': 'Thinking',
+    context: 'Loading context',
+    'entries.relate': 'Creating relation',
+    'entries.unrelate': 'Removing relation',
+    constellation: 'Loading constellation',
+};
+/** Get a human-friendly spinner label for an MCP function name. */
+export function spinnerLabel(fn) {
+    return SPINNER_LABELS[fn] || `Loading ${fn.replace(/\./g, ' ')}`;
+}
+/**
+ * POST to the admin gateway (/api/admin) — separate from /api/aki (STD-101, BR-109).
+ * Admin operations are not knowledge operations — they target the operator surface.
+ *
+ * No built-in spinner: callers wrap with withSpinner when appropriate.
+ * Throws CLIError on auth failure or non-OK response.
+ */
+export async function adminCall(command, args) {
+    const { apiKey, siteUrl } = resolveAdminConfig();
+    let res;
+    try {
+        res = await fetch(`${siteUrl}/api/admin`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ command, args }),
+        });
+    }
+    catch (err) {
+        rethrowWithGuidance(err, siteUrl);
+    }
+    const json = (await res.json().catch(() => ({})));
     if (!res.ok || json.error) {
-        throw new Error(json.error ?? res.statusText);
+        throw new McpError((json.error ?? res.statusText) || 'Admin request failed', json.code);
     }
     return json.data;
 }
+export async function convexCall(fn, args = {}) {
+    const { apiKey, siteUrl } = getConfig();
+    const label = spinnerLabel(fn);
+    return withSpinner(label, async () => {
+        let res;
+        try {
+            res = await fetch(`${siteUrl}/api/aki`, {
+                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.ok === false) {
+            throw new McpError(json.message || json.error || res.statusText, json.code, json.details);
+        }
+        return json.data;
+    });
+}
+/**
+ * Raw fetch to the gateway — no spinner, swallows errors.
+ * Used for fire-and-forget operations (e.g. session touch) where visible feedback is noise.
+ */
+async function mcpFetchRaw(fn, args, apiKey, siteUrl) {
+    try {
+        await fetch(`${siteUrl}/api/aki`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ fn, args }),
+        });
+    }
+    catch {
+        // Best-effort — silently swallow all errors
+    }
+}
+/**
+ * convexCall 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 convexCallWithSession(fn, args = {}) {
+    const { apiKey, siteUrl } = getConfig();
+    const session = readSession();
+    const label = spinnerLabel(fn);
+    const headers = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (session?.sessionId) {
+        headers['X-Agent-Session-Id'] = session.sessionId;
+    }
+    const result = await withSpinner(label, async () => {
+        let res;
+        try {
+            res = await fetch(`${siteUrl}/api/aki`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ fn, args }),
+            });
+        }
+        catch (err) {
+            rethrowWithGuidance(err, siteUrl);
+        }
+        const json = (await res.json());
+        if (!res.ok || json.ok === false) {
+            throw new McpError(json.message || json.error || res.statusText, json.code, json.details);
+        }
+        return json.data;
+    });
+    // Fire-and-forget session touch — best-effort, never blocks the write response.
+    // Uses mcpFetchRaw (not convexCall) to avoid recursion and suppress the visible spinner
+    // that would appear if convexCall were used here (background ops are silent noise).
+    if (session?.sessionId) {
+        void mcpFetchRaw('agent.touchSession', { sessionId: session.sessionId }, apiKey, siteUrl);
+    }
+    return result;
+}
 //# 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/config.d.ts

@@ -1,13 +1,51 @@
 /**
  * CLI config — reads PRODUCTBRAIN_API_KEY + CONVEX_SITE_URL from:
- * 1. Environment variables
- * 2. ~/.config/productbrain/.env (works from any directory)
- * 3. CWD .env.mcp / packages/mcp-server/.env.mcp / .env
+ * 1. Environment variables (always highest priority)
+ * 2. Project config: .productbrain/config.json in CWD (WP-303 S0)
+ * 3. Profile system (~/.config/productbrain/profiles/{name}.env)
+ * 4. Legacy ~/.config/productbrain/.env (auto-migrated to profiles on first use)
+ * 5. CWD .env.mcp / packages/mcp-server/.env.mcp / .env
+ *
+ * Config loading is lazy — loadEnv() runs on first getConfig()/getConfigOrGuide() call.
+ * This enables profile switching without import-time side effects (TEN-1276).
  *
  * When key is missing and retry is provided (TTY), runs guided flow per docs/cli-unauthenticated-user-journey.md.
  */
 declare const HOME_CONFIG_DIR: string;
 declare const HOME_ENV_PATH: string;
+/** Project config shape — .productbrain/config.json */
+interface ProjectConfig {
+    apiKey?: string;
+    siteUrl?: string;
+    profile?: string;
+}
+/**
+ * Read .productbrain/config.json from CWD.
+ * Returns null if file missing. Warns to stderr on invalid JSON but does not throw.
+ */
+declare function readProjectConfig(): ProjectConfig | null;
+/** Config source in resolution priority order. */
+export type ConfigSource = 'env' | 'project' | 'profile' | 'cwd' | 'default';
+/** Result of the full config resolution cascade. */
+export interface ResolvedConfig {
+    apiKey?: string;
+    siteUrl: string;
+    source: ConfigSource;
+}
+/**
+ * Run the full config resolution cascade and return a typed result.
+ * Resolution order:
+ * 1. Environment variables (highest priority)
+ * 2. Project config (.productbrain/config.json in CWD)
+ * 3. Profile system (~/.config/productbrain/profiles/{name}.env)
+ * 4. Legacy home config (~/.config/productbrain/.env)
+ * 5. CWD .env files (.env.mcp, packages/mcp-server/.env.mcp, .env)
+ *
+ * siteUrl always has a value (falls back to DEFAULT_SITE_URL).
+ */
+export declare function resolveConfig(): ResolvedConfig;
+/** Reset env loaded state — used for profile switching. */
+export declare function resetConfigCache(): void;
 export declare function getConfig(): {
     apiKey: string;
     siteUrl: string;
@@ -16,11 +54,53 @@ export type Config = {
     apiKey: string;
     siteUrl: string;
 };
+/** Discriminated union result for non-throwing config access. */
+export type ConfigResult = {
+    ok: true;
+    apiKey: string;
+    siteUrl: string;
+    source: ConfigSource;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Non-throwing alternative to getConfig().
+ *
+ * Architecture: getConfig() is the primary path for commands that require auth — it
+ * throws CLIError when the key is missing, which is correct for API call paths.
+ * getConfigSafe() is for status/probe surfaces (no-args dashboard, init) that need
+ * to check config availability without crashing. Both paths are intentional and
+ * coexist by design — see WP-303 review (DW#5).
+ *
+ * Uses resolveConfig() directly (no loadEnv) to avoid env var pollution affecting source attribution.
+ */
+export declare function getConfigSafe(): ConfigResult;
 /**
  * Get config; if key is missing and stdin is a TTY, run guided flow (y/n → paste key → save → retry).
  * @param retry Called after saving key so the original command runs in-process.
  * @returns Config, or null if we ran retry (caller should return without running again).
  */
 export declare function getConfigOrGuide(retry: () => Promise<void>): Promise<Config | null>;
-export { HOME_CONFIG_DIR, HOME_ENV_PATH };
+/**
+ * Resolve config for admin operations — profile-only resolution.
+ *
+ * Admin commands (pb admin ...) must NOT read .productbrain/config.json or CWD env files.
+ * The project config intentionally pins the repo to a dev Convex site; admin operations
+ * target PROD workspaces via the operator's active profile. Reading project config here
+ * would silently route admin calls to the wrong gateway (TEN-1334).
+ *
+ * Resolution order:
+ * 1. Shell env vars (PRODUCTBRAIN_API_KEY / CONVEX_SITE_URL) — always win
+ * 2. Active named profile (~/.config/productbrain/profiles/{name}.env)
+ * 3. Legacy home config (~/.config/productbrain/.env)
+ * 4. DEFAULT_SITE_URL as fallback for siteUrl
+ *
+ * Throws CLIError with AUTH_MISSING if no API key is found.
+ */
+export declare function resolveAdminConfig(): {
+    apiKey: string;
+    siteUrl: string;
+};
+export { HOME_CONFIG_DIR, HOME_ENV_PATH, readProjectConfig };
 //# sourceMappingURL=config.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,QAAA,MAAM,eAAe,QAAgD,CAAC;AACtE,QAAA,MAAM,aAAa,QAAmC,CAAC;AA2FvD,wBAAgB,SAAS,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe/D;AAED,MAAM,MAAM,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAczF;AAED,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,QAAA,MAAM,eAAe,QAAgD,CAAC;AACtE,QAAA,MAAM,aAAa,QAAmC,CAAC;AAUvD,uDAAuD;AACvD,UAAU,aAAa;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,iBAAS,iBAAiB,IAAI,aAAa,GAAG,IAAI,CA0BjD;AAED,kDAAkD;AAClD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAE7E,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,IAAI,cAAc,CA8E9C;AA2ED,2DAA2D;AAC3D,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AA6DD,wBAAgB,SAAS,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA0B/D;AAED,MAAM,MAAM,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,iEAAiE;AACjE,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACnE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,IAAI,YAAY,CAiB5C;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBzF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAmDxE;AAED,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,iBAAiB,EAAE,CAAC"}