doc: plugin development guide

.gitmodules

@@ -28,3 +28,6 @@
 [submodule "code-repos/zenstackhq/v3-doc-tanstack-query"]
 	path = code-repos/zenstackhq/v3-doc-tanstack-query
 	url = https://github.com/zenstackhq/v3-doc-tanstack-query
+[submodule "code-repos/zenstackhq/v3-doc-plugin"]
+	path = code-repos/zenstackhq/v3-doc-plugin
+	url = https://github.com/zenstackhq/v3-doc-plugin

package.json

@@ -23,7 +23,6 @@
         "@docusaurus/theme-mermaid": "3.4.0",
         "@giscus/react": "^2.4.0",
         "@mdx-js/react": "^3.0.1",
-        "@stackblitz/sdk": "^1.11.0",
         "autoprefixer": "^10.4.13",
         "clsx": "^1.2.1",
         "is-mobile": "^5.0.0",

src/components/StackBlitzGithub.tsx

@@ -1,4 +1,3 @@
-import sdk from '@stackblitz/sdk';
 import React from 'react';
 import GithubCodeBlock from './GithubCodeBlock';
 
@@ -17,19 +16,23 @@ const StackBlitzGithub: React.FC<StackBlitzGithubProps> = ({
 }) => {
     const openFiles = Array.isArray(openFile) ? openFile : openFile ? openFile.split(',') : [];
 
-    const options = {
-        openFile: openFiles ? openFiles.join(',') : undefined,
-        view: 'editor',
-        startScript,
-    } as const;
+    // construct StackBlitz URL
+    const url = new URL(`https://stackblitz.com/~/github/${repoPath}`);
+    url.searchParams.append('view', 'editor');
+    if (openFiles && openFiles.length > 0) {
+        openFiles.forEach((f) => url.searchParams.append('file', f));
+    }
+    if (startScript) {
+        url.searchParams.append('startScript', startScript);
+    }
 
     if (!plainCodeFiles) {
         plainCodeFiles = [...openFiles];
     }
 
     return (
         <>
-            <a href="#" onClick={() => sdk.openGithubProject(repoPath, options)}>
+            <a href={url.toString()} target="_blank">
                 <img alt="Open in StackBlitz" src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" />
             </a>
             {plainCodeFiles.map((file) => (

versioned_docs/version-3.x/modeling/plugin.md

@@ -11,7 +11,7 @@ import ZModelVsPSL from '../_components/ZModelVsPSL';
 ZenStack's "plugin" concept replaces PSL's "generator".
 </ZModelVsPSL>
 
-Plugin is a powerful mechanism that allows you to extend ZenStack at the schema, CLI, and runtime levels. This section only focuses on how to add plugins to your ZModel. Please refer to the [Plugin Development](../reference/plugin-dev.md) section for more details on how to develop plugins.
+Plugin is a powerful mechanism that allows you to extend ZenStack at the schema, CLI, and runtime levels. This section only focuses on how to add plugins to your ZModel. Please refer to the [Plugin Development](../recipe/plugin-dev.md) section for more details on how to develop plugins.
 
 ## Adding plugins to ZModel
 
@@ -48,4 +48,6 @@ A plugin can have the following effects to ZModel:
 - It can contribute custom attributes that you can use to annotate models and fields.
 - It can contribute code generation logic that's executed when you run the `zenstack generate` command.
 
-Plugins can also contribute to the ORM runtime behavior, and we'll leave it to the [ORM](../orm/plugins/) part to explain it in detail.
+:::info
+Plugins can also extend ZenStack's CLI and ORM runtime behavior. Please refer to the [Plugin Development](../recipe/plugin-dev.md) documentation for a comprehensive guide.
+:::

versioned_docs/version-3.x/orm/cli.md

@@ -16,3 +16,7 @@ You can try running the `npx zen generate` command in the following playground a
 <StackBlitzGithub repoPath="zenstackhq/v3-doc-quick-start" openFile="zenstack/schema.zmodel" />
 
 The `generate` command generates several TypeScript files from the ZModel schema that support both development-time typing and runtime access to the schema. For more details of the generated code, please refer to the [@core/typescript plugin](../reference/plugins/typescript.md) documentation.
+
+:::info
+The CLI's code generation is extensible via plugins. Please refer to the [Plugin Development](../recipe/plugin-dev.md) documentation for a comprehensive guide.
+:::

versioned_docs/version-3.x/orm/plugins/index.md

@@ -40,3 +40,7 @@ const db = new ZenStackClient({ ... });
 const withPlugin = $db.use({ ... });
 const noPlugin = withPlugin.$unuseAll();
 ```
+
+:::info
+Plugins can also extend the ZModel language and ZenStack's CLI. Please refer to the [Plugin Development](../../recipe/plugin-dev.md) documentation for a comprehensive guide.
+:::

versioned_docs/version-3.x/recipe/plugin-dev.md

@@ -0,0 +1,107 @@
+---
+sidebar_position: 5
+description: Plugin development guide
+---
+
+import StackBlitzGithub from '@site/src/components/StackBlitzGithub';
+import PackageInstall from '../_components/PackageInstall';
+
+# Plugin Development
+
+This guide provides a comprehensive introduction to developing ZenStack plugins, demonstrating how to extend ZenStack’s functionality at the schema, CLI, and runtime levels.
+
+## Extending the schema language
+
+Plugins can contribute new ZModel attributes and functions, and use them to extend the data modeling semantics. To do that, create a folder in your source tree with a `plugin.zmodel` file in it, and define your custom attributes and/or functions in it.
+
+:::tip
+You can also package a plugin as an npm package. Make sure to export the "plugin.zmodel" file in the package's `package.json` file.
+:::
+
+The following example shows a sample plugin that allows you to mark fields as "password" and specify hashing algorithms to use.
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-plugin" openFile="zenstack/password-plugin/plugin.zmodel" />
+
+:::info
+Model-level attributes must be prefixed with `@@`, and field-level ones with `@`.
+:::
+
+You need to enable the plugin in your ZModel to use the attributes and functions defined in it:
+
+```zmodel title="schema.zmodel"
+plugin password {
+    provider = './password-plugin'
+}
+
+model User {
+    id Int @id @default(autoincrement())
+    password String @password(hasher: bcryptHasher(10))
+}
+```
+
+## Generating custom artifacts
+
+The `zen` CLI is extensible via plugins and allows you to generate custom artifacts from the ZModel schema. To continue the previous example, let's create a very simple CLI plugin that generates a markdown document listing all model fields marked as passwords.
+
+To implement a plugin, first install the "@zenstackhq/sdk" package that contains type definitions and utilities for working with ZModel AST:
+
+<PackageInstall devDependencies={["@zenstackhq/sdk@next"]} />
+
+A CLI plugin is an ESM module that default-exports an object that contains the following fields:
+
+- `name`: the name of the plugin.
+- `generate`: an async function that's invoked during the `zen generate` command run.
+- `statusText` (optional): text displayed in the CLI during the plugin run.
+
+The implementation looks like the following:
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-plugin" openFile="zenstack/password-plugin/index.ts" />
+
+Then, enable the reporting in ZModel with the "report" option:
+
+```zmodel title="schema.zmodel"
+plugin password {
+    provider = './password-plugin'
+    report = true
+}
+```
+
+Finally, run the `zen generate` command to generate the report:
+
+```bash
+npx zen generate
+```
+
+You should see that the custom plugin is run during the generation process, and the markdown file is created in the output folder.
+
+```plain
+% npx zen generate
+✔ Generating TypeScript schema
+✔ Running plugin Password Report
+Generation completed successfully in 116ms.
+```
+
+:::info How does the CLI load plugin modules?
+The CLI attempts to load the plugin module following these steps:
+1. If `provider` is resolvable as a file path (with ".js", ".mjs", ".ts", or ".mts" extensions), load it as a local file.
+2. If `provider` is resolvable as a folder containing an index file (with ".js", ".mjs", ".ts", or ".mts" extensions), load the index file.
+3. Otherwise, load it as an npm package.
+
+Please note that only ESM modules are supported. TypeScript files are loaded via [jiti](https://github.com/unjs/jiti).
+:::
+
+## Extending the ORM runtime
+
+The most powerful aspect of the plugin system is the ability to extend the ORM runtime behavior. ZenStack's ORM client provides a plugin system that allows you to intercept the ORM query lifecycle at different stages and abstraction levels. Please see the [ORM plugins](../orm/plugins/) documentation for detailed information.
+
+In this section, we'll see how to implement automatic password hashing functionality at runtime using the [Kysely](https://kysely.dev/) query hooks mechanism. The implementation requires an understanding of Kysely's [Operation Node](https://kysely-org.github.io/kysely-apidoc/interfaces/OperationNode.html) concept (which is the SQL AST used by Kysely internally).
+
+:::warning
+The implementation is mostly vibe-coded with Claude Code. Please review carefully before using it in production.
+:::
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-plugin" openFile="password-hasher-plugin.ts" />
+
+With the plugin installed on the ORM client, any time you create or update a User record, the password field will be automatically hashed before being stored in the database.
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-plugin" openFile="main.ts" />