@isomorph.ai/cli 0.2.0

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

@@ -0,0 +1,168 @@
+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"], "/_harbour/ai/chat": ["POST"], "/_harbour/ai/embed": ["POST"] };
+/** The governance development route family a local path forwards to, relative to /v1/development/apps/{appId}/. */
+function developmentTarget(path) { return path.startsWith("/_harbour/ai/") ? `ai/${path.slice("/_harbour/ai/".length)}` : `integrations/${path.slice("/_harbour/integrations/".length)}`; }
+const HOP_HEADERS = new Set(["connection", "keep-alive", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade", "host", "content-length"]);
+const IDENTITY_HEADER = "x-harbour-identity-context";
+/** The session identity for a gateway leg, unless the request already names one. */
+function identityHeaders(request, token) {
+    return request.headers[IDENTITY_HEADER] ? {} : { [IDENTITY_HEADER]: token };
+}
+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/") || path.startsWith("/_harbour/ai/")) {
+            void answerLocally(request, response, path, host, origin, options);
+            return;
+        }
+        if (path.startsWith("/_harbour/")) {
+            pipe(request, response, options.gatewayPort, identityHeaders(request, 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/") ? identityHeaders(request, 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", path.startsWith("/_harbour/ai/") ? "Unknown AI route." : "Unknown integration route.");
+        return;
+    }
+    const method = request.method ?? "GET";
+    if (!methods.includes(method)) {
+        reject(response, 405, "VALIDATION_FAILED", "Method not allowed.");
+        return;
+    }
+    const ai = path.startsWith("/_harbour/ai/");
+    const token = await options.accessToken().catch(() => undefined);
+    if (!token) {
+        options.onAuthRequired?.();
+        reject(response, 401, "AUTH_REQUIRED", ai ? "Sign in to Isomorph with `isomorph login` to use governed AI locally." : "Sign in to Isomorph with `isomorph login` to use company integrations locally.", "CLI_LOGIN_REQUIRED");
+        return;
+    }
+    // Governed AI needs the app's identity for its trace; a signed-in builder's app is linked on first use.
+    const appId = options.appId() ?? (ai && options.linkApp ? await options.linkApp().catch(() => undefined) : undefined);
+    if (!appId) {
+        reject(response, 409, "CONFLICT", ai ? "This app could not be linked with Isomorph yet; check `isomorph login` and try again." : "This app is not linked yet: restart `isomorph dev` now that you are signed in, or run `isomorph integrations request <connection> --app-root .` once.", "APP_NOT_LINKED");
+        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)}/${developmentTarget(path)}`;
+    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(ai ? 45_000 : 12_000) });
+    }
+    catch {
+        reject(response, 503, "UNAVAILABLE", "Isomorph 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);
+}
+/**
+ * An upgrade keeps the browser's own `Host` — this origin's — instead of the
+ * internal target port. A WebSocket server's same-origin defence compares
+ * `Origin` against `Host`: the App Gateway's `websocket.Accept` answers
+ * `403 request Origin "…" is not authorized for Host "…"` when they differ, so
+ * rewriting `Host` to the gateway's published port broke `/_harbour/realtime`
+ * (live updates fell back to polling) while every plain `/_harbour/*` call, which
+ * has no such check, kept working. Both targets listen on loopback and route by
+ * path, never by `Host`, and `sameOrigin` above has already rejected anything
+ * whose `Host`/`Origin` is not exactly this origin — forwarding the real pair is
+ * what lets the gateway's check do its job rather than defeating it.
+ */
+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 }))
+            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>Isomorph</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>";

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

@@ -0,0 +1,385 @@
+import { basename } from "node:path";
+import { linkIdempotencyKey, OPERATIONS, readDeclaration, readKitLock, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
+import { CliError } from "./output.js";
+export class GovernanceClient {
+    apiUrl;
+    token;
+    tenantId;
+    fetchImpl;
+    constructor(apiUrl, token, tenantId, fetchImpl = fetch) {
+        this.apiUrl = apiUrl;
+        this.token = token;
+        this.tenantId = tenantId;
+        this.fetchImpl = fetchImpl;
+    }
+    link(input) {
+        return this.call("POST", "/v1/development/apps/link", { tenantId: this.tenantId, ...input });
+    }
+    /** One app-wide request per (connection, identity): no environment and no expiry — IT approves once for every lane and sets any expiry itself. */
+    request(appId, input) {
+        return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/integration-requests`, { tenantId: this.tenantId, ...input });
+    }
+    list(appId) {
+        return this.call("GET", `/v1/development/apps/${encodeURIComponent(appId)}/integrations?tenantId=${encodeURIComponent(this.tenantId)}`);
+    }
+    /** Tenant-scoped: needs no linked app, so it answers on a builder's first turn. */
+    catalog() {
+        return this.call("GET", `/v1/development/integrations/catalog?tenantId=${encodeURIComponent(this.tenantId)}`);
+    }
+    execute(appId, body) {
+        return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/integrations/execute`, body);
+    }
+    /** Would this app's deployment PLAN pass for the environment? Read-only; governance answers from the company's AI setup. */
+    aiReadiness(appId, environment) {
+        return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/ai/readiness`, { environment });
+    }
+    async call(method, path, body) {
+        const url = `${this.apiUrl.replace(/\/$/, "")}${path}`;
+        const response = await this.fetchImpl(url, { method, headers: { authorization: `Bearer ${this.token}`, "x-harbour-tenant": this.tenantId, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error" })
+            .catch((error) => { throw new CliError("GOVERNANCE_UNREACHABLE", `Isomorph governance at ${new URL(url).host} could not be reached: ${transportFailure(error)}.`); });
+        const parsed = await response.json().catch(() => ({}));
+        if (response.status === 401)
+            throw new CliError("AUTH_REQUIRED", "Please sign in to Isomorph with `isomorph login`.");
+        if (!response.ok)
+            throw new CliError(parsed.error?.details?.code ?? parsed.error?.category ?? `HTTP_${response.status}`, parsed.error?.message ?? "Isomorph governance rejected the request.");
+        return (parsed.data ?? parsed);
+    }
+}
+/**
+ * What actually failed under a `fetch` rejection. undici reports every transport
+ * failure as `TypeError: fetch failed` and keeps the reason in `cause`: `getaddrinfo
+ * ENOTFOUND <host>`, `connect ECONNREFUSED <ip>:<port>`, a ConnectTimeoutError
+ * (UND_ERR_CONNECT_TIMEOUT, after 10 s), `unexpected redirect` under `redirect:
+ * "error"`, or an AggregateError with an empty message over one error per address
+ * tried. Observed 2026-09-12 (CLI 0.1.29): `isomorph check --integrations` printed
+ * `fetch failed` and nothing else, so what was wrong — and that nothing about the
+ * app was — could not be told from the output.
+ */
+function transportFailure(error) {
+    const cause = (error instanceof Error ? error.cause ?? error : error);
+    const words = (failure) => { const { message } = (failure ?? {}); return typeof message === "string" ? message.trim() : ""; };
+    const text = words(cause) || (Array.isArray(cause?.errors) ? cause.errors.map(words).filter(Boolean).join("; ") : "") || String(cause);
+    return typeof cause?.code === "string" && !text.includes(cause.code) ? `${text} (${cause.code})` : text;
+}
+/** Links the app once (stable idempotency key) and records the appId in kit.lock. */
+export async function ensureLinkedApp(root, client, tenantId, bundle) {
+    const lock = (await readKitLock(root)) ?? newKitLock(bundle, tenantId);
+    if (lock.appId)
+        return lock.appId;
+    const linked = await client.link({ displayName: basename(root), idempotencyKey: linkIdempotencyKey(tenantId, root) });
+    if (!linked.appId)
+        throw new CliError("LINK_FAILED", "Isomorph did not return an app identity for this app.");
+    await writeKitLock(root, { ...lock, appId: linked.appId, tenantId });
+    return linked.appId;
+}
+export const ENVIRONMENTS = ["development", "preview", "production"];
+export const IDENTITY_WORDS = { app: "as the company bot", user: "as the signed-in person" };
+/** A refusal about the leg rather than the ask — signed out, unreachable, an answer with no code — is nobody's ask and stops the run. */
+const legFailure = (code) => code === "AUTH_REQUIRED" || code === "GOVERNANCE_UNREACHABLE" || code.startsWith("HTTP_");
+/** One request per identity mode of the connection. A refusal of an ask is returned beside the others, not thrown, so a caller can report every connection at once. */
+async function submitRequests(client, appId, declaration, root, connection, reason, only) {
+    return Promise.all(requestScope(declaration, connection, only).map(async (part) => {
+        const ask = { connection, ...part };
+        try {
+            return { ...ask, outcome: await client.request(appId, { connection, identityMode: part.identityMode, operations: part.operations, resources: part.resources, ...(part.presentation ? { presentation: part.presentation } : {}), ...(reason?.trim() ? { reason: reason.trim() } : {}) }) };
+        }
+        catch (error) {
+            const refusal = unregisteredResourceGuidance(error, declaration, connection, root);
+            if (!(refusal instanceof CliError) || legFailure(refusal.code))
+                throw refusal;
+            return { ...ask, error: refusal };
+        }
+    }));
+}
+/** The filed asks with every refusal thrown, for the commands that cannot go on past one. */
+function settled(requests) {
+    return requests.map(item => { if (item.error)
+        throw item.error; return item; });
+}
+/**
+ * Files the app-wide request for every connection the app declares, one per
+ * identity mode — what `isomorph dev` (signed in) and `productionise` do before
+ * anything else, so IT's queue holds the ask from the first run and no command
+ * stands between a builder and an approval. Idempotent: governance answers
+ * READY for a scope IT has approved and PENDING with the existing request for
+ * one it is still deciding, so a repeat opens nothing. Links the app first
+ * (the same key as `integrations request`) and reads the lanes back, grouped.
+ * An app with no declaration or no connections is left alone: nothing to ask,
+ * so governance is not called.
+ */
+export async function fileDeclaredRequests(root, client, tenantId, bundle) {
+    const { declaration, errors } = await readDeclaration(root);
+    if (errors.length) {
+        if (errors[0].startsWith(".isomorph/integrations.json is missing"))
+            return undefined;
+        throw new CliError("DECLARATION_INVALID", `.isomorph/integrations.json is invalid: ${errors[0]}`);
+    }
+    const connections = Object.keys(declaration.connections);
+    if (!connections.length)
+        return undefined;
+    const appId = await ensureLinkedApp(root, client, tenantId, bundle);
+    const requests = (await Promise.all(connections.map(connection => submitRequests(client, appId, declaration, root, connection)))).flat();
+    return { appId, requests, groups: groupGrants((await client.list(appId)).grants) };
+}
+/**
+ * `isomorph integrations request`: the request for one connection (or the named
+ * subset of its operations) now, one per identity mode. Polls the grant list
+ * for up to 30 s; PENDING is reported as pending, never as ready.
+ */
+export async function requestIntegrations(root, client, tenantId, bundle, options) {
+    const { declaration, errors } = await readDeclaration(root);
+    if (errors.length)
+        throw new CliError("DECLARATION_INVALID", `.isomorph/integrations.json is invalid: ${errors[0]}`);
+    const appId = await ensureLinkedApp(root, client, tenantId, bundle);
+    const submitted = settled(await submitRequests(client, appId, declaration, root, options.connection, options.reason, options.operations)).map(item => ({ ...item, state: item.outcome.state }));
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const pollMs = options.pollMs ?? 3_000;
+    let grants = [];
+    for (let waited = 0;; waited += pollMs) {
+        grants = (await client.list(appId)).grants;
+        // A grant that already serves an older scope reads "ready" while this request (an expansion, a renewal,
+        // a changed per-app name) is still attached to it as pending: READY only once the grant no longer waits on it.
+        for (const item of submitted) {
+            const grant = grants.find(candidate => candidate.grantId === item.outcome.grantId);
+            // Guidance also rides on a grant that is still being retried ("attempt 1 of 3 …"); only a failed readiness ends the wait.
+            if (grant?.failure && grant.readiness === "failed")
+                throw failureError(grant.failure);
+            if (grant?.readiness === "ready" && grant.pendingRequestId !== item.outcome.requestId)
+                item.state = "READY";
+        }
+        if (!submitted.some(item => item.state === "PENDING") || waited >= 30_000)
+            break;
+        await sleep(pollMs);
+    }
+    const groups = groupGrants(grants);
+    return { appId, connection: options.connection, requests: submitted.map(item => ({
+            identityMode: item.identityMode, operations: item.operations, resources: item.resources, ...(item.presentation ? { presentation: item.presentation } : {}),
+            ...(item.outcome.requestId ? { requestId: item.outcome.requestId } : {}), grantId: item.outcome.grantId, state: item.state,
+            readiness: item.state === "PENDING" ? "pending" : grants.find(grant => grant.grantId === item.outcome.grantId)?.readiness ?? (item.state === "READY" ? "ready" : "denied"),
+            // The three lanes in one sentence, as `integrations status` prints them (the request itself names the anchor lane's grant).
+            summary: laneSummary(findGroup(groups, options.connection, item.identityMode), item.outcome.requestId)
+        })) };
+}
+const UNREGISTERED_RESOURCE = /^resource "([^"]+)" is not registered for \S+ on "([^"]+)"$/;
+/**
+ * Governance refuses a request that names a channel, table, view or mailbox IT has not
+ * registered on the connection (404 RESOURCE_NOT_APPROVED) before the Review
+ * queue ever sees it, so a builder cannot self-serve it. Observed: an agent
+ * read the raw refusal and told the person to email an administrator, who gave
+ * up. The code is kept for `--json`; the sentence names the resource, the one
+ * console place where IT adds it, and the command to run again afterwards.
+ */
+export function unregisteredResourceGuidance(error, declaration, connection, root) {
+    if (!(error instanceof CliError) || error.code !== "RESOURCE_NOT_APPROVED")
+        return error;
+    const match = UNREGISTERED_RESOURCE.exec(error.message);
+    if (!match)
+        return error;
+    const [, resource] = match;
+    const declared = declaration.connections[connection];
+    const operations = Object.keys(declared?.operations ?? {});
+    const provider = operations.some(name => name.startsWith("gmail.")) ? "Gmail" : operations.some(name => name.startsWith("slack.")) ? "Slack" : connection;
+    const place = declared?.kind === "database"
+        ? `Controls & integrations → Databases → ${connection} → Data resources`
+        : `Controls & integrations → API integrations → ${provider} → Configure → ${provider === "Gmail" ? "the mailbox" : "Channels"}`;
+    return new CliError(error.code, `IT has to add ${resource} to the ${connection} connection first (in the Isomorph console: ${place}); the app works without it until then, and once it is added run \`isomorph integrations request ${connection} --app-root ${root}\` again (\`isomorph dev\` and \`isomorph productionise\` file the request too).`, error.operationRef);
+}
+export function groupGrants(grants) {
+    const groups = new Map();
+    for (const grant of grants) {
+        const key = `${grant.identityMode}:${grant.connection}`;
+        const group = groups.get(key) ?? { connection: grant.connection, identityMode: grant.identityMode, lanes: {} };
+        if (ENVIRONMENTS.includes(grant.environment))
+            group.lanes[grant.environment] = grant;
+        groups.set(key, group);
+    }
+    return [...groups.values()].sort((a, b) => a.connection.localeCompare(b.connection) || a.identityMode.localeCompare(b.identityMode));
+}
+/** The group of one ask, or an empty one (no lane on file yet). */
+export function findGroup(groups, connection, identityMode) {
+    return groups.find(group => group.connection === connection && group.identityMode === identityMode) ?? { connection, identityMode, lanes: {} };
+}
+/** The open request of a group: it sits on the production lane (the anchor), so whichever lane record carries one names it. */
+export function openRequestId(lanes) {
+    return ENVIRONMENTS.map(lane => lanes[lane]?.pendingRequestId).find(Boolean);
+}
+/** A granted lane past IT's expiry (the server reads it as failed; the sentence says why). */
+const expired = (grant, nowMs) => grant.status === "GRANTED" && Boolean(grant.expiresAt && Date.parse(grant.expiresAt) <= nowMs);
+/** A lane a deploy can run on: granted, unexpired, not still provisioning or failed (a person's consent is asked in the app, at runtime). */
+const laneReady = (grant, nowMs) => grant.status === "GRANTED" && !expired(grant, nowMs) && grant.readiness !== "pending" && grant.readiness !== "failed";
+/** Builder-safe failure guidance as one sentence: what failed, then what to do. */
+export const failureSentence = (failure) => `${failure.message} ${failure.remediation}`;
+const failureError = (failure) => new CliError(failure.code, failureSentence(failure));
+/**
+ * One sentence for the three lanes: `ready in development, preview, production`
+ * when they agree, otherwise the lanes that differ — `development ready
+ * (preapproved until <ts>); preview, production waiting for IT (request <id>)`.
+ * A lane with no record yet is waiting on the group's open request (the list
+ * read right after filing may not carry the anchor yet, so the filing's own
+ * request id is the fallback). Development ready while another lane waits is
+ * the connection's development preapproval: the server writes that lane at
+ * filing time and keeps the request open for IT.
+ */
+export function laneSummary(group, requestHint, nowMs = Date.now()) {
+    const { lanes } = group;
+    const open = openRequestId(lanes) ?? requestHint;
+    const waitingOn = (lane) => { const grant = lanes[lane]; return grant ? (grant.readiness === "pending" ? grant.pendingRequestId ?? requestHint : undefined) : open; };
+    const word = (lane) => {
+        const grant = lanes[lane];
+        const request = waitingOn(lane);
+        if (!grant)
+            return { base: request ? `waiting for IT (request ${request})` : "not requested", suffix: "" };
+        if (expired(grant, nowMs))
+            return { base: `expired ${grant.expiresAt}`, suffix: "" };
+        const until = grant.expiresAt ? ` until ${grant.expiresAt}` : "";
+        switch (grant.readiness) {
+            case "ready": return { base: "ready", suffix: lane === "development" && ENVIRONMENTS.some(other => other !== lane && waitingOn(other)) ? ` (preapproved${until})` : until };
+            case "consent_required": return { base: "approved", suffix: " (connect your account in the app)" };
+            case "reconnect_required": return { base: "approved", suffix: " (reconnect your account in the app)" };
+            case "pending": return { base: request ? `waiting for IT (request ${request})` : "being set up", suffix: "" };
+            case "failed": return { base: grant.status === "DENIED" ? "denied" : grant.status === "REVOKED" ? "revoked" : "failed", suffix: "" };
+        }
+    };
+    const segments = [];
+    for (const lane of ENVIRONMENTS) {
+        const { base, suffix } = word(lane);
+        const segment = segments.find(candidate => candidate.base === base && candidate.suffix === suffix);
+        if (segment)
+            segment.lanes.push(lane);
+        else
+            segments.push({ base, suffix, lanes: [lane] });
+    }
+    return segments.length === 1 ? `${segments[0].base} in ${ENVIRONMENTS.join(", ")}${segments[0].suffix}` : segments.map(segment => `${segment.lanes.join(", ")} ${segment.base}${segment.suffix}`).join("; ");
+}
+/** The group's line — `company-slack [as the company bot] ready in development, preview, production` — plus the failure guidance of any lane, once per distinct failure. */
+export function renderGrantGroup(group, nowMs = Date.now()) {
+    const lines = [`${group.connection} [${IDENTITY_WORDS[group.identityMode]}] ${laneSummary(group, undefined, nowMs)}`];
+    const seen = new Set();
+    for (const lane of ENVIRONMENTS) {
+        const failure = group.lanes[lane]?.failure;
+        if (failure && !seen.has(failure.message)) {
+            seen.add(failure.message);
+            lines.push(`  ${failureSentence(failure)}`);
+        }
+    }
+    return lines;
+}
+/**
+ * `productionise` pre-check. Files the app-wide request for every declared
+ * connection (idempotent: READY comes straight back once IT has approved), then
+ * reads the preview lane — the one this deploy runs in — and refuses before any
+ * operation exists, naming exactly what is still waiting. Links the app when
+ * needed (the same key as `integrations request`) so both share one appId.
+ * Returns the kit appId, or undefined for a non-kit app.
+ */
+export async function assertPreviewIntegrationsReady(root, client, tenantId, bundle, output) {
+    const filed = await fileDeclaredRequests(root, client, tenantId, bundle);
+    if (!filed)
+        return (await readKitLock(root))?.appId || undefined;
+    const nowMs = Date.now();
+    const waiting = [];
+    for (const item of settled(filed.requests)) {
+        const group = findGroup(filed.groups, item.connection, item.identityMode);
+        const preview = group.lanes.preview;
+        // Guidance also rides on a lane that is still being retried; only a failed readiness is a refusal in its own words.
+        if (preview?.failure && preview.readiness === "failed")
+            throw failureError(preview.failure);
+        if (preview && laneReady(preview, nowMs))
+            continue;
+        const requestId = item.outcome.requestId ?? openRequestId(group.lanes);
+        waiting.push(requestId
+            ? `Waiting for IT: ${item.connection} ${IDENTITY_WORDS[item.identityMode]} (request ${requestId}).`
+            : `${item.connection} ${IDENTITY_WORDS[item.identityMode]} is not ready for the preview (${laneSummary(group, undefined, nowMs)}); ask IT to review this app's access in the Isomorph console.`);
+    }
+    if (!waiting.length)
+        return filed.appId;
+    output("Isomorph cannot deploy the preview yet:");
+    for (const line of waiting)
+        output(`  ${line}`);
+    throw new CliError("INTEGRATIONS_NOT_READY", `${waiting.join(" ")} IT approves a request once, for every environment; rerun productionise when it is approved.`);
+}
+/**
+ * `productionise` / `promote` pre-check for an app that calls governed AI
+ * (the local gate's inventory lists `ai` among its capabilities): the
+ * pipeline will ask governance for a PLAN over the inventory the kit shipped,
+ * and that PLAN blocks on the company's AI setup — no provider, no route, no
+ * budget, observe mode before production. Ask the same question here, before
+ * any build, and refuse with the one IT step, the way a missing grant is
+ * refused. Observed without it (fourier app-f578bfc2, 2026-09-12): a green
+ * check, a live preview, and a button that answered AI_UNAVAILABLE.
+ */
+export async function assertAiReady(appId, environment, client, output) {
+    const readiness = await client.aiReadiness(appId, environment);
+    if (readiness.ready) {
+        output(`Isomorph confirmed the company's AI setup for ${environment}.`);
+        return;
+    }
+    throw new CliError("AI_NOT_READY", readiness.plainEnglish);
+}
+/**
+ * Splits the declared operations of one connection by identity mode — the
+ * declaration's own `identity` (the gate has checked it against the closed
+ * set; an operation with one mode is read as that mode). The app-mode part
+ * that carries `slack.message.post` also carries the connection's declared
+ * presentation, so IT sees "posts as" on the request.
+ */
+export function requestScope(declaration, connection, only) {
+    const declared = declaration.connections[connection];
+    if (!declared)
+        throw new CliError("CONNECTION_NOT_DECLARED", `${connection} is not declared in .isomorph/integrations.json.`);
+    const names = (only?.length ? only : Object.keys(declared.operations));
+    const unknown = names.filter(name => !declared.operations[name]);
+    if (unknown.length)
+        throw new CliError("OPERATION_NOT_DECLARED", `${unknown.join(", ")} not declared for ${connection}.`);
+    const byMode = new Map();
+    for (const name of names) {
+        const allowed = OPERATIONS[name]?.identities ?? [];
+        const declaredMode = declared.operations[name].identity;
+        const mode = allowed.includes(declaredMode) ? declaredMode : allowed[0];
+        const entry = byMode.get(mode) ?? { operations: [], resources: new Map() };
+        entry.operations.push(name);
+        for (const resource of requestResources(declared.operations[name]))
+            entry.resources.set(requestResourceName(resource), resource);
+        byMode.set(mode, entry);
+    }
+    return [...byMode.entries()].map(([identityMode, entry]) => ({
+        identityMode, operations: entry.operations, resources: [...entry.resources.keys()].sort().map(key => entry.resources.get(key)),
+        ...(identityMode === "app" && entry.operations.includes("slack.message.post") && declared.presentation ? { presentation: declared.presentation } : {})
+    }));
+}
+/** Where connection, channel, table, view and mailbox names come from, so an agent never guesses one (2026-09-12: six of nineteen turns spent on refused guesses). */
+export async function integrationsCatalog(client) {
+    const listed = await client.catalog();
+    return { connections: listed.connections.map(entry => ({
+            connection: entry.connection, kind: entry.kind, ...(entry.provider ? { provider: entry.provider } : {}), ...(entry.connector ? { connector: entry.connector } : {}), ...(entry.installation ? { installation: entry.installation } : {}),
+            displayName: entry.displayName, status: entry.status,
+            operations: entry.operations.map(item => ({ operation: item.operation, identities: [...item.identities] })),
+            resources: Object.fromEntries(ENVIRONMENTS.map(environment => [environment, (entry.resources[environment] ?? []).map(resource => ({ name: resource.name, ...(resource.columns ? { columns: [...resource.columns] } : {}), ...(resource.description ? { description: resource.description } : {}) }))]))
+        })) };
+}
+const PROVIDER_WORDS = { slack: "Slack", gmail: "Gmail" };
+const INSTALLATION_WORDS = { installed: "bot installed", not_installed: "bot not installed yet: IT installs it in the Isomorph console", reconnect_required: "bot needs reconnecting: IT does that in the Isomorph console" };
+/** One block per connection: the identifier to declare, what it is, the allowed operations with their identity, and the approved names per environment. */
+export function renderIntegrationsCatalog(result) {
+    if (!result.connections.length)
+        return "No connections are registered for your company yet; IT adds them in the Isomorph console under Controls & integrations. Do not declare one until it is listed here.";
+    const lines = [];
+    for (const entry of result.connections) {
+        const what = entry.kind === "saas" ? `${PROVIDER_WORDS[entry.provider ?? ""] ?? entry.provider} connection` : `${entry.connector ?? "database"} warehouse`;
+        const state = [entry.status, ...(entry.installation && INSTALLATION_WORDS[entry.installation] ? [INSTALLATION_WORDS[entry.installation]] : [])].join(", ");
+        lines.push(`\`${entry.connection}\` — ${what} "${entry.displayName}" (${state})`);
+        lines.push(`  operations: ${entry.operations.map(item => `${item.operation} (${item.identities.join(" or ")})`).join(", ") || "none allowed"}`);
+        for (const environment of ENVIRONMENTS) {
+            const names = entry.resources[environment].map(resource => `${resource.name}${resource.description ? ` — ${resource.description}` : ""}${resource.columns?.length ? ` (${resource.columns.join(", ")})` : ""}`);
+            lines.push(`  ${environment}: ${names.join(", ") || "nothing approved yet"}`);
+        }
+    }
+    return lines.join("\n");
+}
+export async function integrationsStatus(root, client) {
+    const lock = await readKitLock(root);
+    if (!lock?.appId)
+        return { linked: false, grants: [], requests: [] };
+    const listed = await client.list(lock.appId);
+    return { appId: lock.appId, linked: true, grants: listed.grants.map(grant => ({ connection: grant.connection, environment: grant.environment, identityMode: grant.identityMode, status: grant.status, operations: grant.operations, resources: grant.resources, expiresAt: grant.expiresAt, readiness: grant.readiness, pendingRequestId: grant.pendingRequestId, failure: grant.failure })), requests: listed.requests };
+}

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

@@ -0,0 +1,53 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { CliError } from "./output.js";
+import { parseSessionEnv, readDevLock, runCommand } from "./local-runtime.js";
+import { kitPaths } from "./kit.js";
+const jobName = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const scheduleDeclaration = /^export\s+const\s+schedule\s*=\s*["']([^"']+)["']\s*;?\s*$/m;
+export async function discoverJobs(root) {
+    const directory = join(root, "jobs");
+    const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    const jobs = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".ts"))
+            continue;
+        const name = entry.name.slice(0, -3);
+        if (!jobName.test(name))
+            throw new CliError("JOB_INVALID", `jobs/${entry.name}: the file name must be a lowercase logical name.`);
+        const path = join(directory, entry.name);
+        const source = await readFile(path, "utf8");
+        const schedule = source.match(scheduleDeclaration)?.[1];
+        if (!schedule)
+            throw new CliError("JOB_INVALID", `jobs/${entry.name}: export one literal schedule, for example export const schedule = \"0 9 * * 1-5\".`);
+        if (!/^export\s+default\s+/m.test(source))
+            throw new CliError("JOB_INVALID", `jobs/${entry.name}: export one default job handler.`);
+        jobs.push({ name, schedule, path });
+    }
+    return jobs.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function runJob(root, name, scheduledAt, run = runCommand, real = false) {
+    if (!jobName.test(name))
+        throw new CliError("JOB_INVALID", "A valid job name is required.");
+    const job = (await discoverJobs(root)).find(candidate => candidate.name === name);
+    if (!job)
+        throw new CliError("JOB_NOT_FOUND", `No job named ${name} exists under jobs/.`);
+    const timestamp = scheduledAt ?? new Date().toISOString();
+    if (Number.isNaN(Date.parse(timestamp)))
+        throw new CliError("JOB_INVALID", "--scheduled-at must be an ISO 8601 timestamp.");
+    const session = await readFile(join(kitPaths(root).state, "session.env"), "utf8").catch(() => "");
+    const lock = await readDevLock(root);
+    if (!session || !lock)
+        throw new CliError("DEV_NOT_RUNNING", "Start `isomorph dev` before running a job so it uses the same local data and identity boundary.");
+    const env = parseSessionEnv(session);
+    const runner = `const module = await import(${JSON.stringify(pathToFileURL(job.path).href)}); if (typeof module.default !== "function") throw new Error("job has no default handler"); await module.default({scheduledAt: process.env.ISOMORPH_SCHEDULED_AT});`;
+    // Ordinary runs stay fixture-only. An explicit real run uses the same
+    // loopback origin as the browser, where the existing forwarder applies the
+    // builder's approved company/AI access.
+    const gatewayUrl = real ? lock.origin : `http://127.0.0.1:${lock.ports.gateway}`;
+    const result = await run(process.execPath, ["--experimental-strip-types", "--input-type=module", "--eval", runner], { cwd: root, env: { ...env, ISOMORPH_GATEWAY_URL: gatewayUrl, ISOMORPH_SCHEDULED_AT: timestamp } });
+    if (result.code !== 0)
+        throw new CliError("JOB_FAILED", `Job ${name} failed: ${result.stderr.trim().split("\n").at(-1) ?? "process exited non-zero"}`);
+    return { name, schedule: job.schedule, scheduledAt: timestamp, mode: real ? "real" : "local" };
+}