@fourier-labs/harbour 0.1.12 → 0.1.13

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

@@ -78,18 +78,33 @@ export async function login(mcpUrl, tenant, output) {
         callback.close();
     }
 }
-export async function refreshStoredToken(mcpUrl, tenant, path = tokenStorePath()) {
+/** Refresh only when the access token is within this margin of expiry. */
+const REFRESH_MARGIN_MS = 5 * 60_000;
+/**
+ * Returns a usable access token, refreshing only when the stored one is about
+ * to expire. Refresh tokens are single-use, so every CLI process refreshing on
+ * start meant two processes at once (a `productionise` still polling and a
+ * `status` beside it) spent the same refresh token and one was told to sign in
+ * again. A refresh that fails now re-reads the store once: if a sibling
+ * process rotated the pair in the meantime, its newer token is used instead.
+ */
+export async function refreshStoredToken(mcpUrl, tenant, path = tokenStorePath(), now = Date.now) {
     const stored = await loadStoredToken(mcpUrl, tenant, path);
     if (!stored)
         return undefined;
     if (!stored.refreshToken)
         return stored.accessToken;
+    if (stored.accessTokenExpiresAt !== undefined && stored.accessTokenExpiresAt - REFRESH_MARGIN_MS > now())
+        return stored.accessToken;
     try {
         const refreshed = await token(stored.tokenEndpoint, { grant_type: "refresh_token", client_id: stored.clientId, refresh_token: stored.refreshToken });
         await saveStoredToken(mcpUrl, tenant, { ...stored, ...refreshed, refreshToken: refreshed.refreshToken ?? stored.refreshToken }, path);
         return refreshed.accessToken;
     }
     catch {
+        const rotated = await loadStoredToken(mcpUrl, tenant, path);
+        if (rotated && rotated.refreshToken !== stored.refreshToken && (rotated.accessTokenExpiresAt === undefined || rotated.accessTokenExpiresAt - REFRESH_MARGIN_MS > now()))
+            return rotated.accessToken;
         throw new Error("Harbour sign-in expired or was revoked. Run `harbour login` again.");
     }
 }
@@ -119,7 +134,7 @@ async function token(endpoint, values) {
     const response = await json(endpoint, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams(values), redirect: "error" });
     if (!response.access_token)
         throw new Error("Harbour sign-in did not return an access token.");
-    return { accessToken: response.access_token, ...(response.refresh_token ? { refreshToken: response.refresh_token } : {}) };
+    return { accessToken: response.access_token, ...(response.refresh_token ? { refreshToken: response.refresh_token } : {}), ...(typeof response.expires_in === "number" && response.expires_in > 0 ? { accessTokenExpiresAt: Date.now() + response.expires_in * 1_000 } : {}) };
 }
 async function json(url, init) { const response = await fetch(url, { ...init, redirect: "error" }); if (!response.ok)
     throw new Error(`Harbour sign-in request failed (${response.status}).`); return response.json(); }

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

@@ -1,15 +1,26 @@
 #!/usr/bin/env node
 import { RemoteMcpClient } from "./remote-mcp-client.js";
 import { productionise } from "./productionise.js";
-import { safeError, CliError } from "./output.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 { CLI_VERSION } from "./version.js";
 import { login, logout, refreshStoredToken } from "./auth.js";
 import { connect, loadConfig, resolveConfig } from "./config.js";
 const args = process.argv.slice(2);
 const command = args[0];
 const connectUrl = args[1];
-const rootIndex = args.indexOf("--app-root");
-const root = rootIndex >= 0 ? args[rootIndex + 1] : undefined;
+const root = optionValue("--app-root");
+const operationRef = optionValue("--operation");
+const json = args.includes("--json");
+const noWait = args.includes("--no-wait");
+const secretName = optionValue("--name");
+const profileName = optionValue("--name");
+const profileDescription = optionValue("--description");
+const audienceEmails = optionValue("--emails");
+const personal = args.includes("--personal");
+const valueStdin = args.includes("--value-stdin");
+const subcommand = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
+const wait = args.includes("--wait");
 const includePaths = [];
 let optionError;
 for (let index = 0; index < args.length; index += 1) {
@@ -24,14 +35,38 @@ for (let index = 0; index < args.length; index += 1) {
     }
 }
 const explicitToken = process.env.HARBOUR_TOKEN?.trim() ?? "";
-const usage = "Usage: harbour connect <company-start-url> | login | logout | productionise --app-root <path> [--include <relative-path>]... [--json]\nRun `harbour connect <company-start-url>` once, then sign in when Harbour asks.\n";
+const usage = [
+    "Usage:",
+    "  harbour connect <company-start-url>",
+    "  harbour login | logout",
+    "  harbour productionise --app-root <path> [--include <relative-path>]... [--no-wait] [--json]",
+    "  harbour status --operation <reference> [--wait] [--json]",
+    "  harbour retry --operation <reference> [--no-wait] [--json]",
+    "  harbour promote --operation <reference> [--no-wait] [--json]",
+    "  harbour setup --operation <reference> [--json]            what the app still needs (name, audience, secrets)",
+    "  harbour profile --operation <reference> [--name <text>] [--description <text>] [--json]",
+    "  harbour audience --operation <reference> [--emails a@co,b@co] [--json]   (no --emails = only you)",
+    "  harbour secrets list --operation <reference> [--json]",
+    "  harbour secrets set --operation <reference> --name <NAME> [--personal] [--value-stdin]",
+    "  harbour secrets dismiss --operation <reference> --name <NAME>",
+    "Run `harbour connect <company-start-url>` once, then sign in when Harbour asks.",
+    "productionise saves the app, follows its deployment, and prints the protected preview link; promote sends a tested preview to production.",
+    "secrets set reads the value from your terminal with echo off (or from stdin with --value-stdin); it is never printed or passed to any other program.",
+    ""
+].join("\n");
+const OPERATION_COMMANDS = ["status", "retry", "promote", "setup", "profile", "audience", "secrets"];
+const progress = (message) => { process.stderr.write(`${message}\n`); };
 if (command === "--version" || command === "version") {
     process.stdout.write(`${CLI_VERSION}\n`);
 }
 else if (!command || command === "help" || command === "--help" || args.includes("-h")) {
     process.stdout.write(usage);
 }
-else if (!["connect", "login", "logout", "productionise"].includes(command) || (command === "connect" && (!connectUrl || connectUrl.startsWith("--"))) || (command === "productionise" && (optionError || !root || root.startsWith("--")))) {
+else if (!["connect", "login", "logout", "productionise", ...OPERATION_COMMANDS].includes(command)
+    || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
+    || (command === "productionise" && (optionError || !root))
+    || (OPERATION_COMMANDS.includes(command) && !operationRef)
+    || (command === "secrets" && (!subcommand || !["list", "set", "dismiss"].includes(subcommand) || (subcommand !== "list" && !secretName)))) {
     if (optionError)
         process.stderr.write(`${optionError}\n`);
     process.stderr.write(usage);
@@ -51,7 +86,7 @@ else {
             const url = config.mcpUrl;
             const tenant = config.tenantId;
             if (command === "login") {
-                await login(url, tenant, message => process.stderr.write(`${message}\n`));
+                await login(url, tenant, progress);
                 process.stdout.write("Harbour sign-in complete.\n");
                 process.exitCode = 0;
             }
@@ -65,9 +100,34 @@ else {
                 if (!token)
                     throw new CliError("AUTH_REQUIRED", "Please sign in to Harbour with `harbour login`.");
                 const client = new RemoteMcpClient(url, token, tenant);
-                const result = await productionise(root, client, message => { process.stderr.write(`${message}\n`); }, tenant, includePaths);
-                const envelope = { schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: true, operationRef: result.operationRef, result: result.result };
-                process.stdout.write(`${JSON.stringify(envelope)}\n`);
+                let envelope;
+                if (command === "productionise") {
+                    const result = await productionise(root, client, progress, tenant, includePaths, { waitForDeployment: !noWait });
+                    envelope = { schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: true, operationRef: result.operationRef, result: result.result };
+                }
+                else {
+                    let summary;
+                    if (command === "status")
+                        summary = wait ? outcomeFor(await waitForSettled(client, operationRef, progress), operationRef).summary : summarize(await fetchStatus(client, operationRef));
+                    else if (command === "retry")
+                        summary = await retryDeployment(client, operationRef, progress, { wait: !noWait });
+                    else if (command === "promote")
+                        summary = await promoteToProduction(client, operationRef, progress, { wait: !noWait });
+                    else if (command === "setup")
+                        summary = { setup: await getAppSetup(client, operationRef) };
+                    else if (command === "profile")
+                        summary = { setup: await confirmProfile(client, operationRef, { ...(profileName ? { displayName: profileName } : {}), ...(profileDescription ? { description: profileDescription } : {}) }, progress) };
+                    else if (command === "audience")
+                        summary = { setup: await confirmAudience(client, operationRef, audienceEmails ? audienceEmails.split(",").map(value => value.trim()).filter(Boolean) : [], progress) };
+                    else if (subcommand === "list")
+                        summary = { secrets: await listSecrets(client, operationRef) };
+                    else if (subcommand === "set")
+                        summary = await setSecret(client, operationRef, { name: secretName, ...(personal ? { personal: true } : {}), readValue: valueStdin ? readSecretFromStdin : () => readSecretFromTerminal(`Value for ${secretName} (not shown): `) }, progress);
+                    else
+                        summary = await dismissSecret(client, operationRef, secretName, progress);
+                    envelope = { schema: "harbour.cli-result/1.0", cliVersion: CLI_VERSION, status: "SUCCEEDED", operationStarted: true, operationRef: operationRef, result: summary };
+                }
+                process.stdout.write(json ? `${JSON.stringify(envelope)}\n` : renderSummary(envelope));
             }
         }
     }
@@ -75,7 +135,13 @@ else {
         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 };
-        process.stdout.write(`${JSON.stringify(envelope)}\n`);
+        if (json || command === "productionise")
+            process.stdout.write(`${JSON.stringify(envelope)}\n`);
         process.exitCode = 1;
     }
 }
+function optionValue(flag) {
+    const index = args.indexOf(flag);
+    const value = index >= 0 ? args[index + 1] : undefined;
+    return value && !value.startsWith("--") ? value : undefined;
+}

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

@@ -0,0 +1,269 @@
+import { structured } from "./remote-mcp-client.js";
+import { CliError } from "./output.js";
+const DEPLOYMENT_TERMINAL = new Set(["LIVE", "FAILED", "STALE", "RETRYABLE_FAILURE"]);
+const PRODUCTION_TERMINAL = new Set(["LIVE", "FAILED", "MANUAL_RECOVERY"]);
+export function summarize(status) {
+    return {
+        ...(status.operation?.stage ? { stage: status.operation.stage } : {}),
+        ...(status.sourceSave?.status ? { sourceSave: { status: status.sourceSave.status } } : {}),
+        ...(status.deployment ? { deployment: pickDeployment(status.deployment) } : {}),
+        ...(status.production ? { production: pickProduction(status.production) } : {}),
+        ...(status.waiting ? { waiting: { stage: status.waiting.stage, plainEnglish: status.waiting.plainEnglish } } : {}),
+        ...(status.nextAction?.plainEnglish ? { nextStep: status.nextAction.plainEnglish } : {}),
+        ...(status.nextTool ? { nextTool: status.nextTool } : {})
+    };
+}
+function pickDeployment(value) {
+    return {
+        state: value.state,
+        ...(value.status ? { status: value.status } : {}),
+        ...(value.message ? { message: value.message } : {}),
+        ...(value.protectedUrl ? { protectedUrl: value.protectedUrl } : {}),
+        ...(value.versionId ? { versionId: value.versionId } : {}),
+        ...(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 } : {}) } } : {})
+    };
+}
+function pickProduction(value) {
+    return {
+        state: value.state,
+        ...(value.status ? { status: value.status } : {}),
+        ...(value.message ? { message: value.message } : {}),
+        ...(value.productionUrl ? { productionUrl: value.productionUrl } : {}),
+        ...(value.previewVersionId ? { previewVersionId: value.previewVersionId } : {}),
+        ...(value.failure?.message ? { failure: { message: value.failure.message } } : {})
+    };
+}
+export async function fetchStatus(client, operationRef, waitSeconds = 0) {
+    await client.initialize();
+    return structured(await client.call("harbour_get_operation_status", { operationId: operationRef, waitSeconds }));
+}
+/** True when nothing more will change without a person acting. */
+export function isSettled(status) {
+    if (status.waiting)
+        return true;
+    if (status.production)
+        return PRODUCTION_TERMINAL.has(status.production.state);
+    if (status.deployment)
+        return DEPLOYMENT_TERMINAL.has(status.deployment.state);
+    return false;
+}
+/**
+ * Follow the operation until the preview deployment (or an in-flight production
+ * promotion) settles. Harbour long-polls up to 15 s per call and returns early
+ * on change, so the loop is bounded by wall clock rather than by call count.
+ * `noDeploymentGraceMs` covers the gap between the source save succeeding and
+ * the deployment attempt being recorded; past it, a saved operation with no
+ * deployment is reported as such instead of waited on forever.
+ */
+export async function waitForSettled(client, operationRef, output, options = {}) {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const maxWaitMs = options.maxWaitMs ?? 30 * 60_000;
+    const graceMs = options.noDeploymentGraceMs ?? 90_000;
+    const startedAt = now();
+    let lastLine = "";
+    let consecutiveFailures = 0;
+    while (true) {
+        const callStarted = now();
+        let status;
+        try {
+            status = await fetchStatus(client, operationRef, 15);
+            consecutiveFailures = 0;
+        }
+        catch (error) {
+            // A deployment takes minutes and one status call out of dozens can fail
+            // transiently (gateway timeout, dropped connection). The operation is
+            // unaffected by our polling, so keep watching; give up only after a run
+            // of failures, and say what the last one was instead of a generic error.
+            consecutiveFailures += 1;
+            if (consecutiveFailures >= 5)
+                throw new CliError("DEPLOYMENT_STATUS_UNAVAILABLE", `Harbour stopped answering status checks (${safeMessage(error)}). The deployment may still be running; check again with \`harbour status\`.`, operationRef);
+            output("Harbour did not answer that status check; trying again.");
+            await sleep(Math.min(15_000, 3_000 * consecutiveFailures));
+            continue;
+        }
+        if (isSettled(status))
+            return status;
+        if (!status.deployment && !status.production) {
+            if (now() - startedAt > graceMs)
+                return status;
+        }
+        const line = progressLine(status);
+        if (line && line !== lastLine) {
+            output(line);
+            lastLine = line;
+        }
+        if (now() - startedAt > maxWaitMs)
+            throw new CliError("DEPLOYMENT_TIMEOUT", "Harbour is still deploying the app. Check again later with `harbour status`.", operationRef);
+        // Harbour returns immediately when nothing is in flight yet; do not spin.
+        const elapsed = now() - callStarted;
+        if (elapsed < 3_000)
+            await sleep(3_000 - elapsed);
+    }
+}
+function safeMessage(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").replace(/\s+/g, " ").trim().slice(0, 160) || "no details";
+}
+function progressLine(status) {
+    if (status.production)
+        return `Harbour is promoting the app to production${status.production.message ? ` (${status.production.message})` : ""}.`;
+    if (status.deployment)
+        return `Harbour is deploying the app${status.deployment.message ? ` (${status.deployment.message})` : ""}.`;
+    return "Harbour saved the app and is preparing the deployment.";
+}
+/** The exit-relevant outcome of a settled status: success, a failure, or a step the maker must take. */
+export function outcomeFor(status, operationRef) {
+    const summary = summarize(status);
+    if (status.production?.state === "LIVE")
+        return { kind: "production_live", summary };
+    if (status.production && PRODUCTION_TERMINAL.has(status.production.state))
+        throw new CliError("PRODUCTION_PROMOTION_FAILED", status.production.failure?.message ?? status.production.message ?? "Harbour could not complete the production promotion.", operationRef);
+    if (status.waiting)
+        return { kind: "waiting", summary };
+    if (status.deployment?.state === "LIVE")
+        return { kind: "live", summary };
+    if (status.deployment && DEPLOYMENT_TERMINAL.has(status.deployment.state)) {
+        const retryable = status.deployment.failure?.retryable === true;
+        throw new CliError(retryable ? "DEPLOYMENT_RETRYABLE_FAILURE" : "DEPLOYMENT_FAILED", `${status.deployment.failure?.message ?? status.deployment.message ?? "Harbour could not complete the deployment."}${retryable ? " Run `harbour retry` to start it again." : ""}`, operationRef);
+    }
+    return { kind: "no_deployment", summary: { ...summary, nextStep: summary.nextStep ?? "Harbour saved the app but has not started a deployment for this company yet. Ask your Harbour administrator to connect deployment." } };
+}
+export async function retryDeployment(client, operationRef, output, options = {}) {
+    await client.initialize();
+    const result = structured(await client.call("harbour_retry_deployment", { operationId: operationRef }));
+    output(result.retry?.replayed ? "Harbour had already accepted this retry." : "Harbour accepted the deployment retry.");
+    if (options.wait === false)
+        return summarize(await fetchStatus(client, operationRef));
+    return outcomeFor(await waitForSettled(client, operationRef, output), operationRef).summary;
+}
+/**
+ * Promotion mirrors the console's "I tested this version" button: the maker
+ * must have opened the live preview and say so, and the version they tested
+ * is pinned so a redeployed preview is refused as stale rather than promoted
+ * unseen.
+ */
+export async function promoteToProduction(client, operationRef, output, options = {}) {
+    const status = await fetchStatus(client, operationRef);
+    if (status.production && !PRODUCTION_TERMINAL.has(status.production.state)) {
+        output("Harbour is already promoting this app to production.");
+        return options.wait === false ? summarize(status) : outcomeFor(await waitForSettled(client, operationRef, output), operationRef).summary;
+    }
+    const deployment = status.deployment;
+    if (deployment?.state !== "LIVE" || !deployment.versionId || !deployment.protectedUrl)
+        throw new CliError("LIVE_PREVIEW_REQUIRED", "The preview must be live before it can be promoted. Check `harbour status` first.", operationRef);
+    output(`Open the protected preview and test it: ${deployment.protectedUrl}`);
+    output("When it works as expected, type Tested. then press Enter to promote it to production.");
+    const reply = await (options.readConfirmation ?? readLine)();
+    if (reply !== "Tested.")
+        throw new CliError("PROMOTION_NOT_CONFIRMED", "The production promotion was not confirmed.", operationRef);
+    const result = structured(await client.call("harbour_promote_to_production", {
+        operationId: operationRef,
+        expectedPreviewVersionId: deployment.versionId,
+        confirmation: { schema: "harbour.stage-approval/1.0", step: "confirm_preview_tested_and_promote", approved: true, approvedByUser: true, userApprovalText: reply }
+    }));
+    output("Harbour accepted the production promotion.");
+    if (options.wait === false)
+        return { ...summarize(status), ...(result.production ? { production: pickProduction(result.production) } : {}) };
+    return outcomeFor(await waitForSettled(client, operationRef, output), operationRef).summary;
+}
+export async function readLine() {
+    if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(Buffer.from(chunk));
+        return Buffer.concat(chunks).toString("utf8").trim();
+    }
+    return new Promise(resolve => { process.stdin.setEncoding("utf8"); process.stdin.once("data", value => resolve(String(value).trim())); });
+}
+export async function getAppSetup(client, operationRef) {
+    await client.initialize();
+    return structured(await client.call("harbour_get_app_setup", { operationId: operationRef }));
+}
+export async function confirmProfile(client, operationRef, input, output) {
+    const setup = await getAppSetup(client, operationRef);
+    const displayName = input.displayName ?? setup.profile?.suggested?.displayName ?? setup.profile?.displayName;
+    const description = input.description ?? setup.profile?.suggested?.description ?? setup.profile?.description;
+    if (!displayName || !description)
+        throw new CliError("PROFILE_INCOMPLETE", "Give the app a name (--name) and a description (--description); Harbour had no suggestion to fall back on.", operationRef);
+    if (!setup.profile?.profileVersion)
+        throw new CliError("PROFILE_VERSION_MISSING", "Harbour did not return the app details version.", operationRef);
+    await client.call("harbour_confirm_app_profile", { operationId: operationRef, displayName, description, expectedVersion: setup.profile.profileVersion });
+    output(`Harbour recorded the app's name and description: ${displayName}.`);
+    return getAppSetup(client, operationRef);
+}
+export async function confirmAudience(client, operationRef, emails, output) {
+    await client.initialize();
+    await client.call("harbour_confirm_app_audience", { operationId: operationRef, emails });
+    output(emails.length ? `Harbour recorded the app's audience: ${emails.length} colleague${emails.length === 1 ? "" : "s"}.` : "Harbour recorded that only you can open the app for now.");
+    return getAppSetup(client, operationRef);
+}
+export async function listSecrets(client, operationRef) {
+    return (await getAppSetup(client, operationRef)).secrets;
+}
+/**
+ * The value is read by the CLI itself — from the terminal with echo off, or
+ * from stdin when the caller pipes it — and sent straight to Harbour. It is
+ * never printed, never placed in the result, and never seen by an AI tool that
+ * merely launched this command.
+ */
+export async function setSecret(client, operationRef, input, output) {
+    await client.initialize();
+    const value = (await input.readValue()).replace(/\r?\n$/, "");
+    if (!value)
+        throw new CliError("SECRET_VALUE_REQUIRED", "No value was entered.", operationRef);
+    const result = structured(await client.call("harbour_set_app_secret", { operationId: operationRef, name: input.name, value, scope: input.personal ? "personal" : "app", ...(input.personal ? { acknowledgePersonal: true } : {}) }));
+    output(`Harbour stored the value for ${input.name}.${result.resumedOperationIds?.length ? " The paused deployment is resuming." : ""}`);
+    return { ...(result.secret ? { secret: result.secret } : {}), resumedOperationIds: result.resumedOperationIds ?? [] };
+}
+export async function dismissSecret(client, operationRef, name, output) {
+    await client.initialize();
+    const result = structured(await client.call("harbour_dismiss_app_secret", { operationId: operationRef, name }));
+    output(`Harbour recorded that ${name} is not needed.`);
+    return { ...(result.secret ? { secret: result.secret } : {}), resumedOperationIds: result.resumedOperationIds ?? [] };
+}
+/** Read one line from the controlling terminal with echo off, so the value
+ * never lands in shell history, scrollback, or a parent process's capture. */
+export async function readSecretFromTerminal(prompt) {
+    const { openSync, readSync, closeSync } = await import("node:fs");
+    let fd;
+    try {
+        fd = openSync("/dev/tty", "r+");
+    }
+    catch {
+        throw new CliError("NO_TERMINAL", "No terminal is available to enter the value. Pipe it on stdin with --value-stdin instead.");
+    }
+    const { writeSync } = await import("node:fs");
+    writeSync(fd, prompt);
+    const stty = await import("node:child_process");
+    try {
+        stty.execSync("stty -echo", { stdio: ["inherit", "ignore", "ignore"] });
+    }
+    catch { /* best effort: some terminals cannot toggle echo */ }
+    const chunks = [];
+    const buffer = Buffer.alloc(1);
+    try {
+        while (true) {
+            const read = readSync(fd, buffer, 0, 1, null);
+            if (read === 0 || buffer[0] === 0x0a)
+                break;
+            if (buffer[0] !== 0x0d)
+                chunks.push(Buffer.from(buffer));
+        }
+    }
+    finally {
+        try {
+            stty.execSync("stty echo", { stdio: ["inherit", "ignore", "ignore"] });
+        }
+        catch { /* ignore */ }
+        writeSync(fd, "\n");
+        closeSync(fd);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function readSecretFromStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}

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

@@ -4,6 +4,57 @@ export function safeError(error) {
     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." };
 }
+/** Human-readable stdout for runs without `--json`: the operation reference and
+ * whatever link or next step Harbour reported, nothing internal. */
+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})` : ""}`);
+    if (result.production) {
+        lines.push(`Production: ${result.production.state}${result.production.productionUrl ? ` — ${result.production.productionUrl}` : ""}`);
+        if (result.production.failure?.message)
+            lines.push(`  ${result.production.failure.message}`);
+    }
+    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}` : ""}`);
+    }
+    if (result.waiting?.plainEnglish)
+        lines.push(`Action needed: ${result.waiting.plainEnglish}`);
+    else if (result.nextStep)
+        lines.push(`Next: ${result.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)"}`);
+        if (setup.profile?.description || setup.profile?.suggested?.description)
+            lines.push(`Description: ${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"}`);
+        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"}`);
+        else if (!secrets.asks?.length)
+            lines.push("Secrets: none asked for");
+        else
+            for (const ask of secrets.asks)
+                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) : [];
+    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)
+        lines.push("Setup complete.");
+    return `${lines.join("\n")}\n`;
+}
 export class CliError extends Error {
     code;
     operationRef;

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

@@ -6,8 +6,10 @@ 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 { CLI_VERSION } from "./version.js";
-export async function productionise(rootArg, client, output, tenantId, includePaths = []) {
+import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
+export async function productionise(rootArg, client, output, tenantId, includePaths = [], options = {}) {
     const root = resolve(rootArg);
     output(`Harbour is checking ${basename(root)}.`);
     if (root === parse(root).root || root === resolve(homedir()))
@@ -71,7 +73,37 @@ export async function productionise(rootArg, client, output, tenantId, includePa
         const evidence = await waitForSave(client, operationRef, graph, execution, output);
         const report = structured(await client.call("harbour_build_verification_report", { operationId: operationRef, appId, surface: "codex", graph, sourceControlEvidence: evidence.sourceControlEvidence, runnerEvidence: evidence.runnerEvidence }));
         output("Harbour verified the saved app.");
-        return { cliVersion: CLI_VERSION, operationRef, result: safeVerificationResult(report, evidence) };
+        const verification = safeVerificationResult(report, evidence);
+        if (options.waitForDeployment === false)
+            return { cliVersion: CLI_VERSION, operationRef, result: verification };
+        // The saved app is not the finished product. The same source save that the
+        // console follows to "live" starts a preview deployment; follow it here so
+        // the maker gets the app's real protected link, not the example one.
+        // Past this point the app is saved and verified; a failure here is about
+        // following the deployment, not about the save, and must say so.
+        let settled;
+        try {
+            settled = await waitForSettled(client, operationRef, output, options.waitOptions);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            throw new CliError("DEPLOYMENT_STATUS_UNAVAILABLE", `Harbour saved and verified the app but could not follow its deployment (${error instanceof Error ? error.message.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").slice(0, 160) : "unknown error"}). Check again with \`harbour status\`.`, operationRef);
+        }
+        const outcome = outcomeFor(settled, operationRef);
+        output(outcomeLine(outcome));
+        // The console asks for the app's name, audience and secrets before it
+        // offers promotion; say what is still open so a CLI-only builder knows.
+        let setup;
+        try {
+            setup = await getAppSetup(client, operationRef);
+        }
+        catch {
+            setup = undefined;
+        }
+        if (setup?.pending?.length)
+            output(`${setup.nextAction?.plainEnglish ?? "The app still needs setup."} Run \`harbour setup --operation ${operationRef}\`.`);
+        return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...outcome.summary, outcome: outcome.kind, ...(setup ? { setup: { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}) } } : {}) } };
     }
     catch (error) {
         if (error instanceof CliError || (error && typeof error === "object" && "code" in error))
@@ -123,11 +155,6 @@ function boundedWait(value) {
 function matchesTool(actual, expected) {
     return actual.replaceAll(".", "_") === expected;
 }
-function isProhibitedSecretPath(path) {
-    if (/(^|\/)\.env\.example$/i.test(path))
-        return false;
-    return /(^|\/)(?:\.env(?:\.[^/]+)?|\.npmrc|id_rsa|[^/]+\.(?:pem|key))$/i.test(path);
-}
 function safeVerificationResult(value, statusEvidence) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return { verification: "completed" };
@@ -151,9 +178,12 @@ function safeVerificationResult(value, statusEvidence) {
             : {})
     };
 }
-async function readApproval() { if (!process.stdin.isTTY) {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(Buffer.from(chunk));
-    return Buffer.concat(chunks).toString("utf8").trim();
-} return new Promise(resolve => { process.stdin.setEncoding("utf8"); process.stdin.once("data", value => resolve(String(value).trim())); }); }
+function outcomeLine(outcome) {
+    switch (outcome.kind) {
+        case "live": return `Harbour deployed the app. Protected preview: ${outcome.summary.deployment?.protectedUrl ?? ""}`.trim();
+        case "production_live": return `The app is live in production: ${outcome.summary.production?.productionUrl ?? ""}`.trim();
+        case "waiting": return outcome.summary.waiting?.plainEnglish ?? "Harbour needs one more step in the Harbour console before it can deploy.";
+        case "no_deployment": return outcome.summary.nextStep ?? "Harbour saved the app; deployment has not started.";
+    }
+}
+const readApproval = readLine;

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

@@ -2,7 +2,7 @@ import { readFile, lstat } from "node:fs/promises";
 import { relative, resolve, sep } from "node:path";
 import { deflateRawSync } from "node:zlib";
 import { sha256Bytes } from "../../../src/digest.js";
-const SECRET = /(^|\/)(?:(?!\.env\.example$)\.env(?:\.[^/]+)?|\.npmrc|id_rsa|[^/]+\.(?:pem|key))$/i;
+import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
 export async function archiveForManifest(root, manifest) {
     const rootAbsolute = resolve(root);
     if ((await lstat(rootAbsolute)).isSymbolicLink())
@@ -10,7 +10,7 @@ export async function archiveForManifest(root, manifest) {
     const files = [];
     const seen = new Set();
     for (const entry of manifest.files) {
-        if (seen.has(entry.path) || SECRET.test(entry.path) || entry.path.includes("\\") || entry.path.startsWith("/"))
+        if (seen.has(entry.path) || isProhibitedSecretPath(entry.path) || entry.path.includes("\\") || entry.path.startsWith("/"))
             throw new Error("Harbour rejected an unsafe source path.");
         seen.add(entry.path);
         const absolute = resolve(rootAbsolute, entry.path);

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.12";
+export const CLI_VERSION = "0.1.13";

package/dist/src/analyzer.js

@@ -4,6 +4,7 @@ import { existsSync } from "node:fs";
 import { lstat, readFile, readdir, stat } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { sha256 } from "./digest.js";
+import { isEnvExamplePath, isSourceIntakeExcludedPath } from "./secret-paths.js";
 const ANALYZER_VERSION = "0.1.0";
 const MAX_FILES = 600;
 const MAX_FILE_BYTES = 256_000;
@@ -12,7 +13,7 @@ const MAX_FILE_BYTES = 256_000;
 // previous save has written a receipt into the selected workspace.
 const IGNORED_DIRS = new Set([".git", ".harbour", ".next", ".nuxt", ".svelte-kit", ".turbo", "coverage", "dist", "build", "node_modules", "vendor"]);
 const SECRET_FILE_NAMES = new Set([".env", ".env.local", ".env.production", ".env.development", ".npmrc"]);
-const TEXT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".json", ".html", ".css", ".py", ".rb", ".go", ".rs", ".java", ".cs", ".php", ".md", ".toml", ".yaml", ".yml"]);
+const TEXT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".json", ".html", ".css", ".py", ".rb", ".go", ".rs", ".java", ".cs", ".php", ".md", ".toml", ".yaml", ".yml", ".sh"]);
 function normalizeIncludePath(value) {
     if (!value || value === ".")
         return "";
@@ -66,6 +67,11 @@ async function collectFiles(root, current, output, unknowns) {
             unknowns.push(`file limit reached at ${MAX_FILES} files`);
             return;
         }
+        // A linked worktree represents .git as a small pointer file rather than a
+        // directory. It is Git metadata and must stay outside the app boundary in
+        // both checkout layouts.
+        if (entry.name === ".git")
+            continue;
         if (entry.isDirectory()) {
             if (!IGNORED_DIRS.has(entry.name))
                 await collectFiles(root, join(current, entry.name), output, unknowns);
@@ -85,8 +91,10 @@ async function collectFile(root, absolute, output) {
         throw new Error("ANALYZER_FILE_UNSAFE: selected app file changed or is not a regular file.");
     const name = basename(absolute);
     const fact = { path, basename: name, size: info.size };
-    const safeEnvExample = name === ".env.example" || name.endsWith(".env.example");
-    if (!SECRET_FILE_NAMES.has(name) && info.size <= MAX_FILE_BYTES && (TEXT_EXTENSIONS.has(extension(name)) || safeEnvExample)) {
+    // Env templates and extensionless shell-context files (Dockerfile, Procfile)
+    // carry env-name evidence; without content they can never produce an ask.
+    const safeExtensionless = isEnvTemplateFile(name) || isShellContextFile(name);
+    if (!SECRET_FILE_NAMES.has(name) && info.size <= MAX_FILE_BYTES && (TEXT_EXTENSIONS.has(extension(name)) || safeExtensionless)) {
         fact.content = await readFile(absolute, "utf8");
     }
     output.push(fact);
@@ -183,14 +191,66 @@ function detectCapabilities(files, dependencies) {
     }
     return capabilities;
 }
+/** Env-access idioms recognized in any retained text file. Names only —
+ * capture groups never span a value. */
+const ENV_ACCESS_PATTERNS = [
+    // JS/TS dot access and Deno (original rule).
+    /(?:process\.env\.|import\.meta\.env\.|Deno\.env\.get\(["'])([A-Z0-9_]{3,})/g,
+    // JS/TS bracket access.
+    /(?:process\.env|import\.meta\.env)\[["']([A-Z0-9_]{3,})["']\]/g,
+    // Python: os.environ["X"], os.environ.get("X").
+    /\bos\.environ(?:\.get\(\s*|\[)["']([A-Z0-9_]{3,})["']/g,
+    // Go: os.Getenv("X"), os.LookupEnv("X").
+    /\bos\.(?:Getenv|LookupEnv)\(\s*"([A-Z0-9_]{3,})"/g,
+    // Ruby: ENV["X"], ENV.fetch("X").
+    /\bENV(?:\.fetch\(\s*|\[)["']([A-Z0-9_]{3,})["']/g,
+    // Java System.getenv, PHP/C getenv, Python os.getenv — all end in getenv(.
+    /\bgetenv\(\s*["']([A-Z0-9_]{3,})["']/g
+];
+/** Shell parameter expansion: ${X}, ${X:-default}, bare $X. Only applied to
+ * shell-context content (see isShellContextFile) — `${X}` in prose or make
+ * syntax must never become a builder ask. */
+const SHELL_EXPANSION_PATTERN = /\$(?:\{([A-Z0-9_]{3,})(?::?[-=+?][^}]*)?\}|([A-Z0-9_]{3,})\b)/g;
+function isEnvTemplateFile(basename) {
+    return isEnvExamplePath(basename);
+}
+/** Files whose content is shell-like end to end. Markdown and source files are
+ * deliberately absent; Makefiles too (`${X}` there is make-variable syntax). */
+function isShellContextFile(basename) {
+    if (basename === "Dockerfile" || basename.startsWith("Dockerfile."))
+        return true;
+    if (basename === "Procfile")
+        return true;
+    if (basename.endsWith(".sh"))
+        return true;
+    return /^(?:docker-)?compose[^/]*\.ya?ml$/.test(basename);
+}
+function pushMatches(content, pattern, names) {
+    for (const match of content.matchAll(pattern)) {
+        names.push(match[1] ?? match[2] ?? "");
+    }
+}
 function detectEnvNames(files) {
     const names = [];
     for (const file of files) {
         const content = file.content ?? "";
-        for (const match of content.matchAll(/(?:process\.env\.|import\.meta\.env\.|Deno\.env\.get\(["'])([A-Z0-9_]{3,})/g)) {
-            names.push(match[1] ?? "");
+        for (const pattern of ENV_ACCESS_PATTERNS)
+            pushMatches(content, pattern, names);
+        if (isShellContextFile(file.basename))
+            pushMatches(content, SHELL_EXPANSION_PATTERN, names);
+        // package.json scripts run in a shell; expansion applies to the script
+        // strings alone, never to the raw JSON (dependency names, config values).
+        if (file.basename === "package.json") {
+            try {
+                const scripts = JSON.parse(content).scripts ?? {};
+                for (const value of Object.values(scripts)) {
+                    if (typeof value === "string")
+                        pushMatches(value, SHELL_EXPANSION_PATTERN, names);
+                }
+            }
+            catch { /* Invalid manifests contribute no names. */ }
         }
-        if (file.basename === ".env.example" || file.basename.endsWith(".env.example")) {
+        if (isEnvTemplateFile(file.basename)) {
             for (const line of content.split(/\r?\n/)) {
                 const envMatch = /^([A-Z0-9_]{3,})=/.exec(line.trim());
                 if (envMatch)
@@ -349,13 +409,24 @@ const JDBC_SCHEME_DRIVERS = {
     bigquery: "bigquery",
     databricks: "databricks"
 };
+/**
+ * Drivers whose service endpoint is a single fixed global host. Only a driver
+ * that can never point anywhere else belongs here: a BigQuery client names no
+ * host in code or config, so without this its dependency would carry no host
+ * at all, and a hostless dependency is dropped before it ever reaches the
+ * registry — the source could never be matched and the app would deploy with
+ * no grant and no credential.
+ */
+const WELL_KNOWN_DRIVER_HOSTS = {
+    bigquery: "bigquery.googleapis.com"
+};
+const DRIVER_BY_WELL_KNOWN_HOST = Object.fromEntries(Object.entries(WELL_KNOWN_DRIVER_HOSTS).map(([driver, host]) => [host, driver]));
 const CONNECTION_STRING_PATTERN = /\b(postgres(?:ql)?|mysql|mongodb(?:\+srv)?|rediss?):\/\/([^\s"'`<>\\]+)/gi;
 const JDBC_PATTERN = /\bjdbc:([a-z0-9]+):\/\/([^\s"'`<>\\]+)/gi;
 const HTTP_URL_PATTERN = /\bhttps?:\/\/([a-z0-9][a-z0-9.-]*\.[a-z]{2,})(?::\d+)?(?=[/"'`\s?#),;]|$)/gi;
 const BARE_HOSTNAME_PATTERN = /^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}(?::\d+)?$/i;
 function isEnvExampleFile(path) {
-    const name = path.split("/").pop() ?? path;
-    return name === ".env.example" || name.endsWith(".env.example") || name === ".env.sample" || name === ".env.template";
+    return isEnvExamplePath(path);
 }
 /** Extract the hostname from a connection-string authority, discarding any
  * credentials, port, path, or query. Never returns secret material. */
@@ -460,6 +531,15 @@ export function extractDataDependencies(files, declared) {
         let driver = detected.driver;
         if (!driver && drivers.has("supabase") && /\.supabase\.(?:co|in)$/i.test(detected.host))
             driver = "supabase";
+        // A well-known service host counts as that driver's host once the client
+        // library is a declared dependency, so the env names sitting beside it
+        // (the credential, the project) ride along as database identifiers rather
+        // than being filed as an unrelated API endpoint.
+        if (!driver) {
+            const wellKnown = DRIVER_BY_WELL_KNOWN_HOST[detected.host.toLowerCase()];
+            if (wellKnown && drivers.has(wellKnown))
+                driver = wellKnown;
+        }
         if (driver) {
             const group = databaseByDriver.get(driver) ?? { hosts: new Set(), envNames: new Set() };
             group.hosts.add(detected.host);
@@ -471,10 +551,16 @@ export function extractDataDependencies(files, declared) {
             apiHosts.push(detected);
         }
     }
-    // Manifest drivers with no host still surface as a hostless database entry.
+    // Manifest drivers with no host still surface as a database entry, carrying
+    // the driver's fixed service host where it has one.
     for (const driver of drivers) {
-        if (!databaseByDriver.has(driver))
-            databaseByDriver.set(driver, { hosts: new Set(), envNames: new Set() });
+        if (databaseByDriver.has(driver))
+            continue;
+        const wellKnownHost = WELL_KNOWN_DRIVER_HOSTS[driver];
+        databaseByDriver.set(driver, {
+            hosts: new Set(wellKnownHost ? [wellKnownHost] : []),
+            envNames: new Set()
+        });
     }
     const detectedEntries = [];
     for (const [driver, group] of [...databaseByDriver.entries()].sort(([a], [b]) => a.localeCompare(b))) {
@@ -535,7 +621,7 @@ export async function scanWorkspace(root, options = {}) {
     // Secret-bearing files remain visible only in the exclusion policy. They
     // must never be part of the deployable/source-control file boundary.
     const includedFiles = scopedFiles
-        .filter(file => !SECRET_FILE_NAMES.has(file.basename))
+        .filter(file => !SECRET_FILE_NAMES.has(file.basename) && !isSourceIntakeExcludedPath(file.path))
         .map(file => file.path)
         .sort();
     const graphWithoutDigest = {

package/dist/src/contracts.js

@@ -1,5 +1,6 @@
 export const PROTOCOL_VERSION = "2025-11-25";
 export const WAITING_FOR_DATA_ACCESS_PLAIN_ENGLISH = "Your app uses a company data source that isn't set up for apps yet. I've asked your IT admin — I'll continue automatically once it's approved.";
+export const WAITING_FOR_ANALYSIS_PLAIN_ENGLISH = "Harbour is checking which runtime settings this app needs. It will continue automatically when that check is available.";
 export function waitingForSecretsPlainEnglish(missingNames) {
     const count = missingNames.length;
     return `Your app uses ${count} key${count === 1 ? "" : "s"} (${missingNames.join(", ")}). Enter them securely in your Harbour console — I'll continue once they're set.`;
@@ -7,7 +8,8 @@ export function waitingForSecretsPlainEnglish(missingNames) {
 /** Stage → plain-English templates for the two waiting stages. */
 export const OPERATION_WAITING_STAGE_PLAIN_ENGLISH = {
     WAITING_FOR_DATA_ACCESS: WAITING_FOR_DATA_ACCESS_PLAIN_ENGLISH,
-    WAITING_FOR_SECRETS: "Your app needs one or more keys entered securely in your Harbour console before it can be deployed."
+    WAITING_FOR_SECRETS: "Your app needs one or more keys entered securely in your Harbour console before it can be deployed.",
+    WAITING_FOR_ANALYSIS: WAITING_FOR_ANALYSIS_PLAIN_ENGLISH
 };
 export function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -45,10 +47,29 @@ export function assertApplicationGraph(value) {
     const serialized = JSON.stringify(value);
     if (serialized.length > 65_536)
         throw new Error("MANIFEST_TOO_LARGE: application graph exceeds 64 KiB");
-    if (/secret_value|private_key|access_token|refresh_token/i.test(serialized)) {
+    // Environment-variable names are metadata, not secret material. Apps commonly
+    // declare names such as HIGGSFIELD_ACCESS_TOKEN or SESSION_COOKIE_SECRET; a
+    // whole-document substring scan incorrectly rejected those safe declarations.
+    // Reject only prohibited field names and assignment-shaped marker values.
+    if (containsRawSecretMarker(value)) {
         throw new Error("RAW_SECRET_REJECTED: graph contains a prohibited field or value marker");
     }
 }
+const RAW_SECRET_FIELDS = new Set(["secret_value", "private_key", "access_token", "refresh_token"]);
+function containsRawSecretMarker(value, parentKey) {
+    if (parentKey === "environmentVariableNames")
+        return false;
+    if (Array.isArray(value))
+        return value.some(item => containsRawSecretMarker(item, parentKey));
+    if (!isRecord(value)) {
+        return typeof value === "string" && /(?:secret_value|private_key|access_token|refresh_token)\s*[:=]/i.test(value);
+    }
+    return Object.entries(value).some(([key, child]) => {
+        if (RAW_SECRET_FIELDS.has(key.toLowerCase()))
+            return true;
+        return containsRawSecretMarker(child, key);
+    });
+}
 export function assertIdentityProfile(value) {
     if (!isRecord(value) || value.schema !== "harbour.enterprise-identity-profile/1.0") {
         throw new Error("VALIDATION_FAILED: unsupported identity profile schema");

package/dist/src/secret-paths.js

@@ -0,0 +1,19 @@
+/**
+ * Checked-in environment templates are safe source metadata. Real env files
+ * remain excluded because they can contain credentials. Keep this predicate
+ * shared by scanning, manifest validation, and the CLI archive guard so a
+ * template named `.env.mysql.example` is treated consistently everywhere.
+ */
+export function isEnvExamplePath(path) {
+    return /(^|\/)(?:\.env(?:\.[^/]+)*)\.(?:example|sample|template|dist)$/i.test(path);
+}
+export function isProhibitedSecretPath(path) {
+    if (isEnvExamplePath(path))
+        return false;
+    return /(^|\/)(?:\.env(?:\.[^/]+)?|\.npmrc|id_rsa|[^/]+\.(?:pem|key))$/i.test(path);
+}
+/** Files the intake worker intentionally leaves out of the Git-bound set. */
+export function isSourceIntakeExcludedPath(path) {
+    return /(^|\/)(?:__MACOSX)(?:\/|$)|(^|\/)\.DS_Store$/i.test(path)
+        || /(^|\/)\.github\/workflows\//i.test(path);
+}

package/dist/src/source-intake.js

@@ -1,4 +1,5 @@
 import { sha256, sha256Bytes, stableJson } from "./digest.js";
+import { isProhibitedSecretPath } from "./secret-paths.js";
 export class MemorySourceArchiveStore {
     archives = new Map();
     async put(objectKey, archive) { this.archives.set(objectKey, clone(archive)); }
@@ -109,11 +110,10 @@ export function sourceArchiveEvidence(archive) {
 function safeId(value) { return /^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$/.test(value); }
 function safeSourcePath(path) {
     return Boolean(path) && !path.startsWith("/") && !path.includes("\\") && !path.split("/").some(part => !part || part === "." || part === "..")
-        // A checked-in .env.example is a configuration template, not runtime
-        // credentials. Keep it with the app boundary while rejecting every real
-        // .env variant before source staging.
-        && (!/(^|\/)\.env(?:\.|$)/i.test(path) || /(^|\/)\.env\.example$/i.test(path))
-        && !/(^|\/)(?:id_rsa|.*\.pem|.*\.key)$/i.test(path) && !/(^|\/)(?:node_modules|\.git|\.harbour)(?:\/|$)/.test(path);
+        // Checked-in env templates are configuration metadata, not runtime
+        // credentials. All other env variants remain excluded before staging.
+        && !isProhibitedSecretPath(path)
+        && !/(^|\/)(?:node_modules|\.git|\.harbour)(?:\/|$)/.test(path);
 }
 function toBytes(value) { return typeof value === "string" ? new TextEncoder().encode(value) : value; }
 function bytesToBase64(bytes) { return Buffer.from(bytes).toString("base64"); }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": { "harbour": "./dist/packages/harbour-cli/src/cli.js" },
   "repository": { "type": "git", "url": "https://github.com/Fourier-Labs-AI/harbour-governance-control-plane.git" },
   "publishConfig": { "access": "public" },
-  "files": ["dist/packages/harbour-cli/src", "dist/src/analyzer.js", "dist/src/contracts.js", "dist/src/digest.js", "dist/src/source-intake.js", "package.json"],
+  "files": ["dist/packages/harbour-cli/src", "dist/src/analyzer.js", "dist/src/contracts.js", "dist/src/digest.js", "dist/src/secret-paths.js", "dist/src/source-intake.js", "package.json"],
   "engines": { "node": ">=22.13.0" },
   "scripts": {
     "build": "tsc -p tsconfig.json",