@jevitate/cli 0.1.0 → 0.3.0

package/dist/journey-prefix.d.ts

@@ -0,0 +1,194 @@
+import { type JourneyBranchPoint } from "@jevitate/journey";
+import { type Actor } from "@jevitate/screenplay";
+import type { Recording } from "@jevitate/recording";
+import type { BrowserSession } from "@jevitate/playwright";
+import { type ResolvedJourneyEnvironment } from "./environments.js";
+import type { BrowserRunOptions } from "./browser-run-options.js";
+/**
+ * #293 — journey-anchored exploration: `jevitate explore --from-journey <id> --at-step <n|name>`.
+ *
+ * The mission's browser session opens as usual (its storage state, emulation, demo mode); then the
+ * promoted Journey's PREFIX — its first `step` top-level steps — is replayed INTO that session by the
+ * one Journey replay there is (`runJourneyProgrammatically`: fail-closed, never self-healing, the
+ * site policy and `--env` environment applied), and the mission starts on the live page it left:
+ * same page, form contents and session, no fresh navigation. A prefix that no longer replays ends
+ * the run with a typed `journey-stale` outcome (exit 2) — never a silent restart from a URL.
+ *
+ * Everything that can be refused is refused before any browser opens (`resolveJourneyPrefix`): an
+ * unknown or unpromoted Journey, a step or anchor it does not have, params that do not fit, a
+ * Journey that needs a session the run was not given.
+ */
+/** The strategies a mission can branch off a Journey with (`--feature` and multi-runs are refused). */
+export { ANCHORED_STRATEGIES, type AnchoredStrategy } from "@jevitate/journey";
+/** `--from-journey`/`--at-step` cannot be used as given (exit 64, nothing ran). */
+export declare class JourneyPrefixArgsError extends Error {
+    readonly code: "E_EXPLORE_ARGS";
+    constructor(message: string);
+}
+/**
+ * The Journey prefix did not replay up to the anchor: the Journey is stale (a step's target is gone,
+ * the app changed). The run ends `inconclusive` with `failure.kind: "journey-stale"` (exit 2).
+ */
+export declare class JourneyPrefixStaleError extends Error {
+    readonly branch: JourneyBranchPoint;
+    /** The 1-based Journey step that failed, when the replay names it. */
+    readonly failedStep?: number | undefined;
+    readonly code: "E_JOURNEY_STALE";
+    constructor(message: string, branch: JourneyBranchPoint, 
+    /** The 1-based Journey step that failed, when the replay names it. */
+    failedStep?: number | undefined);
+}
+export interface JourneyPrefix {
+    readonly branch: JourneyBranchPoint;
+    /**
+     * Where the prefix is expected to land, from the Recording alone (on the environment's origin) —
+     * the run's origin, allowlist and per-target settings are decided from it before any browser
+     * opens. The mission itself starts from the LIVE page URL the replay leaves.
+     */
+    readonly startUrl: string;
+    /** The origins the Journey's steps may be on: the environment's, else the Journey's own site. */
+    readonly allowedOrigins: readonly string[];
+    /**
+     * The values of the prefix's SECRET params (declared `secret: true`, or credential-like names): the
+     * replay types them into the page the mission then perceives, so the mission must redact them.
+     */
+    readonly secrets: readonly string[];
+    /** Top-level steps the prefix replays: what one re-replay on a reset costs against `maxActions`. */
+    readonly steps: number;
+    /**
+     * What a later replay of a finding needs to go through the same prefix (persisted on the result
+     * as `branch.replay`): never a secret param's value — only its name, re-supplied as `--param`.
+     */
+    readonly replayInfo: BranchReplayInfo;
+    /**
+     * Replays the prefix into `session` (left open) and returns the live URL the mission starts on.
+     * `browser` is how the run launched (a Journey recorded with extensions needs the same build).
+     * Throws `JourneyPrefixStaleError` when the replay stops before the anchor.
+     */
+    replay(session: BrowserSession, browser?: BrowserRunOptions): Promise<string>;
+}
+export interface ResolveJourneyPrefixOptions {
+    /** The Journey store directory. */
+    readonly dir: string;
+    readonly id: string;
+    /** `--at-step`: a 1-based step number or an anchor name. */
+    readonly atStep: string;
+    readonly params: Record<string, string>;
+    /** `--env`/`--base-url` (#247): the Journey's recorded URLs move onto this environment. */
+    readonly environment?: ResolvedJourneyEnvironment;
+    /** The mission's session file (also checked against the Journey's `requiresAuth`). */
+    readonly storageState?: string;
+    /** The site-policy database (`jevitate site policy`): pacing and budgets apply to the replay. */
+    readonly dbPath?: string;
+    /** The `--env`/`--base-url` names `environment` came from (persisted for later replays). */
+    readonly environmentFlags?: {
+        readonly env?: string;
+        readonly baseUrl?: string;
+    };
+}
+/** #293: how a finding's replay goes back through its run's Journey prefix (`result.branch.replay`). */
+export interface BranchReplayInfo {
+    /** The Journey store the prefix was read from (absolute). */
+    readonly journeysDir: string;
+    /** The prefix's NON-secret params, by value. */
+    readonly params: Readonly<Record<string, string>>;
+    /** The prefix's secret params, by NAME only: a replay is given them again (`--param`). */
+    readonly secretParams: readonly string[];
+    readonly env?: string;
+    readonly baseUrl?: string;
+}
+/** A result's `branch`, as an anchored run persists it (#293): the branch point plus how to replay it. */
+export type RecordedBranch = JourneyBranchPoint & {
+    readonly replay?: BranchReplayInfo;
+};
+/**
+ * Resolves `--from-journey <id> --at-step <n|name>` into a replayable prefix — refusing, before any
+ * browser opens, an unknown Journey (`UnknownJourneyError`), an unpromoted one or a step it lacks
+ * (`JourneyPrefixArgsError`), params that do not fit (`ParamValidationError`), and a Journey that
+ * declares `requiresAuth` with no session (`JourneyRequiresAuthError`).
+ */
+export declare function resolveJourneyPrefix(opts: ResolveJourneyPrefixOptions): Promise<JourneyPrefix>;
+/** What an anchored run starts from: the live URL after the prefix, its branch point, and how it resets. */
+export interface AnchoredStart {
+    readonly url: string;
+    readonly branch?: RecordedBranch;
+    /**
+     * #293: what a reset inside the mission uses instead of re-navigating to the anchor URL — the
+     * prefix replayed again into the mission's (current) session, costing `restartCost` actions.
+     */
+    readonly restart?: {
+        readonly restartAtStart: (actor: Actor) => Promise<boolean>;
+        readonly restartCost: number;
+    };
+}
+/**
+ * #293: a reset's prefix re-replay — into the actor's current session; `false` (never a throw) when
+ * the prefix no longer replays or lands off the allowlist, so the mission stops there honestly.
+ */
+export declare function prefixRestart(prefix: JourneyPrefix, allowlist: readonly string[], browser?: BrowserRunOptions): (actor: Actor) => Promise<boolean>;
+/**
+ * The runners' one call (#293): with no prefix, the mission starts at `url` as always; with one, the
+ * prefix is replayed into `session` and the mission starts on the live page it left — which must
+ * still be an authorized origin (`UnauthorizedExploreTargetError` otherwise).
+ */
+export declare function startFromJourney(prefix: JourneyPrefix | undefined, session: BrowserSession, url: string, allowlist: readonly string[], browser?: BrowserRunOptions): Promise<AnchoredStart>;
+/** The result fields an anchored run adds (#293, additive): its branch point (and how to replay it). */
+export declare function branchFields(start: AnchoredStart): {
+    branch?: RecordedBranch;
+};
+/** The typed result of a run whose prefix did not replay (exit 2): `inconclusive`, `failure.kind: "journey-stale"`. */
+export interface JourneyStaleResult {
+    readonly strategy: string;
+    readonly outcome: "inconclusive";
+    readonly missionOutcome: "inconclusive";
+    readonly reason: string;
+    readonly failure: {
+        readonly kind: "journey-stale";
+        readonly message: string;
+    };
+    readonly branch: JourneyBranchPoint;
+    /** The 1-based Journey step whose replay failed, when known. */
+    readonly failedStep?: number;
+    readonly exitCode: 2;
+}
+export declare function journeyStaleResult(err: JourneyPrefixStaleError, strategy: string): JourneyStaleResult;
+/** A finding's result names a branch point it was found from (with how to replay through it). */
+export declare function recordedBranchOf(result: unknown): RecordedBranch | undefined;
+/** `verify-fix`/`regression` of a branch-point finding cannot replay through its prefix (exit 64). */
+export declare class BranchReplayInputError extends Error {
+    readonly code: "E_VERIFY_FIX_INPUT";
+    constructor(message: string);
+}
+export interface PrefixFromBranchOptions {
+    /** `--param` values: the branch's secret params (by name), or overrides of its recorded ones. */
+    readonly params?: Readonly<Record<string, string>>;
+    readonly storageState?: string;
+    readonly dbPath?: string;
+    readonly environmentSeams?: {
+        readonly environmentsFile?: string;
+        readonly targetsFile?: string;
+    };
+}
+/**
+ * The Journey prefix a finding's run branched from, resolved again from `branch.replay` (the
+ * Journey store, its non-secret params, the environment) — a secret param must be given again.
+ * Refused (`BranchReplayInputError`) when the result predates replay info or a secret is missing.
+ */
+export declare function prefixFromBranch(branch: RecordedBranch, opts?: PrefixFromBranchOptions): Promise<JourneyPrefix>;
+/**
+ * A branch-point finding's Recording, for a replay that starts on the prefix's live page: its
+ * leading navigate to the anchor URL (which would reload the page and lose in-page state) becomes
+ * an `assert urlIncludes <path>` — the same flat step indices, so `recordingStepIndex` still holds.
+ */
+export declare function anchoredRecording(rec: Recording): Recording;
+/**
+ * Wraps a fresh-session opener so every replay session first goes through the Journey prefix.
+ * A stale prefix is remembered (`stale()`), and the opener throws — the replay then has no evidence,
+ * and the caller reports a typed `journey-stale` inconclusive.
+ */
+export declare function prefixedOpener<S extends {
+    readonly actor: Actor;
+}>(open: () => Promise<S>, prefix: JourneyPrefix, allowlist: readonly string[], browser?: BrowserRunOptions): {
+    open: () => Promise<S>;
+    stale: () => JourneyPrefixStaleError | undefined;
+};

package/dist/journey-prefix.js

@@ -0,0 +1,279 @@
+import { FsJourneyStore, JourneyRegistry, JourneyStepError, deriveParamSchema, journeyBranchPoint, journeyPrefix, prefixLandingPath, resolveJourneyStep, secretParamNames, secretParamValues, validateParams, } from "@jevitate/journey";
+import { resolve as resolvePath } from "node:path";
+import { UnauthorizedExploreTargetError, assertAuthorizedExploreTarget } from "@jevitate/explore";
+import { BrowseTheWebToken } from "@jevitate/screenplay";
+import { SiteGateRefusedError } from "@jevitate/runtime";
+import { applyJourneyEnvironment, environmentFromFlags } from "./environments.js";
+import { JourneyRequiresAuthError, UnknownJourneyError, prefixParams, runJourneyProgrammatically } from "./journey-api.js";
+import { withSiteGate } from "./site-gate-cli.js";
+/**
+ * #293 — journey-anchored exploration: `jevitate explore --from-journey <id> --at-step <n|name>`.
+ *
+ * The mission's browser session opens as usual (its storage state, emulation, demo mode); then the
+ * promoted Journey's PREFIX — its first `step` top-level steps — is replayed INTO that session by the
+ * one Journey replay there is (`runJourneyProgrammatically`: fail-closed, never self-healing, the
+ * site policy and `--env` environment applied), and the mission starts on the live page it left:
+ * same page, form contents and session, no fresh navigation. A prefix that no longer replays ends
+ * the run with a typed `journey-stale` outcome (exit 2) — never a silent restart from a URL.
+ *
+ * Everything that can be refused is refused before any browser opens (`resolveJourneyPrefix`): an
+ * unknown or unpromoted Journey, a step or anchor it does not have, params that do not fit, a
+ * Journey that needs a session the run was not given.
+ */
+/** The strategies a mission can branch off a Journey with (`--feature` and multi-runs are refused). */
+export { ANCHORED_STRATEGIES } from "@jevitate/journey";
+/** `--from-journey`/`--at-step` cannot be used as given (exit 64, nothing ran). */
+export class JourneyPrefixArgsError extends Error {
+    code = "E_EXPLORE_ARGS";
+    constructor(message) {
+        super(message);
+        this.name = "JourneyPrefixArgsError";
+    }
+}
+/**
+ * The Journey prefix did not replay up to the anchor: the Journey is stale (a step's target is gone,
+ * the app changed). The run ends `inconclusive` with `failure.kind: "journey-stale"` (exit 2).
+ */
+export class JourneyPrefixStaleError extends Error {
+    branch;
+    failedStep;
+    code = "E_JOURNEY_STALE";
+    constructor(message, branch, 
+    /** The 1-based Journey step that failed, when the replay names it. */
+    failedStep) {
+        super(message);
+        this.branch = branch;
+        this.failedStep = failedStep;
+        this.name = "JourneyPrefixStaleError";
+    }
+}
+/**
+ * Resolves `--from-journey <id> --at-step <n|name>` into a replayable prefix — refusing, before any
+ * browser opens, an unknown Journey (`UnknownJourneyError`), an unpromoted one or a step it lacks
+ * (`JourneyPrefixArgsError`), params that do not fit (`ParamValidationError`), and a Journey that
+ * declares `requiresAuth` with no session (`JourneyRequiresAuthError`).
+ */
+export async function resolveJourneyPrefix(opts) {
+    const stored = await new JourneyRegistry(new FsJourneyStore(opts.dir)).get(opts.id);
+    if (stored === null)
+        throw new UnknownJourneyError(`unknown journey '${opts.id}'`);
+    if (!stored.metadata.promoted) {
+        throw new JourneyPrefixArgsError(`journey '${opts.id}' is not promoted — missions branch only off promoted Journeys (a person promotes it: jevitate journey promote ${opts.id})`);
+    }
+    const full = applyJourneyEnvironment(stored, opts.environment);
+    let resolved;
+    try {
+        resolved = resolveJourneyStep(full, opts.atStep);
+    }
+    catch (err) {
+        if (err instanceof JourneyStepError)
+            throw new JourneyPrefixArgsError(err.message);
+        throw err;
+    }
+    if (full.metadata.requiresAuth === true && opts.storageState === undefined) {
+        throw new JourneyRequiresAuthError(`journey '${opts.id}' requires auth (metadata.requiresAuth) — run with --storage-state <file>`);
+    }
+    const prefix = journeyPrefix(full, resolved.step);
+    const used = prefixParams(full, prefix, opts.params);
+    validateParams(deriveParamSchema(prefix.recording), used);
+    const branch = journeyBranchPoint(full, resolved);
+    const site = full.recording.site;
+    let startUrl;
+    try {
+        startUrl = new URL(prefixLandingPath(full, resolved.step), site).href;
+    }
+    catch {
+        throw new JourneyPrefixArgsError(`journey '${opts.id}' has no usable site URL (${JSON.stringify(site)})`);
+    }
+    const allowedOrigins = opts.environment === undefined ? [new URL(site).origin] : [...opts.environment.allowedOrigins];
+    const where = `step ${branch.step}${branch.anchor === undefined ? "" : ` (anchor ${branch.anchor})`}`;
+    const secretNames = secretParamNames(full, used).filter((n) => n in used);
+    return {
+        branch,
+        startUrl,
+        allowedOrigins,
+        secrets: secretParamValues(full, used),
+        steps: resolved.step,
+        replayInfo: {
+            journeysDir: resolvePath(opts.dir),
+            params: Object.fromEntries(Object.entries(used).filter(([k]) => !secretNames.includes(k))),
+            secretParams: secretNames,
+            ...(opts.environmentFlags?.env === undefined ? {} : { env: opts.environmentFlags.env }),
+            ...(opts.environmentFlags?.baseUrl === undefined ? {} : { baseUrl: opts.environmentFlags.baseUrl }),
+        },
+        replay: async (session, browser) => {
+            let run;
+            try {
+                run = await withSiteGate(opts.dbPath, (siteGate) => runJourneyProgrammatically({
+                    dir: opts.dir,
+                    id: opts.id,
+                    params: opts.params,
+                    session,
+                    stopAfterStep: resolved.step,
+                    ...(siteGate === undefined ? {} : { siteGate }),
+                    ...(opts.environment === undefined ? {} : { environment: opts.environment }),
+                    ...(opts.storageState === undefined ? {} : { storageState: opts.storageState }),
+                    ...(browser === undefined ? {} : { browser }),
+                }));
+            }
+            catch (err) {
+                // The site policy's own refusal keeps its code; anything else that stopped the replay means
+                // the Journey did not reach its anchor — typed, never a restart from a URL.
+                if (err instanceof SiteGateRefusedError)
+                    throw err;
+                const message = err instanceof Error ? (err.message.split("\n")[0] ?? err.message) : String(err);
+                throw new JourneyPrefixStaleError(`journey '${opts.id}' did not replay to ${where}: ${message}`, branch);
+            }
+            if (run.outcome !== "ok") {
+                const failed = run.outcome === "quarantined" && run.at !== undefined ? run.at + 1 : undefined;
+                const reason = run.outcome === "quarantined" ? run.reason : "the replay healed a step (a self-healed prefix is never a branch point)";
+                throw new JourneyPrefixStaleError(`journey '${opts.id}' is stale: it no longer reaches ${where} — ${reason}`, branch, failed);
+            }
+            return session.page.url();
+        },
+    };
+}
+/**
+ * #293: a reset's prefix re-replay — into the actor's current session; `false` (never a throw) when
+ * the prefix no longer replays or lands off the allowlist, so the mission stops there honestly.
+ */
+export function prefixRestart(prefix, allowlist, browser) {
+    return async (actor) => {
+        try {
+            const live = await prefix.replay(actor.ability(BrowseTheWebToken).session, browser);
+            assertAuthorizedExploreTarget(live, allowlist);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof JourneyPrefixStaleError || err instanceof UnauthorizedExploreTargetError)
+                return false;
+            throw err;
+        }
+    };
+}
+/**
+ * The runners' one call (#293): with no prefix, the mission starts at `url` as always; with one, the
+ * prefix is replayed into `session` and the mission starts on the live page it left — which must
+ * still be an authorized origin (`UnauthorizedExploreTargetError` otherwise).
+ */
+export async function startFromJourney(prefix, session, url, allowlist, browser) {
+    if (prefix === undefined)
+        return { url };
+    const live = await prefix.replay(session, browser);
+    assertAuthorizedExploreTarget(live, allowlist);
+    const restart = { restartAtStart: prefixRestart(prefix, allowlist, browser), restartCost: prefix.steps };
+    return { url: live, branch: { ...prefix.branch, replay: prefix.replayInfo }, restart };
+}
+/** The result fields an anchored run adds (#293, additive): its branch point (and how to replay it). */
+export function branchFields(start) {
+    return start.branch === undefined ? {} : { branch: start.branch };
+}
+export function journeyStaleResult(err, strategy) {
+    return {
+        strategy,
+        outcome: "inconclusive",
+        missionOutcome: "inconclusive",
+        reason: err.message,
+        failure: { kind: "journey-stale", message: err.message },
+        branch: err.branch,
+        ...(err.failedStep === undefined ? {} : { failedStep: err.failedStep }),
+        exitCode: 2,
+    };
+}
+// ── Replaying a finding through its branch point (#293) ─────────────────────────────────────────
+/** A finding's result names a branch point it was found from (with how to replay through it). */
+export function recordedBranchOf(result) {
+    const b = result?.branch;
+    if (b === null || typeof b !== "object")
+        return undefined;
+    const r = b;
+    if (typeof r.journeyId !== "string" || typeof r.step !== "number")
+        return undefined;
+    return r;
+}
+/** `verify-fix`/`regression` of a branch-point finding cannot replay through its prefix (exit 64). */
+export class BranchReplayInputError extends Error {
+    code = "E_VERIFY_FIX_INPUT";
+    constructor(message) {
+        super(message);
+        this.name = "BranchReplayInputError";
+    }
+}
+/**
+ * The Journey prefix a finding's run branched from, resolved again from `branch.replay` (the
+ * Journey store, its non-secret params, the environment) — a secret param must be given again.
+ * Refused (`BranchReplayInputError`) when the result predates replay info or a secret is missing.
+ */
+export async function prefixFromBranch(branch, opts = {}) {
+    const info = branch.replay;
+    if (info === undefined)
+        throw new BranchReplayInputError(`the finding branched from journey '${branch.journeyId}' step ${branch.step}, but its result records no replay info — re-run the anchored mission`);
+    const params = { ...info.params, ...(opts.params ?? {}) };
+    const missing = info.secretParams.filter((n) => !(n in params));
+    if (missing.length > 0) {
+        throw new BranchReplayInputError(`the finding's Journey prefix types secret param(s) ${missing.join(", ")}: give them again with --param <name>=<value>`);
+    }
+    try {
+        const environment = environmentFromFlags({ ...(info.env === undefined ? {} : { env: info.env }), ...(info.baseUrl === undefined ? {} : { baseUrl: info.baseUrl }) }, opts.environmentSeams ?? {});
+        return await resolveJourneyPrefix({
+            dir: info.journeysDir,
+            id: branch.journeyId,
+            atStep: String(branch.step),
+            params,
+            ...(environment === undefined ? {} : { environment }),
+            ...(opts.storageState === undefined ? {} : { storageState: opts.storageState }),
+            ...(opts.dbPath === undefined ? {} : { dbPath: opts.dbPath }),
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && !(err instanceof JourneyPrefixStaleError))
+            throw new BranchReplayInputError(`cannot replay through journey '${branch.journeyId}' step ${branch.step}: ${err.message}`);
+        throw err;
+    }
+}
+/**
+ * A branch-point finding's Recording, for a replay that starts on the prefix's live page: its
+ * leading navigate to the anchor URL (which would reload the page and lose in-page state) becomes
+ * an `assert urlIncludes <path>` — the same flat step indices, so `recordingStepIndex` still holds.
+ */
+export function anchoredRecording(rec) {
+    const first = rec.pages[0]?.steps[0];
+    if (first === undefined || first.step.kind !== "navigate")
+        return rec;
+    let path;
+    try {
+        path = new URL(first.step.url, rec.site).pathname;
+    }
+    catch {
+        path = first.step.url;
+    }
+    const replaced = { step: { kind: "assert", label: "the Journey prefix reached the anchor", check: { kind: "urlIncludes", text: path } } };
+    const [page0, ...rest] = rec.pages;
+    return { ...rec, pages: [{ ...page0, steps: [replaced, ...page0.steps.slice(1)] }, ...rest] };
+}
+/**
+ * Wraps a fresh-session opener so every replay session first goes through the Journey prefix.
+ * A stale prefix is remembered (`stale()`), and the opener throws — the replay then has no evidence,
+ * and the caller reports a typed `journey-stale` inconclusive.
+ */
+export function prefixedOpener(open, prefix, allowlist, browser) {
+    let stale;
+    return {
+        stale: () => stale,
+        open: async () => {
+            const s = await open();
+            try {
+                const live = await prefix.replay(s.actor.ability(BrowseTheWebToken).session, browser);
+                assertAuthorizedExploreTarget(live, allowlist);
+            }
+            catch (err) {
+                if (err instanceof JourneyPrefixStaleError)
+                    stale ??= err;
+                await s.close?.();
+                throw err;
+            }
+            return s;
+        },
+    };
+}
+//# sourceMappingURL=journey-prefix.js.map

package/dist/journey-prefix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey-prefix.js","sourceRoot":"","sources":["../src/journey-prefix.ts"],"names":[],"mappings":"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"}

package/dist/key-report.d.ts

@@ -0,0 +1,49 @@
+import { type CredentialKey, type CredentialStore, type Feature, type KeyVerdict, type VerifyFetch } from "@jevitate/ai-core";
+/**
+ * Key provenance + live verification for `init`, `ai status` and `ai setup` (#268, #291). Names,
+ * providers, sources and verdicts only — no function here returns, prints or logs a key value.
+ */
+/** Where one required key comes from (`--json`: `keys[feature].sources`, additive). */
+export interface KeySourceReport {
+    readonly key: CredentialKey;
+    readonly provider: string;
+    readonly source: "env" | "file" | "missing";
+    /** The env var the value is read from (the key's own name, or an accepted alias). */
+    readonly envVar?: string;
+    /** The credentials file (`~/.jevitate/credentials.json`). */
+    readonly path?: string;
+    /** An env var is set AND the file holds the key: the env value wins (the stored one is unused). */
+    readonly shadowsStored?: true;
+}
+/** One key's live check (`--json`: `verification`, additive). */
+export interface KeyVerificationReport {
+    readonly key: CredentialKey;
+    readonly provider: string;
+    readonly status: KeyVerdict["status"];
+    readonly httpStatus?: number;
+    readonly reason?: string;
+    /** The value looks like another provider's key (a key stored in the wrong slot). */
+    readonly looksLike?: CredentialKey;
+}
+/** `~/.jevitate/credentials.json` — the file path with the home directory abbreviated. */
+export declare function displayCredentialsPath(): string;
+export declare function keySources(feature: Feature, env: Record<string, string | undefined>, localConfig: Partial<Record<CredentialKey, string>>): KeySourceReport[];
+/** The default verifier: one HTTPS GET with the key in the Authorization header. */
+export declare const realVerifyFetch: VerifyFetch;
+/** Verifies every required key of `feature` (the effective value: env wins). `known` skips a re-check. */
+export declare function verifyFeatureKeys(feature: Feature, store: CredentialStore, fetchFn: VerifyFetch, known?: ReadonlyMap<CredentialKey, KeyVerdict>): Promise<KeyVerificationReport[]>;
+/** `OPENROUTER_API_KEY (OpenRouter), from env OPENROUTER_API_KEY` / `…, from ~/.jevitate/credentials.json`. */
+export declare function describeSource(s: KeySourceReport): string;
+/** One verification as a human phrase (never a value). */
+export declare function describeVerification(v: KeyVerificationReport): string;
+/** A feature's key state without its name: `ready — <sources>: <verdicts>` or `missing <names> — …`. */
+export declare function featureKeysBody(feature: Feature, sources: readonly KeySourceReport[], verification: readonly KeyVerificationReport[] | undefined): string;
+/** A feature's whole key line (`ai status`): `generation: ready — OPENROUTER_API_KEY (OpenRouter), from env …: valid`. */
+export declare function describeFeatureKeys(feature: Feature, sources: readonly KeySourceReport[], verification: readonly KeyVerificationReport[] | undefined): string;
+/** Any verification that is not a pass (invalid or unreachable). */
+export declare function verificationProblems(verification: readonly KeyVerificationReport[]): {
+    invalid: KeyVerificationReport[];
+    unreachable: KeyVerificationReport[];
+};
+/** Env vars that shadow a key just stored (the stored value is unused while they are set). */
+export declare function shadowWarnings(collected: readonly CredentialKey[], sources: readonly KeySourceReport[]): string[];

package/dist/key-report.js

@@ -0,0 +1,101 @@
+import { homedir } from "node:os";
+import { FEATURE_KEYS, KEY_PROVIDERS, credentialProvenance, describeVerdict, looksLikeOtherKey, verifyKey, } from "@jevitate/ai-core";
+import { credentialsFilePath } from "./credentials-file.js";
+/** `~/.jevitate/credentials.json` — the file path with the home directory abbreviated. */
+export function displayCredentialsPath() {
+    const p = credentialsFilePath();
+    const home = homedir();
+    return home !== "" && p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+export function keySources(feature, env, localConfig) {
+    return FEATURE_KEYS[feature].map((key) => {
+        const p = credentialProvenance(key, env, localConfig);
+        const base = { key, provider: p.provider };
+        if (p.source.kind === "env")
+            return { ...base, source: "env", envVar: p.source.envVar, ...(p.shadowsStored ? { shadowsStored: true } : {}) };
+        if (p.source.kind === "file")
+            return { ...base, source: "file", path: displayCredentialsPath() };
+        return { ...base, source: "missing" };
+    });
+}
+/** The default verifier: one HTTPS GET with the key in the Authorization header. */
+export const realVerifyFetch = async (url, init) => {
+    const res = await fetch(url, { method: init.method, headers: init.headers, signal: init.signal });
+    // The body is never read (it may describe the key); only the status decides.
+    await res.body?.cancel().catch(() => undefined);
+    return { status: res.status };
+};
+/** Verifies every required key of `feature` (the effective value: env wins). `known` skips a re-check. */
+export async function verifyFeatureKeys(feature, store, fetchFn, known = new Map()) {
+    const out = [];
+    for (const key of FEATURE_KEYS[feature]) {
+        const value = store.read(key);
+        const verdict = value === undefined ? { status: "missing" } : (known.get(key) ?? (await verifyKey(key, value, fetchFn)));
+        const other = value === undefined || verdict.status === "valid" ? null : looksLikeOtherKey(key, value);
+        out.push({
+            key,
+            provider: KEY_PROVIDERS[key],
+            status: verdict.status,
+            ...(verdict.status === "invalid" ? { httpStatus: verdict.httpStatus } : {}),
+            ...(verdict.status === "unreachable" ? { reason: verdict.reason } : {}),
+            ...(other === null ? {} : { looksLike: other }),
+        });
+    }
+    return out;
+}
+function verdictOf(v) {
+    if (v.status === "invalid")
+        return { status: "invalid", httpStatus: v.httpStatus ?? 0 };
+    if (v.status === "unreachable")
+        return { status: "unreachable", reason: v.reason ?? "unknown" };
+    return { status: v.status };
+}
+/** `OPENROUTER_API_KEY (OpenRouter), from env OPENROUTER_API_KEY` / `…, from ~/.jevitate/credentials.json`. */
+export function describeSource(s) {
+    const name = `${s.key} (${s.provider})`;
+    if (s.source === "env") {
+        return `${name}, from env ${s.envVar ?? s.key}${s.shadowsStored === true ? ` (overrides the key stored in ${displayCredentialsPath()})` : ""}`;
+    }
+    if (s.source === "file")
+        return `${name}, from ${s.path ?? displayCredentialsPath()}`;
+    return `${name} missing`;
+}
+/** One verification as a human phrase (never a value). */
+export function describeVerification(v) {
+    const other = v.looksLike === undefined ? "" : KEY_PROVIDERS[v.looksLike];
+    const misplaced = v.looksLike === undefined ? "" : ` — looks like ${/^[aeiou]/i.test(other) ? "an" : "a"} ${other} key (${v.looksLike})`;
+    return `${describeVerdict(verdictOf(v))}${misplaced}`;
+}
+/** A feature's key state without its name: `ready — <sources>: <verdicts>` or `missing <names> — …`. */
+export function featureKeysBody(feature, sources, verification) {
+    const missing = sources.filter((s) => s.source === "missing");
+    if (missing.length > 0) {
+        return `missing ${missing.map((s) => `${s.key} (${s.provider})`).join(", ")} — set it in the environment or run \`jevitate ai setup ${feature}\``;
+    }
+    const parts = sources.map((s) => {
+        const v = verification?.find((x) => x.key === s.key);
+        return `${describeSource(s)}${v === undefined ? "" : `: ${describeVerification(v)}`}`;
+    });
+    const bad = verification?.filter((v) => v.status === "invalid") ?? [];
+    const hint = bad.length > 0 ? ` — replace it: \`jevitate ai setup ${feature} --replace\`` : "";
+    const state = bad.length > 0 ? "NOT ready" : verification?.some((v) => v.status === "unreachable") ? "configured (unverified)" : "ready";
+    return `${state} — ${parts.join("; ")}${hint}`;
+}
+/** A feature's whole key line (`ai status`): `generation: ready — OPENROUTER_API_KEY (OpenRouter), from env …: valid`. */
+export function describeFeatureKeys(feature, sources, verification) {
+    return `${feature}: ${featureKeysBody(feature, sources, verification)}`;
+}
+/** Any verification that is not a pass (invalid or unreachable). */
+export function verificationProblems(verification) {
+    return {
+        invalid: verification.filter((v) => v.status === "invalid"),
+        unreachable: verification.filter((v) => v.status === "unreachable"),
+    };
+}
+/** Env vars that shadow a key just stored (the stored value is unused while they are set). */
+export function shadowWarnings(collected, sources) {
+    return sources
+        .filter((s) => collected.includes(s.key) && s.source === "env")
+        .map((s) => `env ${s.envVar ?? s.key} is set and overrides the ${s.key} just stored — unset it to use the stored key`);
+}
+//# sourceMappingURL=key-report.js.map