@xubylele/schema-forge 1.6.1 → 1.8.0

package/README.md

@@ -13,6 +13,7 @@ A modern CLI tool for database schema management with a clean DSL and automatic
 - **Default Change Detection** - Detects added/removed/modified column defaults and generates ALTER COLUMN SET/DROP DEFAULT
 - **Postgres/Supabase** - Currently supports PostgreSQL and Supabase
 - **Constraint Diffing** - Detects UNIQUE and PRIMARY KEY changes with deterministic constraint names
+- **Live PostgreSQL Introspection** - Extract normalized schema directly from `information_schema`
 
 ## Installation
 
@@ -28,6 +29,19 @@ Or use directly with npx (no installation required):
 npx @xubylele/schema-forge init
 ```
 
+### Programmatic API
+
+Use the programmatic API from Node (e.g. scripts, GitHub Actions) instead of invoking the CLI via shell:
+
+```js
+const { generate, EXIT_CODES } = require('@xubylele/schema-forge/api');
+
+const result = await generate({ name: 'MyMigration' });
+if (result.exitCode !== EXIT_CODES.SUCCESS) process.exit(result.exitCode);
+```
+
+**Exports:** `init`, `generate`, `diff`, `doctor`, `validate`, `introspect`, `importSchema` (each returns `Promise<RunResult>`), `RunResult` (`{ exitCode: number }`), `EXIT_CODES`, and option types (`GenerateOptions`, `DiffOptions`, etc.). Entrypoint: `@xubylele/schema-forge/api`. Exit code semantics: [docs/exit-codes.json](docs/exit-codes.json).
+
 ## Development
 
 Clone the repository and install dependencies:
@@ -56,6 +70,17 @@ Run tests:
 npm test
 ```
 
+Run real-db drift integration tests:
+
+```bash
+npm run test:integration:drift
+```
+
+Notes:
+
+- Local explicit run: set `SF_RUN_REAL_DB_TESTS=true` (uses Testcontainers `postgres:16-alpine`, Docker required).
+- CI/service mode: set `SF_USE_CI_POSTGRES=true` and `DATABASE_URL` to reuse an existing Postgres service.
+
 ## Getting Started
 
 Here's a quick walkthrough to get started with SchemaForge:
@@ -205,9 +230,13 @@ schema-forge diff [--safe] [--force]
 
 - `--safe` - Block execution if destructive operations are detected (exits with error)
 - `--force` - Bypass safety checks and proceed with displaying destructive SQL (shows warning)
+- `--url` - PostgreSQL connection URL for live database diff (fallback: `DATABASE_URL`)
+- `--schema` - Comma-separated schema names to introspect (default: `public`)
 
 Shows what SQL would be generated if you ran `generate`. Useful for previewing changes. Safety behavior is the same as `generate` command. In CI environments, exits with code 3 if destructive operations are detected unless `--force` is used. See [CI Behavior](#ci-behavior) for more details.
 
+When `--url` (or `DATABASE_URL`) is provided, `diff` compares your target DSL schema against the live PostgreSQL schema introspected from `information_schema`.
+
 ### `schema-forge import`
 
 Reconstruct `schemaforge/schema.sf` from existing PostgreSQL/Supabase SQL migrations.
@@ -234,6 +263,36 @@ Detect destructive or risky schema changes before generating/applying migrations
 schema-forge validate
 ```
 
+Live drift validation:
+
+```bash
+schema-forge validate --url "$DATABASE_URL" --json
+```
+
+Live `--json` output returns a structured `DriftReport`:
+
+```json
+{
+  "missingTables": ["users_archive"],
+  "extraTables": ["audit_log"],
+  "columnDifferences": [
+    {
+      "tableName": "users",
+      "missingInLive": ["nickname"],
+      "extraInLive": ["last_login"]
+    }
+  ],
+  "typeMismatches": [
+    {
+      "tableName": "users",
+      "columnName": "email",
+      "expectedType": "varchar",
+      "actualType": "text"
+    }
+  ]
+}
+```
+
 Validation checks include:
 
 - Dropped tables (`DROP_TABLE`, error)
@@ -247,16 +306,49 @@ Use JSON mode for CI and automation:
 schema-forge validate --json
 ```
 
-Exit codes (also see [CI Behavior](#ci-behavior)):
+Live mode options:
+
+- `--url` - PostgreSQL connection URL for live drift validation (fallback: `DATABASE_URL`)
+- `--schema` - Comma-separated schema names to introspect (default: `public`)
 
-- `3` in CI environment if destructive findings detected
-- `1` if one or more `error` findings are detected
-- `0` if no `error` findings are detected (warnings alone do not fail)
+In live mode, exit code `2` is used when drift is detected between `state.json` and the live database. For all exit codes used by `validate`, see [Exit code standards](#exit-code-standards).
 
-Exit codes:
+### `schema-forge doctor`
 
-- `1` when one or more `error` findings are detected
-- `0` when no `error` findings are detected (warnings alone do not fail)
+Check live database drift against your tracked `state.json`.
+
+```bash
+schema-forge doctor --url "$DATABASE_URL"
+```
+
+Use JSON mode for CI and automation:
+
+```bash
+schema-forge doctor --url "$DATABASE_URL" --json
+```
+
+Options:
+
+- `--url` - PostgreSQL connection URL (fallback: `DATABASE_URL`)
+- `--schema` - Comma-separated schema names to introspect (default: `public`)
+- `--json` - Output structured drift report JSON
+
+Exit codes: see [Exit code standards](#exit-code-standards) (doctor uses 0, 2).
+
+### `schema-forge introspect`
+
+Extract normalized schema directly from a live PostgreSQL database.
+
+```bash
+schema-forge introspect --url "$DATABASE_URL" --json
+```
+
+**Options:**
+
+- `--url` - PostgreSQL connection URL (fallback: `DATABASE_URL`)
+- `--schema` - Comma-separated schema names to introspect (default: `public`)
+- `--json` - Output normalized schema as JSON
+- `--out <path>` - Write normalized schema JSON to a file
 
 ## CI Behavior
 
@@ -269,16 +361,29 @@ CI mode is automatically activated when either environment variable is set:
 - `CI=true`
 - `CONTINUOUS_INTEGRATION=true`
 
-### Exit Codes
+### Exit code standards
+
+SchemaForge uses specific exit codes for deterministic CI and script behavior. The following is the single source of truth.
+
+| Exit Code | Name | Meaning |
+| --------- | ---- | ------- |
+| `0` | SUCCESS | No changes or no destructive operations detected |
+| `1` | VALIDATION_ERROR | Invalid DSL, config errors, missing files, or operation declined (e.g. with `--safe`) |
+| `2` | DRIFT_DETECTED | Drift between expected state and live database schema |
+| `3` | CI_DESTRUCTIVE | Destructive operations detected in CI without `--force` |
+
+**Per-command exit codes:**
 
-SchemaForge uses specific exit codes for different scenarios:
+| Command | Possible exit codes |
+| ------- | -------------------- |
+| `validate` | 0, 1, 2, 3 |
+| `doctor` | 0, 2 |
+| `diff`, `generate` | 0, 1, 3 |
+| `init`, `import` | 0 |
 
-| Exit Code | Meaning |
-| --------- | ------- |
-| `0` | Success - no changes or no destructive operations detected |
-| `1` | General error - validation failed, operation declined, missing files, etc. |
-| `2` | Schema validation error - invalid DSL syntax or structure |
-| `3` | **CI Destructive** - destructive operations detected in CI environment without `--force` |
+(Global CLI errors, e.g. unknown command or missing config, exit with 1.)
+
+A machine-readable exit code contract is available at [docs/exit-codes.json](docs/exit-codes.json). It includes a `version` field and an optional `commands` map for tooling.
 
 ### Destructive Operations in CI
 
@@ -312,6 +417,19 @@ When `CI=true`, SchemaForge will:
 - ✅ Allow explicit override with `--force` flag
 - ❌ Not accept user input for confirmation
 
+### Drift Integration Tests in CI
+
+For drift reliability checks against a real database, run:
+
+```bash
+npm run test:integration:drift
+```
+
+The integration harness supports two deterministic paths:
+
+- `SF_USE_CI_POSTGRES=true` + `DATABASE_URL`: uses the CI Postgres service directly.
+- No CI Postgres env: spins up an isolated Testcontainers Postgres instance.
+
 ### Using `--safe` in CI
 
 The `--safe` flag is compatible with CI and blocks execution of destructive operations:
@@ -323,6 +441,20 @@ schema-forge generate --safe
 
 This is useful for strict CI pipelines where all destructive changes must be reviewed and merged separately.
 
+### Using exit codes in CI
+
+In CI, rely on the process exit code to fail the job when validation or safety checks fail. Example with a shell script:
+
+```bash
+schema-forge validate --json
+if [ $? -ne 0 ]; then
+  echo "Schema validation failed (exit code: $?)"
+  exit 1
+fi
+```
+
+When using the [schema-forge-action](https://github.com/xubylele/schema-forge-action), the action passes through the CLI exit code: a non-zero exit from Schema Forge fails the job with that same code, so no extra script is needed.
+
 ## Constraint Change Detection
 
 SchemaForge detects and generates migrations for:

package/dist/api.d.ts

@@ -0,0 +1,101 @@
+interface DiffOptions {
+    safe?: boolean;
+    force?: boolean;
+    url?: string;
+    schema?: string;
+}
+
+interface DoctorOptions {
+    json?: boolean;
+    url?: string;
+    schema?: string;
+}
+
+interface GenerateOptions {
+    name?: string;
+    safe?: boolean;
+    force?: boolean;
+}
+
+interface ImportOptions {
+    out?: string;
+}
+
+interface IntrospectOptions {
+    url?: string;
+    schema?: string;
+    json?: boolean;
+    out?: string;
+}
+
+interface ValidateOptions {
+    json?: boolean;
+    url?: string;
+    schema?: string;
+}
+
+/**
+ * Exit codes used throughout the CLI for deterministic behavior
+ *
+ * @see SF-106 Standardize Exit Codes
+ */
+declare const EXIT_CODES: {
+    /** Successful operation */
+    readonly SUCCESS: 0;
+    /** Validation error (invalid DSL syntax, config errors, missing files, etc.) */
+    readonly VALIDATION_ERROR: 1;
+    /** Drift detected - Reserved for future use when comparing actual DB state vs schema */
+    readonly DRIFT_DETECTED: 2;
+    /** Destructive operation detected in CI environment without --force */
+    readonly CI_DESTRUCTIVE: 3;
+};
+
+/**
+ * Programmatic API for Schema Forge.
+ * Use this entrypoint when integrating from Node (e.g. scripts, GitHub Actions)
+ * instead of invoking the CLI via shell.
+ *
+ * @example
+ * const { generate, EXIT_CODES } = require('@xubylele/schema-forge/api');
+ * const result = await generate({ name: 'MyMigration' });
+ * if (result.exitCode !== EXIT_CODES.SUCCESS) process.exit(result.exitCode);
+ */
+
+/**
+ * Result of a programmatic command run. Exit codes match the CLI contract.
+ * @see docs/exit-codes.json
+ */
+interface RunResult {
+    exitCode: number;
+}
+/**
+ * Initialize a new schema project in the current directory.
+ */
+declare function init(): Promise<RunResult>;
+/**
+ * Generate SQL migration from schema files.
+ */
+declare function generate(options?: GenerateOptions): Promise<RunResult>;
+/**
+ * Compare two schema versions and generate migration SQL (optionally against live DB).
+ */
+declare function diff(options?: DiffOptions): Promise<RunResult>;
+/**
+ * Check live database drift against state.
+ */
+declare function doctor(options?: DoctorOptions): Promise<RunResult>;
+/**
+ * Validate schema and optionally check for destructive changes or live drift.
+ */
+declare function validate(options?: ValidateOptions): Promise<RunResult>;
+/**
+ * Extract normalized live schema from PostgreSQL.
+ */
+declare function introspect(options?: IntrospectOptions): Promise<RunResult>;
+/**
+ * Import schema from SQL migrations.
+ * @param inputPath - Path to .sql file or migrations directory
+ */
+declare function importSchema(inputPath: string, options?: ImportOptions): Promise<RunResult>;
+
+export { type DiffOptions, type DoctorOptions, EXIT_CODES, type GenerateOptions, type ImportOptions, type IntrospectOptions, type RunResult, type ValidateOptions, diff, doctor, generate, importSchema, init, introspect, validate };