@zenstackhq/cli 3.0.0-beta.9 → 3.0.0

package/src/actions/generate.ts

@@ -3,7 +3,10 @@ import { isPlugin, LiteralExpr, Plugin, type Model } from '@zenstackhq/language/
 import { getLiteral, getLiteralArray } from '@zenstackhq/language/utils';
 import { type CliPlugin } from '@zenstackhq/sdk';
 import colors from 'colors';
+import { createJiti } from 'jiti';
+import fs from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import ora, { type Ora } from 'ora';
 import { CliError } from '../cli-error';
 import * as corePlugins from '../plugins';
@@ -13,6 +16,8 @@ type Options = {
     schema?: string;
     output?: string;
     silent: boolean;
+    lite: boolean;
+    liteOnly: boolean;
 };
 
 /**
@@ -33,8 +38,8 @@ export async function run(options: Options) {
         console.log(`You can now create a ZenStack client with it.
 
 \`\`\`ts
-import { ZenStackClient } from '@zenstackhq/runtime';
-import { schema } from '${outputPath}/schema';
+import { ZenStackClient } from '@zenstackhq/orm';
+import { schema } from '${path.relative('.', outputPath)}/schema';
 
 const client = new ZenStackClient(schema, {
     dialect: { ... }
@@ -64,32 +69,43 @@ async function runPlugins(schemaFile: string, model: Model, outputPath: string,
     for (const plugin of plugins) {
         const provider = getPluginProvider(plugin);
 
-        let cliPlugin: CliPlugin;
+        let cliPlugin: CliPlugin | undefined;
         if (provider.startsWith('@core/')) {
             cliPlugin = (corePlugins as any)[provider.slice('@core/'.length)];
             if (!cliPlugin) {
                 throw new CliError(`Unknown core plugin: ${provider}`);
             }
         } else {
-            let moduleSpec = provider;
-            if (moduleSpec.startsWith('.')) {
-                // relative to schema's path
-                moduleSpec = path.resolve(path.dirname(schemaFile), moduleSpec);
-            }
-            try {
-                cliPlugin = (await import(moduleSpec)).default as CliPlugin;
-            } catch (error) {
-                throw new CliError(`Failed to load plugin ${provider}: ${error}`);
-            }
+            cliPlugin = await loadPluginModule(provider, path.dirname(schemaFile));
         }
 
-        processedPlugins.push({ cliPlugin, pluginOptions: getPluginOptions(plugin) });
+        if (cliPlugin) {
+            const pluginOptions = getPluginOptions(plugin);
+
+            // merge CLI options
+            if (provider === '@core/typescript') {
+                if (pluginOptions['lite'] === undefined) {
+                    pluginOptions['lite'] = options.lite;
+                }
+                if (pluginOptions['liteOnly'] === undefined) {
+                    pluginOptions['liteOnly'] = options.liteOnly;
+                }
+            }
+
+            processedPlugins.push({ cliPlugin, pluginOptions });
+        }
     }
 
-    const defaultPlugins = [corePlugins['typescript']].reverse();
-    defaultPlugins.forEach((d) => {
-        if (!processedPlugins.some((p) => p.cliPlugin === d)) {
-            processedPlugins.push({ cliPlugin: d, pluginOptions: {} });
+    const defaultPlugins = [
+        {
+            plugin: corePlugins['typescript'],
+            options: { lite: options.lite, liteOnly: options.liteOnly },
+        },
+    ];
+    defaultPlugins.forEach(({ plugin, options }) => {
+        if (!processedPlugins.some((p) => p.cliPlugin === plugin)) {
+            // default plugins are run before user plugins
+            processedPlugins.unshift({ cliPlugin: plugin, pluginOptions: options });
         }
     });
 
@@ -142,3 +158,69 @@ function getPluginOptions(plugin: Plugin): Record<string, unknown> {
     }
     return result;
 }
+
+async function loadPluginModule(provider: string, basePath: string) {
+    let moduleSpec = provider;
+    if (moduleSpec.startsWith('.')) {
+        // relative to schema's path
+        moduleSpec = path.resolve(basePath, moduleSpec);
+    }
+
+    const importAsEsm = async (spec: string) => {
+        try {
+            const result = (await import(spec)).default as CliPlugin;
+            return result;
+        } catch (err) {
+            throw new CliError(`Failed to load plugin module from ${spec}: ${(err as Error).message}`);
+        }
+    };
+
+    const jiti = createJiti(pathToFileURL(basePath).toString());
+    const importAsTs = async (spec: string) => {
+        try {
+            const result = (await jiti.import(spec, { default: true })) as CliPlugin;
+            return result;
+        } catch (err) {
+            throw new CliError(`Failed to load plugin module from ${spec}: ${(err as Error).message}`);
+        }
+    };
+
+    const esmSuffixes = ['.js', '.mjs'];
+    const tsSuffixes = ['.ts', '.mts'];
+
+    if (fs.existsSync(moduleSpec) && fs.statSync(moduleSpec).isFile()) {
+        // try provider as ESM file
+        if (esmSuffixes.some((suffix) => moduleSpec.endsWith(suffix))) {
+            return await importAsEsm(pathToFileURL(moduleSpec).toString());
+        }
+
+        // try provider as TS file
+        if (tsSuffixes.some((suffix) => moduleSpec.endsWith(suffix))) {
+            return await importAsTs(moduleSpec);
+        }
+    }
+
+    // try ESM index files in provider directory
+    for (const suffix of esmSuffixes) {
+        const indexPath = path.join(moduleSpec, `index${suffix}`);
+        if (fs.existsSync(indexPath)) {
+            return await importAsEsm(pathToFileURL(indexPath).toString());
+        }
+    }
+
+    // try TS index files in provider directory
+    for (const suffix of tsSuffixes) {
+        const indexPath = path.join(moduleSpec, `index${suffix}`);
+        if (fs.existsSync(indexPath)) {
+            return await importAsTs(indexPath);
+        }
+    }
+
+    // last resort, try to import as esm directly
+    try {
+        return (await import(moduleSpec)).default as CliPlugin;
+    } catch {
+        // plugin may not export a generator so we simply ignore the error here
+        return undefined;
+    }
+}

package/src/actions/index.ts

@@ -1,8 +1,10 @@
+import { run as check } from './check';
 import { run as db } from './db';
+import { run as format } from './format';
 import { run as generate } from './generate';
 import { run as info } from './info';
 import { run as init } from './init';
 import { run as migrate } from './migrate';
-import { run as check } from './check';
+import { run as seed } from './seed';
 
-export { db, generate, info, init, migrate, check };
+export { check, db, format, generate, info, init, migrate, seed };

package/src/actions/init.ts

@@ -13,7 +13,7 @@ import { STARTER_ZMODEL } from './templates';
 export async function run(projectPath: string) {
     const packages = [
         { name: '@zenstackhq/cli@next', dev: true },
-        { name: '@zenstackhq/runtime@next', dev: false },
+        { name: '@zenstackhq/orm@next', dev: false },
     ];
     let pm = await detect();
     if (!pm) {
@@ -23,9 +23,9 @@ export async function run(projectPath: string) {
     console.log(colors.gray(`Using package manager: ${pm.agent}`));
 
     for (const pkg of packages) {
-        const resolved = resolveCommand(pm.agent, 'install', [
+        const resolved = resolveCommand(pm.agent, 'add', [
             pkg.name,
-            ...(pkg.dev ? [pm.agent === 'yarn' ? '--dev' : '--save-dev'] : []),
+            ...(pkg.dev ? [pm.agent.startsWith('yarn') || pm.agent === 'bun' ? '--dev' : '--save-dev'] : []),
         ]);
         if (!resolved) {
             throw new CliError(`Unable to determine how to install package "${pkg.name}". Please install it manually.`);

package/src/actions/migrate.ts

@@ -1,12 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { CliError } from '../cli-error';
-import { execPackage } from '../utils/exec-utils';
-import { generateTempPrismaSchema, getSchemaFile } from './action-utils';
+import { execPrisma } from '../utils/exec-utils';
+import { generateTempPrismaSchema, getSchemaFile, requireDataSourceUrl } from './action-utils';
+import { run as runSeed } from './seed';
 
 type CommonOptions = {
     schema?: string;
     migrations?: string;
+    skipSeed?: boolean;
 };
 
 type DevOptions = CommonOptions & {
@@ -32,6 +34,10 @@ type ResolveOptions = CommonOptions & {
  */
 export async function run(command: string, options: CommonOptions) {
     const schemaFile = getSchemaFile(options.schema);
+
+    // validate datasource url exists
+    await requireDataSourceUrl(schemaFile);
+
     const prismaSchemaDir = options.migrations ? path.dirname(options.migrations) : undefined;
     const prismaSchemaFile = await generateTempPrismaSchema(schemaFile, prismaSchemaDir);
 
@@ -64,17 +70,17 @@ export async function run(command: string, options: CommonOptions) {
     }
 }
 
-async function runDev(prismaSchemaFile: string, options: DevOptions) {
+function runDev(prismaSchemaFile: string, options: DevOptions) {
     try {
         const cmd = [
-            'prisma migrate dev',
+            'migrate dev',
             ` --schema "${prismaSchemaFile}"`,
             ' --skip-generate',
-            options.name ? ` --name ${options.name}` : '',
+            ' --skip-seed',
+            options.name ? ` --name "${options.name}"` : '',
             options.createOnly ? ' --create-only' : '',
         ].join('');
-
-        await execPackage(cmd);
+        execPrisma(cmd);
     } catch (err) {
         handleSubProcessError(err);
     }
@@ -82,48 +88,53 @@ async function runDev(prismaSchemaFile: string, options: DevOptions) {
 
 async function runReset(prismaSchemaFile: string, options: ResetOptions) {
     try {
-        const cmd = ['prisma migrate reset', ` --schema "${prismaSchemaFile}"`, options.force ? ' --force' : ''].join(
-            '',
-        );
-
-        await execPackage(cmd);
+        const cmd = [
+            'migrate reset',
+            ` --schema "${prismaSchemaFile}"`,
+            ' --skip-generate',
+            ' --skip-seed',
+            options.force ? ' --force' : '',
+        ].join('');
+        execPrisma(cmd);
     } catch (err) {
         handleSubProcessError(err);
     }
+
+    if (!options.skipSeed) {
+        await runSeed({ noWarnings: true, printStatus: true }, []);
+    }
 }
 
-async function runDeploy(prismaSchemaFile: string, _options: DeployOptions) {
+function runDeploy(prismaSchemaFile: string, _options: DeployOptions) {
     try {
-        const cmd = ['prisma migrate deploy', ` --schema "${prismaSchemaFile}"`].join('');
-
-        await execPackage(cmd);
+        const cmd = ['migrate deploy', ` --schema "${prismaSchemaFile}"`].join('');
+        execPrisma(cmd);
     } catch (err) {
         handleSubProcessError(err);
     }
 }
 
-async function runStatus(prismaSchemaFile: string, _options: StatusOptions) {
+function runStatus(prismaSchemaFile: string, _options: StatusOptions) {
     try {
-        await execPackage(`prisma migrate status --schema "${prismaSchemaFile}"`);
+        execPrisma(`migrate status --schema "${prismaSchemaFile}"`);
     } catch (err) {
         handleSubProcessError(err);
     }
 }
 
-async function runResolve(prismaSchemaFile: string, options: ResolveOptions) {
+function runResolve(prismaSchemaFile: string, options: ResolveOptions) {
     if (!options.applied && !options.rolledBack) {
         throw new CliError('Either --applied or --rolled-back option must be provided');
     }
 
     try {
         const cmd = [
-            'prisma migrate resolve',
+            'migrate resolve',
             ` --schema "${prismaSchemaFile}"`,
-            options.applied ? ` --applied ${options.applied}` : '',
-            options.rolledBack ? ` --rolled-back ${options.rolledBack}` : '',
+            options.applied ? ` --applied "${options.applied}"` : '',
+            options.rolledBack ? ` --rolled-back "${options.rolledBack}"` : '',
         ].join('');
-
-        await execPackage(cmd);
+        execPrisma(cmd);
     } catch (err) {
         handleSubProcessError(err);
     }

package/src/actions/seed.ts

@@ -0,0 +1,38 @@
+import colors from 'colors';
+import { execaCommand } from 'execa';
+import { CliError } from '../cli-error';
+import { getPkgJsonConfig } from './action-utils';
+
+type Options = {
+    noWarnings?: boolean;
+    printStatus?: boolean;
+};
+
+/**
+ * CLI action for seeding the database.
+ */
+export async function run(options: Options, args: string[]) {
+    const pkgJsonConfig = getPkgJsonConfig(process.cwd());
+    if (!pkgJsonConfig.seed) {
+        if (!options.noWarnings) {
+            console.warn(colors.yellow('No seed script defined in package.json. Skipping seeding.'));
+        }
+        return;
+    }
+
+    const command = `${pkgJsonConfig.seed}${args.length > 0 ? ' ' + args.join(' ') : ''}`;
+
+    if (options.printStatus) {
+        console.log(colors.gray(`Running seed script "${command}"...`));
+    }
+
+    try {
+        await execaCommand(command, {
+            stdout: 'inherit',
+            stderr: 'inherit',
+        });
+    } catch (err) {
+        console.error(colors.red(err instanceof Error ? err.message : String(err)));
+        throw new CliError('Failed to seed the database. Please check the error message above for details.');
+    }
+}

package/src/actions/templates.ts

@@ -21,23 +21,23 @@ model Post {
     title     String   @length(1, 256)
     content   String
     published Boolean  @default(false)
-    author    User     @relation(fields: [authorId], references: [id])
+    author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
     authorId  String
 }
 `;
 
-export const STARTER_MAIN_TS = `import { ZenStackClient } from '@zenstackhq/runtime';
+export const STARTER_MAIN_TS = `import { ZenStackClient } from '@zenstackhq/orm';
+import { SqliteDialect } from '@zenstackhq/orm/dialects/sqlite';
 import SQLite from 'better-sqlite3';
-import { SqliteDialect } from 'kysely';
 import { schema } from './zenstack/schema';
 
 async function main() {
-    const client = new ZenStackClient(schema, {
+    const db = new ZenStackClient(schema, {
         dialect: new SqliteDialect({
             database: new SQLite('./zenstack/dev.db'),
         }),
     });
-    const user = await client.user.create({
+    const user = await db.user.create({
         data: {
             email: 'test@zenstack.dev',
             posts: {

package/src/constants.ts

@@ -1,2 +1,5 @@
 // replaced at build time
 export const TELEMETRY_TRACKING_TOKEN = '<TELEMETRY_TRACKING_TOKEN>';
+
+// plugin-contributed model file name
+export const PLUGIN_MODULE_NAME = 'plugin.zmodel';

package/src/index.ts

@@ -30,10 +30,19 @@ const checkAction = async (options: Parameters<typeof actions.check>[0]): Promis
     await telemetry.trackCommand('check', () => actions.check(options));
 };
 
-function createProgram() {
-    const program = new Command('zen');
+const formatAction = async (options: Parameters<typeof actions.format>[0]): Promise<void> => {
+    await telemetry.trackCommand('format', () => actions.format(options));
+};
 
-    program.version(getVersion()!, '-v --version', 'display CLI version');
+const seedAction = async (options: Parameters<typeof actions.seed>[0], args: string[]): Promise<void> => {
+    await telemetry.trackCommand('db seed', () => actions.seed(options, args));
+};
+
+function createProgram() {
+    const program = new Command('zen')
+        .alias('zenstack')
+        .helpOption('-h, --help', 'Show this help message')
+        .version(getVersion()!, '-v --version', 'Show CLI version');
 
     const schemaExtensions = ZModelLanguageMetaData.fileExtensions.join(', ');
 
@@ -41,7 +50,7 @@ function createProgram() {
         .description(
             `${colors.bold.blue(
                 'ζ',
-            )} ZenStack is the data layer for modern TypeScript apps.\n\nDocumentation: https://zenstack.dev/docs/3.x`,
+            )} ZenStack is the modern data layer for TypeScript apps.\n\nDocumentation: https://zenstack.dev/docs`,
         )
         .showHelpAfterError()
         .showSuggestionAfterError();
@@ -55,10 +64,12 @@ function createProgram() {
 
     program
         .command('generate')
-        .description('Run code generation plugins.')
+        .description('Run code generation plugins')
         .addOption(schemaOption)
         .addOption(noVersionCheckOption)
         .addOption(new Option('-o, --output <path>', 'default output directory for code generation'))
+        .addOption(new Option('--lite', 'also generate a lite version of schema without attributes').default(false))
+        .addOption(new Option('--lite-only', 'only generate lite version of schema without attributes').default(false))
         .addOption(new Option('--silent', 'suppress all output except errors').default(false))
         .action(generateAction);
 
@@ -72,7 +83,7 @@ function createProgram() {
         .addOption(new Option('-n, --name <name>', 'migration name'))
         .addOption(new Option('--create-only', 'only create migration, do not apply'))
         .addOption(migrationsOption)
-        .description('Create a migration from changes in schema and apply it to the database.')
+        .description('Create a migration from changes in schema and apply it to the database')
         .action((options) => migrateAction('dev', options));
 
     migrateCommand
@@ -80,8 +91,13 @@ function createProgram() {
         .addOption(schemaOption)
         .addOption(new Option('--force', 'skip the confirmation prompt'))
         .addOption(migrationsOption)
+        .addOption(new Option('--skip-seed', 'skip seeding the database after reset'))
         .addOption(noVersionCheckOption)
-        .description('Reset your database and apply all migrations, all data will be lost.')
+        .description('Reset your database and apply all migrations, all data will be lost')
+        .addHelpText(
+            'after',
+            '\nIf there is a seed script defined in package.json, it will be run after the reset. Use --skip-seed to skip it.',
+        )
         .action((options) => migrateAction('reset', options));
 
     migrateCommand
@@ -89,7 +105,7 @@ function createProgram() {
         .addOption(schemaOption)
         .addOption(noVersionCheckOption)
         .addOption(migrationsOption)
-        .description('Deploy your pending migrations to your production/staging database.')
+        .description('Deploy your pending migrations to your production/staging database')
         .action((options) => migrateAction('deploy', options));
 
     migrateCommand
@@ -97,7 +113,7 @@ function createProgram() {
         .addOption(schemaOption)
         .addOption(noVersionCheckOption)
         .addOption(migrationsOption)
-        .description('Check the status of your database migrations.')
+        .description('Check the status of your database migrations')
         .action((options) => migrateAction('status', options));
 
     migrateCommand
@@ -107,41 +123,70 @@ function createProgram() {
         .addOption(migrationsOption)
         .addOption(new Option('--applied <migration>', 'record a specific migration as applied'))
         .addOption(new Option('--rolled-back <migration>', 'record a specific migration as rolled back'))
-        .description('Resolve issues with database migrations in deployment databases.')
+        .description('Resolve issues with database migrations in deployment databases')
         .action((options) => migrateAction('resolve', options));
 
-    const dbCommand = program.command('db').description('Manage your database schema during development.');
+    const dbCommand = program.command('db').description('Manage your database schema during development');
 
     dbCommand
         .command('push')
-        .description('Push the state from your schema to your database.')
+        .description('Push the state from your schema to your database')
         .addOption(schemaOption)
         .addOption(noVersionCheckOption)
         .addOption(new Option('--accept-data-loss', 'ignore data loss warnings'))
         .addOption(new Option('--force-reset', 'force a reset of the database before push'))
         .action((options) => dbAction('push', options));
 
+    dbCommand
+        .command('seed')
+        .description('Seed the database')
+        .allowExcessArguments(true)
+        .addHelpText(
+            'after',
+            `
+Seed script is configured under the "zenstack.seed" field in package.json.
+E.g.:
+{
+    "zenstack": {
+        "seed": "ts-node ./zenstack/seed.ts"
+    }
+}
+
+Arguments following -- are passed to the seed script. E.g.: "zen db seed -- --users 10"`,
+        )
+        .addOption(noVersionCheckOption)
+        .action((options, command) => seedAction(options, command.args));
+
     program
         .command('info')
-        .description('Get information of installed ZenStack packages.')
+        .description('Get information of installed ZenStack packages')
         .argument('[path]', 'project path', '.')
         .addOption(noVersionCheckOption)
         .action(infoAction);
 
     program
         .command('init')
-        .description('Initialize an existing project for ZenStack.')
+        .description('Initialize an existing project for ZenStack')
         .argument('[path]', 'project path', '.')
         .addOption(noVersionCheckOption)
         .action(initAction);
 
     program
         .command('check')
-        .description('Check a ZModel schema for syntax or semantic errors.')
+        .description('Check a ZModel schema for syntax or semantic errors')
         .addOption(schemaOption)
         .addOption(noVersionCheckOption)
         .action(checkAction);
 
+    program
+        .command('format')
+        .description('Format a ZModel schema file')
+        .addOption(schemaOption)
+        .addOption(noVersionCheckOption)
+        .action(formatAction);
+
+    program.addHelpCommand('help [command]', 'Display help for a command');
+
     program.hook('preAction', async (_thisCommand, actionCommand) => {
         if (actionCommand.getOptionValue('versionCheck') !== false) {
             await checkNewVersion();

package/src/plugins/typescript.ts

@@ -7,6 +7,7 @@ const plugin: CliPlugin = {
     name: 'TypeScript Schema Generator',
     statusText: 'Generating TypeScript schema',
     async generate({ model, defaultOutputPath, pluginOptions }) {
+        // output path
         let outDir = defaultOutputPath;
         if (typeof pluginOptions['output'] === 'string') {
             outDir = path.resolve(defaultOutputPath, pluginOptions['output']);
@@ -14,7 +15,25 @@ const plugin: CliPlugin = {
                 fs.mkdirSync(outDir, { recursive: true });
             }
         }
-        await new TsSchemaGenerator().generate(model, outDir);
+
+        // lite mode
+        const lite = pluginOptions['lite'] === true;
+
+        // liteOnly mode
+        const liteOnly = pluginOptions['liteOnly'] === true;
+
+        // add .js extension when importing
+        const importWithFileExtension = pluginOptions['importWithFileExtension'];
+        if (importWithFileExtension && typeof importWithFileExtension !== 'string') {
+            throw new Error('The "importWithFileExtension" option must be a string if specified.');
+        }
+
+        await new TsSchemaGenerator().generate(model, {
+            outDir,
+            lite,
+            liteOnly,
+            importWithFileExtension: importWithFileExtension as string | undefined,
+        });
     },
 };
 

package/src/utils/exec-utils.ts

@@ -1,4 +1,5 @@
 import { execSync as _exec, type ExecSyncOptions } from 'child_process';
+import { fileURLToPath } from 'url';
 
 /**
  * Utility for executing command synchronously and prints outputs on current console
@@ -24,3 +25,37 @@ export function execPackage(
     const packageManager = process?.versions?.['bun'] ? 'bunx' : 'npx';
     execSync(`${packageManager} ${cmd}`, options);
 }
+
+/**
+ * Utility for running prisma commands
+ */
+export function execPrisma(args: string, options?: Omit<ExecSyncOptions, 'env'> & { env?: Record<string, string> }) {
+    let prismaPath: string | undefined;
+    try {
+        if (typeof import.meta.resolve === 'function') {
+            // esm
+            prismaPath = fileURLToPath(import.meta.resolve('prisma/build/index.js'));
+        } else {
+            // cjs
+            prismaPath = require.resolve('prisma/build/index.js');
+        }
+    } catch {
+        // ignore and fallback
+    }
+
+    const _options = {
+        ...options,
+        env: {
+            ...options?.env,
+            PRISMA_HIDE_UPDATE_MESSAGE: '1',
+        },
+    };
+
+    if (!prismaPath) {
+        // fallback to npx/bunx execute
+        execPackage(`prisma ${args}`, _options);
+        return;
+    }
+
+    execSync(`node ${prismaPath} ${args}`, _options);
+}