@webpresso/agent-kit 0.21.0

package/dist/esm/cli/auto-update/installer.js

@@ -0,0 +1,171 @@
+/**
+ * Deferred install scheduler.
+ *
+ * The auto-update flow calls this synchronously after detecting an
+ * available release. We DON'T wait for the install to finish — the parent
+ * process exits cleanly and the install completes in a detached child.
+ * The next invocation of `webpresso` picks up the new binary.
+ *
+ * Invariants (per plan Architecture decision 3 and Implementation surface
+ * "Auto-update wiring"):
+ *
+ *   - Synchronous: returns before the install starts.
+ *   - Detached + unref: the install survives the parent exit.
+ *   - Tombstone before spawn: `autoInstallInProgress = <pid+ts>` is written
+ *     to the configstore at `<state-root>/update-notifier-cache.json`
+ *     *before* the spawn fires, so concurrent invocations within the
+ *     lockout window (60s) skip the spawn.
+ *   - Stdio captured to file: child stdout / stderr are piped to
+ *     `<state-root>/auto-update.log` via an `openSync` file descriptor —
+ *     not via Node IPC, which would tie child lifetime to parent.
+ *   - Best-effort: any failure inside this function is logged via
+ *     `logUpdateError` and swallowed; the user never sees an exception
+ *     from a successful CLI run.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname } from 'node:path';
+import { getSurfacePath } from '#paths/state-root.js';
+import { logUpdateError } from './log.js';
+/**
+ * Concurrency-lockout window: a tombstone younger than this is considered
+ * active; further `scheduleDeferredInstall` calls become no-ops.
+ */
+export const LOCKOUT_MS = 60_000;
+/**
+ * Schedule a deferred install for the supplied command. Synchronous —
+ * spawn() returns immediately; the child runs in the background. The parent
+ * is free to `process.exit(0)` after this call returns.
+ */
+export function scheduleDeferredInstall(plan) {
+    try {
+        if (plan.command.length === 0) {
+            return { spawned: false, reason: 'empty install command' };
+        }
+        const configPath = resolveConfigPath();
+        if (configPath === null) {
+            return { spawned: false, reason: 'state root unavailable' };
+        }
+        const existing = readTombstone(configPath);
+        if (existing !== null && isTombstoneFresh(existing, Date.now())) {
+            return {
+                spawned: false,
+                reason: `recent install in progress (pid=${existing.autoInstallInProgress.pid})`,
+            };
+        }
+        const logPath = resolveLogPath();
+        if (logPath === null) {
+            return { spawned: false, reason: 'log path unavailable' };
+        }
+        const tombstone = buildTombstone(process.pid, Date.now());
+        writeTombstone(configPath, tombstone);
+        const logFd = openLogForAppend(logPath);
+        const command = plan.command[0]; // length checked above
+        const args = plan.command.slice(1);
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            windowsHide: true,
+        });
+        child.unref();
+        // Now safe to close our FD — the child has its own duplicates via stdio.
+        closeSync(logFd);
+        return { spawned: true };
+    }
+    catch (err) {
+        logUpdateError(err);
+        return { spawned: false, reason: 'spawn error' };
+    }
+}
+/**
+ * Clear the install-in-progress tombstone. Called by the install wrapper
+ * on exit, or by tests. Best-effort.
+ */
+export function clearInstallTombstone() {
+    try {
+        const configPath = resolveConfigPath();
+        if (configPath === null)
+            return;
+        if (!existsSync(configPath))
+            return;
+        const current = readTombstone(configPath);
+        if (current === null)
+            return;
+        const next = { ...readRaw(configPath) };
+        delete next.autoInstallInProgress;
+        writeFileSync(configPath, JSON.stringify(next));
+    }
+    catch {
+        // Best-effort — no caller waits on this.
+    }
+}
+/**
+ * Whether the given tombstone is within the lockout window relative to `now`.
+ * Exported for testability.
+ */
+export function isTombstoneFresh(tombstone, now) {
+    return now - tombstone.autoInstallInProgress.ts < LOCKOUT_MS;
+}
+/**
+ * Build the canonical tombstone shape. Exported for testability.
+ */
+export function buildTombstone(pid, ts) {
+    return { autoInstallInProgress: { pid, ts } };
+}
+function resolveConfigPath() {
+    try {
+        return getSurfacePath('update-notifier-cache.json', 'user');
+    }
+    catch {
+        return null;
+    }
+}
+function resolveLogPath() {
+    try {
+        return getSurfacePath('auto-update.log', 'user');
+    }
+    catch {
+        return null;
+    }
+}
+function readRaw(configPath) {
+    if (!existsSync(configPath))
+        return {};
+    try {
+        const text = readFileSync(configPath, 'utf-8');
+        if (text.trim().length === 0)
+            return {};
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+function readTombstone(configPath) {
+    const raw = readRaw(configPath);
+    const value = raw.autoInstallInProgress;
+    if (value === undefined || value === null || typeof value !== 'object')
+        return null;
+    const candidate = value;
+    if (typeof candidate.pid !== 'number' || typeof candidate.ts !== 'number')
+        return null;
+    return { autoInstallInProgress: { pid: candidate.pid, ts: candidate.ts } };
+}
+function writeTombstone(configPath, tombstone) {
+    const dir = dirname(configPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const merged = { ...readRaw(configPath), ...tombstone };
+    writeFileSync(configPath, JSON.stringify(merged));
+}
+function openLogForAppend(logPath) {
+    const dir = dirname(logPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // 'a' — create if missing, append, no truncation. Child inherits the offset.
+    return openSync(logPath, 'a');
+}
+//# sourceMappingURL=installer.js.map

package/dist/esm/cli/auto-update/log.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Auto-update error log.
+ *
+ * Append-only JSON-line log at `<state-root>/auto-update.log`. Used as the
+ * sink for `runUpdateFlow(...).catch(logUpdateError)` (per plan D13). Never
+ * throws — failures inside the logger are intentionally silent because the
+ * logger is itself the error handler of last resort.
+ *
+ * Each entry is a single JSON object on its own line:
+ *   { ts, level, message, stack? }
+ *
+ * The stack is truncated to 500 characters so a single rogue entry can't
+ * blow out the file budget. The file is rotated when it crosses 500 lines:
+ * the most recent 250 are kept, the rest dropped.
+ */
+export type LogLevel = 'error' | 'warn' | 'info';
+export interface LogEntry {
+    ts: string;
+    level: LogLevel;
+    message: string;
+    stack?: string;
+}
+export declare const MAX_LINES = 500;
+export declare const ROTATE_KEEP = 250;
+export declare const STACK_TRUNCATE = 500;
+/**
+ * Best-effort logger for auto-update flow errors. Sync (append happens before
+ * the parent process exits), never throws, never returns a value.
+ */
+export declare function logUpdateError(err: unknown): void;
+/**
+ * Convert an unknown thrown value into the canonical log entry shape.
+ * Exported for testing — pure (no I/O).
+ */
+export declare function buildEntry(err: unknown, now?: Date): LogEntry;
+/**
+ * Format a log entry as a single JSON line (newline terminated).
+ * Exported for testing — pure.
+ */
+export declare function formatLine(entry: LogEntry): string;
+/**
+ * Apply rotation policy to an array of lines. If lines exceeds MAX_LINES,
+ * keep only the last ROTATE_KEEP. Exported for testing — pure.
+ */
+export declare function rotateLines(lines: string[]): string[];
+//# sourceMappingURL=log.d.ts.map

package/dist/esm/cli/auto-update/log.js

@@ -0,0 +1,107 @@
+/**
+ * Auto-update error log.
+ *
+ * Append-only JSON-line log at `<state-root>/auto-update.log`. Used as the
+ * sink for `runUpdateFlow(...).catch(logUpdateError)` (per plan D13). Never
+ * throws — failures inside the logger are intentionally silent because the
+ * logger is itself the error handler of last resort.
+ *
+ * Each entry is a single JSON object on its own line:
+ *   { ts, level, message, stack? }
+ *
+ * The stack is truncated to 500 characters so a single rogue entry can't
+ * blow out the file budget. The file is rotated when it crosses 500 lines:
+ * the most recent 250 are kept, the rest dropped.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { getSurfacePath } from '#paths/state-root.js';
+export const MAX_LINES = 500;
+export const ROTATE_KEEP = 250;
+export const STACK_TRUNCATE = 500;
+/**
+ * Best-effort logger for auto-update flow errors. Sync (append happens before
+ * the parent process exits), never throws, never returns a value.
+ */
+export function logUpdateError(err) {
+    try {
+        const entry = buildEntry(err);
+        const logFile = resolveLogFile();
+        if (logFile === null)
+            return;
+        appendEntry(logFile, entry);
+        rotateIfNeeded(logFile);
+    }
+    catch {
+        // Best-effort: never propagate logging failure to the parent.
+    }
+}
+/**
+ * Convert an unknown thrown value into the canonical log entry shape.
+ * Exported for testing — pure (no I/O).
+ */
+export function buildEntry(err, now = new Date()) {
+    const ts = now.toISOString();
+    if (err instanceof Error) {
+        const stack = err.stack ? err.stack.slice(0, STACK_TRUNCATE) : undefined;
+        return { ts, level: 'error', message: err.message, stack };
+    }
+    if (typeof err === 'string') {
+        return { ts, level: 'error', message: err };
+    }
+    return { ts, level: 'error', message: safeStringify(err) };
+}
+/**
+ * Format a log entry as a single JSON line (newline terminated).
+ * Exported for testing — pure.
+ */
+export function formatLine(entry) {
+    return `${JSON.stringify(entry)}\n`;
+}
+/**
+ * Apply rotation policy to an array of lines. If lines exceeds MAX_LINES,
+ * keep only the last ROTATE_KEEP. Exported for testing — pure.
+ */
+export function rotateLines(lines) {
+    if (lines.length <= MAX_LINES)
+        return lines;
+    return lines.slice(-ROTATE_KEEP);
+}
+function resolveLogFile() {
+    try {
+        return getSurfacePath('auto-update.log', 'user');
+    }
+    catch {
+        return null;
+    }
+}
+function appendEntry(logFile, entry) {
+    const dir = dirname(logFile);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    appendFileSync(logFile, formatLine(entry));
+}
+function rotateIfNeeded(logFile) {
+    if (!existsSync(logFile))
+        return;
+    // Cheap early-out — only read+rewrite when the file has grown beyond budget.
+    const size = statSync(logFile).size;
+    // Each JSON line averages ≥40 bytes; ignore rotation work below that threshold.
+    if (size < MAX_LINES * 40)
+        return;
+    const content = readFileSync(logFile, 'utf-8');
+    const lines = content.split('\n').filter((line) => line.length > 0);
+    if (lines.length <= MAX_LINES)
+        return;
+    const kept = rotateLines(lines);
+    writeFileSync(logFile, `${kept.join('\n')}\n`);
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=log.js.map

package/dist/esm/cli/auto-update/run.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Auto-update orchestrator.
+ *
+ * `runUpdateFlow(version)` is the single entry point called from bootstrap.ts.
+ * It checks the npm registry for a newer version of @webpresso/agent-kit and,
+ * when one is available:
+ *   1. Writes a cache entry to the state root (read by the SessionStart banner).
+ *   2. Prints a one-line update notice to stderr.
+ *   3. Optionally schedules a deferred background install (unless opt-out).
+ *
+ * The function NEVER throws — all errors are sunk to logUpdateError per D13.
+ *
+ * ## Registry note
+ * Version checks use the public npm registry for the canonical
+ * `@webpresso/agent-kit` package.
+ */
+export declare function fetchLatestRelease(): Promise<string | null>;
+/**
+ * Orchestrate the full auto-update pipeline for the given package version.
+ * Resolves without throwing — any error is written to auto-update.log.
+ */
+export declare function runUpdateFlow(version: string): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/esm/cli/auto-update/run.js

@@ -0,0 +1,116 @@
+/**
+ * Auto-update orchestrator.
+ *
+ * `runUpdateFlow(version)` is the single entry point called from bootstrap.ts.
+ * It checks the npm registry for a newer version of @webpresso/agent-kit and,
+ * when one is available:
+ *   1. Writes a cache entry to the state root (read by the SessionStart banner).
+ *   2. Prints a one-line update notice to stderr.
+ *   3. Optionally schedules a deferred background install (unless opt-out).
+ *
+ * The function NEVER throws — all errors are sunk to logUpdateError per D13.
+ *
+ * ## Registry note
+ * Version checks use the public npm registry for the canonical
+ * `@webpresso/agent-kit` package.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getStateRoot } from '#paths/state-root.js';
+import { detect } from './detect-pm.js';
+import { scheduleDeferredInstall } from './installer.js';
+import { logUpdateError } from './log.js';
+import { shouldSkipAutoInstall } from './skip.js';
+const PUBLIC_NPM_URL = 'https://registry.npmjs.org/@webpresso%2Fagent-kit';
+const UPDATE_CHECK_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+const CACHE_FILENAME = 'update-notifier-cache.json';
+async function readCache(cachePath) {
+    try {
+        const raw = await readFile(cachePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.latest === 'string' &&
+            typeof parsed.current === 'string' &&
+            typeof parsed.lastUpdateCheck === 'number') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCache(cachePath, data) {
+    try {
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, JSON.stringify(data, null, 2) + '\n');
+    }
+    catch {
+        // Cache write failure is non-fatal
+    }
+}
+export async function fetchLatestRelease() {
+    const res = await fetch(PUBLIC_NPM_URL, {
+        headers: {
+            Accept: 'application/json',
+        },
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    return data['dist-tags']?.latest ?? null;
+}
+function isNewerVersion(latest, current) {
+    const l = latest.split('.').map((p) => parseInt(p, 10));
+    const c = current.split('.').map((p) => parseInt(p, 10));
+    const len = Math.max(l.length, c.length);
+    for (let i = 0; i < len; i++) {
+        const lv = l[i] ?? 0;
+        const cv = c[i] ?? 0;
+        if (Number.isNaN(lv) || Number.isNaN(cv))
+            return latest !== current;
+        if (lv > cv)
+            return true;
+        if (lv < cv)
+            return false;
+    }
+    return false;
+}
+/**
+ * Orchestrate the full auto-update pipeline for the given package version.
+ * Resolves without throwing — any error is written to auto-update.log.
+ */
+export async function runUpdateFlow(version) {
+    try {
+        const cachePath = join(getStateRoot(), CACHE_FILENAME);
+        const now = Date.now();
+        // Check 24-hour interval via cache
+        const cached = await readCache(cachePath);
+        let latest;
+        if (cached !== null && now - cached.lastUpdateCheck < UPDATE_CHECK_INTERVAL) {
+            latest = cached.latest;
+        }
+        else {
+            const fetched = await fetchLatestRelease();
+            if (fetched === null)
+                return;
+            latest = fetched;
+            await writeCache(cachePath, { latest, current: version, lastUpdateCheck: now });
+        }
+        if (!isNewerVersion(latest, version))
+            return;
+        // Notify on stderr — safe for all modes (MCP is gated upstream via shouldSkipUpdateCheck)
+        process.stderr.write(`\n  @webpresso/agent-kit ${version} → ${latest} available\n  Auto-install scheduled for next \`wp\` invocation.\n\n`);
+        if (shouldSkipAutoInstall(process.env))
+            return;
+        const plan = detect(process.env, process.argv[1] ?? '');
+        if ('abort' in plan) {
+            logUpdateError(new Error(plan.abort));
+            return;
+        }
+        scheduleDeferredInstall({ command: plan.command });
+    }
+    catch (err) {
+        logUpdateError(err);
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/esm/cli/auto-update/skip.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Decide whether to skip the auto-update check entirely for this invocation.
+ *
+ * Returning `true` means: bypass the *whole* update flow — no registry probe,
+ * no banner, no spawn. This is for invocations where running the flow would be
+ * either useless or actively harmful:
+ *
+ *   - `--version` / `-v` / `--help` / `-h` — informational verbs that should
+ *     never trigger background work.
+ *   - `mcp` subcommand — JSON-RPC stdio mode; stderr writes would corrupt the
+ *     transport.
+ *   - `WP_SKIP_UPDATE_CHECK=1` — explicit user opt-out of the whole flow.
+ *   - `CI=true` (and the broader set of CI signals via ci-info-style env
+ *     probing) — non-interactive environments don't want surprise spawns.
+ *
+ * `setup` / `init` intentionally DO NOT skip the update check: setup is the
+ * command users run when they want their agent surfaces refreshed, so it should
+ * also detect and schedule an webpresso package refresh when a newer version is
+ * available.
+ *
+ * `WP_SKIP_AUTO_INSTALL=1` does **not** appear here — that variable only
+ * disables the install step. The notify side of the flow still runs so users
+ * get a banner. That check belongs in the installer module.
+ */
+export declare const INFORMATIONAL_FLAGS: Set<string>;
+export declare const CI_ENV_KEYS: readonly ["CI", "CONTINUOUS_INTEGRATION", "BUILD_NUMBER", "RUN_ID", "GITHUB_ACTIONS", "GITLAB_CI", "CIRCLECI", "TRAVIS", "APPVEYOR", "BUILDKITE", "DRONE", "JENKINS_URL"];
+export declare function shouldSkipUpdateCheck(env: NodeJS.ProcessEnv, argv: string[]): boolean;
+/**
+ * Whether the installer step should be suppressed (still allow the notify-only
+ * banner). Separate from `shouldSkipUpdateCheck` so users can keep notifications
+ * but block automatic install.
+ */
+export declare function shouldSkipAutoInstall(env: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=skip.d.ts.map

package/dist/esm/cli/auto-update/skip.js

@@ -0,0 +1,84 @@
+/**
+ * Decide whether to skip the auto-update check entirely for this invocation.
+ *
+ * Returning `true` means: bypass the *whole* update flow — no registry probe,
+ * no banner, no spawn. This is for invocations where running the flow would be
+ * either useless or actively harmful:
+ *
+ *   - `--version` / `-v` / `--help` / `-h` — informational verbs that should
+ *     never trigger background work.
+ *   - `mcp` subcommand — JSON-RPC stdio mode; stderr writes would corrupt the
+ *     transport.
+ *   - `WP_SKIP_UPDATE_CHECK=1` — explicit user opt-out of the whole flow.
+ *   - `CI=true` (and the broader set of CI signals via ci-info-style env
+ *     probing) — non-interactive environments don't want surprise spawns.
+ *
+ * `setup` / `init` intentionally DO NOT skip the update check: setup is the
+ * command users run when they want their agent surfaces refreshed, so it should
+ * also detect and schedule an webpresso package refresh when a newer version is
+ * available.
+ *
+ * `WP_SKIP_AUTO_INSTALL=1` does **not** appear here — that variable only
+ * disables the install step. The notify side of the flow still runs so users
+ * get a banner. That check belongs in the installer module.
+ */
+export const INFORMATIONAL_FLAGS = new Set(['--version', '-v', '--help', '-h']);
+export const CI_ENV_KEYS = [
+    'CI',
+    'CONTINUOUS_INTEGRATION',
+    'BUILD_NUMBER',
+    'RUN_ID',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'CIRCLECI',
+    'TRAVIS',
+    'APPVEYOR',
+    'BUILDKITE',
+    'DRONE',
+    'JENKINS_URL',
+];
+const SKIP_SUBCOMMANDS = new Set(['mcp']);
+export function shouldSkipUpdateCheck(env, argv) {
+    if (hasInformationalFlag(argv))
+        return true;
+    if (argv[2] !== undefined && SKIP_SUBCOMMANDS.has(argv[2]))
+        return true;
+    if (env.WP_SKIP_UPDATE_CHECK === '1')
+        return true;
+    if (isCiEnvironment(env))
+        return true;
+    return false;
+}
+/**
+ * Whether the installer step should be suppressed (still allow the notify-only
+ * banner). Separate from `shouldSkipUpdateCheck` so users can keep notifications
+ * but block automatic install.
+ */
+export function shouldSkipAutoInstall(env) {
+    return env.WP_SKIP_AUTO_INSTALL === '1';
+}
+function hasInformationalFlag(argv) {
+    // Skip argv[0] (runtime) and argv[1] (script path). Inspect the rest.
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg !== undefined && INFORMATIONAL_FLAGS.has(arg))
+            return true;
+    }
+    return false;
+}
+function isCiEnvironment(env) {
+    // Match the convention used by `is-ci` / `ci-info`: `CI` set to any
+    // truthy-looking value counts. Some CI vendors set `CI=1` rather than
+    // `CI=true`, so don't anchor on a specific value.
+    if (env.CI !== undefined && env.CI !== '' && env.CI !== 'false' && env.CI !== '0')
+        return true;
+    for (const key of CI_ENV_KEYS) {
+        if (key === 'CI')
+            continue;
+        const value = env[key];
+        if (value !== undefined && value !== '' && value !== 'false' && value !== '0')
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=skip.js.map

package/dist/esm/cli/bootstrap.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pre-flight hook for the CLI.
+ *
+ * Ordered bootstrap per D6 + D8 + D19:
+ *   1. Short-circuit on informational verbs (--version / --help / -v / -h)
+ *      so those always work outside a git repo.
+ *   2. Hard-fail outside a git repo — propagates NotInGitRepoError to cli.ts
+ *      for formatted error output + exit 2.
+ *   3. Skip auto-update when env/argv say so (CI, mcp, WP_SKIP_UPDATE_CHECK).
+ *   4. Fire-and-forget runUpdateFlow — errors sink to logUpdateError (D13).
+ */
+import { NotInGitRepoError } from '#paths/state-root.js';
+export { NotInGitRepoError };
+/**
+ * Returns true when argv contains an informational flag anywhere after the
+ * first two entries (runtime + script path).
+ */
+export declare function isInformationalVerb(argv: string[]): boolean;
+/**
+ * Run CLI bootstrap. Throws NotInGitRepoError if not inside a git repo
+ * (except for informational verbs). Fire-and-forget auto-update check.
+ *
+ * @param version  Package version string (e.g. "0.16.0") — passed from cli.ts
+ *                 so the caller owns the version read, not bootstrap.
+ * @param argv     Normalized process.argv (defaults to process.argv).
+ */
+export declare function bootstrapAk(version: string, argv?: string[]): Promise<void>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/esm/cli/bootstrap.js

@@ -0,0 +1,55 @@
+/**
+ * Pre-flight hook for the CLI.
+ *
+ * Ordered bootstrap per D6 + D8 + D19:
+ *   1. Short-circuit on informational verbs (--version / --help / -v / -h)
+ *      so those always work outside a git repo.
+ *   2. Hard-fail outside a git repo — propagates NotInGitRepoError to cli.ts
+ *      for formatted error output + exit 2.
+ *   3. Skip auto-update when env/argv say so (CI, mcp, WP_SKIP_UPDATE_CHECK).
+ *   4. Fire-and-forget runUpdateFlow — errors sink to logUpdateError (D13).
+ */
+import { NotInGitRepoError, getRepoKey } from '#paths/state-root.js';
+import { logUpdateError } from '#cli/auto-update/log.js';
+import { shouldSkipUpdateCheck } from '#cli/auto-update/skip.js';
+import { runUpdateFlow } from '#cli/auto-update/run.js';
+export { NotInGitRepoError };
+const INFORMATIONAL_FLAGS = new Set(['--version', '-v', '--help', '-h']);
+/**
+ * Returns true when argv contains an informational flag anywhere after the
+ * first two entries (runtime + script path).
+ */
+export function isInformationalVerb(argv) {
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg !== undefined && INFORMATIONAL_FLAGS.has(arg))
+            return true;
+    }
+    return false;
+}
+/**
+ * Run CLI bootstrap. Throws NotInGitRepoError if not inside a git repo
+ * (except for informational verbs). Fire-and-forget auto-update check.
+ *
+ * @param version  Package version string (e.g. "0.16.0") — passed from cli.ts
+ *                 so the caller owns the version read, not bootstrap.
+ * @param argv     Normalized process.argv (defaults to process.argv).
+ */
+export async function bootstrapAk(version, argv = process.argv) {
+    // D19 — informational verbs short-circuit before any git repo check.
+    if (isInformationalVerb(argv))
+        return;
+    // D6 — hard-fail outside git repo. NotInGitRepoError propagates to cli.ts.
+    getRepoKey(); // throws NotInGitRepoError if not in git; return value not needed here
+    // D8 — skip update check when in CI, mcp mode, or explicitly opted out.
+    if (shouldSkipUpdateCheck(process.env, argv))
+        return;
+    // D13 — awaited so cache write + deferred install spawn complete before exit.
+    try {
+        await runUpdateFlow(version);
+    }
+    catch (err) {
+        logUpdateError(err);
+    }
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/esm/cli/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+/**
+ * `wp` — webpresso CLI entrypoint.
+ *
+ * Lazy-loads subcommand modules based on the first argv to keep startup
+ * cheap. Modeled on apps/cli-wp/src/cli.ts.
+ */
+declare const SUPPORTED_COMMANDS: readonly ["blueprint", "config", "roadmap", "sync", "audit", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "doctor", "err", "test", "e2e", "ci", "typecheck", "lint", "format", "tech-debt", "worktree", "mcp", "hooks", "gain", "bench"];
+export { SUPPORTED_COMMANDS };
+export declare function main(): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map