@joint/cli 0.1.1 → 0.2.2

package/README.md

@@ -6,7 +6,7 @@ Command-line tool for [JointJS](https://jointjs.com).
 
 ```bash
 npx @joint/cli list
-npx @joint/cli download scada/js
+npx @joint/cli download kitchen-sink/js
 ```
 
 ## Installation
@@ -19,7 +19,7 @@ Once installed globally, the `joint` command is available:
 
 ```bash
 joint list
-joint download scada/js
+joint download kitchen-sink/js
 ```
 
 ## Commands
@@ -37,14 +37,21 @@ joint list
 Download an example into the current working directory.
 
 ```bash
-# Downloads into ./scada-js/
-joint download scada/js
+# Downloads into ./kitchen-sink-js/
+joint download kitchen-sink/js
 
-# Downloads into ./scada/
-joint download scada/js scada
+# Downloads into ./my-app/
+joint download kitchen-sink/js my-app
 
-# Downloads into the current directory
-joint download scada/js .
+# Downloads into the current directory (must be empty or use --force)
+joint download kitchen-sink/js .
+```
+
+If the destination directory already exists, use `--force` to overwrite:
+
+```bash
+joint download kitchen-sink/js --force
+joint download kitchen-sink/js . --force
 ```
 
 ## Options
@@ -55,6 +62,7 @@ joint download scada/js .
 | `--version`, `-v` | Show version number |
 | `--owner <name>` | GitHub repo owner (default: `clientIO`) |
 | `--branch <name>` | GitHub repo branch (default: `main`) |
+| `--force` | Overwrite existing files when downloading |
 
 ### Working with forks
 
@@ -62,7 +70,7 @@ Use `--owner` and `--branch` to list and download examples from a fork:
 
 ```bash
 joint list --owner myGitHubUser
-joint download scada/js --owner myGitHubUser --branch dev
+joint download kitchen-sink/js --owner myGitHubUser --branch dev
 ```
 
 ## Environment Variables

package/dist/__tests__/download.test.js

@@ -0,0 +1,67 @@
+import { describe, it, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert/strict';
+const defaultOptions = { owner: 'clientIO', branch: 'main' };
+function mockFetchWithFolders(folders) {
+    const tree = folders.flatMap((f) => {
+        const top = f.split('/')[0];
+        return [
+            { path: top, type: 'tree' },
+            { path: f, type: 'tree' },
+        ];
+    });
+    globalThis.fetch = mock.fn(async () => ({
+        ok: true,
+        json: async () => ({ tree }),
+    }));
+}
+describe('download command', () => {
+    let originalFetch;
+    const originalExit = process.exit;
+    let exitCode;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+        exitCode = undefined;
+        process.exit = mock.fn((code) => {
+            exitCode = code;
+            throw new Error(`process.exit(${code})`);
+        });
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        process.exit = originalExit;
+    });
+    it('exits with error when example not found', async () => {
+        mockFetchWithFolders(['scada/js', 'scada/ts']);
+        // Dynamic import to get fresh module
+        const { download } = await import('../commands/download.js');
+        await assert.rejects(() => download('nonexistent/js', undefined, defaultOptions), { message: 'process.exit(1)' });
+        assert.equal(exitCode, 1);
+    });
+    it('exits with error when folder not found in empty repo', async () => {
+        globalThis.fetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({ tree: [] }),
+        }));
+        const { download } = await import('../commands/download.js');
+        await assert.rejects(() => download('scada/js', undefined, defaultOptions), { message: 'process.exit(1)' });
+    });
+    it('computes default directory name from folder path', async () => {
+        // We can test the naming logic by checking what happens when the dir already exists
+        // If we provide a folder that exists in the list, it will try to create "scada-js"
+        // We test this indirectly — the naming logic is: folder.replace(/\//g, '-')
+        const folderName = 'scada/js';
+        const expected = 'scada-js';
+        assert.equal(folderName.replace(/\//g, '-'), expected);
+    });
+    it('uses custom target name when provided', () => {
+        const folderName = 'scada/js';
+        const target = 'my-project';
+        const dirName = target ?? folderName.replace(/\//g, '-');
+        assert.equal(dirName, 'my-project');
+    });
+    it('handles dot target for current directory', () => {
+        const dirName = '.';
+        const displayPath = dirName === '.' ? 'current directory' : `./${dirName}`;
+        assert.equal(displayPath, 'current directory');
+    });
+});

package/dist/__tests__/github.test.js

@@ -0,0 +1,92 @@
+import { describe, it, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { listDemoFolders } from '../lib/github.js';
+const defaultOptions = { owner: 'clientIO', branch: 'main' };
+describe('listDemoFolders', () => {
+    let originalFetch;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        delete process.env.GITHUB_TOKEN;
+    });
+    it('returns sorted 2-level deep directories', async () => {
+        globalThis.fetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({
+                tree: [
+                    { path: 'scada', type: 'tree' },
+                    { path: 'scada/js', type: 'tree' },
+                    { path: 'scada/ts', type: 'tree' },
+                    { path: 'scada/js/package.json', type: 'blob' },
+                    { path: 'kitchen-sink', type: 'tree' },
+                    { path: 'kitchen-sink/js', type: 'tree' },
+                ],
+            }),
+        }));
+        const result = await listDemoFolders(defaultOptions);
+        assert.deepEqual(result, ['kitchen-sink/js', 'scada/js', 'scada/ts']);
+    });
+    it('filters out blobs and top-level directories', async () => {
+        globalThis.fetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({
+                tree: [
+                    { path: 'README.md', type: 'blob' },
+                    { path: 'scada', type: 'tree' },
+                    { path: 'scada/js', type: 'tree' },
+                    { path: 'scada/js/src', type: 'tree' },
+                ],
+            }),
+        }));
+        const result = await listDemoFolders(defaultOptions);
+        assert.deepEqual(result, ['scada/js']);
+    });
+    it('returns empty array when tree is empty', async () => {
+        globalThis.fetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({ tree: [] }),
+        }));
+        const result = await listDemoFolders(defaultOptions);
+        assert.deepEqual(result, []);
+    });
+    it('throws on 404', async () => {
+        globalThis.fetch = mock.fn(async () => ({
+            ok: false,
+            status: 404,
+            statusText: 'Not Found',
+        }));
+        await assert.rejects(() => listDemoFolders(defaultOptions), { message: 'Repository or branch not found. Please verify the --owner and --branch options.' });
+    });
+    it('throws on other HTTP errors', async () => {
+        globalThis.fetch = mock.fn(async () => ({
+            ok: false,
+            status: 403,
+            statusText: 'rate limit exceeded',
+        }));
+        await assert.rejects(() => listDemoFolders(defaultOptions), { message: 'GitHub API request failed: 403 rate limit exceeded' });
+    });
+    it('uses correct URL with custom owner and branch', async () => {
+        const mockFetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({ tree: [] }),
+        }));
+        globalThis.fetch = mockFetch;
+        await listDemoFolders({ owner: 'myFork', branch: 'dev' });
+        const calledUrl = mockFetch.mock.calls[0].arguments[0];
+        assert.ok(calledUrl.includes('/myFork/'));
+        assert.ok(calledUrl.endsWith('/git/trees/dev?recursive=1'));
+    });
+    it('includes Authorization header when GITHUB_TOKEN is set', async () => {
+        process.env.GITHUB_TOKEN = 'test-token';
+        const mockFetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({ tree: [] }),
+        }));
+        globalThis.fetch = mockFetch;
+        await listDemoFolders(defaultOptions);
+        const calledHeaders = mockFetch.mock.calls[0].arguments[1];
+        assert.equal(calledHeaders.headers['Authorization'], 'Bearer test-token');
+    });
+});

package/dist/__tests__/list.test.js

@@ -0,0 +1,55 @@
+import { describe, it, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { list } from '../commands/list.js';
+const defaultOptions = { owner: 'clientIO', branch: 'main' };
+describe('list command', () => {
+    let originalFetch;
+    const logOutput = [];
+    const originalLog = console.log;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+        logOutput.length = 0;
+        console.log = (...args) => {
+            logOutput.push(args.join(' '));
+        };
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        console.log = originalLog;
+    });
+    it('prints available examples', async () => {
+        globalThis.fetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({
+                tree: [
+                    { path: 'scada', type: 'tree' },
+                    { path: 'scada/js', type: 'tree' },
+                    { path: 'kitchen-sink', type: 'tree' },
+                    { path: 'kitchen-sink/ts', type: 'tree' },
+                ],
+            }),
+        }));
+        await list(defaultOptions);
+        assert.ok(logOutput.some((line) => line.includes('scada/js')));
+        assert.ok(logOutput.some((line) => line.includes('kitchen-sink/ts')));
+    });
+    it('handles empty tree', async () => {
+        globalThis.fetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({ tree: [] }),
+        }));
+        await list(defaultOptions);
+        assert.ok(!logOutput.some((line) => line.includes('  - ')));
+    });
+    it('passes options to the API call', async () => {
+        const mockFetch = mock.fn(async () => ({
+            ok: true,
+            json: async () => ({ tree: [] }),
+        }));
+        globalThis.fetch = mockFetch;
+        await list({ owner: 'myFork', branch: 'dev' });
+        const calledUrl = mockFetch.mock.calls[0].arguments[0];
+        assert.ok(calledUrl.includes('/myFork/'));
+        assert.ok(calledUrl.includes('/dev?'));
+    });
+});

package/dist/cli.js

@@ -21,20 +21,29 @@ ${logger.bold('Options:')}
   --version, -v       Show version number
   --owner <name>      GitHub repo owner (default: ${DEFAULT_OWNER})
   --branch <name>     GitHub repo branch (default: ${DEFAULT_BRANCH})
+  --force             Overwrite existing files when downloading
 
 ${logger.bold('Environment:')}
   GITHUB_TOKEN        Optional GitHub token to avoid rate limiting
 `;
 function getFlag(args, name) {
     const index = args.indexOf(name);
-    if (index === -1 || index + 1 >= args.length)
+    if (index === -1)
         return undefined;
-    return args[index + 1];
+    const value = args[index + 1];
+    if (index + 1 >= args.length || !value || value.startsWith('--')) {
+        logger.error(`Missing value for option "${name}".`);
+        process.exit(1);
+    }
+    return value;
 }
 function stripFlags(args) {
     const result = [];
     for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--owner' || args[i] === '--branch') {
+        if (args[i] === '--force') {
+            continue;
+        }
+        else if (args[i] === '--owner' || args[i] === '--branch') {
             i++; // skip the value
         }
         else {
@@ -46,16 +55,17 @@ function stripFlags(args) {
 async function main() {
     const rawArgs = process.argv.slice(2);
     if (rawArgs.length === 0 || rawArgs.includes('--help') || rawArgs.includes('-h')) {
-        console.log(HELP);
+        logger.log(HELP);
         return;
     }
     if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
-        console.log(VERSION);
+        logger.log(VERSION);
         return;
     }
     const options = {
         owner: getFlag(rawArgs, '--owner') ?? DEFAULT_OWNER,
         branch: getFlag(rawArgs, '--branch') ?? DEFAULT_BRANCH,
+        force: rawArgs.includes('--force'),
     };
     const args = stripFlags(rawArgs);
     const command = args[0];

package/dist/commands/download.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { listDemoFolders } from '../lib/github.js';
 import { sparseCheckout } from '../lib/git.js';
@@ -9,11 +9,11 @@ export async function download(folder, target, options) {
     if (!folders.includes(folder)) {
         logger.error(`Example "${folder}" not found.`);
         if (folders.length > 0) {
-            console.log(`\n${logger.bold('Available examples:')}\n`);
+            logger.log(`\n${logger.bold('Available examples:')}\n`);
             for (const f of folders) {
-                console.log(`  - ${f}`);
+                logger.log(`  - ${f}`);
             }
-            console.log();
+            logger.log('');
         }
         else {
             logger.warn('No examples are available yet.');
@@ -22,11 +22,18 @@ export async function download(folder, target, options) {
     }
     const dirName = target ?? folder.replace(/\//g, '-');
     const dest = resolve(process.cwd(), dirName);
-    if (dirName !== '.' && existsSync(dest)) {
-        logger.error(`Directory "${dirName}" already exists in the current directory.`);
-        process.exit(1);
+    if (existsSync(dest)) {
+        if (dirName !== '.' && !options.force) {
+            logger.error(`Directory "${dirName}" already exists. Use --force to overwrite.`);
+            process.exit(1);
+        }
+        if (dirName === '.' && readdirSync(dest).length > 0 && !options.force) {
+            logger.error('Current directory is not empty. Use --force to overwrite existing files.');
+            process.exit(1);
+        }
     }
     logger.info(`Downloading "${folder}"...`);
     await sparseCheckout(folder, dest, options);
-    logger.success(`\nDone! Example downloaded to ./${dirName}`);
+    const displayPath = dirName === '.' ? 'current directory' : `./${dirName}`;
+    logger.success(`\nDone! Example downloaded to ${displayPath}`);
 }

package/dist/commands/list.js

@@ -7,9 +7,9 @@ export async function list(options) {
         logger.warn('No examples available yet.');
         return;
     }
-    console.log(logger.bold('Available examples:\n'));
+    logger.log(logger.bold('Available examples:\n'));
     for (const folder of folders) {
-        console.log(`  - ${folder}`);
+        logger.log(`  - ${folder}`);
     }
-    console.log();
+    logger.log('');
 }

package/dist/lib/git.js

@@ -1,7 +1,8 @@
 import { execFile } from 'node:child_process';
-import { mkdtemp, rm, cp } from 'node:fs/promises';
+import { mkdtemp, rm, cp, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
+import { existsSync } from 'node:fs';
 import { getRepoUrl } from '../constants.js';
 function run(command, args, cwd) {
     return new Promise((resolve, reject) => {
@@ -21,12 +22,19 @@ export async function sparseCheckout(folder, dest, options) {
         await run('git', ['init', tmp]);
         await run('git', ['remote', 'add', 'origin', repoUrl], tmp);
         await run('git', ['sparse-checkout', 'init', '--cone'], tmp);
-        await run('git', ['sparse-checkout', 'set', folder], tmp);
-        await run('git', ['pull', 'origin', options.branch, '--depth=1'], tmp);
+        await run('git', ['sparse-checkout', 'set', '--', folder], tmp);
+        await run('git', ['pull', 'origin', '--depth=1', '--', options.branch], tmp);
         const src = join(tmp, folder);
-        // If dest already exists (e.g. "."), copy contents into it.
-        // Otherwise, move the folder directly.
-        await cp(src, dest, { recursive: true });
+        if (existsSync(dest)) {
+            // Copy each entry individually into the existing directory
+            const entries = await readdir(src);
+            for (const entry of entries) {
+                await cp(join(src, entry), join(dest, entry), { recursive: true });
+            }
+        }
+        else {
+            await cp(src, dest, { recursive: true });
+        }
     }
     finally {
         await rm(tmp, { recursive: true, force: true });

package/dist/lib/github.js

@@ -12,11 +12,11 @@ function buildHeaders() {
 }
 export async function listDemoFolders(options) {
     const apiUrl = getGitHubApiUrl(options);
-    const url = `${apiUrl}/git/trees/${options.branch}?recursive=1`;
+    const url = `${apiUrl}/git/trees/${encodeURIComponent(options.branch)}?recursive=1`;
     const response = await fetch(url, { headers: buildHeaders() });
     if (!response.ok) {
         if (response.status === 404) {
-            return [];
+            throw new Error('Repository or branch not found. Please verify the --owner and --branch options.');
         }
         throw new Error(`GitHub API request failed: ${response.status} ${response.statusText}`);
     }
@@ -26,7 +26,9 @@ export async function listDemoFolders(options) {
     }
     // Return only 2-level deep directories (e.g. "scada/js", "kitchen-sink/ts")
     return data.tree
-        .filter((item) => item.type === 'tree' && item.path.split('/').length === 2)
+        // Only include items that are directories (type 'tree'),
+        // are exactly 2 levels deep, and don't start with a dot (to exclude hidden folders)
+        .filter((item) => item.type === 'tree' && item.path.split('/').length === 2 && !item.path.startsWith('.'))
         .map((item) => item.path)
         .sort();
 }

package/dist/lib/logger.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 const RESET = '\x1b[0m';
 const RED = '\x1b[31m';
 const GREEN = '\x1b[32m';
@@ -11,11 +12,14 @@ export function success(msg) {
     console.log(`${GREEN}${msg}${RESET}`);
 }
 export function warn(msg) {
-    console.log(`${YELLOW}${msg}${RESET}`);
+    console.warn(`${YELLOW}${msg}${RESET}`);
 }
 export function error(msg) {
     console.error(`${RED}${msg}${RESET}`);
 }
+export function log(msg) {
+    console.log(msg);
+}
 export function bold(msg) {
     return `${BOLD}${msg}${RESET}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joint/cli",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "type": "module",
   "description": "Command-line tool for JointJS.",
   "license": "MIT",
@@ -12,10 +12,18 @@
   ],
   "scripts": {
     "build": "tsc",
+    "dist": "yarn build",
+    "test": "tsx --test src/__tests__/*.test.ts",
+    "lint": "eslint .",
+    "lint-fix": "eslint . --fix",
+    "prepack": "yarn build",
     "prepublishOnly": "echo \"Publishing via NPM is not allowed!\" && exit 1"
   },
   "devDependencies": {
+    "@joint/eslint-config": "4.2.3",
     "@types/node": "^22.0.0",
+    "eslint": "9.39.2",
+    "tsx": "^4.21.0",
     "typescript": "^5.8.0"
   },
   "publishConfig": {