@fourier-labs/harbour 0.1.33 → 0.1.34

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

@@ -2,11 +2,11 @@ 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 { join, relative } from "node:path";
-import { LOCAL_SERVICE_IMAGES } from "./kit-bundle.js";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import EmbeddedPostgres from "embedded-postgres";
 import { kitPaths, projectName } from "./kit.js";
 import { CliError } from "./output.js";
-import { HARBOUR_NETWORK_LABEL, isAddressPoolExhausted, poolExhaustedMessage, reclaimStaleHarbourProjects } from "./docker-networks.js";
 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 = "";
@@ -36,59 +36,6 @@ export const LOCAL = {
     s3Secret: "harbour-local-secret-key",
     gatewayRole: "harbour_app_gateway"
 };
-// ---- Compose ----------------------------------------------------------------------
-/**
- * Compose file for one project — three containers: Postgres, MinIO and one
- * Harbour process, the app gateway in local-session mode. Every port bound to
- * 127.0.0.1, named volumes prefixed with the project name, images pinned from
- * the bundle manifest. The gateway mints the session identities and serves
- * their JWKS itself, serves the provider fixtures beside its routes, relays
- * the realtime outbox in-process, and writes the session env (both identity
- * tokens) and the platform's realtime outbox migration (generated from the
- * app's migrations, staged under state/migrations) to the shared state dir
- * (data plane docs/local-kit.md).
- */
-export function composeFile(project, bundle, ports, stateDir) {
-    const images = bundle.images;
-    const originUrl = `http://127.0.0.1:${ports.origin}`;
-    return [
-        `name: ${project}`,
-        "services:",
-        "  postgres:",
-        `    image: ${images.postgres ?? LOCAL_SERVICE_IMAGES.postgres}`,
-        `    environment: { POSTGRES_USER: ${LOCAL.dbUser}, POSTGRES_PASSWORD: ${LOCAL.dbPassword}, POSTGRES_DB: ${LOCAL.database} }`,
-        `    ports: ["127.0.0.1:${ports.postgres}:5432"]`,
-        "    volumes: [postgres-data:/var/lib/postgresql/data]",
-        `    healthcheck: { test: ["CMD-SHELL", "pg_isready -U ${LOCAL.dbUser} -d ${LOCAL.database}"], interval: 2s, timeout: 3s, retries: 30 }`,
-        "  minio:",
-        `    image: ${images.minio ?? LOCAL_SERVICE_IMAGES.minio}`,
-        "    command: server /data",
-        `    environment: { MINIO_ROOT_USER: ${LOCAL.s3Key}, MINIO_ROOT_PASSWORD: ${LOCAL.s3Secret} }`,
-        `    ports: ["127.0.0.1:${ports.minio}:9000"]`,
-        "    volumes: [minio-data:/data]",
-        "    healthcheck: { test: [\"CMD-SHELL\", \"curl -sf http://127.0.0.1:9000/minio/health/ready || wget -qO- http://127.0.0.1:9000/minio/health/ready\"], interval: 2s, timeout: 3s, retries: 30 }",
-        "  gateway:",
-        `    image: ${images.appGateway}`,
-        "    environment:",
-        "      HARBOUR_APP_GATEWAY_CONFIG_FILE: /config/app-gateway.json",
-        "      HARBOUR_APP_GATEWAY_UPLOAD_KEY: " + uploadKey(project),
-        "      HARBOUR_S3_ENDPOINT: http://minio:9000",
-        `      HARBOUR_S3_PUBLIC_ENDPOINT: http://127.0.0.1:${ports.minio}`,
-        `      AWS_ACCESS_KEY_ID: ${LOCAL.s3Key}`,
-        `      AWS_SECRET_ACCESS_KEY: ${LOCAL.s3Secret}`,
-        "      AWS_REGION: us-east-1",
-        "      AWS_EC2_METADATA_DISABLED: \"true\"",
-        `    ports: ["127.0.0.1:${ports.gateway}:8080"]`,
-        `    volumes: ["${stateDir}/app-gateway.json:/config/app-gateway.json:ro", "${stateDir}:/state"]`,
-        "    depends_on: { postgres: { condition: service_healthy }, minio: { condition: service_healthy } }",
-        "volumes:",
-        `  postgres-data: { name: ${project}-postgres }`,
-        `  minio-data: { name: ${project}-minio }`,
-        ...networkLabelLines(),
-        `# Browser origin: ${originUrl}`,
-        ""
-    ].join("\n");
-}
 /**
  * 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
@@ -121,13 +68,27 @@ export function gatewayConfig(project, ports, stateDir) {
         }
     };
 }
+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 `harbour 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();
 }
-/** Marks the project's default network as Harbour's, so a full address pool can be healed by removing only what Harbour left behind (docker-networks.ts). */
-export function networkLabelLines() { return ["networks:", `  default: { labels: { ${HARBOUR_NETWORK_LABEL}: "1" } }`]; }
-export function internalDatabaseUrl(user = LOCAL.dbUser) { return `postgresql://${user}:${LOCAL.dbPassword}@postgres:5432/${LOCAL.database}?sslmode=disable`; }
+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() {
@@ -172,26 +133,27 @@ export function pidAlive(pid) { try {
 catch {
     return false;
 } }
-// ---- Compose lifecycle ----------------------------------------------------------------
+// ---- Native lifecycle -----------------------------------------------------------------
 export class LocalRuntime {
     root;
     run;
     project;
-    composePath;
-    constructor(root, run = runCommand, project = projectName(root), composePath = kitPaths(root).compose) {
+    postgres;
+    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;
-        this.composePath = composePath;
-    }
-    compose(args, options = {}) {
-        return this.run("docker", ["compose", "-p", this.project, "-f", this.composePath, ...args], { cwd: this.root, ...options });
     }
     async writeFiles(bundle, ports) {
         const paths = kitPaths(this.root);
         await mkdir(paths.state, { recursive: true });
-        await writeFile(paths.compose, composeFile(this.project, bundle, ports, paths.state));
-        await writeFile(join(paths.state, "app-gateway.json"), `${JSON.stringify(gatewayConfig(this.project, ports, paths.state), null, 2)}\n`);
+        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.
@@ -209,9 +171,10 @@ export class LocalRuntime {
      * a tag can never substitute other bytes.
      */
     async pull(bundle) {
-        const result = await this.compose(["pull", "--quiet"]);
-        if (result.code !== 0)
-            throw new CliError("KIT_IMAGES_UNAVAILABLE", `Docker could not pull the kit images (${bundle.images.appGateway}): ${result.stderr.trim().split("\n").at(-1) ?? "docker error"}. They are public and pinned by digest; \`docker compose\` (Compose v2) must be installed and Docker running with access to the registry.`);
+        this.binary = process.env.HARBOUR_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 Harbour runtime could not be started. Reinstall the current Harbour CLI.");
     }
     /**
      * `compose up`. When Docker's bridge address pool is full (each Harbour
@@ -221,16 +184,24 @@ export class LocalRuntime {
      * person can apply, never as a generic "could not start".
      */
     async up(output) {
-        let result = await this.compose(["up", "-d", "--wait"]);
-        if (result.code !== 0 && isAddressPoolExhausted(result.stderr)) {
-            const { reclaimed, running } = await reclaimStaleHarbourProjects(this.run, this.project, output);
-            if (reclaimed.length)
-                result = await this.compose(["up", "-d", "--wait"]);
-            if (result.code !== 0 && isAddressPoolExhausted(result.stderr))
-                throw new CliError("DOCKER_NETWORK_POOL_EXHAUSTED", poolExhaustedMessage(running));
-        }
-        if (result.code !== 0)
-            throw new CliError("LOCAL_RUNTIME_FAILED", "Docker could not start the local Harbour services. Is Docker running and are the kit images available (see .harbour/kit.lock.json)?");
+        void output;
+        if (!this.ports)
+            throw new CliError("LOCAL_RUNTIME_FAILED", "The local runtime was not prepared.");
+        const paths = kitPaths(this.root);
+        await hydrateEmbeddedPostgres(this.run);
+        this.postgres = new EmbeddedPostgres({ databaseDir: join(paths.state, "postgres"), port: this.ports.postgres, user: LOCAL.dbUser, password: LOCAL.dbPassword, persistent: true, onLog: () => undefined, onError: () => undefined });
+        if (!(await readdir(join(paths.state, "postgres")).catch(() => [])).length)
+            await this.postgres.initialise();
+        await this.postgres.start();
+        await this.postgres.createDatabase(LOCAL.database).catch(error => { if (!String(error).includes("already exists"))
+            throw error; });
+        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));
     }
     /**
      * `harbour stop` and Ctrl-C: the project's containers and network go, its
@@ -246,13 +217,17 @@ export class LocalRuntime {
      * and Docker's address pools run out after a dozen or so ("all predefined
      * address pools have been fully subnetted").
      */
-    async down() { return (await this.compose(["down", "--remove-orphans"], { quiet: true })).code === 0; }
+    async down() {
+        this.gateway?.kill("SIGTERM");
+        for (const child of this.gates.values())
+            child.kill("SIGTERM");
+        await this.postgres?.stop().catch(() => undefined);
+        return true;
+    }
     /** Removes this project's containers and named volumes only. */
     async reset(output) {
-        output(`Deleting local data for this app only: compose project ${this.project}, volumes ${this.project}-postgres and ${this.project}-minio.`);
-        const result = await this.compose(["down", "-v", "--remove-orphans"], { quiet: true });
-        if (result.code !== 0)
-            throw new CliError("LOCAL_RESET_FAILED", "Docker could not remove the local Harbour services for this app.");
+        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. */
@@ -271,7 +246,22 @@ export class LocalRuntime {
         return names;
     }
     psql(sql) {
-        return this.compose(["exec", "-T", "postgres", "psql", "-v", "ON_ERROR_STOP=1", "-U", LOCAL.dbUser, "-d", LOCAL.database], { stdin: sql, quiet: true });
+        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
@@ -282,28 +272,26 @@ export class LocalRuntime {
      * (check.ts) and stops it with stopGate.
      */
     async startGate(bundle, port, publicUrl) {
-        const result = await this.compose([
-            "run", "--detach", "--no-deps", "--rm", "--publish", `127.0.0.1:${port}:${port}`,
-            "--volume", `${this.root}:/workspace:ro`,
-            "--env", "HARBOUR_GATE_WORKSPACE=/workspace", "--env", `HARBOUR_GATE_LISTEN=:${port}`, "--env", `HARBOUR_GATE_PUBLIC_URL=${publicUrl}`,
-            "--env", `HARBOUR_GATE_DATABASE_URL=${internalDatabaseUrl()}`, "--env", `HARBOUR_GATE_S3_BUCKET=${LOCAL.bucket}`,
-            "gateway", "gate"
-        ], { quiet: true });
-        const id = result.code === 0 ? result.stdout.trim().split("\n").at(-1)?.trim() ?? "" : "";
-        if (!id)
-            throw new CliError("LOCAL_RUNTIME_FAILED", `Docker could not start the kit gate (${bundle.images.appGateway}): ${result.stderr.trim().split("\n").at(-1) ?? "docker error"}.`);
+        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 result = await this.run("docker", ["inspect", "--format", "{{.State.Running}}", container], { quiet: true });
-        return result.code === 0 && result.stdout.trim() === "true";
+        const child = this.gates.get(container);
+        return Boolean(child && child.exitCode === null && !child.killed);
     }
     async gateLogs(container) {
-        const result = await this.run("docker", ["logs", "--tail", "20", container], { quiet: true });
-        return `${result.stdout}${result.stderr}`.trim().split("\n").slice(-5).join(" | ").slice(0, 800);
+        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) {
-        await this.run("docker", ["rm", "-f", container], { quiet: true });
+        this.gates.get(container)?.kill("SIGTERM");
+        this.gates.delete(container);
+        this.gateOutput.delete(container);
     }
     /**
      * Applies the platform's realtime outbox migration the gateway generated
@@ -343,6 +331,37 @@ export class LocalRuntime {
         throw new CliError("LOCAL_RUNTIME_FAILED", "The local Harbour gateway did not publish a session.");
     }
 }
+async function hydrateEmbeddedPostgres(run) {
+    const packageName = `@embedded-postgres/${process.platform}-${process.arch}`;
+    let entry;
+    try {
+        entry = fileURLToPath(import.meta.resolve(packageName));
+    }
+    catch {
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", `This Harbour 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.");
+}
+async function ensureNativeGateway(root, bundle) {
+    const runtime = process.platform === "darwin" && process.arch === "arm64" ? bundle.nativeRuntime?.darwinArm64 : undefined;
+    if (!runtime)
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", `This kit bundle has no native Harbour runtime for ${process.platform}-${process.arch}.`);
+    const directory = join(kitPaths(root).local, "runtime");
+    const target = join(directory, `harbour-app-gateway-${runtime.sha256.slice(0, 12)}`);
+    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;
+}
 /** The three names the pipeline's retained-check runner exports for the signed identities, from a session env. */
 export function identityEnvironment(session) {
     return {

package/dist/packages/harbour-cli/src/productionise.js

@@ -1,23 +1,62 @@
 import { homedir } from "node:os";
-import { basename, parse, resolve } from "node:path";
-import { readdir, readFile } from "node:fs/promises";
+import { basename, dirname, parse, resolve } from "node:path";
+import { readdir, readFile, mkdir, rename, writeFile } from "node:fs/promises";
 import { scanWorkspace } from "../../../src/analyzer.js";
 import { createSourceManifest } from "../../../src/source-intake.js";
 import { structured } from "./remote-mcp-client.js";
 import { archiveForManifest, putMultipart } from "./upload.js";
 import { CliError } from "./output.js";
-import { follow, getAppSetup, pickSourceFailure, readLine } from "./operations.js";
+import { follow, getAppSetup, pickSourceFailure, readLine, fetchStatus, outcomeFor } from "./operations.js";
 import { CLI_VERSION } from "./version.js";
 import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
 import { assertAiReady, assertPreviewIntegrationsReady } from "./integrations.js";
-import { kitPaths, recordKitAppId, sourceDigest } from "./kit.js";
+import { kitPaths, readKitLock, recordKitAppId, sourceDigest } from "./kit.js";
 import { FLOW_CHECK, preflightKitGate, readReport } from "./check.js";
 export async function productionise(rootArg, client, output, tenantId, includePaths = [], options = {}) {
     const root = resolve(rootArg);
     output(`Harbour is checking ${basename(root)}.`);
     if (root === parse(root).root || root === resolve(homedir()))
         throw new CliError("PREFLIGHT_APP_ROOT", "The selected app boundary is unsafe.");
-    const graph = await scanWorkspace(root, { sourceBoundary: "root", ...(includePaths.length ? { includePaths } : {}) });
+    let pending = await readPending(root, tenantId, client.endpoint);
+    let prior;
+    if (pending) {
+        try {
+            prior = await fetchStatus(client, pending.operationRef);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw withOperation(error, pending.operationRef);
+            throw new CliError("OPERATION_STATUS_UNAVAILABLE", "Harbour could not read the existing operation. Continue it when the connection recovers; do not start another deployment.", pending.operationRef);
+        }
+        if (prior.operation?.stage === "failed" && pending.sourceDigest === (await sourceDigest(root)).digest)
+            throw intakeRejection(prior, pending.operationRef);
+        if (operationFinished(prior) && pending.sourceDigest !== (await sourceDigest(root)).digest)
+            pending = undefined;
+    }
+    else {
+        const appId = options.appId ?? (await readKitLock(root))?.appId;
+        if (appId) {
+            await client.initialize();
+            const recovered = structured(await client.call("harbour_get_operation_status", { appId }));
+            if (!recovered || !Object.hasOwn(recovered, "operation"))
+                throw new CliError("RECOVERY_UNAVAILABLE", "This company needs Harbour's deployment recovery update before shipping. No new deployment was started.");
+            if (recovered.operation?.operationId && !operationFinished(recovered)) {
+                prior = recovered;
+                pending = { tenantId, endpoint: client.endpoint, operationRef: recovered.operation.operationId, sourceDigest: (await sourceDigest(root)).digest, uploaded: Boolean(recovered.sourceSave || recovered.deployment || recovered.waiting || recovered.operation.stage === "awaiting-approval"), graph: await scanWorkspace(root, { sourceBoundary: "root", ...(includePaths.length ? { includePaths } : {}) }), appId };
+                await writePending(root, pending);
+            }
+        }
+    }
+    if (pending && (prior?.deployment || prior?.production || prior?.waiting || operationFinished(prior))) {
+        output("Harbour is continuing the existing operation; no new deployment was started.");
+        return finishDeployment(client, pending.operationRef, output, options);
+    }
+    if (pending && prior?.sourceSave)
+        pending.uploaded = true;
+    if (pending && !pending.uploaded && pending.sourceDigest !== (await sourceDigest(root)).digest) {
+        throw new CliError("UPLOAD_SOURCE_CHANGED", "The app changed before its upload finished. Restore the submitted files before continuing this operation.", pending.operationRef);
+    }
+    const graph = pending?.graph ?? await scanWorkspace(root, { sourceBoundary: "root", ...(includePaths.length ? { includePaths } : {}) });
     if (!graph.deploymentScope.includedFiles.length)
         throw new CliError("PREFLIGHT_EMPTY", "The selected app boundary contains no eligible files.");
     if (graph.deploymentScope.includedFiles.some(isProhibitedSecretPath))
@@ -29,21 +68,22 @@ export async function productionise(rootArg, client, output, tenantId, includePa
     // discovery — for a mismatch `harbour check` names locally in about five
     // seconds. Refuse here, before the tree is even read into memory, and long
     // before any grant lookup, database replay, operation or upload.
-    await assertChecksPassedForTree(root, output);
-    const files = await Promise.all(graph.deploymentScope.includedFiles.map(async (path) => ({ path, content: new Uint8Array(await readFile(resolve(root, path))) })));
-    output(`Harbour found ${files.length} app files.`);
+    if (!pending?.uploaded)
+        await assertChecksPassedForTree(root, output);
+    const files = pending?.uploaded ? [] : await Promise.all(graph.deploymentScope.includedFiles.map(async (path) => ({ path, content: new Uint8Array(await readFile(resolve(root, path))) })));
+    output(`Harbour found ${graph.deploymentScope.includedFiles.length} app files.`);
     // A declared connection without its preview grant would only park the
     // deployment after the save; refuse here, before any operation exists.
-    const kitAppId = options.integrations ? await assertPreviewIntegrationsReady(root, options.integrations.governance, tenantId, options.integrations.bundle, output) : options.appId;
+    const kitAppId = pending?.appId ?? (options.integrations ? await assertPreviewIntegrationsReady(root, options.integrations.governance, tenantId, options.integrations.bundle, output) : options.appId);
     // An app that calls governed AI needs the company's AI setup to pass the
     // deployment PLAN; ask governance now rather than discover it on the deployed button.
-    if (options.integrations && kitAppId && await appCallsAi(root))
+    if (!pending?.uploaded && options.integrations && kitAppId && await appCallsAi(root))
         await assertAiReady(kitAppId, "preview", options.integrations.governance, output);
     // A kit app the pipeline's gate would refuse (a table without RLS, an
     // operation no journey exercises, a cross-user leak) is refused here,
     // before the save, by the same gate with the same wording.
     const gate = options.kitGate === false ? undefined : options.kitGate ?? (options.integrations ? { bundle: options.integrations.bundle } : undefined);
-    if (gate)
+    if (gate && !pending?.uploaded)
         await preflightKitGate(root, gate.bundle, output, gate.run);
     try {
         await client.initialize();
@@ -54,40 +94,59 @@ export async function productionise(rootArg, client, output, tenantId, includePa
     let start;
     const linked = kitAppId ? { appId: kitAppId } : {};
     try {
-        start = structured(await client.call("harbour_start_productionization", { appPath: basename(root), appName: basename(root), surface: "codex", ...linked }));
+        start = pending ? { operation: { operationId: pending.operationRef } } : structured(await client.call("harbour_start_productionization", { appPath: basename(root), appName: basename(root), surface: "codex", ...linked }));
     }
-    catch {
-        throw new CliError("NOT_STARTED", "Harbour could not start the productionisation operation.");
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError("START_UNCONFIRMED", "Harbour did not confirm the start response. Run productionise again to recover the app operation before starting another deployment.");
     }
     const operationRef = start.operation?.operationId;
     if (!operationRef)
-        throw new CliError("NOT_STARTED", "Harbour did not start the productionisation operation.");
+        throw new CliError("START_UNCONFIRMED", "Harbour did not return the operation reference. Recover the app operation before starting another deployment.");
+    pending ??= { tenantId, endpoint: client.endpoint, operationRef, sourceDigest: (await sourceDigest(root)).digest, uploaded: false, graph, ...(kitAppId ? { appId: kitAppId } : {}) };
+    await writePending(root, pending);
+    output(`Harbour operation saved. Continue with harbour status --operation ${operationRef} --wait --json.`);
     try {
-        const submitted = structured(await client.call("harbour_submit_application_graph", { operationId: operationRef, surface: "codex", graph, ...linked }));
-        if (submitted.nextTool && !matchesTool(submitted.nextTool, "harbour_prepare_source_upload"))
-            throw new CliError("UNSUPPORTED_NEXT_STEP", "Harbour returned an unsupported next step.", operationRef);
-        const appId = typeof submitted.appId === "string" ? submitted.appId.trim() : "";
+        let appId = pending.appId;
+        if (!pending.uploaded && !pending.uploadCompletion) {
+            const submitted = structured(await client.call("harbour_submit_application_graph", { operationId: operationRef, surface: "codex", graph, ...linked }));
+            if (submitted.nextTool && !matchesTool(submitted.nextTool, "harbour_prepare_source_upload"))
+                throw new CliError("UNSUPPORTED_NEXT_STEP", "Harbour returned an unsupported next step.", operationRef);
+            appId = typeof submitted.appId === "string" ? submitted.appId.trim() : "";
+            if (!appId)
+                throw new CliError("APP_IDENTITY_MISSING", "Harbour did not return the app identity for this operation.", operationRef);
+            if (kitAppId && appId !== kitAppId)
+                throw new CliError("APP_IDENTITY_MISMATCH", "Harbour returned a different app identity than the one linked in .harbour/kit.lock.json.", operationRef);
+            // The canonical identity lands in kit.lock so a later `integrations request` reuses it instead of linking a second app.
+            await recordKitAppId(root, appId, tenantId);
+            pending = { ...pending, appId, sourceDigest: (await sourceDigest(root)).digest };
+            await writePending(root, pending);
+            const manifest = await createSourceManifest({ tenantId, appId, operationId: operationRef, graphDigest: graph.graphDigest, files });
+            const preliminaryArchive = await archiveForManifest(root, manifest);
+            const prepared = structured(await client.call("harbour_prepare_source_upload", { operationId: operationRef, appId, surface: "codex", graph, format: "zip", filename: `${appId}.zip`, compressedBytes: preliminaryArchive.body.byteLength, manifest: { schema: "harbour.source-package-manifest/1.0", files: manifest.files.map(file => ({ path: file.path, size: file.bytes, sha256: file.sha256 })) } }));
+            if (!prepared.acceptedManifest || !prepared.sourceUpload)
+                throw new CliError("UPLOAD_CONTRACT_MISSING", "Harbour did not return a safe upload contract.", operationRef);
+            if (prepared.nextAction?.tool && !matchesTool(prepared.nextAction.tool, "harbour_complete_source_upload"))
+                throw new CliError("UNSUPPORTED_NEXT_STEP", "Harbour returned an unsupported next step.", operationRef);
+            const archive = await archiveForManifest(root, prepared.acceptedManifest);
+            const parts = await putMultipart(prepared.sourceUpload, archive.body, (sent, total) => output(`Harbour is uploading the app package (${Math.floor(sent * 100 / total)}%).`));
+            pending = { ...pending, uploadCompletion: { intentId: prepared.sourceUpload.intentId, parts, clientSha256: archive.digest } };
+            await writePending(root, pending);
+        }
+        if (!pending.uploaded && pending.uploadCompletion) {
+            await client.call("harbour_complete_source_upload", { operationId: operationRef, ...pending.uploadCompletion });
+            pending = { ...pending, uploaded: true };
+            await writePending(root, pending);
+            output("Harbour uploaded the secure app package and is inspecting it.");
+        }
         if (!appId)
-            throw new CliError("APP_IDENTITY_MISSING", "Harbour did not return the app identity for this operation.", operationRef);
-        if (kitAppId && appId !== kitAppId)
-            throw new CliError("APP_IDENTITY_MISMATCH", "Harbour returned a different app identity than the one linked in .harbour/kit.lock.json.", operationRef);
-        // The canonical identity lands in kit.lock so a later `integrations request` reuses it instead of linking a second app.
-        await recordKitAppId(root, appId, tenantId);
-        const manifest = await createSourceManifest({ tenantId, appId, operationId: operationRef, graphDigest: graph.graphDigest, files });
-        const preliminaryArchive = await archiveForManifest(root, manifest);
-        const prepared = structured(await client.call("harbour_prepare_source_upload", { operationId: operationRef, appId, surface: "codex", graph, format: "zip", filename: `${appId}.zip`, compressedBytes: preliminaryArchive.body.byteLength, manifest: { schema: "harbour.source-package-manifest/1.0", files: manifest.files.map(file => ({ path: file.path, size: file.bytes, sha256: file.sha256 })) } }));
-        if (!prepared.acceptedManifest || !prepared.sourceUpload)
-            throw new CliError("UPLOAD_CONTRACT_MISSING", "Harbour did not return a safe upload contract.", operationRef);
-        if (prepared.nextAction?.tool && !matchesTool(prepared.nextAction.tool, "harbour_complete_source_upload"))
-            throw new CliError("UNSUPPORTED_NEXT_STEP", "Harbour returned an unsupported next step.", operationRef);
-        const archive = await archiveForManifest(root, prepared.acceptedManifest);
-        const parts = await putMultipart(prepared.sourceUpload, archive.body, (sent, total) => output(`Harbour is uploading the app package (${Math.floor(sent * 100 / total)}%).`));
-        await client.call("harbour_complete_source_upload", { operationId: operationRef, intentId: prepared.sourceUpload.intentId, parts, clientSha256: archive.digest });
-        output("Harbour uploaded the secure app package and is inspecting it.");
-        await waitForIntake(client, operationRef);
-        let execution = await execute(client, operationRef, appId, graph);
+            throw new CliError("APP_IDENTITY_MISSING", "The saved operation has no app identity.", operationRef);
+        if (!prior?.sourceSave)
+            await waitForIntake(client, operationRef);
+        let execution = prior?.sourceSave?.status && prior.sourceSave.status !== "AWAITING_APPROVAL" ? { status: prior.sourceSave.status } : await execute(client, operationRef, appId, graph);
         if (execution.status === "APPROVAL_REQUIRED" || execution.approvalRequiredBeforeExternalAction === true) {
-            output(`Approval required: Harbour can copy ${files.length} app files to the approved company code system. Nothing will be deployed or released. Type Approved. then press Enter.`);
+            output(`Approval required: Harbour can copy ${graph.deploymentScope.includedFiles.length} app files to the approved company code system. Nothing will be deployed or released. Type Approved. then press Enter.`);
             const approval = await readApproval();
             if (approval !== "Approved.")
                 throw new CliError("APPROVAL_NOT_GRANTED", "The Harbour save was not approved.", operationRef);
@@ -105,33 +164,7 @@ export async function productionise(rootArg, client, output, tenantId, includePa
         const verification = safeVerificationResult(report, evidence);
         if (options.waitForDeployment === false)
             return { cliVersion: CLI_VERSION, operationRef, result: verification };
-        // The saved app is not the finished product. The same source save that the
-        // console follows to "live" starts a preview deployment; follow it here so
-        // the maker gets the app's real protected link, not the example one.
-        // Past this point the app is saved and verified; a failure here is about
-        // following the deployment, not about the save, and must say so.
-        let summary;
-        try {
-            summary = await follow(client, operationRef, output, options.waitOptions);
-        }
-        catch (error) {
-            if (error instanceof CliError)
-                throw error;
-            throw new CliError("DEPLOYMENT_STATUS_UNAVAILABLE", `Harbour saved and verified the app but could not follow its deployment (${error instanceof Error ? error.message.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").slice(0, 160) : "unknown error"}). Check again with \`harbour status\`.`, operationRef);
-        }
-        output(outcomeLine(summary));
-        // The console asks for the app's name, audience and secrets before it
-        // offers promotion; say what is still open so a CLI-only builder knows.
-        let setup;
-        try {
-            setup = await getAppSetup(client, operationRef);
-        }
-        catch {
-            setup = undefined;
-        }
-        if (setup?.pending?.length)
-            output(`${setup.nextAction?.plainEnglish ?? "The app still needs setup."} Run \`harbour setup --operation ${operationRef}\`.`);
-        return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...summary, ...(setup ? { setup: { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}) } } : {}) } };
+        return finishDeployment(client, operationRef, output, options, verification);
     }
     catch (error) {
         throw await operationFailure(client, operationRef, error);
@@ -216,6 +249,7 @@ async function waitForIntake(client, operationRef) {
             return;
         if (status.operation?.stage === "failed")
             throw intakeRejection(status, operationRef);
+        await new Promise(resolve => setTimeout(resolve, 1_000));
     }
     throw new CliError("INSPECTION_TIMEOUT", "Harbour is still inspecting the app package. Resume this operation safely.", operationRef);
 }
@@ -398,3 +432,64 @@ export async function appCallsAi(root) {
     const capabilities = report?.gate?.inventory?.capabilities;
     return Array.isArray(capabilities) && capabilities.includes("ai");
 }
+async function finishDeployment(client, operationRef, output, options, verification = {}) {
+    let summary;
+    try {
+        summary = options.waitForDeployment === false ? outcomeFor(await fetchStatus(client, operationRef), operationRef) : await follow(client, operationRef, output, options.waitOptions);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw withOperation(error, operationRef);
+        throw new CliError("DEPLOYMENT_STATUS_UNAVAILABLE", `Harbour could not follow the existing operation (${error instanceof Error ? error.message.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").slice(0, 160) : "unknown error"}). Check again with \`harbour status\`.`, operationRef);
+    }
+    output(outcomeLine(summary));
+    // The console asks for the app's name, audience and secrets before it
+    // offers promotion; say what is still open so a CLI-only builder knows.
+    let setup;
+    try {
+        setup = await getAppSetup(client, operationRef);
+    }
+    catch {
+        setup = undefined;
+    }
+    if (setup?.pending?.length)
+        output(`${setup.nextAction?.plainEnglish ?? "The app still needs setup."} Run \`harbour setup --operation ${operationRef}\`.`);
+    return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...summary, ...(setup ? { setup: { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}) } } : {}) } };
+}
+function operationFinished(status) {
+    if (status.production)
+        return ["LIVE", "FAILED", "MANUAL_RECOVERY"].includes(status.production.state);
+    if (status.deployment)
+        return ["LIVE", "FAILED", "STALE", "RETRYABLE_FAILURE"].includes(status.deployment.state);
+    return status.operation?.stage === "failed";
+}
+async function readPending(root, tenantId, endpoint) {
+    let raw;
+    try {
+        raw = await readFile(resolve(root, ".harbour/local/productionise.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const record = JSON.parse(raw);
+    if (!record.operationRef || !record.graph || typeof record.uploaded !== "boolean" || !record.sourceDigest)
+        throw new CliError("OPERATION_RECORD_INVALID", "The saved deployment reference cannot be read. Recover the operation from Harbour before starting another.");
+    return record.tenantId === tenantId && record.endpoint === endpoint ? record : undefined;
+}
+async function writePending(root, record) {
+    const path = resolve(root, ".harbour/local/productionise.json");
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        const temporary = `${path}.${process.pid}.tmp`;
+        await writeFile(temporary, JSON.stringify(record), { mode: 0o600 });
+        await rename(temporary, path);
+    }
+    catch {
+        throw new CliError("OPERATION_RECORD_WRITE_FAILED", "Harbour started the operation but could not save its local reference. Continue with harbour status using this operation reference.", record.operationRef);
+    }
+}
+function withOperation(error, operationRef) {
+    return new CliError(error.code, error.message, operationRef, error.remediationHint, error.result);
+}

package/dist/packages/harbour-cli/src/remote-mcp-client.js

@@ -56,6 +56,7 @@ export class RemoteMcpClient {
         this.tenant = tenant;
         this.token = typeof token === "string" ? async () => token : token;
     }
+    get endpoint() { return this.url; }
     async initialize() {
         if (this.initialized)
             return;