@jevitate/cli 0.1.0 → 0.3.0

package/dist/load-api.js

@@ -1,13 +1,14 @@
-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 { gateJourney } from "./site-gate-cli.js";
 import { safeRunPolicy } from "@jevitate/domain";
 import { PlaywrightBrowserPort } from "@jevitate/playwright";
+import { sessionLaunchOptions } from "./browser-run-options.js";
 import { CastActor, BrowseTheWeb } from "@jevitate/screenplay";
 import { RecordingInterpreter } from "@jevitate/interpreter";
 import { JourneyRunner } from "@jevitate/runtime";
 import { runLoadTest } from "@jevitate/load";
+import { JourneyRequiresAuthError } from "./journey-api.js";
+import { applyJourneyEnvironment } from "./environments.js";
 /** Distinct from `@jevitate/journey`'s ParamValidationError-style "unknown id" cases elsewhere, so CLI callers can branch without string-matching. */
 export class UnknownLoadJourneyError extends Error {
 }
@@ -21,18 +22,25 @@ export class UnknownLoadJourneyError extends Error {
  *
  * 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()`.
+ * `deriveActorSeeds` inside `runLoadTest`), and — with a site policy that declares pacing — each
+ * actor's clicks and keystrokes are human-paced, seeded from `seed` and the actor's index. A load
+ * run is the operator's deliberate burst: the policy's throttles, budgets and quiet hours do not
+ * refuse it; only its pacing applies.
  */
 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) {
+    const stored = await registry.get(opts.id);
+    if (!stored) {
         throw new UnknownLoadJourneyError(`unknown journey '${opts.id}'`);
     }
+    const journey = applyJourneyEnvironment(stored, opts.environment);
+    const allowedOrigins = opts.environment === undefined ? [journey.recording.site] : [...opts.environment.allowedOrigins];
+    // #118: a Journey that declares it needs auth refuses BEFORE any browser launch when no
+    // storageState was given — a clear, typed failure instead of a deep `replay-target-not-found`.
+    if (journey.metadata.requiresAuth === true && opts.storageState === undefined) {
+        throw new JourneyRequiresAuthError(`journey '${opts.id}' requires auth (metadata.requiresAuth) — run with --storage-state <file>`);
+    }
     validateParams(deriveParamSchema(journey.recording), opts.params);
     const policy = opts.policy ?? safeRunPolicy();
     const browserPortFactory = opts.browserPortFactory ?? (() => new PlaywrightBrowserPort());
@@ -43,15 +51,16 @@ export async function runJourneyLoadTest(opts) {
         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],
+                ...sessionLaunchOptions(opts.browser),
+                allowedOrigins,
                 baseUrl: journey.recording.site,
+                ...opts.emulation,
+                ...(opts.storageState !== undefined ? { storageState: opts.storageState } : {}),
             });
-            const actor = CastActor.named(`load-actor-${actorIndex}`).whoCan(new BrowseTheWeb(session, [journey.recording.site]));
+            const gate = await gateJourney(opts.siteGate, journey.recording, { enforceLimits: false, runId: `load-${opts.seed}-${actorIndex}` });
+            const actor = CastActor.named(`load-actor-${actorIndex}`).whoCan(new BrowseTheWeb(session, allowedOrigins), ...gate.abilities);
             const runner = new JourneyRunner(actor, new RecordingInterpreter());
             // `runLoadTest` calls `run()` exactly `iterationsPerActor` times for
             // this actor — success or failure, never more, never fewer (see
@@ -73,7 +82,6 @@ export async function runJourneyLoadTest(opts) {
                         remainingIterations--;
                         if (remainingIterations <= 0) {
                             await session.close();
-                            await rm(profileDir, { recursive: true, force: true });
                         }
                     }
                 },

package/dist/load-api.js.map

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

package/dist/load-cli.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import { type CliDeps } from "./cli-shared.js";
+/** Registers `jevitate load run`. */
+export declare function registerLoadCommands(program: Command, deps: CliDeps): void;

package/dist/load-cli.js

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import { ok, fail } from "./envelope.js";
+import { JourneyRequiresAuthError } from "./journey-api.js";
+import { runJourneyLoadTest, UnknownLoadJourneyError } from "./load-api.js";
+import { withSiteGate } from "./site-gate-cli.js";
+import { withEngine } from "./engine.js";
+import { finiteNumberArg, positiveIntArg } from "./cli-args.js";
+import { environmentFromFlags, isEnvironmentError, withEnvironmentFlags } from "./environments.js";
+import { resolveDbPath, resolveJourneysDir, withBrowserLaunchFlags, browserOption, withEmulationFlags, emulationFromFlags, collectParam, emitJson, environmentSeams, } from "./cli-shared.js";
+/** Registers `jevitate load run`. */
+export function registerLoadCommands(program, deps) {
+    const load = program.command("load").description("run a promoted Journey as a load test");
+    withEnvironmentFlags(withBrowserLaunchFlags(withEmulationFlags(load.command("run <journeyId>"))))
+        .option("--dir <path>", "journeys directory (default: the repo's .jevitate/journeys; outside a repo ~/.jevitate/journeys)")
+        .option("--param <kv>", "param as key=value (repeatable)", collectParam, {})
+        // `--authorized-origin` is mandatory, but enforced IN THE ACTION (below)
+        // via a `fail` envelope rather than commander's `.requiredOption` — which
+        // hard-exits via `process.exit`, inconsistent with this CLI's convention
+        // of emitting a JSON envelope + setting `process.exitCode` (see emitJson).
+        .option("--authorized-origin <origin>", "allowed load-test target origin (repeatable) — required, fails closed if omitted", (v, prev) => [...prev, v], [])
+        .option("--concurrency <n>", "pool size", positiveIntArg, 1)
+        .option("--iterations <n>", "iterations per actor", positiveIntArg, 1)
+        .option("--seed <n>", "master RNG seed", finiteNumberArg, 1)
+        .option("--storage-state <file>", "Playwright storageState JSON to start every actor's session authenticated (#118: required when the journey declares metadata.requiresAuth); must exist")
+        .option("--json", "emit a JSON envelope")
+        .action(async function (journeyId) {
+        const { dir, param, authorizedOrigin, concurrency, iterations, seed, storageState: storageStateFlag, json, env: envName, baseUrl, ...emulationFlags } = this.opts();
+        if (authorizedOrigin.length === 0) {
+            emitJson(program, fail("E_LOAD_RUN", "at least one --authorized-origin is required (refusing to load-test with an empty allowlist)"));
+            return;
+        }
+        // #247: --env/--base-url choose where the load runs (unknown env / bad file → 64, nothing opened).
+        let environment;
+        try {
+            environment = environmentFromFlags({ ...(envName === undefined ? {} : { env: envName }), ...(baseUrl === undefined ? {} : { baseUrl }) }, environmentSeams(deps));
+        }
+        catch (err) {
+            if (!isEnvironmentError(err))
+                throw err;
+            emitJson(program, fail(err.code, err.message));
+            return;
+        }
+        const storageState = storageStateFlag ?? environment?.storageState;
+        if (storageState !== undefined && !existsSync(storageState)) {
+            emitJson(program, fail("E_LOAD_RUN_ARGS", `storage state not found: ${storageState}`));
+            return;
+        }
+        let loadRunEmulation;
+        try {
+            loadRunEmulation = emulationFromFlags(emulationFlags);
+        }
+        catch (err) {
+            emitJson(program, fail("E_LOAD_RUN_ARGS", err instanceof Error ? err.message : String(err)));
+            return;
+        }
+        try {
+            const report = await withSiteGate(resolveDbPath(deps), (siteGate) => runJourneyLoadTest({
+                ...(siteGate === undefined ? {} : { siteGate }),
+                dir: resolveJourneysDir(deps, dir),
+                id: journeyId,
+                params: param,
+                concurrency: Number(concurrency),
+                iterationsPerActor: Number(iterations),
+                seed: Number(seed),
+                authorizedOrigins: authorizedOrigin,
+                browserPortFactory: deps.explore?.browserPortFactory,
+                ...browserOption(this.opts()),
+                ...(loadRunEmulation === undefined ? {} : { emulation: loadRunEmulation }),
+                ...(storageState !== undefined ? { storageState } : {}),
+                ...(environment === undefined ? {} : { environment }),
+            })).then((r) => withEngine(r));
+            const envelope = ok(report);
+            if (json) {
+                emitJson(program, envelope);
+            }
+            else {
+                program.configureOutput().writeOut?.(`${JSON.stringify(report, null, 2)}\n`);
+                process.exitCode = 0;
+            }
+        }
+        catch (err) {
+            if (isEnvironmentError(err)) {
+                emitJson(program, fail(err.code, err.message));
+            }
+            else if (err instanceof UnknownLoadJourneyError) {
+                emitJson(program, fail("E_UNKNOWN_JOURNEY", String(err.message)));
+            }
+            else if (err instanceof JourneyRequiresAuthError) {
+                emitJson(program, fail("E_JOURNEY_REQUIRES_AUTH", String(err.message)));
+            }
+            else {
+                emitJson(program, fail("E_LOAD_RUN", String(err instanceof Error ? err.message : err)));
+            }
+        }
+    });
+}
+//# sourceMappingURL=load-cli.js.map

package/dist/load-cli.js.map

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

package/dist/log-correlation.d.ts

@@ -0,0 +1,200 @@
+import { type MissionOutcome } from "@jevitate/domain";
+import { type TranscriptEntry } from "@jevitate/explore";
+import { type LogSourceSpec } from "./log-sources.js";
+import { type LogDefectMatcher, type LogIgnoreMatcher, type LogLevel } from "./log-lines.js";
+import { type RequestEvents } from "./log-trace.js";
+/**
+ * Correlates tailed backend log lines to the mission step they landed during (#142): each step's
+ * "window" runs from the previous step's settle time to this step's own settle time (a mission's
+ * `TranscriptListener` fires the moment a step is recorded — already the crash-safe incremental-
+ * flush seam `MissionJournal` uses, per-step wall-clock epochs come for free from `Date.now()` at
+ * that call, with no change needed to `@jevitate/explore`'s mission loop). The LAST step's window
+ * is additionally held open for `drainMs` (`--server-log-drain-ms`) so async backend work that
+ * settles after the browser gave up is still caught, never blocking the mission itself: the
+ * runtime's own await (waiting out the drain) happens AFTER the mission function has already
+ * returned.
+ *
+ * Fail closed: every line is redacted with the run's own secret list before it is ever attached to
+ * a step, turned into a defect, or counted in the summary — a log line can contain secrets the page
+ * never showed.
+ *
+ * #204 — by trace / correlation id first: a line that carries an id one of the run's requests sent
+ * or received (`traceparent`, `x-request-id`, …; see `log-trace.ts`) is attached to EXACTLY that
+ * request (`request: { method, url, status, id }`) and to the step that sent it, whenever it
+ * landed. Only a line with no id falls back to the time window. Once ids demonstrably correlate, a
+ * line carrying ANOTHER id is other work (another user, a background job) and is never this run's.
+ *
+ * #282 — `--log-scope`: when given, only lines matching it (a tenant id, a run marker) are
+ * attributed; the rest count as `ignoredLines`. A line carrying one of the run's ids is in scope.
+ */
+export interface ServerLogEvidence {
+    readonly level: LogLevel;
+    /** Redacted human message. */
+    readonly message: string;
+    /** Redacted raw line. */
+    readonly raw: string;
+    readonly source: string;
+    readonly epochMs: number;
+    /** The logger's own target/category, when known (#169). */
+    readonly target?: string;
+    /**
+     * #204: the run's request this line was correlated to by a trace/correlation id it carries —
+     * method, redacted URL, response status (null: no response) and the id. Unset: attached by time.
+     */
+    readonly request?: ServerLogRequest;
+}
+/** #204: the request a server log line belongs to, by a correlation id both carry. */
+export interface ServerLogRequest {
+    readonly method: string;
+    readonly url: string;
+    readonly status: number | null;
+    readonly id: string;
+}
+export type TranscriptEntryWithLogs = TranscriptEntry & {
+    readonly serverLogs?: readonly ServerLogEvidence[];
+};
+export interface ServerLogSourceStatus {
+    readonly spec: string;
+    readonly opened: boolean;
+    readonly linesRead: number;
+    readonly truncated: boolean;
+    readonly error?: string;
+    /** True when this source was declared `--log-quiet-ok` (#169): zero lines from it is expected,
+     *  not a sign the oracle never actually watched the backend. */
+    readonly quietOk?: boolean;
+}
+export interface ServerLogTopMessage {
+    readonly level: LogLevel;
+    /** Normalized message class (ids/numbers/uuids/timestamps stripped). */
+    readonly message: string;
+    /** The logger's own target/category, when known (#169) — kept distinct in this summary too. */
+    readonly target?: string;
+    readonly count: number;
+}
+export interface ServerLogsSummary {
+    readonly sources: readonly ServerLogSourceStatus[];
+    readonly byLevel: Readonly<Record<string, number>>;
+    readonly topMessages: readonly ServerLogTopMessage[];
+    readonly attachedLines: number;
+    readonly unattributedLines: number;
+    /** Lines excluded by `--log-ignore` (#169 item 3) — known noise, never attached, never a defect
+     *  candidate, not counted in `byLevel`/`topMessages` — plus lines outside `--log-scope` (#282) and
+     *  lines carrying another request's correlation id (#204), broken down in `correlation`. */
+    readonly ignoredLines: number;
+    /**
+     * #204/#282: how lines were correlated — set when a request carried a correlation id or
+     * `--log-scope` was given. `idMatchedLines`: attached to their exact request by id;
+     * `foreignLines`: carried another request's id (never this run's); `outOfScopeLines`: outside
+     * `--log-scope`. The last two are included in `ignoredLines`.
+     */
+    readonly correlation?: {
+        readonly requestsWithIds: number;
+        readonly idMatchedLines: number;
+        readonly foreignLines: number;
+        readonly outOfScopeLines: number;
+    };
+    /**
+     * False when `--log-defect` was given but at least one declared source is unhealthy: it never
+     * opened/errored, OR it opened and delivered not one line while NOT declared `--log-quiet-ok`
+     * (#169) — an absence of `server-log` defects then proves nothing about the backend; it must never
+     * be read as "held"/clean (#142).
+     */
+    readonly oracleOk: boolean;
+    /** Why `oracleOk` is false — which source(s), and whether they failed to open or were silently
+     *  quiet. Unset when `oracleOk` is true. */
+    readonly oracleReason?: string;
+}
+export interface ServerLogDefect {
+    readonly fingerprint: string;
+    readonly related: string[];
+    readonly kind: "server-log";
+    readonly title: string;
+    readonly route: string;
+    readonly level: LogLevel;
+    /** First occurrence's redacted message. */
+    readonly message: string;
+    readonly occurrences: number;
+    readonly repro: {
+        readonly recordingStepIndex: number;
+    };
+    /** #204: the request the first occurrence was correlated to by id, when it was. */
+    readonly request?: ServerLogRequest;
+    /** So `verify-fix` can re-open the SAME sources and re-check the SAME matcher (#142). */
+    readonly serverLog: {
+        readonly sources: readonly string[];
+        readonly matcher: string;
+        readonly normalizedMessage: string;
+        readonly drainMs: number;
+        /** #282: the run's `--log-scope` (raw specs): verify-fix counts only lines in scope too. */
+        readonly scope?: readonly string[];
+    };
+}
+export interface ServerLogRuntimeResult {
+    readonly transcript: readonly TranscriptEntryWithLogs[];
+    readonly summary: ServerLogsSummary;
+    readonly defects: ServerLogDefect[];
+}
+export declare const DEFAULT_SERVER_LOG_DRAIN_MS = 3000;
+export interface ServerLogRuntimeOptions {
+    readonly sources: readonly LogSourceSpec[];
+    /** Already-parsed `--log-defect` matchers (empty ⇒ evidence attachment only, no defects). */
+    readonly logDefect: readonly LogDefectMatcher[];
+    readonly drainMs?: number;
+    readonly secrets: readonly string[];
+    /** Raw `--log-source` specs (matched against a source's own `spec.raw`) that are allowed to
+     *  deliver zero lines without making `oracleOk` false (#169's `--log-quiet-ok`). */
+    readonly quietOk?: readonly string[];
+    /** Already-parsed `--log-ignore` matchers (#169 item 3): known-noise lines excluded from
+     *  correlation AND the defect oracle, counted separately (`serverLogs.ignoredLines`). */
+    readonly logIgnore?: readonly LogIgnoreMatcher[];
+    /** #282: `--log-scope` matchers (same `/regex/` or substring grammar as `--log-ignore`): only lines
+     *  matching one are attributed (or carrying one of the run's correlation ids); the rest are ignored. */
+    readonly logScope?: readonly LogIgnoreMatcher[];
+    /** #204: extra response/request headers carrying a correlation id (`--log-correlation-header`). */
+    readonly correlationHeaders?: readonly string[];
+    /** #204: `--log-id-pattern`s: how an id is written in a log line of the operator's own format. */
+    readonly idPatterns?: readonly RegExp[];
+    /** The journal's own listener — still called for every entry (the crash-safe flush is unchanged). */
+    readonly onTranscriptEntry?: (entry: TranscriptEntry, all: readonly TranscriptEntry[]) => void;
+}
+/**
+ * Opens every source and starts correlating (#142). Returns `undefined` when `sources` is empty —
+ * a complete no-op, so a run without `--log-source` pays nothing.
+ */
+export declare function openServerLogRuntime(opts: ServerLogRuntimeOptions): ServerLogRuntime | undefined;
+export declare class ServerLogRuntime {
+    #private;
+    constructor(opts: ServerLogRuntimeOptions);
+    /**
+     * #204: records the correlation ids of every request this page sends and receives. Call before
+     * the page's first navigation (the seed load's requests count too).
+     */
+    observe(page: RequestEvents): void;
+    /** Wraps the journal's own `TranscriptListener`: unchanged persistence, plus this step's epoch. */
+    readonly onTranscriptEntry: (entry: TranscriptEntry, all: readonly TranscriptEntry[]) => void;
+    /** Call once the mission function has returned. Waits out the drain window, closes every source,
+     *  and returns the correlated transcript/summary/defects. Idempotent (a second call is a no-op
+     *  empty result) — never blocks the mission itself, only this post-processing step. */
+    finish(transcript: readonly TranscriptEntry[]): Promise<ServerLogRuntimeResult>;
+    /**
+     * Safety net for the mission-threw-before-`finish` path: closes every source immediately, with NO
+     * drain wait and no correlation. A no-op once `finish` already ran. Never throws.
+     */
+    abort(): Promise<void>;
+}
+/** Parses `--log-defect` values, failing closed on the first bad one. */
+export declare function parseLogDefectSpecs(raw: readonly string[]): LogDefectMatcher[];
+/** Parses `--log-ignore` values, failing closed on the first bad one (#169 item 3). */
+export declare function parseLogIgnoreSpecs(raw: readonly string[]): LogIgnoreMatcher[];
+/** Parses `--log-scope` values (#282): the `--log-ignore` grammar, a `/regex/flags/` or a substring. */
+export declare function parseLogScopeSpecs(raw: readonly string[]): LogIgnoreMatcher[];
+/**
+ * Folds a server-log correlation result into an already-computed `MissionOutcome` (#142, follow-up
+ * on the exit-code requirement): a found `server-log` defect is at least `defects-found` — via
+ * `worstOutcome`, so it never DOWNGRADES a worse outcome (hang/crashed/inconclusive already proves
+ * more, or the same, than a defect). An unreadable `--log-defect` oracle (`oracleOk: false`) turns
+ * an otherwise-`clean` run `inconclusive` — its absence of defects proves nothing when the source
+ * that would have caught them was never demonstrably read. `undefined` (no `--log-source`) is a
+ * complete no-op.
+ */
+export declare function applyServerLogOutcome(outcome: MissionOutcome, run: ServerLogRuntimeResult | undefined): MissionOutcome;