@jevitate/cli 0.1.0 → 0.3.0

package/dist/mcp-cli-tools.d.ts

@@ -0,0 +1,129 @@
+import { type McpArgs } from "./mcp-args.js";
+import type { McpCliRunner } from "./mcp-cli-runner.js";
+/**
+ * #255 — MCP ⊇ CLI. Every CLI command an agent could run as `jevitate … --json` is reachable over
+ * MCP (MCP is a convenience and an optimization for LLMs, not a separate product surface). The
+ * tools here MIRROR a CLI command: their typed arguments map one-to-one onto that command's flags
+ * and positional arguments, and the handler runs the command in process (mcp-cli-runner.ts) and
+ * returns its JSON envelope and exit code. The CLI does every check it always does — so the two
+ * surfaces validate, confine, redact and exit identically — and MCP adds its own strictness on top:
+ *
+ * - arguments are typed and closed: an unknown argument or a wrong type is `invalid_args`, never
+ *   ignored or coerced;
+ * - every path argument is confined (mcp-paths.ts): inside the project or `~/.jevitate/`, and a
+ *   storage state never under a repo's `.jevitate/`;
+ * - the argv is built by code, never parsed from caller text: options are passed as
+ *   `--flag=value` and positionals after `--`, so no argument value can become a flag;
+ * - flags that are the OPERATOR's call are not MCP arguments at all (`omitted`, each with its
+ *   reason, checked against the real commander tree by mcp-cli-parity.test.ts): shell hooks, the
+ *   browser binary/switches, which environment variable a secret is read from, `cmd:` log sources,
+ *   store directories.
+ *
+ * Long-running commands follow the existing MCP pattern: a single browser run on one Journey,
+ * finding or suite (run_journey, verify_fix, and here annotate/demo/check/regressions/load/…)
+ * runs DIRECTLY and returns its verdict; open-ended exploration against a promoted target is
+ * queue + poll (queue_exploration → run_queued_missions/`mission run` → get_mission_result). A
+ * direct exploration (`explore`) is `run_exploration`, bounded by its own budget flags.
+ *
+ * The result: `{exitCode, data}` (the envelope's data). Exit 0/1/3/4 are answers (1 = defects /
+ * still reproduces, 3 = hang, 4 = intermittent) and come back as a normal result; exit 2 (the run
+ * proved nothing) and every refusal come back as an MCP error result — never a pass. A refusal is
+ * `{error: "invalid_args" (exit 64) | "refused", code: "E_…", message, exitCode}`.
+ */
+export type CliParamKind = 
+/** `--flag=<value>` (or a positional). */
+"string"
+/** A non-negative integer (`--flag=<n>`). */
+ | "integer"
+/** A number (ratios, confidences). */
+ | "number"
+/** `true` → `--flag`; `false`/absent → nothing. For a `--no-x` flag: `false` → `--no-x`. */
+ | "boolean"
+/** A repeatable flag (`--flag=a --flag=b`) or a variadic positional. */
+ | "string[]"
+/** `--param k=v` per entry (a string→string map). */
+ | "params"
+/** A path the command reads (confined). */
+ | "path"
+/** Repeatable read paths (confined). */
+ | "path[]"
+/** A Playwright storage state (confined; never under a repo's `.jevitate/`). */
+ | "session"
+/** `true` or a directory (confined) — `--record-video [dir]`-style optional values. */
+ | "optional-path"
+/** `true` or a storage-state path (confined as a session) — `--save-storage-state [file]`. */
+ | "optional-session"
+/** `--screenshots [mode|dir]` (any directory confined). */
+ | "screenshots"
+/** `{width, height}` → `--viewport WxH`. */
+ | "viewport"
+/** `name=<storageState>` entries (`--persona`/`--actor`): each path confined as a session. */
+ | "named-sessions"
+/** `<descriptor>=<file>` entries (`--type-fixture`): the file (after the LAST `=`) confined as a read path. */
+ | "bound-paths";
+export interface CliParam {
+    readonly kind: CliParamKind;
+    /** The long flag (`--env`); absent for a positional. */
+    readonly flag?: string;
+    /** A positional argument (in declaration order). */
+    readonly positional?: true;
+    readonly required?: true;
+    /** A closed set of string values. */
+    readonly enum?: readonly string[];
+}
+export interface CliCommandSpec {
+    /** The commander path, e.g. `journey annotate`. */
+    readonly path: string;
+    readonly params: Readonly<Record<string, CliParam>>;
+    /** Every flag of the command that is NOT an MCP argument, with why (checked by the parity guard). */
+    readonly omitted: Readonly<Record<string, string>>;
+}
+export interface CliToolSpec {
+    readonly name: string;
+    readonly description: string;
+    /** One command, or several selected by an `action` argument (a family of small commands). */
+    readonly command?: CliCommandSpec;
+    readonly actions?: Readonly<Record<string, CliCommandSpec>>;
+}
+export declare const OMIT: {
+    readonly json: "always set: the tool returns the command's JSON envelope";
+    readonly hooks: "operator shell hooks run commands on this machine: never model-chosen (--allow-shell-hooks is never set over MCP; an environment's hooks refuse as on the CLI without it)";
+    readonly browserBin: "which browser binary, channel and Chromium switches launch is the operator's setting (the server's own launch), never an MCP argument";
+    readonly storeDir: "store and results locations are the server's (the `jevitate mcp` defaults / --dir): an MCP argument never picks which directory is read or written as a store";
+    readonly envSecret: "binds an environment variable (or a literal secret) the run types or redacts: a request never chooses which of the operator's variables is read — secret fields come from targets.json (secretFields/personas)";
+    readonly logCmd: "server-log sources can run commands and read arbitrary files: operator-declared only (targets.json logSources/allowLogCmd)";
+    readonly hangWrites: "re-sending a paid/destructive write is the operator's call (targets.json safety.hangReplayWrites)";
+    readonly filingRepo: "where findings are filed (a GitHub repo, under the operator's identity) is the operator's filing config (~/.jevitate/filing.json)";
+    readonly watch: "a watch loop never returns: MCP drains once (call again to drain more)";
+    readonly branchParams: "#293: a branch-point finding replays through its Journey prefix with the params its result recorded (non-secret ones); a secret param is re-supplied by the operator on the CLI, never sent as an MCP argument";
+    readonly tou: "accepting a third-party source's Terms of Use is a person's decision (like approve_action): MCP can add, pull and run a source, never accept for them";
+    readonly hostLoad: "#205: starting a browser run on a STARVED host (overriding E_HOST_STARVED) can take the machine other people's work runs on down with it: the operator's call, never a request's";
+};
+export declare const CLI_TOOL_SPECS: readonly CliToolSpec[];
+/** The MCP inputSchema for a CLI-backed tool (a family adds the `action` discriminator). */
+export declare function cliToolInputSchema(spec: CliToolSpec): {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+    additionalProperties: false;
+};
+/** The command an invocation selects (validating `action` for a family). */
+export declare function commandFor(spec: CliToolSpec, args: McpArgs): CliCommandSpec;
+/**
+ * The argv for one invocation: `<path…> --flag=value… --json -- <positionals…>`. Options use the
+ * `=` form and positionals follow `--`, so no value can ever be read as a flag.
+ */
+export declare function buildCliArgv(spec: CliToolSpec, args: McpArgs, roots: readonly string[]): string[];
+export interface CliToolOutcome {
+    readonly isError: boolean;
+    readonly body: Record<string, unknown>;
+}
+/**
+ * Runs one CLI-backed tool call: argv from the typed arguments, the CLI in process, its envelope back.
+ * `redact` strips credential values from the output text (belt-and-braces over the CLI's own redaction).
+ */
+export declare function runCliTool(spec: CliToolSpec, args: McpArgs, deps: {
+    runCli?: McpCliRunner;
+    roots: readonly string[];
+    redact: (text: string) => string;
+}): Promise<CliToolOutcome>;