@isomorph.ai/cli 0.2.0

package/dist/packages/harbour-cli/src/local-runtime.js

@@ -0,0 +1,526 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import { dirname, join, relative, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import EmbeddedPostgres from "embedded-postgres";
+import { kitPaths, projectName } from "./kit.js";
+import { CliError } from "./output.js";
+export function nodePackageCommand(tool, args, platform = process.platform, execPath = process.execPath) {
+    if (platform !== "win32")
+        return { command: tool, args };
+    return { command: execPath, args: [win32.join(win32.dirname(execPath), "node_modules", "npm", "bin", `${tool}-cli.js`), ...args] };
+}
+export const runCommand = (command, args, options = {}) => new Promise(resolve => {
+    const child = spawn(command, args, { cwd: options.cwd, env: { ...process.env, ...options.env }, stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", chunk => { stdout += chunk; });
+    child.stderr?.on("data", chunk => { stderr += chunk; if (!options.quiet)
+        process.stderr.write(chunk); });
+    child.on("error", error => resolve({ code: 127, stdout, stderr: `${stderr}${error.message}` }));
+    child.on("close", code => resolve({ code: code ?? 1, stdout, stderr }));
+    if (options.stdin !== undefined) {
+        child.stdin?.end(options.stdin);
+    }
+});
+const runWindowsController = (command, args) => new Promise(resolve => {
+    const child = spawn(command, args, { stdio: "ignore", windowsHide: true });
+    child.on("error", () => resolve(127));
+    child.on("close", code => resolve(code ?? 1));
+});
+export const LOCAL = {
+    tenant: "local-tenant",
+    app: "local-app",
+    userId: "local-user",
+    email: "local-user@example.test",
+    /** The second signed-in person of every local session: what a cross-user check runs as. */
+    secondUserId: "local-teammate",
+    secondEmail: "teammate@example.test",
+    database: "harbour",
+    dbUser: "harbour",
+    dbPassword: "harbour-local",
+    bucket: "harbour-local",
+    gatewayRole: "harbour_app_gateway"
+};
+/**
+ * App Gateway configuration in the shape cmd/appgateway/main.go decodes (unknown fields are rejected there).
+ * `localSession` is what makes the gateway the whole local runtime: issuer = its own published origin (the
+ * tokens' `iss`), no jwksUrl (the keys are in-process), the session's bucket, users and state files.
+ */
+export function gatewayConfig(project, ports, stateDir) {
+    return {
+        listen: ":8080",
+        issuer: `http://127.0.0.1:${ports.gateway}`,
+        environment: "development",
+        publicBaseUrl: `http://127.0.0.1:${ports.origin}`,
+        // `unrestrictedFiles` with no filePolicies is the local cell's file policy.
+        bindings: [{
+                tenant: LOCAL.tenant,
+                app: LOCAL.app,
+                databaseUrl: internalDatabaseUrl(LOCAL.gatewayRole),
+                bucket: LOCAL.bucket,
+                prefix: `${LOCAL.tenant}/${LOCAL.app}/development/`,
+                publicBaseUrl: `http://127.0.0.1:${ports.minio}/${LOCAL.bucket}`,
+                capabilities: ["data", "files", "realtime", "telemetry"],
+                filePolicies: [],
+                unrestrictedFiles: true
+            }],
+        localSession: {
+            session: project, tenant: LOCAL.tenant, app: LOCAL.app, userId: LOCAL.userId, email: LOCAL.email,
+            secondUserId: LOCAL.secondUserId, secondEmail: LOCAL.secondEmail,
+            metadataFile: "/state/session.json", envFile: "/state/session.env", displayDirectory: stateDir,
+            migrationsDir: "/state/migrations", realtimeOutboxFile: "/state/realtime-outbox.sql",
+            bucket: LOCAL.bucket
+        }
+    };
+}
+export function nativeGatewayConfig(project, ports, stateDir) {
+    const config = gatewayConfig(project, ports, stateDir);
+    config.listen = `127.0.0.1:${ports.gateway}`;
+    config.bindings[0] = {
+        ...config.bindings[0],
+        databaseUrl: `postgresql://${LOCAL.gatewayRole}:${LOCAL.dbPassword}@127.0.0.1:${ports.postgres}/${LOCAL.database}?sslmode=disable`,
+        publicBaseUrl: `http://127.0.0.1:${ports.origin}`,
+        localFilesDirectory: join(stateDir, "files")
+    };
+    config.localSession = {
+        ...config.localSession,
+        metadataFile: join(stateDir, "session.json"), envFile: join(stateDir, "session.env"),
+        migrationsDir: join(stateDir, "migrations"), realtimeOutboxFile: join(stateDir, "realtime-outbox.sql")
+    };
+    return config;
+}
+/** `migrations/*.sql` in name order — what `isomorph dev` applies and what the fixture derives the outbox from. */
+async function migrationNames(root) {
+    return (await readdir(join(root, "migrations")).catch(() => [])).filter(name => name.endsWith(".sql")).sort();
+}
+export function internalDatabaseUrl(user = LOCAL.dbUser) { return `postgresql://${user}:${LOCAL.dbPassword}@127.0.0.1/${LOCAL.database}?sslmode=disable`; }
+function uploadKey(project) { return createHash("sha256").update(`upload-key:${project}`).digest("base64"); }
+// ---- Ports and lock ------------------------------------------------------------------
+export async function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => { const address = server.address(); server.close(() => typeof address === "object" && address ? resolve(address.port) : reject(new Error("no port"))); });
+    });
+}
+export async function allocatePorts() {
+    const [postgres, minio, gateway, vite, origin] = await Promise.all([freePort(), freePort(), freePort(), freePort(), freePort()]);
+    return { postgres: postgres, minio: minio, gateway: gateway, vite: vite, origin: origin };
+}
+/** Acquires `.isomorph/local/dev.lock`; a lock whose process is gone is stale and replaced. */
+export async function acquireDevLock(root, ports, isAlive = pidAlive) {
+    const existing = await readDevLock(root);
+    if (existing && existing.pid !== process.pid && isAlive(existing.pid))
+        throw new CliError("DEV_ALREADY_RUNNING", `isomorph dev is already running for this app (pid ${existing.pid}, ${existing.origin}). Run \`isomorph stop\` first.`);
+    const lock = { pid: process.pid, startedAt: new Date().toISOString(), ports, origin: `http://127.0.0.1:${ports.origin}` };
+    await mkdir(kitPaths(root).local, { recursive: true });
+    await writeFile(kitPaths(root).devLock, JSON.stringify(lock));
+    return lock;
+}
+export async function readDevLock(root) {
+    try {
+        return JSON.parse(await readFile(kitPaths(root).devLock, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function releaseDevLock(root) { await rm(kitPaths(root).devLock, { force: true }); }
+/** The running dev origin for this app, if its lock holder is alive. */
+export async function runningOrigin(root, isAlive = pidAlive) {
+    const lock = await readDevLock(root);
+    return lock && isAlive(lock.pid) ? lock.origin : undefined;
+}
+export function pidAlive(pid) { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch {
+    return false;
+} }
+// ---- Native lifecycle -----------------------------------------------------------------
+export class LocalRuntime {
+    root;
+    run;
+    project;
+    postgres;
+    windowsPgCtl;
+    gateway;
+    gates = new Map();
+    gateOutput = new Map();
+    ports;
+    binary;
+    constructor(root, run = runCommand, project = projectName(root)) {
+        this.root = root;
+        this.run = run;
+        this.project = project;
+    }
+    async writeFiles(bundle, ports) {
+        const paths = kitPaths(this.root);
+        await mkdir(paths.state, { recursive: true });
+        this.ports = ports;
+        await writeFile(join(paths.state, "app-gateway.json"), `${JSON.stringify(nativeGatewayConfig(this.project, ports, paths.state), null, 2)}\n`);
+        // The gateway derives the realtime outbox from the app's migrations; they
+        // are staged into the state dir (already mounted at /state) rather than
+        // bind-mounting migrations/, which Docker would create as root if absent.
+        const staged = join(paths.state, "migrations");
+        await rm(staged, { recursive: true, force: true });
+        await mkdir(staged, { recursive: true });
+        for (const name of await migrationNames(this.root))
+            await copyFile(join(this.root, "migrations", name), join(staged, name));
+        await rm(join(paths.state, "realtime-outbox.sql"), { force: true });
+        // Session credentials are signed by the gateway process that is about to
+        // start. Leaving the previous process's files here lets sessionEnv return
+        // before the new gateway publishes its keys, so the browser receives a
+        // token the new gateway cannot verify after stop/start.
+        await rm(join(paths.state, "session.env"), { force: true });
+        await rm(join(paths.state, "session.json"), { force: true });
+    }
+    /**
+     * Pulls the pinned images before `up`, so a registry problem is named as such
+     * rather than surfacing as a failed start. Every kit image is a public
+     * `repository@sha256:<digest>` reference: no registry login is needed and
+     * a tag can never substitute other bytes.
+     */
+    async pull(bundle) {
+        this.binary = process.env.ISOMORPH_APP_GATEWAY_BINARY || await ensureNativeGateway(this.root, bundle);
+        const result = await this.run(this.binary, ["--help"], { quiet: true });
+        if (result.code === 127)
+            throw new CliError("KIT_RUNTIME_UNAVAILABLE", "The native Isomorph runtime could not be started. Reinstall the current Isomorph CLI.");
+    }
+    /** Attach a one-shot command to the native services owned by a running dev process. */
+    async attach(bundle, ports) {
+        this.ports = ports;
+        await this.pull(bundle);
+    }
+    /**
+     * `compose up`. When Docker's bridge address pool is full (each Isomorph
+     * project holds one network), the stopped projects of other app roots are
+     * brought down — networks freed, data volumes kept — and `up` is retried
+     * once; a pool still full after that is reported with the remedies only the
+     * person can apply, never as a generic "could not start".
+     */
+    async up(output) {
+        if (!this.ports)
+            throw new CliError("LOCAL_RUNTIME_FAILED", "The local runtime was not prepared.");
+        const paths = kitPaths(this.root);
+        const postgresBinaries = await hydrateEmbeddedPostgres(this.run);
+        const postgresMessages = [];
+        this.postgres = new EmbeddedPostgres({ databaseDir: join(paths.state, "postgres"), port: this.ports.postgres, user: LOCAL.dbUser, password: LOCAL.dbPassword, persistent: true, onLog: message => postgresMessages.push(String(message).trim()), onError: error => postgresMessages.push(String(error)) });
+        try {
+            if (!(await readdir(join(paths.state, "postgres")).catch(() => [])).length)
+                await this.postgres.initialise();
+            output?.("Local database files are ready.");
+            if (process.platform === "win32") {
+                this.windowsPgCtl = postgresBinaries.pg_ctl;
+                const started = await runWindowsController(this.windowsPgCtl, ["start", "-w", "-D", join(paths.state, "postgres"), "-l", join(paths.state, "postgres.log"), "-o", `-p ${this.ports.postgres}`]);
+                if (started !== 0)
+                    throw new Error(`pg_ctl could not start Postgres (exit ${started})`);
+            }
+            else {
+                await this.postgres.start();
+            }
+            output?.("Local database is running.");
+        }
+        catch (error) {
+            const detail = postgresMessages.filter(Boolean).slice(-3).join(" ") || (error instanceof Error ? error.message : String(error));
+            throw new CliError("LOCAL_RUNTIME_FAILED", `Local Postgres could not start${detail ? `: ${detail}` : "."}`);
+        }
+        const root = this.postgres.getPgClient("postgres", "127.0.0.1");
+        try {
+            await root.connect();
+            await root.query(`CREATE DATABASE ${LOCAL.database}`).catch(error => { if (!String(error).includes("already exists"))
+                throw error; });
+        }
+        finally {
+            await root.end().catch(() => undefined);
+        }
+        output?.("Local app database is ready.");
+        const admin = this.postgres.getPgClient(LOCAL.database, "127.0.0.1");
+        await admin.connect();
+        await admin.query(`DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${LOCAL.gatewayRole}') THEN CREATE ROLE ${LOCAL.gatewayRole} LOGIN PASSWORD '${LOCAL.dbPassword}'; END IF; END $$;`);
+        await admin.end();
+        const binary = this.binary;
+        this.gateway = spawn(binary, [], { cwd: this.root, env: { ...process.env, HARBOUR_APP_GATEWAY_CONFIG_FILE: join(paths.state, "app-gateway.json"), HARBOUR_APP_GATEWAY_UPLOAD_KEY: uploadKey(this.project), AWS_EC2_METADATA_DISABLED: "true" }, stdio: ["ignore", "ignore", "pipe"] });
+        this.gateway.stderr?.on("data", chunk => process.stderr.write(chunk));
+    }
+    /**
+     * `isomorph stop` and Ctrl-C: the project's containers and network go, its
+     * volumes (the app's local data) stay; safe to repeat. `compose stop` alone
+     * kept the network, and ~31 stopped apps then exhausted Docker's address
+     * pool for every later `isomorph dev` and `isomorph check`.
+     */
+    async stop() { return { stopped: await this.down() }; }
+    /**
+     * Removes this project's containers and network, keeping its named volumes
+     * (the app's local data). What the kit gate uses for a session it started
+     * itself: `stop` would leave one Docker network per checked app behind,
+     * and Docker's address pools run out after a dozen or so ("all predefined
+     * address pools have been fully subnetted").
+     */
+    async down() {
+        this.gateway?.kill("SIGTERM");
+        for (const child of this.gates.values())
+            child.kill("SIGTERM");
+        if (this.windowsPgCtl) {
+            await runWindowsController(this.windowsPgCtl, ["stop", "-w", "-D", join(kitPaths(this.root).state, "postgres"), "-m", "fast"]);
+        }
+        else {
+            await this.postgres?.stop().catch(() => undefined);
+        }
+        return true;
+    }
+    /** Removes this project's containers and named volumes only. */
+    async reset(output) {
+        output("Deleting this app's local database and files.");
+        await this.down();
+        await rm(kitPaths(this.root).state, { recursive: true, force: true });
+    }
+    /** Applies `migrations/*.sql` in name order through psql inside the postgres container, after ensuring the runtime role. */
+    async migrate() {
+        const dir = join(this.root, "migrations");
+        const names = await migrationNames(this.root);
+        const psql = (sql) => this.psql(sql);
+        const role = await psql(`DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${LOCAL.gatewayRole}') THEN CREATE ROLE ${LOCAL.gatewayRole} LOGIN PASSWORD '${LOCAL.dbPassword}'; END IF; END $$;`);
+        if (role.code !== 0)
+            throw new CliError("MIGRATION_FAILED", "Could not prepare the local database role.");
+        for (const name of names) {
+            const result = await psql(await readFile(join(dir, name), "utf8"));
+            if (result.code !== 0)
+                throw new CliError("MIGRATION_FAILED", `Migration ${name} failed: ${result.stderr.trim().split("\n").at(-1) ?? "psql error"}`);
+        }
+        return names;
+    }
+    psql(sql) {
+        if (!this.postgres)
+            return Promise.resolve({ code: 1, stdout: "", stderr: "Postgres is not running" });
+        return (async () => {
+            const client = this.postgres.getPgClient(LOCAL.database, "127.0.0.1");
+            try {
+                await client.connect();
+                await client.query(sql);
+                return { code: 0, stdout: "", stderr: "" };
+            }
+            catch (error) {
+                return { code: 1, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                await client.end().catch(() => undefined);
+            }
+        })();
+    }
+    /**
+     * Starts the kit gate: the pinned gateway image's `gate` subcommand as a
+     * one-shot service of this project (`docker compose run`), the app mounted
+     * read-only at /workspace, its control listener published on `port`, the
+     * session's PostgreSQL and bucket named for its scratch database and files.
+     * Resolves to the container id; the caller drives the control API
+     * (check.ts) and stops it with stopGate.
+     */
+    async startGate(bundle, port, publicUrl) {
+        void bundle;
+        if (!this.ports)
+            throw new CliError("LOCAL_RUNTIME_FAILED", "The local runtime was not prepared.");
+        const id = `gate-${Date.now()}`;
+        const child = spawn(this.binary, ["gate"], { cwd: this.root, env: { ...process.env, HARBOUR_GATE_WORKSPACE: this.root, HARBOUR_GATE_LISTEN: `127.0.0.1:${port}`, HARBOUR_GATE_PUBLIC_URL: publicUrl, HARBOUR_GATE_DATABASE_URL: `postgresql://${LOCAL.dbUser}:${LOCAL.dbPassword}@127.0.0.1:${this.ports.postgres}/${LOCAL.database}?sslmode=disable`, HARBOUR_GATE_S3_BUCKET: LOCAL.bucket, HARBOUR_GATE_FILES_DIRECTORY: join(kitPaths(this.root).state, "gate-files") }, stdio: ["ignore", "ignore", "pipe"] });
+        this.gates.set(id, child);
+        child.stderr?.on("data", chunk => this.gateOutput.set(id, `${this.gateOutput.get(id) ?? ""}${chunk}`.slice(-4000)));
+        return id;
+    }
+    async gateRunning(container) {
+        const child = this.gates.get(container);
+        return Boolean(child && child.exitCode === null && !child.killed);
+    }
+    async gateLogs(container) {
+        return (this.gateOutput.get(container) || (this.gates.has(container) ? "native gate exited" : "native gate was not started")).trim().split("\n").slice(-20).join(" | ").slice(0, 3000);
+    }
+    async stopGate(container) {
+        this.gates.get(container)?.kill("SIGTERM");
+        this.gates.delete(container);
+        this.gateOutput.delete(container);
+    }
+    /**
+     * Applies the platform's realtime outbox migration the gateway generated
+     * for this app's tables (state/realtime-outbox.sql: the data plane's one
+     * generator, the same text the hosted pipeline appends to the app's
+     * bundle) — after the app's migrations, idempotent on every start. The
+     * gateway's in-process relay starts publishing once the table exists.
+     * Returns the number of watched tables; 0 when the app has no tables.
+     */
+    async installRealtimeOutbox() {
+        const path = join(kitPaths(this.root).state, "realtime-outbox.sql");
+        const sql = await readFile(path, "utf8").catch(() => "");
+        if (!sql.trim())
+            return 0;
+        const result = await this.psql(sql);
+        if (result.code !== 0)
+            throw new CliError("MIGRATION_FAILED", `The realtime outbox migration failed: ${result.stderr.trim().split("\n").at(-1) ?? "psql error"}`);
+        return (sql.match(/harbour_runtime\.watch_table\(/g) ?? []).length;
+    }
+    /**
+     * The gateway's session env — both signed identities under the pipeline's
+     * names (ISOMORPH_IDENTITY_CONTEXT, _HEADER, _SECOND_USER) — once the
+     * gateway has bound its listener and written it.
+     */
+    async sessionEnv(attempts = 60) {
+        const path = join(kitPaths(this.root).state, "session.env");
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            try {
+                const env = parseSessionEnv(await readFile(path, "utf8"));
+                if (env.ISOMORPH_IDENTITY_CONTEXT && env.ISOMORPH_IDENTITY_CONTEXT_SECOND_USER)
+                    return env;
+            }
+            catch { /* not written yet */ }
+            if (attempts > 1)
+                await new Promise(resolve => setTimeout(resolve, 500));
+        }
+        throw new CliError("LOCAL_RUNTIME_FAILED", "The local Isomorph gateway did not publish a session.");
+    }
+}
+async function hydrateEmbeddedPostgres(run) {
+    const packageName = embeddedPostgresPackage(process.platform, process.arch);
+    let entry;
+    try {
+        entry = fileURLToPath(import.meta.resolve(packageName));
+    }
+    catch {
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", `This Isomorph CLI does not include Postgres for ${process.platform}-${process.arch}.`);
+    }
+    const packageRoot = dirname(dirname(entry));
+    const script = join(packageRoot, "scripts", "hydrate-symlinks.js");
+    const result = await run(process.execPath, [script], { cwd: packageRoot, quiet: true });
+    if (result.code !== 0)
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", "The bundled Postgres files could not be prepared.");
+    const binaries = await import(packageName);
+    if (!binaries.pg_ctl)
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", "The bundled Postgres controller is missing.");
+    return { pg_ctl: binaries.pg_ctl };
+}
+export function embeddedPostgresPackage(platform, arch) {
+    return `@embedded-postgres/${platform === "win32" ? "windows" : platform}-${arch}`;
+}
+async function ensureNativeGateway(root, bundle) {
+    const runtime = nativeGatewayArtifact(bundle, process.platform, process.arch);
+    if (!runtime)
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", `This kit bundle has no native Isomorph runtime for ${process.platform}-${process.arch}.`);
+    const directory = join(kitPaths(root).local, "runtime");
+    const target = join(directory, `isomorph-app-gateway-${runtime.sha256.slice(0, 12)}${process.platform === "win32" ? ".exe" : ""}`);
+    if (!(await exists(target))) {
+        const bytes = await downloadSdk(runtime.url);
+        const digest = createHash("sha256").update(bytes).digest("hex");
+        if (digest !== runtime.sha256)
+            throw new CliError("KIT_BUNDLE_INCOMPATIBLE", `The native runtime digest ${digest} does not match the kit bundle ${runtime.sha256}.`);
+        await mkdir(directory, { recursive: true });
+        await writeFile(target, bytes, { mode: 0o755 });
+    }
+    return target;
+}
+export function nativeGatewayArtifact(bundle, platform, arch) {
+    if (platform === "darwin" && arch === "arm64")
+        return bundle.nativeRuntime?.darwinArm64;
+    if (platform === "linux" && arch === "x64")
+        return bundle.nativeRuntime?.linuxX64;
+    if (platform === "win32" && arch === "x64")
+        return bundle.nativeRuntime?.windowsX64;
+    return undefined;
+}
+/** The gateway writes a shell-sourceable file: `export KEY='value'`, a literal quote written as `'"'"'`. */
+export function parseSessionEnv(text) {
+    const env = {};
+    for (const line of text.split("\n")) {
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line.trim());
+        if (!match)
+            continue;
+        const raw = match[2];
+        env[match[1]] = raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2 ? raw.slice(1, -1).replace(/'"'"'/g, "'") : raw;
+    }
+    return env;
+}
+// ---- SDK tarball ---------------------------------------------------------------------------
+/**
+ * The SDK ships in the kit bundle, not the public registry. Stages the tarball
+ * named by ISOMORPH_KIT_SDK_TARBALL or downloaded from the manifest's sdk.url under
+ * `.isomorph/local/sdk/` (so package.json gets a relative `file:` dependency), checks
+ * its sha256 against the bundle and installs it with the app's other dependencies.
+ * Returns "present" when the staged tarball is already installed, "missing" when
+ * no tarball is available and node_modules lacks the package.
+ */
+export async function ensureSdk(root, bundle, env, run, output, fetchImpl = fetch) {
+    const installed = await readFile(join(root, "node_modules", ...bundle.sdk.package.split("/"), "package.json")).then(() => true, () => false);
+    const stageDir = join(kitPaths(root).local, "sdk");
+    const staged = join(stageDir, `isomorph-app-sdk-${bundle.sdk.tarballSha256.slice(0, 12)}.tgz`);
+    const source = env.ISOMORPH_KIT_SDK_TARBALL?.trim();
+    if (!(await exists(staged))) {
+        let bytes;
+        if (source)
+            bytes = await readFile(source).catch(() => { throw new CliError("SDK_UNAVAILABLE", `ISOMORPH_KIT_SDK_TARBALL is not readable: ${source}`); });
+        else if (bundle.sdk.url) {
+            output(`Downloading ${bundle.sdk.package} from the kit bundle (sha256 ${bundle.sdk.tarballSha256.slice(0, 12)}…).`);
+            bytes = await downloadSdk(bundle.sdk.url, fetchImpl);
+        }
+        if (!bytes)
+            return installed ? "present" : "missing";
+        const digest = createHash("sha256").update(bytes).digest("hex");
+        if (bundle.sdk.tarballSha256 !== "unknown" && digest !== bundle.sdk.tarballSha256)
+            throw new CliError("KIT_BUNDLE_INCOMPATIBLE", `The SDK tarball digest ${digest} does not match the kit bundle ${bundle.sdk.tarballSha256}. Run \`isomorph init --upgrade\` or use the matching tarball.`);
+        await mkdir(stageDir, { recursive: true });
+        await writeFile(staged, bytes);
+    }
+    else if (installed && (await readFile(join(root, "package.json"), "utf8").catch(() => "")).includes(relative(root, staged)))
+        return "present";
+    output(`Installing ${bundle.sdk.package} from the kit bundle.`);
+    const npm = nodePackageCommand("npm", ["install", "--no-audit", "--no-fund", relative(root, staged)]);
+    const result = await run(npm.command, npm.args, { cwd: root, quiet: true });
+    if (result.code !== 0)
+        throw new CliError("SDK_INSTALL_FAILED", `npm could not install the kit SDK tarball: ${result.stderr.trim().split("\n").at(-1) ?? "npm error"}`);
+    return "installed";
+}
+/**
+ * Fetches the SDK tarball from the bundle's `sdk.url`. The published bundle
+ * stores it as a content-addressed OCI blob on a public registry, which answers
+ * an anonymous GET with a Bearer challenge naming a token endpoint that hands
+ * out pull tokens without credentials; the challenge is followed once and the
+ * request repeated. Redirects (a blob served from object storage) are followed;
+ * the bearer token is not forwarded across origins by fetch itself. The caller
+ * verifies the bytes against `sdk.tarballSha256` — a token or a redirect can
+ * change where the bytes come from, never which bytes are accepted.
+ */
+export async function downloadSdk(url, fetchImpl = fetch) {
+    if (!/^https:\/\//.test(url))
+        throw new CliError("SDK_UNAVAILABLE", `The kit bundle's sdk.url must be https: ${url}`);
+    const attempt = (headers = {}) => fetchImpl(url, { redirect: "follow", headers }).catch(error => { throw new CliError("SDK_UNAVAILABLE", `The kit SDK tarball could not be downloaded from ${url}: ${error instanceof Error ? error.message : String(error)}`); });
+    let response = await attempt();
+    if (response.status === 401) {
+        const challenge = parseBearerChallenge(response.headers.get("www-authenticate"));
+        if (challenge && /^https:\/\//.test(challenge.realm)) {
+            const tokenUrl = new URL(challenge.realm);
+            if (challenge.service)
+                tokenUrl.searchParams.set("service", challenge.service);
+            if (challenge.scope)
+                tokenUrl.searchParams.set("scope", challenge.scope);
+            const tokenResponse = await fetchImpl(tokenUrl, { redirect: "follow" }).catch(() => undefined);
+            const body = tokenResponse?.ok ? await tokenResponse.json().catch(() => undefined) : undefined;
+            const token = typeof body?.token === "string" ? body.token : typeof body?.access_token === "string" ? body.access_token : undefined;
+            if (token)
+                response = await attempt({ authorization: `Bearer ${token}` });
+        }
+    }
+    if (!response.ok)
+        throw new CliError("SDK_UNAVAILABLE", `The kit SDK tarball could not be downloaded from ${url} (HTTP ${response.status}).`);
+    return new Uint8Array(await response.arrayBuffer());
+}
+/** `Bearer realm="…",service="…",scope="…"` (RFC 6750 / distribution token auth); anything else is no challenge. */
+export function parseBearerChallenge(header) {
+    if (!header || !/^\s*bearer\s/i.test(header))
+        return undefined;
+    const params = {};
+    for (const match of header.slice(header.search(/\s/)).matchAll(/([a-z_]+)="([^"]*)"/gi))
+        params[match[1].toLowerCase()] = match[2];
+    if (!params.realm)
+        return undefined;
+    return { realm: params.realm, service: params.service, scope: params.scope };
+}
+const exists = (path) => readFile(path).then(() => true, () => false);