@isomorph.ai/cli 0.2.0

package/dist/src/contracts.js

@@ -0,0 +1,82 @@
+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 = "Isomorph 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 Isomorph console — I'll continue once they're set.`;
+}
+/** 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 Isomorph 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);
+}
+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 !== "isomorph.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");
+    // 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");
+    }
+    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/secret-paths.js

@@ -0,0 +1,38 @@
+/**
+ * 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);
+}
+/**
+ * The development kit commits exactly these files under `.isomorph`: the
+ * integrations declaration, the kit lock, the governed-AI inventory, and the
+ * journey checks directly in `.isomorph/checks/` as `.mjs`, `.js` or `.cjs`
+ * modules (no subdirectories, no other extensions — evidence and reports
+ * written next to them stay local). Everything else there (local state,
+ * generated control files) stays local.
+ */
+export function isKitCommittedPath(path) {
+    return /(^|\/)\.isomorph\/(?:integrations\.json|kit\.lock\.json|ai-inventory\.json|checks\/[^/]+\.(?:mjs|js|cjs))$/.test(path);
+}
+/**
+ * Dependency and internal directories the intake never stages: `node_modules`,
+ * `.git`, the pipeline's own `.harbour` (receipts and derived artifacts, never
+ * an app's), and `.isomorph` except its committed kit files.
+ */
+export function isInternalSourcePath(path) {
+    return /(^|\/)(?:node_modules|\.git|\.harbour)(?:\/|$)/i.test(path) || (/(^|\/)\.isomorph(?:\/|$)/i.test(path) && !isKitCommittedPath(path));
+}

package/dist/src/source-intake.js

@@ -0,0 +1,125 @@
+import { sha256, sha256Bytes, stableJson } from "./digest.js";
+import { isInternalSourcePath, isProhibitedSecretPath } from "./secret-paths.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 exists(objectKey) { return this.archives.has(objectKey); }
+    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: "isomorph.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 !== "isomorph.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 === "..")
+        // Checked-in env templates are configuration metadata, not runtime
+        // credentials. All other env variants remain excluded before staging.
+        && !isProhibitedSecretPath(path)
+        && !isInternalSourcePath(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,43 @@
+{
+  "name": "@isomorph.ai/cli",
+  "version": "0.2.0",
+  "description": "Isomorph development kit CLI",
+  "type": "module",
+  "bin": {
+    "isomorph": "./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/secret-paths.js",
+    "dist/src/source-intake.js",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "embedded-postgres": "18.4.0-beta.17"
+  },
+  "scripts": {
+    "prebuild": "node scripts/kit-bundle.mjs verify",
+    "build": "tsc -p tsconfig.json",
+    "kit-bundle:sync": "node scripts/kit-bundle.mjs sync",
+    "pack:check": "npm pack --dry-run"
+  },
+  "harbour": {
+    "kitBundle": {
+      "repository": "public.ecr.aws/y6t4p3i8/harbour-kit-bundle",
+      "version": "0.2.0"
+    }
+  }
+}