@nightowlsdev/cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Night Owls contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# `@nightowlsdev/cli`
+
+The pluggable Night Owls CLI. One thin binary — `owl` — that scaffolds a project, installs adapters, and
+**contributes** each adapter's migrations into your `supabase/migrations/`. Each `@nightowlsdev/*` adapter
+contributes a **declarative** manifest; the CLI discovers the installed adapters from your `package.json`
+and acts on their manifests. All codegen lives in the CLI, so adapters stay data-only (no dependency cycle).
+
+**Night Owls never runs DDL against your database.** It only ever *contributes* migrations into your
+`supabase/migrations/`; you apply them with your own tooling (e.g. `supabase db push`).
+
+```bash
+npx @nightowlsdev/cli init
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `owl init [plugin]` | Scaffold `nightowls.config.ts` + `.env.example` and install the selected adapters (each one **installs** its migrations into `supabase/migrations/` and runs its `init` hook). Idempotent; never clobbers an existing config. With a `[plugin]` arg (e.g. `owl init storage-supabase`), re-init **just that one** plugin against the existing project — re-apply its wiring + re-run its `init` hook (useful to integrate a plugin after the fact). Flags: `--storage <adapter>`, `--runner <adapter>`, `--no-storage`, `--no-runner`, `-y/--yes`. |
+| `owl install <adapter>` | Add `@nightowlsdev/<adapter>` as a dependency and apply its boilerplate: merge its env vars into `.env.example`, scaffold its files (only if absent), insert its config import + wiring snippet into `nightowls.config.ts`, **install its migrations into `supabase/migrations/`**, and run its `init` hook. Idempotent. |
+| `owl plugins` | List the installed `@nightowlsdev/*` plugins, their kind + description, and the commands each exposes. |
+| `owl <plugin> <cmd>` | Run a plugin's own subcommand (e.g. `owl storage-supabase info`, `owl runner-nextjs routes`). `owl <plugin> --help` lists a plugin's commands; `owl <plugin> <cmd> --help` shows a command's flags. |
+| `owl db install` | (Re-)install Night Owls' migrations into the host's classic `supabase/migrations/` as timestamped `.sql` files, so they run with the app's own via `supabase db push`. Useful after upgrading an adapter. Idempotent. Flag: `--out <dir>` (default `supabase/migrations`). |
+| `owl db types` | Generate TypeScript types for the `nightowls` schema (`supabase gen types typescript --schema nightowls`). |
+
+## Adapters and what `owl install` wires
+
+Each adapter contributes env vars, a config snippet (or files + guidance), an `init` hint, and an `info`
+command. **Install ONE storage adapter, ONE auth provider, and ONE model provider; telemetry COMPOSES
+(install as many as you like); `runner-background` is opt-in (`runner-nextjs` is the default).** The scaffolded
+`nightowls.config.ts` is a **starting point you complete** — fill in your `agents` (and set `MODEL_ID`; a model
+provider wires `modelFactory` and `models.allow` is env-driven from it).
+
+| Adapter | kind | `owl install` wiring |
+| --- | --- | --- |
+| `storage-supabase` | storage | env `SUPABASE_URL`, `SUPABASE_SECRET_KEY`, `DATABASE_URL`, `SUPABASE_ANON_KEY`; config `storage = createSupabaseStorage({ url, secretKey, dbUrl })`; installs its migrations into `supabase/migrations/`. Command: `info`. |
+| `runner-nextjs` | runner | scaffolds `app/api/swarm/*` route handlers; config `runner = createNextjsRunner({ swarm, auth, storage })`. The interactive (SSE) default. Command: `routes`. |
+| `auth-supabase` | auth | env `SUPABASE_URL`, `SUPABASE_ANON_KEY` (anon key only — verifies the user JWT, never the secret key); config `auth = supabaseAuth({ url, anonKey })`. Command: `info`. |
+| `auth-auth0` | auth | env `AUTH0_ISSUER_BASE_URL`, `AUTH0_AUDIENCE`; config `auth = auth0Auth({ issuerBaseUrl, audience })`. **Install ONE auth provider** (reconcile a duplicate `auth = …` if you install both). Command: `info`. |
+| `telemetry-otel` | telemetry | env `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`; config **composes** `telemetry = [...(telemetry ?? []), otelTelemetry({ url })]`. Command: `info`. |
+| `telemetry-langfuse` | telemetry | env `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_BASEURL`; config **composes** `telemetry = [...(telemetry ?? []), langfuseTelemetry({ publicKey, secretKey, baseUrl })]`. Command: `info`. |
+| `runner-background` | runner | **opt-in** durable HITL runner (Trigger.dev v4 / Vercel Workflow). env `DURABLE_BACKEND`, `TRIGGER_SECRET_KEY`; scaffolds `trigger/nightowls.ts` (task) + `lib/nightowls-durable.ts` (registry); config is **commented guidance** at the runner marker — you wire `createBackgroundRunner(...)` by hand. The `init` hook prints the setup steps. Command: `info`. |
+| `mcp` | connector | connect external MCP servers as Night Owls tools (approval-gated, fenced). env `MCP_<SERVER>_URL`; config is **commented guidance** at the connector marker — MCP tools are **granted to specific agents' skills**, not assigned to a single binding. Command: `info`. |
+| `model-vercel-gateway` | model | any model via the Vercel AI Gateway (`provider/model` ids, one key). env `AI_GATEWAY_API_KEY`, `MODEL_ID`; config `modelFactory = vercelGatewayModels()`. **Install ONE model provider** (reconcile a duplicate `modelFactory = …` if you install more than one). Command: `info`. |
+| `model-openrouter` | model | any model via OpenRouter. env `OPENROUTER_API_KEY`, `MODEL_ID`; config `modelFactory = openrouterModels()`. Command: `info`. |
+| `model-anthropic` | model | Anthropic Claude models (native `@ai-sdk/anthropic`). env `ANTHROPIC_API_KEY`, `MODEL_ID`; config `modelFactory = anthropicModels()`. Command: `info`. |
+| `model-openai` | model | OpenAI models (native `@ai-sdk/openai`). env `OPENAI_API_KEY`, `MODEL_ID`; config `modelFactory = openaiModels()`. Command: `info`. |
+
+Telemetry composing is verified at the gate: the generated `nightowls.config.ts` with storage + runner + auth
++ a model provider (`modelFactory = anthropicModels()`) + **both** telemetry exporters **parses and
+typechecks** against the real `@nightowlsdev/core` + adapter types (`packages/cli/test/config-typecheck.test.ts`).
+
+## How migrations land: install, then apply with your own tooling
+
+Night Owls is a migration **contributor** — it never connects to your database to run DDL. `owl install`
+(and `owl init`, which installs per adapter) **installs** each storage adapter's migrations into the
+host's classic `supabase/migrations/` directory as timestamped files named
+`<YYYYMMDDHHMMSS>_corale_<version>.sql` (e.g. `20260604093000_corale_0001_core.sql`). You then apply them
+with **your own** tooling — `supabase db push` — alongside your app's own migrations. The install prints
+the apply instruction; it does not run it.
+
+`owl db install` is **idempotent**: it scans the out dir and skips any version already installed (matched by the
+`_corale_<version>` filename token), so re-running it never overwrites or duplicates a file. Newly added
+migrations are appended on the next install (e.g. after `owl install` of a newer adapter, or an explicit
+`owl db install`). The install-time timestamp (base clock plus an index offset, so the files stay unique and
+lexically ordered) **slots them in correctly whether you adopt Night Owls on day one or add it later** — they
+sort after whatever the host already had.
+
+## Plugin commands, lifecycle hooks, and help
+
+Beyond the declarative wiring, a plugin can carry **behavior** and **docs**:
+
+- **Subcommands** — a plugin exposes `commands`, each surfaced as `owl <plugin-name> <command-name>`.
+  The CLI discovers the installed plugins on every run and registers their command groups before parsing,
+  so `owl storage-supabase info` and `owl runner-nextjs routes` "just work". A plugin command's
+  handler gets a structural context: `{ cwd, log, args, options }`. The reference commands are **pure** —
+  no DB, no network — honoring "Night Owls never acts on its own". A plugin whose `name` would shadow a
+  built-in (`init`/`install`/`db`/`plugins`/`help`) is **skipped with a warning** (the built-in always wins).
+- **`init` hook** — a plugin's optional `init({ cwd, log })` runs **after** the declarative wiring during
+  `owl init`, `owl install <plugin>`, and `owl init <plugin>`. This integrates a plugin into an
+  already-inited project. The hook is **idempotent and print-only** — it MUST NOT apply DDL or touch a DB.
+- **Help** — every plugin and command carries a `description`. `owl plugins` lists them; `owl <plugin>
+  --help` and `owl <plugin> <cmd> --help` render Commander's usage from those descriptions + options.
+
+```bash
+owl plugins                    # list installed plugins, their kind/description, and their commands
+owl storage-supabase --help    # a plugin's commands
+owl storage-supabase info      # a pure command: the migrations + env this adapter contributes
+owl runner-nextjs routes       # a pure command: the App Router routes this runner scaffolds
+owl init storage-supabase      # re-init one plugin: re-apply wiring + re-run its init hook
+```
+
+**Adapters stay import-free of `@nightowlsdev/cli`.** The `init`/command handler contexts are typed
+**structurally** (a local `type Ctx = { cwd; log; args; options }` in the adapter) — no adapter imports the
+CLI, so the published `.d.ts` references no `@nightowlsdev/cli` type (no dependency cycle). The CLI's
+`conformance.test-d.ts` pins each manifest to `NightOwlsPlugin` structurally.
+
+## The declarative `nightOwlsPlugin` contract
+
+An adapter plugs into the CLI by exporting a `nightOwlsPlugin` plain object that **structurally** matches
+`NightOwlsPlugin` (it does NOT import the type — that would create a cycle, since the CLI imports the adapter):
+
+```ts
+export interface NightOwlsPlugin {
+  name: string;            // short name, e.g. "storage-supabase"
+  version: string;
+  kind?: "storage" | "runner" | "auth" | "telemetry" | "ui" | "connector";
+  pkg: string;             // npm name, e.g. "@nightowlsdev/storage-supabase"
+  description?: string;    // one-line summary shown by `owl plugins` + `owl <plugin> --help`
+  migrations?: { version: string; name: string; sql: string }[]; // installed into supabase/migrations/
+  env?: { key: string; example: string; comment?: string }[];     // merged into .env.example
+  files?: { path: string; contents: string }[];                   // scaffolded if absent (never clobbered)
+  config?: {                                                       // inserted at the `// nightowls:<marker>` line
+    import: string;
+    snippet: string;
+    marker: "storage" | "auth" | "runner" | "telemetry" | "connector";
+  };
+  // Runs after the declarative wiring on init/install (idempotent; print-only — never applies DDL).
+  init?: (ctx: { cwd: string; log: (msg: string) => void }) => void | Promise<void>;
+  // Subcommands surfaced as `owl <plugin-name> <command-name>` (the ctx adds { args, options }).
+  commands?: {
+    name: string;
+    description: string;
+    options?: { flags: string; description: string; defaultValue?: string | boolean }[];
+    run: (ctx: {
+      cwd: string;
+      log: (msg: string) => void;
+      args: string[];
+      options: Record<string, unknown>;
+    }) => void | Promise<void>;
+  }[];
+}
+```
+
+The CLI discovers `@nightowlsdev/*` deps from the host `package.json`, dynamic-imports each one, and collects the
+`nightOwlsPlugin` exports. Adapters without a manifest (e.g. `@nightowlsdev/react`) are ignored.
+
+`config.snippet` is a **top-level statement** inserted above the `// nightowls:<marker>` line — it assigns the
+scaffold's pre-declared binding (e.g. `storage = createSupabaseStorage({ … });`,
+`runner = createNextjsRunner({ … });`), so installing several adapters into one `nightowls.config.ts` produces
+valid, functional TypeScript. It is NOT an object-property fragment.
+
+## The nightowls schema
+
+Night Owls' tables live in a dedicated `nightowls` schema (not `public`). Night Owls **contributes** its migrations
+into your `supabase/migrations/` (via `owl install` / `owl db install`); your host's migration runner
+(`supabase db push`) applies them and tracks them in the host's own `supabase_migrations.schema_migrations`.
+There is one migration system — the host's — and Night Owls never runs DDL itself. See
+`docs/spec/2026-06-03-owl-schema-and-cli.md`.
+
+## Roadmap
+
+The agentic CLI layer (`owl doctor`, `owl mcp`, deep ts-morph config edits) is future work. Today the
+config insertion is marker-based — the `// nightowls:<marker>` comment lines are stable insertion points.

package/dist/chunk-E2C2JZ2E.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+// src/registry.ts
+async function discoverPlugins(deps) {
+  const pkg = await deps.readPkgJson();
+  const names = [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})].filter(
+    (n) => n.startsWith("@nightowlsdev/")
+  );
+  const out = [];
+  for (const name of names) {
+    const mod = await deps.importPlugin(name).catch(() => ({}));
+    if (mod.nightOwlsPlugin) out.push({ ...mod.nightOwlsPlugin, pkg: mod.nightOwlsPlugin.pkg ?? name });
+  }
+  return out;
+}
+function nodeDiscoverDeps(cwd) {
+  return {
+    readPkgJson: async () => JSON.parse(await (await import("fs/promises")).readFile(`${cwd}/package.json`, "utf8")),
+    importPlugin: async (pkg) => (await import("./node-EVZ52KTR.js")).hostImport(cwd, pkg)
+  };
+}
+
+export {
+  discoverPlugins,
+  nodeDiscoverDeps
+};

package/dist/chunk-YZIYBDZO.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+// src/node.ts
+async function exec(cmd, args) {
+  const { execFile } = await import("child_process");
+  const { promisify } = await import("util");
+  const run = promisify(execFile);
+  const { stdout } = await run(cmd, args, { maxBuffer: 64 * 1024 * 1024 });
+  return { stdout: stdout.toString() };
+}
+async function detectPackageManager(cwd) {
+  const fs = await import("fs/promises");
+  const has = async (f) => {
+    try {
+      await fs.access(`${cwd}/${f}`);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (await has("pnpm-lock.yaml")) return "pnpm";
+  if (await has("yarn.lock")) return "yarn";
+  return "npm";
+}
+async function addDep(pm, cwd, pkg) {
+  const { spawn } = await import("child_process");
+  const args = pm === "yarn" ? ["add", pkg] : pm === "npm" ? ["install", pkg] : ["add", pkg];
+  await new Promise((resolve, reject) => {
+    const child = spawn(pm, args, { cwd, stdio: "inherit", shell: process.platform === "win32" });
+    child.on("error", reject);
+    child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`${pm} ${args.join(" ")} exited ${code}`)));
+  });
+}
+async function isInstalled(cwd, pkg) {
+  try {
+    const fs = await import("fs/promises");
+    const json = JSON.parse(await fs.readFile(`${cwd}/package.json`, "utf8"));
+    return Boolean(json.dependencies?.[pkg] ?? json.devDependencies?.[pkg]);
+  } catch {
+    return false;
+  }
+}
+async function hostImport(cwd, pkg) {
+  const { createRequire } = await import("module");
+  const { pathToFileURL } = await import("url");
+  const requireFromHost = createRequire(`${cwd}/package.json`);
+  const resolved = requireFromHost.resolve(pkg);
+  return await import(pathToFileURL(resolved).href);
+}
+async function loadPlugin(pkg, cwd) {
+  try {
+    const mod = await hostImport(cwd, pkg);
+    return mod.nightOwlsPlugin ?? null;
+  } catch {
+    return null;
+  }
+}
+async function nodeFs() {
+  const fs = await import("fs/promises");
+  return {
+    readFile: (p, enc) => fs.readFile(p, enc),
+    writeFile: (p, data) => fs.writeFile(p, data),
+    mkdir: (p, opts) => fs.mkdir(p, opts),
+    readdir: (p) => fs.readdir(p)
+  };
+}
+
+export {
+  exec,
+  detectPackageManager,
+  addDep,
+  isInstalled,
+  hostImport,
+  loadPlugin,
+  nodeFs
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,421 @@
+#!/usr/bin/env node
+import {
+  discoverPlugins,
+  nodeDiscoverDeps
+} from "./chunk-E2C2JZ2E.js";
+import {
+  addDep,
+  detectPackageManager,
+  exec,
+  isInstalled,
+  loadPlugin,
+  nodeFs
+} from "./chunk-YZIYBDZO.js";
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/commands/db.ts
+function collectMigrations(plugins) {
+  const all = plugins.flatMap((p) => p.migrations ?? []);
+  if (all.length === 0) {
+    throw new Error(
+      "No storage adapter installed (or it ships no migrations). Run `owl install storage-supabase` first."
+    );
+  }
+  return [...all].sort((a, b) => a.version.localeCompare(b.version));
+}
+async function runDbTypes(deps) {
+  const schema = deps.schema ?? "nightowls";
+  const { stdout } = await deps.exec("supabase", ["gen", "types", "typescript", "--schema", schema]);
+  return stdout;
+}
+function migrationStamp(base, i) {
+  const d = new Date(base.getTime() + i * 1e3);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`;
+}
+var INSTALLED_FILE = /_corale_(.+)\.sql$/;
+async function runDbInstall(deps) {
+  const migrations = collectMigrations(deps.plugins);
+  const dir = `${deps.root.replace(/\/$/, "")}/${deps.out.replace(/^\//, "")}`;
+  await deps.fs.mkdir(dir, { recursive: true }).catch(() => void 0);
+  const existing = await deps.fs.readdir(dir).catch(() => []);
+  const installed = new Set(
+    existing.map((f) => INSTALLED_FILE.exec(f)?.[1]).filter((v) => Boolean(v))
+  );
+  const base = deps.now();
+  const written = [];
+  const skipped = [];
+  let i = 0;
+  for (const m of migrations) {
+    if (installed.has(m.version)) {
+      skipped.push(m.version);
+      continue;
+    }
+    const file = `${migrationStamp(base, i)}_corale_${m.version}.sql`;
+    await deps.fs.writeFile(`${dir}/${file}`, `${m.sql.trimStart()}
+`);
+    written.push({ version: m.version, file });
+    i += 1;
+  }
+  return { written, skipped };
+}
+
+// src/templates.ts
+var CONFIG_TEMPLATE = `import { defineSwarm } from "@nightowlsdev/core";
+// nightowls:imports \u2014 adapter imports are inserted above this line by \`owl install\`.
+
+/**
+ * Read your secrets here (e.g. via \`process.env\` or a validated env module). Required by the inserted
+ * adapter snippets: SUPABASE_URL, SUPABASE_SECRET_KEY, DATABASE_URL (see .env.example).
+ */
+const env = process.env as Record<string, string>;
+
+// Define your agents (slug, instructions, model_id, skills). See the docs for the full shape.
+const AGENTS: Parameters<typeof defineSwarm>[0]["agents"] = [];
+
+// Storage adapter \u2014 \`owl install storage-supabase\` assigns \`storage = \u2026\` above the marker below
+// (and installs its migrations into supabase/migrations/ \u2014 apply them with \`supabase db push\`).
+// Until then this is a placeholder; a real storage adapter is required to run.
+let storage: Parameters<typeof defineSwarm>[0]["storage"] = undefined as never;
+// nightowls:storage
+
+// Telemetry exporter(s) \u2014 \`owl install telemetry-*\` COMPOSES into this array (each adapter pushes
+// its exporter above the marker). \`defineSwarm\` accepts one OR many; many are best-effort composed
+// (a throwing exporter never breaks a run). Declared as the ARRAY member of that union so multiple
+// exporters coexist (\`telemetry = [...(telemetry ?? []), xTelemetry({...})];\`).
+let telemetry: Extract<NonNullable<Parameters<typeof defineSwarm>[0]["telemetry"]>, readonly unknown[]> = [];
+// nightowls:telemetry
+
+// Model provider \u2014 \`owl install model-<provider>\` assigns \`modelFactory = \u2026\` above the marker below
+// (install ONE \u2014 providers are mutually exclusive, like auth). Declared as a \`let\` so the inserted
+// snippet can reassign it; the placeholder throws until a real provider is wired. \`models.allow\` is
+// env-driven (\`MODEL_ID\`), so the scaffold is runnable once a model plugin + MODEL_ID are set.
+let modelFactory: Parameters<typeof defineSwarm>[0]["modelFactory"] = () => {
+  throw new Error("Install a model provider: owl install model-anthropic (or model-openai / model-vercel-gateway / model-openrouter).");
+};
+// nightowls:model
+
+export const swarm = defineSwarm({
+  storage,
+  agents: AGENTS,
+  models: { allow: env.MODEL_ID ? [env.MODEL_ID] : [] },
+  modelFactory,
+  cost: { maxSteps: 12, maxCostUsd: 0.5 },
+  telemetry,
+});
+
+// Server-side auth \u2014 \`owl install auth-*\` assigns \`auth = \u2026\` above the marker below (install ONE
+// auth provider). Declared as a \`let\` so the inserted snippet can reassign it; the placeholder rejects
+// every request (never trust the request body for identity \u2014 replace it with a real identity resolver).
+let auth: { authenticate(req: Request): Promise<{ tenantId: string; userId: string; capabilities?: string[] } | null> } = {
+  authenticate: async () => null,
+};
+// nightowls:auth
+
+// Runner \u2014 \`owl install runner-nextjs\` assigns \`runner = \u2026\` above the marker below. The structural
+// type covers the three App Router handlers the scaffolded route files call (\`runner.chatRoute()\`, \u2026), so
+// the host typechecks before AND after the assignment without the CLI importing the runner package.
+type SwarmRunner = {
+  chatRoute(): { POST: (req: Request) => Promise<Response> };
+  resumeRoute(): { POST: (req: Request) => Promise<Response> };
+  eventsRoute(): { GET: (req: Request, ctx: { params: Promise<{ id: string }> }) => Promise<Response> };
+};
+let runner: SwarmRunner = undefined as never;
+// nightowls:runner
+export { runner };
+
+// Connectors \u2014 \`owl install mcp\` inserts a guidance comment above the marker below. Connector tools
+// (e.g. MCP servers) are GRANTED to specific agents' skills (approval-gated, fenced), not assigned to a
+// single binding \u2014 so the inserted snippet is a comment, not an assignment.
+// nightowls:connector
+`;
+var ENV_EXAMPLE_HEADER = `# Night Owls environment \u2014 copy to .env.local and fill in.
+# Adapter variables are appended below by \`owl install <adapter>\`.
+`;
+
+// src/codegen.ts
+async function readIfExists(fs, path) {
+  try {
+    return await fs.readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function join(root, rel) {
+  return `${root.replace(/\/$/, "")}/${rel.replace(/^\//, "")}`;
+}
+function envLine(e) {
+  const base = `${e.key}=${e.example}`;
+  return e.comment ? `${base}          # ${e.comment}` : base;
+}
+async function mergeEnv(fs, envPath, env) {
+  const current = await readIfExists(fs, envPath) ?? "";
+  const additions = [];
+  for (const e of env) {
+    const present = new RegExp(`^\\s*${e.key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}=`, "m").test(current);
+    if (!present) additions.push(envLine(e));
+  }
+  if (additions.length === 0) return;
+  const needsNl = current.length > 0 && !current.endsWith("\n");
+  const next = current + (needsNl ? "\n" : "") + additions.join("\n") + "\n";
+  await fs.writeFile(envPath, next);
+}
+async function insertConfig(fs, configPath, plugin) {
+  const cfg = plugin.config;
+  if (!cfg) return;
+  let text = await readIfExists(fs, configPath);
+  if (text === null) return;
+  let changed = false;
+  if (!text.includes(cfg.import)) {
+    text = `${cfg.import}
+${text}`;
+    changed = true;
+  }
+  if (!text.includes(cfg.snippet)) {
+    const marker = `// nightowls:${cfg.marker}`;
+    const idx = text.indexOf(marker);
+    if (idx !== -1) {
+      const lineStart = text.lastIndexOf("\n", idx) + 1;
+      const indent = text.slice(lineStart, idx);
+      const insertion = `${indent}${cfg.snippet}
+`;
+      text = text.slice(0, lineStart) + insertion + text.slice(lineStart);
+      changed = true;
+    }
+  }
+  if (changed) await fs.writeFile(configPath, text);
+}
+async function scaffoldFiles(fs, root, plugin) {
+  for (const f of plugin.files ?? []) {
+    const abs = join(root, f.path);
+    if (await readIfExists(fs, abs) !== null) continue;
+    const dir = abs.slice(0, abs.lastIndexOf("/"));
+    if (dir) await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(abs, f.contents);
+  }
+}
+async function applyInstall(args) {
+  const { plugin, root, fs } = args;
+  if (plugin.env?.length) await mergeEnv(fs, join(root, ".env.example"), plugin.env);
+  await scaffoldFiles(fs, root, plugin);
+  await insertConfig(fs, join(root, "nightowls.config.ts"), plugin);
+}
+
+// src/commands/install.ts
+function toPkgName(adapter) {
+  return adapter.startsWith("@nightowlsdev/") ? adapter : `@nightowlsdev/${adapter}`;
+}
+async function runInstall(deps) {
+  const pkg = toPkgName(deps.adapter);
+  const already = deps.isInstalled ? await deps.isInstalled(pkg) : false;
+  let added = false;
+  if (!already) {
+    await deps.addDep(pkg);
+    added = true;
+  }
+  const plugin = await deps.loadPlugin(pkg);
+  if (!plugin) {
+    throw new Error(`${pkg} does not export a nightOwlsPlugin manifest \u2014 nothing to install.`);
+  }
+  await applyInstall({ plugin, root: deps.root, fs: deps.fs });
+  let migrations = [];
+  if (plugin.migrations?.length) {
+    const result = await runDbInstall({
+      plugins: [plugin],
+      root: deps.root,
+      out: "supabase/migrations",
+      fs: deps.fs,
+      now: deps.now ?? (() => /* @__PURE__ */ new Date())
+    });
+    migrations = result.written;
+  }
+  const log = deps.log ?? console.log;
+  let initRan = false;
+  if (plugin.init) {
+    await plugin.init({ cwd: deps.root, log });
+    initRan = true;
+  }
+  return { pkg, added, applied: true, migrations, initRan };
+}
+
+// src/commands/init.ts
+async function readIfExists2(fs, path) {
+  try {
+    return await fs.readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function join2(root, rel) {
+  return `${root.replace(/\/$/, "")}/${rel}`;
+}
+async function runInit(deps) {
+  const configPath = join2(deps.root, "nightowls.config.ts");
+  const envPath = join2(deps.root, ".env.example");
+  if (await readIfExists2(deps.fs, configPath) === null) {
+    await deps.fs.writeFile(configPath, CONFIG_TEMPLATE);
+  }
+  if (await readIfExists2(deps.fs, envPath) === null) {
+    await deps.fs.writeFile(envPath, ENV_EXAMPLE_HEADER);
+  }
+  const migrations = [];
+  for (const adapter of deps.adapters) {
+    const result = await runInstall({
+      adapter,
+      root: deps.root,
+      fs: deps.fs,
+      addDep: deps.addDep,
+      loadPlugin: deps.loadPlugin,
+      now: deps.now,
+      log: deps.log
+    });
+    migrations.push(...result.migrations);
+  }
+  return { migrations };
+}
+
+// src/commands/plugins.ts
+function registerPluginCommands(program2, plugins, base) {
+  const taken = /* @__PURE__ */ new Set([...program2.commands.map((c) => c.name()), "help"]);
+  for (const p of plugins) {
+    if (!p.commands?.length) continue;
+    if (taken.has(p.name)) {
+      base.log(`(skipping plugin "${p.name}": shadows a built-in command)`);
+      continue;
+    }
+    taken.add(p.name);
+    const group = program2.command(p.name).description(p.description ?? `${p.kind ?? "plugin"} adapter (${p.pkg})`);
+    for (const cmd of p.commands) {
+      const sub = group.command(cmd.name).description(cmd.description);
+      for (const o of cmd.options ?? []) {
+        sub.option(o.flags, o.description, o.defaultValue);
+      }
+      sub.allowExcessArguments(true);
+      sub.action(async (...a) => {
+        const command = a[a.length - 1];
+        await cmd.run({ ...base, args: command.args ?? [], options: command.opts() });
+      });
+    }
+  }
+}
+function runPluginsList(plugins, log) {
+  if (!plugins.length) {
+    log("No @nightowlsdev/* plugins found in this project.");
+    return;
+  }
+  log("Installed Night Owls plugins:");
+  for (const p of plugins) {
+    const cmds = p.commands?.length ? `  [${p.commands.map((c) => c.name).join(", ")}]` : "";
+    log(`  ${p.name.padEnd(20)} ${(p.kind ?? "").padEnd(10)} ${p.description ?? ""}${cmds}`);
+  }
+}
+
+// src/cli.ts
+function reportInstalledMigrations(migrations) {
+  if (!migrations.length) return;
+  console.log(`\u2713 Installed Night Owls's migrations into supabase/migrations/ (${migrations.length} file(s)).`);
+  console.log("  Apply them with your own tooling:  supabase db push");
+}
+var program = new Command();
+program.name("owl").description("The pluggable Night Owls CLI: scaffold a config, install adapters, and contribute their migrations to your supabase/migrations/.").version("0.0.0");
+program.command("init").argument("[plugin]", "re-init just one already-installed plugin (apply its wiring + run its init hook)").description(
+  "Scaffold nightowls.config.ts + .env.example and install the selected adapters (idempotent). With a [plugin] arg, re-init just that one plugin against the existing project."
+).option("--storage <adapter>", "storage adapter to install", "storage-supabase").option("--runner <adapter>", "runner adapter to install", "runner-nextjs").option("--no-storage", "skip installing a storage adapter").option("--no-runner", "skip installing a runner adapter").option("-y, --yes", "accept defaults (non-interactive)").action(
+  async (plugin, opts) => {
+    const cwd = process.cwd();
+    const pm = await detectPackageManager(cwd);
+    if (plugin) {
+      const pkg = toPkgName(plugin);
+      const result = await runInstall({
+        adapter: plugin,
+        root: cwd,
+        fs: await nodeFs(),
+        addDep: (p) => addDep(pm, cwd, p),
+        loadPlugin: (p) => loadPlugin(p, cwd),
+        isInstalled: (p) => isInstalled(cwd, p),
+        now: () => /* @__PURE__ */ new Date(),
+        log: console.log
+      });
+      console.log(`${result.added ? "Added" : "Found"} ${pkg}; re-applied its env/config/files.`);
+      reportInstalledMigrations(result.migrations);
+      if (result.initRan) console.log(`\u2713 Ran ${plugin}'s init hook.`);
+      return;
+    }
+    const adapters = [];
+    if (opts.storage) adapters.push(opts.storage);
+    if (opts.runner) adapters.push(opts.runner);
+    const { migrations } = await runInit({
+      root: cwd,
+      fs: await nodeFs(),
+      adapters,
+      loadPlugin: (p) => loadPlugin(p, cwd),
+      addDep: (p) => addDep(pm, cwd, p),
+      pm,
+      now: () => /* @__PURE__ */ new Date(),
+      log: console.log
+    });
+    console.log("Scaffolded nightowls.config.ts + .env.example.");
+    if (adapters.length) console.log(`Installed: ${adapters.join(", ")}.`);
+    reportInstalledMigrations(migrations);
+    console.log("Next: fill .env.local, then run your dev server.");
+  }
+);
+program.command("install").argument("<adapter>", "adapter short name, e.g. storage-supabase").description("Add a @nightowlsdev/<adapter> dependency and apply its env/config/files boilerplate (idempotent).").action(async (adapter) => {
+  const cwd = process.cwd();
+  const pm = await detectPackageManager(cwd);
+  const pkg = toPkgName(adapter);
+  const result = await runInstall({
+    adapter,
+    root: cwd,
+    fs: await nodeFs(),
+    addDep: (p) => addDep(pm, cwd, p),
+    loadPlugin: (p) => loadPlugin(p, cwd),
+    isInstalled: (p) => isInstalled(cwd, p),
+    now: () => /* @__PURE__ */ new Date(),
+    log: console.log
+  });
+  console.log(`${result.added ? "Added" : "Found"} ${pkg}; applied its env/config/files.`);
+  reportInstalledMigrations(result.migrations);
+  if (result.initRan) console.log(`\u2713 Ran ${adapter}'s init hook.`);
+  console.log("Next: fill .env.local, then run your dev server.");
+});
+var db = program.command("db").description("Manage nightowls migrations (install into your supabase/migrations, generate types).");
+db.command("types").description("Generate TypeScript types for the nightowls schema (supabase gen types).").action(async () => {
+  const out = await runDbTypes({ exec });
+  process.stdout.write(out);
+});
+db.command("install").description("Install Night Owls' migrations into your supabase/migrations/ (timestamped, idempotent) \u2014 apply them with `supabase db push`.").option("--out <dir>", "target migrations dir (relative to cwd)", "supabase/migrations").action(async (opts) => {
+  const cwd = process.cwd();
+  const plugins = await discoverPlugins(nodeDiscoverDeps(cwd));
+  const { written, skipped } = await runDbInstall({
+    plugins,
+    root: cwd,
+    out: opts.out,
+    fs: await nodeFs(),
+    now: () => /* @__PURE__ */ new Date()
+  });
+  for (const w of written) console.log(`wrote ${opts.out}/${w.file}`);
+  for (const version of skipped) console.log(`skipped ${version} (already installed)`);
+  if (!written.length) console.log("Nothing to install \u2014 all nightowls migrations already present.");
+});
+program.command("plugins").description("List installed Night Owls plugins and the commands they expose.").action(async () => {
+  const cwd = process.cwd();
+  const plugins = await discoverPlugins(nodeDiscoverDeps(cwd));
+  runPluginsList(plugins, console.log);
+});
+program.command("mcp").description("Run the Night Owls MCP server on stdio (exposes nightowls_* tools to external agents).").action(async () => {
+  const { runMcpServer } = await import("./mcp-3ZFDXVDT.js");
+  await runMcpServer();
+});
+async function main() {
+  const cwd = process.cwd();
+  const plugins = await discoverPlugins(nodeDiscoverDeps(cwd)).catch(() => []);
+  registerPluginCommands(program, plugins, { cwd, log: console.log });
+  await program.parseAsync();
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The declarative Night Owls plugin contract.
+ *
+ * Each `@nightowlsdev/*` adapter exports a `nightOwlsPlugin` plain object that STRUCTURALLY matches
+ * `NightOwlsPlugin` — adapters do NOT import this type (that would create a dependency cycle, since the
+ * CLI also imports the adapters). All codegen (env merge, file scaffold, config insertion, migrations)
+ * lives in the CLI; adapters stay data-only.
+ */
+/** A single Night Owls migration: a stable `version` (ledger key), a human `name`, and `nightowls.*` SQL. */
+interface Migration {
+    version: string;
+    name: string;
+    sql: string;
+}
+/** An environment variable the adapter needs. Appended to `.env.example` if its `key` is absent. */
+interface PluginEnv {
+    key: string;
+    example: string;
+    comment?: string;
+}
+/** A file scaffolded into the host (e.g. a Next.js route handler). Written only if absent (idempotent). */
+interface PluginFile {
+    path: string;
+    contents: string;
+}
+/** The `import` line + the wiring `snippet` inserted at the `// nightowls:<marker>` line in the config. */
+interface PluginConfig {
+    import: string;
+    snippet: string;
+    marker: "storage" | "auth" | "runner" | "telemetry" | "connector" | "model";
+}
+/**
+ * Context passed to a plugin's `init` hook and command handlers. Structural — adapters type their
+ * handlers against an equivalent shape WITHOUT importing @nightowlsdev/cli (keeps their .d.ts cycle-free).
+ */
+interface PluginContext {
+    /** The host project root (cwd). */
+    cwd: string;
+    /** Print a line to the user. */
+    log: (msg: string) => void;
+}
+/** The context a plugin command's `run` receives — the base context plus the parsed argv. */
+interface PluginCommandContext extends PluginContext {
+    /** Positional args after `owl <plugin> <cmd>`. */
+    args: string[];
+    /** Parsed `--flag` options. */
+    options: Record<string, unknown>;
+}
+/** A flag a plugin command accepts (declarative; registered on the Commander subcommand). */
+interface PluginOption {
+    /** e.g. "--json" or "--out <dir>". */
+    flags: string;
+    description: string;
+    defaultValue?: string | boolean;
+}
+/** A subcommand a plugin exposes, run as `owl <plugin-name> <command-name>`. */
+interface PluginCommand {
+    name: string;
+    description: string;
+    options?: readonly PluginOption[];
+    /** Self-contained: uses only the ctx + the adapter's own logic + Node. MUST NOT import @nightowlsdev/cli. */
+    run: (ctx: PluginCommandContext) => Promise<void> | void;
+}
+/** The full adapter manifest the CLI discovers, dynamic-imports, and acts on. */
+interface NightOwlsPlugin {
+    /** Adapter short name, e.g. "storage-supabase". */
+    name: string;
+    version: string;
+    kind?: "storage" | "runner" | "auth" | "telemetry" | "ui" | "connector" | "model";
+    /** npm name, e.g. "@nightowlsdev/storage-supabase". */
+    pkg: string;
+    /** One-line summary shown by `owl plugins` and `owl <plugin> --help`. */
+    description?: string;
+    migrations?: readonly Migration[];
+    env?: readonly PluginEnv[];
+    files?: readonly PluginFile[];
+    config?: PluginConfig;
+    /**
+     * Runs during `owl init`, `owl install <plugin>`, and `owl init <plugin>` — AFTER the
+     * declarative wiring. For integration that can't be expressed declaratively (idempotent; print-only
+     * side effects preferred — never apply DDL).
+     */
+    init?: (ctx: PluginContext) => Promise<void> | void;
+    /** Plugin-specific subcommands, exposed as `owl <plugin-name> <command-name>`. */
+    commands?: readonly PluginCommand[];
+}
+
+interface DiscoverDeps {
+    readPkgJson: () => Promise<{
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+    }>;
+    importPlugin: (pkg: string) => Promise<{
+        nightOwlsPlugin?: NightOwlsPlugin;
+    }>;
+}
+/**
+ * Discover installed `@nightowlsdev/*` adapters that export a `nightOwlsPlugin` manifest. Injected deps keep this
+ * hermetic (tests pass fakes; production uses `nodeDiscoverDeps`). `@nightowlsdev/*` deps without a manifest
+ * (e.g. `@nightowlsdev/react`) are silently ignored.
+ */
+declare function discoverPlugins(deps: DiscoverDeps): Promise<NightOwlsPlugin[]>;
+/** Production deps: read `<cwd>/package.json` + dynamic-import each adapter's manifest resolved from the
+ *  HOST cwd (so a real host's installed adapters are discovered, not the CLI's own deps). */
+declare function nodeDiscoverDeps(cwd: string): DiscoverDeps;
+
+export { type DiscoverDeps, type Migration, type NightOwlsPlugin, type PluginCommand, type PluginCommandContext, type PluginConfig, type PluginContext, type PluginEnv, type PluginFile, type PluginOption, discoverPlugins, nodeDiscoverDeps };

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {
+  discoverPlugins,
+  nodeDiscoverDeps
+} from "./chunk-E2C2JZ2E.js";
+export {
+  discoverPlugins,
+  nodeDiscoverDeps
+};

package/dist/mcp-3ZFDXVDT.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+// src/commands/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMastraLibsqlStore } from "@nightowlsdev/storage-local";
+function doctorReport() {
+  const bootstrapStore = createMastraLibsqlStore({ url: ":memory:" });
+  return {
+    ok: true,
+    bootstrapStore: bootstrapStore ? "available (libsql :memory:)" : "unavailable",
+    node: process.version,
+    cwd: process.cwd()
+  };
+}
+function buildMcpServer() {
+  const server = new McpServer({ name: "nightowls", version: "0.0.0" });
+  server.registerTool(
+    "nightowls_doctor",
+    {
+      title: "Night Owls doctor",
+      description: "Report Night Owls environment diagnostics (read-only).",
+      annotations: { readOnlyHint: true }
+    },
+    async () => ({ content: [{ type: "text", text: JSON.stringify(doctorReport(), null, 2) }] })
+  );
+  return server;
+}
+async function runMcpServer() {
+  const server = buildMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[nightowls] mcp server ready on stdio (nightowls_doctor)");
+}
+export {
+  buildMcpServer,
+  doctorReport,
+  runMcpServer
+};

package/dist/node-EVZ52KTR.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import {
+  addDep,
+  detectPackageManager,
+  exec,
+  hostImport,
+  isInstalled,
+  loadPlugin,
+  nodeFs
+} from "./chunk-YZIYBDZO.js";
+export {
+  addDep,
+  detectPackageManager,
+  exec,
+  hostImport,
+  isInstalled,
+  loadPlugin,
+  nodeFs
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nightowlsdev/cli",
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "owl": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cueplusplus/corale.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/cueplusplus/corale#readme",
+  "dependencies": {
+    "commander": "^15.0.0",
+    "ts-morph": "^28.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@nightowlsdev/storage-local": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "memfs": "^4.57.0",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "^3.2.0",
+    "@nightowlsdev/storage-supabase": "0.3.0",
+    "@nightowlsdev/core": "0.3.0",
+    "@nightowlsdev/telemetry-otel": "0.1.1",
+    "@nightowlsdev/telemetry-langfuse": "0.1.1",
+    "@nightowlsdev/runner-nextjs": "0.2.0",
+    "@nightowlsdev/runner-background": "0.2.0",
+    "@nightowlsdev/model-anthropic": "0.1.0",
+    "@nightowlsdev/auth-supabase": "0.1.1",
+    "@nightowlsdev/auth-auth0": "0.1.1",
+    "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/mcp": "0.1.1",
+    "@nightowlsdev/tsconfig": "0.0.0",
+    "@nightowlsdev/model-openai": "0.1.0",
+    "@nightowlsdev/model-vercel-gateway": "0.1.0",
+    "@nightowlsdev/model-openrouter": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}