@isomorph.ai/cli 0.3.3 → 0.3.4-rc.1

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

@@ -7,6 +7,28 @@ import { CliError } from "./output.js";
 import { DEPENDENT_READ_OPERATIONS, READ_OPERATIONS, kitPaths, readDeclaration, readKitLock, resourceNames, sourceDigest } from "./kit.js";
 import { LocalRuntime, allocatePorts, ensureSdk, freePort, nodePackageCommand, readDevLock, runCommand, runningOrigin } from "./local-runtime.js";
 import { CLI_VERSION } from "./version.js";
+/**
+ * What actually failed, in the refusal itself.
+ *
+ * The report is already in hand at the call site, and a refusal that spends its
+ * message on a file path costs the reader a whole turn to learn anything —
+ * `productionise` already names the failing checks when it refuses to deploy
+ * (`nameList(failed)`), and `check` did not. The detail of the first failure is
+ * carried too, capped, because "which check" is a smaller answer than "why".
+ */
+export function checksFailedMessage(report) {
+    const failed = report.checks.filter(check => check.status === "fail");
+    if (failed.length === 0)
+        return "One or more checks failed.";
+    const names = failed.map(check => check.name).join(", ");
+    const first = failed.find(check => check.detail)?.detail?.replace(/\s+/g, " ").trim();
+    const detail = first ? ` ${first.length > DETAIL_CAP ? `${first.slice(0, DETAIL_CAP - 1)}\u2026` : first}` : "";
+    return `${failed.length === 1 ? "Check" : "Checks"} failed: ${names}.${detail}`;
+}
+/** The bound on the reason carried into the refusal; the rest stays in the report. */
+const DETAIL_CAP = 200;
+/** Where the rest of it is, and the one command that re-runs them. */
+export const CHECKS_FAILED_HINT = "Full detail is in .isomorph/local/check-report.json; fix what it reports, then run `isomorph check --app-root .` again.";
 /** The name the gate reports operation coverage under — the pipeline's rule for it. */
 export const FLOW_CHECK = "flow.check-failed";
 /**
@@ -78,6 +100,7 @@ export async function runChecks(root, options) {
         schema: "isomorph.check-report/1.0",
         createdAt: new Date().toISOString(),
         sourceDigest: source.digest,
+        sourceFiles: source.entries,
         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,

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

@@ -12,7 +12,7 @@ import { initKit } from "./starter.js";
 import { agentPaths, agentSetup, cliVersionLines } from "./agent-setup.js";
 import { startDev } from "./dev.js";
 import { ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
-import { runChecks } from "./check.js";
+import { CHECKS_FAILED_HINT, checksFailedMessage, runChecks } from "./check.js";
 import { assertAiReady, companySystemsLine, GovernanceClient, groupGrants, IDENTITY_WORDS, integrationsCatalog, integrationsStatus, renderGrantGroup, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
 import { runJob } from "./jobs.js";
 const args = process.argv.slice(2);
@@ -112,8 +112,12 @@ const exitAfterWriting = (code, out, err = "") => { process.stderr.write(err, ()
 const USAGE_REFUSALS = ["INTEGRATIONS_NOT_READY", "AI_NOT_READY", "NOT_A_MEMBER", "TENANT_AMBIGUOUS", "NOT_A_START_LINK", "PLATFORM_UNREACHABLE"];
 if (command === "--version" || command === "version") {
     process.stdout.write(`${CLI_VERSION}\n`);
+    // `-h` was matched anywhere in argv while `--help` was only recognised as the
+    // first token, so `isomorph productionise --help` fell through to argument
+    // validation and exited 2 with the usage block as an error. Both spellings now
+    // mean the same thing wherever they appear.
 }
-else if (!command || command === "help" || command === "--help" || args.includes("-h")) {
+else if (!command || command === "help" || command === "--help" || args.includes("-h") || args.includes("--help")) {
     process.stdout.write(usage);
 }
 else if (command === "agent-setup") {
@@ -202,8 +206,12 @@ else {
                     governance = new GovernanceClient(config.apiUrl, token, config.tenantId);
                 }
                 const report = await runChecks(target, { run: runCommand, bundle, output: progress, governance });
-                if (!report.passed)
-                    exitAfterWriting(1, json ? `${JSON.stringify({ ...summaryEnvelope(report), status: "FAILED", error: { code: "CHECKS_FAILED", message: "One or more checks failed; see .isomorph/local/check-report.json." } })}\n` : "Checks failed; see .isomorph/local/check-report.json.\n");
+                if (!report.passed) {
+                    const message = checksFailedMessage(report);
+                    exitAfterWriting(1, json
+                        ? `${JSON.stringify({ ...summaryEnvelope(report), status: "FAILED", error: { code: "CHECKS_FAILED", message, remediationHint: CHECKS_FAILED_HINT } })}\n`
+                        : `${message}\n${CHECKS_FAILED_HINT}\n`);
+                }
                 else
                     emit(summaryEnvelope(report));
             }

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

@@ -136,14 +136,45 @@ export function projectName(root, suffix = "") {
 export function linkIdempotencyKey(tenantId, root) {
     return createHash("sha256").update(`${tenantId}${resolve(root)}`).digest("hex");
 }
-/** sha256 over the tracked app files (same boundary as productionise), so any edit changes it. */
+/**
+ * sha256 over the tracked app files (same boundary as productionise), so any
+ * edit changes it — and, per file, the hash of its contents, so a stale check
+ * can say WHICH path moved rather than only that something did.
+ */
 export async function sourceDigest(root) {
     const graph = await scanWorkspace(root, { sourceBoundary: "root" });
     const files = [...graph.deploymentScope.includedFiles].sort();
     const hash = createHash("sha256");
+    const entries = {};
     for (const path of files) {
+        const content = await readFile(join(root, path));
         hash.update(path).update("\0");
-        hash.update(await readFile(join(root, path))).update("\0");
+        hash.update(content).update("\0");
+        entries[path] = createHash("sha256").update(content).digest("hex");
     }
-    return { digest: `sha256:${hash.digest("hex")}`, files };
+    return { digest: `sha256:${hash.digest("hex")}`, files, entries };
+}
+/**
+ * What moved between the tree the checks ran on and the tree being deployed.
+ *
+ * A builder hit this three times in one session: their agent wrote scratch files
+ * into a gitignored folder inside the app root, which is still inside the
+ * deployment boundary, so every write invalidated the checks. The refusal named
+ * the code but not the path, so nothing pointed at the folder. Naming the paths
+ * is the whole fix.
+ */
+export function describeSourceChange(before, after) {
+    if (!before)
+        return "";
+    const added = Object.keys(after).filter(path => !(path in before)).sort();
+    const removed = Object.keys(before).filter(path => !(path in after)).sort();
+    const changed = Object.keys(after).filter(path => path in before && before[path] !== after[path]).sort();
+    const some = (paths, verb) => {
+        if (!paths.length)
+            return "";
+        const shown = paths.slice(0, 3).join(", ");
+        const rest = paths.length - 3;
+        return `${verb} ${shown}${rest > 0 ? ` and ${rest} more` : ""}`;
+    };
+    return [some(added, "added"), some(changed, "changed"), some(removed, "removed")].filter(Boolean).join("; ");
 }

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

@@ -10,7 +10,7 @@ import { confirmAudience, confirmProfile, follow, getAppSetup, pickSourceFailure
 import { CLI_VERSION } from "./version.js";
 import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
 import { assertAiReady, assertPreviewIntegrationsReady } from "./integrations.js";
-import { kitPaths, readKitLock, recordKitAppId, sourceDigest } from "./kit.js";
+import { describeSourceChange, kitPaths, readKitLock, recordKitAppId, sourceDigest } from "./kit.js";
 import { FLOW_CHECK, preflightKitGate, readReport } from "./check.js";
 /** What the maker types at the save prompt; `--confirm-save` supplies this same literal, so the
  * `isomorph.stage-approval/1.0` attestation governance receives is unchanged, byte for byte. */
@@ -302,8 +302,20 @@ async function assertChecksPassedForTree(root, output) {
     if (!report)
         throw new CliError("CHECKS_NOT_RUN", `This app keeps ${retained.length} check${plural} that say whether it still works, and ${retained.length === 1 ? "it has" : "they have"} never been run against this code. Isomorph does not deploy an app whose own checks have not passed.`, undefined, RUN_THE_CHECKS);
     const tree = await sourceDigest(root);
-    if (report.sourceDigest !== tree.digest)
-        throw new CliError("CHECKS_STALE", "The app's code has changed since its checks last ran, so that result no longer describes what would be deployed. Isomorph does not deploy an app whose own checks have not passed for this exact code.", undefined, RUN_THE_CHECKS);
+    if (report.sourceDigest !== tree.digest) {
+        // Name the paths. Without them the refusal is true but unactionable: a
+        // builder whose agent wrote scratch files into a gitignored folder inside
+        // the app root hit this three times before finding the folder, because
+        // everything inside the root is inside the deployment boundary whether git
+        // tracks it or not. Reports written before CLI 0.3.4 carry no file hashes,
+        // so the sentence degrades to what it always said.
+        // The paths lead, and the whole sentence stays inside output.ts's
+        // DETAIL_BOUND. That bound keeps both ENDS and elides the middle, precisely
+        // because a filename once sat at index 266 and was never printed — so a
+        // path placed mid-sentence is put in the one position the bounding deletes.
+        const moved = describeSourceChange(report.sourceFiles, tree.entries);
+        throw new CliError("CHECKS_STALE", `The app's code has changed since its checks last ran${moved ? ` (${moved})` : ""}. Isomorph does not deploy an app whose checks have not passed for this exact code; everything inside the app folder counts, including files git ignores.`, undefined, RUN_THE_CHECKS);
+    }
     const checks = Array.isArray(report.checks) ? report.checks : [];
     const failed = checks.filter(check => check.status === "fail").map(check => check.name);
     if (failed.length || report.passed !== true)

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

@@ -18,7 +18,7 @@ export async function initKit(root, bundle, options = {}) {
     const existingPackage = await readJson(join(root, "package.json"));
     const emptyDir = !existingPackage && !(await exists(join(root, "src")));
     if (existingPackage && !isSupportedApp(existingPackage))
-        throw new CliError("APP_UNSUPPORTED", "isomorph init supports an empty directory or an existing Vite + React app (package.json must depend on vite and react).");
+        throw new CliError("APP_UNSUPPORTED", "isomorph init supports an empty directory or an existing Vite + React app (package.json must depend on vite and react).", undefined, "Run `isomorph init --app-root <new-empty-folder>` to start a Vite + React app, then move this app's code into it.");
     // An app from a CLI older than 0.2.0 is moved to this layout by `--upgrade`
     // and by nothing else: a plain `init` over it would write a second, empty kit
     // beside the one it has. Refused before anything, the user-level skill included, is written.

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.3.3";
+export const CLI_VERSION = "0.3.4-rc.1";

package/package.json

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