@better-schemic/cli 0.1.0-alpha.1

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@better-schemic/cli",
+  "version": "0.1.0-alpha.1",
+  "description": "The Better-schemic CLI — driver-agnostic schema migrations (gen/migrate/diff/push/pull/check).",
+  "license": "MIT",
+  "author": "Vertio Solutions",
+  "homepage": "https://github.com/NONSTANDARDCODE/better-schemic",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NONSTANDARDCODE/better-schemic.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "better-schemic": "lib/cli.js",
+    "sc": "lib/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "src",
+    "LICENSE"
+  ],
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "bun run build",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check ."
+  },
+  "dependencies": {
+    "@better-schemic/core": "0.1.0-alpha.1",
+    "commander": "^14.0.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@better-schemic/surrealdb": "0.1.0-alpha.1",
+    "@types/bun": "latest",
+    "surrealdb": "^2.0.3",
+    "tsup": "^8",
+    "typescript": "^5",
+    "zod": "^4.3.5"
+  }
+}

package/src/cli/action.ts

@@ -0,0 +1,40 @@
+// Shared command-action runner: execute an action to completion, format any error the same way across
+// EVERY command (built-ins, driver `sc <kind> <verb>`, and the inspect ls/info), and force `process.exit`
+// once it settles so a lingering SDK connection handle can't keep the process alive.
+// BETTER_SCHEMIC_DEBUG=1 (legacy: SCHEMIC_DEBUG=1) or --stack prints the full stack + the `.cause`
+// chain; otherwise a one-line hint. Watch commands return a never-settling promise, so they keep
+// running until SIGINT.
+import { fail, style } from "@better-schemic/core";
+
+// Legacy `SCHEMIC_DEBUG` still works; the `BETTER_SCHEMIC_` spelling wins when both are set.
+const debugEnabled = (): boolean =>
+  !!process.env.BETTER_SCHEMIC_DEBUG || !!process.env.SCHEMIC_DEBUG;
+
+const errMsg = (err: unknown) =>
+  err instanceof Error ? err.message : String(err);
+
+/** Run `action`, then exit (0 on success / the set exitCode; 1 on a thrown error, printed cleanly). */
+export function runAction(action: () => Promise<void>): void {
+  action().then(
+    () => process.exit(process.exitCode ?? 0),
+    (err: unknown) => {
+      console.error(`\n${fail(errMsg(err))}`);
+      if (debugEnabled() || process.argv.includes("--stack")) {
+        for (let e: unknown = err, depth = 0; e && depth < 8; depth++) {
+          console.error(
+            style.dim(e instanceof Error ? (e.stack ?? String(e)) : String(e)),
+          );
+          e = e instanceof Error ? e.cause : undefined;
+          if (e) console.error(style.dim("caused by:"));
+        }
+      } else {
+        console.error(
+          style.dim(
+            "(re-run with BETTER_SCHEMIC_DEBUG=1 or --stack for the stack trace)",
+          ),
+        );
+      }
+      process.exit(1);
+    },
+  );
+}

package/src/cli/driver-commands.ts

@@ -0,0 +1,195 @@
+// Dispatch for DRIVER-CONTRIBUTED CLI commands — `sc <kind> <verb> [args]` (e.g. surreal
+// `sc access rotate <name>`). Core owns ONLY this mechanism:
+// it discovers `driver.commands`, registers each under its kind, parses argv, resolves the connection,
+// and dispatches to `command.run` with a CommandContext. The driver owns each kind/verb's meaning.
+//
+// Driver commands are DISCOVERED LAZILY: the driver is loaded from the project's config, so this
+// registration runs (async) before `program.parse()`. With no config (e.g. `sc init`), it no-ops.
+
+import { createInterface } from "node:readline/promises";
+import {
+  type CommandContext,
+  type CommandIo,
+  type DriverCommand,
+  envSecretProvider,
+  fail,
+  getDriver,
+  loadProject,
+  ok,
+  type ParsedCommandArgs,
+  style,
+} from "@better-schemic/core";
+import type { Command } from "commander";
+import { runAction } from "./action";
+import { registerInspectVerbs } from "./inspect";
+import { ensureDriver, type ResolveOpts, resolveOne } from "./resolve";
+
+/** Stdio + prompt helpers handed to a command, so a driver never touches stdio directly. */
+const io: CommandIo = {
+  ok: (m) => console.log(ok(m)),
+  fail: (m) => console.error(fail(m)),
+  info: (m) => console.log(m),
+  async prompt(question, opts) {
+    if (!process.stdin.isTTY)
+      throw new Error(
+        `"${question}" needs an interactive terminal (no value was provided non-interactively)`,
+      );
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    try {
+      // `hidden` masks typed input (e.g. a password) so it never echoes to the screen.
+      if (opts?.hidden) {
+        const out = process.stdout;
+        const onData = () => out.write("\r");
+        process.stdin.on("data", onData);
+        try {
+          return (await rl.question(`${question} `)).trim();
+        } finally {
+          process.stdin.off("data", onData);
+        }
+      }
+      return (await rl.question(`${question} `)).trim();
+    } finally {
+      rl.close();
+    }
+  },
+};
+
+/** Pre-scan argv for `-c`/`--config <path>` so registration loads the right project's driver. */
+function configFromArgv(argv: string[]): string | undefined {
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "-c" || argv[i] === "--config") return argv[i + 1];
+    if (argv[i].startsWith("--config="))
+      return argv[i].slice("--config=".length);
+  }
+  return undefined;
+}
+
+/**
+ * Parse a command's raw positionals + commander option bag into {@link ParsedCommandArgs}, per the
+ * command's declared `args`. Core collects ALL positionals (the driver validates arity); flags become
+ * a string (value-flag) or boolean. Throws if a `required` flag is missing. Pure — unit-testable.
+ */
+export function toParsedArgs(
+  cmd: DriverCommand,
+  positionals: string[],
+  opts: Record<string, unknown>,
+): ParsedCommandArgs {
+  const flags: ParsedCommandArgs["flags"] = {};
+  for (const f of cmd.args?.flags ?? []) {
+    const v = opts[f.name];
+    flags[f.name] = f.value
+      ? (v as string | undefined)
+      : (v as boolean) === true;
+    if (f.required && (v === undefined || v === false))
+      throw new Error(`\`sc ${cmd.kind} ${cmd.verb}\` requires --${f.name}`);
+  }
+  return { positionals, flags };
+}
+
+/** Register one driver command as `sc <kind> <verb>` under its (shared) kind group. */
+function addCommand(
+  kindGroup: Command,
+  cmd: DriverCommand,
+  resolveOpts: () => ResolveOpts,
+): void {
+  // Positionals are always collected raw (variadic) and the DRIVER validates arity; the declared
+  // `args.positionals` shape only feeds the usage line + help.
+  const usage = (cmd.args?.positionals ?? [])
+    .map((p) => (p.required ? `<${p.name}>` : `[${p.name}]`))
+    .join(" ");
+  const verb = kindGroup
+    .command(`${cmd.verb} [args...]`)
+    .summary(cmd.summary)
+    .description(usage ? `${cmd.summary}\n\nArguments: ${usage}` : cmd.summary);
+
+  for (const f of cmd.args?.flags ?? []) {
+    const flag = f.value ? `--${f.name} <value>` : `--${f.name}`;
+    verb.option(flag, f.help ?? "");
+  }
+
+  verb.action((args: string[], opts: Record<string, unknown>) =>
+    runAction(async () => {
+      const parsed = toParsedArgs(cmd, args, opts);
+
+      const config = await resolveOne(resolveOpts());
+      const driver = getDriver(config.driver);
+      const conn = await driver.connect(config);
+      const ctx: CommandContext = {
+        conn,
+        config,
+        io,
+        secrets: envSecretProvider,
+      };
+      try {
+        await cmd.run(ctx, parsed);
+      } finally {
+        await driver.close(conn);
+      }
+    }),
+  );
+}
+
+/**
+ * Register every `sc <kind> <verb>` command from the active driver's project: the CORE-provided
+ * `ls`/`info` for each registered kind (+ the top-level `sc ls` overview) and the driver's own
+ * contributed `commands` on top, grouped per kind. Runs before `program.parse()`; no-ops entirely when
+ * there's no project config (the driver is unknown, e.g. `sc init`). `resolveOpts` reads the global
+ * addressing flags (`--connection`/`--config`) off the invoked command at action time.
+ */
+export async function registerDriverCommands(program: Command): Promise<void> {
+  let driverName: string;
+  const configPath = configFromArgv(process.argv.slice(2));
+  try {
+    const { config } = await loadProject({ config: configPath });
+    // Each connection entry carries its driver name directly (no resolve/connect needed): read it off
+    // any entry. A project's connections share one driver, so the first is enough.
+    const entry = Object.values(config.connections)[0] as
+      | { driver?: string }
+      | undefined;
+    if (!entry?.driver) return;
+    driverName = entry.driver;
+  } catch {
+    return; // no/invalid config (e.g. `sc init`) — driver commands simply aren't available
+  }
+
+  try {
+    await ensureDriver(driverName);
+  } catch {
+    return;
+  }
+  const driver = getDriver(driverName);
+
+  // Group verbs under a shared kind command, so the universal `sc <kind> ls`/`info` and any driver
+  // verbs (`sc access rotate`, `sc access check`) co-exist under one `sc <kind>` group.
+  const groups = new Map<string, Command>();
+  const groupFor = (kind: string): Command => {
+    let g = groups.get(kind);
+    if (!g) {
+      g = program
+        .command(kind)
+        .summary(`inspect + manage ${style.bold(kind)} resources`)
+        .description(
+          `\`${kind}\` commands: the universal \`ls\`/\`info\` (any kind) plus any driver verbs from @better-schemic/${driverName}.`,
+        );
+      groups.set(kind, g);
+    }
+    return g;
+  };
+
+  // The invoked verb command carries the global addressing flags; read them at action time.
+  const resolveOpts = (): ResolveOpts => {
+    const opts = program.opts() as { connection?: string; config?: string };
+    return { connection: opts.connection, config: opts.config ?? configPath };
+  };
+
+  // Core-provided READ inspection for EVERY registered kind (`sc <kind> ls`/`info` + top-level `sc ls`).
+  registerInspectVerbs(program, driver, groupFor, resolveOpts);
+
+  // The driver's own verbs (e.g. `access rotate`) on top of the universal ls/info.
+  for (const cmd of driver.commands ?? []) {
+    addCommand(groupFor(cmd.kind), cmd, resolveOpts);
+  }
+}