product-console-companion 0.2.0 → 0.3.0

package/README.md

@@ -55,6 +55,15 @@ 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.
+
 **`--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/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,22 +41,44 @@ 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'];
     // 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> [--api-key <your Anthropic key>] [--no-run]');
         process.exitCode = 1;
         return;
     }
+    if (!connectionId) {
+        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 });
+        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 || '.');
+    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;
@@ -109,23 +131,29 @@ 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 backend === 'cli' ? runVerifyModuleTaskViaCli(task, repoPath) : runVerifyModuleTask(anthropic, task, repoPath); // anthropic is always set for backend 'api-key' — see cmdRun
+        return effectiveBackend === '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 backend === 'cli' ? runGenerateSpecBatchTaskViaCli(task, repoPath) : runGenerateSpecBatchTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runGenerateSpecBatchTaskViaCli(task, repoPath) : runGenerateSpecBatchTask(anthropic, task, repoPath);
     }
     if (task.kind === 'propose_skeleton') {
-        return backend === 'cli' ? runProposeSkeletonTaskViaCli(task, repoPath) : runProposeSkeletonTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runProposeSkeletonTaskViaCli(task, repoPath) : runProposeSkeletonTask(anthropic, task, repoPath);
     }
     if (task.kind === 'propose_new_capabilities') {
-        return backend === 'cli' ? runProposeNewCapabilitiesTaskViaCli(task, repoPath) : runProposeNewCapabilitiesTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runProposeNewCapabilitiesTaskViaCli(task, repoPath) : runProposeNewCapabilitiesTask(anthropic, task, repoPath);
     }
     if (task.kind === 'design_prompt') {
-        return backend === 'cli' ? runDesignPromptTaskViaCli(task, repoPath) : runDesignPromptTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runDesignPromptTaskViaCli(task, repoPath) : runDesignPromptTask(anthropic, task, repoPath);
     }
     if (task.kind === 'analyse_shipment') {
-        return backend === 'cli' ? runAnalyseShipmentTaskViaCli(task, repoPath) : runAnalyseShipmentTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runAnalyseShipmentTaskViaCli(task, repoPath) : runAnalyseShipmentTask(anthropic, task, repoPath);
     }
     throw new Error(`This companion doesn't know how to run task kind "${task.kind}" yet.`);
 }
@@ -155,14 +183,14 @@ 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');
+    // Repo backends are chosen per connection; workspace-level tasks always use api-key. 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');
     // 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
@@ -192,11 +220,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');
+    }
     console.log('Waiting for work — leave this running. Ctrl+C any time to stop.');
     let stopping = false;
     process.on('SIGINT', () => {
@@ -227,6 +262,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, 'api-key', client, process.cwd(), claim.task);
+            }
+        }
         if (!claimedAny && !stopping)
             await new Promise((r) => setTimeout(r, IDLE_POLL_MS));
     }

package/dist/config.js

@@ -27,7 +27,28 @@ 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,
+    };
+    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,
+    };
     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.3.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",