@hue-run/sdk 0.3.1 → 0.4.1

package/dist/receipt.js

@@ -31,7 +31,7 @@ function validId(value, length) {
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function parseReceipt(value, traceId, expected, origin) {
+function parseReceipt(value, traceId, expected, origin, setup = false) {
     if (!record(value) ||
         value.traceId !== traceId ||
         !Number.isSafeInteger(value.spanCount) ||
@@ -52,6 +52,24 @@ function parseReceipt(value, traceId, expected, origin) {
     }
     if (traceUrl.origin !== origin || traceUrl.username || traceUrl.password)
         invalidResponse();
+    if (setup) {
+        const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
+        if (traceUrl.href !== value.traceUrl ||
+            traceUrl.hash ||
+            !traceUrl.pathname.startsWith("/traces/") ||
+            !uuid.test(traceUrl.pathname.slice(8)))
+            invalidResponse();
+        const queryNames = [];
+        traceUrl.searchParams.forEach((value, name) => {
+            if (!["projectId", "organizationId"].includes(name) ||
+                queryNames.includes(name) ||
+                !uuid.test(value))
+                invalidResponse();
+            queryNames.push(name);
+        });
+        if (queryNames.length !== 2)
+            invalidResponse();
+    }
     const matched = value.matchedSpanIds, missing = value.missingSpanIds;
     if (!Array.isArray(matched) ||
         !Array.isArray(missing) ||
@@ -128,6 +146,13 @@ async function pause(milliseconds, signal) {
 }
 /** Observe persisted evidence after the application and its exporter have finished. */
 export async function verifyTrace(connection, traceId, options = {}) {
+    return verifyTraceAtPath(connection, traceId, options, false, fetch);
+}
+/** @internal Dedicated receipt path for setup credentials; ordinary clients stay unchanged. */
+export async function verifySetupTrace(connection, traceId, options, fetcher, signal) {
+    return verifyTraceAtPath(connection, traceId, options, true, fetcher, signal);
+}
+async function verifyTraceAtPath(connection, traceId, options, setup, fetcher, signal) {
     if (!validId(traceId, 32))
         throw new TypeError("traceId must be a nonzero lowercase 32-character OpenTelemetry trace ID");
     if (options === null || typeof options !== "object" || Array.isArray(options))
@@ -148,27 +173,28 @@ export async function verifyTrace(connection, traceId, options = {}) {
         throw new TypeError("timeoutMillis must be greater than zero and at most 60000");
     // Snapshot caller arrays so concurrent mutation cannot alter the verification criteria.
     const expectedIds = [...expected], requiredFields = [...required];
-    const url = new URL(`/api/v1/traces/${traceId}/receipt`, connection.baseUrl);
+    const url = new URL(`/api/v1/${setup ? "setup/" : ""}traces/${traceId}/receipt`, connection.baseUrl);
     for (const id of expectedIds)
         url.searchParams.append("expectedSpanId", id);
     const controller = new AbortController();
     const deadline = performance.now() + timeout;
     const timer = setTimeout(() => controller.abort(), timeout);
+    const requestSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
     let receipt = null;
     let delay = 250;
     try {
-        while (!controller.signal.aborted && performance.now() < deadline) {
-            const response = await fetch(url, {
+        while (!requestSignal.aborted && performance.now() < deadline) {
+            const response = await fetcher(url, {
                 headers: { Authorization: `Bearer ${connection.apiKey}`, Accept: "application/json" },
                 redirect: "manual",
                 credentials: "omit",
                 cache: "no-store",
-                signal: controller.signal,
+                signal: requestSignal,
             });
             let retryAfter = 0;
             if (response.status === 200) {
-                receipt = parseReceipt(await readJson(response), traceId, expectedIds, url.origin);
-                if (!controller.signal.aborted &&
+                receipt = parseReceipt(await readJson(response), traceId, expectedIds, url.origin, setup);
+                if (!requestSignal.aborted &&
                     performance.now() < deadline &&
                     receipt.missingSpanIds.length === 0 &&
                     requiredFields.every((field) => receipt.fields[field]))
@@ -195,7 +221,7 @@ export async function verifyTrace(connection, traceId, options = {}) {
             if (remaining <= 0)
                 break;
             const wait = Math.max(delay, retryAfter);
-            await pause(Math.min(wait, remaining), controller.signal);
+            await pause(Math.min(wait, remaining), requestSignal);
             // A truncated backoff exhausts this call even if a timer wakes just early.
             if (wait >= remaining)
                 break;
@@ -203,6 +229,8 @@ export async function verifyTrace(connection, traceId, options = {}) {
         }
     }
     catch (error) {
+        if (signal?.aborted)
+            throw new Error("Setup interrupted");
         if (!controller.signal.aborted && performance.now() < deadline) {
             if (error instanceof HueTraceVerificationError)
                 throw error;

package/dist/setup/application.d.ts

@@ -0,0 +1,74 @@
+import type { SetupFileChange } from "./configure.js";
+import { type FileSetupInstallationStore, type SetupInstallationRecord, type SetupStoredApplicationEvidence } from "./installation.js";
+import type { SetupProjectDetection } from "./types.js";
+/** Closed automatic application matrix; other projects require an explicit agent-owned integration. */
+export type SetupApplicationPlan = {
+    /** JavaScript or TypeScript application using the shared TypeScript SDK. */
+    language: "typescript";
+    /** Package manager selected from the project's manifest and lockfile. */
+    manager: "bun" | "npm";
+    /** Recognized HTTP framework. */
+    framework: "express";
+    /** Runtime named by the recognized start script; defaults to Node when omitted. */
+    runtime?: "node" | "bun";
+    /** Whether the start script explicitly enables Node source maps. */
+    sourceMaps?: boolean;
+    /** Validated project-relative application entrypoint. */
+    entrypoint: string;
+    /** One literal loopback HTTP pathname selected for the application request. */
+    requestPath: string;
+    /** SHA-256 of the source inspected during planning. */
+    entryDigest: string;
+} | {
+    /** Python application using the Python SDK. */
+    language: "python";
+    /** Environment manager for the supported Python application. */
+    manager: "uv";
+    /** Recognized HTTP framework. */
+    framework: "flask";
+    /** Supported project-relative Flask entrypoint. */
+    entrypoint: "app.py";
+    /** One literal loopback HTTP pathname selected for the application request. */
+    requestPath: string;
+    /** SHA-256 of the source inspected during planning. */
+    entryDigest: string;
+};
+/** Stable reason an automatic application integration is not safe. */
+export declare class SetupApplicationActionRequired extends Error {
+    /** Stable reason the caller must resolve before automatic integration continues. */
+    readonly code: "ambiguous-project" | "unsupported-manager" | "unsupported-framework" | "ambiguous-entrypoint" | "custom-instrumentation";
+    constructor(
+    /** Stable reason the caller must resolve before automatic integration continues. */
+    code: "ambiguous-project" | "unsupported-manager" | "unsupported-framework" | "ambiguous-entrypoint" | "custom-instrumentation", message: string);
+}
+/** Fixed argv execution boundary used for package managers and application entrypoints. */
+export interface SetupCommand {
+    /** Fixed executable name or runtime path; never evaluated by a shell. */
+    command: string;
+    /** Explicit argument vector supplied to the executable. */
+    args: string[];
+    /** Selected application's working directory. */
+    cwd: string;
+    /** Optional child environment; values are never included in command output. */
+    env?: NodeJS.ProcessEnv;
+    /** Maximum elapsed execution time before termination. */
+    timeoutMillis: number;
+}
+/** Executes a fixed argv without a shell and returns only its status. */
+export type SetupCommandRunner = (command: SetupCommand) => Promise<void>;
+/** Statically recognizes the deliberately narrow automatic matrix without executing project code. */
+export declare function planSetupApplication(project: SetupProjectDetection): Promise<SetupApplicationPlan>;
+/** Default command runner: fixed argv, no shell, bounded output and deadline. */
+export declare function runSetupCommand(input: SetupCommand): Promise<void>;
+/** Installs the exact runtime with the detected owner of the project's manifest and lockfile. */
+export declare function installSetupRuntime(project: SetupProjectDetection, plan: SetupApplicationPlan, runner?: SetupCommandRunner): Promise<boolean>;
+/** Adds only two owned wiring blocks around an existing app object; business logic is untouched. */
+export declare function wireSetupApplication(store: FileSetupInstallationStore, record: SetupInstallationRecord, plan: SetupApplicationPlan): Promise<SetupFileChange | undefined>;
+/** Starts the existing entrypoint without a shell and exercises one existing HTTP GET route. */
+export declare function exerciseSetupApplication(store: FileSetupInstallationStore, record: SetupInstallationRecord, plan: SetupApplicationPlan, signal?: AbortSignal, deadlines?: {
+    readinessMillis: number;
+    requestMillis: number;
+    evidenceMillis: number;
+    /** Internal loopback test seam; the public CLI always chooses a random port. */
+    port?: number;
+}): Promise<SetupStoredApplicationEvidence>;