@fourier-labs/harbour 0.1.24 → 0.1.25

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

@@ -1,7 +1,7 @@
 import { readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { loadDatabaseGate } from "./database-gate.js";
-import { CoverageLedger, createCoverageProxy, declaredCapabilities, missingFlowOperations, sourceTableVerbs } from "./flow-coverage.js";
+import { CoverageLedger, capabilityCallSurface, createCoverageProxy, declaredCapabilities, flowDetail, missingFlowOperations, orphanedChecks, sourceTableVerbs } from "./flow-coverage.js";
 import { CliError } from "./output.js";
 import { DEPENDENT_READ_OPERATIONS, READ_OPERATIONS, kitPaths, readDeclaration, readKitLock, resourceNames, sourceDigest } from "./kit.js";
 import { LOCAL, LocalRuntime, identityEnvironment, runCommand, runningOrigin } from "./local-runtime.js";
@@ -72,17 +72,25 @@ export async function runChecks(root, options) {
         const appUrl = await proxy.listen();
         try {
             for (const name of journeys) {
+                // The journeys run one at a time, so naming the running check makes the
+                // gateway traffic that follows attributable to it — which is what lets
+                // an orphaned check be named as the file to delete.
+                ledger.nowRunning(name);
                 const result = await run("node", [join(kitPaths(root).checks, name)], { cwd: root, quiet: true, env: { HARBOUR_APP_URL: appUrl, HARBOUR_SDK_MODULE: join(root, "node_modules", "@harbour", "app-sdk", "dist", "index.js"), ...identityEnvironment(session) } });
+                ledger.nowRunning(undefined);
                 record(`journey:${name}`, result.code === 0 ? "pass" : "fail", result.code === 0 ? undefined : lastLines(result.stderr || result.stdout));
             }
         }
         finally {
+            ledger.nowRunning(undefined);
             await proxy.close();
         }
+        // Both directions of the pipeline's gate: an operation or capability the
+        // app has with no check exercising it, and a check exercising a capability
+        // the app does not have.
         const missing = missingFlowOperations(await sourceTableVerbs(root), await declaredCapabilities(root), ledger);
-        record("flow", missing.length ? "fail" : "pass", missing.length
-            ? `${missing.join("; ")}. Exercise the converted application operations with source-valid inputs and assertions; an unrelated passing check is insufficient. The pipeline refuses this deployment as kit.check-failed: flow.check-failed.`
-            : "every operation the app performs and every capability it declares was exercised by a retained check");
+        const orphaned = orphanedChecks(await capabilityCallSurface(root), ledger);
+        record("flow", missing.length || orphaned.length ? "fail" : "pass", flowDetail(missing, orphaned));
     }
     let integrations = "not tested";
     if (options.governance && lock?.appId && !declaration.errors.length) {

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

@@ -25,16 +25,58 @@ export const COVERED_CAPABILITIES = ["data", "files", "actions", "telemetry", "r
 const SDK_CAPABILITIES = ["data", "files", "actions", "realtime", "telemetry", "integrations"];
 const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
 const SKIPPED_DIRECTORIES = new Set(["node_modules", ".git", "dist", "build", ".harbour"]);
-const TABLE_CHAIN = /\.from\(\s*["'`]([A-Za-z0-9_]+)["'`]\s*\)/g;
-const VERB_CALL = /\.(select|insert|update|delete|upsert)\s*\(/g;
+/**
+ * TypeScript call sites carry explicit type arguments between a method name and
+ * its call — `harbour.data.from<Note>("notes")`, `.select<Row>(` — and the
+ * starter's own list is one of them. Matching only the bare `.from(` made every
+ * typed call site invisible, so a freshly generated starter inventoried
+ * `notes: delete, insert, update` with no SELECT: the gate was reading the
+ * starter's own capabilities wrong. This is the pipeline's own
+ * `appSDKTypeArguments` (transformbuild/source_inspection.go), one nesting
+ * level of generics, so both scanners see the same call sites.
+ */
+const TYPE_ARGUMENTS = String.raw `(?:<[^<>()]*(?:<[^<>()]*>[^<>()]*)*>)?\s*`;
+const TABLE_CHAIN_SOURCE = String.raw `\.from${TYPE_ARGUMENTS}\(\s*["'\`]([A-Za-z0-9_]+)["'\`]\s*\)`;
+const TABLE_CHAIN = new RegExp(TABLE_CHAIN_SOURCE, "g");
+/** The same chain, unanchored and non-global: where THIS chain's verbs stop. */
+const NEXT_TABLE_CHAIN = new RegExp(TABLE_CHAIN_SOURCE);
+const VERB_CALL = new RegExp(String.raw `\.(select|insert|update|delete|upsert)\s*${TYPE_ARGUMENTS}\(`, "g");
 /** `createClient()` bindings name the identifier a capability call must be made on. */
 const CLIENT_BINDING = /(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?::[^=]+)?=\s*(?:await\s+)?createClient\s*\(/g;
+/** `<anything>.<namespace>.<method>(` — the receiver is deliberately not constrained; see capabilityCallSurface. */
+const CAPABILITY_CALL = new RegExp(String.raw `\.\s*(${SDK_CAPABILITIES.join("|")})\s*\.\s*[A-Za-z_$][A-Za-z0-9_$]*\s*${TYPE_ARGUMENTS}\(`, "g");
 /** Records the gateway operations observed while the retained checks ran. */
 export class CoverageLedger {
     seen = new Set();
+    /** capability -> the retained checks that asked the gateway for it. */
+    asked = new Map();
+    running;
     add(key) { this.seen.add(key); }
     has(key) { return this.seen.has(key); }
     keys() { return [...this.seen].sort(); }
+    /**
+     * Names the retained check whose gateway traffic follows. The journeys run
+     * one at a time, so a request the proxy sees between this call and the next
+     * belongs to this check — which is how a refusal can name the file to delete.
+     */
+    nowRunning(check) { this.running = check; }
+    /**
+     * One request the running check sent at a capability-gated path, recorded
+     * whatever the answer was. The deployed gateway resolves the capability
+     * BEFORE any handler runs and answers 404 when the app did not declare it
+     * (appgateway/resolver.go "capability is not declared"), so the request
+     * itself — not its local success — is what decides the check's fate there.
+     */
+    askedFor(path) {
+        const capability = capabilityForRequest(path);
+        if (!capability || !this.running)
+            return;
+        const checks = this.asked.get(capability) ?? new Set();
+        checks.add(this.running);
+        this.asked.set(capability, checks);
+    }
+    /** capability -> the checks that asked for it, for the reverse coverage question. */
+    capabilitiesAsked() { return this.asked; }
     /**
      * The gateway's data boundary. A write that changed no row proves nothing, so
      * only a select — or a mutation that returned rows — counts (observeData in
@@ -82,7 +124,7 @@ export async function sourceTableVerbs(root) {
             const semicolon = tail.indexOf(";");
             if (/[;\n]/.test(tail) && semicolon >= 0)
                 tail = tail.slice(0, semicolon);
-            const next = tail.indexOf(".from(");
+            const next = tail.search(NEXT_TABLE_CHAIN);
             if (next > 0)
                 tail = tail.slice(0, next);
             tail = tail.slice(0, 200);
@@ -119,6 +161,101 @@ export async function declaredCapabilities(root) {
     }
     return used;
 }
+/**
+ * Every capability namespace the app's own source calls a method on, whatever
+ * object the call is made on: `harbour.files.list(`, `client().files.list(`,
+ * `(harbour as {files: F}).files.list(`.
+ *
+ * This is deliberately looser than `declaredCapabilities`, and the two answer
+ * different questions. The forward gate asks "was this capability exercised?"
+ * and must be precise about what the app really uses. The reverse gate below
+ * asks "is this check exercising something the app no longer has?" — a
+ * question whose wrong answer refuses a good app — so it needs a lower bound on
+ * what is unused, never an upper bound on what is used.
+ *
+ * The pipeline's own evidence for a capability is `<client>.<namespace>.<method>(`
+ * with the client traced through the module graph (transformbuild
+ * analyzeAppSDKClientCalls / analyzeAppSDKNamespaceWrappers). Dropping the
+ * receiver makes this a superset of that set — every call site the pipeline can
+ * trace, plus ones it cannot — so a capability this cannot see is one the kit
+ * lane cannot declare either, and the reverse gate refuses only trees the
+ * pipeline already refuses. Where it errs it errs by staying quiet: a
+ * commented-out call still counts here, and the pipeline masks comments.
+ */
+export async function capabilityCallSurface(root) {
+    const surface = new Set();
+    for (const path of await sourceFiles(root)) {
+        const text = await readFile(path, "utf8").catch(() => "");
+        for (const match of text.matchAll(CAPABILITY_CALL))
+            surface.add(match[1]);
+    }
+    return surface;
+}
+/**
+ * The gateway's own path -> capability map (appgateway/gateway.go
+ * `capabilityForRequest`). Every one of these paths is resolved against the
+ * app's declared capability set before it is served.
+ */
+export function capabilityForRequest(path) {
+    if (path === "/_harbour/realtime")
+        return "realtime";
+    if (path.startsWith("/_harbour/files"))
+        return "files";
+    if (path.startsWith("/_harbour/actions/"))
+        return "actions";
+    if (path === "/_harbour/telemetry")
+        return "telemetry";
+    if (path.startsWith("/_harbour/integrations/"))
+        return "integrations";
+    if (path.startsWith("/_harbour/data/"))
+        return "data";
+    return undefined;
+}
+/**
+ * The other direction, and the one that let a real deploy fail twice: a
+ * retained check exercising a capability the app does not have any more.
+ *
+ * A builder's agent replaced the starter's notes schema and deleted the
+ * "Private files" section but left `.harbour/checks/files-journey.mjs` behind.
+ * The kit lane derives `.harbour/app-capabilities.json` from the browser SDK
+ * surface, the cell's App Gateway serves only what that file declares, and the
+ * journey's first `harbour.files.*` call came back 404 — `flow.check-failed …
+ * files-journey.mjs: exit status 1`, twice, 2m23s and 2m12s. Locally the check
+ * was green: `harbour dev` hard-codes data/files/realtime/telemetry
+ * (local-runtime.ts `gatewayConfig`) and always provisions MinIO, so the
+ * orphaned journey passed on its own terms.
+ *
+ * This reproduces the pipeline's refusal rather than inventing a second
+ * opinion, at the pipeline's own granularity — the capability, not the table.
+ * The pipeline does have a table-level reverse check
+ * (`rejectServerTierOperationsDrivenFromTheBrowser`), but it is scoped to apps
+ * that declare a workload directory; a kit app has none, so a check that reads
+ * a table the browser no longer reads is served there and must be served here.
+ */
+export function orphanedChecks(surface, ledger) {
+    const orphaned = [];
+    for (const [capability, checks] of ledger.capabilitiesAsked()) {
+        if (surface.has(capability))
+            continue;
+        for (const check of checks) {
+            orphaned.push(`${check}: exercises the ${capability} capability, which no code in this app calls any more. ` +
+                `The deployed gateway serves only the capabilities the kit lane derives from the source, so it refuses this check as ` +
+                `flow.check-failed: ${check}: exit status 1. Delete .harbour/checks/${check}, or restore the harbour.${capability}.* feature it was written for.`);
+        }
+    }
+    return orphaned.sort();
+}
+/** The `flow` check's detail, in the pipeline's words, for both directions. */
+export function flowDetail(missing, orphaned) {
+    const parts = [];
+    if (missing.length)
+        parts.push(`${missing.join("; ")}. Exercise the converted application operations with source-valid inputs and assertions; an unrelated passing check is insufficient.`);
+    if (orphaned.length)
+        parts.push(orphaned.join("; "));
+    if (!parts.length)
+        return "every operation the app performs and every capability it declares was exercised by a retained check, and no retained check exercises a capability the app no longer has";
+    return `${parts.join(" ")} The pipeline refuses this deployment as kit.check-failed: flow.check-failed.`;
+}
 /**
  * What the pipeline would refuse, in its own words: an inventoried operation or
  * a declared capability with no successful observation while the checks ran.
@@ -151,6 +288,10 @@ export function createCoverageProxy(origin, ledger) {
     const upstreamOrigin = target.origin;
     const server = createServer((incoming, response) => {
         const path = (incoming.url ?? "/").split("?")[0];
+        // Before the answer: the deployed gateway refuses an undeclared capability
+        // at this path whatever the handler would have said, so what the check
+        // asked for is the evidence the reverse gate needs.
+        ledger.askedFor(path);
         const chunks = [];
         incoming.on("data", chunk => { if (chunks.length < 64)
             chunks.push(chunk); });
@@ -177,6 +318,7 @@ export function createCoverageProxy(origin, ledger) {
     // receives nothing does not clear the capability here either.
     server.on("upgrade", (incoming, socket, head) => {
         const path = (incoming.url ?? "/").split("?")[0];
+        ledger.askedFor(path);
         const upstream = connect(port, host, () => {
             const headers = Object.entries({ ...forwardable(incoming.headers, upstreamOrigin), host: `${host}:${port}`, connection: "Upgrade", upgrade: "websocket" })
                 .map(([key, value]) => `${key}: ${value}`);

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

@@ -105,43 +105,110 @@ export function renderFailure(envelope) {
     const error = envelope.error;
     return `${error?.message ?? NO_DETAIL}${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. */
+/**
+ * Server-supplied text on its way to a terminal, given exactly the treatment
+ * `safeError` gives the failure path: secrets stripped, whitespace collapsed,
+ * bounded at `DETAIL_BOUND` keeping both ends.
+ *
+ * `safeError` was `redact`’s only caller. `renderSummary` printed the server’s
+ * words straight from the payload, so on the success-shaped path — a deployment
+ * that reports a failure inside an otherwise-successful envelope, which is what
+ * `status` and `productionise` emit after a failed build — that text reached the
+ * terminal both unredacted and unbounded. A presigned URL, a bearer token or a
+ * forwarded header dump printed verbatim into whatever captured stdout, and a
+ * pathological message printed whole.
+ *
+ * That is the opposite defect to the one the tail-keeping change fixed: that
+ * one lost information, this one leaks and floods. One function and not a
+ * second implementation, because a second implementation is how the two paths
+ * came to differ at all.
+ */
+function said(value) {
+    return value ? redact(value) : "";
+}
+/**
+ * Human-readable stdout for runs without `--json`: the operation reference and
+ * whatever link or next step Harbour reported, nothing internal.
+ *
+ * Every server-supplied string printed here goes through `said`. What does not
+ * is listed below, because each is a value whose whole job is to be reproduced
+ * verbatim, and each would be destroyed by the very rules that make redaction
+ * worth doing:
+ *
+ *  - `protectedUrl`, `productionUrl` — `SECRETS` strips URLs, and these two are
+ *    the app’s address: the thing the builder ran the command to get.
+ *  - `operationRef` — the handle every later `--operation` needs, and already
+ *    exempt on the failure path: `safeError` redacts the message and the hint,
+ *    never the reference they travel with. The same policy on both paths.
+ *  - `secrets.asks[].name` and `.prefilledFromPath` — identifiers, not prose. A
+ *    secret named `AUTHORIZATION_TOKEN` matches the header pattern and would be
+ *    erased whole, printing `Secret : needs a value`; the path is read off the
+ *    local checkout rather than sent by the server.
+ *  - `audience.emails` — the builder’s own confirmed list, echoed back. A
+ *    240-character bound over a joined list silently drops members, which is
+ *    the information loss the tail-keeping change was about.
+ *  - `ask.status`, `ask.scope`, `secrets.available`, `audience.confirmed` and
+ *    the three mapped `pending` steps — compared against fixed literals, so
+ *    only Harbour’s own words ever print. An unmapped `pending` step is the
+ *    server’s own id, so that one does go through `said`.
+ *
+ * `deployment.message` and `production.message` are declared on the payload and
+ * never printed here; nothing routes them, and a line that printed one would
+ * need `said` like the rest. The `--json` envelope is unchanged: it carries the
+ * raw structured result by design and this is about what is printed. Whether
+ * the envelope should be redacted too is a decision about that contract, not
+ * one to take in the renderer.
+ */
 export function renderSummary(envelope) {
     const lines = [];
     const result = (envelope.result ?? {});
     if (envelope.operationRef)
         lines.push(`Operation reference: ${envelope.operationRef}`);
-    if (result.verification)
-        lines.push(`Saved app: ${result.verification}${result.assuranceLevel ? ` (${result.assuranceLevel})` : ""}`);
+    const verification = said(result.verification);
+    const assurance = said(result.assuranceLevel);
+    if (verification)
+        lines.push(`Saved app: ${verification}${assurance ? ` (${assurance})` : ""}`);
     if (result.production) {
-        lines.push(`Production: ${result.production.state}${result.production.productionUrl ? ` — ${result.production.productionUrl}` : ""}`);
+        lines.push(`Production: ${said(result.production.state)}${result.production.productionUrl ? ` — ${result.production.productionUrl}` : ""}`);
+        // `|| NO_DETAIL` for the reason `safeError` has it: redaction can empty a
+        // string, and a failure reported as two spaces is worse than one that says
+        // plainly this CLI has nothing to show.
         if (result.production.failure?.message)
-            lines.push(`  ${result.production.failure.message}`);
+            lines.push(`  ${said(result.production.failure.message) || NO_DETAIL}`);
     }
     if (result.deployment) {
-        lines.push(`Preview deployment: ${result.deployment.status ?? result.deployment.state}${result.deployment.protectedUrl ? ` — ${result.deployment.protectedUrl}` : ""}`);
-        if (result.deployment.failure?.message)
-            lines.push(`  ${result.deployment.failure.message}${result.deployment.failure.remediationHint ? ` ${result.deployment.failure.remediationHint}` : ""}`);
+        lines.push(`Preview deployment: ${said(result.deployment.status ?? result.deployment.state)}${result.deployment.protectedUrl ? ` — ${result.deployment.protectedUrl}` : ""}`);
+        if (result.deployment.failure?.message) {
+            // The hint is redacted and bounded on its own, exactly as `safeError`
+            // bounds it separately from the message: appending it first would spend
+            // the message’s own budget on it.
+            const hint = said(result.deployment.failure.remediationHint);
+            lines.push(`  ${said(result.deployment.failure.message) || NO_DETAIL}${hint ? ` ${hint}` : ""}`);
+        }
     }
-    if (result.waiting?.plainEnglish)
-        lines.push(`Action needed: ${result.waiting.plainEnglish}`);
-    else if (result.nextStep)
-        lines.push(`Next: ${result.nextStep}`);
+    // Gated on the redacted value rather than the raw one, so guidance that is
+    // nothing but a link falls through to the next step instead of printing a
+    // label with nothing after it.
+    const waiting = said(result.waiting?.plainEnglish);
+    const nextStep = said(result.nextStep);
+    if (waiting)
+        lines.push(`Action needed: ${waiting}`);
+    else if (nextStep)
+        lines.push(`Next: ${nextStep}`);
     const setup = envelope.result?.setup;
     const secrets = setup?.secrets ?? envelope.result?.secrets;
     if (setup?.profile) {
-        lines.push(`App name: ${setup.profile.displayName ?? "(none)"}${setup.profile?.confirmed ? " (confirmed)" : setup.profile?.suggested?.displayName ? ` — suggested: ${setup.profile.suggested.displayName}` : " (not confirmed)"}`);
+        lines.push(`App name: ${said(setup.profile.displayName) || "(none)"}${setup.profile?.confirmed ? " (confirmed)" : setup.profile?.suggested?.displayName ? ` — suggested: ${said(setup.profile.suggested.displayName)}` : " (not confirmed)"}`);
         if (setup.profile?.description || setup.profile?.suggested?.description)
-            lines.push(`Description: ${setup.profile?.confirmed ? setup.profile.description : setup.profile?.suggested?.description ?? setup.profile?.description}`);
+            lines.push(`Description: ${said(setup.profile?.confirmed ? setup.profile.description : setup.profile?.suggested?.description ?? setup.profile?.description)}`);
         if (setup.audience?.available === false)
-            lines.push(`Audience: ${setup.audience.plainEnglish ?? "console only"}`);
+            lines.push(`Audience: ${said(setup.audience.plainEnglish) || "console only"}`);
         else
             lines.push(`Audience: ${setup.audience?.confirmed ? (setup.audience.emails?.length ? setup.audience.emails.join(", ") : "only you") + " (confirmed)" : "not confirmed"}`);
     }
     if (secrets) {
         if (secrets.available === false)
-            lines.push(`Secrets: ${secrets.plainEnglish ?? "console only"}`);
+            lines.push(`Secrets: ${said(secrets.plainEnglish) || "console only"}`);
         else if (!secrets.asks?.length)
             lines.push("Secrets: none asked for");
         else
@@ -149,7 +216,7 @@ export function renderSummary(envelope) {
                 lines.push(`Secret ${ask.name}: ${ask.status === "UNSET" ? "needs a value" : ask.status === "SET" ? "set" : "not needed"}${ask.scope === "personal" ? " (personal)" : ""}${ask.prefilledFromPath ? ` (from ${ask.prefilledFromPath})` : ""}`);
     }
     // productionise carries only the open steps; the setup commands carry the full view.
-    const openSteps = setup?.pending?.length ? setup.pending.map(step => step === "confirm_app_profile" ? "confirm the app's name and description" : step === "confirm_app_audience" ? "confirm who may open it" : step === "provide_secrets" ? "provide the secrets it asked for" : step) : [];
+    const openSteps = setup?.pending?.length ? setup.pending.map(step => step === "confirm_app_profile" ? "confirm the app's name and description" : step === "confirm_app_audience" ? "confirm who may open it" : step === "provide_secrets" ? "provide the secrets it asked for" : said(step)) : [];
     if (openSteps.length)
         lines.push(`Still needed: ${openSteps.join("; ")}${envelope.result.setup?.plainEnglish && !setup?.profile ? ` — run \`harbour setup --operation ${envelope.operationRef ?? "<reference>"}\`` : ""}`);
     else if (setup?.profile)

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.24";
+export const CLI_VERSION = "0.1.25";

package/package.json

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