dbdiagram 0.2.0 → 0.3.0

package/README.md

@@ -181,6 +181,19 @@ yarn build      # compile to dist/
 yarn start      # run compiled output
 ```
 
+### Telemetry in development
+
+Copy `.env.example` to `.env`. Its defaults point telemetry at a local collector
+(`TRACKING_COLLECTOR_URL=http://localhost:9090`) and tag events with a non-production app id (`TRACKING_APP_ID=dbdiagram-cli-test`), so development never writes to production analytics.
+
+To disable tracking entirely, point the collector at a local address with nothing listening:
+
+```sh
+TRACKING_COLLECTOR_URL=http://localhost:9090 yarn dev push ...
+```
+
+Sends fail silently (the CLI never retries and never surfaces telemetry errors), so no events leave your machine. To instead inspect what would be sent, run [Snowplow Micro](https://docs.snowplow.io/docs/data-product-studio/data-quality/snowplow-micro/) on that port and read `curl localhost:9090/micro/good` (passed validation) and `/micro/bad` (failed).
+
 ## Test
 
 ```sh

package/dist/actions/build/build-document.action.js

@@ -6,6 +6,7 @@ import { DOCUMENT_SOURCE_TYPE } from '../../constants/document.constant.js';
 import { AUTH_NOT_LOGGED_IN, DBML_PARSE_ERROR, FILE_READ_ERROR, PROJECT_NAME_INVALID, PROJECT_NAME_MISSING, SOURCE_MISSING, VERSION_NAME_INVALID, WORKSPACE_NAME_INVALID, WORKSPACE_NAME_MISSING, } from '../../constants/cli-error.constant.js';
 import { CliError } from '../../errors/cli.error.js';
 import { portalIntegration } from '../../integrations/portal/portal.integration.js';
+import { trackEvent } from '../../services/telemetry.service.js';
 import { prepareBuildDocumentData } from '../../services/dbml/dbml.service.js';
 import { getCliErrorMessageFromCode, toCliError } from '../../utils/cli-error.util.js';
 import { formatDbmlError, getDbmlVersion } from '../../utils/dbml.util.js';
@@ -88,6 +89,7 @@ export async function documentAction(options) {
     const s = spinner();
     s.start('Building document on dbdocs...');
     try {
+        const currentUser = await portalIntegration.getCurrentUser();
         const { project } = await portalIntegration.createDocument({
             projectName: options.projectUrlOrName,
             projectDescription: preparedDocumentData.description,
@@ -101,10 +103,16 @@ export async function documentAction(options) {
             normalizedDatabase: preparedDocumentData.normalizedDatabase,
             dbmlVersion: getDbmlVersion(),
         });
-        const url = `${DBDOCS_CONFIGS.baseUrl}/${project.workspaceUrl}/${project.urlName}`;
+        const { workspaceUrl: workspaceUrlName, urlName: projectUrlName } = project;
+        trackEvent({
+            name: 'cli_document_build',
+            properties: { workspaceUrlName, projectUrlName },
+            userId: currentUser.id.toString(),
+        });
+        const url = `${DBDOCS_CONFIGS.baseUrl}/${workspaceUrlName}/${projectUrlName}`;
         if (options.json) {
             s.stop();
-            printJson({ projectUrlName: `${project.workspaceUrl}/${project.urlName}`, url });
+            printJson({ projectUrlName: `${workspaceUrlName}/${projectUrlName}`, url });
         }
         else {
             s.stop(`Document built successfully. Visit: ${url}`);

package/dist/actions/push.action.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { spinner } from '@clack/prompts';
 import { getCredential } from '../config/credential-manager.js';
 import { portalIntegration } from '../integrations/portal/portal.integration.js';
+import { trackEvent } from '../services/telemetry.service.js';
 import { deriveDiagramVizPathFromDBML, readDiagramVizFile } from '../services/viz/diagram-viz-file.service.js';
 import { toServerFormat } from '../services/viz/diagram-viz-converter.service.js';
 import { preparePushDiagramData } from '../services/dbml/dbml.service.js';
@@ -49,16 +50,27 @@ export async function pushAction(filepath, options, thisCommand) {
     const s = spinner();
     s.start('Pushing diagram to dbdiagram...');
     try {
+        const currentUser = await portalIntegration.getCurrentUser();
         let diagramId;
         if (!options.new && options.diagramId) {
             ({ diagramId } = await portalIntegration.updateDiagram({
                 diagramId: options.diagramId, name: options.name, dbml, vizData,
             }));
+            trackEvent({
+                name: 'cli_diagram_push',
+                properties: { action: 'update', diagramId, workspaceId: options.workspace ?? null },
+                userId: currentUser.id.toString(),
+            });
         }
         else {
             ({ diagramId } = await portalIntegration.createDiagram({
                 name: options.name, dbml, workspaceId: options.workspace, vizData,
             }));
+            trackEvent({
+                name: 'cli_diagram_push',
+                properties: { action: 'create', diagramId, workspaceId: options.workspace ?? null },
+                userId: currentUser.id.toString(),
+            });
         }
         const diagramUrl = `${DBDIAGRAM_CONFIGS.baseUrl}/d/${diagramId}`;
         if (options.json) {

package/dist/commands/auth/auth.command.js

@@ -8,7 +8,7 @@ export function registerAuthCommand(program) {
         .addHelpText('after', '\nAlternatively, set the DBDIAGRAM_TOKEN env var to authenticate with a\n' +
         'CLI token (see: dbdiagram tokens generate).')
         .action(() => {
-        auth.help();
+        auth.outputHelp();
     });
     registerLoginCommand(auth);
     registerLogoutCommand(auth);

package/dist/commands/build/build.command.js

@@ -4,7 +4,7 @@ export function registerBuildCommand(program) {
         .command('build')
         .description('Publish documentation to dbdocs.io')
         .action(() => {
-        build.help();
+        build.outputHelp();
     });
     registerDocumentCommand(build);
 }

package/dist/commands/tokens/tokens.command.js

@@ -7,7 +7,7 @@ export function registerTokensCommand(program) {
         .description('Manage your CLI tokens')
         .addHelpText('after', '\nSet a token value as DBDIAGRAM_TOKEN env var to authenticate without browser login.')
         .action(() => {
-        tokens.help();
+        tokens.outputHelp();
     });
     registerTokenGenerateCommand(tokens);
     registerTokenListCommand(tokens);

package/dist/config/credential-manager.js

@@ -1,40 +1,27 @@
 import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { DOT_DBDIAGRAM_DIR, CREDENTIALS_FILE_NAME } from '../constants/dot-dbdiagram-dir.constant.js';
+import { getGlobalCredentialsFilePath, getGlobalDir, getProjectCredentialsFilePath, readAndParseJsonFileSafe, } from '../utils/file.util.js';
 let cachedCredential = null;
-function readJsonSafe(filePath) {
-    try {
-        const contents = fs.readFileSync(filePath, 'utf8');
-        return JSON.parse(contents);
-    }
-    catch {
-        return null;
-    }
-}
 export function resolveCredential() {
     if (process.env.DBDIAGRAM_TOKEN) {
         cachedCredential = { token: process.env.DBDIAGRAM_TOKEN };
         return cachedCredential;
     }
-    const projectPath = path.join(process.cwd(), DOT_DBDIAGRAM_DIR, CREDENTIALS_FILE_NAME);
-    const projectCred = readJsonSafe(projectPath);
-    if (projectCred && typeof projectCred.token === 'string') {
-        cachedCredential = { token: projectCred.token };
+    const projectCredential = readAndParseJsonFileSafe(getProjectCredentialsFilePath());
+    if (projectCredential && typeof projectCredential.token === 'string') {
+        cachedCredential = { token: projectCredential.token };
         return cachedCredential;
     }
-    const userPath = path.join(os.homedir(), DOT_DBDIAGRAM_DIR, CREDENTIALS_FILE_NAME);
-    const userCred = readJsonSafe(userPath);
-    if (userCred && typeof userCred.token === 'string') {
-        cachedCredential = { token: userCred.token };
+    const globalCredential = readAndParseJsonFileSafe(getGlobalCredentialsFilePath());
+    if (globalCredential && typeof globalCredential.token === 'string') {
+        cachedCredential = { token: globalCredential.token };
         return cachedCredential;
     }
     cachedCredential = null;
     return null;
 }
 export function storeCredential(token) {
-    const dir = path.join(os.homedir(), DOT_DBDIAGRAM_DIR);
-    const filePath = path.join(dir, CREDENTIALS_FILE_NAME);
+    const dir = getGlobalDir();
+    const filePath = getGlobalCredentialsFilePath();
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(filePath, JSON.stringify({ token }, null, 2), { mode: 0o600 });
     cachedCredential = { token };
@@ -46,7 +33,7 @@ export function getAccessToken() {
     return cachedCredential?.token ?? null;
 }
 export function clearCredential() {
-    const filePath = path.join(os.homedir(), DOT_DBDIAGRAM_DIR, CREDENTIALS_FILE_NAME);
+    const filePath = getGlobalCredentialsFilePath();
     fs.rmSync(filePath, { force: true });
     cachedCredential = null;
 }

package/dist/config/settings-manager.js

@@ -1,12 +1,8 @@
 import fs from 'node:fs';
-import path from 'node:path';
-import { DOT_DBDIAGRAM_DIR, SETTINGS_FILE_NAME } from '../constants/dot-dbdiagram-dir.constant.js';
+import { getProjectDir, getSettingsFilePath, readAndParseJsonFileSafe } from '../utils/file.util.js';
 let cachedSettings = null;
-function settingsPath() {
-    return path.join(process.cwd(), DOT_DBDIAGRAM_DIR, SETTINGS_FILE_NAME);
-}
 export function settingsExists() {
-    return fs.existsSync(settingsPath());
+    return fs.existsSync(getSettingsFilePath());
 }
 export function defaultSettings() {
     return {
@@ -15,30 +11,17 @@ export function defaultSettings() {
         document: { source: 'file', workspaceUrlName: '', projectUrlName: '' },
     };
 }
-export function readSettings() {
-    try {
-        const contents = fs.readFileSync(settingsPath(), 'utf8');
-        return JSON.parse(contents);
-    }
-    catch {
-        return null;
-    }
-}
-export function writeSettings(data) {
-    const dir = path.join(process.cwd(), DOT_DBDIAGRAM_DIR);
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(settingsPath(), JSON.stringify(data, null, 2), 'utf8');
+export const readSettings = () => {
+    return readAndParseJsonFileSafe(getSettingsFilePath());
+};
+export const writeSettings = (data) => {
+    fs.mkdirSync(getProjectDir(), { recursive: true });
+    fs.writeFileSync(getSettingsFilePath(), JSON.stringify(data, null, 2), 'utf8');
     cachedSettings = data;
-}
-export function resolveSettings() {
-    try {
-        const contents = fs.readFileSync(settingsPath(), 'utf8');
-        cachedSettings = JSON.parse(contents);
-    }
-    catch {
-        cachedSettings = null;
-    }
-}
-export function getSettings() {
+};
+export const resolveSettings = () => {
+    cachedSettings = readAndParseJsonFileSafe(getSettingsFilePath());
+};
+export const getSettings = () => {
     return cachedSettings;
-}
+};

package/dist/config.js

@@ -12,3 +12,7 @@ export const DBDIAGRAM_CONFIGS = {
 export const DBDOCS_CONFIGS = {
     baseUrl: process.env.DBDOCS_BASE_URL || 'https://dbdocs.io',
 };
+export const TELEMETRY_CONFIGS = {
+    collectorUrl: process.env.TRACKING_COLLECTOR_URL || 'https://snowplow.holistics.io',
+    appId: process.env.TRACKING_APP_ID || 'dbdiagram-cli',
+};

package/dist/constants/dot-dbdiagram-dir.constant.js

@@ -7,3 +7,4 @@ export const DIAGRAM_VIZ_FILE_VERSIONS = {
     v1: '1.0.0',
     v2: '2.0.0',
 };
+export const TELEMETRY_FILE_NAME = 'telemetry.json';

package/dist/hooks/global.hook.js

@@ -1,6 +1,13 @@
 import { resolveCredential } from '../config/credential-manager.js';
 import { resolveSettings } from '../config/settings-manager.js';
-export function globalPreAction(_thisCommand, _actionCommand) {
+import { flushTelemetry, initTelemetry, trackEvent } from '../services/telemetry.service.js';
+import { resolveCommandName } from '../utils/command-name.util.js';
+export function globalPreAction(_thisCommand, actionCommand) {
     resolveCredential();
     resolveSettings();
+    initTelemetry();
+    trackEvent({ name: 'cli_command_run', properties: { command: resolveCommandName(actionCommand) } });
+}
+export function globalPostAction() {
+    flushTelemetry();
 }

package/dist/index.js

@@ -1,12 +1,32 @@
 #!/usr/bin/env node
 import 'dotenv/config';
+import { CommanderError } from 'commander';
 import { load } from './commands/command.loader.js';
 import { createProgram } from './program.js';
-import { globalPreAction } from './hooks/global.hook.js';
+import { globalPostAction, globalPreAction } from './hooks/global.hook.js';
+import { flushTelemetry, initTelemetry, trackEvent } from './services/telemetry.service.js';
+const getAttemptedCommand = () => {
+    const operands = process.argv.slice(2).filter((arg) => !arg.startsWith('-'));
+    return operands.length ? operands.join(' ') : 'unknown';
+};
 const bootstrap = async () => {
     const program = createProgram();
     load(program);
     program.hook('preAction', globalPreAction);
-    await program.parseAsync(process.argv);
+    program.hook('postAction', globalPostAction);
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        if (!(error instanceof CommanderError))
+            throw error;
+        if (error.code === 'commander.unknownCommand' ||
+            error.code === 'commander.excessArguments') {
+            initTelemetry();
+            trackEvent({ name: 'cli_command_run', properties: { command: getAttemptedCommand() } });
+            flushTelemetry();
+        }
+        process.exitCode = error.exitCode;
+    }
 };
 bootstrap();

package/dist/integrations/telemetry/telemetry.integration.js

@@ -0,0 +1,77 @@
+import { buildSelfDescribingEvent, newTracker } from '@snowplow/node-tracker';
+import { TELEMETRY_CONFIGS } from '../../config.js';
+export const constructSnowplowSchemaUrl = (name, version = '1-0-0') => `iglu:io.dbdiagram/${name}/jsonschema/${version}`;
+let tracker;
+export const getTracker = () => {
+    if (tracker)
+        return tracker;
+    tracker = newTracker({
+        namespace: 'cli',
+        appId: TELEMETRY_CONFIGS.appId,
+        encodeBase64: true,
+    }, {
+        endpoint: TELEMETRY_CONFIGS.collectorUrl,
+        eventMethod: 'post',
+        bufferSize: 1,
+        retryFailedRequests: false,
+        onRequestFailure: () => { },
+        onRequestSuccess() { },
+    });
+    return tracker;
+};
+export const toEventData = (event) => {
+    const { name, properties } = event;
+    switch (name) {
+        case 'cli_command_run':
+            return { command: properties.command };
+        case 'cli_diagram_push': {
+            const { action, diagramId, workspaceId } = properties;
+            return {
+                action,
+                diagram_id: diagramId,
+                workspace_id: workspaceId,
+            };
+        }
+        case 'cli_document_build': {
+            const { workspaceUrlName, projectUrlName } = properties;
+            return {
+                workspace_url_name: workspaceUrlName,
+                project_url_name: projectUrlName,
+            };
+        }
+    }
+};
+export const toClientContextEntity = (client) => ({
+    schema: constructSnowplowSchemaUrl('cli_client_context'),
+    data: {
+        device_id: client.deviceId,
+        invocation_id: client.invocationId,
+        cli_version: client.cliVersion,
+        node_version: client.nodeVersion,
+        os: client.os,
+        arch: client.arch,
+        actor: client.actor,
+        ...(client.agentName ? { agent_name: client.agentName } : {}),
+        environment: client.environment,
+    },
+});
+export const toUserContextEntity = (userId) => ({
+    schema: constructSnowplowSchemaUrl('cli_user_context'),
+    data: { user_id: userId },
+});
+export const send = (events, client) => {
+    const tracker = getTracker();
+    const clientContextEntity = toClientContextEntity(client);
+    for (const event of events) {
+        const contexts = [clientContextEntity];
+        if ('userId' in event) {
+            contexts.push(toUserContextEntity(event.userId));
+        }
+        tracker.track(buildSelfDescribingEvent({
+            event: { schema: constructSnowplowSchemaUrl(event.name), data: toEventData(event) },
+        }), contexts, { type: 'ttm', value: event.timestamp });
+    }
+};
+export const telemetryIntegration = {
+    send,
+};

package/dist/program.js

@@ -9,8 +9,9 @@ export function createProgram() {
         .helpOption('-h, --help', 'Show help information')
         .enablePositionalOptions(true)
         .action(() => {
-        program.help();
+        program.outputHelp();
     })
         .showHelpAfterError(true);
+    program.exitOverride();
     return program;
 }

package/dist/services/telemetry.service.js

@@ -0,0 +1,59 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import packageJson from '../../package.json' with { type: 'json' };
+import { telemetryIntegration } from '../integrations/telemetry/telemetry.integration.js';
+import { detectAgent } from '../utils/agent-detector.util.js';
+import { detectExecuteEnvironment } from '../utils/environment-detector.util.js';
+import { getGlobalDir, getTelemetryFilePath, readAndParseJsonFileSafe } from '../utils/file.util.js';
+const events = [];
+let deviceId;
+let invocationId;
+export const getOrCreateDeviceId = () => {
+    const telemetryFilePath = getTelemetryFilePath();
+    const telemetrySettings = readAndParseJsonFileSafe(telemetryFilePath);
+    if (telemetrySettings && telemetrySettings.deviceId) {
+        return telemetrySettings.deviceId;
+    }
+    const deviceId = crypto.randomUUID();
+    fs.mkdirSync(getGlobalDir(), { recursive: true });
+    fs.writeFileSync(telemetryFilePath, JSON.stringify({ deviceId }, null, 2));
+    return deviceId;
+};
+export const constructCliClientContext = () => {
+    const { actor, agentName } = detectAgent();
+    return {
+        deviceId: deviceId ?? '',
+        invocationId: invocationId ?? '',
+        cliVersion: packageJson.version,
+        nodeVersion: process.versions.node,
+        os: process.platform,
+        arch: process.arch,
+        actor,
+        ...(agentName ? { agentName } : {}),
+        environment: detectExecuteEnvironment(),
+    };
+};
+export const initTelemetry = () => {
+    try {
+        deviceId = getOrCreateDeviceId();
+        invocationId = crypto.randomUUID();
+    }
+    catch {
+    }
+};
+export const trackEvent = (event) => {
+    try {
+        events.push({ ...event, timestamp: Date.now() });
+    }
+    catch {
+    }
+};
+export const flushTelemetry = () => {
+    try {
+        if (!events.length)
+            return;
+        telemetryIntegration.send(events, constructCliClientContext());
+    }
+    catch {
+    }
+};

package/dist/types/telemetry.type.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/agent-detector.util.js

@@ -0,0 +1,27 @@
+const AGENT_ENV_VAR_TO_NAME = {
+    CURSOR_TRACE_ID: 'cursor',
+    CURSOR_AGENT: 'cursor-cli',
+    CURSOR_EXTENSION_HOST_ROLE: 'cursor-cli',
+    GEMINI_CLI: 'gemini',
+    CODEX_SANDBOX: 'codex',
+    CODEX_CI: 'codex',
+    CODEX_THREAD_ID: 'codex',
+    CLAUDECODE: 'claude',
+    CLAUDE_CODE: 'claude',
+    REPL_ID: 'replit',
+    COPILOT_MODEL: 'github-copilot',
+    COPILOT_ALLOW_ALL: 'github-copilot',
+    COPILOT_GITHUB_TOKEN: 'github-copilot',
+    ANTIGRAVITY_AGENT: 'antigravity',
+    AUGMENT_AGENT: 'augment-cli',
+    OPENCODE_CLIENT: 'opencode',
+    OPENCODE: 'opencode',
+};
+export const detectAgent = () => {
+    for (const [envVar, agentName] of Object.entries(AGENT_ENV_VAR_TO_NAME)) {
+        if (process.env[envVar]) {
+            return { actor: 'ai_agent', agentName };
+        }
+    }
+    return { actor: 'human' };
+};

package/dist/utils/command-name.util.js

@@ -0,0 +1,12 @@
+export function resolveCommandName(actionCommand) {
+    const nameSegments = [];
+    let currentCommand = actionCommand;
+    while (currentCommand && currentCommand.parent) {
+        nameSegments.unshift(currentCommand.name());
+        currentCommand = currentCommand.parent;
+    }
+    if (nameSegments.length === 0) {
+        return actionCommand.name();
+    }
+    return nameSegments.join(' ');
+}

package/dist/utils/environment-detector.util.js

@@ -0,0 +1,6 @@
+import { isCI } from 'ci-info';
+export const detectExecuteEnvironment = () => {
+    if (isCI || !process.stdout.isTTY)
+        return 'unattended';
+    return 'interactive';
+};

package/dist/utils/file.util.js

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { DOT_DBDIAGRAM_DIR, CREDENTIALS_FILE_NAME, SETTINGS_FILE_NAME, TELEMETRY_FILE_NAME, } from '../constants/dot-dbdiagram-dir.constant.js';
+export const readAndParseJsonFileSafe = (filePath) => {
+    try {
+        const contents = readFileSync(filePath, 'utf8');
+        return JSON.parse(contents);
+    }
+    catch {
+        return null;
+    }
+};
+export const getProjectDir = () => {
+    return join(process.cwd(), DOT_DBDIAGRAM_DIR);
+};
+export const getGlobalDir = () => {
+    return join(homedir(), DOT_DBDIAGRAM_DIR);
+};
+export const getSettingsFilePath = () => {
+    return join(getProjectDir(), SETTINGS_FILE_NAME);
+};
+export const getProjectCredentialsFilePath = () => {
+    return join(getProjectDir(), CREDENTIALS_FILE_NAME);
+};
+export const getGlobalCredentialsFilePath = () => {
+    return join(getGlobalDir(), CREDENTIALS_FILE_NAME);
+};
+export const getTelemetryFilePath = () => {
+    return join(getGlobalDir(), TELEMETRY_FILE_NAME);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbdiagram",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "main": "dist/index.js",
   "bin": {
     "dbdiagram": "dist/index.js"
@@ -31,7 +31,9 @@
   "dependencies": {
     "@clack/prompts": "^1.4.0",
     "@dbml/core": "8.2.5",
+    "@snowplow/node-tracker": "^4.9.0",
     "axios": "^1.16.1",
+    "ci-info": "^4.4.0",
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",
     "dotenv": "^16.4.0",