@isomorph.ai/cli 0.2.0 → 0.2.2-rc.1

package/README.md

@@ -46,10 +46,10 @@ isomorph status | retry | promote | setup | profile | audience | secrets … --o
 
 ## 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.
+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, replaces the project skill (the old `.claude/skills/harbour-kit/SKILL.md` is deleted when it is the kit's — the frontmatter name and the opening line every release wrote — and kept, and reported as kept, when you rewrote its body), deletes the checks the old kit generated (the next `isomorph check` regenerates them) and rewrites the SDK package name, its exported type names and the retired `HARBOUR_*` environment names (`HARBOUR_APP_URL` → `ISOMORPH_APP_URL` and the rest) in `package.json`, `vite.config.*`, `src/`, `jobs/` and the checks you wrote yourself. Run it again after updating the CLI: an app already moved by 0.2.0 loses its old skill and old environment names the same way. 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).
+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>` by the release automation the moment `packages/harbour-cli/package.json` changes on `main`, so bump to a candidate first (`X.Y.Z-rc.1`, published under the `candidate` dist-tag through npm trusted publishing) and promote it with the `CLI release automation` workflow's `candidate` input; a final version on `main` without an accepted candidate is refused by the release job. 0.2.0 and 0.2.1 (the rename) were published by hand from their merge commits before the trusted publisher existed for `@isomorph.ai/cli`, which is why their `cli-v` release runs show red.
 
 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/productionise.js

@@ -85,10 +85,16 @@ export async function productionise(rootArg, client, output, tenantId, includePa
     const gate = options.kitGate === false ? undefined : options.kitGate ?? (options.integrations ? { bundle: options.integrations.bundle } : undefined);
     if (gate && !pending?.uploaded)
         await preflightKitGate(root, gate.bundle, output, gate.run);
+    // A `CliError` is Isomorph's own answer (`AUTH_REQUIRED` after two 401s, a
+    // JSON-RPC refusal) and reaches the builder as it is; only a plain Error from
+    // the transport — Isomorph out of reach — is "not started". Reporting a
+    // refused sign-in as unreachable sent an agent down a worse path (2026-09-14).
     try {
         await client.initialize();
     }
-    catch {
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
         throw new CliError("NOT_STARTED", "Isomorph could not be reached before the operation started.");
     }
     let start;

package/dist/packages/harbour-cli/src/remote-mcp-client.js

@@ -37,6 +37,20 @@ function rpcRefusal(error, status) {
     const code = labelled?.[1] ?? (typeof error.code === "number" ? `ISOMORPH_RPC_${error.code}` : `ISOMORPH_HTTP_${status}`);
     return new CliError(code, (labelled?.[2] ?? text) || `Isomorph refused the request (HTTP ${status}).`);
 }
+/**
+ * A second 401 in a row: the sign-in itself is gone, or this company does not
+ * admit the signed-in account. The server says which in `error_description`
+ * (plain English, no URL or token); an older server sends only the code, and
+ * the fixed sentence stands in. Both fixes are named because the builder cannot
+ * tell the two causes apart: on 2026-09-14 a `productionise` 14 seconds after a
+ * successful `isomorph login` was refused by a company the account was not a
+ * member of, and "run login again" would only have repeated it.
+ */
+async function signInRefused(response) {
+    const body = await response.json().catch(() => undefined);
+    const said = typeof body?.error_description === "string" ? body.error_description.trim() : "";
+    return new CliError("AUTH_REQUIRED", `${said || "Isomorph sign-in expired or was revoked."} Run \`isomorph login\` again, or \`isomorph connect <work-email-or-start-url>\` if this is the wrong company.`);
+}
 async function readRpc(response) {
     try {
         return await response.json();
@@ -76,11 +90,11 @@ export class RemoteMcpClient {
         let response = await this.post(body);
         // A 401 mid-command usually means the stored token was rotated by another
         // process; re-resolve (which reloads the store) and retry once. A second
-        // 401 means the sign-in itself is gone.
+        // 401 is Isomorph refusing the sign-in, and `signInRefused` says why.
         if (response.status === 401)
             response = await this.post(body);
         if (response.status === 401)
-            throw new CliError("AUTH_REQUIRED", "Isomorph sign-in expired or was revoked. Run `isomorph login` again.");
+            throw await signInRefused(response);
         if (!expectResponse)
             return undefined;
         const parsed = await readRpc(response);

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

@@ -26,7 +26,8 @@ export async function initKit(root, bundle, options = {}) {
     const result = { root, created: [], kept: [], updated: [], mode: options.upgrade ? "upgrade" : emptyDir ? "starter" : "existing", bundleChanges: [], agents: options.env ? await agentSetup(options.env) : { created: [], updated: [], kept: [], removed: [] } };
     if (options.upgrade) {
         await migrateLegacyKit(root, bundle, result);
-        await rewriteSdkReferences(root, bundle.sdk.package, result);
+        await retireLegacySkill(root, result);
+        await rewriteLegacyReferences(root, bundle.sdk.package, result);
     }
     const write = async (path, content) => {
         const absolute = join(root, path);
@@ -76,18 +77,29 @@ const LEGACY = {
     generatedPrefix: "// harbour:generated sha256:",
     gitignoreLine: ".harbour/local/",
     skill: ".claude/skills/harbour-kit/SKILL.md",
+    /** How every release's project skill opened, under the frontmatter `name: harbour-kit`; the body below it changed from release to release. */
+    skillOpening: 'Follow the "Harbour development kit" block',
     sdkPackage: "@harbour/app-sdk",
     /** The SDK's exported type names, renamed with the package. */
-    typeNames: /\bHarbour(User|ErrorCategory|Error|Client|Result|CompatSource)\b/g
+    typeNames: /\bHarbour(User|ErrorCategory|Error|Client|Result|CompatSource)\b/g,
+    /**
+     * The environment names the kit and the platform export to a check, a job and
+     * the Vite config, renamed with the CLI. Whole words: the session's
+     * `HARBOUR_LOCAL_USER_EMAIL` and the CLI↔gateway `HARBOUR_APP_GATEWAY_*` and
+     * `HARBOUR_GATE_*` names are not builder-visible and are not renamed.
+     */
+    envNames: /\bHARBOUR_(APP_URL|SDK_MODULE|IDENTITY_CONTEXT_SECOND_USER|IDENTITY_CONTEXT_HEADER|IDENTITY_CONTEXT|GATEWAY_URL|WORKLOAD_TOKEN|SCHEDULED_AT|LOCAL_ORIGIN|VITE_PORT)\b/g
 };
 /**
  * Moves an app set up by a CLI older than 0.2.0 to this kit, once, and only under
  * `init --upgrade`: the kit directory and its five entries are renamed (git records
- * renames), the two committed schema ids move with it, the `.gitignore` line, the
- * managed block in CLAUDE.md / AGENTS.md and the project skill are rewritten, and
- * the checks the old kit generated are deleted for the next `check` to regenerate.
- * A check the author wrote or edited is kept, as everywhere else. Nothing happens
- * when there is no old layout, or when the current one already exists beside it.
+ * renames), the two committed schema ids move with it, the `.gitignore` line and
+ * the managed block in CLAUDE.md / AGENTS.md are rewritten, and the checks the old
+ * kit generated are deleted for the next `check` to regenerate. A check the author
+ * wrote or edited is kept, as everywhere else. Nothing happens when there is no old
+ * layout, or when the current one already exists beside it. The old project skill
+ * and the old names in the app's own files are handled after this, on every
+ * `--upgrade`, so an app this pass already moved still loses them.
  */
 async function migrateLegacyKit(root, bundle, result) {
     const legacy = join(root, LEGACY_KIT_DIRECTORY);
@@ -124,12 +136,6 @@ async function migrateLegacyKit(root, bundle, result) {
             touched(file);
         }
     }
-    const skill = join(root, LEGACY.skill);
-    if ((await readFile(skill, "utf8").catch(() => undefined)) === LEGACY_SKILL_FILE) {
-        await rm(skill);
-        await rmdir(dirname(skill)).catch(() => undefined);
-        touched(LEGACY.skill);
-    }
     for (const name of await readdir(paths.checks).catch(() => [])) {
         if (!isPristine(await readFile(join(paths.checks, name), "utf8").catch(() => ""), LEGACY.generatedPrefix))
             continue;
@@ -138,15 +144,45 @@ async function migrateLegacyKit(root, bundle, result) {
     }
 }
 /**
- * Rewrites the SDK's previous package name (and, in `package.json`, the tarball
- * path the old kit staged it under) and its six exported type names in the app's
- * own files: `package.json`, `src/`, `jobs/` and the retained checks. Whole words
- * only, so an author's own `HarbourUserProfile` is theirs. Idempotent: an app that
- * names none of them is left untouched and unreported.
+ * Deletes the project skill an older CLI wrote, on every `--upgrade` — an app the
+ * layout migration moved under 0.2.0 still has it beside the new skill. The file
+ * is the kit's by shape, not by bytes: each release wrote a different body under
+ * the same frontmatter name and the same opening line, so one whose body an
+ * author rewrote is kept, and reported, as theirs.
+ */
+async function retireLegacySkill(root, result) {
+    const path = join(root, LEGACY.skill);
+    const text = await readFile(path, "utf8").catch(() => undefined);
+    if (text === undefined)
+        return;
+    if (!isLegacyKitSkill(text)) {
+        result.kept.push(LEGACY.skill);
+        return;
+    }
+    await rm(path);
+    await rmdir(dirname(path)).catch(() => undefined);
+    result.updated.push(LEGACY.skill);
+}
+/** Frontmatter naming `harbour-kit`, and the opening every release wrote as the body's first line. */
+function isLegacyKitSkill(text) {
+    const lines = text.split(/\r?\n/);
+    const close = lines.indexOf("---", 1);
+    if (lines[0] !== "---" || close < 0)
+        return false;
+    return lines.slice(1, close).includes("name: harbour-kit") && (lines.slice(close + 1).find(line => line.trim()) ?? "").startsWith(LEGACY.skillOpening);
+}
+/**
+ * Rewrites what the old kit named in the app's own files — `package.json`,
+ * `vite.config.*`, `src/`, `jobs/` and the retained checks — on every `--upgrade`:
+ * the SDK's previous package name (and, in `package.json`, the tarball path the
+ * old kit staged it under), its six exported type names, and the environment
+ * names the kit and the platform export to a check, a job and the Vite config.
+ * Whole words only, so an author's own `HarbourUserProfile` is theirs. Idempotent:
+ * an app that names none of them is left untouched and unreported.
  */
-async function rewriteSdkReferences(root, sdkPackage, result) {
-    const rewrite = (text) => text.replaceAll(`"${LEGACY.sdkPackage}"`, `"${sdkPackage}"`).replaceAll(`'${LEGACY.sdkPackage}'`, `'${sdkPackage}'`).replace(LEGACY.typeNames, "Isomorph$1");
-    for (const path of ["package.json", ...(await appSourceFiles(root))]) {
+async function rewriteLegacyReferences(root, sdkPackage, result) {
+    const rewrite = (text) => text.replaceAll(`"${LEGACY.sdkPackage}"`, `"${sdkPackage}"`).replaceAll(`'${LEGACY.sdkPackage}'`, `'${sdkPackage}'`).replace(LEGACY.typeNames, "Isomorph$1").replace(LEGACY.envNames, "ISOMORPH_$1");
+    for (const path of ["package.json", "vite.config.ts", "vite.config.js", "vite.config.mjs", ...(await appSourceFiles(root))]) {
         const current = await readFile(join(root, path), "utf8").catch(() => undefined);
         if (current === undefined)
             continue;
@@ -242,21 +278,6 @@ Follow the "Isomorph development kit" block in CLAUDE.md / AGENTS.md. Workflow:
 5. \`isomorph integrations request <connection> --reason "<why>" --app-root .\` asks IT for access now — one request per connection, approved once for every environment; \`isomorph dev\` (signed in) and \`isomorph productionise\` file it for you. Pending is not ready.
 6. \`isomorph productionise --app-root .\` saves and deploys the preview; \`isomorph promote\` after the person has tested it.
 `;
-/** The project skill CLI releases before 0.2.0 wrote, byte for byte: `init --upgrade` deletes the old file only when it is still exactly this. */
-export const LEGACY_SKILL_FILE = `---
-name: harbour-kit
-description: Build, run and check this Harbour app with the Harbour CLI (dev, check, integrations, productionise).
----
-
-Follow the "Harbour development kit" block in CLAUDE.md / AGENTS.md. Workflow:
-
-1. \`harbour dev --app-root .\` starts Postgres, storage and one Harbour gateway (session identities, fixtures, realtime) plus Vite behind one loopback origin printed in the banner.
-2. Edit \`src/\` and \`migrations/\`. Use the SDK only. \`.harbour/integrations.json\` starts with no connections and gains one only when the app really calls a company system: declare it with only the operations the app calls, then request access (step 5). A declared connection the app does not call blocks every deploy until IT grants it; an undeclared one cannot be requested, so it never gets a grant. README.md has the worked Slack and warehouse examples — the file itself is strict JSON and cannot hold comments.
-3. \`.harbour/checks/\` is generated, not written by hand: \`harbour check\` reads \`migrations/\` and \`src/\` and writes one retained journey per capability the app's own code uses (plus a cross-user denial per owner-scoped table), deleting the ones the app no longer needs — so run it in the same edit that changes the app instead of adding or deleting these files yourself. It reports anything it cannot generate (\`actions\`, \`realtime\`, a table with no migration) for you to write. Edit a generated check and it becomes yours: Harbour keeps it, stops managing it and never removes it, so deleting it when the feature goes is then your job. \`harbour check\` and the deployment pipeline replay these checks against a real App Gateway and refuse the app (\`flow.check-failed\`) in both directions — a capability no check exercises, and a check that exercises something the code no longer does.
-4. \`harbour check --app-root .\` before every hand-off; read \`.harbour/local/check-report.json\`. Real integrations are reported as not tested unless \`--integrations\` is passed (read operations only); a retained check that calls \`harbour.integrations.execute\` is answered by the gate's fixture (the contract's shape for what the app declared, nothing sent or read) and the passed check says so. A governed AI call (\`harbour.ai.chat\`) is exercised for real through the development route while \`harbour dev\` is up; the pipeline answers it with a canned completion and reports it as not tested.
-5. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for access now — one request per connection, approved once for every environment; \`harbour dev\` (signed in) and \`harbour productionise\` file it for you. Pending is not ready.
-6. \`harbour productionise --app-root .\` saves and deploys the preview; \`harbour promote\` after the person has tested it.
-`;
 /**
  * Kit infrastructure: structural files every kit app needs, on every path —
  * `init` in an empty directory, `init` over an existing Vite + React app, and

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.2.0";
+export const CLI_VERSION = "0.2.2-rc.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/cli",
-  "version": "0.2.0",
+  "version": "0.2.2-rc.1",
   "description": "Isomorph development kit CLI",
   "type": "module",
   "bin": {