@isomorph.ai/cli 0.2.0

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

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+import { RemoteMcpClient } from "./remote-mcp-client.js";
+import { appCallsAi, productionise } from "./productionise.js";
+import { confirmAudience, confirmProfile, continueCommand, dismissSecret, fetchStatus, follow, getAppSetup, listSecrets, promoteToProduction, readSecretFromStdin, readSecretFromTerminal, retryDeployment, setSecret, summarize } from "./operations.js";
+import { CliError, failureEnvelope, operationEnvelope, renderFailure, renderSummary } from "./output.js";
+import { CLI_VERSION } from "./version.js";
+import { connectedAccount, login, logout, refreshStoredToken } from "./auth.js";
+import { connect, loadConfig, resolveConfig } from "./config.js";
+import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
+import { appRoot, assertKitCurrent, readKitLock, requestResourceName } from "./kit.js";
+import { initKit } from "./starter.js";
+import { agentPaths, agentSetup, cliVersionLines } from "./agent-setup.js";
+import { startDev } from "./dev.js";
+import { ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
+import { runChecks } from "./check.js";
+import { assertAiReady, GovernanceClient, groupGrants, IDENTITY_WORDS, integrationsCatalog, integrationsStatus, renderGrantGroup, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
+import { runJob } from "./jobs.js";
+const args = process.argv.slice(2);
+const command = args[0];
+const connectUrl = args[1];
+const root = optionValue("--app-root");
+const operationRef = optionValue("--operation");
+const json = args.includes("--json");
+const noWait = args.includes("--no-wait");
+const secretName = optionValue("--name");
+const profileName = optionValue("--name");
+const profileDescription = optionValue("--description");
+const audienceEmails = optionValue("--emails");
+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 operations = optionValue("--operations");
+const scheduledAt = optionValue("--scheduled-at");
+const realJob = args.includes("--real");
+/** Seconds `productionise`, `status --wait`, `retry` and `promote` follow the operation before reporting it as still running (default: 30 minutes). */
+const maxWaitSeconds = args.includes("--max-wait") ? Number(optionValue("--max-wait")) : undefined;
+const waitOptions = maxWaitSeconds ? { maxWaitMs: maxWaitSeconds * 1000 } : {};
+const includePaths = [];
+let optionError;
+if (maxWaitSeconds !== undefined && !(Number.isInteger(maxWaitSeconds) && maxWaitSeconds > 0))
+    optionError = "--max-wait takes a whole number of seconds.";
+if (command === "productionise" && ((profileName && !profileDescription) || (!profileName && profileDescription) || (audienceEmails && (!profileName || !profileDescription))))
+    optionError = "Productionise takes --name and --description together; --emails may be added only with both.";
+for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--include") {
+        const value = args[index + 1];
+        if (!value || value.startsWith("--")) {
+            optionError = "--include requires a relative file or directory path.";
+            break;
+        }
+        includePaths.push(value);
+        index += 1;
+    }
+}
+const explicitToken = process.env.ISOMORPH_TOKEN?.trim() ?? "";
+const usage = [
+    "Usage:",
+    "  isomorph connect <work-email-or-start-url>",
+    "  isomorph login | logout",
+    "  isomorph productionise --app-root <path> [--include <relative-path>]... [--name <text> --description <text> [--emails a@co,b@co]] [--no-wait] [--max-wait <seconds>] [--json]",
+    "  isomorph status --operation <reference> [--wait] [--max-wait <seconds>] [--json]",
+    "  isomorph retry --operation <reference> [--no-wait] [--max-wait <seconds>] [--json]",
+    "  isomorph promote --operation <reference> [--app-root <path>] [--no-wait] [--max-wait <seconds>] [--json]   (--app-root: also confirm the company's AI setup for production when the app calls governed AI)",
+    "  isomorph setup --operation <reference> [--json]            what the app still needs (name, audience, secrets)",
+    "  isomorph profile --operation <reference> [--name <text>] [--description <text>] [--json]",
+    "  isomorph audience --operation <reference> [--emails a@co,b@co] [--json]   (no --emails = only you)",
+    "  isomorph secrets list --operation <reference> [--json]",
+    "  isomorph secrets set --operation <reference> --name <NAME> [--personal] [--value-stdin]",
+    "  isomorph secrets dismiss --operation <reference> --name <NAME>",
+    "  isomorph agent-setup [--json]                               install the plain-English Isomorph skill for Claude Code (~/.claude/skills/isomorph) and Codex (~/.codex/skills/isomorph)",
+    "  isomorph init --app-root <path> [--upgrade]                 create the starter or add the kit files; --upgrade re-pins the kit bundle and moves an app set up by an older CLI to this kit (also runs agent-setup)",
+    "  isomorph dev --app-root <path> [--reset]                    run the app locally on one loopback origin (--reset deletes this app's local data)",
+    "  isomorph stop --app-root <path>                             stop this app's local services, keeping its database and files",
+    "  isomorph check --app-root <path> [--integrations] [--json]  types, build, then the pipeline's kit gate in the local session: declaration, migrations + database gate, write probe with cross-user denial, journeys, operation coverage (+ authorised real reads)",
+    "  isomorph jobs run <name> --app-root <path> [--scheduled-at <UTC>] [--real] [--json]  run one scheduled job now (local fixtures; --real uses approved company access)",
+    "  isomorph integrations request <connection> --app-root <path> [--reason <text>] [--operations a,b] [--json]   one request per connection, for every environment at once: IT approves it once (isomorph dev and productionise file it for you)",
+    "  isomorph integrations status --app-root <path> [--json]",
+    "  isomorph integrations catalog --app-root <path> [--json]   the company's connections as .isomorph/integrations.json names them: identifiers, allowed operations, approved channels/tables/views/mailboxes per environment (no app needed)",
+    "Run `isomorph connect <work-email-or-start-url>` once, then sign in when Isomorph asks.",
+    "productionise saves the app, follows its deployment, and prints the protected preview link; promote sends a tested preview to production.",
+    `--max-wait bounds how long productionise, status --wait, retry and promote follow the deployment (default 30 minutes). When it passes the command exits 0 with status RUNNING, the last known deployment state, and the \`${continueCommand("<reference>")}\` that continues the same deployment: a bounded wait is not a failure and never means start another one.`,
+    "For kit apps, productionise first files the access request for every connection in .isomorph/integrations.json (one per connection; IT approves it once for every environment) and exits 2 (INTEGRATIONS_NOT_READY) naming what IT still has to approve, asks governance whether the company's AI setup is ready when the app calls governed AI (exit 2, AI_NOT_READY, with the IT step), then runs the pipeline's kit gate in the local session and refuses (KIT_GATE_FAILED) what CodeBuild would refuse. promote asks the same AI question for production when --app-root names the app.",
+    "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", "jobs"];
+const progress = (message) => { process.stderr.write(`${message}\n`); };
+/** Envelope for commands that start no Isomorph operation (local kit commands, integrations). */
+const summaryEnvelope = (result) => ({ schema: "isomorph.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 (command === "agent-setup") {
+    const result = await agentSetup(process.env);
+    for (const state of ["created", "updated", "kept", "removed"])
+        for (const path of result[state])
+            progress(`${state.padEnd(7)} ${path}`);
+    if (result.removed.length)
+        progress("The guide is no longer in your global Codex instructions, where every session read it; Codex now has it as a skill, like Claude Code.");
+    progress("Claude Code and Codex: the `isomorph` skill is installed. Each agent uses it only for an Isomorph app (a folder with .isomorph/, or an app you ask it to build) and works as usual everywhere else. Say what you want to build; the agent installs and runs the kit itself.");
+    // Which `isomorph` the next command will run. This command is usually reached through
+    // `npx …@stable`, which tells you nothing about the CLI that does the actual work.
+    if (result.cli)
+        for (const line of cliVersionLines(result.cli))
+            progress(line);
+    emit(summaryEnvelope({ ...result, paths: agentPaths(process.env) }));
+}
+else if (!["connect", "login", "logout", "productionise", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
+    || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
+    || (["productionise", "status", "retry", "promote"].includes(command) && optionError)
+    || (command === "productionise" && !root)
+    || (LOCAL_COMMANDS.includes(command) && !root)
+    || (command === "jobs" && (subcommand !== "run" || !args[2] || args[2].startsWith("--")))
+    || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--")))))
+    || (OPERATION_COMMANDS.includes(command) && !operationRef)
+    || (command === "secrets" && (!subcommand || !["list", "set", "dismiss"].includes(subcommand) || (subcommand !== "list" && !secretName)))) {
+    if (optionError)
+        process.stderr.write(`${optionError}\n`);
+    process.stderr.write(usage);
+    process.exit(2);
+}
+else {
+    try {
+        if (command === "connect") {
+            const saved = await connect(connectUrl);
+            process.stdout.write(`Isomorph 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 = EMBEDDED_KIT_BUNDLE;
+            const target = appRoot(root);
+            // `init --upgrade` is the one command that moves an app from the old kit layout (initKit decides); every other one refuses it.
+            if (command !== "init")
+                await assertKitCurrent(target);
+            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, env: process.env });
+                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}`), ...["created", "updated"].flatMap(state => result.agents[state].map(path => `${state} ${path} (agent guide)`))])
+                    progress(line);
+                // Silent while the installed CLI is current; loud when `init` came from a
+                // newer package than the CLI that will run `dev`, `check` and `productionise`.
+                if (result.agents.cli?.upgradeRequired)
+                    for (const line of cliVersionLines(result.agents.cli))
+                        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 ISOMORPH_KIT_SDK_TARBALL to the bundle's ${bundle.sdk.package} tarball (or use a bundle with sdk.url), then rerun \`isomorph init\`.`);
+                progress(result.mode === "starter" ? "Starter created. Next: `isomorph dev --app-root <path>`. Codex reads the AGENTS.md block; Claude Code reads .claude/skills/isomorph-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 `isomorph connect <work-email-or-start-url>`.");
+                    const token = await companyToken();
+                    if (!token)
+                        throw new CliError("AUTH_REQUIRED", "`--integrations` needs an Isomorph sign-in: run `isomorph 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 .isomorph/local/check-report.json." } })}\n` : "Checks failed; see .isomorph/local/check-report.json.\n");
+                    process.exitCode = 1;
+                }
+                else
+                    emit(summaryEnvelope(report));
+            }
+            else if (command === "jobs") {
+                const result = await runJob(target, args[2], scheduledAt, runCommand, realJob);
+                progress(`Job ${result.name} completed for ${result.scheduledAt}.`);
+                emit(summaryEnvelope(result));
+            }
+            else {
+                const started = await startDev(target, { bundle, output: progress, reset, company: config ? { apiUrl: config.apiUrl, tenantId: config.tenantId, accessToken: companyToken, account: token => connectedAccount(config.mcpUrl, config.tenantId, token) } : undefined });
+                let stopping = false;
+                const shutdown = () => { if (stopping)
+                    return; stopping = true; progress("Stopping local Isomorph 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)
+                throw new CliError("CONFIG_REQUIRED", "Connect Isomorph first with `isomorph connect <work-email-or-start-url>`.");
+            const url = config.mcpUrl;
+            const tenant = config.tenantId;
+            if (command === "login") {
+                await login(url, tenant, progress);
+                process.stdout.write("Isomorph sign-in complete.\n");
+                process.exitCode = 0;
+            }
+            else if (command === "logout") {
+                await logout(url, tenant);
+                process.stdout.write("Isomorph sign-in removed from this device.\n");
+                process.exitCode = 0;
+            }
+            else {
+                const resolveToken = async () => explicitToken || await refreshStoredToken(url, tenant);
+                const token = await resolveToken();
+                if (!token)
+                    throw new CliError("AUTH_REQUIRED", "Please sign in to Isomorph with `isomorph login`.");
+                // 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 === "integrations") {
+                    const target = appRoot(root);
+                    await assertKitCurrent(target);
+                    const governance = new GovernanceClient(config.apiUrl, token, tenant);
+                    const result = subcommand === "status"
+                        ? await integrationsStatus(target, governance)
+                        : subcommand === "catalog"
+                            ? await integrationsCatalog(governance)
+                            : await requestIntegrations(target, governance, tenant, EMBEDDED_KIT_BUNDLE, { connection: args[2], ...(reason ? { reason } : {}), operations: operations?.split(",").map(value => value.trim()).filter(Boolean) });
+                    envelope = summaryEnvelope(result);
+                    if (!json)
+                        progress(subcommand === "status" ? renderIntegrationsStatus(result) : subcommand === "catalog" ? renderIntegrationsCatalog(result) : renderRequest(result));
+                }
+                else if (command === "productionise") {
+                    // Kit apps: the access requests are filed and the preview lane checked (and the app linked) before any operation starts, so productionise never mints a second app for the same root.
+                    const confirmedAppSetup = profileName && profileDescription
+                        ? { displayName: profileName, description: profileDescription, audienceEmails: audienceEmails ? audienceEmails.split(",").map(value => value.trim()).filter(Boolean) : [] }
+                        : undefined;
+                    await assertKitCurrent(appRoot(root));
+                    const result = await productionise(root, client, progress, tenant, includePaths, { waitForDeployment: !noWait, waitOptions, integrations: { governance: new GovernanceClient(config.apiUrl, token, tenant), bundle: EMBEDDED_KIT_BUNDLE }, ...(confirmedAppSetup ? { confirmedAppSetup } : {}) });
+                    envelope = operationEnvelope(result.result, result.operationRef, CLI_VERSION);
+                }
+                else {
+                    let summary;
+                    if (command === "status")
+                        summary = wait ? await follow(client, operationRef, progress, waitOptions) : summarize(await fetchStatus(client, operationRef));
+                    else if (command === "retry")
+                        summary = await retryDeployment(client, operationRef, progress, { wait: !noWait, waitOptions });
+                    else if (command === "promote") {
+                        // The production PLAN blocks on the same AI setup plus enforce mode; with the app root in hand, ask before promoting.
+                        if (root && config.apiUrl && await appCallsAi(appRoot(root))) {
+                            const lock = await readKitLock(appRoot(root));
+                            if (lock?.appId)
+                                await assertAiReady(lock.appId, "production", new GovernanceClient(config.apiUrl, token, tenant), progress);
+                        }
+                        summary = await promoteToProduction(client, operationRef, progress, { wait: !noWait, waitOptions });
+                    }
+                    else if (command === "setup")
+                        summary = { setup: await getAppSetup(client, operationRef) };
+                    else if (command === "profile")
+                        summary = { setup: await confirmProfile(client, operationRef, { ...(profileName ? { displayName: profileName } : {}), ...(profileDescription ? { description: profileDescription } : {}) }, progress) };
+                    else if (command === "audience")
+                        summary = { setup: await confirmAudience(client, operationRef, audienceEmails ? audienceEmails.split(",").map(value => value.trim()).filter(Boolean) : [], progress) };
+                    else if (subcommand === "list")
+                        summary = { secrets: await listSecrets(client, operationRef) };
+                    else if (subcommand === "set")
+                        summary = await setSecret(client, operationRef, { name: secretName, ...(personal ? { personal: true } : {}), readValue: valueStdin ? readSecretFromStdin : () => readSecretFromTerminal(`Value for ${secretName} (not shown): `) }, progress);
+                    else
+                        summary = await dismissSecret(client, operationRef, secretName, progress);
+                    envelope = operationEnvelope(summary, operationRef, CLI_VERSION);
+                }
+                process.stdout.write(json ? `${JSON.stringify(envelope)}\n` : renderSummary(envelope));
+            }
+        }
+    }
+    catch (error) {
+        const envelope = failureEnvelope(error, CLI_VERSION);
+        process.stderr.write(renderFailure(envelope));
+        if (json || command === "productionise")
+            process.stdout.write(`${JSON.stringify(envelope)}\n`);
+        // Exit 2, like a usage error: nothing started and the fix is a command the maker runs.
+        process.exit(envelope.error?.code === "INTEGRATIONS_NOT_READY" || envelope.error?.code === "AI_NOT_READY" ? 2 : 1);
+    }
+}
+/** One line per (connection, identity): the three lanes are one approval, so they are read together. */
+function renderIntegrationsStatus(status) {
+    if (!status.linked)
+        return "This app is not linked yet; `isomorph dev` (signed in) or `isomorph integrations request` links it.";
+    const lines = [`App ${status.appId}`, ...groupGrants(status.grants).flatMap(group => renderGrantGroup(group).map(line => `  ${line}`))];
+    for (const request of status.requests)
+        lines.push(`  request ${request.requestId}: ${request.state}${request.reason ? ` (${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.requests.map(item => `  ${IDENTITY_WORDS[item.identityMode]} — ${item.operations.join(", ")} on ${item.resources.map(requestResourceName).join(", ")}${item.presentation ? ` (posts as "${item.presentation.displayName}")` : ""}: ${item.state} — ${item.summary}`)].join("\n");
+}
+function optionValue(flag) {
+    const index = args.indexOf(flag);
+    const value = index >= 0 ? args[index + 1] : undefined;
+    return value && !value.startsWith("--") ? value : undefined;
+}

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

@@ -0,0 +1,97 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+export function configPath(env = process.env) {
+    return join(env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config"), "isomorph", "config.json");
+}
+export async function loadConfig(path = configPath()) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return validConfig(parsed) ? parsed : undefined;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw new Error("Isomorph could not read its saved connection. Run `isomorph connect <start-url>` again.");
+    }
+}
+export async function saveConfig(config, path = configPath()) {
+    if (!validConfig(config))
+        throw new Error("Isomorph received an incomplete connection profile.");
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await chmod(dirname(path), 0o700);
+    await writeFile(path, JSON.stringify(config, null, 2), { mode: 0o600 });
+    await chmod(path, 0o600);
+}
+export async function connect(startUrl, path = configPath()) {
+    const input = startUrl.trim();
+    const email = /^[^\s@]+@([a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+)$/i.exec(input);
+    const guessedTenant = email?.[1]?.split(".")[0]?.toLowerCase();
+    let url;
+    try {
+        url = new URL(guessedTenant ? `https://platform.isomorph.ai/start/${guessedTenant}.json` : input);
+    }
+    catch {
+        throw new Error("Enter your work email or the company setup link from your Isomorph start page: `isomorph connect <work-email-or-start-url>`.");
+    }
+    if (!/^https?:$/.test(url.protocol))
+        throw new Error("The Isomorph connection URL must be an HTTPS URL.");
+    if (!url.pathname.endsWith(".json")) {
+        url.pathname = `${url.pathname.replace(/\/$/, "")}.json`;
+    }
+    let config;
+    try {
+        const response = await fetch(url, { headers: { accept: "application/json" }, redirect: "error" });
+        if (!response.ok)
+            throw new Error("Isomorph could not read this company connection profile.");
+        const body = await response.json();
+        if (!isRecord(body) || body.schema !== "harbour.tenant-start/1.0")
+            throw new Error("This is not an Isomorph connection profile.");
+        config = {
+            schema: "isomorph.cli-config/1.0",
+            tenantId: String(body.tenantId ?? ""),
+            mcpUrl: String(body.mcpUrl ?? ""),
+            ...(typeof body.uploadUrl === "string" ? { uploadUrl: body.uploadUrl } : {}),
+            ...(typeof body.apiUrl === "string" ? { apiUrl: body.apiUrl } : {})
+        };
+        if (!validConfig(config) || (guessedTenant && config.tenantId !== guessedTenant))
+            throw new Error("This is not the expected Isomorph connection profile.");
+    }
+    catch (error) {
+        if (guessedTenant)
+            throw new Error("Isomorph could not find your company from that email. Ask for the company setup link from your Isomorph start page, then run `isomorph connect <company-start-url>`.");
+        throw error;
+    }
+    await saveConfig(config, path);
+    return config;
+}
+export function resolveConfig(env, saved) {
+    const mcpUrl = env.ISOMORPH_MCP_URL?.trim() || saved?.mcpUrl;
+    const tenantId = env.ISOMORPH_TENANT?.trim() || saved?.tenantId;
+    if (!mcpUrl || !tenantId)
+        return undefined;
+    return { schema: "isomorph.cli-config/1.0", tenantId, mcpUrl, ...(saved?.uploadUrl ? { uploadUrl: saved.uploadUrl } : {}), apiUrl: env.ISOMORPH_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)
+        && value.schema === "isomorph.cli-config/1.0"
+        && typeof value.tenantId === "string"
+        && value.tenantId.length > 0
+        && typeof value.mcpUrl === "string"
+        && /^https?:\/\//.test(value.mcpUrl)
+        && (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));
+}
+function isMissing(error) {
+    return Boolean(error && typeof error === "object" && error.code === "ENOENT");
+}

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

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { createForwarder } from "./forwarder.js";
+import { readKitLock } from "./kit.js";
+import { GovernanceClient, ensureLinkedApp, fileDeclaredRequests, IDENTITY_WORDS, renderGrantGroup } from "./integrations.js";
+import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, nodePackageCommand, releaseDevLock, runCommand } from "./local-runtime.js";
+import { CliError, safeError } from "./output.js";
+/**
+ * Signed in at startup: link the app and file the access request for every
+ * declared connection — one per connection, approved by IT once for every
+ * environment; the same filing `productionise` does — so IT's queue holds the
+ * ask from the first run and no command stands between the builder and the
+ * approval. Returns the banner lines saying where each connection stands.
+ * Never throws: `isomorph dev` runs without company access.
+ */
+export async function companyAccessAtStartup(root, client, tenantId, bundle) {
+    try {
+        const filed = await fileDeclaredRequests(root, client, tenantId, bundle);
+        // Nothing declared: still link, so governed AI has the app's identity from its first call.
+        if (!filed)
+            return { appId: await ensureLinkedApp(root, client, tenantId, bundle), lines: [] };
+        const lines = filed.groups.flatMap(group => renderGrantGroup(group));
+        for (const item of filed.requests)
+            if (item.error)
+                lines.push(`${item.connection} [${IDENTITY_WORDS[item.identityMode]}] not requested: ${item.error.message}`);
+        return { appId: filed.appId, lines };
+    }
+    catch (error) {
+        return { lines: [`Company access could not be checked (${safeError(error).message}); the app runs without it until the next start.`] };
+    }
+}
+/**
+ * Starts the kit-managed Postgres and App Gateway, applies migrations, then
+ * starts Vite and the loopback origin. Stopping retains the app's local data.
+ */
+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 ISOMORPH_KIT_SDK_TARBALL to the bundle's ${options.bundle.sdk.package} tarball (or use a bundle with sdk.url).`);
+        await runtime.writeFiles(options.bundle, ports);
+        options.output("Preparing the kit-managed native runtime (public registry, no login).");
+        await runtime.pull(options.bundle);
+        options.output("Starting local Isomorph services (postgres, storage, one Isomorph gateway with the session identities, fixtures and realtime relay).");
+        await runtime.up(options.output);
+        // The gateway writes the session env and the app's realtime outbox
+        // migration together once it is serving, so waiting for the session also
+        // waits for the SQL and for the gateway.
+        const session = await runtime.sessionEnv();
+        const applied = await runtime.migrate();
+        options.output(`Applied ${applied.length} migration file(s).`);
+        const watched = await runtime.installRealtimeOutbox();
+        // The gateway's in-process relay starts publishing as soon as the outbox
+        // table exists; nothing to create or restart.
+        if (watched > 0)
+            options.output(`Installed the Isomorph realtime outbox for ${watched} table(s) (isomorph.realtime change events).`);
+        const origin = `http://127.0.0.1:${ports.origin}`;
+        const npm = nodePackageCommand("npm", ["run", "dev"]);
+        vite = spawn(npm.command, npm.args, { cwd: root, env: { ...env, ISOMORPH_LOCAL_ORIGIN: origin, ISOMORPH_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.ISOMORPH_IDENTITY_CONTEXT,
+            apiUrl: company?.apiUrl ?? "", tenantId: company?.tenantId ?? "",
+            appId: () => lockAppId,
+            accessToken: async () => company ? company.accessToken() : undefined,
+            linkApp: async () => {
+                const token = company ? await company.accessToken() : undefined;
+                if (!company || !token)
+                    return undefined;
+                lockAppId = await ensureLinkedApp(root, new GovernanceClient(company.apiUrl, token, company.tenantId), company.tenantId, options.bundle);
+                return lockAppId;
+            },
+            onAuthRequired: () => { if (!warnedAuth) {
+                warnedAuth = true;
+                options.output("Company integrations need an Isomorph sign-in: run `isomorph 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 token = company ? await company.accessToken().catch(() => undefined) : undefined;
+        const governance = company && token ? new GovernanceClient(company.apiUrl, token, company.tenantId) : undefined;
+        const account = company && token ? await company.account(token).catch(() => undefined) : undefined;
+        const linkedAtStart = lockAppId;
+        options.output([
+            "",
+            `Isomorph dev is running: ${origin}`,
+            `  App identity (local session): ${session.HARBOUR_LOCAL_USER_EMAIL ?? "local-user@example.test"}; second user for cross-user checks: ${session.HARBOUR_LOCAL_SECOND_USER_EMAIL ?? "teammate@example.test"}`,
+            `  Company account for integrations: ${account ?? (company ? "not signed in — run `isomorph login`" : "not connected — run `isomorph connect`")}`,
+            ...(linkedAtStart ? [`  Linked app: ${linkedAtStart}`] : governance ? [] : ["  App not linked yet: the next `isomorph dev` after `isomorph login` links it and files its access requests (so does `isomorph integrations request`)."]),
+            "  Ctrl-C or `isomorph stop` stops the services and keeps local data; `isomorph dev --reset` deletes it.",
+            ""
+        ].join("\n"));
+        // Signed in: link now and file the app-wide requests — after the link is out, so governance's round-trips never hold it — and say where each connection stands.
+        if (governance && company) {
+            const access = await companyAccessAtStartup(root, governance, company.tenantId, options.bundle);
+            lockAppId = access.appId ?? lockAppId;
+            const lines = [...(access.appId && !linkedAtStart ? [`Linked app: ${access.appId}`] : []), ...access.lines];
+            if (lines.length)
+                options.output(lines.map(line => `  ${line}`).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 : "isomorph dev could not start.");
+    }
+}