product-console-companion 0.3.0 → 0.4.0

package/README.md

@@ -63,6 +63,10 @@ npx product-console-companion connect --url https://console.fynchconsulting.com
 
 This runs your workspace's PRD-only setup AI calls when there is no repo yet. `run` then polls
 for workspace-level tasks in addition to any per-repo connections configured on this machine.
+Pass `--backend cli` to use your Claude subscription for these repo-less tasks too. This mode
+runs with zero filesystem access (stricter than the repo-scoped `cli` backend, because there is
+nothing to read). PDF-format PRDs cannot be delivered to the `cli` backend yet; use `api-key`,
+or re-upload the PRD as `.md`, `.txt`, or `.docx`.
 
 **`--backend api-key`** (default) needs an Anthropic API key (get one free at
 console.anthropic.com) — either pass it inline with `--api-key sk-ant-...` (saved to this

package/dist/claude-cli-caller.js

@@ -11,6 +11,7 @@
  * during development, not guessed from --help text alone — see the Phase 2 PR description.
  */
 import spawn from 'cross-spawn';
+import { tmpdir } from 'node:os';
 import { createInterface } from 'node:readline';
 import { createSandbox } from './sandbox.js';
 import { appendDiffToVolatile, prepareShipmentAnalysis } from './shipment.js';
@@ -26,13 +27,18 @@ function normalizeToRepoRelative(filePath, root) {
     const r = root.replace(/\\/g, '/');
     return (p.startsWith(r) ? p.slice(r.length) : p).replace(/^\/+/, '');
 }
-/** The actual invocation — task-kind-agnostic. Runs `spec` against a disposable sandbox
- *  worktree of `repoPath`, returns whatever structured_output the model produced plus every
- *  file it actually read via the Read tool. Every exported per-kind function below is a thin
- *  wrapper over this: extract a ModelTaskSpec from that kind's own payload shape, call this,
- *  return what it returns. */
-async function runViaCli(spec, maxBudgetUsd, repoPath) {
-    const sandbox = await createSandbox(repoPath);
+/** The actual invocation — task-kind-agnostic. Repo-scoped calls run against a disposable
+ *  sandbox worktree of `repoPath`; connection-less calls grant no tools and need no sandbox.
+ *  Returns whatever structured_output the model produced plus every file it actually read via
+ *  the Read tool. Every exported per-kind function below is a thin wrapper over this. */
+async function runViaCli(spec, maxBudgetUsd, repoPath, connectionless = false) {
+    if (spec.stableDocumentBase64) {
+        throw new Error("This task includes a PDF PRD, which the cli backend can't read yet. Pair with " +
+            '--backend api-key instead, or re-upload the PRD as .md/.txt/.docx.');
+    }
+    const sandbox = connectionless
+        ? { path: tmpdir(), cleanup: async () => { } }
+        : await createSandbox(repoPath);
     try {
         const args = [
             '-p',
@@ -43,10 +49,7 @@ async function runViaCli(spec, maxBudgetUsd, repoPath) {
             '--verbose',
             ...(spec.schema ? ['--json-schema', JSON.stringify(spec.schema)] : []),
             '--restricted',
-            '--tools',
-            'Read,Grep,Glob',
-            '--add-dir',
-            sandbox.path,
+            ...(connectionless ? ['--tools', ''] : ['--tools', 'Read,Grep,Glob', '--add-dir', sandbox.path]),
             '--model',
             spec.model,
             '--effort',
@@ -66,6 +69,8 @@ async function runViaCli(spec, maxBudgetUsd, repoPath) {
         let stderrTail = '';
         let timedOut = false;
         const child = spawn('claude', args, { cwd: sandbox.path });
+        if (spec.stableText)
+            child.stdin.write(spec.stableText + '\n\n');
         child.stdin.write(spec.volatileText);
         child.stdin.end();
         // stdout/stderr are only null when stdio is explicitly configured away from 'pipe' — the
@@ -135,19 +140,17 @@ export async function runVerifyModuleTaskViaCli(task, repoPath) {
     return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
 }
 /** moduleIds isn't needed here the way api-key-caller.ts's batch path needs it (to structure its
- *  own file-select pass) — the CLI does its own exploring in one shot off spec.volatileText
- *  alone, which already names every module in the batch. */
+ *  own file-select pass) — spec.volatileText already names every module in the batch. */
 export async function runGenerateSpecBatchTaskViaCli(task, repoPath) {
     const payload = task.payload;
-    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath, payload.connectionless);
 }
 /** propose_skeleton and propose_new_capabilities are "shallow whole-repo" tasks (see
- *  api-key-caller.ts's own comment on the pair) — for the CLI backend this needs no special
- *  handling at all: --add-dir plus Read/Grep/Glob already lets the model explore the repo
- *  itself, same as verify_module/generate_spec_batch, so these are exactly as thin as those. */
+ *  api-key-caller.ts's own comment on the pair). Repo-scoped calls let the model explore via
+ *  --add-dir plus Read/Grep/Glob; a connection-less skeleton call has no repo to explore. */
 export async function runProposeSkeletonTaskViaCli(task, repoPath) {
     const payload = task.payload;
-    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath, payload.connectionless);
 }
 export async function runProposeNewCapabilitiesTaskViaCli(task, repoPath) {
     const payload = task.payload;

package/dist/cli.js

@@ -42,6 +42,7 @@ async function cmdConnect(argv) {
     const token = f.token;
     const connectionId = f.connection;
     const apiKey = f['api-key'];
+    const backend = (f.backend || 'api-key');
     // Pairing on its own does nothing useful — see cmdRun below — so this defaults to starting
     // right away, which is what someone following the app's own copy-pasted command wants: one
     // paste, and it's working. --no-run is the escape hatch for pairing a second/third project
@@ -50,11 +51,25 @@ async function cmdConnect(argv) {
     if (!url || !token) {
         console.error('Usage: product-console-companion connect --url <your Console link> --token <publicId.secret> --connection <connectionId> ' +
             '[--path <folder — defaults to the folder you\'re in right now>] [--backend api-key|cli] [--api-key <your Anthropic key>] [--no-run]\n' +
-            '   or: product-console-companion connect --url <your Console link> --token <publicId.secret> [--api-key <your Anthropic key>] [--no-run]');
+            '   or: product-console-companion connect --url <your Console link> --token <publicId.secret> [--backend api-key|cli] [--api-key <your Anthropic key>] [--no-run]');
+        process.exitCode = 1;
+        return;
+    }
+    if (backend !== 'api-key' && backend !== 'cli') {
+        console.error(`--backend must be "api-key" or "cli", got "${backend}"`);
         process.exitCode = 1;
         return;
     }
     if (!connectionId) {
+        if (backend === 'cli') {
+            const version = await checkClaudeCliAvailable();
+            if (!version) {
+                console.error('This needs Claude Code installed and you logged into it first: npm install -g @anthropic-ai/claude-code, then run `claude` and follow the login prompt.');
+                process.exitCode = 1;
+                return;
+            }
+            console.log(`Found Claude Code: ${version}`);
+        }
         const client = new CompanionClient(url, token);
         try {
             await client.whoami();
@@ -65,7 +80,7 @@ async function cmdConnect(argv) {
             process.exitCode = 1;
             return;
         }
-        enableWorkspacePolling({ url, token, apiKey });
+        enableWorkspacePolling({ url, token, apiKey, backend });
         console.log(`Connected! This computer will now run AI calls for this workspace's setup (PRD-only) tasks. (Saved to ${configPath}.)`);
         if (!shouldRunAfter) {
             console.log('Run "product-console-companion run" whenever you\'re ready to start.');
@@ -78,12 +93,6 @@ async function cmdConnect(argv) {
     // --path is optional — defaults to wherever this command is actually run from, so "open a
     // terminal in your project's folder, paste this" just works without typing a path at all.
     const repoPath = resolve(f.path || '.');
-    const backend = (f.backend || 'api-key');
-    if (backend !== 'api-key' && backend !== 'cli') {
-        console.error(`--backend must be "api-key" or "cli", got "${backend}"`);
-        process.exitCode = 1;
-        return;
-    }
     try {
         await assertIsRepo(repoPath);
     }
@@ -131,29 +140,23 @@ const HEARTBEAT_MS = 30_000;
  *  each backed by both backends. Grows by one entry per phase, same as the server's own registry
  *  (server/companion.ts's TASK_RESULT_SCHEMAS) — the two lists should always name the same kinds. */
 async function runTask(task, backend, anthropic, repoPath) {
-    const connectionless = task.payload.connectionless === true;
-    const effectiveBackend = connectionless ? 'api-key' : backend;
-    if (connectionless && !anthropic) {
-        throw new Error('This is a connection-less (PRD-only) task, which needs an Anthropic API key. Re-run ' +
-            '`connect` with --api-key <key>, or set ANTHROPIC_API_KEY.');
-    }
     if (task.kind === 'verify_module') {
-        return effectiveBackend === 'cli' ? runVerifyModuleTaskViaCli(task, repoPath) : runVerifyModuleTask(anthropic, task, repoPath); // anthropic is always set for backend 'api-key' — see cmdRun
+        return backend === 'cli' ? runVerifyModuleTaskViaCli(task, repoPath) : runVerifyModuleTask(anthropic, task, repoPath); // anthropic is always set for backend 'api-key' — see cmdRun
     }
     if (task.kind === 'generate_spec_batch') {
-        return effectiveBackend === 'cli' ? runGenerateSpecBatchTaskViaCli(task, repoPath) : runGenerateSpecBatchTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runGenerateSpecBatchTaskViaCli(task, repoPath) : runGenerateSpecBatchTask(anthropic, task, repoPath);
     }
     if (task.kind === 'propose_skeleton') {
-        return effectiveBackend === 'cli' ? runProposeSkeletonTaskViaCli(task, repoPath) : runProposeSkeletonTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runProposeSkeletonTaskViaCli(task, repoPath) : runProposeSkeletonTask(anthropic, task, repoPath);
     }
     if (task.kind === 'propose_new_capabilities') {
-        return effectiveBackend === 'cli' ? runProposeNewCapabilitiesTaskViaCli(task, repoPath) : runProposeNewCapabilitiesTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runProposeNewCapabilitiesTaskViaCli(task, repoPath) : runProposeNewCapabilitiesTask(anthropic, task, repoPath);
     }
     if (task.kind === 'design_prompt') {
-        return effectiveBackend === 'cli' ? runDesignPromptTaskViaCli(task, repoPath) : runDesignPromptTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runDesignPromptTaskViaCli(task, repoPath) : runDesignPromptTask(anthropic, task, repoPath);
     }
     if (task.kind === 'analyse_shipment') {
-        return effectiveBackend === 'cli' ? runAnalyseShipmentTaskViaCli(task, repoPath) : runAnalyseShipmentTask(anthropic, task, repoPath);
+        return backend === 'cli' ? runAnalyseShipmentTaskViaCli(task, repoPath) : runAnalyseShipmentTask(anthropic, task, repoPath);
     }
     throw new Error(`This companion doesn't know how to run task kind "${task.kind}" yet.`);
 }
@@ -188,10 +191,11 @@ async function cmdRun() {
         process.exitCode = 1;
         return;
     }
-    // Repo backends are chosen per connection; workspace-level tasks always use api-key. Only
+    // Repo backends are chosen per connection; workspace-level tasks have their own choice. Only
     // require what's actually configured to run, not every prerequisite either backend could need.
-    const needsApiKey = config.pollWorkspaceTasks || config.connections.some((c) => c.backend !== 'cli');
-    const needsCli = config.connections.some((c) => c.backend === 'cli');
+    const workspaceBackend = config.workspaceBackend ?? 'api-key';
+    const needsApiKey = (config.pollWorkspaceTasks && workspaceBackend !== 'cli') || config.connections.some((c) => c.backend !== 'cli');
+    const needsCli = (config.pollWorkspaceTasks && workspaceBackend === 'cli') || config.connections.some((c) => c.backend === 'cli');
     // config.apiKey (set via `connect --api-key ...`) takes priority over the environment variable
     // — the easier path for someone who'd rather paste their key once into a command than learn
     // what an environment variable is and how to set one on their OS. Both are supported; neither
@@ -230,7 +234,7 @@ async function cmdRun() {
         console.log(`  - ${c.connectionId} → ${c.repoPath} @ ${sha.slice(0, 7)} (${c.backend})`);
     }
     if (config.pollWorkspaceTasks) {
-        console.log('  - workspace-level (connection-less / PRD-only) tasks');
+        console.log(`  - workspace-level (connection-less / PRD-only) tasks (${workspaceBackend})`);
     }
     console.log('Waiting for work — leave this running. Ctrl+C any time to stop.');
     let stopping = false;
@@ -278,7 +282,7 @@ async function cmdRun() {
             if (claim.task) {
                 claimedAny = true;
                 // Connection-less task kinds do not read a repo; cwd is a harmless placeholder.
-                await runOneTask(anthropic, 'api-key', client, process.cwd(), claim.task);
+                await runOneTask(anthropic, workspaceBackend, client, process.cwd(), claim.task);
             }
         }
         if (!claimedAny && !stopping)

package/dist/config.js

@@ -33,6 +33,7 @@ export function addConnection(args) {
         connections,
         apiKey: args.apiKey || existing?.apiKey,
         pollWorkspaceTasks: existing?.pollWorkspaceTasks,
+        workspaceBackend: existing?.workspaceBackend,
     };
     save(config);
     return config;
@@ -48,6 +49,7 @@ export function enableWorkspacePolling(args) {
         connections: existing?.connections ?? [],
         apiKey: args.apiKey || existing?.apiKey,
         pollWorkspaceTasks: true,
+        workspaceBackend: args.backend || existing?.workspaceBackend,
     };
     save(config);
     return config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "product-console-companion",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local-first BYOS companion for the Fynch Product Console — reads code and runs AI calls from your own machine instead of the hosted server.",
   "type": "module",
   "license": "MIT",