@isomorph.ai/cli 0.2.0

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

@@ -0,0 +1,197 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+export const requestedOAuthScopes = "mcp";
+export function tokenStorePath(env = process.env) {
+    return join(env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config"), "isomorph", "tokens.json");
+}
+export function tokenStoreKey(mcpUrl, tenant) { return `${new URL(mcpUrl).toString()}|${tenant}`; }
+export async function loadStoredToken(mcpUrl, tenant, path = tokenStorePath()) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        const token = parsed.version === 1 ? parsed.tokens?.[tokenStoreKey(mcpUrl, tenant)] : undefined;
+        return validToken(token) ? token : undefined;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw new Error("Isomorph could not read its local sign-in record. Run `isomorph logout` and sign in again.");
+    }
+}
+export async function saveStoredToken(mcpUrl, tenant, token, path = tokenStorePath()) {
+    if (!validToken(token))
+        throw new Error("Isomorph received an incomplete sign-in response.");
+    let store = { version: 1, tokens: {} };
+    try {
+        store = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    if (store.version !== 1 || !store.tokens || typeof store.tokens !== "object")
+        store = { version: 1, tokens: {} };
+    store.tokens[tokenStoreKey(mcpUrl, tenant)] = token;
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await chmod(dirname(path), 0o700);
+    await writeFile(path, JSON.stringify(store), { mode: 0o600 });
+    await chmod(path, 0o600);
+}
+export async function clearStoredToken(mcpUrl, tenant, path = tokenStorePath()) {
+    const token = await loadStoredToken(mcpUrl, tenant, path);
+    if (!token)
+        return undefined;
+    const store = JSON.parse(await readFile(path, "utf8"));
+    delete store.tokens[tokenStoreKey(mcpUrl, tenant)];
+    if (Object.keys(store.tokens).length)
+        await writeFile(path, JSON.stringify(store), { mode: 0o600 });
+    else
+        await rm(path, { force: true });
+    return token;
+}
+export async function login(mcpUrl, tenant, output) {
+    const metadata = await discover(mcpUrl);
+    if (!metadata.registration_endpoint || !metadata.authorization_endpoint || !metadata.token_endpoint)
+        throw new Error("Isomorph sign-in is not available on this endpoint yet.");
+    const callback = await loopbackCallback();
+    try {
+        const registered = await json(metadata.registration_endpoint, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ client_name: "Isomorph CLI", redirect_uris: [callback.redirectUri], grant_types: ["authorization_code", "refresh_token"], response_types: ["code"], token_endpoint_auth_method: "none" }) });
+        if (!registered.client_id)
+            throw new Error("Isomorph did not register this sign-in session.");
+        const verifier = randomBytes(32).toString("base64url");
+        const state = randomBytes(24).toString("base64url");
+        const challenge = createHash("sha256").update(verifier).digest("base64url");
+        const authorize = new URL(metadata.authorization_endpoint);
+        authorize.search = new URLSearchParams({ response_type: "code", client_id: registered.client_id, redirect_uri: callback.redirectUri, scope: requestedOAuthScopes, state, resource: mcpUrl, code_challenge: challenge, code_challenge_method: "S256" }).toString();
+        output("Isomorph is opening your browser to sign in.");
+        openBrowser(authorize.toString());
+        output(`If it does not open, visit: ${authorize}`);
+        const code = await callback.wait(state);
+        const response = await token(metadata.token_endpoint, { grant_type: "authorization_code", client_id: registered.client_id, code, redirect_uri: callback.redirectUri, code_verifier: verifier });
+        await saveStoredToken(mcpUrl, tenant, { ...response, clientId: registered.client_id, tokenEndpoint: metadata.token_endpoint, ...(metadata.revocation_endpoint ? { revocationEndpoint: metadata.revocation_endpoint } : {}) });
+        output("Isomorph sign-in is complete.");
+    }
+    finally {
+        callback.close();
+    }
+}
+/** Refresh only when the access token is within this margin of expiry. */
+const REFRESH_MARGIN_MS = 5 * 60_000;
+/**
+ * Returns a usable access token, refreshing only when the stored one is about
+ * to expire. Refresh tokens are single-use, so every CLI process refreshing on
+ * start meant two processes at once (a `productionise` still polling and a
+ * `status` beside it) spent the same refresh token and one was told to sign in
+ * again. A refresh that fails now re-reads the store once: if a sibling
+ * process rotated the pair in the meantime, its newer token is used instead.
+ */
+export async function refreshStoredToken(mcpUrl, tenant, path = tokenStorePath(), now = Date.now) {
+    const stored = await loadStoredToken(mcpUrl, tenant, path);
+    if (!stored)
+        return undefined;
+    if (!stored.refreshToken)
+        return stored.accessToken;
+    if (stored.accessTokenExpiresAt !== undefined && stored.accessTokenExpiresAt - REFRESH_MARGIN_MS > now())
+        return stored.accessToken;
+    try {
+        const refreshed = await token(stored.tokenEndpoint, { grant_type: "refresh_token", client_id: stored.clientId, refresh_token: stored.refreshToken });
+        await saveStoredToken(mcpUrl, tenant, { ...stored, ...refreshed, refreshToken: refreshed.refreshToken ?? stored.refreshToken }, path);
+        return refreshed.accessToken;
+    }
+    catch {
+        const rotated = await loadStoredToken(mcpUrl, tenant, path);
+        if (rotated && rotated.refreshToken !== stored.refreshToken && (rotated.accessTokenExpiresAt === undefined || rotated.accessTokenExpiresAt - REFRESH_MARGIN_MS > now()))
+            return rotated.accessToken;
+        throw new Error("Isomorph sign-in expired or was revoked. Run `isomorph login` again.");
+    }
+}
+/**
+ * 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, 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, "/");
+    const protectedResource = await json(resource.toString());
+    const server = protectedResource.authorization_servers?.[0];
+    if (!server)
+        throw new Error("Isomorph did not advertise a sign-in service.");
+    const wellKnown = authorizationServerMetadataUrl(server);
+    const metadata = await json(wellKnown);
+    if (!metadata.authorization_endpoint || !metadata.token_endpoint || !metadata.registration_endpoint)
+        throw new Error("Isomorph sign-in metadata is incomplete.");
+    return { authorization_endpoint: metadata.authorization_endpoint, token_endpoint: metadata.token_endpoint, registration_endpoint: metadata.registration_endpoint, revocation_endpoint: metadata.revocation_endpoint ?? "" };
+}
+async function token(endpoint, values) {
+    const response = await json(endpoint, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(values), redirect: "error" });
+    if (!response.access_token)
+        throw new Error("Isomorph sign-in did not return an access token.");
+    return { accessToken: response.access_token, ...(response.refresh_token ? { refreshToken: response.refresh_token } : {}), ...(typeof response.expires_in === "number" && response.expires_in > 0 ? { accessTokenExpiresAt: Date.now() + response.expires_in * 1_000 } : {}) };
+}
+async function json(url, init) { const response = await fetch(url, { ...init, redirect: "error" }); if (!response.ok)
+    throw new Error(`Isomorph sign-in request failed (${response.status}).`); return response.json(); }
+export function authorizationServerMetadataUrl(server) { return `${server.replace(/\/$/, "")}/.well-known/oauth-authorization-server`; }
+function validToken(value) { return Boolean(value && typeof value === "object" && typeof value.accessToken === "string" && typeof value.clientId === "string" && typeof value.tokenEndpoint === "string"); }
+function isMissing(error) { return Boolean(error && typeof error === "object" && error.code === "ENOENT"); }
+function loopbackCallback() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        const timer = setTimeout(() => { server.close(); reject(new Error("Isomorph sign-in timed out. Run `isomorph login` again.")); }, 5 * 60_000);
+        server.on("request", (request, response) => {
+            const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+            const code = requestUrl.searchParams.get("code");
+            const state = requestUrl.searchParams.get("state");
+            response.writeHead(code && state ? 200 : 400, { "content-type": "text/plain; charset=utf-8" });
+            response.end(code && state ? "Isomorph sign-in complete. You can close this tab." : "Isomorph sign-in could not be completed.");
+            if (code && state)
+                server.callback = { code, state };
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                reject(new Error("Isomorph could not start local sign-in."));
+                return;
+            }
+            resolve({ redirectUri: `http://127.0.0.1:${address.port}/callback`, wait: expected => new Promise((done, fail) => {
+                    const poll = setInterval(() => { const callback = server.callback; if (!callback)
+                        return; clearInterval(poll); clearTimeout(timer); if (callback.state !== expected)
+                        fail(new Error("Isomorph sign-in returned an invalid state."));
+                    else
+                        done(callback.code); }, 25);
+                }), close: () => { clearTimeout(timer); server.close(); } });
+        });
+        server.on("error", reject);
+    });
+}
+function openBrowser(url) { const command = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open"; const args = platform() === "win32" ? ["/c", "start", "", url] : [url]; const child = spawn(command, args, { detached: true, stdio: "ignore" }); child.unref(); child.on("error", () => { }); }

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

@@ -0,0 +1,317 @@
+import { readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readAppSchema } from "./app-schema.js";
+import { describeRetainedChecks, syncRetainedChecks } from "./retained-checks.js";
+import { CliError } from "./output.js";
+import { DEPENDENT_READ_OPERATIONS, READ_OPERATIONS, kitPaths, readDeclaration, readKitLock, resourceNames, sourceDigest } from "./kit.js";
+import { LocalRuntime, allocatePorts, ensureSdk, freePort, nodePackageCommand, readDevLock, runCommand, runningOrigin } from "./local-runtime.js";
+import { CLI_VERSION } from "./version.js";
+/** The name the gate reports operation coverage under — the pipeline's rule for it. */
+export const FLOW_CHECK = "flow.check-failed";
+/**
+ * Runs the kit checks and writes `.isomorph/local/check-report.json`; a source
+ * edit changes sourceDigest and so invalidates the previous report. The app's
+ * own toolchain first (typecheck, build), then the kit gate — the pipeline's
+ * gate, run by the pinned gateway image in this app's local session — whose
+ * checks are reported verbatim. The retained journeys are generated inside
+ * that run, from the app's tables as the gate's replayed database holds
+ * them, before the gate enumerates and runs them.
+ */
+export async function runChecks(root, options) {
+    const { output, run, bundle } = options;
+    const checks = [];
+    const record = (check) => { checks.push(check); output(renderCheck(check)); };
+    const previous = await readReport(root);
+    if (previous && previous.sourceDigest !== (await sourceDigest(root)).digest)
+        output("Source changed since the last report; the previous report is no longer valid.");
+    const npx = nodePackageCommand("npx", ["tsc", "--noEmit"]);
+    const typecheck = await run(npx.command, npx.args, { cwd: root, quiet: true });
+    record({ name: "typecheck", status: typecheck.code === 0 ? "pass" : "fail", ...(typecheck.code === 0 ? {} : { detail: lastLines(typecheck.stdout || typecheck.stderr) }) });
+    const npm = nodePackageCommand("npm", ["run", "build"]);
+    const build = await run(npm.command, npm.args, { cwd: root, quiet: true });
+    record({ name: "build", status: build.code === 0 ? "pass" : "fail", ...(build.code === 0 ? {} : { detail: lastLines(build.stderr || build.stdout) }) });
+    // The journeys run here with the app's own node and SDK: the SDK the bundle
+    // pins, installed now if node_modules holds an older copy.
+    const sdk = await ensureSdk(root, bundle, options.env ?? process.env, run, output).catch(error => { output(error instanceof Error ? error.message : String(error)); return "missing"; });
+    if (sdk === "missing")
+        output(`The kit SDK is not installed: set ISOMORPH_KIT_SDK_TARBALL to the bundle's ${bundle.sdk.package} tarball (or use a bundle with sdk.url).`);
+    const gate = await runKitGate(root, { run, bundle, output, ...(options.fetch ? { fetch: options.fetch } : {}), ...(options.runtime ? { runtime: options.runtime } : {}) });
+    for (const check of gate.checks)
+        record(check);
+    let integrations = "not tested";
+    if (options.governance) {
+        // Reads that could not run are one check the report carries as not_run with
+        // the reason, beside the gate's own skipped checks where an agent reads
+        // outcomes — not exit 1 with the reason dropped, and not a stderr line beside
+        // `"not tested"`, the shape of a run that never asked. Observed 2026-09-12
+        // (CLI 0.1.29): every gate check passed, then the grant list's transport
+        // failure ended the run as `fetch failed` (CLI_FAILED) with no report written.
+        const skipped = (why) => record({ name: "integrations", status: "not_run", detail: why });
+        const lock = await readKitLock(root).catch(() => undefined);
+        const { declaration, errors } = await readDeclaration(root);
+        if (!lock?.appId)
+            skipped("the app is not linked yet; `isomorph dev` (signed in) or `isomorph integrations request` links it");
+        else if (errors.length)
+            skipped(`.isomorph/integrations.json is invalid: ${errors[0]}`);
+        else {
+            try {
+                integrations = await testIntegrationReads(lock.appId, options.governance, declaration, output);
+                if (!integrations.length)
+                    output("No READY development grants with read operations; real integrations were not exercised.");
+            }
+            catch (error) {
+                // Governance's answer about the grant list — unreachable, sign-in gone, a refusal — is about the leg, never about the app.
+                if (!(error instanceof CliError))
+                    throw error;
+                skipped(error.message);
+            }
+        }
+    }
+    // After the gate, because `.isomorph/checks/*.mjs` is part of the deployed
+    // tree (kit.ts `sourceDigest`) and the gate may have regenerated it: the
+    // report has to pin the tree the journeys actually ran against, or
+    // `isomorph productionise` would refuse the very tree this check just passed
+    // as CHECKS_STALE.
+    const source = await sourceDigest(root);
+    const report = {
+        schema: "isomorph.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,
+        gate,
+        integrations,
+        ai: "not tested",
+        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;
+}
+function renderCheck(check) {
+    const mark = check.status === "pass" ? "ok  " : check.status === "fail" ? "FAIL" : "skip";
+    return `${mark} ${check.name}${check.detail ? ` — ${indentLines(check.detail)}` : ""}`;
+}
+/**
+ * Runs the pipeline's kit gate in this app's local session: the pinned
+ * native gateway's `gate` subcommand as a one-shot process using the local
+ * session's scratch database and files. The gate's control API drives two things
+ * from here: the `checks` phase, where the gate hands over the app's tables
+ * as its replayed database holds them and `.isomorph/checks/` is regenerated
+ * from them (retained-checks.ts) and handed back as the set to run; and the
+ * journeys, run here — the app's own node and SDK — one at a time as the
+ * gate asks for them. The session services are started when `isomorph dev`
+ * is not running and stopped again afterwards.
+ */
+export async function runKitGate(root, options) {
+    const { run, bundle, output } = options;
+    const fetchImpl = options.fetch ?? fetch;
+    const runtime = options.runtime ?? new LocalRuntime(root, run);
+    const started = await ensureSession(root, runtime, bundle, output);
+    const port = await freePort();
+    const base = `http://127.0.0.1:${port}`;
+    const deadline = Date.now() + (options.timeoutMs ?? 10 * 60_000);
+    const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+    const request = async (path, init) => { try {
+        return await fetchImpl(`${base}${path}`, init);
+    }
+    catch {
+        return undefined;
+    } };
+    const post = (path, body) => request(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    // Everything after the session is up runs under one `finally`: a gate
+    // gate process that fails to start is exactly the case that could leave a
+    // session this run had started still running.
+    let container;
+    try {
+        container = await runtime.startGate(bundle, port, base);
+        let announced = false;
+        while (Date.now() < deadline) {
+            const done = await request("/_gate/report");
+            if (done?.status === 200) {
+                const result = await done.json();
+                if (result.report) {
+                    // The app is mounted read-only and the gate works on a mirror, so
+                    // what it authored for the app to ship comes home here — today the
+                    // governed-AI inventory (`.isomorph/ai-inventory.json`), which the
+                    // pipeline verifies against the source and which only the gate may
+                    // write. Written before the caller pins the tree digest, like the
+                    // regenerated retained checks.
+                    await writeGateFiles(root, result.files ?? {}, output);
+                    return result.report;
+                }
+                throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate could not run: ${result.error ?? "no report"}.`);
+            }
+            if (!(await runtime.gateRunning(container)))
+                throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate stopped before reporting: ${await runtime.gateLogs(container)}`);
+            const session = await request("/_gate/session");
+            const state = session?.status === 200 ? await session.json() : undefined;
+            if (state?.status === "checks") {
+                const files = await regenerateRetainedChecks(root, state.catalog, state.capabilities, output);
+                const posted = await post("/_gate/checks", { files });
+                if (posted?.status !== 200)
+                    throw new CliError("LOCAL_RUNTIME_FAILED", "The kit gate did not accept the retained checks.");
+                continue;
+            }
+            if (state?.status === "journeys" && state.current && state.environment) {
+                if (!announced) {
+                    announced = true;
+                    output("Running the retained journeys against the gate's App Gateway.");
+                }
+                const name = state.current;
+                const result = await run("node", [join(kitPaths(root).checks, name)], { cwd: root, quiet: true, env: { ...state.environment, ISOMORPH_SDK_MODULE: join(root, "node_modules", ...bundle.sdk.package.split("/"), "dist", "index.js"), NODE_NO_WARNINGS: "1" } });
+                const posted = await post(`/_gate/journeys/${encodeURIComponent(name)}`, { code: result.code, output: `${result.stdout}${result.stderr}`.slice(-4000) });
+                if (posted?.status !== 200)
+                    throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate did not accept the result of ${name}.`);
+                continue;
+            }
+            await sleep(options.pollMs ?? 500);
+        }
+        throw new CliError("LOCAL_RUNTIME_FAILED", "The kit gate did not finish within its budget.");
+    }
+    finally {
+        if (container)
+            await runtime.stopGate(container);
+        if (started)
+            await runtime.down();
+    }
+}
+/**
+ * `.isomorph/checks/` is generated from what the app declares — the tables the
+ * gate's replayed database holds, the capabilities the gate derived from the
+ * source (the set its coverage gate will demand evidence for) —
+ * before the gate reads it, so a check for a feature the app dropped cannot
+ * survive a single `isomorph check`, and a feature it added arrives with its
+ * journey. This is not one of the gates: it writes files and reports what it
+ * did, and the gate's coverage check still decides. Files Isomorph did not
+ * write, and generated files the builder has edited, are never touched — and
+ * when the catalog is not one, nothing is touched at all. Resolves to the
+ * complete set the gate is to run.
+ */
+async function regenerateRetainedChecks(root, catalog, capabilities, output) {
+    const schema = await readAppSchema(typeof catalog === "string" ? catalog : JSON.stringify(catalog ?? null), root);
+    if (schema)
+        for (const line of describeRetainedChecks(await syncRetainedChecks(root, schema, Array.isArray(capabilities) ? capabilities : undefined)))
+            output(line);
+    else
+        output(".isomorph/checks/ was left as it is: the app's tables could not be read from the gate's database, so there was nothing to generate from.");
+    const directory = kitPaths(root).checks;
+    const names = (await readdir(directory).catch(() => [])).filter(name => /\.(mjs|js|cjs)$/.test(name)).sort();
+    const files = {};
+    for (const name of names)
+        files[name] = await readFile(join(directory, name), "utf8");
+    return files;
+}
+/** Brings the session services up when `isomorph dev` is not running; resolves to whether they were started here (and so are taken down again after the gate, data kept). */
+async function ensureSession(root, runtime, bundle, output) {
+    const lock = await readDevLock(root);
+    if (lock && await runningOrigin(root)) {
+        await runtime.attach(bundle, lock.ports);
+        return false;
+    }
+    const ports = lock?.ports ?? await allocatePorts();
+    await runtime.writeFiles(bundle, ports);
+    output("isomorph dev is not running; starting the local Isomorph services for the gate (stopped again afterwards).");
+    await runtime.pull(bundle);
+    await runtime.up(output);
+    await runtime.sessionEnv();
+    return true;
+}
+/**
+ * `productionise` pre-flight for a kit app: the same gate the pipeline runs,
+ * here, before any operation exists. A failed check is refused with the
+ * pipeline's own wording (kit.check-failed: <check>); a local runtime that
+ * cannot start is reported and skipped — the pipeline's gate
+ * still runs.
+ */
+export async function preflightKitGate(root, bundle, output, run = runCommand, fetchImpl, runtime) {
+    const lock = await readKitLock(root).catch(() => undefined);
+    if (!lock)
+        return "skipped";
+    let report;
+    try {
+        report = await runKitGate(root, { run, bundle, output, ...(fetchImpl ? { fetch: fetchImpl } : {}), ...(runtime ? { runtime } : {}) });
+    }
+    catch (error) {
+        if (error instanceof CliError && ["LOCAL_RUNTIME_FAILED", "KIT_IMAGES_UNAVAILABLE", "KIT_RUNTIME_UNAVAILABLE"].includes(error.code)) {
+            output(`The kit gate was not run locally (${error.message}); the pipeline's gate will run in CodeBuild.`);
+            return "skipped";
+        }
+        throw error;
+    }
+    const failed = report.checks.filter(check => check.status === "fail");
+    if (failed.length)
+        throw new CliError("KIT_GATE_FAILED", `The kit gate refused this app (${failed.length} check(s) failed):\n${failed.map(check => `  - ${check.name}: ${check.detail ?? ""}`).join("\n")}\nFix the app and run \`isomorph check\`; the pipeline would refuse this deployment as kit.check-failed: ${failed[0].name}.`);
+    output(`The kit gate passed locally (${report.checks.length} checks; ${report.inventory.journeys.length} journey(s), ${report.inventory.migrations} migration(s)).`);
+    return "passed";
+}
+// ---- Real integrations ----------------------------------------------------------------
+/** 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); }
+/** A multi-line detail (one gate violation per line) keeps its lines, each under the check name. */
+function indentLines(detail) { return detail.split("\n").map((line, index) => index ? `      ${line}` : line).join("\n"); }
+/** Files the gate authored for the app (path → content, or null to remove), confined to `.isomorph/`. */
+export async function writeGateFiles(root, files, output) {
+    for (const [path, content] of Object.entries(files)) {
+        if (!/^\.isomorph\/[A-Za-z0-9._-]+$/.test(path))
+            throw new CliError("LOCAL_RUNTIME_FAILED", `The kit gate named a file outside .isomorph/: ${path}.`);
+        const target = join(root, path);
+        if (content === null) {
+            await rm(target, { force: true });
+            output(`Removed ${path}: the app no longer needs it.`);
+        }
+        else {
+            await writeFile(target, content);
+            output(`Wrote ${path}.`);
+        }
+    }
+}