@hue-run/sdk 0.3.2 → 0.4.1

package/dist/setup/runner.js

@@ -1,6 +1,14 @@
+import { SetupBackendError } from "./backend.js";
+import { SetupApplicationActionRequired } from "./application.js";
+import { acquireSetupCommandLock } from "./lock.js";
 import { createInitialSetupState, transitionSetup } from "./machine.js";
+import { redactSetupTranscriptText } from "./render.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. */
+function rejectTerminal(status) {
+    if (status.state === "expired" || status.state === "purged")
+        throw new SetupBackendError("SETUP_EXPIRED", "This setup installation is terminal and will not be replaced automatically.", 410);
+}
+/** Runs one resumable setup command and emits exactly one terminal event. */
 export async function runSetup(options) {
     const now = options.now ?? (() => new Date());
     let sequence = 0;
@@ -23,7 +31,14 @@ export async function runSetup(options) {
         await options.emit(event);
     };
     let state;
+    let releaseLock;
     try {
+        if (options.backend) {
+            releaseLock = await acquireSetupCommandLock(options.projectRoot);
+            options.backend.resetLocalCache();
+        }
+        if (options.claimRestart && (options.command !== "claim" || options.mode !== "human"))
+            throw new Error("Refusing non-human browser handoff restart");
         state = await options.checkpoints.load(options.runId, options.projectRoot);
         await emit({
             event: "run.started",
@@ -34,84 +49,344 @@ export async function runSetup(options) {
         if (options.signal?.aborted)
             throw new Error("Setup interrupted");
         if (options.command === "status") {
+            if (!options.backend) {
+                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 });
+                return { outcome: "unchanged", state };
+            }
+            if (!state) {
+                const local = await options.backend.localInstallation();
+                if (!local) {
+                    await emit({
+                        event: "diagnostic",
+                        level: "info",
+                        code: "installation.absent",
+                        message: "No Hue setup installation exists for this project and origin.",
+                    });
+                    await emit({ event: "run.completed", outcome: "unchanged", checkpointed: false });
+                    return { outcome: "unchanged" };
+                }
+            }
+        }
+        if (!state) {
+            if (options.command === "resume" || options.command === "claim")
+                throw new Error("No setup checkpoint exists for this project");
+            state = createInitialSetupState(options.runId, options.projectRoot);
+            await options.checkpoints.save(state);
+        }
+        // A checkpoint is progress, never authority for current manifests or ownership.
+        {
+            state = createInitialSetupState(options.runId, options.projectRoot);
+            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);
+        }
+        if (state.phase !== "local-ready")
+            throw new Error("Setup project detection did not complete");
+        if (!options.backend) {
+            await emit({
+                event: "action.required",
+                action: "configure",
+                message: "A SetupBackendAdapter is required to continue; no success was fabricated.",
+            });
+            await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+            return { outcome: "action_required", state };
+        }
+        const project = state.project;
+        let status;
+        const local = await options.backend.localInstallation();
+        if (options.command === "status" && !local) {
             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.",
+                code: "installation.absent",
+                message: "No Hue setup installation exists for this project and origin.",
+            });
+            await emit({ event: "run.completed", outcome: "unchanged", checkpointed: true });
+            return { outcome: "unchanged", state };
+        }
+        if (options.command === "claim" && !local)
+            throw new Error("No Hue setup installation exists for this project and origin");
+        try {
+            const availability = await options.backend.preflight(project, options.signal, options.command === "setup" || options.command === "resume");
+            if ((options.command === "setup" || options.command === "resume") &&
+                availability?.state === "inactive") {
+                await emit({
+                    event: "diagnostic",
+                    level: "warning",
+                    code: "setup.inactive",
+                    message: "Hue anonymous setup is currently inactive; no project or installation files were changed.",
+                });
+                await emit({
+                    event: "action.required",
+                    action: "configure",
+                    message: "Rerun hue resume after Hue setup admissions are available.",
+                    command: "hue resume",
+                });
+                await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+                return { outcome: "action_required", state };
+            }
+            if (availability) {
+                await emit({
+                    event: "privacy.notice",
+                    privacyUrl: availability.privacyNotice.url,
+                    effectiveDate: availability.privacyNotice.effectiveDate,
+                    securityUrl: availability.securityUrl,
+                });
+            }
+        }
+        catch (error) {
+            if (!(error instanceof SetupApplicationActionRequired))
+                throw error;
+            await emit({
+                event: "action.required",
+                action: error.code === "ambiguous-project" ? "select-project" : "integrate-application",
+                message: error.message,
+                command: "hue resume",
+            });
+            await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+            return { outcome: "action_required", state };
+        }
+        if (options.command === "setup" || options.command === "resume") {
+            await emit({ event: "step.started", step: "install-runtime" });
+            const installed = await options.backend.installRuntime(project);
+            await emit({
+                event: "step.completed",
+                step: "install-runtime",
+                outcome: installed ? "changed" : "unchanged",
             });
+            await options.backend.prepare();
+            // Once a credential exists, status is recovery and spends no provisioning admission.
+            status = local?.credential
+                ? await options.backend.status(options.signal)
+                : await options.backend.provision(options.signal);
+            rejectTerminal(status);
+            if (status.state === "active")
+                await emit({
+                    event: "trial.created",
+                    trialId: status.installationId,
+                    expiresAt: status.expiresAt,
+                });
+        }
+        else {
+            status = await options.backend.status(options.signal);
+            rejectTerminal(status);
+        }
+        if (options.command === "status" && status.state === "active") {
             await emit({
-                event: "run.completed",
-                outcome: "unchanged",
-                checkpointed: state !== undefined,
+                event: "diagnostic",
+                level: "info",
+                code: "installation.active",
+                message: "The metadata-only setup installation is active and awaiting account claim.",
             });
+            await emit({ event: "run.completed", outcome: "unchanged", checkpointed: true });
             return { outcome: "unchanged", state };
         }
-        if (options.command === "claim") {
+        if (options.command === "claim" &&
+            status.state === "active" &&
+            local?.applicationEvidence?.verified &&
+            local.applicationEvidence.credentialVersion === 0) {
+            const handoff = await options.backend.prepareClaimHandoff(status, options.mode === "human", options.claimRestart === true, options.signal);
+            await emit({
+                event: "claim.required",
+                claimId: status.installationId,
+            });
             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.",
+                action: handoff.restartRequired ? "restart-claim-handoff" : "open-claim-handoff",
+                message: handoff.restartRequired
+                    ? "The one-time browser handoff is no longer usable. The project owner may explicitly replace it from an interactive local terminal."
+                    : handoff.opened
+                        ? "Finish account linkage in the browser opened from the owner-only local handoff, then rerun hue claim."
+                        : "Ask the project owner to run hue claim in an interactive local terminal, finish account linkage in the browser, then rerun hue claim.",
+                command: handoff.restartRequired ? "hue claim --restart" : "hue claim",
             });
+            await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+            return { outcome: "action_required", state };
+        }
+        const before = await options.backend.prepare();
+        let oldCredential = status.state === "claimed" && before.credential?.version === 0
+            ? before.credential.apiKey
+            : status.state === "claimed"
+                ? before.revocationCredential?.apiKey
+                : undefined;
+        let refreshed = false;
+        for (;;) {
+            try {
+                await options.backend.credentials(status.credentialVersion, options.signal);
+                break;
+            }
+            catch (error) {
+                if (error instanceof SetupBackendError && error.code === "SETUP_CHANGED" && !refreshed) {
+                    refreshed = true;
+                    status = await options.backend.status(options.signal);
+                    rejectTerminal(status);
+                    if (status.state === "claimed" && before.credential?.version === 0)
+                        oldCredential = before.credential.apiKey;
+                    else if (status.state === "claimed" && before.revocationCredential)
+                        oldCredential = before.revocationCredential.apiKey;
+                    continue;
+                }
+                if (error instanceof SetupBackendError && error.code === "SETUP_REVOKED") {
+                    await emit({
+                        event: "action.required",
+                        action: "configure",
+                        message: "The managed setup key was revoked. An account owner must explicitly rotate an account-managed telemetry key; setup will not resurrect it.",
+                    });
+                    await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+                    return { outcome: "action_required", state };
+                }
+                throw error;
+            }
+        }
+        await emit({ event: "step.started", step: "configure-telemetry" });
+        const changes = await options.backend.configure(project);
+        for (const change of changes)
+            await emit({ event: "file.changed", ...change });
+        await emit({
+            event: "step.completed",
+            step: "configure-telemetry",
+            outcome: changes.length ? "changed" : "unchanged",
+        });
+        await emit({ event: "step.started", step: "verify-application-receipt" });
+        const application = await options.backend.prepare();
+        if (!application.applicationEvidence && status.state === "claimed") {
             await emit({
-                event: "run.completed",
-                outcome: "action_required",
-                checkpointed: state !== undefined,
+                event: "action.required",
+                action: "run-instrumented-request",
+                message: "The preserved initial application evidence is unavailable. Setup will not replay business work automatically; run one explicit instrumented request and rerun hue claim.",
+                command: "hue claim",
             });
+            await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
             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 (!application.applicationEvidence) {
+            try {
+                await options.backend.exerciseApplication(project, options.signal);
+            }
+            catch (error) {
+                if (!(error instanceof SetupApplicationActionRequired))
+                    throw error;
+                await emit({
+                    event: "action.required",
+                    action: "run-instrumented-request",
+                    message: error.message,
+                });
+                await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+                return { outcome: "action_required", state };
+            }
         }
-        if (state.phase === "local-ready") {
-            await emit({ event: "project.detected", project: state.project });
-            await emit({ event: "plan.ready", plan: state.plan });
+        const evidence = await options.backend.verifyApplication(options.signal);
+        if (!evidence) {
+            await emit({
+                event: "diagnostic",
+                level: "warning",
+                code: "application.unverified",
+                message: "The existing application request was exported, but exact stored receipt evidence did not arrive within the bounded deadline.",
+            });
             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.",
+                action: "run-instrumented-request",
+                message: "Run hue resume to retry only exact receipt verification; the business request will not be replayed.",
+                command: "hue resume",
             });
             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 };
+        await emit({
+            event: "receipt.verified",
+            receiptId: evidence.traceId,
+            traceId: evidence.traceId,
+            source: "repository-http-boundary",
+        });
+        await emit({
+            event: "step.completed",
+            step: "verify-application-receipt",
+            outcome: "verified",
+        });
+        if (status.state === "active") {
+            const handoff = options.mode === "human"
+                ? await options.backend.prepareClaimHandoff(status, true, false, options.signal)
+                : { opened: false, state: "pending", restartRequired: false };
+            await emit({
+                event: "claim.required",
+                claimId: status.installationId,
+            });
+            await emit({
+                event: "action.required",
+                action: "open-claim-handoff",
+                message: handoff.opened
+                    ? "An existing application request and its exact receipt are verified. Finish account linkage in the browser opened from the owner-only local handoff, then rerun hue claim."
+                    : "An existing application request and its exact receipt are verified. Ask the project owner to run hue claim in an interactive local terminal and finish account linkage, then rerun hue claim.",
+                command: "hue claim",
+            });
+            await emit({ event: "run.completed", outcome: "action_required", checkpointed: true });
+            return { outcome: "action_required", state };
+        }
+        if (oldCredential)
+            await options.backend.verifyRevokedCredential(oldCredential, evidence, options.signal);
+        if (!(await options.backend.prepare()).anonymousKeyRevoked)
+            throw new SetupBackendError("unverified", "The original anonymous credential is unavailable for revocation verification; claim reconciliation is unverified.");
+        await emit({ event: "claim.completed", claimId: status.installationId });
+        await emit({
+            event: "diagnostic",
+            level: "info",
+            code: "claim.reconciled",
+            message: "The replacement credential can access the preserved application receipt, and the superseded anonymous key was refused.",
+        });
+        await emit({ event: "run.completed", outcome: "ready", checkpointed: true });
+        return { outcome: "ready", state };
     }
     catch (error) {
         if (!terminal) {
             const interrupted = options.signal?.aborted ||
                 (error instanceof Error && error.message === "Setup interrupted");
+            const backendCode = error instanceof SetupBackendError ? error.code.toLowerCase() : undefined;
+            const missing = error instanceof Error &&
+                (error.message.startsWith("No setup checkpoint") ||
+                    error.message.startsWith("No Hue setup installation"));
+            const conflict = error instanceof Error && error.message.startsWith("Refusing");
             await emit({
                 event: "run.failed",
-                code: interrupted ? "interrupted" : "setup_failed",
+                code: interrupted
+                    ? "interrupted"
+                    : conflict
+                        ? "configuration_conflict"
+                        : (backendCode ?? "setup_failed"),
                 message: interrupted
                     ? "Setup session was interrupted and can be resumed."
-                    : error instanceof Error && error.message.startsWith("No setup checkpoint")
+                    : missing
                         ? error.message
-                        : "Setup session could not complete. No credentials were stored.",
-                resumable: state !== undefined,
+                        : conflict
+                            ? error.message
+                            : error instanceof SetupBackendError
+                                ? redactSetupTranscriptText(error.message)
+                                : "Setup session could not complete. Local resumable state was preserved.",
+                resumable: state !== undefined && !missing,
             });
         }
         throw error;
     }
+    finally {
+        await releaseLock?.();
+    }
 }

package/dist/setup/socket.d.ts

@@ -0,0 +1,7 @@
+import { type Socket } from "node:net";
+/** Private attempt framing, never an HTTP header or public event. */
+export declare function setupSocketPreface(nonce: string, serverPort: number, clientPort: number): Buffer;
+/** Connect without sending anything; only the launched app knows this attempt's proof. */
+export declare function connectOwnedApplication(port: number, nonce: string, stillRunning: () => boolean, timeoutMillis: number, signal?: AbortSignal): Promise<Socket>;
+/** One HTTP request on exactly the authenticated connection. Never dial, redirect or retry. */
+export declare function requestOwnedApplication(socket: Socket, url: URL, timeoutMillis: number, signal?: AbortSignal): Promise<void>;

package/dist/setup/socket.js

@@ -0,0 +1,144 @@
+import { Agent, request } from "node:http";
+import { createConnection } from "node:net";
+import { createHmac } from "node:crypto";
+/** Private attempt framing, never an HTTP header or public event. */
+export function setupSocketPreface(nonce, serverPort, clientPort) {
+    if (!/^[A-Za-z0-9_-]{43}$/u.test(nonce))
+        throw new Error("Invalid application ownership challenge");
+    const digest = createHmac("sha256", Buffer.from(nonce, "base64url"))
+        .update(`hue-setup-owned-v1\0${serverPort}\0${clientPort}`)
+        .digest("base64url");
+    return Buffer.from(`Hue-setup-owned:${digest}\n`, "ascii");
+}
+/** Connect without sending anything; only the launched app knows this attempt's proof. */
+export async function connectOwnedApplication(port, nonce, stillRunning, timeoutMillis, signal) {
+    const deadline = Date.now() + timeoutMillis;
+    while (Date.now() < deadline) {
+        if (signal?.aborted)
+            throw new Error("Setup interrupted");
+        if (!stillRunning())
+            throw new Error("The application exited before verification");
+        const owned = await new Promise((resolve, reject) => {
+            const socket = createConnection({ host: "127.0.0.1", port });
+            let settled = false;
+            let received = Buffer.alloc(0);
+            let expected;
+            const finish = (success, refused = false) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", abort);
+                socket.removeAllListeners();
+                if (success && stillRunning()) {
+                    socket.pause();
+                    // A peer reset between authentication and request creation must not be unhandled.
+                    socket.on("error", () => undefined);
+                    resolve(socket);
+                }
+                else {
+                    socket.destroy();
+                    if (refused)
+                        resolve(undefined);
+                    else
+                        reject(new Error("The application socket did not prove ownership; no HTTP request was sent"));
+                }
+            };
+            const abort = () => finish(false);
+            const timer = setTimeout(abort, Math.max(1, Math.min(500, deadline - Date.now())));
+            signal?.addEventListener("abort", abort, { once: true });
+            socket.once("connect", () => {
+                expected = setupSocketPreface(nonce, socket.remotePort, socket.localPort);
+            });
+            socket.on("data", (data) => {
+                if (!expected || data.length > expected.length - received.length) {
+                    finish(false);
+                    return;
+                }
+                received = Buffer.concat([received, data]);
+                if (received.length > expected.length ||
+                    !expected.subarray(0, received.length).equals(received))
+                    finish(false);
+                else if (received.length === expected.length)
+                    finish(true);
+            });
+            socket.once("error", (error) => finish(false, !expected && error.code === "ECONNREFUSED"));
+            socket.once("end", abort);
+            socket.once("close", abort);
+        });
+        if (owned)
+            return owned;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(50, Math.max(0, deadline - Date.now()))));
+    }
+    throw new Error("The application did not prove socket ownership within the setup deadline");
+}
+/** One HTTP request on exactly the authenticated connection. Never dial, redirect or retry. */
+export async function requestOwnedApplication(socket, url, timeoutMillis, signal) {
+    if (socket.destroyed || socket.readableEnded || !socket.writable || signal?.aborted) {
+        socket.destroy();
+        throw new Error("The owned application connection closed before its request");
+    }
+    const agent = new Agent({ keepAlive: false, maxSockets: 1, maxTotalSockets: 1 });
+    let assigned = false;
+    agent.createConnection = () => {
+        if (assigned || socket.destroyed)
+            throw new Error("Refusing an application connection replacement");
+        assigned = true;
+        return socket;
+    };
+    try {
+        await new Promise((resolve, reject) => {
+            let finished = false;
+            const done = (error) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", abort);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const fail = () => done(new Error("The single application request did not complete; it will not be replayed"));
+            const outgoing = request(url, { agent, method: "GET", maxHeaderSize: 16 * 1024 });
+            const abort = () => {
+                outgoing.destroy();
+                fail();
+            };
+            const timer = setTimeout(abort, timeoutMillis);
+            signal?.addEventListener("abort", abort, { once: true });
+            outgoing.once("socket", (actual) => {
+                if (actual !== socket) {
+                    actual.destroy();
+                    abort();
+                }
+            });
+            outgoing.once("error", fail);
+            outgoing.once("response", (response) => {
+                if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+                    response.destroy();
+                    done(new Error("The selected application handler did not return a successful response; it will not be replayed"));
+                    return;
+                }
+                let bytes = 0;
+                response.on("data", (data) => {
+                    bytes += data.length;
+                    if (bytes > 1024 * 1024)
+                        abort();
+                });
+                response.once("error", fail);
+                response.once("aborted", fail);
+                response.once("end", () => done());
+            });
+            outgoing.end();
+            socket.resume();
+            if (signal?.aborted)
+                abort();
+        });
+    }
+    finally {
+        agent.destroy();
+        socket.destroy();
+    }
+}

package/dist/setup/source.d.ts

@@ -0,0 +1,9 @@
+export interface ApplicationSyntax {
+    constructorEnd: number;
+    importOffset: number;
+    requestPath: string;
+}
+/** Syntax inspection only: no application imports, evaluation, or package lifecycle. */
+export declare function inspectExpressSource(source: string): ApplicationSyntax;
+/** An isolated stdlib parser never imports/executes the customer's Python module. */
+export declare function inspectFlaskSource(source: string): ApplicationSyntax;