@kequtech/tenon-orm 0.4.0 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.3
+
+- Add shared runtime/CLI configuration and offline `tenon init`. Restore `tenon generate`, share migration defaults, and require config for generation/checking/inspection.
+- Remove `db.generateTypes()`. Add native baseline connection/schema defaults and fix inspection timeout overrides and migration-history lookup under custom search paths.
+
+## 0.4.2
+
+- Rewrite the README and consumer guides around a complete getting-started workflow and task-based navigation.
+- Add guides for SQL queries, schema types and values, connections, and migrations, including joins, pagination, codec configuration, rollback, and migration recovery.
+- Clarify query result modes, write guards, generated types, source checking, and their validation limits. This release changes documentation only; no application migration is required.
+
+## 0.4.1
+
+- Add `db.generateTypes({ out, namespace?, check?, onWarning? })`, using the instance's configured codecs.
+- Remove `tenon generate`; run generation and freshness checks from an application script.
+  Use the configured database instance, set `check: true` for freshness checks, and close it when
+  the script finishes. See the [generation script example](docs/human-guide.md#generate-types).
+
 ## 0.4.0
 
 ### Breaking changes
@@ -9,7 +27,7 @@
   Connections accept a PostgreSQL URI, pgclear `PoolOptions`, or a pgclear `Pool`; translate former
   pg configuration and supply deployment settings explicitly.
   PG environment defaults, pgpass/service files, and pg-specific URI options are not read. See
-  [upgrading from 0.3.x](docs/adoption-guide.md#upgrade-from-tenon-03x).
+  [connection configuration](docs/connections.md#configure-a-database-instance).
 - `db.native` is now a pgclear `Pool`. Use `queryClassic(text, values?)` for finished SQL and
   acquire/withSession for held sessions; native `query` accepts pgclear's own sql tag only. Prepared
   statements, streams, and COPY use the public session APIs. Use pgclear `listen` for dedicated
@@ -21,7 +39,9 @@
   output conversions are opt-in. Undefined, plain objects, and arrays reject; mutation-helper
   undefined still omits. JSON encoding still rejects bigint values.
 - Tenon owns schema generation and exports `Database[table]['row' | 'insert' | 'update']`.
-  Regenerate committed definitions, replace former Rows imports, and review write representations.
+  Regenerate committed definitions and review write representations. Replace `Rows[table]`,
+  `Rows.Insert[table]`, and `Rows.Update[table]` with `Database[table]['row']`,
+  `Database[table]['insert']`, and `Database[table]['update']`.
   Catalog queries, schema summaries, defaults/domains/identities, and TypeScript rendering live in
   Tenon; decoder representations come from pgclear. Import generation from Tenon instead of pgclear.
   Tenon retains migration coordination, atomic file output, and `generate --check` freshness checks.

package/README.md

@@ -2,19 +2,20 @@
 
 A PostgreSQL ORM designed for coding agents. Built for Node.js and TypeScript.
 
-Write SQL directly, bind values with a template tag, and reuse queries through ordinary functions.
-Tenon provides transactions, affected-row guards, SQL migrations, generated database types, and
-query inspection and optional source-aware checking. Tenon owns database declarations and application
-TypeScript tooling. Execution, Describe, and value conversion come from the
-`@kequtech/pgclear` runtime dependency. Import `sql`, `json`, `param`, and codec helpers from
-Tenon for application queries; no separate driver installation is needed.
+Tenon keeps database work in forms coding agents can read, write, and check: explicit SQL, ordinary
+TypeScript functions, and SQL migrations. Queries carry their result types and execution options
+together, so an agent and the person reviewing its work can see what an operation does in one place.
 
 ```sh
 npm install @kequtech/tenon-orm
 ```
 
-Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript consumers need TypeScript 6+ and Node
-development typings.
+Requires Node.js 24+, PostgreSQL 16+, and ESM. TypeScript applications need TypeScript 6+ and Node.js
+typings. The PostgreSQL driver, [pgclear](https://github.com/kequtech/pgclear), is included.
+
+## Query with SQL
+
+This example assumes a `public.users` table with integer `id` and text `email` columns:
 
 ```ts
 import { createTenon, sql } from '@kequtech/tenon-orm';
@@ -31,57 +32,98 @@ try {
     `,
     { returns: 'oneOrNone' },
   );
-  // user is { id: number; email: string } | undefined
+  // user: { id: number; email: string } | undefined
 } finally {
   await db.close();
 }
 ```
 
-The example assumes `public.users` exists. In a server, reuse the instance and close it at shutdown.
-`oneOrNone` rejects multiple rows; use `one` for exactly one row, `many` for an array, or omit
-`returns` for the driver's result object and metadata.
-
-Command `rowCount` values are numbers. SQL `count(*)`, bigint/bigserial columns, and bigint array
-elements read as exact strings by default. Plain bigint, Date, and supported native/polyfilled
-Temporal inputs use server type inference; output conversions to bigint, Date, or Temporal are
-explicit codec choices. JSON and PostgreSQL arrays use explicit helpers. See the
-[value mappings](docs/reference.md#generated-types-and-checking).
-
-Joins, relationships, aggregates, and upserts use PostgreSQL SQL. Object-based writes can use
-`sql.insertValues` and `sql.assignments` while keeping the surrounding statement explicit.
-`db.native` exposes the underlying pgclear `Pool` for prepared statements, streams, COPY, and
-other driver features; those calls bypass Tenon's query and transaction guards. Use pgclear's
-`listen` for a dedicated notification connection.
-
-`sql<Row>` declares an expected result type. `tenon check src/users.ts:23` checks a recoverable query
-against that type and PostgreSQL Describe without executing the statement. Inconclusive types remain
-unproven; unsupported SQL composition is reported as unchecked. `describeQuery` inspects finished SQL
-without comparing a source annotation. Keep database tests for actual
-rows and write effects. Validation, authorization, and retry policy belong to the application.
-Existing migration runners can be retained; Tenon's migrations and type generation are optional.
+`${email}` becomes `$1` in the SQL, with the value passed separately. `sql<Row>` describes one
+returned row. `returns` chooses how Tenon gives those rows back:
+
+| `returns`          | You receive                                         | Required rows |
+| ------------------ | --------------------------------------------------- | ------------- |
+| `many`             | `readonly Row[]`                                    | Any number    |
+| `oneOrNone`        | `Row \| undefined`                                  | Zero or one   |
+| `one`              | `Row`                                               | Exactly one   |
+| `native` (default) | Driver result with `rows`, `rowCount`, and `fields` | Any number    |
+
+A row-count mismatch throws. The modes do not add `LIMIT` or change the SQL. In a server, reuse one
+database instance and close it during shutdown. Supply environment variables through your application;
+Tenon does not load `.env` files.
+
+## Designed for coding agents
+
+Tenon's API gives coding agents concrete code to work with and explicit contracts to preserve:
+
+- **Readable SQL.** Selected columns, joins, filters, and conflict handling are visible in the query.
+  An agent can inspect the operation directly and use PostgreSQL's existing vocabulary.
+- **Ordinary TypeScript.** Reusable queries are functions. An agent can follow imports, change a
+  function, and pass the same query code a database or transaction client.
+- **Explicit write limits.** A query can require exactly one affected row or set a maximum. Tenon
+  rolls back the operation if that bound is violated.
+- **Actionable checks.** Generated table types describe storage contracts; `tenon check` reports
+  contradictions between recoverable SQL and declared types. Freshness checks catch stale generated
+  declarations, and database tests verify results and effects.
+
+The guides and changelog ship with the package, giving an agent documentation for the installed
+version. For work in an existing project, start with the [agent guide](docs/agent-guide.md).
+
+## How Tenon fits together
+
+- **SQL defines the operation.** Use PostgreSQL joins, aggregates, constraints, and upserts directly.
+  Reuse queries with ordinary functions; use fragments when parts of the SQL need to vary.
+- **TypeScript describes the values.** Declare query projections with `sql<Row>`. Optionally generate
+  table read/insert/update types with `tenon generate`.
+- **Transactions define what commits together.** Use `db.transaction(async (tx) => { ... })` and run
+  every participating query through `tx`.
+- **Write guards check affected rows.** `{ affectedRows: { exact: 1 } }` rolls back a write unless
+  exactly one row was affected. `{ max: 1 }` allows zero or one.
+- **Migrations change the schema.** Tenon's optional runner applies numbered SQL files. You can keep
+  an existing schema and migration runner.
+
+For object inputs, `sql.insertValues(input)` and `sql.assignments(patch)` build the column/value
+parts of a statement. The table, conditions, expressions, and conflict behavior stay in your SQL.
+There are no model instances or implicit relationship loading.
+
+Query types are declarations. Tenon does not validate returned data against `Row` during execution.
+The optional `tenon check` command compares recoverable source queries with TypeScript types and
+PostgreSQL metadata. Keep database tests for actual results and write effects.
+
+Some PostgreSQL values need care: bigint columns and `count(*)` read as exact strings, numeric and
+temporal values also default to strings, and JSON/array inputs use explicit encoding helpers. Command
+`rowCount` is a number or null. See [value mappings](docs/schema-types.md#value-mappings) before
+choosing application types.
+
+## Share configuration with the CLI
+
+Run `tenon init` to create `tenon.config.ts`, put connection settings and codecs there, and use its
+`connection` in `createTenon`.
+Then run `tenon generate`, `tenon generate --check`, `tenon check`, and `tenon describe query.sql`
+without custom scripts. Migration commands also use the shared connection and migration defaults.
+See [shared configuration](docs/configuration.md) for the complete setup.
 
 ## Documentation
 
-Start with this README, then follow the [agent guide](docs/agent-guide.md) when working in an
-existing project or the [human guide](docs/human-guide.md) for a first setup. Use the reference for
-specific options and the focused guides when a task needs them. Read the docs shipped with the
-installed Tenon version; unreleased repository changes may differ.
-
-- **[Human guide](docs/human-guide.md)** — a table, queries, transactions, and generated types.
-- **[Agent guide](docs/agent-guide.md)** — implementation contracts and upgrade workflow.
-- **[Reference](docs/reference.md)** — API options, value mappings, CLI, and limitations.
-- **[Adoption guide](docs/adoption-guide.md)** — replace an ORM and transfer migration ownership.
-- **[Mutation cookbook](docs/mutations.md)** — defaults, patches, upserts, arrays, and batching.
-- **[Query inspection](docs/query-inspection.md)** — Describe reports and database tests.
-- **[Query checking](docs/query-checking.md)** — project/file/line checking, composition, and limitations.
-- **[Changelog](CHANGELOG.md)** — versioned changes and upgrade instructions.
-
-For common failures, see [troubleshooting](docs/reference.md#troubleshooting). To choose between
-source checking, SQL inspection, and generated-file freshness, see
-[validation tools](docs/reference.md#choosing-a-validation-tool).
-
-These documents all ship with the npm package, including the changelog so an agent upgrading a
-project can read the relevant release entries locally. Repository maintenance instructions are in
+Start with [Getting started](docs/human-guide.md) for a complete table-to-query example. Then choose
+the guide for your task:
+
+| Guide                                                      | What it covers                                                               |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [Shared configuration](docs/configuration.md)              | Runtime/CLI connection settings, codecs, command defaults, and overrides     |
+| [Writing queries](docs/sql.md)                             | Parameters, reusable functions, joins, aggregates, pagination, and fragments |
+| [Writing data](docs/mutations.md)                          | Inserts, patches, defaults, upserts, JSON, arrays, and batches               |
+| [Schema types and values](docs/schema-types.md)            | Generation, read/write types, codecs, and domain validation                  |
+| [Migrations](docs/migrations.md)                           | Creating, applying, inspecting, and rolling back SQL migrations              |
+| [Connections and driver access](docs/connections.md)       | Pool configuration, shutdown, custom codecs, and native features             |
+| [Checking query types](docs/query-checking.md)             | Source-aware checks and their supported SQL composition                      |
+| [Inspecting and testing queries](docs/query-inspection.md) | PostgreSQL metadata and tests of real behavior                               |
+| [Adopting Tenon](docs/adoption-guide.md)                   | Replacing an ORM and transferring migration ownership                        |
+| [Agent guide](docs/agent-guide.md)                         | A short implementation workflow for an existing project                      |
+| [API and CLI reference](docs/reference.md)                 | Signatures, options, errors, commands, and troubleshooting                   |
+
+The README, guides, and [changelog](CHANGELOG.md) ship with the npm package. Read the documentation
+for your installed version when upgrading. Library maintenance is covered in
 [CONTRIBUTING.md](https://github.com/kequtech/tenon-orm/blob/main/CONTRIBUTING.md).
 
 [ISC licensed](LICENSE). Maintained by [Kequtech](https://github.com/kequtech).

package/dist/check.js

@@ -17,7 +17,10 @@ export async function checkQueries(options) {
         if (!['connection', 'target', 'project', 'session', 'timeouts', 'codecs', 'readTypes'].includes(name))
             throw new Error(`Unknown check option: ${name}`);
     }
-    const project = loadProject(options);
+    const codecs = options.codecs ??
+        (typeof options.connection === 'object' ? options.connection?.codecs : undefined) ??
+        defaultCodecs;
+    const project = loadProject({ ...options, codecs });
     const libraries = librarySymbols(project);
     const diagnostics = [...project.diagnostics];
     const queries = project.selected.flatMap((source) => new SourceAnalysis(project, libraries).discover(source));
@@ -52,7 +55,6 @@ export async function checkQueries(options) {
         return { query, variants, diagnostics: analysis.issues };
     });
     const reports = [];
-    const codecs = options.codecs ?? defaultCodecs;
     const readTypes = { ...options.readTypes };
     for (const oid of Object.keys(readTypes)) {
         if (codecs.typescript(Number(oid)) !== undefined)

package/dist/cli.js

@@ -1,23 +1,32 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { defaultCodecs } from '@kequtech/pgclear';
 import { adoptBaseline, captureBaseline } from './baseline.js';
+import { describeFlags, inspectionSettings } from './inspection/cli.js';
+import { loadConfig } from './config/load.js';
+import { initConfig } from './config/init.js';
 import { generateDefinitions } from './generate.js';
 import { writeDefinitions } from './generation/output.js';
-import { describeFlags, inspectionSettings, runDescribe } from './inspection/cli.js';
+import { validatePath } from './validation.js';
+import { describeQuery } from './describe.js';
 import { migrate, migrationStatus, rollback } from './migrations.js';
 import { createMigration } from './migrations/files.js';
-const help = `tenon migrate|status|rollback [--directory migrations] [--namespace public]
+const help = `tenon init [--config path] (create config without a database)
+tenon migrate|status|rollback [--directory migrations] [--namespace public]
 tenon baseline capture|adopt [--directory migrations] [--namespace public]
-baseline capture: [--schema name ...] (default: whole database schema)
+baseline capture: [--schema name ...] [--connection native-uri] (default: whole database schema)
 tenon new <name> [--directory migrations] (no database required)
-tenon generate [--namespace public] [--out src/generated-schema.ts] [--check]
+tenon generate [--out path] [--namespace public] [--check] [--config path]
 tenon describe <query.sql> [--role name] [--search-path schemas] [--time-zone zone]
 tenon check [file.ts[:line]] [--project tsconfig.json] [--json]
+generate/check/describe require tenon.config.ts, .mts, .js or .mjs, or --config path.
 describe: [--connect-timeout-ms 3000] [--statement-timeout-ms 5000] [--lock-timeout-ms 1000]
 describe emits JSON metadata; it does not execute the query or verify result annotations.
 check compares source contracts; mismatches, unchecked sites and no sites fail. Unproven types are notes.
 rollback: --steps 1
-Connection: DATABASE_URL
+All commands accept --config path. Migration commands fall back to DATABASE_URL only without config.
 `;
 function warn(message) {
     process.stderr.write(`Warning: ${message}\n`);
@@ -25,7 +34,14 @@ function warn(message) {
 async function runBaseline(action, options) {
     warn("Capture one shared baseline at the old ORM's final schema checkpoint. Each existing database must be at that checkpoint before adoption. Tenon does not compare schemas or remove the old ORM.");
     if (action === 'capture') {
-        const result = await captureBaseline({ ...options, onWarning: warn });
+        if (typeof options.connection !== 'string') {
+            throw new Error('Baseline capture needs a native libpq URI. Pass --connection or use a string config connection.');
+        }
+        const result = await captureBaseline({
+            ...options,
+            connection: options.connection,
+            onWarning: warn,
+        });
         process.stdout.write(`Captured ${result.upPath}. Source history and data were not changed. Commit this file and generated definitions.\n`);
     }
     else {
@@ -39,11 +55,13 @@ async function main() {
         allowPositionals: true,
         tokens: true,
         options: {
-            directory: { type: 'string', default: 'migrations' },
-            namespace: { type: 'string', default: 'public' },
-            out: { type: 'string', default: 'src/generated-schema.ts' },
-            schema: { type: 'string', multiple: true },
+            directory: { type: 'string' },
+            connection: { type: 'string' },
+            namespace: { type: 'string' },
+            config: { type: 'string' },
+            out: { type: 'string' },
             check: { type: 'boolean', default: false },
+            schema: { type: 'string', multiple: true },
             steps: { type: 'string', default: '1' },
             help: { type: 'boolean', default: false },
             project: { type: 'string' },
@@ -56,23 +74,29 @@ async function main() {
         return;
     }
     const [command, argument] = positionals;
+    for (const name of ['out', 'directory', 'project']) {
+        if (values[name] !== undefined)
+            validatePath(values[name], `--${name}`);
+    }
     // Validate explicitly supplied flags, not defaults. Silently ignoring --check
     // on migrate, for example, would turn an intended dry run into a schema change.
     const allowed = new Set(['help']);
-    if (command !== 'generate' && command !== 'describe' && command !== 'check')
+    if (!['describe', 'check', 'generate', 'init'].includes(command ?? ''))
         allowed.add('directory');
-    if (command !== 'new' && command !== 'describe' && command !== 'check') {
+    if (!['new', 'describe', 'check', 'init'].includes(command ?? '')) {
         allowed.add('namespace');
     }
+    if (command === 'rollback') {
+        allowed.add('steps');
+    }
     if (command === 'generate') {
         allowed.add('out');
         allowed.add('check');
     }
-    if (command === 'rollback') {
-        allowed.add('steps');
-    }
+    allowed.add('config');
     if (command === 'baseline' && argument === 'capture') {
         allowed.add('schema');
+        allowed.add('connection');
     }
     if (command === 'check') {
         allowed.add('project');
@@ -87,11 +111,22 @@ async function main() {
             throw new Error(`--${token.name} is not supported by ${command ?? 'this command'}.`);
         }
     }
+    if (command === 'init') {
+        if (positionals.length !== 1)
+            throw new Error('Use init [--config path] to create configuration.');
+        const path = await initConfig(values.config);
+        process.stdout.write(`Created ${path}\nSet DATABASE_URL before running database commands.\n`);
+        return;
+    }
     if (command === 'new') {
         if (positionals.length !== 2) {
             throw new Error('Use new <name> to create a migration pair.');
         }
-        const files = await createMigration({ name: argument, directory: values.directory });
+        const config = await loadConfig(values.config, false);
+        const files = await createMigration({
+            name: argument,
+            directory: values.directory ?? config?.migrations?.directory ?? 'migrations',
+        });
         process.stdout.write(`Created ${files.upPath}\nCreated ${files.downPath}\n`);
         return;
     }
@@ -103,23 +138,41 @@ async function main() {
             : positionals.length === 1 &&
                 ['migrate', 'generate', 'status', 'rollback'].includes(command ?? '');
     if (!valid) {
-        throw new Error('Choose new, baseline capture|adopt, migrate, generate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
-    }
-    const connection = process.env.DATABASE_URL;
-    if (!connection) {
-        throw new Error('DATABASE_URL is required.');
-    }
-    if (command === 'describe') {
-        await runDescribe(argument, connection, values);
-        return;
-    }
-    if (command === 'check') {
+        throw new Error('Choose init, new, baseline capture|adopt, migrate, generate, describe <query.sql>, check [file.ts[:line]], status, or rollback. Use --help for options.');
+    }
+    if (command === 'generate' || command === 'check' || command === 'describe') {
+        const config = await loadConfig(values.config);
+        if (command === 'generate') {
+            const out = values.out === undefined ? config.generate?.out : resolve(values.out);
+            if (out === undefined)
+                throw new Error('Configure generate.out or pass --out.');
+            const namespace = values.namespace ?? config.generate?.namespace ?? config.migrations?.namespace;
+            const source = await generateDefinitions({
+                connection: config.connection,
+                onWarning: warn,
+                ...(namespace !== undefined && { namespace }),
+            });
+            await writeDefinitions(source, out, values.check);
+            process.stdout.write(values.check ? 'Generated definitions are current.\n' : `Generated ${out}\n`);
+            return;
+        }
+        const flags = inspectionSettings(values);
+        const settings = {
+            connection: config.connection,
+            session: { ...config.session, ...flags.session },
+            timeouts: { ...config.timeouts, ...flags.timeouts },
+        };
+        if (command === 'describe') {
+            const result = await describeQuery({ ...settings, query: await readFile(argument, 'utf8') });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
         const { checkQueries } = await import('./check.js');
         const report = await checkQueries({
-            connection,
+            ...settings,
+            ...config.check,
             ...(argument === undefined ? {} : { target: argument }),
             ...(values.project === undefined ? {} : { project: values.project }),
-            ...inspectionSettings(values),
         });
         if (values.json)
             process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
@@ -132,24 +185,28 @@ async function main() {
             process.exitCode = 1;
         return;
     }
-    const options = { connection, directory: values.directory, namespace: values.namespace };
+    const config = await loadConfig(values.config, false);
+    const capture = command === 'baseline' && argument === 'capture';
+    const connection = values.connection ??
+        (capture ? config?.baseline?.connection : undefined) ??
+        config?.connection ??
+        process.env.DATABASE_URL;
+    if (!connection)
+        throw new Error('DATABASE_URL is required.');
+    const options = {
+        connection: typeof connection === 'string' ? connection : { ...connection, codecs: defaultCodecs },
+        directory: values.directory ?? config?.migrations?.directory ?? 'migrations',
+        namespace: values.namespace ?? config?.migrations?.namespace ?? 'public',
+    };
     if (baseline) {
+        const schemas = values.schema ?? (capture ? config?.baseline?.schemas : undefined);
         await runBaseline(argument, {
             ...options,
-            ...(values.schema ? { schemas: values.schema } : {}),
+            ...(schemas !== undefined && { schemas }),
         });
         return;
     }
     switch (command) {
-        case 'generate': {
-            const source = await generateDefinitions({
-                connection,
-                namespace: values.namespace,
-                onWarning: warn,
-            });
-            await writeDefinitions(source, values.out, values.check);
-            break;
-        }
         case 'status':
             process.stdout.write(`${JSON.stringify(await migrationStatus(options), null, 2)}\n`);
             break;

package/dist/config/init.d.ts

@@ -0,0 +1,2 @@
+/** Scaffold one value-only config, without importing existing application code or opening a pool. */
+export declare function initConfig(filename?: string): Promise<string>;

package/dist/config/init.js

@@ -0,0 +1,34 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, resolve } from 'node:path';
+import { validatePath } from '../validation.js';
+import { configNames, findConfig } from './load.js';
+/** Scaffold one value-only config, without importing existing application code or opening a pool. */
+export async function initConfig(filename) {
+    if (filename !== undefined)
+        validatePath(filename, 'Config filename');
+    const output = resolve(filename ?? 'tenon.config.ts');
+    const extension = extname(output);
+    if (!['.ts', '.mts', '.js', '.mjs'].includes(extension)) {
+        throw new Error('Config filename must end in .ts, .mts, .js, or .mjs.');
+    }
+    if (filename === undefined || configNames.includes(basename(output))) {
+        const existing = await findConfig(dirname(output));
+        if (existing && (filename === undefined || dirname(existing) === dirname(output))) {
+            throw new Error(`Tenon configuration already exists: ${existing}. Use or edit that file.`);
+        }
+    }
+    const typed = extension === '.ts' || extension === '.mts';
+    const source = `${typed ? "import type { TenonConfig } from '@kequtech/tenon-orm';\n\n" : ''}const connectionString = process.env.DATABASE_URL;
+if (!connectionString) throw new Error('DATABASE_URL is required');
+
+export default {
+  connection: { connectionString },
+  migrations: { directory: 'migrations', namespace: 'public' },
+  generate: { out: 'src/generated-schema.d.ts' },
+  check: { project: 'tsconfig.json' },
+}${typed ? ' satisfies TenonConfig' : ''};
+`;
+    await mkdir(dirname(output), { recursive: true });
+    await writeFile(output, source, { encoding: 'utf8', flag: 'wx' });
+    return output;
+}

package/dist/config/load.d.ts

@@ -0,0 +1,7 @@
+import type { TenonConfig } from '../config.js';
+export declare const configNames: string[];
+/** Find configuration without importing it, including for offline initialization. */
+export declare function findConfig(directory?: string): Promise<string | undefined>;
+/** Import only the selected trusted configuration module; never discover application entry points. */
+export declare function loadConfig(filename?: string): Promise<TenonConfig>;
+export declare function loadConfig(filename: string | undefined, required: false): Promise<TenonConfig | undefined>;