@pugi/cli 0.1.0-beta.3 → 0.1.0-beta.31

package/dist/runtime/commands/style.js

@@ -0,0 +1,194 @@
+/**
+ * Leak L18 (2026-05-27) — `pugi style` top-level command + REPL slash
+ * companion.
+ *
+ * Operator surface:
+ *
+ *   pugi style                       Show active preset + table.
+ *   pugi style <name>                Switch workspace preset (current cwd).
+ *   pugi style <name> --persist      Switch + also write user default.
+ *   pugi style --reset               Clear workspace override → back to default.
+ *   pugi style --reset --user        Also clear the user default.
+ *   pugi style --list                Print the catalogue (no flip).
+ *   pugi style --json                Structured envelope variant.
+ *
+ * The same runner powers `/style` from inside the REPL. The REPL
+ * dispatcher (see `core/repl/session.ts`) routes through here so the
+ * two surfaces stay single-sourced — operators trained on one read
+ * the same payload + table on the other.
+ *
+ * Exit codes:
+ *   0 — show / switch / reset all succeed
+ *   1 — unknown preset slug (returned BEFORE any write)
+ *   2 — conflicting flags (e.g. `--reset` with a positional slug)
+ *
+ * The exit codes are surfaced through `process.exitCode` by the
+ * dispatcher in `cli.ts` — this module returns a structured payload
+ * + writes via the injected `writeOutput`. Throwing is reserved for
+ * truly unexpected errors (fs permissions etc.); the spec hooks the
+ * happy + sad paths through `writeOutput` shape, not via try/catch
+ * on the throw.
+ */
+import { DEFAULT_OUTPUT_STYLE, isOutputStyleSlug, OUTPUT_STYLE_SLUGS, renderStyleTable, } from '../../core/output-style/presets.js';
+import { clearUserOutputStyle, clearWorkspaceOutputStyle, resolveOutputStyle, setUserOutputStyle, setWorkspaceOutputStyle, } from '../../core/output-style/state.js';
+/**
+ * Entry point. Parses `args`, applies the operation, emits the
+ * payload + text via `ctx.writeOutput`, and returns the exit code the
+ * dispatcher should hand back to the shell.
+ */
+export async function runStyleCommand(args, ctx) {
+    const flags = parseFlags(args);
+    // Reset path
+    if (flags.reset) {
+        if (flags.slug !== null) {
+            const payload = buildPayload({
+                status: 'invalid_flags',
+                ctx,
+                message: '/style --reset cannot be combined with a preset name. Use one or the other.',
+            });
+            ctx.writeOutput(payload, payload.message);
+            return 2;
+        }
+        if (flags.persist) {
+            const payload = buildPayload({
+                status: 'invalid_flags',
+                ctx,
+                message: '/style --reset cannot be combined with --persist. Use --reset --user to also clear the user default.',
+            });
+            ctx.writeOutput(payload, payload.message);
+            return 2;
+        }
+        clearWorkspaceOutputStyle({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        if (flags.user) {
+            clearUserOutputStyle({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        }
+        const payload = buildPayload({
+            status: 'reset',
+            ctx,
+            message: flags.user
+                ? `Cleared workspace + user output style. Active: ${DEFAULT_OUTPUT_STYLE} (default).`
+                : `Cleared workspace output style. Active: ${describeActive(ctx)}.`,
+        });
+        ctx.writeOutput(payload, payload.message);
+        return 0;
+    }
+    // List path
+    if (flags.list && flags.slug === null) {
+        const resolved = resolveOutputStyle({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        const payload = buildPayload({
+            status: 'listed',
+            ctx,
+            message: renderStyleTable(resolved.slug),
+        });
+        ctx.writeOutput(payload, payload.message);
+        return 0;
+    }
+    // Switch path
+    if (flags.slug !== null) {
+        if (!isOutputStyleSlug(flags.slug)) {
+            const payload = buildPayload({
+                status: 'invalid_slug',
+                ctx,
+                attemptedSlug: flags.slug,
+                message: `Unknown style "${flags.slug}". Try one of: ${OUTPUT_STYLE_SLUGS.join(', ')}.`,
+            });
+            ctx.writeOutput(payload, payload.message);
+            return 1;
+        }
+        const before = resolveOutputStyle({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        setWorkspaceOutputStyle(flags.slug, { workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        if (flags.persist) {
+            setUserOutputStyle(flags.slug, { workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        }
+        const tail = flags.persist ? ' (workspace + user default)' : ' (workspace)';
+        const payload = buildPayload({
+            status: 'switched',
+            ctx,
+            previous: before.slug,
+            persistedToUser: flags.persist,
+            message: `Output style → ${flags.slug}${tail}. Was: ${before.slug} (${before.source}).`,
+        });
+        ctx.writeOutput(payload, payload.message);
+        return 0;
+    }
+    // Show path (no args)
+    const resolved = resolveOutputStyle({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+    const banner = `Active output style: ${resolved.slug} (${resolved.source})`;
+    const table = renderStyleTable(resolved.slug);
+    const payload = buildPayload({
+        status: 'show',
+        ctx,
+        message: `${banner}\n\n${table}`,
+    });
+    ctx.writeOutput(payload, payload.message);
+    return 0;
+}
+function describeActive(ctx) {
+    const resolved = resolveOutputStyle({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+    return `${resolved.slug} (${resolved.source})`;
+}
+function buildPayload(args) {
+    const resolved = resolveOutputStyle({ workspaceRoot: args.ctx.workspaceRoot, env: args.ctx.env });
+    const payload = {
+        command: 'style',
+        status: args.status,
+        active: resolved.slug,
+        source: resolved.source,
+        presets: OUTPUT_STYLE_SLUGS,
+        message: args.message,
+    };
+    if (args.previous !== undefined)
+        payload.previous = args.previous;
+    if (args.persistedToUser !== undefined)
+        payload.persistedToUser = args.persistedToUser;
+    if (args.attemptedSlug !== undefined)
+        payload.attemptedSlug = args.attemptedSlug;
+    return payload;
+}
+function parseFlags(args) {
+    const flags = {
+        slug: null,
+        persist: false,
+        reset: false,
+        user: false,
+        list: false,
+    };
+    for (const arg of args) {
+        if (arg === '--persist')
+            flags.persist = true;
+        else if (arg === '--reset')
+            flags.reset = true;
+        else if (arg === '--user')
+            flags.user = true;
+        else if (arg === '--list')
+            flags.list = true;
+        else if (arg.startsWith('-')) {
+            // Unknown flag — keep simple parser. Treat as positional so the
+            // downstream isOutputStyleSlug check rejects it with a clear
+            // "unknown style" message rather than swallowing silently.
+            if (flags.slug === null)
+                flags.slug = arg;
+        }
+        else if (flags.slug === null) {
+            flags.slug = arg;
+        }
+    }
+    // Normalise the slug to lowercase so `pugi style TERSE` works the
+    // same as `pugi style terse`. The catalogue is lowercase-only by
+    // contract; this keeps operators from tripping on shift-key habits.
+    if (flags.slug !== null)
+        flags.slug = flags.slug.toLowerCase();
+    return flags;
+}
+/**
+ * Re-export for the slash-command dispatcher in `core/repl/session.ts`
+ * so it can render a compiled prompt block when the operator runs
+ * `/style --preview` (follow-up surface; current slash returns the
+ * runner's standard payload).
+ *
+ * Kept here so the runtime module is the single import point for
+ * style-related surfaces; consumers should NOT reach into
+ * `core/output-style/*` directly.
+ */
+export { OUTPUT_STYLES as OUTPUT_STYLE_CATALOGUE, } from '../../core/output-style/presets.js';
+//# sourceMappingURL=style.js.map

package/dist/runtime/commands/theme.js

@@ -0,0 +1,196 @@
+/**
+ * Leak L30 (2026-05-27) — `pugi theme` top-level command + REPL slash
+ * companion.
+ *
+ * Operator surface:
+ *
+ *   pugi theme                       Show active theme + table.
+ *   pugi theme <name>                Switch workspace theme (current cwd).
+ *   pugi theme <name> --persist      Switch + also write user default.
+ *   pugi theme --reset               Clear workspace override → back to default.
+ *   pugi theme --reset --user        Also clear the user default.
+ *   pugi theme --list                Print the catalogue (no flip).
+ *   pugi theme --json                Structured envelope variant.
+ *
+ * The same runner powers `/theme` from inside the REPL. The REPL
+ * dispatcher (see `core/repl/session.ts`) routes through here so the
+ * two surfaces stay single-sourced — operators trained on one read
+ * the same payload + table on the other. Matches the leak L18
+ * `/style` runner exactly so the two settings surfaces are
+ * paste-comparable for the operator + grep-comparable for future
+ * maintenance.
+ *
+ * Exit codes:
+ *   0 — show / switch / reset all succeed
+ *   1 — unknown preset slug (returned BEFORE any write)
+ *   2 — conflicting flags (e.g. `--reset` with a positional slug)
+ *
+ * The exit codes are surfaced through `process.exitCode` by the
+ * dispatcher in `cli.ts` — this module returns a structured payload
+ * + writes via the injected `writeOutput`. Throwing is reserved for
+ * truly unexpected errors (fs permissions etc.); the spec hooks the
+ * happy + sad paths through `writeOutput` shape, not via try/catch
+ * on the throw.
+ */
+import { DEFAULT_THEME, isThemeSlug, renderThemeTable, THEME_SLUGS, } from '../../core/theme/presets.js';
+import { clearUserTheme, clearWorkspaceTheme, resolveTheme, setUserTheme, setWorkspaceTheme, } from '../../core/theme/state.js';
+/**
+ * Entry point. Parses `args`, applies the operation, emits the
+ * payload + text via `ctx.writeOutput`, and returns the exit code the
+ * dispatcher should hand back to the shell.
+ */
+export async function runThemeCommand(args, ctx) {
+    const flags = parseFlags(args);
+    // Reset path
+    if (flags.reset) {
+        if (flags.slug !== null) {
+            const payload = buildPayload({
+                status: 'invalid_flags',
+                ctx,
+                message: '/theme --reset cannot be combined with a preset name. Use one or the other.',
+            });
+            ctx.writeOutput(payload, payload.message);
+            return 2;
+        }
+        if (flags.persist) {
+            const payload = buildPayload({
+                status: 'invalid_flags',
+                ctx,
+                message: '/theme --reset cannot be combined with --persist. Use --reset --user to also clear the user default.',
+            });
+            ctx.writeOutput(payload, payload.message);
+            return 2;
+        }
+        clearWorkspaceTheme({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        if (flags.user) {
+            clearUserTheme({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        }
+        const payload = buildPayload({
+            status: 'reset',
+            ctx,
+            message: flags.user
+                ? `Cleared workspace + user theme. Active: ${DEFAULT_THEME} (default).`
+                : `Cleared workspace theme. Active: ${describeActive(ctx)}.`,
+        });
+        ctx.writeOutput(payload, payload.message);
+        return 0;
+    }
+    // List path
+    if (flags.list && flags.slug === null) {
+        const resolved = resolveTheme({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        const payload = buildPayload({
+            status: 'listed',
+            ctx,
+            message: renderThemeTable(resolved.slug),
+        });
+        ctx.writeOutput(payload, payload.message);
+        return 0;
+    }
+    // Switch path
+    if (flags.slug !== null) {
+        if (!isThemeSlug(flags.slug)) {
+            const payload = buildPayload({
+                status: 'invalid_slug',
+                ctx,
+                attemptedSlug: flags.slug,
+                message: `Unknown theme "${flags.slug}". Try one of: ${THEME_SLUGS.join(', ')}.`,
+            });
+            ctx.writeOutput(payload, payload.message);
+            return 1;
+        }
+        const before = resolveTheme({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        setWorkspaceTheme(flags.slug, { workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        if (flags.persist) {
+            setUserTheme(flags.slug, { workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+        }
+        const tail = flags.persist ? ' (workspace + user default)' : ' (workspace)';
+        const payload = buildPayload({
+            status: 'switched',
+            ctx,
+            previous: before.slug,
+            persistedToUser: flags.persist,
+            message: `Theme → ${flags.slug}${tail}. Was: ${before.slug} (${before.source}).`,
+        });
+        ctx.writeOutput(payload, payload.message);
+        return 0;
+    }
+    // Show path (no args)
+    const resolved = resolveTheme({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+    const banner = `Active theme: ${resolved.slug} (${resolved.source})`;
+    const table = renderThemeTable(resolved.slug);
+    const payload = buildPayload({
+        status: 'show',
+        ctx,
+        message: `${banner}\n\n${table}`,
+    });
+    ctx.writeOutput(payload, payload.message);
+    return 0;
+}
+function describeActive(ctx) {
+    const resolved = resolveTheme({ workspaceRoot: ctx.workspaceRoot, env: ctx.env });
+    return `${resolved.slug} (${resolved.source})`;
+}
+function buildPayload(args) {
+    const resolved = resolveTheme({ workspaceRoot: args.ctx.workspaceRoot, env: args.ctx.env });
+    const payload = {
+        command: 'theme',
+        status: args.status,
+        active: resolved.slug,
+        source: resolved.source,
+        presets: THEME_SLUGS,
+        message: args.message,
+    };
+    if (args.previous !== undefined)
+        payload.previous = args.previous;
+    if (args.persistedToUser !== undefined)
+        payload.persistedToUser = args.persistedToUser;
+    if (args.attemptedSlug !== undefined)
+        payload.attemptedSlug = args.attemptedSlug;
+    return payload;
+}
+function parseFlags(args) {
+    const flags = {
+        slug: null,
+        persist: false,
+        reset: false,
+        user: false,
+        list: false,
+    };
+    for (const arg of args) {
+        if (arg === '--persist')
+            flags.persist = true;
+        else if (arg === '--reset')
+            flags.reset = true;
+        else if (arg === '--user')
+            flags.user = true;
+        else if (arg === '--list')
+            flags.list = true;
+        else if (arg.startsWith('-')) {
+            // Unknown flag — keep simple parser. Treat as positional so the
+            // downstream isThemeSlug check rejects it with a clear "unknown
+            // theme" message rather than swallowing silently. Mirrors the
+            // L18 style runner's behaviour for grep-parity.
+            if (flags.slug === null)
+                flags.slug = arg;
+        }
+        else if (flags.slug === null) {
+            flags.slug = arg;
+        }
+    }
+    // Normalise the slug to lowercase so `pugi theme DARK` works the
+    // same as `pugi theme dark`. The catalogue is lowercase-only by
+    // contract; this keeps operators from tripping on shift-key habits.
+    if (flags.slug !== null)
+        flags.slug = flags.slug.toLowerCase();
+    return flags;
+}
+/**
+ * Re-export for the slash-command dispatcher in
+ * `core/repl/session.ts` so it can render a preview block if a
+ * future surface (`/theme --preview`) lands. Kept here so the
+ * runtime module is the single import point for theme-related
+ * surfaces; consumers should NOT reach into `core/theme/*` directly
+ * unless they are Ink components that need the React context.
+ */
+export { THEMES as THEME_CATALOGUE, } from '../../core/theme/presets.js';
+//# sourceMappingURL=theme.js.map

package/dist/runtime/commands/update.js

@@ -0,0 +1,289 @@
+/**
+ * Leak L27 (2026-05-27) — `pugi update` dispatcher.
+ *
+ * Top-level command + in-REPL `/update` slash share this handler.
+ * Both surfaces delegate IO + persistence here so the channel
+ * resolution, the registry probe, and the install shell-out stay
+ * single-sourced.
+ *
+ * Command grammar:
+ *
+ *   pugi update                     -> probe + interactive prompt
+ *   pugi update --check             -> probe + JSON envelope (scripted)
+ *   pugi update --channel <name>    -> switch channel + probe
+ *   pugi update --apply             -> probe + shell `npm i -g …`
+ *                                      (confirms unless --yes)
+ *   pugi update --apply --yes       -> probe + shell, no confirmation
+ *
+ * Exit codes:
+ *
+ *   0 — happy path (no update OR update completed) OR `--check` JSON
+ *   1 — install / probe failure with structured error envelope
+ *   2 — argument error (bad channel, conflicting flags)
+ *
+ * R2 atomic swap deferred (sprint plan L27 mention): the leak research
+ * also describes Claude Code's R2-backed binary swap. Pugi ships
+ * exclusively via npm today; building a parallel R2 distribution
+ * channel + checksum verification + rollback is materially more work
+ * than the L27 acceptance criteria allow. Document the deferral in
+ * the PR body and revisit when npm's once-per-day rate-limit or
+ * outage cadence justifies the parallel pipeline.
+ */
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { DEFAULT_UPDATE_CHANNEL, UPDATE_CHANNELS, describeChannel, npmTagForChannel, parseUpdateChannel, } from '../../core/auto-update/channels.js';
+import { checkForChannelUpdate, } from '../../core/auto-update/checker.js';
+import { resolveEffectiveChannel, setUpdateChannel, writeLastCheckedAt, } from '../../core/auto-update/state.js';
+import { PUGI_CLI_VERSION } from '../version.js';
+/**
+ * Default subprocess runner. Spawns `npm install -g @pugi/cli@<tag>`
+ * inheriting stdio so the operator sees the live npm output.
+ */
+export function defaultSpawnInstaller(channel) {
+    const tag = npmTagForChannel(channel);
+    const args = ['install', '-g', `@pugi/cli@${tag}`];
+    return new Promise((resolvePromise) => {
+        const child = spawn('npm', args, { stdio: 'inherit' });
+        child.on('exit', (code) => {
+            resolvePromise(typeof code === 'number' ? code : 1);
+        });
+        child.on('error', () => {
+            // ENOENT / EACCES — npm not on PATH or permission denied. We
+            // surface a non-zero code so the dispatcher's JSON envelope
+            // tells the operator the apply failed; the inherited stdio
+            // already printed the underlying error to the terminal.
+            resolvePromise(127);
+        });
+    });
+}
+/**
+ * Parse a CLI / slash argv into our `UpdateCommandFlags`. Returns
+ * `null` AND writes the usage error via `writeError` for conflicting
+ * combinations. Both `pugi update` and the in-REPL `/update <args>`
+ * surface call through this so the validation lives in one place.
+ */
+export function parseUpdateArgs(argv, options = {}) {
+    let check = false;
+    let apply = false;
+    let yes = false;
+    let json = options.jsonDefault ?? false;
+    let channel = null;
+    let channelInvalid;
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i] ?? '';
+        if (token === '--check') {
+            check = true;
+        }
+        else if (token === '--apply') {
+            apply = true;
+        }
+        else if (token === '--yes' || token === '-y') {
+            yes = true;
+        }
+        else if (token === '--json') {
+            json = true;
+        }
+        else if (token === '--channel') {
+            const value = argv[i + 1];
+            i += 1;
+            const parsed = parseUpdateChannel(value);
+            if (!parsed) {
+                channelInvalid = value ?? '';
+                continue;
+            }
+            channel = parsed;
+        }
+        else if (token.startsWith('--channel=')) {
+            const value = token.slice('--channel='.length);
+            const parsed = parseUpdateChannel(value);
+            if (!parsed) {
+                channelInvalid = value;
+                continue;
+            }
+            channel = parsed;
+        }
+        else {
+            return {
+                error: `pugi update: unknown argument '${token}'. See \`pugi update --help\`.`,
+            };
+        }
+    }
+    if (channelInvalid !== undefined) {
+        return {
+            error: `pugi update: unknown channel '${channelInvalid}'. Allowed: ${UPDATE_CHANNELS.join(' / ')}.`,
+        };
+    }
+    return {
+        check,
+        apply,
+        yes,
+        json,
+        channel,
+    };
+}
+/**
+ * Run the full command. Returns the structured envelope so the in-
+ * REPL slash can decide whether to render the human-readable text OR
+ * pretty-print the JSON.
+ */
+export async function runUpdateCommand(ctx) {
+    const flags = ctx.flags;
+    const home = ctx.home;
+    // 1. Resolve channel. `--channel <name>` wins; otherwise read the
+    //    persisted preference; otherwise hard default `beta`.
+    const cliFlagChannel = flags.channel;
+    const effectiveChannel = resolveEffectiveChannel({
+        cliFlag: cliFlagChannel,
+        homeDir: home,
+    });
+    // 2. Persist the channel switch BEFORE the probe so a probe failure
+    //    still leaves the operator on the channel they asked for.
+    let switched = false;
+    if (cliFlagChannel) {
+        setUpdateChannel(cliFlagChannel, home);
+        switched = true;
+    }
+    // 3. Probe the registry.
+    const outcome = await checkForChannelUpdate({
+        channel: effectiveChannel,
+        currentVersion: PUGI_CLI_VERSION,
+        ...(ctx.fetchImpl ? { fetchImpl: ctx.fetchImpl } : {}),
+        ...(ctx.registryUrl ? { registryUrl: ctx.registryUrl } : {}),
+    });
+    // 4. Record the timestamp on a successful probe (regardless of
+    //    whether an update is available). Failed probes do NOT update
+    //    the timestamp so the cold-start banner retries on the next
+    //    invocation.
+    if (!outcome.error) {
+        const now = ctx.now ? new Date(ctx.now()) : new Date();
+        try {
+            writeLastCheckedAt(now, home);
+        }
+        catch {
+            // Best-effort — a read-only home should not crash the dispatcher.
+        }
+    }
+    // 5. Build the envelope shape ALL action paths share.
+    const baseEnvelope = {
+        command: 'update',
+        ok: outcome.error === null,
+        available: outcome.available,
+        channel: outcome.channel,
+        npmTag: outcome.npmTag,
+        current: outcome.current,
+        latest: outcome.latest,
+        gap: outcome.gap,
+        installCommand: outcome.installCommand,
+        action: outcome.error ? 'error' : 'probe',
+        error: outcome.error,
+        meta: { cliVersion: PUGI_CLI_VERSION },
+    };
+    // 6. --check: emit the envelope, never prompt, never apply.
+    if (flags.check) {
+        const text = renderHumanText(baseEnvelope, { switched });
+        ctx.writeOutput(baseEnvelope, text);
+        return baseEnvelope;
+    }
+    // 7. No update available — bail with a friendly message.
+    if (!outcome.available || !outcome.latest) {
+        const envelope = {
+            ...baseEnvelope,
+            action: outcome.error ? 'error' : (switched ? 'switch' : 'no_update'),
+        };
+        const text = renderHumanText(envelope, { switched });
+        ctx.writeOutput(envelope, text);
+        return envelope;
+    }
+    // 8. Update IS available. Branch on --apply.
+    if (!flags.apply) {
+        // Default: print the offer, suggest the install command, leave
+        // the install to the operator. Mirrors the leak research note:
+        // operators install side-effects must remain explicit on the CLI
+        // happy path — `pugi update` showing the gap is informational,
+        // `pugi update --apply` is the destructive verb.
+        const envelope = {
+            ...baseEnvelope,
+            action: switched ? 'switch' : 'probe',
+        };
+        const text = renderHumanText(envelope, { switched });
+        ctx.writeOutput(envelope, text);
+        return envelope;
+    }
+    // 9. --apply path. Confirm unless --yes, then spawn npm.
+    const installer = ctx.spawnInstaller ?? defaultSpawnInstaller;
+    let confirmed = flags.yes;
+    if (!confirmed) {
+        confirmed = await ctx.promptConfirm(`Run \`${outcome.installCommand}\` to update ${outcome.current} -> ${outcome.latest}? [y/N]`);
+    }
+    if (!confirmed) {
+        const envelope = {
+            ...baseEnvelope,
+            action: 'probe',
+            ok: false,
+            error: 'apply_cancelled_by_operator',
+        };
+        const text = `Cancelled. Run \`${outcome.installCommand}\` manually when you are ready.`;
+        ctx.writeOutput(envelope, text);
+        return envelope;
+    }
+    const exitCode = await installer(outcome.channel);
+    const applyEnvelope = {
+        ...baseEnvelope,
+        action: 'apply',
+        installExitCode: exitCode,
+        ok: exitCode === 0,
+        error: exitCode === 0 ? null : `npm_install_exit_${exitCode}`,
+    };
+    const applyText = exitCode === 0
+        ? `Updated to @pugi/cli@${outcome.latest}. Restart your shell so the new binary takes effect.`
+        : `Update failed (npm exit ${exitCode}). Try \`${outcome.installCommand}\` manually.`;
+    ctx.writeOutput(applyEnvelope, applyText);
+    return applyEnvelope;
+}
+/**
+ * Build the operator-readable hint that lives next to the JSON
+ * envelope. The text + the JSON are both passed to `writeOutput`; the
+ * caller (`writeOutput` in cli.ts) picks based on `--json`. Exported
+ * so the spec can assert the literal strings the operator sees.
+ */
+export function renderHumanText(envelope, options = {}) {
+    const { current, latest, channel, installCommand, available, error } = envelope;
+    const lines = [];
+    lines.push(`Channel: ${channel} — ${describeChannel(channel)}`);
+    if (options.switched) {
+        lines.push(`Persisted channel selection -> ${channel}.`);
+    }
+    if (error) {
+        lines.push(`Update check failed: ${error}`);
+        lines.push(`Manual: \`${installCommand}\` (no probe necessary).`);
+        return lines.join('\n');
+    }
+    if (available && latest) {
+        lines.push(`Update available: ${current} -> ${latest}.`);
+        lines.push(`Run \`${installCommand}\` to upgrade.`);
+        lines.push(`Or \`pugi update --apply\` to upgrade with confirmation.`);
+        return lines.join('\n');
+    }
+    lines.push(`Up to date (${current} is the latest on ${channel}).`);
+    return lines.join('\n');
+}
+/**
+ * Render a one-line cold-start hint that callers (REPL boot, doctor
+ * banner) splice above their own UI. Returns `null` when there is
+ * nothing to nudge the operator about. Pure — no IO.
+ */
+export function renderUpdateHint(outcome) {
+    if (!outcome.available || !outcome.latest)
+        return null;
+    return `Update available: ${outcome.current} -> ${outcome.latest}. Run \`pugi update\`.`;
+}
+/**
+ * Convenience entry point — resolve the effective channel from
+ * `~/.pugi/config.json` + DEFAULT_UPDATE_CHANNEL without forcing the
+ * caller to import multiple modules. Used by the cold-start banner +
+ * the doctor probe.
+ */
+export function effectiveChannel(home = homedir()) {
+    return resolveEffectiveChannel({ homeDir: home }) ?? DEFAULT_UPDATE_CHANNEL;
+}
+//# sourceMappingURL=update.js.map