@hue-run/sdk 0.3.0 → 0.3.1

package/dist/setup/runner.js

@@ -0,0 +1,117 @@
+import { createInitialSetupState, transitionSetup } from "./machine.js";
+import { SETUP_EVENT_CONTRACT_VERSION, } from "./types.js";
+/** Runs one installer setup-session command and emits one terminal event; it never launches a Hue Run. */
+export async function runSetup(options) {
+    const now = options.now ?? (() => new Date());
+    let sequence = 0;
+    let terminal = false;
+    const emit = async (body) => {
+        const event = {
+            contractVersion: SETUP_EVENT_CONTRACT_VERSION,
+            runId: options.runId,
+            sequence: ++sequence,
+            timestamp: now().toISOString(),
+            ...body,
+        };
+        if (event.event === "run.completed" || event.event === "run.failed") {
+            if (terminal)
+                throw new Error("Setup runner attempted to emit more than one terminal event");
+            terminal = true;
+        }
+        else if (terminal)
+            throw new Error("Setup runner emitted an event after its terminal event");
+        await options.emit(event);
+    };
+    let state;
+    try {
+        state = await options.checkpoints.load(options.runId, options.projectRoot);
+        await emit({
+            event: "run.started",
+            command: options.command,
+            mode: options.mode,
+            resumed: state !== undefined,
+        });
+        if (options.signal?.aborted)
+            throw new Error("Setup interrupted");
+        if (options.command === "status") {
+            await emit({
+                event: "diagnostic",
+                level: "info",
+                code: state ? `checkpoint.${state.phase}` : "checkpoint.absent",
+                message: state
+                    ? `Checkpoint phase: ${state.phase}.`
+                    : "No setup checkpoint exists for this project.",
+            });
+            await emit({
+                event: "run.completed",
+                outcome: "unchanged",
+                checkpointed: state !== undefined,
+            });
+            return { outcome: "unchanged", state };
+        }
+        if (options.command === "claim") {
+            await emit({
+                event: "action.required",
+                action: "claim-project",
+                message: "Project claim is not available in this build; no backend request was made. A future adapter must require a verified anonymous telemetry receipt first.",
+            });
+            await emit({
+                event: "run.completed",
+                outcome: "action_required",
+                checkpointed: state !== undefined,
+            });
+            return { outcome: "action_required", state };
+        }
+        if (!state) {
+            if (options.command === "resume")
+                throw new Error("No setup checkpoint exists for this project");
+            state = createInitialSetupState(options.runId, options.projectRoot);
+            await options.checkpoints.save(state);
+        }
+        if (state.phase === "local-ready") {
+            await emit({ event: "project.detected", project: state.project });
+            await emit({ event: "plan.ready", plan: state.plan });
+            await emit({
+                event: "action.required",
+                action: "configure",
+                message: "Local inspection is complete. Telemetry configuration is not available in this build; no project files were changed.",
+            });
+            await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+            return { outcome: "action_required", state };
+        }
+        const first = transitionSetup(state, { type: "start" });
+        state = first.state;
+        await options.checkpoints.save(state);
+        for (const event of first.events)
+            await emit(event);
+        if (options.signal?.aborted)
+            throw new Error("Setup interrupted");
+        const project = await options.project.detect(first.effect.root, options.signal);
+        if (options.signal?.aborted)
+            throw new Error("Setup interrupted");
+        const second = transitionSetup(state, { type: "project.detected", project });
+        state = second.state;
+        await options.checkpoints.save(state);
+        for (const event of second.events)
+            await emit(event);
+        await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+        return { outcome: "action_required", state };
+    }
+    catch (error) {
+        if (!terminal) {
+            const interrupted = options.signal?.aborted ||
+                (error instanceof Error && error.message === "Setup interrupted");
+            await emit({
+                event: "run.failed",
+                code: interrupted ? "interrupted" : "setup_failed",
+                message: interrupted
+                    ? "Setup session was interrupted and can be resumed."
+                    : error instanceof Error && error.message.startsWith("No setup checkpoint")
+                        ? error.message
+                        : "Setup session could not complete. No credentials were stored.",
+                resumable: state !== undefined,
+            });
+        }
+        throw error;
+    }
+}

package/dist/setup/types.d.ts

@@ -0,0 +1,145 @@
+/** Version carried by every setup JSONL event. */
+export declare const SETUP_EVENT_CONTRACT_VERSION: 1;
+/** Names in the version 1 setup event contract. */
+export type SetupEventName = "run.started" | "project.detected" | "plan.ready" | "step.started" | "step.completed" | "file.changed" | "diagnostic" | "action.required" | "trial.created" | "receipt.verified" | "claim.required" | "claim.completed" | "run.completed" | "run.failed";
+interface EventBase<Name extends SetupEventName> {
+    /** JSONL contract version, independent of the package version. */
+    contractVersion: typeof SETUP_EVENT_CONTRACT_VERSION;
+    /** Event discriminator. */
+    event: Name;
+    /** Deterministic installer-session identifier; it is not a Hue Run identifier. */
+    runId: string;
+    /** One-based sequence within this command invocation. */
+    sequence: number;
+    /** ISO-8601 time supplied by the runner clock. */
+    timestamp: string;
+}
+/** An installer setup-session command invocation began; this is not a Hue Run. */
+export interface RunStartedEvent extends EventBase<"run.started"> {
+    /** Command being executed. */
+    command: "setup" | "resume" | "status" | "claim";
+    /** Renderer selected for this invocation. */
+    mode: "human" | "plain" | "jsonl";
+    /** Whether a checkpoint existed when the invocation began. */
+    resumed: boolean;
+}
+/** Static project facts read without executing repository code. */
+export interface SetupProjectDetection {
+    /** Canonical project root. */
+    root: string;
+    /** Stable hash of the root and detected, non-secret facts. */
+    fingerprint: string;
+    /** Supported language ecosystems found at the root. */
+    languages: Array<"typescript" | "python">;
+    /** Package managers identified from declarations or lockfiles. */
+    packageManagers: Array<"bun" | "npm" | "pnpm" | "yarn" | "uv" | "poetry" | "pip">;
+    /** Known frameworks identified from manifest dependency names. */
+    frameworks: Array<"nextjs" | "nestjs" | "express" | "fastapi" | "django" | "flask" | "vercel-ai-sdk">;
+    /** Language ecosystems with an existing Hue dependency. */
+    hue: "absent" | "typescript" | "python" | "multiple";
+    /** Language ecosystems with an existing OpenTelemetry dependency. */
+    openTelemetry: "absent" | "typescript" | "python" | "multiple";
+}
+/** Project detection completed. */
+export interface ProjectDetectedEvent extends EventBase<"project.detected"> {
+    /** Bounded static detection result. */
+    project: SetupProjectDetection;
+}
+/** A bounded local setup plan. */
+export interface SetupPlan {
+    /** Ordered setup step names. */
+    steps: Array<"detect-project" | "configure-telemetry" | "verify-receipt" | "claim-project">;
+    /** Whether this plan is permitted to change project files. */
+    mutatesProject: boolean;
+    /** Whether completion ultimately requires a backend adapter. */
+    backendRequired: boolean;
+}
+/** The deterministic setup plan is ready. */
+export interface PlanReadyEvent extends EventBase<"plan.ready"> {
+    /** Deterministic plan for this project. */
+    plan: SetupPlan;
+}
+/** A named setup step began. */
+export interface StepStartedEvent extends EventBase<"step.started"> {
+    /** Step that began. */
+    step: SetupPlan["steps"][number];
+}
+/** A named setup step completed. */
+export interface StepCompletedEvent extends EventBase<"step.completed"> {
+    /** Step that completed. */
+    step: SetupPlan["steps"][number];
+    /** Observable result of the step. */
+    outcome: "unchanged" | "changed" | "verified" | "skipped";
+}
+/** A future mutating adapter changed a project file. */
+export interface FileChangedEvent extends EventBase<"file.changed"> {
+    /** Project-relative changed path. */
+    path: string;
+    /** Whether the adapter created or updated the path. */
+    change: "created" | "updated";
+}
+/** A secret-free diagnostic safe for terminals and transcripts. */
+export interface DiagnosticEvent extends EventBase<"diagnostic"> {
+    /** Diagnostic severity. */
+    level: "info" | "warning" | "error";
+    /** Stable machine-readable diagnostic code. */
+    code: string;
+    /** Secret-free human-readable explanation. */
+    message: string;
+}
+/** Progress needs an explicit local or human action. */
+export interface ActionRequiredEvent extends EventBase<"action.required"> {
+    /** Kind of action needed to continue. */
+    action: "claim-project" | "configure" | "run-instrumented-request" | "open-claim-url" | "capture-approved-content" | "review-content-approved-trace";
+    /** Secret-free explanation of the action. */
+    message: string;
+    /** Optional command the caller may run. */
+    command?: string;
+    /** Optional HTTPS destination for a user action. */
+    url?: string;
+}
+/** A backend adapter created an anonymous trial. */
+export interface TrialCreatedEvent extends EventBase<"trial.created"> {
+    /** Non-secret backend trial identifier. */
+    trialId: string;
+    /** ISO-8601 trial expiration. */
+    expiresAt: string;
+}
+/** A backend adapter verified instrumentation-only receipt evidence. */
+export interface ReceiptVerifiedEvent extends EventBase<"receipt.verified"> {
+    /** Non-secret receipt identifier. */
+    receiptId: string;
+    /** Verified lowercase OpenTelemetry trace identifier; this does not prove content approval. */
+    traceId: string;
+}
+/** The anonymous project can be claimed by a person. */
+export interface ClaimRequiredEvent extends EventBase<"claim.required"> {
+    /** Non-secret claim identifier. */
+    claimId: string;
+    /** User-facing claim destination; never persisted in setup checkpoints. */
+    url: string;
+}
+/** A backend adapter confirmed that the project was claimed. */
+export interface ClaimCompletedEvent extends EventBase<"claim.completed"> {
+    /** Non-secret completed claim identifier. */
+    claimId: string;
+}
+/** Exactly one successful terminal installer event ends a JSONL setup-session invocation. */
+export interface RunCompletedEvent extends EventBase<"run.completed"> {
+    /** Terminal invocation result. */
+    outcome: "ready" | "action_required" | "unchanged";
+    /** Whether resumable state exists after the invocation. */
+    checkpointed: boolean;
+}
+/** Exactly one failed terminal installer event ends a JSONL setup-session invocation. */
+export interface RunFailedEvent extends EventBase<"run.failed"> {
+    /** Stable machine-readable failure code. */
+    code: string;
+    /** Sanitized failure explanation. */
+    message: string;
+    /** Whether a later `resume` can safely continue. */
+    resumable: boolean;
+}
+/** Version 1 setup JSONL event union. */
+export type SetupEvent = RunStartedEvent | ProjectDetectedEvent | PlanReadyEvent | StepStartedEvent | StepCompletedEvent | FileChangedEvent | DiagnosticEvent | ActionRequiredEvent | TrialCreatedEvent | ReceiptVerifiedEvent | ClaimRequiredEvent | ClaimCompletedEvent | RunCompletedEvent | RunFailedEvent;
+export {};

package/dist/setup/types.js

@@ -0,0 +1,2 @@
+/** Version carried by every setup JSONL event. */
+export const SETUP_EVENT_CONTRACT_VERSION = 1;

package/dist/setup.d.ts

@@ -0,0 +1,6 @@
+/** Local, resumable installer setup-session contracts used by the `hue` command. */
+export { SETUP_EVENT_CONTRACT_VERSION, type ActionRequiredEvent, type ClaimCompletedEvent, type ClaimRequiredEvent, type DiagnosticEvent, type FileChangedEvent, type PlanReadyEvent, type ProjectDetectedEvent, type ReceiptVerifiedEvent, type RunCompletedEvent, type RunFailedEvent, type RunStartedEvent, type SetupEvent, type SetupEventName, type SetupPlan, type SetupProjectDetection, type StepCompletedEvent, type StepStartedEvent, type TrialCreatedEvent, } from "./setup/types.js";
+export { createInitialSetupState, transitionSetup, type SetupEffect, type SetupMachineInput, type SetupMachineState, type SetupTransition, } from "./setup/machine.js";
+export { runSetup, type SetupBackendAdapter, type SetupBackendClaim, type SetupBackendReceipt, type SetupBackendTrial, type SetupCheckpointAdapter, type SetupProjectAdapter, type SetupRunOptions, type SetupRunResult, } from "./setup/runner.js";
+export { detectSetupProject } from "./setup/detect.js";
+export { renderHumanEvent, renderJsonlEvent, renderPlainEvent, selectSetupOutputMode, type SetupOutputMode, } from "./setup/render.js";

package/dist/setup.js

@@ -0,0 +1,6 @@
+/** Local, resumable installer setup-session contracts used by the `hue` command. */
+export { SETUP_EVENT_CONTRACT_VERSION, } from "./setup/types.js";
+export { createInitialSetupState, transitionSetup, } from "./setup/machine.js";
+export { runSetup, } from "./setup/runner.js";
+export { detectSetupProject } from "./setup/detect.js";
+export { renderHumanEvent, renderJsonlEvent, renderPlainEvent, selectSetupOutputMode, } from "./setup/render.js";

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.3.0";
+export declare const sdkVersion = "0.3.1";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.3.0";
+export const sdkVersion = "0.3.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -29,6 +29,8 @@
   ],
   "files": [
     "dist",
+    "CLI.md",
+    "setup-events.schema.json",
     "README.md",
     "EVALUATIONS.md",
     "ENVIRONMENTS.md",
@@ -36,6 +38,9 @@
     "LICENSE"
   ],
   "type": "module",
+  "bin": {
+    "hue": "./dist/setup/cli.js"
+  },
   "sideEffects": [
     "./dist/evals/schema-worker.js"
   ],
@@ -65,6 +70,12 @@
       "import": "./dist/managed.js",
       "default": "./dist/managed.js"
     },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "import": "./dist/setup.js",
+      "default": "./dist/setup.js"
+    },
+    "./setup-events.schema.json": "./setup-events.schema.json",
     "./package.json": "./package.json"
   },
   "scripts": {

package/setup-events.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hue.run/schemas/setup-events-v1.json",
+  "title": "Hue setup-session installer event version 1",
+  "description": "Installer lifecycle events only. run.* events are setup-session invocations, not Hue Runs.",
+  "oneOf": [
+    { "$ref": "#/$defs/run.started" },
+    { "$ref": "#/$defs/project.detected" },
+    { "$ref": "#/$defs/plan.ready" },
+    { "$ref": "#/$defs/step.started" },
+    { "$ref": "#/$defs/step.completed" },
+    { "$ref": "#/$defs/file.changed" },
+    { "$ref": "#/$defs/diagnostic" },
+    { "$ref": "#/$defs/action.required" },
+    { "$ref": "#/$defs/trial.created" },
+    { "$ref": "#/$defs/receipt.verified" },
+    { "$ref": "#/$defs/claim.required" },
+    { "$ref": "#/$defs/claim.completed" },
+    { "$ref": "#/$defs/run.completed" },
+    { "$ref": "#/$defs/run.failed" }
+  ],
+  "$defs": {
+    "base": {
+      "type": "object",
+      "required": ["contractVersion", "event", "runId", "sequence", "timestamp"],
+      "properties": {
+        "contractVersion": { "const": 1 },
+        "event": { "type": "string", "maxLength": 40 },
+        "runId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,80}$" },
+        "sequence": { "type": "integer", "minimum": 1, "maximum": 10000 },
+        "timestamp": { "type": "string", "format": "date-time", "maxLength": 40 }
+      }
+    },
+    "step": { "enum": ["detect-project", "configure-telemetry", "verify-receipt", "claim-project"] },
+    "text": { "type": "string", "minLength": 1, "maxLength": 1000 },
+    "identifier": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" },
+    "plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["steps", "mutatesProject", "backendRequired"],
+      "properties": {
+        "steps": { "type": "array", "items": { "$ref": "#/$defs/step" }, "minItems": 1, "maxItems": 10, "uniqueItems": true },
+        "mutatesProject": { "type": "boolean" },
+        "backendRequired": { "type": "boolean" }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["root", "fingerprint", "languages", "packageManagers", "frameworks", "hue", "openTelemetry"],
+      "properties": {
+        "root": { "type": "string", "minLength": 1, "maxLength": 4096 },
+        "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "languages": { "type": "array", "items": { "enum": ["typescript", "python"] }, "maxItems": 2, "uniqueItems": true },
+        "packageManagers": { "type": "array", "items": { "enum": ["bun", "npm", "pnpm", "yarn", "uv", "poetry", "pip"] }, "maxItems": 7, "uniqueItems": true },
+        "frameworks": { "type": "array", "items": { "enum": ["nextjs", "nestjs", "express", "fastapi", "django", "flask", "vercel-ai-sdk"] }, "maxItems": 7, "uniqueItems": true },
+        "hue": { "enum": ["absent", "typescript", "python", "multiple"] },
+        "openTelemetry": { "enum": ["absent", "typescript", "python", "multiple"] }
+      }
+    },
+    "run.started": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["command", "mode", "resumed"], "properties": { "event": { "const": "run.started" }, "command": { "enum": ["setup", "resume", "status", "claim"] }, "mode": { "enum": ["human", "plain", "jsonl"] }, "resumed": { "type": "boolean" } } }],
+      "unevaluatedProperties": false
+    },
+    "project.detected": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["project"], "properties": { "event": { "const": "project.detected" }, "project": { "$ref": "#/$defs/project" } } }],
+      "unevaluatedProperties": false
+    },
+    "plan.ready": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["plan"], "properties": { "event": { "const": "plan.ready" }, "plan": { "$ref": "#/$defs/plan" } } }],
+      "unevaluatedProperties": false
+    },
+    "step.started": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["step"], "properties": { "event": { "const": "step.started" }, "step": { "$ref": "#/$defs/step" } } }],
+      "unevaluatedProperties": false
+    },
+    "step.completed": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["step", "outcome"], "properties": { "event": { "const": "step.completed" }, "step": { "$ref": "#/$defs/step" }, "outcome": { "enum": ["unchanged", "changed", "verified", "skipped"] } } }],
+      "unevaluatedProperties": false
+    },
+    "file.changed": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["path", "change"], "properties": { "event": { "const": "file.changed" }, "path": { "type": "string", "minLength": 1, "maxLength": 4096 }, "change": { "enum": ["created", "updated"] } } }],
+      "unevaluatedProperties": false
+    },
+    "diagnostic": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["level", "code", "message"], "properties": { "event": { "const": "diagnostic" }, "level": { "enum": ["info", "warning", "error"] }, "code": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$" }, "message": { "$ref": "#/$defs/text" } } }],
+      "unevaluatedProperties": false
+    },
+    "action.required": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["action", "message"], "properties": { "event": { "const": "action.required" }, "action": { "enum": ["claim-project", "configure", "run-instrumented-request", "open-claim-url", "capture-approved-content", "review-content-approved-trace"] }, "message": { "$ref": "#/$defs/text" }, "command": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } } }],
+      "unevaluatedProperties": false
+    },
+    "trial.created": {
+      "type": "object",
+      "description": "An anonymous setup trial hard-pinned to trial_metadata_v1.",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["trialId", "expiresAt"], "properties": { "event": { "const": "trial.created" }, "trialId": { "$ref": "#/$defs/identifier" }, "expiresAt": { "type": "string", "format": "date-time", "maxLength": 40 } } }],
+      "unevaluatedProperties": false
+    },
+    "receipt.verified": {
+      "type": "object",
+      "description": "Instrumentation-only proof for an anonymous trace; not evidence of content approval or Scenario suitability.",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["receiptId", "traceId"], "properties": { "event": { "const": "receipt.verified" }, "receiptId": { "$ref": "#/$defs/identifier" }, "traceId": { "type": "string", "pattern": "^[a-f0-9]{32}$" } } }],
+      "unevaluatedProperties": false
+    },
+    "claim.required": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["claimId", "url"], "properties": { "event": { "const": "claim.required" }, "claimId": { "$ref": "#/$defs/identifier" }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } } }],
+      "unevaluatedProperties": false
+    },
+    "claim.completed": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["claimId"], "properties": { "event": { "const": "claim.completed" }, "claimId": { "$ref": "#/$defs/identifier" } } }],
+      "unevaluatedProperties": false
+    },
+    "run.completed": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["outcome", "checkpointed"], "properties": { "event": { "const": "run.completed" }, "outcome": { "enum": ["ready", "action_required", "unchanged"] }, "checkpointed": { "type": "boolean" } } }],
+      "unevaluatedProperties": false
+    },
+    "run.failed": {
+      "type": "object",
+      "allOf": [{ "$ref": "#/$defs/base" }, { "type": "object", "required": ["code", "message", "resumable"], "properties": { "event": { "const": "run.failed" }, "code": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$" }, "message": { "$ref": "#/$defs/text" }, "resumable": { "type": "boolean" } } }],
+      "unevaluatedProperties": false
+    }
+  }
+}