@zenstackhq/cli 3.0.0-alpha.2 → 3.0.0-alpha.21

package/src/actions/info.ts

@@ -7,9 +7,7 @@ import path from 'node:path';
 export async function run(projectPath: string) {
     const packages = await getZenStackPackages(projectPath);
     if (!packages) {
-        console.error(
-            'Unable to locate package.json. Are you in a valid project directory?'
-        );
+        console.error('Unable to locate package.json. Are you in a valid project directory?');
         return;
     }
 
@@ -23,17 +21,11 @@ export async function run(projectPath: string) {
     }
 
     if (versions.size > 1) {
-        console.warn(
-            colors.yellow(
-                'WARNING: Multiple versions of Zenstack packages detected. This may cause issues.'
-            )
-        );
+        console.warn(colors.yellow('WARNING: Multiple versions of Zenstack packages detected. This may cause issues.'));
     }
 }
 
-async function getZenStackPackages(
-    projectPath: string
-): Promise<Array<{ pkg: string; version: string | undefined }>> {
+async function getZenStackPackages(projectPath: string): Promise<Array<{ pkg: string; version: string | undefined }>> {
     let pkgJson: {
         dependencies: Record<string, unknown>;
         devDependencies: Record<string, unknown>;
@@ -45,17 +37,16 @@ async function getZenStackPackages(
                 with: { type: 'json' },
             })
         ).default;
-    } catch (err) {
+    } catch {
         return [];
     }
 
     const packages = Array.from(
         new Set(
-            [
-                ...Object.keys(pkgJson.dependencies ?? {}),
-                ...Object.keys(pkgJson.devDependencies ?? {}),
-            ].filter((p) => p.startsWith('@zenstackhq/') || p === 'zenstack')
-        )
+            [...Object.keys(pkgJson.dependencies ?? {}), ...Object.keys(pkgJson.devDependencies ?? {})].filter(
+                (p) => p.startsWith('@zenstackhq/') || p === 'zenstack',
+            ),
+        ),
     ).sort();
 
     const result = await Promise.all(
@@ -70,7 +61,7 @@ async function getZenStackPackages(
             } catch {
                 return { pkg, version: undefined };
             }
-        })
+        }),
     );
 
     return result;

package/src/actions/init.ts

@@ -28,9 +28,7 @@ export async function run(projectPath: string) {
             ...(pkg.dev ? [pm.agent === 'yarn' ? '--dev' : '--save-dev'] : []),
         ]);
         if (!resolved) {
-            throw new CliError(
-                `Unable to determine how to install package "${pkg.name}". Please install it manually.`
-            );
+            throw new CliError(`Unable to determine how to install package "${pkg.name}". Please install it manually.`);
         }
 
         const spinner = ora(`Installing "${pkg.name}"`).start();
@@ -51,32 +49,13 @@ export async function run(projectPath: string) {
         fs.mkdirSync(path.join(projectPath, generationFolder));
     }
 
-    if (
-        !fs.existsSync(
-            path.join(projectPath, generationFolder, 'schema.zmodel')
-        )
-    ) {
-        fs.writeFileSync(
-            path.join(projectPath, generationFolder, 'schema.zmodel'),
-            STARTER_ZMODEL
-        );
+    if (!fs.existsSync(path.join(projectPath, generationFolder, 'schema.zmodel'))) {
+        fs.writeFileSync(path.join(projectPath, generationFolder, 'schema.zmodel'), STARTER_ZMODEL);
     } else {
-        console.log(
-            colors.yellow(
-                'Schema file already exists. Skipping generation of sample.'
-            )
-        );
+        console.log(colors.yellow('Schema file already exists. Skipping generation of sample.'));
     }
 
     console.log(colors.green('ZenStack project initialized successfully!'));
-    console.log(
-        colors.gray(
-            `See "${generationFolder}/schema.zmodel" for your database schema.`
-        )
-    );
-    console.log(
-        colors.gray(
-            'Run `zenstack generate` to compile the the schema into a TypeScript file.'
-        )
-    );
+    console.log(colors.gray(`See "${generationFolder}/schema.zmodel" for your database schema.`));
+    console.log(colors.gray('Run `zenstack generate` to compile the the schema into a TypeScript file.'));
 }

package/src/actions/migrate.ts

@@ -1,109 +1,107 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import { execPackage } from '../utils/exec-utils';
-import { getSchemaFile } from './action-utils';
-import { run as runGenerate } from './generate';
+import { generateTempPrismaSchema, getSchemaFile } from './action-utils';
 
 type CommonOptions = {
     schema?: string;
+    migrations?: string;
+};
+
+type DevOptions = CommonOptions & {
     name?: string;
+    createOnly?: boolean;
+};
+
+type ResetOptions = CommonOptions & {
+    force?: boolean;
 };
 
+type DeployOptions = CommonOptions;
+
+type StatusOptions = CommonOptions;
+
 /**
  * CLI action for migration-related commands
  */
 export async function run(command: string, options: CommonOptions) {
     const schemaFile = getSchemaFile(options.schema);
+    const prismaSchemaDir = options.migrations ? path.dirname(options.migrations) : undefined;
+    const prismaSchemaFile = await generateTempPrismaSchema(schemaFile, prismaSchemaDir);
+
+    try {
+        switch (command) {
+            case 'dev':
+                await runDev(prismaSchemaFile, options as DevOptions);
+                break;
 
-    // run generate first
-    await runGenerate({
-        schema: schemaFile,
-        silent: true,
-    });
-
-    const prismaSchemaFile = path.join(
-        path.dirname(schemaFile),
-        'schema.prisma'
-    );
-
-    switch (command) {
-        case 'dev':
-            await runDev(prismaSchemaFile, options);
-            break;
-
-        case 'reset':
-            await runReset(prismaSchemaFile, options as any);
-            break;
-
-        case 'deploy':
-            await runDeploy(prismaSchemaFile, options);
-            break;
-
-        case 'status':
-            await runStatus(prismaSchemaFile, options);
-            break;
+            case 'reset':
+                await runReset(prismaSchemaFile, options as ResetOptions);
+                break;
+
+            case 'deploy':
+                await runDeploy(prismaSchemaFile, options as DeployOptions);
+                break;
+
+            case 'status':
+                await runStatus(prismaSchemaFile, options as StatusOptions);
+                break;
+        }
+    } finally {
+        if (fs.existsSync(prismaSchemaFile)) {
+            fs.unlinkSync(prismaSchemaFile);
+        }
     }
 }
 
-async function runDev(prismaSchemaFile: string, _options: unknown) {
+async function runDev(prismaSchemaFile: string, options: DevOptions) {
     try {
-        await execPackage(
-            `prisma migrate dev --schema "${prismaSchemaFile}" --skip-generate`,
-            {
-                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);
     }
 }
 
-async function runReset(prismaSchemaFile: string, options: { force: boolean }) {
+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);
     }
 }
 
-async function runDeploy(prismaSchemaFile: string, _options: unknown) {
+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);
     }
 }
 
-async function runStatus(prismaSchemaFile: string, _options: unknown) {
+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);
     }
 }
 
 function handleSubProcessError(err: unknown) {
-    if (
-        err instanceof Error &&
-        'status' in err &&
-        typeof err.status === 'number'
-    ) {
+    if (err instanceof Error && 'status' in err && typeof err.status === 'number') {
         process.exit(err.status);
     } else {
         process.exit(1);

package/src/actions/templates.ts

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

package/src/actions/validate.ts

@@ -0,0 +1,22 @@
+import colors from 'colors';
+import { getSchemaFile, loadSchemaDocument } from './action-utils';
+
+type Options = {
+    schema?: string;
+};
+
+/**
+ * CLI action for validating schema without generation
+ */
+export async function run(options: Options) {
+    const schemaFile = getSchemaFile(options.schema);
+
+    try {
+        await loadSchemaDocument(schemaFile);
+        console.log(colors.green('✓ Schema validation completed successfully.'));
+    } catch (error) {
+        console.error(colors.red('✗ Schema validation failed.'));
+        // Re-throw to maintain CLI exit code behavior
+        throw error;
+    }
+}

package/src/index.ts

@@ -1,12 +1,11 @@
 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 { CliError } from './cli-error';
 import { getVersion } from './utils/version-utils';
 
-const generateAction = async (
-    options: Parameters<typeof actions.generate>[0]
-): Promise<void> => {
+const generateAction = async (options: Parameters<typeof actions.generate>[0]): Promise<void> => {
     await actions.generate(options);
 };
 
@@ -26,6 +25,10 @@ const initAction = async (projectPath: string): Promise<void> => {
     await actions.init(projectPath);
 };
 
+const validateAction = async (options: Parameters<typeof actions.validate>[0]): Promise<void> => {
+    await actions.validate(options);
+};
+
 export function createProgram() {
     const program = new Command('zenstack');
 
@@ -36,92 +39,78 @@ export function createProgram() {
     program
         .description(
             `${colors.bold.blue(
-                'ζ'
-            )} ZenStack is a Prisma power pack for building full-stack apps.\n\nDocumentation: https://zenstack.dev.`
+                'ζ',
+            )} ZenStack is a database access toolkit for TypeScript apps.\n\nDocumentation: https://zenstack.dev.`,
         )
         .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 "schema.zmodel" unless specified in package.json.`,
     );
 
     program
         .command('generate')
         .description('Run code generation.')
         .addOption(schemaOption)
+        .addOption(new Option('--silent', 'do not print any output'))
         .addOption(
             new Option(
-                '-o, --output <path>',
-                'default output directory for core plugins'
-            )
+                '--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'))
         .action(generateAction);
 
-    const migrateCommand = program
-        .command('migrate')
-        .description('Update the database schema with migrations.');
+    const migrateCommand = program.command('migrate').description('Update the database schema with migrations.');
+    const migrationsOption = new Option('--migrations <path>', 'path for migrations');
 
     migrateCommand
         .command('dev')
         .addOption(schemaOption)
         .addOption(new Option('-n, --name <name>', 'migration name'))
-        .addOption(
-            new Option('--create-only', 'only create migration, do not apply')
-        )
-        .description(
-            'Create a migration from changes in schema and apply it to the database.'
-        )
+        .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));
 
     migrateCommand
         .command('reset')
         .addOption(schemaOption)
         .addOption(new Option('--force', 'skip the confirmation prompt'))
-        .description(
-            'Reset your database and apply all migrations, all data will be lost.'
-        )
+        .addOption(migrationsOption)
+        .description('Reset your database and apply all migrations, all data will be lost.')
         .action((options) => migrateAction('reset', options));
 
     migrateCommand
         .command('deploy')
         .addOption(schemaOption)
-        .description(
-            'Deploy your pending migrations to your production/staging database.'
-        )
+        .addOption(migrationsOption)
+        .description('Deploy your pending migrations to your production/staging database.')
         .action((options) => migrateAction('deploy', options));
 
     migrateCommand
         .command('status')
         .addOption(schemaOption)
+        .addOption(migrationsOption)
         .description('check the status of your database migrations.')
         .action((options) => migrateAction('status', 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')
         .addOption(schemaOption)
-        .addOption(
-            new Option('--accept-data-loss', 'ignore data loss warnings')
-        )
-        .addOption(
-            new Option(
-                '--force-reset',
-                'force a reset of the database before push'
-            )
-        )
+        .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 and related packages.')
         .argument('[path]', 'project path', '.')
         .action(infoAction);
 
@@ -131,8 +120,23 @@ export function createProgram() {
         .argument('[path]', 'project path', '.')
         .action(initAction);
 
+    program.command('validate').description('Validate a ZModel schema.').addOption(schemaOption).action(validateAction);
+
     return program;
 }
 
 const program = createProgram();
-program.parse(process.argv);
+
+program.parseAsync().catch((err) => {
+    if (err instanceof CliError) {
+        console.error(colors.red(err.message));
+        process.exit(1);
+    } else if (err instanceof CommanderError) {
+        // errors are already reported, just exit
+        process.exit(err.exitCode);
+    } else {
+        console.error(colors.red('An unexpected error occurred:'));
+        console.error(err);
+        process.exit(1);
+    }
+});

package/src/utils/exec-utils.ts

@@ -3,10 +3,7 @@ import { execSync as _exec, type ExecSyncOptions } from 'child_process';
 /**
  * Utility for executing command synchronously and prints outputs on current console
  */
-export function execSync(
-    cmd: string,
-    options?: Omit<ExecSyncOptions, 'env'> & { env?: Record<string, string> }
-): void {
+export function execSync(cmd: string, options?: Omit<ExecSyncOptions, 'env'> & { env?: Record<string, string> }): void {
     const { env, ...restOptions } = options ?? {};
     const mergedEnv = env ? { ...process.env, ...env } : undefined;
     _exec(cmd, {
@@ -22,7 +19,7 @@ export function execSync(
  */
 export function execPackage(
     cmd: string,
-    options?: Omit<ExecSyncOptions, 'env'> & { env?: Record<string, string> }
+    options?: Omit<ExecSyncOptions, 'env'> & { env?: Record<string, string> },
 ): void {
     const packageManager = process?.versions?.['bun'] ? 'bunx' : 'npx';
     execSync(`${packageManager} ${cmd}`, options);

package/src/utils/version-utils.ts

@@ -1,13 +1,13 @@
-/* eslint-disable @typescript-eslint/no-var-requires */
-export function getVersion(): string | undefined {
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function getVersion() {
     try {
-        return require('../package.json').version;
+        // isomorphic __dirname
+        const _dirname = typeof __dirname !== 'undefined' ? __dirname : path.dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(fs.readFileSync(path.join(_dirname, '../package.json'), 'utf8')).version;
     } catch {
-        try {
-            // dev environment
-            return require('../../package.json').version;
-        } catch {
-            return undefined;
-        }
+        return undefined;
     }
 }

package/test/db.test.ts

@@ -0,0 +1,18 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createProject, runCli } from './utils';
+
+const model = `
+model User {
+    id String @id @default(cuid())
+}
+`;
+
+describe('CLI db commands test', () => {
+    it('should generate a database with db push', () => {
+        const workDir = createProject(model);
+        runCli('db push', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/dev.db'))).toBe(true);
+    });
+});

package/test/generate.test.ts

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createProject, runCli } from './utils';
+
+const model = `
+model User {
+    id String @id @default(cuid())
+}
+`;
+
+describe('CLI generate command test', () => {
+    it('should generate a TypeScript schema', () => {
+        const workDir = createProject(model);
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.ts'))).toBe(true);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.prisma'))).toBe(false);
+    });
+
+    it('should respect custom output directory', () => {
+        const workDir = createProject(model);
+        runCli('generate --output ./zen', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zen/schema.ts'))).toBe(true);
+    });
+
+    it('should respect custom schema location', () => {
+        const workDir = createProject(model);
+        fs.renameSync(path.join(workDir, 'zenstack/schema.zmodel'), path.join(workDir, 'zenstack/foo.zmodel'));
+        runCli('generate --schema ./zenstack/foo.zmodel', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.ts'))).toBe(true);
+    });
+
+    it('should respect save prisma schema option', () => {
+        const workDir = createProject(model);
+        runCli('generate --save-prisma-schema', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.prisma'))).toBe(true);
+    });
+
+    it('should respect save prisma schema custom path option', () => {
+        const workDir = createProject(model);
+        runCli('generate --save-prisma-schema "../prisma/schema.prisma"', workDir);
+        expect(fs.existsSync(path.join(workDir, 'prisma/schema.prisma'))).toBe(true);
+    });
+
+    it('should respect package.json config', () => {
+        const workDir = createProject(model);
+        fs.mkdirSync(path.join(workDir, 'foo'));
+        fs.renameSync(path.join(workDir, 'zenstack/schema.zmodel'), path.join(workDir, 'foo/schema.zmodel'));
+        fs.rmdirSync(path.join(workDir, 'zenstack'));
+        const pkgJson = JSON.parse(fs.readFileSync(path.join(workDir, 'package.json'), 'utf8'));
+        pkgJson.zenstack = {
+            schema: './foo/schema.zmodel',
+            output: './bar',
+        };
+        fs.writeFileSync(path.join(workDir, 'package.json'), JSON.stringify(pkgJson, null, 2));
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'bar/schema.ts'))).toBe(true);
+    });
+});

package/test/init.test.ts

@@ -0,0 +1,13 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import tmp from 'tmp';
+import { describe, expect, it } from 'vitest';
+import { runCli } from './utils';
+
+describe('Cli init command tests', () => {
+    it('should create a new project', () => {
+        const { name: workDir } = tmp.dirSync({ unsafeCleanup: true });
+        runCli('init', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.zmodel'))).toBe(true);
+    });
+});

package/test/migrate.test.ts

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createProject, runCli } from './utils';
+
+const model = `
+model User {
+    id String @id @default(cuid())
+}
+`;
+
+describe('CLI migrate commands test', () => {
+    it('should generate a database with migrate dev', () => {
+        const workDir = createProject(model);
+        runCli('migrate dev --name init', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/dev.db'))).toBe(true);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/migrations'))).toBe(true);
+    });
+
+    it('should reset the database with migrate reset', () => {
+        const workDir = createProject(model);
+        runCli('db push', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/dev.db'))).toBe(true);
+        runCli('migrate reset --force', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/dev.db'))).toBe(true);
+    });
+
+    it('should reset the database with migrate deploy', () => {
+        const workDir = createProject(model);
+        runCli('migrate dev --name init', workDir);
+        fs.rmSync(path.join(workDir, 'zenstack/dev.db'));
+        runCli('migrate deploy', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/dev.db'))).toBe(true);
+    });
+
+    it('supports migrate status', () => {
+        const workDir = createProject(model);
+        runCli('migrate dev --name init', workDir);
+        runCli('migrate status', workDir);
+    });
+});