@fusionkit/cli 0.1.5 → 0.1.7

package/dist/fusion/env.js

@@ -0,0 +1,98 @@
+/**
+ * Shared types, panel defaults, and env helpers for the `fusionkit <tool>`
+ * launcher. Kept dependency-light (node builtins only) so every other fusion
+ * module and the orchestrator can import from here without cycles.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+/**
+ * The PyPI version of the `fusionkit` Python distribution that provides the
+ * synthesizer (`fusionkit serve`) and the single-model OpenAI shim
+ * (`fusionkit serve-endpoint`). Pinned so `uvx` resolves a reproducible build.
+ */
+export const FUSIONKIT_PYPI_VERSION = "0.3.0";
+/**
+ * Default cloud panel — works cross-platform with only `OPENAI_API_KEY` and
+ * `ANTHROPIC_API_KEY` set. The judge defaults to the first entry.
+ */
+export const DEFAULT_CLOUD_PANEL = [
+    { id: "gpt", model: "gpt-5.5", provider: "openai" },
+    { id: "sonnet", model: "claude-sonnet-4-6", provider: "anthropic" }
+];
+/** The locally cached MLX trio (Apple Silicon only) used behind `--local`. */
+export const DEFAULT_TRIO = [
+    { id: "qwen", model: "mlx-community/Qwen3-1.7B-4bit", provider: "mlx" },
+    { id: "gemma", model: "mlx-community/gemma-3-1b-it-4bit", provider: "mlx" },
+    { id: "llama", model: "mlx-community/Llama-3.2-1B-Instruct-4bit", provider: "mlx" }
+];
+/**
+ * How to invoke the `fusionkit` Python CLI: from PyPI via `uvx` by default
+ * (no checkout), or from a local checkout via `uv run` when `fusionkitDir` is
+ * given (a dev override). Returns the command plus the argv prefix that
+ * precedes the subcommand (`serve`, `serve-endpoint`, ...).
+ */
+export function fusionkitPyCommand(fusionkitDir) {
+    if (fusionkitDir !== undefined) {
+        return { command: "uv", prefix: ["run", "fusionkit"], cwd: fusionkitDir };
+    }
+    return { command: "uvx", prefix: [`fusionkit@${FUSIONKIT_PYPI_VERSION}`] };
+}
+/**
+ * Parse a `.env` file (KEY=VALUE lines, `#` comments, optional `export`,
+ * single/double quotes) and fill any keys not already present in `env`.
+ * Existing env values win, so an explicitly exported key is never overridden.
+ */
+export function loadEnvFileInto(path, env) {
+    if (!existsSync(path))
+        return;
+    for (const rawLine of readFileSync(path, "utf8").split("\n")) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        const withoutExport = line.startsWith("export ") ? line.slice("export ".length) : line;
+        const eq = withoutExport.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = withoutExport.slice(0, eq).trim();
+        let value = withoutExport.slice(eq + 1).trim();
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        if (env[key] === undefined)
+            env[key] = value;
+    }
+}
+/** Default env var holding the API key for each cloud provider. */
+export function defaultKeyEnv(provider) {
+    switch (provider) {
+        case "openai":
+            return "OPENAI_API_KEY";
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "google":
+            return "GEMINI_API_KEY";
+        case "openai-compatible":
+        case "mlx":
+            return undefined;
+        default: {
+            const exhaustive = provider;
+            throw new Error(`unknown provider ${String(exhaustive)}`);
+        }
+    }
+}
+/** The git repository root containing `dir`, or undefined if it is not in a repo. */
+export function gitToplevel(dir) {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: dir,
+            encoding: "utf8",
+            // Don't leak git's "fatal: not a git repository" to our stderr; we surface
+            // a clearer message ourselves.
+            stdio: ["ignore", "pipe", "ignore"]
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/fusion/observability.d.ts

@@ -0,0 +1,39 @@
+import type { PortlessSession } from "../shared/portless.js";
+import type { StackReporter } from "./env.js";
+/** Fixed port for the local observability dashboard (the scope app). */
+export declare const SCOPE_DASHBOARD_PORT = 4317;
+/**
+ * Locate the isolated scope dashboard app (handoffkit/apps/scope) by walking up
+ * from this module. Works from both the compiled dist and src layouts. Only the
+ * monorepo dev fallback uses this — published installs ship a prebuilt bundle.
+ */
+export declare function findScopeAppDir(): string;
+/**
+ * Path to the prebuilt, self-contained dashboard server staged into the CLI
+ * package (`scope/server.js`, a sibling of `dist/`), or undefined when it is
+ * absent — i.e. a monorepo dev checkout where the bundle was never staged. This
+ * module compiles to `<cli-package>/dist/fusion/observability.js`, so the staged
+ * bundle is two levels up at `<cli-package>/scope/server.js`.
+ */
+export declare function bundledScopeServer(): string | undefined;
+/** Best-effort: open a URL in the default browser (no-op on failure). */
+export declare function openUrl(url: string): void;
+export type Observability = {
+    url: string;
+    ingestUrl: string;
+    traceDir: string;
+    close: () => Promise<void>;
+};
+/**
+ * Start the scope dashboard on the fixed port, backed by a fresh per-run SQLite
+ * file and trace dir, and return the URLs the caller injects (as
+ * FUSION_TRACE_URL / FUSION_TRACE_DIR) into every spawned process. Prefers the
+ * prebuilt bundle shipped inside the npm package; falls back to building the
+ * app from source in a monorepo dev checkout.
+ */
+export declare function startObservability(input: {
+    log: (line: string) => void;
+    logFile?: string;
+    report?: StackReporter;
+    portless: PortlessSession;
+}): Promise<Observability>;

package/dist/fusion/observability.js

@@ -0,0 +1,227 @@
+/**
+ * The local scope observability dashboard: locating the prebuilt bundle (or
+ * building it from source in a monorepo checkout), starting it on the fixed
+ * port, and exposing the trace URLs the orchestrator injects into spawned
+ * children.
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnLogged, terminate, waitForHttp } from "../shared/proc.js";
+/** Fixed port for the local observability dashboard (the scope app). */
+export const SCOPE_DASHBOARD_PORT = 4317;
+/**
+ * Locate the isolated scope dashboard app (handoffkit/apps/scope) by walking up
+ * from this module. Works from both the compiled dist and src layouts. Only the
+ * monorepo dev fallback uses this — published installs ship a prebuilt bundle.
+ */
+export function findScopeAppDir() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth++) {
+        const candidate = join(dir, "apps", "scope");
+        if (existsSync(join(candidate, "package.json")))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error("could not locate apps/scope relative to the handoffkit CLI");
+}
+/**
+ * Path to the prebuilt, self-contained dashboard server staged into the CLI
+ * package (`scope/server.js`, a sibling of `dist/`), or undefined when it is
+ * absent — i.e. a monorepo dev checkout where the bundle was never staged. This
+ * module compiles to `<cli-package>/dist/fusion/observability.js`, so the staged
+ * bundle is two levels up at `<cli-package>/scope/server.js`.
+ */
+export function bundledScopeServer() {
+    const serverJs = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "scope", "server.js");
+    return existsSync(serverJs) ? serverJs : undefined;
+}
+/**
+ * Inject the portless CA so spawned Node children (dashboard, cursor bridge,
+ * launched agents) trust the proxy's HTTPS routes. Only `NODE_EXTRA_CA_CERTS` is
+ * set: it *extends* Node's trust store. We deliberately do NOT set Python's
+ * `SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`, because those *replace* the bundle — and
+ * pointing them at the portless CA alone breaks the router's outbound HTTPS to
+ * real providers (api.openai.com, etc.). The router never calls a portless HTTPS
+ * URL (providers go direct; MLX is loopback), so it needs no portless CA. If a
+ * Python process ever must reach a portless HTTPS URL, build a combined
+ * certifi+portless bundle rather than replacing the bundle here. A no-op when
+ * portless is off (no CA path).
+ */
+function withCaEnv(env, caCertPath) {
+    if (caCertPath === undefined)
+        return env;
+    return {
+        ...env,
+        NODE_EXTRA_CA_CERTS: env.NODE_EXTRA_CA_CERTS ?? caCertPath
+    };
+}
+/** Best-effort: open a URL in the default browser (no-op on failure). */
+export function openUrl(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(command, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // opening a browser is a convenience, never required
+    }
+}
+/**
+ * Spawn the prebuilt standalone dashboard server (`node scope/server.js`) on the
+ * fixed port. The Next standalone entrypoint reads PORT/HOSTNAME from the env
+ * (there is no `-p` flag). This is the path every npm-installed user takes.
+ */
+function startBundledDashboard(input) {
+    return spawnLogged(process.execPath, [input.serverJs], {
+        cwd: dirname(input.serverJs),
+        ...(input.logFile !== undefined ? { logFile: input.logFile } : {}),
+        env: { ...input.env, PORT: String(SCOPE_DASHBOARD_PORT), HOSTNAME: "127.0.0.1" }
+    });
+}
+/**
+ * Monorepo dev fallback: build the scope app once (reusing a prior build) and
+ * `next start` it on the fixed port. Only reached in a handoffkit checkout where
+ * no bundle was staged; published installs always use {@link startBundledDashboard}.
+ */
+function startDevDashboard(input) {
+    const scopeDir = findScopeAppDir();
+    const nextBin = join(scopeDir, "node_modules", ".bin", "next");
+    if (!existsSync(nextBin)) {
+        throw new Error("the observability dashboard is not available in this checkout.\n" +
+            `  Install its dependencies once: cd ${scopeDir} && pnpm install`);
+    }
+    // Rebuilding every run is slow; reuse a prior build when present. The build
+    // output is captured (never inherited) so it can't corrupt a live checklist.
+    const alreadyBuilt = existsSync(join(scopeDir, ".next", "BUILD_ID"));
+    if (!alreadyBuilt) {
+        try {
+            const buildOut = execFileSync(nextBin, ["build"], {
+                cwd: scopeDir,
+                env: input.env,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"]
+            });
+            if (input.logFile !== undefined)
+                appendFileSync(input.logFile, buildOut);
+        }
+        catch (error) {
+            if (input.logFile !== undefined) {
+                appendFileSync(input.logFile, String(error.stdout ?? "") + String(error.stderr ?? ""));
+            }
+            throw new Error("the observability dashboard failed to build. See the log for details" +
+                (input.logFile ? `: ${input.logFile}` : ""));
+        }
+    }
+    return spawnLogged(nextBin, ["start", "-p", String(SCOPE_DASHBOARD_PORT)], {
+        cwd: scopeDir,
+        ...(input.logFile !== undefined ? { logFile: input.logFile } : {}),
+        env: input.env
+    });
+}
+/** Identity token of a reusable scope dashboard (any healthy instance qualifies). */
+const SCOPE_IDENTITY = "scope-dashboard";
+/**
+ * Start the scope dashboard on the fixed port, backed by a fresh per-run SQLite
+ * file and trace dir, and return the URLs the caller injects (as
+ * FUSION_TRACE_URL / FUSION_TRACE_DIR) into every spawned process. Prefers the
+ * prebuilt bundle shipped inside the npm package; falls back to building the
+ * app from source in a monorepo dev checkout.
+ */
+export async function startObservability(input) {
+    const traceDir = mkdtempSync(join(tmpdir(), "fusion-trace-"));
+    const dbPath = join(traceDir, "scope.db");
+    // The dashboard server loads node:sqlite; keep its experimental warnings out
+    // of the log just like the parent CLI. The per-run db/trace dir isolate state.
+    const childEnv = withCaEnv({
+        ...process.env,
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"].filter(Boolean).join(" "),
+        SCOPEKIT_DB: dbPath,
+        FUSION_TRACE_DIR: traceDir
+    }, input.portless.caCertPath);
+    const spawnDashboard = async () => {
+        const bundled = bundledScopeServer();
+        if (input.report)
+            input.report({ kind: "dashboard.start" });
+        else if (bundled !== undefined)
+            input.log("fusion: starting observability dashboard...");
+        else
+            input.log("fusion: building observability dashboard (one-time)...");
+        let proc;
+        try {
+            proc =
+                bundled !== undefined
+                    ? startBundledDashboard({
+                        serverJs: bundled,
+                        env: childEnv,
+                        ...(input.logFile !== undefined ? { logFile: input.logFile } : {})
+                    })
+                    : startDevDashboard({
+                        env: childEnv,
+                        traceDir,
+                        ...(input.logFile !== undefined ? { logFile: input.logFile } : {})
+                    });
+        }
+        catch (error) {
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+        try {
+            await waitForHttp(`http://127.0.0.1:${SCOPE_DASHBOARD_PORT}`, proc, {
+                timeoutMs: 60_000,
+                label: "dashboard"
+            });
+        }
+        catch (error) {
+            terminate(proc.child);
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+        return {
+            port: SCOPE_DASHBOARD_PORT,
+            ...(proc.child.pid !== undefined ? { pid: proc.child.pid } : {}),
+            close: () => terminate(proc.child)
+        };
+    };
+    let resolved;
+    try {
+        resolved = await input.portless.discoverOrSpawn({
+            name: "scope",
+            identity: SCOPE_IDENTITY,
+            healthCheck: async (loopbackUrl) => {
+                try {
+                    const response = await fetch(loopbackUrl, { signal: AbortSignal.timeout(2000) });
+                    return response.ok ? SCOPE_IDENTITY : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            spawn: spawnDashboard
+        });
+    }
+    catch (error) {
+        rmSync(traceDir, { recursive: true, force: true });
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+    if (input.report)
+        input.report({ kind: "dashboard.ready", detail: resolved.url });
+    else
+        input.log(`fusion: observability dashboard ready on ${resolved.url}`);
+    return {
+        url: resolved.url,
+        // Trace events post over loopback (the in-process emitters do not carry the
+        // portless CA), so ingest uses the raw port; the named URL is for humans.
+        ingestUrl: `${resolved.loopbackUrl}/api/ingest`,
+        traceDir,
+        close: async () => {
+            await resolved.close();
+            rmSync(traceDir, { recursive: true, force: true });
+        }
+    };
+}

package/dist/fusion/preflight.d.ts

@@ -0,0 +1,12 @@
+import type { FusionTool, PanelModelSpec, RunFusionOptions } from "./env.js";
+/** The PATH binary each coding agent launches as. `serve` launches nothing. */
+export declare function agentBinary(tool: FusionTool): string | undefined;
+/**
+ * Compute the binaries and API keys the run requires given the tool, panel, and
+ * options. Pre-running endpoints (`--model-endpoint`) and a pre-running
+ * `--synthesis-url` drop the corresponding requirements.
+ */
+export declare function preflightRequirements(tool: FusionTool, models: PanelModelSpec[], options: RunFusionOptions): {
+    requiredBins: string[];
+    requiredEnv: string[];
+};

package/dist/fusion/preflight.js

@@ -0,0 +1,42 @@
+/**
+ * Preflight: the binaries and API keys a `fusionkit <tool>` run requires, given
+ * the tool, panel, and options. The actual prerequisite check lives in
+ * `../shared/preflight.ts`; this computes what to check.
+ */
+import { toolRegistry } from "../tools.js";
+import { defaultKeyEnv } from "./env.js";
+/** The PATH binary each coding agent launches as. `serve` launches nothing. */
+export function agentBinary(tool) {
+    return toolRegistry.get(tool)?.binary;
+}
+/**
+ * Compute the binaries and API keys the run requires given the tool, panel, and
+ * options. Pre-running endpoints (`--model-endpoint`) and a pre-running
+ * `--synthesis-url` drop the corresponding requirements.
+ */
+export function preflightRequirements(tool, models, options) {
+    const requiredBins = [];
+    const requiredEnv = [];
+    const endpointsProvided = options.endpoints !== undefined;
+    const spawnsServers = !endpointsProvided;
+    const spawnsSynthesizer = options.synthesisUrl === undefined;
+    // The FusionKit Python CLI is fetched via uvx (or run from a local checkout).
+    if (spawnsServers || spawnsSynthesizer) {
+        requiredBins.push(options.fusionkitDir !== undefined ? "uv" : "uvx");
+    }
+    const agent = agentBinary(tool);
+    if (agent !== undefined)
+        requiredBins.push(agent);
+    // Cloud panel members need their provider key when we front them ourselves.
+    if (spawnsServers) {
+        for (const spec of models) {
+            const provider = spec.provider ?? "mlx";
+            if (provider === "mlx")
+                continue;
+            const keyEnv = spec.keyEnv ?? defaultKeyEnv(provider);
+            if (keyEnv !== undefined)
+                requiredEnv.push(keyEnv);
+        }
+    }
+    return { requiredBins, requiredEnv };
+}

package/dist/fusion/stack.d.ts

@@ -0,0 +1,66 @@
+import type { EnsembleModel } from "@fusionkit/ensemble";
+import type { PortlessSession } from "../shared/portless.js";
+import type { PromptOverrides } from "../fusion-config.js";
+import type { PanelModelSpec, StackReporter } from "./env.js";
+/**
+ * The single `fusionkit serve` router: one process that fronts every panel
+ * model (passthrough, routed by the endpoint id in the request `model` field)
+ * and also performs trajectory synthesis. `endpoints` maps each panel id to the
+ * router URL so the harness reaches its model through the one base URL.
+ */
+export type Router = {
+    url: string;
+    port: number;
+    /** The router process pid (owns its portless route across runs). */
+    pid?: number;
+    endpoints: Record<string, string>;
+    models: EnsembleModel[];
+    /** The endpoint id used as the judge/synthesizer. */
+    judgeModel: string;
+    /** Sorted endpoint ids — the router's discover-or-spawn identity token. */
+    identity: string;
+    close: () => Promise<void>;
+};
+/**
+ * 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 declare function startRouter(options: {
+    specs: PanelModelSpec[];
+    judgeModel?: string;
+    fusionkitDir?: string;
+    prompts?: PromptOverrides;
+    logsDir?: string;
+    report?: StackReporter;
+    log: (line: string) => void;
+}): Promise<Router>;
+export type FusionStack = {
+    fusionUrl: string;
+    endpoints: Record<string, string>;
+    close: () => Promise<void>;
+};
+export type StartFusionStackOptions = {
+    repo: string;
+    outputRoot: string;
+    models: PanelModelSpec[];
+    endpoints?: Record<string, string>;
+    fusionkitDir?: string;
+    /** System-prompt overrides emitted into the router's synthesizer config. */
+    prompts?: PromptOverrides;
+    judgeModel?: string;
+    /** Pre-running fusionkit serve URL for trajectory synthesis (skips spawn). */
+    synthesisUrl?: string;
+    host?: string;
+    port?: number;
+    authToken?: string;
+    timeoutMs?: number;
+    logsDir?: string;
+    report?: StackReporter;
+    /** Active portless session; defaults to a disabled (loopback) session. */
+    portless?: PortlessSession;
+    log: (line: string) => void;
+};
+export declare function startFusionStack(options: StartFusionStackOptions): Promise<FusionStack>;