@jevitate/cli 0.1.0 → 0.3.0

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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"}

package/dist/journey-annotate-api.d.ts

@@ -0,0 +1,76 @@
+import { type AnnotationChange, type AnnotationDraft, type IntentCoverage, type Journey } from "@jevitate/journey";
+import { type GenerationPort } from "@jevitate/ai-core";
+import { type RunJourneyProgrammaticallyOptions } from "./journey-api.js";
+export declare class AnnotationDraftNotFoundError extends Error {
+    readonly code = "E_JOURNEY_ANNOTATIONS_NOT_FOUND";
+}
+export declare class InvalidAnnotationDraftError extends Error {
+    readonly code = "E_INVALID_ANNOTATIONS_DRAFT";
+}
+/** The Journey changed after the draft was made — approving would annotate steps it never saw. */
+export declare class StaleAnnotationDraftError extends Error {
+    readonly code = "E_JOURNEY_ANNOTATIONS_STALE";
+}
+/**
+ * Where a Journey's draft lives: `<journeys>/.drafts/<id>.annotations.json` (`<ns>/<id>` for a shared
+ * Journey). A dot-folder, so `journey list` and namespace discovery never read it as a Journey.
+ */
+export declare function annotationDraftPath(journeysDir: string, id: string): string;
+/** The Journey's content hash — what a draft is bound to. */
+export declare function journeyContentHash(journey: Journey): string;
+export interface AnnotateJourneyOptions extends Omit<RunJourneyProgrammaticallyOptions, "interpreter" | "policy" | "selfHealer"> {
+    /** The generation gateway that drafts the text (`--real` / `--fake-ai`). */
+    gen: GenerationPort;
+    /** Testing seam for the draft's timestamp. */
+    now?: () => string;
+}
+export interface AnnotateJourneyResult {
+    readonly id: string;
+    readonly draftPath: string;
+    readonly replay: AnnotationDraft["replay"];
+    readonly drafted: {
+        readonly objectives: number;
+        readonly expectedResults: number;
+        readonly goal: boolean;
+        readonly successCriteria: number;
+    };
+    /** What approving the draft would change (the same diff `--approve` shows). */
+    readonly proposed: AnnotationChange[];
+    readonly coverage: IntentCoverage;
+    /** #251 `--screenshots`: the replay's masked screenshots and their `index.md`. */
+    readonly screenshotPaths?: string[];
+    readonly screenshotIndex?: string;
+    readonly screenshotsSkipped?: Array<{
+        readonly step: number;
+        readonly reason: string;
+    }>;
+}
+/**
+ * Replays the Journey through `runJourneyProgrammatically` (the same session, site policy, fixtures
+ * and fail-closed policy as `journey run`) with an observing interpreter, then drafts. A replay that
+ * stops early still drafts the steps it reached (`replay.outcome: "stopped"`).
+ *
+ * Environments (#247): every browser/session option `journey run` takes rides in `opts` and is
+ * handed to `runJourneyProgrammatically` unchanged — including `environment` (`--env`/`--base-url`,
+ * resolved by `resolveJourneyEnvironment`), so the replay is rebased and allowlisted exactly as a run.
+ */
+export declare function annotateJourney(opts: AnnotateJourneyOptions): Promise<AnnotateJourneyResult>;
+export interface ApproveAnnotationsResult {
+    readonly id: string;
+    readonly draftPath: string;
+    readonly changes: AnnotationChange[];
+    readonly coverage: IntentCoverage;
+}
+/** Reads and validates a Journey's draft (not found / invalid are typed refusals). */
+export declare function readAnnotationDraft(dir: string, id: string): Promise<{
+    draft: AnnotationDraft;
+    draftPath: string;
+}>;
+/**
+ * The human approval gate (like `journey promote`): applies the reviewed draft to the Journey and
+ * removes the draft. Refuses — writing nothing — when the Journey changed since the draft was made
+ * (its content hash differs) or the draft names steps the Journey does not have.
+ */
+export declare function approveJourneyAnnotations(dir: string, id: string): Promise<ApproveAnnotationsResult>;
+/** `journey run`'s informational intent line (#246): how many steps say why. Never fails a run. */
+export declare function journeyIntentCoverage(dir: string, id: string): Promise<IntentCoverage | undefined>;