@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/core/auto-open-browser.js

@@ -1,128 +0,0 @@
-import { spawn } from 'node:child_process';
-/**
- * Open `url` in the default browser. Returns `{ opened: true }` on a
- * successful spawn, `{ opened: false }` on any failure. The url is not
- * shell-escaped here; we always pass it as a single argv element to a
- * direct spawn (no shell), so quoting is irrelevant.
- */
-export async function autoOpenBrowser(url, deps = {}) {
-    const platform = deps.platform ?? process.platform;
-    const spawnDetached = deps.spawnDetached ?? defaultSpawnDetached;
-    // Refuse anything that does not parse as http(s). The device-flow URL
-    // is always https — guarding here keeps a hostile server response
-    // from convincing us to spawn `open file:///etc/passwd` or worse.
-    if (!isSafeHttpUrl(url)) {
-        return { opened: false };
-    }
-    if (platform === 'darwin') {
-        return { opened: spawnDetached('open', [url]) };
-    }
-    if (platform === 'win32') {
-        // P1-3 (triple-review): cmd.exe parses `&` as a command
-        // separator BEFORE Node hands argv to the child, regardless of
-        // `shell: false`. A device-flow URL like
-        // `https://app.pugi.io/devices/authorize?user_code=ABC&trace=xyz`
-        // would be truncated at the `&`, opening only the first half. We
-        // prefer PowerShell (its argv parser is sane: a single quoted URL
-        // round-trips verbatim) and fall back to a double-quoted cmd
-        // invocation when PowerShell is missing from PATH.
-        if (spawnDetached('powershell', [
-            '-NoProfile',
-            '-NonInteractive',
-            '-Command',
-            'Start-Process',
-            quoteForPowerShell(url),
-        ])) {
-            return { opened: true };
-        }
-        // Fallback: `cmd /c start "" "<url>"`. The URL itself is wrapped
-        // in double quotes so cmd does not split on `&`; any embedded `"`
-        // in the URL is escaped using cmd's caret-quote convention.
-        return {
-            opened: spawnDetached('cmd', ['/c', 'start', '""', quoteForCmd(url)]),
-        };
-    }
-    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
-        // Try xdg-open first (the freedesktop standard), then gio (GNOME),
-        // then a couple of well-known browsers as a last resort. Each
-        // attempt is a fresh spawn — if the binary is missing the helper
-        // returns false and we fall through.
-        for (const cmd of LINUX_OPENERS) {
-            if (spawnDetached(cmd, [url]))
-                return { opened: true };
-        }
-        return { opened: false };
-    }
-    // Unknown platform (android, aix, sunos…) — degrade gracefully.
-    return { opened: false };
-}
-const LINUX_OPENERS = ['xdg-open', 'gio', 'gnome-open', 'kde-open'];
-function isSafeHttpUrl(candidate) {
-    try {
-        const url = new URL(candidate);
-        return url.protocol === 'https:' || url.protocol === 'http:';
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * P1-3 (triple-review): wrap a URL for PowerShell's
- * `Start-Process` invocation. PowerShell's single-quote string literal
- * does NOT process escape sequences; the only metachar inside is the
- * single quote itself (escaped by doubling). URLs do not contain
- * single quotes in practice, but the helper handles them defensively
- * so future input shapes do not break.
- */
-function quoteForPowerShell(url) {
-    return `'${url.replace(/'/g, "''")}'`;
-}
-/**
- * P1-3 (triple-review): wrap a URL for cmd.exe's
- * `start ""` invocation. Double quotes pin the URL as a single token
- * so cmd does NOT split on `&`, `|`, `^`, `<`, `>`. Embedded `"` (rare
- * in URLs but defensible) is escaped via cmd's caret-quote convention:
- * `^"`.
- */
-function quoteForCmd(url) {
-    return `"${url.replace(/"/g, '^"')}"`;
-}
-/**
- * Real spawn implementation. Detaches the child so the Pugi CLI can
- * exit (or keep polling) without inheriting the browser's lifecycle.
- * Returns `true` only when the spawn produced a pid; any error event
- * (ENOENT for a missing binary, EACCES for a sandboxed permission
- * denial) flips the result to `false`.
- */
-function defaultSpawnDetached(cmd, args) {
-    try {
-        const options = {
-            detached: true,
-            stdio: 'ignore',
-            shell: false,
-        };
-        const child = spawn(cmd, args.slice(), options);
-        // P3 polish (triple-review): swallow the async `error`
-        // event (ENOENT for a missing binary, EACCES for a sandboxed
-        // permission denial). The old `errored` flag was always false at
-        // the synchronous `return !errored` point (the `error` event is
-        // delivered later in the next tick), so the flag was dead. The
-        // listener is still required: without it, Node escalates the
-        // event to an unhandled-error and crashes the host process when
-        // the binary is missing.
-        child.on('error', () => undefined);
-        if (typeof child.pid !== 'number')
-            return false;
-        // unref so the parent event loop is not held open by the browser
-        // handle. The browser process continues independently.
-        child.unref();
-        // Callers treat `true` as best-effort: the fallback "Browser
-        // didn't open?" hint is always rendered, so a silent spawn
-        // failure still leaves the user a usable path.
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-//# sourceMappingURL=auto-open-browser.js.map

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

@@ -1,122 +0,0 @@
-/**
- * — 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

@@ -1,241 +0,0 @@
-/**
- * — 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