@jevitate/cli 0.1.0 → 0.3.0

package/dist/environments.d.ts

@@ -0,0 +1,155 @@
+import type { Command } from "commander";
+import type { Journey } from "@jevitate/journey";
+import type { Recording } from "@jevitate/recording";
+import { type LayoutDeps } from "./project-dir.js";
+import { type TargetConfig } from "./target-config.js";
+/**
+ * Named environments (#247). A Journey is environment-free: its steps are app-relative paths
+ * (`/login`), and its recorded `site` is only its DEFAULT environment. Which app a run replays
+ * against is chosen at run time:
+ *
+ *  - `--env <name>` — an entry of the repo's committed `.jevitate/environments.json`:
+ *
+ *    ```json
+ *    { "local":   { "baseUrl": "http://localhost:3000" },
+ *      "staging": { "baseUrl": "https://staging.example.com", "allow": ["https://auth.example.com"],
+ *                   "fixtures": "fixtures/staging.json", "hooks": { "before": "./scripts/seed.sh" } } }
+ *    ```
+ *
+ *    `baseUrl` — the environment's origin (never a path, never credentials); `allow` — the other
+ *    origins a Journey step may be on (an auth provider, say); `fixtures` — a mission fixtures file
+ *    (relative to the environments file) used when `--fixtures` is absent; `hooks` — `before`/
+ *    `after` shell hooks used when `--before`/`--after` are absent (they still need
+ *    `--allow-shell-hooks`); `production: true` marks a live environment (`jevitate demo` refuses it,
+ *    #249). Keys starting with `$` (`$comment`) are documentation. The file is
+ *    committed, so it NEVER holds a secret or a session: a `storageState`/`secret`/`password`/
+ *    `token`/`cookie`/`credential` key anywhere in it is refused.
+ *  - `--base-url <origin>` — an ad-hoc environment (a preview deploy); with `--env`, it replaces
+ *    that environment's `baseUrl` and keeps the rest.
+ *
+ * Per-environment sessions and secrets live in `~/.jevitate/targets.json`, keyed by the
+ * environment's origin — the same per-origin operator file (#175) `mission run` and `verify_fix`
+ * already read: `storageState` (the default session), `secretFields` (`env:VAR` bindings), and
+ * `personas: { "<name>": { storageState?, secretFields? } }` for one session per persona. No `--env`
+ * and no `--base-url` means exactly the pre-#247 behaviour: the Journey's recorded site.
+ *
+ * `resolveJourneyEnvironment` is THE one resolver every Journey-running command calls (`journey
+ * run`, `regression run`, `load run`, check-suite Journey items, and later `journey annotate` /
+ * `journey demo`); `applyJourneyEnvironment` rebases a Journey onto it and refuses a step on an
+ * origin the environment does not allow — before any browser opens.
+ */
+export { ENVIRONMENTS_FILE, ENVIRONMENTS_SCAFFOLD, scaffoldEnvironmentsFile } from "./project-dir.js";
+/** One environment, as declared in `.jevitate/environments.json` (paths resolved absolute). */
+export interface EnvironmentDef {
+    /** The environment's origin (`https://staging.example.com`), normalized. */
+    readonly baseUrl: string;
+    /** Other origins a Journey step may be on, normalized. */
+    readonly allow: readonly string[];
+    /** Mission fixtures file, absolute. */
+    readonly fixtures?: string;
+    /** Operator shell hooks (still gated by `--allow-shell-hooks`). */
+    readonly hooks?: {
+        readonly before?: string;
+        readonly after?: string;
+    };
+    /** `production: true` (#249): a live environment — `jevitate demo` refuses it. */
+    readonly production?: boolean;
+}
+/** `.jevitate/environments.json` is missing a named environment, or is not what it should be. */
+export declare class EnvironmentConfigError extends Error {
+    readonly code: "E_ENV_CONFIG";
+    constructor(message: string);
+}
+/** `--env <name>` names no environment (exit 64, listing the known ones). */
+export declare class UnknownEnvironmentError extends Error {
+    readonly env: string;
+    readonly known: readonly string[];
+    readonly code: "E_ENV_UNKNOWN";
+    constructor(env: string, known: readonly string[], where: string | null);
+}
+/** `--base-url` is not an origin. */
+export declare class EnvironmentArgsError extends Error {
+    readonly code: "E_ENV_ARGS";
+    constructor(message: string);
+}
+/** A Journey step is on an origin the chosen environment does not allow (exit 64, nothing opened). */
+export declare class EnvironmentOriginRefusedError extends Error {
+    readonly code: "E_ENV_ORIGIN_REFUSED";
+    constructor(message: string);
+}
+/** Every error the resolver or the rebase can throw — each a usage refusal (exit 64). */
+export type EnvironmentError = EnvironmentConfigError | UnknownEnvironmentError | EnvironmentArgsError | EnvironmentOriginRefusedError;
+export declare function isEnvironmentError(err: unknown): err is EnvironmentError;
+/** Validates a parsed environments file (`where` names it in every error). */
+export declare function parseEnvironments(parsed: unknown, where: string, baseDir: string): Readonly<Record<string, EnvironmentDef>>;
+/** The repo's `.jevitate/environments.json` (found as `.jevitate/` is), or `null` outside a project. */
+export declare function environmentsFilePath(deps?: LayoutDeps): string | null;
+/** Reads and validates an environments file. A missing file is "no environments". */
+export declare function loadEnvironmentsFile(path: string): Readonly<Record<string, EnvironmentDef>>;
+/** The chosen environment for one run: where the Journey goes, what it may reach, and its local session. */
+export interface ResolvedJourneyEnvironment {
+    /** The environment's name (`--env`), absent for a bare `--base-url`. */
+    readonly name?: string;
+    /** The origin the Journey's paths are moved onto. */
+    readonly baseUrl: string;
+    /** Every origin a step may be on: `baseUrl`, then the environment's `allow`. */
+    readonly allowedOrigins: readonly string[];
+    readonly fixtures?: string;
+    readonly hooks?: {
+        readonly before?: string;
+        readonly after?: string;
+    };
+    /** From `~/.jevitate/targets.json[baseUrl]` (or its `personas[persona]`): the default session. */
+    readonly storageState?: string;
+    /** From `~/.jevitate/targets.json[baseUrl]` (or its persona): `env:VAR` secret-field specs. */
+    readonly secretFields?: readonly string[];
+    /** Where the environment came from (`--env`'s file, or `--base-url`). */
+    readonly source: string;
+    /** The named environment is flagged `production: true` (#249: `demo` refuses it). */
+    readonly production?: true;
+}
+export interface JourneyEnvironmentRequest {
+    /** `--env <name>`. */
+    readonly env?: string;
+    /** `--base-url <origin>`. */
+    readonly baseUrl?: string;
+    /** A persona under the origin's `personas` in `~/.jevitate/targets.json` (its session and secrets). */
+    readonly persona?: string;
+    /** The environments file (default: the repo's `.jevitate/environments.json`). */
+    readonly environmentsFile?: string;
+    /** `~/.jevitate/targets.json` (the per-origin operator file). */
+    readonly targetsFile?: string;
+    /** An already-loaded targets file (wins over `targetsFile`). */
+    readonly targets?: Readonly<Record<string, TargetConfig>>;
+    readonly layout?: LayoutDeps;
+}
+/**
+ * THE environment resolver (#247). `undefined` when neither `env` nor `baseUrl` is given — the
+ * caller then runs exactly as before, on the Journey's recorded site. Throws `UnknownEnvironmentError`
+ * (listing the known names), `EnvironmentConfigError` (a bad file, path-precise; a persona the
+ * origin does not declare), or `EnvironmentArgsError` (a `baseUrl` that is not an origin).
+ */
+export declare function resolveJourneyEnvironment(req: JourneyEnvironmentRequest): ResolvedJourneyEnvironment | undefined;
+/**
+ * Moves a Recording onto `env` (#247): its `site` becomes the environment's `baseUrl`; every
+ * absolute URL on the recorded site's origin (page urls, `navigate` urls, `urlIncludes` texts)
+ * keeps its path/query/fragment on the new origin; app-relative paths are left as they are (they
+ * resolve against the environment). A page or `navigate` step on any OTHER origin must be in the
+ * environment's `allow` — otherwise `EnvironmentOriginRefusedError`, before anything opens.
+ * Never guesses, never mutates the input.
+ */
+export declare function rebaseRecording(recording: Recording, env: ResolvedJourneyEnvironment): Recording;
+/** `rebaseRecording` for a whole Journey (its metadata, incl. origin-bound secretRefs, is untouched: fail closed). */
+export declare function applyJourneyEnvironment(journey: Journey, env: ResolvedJourneyEnvironment | undefined): Journey;
+/** Raw commander values of `--env` / `--base-url`. */
+export interface EnvironmentFlags {
+    readonly env?: string;
+    readonly baseUrl?: string;
+}
+/** Adds `--env <name>` and `--base-url <origin>` (#247). */
+export declare function withEnvironmentFlags(cmd: Command): Command;
+/** The environment a command's `--env`/`--base-url` flags choose (see `resolveJourneyEnvironment`). */
+export declare function environmentFromFlags(flags: EnvironmentFlags, seams?: {
+    readonly environmentsFile?: string;
+    readonly targetsFile?: string;
+}): ResolvedJourneyEnvironment | undefined;

package/dist/environments.js

@@ -0,0 +1,364 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { ENVIRONMENTS_FILE, findProjectDir } from "./project-dir.js";
+import { loadTargetsFile, TargetConfigError } from "./target-config.js";
+/**
+ * Named environments (#247). A Journey is environment-free: its steps are app-relative paths
+ * (`/login`), and its recorded `site` is only its DEFAULT environment. Which app a run replays
+ * against is chosen at run time:
+ *
+ *  - `--env <name>` — an entry of the repo's committed `.jevitate/environments.json`:
+ *
+ *    ```json
+ *    { "local":   { "baseUrl": "http://localhost:3000" },
+ *      "staging": { "baseUrl": "https://staging.example.com", "allow": ["https://auth.example.com"],
+ *                   "fixtures": "fixtures/staging.json", "hooks": { "before": "./scripts/seed.sh" } } }
+ *    ```
+ *
+ *    `baseUrl` — the environment's origin (never a path, never credentials); `allow` — the other
+ *    origins a Journey step may be on (an auth provider, say); `fixtures` — a mission fixtures file
+ *    (relative to the environments file) used when `--fixtures` is absent; `hooks` — `before`/
+ *    `after` shell hooks used when `--before`/`--after` are absent (they still need
+ *    `--allow-shell-hooks`); `production: true` marks a live environment (`jevitate demo` refuses it,
+ *    #249). Keys starting with `$` (`$comment`) are documentation. The file is
+ *    committed, so it NEVER holds a secret or a session: a `storageState`/`secret`/`password`/
+ *    `token`/`cookie`/`credential` key anywhere in it is refused.
+ *  - `--base-url <origin>` — an ad-hoc environment (a preview deploy); with `--env`, it replaces
+ *    that environment's `baseUrl` and keeps the rest.
+ *
+ * Per-environment sessions and secrets live in `~/.jevitate/targets.json`, keyed by the
+ * environment's origin — the same per-origin operator file (#175) `mission run` and `verify_fix`
+ * already read: `storageState` (the default session), `secretFields` (`env:VAR` bindings), and
+ * `personas: { "<name>": { storageState?, secretFields? } }` for one session per persona. No `--env`
+ * and no `--base-url` means exactly the pre-#247 behaviour: the Journey's recorded site.
+ *
+ * `resolveJourneyEnvironment` is THE one resolver every Journey-running command calls (`journey
+ * run`, `regression run`, `load run`, check-suite Journey items, and later `journey annotate` /
+ * `journey demo`); `applyJourneyEnvironment` rebases a Journey onto it and refuses a step on an
+ * origin the environment does not allow — before any browser opens.
+ */
+export { ENVIRONMENTS_FILE, ENVIRONMENTS_SCAFFOLD, scaffoldEnvironmentsFile } from "./project-dir.js";
+/** `.jevitate/environments.json` is missing a named environment, or is not what it should be. */
+export class EnvironmentConfigError extends Error {
+    code = "E_ENV_CONFIG";
+    constructor(message) {
+        super(message);
+        this.name = "EnvironmentConfigError";
+    }
+}
+/** `--env <name>` names no environment (exit 64, listing the known ones). */
+export class UnknownEnvironmentError extends Error {
+    env;
+    known;
+    code = "E_ENV_UNKNOWN";
+    constructor(env, known, where) {
+        super(`unknown environment ${JSON.stringify(env)}: ${known.length === 0
+            ? `no environments are declared${where === null ? " (no .jevitate/environments.json — run `jevitate init` in the repo)" : ` in ${where}`}`
+            : `known environments: ${known.join(", ")}${where === null ? "" : ` (${where})`}`}`);
+        this.env = env;
+        this.known = known;
+        this.name = "UnknownEnvironmentError";
+    }
+}
+/** `--base-url` is not an origin. */
+export class EnvironmentArgsError extends Error {
+    code = "E_ENV_ARGS";
+    constructor(message) {
+        super(message);
+        this.name = "EnvironmentArgsError";
+    }
+}
+/** A Journey step is on an origin the chosen environment does not allow (exit 64, nothing opened). */
+export class EnvironmentOriginRefusedError extends Error {
+    code = "E_ENV_ORIGIN_REFUSED";
+    constructor(message) {
+        super(message);
+        this.name = "EnvironmentOriginRefusedError";
+    }
+}
+export function isEnvironmentError(err) {
+    return (err instanceof EnvironmentConfigError ||
+        err instanceof UnknownEnvironmentError ||
+        err instanceof EnvironmentArgsError ||
+        err instanceof EnvironmentOriginRefusedError);
+}
+const ENV_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const ENV_KEYS = new Set(["baseUrl", "allow", "fixtures", "hooks", "production"]);
+const HOOK_KEYS = new Set(["before", "after"]);
+/** A key that would put a secret or a session into a committed file. */
+const SECRET_KEY = /storage.?state|secret|passw(or)?d|token|cookie|credential|api.?key|session|auth(orization)?$/i;
+/** An `http(s)` origin — no path, query, fragment or credentials. `null` + the reason otherwise. */
+function originOf(raw) {
+    if (typeof raw !== "string" || raw.trim() === "")
+        return { reason: "must be an http(s) origin string" };
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return { reason: `must be an http(s) origin (got ${JSON.stringify(raw)})` };
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:")
+        return { reason: `must be an http(s) origin (got ${JSON.stringify(raw)})` };
+    if (u.username !== "" || u.password !== "")
+        return { reason: "must not carry credentials (user:password@) — sessions and secrets live in ~/.jevitate/targets.json" };
+    if ((u.pathname !== "/" && u.pathname !== "") || u.search !== "" || u.hash !== "") {
+        return { reason: `must be an origin with no path, query or fragment (got ${JSON.stringify(raw)}; Journeys carry app-relative paths)` };
+    }
+    return { origin: u.origin };
+}
+/** Refuses any secret-looking key, anywhere in the value (path-precise). */
+function refuseSecretKeys(v, where) {
+    if (Array.isArray(v)) {
+        v.forEach((x, i) => refuseSecretKeys(x, `${where}[${i}]`));
+        return;
+    }
+    if (v === null || typeof v !== "object")
+        return;
+    for (const [k, x] of Object.entries(v)) {
+        if (SECRET_KEY.test(k)) {
+            throw new EnvironmentConfigError(`${where}.${k}: environments.json is committed with the app's code and never holds secrets or sessions — ` +
+                `put storage states and secret fields in ~/.jevitate/targets.json under the environment's origin ("storageState", "secretFields", "personas")`);
+        }
+        refuseSecretKeys(x, `${where}.${k}`);
+    }
+}
+function parseEnvironment(v, where, baseDir) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        throw new EnvironmentConfigError(`${where} must be an object { baseUrl, allow?, fixtures?, hooks? }`);
+    refuseSecretKeys(v, where);
+    const o = v;
+    for (const k of Object.keys(o)) {
+        if (!ENV_KEYS.has(k) && !k.startsWith("$"))
+            throw new EnvironmentConfigError(`${where}.${k}: unknown key (allowed: baseUrl, allow, fixtures, hooks, production)`);
+    }
+    if (o.baseUrl === undefined)
+        throw new EnvironmentConfigError(`${where}.baseUrl is required`);
+    const base = originOf(o.baseUrl);
+    if ("reason" in base)
+        throw new EnvironmentConfigError(`${where}.baseUrl ${base.reason}`);
+    const allow = [];
+    if (o.allow !== undefined) {
+        if (!Array.isArray(o.allow))
+            throw new EnvironmentConfigError(`${where}.allow must be an array of http(s) origins`);
+        o.allow.forEach((a, i) => {
+            const r = originOf(a);
+            if ("reason" in r)
+                throw new EnvironmentConfigError(`${where}.allow[${i}] ${r.reason}`);
+            if (!allow.includes(r.origin))
+                allow.push(r.origin);
+        });
+    }
+    let fixtures;
+    if (o.fixtures !== undefined) {
+        if (typeof o.fixtures !== "string" || o.fixtures === "")
+            throw new EnvironmentConfigError(`${where}.fixtures must be a file path`);
+        fixtures = resolvePath(baseDir, o.fixtures);
+    }
+    let hooks;
+    if (o.hooks !== undefined) {
+        if (o.hooks === null || typeof o.hooks !== "object" || Array.isArray(o.hooks))
+            throw new EnvironmentConfigError(`${where}.hooks must be an object { before?, after? }`);
+        hooks = {};
+        for (const [k, h] of Object.entries(o.hooks)) {
+            if (k.startsWith("$"))
+                continue;
+            if (!HOOK_KEYS.has(k))
+                throw new EnvironmentConfigError(`${where}.hooks.${k}: unknown key (allowed: before, after)`);
+            if (typeof h !== "string" || h.trim() === "")
+                throw new EnvironmentConfigError(`${where}.hooks.${k} must be a shell command string`);
+            hooks[k] = h;
+        }
+    }
+    if (o.production !== undefined && typeof o.production !== "boolean")
+        throw new EnvironmentConfigError(`${where}.production must be true or false`);
+    return {
+        baseUrl: base.origin,
+        allow: allow.filter((a) => a !== base.origin),
+        ...(fixtures === undefined ? {} : { fixtures }),
+        ...(hooks === undefined ? {} : { hooks }),
+        ...(o.production === true ? { production: true } : {}),
+    };
+}
+/** Validates a parsed environments file (`where` names it in every error). */
+export function parseEnvironments(parsed, where, baseDir) {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new EnvironmentConfigError(`${where} must be an object keyed by environment name ({ "local": { "baseUrl": "http://localhost:3000" } })`);
+    }
+    const out = {};
+    for (const [name, v] of Object.entries(parsed)) {
+        if (name.startsWith("$"))
+            continue;
+        if (!ENV_NAME.test(name) || name.includes("..") || name.length > 64) {
+            throw new EnvironmentConfigError(`${where}[${JSON.stringify(name)}]: an environment name is letters, digits, '.', '_' or '-', starting with a letter or digit`);
+        }
+        out[name] = parseEnvironment(v, `${where}[${name}]`, baseDir);
+    }
+    return out;
+}
+/** The repo's `.jevitate/environments.json` (found as `.jevitate/` is), or `null` outside a project. */
+export function environmentsFilePath(deps = {}) {
+    const dir = findProjectDir(deps);
+    return dir === null ? null : join(dir, ENVIRONMENTS_FILE);
+}
+/** Reads and validates an environments file. A missing file is "no environments". */
+export function loadEnvironmentsFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        if (typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT")
+            return {};
+        throw new EnvironmentConfigError(`cannot read ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new EnvironmentConfigError(`${path} is not valid JSON`);
+    }
+    return parseEnvironments(parsed, path, dirname(path));
+}
+/**
+ * THE environment resolver (#247). `undefined` when neither `env` nor `baseUrl` is given — the
+ * caller then runs exactly as before, on the Journey's recorded site. Throws `UnknownEnvironmentError`
+ * (listing the known names), `EnvironmentConfigError` (a bad file, path-precise; a persona the
+ * origin does not declare), or `EnvironmentArgsError` (a `baseUrl` that is not an origin).
+ */
+export function resolveJourneyEnvironment(req) {
+    if (req.env === undefined && req.baseUrl === undefined) {
+        if (req.persona !== undefined)
+            throw new EnvironmentArgsError("a persona needs an environment (--env <name> or --base-url <origin>)");
+        return undefined;
+    }
+    let def;
+    let source = "--base-url";
+    if (req.env !== undefined) {
+        const file = req.environmentsFile ?? environmentsFilePath(req.layout);
+        const envs = file === null ? {} : loadEnvironmentsFile(file);
+        def = Object.prototype.hasOwnProperty.call(envs, req.env) ? envs[req.env] : undefined;
+        if (def === undefined)
+            throw new UnknownEnvironmentError(req.env, Object.keys(envs).sort(), file !== null && existsSync(file) ? file : null);
+        source = `${file}[${req.env}]`;
+    }
+    let baseUrl = def?.baseUrl;
+    if (req.baseUrl !== undefined) {
+        const r = originOf(req.baseUrl);
+        if ("reason" in r)
+            throw new EnvironmentArgsError(`--base-url ${r.reason}`);
+        baseUrl = r.origin;
+    }
+    if (baseUrl === undefined)
+        throw new EnvironmentArgsError("no base URL"); // unreachable: env or baseUrl is set
+    const allow = (def?.allow ?? []).filter((a) => a !== baseUrl);
+    let targets;
+    try {
+        targets = req.targets ?? (req.targetsFile === undefined ? loadTargetsFile() : loadTargetsFile(req.targetsFile));
+    }
+    catch (e) {
+        if (e instanceof TargetConfigError)
+            throw new EnvironmentConfigError(e.message);
+        throw e;
+    }
+    const local = targets[baseUrl];
+    let session = local;
+    if (req.persona !== undefined) {
+        session = local?.personas?.[req.persona];
+        if (session === undefined) {
+            const known = Object.keys(local?.personas ?? {});
+            throw new EnvironmentConfigError(`persona ${JSON.stringify(req.persona)} has no session for ${baseUrl} in ~/.jevitate/targets.json` +
+                (known.length === 0 ? "" : ` (known personas: ${known.join(", ")})`));
+        }
+    }
+    return {
+        ...(req.env === undefined ? {} : { name: req.env }),
+        baseUrl,
+        allowedOrigins: [baseUrl, ...allow],
+        ...(def?.fixtures === undefined ? {} : { fixtures: def.fixtures }),
+        ...(def?.hooks === undefined ? {} : { hooks: def.hooks }),
+        ...(session?.storageState === undefined ? {} : { storageState: session.storageState }),
+        ...(session?.secretFields === undefined ? {} : { secretFields: session.secretFields }),
+        source,
+        ...(def?.production === true ? { production: true } : {}),
+    };
+}
+function absoluteUrl(s) {
+    if (!/^https?:\/\//i.test(s))
+        return null;
+    try {
+        return new URL(s);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Moves a Recording onto `env` (#247): its `site` becomes the environment's `baseUrl`; every
+ * absolute URL on the recorded site's origin (page urls, `navigate` urls, `urlIncludes` texts)
+ * keeps its path/query/fragment on the new origin; app-relative paths are left as they are (they
+ * resolve against the environment). A page or `navigate` step on any OTHER origin must be in the
+ * environment's `allow` — otherwise `EnvironmentOriginRefusedError`, before anything opens.
+ * Never guesses, never mutates the input.
+ */
+export function rebaseRecording(recording, env) {
+    const recordedOrigin = absoluteUrl(recording.site)?.origin;
+    const refusals = [];
+    const move = (raw, where, mustBeAllowed) => {
+        const u = absoluteUrl(raw);
+        if (u === null)
+            return raw;
+        if (recordedOrigin !== undefined && u.origin === recordedOrigin)
+            return `${env.baseUrl}${u.pathname}${u.search}${u.hash}`;
+        if (mustBeAllowed && !env.allowedOrigins.includes(u.origin))
+            refusals.push(`${where} is on ${u.origin}`);
+        return raw;
+    };
+    const walk = (v, where) => {
+        if (Array.isArray(v))
+            return v.map((x, i) => walk(x, `${where}[${i}]`));
+        if (v === null || typeof v !== "object")
+            return v;
+        const o = v;
+        const out = {};
+        for (const [k, x] of Object.entries(o))
+            out[k] = walk(x, `${where}.${k}`);
+        if (o.kind === "navigate" && typeof o.url === "string")
+            out.url = move(o.url, `${where} (navigate ${o.url})`, true);
+        if (o.kind === "urlIncludes" && typeof o.text === "string")
+            out.text = move(o.text, `${where}.text`, false);
+        return out;
+    };
+    const pages = recording.pages.map((p, i) => ({
+        ...walk(p, `pages[${i}]`),
+        url: move(p.url, `pages[${i}] (${p.url})`, true),
+    }));
+    if (refusals.length > 0) {
+        throw new EnvironmentOriginRefusedError(`${refusals.join("; ")} — not allowed by the ${env.name === undefined ? `--base-url ${env.baseUrl}` : `environment '${env.name}'`} ` +
+            `(allowed: ${env.allowedOrigins.join(", ")}). Add the origin to its "allow" in .jevitate/environments.json to permit it; nothing was opened`);
+    }
+    return { ...recording, site: env.baseUrl, pages };
+}
+/** `rebaseRecording` for a whole Journey (its metadata, incl. origin-bound secretRefs, is untouched: fail closed). */
+export function applyJourneyEnvironment(journey, env) {
+    if (env === undefined)
+        return journey;
+    return { ...journey, recording: rebaseRecording(journey.recording, env) };
+}
+/** Adds `--env <name>` and `--base-url <origin>` (#247). */
+export function withEnvironmentFlags(cmd) {
+    return cmd
+        .option("--env <name>", "run against a named environment from the repo's .jevitate/environments.json (default: the Journey's recorded site)")
+        .option("--base-url <origin>", "run against this origin (an ad-hoc environment; with --env, replaces its baseUrl)");
+}
+/** The environment a command's `--env`/`--base-url` flags choose (see `resolveJourneyEnvironment`). */
+export function environmentFromFlags(flags, seams = {}) {
+    return resolveJourneyEnvironment({
+        ...(flags.env === undefined ? {} : { env: flags.env }),
+        ...(flags.baseUrl === undefined ? {} : { baseUrl: flags.baseUrl }),
+        ...(seams.environmentsFile === undefined ? {} : { environmentsFile: seams.environmentsFile }),
+        ...(seams.targetsFile === undefined ? {} : { targetsFile: seams.targetsFile }),
+    });
+}
+//# sourceMappingURL=environments.js.map

package/dist/environments.js.map

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

package/dist/exit-codes.d.ts

@@ -0,0 +1,46 @@
+import { type MissionOutcome } from "@jevitate/domain";
+/**
+ * THE exit-code table for every `jevitate` command (#210) — documented once, in
+ * docs/outcomes.md "Exit codes", and linked from everywhere else. Every command sets
+ * `process.exitCode` from this table (directly, or through `exitCodeForError` for a refused
+ * command), so CI can tell a typo from a defect from a run that proved nothing:
+ *
+ *  | code | class         | meaning                                                                        |
+ *  |------|---------------|--------------------------------------------------------------------------------|
+ *  | 0    | ok            | clean · succeeded · check passed · fixed · the command did what it was asked   |
+ *  | 1    | defects       | defects found · a gating finding · still reproduces · a success check failed   |
+ *  | 2    | inconclusive  | the run/command could not finish its work (inconclusive, crashed, an item      |
+ *  |      |               | errored, budget exceeded, an unexpected error) — it proves nothing             |
+ *  | 3    | hang          | the app under test hung, and the hang reproduced on replay                     |
+ *  | 4    | intermittent  | a signal fired on some but not every replay                                    |
+ *  | 64   | usage         | bad flags/arguments or unusable input (unknown id, invalid file, missing keys, |
+ *  |      |               | refused target) — nothing ran. `EX_USAGE` from sysexits.h.                     |
+ *  | 130/143 | killed     | SIGINT / SIGTERM (kill-signal.ts); the partial result is still written         |
+ *
+ * 0–4 are the pre-existing mission codes (`MISSION_EXIT_CODES`, @jevitate/domain) unchanged; the
+ * mission outcome → code mapping stays THERE (one place), and this table only names the classes.
+ * Usage errors get 64 rather than the next small integer so a future outcome code (5, 6, …) never
+ * collides with it.
+ */
+export declare const EXIT_CODES: {
+    readonly ok: 0;
+    readonly defects: 1;
+    readonly inconclusive: 2;
+    readonly hang: 3;
+    readonly intermittent: 4;
+    readonly usage: 64;
+};
+export type ExitClass = keyof typeof EXIT_CODES;
+/** A canonical mission outcome's exit code (the domain table; re-exported so commands import one module). */
+export declare function exitCodeForOutcome(outcome: MissionOutcome): number;
+/** True when a refused command's error code is a usage/input error (exit 64). */
+export declare function isUsageErrorCode(code: string): boolean;
+/** A refused command's exit code: 64 for a usage/input error, else 2 (the command could not finish). */
+export declare function exitCodeForError(code: string): number;
+/** The exit code for a `{ok, error?}` envelope that carries no verdict of its own. */
+export declare function exitCodeForEnvelope(envelope: {
+    readonly ok: boolean;
+    readonly error?: {
+        readonly code: string;
+    };
+}): number;