@isomorph.ai/cli 0.2.0

package/README.md

@@ -0,0 +1,55 @@
+# @isomorph.ai/cli
+
+The Isomorph development kit CLI: sets up, runs, checks and ships an Isomorph app. It is meant to be driven by an AI coding agent (Claude Code or Codex) on your behalf; you can also use it directly.
+
+## Quick start (no coding needed)
+
+You describe the app in plain English inside Claude Code or Codex; the agent installs and runs everything. One paste, once per computer:
+
+```
+npx -y @isomorph.ai/cli agent-setup
+```
+
+Paste that line into Claude Code or Codex (or a terminal). It teaches both agents the kit by installing the `isomorph` skill for each (`~/.claude/skills/isomorph/SKILL.md`, `~/.codex/skills/isomorph/SKILL.md`) and never touches your other skills or instructions. A skill is read only when the task matches it — a folder with `.isomorph/`, an app you ask for on Isomorph — so the agent works exactly as before on everything else. (Releases before 0.1.34 put the guide in your global Codex instructions, `~/.codex/AGENTS.md`, where every Codex session read it; running the line again takes that block out and leaves the rest of the file as it was.)
+
+That `npx` line runs the current release, but `isomorph init`, `dev` and `check` afterwards run whatever `isomorph` is installed on this machine. So `agent-setup` also compares the two and says, in its output and in `result.cli` of `--json` (`state`, `upgradeRequired`, `remediation`), when the installed CLI is missing or behind — a stale one carries an old kit bundle and builds an app the deployment pipeline refuses. The fix is always `npm i -g @isomorph.ai/cli`.
+
+Then, in an empty folder:
+
+1. Say what you want, for example "Build me a small app where my team can vote on lunch options and see the results live."
+2. Say "run it" — the agent starts it and gives you a link to open.
+3. Say "check it" — the agent runs the checks and tells you in plain words what passed and what it fixed.
+4. Say "I need Slack" (or Gmail, or the warehouse) — the agent asks IT for access and tells you when it is approved.
+5. Say "ship it" — the agent puts a private preview online and gives you the link; "make it live for everyone" promotes it after you have tried it.
+
+The only step you do yourself is the company sign-in: when the agent runs `isomorph login`, your browser opens and you sign in there. You need Node 22+ on macOS Apple silicon, Linux x64 or Windows x64; Isomorph installs its local database, files and gateway without Docker. Full walkthrough: [docs/vibecoding.md](../../docs/vibecoding.md).
+
+## Commands
+
+```
+isomorph agent-setup                                        install the `isomorph` skill for Claude Code and Codex; idempotent; reports a missing or stale installed CLI
+isomorph init --app-root <path> [--upgrade]                 starter app in an empty folder, or kit files in a Vite + React app (also runs agent-setup); --upgrade re-pins the kit bundle
+isomorph dev --app-root <path> [--reset]                    run the app locally on one loopback origin
+isomorph stop --app-root <path>                             stop local services, keep data
+isomorph check --app-root <path> [--integrations] [--json]  declaration, types, build, migrations, journeys; report in .isomorph/local/check-report.json
+isomorph integrations catalog --app-root <path> [--json]   the company's connections as .isomorph/integrations.json names them, with approved channels/views per environment
+isomorph integrations request <connection> --app-root <path> [--reason <text>]   one request per connection; IT approves it once for every environment (`isomorph dev` and `isomorph productionise` file it for you)
+isomorph integrations status --app-root <path> [--json]
+isomorph connect <work-email-or-start-url>                        once per company; then isomorph login | logout
+isomorph productionise --app-root <path> [--wait] [--json]  save + preview deployment, prints the protected link
+isomorph status | retry | promote | setup | profile | audience | secrets … --operation <reference>
+```
+
+`productionise`, `status --wait`, `retry` and `promote` follow the deployment for up to `--max-wait <seconds>` (default 30 minutes). Past that they exit 0 with `status: "RUNNING"` and the `isomorph status --operation <reference> --wait --max-wait 120 --json` that continues the same deployment — a bounded wait is not a failure, and never a reason to start another deploy.
+
+`isomorph --help` prints the full usage. Local commands need no company sign-in; integrations and shipping do.
+
+## Apps set up by the old `harbour` CLI
+
+Before 0.2.0 the CLI was published as `@fourier-labs/harbour` with the command `harbour`, and it kept the kit's files under `.harbour/`. That layout is not read any more — not by this CLI and not by the deployment pipeline. Run `isomorph init --upgrade --app-root .` once in each such app: it renames `.harbour/` to `.isomorph/` (git records renames), moves the two committed schema ids with it, rewrites the managed block in CLAUDE.md / AGENTS.md and the project skill, deletes the checks the old kit generated (the next `isomorph check` regenerates them) and rewrites the SDK package name and its exported type names in `package.json`, `src/`, `jobs/` and the checks you wrote yourself. Every other command refuses an un-upgraded app and names that command. The old CLI can stay installed; it no longer deploys.
+
+## Development
+
+Built from the [governance control plane](https://github.com/Fourier-Labs-AI/harbour-governance-control-plane) repository: `npm ci`, `npm run build --prefix packages/harbour-cli`, tests in `tests/cli-kit.test.ts` and `tests/cli-packaging-contract.test.ts`. Releases are tagged `cli-v<version>` (a `-rc.N` candidate first, then the stable tag).
+
+Connect with `isomorph connect name@getlokal.com`: the CLI tries `https://platform.isomorph.ai/start/getlokal.json` and validates the profile before saving it. This uses the first domain label as a guess, not a domain registry; subdomains or companies whose tenant name differs should use their company setup link. Only the guessed tenant name is sent, not the email. Company sign-in and access checks still apply.

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

@@ -0,0 +1,235 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { CLI_VERSION } from "./version.js";
+import { continueCommand } from "./operations.js";
+const execFileAsync = promisify(execFile);
+export const MANAGED_START = "<!-- isomorph:kit:start -->";
+export const MANAGED_END = "<!-- isomorph:kit:end -->";
+/**
+ * The one command that installs or upgrades the CLI. It carries no dist-tag: npm resolves an
+ * untagged name through `latest`, which is what a release publishes, so every instruction in
+ * the kit names the package the same way a person typing it from memory would (LLD §15.5).
+ */
+export const CLI_INSTALL_COMMAND = "npm i -g @isomorph.ai/cli";
+/**
+ * Where the two agents read the user-level guide from; both honour the tools' own
+ * override variables. Both are skills — a file each tool lists by name and description
+ * and reads in full only when the task matches — so the guide costs nothing in every
+ * other session. `legacyCodexAgents` is Codex's global AGENTS.md, which releases up to
+ * 0.1.33 wrote the guide into; Codex reads that file in every session, in every
+ * folder, so the kit's rules for a non-developer's Isomorph app ("never paste logs",
+ * "end every report with three lines") were applied to all of a person's other work.
+ */
+export function agentPaths(env = process.env) {
+    const home = env.ISOMORPH_AGENT_HOME?.trim() || homedir();
+    const codexHome = env.CODEX_HOME?.trim() || join(home, ".codex");
+    return {
+        claudeSkill: join(env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), "skills", "isomorph", "SKILL.md"),
+        codexSkill: join(codexHome, "skills", "isomorph", "SKILL.md"),
+        legacyCodexAgents: join(codexHome, "AGENTS.md")
+    };
+}
+/**
+ * Installs the user-level Isomorph skill for Claude Code and Codex (one file each,
+ * wholly owned by the kit) and takes the guide back out of Codex's global AGENTS.md
+ * where an older release put it, keeping everything else in that file. Idempotent:
+ * unchanged files are reported as kept. Also reports which `isomorph` the agent's next
+ * command will run (`result.cli`), because this command is routinely reached through
+ * `npx` while everything after it is not.
+ */
+export async function agentSetup(env = process.env, lookups = {}) {
+    const paths = agentPaths(env);
+    const result = { created: [], updated: [], kept: [], removed: [], cli: await checkCliVersion(lookups) };
+    for (const skill of [paths.claudeSkill, paths.codexSkill])
+        result[await upsertManagedBlock(skill, `${SKILL_FRONTMATTER}\n${AGENT_GUIDE}`, {})].push(skill);
+    if (await removeManagedBlock(paths.legacyCodexAgents, { start: MANAGED_START, end: MANAGED_END }))
+        result.removed.push(paths.legacyCodexAgents);
+    return result;
+}
+/** Compares the globally resolvable `isomorph` with the package this process runs from. */
+export async function checkCliVersion(lookups = {}) {
+    const running = await (lookups.runningCliVersion ?? runningPackageVersion)();
+    // No `isomorph` on PATH, output with no version in it, a non-zero exit or a hang all
+    // mean the same thing: there is no installed CLI whose version can be trusted.
+    const installed = parseVersion(await (lookups.installedCliVersion ?? installedCliVersion)() ?? "");
+    const consequence = "carries an old kit bundle, so the app it creates passes every local check and is then refused by the deployment pipeline (kit_bundle_incompatible)";
+    if (!installed) {
+        // The CLI used to be published under another name with another command; a machine that still has it needs to know that it no longer deploys.
+        const legacy = await (lookups.legacyCliInstalled ?? legacyCliInstalled)() ? " The old `harbour` CLI is installed; it no longer deploys — install @isomorph.ai/cli." : "";
+        return { running, state: "missing", upgradeRequired: true, remediation: CLI_INSTALL_COMMAND, message: `No \`isomorph\` command is installed on this machine; this package is ${running}. \`isomorph init\`, \`dev\` and \`check\` run the installed CLI, not this one, and a missing or stale CLI ${consequence}.${legacy}` };
+    }
+    const order = compareCliVersions(installed, running);
+    if (order < 0)
+        return { running, installed, state: "stale", upgradeRequired: true, remediation: CLI_INSTALL_COMMAND, message: `The installed \`isomorph\` command is ${installed}, older than this package (${running}). \`isomorph init\`, \`dev\` and \`check\` run the installed CLI, not this one, and a stale CLI ${consequence}.` };
+    if (order > 0)
+        return { running, installed, state: "ahead", upgradeRequired: false, message: `The installed \`isomorph\` command is ${installed}, newer than this package (${running}); the installed one is what runs.` };
+    return { running, installed, state: "current", upgradeRequired: false, message: `The installed \`isomorph\` command is ${installed}, the same version as this package.` };
+}
+/** What `agent-setup` and `init` print about the installed CLI; an upgrade is impossible to miss in a scrolling log. */
+export function cliVersionLines(check) {
+    if (!check.upgradeRequired)
+        return [check.message];
+    return ["", "!!! UPGRADE THE ISOMORPH CLI BEFORE `isomorph init` OR ANY OTHER ISOMORPH COMMAND !!!", check.message, `Run: ${check.remediation}`, ""];
+}
+/** Numeric-core semver order; a prerelease sorts before its release. An unparseable version compares equal, so nothing is called stale on a guess. */
+export function compareCliVersions(left, right) {
+    const parse = (value) => {
+        const match = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value);
+        return match ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] } : undefined;
+    };
+    const a = parse(left);
+    const b = parse(right);
+    if (!a || !b)
+        return 0;
+    for (let index = 0; index < 3; index += 1)
+        if (a.core[index] !== b.core[index])
+            return a.core[index] < b.core[index] ? -1 : 1;
+    if (a.pre === b.pre)
+        return 0;
+    if (a.pre === undefined)
+        return 1;
+    if (b.pre === undefined)
+        return -1;
+    return a.pre < b.pre ? -1 : 1;
+}
+/** Whatever the globally resolvable `isomorph` prints for `--version`; undefined when running it is not possible at all. */
+async function installedCliVersion() {
+    try {
+        const { stdout } = await execFileAsync("isomorph", ["--version"], { timeout: 20_000, windowsHide: true });
+        return stdout;
+    }
+    catch (error) {
+        return error.stdout;
+    }
+}
+/** Whether the CLI's previous command name is still on PATH (whatever it answers). */
+async function legacyCliInstalled() {
+    try {
+        await execFileAsync("harbour", ["--version"], { timeout: 20_000, windowsHide: true });
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ENOENT";
+    }
+}
+function parseVersion(text) {
+    return /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(text.trim())?.[1];
+}
+/**
+ * The version of the package this process runs from: the nearest package.json named
+ * `@isomorph.ai/cli`, walking up from this file. That is `packages/harbour-cli/`
+ * in the repository and the package root once published (the entry point is
+ * `dist/packages/harbour-cli/src/cli.js`), so no environment variable is involved.
+ */
+async function runningPackageVersion() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 12; depth += 1) {
+        const manifest = await readFile(join(directory, "package.json"), "utf8").then(text => JSON.parse(text), () => undefined);
+        if (manifest?.name === "@isomorph.ai/cli" && typeof manifest.version === "string")
+            return manifest.version;
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return CLI_VERSION;
+}
+/**
+ * Writes `block` to `file`: creates the file, replaces the text between the markers
+ * when both are present, or appends the block after the existing content. Without
+ * markers the whole file is the managed block and is rewritten only when it differs.
+ */
+export async function upsertManagedBlock(file, block, options) {
+    const current = await readFile(file, "utf8").catch(() => undefined);
+    if (current === undefined) {
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, `${block}\n`);
+        return "created";
+    }
+    const { start, end } = options;
+    let next;
+    if (start && end && current.includes(start) && current.includes(end))
+        next = current.replace(new RegExp(`${escape(start)}[\\s\\S]*?${escape(end)}`), () => block);
+    else if (start && end)
+        next = `${current.replace(/\n*$/, "")}${options.separator ?? "\n\n"}${block}\n`;
+    else
+        next = `${block}\n`;
+    if (next === current)
+        return "kept";
+    await writeFile(file, next);
+    return "updated";
+}
+/**
+ * Takes the marker-fenced block out of `file`, keeping everything before and after it;
+ * a file that held nothing else is deleted. Returns whether there was a block to remove.
+ */
+export async function removeManagedBlock(file, options) {
+    const current = await readFile(file, "utf8").catch(() => undefined);
+    if (current === undefined || !current.includes(options.start) || !current.includes(options.end))
+        return false;
+    const remainder = current.replace(new RegExp(`\\n*${escape(options.start)}[\\s\\S]*?${escape(options.end)}\\n*`), "\n\n").replace(/^\n+/, "").replace(/\n*$/, "\n");
+    if (remainder.trim())
+        await writeFile(file, remainder);
+    else
+        await rm(file);
+    return true;
+}
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Both agents show a skill to the model as this name and description and read the body
+ * only for a task that matches, so the description is the whole gate: it names the
+ * three signs of Isomorph work and rules everything else out, because "run it" or
+ * "ship it" is said about every kind of project.
+ */
+export const SKILL_DESCRIPTION = `Build, run, check and ship a company app on Isomorph from plain English. Use only when the folder has an .isomorph/ directory, when the person names Isomorph, or when they ask for a new app for their team in an empty folder; there, "run it", "check it", "I need Slack/Gmail/company data", "ship it" and "make it live" mean this skill. Do not use for any other project, script, question or coding task — nothing in it applies outside an Isomorph app.`;
+const SKILL_FRONTMATTER = `---
+name: isomorph
+description: ${SKILL_DESCRIPTION}
+---`;
+/** One guide, shared by the Claude Code and Codex skills. Written for an agent working with a non-developer, and only for that. */
+export const AGENT_GUIDE = `# Isomorph development kit
+
+This guide is for one job: an app that runs on Isomorph. It applies when the folder has an \`.isomorph/\` directory, when the person names Isomorph, or when they ask for a new app for their team and the folder holds no other project. Anything else — another project, a script, a question, ordinary coding — is not this job: ignore every rule below and work as you always do. Never turn an existing project into an Isomorph app unless the person asks for that by name.
+
+The person you are working with may not be a developer. They say what they want in plain English; you build it with the Isomorph development kit and run every command yourself. Never ask them to type a terminal command (the one exception is sign-in, below). Turn every failure into one sentence about what happened and one about what happens next. Prefer \`--json\` output and read it yourself; never paste JSON, logs, stack traces or file contents at them.
+
+## Getting ready (do this yourself, once per machine and folder)
+
+1. CLI, before \`isomorph init\` or anything else: compare the installed CLI with the current release and upgrade it whenever it is behind — a CLI that merely runs is not good enough, only a current one is. \`isomorph agent-setup\` prints both versions and says plainly when the installed one is missing or older (its \`--json\` result carries \`cli.upgradeRequired\` and \`cli.remediation\`); without that output, compare \`isomorph --version\` with \`npx -y @isomorph.ai/cli --version\` yourself. If either says the installed one is missing or older, run \`npm i -g @isomorph.ai/cli\` and confirm \`isomorph --version\` now matches, then continue. Every later command runs the *installed* CLI, so a stale one builds an app that passes every local check and is then refused by the deployment pipeline (\`kit_bundle_incompatible\`) minutes later, with nothing in the app to fix. The kit needs Node 22+ on macOS Apple silicon, Linux x64 or Windows x64; it installs and runs its local database, files and gateway without Docker.
+2. Folder: if the current folder has no \`.isomorph/\` directory, run \`isomorph init --app-root .\` — an empty folder gets a small starter app, an existing Vite + React app gets the kit files added and nothing overwritten. Then read the "Isomorph development kit" block in CLAUDE.md / AGENTS.md; it holds the per-app rules.
+3. Sign-in, needed only for company systems and shipping: run \`isomorph login\`. It opens the browser and the person finishes the sign-in there — the one step they do themselves; tell them so in one line. If login says the company is not connected yet, ask for their work email and run \`isomorph connect <work-email>\` first. This guesses the tenant from the first email-domain label and validates its company profile; it does not grant access. If the lookup fails, ask for the company setup link their IT/admin gave them and run \`isomorph connect <link>\`.
+
+## What they say → what you do
+
+- "run it", "show me", "let me try it" → start \`isomorph dev --app-root .\` in the background (it keeps running; the first start downloads the native runtime and takes a minute or two). Wait for the line \`Isomorph dev is running: http://127.0.0.1:<port>\` and give them that link. Do this unasked as soon as the first check is green — they should always have the link. Locally they are a fixture user; no company sign-in is needed.
+- "check it", "is it ok?", "is it ready?" → with dev running, \`isomorph check --app-root . --json\`, then read \`.isomorph/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.
+- "does it work?", and before you report anything as working → open the dev link in your own browser when you have one, press the control you built or changed, and read what the app shows. A green \`isomorph check\` is not that proof: it answers governed AI and company systems from fixtures, so the refusals that matter (a field the company's AI route does not accept, a consent the operation does not need, a channel that is not approved) appear only when the control is really pressed. Test rendering, navigation, fixtures and approved reads automatically. In development a Send sends a real email or Slack message: reuse explicit authorization for that bounded test, or ask once if none exists; IT access approval alone is not permission to send. Never ask again for the same authorized test. Before a real integration test, run \`isomorph integrations status --app-root . --json\`; explain pending IT approval or missing personal consent before pressing Send, and test the ready parts independently. If you have no browser, say that the button itself is untested.
+- "I need Slack / Gmail / the warehouse / company data" → a fresh \`isomorph init\` declares no connection at all, which is why a new app ships with nothing waiting on IT. Never guess a connection, channel, table, view, mailbox or warehouse column — a guessed name is refused before IT's queue ever sees it. Before writing a warehouse query or mapping response fields, run \`isomorph integrations catalog --app-root . --json\`, select a listed table or view, and copy its listed column names exactly. If the required object or column is absent, report that catalog gap instead of substituting a plausible name. A warehouse resource whose catalog columns are \`["*"]\` is declared and read with \`["*"]\`; inspect the returned row keys before mapping them and do not invent a friendlier schema or ask the person to get IT to confirm one. Declare only connections and operations the app really calls, then submit the request yourself in the same turn with \`isomorph integrations request <connection> --reason "<what the app does with it>" --app-root . --json\` — one request per connection; IT approves it once for every environment (development, preview and production together), and \`isomorph dev\` and \`isomorph productionise\` file it for you as well, so there is never a second request to make before shipping. Never tell the person to ask IT before you have submitted the request. 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 \`isomorph integrations status --app-root . --json\` (development may already read ready while preview and production wait: that is the company's development preapproval, and the one approval covers the rest). A refusal with \`RESOURCE_NOT_APPROVED\` means the named resource is not on the connection yet: IT adds it in the Isomorph console under Controls & integrations, and then you run the same request again. Never declare a connection the app does not call — every declared one blocks shipping until IT approves it.
+- "summarise", "draft", "explain", "AI" → one \`isomorph.ai.chat\` call (on the client exported by \`src/isomorph.client.ts\`, never through a wrapper function) behind a control the person presses; never an OpenAI/Anthropic key, SDK or URL. \`isomorph check\` writes its journey. Send \`messages\` and \`maxTokens\` and nothing else: a refusal with \`unsupported_request_capability\` names a field the company's AI route does not accept — remove that field. 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 \`isomorph 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. Before sharing or deploying the private preview, show the person the exact proposed app name, description and audience that will be passed to Isomorph (say "only you" when the audience is empty) and ask for one confirmation or correction covering all three; do not run \`productionise\` until they confirm. Pass that confirmed setup in the same command: \`isomorph productionise --app-root . --name "<app name>" --description "<description>" --emails "<comma-separated audience>" --wait --json\`; omit \`--emails\` for "only you". The command records the confirmed setup before uploading or deploying the app. It files the access request for each declared connection itself and refuses with \`INTEGRATIONS_NOT_READY\` naming what IT still has to approve — say that line and nothing more, and ship again once IT has approved it (one approval covers preview and production); when the app calls governed AI, \`productionise\` also asks whether the company's AI setup is ready and refuses with \`AI_NOT_READY\` and the one IT step — say that line and nothing more; the app works without AI until then. The command gives them \`result.deployment.protectedUrl\`: a private preview that they, and the people they confirmed, open after company sign-in. If your tool cuts the command off before it finishes, \`${continueCommand("<ref>")}\` continues the same deployment — never start another one to find out what happened. For kit apps, describe \`TRANSFORMING\` as building and checking the app; it does not mean a transformation AI is running. The CLI saves \`operationRef\` in \`.isomorph/local/productionise.json\`; repeating \`productionise\` continues that operation. Keep \`operationRef\`; \`isomorph setup --operation <ref> --json\` lists what is still missing (name, audience, secrets) and \`isomorph profile\` / \`isomorph audience\` / \`isomorph secrets set\` fill it in.
+- "make it live for everyone", "go to production" → only after they have tried the preview. Before \`isomorph promote --operation <ref> --json\`, show the exact app name, description and production audience again and ask for one confirmation or correction covering all three; never promote a profile or audience the person has not just seen and confirmed. Then promote with the operation reference from productionise. Report the production link, or that an operator approval is pending.
+- "stop it" → \`isomorph stop --app-root .\` (local data kept). \`isomorph dev --reset --app-root .\` deletes local data — only when they explicitly ask to start over.
+- "every day at 2pm", "run this on a schedule", "send this automatically" → create one \`jobs/<name>.ts\` file with a literal UTC cron and one default async handler. Start \`isomorph dev\`, then run it immediately with \`isomorph jobs run <name> --app-root . --scheduled-at <matching-UTC-time> --json\`; this checks the job against local data and safe fixtures. If the person explicitly asks to test the company action now, use \`--real\` only after the exact action has development approval. Tell them: "Your scheduled task is ready. I can test the app on your computer now. Company messages will start after the app is online and access is approved." Never use \`setInterval\`, an effect or a browser timer as a scheduler; Isomorph runs the same declaration automatically after deployment.
+
+When a command refuses, the refusal names its own reason and its own fix: change that one thing, then run it again. A failed app needs its reported fix; a wait timeout means work is still running, so continue the saved operation — and never start a second deploy of an app while one is running, because concurrent deploys of one app cancel each other.
+
+## Building the app
+
+- Identity, data and files go through \`@isomorph.ai/app-sdk\` only: \`isomorph.identity.current()\`, \`isomorph.data.from(table)\`, \`isomorph.files.*\`. Company systems go only through \`isomorph.integrations.execute\` with declared operations. AI goes through \`isomorph.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 Isomorph 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\`; \`isomorph dev\` and \`isomorph 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.
+- In browser code, a Slack message or an email (\`slack.message.post\`, \`gmail.message.send\`) is sent only from an explicit Send control (pressed by the person, or by you for an explicitly authorized test), with a fresh UUID \`idempotencyKey\` per press (reused only to retry that press). Never send from an effect, a browser timer or during checks. A declared \`jobs/*.ts\` handler is the only scheduled-send path: it acts as the app, so only app-mode operations such as \`slack.message.post\` may run there; user-mode Slack and Gmail need a person and cannot. A real scheduled send requires the person's explicit request, the exact operation and destination declared in \`.isomorph/integrations.json\`, and a grant for that environment; use one deterministic idempotency key for the business period and destination so replay does not silently repost. Local job runs and \`isomorph check\` use fixtures and send nothing. Consent (\`isomorph.integrations.connect\`) exists only for user-identity operations (\`slack.channel.history\`, \`gmail.thread.list\`, \`gmail.message.read\`, \`gmail.message.send\`, and \`slack.message.post\` declared \`"identity": "user"\`); app-identity operations (\`slack.message.post\` declared \`"identity": "app"\`, \`warehouse.view.read\`) never call it — a connect for them is refused as unapproved user access and puts nothing in IT's queue. Whenever the app uses a user-identity operation, build its consent flow into the app during the original implementation without asking whether to add it: the operation's control calls \`isomorph.integrations.connect\`, follows \`authorizationUrl\` when the result is \`consent_required\`, returns to a clear connected state, and then lets the person continue the operation. Consent starts only from that person's control, never on page load. Missing consent never falls back to another account.
+- A Slack message is posted either as the app (\`"identity": "app"\` — the company's one Slack bot, Isomorph AI, under the name IT approved: declare \`"presentation": { "displayName": "<app name>", "iconEmoji": ":sandwich:" }\` on the connection and IT sees "posts as" before approving; leave it out to post as Isomorph AI itself) or as the person (\`"identity": "user"\` — their own Slack account, after their consent; an older consent answers \`USER_RECONNECT_REQUIRED\` "reconnect Slack to allow posting as you", so offer Connect again) — never pretend one is the other. The declaration in \`.isomorph/integrations.json\` is the mode the app requests access for; a post names the approved mode it runs under with \`mode: "app"\` or \`mode: "user"\` on the execute call — optional while the app is approved for one mode, required once IT approved both (\`MODE_REQUIRED\`), and a mode IT has not approved is refused with \`MODE_NOT_GRANTED\`, never swapped for the other. An app-mode post always ends with "Posted by <app> on Isomorph". A post is refused with \`RESOURCE_NOT_APPROVED\` until the bot is in the channel: say "IT (or anyone in the channel) has to run \`/invite @Isomorph AI\` in #<channel> first".
+- No secrets, tokens, \`.env\` values or fetched company content in source. \`.isomorph/local/\` is never committed; \`.isomorph/integrations.json\` and \`.isomorph/kit.lock.json\` are.
+
+## Talking to the person
+
+- Plain words, short: "Your app is running at <link>.", "All 6 checks passed.", "One check failed: votes were not being saved — fixed, checking again.", "IT has to approve Slack; the app works without it until then."
+- Say what happens next and roughly how long it takes. Report only what you observed; if something is unknown, say so.
+- Keep app reports natural and brief: say what you actually verified, any remaining blocker and who can resolve it, and any material scope decision you made. Do not force headings or repeat unchanged status. A platform check is not proof that the main task worked in the browser.
+- End a turn with at most one question, and only when a decision is genuinely theirs to make and you cannot go on without it. Never offer to do something this guide already tells you to do unasked — do it and report what happened.`;

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

@@ -0,0 +1,142 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+/** 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, 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 Isomorph 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(catalogText, root) {
+    const text = catalogText.trim();
+    if (!text.startsWith("["))
+        return undefined;
+    let catalog;
+    try {
+        catalog = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(catalog))
+        return undefined;
+    const migrations = await migrationTexts(root);
+    const schema = new Map();
+    for (const table of catalog) {
+        schema.set(table.name, {
+            columns: table.columns.map(column => ({
+                name: column.name,
+                type: columnType(column.base, column.category),
+                declaredType: column.type,
+                notNull: column.notnull,
+                hasDefault: column.default !== null,
+                generated: column.generated,
+                identityDefault: IDENTITY.test(column.default ?? ""),
+                references: column.fk,
+                checks: column.checks
+            })),
+            primaryKey: table.primaryKey,
+            ownerScoped: table.policies.some(policy => IDENTITY.test(policy)),
+            ownerColumn: table.policies.map(policy => OWNER_SCOPE.exec(policy)?.[1]).find(Boolean),
+            file: createdIn(table.name, migrations)
+        });
+    }
+    return schema;
+}
+/**
+ * Postgres has already reduced every declared spelling to one base type name
+ * (`character varying` to `varchar`, `double precision` to `float8`, `BIGSERIAL`
+ * to `int8` with a nextval default), so this is a lookup rather than a parse.
+ */
+function columnType(base, category) {
+    if (category === "A")
+        return "array";
+    switch (base) {
+        case "text":
+        case "varchar":
+        case "bpchar":
+        case "char":
+        case "citext":
+        case "name": return "text";
+        case "uuid": return "uuid";
+        case "bool": return "boolean";
+        case "int2":
+        case "int4":
+        case "int8": return "integer";
+        case "numeric":
+        case "float4":
+        case "float8":
+        case "money": return "number";
+        case "timestamptz":
+        case "timestamp": return "timestamptz";
+        case "date": return "date";
+        case "time":
+        case "timetz": return "time";
+        case "json":
+        case "jsonb": return "json";
+        default: return "unknown";
+    }
+}
+async function migrationTexts(root) {
+    const directory = join(root, "migrations");
+    const names = (await readdir(directory).catch(() => [])).filter(name => name.endsWith(".sql")).sort();
+    return Promise.all(names.map(async (name) => ({ name: `migrations/${name}`, text: await readFile(join(directory, name), "utf8").catch(() => "") })));
+}
+/** Which file created a table: the only question the catalog cannot answer, so the only one still asked of the SQL text. */
+function createdIn(table, migrations) {
+    const pattern = new RegExp(String.raw `create\s+table\b[^;]*\b${table}\b`, "i");
+    return migrations.find(migration => pattern.test(migration.text))?.name ?? "migrations/";
+}
+// ---- CHECK constraints ----------------------------------------------------------
+//
+// `pg_get_constraintdef` deparses, so these read one normal form rather than
+// everything an author might have typed: `BETWEEN a AND b` has already become
+// `>= a AND <= b`, `IN (…)` has become `= ANY (ARRAY[…])`, and each operand
+// carries its cast. Only the shapes a value has to satisfy to be accepted are
+// read; anything else is left alone, and a value the database rejects surfaces
+// as a failing journey under `isomorph check` in seconds rather than in the
+// pipeline minutes later.
+/** `char_length(col) >= n`, `length(col) <= n` — including the `((col)::text)` spelling a deparse gives a varchar. */
+export function textLengthBounds(checks, column) {
+    let min = 1;
+    let max = 500;
+    const pattern = new RegExp(String.raw `(?:char_length|length|octet_length)\([^<>=]*\b${column}\b[^<>=]*(<=|<|>=|>|=)\s*(\d+)`, "gi");
+    for (const check of checks)
+        for (const match of check.matchAll(pattern)) {
+            const value = Number(match[2]);
+            if (match[1] === "<=" || match[1] === "=")
+                max = Math.min(max, value);
+            else if (match[1] === "<")
+                max = Math.min(max, value - 1);
+            else if (match[1] === ">=")
+                min = Math.max(min, value);
+            else
+                min = Math.max(min, value + 1);
+        }
+    return { min, max: Math.max(max, min) };
+}
+/** `col = ANY (ARRAY['a'::text, 'b'::text])`: the closed set a value must come from. */
+export function allowedLiterals(checks, column) {
+    for (const check of checks) {
+        const list = new RegExp(String.raw `\b${column}\b[^=]*=\s*ANY\s*[\s(]*ARRAY\[([^\]]*)\]`, "i").exec(check);
+        const values = [...(list?.[1] ?? "").matchAll(/'((?:[^']|'')*)'/g)].map(match => match[1].replace(/''/g, "'"));
+        if (values.length)
+            return values;
+    }
+    return [];
+}
+/** The smallest number `col > n` / `col >= n` accepts. */
+export function numericMinimum(checks, column) {
+    let minimum = 1;
+    for (const check of checks) {
+        const comparison = new RegExp(String.raw `\b${column}\b[^<>=]*(>=|>)\s*(-?\d+(?:\.\d+)?)`, "i").exec(check);
+        if (!comparison)
+            continue;
+        const value = Number(comparison[2]);
+        minimum = Math.max(minimum, comparison[1] === ">" ? value + 1 : value);
+    }
+    return minimum;
+}