@fusionkit/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,77 @@
+# fusionkit
+
+Real model fusion behind your coding agent. `fusionkit` spins up a panel of
+models, has each produce a real candidate, and lets a judge synthesize the
+answer your coding agent (Codex, Claude Code, or Cursor) actually runs — all from
+one command.
+
+```bash
+npm install -g @fusionkit/cli
+cd your-project        # a git repo
+fusionkit doctor       # check prerequisites
+fusionkit codex        # launch Codex backed by the fusion panel
+```
+
+## Prerequisites
+
+`fusionkit` orchestrates other tools, so a few things must be available:
+
+- **[uv](https://docs.astral.sh/uv/getting-started/installation/)** — provides
+  `uvx`, used to run the Python synthesizer (`fusionkit` on PyPI). No manual
+  Python install needed.
+- **A coding agent on your PATH** — one of:
+  [`codex`](https://github.com/openai/codex),
+  [`claude`](https://docs.anthropic.com/en/docs/claude-code/overview), or
+  [`cursor-agent`](https://cursor.com/cli).
+- **Provider API keys** for the default cloud panel: `OPENAI_API_KEY` and
+  `ANTHROPIC_API_KEY` (exported, or in a project `.env` — fusionkit loads it
+  automatically). Not needed for the local MLX panel (`--local`, Apple Silicon).
+- **A git repository** — the panel fuses over the code in your current repo.
+
+Run `fusionkit doctor` any time to see exactly what is and isn't ready.
+
+> Two packages share the name "fusionkit": this npm CLI (`@fusionkit/cli`, the
+> `fusionkit` command) and the Python distribution (`fusionkit` on PyPI) that
+> provides the synthesizer. The CLI fetches the pinned PyPI build via `uvx`
+> automatically; `fusionkit --version` prints both versions.
+
+## Cost
+
+The default panel runs **multiple frontier cloud models plus a judge** on every
+prompt, so usage adds up. fusionkit asks for confirmation before starting a
+cloud panel (skip with `--yes`). Use `--local` for the on-device MLX panel, or
+`--model` to pick cheaper models.
+
+## Per-repo config
+
+Tired of long flag lines? Scaffold a committed `fusionkit.json`:
+
+```bash
+fusionkit fusion 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`.
+
+## 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 fusion init` — scaffold `fusionkit.json` for this repo.
+- `fusionkit doctor` — check prerequisites with fix hints.
+- `fusionkit status` — show the effective config and what a run will do.
+
+Useful flags: `--local`, `--observe`, `--model ID=PROVIDER:MODEL`,
+`--judge-model`, `--repo <dir>`, `--yes`. fusionkit's own flags must precede the
+tool name; everything after the tool is forwarded to it.
+
+## Notes
+
+- `--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.

package/dist/cli.d.ts

@@ -1,8 +1,2 @@
 import { Command } from "commander";
-/**
- * Build the `fusionkit` command tree. The global `--dir` option must precede the
- * subcommand (`enablePositionalOptions` keeps the launcher commands' passthrough
- * unambiguous). Each `register*` helper attaches its command(s) and reads the
- * global home directory via `program.opts().dir`.
- */
 export declare function buildProgram(): Command;

package/dist/cli.js

@@ -1,4 +1,8 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
+import { FUSIONKIT_PYPI_VERSION } from "./fusion-quickstart.js";
+import { registerDoctor } from "./commands/doctor.js";
 import { registerEnsemble } from "./commands/ensemble.js";
 import { registerFusion } from "./commands/fusion.js";
 import { registerInit } from "./commands/init.js";
@@ -14,11 +18,22 @@ import { registerSecrets } from "./commands/secrets.js";
  * unambiguous). Each `register*` helper attaches its command(s) and reads the
  * global home directory via `program.opts().dir`.
  */
+function cliVersion() {
+    // dist/cli.js -> ../package.json is the published package manifest.
+    try {
+        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 export function buildProgram() {
     const program = new Command();
     program
         .name("fusionkit")
         .description("real model fusion behind your coding agent (codex, claude, cursor)")
+        .version(`@fusionkit/cli ${cliVersion()} (synthesizer: fusionkit@${FUSIONKIT_PYPI_VERSION} from PyPI)`, "-v, --version", "print the CLI (npm) and pinned synthesizer (PyPI) versions")
         .option("-d, --dir <dir>", "fusionkit home (default: ./.fusionkit)")
         .enablePositionalOptions();
     registerInit(program);
@@ -30,5 +45,6 @@ export function buildProgram() {
     registerEnsemble(program);
     registerLocal(program);
     registerFusion(program);
+    registerDoctor(program);
     return program;
 }

package/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerDoctor(program: Command): void;

package/dist/commands/doctor.js

@@ -0,0 +1,136 @@
+import { join } from "node:path";
+import { DEFAULT_CLOUD_PANEL, DEFAULT_TRIO, defaultKeyEnv, gitToplevel, loadEnvFileInto } from "../fusion-quickstart.js";
+import { loadFusionConfig, fusionConfigPath, FusionConfigError } from "../fusion-config.js";
+import { hasBinary, INSTALL_HINTS } from "../shared/preflight.js";
+import { bold, brandHeader, cyan, dim, glyph, gray, green, red, yellow } from "../ui/theme.js";
+function line(check) {
+    const mark = check.ok ? green(glyph.tick()) : red(glyph.cross());
+    const detail = check.detail !== undefined ? ` ${dim(check.detail)}` : "";
+    const hint = !check.ok && check.hint !== undefined ? `\n    ${yellow(glyph.arrow())} ${check.hint}` : "";
+    return `${mark} ${check.label}${detail}${hint}`;
+}
+function keyPresent(name) {
+    const value = process.env[name];
+    return value !== undefined && value.length > 0;
+}
+/** `fusionkit doctor` — a proactive environment checklist with fix hints. */
+function runDoctor() {
+    // Match runtime: a project .env makes provider keys available without export.
+    loadEnvFileInto(join(process.cwd(), ".env"), process.env);
+    console.log(`\n${brandHeader("environment check")}\n`);
+    const runner = hasBinary("uvx") || hasBinary("uv");
+    const checks = [];
+    checks.push({
+        label: "uv / uvx (Python runner for the synthesizer)",
+        ok: runner,
+        ...(runner ? {} : { hint: INSTALL_HINTS.uvx })
+    });
+    checks.push({ label: "git (repo detection)", ok: hasBinary("git"), hint: "install git" });
+    const repoRoot = gitToplevel(process.cwd());
+    checks.push({
+        label: "inside a git repository",
+        ok: repoRoot !== undefined,
+        ...(repoRoot !== undefined ? { detail: repoRoot } : { hint: "cd into your project, or run `git init`" })
+    });
+    console.log(bold("prerequisites"));
+    for (const check of checks)
+        console.log(`  ${line(check)}`);
+    console.log("");
+    console.log(bold("coding agents (install the one you use)"));
+    for (const [bin, tool] of [
+        ["codex", "codex"],
+        ["claude", "claude"],
+        ["cursor-agent", "cursor"]
+    ]) {
+        const ok = hasBinary(bin);
+        console.log(`  ${line({ label: `${tool} (${bin})`, ok, ...(ok ? {} : { hint: INSTALL_HINTS[bin] ?? `install ${bin}` }) })}`);
+    }
+    console.log("");
+    console.log(bold("provider keys (needed by the cloud panel)"));
+    for (const name of ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GEMINI_API_KEY"]) {
+        const ok = keyPresent(name);
+        console.log(`  ${line({ label: name, ok, detail: ok ? "set" : "not set", ...(ok ? {} : { hint: `export ${name}=... (or add it to .env)` }) })}`);
+    }
+    // Config status, if any.
+    if (repoRoot !== undefined) {
+        console.log("");
+        console.log(bold("repo config"));
+        try {
+            const config = loadFusionConfig(repoRoot);
+            if (config === undefined) {
+                console.log(`  ${gray(glyph.bullet())} no ${cyan("fusionkit.json")} yet — run ${bold("fusionkit fusion init")}`);
+            }
+            else {
+                console.log(`  ${green(glyph.tick())} ${cyan(fusionConfigPath(repoRoot))}`);
+                console.log(`    ${dim(`tool: ${config.tool ?? "(unset)"}  panel: ${(config.panel ?? []).map((s) => s.id).join(", ") || "(unset)"}`)}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof FusionConfigError ? error.message : String(error);
+            console.log(`  ${red(glyph.cross())} ${message}`);
+        }
+    }
+    console.log("");
+    if (!runner) {
+        console.log(red("fusionkit needs uv/uvx to run the synthesizer. Install it, then re-run `fusionkit doctor`."));
+        return 1;
+    }
+    console.log(green("ready. Try: ") + bold("fusionkit codex"));
+    return 0;
+}
+function panelLabel(spec) {
+    const provider = spec.provider ?? "mlx";
+    const key = spec.keyEnv ?? defaultKeyEnv(provider);
+    const keyNote = key !== undefined ? ` ${gray(`[${key}]`)}` : "";
+    return `${spec.id} = ${provider}:${spec.model}${keyNote}`;
+}
+/** `fusionkit status` — show the effective config and a dry-run preview. */
+function runStatus() {
+    const repoRoot = gitToplevel(process.cwd());
+    console.log(`\n${brandHeader("status")}\n`);
+    if (repoRoot === undefined) {
+        console.log(gray("not inside a git repository; run from your project."));
+        return 0;
+    }
+    let config;
+    try {
+        config = loadFusionConfig(repoRoot);
+    }
+    catch (error) {
+        console.log(`${red("config error:")} ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    const local = config?.local === true;
+    const panel = config?.panel ?? (local ? [...DEFAULT_TRIO] : [...DEFAULT_CLOUD_PANEL]);
+    const tool = config?.tool ?? "codex";
+    const judge = config?.judgeModel ?? panel[0]?.model ?? "(first panel model)";
+    const source = config !== undefined ? cyan(fusionConfigPath(repoRoot)) : dim("(built-in defaults; run `fusionkit fusion init`)");
+    console.log(`${dim("config:")} ${source}`);
+    console.log(`${dim("repo:")}   ${repoRoot}`);
+    console.log(`${dim("tool:")}   ${bold(tool)}`);
+    console.log(`${dim("judge:")}  ${judge}`);
+    console.log(`${dim("observe:")} ${config?.observe === true ? "on" : "off"}`);
+    console.log(bold("\npanel"));
+    for (const spec of panel)
+        console.log(`  ${glyph.bullet()} ${panelLabel(spec)}`);
+    const spawnsCloud = panel.some((spec) => (spec.provider ?? "mlx") !== "mlx");
+    console.log("");
+    console.log(dim(`a run will: spawn ${panel.length} model server(s), a synthesizer, and the gateway, then launch ${tool}.`));
+    if (spawnsCloud)
+        console.log(yellow(`${glyph.warn()} cloud panel: each prompt fans out across the panel + judge (provider usage applies).`));
+    return 0;
+}
+export function registerDoctor(program) {
+    program
+        .command("doctor")
+        .description("check that prerequisites (uv, agents, keys, git) are ready")
+        .action(() => {
+        process.exit(runDoctor());
+    });
+    program
+        .command("status")
+        .description("show the effective fusion config and a dry-run preview")
+        .action(() => {
+        process.exit(runStatus());
+    });
+}

package/dist/commands/fusion.js

@@ -1,5 +1,8 @@
 import { resolve } from "node:path";
-import { FUSION_TOOLS, pickTool, runFusion } from "../fusion-quickstart.js";
+import { FUSION_TOOLS, gitToplevel, pickTool, runFusion } from "../fusion-quickstart.js";
+import { loadFusionConfig } from "../fusion-config.js";
+import { runFusionInit } from "../fusion-init.js";
+import { fail } from "../shared/errors.js";
 import { collect, parseFusionTool, parseIdValue, parsePanelModelSpec, parsePort } from "../shared/options.js";
 /** Attach the panel/gateway flags shared by `fusion` and the per-tool launchers. */
 function applyFusionOptions(command) {
@@ -14,13 +17,16 @@ function applyFusionOptions(command) {
         .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("--observe", "boot the local scope dashboard and stream live trace events")
+        .option("--no-observe", "override a fusionkit.json 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)")
         .allowUnknownOption()
         .passThroughOptions();
 }
-/** Build the `RunFusionOptions` shared by every entrypoint from parsed flags. */
+/** Build the flag-only `RunFusionOptions` (no config/defaults applied yet). */
 function resolveOptions(opts) {
     const options = {};
     const keyEnvs = {};
@@ -38,10 +44,14 @@ function resolveOptions(opts) {
         options.repo = resolve(opts.repo);
     if (opts.cursorKitDir !== undefined)
         options.cursorKitDir = resolve(opts.cursorKitDir);
-    if (opts.local === true)
-        options.local = true;
-    if (opts.observe === true)
-        options.observe = true;
+    // 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)
+        options.local = opts.local;
+    if (opts.observe !== undefined)
+        options.observe = opts.observe;
+    if (opts.yes === true)
+        options.yes = true;
     if (opts.authToken !== undefined)
         options.authToken = opts.authToken;
     if (opts.port !== undefined)
@@ -71,16 +81,65 @@ function resolveOptions(opts) {
     }
     return options;
 }
+/** Fill any option the user did not set explicitly from `fusionkit.json`. */
+function mergeConfig(options, config) {
+    if (options.models === undefined && options.endpoints === undefined && config.panel !== undefined && config.panel.length > 0) {
+        options.models = config.panel.map((spec) => ({ ...spec }));
+    }
+    if (options.judgeModel === undefined && config.judgeModel !== undefined)
+        options.judgeModel = config.judgeModel;
+    if (options.local === undefined && config.local !== undefined)
+        options.local = config.local;
+    if (options.observe === undefined && config.observe !== undefined)
+        options.observe = config.observe;
+    if (options.cursorKitDir === undefined && config.cursorKitDir != null)
+        options.cursorKitDir = config.cursorKitDir;
+    if (options.port === undefined && config.port != null)
+        options.port = config.port;
+}
+/** The repo root used for config lookup: --repo if given, else the cwd's git root. */
+function configRepoRoot(options) {
+    return options.repo ?? gitToplevel(process.cwd());
+}
+/**
+ * Resolve options + the config-provided default tool. Flags always win over the
+ * file; the file wins over built-in defaults.
+ */
+function resolveContext(opts) {
+    const options = resolveOptions(opts);
+    const repoRoot = configRepoRoot(options);
+    let config;
+    if (repoRoot !== undefined) {
+        try {
+            config = loadFusionConfig(repoRoot);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (config !== undefined)
+        mergeConfig(options, config);
+    return { options, ...(config?.tool !== undefined ? { configTool: config.tool } : {}) };
+}
 export function registerFusion(program) {
     // Generic `fusion [tool]` — keeps the original surface and interactive pick.
     applyFusionOptions(program
         .command("fusion")
         .description("one command: real model fusion backs a coding agent")
-        .argument("[tool]", `${FUSION_TOOLS.join(" | ")} (omit on a TTY to pick interactively)`)
+        .argument("[tool]", `${FUSION_TOOLS.join(" | ")} | init (omit on a TTY to pick interactively)`)
         .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.")
+        .option("--tool <tool>", `coding agent to launch (${FUSION_TOOLS.join(" | ")})`)
+        .option("--force", "overwrite an existing fusionkit.json (with `fusion init`)"))
+        .addHelpText("after", "\nfusionkit's own flags must precede the tool name; everything after the tool is forwarded to it." +
+        "\nRun `fusionkit fusion init` to scaffold a committed fusionkit.json for this repo.")
         .action(async (positionalTool, args, opts) => {
+        // `fusion init` scaffolds the per-repo config instead of launching a tool.
+        if (positionalTool === "init") {
+            const repoRoot = configRepoRoot(resolveOptions(opts));
+            const code = await runFusionInit({ repoRoot, force: opts.force === true });
+            process.exit(code);
+        }
+        const { options, configTool } = resolveContext(opts);
         let tool = opts.tool ? parseFusionTool(opts.tool) : undefined;
         let toolArgs = [...args];
         if (positionalTool !== undefined) {
@@ -91,8 +150,7 @@ export function registerFusion(program) {
                 toolArgs = [positionalTool, ...toolArgs];
             }
         }
-        const options = resolveOptions(opts);
-        const resolvedTool = tool ?? (process.stdin.isTTY ? await pickTool() : "codex");
+        const resolvedTool = tool ?? configTool ?? (process.stdin.isTTY ? await pickTool() : "codex");
         const code = await runFusion(resolvedTool, toolArgs, options);
         process.exit(code);
     });
@@ -104,7 +162,7 @@ export function registerFusion(program) {
             .argument("[args...]", `arguments forwarded to ${tool}`))
             .addHelpText("after", `\nfusionkit's own flags must precede any ${tool} args; everything after is forwarded to ${tool}.`)
             .action(async (args, opts) => {
-            const options = resolveOptions(opts);
+            const { options } = resolveContext(opts);
             const code = await runFusion(tool, args, options);
             process.exit(code);
         });

package/dist/fusion-config.d.ts

@@ -0,0 +1,28 @@
+import type { FusionTool, PanelModelSpec } from "./fusion-quickstart.js";
+export declare const FUSION_CONFIG_FILENAME = "fusionkit.json";
+export declare const FUSION_CONFIG_VERSION = "fusionkit.fusion.v1";
+export type FusionConfig = {
+    version: typeof FUSION_CONFIG_VERSION;
+    tool?: FusionTool;
+    panel?: PanelModelSpec[];
+    judgeModel?: string;
+    local?: boolean;
+    observe?: boolean;
+    cursorKitDir?: string | null;
+    port?: number | null;
+};
+export declare class FusionConfigError extends Error {
+    constructor(message: string);
+}
+export declare function fusionConfigPath(repoRoot: string): string;
+/** Validate a parsed object as a {@link FusionConfig}, throwing on any problem. */
+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.
+ */
+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;

package/dist/fusion-config.js

@@ -0,0 +1,133 @@
+/**
+ * Per-repo fusion configuration (`fusionkit.json`, committed 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.
+ *
+ * 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.
+ */
+import { existsSync, 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_FILENAME = "fusionkit.json";
+export const FUSION_CONFIG_VERSION = "fusionkit.fusion.v1";
+export class FusionConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FusionConfigError";
+    }
+}
+export function fusionConfigPath(repoRoot) {
+    return join(repoRoot, FUSION_CONFIG_FILENAME);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validatePanelEntry(entry, index) {
+    if (!isRecord(entry)) {
+        throw new FusionConfigError(`panel[${index}] must be an object`);
+    }
+    const { id, model, provider, baseUrl, keyEnv } = entry;
+    if (typeof id !== "string" || id.length === 0) {
+        throw new FusionConfigError(`panel[${index}].id must be a non-empty string`);
+    }
+    if (typeof model !== "string" || model.length === 0) {
+        throw new FusionConfigError(`panel[${index}].model must be a non-empty string`);
+    }
+    const spec = { id, model };
+    if (provider !== undefined) {
+        if (typeof provider !== "string" || !PANEL_PROVIDERS.includes(provider)) {
+            throw new FusionConfigError(`panel[${index}].provider must be one of ${PANEL_PROVIDERS.join(", ")}`);
+        }
+        spec.provider = provider;
+    }
+    if (baseUrl !== undefined) {
+        if (typeof baseUrl !== "string")
+            throw new FusionConfigError(`panel[${index}].baseUrl must be a string`);
+        spec.baseUrl = baseUrl;
+    }
+    if (keyEnv !== undefined) {
+        if (typeof keyEnv !== "string")
+            throw new FusionConfigError(`panel[${index}].keyEnv must be a string`);
+        spec.keyEnv = keyEnv;
+    }
+    return spec;
+}
+/** Validate a parsed object as a {@link FusionConfig}, throwing on any problem. */
+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}")`);
+    }
+    const config = { version: FUSION_CONFIG_VERSION };
+    if (raw.tool !== undefined) {
+        if (typeof raw.tool !== "string" || !FUSION_TOOLS.includes(raw.tool)) {
+            throw new FusionConfigError(`${source}: tool must be one of ${FUSION_TOOLS.join(", ")}`);
+        }
+        config.tool = raw.tool;
+    }
+    if (raw.panel !== undefined) {
+        if (!Array.isArray(raw.panel))
+            throw new FusionConfigError(`${source}: panel must be an array`);
+        config.panel = raw.panel.map((entry, index) => validatePanelEntry(entry, index));
+    }
+    if (raw.judgeModel !== undefined) {
+        if (typeof raw.judgeModel !== "string")
+            throw new FusionConfigError(`${source}: judgeModel must be a string`);
+        config.judgeModel = raw.judgeModel;
+    }
+    if (raw.local !== undefined) {
+        if (typeof raw.local !== "boolean")
+            throw new FusionConfigError(`${source}: local must be a boolean`);
+        config.local = raw.local;
+    }
+    if (raw.observe !== undefined) {
+        if (typeof raw.observe !== "boolean")
+            throw new FusionConfigError(`${source}: observe must be a boolean`);
+        config.observe = raw.observe;
+    }
+    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`);
+        }
+        config.port = raw.port;
+    }
+    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;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new FusionConfigError(`${path}: invalid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    return parseFusionConfig(raw, path);
+}
+/** Write `fusionkit.json` at the repo root, refusing to clobber unless `force`. */
+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");
+    return path;
+}

package/dist/fusion-init.d.ts

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