@pugi/cli 0.1.0-beta.3 → 0.1.0-beta.31

package/dist/core/artifact-chain/state.js

@@ -0,0 +1,243 @@
+/**
+ * Artifact chain state machine — Pugi α7 Wave 6 (2026-05-27).
+ *
+ * Owns the on-disk persisted state for a single chain
+ * (`.pugi/chains/<chain-id>/chain.json`). A chain is a deterministic
+ * 7-step pipeline: each step is `pending` → `dispatched` → `complete`
+ * (terminal). The machine never auto-advances; operator review between
+ * steps is the gate. This file is pure with respect to the network and
+ * stays small enough to import from the REPL hot path without dragging
+ * the dispatcher graph along.
+ *
+ * Concurrency: the CLI is single-process per invocation; the on-disk
+ * format tolerates two simultaneous readers (snapshot is atomic via
+ * write-then-rename) but writers MUST take the per-chain directory as
+ * an implicit lock. Multi-writer races are out-of-scope — the operator
+ * runs one `pugi chain next` at a time.
+ *
+ * Backwards-compat: `schemaVersion` is pinned. Older chains with no
+ * version field default to `1`. Bump + add migration logic when the
+ * persisted shape changes.
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync, renameSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { CHAIN_STEPS, CHAIN_STEP_IDS, CHAIN_STEP_COUNT, findStep, } from './steps.js';
+/**
+ * Generate a new chain id. Format: `chn_<8 lowercase hex>`. Short
+ * enough to fit on one terminal column; collision probability is fine
+ * for the operator-scale workload (chains per workspace per session).
+ */
+export function generateChainId(rng = () => randomBytes(4)) {
+    return `chn_${rng().toString('hex')}`;
+}
+/**
+ * Resolve the directory that holds a single chain. Encapsulates the
+ * `.pugi/chains/<id>/` convention so every caller agrees.
+ */
+export function chainDir(workspaceCwd, chainId) {
+    return resolve(workspaceCwd, '.pugi', 'chains', chainId);
+}
+/**
+ * Path to the chain's state JSON. Atomic writes go through a sibling
+ * `chain.json.tmp` + rename so a crashed CLI cannot leave a truncated
+ * state file behind.
+ */
+export function chainStatePath(workspaceCwd, chainId) {
+    return join(chainDir(workspaceCwd, chainId), 'chain.json');
+}
+/**
+ * Initialise on-disk state for a fresh chain. Returns the persisted
+ * snapshot. Throws when the chain id already exists on disk so the
+ * caller is forced to handle the collision explicitly.
+ */
+export function createChain(workspaceCwd, intent, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const id = options.chainId ?? generateChainId();
+    const dir = chainDir(workspaceCwd, id);
+    if (existsSync(dir)) {
+        throw new Error(`chain ${id} already exists at ${dir}`);
+    }
+    mkdirSync(dir, { recursive: true });
+    const createdAt = now().toISOString();
+    const trimmedIntent = intent.trim();
+    if (trimmedIntent.length === 0) {
+        throw new Error('chain intent must be non-empty');
+    }
+    const steps = CHAIN_STEPS.map((descriptor) => ({
+        id: descriptor.id,
+        status: 'pending',
+        updatedAt: createdAt,
+        dispatchId: null,
+        errorMessage: null,
+    }));
+    const state = {
+        schemaVersion: 1,
+        id,
+        intent: trimmedIntent,
+        createdAt,
+        updatedAt: createdAt,
+        nextStep: CHAIN_STEP_IDS[0] ?? null,
+        steps,
+    };
+    writeStateAtomic(workspaceCwd, state);
+    return Object.freeze(state);
+}
+/**
+ * Read the persisted state for a chain. Returns `null` when the chain
+ * does not exist on disk — callers render a friendly "no such chain"
+ * message instead of throwing.
+ */
+export function readChain(workspaceCwd, chainId) {
+    const path = chainStatePath(workspaceCwd, chainId);
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed.schemaVersion !== 1 || typeof parsed.id !== 'string') {
+        throw new Error(`chain ${chainId} state is malformed (schemaVersion mismatch)`);
+    }
+    // Migrate any missing optional fields to defaults so a partially-
+    // hand-edited state file still loads.
+    const steps = Array.isArray(parsed.steps) ? parsed.steps : [];
+    if (steps.length !== CHAIN_STEP_COUNT) {
+        throw new Error(`chain ${chainId} state has ${steps.length} steps; expected ${CHAIN_STEP_COUNT}`);
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        id: parsed.id,
+        intent: parsed.intent ?? '',
+        createdAt: parsed.createdAt ?? new Date(0).toISOString(),
+        updatedAt: parsed.updatedAt ?? new Date(0).toISOString(),
+        nextStep: parsed.nextStep ?? null,
+        steps: steps.map((s) => ({
+            id: s.id,
+            status: (s.status ?? 'pending'),
+            updatedAt: s.updatedAt ?? parsed.updatedAt ?? new Date(0).toISOString(),
+            dispatchId: s.dispatchId ?? null,
+            errorMessage: s.errorMessage ?? null,
+        })),
+    });
+}
+/**
+ * List every chain id present under `.pugi/chains/`. Returns an empty
+ * array when the directory does not exist — operators rarely call this
+ * before `pugi chain new`.
+ */
+export function listChainIds(workspaceCwd) {
+    const root = join(workspaceCwd, '.pugi', 'chains');
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith('chn_'))
+        .map((entry) => entry.name)
+        .sort();
+}
+/**
+ * Mark a step as dispatched. Idempotent re-dispatch is allowed (the
+ * operator may re-run a step after a transient failure); the previous
+ * dispatchId is overwritten.
+ */
+export function markDispatched(workspaceCwd, chainId, stepId, dispatchId, options = {}) {
+    return transition(workspaceCwd, chainId, options.now ?? (() => new Date()), (state) => {
+        const step = state.steps.find((s) => s.id === stepId);
+        if (!step) {
+            throw new Error(`chain ${chainId}: unknown step ${stepId}`);
+        }
+        if (step.status === 'complete') {
+            throw new Error(`chain ${chainId}: step ${stepId} already complete`);
+        }
+        step.status = 'dispatched';
+        step.dispatchId = dispatchId;
+        step.errorMessage = null;
+    });
+}
+/**
+ * Mark a step as complete. Operator approves between steps so this is
+ * the final gate — when the operator runs `pugi chain next` AFTER the
+ * artifact lands, the dispatcher first flips the current step to
+ * complete then advances the cursor.
+ */
+export function markComplete(workspaceCwd, chainId, stepId, options = {}) {
+    return transition(workspaceCwd, chainId, options.now ?? (() => new Date()), (state) => {
+        const step = state.steps.find((s) => s.id === stepId);
+        if (!step) {
+            throw new Error(`chain ${chainId}: unknown step ${stepId}`);
+        }
+        step.status = 'complete';
+        step.errorMessage = null;
+        state.nextStep = firstPendingStep(state.steps);
+    });
+}
+/**
+ * Capture an error against the current step without flipping it to
+ * complete. The step stays in `dispatched` so the operator can re-run.
+ */
+export function markError(workspaceCwd, chainId, stepId, errorMessage, options = {}) {
+    return transition(workspaceCwd, chainId, options.now ?? (() => new Date()), (state) => {
+        const step = state.steps.find((s) => s.id === stepId);
+        if (!step) {
+            throw new Error(`chain ${chainId}: unknown step ${stepId}`);
+        }
+        step.errorMessage = errorMessage;
+    });
+}
+/**
+ * Compute the next pending step. Returns `null` when every step is
+ * complete (chain finalised).
+ */
+export function firstPendingStep(steps) {
+    for (const id of CHAIN_STEP_IDS) {
+        const record = steps.find((s) => s.id === id);
+        if (!record || record.status !== 'complete')
+            return id;
+    }
+    return null;
+}
+/**
+ * Resolve the descriptor for the current cursor. Returns `null` when
+ * the chain is finalised. Convenience wrapper so renderers do not need
+ * to handle the lookup themselves.
+ */
+export function currentStepDescriptor(state) {
+    if (!state.nextStep)
+        return null;
+    return findStep(state.nextStep) ?? null;
+}
+/* ------------------------------------------------------------------ */
+/* Internal: transactional mutate helper                              */
+/* ------------------------------------------------------------------ */
+function transition(workspaceCwd, chainId, now, mutate) {
+    const current = readChain(workspaceCwd, chainId);
+    if (!current) {
+        throw new Error(`chain ${chainId} not found at ${chainStatePath(workspaceCwd, chainId)}`);
+    }
+    // Deep clone so the frozen snapshot is never mutated.
+    const draft = JSON.parse(JSON.stringify(current));
+    mutate(draft);
+    draft.updatedAt = now().toISOString();
+    // Update step-level timestamp for whichever step the mutation
+    // touched. We diff status / dispatchId / errorMessage against the
+    // previous snapshot — any change bumps the step's updatedAt.
+    for (const draftStep of draft.steps) {
+        const previousStep = current.steps.find((s) => s.id === draftStep.id);
+        if (!previousStep)
+            continue;
+        if (draftStep.status !== previousStep.status ||
+            draftStep.dispatchId !== previousStep.dispatchId ||
+            draftStep.errorMessage !== previousStep.errorMessage) {
+            draftStep.updatedAt = draft.updatedAt;
+        }
+    }
+    writeStateAtomic(workspaceCwd, draft);
+    return Object.freeze(draft);
+}
+function writeStateAtomic(workspaceCwd, state) {
+    const dir = chainDir(workspaceCwd, state.id);
+    mkdirSync(dir, { recursive: true });
+    const finalPath = chainStatePath(workspaceCwd, state.id);
+    const tmpPath = `${finalPath}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    renameSync(tmpPath, finalPath);
+}
+//# sourceMappingURL=state.js.map

package/dist/core/artifact-chain/steps.js

@@ -0,0 +1,169 @@
+/**
+ * Artifact chain step definitions — Pugi α7 Wave 6 (2026-05-27).
+ *
+ * The chain encodes Pugi's moat: an operator drops one high-level intent
+ * (`pugi chain new "<intent>"`) and the CLI walks a deterministic 7-step
+ * pipeline that produces verifiable artifacts at each stage. Every step
+ * dispatches to a specialist persona via the existing `pugi delegate`
+ * surface so the same Tier 1 roster powers both ad-hoc dispatch and the
+ * artifact chain.
+ *
+ * The pipeline:
+ *
+ *   1. prd       — Olivia (PM):       structured PRD (goals / users /
+ *                                     acceptance criteria / scope)
+ *   2. adr       — Marcus (CTO):      architectural decision record
+ *                                     against the team ADR template
+ *   3. mindmap   — Marcus (CTO):      mermaid mindmap of the solution
+ *                                     surface (modules + boundaries)
+ *   4. er        — Hiroshi (Lead Dev):entity-relationship mermaid for
+ *                                     the data model the design implies
+ *   5. sequence  — Hiroshi (Lead Dev):mermaid sequence diagram covering
+ *                                     the critical happy + sad paths
+ *   6. tests     — Vera (QA):         spec scaffolding mapped from the
+ *                                     PRD acceptance criteria
+ *   7. code      — Hiroshi (Lead Dev):implementation diff against the
+ *                                     scaffolded specs
+ *
+ * Persona slugs are lowercase ASCII to satisfy the server-side delegate
+ * grammar (`^[a-z]+$`, mirrors `PUGI_DELEGATE_REGEX` in
+ * `apps/admin-api/src/pugi/sessions.controller.ts`). The chain never
+ * invents new personas — it only orchestrates the existing roster.
+ *
+ * Module contract:
+ *
+ *   - This file is PURE data. No fs, no network, no side effects.
+ *     Importing it from a hot path (REPL keystroke handler) is safe.
+ *   - The step ORDER is authoritative; downstream consumers MUST iterate
+ *     `CHAIN_STEPS` instead of hand-rolling their own arrays so future
+ *     re-ordering lands in exactly one place.
+ *   - Personas are looked up by slug at dispatch time so a roster change
+ *     does not silently break the chain — the dispatcher surfaces an
+ *     `unknown_persona` outcome the operator can see.
+ */
+/**
+ * Ordered, frozen table of the seven steps. The chain state machine
+ * advances through this array exactly once; re-ordering OR insertion
+ * is a breaking change for any chain currently on disk.
+ */
+export const CHAIN_STEPS = Object.freeze([
+    {
+        id: 'prd',
+        ordinal: 1,
+        persona: 'olivia',
+        personaLabel: 'Olivia (PM)',
+        artifactFilename: 'PRD.md',
+        briefTemplate: 'Produce a structured PRD for chain {{chainId}}. ' +
+            'Operator intent: "{{intent}}". ' +
+            'Cover: goals, target users, success metrics, ' +
+            'numbered acceptance criteria (## Acceptance Criteria), scope + non-scope, ' +
+            'risks. Output markdown ready for prd-check ingestion.',
+        gloss: 'Structured PRD — goals, users, acceptance criteria, scope',
+    },
+    {
+        id: 'adr',
+        ordinal: 2,
+        persona: 'marcus',
+        personaLabel: 'Marcus (CTO)',
+        artifactFilename: 'ADR.md',
+        briefTemplate: 'Produce an architectural decision record for chain {{chainId}}. ' +
+            'Read the PRD at .pugi/chains/{{chainId}}/PRD.md verbatim. ' +
+            'Follow the team ADR template: Status, Context, Decision, ' +
+            'Consequences, Alternatives Considered. ' +
+            'Be explicit about boundary changes the decision implies.',
+        gloss: 'Architectural decision record per team ADR template',
+    },
+    {
+        id: 'mindmap',
+        ordinal: 3,
+        persona: 'marcus',
+        personaLabel: 'Marcus (CTO)',
+        artifactFilename: 'MINDMAP.mmd',
+        briefTemplate: 'Produce a mermaid mindmap of the solution surface for chain {{chainId}}. ' +
+            'Read PRD + ADR at .pugi/chains/{{chainId}}/PRD.md and ADR.md. ' +
+            'Root node = the feature name; first-level branches = subsystems; ' +
+            'leaves = concrete modules / endpoints / tables. ' +
+            'Output ONE mermaid `mindmap` fenced block — no prose.',
+        gloss: 'Mermaid mindmap — solution surface (subsystems + modules)',
+    },
+    {
+        id: 'er',
+        ordinal: 4,
+        persona: 'hiroshi',
+        personaLabel: 'Hiroshi (Lead Dev)',
+        artifactFilename: 'ER.mmd',
+        briefTemplate: 'Produce a mermaid entity-relationship diagram for chain {{chainId}}. ' +
+            'Source: PRD + ADR + MINDMAP under .pugi/chains/{{chainId}}/. ' +
+            'Use `erDiagram` syntax. Cover every persisted entity the ' +
+            'design implies; mark PK / FK relationships explicitly.',
+        gloss: 'Mermaid ER diagram — persisted entities + relationships',
+    },
+    {
+        id: 'sequence',
+        ordinal: 5,
+        persona: 'hiroshi',
+        personaLabel: 'Hiroshi (Lead Dev)',
+        artifactFilename: 'SEQUENCE.mmd',
+        briefTemplate: 'Produce mermaid sequence diagrams for chain {{chainId}}. ' +
+            'Cover the critical happy path + at least one sad path. ' +
+            'Source: PRD acceptance criteria + ER diagram. ' +
+            'Use `sequenceDiagram` syntax; one diagram per fenced block.',
+        gloss: 'Mermaid sequence diagrams — happy + sad path flows',
+    },
+    {
+        id: 'tests',
+        ordinal: 6,
+        persona: 'vera',
+        personaLabel: 'Vera (QA)',
+        artifactFilename: 'TESTS.md',
+        briefTemplate: 'Produce spec scaffolding for chain {{chainId}}. ' +
+            'Map every numbered PRD acceptance criterion (under ## Acceptance Criteria) ' +
+            'to one or more concrete test descriptions using node:test + node:assert. ' +
+            'Format: criterion-id → test file path → `it(...)` blocks. ' +
+            'Output markdown only — no executable code.',
+        gloss: 'Spec scaffolding — PRD criteria mapped to test descriptions',
+    },
+    {
+        id: 'code',
+        ordinal: 7,
+        persona: 'hiroshi',
+        personaLabel: 'Hiroshi (Lead Dev)',
+        artifactFilename: 'CODE.md',
+        briefTemplate: 'Produce an implementation plan + diff references for chain {{chainId}}. ' +
+            'Read PRD, ADR, MINDMAP, ER, SEQUENCE, TESTS under .pugi/chains/{{chainId}}/. ' +
+            'Output: file-by-file changes (path, change kind, summary), ' +
+            'with each change tied back to a PRD criterion id. ' +
+            'NO inline patches — patches land via `pugi patch apply` after operator review.',
+        gloss: 'Implementation plan — file changes mapped to PRD criteria',
+    },
+]);
+/**
+ * Resolve a step descriptor by id. Returns `undefined` for unknown ids
+ * so callers can surface a structured error instead of panicking.
+ */
+export function findStep(id) {
+    return CHAIN_STEPS.find((step) => step.id === id);
+}
+/**
+ * Index of step ids in chain order. Exported so the state machine can
+ * answer "what is the next step after X?" without re-scanning the
+ * table on every transition.
+ */
+export const CHAIN_STEP_IDS = Object.freeze(CHAIN_STEPS.map((s) => s.id));
+/**
+ * Total number of steps in the chain. Hard-coded constant exported so
+ * downstream renderers can size their progress bars without iterating.
+ */
+export const CHAIN_STEP_COUNT = CHAIN_STEPS.length;
+/**
+ * Interpolate the brief template with chain context. The template
+ * grammar is intentionally minimal — only `{{chainId}}` and `{{intent}}`
+ * are honoured. Unknown placeholders are left verbatim so a template
+ * typo surfaces in the dispatched brief instead of silently dropping.
+ */
+export function renderBrief(template, ctx) {
+    return template
+        .replace(/\{\{chainId\}\}/g, ctx.chainId)
+        .replace(/\{\{intent\}\}/g, ctx.intent);
+}
+//# sourceMappingURL=steps.js.map

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