dbdiagram 0.1.0

package/COPYRIGHT.md

@@ -0,0 +1,3 @@
+Copyright (C) 2015-present Holistics Software Pte Ltd - All Rights Reserved
+
+The content of this repository is protected by International copyright laws. Unauthorized reproduction and distribution of any part of this repository, via any medium without permission is strictly prohibited.

package/README.md

@@ -0,0 +1,189 @@
+# dbdiagram-cli
+
+A CLI tool for dbdiagram.io.
+
+## Install
+
+```sh
+npm install -g dbdiagram-cli
+# or
+yarn global add dbdiagram-cli
+# or
+pnpm add -g dbdiagram-cli
+```
+
+## Usage
+
+### Authentication
+
+Manage login state for dbdiagram/dbdocs.
+
+**Options:**
+
+- `--json` — Output status as JSON (`auth status` only)
+
+```sh
+dbdiagram auth login            # log in via browser
+dbdiagram auth logout           # clear stored credentials
+dbdiagram auth status           # show who you're logged in as
+```
+
+> **Tip:** Set `DBDIAGRAM_TOKEN=<token>` to authenticate without a browser (see [Tokens](#tokens)).
+
+---
+
+### Init
+
+Creates or updates `.dbdiagram/settings.json` so you don't need to repeat flags on every command.
+
+**Options:**
+
+- `--entry <filepath>` — Path to your DBML entry file
+- `--diagram-id <id>` — Diagram ID (from `dbdiagram.io/d/<id>`)
+- `--workspace <id>` — Workspace ID (omit for personal workspace)
+- `--document-source <mode>` — DBML source for `build document`: `file` or `diagram`
+- `--workspace-url <name>` — dbdocs workspace URL name (from `dbdocs.io/<name>`)
+- `--project-url <name>` — dbdocs project URL name (from `dbdocs.io/<workspace>/<name>`)
+
+```sh
+# set up a diagram project
+dbdiagram init --entry schema.dbml --diagram-id <id>
+
+# set up a dbdocs project
+dbdiagram init --entry schema.dbml --workspace-url myteam --project-url myteam/myproject
+```
+
+---
+
+### Push
+
+Push a local DBML file to create or update a diagram on dbdiagram.io.
+
+**Options:**
+
+- `--name <name>` — Name for the diagram
+- `--diagram-id <id>` — Update an existing diagram (omit to create new)
+- `--workspace <id>` — Create in a specific workspace (ignored when `--diagram-id` is set)
+- `--new` — Force-create a new diagram, ignoring `diagram-id` from settings
+- `--json` — Output result as JSON
+
+```sh
+dbdiagram push schema.dbml --name "My Diagram"         # create new diagram
+dbdiagram push schema.dbml --diagram-id <id>           # update existing diagram
+dbdiagram push schema.dbml --workspace <id>            # create in a workspace
+dbdiagram push schema.dbml --new                       # force-create, ignoring settings
+```
+
+---
+
+### Pull
+
+Pull DBML content from a diagram on dbdiagram.io.
+
+**Options:**
+
+- `--diagram-id <id>` — The diagram to pull from
+- `-o, --out-file <filepath>` — Save to a file instead of printing to stdout
+
+```sh
+dbdiagram pull --diagram-id <id>                       # print DBML to stdout
+dbdiagram pull --diagram-id <id> -o schema.dbml        # save to file
+```
+
+---
+
+### List
+
+List diagrams or documents.
+
+**Options:**
+
+- `--workspace <id>` — Filter by workspace (omit for personal workspace)
+- `--json` — Output as JSON
+
+```sh
+dbdiagram list                                         # list your diagrams
+dbdiagram list --workspace <id>                        # list diagrams in a workspace
+dbdiagram list document                                # list your dbdocs documents
+dbdiagram list document --workspace <name>             # list documents in a workspace
+```
+
+---
+
+### Delete
+
+Delete a diagram.
+
+**Options:**
+
+- `--diagram-id <id>` — The diagram to delete
+- `-f, --force` — Skip confirmation prompt
+- `--json` — Output result as JSON
+
+```sh
+dbdiagram delete --diagram-id <id>                     # delete with confirmation
+dbdiagram delete --diagram-id <id> --force             # delete without confirmation
+```
+
+---
+
+### Build
+
+Publish a dbdocs document from a local DBML file or a cloud diagram.
+
+**Options:**
+
+- `--from-file <filepath>` — Use a local DBML file as source _(required if not using `--from-diagram`)_
+- `--from-diagram <id>` — Use a cloud diagram as source _(required if not using `--from-file`)_
+- `--project <name>` — Target project as `<workspace>/<project>` or just `<project>`
+- `--version-name <name>` — Version label for this publish
+- `--json` — Output result as JSON
+
+```sh
+dbdiagram build document --from-file schema.dbml                               # publish from local file
+dbdiagram build document --from-diagram <id>                                   # publish from cloud diagram
+dbdiagram build document --from-file schema.dbml --project myteam/myproject    # publish to a specific project
+dbdiagram build document --from-file schema.dbml --version-name "v1.2.0"       # publish with a version label
+```
+
+---
+
+### Tokens
+
+Manage CLI tokens for non-interactive authentication.
+
+**Options:**
+
+- `--name <name>` — Name for the token (`generate` only)
+- `-f, --force` — Skip confirmation (`delete` only)
+- `--json` — Output as JSON
+
+```sh
+dbdiagram tokens generate --name "CI token"            # create a named token
+dbdiagram tokens list                                  # list all tokens
+dbdiagram tokens delete <token_id>                     # delete a token (with confirmation)
+dbdiagram tokens delete <token_id> --force             # delete without confirmation
+```
+
+Set the generated token as `DBDIAGRAM_TOKEN=<value>` in your environment to authenticate without browser login.
+
+---
+
+## Development
+
+```sh
+yarn install
+yarn dev        # run with tsx (no build needed)
+```
+
+```sh
+yarn build      # compile to dist/
+yarn start      # run compiled output
+```
+
+## Test
+
+```sh
+yarn test       # run tests for changed files with coverage
+yarn test:all   # run all tests
+```

package/dist/actions/auth/auth-login.action.js

@@ -0,0 +1,44 @@
+import path from 'path';
+import { spinner, log } from '@clack/prompts';
+import open from 'open';
+import { storeCredential } from '../../config/credential-manager.js';
+import { PORTAL_LOGIN_CONFIGS, PORTAL_URLS } from '../../config.js';
+import { initAuthClient, PORTAL_AUTH_ERROR_CODES, PortalAuthenticationError, } from '../../libs/portal/index.js';
+const ERROR_MESSAGES = {
+    [PORTAL_AUTH_ERROR_CODES.loginTimeout]: 'Login timed out. Please try again.',
+    [PORTAL_AUTH_ERROR_CODES.loginCancelled]: 'Login cancelled.',
+    [PORTAL_AUTH_ERROR_CODES.stateMismatch]: 'Authentication failed: security validation error.',
+    [PORTAL_AUTH_ERROR_CODES.exchangeFailed]: 'Authentication failed: could not exchange token.',
+    [PORTAL_AUTH_ERROR_CODES.invalidCallback]: 'Authentication failed: invalid callback received.',
+    [PORTAL_AUTH_ERROR_CODES.loopbackServerError]: 'Authentication failed: could not start local server.',
+    [PORTAL_AUTH_ERROR_CODES.unknownError]: 'Authentication failed: an unexpected error occurred.',
+};
+export async function loginAction() {
+    try {
+        const authClient = await initAuthClient({
+            loginUrl: PORTAL_URLS.loginUrl,
+            loginApiUrl: PORTAL_URLS.apiUrl,
+            clientId: PORTAL_LOGIN_CONFIGS.clientId,
+            loginTimeoutMs: PORTAL_LOGIN_CONFIGS.loginTimeoutMs,
+            callbackHtmlPaths: {
+                success: path.join(import.meta.dirname, '../../assets/callback-success.html'),
+                error: path.join(import.meta.dirname, '../../assets/callback-error.html'),
+            },
+        });
+        const s = spinner();
+        await open(authClient.getLoginUrl());
+        s.start('Waiting for browser login...');
+        const { accessToken } = await authClient.obtainTokens();
+        storeCredential(accessToken);
+        s.stop('Login successful. Credentials saved.');
+    }
+    catch (error) {
+        if (error instanceof PortalAuthenticationError) {
+            const message = ERROR_MESSAGES[error.errorCode] || ERROR_MESSAGES[PORTAL_AUTH_ERROR_CODES.unknownError];
+            log.error(message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}

package/dist/actions/auth/auth-logout.action.js

@@ -0,0 +1,13 @@
+import { log } from '@clack/prompts';
+import { clearCredential } from '../../config/credential-manager.js';
+export async function logoutAction() {
+    try {
+        clearCredential();
+        log.success('Logout successful.');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log.error(`Failed to log out: ${message}`);
+        process.exitCode = 1;
+    }
+}

package/dist/actions/auth/auth-status.action.js

@@ -0,0 +1,38 @@
+import { log, spinner } from '@clack/prompts';
+import { getCredential } from '../../config/credential-manager.js';
+import { NOT_LOGGED_IN_MESSAGE } from '../../constants/auth-message.constant.js';
+import { portalIntegration } from '../../integrations/portal/portal.integration.js';
+import { isPortalApiError, getPortalApiErrorMessage } from '../../utils/portal-error.util.js';
+import { printJson } from '../../utils/output.util.js';
+export async function statusAction(options = {}) {
+    const credential = getCredential();
+    if (!credential) {
+        log.warn(NOT_LOGGED_IN_MESSAGE);
+        process.exitCode = 1;
+        return;
+    }
+    const s = spinner();
+    s.start('Checking login status...');
+    try {
+        const user = await portalIntegration.getCurrentUser();
+        if (options.json) {
+            s.stop();
+            printJson({ email: user.email, name: user.name ?? null });
+        }
+        else {
+            const display = user.name ? `${user.name} (${user.email})` : user.email;
+            s.stop(`Logged in as ${display}`);
+        }
+    }
+    catch (error) {
+        s.stop('Failed to check login status.');
+        if (isPortalApiError(error)) {
+            log.error(getPortalApiErrorMessage(error));
+        }
+        else {
+            const message = error instanceof Error ? error.message : String(error);
+            log.error(message);
+        }
+        process.exitCode = 1;
+    }
+}

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

@@ -0,0 +1,142 @@
+import { readFile } from 'node:fs/promises';
+import { log, spinner } from '@clack/prompts';
+import { getCredential } from '../../config/credential-manager.js';
+import { NOT_LOGGED_IN_MESSAGE } from '../../constants/auth-message.constant.js';
+import { prepareBuildDocumentData } from '../../services/dbml/dbml.service.js';
+import { formatDbmlError, getDbmlVersion } from '../../utils/dbml.util.js';
+import { portalIntegration } from '../../integrations/portal/portal.integration.js';
+import { DBDOCS_CONFIGS } from '../../config.js';
+import { isPortalApiError, getPortalApiErrorMessage } from '../../utils/portal-error.util.js';
+import { printJson } from '../../utils/output.util.js';
+import { validateProjectUrlName, validateVersionName, validateWorkspaceUrlName, } from '../../utils/validation.util.js';
+import { DOCUMENT_SOURCE_TYPE } from '../../constants/document.constant.js';
+const DOCUMENT_SOURCE_CLIENT_TYPE = 'dbdiagram-cli';
+export async function documentAction(options) {
+    const credential = getCredential();
+    if (!credential) {
+        log.error(NOT_LOGGED_IN_MESSAGE);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.versionName !== undefined) {
+        const versionError = validateVersionName(options.versionName);
+        if (versionError) {
+            log.error(versionError);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (!options.workspaceUrlName) {
+        log.error('Workspace url name is required. Use --project <workspace>/<project> '
+            + 'or configure workspaceUrlName in settings.json');
+        process.exitCode = 1;
+        return;
+    }
+    const workspaceError = validateWorkspaceUrlName(options.workspaceUrlName);
+    if (workspaceError) {
+        log.error(workspaceError);
+        process.exitCode = 1;
+        return;
+    }
+    if (!options.projectUrlOrName) {
+        log.error('Project name/url name is required. Use --project <workspace>/<project> '
+            + 'or configure projectUrlName in settings.json');
+        process.exitCode = 1;
+        return;
+    }
+    if (options.projectUrlOrName.includes('/')) {
+        log.error('Invalid --project value. Expected <workspace>/<project> or <project>.');
+        process.exitCode = 1;
+        return;
+    }
+    const projectError = validateProjectUrlName(options.projectUrlOrName);
+    if (projectError) {
+        log.error(projectError);
+        process.exitCode = 1;
+        return;
+    }
+    if (options.source === undefined) {
+        log.error('One source must be specified: --from-file or --from-diagram');
+        process.exitCode = 1;
+        return;
+    }
+    let content;
+    if (options.source.type === DOCUMENT_SOURCE_TYPE.FILE) {
+        try {
+            content = await readFile(options.source.value, 'utf8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log.error(`Failed to read file: ${message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else {
+        try {
+            const diagram = await portalIntegration.getDiagram(options.source.value);
+            content = diagram.content;
+        }
+        catch (error) {
+            if (isPortalApiError(error)) {
+                log.error(getPortalApiErrorMessage(error));
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                log.error(`Failed to fetch diagram: ${message}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (!content || !content.trim()) {
+        log.warn('Source content is empty. Skipping document build.');
+        process.exitCode = 0;
+        return;
+    }
+    let preparedDocumentData;
+    try {
+        preparedDocumentData = await prepareBuildDocumentData(content);
+    }
+    catch (error) {
+        log.error(`Failed to parse DBML: ${formatDbmlError(error)}`);
+        process.exitCode = 1;
+        return;
+    }
+    const s = spinner();
+    s.start('Building document on dbdocs...');
+    try {
+        const { project } = await portalIntegration.createDocument({
+            projectName: options.projectUrlOrName,
+            projectDescription: preparedDocumentData.description,
+            workspaceUrlName: options.workspaceUrlName,
+            clientType: DOCUMENT_SOURCE_CLIENT_TYPE,
+            doc: {
+                content,
+                name: options.versionName ?? null,
+            },
+            shallowSchema: preparedDocumentData.shallowSchema,
+            normalizedDatabase: preparedDocumentData.normalizedDatabase,
+            dbmlVersion: getDbmlVersion(),
+        });
+        const url = `${DBDOCS_CONFIGS.baseUrl}/${project.workspaceUrl}/${project.urlName}`;
+        if (options.json) {
+            s.stop();
+            printJson({ projectUrlName: `${project.workspaceUrl}/${project.urlName}`, url });
+        }
+        else {
+            s.stop(`Document built successfully. Visit: ${url}`);
+        }
+    }
+    catch (error) {
+        s.stop('Failed to build document.');
+        if (isPortalApiError(error)) {
+            log.error(getPortalApiErrorMessage(error));
+        }
+        else {
+            const message = error instanceof Error ? error.message : String(error);
+            log.error(message);
+        }
+        process.exitCode = 1;
+    }
+}

package/dist/actions/delete.action.js

@@ -0,0 +1,67 @@
+import { confirm, isCancel, log, spinner } from '@clack/prompts';
+import { getCredential } from '../config/credential-manager.js';
+import { NOT_LOGGED_IN_MESSAGE } from '../constants/auth-message.constant.js';
+import { getSettings, writeSettings } from '../config/settings-manager.js';
+import { portalIntegration } from '../integrations/portal/portal.integration.js';
+import { isPortalApiError, getPortalApiErrorMessage } from '../utils/portal-error.util.js';
+import { printJson } from '../utils/output.util.js';
+export async function deleteAction(options) {
+    const credential = getCredential();
+    if (!credential) {
+        log.error(NOT_LOGGED_IN_MESSAGE);
+        process.exitCode = 1;
+        return;
+    }
+    if (!options.diagramId) {
+        log.error('Missing required flag: --diagram-id');
+        process.exitCode = 1;
+        return;
+    }
+    if (!options.force) {
+        const shouldDelete = await confirm({
+            message: `Delete diagram '${options.diagramId}'?`,
+            initialValue: false,
+        });
+        if (isCancel(shouldDelete) || !shouldDelete) {
+            return;
+        }
+    }
+    const s = spinner();
+    s.start('Deleting diagram...');
+    try {
+        await portalIntegration.deleteDiagram(options.diagramId);
+        const settings = getSettings();
+        let isRemoveInSettings = false;
+        if (settings && settings.diagram.id === options.diagramId) {
+            settings.diagram.id = '';
+            writeSettings(settings);
+            isRemoveInSettings = true;
+        }
+        if (options.json) {
+            s.stop();
+            printJson({
+                diagramId: options.diagramId,
+                deleted: true,
+                ...(isRemoveInSettings ? {} : { diagramIdSettingCleared: true }),
+            });
+        }
+        else {
+            s.stop(`Diagram '${options.diagramId}' deleted successfully.`);
+            if (isRemoveInSettings) {
+                log.info('The diagram.id has been cleared from .dbdiagram/settings.json');
+            }
+        }
+    }
+    catch (error) {
+        s.error('Failed to delete diagram.');
+        s.stop();
+        if (isPortalApiError(error)) {
+            log.error(getPortalApiErrorMessage(error));
+        }
+        else {
+            const message = error instanceof Error ? error.message : String(error);
+            log.error(message);
+        }
+        process.exitCode = 1;
+    }
+}

package/dist/actions/init.action.js

@@ -0,0 +1,105 @@
+import { isCancel, log, select, text } from '@clack/prompts';
+import { defaultSettings, readSettings, settingsExists, writeSettings, } from '../config/settings-manager.js';
+function hasFieldFlags(options) {
+    return [
+        options.entry,
+        options.diagramId,
+        options.workspace,
+        options.documentSource,
+        options.workspaceUrl,
+        options.projectUrl,
+    ].some((v) => v !== undefined);
+}
+function persist(data, message) {
+    try {
+        writeSettings(data);
+        log.success(message);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error(errorMessage);
+        process.exitCode = 1;
+    }
+}
+function flagFlow(options) {
+    const existed = settingsExists();
+    const existing = readSettings() ?? defaultSettings();
+    if (options.entry !== undefined)
+        existing.dbml.entry = options.entry;
+    if (options.diagramId !== undefined)
+        existing.diagram.id = options.diagramId;
+    if (options.workspace !== undefined)
+        existing.diagram.workspaceId = options.workspace;
+    if (options.documentSource !== undefined)
+        existing.document.source = options.documentSource;
+    if (options.workspaceUrl !== undefined)
+        existing.document.workspaceUrlName = options.workspaceUrl;
+    if (options.projectUrl !== undefined)
+        existing.document.projectUrlName = options.projectUrl;
+    persist(existing, existed ? 'Updated .dbdiagram/settings.json' : 'Created .dbdiagram/settings.json');
+}
+async function interactiveFlow() {
+    const existed = settingsExists();
+    const existing = readSettings() ?? defaultSettings();
+    const entryResult = await text({
+        message: 'DBML entry file',
+        placeholder: './schema.dbml',
+        defaultValue: existing.dbml.entry || undefined,
+    });
+    if (isCancel(entryResult))
+        return;
+    const diagramIdResult = await text({
+        message: 'Diagram ID (from dbdiagram.io/d/<id>)',
+        defaultValue: existing.diagram.id || undefined,
+    });
+    if (isCancel(diagramIdResult))
+        return;
+    const workspaceIdResult = await text({
+        message: 'dbdiagram Workspace ID (leave empty for personal)',
+        defaultValue: existing.diagram.workspaceId || undefined,
+    });
+    if (isCancel(workspaceIdResult))
+        return;
+    const sourceResult = await select({
+        message: 'Document source',
+        options: [
+            { value: 'file', label: 'file' },
+            { value: 'diagram', label: 'diagram' },
+        ],
+        initialValue: existing.document.source || 'file',
+    });
+    if (isCancel(sourceResult))
+        return;
+    const wsUrlResult = await text({
+        message: 'dbdocs Workspace URL name (from dbdocs.io/<name>)',
+        defaultValue: existing.document.workspaceUrlName || undefined,
+    });
+    if (isCancel(wsUrlResult))
+        return;
+    const projUrlResult = await text({
+        message: 'dbdocs Project URL name (from dbdocs.io/<workspace>/<name>)',
+        defaultValue: existing.document.projectUrlName || undefined,
+    });
+    if (isCancel(projUrlResult))
+        return;
+    const data = {
+        dbml: { entry: entryResult || '' },
+        diagram: {
+            id: diagramIdResult || '',
+            workspaceId: workspaceIdResult || '',
+        },
+        document: {
+            source: sourceResult || 'file',
+            workspaceUrlName: wsUrlResult || '',
+            projectUrlName: projUrlResult || '',
+        },
+    };
+    persist(data, existed ? 'Updated .dbdiagram/settings.json' : 'Created .dbdiagram/settings.json');
+}
+export async function initAction(options) {
+    if (hasFieldFlags(options)) {
+        flagFlow(options);
+        return;
+    }
+    await interactiveFlow();
+}