nexus-prime 6.4.0 → 6.6.0

package/dist/agents/adapters/mcp/envelope.d.ts

@@ -35,12 +35,13 @@ export interface RunHandlerOptions {
 /**
  * Convert a HandlerEnvelope into the MCP tool-call response shape.
  *
- * On success, if `envelope.data` is already a ToolResult
- * (`{ content: Array<...> }`), it is returned directly so we never
- * double-wrap handler output.  Any other value is JSON-stringified into a
- * single text content block.
+ * On success:
+ *  - If data is already a ToolResult (`{ content: Array<...> }`), appended footer + pass-through.
+ *  - If data is an array of objects, rendered as ASCII table.
+ *  - If data is a plain object, rendered as key-value rows.
+ *  - If data is a string, returned as-is with footer appended.
  *
- * On error, a structured JSON error block is produced.
+ * On error, a compact human-readable error block is produced.
  */
 export declare function envelopeToMcpResponse<T>(envelope: HandlerEnvelope<T>): {
     content: Array<{

package/dist/agents/adapters/mcp/envelope.js

@@ -5,18 +5,52 @@
  * dashboard routes) can import the type without pulling in the full
  * runHandler runtime.  runHandler.ts re-exports these for back-compat.
  */
+// ─── Pretty-print helpers ─────────────────────────────────────────────────────
+const DASH_PORT = process.env.NEXUS_DASHBOARD_PORT ?? '3377';
+/** Render an array of objects as an aligned ASCII table (max 20 rows × 6 cols). */
+function renderTable(rows, maxRows = 20) {
+    if (rows.length === 0)
+        return '(empty)';
+    const cols = Object.keys(rows[0]).slice(0, 6);
+    const display = rows.slice(0, maxRows);
+    const widths = cols.map(col => Math.max(col.length, ...display.map(r => String(r[col] ?? '').length)));
+    const sep = '─'.repeat(widths.reduce((a, w) => a + w + 3, 1));
+    const header = '│ ' + cols.map((c, i) => c.toUpperCase().padEnd(widths[i])).join(' │ ') + ' │';
+    const dataRows = display.map(r => '│ ' + cols.map((c, i) => String(r[c] ?? '').slice(0, widths[i]).padEnd(widths[i])).join(' │ ') + ' │');
+    const truncNote = rows.length > maxRows ? `\n  … ${rows.length - maxRows} more rows` : '';
+    return [sep, header, sep, ...dataRows, sep].join('\n') + truncNote;
+}
+/** Build a compact timing + savings footer line for tool responses. */
+function buildMcpFooter(meta) {
+    const ms = meta.durationMs;
+    const timing = ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+    return `\n\n─── nexus-prime · ${meta.toolName} · ${timing} · dashboard: http://localhost:${DASH_PORT}/#runtime ───`;
+}
+/** Format a plain object as key: value rows. */
+function renderKV(obj, indent = '  ') {
+    return Object.entries(obj)
+        .filter(([, v]) => v !== null && v !== undefined && v !== '' && !Array.isArray(v))
+        .map(([k, v]) => `${indent}${k.padEnd(22)} ${String(v).slice(0, 120)}`)
+        .join('\n');
+}
+/** Detect if value is an array of objects suitable for table rendering. */
+function isTableData(val) {
+    return Array.isArray(val) && val.length > 0 && typeof val[0] === 'object' && val[0] !== null;
+}
 // ─── Serialisation helper ─────────────────────────────────────────────────────
 /**
  * Convert a HandlerEnvelope into the MCP tool-call response shape.
  *
- * On success, if `envelope.data` is already a ToolResult
- * (`{ content: Array<...> }`), it is returned directly so we never
- * double-wrap handler output.  Any other value is JSON-stringified into a
- * single text content block.
+ * On success:
+ *  - If data is already a ToolResult (`{ content: Array<...> }`), appended footer + pass-through.
+ *  - If data is an array of objects, rendered as ASCII table.
+ *  - If data is a plain object, rendered as key-value rows.
+ *  - If data is a string, returned as-is with footer appended.
  *
- * On error, a structured JSON error block is produced.
+ * On error, a compact human-readable error block is produced.
  */
 export function envelopeToMcpResponse(envelope) {
+    const footer = buildMcpFooter(envelope.meta);
     if (envelope.ok) {
         const data = envelope.data;
         // Pass-through: handler already returned a ToolResult-shaped object.
@@ -24,22 +58,54 @@ export function envelopeToMcpResponse(envelope) {
             data !== undefined &&
             typeof data === 'object' &&
             Array.isArray(data.content)) {
-            return data;
+            const result = data;
+            // Append footer to last text block
+            const last = result.content[result.content.length - 1];
+            if (last?.type === 'text') {
+                last.text += footer;
+            }
+            return result;
+        }
+        let text;
+        if (typeof data === 'string') {
+            text = data + footer;
+        }
+        else if (isTableData(data)) {
+            // Array of objects → ASCII table
+            const noun = envelope.meta.toolName.replace('nexus_list_', '').replace('nexus_', '');
+            text = `⚡ ${envelope.meta.toolName} · ${data.length} ${noun}\n\n${renderTable(data)}\n${footer}`;
+        }
+        else if (data !== null && data !== undefined && typeof data === 'object') {
+            // Plain object → key-value rows (compact, no JSON noise)
+            const obj = data;
+            // Check for a nested array payload (e.g. { skills: [...] })
+            const arrayKey = Object.keys(obj).find(k => isTableData(obj[k]));
+            if (arrayKey) {
+                const rows = obj[arrayKey];
+                const rest = Object.entries(obj).filter(([k]) => k !== arrayKey);
+                const kvSection = rest.length > 0 ? renderKV(Object.fromEntries(rest)) + '\n\n' : '';
+                text = `⚡ ${envelope.meta.toolName} · ${rows.length} ${arrayKey}\n\n${kvSection}${renderTable(rows)}${footer}`;
+            }
+            else {
+                // Flat KV display — avoids raw JSON blobs
+                const kvText = renderKV(obj);
+                text = `⚡ ${envelope.meta.toolName}\n\n${kvText || JSON.stringify(data, null, 2)}${footer}`;
+            }
+        }
+        else {
+            text = String(data ?? '') + footer;
         }
-        const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
         return { content: [{ type: 'text', text }] };
     }
-    return {
-        content: [{
-                type: 'text',
-                text: JSON.stringify({
-                    status: 'error',
-                    code: envelope.error.code,
-                    message: envelope.error.message,
-                    retriable: envelope.error.retriable,
-                    hint: envelope.error.hint,
-                    meta: envelope.meta,
-                }, null, 2),
-            }],
-    };
+    // Error: compact human-readable format
+    const err = envelope.error;
+    const errText = [
+        `✗ ${envelope.meta.toolName} failed · ${err.code}`,
+        `  ${err.message}`,
+        err.hint ? `  hint: ${err.hint}` : '',
+        err.retriable ? '  retriable: yes' : '',
+        `  duration: ${envelope.meta.durationMs}ms · attempts: ${envelope.meta.attempts}`,
+        `  dashboard: http://localhost:${DASH_PORT}/#runtime`,
+    ].filter(Boolean).join('\n');
+    return { content: [{ type: 'text', text: errText }] };
 }

package/dist/cli/install-wizard.d.ts

@@ -40,5 +40,15 @@ export declare function configureIDE(ide: IDEId, opts?: WizardOptions): Promise<
 export declare function runInstallWizard(opts?: WizardOptions): Promise<WizardResult>;
 /** Print how to add nexus-prime manually to an MCP client. */
 export declare function printManualMcpInstructions(): void;
-/** Entry point for CLI: nexus-prime install */
-export declare function cliSetup(args: string[]): Promise<void>;
+export interface CliSetupOptions {
+    dryRun?: boolean;
+    verbose?: boolean;
+    /** Pre-validated license key to activate before starting daemon. */
+    licenseKey?: string;
+    /** Open browser to dashboard after daemon starts (default: true for new users). */
+    openDashboard?: boolean;
+    /** Whether this is a first-time install — affects banner and browser target. */
+    isNewUser?: boolean;
+}
+/** Entry point for CLI: nexus-prime install / setup auto */
+export declare function cliSetup(opts?: CliSetupOptions | string[]): Promise<void>;

package/dist/cli/install-wizard.js

@@ -14,7 +14,7 @@ import { getSetupDefinition, installSetup } from '../engines/client-bootstrap.js
 import { resolveNexusStateDir } from '../engines/runtime-registry.js';
 import { resolveWorkspaceContext } from '../engines/workspace-resolver.js';
 import { runPostinstallCleanup } from '../postinstall/cleanup.js';
-import { drawCard } from '../utils/ascii-card.js';
+import { openBrowser, printHandoffBanner, withSpinner } from './interactive-setup.js';
 /** Compute sha256 of a file's content. Returns null if the file cannot be read. */
 export function computeFileHash(filePath) {
     try {
@@ -340,101 +340,155 @@ export function printManualMcpInstructions() {
     process.stdout.write(snippet.split('\n').map(l => `    ${l}`).join('\n') + '\n\n');
     process.stdout.write('  Or run:  npx nexus-prime@latest setup\n\n');
 }
-/** Entry point for CLI: nexus-prime install */
-export async function cliSetup(args) {
-    const dryRun = args.includes('--dry-run');
-    const verbose = !args.includes('--silent');
+/** Entry point for CLI: nexus-prime install / setup auto */
+export async function cliSetup(opts = []) {
+    // Backwards-compat: accept string[] args as before
+    const args = Array.isArray(opts) ? opts : [];
+    const options = Array.isArray(opts)
+        ? { dryRun: args.includes('--dry-run'), verbose: !args.includes('--silent') }
+        : opts;
+    const dryRun = options.dryRun ?? false;
+    const verbose = options.verbose ?? true;
     const port = process.env.NEXUS_DASHBOARD_PORT ?? '3377';
     const dashUrl = `http://localhost:${port}`;
+    const isNew = options.isNewUser ?? false;
+    const ANSI = { cyan: '\x1b[36m', green: '\x1b[32m', yellow: '\x1b[33m', dim: '\x1b[2m', reset: '\x1b[0m' };
+    const isTTY = process.stdout.isTTY === true && !process.env.NO_COLOR;
+    const c = (s, k) => isTTY ? `${ANSI[k]}${s}${ANSI.reset}` : s;
     const log = (msg) => { if (verbose)
         process.stdout.write(msg + '\n'); };
-    // Step 1 — detect IDEs
-    log('\n◆ Nexus Prime Setup');
+    const step = (n, t, label) => log(`${c(`◇ Step ${n}/${t}`, 'yellow')} · ${label}`);
+    log('');
+    log(c('◆ Nexus Prime Setup', 'cyan'));
     const cleanup = await runPostinstallCleanup({ dryRun, silent: true });
-    log(`${dryRun ? '  Would clean up' : '  Cleaned up'} ${cleanup.staleLockfilesRemoved} stale lockfiles, killed ${cleanup.staleDaemonsKilled} stale daemons`);
-    log('◇ Step 1/4 · Detecting IDEs…');
-    const result = await runInstallWizard({ dryRun, verbose: false });
-    if (result.configured.length > 0) {
-        log(`  ✓ Configured: ${result.configured.join(', ')}`);
+    if (cleanup.staleLockfilesRemoved + cleanup.staleDaemonsKilled > 0) {
+        log(`  ${c('↺', 'dim')} Cleaned ${cleanup.staleLockfilesRemoved} lockfiles, stopped ${cleanup.staleDaemonsKilled} stale daemons`);
     }
-    if (result.skipped.length > 0) {
-        log(`  ✓ Already configured: ${result.skipped.join(', ')}`);
+    // Step 1 — detect + configure IDEs (per-IDE animated checklist)
+    const totalSteps = options.licenseKey ? 5 : 4;
+    step(1, totalSteps, 'Detecting IDEs…');
+    // Emit install.step event helper (best-effort; daemon may not be running yet)
+    const emitInstallStep = (stepN, total, label, status, detail) => {
+        try {
+            import('../engines/event-bus.js').then(({ nexusEventBus }) => {
+                nexusEventBus.emit('install.step', { step: stepN, total, label, status, detail });
+            }).catch(() => { });
+        }
+        catch { /* non-fatal */ }
+    };
+    const result = await runInstallWizard({ dryRun, verbose: false });
+    const allIDEs = [...result.configured, ...result.skipped, ...result.errors.map(e => e.ide)];
+    if (allIDEs.length > 0) {
+        for (const ide of allIDEs) {
+            const isConfigured = result.configured.includes(ide);
+            const isSkipped = result.skipped.includes(ide);
+            const errEntry = result.errors.find(e => e.ide === ide);
+            if (isConfigured) {
+                await withSpinner(`${ide} · configuring`, Promise.resolve());
+                emitInstallStep(1, totalSteps, ide, 'ok', 'MCP config written');
+            }
+            else if (isSkipped) {
+                log(`  ${c('─', 'dim')} ${c(ide, 'dim')} already set up`);
+                emitInstallStep(1, totalSteps, ide, 'skip', 'already configured');
+            }
+            else if (errEntry) {
+                log(`  ${c('✗', 'yellow')} ${c(ide, 'yellow')} · ${errEntry.reason}`);
+                emitInstallStep(1, totalSteps, ide, 'fail', errEntry.reason);
+            }
+        }
     }
-    if (result.errors.length > 0) {
-        log(`  ✗ ${result.errors.length} error(s). Check output above.`);
+    else {
+        log(`  ${c('—', 'dim')} No IDEs auto-detected. Run: nexus-prime setup <ide>`);
     }
-    else if (result.configured.length === 0 && result.skipped.length === 0) {
-        log('  — No IDEs auto-detected. Run: nexus-prime setup <ide>');
+    // Step 2 — MCP configs confirmed
+    step(2, totalSteps, 'MCP configs written.');
+    // Optional license activation step
+    let licStepBase = 2;
+    if (options.licenseKey) {
+        licStepBase = 3;
+        step(3, totalSteps, 'Activating license…');
+        if (!dryRun) {
+            try {
+                const licRes = await fetch(`${dashUrl}/api/license/activate`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ key: options.licenseKey }),
+                    signal: AbortSignal.timeout(8_000),
+                });
+                if (licRes.ok) {
+                    const data = await licRes.json();
+                    log(`  ${c('✓', 'green')} License activated · ${c(data?.tier?.toUpperCase() ?? 'PRO', 'yellow')} plan`);
+                }
+                else {
+                    log(`  ${c('⚠', 'yellow')} License activation returned ${licRes.status} — check key and retry: nexus-prime license activate <key>`);
+                }
+            }
+            catch {
+                log(`  ${c('—', 'dim')} License activation skipped (daemon not ready yet) — retry: nexus-prime license activate <key>`);
+            }
+        }
+        else {
+            log(`  ${c('[dry-run]', 'dim')} Would activate license key`);
+        }
     }
-    // Step 2 — write configs (done by runInstallWizard above, just report)
-    log('◇ Step 2/4 · MCP configs written.');
-    // Step 3 — start daemon
-    log('◇ Step 3/4 · Starting daemon…');
+    // Step daemon
+    const daemonStep = licStepBase + 1;
+    step(daemonStep, totalSteps, 'Starting daemon…');
+    let daemonReady = false;
     if (!dryRun) {
         try {
             const workspace = resolveWorkspaceContext({ workspaceRoot: process.cwd() });
-            await ensureDaemonReady(workspace, { timeoutMs: 10_000, entrypoint: process.argv[1] });
-            log(`  ✓ Dashboard: ${dashUrl}`);
+            await withSpinner('Connecting to daemon', ensureDaemonReady(workspace, { timeoutMs: 15_000, entrypoint: process.argv[1] }));
+            daemonReady = true;
+            log(`  ${c('✓', 'green')} Dashboard: ${c(dashUrl, 'cyan')}`);
         }
         catch (err) {
-            log(`  ✗ Daemon start failed: ${err instanceof Error ? err.message : String(err)}`);
-            log(`    Start manually: nexus-prime daemon`);
+            log(`  ${c('✗', 'yellow')} Daemon start failed: ${err instanceof Error ? err.message : String(err)}`);
+            log(`    Start manually: ${c('nexus-prime daemon', 'dim')}`);
         }
     }
     else {
-        log(`  [dry-run] Would start daemon → ${dashUrl}`);
+        log(`  ${c('[dry-run]', 'dim')} Would start daemon → ${dashUrl}`);
     }
-    // Step 4 — auto-hire starter operative (opt-out via NEXUS_AUTO_HIRE_STARTER=0)
-    log('◇ Step 4/4 · Hiring your first specialist…');
-    if (!dryRun && process.env.NEXUS_AUTO_HIRE_STARTER !== '0') {
+    // Step hire
+    const hireStep = daemonStep + 1;
+    step(hireStep, totalSteps, 'Hiring your first specialist…');
+    if (!dryRun && daemonReady && process.env.NEXUS_AUTO_HIRE_STARTER !== '0') {
         try {
             const hireRes = await fetch(`${dashUrl}/api/synapse/hire`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    specialistId: 'engineering.rapid-prototyper',
-                    budgetCapUsd: 1,
-                    name: 'Rapid Prototyper',
-                }),
+                body: JSON.stringify({ specialistId: 'engineering.rapid-prototyper', budgetCapUsd: 1, name: 'Rapid Prototyper' }),
                 signal: AbortSignal.timeout(5_000),
             });
             if (hireRes.ok) {
                 const op = await hireRes.json();
                 const opId = op?.operative?.id ?? op?.id ?? 'op_???';
-                log(`  ✓ Operative ${opId} · rapid-prototyper · hired`);
-                // Enqueue welcome mission — fire-and-forget (daemon may still be warming up).
-                try {
-                    await fetch(`${dashUrl}/api/orchestrate`, {
-                        method: 'POST',
-                        headers: { 'Content-Type': 'application/json' },
-                        body: JSON.stringify({
-                            goal: 'Introduce yourself to this codebase — read the README and top 3 source files, then store what you learn as memories.',
-                        }),
-                        signal: AbortSignal.timeout(3_000),
-                    });
-                }
-                catch { /* best-effort — not fatal */ }
+                log(`  ${c('✓', 'green')} Operative ${c(String(opId), 'cyan')} · rapid-prototyper · hired`);
+                // Fire-and-forget welcome mission
+                fetch(`${dashUrl}/api/orchestrate`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ goal: 'Introduce yourself to this codebase — read the README and top 3 source files, then store what you learn as memories.' }),
+                    signal: AbortSignal.timeout(3_000),
+                }).catch(() => { });
             }
             else {
-                log(`  — Hire skipped (daemon not ready yet — open dashboard to hire)`);
+                log(`  ${c('—', 'dim')} Hire skipped (daemon warming up) — open dashboard to hire`);
             }
         }
         catch {
-            log(`  — Hire skipped (open ${dashUrl}/#workforce to hire manually)`);
+            log(`  ${c('—', 'dim')} Hire skipped — open ${c(`${dashUrl}/#workforce`, 'dim')} to hire manually`);
         }
     }
     else if (dryRun) {
-        log(`  [dry-run] Would hire engineering.rapid-prototyper with $1 budget`);
+        log(`  ${c('[dry-run]', 'dim')} Would hire engineering.rapid-prototyper`);
+    }
+    // Handoff: open browser + print banner
+    if (!dryRun && daemonReady && (options.openDashboard ?? isNew)) {
+        const target = isNew ? `${dashUrl}/welcome` : dashUrl;
+        openBrowser(target);
+        log(`  ${c('↗', 'cyan')} Opening ${c(target, 'cyan')} in browser…`);
     }
-    // Print next-actions card
-    drawCard({
-        title: 'NEXUS PRIME · READY',
-        lines: [
-            `Dashboard  ${dashUrl}`,
-            `Welcome    ${dashUrl}/welcome`,
-            '',
-            `  [o] open dashboard   [h] hire another   [q] quit`,
-        ],
-        color: '36',
-    });
+    printHandoffBanner(dashUrl, { isNew });
 }

package/dist/cli/interactive-setup.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Interactive setup utilities — new-user detection, prompts, browser open, handoff.
+ * Uses only Node.js built-ins; no new runtime dependencies.
+ */
+/** Single-line readline prompt. Returns empty string in non-TTY environments. */
+export declare function promptLine(question: string): Promise<string>;
+/**
+ * Keystroke-level prompt — shows question and waits for one of `validKeys`.
+ * Falls back to validKeys[0] in non-TTY or CI environments.
+ */
+export declare function promptKey(question: string, validKeys: string[]): Promise<string>;
+/** Open browser cross-platform. Non-fatal on error. */
+export declare function openBrowser(url: string): void;
+/** True when no setup marker exists → first install. */
+export declare function isNewUser(): boolean;
+/**
+ * Interactive license key prompt shown to new users on the free tier.
+ * Returns the entered key or null if user chose to skip.
+ */
+export declare function promptLicenseKey(currentTier?: string): Promise<string | null>;
+/** Print post-install handoff banner with dashboard URL and quick-start commands. */
+export declare function printHandoffBanner(dashUrl: string, opts?: {
+    isNew?: boolean;
+}): void;
+/** Print a compact banner for returning users showing last-setup info. */
+export declare function printReturningUserBanner(marker: {
+    configuredIDEs: string[];
+    setupCompletedAt: number;
+}): void;
+/**
+ * Animated "syncing" spinner that resolves when the provided promise resolves.
+ * Falls back to simple await in non-TTY environments.
+ */
+export declare function withSpinner<T>(label: string, work: Promise<T>): Promise<T>;

package/dist/cli/interactive-setup.js

@@ -0,0 +1,163 @@
+/**
+ * Interactive setup utilities — new-user detection, prompts, browser open, handoff.
+ * Uses only Node.js built-ins; no new runtime dependencies.
+ */
+import readline from 'readline';
+import { execSync } from 'child_process';
+import { readSetupMarker } from './install-wizard.js';
+const ANSI = {
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    magenta: '\x1b[35m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    reset: '\x1b[0m',
+};
+const tty = () => process.stdout.isTTY === true && !process.env.NO_COLOR;
+const c = (s, k) => tty() ? `${ANSI[k]}${s}${ANSI.reset}` : s;
+const log = (s) => process.stdout.write(s + '\n');
+/** Single-line readline prompt. Returns empty string in non-TTY environments. */
+export async function promptLine(question) {
+    if (!tty())
+        return '';
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: true,
+    });
+    return new Promise(resolve => {
+        rl.question(question, ans => {
+            rl.close();
+            resolve(ans.trim());
+        });
+    });
+}
+/**
+ * Keystroke-level prompt — shows question and waits for one of `validKeys`.
+ * Falls back to validKeys[0] in non-TTY or CI environments.
+ */
+export async function promptKey(question, validKeys) {
+    if (!tty() || process.env.CI)
+        return validKeys[0];
+    process.stdout.write(question);
+    return new Promise(resolve => {
+        const stdin = process.stdin;
+        const wasRaw = stdin.isRaw;
+        if (stdin.setRawMode)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        const handler = (key) => {
+            const k = key.toLowerCase();
+            const normalized = (k === '\r' || k === '\n') ? '\r' : k;
+            if (validKeys.includes(normalized) || validKeys.includes(k)) {
+                if (stdin.setRawMode)
+                    stdin.setRawMode(wasRaw ?? false);
+                stdin.pause();
+                stdin.removeListener('data', handler);
+                process.stdout.write('\n');
+                resolve(validKeys.includes(k) ? k : validKeys[0]);
+            }
+            else if (key === '\u0003') {
+                process.stdout.write('\n');
+                process.exit(0);
+            }
+        };
+        stdin.on('data', handler);
+    });
+}
+/** Open browser cross-platform. Non-fatal on error. */
+export function openBrowser(url) {
+    try {
+        const cmd = process.platform === 'darwin' ? `open "${url}"`
+            : process.platform === 'win32' ? `start "" "${url}"`
+                : `xdg-open "${url}"`;
+        execSync(cmd, { stdio: 'ignore', timeout: 3000 });
+    }
+    catch { /* non-fatal */ }
+}
+/** True when no setup marker exists → first install. */
+export function isNewUser() {
+    return readSetupMarker() === null;
+}
+/**
+ * Interactive license key prompt shown to new users on the free tier.
+ * Returns the entered key or null if user chose to skip.
+ */
+export async function promptLicenseKey(currentTier = 'free') {
+    if (!tty() || currentTier !== 'free')
+        return null;
+    log('');
+    log(c('  ┌─ LICENSE ──────────────────────────────────────────────────┐', 'magenta'));
+    log(c('  │', 'magenta') + '  You\'re on the ' + c('Free', 'yellow') + ' plan.                                    ' + c('│', 'magenta'));
+    log(c('  │', 'magenta') + '  Get a license at ' + c('nexus-prime.cfd/license', 'cyan') + '              ' + c('│', 'magenta'));
+    log(c('  └────────────────────────────────────────────────────────────┘', 'magenta'));
+    log('');
+    const choice = await promptKey(`  ${c('[L]', 'yellow')} Enter license key   ${c('[S]', 'dim')} Skip for now   › `, ['l', 's']);
+    if (choice === 'l') {
+        const key = await promptLine(`\n  ${c('License key', 'cyan')}: `);
+        if (key.length > 4)
+            return key;
+        log(`  ${c('(skipped — key too short)', 'dim')}`);
+    }
+    return null;
+}
+/** Print post-install handoff banner with dashboard URL and quick-start commands. */
+export function printHandoffBanner(dashUrl, opts = {}) {
+    const bdr = '═'.repeat(62);
+    const row = (label, val) => {
+        const content = `  ${label.padEnd(12)} → ${val}`;
+        return c('║', 'cyan') + content.padEnd(64) + c('║', 'cyan');
+    };
+    const div = c('╠' + '─'.repeat(62) + '╣', 'dim');
+    log('');
+    log(c(`╔${bdr}╗`, 'cyan'));
+    log(c('║', 'cyan') + c('  ⚡ NEXUS PRIME · CONTROL PLANE ONLINE', 'bold').padEnd(75) + c('║', 'cyan'));
+    log(div);
+    log(row(c('Dashboard', 'yellow'), c(dashUrl, 'cyan')));
+    if (opts.isNew) {
+        log(row(c('Onboarding', 'yellow'), c(dashUrl + '/welcome', 'cyan')));
+    }
+    log(div);
+    log(row(c('Orchestrate', 'dim'), 'nexus-prime orchestrate "<goal>"'));
+    log(row(c('Status', 'dim'), 'nexus-prime status'));
+    log(row(c('Hire', 'dim'), 'nexus-prime setup auto (re-run anytime)'));
+    log(c(`╚${bdr}╝`, 'cyan'));
+    log('');
+}
+/** Print a compact banner for returning users showing last-setup info. */
+export function printReturningUserBanner(marker) {
+    const ago = Math.round((Date.now() - marker.setupCompletedAt) / 86_400_000);
+    const agoStr = ago < 1 ? 'today' : ago === 1 ? 'yesterday' : `${ago}d ago`;
+    log('');
+    log(c('  ┌─ EXISTING INSTALLATION ─────────────────────────────────────┐', 'dim'));
+    log(c('  │', 'dim') + `  Last setup : ${c(agoStr.padEnd(48, ' '), 'cyan')}` + c('│', 'dim'));
+    log(c('  │', 'dim') + `  IDEs       : ${c(marker.configuredIDEs.join(', ').substring(0, 48).padEnd(48, ' '), 'cyan')}` + c('│', 'dim'));
+    log(c('  └─────────────────────────────────────────────────────────────┘', 'dim'));
+    log('');
+}
+/**
+ * Animated "syncing" spinner that resolves when the provided promise resolves.
+ * Falls back to simple await in non-TTY environments.
+ */
+export async function withSpinner(label, work) {
+    if (!tty())
+        return work;
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    let i = 0;
+    const interval = setInterval(() => {
+        process.stdout.write(`\r  ${c(frames[i++ % frames.length], 'cyan')} ${label}  `);
+    }, 80);
+    try {
+        const result = await work;
+        clearInterval(interval);
+        process.stdout.write(`\r  ${c('✓', 'green')} ${label}          \n`);
+        return result;
+    }
+    catch (err) {
+        clearInterval(interval);
+        process.stdout.write(`\r  ${c('✗', 'yellow')} ${label}          \n`);
+        throw err;
+    }
+}

package/dist/cli/orchestrate-stream.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI orchestrate command — streams live SSE events as phase spinners.
+ * Usage: nexus-prime orchestrate "<goal>"
+ */
+export declare function runOrchestrateStream(goal: string, opts?: {
+    port?: number;
+    timeoutMs?: number;
+}): Promise<void>;