@pugi/cli 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/runtime/update-check.js

@@ -0,0 +1,294 @@
+/**
+ * Update check + install-method detection — Sprint α6.2.
+ *
+ * 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/tools/registry.js

@@ -10,6 +10,7 @@ const registry = [
     { name: 'task_get', permission: 'none', risk: 'low', concurrencySafe: true, m1: true },
     { name: 'task_list', permission: 'none', risk: 'low', concurrencySafe: true, m1: true },
     { name: 'task_update', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
+    { name: 'web_fetch', permission: 'network', risk: 'medium', concurrencySafe: true, m1: true },
     { name: 'write', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
 ];
 export const toolRegistry = registry.sort((a, b) => a.name.localeCompare(b.name));