@fourier-labs/harbour 0.1.13 → 0.1.14

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

@@ -0,0 +1,151 @@
+import { basename } from "node:path";
+import { linkIdempotencyKey, OPERATIONS, readDeclaration, readKitLock, requestResources, writeKitLock, newKitLock } from "./kit.js";
+import { CliError } from "./output.js";
+export class GovernanceClient {
+    apiUrl;
+    token;
+    tenantId;
+    fetchImpl;
+    constructor(apiUrl, token, tenantId, fetchImpl = fetch) {
+        this.apiUrl = apiUrl;
+        this.token = token;
+        this.tenantId = tenantId;
+        this.fetchImpl = fetchImpl;
+    }
+    link(input) {
+        return this.call("POST", "/v1/development/apps/link", { tenantId: this.tenantId, ...input });
+    }
+    request(appId, input) {
+        return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/integration-requests`, { tenantId: this.tenantId, ...input });
+    }
+    list(appId) {
+        return this.call("GET", `/v1/development/apps/${encodeURIComponent(appId)}/integrations?tenantId=${encodeURIComponent(this.tenantId)}`);
+    }
+    execute(appId, body) {
+        return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/integrations/execute`, body);
+    }
+    async call(method, path, body) {
+        const response = await this.fetchImpl(`${this.apiUrl.replace(/\/$/, "")}${path}`, { method, headers: { authorization: `Bearer ${this.token}`, "x-harbour-tenant": this.tenantId, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: "error" });
+        const parsed = await response.json().catch(() => ({}));
+        if (response.status === 401)
+            throw new CliError("AUTH_REQUIRED", "Please sign in to Harbour with `harbour login`.");
+        if (!response.ok)
+            throw new CliError(parsed.error?.details?.code ?? parsed.error?.category ?? `HTTP_${response.status}`, parsed.error?.message ?? "Harbour governance rejected the request.");
+        return (parsed.data ?? parsed);
+    }
+}
+/** Links the app once (stable idempotency key) and records the appId in kit.lock. */
+export async function ensureLinkedApp(root, client, tenantId, bundle) {
+    const lock = (await readKitLock(root)) ?? newKitLock(bundle, tenantId);
+    if (lock.appId)
+        return lock.appId;
+    const linked = await client.link({ displayName: basename(root), idempotencyKey: linkIdempotencyKey(tenantId, root) });
+    if (!linked.appId)
+        throw new CliError("LINK_FAILED", "Harbour did not return an app identity for this app.");
+    await writeKitLock(root, { ...lock, appId: linked.appId, tenantId });
+    return linked.appId;
+}
+/**
+ * One request per identity mode from the declaration's scope (or the named subset).
+ * Polls the grant list for up to 30 s; PENDING is reported as pending, never as ready.
+ */
+export async function requestIntegrations(root, client, tenantId, bundle, options) {
+    const { declaration, errors } = await readDeclaration(root);
+    if (errors.length)
+        throw new CliError("DECLARATION_INVALID", `.harbour/integrations.json is invalid: ${errors[0]}`);
+    const environment = options.environment ?? "development";
+    if (!["development", "preview", "production"].includes(environment))
+        throw new CliError("USAGE", "--environment must be development, preview or production.");
+    if (!options.reason.trim())
+        throw new CliError("USAGE", "--reason <text> is required.");
+    if (options.expiresAt && Number.isNaN(Date.parse(options.expiresAt)))
+        throw new CliError("USAGE", "--expires-at must be an ISO-8601 UTC timestamp.");
+    const scope = requestScope(declaration, options.connection, options.operations);
+    const appId = await ensureLinkedApp(root, client, tenantId, bundle);
+    const submitted = await Promise.all(scope.map(async (part) => ({ ...part, ...await client.request(appId, { connection: options.connection, environment, identityMode: part.identityMode, operations: part.operations, resources: part.resources, ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}), reason: options.reason }) })));
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const pollMs = options.pollMs ?? 3_000;
+    let grants = [];
+    for (let waited = 0; submitted.some(item => item.state === "PENDING") && waited < 30_000; waited += pollMs) {
+        await sleep(pollMs);
+        grants = (await client.list(appId)).grants;
+        for (const item of submitted) {
+            const grant = grants.find(candidate => candidate.grantId === item.grantId);
+            if (grant?.readiness === "ready")
+                item.state = "READY";
+        }
+    }
+    return { appId, connection: options.connection, environment, requests: submitted.map(item => ({ identityMode: item.identityMode, operations: item.operations, resources: item.resources, requestId: item.requestId, grantId: item.grantId, state: item.state, readiness: grants.find(grant => grant.grantId === item.grantId)?.readiness ?? (item.state === "READY" ? "ready" : item.state === "PENDING" ? "pending" : "denied") })) };
+}
+/**
+ * `productionise` pre-check: the preview deploy holds until every declared
+ * connection has a GRANTED, unexpired preview grant per identity mode, so the
+ * CLI checks first and names the exact request to make. Links the app when
+ * needed (same idempotency key as `integrations request`) so both commands
+ * share one appId. Returns the kit appId, or undefined for a non-kit app.
+ */
+export async function assertPreviewIntegrationsReady(root, client, tenantId, bundle, output) {
+    const lock = await readKitLock(root);
+    const { declaration, errors } = await readDeclaration(root);
+    if (errors.length) {
+        if (errors[0].startsWith(".harbour/integrations.json is missing"))
+            return lock?.appId || undefined;
+        throw new CliError("DECLARATION_INVALID", `.harbour/integrations.json is invalid: ${errors[0]}`);
+    }
+    const connections = Object.keys(declaration.connections);
+    if (!connections.length)
+        return lock?.appId || undefined;
+    const appId = await ensureLinkedApp(root, client, tenantId, bundle);
+    const grants = (await client.list(appId)).grants;
+    const nowMs = Date.now();
+    const missing = [];
+    for (const connection of connections) {
+        for (const { identityMode } of requestScope(declaration, connection)) {
+            const grant = grants.find(candidate => candidate.connection === connection && candidate.environment === "preview" && candidate.identityMode === identityMode);
+            const why = !grant ? "no preview grant requested"
+                : grant.status !== "GRANTED" ? `preview grant is ${grant.status}${grant.readiness === "pending" ? " (waiting for IT)" : ""}`
+                    : grant.expiresAt && Date.parse(grant.expiresAt) <= nowMs ? `preview grant expired ${grant.expiresAt}`
+                        : grant.readiness === "pending" || grant.readiness === "failed" ? `preview grant is ${grant.readiness}`
+                            : undefined;
+            if (why)
+                missing.push({ connection, identityMode, why });
+        }
+    }
+    if (!missing.length)
+        return appId;
+    const unresolved = [...new Set(missing.map(item => item.connection))];
+    output(`Harbour cannot deploy the preview yet: ${missing.length} integration grant${missing.length === 1 ? " is" : "s are"} missing.`);
+    for (const item of missing)
+        output(`  ${item.connection} (${item.identityMode} identity): ${item.why}`);
+    output("Request each one, then rerun productionise:");
+    for (const connection of unresolved)
+        output(`  harbour integrations request ${connection} --environment preview --reason "<why>" --app-root ${root}`);
+    throw new CliError("INTEGRATIONS_NOT_READY", `Preview grants are missing for ${unresolved.join(", ")}. Run the \`harbour integrations request … --environment preview\` commands above, then rerun productionise.`);
+}
+/** Splits the declared operations of one connection by identity mode. */
+export function requestScope(declaration, connection, only) {
+    const declared = declaration.connections[connection];
+    if (!declared)
+        throw new CliError("CONNECTION_NOT_DECLARED", `${connection} is not declared in .harbour/integrations.json.`);
+    const names = (only?.length ? only : Object.keys(declared.operations));
+    const unknown = names.filter(name => !declared.operations[name]);
+    if (unknown.length)
+        throw new CliError("OPERATION_NOT_DECLARED", `${unknown.join(", ")} not declared for ${connection}.`);
+    const byMode = new Map();
+    for (const name of names) {
+        const mode = OPERATIONS[name].identity;
+        const entry = byMode.get(mode) ?? { operations: [], resources: new Map() };
+        entry.operations.push(name);
+        for (const resource of requestResources(declared.operations[name]))
+            entry.resources.set(typeof resource === "string" ? resource : resource.name, resource);
+        byMode.set(mode, entry);
+    }
+    return [...byMode.entries()].map(([identityMode, entry]) => ({ identityMode, operations: entry.operations, resources: [...entry.resources.keys()].sort().map(key => entry.resources.get(key)) }));
+}
+export async function integrationsStatus(root, client) {
+    const lock = await readKitLock(root);
+    if (!lock?.appId)
+        return { linked: false, grants: [], requests: [] };
+    const listed = await client.list(lock.appId);
+    return { appId: lock.appId, linked: true, grants: listed.grants.map(grant => ({ connection: grant.connection, environment: grant.environment, identityMode: grant.identityMode, status: grant.status, operations: grant.operations, resources: grant.resources, expiresAt: grant.expiresAt, readiness: grant.readiness, pendingRequestId: grant.pendingRequestId })), requests: listed.requests };
+}

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

@@ -0,0 +1,63 @@
+import { readFile } from "node:fs/promises";
+/**
+ * The bundle this CLI was released with: `manifest.json` from the
+ * harbour-deployment-data-plane `publish-kit-bundle` run for this kit version,
+ * copied verbatim (the images and the tarball live in the kit's public
+ * registry, `public.ecr.aws/<alias>/`, pinned by digest so no login and no
+ * tag can substitute other bytes). `harbour init` records it in the app's
+ * kit.lock; `harbour init --upgrade` shows the digest diff against it; the
+ * hosted pipeline compares `sdk.tarballSha256` with the SDK it bakes.
+ */
+export const EMBEDDED_KIT_BUNDLE = {
+    schema: "harbour.kit-bundle/1.0",
+    kitVersion: "0.1.14",
+    sdk: {
+        package: "@harbour/app-sdk",
+        version: "1.0.0",
+        tarballSha256: "62954161ec29148c20223316d83367b781dd9291665ea16f74a003b16e304a3b",
+        url: "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:62954161ec29148c20223316d83367b781dd9291665ea16f74a003b16e304a3b"
+    },
+    images: {
+        appGateway: "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:387f51c7a824fc839044a2582fc3271acf2ff2b704d9ca6bb6d1edb06a845def",
+        sessionFixture: "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:a64025be110e592927b5c2a1ef5312e24624208e9427e74deb3873453512b0ca",
+        postgres: "postgres:16-alpine",
+        minio: "minio/minio:RELEASE.2025-07-23T15-54-02Z",
+        nats: "nats:2.11.17-alpine"
+    },
+    brief: { fingerprint: "ebc897c539526c5537017b49b99dc970053ba9999e346029883e96d61b98ef13" },
+    declarationSchema: "harbour.app-integrations/2.0"
+};
+/** The manifest the CLI ships with, or the one named by HARBOUR_KIT_BUNDLE for local testing against unreleased images. */
+export async function loadKitBundle(env = process.env) {
+    const override = env.HARBOUR_KIT_BUNDLE?.trim();
+    if (!override)
+        return EMBEDDED_KIT_BUNDLE;
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(override, "utf8"));
+    }
+    catch {
+        throw new Error(`HARBOUR_KIT_BUNDLE does not point at a readable manifest: ${override}`);
+    }
+    if (!isKitBundle(parsed))
+        throw new Error("HARBOUR_KIT_BUNDLE is not a harbour.kit-bundle/1.0 manifest.");
+    return { ...EMBEDDED_KIT_BUNDLE, ...parsed, images: { ...EMBEDDED_KIT_BUNDLE.images, ...parsed.images } };
+}
+export function isKitBundle(value) {
+    const record = value;
+    return Boolean(record && typeof record === "object" && record.schema === "harbour.kit-bundle/1.0" && typeof record.kitVersion === "string"
+        && record.sdk && typeof record.sdk.package === "string" && typeof record.sdk.tarballSha256 === "string"
+        && record.images && typeof record.images.appGateway === "string" && typeof record.images.sessionFixture === "string"
+        && record.brief && typeof record.brief.fingerprint === "string" && record.declarationSchema === "harbour.app-integrations/2.0");
+}
+/** Lines naming every digest that differs between two manifests, for `init --upgrade`. */
+export function bundleDiff(before, after) {
+    const fields = [
+        ["kitVersion", before.kitVersion, after.kitVersion],
+        ["sdk.tarballSha256", before.sdk.tarballSha256, after.sdk.tarballSha256],
+        ["images.appGateway", before.images.appGateway, after.images.appGateway],
+        ["images.sessionFixture", before.images.sessionFixture, after.images.sessionFixture],
+        ["brief.fingerprint", before.brief.fingerprint, after.brief.fingerprint]
+    ];
+    return fields.filter(([, a, b]) => a !== b).map(([name, a, b]) => `${name}: ${a ?? "(none)"} -> ${b ?? "(none)"}`);
+}

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

@@ -0,0 +1,167 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+import { scanWorkspace } from "../../../src/analyzer.js";
+import { isKitBundle } from "./kit-bundle.js";
+import { CliError } from "./output.js";
+/** Closed set: each operation has exactly one identity mode and one connection kind. Gmail is read-only and user-mode only. */
+export const OPERATIONS = {
+    "slack.channel.history": { identity: "user", kind: "saas" },
+    "slack.message.post": { identity: "app", kind: "saas" },
+    "gmail.thread.list": { identity: "user", kind: "saas" },
+    "gmail.message.read": { identity: "user", kind: "saas" },
+    "warehouse.view.read": { identity: "app", kind: "database" }
+};
+/** Explicit reads `harbour check --integrations` may run; every other operation is a send and never runs during checks. */
+export const READ_OPERATIONS = ["slack.channel.history", "gmail.thread.list", "warehouse.view.read"];
+/** Reads whose input needs an identifier from a prior read (a message id): listed as reads, exercised only through the list. */
+export const DEPENDENT_READ_OPERATIONS = ["gmail.message.read"];
+const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/** Validates the committed declaration; every error names the path that broke the closed rules. */
+export function validateDeclaration(value) {
+    const errors = [];
+    const record = (value ?? {});
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { declaration: emptyDeclaration(), errors: ["declaration must be a JSON object"] };
+    if (record.schema !== "harbour.app-integrations/2.0")
+        errors.push("schema must be harbour.app-integrations/2.0");
+    const connections = record.connections && typeof record.connections === "object" && !Array.isArray(record.connections) ? record.connections : undefined;
+    if (!connections)
+        errors.push("connections must be an object keyed by connection alias");
+    for (const [alias, connection] of Object.entries(connections ?? {})) {
+        if (!LOGICAL_NAME.test(alias))
+            errors.push(`connections.${alias}: alias must be a lowercase logical name`);
+        if (!connection || typeof connection !== "object") {
+            errors.push(`connections.${alias}: must be an object`);
+            continue;
+        }
+        if (connection.kind !== "saas" && connection.kind !== "database")
+            errors.push(`connections.${alias}.kind: must be saas or database`);
+        const operations = connection.operations && typeof connection.operations === "object" ? connection.operations : undefined;
+        if (!operations || !Object.keys(operations).length) {
+            errors.push(`connections.${alias}.operations: at least one operation is required`);
+            continue;
+        }
+        for (const [name, operation] of Object.entries(operations)) {
+            const path = `connections.${alias}.operations.${name}`;
+            const rule = OPERATIONS[name];
+            if (!rule) {
+                errors.push(`${path}: unsupported operation (allowed: ${Object.keys(OPERATIONS).join(", ")})`);
+                continue;
+            }
+            if (rule.kind !== connection.kind)
+                errors.push(`${path}: ${name} belongs to a ${rule.kind} connection`);
+            if (operation?.identity !== rule.identity)
+                errors.push(`${path}.identity: ${name} is always ${rule.identity}`);
+            const resources = operation?.resources;
+            if (name === "warehouse.view.read") {
+                if (!resources || Array.isArray(resources) || typeof resources !== "object" || !Object.keys(resources).length)
+                    errors.push(`${path}.resources: must map view names to {columns}`);
+                else
+                    for (const [view, spec] of Object.entries(resources)) {
+                        if (!LOGICAL_NAME.test(view))
+                            errors.push(`${path}.resources.${view}: view name must be a logical name`);
+                        if (!spec || !Array.isArray(spec.columns) || !spec.columns.length || spec.columns.length > 32 || spec.columns.some(column => typeof column !== "string" || !LOGICAL_NAME.test(column)))
+                            errors.push(`${path}.resources.${view}.columns: 1..32 column names are required`);
+                    }
+            }
+            else if (!Array.isArray(resources) || !resources.length || resources.some(resource => typeof resource !== "string" || !LOGICAL_NAME.test(resource)))
+                errors.push(`${path}.resources: must be a non-empty list of logical resource names (no IDs, tokens or URLs)`);
+        }
+    }
+    return { declaration: record, errors };
+}
+export function emptyDeclaration() { return { schema: "harbour.app-integrations/2.0", connections: {} }; }
+export function resourceNames(operation) { return Array.isArray(operation.resources) ? operation.resources : Object.keys(operation.resources); }
+export function requestResources(operation) {
+    return Array.isArray(operation.resources) ? operation.resources : Object.entries(operation.resources).map(([name, spec]) => ({ name, columns: [...spec.columns] }));
+}
+export async function readDeclaration(root) {
+    let raw;
+    try {
+        raw = await readFile(kitPaths(root).declaration, "utf8");
+    }
+    catch {
+        return { declaration: emptyDeclaration(), errors: [".harbour/integrations.json is missing (run `harbour init`)"] };
+    }
+    try {
+        return validateDeclaration(JSON.parse(raw));
+    }
+    catch {
+        return { declaration: emptyDeclaration(), errors: [".harbour/integrations.json is not valid JSON"] };
+    }
+}
+export function isKitLock(value) {
+    const record = value;
+    return Boolean(record && typeof record === "object" && record.schema === "harbour.kit-lock/1.0" && typeof record.appId === "string" && typeof record.tenantId === "string" && isKitBundle(record.bundle) && typeof record.createdAt === "string" && typeof record.updatedAt === "string");
+}
+export async function readKitLock(root) {
+    let raw;
+    try {
+        raw = await readFile(kitPaths(root).lock, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("KIT_LOCK_INVALID", ".harbour/kit.lock.json is not valid JSON.");
+    }
+    if (!isKitLock(parsed))
+        throw new CliError("KIT_LOCK_INVALID", ".harbour/kit.lock.json does not match harbour.kit-lock/1.0.");
+    return parsed;
+}
+export async function writeKitLock(root, lock) {
+    const next = { ...lock, updatedAt: new Date().toISOString() };
+    await mkdir(dirname(kitPaths(root).lock), { recursive: true });
+    await writeFile(kitPaths(root).lock, `${JSON.stringify(next, null, 2)}\n`);
+    return next;
+}
+/** Records the app identity Harbour settled on; a non-kit app (no kit.lock) is left alone. */
+export async function recordKitAppId(root, appId, tenantId) {
+    const lock = await readKitLock(root);
+    if (!lock || (lock.appId === appId && lock.tenantId === tenantId))
+        return;
+    await writeKitLock(root, { ...lock, appId, tenantId });
+}
+export function newKitLock(bundle, tenantId = "", appId = "") {
+    const now = new Date().toISOString();
+    return { schema: "harbour.kit-lock/1.0", appId, tenantId, bundle, createdAt: now, updatedAt: now };
+}
+// ---- Paths and identity --------------------------------------------------------
+export function appRoot(rootArg) {
+    if (!rootArg)
+        throw new CliError("USAGE", "--app-root <path> is required.");
+    const root = resolve(rootArg);
+    if (root === parse(root).root || root === resolve(homedir()))
+        throw new CliError("PREFLIGHT_APP_ROOT", "The selected app root is unsafe.");
+    return root;
+}
+export function kitPaths(root) {
+    const harbour = join(root, ".harbour");
+    const local = join(harbour, "local");
+    return { harbour, local, declaration: join(harbour, "integrations.json"), lock: join(harbour, "kit.lock.json"), checks: join(harbour, "checks"), compose: join(local, "compose.yml"), gatewayConfig: join(local, "app-gateway.json"), devLock: join(local, "dev.lock"), state: join(local, "state"), report: join(local, "check-report.json") };
+}
+/** Stable per-project identity for Compose projects and volumes: `harbour-<12 hex of sha256(abs root)>`. */
+export function projectName(root, suffix = "") {
+    return `harbour-${createHash("sha256").update(resolve(root)).digest("hex").slice(0, 12)}${suffix}`;
+}
+/** Governance link idempotency key: sha256(tenantId + absolute app root). */
+export function linkIdempotencyKey(tenantId, root) {
+    return createHash("sha256").update(`${tenantId}${resolve(root)}`).digest("hex");
+}
+/** sha256 over the tracked app files (same boundary as productionise), so any edit changes it. */
+export async function sourceDigest(root) {
+    const graph = await scanWorkspace(root, { sourceBoundary: "root" });
+    const files = [...graph.deploymentScope.includedFiles].sort();
+    const hash = createHash("sha256");
+    for (const path of files) {
+        hash.update(path).update("\0");
+        hash.update(await readFile(join(root, path))).update("\0");
+    }
+    return { digest: `sha256:${hash.digest("hex")}`, files };
+}