@fourier-labs/harbour 0.1.27 → 0.1.28

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

@@ -156,7 +156,8 @@ The person you are working with may not be a developer. They say what they want
 
 - "run it", "show me", "let me try it" → start \`harbour dev --app-root .\` in the background (it keeps running; the first start pulls images and takes a minute or two). Wait for the line \`Harbour dev is running: http://127.0.0.1:<port>\` and give them that link. Locally they are a fixture user; no company sign-in is needed.
 - "check it", "is it ok?", "is it ready?" → with dev running, \`harbour check --app-root . --json\`, then read \`.harbour/local/check-report.json\`. Failures in the app's code are yours to fix — fix, then check again until it is clean. Run the checks yourself after every change and before every ship, without being asked and without offering them as a choice.
-- "I need Slack / Gmail / the warehouse / company data" → a fresh \`harbour init\` declares no connection at all, which is why a new app ships with nothing waiting on IT. Declare the connection and only the operations the app really calls in \`.harbour/integrations.json\` (the closed set is in the per-app block), then \`harbour integrations request <connection> --reason "<what the app does with it>" --app-root . --json\`. READY means use it now. PENDING means IT has to approve it: say "IT has to approve this; the app works without it until then", and check later with \`harbour integrations status --app-root . --json\`. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
+- "I need Slack / Gmail / the warehouse / company data" → a fresh \`harbour init\` declares no connection at all, which is why a new app ships with nothing waiting on IT. Declare the connection and only the operations the app really calls in \`.harbour/integrations.json\` (the closed set is in the per-app block), then \`harbour integrations request <connection> --reason "<what the app does with it>" --app-root . --json\`. READY means use it now. PENDING means IT has to approve it: say "IT has to approve this; the app works without it until then", and check later with \`harbour integrations status --app-root . --json\`. A refusal with \`RESOURCE_NOT_APPROVED\` means the channel, view or mailbox is not on the connection yet: IT adds it in the Harbour console under Controls & integrations → API integrations → the provider tile → Configure → Channels (a warehouse view: Controls & integrations → Databases → the source → Views for the environment), and then you run the same request command again. Say "IT has to add <name> to the Slack connection first; the app works without it until then" and nothing more. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
+- "summarise", "draft", "explain", "AI" → one \`harbour.ai.chat\` call (through \`ai()\` in \`src/harbour.client.ts\`) behind a control the person presses; never an OpenAI/Anthropic key, SDK or URL. \`harbour check\` writes its journey. A refusal with \`AI_NOT_ENABLED\` means IT has to enable an AI provider: say so in one line and keep the app working without it.
 - "ship it", "put it online", "let my team try it" → run \`harbour check --app-root . --json\` first and fix everything it finds, every time, unasked: the same gates run again in the cloud, where each failed attempt costs minutes instead of the seconds it costs here. Then each declared connection needs a preview grant (\`harbour integrations request <connection> --environment preview --reason "…" --app-root . --json\`), and \`harbour productionise --app-root . --wait --json\` gives them \`result.deployment.protectedUrl\`: a private preview that they, and the people they name, open after company sign-in. Keep \`operationRef\`; \`harbour setup --operation <ref> --json\` lists what is still missing (name, audience, secrets) and \`harbour profile\` / \`harbour audience\` / \`harbour secrets set\` fill it in.
 - "make it live for everyone", "go to production" → only after they have tried the preview: \`harbour promote --operation <ref> --json\` with the operation reference from productionise. Report the production link, or that an operator approval is pending.
 - "stop it" → \`harbour stop --app-root .\` (local data kept). \`harbour dev --reset --app-root .\` deletes local data — only when they explicitly ask to start over.
@@ -165,9 +166,10 @@ When a command refuses, the refusal names its own reason and its own fix: change
 
 ## Building the app
 
-- Identity, data and files go through \`@harbour/app-sdk\` only: \`harbour.identity.current()\`, \`harbour.data.from(table)\`, \`harbour.files.*\`. Company systems go only through \`harbour.integrations.execute\` with declared operations. Never open a database, bucket or company URL from browser code, and never add another backend, auth library or deployment config: the kit is the whole path.
+- Identity, data and files go through \`@harbour/app-sdk\` only: \`harbour.identity.current()\`, \`harbour.data.from(table)\`, \`harbour.files.*\`. Company systems go only through \`harbour.integrations.execute\` with declared operations. AI goes through \`harbour.ai\`; never add an OpenAI/Anthropic key or SDK. Never open a database, bucket or company URL from browser code, and never add another backend, auth library or deployment config: the kit is the whole path.
 - Authentication is Harbour SSO: no login forms, no roles or ids trusted from the browser; row ownership is decided in SQL through \`current_setting('harbour.user_id', true)\`. Every route needs a signed-in person; no public routes.
 - Schema changes are SQL files in \`migrations/\` with row-level security and GRANTs to \`harbour_app_gateway\`; \`harbour dev\` and \`harbour check\` apply them.
+- Know the operation's input bounds before writing a call: \`slack.channel.history\` \`input.limit\` 1..15, \`gmail.thread.list\` \`input.limit\` 1..15, \`warehouse.view.read\` \`input.limit\` 1..1000 (the connector's \`VIEW_READ_MAX_LIMIT\`); anything larger is refused with \`INPUT_INVALID\`, so page instead of asking for more.
 - A Slack message or an email (\`slack.message.post\`, \`gmail.message.send\`) is sent only when the person presses an explicit Send control, with a fresh UUID \`idempotencyKey\` per press (reused only to retry that press). Never send from an effect, a timer, a queue or during checks. Consent is a user action (\`harbour.integrations.connect\`); missing consent never falls back to another account.
 - No secrets, tokens, \`.env\` values or fetched company content in source. \`.harbour/local/\` is never committed; \`.harbour/integrations.json\` and \`.harbour/kit.lock.json\` are.
 

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

@@ -1,56 +1,18 @@
 import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
-/**
- * One row per application table, as one JSON document. The scoping is the
- * database gate's own (`relkind` r/p outside pg_catalog, information_schema and
- * the platform's harbour_runtime), so "an application table" means the same
- * thing to the generator as it does to the gate that refuses the app.
- */
-const CATALOG_SQL = String.raw `
-SELECT coalesce(json_agg(t ORDER BY t.name), '[]'::json)::text FROM (
-  SELECT c.relname AS name,
-    (SELECT coalesce(json_agg(json_build_object(
-        'name', a.attname,
-        'type', format_type(a.atttypid, a.atttypmod),
-        'base', y.typname,
-        'category', y.typcategory,
-        'notnull', a.attnotnull,
-        'default', pg_get_expr(d.adbin, d.adrelid),
-        'generated', a.attidentity <> '' OR a.attgenerated <> '' OR coalesce(pg_get_expr(d.adbin, d.adrelid), '') LIKE 'nextval(%',
-        'fk', EXISTS (SELECT 1 FROM pg_constraint f WHERE f.conrelid = a.attrelid AND f.contype = 'f' AND a.attnum = ANY (f.conkey)),
-        'checks', (SELECT coalesce(json_agg(pg_get_constraintdef(k.oid)), '[]'::json) FROM pg_constraint k WHERE k.conrelid = a.attrelid AND k.contype = 'c' AND a.attnum = ANY (k.conkey))
-      ) ORDER BY a.attnum), '[]'::json)
-     FROM pg_attribute a
-     JOIN pg_type y ON y.oid = a.atttypid
-     LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
-     WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped) AS columns,
-    (SELECT coalesce(json_agg(k.attname ORDER BY u.ord), '[]'::json)
-     FROM pg_constraint p
-     CROSS JOIN LATERAL unnest(p.conkey) WITH ORDINALITY AS u(num, ord)
-     JOIN pg_attribute k ON k.attrelid = p.conrelid AND k.attnum = u.num
-     WHERE p.conrelid = c.oid AND p.contype = 'p') AS "primaryKey",
-    (SELECT coalesce(json_agg(concat_ws(' ', pg_get_expr(pol.polqual, pol.polrelid), pg_get_expr(pol.polwithcheck, pol.polrelid))), '[]'::json)
-     FROM pg_policy pol WHERE pol.polrelid = c.oid) AS policies
-  FROM pg_class c
-  JOIN pg_namespace n ON n.oid = c.relnamespace
-  WHERE c.relkind IN ('r', 'p')
-    AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'harbour_runtime')
-    AND n.nspname NOT LIKE 'pg\_toast%' AND n.nspname NOT LIKE 'pg\_temp%'
-) t;
-`;
 /** A policy that decides rows by the signed-in identity, and the column it decides them on. */
 const OWNER_SCOPE = /([A-Za-z_][A-Za-z0-9_]*)\s*(?:\)|::[a-z ]+)*\s*=\s*current_setting\('harbour\.user_(?:id|email)'/i;
 const IDENTITY = /current_setting\('harbour\.user_(?:id|email)'/i;
 /**
- * The app's tables as the database holds them, or `undefined` when the database
- * did not answer. `undefined` is not "no tables": nothing is generated from, or
+ * The app's tables as the database holds them, from the catalog the kit gate
+ * read after replaying the migrations, or `undefined` when that text is not a
+ * catalog. `undefined` is not "no tables": nothing is generated from, or
  * removed because of, a schema Harbour could not read — deleting an app's
  * retained checks on a failed query would be the worst possible reading of it.
  */
-export async function readAppSchema(source, root) {
-    const result = await source.psql(CATALOG_SQL, ["-At"]);
-    const text = result.stdout.trim();
-    if (result.code !== 0 || !text.startsWith("["))
+export async function readAppSchema(catalogText, root) {
+    const text = catalogText.trim();
+    if (!text.startsWith("["))
         return undefined;
     let catalog;
     try {
@@ -59,6 +21,8 @@ export async function readAppSchema(source, root) {
     catch {
         return undefined;
     }
+    if (!Array.isArray(catalog))
+        return undefined;
     const migrations = await migrationTexts(root);
     const schema = new Map();
     for (const table of catalog) {

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

@@ -1,123 +1,44 @@
 import { readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { readAppSchema } from "./app-schema.js";
-import { loadDatabaseGate } from "./database-gate.js";
-import { CoverageLedger, capabilityCallSurface, createCoverageProxy, declaredCapabilities, flowDetail, missingFlowOperations, orphanedChecks, sourceTableVerbs } from "./flow-coverage.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 { LOCAL, LocalRuntime, identityEnvironment, runCommand, runningOrigin } from "./local-runtime.js";
+import { LocalRuntime, allocatePorts, ensureSdk, freePort, readDevLock, runCommand, runningOrigin } from "./local-runtime.js";
 import { CLI_VERSION } from "./version.js";
-/** Runs the kit checks and writes `.harbour/local/check-report.json`; a source edit changes sourceDigest and so invalidates the previous report. */
+/** 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 `.harbour/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 = (name, status, detail) => { checks.push({ name, status, ...(detail ? { detail } : {}) }); output(`${status === "pass" ? "ok  " : status === "fail" ? "FAIL" : "skip"} ${name}${detail ? ` — ${indentLines(detail)}` : ""}`); };
-    const declaration = await readDeclaration(root);
-    record("declaration", declaration.errors.length ? "fail" : "pass", declaration.errors[0]);
-    let lockDetail;
-    const lock = await readKitLock(root).catch(error => { lockDetail = error instanceof Error ? error.message : String(error); return undefined; });
-    record("kit_lock", lock ? "pass" : "fail", lockDetail ?? (lock ? undefined : ".harbour/kit.lock.json is missing (run `harbour init`)"));
-    const typecheck = await run("npx", ["tsc", "--noEmit"], { cwd: root, quiet: true });
-    record("typecheck", typecheck.code === 0 ? "pass" : "fail", typecheck.code === 0 ? undefined : lastLines(typecheck.stdout || typecheck.stderr));
-    const build = await run("npm", ["run", "build"], { cwd: root, quiet: true });
-    record("build", build.code === 0 ? "pass" : "fail", build.code === 0 ? undefined : lastLines(build.stderr || build.stdout));
-    const throwaway = LocalRuntime.forCheck(root, run);
-    let schema;
-    try {
-        await throwaway.writeCheckFiles(bundle);
-        await throwaway.up();
-        const applied = await throwaway.migrate();
-        // The app's own tables, as the database holds them once those files have
-        // replayed. This is the only window in which that database exists, and
-        // reading it here is what lets `.harbour/checks/` be generated from the
-        // schema the app will really run against rather than from the SQL text.
-        schema = await readAppSchema(throwaway, root);
-        record("migrations", "pass", `${applied.length} file(s) applied to a disposable database`);
-        // The pipeline's database gate, on the database those files just built:
-        // the same script the in-loop probe runs after its replay, so the defect
-        // CodeBuild would name is named here, in seconds.
-        if (!applied.length)
-            record("database_gate", "not_run", "no migrations/*.sql to gate");
-        else {
-            const gate = await loadDatabaseGate(bundle, run);
-            const violations = await throwaway.databaseGate(gate.sql);
-            record("database_gate", violations.length ? "fail" : "pass", violations.length ? violations.join("\n") : `row-level security, policy verbs and grants verified for ${LOCAL.gatewayRole} (gate from ${gateSourceLabel(gate.source)})`);
-        }
-    }
-    catch (error) {
-        record("migrations", "fail", error instanceof Error ? error.message : String(error));
-        record("database_gate", "not_run", "the migrations did not replay");
-    }
-    finally {
-        await throwaway.down();
-    }
-    // `.harbour/checks/` is generated from what the app declares — the tables the
-    // database above holds, the SDK namespaces its own code calls — before
-    // anything reads it, so a check for a feature the app dropped cannot survive a
-    // single `harbour 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
-    // `flow` below still decides. Files Harbour did not write, and generated files
-    // the builder has edited, are never touched — and when the database did not
-    // answer, nothing is touched at all.
-    if (schema)
-        for (const line of describeRetainedChecks(await syncRetainedChecks(root, schema)))
-            output(line);
-    else
-        output(".harbour/checks/ was left as it is: the app's tables could not be read from the disposable database, so there was nothing to generate from.");
-    // After generation, because `.harbour/checks/*.mjs` is part of the deployed
-    // tree (kit.ts `sourceDigest`): the report has to pin the tree the journeys
-    // below actually run against, or `harbour productionise` would refuse the very
-    // tree this check just passed as CHECKS_STALE.
-    const source = await sourceDigest(root);
+    const record = (check) => { checks.push(check); output(renderCheck(check)); };
     const previous = await readReport(root);
-    if (previous && previous.sourceDigest !== source.digest)
+    if (previous && previous.sourceDigest !== (await sourceDigest(root)).digest)
         output("Source changed since the last report; the previous report is no longer valid.");
-    const origin = await (options.localOrigin ?? (() => runningOrigin(root)))();
-    const journeys = (await readdir(kitPaths(root).checks).catch(() => [])).filter(name => /\.(mjs|js|cjs)$/.test(name)).sort();
-    if (!journeys.length) {
-        record("journeys", "not_run", "no checks under .harbour/checks/");
-        record("flow", "not_run", "no checks under .harbour/checks/ to exercise the app's operations");
-    }
-    else if (!origin) {
-        record("journeys", "not_run", "harbour dev is not running; start it to exercise the journey checks");
-        record("flow", "not_run", "harbour dev is not running; the pipeline's operation-coverage gate needs the checks to run");
-    }
-    else {
-        // The journeys run through a recording proxy so this reports what the
-        // pipeline reports: which converted operations and declared capabilities
-        // the checks actually exercised at the gateway. They get the pipeline's
-        // three identity names from the running session (both signed users), so
-        // the SDK attaches the first identity itself and a cross-user check can
-        // act as the second — the same environment the retained-check runner
-        // gives them in CodeBuild.
-        const session = await new LocalRuntime(root, run).sessionEnv(1).catch(() => ({}));
-        const ledger = new CoverageLedger();
-        const proxy = createCoverageProxy(origin, ledger);
-        const appUrl = await proxy.listen();
-        try {
-            for (const name of journeys) {
-                // The journeys run one at a time, so naming the running check makes the
-                // gateway traffic that follows attributable to it — which is what lets
-                // an orphaned check be named as the file to delete.
-                ledger.nowRunning(name);
-                const result = await run("node", [join(kitPaths(root).checks, name)], { cwd: root, quiet: true, env: { HARBOUR_APP_URL: appUrl, HARBOUR_SDK_MODULE: join(root, "node_modules", "@harbour", "app-sdk", "dist", "index.js"), ...identityEnvironment(session) } });
-                ledger.nowRunning(undefined);
-                record(`journey:${name}`, result.code === 0 ? "pass" : "fail", result.code === 0 ? undefined : lastLines(result.stderr || result.stdout));
-            }
-        }
-        finally {
-            ledger.nowRunning(undefined);
-            await proxy.close();
-        }
-        // Both directions of the pipeline's gate: an operation or capability the
-        // app has with no check exercising it, and a check exercising a capability
-        // the app does not have.
-        const missing = missingFlowOperations(await sourceTableVerbs(root), await declaredCapabilities(root), ledger);
-        const orphaned = orphanedChecks(await capabilityCallSurface(root), ledger);
-        record("flow", missing.length || orphaned.length ? "fail" : "pass", flowDetail(missing, orphaned));
-    }
+    const typecheck = await run("npx", ["tsc", "--noEmit"], { cwd: root, quiet: true });
+    record({ name: "typecheck", status: typecheck.code === 0 ? "pass" : "fail", ...(typecheck.code === 0 ? {} : { detail: lastLines(typecheck.stdout || typecheck.stderr) }) });
+    const build = await run("npm", ["run", "build"], { 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 HARBOUR_KIT_SDK_TARBALL to the bundle's @harbour/app-sdk tarball (or use a bundle with sdk.url).");
+    const gate = await runKitGate(root, { run, bundle, output, ...(options.fetch ? { fetch: options.fetch } : {}) });
+    for (const check of gate.checks)
+        record(check);
     let integrations = "not tested";
+    const lock = await readKitLock(root).catch(() => undefined);
+    const declaration = await readDeclaration(root);
     if (options.governance && lock?.appId && !declaration.errors.length) {
         integrations = await testIntegrationReads(lock.appId, options.governance, declaration.declaration, output);
         if (!integrations.length)
@@ -125,18 +46,175 @@ export async function runChecks(root, options) {
     }
     else if (options.governance)
         output("Integrations were not tested: the app is not linked yet or the declaration is invalid.");
+    // After the gate, because `.harbour/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
+    // `harbour productionise` would refuse the very tree this check just passed
+    // as CHECKS_STALE.
+    const source = await sourceDigest(root);
     const report = {
         schema: "harbour.check-report/1.0",
         createdAt: new Date().toISOString(),
         sourceDigest: source.digest,
         toolchain: { node: process.version, cliVersion: CLI_VERSION, bundle: { kitVersion: bundle.kitVersion, sdkTarballSha256: bundle.sdk.tarballSha256, appGateway: bundle.images.appGateway, sessionFixture: bundle.images.sessionFixture, briefFingerprint: bundle.brief.fingerprint } },
         checks,
+        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
+ * gateway image's `gate` subcommand as a one-shot service of the Compose
+ * project (the app mounted read-only, a scratch database on the session
+ * PostgreSQL, the session bucket). 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 `.harbour/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 `harbour 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 = 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
+    // container that fails to start is exactly the case that used to 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)
+                    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, HARBOUR_SDK_MODULE: join(root, "node_modules", "@harbour", "app-sdk", "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();
+    }
+}
+/**
+ * `.harbour/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 `harbour 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 Harbour 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(".harbour/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 `harbour 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) {
+    if (await runningOrigin(root))
+        return false;
+    const lock = await readDevLock(root);
+    const ports = lock?.ports ?? await allocatePorts();
+    await runtime.writeFiles(bundle, ports);
+    output("harbour dev is not running; starting the local Harbour services for the gate (stopped again afterwards).");
+    await runtime.pull(bundle);
+    await runtime.up();
+    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 (no Docker) is reported and skipped — the pipeline's gate
+ * still runs.
+ */
+export async function preflightKitGate(root, bundle, output, run = runCommand, fetchImpl) {
+    const lock = await readKitLock(root).catch(() => undefined);
+    if (!lock)
+        return "skipped";
+    let report;
+    try {
+        report = await runKitGate(root, { run, bundle, output, ...(fetchImpl ? { fetch: fetchImpl } : {}) });
+    }
+    catch (error) {
+        if (error instanceof CliError && ["LOCAL_RUNTIME_FAILED", "KIT_IMAGES_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 \`harbour 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 = [];
@@ -180,44 +258,6 @@ async function testIntegrationReads(appId, client, declaration, output) {
     }
     return results;
 }
-/**
- * `productionise` pre-flight for a kit app with migrations: replays them on a
- * throwaway database and runs the pipeline's database gate before any
- * operation exists. A gate violation or a migration that will not replay is
- * refused here — the pipeline would refuse it minutes later in CodeBuild. A
- * local runtime that cannot start (no Docker) is reported and skipped: the
- * pipeline gate still runs.
- */
-export async function preflightDatabaseGate(root, bundle, output, run = runCommand) {
-    const lock = await readKitLock(root).catch(() => undefined);
-    const migrations = (await readdir(join(root, "migrations")).catch(() => [])).filter(name => name.endsWith(".sql"));
-    if (!lock || !migrations.length)
-        return "skipped";
-    const throwaway = LocalRuntime.forCheck(root, run);
-    try {
-        await throwaway.writeCheckFiles(bundle);
-        try {
-            await throwaway.up();
-        }
-        catch (error) {
-            output(`The migrations were not replayed locally (${error instanceof Error ? error.message : String(error)}); the pipeline's database gate will run in CodeBuild.`);
-            return "skipped";
-        }
-        await throwaway.migrate();
-        const gate = await loadDatabaseGate(bundle, run);
-        const violations = await throwaway.databaseGate(gate.sql);
-        if (violations.length)
-            throw new CliError("DATABASE_GATE_FAILED", `The migrations fail the pipeline's database gate (${violations.length} violation(s)):\n${violations.map(line => `  - ${line}`).join("\n")}\nFix migrations/ and run \`harbour check\`; the pipeline would refuse this deployment as kit.check-failed: aurora.database-gate.`);
-        output(`Migrations replayed and the database gate passed locally (${migrations.length} file(s), gate from ${gateSourceLabel(gate.source)}).`);
-        return "passed";
-    }
-    finally {
-        await throwaway.down();
-    }
-}
-function gateSourceLabel(source) {
-    return source === "gateway" ? "the pinned app gateway image" : source === "fixture" ? "the pinned session fixture" : "this CLI release";
-}
 export async function readReport(root) {
     try {
         return JSON.parse(await readFile(kitPaths(root).report, "utf8"));

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

@@ -68,12 +68,12 @@ const usage = [
     "  harbour init --app-root <path> [--upgrade]                 create the starter or add the kit files; --upgrade re-pins the kit bundle (also runs agent-setup)",
     "  harbour dev --app-root <path> [--reset]                    run the app locally on one loopback origin (--reset deletes this app's local data)",
     "  harbour stop --app-root <path>                             stop this app's local services, keeping data",
-    "  harbour check --app-root <path> [--integrations] [--json]  declaration, types, build, migrations + the pipeline's database gate (RLS, policy verbs, grants to harbour_app_gateway), journeys (+ authorised real reads)",
+    "  harbour 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)",
     "  harbour integrations request <connection> --reason <text> --app-root <path> [--environment <env>] [--operations a,b] [--expires-at <UTC>] [--json]",
     "  harbour integrations status --app-root <path> [--json]",
     "Run `harbour connect <company-start-url>` once, then sign in when Harbour asks.",
     "productionise saves the app, follows its deployment, and prints the protected preview link; promote sends a tested preview to production.",
-    "For kit apps, productionise first checks that every connection in .harbour/integrations.json has a preview grant and exits 2 (INTEGRATIONS_NOT_READY) with the requests to make, then replays migrations/ on a throwaway database and refuses (DATABASE_GATE_FAILED) what the pipeline's database gate would refuse.",
+    "For kit apps, productionise first checks that every connection in .harbour/integrations.json has a preview grant and exits 2 (INTEGRATIONS_NOT_READY) with the requests to make, then runs the pipeline's kit gate in the local session and refuses (KIT_GATE_FAILED) what CodeBuild would refuse.",
     "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");

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

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { createForwarder } from "./forwarder.js";
 import { readKitLock } from "./kit.js";
+import { GovernanceClient, ensureLinkedApp } from "./integrations.js";
 import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, releaseDevLock, runCommand } from "./local-runtime.js";
 import { CliError } from "./output.js";
 /**
@@ -55,6 +56,13 @@ export async function startDev(root, options) {
             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 a Harbour sign-in: run `harbour login` (in another terminal) and retry in the app.");

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

@@ -1,6 +1,8 @@
 import { createServer, request as httpRequest } from "node:http";
 import { connect } from "node:net";
-const INTEGRATION_ROUTES = { "/_harbour/integrations/execute": ["POST"], "/_harbour/integrations/connect": ["POST", "DELETE"] };
+const 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. */
@@ -12,7 +14,7 @@ export function createForwarder(options) {
     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/")) {
+        if (!sameOrigin(request, host, origin) || path.startsWith("/_harbour/integrations/") || path.startsWith("/_harbour/ai/")) {
             void answerLocally(request, response, path, host, origin, options);
             return;
         }
@@ -51,7 +53,7 @@ async function answerLocally(request, response, path, host, origin, options) {
     }
     const methods = INTEGRATION_ROUTES[path];
     if (!methods) {
-        reject(response, 404, "NOT_FOUND", "Unknown integration route.");
+        reject(response, 404, "NOT_FOUND", path.startsWith("/_harbour/ai/") ? "Unknown AI route." : "Unknown integration route.");
         return;
     }
     const method = request.method ?? "GET";
@@ -59,26 +61,28 @@ async function answerLocally(request, response, path, host, origin, options) {
         reject(response, 405, "VALIDATION_FAILED", "Method not allowed.");
         return;
     }
-    const appId = options.appId();
-    if (!appId) {
-        reject(response, 409, "CONFLICT", "This app is not linked yet. Run `harbour integrations request <connection> --reason <text>` once.", "APP_NOT_LINKED");
-        return;
-    }
+    const ai = path.startsWith("/_harbour/ai/");
     const token = await options.accessToken().catch(() => undefined);
     if (!token) {
         options.onAuthRequired?.();
-        reject(response, 401, "AUTH_REQUIRED", "Sign in to Harbour with `harbour login` to use company integrations locally.", "CLI_LOGIN_REQUIRED");
+        reject(response, 401, "AUTH_REQUIRED", ai ? "Sign in to Harbour with `harbour login` to use governed AI locally." : "Sign in to Harbour with `harbour 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 Harbour yet; check `harbour login` and try again." : "This app is not linked yet. Run `harbour integrations request <connection> --reason <text>` 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)}/integrations/${path.slice("/_harbour/integrations/".length)}`;
+    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(12_000) });
+        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", "Harbour governance could not be reached.", "PROVIDER_UNAVAILABLE");

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

@@ -62,7 +62,7 @@ export async function requestIntegrations(root, client, tenantId, bundle, option
         throw new CliError("USAGE", "--expires-at must be an ISO-8601 UTC timestamp.");
     const scope = requestScope(declaration, options.connection, options.operations);
     const appId = await ensureLinkedApp(root, client, tenantId, bundle);
-    const submitted = await Promise.all(scope.map(async (part) => ({ ...part, ...await client.request(appId, { connection: options.connection, environment, identityMode: part.identityMode, operations: part.operations, resources: part.resources, ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}), reason: options.reason }) })));
+    const submitted = await Promise.all(scope.map(async (part) => ({ ...part, ...await client.request(appId, { connection: options.connection, environment, identityMode: part.identityMode, operations: part.operations, resources: part.resources, ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}), reason: options.reason }).catch((error) => { throw unregisteredResourceGuidance(error, declaration, options.connection, environment, options.reason, root); }) })));
     const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
     const pollMs = options.pollMs ?? 3_000;
     let grants = [];
@@ -77,6 +77,31 @@ export async function requestIntegrations(root, client, tenantId, bundle, option
     }
     return { appId, connection: options.connection, environment, requests: submitted.map(item => ({ identityMode: item.identityMode, operations: item.operations, resources: item.resources, requestId: item.requestId, grantId: item.grantId, state: item.state, readiness: grants.find(grant => grant.grantId === item.grantId)?.readiness ?? (item.state === "READY" ? "ready" : item.state === "PENDING" ? "pending" : "denied") })) };
 }
+const UNREGISTERED_RESOURCE = /^resource "([^"]+)" is not registered for \S+ on "([^"]+)"$/;
+/**
+ * Governance refuses a request that names a channel, 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, environment, reason, 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} → Views for ${environment}`
+        : `Controls & integrations → API integrations → ${provider} → Configure → ${provider === "Gmail" ? "the mailbox" : "Channels"}`;
+    const command = `harbour integrations request ${connection} --reason "${reason}" --app-root ${root}${environment === "development" ? "" : ` --environment ${environment}`}`;
+    return new CliError(error.code, `IT has to add ${resource} to the ${connection} connection first (in the Harbour console: ${place}); the app works without it until then, and once it is added run \`${command}\` again.`, error.operationRef);
+}
 /**
  * `productionise` pre-check: the preview deploy holds until every declared
  * connection has a GRANTED, unexpired preview grant per identity mode, so the