@zenstackhq/cli 3.0.0-alpha.3 → 3.0.0-alpha.30

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 checkAction = async (options: Parameters<typeof actions.check>[0]): Promise<void> => {
+    await actions.check(options);
+};
+
 export function createProgram() {
     const program = new Command('zenstack');
 
@@ -36,92 +39,80 @@ 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 the data layer for modern 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 "zenstack/schema.zmodel" unless specified in package.json.`,
     );
 
     program
         .command('generate')
-        .description('Run code generation.')
+        .description('Run code generation plugins.')
         .addOption(schemaOption)
-        .addOption(
-            new Option(
-                '-o, --output <path>',
-                'default output directory for core plugins'
-            )
-        )
+        .addOption(new Option('-o, --output <path>', 'default output directory for code generation'))
         .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(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)
-        .description('check the status of your database migrations.')
+        .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.');
+    migrateCommand
+        .command('resolve')
+        .addOption(schemaOption)
+        .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(
-            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 packages.')
         .argument('[path]', 'project path', '.')
         .action(infoAction);
 
@@ -131,8 +122,27 @@ export function createProgram() {
         .argument('[path]', 'project path', '.')
         .action(initAction);
 
+    program
+        .command('check')
+        .description('Check a ZModel schema for syntax or semantic errors.')
+        .addOption(schemaOption)
+        .action(checkAction);
+
     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/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;

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/check.test.ts

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createProject, runCli } from './utils';
+
+const validModel = `
+model User {
+    id String @id @default(cuid())
+    email String @unique
+    name String?
+    posts Post[]
+}
+
+model Post {
+    id String @id @default(cuid())
+    title String
+    content String?
+    author User @relation(fields: [authorId], references: [id])
+    authorId String
+}
+`;
+
+const invalidModel = `
+model User {
+    id String @id @default(cuid())
+    email String @unique
+    posts Post[]
+}
+
+model Post {
+    id String @id @default(cuid())
+    title String
+    author User @relation(fields: [authorId], references: [id])
+    // Missing authorId field - should cause validation error
+}
+`;
+
+describe('CLI validate command test', () => {
+    it('should validate a valid schema successfully', () => {
+        const workDir = createProject(validModel);
+
+        // Should not throw an error
+        expect(() => runCli('check', workDir)).not.toThrow();
+    });
+
+    it('should fail validation for invalid schema', () => {
+        const workDir = createProject(invalidModel);
+
+        // Should throw an error due to validation failure
+        expect(() => runCli('check', workDir)).toThrow();
+    });
+
+    it('should respect custom schema location', () => {
+        const workDir = createProject(validModel);
+        fs.renameSync(path.join(workDir, 'zenstack/schema.zmodel'), path.join(workDir, 'zenstack/custom.zmodel'));
+
+        // Should not throw an error when using custom schema path
+        expect(() => runCli('check --schema ./zenstack/custom.zmodel', workDir)).not.toThrow();
+    });
+
+    it('should fail when schema file does not exist', () => {
+        const workDir = createProject(validModel);
+
+        // Should throw an error when schema file doesn't exist
+        expect(() => runCli('check --schema ./nonexistent.zmodel', workDir)).toThrow();
+    });
+
+    it('should respect package.json config', () => {
+        const workDir = createProject(validModel);
+        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',
+        };
+        fs.writeFileSync(path.join(workDir, 'package.json'), JSON.stringify(pkgJson, null, 2));
+
+        // Should not throw an error when using package.json config
+        expect(() => runCli('check', workDir)).not.toThrow();
+    });
+
+    it('should validate schema with syntax errors', () => {
+        const modelWithSyntaxError = `
+datasource db {
+    provider = "sqlite"
+    url = "file:./dev.db"
+}
+
+model User {
+    id String @id @default(cuid())
+    email String @unique
+    // Missing closing brace - syntax error
+        `;
+        const workDir = createProject(modelWithSyntaxError, false);
+
+        // Should throw an error due to syntax error
+        expect(() => runCli('check', workDir)).toThrow();
+    });
+});

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,47 @@
+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 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,72 @@
+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);
+    });
+
+    it('supports migrate resolve', () => {
+        const workDir = createProject(model);
+        runCli('migrate dev --name init', workDir);
+
+        // find the migration record "timestamp_init"
+        const migrationRecords = fs.readdirSync(path.join(workDir, 'zenstack/migrations'));
+        const migration = migrationRecords.find((f) => f.endsWith('_init'));
+
+        // force a migration failure
+        fs.writeFileSync(path.join(workDir, 'zenstack/migrations', migration!, 'migration.sql'), 'invalid content');
+
+        // redeploy the migration, which will fail
+        fs.rmSync(path.join(workDir, 'zenstack/dev.db'), { force: true });
+        try {
+            runCli('migrate deploy', workDir);
+        } catch {
+            // noop
+        }
+
+        // --rolled-back
+        runCli(`migrate resolve --rolled-back ${migration}`, workDir);
+
+        // --applied
+        runCli(`migrate resolve --applied ${migration}`, workDir);
+    });
+
+    it('should throw error when neither applied nor rolled-back is provided', () => {
+        const workDir = createProject(model);
+        expect(() => runCli('migrate resolve', workDir)).toThrow();
+    });
+});

package/test/plugins/custom-plugin.test.ts

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createProject, runCli } from '../utils';
+import { execSync } from 'node:child_process';
+
+describe('Custom plugins tests', () => {
+    it('runs custom plugin generator', () => {
+        const workDir = createProject(`
+plugin custom {
+    provider = '../my-plugin.js'
+    output = '../custom-output'
+}
+
+model User {
+    id String @id @default(cuid())
+}
+`);
+
+        fs.writeFileSync(
+            path.join(workDir, 'my-plugin.ts'),
+            `
+import type { CliPlugin } from '@zenstackhq/sdk';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const plugin: CliPlugin = {
+    name: 'Custom Generator',
+    statusText: 'Generating foo.txt',
+    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 });
+            }
+        }
+        fs.writeFileSync(path.join(outDir, 'foo.txt'), 'from my plugin');
+    },
+};
+
+export default plugin;
+`,
+        );
+
+        execSync('npx tsc', { cwd: workDir });
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'custom-output/foo.txt'))).toBe(true);
+    });
+});

package/test/plugins/prisma-plugin.test.ts

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { createProject, runCli } from '../utils';
+
+describe('Core plugins tests', () => {
+    it('can automatically generate a TypeScript schema with default output', () => {
+        const workDir = createProject(`
+model User {
+    id String @id @default(cuid())
+}
+`);
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.ts'))).toBe(true);
+    });
+
+    it('can automatically generate a TypeScript schema with custom output', () => {
+        const workDir = createProject(`
+plugin typescript {
+    provider = '@core/typescript'
+    output = '../generated-schema'
+}
+
+model User {
+    id String @id @default(cuid())
+}
+`);
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'generated-schema/schema.ts'))).toBe(true);
+    });
+
+    it('can generate a Prisma schema with default output', () => {
+        const workDir = createProject(`
+plugin prisma {
+    provider = '@core/prisma'
+}
+
+model User {
+    id String @id @default(cuid())
+}
+`);
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'zenstack/schema.prisma'))).toBe(true);
+    });
+
+    it('can generate a Prisma schema with custom output', () => {
+        const workDir = createProject(`
+plugin prisma {
+    provider = '@core/prisma'
+    output = '../prisma/schema.prisma'
+}
+
+model User {
+    id String @id @default(cuid())
+}
+`);
+        runCli('generate', workDir);
+        expect(fs.existsSync(path.join(workDir, 'prisma/schema.prisma'))).toBe(true);
+    });
+});