@fusionkit/cli 0.1.5 → 0.1.7

package/README.md

@@ -44,23 +44,25 @@ cloud panel (skip with `--yes`). Use `--local` for the on-device MLX panel, or
 
 ## Per-repo config
 
-Tired of long flag lines? Scaffold a committed `fusionkit.json`:
+Tired of long flag lines? Scaffold a committed `.fusionkit/` folder:
 
 ```bash
 fusionkit init
 ```
 
-It records the panel, judge, default tool, and run defaults so the whole team
-can just run `fusionkit codex`. Only env-var *names* for keys are stored, never
-secrets. Explicit CLI flags always override the file. Inspect the effective
-config and a dry-run preview with `fusionkit status`.
+It writes `.fusionkit/fusion.json` (the panel, judge, default tool, and run
+defaults) plus editable system-prompt overrides in `.fusionkit/prompts/*.md`, so
+the whole team can just run `fusionkit codex`. Only env-var *names* for keys are
+stored, never secrets. Explicit CLI flags always override the folder. A legacy
+`fusionkit.json` is auto-migrated on first run. Inspect the effective config and
+a dry-run preview with `fusionkit status`.
 
 ## Commands
 
 - `fusionkit codex | claude | cursor` — launch that agent backed by the panel.
 - `fusionkit serve` — just run the gateway and print setup snippets for any tool.
 - `fusionkit fusion [tool]` — the generic launcher (interactive picker on a TTY).
-- `fusionkit init` — scaffold `fusionkit.json` for this repo.
+- `fusionkit init` — scaffold the committed `.fusionkit/` folder for this repo.
 - `fusionkit doctor` — check prerequisites with fix hints.
 - `fusionkit status` — show the effective config and what a run will do.
 
@@ -73,5 +75,27 @@ tool name; everything after the tool is forwarded to it.
 - `--observe` boots a local dashboard that streams live trace events. It is a
   separate app and is not bundled in the npm package; fusionkit prints how to
   enable it if it isn't available.
-- `cursor` needs a built Cursorkit checkout (`--cursor-kit-dir` or
-  `FUSIONKIT_CURSORKIT_DIR`); fusionkit prints setup guidance if it's missing.
+- `cursor` only needs a logged-in `cursor-agent` CLI; Cursorkit ships bundled
+  with this package, so no separate checkout is required.
+
+## Adding a new tool
+
+Each coding tool is its own workspace package implementing a single
+`ToolIntegration` (the adapter), so supporting a new tool is additive:
+
+1. Create `packages/tool-<name>/` (copy `packages/tool-codex` as a template). It
+   depends on `@fusionkit/tools` for the `ToolIntegration` / `ToolLaunchContext`
+   contract, and on `@fusionkit/ensemble` if it also ships a harness adapter.
+2. Export a `const <name>Tool: ToolIntegration` with:
+   - `launch(ctx)` — boot the tool's binary against `ctx.gatewayUrl` (the host
+     injects `spawnTool`, portless, teardown, etc. via the context; tool packages
+     never import the CLI).
+   - `modes` — `"fusion"`, `"local"`, or both.
+   - `createHarness` + `harnessKinds` — optional, only if the tool also runs as
+     an ensemble harness in the gateway/e2e matrix.
+3. Register it in [`packages/cli/src/tools.ts`](src/tools.ts) by adding it to the
+   `createToolRegistry([...])` list.
+
+That single registry entry wires the tool into the `fusionkit <tool>` launcher,
+`fusionkit local <tool>`, the interactive picker, preflight, and (when it has a
+harness) the ensemble gateway — no other switch statements to update.

package/dist/cli.d.ts

@@ -1,2 +1,3 @@
 import { Command } from "commander";
+import "./tools.js";
 export declare function buildProgram(): Command;

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
+import "./tools.js";
 import { FUSIONKIT_PYPI_VERSION } from "./fusion-quickstart.js";
 import { registerDoctor } from "./commands/doctor.js";
 import { registerEnsemble } from "./commands/ensemble.js";

package/dist/commands/doctor.js

@@ -56,13 +56,15 @@ function runDoctor() {
         console.log("");
         console.log(bold("repo config"));
         try {
-            const config = loadFusionConfig(repoRoot);
+            const config = loadFusionConfig(repoRoot, (message) => console.log(`  ${gray(glyph.bullet())} ${dim(message)}`));
             if (config === undefined) {
-                console.log(`  ${gray(glyph.bullet())} no ${cyan("fusionkit.json")} yet — run ${bold("fusionkit fusion init")}`);
+                console.log(`  ${gray(glyph.bullet())} no ${cyan(".fusionkit/")} yet — run ${bold("fusionkit fusion init")}`);
             }
             else {
+                const overrides = Object.keys(config.prompts ?? {});
                 console.log(`  ${green(glyph.tick())} ${cyan(fusionConfigPath(repoRoot))}`);
                 console.log(`    ${dim(`tool: ${config.tool ?? "(unset)"}  panel: ${(config.panel ?? []).map((s) => s.id).join(", ") || "(unset)"}`)}`);
+                console.log(`    ${dim(`prompt overrides: ${overrides.length > 0 ? overrides.join(", ") : "(none — built-in defaults)"}`)}`);
             }
         }
         catch (error) {
@@ -94,7 +96,7 @@ function runStatus() {
     }
     let config;
     try {
-        config = loadFusionConfig(repoRoot);
+        config = loadFusionConfig(repoRoot, (message) => console.log(dim(message)));
     }
     catch (error) {
         console.log(`${red("config error:")} ${error instanceof Error ? error.message : String(error)}`);
@@ -110,6 +112,8 @@ function runStatus() {
     console.log(`${dim("tool:")}   ${bold(tool)}`);
     console.log(`${dim("judge:")}  ${judge}`);
     console.log(`${dim("observe:")} ${config?.observe === true ? "on" : "off"}`);
+    const overrides = Object.keys(config?.prompts ?? {});
+    console.log(`${dim("prompts:")} ${overrides.length > 0 ? overrides.join(", ") : dim("(built-in defaults)")}`);
     console.log(bold("\npanel"));
     for (const spec of panel)
         console.log(`  ${glyph.bullet()} ${panelLabel(spec)}`);

package/dist/commands/ensemble-gateway.js

@@ -12,7 +12,6 @@ function addCommonGatewayOptions(cmd) {
         .option("--out <dir>", "output directory")
         .option("--model <spec>", "panel model mapping ID=MODEL (repeatable)", collect)
         .option("--judge-model <model>", "model used for judge synthesis")
-        .option("--cursor-kit-dir <dir>", "Cursorkit repo for cursor scenarios")
         .option("--timeout-ms <n>", "candidate timeout")
         .option("--fusion-api-key <key>", "API key for the fusion backend");
 }
@@ -30,7 +29,6 @@ function gatewayConfig(opts) {
         timeoutMs,
         ...(opts.command !== undefined ? { command: opts.command } : {}),
         ...(opts.judgeModel !== undefined ? { judgeModel: opts.judgeModel } : {}),
-        ...(opts.cursorKitDir !== undefined ? { cursorKitDir: resolve(opts.cursorKitDir) } : {}),
         ...(opts.fusionApiKey !== undefined ? { fusionApiKey: opts.fusionApiKey } : {})
     };
 }

package/dist/commands/ensemble-records.d.ts

@@ -1,4 +1,5 @@
-import type { EnsembleRunResult, HarnessAdapter, HarnessSmokeDashboard } from "@fusionkit/ensemble";
+import type { EnsembleRunResult, HarnessAdapter } from "@fusionkit/ensemble";
+import type { HarnessSmokeDashboard } from "../dashboard.js";
 import type { BenchmarkTaskRecordV1, ModelFusionHarnessKind, ModelFusionRecordV1, ModelFusionSideEffects } from "@fusionkit/protocol";
 export type HandoffPayload = {
     category?: string;

package/dist/commands/ensemble-records.js

@@ -1,6 +1,8 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { claudeCodeHarness, claudeCodeHarnessCredentialSkipReason, codexHarness, codexHarnessCredentialSkipReason, createCommandHarness, createMockHarness } from "@fusionkit/ensemble";
+import { createCommandHarness, createMockHarness } from "@fusionkit/ensemble";
+import { claudeCodeHarness, claudeCodeHarnessCredentialSkipReason } from "@fusionkit/tool-claude";
+import { codexHarness, codexHarnessCredentialSkipReason } from "@fusionkit/tool-codex";
 import { assertBenchmarkTaskRecordV1, assertHarnessCandidateRecordV1, assertJudgeSynthesisRecordV1, assertModelCallRecordV1, assertModelFusionRecord, assertToolExecutionRecordV1, MODEL_FUSION_SCHEMA_BUNDLE_HASH } from "@fusionkit/protocol";
 import { gitText } from "@fusionkit/workspace";
 import { fail } from "../shared/errors.js";

package/dist/commands/ensemble.js

@@ -1,9 +1,10 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { Command } from "commander";
-import { createCommandHarness, createMockHarness, createMockJudgeSynthesizer, runEnsemble, runHarnessSmokeDashboard, runUnifiedHarnessE2E } from "@fusionkit/ensemble";
+import { createCommandHarness, createMockHarness, createMockJudgeSynthesizer, runEnsemble, runUnifiedHarnessE2E } from "@fusionkit/ensemble";
 import { assertHarnessRunRequestV1, assertHarnessRunResultV1 } from "@fusionkit/protocol";
 import { gitText } from "@fusionkit/workspace";
+import { runHarnessSmokeDashboard } from "../dashboard.js";
 import { fail } from "../shared/errors.js";
 import { collect, ensembleModels, liveSmokeTargets, parseTimeoutMs, unifiedHarnessKinds } from "../shared/options.js";
 import { buildGatewayCommand } from "./ensemble-gateway.js";
@@ -172,8 +173,7 @@ async function runEnsembleE2E(task, opts) {
         models,
         ...(opts.command !== undefined ? { command: opts.command } : {}),
         timeoutMs,
-        ...(opts.judgeModel !== undefined ? { judgeModel: opts.judgeModel } : {}),
-        ...(opts.cursorKitDir !== undefined ? { cursorKitDir: resolve(opts.cursorKitDir) } : {})
+        ...(opts.judgeModel !== undefined ? { judgeModel: opts.judgeModel } : {})
     });
     const counts = new Map();
     for (const row of result.results) {
@@ -245,7 +245,6 @@ export function registerEnsemble(program) {
         .option("--id <id>", "descriptor id")
         .option("--model <spec>", "panel model mapping ID=MODEL (repeatable)", collect)
         .option("--judge-model <model>", "model used for judge synthesis")
-        .option("--cursor-kit-dir <dir>", "Cursorkit repo for cursor ACP/desktop scenarios")
         .option("--timeout-ms <n>", "candidate timeout")
         .option("--task-file <file>", "read task prompt from file")
         .action(runEnsembleE2E);

package/dist/commands/fusion.js

@@ -16,11 +16,10 @@ function applyFusionOptions(command) {
         .option("--synthesis-url <url>", "pre-running fusionkit serve for synthesis")
         .option("--fusionkit-dir <dir>", "local FusionKit checkout (dev override for the uvx synthesizer)")
         .option("--repo <dir>", "coding workspace the panel fuses over")
-        .option("--cursor-kit-dir <dir>", "built Cursorkit checkout for the cursor tool")
         .option("--local", "use the local MLX panel trio instead of the default cloud panel")
-        .option("--no-local", "override a fusionkit.json default of local=true")
+        .option("--no-local", "override a .fusionkit default of local=true")
         .option("--observe", "boot the local scope dashboard and stream live trace events")
-        .option("--no-observe", "override a fusionkit.json default of observe=true")
+        .option("--no-observe", "override a .fusionkit default of observe=true")
         .option("--yes", "skip the interactive cloud-panel cost confirmation")
         .option("--auth-token <token>", "require a bearer token on the gateway")
         .option("--port <n>", "gateway port (default: ephemeral)")
@@ -45,8 +44,6 @@ function resolveOptions(opts) {
         options.fusionkitDir = resolve(opts.fusionkitDir);
     if (opts.repo !== undefined)
         options.repo = resolve(opts.repo);
-    if (opts.cursorKitDir !== undefined)
-        options.cursorKitDir = resolve(opts.cursorKitDir);
     // local/observe are tri-state: only set when the user passed --local/--no-local
     // (or --observe/--no-observe), so an unset flag can fall through to the config.
     if (opts.local !== undefined)
@@ -99,10 +96,10 @@ function mergeConfig(options, config) {
         options.observe = config.observe;
     if (options.portless === undefined && config.portless !== undefined)
         options.portless = config.portless;
-    if (options.cursorKitDir === undefined && config.cursorKitDir != null)
-        options.cursorKitDir = config.cursorKitDir;
     if (options.port === undefined && config.port != null)
         options.port = config.port;
+    if (options.prompts === undefined && config.prompts !== undefined)
+        options.prompts = config.prompts;
 }
 /** The repo root used for config lookup: --repo if given, else the cwd's git root. */
 function configRepoRoot(options) {
@@ -129,15 +126,21 @@ function resolveContext(opts) {
     return { options, ...(config?.tool !== undefined ? { configTool: config.tool } : {}) };
 }
 export function registerFusion(program) {
-    // Top-level `init` — scaffold a committed fusionkit.json for this repo.
+    // Top-level `init` — scaffold a committed .fusionkit/ folder for this repo.
     program
         .command("init")
-        .description("scaffold a committed fusionkit.json for this repo")
+        .description("scaffold a committed .fusionkit/ folder for this repo")
         .option("--repo <dir>", "coding workspace the panel fuses over")
-        .option("--force", "overwrite an existing fusionkit.json")
+        .option("--fusionkit-dir <dir>", "local FusionKit checkout (dev override for default prompts)")
+        .option("--force", "overwrite an existing .fusionkit/ config and prompts")
         .action(async (opts) => {
-        const repoRoot = configRepoRoot(resolveOptions(opts));
-        const code = await runFusionInit({ repoRoot, force: opts.force === true });
+        const options = resolveOptions(opts);
+        const repoRoot = configRepoRoot(options);
+        const code = await runFusionInit({
+            repoRoot,
+            force: opts.force === true,
+            ...(options.fusionkitDir !== undefined ? { fusionkitDir: options.fusionkitDir } : {})
+        });
         process.exit(code);
     });
     // Generic `fusion [tool]` — keeps the original surface and interactive pick.
@@ -148,7 +151,7 @@ export function registerFusion(program) {
         .argument("[args...]", "arguments forwarded to the tool")
         .option("--tool <tool>", `coding agent to launch (${FUSION_TOOLS.join(" | ")})`))
         .addHelpText("after", "\nfusionkit's own flags must precede the tool name; everything after the tool is forwarded to it." +
-        "\nRun `fusionkit init` to scaffold a committed fusionkit.json for this repo." +
+        "\nRun `fusionkit init` to scaffold a committed .fusionkit/ folder for this repo." +
         "\nRun `fusionkit fusion stop` to reap portless singleton services (router, dashboard, ...).")
         .action(async (positionalTool, args, opts) => {
         // `fusion stop` reaps persistent portless singletons left running by prior

package/dist/commands/local.js

@@ -6,14 +6,14 @@ export function registerLocal(program) {
         .description("back a vendor agent with a local model")
         .argument("[tool]", `${LOCAL_TOOLS.join(" | ")}`)
         .argument("[args...]", "arguments forwarded to the tool")
-        .option("--public-url <url>", "public tunnel URL for Cursor (or WARRANT_PUBLIC_URL)")
+        .option("--public-url <url>", "public tunnel URL for Cursor (or FUSIONKIT_PUBLIC_URL)")
         .option("--auth-token <token>", "require a bearer token on the gateway")
         .allowUnknownOption()
         .passThroughOptions()
-        .addHelpText("after", "\nwarrant's own flags must precede the tool name; everything after the tool is forwarded to it.")
+        .addHelpText("after", "\nfusionkit's own flags must precede the tool name; everything after the tool is forwarded to it.")
         .action(async (tool, args, opts) => {
         if (tool === undefined || !LOCAL_TOOLS.includes(tool)) {
-            fail(`usage: warrant local <${LOCAL_TOOLS.join(" | ")}> [args...]`);
+            fail(`usage: fusionkit local <${LOCAL_TOOLS.join(" | ")}> [args...]`);
         }
         const options = {
             ...(opts.publicUrl !== undefined ? { publicUrl: opts.publicUrl } : {}),

package/dist/cursor-acp.d.ts

@@ -1,15 +1,13 @@
 /**
- * Real Cursor ACP front-door producer. Spawns the Cursorkit bridge (its
+ * Real Cursor ACP front-door producer. Spawns the bundled Cursorkit bridge (its
  * local-model backend pointed at the running Fusion Harness Gateway) and drives
  * the real cursor-agent CLI in ACP mode, asserting the fusion-synthesized
  * sentinel reaches Cursor via session/update. Returns undefined when the
- * Cursorkit checkout or the cursor-agent CLI are unavailable, so the acceptance
- * suite records the explicit `blocked` / `cursorkit_backend_not_running`
- * outcome instead of a silent pass.
+ * cursor-agent CLI is unavailable, so the acceptance suite records the explicit
+ * `blocked` / `cursorkit_backend_not_running` outcome instead of a silent pass.
  */
 import type { FrontDoorOutcomeProducer } from "@fusionkit/model-gateway";
 export type CursorAcpProducerInput = {
-    cursorKitDir: string | undefined;
     gatewayUrl: string;
     sentinel: string;
     repo: string;

package/dist/cursor-acp.js

@@ -1,16 +1,17 @@
 /**
- * Real Cursor ACP front-door producer. Spawns the Cursorkit bridge (its
+ * Real Cursor ACP front-door producer. Spawns the bundled Cursorkit bridge (its
  * local-model backend pointed at the running Fusion Harness Gateway) and drives
  * the real cursor-agent CLI in ACP mode, asserting the fusion-synthesized
  * sentinel reaches Cursor via session/update. Returns undefined when the
- * Cursorkit checkout or the cursor-agent CLI are unavailable, so the acceptance
- * suite records the explicit `blocked` / `cursorkit_backend_not_running`
- * outcome instead of a silent pass.
+ * cursor-agent CLI is unavailable, so the acceptance suite records the explicit
+ * `blocked` / `cursorkit_backend_not_running` outcome instead of a silent pass.
  */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { delimiter, join } from "node:path";
 import { createInterface } from "node:readline";
+import { resolveCursorkitCli } from "@fusionkit/ensemble";
+import { readEnv } from "@fusionkit/tools";
 function commandOnPath(command) {
     if (command.includes("/"))
         return existsSync(command);
@@ -26,10 +27,11 @@ function normalizeModelBaseUrl(gatewayUrl) {
 }
 export function buildCursorAcpProducer(input) {
     const command = input.command ?? "cursor-agent";
-    if (input.cursorKitDir === undefined || input.cursorKitDir.length === 0) {
-        return undefined;
-    }
-    if (!existsSync(join(input.cursorKitDir, "dist/src/cli.js"))) {
+    // The live Cursor ACP probe drives the real cursor-agent CLI through the
+    // bundled Cursorkit bridge, so it stays opt-in: without the live flag the
+    // acceptance suite reports this door as `blocked` rather than spawning live
+    // tooling (keeping deterministic runs free of credential/CLI dependencies).
+    if (readEnv(process.env, "FUSIONKIT_GATEWAY_LIVE_CURSOR") !== "1") {
         return undefined;
     }
     if (!commandOnPath(command)) {
@@ -38,7 +40,6 @@ export function buildCursorAcpProducer(input) {
     return () => runCursorAcpOutcome({ ...input, command });
 }
 async function runCursorAcpOutcome(input) {
-    const cursorKitDir = input.cursorKitDir;
     const modelName = input.modelName ?? "local-fusion";
     const bridgePort = 9700 + Math.floor(Math.random() * 250);
     const bridgeEnv = {};
@@ -60,9 +61,9 @@ async function runCursorAcpOutcome(input) {
         MODEL_PROVIDER_MODEL: "fusion-panel",
         MODEL_CONTEXT_TOKEN_LIMIT: "128000"
     });
+    const { serveCli } = resolveCursorkitCli();
     let bridgeOut = "";
-    const bridge = spawn(process.execPath, ["dist/src/cli.js", "serve"], {
-        cwd: cursorKitDir,
+    const bridge = spawn(process.execPath, [serveCli, "serve"], {
         env: bridgeEnv,
         stdio: ["ignore", "pipe", "pipe"]
     });

package/dist/dashboard.d.ts

@@ -0,0 +1,65 @@
+import type { HarnessRunResultV1, ModelFusionHarnessKind } from "@fusionkit/protocol";
+import type { HarnessAdapter, HarnessCapabilities } from "@fusionkit/ensemble";
+import type { ToolDashboardMetadata } from "@fusionkit/tools";
+/** Dashboard target id (a tool id like "claude-code", or "command"/"mock"). */
+export type HarnessCapabilityTarget = string;
+export type HarnessAvailability = "available" | "credential_gated" | "missing";
+/** A tool id that exposes a live smoke (e.g. "claude-code", "codex", "cursor"). */
+export type HarnessLiveSmokeTarget = string;
+export type HarnessSmokePurpose = "contract" | "credential-skip" | "live" | "missing";
+export type HarnessAdapterReadiness = {
+    harnessId: HarnessCapabilityTarget;
+    displayName: string;
+    contractReadiness: string;
+    credentialState: string;
+    liveSmoke: string;
+    evidence: string[];
+    artifactRefs: string[];
+};
+export type HarnessCapabilityMatrixRow = {
+    harnessId: HarnessCapabilityTarget;
+    harnessKind: ModelFusionHarnessKind;
+    displayName: string;
+    availability: HarnessAvailability;
+    capabilities: HarnessCapabilities;
+    notes: string[];
+};
+export type HarnessCapabilityMatrix = {
+    capabilities: string[];
+    rows: HarnessCapabilityMatrixRow[];
+};
+export type HarnessSmokeOutcome = "success" | "failure" | "missing" | "skipped";
+export type HarnessSmokeRecord = {
+    taskId: string;
+    harnessId: HarnessCapabilityTarget;
+    purpose: HarnessSmokePurpose;
+    outcome: HarnessSmokeOutcome;
+    result: HarnessRunResultV1;
+    resultPath: string;
+};
+export type HarnessSmokeDashboard = {
+    outputRoot: string;
+    dashboardPath: string;
+    matrix: HarnessCapabilityMatrix;
+    records: HarnessSmokeRecord[];
+    readiness: HarnessAdapterReadiness[];
+};
+export type HarnessSmokeDashboardOptions = {
+    repo?: string;
+    outputRoot?: string;
+    timeoutMs?: number;
+    createdAt?: string;
+    env?: Record<string, string | undefined>;
+    commandSuccess?: string;
+    commandFailure?: string;
+    liveSmoke?: readonly HarnessLiveSmokeTarget[];
+    liveSmokeHarnesses?: Partial<Record<HarnessLiveSmokeTarget, HarnessAdapter>>;
+    /** Per-tool dashboard metadata; defaults to the registered tool registry. */
+    tools?: readonly ToolDashboardMetadata[];
+};
+export declare function createHarnessCapabilityMatrix(options?: HarnessSmokeDashboardOptions): HarnessCapabilityMatrix;
+export declare function runHarnessSmokeDashboard(options?: HarnessSmokeDashboardOptions): Promise<HarnessSmokeDashboard>;
+export declare const harnessDashboard: {
+    readonly capabilities: typeof createHarnessCapabilityMatrix;
+    readonly run: typeof runHarnessSmokeDashboard;
+};