@xubylele/schema-forge 1.11.0 → 1.12.1

package/README.md

@@ -14,6 +14,7 @@ A modern CLI tool for database schema management with a clean DSL and automatic
 - **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`
+- **Policy (RLS) support** - Define Row Level Security policies in the DSL: `for select|insert|update|delete|all`, optional `to role1 role2` (e.g. `anon`, `authenticated`). Invalid policies produce clear CLI errors during validation. See [RLS policy patterns](https://github.com/xubylele/schema-forge-core/blob/main/docs/rls-policy-patterns.md) for user-owned rows, public read/authenticated write, and multi-tenant examples.
 
 ## Installation
 
@@ -324,6 +325,7 @@ Live `--json` output returns a structured `DriftReport`:
 
 Validation checks include:
 
+- **Policy validation** – Each policy must reference an existing table, use a valid command (`select` / `insert` / `update` / `delete` / `all`), and have at least one of `using` or `with check`. Invalid policies cause validation to fail with a clear error (exit code 1).
 - Dropped tables (`DROP_TABLE`, error)
 - Dropped columns (`DROP_COLUMN`, error)
 - Column type changes (`ALTER_COLUMN_TYPE`, warning/error based on compatibility heuristics)
@@ -566,6 +568,39 @@ table table_name {
 - `default <value>` - Default value (e.g., `default now()`, `default false`, `default 0`)
 - `fk <table>.<column>` - Foreign key reference (e.g., `fk users.id`)
 
+### Policies (RLS)
+
+Row Level Security policies are declared at the top level (the table must be defined first). Each policy must have a `for` command and at least one of `using` or `with check`.
+
+```sql
+table users {
+  id uuid pk
+  email text unique
+}
+
+policy "Users can read themselves" on users
+for select
+using auth.uid() = id
+```
+
+- **First line:** `policy "<name>" on <table>`
+- **Continuation:** `for <command>` (required): `select`, `insert`, `update`, `delete`, or `all` (applies to all commands). Optional `to role1 role2` (e.g. `to anon authenticated`). Optional `using <expr>` and `with check <expr>`.
+
+Example with `for all` and `to`:
+
+```sql
+policy "Own rows" on profiles
+for all
+using auth.uid() = id
+with check auth.uid() = id
+
+policy "Public read" on items
+for select to anon authenticated
+using true
+```
+
+Invalid policies (missing table, invalid command, or no expressions) fail `schema-forge validate` with a clear error message. For common patterns (user-owned rows, public read / authenticated write, multi-tenant), see [RLS policy patterns](https://github.com/xubylele/schema-forge-core/blob/main/docs/rls-policy-patterns.md) in the core package.
+
 ### Examples
 
 #### Simple table

package/dist/api.d.ts

@@ -11,14 +11,12 @@ interface DoctorOptions {
     schema?: string;
 }
 
-/** Migration file name format: hyphen (timestamp-name.sql) or underscore (timestamp_name.sql, Supabase CLI style). */
 type MigrationFileNameFormat = 'hyphen' | 'underscore';
 
 interface GenerateOptions {
     name?: string;
     safe?: boolean;
     force?: boolean;
-    /** Override migration file name format: hyphen (timestamp-name.sql) or underscore (timestamp_name.sql). */
     migrationFormat?: MigrationFileNameFormat;
 }
 
@@ -44,69 +42,22 @@ interface ValidateOptions {
     force?: boolean;
 }
 
-/**
- * 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.
- * @param options.provider - Database provider: 'postgres' (default) or 'supabase'. Supabase uses supabase/migrations for output.
- */
 declare function init(options?: InitOptions): 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 InitOptions, type IntrospectOptions, type RunResult, type ValidateOptions, diff, doctor, generate, importSchema, init, introspect, validate };