@jevitate/cli 0.1.0 → 0.2.0

package/dist/init-cli.js

@@ -0,0 +1,127 @@
+import { envCredentialStore, FEATURE_KEYS } from "@jevitate/ai-core";
+import { loadLocalCredentials } from "./credentials-file.js";
+import { ok, fail } from "./envelope.js";
+import { initProjectDir } from "./project-dir.js";
+import { realSecureIO } from "./ai-cli.js";
+import { collectAllMissingKeys } from "./init-keys.js";
+import { formatInitKeysHuman } from "./cli-output.js";
+import { detectRuntimes, resolveInstallTargetPaths, installSkills } from "./init-skills.js";
+import { registerMcp, resolveMcpTargetPaths } from "./init-mcp.js";
+import { initNextSteps, environmentHint } from "./init-next-steps.js";
+import { loadManifest } from "@jevitate/skills";
+import { resolveDataDir } from "./data-dir.js";
+import { emitJson, emitCommandResult } from "./cli-shared.js";
+/** Registers `jevitate init` (API keys, skills/MCP wiring, the repo's .jevitate/). */
+export function registerInitCommands(program, deps) {
+    program
+        .command("init")
+        .description("set up jevitate: collect API keys, install skills/MCP wiring, create the repo's .jevitate/")
+        .option("--json", "emit a JSON envelope")
+        .option("--skip-keys", "skip credential collection")
+        .option("--skip-skills", "skip skill installation")
+        .option("--skip-mcp", "skip registering the jevitate MCP server in detected harnesses")
+        .option("--targets <ids>", "comma-separated runtime ids to force-install to, overriding detection")
+        .option("--force", "overwrite a user-modified installed skill file/block or MCP config entry")
+        .option("--dry-run", "report planned skill-install/mcp-register actions without writing")
+        .option("--skip-project", "skip creating the repo's .jevitate/ (journeys, regressions, baselines, logs)")
+        .action(async function () {
+        const { json, skipKeys, skipSkills, skipMcp, skipProject, targets, force, dryRun } = this.opts();
+        try {
+            const data = { initialized: true };
+            // The repo's own .jevitate/ (0.2.0 layout): Journeys, regressions and baselines live with the
+            // app's code; logs stay local. Secrets and machine state stay in ~/.jevitate.
+            if (!skipProject)
+                data.project = initProjectDir(deps.init?.detection?.cwd?.() ?? process.cwd(), { ...(dryRun === true ? { dryRun: true } : {}) });
+            if (!skipKeys) {
+                // SECURITY: reuses the existing, already-guardrailed credential
+                // collection. The report holds only key NAMES (required/collected/missing),
+                // never a value — nothing here reads, echoes, logs, or returns a key.
+                const store = envCredentialStore(deps.ai?.env ?? process.env, deps.ai?.localConfig ?? loadLocalCredentials());
+                const io = deps.ai?.secureIO ?? realSecureIO();
+                // #230: never prompt a non-interactive stdin (no TTY — how coding agents and CI run
+                // `jevitate init`) — it would hang reading a 'line' event that never comes, or read EOF
+                // silently. Report what's still missing instead; the rest of init still completes.
+                const interactive = deps.init?.isInteractive?.() ?? process.stdin.isTTY === true;
+                data.keys = await collectAllMissingKeys(store, io, { interactive });
+            }
+            // Explicit `--targets` overrides detection entirely (the user takes
+            // full control); otherwise `detectRuntimes` decides, always including
+            // the always-on generic fallback. Shared by the skill install and the
+            // MCP registration so a single selection drives both.
+            const runtimes = targets
+                ? targets.split(",").map((t) => t.trim()).filter((t) => t.length > 0)
+                : detectRuntimes(deps.init?.detection);
+            if (!skipSkills) {
+                const paths = resolveInstallTargetPaths(deps.init?.detection);
+                const statePath = deps.init?.statePath ?? resolveDataDir(["skills-install-state.json"]);
+                const skills = loadManifest();
+                data.skills = await installSkills(runtimes, skills, paths, statePath, { force, dryRun });
+            }
+            if (!skipMcp) {
+                // Register the `jevitate mcp` server for each detected/selected
+                // harness, with the SAME never-clobber safety as skills: a user's
+                // conflicting or unparseable config is never overwritten without
+                // --force; each declined target reports a printable instruction
+                // instead (honest, never corrupts a config). `generic` has no MCP
+                // convention and is skipped inside `registerMcp`.
+                const mcpPaths = resolveMcpTargetPaths(deps.init?.detection);
+                data.mcp = await registerMcp(runtimes, mcpPaths, { force, dryRun });
+            }
+            // #230: exit 0 even when keys are still missing (the non-interactive path above) —
+            // init's other work (project dir, skills, MCP registration) genuinely succeeded, and a
+            // missing key is expected/normal for a fresh non-interactive install (CI, a coding
+            // agent) that configures keys separately. The warning lives in `data.keys[*].missing`
+            // (both here and in the --json envelope) rather than in the exit code, so a script that
+            // only checks the exit code still sees init as having done its job; a caller that cares
+            // about keys reads the summary/envelope, same as `jevitate ai status`.
+            // The "try this next" block, tailored to what is set up now (keys, MCP, the repo's
+            // environments). Additive in --json (`data.nextSteps`); keys are checked by NAME only.
+            const keysReady = data.keys !== undefined
+                ? Object.values(data.keys).every((r) => (r.missing ?? []).length === 0)
+                : (() => {
+                    const store = envCredentialStore(deps.ai?.env ?? process.env, deps.ai?.localConfig ?? loadLocalCredentials());
+                    return Object.keys(FEATURE_KEYS).every((f) => FEATURE_KEYS[f].every((k) => store.detect(k)));
+                })();
+            const projectDir = data.project?.dir ?? null;
+            data.nextSteps = initNextSteps({
+                keysReady,
+                ...environmentHint(projectDir),
+                ...(data.mcp !== undefined ? { mcp: data.mcp } : {}),
+                skills: data.skills !== undefined,
+                dryRun: dryRun === true,
+            });
+            const envelope = ok(data);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                const out = program.configureOutput().writeOut;
+                // #213: --dry-run writes nothing — say "would" so the summary matches the disk.
+                out?.(dryRun === true ? "jevitate: dry run — nothing was written\n" : "jevitate initialized\n");
+                // #210/#230: per feature, "ready — n/n configured", or (no TTY on stdin) "not
+                // configured — set X or run `jevitate ai setup <feature>`" — never a raw `collected:
+                // []` that reads as "missing" when every key was already set.
+                if (data.keys)
+                    out?.(`${formatInitKeysHuman(data.keys)}\n`);
+                if (data.skills)
+                    out?.(`skills: ${data.skills.length} target/skill pairs ${dryRun === true ? "would be processed" : "processed"}\n`);
+                if (data.mcp)
+                    out?.(`mcp: ${data.mcp.length} harness config(s) ${dryRun === true ? "would be processed" : "processed"}\n`);
+                const project = data.project;
+                if (project !== undefined) {
+                    out?.(project.dir === null
+                        ? `project: ${project.reason ?? "none"}\n`
+                        : `project: ${project.dir} (${project.created.length} ${dryRun === true ? "would create" : "created"})\n`);
+                }
+                out?.(`next steps${data.project?.dir == null ? "" : " (app URLs: .jevitate/environments.json)"}:\n`);
+                for (const line of data.nextSteps)
+                    out?.(`  ${line}\n`);
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            emitCommandResult(program, fail("E_INIT", String(err instanceof Error ? err.message : err)), { json: json === true, command: "init" });
+        }
+    });
+}
+//# sourceMappingURL=init-cli.js.map

package/dist/init-cli.js.map

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

package/dist/init-keys.d.ts

@@ -2,13 +2,30 @@ import { type CredentialStore, type SecureKeyIO, type Feature, type CredentialKe
 export interface FeatureKeyReport {
     required: CredentialKey[];
     collected: CredentialKey[];
+    /**
+     * #230: only set on the non-interactive path — the required keys still absent after this
+     * command ran (nothing was prompted for, nothing persisted). Undefined/empty on the
+     * interactive path: `collectMissingKeys` either leaves every required key configured or
+     * throws (fail-closed), so there is nothing left to report as missing.
+     */
+    missing?: CredentialKey[];
 }
 export type KeyCollectionReport = Record<Feature, FeatureKeyReport>;
+export interface CollectAllMissingKeysOptions {
+    /**
+     * #230: false when stdin is not a TTY (no key env vars, piped/redirected input — how coding
+     * agents and CI run `jevitate init`). `SecureKeyIO.promptSecret` reads a 'line' event that a
+     * closed/non-interactive stdin never emits, so prompting there would hang until the process is
+     * killed, or (observed) read EOF and exit 0 with nothing collected and no summary. Default true
+     * (a real terminal): unchanged prompting behavior.
+     */
+    interactive?: boolean;
+}
 /**
  * Thin orchestration over the existing, already-guardrailed `collectMissingKeys`
  * — collects every feature's missing keys in turn (never in parallel:
  * `SecureKeyIO.promptSecret` is a single shared stdin, so concurrent prompts
  * would interleave). Adds NO new key-handling logic: it never reads, echoes,
- * logs, or returns a key value — only the key NAMES (required/collected).
+ * logs, or returns a key value — only the key NAMES (required/collected/missing).
  */
-export declare function collectAllMissingKeys(store: CredentialStore, io: SecureKeyIO): Promise<KeyCollectionReport>;
+export declare function collectAllMissingKeys(store: CredentialStore, io: SecureKeyIO, opts?: CollectAllMissingKeysOptions): Promise<KeyCollectionReport>;

package/dist/init-keys.js

@@ -5,13 +5,24 @@ const FEATURES = ["generation", "judgment"];
  * — collects every feature's missing keys in turn (never in parallel:
  * `SecureKeyIO.promptSecret` is a single shared stdin, so concurrent prompts
  * would interleave). Adds NO new key-handling logic: it never reads, echoes,
- * logs, or returns a key value — only the key NAMES (required/collected).
+ * logs, or returns a key value — only the key NAMES (required/collected/missing).
  */
-export async function collectAllMissingKeys(store, io) {
+export async function collectAllMissingKeys(store, io, opts = {}) {
     const report = {};
+    const interactive = opts.interactive ?? true;
     for (const feature of FEATURES) {
-        const collected = await collectMissingKeys(feature, store, io);
-        report[feature] = { required: [...FEATURE_KEYS[feature]], collected };
+        const required = [...FEATURE_KEYS[feature]];
+        if (interactive) {
+            const collected = await collectMissingKeys(feature, store, io);
+            report[feature] = { required, collected };
+        }
+        else {
+            // Never prompt: report what's still missing instead of hanging on a closed stdin. `missing`
+            // is omitted (not an empty array) when nothing is missing, so a fully-configured non-TTY
+            // run reads identically to the interactive path's `{ required, collected: [] }`.
+            const missing = required.filter((k) => !store.detect(k));
+            report[feature] = { required, collected: [], ...(missing.length > 0 ? { missing } : {}) };
+        }
     }
     return report;
 }

package/dist/init-keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"init-keys.js","sourceRoot":"","sources":["../src/init-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,GAKb,MAAM,mBAAmB,CAAC;AAQ3B,MAAM,QAAQ,GAAc,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAsB,EACtB,EAAe;IAEf,MAAM,MAAM,GAAG,EAAyB,CAAC;IACzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC/D,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;IACxE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"init-keys.js","sourceRoot":"","sources":["../src/init-keys.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,GAKb,MAAM,mBAAmB,CAAC;AAe3B,MAAM,QAAQ,GAAc,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;AAavD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAsB,EACtB,EAAe,EACf,OAAqC,EAAE;IAEvC,MAAM,MAAM,GAAG,EAAyB,CAAC;IACzC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC;IAC7C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5C,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YAC/D,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QAC5C,CAAC;aAAM,CAAC;YACN,4FAA4F;YAC5F,yFAAyF;YACzF,iFAAiF;YACjF,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YACzD,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAC5F,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/init-next-steps.d.ts

@@ -0,0 +1,35 @@
+import type { McpInstallReport } from "./init-mcp.js";
+/** What `jevitate init` knows after setup that changes the "try this next" block. */
+export interface InitNextStepsInput {
+    /** Both AI features (generation + judgment) have their keys configured. */
+    readonly keysReady: boolean;
+    /** The app URL to put in the commands, when the repo's environments file names a real one. */
+    readonly appUrl?: string;
+    /** A non-production environment name from `.jevitate/environments.json`, for `demo --env`. */
+    readonly env?: string;
+    /** The MCP registration report; undefined when `--skip-mcp`. */
+    readonly mcp?: readonly McpInstallReport[];
+    /** Whether skills were installed (false under `--skip-skills`). */
+    readonly skills: boolean;
+    readonly dryRun: boolean;
+}
+/**
+ * The ≤5 "try this next" lines `jevitate init` prints (and returns as `data.nextSteps`). Every
+ * command is a real one with real flags (skills-cli-drift.test.ts checks them against the CLI);
+ * placeholders are `<…>` so nothing reads as a value we guessed. Tailored, never silent:
+ *  - keys ready → a goal run, an authored Journey and a demo (all need the model gateway);
+ *  - keys missing → the key-free adversarial run (`--fake-ai`: misuse is planned in code, the
+ *    findings are hard signals), a human-recorded flow, and how to add the keys;
+ *  - the agent line says whether the MCP server was registered, declined (conflict), or skipped.
+ */
+export declare function initNextSteps(input: InitNextStepsInput): string[];
+/**
+ * Reads `.jevitate/environments.json` for the next-steps block: the first non-production
+ * environment's name, and its `baseUrl` only when it is not the untouched scaffold's (so the block
+ * never presents the example `http://localhost:3000` as "your app"). Unreadable → nothing: the
+ * block keeps its `<app-url>`/`<env>` placeholders.
+ */
+export declare function environmentHint(projectDir: string | null): {
+    appUrl?: string;
+    env?: string;
+};

package/dist/init-next-steps.js

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ENVIRONMENTS_FILE, ENVIRONMENTS_SCAFFOLD } from "./project-dir.js";
+const REGISTERED = new Set(["create", "update", "unchanged", "force-update"]);
+/**
+ * The ≤5 "try this next" lines `jevitate init` prints (and returns as `data.nextSteps`). Every
+ * command is a real one with real flags (skills-cli-drift.test.ts checks them against the CLI);
+ * placeholders are `<…>` so nothing reads as a value we guessed. Tailored, never silent:
+ *  - keys ready → a goal run, an authored Journey and a demo (all need the model gateway);
+ *  - keys missing → the key-free adversarial run (`--fake-ai`: misuse is planned in code, the
+ *    findings are hard signals), a human-recorded flow, and how to add the keys;
+ *  - the agent line says whether the MCP server was registered, declined (conflict), or skipped.
+ */
+export function initNextSteps(input) {
+    const url = input.appUrl ?? "<app-url>";
+    const env = input.env ?? "<env>";
+    const lines = [];
+    if (input.keysReady) {
+        lines.push(`1. try it:     jevitate explore --url ${url} --goal "<a task a user does>" --success "urlIncludes:<done-path>" --real`);
+        lines.push(`2. keep it:    jevitate explore-author-journey --url ${url} --goal "<task>" --success "<check>" --id <id> --name "<name>" --real`);
+        lines.push(`3. demo it:    jevitate demo "<aspect>" --env ${env} --success "<check>" --real`);
+    }
+    else {
+        lines.push(`1. try it:     jevitate explore --strategy adversarial --url ${url} --fake-ai   (no keys: finds 5xx, crashes, hangs)`);
+        lines.push(`2. record it:  jevitate record --url ${url}   (you click; Enter saves a replayable Recording)`);
+        lines.push("3. add keys:   jevitate ai setup generation && jevitate ai setup judgment   (goals, Journeys, demos)");
+    }
+    lines.push("4. gate CI:    jevitate check --suite <suite.json>   (JUnit + SARIF; exit 1 = a gating finding)");
+    const agent = agentLine(input);
+    if (agent !== undefined)
+        lines.push(agent);
+    return lines;
+}
+function agentLine(input) {
+    const would = input.dryRun ? "would be " : "";
+    if (input.mcp !== undefined && input.mcp.length > 0) {
+        const ok = input.mcp.filter((r) => REGISTERED.has(r.action)).map((r) => r.target);
+        const declined = input.mcp.filter((r) => !REGISTERED.has(r.action)).map((r) => r.target);
+        if (ok.length > 0) {
+            return `agents: MCP server ${would}registered for ${ok.join(", ")}${declined.length > 0 ? ` (not ${declined.join(", ")}: see above)` : ""} — restart the agent, then ask in plain words`;
+        }
+        return `agents: MCP server NOT registered (${declined.join(", ")}: existing config kept) — rerun with --force, or: jevitate mcp --print-config claude`;
+    }
+    if (input.skills) {
+        return "agents: skills installed (CLI) — for MCP tools too: jevitate mcp --print-config claude|cursor|codex|json";
+    }
+    return undefined;
+}
+/**
+ * Reads `.jevitate/environments.json` for the next-steps block: the first non-production
+ * environment's name, and its `baseUrl` only when it is not the untouched scaffold's (so the block
+ * never presents the example `http://localhost:3000` as "your app"). Unreadable → nothing: the
+ * block keeps its `<app-url>`/`<env>` placeholders.
+ */
+export function environmentHint(projectDir) {
+    if (projectDir === null)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(projectDir, ENVIRONMENTS_FILE), "utf8"));
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    for (const [name, entry] of Object.entries(parsed)) {
+        if (name.startsWith("$") || entry === null || typeof entry !== "object")
+            continue;
+        const e = entry;
+        if (e.production === true)
+            continue;
+        const baseUrl = typeof e.baseUrl === "string" ? e.baseUrl : undefined;
+        const isScaffold = name === "local" && baseUrl === ENVIRONMENTS_SCAFFOLD.local.baseUrl;
+        return { env: name, ...(baseUrl !== undefined && !isScaffold ? { appUrl: baseUrl } : {}) };
+    }
+    return {};
+}
+//# sourceMappingURL=init-next-steps.js.map

package/dist/init-next-steps.js.map

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

package/dist/invariants-file.d.ts

@@ -0,0 +1,34 @@
+import { type InvariantSpec } from "@jevitate/recording";
+/**
+ * `--invariants <file.json>` (repeatable, #86): loads the app team's declared-invariant files,
+ * validates each against the closed schema, merges them, and authorizes every probe against the
+ * run's allowlist — all BEFORE any browser opens. A bad file refuses the dispatch with a precise
+ * path (`a.json: invariants[2].require: unknown observable "balanse"`), never mid-run.
+ */
+export declare class InvariantsFileError extends Error {
+    readonly code: "E_EXPLORE_INVARIANTS";
+    /** #195: each path-precise problem on its own (`invariants[2].require: …`); the message joins them. */
+    readonly problems: readonly string[];
+    constructor(message: string, problems?: readonly string[]);
+}
+export interface LoadInvariantsOptions {
+    /**
+     * The run's authorized origins: every probe must resolve onto one. Omitted (with `baseUrl`) only by
+     * `jevitate invariants validate` without `--url` (#195): then every probe/`deniedAs` is REFUSED
+     * ("needs the mission's authorized origins") — nothing is ever assumed authorized.
+     */
+    readonly allowlist?: readonly string[];
+    /** What relative probe paths resolve against (the run's start URL). */
+    readonly baseUrl?: string;
+    /** #147: the registered observer actors (every `--actor` but the primary) cross-actor checks may name. */
+    readonly observers?: readonly string[];
+}
+/** Loads, validates and merges invariant files. Returns undefined for no files. Throws `InvariantsFileError`. */
+export declare function loadInvariantFiles(paths: readonly string[], opts: LoadInvariantsOptions): InvariantSpec | undefined;
+/**
+ * Resolves every `authFrom.secret` ref (#135, `env:VAR`) a spec's probes use, from `env` — the ONE
+ * place this ever happens (the CLI dispatch), matching `--secret-field`'s own `env:VAR` resolution.
+ * Throws `InvariantsFileError` (naming the ref, never a value) for an unset/empty variable. Returns
+ * a map keyed by the ref itself (`"env:APP_TOKEN"` → its value) for `InvariantMonitorOptions.authTokens`.
+ */
+export declare function resolveInvariantAuthTokens(spec: InvariantSpec, env: Readonly<Record<string, string | undefined>>): Map<string, string>;

package/dist/invariants-file.js

@@ -0,0 +1,68 @@
+import { readFileSync } from "node:fs";
+import { InvariantSpecError, invariantAuthSecretRefs, mergeInvariantSpecs, validateInvariantSpec, } from "@jevitate/recording";
+/**
+ * `--invariants <file.json>` (repeatable, #86): loads the app team's declared-invariant files,
+ * validates each against the closed schema, merges them, and authorizes every probe against the
+ * run's allowlist — all BEFORE any browser opens. A bad file refuses the dispatch with a precise
+ * path (`a.json: invariants[2].require: unknown observable "balanse"`), never mid-run.
+ */
+export class InvariantsFileError extends Error {
+    code = "E_EXPLORE_INVARIANTS";
+    /** #195: each path-precise problem on its own (`invariants[2].require: …`); the message joins them. */
+    problems;
+    constructor(message, problems = [message]) {
+        super(message);
+        this.name = "InvariantsFileError";
+        this.problems = problems;
+    }
+}
+/** Loads, validates and merges invariant files. Returns undefined for no files. Throws `InvariantsFileError`. */
+export function loadInvariantFiles(paths, opts) {
+    if (paths.length === 0)
+        return undefined;
+    const specs = [];
+    for (const path of paths) {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (e) {
+            throw new InvariantsFileError(`cannot read invariants file ${path}: ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`);
+        }
+        try {
+            specs.push(validateInvariantSpec(raw, opts));
+        }
+        catch (e) {
+            if (e instanceof InvariantSpecError)
+                throw new InvariantsFileError(`${path}: ${e.problems.join("; ")}`, e.problems);
+            throw e;
+        }
+    }
+    try {
+        return mergeInvariantSpecs(specs);
+    }
+    catch (e) {
+        if (e instanceof InvariantSpecError)
+            throw new InvariantsFileError(e.problems.join("; "), e.problems);
+        throw e;
+    }
+}
+/**
+ * Resolves every `authFrom.secret` ref (#135, `env:VAR`) a spec's probes use, from `env` — the ONE
+ * place this ever happens (the CLI dispatch), matching `--secret-field`'s own `env:VAR` resolution.
+ * Throws `InvariantsFileError` (naming the ref, never a value) for an unset/empty variable. Returns
+ * a map keyed by the ref itself (`"env:APP_TOKEN"` → its value) for `InvariantMonitorOptions.authTokens`.
+ */
+export function resolveInvariantAuthTokens(spec, env) {
+    const tokens = new Map();
+    for (const ref of invariantAuthSecretRefs(spec)) {
+        const name = ref.slice("env:".length);
+        const value = env[name];
+        if (value === undefined || value === "") {
+            throw new InvariantsFileError(`--invariants: authFrom.secret ${ref}: environment variable ${name} is not set`);
+        }
+        tokens.set(ref, value);
+    }
+    return tokens;
+}
+//# sourceMappingURL=invariants-file.js.map

package/dist/invariants-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants-file.js","sourceRoot":"","sources":["../src/invariants-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,GAEtB,MAAM,qBAAqB,CAAC;AAE7B;;;;;GAKG;AAEH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,sBAA+B,CAAC;IAChD,uGAAuG;IAC9F,QAAQ,CAAoB;IACrC,YAAY,OAAe,EAAE,WAA8B,CAAC,OAAO,CAAC;QAClE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAeD,iHAAiH;AACjH,MAAM,UAAU,kBAAkB,CAAC,KAAwB,EAAE,IAA2B;IACtF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,GAAY,CAAC;QACjB,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,mBAAmB,CAAC,+BAA+B,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACrI,CAAC;QACD,IAAI,CAAC;YACH,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,kBAAkB;gBAAE,MAAM,IAAI,mBAAmB,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;YACpH,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,kBAAkB;YAAE,MAAM,IAAI,mBAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;QACtG,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,IAAmB,EACnB,GAAiD;IAEjD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACxC,MAAM,IAAI,mBAAmB,CAAC,iCAAiC,GAAG,0BAA0B,IAAI,aAAa,CAAC,CAAC;QACjH,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/invariants-validate.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from "commander";
+import { type LoadInvariantsOptions } from "./invariants-file.js";
+/**
+ * `jevitate invariants validate <file…>` (#195): lints declared-invariant files WITHOUT a browser —
+ * the exact loader `explore --invariants` runs before any browser opens (`loadInvariantFiles`: the
+ * closed schema, expression/observable cross-references, probe and `deniedAs` origin authorization,
+ * the cross-file merge), so CI can gate committed invariant files. No second implementation.
+ *
+ * Probe/`deniedAs` origins are authorized only against what the caller names (`--url`, `--allow`);
+ * without `--url` a spec that makes network probes is refused, never assumed authorized.
+ */
+export interface InvariantsFileResult {
+    readonly file: string;
+    readonly valid: boolean;
+    /** The file's declared invariants (when it validated). */
+    readonly invariants?: number;
+    /** Path-precise problems (`invariants[2].require: unknown observable "balanse"`). */
+    readonly problems: string[];
+}
+export interface InvariantsValidation {
+    readonly valid: boolean;
+    readonly files: InvariantsFileResult[];
+    /** Problems merging the (individually valid) files: a repeated id, an observable declared twice differently. */
+    readonly merge: string[];
+    /** How to fix an origin-authorization refusal, when one occurred. */
+    readonly hint?: string;
+}
+/** Validates each file on its own (so every file's problems are reported), then their merge. */
+export declare function validateInvariantFiles(files: readonly string[], opts: LoadInvariantsOptions): InvariantsValidation;
+export declare function registerInvariantsCommands(program: Command): void;

package/dist/invariants-validate.js

@@ -0,0 +1,105 @@
+import { readFileSync } from "node:fs";
+import { emitJsonOrRefusal } from "./cli-refusal.js";
+import { ok, fail } from "./envelope.js";
+import { resolveExploreAllowlist } from "./explore-api.js";
+import { InvariantsFileError, loadInvariantFiles } from "./invariants-file.js";
+import { EXIT_CODES } from "./exit-codes.js";
+const ORIGIN_HINT = "pass --url <start-url> (and --allow <origin>, repeatable) to authorize probe and deniedAs origins, as `explore --invariants` does";
+/** Validates each file on its own (so every file's problems are reported), then their merge. */
+export function validateInvariantFiles(files, opts) {
+    const results = files.map((file) => {
+        try {
+            const spec = loadInvariantFiles([file], opts);
+            return { file, valid: true, invariants: spec?.invariants.length ?? 0, problems: [] };
+        }
+        catch (e) {
+            if (!(e instanceof InvariantsFileError))
+                throw e;
+            return { file, valid: false, problems: [...e.problems] };
+        }
+    });
+    let merge = [];
+    if (files.length > 1 && results.every((r) => r.valid)) {
+        try {
+            loadInvariantFiles(files, opts);
+        }
+        catch (e) {
+            if (!(e instanceof InvariantsFileError))
+                throw e;
+            merge = [...e.problems];
+        }
+    }
+    const valid = merge.length === 0 && results.every((r) => r.valid);
+    const needsOrigins = results.some((r) => r.problems.some((p) => p.includes("authorized origins to be checked against")));
+    return { valid, files: results, merge, ...(needsOrigins ? { hint: ORIGIN_HINT } : {}) };
+}
+/** The envelope (success, or a refusal with --json); a refusal without --json is a human stderr line (#218). */
+function emit(program, envelope, exitCode) {
+    emitJsonOrRefusal(program, envelope, exitCode);
+}
+/** The first file that cannot be read at all, with why — unusable input, refused before validating (#218). */
+function unreadableFile(files) {
+    for (const file of files) {
+        try {
+            readFileSync(file, "utf8");
+        }
+        catch (e) {
+            return `cannot read invariants file ${file}: ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`;
+        }
+    }
+    return undefined;
+}
+const collect = (v, prev) => [...prev, v];
+export function registerInvariantsCommands(program) {
+    const invariants = program.command("invariants").description("declared-invariant files (`explore --invariants`)");
+    invariants
+        .command("validate <files...>")
+        .description("validate invariant files without a browser (the same pre-browser check `explore --invariants` runs); exit 1 when any is invalid, 64 when one cannot be read")
+        .option("--url <url>", "the run's start URL: relative probe/deniedAs paths resolve against it, and its origin is authorized")
+        .option("--allow <origin>", "authorized origin (repeatable; needs --url); REPLACES the URL's own origin, as `explore --allow`", collect, [])
+        .option("--observer <name>", "a registered observer actor a probe `as:` / `deniedAs.actor` may name (repeatable; `explore --actor` minus the primary)", collect, [])
+        .option("--json", "emit a JSON envelope")
+        .action(function (files) {
+        const o = this.opts();
+        if (o.url === undefined && o.allow.length > 0) {
+            emit(program, fail("E_INVARIANTS_ARGS", "--allow needs --url (relative probe paths resolve against it)"), EXIT_CODES.usage);
+            return;
+        }
+        // #218: a file that cannot be read is unusable input (64, like every command), not an invalid one (1).
+        const unreadable = unreadableFile(files);
+        if (unreadable !== undefined) {
+            emit(program, fail("E_INVARIANTS_INPUT", unreadable), EXIT_CODES.usage);
+            return;
+        }
+        // Without --url nothing is authorized: the loader refuses every probe/deniedAs origin itself.
+        const opts = o.url === undefined
+            ? { observers: o.observer }
+            : { allowlist: resolveExploreAllowlist(o.url, o.allow), baseUrl: o.url, observers: o.observer };
+        const result = validateInvariantFiles(files, opts);
+        const exitCode = result.valid ? EXIT_CODES.ok : EXIT_CODES.defects;
+        if (o.json === true) {
+            emit(program, ok(result), exitCode);
+            return;
+        }
+        const lines = [];
+        for (const f of result.files) {
+            if (f.valid)
+                lines.push(`valid    ${f.file} (${f.invariants ?? 0} invariants)`);
+            else {
+                lines.push(`invalid  ${f.file}`);
+                for (const p of f.problems)
+                    lines.push(`  ${p}`);
+            }
+        }
+        if (result.merge.length > 0) {
+            lines.push("invalid  merge of the files above");
+            for (const p of result.merge)
+                lines.push(`  ${p}`);
+        }
+        if (result.hint !== undefined)
+            lines.push(`hint: ${result.hint}`);
+        program.configureOutput().writeOut?.(`${lines.join("\n")}\n`);
+        process.exitCode = exitCode;
+    });
+}
+//# sourceMappingURL=invariants-validate.js.map

package/dist/invariants-validate.js.map

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