@pugi/cli 0.1.0-beta.22 → 0.1.0-beta.24

package/dist/core/auth/env-provider.js

@@ -0,0 +1,238 @@
+/**
+ * `pugi login --provider env` — env-var auth path (Leak L35).
+ *
+ * Claude Code, Codex CLI, and gh CLI all ship a way to authenticate via
+ * an environment variable so CI / container / scripted contexts can
+ * skip the device flow entirely. This module backs that path:
+ *
+ *   1. Resolve the candidate token (explicit `--key` flag beats
+ *      `PUGI_API_KEY` env — same precedence as `gh auth login --token`).
+ *   2. Run a cheap local format check so an obviously malformed key
+ *      (empty, whitespace, suspiciously short) fails fast WITHOUT
+ *      shipping it to the server (no observability leak into the
+ *      Anvil access log).
+ *   3. Call `GET /api/pugi/health` with `Authorization: Bearer <key>`
+ *      so an expired / revoked / typo'd token surfaces immediately
+ *      and the credential file never lands on disk for a dead key.
+ *   4. Map response to typed outcome the CLI dispatcher can render.
+ *
+ * The module is intentionally pure — fetch + reading env are injected,
+ * the writer is a separate concern. The CLI dispatcher composes
+ * `resolveEnvCandidateToken` + `assertTokenFormat` + `validateTokenAgainstHealth`
+ * and then writes the credential via `storeApiKey` on success.
+ *
+ * Failure modes are explicit so the dispatcher can pick the user-facing
+ * remediation string without re-parsing strings:
+ *
+ *   - `missing`          → no token in env or --key, halt with hint
+ *   - `invalid-format`   → token failed local format check, halt
+ *   - `unauthorized`     → server rejected the token (401 / 403)
+ *   - `network-error`    → fetch threw (DNS, refused, TLS)
+ *   - `server-error`     → server returned 5xx (transient — operator
+ *                          may want to retry once)
+ *   - `unexpected-status`→ anything else non-2xx (treat as failure)
+ *
+ * NEVER log the raw token. Memory hits
+ * `feedback_no_claude_attribution_anywhere_hard_rule` plus the
+ * CSO bearer-leak sweep apply here. Use `maskApiKey` from
+ * `core/credentials.ts` when the dispatcher needs to surface the key
+ * to the operator.
+ */
+/**
+ * The minimum length below which we refuse to even ship the token to
+ * the server. Pugi-issued PATs are 48+ chars (`pugi_<32 base32>`), JWTs
+ * issued by the device flow are ~250 chars, legacy `sk-*` PATs we
+ * accept for compatibility are 32+. 16 is well below all three real
+ * shapes so it only catches obvious paste mistakes.
+ */
+export const MIN_TOKEN_LENGTH = 16;
+/**
+ * The set of prefixes we recognise as plausibly-real Pugi-shaped
+ * tokens. Loose by design — the real validator is the server-side
+ * health probe. We just want to catch an operator who pasted the
+ * wrong string entirely (a username, a URL, a placeholder like
+ * "<your-key>") before it reaches the network.
+ *
+ * Three-segment JWTs are also accepted via the `looksLikeJwt`
+ * predicate so device-flow tokens copied out of `~/.pugi/credentials.json`
+ * on a different machine work.
+ */
+export const RECOGNISED_TOKEN_PREFIXES = ['pugi_', 'sk_', 'sk-', 'pat_'];
+/**
+ * Returns the trimmed candidate token, or `null` when neither path
+ * produced one. Precedence: explicit flag arg beats env var (matches
+ * `gh auth login --with-token`, `aws configure set`, and `pugi config`
+ * which all prefer the most-specific operator intent over the ambient
+ * env).
+ */
+export function resolveEnvCandidateToken(input) {
+    const explicit = input.explicitKey?.trim();
+    if (explicit)
+        return explicit;
+    const env = input.env ?? process.env;
+    const fromEnv = env.PUGI_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return null;
+}
+/**
+ * Local-only format check. Returns `null` on accept, a human-readable
+ * error string on reject. Deliberately lenient — the server-side
+ * health probe is the source of truth. We only catch obvious paste
+ * mistakes (empty, whitespace-laden, too short, looks like a URL or
+ * a placeholder).
+ */
+export function assertTokenFormat(token) {
+    if (!token)
+        return 'Token is empty';
+    if (/\s/.test(token)) {
+        return 'Token contains whitespace — check for shell quoting issues or a stray newline';
+    }
+    if (token.length < MIN_TOKEN_LENGTH) {
+        return `Token too short (${token.length} chars; Pugi tokens are >= ${MIN_TOKEN_LENGTH})`;
+    }
+    if (token.startsWith('<') && token.endsWith('>')) {
+        return 'Token looks like a placeholder (`<your-key>`) — replace with the actual key';
+    }
+    if (/^https?:\/\//i.test(token)) {
+        return 'Token looks like a URL — did you mean --api-url?';
+    }
+    // Accept either a recognised prefix OR a JWT three-segment shape.
+    // Anything else still passes — the server probe will catch genuinely
+    // unknown keys. We just want to surface an obvious mistake.
+    const hasKnownPrefix = RECOGNISED_TOKEN_PREFIXES.some((p) => token.startsWith(p));
+    if (!hasKnownPrefix && !looksLikeJwt(token)) {
+        // Soft-fail: warn the operator but proceed. Returning null here
+        // would mask the case where the operator pasted something
+        // genuinely wrong but the server happens to accept it (impossible
+        // for real keys but defence-in-depth). Returning the warning
+        // string would block legacy keys. We choose to proceed — the
+        // server is the source of truth — and let the CLI dispatcher
+        // decide whether to surface a note. Tracked via a separate
+        // `warnUnknownPrefix` return on a future revision.
+        return null;
+    }
+    return null;
+}
+/**
+ * JWT three-segment check. Does NOT verify the signature — we just
+ * want to recognise the shape so device-flow tokens copied from one
+ * machine to another pass the format gate.
+ */
+export function looksLikeJwt(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return false;
+    return parts.every((p) => /^[A-Za-z0-9_-]+$/.test(p) && p.length > 0);
+}
+/**
+ * Call `GET /api/pugi/health` with the candidate token. Returns a
+ * typed outcome that the CLI dispatcher can map directly to an exit
+ * code + remediation string.
+ *
+ * Health endpoint conventions (see apps/admin-api):
+ *   - 200 → token is valid, account is active
+ *   - 401 → token unknown / malformed at the server boundary
+ *   - 403 → token recognised but the account is suspended / paused
+ *   - 5xx → server-side issue, operator can retry
+ *   - network throw → DNS, refused, TLS — operator's connectivity issue
+ *
+ * We do not parse the body — the health endpoint's contract is the
+ * status code. Any future field (latency, region, build sha) can be
+ * surfaced by a separate `pugi doctor` probe without touching the
+ * login path.
+ */
+export async function validateTokenAgainstHealth(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const now = input.now ?? Date.now;
+    const url = `${stripTrailingSlash(input.apiUrl)}/api/pugi/health`;
+    const started = now();
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${input.apiKey}`,
+                Accept: 'application/json',
+            },
+        });
+    }
+    catch (error) {
+        // DNS failure, ECONNREFUSED, TLS handshake — anything that makes
+        // fetch throw before a status code is observable. We deliberately
+        // do NOT echo the URL host in the message body if it could leak a
+        // self-hosted Anvil hostname into a public CI log; the dispatcher
+        // composes the user-facing remediation.
+        const cause = error instanceof Error ? error.message : String(error);
+        return {
+            kind: 'network-error',
+            message: `Cannot reach ${input.apiUrl}; check your connection`,
+            cause,
+        };
+    }
+    const latencyMs = now() - started;
+    const { status } = response;
+    if (status === 200) {
+        return { kind: 'ok', latencyMs };
+    }
+    if (status === 401 || status === 403) {
+        return {
+            kind: 'unauthorized',
+            status,
+            message: status === 401
+                ? 'Token invalid or expired — run `pugi login --provider device` to get a fresh one'
+                : 'Token recognised but the account is suspended — check `pugi whoami` on a working machine or contact support',
+        };
+    }
+    if (status >= 500) {
+        return {
+            kind: 'server-error',
+            status,
+            message: `${input.apiUrl} returned ${status}; retry in a moment`,
+        };
+    }
+    return {
+        kind: 'unexpected-status',
+        status,
+        message: `Unexpected ${status} from /api/pugi/health; treat as login failure`,
+    };
+}
+export async function resolveAndValidateEnvLogin(input) {
+    const token = resolveEnvCandidateToken({
+        explicitKey: input.explicitKey,
+        env: input.env,
+    });
+    if (!token) {
+        return {
+            kind: 'missing',
+            message: 'pugi login --provider env requires a token. Export PUGI_API_KEY in the current shell or pass --key <value>.',
+        };
+    }
+    const formatError = assertTokenFormat(token);
+    if (formatError) {
+        return {
+            kind: 'invalid-format',
+            message: `pugi login --provider env: ${formatError}`,
+        };
+    }
+    if (input.skipValidate) {
+        // Used by the existing `login-variants.spec.ts` regression suite
+        // so the test plane does not require a live network. Production
+        // path always validates.
+        return { kind: 'ok', token, latencyMs: 0 };
+    }
+    const probe = await validateTokenAgainstHealth({
+        apiUrl: input.apiUrl,
+        apiKey: token,
+        fetchImpl: input.fetchImpl,
+        now: input.now,
+    });
+    if (probe.kind === 'ok') {
+        return { kind: 'ok', token, latencyMs: probe.latencyMs };
+    }
+    return probe;
+}
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+//# sourceMappingURL=env-provider.js.map

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

@@ -0,0 +1,122 @@
+/**
+ * Leak L27 (2026-05-27) — Auto-update channel model.
+ *
+ * Claude Code'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 @@
+/**
+ * Leak L27 (2026-05-27) — 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