@fusionkit/cli 0.1.5 → 0.1.7

package/dist/fusion/stack.js

@@ -0,0 +1,315 @@
+/**
+ * The fusion model stack: the single `fusionkit serve` router that fronts every
+ * panel model plus synthesis, and the in-process gateway that turns it into the
+ * judge-streamed-trajectory front door.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MlxBackend, startGateway } from "@fusionkit/model-gateway";
+import { startFusionStepGateway } from "../gateway.js";
+import { createPortlessSession } from "../shared/portless.js";
+import { freePort, spawnLogged, terminate, waitForHttp } from "../shared/proc.js";
+import { PROMPT_CONFIG_KEY, PROMPT_IDS } from "../fusion-config.js";
+import { defaultKeyEnv, fusionkitPyCommand, loadEnvFileInto } from "./env.js";
+/**
+ * Heuristic: does the captured output indicate a permanent failure (bad key,
+ * inaccessible model) that a retry cannot fix? Used to fail fast with a clear
+ * message instead of burning the retry budget on a hopeless start.
+ */
+function looksPermanentFailure(log) {
+    return /401|403|invalid[ _-]?api[ _-]?key|unauthorized|forbidden|authentication|permission|model[^\n]*(not found|does not exist)|no such model|model_not_found/i.test(log);
+}
+/**
+ * Default provider base URL when a cloud spec carries no explicit `baseUrl`.
+ * fusionkit's `ModelEndpoint` requires `base_url`, so the router config must
+ * always set it (the `serve-endpoint` shim filled this in for us before). Mirrors
+ * `PROVIDER_DEFAULT_BASE_URL` in fusionkit's openai_endpoint.py.
+ */
+function providerDefaultBaseUrl(provider) {
+    switch (provider) {
+        case "openai":
+            return "https://api.openai.com";
+        case "anthropic":
+            return "https://api.anthropic.com";
+        case "google":
+            return "https://generativelanguage.googleapis.com";
+        case "openai-compatible":
+            return "http://127.0.0.1";
+        default: {
+            const exhaustive = provider;
+            throw new Error(`unknown provider ${String(exhaustive)}`);
+        }
+    }
+}
+/** Pick the panel spec that backs the judge (by model name), else the first. */
+function judgeSpecFor(specs, judgeModel) {
+    const first = specs[0];
+    if (first === undefined)
+        throw new Error("at least one panel model is required");
+    if (judgeModel === undefined)
+        return first;
+    return specs.find((spec) => spec.model === judgeModel) ?? first;
+}
+/**
+ * Build the `fusionkit serve` config (YAML) for the consolidated router: one
+ * endpoint per panel model. Cloud models call their provider directly (keyed by
+ * `api_key_env`); MLX models are fronted as `openai-compatible` endpoints
+ * pointing at their in-process gateway loopback URL. The judge endpoint doubles
+ * as the synthesizer. Values are JSON-quoted (valid YAML flow scalars).
+ */
+function routerConfigYaml(input) {
+    const lines = ["endpoints:"];
+    for (const spec of input.specs) {
+        const provider = spec.provider ?? "mlx";
+        lines.push(`  - id: ${JSON.stringify(spec.id)}`);
+        lines.push(`    model: ${JSON.stringify(spec.model)}`);
+        if (provider === "mlx") {
+            lines.push("    provider: openai-compatible");
+            lines.push(`    base_url: ${JSON.stringify(input.mlxUrls[spec.id] ?? "")}`);
+            lines.push("    api_key: not-needed");
+        }
+        else {
+            // `base_url` is required by fusionkit's ModelEndpoint, so always emit one
+            // (the spec's, or the provider default).
+            const baseUrl = spec.baseUrl ?? providerDefaultBaseUrl(provider);
+            lines.push(`    provider: ${provider}`);
+            lines.push(`    base_url: ${JSON.stringify(baseUrl)}`);
+            const keyEnv = spec.keyEnv ?? defaultKeyEnv(provider);
+            if (keyEnv !== undefined)
+                lines.push(`    api_key_env: ${JSON.stringify(keyEnv)}`);
+        }
+    }
+    lines.push(`default_model: ${JSON.stringify(input.judgeId)}`);
+    lines.push(`judge_model: ${JSON.stringify(input.judgeId)}`);
+    lines.push(`synthesizer_model: ${JSON.stringify(input.judgeId)}`);
+    // Generous budget: reasoning models (gpt-5.x) spend tokens on reasoning before
+    // producing content, so a small cap can yield an empty answer.
+    lines.push("sampling: {temperature: 0.2, top_p: 0.9, max_tokens: 8192}");
+    // Committed `.fusionkit/prompts/*.md` overrides flow into the synthesizer's
+    // PromptOverrides here. JSON.stringify yields a valid YAML double-quoted
+    // scalar, so multi-line prompts are escaped safely.
+    const promptEntries = PROMPT_IDS.flatMap((id) => {
+        const value = input.prompts?.[id];
+        return value !== undefined ? [[PROMPT_CONFIG_KEY[id], value]] : [];
+    });
+    if (promptEntries.length > 0) {
+        lines.push("prompts:");
+        for (const [key, value] of promptEntries) {
+            lines.push(`  ${key}: ${JSON.stringify(value)}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Spawn the single `fusionkit serve` router fronting every panel model + the
+ * synthesizer. MLX specs first get an in-process OpenAI-compatible gateway
+ * (loopback) that the router proxies to; cloud specs call their provider
+ * directly. Returns the router URL, an id->routerUrl endpoint map, and a close
+ * that tears down the router process and any MLX gateways it fronts.
+ */
+export async function startRouter(options) {
+    const { specs, report } = options;
+    const judgeSpec = judgeSpecFor(specs, options.judgeModel);
+    const models = specs.map((spec) => ({ id: spec.id, model: spec.model }));
+    const identity = specs.map((spec) => spec.id).sort().join(",");
+    const announceStart = (label) => {
+        if (report)
+            report({ kind: "server.start", id: "router", label });
+        else
+            options.log(`fusion: starting ${label}...`);
+    };
+    const announceReady = (detail) => {
+        if (report)
+            report({ kind: "server.ready", id: "router", detail });
+        else
+            options.log(`fusion: router ready on ${detail}`);
+    };
+    announceStart(`router · ${specs.map((spec) => spec.id).join(", ")}`);
+    // The router inherits the parent env plus the FusionKit checkout's `.env` (so
+    // provider keys load seamlessly), without overriding anything already exported.
+    // It calls providers directly and MLX over loopback (never a portless HTTPS
+    // URL), so it needs no portless CA — and must keep its default certifi bundle
+    // intact to verify real provider certificates.
+    const env = { ...process.env };
+    if (options.fusionkitDir !== undefined) {
+        loadEnvFileInto(join(options.fusionkitDir, ".env"), env);
+    }
+    const backends = [];
+    const gateways = [];
+    const mlxUrls = {};
+    const closeBackends = async () => {
+        await Promise.allSettled(gateways.map((gateway) => gateway.close()));
+        await Promise.allSettled(backends.map((backend) => backend.stop()));
+    };
+    try {
+        // MLX backends are memory-heavy (each loads a model into RAM), so they start
+        // sequentially before the router that fronts them.
+        for (const spec of specs) {
+            if ((spec.provider ?? "mlx") !== "mlx")
+                continue;
+            const backend = new MlxBackend({ model: spec.model });
+            await backend.start();
+            const gateway = await startGateway({ backend });
+            backends.push(backend);
+            gateways.push(gateway);
+            mlxUrls[spec.id] = gateway.url();
+        }
+        const config = routerConfigYaml({
+            specs,
+            mlxUrls,
+            judgeId: judgeSpec.id,
+            ...(options.prompts !== undefined ? { prompts: options.prompts } : {})
+        });
+        const configDir = mkdtempSync(join(tmpdir(), "fusion-router-"));
+        const configPath = join(configDir, "router.yaml");
+        writeFileSync(configPath, config);
+        const runner = fusionkitPyCommand(options.fusionkitDir);
+        const port = await freePort();
+        const proc = spawnLogged(runner.command, [...runner.prefix, "serve", "--config", configPath, "--host", "127.0.0.1", "--port", String(port)], {
+            ...(runner.cwd !== undefined ? { cwd: runner.cwd } : {}),
+            ...(options.logsDir !== undefined ? { logFile: join(options.logsDir, "router.log") } : {}),
+            env
+        });
+        proc.child.once("exit", () => rmSync(configDir, { recursive: true, force: true }));
+        const url = `http://127.0.0.1:${port}`;
+        try {
+            await waitForHttp(`${url}/v1/models`, proc, {
+                timeoutMs: 60_000,
+                label: "fusion router",
+                requireOk: true
+            });
+        }
+        catch (error) {
+            terminate(proc.child);
+            // A provider-side rejection (bad key / model) will not be fixed by a
+            // retry, so surface the distilled cause with guidance.
+            const hint = looksPermanentFailure(proc.log()) ? " (check model names and provider API keys)" : "";
+            throw new Error(`${error instanceof Error ? error.message : String(error)}${hint}`);
+        }
+        announceReady(url);
+        const endpoints = Object.fromEntries(specs.map((spec) => [spec.id, url]));
+        return {
+            url,
+            port,
+            ...(proc.child.pid !== undefined ? { pid: proc.child.pid } : {}),
+            endpoints,
+            models,
+            judgeModel: judgeSpec.id,
+            identity,
+            close: async () => {
+                terminate(proc.child);
+                await closeBackends();
+            }
+        };
+    }
+    catch (error) {
+        await closeBackends();
+        throw error;
+    }
+}
+export async function startFusionStack(options) {
+    const report = options.report;
+    const portless = options.portless ?? (await createPortlessSession({ enabled: false }));
+    // Full override (pre-running per-model endpoints + a pre-running synthesis
+    // URL, e.g. tests): use them verbatim and spawn no router.
+    const override = options.endpoints !== undefined && options.synthesisUrl !== undefined;
+    const judgeModelName = options.judgeModel ?? options.models[0]?.model ?? "";
+    const models = options.models.map((spec) => ({ id: spec.id, model: spec.model }));
+    let modelEndpoints;
+    let fusionBackendUrl;
+    let routerClose = () => { };
+    if (override) {
+        modelEndpoints = options.endpoints;
+        fusionBackendUrl = options.synthesisUrl;
+    }
+    else {
+        // Discover-or-spawn the single router (models + synthesis), reusing a
+        // compatible running instance (same endpoint id set) across runs.
+        const expectedIdentity = options.models.map((spec) => spec.id).sort().join(",");
+        const resolved = await portless.discoverOrSpawn({
+            name: "router",
+            identity: expectedIdentity,
+            healthCheck: async (loopbackUrl) => {
+                try {
+                    const response = await fetch(`${loopbackUrl}/v1/models`, { signal: AbortSignal.timeout(2000) });
+                    if (!response.ok)
+                        return undefined;
+                    const body = (await response.json());
+                    return (body.data ?? [])
+                        .map((entry) => entry.id)
+                        .filter((id) => typeof id === "string" && id !== "fusionkit/router")
+                        .sort()
+                        .join(",");
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            spawn: async () => {
+                if (report)
+                    report({ kind: "server.start", id: "router", label: "router" });
+                const router = await startRouter({
+                    specs: options.models,
+                    ...(options.judgeModel !== undefined ? { judgeModel: options.judgeModel } : {}),
+                    ...(options.fusionkitDir !== undefined ? { fusionkitDir: options.fusionkitDir } : {}),
+                    ...(options.prompts !== undefined ? { prompts: options.prompts } : {}),
+                    ...(options.logsDir !== undefined ? { logsDir: options.logsDir } : {}),
+                    ...(report !== undefined ? { report } : {}),
+                    log: options.log
+                });
+                return {
+                    port: router.port,
+                    ...(router.pid !== undefined ? { pid: router.pid } : {}),
+                    close: router.close
+                };
+            }
+        });
+        // The harness + the in-process step call reach the router over loopback (the
+        // portless name is for humans); see the CA-at-startup note in portless.ts.
+        modelEndpoints = Object.fromEntries(options.models.map((spec) => [spec.id, resolved.loopbackUrl]));
+        fusionBackendUrl = resolved.loopbackUrl;
+        routerClose = resolved.close;
+    }
+    try {
+        if (report)
+            report({ kind: "gateway.start" });
+        // The judge-streamed-trajectory front door: each panel model produces a
+        // trajectory and the judge emits the trajectory the user's tool executes.
+        const gatewayConfig = {
+            fusionBackendUrl,
+            repo: options.repo,
+            outputRoot: options.outputRoot,
+            harnesses: ["agent"],
+            models,
+            judgeModel: judgeModelName,
+            modelEndpoints,
+            ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {})
+        };
+        const gateway = await startFusionStepGateway({
+            config: gatewayConfig,
+            host: options.host ?? "127.0.0.1",
+            port: options.port ?? 0,
+            ...(options.authToken !== undefined ? { authToken: options.authToken } : {})
+        });
+        // The gateway runs in-process (dies with this CLI), so it gets a per-run
+        // portless name rather than being a cross-run singleton.
+        const fusionUrl = portless.register("gateway", gateway.port());
+        if (report)
+            report({ kind: "gateway.ready", detail: fusionUrl });
+        return {
+            fusionUrl,
+            endpoints: modelEndpoints,
+            close: async () => {
+                await gateway.close();
+                portless.unregister("gateway");
+                await routerClose();
+            }
+        };
+    }
+    catch (error) {
+        await routerClose();
+        throw error;
+    }
+}

package/dist/fusion-config.d.ts

@@ -1,6 +1,20 @@
 import type { FusionTool, PanelModelSpec } from "./fusion-quickstart.js";
+export declare const FUSION_CONFIG_DIRNAME = ".fusionkit";
+export declare const FUSION_CONFIG_BASENAME = "fusion.json";
+export declare const FUSION_PROMPTS_DIRNAME = "prompts";
+/** Legacy single-file config at the repo root (pre-`.fusionkit/`). */
 export declare const FUSION_CONFIG_FILENAME = "fusionkit.json";
-export declare const FUSION_CONFIG_VERSION = "fusionkit.fusion.v1";
+export declare const FUSION_CONFIG_VERSION = "fusionkit.fusion.v2";
+/**
+ * The committable system-prompt override ids. Each maps to a
+ * `.fusionkit/prompts/<id>.md` file and to a `FusionConfig.prompts` key in the
+ * Python synthesizer (see {@link PROMPT_CONFIG_KEY}).
+ */
+export declare const PROMPT_IDS: readonly ["judge", "synthesizer", "trajectory-synthesizer", "trajectory-step", "verifier", "panel"];
+export type PromptId = (typeof PROMPT_IDS)[number];
+/** Map each prompt override id to the `prompts:` key fusionkit's config expects. */
+export declare const PROMPT_CONFIG_KEY: Record<PromptId, string>;
+export type PromptOverrides = Partial<Record<PromptId, string>>;
 export type FusionConfig = {
     version: typeof FUSION_CONFIG_VERSION;
     tool?: FusionTool;
@@ -9,21 +23,58 @@ export type FusionConfig = {
     local?: boolean;
     observe?: boolean;
     portless?: boolean;
-    cursorKitDir?: string | null;
     port?: number | null;
+    /**
+     * System-prompt overrides, loaded from `.fusionkit/prompts/*.md`. Not stored
+     * inline in `config.json` — it is hydrated from the prompt files on load.
+     */
+    prompts?: PromptOverrides;
 };
 export declare class FusionConfigError extends Error {
     constructor(message: string);
 }
+/** The `.fusionkit/` directory at the repo root. */
+export declare function fusionConfigDir(repoRoot: string): string;
+/** The `.fusionkit/fusion.json` settings file. */
 export declare function fusionConfigPath(repoRoot: string): string;
-/** Validate a parsed object as a {@link FusionConfig}, throwing on any problem. */
+/** The legacy `fusionkit.json` at the repo root (pre-`.fusionkit/`). */
+export declare function legacyFusionConfigPath(repoRoot: string): string;
+/** The `.fusionkit/prompts/` directory holding the override files. */
+export declare function fusionPromptsDir(repoRoot: string): string;
+/** The `.fusionkit/prompts/<id>.md` file for a single prompt override. */
+export declare function fusionPromptPath(repoRoot: string, id: PromptId): string;
+/**
+ * Validate a parsed settings object as a {@link FusionConfig}, throwing on any
+ * problem. Prompt overrides are loaded separately from `.fusionkit/prompts/`,
+ * not from this object. A `v1` version is accepted and upgraded to `v2`.
+ */
 export declare function parseFusionConfig(raw: unknown, source: string): FusionConfig;
 /**
- * Load `<repoRoot>/fusionkit.json` if present. Returns `undefined` when the file
- * does not exist; throws {@link FusionConfigError} on malformed content.
+ * Read the committed prompt overrides from `.fusionkit/prompts/*.md`. Only files
+ * that exist and are non-empty (after trimming) become overrides.
+ */
+export declare function readFusionPrompts(repoRoot: string): PromptOverrides;
+/**
+ * Load the per-repo config. Prefers `.fusionkit/config.json`; if it is absent
+ * but a legacy `fusionkit.json` exists, auto-migrates it into the folder (the
+ * original is left intact) and loads from there. Returns `undefined` when no
+ * config exists; throws {@link FusionConfigError} on malformed content.
+ *
+ * `onNotice` receives a one-line message when a migration happens.
+ */
+export declare function loadFusionConfig(repoRoot: string, onNotice?: (message: string) => void): FusionConfig | undefined;
+/**
+ * Write `.fusionkit/config.json` (creating the folder), refusing to clobber
+ * unless `force`. Prompt overrides are stored as files, not inline, so any
+ * `prompts` on the config object is omitted here.
  */
-export declare function loadFusionConfig(repoRoot: string): FusionConfig | undefined;
-/** Write `fusionkit.json` at the repo root, refusing to clobber unless `force`. */
 export declare function writeFusionConfig(repoRoot: string, config: FusionConfig, options?: {
     force?: boolean;
 }): string;
+/**
+ * Write prompt override files into `.fusionkit/prompts/`. Existing files are
+ * left untouched unless `force`. Returns the paths actually written.
+ */
+export declare function writeFusionPrompts(repoRoot: string, prompts: PromptOverrides, options?: {
+    force?: boolean;
+}): string[];

package/dist/fusion-config.js

@@ -1,29 +1,85 @@
 /**
- * Per-repo fusion configuration (`fusionkit.json`, committed at the repo root).
+ * Per-repo fusion configuration, stored in a committed `.fusionkit/` folder at
+ * the repo root:
  *
- * Captures the panel, judge, default tool, and run defaults so a contributor can
- * just run `fusionkit codex` instead of retyping a long flag line. The file is
- * safe to commit: it stores only the env-var *names* that hold API keys
- * (`keyEnv`), never the secret values.
+ *   .fusionkit/
+ *     fusion.json        - all settings (panel, judge, default tool, run defaults)
+ *     prompts/<id>.md    - optional system-prompt overrides (one file per prompt)
  *
- * Precedence at run time is: explicit CLI flags > fusionkit.json > built-in
- * defaults. CLI flags always win, so the file is a default layer, not a lock.
+ * The folder is safe to commit: it stores only the env-var *names* that hold API
+ * keys (`keyEnv`), never the secret values. A prompt file that exists and is
+ * non-empty overrides the matching built-in synthesizer prompt; absent/empty
+ * falls back to the built-in default.
+ *
+ * Precedence at run time is: explicit CLI flags > .fusionkit > built-in
+ * defaults. CLI flags always win, so the folder is a default layer, not a lock.
+ *
+ * Legacy `fusionkit.json` files at the repo root are auto-migrated into
+ * `.fusionkit/fusion.json` on first load (the original is left intact as a
+ * back-compat fallback).
  */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { FUSION_TOOLS } from "./fusion-quickstart.js";
 import { PANEL_PROVIDERS } from "./shared/options.js";
+export const FUSION_CONFIG_DIRNAME = ".fusionkit";
+// `fusion.json` (not `config.json`) so the fusion settings never collide with
+// the plane home's `.fusionkit/config.json` (`warrant.config.v2`).
+export const FUSION_CONFIG_BASENAME = "fusion.json";
+export const FUSION_PROMPTS_DIRNAME = "prompts";
+/** Legacy single-file config at the repo root (pre-`.fusionkit/`). */
 export const FUSION_CONFIG_FILENAME = "fusionkit.json";
-export const FUSION_CONFIG_VERSION = "fusionkit.fusion.v1";
+export const FUSION_CONFIG_VERSION = "fusionkit.fusion.v2";
+/** Versions `parseFusionConfig` will load; `v1` is upgraded to `v2` in memory. */
+const SUPPORTED_CONFIG_VERSIONS = ["fusionkit.fusion.v1", "fusionkit.fusion.v2"];
+/**
+ * The committable system-prompt override ids. Each maps to a
+ * `.fusionkit/prompts/<id>.md` file and to a `FusionConfig.prompts` key in the
+ * Python synthesizer (see {@link PROMPT_CONFIG_KEY}).
+ */
+export const PROMPT_IDS = [
+    "judge",
+    "synthesizer",
+    "trajectory-synthesizer",
+    "trajectory-step",
+    "verifier",
+    "panel"
+];
+/** Map each prompt override id to the `prompts:` key fusionkit's config expects. */
+export const PROMPT_CONFIG_KEY = {
+    judge: "judge_system",
+    synthesizer: "synthesizer_system",
+    "trajectory-synthesizer": "trajectory_synthesizer_system",
+    "trajectory-step": "trajectory_step_system",
+    verifier: "verifier_system",
+    panel: "panel_system"
+};
 export class FusionConfigError extends Error {
     constructor(message) {
         super(message);
         this.name = "FusionConfigError";
     }
 }
+/** The `.fusionkit/` directory at the repo root. */
+export function fusionConfigDir(repoRoot) {
+    return join(repoRoot, FUSION_CONFIG_DIRNAME);
+}
+/** The `.fusionkit/fusion.json` settings file. */
 export function fusionConfigPath(repoRoot) {
+    return join(fusionConfigDir(repoRoot), FUSION_CONFIG_BASENAME);
+}
+/** The legacy `fusionkit.json` at the repo root (pre-`.fusionkit/`). */
+export function legacyFusionConfigPath(repoRoot) {
     return join(repoRoot, FUSION_CONFIG_FILENAME);
 }
+/** The `.fusionkit/prompts/` directory holding the override files. */
+export function fusionPromptsDir(repoRoot) {
+    return join(fusionConfigDir(repoRoot), FUSION_PROMPTS_DIRNAME);
+}
+/** The `.fusionkit/prompts/<id>.md` file for a single prompt override. */
+export function fusionPromptPath(repoRoot, id) {
+    return join(fusionPromptsDir(repoRoot), `${id}.md`);
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -57,12 +113,16 @@ function validatePanelEntry(entry, index) {
     }
     return spec;
 }
-/** Validate a parsed object as a {@link FusionConfig}, throwing on any problem. */
+/**
+ * Validate a parsed settings object as a {@link FusionConfig}, throwing on any
+ * problem. Prompt overrides are loaded separately from `.fusionkit/prompts/`,
+ * not from this object. A `v1` version is accepted and upgraded to `v2`.
+ */
 export function parseFusionConfig(raw, source) {
     if (!isRecord(raw))
         throw new FusionConfigError(`${source}: must be a JSON object`);
-    if (raw.version !== FUSION_CONFIG_VERSION) {
-        throw new FusionConfigError(`${source}: unsupported version ${JSON.stringify(raw.version)} (expected "${FUSION_CONFIG_VERSION}")`);
+    if (typeof raw.version !== "string" || !SUPPORTED_CONFIG_VERSIONS.includes(raw.version)) {
+        throw new FusionConfigError(`${source}: unsupported version ${JSON.stringify(raw.version)} (expected one of ${SUPPORTED_CONFIG_VERSIONS.join(", ")})`);
     }
     const config = { version: FUSION_CONFIG_VERSION };
     if (raw.tool !== undefined) {
@@ -96,12 +156,6 @@ export function parseFusionConfig(raw, source) {
             throw new FusionConfigError(`${source}: portless must be a boolean`);
         config.portless = raw.portless;
     }
-    if (raw.cursorKitDir !== undefined && raw.cursorKitDir !== null) {
-        if (typeof raw.cursorKitDir !== "string") {
-            throw new FusionConfigError(`${source}: cursorKitDir must be a string or null`);
-        }
-        config.cursorKitDir = raw.cursorKitDir;
-    }
     if (raw.port !== undefined && raw.port !== null) {
         if (typeof raw.port !== "number" || !Number.isInteger(raw.port) || raw.port < 0) {
             throw new FusionConfigError(`${source}: port must be a non-negative integer or null`);
@@ -110,14 +164,7 @@ export function parseFusionConfig(raw, source) {
     }
     return config;
 }
-/**
- * Load `<repoRoot>/fusionkit.json` if present. Returns `undefined` when the file
- * does not exist; throws {@link FusionConfigError} on malformed content.
- */
-export function loadFusionConfig(repoRoot) {
-    const path = fusionConfigPath(repoRoot);
-    if (!existsSync(path))
-        return undefined;
+function readAndParse(path) {
     let raw;
     try {
         raw = JSON.parse(readFileSync(path, "utf8"));
@@ -127,12 +174,89 @@ export function loadFusionConfig(repoRoot) {
     }
     return parseFusionConfig(raw, path);
 }
-/** Write `fusionkit.json` at the repo root, refusing to clobber unless `force`. */
+/**
+ * Read the committed prompt overrides from `.fusionkit/prompts/*.md`. Only files
+ * that exist and are non-empty (after trimming) become overrides.
+ */
+export function readFusionPrompts(repoRoot) {
+    const dir = fusionPromptsDir(repoRoot);
+    const prompts = {};
+    if (!existsSync(dir))
+        return prompts;
+    for (const id of PROMPT_IDS) {
+        const path = fusionPromptPath(repoRoot, id);
+        if (!existsSync(path))
+            continue;
+        const text = readFileSync(path, "utf8").trim();
+        if (text.length > 0)
+            prompts[id] = text;
+    }
+    return prompts;
+}
+function withPrompts(repoRoot, config) {
+    const prompts = readFusionPrompts(repoRoot);
+    if (Object.keys(prompts).length === 0)
+        return config;
+    return { ...config, prompts };
+}
+/**
+ * Load the per-repo config. Prefers `.fusionkit/config.json`; if it is absent
+ * but a legacy `fusionkit.json` exists, auto-migrates it into the folder (the
+ * original is left intact) and loads from there. Returns `undefined` when no
+ * config exists; throws {@link FusionConfigError} on malformed content.
+ *
+ * `onNotice` receives a one-line message when a migration happens.
+ */
+export function loadFusionConfig(repoRoot, onNotice) {
+    const newPath = fusionConfigPath(repoRoot);
+    if (existsSync(newPath)) {
+        return withPrompts(repoRoot, readAndParse(newPath));
+    }
+    const legacyPath = legacyFusionConfigPath(repoRoot);
+    if (!existsSync(legacyPath))
+        return undefined;
+    const config = readAndParse(legacyPath);
+    try {
+        writeFusionConfig(repoRoot, config);
+        onNotice?.(`migrated ${legacyPath} into ${newPath}`);
+    }
+    catch {
+        // Could not write the migrated copy (e.g. read-only FS); use the legacy
+        // file in place for this run rather than failing.
+    }
+    return withPrompts(repoRoot, config);
+}
+/**
+ * Write `.fusionkit/config.json` (creating the folder), refusing to clobber
+ * unless `force`. Prompt overrides are stored as files, not inline, so any
+ * `prompts` on the config object is omitted here.
+ */
 export function writeFusionConfig(repoRoot, config, options = {}) {
     const path = fusionConfigPath(repoRoot);
     if (existsSync(path) && options.force !== true) {
         throw new FusionConfigError(`${path} already exists (pass --force to overwrite)`);
     }
-    writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+    mkdirSync(fusionConfigDir(repoRoot), { recursive: true });
+    const { prompts: _prompts, ...persisted } = config;
+    writeFileSync(path, JSON.stringify(persisted, null, 2) + "\n");
     return path;
 }
+/**
+ * Write prompt override files into `.fusionkit/prompts/`. Existing files are
+ * left untouched unless `force`. Returns the paths actually written.
+ */
+export function writeFusionPrompts(repoRoot, prompts, options = {}) {
+    mkdirSync(fusionPromptsDir(repoRoot), { recursive: true });
+    const written = [];
+    for (const id of PROMPT_IDS) {
+        const text = prompts[id];
+        if (text === undefined)
+            continue;
+        const path = fusionPromptPath(repoRoot, id);
+        if (existsSync(path) && options.force !== true)
+            continue;
+        writeFileSync(path, text.endsWith("\n") ? text : `${text}\n`);
+        written.push(path);
+    }
+    return written;
+}

package/dist/fusion-init.d.ts

@@ -1,4 +1,5 @@
 export declare function runFusionInit(input: {
     repoRoot?: string;
     force?: boolean;
+    fusionkitDir?: string;
 }): Promise<number>;