@pugi/cli 0.1.0-beta.10 → 0.1.0-beta.101

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

@@ -0,0 +1,169 @@
+/**
+ * Artifact chain step definitions — Pugi  .
+ *
+ * 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/ask-user/question.js

@@ -0,0 +1,92 @@
+const MIN_QUESTIONS = 1;
+const MAX_QUESTIONS = 4;
+const MIN_OPTIONS = 2;
+const MAX_OPTIONS = 4;
+const MAX_HEADER_LENGTH = 12;
+export function validateBatch(batch) {
+    const errors = [];
+    if (!Array.isArray(batch.questions)) {
+        errors.push({
+            field: 'questions',
+            message: 'questions must be an array',
+        });
+        return errors;
+    }
+    if (batch.questions.length < MIN_QUESTIONS || batch.questions.length > MAX_QUESTIONS) {
+        errors.push({
+            field: 'questions',
+            message: 'questions must contain 1 to 4 items',
+        });
+    }
+    for (const [questionIndex, question] of batch.questions.entries()) {
+        const questionPath = `questions[${questionIndex}]`;
+        if (typeof question.question !== 'string' || !question.question.endsWith('?')) {
+            errors.push({
+                field: `${questionPath}.question`,
+                message: 'question must end with ?',
+            });
+        }
+        if (typeof question.header !== 'string' || question.header.length < 1 || question.header.length > MAX_HEADER_LENGTH) {
+            errors.push({
+                field: `${questionPath}.header`,
+                message: 'header must be 1 to 12 characters',
+            });
+        }
+        if (typeof question.multiSelect !== 'boolean') {
+            errors.push({
+                field: `${questionPath}.multiSelect`,
+                message: 'multiSelect must be a boolean',
+            });
+        }
+        if (!Array.isArray(question.options)) {
+            errors.push({
+                field: `${questionPath}.options`,
+                message: 'options must be an array',
+            });
+            continue;
+        }
+        if (question.options.length < MIN_OPTIONS || question.options.length > MAX_OPTIONS) {
+            errors.push({
+                field: `${questionPath}.options`,
+                message: 'options must contain 2 to 4 items',
+            });
+        }
+        for (const [optionIndex, option] of question.options.entries()) {
+            const optionPath = `${questionPath}.options[${optionIndex}]`;
+            if (typeof option.label !== 'string' || option.label.length < 1) {
+                errors.push({
+                    field: `${optionPath}.label`,
+                    message: 'label must be a non-empty string',
+                });
+            }
+            if (typeof option.description !== 'string' || option.description.length < 1) {
+                errors.push({
+                    field: `${optionPath}.description`,
+                    message: 'description must be a non-empty string',
+                });
+            }
+            if (option.preview !== undefined && (typeof option.preview !== 'string' || option.preview.length < 1)) {
+                errors.push({
+                    field: `${optionPath}.preview`,
+                    message: 'preview must be a non-empty string when set',
+                });
+            }
+            if (option.recommended !== undefined && typeof option.recommended !== 'boolean') {
+                errors.push({
+                    field: `${optionPath}.recommended`,
+                    message: 'recommended must be a boolean when set',
+                });
+            }
+        }
+    }
+    return errors;
+}
+export function formatHeader(header) {
+    if (header.length <= MAX_HEADER_LENGTH)
+        return header;
+    return `${header.slice(0, MAX_HEADER_LENGTH - 3)}...`;
+}
+export function findRecommended(options) {
+    return options.find(option => option.recommended === true) ?? null;
+}
+//# sourceMappingURL=question.js.map

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