merge dev to main (v3.5.0)

.github/workflows/build-test.yml

@@ -8,6 +8,7 @@ on:
 
 env:
     TELEMETRY_TRACKING_TOKEN: ${{ secrets.TELEMETRY_TRACKING_TOKEN }}
+    VSCODE_TELEMETRY_TRACKING_TOKEN: ${{ secrets.VSCODE_TELEMETRY_TRACKING_TOKEN }}
     DO_NOT_TRACK: '1'
 
 permissions:

README.md

@@ -34,6 +34,7 @@ ZenStack is a TypeScript database toolkit for developing full-stack or backend N
 - 🧩 Designed for extensibility and flexibility
 - ⚙️ Automatic CRUD web APIs with adapters for popular frameworks
 - 🏖️ Automatic [TanStack Query](https://github.com/TanStack/query) hooks for easy CRUD from the frontend
+- 💎 [Zod](https://zod.dev) schema generation
 
 # What's New in V3
 
@@ -111,3 +112,23 @@ Thank you for your generous support!
 # Community
 
 Join our [discord server](https://discord.gg/Ykhr738dUe) for chat and updates!
+
+# Contributors
+
+Thanks to all the contributors who have helped make ZenStack better!
+
+### Source
+
+<a href="https://github.com/zenstackhq/zenstack/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=zenstackhq/zenstack" />
+</a>
+
+### Docs
+
+<a href="https://github.com/zenstackhq/zenstack-docs/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=zenstackhq/zenstack-docs" />
+</a>
+
+## License
+
+[MIT](LICENSE)

package.json

@@ -1,6 +1,6 @@
 {
     "name": "zenstack-v3",
-    "version": "3.4.6",
+    "version": "3.5.0",
     "description": "ZenStack",
     "packageManager": "pnpm@10.23.0",
     "type": "module",

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

@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/better-auth",
-    "version": "3.4.6",
+    "version": "3.5.0",
     "description": "ZenStack Better Auth Adapter. This adapter is modified from better-auth's Prisma adapter.",
     "type": "module",
     "scripts": {

packages/cli/README.md

@@ -0,0 +1,24 @@
+# @zenstackhq/cli
+
+The command-line interface for ZenStack. Provides commands for initializing projects, generating TypeScript code from ZModel schemas, managing database migrations, and etc.
+
+## Key Commands
+
+- `zenstack init` — Initialize ZenStack in an existing project
+- `zenstack generate` — Compile ZModel schema to TypeScript
+- `zenstack db push` — Sync schema to the database
+- `zenstack db pull` — Pull database schema changes into ZModel
+- `zenstack migrate dev` — Create and apply database migrations
+- `zenstack migrate deploy` — Deploy migrations to production
+- `zenstack format` — Format ZModel schema files
+- `zenstack proxy|studio` — Start a database proxy server for using studio
+
+## Installation
+
+```bash
+npm install -D @zenstackhq/cli
+```
+
+## Learn More
+
+- [ZenStack Documentation](https://zenstack.dev/docs)

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.4.6",
+    "version": "3.5.0",
     "type": "module",
     "author": {
         "name": "ZenStack Team"

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

@@ -291,6 +291,14 @@ export async function loadPluginModule(provider: string, basePath: string) {
         }
     }
 
+    // try jiti import for bare package specifiers (handles workspace packages)
+    try {
+        const result = (await jiti.import(moduleSpec, { default: true })) as CliPlugin;
+        return result;
+    } catch {
+        // fall through to last resort
+    }
+
     // last resort, try to import as esm directly
     try {
         const mod = await import(moduleSpec);

packages/cli/src/actions/check.ts

@@ -29,7 +29,9 @@ async function checkPluginResolution(schemaFile: string, model: Model) {
     for (const plugin of plugins) {
         const provider = getPluginProvider(plugin);
         if (!provider.startsWith('@core/')) {
-            await loadPluginModule(provider, path.dirname(schemaFile));
+            const pluginSourcePath =
+                plugin.$cstNode?.parent?.element.$document?.uri?.fsPath ?? schemaFile;
+            await loadPluginModule(provider, path.dirname(pluginSourcePath));
         }
     }
 }

packages/cli/src/actions/generate.ts

@@ -186,7 +186,11 @@ async function runPlugins(schemaFile: string, model: Model, outputPath: string,
                 throw new CliError(`Unknown core plugin: ${provider}`);
             }
         } else {
-            cliPlugin = await loadPluginModule(provider, path.dirname(schemaFile));
+            // resolve relative plugin paths against the schema file where the plugin is declared,
+            // not the entry schema file
+            const pluginSourcePath =
+                plugin.$cstNode?.parent?.element.$document?.uri?.fsPath ?? schemaFile;
+            cliPlugin = await loadPluginModule(provider, path.dirname(pluginSourcePath));
         }
 
         if (cliPlugin) {
@@ -252,7 +256,7 @@ async function runPlugins(schemaFile: string, model: Model, outputPath: string,
             spinner?.succeed();
         } catch (err) {
             spinner?.fail();
-            console.error(err);
+            throw err;
         }
     }
 }

packages/cli/src/index.ts

@@ -1,7 +1,7 @@
-import 'dotenv/config';
 import { ZModelLanguageMetaData } from '@zenstackhq/language';
 import colors from 'colors';
 import { Command, CommanderError, Option } from 'commander';
+import 'dotenv/config';
 import * as actions from './actions';
 import { CliError } from './cli-error';
 import { telemetry } from './telemetry';

packages/cli/test/generate.test.ts

@@ -1,7 +1,8 @@
+import { formatDocument } from '@zenstackhq/language';
 import fs from 'node:fs';
 import path from 'node:path';
 import { describe, expect, it } from 'vitest';
-import { createProject, runCli } from './utils';
+import { createProject, getDefaultPrelude, runCli } from './utils';
 
 const model = `
 model User {
@@ -272,6 +273,84 @@ model User {
         expect(fs.existsSync(path.join(workDir, 'zenstack/schema.ts'))).toBe(true);
     });
 
+    it('should load plugin from a bare package specifier via jiti', async () => {
+        const modelWithBarePlugin = `
+plugin foo {
+    provider = 'my-test-plugin'
+}
+
+model User {
+    id String @id @default(cuid())
+}
+`;
+        const { workDir } = await createProject(modelWithBarePlugin);
+        // Create a fake node_modules package with a TS entry point
+        // This can only be resolved by jiti, not by native import() or fs.existsSync checks
+        const pkgDir = path.join(workDir, 'node_modules/my-test-plugin');
+        fs.mkdirSync(pkgDir, { recursive: true });
+        fs.writeFileSync(
+            path.join(pkgDir, 'package.json'),
+            JSON.stringify({ name: 'my-test-plugin', main: './index.ts' }),
+        );
+        fs.writeFileSync(
+            path.join(pkgDir, 'index.ts'),
+            `
+const plugin = {
+    name: 'test-bare-plugin',
+    statusText: 'Testing bare plugin',
+    async generate() {},
+};
+export default plugin;
+`,
+        );
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.ts'))).toBe(true);
+    });
+
+    it('should resolve plugin paths relative to the schema file where the plugin is declared', async () => {
+        // Entry schema imports a sub-schema that declares a plugin with a relative path.
+        // The plugin path should resolve relative to the sub-schema, not the entry schema.
+        const { workDir } = await createProject(
+            `import './core/core'
+
+${getDefaultPrelude()}
+
+model User {
+    id String @id @default(cuid())
+}
+`,
+            { customPrelude: true },
+        );
+
+        // Create core/ subdirectory with its own schema and plugin
+        const coreDir = path.join(workDir, 'zenstack/core');
+        fs.mkdirSync(coreDir, { recursive: true });
+
+        const coreSchema = await formatDocument(`
+plugin foo {
+    provider = './my-core-plugin.ts'
+}
+`);
+        fs.writeFileSync(path.join(coreDir, 'core.zmodel'), coreSchema);
+
+        // Plugin lives next to the core schema, NOT next to the entry schema
+        fs.writeFileSync(
+            path.join(coreDir, 'my-core-plugin.ts'),
+            `
+const plugin = {
+    name: 'core-plugin',
+    statusText: 'Testing core plugin',
+    async generate() {},
+};
+export default plugin;
+`,
+        );
+
+        // This would fail if the plugin path was resolved relative to the entry schema
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.ts'))).toBe(true);
+    });
+
     it('should prefer CLI options over @core/typescript plugin settings for generateModels and generateInput', async () => {
         const modelWithPlugin = `
 plugin typescript {

packages/clients/client-helpers/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/client-helpers",
-    "version": "3.4.6",
+    "version": "3.5.0",
     "description": "Helpers for implementing clients that consume ZenStack's CRUD service",
     "type": "module",
     "scripts": {

packages/clients/client-helpers/src/types.ts

@@ -1,8 +1,28 @@
+import type { ClientContract, QueryOptions } from '@zenstackhq/orm';
+import type { SchemaDef } from '@zenstackhq/schema';
+
 /**
  * A type that represents either a value of type T or a Promise that resolves to type T.
  */
 export type MaybePromise<T> = T | Promise<T> | PromiseLike<T>;
 
+/**
+ * Infers the schema definition from a client contract type, or passes through a raw SchemaDef.
+ */
+export type InferSchema<T> = T extends { $schema: infer S extends SchemaDef } ? S : T extends SchemaDef ? T : never;
+
+/**
+ * Extracts the ExtResult type from a client contract, or defaults to `{}`.
+ */
+export type InferExtResult<T> = T extends ClientContract<any, any, any, any, infer E> ? E : {};
+
+/**
+ * Infers query options from a client contract type, or defaults to `QueryOptions<Schema>`.
+ */
+export type InferOptions<T, Schema extends SchemaDef> = T extends { $options: infer O extends QueryOptions<Schema> }
+    ? O
+    : QueryOptions<Schema>;
+
 /**
  * List of ORM write actions.
  */

packages/clients/tanstack-query/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/tanstack-query",
-    "version": "3.4.6",
+    "version": "3.5.0",
     "description": "TanStack Query Client for consuming ZenStack v3's CRUD service",
     "type": "module",
     "scripts": {

packages/clients/tanstack-query/src/common/types.ts

@@ -3,11 +3,12 @@ import type { FetchFn } from '@zenstackhq/client-helpers/fetch';
 import type {
     GetProcedureNames,
     GetSlicedOperations,
-    OperationsIneligibleForDelegateModels,
+    ModelAllowsCreate,
+    OperationsRequiringCreate,
     ProcedureFunc,
     QueryOptions,
 } from '@zenstackhq/orm';
-import type { GetModels, IsDelegateModel, SchemaDef } from '@zenstackhq/schema';
+import type { GetModels, SchemaDef } from '@zenstackhq/schema';
 
 /**
  * Context type for configuring the hooks.
@@ -59,8 +60,8 @@ export type ExtraMutationOptions = {
     optimisticDataProvider?: OptimisticDataProvider;
 } & QueryContext;
 
-type HooksOperationsIneligibleForDelegateModels = OperationsIneligibleForDelegateModels extends any
-    ? `use${Capitalize<OperationsIneligibleForDelegateModels>}`
+type HooksOperationsRequiringCreate = OperationsRequiringCreate extends any
+    ? `use${Capitalize<OperationsRequiringCreate>}`
     : never;
 
 type Modifiers = '' | 'Suspense' | 'Infinite' | 'SuspenseInfinite';
@@ -76,12 +77,12 @@ export type TrimSlicedOperations<
 > = {
     // trim operations based on slicing options
     [Key in keyof T as Key extends `use${Modifiers}${Capitalize<GetSlicedOperations<Schema, Model, Options>>}`
-        ? IsDelegateModel<Schema, Model> extends true
-            ? // trim operations ineligible for delegate models
-              Key extends HooksOperationsIneligibleForDelegateModels
-                ? never
-                : Key
-            : Key
+        ? ModelAllowsCreate<Schema, Model> extends true
+            ? Key
+            : // trim create operations for models that don't allow create
+              Key extends HooksOperationsRequiringCreate
+              ? never
+              : Key
         : never]: T[Key];
 };