opensip-cli 0.1.0

package/dist/update-notifier.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Thin wrapper around `update-notifier` that checks npm
+ * hourly for a newer version of opensip-cli (see UPDATE_CHECK_INTERVAL_MS).
+ *
+ * `update-notifier` is used purely as the *fetcher* — it runs the throttled
+ * (hourly), detached, non-blocking network check. It is NOT used as the
+ * display source, because its `check()` deletes the cached result the instant
+ * it's read, which would make the notice show at most once per fetch cycle.
+ * Instead the newest known version is mirrored into a sticky store
+ * (`update-state.ts`) that {@link checkForUpdate} consults on EVERY run, so
+ * the notice persists until the running version catches up. See
+ * `update-state.ts` for the rationale in full.
+ *
+ * Two consumers, one resolved result:
+ *   - {@link checkForUpdate} returns the newer version string (if any) so
+ *     the `mini` banner can surface it inline as `(<new-version> available)`.
+ *   - {@link formatUpdateNag} builds the stderr one-liner shown for the
+ *     other banner sizes (which have no version line to annotate).
+ * The bootstrap calls `checkForUpdate` once and decides which surface to use.
+ *
+ * Design goals:
+ *   - Silent by default when there's nothing to report.
+ *   - Persistent while a genuinely newer release exists; self-clearing the
+ *     run after the user upgrades.
+ *   - Opt-out via OPENSIP_NO_UPDATE (and honours the upstream
+ *     NO_UPDATE_NOTIFIER flag for convention).
+ *   - Non-blocking: the check runs in a child process; the current
+ *     command never waits on network I/O.
+ *
+ * Suppressed when:
+ *   - Env var OPENSIP_NO_UPDATE=1 (our flag)
+ *   - Env var NO_UPDATE_NOTIFIER=1 (convention for the npm package)
+ *   - Env var CI set (update-notifier suppresses by default)
+ *   - stdout is not a TTY (scripts, pipelines)
+ */
+import { type UpdateNotifier } from 'update-notifier';
+/**
+ * How often the detached background fetch may hit npm to learn the latest
+ * published version. `update-notifier` throttles its network check to this
+ * interval; the sticky store (`update-state.ts`) then drives *display* on
+ * every run. This is therefore the worst-case DETECTION latency: a freshly
+ * published release becomes visible within one interval of going live (on the
+ * run after the next fetch completes — the fetch is detached, so never the
+ * same run).
+ *
+ * Set to 1 hour rather than the conventional 24h: the fetch is non-blocking,
+ * so a shorter interval costs the user nothing at the command line and only a
+ * modest amount of extra npm traffic (≤1 request/hour/user), while shrinking
+ * the "I published but the CLI still says up-to-date" window from a day to an
+ * hour. One named constant so the two call sites can't drift.
+ */
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+export interface NotifyOptions {
+    readonly name: string;
+    readonly version: string;
+    /** Override stderr writer (for tests). */
+    readonly write?: (s: string) => void;
+}
+export interface CheckForUpdateOptions {
+    readonly name: string;
+    readonly version: string;
+    /**
+     * Override the sticky update-state file path (for tests). Defaults to
+     * `~/.opensip-cli/update-state.json`.
+     */
+    readonly stateFile?: string;
+}
+/**
+ * Strict semver "is `latest` newer than `current`". Compares the numeric
+ * MAJOR.MINOR.PATCH core; with equal cores a prerelease (`1.0.0-beta`) is
+ * treated as OLDER than its release (`1.0.0`), per semver.
+ *
+ * This is the guard the nag relies on: the previous `latest !== current`
+ * check fired on ANY difference, so running a build AHEAD of npm's `latest`
+ * (a local dev build, or a prerelease) wrongly prompted a "downgrade". We
+ * only notify when there is a genuinely newer release to move TO.
+ */
+export declare function isNewerVersion(latest: string, current: string): boolean;
+/**
+ * Resolve whether a newer published version is available, scheduling the
+ * hourly background fetch as a side effect. Returns the newer version
+ * string (e.g. `1.0.1`) when one is known, or `undefined` when up-to-date,
+ * opted-out, or non-TTY.
+ *
+ * Unlike `update-notifier`'s own delete-on-read result, this is **sticky**:
+ * the newest version the hourly check observes is mirrored into a small store
+ * (`update-state.ts`) that is read on EVERY run, so the notice persists until
+ * the running version catches up — at which point the store is cleared and
+ * the notice stops on its own.
+ *
+ * Never throws: a malformed cache or notifier failure degrades to "no update
+ * known" rather than breaking the command. Callers decide how to surface it
+ * (the `mini` banner inline, or {@link formatUpdateNag} on stderr).
+ */
+export declare function checkForUpdate(opts: CheckForUpdateOptions): string | undefined;
+/**
+ * Build the stderr update-nag line for the non-`mini` banner sizes (which
+ * have no version line to annotate inline) and the banner-less `--json` path.
+ * The `mini` banner surfaces the same information in-box, so the bootstrap
+ * skips this for `mini`.
+ */
+export declare function formatUpdateNag(current: string, latest: string): string;
+/**
+ * Run the update check. Returns the notifier instance (so tests can
+ * assert) or null if skipped.
+ */
+export declare function maybeNotify(opts: NotifyOptions): UpdateNotifier | null;
+//# sourceMappingURL=update-notifier.d.ts.map

package/dist/update-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-notifier.d.ts","sourceRoot":"","sources":["../src/update-notifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAuB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAKtE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AASD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAWvE;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,GAAG,SAAS,CAgC9E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,cAAc,GAAG,IAAI,CAwBtE"}

package/dist/update-notifier.js

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Thin wrapper around `update-notifier` that checks npm
+ * hourly for a newer version of opensip-cli (see UPDATE_CHECK_INTERVAL_MS).
+ *
+ * `update-notifier` is used purely as the *fetcher* — it runs the throttled
+ * (hourly), detached, non-blocking network check. It is NOT used as the
+ * display source, because its `check()` deletes the cached result the instant
+ * it's read, which would make the notice show at most once per fetch cycle.
+ * Instead the newest known version is mirrored into a sticky store
+ * (`update-state.ts`) that {@link checkForUpdate} consults on EVERY run, so
+ * the notice persists until the running version catches up. See
+ * `update-state.ts` for the rationale in full.
+ *
+ * Two consumers, one resolved result:
+ *   - {@link checkForUpdate} returns the newer version string (if any) so
+ *     the `mini` banner can surface it inline as `(<new-version> available)`.
+ *   - {@link formatUpdateNag} builds the stderr one-liner shown for the
+ *     other banner sizes (which have no version line to annotate).
+ * The bootstrap calls `checkForUpdate` once and decides which surface to use.
+ *
+ * Design goals:
+ *   - Silent by default when there's nothing to report.
+ *   - Persistent while a genuinely newer release exists; self-clearing the
+ *     run after the user upgrades.
+ *   - Opt-out via OPENSIP_NO_UPDATE (and honours the upstream
+ *     NO_UPDATE_NOTIFIER flag for convention).
+ *   - Non-blocking: the check runs in a child process; the current
+ *     command never waits on network I/O.
+ *
+ * Suppressed when:
+ *   - Env var OPENSIP_NO_UPDATE=1 (our flag)
+ *   - Env var NO_UPDATE_NOTIFIER=1 (convention for the npm package)
+ *   - Env var CI set (update-notifier suppresses by default)
+ *   - stdout is not a TTY (scripts, pipelines)
+ */
+import updateNotifier from 'update-notifier';
+import { hostEnv } from './env/host-env-specs.js';
+import { clearKnownLatest, readKnownLatest, writeKnownLatest } from './update-state.js';
+/**
+ * How often the detached background fetch may hit npm to learn the latest
+ * published version. `update-notifier` throttles its network check to this
+ * interval; the sticky store (`update-state.ts`) then drives *display* on
+ * every run. This is therefore the worst-case DETECTION latency: a freshly
+ * published release becomes visible within one interval of going live (on the
+ * run after the next fetch completes — the fetch is detached, so never the
+ * same run).
+ *
+ * Set to 1 hour rather than the conventional 24h: the fetch is non-blocking,
+ * so a shorter interval costs the user nothing at the command line and only a
+ * modest amount of extra npm traffic (≤1 request/hour/user), while shrinking
+ * the "I published but the CLI still says up-to-date" window from a day to an
+ * hour. One named constant so the two call sites can't drift.
+ */
+export const UPDATE_CHECK_INTERVAL_MS = 1000 * 60 * 60;
+/** Split `1.0.0-beta.1` into `([1,0,0], 'beta.1')`; missing parts → 0 / ''. */
+function splitPrerelease(version) {
+    const [core, ...rest] = version.split('-');
+    const nums = core.split('.').map((p) => Number.parseInt(p, 10) || 0);
+    return [nums, rest.join('-')];
+}
+/**
+ * Strict semver "is `latest` newer than `current`". Compares the numeric
+ * MAJOR.MINOR.PATCH core; with equal cores a prerelease (`1.0.0-beta`) is
+ * treated as OLDER than its release (`1.0.0`), per semver.
+ *
+ * This is the guard the nag relies on: the previous `latest !== current`
+ * check fired on ANY difference, so running a build AHEAD of npm's `latest`
+ * (a local dev build, or a prerelease) wrongly prompted a "downgrade". We
+ * only notify when there is a genuinely newer release to move TO.
+ */
+export function isNewerVersion(latest, current) {
+    const [latestCore, latestPre] = splitPrerelease(latest);
+    const [currentCore, currentPre] = splitPrerelease(current);
+    for (let i = 0; i < 3; i++) {
+        const l = latestCore[i] ?? 0;
+        const c = currentCore[i] ?? 0;
+        if (l > c)
+            return true;
+        if (l < c)
+            return false;
+    }
+    // Cores equal: a full release is newer than a prerelease of the same core.
+    return latestPre === '' && currentPre !== '';
+}
+function shouldSkip() {
+    // Either opt-out (read through the registry) skips the check — byte-identical
+    // to the prior two independent truthy `process.env` checks.
+    if (hostEnv.get('OPENSIP_NO_UPDATE') === true)
+        return true;
+    if (hostEnv.get('NO_UPDATE_NOTIFIER') === true)
+        return true;
+    // The update-notifier package already suppresses in CI and non-TTY,
+    // but we short-circuit so we don't even construct the notifier —
+    // keeps the startup path minimal.
+    // eslint-disable-next-line no-restricted-properties -- a `.isTTY` capability READ (terminal detection), not run output; the seam rule targets stdout writes, not TTY probing.
+    if (!process.stdout.isTTY)
+        return true;
+    return false;
+}
+/**
+ * Resolve whether a newer published version is available, scheduling the
+ * hourly background fetch as a side effect. Returns the newer version
+ * string (e.g. `1.0.1`) when one is known, or `undefined` when up-to-date,
+ * opted-out, or non-TTY.
+ *
+ * Unlike `update-notifier`'s own delete-on-read result, this is **sticky**:
+ * the newest version the hourly check observes is mirrored into a small store
+ * (`update-state.ts`) that is read on EVERY run, so the notice persists until
+ * the running version catches up — at which point the store is cleared and
+ * the notice stops on its own.
+ *
+ * Never throws: a malformed cache or notifier failure degrades to "no update
+ * known" rather than breaking the command. Callers decide how to surface it
+ * (the `mini` banner inline, or {@link formatUpdateNag} on stderr).
+ */
+export function checkForUpdate(opts) {
+    if (shouldSkip())
+        return undefined;
+    try {
+        // Fetcher: schedules the throttled, detached hourly network check. On the
+        // run right after that check completes, `notifier.update` is populated
+        // (then update-notifier deletes it from its own cache — hence the mirror).
+        const notifier = updateNotifier({
+            pkg: { name: opts.name, version: opts.version },
+            updateCheckInterval: UPDATE_CHECK_INTERVAL_MS,
+            shouldNotifyInNpmScript: false,
+        });
+        const fresh = notifier.update;
+        if (fresh && isNewerVersion(fresh.latest, fresh.current)) {
+            writeKnownLatest(fresh.latest, opts.stateFile);
+        }
+        // @fitness-ignore-next-line error-handling-quality -- the update fetch is best-effort cosmetic: any failure (corrupt cache, network helper error) must degrade silently, never break the user's command. The sticky store below still drives display from whatever was last known.
+    }
+    catch {
+        // Intentionally swallow — see the directive above. Display falls through
+        // to readKnownLatest, so a failed fetch just shows the last known state.
+    }
+    // Display: driven entirely by the sticky store so the notice persists across
+    // runs. Clear it once the running version has caught up so it self-stops
+    // after an upgrade.
+    const known = readKnownLatest(opts.stateFile);
+    if (known && isNewerVersion(known, opts.version)) {
+        return known;
+    }
+    if (known) {
+        clearKnownLatest(opts.stateFile);
+    }
+    return undefined;
+}
+/**
+ * Build the stderr update-nag line for the non-`mini` banner sizes (which
+ * have no version line to annotate inline) and the banner-less `--json` path.
+ * The `mini` banner surfaces the same information in-box, so the bootstrap
+ * skips this for `mini`.
+ */
+export function formatUpdateNag(current, latest) {
+    return (`\nOpenSIP CLI ${current} -> ${latest} available. ` +
+        `Run \`curl -fsSL https://opensip.ai/cli/install.sh | bash\` to update.\n` +
+        `(Silence with OPENSIP_NO_UPDATE=1.)\n\n`);
+}
+/**
+ * Run the update check. Returns the notifier instance (so tests can
+ * assert) or null if skipped.
+ */
+export function maybeNotify(opts) {
+    if (shouldSkip())
+        return null;
+    const notifier = updateNotifier({
+        pkg: { name: opts.name, version: opts.version },
+        // Hourly (UPDATE_CHECK_INTERVAL_MS) — the detached fetch never blocks the
+        // command, so we trade a little npm traffic for sub-hourly detection.
+        updateCheckInterval: UPDATE_CHECK_INTERVAL_MS,
+        shouldNotifyInNpmScript: false,
+    });
+    const update = notifier.update;
+    // Only nag when npm's latest is genuinely NEWER than what's running — not
+    // merely different. Guards against the "1.0.1 → 1.0.0 available" downgrade
+    // prompt seen when running a build ahead of the published `latest` tag.
+    if (update && isNewerVersion(update.latest, update.current)) {
+        const write = opts.write ?? ((s) => process.stderr.write(s));
+        const line = `\nOpenSIP CLI ${update.current} -> ${update.latest} available. ` +
+            `Run \`curl -fsSL https://opensip.ai/cli/install.sh | bash\` to update.\n` +
+            `(Silence with OPENSIP_NO_UPDATE=1.)\n\n`;
+        write(line);
+    }
+    return notifier;
+}
+//# sourceMappingURL=update-notifier.js.map

package/dist/update-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-notifier.js","sourceRoot":"","sources":["../src/update-notifier.ts"],"names":[],"mappings":"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"}

package/dist/update-state.d.ts

@@ -0,0 +1,40 @@
+/**
+ * update-state — sticky persistence for the "update available" notice.
+ *
+ * `update-notifier` is a good *fetcher* (throttled — hourly here — detached
+ * background network check) but a poor *display* source: its `check()`
+ * deletes the cached result the instant it's read, so the notice would show
+ * at most once per fetch cycle. A user who blinks past one `fit` run would
+ * never see it again until the next hourly check repopulated the cache.
+ *
+ * This module owns the display state instead. The update notifier mirrors the
+ * newest known published version here; {@link readKnownLatest} is consulted on
+ * EVERY run so the notice persists, and {@link clearKnownLatest} wipes it the
+ * moment the running version catches up — so it stops on its own after an
+ * upgrade, with no stale "update available" lingering.
+ *
+ * The store is a tiny JSON file at `~/.opensip-cli/update-state.json`
+ * (see {@link resolveUserPaths}), kept separate from the user-authored
+ * `config.yml`. Reads and writes are best-effort: any failure degrades to
+ * "nothing known" rather than breaking the command.
+ */
+/** Default store path: `~/.opensip-cli/update-state.json`. */
+export declare function defaultUpdateStateFile(): string;
+/**
+ * Read the last-known newer published version, or `undefined` when nothing is
+ * cached / the file is absent or unreadable. Never throws.
+ */
+export declare function readKnownLatest(file?: string): string | undefined;
+/**
+ * Persist the newest known published version so the notice survives across
+ * runs. No-ops on any I/O failure. Skips the write when the value is unchanged
+ * to avoid needless disk churn on every invocation.
+ */
+export declare function writeKnownLatest(latest: string, file?: string): void;
+/**
+ * Clear the cached version — called once the running version catches up, so
+ * the notice stops on its own after an upgrade. No-ops when already absent or
+ * on any I/O failure.
+ */
+export declare function clearKnownLatest(file?: string): void;
+//# sourceMappingURL=update-state.d.ts.map

package/dist/update-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-state.d.ts","sourceRoot":"","sources":["../src/update-state.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAaH,8DAA8D;AAC9D,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,MAAiC,GAAG,MAAM,GAAG,SAAS,CAU3F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAAiC,GAAG,IAAI,CAS9F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAAiC,GAAG,IAAI,CAS9E"}

package/dist/update-state.js

@@ -0,0 +1,81 @@
+// @fitness-ignore-file error-handling-quality -- every function here is best-effort cosmetic state for the "update available" notice: any failure (missing dir, malformed JSON, EACCES) must degrade silently to "nothing known" and never break the user's command. Absence and corruption are deliberately equivalent to "no update known".
+// @fitness-ignore-file unbounded-memory -- reads ~/.opensip-cli/update-state.json, a tiny tool-generated cache holding a single version string.
+/**
+ * update-state — sticky persistence for the "update available" notice.
+ *
+ * `update-notifier` is a good *fetcher* (throttled — hourly here — detached
+ * background network check) but a poor *display* source: its `check()`
+ * deletes the cached result the instant it's read, so the notice would show
+ * at most once per fetch cycle. A user who blinks past one `fit` run would
+ * never see it again until the next hourly check repopulated the cache.
+ *
+ * This module owns the display state instead. The update notifier mirrors the
+ * newest known published version here; {@link readKnownLatest} is consulted on
+ * EVERY run so the notice persists, and {@link clearKnownLatest} wipes it the
+ * moment the running version catches up — so it stops on its own after an
+ * upgrade, with no stale "update available" lingering.
+ *
+ * The store is a tiny JSON file at `~/.opensip-cli/update-state.json`
+ * (see {@link resolveUserPaths}), kept separate from the user-authored
+ * `config.yml`. Reads and writes are best-effort: any failure degrades to
+ * "nothing known" rather than breaking the command.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { resolveUserPaths } from '@opensip-cli/core';
+/** Default store path: `~/.opensip-cli/update-state.json`. */
+export function defaultUpdateStateFile() {
+    return resolveUserPaths().updateStateFile;
+}
+/**
+ * Read the last-known newer published version, or `undefined` when nothing is
+ * cached / the file is absent or unreadable. Never throws.
+ */
+export function readKnownLatest(file = defaultUpdateStateFile()) {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof parsed.latest === 'string' && parsed.latest.length > 0
+            ? parsed.latest
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Persist the newest known published version so the notice survives across
+ * runs. No-ops on any I/O failure. Skips the write when the value is unchanged
+ * to avoid needless disk churn on every invocation.
+ */
+export function writeKnownLatest(latest, file = defaultUpdateStateFile()) {
+    if (readKnownLatest(file) === latest)
+        return;
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${JSON.stringify({ latest }, null, 2)}\n`, 'utf8');
+    }
+    catch {
+        // Best-effort: a missing cache just means the notice falls back to
+        // update-notifier's once-per-cycle behaviour. Never break the command.
+    }
+}
+/**
+ * Clear the cached version — called once the running version catches up, so
+ * the notice stops on its own after an upgrade. No-ops when already absent or
+ * on any I/O failure.
+ */
+export function clearKnownLatest(file = defaultUpdateStateFile()) {
+    if (!existsSync(file))
+        return;
+    try {
+        // Overwrite rather than unlink: keeps the file (and its dir perms) stable,
+        // and an empty `{}` reads back as "nothing known" via readKnownLatest.
+        writeFileSync(file, '{}\n', 'utf8');
+    }
+    catch {
+        // Ignore — a stale file at worst re-shows a notice that clears next run.
+    }
+}
+//# sourceMappingURL=update-state.js.map

package/dist/update-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-state.js","sourceRoot":"","sources":["../src/update-state.ts"],"names":[],"mappings":"AAAA,8UAA8U;AAC9U,gJAAgJ;AAChJ;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAQrD,8DAA8D;AAC9D,MAAM,UAAU,sBAAsB;IACpC,OAAO,gBAAgB,EAAE,CAAC,eAAe,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,sBAAsB,EAAE;IACrE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAyB,CAAC;QAC9E,OAAO,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YAClE,CAAC,CAAC,MAAM,CAAC,MAAM;YACf,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe,sBAAsB,EAAE;IACtF,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,MAAM;QAAE,OAAO;IAC7C,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAwB,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChG,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,uEAAuE;IACzE,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,sBAAsB,EAAE;IACtE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,IAAI,CAAC;QACH,2EAA2E;QAC3E,uEAAuE;QACvE,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;AACH,CAAC"}

package/dist/welcome.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Welcome message printed when `opensip` is invoked
+ * with no subcommand and no flags.
+ *
+ * Design goal: a new user typing `opensip` sees the two primary
+ * subcommands (fit / sim), a minimal quickstart, and a pointer at
+ * `--help` for everything else. Progressive disclosure: the tool
+ * decides what to show first rather than dumping the full help dump
+ * produced by commander.
+ *
+ * Called only when `process.argv.length <= 2`. When the user passes
+ * `--help` or `--version`, commander owns the output and this is
+ * never invoked.
+ *
+ * Theme bypass — load-bearing
+ * ---------------------------
+ * This module emits raw ANSI escape sequences directly to
+ * `process.stdout` rather than routing through Ink and `theme.ts`. The
+ * bypass is INTENTIONAL and is the F6 promise's documented exception:
+ *
+ *   - The welcome screen is the very first thing a zero-arg invocation
+ *     does. Loading Ink/React (~50 ms cold-start on a typical machine)
+ *     to print twelve lines of static help would be a regression on
+ *     `opensip` (no args) → welcome.
+ *   - The render is fully static — no progress, no live updates, no
+ *     theme-driven palette decisions. The only colour roles in use are
+ *     bold, dim, and a single accent — all NO_COLOR / FORCE_COLOR
+ *     aware via `colorsEnabled()`.
+ *   - Theme drift risk is bounded: if a user customises `theme.ts`,
+ *     they will see their accent everywhere EXCEPT the welcome
+ *     screen. Acceptable — they typed nothing, so the screen is a
+ *     handshake, not user-facing output. Audit 2026-05-23 G4 picked
+ *     this option (b: tolerate the bypass, document it).
+ *
+ * If welcome ever grows dynamic content (recipe suggestions, recent-run
+ * peek, etc.) it should move to an Ink renderer + a `WelcomeResult`;
+ * delete this header at the same time.
+ */
+export interface WelcomeOptions {
+    readonly version: string;
+    readonly write?: (s: string) => void;
+}
+/**
+ * Render the welcome message as a single string. Exported for testing.
+ */
+export declare function buildWelcome(opts: WelcomeOptions): string;
+/**
+ * Write the welcome message to stdout. Separate from `buildWelcome`
+ * so tests can assert on the rendered string without capturing
+ * process.stdout.
+ */
+export declare function printWelcome(opts: WelcomeOptions): void;
+//# sourceMappingURL=welcome.d.ts.map

package/dist/welcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome.d.ts","sourceRoot":"","sources":["../src/welcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAkBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAuBzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAGvD"}

package/dist/welcome.js

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Welcome message printed when `opensip` is invoked
+ * with no subcommand and no flags.
+ *
+ * Design goal: a new user typing `opensip` sees the two primary
+ * subcommands (fit / sim), a minimal quickstart, and a pointer at
+ * `--help` for everything else. Progressive disclosure: the tool
+ * decides what to show first rather than dumping the full help dump
+ * produced by commander.
+ *
+ * Called only when `process.argv.length <= 2`. When the user passes
+ * `--help` or `--version`, commander owns the output and this is
+ * never invoked.
+ *
+ * Theme bypass — load-bearing
+ * ---------------------------
+ * This module emits raw ANSI escape sequences directly to
+ * `process.stdout` rather than routing through Ink and `theme.ts`. The
+ * bypass is INTENTIONAL and is the F6 promise's documented exception:
+ *
+ *   - The welcome screen is the very first thing a zero-arg invocation
+ *     does. Loading Ink/React (~50 ms cold-start on a typical machine)
+ *     to print twelve lines of static help would be a regression on
+ *     `opensip` (no args) → welcome.
+ *   - The render is fully static — no progress, no live updates, no
+ *     theme-driven palette decisions. The only colour roles in use are
+ *     bold, dim, and a single accent — all NO_COLOR / FORCE_COLOR
+ *     aware via `colorsEnabled()`.
+ *   - Theme drift risk is bounded: if a user customises `theme.ts`,
+ *     they will see their accent everywhere EXCEPT the welcome
+ *     screen. Acceptable — they typed nothing, so the screen is a
+ *     handshake, not user-facing output. Audit 2026-05-23 G4 picked
+ *     this option (b: tolerate the bypass, document it).
+ *
+ * If welcome ever grows dynamic content (recipe suggestions, recent-run
+ * peek, etc.) it should move to an Ink renderer + a `WelcomeResult`;
+ * delete this header at the same time.
+ */
+const ANSI_BOLD = '\u001B[1m';
+const ANSI_DIM = '\u001B[2m';
+const ANSI_CYAN = '\u001B[36m';
+const ANSI_RESET = '\u001B[0m';
+/** True when stdout is a terminal and colors are safe to emit. */
+function colorsEnabled() {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return Boolean(process.stdout.isTTY);
+}
+function color(enabled, code, text) {
+    return enabled ? `${code}${text}${ANSI_RESET}` : text;
+}
+/**
+ * Render the welcome message as a single string. Exported for testing.
+ */
+export function buildWelcome(opts) {
+    const c = colorsEnabled();
+    const bold = (s) => color(c, ANSI_BOLD, s);
+    const dim = (s) => color(c, ANSI_DIM, s);
+    const accent = (s) => color(c, ANSI_CYAN, s);
+    return [
+        '',
+        `${bold('OpenSIP CLI')} ${dim(opts.version)} — codebase analysis toolkit`,
+        '',
+        `${bold('Primary commands:')}`,
+        `  ${accent('opensip fit')}        Run fitness checks against your codebase`,
+        `  ${accent('opensip sim')}        Run simulation scenarios`,
+        '',
+        `${bold('Getting started:')}`,
+        `  $ cd your-project`,
+        `  $ opensip init       ${dim('# create a targets config')}`,
+        `  $ opensip fit        ${dim('# run every registered check')}`,
+        '',
+        `${dim('Full reference: opensip --help')}`,
+        `${dim('Docs:           https://github.com/opensip-ai/opensip-cli')}`,
+        '',
+    ].join('\n');
+}
+/**
+ * Write the welcome message to stdout. Separate from `buildWelcome`
+ * so tests can assert on the rendered string without capturing
+ * process.stdout.
+ */
+export function printWelcome(opts) {
+    const write = opts.write ?? ((s) => process.stdout.write(s));
+    write(buildWelcome(opts));
+}
+//# sourceMappingURL=welcome.js.map

package/dist/welcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"welcome.js","sourceRoot":"","sources":["../src/welcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAOH,MAAM,SAAS,GAAG,WAAW,CAAC;AAC9B,MAAM,QAAQ,GAAG,WAAW,CAAC;AAC7B,MAAM,SAAS,GAAG,YAAY,CAAC;AAC/B,MAAM,UAAU,GAAG,WAAW,CAAC;AAE/B,kEAAkE;AAClE,SAAS,aAAa;IACpB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,KAAK,CAAC,OAAgB,EAAE,IAAY,EAAE,IAAY;IACzD,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAoB;IAC/C,MAAM,CAAC,GAAG,aAAa,EAAE,CAAC;IAC1B,MAAM,IAAI,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IAE7D,OAAO;QACL,EAAE;QACF,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,8BAA8B;QACzE,EAAE;QACF,GAAG,IAAI,CAAC,mBAAmB,CAAC,EAAE;QAC9B,KAAK,MAAM,CAAC,aAAa,CAAC,kDAAkD;QAC5E,KAAK,MAAM,CAAC,aAAa,CAAC,kCAAkC;QAC5D,EAAE;QACF,GAAG,IAAI,CAAC,kBAAkB,CAAC,EAAE;QAC7B,qBAAqB;QACrB,0BAA0B,GAAG,CAAC,2BAA2B,CAAC,EAAE;QAC5D,0BAA0B,GAAG,CAAC,8BAA8B,CAAC,EAAE;QAC/D,EAAE;QACF,GAAG,GAAG,CAAC,gCAAgC,CAAC,EAAE;QAC1C,GAAG,GAAG,CAAC,2DAA2D,CAAC,EAAE;QACrE,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAoB;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5B,CAAC"}