@hue-run/sdk 0.3.2 → 0.4.1

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>;