schematic-pg 0.1.15 → 0.1.17

package/README.md

@@ -425,7 +425,7 @@ The `init` command creates everything you need to get running:
 |------------------|---------|
 | `AGENTS.md` | Agent-oriented guide for working with schematic-pg in this project |
 | `app.schema` | Starter schema (one `User` model) — edit this |
-| `.env` | `DATABASE_URL`, JWT settings |
+| `.env` | `DATABASE_URL`, JWT settings, `CORS_ORIGIN` |
 | `docker-compose.yml` | Local PostgreSQL on `:5432` |
 | `Makefile` | `make dev` — docker compose (with health wait) + `schematic-pg dev` |
 | `tsconfig.json` | TypeScript config for `generated/` and `src/routes/` |
@@ -456,9 +456,12 @@ Generated code imports the runtime from the `schematic-pg` package (`schematic-p
 | `AUTH_ACCESS_TOKEN_TTL` | `1h` | Access token lifetime (`15m`, `1h`, or seconds) |
 | `JWT_ROLE_CLAIM` | `role` | JWT claim mapped to `auth.role` |
 | `JWT_USER_ID_CLAIM` | `sub` | JWT claim mapped to `auth.user.id` |
+| `CORS_ORIGIN` | — (disabled) | Allowed browser origins. Unset disables CORS. Use `*` for any origin, or a comma-separated list (`http://localhost:5173,https://app.example.com`) |
 
 Set these in `.env` before running `dev`, `start`, or `db:bootstrap`.
 
+Browser frontends on another origin need `CORS_ORIGIN`. The generated app reads it at runtime (no regenerate). Preflight `OPTIONS` is handled automatically; `Authorization` and `Content-Type` are allowed. See [CORS](docs/rest-api.md#cors).
+
 ---
 
 ## Authentication

package/dist/api/middleware/cors.d.ts

@@ -0,0 +1,6 @@
+import type { MiddlewareHandler } from 'hono';
+import type { AppEnv } from '../types.js';
+export declare function parseCorsOrigin(raw?: string | undefined): string | string[] | null;
+export declare function createCorsMiddleware(options?: {
+    origin?: string | string[] | null;
+}): MiddlewareHandler<AppEnv>;

package/dist/api/middleware/cors.js

@@ -0,0 +1,35 @@
+import { cors } from 'hono/cors';
+const CORS_ALLOW_HEADERS = ['Authorization', 'Content-Type'];
+const CORS_ALLOW_METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'];
+const CORS_MAX_AGE_SECONDS = 86400;
+export function parseCorsOrigin(raw = process.env.CORS_ORIGIN) {
+    const trimmed = raw?.trim() ?? '';
+    if (!trimmed) {
+        return null;
+    }
+    if (trimmed === '*') {
+        return '*';
+    }
+    const origins = trimmed
+        .split(',')
+        .map((origin) => origin.trim())
+        .filter((origin) => origin.length > 0);
+    if (origins.length === 0) {
+        return null;
+    }
+    return origins.length === 1 ? origins[0] : origins;
+}
+export function createCorsMiddleware(options = {}) {
+    const origin = options.origin !== undefined ? options.origin : parseCorsOrigin();
+    if (origin == null) {
+        return async (_c, next) => {
+            await next();
+        };
+    }
+    return cors({
+        origin,
+        allowHeaders: CORS_ALLOW_HEADERS,
+        allowMethods: CORS_ALLOW_METHODS,
+        maxAge: CORS_MAX_AGE_SECONDS,
+    });
+}

package/dist/api-generator/app-generator.d.ts

@@ -1,11 +1,16 @@
 import type { Schema } from '../schema-dsl/ast.js';
+import { type CustomRouteMountEntry } from './custom-route-scanner.js';
 export interface AppGeneratorOptions {
     customRoutesDir?: string;
+    /** When provided, skip re-discovering and use these standalone mounts only. */
+    standaloneCustomRoutes?: CustomRouteMountEntry[];
+    overlays?: ReadonlyMap<string, CustomRouteMountEntry>;
 }
 export declare class AppGenerator {
     private readonly schema;
     private readonly options;
     constructor(schema: Schema, options?: AppGeneratorOptions);
     generate(): string;
+    private resolveStandaloneCustomRoutes;
 }
 export declare function generateAppFile(schema: Schema, options?: AppGeneratorOptions): string;

package/dist/api-generator/app-generator.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { PACKAGE_NAME } from '../constants.js';
-import { discoverCustomRoutes } from './custom-route-scanner.js';
+import { discoverCustomRoutes, partitionCustomRoutes, } from './custom-route-scanner.js';
 import { getRouteMountEntries } from './route-generator.js';
 const DEFAULT_CUSTOM_ROUTES_DIR = path.resolve('src/routes');
 export class AppGenerator {
@@ -11,19 +11,19 @@ export class AppGenerator {
         this.options = options;
     }
     generate() {
-        const mounts = getRouteMountEntries(this.schema);
+        const overlays = this.options.overlays ?? new Map();
+        const mounts = getRouteMountEntries(this.schema, overlays);
         const generatedImports = mounts
             .map((entry) => `import ${entry.importName} from './routes/${entry.fileName.replace(/\.ts$/, '.js')}';`)
             .join('\n');
         const generatedRoutes = mounts
             .map((entry) => `  app.route('/${entry.basePath}', ${entry.importName});`)
             .join('\n');
-        const customRoutesDir = this.options.customRoutesDir ?? DEFAULT_CUSTOM_ROUTES_DIR;
-        const customMounts = discoverCustomRoutes(customRoutesDir);
-        const customImports = customMounts
+        const standaloneMounts = this.resolveStandaloneCustomRoutes();
+        const customImports = standaloneMounts
             .map((entry) => `import ${entry.importName} from '${entry.importPath}';`)
             .join('\n');
-        const customRoutes = customMounts
+        const customRoutes = standaloneMounts
             .map((entry) => `  app.route('/${entry.basePath}', ${entry.importName});`)
             .join('\n');
         const routeImports = [generatedImports, customImports].filter(Boolean).join('\n');
@@ -46,6 +46,7 @@ export class AppGenerator {
             `import { createAuthMiddleware } from '${PACKAGE_NAME}/api/auth/middleware';`,
             `import { createJwtResolver } from '${PACKAGE_NAME}/api/auth/jwt-resolver';`,
             `import type { AuthResolver } from '${PACKAGE_NAME}/api/auth/types';`,
+            `import { createCorsMiddleware } from '${PACKAGE_NAME}/api/middleware/cors';`,
             `import { createDbMiddleware } from '${PACKAGE_NAME}/api/middleware/db';`,
             `import { handleError } from '${PACKAGE_NAME}/api/middleware/errors';`,
             `import { mountApiDocs } from '${PACKAGE_NAME}/api/openapi';`,
@@ -61,6 +62,7 @@ export class AppGenerator {
             '',
             'export function createApp(options: CreateAppOptions = {}): Hono<AppEnv> {',
             '  const app = new Hono<AppEnv>();',
+            '  app.use(createCorsMiddleware());',
             '  mountApiDocs(app, openApiDocument);',
             '  app.use(logger());',
             '  app.use(prettyJSON());',
@@ -85,6 +87,14 @@ export class AppGenerator {
             '',
         ].join('\n');
     }
+    resolveStandaloneCustomRoutes() {
+        if (this.options.standaloneCustomRoutes) {
+            return this.options.standaloneCustomRoutes;
+        }
+        const customRoutesDir = this.options.customRoutesDir ?? DEFAULT_CUSTOM_ROUTES_DIR;
+        const { standalone } = partitionCustomRoutes(discoverCustomRoutes(customRoutesDir), this.schema);
+        return standalone;
+    }
 }
 export function generateAppFile(schema, options) {
     return new AppGenerator(schema, options).generate();

package/dist/api-generator/custom-route-scanner.d.ts

@@ -1,6 +1,15 @@
+import type { Schema } from '../schema-dsl/ast.js';
 export interface CustomRouteMountEntry {
     basePath: string;
     importName: string;
+    /** Import path relative to generated/app.ts */
     importPath: string;
+    /** Import path relative to generated/routes/*.ts */
+    routeImportPath: string;
+}
+export interface PartitionedCustomRoutes {
+    overlays: Map<string, CustomRouteMountEntry>;
+    standalone: CustomRouteMountEntry[];
 }
 export declare function discoverCustomRoutes(customRoutesDir: string): CustomRouteMountEntry[];
+export declare function partitionCustomRoutes(entries: CustomRouteMountEntry[], schema: Schema): PartitionedCustomRoutes;

package/dist/api-generator/custom-route-scanner.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
-import { toRouteImportName } from '../api/utils/route-naming.js';
+import { toRouteBasePath, toRouteImportName } from '../api/utils/route-naming.js';
 function isRouteFile(filename) {
     return (filename.endsWith('.ts') &&
         !filename.endsWith('.test.ts') &&
@@ -29,6 +29,7 @@ function scanDirectory(customRoutesDir, relativeDir, entries) {
             basePath,
             importName: toRouteImportName(basePath),
             importPath: `../src/routes/${basePath}.js`,
+            routeImportPath: `../../src/routes/${basePath}.js`,
         });
     }
 }
@@ -40,3 +41,18 @@ export function discoverCustomRoutes(customRoutesDir) {
     scanDirectory(customRoutesDir, '', entries);
     return entries.sort((left, right) => left.basePath.localeCompare(right.basePath));
 }
+export function partitionCustomRoutes(entries, schema) {
+    const modelBasePaths = new Map(schema.models.map((model) => [toRouteBasePath(model.name), model.name]));
+    const overlays = new Map();
+    const standalone = [];
+    for (const entry of entries) {
+        const modelName = modelBasePaths.get(entry.basePath);
+        if (modelName) {
+            overlays.set(modelName, entry);
+        }
+        else {
+            standalone.push(entry);
+        }
+    }
+    return { overlays, standalone };
+}

package/dist/api-generator/index.js

@@ -1,6 +1,6 @@
 import { DEFAULT_CUSTOM_ROUTES_DIR, DEFAULT_HOOKS_DIR } from '../cli/paths.js';
 import { generateAppFile } from './app-generator.js';
-import { discoverCustomRoutes } from './custom-route-scanner.js';
+import { discoverCustomRoutes, partitionCustomRoutes } from './custom-route-scanner.js';
 import { discoverHooks } from './hook-scanner.js';
 import { generateHooksFile } from './hooks-generator.js';
 import { generateOpenApiFiles } from './openapi-generator.js';
@@ -9,17 +9,23 @@ import { generateRouteFiles } from './route-generator.js';
 import { generateValidationSchemas } from './zod-schema-generator.js';
 export function generateApiFiles(schema, options) {
     const customRoutesDir = options?.customRoutesDir ?? DEFAULT_CUSTOM_ROUTES_DIR;
-    const appOptions = { customRoutesDir };
     const hooksDir = options?.hooksDir ?? DEFAULT_HOOKS_DIR;
     const { entries: hookEntries, modelsWithHooks } = discoverHooks(hooksDir, schema);
-    const includeAuthPaths = discoverCustomRoutes(customRoutesDir).some((entry) => entry.basePath === 'auth');
+    const customEntries = discoverCustomRoutes(customRoutesDir);
+    const { overlays, standalone } = partitionCustomRoutes(customEntries, schema);
+    const includeAuthPaths = customEntries.some((entry) => entry.basePath === 'auth');
     const openapi = generateOpenApiFiles(schema, { includeAuthPaths });
+    const appOptions = {
+        customRoutesDir,
+        standaloneCustomRoutes: standalone,
+        overlays,
+    };
     return {
         app: generateAppFile(schema, appOptions),
         policies: generatePoliciesFile(schema),
         validation: generateValidationSchemas(schema),
         hooks: generateHooksFile(hookEntries),
-        routes: generateRouteFiles(schema, modelsWithHooks),
+        routes: generateRouteFiles(schema, { modelsWithHooks, overlays }),
         openapiTs: openapi.openapiTs,
         openapiJson: openapi.openapiJson,
     };

package/dist/api-generator/openapi-generator.js

@@ -2,6 +2,7 @@ import { toRouteBasePath } from '../api/utils/route-naming.js';
 import { fieldHasAttribute, getModelNames, getPrimaryKey, getStoredFields, } from '../sql-generator/utils/ast-helpers.js';
 import { getFilterableFields, getIncludableRelationFields, getOmittedFields, getSortableFieldNames, isStoredScalarField, } from './utils/api-fields.js';
 import { buildFilterFieldMeta, queryParamKey } from './utils/filter-operators.js';
+import { hasRestOperation, isRestEnabled } from './utils/rest.js';
 const ERROR_REF = { $ref: '#/components/schemas/Error' };
 const ERROR_EXAMPLE_VALIDATION = 'Validation failed';
 const ERROR_EXAMPLE_FORBIDDEN = 'Role "USER" is not allowed to list this resource';
@@ -47,6 +48,9 @@ export class OpenApiGenerator {
         };
         const paths = {};
         for (const model of this.schema.models) {
+            if (!isRestEnabled(model)) {
+                continue;
+            }
             Object.assign(schemas, this.buildModelComponentSchemas(model));
             Object.assign(paths, this.buildModelPaths(model));
         }
@@ -127,22 +131,27 @@ export class OpenApiGenerator {
                 nullable: Boolean(field.type.optional),
             });
         }
-        return {
+        const schemas = {
             [`${model.name}Response`]: {
                 type: 'object',
                 properties: responseProps,
                 ...(responseRequired.length > 0 ? { required: responseRequired } : {}),
             },
-            [`${model.name}Create`]: {
+        };
+        if (hasRestOperation(model, 'create')) {
+            schemas[`${model.name}Create`] = {
                 type: 'object',
                 properties: createProps,
                 ...(createRequired.length > 0 ? { required: createRequired } : {}),
-            },
-            [`${model.name}Update`]: {
+            };
+        }
+        if (hasRestOperation(model, 'update')) {
+            schemas[`${model.name}Update`] = {
                 type: 'object',
                 properties: updateProps,
-            },
-        };
+            };
+        }
+        return schemas;
     }
     buildModelPaths(model) {
         const basePath = toRouteBasePath(model.name);
@@ -157,52 +166,58 @@ export class OpenApiGenerator {
         const createRef = { $ref: `#/components/schemas/${model.name}Create` };
         const updateRef = { $ref: `#/components/schemas/${model.name}Update` };
         const tag = model.name;
-        const paths = {
-            [collectionPath]: {
-                get: {
-                    tags: [tag],
-                    summary: `List ${model.name}`,
-                    operationId: `list${model.name}`,
-                    security: OPTIONAL_BEARER_SECURITY,
-                    parameters: this.buildListQueryParameters(model),
-                    responses: {
-                        '200': {
-                            description: `List of ${model.name}`,
-                            content: jsonContent({ type: 'array', items: responseRef }),
-                        },
-                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
-                        '401': errorResponse('Unauthorized'),
-                        '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
-                        '500': errorResponse('Internal server error'),
+        const paths = {};
+        const collectionOps = {};
+        if (hasRestOperation(model, 'list')) {
+            collectionOps.get = {
+                tags: [tag],
+                summary: `List ${model.name}`,
+                operationId: `list${model.name}`,
+                security: OPTIONAL_BEARER_SECURITY,
+                parameters: this.buildListQueryParameters(model),
+                responses: {
+                    '200': {
+                        description: `List of ${model.name}`,
+                        content: jsonContent({ type: 'array', items: responseRef }),
                     },
+                    '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
+                    '401': errorResponse('Unauthorized'),
+                    '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
+                    '500': errorResponse('Internal server error'),
                 },
-                post: {
-                    tags: [tag],
-                    summary: `Create ${model.name}`,
-                    operationId: `create${model.name}`,
-                    security: OPTIONAL_BEARER_SECURITY,
-                    requestBody: {
-                        required: true,
-                        content: jsonContent(createRef),
-                    },
-                    responses: {
-                        '201': {
-                            description: `Created ${model.name}`,
-                            content: jsonContent(responseRef),
-                        },
-                        '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
-                        '401': errorResponse('Unauthorized'),
-                        '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
-                        '409': errorResponse('Conflict', ERROR_EXAMPLE_CONFLICT),
-                        '500': errorResponse('Internal server error'),
+            };
+        }
+        if (hasRestOperation(model, 'create')) {
+            collectionOps.post = {
+                tags: [tag],
+                summary: `Create ${model.name}`,
+                operationId: `create${model.name}`,
+                security: OPTIONAL_BEARER_SECURITY,
+                requestBody: {
+                    required: true,
+                    content: jsonContent(createRef),
+                },
+                responses: {
+                    '201': {
+                        description: `Created ${model.name}`,
+                        content: jsonContent(responseRef),
                     },
+                    '400': errorResponse('Validation error', ERROR_EXAMPLE_VALIDATION),
+                    '401': errorResponse('Unauthorized'),
+                    '403': errorResponse('Forbidden', ERROR_EXAMPLE_FORBIDDEN),
+                    '409': errorResponse('Conflict', ERROR_EXAMPLE_CONFLICT),
+                    '500': errorResponse('Internal server error'),
                 },
-            },
-        };
+            };
+        }
+        if (Object.keys(collectionOps).length > 0) {
+            paths[collectionPath] = collectionOps;
+        }
         if (pkFields.length > 0) {
             const pathParams = this.buildPathParameters(pkFields, model);
-            paths[itemPath] = {
-                get: {
+            const itemOps = {};
+            if (hasRestOperation(model, 'get')) {
+                itemOps.get = {
                     tags: [tag],
                     summary: `Get ${model.name}`,
                     operationId: `get${model.name}`,
@@ -219,8 +234,10 @@ export class OpenApiGenerator {
                         '404': errorResponse('Not found'),
                         '500': errorResponse('Internal server error'),
                     },
-                },
-                put: {
+                };
+            }
+            if (hasRestOperation(model, 'update')) {
+                itemOps.put = {
                     tags: [tag],
                     summary: `Update ${model.name}`,
                     operationId: `update${model.name}`,
@@ -242,8 +259,10 @@ export class OpenApiGenerator {
                         '409': errorResponse('Conflict', ERROR_EXAMPLE_CONFLICT),
                         '500': errorResponse('Internal server error'),
                     },
-                },
-                delete: {
+                };
+            }
+            if (hasRestOperation(model, 'delete')) {
+                itemOps.delete = {
                     tags: [tag],
                     summary: `Delete ${model.name}`,
                     operationId: `delete${model.name}`,
@@ -260,8 +279,11 @@ export class OpenApiGenerator {
                         '404': errorResponse('Not found'),
                         '500': errorResponse('Internal server error'),
                     },
-                },
-            };
+                };
+            }
+            if (Object.keys(itemOps).length > 0) {
+                paths[itemPath] = itemOps;
+            }
         }
         return paths;
     }

package/dist/api-generator/route-generator.d.ts

@@ -1,10 +1,17 @@
 import type { Model, Schema } from '../schema-dsl/ast.js';
+import type { CustomRouteMountEntry } from './custom-route-scanner.js';
+export interface RouteGeneratorOptions {
+    modelsWithHooks?: ReadonlySet<string>;
+    overlays?: ReadonlyMap<string, CustomRouteMountEntry>;
+}
 export declare class RouteGenerator {
     private readonly model;
     private readonly schema;
     private readonly modelsWithHooks;
-    constructor(model: Model, schema: Schema, modelsWithHooks?: ReadonlySet<string>);
-    generate(): string;
+    private readonly overlays;
+    constructor(model: Model, schema: Schema, options?: RouteGeneratorOptions);
+    generate(): string | null;
+    private generateOverlayOnly;
     private jsonRow;
     private jsonRows;
     private mutationJsonRow;
@@ -16,8 +23,8 @@ export declare class RouteGenerator {
     getRouteFileName(): string;
     getRouteBasePath(): string;
 }
-export declare function generateRouteFiles(schema: Schema, modelsWithHooks?: ReadonlySet<string>): Map<string, string>;
-export declare function getRouteMountEntries(schema: Schema): {
+export declare function generateRouteFiles(schema: Schema, modelsWithHooksOrOptions?: ReadonlySet<string> | RouteGeneratorOptions): Map<string, string>;
+export declare function getRouteMountEntries(schema: Schema, overlays?: ReadonlyMap<string, CustomRouteMountEntry>): {
     basePath: string;
     fileName: string;
     importName: string;

package/dist/api-generator/route-generator.js

@@ -4,74 +4,154 @@ import { getClientExportName } from '../db/type-generator.js';
 import { toRouteBasePath, toRouteFileName, toRouteImportName } from '../api/utils/route-naming.js';
 import { toModelConstantPrefix } from './utils/api-fields.js';
 import { hasPolicies } from './utils/policy.js';
+import { isRestEnabled, normalizeRest } from './utils/rest.js';
 export class RouteGenerator {
     model;
     schema;
     modelsWithHooks;
-    constructor(model, schema, modelsWithHooks = new Set()) {
+    overlays;
+    constructor(model, schema, options = {}) {
         this.model = model;
         this.schema = schema;
-        this.modelsWithHooks = modelsWithHooks;
+        this.modelsWithHooks = options.modelsWithHooks ?? new Set();
+        this.overlays = options.overlays ?? new Map();
     }
     generate() {
-        const clientKey = getClientExportName(this.model.name);
+        const rest = normalizeRest(this.model);
+        const overlay = this.overlays.get(this.model.name);
+        const operations = rest.operations;
+        if (operations.size === 0 && !overlay) {
+            return null;
+        }
+        if (operations.size === 0 && overlay) {
+            return this.generateOverlayOnly(overlay);
+        }
+        const needsPk = operations.has('get') || operations.has('update') || operations.has('delete');
         const primaryKey = getPrimaryKey(this.model);
-        if (!primaryKey) {
+        if (needsPk && !primaryKey) {
             throw new Error(`Model ${this.model.name} has no primary key`);
         }
-        const pathParams = primaryKey.fields.map((field) => `:${field}`).join('/');
-        const whereFromParams = primaryKey.fields.map((field) => `${field}: params.${field}`).join(', ');
+        const clientKey = getClientExportName(this.model.name);
+        const pathParams = primaryKey?.fields.map((field) => `:${field}`).join('/') ?? '';
+        const whereFromParams = primaryKey?.fields.map((field) => `${field}: params.${field}`).join(', ') ?? '';
         const paramSchemaName = `${this.model.name}ParamSchema`;
         const listQuerySchemaName = `${this.model.name}ListQuerySchema`;
         const getQuerySchemaName = `${this.model.name}GetQuerySchema`;
         const modelHasPolicies = hasPolicies(this.model);
-        const modelHasHooks = this.modelsWithHooks.has(this.model.name);
+        const hasWriteOps = operations.has('create') || operations.has('update') || operations.has('delete');
+        const modelHasHooks = hasWriteOps && this.modelsWithHooks.has(this.model.name);
         const constantPrefix = toModelConstantPrefix(this.model.name);
+        const needsValidateJson = operations.has('create') || operations.has('update');
+        const needsValidateParam = operations.has('get') || operations.has('update') || operations.has('delete');
+        const needsValidateQuery = operations.has('list') || operations.has('get');
+        const needsNotFound = operations.has('get');
+        const needsBuildReadQuery = operations.has('list');
+        const needsParseInclude = operations.has('get');
+        const needsOmitFields = hasWriteOps;
+        const needsShapeResponse = operations.has('list') || operations.has('get');
+        const validateImports = [];
+        if (needsValidateJson)
+            validateImports.push('validateJson');
+        if (needsValidateParam)
+            validateImports.push('validateParam');
+        if (needsValidateQuery)
+            validateImports.push('validateQuery');
+        const schemaImports = [];
+        if (operations.has('create'))
+            schemaImports.push(`  ${this.model.name}CreateSchema,`);
+        if (operations.has('update'))
+            schemaImports.push(`  ${this.model.name}UpdateSchema,`);
+        if (needsValidateParam)
+            schemaImports.push(`  ${paramSchemaName},`);
+        if (operations.has('list'))
+            schemaImports.push(`  ${listQuerySchemaName},`);
+        if (operations.has('get'))
+            schemaImports.push(`  ${getQuerySchemaName},`);
+        if (operations.has('list')) {
+            schemaImports.push(`  ${constantPrefix}_LIST_QUERY_FIELDS,`);
+            schemaImports.push(`  ${constantPrefix}_SORTABLE_FIELDS,`);
+        }
+        if (operations.has('list') || operations.has('get')) {
+            schemaImports.push(`  ${constantPrefix}_INCLUDABLE_RELATIONS,`);
+        }
+        if (needsOmitFields)
+            schemaImports.push(`  ${constantPrefix}_OMIT_FIELDS,`);
+        if (needsShapeResponse) {
+            schemaImports.push(`  API_OMIT_FIELDS_BY_MODEL,`);
+            schemaImports.push(`  API_RELATION_TARGETS,`);
+        }
+        const handlerBlocks = [];
+        if (operations.has('list')) {
+            handlerBlocks.push(this.generateListRoute(clientKey, modelHasPolicies, listQuerySchemaName, constantPrefix));
+        }
+        if (operations.has('get')) {
+            handlerBlocks.push(this.generateGetRoute(clientKey, pathParams, paramSchemaName, getQuerySchemaName, whereFromParams, modelHasPolicies, constantPrefix));
+        }
+        if (operations.has('create')) {
+            handlerBlocks.push(this.generateCreateRoute(clientKey, modelHasPolicies, modelHasHooks, constantPrefix));
+        }
+        if (operations.has('update')) {
+            handlerBlocks.push(this.generateUpdateRoute(clientKey, pathParams, paramSchemaName, whereFromParams, modelHasPolicies, modelHasHooks, constantPrefix));
+        }
+        if (operations.has('delete')) {
+            handlerBlocks.push(this.generateDeleteRoute(clientKey, pathParams, paramSchemaName, whereFromParams, modelHasPolicies, modelHasHooks, constantPrefix));
+        }
+        const lines = [
+            '// Auto-generated by RouteGenerator. Do not edit manually.',
+            "import { Hono } from 'hono';",
+            `import type { AppEnv } from '${PACKAGE_NAME}/api/types';`,
+        ];
+        if (validateImports.length > 0) {
+            lines.push(`import { ${validateImports.join(', ')} } from '${PACKAGE_NAME}/api/middleware/validate';`);
+        }
+        if (needsNotFound) {
+            lines.push(`import { notFoundResponse } from '${PACKAGE_NAME}/api/middleware/errors';`);
+        }
+        if (needsBuildReadQuery) {
+            lines.push(`import { buildReadQuery } from '${PACKAGE_NAME}/api/utils/read-query';`);
+        }
+        if (needsParseInclude) {
+            lines.push(`import { parseIncludeQuery } from '${PACKAGE_NAME}/api/utils/include-query';`);
+        }
+        if (needsOmitFields) {
+            lines.push(`import { omitFields } from '${PACKAGE_NAME}/api/utils/omit-fields';`);
+        }
+        if (needsShapeResponse) {
+            lines.push(`import { shapeResponse, shapeResponseMany } from '${PACKAGE_NAME}/api/utils/response-shape';`);
+        }
+        if (modelHasPolicies) {
+            lines.push(`import { assertPolicy, mergeWhere, resolvePolicyWhere } from '${PACKAGE_NAME}/api/auth/policy';`);
+        }
+        if (modelHasHooks) {
+            lines.push(`import { cancelledResponse, createHookContext, runAfterHooks, runBeforeHooks } from '${PACKAGE_NAME}/api/hooks';`);
+        }
+        if (schemaImports.length > 0) {
+            lines.push('import {');
+            lines.push(...schemaImports);
+            lines.push(`} from '../schemas/validation.js';`);
+        }
+        if (overlay) {
+            lines.push(`import ${overlay.importName}Overlay from '${overlay.routeImportPath}';`);
+        }
+        lines.push('', 'const router = new Hono<AppEnv>();', '');
+        for (const block of handlerBlocks) {
+            lines.push(...block, '');
+        }
+        if (overlay) {
+            lines.push(`router.route('/', ${overlay.importName}Overlay);`, '');
+        }
+        lines.push('export default router;', '');
+        return lines.join('\n');
+    }
+    generateOverlayOnly(overlay) {
         return [
             '// Auto-generated by RouteGenerator. Do not edit manually.',
             "import { Hono } from 'hono';",
             `import type { AppEnv } from '${PACKAGE_NAME}/api/types';`,
-            `import { validateJson, validateParam, validateQuery } from '${PACKAGE_NAME}/api/middleware/validate';`,
-            `import { notFoundResponse } from '${PACKAGE_NAME}/api/middleware/errors';`,
-            `import { buildReadQuery } from '${PACKAGE_NAME}/api/utils/read-query';`,
-            `import { parseIncludeQuery } from '${PACKAGE_NAME}/api/utils/include-query';`,
-            `import { omitFields } from '${PACKAGE_NAME}/api/utils/omit-fields';`,
-            `import { shapeResponse, shapeResponseMany } from '${PACKAGE_NAME}/api/utils/response-shape';`,
-            ...(modelHasPolicies
-                ? [
-                    `import { assertPolicy, mergeWhere, resolvePolicyWhere } from '${PACKAGE_NAME}/api/auth/policy';`,
-                ]
-                : []),
-            ...(modelHasHooks
-                ? [
-                    `import { cancelledResponse, createHookContext, runAfterHooks, runBeforeHooks } from '${PACKAGE_NAME}/api/hooks';`,
-                ]
-                : []),
-            `import {`,
-            `  ${this.model.name}CreateSchema,`,
-            `  ${this.model.name}UpdateSchema,`,
-            `  ${paramSchemaName},`,
-            `  ${listQuerySchemaName},`,
-            `  ${getQuerySchemaName},`,
-            `  ${constantPrefix}_LIST_QUERY_FIELDS,`,
-            `  ${constantPrefix}_INCLUDABLE_RELATIONS,`,
-            `  ${constantPrefix}_OMIT_FIELDS,`,
-            `  ${constantPrefix}_SORTABLE_FIELDS,`,
-            `  API_OMIT_FIELDS_BY_MODEL,`,
-            `  API_RELATION_TARGETS,`,
-            `} from '../schemas/validation.js';`,
+            `import ${overlay.importName}Overlay from '${overlay.routeImportPath}';`,
             '',
             'const router = new Hono<AppEnv>();',
-            '',
-            ...this.generateListRoute(clientKey, modelHasPolicies, listQuerySchemaName, constantPrefix),
-            '',
-            ...this.generateGetRoute(clientKey, pathParams, paramSchemaName, getQuerySchemaName, whereFromParams, modelHasPolicies, constantPrefix),
-            '',
-            ...this.generateCreateRoute(clientKey, modelHasPolicies, modelHasHooks, constantPrefix),
-            '',
-            ...this.generateUpdateRoute(clientKey, pathParams, paramSchemaName, whereFromParams, modelHasPolicies, modelHasHooks, constantPrefix),
-            '',
-            ...this.generateDeleteRoute(clientKey, pathParams, paramSchemaName, whereFromParams, modelHasPolicies, modelHasHooks, constantPrefix),
+            `router.route('/', ${overlay.importName}Overlay);`,
             '',
             'export default router;',
             '',
@@ -264,16 +344,36 @@ export class RouteGenerator {
         return toRouteBasePath(this.model.name);
     }
 }
-export function generateRouteFiles(schema, modelsWithHooks = new Set()) {
+export function generateRouteFiles(schema, modelsWithHooksOrOptions = new Set()) {
+    const options = normalizeRouteGeneratorOptions(modelsWithHooksOrOptions);
     const files = new Map();
     for (const model of schema.models) {
-        const generator = new RouteGenerator(model, schema, modelsWithHooks);
-        files.set(generator.getRouteFileName(), generator.generate());
+        const generator = new RouteGenerator(model, schema, options);
+        const content = generator.generate();
+        if (content !== null) {
+            files.set(generator.getRouteFileName(), content);
+        }
     }
     return files;
 }
-export function getRouteMountEntries(schema) {
-    return schema.models.map((model) => {
+function normalizeRouteGeneratorOptions(value) {
+    if (value instanceof Set) {
+        return { modelsWithHooks: value };
+    }
+    if (value &&
+        typeof value === 'object' &&
+        'has' in value &&
+        typeof value.has === 'function' &&
+        !('overlays' in value) &&
+        !('modelsWithHooks' in value)) {
+        return { modelsWithHooks: value };
+    }
+    return value;
+}
+export function getRouteMountEntries(schema, overlays = new Map()) {
+    return schema.models
+        .filter((model) => isRestEnabled(model) || overlays.has(model.name))
+        .map((model) => {
         const basePath = toRouteBasePath(model.name);
         const fileName = toRouteFileName(model.name);
         const importName = toRouteImportName(basePath);

package/dist/api-generator/utils/rest.d.ts

@@ -0,0 +1,9 @@
+import type { Model } from '../../schema-dsl/ast.js';
+export type RestOperation = 'list' | 'get' | 'create' | 'update' | 'delete';
+export declare const REST_OPERATIONS: RestOperation[];
+export interface NormalizedRest {
+    operations: Set<RestOperation>;
+}
+export declare function normalizeRest(model: Model): NormalizedRest;
+export declare function isRestEnabled(model: Model): boolean;
+export declare function hasRestOperation(model: Model, operation: RestOperation): boolean;

package/dist/api-generator/utils/rest.js

@@ -0,0 +1,93 @@
+import { assertKeyValueArgs, getOptionalKvPair } from '../../sql-generator/utils/ast-helpers.js';
+export const REST_OPERATIONS = ['list', 'get', 'create', 'update', 'delete'];
+const HTTP_VERB_HINTS = {
+    GET: 'list or get',
+    POST: 'create',
+    PUT: 'update',
+    PATCH: 'update',
+    DELETE: 'delete',
+};
+export function normalizeRest(model) {
+    const fieldRest = model.fields.find((field) => field.attributes.some((attribute) => attribute.name === 'rest'));
+    if (fieldRest) {
+        throw new Error(`@rest on model ${model.name} must be a model attribute, not a field attribute on "${fieldRest.name}"`);
+    }
+    const restAttributes = model.attributes.filter((attribute) => attribute.name === 'rest');
+    if (restAttributes.length === 0) {
+        return { operations: new Set(REST_OPERATIONS) };
+    }
+    if (restAttributes.length > 1) {
+        throw new Error(`Model ${model.name} has duplicate @rest attributes`);
+    }
+    return normalizeRestAttribute(restAttributes[0], model.name);
+}
+export function isRestEnabled(model) {
+    return normalizeRest(model).operations.size > 0;
+}
+export function hasRestOperation(model, operation) {
+    return normalizeRest(model).operations.has(operation);
+}
+function normalizeRestAttribute(attribute, modelName) {
+    if (!attribute.args) {
+        return { operations: new Set() };
+    }
+    if (attribute.args.kind === 'ExpressionArgs') {
+        if (attribute.args.expressions.length === 0) {
+            throw new Error(`@rest() on model ${modelName} is empty; use @rest, @rest(false), only, or except`);
+        }
+        if (attribute.args.expressions.length !== 1) {
+            throw new Error(`@rest on model ${modelName} expects a single boolean or key-value args`);
+        }
+        const expression = attribute.args.expressions[0];
+        if (expression.kind === 'BooleanLiteral') {
+            if (expression.value === false) {
+                return { operations: new Set() };
+            }
+            return { operations: new Set(REST_OPERATIONS) };
+        }
+        throw new Error(`@rest on model ${modelName} expects false, only, or except`);
+    }
+    const args = assertKeyValueArgs(attribute.args);
+    const onlyPair = getOptionalKvPair(args, 'only');
+    const exceptPair = getOptionalKvPair(args, 'except');
+    if (onlyPair && exceptPair) {
+        throw new Error(`@rest on model ${modelName} cannot mix only and except`);
+    }
+    if (!onlyPair && !exceptPair) {
+        throw new Error(`@rest on model ${modelName} requires only, except, or false`);
+    }
+    if (onlyPair) {
+        return { operations: new Set(parseRestOperations(onlyPair.value, modelName, 'only')) };
+    }
+    const excluded = new Set(parseRestOperations(exceptPair.value, modelName, 'except'));
+    return {
+        operations: new Set(REST_OPERATIONS.filter((operation) => !excluded.has(operation))),
+    };
+}
+function parseRestOperations(value, modelName, fieldName) {
+    if (value.kind !== 'ArrayLiteral') {
+        throw new Error(`@rest ${fieldName} on model ${modelName} must be an array of operations`);
+    }
+    return value.elements.map((element) => parseRestOperation(element, modelName));
+}
+function parseRestOperation(value, modelName) {
+    if (value.kind !== 'Identifier') {
+        throw new Error(`@rest operation on model ${modelName} must be an identifier`);
+    }
+    const raw = value.name;
+    const httpHint = HTTP_VERB_HINTS[raw.toUpperCase()];
+    if (httpHint && raw === raw.toUpperCase()) {
+        throw new Error(`Unknown @rest operation "${raw}" on model ${modelName}; use ${httpHint} instead of HTTP verb "${raw}"`);
+    }
+    const operation = raw.toLowerCase();
+    if (isRestOperation(operation)) {
+        return operation;
+    }
+    if (httpHint) {
+        throw new Error(`Unknown @rest operation "${raw}" on model ${modelName}; use ${httpHint} instead of HTTP verb "${raw}"`);
+    }
+    throw new Error(`Unknown @rest operation "${raw}" on model ${modelName}; expected one of ${REST_OPERATIONS.join(', ')}`);
+}
+function isRestOperation(value) {
+    return REST_OPERATIONS.includes(value);
+}

package/dist/cli/generate.d.ts

@@ -1,4 +1,5 @@
 export declare function generateSql(schemaPath?: string): Promise<string>;
 export declare function generateClient(schemaPath?: string): Promise<void>;
 export declare function generateApi(schemaPath?: string): Promise<void>;
+export declare function syncGeneratedRouteFiles(routesDir: string, routes: Map<string, string>): Promise<void>;
 export declare function generateAll(schemaPath?: string): Promise<void>;

package/dist/cli/generate.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parse } from '../schema-dsl/index.js';
 import { generateApiFiles } from '../api-generator/index.js';
@@ -38,10 +38,17 @@ export async function generateApi(schemaPath) {
     await writeFile(path.join(schemasDir, 'validation.ts'), files.validation, 'utf8');
     await writeFile(path.join(outputDir, 'openapi.ts'), files.openapiTs, 'utf8');
     await writeFile(path.join(outputDir, 'openapi.json'), files.openapiJson, 'utf8');
-    for (const [fileName, content] of files.routes) {
+    await syncGeneratedRouteFiles(routesDir, files.routes);
+    console.log(`Generated API files in ${outputDir}`);
+}
+export async function syncGeneratedRouteFiles(routesDir, routes) {
+    for (const [fileName, content] of routes) {
         await writeFile(path.join(routesDir, fileName), content, 'utf8');
     }
-    console.log(`Generated API files in ${outputDir}`);
+    const existing = await readdir(routesDir);
+    await Promise.all(existing
+        .filter((fileName) => fileName.endsWith('.ts') && !routes.has(fileName))
+        .map((fileName) => unlink(path.join(routesDir, fileName))));
 }
 export async function generateAll(schemaPath) {
     const resolvedSchemaPath = resolveSchemaPath(schemaPath);

package/dist/cli/templates/agents.md

@@ -25,7 +25,7 @@ my-app/
 ├── app.schema              # Source of truth — edit this
 ├── schema.sql              # Generated PostgreSQL DDL (read-only)
 ├── AGENTS.md               # This file
-├── .env                    # DATABASE_URL, JWT_* settings
+├── .env                    # DATABASE_URL, JWT_*, CORS_ORIGIN
 ├── docker-compose.yml      # Local PostgreSQL
 ├── generated/              # Generated — do not edit
 │   ├── db.ts               # createDbClient(pool)
@@ -59,6 +59,7 @@ npx schematic-pg dev
 | `JWT_SECRET` | HMAC secret for Bearer JWT auth |
 | `JWT_ROLE_CLAIM` | JWT claim for role (default `role`) |
 | `JWT_USER_ID_CLAIM` | JWT claim for user id (default `sub`) |
+| `CORS_ORIGIN` | Allowed browser origins (`*` or comma-separated). Unset disables CORS |
 
 ## Schema DSL Essentials
 
@@ -77,7 +78,8 @@ models {
 
     orders: Order[]
 
-    @policy(role: USER, allow: [select, update], where: "id = {{auth.user.id}}")
+    @rest(except: [create, update, delete])
+    @policy(role: USER, allow: [select], where: "id = {{auth.user.id}}")
     @policy(role: ADMIN, allow: all)
 
     @@index(fields: [role])
@@ -93,6 +95,7 @@ models {
 **Key concepts:**
 
 - **Relations:** Put `@relation(fields: [...], references: [...])` on the FK-owning side. The inverse side is inferred.
+- **REST surface:** `@rest(only: [...])`, `@rest(except: [...])`, or `@rest(false)` controls which CRUD handlers are generated (`list`/`get`/`create`/`update`/`delete`).
 - **Policies:** `@policy(role: ..., allow: [select|insert|update|delete|all], where: "...")` — `where` supports `{{auth.user.id}}`.
 - **Validation:** `@regex(...)`, `@range(min: ..., max: ...)` flow into generated Zod schemas.
 - **Indexes / triggers:** `@@index(...)`, `@@trigger { timing, event, level, execute: """...""" }`.
@@ -225,8 +228,9 @@ Also available: `ForeignKeyConstraintError`, `DatabaseError`.
 | Location | `src/routes/**/*.ts` |
 | Export | `export default router` (`Hono<AppEnv>`) |
 | Mount path | File path relative to `src/routes/` |
+| Same-path overlay | `src/routes/users.ts` merges into `generated/routes/users.ts` |
 
-`src/routes/health.ts` → `GET /health`. Regenerate after adding files.
+`src/routes/health.ts` → `GET /health` (standalone). When the file name matches a model route (`users.ts`), it is imported into the generated model router after remaining `@rest` handlers. Regenerate after adding files.
 
 ```typescript
 import { Hono } from 'hono';
@@ -276,6 +280,7 @@ schematic-pg hooks:add [--model X]   # scaffold src/hooks/{Model}.ts
 - Unauthenticated requests default to `{ role: 'PUBLIC' }`.
 - `@policy` `allow` maps to HTTP: GET→select, POST→insert, PUT→update, DELETE→delete.
 - Row-level `where` is injected on read/update/delete; POST checks permission only.
+- `@rest` controls which handlers exist; disabled methods return `404` and are omitted from OpenAPI.
 
 ## Generated Outputs (Read-Only)
 

package/dist/cli/templates.d.ts

@@ -1,6 +1,6 @@
 export declare const AGENTS_TEMPLATE: string;
-export declare const APP_SCHEMA_TEMPLATE = "extensions {\n\n}\n\nenums {\n  UserRole { ADMIN, USER }\n}\n\nmodels {\n  model User {\n    id:           UUID         @id @default(gen_random_uuid())\n    email:        VARCHAR(255) @unique @regex(pattern: \"^[\\w.-]+@[\\w.-]+\\.\\w+$\", message: \"Invalid email address\")\n    name:         VARCHAR(150)?\n    role:         UserRole     @default(USER)\n    passwordHash: VARCHAR(255)? @omit @unfilterable\n    createdAt:    TIMESTAMP    @default(now())\n\n    @policy(role: USER, allow: [select, update], where: \"id = {{auth.user.id}}\")\n    @policy(role: ADMIN, allow: all)\n  }\n}\n";
-export declare const ENV_TEMPLATE = "DATABASE_URL=postgresql://postgrest:postgrest@localhost:5432/postgrest\nJWT_SECRET=\nAUTH_PEPPER=\nAUTH_ACCESS_TOKEN_TTL=1h\nJWT_ROLE_CLAIM=role\nJWT_USER_ID_CLAIM=sub\n";
+export declare const APP_SCHEMA_TEMPLATE = "extensions {\n\n}\n\nenums {\n  UserRole { ADMIN, USER }\n}\n\nmodels {\n  model User {\n    id:           UUID         @id @default(gen_random_uuid())\n    email:        VARCHAR(255) @unique @regex(pattern: \"^[\\w.-]+@[\\w.-]+\\.\\w+$\", message: \"Invalid email address\")\n    name:         VARCHAR(150)?\n    role:         UserRole     @default(USER)\n    passwordHash: VARCHAR(255)? @omit @unfilterable\n    createdAt:    TIMESTAMP    @default(now())\n\n    @rest(except: [create, update, delete])\n    @policy(role: USER, allow: [select], where: \"id = {{auth.user.id}}\")\n    @policy(role: ADMIN, allow: all)\n  }\n}\n";
+export declare const ENV_TEMPLATE = "DATABASE_URL=postgresql://postgrest:postgrest@localhost:5432/postgrest\nJWT_SECRET=\nAUTH_PEPPER=\nAUTH_ACCESS_TOKEN_TTL=1h\nJWT_ROLE_CLAIM=role\nJWT_USER_ID_CLAIM=sub\nCORS_ORIGIN=\n";
 export declare const GITIGNORE_TEMPLATE = "node_modules/\ndist/\n.env\ndocker_data/\n.DS_Store\n*.log\nnpm-debug.log*\n";
 export declare const DOCKER_COMPOSE_TEMPLATE = "services:\n  postgres:\n    image: postgres:18.4-bookworm\n    container_name: schematic-pg\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgrest\n      POSTGRES_PASSWORD: postgrest\n      POSTGRES_DB: postgrest\n    volumes:\n      - ./docker_data/postgres:/var/lib/postgresql\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgrest -d postgrest\"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n";
 export declare const TSCONFIG_TEMPLATE = "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"NodeNext\",\n    \"moduleResolution\": \"NodeNext\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"outDir\": \"dist\",\n    \"rootDir\": \".\"\n  },\n  \"include\": [\"generated/**/*\", \"src/**/*\"]\n}\n";

package/dist/cli/templates.js

@@ -21,7 +21,8 @@ models {
     passwordHash: VARCHAR(255)? @omit @unfilterable
     createdAt:    TIMESTAMP    @default(now())
 
-    @policy(role: USER, allow: [select, update], where: "id = {{auth.user.id}}")
+    @rest(except: [create, update, delete])
+    @policy(role: USER, allow: [select], where: "id = {{auth.user.id}}")
     @policy(role: ADMIN, allow: all)
   }
 }
@@ -32,6 +33,7 @@ AUTH_PEPPER=
 AUTH_ACCESS_TOKEN_TTL=1h
 JWT_ROLE_CLAIM=role
 JWT_USER_ID_CLAIM=sub
+CORS_ORIGIN=
 `;
 export const GITIGNORE_TEMPLATE = `node_modules/
 dist/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematic-pg",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Single-file backend framework for PostgreSQL and Node.js",
   "type": "module",
   "license": "MIT",