@fourier-labs/harbour 0.1.13 → 0.1.14

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

@@ -108,15 +108,38 @@ export async function refreshStoredToken(mcpUrl, tenant, path = tokenStorePath()
         throw new Error("Harbour sign-in expired or was revoked. Run `harbour login` again.");
     }
 }
-export async function logout(mcpUrl, tenant) {
-    const stored = await clearStoredToken(mcpUrl, tenant);
-    if (stored?.refreshToken && stored.revocationEndpoint) {
+/**
+ * Removes the local record and revokes both stored tokens when the server
+ * advertises a revocation endpoint. Offline revocation cannot reach a token
+ * already held elsewhere; the local copy is removed regardless.
+ */
+export async function logout(mcpUrl, tenant, path = tokenStorePath()) {
+    const stored = await clearStoredToken(mcpUrl, tenant, path);
+    if (!stored?.revocationEndpoint)
+        return;
+    for (const [token, hint] of [[stored.refreshToken, "refresh_token"], [stored.accessToken, "access_token"]]) {
+        if (!token)
+            continue;
         try {
-            await fetch(stored.revocationEndpoint, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ token: stored.refreshToken, client_id: stored.clientId }), redirect: "error" });
+            await fetch(stored.revocationEndpoint, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ token, token_type_hint: hint, client_id: stored.clientId }), redirect: "error" });
         }
         catch { /* Local credentials are removed even if offline revocation cannot complete. */ }
     }
 }
+/** Email of the signed-in company account, from the OAuth userinfo endpoint beside the token endpoint; undefined when unavailable. */
+export async function connectedAccount(mcpUrl, tenant, accessToken, path = tokenStorePath()) {
+    const stored = await loadStoredToken(mcpUrl, tenant, path);
+    if (!stored)
+        return undefined;
+    try {
+        const response = await fetch(stored.tokenEndpoint.replace(/\/token$/, "/userinfo"), { headers: { authorization: `Bearer ${accessToken}` }, redirect: "error" });
+        const body = response.ok ? await response.json() : {};
+        return typeof body.email === "string" ? body.email : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function discover(mcpUrl) {
     const resource = new URL(mcpUrl);
     resource.pathname = `${resource.pathname.replace(/\/mcp$/, "")}/.well-known/oauth-protected-resource`.replace(/\/\//g, "/");

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

@@ -0,0 +1,119 @@
+import { readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEPENDENT_READ_OPERATIONS, READ_OPERATIONS, kitPaths, readDeclaration, readKitLock, resourceNames, sourceDigest } from "./kit.js";
+import { LocalRuntime, runningOrigin } from "./local-runtime.js";
+import { CLI_VERSION } from "./version.js";
+/** Runs the kit checks and writes `.harbour/local/check-report.json`; a source edit changes sourceDigest and so invalidates the previous report. */
+export async function runChecks(root, options) {
+    const { output, run, bundle } = options;
+    const checks = [];
+    const record = (name, status, detail) => { checks.push({ name, status, ...(detail ? { detail } : {}) }); output(`${status === "pass" ? "ok  " : status === "fail" ? "FAIL" : "skip"} ${name}${detail ? ` — ${detail}` : ""}`); };
+    const source = await sourceDigest(root);
+    const previous = await readReport(root);
+    if (previous && previous.sourceDigest !== source.digest)
+        output("Source changed since the last report; the previous report is no longer valid.");
+    const declaration = await readDeclaration(root);
+    record("declaration", declaration.errors.length ? "fail" : "pass", declaration.errors[0]);
+    let lockDetail;
+    const lock = await readKitLock(root).catch(error => { lockDetail = error instanceof Error ? error.message : String(error); return undefined; });
+    record("kit_lock", lock ? "pass" : "fail", lockDetail ?? (lock ? undefined : ".harbour/kit.lock.json is missing (run `harbour init`)"));
+    const typecheck = await run("npx", ["tsc", "--noEmit"], { cwd: root, quiet: true });
+    record("typecheck", typecheck.code === 0 ? "pass" : "fail", typecheck.code === 0 ? undefined : lastLines(typecheck.stdout || typecheck.stderr));
+    const build = await run("npm", ["run", "build"], { cwd: root, quiet: true });
+    record("build", build.code === 0 ? "pass" : "fail", build.code === 0 ? undefined : lastLines(build.stderr || build.stdout));
+    const throwaway = LocalRuntime.forCheck(root, run);
+    try {
+        await throwaway.writeCheckFiles(bundle);
+        await throwaway.up();
+        const applied = await throwaway.migrate();
+        record("migrations", "pass", `${applied.length} file(s) applied to a disposable database`);
+    }
+    catch (error) {
+        record("migrations", "fail", error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        await throwaway.down();
+    }
+    const origin = await (options.localOrigin ?? (() => runningOrigin(root)))();
+    const journeys = (await readdir(kitPaths(root).checks).catch(() => [])).filter(name => /\.(mjs|js|cjs)$/.test(name)).sort();
+    if (!journeys.length)
+        record("journeys", "not_run", "no checks under .harbour/checks/");
+    else if (!origin)
+        record("journeys", "not_run", "harbour dev is not running; start it to exercise the journey checks");
+    else
+        for (const name of journeys) {
+            const result = await run("node", [join(kitPaths(root).checks, name)], { cwd: root, quiet: true, env: { HARBOUR_APP_URL: origin, HARBOUR_SDK_MODULE: join(root, "node_modules", "@harbour", "app-sdk", "dist", "index.js") } });
+            record(`journey:${name}`, result.code === 0 ? "pass" : "fail", result.code === 0 ? undefined : lastLines(result.stderr || result.stdout));
+        }
+    let integrations = "not tested";
+    if (options.governance && lock?.appId && !declaration.errors.length) {
+        integrations = await testIntegrationReads(lock.appId, options.governance, declaration.declaration, output);
+        if (!integrations.length)
+            output("No READY development grants with read operations; real integrations were not exercised.");
+    }
+    else if (options.governance)
+        output("Integrations were not tested: the app is not linked yet or the declaration is invalid.");
+    const report = {
+        schema: "harbour.check-report/1.0",
+        createdAt: new Date().toISOString(),
+        sourceDigest: source.digest,
+        toolchain: { node: process.version, cliVersion: CLI_VERSION, bundle: { kitVersion: bundle.kitVersion, sdkTarballSha256: bundle.sdk.tarballSha256, appGateway: bundle.images.appGateway, sessionFixture: bundle.images.sessionFixture, briefFingerprint: bundle.brief.fingerprint } },
+        checks,
+        integrations,
+        passed: checks.every(check => check.status !== "fail") && (integrations === "not tested" || integrations.every(item => item.status !== "fail"))
+    };
+    await writeFile(kitPaths(root).report, `${JSON.stringify(report, null, 2)}\n`).catch(() => undefined);
+    return report;
+}
+/** Explicit read operations only (READ_OPERATIONS) against READY development grants; sends never run. A dependent read (gmail.message.read) is exercised through its list: the newest message of the first thread, when there is one. */
+async function testIntegrationReads(appId, client, declaration, output) {
+    const results = [];
+    const { grants } = await client.list(appId);
+    for (const grant of grants) {
+        if (grant.environment !== "development" || grant.readiness !== "ready")
+            continue;
+        const declared = declaration.connections[grant.connection];
+        for (const operation of grant.operations) {
+            if (!READ_OPERATIONS.includes(operation))
+                continue;
+            const declaredOperation = declared?.operations[operation];
+            if (!declaredOperation)
+                continue;
+            for (const resource of resourceNames(declaredOperation)) {
+                const input = operation === "warehouse.view.read" ? { columns: declaredOperation.resources[resource]?.columns ?? [], limit: 1 } : { limit: 1 };
+                const record = (name, status, detail) => { results.push({ connection: grant.connection, operation: name, resource, status, ...(detail ? { detail } : {}) }); output(`${status === "pass" ? "ok  " : "FAIL"} integration ${grant.connection} ${name} ${resource}`); };
+                let listed;
+                try {
+                    listed = await client.execute(appId, { connection: grant.connection, operation, resource, input });
+                    record(operation, "pass");
+                }
+                catch (error) {
+                    record(operation, "fail", error instanceof Error ? error.message : String(error));
+                    continue;
+                }
+                // gmail.message.read needs a message id: read the newest message of the first listed thread when the grant covers it.
+                const dependent = DEPENDENT_READ_OPERATIONS.find(name => name === "gmail.message.read" && operation === "gmail.thread.list" && grant.operations.includes(name) && declared?.operations[name]);
+                const messageId = listed?.threads?.[0]?.messageId;
+                if (!dependent || !messageId)
+                    continue;
+                try {
+                    await client.execute(appId, { connection: grant.connection, operation: dependent, resource, input: { messageId } });
+                    record(dependent, "pass");
+                }
+                catch (error) {
+                    record(dependent, "fail", error instanceof Error ? error.message : String(error));
+                }
+            }
+        }
+    }
+    return results;
+}
+export async function readReport(root) {
+    try {
+        return JSON.parse(await readFile(kitPaths(root).report, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function lastLines(text, count = 5) { return text.trim().split("\n").slice(-count).join(" | ").slice(0, 600); }

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

@@ -4,8 +4,15 @@ import { productionise } from "./productionise.js";
 import { confirmAudience, confirmProfile, dismissSecret, fetchStatus, getAppSetup, listSecrets, outcomeFor, promoteToProduction, readSecretFromStdin, readSecretFromTerminal, retryDeployment, setSecret, summarize, waitForSettled } from "./operations.js";
 import { safeError, CliError, renderSummary } from "./output.js";
 import { CLI_VERSION } from "./version.js";
-import { login, logout, refreshStoredToken } from "./auth.js";
+import { connectedAccount, login, logout, refreshStoredToken } from "./auth.js";
 import { connect, loadConfig, resolveConfig } from "./config.js";
+import { loadKitBundle } from "./kit-bundle.js";
+import { appRoot } from "./kit.js";
+import { initKit } from "./starter.js";
+import { startDev } from "./dev.js";
+import { ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
+import { runChecks } from "./check.js";
+import { GovernanceClient, integrationsStatus, requestIntegrations } from "./integrations.js";
 const args = process.argv.slice(2);
 const command = args[0];
 const connectUrl = args[1];
@@ -21,6 +28,13 @@ const personal = args.includes("--personal");
 const valueStdin = args.includes("--value-stdin");
 const subcommand = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
 const wait = args.includes("--wait");
+const reset = args.includes("--reset");
+const upgrade = args.includes("--upgrade");
+const testIntegrations = args.includes("--integrations");
+const reason = optionValue("--reason");
+const environment = optionValue("--environment");
+const operations = optionValue("--operations");
+const expiresAt = optionValue("--expires-at");
 const includePaths = [];
 let optionError;
 for (let index = 0; index < args.length; index += 1) {
@@ -49,22 +63,35 @@ const usage = [
     "  harbour secrets list --operation <reference> [--json]",
     "  harbour secrets set --operation <reference> --name <NAME> [--personal] [--value-stdin]",
     "  harbour secrets dismiss --operation <reference> --name <NAME>",
+    "  harbour init --app-root <path> [--upgrade]                 create the starter or add the kit files; --upgrade re-pins the kit bundle",
+    "  harbour dev --app-root <path> [--reset]                    run the app locally on one loopback origin (--reset deletes this app's local data)",
+    "  harbour stop --app-root <path>                             stop this app's local services, keeping data",
+    "  harbour check --app-root <path> [--integrations] [--json]  declaration, types, build, migrations, journeys (+ authorised real reads)",
+    "  harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>] [--operations a,b] [--expires-at <UTC>] [--json]",
+    "  harbour integrations status --app-root <path> [--json]",
     "Run `harbour connect <company-start-url>` once, then sign in when Harbour asks.",
     "productionise saves the app, follows its deployment, and prints the protected preview link; promote sends a tested preview to production.",
+    "For kit apps, productionise first checks that every connection in .harbour/integrations.json has a preview grant and exits 2 (INTEGRATIONS_NOT_READY) with the requests to make.",
     "secrets set reads the value from your terminal with echo off (or from stdin with --value-stdin); it is never printed or passed to any other program.",
     ""
 ].join("\n");
 const OPERATION_COMMANDS = ["status", "retry", "promote", "setup", "profile", "audience", "secrets"];
+const LOCAL_COMMANDS = ["init", "dev", "stop", "check"];
 const progress = (message) => { process.stderr.write(`${message}\n`); };
+/** Envelope for commands that start no Harbour operation (local kit commands, integrations). */
+const summaryEnvelope = (result) => ({ schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: false, result });
+const emit = (value) => { process.stdout.write(json ? `${JSON.stringify(value)}\n` : renderSummary(value)); process.exitCode = 0; };
 if (command === "--version" || command === "version") {
     process.stdout.write(`${CLI_VERSION}\n`);
 }
 else if (!command || command === "help" || command === "--help" || args.includes("-h")) {
     process.stdout.write(usage);
 }
-else if (!["connect", "login", "logout", "productionise", ...OPERATION_COMMANDS].includes(command)
+else if (!["connect", "login", "logout", "productionise", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
     || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
     || (command === "productionise" && (optionError || !root))
+    || (LOCAL_COMMANDS.includes(command) && !root)
+    || (command === "integrations" && (!root || !subcommand || !["request", "status"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--") || !reason))))
     || (OPERATION_COMMANDS.includes(command) && !operationRef)
     || (command === "secrets" && (!subcommand || !["list", "set", "dismiss"].includes(subcommand) || (subcommand !== "list" && !secretName)))) {
     if (optionError)
@@ -79,6 +106,69 @@ else {
             process.stdout.write(`Harbour is connected for ${saved.tenantId}.\n`);
             process.exitCode = 0;
         }
+        else if (LOCAL_COMMANDS.includes(command)) {
+            // Local commands run before the company config/login requirement: the base app needs neither.
+            const bundle = await loadKitBundle();
+            const target = appRoot(root);
+            const config = resolveConfig(process.env, await loadConfig());
+            const companyToken = async () => config ? (explicitToken || await refreshStoredToken(config.mcpUrl, config.tenantId)) : undefined;
+            if (command === "init") {
+                const result = await initKit(target, bundle, { upgrade, tenantId: config?.tenantId });
+                for (const line of [...result.created.map(path => `created ${path}`), ...result.updated.map(path => `updated ${path}`), ...result.kept.map(path => `kept    ${path}`), ...result.bundleChanges.map(change => `bundle  ${change}`)])
+                    progress(line);
+                // The SDK is not on the public registry: init installs the pinned tarball (and the app's other dependencies) itself.
+                const sdk = await ensureSdk(target, bundle, process.env, runCommand, progress);
+                if (sdk === "missing")
+                    progress("The kit SDK was not installed: set HARBOUR_KIT_SDK_TARBALL to the bundle's @harbour/app-sdk tarball (or use a bundle with sdk.url), then rerun `harbour init`.");
+                progress(result.mode === "starter" ? "Starter created. Next: `harbour dev --app-root <path>`. Codex reads the AGENTS.md block; Claude Code reads .claude/skills/harbour-kit/SKILL.md." : upgrade ? (result.bundleChanges.length ? "Kit bundle upgraded; running checks." : "Kit bundle already current; running checks.") : "Kit files added; existing files were kept.");
+                if (upgrade) {
+                    const report = await runChecks(target, { run: runCommand, bundle, output: progress });
+                    emit(summaryEnvelope({ ...result, report }));
+                }
+                else
+                    emit(summaryEnvelope(result));
+            }
+            else if (command === "stop") {
+                const runtime = new LocalRuntime(target);
+                const lock = await readDevLock(target);
+                if (lock && lock.pid !== process.pid) {
+                    try {
+                        process.kill(lock.pid, "SIGTERM");
+                    }
+                    catch { /* already gone */ }
+                }
+                const stopped = await runtime.stop();
+                await releaseDevLock(target);
+                emit(summaryEnvelope({ project: runtime.project, stopped: stopped.stopped, volumesRetained: true }));
+            }
+            else if (command === "check") {
+                let governance;
+                if (testIntegrations) {
+                    if (!config)
+                        throw new CliError("CONFIG_REQUIRED", "`--integrations` needs a company connection: run `harbour connect <company-start-url>`.");
+                    const token = await companyToken();
+                    if (!token)
+                        throw new CliError("AUTH_REQUIRED", "`--integrations` needs a Harbour sign-in: run `harbour login`.");
+                    governance = new GovernanceClient(config.apiUrl, token, config.tenantId);
+                }
+                const report = await runChecks(target, { run: runCommand, bundle, output: progress, governance });
+                if (!report.passed) {
+                    process.stdout.write(json ? `${JSON.stringify({ ...summaryEnvelope(report), status: "FAILED", error: { code: "CHECKS_FAILED", message: "One or more checks failed; see .harbour/local/check-report.json." } })}\n` : "Checks failed; see .harbour/local/check-report.json.\n");
+                    process.exitCode = 1;
+                }
+                else
+                    emit(summaryEnvelope(report));
+            }
+            else {
+                const started = await startDev(target, { bundle, output: progress, reset, company: config ? { apiUrl: config.apiUrl, tenantId: config.tenantId, accessToken: companyToken, account: async () => { const token = await companyToken(); return token ? connectedAccount(config.mcpUrl, config.tenantId, token) : undefined; } } : undefined });
+                let stopping = false;
+                const shutdown = () => { if (stopping)
+                    return; stopping = true; progress("Stopping local Harbour services (data kept)."); void started.stop().finally(() => process.exit(0)); };
+                process.on("SIGINT", shutdown);
+                process.on("SIGTERM", shutdown);
+                await new Promise(() => { });
+            }
+        }
         else {
             const config = resolveConfig(process.env, await loadConfig());
             if (!config)
@@ -96,13 +186,26 @@ else {
                 process.exitCode = 0;
             }
             else {
-                const token = explicitToken || await refreshStoredToken(url, tenant);
+                const resolveToken = async () => explicitToken || await refreshStoredToken(url, tenant);
+                const token = await resolveToken();
                 if (!token)
                     throw new CliError("AUTH_REQUIRED", "Please sign in to Harbour with `harbour login`.");
-                const client = new RemoteMcpClient(url, token, tenant);
+                // The client re-resolves per request so a token rotated by a sibling process mid-poll is picked up.
+                const client = new RemoteMcpClient(url, resolveToken, tenant);
                 let envelope;
-                if (command === "productionise") {
-                    const result = await productionise(root, client, progress, tenant, includePaths, { waitForDeployment: !noWait });
+                if (command === "integrations") {
+                    const target = appRoot(root);
+                    const governance = new GovernanceClient(config.apiUrl, token, tenant);
+                    const result = subcommand === "status"
+                        ? await integrationsStatus(target, governance)
+                        : await requestIntegrations(target, governance, tenant, await loadKitBundle(), { connection: args[2], reason: reason, environment, operations: operations?.split(",").map(value => value.trim()).filter(Boolean), expiresAt });
+                    envelope = summaryEnvelope(result);
+                    if (!json)
+                        progress(subcommand === "status" ? renderIntegrationsStatus(result) : renderRequest(result));
+                }
+                else if (command === "productionise") {
+                    // Kit apps: preview grants are checked (and the app linked) before any operation starts, so productionise never mints a second app for the same root.
+                    const result = await productionise(root, client, progress, tenant, includePaths, { waitForDeployment: !noWait, integrations: { governance: new GovernanceClient(config.apiUrl, token, tenant), bundle: await loadKitBundle() } });
                     envelope = { schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: true, operationRef: result.operationRef, result: result.result };
                 }
                 else {
@@ -137,9 +240,25 @@ else {
         const envelope = { schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "FAILED", operationStarted: error instanceof CliError ? Boolean(error.operationRef) : false, ...(error instanceof CliError && error.operationRef ? { operationRef: error.operationRef } : {}), error: safe };
         if (json || command === "productionise")
             process.stdout.write(`${JSON.stringify(envelope)}\n`);
-        process.exitCode = 1;
+        // Exit 2, like a usage error: nothing started and the fix is a command the maker runs.
+        process.exitCode = safe.code === "INTEGRATIONS_NOT_READY" ? 2 : 1;
     }
 }
+function renderIntegrationsStatus(status) {
+    if (!status.linked)
+        return "This app is not linked yet; `harbour integrations request` links it.";
+    const lines = [`App ${status.appId}`];
+    for (const grant of status.grants)
+        lines.push(`  ${grant.connection} [${grant.environment}, ${grant.identityMode}] ${grant.status} — ${grant.readiness}${grant.expiresAt ? ` until ${grant.expiresAt}` : ""}: ${grant.operations.join(", ")}`);
+    for (const request of status.requests)
+        lines.push(`  request ${request.requestId}: ${request.state} (${request.reason})`);
+    if (!status.grants.length && !status.requests.length)
+        lines.push("  no grants or requests yet");
+    return lines.join("\n");
+}
+function renderRequest(result) {
+    return [`App ${result.appId}: ${result.connection} (${result.environment})`, ...result.requests.map(item => `  ${item.identityMode} identity — ${item.operations.join(", ")} on ${item.resources.join(", ")}: ${item.state === "READY" ? "READY" : item.state === "PENDING" ? "PENDING (not ready; IT approval or provider setup is outstanding)" : item.state}${item.readiness && item.readiness !== "ready" && item.readiness !== "pending" ? ` (${item.readiness})` : ""}`)].join("\n");
+}
 function optionValue(flag) {
     const index = args.indexOf(flag);
     const value = index >= 0 ? args[index + 1] : undefined;

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

@@ -40,7 +40,8 @@ export async function connect(startUrl, path = configPath()) {
         schema: "harbour.cli-config/1.0",
         tenantId: String(body.tenantId ?? ""),
         mcpUrl: String(body.mcpUrl ?? ""),
-        ...(typeof body.uploadUrl === "string" ? { uploadUrl: body.uploadUrl } : {})
+        ...(typeof body.uploadUrl === "string" ? { uploadUrl: body.uploadUrl } : {}),
+        ...(typeof body.apiUrl === "string" ? { apiUrl: body.apiUrl } : {})
     };
     await saveConfig(config, path);
     return config;
@@ -50,7 +51,14 @@ export function resolveConfig(env, saved) {
     const tenantId = env.HARBOUR_TENANT?.trim() || saved?.tenantId;
     if (!mcpUrl || !tenantId)
         return undefined;
-    return { schema: "harbour.cli-config/1.0", tenantId, mcpUrl, ...(saved?.uploadUrl ? { uploadUrl: saved.uploadUrl } : {}) };
+    return { schema: "harbour.cli-config/1.0", tenantId, mcpUrl, ...(saved?.uploadUrl ? { uploadUrl: saved.uploadUrl } : {}), apiUrl: env.HARBOUR_API_URL?.trim() || saved?.apiUrl || apiUrlFromMcpUrl(mcpUrl) };
+}
+/** `https://host/stage/mcp` -> `https://host/stage`: the dev routes live beside the MCP endpoint. */
+export function apiUrlFromMcpUrl(mcpUrl) {
+    const url = new URL(mcpUrl);
+    url.pathname = url.pathname.replace(/\/mcp\/?$/, "");
+    url.search = "";
+    return url.toString().replace(/\/$/, "");
 }
 function validConfig(value) {
     return Boolean(isRecord(value)
@@ -59,7 +67,8 @@ function validConfig(value) {
         && value.tenantId.length > 0
         && typeof value.mcpUrl === "string"
         && /^https?:\/\//.test(value.mcpUrl)
-        && (value.uploadUrl === undefined || typeof value.uploadUrl === "string"));
+        && (value.uploadUrl === undefined || typeof value.uploadUrl === "string")
+        && (value.apiUrl === undefined || (typeof value.apiUrl === "string" && /^https?:\/\//.test(value.apiUrl))));
 }
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));

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

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+import { createForwarder } from "./forwarder.js";
+import { readKitLock } from "./kit.js";
+import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, releaseDevLock, runCommand } from "./local-runtime.js";
+import { CliError } from "./output.js";
+/**
+ * Starts the project's Compose services, applies migrations, starts Vite and the
+ * loopback origin. Resolves when the runtime is up; the returned `stop` runs
+ * `docker compose stop` (volumes retained) and is what Ctrl-C calls.
+ */
+export async function startDev(root, options) {
+    const run = options.run ?? runCommand;
+    const env = options.env ?? process.env;
+    const runtime = new LocalRuntime(root, run);
+    if (options.reset)
+        await runtime.reset(options.output);
+    const ports = await allocatePorts();
+    await acquireDevLock(root, ports);
+    let vite;
+    let forwarder;
+    const stop = async () => {
+        forwarder?.close();
+        vite?.kill("SIGTERM");
+        await runtime.stop();
+        await releaseDevLock(root);
+    };
+    try {
+        const sdk = await ensureSdk(root, options.bundle, env, run, options.output);
+        if (sdk === "missing")
+            options.output("The kit SDK is not installed: set HARBOUR_KIT_SDK_TARBALL to the bundle's @harbour/app-sdk tarball (or use a bundle with sdk.url).");
+        await runtime.writeFiles(options.bundle, ports);
+        options.output("Pulling the kit images by digest (public registry, no login).");
+        await runtime.pull(options.bundle);
+        options.output("Starting local Harbour services (postgres, storage, realtime, identity fixture, app gateway).");
+        await runtime.up();
+        const applied = await runtime.migrate();
+        options.output(`Applied ${applied.length} migration file(s).`);
+        const session = await runtime.sessionEnv();
+        const origin = `http://127.0.0.1:${ports.origin}`;
+        vite = spawn("npm", ["run", "dev"], { cwd: root, env: { ...env, HARBOUR_LOCAL_ORIGIN: origin, HARBOUR_VITE_PORT: String(ports.vite) }, stdio: ["ignore", "inherit", "inherit"] });
+        vite.on("error", () => options.output("Vite could not be started; is npm installed and `npm install` done?"));
+        const company = options.company;
+        let warnedAuth = false;
+        let lockAppId = (await readKitLock(root))?.appId || undefined;
+        forwarder = createForwarder({
+            port: ports.origin, vitePort: ports.vite, gatewayPort: ports.gateway, identityToken: session.HARBOUR_IDENTITY_CONTEXT_TOKEN,
+            apiUrl: company?.apiUrl ?? "", tenantId: company?.tenantId ?? "",
+            appId: () => lockAppId,
+            accessToken: async () => company ? company.accessToken() : undefined,
+            onAuthRequired: () => { if (!warnedAuth) {
+                warnedAuth = true;
+                options.output("Company integrations need a Harbour sign-in: run `harbour login` (in another terminal) and retry in the app.");
+            } }
+        });
+        const refreshLock = setInterval(() => { void readKitLock(root).then(lock => { lockAppId = lock?.appId || undefined; }).catch(() => undefined); }, 5_000);
+        refreshLock.unref();
+        await new Promise((resolve, reject) => { forwarder.on("error", reject); forwarder.listen(ports.origin, "127.0.0.1", resolve); });
+        const account = company ? await company.account().catch(() => undefined) : undefined;
+        options.output([
+            "",
+            `Harbour dev is running: ${origin}`,
+            `  App identity (local fixture): ${session.HARBOUR_LOCAL_USER_EMAIL ?? "local-user@example.test"}`,
+            `  Company account for integrations: ${account ?? (company ? "not signed in — run `harbour login`" : "not connected — run `harbour connect`")}`,
+            lockAppId ? `  Linked app: ${lockAppId}` : "  App not linked yet (harbour integrations request links it).",
+            "  Ctrl-C or `harbour stop` stops the services and keeps local data; `harbour dev --reset` deletes it.",
+            ""
+        ].join("\n"));
+        return { origin, stop };
+    }
+    catch (error) {
+        await stop().catch(() => undefined);
+        throw error instanceof CliError ? error : new CliError("DEV_FAILED", error instanceof Error ? error.message : "harbour dev could not start.");
+    }
+}

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

@@ -0,0 +1,147 @@
+import { createServer, request as httpRequest } from "node:http";
+import { connect } from "node:net";
+const INTEGRATION_ROUTES = { "/_harbour/integrations/execute": ["POST"], "/_harbour/integrations/connect": ["POST", "DELETE"] };
+const HOP_HEADERS = new Set(["connection", "keep-alive", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade", "host", "content-length"]);
+export function createForwarder(options) {
+    const origin = `http://127.0.0.1:${options.port}`;
+    const host = `127.0.0.1:${options.port}`;
+    const server = createServer((request, response) => {
+        const path = (request.url ?? "/").split("?")[0];
+        if (!sameOrigin(request, host, origin) || path.startsWith("/_harbour/integrations/")) {
+            void answerLocally(request, response, path, host, origin, options);
+            return;
+        }
+        if (path.startsWith("/_harbour/")) {
+            pipe(request, response, options.gatewayPort, { "x-harbour-identity-context": options.identityToken });
+            return;
+        }
+        pipe(request, response, options.vitePort);
+    });
+    server.on("upgrade", (request, socket, head) => {
+        if (!sameOrigin(request, host, origin)) {
+            socket.destroy();
+            return;
+        }
+        tunnel(request, socket, head, (request.url ?? "/").startsWith("/_harbour/") ? options.gatewayPort : options.vitePort, (request.url ?? "/").startsWith("/_harbour/") ? { "x-harbour-identity-context": options.identityToken } : {});
+    });
+    return server;
+}
+export function sameOrigin(request, host, origin) {
+    if (request.headers.host !== host)
+        return false;
+    const requestOrigin = request.headers.origin;
+    return requestOrigin === undefined || requestOrigin === origin;
+}
+/** Locally answered routes read the whole request first so a keep-alive socket is left clean. */
+async function answerLocally(request, response, path, host, origin, options) {
+    const body = await readBody(request, 16 * 1024);
+    if (!sameOrigin(request, host, origin)) {
+        reject(response, 403, "FORBIDDEN", "Requests must come from the local app origin.");
+        return;
+    }
+    if (path === "/_harbour/integrations/oauth/complete") {
+        response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+        response.end(COMPLETE_PAGE);
+        return;
+    }
+    const methods = INTEGRATION_ROUTES[path];
+    if (!methods) {
+        reject(response, 404, "NOT_FOUND", "Unknown integration route.");
+        return;
+    }
+    const method = request.method ?? "GET";
+    if (!methods.includes(method)) {
+        reject(response, 405, "VALIDATION_FAILED", "Method not allowed.");
+        return;
+    }
+    const appId = options.appId();
+    if (!appId) {
+        reject(response, 409, "CONFLICT", "This app is not linked yet. Run `harbour integrations request <connection> --reason <text>` once.", "APP_NOT_LINKED");
+        return;
+    }
+    const token = await options.accessToken().catch(() => undefined);
+    if (!token) {
+        options.onAuthRequired?.();
+        reject(response, 401, "AUTH_REQUIRED", "Sign in to Harbour with `harbour login` to use company integrations locally.", "CLI_LOGIN_REQUIRED");
+        return;
+    }
+    if (body === undefined) {
+        reject(response, 413, "VALIDATION_FAILED", "Request too large.", "REQUEST_TOO_LARGE");
+        return;
+    }
+    const target = `${options.apiUrl.replace(/\/$/, "")}/v1/development/apps/${encodeURIComponent(appId)}/integrations/${path.slice("/_harbour/integrations/".length)}`;
+    const payload = path.endsWith("/connect") && method === "POST" ? withReturnUrl(body, `${origin}/_harbour/integrations/oauth/complete`) : body.length ? Buffer.from(body).toString("utf8") : undefined;
+    let upstream;
+    try {
+        upstream = await (options.fetch ?? fetch)(target, { method, headers: { authorization: `Bearer ${token}`, "x-harbour-tenant": options.tenantId, "content-type": "application/json", accept: "application/json" }, ...(payload === undefined ? {} : { body: payload }), redirect: "error", signal: AbortSignal.timeout(12_000) });
+    }
+    catch {
+        reject(response, 503, "UNAVAILABLE", "Harbour governance could not be reached.", "PROVIDER_UNAVAILABLE");
+        return;
+    }
+    if (upstream.status === 401)
+        options.onAuthRequired?.();
+    const headers = { "content-type": upstream.headers.get("content-type") ?? "application/json", "cache-control": "no-store" };
+    const retryAfter = upstream.headers.get("retry-after");
+    if (retryAfter)
+        headers["retry-after"] = retryAfter;
+    response.writeHead(upstream.status, headers);
+    response.end(new Uint8Array(await upstream.arrayBuffer()));
+}
+function pipe(request, response, port, extraHeaders = {}) {
+    const headers = {};
+    for (const [name, value] of Object.entries(request.headers))
+        if (value !== undefined && !HOP_HEADERS.has(name))
+            headers[name] = value;
+    if (request.headers["content-length"])
+        headers["content-length"] = request.headers["content-length"];
+    Object.assign(headers, extraHeaders);
+    const upstream = httpRequest({ host: "127.0.0.1", port, method: request.method, path: request.url, headers: { ...headers, host: `127.0.0.1:${port}` } }, upstreamResponse => {
+        response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
+        upstreamResponse.pipe(response);
+    });
+    upstream.on("error", () => reject(response, 502, "UNAVAILABLE", "The local service is not responding."));
+    request.pipe(upstream);
+}
+function tunnel(request, socket, head, port, extraHeaders) {
+    const upstream = connect(port, "127.0.0.1", () => {
+        const lines = [`${request.method} ${request.url} HTTP/1.1`];
+        for (const [name, value] of Object.entries({ ...request.headers, ...extraHeaders, host: `127.0.0.1:${port}` }))
+            if (value !== undefined)
+                for (const item of Array.isArray(value) ? value : [value])
+                    lines.push(`${name}: ${item}`);
+        upstream.write(`${lines.join("\r\n")}\r\n\r\n`);
+        if (head.length)
+            upstream.write(head);
+        upstream.pipe(socket);
+        socket.pipe(upstream);
+    });
+    upstream.on("error", () => socket.destroy());
+    socket.on("error", () => upstream.destroy());
+}
+/** Consent flows return the browser to this origin's completion page; governance allowlists exactly that loopback URL. */
+function withReturnUrl(body, returnUrl) {
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(body).toString("utf8") || "{}");
+    }
+    catch {
+        parsed = {};
+    }
+    return JSON.stringify({ ...(parsed && typeof parsed === "object" ? parsed : {}), returnUrl });
+}
+function readBody(request, limit) {
+    return new Promise(resolve => {
+        const chunks = [];
+        let size = 0;
+        request.on("data", (chunk) => { size += chunk.length; if (size <= limit)
+            chunks.push(chunk); });
+        request.on("end", () => resolve(size > limit ? undefined : new Uint8Array(Buffer.concat(chunks))));
+        request.on("error", () => resolve(undefined));
+    });
+}
+function reject(response, status, category, message, code = category) {
+    response.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    response.end(JSON.stringify({ error: { category, message, details: { code } }, requestId: "local" }));
+}
+const COMPLETE_PAGE = "<!doctype html><meta charset=\"utf-8\"><title>Harbour</title><body style=\"font-family:system-ui;margin:3rem\"><h1>Connected</h1><p>Your account is linked for this app. You can close this tab and return to the app.</p></body>";