agnes-cli 0.0.1

package/README.md

@@ -0,0 +1,140 @@
+# agnes-cli
+
+Schema toolkit for **agnes-rs**. Reads your TypeScript `schema.ts` DSL and keeps
+your database in sync — `push`, `pull`, and `migrate`. Runs on [Bun](https://bun.sh)
+and talks to the database through the same Rust bridge (`agnes-library`), so it
+supports **PostgreSQL, MySQL and SQLite**.
+
+## Install
+
+Inside this workspace it's already linked. From a consumer project:
+
+```bash
+bun add agnes-cli agnes-library
+```
+
+## Configure
+
+Create `agnes.config.ts` in your project root (see `agnes.config.example.ts`):
+
+```ts
+import { defineConfig } from "agnes-cli";
+import { schema } from "./schema"; // your `export const schema = { ... }`
+
+export default defineConfig({
+  driver: "postgres",
+  url: process.env.DATABASE_URL!,
+  schema,
+  out: "./schema.ts",          // where `pull` writes
+  migrationsDir: "./migrations",
+
+  // `generate` output — extension picks the language (.ts or .js)
+  output: "src/services/db.ts",
+  schemaPath: "./schema.ts",   // module the generated client imports `schema` from
+  cache: { enabled: true, walPath: ".agnes/cache.wal" },
+});
+```
+
+## Commands
+
+```bash
+bun agnes push        # make the DB match schema.ts (create/alter/DROP)
+bun agnes pull        # regenerate schema.ts from the live DB
+bun agnes migrate     # write a versioned .sql from drift, then apply pending
+bun agnes generate    # emit a pre-wired AgnesClient module (db.ts / db.js)
+```
+
+(From the repo root: `bun run agnes push`.)
+
+### `push` — schema.ts ➜ database
+
+Diffs your schema against the live database and applies the difference. This is a
+**full sync**: tables and columns that exist in the DB but not in your schema are
+**dropped**. Destructive operations (`DROP TABLE` / `DROP COLUMN`) require an
+interactive confirmation — pass `-y` / `--yes` to skip it in CI.
+
+```bash
+bun agnes push --dry-run   # print the plan + SQL, change nothing
+bun agnes push --yes       # apply without prompting
+```
+
+### `pull` — database ➜ schema.ts
+
+Introspects the live database and regenerates `schema.ts` to mirror it exactly
+(tables/columns/indexes/foreign keys no longer present are removed from the file).
+Prompts before overwriting an existing file unless `--yes`.
+
+```bash
+bun agnes pull --out src/schema.ts
+```
+
+### `migrate` — versioned SQL files
+
+1. Diffs schema vs DB and, if there's drift, writes a timestamped file to
+   `migrationsDir` (e.g. `20260701123000_auto.sql`).
+2. Applies every pending file (those not yet recorded in the `_agnes_migrations`
+   tracking table) in order, recording each as it succeeds.
+
+Destructive migrations prompt for confirmation unless `--yes`.
+
+```bash
+bun agnes migrate -n add_users     # name the generated migration
+bun agnes migrate --dry-run        # show what would be generated/applied
+```
+
+### `generate` — pre-wired client module
+
+Writes a ready-to-import `AgnesClient` module built from your config — driver,
+url and cache all baked in. Point `output` anywhere (nested dirs are created):
+
+```ts
+// src/services/db.ts  ← generated
+import { AgnesClient } from "agnes-library";
+import { schema } from "../../schema";
+
+export const db = await AgnesClient.create(
+  {
+    driver: "sqlite",
+    url: "sqlite:./demo.db",
+    cache: { enabled: true, walPath: ".agnes/cache.wal" },
+  },
+  schema,
+);
+```
+
+- `output` (config) or `--output` picks the path. `.ts` → TypeScript, `.js` → JavaScript.
+- The `import { schema }` path is made relative to the output file automatically.
+- The `cache` block is emitted only if you set `cache` in the config.
+
+```bash
+bun agnes generate                       # uses config.output
+bun agnes generate --output src/db.js    # override; JS output
+```
+
+## Options
+
+| Flag | Applies to | Meaning |
+|------|-----------|---------|
+| `-c, --config <path>` | all | Config file (default `agnes.config.ts`) |
+| `-o, --out <path>` | pull | Output schema file |
+| `--output <path>` | generate | Output client module (.ts/.js) |
+| `--dir <path>` | migrate | Migrations directory |
+| `-n, --name <name>` | migrate | Name for the generated migration |
+| `-y, --yes` | push, pull, migrate | Skip destructive confirmations |
+| `--dry-run` | push, migrate | Show the plan/SQL without executing |
+
+## Type mapping
+
+| DSL | PostgreSQL | MySQL | SQLite |
+|-----|-----------|-------|--------|
+| `int` | integer | int | integer |
+| `bigint` | bigint | bigint | integer |
+| `text` | text | text | text |
+| `bool` | boolean | tinyint(1) | integer |
+| `float` | double precision | double | real |
+| `bytes` | bytea | blob | blob |
+| `json` | jsonb | json | text |
+
+> **SQLite note:** SQLite can't `ALTER` column types or add/drop foreign keys after
+> table creation. Those operations are emitted as `-- SKIPPED` comments; recreate
+> the table manually if you need them.

package/agnes.config.example.ts

@@ -0,0 +1,50 @@
+import { defineConfig } from "agnes-cli";
+import {
+  table,
+  int,
+  text,
+  bool,
+  many,
+  one,
+  OnAction,
+} from "agnes-library";
+
+// Your schema. Can live here or be imported from ./schema.ts.
+export const schema = {
+  user: table(
+    {
+      id: int("id").primary(),
+      name: text("name").index("name_idx"),
+      email: text("email").uniqueIndex("email_idx"),
+      age: int("age"),
+      active: bool("active").default(true),
+      posts: many("post", "userId"),
+    },
+    "users",
+  ),
+  post: table(
+    {
+      id: int("id").primary(),
+      userId: int("user_id"),
+      content: text("content"),
+      user: one("user", "userId", "id", OnAction.None, OnAction.Cascade),
+    },
+    "posts",
+  ),
+};
+
+export default defineConfig({
+  driver: "postgres",
+  url: process.env.DATABASE_URL ?? "postgres://user:pass@localhost/db",
+  schema,
+  out: "./schema.ts",
+  migrationsDir: "./migrations",
+
+  // `agnes generate` writes the ready-to-import client here.
+  // Extension picks the language: db.ts → TypeScript, db.js → JavaScript.
+  output: "src/services/db.ts",
+  // Module the generated client imports `schema` from (default: `out`).
+  schemaPath: "./agnes.config.ts",
+  // Cache baked into the generated client.
+  cache: { enabled: true, walPath: ".agnes/cache.wal" },
+});

package/bin/agnes.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { run } from "../src/cli";
+
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "agnes-cli",
+  "version": "0.0.1",
+  "description": "Schema migration CLI for agnes-rs — push, pull and migrate from schema.ts",
+  "type": "module",
+  "bin": {
+    "agnes": "./bin/agnes.ts"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "bin",
+    "agnes.config.example.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "agnes": "bun bin/agnes.ts",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "agnes-library": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/apply.ts

@@ -0,0 +1,64 @@
+import type { Dialect } from "./dialect";
+import type { CliDb } from "./db";
+import { isDestructive, type Operation } from "./diff";
+import { describeOperation, renderPlan } from "./generate";
+import { c, confirm } from "./prompt";
+
+export interface ApplyOpts {
+  yes?: boolean;
+  dryRun?: boolean;
+}
+
+/**
+ * Print the diff plan, confirm destructive operations, then execute the SQL.
+ * Returns the SQL statements that were (or would be) run.
+ */
+export async function applyPlan(
+  db: CliDb,
+  dialect: Dialect,
+  ops: Operation[],
+  opts: ApplyOpts = {},
+): Promise<string[]> {
+  if (ops.length === 0) {
+    console.log(c.green("✓ Database is up to date. Nothing to apply."));
+    return [];
+  }
+
+  console.log(c.bold("\nPlan:"));
+  for (const op of ops) {
+    const line = describeOperation(op);
+    console.log("  " + (isDestructive(op) ? c.red(line) : c.green(line)));
+  }
+
+  const statements = renderPlan(dialect, ops);
+
+  if (opts.dryRun) {
+    console.log(c.bold("\nSQL (dry run):"));
+    for (const s of statements) console.log(c.dim(s));
+    return statements;
+  }
+
+  const destructive = ops.filter(isDestructive);
+  if (destructive.length > 0 && !opts.yes) {
+    console.log(
+      c.yellow(`\n⚠ ${destructive.length} destructive operation(s) will delete data or objects.`),
+    );
+    const ok = await confirm("Apply these changes?");
+    if (!ok) {
+      console.log(c.dim("Aborted. No changes made."));
+      return [];
+    }
+  }
+
+  console.log(c.bold("\nApplying..."));
+  for (const sql of statements) {
+    if (sql.startsWith("--")) {
+      console.log(c.yellow("  " + sql));
+      continue;
+    }
+    await db.mutate(sql);
+    console.log(c.dim("  ✓ " + sql.split("\n")[0]));
+  }
+  console.log(c.green(`\n✓ Applied ${statements.filter((s) => !s.startsWith("--")).length} statement(s).`));
+  return statements;
+}

package/src/cli.ts

@@ -0,0 +1,116 @@
+import { loadConfig } from "./config";
+import { push } from "./commands/push";
+import { pull } from "./commands/pull";
+import { migrate } from "./commands/migrate";
+import { generate } from "./commands/generate";
+import { c } from "./prompt";
+
+interface Flags {
+  _: string[];
+  config?: string;
+  out?: string;
+  output?: string;
+  dir?: string;
+  name?: string;
+  yes: boolean;
+  dryRun: boolean;
+}
+
+function parseArgs(argv: string[]): Flags {
+  const flags: Flags = { _: [], yes: false, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    switch (a) {
+      case "-y":
+      case "--yes":
+        flags.yes = true;
+        break;
+      case "--dry-run":
+        flags.dryRun = true;
+        break;
+      case "-c":
+      case "--config":
+        flags.config = argv[++i];
+        break;
+      case "-o":
+      case "--out":
+        flags.out = argv[++i];
+        break;
+      case "--output":
+        flags.output = argv[++i];
+        break;
+      case "--dir":
+        flags.dir = argv[++i];
+        break;
+      case "-n":
+      case "--name":
+        flags.name = argv[++i];
+        break;
+      default:
+        flags._.push(a);
+    }
+  }
+  return flags;
+}
+
+const HELP = `${c.bold("agnes")} — schema toolkit for agnes-rs
+
+${c.bold("Usage:")}
+  agnes <command> [options]
+
+${c.bold("Commands:")}
+  push       Sync the database to match schema.ts (create/alter/drop)
+  pull       Introspect the database and (re)generate schema.ts
+  migrate    Generate a versioned SQL migration from drift, then apply pending
+  generate   Emit a pre-wired AgnesClient module (db.ts/db.js) from the config
+
+${c.bold("Options:")}
+  -c, --config <path>   Config file (default: agnes.config.ts)
+  -o, --out <path>      [pull] Output schema file (default: config.out or schema.ts)
+      --output <path>   [generate] Output client module (default: config.output)
+      --dir <path>      [migrate] Migrations directory (default: migrations)
+  -n, --name <name>     [migrate] Name for the generated migration
+  -y, --yes             Skip confirmation for destructive operations
+      --dry-run         Show the plan/SQL without executing
+  -h, --help            Show this help
+`;
+
+export async function run(argv: string[]): Promise<void> {
+  const flags = parseArgs(argv);
+  const command = flags._[0];
+
+  if (!command || flags._.includes("help") || argv.includes("-h") || argv.includes("--help")) {
+    console.log(HELP);
+    return;
+  }
+
+  try {
+    const config = await loadConfig(flags.config);
+    switch (command) {
+      case "push":
+        await push(config, { yes: flags.yes, dryRun: flags.dryRun });
+        break;
+      case "pull":
+        await pull(config, { out: flags.out, yes: flags.yes });
+        break;
+      case "migrate":
+        await migrate(config, {
+          yes: flags.yes,
+          dryRun: flags.dryRun,
+          dir: flags.dir,
+          name: flags.name,
+        });
+        break;
+      case "generate":
+        await generate(config, { output: flags.output, yes: flags.yes });
+        break;
+      default:
+        console.error(c.red(`Unknown command: ${command}`));
+        console.log(HELP);
+        process.exitCode = 1;
+    }
+  } catch (err) {
+    console.error(c.red(`\n✗ ${err instanceof Error ? err.message : String(err)}`));
+    process.exitCode = 1;
+  }
+}

package/src/commands/generate.ts

@@ -0,0 +1,74 @@
+import { dirname, relative, resolve } from "node:path";
+import type { AgnesConfig } from "../config";
+import { c } from "../prompt";
+
+export interface GenerateArgs {
+  output?: string;
+  yes?: boolean;
+}
+
+/** Turn a filesystem path into a relative ESM import specifier (no extension). */
+function toImportSpecifier(fromFile: string, toModule: string): string {
+  let rel = relative(dirname(fromFile), toModule).replace(/\\/g, "/");
+  rel = rel.replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, "");
+  if (!rel.startsWith(".")) rel = `./${rel}`;
+  return rel;
+}
+
+function renderConfigObject(config: AgnesConfig): string {
+  const lines: string[] = [
+    `    driver: ${JSON.stringify(config.driver)},`,
+    `    url: ${JSON.stringify(config.url)},`,
+  ];
+  if (config.maxConnections !== undefined)
+    lines.push(`    maxConnections: ${config.maxConnections},`);
+  if (config.cache) {
+    const parts = [`enabled: ${config.cache.enabled}`];
+    if (config.cache.walPath !== undefined) parts.push(`walPath: ${JSON.stringify(config.cache.walPath)}`);
+    if (config.cache.compactionThreshold !== undefined)
+      parts.push(`compactionThreshold: ${config.cache.compactionThreshold}`);
+    lines.push(`    cache: { ${parts.join(", ")} },`);
+  }
+  return lines.join("\n");
+}
+
+function renderClient(config: AgnesConfig, schemaImport: string): string {
+  return (
+    `// Generated by \`agnes generate\`. Do not edit — re-run to regenerate.\n` +
+    `import { AgnesClient } from "agnes-library";\n` +
+    `import { schema } from ${JSON.stringify(schemaImport)};\n\n` +
+    `export const db = await AgnesClient.create(\n` +
+    `  {\n${renderConfigObject(config)}\n  },\n` +
+    `  schema,\n` +
+    `);\n`
+  );
+}
+
+/** Emit a ready-to-import AgnesClient module wired to the config. */
+export async function generate(config: AgnesConfig, args: GenerateArgs): Promise<void> {
+  const outRel = args.output ?? config.output;
+  if (!outRel) {
+    throw new Error(
+      `No output path. Set \`output\` in agnes.config.ts (e.g. "src/services/db.ts") or pass --output <path>.`,
+    );
+  }
+
+  const outPath = resolve(process.cwd(), outRel);
+  const schemaFsPath = resolve(process.cwd(), config.schemaPath ?? config.out ?? "schema.ts");
+  const schemaImport = toImportSpecifier(outPath, schemaFsPath);
+
+  const source = renderClient(config, schemaImport);
+
+  if (await Bun.file(outPath).exists() && !args.yes) {
+    console.log(c.yellow(`⚠ ${outPath} already exists and will be overwritten.`));
+    const { confirm } = await import("../prompt");
+    if (!(await confirm("Overwrite it?"))) {
+      console.log(c.dim("Aborted. File left unchanged."));
+      return;
+    }
+  }
+
+  await Bun.write(outPath, source);
+  console.log(c.green(`✓ Generated client → ${outPath}`));
+  console.log(c.dim(`  imports schema from ${schemaImport}`));
+}

package/src/commands/migrate.ts

@@ -0,0 +1,146 @@
+import { resolve } from "node:path";
+import { readdir } from "node:fs/promises";
+import type { AgnesConfig } from "../config";
+import type { Dialect } from "../dialect";
+import { openDb, type CliDb } from "../db";
+import { diffSchemas } from "../diff";
+import { renderPlan } from "../generate";
+import { schemaToIR } from "../ir";
+import { normalizeIR } from "../normalize";
+import { introspect } from "../introspect";
+import { c, confirm } from "../prompt";
+
+export interface MigrateArgs {
+  yes?: boolean;
+  dryRun?: boolean;
+  dir?: string;
+  name?: string;
+}
+
+const DESTRUCTIVE = /\bDROP\s+(TABLE|COLUMN|CONSTRAINT|FOREIGN\s+KEY)\b/i;
+
+function trackingTableDdl(dialect: Dialect): string {
+  const nameType = dialect === "mysql" ? "VARCHAR(255)" : "TEXT";
+  return (
+    `CREATE TABLE IF NOT EXISTS _agnes_migrations (` +
+    `name ${nameType} PRIMARY KEY, ` +
+    `applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP)`
+  );
+}
+
+function timestamp(): string {
+  const d = new Date();
+  const p = (n: number, w = 2) => String(n).padStart(w, "0");
+  return (
+    `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}` +
+    `${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+  );
+}
+
+function splitStatements(sql: string): string[] {
+  return sql
+    .split(";")
+    // Strip full-line SQL comments so a leading `-- header` doesn't swallow the
+    // statement that follows it on the next line.
+    .map((chunk) =>
+      chunk
+        .split("\n")
+        .filter((line) => !line.trim().startsWith("--"))
+        .join("\n")
+        .trim(),
+    )
+    .filter((s) => s.length > 0);
+}
+
+/** Generate a new migration from schema drift, then apply all pending files. */
+export async function migrate(config: AgnesConfig, args: MigrateArgs): Promise<void> {
+  console.log(c.cyan(`agnes migrate → ${config.driver}`));
+  const db = await openDb(config);
+  const dir = resolve(process.cwd(), args.dir ?? config.migrationsDir ?? "migrations");
+
+  await db.mutate(trackingTableDdl(config.driver));
+
+  // 1. Detect drift and write a new migration file.
+  const desired = normalizeIR(schemaToIR(config.schema), config.driver);
+  const current = normalizeIR(await introspect(db, config.driver), config.driver);
+  const ops = diffSchemas(desired, current);
+
+  if (ops.length > 0) {
+    const statements = renderPlan(config.driver, ops);
+    const fileName = `${timestamp()}_${args.name ?? "auto"}.sql`;
+    const filePath = resolve(dir, fileName);
+    const body = statements.map((s) => (s.startsWith("--") ? s : `${s}`)).join("\n\n") + "\n";
+
+    if (args.dryRun) {
+      console.log(c.bold(`\nWould create ${fileName}:`));
+      console.log(c.dim(body));
+    } else {
+      await Bun.write(filePath, `-- Migration ${fileName}\n-- Generated by \`agnes migrate\`\n\n${body}`);
+      console.log(c.green(`✓ Created migration ${fileName} (${statements.length} statement(s))`));
+    }
+  } else {
+    console.log(c.dim("No schema drift — no new migration generated."));
+  }
+
+  // 2. Apply pending migration files.
+  await applyPending(db, config.driver, dir, args);
+}
+
+async function applyPending(
+  db: CliDb,
+  dialect: Dialect,
+  dir: string,
+  args: MigrateArgs,
+): Promise<void> {
+  let files: string[];
+  try {
+    files = (await readdir(dir)).filter((f) => f.endsWith(".sql")).sort();
+  } catch {
+    files = [];
+  }
+
+  const appliedRows = await db.query<{ name: string }>(`SELECT name FROM _agnes_migrations`);
+  const applied = new Set(appliedRows.map((r) => String(r.name)));
+  const pending = files.filter((f) => !applied.has(f));
+
+  if (pending.length === 0) {
+    console.log(c.green("\n✓ No pending migrations."));
+    return;
+  }
+
+  console.log(c.bold(`\nPending migrations (${pending.length}):`));
+  for (const f of pending) console.log("  " + c.green(f));
+
+  if (args.dryRun) {
+    console.log(c.dim("\nDry run — not applied."));
+    return;
+  }
+
+  // Confirm if any pending file contains destructive statements.
+  const bodies = new Map<string, string>();
+  let anyDestructive = false;
+  for (const f of pending) {
+    const text = await Bun.file(resolve(dir, f)).text();
+    bodies.set(f, text);
+    if (DESTRUCTIVE.test(text)) anyDestructive = true;
+  }
+
+  if (anyDestructive && !args.yes) {
+    console.log(c.yellow("\n⚠ Some pending migrations contain destructive statements (DROP)."));
+    const ok = await confirm("Apply all pending migrations?");
+    if (!ok) {
+      console.log(c.dim("Aborted. No migrations applied."));
+      return;
+    }
+  }
+
+  for (const f of pending) {
+    console.log(c.bold(`\nApplying ${f}...`));
+    for (const stmt of splitStatements(bodies.get(f)!)) {
+      await db.mutate(stmt);
+      console.log(c.dim("  ✓ " + stmt.split("\n")[0]));
+    }
+    await db.mutate(`INSERT INTO _agnes_migrations (name) VALUES (${dialect === "postgres" ? "$1" : "?"})`, [f]);
+  }
+  console.log(c.green(`\n✓ Applied ${pending.length} migration(s).`));
+}

package/src/commands/pull.ts

@@ -0,0 +1,38 @@
+import { resolve } from "node:path";
+import type { AgnesConfig } from "../config";
+import { openDb } from "../db";
+import { introspect } from "../introspect";
+import { printSchema } from "../print";
+import { c, confirm } from "../prompt";
+
+export interface PullArgs {
+  out?: string;
+  yes?: boolean;
+}
+
+/** Introspect the database and (re)generate schema.ts to mirror it. */
+export async function pull(config: AgnesConfig, args: PullArgs): Promise<void> {
+  console.log(c.cyan(`agnes pull ← ${config.driver}`));
+  const db = await openDb(config);
+
+  const current = await introspect(db, config.driver);
+  const tableCount = Object.keys(current).length;
+  const source = printSchema(current);
+
+  const outPath = resolve(process.cwd(), args.out ?? config.out ?? "schema.ts");
+  const exists = await Bun.file(outPath).exists();
+
+  console.log(c.green(`\n✓ Introspected ${tableCount} table(s).`));
+
+  if (exists && !args.yes) {
+    console.log(c.yellow(`\n⚠ ${outPath} already exists and will be overwritten.`));
+    const ok = await confirm("Overwrite it?");
+    if (!ok) {
+      console.log(c.dim("Aborted. File left unchanged."));
+      return;
+    }
+  }
+
+  await Bun.write(outPath, source);
+  console.log(c.green(`✓ Wrote ${outPath}`));
+}

package/src/commands/push.ts

@@ -0,0 +1,25 @@
+import { applyPlan } from "../apply";
+import type { AgnesConfig } from "../config";
+import { openDb } from "../db";
+import { diffSchemas } from "../diff";
+import { schemaToIR } from "../ir";
+import { normalizeIR } from "../normalize";
+import { introspect } from "../introspect";
+import { c } from "../prompt";
+
+export interface PushArgs {
+  yes?: boolean;
+  dryRun?: boolean;
+}
+
+/** Sync the database to match schema.ts (create/alter/drop). */
+export async function push(config: AgnesConfig, args: PushArgs): Promise<void> {
+  console.log(c.cyan(`agnes push → ${config.driver}`));
+  const db = await openDb(config);
+
+  const desired = normalizeIR(schemaToIR(config.schema), config.driver);
+  const current = normalizeIR(await introspect(db, config.driver), config.driver);
+  const ops = diffSchemas(desired, current);
+
+  await applyPlan(db, config.driver, ops, args);
+}