@pylonts/dsl 1.0.6 → 1.1.2

package/dist/mysql-driver.js

@@ -1,7 +1,8 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildCreateTableSql = buildCreateTableSql;
 // MySQL driver: converts a TableSchema into a CREATE TABLE statement.
+/** Default value constant for created_at columns. */
+export const CURRENT_TIMESTAMP = 'CURRENT_TIMESTAMP';
+/** Default value constant for updated_at columns (with auto-update). */
+export const CURRENT_TIMESTAMP_ON_UPDATE = 'CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP';
 function columnType(field) {
     switch (field.type) {
         case 'string':
@@ -31,14 +32,28 @@ function columnType(field) {
             return 'JSON';
     }
 }
+function renderDefault(field) {
+    if (field.default === undefined)
+        return '';
+    // MySQL keyword expressions (CURRENT_TIMESTAMP, CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+    // NULL, etc.) — render bare, no quotes.
+    if (/^[A-Z]/.test(field.default))
+        return ` DEFAULT ${field.default}`;
+    // Numeric columns take a bare literal, not a quoted one.
+    if (field.type === 'integer' || field.type === 'bigint' || field.type === 'decimal' || field.type === 'boolean') {
+        return ` DEFAULT ${field.default}`;
+    }
+    return ` DEFAULT '${field.default}'`;
+}
 function columnDef(field, autoIncrement) {
     const parts = [field.name, columnType(field)];
     if (field.optional === false)
         parts.push('NOT NULL');
-    if (field.default !== undefined)
-        parts.push(`DEFAULT '${field.default}'`);
+    parts.push(renderDefault(field));
     if (field === autoIncrement)
         parts.push('AUTO_INCREMENT');
+    if (field.description)
+        parts.push(`COMMENT '${field.description.replace(/'/g, "\\'")}'`);
     return parts.join(' ');
 }
 function primaryKeyClause(schema) {
@@ -48,13 +63,13 @@ function primaryKeyClause(schema) {
     return `PRIMARY KEY (${fields.map((f) => f.name).join(', ')})`;
 }
 function indexClause(index) {
-    const fields = Array.isArray(index.fields) ? index.fields : [index.fields];
+    const fields = Array.isArray(index.columns) ? index.columns : [index.columns];
     const kind = index.unique ? 'UNIQUE KEY' : 'KEY';
     const name = index.name ?? fields.map((f) => f.name).join('_');
     return `${kind} ${name} (${fields.map((f) => f.name).join(', ')})`;
 }
 function foreignKeyClause(name, fk) {
-    const fields = Array.isArray(fk.fields) ? fk.fields : [fk.fields];
+    const fields = Array.isArray(fk.columns) ? fk.columns : [fk.columns];
     const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
     const refTable = refs[0].schema?.name;
     if (!refTable)
@@ -63,8 +78,8 @@ function foreignKeyClause(name, fk) {
     const refCols = refs.map((r) => r.name).join(', ');
     return `CONSTRAINT \`${name}\` FOREIGN KEY (${fkCols}) REFERENCES \`${refTable}\` (${refCols})`;
 }
-function buildCreateTableSql(schema, options = {}) {
-    const lines = Object.values(schema.fields).map((field) => columnDef(field, schema.autoIncrement));
+export function buildCreateTableSql(schema, options = {}) {
+    const lines = Object.values(schema.columns).map((field) => columnDef(field, schema.autoIncrement));
     const pk = primaryKeyClause(schema);
     if (pk)
         lines.push(pk);
@@ -75,5 +90,5 @@ function buildCreateTableSql(schema, options = {}) {
             lines.push(foreignKeyClause(name, fk));
         }
     }
-    return `CREATE TABLE \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
+    return `CREATE TABLE IF NOT EXISTS \`${schema.name}\` (\n  ${lines.join(',\n  ')}\n);`;
 }

package/dist/navigation.d.ts

@@ -0,0 +1,22 @@
+import type { RouteDataSchema } from './route.js';
+import type { ActionSchema } from './action.js';
+import { PageSchema } from './page.js';
+/** Navigation primitives: front-end routing actions that are not provider calls. */
+export interface NavigationAction extends ActionSchema {
+    type: 'navigation';
+    method: 'back' | 'push' | 'popup' | 'home';
+    /** Target page for push navigation. */
+    target?: PageSchema;
+    /** Route params type for push navigation. Auto-derived from target.params if omitted. */
+    params?: RouteDataSchema;
+}
+export declare const navigation: {
+    back(description?: string): NavigationAction;
+    push(options: {
+        target: PageSchema;
+        params?: RouteDataSchema;
+        description?: string;
+    }): NavigationAction;
+    popup(description?: string): NavigationAction;
+    home(description?: string): NavigationAction;
+};

package/dist/navigation.js

@@ -0,0 +1,15 @@
+export const navigation = {
+    back(description) {
+        return { name: 'back', type: 'navigation', method: 'back', description };
+    },
+    push(options) {
+        const { target, params, description } = options;
+        return { name: 'push', type: 'navigation', method: 'push', target, params: params ?? target.params, description };
+    },
+    popup(description) {
+        return { name: 'popup', type: 'navigation', method: 'popup', description };
+    },
+    home(description) {
+        return { name: 'home', type: 'navigation', method: 'home', description };
+    },
+};

package/dist/page-def.d.ts

@@ -0,0 +1,40 @@
+import type { ImportableSchemaBase, CollectionSchemaBase, SchemaBase } from './dsl.js';
+import { DtoField } from './dto.js';
+import type { DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
+import type { ComponentSchema } from './component.js';
+import type { ActionSchema } from './action.js';
+export type { RouteDataSchema } from './route.js';
+export { defineRouteData } from './route.js';
+/** Page lifecycle events that trigger data loading. */
+export interface EventSchema extends SchemaBase {
+    type: 'onLoad' | 'onShow' | 'onHide' | 'onPullDownRefresh' | 'onReachBottom';
+    /** Actions that fire when this event occurs. */
+    actions?: ActionSchema[];
+}
+export declare const events: {
+    onLoad(actions?: ActionSchema[], description?: string): EventSchema;
+    onShow(actions?: ActionSchema[], description?: string): EventSchema;
+    onHide(actions?: ActionSchema[], description?: string): EventSchema;
+    onPullDownRefresh(actions?: ActionSchema[], description?: string): EventSchema;
+    onReachBottom(actions?: ActionSchema[], description?: string): EventSchema;
+};
+/** Page data: a named collection of fields that defines the page's data shape. */
+export interface PageDataSchema extends CollectionSchemaBase {
+    type: 'pageData';
+    fields: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField>;
+}
+export declare function definePageData(fields: PageDataSchema['fields']): PageDataSchema;
+/** Page skeleton definition. */
+export interface PageDef extends ImportableSchemaBase {
+    data: PageDataSchema;
+    /** Lifecycle events that trigger data loading. */
+    events: EventSchema[];
+    /** Page actions (provider calls, navigation, etc.). */
+    actions: ActionSchema[];
+    /** UI component declarations that make up the page skeleton. */
+    components: ComponentSchema[];
+    /** Whether the driver should generate page-level loading / error / empty state wrappers. */
+    handleStates?: boolean;
+}
+/** Define a page skeleton. */
+export declare function definePageDef(name: string, schema: Omit<PageDef, 'name'>): PageDef;

package/dist/page-def.js

@@ -0,0 +1,38 @@
+import { DtoField } from './dto.js';
+export { defineRouteData } from './route.js';
+export const events = {
+    onLoad(actions, description) {
+        return { name: 'onLoad', type: 'onLoad', actions, description };
+    },
+    onShow(actions, description) {
+        return { name: 'onShow', type: 'onShow', actions, description };
+    },
+    onHide(actions, description) {
+        return { name: 'onHide', type: 'onHide', actions, description };
+    },
+    onPullDownRefresh(actions, description) {
+        return { name: 'onPullDownRefresh', type: 'onPullDownRefresh', actions, description };
+    },
+    onReachBottom(actions, description) {
+        return { name: 'onReachBottom', type: 'onReachBottom', actions, description };
+    },
+};
+export function definePageData(fields) {
+    // Page data has no meaningful identity of its own; the page name already
+    // scopes it, so the schema name defaults to 'data'.
+    const data = { name: 'data', type: 'pageData', fields };
+    // Write back field names (same convention as buildMessage) so defineRef
+    // produces refs with a real field name instead of ''.
+    for (const key of Object.keys(data.fields)) {
+        const df = data.fields[key];
+        if (df instanceof DtoField) {
+            df.name = key;
+            df.schema = data;
+        }
+    }
+    return data;
+}
+/** Define a page skeleton. */
+export function definePageDef(name, schema) {
+    return { name, ...schema };
+}

package/dist/page-flow.d.ts

@@ -1,5 +1,6 @@
-import { SchemaBase } from './dsl';
-import { ActionSchema, Page } from './page';
+import { SchemaBase } from './dsl.js';
+import type { ActionSchema } from './action.js';
+import { Page } from './page.js';
 export interface PageEdge extends SchemaBase {
     /** Trigger action; undefined = default path (success/normal). */
     when?: ActionSchema;
@@ -9,13 +10,14 @@ export interface PageEdge extends SchemaBase {
 export interface PageFlow extends SchemaBase {
     /** Entry page. */
     start: Page;
-    /** All pages, collected from edges (deduplicated by object identity). */
+    /** All pages explicitly declared by the caller. */
     pages: Page[];
     edges: PageEdge[];
 }
 export declare function pageEdge(start: Page, end: Page, when?: ActionSchema, description?: string): PageEdge;
 export declare function definePageFlow(name: string, schema: {
     start: Page;
+    pages: Page[];
     edges: PageEdge[];
     description?: string;
 }): PageFlow;

package/dist/page-flow.js

@@ -1,25 +1,116 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pageEdge = pageEdge;
-exports.definePageFlow = definePageFlow;
-function pageEdge(start, end, when, description) {
+import { getRegisteredPages, clearRegisteredPages } from './page.js';
+export function pageEdge(start, end, when, description) {
     // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
     return { name: `${start.name}->${end.name}`, start, end, when, description };
 }
-function definePageFlow(name, schema) {
-    const seen = new Set();
-    const pages = [];
-    for (const e of schema.edges) {
-        for (const p of [e.start, e.end]) {
-            if (!seen.has(p)) {
-                seen.add(p);
-                pages.push(p);
-            }
+export function definePageFlow(name, schema) {
+    const { start, pages, edges: explicitEdges, description } = schema;
+    // Resolve the back action from any page's actions list (PageSchema at runtime)
+    const backAction = findBackAction(pages);
+    // Auto-generate back edges: for every explicit edge A→B (not itself a back),
+    // if B has no explicit back edge and no existing edge B→A, add B→A with back.
+    const hasExplicitBack = new Set();
+    for (const e of explicitEdges) {
+        if (e.when && e.when.name === 'back')
+            hasExplicitBack.add(e.start);
+    }
+    const hasReverse = new Set();
+    for (const e of explicitEdges) {
+        hasReverse.add(`${e.start.name}->${e.end.name}`);
+    }
+    const generatedBackEdges = [];
+    if (backAction) {
+        for (const e of explicitEdges) {
+            if (e.when && e.when.name === 'back')
+                continue;
+            if (hasExplicitBack.has(e.end))
+                continue;
+            if (hasReverse.has(`${e.end.name}->${e.start.name}`))
+                continue;
+            generatedBackEdges.push({
+                name: `${e.end.name}->${e.start.name}`,
+                start: e.end,
+                end: e.start,
+                when: backAction,
+                description: 'auto-generated back edge',
+            });
+            hasExplicitBack.add(e.end);
+        }
+    }
+    const edges = [...explicitEdges, ...generatedBackEdges];
+    // Validate: every registered page must be in the flow's pages
+    const registered = getRegisteredPages();
+    const orphaned = [];
+    for (const rp of registered) {
+        // Compare by object identity — caller passes the same reference
+        if (!pages.includes(rp)) {
+            orphaned.push(rp.name);
+        }
+    }
+    if (orphaned.length > 0) {
+        throw new Error(`[definePageFlow "${name}"] orphaned pages (defined but not in flow): ${orphaned.join(', ')}`);
+    }
+    clearRegisteredPages();
+    // Validate: start must be in pages
+    if (!pages.includes(start)) {
+        throw new Error(`[definePageFlow "${name}"] start page "${start.name}" not in pages`);
+    }
+    // Validate: every page appears in at least one edge
+    const inEdge = new Set();
+    for (const e of edges) {
+        inEdge.add(e.start);
+        inEdge.add(e.end);
+    }
+    const isolated = [];
+    for (const p of pages) {
+        if (!inEdge.has(p))
+            isolated.push(p.name);
+    }
+    if (isolated.length > 0) {
+        throw new Error(`[definePageFlow "${name}"] isolated pages (no edges): ${isolated.join(', ')}`);
+    }
+    // Validate: all pages reachable from start
+    const adj = new Map();
+    for (const p of pages)
+        adj.set(p, []);
+    for (const e of edges) {
+        const neighbors = adj.get(e.start);
+        if (neighbors)
+            neighbors.push(e.end);
+    }
+    const visited = new Set();
+    const stack = [start];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        if (visited.has(cur))
+            continue;
+        visited.add(cur);
+        for (const next of adj.get(cur) ?? []) {
+            if (!visited.has(next))
+                stack.push(next);
         }
     }
-    if (!seen.has(schema.start)) {
-        seen.add(schema.start);
-        pages.push(schema.start);
+    const unreachable = [];
+    for (const p of pages) {
+        if (!visited.has(p))
+            unreachable.push(p.name);
+    }
+    if (unreachable.length > 0) {
+        throw new Error(`[definePageFlow "${name}"] unreachable pages: ${unreachable.join(', ')}`);
+    }
+    return { name, description, start, pages, edges };
+}
+/** Walk all pages' pageDef.actions (PageSchema runtime shape) to find a NavigationAction with method 'back'. */
+function findBackAction(pages) {
+    for (const p of pages) {
+        const pageDef = p.pageDef;
+        if (!pageDef?.actions)
+            continue;
+        for (const a of pageDef.actions) {
+            const na = a;
+            if (na.type === 'navigation' && na.method === 'back')
+                return na;
+        }
     }
-    return { name, description: schema.description, start: schema.start, pages, edges: schema.edges };
+    return undefined;
 }

package/dist/page.d.ts

@@ -1,26 +1,48 @@
-import { SchemaBase } from './dsl';
-import { FrontApp } from './project';
-/** Standalone page definition. A page is a shared value object: it lists
- *  the actions a user can perform, and belongs to exactly one frontend app. */
+import { SchemaBase } from './dsl.js';
+import { FrontAppSchema } from './project.js';
+import type { PageDef } from './page-def.js';
+import type { RouteDataSchema } from './route.js';
+export declare function getRegisteredPages(): ReadonlySet<PageSchema>;
+export declare function clearRegisteredPages(): void;
+/** Standalone page definition. A page is a shared value object: it belongs to
+ *  exactly one frontend app. Actions live in the page skeleton (PageDef.actions),
+ *  not on the page itself — the page only carries what the flow/topology needs. */
 export interface PageSchema extends SchemaBase {
+    /** Short display name for topology diagrams. */
+    label: string;
     /** The frontend app this page belongs to (shared instance from project.config). */
-    app: FrontApp;
-    /** Actions a user can perform on this page (e.g. submit, approve, reject). */
-    actions: ActionSchema[];
+    app: FrontAppSchema;
+    /** Full page skeleton definition (optional). */
+    pageDef?: PageDef;
+    /** Route params this page expects (e.g. detail page expects productId). */
+    params?: RouteDataSchema;
 }
-/** An action a user can perform on a page (e.g. submit, approve, reject). */
-export interface ActionSchema extends SchemaBase {
-}
-export declare function defineAction(name: string, description?: string): ActionSchema;
 export declare function definePage(schema: {
     name: string;
+    label: string;
     description?: string;
-    app: FrontApp;
-    actions: ActionSchema[];
+    app: FrontAppSchema;
+    pageDef?: PageDef;
+    params?: RouteDataSchema;
 }): PageSchema;
+/** Page with bottom tab navigation. tabs collects the child pages reachable via tab switch. */
+export interface TabPageSchema extends PageSchema {
+    tabs: PageSchema[];
+}
+export declare function defineTabPage(schema: {
+    name: string;
+    label: string;
+    description?: string;
+    app: FrontAppSchema;
+    tabs: PageSchema[];
+    pageDef?: PageDef;
+    params?: RouteDataSchema;
+}): TabPageSchema;
 /** A page node in a page-driven flow: every node is a page, and a page belongs to an app. */
 export interface Page extends SchemaBase {
+    /** Short display name for topology diagrams. */
+    label?: string;
     /** The frontend app this page belongs to (shared instance from project.config). */
-    app: FrontApp;
+    app: FrontAppSchema;
 }
-export declare function page(app: FrontApp, name: string, description?: string): Page;
+export declare function page(app: FrontAppSchema, name: string, description?: string, label?: string): Page;

package/dist/page.js

@@ -1,14 +1,24 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineAction = defineAction;
-exports.definePage = definePage;
-exports.page = page;
-function defineAction(name, description) {
-    return { name, description };
-}
-function definePage(schema) {
-    return { ...schema };
-}
-function page(app, name, description) {
-    return { name, app, description };
+// Page definitions: standalone page schemas and the page node type used by
+// page-driven flows. Kept separate from page-flow.ts (the flow graph itself).
+// Module-level registry: every definePage/defineTabPage call registers its
+// result so definePageFlow can check that no page is left out.
+const _pageRegistry = new Set();
+export function getRegisteredPages() {
+    return _pageRegistry;
+}
+export function clearRegisteredPages() {
+    _pageRegistry.clear();
+}
+export function definePage(schema) {
+    const p = { ...schema };
+    _pageRegistry.add(p);
+    return p;
+}
+export function defineTabPage(schema) {
+    const p = { ...schema };
+    _pageRegistry.add(p);
+    return p;
+}
+export function page(app, name, description, label) {
+    return { name, label, app, description };
 }

package/dist/pattern.js

@@ -1,13 +1,9 @@
-"use strict";
 // Pattern core: minimal definitions to bootstrap the Flow × Pattern DSL.
 // A Pattern is a reusable solution ("how to guarantee success") declared as
 // pure data. Concrete usage fills its params and action injection points.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.definePattern = definePattern;
-exports.ref = ref;
-function definePattern(def) {
+export function definePattern(def) {
     return def;
 }
-function ref(name, args) {
+export function ref(name, args) {
     return { ref: name, args };
 }

package/dist/patterns/retry.d.ts

@@ -1,4 +1,4 @@
-import { PatternDef } from '../pattern';
+import { PatternDef } from '../pattern.js';
 export declare const retryPattern: PatternDef;
 export interface RetryAction {
     /** Function to call, e.g. 'queryOrderList' */

package/dist/patterns/retry.js

@@ -1,19 +1,15 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.retryPattern = void 0;
-exports.renderRetry = renderRetry;
 // Retry pattern: blind mechanical retry for read-only operations.
 // Valid because a read-only action is idempotent by nature: clicking a query
 // button any number of times never changes the result, so retrying the same
 // call is always safe. No idempotency key, no query-and-resume, no compensate.
-exports.retryPattern = {
+export const retryPattern = {
     name: 'retry',
     params: {
         max: { type: 'int', min: 1, default: 3 },
         backoffMs: { type: 'int', min: 0, default: 0 },
     },
 };
-function renderRetry(args) {
+export function renderRetry(args) {
     if (args.max !== undefined && args.max < 1)
         throw new Error('retry: max must be >= 1');
     if (!args.action.call)

package/dist/popup.d.ts

@@ -0,0 +1,18 @@
+import type { ActionSchema } from './action.js';
+import type { RefSchema } from './ref.js';
+/** Display a toast notification. React: toast/message UI. Mini-program: wx.showToast. */
+export interface ToastAction extends ActionSchema {
+    type: 'toast';
+    message: string | RefSchema;
+    icon?: 'success' | 'error' | 'loading' | 'none';
+}
+/** Display an alert dialog. React: modal. Mini-program: wx.showModal. */
+export interface AlertAction extends ActionSchema {
+    type: 'alert';
+    title: string | RefSchema;
+    content: string | RefSchema;
+}
+export declare const popup: {
+    toast(message: string | RefSchema, icon?: 'success' | 'error' | 'loading' | 'none'): ToastAction;
+    alert(title: string | RefSchema, content: string | RefSchema): AlertAction;
+};

package/dist/popup.js

@@ -0,0 +1,8 @@
+export const popup = {
+    toast(message, icon) {
+        return { name: 'toast', type: 'toast', message, icon };
+    },
+    alert(title, content) {
+        return { name: 'alert', type: 'alert', title, content };
+    },
+};

package/dist/project.d.ts

@@ -1,41 +1,53 @@
-import { SchemaBase } from './dsl';
+import { SchemaBase } from './dsl.js';
+import type { TableSchema } from './db.js';
 /** Frontend form factor. Closed enum, extend when new form factors appear. */
 export type FrontType = 'admin' | 'wxmini';
 /** A frontend application (e.g. admin console, wechat mini program). */
-export interface FrontApp extends SchemaBase {
+export interface FrontAppSchema extends SchemaBase {
     type: FrontType;
     /** Source directory relative to project root, e.g. 'web-admin/'. */
     dir: string;
+    /**
+     * Tenant table for this app. When set, all tables with a foreign key
+     * pointing to this table get automatic tenant scoping: the tenant PK
+     * value is injected from `user.id` into all curd operations.
+     */
+    tenant?: TableSchema;
 }
-/** A backend API service. apps references shared FrontApp instances. */
-export interface ProjectApi extends SchemaBase {
+/** A backend API service. apps references shared FrontAppSchema instances. */
+export interface ProjectApiSchema extends SchemaBase {
     /** Source directory relative to project root, e.g. 'api/'. */
     dir: string;
     /** Frontends this API serves. Direct instance references (see defineProject). */
-    apps: FrontApp[];
+    apps: FrontAppSchema[];
     /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
     contextPath?: string;
+    /** API service base URL for node clients, e.g. 'http://127.0.0.1:3000'. */
+    baseUrl?: string;
 }
 /** A third-party system (e.g. wechat pay, unionpay). Owns its own
  *  implementation dir and contract (controller_types), just like an API,
  *  but is not part of this repo's served surface. */
-export interface ThirdApi extends SchemaBase {
+export interface ThirdApiSchema extends SchemaBase {
     /** Source directory relative to project root, e.g. 'wechat/'. */
     dir: string;
 }
 export interface ProjectSchema extends SchemaBase {
-    apps: FrontApp[];
-    apis: ProjectApi[];
-    thirdApis: ThirdApi[];
+    apps: FrontAppSchema[];
+    apis: ProjectApiSchema[];
+    thirdApis: ThirdApiSchema[];
 }
 /**
- * Defines the project topology. FrontApp instances are shared value objects:
+ * Defines the project topology. FrontAppSchema instances are shared value objects:
  * api.apps references the same instances from project.apps, so an app served
  * by multiple APIs is defined once and referenced many times.
+ *
+ * Runtime-validates app type whitelist, unique names and api.apps reference
+ * integrity (same style as defineTable/defineCurd).
  */
 export declare function defineProject(name: string, schema: {
     description?: string;
-    apps: FrontApp[];
-    apis: ProjectApi[];
-    thirdApis?: ThirdApi[];
+    apps: FrontAppSchema[];
+    apis: ProjectApiSchema[];
+    thirdApis?: ThirdApiSchema[];
 }): ProjectSchema;

package/dist/project.js

@@ -1,11 +1,46 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineProject = defineProject;
 /**
- * Defines the project topology. FrontApp instances are shared value objects:
+ * Defines the project topology. FrontAppSchema instances are shared value objects:
  * api.apps references the same instances from project.apps, so an app served
  * by multiple APIs is defined once and referenced many times.
+ *
+ * Runtime-validates app type whitelist, unique names and api.apps reference
+ * integrity (same style as defineTable/defineCurd).
  */
-function defineProject(name, schema) {
-    return { name, ...schema, thirdApis: schema.thirdApis ?? [] };
+export function defineProject(name, schema) {
+    const project = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
+    const appNames = new Set();
+    for (const app of project.apps) {
+        if (!app.name)
+            throw new Error(`project ${name}: app name is required`);
+        if (appNames.has(app.name))
+            throw new Error(`project ${name}: duplicate app name '${app.name}'`);
+        appNames.add(app.name);
+        if (app.type !== 'admin' && app.type !== 'wxmini') {
+            throw new Error(`project ${name}: app '${app.name}' must be type 'admin' or 'wxmini' (got '${app.type}')`);
+        }
+        if (!app.dir)
+            throw new Error(`project ${name}: app '${app.name}' dir is required`);
+    }
+    const apiNames = new Set();
+    for (const api of project.apis) {
+        if (!api.name)
+            throw new Error(`project ${name}: api name is required`);
+        if (apiNames.has(api.name))
+            throw new Error(`project ${name}: duplicate api name '${api.name}'`);
+        apiNames.add(api.name);
+        if (!api.dir)
+            throw new Error(`project ${name}: api '${api.name}' dir is required`);
+        for (const ref of api.apps) {
+            if (!project.apps.includes(ref)) {
+                throw new Error(`project ${name}: api '${api.name}' references app '${ref.name}' that is not a shared instance in project.apps (define once and reference it)`);
+            }
+        }
+    }
+    for (const third of project.thirdApis) {
+        if (!third.name)
+            throw new Error(`project ${name}: thirdApi name is required`);
+        if (!third.dir)
+            throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
+    }
+    return project;
 }