product-console-companion 0.2.0 → 0.4.0

package/README.md

@@ -55,6 +55,19 @@ Running `connect` again for a different `--connection`/`--path` (same `--url`/`-
 second connection to the same local config; one companion process can serve several repos, each
 with its own backend choice.
 
+To pair this machine before any repo is connected, omit `--connection` and `--path`:
+
+```bash
+npx product-console-companion connect --url https://console.fynchconsulting.com --token <publicId>.<secret> [--api-key sk-ant-...]
+```
+
+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's own local config file, `~/.product-console-companion/config.json`, permissions locked

package/dist/api-key-caller.js

@@ -160,6 +160,28 @@ export async function runGenerateSpecBatchTask(client, task, repoPath) {
     const payload = task.payload;
     const spec = payload.spec;
     const moduleIds = payload.moduleIds;
+    if (payload.connectionless) {
+        // The PRD is already in spec.stableText (stableTextForLocalDispatch); there is nothing local to read.
+        const content = [];
+        if (spec.stableText)
+            content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
+        content.push({ type: 'text', text: spec.volatileText });
+        const writeStream = client.messages.stream({
+            model: spec.model,
+            max_tokens: spec.maxTokens,
+            thinking: { type: 'adaptive' },
+            output_config: spec.schema ? { effort: spec.effort, format: { type: 'json_schema', schema: spec.schema } } : { effort: spec.effort },
+            system: spec.system,
+            messages: [{ role: 'user', content }],
+        });
+        const writeMsg = await writeStream.finalMessage();
+        if (writeMsg.stop_reason === 'refusal')
+            throw new Error('The model declined to write specs for this batch.');
+        const writeText = writeMsg.content.find((b) => b.type === 'text');
+        if (!writeText || writeText.type !== 'text')
+            throw new Error('No specs returned.');
+        return { result: JSON.parse(writeText.text), filesRead: [] };
+    }
     const allFiles = await listRepoFiles(repoPath);
     console.log(`  scanning ${allFiles.length} files in ${repoPath} for ${moduleIds.length} module(s)…`);
     // Pass 1: which files relate to each module in this batch?
@@ -236,10 +258,12 @@ in the same order as given.`;
  * server/index.ts's completeAiJob payloads for /api/setup/skeleton and
  * /api/module-suggestions/scan — neither includes it), so there's nothing meaningful to report.
  */
-async function runShallowRepoTask(client, spec, repoPath) {
-    const repoCtx = await buildLocalRepoContext(repoPath);
-    console.log(`  scanning ${repoCtx.fileList.length} files, README ${repoCtx.readme ? 'found' : 'not found'}, CHANGELOG ${repoCtx.changelog ? 'found' : 'not found'}, package.json ${repoCtx.packageJson ? 'found' : 'not found'}`);
-    const repoSection = `
+async function runShallowRepoTask(client, spec, repoPath, connectionless = false) {
+    let repoSection = '';
+    if (!connectionless) {
+        const repoCtx = await buildLocalRepoContext(repoPath);
+        console.log(`  scanning ${repoCtx.fileList.length} files, README ${repoCtx.readme ? 'found' : 'not found'}, CHANGELOG ${repoCtx.changelog ? 'found' : 'not found'}, package.json ${repoCtx.packageJson ? 'found' : 'not found'}`);
+        repoSection = `
 # Repository context (your local checkout)
 
 ## File tree (${repoCtx.fileList.length} files)
@@ -254,13 +278,14 @@ ${repoCtx.changelog ?? '(none found)'}
 ## package.json
 ${repoCtx.packageJson ?? '(none found)'}
 `.trim();
+    }
     const content = [];
     if (spec.stableDocumentBase64) {
         content.push({ type: 'document', source: { type: 'base64', media_type: 'application/pdf', data: spec.stableDocumentBase64 } });
     }
     if (spec.stableText)
         content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
-    content.push({ type: 'text', text: `${spec.volatileText}\n\n${repoSection}` });
+    content.push({ type: 'text', text: connectionless ? spec.volatileText : `${spec.volatileText}\n\n${repoSection}` });
     const stream = client.messages.stream({
         model: spec.model,
         max_tokens: spec.maxTokens,
@@ -279,7 +304,7 @@ ${repoCtx.packageJson ?? '(none found)'}
 }
 export async function runProposeSkeletonTask(client, task, repoPath) {
     const payload = task.payload;
-    return runShallowRepoTask(client, payload.spec, repoPath);
+    return runShallowRepoTask(client, payload.spec, repoPath, payload.connectionless);
 }
 export async function runProposeNewCapabilitiesTask(client, task, repoPath) {
     const payload = task.payload;

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

@@ -2,7 +2,7 @@
 import Anthropic from '@anthropic-ai/sdk';
 import spawn from 'cross-spawn';
 import { resolve } from 'node:path';
-import { addConnection, configPath, loadConfig } from './config.js';
+import { addConnection, configPath, enableWorkspacePolling, loadConfig } from './config.js';
 import { CompanionClient, CompanionHttpError } from './http-client.js';
 import { assertIsRepo, currentCommit } from './local-scan.js';
 import { runAnalyseShipmentTask, runDesignPromptTask, runGenerateSpecBatchTask, runProposeNewCapabilitiesTask, runProposeSkeletonTask, runVerifyModuleTask } from './api-key-caller.js';
@@ -41,19 +41,17 @@ async function cmdConnect(argv) {
     const url = f.url?.replace(/\/+$/, '');
     const token = f.token;
     const connectionId = f.connection;
-    // --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');
     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
     // before starting one shared `run` for all of them (see the README's own multi-connection note).
     const shouldRunAfter = f['no-run'] !== 'true';
-    if (!url || !token || !connectionId) {
+    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]');
+            '[--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> [--backend api-key|cli] [--api-key <your Anthropic key>] [--no-run]');
         process.exitCode = 1;
         return;
     }
@@ -62,6 +60,39 @@ async function cmdConnect(argv) {
         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();
+        }
+        catch (err) {
+            console.error(`Hmm, that didn't work — could not verify your token against ${url}. Double check you copied the ` +
+                `WHOLE thing, including the part after the dot.`, err instanceof Error ? err.message : err);
+            process.exitCode = 1;
+            return;
+        }
+        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.');
+            return;
+        }
+        console.log('Starting now — Ctrl+C any time to stop.\n');
+        await cmdRun();
+        return;
+    }
+    // --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 || '.');
     try {
         await assertIsRepo(repoPath);
     }
@@ -155,15 +186,16 @@ async function runOneTask(anthropic, backend, client, repoPath, task) {
 }
 async function cmdRun() {
     const config = loadConfig();
-    if (!config || config.connections.length === 0) {
+    if (!config || (config.connections.length === 0 && !config.pollWorkspaceTasks)) {
         console.error(`Nothing set up yet — ${configPath} is missing or empty. Run "connect" first.`);
         process.exitCode = 1;
         return;
     }
-    // Backends are per-connection (chosen at `connect` time) — only require what's actually
-    // configured to run, not every prerequisite either backend could ever need.
-    const needsApiKey = config.connections.some((c) => c.backend !== 'cli');
-    const needsCli = config.connections.some((c) => c.backend === 'cli');
+    // 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 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
@@ -192,11 +224,18 @@ async function cmdRun() {
     const anthropic = needsApiKey ? new Anthropic({ apiKey }) : null;
     const client = new CompanionClient(config.url, config.token);
     await client.whoami();
-    console.log(`Connected to ${config.url}. Watching ${config.connections.length} project${config.connections.length === 1 ? '' : 's'}:`);
+    const projectCount = config.connections.length;
+    const watching = config.pollWorkspaceTasks
+        ? `${projectCount > 0 ? `${projectCount} project${projectCount === 1 ? '' : 's'} and ` : ''}workspace-level tasks`
+        : `${projectCount} project${projectCount === 1 ? '' : 's'}`;
+    console.log(`Connected to ${config.url}. Watching ${watching}:`);
     for (const c of config.connections) {
         const sha = await currentCommit(c.repoPath).catch(() => '(unknown)');
         console.log(`  - ${c.connectionId} → ${c.repoPath} @ ${sha.slice(0, 7)} (${c.backend})`);
     }
+    if (config.pollWorkspaceTasks) {
+        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;
     process.on('SIGINT', () => {
@@ -227,6 +266,25 @@ async function cmdRun() {
             claimedAny = true;
             await runOneTask(anthropic, c.backend, client, c.repoPath, claim.task);
         }
+        if (!stopping && config.pollWorkspaceTasks) {
+            let claim;
+            try {
+                claim = await client.claimNext();
+            }
+            catch (err) {
+                if (err instanceof CompanionHttpError && err.status === 401) {
+                    console.error('Token rejected (revoked?) — stopping. Pair a new token and reconnect.');
+                    return;
+                }
+                console.error('Workspace-level poll failed:', err instanceof Error ? err.message : err);
+                claim = { task: null };
+            }
+            if (claim.task) {
+                claimedAny = true;
+                // Connection-less task kinds do not read a repo; cwd is a harmless placeholder.
+                await runOneTask(anthropic, workspaceBackend, client, process.cwd(), claim.task);
+            }
+        }
         if (!claimedAny && !stopping)
             await new Promise((r) => setTimeout(r, IDLE_POLL_MS));
     }

package/dist/config.js

@@ -27,7 +27,30 @@ export function addConnection(args) {
     const existing = loadConfig();
     const connections = (existing?.connections ?? []).filter((c) => c.connectionId !== args.connection.connectionId);
     connections.push(args.connection);
-    const config = { url: args.url, token: args.token, connections, apiKey: args.apiKey || existing?.apiKey };
+    const config = {
+        url: args.url,
+        token: args.token,
+        connections,
+        apiKey: args.apiKey || existing?.apiKey,
+        pollWorkspaceTasks: existing?.pollWorkspaceTasks,
+        workspaceBackend: existing?.workspaceBackend,
+    };
+    save(config);
+    return config;
+}
+/** Records that this companion should also poll for workspace-level (connection-less) tasks.
+ *  Additive: keeps any existing connections and apiKey; only sets url/token if not already set
+ *  (or if they differ — same rule as addConnection). */
+export function enableWorkspacePolling(args) {
+    const existing = loadConfig();
+    const config = {
+        url: args.url,
+        token: args.token,
+        connections: existing?.connections ?? [],
+        apiKey: args.apiKey || existing?.apiKey,
+        pollWorkspaceTasks: true,
+        workspaceBackend: args.backend || existing?.workspaceBackend,
+    };
     save(config);
     return config;
 }

package/dist/http-client.js

@@ -26,7 +26,7 @@ export class CompanionClient {
         return this.call('/api/companion/whoami');
     }
     claimNext(connectionId) {
-        return this.call(`/api/companion/tasks/next?connectionId=${encodeURIComponent(connectionId)}`);
+        return this.call(connectionId ? `/api/companion/tasks/next?connectionId=${encodeURIComponent(connectionId)}` : '/api/companion/tasks/next');
     }
     heartbeat(taskId) {
         return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/heartbeat`, { method: 'POST' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "product-console-companion",
-  "version": "0.2.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",