@fourier-labs/harbour 0.1.5 → 0.1.6

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

@@ -1,32 +1,53 @@
 #!/usr/bin/env node
 import { RemoteMcpClient } from "./remote-mcp-client.js";
 import { productionise } from "./productionise.js";
+import { safeError, CliError } from "./output.js";
+import { CLI_VERSION } from "./version.js";
 const args = process.argv.slice(2);
 const command = args[0];
 const rootIndex = args.indexOf("--app-root");
-const root = rootIndex >= 0 ? args[rootIndex + 1] : ".";
-const json = args.includes("--json");
+const root = rootIndex >= 0 ? args[rootIndex + 1] : undefined;
+const includePaths = [];
+let optionError;
+for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--include") {
+        const value = args[index + 1];
+        if (!value || value.startsWith("--")) {
+            optionError = "--include requires a relative file or directory path.";
+            break;
+        }
+        includePaths.push(value);
+        index += 1;
+    }
+}
 const url = process.env.HARBOUR_MCP_URL;
 const token = process.env.HARBOUR_TOKEN ?? "";
 const tenant = process.env.HARBOUR_TENANT ?? "";
-const usage = "Usage: harbour productionise --app-root <path>\nSet HARBOUR_MCP_URL, HARBOUR_TENANT, and HARBOUR_TOKEN before running.\n";
-if (!command || command === "help" || command === "--help" || args.includes("-h")) {
+const usage = "Usage: harbour productionise --app-root <path> [--include <relative-path>]... [--json]\nSet HARBOUR_MCP_URL, HARBOUR_TENANT, and HARBOUR_TOKEN before running.\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 (command !== "productionise" || !root || !url || !tenant) {
+else if (optionError || command !== "productionise" || !root || root.startsWith("--") || !url || !tenant || !token) {
+    if (optionError)
+        process.stderr.write(`${optionError}\n`);
     process.stderr.write(usage);
     process.exitCode = 2;
 }
 else {
     const client = new RemoteMcpClient(url, token, tenant);
     try {
-        await client.initialize();
-        const result = await productionise(root, client, message => { if (!json)
-            process.stderr.write(`${message}\n`); }, tenant);
-        process.stdout.write(`${JSON.stringify(result)}\n`);
+        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`);
     }
     catch (error) {
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        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`);
         process.exitCode = 1;
     }
 }

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

@@ -0,0 +1,14 @@
+export function safeError(error) {
+    const code = error instanceof CliError ? error.code : "CLI_FAILED";
+    const raw = error instanceof CliError ? error.message : "Harbour could not complete the request.";
+    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." };
+}
+export class CliError extends Error {
+    code;
+    operationRef;
+    constructor(code, message, operationRef) {
+        super(message);
+        this.code = code;
+        this.operationRef = operationRef;
+    }
+}

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

@@ -1,67 +1,135 @@
-import { basename, resolve } from "node:path";
+import { homedir } from "node:os";
+import { basename, parse, resolve } from "node:path";
 import { readFile } from "node:fs/promises";
 import { scanWorkspace } from "../../../src/analyzer.js";
 import { createSourceManifest } from "../../../src/source-intake.js";
 import { structured } from "./remote-mcp-client.js";
 import { archiveForManifest, putExact } from "./upload.js";
-export async function productionise(rootArg, client, output, tenantId) {
+import { CliError } from "./output.js";
+import { CLI_VERSION } from "./version.js";
+export async function productionise(rootArg, client, output, tenantId, includePaths = []) {
     const root = resolve(rootArg);
     output(`Harbour is checking ${basename(root)}.`);
-    const start = structured(await client.call("harbour_start_productionization", { appPath: basename(root), appName: basename(root), surface: "codex" }));
-    const operationId = start.operation?.operationId;
-    if (!operationId)
-        throw new Error("Harbour did not return an operation.");
-    const graph = await scanWorkspace(root, { sourceBoundary: "root" });
-    const submitted = structured(await client.call("harbour_submit_application_graph", { operationId, surface: "codex", graph }));
-    if (submitted.nextTool && submitted.nextTool !== "harbour_prepare_source_upload")
-        throw new Error("Harbour returned an unsupported next step.");
-    output(`Harbour found ${graph.deploymentScope.includedFiles.length} app files.`);
-    if (graph.deploymentScope.includedFiles.some(path => /(^|\/)(?:\.env(?:\.[^/]+)?|\.npmrc|id_rsa|[^/]+\.(?:pem|key))$/i.test(path))) {
-        throw new Error("Harbour found a prohibited secret file in the selected app boundary.");
-    }
+    if (root === parse(root).root || root === resolve(homedir()))
+        throw new CliError("PREFLIGHT_APP_ROOT", "The selected app boundary is unsafe.");
+    const graph = await scanWorkspace(root, { sourceBoundary: "root", ...(includePaths.length ? { includePaths } : {}) });
+    if (!graph.deploymentScope.includedFiles.length)
+        throw new CliError("PREFLIGHT_EMPTY", "The selected app boundary contains no eligible files.");
+    if (graph.deploymentScope.includedFiles.some(isProhibitedSecretPath))
+        throw new CliError("PREFLIGHT_SECRET_PATH", "The selected app boundary contains a prohibited secret file.");
     const files = await Promise.all(graph.deploymentScope.includedFiles.map(async (path) => ({ path, content: new Uint8Array(await readFile(resolve(root, path))) })));
-    const appId = projectName(graph.deploymentScope.appRoot);
-    const manifest = await createSourceManifest({ tenantId, appId, operationId, graphDigest: graph.graphDigest, files });
-    const prepared = structured(await client.call("harbour_prepare_source_upload", { operationId, surface: "codex", graph, manifest: { schema: "harbour.source-package-manifest/1.0", files: manifest.files.map(file => ({ path: file.path, size: file.bytes, sha256: file.sha256 })) } }));
-    if (!prepared.acceptedManifest || !prepared.sourceUpload)
-        throw new Error("Harbour did not return an upload contract.");
-    if (prepared.nextAction && typeof prepared.nextAction === "object" && "tool" in prepared.nextAction && prepared.nextAction.tool !== "harbour_execute_source_control")
-        throw new Error("Harbour returned an unsupported next step.");
-    const archive = await archiveForManifest(root, prepared.acceptedManifest);
-    await putExact(prepared.sourceUpload, archive.body);
-    output("Harbour has prepared the secure app package.");
-    output("Approval required: Harbour can save this app in the approved company code system. Nothing will be deployed or released. Type Approved. then press Enter.");
-    const approval = await readApproval();
-    if (approval !== "Approved.")
-        throw new Error("The Harbour save was not approved.");
-    const approvalObject = { schema: "harbour.stage-approval/1.0", step: "save_source_baseline", approved: true, approvedByUser: true, userApprovalText: approval, userVisibleProgress: "Approved.", nextStepSummary: "Harbour can safely save the app.", dataOrActions: ["Save the app in the company code system."] };
-    const executed = structured(await client.call("harbour_execute_source_control", { operationId, surface: "codex", graph, action: "save_baseline", mode: "EXECUTE", approval: approvalObject }));
-    if (executed.sourceControlExecution?.status === "FAILED")
-        throw new Error("Harbour could not save the app.");
-    let status;
-    for (let attempt = 0; attempt < 40; attempt += 1) {
-        status = structured(await client.call("harbour_get_operation_status", { operationId, waitSeconds: 15 }));
-        if (status.sourceSave?.status === "SUCCEEDED" || status.sourceSave?.status === "DUPLICATE")
-            break;
-        if (status.sourceSave?.status === "FAILED")
-            throw new Error("Harbour could not save the app.");
+    output(`Harbour found ${files.length} app files.`);
+    try {
+        await client.initialize();
+    }
+    catch {
+        throw new CliError("NOT_STARTED", "Harbour could not be reached before the operation started.");
+    }
+    let start;
+    try {
+        start = structured(await client.call("harbour_start_productionization", { appPath: basename(root), appName: basename(root), surface: "codex" }));
+    }
+    catch {
+        throw new CliError("NOT_STARTED", "Harbour could not start the productionisation operation.");
+    }
+    const operationRef = start.operation?.operationId;
+    if (!operationRef)
+        throw new CliError("NOT_STARTED", "Harbour did not start the productionisation operation.");
+    try {
+        const submitted = structured(await client.call("harbour_submit_application_graph", { operationId: operationRef, surface: "codex", graph }));
+        if (submitted.nextTool && submitted.nextTool !== "harbour_prepare_source_upload")
+            throw new CliError("UNSUPPORTED_NEXT_STEP", "Harbour returned an unsupported next step.", operationRef);
+        const appId = projectName(graph.deploymentScope.appRoot);
+        const manifest = await createSourceManifest({ tenantId, appId, operationId: operationRef, graphDigest: graph.graphDigest, files });
+        const prepared = structured(await client.call("harbour_prepare_source_upload", { operationId: operationRef, surface: "codex", graph, manifest: { schema: "harbour.source-package-manifest/1.0", files: manifest.files.map(file => ({ path: file.path, size: file.bytes, sha256: file.sha256 })) } }));
+        if (!prepared.acceptedManifest || !prepared.sourceUpload)
+            throw new CliError("UPLOAD_CONTRACT_MISSING", "Harbour did not return a safe upload contract.", operationRef);
+        if (prepared.nextAction?.tool && prepared.nextAction.tool !== "harbour_execute_source_control")
+            throw new CliError("UNSUPPORTED_NEXT_STEP", "Harbour returned an unsupported next step.", operationRef);
+        const archive = await archiveForManifest(root, prepared.acceptedManifest);
+        await putExact(prepared.sourceUpload, archive.body);
+        output("Harbour has prepared the secure app package.");
+        let execution = await execute(client, operationRef, graph);
+        if (execution.status === "APPROVAL_REQUIRED" || execution.approvalRequiredBeforeExternalAction === true) {
+            output(`Approval required: Harbour can copy ${files.length} app files to the approved company code system. Nothing will be deployed or released. Type Approved. then press Enter.`);
+            const approval = await readApproval();
+            if (approval !== "Approved.")
+                throw new CliError("APPROVAL_NOT_GRANTED", "The Harbour save was not approved.", operationRef);
+            execution = await execute(client, operationRef, graph, { schema: "harbour.stage-approval/1.0", step: "save_source_baseline", approved: true, approvedByUser: true, userApprovalText: approval, userVisibleProgress: "Approved.", nextStepSummary: "Harbour can safely save the app.", dataOrActions: ["Save the app in the company code system."] });
+        }
+        if (execution.status === "ADMIN_SETUP_REQUIRED")
+            throw new CliError("ADMIN_SETUP_REQUIRED", "The company code connection needs one-time administrator setup.", operationRef);
+        if (execution.status === "FAILED")
+            throw new CliError("FAILED", "Harbour could not save the app.", operationRef);
+        if (execution.status === "RETRYABLE_FAILURE")
+            throw new CliError("RETRYABLE_FAILURE", "Harbour could not complete the save yet. Resume this operation safely.", operationRef);
+        const evidence = await waitForSave(client, operationRef, graph, execution, output);
+        const report = structured(await client.call("harbour_build_verification_report", { operationId: operationRef, surface: "codex", graph, sourceControlEvidence: evidence.sourceControlEvidence, runnerEvidence: evidence.runnerEvidence }));
+        output("Harbour verified the saved app.");
+        return { cliVersion: CLI_VERSION, operationRef, result: safeVerificationResult(report) };
+    }
+    catch (error) {
+        if (error instanceof CliError || (error && typeof error === "object" && "code" in error))
+            throw error;
+        throw new CliError("OPERATION_FAILED", "Harbour could not complete the started operation.", operationRef);
     }
-    if (!status?.sourceControlEvidence || !status.runnerEvidence)
-        throw new Error("Harbour did not return managed save evidence.");
-    const report = structured(await client.call("harbour_build_verification_report", { operationId, surface: "codex", graph, sourceControlEvidence: status.sourceControlEvidence, runnerEvidence: status.runnerEvidence }));
-    output("Harbour verified the saved app.");
-    return report;
 }
-function projectName(value) {
-    const name = value.split(/[\\/]/).filter(Boolean).at(-1) ?? "harbour-app";
-    return name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "harbour-app";
+async function execute(client, operationRef, graph, approval) {
+    const args = { operationId: operationRef, surface: "codex", graph, action: "save_baseline", mode: "EXECUTE" };
+    if (approval)
+        args.approval = approval;
+    return structured(await client.call("harbour_execute_source_control", args)).sourceControlExecution ?? {};
 }
-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();
+async function waitForSave(client, operationRef, graph, first, output) {
+    let waitSeconds = boundedWait(first.nextAction?.waitSeconds);
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+        const status = structured(await client.call("harbour_get_operation_status", { operationId: operationRef, waitSeconds }));
+        const terminal = status.sourceSave?.status;
+        if (terminal === "SUCCEEDED" || terminal === "DUPLICATE") {
+            const sourceControlEvidence = status.sourceControlEvidence ?? status.sourceSave?.sourceControlEvidence;
+            const runnerEvidence = status.runnerEvidence ?? status.sourceSave?.runnerEvidence;
+            if (!sourceControlEvidence || !runnerEvidence)
+                throw new CliError("EVIDENCE_MISSING", "Harbour did not return managed save evidence.", operationRef);
+            return { sourceControlEvidence, runnerEvidence };
+        }
+        if (terminal === "FAILED")
+            throw new CliError("FAILED", "Harbour could not save the app.", operationRef);
+        if (terminal === "RETRYABLE_FAILURE")
+            throw new CliError("RETRYABLE_FAILURE", "Harbour could not complete the save yet. Resume this operation safely.", operationRef);
+        waitSeconds = boundedWait(status.nextAction?.waitSeconds ?? status.waitSeconds);
+        output("Harbour is still saving the app.");
     }
-    return new Promise(resolve => { process.stdin.setEncoding("utf8"); process.stdin.once("data", value => resolve(String(value).trim())); });
+    throw new CliError("RETRYABLE_FAILURE", "Harbour could not finish the save within the safe retry window.", operationRef);
+}
+function boundedWait(value) {
+    return Math.min(15, Math.max(0, Number.isFinite(value) ? Math.floor(value) : 15));
+}
+function isProhibitedSecretPath(path) {
+    if (/(^|\/)\.env\.example$/i.test(path))
+        return false;
+    return /(^|\/)(?:\.env(?:\.[^/]+)?|\.npmrc|id_rsa|[^/]+\.(?:pem|key))$/i.test(path);
+}
+function safeVerificationResult(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { verification: "completed" };
+    const record = value;
+    const decision = record.decision && typeof record.decision === "object" && !Array.isArray(record.decision)
+        ? record.decision
+        : undefined;
+    return {
+        verification: typeof decision?.status === "string"
+            ? decision.status
+            : typeof record.status === "string"
+                ? record.status
+                : "completed",
+        ...(typeof decision?.assuranceLevel === "string" ? { assuranceLevel: decision.assuranceLevel } : {}),
+        ...(typeof record.protectedUrl === "string" ? { protectedUrl: record.protectedUrl } : {})
+    };
 }
+function projectName(value) { const name = value.split(/[\\/]/).filter(Boolean).at(-1) ?? "harbour-app"; return name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "harbour-app"; }
+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())); }); }

package/dist/packages/harbour-cli/src/remote-mcp-client.js

@@ -1,3 +1,4 @@
+import { CLI_VERSION } from "./version.js";
 export class RemoteMcpClient {
     url;
     token;
@@ -12,7 +13,7 @@ export class RemoteMcpClient {
     async initialize() {
         if (this.initialized)
             return;
-        await this.request("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "harbour-cli", version: "0.1.0" } });
+        await this.request("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "harbour-cli", version: CLI_VERSION } });
         await this.request("notifications/initialized", undefined, false);
         this.initialized = true;
     }

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

@@ -2,24 +2,33 @@ import { readFile, lstat } from "node:fs/promises";
 import { relative, resolve, sep } from "node:path";
 import { createSourceArchive } from "../../../src/source-intake.js";
 import { sha256Bytes } from "../../../src/digest.js";
-const SECRET = /(^|\/)(?:\.env(?:\.[^/]+)?|\.npmrc|id_rsa|[^/]+\.(?:pem|key))$/i;
+const SECRET = /(^|\/)(?:(?!\.env\.example$)\.env(?:\.[^/]+)?|\.npmrc|id_rsa|[^/]+\.(?:pem|key))$/i;
 export async function archiveForManifest(root, manifest) {
+    const rootAbsolute = resolve(root);
+    if ((await lstat(rootAbsolute)).isSymbolicLink())
+        throw new Error("Harbour rejected an unsafe app boundary.");
     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("/"))
             throw new Error("Harbour rejected an unsafe source path.");
         seen.add(entry.path);
-        const absolute = resolve(root, entry.path);
-        if (!absolute.startsWith(resolve(root) + sep))
+        const absolute = resolve(rootAbsolute, entry.path);
+        if (!absolute.startsWith(rootAbsolute + sep))
             throw new Error("Harbour rejected a path outside the selected app.");
+        let current = rootAbsolute;
+        for (const component of entry.path.split("/")) {
+            current = resolve(current, component);
+            if ((await lstat(current)).isSymbolicLink())
+                throw new Error("Harbour rejected an unsafe source path.");
+        }
         const info = await lstat(absolute);
         if (!info.isFile())
             throw new Error("The app changed while it was being packaged.");
         const content = new Uint8Array(await readFile(absolute));
         if (content.byteLength !== entry.bytes || await sha256Bytes(content) !== entry.sha256)
             throw new Error(`The app changed while it was being packaged (${entry.path}).`);
-        files.push({ path: relative(root, absolute).split(sep).join("/"), content });
+        files.push({ path: relative(rootAbsolute, absolute).split(sep).join("/"), content });
     }
     const archive = await createSourceArchive(manifest, files);
     const body = new TextEncoder().encode(JSON.stringify(archive));
@@ -32,7 +41,7 @@ export async function putExact(upload, body) {
     let lastError;
     for (let attempt = 0; attempt < 2; attempt += 1) {
         try {
-            const response = await fetch(upload.url, { method: "PUT", headers, body: Buffer.from(body) });
+            const response = await fetch(upload.url, { method: "PUT", headers, body: Buffer.from(body), redirect: "error" });
             if (!response.ok) {
                 if (![408, 429, 500, 502, 503, 504].includes(response.status))
                     throw new Error(`Harbour source upload failed (${response.status}).`);

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

@@ -0,0 +1 @@
+export const CLI_VERSION = "0.1.6";

package/dist/src/analyzer.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { readFile, readdir, stat } from "node:fs/promises";
+import { lstat, readFile, readdir, stat } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { sha256 } from "./digest.js";
 const ANALYZER_VERSION = "0.1.0";
@@ -13,6 +13,46 @@ const MAX_FILE_BYTES = 256_000;
 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"]);
+function normalizeIncludePath(value) {
+    if (!value || value === ".")
+        return "";
+    if (value.startsWith("/") || value.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(value))
+        throw new Error("ANALYZER_INCLUDE_INVALID: include paths must be relative to the selected app root.");
+    const parts = value.split(/[\\/]+/).filter(Boolean);
+    if (parts.some(part => part === "." || part === ".."))
+        throw new Error("ANALYZER_INCLUDE_INVALID: include paths may not contain traversal segments.");
+    return parts.join("/");
+}
+async function collectIncludedFiles(root, includePaths, output, unknowns) {
+    const normalized = [...new Set(includePaths.map(normalizeIncludePath))];
+    for (const include of normalized) {
+        if (include.split("/").some(part => IGNORED_DIRS.has(part)))
+            continue;
+        const absolute = include ? join(root, ...include.split("/")) : root;
+        let info;
+        try {
+            info = await lstat(absolute);
+        }
+        catch {
+            throw new Error(`ANALYZER_INCLUDE_MISSING: include path does not exist: ${include || "."}`);
+        }
+        if (info.isSymbolicLink())
+            throw new Error(`ANALYZER_INCLUDE_UNSAFE: symlink include path is not allowed: ${include || "."}`);
+        if (!info.isFile() && !info.isDirectory())
+            throw new Error(`ANALYZER_INCLUDE_UNSAFE: include path is not a file or directory: ${include}`);
+        let current = root;
+        for (const part of include.split("/").filter(Boolean)) {
+            current = join(current, part);
+            const component = await lstat(current);
+            if (component.isSymbolicLink())
+                throw new Error(`ANALYZER_INCLUDE_UNSAFE: symlink path component is not allowed: ${include}`);
+        }
+        if (info.isDirectory())
+            await collectFiles(root, absolute, output, unknowns);
+        else
+            await collectFile(root, absolute, output);
+    }
+}
 function extension(path) {
     const index = path.lastIndexOf(".");
     return index >= 0 ? path.slice(index) : "";
@@ -33,16 +73,23 @@ async function collectFiles(root, current, output, unknowns) {
         }
         if (!entry.isFile())
             continue;
-        const absolute = join(current, entry.name);
-        const rel = relative(root, absolute);
-        const info = await stat(absolute);
-        const fact = { path: rel, basename: entry.name, size: info.size };
-        const safeEnvExample = entry.name === ".env.example" || entry.name.endsWith(".env.example");
-        if (!SECRET_FILE_NAMES.has(entry.name) && info.size <= MAX_FILE_BYTES && (TEXT_EXTENSIONS.has(extension(entry.name)) || safeEnvExample)) {
-            fact.content = await readFile(absolute, "utf8");
-        }
-        output.push(fact);
+        await collectFile(root, join(current, entry.name), output);
+    }
+}
+async function collectFile(root, absolute, output) {
+    const path = relative(root, absolute);
+    if (output.some(file => file.path === path))
+        return;
+    const info = await lstat(absolute);
+    if (!info.isFile() || info.isSymbolicLink())
+        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)) {
+        fact.content = await readFile(absolute, "utf8");
     }
+    output.push(fact);
 }
 function unique(values) {
     return [...new Set(values.filter(Boolean))].sort();
@@ -271,16 +318,25 @@ function detectGitProvider(locator) {
     return "git";
 }
 export async function scanWorkspace(root, options = {}) {
+    const rootInfo = await lstat(root);
+    if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory())
+        throw new Error("ANALYZER_ROOT_INVALID: selected app root must be a real directory.");
     const unknowns = [];
     const files = [];
-    await collectFiles(root, root, files, unknowns);
-    const fingerprintInput = files.map(file => `${file.path}:${file.size}:${file.content ? createHash("sha256").update(file.content).digest("hex") : "unread"}`).join("\n");
+    if (options.includePaths?.length)
+        await collectIncludedFiles(root, options.includePaths, files, unknowns);
+    else
+        await collectFiles(root, root, files, unknowns);
+    const scopedFiles = files.sort((a, b) => a.path.localeCompare(b.path));
+    if (options.includePaths?.length && scopedFiles.length === 0)
+        throw new Error("ANALYZER_INCLUDE_EMPTY: the declared include paths contain no eligible files.");
+    const fingerprintInput = scopedFiles.map(file => `${file.path}:${file.size}:${file.content ? createHash("sha256").update(file.content).digest("hex") : "unread"}`).join("\n");
     const workspaceFingerprint = await sha256(fingerprintInput);
-    const { dependencies, scripts, packageManagers } = parsePackageJson(files);
-    const framework = detectFramework(dependencies, files);
+    const { dependencies, scripts, packageManagers } = parsePackageJson(scopedFiles);
+    const framework = detectFramework(dependencies, scopedFiles);
     // Secret-bearing files remain visible only in the exclusion policy. They
     // must never be part of the deployable/source-control file boundary.
-    const includedFiles = files
+    const includedFiles = scopedFiles
         .filter(file => !SECRET_FILE_NAMES.has(file.basename))
         .map(file => file.path)
         .sort();
@@ -295,11 +351,11 @@ export async function scanWorkspace(root, options = {}) {
             excludedSecretFiles: [...SECRET_FILE_NAMES].sort(),
             deployCommands: detectDeployCommands(scripts)
         },
-        components: detectComponents(framework, dependencies, files),
-        capabilities: detectCapabilities(files, dependencies),
+        components: detectComponents(framework, dependencies, scopedFiles),
+        capabilities: detectCapabilities(scopedFiles, dependencies),
         packageManagers,
         dependencyNames: dependencies,
-        environmentVariableNames: detectEnvNames(files),
+        environmentVariableNames: detectEnvNames(scopedFiles),
         testCommands: detectTestCommands(scripts),
         analysis: {
             analyzerVersion: ANALYZER_VERSION,

package/dist/src/source-intake.js

@@ -6,6 +6,7 @@ export class MemorySourceArchiveStore {
         const value = this.archives.get(objectKey);
         return value ? clone(value) : undefined;
     }
+    async exists(objectKey) { return this.archives.has(objectKey); }
     async delete(objectKey) { this.archives.delete(objectKey); }
 }
 export async function createSourceManifest(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": { "harbour": "./dist/packages/harbour-cli/src/cli.js" },