@momentiq/dark-factory-cli 0.1.1-alpha.9 → 0.3.0-alpha.9

package/README.md

@@ -106,6 +106,11 @@ df gate-push --commit HEAD --ci       # CI replay
 df doctor --profile local             # env + per-adapter auth check
 df gates                              # static gates, no LLM
 df stats                              # alias for `df audit stats`
+
+# Phase G — MCP server (cycle 5). Stdio Model Context Protocol server
+# exposing the CLI surface to any MCP-speaking agent.
+df mcp                                # start the stdio MCP server
+df mcp --help                         # config snippets for Claude Code, Cursor, Codex
 ```
 
 > **Note on `--use-bundled-default-spec`**: the bundled `spec-default.yaml`

package/dist/adapters/cursor-cli.d.ts

@@ -0,0 +1,211 @@
+import { type CriticConfig, type CriticResult, type DoctorCheck, type ReviewPacket } from "@momentiq/dark-factory-schemas";
+import type { CriticAdapter, CriticReviewOptions } from "./critic.js";
+import { type AttemptOutcome } from "./_retry.js";
+export declare const CURSOR_CLI_ADAPTER_ID = "cursor-cli";
+export declare const CURSOR_CLI_BINARY = "cursor-agent";
+export declare const CURSOR_API_KEY_ENV = "CURSOR_API_KEY";
+export declare const CURSOR_CLI_AUTH_CHATGPT: "chatgpt";
+export type CursorCliAuthMode = typeof CURSOR_CLI_AUTH_CHATGPT;
+export declare const CURSOR_CLI_AUTH_MODES: readonly CursorCliAuthMode[];
+/**
+ * Resolve the effective `--model` arg from a critic config. Appends the
+ * `-fast` suffix when the critic declares `fast: true` (and the id
+ * doesn't already carry the suffix). Exported for direct unit testing.
+ */
+export declare function resolveCursorCliModelId(critic: CriticConfig): string;
+/**
+ * `system.init` event — emitted as the first event in `--output-format
+ * stream-json` mode. Documented fields: `type`, `subtype`,
+ * `apiKeySource`, `cwd`, `session_id`, `model`, `permissionMode`.
+ *
+ * `apiKeySource` is the trust signal: `"login"` means the CLI used
+ * Keychain-backed subscription auth (the desired mode for `cursor-cli`),
+ * `"env"` means a `CURSOR_API_KEY` env var was honored, `"flag"` means
+ * `--api-key` was passed. When auth is pinned to "chatgpt", anything
+ * other than "login" fails the run closed (issue #28 defense in depth).
+ */
+export interface CursorCliInitEvent {
+    apiKeySource?: string;
+    sessionId?: string;
+    model?: string;
+    permissionMode?: string;
+    cwd?: string;
+}
+export declare function extractInitEvent(event: unknown): CursorCliInitEvent | null;
+/**
+ * `assistant` event — `message.content[]` array with `type: "text"`
+ * entries the model wrote. Same shape as the @cursor/sdk stream (verified
+ * empirically) so this extractor mirrors `cursor-sdk.ts:extractAssistantText`.
+ *
+ * Returns the empty string for non-assistant events or malformed shapes.
+ */
+export declare function extractAssistantText(event: unknown): string;
+/**
+ * `result` event — terminal envelope. Documented fields: `type`,
+ * `subtype`, `duration_ms`, `duration_api_ms`, `is_error`, `result`,
+ * `session_id`, `request_id`, `usage`. Stream parsing stops once this
+ * event is observed (or the subprocess exits, whichever comes first).
+ */
+export interface CursorCliResultEnvelope {
+    isError: boolean;
+    subtype: string | null;
+    resultText: string;
+    sessionId: string | null;
+    requestId: string | null;
+    durationMs: number | null;
+    usageInputTokens: number | null;
+    usageOutputTokens: number | null;
+}
+export declare function extractResultEnvelope(event: unknown): CursorCliResultEnvelope | null;
+export declare const CURSOR_CLI_PERMANENT_SUBTYPES: ReadonlySet<string>;
+/**
+ * Classify a `result` envelope's `subtype` as permanent vs retryable.
+ * Returns `true` for the permanent set, `false` otherwise (unknown
+ * subtypes are treated as retryable). Exported for unit testing.
+ */
+export declare function isPermanentResultSubtype(subtype: string | null): boolean;
+/**
+ * Aggregate outcome of a single subprocess invocation. The adapter
+ * dispatches on these fields; tests inject a stub returning a scripted
+ * shape so no real `cursor-agent` process is spawned during unit tests.
+ */
+export interface CursorCliRunOutcome {
+    /** Parsed NDJSON events from stdout, in order. */
+    events: unknown[];
+    /** Process exit code (`null` if the process was killed by a signal). */
+    exitCode: number | null;
+    /** Captured stderr (typically empty on success; carries CLI errors). */
+    stderr: string;
+    /**
+     * Set when the subprocess could not be spawned at all (e.g., the
+     * `cursor-agent` binary was not on PATH). The adapter treats this as a
+     * permanent install failure rather than a retryable run failure.
+     */
+    spawnError: Error | null;
+}
+export interface CursorCliRunArgs {
+    binaryPath: string;
+    cliArgs: readonly string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    prompt: string;
+    signal?: AbortSignal;
+}
+export type CursorCliRunner = (args: CursorCliRunArgs) => Promise<CursorCliRunOutcome>;
+/**
+ * Default production runner. Spawns the CLI, writes the compiled
+ * prompt to stdin, parses NDJSON line-by-line from stdout, captures
+ * stderr verbatim, resolves once the subprocess exits (or once the
+ * AbortSignal fires, in which case the subprocess is killed first).
+ *
+ * Returns a `spawnError` when spawning itself failed (ENOENT, EACCES,
+ * etc.) so the adapter can surface a clear install/binary failure
+ * instead of a generic transport error.
+ */
+export declare const defaultCursorCliRunner: CursorCliRunner;
+/**
+ * Issue #28 — strict-no-fallback auth resolution. Validates `critic.auth`
+ * against the cursor-cli adapter vocabulary
+ * ({@link CURSOR_CLI_AUTH_MODES}) and surfaces every misuse as
+ * `permanent_failure` so the outer retry loop returns the configuration
+ * error immediately (retrying a config mistake just wastes budget).
+ *
+ * Two failure shapes, both permanent (no retry):
+ *
+ *   1. `critic.auth === undefined`: profile didn't pin auth. Surfaces
+ *      as `permanent_failure` with a message naming the critic + the
+ *      exact config path the operator must edit.
+ *
+ *   2. `critic.auth` is set but not "chatgpt" (e.g., "api"): this
+ *      adapter is subscription-only. Error message directs the
+ *      operator to use the `cursor-sdk` adapter instead (which is
+ *      designed for API-key auth) — fixing the config rather than
+ *      muddling adapter responsibilities.
+ */
+export declare function resolveAuthOrFail(critic: CriticConfig, attemptIdx: number): {
+    kind: "ok";
+    mode: CursorCliAuthMode;
+} | Extract<AttemptOutcome, {
+    kind: "permanent_failure";
+}>;
+/**
+ * Build the CLI argv array for a review run. Pure function — no env
+ * inspection — so the test surface is a flat array. Order is documented
+ * by Cursor; the adapter sets every flag explicitly rather than relying
+ * on defaults so behavior is reproducible across CLI versions.
+ *
+ *   --print                           Headless mode (no TUI).
+ *   --output-format stream-json       NDJSON events on stdout.
+ *   --trust                           Workspace trust without prompting
+ *                                     (only valid with --print).
+ *   --sandbox enabled                 Read-only sandbox; blocks file
+ *                                     writes even if the model attempts
+ *                                     one (defense in depth against
+ *                                     untrusted diff content).
+ *   --model <id>                      Resolved by resolveCursorCliModelId.
+ *
+ * The prompt itself is NOT an argv member — it's piped via stdin to
+ * sidestep the macOS argv length cap (~256KB) that would truncate
+ * review packets with full changed files (config caps
+ * `maxChangedFileBytes: 200000`).
+ */
+export declare function buildCursorCliArgs(modelId: string): string[];
+/**
+ * Strip `CURSOR_API_KEY` from the subprocess env when auth is pinned to
+ * "chatgpt". Belt-and-suspenders against a Doppler-leaked env var
+ * routing the run through API-key billing without the operator
+ * noticing. The `system.init.apiKeySource` assertion below is the
+ * second layer — if a key somehow leaks past this strip, the run still
+ * fails closed because `apiKeySource !== "login"`.
+ */
+export declare function buildSubscriptionEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export interface CursorCliAdapterOptions {
+    /**
+     * Override the cursor-agent binary path. Default: the literal
+     * "cursor-agent" (resolved via PATH at spawn time). Tests pass a
+     * fixed string to assert which path was probed.
+     */
+    binaryPath?: string;
+    /**
+     * Test escape hatch — inject a scripted subprocess runner. Production
+     * uses {@link defaultCursorCliRunner} which actually spawns the CLI.
+     */
+    runCursorAgentCli?: CursorCliRunner;
+    /**
+     * Test escape hatch for the `execFile` doctor-probe wrapper. Production
+     * uses the promisified `child_process.execFile`. Tests pass a mock to
+     * avoid spawning the real binary and to assert which arguments the
+     * doctor probed.
+     */
+    execCursorAgent?: (binaryPath: string, args: readonly string[], options?: {
+        timeout?: number;
+    }) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /**
+     * Test escape hatch for the retry-loop sleep. When unset the adapter
+     * uses the real `sleepForRetry` (wall-clock + AbortSignal-aware).
+     * Mirrors the same hook on `runRetryLoop` so tests don't have to
+     * wait for 5s + 15s of real backoff to exercise retry behavior.
+     */
+    sleep?: (idx: number, signal: AbortSignal | undefined) => Promise<void>;
+    /**
+     * Override the `process.env` snapshot used as the base for the
+     * subprocess env. Tests pass a fixed map so the env-strip behavior
+     * is hermetic.
+     */
+    baseEnv?: NodeJS.ProcessEnv;
+}
+export declare class CursorCliAdapter implements CriticAdapter {
+    private readonly options;
+    readonly id = "cursor-cli";
+    readonly requiredEnvVars: readonly string[];
+    private readonly run;
+    private readonly exec;
+    constructor(options?: CursorCliAdapterOptions);
+    review(packet: ReviewPacket, critic: CriticConfig, options: CriticReviewOptions): Promise<CriticResult>;
+    private attemptReview;
+    doctor(critic: CriticConfig): Promise<DoctorCheck[]>;
+}
+//# sourceMappingURL=cursor-cli.d.ts.map

package/dist/adapters/cursor-cli.d.ts.map

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