@isomorph.ai/cli 0.8.2 → 0.8.3

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

@@ -108,7 +108,7 @@ Rules live beside this file: \`core.md\` before the first edit; \`integrations.m
 
 ## Getting ready
 
-- No \`.isomorph/\` yet: \`isomorph init --app-root .\` (empty folder → starter; an existing app → three choices to relay). Node 22+, no Docker.
+- No \`.isomorph/\` yet: \`isomorph init --app-root .\` (empty folder → starter; an existing app → three choices to relay). Node 22+, no Docker. Then write the app's \`name\` and \`description\` into \`.isomorph/app.json\` from what they asked and tell them both: IT sees the app under exactly these, once, on its first approval.
 - Sign-in, only when a command answers \`CONFIG_REQUIRED\` or \`AUTH_REQUIRED\` (most machines already are): \`isomorph connect <work-email>\`, then \`isomorph login\` — the browser opens and the person finishes there (their one step; say so).
 
 ## Intent → command

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

@@ -7,7 +7,7 @@ import { continueCommand, follow, outcomeFor, pickSourceFailure, recordedRefusal
 import { CLI_VERSION } from "./version.js";
 import { assertSafeAppRoot, readAppTree } from "./package.js";
 import { deployBlocked, ensureLinkedApp, kitLockBody } from "./integrations.js";
-import { assertLockCompany, describeSourceChange, kitPaths, readAppProfile, readDeclaration, readKitLock, sourceDigest } from "./kit.js";
+import { assertLockCompany, describeSourceChange, kitPaths, readReviewedAppProfile, readDeclaration, readKitLock, sourceDigest } from "./kit.js";
 import { CHECKS_FAILED_HINT, checksFailedMessage, FLOW_CHECK, readReport, runChecks } from "./check.js";
 import { runCommand } from "./local-runtime.js";
 import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
@@ -56,15 +56,14 @@ async function runDeploy(rootArg, governance, output, tenantId, options) {
     assertLockCompany(lock, tenantId);
     // The three values the person confirmed, printed so the transcript shows what
     // was recorded; recorded on the operation before anything is uploaded.
-    const profile = await readAppProfile(root);
+    // Refused here, in the first second, and by the same rule as the first access
+    // request (`APP_PROFILE_UNREVIEWED`): a deploy with the starter profile used
+    // to run the whole gate and open an operation before the profile was refused
+    // (live, 2026-09-16). The deploy route records all three values, so it
+    // refuses a blank one too; this only says so before the checks spend a minute.
+    const profile = await readReviewedAppProfile(root);
     for (const line of describeProfile(profile))
         output(line);
-    // Refused here, in the first second: a deploy with no description used to run
-    // the whole gate and open an operation before the profile was refused (live,
-    // 2026-09-16). The deploy route records all three values, so it refuses one
-    // that is blank too; this only says so before the checks spend a minute.
-    if (!profile.name.trim() || !profile.description.trim())
-        throw new CliError("PROFILE_INCOMPLETE", "The app needs a name and a description in .isomorph/app.json before it can deploy.", undefined, "Edit `name` and `description` in .isomorph/app.json (show them to the person first), then run this again.");
     const declaration = await readDeclaration(root);
     // Link first: the app's identity lands in `.isomorph/kit.lock.json`, which is
     // one of the deployable files, so a report pinned after the link stays fresh

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

@@ -6,7 +6,7 @@ import { createForwarder } from "./forwarder.js";
 import { readKitLock } from "./kit.js";
 import { GovernanceClient, ensureLinkedApp, fileDeclaredRequests, IDENTITY_WORDS, renderGrantGroup } from "./integrations.js";
 import { acquireDevLock, allocatePorts, assertMigrationNames, installDependencies, LocalRuntime, nodePackageCommand, pidAlive, readDevLock, recordDevChildren, releaseDevLock, runCommand } from "./local-runtime.js";
-import { declarationDigest, kitPaths } from "./kit.js";
+import { accessDigest, kitPaths } from "./kit.js";
 import { CliError, safeError } from "./output.js";
 /**
  * Signed in at startup: link the app and file the access request for every
@@ -29,16 +29,21 @@ export async function companyAccessAtStartup(root, client, tenantId, bundle) {
         return { appId: filed.appId, lines };
     }
     catch (error) {
+        // Not a fault: the ask waits on the person. Said in full, since this line is the only place the builder learns why IT has nothing yet; the watcher files once app.json changes.
+        if (error instanceof CliError && error.code === "APP_PROFILE_UNREVIEWED")
+            return { lines: [`Company access not requested yet: ${error.message} ${error.remediationHint ?? ""}`.trim()], failed: true };
         return { lines: [`Company access could not be checked (${safeError(error).message}); the app runs without it until the next start.`], failed: true };
     }
 }
 /**
- * Files the declared requests again whenever `.isomorph/integrations.json`
- * changes while `isomorph dev` runs — `isomorph check` rewrites it as the app's
- * calls change — so adding a company system needs no restart. Before this the
- * session filed once at start, nothing watched the file, and a builder's new
- * connection was never requested (2026-09-17 round). `poll` is one tick; a
- * filing that failed is retried on the next tick with the same digest.
+ * Files the declared requests again whenever `.isomorph/integrations.json` or
+ * `.isomorph/app.json` changes while `isomorph dev` runs — `isomorph check`
+ * rewrites the first as the app's calls change, the builder edits the second
+ * when the person names the app — so adding a company system, or reviewing the
+ * profile the first request waits on, needs no restart. Before this the session
+ * filed once at start, nothing watched the file, and a builder's new connection
+ * was never requested (2026-09-17 round). `poll` is one tick; a filing that
+ * failed is retried on the next tick with the same digest.
  */
 export function declarationWatcher(root, refile, output, filed) {
     let known = filed;
@@ -49,12 +54,12 @@ export function declarationWatcher(root, refile, output, filed) {
                 return;
             busy = true;
             try {
-                const digest = await declarationDigest(root);
+                const digest = await accessDigest(root);
                 if (digest === known)
                     return;
                 const result = await refile();
                 if (result.lines.length)
-                    output([".isomorph/integrations.json changed: company access requested again.", ...result.lines].map(line => `  ${line}`).join("\n"));
+                    output([".isomorph/integrations.json or app.json changed: company access requested again.", ...result.lines].map(line => `  ${line}`).join("\n"));
                 if (!result.failed)
                     known = digest;
             }
@@ -158,7 +163,7 @@ export async function startDev(root, options) {
         ].join("\n"));
         // Signed in: link now and file the app-wide requests — after the link is out, so governance's round-trips never hold it — and say where each connection stands.
         if (governance && company) {
-            const filed = await declarationDigest(root);
+            const filed = await accessDigest(root);
             const access = await companyAccessAtStartup(root, governance, company.tenantId, options.bundle);
             lockAppId = access.appId ?? lockAppId;
             const lines = [...(access.appId && !linkedAtStart ? [`Linked app: ${access.appId}`] : []), ...access.lines];

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

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { linkIdempotencyKey, readDeclaration, readKitLock, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
+import { linkIdempotencyKey, readDeclaration, readKitLock, readReviewedAppProfile, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
 import { CliError } from "./output.js";
 import { CLI_VERSION } from "./version.js";
 /** The lock's bundle as the preflight body carries it. */
@@ -18,7 +18,7 @@ export class GovernanceClient {
     link(input) {
         return this.call("POST", "/v1/development/apps/link", { tenantId: this.tenantId, ...input });
     }
-    /** One app-wide request per (connection, identity): no environment and no expiry — IT approves once for every lane and sets any expiry itself. */
+    /** One app-wide request per (connection, identity): no environment and no expiry — IT approves once for every lane and sets any expiry itself. `app` is the reviewed name and description IT sees the ask under; governance records them before the request. */
     request(appId, input) {
         return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/integration-requests`, { tenantId: this.tenantId, ...input });
     }
@@ -119,12 +119,18 @@ export function transportFailure(error) {
     const text = words(cause) || (Array.isArray(cause?.errors) ? cause.errors.map(words).filter(Boolean).join("; ") : "") || String(cause);
     return typeof cause?.code === "string" && !text.includes(cause.code) ? `${text} (${cause.code})` : text;
 }
-/** Links the app once (stable idempotency key) and records the appId in kit.lock. */
+/**
+ * Links the app once (stable idempotency key) and records the appId in kit.lock.
+ * The link's name is provisional — IT sees nothing of an app until its first
+ * access request, which carries the reviewed profile — so a profile not yet
+ * reviewed (or absent) links under the folder name and is renamed by that request.
+ */
 export async function ensureLinkedApp(root, client, tenantId, bundle) {
     const lock = (await readKitLock(root)) ?? newKitLock(bundle, tenantId);
     if (lock.appId)
         return lock.appId;
-    const linked = await client.link({ displayName: basename(root), idempotencyKey: linkIdempotencyKey(tenantId, root) });
+    const displayName = await readReviewedAppProfile(root).then(profile => profile.name, () => basename(root));
+    const linked = await client.link({ displayName, idempotencyKey: linkIdempotencyKey(tenantId, root) });
     if (!linked.appId)
         throw new CliError("LINK_FAILED", "Isomorph did not return an app identity for this app.");
     await writeKitLock(root, { ...lock, appId: linked.appId, tenantId });
@@ -135,11 +141,11 @@ export const IDENTITY_WORDS = { app: "as the company bot", user: "as the signed-
 /** A refusal about the leg rather than the ask — signed out, unreachable, an answer with no code — is nobody's ask and stops the run. */
 const legFailure = (code) => code === "AUTH_REQUIRED" || code === "GOVERNANCE_UNREACHABLE" || code.startsWith("HTTP_");
 /** One request per identity mode of the connection. A refusal of an ask is returned beside the others, not thrown, so a caller can report every connection at once. */
-async function submitRequests(client, appId, declaration, root, connection, reason, only) {
+async function submitRequests(client, appId, declaration, root, connection, app, reason, only) {
     return Promise.all(requestScope(declaration, connection, only).map(async (part) => {
         const ask = { connection, ...part };
         try {
-            return { ...ask, outcome: await client.request(appId, { connection, identityMode: part.identityMode, operations: part.operations, resources: part.resources, ...(part.presentation ? { presentation: part.presentation } : {}), ...(reason?.trim() ? { reason: reason.trim() } : {}) }) };
+            return { ...ask, outcome: await client.request(appId, { connection, identityMode: part.identityMode, operations: part.operations, resources: part.resources, ...(part.presentation ? { presentation: part.presentation } : {}), ...(reason?.trim() ? { reason: reason.trim() } : {}), app }) };
         }
         catch (error) {
             const refusal = unregisteredResourceGuidance(error, declaration, connection, root);
@@ -149,6 +155,8 @@ async function submitRequests(client, appId, declaration, root, connection, reas
         }
     }));
 }
+/** The two profile values an access request carries. */
+const reviewedProfileBody = (profile) => ({ name: profile.name, description: profile.description });
 /** The filed asks with every refusal thrown, for the commands that cannot go on past one. */
 function settled(requests) {
     return requests.map(item => { if (item.error)
@@ -163,15 +171,18 @@ function settled(requests) {
  * one it is still deciding, so a repeat opens nothing. Links the app first
  * (the same key as `integrations request`) and reads the lanes back, grouped.
  * An app with no declaration or no connections is left alone: nothing to ask,
- * so governance is not called.
+ * so governance is not called. A profile nobody has reviewed is refused
+ * (`APP_PROFILE_UNREVIEWED`) before anything is filed: the request is the
+ * first thing IT sees of the app, under that name and description.
  */
 export async function fileDeclaredRequests(root, client, tenantId, bundle) {
     const declaration = await readDeclaration(root);
     const connections = Object.keys(declaration.connections);
     if (!connections.length)
         return undefined;
+    const app = reviewedProfileBody(await readReviewedAppProfile(root));
     const appId = await ensureLinkedApp(root, client, tenantId, bundle);
-    const requests = (await Promise.all(connections.map(connection => submitRequests(client, appId, declaration, root, connection)))).flat();
+    const requests = (await Promise.all(connections.map(connection => submitRequests(client, appId, declaration, root, connection, app)))).flat();
     return { appId, requests, groups: groupGrants((await client.list(appId)).grants) };
 }
 /**
@@ -181,8 +192,9 @@ export async function fileDeclaredRequests(root, client, tenantId, bundle) {
  */
 export async function requestIntegrations(root, client, tenantId, bundle, options) {
     const declaration = await readDeclaration(root);
+    const app = reviewedProfileBody(await readReviewedAppProfile(root));
     const appId = await ensureLinkedApp(root, client, tenantId, bundle);
-    const submitted = settled(await submitRequests(client, appId, declaration, root, options.connection, options.reason, options.operations)).map(item => ({ ...item, state: item.outcome.state }));
+    const submitted = settled(await submitRequests(client, appId, declaration, root, options.connection, app, options.reason, options.operations)).map(item => ({ ...item, state: item.outcome.state }));
     const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
     const pollMs = options.pollMs ?? 3_000;
     let grants = [];

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

@@ -146,11 +146,60 @@ export function kitPaths(root) {
     const local = join(kit, "local");
     return { kit, local, declaration: join(kit, "integrations.json"), app: join(kit, "app.json"), lock: join(kit, "kit.lock.json"), devLock: join(local, "dev.lock"), state: join(local, "state"), report: join(local, "check-report.json"), deployNote: join(local, "deploy.json") };
 }
+/** The description `init` writes: recognisable later, so a profile nobody has reviewed is never sent to IT. */
+const STARTER_DESCRIPTION_SUFFIX = ": an app built on Isomorph.";
 export function defaultAppProfile(root) {
-    // A real description from the start: the person changes it, but a first
-    // deploy is never refused for a field they have not been shown yet.
+    // A recognisable starter: `profileReviewProblem` refuses it before the first
+    // access request, so the person is shown the name and description exactly
+    // once, before IT sees either, and never again after.
     const name = basename(resolve(root));
-    return { schema: "isomorph.app/1.0", name, description: `${name}: an app built on Isomorph.`, audience: [] };
+    return { schema: "isomorph.app/1.0", name, description: `${name}${STARTER_DESCRIPTION_SUFFIX}`, audience: [] };
+}
+/** Governance's bounds for the profile (maker-app-actions `validateAppProfileInput`), applied here so the refusal is local and names the field. */
+const PROFILE_NAME_LENGTH = { min: 3, max: 80 };
+const PROFILE_DESCRIPTION_LENGTH = { min: 20, max: 240 };
+/**
+ * Why the profile cannot go to IT yet, or `undefined` when it can. The first
+ * access request carries the app's name and description into IT's queue, and
+ * a name IT has seen cannot be unseen: before 0.8.3 that request went out with
+ * the folder name (`my-slack-thing-v2`) and no description, and the real name
+ * only arrived with `deploy` — relabelling the ask under the admin (2026-09-18).
+ * So the starter values `init` wrote are refused until the builder has shown
+ * them to the person and written what they said; a reviewed profile passes
+ * every later run unchanged.
+ */
+export function profileReviewProblem(profile, root) {
+    const name = profile.name.trim();
+    const description = profile.description.trim();
+    if (!name)
+        return "`name` is empty";
+    if (name === basename(resolve(root)))
+        return "`name` is still the folder name";
+    if (!description)
+        return "`description` is empty";
+    if (description.endsWith(STARTER_DESCRIPTION_SUFFIX))
+        return "`description` is still the starter text";
+    if (name.length < PROFILE_NAME_LENGTH.min || name.length > PROFILE_NAME_LENGTH.max)
+        return `\`name\` must be ${PROFILE_NAME_LENGTH.min}-${PROFILE_NAME_LENGTH.max} characters`;
+    if (description.length < PROFILE_DESCRIPTION_LENGTH.min || description.length > PROFILE_DESCRIPTION_LENGTH.max)
+        return `\`description\` must be ${PROFILE_DESCRIPTION_LENGTH.min}-${PROFILE_DESCRIPTION_LENGTH.max} characters`;
+    return undefined;
+}
+/** The profile as the first access request may carry it, or the one refusal that says what to review. */
+export async function readReviewedAppProfile(root) {
+    const profile = await readAppProfile(root);
+    const problem = profileReviewProblem(profile, root);
+    if (problem)
+        throw new CliError("APP_PROFILE_UNREVIEWED", `IT will see this app by its name and description, and .isomorph/app.json has not been reviewed yet: ${problem}.`, undefined, "Show the person the `name` and `description` in .isomorph/app.json, write what they say (a name for colleagues, one sentence on what the app does), then run this again. This is asked once: a reviewed profile is never asked about again.");
+    return profile;
+}
+/** What changes the app's standing with the company: the declaration and the profile the first request carries. */
+export async function accessDigest(root) {
+    const paths = kitPaths(root);
+    const hash = createHash("sha256");
+    for (const path of [paths.declaration, paths.app])
+        hash.update(await readFile(path).catch(() => Buffer.alloc(0))).update("\0");
+    return `sha256:${hash.digest("hex")}`;
 }
 /** `.isomorph/app.json` as `init` writes it. */
 export function renderAppProfile(profile) {

package/package.json

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