@zenstackhq/cli 3.0.0-alpha.8 → 3.0.0-beta.1

package/src/actions/generate.ts

@@ -1,46 +1,35 @@
 import { invariant } from '@zenstackhq/common-helpers';
-import { isPlugin, LiteralExpr, type Model } from '@zenstackhq/language/ast';
-import { PrismaSchemaGenerator, TsSchemaGenerator, type CliGenerator } from '@zenstackhq/sdk';
+import { isPlugin, LiteralExpr, Plugin, type Model } from '@zenstackhq/language/ast';
+import { getLiteral, getLiteralArray } from '@zenstackhq/language/utils';
+import { type CliPlugin } from '@zenstackhq/sdk';
 import colors from 'colors';
-import fs from 'node:fs';
 import path from 'node:path';
-import { getSchemaFile, loadSchemaDocument } from './action-utils';
+import ora, { type Ora } from 'ora';
+import { CliError } from '../cli-error';
+import * as corePlugins from '../plugins';
+import { getPkgJsonConfig, getSchemaFile, loadSchemaDocument } from './action-utils';
 
 type Options = {
     schema?: string;
     output?: string;
-    silent?: boolean;
-    savePrismaSchema?: string | boolean;
+    silent: boolean;
 };
 
 /**
  * CLI action for generating code from schema
  */
 export async function run(options: Options) {
+    const start = Date.now();
+
     const schemaFile = getSchemaFile(options.schema);
 
     const model = await loadSchemaDocument(schemaFile);
-    const outputPath = options.output ?? path.dirname(schemaFile);
-
-    // generate TS schema
-    const tsSchemaFile = path.join(outputPath, 'schema.ts');
-    await new TsSchemaGenerator().generate(schemaFile, [], tsSchemaFile);
+    const outputPath = getOutputPath(options, schemaFile);
 
-    await runPlugins(model, outputPath, tsSchemaFile);
-
-    // generate Prisma schema
-    if (options.savePrismaSchema) {
-        const prismaSchema = await new PrismaSchemaGenerator(model).generate();
-        let prismaSchemaFile = path.join(outputPath, 'schema.prisma');
-        if (typeof options.savePrismaSchema === 'string') {
-            prismaSchemaFile = path.resolve(outputPath, options.savePrismaSchema);
-            fs.mkdirSync(path.dirname(prismaSchemaFile), { recursive: true });
-        }
-        fs.writeFileSync(prismaSchemaFile, prismaSchema);
-    }
+    await runPlugins(schemaFile, model, outputPath, options);
 
     if (!options.silent) {
-        console.log(colors.green('Generation completed successfully.'));
+        console.log(colors.green(`Generation completed successfully in ${Date.now() - start}ms.\n`));
         console.log(`You can now create a ZenStack client with it.
 
 \`\`\`ts
@@ -48,25 +37,108 @@ import { ZenStackClient } from '@zenstackhq/runtime';
 import { schema } from '${outputPath}/schema';
 
 const client = new ZenStackClient(schema, {
-    dialectConfig: { ... }
+    dialect: { ... }
 });
 \`\`\`
-`);
+
+Check documentation: https://zenstack.dev/docs/3.x`);
+    }
+}
+
+function getOutputPath(options: Options, schemaFile: string) {
+    if (options.output) {
+        return options.output;
+    }
+    const pkgJsonConfig = getPkgJsonConfig(process.cwd());
+    if (pkgJsonConfig.output) {
+        return pkgJsonConfig.output;
+    } else {
+        return path.dirname(schemaFile);
     }
 }
 
-async function runPlugins(model: Model, outputPath: string, tsSchemaFile: string) {
+async function runPlugins(schemaFile: string, model: Model, outputPath: string, options: Options) {
     const plugins = model.declarations.filter(isPlugin);
+    const processedPlugins: { cliPlugin: CliPlugin; pluginOptions: Record<string, unknown> }[] = [];
+
     for (const plugin of plugins) {
-        const providerField = plugin.fields.find((f) => f.name === 'provider');
-        invariant(providerField, `Plugin ${plugin.name} does not have a provider field`);
-        const provider = (providerField.value as LiteralExpr).value as string;
-        let useProvider = provider;
-        if (useProvider.startsWith('@core/')) {
-            useProvider = `@zenstackhq/runtime/plugins/${useProvider.slice(6)}`;
+        const provider = getPluginProvider(plugin);
+
+        let cliPlugin: CliPlugin;
+        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}`);
+            }
+        }
+
+        processedPlugins.push({ cliPlugin, pluginOptions: getPluginOptions(plugin) });
+    }
+
+    const defaultPlugins = [corePlugins['typescript']].reverse();
+    defaultPlugins.forEach((d) => {
+        if (!processedPlugins.some((p) => p.cliPlugin === d)) {
+            processedPlugins.push({ cliPlugin: d, pluginOptions: {} });
+        }
+    });
+
+    for (const { cliPlugin, pluginOptions } of processedPlugins) {
+        invariant(
+            typeof cliPlugin.generate === 'function',
+            `Plugin ${cliPlugin.name} does not have a generate function`,
+        );
+
+        // run plugin generator
+        let spinner: Ora | undefined;
+
+        if (!options.silent) {
+            spinner = ora(cliPlugin.statusText ?? `Running plugin ${cliPlugin.name}`).start();
+        }
+        try {
+            await cliPlugin.generate({
+                schemaFile,
+                model,
+                defaultOutputPath: outputPath,
+                pluginOptions,
+            });
+            spinner?.succeed();
+        } catch (err) {
+            spinner?.fail();
+            console.error(err);
+        }
+    }
+}
+
+function getPluginProvider(plugin: Plugin) {
+    const providerField = plugin.fields.find((f) => f.name === 'provider');
+    invariant(providerField, `Plugin ${plugin.name} does not have a provider field`);
+    const provider = (providerField.value as LiteralExpr).value as string;
+    return provider;
+}
+
+function getPluginOptions(plugin: Plugin): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const field of plugin.fields) {
+        if (field.name === 'provider') {
+            continue; // skip provider
+        }
+        const value = getLiteral(field.value) ?? getLiteralArray(field.value);
+        if (value === undefined) {
+            console.warn(`Plugin "${plugin.name}" option "${field.name}" has unsupported value, skipping`);
+            continue;
         }
-        const generator = (await import(useProvider)).default as CliGenerator;
-        console.log('Running generator:', provider);
-        await generator({ model, outputPath, tsSchemaFile });
+        result[field.name] = value;
     }
+    return result;
 }

package/src/actions/index.ts

@@ -3,5 +3,6 @@ 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';
 
-export { db, generate, info, init, migrate };
+export { db, generate, info, init, migrate, check };

package/src/actions/info.ts

@@ -57,6 +57,9 @@ async function getZenStackPackages(projectPath: string): Promise<Array<{ pkg: st
                         with: { type: 'json' },
                     })
                 ).default;
+                if (depPkgJson.private) {
+                    return undefined;
+                }
                 return { pkg, version: depPkgJson.version as string };
             } catch {
                 return { pkg, version: undefined };
@@ -64,5 +67,5 @@ async function getZenStackPackages(projectPath: string): Promise<Array<{ pkg: st
         }),
     );
 
-    return result;
+    return result.filter((p) => !!p);
 }

package/src/actions/migrate.ts

@@ -1,9 +1,12 @@
 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';
 
 type CommonOptions = {
     schema?: string;
+    migrations?: string;
 };
 
 type DevOptions = CommonOptions & {
@@ -19,12 +22,18 @@ type DeployOptions = CommonOptions;
 
 type StatusOptions = CommonOptions;
 
+type ResolveOptions = CommonOptions & {
+    applied?: string;
+    rolledBack?: string;
+};
+
 /**
  * CLI action for migration-related commands
  */
 export async function run(command: string, options: CommonOptions) {
     const schemaFile = getSchemaFile(options.schema);
-    const prismaSchemaFile = await generateTempPrismaSchema(schemaFile);
+    const prismaSchemaDir = options.migrations ? path.dirname(options.migrations) : undefined;
+    const prismaSchemaFile = await generateTempPrismaSchema(schemaFile, prismaSchemaDir);
 
     try {
         switch (command) {
@@ -43,6 +52,10 @@ export async function run(command: string, options: CommonOptions) {
             case 'status':
                 await runStatus(prismaSchemaFile, options as StatusOptions);
                 break;
+
+            case 'resolve':
+                await runResolve(prismaSchemaFile, options as ResolveOptions);
+                break;
         }
     } finally {
         if (fs.existsSync(prismaSchemaFile)) {
@@ -53,12 +66,15 @@ export async function run(command: string, options: CommonOptions) {
 
 async function runDev(prismaSchemaFile: string, options: DevOptions) {
     try {
-        await execPackage(
-            `prisma migrate dev --schema "${prismaSchemaFile}" --skip-generate${options.name ? ` --name ${options.name}` : ''}${options.createOnly ? ' --create-only' : ''}`,
-            {
-                stdio: 'inherit',
-            },
-        );
+        const cmd = [
+            'prisma migrate dev',
+            ` --schema "${prismaSchemaFile}"`,
+            ' --skip-generate',
+            options.name ? ` --name ${options.name}` : '',
+            options.createOnly ? ' --create-only' : '',
+        ].join('');
+
+        await execPackage(cmd);
     } catch (err) {
         handleSubProcessError(err);
     }
@@ -66,9 +82,11 @@ async function runDev(prismaSchemaFile: string, options: DevOptions) {
 
 async function runReset(prismaSchemaFile: string, options: ResetOptions) {
     try {
-        await execPackage(`prisma migrate reset --schema "${prismaSchemaFile}"${options.force ? ' --force' : ''}`, {
-            stdio: 'inherit',
-        });
+        const cmd = ['prisma migrate reset', ` --schema "${prismaSchemaFile}"`, options.force ? ' --force' : ''].join(
+            '',
+        );
+
+        await execPackage(cmd);
     } catch (err) {
         handleSubProcessError(err);
     }
@@ -76,9 +94,9 @@ async function runReset(prismaSchemaFile: string, options: ResetOptions) {
 
 async function runDeploy(prismaSchemaFile: string, _options: DeployOptions) {
     try {
-        await execPackage(`prisma migrate deploy --schema "${prismaSchemaFile}"`, {
-            stdio: 'inherit',
-        });
+        const cmd = ['prisma migrate deploy', ` --schema "${prismaSchemaFile}"`].join('');
+
+        await execPackage(cmd);
     } catch (err) {
         handleSubProcessError(err);
     }
@@ -86,9 +104,26 @@ async function runDeploy(prismaSchemaFile: string, _options: DeployOptions) {
 
 async function runStatus(prismaSchemaFile: string, _options: StatusOptions) {
     try {
-        await execPackage(`prisma migrate status --schema "${prismaSchemaFile}"`, {
-            stdio: 'inherit',
-        });
+        await execPackage(`prisma migrate status --schema "${prismaSchemaFile}"`);
+    } catch (err) {
+        handleSubProcessError(err);
+    }
+}
+
+async 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',
+            ` --schema "${prismaSchemaFile}"`,
+            options.applied ? ` --applied ${options.applied}` : '',
+            options.rolledBack ? ` --rolled-back ${options.rolledBack}` : '',
+        ].join('');
+
+        await execPackage(cmd);
     } catch (err) {
         handleSubProcessError(err);
     }

package/src/actions/templates.ts

@@ -27,14 +27,15 @@ model Post {
 `;
 
 export const STARTER_MAIN_TS = `import { ZenStackClient } from '@zenstackhq/runtime';
-import { schema } from './zenstack/schema';
 import SQLite from 'better-sqlite3';
+import { SqliteDialect } from 'kysely';
+import { schema } from './zenstack/schema';
 
 async function main() {
     const client = new ZenStackClient(schema, {
-        dialectConfig: {
+        dialect: new SqliteDialect({
             database: new SQLite('./zenstack/dev.db'),
-        },
+        }),
     });
     const user = await client.user.create({
         data: {

package/src/constants.ts

@@ -0,0 +1,2 @@
+// replaced at build time
+export const TELEMETRY_TRACKING_TOKEN = '<TELEMETRY_TRACKING_TOKEN>';

package/src/index.ts

@@ -1,31 +1,37 @@
 import { ZModelLanguageMetaData } from '@zenstackhq/language';
 import colors from 'colors';
-import { Command, Option } from 'commander';
+import { Command, CommanderError, Option } from 'commander';
 import * as actions from './actions';
-import { getVersion } from './utils/version-utils';
+import { CliError } from './cli-error';
+import { telemetry } from './telemetry';
+import { checkNewVersion, getVersion } from './utils/version-utils';
 
 const generateAction = async (options: Parameters<typeof actions.generate>[0]): Promise<void> => {
-    await actions.generate(options);
+    await telemetry.trackCommand('generate', () => actions.generate(options));
 };
 
-const migrateAction = async (command: string, options: any): Promise<void> => {
-    await actions.migrate(command, options);
+const migrateAction = async (subCommand: string, options: any): Promise<void> => {
+    await telemetry.trackCommand(`migrate ${subCommand}`, () => actions.migrate(subCommand, options));
 };
 
-const dbAction = async (command: string, options: any): Promise<void> => {
-    await actions.db(command, options);
+const dbAction = async (subCommand: string, options: any): Promise<void> => {
+    await telemetry.trackCommand(`db ${subCommand}`, () => actions.db(subCommand, options));
 };
 
 const infoAction = async (projectPath: string): Promise<void> => {
-    await actions.info(projectPath);
+    await telemetry.trackCommand('info', () => actions.info(projectPath));
 };
 
 const initAction = async (projectPath: string): Promise<void> => {
-    await actions.init(projectPath);
+    await telemetry.trackCommand('init', () => actions.init(projectPath));
 };
 
-export function createProgram() {
-    const program = new Command('zenstack');
+const checkAction = async (options: Parameters<typeof actions.check>[0]): Promise<void> => {
+    await telemetry.trackCommand('check', () => actions.check(options));
+};
+
+function createProgram() {
+    const program = new Command('zen');
 
     program.version(getVersion()!, '-v --version', 'display CLI version');
 
@@ -35,37 +41,37 @@ export function createProgram() {
         .description(
             `${colors.bold.blue(
                 'ζ',
-            )} ZenStack is a Prisma power pack for building full-stack apps.\n\nDocumentation: https://zenstack.dev.`,
+            )} ZenStack is the data layer for modern TypeScript apps.\n\nDocumentation: https://zenstack.dev/docs/3.x`,
         )
         .showHelpAfterError()
         .showSuggestionAfterError();
 
     const schemaOption = new Option(
         '--schema <file>',
-        `schema file (with extension ${schemaExtensions}). Defaults to "schema.zmodel" unless specified in package.json.`,
+        `schema file (with extension ${schemaExtensions}). Defaults to "zenstack/schema.zmodel" unless specified in package.json.`,
     );
 
+    const noVersionCheckOption = new Option('--no-version-check', 'do not check for new version');
+
     program
         .command('generate')
-        .description('Run code generation.')
+        .description('Run code generation plugins.')
         .addOption(schemaOption)
-        .addOption(new Option('--silent', 'do not print any output'))
-        .addOption(
-            new Option(
-                '--save-prisma-schema [path]',
-                'save a Prisma schema file, by default into the output directory',
-            ),
-        )
-        .addOption(new Option('-o, --output <path>', 'default output directory for core plugins'))
+        .addOption(noVersionCheckOption)
+        .addOption(new Option('-o, --output <path>', 'default output directory for code generation'))
+        .addOption(new Option('--silent', 'suppress all output except errors').default(false))
         .action(generateAction);
 
-    const migrateCommand = program.command('migrate').description('Update the database schema with migrations.');
+    const migrateCommand = program.command('migrate').description('Run database schema migration related tasks.');
+    const migrationsOption = new Option('--migrations <path>', 'path that contains the "migrations" directory');
 
     migrateCommand
         .command('dev')
         .addOption(schemaOption)
+        .addOption(noVersionCheckOption)
         .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.')
         .action((options) => migrateAction('dev', options));
 
@@ -73,45 +79,110 @@ export function createProgram() {
         .command('reset')
         .addOption(schemaOption)
         .addOption(new Option('--force', 'skip the confirmation prompt'))
+        .addOption(migrationsOption)
+        .addOption(noVersionCheckOption)
         .description('Reset your database and apply all migrations, all data will be lost.')
         .action((options) => migrateAction('reset', options));
 
     migrateCommand
         .command('deploy')
         .addOption(schemaOption)
+        .addOption(noVersionCheckOption)
+        .addOption(migrationsOption)
         .description('Deploy your pending migrations to your production/staging database.')
         .action((options) => migrateAction('deploy', options));
 
     migrateCommand
         .command('status')
         .addOption(schemaOption)
-        .description('check the status of your database migrations.')
+        .addOption(noVersionCheckOption)
+        .addOption(migrationsOption)
+        .description('Check the status of your database migrations.')
         .action((options) => migrateAction('status', options));
 
+    migrateCommand
+        .command('resolve')
+        .addOption(schemaOption)
+        .addOption(noVersionCheckOption)
+        .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.')
+        .action((options) => migrateAction('resolve', options));
+
     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));
 
     program
         .command('info')
-        .description('Get information of installed ZenStack and related 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.')
         .argument('[path]', 'project path', '.')
+        .addOption(noVersionCheckOption)
         .action(initAction);
 
+    program
+        .command('check')
+        .description('Check a ZModel schema for syntax or semantic errors.')
+        .addOption(schemaOption)
+        .addOption(noVersionCheckOption)
+        .action(checkAction);
+
+    program.hook('preAction', async (_thisCommand, actionCommand) => {
+        if (actionCommand.getOptionValue('versionCheck') !== false) {
+            await checkNewVersion();
+        }
+    });
+
     return program;
 }
 
-const program = createProgram();
-program.parse(process.argv);
+async function main() {
+    let exitCode = 0;
+
+    const program = createProgram();
+    program.exitOverride();
+
+    try {
+        await telemetry.trackCli(async () => {
+            await program.parseAsync();
+        });
+    } catch (e) {
+        if (e instanceof CommanderError) {
+            // ignore
+            exitCode = e.exitCode;
+        } else if (e instanceof CliError) {
+            // log
+            console.error(colors.red(e.message));
+            exitCode = 1;
+        } else {
+            console.error(colors.red(`Unhandled error: ${e}`));
+            exitCode = 1;
+        }
+    }
+
+    if (telemetry.isTracking) {
+        // give telemetry a chance to send events before exit
+        setTimeout(() => {
+            process.exit(exitCode);
+        }, 200);
+    } else {
+        process.exit(exitCode);
+    }
+}
+
+main();

package/src/plugins/index.ts

@@ -0,0 +1,2 @@
+export { default as prisma } from './prisma';
+export { default as typescript } from './typescript';

package/src/plugins/prisma.ts

@@ -0,0 +1,21 @@
+import { PrismaSchemaGenerator, type CliPlugin } from '@zenstackhq/sdk';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const plugin: CliPlugin = {
+    name: 'Prisma Schema Generator',
+    statusText: 'Generating Prisma schema',
+    async generate({ model, schemaFile, defaultOutputPath, pluginOptions }) {
+        let outFile = path.join(defaultOutputPath, 'schema.prisma');
+        if (typeof pluginOptions['output'] === 'string') {
+            outFile = path.resolve(path.dirname(schemaFile), pluginOptions['output']);
+            if (!fs.existsSync(path.dirname(outFile))) {
+                fs.mkdirSync(path.dirname(outFile), { recursive: true });
+            }
+        }
+        const prismaSchema = await new PrismaSchemaGenerator(model).generate();
+        fs.writeFileSync(outFile, prismaSchema);
+    },
+};
+
+export default plugin;

package/src/plugins/typescript.ts

@@ -0,0 +1,21 @@
+import type { CliPlugin } from '@zenstackhq/sdk';
+import { TsSchemaGenerator } from '@zenstackhq/sdk';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const plugin: CliPlugin = {
+    name: 'TypeScript Schema Generator',
+    statusText: 'Generating TypeScript schema',
+    async generate({ model, defaultOutputPath, pluginOptions }) {
+        let outDir = defaultOutputPath;
+        if (typeof pluginOptions['output'] === 'string') {
+            outDir = path.resolve(defaultOutputPath, pluginOptions['output']);
+            if (!fs.existsSync(outDir)) {
+                fs.mkdirSync(outDir, { recursive: true });
+            }
+        }
+        await new TsSchemaGenerator().generate(model, outDir);
+    },
+};
+
+export default plugin;