@nusoft/nuos-build-catalogue 0.17.0 → 0.19.0

package/dist/cli.js

@@ -362,8 +362,10 @@ function cmdHelp() {
     console.log(`nuos-catalogue — NuOS build-catalogue tooling (WU 110, WU 111)
 
 Usage:
-  nuos-catalogue init     [--name=X --tagline="Y" --role=consumer --interactive]
-                          (interactive bootstrap of docs/build/, methodfile.json, .claude/commands/<protocols>, CLAUDE.md, .gitignore overrides; refuses if docs/build/ already exists)
+  nuos-catalogue init     [--name=X --tagline="Y" --role=consumer --interactive] [--no-llm]
+                          (bootstrap docs/build/, methodfile.json, .claude/commands/<protocols>, CLAUDE.md, .gitignore overrides; then probe Ollama and pull qwen3-embedding:0.6b for semantic search. --no-llm skips the LLM step. Refuses if docs/build/ already exists)
+  nuos-catalogue setup-llm
+                          (run the LLM-setup phase outside 'init': detect Ollama, offer to install where reliable, pull qwen3-embedding:0.6b with a progress bar. Idempotent — safe to re-run)
   nuos-catalogue install-protocols
                           (refresh .claude/commands/<protocols> from this CLI's bundled canonical bodies)
 
@@ -396,6 +398,9 @@ Usage:
   nuos-catalogue swarm     status    [--limit=N]  list recent /build-wu runs
   nuos-catalogue swarm     cost      aggregate cost across swarm runs
 
+  nuos-catalogue memory    store     --value="..." [--wu=wu-007] [--agent=architect] [--key="label"]
+  nuos-catalogue memory    search    --query="..." [--limit=N]   [--wu=wu-007]       [--agent=architect]
+
   nuos-catalogue help
 
 Handles accepted: canonical (wu-111, D046, Q009, P001) or friendly
@@ -438,6 +443,7 @@ async function main() {
                     domain: args.flags['domain'] ? String(args.flags['domain']) : undefined,
                     role: args.flags['role'] ? String(args.flags['role']) : undefined,
                     interactive: Boolean(args.flags['interactive']),
+                    noLlm: Boolean(args.flags['no-llm']),
                 });
                 if (result.output)
                     console.log(result.output);
@@ -448,6 +454,19 @@ async function main() {
             }
             break;
         }
+        case 'setup-llm': {
+            // WU 135 — standalone re-entry into the LLM-setup phase. Useful
+            // when `init` was run with --no-llm, when an install failed, or
+            // when the user switched machines and needs to pull the model
+            // freshly. Same orchestrator that `init` calls internally.
+            const { runLlmSetup } = await import('./setup/run-llm-setup.js');
+            const result = await runLlmSetup({ nonInteractive: false });
+            // Most failure paths emit guidance in-band; we exit non-zero only
+            // when a pull actually failed (so CI scripting can branch on it).
+            const exitCode = result.kind === 'pull_failed' || result.kind === 'install_failed' ? 1 : 0;
+            process.exit(exitCode);
+            break;
+        }
         case 'install-protocols': {
             const prompt = openPrompt();
             try {
@@ -509,6 +528,34 @@ async function main() {
             console.error('available: swarm status [--limit=N], swarm cost');
             process.exit(1);
         }
+        case 'memory': {
+            const sub = args.positional[0];
+            const { cmdMemoryStore, cmdMemorySearch } = await import('./commands/memory.js');
+            if (sub === 'store') {
+                const value = args.flags['value'] ? String(args.flags['value']) : '';
+                const wu = args.flags['wu'] ? String(args.flags['wu']) : undefined;
+                const agent = args.flags['agent'] ? String(args.flags['agent']) : undefined;
+                const key = args.flags['key'] ? String(args.flags['key']) : undefined;
+                const code = await cmdMemoryStore({ value, wu, agent, key, cwd: process.cwd() });
+                if (code !== 0)
+                    process.exit(code);
+                break;
+            }
+            if (sub === 'search') {
+                const query = args.flags['query'] ? String(args.flags['query']) : '';
+                const limit = args.flags['limit'] ? Number(args.flags['limit']) : undefined;
+                const wu = args.flags['wu'] ? String(args.flags['wu']) : undefined;
+                const agent = args.flags['agent'] ? String(args.flags['agent']) : undefined;
+                const code = await cmdMemorySearch({ query, limit, wu, agent, cwd: process.cwd() });
+                if (code !== 0)
+                    process.exit(code);
+                break;
+            }
+            console.error(`unknown memory subcommand: ${sub ?? '(none)'}`);
+            console.error('available: memory store --value="..." [--wu=...] [--agent=...] [--key=...]');
+            console.error('           memory search --query="..." [--limit=N] [--wu=...] [--agent=...]');
+            process.exit(1);
+        }
         case 'help':
         case '--help':
         case '-h':

package/dist/commands/init.d.ts

@@ -47,6 +47,13 @@ export interface InitOptions {
      * has no effect — init is always non-interactive unless `interactive` is set.
      */
     nonInteractive?: boolean;
+    /**
+     * Skip the post-scaffold LLM-setup phase (WU 135). When true, `init`
+     * scaffolds the catalogue and exits without probing for Ollama or
+     * offering to pull the embedding model. Users who skip can run
+     * `nuos-catalogue setup-llm` later. Default: false.
+     */
+    noLlm?: boolean;
 }
 export interface InitResult {
     output: string;

package/dist/commands/init.js

@@ -204,6 +204,31 @@ export async function cmdInit(prompt, options = {}) {
     // Step 5: .gitignore
     const gitignorePath = path.join(cwd, '.gitignore');
     await ensureGitignoreEntries(gitignorePath, log_line);
+    // Step 6: LLM setup (WU 135). Probes Ollama, offers to install where
+    // reliable, pulls the default embedding model with a live progress bar.
+    // Skipped when `noLlm` is set, leaving the catalogue scaffolded and
+    // usable for markdown-only workflows — the user can run
+    // `nuos-catalogue setup-llm` later.
+    if (!options.noLlm) {
+        const { runLlmSetup } = await import('../setup/run-llm-setup.js');
+        await runLlmSetup({
+            // The setup module writes its own progress directly to stderr; we
+            // don't route through `prompt.print` because the in-place progress
+            // bar needs unbuffered control of the line.
+            //
+            // We always allow prompts here, even though `init` overall is
+            // zero-prompt by default. The LLM setup's only prompts are
+            // single-key consent gates ("install Ollama?", "open download
+            // page?") and they need the user's input on a fresh machine.
+            // `runLlmSetup` falls back to no-on-EOF when stdin isn't a TTY,
+            // so this is safe in unattended runs too.
+            nonInteractive: false,
+        });
+    }
+    else {
+        prompt.print('');
+        prompt.print('  · LLM setup skipped (--no-llm). Run `nuos-catalogue setup-llm` later to enable semantic search.');
+    }
     prompt.print('');
     prompt.print('✅ Done.');
     prompt.print('');

package/dist/commands/memory.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `nuos-catalogue memory store` — embed a finding and persist it to NuVector.
+ * `nuos-catalogue memory search` — retrieve relevant past findings by query.
+ *
+ * Cross-agent memory: every agent in a swarm can write findings here and
+ * any future agent (in this run or a later one) can retrieve them by
+ * semantic query. Uses the same NuVector store as the catalogue index,
+ * distinguished by kind: 'agent_memory'.
+ *
+ * CLI:
+ *   memory store  --value="..."  [--wu=wu-007] [--agent=architect] [--key="label"]
+ *   memory search --query="..."  [--limit=N]   [--wu=wu-007]       [--agent=architect]
+ */
+export interface MemoryStoreOptions {
+    value: string;
+    wu?: string;
+    agent?: string;
+    key?: string;
+    cwd?: string;
+    buildRoot?: string | boolean;
+    index?: string | boolean;
+}
+export interface MemorySearchOptions {
+    query: string;
+    limit?: number;
+    wu?: string;
+    agent?: string;
+    cwd?: string;
+    buildRoot?: string | boolean;
+    index?: string | boolean;
+}
+export interface MemoryHit {
+    id: string;
+    score: number;
+    text: string;
+    agentRole: string;
+    workUnit: string;
+    key: string;
+    timestamp: string;
+}
+export declare function cmdMemoryStore(opts: MemoryStoreOptions): Promise<number>;
+export declare function cmdMemorySearch(opts: MemorySearchOptions): Promise<number>;

package/dist/commands/memory.js

@@ -0,0 +1,116 @@
+/**
+ * `nuos-catalogue memory store` — embed a finding and persist it to NuVector.
+ * `nuos-catalogue memory search` — retrieve relevant past findings by query.
+ *
+ * Cross-agent memory: every agent in a swarm can write findings here and
+ * any future agent (in this run or a later one) can retrieve them by
+ * semantic query. Uses the same NuVector store as the catalogue index,
+ * distinguished by kind: 'agent_memory'.
+ *
+ * CLI:
+ *   memory store  --value="..."  [--wu=wu-007] [--agent=architect] [--key="label"]
+ *   memory search --query="..."  [--limit=N]   [--wu=wu-007]       [--agent=architect]
+ */
+import { randomUUID } from 'node:crypto';
+import { resolveBuildRoot, resolveIndexPath } from '../path-resolution.js';
+// NuVector's MemoryRecordKind union doesn't include a swarm-specific kind yet.
+// 'workflow_provenance' is the closest semantic match — agent memories are
+// provenance of the swarm workflow. NuFlow isn't wired (harness.runtime.nuflow
+// is null) so there's no collision today; records are further distinguished by
+// the presence of an `agent_role` metadata field (absent on NuFlow provenance).
+const MEMORY_KIND = 'workflow_provenance';
+export async function cmdMemoryStore(opts) {
+    const { value, wu, agent, key } = opts;
+    if (!value || value.trim().length === 0) {
+        console.error('memory store: --value is required and must be non-empty');
+        return 1;
+    }
+    const { selectEmbedderFromEnv } = await import('../embedder/select.js');
+    const { openStore, TENANT } = await import('../store/open.js');
+    const buildRoot = resolveBuildRoot(opts.buildRoot, { cwd: opts.cwd ?? process.cwd() });
+    const indexPath = resolveIndexPath(buildRoot, opts.index);
+    const embedder = await selectEmbedderFromEnv();
+    const store = await openStore({ storagePath: indexPath, dimensions: embedder.dimensions });
+    const [embedding] = await embedder.embed([value]);
+    await store.upsert({
+        id: randomUUID(),
+        kind: MEMORY_KIND,
+        embedding,
+        text: value,
+        tenant: TENANT,
+        metadata: {
+            agent_role: agent ?? '',
+            work_unit: wu ?? '',
+            key: key ?? '',
+            timestamp: new Date().toISOString(),
+        },
+    });
+    const label = key ? ` [${key}]` : '';
+    const context = [agent, wu].filter(Boolean).join(' / ');
+    console.log(`memory stored${label}${context ? ` (${context})` : ''}`);
+    return 0;
+}
+export async function cmdMemorySearch(opts) {
+    const { query, limit = 5, wu, agent } = opts;
+    if (!query || query.trim().length === 0) {
+        console.error('memory search: --query is required and must be non-empty');
+        return 1;
+    }
+    const { selectEmbedderFromEnv } = await import('../embedder/select.js');
+    const { openStore, TENANT } = await import('../store/open.js');
+    const buildRoot = resolveBuildRoot(opts.buildRoot, { cwd: opts.cwd ?? process.cwd() });
+    const indexPath = resolveIndexPath(buildRoot, opts.index);
+    const embedder = await selectEmbedderFromEnv();
+    const store = await openStore({ storagePath: indexPath, dimensions: embedder.dimensions });
+    const [queryEmbedding] = await embedder.embed([query]);
+    const result = await store.retrieveContext({
+        embedding: queryEmbedding,
+        tenant: TENANT,
+        topK: Math.max(limit * 4, 20),
+        filters: { kind: MEMORY_KIND },
+    });
+    const raw = (result?.items ?? []);
+    let hits = raw
+        .filter((r) => typeof r.score === 'number' && r.score > 0.3)
+        .map((r) => ({
+        id: r.ref ?? '',
+        score: r.score ?? 0,
+        text: r.text ?? '',
+        agentRole: String(r.metadata?.agent_role ?? ''),
+        workUnit: String(r.metadata?.work_unit ?? ''),
+        key: String(r.metadata?.key ?? ''),
+        timestamp: String(r.metadata?.timestamp ?? ''),
+    }));
+    // Post-filter by wu / agent when requested
+    if (wu) {
+        hits = hits.filter((h) => h.workUnit === wu || h.workUnit === normaliseWu(wu));
+    }
+    if (agent) {
+        hits = hits.filter((h) => h.agentRole === agent);
+    }
+    hits = hits.slice(0, limit);
+    if (hits.length === 0) {
+        console.log(`no memories found (query: "${query}")`);
+        return 0;
+    }
+    console.log(`${hits.length} memor${hits.length === 1 ? 'y' : 'ies'} found (query: "${query}")\n`);
+    for (let i = 0; i < hits.length; i++) {
+        const h = hits[i];
+        const score = h.score.toFixed(2);
+        const ctx = [h.workUnit, h.agentRole].filter(Boolean).join(' | ');
+        const date = h.timestamp ? h.timestamp.slice(0, 10) : '';
+        const header = [ctx, date].filter(Boolean).join(' | ');
+        const keyLabel = h.key ? ` [${h.key}]` : '';
+        console.log(`[${i + 1}] (score: ${score})${keyLabel}${header ? ` — ${header}` : ''}`);
+        console.log(`    ${h.text.replace(/\n/g, '\n    ')}`);
+        if (i < hits.length - 1)
+            console.log('');
+    }
+    return 0;
+}
+function normaliseWu(handle) {
+    const m = handle.match(/(\d+)/);
+    if (!m)
+        return handle;
+    return `wu-${m[1].padStart(3, '0')}`;
+}

package/dist/setup/ollama-detect.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Probes for the Ollama CLI binary, the HTTP API, and a specific model.
+ *
+ * All three probes are non-throwing — they return result objects with a
+ * `found` / `reachable` / `present` boolean so the caller can compose a
+ * branching setup flow without try/catch noise.
+ *
+ * @module setup/ollama-detect
+ */
+import type { OllamaApiProbe, OllamaCliProbe, ModelProbe, Platform } from './types.js';
+/** Default API host used by the existing Ollama embedder. */
+export declare const DEFAULT_OLLAMA_HOST = "http://localhost:11434";
+/**
+ * Resolve `ollama` on PATH and capture its absolute path if present.
+ *
+ * Uses `which` on Unix-likes and `where` on Windows. We do not parse
+ * version output here — the caller only needs the boolean and the path.
+ */
+export declare function detectOllamaCli(platform: Platform): Promise<OllamaCliProbe>;
+/**
+ * Probe the Ollama HTTP API at the given host. Uses `/api/tags` which
+ * is cheap and returns a 200 even on an empty model list.
+ *
+ * Returns `reachable: false` plus an error string for any non-200 or
+ * network failure. Times out after 1500ms so a hung daemon doesn't
+ * stall the setup flow.
+ */
+export declare function detectOllamaApi(host?: string): Promise<OllamaApiProbe>;
+/**
+ * Check whether a specific model has been pulled into the local Ollama
+ * instance. Calls `/api/tags` and matches by exact name. Returns
+ * `present: false` on any failure — the caller's next step (pull) will
+ * surface the underlying error.
+ */
+export declare function detectModelPresent(host: string, model: string): Promise<ModelProbe>;

package/dist/setup/ollama-detect.js

@@ -0,0 +1,83 @@
+/**
+ * Probes for the Ollama CLI binary, the HTTP API, and a specific model.
+ *
+ * All three probes are non-throwing — they return result objects with a
+ * `found` / `reachable` / `present` boolean so the caller can compose a
+ * branching setup flow without try/catch noise.
+ *
+ * @module setup/ollama-detect
+ */
+import { spawn } from 'node:child_process';
+/** Default API host used by the existing Ollama embedder. */
+export const DEFAULT_OLLAMA_HOST = 'http://localhost:11434';
+/**
+ * Resolve `ollama` on PATH and capture its absolute path if present.
+ *
+ * Uses `which` on Unix-likes and `where` on Windows. We do not parse
+ * version output here — the caller only needs the boolean and the path.
+ */
+export async function detectOllamaCli(platform) {
+    const command = platform === 'win32' ? 'where' : 'which';
+    return new Promise((resolve) => {
+        const child = spawn(command, ['ollama'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+        child.on('error', () => resolve({ found: false }));
+        child.on('close', (code) => {
+            if (code === 0 && stdout.trim()) {
+                // `where` on Windows may return multiple lines; take the first.
+                const firstLine = stdout.split(/\r?\n/)[0]?.trim() ?? '';
+                resolve({ found: true, path: firstLine });
+            }
+            else {
+                resolve({ found: false });
+            }
+        });
+    });
+}
+/**
+ * Probe the Ollama HTTP API at the given host. Uses `/api/tags` which
+ * is cheap and returns a 200 even on an empty model list.
+ *
+ * Returns `reachable: false` plus an error string for any non-200 or
+ * network failure. Times out after 1500ms so a hung daemon doesn't
+ * stall the setup flow.
+ */
+export async function detectOllamaApi(host = DEFAULT_OLLAMA_HOST) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1500);
+    try {
+        const response = await fetch(`${host}/api/tags`, { signal: controller.signal });
+        if (!response.ok) {
+            return { reachable: false, host, error: `HTTP ${response.status}` };
+        }
+        return { reachable: true, host };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { reachable: false, host, error: message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Check whether a specific model has been pulled into the local Ollama
+ * instance. Calls `/api/tags` and matches by exact name. Returns
+ * `present: false` on any failure — the caller's next step (pull) will
+ * surface the underlying error.
+ */
+export async function detectModelPresent(host, model) {
+    try {
+        const response = await fetch(`${host}/api/tags`);
+        if (!response.ok)
+            return { present: false, model };
+        const data = (await response.json());
+        const present = Array.isArray(data.models)
+            && data.models.some((m) => m.name === model);
+        return { present, model };
+    }
+    catch {
+        return { present: false, model };
+    }
+}

package/dist/setup/ollama-install.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-platform install offers for Ollama (WU 135).
+ *
+ * Three platforms; three install paths with very different
+ * reliability:
+ *
+ *   - macOS — `brew install --cask ollama` is reliable when Homebrew
+ *     is present. Without Homebrew, the only path is the download
+ *     page.
+ *   - Linux — `curl -fsSL https://ollama.com/install.sh | sh` is the
+ *     official one-liner and works on every Linux distro Ollama
+ *     supports. It writes to /usr/local and asks for sudo.
+ *   - Windows — there is no reliable CLI install path. Open the
+ *     download page.
+ *
+ * The pure offer-builder is split from the spawn-the-installer
+ * function so it's unit-testable.
+ *
+ * @module setup/ollama-install
+ */
+import type { InstallOffer, Platform } from './types.js';
+/** The canonical download page used as the safe fallback on every platform. */
+export declare const OLLAMA_DOWNLOAD_URL = "https://ollama.com/download";
+/**
+ * Build the install offer for the current platform. `hasBrew` is
+ * relevant only on macOS — the caller probes for `brew` separately
+ * via the standard CLI detection path and passes the result in.
+ *
+ * Pure — no I/O.
+ */
+export declare function buildInstallOffer(platform: Platform, hasBrew: boolean): InstallOffer;
+/**
+ * Run the offer's primary command, streaming the installer's stdout
+ * and stderr to the caller's handler. Resolves with a result the
+ * caller turns into a `LlmSetupResult`.
+ *
+ * The command is invoked via the user's shell so pipes (`curl | sh`)
+ * work as expected. The user already consented to running it; the
+ * harness does not silently auto-run installers.
+ */
+export declare function runInstaller(offer: InstallOffer, onOutput: (line: string) => void): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;
+/**
+ * Open a URL in the user's default browser. Used as the Windows /
+ * brew-less macOS fallback so the user can grab the installer
+ * manually. Best-effort — never throws.
+ */
+export declare function openInBrowser(url: string, platform: Platform): Promise<void>;

package/dist/setup/ollama-install.js

@@ -0,0 +1,140 @@
+/**
+ * Per-platform install offers for Ollama (WU 135).
+ *
+ * Three platforms; three install paths with very different
+ * reliability:
+ *
+ *   - macOS — `brew install --cask ollama` is reliable when Homebrew
+ *     is present. Without Homebrew, the only path is the download
+ *     page.
+ *   - Linux — `curl -fsSL https://ollama.com/install.sh | sh` is the
+ *     official one-liner and works on every Linux distro Ollama
+ *     supports. It writes to /usr/local and asks for sudo.
+ *   - Windows — there is no reliable CLI install path. Open the
+ *     download page.
+ *
+ * The pure offer-builder is split from the spawn-the-installer
+ * function so it's unit-testable.
+ *
+ * @module setup/ollama-install
+ */
+import { spawn } from 'node:child_process';
+/** The canonical download page used as the safe fallback on every platform. */
+export const OLLAMA_DOWNLOAD_URL = 'https://ollama.com/download';
+/**
+ * Build the install offer for the current platform. `hasBrew` is
+ * relevant only on macOS — the caller probes for `brew` separately
+ * via the standard CLI detection path and passes the result in.
+ *
+ * Pure — no I/O.
+ */
+export function buildInstallOffer(platform, hasBrew) {
+    switch (platform) {
+        case 'darwin':
+            if (hasBrew) {
+                return {
+                    platform,
+                    primaryCommand: 'brew install --cask ollama',
+                    primaryDescription: 'Install Ollama via Homebrew (brew install --cask ollama)',
+                    fallbackUrl: OLLAMA_DOWNLOAD_URL,
+                    canAutoInstall: true,
+                    requiresElevation: false,
+                };
+            }
+            return {
+                platform,
+                primaryCommand: '',
+                primaryDescription: `Download the Ollama app from ${OLLAMA_DOWNLOAD_URL}`,
+                fallbackUrl: OLLAMA_DOWNLOAD_URL,
+                canAutoInstall: false,
+                requiresElevation: false,
+            };
+        case 'linux':
+            return {
+                platform,
+                primaryCommand: 'curl -fsSL https://ollama.com/install.sh | sh',
+                primaryDescription: 'Install Ollama via the official install script (asks for sudo)',
+                fallbackUrl: OLLAMA_DOWNLOAD_URL,
+                canAutoInstall: true,
+                requiresElevation: true,
+            };
+        case 'win32':
+            return {
+                platform,
+                primaryCommand: '',
+                primaryDescription: `Download the Ollama installer from ${OLLAMA_DOWNLOAD_URL}`,
+                fallbackUrl: OLLAMA_DOWNLOAD_URL,
+                canAutoInstall: false,
+                requiresElevation: false,
+            };
+        case 'other':
+        default:
+            return {
+                platform,
+                primaryCommand: '',
+                primaryDescription: `See ${OLLAMA_DOWNLOAD_URL} for install options on your platform`,
+                fallbackUrl: OLLAMA_DOWNLOAD_URL,
+                canAutoInstall: false,
+                requiresElevation: false,
+            };
+    }
+}
+/**
+ * Run the offer's primary command, streaming the installer's stdout
+ * and stderr to the caller's handler. Resolves with a result the
+ * caller turns into a `LlmSetupResult`.
+ *
+ * The command is invoked via the user's shell so pipes (`curl | sh`)
+ * work as expected. The user already consented to running it; the
+ * harness does not silently auto-run installers.
+ */
+export async function runInstaller(offer, onOutput) {
+    if (!offer.canAutoInstall || !offer.primaryCommand) {
+        return { ok: false, error: 'No auto-install path is available for this platform.' };
+    }
+    return new Promise((resolve) => {
+        // Spawn through the user's shell so the Linux curl-pipe-sh form
+        // works. macOS brew is also fine via shell. We never spawn this
+        // without explicit user consent at the prompt layer above.
+        const child = spawn(offer.primaryCommand, {
+            shell: true,
+            stdio: ['inherit', 'pipe', 'pipe'],
+        });
+        child.stdout.on('data', (chunk) => {
+            for (const line of chunk.toString('utf8').split(/\r?\n/)) {
+                if (line)
+                    onOutput(line);
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            for (const line of chunk.toString('utf8').split(/\r?\n/)) {
+                if (line)
+                    onOutput(line);
+            }
+        });
+        child.on('error', (err) => {
+            resolve({ ok: false, error: err.message });
+        });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve({ ok: true });
+            else
+                resolve({ ok: false, error: `Installer exited with code ${code ?? 'null'}.` });
+        });
+    });
+}
+/**
+ * Open a URL in the user's default browser. Used as the Windows /
+ * brew-less macOS fallback so the user can grab the installer
+ * manually. Best-effort — never throws.
+ */
+export async function openInBrowser(url, platform) {
+    const command = platform === 'darwin' ? 'open'
+        : platform === 'win32' ? 'start'
+            : 'xdg-open';
+    return new Promise((resolve) => {
+        const child = spawn(command, [url], { stdio: 'ignore', shell: platform === 'win32' });
+        child.on('error', () => resolve());
+        child.on('close', () => resolve());
+    });
+}

package/dist/setup/ollama-pull.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Streams a model pull from Ollama and emits one `PullEvent` per
+ * NDJSON line.
+ *
+ * The Ollama `/api/pull` endpoint returns a stream of newline-delimited
+ * JSON objects describing the pull's progress — `pulling manifest`
+ * first, then one or more `downloading` events per blob (each with
+ * `digest`, `total`, `completed`), then `verifying`, `writing manifest`,
+ * and finally `success`. On failure an object with `error` is emitted
+ * instead.
+ *
+ * The pure parser is exported separately so it can be unit-tested with
+ * a fixed byte stream.
+ *
+ * @module setup/ollama-pull
+ */
+import type { PullEvent } from './types.js';
+/**
+ * Parse a single byte chunk into zero-or-more complete events, given
+ * the running buffer left over from the previous chunk. Returns the
+ * new buffer (any trailing partial line) alongside the parsed events.
+ *
+ * Pure — exported for testing.
+ */
+export declare function parsePullChunk(buffer: string, chunk: string): {
+    buffer: string;
+    events: PullEvent[];
+};
+/**
+ * Pull the named model from the Ollama registry, invoking `onEvent`
+ * for each event the stream emits. Resolves to a success/failure
+ * result; never throws on protocol-level errors (network failures,
+ * abnormal stream closure surface as `{ ok: false }`).
+ */
+export declare function pullModel(host: string, model: string, onEvent: (event: PullEvent) => void): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;