Merge remote-tracking branch 'origin/dev' into chore/bump-beta

Author: ymc9

.github/workflows/build-test.yml

@@ -6,6 +6,10 @@ on:
             - main
             - dev
 
+env:
+    TELEMETRY_TRACKING_TOKEN: ${{ secrets.TELEMETRY_TRACKING_TOKEN }}
+    DO_NOT_TRACK: '1'
+
 permissions:
     contents: read
 

packages/cli/package.json

@@ -35,15 +35,18 @@
         "colors": "1.4.0",
         "commander": "^8.3.0",
         "langium": "catalog:",
+        "mixpanel": "^0.18.1",
         "ora": "^5.4.1",
         "package-manager-detector": "^1.3.0",
+        "semver": "^7.7.2",
         "ts-pattern": "catalog:"
     },
     "peerDependencies": {
         "prisma": "catalog:"
     },
     "devDependencies": {
         "@types/better-sqlite3": "^7.6.13",
+        "@types/semver": "^7.7.0",
         "@types/tmp": "catalog:",
         "@zenstackhq/eslint-config": "workspace:*",
         "@zenstackhq/runtime": "workspace:*",

packages/cli/src/actions/generate.ts

@@ -39,7 +39,9 @@ import { schema } from '${outputPath}/schema';
 const client = new ZenStackClient(schema, {
     dialect: { ... }
 });
-\`\`\``);
+\`\`\`
+
+Check documentation: https://zenstack.dev/docs/3.x`);
     }
 }
 

packages/cli/src/actions/info.ts

@@ -57,12 +57,15 @@ 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 };
             }
         }),
     );
 
-    return result;
+    return result.filter((p) => !!p);
 }

packages/cli/src/constants.ts

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

packages/cli/src/index.ts

@@ -3,33 +3,34 @@ import colors from 'colors';
 import { Command, CommanderError, Option } from 'commander';
 import * as actions from './actions';
 import { CliError } from './cli-error';
-import { getVersion } from './utils/version-utils';
+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));
 };
 
 const checkAction = async (options: Parameters<typeof actions.check>[0]): Promise<void> => {
-    await actions.check(options);
+    await telemetry.trackCommand('check', () => actions.check(options));
 };
 
-export function createProgram() {
+function createProgram() {
     const program = new Command('zen');
 
     program.version(getVersion()!, '-v --version', 'display CLI version');
@@ -50,10 +51,13 @@ export function createProgram() {
         `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 plugins.')
         .addOption(schemaOption)
+        .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);
@@ -64,6 +68,7 @@ export function createProgram() {
     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)
@@ -75,26 +80,30 @@ export function createProgram() {
         .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)
+        .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'))
@@ -107,6 +116,7 @@ export function createProgram() {
         .command('push')
         .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));
@@ -115,35 +125,64 @@ export function createProgram() {
         .command('info')
         .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();
+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;
+        }
+    }
 
-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);
+    if (telemetry.isTracking) {
+        // give telemetry a chance to send events before exit
+        setTimeout(() => {
+            process.exit(exitCode);
+        }, 200);
     } else {
-        console.error(colors.red('An unexpected error occurred:'));
-        console.error(err);
-        process.exit(1);
+        process.exit(exitCode);
     }
-});
+}
+
+main();

packages/cli/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();

packages/cli/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_')));