@fourier-labs/harbour 0.1.2

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

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { RemoteMcpClient } from "./remote-mcp-client.js";
+import { productionise } from "./productionise.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 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")) {
+    process.stdout.write(usage);
+}
+else if (command !== "productionise" || !root || !url || !tenant) {
+    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`);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+}

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

@@ -0,0 +1,67 @@
+import { basename, 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) {
+    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.");
+    }
+    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.");
+    }
+    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 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

@@ -0,0 +1,47 @@
+export class RemoteMcpClient {
+    url;
+    token;
+    tenant;
+    id = 0;
+    initialized = false;
+    constructor(url, token, tenant) {
+        this.url = url;
+        this.token = token;
+        this.tenant = tenant;
+    }
+    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("notifications/initialized", undefined, false);
+        this.initialized = true;
+    }
+    async call(name, args) {
+        const response = await this.request("tools/call", { name, arguments: args });
+        const result = response;
+        if (result.isError)
+            throw new Error(result.content?.map(item => item.text ?? "").join("\n") || "Harbour rejected the request.");
+        return result;
+    }
+    async request(method, params, expectResponse = true) {
+        const headers = { "content-type": "application/json", "mcp-protocol-version": "2025-11-25" };
+        if (this.token)
+            headers.authorization = `Bearer ${this.token}`;
+        headers["x-harbour-tenant"] = this.tenant;
+        const response = await fetch(this.url, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", id: ++this.id, method, ...(params === undefined ? {} : { params }) }) });
+        if (!expectResponse)
+            return undefined;
+        const body = await response.json();
+        if (!response.ok || body.error)
+            throw new Error(body.error?.message ?? `Harbour request failed (${response.status}).`);
+        return body.result;
+    }
+}
+export function structured(result) {
+    if (result.isError)
+        throw new Error(result.content?.map(item => item.text ?? "").join("\n") || "Harbour rejected the request.");
+    return result.structuredContent;
+}
+export function plainText(result) {
+    return result.content?.map(item => item.text ?? "").join("\n") ?? "";
+}

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

@@ -0,0 +1,53 @@
+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;
+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("/"))
+            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))
+            throw new Error("Harbour rejected a path outside the selected app.");
+        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 });
+    }
+    const archive = await createSourceArchive(manifest, files);
+    const body = new TextEncoder().encode(JSON.stringify(archive));
+    return { body, digest: archive.archiveDigest };
+}
+export async function putExact(upload, body) {
+    if (upload.url.startsWith("local://"))
+        return;
+    const headers = { ...(upload.requiredHeaders ?? {}), ...(upload.contentType ? { "content-type": upload.contentType } : {}) };
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const response = await fetch(upload.url, { method: "PUT", headers, body: Buffer.from(body) });
+            if (!response.ok) {
+                if (![408, 429, 500, 502, 503, 504].includes(response.status))
+                    throw new Error(`Harbour source upload failed (${response.status}).`);
+                throw new Error(`Harbour source upload failed (${response.status}).`);
+            }
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            const retryable = error instanceof Error && (!/\(\d{3}\)/.test(error.message) || /\((408|429|500|502|503|504)\)/.test(error.message));
+            if (attempt === 0 && retryable)
+                await new Promise(resolve => setTimeout(resolve, 250));
+            else
+                break;
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error("Harbour source upload failed.");
+}

package/dist/src/analyzer.js

@@ -0,0 +1,311 @@
+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 { basename, dirname, join, relative } from "node:path";
+import { sha256 } from "./digest.js";
+const ANALYZER_VERSION = "0.1.0";
+const MAX_FILES = 600;
+const MAX_FILE_BYTES = 256_000;
+// Harbour's own receipts and lab metadata are control-plane artifacts, not
+// application files. Keeping them out also makes reruns idempotent after a
+// 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"]);
+function extension(path) {
+    const index = path.lastIndexOf(".");
+    return index >= 0 ? path.slice(index) : "";
+}
+async function collectFiles(root, current, output, unknowns) {
+    if (output.length >= MAX_FILES)
+        return;
+    const entries = await readdir(current, { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (output.length >= MAX_FILES) {
+            unknowns.push(`file limit reached at ${MAX_FILES} files`);
+            return;
+        }
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRS.has(entry.name))
+                await collectFiles(root, join(current, entry.name), output, unknowns);
+            continue;
+        }
+        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);
+    }
+}
+function unique(values) {
+    return [...new Set(values.filter(Boolean))].sort();
+}
+function parsePackageJson(files) {
+    const packageFile = files.find(file => file.path === "package.json" && file.content);
+    const dependencies = [];
+    const scripts = {};
+    if (packageFile?.content) {
+        const parsed = JSON.parse(packageFile.content);
+        dependencies.push(...Object.keys(parsed.dependencies ?? {}), ...Object.keys(parsed.devDependencies ?? {}));
+        Object.assign(scripts, parsed.scripts ?? {});
+        if (parsed.packageManager)
+            dependencies.push(parsed.packageManager.split("@")[0] ?? "");
+    }
+    const packageManagers = unique([
+        files.some(file => file.basename === "package-lock.json") ? "npm" : "",
+        files.some(file => file.basename === "pnpm-lock.yaml") ? "pnpm" : "",
+        files.some(file => file.basename === "yarn.lock") ? "yarn" : "",
+        files.some(file => file.basename === "bun.lockb" || file.basename === "bun.lock") ? "bun" : "",
+        packageFile ? "npm" : ""
+    ]);
+    return { dependencies: unique(dependencies), scripts, packageManagers };
+}
+function detectFramework(dependencies, files) {
+    const deps = new Set(dependencies);
+    if (deps.has("next"))
+        return "nextjs";
+    if (deps.has("@remix-run/react"))
+        return "remix";
+    if (deps.has("@sveltejs/kit"))
+        return "sveltekit";
+    if (deps.has("astro"))
+        return "astro";
+    if (deps.has("vite"))
+        return "vite";
+    if (deps.has("react"))
+        return "react";
+    if (deps.has("express"))
+        return "express";
+    if (files.some(file => file.basename === "requirements.txt" || file.basename === "pyproject.toml"))
+        return "python";
+    return "unknown";
+}
+function detectComponents(framework, dependencies, files) {
+    const deps = new Set(dependencies);
+    const entries = files.map(file => file.path);
+    const components = [];
+    const frontendEntries = entries.filter(path => /^(src|app|pages)\//.test(path) && /\.(tsx|jsx|ts|js|html)$/.test(path)).slice(0, 12);
+    const backendEntries = entries.filter(path => /^(server|api|src\/server|functions)\//.test(path) && /\.(ts|js|mjs|cjs)$/.test(path)).slice(0, 12);
+    if (frontendEntries.length || ["vite", "nextjs", "react", "remix", "sveltekit", "astro"].includes(framework)) {
+        components.push({
+            componentId: "web-frontend",
+            kind: framework === "nextjs" || framework === "remix" ? "SSR_FRONTEND" : "STATIC_FRONTEND",
+            runtime: deps.has("vite") || deps.has("react") || deps.has("next") ? "node" : "unknown",
+            framework,
+            entrypoints: frontendEntries.length ? frontendEntries : ["package.json"]
+        });
+    }
+    if (backendEntries.length || deps.has("express") || deps.has("fastify") || deps.has("hono")) {
+        components.push({
+            componentId: "http-backend",
+            kind: "HTTP_BACKEND",
+            runtime: "node",
+            framework: deps.has("express") ? "express" : deps.has("fastify") ? "fastify" : deps.has("hono") ? "hono" : "unknown",
+            entrypoints: backendEntries.length ? backendEntries : ["package.json"]
+        });
+    }
+    return components.length ? components : [{ componentId: "app", kind: "UNKNOWN", runtime: "unknown", framework, entrypoints: entries.slice(0, 8) }];
+}
+function detectCapabilities(files, dependencies) {
+    const corpus = `${dependencies.join("\n")}\n${files.map(file => `${file.path}\n${file.content ?? ""}`).join("\n")}`;
+    const capabilities = [];
+    if (/auth|oauth|oidc|saml|next-auth|passport|clerk|auth0|supabase/i.test(corpus)) {
+        capabilities.push({ kind: "IDENTITY", providerHint: "existing-auth-code", usage: "Authentication or identity dependency/code detected" });
+    }
+    if (/postgres|mysql|sqlite|prisma|drizzle|sequelize|mongoose|mongodb|redis/i.test(corpus)) {
+        capabilities.push({ kind: "RELATIONAL_DATA", usage: "Database dependency or connection pattern detected" });
+    }
+    if (/s3|blob|bucket|r2|storage/i.test(corpus)) {
+        capabilities.push({ kind: "OBJECT_STORAGE", usage: "Object storage dependency or naming pattern detected" });
+    }
+    if (/openai|anthropic|gemini|model|llm/i.test(corpus)) {
+        capabilities.push({ kind: "MODEL_ENDPOINT", usage: "Model endpoint dependency or naming pattern detected" });
+    }
+    if (/api[_-]?key|fetch\(|axios|external/i.test(corpus)) {
+        capabilities.push({ kind: "EXTERNAL_API", usage: "External API call or credential name pattern detected" });
+    }
+    if (/process\.env|import\.meta\.env|Deno\.env/i.test(corpus)) {
+        capabilities.push({ kind: "SECRETS", usage: "Environment-variable based configuration detected" });
+    }
+    return capabilities;
+}
+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] ?? "");
+        }
+        if (file.basename === ".env.example" || file.basename.endsWith(".env.example")) {
+            for (const line of content.split(/\r?\n/)) {
+                const envMatch = /^([A-Z0-9_]{3,})=/.exec(line.trim());
+                if (envMatch)
+                    names.push(envMatch[1] ?? "");
+            }
+        }
+    }
+    return unique(names);
+}
+function detectTestCommands(scripts) {
+    return unique([
+        scripts.test ? "npm test" : "",
+        scripts.check ? "npm run check" : "",
+        scripts.lint ? "npm run lint" : ""
+    ]);
+}
+function detectDeployCommands(scripts) {
+    return unique([
+        scripts.build ? "npm run build" : "",
+        scripts.start ? "npm start" : "",
+        scripts.dev ? "npm run dev" : "",
+        scripts.preview ? "npm run preview" : "",
+        scripts.deploy ? "npm run deploy" : ""
+    ]);
+}
+async function detectGitSource(root, fingerprint, options, includedFiles) {
+    const gitRoot = options.sourceBoundary === "root"
+        ? (existsSync(join(root, ".git")) ? root : undefined)
+        : findGitRoot(root);
+    if (!gitRoot || !allDeployableFilesTracked(gitRoot, root, includedFiles)) {
+        const source = {
+            schema: "harbour.source-ref/1.0",
+            kind: "unversioned_workspace",
+            locator: options.sourceLocator ?? `workspace://${basename(root)}`,
+            revision: fingerprint,
+            recoverable: false
+        };
+        if (options.sourceProvider)
+            source.provider = options.sourceProvider;
+        return source;
+    }
+    const gitDir = await resolveGitDir(gitRoot);
+    const headPath = join(gitDir, "HEAD");
+    let revision = fingerprint;
+    let locator = options.sourceLocator ?? await readFirstRemoteUrl(gitRoot) ?? `git://${basename(gitRoot)}`;
+    try {
+        const head = (await readFile(headPath, "utf8")).trim();
+        if (head.startsWith("ref:")) {
+            const ref = head.replace("ref:", "").trim();
+            const commit = await readFile(join(gitDir, ref), "utf8").then(value => value.trim()).catch(() => "");
+            revision = commit ? `${commit}@${fingerprint}` : `${ref}@${fingerprint}`;
+        }
+        else {
+            revision = `${head}@${fingerprint}`;
+        }
+    }
+    catch {
+        revision = fingerprint;
+    }
+    const source = {
+        schema: "harbour.source-ref/1.0",
+        kind: "connected_repository",
+        locator,
+        revision,
+        recoverable: true
+    };
+    source.provider = options.sourceProvider ?? detectGitProvider(locator);
+    return source;
+}
+function allDeployableFilesTracked(gitRoot, appRoot, includedFiles) {
+    if (includedFiles.length === 0)
+        return false;
+    const appPathFromGitRoot = relative(gitRoot, appRoot);
+    const tracked = spawnSync("git", ["-C", gitRoot, "ls-files", "--", appPathFromGitRoot || "."], {
+        encoding: "utf8"
+    });
+    if (tracked.status !== 0)
+        return false;
+    const trackedPaths = new Set(tracked.stdout.split(/\r?\n/).filter(Boolean));
+    return includedFiles.every(file => {
+        const repoRelativePath = appPathFromGitRoot ? join(appPathFromGitRoot, file) : file;
+        return trackedPaths.has(repoRelativePath);
+    });
+}
+function findGitRoot(start) {
+    let current = start;
+    while (true) {
+        if (existsSync(join(current, ".git")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+async function resolveGitDir(gitRoot) {
+    const dotGit = join(gitRoot, ".git");
+    const info = await stat(dotGit);
+    if (info.isDirectory())
+        return dotGit;
+    const content = await readFile(dotGit, "utf8");
+    const match = /^gitdir:\s*(.+)$/m.exec(content);
+    if (!match?.[1])
+        return dotGit;
+    const gitDir = match[1];
+    return gitDir.startsWith("/") ? gitDir : join(gitRoot, gitDir);
+}
+async function readFirstRemoteUrl(gitRoot) {
+    try {
+        const config = await readFile(join(await resolveGitDir(gitRoot), "config"), "utf8");
+        const match = /\[remote "origin"\][\s\S]*?\n\s*url = (.+)/.exec(config) ?? /\[remote "[^"]+"\][\s\S]*?\n\s*url = (.+)/.exec(config);
+        return match?.[1]?.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function detectGitProvider(locator) {
+    if (/^(https:\/\/|git@)github\.com[:/]/i.test(locator) || /\/\/github\.com\//i.test(locator))
+        return "github";
+    if (/^(https:\/\/|git@)gitlab\.com[:/]/i.test(locator) || /\/\/gitlab\.com\//i.test(locator))
+        return "gitlab";
+    if (/^(https:\/\/|git@)bitbucket\.org[:/]/i.test(locator) || /\/\/bitbucket\.org\//i.test(locator))
+        return "bitbucket";
+    return "git";
+}
+export async function scanWorkspace(root, options = {}) {
+    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");
+    const workspaceFingerprint = await sha256(fingerprintInput);
+    const { dependencies, scripts, packageManagers } = parsePackageJson(files);
+    const framework = detectFramework(dependencies, files);
+    // 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
+        .filter(file => !SECRET_FILE_NAMES.has(file.basename))
+        .map(file => file.path)
+        .sort();
+    const graphWithoutDigest = {
+        schema: "harbour.application-graph/1.0",
+        workspaceFingerprint,
+        source: await detectGitSource(root, workspaceFingerprint, options, includedFiles),
+        deploymentScope: {
+            appRoot: basename(root),
+            includedFiles,
+            excludedDirectories: [...IGNORED_DIRS].sort(),
+            excludedSecretFiles: [...SECRET_FILE_NAMES].sort(),
+            deployCommands: detectDeployCommands(scripts)
+        },
+        components: detectComponents(framework, dependencies, files),
+        capabilities: detectCapabilities(files, dependencies),
+        packageManagers,
+        dependencyNames: dependencies,
+        environmentVariableNames: detectEnvNames(files),
+        testCommands: detectTestCommands(scripts),
+        analysis: {
+            analyzerVersion: ANALYZER_VERSION,
+            coverage: unknowns.length ? "PARTIAL" : "COMPLETE_FOR_SUPPORTED_MANIFESTS",
+            unknowns
+        }
+    };
+    return { ...graphWithoutDigest, graphDigest: await sha256(graphWithoutDigest) };
+}

package/dist/src/contracts.js

@@ -0,0 +1,51 @@
+export const PROTOCOL_VERSION = "2025-11-25";
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function requireString(object, key) {
+    const value = object[key];
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`VALIDATION_FAILED: ${key} must be a non-empty string`);
+    return value;
+}
+export function assertApplicationGraph(value) {
+    if (!isRecord(value))
+        throw new Error("VALIDATION_FAILED: graph must be an object");
+    if (value.schema !== "harbour.application-graph/1.0")
+        throw new Error("VALIDATION_FAILED: unsupported graph schema");
+    requireString(value, "workspaceFingerprint");
+    const graphDigest = requireString(value, "graphDigest");
+    // Some coding surfaces emit a bare hexadecimal digest while others include
+    // the algorithm prefix. Normalize at the Harbour boundary so one client
+    // formatting difference cannot invalidate the later upload/save steps.
+    if (/^[0-9a-f]{64}$/i.test(graphDigest))
+        value.graphDigest = `sha256:${graphDigest}`;
+    if (!/^sha256:[0-9a-f]{64}$/i.test(value.graphDigest))
+        throw new Error("VALIDATION_FAILED: graphDigest must be a SHA-256 digest");
+    if (!isRecord(value.source))
+        throw new Error("VALIDATION_FAILED: source is required");
+    requireString(value.source, "revision");
+    if (!isRecord(value.deploymentScope))
+        throw new Error("VALIDATION_FAILED: deploymentScope is required");
+    if (!Array.isArray(value.deploymentScope.includedFiles) || value.deploymentScope.includedFiles.length === 0) {
+        throw new Error("VALIDATION_FAILED: deploymentScope.includedFiles must include at least one file");
+    }
+    if (!Array.isArray(value.components) || value.components.length === 0)
+        throw new Error("VALIDATION_FAILED: at least one component is required");
+    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)) {
+        throw new Error("RAW_SECRET_REJECTED: graph contains a prohibited field or value marker");
+    }
+}
+export function assertIdentityProfile(value) {
+    if (!isRecord(value) || value.schema !== "harbour.enterprise-identity-profile/1.0") {
+        throw new Error("VALIDATION_FAILED: unsupported identity profile schema");
+    }
+    requireString(value, "profileId");
+    requireString(value, "issuerRef");
+    requireString(value, "clientIdRef");
+    if (!Array.isArray(value.requiredScopes))
+        throw new Error("VALIDATION_FAILED: requiredScopes must be an array");
+}

package/dist/src/digest.js

@@ -0,0 +1,26 @@
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (value && typeof value === "object") {
+        const output = {};
+        for (const key of Object.keys(value).sort()) {
+            output[key] = stableValue(value[key]);
+        }
+        return output;
+    }
+    return value;
+}
+export function stableJson(value) {
+    return JSON.stringify(stableValue(value));
+}
+export async function sha256(value) {
+    const bytes = new TextEncoder().encode(typeof value === "string" ? value : stableJson(value));
+    return sha256Bytes(bytes);
+}
+export async function sha256Bytes(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", new Uint8Array(bytes).buffer);
+    return `sha256:${Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+export async function verifyDigest(value, expected) {
+    return (await sha256(value)) === expected;
+}

package/dist/src/source-intake.js

@@ -0,0 +1,124 @@
+import { sha256, sha256Bytes, stableJson } from "./digest.js";
+export class MemorySourceArchiveStore {
+    archives = new Map();
+    async put(objectKey, archive) { this.archives.set(objectKey, clone(archive)); }
+    async get(objectKey) {
+        const value = this.archives.get(objectKey);
+        return value ? clone(value) : undefined;
+    }
+    async delete(objectKey) { this.archives.delete(objectKey); }
+}
+export async function createSourceManifest(input) {
+    const files = await Promise.all(input.files.map(async (file) => {
+        const bytes = toBytes(file.content);
+        return { path: file.path, sha256: await sha256Bytes(bytes), bytes: bytes.byteLength };
+    }));
+    const draft = { schema: "harbour.source-manifest/1.0", tenantId: input.tenantId, appId: input.appId, operationId: input.operationId, graphDigest: input.graphDigest, files };
+    const manifest = { ...draft, manifestDigest: await sha256(draft) };
+    validateSourceManifest(manifest);
+    return manifest;
+}
+export async function createSourceArchive(manifest, files) {
+    validateSourceManifest(manifest);
+    const encodedFiles = files.map(file => ({ path: file.path, contentBase64: bytesToBase64(toBytes(file.content)) }));
+    const draft = { schema: "harbour.source-archive/1.0", manifest, files: encodedFiles };
+    const archive = { ...draft, archiveDigest: await sha256(draft) };
+    await validateSourceArchive(archive);
+    return archive;
+}
+export function createSourceUploadIntent(input) {
+    validateSourceManifest(input.manifest);
+    if (input.manifest.tenantId !== input.tenantId || input.manifest.appId !== input.appId || input.manifest.operationId !== input.operationId) {
+        throw new Error("SOURCE_UPLOAD_INTENT_SCOPE_MISMATCH: manifest does not belong to this tenant, app, and operation.");
+    }
+    const now = input.now ?? new Date();
+    const expiry = new Date(now.getTime() + (input.ttlMs ?? 15 * 60_000));
+    const nonce = crypto.randomUUID();
+    return {
+        schema: "harbour.source-upload-intent/1.0",
+        intentId: `upload-${nonce}`,
+        tenantId: input.tenantId,
+        appId: input.appId,
+        operationId: input.operationId,
+        objectKey: `source-staging/${input.tenantId}/${input.appId}/${input.operationId}/${nonce}.json`,
+        manifestDigest: input.manifest.manifestDigest,
+        preparedAt: now.toISOString(),
+        expiresAt: expiry.toISOString(),
+        used: false
+    };
+}
+export async function acceptSourceUpload(input) {
+    const { intent, archive } = input;
+    if (intent.schema !== "harbour.source-upload-intent/1.0" || intent.used)
+        throw new Error("SOURCE_UPLOAD_INTENT_USED: upload intent is no longer valid.");
+    if (new Date(intent.expiresAt).getTime() <= (input.now ?? new Date()).getTime())
+        throw new Error("SOURCE_UPLOAD_INTENT_EXPIRED: upload intent has expired.");
+    await validateSourceArchive(archive);
+    if (archive.manifest.manifestDigest !== intent.manifestDigest
+        || archive.manifest.tenantId !== intent.tenantId
+        || archive.manifest.appId !== intent.appId
+        || archive.manifest.operationId !== intent.operationId) {
+        throw new Error("SOURCE_UPLOAD_INTENT_SCOPE_MISMATCH: archive does not match the upload intent.");
+    }
+    await input.store.put(intent.objectKey, archive);
+    return { ...intent, used: true };
+}
+export function validateSourceManifest(manifest) {
+    if (manifest.schema !== "harbour.source-manifest/1.0" || !safeId(manifest.tenantId) || !safeId(manifest.appId) || !safeId(manifest.operationId)) {
+        throw new Error("SOURCE_MANIFEST_INVALID: manifest identity is invalid.");
+    }
+    if (!/^sha256:[a-f0-9]{64}$/i.test(manifest.graphDigest) || !/^sha256:[a-f0-9]{64}$/i.test(manifest.manifestDigest) || manifest.files.length === 0) {
+        throw new Error("SOURCE_MANIFEST_INVALID: manifest must have a digest and at least one file.");
+    }
+    const paths = new Set();
+    for (const file of manifest.files) {
+        if (!safeSourcePath(file.path) || paths.has(file.path) || !/^sha256:[a-f0-9]{64}$/i.test(file.sha256) || !Number.isSafeInteger(file.bytes) || file.bytes < 0) {
+            throw new Error("SOURCE_MANIFEST_INVALID: manifest contains an unsafe or duplicate file.");
+        }
+        paths.add(file.path);
+    }
+}
+export async function validateSourceArchive(archive) {
+    if (archive.schema !== "harbour.source-archive/1.0")
+        throw new Error("SOURCE_ARCHIVE_INVALID: unsupported archive schema.");
+    validateSourceManifest(archive.manifest);
+    const expectedArchiveDigest = await sha256({ schema: archive.schema, manifest: archive.manifest, files: archive.files });
+    if (archive.archiveDigest !== expectedArchiveDigest)
+        throw new Error("SOURCE_ARCHIVE_DIGEST_MISMATCH: archive digest does not match its contents.");
+    const expectedManifestDigest = await sha256({ schema: archive.manifest.schema, tenantId: archive.manifest.tenantId, appId: archive.manifest.appId, operationId: archive.manifest.operationId, graphDigest: archive.manifest.graphDigest, files: archive.manifest.files });
+    if (archive.manifest.manifestDigest !== expectedManifestDigest)
+        throw new Error("SOURCE_MANIFEST_DIGEST_MISMATCH: manifest digest does not match its contents.");
+    if (archive.files.length !== archive.manifest.files.length)
+        throw new Error("SOURCE_ARCHIVE_INCOMPLETE: archive file count does not match its manifest.");
+    const files = new Map(archive.files.map(file => [file.path, file]));
+    for (const expected of archive.manifest.files) {
+        const actual = files.get(expected.path);
+        if (!actual || !safeSourcePath(actual.path))
+            throw new Error("SOURCE_ARCHIVE_INCOMPLETE: a manifest file is missing from the archive.");
+        const bytes = base64ToBytes(actual.contentBase64);
+        if (bytes.byteLength !== expected.bytes || await sha256Bytes(bytes) !== expected.sha256) {
+            throw new Error("SOURCE_ARCHIVE_FILE_DIGEST_MISMATCH: archived file does not match the manifest.");
+        }
+    }
+}
+/** Safe to persist as evidence: no source content, archive key, or secret values. */
+export function sourceArchiveEvidence(archive) {
+    return { manifestDigest: archive.manifest.manifestDigest, archiveDigest: archive.archiveDigest, fileCount: archive.manifest.files.length, totalBytes: archive.manifest.files.reduce((sum, file) => sum + file.bytes, 0) };
+}
+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);
+}
+function toBytes(value) { return typeof value === "string" ? new TextEncoder().encode(value) : value; }
+function bytesToBase64(bytes) { return Buffer.from(bytes).toString("base64"); }
+function base64ToBytes(value) {
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value))
+        throw new Error("SOURCE_ARCHIVE_INVALID: file is not valid base64.");
+    return new Uint8Array(Buffer.from(value, "base64"));
+}
+function clone(value) { return JSON.parse(stableJson(value)); }

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@fourier-labs/harbour",
+  "version": "0.1.2",
+  "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-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"],
+  "engines": { "node": ">=22.13.0" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "pack:check": "npm pack --dry-run"
+  }
+}