@fourier-labs/harbour 0.1.22 → 0.1.23

package/README.md

@@ -7,12 +7,12 @@ The Harbour CLI: sets up, runs, checks and ships an Isomorph app. It is meant to
 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 @fourier-labs/harbour@stable agent-setup
+npx -y @fourier-labs/harbour agent-setup
 ```
 
 Paste that line into Claude Code or Codex (or a terminal). It teaches both agents the kit: it writes the `isomorph` skill for Claude Code (`~/.claude/skills/isomorph/SKILL.md`) and a fenced block in your global Codex instructions (`~/.codex/AGENTS.md`), and never touches your other skills or instructions.
 
-That `npx` line runs the current release, but `harbour init`, `dev` and `check` afterwards run whatever `harbour` 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 @fourier-labs/harbour@stable`.
+That `npx` line runs the current release, but `harbour init`, `dev` and `check` afterwards run whatever `harbour` 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 @fourier-labs/harbour`.
 
 Then, in an empty folder:
 

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

@@ -8,8 +8,12 @@ import { CLI_VERSION } from "./version.js";
 const execFileAsync = promisify(execFile);
 export const MANAGED_START = "<!-- harbour:kit:start -->";
 export const MANAGED_END = "<!-- harbour:kit:end -->";
-/** The one command that installs or upgrades the CLI; every instruction in the kit names this tag. */
-export const CLI_INSTALL_COMMAND = "npm i -g @fourier-labs/harbour@stable";
+/**
+ * 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 @fourier-labs/harbour";
 /** Where the two agents read their user-level instructions from; both honour the tools' own override variables. */
 export function agentPaths(env = process.env) {
     const home = env.HARBOUR_AGENT_HOME?.trim() || homedir();
@@ -144,7 +148,7 @@ The person you are working with may not be a developer. They say what they want
 
 ## Getting ready (do this yourself, once per machine and folder)
 
-1. CLI, before \`harbour 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. \`harbour 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 \`harbour --version\` with \`npx -y @fourier-labs/harbour@stable --version\` yourself. If either says the installed one is missing or older, run \`npm i -g @fourier-labs/harbour@stable\` and confirm \`harbour --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+ and Docker Desktop running; if Docker is missing, that is the one thing to tell them to install, in one line.
+1. CLI, before \`harbour 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. \`harbour 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 \`harbour --version\` with \`npx -y @fourier-labs/harbour --version\` yourself. If either says the installed one is missing or older, run \`npm i -g @fourier-labs/harbour\` and confirm \`harbour --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+ and Docker Desktop running; if Docker is missing, that is the one thing to tell them to install, in one line.
 2. Folder: if the current folder has no \`.harbour/\` directory, run \`harbour 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 "Harbour 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 \`harbour 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 them for the Harbour link their IT/admin gave them and run \`harbour connect <link>\` first.
 

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

@@ -2,7 +2,7 @@
 import { RemoteMcpClient } from "./remote-mcp-client.js";
 import { productionise } from "./productionise.js";
 import { confirmAudience, confirmProfile, dismissSecret, fetchStatus, getAppSetup, listSecrets, outcomeFor, promoteToProduction, readSecretFromStdin, readSecretFromTerminal, retryDeployment, setSecret, summarize, waitForSettled } from "./operations.js";
-import { safeError, CliError, renderSummary } from "./output.js";
+import { CliError, failureEnvelope, renderFailure, renderSummary } from "./output.js";
 import { CLI_VERSION } from "./version.js";
 import { connectedAccount, login, logout, refreshStoredToken } from "./auth.js";
 import { connect, loadConfig, resolveConfig } from "./config.js";
@@ -255,13 +255,12 @@ else {
         }
     }
     catch (error) {
-        const safe = safeError(error);
-        process.stderr.write(`${safe.message}\n`);
-        const envelope = { schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "FAILED", operationStarted: error instanceof CliError ? Boolean(error.operationRef) : false, ...(error instanceof CliError && error.operationRef ? { operationRef: error.operationRef } : {}), error: safe };
+        const envelope = failureEnvelope(error, CLI_VERSION);
+        process.stderr.write(renderFailure(envelope));
         if (json || command === "productionise")
             process.stdout.write(`${JSON.stringify(envelope)}\n`);
         // Exit 2, like a usage error: nothing started and the fix is a command the maker runs.
-        process.exitCode = safe.code === "INTEGRATIONS_NOT_READY" ? 2 : 1;
+        process.exitCode = envelope.error?.code === "INTEGRATIONS_NOT_READY" ? 2 : 1;
     }
 }
 function renderIntegrationsStatus(status) {

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

@@ -23,6 +23,32 @@ function pickDeployment(value) {
         ...(value.failure ? { failure: { ...(value.failure.message ? { message: value.failure.message } : {}), ...(value.failure.retryable !== undefined ? { retryable: value.failure.retryable } : {}), ...(value.failure.remediationHint ? { remediationHint: value.failure.remediationHint } : {}) } } : {})
     };
 }
+/**
+ * The refusal reason source intake stored on the operation. Read the same way
+ * `pickDeployment` reads a deployment failure: keep the server's own code,
+ * wording and remediation, drop anything blank, and report nothing at all when
+ * the server supplied nothing — so a caller can tell "no detail" apart from
+ * "detail that happened to be empty".
+ */
+export function pickSourceFailure(status) {
+    const failure = status.operation?.source?.failure;
+    if (!failure || typeof failure !== "object")
+        return undefined;
+    const code = text(failure.code);
+    const message = text(failure.message);
+    const remediationHint = text(failure.remediationHint);
+    if (!code && !message && !remediationHint)
+        return undefined;
+    return {
+        ...(code ? { code } : {}),
+        ...(failure.retryable !== undefined ? { retryable: failure.retryable } : {}),
+        ...(message ? { message } : {}),
+        ...(remediationHint ? { remediationHint } : {})
+    };
+}
+function text(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
 function pickProduction(value) {
     return {
         state: value.state,

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

@@ -2,7 +2,26 @@ export function safeError(error) {
     const code = error instanceof CliError ? error.code : "CLI_FAILED";
     const original = error instanceof Error ? error.message : "";
     const raw = error instanceof CliError ? error.message : friendlyMessage(original);
-    return { code, message: raw.replace(/https?:\/\/\S+|Bearer\s+\S+|(?:x-harbour|authorization|content-type)[^\n]*/gi, "").replace(/\s+/g, " ").trim().slice(0, 240) || "Harbour could not complete the request." };
+    // The hint is a separate field rather than more sentence: it is often as long
+    // as the message, and appending it would push the reason itself past the cap.
+    const hint = error instanceof CliError && error.remediationHint ? redact(error.remediationHint) : "";
+    return { code, message: redact(raw) || "Harbour could not complete the request.", ...(hint ? { remediationHint: hint } : {}) };
+}
+function redact(value) {
+    return value.replace(/https?:\/\/\S+|Bearer\s+\S+|(?:x-harbour|authorization|content-type)[^\n]*/gi, "").replace(/\s+/g, " ").trim().slice(0, 240);
+}
+/**
+ * What a failed command reports: the JSON envelope on stdout and the line on
+ * stderr. One place, so the human line and the envelope always carry the same
+ * reason and the same fix.
+ */
+export function failureEnvelope(error, cliVersion) {
+    const operationRef = error instanceof CliError ? error.operationRef : undefined;
+    return { schema: "harbour.cli-result/1.0", cliVersion, status: "FAILED", operationStarted: Boolean(operationRef), ...(operationRef ? { operationRef } : {}), error: safeError(error) };
+}
+export function renderFailure(envelope) {
+    const error = envelope.error;
+    return `${error?.message ?? "Harbour could not complete the request."}${error?.remediationHint ? ` ${error.remediationHint}` : ""}\n`;
 }
 /** Human-readable stdout for runs without `--json`: the operation reference and
  * whatever link or next step Harbour reported, nothing internal. */
@@ -58,10 +77,12 @@ export function renderSummary(envelope) {
 export class CliError extends Error {
     code;
     operationRef;
-    constructor(code, message, operationRef) {
+    remediationHint;
+    constructor(code, message, operationRef, remediationHint) {
         super(message);
         this.code = code;
         this.operationRef = operationRef;
+        this.remediationHint = remediationHint;
     }
 }
 function friendlyMessage(message) {

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

@@ -6,7 +6,7 @@ import { createSourceManifest } from "../../../src/source-intake.js";
 import { structured } from "./remote-mcp-client.js";
 import { archiveForManifest, putMultipart } from "./upload.js";
 import { CliError } from "./output.js";
-import { getAppSetup, outcomeFor, readLine, waitForSettled } from "./operations.js";
+import { getAppSetup, outcomeFor, pickSourceFailure, readLine, waitForSettled } from "./operations.js";
 import { CLI_VERSION } from "./version.js";
 import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
 import { assertPreviewIntegrationsReady } from "./integrations.js";
@@ -134,10 +134,22 @@ async function waitForIntake(client, operationRef) {
         if (status.operation?.stage === "awaiting-approval" || status.sourceSave?.status === "QUEUED")
             return;
         if (status.operation?.stage === "failed")
-            throw new CliError("PACKAGE_REJECTED", "Harbour could not safely accept this app package.", operationRef);
+            throw intakeRejection(status, operationRef);
     }
     throw new CliError("INSPECTION_TIMEOUT", "Harbour is still inspecting the app package. Resume this operation safely.", operationRef);
 }
+/**
+ * Intake does not merely refuse a package; it records why — a stable code, one
+ * plain-English sentence, and the commands that fix it — on the operation. The
+ * stage alone was all this used to read, so every refusal reached the maker as
+ * the same sentence and the reason stayed on the server. Say what the server
+ * said, and keep the generic line only for an operation that failed without
+ * any detail at all.
+ */
+function intakeRejection(status, operationRef) {
+    const failure = pickSourceFailure(status);
+    return new CliError(failure?.code ?? "PACKAGE_REJECTED", failure?.message ?? "Harbour could not safely accept this app package.", operationRef, failure?.remediationHint);
+}
 async function execute(client, operationRef, appId, graph, approval) {
     const args = { operationId: operationRef, appId, surface: "codex", graph, action: "save_baseline", mode: "EXECUTE" };
     if (approval)

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

@@ -28,6 +28,8 @@ export async function initKit(root, bundle, options = {}) {
         await writeFile(absolute, content);
         result.created.push(path);
     };
+    // The starter (its source, schema and retained checks) is created only when there is
+    // no app here yet; kit infrastructure is written on every path, including `--upgrade`.
     const appFiles = emptyDir ? starterFiles(bundle) : {};
     for (const [path, content] of Object.entries({ ...appFiles, ...kitFiles() }))
         await write(path, content);
@@ -115,6 +117,12 @@ Follow the "Harbour development kit" block in CLAUDE.md / AGENTS.md. Workflow:
 4. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for development access; pending is not ready.
 5. \`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
+ * `--upgrade`. Nothing here is example content, because `write` only fills a
+ * gap: an app that deleted a file it does not want must not have it recreated.
+ */
 function kitFiles() {
     return {
         // No connection. The starter calls no company system, and a connection the
@@ -125,7 +133,20 @@ function kitFiles() {
         // development kit" block of AGENTS.md / CLAUDE.md and in src/App.tsx. They
         // are not in this file: it is read with JSON.parse here and again by the
         // pipeline's source intake, so it cannot carry comments.
-        ".harbour/integrations.json": `${JSON.stringify({ schema: "harbour.app-integrations/2.0", connections: {} }, null, 2)}\n`,
+        ".harbour/integrations.json": `${JSON.stringify({ schema: "harbour.app-integrations/2.0", connections: {} }, null, 2)}\n`
+    };
+}
+/**
+ * The starter app itself: written only when `init` is creating one in an empty
+ * directory. This includes the notes migration and the three retained checks —
+ * they are the starter's own schema and journeys, not kit infrastructure, and
+ * they exist so a fresh starter passes the pipeline's `flow` gate (one journey
+ * per capability its UI declares, plus the cross-user denial). Writing them into
+ * an app that has its own schema recreates a `notes` table it never had, and the
+ * checks that query it then fail `flow` on the next deploy.
+ */
+function starterFiles(bundle) {
+    return {
         "migrations/0001_notes.sql": MIGRATION,
         // One retained check per capability the starter's UI uses: the pipeline's
         // flow gate refuses an app whose checks never exercise a declared capability.
@@ -133,11 +154,7 @@ function kitFiles() {
         ".harbour/checks/files-journey.mjs": FILES_JOURNEY_CHECK,
         // The pipeline's cross-user denial, run locally: the last gate class that
         // used to exist only in CodeBuild.
-        ".harbour/checks/notes-cross-user.mjs": CROSS_USER_CHECK
-    };
-}
-function starterFiles(bundle) {
-    return {
+        ".harbour/checks/notes-cross-user.mjs": CROSS_USER_CHECK,
         "package.json": `${JSON.stringify({
             name: "harbour-app", private: true, version: "0.1.0", type: "module",
             scripts: { dev: "vite", build: "tsc --noEmit && vite build", preview: "vite preview" },

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.22";
+export const CLI_VERSION = "0.1.23";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": {