@better-schemic/core 0.1.0-alpha.1

package/src/cli-kit/schema.ts

@@ -0,0 +1,214 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Authored, AuthoredDef } from "@better-schemic/core";
+import { makeJiti } from "./config";
+
+/**
+ * The NEUTRAL view of a loaded table the engine reads — just `name` plus the `config.relation` flag
+ * used for ordering. A driver casts this to its own concrete table builder in `lower`. (The runtime
+ * object is the driver's real `TableDef`; the engine never names that type.)
+ */
+
+/** Import one schema module, wrapping a crash with the FAILING FILE path (original as `cause`). */
+async function importSchemaModule(
+  jiti: ReturnType<typeof makeJiti>,
+  file: string,
+): Promise<unknown> {
+  try {
+    return await jiti.import(file);
+  } catch (err) {
+    throw new Error(
+      `failed to load schema module ${file}: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
+    );
+  }
+}
+
+export interface AnyTable extends Authored {
+  readonly config: { readonly relation?: unknown };
+}
+
+/**
+ * Duck-typed `TableDef` check. We avoid `instanceof` on purpose: the user's schema and the
+ * CLI may end up with different module instances of `@better-schemic/core`, so we recognize a table
+ * by shape instead. (Structural access into `emitStatements` works regardless.)
+ */
+function isTableDef(v: unknown): v is AnyTable {
+  if (!v || typeof v !== "object") return false;
+  const t = v as Record<string, unknown>;
+  return (
+    typeof t.name === "string" &&
+    typeof t.fields === "object" &&
+    t.fields !== null &&
+    typeof t.config === "object" &&
+    t.config !== null &&
+    typeof t.record === "function"
+  );
+}
+
+/**
+ * Duck-typed standalone-def check — DRIVER-AGNOSTIC: any non-table object carrying a string `kind`
+ * and `name` is a standalone definable (event/function/access/enum/view/sequence/…). Core must not
+ * hardcode a dialect's kinds — the driver's `registry`/`explode` owns which kinds are valid. Tables
+ * are matched by `isTableDef` first, so they never reach here. See `isTableDef` on why not `instanceof`.
+ */
+function isStandaloneDef(v: unknown): v is AuthoredDef {
+  if (!v || typeof v !== "object") return false;
+  const d = v as Record<string, unknown>;
+  return (
+    typeof d.kind === "string" &&
+    d.kind.length > 0 &&
+    typeof d.name === "string"
+  );
+}
+
+function tsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir).sort()) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) out.push(...tsFiles(p));
+    else if (/\.(ts|mts|js|mjs)$/.test(entry) && !entry.endsWith(".d.ts"))
+      out.push(p);
+  }
+  return out;
+}
+
+/** The schema module file(s) for a path: the file itself, or every module under the directory. */
+function schemaFiles(path: string): string[] {
+  return statSync(path).isFile() ? [path] : tsFiles(path);
+}
+
+/** Import a schema module file and yield its exported tables/relations, paired with the file. */
+async function* tablesIn(
+  jiti: ReturnType<typeof makeJiti>,
+  file: string,
+): AsyncGenerator<AnyTable> {
+  const mod = (await importSchemaModule(jiti, file)) as Record<
+    string,
+    unknown
+  >;
+  for (const value of Object.values(mod)) if (isTableDef(value)) yield value;
+}
+
+/**
+ * Load every schema object from `schemaPath` (a single `.ts` module, or a directory of them): the
+ * tables/relations (ordered normal-before-relation, then by name, for stable DDL) and the standalone
+ * defs (any non-table `{ kind, name }` definable — the driver's registry owns the kinds). One pass.
+ */
+export async function loadDefs(schemaPath: string): Promise<{
+  tables: AnyTable[];
+  defs: AuthoredDef[];
+  /** Absolute source file each table/def was loaded from (for `diff`'s file annotations). */
+  fileOf: Map<AnyTable | AuthoredDef, string>;
+}> {
+  if (!existsSync(schemaPath)) {
+    throw new Error(`Schema path not found: ${schemaPath}`);
+  }
+  const jiti = makeJiti();
+  const tables = new Map<string, AnyTable>();
+  const defs: AuthoredDef[] = [];
+  const fileOf = new Map<AnyTable | AuthoredDef, string>();
+  for (const file of schemaFiles(schemaPath)) {
+    const mod = (await importSchemaModule(jiti, file)) as Record<
+    string,
+    unknown
+  >;
+    for (const value of Object.values(mod)) {
+      if (isTableDef(value)) {
+        tables.set(value.name, value); // last def of a name wins
+        fileOf.set(value, file);
+      } else if (isStandaloneDef(value)) {
+        defs.push(value);
+        fileOf.set(value, file);
+      }
+    }
+  }
+  const rank = (t: AnyTable) => (t.config.relation ? 1 : 0);
+  const sorted = [...tables.values()].sort(
+    (a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name),
+  );
+  return { tables: sorted, defs, fileOf };
+}
+
+/** The tables/relations from `schemaPath` (standalone events excluded — see {@link loadDefs}). */
+export async function loadSchemas(schemaPath: string): Promise<AnyTable[]> {
+  return (await loadDefs(schemaPath)).tables;
+}
+
+/** A schema file's exported entities (tables/functions/accesses) and whether it holds ONLY those. */
+export interface LocalFileEntities {
+  /** Each schema entity by its export-const identifier + its DB name (table/function/access name). */
+  entities: { exportName: string; name: string; kind: "table" | "def" }[];
+  /** True when EVERY runtime export of the file is a schema entity (no helpers / other exports). */
+  pureSchema: boolean;
+}
+
+/**
+ * Scan each schema file for the tables/functions/accesses it exports (by export-const name), and
+ * whether the file is purely schema. `pull` uses this to find whole-entity local-only schema
+ * (entities the live DB doesn't have) and to decide whether a file is safe to delete when mirroring
+ * the DB. Standalone events are not whole entities (they attach to a table), so they don't count as
+ * entities — a file exporting one is therefore not `pureSchema` and won't be auto-deleted.
+ */
+export async function scanLocalEntities(
+  schemaPath: string,
+): Promise<Map<string, LocalFileEntities>> {
+  if (!existsSync(schemaPath)) return new Map();
+  const jiti = makeJiti();
+  const out = new Map<string, LocalFileEntities>();
+  for (const file of schemaFiles(schemaPath)) {
+    const exports = Object.entries(
+      (await importSchemaModule(jiti, file)) as Record<string, unknown>,
+    );
+    const entities: LocalFileEntities["entities"] = [];
+    for (const [exportName, value] of exports) {
+      if (isTableDef(value))
+        entities.push({ exportName, name: value.name, kind: "table" });
+      else if (
+        isStandaloneDef(value) &&
+        (value.kind === "function" || value.kind === "access")
+      )
+        entities.push({ exportName, name: value.name, kind: "def" });
+    }
+    if (entities.length)
+      out.set(file, {
+        entities,
+        pureSchema: entities.length === exports.length,
+      });
+  }
+  return out;
+}
+
+/** Map of table name → the file that defines it (for `pull`'s duplicate-definition check). */
+export async function existingTables(
+  schemaPath: string,
+): Promise<Map<string, string>> {
+  if (!existsSync(schemaPath)) return new Map();
+  const jiti = makeJiti();
+  const out = new Map<string, string>();
+  for (const file of schemaFiles(schemaPath)) {
+    for await (const t of tablesIn(jiti, file)) out.set(t.name, file);
+  }
+  return out;
+}
+
+/**
+ * Names defined in more than one place, mapped to the files that define them (a file repeats if it
+ * defines the same name twice). `loadSchemas` silently lets the last definition win, so this is how
+ * `doctor` surfaces the otherwise-invisible conflict.
+ */
+export async function duplicateTables(
+  schemaPath: string,
+): Promise<Map<string, string[]>> {
+  if (!existsSync(schemaPath)) return new Map();
+  const jiti = makeJiti();
+  const seen = new Map<string, string[]>();
+  for (const file of schemaFiles(schemaPath)) {
+    for await (const t of tablesIn(jiti, file)) {
+      const files = seen.get(t.name);
+      if (files) files.push(file);
+      else seen.set(t.name, [file]);
+    }
+  }
+  return new Map([...seen].filter(([, files]) => files.length > 1));
+}

package/src/cli-kit/style.ts

@@ -0,0 +1,24 @@
+// Tiny ANSI styling, gated on a TTY and honoring NO_COLOR. No dependency.
+/** Whether colored output is enabled (a TTY and `NO_COLOR` unset). */
+export const colorEnabled = () =>
+  Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const paint = (code: number, s: string) =>
+  colorEnabled() ? `\x1b[${code}m${s}\x1b[0m` : s;
+
+export const style = {
+  green: (s: string) => paint(32, s),
+  red: (s: string) => paint(31, s),
+  yellow: (s: string) => paint(33, s),
+  cyan: (s: string) => paint(36, s),
+  dim: (s: string) => paint(90, s),
+  bold: (s: string) => paint(1, s),
+};
+
+/** A green ✓ success line. */
+export const ok = (s: string) => `${style.green("✓")} ${s}`;
+/** A red ✗ failure line. */
+export const fail = (s: string) => `${style.red("✗")} ${s}`;
+
+/** Pluralize `n thing` / `n things`. */
+export const plural = (n: number, word: string) =>
+  `${n} ${word}${n === 1 ? "" : "s"}`;

package/src/client.ts

@@ -0,0 +1,244 @@
+// The neutral foundation for the bound ORM CLIENT (P1) — the runtime read/write handle each driver
+// builds on. Core owns only the dialect-agnostic parts: the disposable lifecycle contract and the
+// managed-connection resolution. A driver's client (`@better-schemic/<driver>/client`) extends `OrmClientBase`,
+// binds its native connection, and adds its TYPED `select`/`call` (+ writes in P2). See
+// docs/proposals/managed-connections-and-orm-client.md.
+
+import {
+  loadProject,
+  type ResolvedConfig,
+  resolveConnectionConfig,
+} from "./cli-kit/config";
+import type { BetterSchemicConfig } from "./config";
+import type { AnyConnectionEntry, ResolveContext } from "./connection";
+
+/**
+ * The neutral bound-client contract. A driver's client extends this and adds its typed query surface.
+ * It is an `AsyncDisposable`, so `await using db = await connect()` closes it at block exit.
+ *
+ * DISPOSE RULE (hard): a MANAGED client (opened by {@link resolveConnection} + the driver's `connect`)
+ * closes the connection it opened; a BYO client (wrapping the user's own pool) MUST make `close` a
+ * NO-OP — we never close a connection the user owns. The driver enforces this at construction.
+ */
+export interface OrmClientBase extends AsyncDisposable {
+  /** Close the underlying connection (managed only; a BYO client is a no-op — see the dispose rule). */
+  close(): Promise<void>;
+}
+
+/** Mixin the default `[Symbol.asyncDispose]` (= `close`) onto a client class's prototype. */
+export function asyncDisposable<T extends { close(): Promise<void> }>(
+  proto: T,
+): void {
+  (proto as { [Symbol.asyncDispose]?: () => Promise<void> })[
+    Symbol.asyncDispose
+  ] = function (this: T) {
+    return this.close();
+  };
+}
+
+/** Options for {@link resolveConnection}: which connection, and where the config lives. */
+export interface ResolveConnectionOptions {
+  /** Connection name; defaults to `defaultConnection`, else the sole connection, else `"default"`. */
+  name?: string;
+  /** Path to `better-schemic.config.ts` (else auto-discovered from `cwd`). */
+  config?: string;
+  /** Working directory to discover the config + resolve relative paths from. */
+  cwd?: string;
+  /** The resolver's typed args (its declared 2nd param) for a PARAMETERIZED connection. */
+  args?: unknown;
+}
+
+/**
+ * A live resolution context for RUNTIME connects: `ctx.connections.<name>` lazily opens the sibling
+ * via ITS entry's embedded client opener (so a resolver can query another connection to enumerate a
+ * fleet), with CYCLE detection; everything opened during resolution is closed when it settles.
+ */
+function makeRuntimeContext(config: BetterSchemicConfig, root: string) {
+  const opened = new Map<string, Promise<unknown>>();
+  const resolving = new Set<string>();
+
+  const open = async (name: string): Promise<unknown> => {
+    if (resolving.has(name)) {
+      throw new Error(
+        `cyclic connection resolution: "${name}" is already resolving (a resolver reached back into itself via ctx.connections)`,
+      );
+    }
+    const entry = config.connections[name];
+    if (!entry) throw new Error(`ctx.connections.${name}: no such connection`);
+    if (!entry.client) {
+      throw new Error(
+        `ctx.connections.${name}: the "${entry.driver}" connection factory predates runtime cross-connection access — update @better-schemic/${entry.driver}`,
+      );
+    }
+    resolving.add(name);
+    try {
+      const bases = await entry.resolve(context, undefined);
+      if (bases.length !== 1) {
+        throw new Error(
+          `ctx.connections.${name}: resolved to ${bases.length} configs — a sibling reached via ctx.connections must resolve to exactly one`,
+        );
+      }
+      const rc = resolveConnectionConfig(
+        config,
+        name,
+        bases[0],
+        entry.driver,
+        root,
+      );
+      return await entry.client(rc);
+    } finally {
+      resolving.delete(name);
+    }
+  };
+
+  const context: ResolveContext = {
+    env: process.env,
+    connections: new Proxy(
+      {},
+      {
+        get(_t, name: string) {
+          const openOnce = () => {
+            let client = opened.get(name);
+            if (!client) {
+              client = open(name);
+              opened.set(name, client);
+            }
+            return client;
+          };
+          // The handle is THENABLE to the sibling's FULL ORM client (typed in the chained form:
+          // `const main = await ctx.connections.main; main.select(...)`) and keeps a direct
+          // `.query` for the neutral/literal form. Do NOT stash the client past resolution — it is
+          // closed when resolution settles.
+          return {
+            query: async (sql: string, vars?: Record<string, unknown>) => {
+              const db = (await openOnce()) as {
+                query(sql: string, vars?: unknown): Promise<unknown>;
+              };
+              return db.query(sql, vars);
+            },
+            then: (
+              onOk?: (v: unknown) => unknown,
+              onErr?: (e: unknown) => unknown,
+            ) => openOnce().then(onOk, onErr),
+          };
+        },
+      },
+    ) as ResolveContext["connections"],
+  };
+
+  const closeOpened = async () => {
+    for (const c of opened.values()) {
+      try {
+        await ((await c) as { close?: () => Promise<void> }).close?.();
+      } catch {
+        // best-effort cleanup of resolution-time siblings
+      }
+    }
+    opened.clear();
+  };
+
+  return { context, closeOpened, resolving };
+}
+
+/**
+ * Resolve ONE named connection from the disk-discovered project config — the MANAGED path a driver's
+ * standalone `connect(name?)` uses before `driver.connect(config)`. Single-config or a teaching
+ * error (a bulk resolution must be arg-selected).
+ */
+export async function resolveConnection(
+  opts: ResolveConnectionOptions = {},
+): Promise<ResolvedConfig> {
+  const { config, root } = await loadProject({
+    config: opts.config,
+    cwd: opts.cwd,
+  });
+  return exactlyOne(
+    await resolveFromConfig(config, root, { name: opts.name, args: opts.args }),
+  );
+}
+
+/**
+ * The shared single-name resolution over an IN-MEMORY config: pick the entry (named /
+ * defaultConnection / sole / `"default"`), run the resolver with its typed `args`, and build one
+ * {@link ResolvedConfig} per returned config, each with a display label (config `key` > the entry's
+ * `label` hook > positional `name[i]`). Resolvers may query siblings via `ctx.connections` (lazy,
+ * cycle-checked; opened siblings are closed when resolution settles). Used by both
+ * {@link resolveConnection} (disk-discovered config) and {@link connectFromConfig} (`config.connect`).
+ */
+export async function resolveFromConfig(
+  config: BetterSchemicConfig,
+  root: string,
+  opts: { name?: string; args?: unknown } = {},
+): Promise<{
+  entry: AnyConnectionEntry;
+  name: string;
+  resolved: ResolvedConfig[];
+  labels: string[];
+}> {
+  const names = Object.keys(config.connections);
+  const name =
+    opts.name ??
+    config.defaultConnection ??
+    (names.length === 1 ? names[0] : "default");
+  const entry = config.connections[name];
+  if (!entry) {
+    throw new Error(
+      `connection "${name}" is not defined in the config (have: ${names.join(", ") || "none"})`,
+    );
+  }
+
+  const rt = makeRuntimeContext(config, root);
+  rt.resolving.add(name); // the target itself is mid-resolution — a self-reference is a cycle
+  try {
+    const bases = await entry.resolve(rt.context, opts.args);
+    if (!bases.length) {
+      throw new Error(`connection "${name}" resolved to no config`);
+    }
+    const resolved = bases.map((b) =>
+      resolveConnectionConfig(config, name, b, entry.driver, root),
+    );
+    const labels = resolved.map(
+      (rc, i) => bases[i].key ?? entry.label?.(rc) ?? `${name}[${i}]`,
+    );
+    return { entry, name, resolved, labels };
+  } finally {
+    rt.resolving.delete(name);
+    await rt.closeOpened();
+  }
+}
+
+/** Single-config resolution or a TEACHING error — bulk (array) resolutions must be arg-selected. */
+function exactlyOne(r: {
+  name: string;
+  resolved: ResolvedConfig[];
+  labels: string[];
+}): ResolvedConfig {
+  if (r.resolved.length !== 1) {
+    throw new Error(
+      `connection "${r.name}" resolved to ${r.resolved.length} configs (${r.labels.join(", ")}) — ` +
+        `a parameterized/bulk connection. Pass args selecting exactly one, e.g. betterSchemic.connect("${r.name}", { ... }).`,
+    );
+  }
+  return r.resolved[0];
+}
+
+/**
+ * The runtime behind `config.connect(name, args?)` (see `defineConfig`): resolve the entry from the
+ * in-memory config and open its bound ORM client via the factory-embedded
+ * {@link AnyConnectionEntry.client} opener. The static return type is the entry's own client type
+ * (inferred per entry in `BetterSchemicProject`).
+ */
+export async function connectFromConfig(
+  config: BetterSchemicConfig,
+  name?: string,
+  args?: unknown,
+): Promise<unknown> {
+  const r = await resolveFromConfig(config, process.cwd(), { name, args });
+  const resolved = exactlyOne(r);
+  if (!r.entry.client) {
+    throw new Error(
+      `the "${r.entry.driver}" connection factory predates config.connect() — update @better-schemic/${r.entry.driver} to a version whose ${r.entry.driver}Connection embeds a client opener`,
+    );
+  }
+  return r.entry.client(resolved);
+}

package/src/config.ts

@@ -0,0 +1,199 @@
+/**
+ * Configuration for the `better-schemic` CLI — author it in `better-schemic.config.ts`
+ * (`schemic.config.ts` still loads as a legacy alias).
+ *
+ * A project declares one or more named CONNECTIONS, each built by a per-driver factory
+ * (`<driver>Connection(...)` exported from `@better-schemic/<driver>/connection`). Connection values are EXPLICIT —
+ * there is no env-var magic; read env yourself where you want it (`url: process.env.MY_URL`).
+ * See `@better-schemic/core` docs/MULTI-CONNECTION.md.
+ *
+ * ```ts
+ * import { defineConfig } from "@better-schemic/core/config";
+ * import { surrealConnection } from "@better-schemic/surrealdb/connection";
+ *
+ * export default defineConfig({
+ *   connections: {
+ *     default: surrealConnection({
+ *       schema: "./database/schema",
+ *       url: "ws://localhost:8000",
+ *       namespace: "app",
+ *       database: "app",
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * For MULTIPLE databases (multi-tenant / heterogeneous / DB-per-user), add more named connections;
+ * a connection may be a resolver (incl. an array → a collection). See docs/MULTI-CONNECTION.md.
+ *
+ * NOTE: this file is dialect-NEUTRAL. Driver-specific connection shapes (SurrealDB's
+ * url/namespace/authLevel, its check-engine options, …) live in the driver package's
+ * `<driver>Connection` factory, not here.
+ */
+import type {
+  AnyConnectionEntry,
+  ConnectionConfigBase,
+  ConnectionEntry,
+  ConnectionInput,
+  ResolveContext,
+  ResolvedConnectionHandle,
+} from "./connection";
+
+export interface BetterSchemicConfig {
+  /** Named database connections — each produced by a per-driver `<driver>Connection(...)` factory. */
+  connections: Record<string, AnyConnectionEntry>;
+  /**
+   * With more than one connection, the connection a bare command targets (must name a single static
+   * connection). Absent + ambiguous → a live command errors asking for `--connection`.
+   */
+  defaultConnection?: string;
+  /** Table that records applied migrations (per connection). Default `_migrations`. */
+  migrationsTable?: string;
+  /** Optional seed script run by `better-schemic seed`. */
+  seed?: string;
+}
+
+/**
+ * Legacy alias — prefer {@link BetterSchemicConfig}.
+ */
+export type SchemicConfig = BetterSchemicConfig;
+
+/** The bound ORM client type a {@link ConnectionEntry} opens (inferred from the driver factory). */
+// biome-ignore lint/suspicious/noExplicitAny: matching the erased Args slot.
+export type EntryClient<E> =
+  E extends ConnectionEntry<infer Client, any> ? Client : never;
+/** The typed resolver `args` a {@link ConnectionEntry} accepts (from its `args` schema). */
+// biome-ignore lint/suspicious/noExplicitAny: matching the erased Client slot.
+export type EntryArgs<E> =
+  E extends ConnectionEntry<any, infer Args> ? Args : never;
+
+/**
+ * What {@link defineConfig} ADDS to your config: the config IS the app's typed entry point to its
+ * databases. `connect(name, args?)` autocompletes your connection names, types `args` per connection
+ * (the resolver's declared 2nd param — absent for a static/argless connection), and returns that
+ * entry's own client type (a heterogeneous-driver project types per-connection). A PARAMETERIZED
+ * connection whose resolver returns an ARRAY is bulk-only: `connect` throws a teaching error — pass
+ * `args` selecting ONE config. The client is disposable: `await using db = await betterSchemic.connect()`.
+ */
+export interface BetterSchemicProject<
+  Conns extends Record<string, AnyConnectionEntry>,
+> {
+  connect<N extends keyof Conns & string>(
+    name?: N,
+    args?: EntryArgs<Conns[N]>,
+  ): Promise<EntryClient<Conns[N]>>;
+}
+
+/**
+ * Type + enrich a Better-schemic config: returns the config with a typed `connect()` attached — the config
+ * itself is the factory. The loader accepts a `default` export OR the NAMED `betterSchemic` export
+ * (`schemic` still loads as a legacy alias); the scaffolded form is the named one
+ * (deterministic auto-import, no file rename needed):
+ *
+ * ```ts
+ * // better-schemic.config.ts (better-schemic.ts, schemic.config.ts, and schemic.ts also load)
+ * export const betterSchemic = defineConfig({ connections: { ... } });
+ * // app code: import { betterSchemic } from "./better-schemic.config";  →  await using db = await betterSchemic.connect();
+ * ```
+ */
+/**
+ * A resolver's `ctx` in the CHAINED form: `connections` is typed with the ACCUMULATED prior
+ * connections — each handle is thenable to that entry's FULL ORM client (`const main = await
+ * ctx.connections.main; main.select(...)`) and keeps a direct `.query`. Order = visibility: a
+ * resolver only sees connections declared BEFORE it (structural cycle prevention). Do not stash a
+ * sibling client — it is closed when resolution settles.
+ */
+export type ChainCtx<Conns extends Record<string, AnyConnectionEntry>> = Omit<
+  ResolveContext,
+  "connections"
+> & {
+  connections: {
+    [K in keyof Conns]: PromiseLike<EntryClient<Conns[K]>> &
+      ResolvedConnectionHandle;
+  };
+};
+
+/** The shape a driver connection factory must have to be used as the `.connection()` driver marker. */
+export interface ChainableDriverFactory<
+  C extends ConnectionConfigBase,
+  Client,
+> {
+  // biome-ignore lint/suspicious/noExplicitAny: the chain re-types input/args itself (variance cast).
+  (input: ConnectionInput<C, any>): ConnectionEntry<Client, any>;
+}
+
+/**
+ * The CHAINED config builder (`defineConfig().connection(...)`): each `.connection(name, factory,
+ * input)` uses the driver FACTORY ITSELF as the driver marker and contextually types the resolver's
+ * `ctx.connections` with everything declared so far. The literal `defineConfig({ connections })`
+ * form remains for static maps.
+ */
+export interface ChainedConfig<Conns extends Record<string, AnyConnectionEntry>>
+  extends BetterSchemicProject<Conns> {
+  connections: Conns;
+  defaultConnection?: string;
+  migrationsTable?: string;
+  seed?: string;
+  connection<
+    N extends string,
+    C extends ConnectionConfigBase,
+    Client,
+    Args = undefined,
+  >(
+    name: N,
+    factory: ChainableDriverFactory<C, Client>,
+    input:
+      | C
+      | ((ctx: ChainCtx<Conns>, args: Args) => C | C[] | Promise<C | C[]>),
+  ): ChainedConfig<Conns & { [K in N]: ConnectionEntry<Client, Args> }>;
+}
+
+/** Start a CHAINED config: `defineConfig().connection("main", surrealConnection, {...})`. */
+export function defineConfig(
+  base?: Omit<BetterSchemicConfig, "connections">,
+): ChainedConfig<Record<never, never>>;
+/** Type + enrich a literal config — returns it with the typed `connect()` attached. */
+export function defineConfig<const C extends BetterSchemicConfig>(
+  config: C,
+): C & BetterSchemicProject<C["connections"]>;
+export function defineConfig(
+  config?: BetterSchemicConfig | Omit<BetterSchemicConfig, "connections">,
+): unknown {
+  const isLiteral = !!config && "connections" in config;
+  const base: BetterSchemicConfig = isLiteral
+    ? (config as BetterSchemicConfig)
+    : {
+        ...(config as Omit<BetterSchemicConfig, "connections"> | undefined),
+        connections: {},
+      };
+
+  const withApi = (cfg: BetterSchemicConfig): unknown => ({
+    ...cfg,
+    async connect(name?: string, args?: unknown) {
+      // Lazy: authoring/loading a config stays light; the client machinery loads only when used.
+      const { connectFromConfig } = await import("./client");
+      return connectFromConfig(cfg, name, args);
+    },
+    connection(
+      name: string,
+      factory: (input: unknown) => AnyConnectionEntry,
+      input: unknown,
+    ) {
+      // The factory IS the driver marker: it stamps the driver tag, config type, and client opener.
+      // The chain re-types ctx/args itself, so the factory is called through a variance cast.
+      const entry = factory(input as never);
+      return withApi({
+        ...cfg,
+        connections: { ...cfg.connections, [name]: entry },
+      });
+    },
+  });
+
+  return withApi(base);
+}
+
+/**
+ * Legacy alias — prefer {@link BetterSchemicProject}.
+ */
+export type SchemicProject<Conns extends Record<string, AnyConnectionEntry>> =
+  BetterSchemicProject<Conns>;