@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.90

package/dist/core/audit/audit-trail.js

@@ -0,0 +1,275 @@
+/**
+ * Tenant-wide JSONL audit trail .
+ *
+ * Pugi already records every tool_call / tool_result in two places:
+ *
+ *  1. The global per-workspace log at `<workspace>/.pugi/events.jsonl`
+ *     (audit-replay source of truth; see `core/session.ts`).
+ *  2. The per-session mirror at
+ *     `<workspace>/.pugi/sessions/<sessionId>/events.jsonl`
+ *     (operator-friendly per-run copy, see `native-pugi.ts`).
+ *
+ * Both live under the workspace directory and disappear when the
+ * operator wipes the workspace or runs many ephemeral sandboxes.
+ * What's missing is a TENANT-wide structured audit log: a single
+ * append-only NDJSON stream per (tenant, workspace) pair that the
+ * operator (or a SOC pipeline) can tail across every session over
+ * the lifetime of the host.
+ *
+ * Spec :
+ *
+ *  - Path: `~/.pugi/audit/<tenant>/<workspace-slug>-<hash>.jsonl`
+ *  - One JSON line per event with shared shape:
+ *    `{ ts, tenant, workspace, workspaceHash, event, sessionId, data }`
+ *  - Events covered: `tool_call`, `tool_result`, `dispatch_start`,
+ *    `dispatch_end`, `permission_denied`, `auto_compact`,
+ *    `budget_exhausted`.
+ *  - Append-only — no rotation logic. Operators wire `logrotate`
+ *    themselves if they want size caps.
+ *  - Opt-out: `PUGI_AUDIT_TRAIL_DISABLE=1`.
+ *  - Failures NEVER throw. Audit MUST NOT break a dispatch.
+ *  - Tenant fallback: when `PUGI_API_KEY` is unset, tenant is `local`.
+ *
+ * Why duplicate the per-session log on disk:
+ *
+ *  The per-session mirror clusters by `sessionId` (one dir per run).
+ *  To answer "what did this tenant DO across every session this week
+ *  from this workspace" an operator otherwise has to glob hundreds of
+ *  session dirs and merge by timestamp. The audit trail flattens that
+ *  into one tail-able stream per (tenant, workspace) — same shape an
+ *  ops pipeline would expect from a hosted log surface.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { collectStrings, scanForInjection, summarizeFindings, } from '../security/injection-scanner.js';
+/**
+ * Opt-out env var. Mirrors the convention every other Pugi feature uses
+ * (`PUGI_BARE`, `PUGI_AGENTMEMORY_RECALL_ENABLED=false`, etc.).
+ * Operators set this when they pipe the CLI through a sandbox that
+ * already captures audit upstream and they want to skip the duplicate.
+ */
+export const PUGI_AUDIT_TRAIL_DISABLE_VAR = 'PUGI_AUDIT_TRAIL_DISABLE';
+/**
+ * Tenant fallback used when the operator has not exported
+ * `PUGI_API_KEY`. The audit trail still flows — it just lives under
+ * `~/.pugi/audit/local/...` so a single-user workstation gets a useful
+ * forensic log without needing API-key plumbing.
+ */
+export const LOCAL_TENANT_FALLBACK = 'local';
+/**
+ * Sanitize the workspace basename to a safe filesystem slug:
+ * lowercase a-z + 0-9 + `-`. Anything else collapses to `-`. We avoid
+ * the empty case (root workspace) by falling back to `workspace`.
+ *
+ * Why not a hash here too: the hash is appended separately so two
+ * workspaces with the same basename (e.g. two clones of the same repo
+ * sitting in different parent dirs) get distinct files. The slug is
+ * the human-readable half operators eyeball at `ls ~/.pugi/audit/...`.
+ */
+export function sanitizeWorkspaceSlug(workspaceRoot) {
+    const base = basename(resolve(workspaceRoot));
+    const sanitized = base
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return sanitized.length > 0 ? sanitized : 'workspace';
+}
+/**
+ * Stable, anonymous workspace handle. We use the FIRST 8 hex of
+ * sha256(workspaceRoot). 8 hex = 32 bits = ~4 billion buckets, more
+ * than enough to disambiguate `~/code/foo` from `~/other/foo` on the
+ * same host without leaking the absolute path through the file name.
+ *
+ * The hash is over the RESOLVED path so symlink trickery cannot point
+ * two different audit streams at the same file by accident.
+ */
+export function computeWorkspaceHash(workspaceRoot) {
+    return createHash('sha256')
+        .update(resolve(workspaceRoot))
+        .digest('hex')
+        .slice(0, 8);
+}
+/**
+ * Derive the tenant slug from `PUGI_API_KEY`. We hash the key (sha256,
+ * 12 hex prefix) rather than emitting the raw key — the audit trail is
+ * a plaintext file on the local FS and the tenant slug shows up in
+ * every path under `~/.pugi/audit/`. A truncated hash is enough to
+ * cluster every (tenant, workspace) over time without leaking the key
+ * if the operator accidentally `tar`s their `~/.pugi` for support.
+ *
+ * The hash is purely a CLI-local clustering key — the runtime backend
+ * has its own (different) tenant identifier and never sees this.
+ */
+export function resolveTenant(env = process.env) {
+    const key = env.PUGI_API_KEY?.trim();
+    if (!key)
+        return LOCAL_TENANT_FALLBACK;
+    // 12 hex = 48 bits — enough disambiguation for any realistic per-host
+    // tenant cardinality; still short enough for operators to eyeball at
+    // `ls ~/.pugi/audit/`.
+    return createHash('sha256').update(key).digest('hex').slice(0, 12);
+}
+/**
+ * Resolve the audit file path for a given (tenant, workspace) pair.
+ * Pure path arithmetic — the caller is responsible for `mkdir -p`
+ * before append (handled inside `writeAuditEvent`).
+ */
+export function resolveAuditPath(workspaceRoot, tenant, home = homedir()) {
+    const slug = sanitizeWorkspaceSlug(workspaceRoot);
+    const hash = computeWorkspaceHash(workspaceRoot);
+    return join(home, '.pugi', 'audit', tenant, `${slug}-${hash}.jsonl`);
+}
+/**
+ * Predicate: is the audit trail disabled via env opt-out?
+ *
+ * Accept `1`, `true`, `yes` (case-insensitive) as positive; anything
+ * else — including `0`, `false`, `''`, and the var being absent — keeps
+ * the trail enabled. Mirrors the convention used in `bare-mode/` and
+ * elsewhere in the CLI.
+ */
+export function isAuditDisabled(env = process.env) {
+    const raw = env[PUGI_AUDIT_TRAIL_DISABLE_VAR]?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+/**
+ * Append a single audit event to the per-tenant per-workspace NDJSON
+ * trail. Never throws — failures (FS unwritable, opt-out, malformed
+ * input) are silently swallowed so a misconfigured audit surface
+ * cannot break a dispatch. The engine adapter's existing per-session
+ * mirror remains intact as a redundant copy.
+ *
+ * Append-only: every call writes exactly one line. No rotation, no
+ * truncation. Operators wire `logrotate` if they want size caps.
+ *
+ * macOS hardening: we `mkdir -p` the parent dir on every call (cheap
+ * in practice — Node short-circuits when the dir exists) so a manual
+ * `rm -rf ~/.pugi/audit/<tenant>/` between runs does not turn the next
+ * append into ENOENT. The mode is `0o700` for the tenant dir and
+ * `0o600` for the JSONL file so curious users on a shared host cannot
+ * read another tenant's trail.
+ */
+export function writeAuditEvent(input) {
+    const env = input.env ?? process.env;
+    if (isAuditDisabled(env))
+        return;
+    try {
+        const tenant = (input.tenant?.trim() || resolveTenant(env)) || LOCAL_TENANT_FALLBACK;
+        const home = input.home ?? homedir();
+        const path = resolveAuditPath(input.workspaceRoot, tenant, home);
+        const now = input.now ? input.now() : new Date().toISOString();
+        const envelope = {
+            ts: now,
+            tenant,
+            workspace: sanitizeWorkspaceSlug(input.workspaceRoot),
+            workspaceHash: computeWorkspaceHash(input.workspaceRoot),
+            event: input.event,
+            sessionId: input.sessionId,
+            data: input.data,
+        };
+        try {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        }
+        catch {
+            // mkdir failure is silent — the appendFileSync below will surface
+            // the real error and the outer catch swallows it. We still try
+            // the write so EEXIST on the dir (the only real path here) does
+            // not block the append.
+        }
+        appendFileSync(path, `${JSON.stringify(envelope)}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        // Injection scan (ported an external utility,
+        // Apache-2.0). Wrap the OUTBOUND `data` payload through the
+        // scanner. Findings emit a SECOND audit line of type
+        // `injection_detected` so an operator (or SOC pipeline) sees a
+        // structured, append-only record without losing the original
+        // event. Never blocks the write — hard-block requires a separate
+        // CEO-signed PR.
+        //
+        // Recursion guard: the `injection_detected` event itself carries
+        // matched substrings (intentional — they are the evidence). We
+        // skip scanning it to avoid an infinite loop of self-detections.
+        if (input.event !== 'injection_detected') {
+            const findings = scanAuditPayload(input.data);
+            if (findings.length > 0) {
+                emitInjectionDetected({
+                    findings,
+                    triggeringEvent: input.event,
+                    sessionId: input.sessionId,
+                    workspaceRoot: input.workspaceRoot,
+                    tenant: input.tenant,
+                    env: input.env,
+                    home: input.home,
+                    now: input.now,
+                });
+            }
+        }
+    }
+    catch {
+        // Audit failures must NEVER break a dispatch. The session log + the
+        // per-session mirror under `<workspace>/.pugi/` remain as redundant
+        // surfaces. A future telemetry pass can surface the failure count
+        // via the doctor probe; for now silent no-op is the contract.
+    }
+}
+/**
+ * Fold the audit `data` payload into a single string and scan it for
+ * prompt-injection / invisible-unicode / secret markers. Returns the
+ * empty array on clean payloads.
+ *
+ * Exported for the spec — the scanner module owns the algorithm, this
+ * helper owns the payload-walking glue.
+ */
+export function scanAuditPayload(data) {
+    // Fold every string anywhere in the payload (keys included) into a
+    // single buffer separated by NULs. NUL keeps regex anchors honest
+    // (no accidental cross-field match for a `^system:` pattern) without
+    // adding bytes that themselves could become a pattern.
+    const fragments = collectStrings(data);
+    if (fragments.length === 0)
+        return [];
+    const joined = fragments.join('\0');
+    return scanForInjection(joined);
+}
+/**
+ * Build the `injection_detected` envelope payload and recurse into
+ * `writeAuditEvent` to append it. The recursion is bounded — the
+ * recursion guard in `writeAuditEvent` short-circuits on the
+ * `injection_detected` event so we never re-scan ourselves.
+ */
+function emitInjectionDetected(input) {
+    const summary = summarizeFindings(input.findings);
+    // Cap the findings array in the audit line so a payload with
+    // hundreds of invisible-unicode hits does not bloat the JSONL row.
+    // The summary still carries `total` so operators see the real count.
+    const MAX_FINDINGS_PER_EVENT = 32;
+    const truncated = input.findings.length > MAX_FINDINGS_PER_EVENT;
+    const capped = truncated
+        ? input.findings.slice(0, MAX_FINDINGS_PER_EVENT)
+        : [...input.findings];
+    writeAuditEvent({
+        event: 'injection_detected',
+        sessionId: input.sessionId,
+        workspaceRoot: input.workspaceRoot,
+        tenant: input.tenant,
+        env: input.env,
+        home: input.home,
+        now: input.now,
+        data: {
+            triggeringEvent: input.triggeringEvent,
+            summary,
+            findings: capped,
+            truncated,
+            // External attribution is recorded inline so a SOC pipeline
+            // grepping for the upstream project name lands here.
+            detector: 'external-injection-patterns',
+        },
+    });
+}
+//# sourceMappingURL=audit-trail.js.map

package/dist/core/auth/ensure-authenticated.js

@@ -0,0 +1,129 @@
+/**
+ * UX — `ensureAuthenticated` helper.
+ *
+ * Auto-login pre-flight for every Pugi command that needs an Anvil
+ * credential. Before this helper landed, cold-start without a stored
+ * credential surfaced a generic "Login required" message and the
+ * operator had к run `pugi login` separately, which broke the muscle-
+ * memory of "open terminal, type the command, see the answer".
+ *
+ * The helper exposes a single contract: `ensureAuthenticated(opts)`.
+ * On a happy path (credential resolves) it returns the credential.
+ * On a cold-start it either:
+ *
+ *  - launches the device-flow login inline (interactive TTY only,
+ *    `--no-login` not set), waits for completion, then re-resolves
+ *    the credential and returns it. The surrounding command continues
+ *    transparently;
+ *  - returns `{ status: 'missing' }` with a reason describing why no
+ *    auto-login was attempted (non-interactive, opted-out, or login
+ *    aborted by user). The caller bails with a clean message.
+ *
+ * Cross-command parity: the helper is wired into every command that
+ * needs auth (engine commands `code`/`fix`/`build`/`explain`/`plan`,
+ * plus `sync`, `chain new`, `smoke`, `review`, `deploy`, ...). The
+ * previous patchwork of `resolveActiveCredential() ?? throw` /
+ * `if (!config) writeOutput unauthenticated` calls now all funnel
+ * through here so future auth changes are one-edit.
+ *
+ * Session cache: the helper caches the resolved credential per-process.
+ * A second command in the same process never re-launches login even if
+ * the operator deletes credentials.json mid-run (that is a footgun, not
+ * a supported use case — the cached credential is still valid because
+ * the auth token in memory has not been revoked).
+ *
+ * Framework-free: the actual login call is injected via the `login`
+ * callback. The CLI passes a closure that calls
+ * `performDeviceFlowLogin` (or the interactive picker for token /
+ * env). The spec passes a fake that flips an in-memory env var so
+ * subsequent `resolveActiveCredential` calls see a credential.
+ */
+/**
+ * Process-local cache of resolved credentials. Keyed by `apiUrl` so a
+ * future `pugi accounts switch` invocation does not return stale data
+ * (different apiUrl → cache miss). Cache is additive-only.
+ */
+const credentialCache = new Map();
+/**
+ * Reset the cache. Exported for spec teardown — production callers
+ * never need this.
+ */
+export function resetAuthenticatedCache() {
+    credentialCache.clear();
+}
+/**
+ * Auth pre-flight. Returns the resolved credential or a structured
+ * `missing` envelope. The cached path skips the `resolve()` callback
+ * entirely — useful when `resolveActiveCredential` is expensive
+ * (filesystem read of ~/.pugi/credentials.json + Zod parse).
+ *
+ * Headless contract: even on a TTY, when `headless === true` the
+ * helper bails with `non_interactive`. Reason: a browser-popup login
+ * in the middle of an automated stdin → engine → stdout loop would
+ * silently freeze the run.
+ */
+export async function ensureAuthenticated(opts) {
+    // Resolve once. Cache by the resolved apiUrl so a subsequent call
+    // after `pugi accounts switch` produces a fresh resolution.
+    const initial = opts.resolve();
+    if (initial) {
+        credentialCache.set(initial.apiUrl, initial);
+        return { status: 'ready', credential: initial };
+    }
+    if (opts.skip) {
+        return {
+            status: 'missing',
+            reason: 'disabled',
+            detail: 'Authentication skipped (--no-login or PUGI_NO_AUTO_LOGIN). Run `pugi login` to authenticate.',
+        };
+    }
+    if (opts.headless) {
+        return {
+            status: 'missing',
+            reason: 'non_interactive',
+            detail: 'Headless mode cannot launch browser-popup login. Run `pugi login` once with a TTY, then re-run with --headless.',
+        };
+    }
+    if (!opts.interactive) {
+        return {
+            status: 'missing',
+            reason: 'non_interactive',
+            detail: 'No credential found and stdin is not a TTY. Run `pugi login` with a TTY OR set PUGI_API_KEY before invoking Pugi in CI.',
+        };
+    }
+    const write = opts.write ?? ((line) => process.stderr.write(line));
+    write('No Pugi credential found. Launching login...\n');
+    let succeeded;
+    try {
+        succeeded = await opts.login();
+    }
+    catch (error) {
+        return {
+            status: 'missing',
+            reason: 'login_failed',
+            detail: `Login failed: ${error.message ?? String(error)}`,
+        };
+    }
+    if (!succeeded) {
+        return {
+            status: 'missing',
+            reason: 'login_cancelled',
+            detail: 'Authentication required to continue. Run `pugi login` when ready.',
+        };
+    }
+    // Re-resolve. If a successful login was reported but no credential
+    // landed on disk, surface that as `login_failed` rather than a
+    // silent miss — would otherwise produce a confusing "you said it
+    // worked but I still see nothing" loop.
+    const resolved = opts.resolve();
+    if (!resolved) {
+        return {
+            status: 'missing',
+            reason: 'login_failed',
+            detail: 'Login reported success but no credential persisted. Check `pugi whoami`.',
+        };
+    }
+    credentialCache.set(resolved.apiUrl, resolved);
+    return { status: 'ready', credential: resolved };
+}
+//# sourceMappingURL=ensure-authenticated.js.map

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

@@ -0,0 +1,238 @@
+/**
+ * `pugi login --provider env` — env-var auth path ().
+ *
+ * the upstream tool, peer 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-open-browser.js

@@ -18,7 +18,7 @@ export async function autoOpenBrowser(url, deps = {}) {
         return { opened: spawnDetached('open', [url]) };
     }
     if (platform === 'win32') {
-        // P1-3 (triple-review 2026-05-24): cmd.exe parses `&` as a command
+        // 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`
@@ -67,7 +67,7 @@ function isSafeHttpUrl(candidate) {
     }
 }
 /**
- * P1-3 (triple-review 2026-05-24): wrap a URL for PowerShell's
+ * 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
@@ -78,7 +78,7 @@ function quoteForPowerShell(url) {
     return `'${url.replace(/'/g, "''")}'`;
 }
 /**
- * P1-3 (triple-review 2026-05-24): wrap a URL for cmd.exe's
+ * 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:
@@ -102,7 +102,7 @@ function defaultSpawnDetached(cmd, args) {
             shell: false,
         };
         const child = spawn(cmd, args.slice(), options);
-        // P3 polish (triple-review 2026-05-24): swallow the async `error`
+        // 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