@hue-run/sdk 0.3.1 → 0.4.1

package/dist/setup/machine.js

@@ -14,8 +14,14 @@ export function transitionSetup(state, input) {
     }
     if (state.phase === "detecting" && input.type === "project.detected") {
         const plan = {
-            steps: ["detect-project", "configure-telemetry", "verify-receipt", "claim-project"],
-            mutatesProject: false,
+            steps: [
+                "detect-project",
+                "install-runtime",
+                "configure-telemetry",
+                "verify-application-receipt",
+                "claim-project",
+            ],
+            mutatesProject: true,
             backendRequired: true,
         };
         return {
@@ -31,11 +37,6 @@ export function transitionSetup(state, input) {
                 { 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.",
-                },
             ],
         };
     }

package/dist/setup/render.d.ts

@@ -1,6 +1,8 @@
-import type { SetupEvent } from "./types.js";
+import { type SetupEvent } from "./types.js";
 /** Supported setup transcript formats. */
 export type SetupOutputMode = "human" | "plain" | "jsonl";
+/** Removes capability-shaped fragments and bounds text before it reaches a public transcript. */
+export declare function redactSetupTranscriptText(value: string): string;
 /** Renders one newline-free JSON object for JSONL output. */
 export declare function renderJsonlEvent(event: SetupEvent): string;
 /** Renders one ANSI-free append-only transcript entry. */

package/dist/setup/render.js

@@ -1,3 +1,4 @@
+import { SETUP_EVENT_CONTRACT_VERSION } from "./types.js";
 const ansi = {
     cyan: "\u001b[36m",
     green: "\u001b[32m",
@@ -6,6 +7,206 @@ const ansi = {
     dim: "\u001b[2m",
     reset: "\u001b[0m",
 };
+/** Removes capability-shaped fragments and bounds text before it reaches a public transcript. */
+export function redactSetupTranscriptText(value) {
+    if (typeof value !== "string")
+        return "[invalid text]";
+    // Normalize encoded/separated spellings before matching, and redact before truncating.
+    let normalized = value;
+    for (let pass = 0; pass < 3; pass++)
+        normalized = normalized
+            .replace(/%([a-f0-9]{2})/giu, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+            .replace(/\\u([a-f0-9]{4})/giu, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+            .replaceAll("\\/", "/");
+    normalized = normalized.replace(/[\p{Cc}\p{Cf}]/gu, "");
+    const withoutUrls = normalized.replace(/https?:\/\/[^\s"'<>]+/giu, (candidate) => {
+        try {
+            const url = new URL(candidate);
+            return url.hash || url.pathname.includes("/setup/claim")
+                ? "[private claim handoff]"
+                : candidate;
+        }
+        catch {
+            return "[redacted URL]";
+        }
+    });
+    const redacted = withoutUrls
+        // Deliberately recognize incomplete and unknown namespace suffixes too. A
+        // transport exception may contain only a truncated credential.
+        .replace(/hue_(?:sk|setup|install|claim)_[A-Za-z0-9_-]*/giu, "[private credential]")
+        .replace(/#[A-Za-z0-9_-]+/gu, "#[redacted]")
+        .replace(/\b(claim[_-]?(?:secret|token))(["']?\s*[:=]\s*["']?)[A-Za-z0-9_-]+/giu, "$1$2[redacted]")
+        .replace(/(?<![A-Za-z0-9_-])[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-])/gu, "[private capability]");
+    return redacted.slice(0, 1000);
+}
+function choice(value, allowed) {
+    return allowed.includes(value) ? value : allowed[0];
+}
+function choices(values, allowed) {
+    return Array.isArray(values)
+        ? [...new Set(values.filter((value) => allowed.includes(value)))]
+        : [];
+}
+const steps = [
+    "detect-project",
+    "install-runtime",
+    "configure-telemetry",
+    "verify-application-receipt",
+    "claim-project",
+];
+function publicEvent(event) {
+    const base = {
+        contractVersion: SETUP_EVENT_CONTRACT_VERSION,
+        runId: redactSetupTranscriptText(event.runId),
+        sequence: Number.isSafeInteger(event.sequence) ? event.sequence : 1,
+        timestamp: redactSetupTranscriptText(event.timestamp),
+    };
+    switch (event.event) {
+        case "run.started":
+            return {
+                ...base,
+                event: "run.started",
+                command: choice(event.command, ["setup", "resume", "status", "claim"]),
+                mode: choice(event.mode, ["human", "plain", "jsonl"]),
+                resumed: event.resumed === true,
+            };
+        case "project.detected":
+            return {
+                ...base,
+                event: "project.detected",
+                project: {
+                    root: redactSetupTranscriptText(event.project.root),
+                    fingerprint: redactSetupTranscriptText(event.project.fingerprint),
+                    languages: choices(event.project.languages, ["typescript", "python"]),
+                    packageManagers: choices(event.project.packageManagers, [
+                        "bun",
+                        "npm",
+                        "pnpm",
+                        "yarn",
+                        "uv",
+                        "poetry",
+                        "pip",
+                    ]),
+                    frameworks: choices(event.project.frameworks, [
+                        "nextjs",
+                        "nestjs",
+                        "express",
+                        "fastapi",
+                        "django",
+                        "flask",
+                        "vercel-ai-sdk",
+                    ]),
+                    hue: choice(event.project.hue, ["absent", "typescript", "python", "multiple"]),
+                    openTelemetry: choice(event.project.openTelemetry, [
+                        "absent",
+                        "typescript",
+                        "python",
+                        "multiple",
+                    ]),
+                },
+            };
+        case "plan.ready":
+            return {
+                ...base,
+                event: "plan.ready",
+                plan: {
+                    steps: choices(event.plan.steps, steps),
+                    mutatesProject: event.plan.mutatesProject === true,
+                    backendRequired: event.plan.backendRequired === true,
+                },
+            };
+        case "step.started":
+            return { ...base, event: "step.started", step: choice(event.step, steps) };
+        case "step.completed":
+            return {
+                ...base,
+                event: "step.completed",
+                step: choice(event.step, steps),
+                outcome: choice(event.outcome, ["unchanged", "changed", "verified", "skipped"]),
+            };
+        case "file.changed":
+            return {
+                ...base,
+                event: "file.changed",
+                path: redactSetupTranscriptText(event.path),
+                change: choice(event.change, ["created", "updated"]),
+            };
+        case "diagnostic":
+            return {
+                ...base,
+                event: "diagnostic",
+                level: choice(event.level, ["info", "warning", "error"]),
+                code: redactSetupTranscriptText(event.code),
+                message: redactSetupTranscriptText(event.message),
+            };
+        case "privacy.notice":
+            return {
+                ...base,
+                event: "privacy.notice",
+                privacyUrl: "https://hue.run/privacy",
+                effectiveDate: "2026-08-24",
+                securityUrl: "https://trust.hue.run/",
+            };
+        case "action.required":
+            return {
+                ...base,
+                event: "action.required",
+                action: choice(event.action, [
+                    "claim-project",
+                    "configure",
+                    "select-project",
+                    "integrate-application",
+                    "run-instrumented-request",
+                    "open-claim-handoff",
+                    "restart-claim-handoff",
+                ]),
+                message: redactSetupTranscriptText(event.message),
+                ...(event.command ? { command: redactSetupTranscriptText(event.command) } : {}),
+            };
+        case "trial.created":
+            return {
+                ...base,
+                event: "trial.created",
+                trialId: redactSetupTranscriptText(event.trialId),
+                expiresAt: redactSetupTranscriptText(event.expiresAt),
+            };
+        case "receipt.verified":
+            return {
+                ...base,
+                event: "receipt.verified",
+                receiptId: redactSetupTranscriptText(event.receiptId),
+                traceId: redactSetupTranscriptText(event.traceId),
+                source: "repository-http-boundary",
+            };
+        case "claim.required":
+            return {
+                ...base,
+                event: "claim.required",
+                claimId: redactSetupTranscriptText(event.claimId),
+            };
+        case "claim.completed":
+            return {
+                ...base,
+                event: "claim.completed",
+                claimId: redactSetupTranscriptText(event.claimId),
+            };
+        case "run.completed":
+            return {
+                ...base,
+                event: "run.completed",
+                outcome: choice(event.outcome, ["ready", "action_required", "unchanged"]),
+                checkpointed: event.checkpointed === true,
+            };
+        case "run.failed":
+            return {
+                ...base,
+                event: "run.failed",
+                code: redactSetupTranscriptText(event.code),
+                message: redactSetupTranscriptText(event.message),
+                resumable: event.resumable === true,
+            };
+    }
+}
 function wrap(text, width, prefix) {
     const available = Math.max(20, width - prefix.length);
     const words = text.split(/\s+/u);
@@ -46,14 +247,16 @@ function summary(event) {
             return `${event.change === "created" ? "Created" : "Updated"} ${event.path}.`;
         case "diagnostic":
             return `${event.code}: ${event.message}`;
+        case "privacy.notice":
+            return `Privacy notice effective ${event.effectiveDate}: ${event.privacyUrl}. Security: ${event.securityUrl}`;
         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}.`;
+            return `Repository HTTP boundary receipt ${event.receiptId} verified for trace ${event.traceId}.`;
         case "claim.required":
-            return `Claim ${event.claimId} is ready: ${event.url}`;
+            return `Account linkage is ready for project owner action (${event.claimId}).`;
         case "claim.completed":
             return `Claim ${event.claimId} completed.`;
         case "run.completed":
@@ -64,11 +267,11 @@ function summary(event) {
 }
 /** Renders one newline-free JSON object for JSONL output. */
 export function renderJsonlEvent(event) {
-    return JSON.stringify(event);
+    return JSON.stringify(publicEvent(event));
 }
 /** Renders one ANSI-free append-only transcript entry. */
 export function renderPlainEvent(event, width = 80) {
-    const text = summary(event);
+    const text = summary(publicEvent(event));
     if (!text)
         return "";
     const marker = event.event === "run.failed"
@@ -80,7 +283,7 @@ export function renderPlainEvent(event, width = 80) {
 }
 /** 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);
+    const text = summary(publicEvent(event));
     if (!text)
         return "";
     const [symbol, tone] = event.event === "run.failed"
@@ -102,7 +305,7 @@ export function renderHumanEvent(event, width = 80, color = true) {
 export function selectSetupOutputMode(input) {
     if (input.agent)
         return "jsonl";
-    if (input.explicit === "jsonl" || input.explicit === "plain")
+    if (input.explicit)
         return input.explicit;
     const env = input.env ?? process.env;
     if (!input.isTTY || env.NO_COLOR !== undefined || env.TERM === "dumb" || env.CI !== undefined)

package/dist/setup/runner.d.ts

@@ -1,101 +1,51 @@
+import type { SetupBackendAdapter } from "./backend.js";
 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. */
+/** Detects the supported language and safe setup plan for a project root. */
 export interface SetupProjectAdapter {
-    /** Inspects bounded metadata without executing project code. */
+    /** Inspects a project without executing its code. */
     detect(root: string, signal?: AbortSignal): Promise<SetupProjectDetection>;
 }
-/** Secret-free durable state boundary. */
+/** Persists secret-free setup progress across interruptions. */
 export interface SetupCheckpointAdapter {
-    /** Loads and validates state for this exact project identity. */
+    /** Reads the checkpoint for one setup run and project. */
     load(runId: string, projectRoot: string): Promise<SetupMachineState | undefined>;
-    /** Durably saves secret-free state before the next effect. */
+    /** Atomically saves the latest setup state. */
     save(state: SetupMachineState): Promise<void>;
 }
-/** Options for one deterministic setup invocation. */
+/** Backend operations consumed by the resumable setup runner. */
+export type SetupBackendOperations = Pick<SetupBackendAdapter, "prepare" | "resetLocalCache" | "preflight" | "localInstallation" | "provision" | "status" | "credentials" | "installRuntime" | "configure" | "exerciseApplication" | "prepareClaimHandoff" | "verifyApplication" | "verifyRevokedCredential">;
+/** Inputs for one invocation of the resumable setup runner. */
 export interface SetupRunOptions {
-    /** CLI operation being orchestrated. */
+    /** Operation requested by the caller. */
     command: "setup" | "resume" | "status" | "claim";
-    /** Renderer mode recorded in `run.started`. */
+    /** Output contract selected by the CLI. */
     mode: "human" | "plain" | "jsonl";
-    /** Stable installer-session identifier, unrelated to Hue Runs. */
+    /** Stable identifier for this resumable invocation. */
     runId: string;
-    /** Canonical project root. */
+    /** Absolute project directory being configured. */
     projectRoot: string;
-    /** Injected static-inspection adapter. */
+    /** Safe project detector. */
     project: SetupProjectAdapter;
-    /** Injected secret-free checkpoint adapter. */
+    /** Secret-free checkpoint persistence. */
     checkpoints: SetupCheckpointAdapter;
-    /** Reserved injection point for the follow-up integration; intentionally unused by this slice. */
-    backend?: SetupBackendAdapter;
-    /** Receives each ordered event exactly once. */
+    /** Real protocol adapter; omitting it can only report that action is required. */
+    backend?: SetupBackendOperations;
+    /** Receives each ordered setup event. */
     emit(event: SetupEvent): void | Promise<void>;
-    /** Injectable clock for deterministic tests. */
+    /** Injectable clock used by deterministic tests. */
     now?: () => Date;
-    /** Optional cancellation signal. */
+    /** Cancels bounded local and network work. */
     signal?: AbortSignal;
+    /** Explicit owner request to replace the current browser handoff. Human claim commands only. */
+    claimRestart?: boolean;
 }
-/** Result of one setup invocation. */
+/** Terminal outcome and latest resumable state from one setup invocation. */
 export interface SetupRunResult {
-    /** Non-fabricated local outcome. */
+    /** Whether setup is verified, needs owner action, or made no change. */
     outcome: "ready" | "action_required" | "unchanged";
-    /** Last validated state, when one exists. */
+    /** Latest checkpoint state when project detection has begun. */
     state?: SetupMachineState;
 }
-/** Runs one installer setup-session command and emits one terminal event; it never launches a Hue Run. */
+/** Runs one resumable setup command and emits exactly one terminal event. */
 export declare function runSetup(options: SetupRunOptions): Promise<SetupRunResult>;
-export {};