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

package/src/telemetry.ts

@@ -0,0 +1,139 @@
+import { init, type Mixpanel } from 'mixpanel';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import * as os from 'os';
+import { TELEMETRY_TRACKING_TOKEN } from './constants';
+import { isInCi } from './utils/is-ci';
+import { isInContainer } from './utils/is-container';
+import isDocker from './utils/is-docker';
+import { isWsl } from './utils/is-wsl';
+import { getMachineId } from './utils/machine-id-utils';
+import { getVersion } from './utils/version-utils';
+
+/**
+ * Telemetry events
+ */
+export type TelemetryEvents =
+    | 'cli:start'
+    | 'cli:complete'
+    | 'cli:error'
+    | 'cli:command:start'
+    | 'cli:command:complete'
+    | 'cli:command:error'
+    | 'cli:plugin:start'
+    | 'cli:plugin:complete'
+    | 'cli:plugin:error';
+
+/**
+ * Utility class for sending telemetry
+ */
+export class Telemetry {
+    private readonly mixpanel: Mixpanel | undefined;
+    private readonly hostId = getMachineId();
+    private readonly sessionid = randomUUID();
+    private readonly _os_type = os.type();
+    private readonly _os_release = os.release();
+    private readonly _os_arch = os.arch();
+    private readonly _os_version = os.version();
+    private readonly _os_platform = os.platform();
+    private readonly version = getVersion();
+    private readonly prismaVersion = this.getPrismaVersion();
+    private readonly isDocker = isDocker();
+    private readonly isWsl = isWsl();
+    private readonly isContainer = isInContainer();
+    private readonly isCi = isInCi;
+
+    constructor() {
+        if (process.env['DO_NOT_TRACK'] !== '1' && TELEMETRY_TRACKING_TOKEN) {
+            this.mixpanel = init(TELEMETRY_TRACKING_TOKEN, {
+                geolocate: true,
+            });
+        }
+    }
+
+    get isTracking() {
+        return !!this.mixpanel;
+    }
+
+    track(event: TelemetryEvents, properties: Record<string, unknown> = {}) {
+        if (this.mixpanel) {
+            const payload = {
+                distinct_id: this.hostId,
+                session: this.sessionid,
+                time: new Date(),
+                $os: this._os_type,
+                osType: this._os_type,
+                osRelease: this._os_release,
+                osPlatform: this._os_platform,
+                osArch: this._os_arch,
+                osVersion: this._os_version,
+                nodeVersion: process.version,
+                version: this.version,
+                prismaVersion: this.prismaVersion,
+                isDocker: this.isDocker,
+                isWsl: this.isWsl,
+                isContainer: this.isContainer,
+                isCi: this.isCi,
+                ...properties,
+            };
+            this.mixpanel.track(event, payload);
+        }
+    }
+
+    trackError(err: Error) {
+        this.track('cli:error', {
+            message: err.message,
+            stack: err.stack,
+        });
+    }
+
+    async trackSpan<T>(
+        startEvent: TelemetryEvents,
+        completeEvent: TelemetryEvents,
+        errorEvent: TelemetryEvents,
+        properties: Record<string, unknown>,
+        action: () => Promise<T> | T,
+    ) {
+        this.track(startEvent, properties);
+        const start = Date.now();
+        let success = true;
+        try {
+            return await action();
+        } catch (err: any) {
+            this.track(errorEvent, {
+                message: err.message,
+                stack: err.stack,
+                ...properties,
+            });
+            success = false;
+            throw err;
+        } finally {
+            this.track(completeEvent, {
+                duration: Date.now() - start,
+                success,
+                ...properties,
+            });
+        }
+    }
+
+    async trackCommand(command: string, action: () => Promise<void> | void) {
+        await this.trackSpan('cli:command:start', 'cli:command:complete', 'cli:command:error', { command }, action);
+    }
+
+    async trackCli(action: () => Promise<void> | void) {
+        await this.trackSpan('cli:start', 'cli:complete', 'cli:error', {}, action);
+    }
+
+    getPrismaVersion() {
+        try {
+            const packageJsonPath = import.meta.resolve('prisma/package.json');
+            const packageJsonUrl = new URL(packageJsonPath);
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonUrl, 'utf8'));
+            return packageJson.version;
+        } catch {
+            return undefined;
+        }
+    }
+}
+
+export const telemetry = new Telemetry();

package/src/utils/is-ci.ts

@@ -0,0 +1,5 @@
+import { env } from 'node:process';
+export const isInCi =
+    env['CI'] !== '0' &&
+    env['CI'] !== 'false' &&
+    ('CI' in env || 'CONTINUOUS_INTEGRATION' in env || Object.keys(env).some((key) => key.startsWith('CI_')));

package/src/utils/is-container.ts

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import isDocker from './is-docker';
+
+let cachedResult: boolean | undefined;
+
+// Podman detection
+const hasContainerEnv = () => {
+    try {
+        fs.statSync('/run/.containerenv');
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+export function isInContainer() {
+    // TODO: Use `??=` when targeting Node.js 16.
+    if (cachedResult === undefined) {
+        cachedResult = hasContainerEnv() || isDocker();
+    }
+
+    return cachedResult;
+}

package/src/utils/is-docker.ts

@@ -0,0 +1,31 @@
+// Copied over from https://github.com/sindresorhus/is-docker for CJS compatibility
+
+import fs from 'node:fs';
+
+let isDockerCached: boolean | undefined;
+
+function hasDockerEnv() {
+    try {
+        fs.statSync('/.dockerenv');
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function hasDockerCGroup() {
+    try {
+        return fs.readFileSync('/proc/self/cgroup', 'utf8').includes('docker');
+    } catch {
+        return false;
+    }
+}
+
+export default function isDocker() {
+    // TODO: Use `??=` when targeting Node.js 16.
+    if (isDockerCached === undefined) {
+        isDockerCached = hasDockerEnv() || hasDockerCGroup();
+    }
+
+    return isDockerCached;
+}

package/src/utils/is-wsl.ts

@@ -0,0 +1,18 @@
+import process from 'node:process';
+import os from 'node:os';
+import fs from 'node:fs';
+export const isWsl = () => {
+    if (process.platform !== 'linux') {
+        return false;
+    }
+
+    if (os.release().toLowerCase().includes('microsoft')) {
+        return true;
+    }
+
+    try {
+        return fs.readFileSync('/proc/version', 'utf8').toLowerCase().includes('microsoft');
+    } catch {
+        return false;
+    }
+};

package/src/utils/machine-id-utils.ts

@@ -0,0 +1,76 @@
+// modified from https://github.com/automation-stack/node-machine-id
+
+import { execSync } from 'child_process';
+import { createHash, randomUUID } from 'node:crypto';
+
+const { platform } = process;
+const win32RegBinPath = {
+    native: '%windir%\\System32',
+    mixed: '%windir%\\sysnative\\cmd.exe /c %windir%\\System32',
+};
+const guid = {
+    darwin: 'ioreg -rd1 -c IOPlatformExpertDevice',
+    win32:
+        `${win32RegBinPath[isWindowsProcessMixedOrNativeArchitecture()]}\\REG.exe ` +
+        'QUERY HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Cryptography ' +
+        '/v MachineGuid',
+    linux: '( cat /var/lib/dbus/machine-id /etc/machine-id 2> /dev/null || hostname 2> /dev/null) | head -n 1 || :',
+    freebsd: 'kenv -q smbios.system.uuid || sysctl -n kern.hostuuid',
+};
+
+function isWindowsProcessMixedOrNativeArchitecture() {
+    // eslint-disable-next-line no-prototype-builtins
+    if (process.arch === 'ia32' && process.env.hasOwnProperty('PROCESSOR_ARCHITEW6432')) {
+        return 'mixed';
+    }
+    return 'native';
+}
+
+function hash(guid: string): string {
+    return createHash('sha256').update(guid).digest('hex');
+}
+
+function expose(result: string): string | undefined {
+    switch (platform) {
+        case 'darwin':
+            return result
+                .split('IOPlatformUUID')[1]
+                ?.split('\n')[0]
+                ?.replace(/=|\s+|"/gi, '')
+                .toLowerCase();
+        case 'win32':
+            return result
+                .toString()
+                .split('REG_SZ')[1]
+                ?.replace(/\r+|\n+|\s+/gi, '')
+                .toLowerCase();
+        case 'linux':
+            return result
+                .toString()
+                .replace(/\r+|\n+|\s+/gi, '')
+                .toLowerCase();
+        case 'freebsd':
+            return result
+                .toString()
+                .replace(/\r+|\n+|\s+/gi, '')
+                .toLowerCase();
+        default:
+            throw new Error(`Unsupported platform: ${process.platform}`);
+    }
+}
+
+export function getMachineId() {
+    if (!(platform in guid)) {
+        return randomUUID();
+    }
+    try {
+        const value = execSync(guid[platform as keyof typeof guid]);
+        const id = expose(value.toString());
+        if (!id) {
+            return randomUUID();
+        }
+        return hash(id);
+    } catch {
+        return randomUUID();
+    }
+}

package/src/utils/version-utils.ts

@@ -1,6 +1,11 @@
+import colors from 'colors';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+
+const CHECK_VERSION_TIMEOUT = 2000;
+const VERSION_CHECK_TAG = 'next';
 
 export function getVersion() {
     try {
@@ -11,3 +16,35 @@ export function getVersion() {
         return undefined;
     }
 }
+
+export async function checkNewVersion() {
+    const currVersion = getVersion();
+    let latestVersion: string;
+    try {
+        latestVersion = await getLatestVersion();
+    } catch {
+        // noop
+        return;
+    }
+
+    if (latestVersion && currVersion && semver.gt(latestVersion, currVersion)) {
+        console.log(`A newer version ${colors.cyan(latestVersion)} is available.`);
+    }
+}
+
+export async function getLatestVersion() {
+    const fetchResult = await fetch(`https://registry.npmjs.org/@zenstackhq/cli/${VERSION_CHECK_TAG}`, {
+        headers: { accept: 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*' },
+        signal: AbortSignal.timeout(CHECK_VERSION_TIMEOUT),
+    });
+
+    if (fetchResult.ok) {
+        const data: any = await fetchResult.json();
+        const latestVersion = data?.version;
+        if (typeof latestVersion === 'string' && semver.valid(latestVersion)) {
+            return latestVersion;
+        }
+    }
+
+    throw new Error('invalid npm registry response');
+}

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

@@ -30,15 +30,18 @@ describe('CLI generate command test', () => {
         expect(fs.existsSync(path.join(workDir, 'zenstack/schema.ts'))).toBe(true);
     });
 
-    it('should respect save prisma schema option', () => {
+    it('should respect package.json config', () => {
         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);
+        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/migrate.test.ts

@@ -38,4 +38,35 @@ describe('CLI migrate commands test', () => {
         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);
+    });
+});