@fusionkit/cli 0.1.5 → 0.1.6

package/dist/dashboard.js

@@ -0,0 +1,587 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { assertHarnessRunResultV1, MODEL_FUSION_SCHEMA_BUNDLE_HASH } from "@fusionkit/protocol";
+import { gitText } from "@fusionkit/workspace";
+import { createCommandHarness, createMockHarness, runEnsemble } from "@fusionkit/ensemble";
+import { envFlagEnabled, readEnv } from "@fusionkit/tools";
+import { toolRegistry } from "./tools.js";
+const PRODUCER_GIT_SHA = "0".repeat(40);
+const PRODUCER = "handoffkit-ensemble";
+const PRODUCER_VERSION = "0.1.0";
+const ZERO_GIT_SHA = "0".repeat(40);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_PROMPT = "Run the CI-safe harness smoke task and report concise evidence.";
+const DEFAULT_COMMAND_SUCCESS = "printf command-ok";
+const DEFAULT_COMMAND_FAILURE = "exit 7";
+const DEFAULT_OUTPUT_DIR = ".warrant/ensemble-dashboard";
+const ALL_LIVE_SMOKE_ENV = "FUSIONKIT_ENSEMBLE_LIVE_SMOKE";
+/** Dashboard capability overlays for the generic (non-tool) harnesses. */
+const COMMAND_CAPABILITIES = {
+    model_override: "supported",
+    transcript_capture: "supported",
+    diff_capture: "unsupported",
+    tool_loop_capture: "supported",
+    patch_apply_visibility: "unsupported",
+    route_model_observation: "unsupported",
+    verification_hint: "supported",
+    replay_support: "supported"
+};
+const MOCK_CAPABILITIES = {
+    model_override: "supported",
+    transcript_capture: "supported",
+    diff_capture: "supported",
+    tool_loop_capture: "supported",
+    patch_apply_visibility: "supported",
+    route_model_observation: "degraded",
+    verification_hint: "supported",
+    replay_support: "supported"
+};
+function metadata(schema, createdAt) {
+    return {
+        schema,
+        schema_version: "v1",
+        schema_bundle_hash: MODEL_FUSION_SCHEMA_BUNDLE_HASH,
+        producer: PRODUCER,
+        producer_version: PRODUCER_VERSION,
+        producer_git_sha: PRODUCER_GIT_SHA,
+        created_at: createdAt
+    };
+}
+function dashboardTools(options) {
+    return options.tools ?? toolRegistry.dashboardTools();
+}
+function safeFileName(value) {
+    return value.replace(/[^A-Za-z0-9_.:-]/g, "_");
+}
+function escapeMarkdownCell(value) {
+    return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function liveSmokeEnvEnabled(env, tool) {
+    return (tool.liveSmoke !== undefined &&
+        (envFlagEnabled(env, ALL_LIVE_SMOKE_ENV) || envFlagEnabled(env, tool.liveSmoke.envName)));
+}
+function requestedLiveSmokeTools(options) {
+    const liveCapable = options.tools.filter((tool) => tool.liveSmoke !== undefined);
+    const selected = options.liveSmoke?.length
+        ? liveCapable.filter((tool) => options.liveSmoke?.includes(tool.id))
+        : liveCapable;
+    return selected.filter((tool) => liveSmokeEnvEnabled(options.env, tool));
+}
+function descriptorForCapabilities(harness) {
+    return {
+        id: "capability_matrix",
+        harness,
+        models: [{ id: "capability", model: "capability-model" }],
+        runtime: { id: "local" },
+        judge: { id: "none" },
+        policy: {
+            id: "capability-policy",
+            allowedTools: ["read_file"],
+            sideEffects: "read_only",
+            timeoutMs: DEFAULT_TIMEOUT_MS
+        },
+        prompt: DEFAULT_PROMPT,
+        sourceRepo: "handoffkit",
+        baseGitSha: ZERO_GIT_SHA
+    };
+}
+function adapterCapabilities(harness) {
+    return harness.capabilities(descriptorForCapabilities(harness));
+}
+function mergeCapabilities(adapter, overlay) {
+    return { ...adapter, ...overlay };
+}
+function matrixRow(input) {
+    return input;
+}
+export function createHarnessCapabilityMatrix(options = {}) {
+    const env = options.env ?? {};
+    const toolRows = dashboardTools(options).map((tool) => matrixRow({
+        harnessId: tool.id,
+        harnessKind: tool.harnessKind,
+        displayName: tool.displayName,
+        availability: tool.availability,
+        capabilities: mergeCapabilities(adapterCapabilities(tool.makeMatrixHarness(env)), tool.capabilities),
+        notes: tool.notes
+    }));
+    const rows = [
+        ...toolRows,
+        matrixRow({
+            harnessId: "command",
+            harnessKind: "generic",
+            displayName: "Command",
+            availability: "available",
+            capabilities: mergeCapabilities(adapterCapabilities(createCommandHarness({
+                command: options.commandSuccess ?? DEFAULT_COMMAND_SUCCESS,
+                cwd: options.repo
+            })), COMMAND_CAPABILITIES),
+            notes: ["Runs local shell commands through the command harness."]
+        }),
+        matrixRow({
+            harnessId: "mock",
+            harnessKind: "generic",
+            displayName: "Mock",
+            availability: "available",
+            capabilities: mergeCapabilities(adapterCapabilities(createMockHarness()), MOCK_CAPABILITIES),
+            notes: ["Pure synthetic fixture harness for CI."]
+        })
+    ];
+    const capabilities = [...new Set(rows.flatMap((row) => Object.keys(row.capabilities)))].sort();
+    return { capabilities, rows };
+}
+function currentGitSha(repo) {
+    try {
+        const sha = gitText(repo, ["rev-parse", "HEAD"]).trim();
+        return sha.length > 0 ? sha : ZERO_GIT_SHA;
+    }
+    catch {
+        return ZERO_GIT_SHA;
+    }
+}
+function smokeDescriptor(input) {
+    return {
+        id: input.id,
+        harness: input.harness,
+        models: [input.model],
+        runtime: { id: "local" },
+        judge: { id: "none" },
+        policy: {
+            id: `${input.id}_policy`,
+            allowedTools: input.allowedTools,
+            sideEffects: input.sideEffects,
+            timeoutMs: input.timeoutMs
+        },
+        prompt: input.prompt,
+        sourceRepo: input.repo,
+        baseGitSha: input.baseGitSha,
+        outputRoot: join(input.outputRoot, "runs", input.id)
+    };
+}
+function liveSmokePreflightFailureResult(input) {
+    const result = {
+        ...metadata("harness-run-result.v1", input.createdAt),
+        result_id: `ensemble_result_${input.taskId}`,
+        request_id: `ensemble_req_${input.taskId}`,
+        harness_kind: input.harnessKind,
+        status: "failed",
+        candidate_ids: [],
+        output_summary: `Explicit live smoke failed before launch: ${input.reason}`,
+        capabilities: input.capabilities,
+        started_at: input.createdAt,
+        finished_at: input.createdAt,
+        errors: [
+            {
+                kind: "capability_missing",
+                message: input.reason,
+                retryable: false
+            }
+        ],
+        metadata: {
+            dashboard_outcome: "failure",
+            harness_id: input.taskId,
+            live_smoke: true,
+            preflight: "credentials"
+        }
+    };
+    assertHarnessRunResultV1(result);
+    return result;
+}
+function failSkippedLiveSmokeResult(result, taskId) {
+    if (result.status !== "skipped")
+        return result;
+    const metadata = {
+        ...(result.metadata ?? {}),
+        dashboard_outcome: "failure",
+        explicit_live_smoke: true,
+        original_status: "skipped"
+    };
+    const promoted = {
+        ...result,
+        status: "failed",
+        output_summary: `Explicit live smoke ${taskId} failed because the adapter returned skipped. ` +
+            (result.output_summary ?? ""),
+        errors: [
+            ...(result.errors ?? []),
+            {
+                kind: "capability_missing",
+                message: "Explicit live smoke was requested but the adapter returned skipped.",
+                retryable: false
+            }
+        ],
+        metadata
+    };
+    assertHarnessRunResultV1(promoted);
+    return promoted;
+}
+function writeRunResult(outputRoot, taskId, result) {
+    const dir = join(outputRoot, "harness-run-results");
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${safeFileName(taskId)}.json`);
+    assertHarnessRunResultV1(result);
+    writeFileSync(path, JSON.stringify(result, null, 2) + "\n");
+    return path;
+}
+async function runSmokeTask(input) {
+    if (input.run.preflightFailureReason !== undefined) {
+        const result = liveSmokePreflightFailureResult({
+            createdAt: input.createdAt,
+            taskId: input.run.taskId,
+            harnessKind: input.run.harnessKind,
+            capabilities: mergeCapabilities(adapterCapabilities(input.run.harness), input.run.capabilities),
+            reason: input.run.preflightFailureReason
+        });
+        const resultPath = writeRunResult(input.outputRoot, input.run.taskId, result);
+        return {
+            taskId: input.run.taskId,
+            harnessId: input.run.harnessId,
+            purpose: input.run.purpose,
+            outcome: input.run.outcome,
+            result,
+            resultPath
+        };
+    }
+    const descriptor = smokeDescriptor({
+        id: input.run.taskId,
+        harness: input.run.harness,
+        model: input.run.model,
+        repo: input.repo,
+        baseGitSha: input.baseGitSha,
+        outputRoot: input.outputRoot,
+        sideEffects: input.run.sideEffects,
+        allowedTools: input.run.allowedTools,
+        timeoutMs: input.timeoutMs,
+        prompt: input.run.prompt ?? DEFAULT_PROMPT
+    });
+    const result = await runEnsemble(descriptor);
+    const harnessRunResult = input.run.purpose === "live"
+        ? failSkippedLiveSmokeResult(result.harnessRunResult, input.run.taskId)
+        : result.harnessRunResult;
+    const resultPath = writeRunResult(input.outputRoot, input.run.taskId, harnessRunResult);
+    return {
+        taskId: input.run.taskId,
+        harnessId: input.run.harnessId,
+        purpose: input.run.purpose,
+        outcome: input.run.outcome,
+        result: harnessRunResult,
+        resultPath
+    };
+}
+function genericSmokeRuns(options) {
+    return [
+        {
+            taskId: "mock-success",
+            harnessId: "mock",
+            harnessKind: "generic",
+            purpose: "contract",
+            outcome: "success",
+            harness: createMockHarness(),
+            model: { id: "mock", model: "synthetic-mock" },
+            sideEffects: "read_only",
+            allowedTools: ["read_file"],
+            capabilities: MOCK_CAPABILITIES
+        },
+        {
+            taskId: "command-success",
+            harnessId: "command",
+            harnessKind: "generic",
+            purpose: "contract",
+            outcome: "success",
+            harness: createCommandHarness({ command: options.commandSuccess }),
+            model: { id: "command", model: "local-shell" },
+            sideEffects: "tool_execution",
+            allowedTools: ["shell_command"],
+            capabilities: COMMAND_CAPABILITIES
+        },
+        {
+            taskId: "command-failure",
+            harnessId: "command",
+            harnessKind: "generic",
+            purpose: "contract",
+            outcome: "failure",
+            harness: createCommandHarness({ command: options.commandFailure }),
+            model: { id: "command", model: "local-shell" },
+            sideEffects: "tool_execution",
+            allowedTools: ["shell_command"],
+            capabilities: COMMAND_CAPABILITIES
+        }
+    ];
+}
+function credentialSkipSmokeRuns(tools) {
+    return tools.map((tool) => ({
+        taskId: tool.smoke.taskId,
+        harnessId: tool.id,
+        harnessKind: tool.harnessKind,
+        purpose: "credential-skip",
+        outcome: "skipped",
+        harness: tool.smoke.makeHarness(),
+        model: tool.smoke.model,
+        sideEffects: tool.smoke.sideEffects,
+        allowedTools: tool.smoke.allowedTools,
+        capabilities: tool.capabilities
+    }));
+}
+function liveSmokeRuns(options) {
+    const runs = [];
+    for (const tool of options.tools) {
+        const live = tool.liveSmoke;
+        if (live === undefined)
+            continue;
+        const harness = options.harnesses?.[tool.id] ?? live.makeHarness(options.env);
+        runs.push({
+            taskId: live.taskId,
+            harnessId: tool.id,
+            harnessKind: tool.harnessKind,
+            purpose: "live",
+            outcome: "success",
+            harness,
+            model: { id: tool.smoke.model.id, model: readEnv(options.env, live.modelEnvName) ?? live.defaultModel },
+            sideEffects: "read_only",
+            allowedTools: ["read_file"],
+            capabilities: tool.capabilities,
+            prompt: live.prompt,
+            preflightFailureReason: tool.credentialSkipReason(options.env)
+        });
+    }
+    return runs;
+}
+function capabilityCell(capabilities, capability) {
+    return capabilities[capability] ?? "unknown";
+}
+function renderCapabilityMatrix(matrix) {
+    const header = [
+        "Harness",
+        "Kind",
+        "Availability",
+        ...matrix.capabilities,
+        "Notes"
+    ];
+    const lines = [
+        "## Capability Matrix",
+        "",
+        `| ${header.map(escapeMarkdownCell).join(" | ")} |`,
+        `| ${header.map(() => "---").join(" | ")} |`
+    ];
+    for (const row of matrix.rows) {
+        const cells = [
+            row.displayName,
+            row.harnessKind,
+            row.availability,
+            ...matrix.capabilities.map((capability) => capabilityCell(row.capabilities, capability)),
+            row.notes.join(" ")
+        ];
+        lines.push(`| ${cells.map(escapeMarkdownCell).join(" | ")} |`);
+    }
+    return lines;
+}
+function relativePath(path, from) {
+    return path.startsWith(from) ? path.slice(from.length + 1) : path;
+}
+function safeArtifactRefs(artifacts) {
+    if (artifacts === undefined || artifacts.length === 0)
+        return [];
+    const refs = [];
+    let rawWithheld = 0;
+    for (const artifact of artifacts) {
+        if (artifact.redaction_status === "raw") {
+            rawWithheld++;
+            continue;
+        }
+        refs.push(`${artifact.kind}:${artifact.artifact_id}:${artifact.hash}`);
+        if (refs.length >= 5)
+            break;
+    }
+    if (rawWithheld > 0)
+        refs.push(`${rawWithheld} raw artifact ref(s) withheld`);
+    return refs;
+}
+function liveSmokeState(record) {
+    if (record === undefined)
+        return "live smoke not requested";
+    switch (record.result.status) {
+        case "succeeded":
+            return "live smoke passed";
+        case "failed":
+        case "canceled":
+        case "requires_action":
+        case "unsupported":
+        case "pending":
+        case "running":
+            return "live smoke failed";
+        case "skipped":
+            return "live smoke skipped";
+        default: {
+            const exhausted = record.result.status;
+            throw new Error(`unsupported live smoke status: ${String(exhausted)}`);
+        }
+    }
+}
+function createAdapterReadiness(input) {
+    return input.matrix.rows.map((row) => {
+        const liveRecord = input.records.find((record) => record.harnessId === row.harnessId && record.purpose === "live");
+        const credentialRecord = input.records.find((record) => record.harnessId === row.harnessId && record.purpose === "credential-skip");
+        const credentialState = input.credentialStateFor(row.harnessId);
+        const evidence = [
+            ...(credentialRecord !== undefined && credentialState.includes("missing")
+                ? [`credential skip: ${relativePath(credentialRecord.resultPath, input.outputRoot)}`]
+                : []),
+            ...(liveRecord !== undefined
+                ? [
+                    `live result: ${relativePath(liveRecord.resultPath, input.outputRoot)}`,
+                    `status=${liveRecord.result.status}`
+                ]
+                : [])
+        ];
+        return {
+            harnessId: row.harnessId,
+            displayName: row.displayName,
+            contractReadiness: "contract/mock ready",
+            credentialState,
+            liveSmoke: liveSmokeState(liveRecord),
+            evidence,
+            artifactRefs: liveRecord !== undefined ? safeArtifactRefs(liveRecord.result.artifacts) : []
+        };
+    });
+}
+function renderAdapterReadiness(readiness) {
+    const lines = [
+        "## Adapter Readiness",
+        "",
+        "| Adapter | Contract/Mock Readiness | Credentials | Live Smoke | Last Evidence | Safe Artifact Refs |",
+        "| --- | --- | --- | --- | --- | --- |"
+    ];
+    for (const row of readiness) {
+        const cells = [
+            row.displayName,
+            row.contractReadiness,
+            row.credentialState,
+            row.liveSmoke,
+            row.evidence.length > 0 ? row.evidence.join("; ") : "-",
+            row.artifactRefs.length > 0 ? row.artifactRefs.join("; ") : "-"
+        ];
+        lines.push(`| ${cells.map(escapeMarkdownCell).join(" | ")} |`);
+    }
+    return lines;
+}
+function renderSmokeRecords(records, outputRoot, displayNameFor) {
+    const lines = [
+        "## Smoke Records",
+        "",
+        "| Task | Harness | Purpose | Expected | Result Status | Harness Kind | Result Record | Summary |",
+        "| --- | --- | --- | --- | --- | --- | --- | --- |"
+    ];
+    for (const record of records) {
+        const cells = [
+            record.taskId,
+            displayNameFor(record.harnessId),
+            record.purpose,
+            record.outcome,
+            record.result.status,
+            record.result.harness_kind,
+            relativePath(record.resultPath, outputRoot),
+            record.result.output_summary ?? ""
+        ];
+        lines.push(`| ${cells.map(escapeMarkdownCell).join(" | ")} |`);
+    }
+    return lines;
+}
+function renderDashboard(input) {
+    const counts = new Map();
+    for (const record of input.records) {
+        counts.set(record.result.status, (counts.get(record.result.status) ?? 0) + 1);
+    }
+    const countText = [...counts.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([status, count]) => `${status}:${count}`)
+        .join(", ");
+    return [
+        "# HandoffKit Harness Smoke Dashboard",
+        "",
+        `Generated: ${input.createdAt}`,
+        `Output root: ${input.outputRoot}`,
+        `Run-result status counts: ${countText}`,
+        "",
+        ...renderCapabilityMatrix(input.matrix),
+        "",
+        ...renderAdapterReadiness(input.readiness),
+        "",
+        ...renderSmokeRecords(input.records, input.outputRoot, input.displayNameFor),
+        ""
+    ].join("\n");
+}
+export async function runHarnessSmokeDashboard(options = {}) {
+    const repo = resolve(options.repo ?? process.cwd());
+    const outputRoot = resolve(options.outputRoot ?? join(repo, DEFAULT_OUTPUT_DIR));
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const createdAt = options.createdAt ?? new Date().toISOString();
+    const commandSuccess = options.commandSuccess ?? DEFAULT_COMMAND_SUCCESS;
+    const commandFailure = options.commandFailure ?? DEFAULT_COMMAND_FAILURE;
+    const env = options.env ?? process.env;
+    const tools = dashboardTools(options);
+    mkdirSync(outputRoot, { recursive: true });
+    const matrix = createHarnessCapabilityMatrix({
+        ...options,
+        repo,
+        commandSuccess,
+        commandFailure,
+        env
+    });
+    const toolsById = new Map(tools.map((tool) => [tool.id, tool]));
+    const displayNameFor = (harnessId) => toolsById.get(harnessId)?.displayName ??
+        matrix.rows.find((row) => row.harnessId === harnessId)?.displayName ??
+        harnessId;
+    const credentialStateFor = (harnessId) => {
+        const tool = toolsById.get(harnessId);
+        if (tool === undefined)
+            return "not required";
+        return tool.credentialSkipReason(env) === undefined
+            ? "credentials available"
+            : "credentials missing/skipped";
+    };
+    const baseGitSha = currentGitSha(repo);
+    const records = [];
+    const runs = [
+        ...genericSmokeRuns({ commandSuccess, commandFailure }),
+        ...credentialSkipSmokeRuns(tools),
+        ...liveSmokeRuns({
+            env,
+            tools: requestedLiveSmokeTools({ env, tools, liveSmoke: options.liveSmoke }),
+            harnesses: options.liveSmokeHarnesses
+        })
+    ];
+    for (const run of runs) {
+        records.push(await runSmokeTask({
+            run,
+            repo,
+            baseGitSha,
+            outputRoot,
+            timeoutMs,
+            createdAt
+        }));
+    }
+    const readiness = createAdapterReadiness({
+        matrix,
+        records,
+        credentialStateFor,
+        outputRoot
+    });
+    const dashboardPath = join(outputRoot, "dashboard.md");
+    writeFileSync(dashboardPath, renderDashboard({
+        matrix,
+        readiness,
+        records,
+        createdAt,
+        outputRoot,
+        displayNameFor
+    }));
+    return {
+        outputRoot,
+        dashboardPath,
+        matrix,
+        records,
+        readiness
+    };
+}
+export const harnessDashboard = {
+    capabilities: createHarnessCapabilityMatrix,
+    run: runHarnessSmokeDashboard
+};

package/dist/fusion/env.d.ts

@@ -0,0 +1,108 @@
+/** A launchable tool id from the registry, or the `serve` pseudo-tool. */
+export type FusionTool = string;
+export type PanelProvider = "mlx" | "openai" | "anthropic" | "google" | "openai-compatible";
+/**
+ * One panel model. `mlx` models run locally via the in-repo provisioner; cloud
+ * providers (openai/anthropic/google/openai-compatible) are fronted as
+ * OpenAI-compatible endpoints by FusionKit's `serve-endpoint` command, run via
+ * `uvx fusionkit` (no checkout required).
+ */
+export type PanelModelSpec = {
+    id: string;
+    model: string;
+    provider?: PanelProvider;
+    baseUrl?: string;
+    keyEnv?: string;
+};
+export type RunFusionOptions = {
+    models?: PanelModelSpec[];
+    endpoints?: Record<string, string>;
+    fusionkitDir?: string;
+    repo?: string;
+    judgeModel?: string;
+    synthesisUrl?: string;
+    authToken?: string;
+    port?: number;
+    timeoutMs?: number;
+    /** Use the local MLX panel trio (Apple Silicon) instead of the cloud panel. */
+    local?: boolean;
+    /** Boot the local scope dashboard and stream trace events into it. */
+    observe?: boolean;
+    /** Skip the interactive cost/scope confirmation for the cloud panel. */
+    yes?: boolean;
+    /** Route services through portless (stable named URLs + singletons). Default on. */
+    portless?: boolean;
+    log?: (line: string) => void;
+};
+/**
+ * Structured boot progress. When a reporter is supplied the stack emits these
+ * events instead of the plain `fusion: ...` log lines, so a live TUI (or any
+ * other consumer) can render per-stage status. Without one, callers keep getting
+ * the existing line logs.
+ */
+export type StackEvent = {
+    kind: "server.start";
+    id: string;
+    label: string;
+} | {
+    kind: "server.ready";
+    id: string;
+    detail: string;
+} | {
+    kind: "server.fail";
+    id: string;
+    detail: string;
+} | {
+    kind: "synth.start";
+} | {
+    kind: "synth.ready";
+    detail: string;
+} | {
+    kind: "gateway.start";
+} | {
+    kind: "gateway.ready";
+    detail: string;
+} | {
+    kind: "dashboard.start";
+} | {
+    kind: "dashboard.ready";
+    detail: string;
+} | {
+    kind: "dashboard.fail";
+    detail: string;
+};
+export type StackReporter = (event: StackEvent) => void;
+/**
+ * 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 declare const FUSIONKIT_PYPI_VERSION = "0.2.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 declare const DEFAULT_CLOUD_PANEL: readonly PanelModelSpec[];
+/** The locally cached MLX trio (Apple Silicon only) used behind `--local`. */
+export declare const DEFAULT_TRIO: readonly PanelModelSpec[];
+/**
+ * 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 declare function fusionkitPyCommand(fusionkitDir?: string): {
+    command: string;
+    prefix: string[];
+    cwd?: string;
+};
+/**
+ * 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 declare function loadEnvFileInto(path: string, env: Record<string, string | undefined>): void;
+/** Default env var holding the API key for each cloud provider. */
+export declare function defaultKeyEnv(provider: PanelProvider): string | undefined;
+/** The git repository root containing `dir`, or undefined if it is not in a repo. */
+export declare function gitToplevel(dir: string): string | undefined;