merge dev to main (v3.4.0) (#2414)

Author: ymc9

CLAUDE.md

@@ -20,6 +20,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ### Testing
 
 - E2E tests are in `tests/e2e/` directory
+- Regression tests for GitHub issues go in `tests/regression/test/` as `issue-{number}.test.ts`
 
 ### ZenStack CLI Commands
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "zenstack-v3",
-    "version": "3.3.3",
+    "version": "3.4.0",
     "description": "ZenStack",
     "packageManager": "pnpm@10.23.0",
     "type": "module",
@@ -50,6 +50,11 @@
             "better-sqlite3",
             "esbuild",
             "vue-demi"
-        ]
+        ],
+        "overrides": {
+            "cookie@<0.7.0": ">=0.7.0",
+            "lodash-es@>=4.0.0 <=4.17.22": ">=4.17.23",
+            "lodash@>=4.0.0 <=4.17.22": ">=4.17.23"
+        }
     }
 }

packages/auth-adapters/better-auth/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/better-auth",
-    "version": "3.3.3",
+    "version": "3.4.0",
     "description": "ZenStack Better Auth Adapter. This adapter is modified from better-auth's Prisma adapter.",
     "type": "module",
     "scripts": {
@@ -46,9 +46,9 @@
         "better-auth": "^1.3.0"
     },
     "devDependencies": {
-        "@better-auth/core": "1.4.17",
-        "better-auth": "1.4.17",
-        "@better-auth/cli": "1.4.17",
+        "@better-auth/core": "1.4.19",
+        "better-auth": "1.4.19",
+        "@better-auth/cli": "1.4.19",
         "@types/tmp": "catalog:",
         "@zenstackhq/cli": "workspace:*",
         "@zenstackhq/eslint-config": "workspace:*",

packages/auth-adapters/better-auth/src/adapter.ts

@@ -171,7 +171,7 @@ export const zenstackAdapter = <Schema extends SchemaDef>(db: ClientContract<Sch
                     const whereClause = convertWhereClause(model, where);
                     return await modelDb.update({
                         where: whereClause,
-                        data: update as UpdateInput<SchemaDef, GetModels<SchemaDef>>,
+                        data: update as UpdateInput<SchemaDef, GetModels<SchemaDef>, any>,
                     });
                 },
 

packages/cli/package.json

@@ -3,7 +3,7 @@
     "publisher": "zenstack",
     "displayName": "ZenStack CLI",
     "description": "FullStack database toolkit with built-in access control and automatic API generation.",
-    "version": "3.3.3",
+    "version": "3.4.0",
     "type": "module",
     "author": {
         "name": "ZenStack Team"
@@ -37,12 +37,11 @@
     },
     "dependencies": {
         "@zenstackhq/common-helpers": "workspace:*",
-        "@zenstackhq/schema": "workspace:*",
         "@zenstackhq/language": "workspace:*",
         "@zenstackhq/orm": "workspace:*",
+        "@zenstackhq/schema": "workspace:*",
         "@zenstackhq/sdk": "workspace:*",
         "@zenstackhq/server": "workspace:*",
-        "better-sqlite3": "catalog:",
         "chokidar": "^5.0.0",
         "colors": "1.4.0",
         "commander": "^8.3.0",
@@ -53,13 +52,13 @@
         "jiti": "^2.6.1",
         "langium": "catalog:",
         "mixpanel": "^0.18.1",
-        "mysql2": "catalog:",
         "ora": "^5.4.1",
         "package-manager-detector": "^1.3.0",
-        "pg": "catalog:",
         "prisma": "catalog:",
         "semver": "^7.7.2",
-        "ts-pattern": "catalog:"
+        "terminal-link": "^5.0.0",
+        "ts-pattern": "catalog:",
+        "zod": "catalog:"
     },
     "devDependencies": {
         "@types/better-sqlite3": "catalog:",
@@ -74,7 +73,23 @@
         "@zenstackhq/vitest-config": "workspace:*",
         "tmp": "catalog:"
     },
+    "peerDependencies": {
+        "better-sqlite3": "catalog:",
+        "mysql2": "catalog:",
+        "pg": "catalog:"
+    },
+    "peerDependenciesMeta": {
+        "pg": {
+            "optional": true
+        },
+        "better-sqlite3": {
+            "optional": true
+        },
+        "mysql2": {
+            "optional": true
+        }
+    },
     "engines": {
         "node": ">=20"
     }
-}
+}

packages/cli/src/actions/action-utils.ts

@@ -6,6 +6,8 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { CliError } from '../cli-error';
+import terminalLink from 'terminal-link';
+import { z } from 'zod';
 
 export function getSchemaFile(file?: string) {
     if (file) {
@@ -216,3 +218,69 @@ export async function getZenStackPackages(
 
     return result.filter((p) => !!p);
 }
+
+const FETCH_CLI_MAX_TIME = 1000;
+const CLI_CONFIG_ENDPOINT = 'https://zenstack.dev/config/cli-v3.json';
+
+const usageTipsSchema = z.object({
+    notifications: z.array(z.object({ title: z.string(), url: z.url().optional(), active: z.boolean() })),
+});
+
+/**
+ * Starts the usage tips fetch in the background. Returns a callback that, when invoked check if the fetch
+ * is complete. If not complete, it will wait until the max time is reached. After that, if fetch is still
+ * not complete, just return.
+ */
+export function startUsageTipsFetch() {
+    let fetchedData: z.infer<typeof usageTipsSchema> | undefined = undefined;
+    let fetchComplete = false;
+
+    const start = Date.now();
+    const controller = new AbortController();
+
+    fetch(CLI_CONFIG_ENDPOINT, {
+        headers: { accept: 'application/json' },
+        signal: controller.signal,
+    })
+        .then(async (res) => {
+            if (!res.ok) return;
+            const data = await res.json();
+            const parseResult = usageTipsSchema.safeParse(data);
+            if (parseResult.success) {
+                fetchedData = parseResult.data;
+            }
+        })
+        .catch(() => {
+            // noop
+        })
+        .finally(() => {
+            fetchComplete = true;
+        });
+
+    return async () => {
+        const elapsed = Date.now() - start;
+
+        if (!fetchComplete && elapsed < FETCH_CLI_MAX_TIME) {
+            // wait for the timeout
+            await new Promise((resolve) => setTimeout(resolve, FETCH_CLI_MAX_TIME - elapsed));
+        }
+
+        if (!fetchComplete) {
+            controller.abort();
+            return;
+        }
+
+        if (!fetchedData) return;
+
+        const activeItems = fetchedData.notifications.filter((item) => item.active);
+        // show a random active item
+        if (activeItems.length > 0) {
+            const item = activeItems[Math.floor(Math.random() * activeItems.length)]!;
+            if (item.url) {
+                console.log(terminalLink(item.title, item.url));
+            } else {
+                console.log(item.title);
+            }
+        }
+    };
+}

packages/cli/src/actions/generate.ts

@@ -1,27 +1,36 @@
 import { invariant, singleDebounce } from '@zenstackhq/common-helpers';
 import { ZModelLanguageMetaData } from '@zenstackhq/language';
-import { type AbstractDeclaration, isPlugin, LiteralExpr, Plugin, type Model } from '@zenstackhq/language/ast';
+import { isPlugin, LiteralExpr, Plugin, type AbstractDeclaration, type Model } from '@zenstackhq/language/ast';
 import { getLiteral, getLiteralArray } from '@zenstackhq/language/utils';
 import { type CliPlugin } from '@zenstackhq/sdk';
+import { watch } from 'chokidar';
 import colors from 'colors';
 import { createJiti } from 'jiti';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { watch } from 'chokidar';
 import ora, { type Ora } from 'ora';
+import semver from 'semver';
 import { CliError } from '../cli-error';
 import * as corePlugins from '../plugins';
-import { getOutputPath, getSchemaFile, getZenStackPackages, loadSchemaDocument } from './action-utils';
-import semver from 'semver';
+import {
+    getOutputPath,
+    getSchemaFile,
+    getZenStackPackages,
+    loadSchemaDocument,
+    startUsageTipsFetch,
+} from './action-utils';
 
 type Options = {
     schema?: string;
     output?: string;
     silent: boolean;
     watch: boolean;
-    lite: boolean;
-    liteOnly: boolean;
+    lite?: boolean;
+    liteOnly?: boolean;
+    generateModels?: boolean;
+    generateInput?: boolean;
+    tips?: boolean;
 };
 
 /**
@@ -33,8 +42,13 @@ export async function run(options: Options) {
     } catch (err) {
         console.warn(colors.yellow(`Failed to check for mismatched ZenStack packages: ${err}`));
     }
+
+    const maybeShowUsageTips = options.tips && !options.silent && !options.watch ? startUsageTipsFetch() : undefined;
+
     const model = await pureGenerate(options, false);
 
+    await maybeShowUsageTips?.();
+
     if (options.watch) {
         const logsEnabled = !options.silent;
 
@@ -181,12 +195,18 @@ async function runPlugins(schemaFile: string, model: Model, outputPath: string,
 
             // merge CLI options
             if (provider === '@core/typescript') {
-                if (pluginOptions['lite'] === undefined) {
+                if (options.lite !== undefined) {
                     pluginOptions['lite'] = options.lite;
                 }
-                if (pluginOptions['liteOnly'] === undefined) {
+                if (options.liteOnly !== undefined) {
                     pluginOptions['liteOnly'] = options.liteOnly;
                 }
+                if (options.generateModels !== undefined) {
+                    pluginOptions['generateModels'] = options.generateModels;
+                }
+                if (options.generateInput !== undefined) {
+                    pluginOptions['generateInput'] = options.generateInput;
+                }
             }
 
             processedPlugins.push({ cliPlugin, pluginOptions });
@@ -196,7 +216,12 @@ async function runPlugins(schemaFile: string, model: Model, outputPath: string,
     const defaultPlugins = [
         {
             plugin: corePlugins['typescript'],
-            options: { lite: options.lite, liteOnly: options.liteOnly },
+            options: {
+                lite: options.lite,
+                liteOnly: options.liteOnly,
+                generateModels: options.generateModels,
+                generateInput: options.generateInput,
+            },
         },
     ];
     defaultPlugins.forEach(({ plugin, options }) => {

packages/cli/src/actions/proxy.ts

@@ -13,14 +13,14 @@ import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
 import { SqliteDialect } from '@zenstackhq/orm/dialects/sqlite';
 import { RPCApiHandler } from '@zenstackhq/server/api';
 import { ZenStackMiddleware } from '@zenstackhq/server/express';
-import SQLite from 'better-sqlite3';
+import type BetterSqlite3 from 'better-sqlite3';
 import colors from 'colors';
 import cors from 'cors';
 import express from 'express';
 import { createJiti } from 'jiti';
-import { createPool as createMysqlPool } from 'mysql2';
+import type { createPool as MysqlCreatePool } from 'mysql2';
 import path from 'node:path';
-import { Pool as PgPool } from 'pg';
+import type { Pool as PgPoolType } from 'pg';
 import { CliError } from '../cli-error';
 import { getVersion } from '../utils/version-utils';
 import { getOutputPath, getSchemaFile, loadSchemaDocument } from './action-utils';
@@ -67,7 +67,7 @@ export async function run(options: Options) {
 
     const provider = getStringLiteral(dataSource?.fields.find((f) => f.name === 'provider')?.value)!;
 
-    const dialect = createDialect(provider, databaseUrl!, outputPath);
+    const dialect = await createDialect(provider, databaseUrl!, outputPath);
 
     const jiti = createJiti(import.meta.url);
 
@@ -137,9 +137,17 @@ function redactDatabaseUrl(url: string): string {
     }
 }
 
-function createDialect(provider: string, databaseUrl: string, outputPath: string) {
+async function createDialect(provider: string, databaseUrl: string, outputPath: string) {
     switch (provider) {
         case 'sqlite': {
+            let SQLite: typeof BetterSqlite3;
+            try {
+                SQLite = (await import('better-sqlite3')).default;
+            } catch {
+                throw new CliError(
+                    `Package "better-sqlite3" is required for SQLite support. Please install it with: npm install better-sqlite3`,
+                );
+            }
             let resolvedUrl = databaseUrl.trim();
             if (resolvedUrl.startsWith('file:')) {
                 const filePath = resolvedUrl.substring('file:'.length);
@@ -152,20 +160,36 @@ function createDialect(provider: string, databaseUrl: string, outputPath: string
                 database: new SQLite(resolvedUrl),
             });
         }
-        case 'postgresql':
+        case 'postgresql': {
+            let PgPool: typeof PgPoolType;
+            try {
+                PgPool = (await import('pg')).Pool;
+            } catch {
+                throw new CliError(
+                    `Package "pg" is required for PostgreSQL support. Please install it with: npm install pg`,
+                );
+            }
             console.log(colors.gray(`Connecting to PostgreSQL database at: ${redactDatabaseUrl(databaseUrl)}`));
             return new PostgresDialect({
                 pool: new PgPool({
                     connectionString: databaseUrl,
                 }),
             });
-
-        case 'mysql':
+        }
+        case 'mysql': {
+            let createMysqlPool: typeof MysqlCreatePool;
+            try {
+                createMysqlPool = (await import('mysql2')).createPool;
+            } catch {
+                throw new CliError(
+                    `Package "mysql2" is required for MySQL support. Please install it with: npm install mysql2`,
+                );
+            }
             console.log(colors.gray(`Connecting to MySQL database at: ${redactDatabaseUrl(databaseUrl)}`));
             return new MysqlDialect({
                 pool: createMysqlPool(databaseUrl),
             });
-
+        }
         default:
             throw new CliError(`Unsupported database provider: ${provider}`);
     }