@nusoft/nuos-build-catalogue 0.17.1 → 0.19.0

package/dist/setup/ollama-pull.js

@@ -0,0 +1,104 @@
+/**
+ * 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
+ */
+/**
+ * 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 function parsePullChunk(buffer, chunk) {
+    const combined = buffer + chunk;
+    const lines = combined.split('\n');
+    const trailing = lines.pop() ?? ''; // partial line carries to the next chunk
+    const events = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            events.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Malformed line — skip. Ollama has never been observed to emit
+            // malformed lines in practice, but we never crash on stream noise.
+        }
+    }
+    return { buffer: trailing, events };
+}
+/**
+ * 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 async function pullModel(host, model, onEvent) {
+    let response;
+    try {
+        response = await fetch(`${host}/api/pull`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name: model, stream: true }),
+        });
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    if (!response.ok || !response.body) {
+        return { ok: false, error: `Pull request failed (HTTP ${response.status}).` };
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder('utf8');
+    let buffer = '';
+    let sawSuccess = false;
+    let lastError = null;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            const chunk = decoder.decode(value, { stream: true });
+            const parsed = parsePullChunk(buffer, chunk);
+            buffer = parsed.buffer;
+            for (const event of parsed.events) {
+                onEvent(event);
+                if (event.error)
+                    lastError = event.error;
+                if (event.status === 'success')
+                    sawSuccess = true;
+            }
+        }
+        // Flush any final partial line that turned out to be complete.
+        const tail = parsePullChunk(buffer, '\n');
+        for (const event of tail.events) {
+            onEvent(event);
+            if (event.error)
+                lastError = event.error;
+            if (event.status === 'success')
+                sawSuccess = true;
+        }
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    if (lastError)
+        return { ok: false, error: lastError };
+    if (!sawSuccess) {
+        return { ok: false, error: 'Pull stream ended without a success event.' };
+    }
+    return { ok: true };
+}

package/dist/setup/progress-bar.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Terminal progress bar rendering for the model pull (WU 135).
+ *
+ * Pure functions — no I/O. The caller writes the returned string to
+ * stderr with a leading `\r` for in-place updates, or to stdout when
+ * not in a TTY. The renderer is split into formatters (`formatBytes`,
+ * `buildBar`) and a composer (`buildProgressLine`) so each piece is
+ * independently testable.
+ *
+ * @module setup/progress-bar
+ */
+/**
+ * Format a byte count as a human-readable string with one decimal place.
+ * Uses 1024-based units (KiB / MiB / GiB) but labels them KB / MB / GB
+ * since that's what most users expect to see from a CLI.
+ */
+export declare function formatBytes(n: number): string;
+/**
+ * Build a fixed-width progress bar from a 0–1 fraction. Uses
+ * solid + light blocks (▰ + ▱) — both BMP characters that render in
+ * every modern terminal. Falls back to ASCII (# + -) when
+ * `asciiOnly` is true.
+ */
+export declare function buildBar(fraction: number, width?: number, asciiOnly?: boolean): string;
+/**
+ * Compose the full progress line for one ongoing download. Shape:
+ *
+ *   [▰▰▰▰▰▰▰▱▱▱▱▱] 58%  450.2 MB / 600.0 MB  downloading
+ *
+ * Caller is responsible for any leading `\r` (in-place update) or
+ * trailing `\n` (final flush).
+ */
+export declare function buildProgressLine(completed: number, total: number, label: string, options?: {
+    width?: number;
+    asciiOnly?: boolean;
+}): string;
+/**
+ * Build a line for indeterminate phases (manifest, verify, etc.) where
+ * no `completed/total` is available. Shape:
+ *
+ *   ⋯ verifying sha256 digest
+ *
+ * The leading glyph is a unicode horizontal ellipsis; falls back to
+ * `...` when `asciiOnly`.
+ */
+export declare function buildSpinnerLine(label: string, asciiOnly?: boolean): string;
+/**
+ * Clear the current line so the next write starts fresh. Used between
+ * in-place progress updates and a final ✓ line.
+ */
+export declare function clearLineSequence(): string;

package/dist/setup/progress-bar.js

@@ -0,0 +1,85 @@
+/**
+ * Terminal progress bar rendering for the model pull (WU 135).
+ *
+ * Pure functions — no I/O. The caller writes the returned string to
+ * stderr with a leading `\r` for in-place updates, or to stdout when
+ * not in a TTY. The renderer is split into formatters (`formatBytes`,
+ * `buildBar`) and a composer (`buildProgressLine`) so each piece is
+ * independently testable.
+ *
+ * @module setup/progress-bar
+ */
+/**
+ * Format a byte count as a human-readable string with one decimal place.
+ * Uses 1024-based units (KiB / MiB / GiB) but labels them KB / MB / GB
+ * since that's what most users expect to see from a CLI.
+ */
+export function formatBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return '0 B';
+    if (n < 1024)
+        return `${n} B`;
+    const kb = n / 1024;
+    if (kb < 1024)
+        return `${kb.toFixed(1)} KB`;
+    const mb = kb / 1024;
+    if (mb < 1024)
+        return `${mb.toFixed(1)} MB`;
+    const gb = mb / 1024;
+    return `${gb.toFixed(2)} GB`;
+}
+/**
+ * Build a fixed-width progress bar from a 0–1 fraction. Uses
+ * solid + light blocks (▰ + ▱) — both BMP characters that render in
+ * every modern terminal. Falls back to ASCII (# + -) when
+ * `asciiOnly` is true.
+ */
+export function buildBar(fraction, width = 30, asciiOnly = false) {
+    const f = Math.max(0, Math.min(1, fraction));
+    const filled = Math.round(f * width);
+    const empty = width - filled;
+    if (asciiOnly) {
+        return `[${'#'.repeat(filled)}${'-'.repeat(empty)}]`;
+    }
+    return `[${'▰'.repeat(filled)}${'▱'.repeat(empty)}]`;
+}
+/**
+ * Compose the full progress line for one ongoing download. Shape:
+ *
+ *   [▰▰▰▰▰▰▰▱▱▱▱▱] 58%  450.2 MB / 600.0 MB  downloading
+ *
+ * Caller is responsible for any leading `\r` (in-place update) or
+ * trailing `\n` (final flush).
+ */
+export function buildProgressLine(completed, total, label, options = {}) {
+    const width = options.width ?? 30;
+    const fraction = total > 0 ? completed / total : 0;
+    const percent = Math.round(fraction * 100);
+    const bar = buildBar(fraction, width, options.asciiOnly);
+    const bytes = `${formatBytes(completed)} / ${formatBytes(total)}`;
+    const percentStr = `${percent.toString().padStart(3)}%`;
+    return `${bar} ${percentStr}  ${bytes}  ${label}`;
+}
+/**
+ * Build a line for indeterminate phases (manifest, verify, etc.) where
+ * no `completed/total` is available. Shape:
+ *
+ *   ⋯ verifying sha256 digest
+ *
+ * The leading glyph is a unicode horizontal ellipsis; falls back to
+ * `...` when `asciiOnly`.
+ */
+export function buildSpinnerLine(label, asciiOnly = false) {
+    const glyph = asciiOnly ? '...' : '⋯';
+    return `${glyph} ${label}`;
+}
+/**
+ * Clear the current line so the next write starts fresh. Used between
+ * in-place progress updates and a final ✓ line.
+ */
+export function clearLineSequence() {
+    // \r returns to column 0; the spaces overwrite anything previously
+    // written on this line; the second \r returns to column 0 again so
+    // the next print starts at the left.
+    return `\r${' '.repeat(80)}\r`;
+}

package/dist/setup/run-llm-setup.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Orchestrates the LLM-setup phase of `init` (WU 135).
+ *
+ * Both `init` (when not run with `--no-llm`) and the standalone
+ * `setup-llm` command call this function. The shape of the work:
+ *
+ *   1. Probe Ollama CLI + API.
+ *   2. If neither — offer to install (platform-specific).
+ *   3. If installed but API not reachable — print start instructions.
+ *   4. Probe for `qwen3-embedding:0.6b`.
+ *   5. If missing — pull it with a live progress bar.
+ *   6. Return a discriminated `LlmSetupResult`.
+ *
+ * I/O is injectable via the options bag so tests can run the whole
+ * orchestrator with mocked probes and prompts.
+ *
+ * @module setup/run-llm-setup
+ */
+import type { InstallOffer, LlmSetupResult, OllamaApiProbe, OllamaCliProbe, ModelProbe, Platform, PullEvent } from './types.js';
+import { OLLAMA_DOWNLOAD_URL } from './ollama-install.js';
+/** The default embedding model — matches `src/embedder/ollama.ts`. */
+export declare const DEFAULT_EMBEDDING_MODEL = "qwen3-embedding:0.6b";
+/** Injectable dependencies for testing. */
+export interface RunLlmSetupDeps {
+    platform: Platform;
+    detectCli: (p: Platform) => Promise<OllamaCliProbe>;
+    detectBrewCli: () => Promise<OllamaCliProbe>;
+    detectApi: (host: string) => Promise<OllamaApiProbe>;
+    detectModel: (host: string, model: string) => Promise<ModelProbe>;
+    installer: (offer: InstallOffer, onLine: (l: string) => void) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    opener: (url: string, p: Platform) => Promise<void>;
+    pull: (host: string, model: string, onEvent: (e: PullEvent) => void) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+}
+/** Public options the caller (init / setup-llm) passes in. */
+export interface RunLlmSetupOptions {
+    host?: string;
+    model?: string;
+    /**
+     * When true, no prompts are issued and any "would you like to install" gate
+     * defaults to NO. Use this in CI / unattended contexts. Default: false (we
+     * ask the user).
+     */
+    nonInteractive?: boolean;
+    /** Output sink — defaults to writing to process.stderr. */
+    out?: (text: string) => void;
+    /**
+     * Prompt callback — defaults to a readline-backed yes/no prompt. Tests
+     * provide a mock. Returns true for yes, false for no.
+     */
+    confirm?: (question: string) => Promise<boolean>;
+    /** Dependency injection — defaults to the real Ollama probes. */
+    deps?: Partial<RunLlmSetupDeps>;
+}
+/**
+ * Run the LLM-setup phase. Pure-result return — never throws on user-
+ * facing failures. The caller turns the result into a one-line summary
+ * for the surrounding command's output.
+ */
+export declare function runLlmSetup(opts?: RunLlmSetupOptions): Promise<LlmSetupResult>;
+/** Re-export of the download URL for callers that want to print it. */
+export { OLLAMA_DOWNLOAD_URL };

package/dist/setup/run-llm-setup.js

@@ -0,0 +1,242 @@
+/**
+ * Orchestrates the LLM-setup phase of `init` (WU 135).
+ *
+ * Both `init` (when not run with `--no-llm`) and the standalone
+ * `setup-llm` command call this function. The shape of the work:
+ *
+ *   1. Probe Ollama CLI + API.
+ *   2. If neither — offer to install (platform-specific).
+ *   3. If installed but API not reachable — print start instructions.
+ *   4. Probe for `qwen3-embedding:0.6b`.
+ *   5. If missing — pull it with a live progress bar.
+ *   6. Return a discriminated `LlmSetupResult`.
+ *
+ * I/O is injectable via the options bag so tests can run the whole
+ * orchestrator with mocked probes and prompts.
+ *
+ * @module setup/run-llm-setup
+ */
+import { narrowPlatform } from './types.js';
+import { DEFAULT_OLLAMA_HOST, detectModelPresent, detectOllamaApi, detectOllamaCli, } from './ollama-detect.js';
+import { buildInstallOffer, openInBrowser, OLLAMA_DOWNLOAD_URL, runInstaller, } from './ollama-install.js';
+import { pullModel } from './ollama-pull.js';
+import { buildProgressLine, buildSpinnerLine, clearLineSequence, } from './progress-bar.js';
+/** The default embedding model — matches `src/embedder/ollama.ts`. */
+export const DEFAULT_EMBEDDING_MODEL = 'qwen3-embedding:0.6b';
+/** Approximate on-disk size of the default model, used in user-facing copy. */
+const DEFAULT_MODEL_SIZE_LABEL = '~600 MB';
+/**
+ * Default deps wired against the real Ollama functions. Tests override
+ * any subset of these via the `deps` field on the options.
+ */
+function defaultDeps() {
+    return {
+        platform: narrowPlatform(process.platform),
+        detectCli: detectOllamaCli,
+        detectBrewCli: async () => detectOllamaCli(narrowPlatform(process.platform)).then(() => ({ found: false }))
+            .catch(() => ({ found: false })),
+        detectApi: detectOllamaApi,
+        detectModel: detectModelPresent,
+        installer: runInstaller,
+        opener: openInBrowser,
+        pull: pullModel,
+    };
+}
+/**
+ * Probe `brew` specifically (separate from the generic CLI probe so we
+ * can use the same `detectOllamaCli` machinery and just check a
+ * different binary name).
+ */
+async function detectBrew(platform) {
+    if (platform !== 'darwin')
+        return false;
+    const probe = await detectBrewBinary();
+    return probe.found;
+}
+async function detectBrewBinary() {
+    // Inline duplicate of detectOllamaCli with the binary name swapped —
+    // keeps ollama-detect.ts narrowly scoped to its name.
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+        const child = spawn('which', ['brew'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        let stdout = '';
+        child.stdout.on('data', (c) => { stdout += c.toString('utf8'); });
+        child.on('error', () => resolve({ found: false }));
+        child.on('close', (code) => {
+            if (code === 0 && stdout.trim()) {
+                resolve({ found: true, path: stdout.split(/\r?\n/)[0]?.trim() });
+            }
+            else {
+                resolve({ found: false });
+            }
+        });
+    });
+}
+/**
+ * Default yes/no prompt. Returns false on EOF (non-TTY input) so unattended
+ * runs can't hang.
+ */
+async function defaultConfirm(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Default output sink — process.stderr so the bar doesn't pollute stdout pipes. */
+function defaultOut(text) {
+    process.stderr.write(text);
+}
+// ─── Orchestrator ────────────────────────────────────────────────────────
+/**
+ * Run the LLM-setup phase. Pure-result return — never throws on user-
+ * facing failures. The caller turns the result into a one-line summary
+ * for the surrounding command's output.
+ */
+export async function runLlmSetup(opts = {}) {
+    const out = opts.out ?? defaultOut;
+    const confirm = opts.confirm ?? defaultConfirm;
+    const host = opts.host ?? process.env.NUOS_CATALOGUE_OLLAMA_HOST ?? DEFAULT_OLLAMA_HOST;
+    const model = opts.model ?? process.env.NUOS_CATALOGUE_OLLAMA_MODEL ?? DEFAULT_EMBEDDING_MODEL;
+    const deps = { ...defaultDeps(), ...opts.deps };
+    // Step 1 — Probe Ollama CLI + API.
+    out('\nSetting up local semantic search…\n');
+    const cliProbe = await deps.detectCli(deps.platform);
+    const apiProbe = await deps.detectApi(host);
+    if (!cliProbe.found && !apiProbe.reachable) {
+        // Ollama is not installed.
+        const hasBrew = await detectBrew(deps.platform);
+        const offer = buildInstallOffer(deps.platform, hasBrew);
+        out(`\nOllama is not installed. ${offer.primaryDescription}.\n`);
+        out(`Reference: ${offer.fallbackUrl}\n`);
+        if (!offer.canAutoInstall) {
+            // Windows / brew-less macOS / unknown platforms: offer to open the page.
+            if (opts.nonInteractive) {
+                out('Skipping (non-interactive). Install Ollama, then run `nuos-catalogue setup-llm`.\n');
+                return { kind: 'install_offered_declined' };
+            }
+            const openIt = await confirm(`Open ${offer.fallbackUrl} in your browser?`);
+            if (openIt) {
+                await deps.opener(offer.fallbackUrl, deps.platform);
+                out('Browser opened. After installing Ollama, run `nuos-catalogue setup-llm` to finish.\n');
+            }
+            else {
+                out('Skipped. After installing Ollama, run `nuos-catalogue setup-llm`.\n');
+            }
+            return { kind: 'install_offered_declined' };
+        }
+        // We have a reliable CLI install path. Offer to run it.
+        if (opts.nonInteractive) {
+            out(`Skipping (non-interactive). Run \`${offer.primaryCommand}\` then re-run setup.\n`);
+            return { kind: 'install_offered_declined' };
+        }
+        const elevationNote = offer.requiresElevation ? ' (you will be asked for your password)' : '';
+        const runIt = await confirm(`Run \`${offer.primaryCommand}\` now?${elevationNote}`);
+        if (!runIt) {
+            out('Skipped. Install Ollama, then run `nuos-catalogue setup-llm` to finish.\n');
+            return { kind: 'install_offered_declined' };
+        }
+        out(`Running: ${offer.primaryCommand}\n`);
+        const installResult = await deps.installer(offer, (line) => out(`  ${line}\n`));
+        if (!installResult.ok) {
+            out(`\nInstall failed: ${installResult.error}\n`);
+            out(`Try installing manually from ${offer.fallbackUrl}, then run \`nuos-catalogue setup-llm\`.\n`);
+            return { kind: 'install_failed', error: installResult.error };
+        }
+        out('\nOllama installed.\n');
+        // After install, the API may not be running yet (the user needs to
+        // start the app on macOS, or the systemd unit might be queued on
+        // Linux). Re-probe and steer the user appropriately.
+        const postInstallApi = await deps.detectApi(host);
+        if (!postInstallApi.reachable) {
+            out('\nOllama is installed but not running yet.\n');
+            if (deps.platform === 'darwin') {
+                out('Open the Ollama app (Spotlight → Ollama), then run `nuos-catalogue setup-llm`.\n');
+            }
+            else if (deps.platform === 'linux') {
+                out('Start Ollama with `ollama serve` (or `systemctl start ollama` on systems where the unit is installed), then run `nuos-catalogue setup-llm`.\n');
+            }
+            else {
+                out('Launch the Ollama app, then run `nuos-catalogue setup-llm`.\n');
+            }
+            return { kind: 'ollama_installed_but_not_running' };
+        }
+        // API is reachable — fall through to the model-pull step below.
+    }
+    else if (cliProbe.found && !apiProbe.reachable) {
+        out('\nOllama is installed but not running.\n');
+        if (deps.platform === 'darwin') {
+            out('Open the Ollama app, then run `nuos-catalogue setup-llm`.\n');
+        }
+        else if (deps.platform === 'linux') {
+            out('Start Ollama with `ollama serve`, then run `nuos-catalogue setup-llm`.\n');
+        }
+        else {
+            out('Launch Ollama, then run `nuos-catalogue setup-llm`.\n');
+        }
+        return { kind: 'ollama_installed_but_not_running' };
+    }
+    else {
+        // API is reachable (with or without CLI on PATH — Docker / remote
+        // Ollama would have API but no local CLI).
+        const detail = cliProbe.path ? ` (CLI at ${cliProbe.path})` : '';
+        out(`✓ Ollama detected at ${host}${detail}.\n`);
+    }
+    // Step 2 — Check the model.
+    const modelProbe = await deps.detectModel(host, model);
+    if (modelProbe.present) {
+        out(`✓ ${model} already pulled (${DEFAULT_MODEL_SIZE_LABEL}).\n`);
+        return { kind: 'already_ready' };
+    }
+    // Step 3 — Pull the model with a progress bar.
+    out(`\nPulling ${model} (${DEFAULT_MODEL_SIZE_LABEL})…\n`);
+    // We render the bar to the same line repeatedly. Outside a TTY we
+    // fall back to line-per-status to keep logs readable.
+    const isTty = !!process.stderr.isTTY;
+    let lastLineLength = 0;
+    function renderPullLine(line) {
+        if (isTty) {
+            out(`\r${' '.repeat(Math.max(lastLineLength, line.length))}\r${line}`);
+            lastLineLength = line.length;
+        }
+        else {
+            out(`${line}\n`);
+        }
+    }
+    const pullResult = await deps.pull(host, model, (event) => {
+        if (event.error) {
+            // Error events are emitted instead of status; let the wrapper handle.
+            return;
+        }
+        if (event.status === 'downloading' && typeof event.total === 'number' && typeof event.completed === 'number') {
+            const shortDigest = event.digest ? event.digest.slice(0, 12) : '';
+            renderPullLine(buildProgressLine(event.completed, event.total, `downloading ${shortDigest}`));
+        }
+        else if (event.status) {
+            renderPullLine(buildSpinnerLine(event.status));
+        }
+    });
+    // Close the bar line cleanly.
+    if (isTty)
+        out(clearLineSequence());
+    if (!pullResult.ok) {
+        out(`\nPull failed: ${pullResult.error}\n`);
+        out('Re-run `nuos-catalogue setup-llm` to retry — Ollama resumes partial pulls automatically.\n');
+        return { kind: 'pull_failed', error: pullResult.error };
+    }
+    out(`✓ ${model} ready.\n`);
+    out(`\nLocal semantic search is ready. Try \`nuos-catalogue search 'your query'\` after the first index.\n`);
+    // Differentiate the result based on whether we just installed Ollama
+    // this run, or only pulled the model.
+    return cliProbe.found || apiProbe.reachable
+        ? { kind: 'pulled_only' }
+        : { kind: 'installed_and_pulled' };
+}
+/** Re-export of the download URL for callers that want to print it. */
+export { OLLAMA_DOWNLOAD_URL };

package/dist/setup/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared types for the LLM-setup phase of `init` (WU 135).
+ *
+ * The setup phase runs after the scaffold and is responsible for
+ * detecting Ollama, offering to install it where reliable, and pulling
+ * the default embedding model (`qwen3-embedding:0.6b`, ~600MB) with a
+ * live progress bar.
+ *
+ * @module setup/types
+ */
+/** Node `process.platform` narrowed to the cases we handle. */
+export type Platform = 'darwin' | 'linux' | 'win32' | 'other';
+/** Result of probing for the Ollama CLI binary on PATH. */
+export interface OllamaCliProbe {
+    found: boolean;
+    /** Resolved path when `found`. */
+    path?: string;
+}
+/** Result of probing the Ollama HTTP API. */
+export interface OllamaApiProbe {
+    reachable: boolean;
+    /** Host the probe used (e.g. "http://localhost:11434"). */
+    host: string;
+    /** Error message when `!reachable`. */
+    error?: string;
+}
+/** Result of querying the local model list. */
+export interface ModelProbe {
+    present: boolean;
+    /** Model identifier we probed for (e.g. "qwen3-embedding:0.6b"). */
+    model: string;
+}
+/**
+ * One event from the Ollama `/api/pull` NDJSON stream. The status
+ * strings come straight from Ollama; we treat them as opaque except for
+ * the distinguished cases used to render the progress bar.
+ *
+ * Known status values observed in practice:
+ *   - "pulling manifest"
+ *   - "downloading"          (carries digest + total + completed)
+ *   - "verifying sha256 digest"
+ *   - "writing manifest"
+ *   - "removing any unused layers"
+ *   - "success"
+ *
+ * An `error` field is set instead of `status` on failure.
+ */
+export interface PullEvent {
+    status?: string;
+    digest?: string;
+    total?: number;
+    completed?: number;
+    error?: string;
+}
+/**
+ * Outcome of the LLM-setup phase. Returned to the caller (init or the
+ * standalone `setup-llm` command) so the surrounding UX can render an
+ * appropriate summary line.
+ */
+export type LlmSetupResult = {
+    kind: 'already_ready';
+} | {
+    kind: 'installed_and_pulled';
+} | {
+    kind: 'pulled_only';
+} | {
+    kind: 'install_offered_declined';
+} | {
+    kind: 'install_failed';
+    error: string;
+} | {
+    kind: 'ollama_installed_but_not_running';
+} | {
+    kind: 'pull_failed';
+    error: string;
+} | {
+    kind: 'skipped';
+    reason: string;
+};
+/**
+ * Per-platform install offer the CLI can present to the user. The
+ * `canAutoInstall` flag is the gate for offering to run the install
+ * command directly — false on Windows (no reliable CLI install path).
+ */
+export interface InstallOffer {
+    platform: Platform;
+    /** The shell command the offer would run (empty string when !canAutoInstall). */
+    primaryCommand: string;
+    /** Plain-English description of the primary path. */
+    primaryDescription: string;
+    /** Download page URL — always present as the safe fallback. */
+    fallbackUrl: string;
+    /** Whether we have a reliable CLI install path to offer running. */
+    canAutoInstall: boolean;
+    /** Whether the primary command needs sudo. Used to phrase the prompt. */
+    requiresElevation: boolean;
+}
+/** Narrow Node's process.platform string to our Platform union. */
+export declare function narrowPlatform(p: NodeJS.Platform): Platform;

package/dist/setup/types.js

@@ -0,0 +1,20 @@
+/**
+ * Shared types for the LLM-setup phase of `init` (WU 135).
+ *
+ * The setup phase runs after the scaffold and is responsible for
+ * detecting Ollama, offering to install it where reliable, and pulling
+ * the default embedding model (`qwen3-embedding:0.6b`, ~600MB) with a
+ * live progress bar.
+ *
+ * @module setup/types
+ */
+/** Narrow Node's process.platform string to our Platform union. */
+export function narrowPlatform(p) {
+    if (p === 'darwin')
+        return 'darwin';
+    if (p === 'linux')
+        return 'linux';
+    if (p === 'win32')
+        return 'win32';
+    return 'other';
+}