@jevitate/cli 0.1.0

package/dist/journey-api.d.ts

@@ -0,0 +1,37 @@
+import { type RunPolicy } from "@jevitate/domain";
+import { type JourneyRunResult, type SelfHealer } from "@jevitate/runtime";
+/**
+ * Distinct from `@jevitate/journey`'s `ParamValidationError` so CLI/API callers
+ * can tell "no such journey" apart from "params didn't match the journey's
+ * schema" without string-matching error messages.
+ */
+export declare class UnknownJourneyError extends Error {
+}
+export interface RunJourneyProgrammaticallyOptions {
+    /** Directory a `FsJourneyStore` reads Journey JSON files from. */
+    dir: string;
+    id: string;
+    params: Record<string, string>;
+    /** Defaults to `safeRunPolicy()` (Slice 1: fail-closed secret mode) when omitted. */
+    policy?: RunPolicy;
+    /**
+     * Optional gated self-heal port (Ticket #7). Only relevant when
+     * `policy.selfHeal.mode !== "fail-closed"`; wired as the `JourneyRunner`'s
+     * 5th constructor arg. When omitted (the default), a divergence quarantines
+     * exactly as before — identical to Slice 1's fail-closed behavior. The
+     * caller (CLI) is responsible for its credential preflight; this surface
+     * never builds AI gateways itself. Writes never auto-heal regardless of
+     * this port (enforced by `JourneyRunner`'s write floor).
+     */
+    selfHealer?: SelfHealer;
+}
+/**
+ * The one programmatic surface for "run this published Journey by id" —
+ * used by BOTH the CLI `journey run` action and external callers. Builds
+ * the real `FsJourneyStore` + `JourneyRegistry`, resolves the journey
+ * (unknown id -> `UnknownJourneyError`), validates params UP FRONT with
+ * `deriveParamSchema`/`validateParams` (unknown/missing param ->
+ * `ParamValidationError`, from `@jevitate/journey`) BEFORE any browser is
+ * launched, then builds the real Actor + `JourneyRunner` and runs.
+ */
+export declare function runJourneyProgrammatically(opts: RunJourneyProgrammaticallyOptions): Promise<JourneyRunResult>;

package/dist/journey-api.js

@@ -0,0 +1,55 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FsJourneyStore, JourneyRegistry, deriveParamSchema, validateParams } from "@jevitate/journey";
+import { safeRunPolicy } from "@jevitate/domain";
+import { PlaywrightBrowserPort } from "@jevitate/playwright";
+import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
+import { RecordingInterpreter } from "@jevitate/interpreter";
+import { JourneyRunner } from "@jevitate/runtime";
+/**
+ * Distinct from `@jevitate/journey`'s `ParamValidationError` so CLI/API callers
+ * can tell "no such journey" apart from "params didn't match the journey's
+ * schema" without string-matching error messages.
+ */
+export class UnknownJourneyError extends Error {
+}
+/**
+ * The one programmatic surface for "run this published Journey by id" —
+ * used by BOTH the CLI `journey run` action and external callers. Builds
+ * the real `FsJourneyStore` + `JourneyRegistry`, resolves the journey
+ * (unknown id -> `UnknownJourneyError`), validates params UP FRONT with
+ * `deriveParamSchema`/`validateParams` (unknown/missing param ->
+ * `ParamValidationError`, from `@jevitate/journey`) BEFORE any browser is
+ * launched, then builds the real Actor + `JourneyRunner` and runs.
+ */
+export async function runJourneyProgrammatically(opts) {
+    const store = new FsJourneyStore(opts.dir);
+    const registry = new JourneyRegistry(store);
+    const journey = await registry.get(opts.id);
+    if (!journey) {
+        throw new UnknownJourneyError(`unknown journey '${opts.id}'`);
+    }
+    // Fail fast: validate BEFORE any browser launch, so bad params never pay
+    // the cost (or risk) of opening a browser.
+    validateParams(deriveParamSchema(journey.recording), opts.params);
+    const policy = opts.policy ?? safeRunPolicy();
+    const profileDir = await mkdtemp(join(tmpdir(), "doit-journey-run-"));
+    const port = new PlaywrightBrowserPort();
+    const session = await port.open({
+        profileDir,
+        headless: true,
+        allowedOrigins: [journey.recording.site],
+        baseUrl: journey.recording.site,
+    });
+    try {
+        const actor = CastActor.named("cli-runner").whoCan(new BrowseTheWeb(session, [journey.recording.site]));
+        const runner = new JourneyRunner(actor, new RecordingInterpreter(), undefined, undefined, opts.selfHealer);
+        return await runner.run({ journey, params: opts.params, policy });
+    }
+    finally {
+        await session.close();
+        await rm(profileDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=journey-api.js.map

package/dist/journey-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey-api.js","sourceRoot":"","sources":["../src/journey-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACvG,OAAO,EAAE,aAAa,EAAkB,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAA0C,MAAM,mBAAmB,CAAC;AAE1F;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;CAAG;AAqBjD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,IAAuC;IAEvC,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,mBAAmB,CAAC,oBAAoB,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IAChE,CAAC;IAED,yEAAyE;IACzE,2CAA2C;IAC3C,cAAc,CAAC,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAElE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;IAE9C,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,mBAAmB,CAAC,CAAC,CAAC;IACtE,MAAM,IAAI,GAAG,IAAI,qBAAqB,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC;QAC9B,UAAU;QACV,QAAQ,EAAE,IAAI;QACd,cAAc,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC;QACxC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,IAAI;KAChC,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,MAAM,CAChD,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CACpD,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,KAAK,EAAE,IAAI,oBAAoB,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3G,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACpE,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC;AACH,CAAC"}

package/dist/load-api.d.ts

@@ -0,0 +1,48 @@
+import { type RunPolicy } from "@jevitate/domain";
+import { type BrowserPort } from "@jevitate/playwright";
+import { type CapacityReport } from "@jevitate/load";
+/** Distinct from `@jevitate/journey`'s ParamValidationError-style "unknown id" cases elsewhere, so CLI callers can branch without string-matching. */
+export declare class UnknownLoadJourneyError extends Error {
+}
+export interface RunJourneyLoadTestOptions {
+    dir: string;
+    id: string;
+    params: Record<string, string>;
+    concurrency: number;
+    iterationsPerActor: number;
+    /**
+     * Governs deterministic actor fan-out/scheduling only (see
+     * `@jevitate/load`'s `RunLoadTestConfig.seed` doc comment) — the real
+     * `JourneyRunner` this function drives per pool member has no pacing
+     * hook, so this `seed` does NOT (yet) produce human-speed pacing of the
+     * real run the way `modeledCapacityReport`'s `seed` drives
+     * `simulateTiming()`. Known gap, deferred to a future slice.
+     */
+    seed: number;
+    authorizedOrigins: readonly string[];
+    /** Defaults to `safeRunPolicy()`, same convention as `journey-api.ts`'s `runJourneyProgrammatically`. */
+    policy?: RunPolicy;
+    /**
+     * Testing seam: overrides the real `PlaywrightBrowserPort` used per pool
+     * member with a fake, so the per-actor browser-session lifecycle (see
+     * `runnerFactory` below) can be unit-tested with no real browser. Defaults
+     * to `() => new PlaywrightBrowserPort()`.
+     */
+    browserPortFactory?: () => BrowserPort;
+}
+/**
+ * The programmatic surface behind `jevitate load run` — resolves a published
+ * Journey (unknown id -> `UnknownLoadJourneyError`), validates params UP
+ * FRONT, then hands `@jevitate/load`'s `runLoadTest` a factory that opens ONE
+ * real headless Playwright session + `JourneyRunner` per pool member. The
+ * authorized-target check happens inside `runLoadTest` itself — this
+ * function does not duplicate or bypass it.
+ *
+ * NOTE on "seeded ⇒ reproducible / human-paced" (corrected post-review):
+ * `opts.seed` makes the ACTOR POOL's composition reproducible (via
+ * `deriveActorSeeds` inside `runLoadTest`) — it does not yet make the real
+ * run human-paced, because `JourneyRunner` (constructed below) has no
+ * pacing hook to seed. Only the offline `modeledCapacityReport` path is
+ * genuinely human-paced today, via `@jevitate/domain`'s `simulateTiming()`.
+ */
+export declare function runJourneyLoadTest(opts: RunJourneyLoadTestOptions): Promise<CapacityReport>;

package/dist/load-api.js

@@ -0,0 +1,84 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { FsJourneyStore, JourneyRegistry, deriveParamSchema, validateParams } from "@jevitate/journey";
+import { safeRunPolicy } from "@jevitate/domain";
+import { PlaywrightBrowserPort } from "@jevitate/playwright";
+import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
+import { RecordingInterpreter } from "@jevitate/interpreter";
+import { JourneyRunner } from "@jevitate/runtime";
+import { runLoadTest } from "@jevitate/load";
+/** Distinct from `@jevitate/journey`'s ParamValidationError-style "unknown id" cases elsewhere, so CLI callers can branch without string-matching. */
+export class UnknownLoadJourneyError extends Error {
+}
+/**
+ * The programmatic surface behind `jevitate load run` — resolves a published
+ * Journey (unknown id -> `UnknownLoadJourneyError`), validates params UP
+ * FRONT, then hands `@jevitate/load`'s `runLoadTest` a factory that opens ONE
+ * real headless Playwright session + `JourneyRunner` per pool member. The
+ * authorized-target check happens inside `runLoadTest` itself — this
+ * function does not duplicate or bypass it.
+ *
+ * NOTE on "seeded ⇒ reproducible / human-paced" (corrected post-review):
+ * `opts.seed` makes the ACTOR POOL's composition reproducible (via
+ * `deriveActorSeeds` inside `runLoadTest`) — it does not yet make the real
+ * run human-paced, because `JourneyRunner` (constructed below) has no
+ * pacing hook to seed. Only the offline `modeledCapacityReport` path is
+ * genuinely human-paced today, via `@jevitate/domain`'s `simulateTiming()`.
+ */
+export async function runJourneyLoadTest(opts) {
+    const store = new FsJourneyStore(opts.dir);
+    const registry = new JourneyRegistry(store);
+    const journey = await registry.get(opts.id);
+    if (!journey) {
+        throw new UnknownLoadJourneyError(`unknown journey '${opts.id}'`);
+    }
+    validateParams(deriveParamSchema(journey.recording), opts.params);
+    const policy = opts.policy ?? safeRunPolicy();
+    const browserPortFactory = opts.browserPortFactory ?? (() => new PlaywrightBrowserPort());
+    return runLoadTest({
+        targetOrigin: journey.recording.site,
+        authorizedOrigins: opts.authorizedOrigins,
+        concurrency: opts.concurrency,
+        iterationsPerActor: opts.iterationsPerActor,
+        seed: opts.seed,
+        runnerFactory: async (actorIndex) => {
+            const profileDir = await mkdtemp(join(tmpdir(), `doit-load-actor-${actorIndex}-`));
+            const port = browserPortFactory();
+            const session = await port.open({
+                profileDir,
+                headless: true,
+                allowedOrigins: [journey.recording.site],
+                baseUrl: journey.recording.site,
+            });
+            const actor = CastActor.named(`load-actor-${actorIndex}`).whoCan(new BrowseTheWeb(session, [journey.recording.site]));
+            const runner = new JourneyRunner(actor, new RecordingInterpreter());
+            // `runLoadTest` calls `run()` exactly `iterationsPerActor` times for
+            // this actor — success or failure, never more, never fewer (see
+            // measured-load-runner.ts's per-actor loop). Closing the real browser
+            // session on EVERY `run()` would defeat pooling (a fresh browser
+            // launch per iteration); never closing it leaks a Chromium process +
+            // tmp profile dir per actor per invocation, worse as `--concurrency`
+            // scales — the whole point of a load harness. So: reuse one session
+            // across this actor's iterations, and close it in a `finally` once
+            // the LAST iteration finishes OR throws — mirroring `journey-api.ts`'s
+            // `try { ... } finally { await session.close(); }`.
+            let remainingIterations = opts.iterationsPerActor;
+            return {
+                run: async () => {
+                    try {
+                        return await runner.run({ journey, params: opts.params, policy });
+                    }
+                    finally {
+                        remainingIterations--;
+                        if (remainingIterations <= 0) {
+                            await session.close();
+                            await rm(profileDir, { recursive: true, force: true });
+                        }
+                    }
+                },
+            };
+        },
+    });
+}
+//# sourceMappingURL=load-api.js.map

package/dist/load-api.js.map

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

package/dist/mcp-api.d.ts

@@ -0,0 +1,116 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type AiGenerateTextArgs, type AiGenerateTextResult } from "@jevitate/mcp-facade";
+import { type CredentialStore, type GenerationPort, type SetupRequiredResult } from "@jevitate/ai-core";
+/**
+ * The MCP stdio server behind `jevitate mcp`. It exposes ONLY the tools in
+ * `@jevitate/mcp-facade`'s `ALLOWED_TOOLS` and structurally CANNOT serve any
+ * of `FORBIDDEN_TOOLS` (the raw browser primitives): the served surface is
+ * derived from `ALLOWED_TOOLS`, every descriptor is re-checked against the
+ * allow/forbid sets at build time (`assertAllowlisted`), and the call
+ * dispatcher refuses any name that is forbidden or not in the served map.
+ *
+ * `buildMcpTools` is the unit-testable seam — a test can enumerate the served
+ * tool names (and exercise each handler) WITHOUT opening a stdio transport.
+ * `startMcpServer` is the only place a real `StdioServerTransport` is opened.
+ */
+export interface McpToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (args: Record<string, unknown>) => Promise<McpToolResult>;
+}
+export interface McpApiDeps {
+    /** Journeys store directory (`~/.jevitate/journeys` in production). */
+    journeysDir: string;
+    /**
+     * Test seam. Defaults to the real promoted-only projection over the
+     * journeys store (`@jevitate/mcp-facade`'s `findCapabilities`).
+     */
+    findCapabilities?: (query: string) => Promise<unknown>;
+    /**
+     * Test seam. Defaults to `runJourneyProgrammatically` with a fail-closed
+     * `safeRunPolicy()` (invariant #5: PUBLISHED-id-only, never inline steps).
+     */
+    runJourney?: (id: string, params: Record<string, string>) => Promise<unknown>;
+    /**
+     * Promoted mission-target store directory (`~/.jevitate/missions/targets` in
+     * production — the SAME store `jevitate mission target` writes). Required for
+     * the default `queue_exploration` wiring; the host resolves it.
+     */
+    missionTargetsDir?: string;
+    /** Mission queue directory (`~/.jevitate/missions/queue` in production). */
+    missionQueueDir?: string;
+    /**
+     * Inbox store directory (`~/.jevitate/inbox` in production) backing all 8
+     * `list_incoming`/`get_command`/`get_thread`/`queue_action`/
+     * `queue_retrieval`/`approve_action`/`cancel_command`/`get_site_health`
+     * tools. The `FsInboxStore` is built lazily inside each handler's closure
+     * (mirrors `queueExploration`'s lazy store) so constructing the tool set
+     * never touches disk. A missing/unconfigured dir is a config error (a
+     * refusal), never a silent success.
+     */
+    inboxDir?: string;
+    /**
+     * Test seam. Defaults to `@jevitate/mcp-facade`'s `queueExploration` over the
+     * fs-backed promoted `MissionTargetRegistry` + `FsMissionQueueStore`. Never
+     * runs a mission — only enqueues; refuses unknown/unpromoted targets and
+     * over-ceiling budgets (all validation delegated to `enqueueMission`).
+     */
+    queueExploration?: (args: unknown) => Promise<unknown>;
+    /**
+     * Credential store for `ai_generate_text`'s preflight gate. Defaults to
+     * `envCredentialStore()` (env + gitignored local config). `detect` never
+     * returns a value; the key value is read ONLY at the provider call, inside
+     * the gateway, and placed only in the Authorization header.
+     */
+    credentialStore?: CredentialStore;
+    /**
+     * Generation gateway for `ai_generate_text`. Provided by the host (the real
+     * `OpenRouterGenerationGateway`, which routes every outbound payload through
+     * the never-to-model credential guard). When ABSENT and no `aiGenerateText`
+     * seam is injected, `ai_generate_text` stays a typed `not_implemented`
+     * rather than fabricating an answer.
+     */
+    generationGateway?: GenerationPort;
+    /**
+     * Test seam. Defaults to `@jevitate/mcp-facade`'s `aiGenerateText`
+     * (`credentialStore` + `generationGateway`), preflight-gated so a missing key
+     * returns a typed `setup_required` result instead of calling the model.
+     */
+    aiGenerateText?: (args: AiGenerateTextArgs) => Promise<AiGenerateTextResult | SetupRequiredResult>;
+}
+/**
+ * Builds the served tool descriptors — EXACTLY one per `ALLOWED_TOOLS` entry.
+ * Wired to their real backing services: `find_capabilities` + `run_journey`
+ * (journey store), `queue_exploration` (`@jevitate/missions` enqueue over the
+ * promoted `MissionTargetRegistry`), and `ai_generate_text` (`@jevitate/ai-core`
+ * generation gateway behind a fail-closed credential preflight). The remaining
+ * allowlisted tools — the inbox/command-queue surface — are registered (so the
+ * served set equals `ALLOWED_TOOLS`) but respond with a typed `not_implemented`
+ * error, since no facade-level backing service exists for them in this slice.
+ * No handler ever fabricates a success.
+ */
+export declare function buildMcpTools(deps: McpApiDeps): McpTool[];
+/**
+ * Constructs the MCP `Server` and registers its `tools/list` and `tools/call`
+ * handlers off `buildMcpTools`. Does NOT open a transport — that is
+ * `startMcpServer`'s job — so this is safe to construct in a unit test.
+ */
+export declare function createMcpServer(deps: McpApiDeps): Server;
+/**
+ * Starts the real MCP stdio server. Blocks (the transport owns stdin/stdout)
+ * until the client disconnects — callers must NOT write to stdout while it
+ * runs, since stdout is the MCP protocol channel.
+ */
+export declare function startMcpServer(deps: McpApiDeps): Promise<void>;