@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.87

package/dist/core/auto-update/channels.js

@@ -0,0 +1,122 @@
+/**
+ * — Auto-update channel model.
+ *
+ * the upstream tool's self-update flow exposes three release channels (stable
+ * / beta / canary) so operators can dial in their own risk tolerance:
+ * a finance-team operator pins `stable`, a tinkerer rides `canary`,
+ * and the default `beta` track sits in the middle. Pugi parity ships
+ * the same vocabulary on top of npm's dist-tags so we do NOT need a
+ * custom registry hop:
+ *
+ *  - `stable`  → npm dist-tag `latest`
+ *  - `beta`    → npm dist-tag `beta`
+ *  - `canary`  → npm dist-tag `next`
+ *
+ * The mapping is centralised here because the dispatcher + the probe
+ * + the slash command + the doctor probe all need to agree on which
+ * tag they query. The channel name is what shows up in operator UI
+ * (`pugi update --channel beta`); the npm tag is the wire-format that
+ * gets concatenated into `npm i -g @pugi/cli@<tag>`.
+ *
+ * Module contract:
+ *
+ *  - Pure constants + a small parse helper. No I/O, no module-level
+ *    side effects. The persistence layer (`state.ts`) and the probe
+ *    (`checker.ts`) wrap this module without ever mutating it.
+ *
+ *  - Default channel is `beta` because Pugi currently publishes ONLY
+ *    beta releases on npm. Defaulting to `stable` would leave fresh
+ *    installs polling a tag that does not exist yet, surfacing a
+ *    confusing "no update available" message even though the binary
+ *    they just installed is already behind. The default is revisited
+ *    when `latest` (stable) starts shipping; the constant lives on
+ *    a single line so the bump is a one-character diff.
+ *
+ *  - All channel <-> tag conversions go through `npmTagForChannel` /
+ *    `channelForNpmTag`. Hard-coding the string `'beta'` anywhere
+ *    else is a bug.
+ */
+/**
+ * Immutable list of every supported channel. Drives the `--channel`
+ * flag validator + the `/update --channel <name>` slash parser +
+ * any future Ink picker that wants to render the full set.
+ */
+export const UPDATE_CHANNELS = Object.freeze([
+    'stable',
+    'beta',
+    'canary',
+]);
+/**
+ * Default channel when neither `~/.pugi/config.json::updateChannel`
+ * nor a CLI flag specifies one. See module header for rationale.
+ */
+export const DEFAULT_UPDATE_CHANNEL = 'beta';
+/**
+ * npm dist-tag → channel mapping. Centralised so a future channel
+ * rename (e.g. dropping `next` in favour of `canary` as the npm tag)
+ * is a single-line change. The reverse-lookup helpers below derive
+ * from this map so the two surfaces never drift.
+ */
+const CHANNEL_TO_NPM_TAG = Object.freeze({
+    stable: 'latest',
+    beta: 'beta',
+    canary: 'next',
+});
+/**
+ * Map a Pugi channel name to the npm dist-tag the registry exposes.
+ * Used to build both the registry query URL and the
+ * `npm i -g @pugi/cli@<tag>` install command surfaced to the operator.
+ */
+export function npmTagForChannel(channel) {
+    return CHANNEL_TO_NPM_TAG[channel];
+}
+/**
+ * Reverse lookup: given an npm dist-tag, return the matching Pugi
+ * channel name. Returns `null` for any tag we do not officially
+ * support; the caller layers in its own fallback (typically
+ * `DEFAULT_UPDATE_CHANNEL`) so a one-off dist-tag never crashes the
+ * channel picker.
+ */
+export function channelForNpmTag(tag) {
+    for (const channel of UPDATE_CHANNELS) {
+        if (CHANNEL_TO_NPM_TAG[channel] === tag)
+            return channel;
+    }
+    return null;
+}
+/**
+ * Type guard / parser for an unknown string. Trims + lowercases the
+ * input so `--channel BETA` and `--channel beta ` both work. Returns
+ * `null` for unknown channel names; the caller decides whether to
+ * fall back, error out, or prompt the operator.
+ */
+export function parseUpdateChannel(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const normalised = raw.trim().toLowerCase();
+    if (normalised.length === 0)
+        return null;
+    for (const channel of UPDATE_CHANNELS) {
+        if (channel === normalised)
+            return channel;
+    }
+    return null;
+}
+/**
+ * Pretty operator-readable description of a channel. Surfaced in the
+ * `pugi update --check` JSON envelope + the interactive picker so the
+ * operator sees what they are switching into. Keeps the copy single-
+ * sourced because the same line lands in the doctor table, the
+ * `--check` JSON, and the slash-command response.
+ */
+export function describeChannel(channel) {
+    switch (channel) {
+        case 'stable':
+            return 'stable (npm latest — finance / prod operators)';
+        case 'beta':
+            return 'beta (npm beta — current Pugi default)';
+        case 'canary':
+            return 'canary (npm next — tinkerers, early adopters)';
+    }
+}
+//# sourceMappingURL=channels.js.map

package/dist/core/auto-update/checker.js

@@ -0,0 +1,241 @@
+/**
+ * — Channel-aware npm registry probe.
+ *
+ * Polls `https://registry.npmjs.org/@pugi/cli` and reads the
+ * `dist-tags` object — npm publishes one entry per dist-tag (`latest`,
+ * `beta`, `next`) mapped to the highest semver under that tag. The
+ * channel resolver in `channels.ts` translates Pugi's user-visible
+ * channel name (`stable` / `beta` / `canary`) into the matching tag
+ * before we read it off the response.
+ *
+ * Why this lives next to (rather than INSIDE) the existing
+ * `runtime/update-check.ts`:
+ *
+ *  - `update-check.ts` already poll `/@pugi/cli/latest`. That endpoint
+ *    ONLY surfaces the `latest` dist-tag — channel selection requires
+ *    the full package document `/@pugi/cli` so we can pluck any of
+ *    the three tags. Two endpoints, two probes.
+ *
+ *  - The legacy banner (REPL cold start) keeps polling `latest` and
+ *    does NOT need to know about channels yet — it is a single-track
+ *    cosmetic hint. Splitting into two modules means we can ship L27
+ *    without churning the existing banner cache shape.
+ *
+ *  - A future sprint may unify the two probes once the channel
+ *    selection percolates into the REPL banner. For now the modules
+ *    coexist with a clear boundary: this file owns the `pugi update`
+ *    surface, `runtime/update-check.ts` owns the REPL cold-start
+ *    cosmetic banner.
+ *
+ * Module contract:
+ *
+ *  - The probe is pure with respect to disk + clock — every IO/clock
+ *    dependency is injected. The same module is used both at the CLI
+ *    entry point (real `fetch` + real `Date.now`) and in tests
+ *    (mock fetch + frozen clock) without a single environment shim.
+ *
+ *  - Failures NEVER throw. A 5xx, a network error, a JSON parse
+ *    failure, or an unknown channel/tag all collapse to a structured
+ *    `{ available: false, error: <reason> }` envelope. The caller
+ *    decides whether to surface the error to the operator (the
+ *    `pugi update --check` JSON surface) or swallow it (the cold-
+ *    start banner).
+ *
+ *  - The probe DOES NOT touch persistence. Writing the
+ *    `~/.pugi/.last-update-check` timestamp is the caller's
+ *    responsibility (the dispatcher in `runtime/commands/update.ts`)
+ *    so a smoke-test sweep that probes the registry 50 times in a
+ *    row does not accidentally write 50 timestamps.
+ */
+import { npmTagForChannel, } from './channels.js';
+import { compareVersions } from '../../runtime/update-check.js';
+/**
+ * Base registry URL — overridable per call so the spec can drive the
+ * full request lifecycle through undici's MockAgent.
+ */
+const PUGI_CLI_PACKAGE_URL = 'https://registry.npmjs.org/@pugi/cli';
+/**
+ * Hard cap on the registry round-trip. Mirrors the existing
+ * `runtime/update-check.ts::FETCH_TIMEOUT_MS` so both surfaces
+ * timeout-by-the-same-budget — operators never wait longer for `pugi
+ * update --check` than they would for the cold-start banner.
+ */
+const FETCH_TIMEOUT_MS = 3_000;
+/**
+ * Build the install command the operator copy-pastes (or `pugi update
+ * --apply` shells out to). Centralised so the dispatcher + the
+ * checker share a single source of truth on the literal string.
+ */
+export function buildInstallCommand(channel) {
+    return `npm install -g @pugi/cli@${npmTagForChannel(channel)}`;
+}
+/**
+ * Probe the npm registry for the latest version under `channel`. The
+ * dispatcher wraps this with persistence + confirmation prompts; this
+ * function is intentionally pure so the doctor probe + the cold-
+ * start banner can reuse it without dragging the dispatcher's I/O
+ * surface in.
+ */
+export async function checkForChannelUpdate(deps) {
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const registryUrl = deps.registryUrl ?? PUGI_CLI_PACKAGE_URL;
+    const timeoutMs = deps.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const tag = npmTagForChannel(deps.channel);
+    const installCommand = buildInstallCommand(deps.channel);
+    // A controller-driven timeout — the spec's MockAgent never trips it
+    // but the production path on a stuck registry must bail in 3s.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetchImpl(registryUrl, {
+            method: 'GET',
+            headers: { Accept: 'application/json' },
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        clearTimeout(timer);
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            channel: deps.channel,
+            npmTag: tag,
+            current: deps.currentVersion,
+            latest: null,
+            available: false,
+            gap: null,
+            installCommand,
+            error: `registry_unreachable: ${message}`,
+        };
+    }
+    clearTimeout(timer);
+    if (!response.ok) {
+        return {
+            channel: deps.channel,
+            npmTag: tag,
+            current: deps.currentVersion,
+            latest: null,
+            available: false,
+            gap: null,
+            installCommand,
+            error: `registry_status_${response.status}`,
+        };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            channel: deps.channel,
+            npmTag: tag,
+            current: deps.currentVersion,
+            latest: null,
+            available: false,
+            gap: null,
+            installCommand,
+            error: `registry_json_unparseable: ${message}`,
+        };
+    }
+    const distTags = extractDistTags(body);
+    if (!distTags) {
+        return {
+            channel: deps.channel,
+            npmTag: tag,
+            current: deps.currentVersion,
+            latest: null,
+            available: false,
+            gap: null,
+            installCommand,
+            error: 'registry_missing_dist_tags',
+        };
+    }
+    const latest = distTags[tag];
+    if (typeof latest !== 'string' || latest.length === 0) {
+        return {
+            channel: deps.channel,
+            npmTag: tag,
+            current: deps.currentVersion,
+            latest: null,
+            available: false,
+            gap: null,
+            installCommand,
+            error: `registry_missing_tag_${tag}`,
+        };
+    }
+    const cmp = compareVersions(deps.currentVersion, latest);
+    const available = cmp < 0;
+    const gap = classifyGap(deps.currentVersion, latest);
+    return {
+        channel: deps.channel,
+        npmTag: tag,
+        current: deps.currentVersion,
+        latest,
+        available,
+        gap,
+        installCommand,
+        error: null,
+    };
+}
+/**
+ * Extract the `dist-tags` object from a registry response. The npm
+ * package document is large (often >100kB); we only need this one
+ * key. Returns null when the field is missing or not a string-record
+ * — both indicate a registry response the probe should treat as
+ * unusable rather than panic on.
+ */
+function extractDistTags(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const obj = body;
+    const raw = obj['dist-tags'];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const result = {};
+    for (const [tag, value] of Object.entries(raw)) {
+        if (typeof value === 'string' && value.length > 0) {
+            result[tag] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Coarse semver gap classification used to colour the dispatcher's
+ * diff line. We do NOT roll our own semver parser — `compareVersions`
+ * (already in `runtime/update-check.ts`) is the canonical comparator;
+ * here we only need to bucket the diff into major / minor / patch /
+ * prerelease for UX hints.
+ *
+ * The classifier is intentionally tolerant: anything that does not
+ * parse as `X.Y.Z[-pre]` collapses to `prerelease` so we surface a
+ * conservative "investigate manually" hint instead of crashing.
+ */
+function classifyGap(current, latest) {
+    if (current === latest)
+        return 'same';
+    const a = parseCoarseSemver(current);
+    const b = parseCoarseSemver(latest);
+    if (!a || !b)
+        return 'prerelease';
+    if (b.major !== a.major)
+        return 'major';
+    if (b.minor !== a.minor)
+        return 'minor';
+    if (b.patch !== a.patch)
+        return 'patch';
+    return 'prerelease';
+}
+function parseCoarseSemver(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
+    if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) {
+        return null;
+    }
+    return { major, minor, patch };
+}
+//# sourceMappingURL=checker.js.map

package/dist/core/auto-update/state.js

@@ -0,0 +1,235 @@
+/**
+ * — Auto-update channel + last-check persistence.
+ *
+ * Two pieces of disk state are managed here:
+ *
+ *  1. **Channel selection** — `~/.pugi/config.json::updateChannel`.
+ *     Persisted across sessions so `pugi update` keeps polling the
+ *     same track the operator opted into via `pugi update --channel
+ *     <name>`. Mirrors the read/write pattern used by
+ *     `core/permissions/state.ts::getGlobalDefaultMode` (passthrough
+ *     schema, atomic tmp+rename, defensive parse).
+ *
+ *  2. **Last-check timestamp** — `~/.pugi/.last-update-check` (ISO
+ *     string, single-line). Read by the cold-start banner gate so
+ *     operators only see the "update available" hint once per
+ *     `UPDATE_CHECK_INTERVAL_HOURS` (default 24h). Living on its own
+ *     file (NOT a JSON object inside config.json) is intentional:
+ *     the timestamp is a hot path — every CLI invocation touches it —
+ *     and a single-line read+write is materially faster than the
+ *     JSON parse + serialise of the broader config doc, with no
+ *     schema coupling cost.
+ *
+ * Module contract:
+ *
+ *  - Every file path resolver accepts a `homeDir` override so the
+ *    test suite can drive the module through a per-test mkdtemp
+ *    directory without polluting the real `~/.pugi/`.
+ *
+ *  - Parse / read helpers NEVER throw on a malformed file. A
+ *    corrupted JSON blob, a missing field, or an unreadable file all
+ *    collapse to "no persisted value" so the next layer (the CLI
+ *    flag or the hard default `beta`) takes over. A future-self
+ *    debugging an update flow against a corrupt config never has the
+ *    CLI crash on them.
+ *
+ *  - Write helpers use the atomic tmp+rename idiom so a kill mid-
+ *    write never produces a half-flushed JSON document. The
+ *    timestamp file is small enough that POSIX `rename` is itself
+ *    atomic in practice, but we keep the idiom uniform with the
+ *    config write so reviewers do not have to context-switch.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve, dirname } from 'node:path';
+import { z } from 'zod';
+import { DEFAULT_UPDATE_CHANNEL, UPDATE_CHANNELS, } from './channels.js';
+/**
+ * Default rate-limit window between registry probes. Operators see the
+ * cold-start banner at most once per window. Override per call via
+ * `shouldCheckForUpdate({ intervalHours })` — the cron-style scheduler
+ * passes 0 to force a check on every invocation, the doctor probe
+ * passes 24 to match the operator-visible cadence.
+ */
+export const UPDATE_CHECK_INTERVAL_HOURS = 24;
+/** Filename of the per-user channel + misc config. Mirrors L6 / L25. */
+const CONFIG_FILE = '.pugi/config.json';
+/** Filename of the standalone last-check ISO timestamp. */
+const LAST_CHECK_FILE = '.pugi/.last-update-check';
+/**
+ * Zod schema for the channel slice of `~/.pugi/config.json`. The
+ * passthrough lets sibling skills (L6 `defaultPermissionMode`, L25
+ * onboarding marker, etc.) coexist in the same JSON document without
+ * dropping their fields on a channel write.
+ */
+const channelConfigSchema = z
+    .object({
+    updateChannel: z.enum(['stable', 'beta', 'canary']).optional(),
+})
+    .partial()
+    .passthrough();
+/**
+ * Resolve the absolute path of the per-user config file. Defaults to
+ * the real home dir, but every caller in the spec passes an explicit
+ * tmpdir so the persisted writes never escape the test sandbox.
+ */
+export function configPath(homeDir = homedir()) {
+    return resolve(homeDir, CONFIG_FILE);
+}
+/**
+ * Resolve the absolute path of the single-line last-check file.
+ */
+export function lastCheckPath(homeDir = homedir()) {
+    return resolve(homeDir, LAST_CHECK_FILE);
+}
+/**
+ * Read the persisted channel selection. Returns `null` when the
+ * config file is absent, the field is unset, or the file is unparse-
+ * able. The caller layers in the CLI flag + the hard default
+ * `DEFAULT_UPDATE_CHANNEL`.
+ *
+ * Defensive parse is intentional — a half-written config from a
+ * crashed session should never block `pugi update` from finishing the
+ * channel switch.
+ */
+export function getUpdateChannel(homeDir = homedir()) {
+    const path = configPath(homeDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = channelConfigSchema.parse(JSON.parse(raw));
+        return parsed.updateChannel ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the effective channel for an invocation. Resolution order:
+ *
+ *  1. `cliFlag` (when provided + parses to a known channel).
+ *  2. `~/.pugi/config.json::updateChannel`.
+ *  3. `DEFAULT_UPDATE_CHANNEL` (currently `beta`).
+ *
+ * An invalid `cliFlag` (e.g. `--channel yolo`) falls through to the
+ * next layer rather than crashing — the dispatcher already validates
+ * the flag up front and surfaces a deterministic error for unknown
+ * names. This helper exists for code paths (the doctor probe, the
+ * cold-start banner) where no CLI flag is in play and a silent fall-
+ * through is the correct behaviour.
+ */
+export function resolveEffectiveChannel(options = {}) {
+    const cli = options.cliFlag;
+    if (cli && typeof cli === 'string') {
+        const trimmed = cli.trim().toLowerCase();
+        for (const channel of UPDATE_CHANNELS) {
+            if (channel === trimmed)
+                return channel;
+        }
+    }
+    const persisted = getUpdateChannel(options.homeDir ?? homedir());
+    if (persisted)
+        return persisted;
+    return DEFAULT_UPDATE_CHANNEL;
+}
+/**
+ * Persist the channel to `~/.pugi/config.json::updateChannel`. Creates
+ * `~/.pugi/` when missing; preserves any unrelated keys in the file
+ * (passthrough schema). Atomic tmp+rename so a kill mid-write never
+ * leaves the config half-flushed.
+ */
+export function setUpdateChannel(channel, homeDir = homedir()) {
+    const path = configPath(homeDir);
+    mkdirSync(dirname(path), { recursive: true });
+    const existing = existsSync(path)
+        ? safeParseObject(readFileSync(path, 'utf8'))
+        : {};
+    const next = { ...existing, updateChannel: channel };
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(next, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    renameSync(tmpPath, path);
+}
+/**
+ * Read the ISO timestamp of the most recent registry probe. Returns
+ * `null` when the file is absent or the contents do not parse as a
+ * valid Date. The caller treats `null` as "never checked" and runs an
+ * immediate probe.
+ */
+export function readLastCheckedAt(homeDir = homedir()) {
+    const path = lastCheckPath(homeDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8').trim();
+        if (raw.length === 0)
+            return null;
+        const ts = Date.parse(raw);
+        if (!Number.isFinite(ts))
+            return null;
+        return new Date(ts);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the timestamp of the most recent registry probe. Atomic
+ * tmp+rename for the same reasons as `setUpdateChannel` — the file is
+ * small but we keep the idiom uniform.
+ */
+export function writeLastCheckedAt(when, homeDir = homedir()) {
+    const path = lastCheckPath(homeDir);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, `${when.toISOString()}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    renameSync(tmpPath, path);
+}
+/**
+ * Decide whether the cold-start hint should run a fresh registry
+ * probe. Returns true when the last probe was more than
+ * `intervalHours` ago OR the timestamp file is missing entirely.
+ *
+ * Pass `intervalHours = 0` to force a probe on every call (used by
+ * the `pugi update --check` JSON surface where the operator is
+ * explicitly asking for a fresh result).
+ */
+export function shouldCheckForUpdate(options = {}) {
+    const now = options.now ? options.now() : Date.now();
+    const intervalHours = options.intervalHours ?? UPDATE_CHECK_INTERVAL_HOURS;
+    if (intervalHours <= 0)
+        return true;
+    const last = readLastCheckedAt(options.homeDir ?? homedir());
+    if (!last)
+        return true;
+    const ageMs = now - last.getTime();
+    const windowMs = intervalHours * 60 * 60 * 1_000;
+    return ageMs >= windowMs;
+}
+/**
+ * Defensive helper — parse JSON to an object; non-object payloads
+ * (top-level array, primitive) collapse to an empty object so the
+ * channel-write merge does not surface a TypeError. Mirrors the
+ * `safeParseObject` in `core/permissions/state.ts` — duplicating the
+ * 10 lines is cheaper than threading a shared util module through
+ * two unrelated leak surfaces.
+ */
+function safeParseObject(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=state.js.map