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

package/dist/runtime/update-check.js

@@ -1,294 +0,0 @@
-/**
- * Update check + install-method detection — Sprint .
- *
- * Shows the REPL operator a one-shot banner at startup when the npm
- * registry advertises a `@pugi/cli` version newer than what is running.
- * The banner adapts the upgrade hint per install method so the operator
- * sees a copy-pasteable command for their toolchain (brew / npm / curl).
- *
- * Constraints baked into the spec:
- *
- *  - **Default-quiet.** Network errors, cache misses, and the
- *    `PUGI_SKIP_UPDATE_BANNER=1` env var all return `null` so the
- *    REPL renders unchanged.
- *  - **24h cache.** The check runs at most once per day, persisted to
- *    `~/.pugi/update-check.json`. Repeated REPL launches in the same
- *    day skip the registry call entirely.
- *  - **3s timeout.** A slow registry never blocks REPL startup; the
- *    undici request is aborted after 3 seconds and treated as a
- *    silent miss.
- *  - **Pure helpers, IO at the edge.** Detection, comparison, cache
- *    decode/encode are exported as pure functions with explicit env /
- *    home / now / fetch seams so the spec's 8 tests can drive every
- *    branch without touching the network or the real filesystem.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
-import { request } from 'undici';
-const REGISTRY_URL = 'https://registry.npmjs.org/@pugi/cli/latest';
-const FETCH_TIMEOUT_MS = 3_000;
-const CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
-/**
- * Pin the install toolchain from the binary path + a small set of env
- * markers. Order matters: the curl installer sets PUGI_VIA_CURL_INSTALL
- * unconditionally, so we honor it first; brew is path-based; npm is the
- * fallback for anything that looks like a node_modules layout; otherwise
- * unknown.
- */
-export function detectInstallMethod(input = {}) {
-    const env = input.env ?? process.env;
-    const execPath = input.execPath ?? process.execPath;
-    if (env.PUGI_VIA_CURL_INSTALL === '1')
-        return 'curl';
-    // Homebrew on macOS keeps node + bin shims under /opt/homebrew (Apple
-    // silicon) or /usr/local/Cellar (Intel). Either suffices to pin brew.
-    if (execPath.includes('/opt/homebrew/') ||
-        execPath.includes('/usr/local/Cellar/') ||
-        execPath.includes('/homebrew/')) {
-        return 'brew';
-    }
-    // npm-global layouts: nvm, fnm, asdf, volta, yarn-global, and the
-    // classic `~/.npm-packages` PATH prefix all leave a fingerprint on
-    // execPath or PATH. Treat any of these as `npm` so the banner shows
-    // the matching `npm install -g` hint.
-    const pathEntries = (env.PATH ?? '').split(':');
-    const npmFingerprints = [
-        '/.nvm/',
-        '/.fnm/',
-        '/.volta/',
-        '/.asdf/',
-        '/.npm-packages/',
-        '/.config/yarn/global',
-    ];
-    if (npmFingerprints.some((marker) => execPath.includes(marker)))
-        return 'npm';
-    if (pathEntries.some((entry) => entry.includes('/.npm-packages') || entry.includes('/.config/yarn/global'))) {
-        return 'npm';
-    }
-    if (execPath.includes('/node_modules/'))
-        return 'npm';
-    return 'unknown';
-}
-/**
- * Cache path resolver. PUGI_HOME wins (test seam matches the rest of
- * the codebase), else `~/.pugi/update-check.json`.
- */
-export function resolveCachePath(home, env = process.env) {
-    const root = env.PUGI_HOME ?? resolve(home ?? homedir(), '.pugi');
-    return resolve(root, 'update-check.json');
-}
-export function loadCache(home, env = process.env) {
-    const path = resolveCachePath(home, env);
-    if (!existsSync(path))
-        return null;
-    try {
-        const text = readFileSync(path, 'utf8');
-        const parsed = JSON.parse(text);
-        if (typeof parsed.checkedAt !== 'string' || typeof parsed.latestVersion !== 'string') {
-            return null;
-        }
-        return { checkedAt: parsed.checkedAt, latestVersion: parsed.latestVersion };
-    }
-    catch {
-        // Corrupt or unreadable cache — treat as no cache. The next write
-        // overwrites the file cleanly.
-        return null;
-    }
-}
-export function saveCache(record, home, env = process.env) {
-    const path = resolveCachePath(home, env);
-    const dir = path.slice(0, path.lastIndexOf('/'));
-    try {
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
-        writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8' });
-    }
-    catch {
-        // Best-effort. A read-only home or full disk should not crash REPL
-        // startup — we just skip caching this round.
-    }
-}
-export function isCacheFresh(record, nowMs) {
-    const checkedMs = Date.parse(record.checkedAt);
-    if (!Number.isFinite(checkedMs))
-        return false;
-    return nowMs - checkedMs < CACHE_TTL_MS;
-}
-/**
- * Compare two semver strings (with prerelease support sufficient for
- * `0.1.0-alpha.6` vs `0.1.0-alpha.7` / `0.1.0-beta.1` / `1.0.0`).
- *
- * Returns:
- *  -1 if `a < b`
- *   0 if `a === b`
- *   1 if `a > b`
- *
- * Rules follow semver §11:
- *  - Major.Minor.Patch compared numerically left-to-right.
- *  - A version with a prerelease tag is LOWER than the same version
- *    without one (`1.0.0-alpha` < `1.0.0`).
- *  - Prerelease identifiers compared dot-by-dot; numeric chunks
- *    numerically, mixed chunks ASCII-lexicographic.
- */
-export function compareVersions(a, b) {
-    const [coreA, preA] = splitVersion(a);
-    const [coreB, preB] = splitVersion(b);
-    for (let i = 0; i < 3; i += 1) {
-        const da = coreA[i] ?? 0;
-        const db = coreB[i] ?? 0;
-        if (da < db)
-            return -1;
-        if (da > db)
-            return 1;
-    }
-    if (preA === null && preB === null)
-        return 0;
-    if (preA === null)
-        return 1;
-    if (preB === null)
-        return -1;
-    return comparePrerelease(preA, preB);
-}
-function splitVersion(v) {
-    const dashIdx = v.indexOf('-');
-    const coreStr = dashIdx === -1 ? v : v.slice(0, dashIdx);
-    const preStr = dashIdx === -1 ? null : v.slice(dashIdx + 1);
-    const core = coreStr.split('.').map((n) => {
-        const parsed = Number.parseInt(n, 10);
-        return Number.isFinite(parsed) ? parsed : 0;
-    });
-    return [core, preStr];
-}
-function comparePrerelease(a, b) {
-    const partsA = a.split('.');
-    const partsB = b.split('.');
-    const max = Math.max(partsA.length, partsB.length);
-    for (let i = 0; i < max; i += 1) {
-        const pa = partsA[i];
-        const pb = partsB[i];
-        if (pa === undefined)
-            return -1;
-        if (pb === undefined)
-            return 1;
-        const na = Number.parseInt(pa, 10);
-        const nb = Number.parseInt(pb, 10);
-        const aIsNum = String(na) === pa;
-        const bIsNum = String(nb) === pb;
-        if (aIsNum && bIsNum) {
-            if (na < nb)
-                return -1;
-            if (na > nb)
-                return 1;
-            continue;
-        }
-        if (aIsNum)
-            return -1; // numeric < alphanumeric, per semver §11
-        if (bIsNum)
-            return 1;
-        if (pa < pb)
-            return -1;
-        if (pa > pb)
-            return 1;
-    }
-    return 0;
-}
-/**
- * One-shot registry GET. Wrapped in a 3s timeout and silently swallows
- * every failure mode — the spec says cache miss / network error = no
- * banner. Returns the `version` string from npm's well-known
- * `/:pkg/latest` document on success, or `null` on any failure.
- */
-export async function fetchLatestVersion(fetcher = request) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-    try {
-        const response = await fetcher(REGISTRY_URL, {
-            method: 'GET',
-            headers: { accept: 'application/json' },
-            bodyTimeout: FETCH_TIMEOUT_MS,
-            headersTimeout: FETCH_TIMEOUT_MS,
-            signal: controller.signal,
-        });
-        if (response.statusCode < 200 || response.statusCode >= 300) {
-            await response.body.dump();
-            return null;
-        }
-        const text = await response.body.text();
-        const parsed = JSON.parse(text);
-        if (typeof parsed.version !== 'string' || parsed.version.length === 0)
-            return null;
-        return parsed.version;
-    }
-    catch {
-        return null;
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-/**
- * High-level orchestrator wired into the CLI startup path. Returns the
- * banner payload when an update is available AND every silence rule
- * declines to fire, otherwise `null`.
- *
- * Silence rules (any one of these short-circuits to `null`):
- *  - `cliSkip === true` (operator passed `--no-update-check`).
- *  - `env.PUGI_SKIP_UPDATE_BANNER === '1'`.
- *  - `isTty === false` (CI / piped / scripted invocation).
- *  - Cache + network both miss — silent skip per spec.
- *  - `installed >= latest` — no upgrade to advertise.
- */
-export async function checkForUpdate(options) {
-    const env = options.env ?? process.env;
-    const now = options.now ?? Date.now;
-    const cliSkip = options.cliSkip === true;
-    const envSkip = env.PUGI_SKIP_UPDATE_BANNER === '1';
-    const isTty = options.isTty ??
-        (Boolean(process.stdout.isTTY) &&
-            Boolean(process.stdin.isTTY));
-    if (cliSkip || envSkip || !isTty)
-        return null;
-    // Cache-first path. A fresh cache (<24h) bypasses the registry round
-    // trip entirely so a daily REPL operator pays one network call per
-    // calendar day.
-    const cached = loadCache(options.home, env);
-    let latest = null;
-    if (cached && isCacheFresh(cached, now())) {
-        latest = cached.latestVersion;
-    }
-    else {
-        latest = await fetchLatestVersion(options.fetcher);
-        if (latest) {
-            saveCache({ checkedAt: new Date(now()).toISOString(), latestVersion: latest }, options.home, env);
-        }
-    }
-    if (!latest)
-        return null;
-    if (compareVersions(options.installed, latest) >= 0)
-        return null;
-    return {
-        installed: options.installed,
-        latest,
-        method: detectInstallMethod({ env }),
-    };
-}
-/**
- * Render the per-method upgrade command. Pure helper so the Ink
- * banner component and any future JSON / log surface share one source
- * of truth on the copy.
- */
-export function upgradeCommand(method) {
-    switch (method) {
-        case 'brew':
-            return 'brew upgrade pugi-io/tap/pugi';
-        case 'npm':
-            return 'npm install -g @pugi/cli@latest';
-        case 'curl':
-            return 'curl -fsSL https://install.pugi.io | sh';
-        case 'unknown':
-        default:
-            return 'npm install -g @pugi/cli@latest # or your install method';
-    }
-}
-//# sourceMappingURL=update-check.js.map

package/dist/runtime/version.js

@@ -1,65 +0,0 @@
-/**
- * Pugi CLI ↔ admin-api version handshake — shared constants.
- *
- * The CLI declares its installed version on every outbound request to
- * the admin-api so the server can enforce a minClientVersion floor and
- * surface a soft-warn for stale-but-allowed installs. See ADR-225 and
- * `apps/admin-api/src/runtime/version.contract.ts` for the server side.
- *
- * # Why the constants live here, not in `@pugi/sdk`
- *
- * The SDK ships to customers as part of the public npm package; bumping
- * a header name there would force a coupled CLI ↔ SDK release. Keeping
- * the constants in the CLI gives us room to evolve the handshake
- * without coupling the SDK's release cadence to it.
- */
-/**
- * Defensive semver sanitizer — single source of truth for the
- * `0.0.0-unknown` fallback when a partially-published pnpm release
- * leaks `workspace:*` into the version literal. `runtime/cli.ts`
- * re-exports this under its `__test__` surface so the existing
- * cli.ts test corpus keeps working with zero churn.
- *
- * Lives here (not in cli.ts) because the version handshake interceptor
- * needs the same guarantee without pulling in the heavyweight cli.ts
- * module graph during transport bootstrap.
- */
-export function sanitizeSemver(raw) {
-    if (typeof raw !== 'string')
-        return '0.0.0-unknown';
-    const trimmed = raw.trim();
-    if (!trimmed)
-        return '0.0.0-unknown';
-    const stripped = trimmed.replace(/^(workspace:|npm:|file:)/, '');
-    if (/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(stripped)) {
-        return stripped;
-    }
-    return '0.0.0-unknown';
-}
-/**
- * Installed CLI version — single source of truth for the handshake
- * header value. Mirrors the literal in `runtime/cli.ts` (intentional
- * duplication because the cli.ts module pulls in Ink + half the CLI
- * surface and the transport interceptor must remain side-effect-free
- * during import). When bumping the CLI version BOTH literals must be
- * updated; the release smoke-test (`pack:smoke`) verifies they agree.
- */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.98');
-/**
- * Outbound: the CLI's installed semver. Read at request time by
- * `version-interceptor.ts` and injected on every `fetch` call.
- */
-export const PUGI_CLI_VERSION_HEADER = 'X-Pugi-Cli-Version';
-/**
- * Inbound: the server's recommendation for which CLI version operators
- * should be on. Surfaces through the UpdateBanner alongside the npm
- * registry poll (the higher of the two wins).
- */
-export const PUGI_CLI_UPGRADE_RECOMMENDED_HEADER = 'X-Pugi-Cli-Upgrade-Recommended';
-/**
- * Inbound: server's own admin-api version. Useful for diagnostics
- * (`pugi doctor --json`) but no enforcement logic keys off it — server
- * drift between admin-api releases is normal during rolling deploys.
- */
-export const PUGI_SERVER_VERSION_HEADER = 'X-Pugi-Server-Version';
-//# sourceMappingURL=version.js.map