@fourier-labs/harbour 0.1.13 → 0.1.14

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

@@ -0,0 +1,390 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { bundleDiff } from "./kit-bundle.js";
+import { newKitLock, readKitLock, writeKitLock } from "./kit.js";
+import { CliError } from "./output.js";
+/**
+ * Creates the starter in an empty directory, or adds the missing kit files to
+ * an existing Vite + React app. User files are never overwritten: a path that
+ * exists is reported as kept. Instruction files get a managed block appended.
+ */
+export async function initKit(root, bundle, options = {}) {
+    await mkdir(root, { recursive: true });
+    const existingPackage = await readJson(join(root, "package.json"));
+    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: [] };
+    const write = async (path, content) => {
+        const absolute = join(root, path);
+        if (await exists(absolute)) {
+            result.kept.push(path);
+            return;
+        }
+        await mkdir(dirname(absolute), { recursive: true });
+        await writeFile(absolute, content);
+        result.created.push(path);
+    };
+    const appFiles = emptyDir ? starterFiles(bundle) : {};
+    for (const [path, content] of Object.entries({ ...appFiles, ...kitFiles() }))
+        await write(path, content);
+    await appendManaged(root, ".gitignore", GITIGNORE_LINES, result, "\n");
+    for (const file of ["CLAUDE.md", "AGENTS.md"])
+        await appendManaged(root, file, managedBlock(), result, "\n\n", MANAGED_START, MANAGED_END);
+    await write(".claude/skills/harbour-kit/SKILL.md", SKILL_FILE);
+    const previous = await readKitLock(root);
+    if (!previous) {
+        await writeKitLock(root, newKitLock(bundle, options.tenantId ?? ""));
+        result.created.push(".harbour/kit.lock.json");
+    }
+    else if (options.upgrade) {
+        result.bundleChanges = bundleDiff(previous.bundle, bundle);
+        if (result.bundleChanges.length) {
+            await writeKitLock(root, { ...previous, bundle });
+            result.updated.push(".harbour/kit.lock.json");
+        }
+        else
+            result.kept.push(".harbour/kit.lock.json");
+    }
+    else
+        result.kept.push(".harbour/kit.lock.json");
+    return result;
+}
+function isSupportedApp(pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return Boolean(deps.vite && deps.react);
+}
+async function appendManaged(root, file, block, result, separator, start, end) {
+    const absolute = join(root, file);
+    const current = await readFile(absolute, "utf8").catch(() => undefined);
+    if (current === undefined) {
+        await writeFile(absolute, `${block}\n`);
+        result.created.push(file);
+        return;
+    }
+    if (start && end && current.includes(start) && current.includes(end)) {
+        const next = current.replace(new RegExp(`${escape(start)}[\\s\\S]*?${escape(end)}`), block);
+        if (next !== current) {
+            await writeFile(absolute, next);
+            result.updated.push(file);
+        }
+        else
+            result.kept.push(file);
+        return;
+    }
+    if (!start && block.split("\n").every(line => current.split("\n").includes(line))) {
+        result.kept.push(file);
+        return;
+    }
+    await writeFile(absolute, `${current.replace(/\n*$/, "")}${separator}${block}\n`);
+    result.updated.push(file);
+}
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const exists = (path) => stat(path).then(() => true, () => false);
+const readJson = (path) => readFile(path, "utf8").then(text => JSON.parse(text), () => undefined);
+// ---- Templates -----------------------------------------------------------------
+export const MANAGED_START = "<!-- harbour:kit:start -->";
+export const MANAGED_END = "<!-- harbour:kit:end -->";
+const GITIGNORE_LINES = ["node_modules/", "dist/", ".harbour/local/"].join("\n");
+/** Condensed from the pipeline briefs (browser-sdk-to-harbour, route-auth-policy, auth-local-to-harbour-sso) for a kit app. */
+export function managedBlock() {
+    return [
+        MANAGED_START,
+        "## Harbour development kit",
+        "",
+        "This app runs on Harbour. Keep these rules; `harbour check` and the deployment pipeline enforce them.",
+        "",
+        "- 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` (app identity), `gmail.thread.list` and `gmail.message.read` (user identity, read-only, resource `inbox`), `warehouse.view.read` (app identity). Resources are logical names, never IDs, URLs or tokens.",
+        "- 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.",
+        "- Consent is a user action: call `harbour.integrations.connect(connection)` and, when it returns `consent_required`, open `authorizationUrl`. Missing consent never falls back to another account.",
+        "- Authentication is owned by Harbour SSO. Do not add login forms, JWT handling, or trust a role, owner id or tenant id supplied by the browser. Row ownership is decided in SQL through `current_setting('harbour.user_id', true)` and `current_setting('harbour.user_email', true)`.",
+        "- Every route needs a signed-in human by default; do not add public routes or wildcard exceptions to make something work.",
+        "- No secrets, tokens, `.env` values or fetched company content in source. `.harbour/local/` is ignored and never committed; `.harbour/integrations.json` and `.harbour/kit.lock.json` are committed.",
+        "- Schema changes are SQL files in `migrations/`, applied by `harbour dev` and `harbour check`. Grant browser-path table privileges to `harbour_app_gateway`.",
+        "- Commands: `harbour dev --app-root .` (local runtime), `harbour check --app-root .` (declaration, types, build, migrations, journeys), `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`.",
+        MANAGED_END
+    ].join("\n");
+}
+const SKILL_FILE = `---
+name: harbour-kit
+description: Build, run and check this Harbour app with the Harbour CLI (dev, check, integrations, productionise).
+---
+
+Follow the "Harbour development kit" block in CLAUDE.md / AGENTS.md. Workflow:
+
+1. \`harbour dev --app-root .\` starts Postgres, storage, the identity fixture, the app gateway and Vite behind one loopback origin printed in the banner.
+2. Edit \`src/\`, \`migrations/\` and \`.harbour/integrations.json\`. Use the SDK only; declare integrations before calling them.
+3. \`harbour check --app-root .\` before every hand-off; read \`.harbour/local/check-report.json\`. Real integrations are reported as not tested unless \`--integrations\` is passed (read operations only).
+4. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for development access; pending is not ready.
+5. \`harbour productionise --app-root .\` saves and deploys the preview; \`harbour promote\` after the person has tested it.
+`;
+function kitFiles() {
+    return {
+        ".harbour/integrations.json": `${JSON.stringify({
+            schema: "harbour.app-integrations/2.0",
+            connections: {
+                // Only connections the app really calls belong here: productionise
+                // refuses to deploy until every declared one has a preview grant.
+                "company-slack": { kind: "saas", operations: { "slack.channel.history": { identity: "user", resources: ["team-updates"] }, "slack.message.post": { identity: "app", resources: ["team-updates"] } } }
+            }
+        }, null, 2)}\n`,
+        "migrations/0001_notes.sql": MIGRATION,
+        ".harbour/checks/notes-journey.mjs": JOURNEY_CHECK
+    };
+}
+function starterFiles(bundle) {
+    return {
+        "package.json": `${JSON.stringify({
+            name: "harbour-app", private: true, version: "0.1.0", type: "module",
+            scripts: { dev: "vite", build: "tsc --noEmit && vite build", preview: "vite preview" },
+            // The SDK is distributed as a tarball in the kit bundle, not from the public registry:
+            // `harbour dev` installs it from HARBOUR_KIT_SDK_TARBALL or the manifest's sdk.url and
+            // verifies its sha256 against .harbour/kit.lock.json before use.
+            dependencies: { [bundle.sdk.package]: bundle.sdk.version ?? "1.0.0", react: "^18.3.1", "react-dom": "^18.3.1" },
+            devDependencies: { "@types/react": "^18.3.12", "@types/react-dom": "^18.3.1", "@vitejs/plugin-react": "^4.3.4", typescript: "^5.6.3", vite: "^5.4.11" }
+        }, null, 2)}\n`,
+        "tsconfig.json": `${JSON.stringify({ compilerOptions: { target: "ES2022", lib: ["ES2022", "DOM", "DOM.Iterable"], module: "ESNext", moduleResolution: "Bundler", jsx: "react-jsx", strict: true, noEmit: true, skipLibCheck: true, isolatedModules: true }, include: ["src"] }, null, 2)}\n`,
+        "vite.config.ts": VITE_CONFIG,
+        "index.html": `<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="UTF-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1.0" />\n    <title>Harbour app</title>\n  </head>\n  <body>\n    <div id="root"></div>\n    <script type="module" src="/src/main.tsx"></script>\n  </body>\n</html>\n`,
+        "src/vite-env.d.ts": "/// <reference types=\"vite/client\" />\n",
+        "src/main.tsx": `import { StrictMode } from "react";\nimport { createRoot } from "react-dom/client";\nimport { App } from "./App";\n\ncreateRoot(document.getElementById("root")!).render(<StrictMode><App /></StrictMode>);\n`,
+        "src/harbour.client.ts": HARBOUR_CLIENT,
+        "src/App.tsx": APP,
+        "src/SlackPanel.tsx": SLACK_PANEL,
+        "README.md": "# Harbour app\n\nCreated by `harbour init`. Run `harbour dev --app-root .` and open the printed origin. See CLAUDE.md / AGENTS.md for the kit rules.\n\n`.harbour/integrations.json` declares `company-slack` only. Declare a connection only when the app calls it: `harbour productionise` refuses to deploy until every declared connection has a preview grant (`harbour integrations request <connection> --environment preview --reason \"<why>\" --app-root .`). The warehouse example (`sales-warehouse` / `warehouse.view.read`) is in a comment in `src/App.tsx`.\n"
+    };
+}
+const VITE_CONFIG = `import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+// \`harbour dev\` fronts Vite with one loopback origin and sets HARBOUR_LOCAL_ORIGIN;
+// the proxy below keeps SDK calls working if Vite is opened directly.
+const harbourOrigin = process.env.HARBOUR_LOCAL_ORIGIN ?? "http://127.0.0.1:4180";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: "127.0.0.1",
+    port: Number(process.env.HARBOUR_VITE_PORT ?? 5173),
+    strictPort: true,
+    proxy: { "/_harbour": { target: harbourOrigin, changeOrigin: false } }
+  }
+});
+`;
+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 };
+export type IntegrationCall = { 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>;
+};
+
+/** Typed access to the SDK's integrations surface (kit bundle SDK); throws a clear error on an older SDK. */
+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;
+}
+
+export function errorCode(error: unknown): string {
+  const details = (error as { details?: { code?: string } } | undefined)?.details;
+  return typeof details?.code === "string" ? details.code : (error as { category?: string })?.category ?? "UNKNOWN";
+}
+`;
+const APP = `import { useCallback, useEffect, useState } from "react";
+import type { HarbourUser } from "@harbour/app-sdk";
+import { harbour } from "./harbour.client";
+import { SlackPanel } from "./SlackPanel";
+
+type Note = { id: number; title: string; done: boolean; created_at: string };
+type StoredFile = { path?: string; name?: string; size?: number };
+
+export function App() {
+  const [user, setUser] = useState<HarbourUser | null>(null);
+  const [notes, setNotes] = useState<Note[]>([]);
+  const [title, setTitle] = useState("");
+  const [files, setFiles] = useState<StoredFile[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  const loadNotes = useCallback(async () => {
+    const { data } = await harbour.data.from<Note>("notes").select("*").order("created_at", { ascending: false });
+    setNotes(data);
+  }, []);
+  const loadFiles = useCallback(async () => { setFiles((await harbour.files.list("private/")) as StoredFile[]); }, []);
+
+  useEffect(() => {
+    harbour.identity.current().then(setUser).catch(err => setError(String(err)));
+    loadNotes().catch(err => setError(String(err)));
+    loadFiles().catch(err => setError(String(err)));
+    return harbour.identity.onChange(setUser);
+  }, [loadNotes, loadFiles]);
+
+  const addNote = async () => {
+    if (!title.trim()) return;
+    await harbour.data.from("notes").insert({ title: title.trim() });
+    setTitle("");
+    await loadNotes();
+  };
+  const toggle = async (note: Note) => { await harbour.data.from("notes").update({ done: !note.done }).eq("id", note.id); await loadNotes(); };
+  const remove = async (note: Note) => { await harbour.data.from("notes").delete().eq("id", note.id); await loadNotes(); };
+  const upload = async (file: File) => { await harbour.files.upload(\`private/\${file.name}\`, file); await loadFiles(); };
+
+  // Warehouse example. Declare the connection in .harbour/integrations.json first —
+  // every declared connection needs a preview grant before productionise will deploy:
+  //   "sales-warehouse": { "kind": "database", "operations": { "warehouse.view.read": { "identity": "app", "resources": { "weekly_sales": { "columns": ["week", "total"] } } } } }
+  // then request access (harbour integrations request sales-warehouse --reason "<why>" --app-root .) and uncomment:
+  // const report = await integrations().execute<{ rows: Array<{ week: string; total: number }> }>("sales-warehouse", {
+  //   operation: "warehouse.view.read", resource: "weekly_sales", input: { columns: ["week", "total"], limit: 100 }
+  // });
+
+  return (
+    <main style={{ fontFamily: "system-ui", maxWidth: 720, margin: "2rem auto", padding: "0 1rem" }}>
+      <h1>Harbour starter</h1>
+      <p>Signed in as <strong>{user ? user.email : "…"}</strong> (identity from Harbour; locally the fixture user).</p>
+      {error && <p role="alert" style={{ color: "crimson" }}>{error}</p>}
+
+      <section>
+        <h2>Notes</h2>
+        <form onSubmit={event => { event.preventDefault(); void addNote(); }}>
+          <input value={title} onChange={event => setTitle(event.target.value)} placeholder="New note" aria-label="New note" />
+          <button type="submit">Add</button>
+        </form>
+        <ul>
+          {notes.map(note => (
+            <li key={note.id}>
+              <label><input type="checkbox" checked={note.done} onChange={() => void toggle(note)} /> {note.title}</label>
+              <button type="button" onClick={() => void remove(note)} aria-label={\`Delete \${note.title}\`}>×</button>
+            </li>
+          ))}
+        </ul>
+      </section>
+
+      <section>
+        <h2>Private files</h2>
+        <input type="file" aria-label="Upload file" onChange={event => { const file = event.target.files?.[0]; if (file) void upload(file); }} />
+        <ul>{files.map((file, index) => <li key={index}>{file.path ?? file.name}{file.size !== undefined ? \` (\${file.size} bytes)\` : ""}</li>)}</ul>
+      </section>
+
+      <SlackPanel connection="company-slack" channel="team-updates" />
+    </main>
+  );
+}
+`;
+const SLACK_PANEL = `import { useState } from "react";
+import { errorCode, integrations, type ConnectResult } from "./harbour.client";
+
+type Message = { id: string; text: string; authorId: string; createdAt: string };
+type SendState = { kind: "idle" } | { kind: "sending" } | { kind: "sent"; messageId: string } | { kind: "unknown" } | { kind: "rate_limited"; retryAfterSeconds?: number } | { kind: "failed"; code: string };
+const SEND_KEY = "harbour.slack.sendActionId";
+
+/** One channel: connect (consent), load history, draft, explicit Send with a stable idempotency key. */
+export function SlackPanel({ connection, channel }: { connection: string; channel: string }) {
+  const [link, setLink] = useState<ConnectResult | { status: "reconnect_required" } | { status: "unknown" }>({ status: "unknown" });
+  const [history, setHistory] = useState<Message[]>([]);
+  const [draft, setDraft] = useState("");
+  const [send, setSend] = useState<SendState>({ kind: "idle" });
+  const [note, setNote] = useState<string | null>(null);
+
+  const connect = async () => {
+    try { setLink(await integrations().connect(connection)); setNote(null); }
+    catch (error) { setNote(\`Connect failed: \${errorCode(error)}\`); }
+  };
+  const loadHistory = async () => {
+    try {
+      const result = await integrations().execute<{ messages: Message[]; hasMore: boolean }>(connection, { operation: "slack.channel.history", resource: channel, input: { limit: 15 } });
+      setHistory(result.messages); setNote(null);
+    } catch (error) {
+      const code = errorCode(error);
+      if (code === "USER_CONNECTION_REQUIRED") setLink({ status: "unknown" });
+      else if (code === "USER_RECONNECT_REQUIRED") setLink({ status: "reconnect_required" });
+      setNote(\`History unavailable: \${code}\`);
+    }
+  };
+
+  // The key is created when the person presses Send and survives retries of that
+  // same action (component state + sessionStorage); a new draft gets a new key.
+  const sendDraft = async () => {
+    if (!draft.trim() || send.kind === "sending") return;
+    let key = sessionStorage.getItem(SEND_KEY);
+    if (!key) { key = crypto.randomUUID(); sessionStorage.setItem(SEND_KEY, key); }
+    setSend({ kind: "sending" });
+    try {
+      const result = await integrations().execute<{ messageId: string }>(connection, { operation: "slack.message.post", resource: channel, input: { text: draft }, idempotencyKey: key });
+      sessionStorage.removeItem(SEND_KEY);
+      setSend({ kind: "sent", messageId: result.messageId }); setDraft("");
+    } catch (error) {
+      const code = errorCode(error);
+      const retryAfterSeconds = (error as { details?: { retryAfterSeconds?: number } })?.details?.retryAfterSeconds;
+      if (code === "SEND_OUTCOME_UNKNOWN") setSend({ kind: "unknown" });
+      else if (code === "PROVIDER_RATE_LIMITED" || code === "RATE_LIMITED") setSend({ kind: "rate_limited", retryAfterSeconds });
+      else setSend({ kind: "failed", code });
+    }
+  };
+
+  return (
+    <section>
+      <h2>Slack: #{channel}</h2>
+      {link.status === "connected" && <p>Connected as {link.accountLabel}.</p>}
+      {link.status === "consent_required" && <p>Slack needs your consent: <a href={link.authorizationUrl}>connect your Slack account</a>.</p>}
+      {link.status === "reconnect_required" && <p>Your Slack connection expired. <button type="button" onClick={() => void connect()}>Reconnect</button></p>}
+      {link.status === "unknown" && <button type="button" onClick={() => void connect()}>Connect Slack</button>}
+      <p><button type="button" onClick={() => void loadHistory()}>Load history</button></p>
+      <ul>{history.map(message => <li key={message.id}><code>{message.authorId}</code> {message.text}</li>)}</ul>
+      <textarea value={draft} onChange={event => { setDraft(event.target.value); if (send.kind !== "sending") { sessionStorage.removeItem(SEND_KEY); setSend({ kind: "idle" }); } }} placeholder="Draft a message (nothing is sent until you press Send)" rows={3} style={{ width: "100%" }} />
+      <p><button type="button" onClick={() => void sendDraft()} disabled={send.kind === "sending" || !draft.trim()}>Send</button></p>
+      {send.kind === "sent" && <p>Sent (message {send.messageId}).</p>}
+      {send.kind === "unknown" && <p>Harbour could not confirm whether the message was sent. Retry sends the same action, not a duplicate. <button type="button" onClick={() => void sendDraft()}>Retry</button></p>}
+      {send.kind === "rate_limited" && <p>Slack is rate limiting; try again{send.retryAfterSeconds ? \` in \${send.retryAfterSeconds}s\` : " shortly"}.</p>}
+      {send.kind === "failed" && <p>Send failed: {send.code}.</p>}
+      {note && <p>{note}</p>}
+    </section>
+  );
+}
+`;
+const MIGRATION = `-- Notes table for the starter. Ownership comes from the gateway's transaction-local
+-- settings (harbour.user_id / harbour.user_email); the browser never supplies it.
+CREATE TABLE IF NOT EXISTS notes (
+  id BIGSERIAL PRIMARY KEY,
+  owner_subject TEXT NOT NULL DEFAULT current_setting('harbour.user_id', true),
+  title TEXT NOT NULL CHECK (char_length(title) BETWEEN 1 AND 500),
+  done BOOLEAN NOT NULL DEFAULT FALSE,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+ALTER TABLE notes ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS notes_owner ON notes;
+CREATE POLICY notes_owner ON notes
+  USING (owner_subject = current_setting('harbour.user_id', true))
+  WITH CHECK (owner_subject = current_setting('harbour.user_id', true));
+GRANT SELECT, INSERT, UPDATE, DELETE ON notes TO harbour_app_gateway;
+GRANT USAGE, SELECT ON SEQUENCE notes_id_seq TO harbour_app_gateway;
+`;
+const JOURNEY_CHECK = `// Journey check: the signed-in identity can create, read and delete a note through
+// the running app (HARBOUR_APP_URL). Runs under \`harbour check\` while \`harbour dev\`
+// is up, and in the deployment pipeline's retained-check container.
+import assert from "node:assert/strict";
+
+const appUrl = process.env.HARBOUR_APP_URL;
+assert.ok(appUrl, "HARBOUR_APP_URL is required");
+const sdk = await import(process.env.HARBOUR_SDK_MODULE ?? "@harbour/app-sdk");
+const token = process.env.HARBOUR_IDENTITY_CONTEXT_TOKEN;
+const fetchWithIdentity = (input, init = {}) => fetch(input, { ...init, headers: { ...(init.headers ?? {}), ...(token ? { "x-harbour-identity-context": token } : {}) } });
+const harbour = sdk.createClient({ baseUrl: appUrl, fetch: fetchWithIdentity });
+
+const user = await harbour.identity.current();
+assert.ok(user && user.email, "identity/current must return the signed-in user");
+const title = \`journey \${Date.now()}\`;
+await harbour.data.from("notes").insert({ title });
+const { data: notes } = await harbour.data.from("notes").select("*").eq("title", title);
+assert.equal(notes.length, 1, "the inserted note is readable by its owner");
+await harbour.data.from("notes").delete().eq("id", notes[0].id);
+const { data: remaining } = await harbour.data.from("notes").select("id").eq("title", title);
+assert.equal(remaining.length, 0, "the note is deleted");
+`;

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.13";
+export const CLI_VERSION = "0.1.14";

package/dist/src/analyzer.js

@@ -12,6 +12,8 @@ const MAX_FILE_BYTES = 256_000;
 // 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"]);
+/** The development kit commits exactly these two files under `.harbour`; everything else there (local state, checks evidence, generated control files) stays out of the package. */
+const KIT_COMMITTED_FILES = new Set([".harbour/integrations.json", ".harbour/kit.lock.json"]);
 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", ".sh"]);
 function normalizeIncludePath(value) {
@@ -27,7 +29,7 @@ function normalizeIncludePath(value) {
 async function collectIncludedFiles(root, includePaths, output, unknowns) {
     const normalized = [...new Set(includePaths.map(normalizeIncludePath))];
     for (const include of normalized) {
-        if (include.split("/").some(part => IGNORED_DIRS.has(part)))
+        if (include.split("/").some(part => IGNORED_DIRS.has(part)) && !KIT_COMMITTED_FILES.has(include))
             continue;
         const absolute = include ? join(root, ...include.split("/")) : root;
         let info;
@@ -75,6 +77,8 @@ async function collectFiles(root, current, output, unknowns) {
         if (entry.isDirectory()) {
             if (!IGNORED_DIRS.has(entry.name))
                 await collectFiles(root, join(current, entry.name), output, unknowns);
+            else if (entry.name === ".harbour" && current === root)
+                await collectKitFiles(root, output);
             continue;
         }
         if (!entry.isFile())
@@ -82,6 +86,20 @@ async function collectFiles(root, current, output, unknowns) {
         await collectFile(root, join(current, entry.name), output);
     }
 }
+async function collectKitFiles(root, output) {
+    for (const path of [...KIT_COMMITTED_FILES].sort()) {
+        const absolute = join(root, ...path.split("/"));
+        let info;
+        try {
+            info = await lstat(absolute);
+        }
+        catch {
+            continue;
+        }
+        if (info.isFile() && !info.isSymbolicLink())
+            await collectFile(root, absolute, output);
+    }
+}
 async function collectFile(root, absolute, output) {
     const path = relative(root, absolute);
     if (output.some(file => file.path === path))

package/dist/src/secret-paths.js

@@ -17,3 +17,11 @@ export function isSourceIntakeExcludedPath(path) {
     return /(^|\/)(?:__MACOSX)(?:\/|$)|(^|\/)\.DS_Store$/i.test(path)
         || /(^|\/)\.github\/workflows\//i.test(path);
 }
+/** The development kit commits exactly these two files under `.harbour`; everything else there stays local. */
+export function isKitCommittedPath(path) {
+    return /(^|\/)\.harbour\/(?:integrations\.json|kit\.lock\.json)$/.test(path);
+}
+/** Dependency and internal directories the intake never stages — `.harbour` except its two committed kit files. */
+export function isInternalSourcePath(path) {
+    return /(^|\/)(?:node_modules|\.git)(?:\/|$)/i.test(path) || (/(^|\/)\.harbour(?:\/|$)/i.test(path) && !isKitCommittedPath(path));
+}

package/dist/src/source-intake.js

@@ -1,5 +1,5 @@
 import { sha256, sha256Bytes, stableJson } from "./digest.js";
-import { isProhibitedSecretPath } from "./secret-paths.js";
+import { isInternalSourcePath, isProhibitedSecretPath } from "./secret-paths.js";
 export class MemorySourceArchiveStore {
     archives = new Map();
     async put(objectKey, archive) { this.archives.set(objectKey, clone(archive)); }
@@ -113,7 +113,7 @@ function safeSourcePath(path) {
         // Checked-in env templates are configuration metadata, not runtime
         // credentials. All other env variants remain excluded before staging.
         && !isProhibitedSecretPath(path)
-        && !/(^|\/)(?:node_modules|\.git|\.harbour)(?:\/|$)/.test(path);
+        && !isInternalSourcePath(path);
 }
 function toBytes(value) { return typeof value === "string" ? new TextEncoder().encode(value) : value; }
 function bytesToBase64(bytes) { return Buffer.from(bytes).toString("base64"); }

package/package.json

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