@hue-run/sdk 0.3.0 → 0.3.1

package/dist/setup/cli.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+import { realpath } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { FileSetupCheckpointAdapter, setupRunId } from "./checkpoint.js";
+import { detectSetupProject } from "./detect.js";
+import { renderHumanEvent, renderJsonlEvent, renderPlainEvent, selectSetupOutputMode, } from "./render.js";
+import { runSetup } from "./runner.js";
+import { SETUP_EVENT_CONTRACT_VERSION } from "./types.js";
+const commands = new Set(["setup", "resume", "status", "claim"]);
+function writeEvent(event, mode, width) {
+    const line = mode === "jsonl"
+        ? renderJsonlEvent(event)
+        : mode === "plain"
+            ? renderPlainEvent(event, width)
+            : renderHumanEvent(event, width, true);
+    if (line)
+        process.stdout.write(`${line}\n`);
+}
+async function main() {
+    const agentRequested = process.argv.slice(2).includes("--agent");
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: process.argv.slice(2),
+            allowPositionals: true,
+            strict: true,
+            options: {
+                agent: { type: "boolean", default: false },
+                format: { type: "string" },
+                project: { type: "string" },
+                help: { type: "boolean", short: "h", default: false },
+            },
+        });
+    }
+    catch {
+        if (!agentRequested) {
+            process.stderr.write("Usage: hue <setup|resume|status|claim> [--agent|--format plain|jsonl] [--project PATH]\n");
+            return 2;
+        }
+        const event = {
+            contractVersion: SETUP_EVENT_CONTRACT_VERSION,
+            event: "run.failed",
+            runId: "setup_invalid_command",
+            sequence: 1,
+            timestamp: new Date().toISOString(),
+            code: "invalid_arguments",
+            message: "Invalid command arguments.",
+            resumable: false,
+        };
+        process.stdout.write(`${renderJsonlEvent(event)}\n`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        if (parsed.values.agent) {
+            const event = {
+                contractVersion: SETUP_EVENT_CONTRACT_VERSION,
+                event: "run.failed",
+                runId: "setup_help",
+                sequence: 1,
+                timestamp: new Date().toISOString(),
+                code: "help_requested",
+                message: "Use hue --help without --agent to read interactive help.",
+                resumable: false,
+            };
+            process.stdout.write(`${renderJsonlEvent(event)}\n`);
+            return 2;
+        }
+        process.stdout.write("Usage: hue <setup|resume|status|claim> [--agent|--format plain|jsonl] [--project PATH]\n");
+        return 0;
+    }
+    const command = parsed.positionals[0];
+    const format = parsed.values.format;
+    const validFormat = format === undefined || format === "human" || format === "plain" || format === "jsonl";
+    if (!command ||
+        !commands.has(command) ||
+        parsed.positionals.length !== 1 ||
+        !validFormat ||
+        (parsed.values.agent && format !== undefined && format !== "jsonl")) {
+        if (parsed.values.agent) {
+            const event = {
+                contractVersion: SETUP_EVENT_CONTRACT_VERSION,
+                event: "run.failed",
+                runId: "setup_invalid_command",
+                sequence: 1,
+                timestamp: new Date().toISOString(),
+                code: "invalid_arguments",
+                message: "Invalid command arguments.",
+                resumable: false,
+            };
+            process.stdout.write(`${renderJsonlEvent(event)}\n`);
+        }
+        else
+            process.stderr.write("Usage: hue <setup|resume|status|claim> [--agent|--format plain|jsonl] [--project PATH]\n");
+        return 2;
+    }
+    const mode = selectSetupOutputMode({
+        agent: parsed.values.agent,
+        explicit: format,
+        isTTY: process.stdout.isTTY,
+        env: process.env,
+    });
+    const width = Math.max(24, process.stdout.columns ?? 80);
+    const controller = new AbortController();
+    let terminalEmitted = false;
+    const interrupt = () => controller.abort();
+    process.once("SIGINT", interrupt);
+    process.once("SIGTERM", interrupt);
+    try {
+        const root = await realpath(parsed.values.project ?? process.cwd());
+        await runSetup({
+            command: command,
+            mode,
+            runId: setupRunId(root),
+            projectRoot: root,
+            project: { detect: detectSetupProject },
+            checkpoints: new FileSetupCheckpointAdapter(),
+            signal: controller.signal,
+            emit: (event) => {
+                if (event.event === "run.completed" || event.event === "run.failed")
+                    terminalEmitted = true;
+                writeEvent(event, mode, width);
+            },
+        });
+        return 0;
+    }
+    catch {
+        if (mode === "jsonl" && !terminalEmitted) {
+            const event = {
+                contractVersion: SETUP_EVENT_CONTRACT_VERSION,
+                event: "run.failed",
+                runId: "setup_preflight_failed",
+                sequence: 1,
+                timestamp: new Date().toISOString(),
+                code: "setup_failed",
+                message: "Setup session could not start. Check the project path and local state directory.",
+                resumable: false,
+            };
+            process.stdout.write(`${renderJsonlEvent(event)}\n`);
+        }
+        else if (mode !== "jsonl" && !terminalEmitted) {
+            process.stderr.write("Setup session could not start. Check the project path and local state directory.\n");
+        }
+        return controller.signal.aborted ? 130 : 1;
+    }
+    finally {
+        process.removeListener("SIGINT", interrupt);
+        process.removeListener("SIGTERM", interrupt);
+    }
+}
+process.exitCode = await main();

package/dist/setup/detect.d.ts

@@ -0,0 +1,3 @@
+import type { SetupProjectDetection } from "./types.js";
+/** Reads bounded manifest and lockfile metadata without importing or executing project code. */
+export declare function detectSetupProject(projectRoot: string): Promise<SetupProjectDetection>;

package/dist/setup/detect.js

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import { join } from "node:path";
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+async function readManifest(root, name) {
+    let handle;
+    try {
+        handle = await open(join(root, name), constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            return undefined;
+        if (info.size > MAX_MANIFEST_BYTES)
+            return "";
+        return await handle.readFile("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+function hasAny(source, names) {
+    return names.some((name) => {
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+        return new RegExp(`(?:^|[^A-Za-z0-9_.-])${escaped}(?:$|[^A-Za-z0-9_.-])`, "iu").test(source);
+    });
+}
+/** Reads bounded manifest and lockfile metadata without importing or executing project code. */
+export async function detectSetupProject(projectRoot) {
+    const root = await realpath(projectRoot);
+    const names = [
+        "package.json",
+        "tsconfig.json",
+        "bun.lock",
+        "bun.lockb",
+        "package-lock.json",
+        "npm-shrinkwrap.json",
+        "pnpm-lock.yaml",
+        "yarn.lock",
+        "pyproject.toml",
+        "uv.lock",
+        "poetry.lock",
+        "requirements.txt",
+    ];
+    const contents = new Map();
+    await Promise.all(names.map(async (name) => {
+        const content = await readManifest(root, name);
+        if (content !== undefined)
+            contents.set(name, content);
+    }));
+    const node = contents.get("package.json") ?? "";
+    let nodeDependencies = new Set();
+    let declaredPackageManager;
+    if (node) {
+        try {
+            const manifest = JSON.parse(node);
+            if (typeof manifest.packageManager === "string")
+                declaredPackageManager = manifest.packageManager.split("@", 1)[0];
+            for (const section of [
+                "dependencies",
+                "devDependencies",
+                "peerDependencies",
+                "optionalDependencies",
+            ]) {
+                const dependencies = manifest[section];
+                if (dependencies && typeof dependencies === "object" && !Array.isArray(dependencies))
+                    nodeDependencies = new Set([...nodeDependencies, ...Object.keys(dependencies)]);
+            }
+        }
+        catch {
+            // Malformed package metadata is reported only through absent detections; setup never executes it.
+        }
+    }
+    const python = [
+        contents.get("pyproject.toml"),
+        contents.get("requirements.txt"),
+        contents.get("uv.lock"),
+        contents.get("poetry.lock"),
+    ]
+        .filter((value) => value !== undefined)
+        .join("\n");
+    const languages = [];
+    if (contents.has("tsconfig.json") || nodeDependencies.has("typescript"))
+        languages.push("typescript");
+    if (python || contents.has("pyproject.toml"))
+        languages.push("python");
+    const packageManagers = [];
+    if (contents.has("bun.lock") || contents.has("bun.lockb") || declaredPackageManager === "bun")
+        packageManagers.push("bun");
+    if (contents.has("package-lock.json") ||
+        contents.has("npm-shrinkwrap.json") ||
+        declaredPackageManager === "npm")
+        packageManagers.push("npm");
+    if (contents.has("pnpm-lock.yaml") || declaredPackageManager === "pnpm")
+        packageManagers.push("pnpm");
+    if (contents.has("yarn.lock") || declaredPackageManager === "yarn")
+        packageManagers.push("yarn");
+    if (contents.has("uv.lock") || /\[tool\.uv(?:\.|\])/u.test(python))
+        packageManagers.push("uv");
+    if (contents.has("poetry.lock") || /\[tool\.poetry\]/u.test(python))
+        packageManagers.push("poetry");
+    if (contents.has("requirements.txt") && !packageManagers.includes("uv"))
+        packageManagers.push("pip");
+    const frameworks = [];
+    if (nodeDependencies.has("next"))
+        frameworks.push("nextjs");
+    if (nodeDependencies.has("@nestjs/core"))
+        frameworks.push("nestjs");
+    if (nodeDependencies.has("express"))
+        frameworks.push("express");
+    if (hasAny(python, ["fastapi"]))
+        frameworks.push("fastapi");
+    if (hasAny(python, ["django"]))
+        frameworks.push("django");
+    if (hasAny(python, ["flask"]))
+        frameworks.push("flask");
+    if (nodeDependencies.has("ai") ||
+        [...nodeDependencies].some((name) => name.startsWith("@ai-sdk/")))
+        frameworks.push("vercel-ai-sdk");
+    const hueTs = nodeDependencies.has("@hue-run/sdk") || nodeDependencies.has("hue-run");
+    const huePy = hasAny(python, ["hue-run", "hue_sdk"]);
+    const otelTs = nodeDependencies.has("@vercel/otel") ||
+        [...nodeDependencies].some((name) => name.startsWith("@opentelemetry/"));
+    const otelPy = /(?:^|[^A-Za-z0-9_.-])opentelemetry[-_]/iu.test(python);
+    const presence = (ts, py) => ts && py ? "multiple" : ts ? "typescript" : py ? "python" : "absent";
+    const facts = {
+        languages,
+        packageManagers,
+        frameworks,
+        hue: presence(hueTs, huePy),
+        openTelemetry: presence(otelTs, otelPy),
+    };
+    return {
+        root,
+        fingerprint: createHash("sha256")
+            .update(`${root}\0${JSON.stringify(facts)}`)
+            .digest("hex"),
+        ...facts,
+    };
+}

package/dist/setup/machine.d.ts

@@ -0,0 +1,109 @@
+import type { SetupPlan, SetupProjectDetection } from "./types.js";
+/** @inline */
+interface SetupStateBase {
+    /** Checkpoint format version. */
+    format: 1;
+    /** Current state-machine phase. */
+    phase: "created" | "detecting" | "local-ready";
+    /** Stable installer-session identifier, unrelated to Hue Runs. */
+    runId: string;
+    /** Canonical project root. */
+    projectRoot: string;
+}
+/** @inline */
+interface CreatedSetupState extends SetupStateBase {
+    /** Initial phase before any adapter work. */
+    phase: "created";
+}
+/** @inline */
+interface DetectingSetupState extends SetupStateBase {
+    /** Safely resumable static-detection phase. */
+    phase: "detecting";
+}
+/** @inline */
+interface LocalReadySetupState extends SetupStateBase {
+    /** Local inspection is complete; a later integration may configure telemetry. */
+    phase: "local-ready";
+    /** Saved bounded project facts. */
+    project: SetupProjectDetection;
+    /** Saved deterministic plan. */
+    plan: SetupPlan;
+}
+/** Persisted phase of the pure setup state machine. */
+export type SetupMachineState = CreatedSetupState | DetectingSetupState | LocalReadySetupState;
+/** @inline */
+interface StartSetupInput {
+    /** Requests the next safe local effect. */
+    type: "start";
+}
+/** @inline */
+interface ProjectDetectedSetupInput {
+    /** Supplies a completed project detection. */
+    type: "project.detected";
+    /** Static detection supplied by the project adapter. */
+    project: SetupProjectDetection;
+}
+/** Input returned by an injected setup adapter. */
+export type SetupMachineInput = StartSetupInput | ProjectDetectedSetupInput;
+/** Side effect requested by the pure state machine. */
+export interface SetupEffect {
+    /** Adapter operation requested by the machine. */
+    type: "detect-project";
+    /** Canonical root to inspect. */
+    root: string;
+}
+/** @inline */
+interface StartStepTransitionEvent {
+    /** Transition-event discriminator. */
+    event: "step.started";
+    /** Static detection step. */
+    step: "detect-project";
+}
+/** @inline */
+interface ProjectDetectedTransitionEvent {
+    /** Transition-event discriminator. */
+    event: "project.detected";
+    /** Completed detection. */
+    project: SetupProjectDetection;
+}
+/** @inline */
+interface CompleteStepTransitionEvent {
+    /** Transition-event discriminator. */
+    event: "step.completed";
+    /** Static detection step. */
+    step: "detect-project";
+    /** Detection never changes project files. */
+    outcome: "unchanged";
+}
+/** @inline */
+interface PlanReadyTransitionEvent {
+    /** Transition-event discriminator. */
+    event: "plan.ready";
+    /** Deterministic plan. */
+    plan: SetupPlan;
+}
+/** @inline */
+interface ConfigureTelemetryRequiredTransitionEvent {
+    /** Transition-event discriminator. */
+    event: "action.required";
+    /** Project action needed next. */
+    action: "configure";
+    /** Secret-free explanation. */
+    message: string;
+}
+/** @inline */
+type SetupTransitionEvent = StartStepTransitionEvent | ProjectDetectedTransitionEvent | CompleteStepTransitionEvent | PlanReadyTransitionEvent | ConfigureTelemetryRequiredTransitionEvent;
+/** Pure transition result. Events are templates completed by the runner. */
+export interface SetupTransition {
+    /** State to checkpoint before executing another effect. */
+    state: SetupMachineState;
+    /** Event templates for the runner to sequence and timestamp. */
+    events: SetupTransitionEvent[];
+    /** Optional side effect to execute after saving the state. */
+    effect?: SetupEffect;
+}
+/** Creates deterministic initial setup state without reading the filesystem. */
+export declare function createInitialSetupState(runId: string, projectRoot: string): SetupMachineState;
+/** Advances the setup state without I/O, clocks, randomness, or environment access. */
+export declare function transitionSetup(state: SetupMachineState, input: SetupMachineInput): SetupTransition;
+export {};

package/dist/setup/machine.js

@@ -0,0 +1,43 @@
+/** Creates deterministic initial setup state without reading the filesystem. */
+export function createInitialSetupState(runId, projectRoot) {
+    return { format: 1, phase: "created", runId, projectRoot };
+}
+/** Advances the setup state without I/O, clocks, randomness, or environment access. */
+export function transitionSetup(state, input) {
+    if ((state.phase === "created" || state.phase === "detecting") && input.type === "start") {
+        const next = { ...state, phase: "detecting" };
+        return {
+            state: next,
+            events: [{ event: "step.started", step: "detect-project" }],
+            effect: { type: "detect-project", root: state.projectRoot },
+        };
+    }
+    if (state.phase === "detecting" && input.type === "project.detected") {
+        const plan = {
+            steps: ["detect-project", "configure-telemetry", "verify-receipt", "claim-project"],
+            mutatesProject: false,
+            backendRequired: true,
+        };
+        return {
+            state: {
+                format: 1,
+                phase: "local-ready",
+                runId: state.runId,
+                projectRoot: state.projectRoot,
+                project: input.project,
+                plan,
+            },
+            events: [
+                { event: "project.detected", project: input.project },
+                { event: "step.completed", step: "detect-project", outcome: "unchanged" },
+                { event: "plan.ready", plan },
+                {
+                    event: "action.required",
+                    action: "configure",
+                    message: "Local inspection is complete. Telemetry configuration is not available in this build; no project files were changed.",
+                },
+            ],
+        };
+    }
+    throw new Error(`Invalid setup transition from ${state.phase} using ${input.type}`);
+}

package/dist/setup/render.d.ts

@@ -0,0 +1,16 @@
+import type { SetupEvent } from "./types.js";
+/** Supported setup transcript formats. */
+export type SetupOutputMode = "human" | "plain" | "jsonl";
+/** Renders one newline-free JSON object for JSONL output. */
+export declare function renderJsonlEvent(event: SetupEvent): string;
+/** Renders one ANSI-free append-only transcript entry. */
+export declare function renderPlainEvent(event: SetupEvent, width?: number): string;
+/** Renders one lightweight append-only terminal entry; it never moves the cursor or clears the screen. */
+export declare function renderHumanEvent(event: SetupEvent, width?: number, color?: boolean): string;
+/** Chooses a safe default: ANSI only on an ordinary interactive terminal. */
+export declare function selectSetupOutputMode(input: {
+    agent?: boolean;
+    explicit?: SetupOutputMode;
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): SetupOutputMode;

package/dist/setup/render.js

@@ -0,0 +1,111 @@
+const ansi = {
+    cyan: "\u001b[36m",
+    green: "\u001b[32m",
+    yellow: "\u001b[33m",
+    red: "\u001b[31m",
+    dim: "\u001b[2m",
+    reset: "\u001b[0m",
+};
+function wrap(text, width, prefix) {
+    const available = Math.max(20, width - prefix.length);
+    const words = text.split(/\s+/u);
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (line && line.length + word.length + 1 > available) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines.map((value) => `${prefix}${value}`).join("\n");
+}
+function summary(event) {
+    switch (event.event) {
+        case "run.started":
+            return `Hue setup session: ${event.command}${event.resumed ? " (resuming)" : ""}`;
+        case "project.detected": {
+            const languages = event.project.languages.length
+                ? event.project.languages.join(" + ")
+                : "unknown language";
+            const managers = event.project.packageManagers.length
+                ? ` via ${event.project.packageManagers.join(" + ")}`
+                : "";
+            return `Detected ${languages}${managers}; Hue ${event.project.hue}, OpenTelemetry ${event.project.openTelemetry}.`;
+        }
+        case "plan.ready":
+            return `Plan ready: ${event.plan.steps.length} bounded steps; project mutation is ${event.plan.mutatesProject ? "enabled" : "disabled"}.`;
+        case "step.started":
+            return `Starting ${event.step}.`;
+        case "step.completed":
+            return `Completed ${event.step} (${event.outcome}).`;
+        case "file.changed":
+            return `${event.change === "created" ? "Created" : "Updated"} ${event.path}.`;
+        case "diagnostic":
+            return `${event.code}: ${event.message}`;
+        case "action.required":
+            return `${event.message}${event.command ? ` Next: ${event.command}.` : ""}`;
+        case "trial.created":
+            return `Anonymous trial ${event.trialId} created; expires ${event.expiresAt}.`;
+        case "receipt.verified":
+            return `Instrumentation receipt ${event.receiptId} verified for trace ${event.traceId}.`;
+        case "claim.required":
+            return `Claim ${event.claimId} is ready: ${event.url}`;
+        case "claim.completed":
+            return `Claim ${event.claimId} completed.`;
+        case "run.completed":
+            return `Setup session ${event.outcome.replace("_", " ")}; checkpoint ${event.checkpointed ? "saved" : "not created"}.`;
+        case "run.failed":
+            return `${event.code}: ${event.message}`;
+    }
+}
+/** Renders one newline-free JSON object for JSONL output. */
+export function renderJsonlEvent(event) {
+    return JSON.stringify(event);
+}
+/** Renders one ANSI-free append-only transcript entry. */
+export function renderPlainEvent(event, width = 80) {
+    const text = summary(event);
+    if (!text)
+        return "";
+    const marker = event.event === "run.failed"
+        ? "error"
+        : event.event === "action.required"
+            ? "action"
+            : event.event;
+    return wrap(text, width, `[${marker}] `);
+}
+/** Renders one lightweight append-only terminal entry; it never moves the cursor or clears the screen. */
+export function renderHumanEvent(event, width = 80, color = true) {
+    const text = summary(event);
+    if (!text)
+        return "";
+    const [symbol, tone] = event.event === "run.failed"
+        ? ["×", ansi.red]
+        : event.event === "action.required"
+            ? ["◆", ansi.yellow]
+            : event.event === "run.completed"
+                ? ["└", ansi.green]
+                : event.event === "step.started"
+                    ? ["◇", ansi.cyan]
+                    : event.event === "diagnostic"
+                        ? ["│", ansi.dim]
+                        : ["│", ansi.green];
+    const prefix = `${symbol} `;
+    const rendered = wrap(text, width, prefix);
+    return color ? `${tone}${rendered}${ansi.reset}` : rendered;
+}
+/** Chooses a safe default: ANSI only on an ordinary interactive terminal. */
+export function selectSetupOutputMode(input) {
+    if (input.agent)
+        return "jsonl";
+    if (input.explicit === "jsonl" || input.explicit === "plain")
+        return input.explicit;
+    const env = input.env ?? process.env;
+    if (!input.isTTY || env.NO_COLOR !== undefined || env.TERM === "dumb" || env.CI !== undefined)
+        return "plain";
+    return "human";
+}

package/dist/setup/runner.d.ts

@@ -0,0 +1,101 @@
+import type { SetupMachineState } from "./machine.js";
+import { type SetupEvent, type SetupProjectDetection } from "./types.js";
+/** Non-secret setup-trial identity returned by a future account-attachment adapter. */
+export interface SetupBackendTrial {
+    /** Non-secret trial identifier. */
+    trialId: string;
+    /** ISO-8601 trial expiration. */
+    expiresAt: string;
+}
+/** Instrumentation-only receipt evidence returned by a future backend adapter. */
+export interface SetupBackendReceipt {
+    /** Non-secret receipt identifier. */
+    receiptId: string;
+    /** Verified lowercase trace identifier; it does not establish content or Scenario suitability. */
+    traceId: string;
+}
+/** @inline */
+interface SetupBackendClaimRequired {
+    /** Claim is ready for a person. */
+    status: "required";
+    /** Non-secret claim identifier. */
+    claimId: string;
+    /** User-facing URL, which must never be checkpointed. */
+    url: string;
+}
+/** @inline */
+interface SetupBackendClaimCompleted {
+    /** Claim has been confirmed by the backend. */
+    status: "completed";
+    /** Non-secret claim identifier. */
+    claimId: string;
+}
+/** Claim state returned by a future backend adapter. Claim URLs are never checkpointed. */
+export type SetupBackendClaim = SetupBackendClaimRequired | SetupBackendClaimCompleted;
+/** Installer-only network boundary for account attachment. It never creates a Scenario, worker, evaluation, or Hue Run. */
+export interface SetupBackendAdapter {
+    /** Creates or idempotently recovers an anonymous trial hard-pinned to `trial_metadata_v1`. */
+    createTrial(input: {
+        runId: string;
+        projectFingerprint: string;
+        idempotencyKey: string;
+    }, signal?: AbortSignal): Promise<SetupBackendTrial>;
+    /**
+     * Returns instrumentation-only receipt evidence, or `undefined` while pending.
+     * A receipt never authorizes content capture or Scenario publication.
+     */
+    verifyReceipt(input: {
+        trialId: string;
+        idempotencyKey: string;
+    }, signal?: AbortSignal): Promise<SetupBackendReceipt | undefined>;
+    /** Reads account-claim state after receipt verification without opening the claim URL. */
+    getClaim(input: {
+        trialId: string;
+        idempotencyKey: string;
+    }, signal?: AbortSignal): Promise<SetupBackendClaim>;
+}
+/** Static project-inspection boundary. */
+export interface SetupProjectAdapter {
+    /** Inspects bounded metadata without executing project code. */
+    detect(root: string, signal?: AbortSignal): Promise<SetupProjectDetection>;
+}
+/** Secret-free durable state boundary. */
+export interface SetupCheckpointAdapter {
+    /** Loads and validates state for this exact project identity. */
+    load(runId: string, projectRoot: string): Promise<SetupMachineState | undefined>;
+    /** Durably saves secret-free state before the next effect. */
+    save(state: SetupMachineState): Promise<void>;
+}
+/** Options for one deterministic setup invocation. */
+export interface SetupRunOptions {
+    /** CLI operation being orchestrated. */
+    command: "setup" | "resume" | "status" | "claim";
+    /** Renderer mode recorded in `run.started`. */
+    mode: "human" | "plain" | "jsonl";
+    /** Stable installer-session identifier, unrelated to Hue Runs. */
+    runId: string;
+    /** Canonical project root. */
+    projectRoot: string;
+    /** Injected static-inspection adapter. */
+    project: SetupProjectAdapter;
+    /** Injected secret-free checkpoint adapter. */
+    checkpoints: SetupCheckpointAdapter;
+    /** Reserved injection point for the follow-up integration; intentionally unused by this slice. */
+    backend?: SetupBackendAdapter;
+    /** Receives each ordered event exactly once. */
+    emit(event: SetupEvent): void | Promise<void>;
+    /** Injectable clock for deterministic tests. */
+    now?: () => Date;
+    /** Optional cancellation signal. */
+    signal?: AbortSignal;
+}
+/** Result of one setup invocation. */
+export interface SetupRunResult {
+    /** Non-fabricated local outcome. */
+    outcome: "ready" | "action_required" | "unchanged";
+    /** Last validated state, when one exists. */
+    state?: SetupMachineState;
+}
+/** Runs one installer setup-session command and emits one terminal event; it never launches a Hue Run. */
+export declare function runSetup(options: SetupRunOptions): Promise<SetupRunResult>;
+export {};