@fourier-labs/harbour 0.1.33 → 0.1.34

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

@@ -17,7 +17,7 @@ export async function initKit(root, bundle, options = {}) {
     const emptyDir = !existingPackage && !(await exists(join(root, "src")));
     if (existingPackage && !isSupportedApp(existingPackage))
         throw new CliError("APP_UNSUPPORTED", "harbour init supports an empty directory or an existing Vite + React app (package.json must depend on vite and react).");
-    const result = { root, created: [], kept: [], updated: [], mode: options.upgrade ? "upgrade" : emptyDir ? "starter" : "existing", bundleChanges: [], agents: options.env ? await agentSetup(options.env) : { created: [], updated: [], kept: [] } };
+    const result = { root, created: [], kept: [], updated: [], mode: options.upgrade ? "upgrade" : emptyDir ? "starter" : "existing", bundleChanges: [], agents: options.env ? await agentSetup(options.env) : { created: [], updated: [], kept: [], removed: [] } };
     const write = async (path, content) => {
         const absolute = join(root, path);
         if (await exists(absolute)) {
@@ -92,7 +92,7 @@ export function managedBlock() {
         "",
         "- Identity, data and files go through `@harbour/app-sdk` only: `harbour.identity.current()`, `harbour.data.from(table)`, `harbour.files.*`. Never open a database, storage bucket or company system from browser code, and never `fetch` a company URL directly.",
         "- Company systems (Slack, Gmail, warehouse views) are reached only through `harbour.integrations.execute(connection, {operation, resource, input})` with the connection and operation declared in `.harbour/integrations.json`. Operations are a closed set: `slack.channel.history` (user identity), `slack.message.post` (declared per app: `app` posts as the company's Slack bot, Isomorph AI, under the name IT approved; `user` posts as the signed-in person after their consent), `gmail.thread.list`, `gmail.message.read` and `gmail.message.send` (user identity — reads and one plain-text send as the signed-in person, resource `inbox`), `warehouse.view.read` (app identity). Resources are logical names, never IDs, URLs or tokens.",
-        "- `.harbour/integrations.json` starts with `\"connections\": {}` and stays that way until the app really calls a company system. Adding one is two steps: declare the connection — by the identifier `harbour integrations catalog --app-root .` lists, with only the operations the app calls and only channels, views and mailboxes the catalog shows as approved; never a guessed name — then `harbour integrations request <connection> --reason \"<why>\" --app-root .` (and the same command with `--environment preview` before shipping). Every declared connection blocks the deploy until IT grants it, so a connection the app does not call is a deploy that never happens; a connection that is not declared cannot be requested at all (`CONNECTION_NOT_DECLARED`), so it never gets a grant. The file is strict JSON and cannot hold comments; the worked Slack and warehouse examples are in README.md and in the comment in `src/App.tsx`.",
+        "- `.harbour/integrations.json` starts with `\"connections\": {}` and stays that way until the app really calls a company system. Adding one is two steps: declare the connection — by the identifier `harbour integrations catalog --app-root .` lists, with only the operations the app calls and only channels, views and mailboxes the catalog shows as approved; never a guessed name — then `harbour integrations request <connection> --reason \"<why>\" --app-root .` (and the same command with `--environment preview` before shipping). Every declared connection blocks the deploy until IT grants it, so a connection the app does not call is a deploy that never happens; a connection that is not declared cannot be requested at all (`CONNECTION_NOT_DECLARED`), so it never gets a grant. Before a real integration test, read `harbour integrations status --app-root . --json`: show pending IT approval separately from personal consent, and test ready destinations independently. After a partial send, retry only the failed destination with its original idempotency key; do not regenerate or resend a successful destination. The file is strict JSON and cannot hold comments; the worked Slack and warehouse examples are in README.md and in the comment in `src/App.tsx`.",
         "- A Slack message is sent only after the person presses an explicit Send control; pass a fresh UUID `idempotencyKey` per send action and reuse the same key when retrying that action. Never send from an effect, a timer or a background queue, and never send during checks.",
         "- A Slack message is posted either as the app (the company's Slack bot, Isomorph AI, under the IT-approved name: declare `\"presentation\": { \"displayName\": \"<app name>\" }` on the Slack connection, optional `iconEmoji`; every app-mode post ends with \"Posted by <app> on Isomorph\") or as the person (`\"identity\": \"user\"` on `slack.message.post`, their own consent; an older consent answers `USER_RECONNECT_REQUIRED` — offer Connect again) — never pretend one is the other. The declaration is the mode you request access for; when the app is approved for both, every post says which with `mode: \"app\"` or `mode: \"user\"` on the call (`MODE_REQUIRED` otherwise), and a mode IT has not approved is refused with `MODE_NOT_GRANTED`, never swapped. A post needs the bot in the channel: `/invite @Isomorph AI` there first.",
         "- Consent is only for user-identity operations (`slack.channel.history`, `gmail.*`, and `slack.message.post` declared `\"identity\": \"user\"`): call `harbour.integrations.connect(connection)` and, when it returns `consent_required`, open `authorizationUrl`. App-identity operations (`slack.message.post` declared `\"identity\": \"app\"`, `warehouse.view.read`) never call connect — it is refused as unapproved user access. Missing consent never falls back to another account.",
@@ -105,7 +105,7 @@ export function managedBlock() {
         "- `.harbour/checks/` holds the app's retained journeys: one per capability the app's own code uses (`harbour.data.*`, `harbour.files.*`, actions, realtime, telemetry), plus a cross-user denial per owner-scoped table. `harbour check` generates them from `migrations/` and the app's own source and deletes the ones the app no longer needs, so the way to keep them right is to run it in the same edit that changes the app — not to write or remove these files by hand. The pairing is two-way and the `flow` gate refuses the deploy in both directions. Start using a capability and it needs its own retained check: `harbour check` writes it, except for the ones it reports it cannot generate (`actions`, `realtime`), which you write yourself. Stop using one — a deleted section, a dropped table, a feature the app no longer has — and its retained check must be deleted in that same edit: `harbour check` deletes the ones it generated, and one you wrote or edited is yours to delete, because `harbour check` and the deployment pipeline replay `.harbour/checks/` against a real App Gateway and refuse the app (`flow.check-failed: the candidate's own retained checks no longer pass`) when a check exercises something the code no longer does.",
         "- A generated check starts with a `// harbour:generated` line carrying a digest of its own body; that is how `harbour check` knows the file is still its to rewrite and remove. Edit one and it becomes yours: Harbour keeps your version, stops updating it and never deletes it, and keeping it honest is then your job. The starter's pairing is: `notes-journey.mjs` + `notes-cross-user.mjs` with the `notes` table and the Notes section of `src/App.tsx`; `files-journey.mjs` with the \"Private files\" section, the only code that calls `harbour.files.*`. Replace the notes table with the app's own, or remove the \"Private files\" section, and the next `harbour check` rewrites and deletes to match — `.harbour/checks/files-journey.mjs` goes with that section, and you delete it by hand in that same edit only if you have edited it. An inherited check for a feature the app replaced or dropped is the most common reason a first deploy is refused.",
         "- Commands: `harbour dev --app-root .` (local runtime), `harbour check --app-root .` (types, build, then the pipeline's own kit gate in the local session: declaration, migrations + database gate, write probe with cross-user denial, the generated journeys, operation coverage), `harbour integrations catalog --app-root .` (the company's connections and approved names, before declaring one), `harbour integrations request <connection> --reason <text> --app-root .`, `harbour integrations status --app-root .`, `harbour productionise --app-root .`. Company calls in `dev` use the account from `harbour login`; the local fixture user is only the app's identity.",
-        "- Codex reads this AGENTS.md block; Claude Code also reads `.claude/skills/harbour-kit/SKILL.md`. The plain-English workflow (what to run when the person says \"run it\", \"check it\", \"ship it\") is in the user-level `isomorph` skill / `~/.codex/AGENTS.md` block installed by `harbour agent-setup`.",
+        "- Codex reads this AGENTS.md block; Claude Code also reads `.claude/skills/harbour-kit/SKILL.md`. The plain-English workflow (what to run when the person says \"run it\", \"check it\", \"ship it\") is the user-level `isomorph` skill installed by `harbour agent-setup` (Claude Code: `~/.claude/skills/isomorph`, Codex: `~/.codex/skills/isomorph`); use it for every request about this app.",
         MANAGED_END
     ].join("\n");
 }
@@ -244,12 +244,12 @@ Add one in two steps, when the app really calls it:
 Then call it from the app through \`integrations()\` in \`src/harbour.client.ts\`:
 
 \`\`\`ts
-const report = await integrations().execute<{ rows: Array<{ week: string; total: number }> }>("sales-warehouse", {
+const report = await integrations().execute("sales-warehouse", {
   operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 }
 });
 \`\`\`
 
-A send (\`slack.message.post\`, \`gmail.message.send\`) runs only when the person presses an explicit Send control, with a fresh UUID \`idempotencyKey\` per press — never from an effect, a timer or a check. Consent is only for user-identity operations (\`slack.channel.history\`, \`gmail.*\`, and \`slack.message.post\` declared \`"identity": "user"\`): \`integrations().connect(connection)\`, and open its \`authorizationUrl\` when it answers \`consent_required\`; app-identity operations (\`slack.message.post\` declared \`"identity": "app"\`, \`warehouse.view.read\`) never call connect. Anything the app calls needs its own retained check under \`.harbour/checks/\`, and anything it stops calling loses its check in the same edit. A check that calls \`integrations().execute\` is answered by the gate's fixture — the contract's result shape for the declared connection, operation and resource, nothing sent or read, and the report says so; \`harbour check --integrations\` is what exercises real access.
+A send (\`slack.message.post\`, \`gmail.message.send\`) runs only from an explicit Send control, pressed by the person or by the AI tool for an explicitly authorized test, with a fresh UUID \`idempotencyKey\` per press — never from an effect, a timer or a check. Consent is only for user-identity operations (\`slack.channel.history\`, \`gmail.*\`, and \`slack.message.post\` declared \`"identity": "user"\`): \`integrations().connect(connection)\`, and open its \`authorizationUrl\` when it answers \`consent_required\`; app-identity operations (\`slack.message.post\` declared \`"identity": "app"\`, \`warehouse.view.read\`) never call connect. Anything the app calls needs its own retained check under \`.harbour/checks/\`, and anything it stops calling loses its check in the same edit. Keep request construction in an app function that both the button and its retained check call, so the check exercises the actual payload. Do not bypass the SDK types with a generic string/unknown wrapper. A check that calls \`integrations().execute\` is answered by the gate's fixture — the contract's result shape for the declared connection, operation and resource, nothing sent or read, and the report says so; \`harbour check --integrations\` is what exercises real access.
 `;
 const VITE_CONFIG = `import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
@@ -268,33 +268,23 @@ export default defineConfig({
   }
 });
 `;
-const HARBOUR_CLIENT = `import { createClient, type IntegrationRequest } from "@harbour/app-sdk";
+const HARBOUR_CLIENT = `import { createClient } from "@harbour/app-sdk";
 
 // Single client for the whole app. Identity, data and files come from Harbour;
 // the same calls work locally (harbour dev) and in preview/production.
 export const harbour = createClient();
 
-export type ConnectResult = { status: "connected"; accountLabel: string } | { status: "consent_required"; authorizationUrl: string };
-// The SDK's per-operation request types carry each input's bound (e.g. slack.channel.history limit: 1 to 15);
-// the second member keeps an operation the SDK has not typed yet (gmail.*) callable until it is.
-export type IntegrationCall = IntegrationRequest | { operation: string; resource: string; input: unknown; idempotencyKey?: string };
-export type Integrations = {
-  connect(connection: string): Promise<ConnectResult>;
-  disconnect(connection: string): Promise<{ status: "disconnected" }>;
-  execute<T>(connection: string, call: IntegrationCall): Promise<T>;
-};
+// Keep the SDK's operation-specific inputs and inferred results intact.
+export type Integrations = typeof harbour.integrations;
+export function integrations(): Integrations { return harbour.integrations; }
 
-/**
- * Typed access to the SDK's integrations surface (kit bundle SDK); throws a clear
- * error on an older SDK. The starter calls no company system, so nothing uses this
- * yet: it is the entry point for the first one you add (declare the connection in
- * .harbour/integrations.json, then \`harbour integrations request\` — see README.md).
- */
-export function integrations(): Integrations {
-  const surface = (harbour as { integrations?: Integrations }).integrations;
-  if (!surface) throw new Error("This @harbour/app-sdk build has no integrations surface; run harbour init --upgrade.");
-  return surface;
-}
+// Gmail sends plain text as the signed-in person, after IT approval and personal consent.
+// Inside an authorized Send handler (use the catalog's actual connection and mailbox):
+// await integrations().execute("company-gmail", {
+//   operation: "gmail.message.send", resource: "inbox",
+//   input: { to: ["recipient@example.com"], subject: "Update", text: "Your message" },
+//   idempotencyKey: crypto.randomUUID()
+// });
 
 export type AiMessage = { role: "system" | "user" | "assistant"; content: string };
 export type AiChatResult = { content: string; model: string; finishReason: string; usage: { inputTokens: number; outputTokens: number }; traceId?: string };
@@ -373,10 +363,10 @@ export function App() {
   // 2. Request access (harbour integrations request sales-warehouse --reason "<why>" --app-root .,
   //    and again with --environment preview before harbour productionise), then import
   //    { integrations } from "./harbour.client" and uncomment:
-  // const report = await integrations().execute<{ rows: Array<{ week: string; total: number }> }>("sales-warehouse", {
+  // const report = await integrations().execute("sales-warehouse", {
   //   operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 }
   // });
-  // A Slack send runs only when the person presses an explicit Send control, with a
+  // A Slack send runs only from an explicit Send control, pressed by the person or by the AI tool for an explicitly authorized test, with a
   // fresh UUID idempotencyKey per press — never from an effect, a timer or a check.
   //
   // Governed AI is not part of the starter either. When the person asks for it, add ONE

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.33";
+export const CLI_VERSION = "0.1.34";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": {
@@ -25,6 +25,9 @@
   "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",
@@ -34,7 +37,7 @@
   "harbour": {
     "kitBundle": {
       "repository": "public.ecr.aws/y6t4p3i8/harbour-kit-bundle",
-      "version": "0.1.33"
+      "version": "0.1.34"
     }
   }
 }

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

@@ -1,126 +0,0 @@
-import { dirname } from "node:path";
-/**
- * Docker's bridge address pool. Every `harbour dev` / `harbour check` project
- * is a Compose project with its own bridge network, and the engine's default
- * pool holds only ~31 of them (Docker Desktop and colima: 172.17-172.31/16 plus
- * 192.168.0.0/16 cut into /20s). Once it is full, `compose up` fails to create
- * the network before a single container starts — a "Docker could not start"
- * that has nothing to do with the app. This module names that failure, reclaims
- * the networks Harbour itself left behind (projects of other app roots with no
- * running container) and, when that is not enough, says what only the person
- * can do.
- */
-/** The network label every Harbour compose project carries (compose puts it on the project's default network). */
-export const HARBOUR_NETWORK_LABEL = "com.harbour.kit";
-/** The engine's wording for an exhausted pool, across versions and the compose wrapper. */
-const POOL_EXHAUSTED = /all predefined address pools have been fully subnetted|could not find an available,? non-overlapping IPv4 address pool|no available IPv4 addresses on this network'?s address pools|could not allocate an IPv4 subnet/i;
-export function isAddressPoolExhausted(stderr) { return POOL_EXHAUSTED.test(stderr); }
-/** The name Harbour gives its compose projects: `harbour-<12 hex>` (+ `-check`) — the recognition rule for projects created before the network label existed. */
-const HARBOUR_PROJECT = /^harbour-[0-9a-f]{12}(?:-check)?$/;
-/**
- * Every compose project on this machine that Harbour created: networks that
- * carry the Harbour label or (older CLIs) the Harbour project-name pattern.
- * Networks without a compose project label are never listed — a network some
- * other tool made is not Harbour's to touch.
- */
-export async function listHarbourProjects(run) {
-    const networks = await run("docker", ["network", "ls", "--filter", "label=com.docker.compose.project", "--format", "{{.Name}}\t{{.Labels}}"], { quiet: true });
-    if (networks.code !== 0)
-        return [];
-    const roots = await projectRoots(run);
-    const projects = [];
-    for (const line of networks.stdout.split("\n")) {
-        const [network, labels = ""] = line.trim().split("\t");
-        if (!network)
-            continue;
-        const project = labels.split(",").map(pair => pair.split("=")).find(([key]) => key === "com.docker.compose.project")?.[1];
-        if (!project)
-            continue;
-        const harbour = labels.split(",").some(pair => pair === `${HARBOUR_NETWORK_LABEL}=1`) || HARBOUR_PROJECT.test(project);
-        if (!harbour)
-            continue;
-        const containers = await run("docker", ["ps", "-a", "--filter", `label=com.docker.compose.project=${project}`, "--format", "{{.State}}"], { quiet: true });
-        const states = containers.code === 0 ? containers.stdout.split("\n").map(state => state.trim()).filter(Boolean) : [];
-        const running = states.filter(state => state === "running" || state === "restarting" || state === "paused").length;
-        projects.push({ project, network, root: roots.get(project), running, total: states.length });
-    }
-    return projects;
-}
-/** Project name -> app root, from the compose files compose still remembers (`<root>/.harbour/local/<compose>.yml`). */
-async function projectRoots(run) {
-    const roots = new Map();
-    const result = await run("docker", ["compose", "ls", "-a", "--format", "json"], { quiet: true });
-    if (result.code !== 0)
-        return roots;
-    let entries = [];
-    try {
-        entries = JSON.parse(result.stdout || "[]");
-    }
-    catch {
-        return roots;
-    }
-    for (const entry of entries) {
-        const file = entry.ConfigFiles?.split(",")[0]?.trim();
-        if (entry.Name && file && /[\\/]\.harbour[\\/]local[\\/][^\\/]+\.yml$/.test(file))
-            roots.set(entry.Name, dirname(dirname(dirname(file))));
-    }
-    return roots;
-}
-/**
- * Removes the containers and network of one Harbour project, keeping its
- * named volumes (the app's local data) unless `volumes` is set. `compose down`
- * needs no compose file for this — it works from the labels — and the network
- * is removed by name afterwards in case compose found no container to anchor on.
- */
-export async function downHarbourProject(run, project, volumes = false) {
-    const result = await run("docker", ["compose", "-p", project.project, "down", "--remove-orphans", ...(volumes ? ["-v"] : [])], { quiet: true });
-    const network = await run("docker", ["network", "rm", project.network], { quiet: true });
-    return result.code === 0 || network.code === 0;
-}
-/**
- * Self-heal: brings down every Harbour project other than `keep` whose
- * containers are all stopped (or gone), which frees their networks. A project
- * with a running container is another app someone is using — it is left alone
- * and named in the returned `running` list. Never touches non-Harbour networks.
- */
-export async function reclaimStaleHarbourProjects(run, keep, output) {
-    const reclaimed = [];
-    const running = [];
-    for (const project of await listHarbourProjects(run)) {
-        if (project.project === keep)
-            continue;
-        if (project.running > 0) {
-            running.push(project);
-            continue;
-        }
-        if (await downHarbourProject(run, project))
-            reclaimed.push(project);
-    }
-    if (reclaimed.length)
-        output?.(`Docker's network address pool was full; removed the stopped local services of ${reclaimed.length} other Harbour app${reclaimed.length === 1 ? "" : "s"} (their data volumes are kept) and retrying.`);
-    return { reclaimed, running };
-}
-/** The one sentence for a pool that is still full after the self-heal: the two remedies only the person can apply. */
-export function poolExhaustedMessage(running) {
-    const stops = running.map(project => `\`harbour stop --app-root ${project.root ?? `<app of compose project ${project.project}>`}\``);
-    const others = stops.length ? `stop the ${stops.length === 1 ? "other Harbour app that is" : `${stops.length} other Harbour apps that are`} still running (${stops.join(", ")}) or ` : "";
-    return `Docker has no network address left for this app's local services (every subnet in its default address pool is taken, none by a stopped Harbour app): ${others}free the pool with \`docker network prune\` (removes networks no container uses) or a wider \`default-address-pools\` in Docker's daemon settings, then rerun.`;
-}
-/**
- * `harbour stop --all`: brings down every Harbour project on this machine whose
- * containers are all stopped (data volumes kept); with `force`, the running
- * ones too. The complete remedy for a full pool when no single app is at fault.
- */
-export async function stopAllHarbourProjects(run, options = {}) {
-    const stopped = [];
-    const running = [];
-    for (const project of await listHarbourProjects(run)) {
-        if (project.running > 0 && !options.force) {
-            running.push(project);
-            continue;
-        }
-        if (await downHarbourProject(run, project))
-            stopped.push(project);
-    }
-    return { stopped, running };
-}