@hue-run/sdk 0.3.2 → 0.4.1

package/dist/setup/checkpoint.js

@@ -1,14 +1,82 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { chmod, lstat, mkdir, open, realpath, rename } from "node:fs/promises";
+import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 const MAX_CHECKPOINT_BYTES = 256 * 1024;
-const STEPS = ["detect-project", "configure-telemetry", "verify-receipt", "claim-project"];
+const STEPS = [
+    "detect-project",
+    "install-runtime",
+    "configure-telemetry",
+    "verify-application-receipt",
+    "claim-project",
+];
+const LEGACY_STEPS = [
+    "detect-project",
+    "configure-telemetry",
+    "verify-receipt",
+    "claim-project",
+];
 function isInside(parent, child) {
     const path = relative(parent, child);
     return path === "" || (!path.startsWith("..") && !isAbsolute(path));
 }
+async function cleanupCheckpointTemporary(path) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function privateDirectory(root, project, enforcePermissions) {
+    const ancestors = [];
+    let current = root;
+    for (;;) {
+        ancestors.unshift(current);
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    for (const path of ancestors) {
+        let info;
+        try {
+            info = await lstat(path);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            // Earlier ancestors have all been inspected. Never recursively follow an
+            // unchecked ancestor into the project or a different owner's directory.
+            await mkdir(path, { mode: 0o700 });
+            info = await lstat(path);
+        }
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw new Error("Setup checkpoint ancestors must be directories without symlinks");
+    }
+    const actual = await realpath(root);
+    if (actual !== root || isInside(project, actual))
+        throw new Error("Setup checkpoints must be outside the project repository");
+    if (enforcePermissions) {
+        const handle = await open(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            await handle.chmod(0o700);
+            const opened = await handle.stat();
+            const current = await lstat(root);
+            if (!current.isDirectory() ||
+                current.isSymbolicLink() ||
+                current.dev !== opened.dev ||
+                current.ino !== opened.ino ||
+                (opened.mode & 0o077) !== 0)
+                throw new Error("Setup checkpoint directory changed during inspection");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
 export function defaultSetupStateDirectory(env = process.env) {
     if (platform() === "darwin")
         return join(homedir(), "Library", "Application Support", "Hue", "setup");
@@ -73,8 +141,8 @@ function validState(value, runId, projectRoot) {
         typeof plan === "object" &&
         !Array.isArray(plan) &&
         hasExactKeys(plan, ["steps", "mutatesProject", "backendRequired"]) &&
-        JSON.stringify(plan.steps) === JSON.stringify(STEPS) &&
-        plan.mutatesProject === false &&
+        [JSON.stringify(STEPS), JSON.stringify(LEGACY_STEPS)].includes(JSON.stringify(plan.steps)) &&
+        plan.mutatesProject === true &&
         plan.backendRequired === true);
 }
 export class FileSetupCheckpointAdapter {
@@ -94,24 +162,7 @@ export class FileSetupCheckpointAdapter {
         const project = await realpath(projectRoot);
         if (isInside(project, root))
             throw new Error("Setup checkpoints must be outside the project repository");
-        let info;
-        try {
-            info = await lstat(root);
-        }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                throw error;
-            await mkdir(root, { recursive: true, mode: 0o700 });
-            info = await lstat(root);
-        }
-        if (!info.isDirectory() || info.isSymbolicLink())
-            throw new Error("Setup checkpoint directory must be private (mode 0700, no symlink)");
-        if (this.enforcesPosixPermissions) {
-            await chmod(root, 0o700);
-            info = await lstat(root);
-            if ((info.mode & 0o077) !== 0)
-                throw new Error("Setup checkpoint directory must be private (mode 0700, no symlink)");
-        }
+        await privateDirectory(root, project, this.enforcesPosixPermissions);
         return join(root, `${runId}.json`);
     }
     async load(runId, projectRoot) {
@@ -124,7 +175,7 @@ export class FileSetupCheckpointAdapter {
                     throw new Error("Unsafe setup checkpoint symlink");
             }
             const noFollow = this.runtimePlatform === "win32" ? 0 : constants.O_NOFOLLOW;
-            handle = await open(path, constants.O_RDONLY | noFollow);
+            handle = await open(path, constants.O_RDONLY | noFollow | constants.O_NONBLOCK);
         }
         catch (error) {
             if (error.code === "ENOENT")
@@ -148,6 +199,9 @@ export class FileSetupCheckpointAdapter {
                 throw new Error("Setup checkpoint integrity check failed");
             if (!validState(state, runId, await realpath(projectRoot)))
                 throw new Error("Setup checkpoint identity or shape does not match this project");
+            if (state.phase === "local-ready" &&
+                JSON.stringify(state.plan.steps) === JSON.stringify(LEGACY_STEPS))
+                return { ...state, plan: { ...state.plan, steps: [...STEPS] } };
             return state;
         }
         finally {
@@ -155,26 +209,42 @@ export class FileSetupCheckpointAdapter {
         }
     }
     async save(state) {
+        if (!validState(state, state.runId, await realpath(state.projectRoot)))
+            throw new Error("Invalid setup checkpoint state");
         const path = await this.pathFor(state.runId, state.projectRoot);
         const encoded = `${JSON.stringify({ state, digest: digest(state) })}\n`;
         if (Buffer.byteLength(encoded) > MAX_CHECKPOINT_BYTES)
             throw new Error("Setup checkpoint exceeds 256 KiB");
         const temporary = join(dirname(path), `.${state.runId}.${randomUUID()}.tmp`);
-        const handle = await open(temporary, "wx", 0o600);
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
         try {
-            await handle.writeFile(encoded);
-            await handle.sync();
+            try {
+                await handle.writeFile(encoded);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await this.pathFor(state.runId, state.projectRoot);
+            try {
+                const existing = await lstat(path);
+                if (existing.isSymbolicLink() || !existing.isFile())
+                    throw new Error("Unsafe setup checkpoint target");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            await rename(temporary, path);
         }
         finally {
-            await handle.close();
+            await cleanupCheckpointTemporary(temporary);
         }
-        await rename(temporary, path);
         // Windows cannot open a directory as a file handle for fsync. The atomic rename and
         // per-user state directory still provide resumability there; POSIX additionally fsyncs
         // the containing directory so the rename survives a sudden interruption.
         if (this.runtimePlatform !== "win32") {
-            await chmod(path, 0o600);
-            const directory = await open(dirname(path), "r");
+            const directory = await open(dirname(path), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
             try {
                 await directory.sync();
             }

package/dist/setup/cli.js

@@ -2,6 +2,7 @@
 import { realpath } from "node:fs/promises";
 import { parseArgs } from "node:util";
 import { FileSetupCheckpointAdapter, setupRunId } from "./checkpoint.js";
+import { SetupBackendAdapter } from "./backend.js";
 import { detectSetupProject } from "./detect.js";
 import { renderHumanEvent, renderJsonlEvent, renderPlainEvent, selectSetupOutputMode, } from "./render.js";
 import { runSetup } from "./runner.js";
@@ -28,13 +29,15 @@ async function main() {
                 agent: { type: "boolean", default: false },
                 format: { type: "string" },
                 project: { type: "string" },
+                origin: { type: "string" },
+                restart: { type: "boolean", default: false },
                 help: { type: "boolean", short: "h", default: false },
             },
         });
     }
     catch {
         if (!agentRequested) {
-            process.stderr.write("Usage: hue <setup|resume|status|claim> [--agent|--format plain|jsonl] [--project PATH]\n");
+            process.stderr.write("Usage: hue <setup|resume|status|claim> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
             return 2;
         }
         const event = {
@@ -65,7 +68,7 @@ async function main() {
             process.stdout.write(`${renderJsonlEvent(event)}\n`);
             return 2;
         }
-        process.stdout.write("Usage: hue <setup|resume|status|claim> [--agent|--format plain|jsonl] [--project PATH]\n");
+        process.stdout.write("Usage: hue <setup|resume|status|claim> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
         return 0;
     }
     const command = parsed.positionals[0];
@@ -75,7 +78,14 @@ async function main() {
         !commands.has(command) ||
         parsed.positionals.length !== 1 ||
         !validFormat ||
-        (parsed.values.agent && format !== undefined && format !== "jsonl")) {
+        (parsed.values.agent && format !== undefined && format !== "jsonl") ||
+        (parsed.values.restart &&
+            (command !== "claim" ||
+                parsed.values.agent ||
+                format === "plain" ||
+                format === "jsonl" ||
+                !process.stdin.isTTY ||
+                !process.stdout.isTTY))) {
         if (parsed.values.agent) {
             const event = {
                 contractVersion: SETUP_EVENT_CONTRACT_VERSION,
@@ -90,7 +100,7 @@ async function main() {
             process.stdout.write(`${renderJsonlEvent(event)}\n`);
         }
         else
-            process.stderr.write("Usage: hue <setup|resume|status|claim> [--agent|--format plain|jsonl] [--project PATH]\n");
+            process.stderr.write("Usage: hue <setup|resume|status|claim> [--agent|--format human|plain|jsonl] [--project PATH] [--origin URL] [--restart]\n");
         return 2;
     }
     const mode = selectSetupOutputMode({
@@ -107,6 +117,10 @@ async function main() {
     process.once("SIGTERM", interrupt);
     try {
         const root = await realpath(parsed.values.project ?? process.cwd());
+        const backend = new SetupBackendAdapter({
+            projectRoot: root,
+            ...(parsed.values.origin ? { origin: parsed.values.origin } : {}),
+        });
         await runSetup({
             command: command,
             mode,
@@ -114,6 +128,8 @@ async function main() {
             projectRoot: root,
             project: { detect: detectSetupProject },
             checkpoints: new FileSetupCheckpointAdapter(),
+            backend,
+            claimRestart: parsed.values.restart,
             signal: controller.signal,
             emit: (event) => {
                 if (event.event === "run.completed" || event.event === "run.failed")

package/dist/setup/configure.d.ts

@@ -0,0 +1,13 @@
+import type { SetupProjectDetection } from "./types.js";
+import { type FileSetupInstallationStore, type SetupInstallationRecord } from "./installation.js";
+/** A secret-free managed integration file created or replaced by setup. */
+export interface SetupFileChange {
+    /** Project-relative managed file path. */
+    path: string;
+    /** Safe write performed during this invocation. */
+    change: "created" | "updated";
+}
+/** Refuses credential/config conflicts before setup makes a provisioning request. */
+export declare function validateSetupConfiguration(store: FileSetupInstallationStore, record: Pick<SetupInstallationRecord, "managedFiles"> | undefined, project: SetupProjectDetection): Promise<void>;
+/** Writes only secret-free, metadata-only integration modules and never executes project code. */
+export declare function configureSetupProject(store: FileSetupInstallationStore, record: SetupInstallationRecord, project: SetupProjectDetection): Promise<SetupFileChange[]>;