@joint/cli 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @joint/cli
+
+Command-line tool for [JointJS](https://jointjs.com).
+
+## Quick Start
+
+```bash
+npx @joint/cli list
+npx @joint/cli download scada/js
+```
+
+## Installation
+
+```bash
+npm install -g @joint/cli
+```
+
+Once installed globally, the `joint` command is available:
+
+```bash
+joint list
+joint download scada/js
+```
+
+## Commands
+
+### `joint list`
+
+List available examples from the [joint-demos](https://github.com/clientIO/joint-demos) repository.
+
+```bash
+joint list
+```
+
+### `joint download <name> [dest]`
+
+Download an example into the current working directory.
+
+```bash
+# Downloads into ./scada-js/
+joint download scada/js
+
+# Downloads into ./scada/
+joint download scada/js scada
+
+# Downloads into the current directory
+joint download scada/js .
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--help`, `-h` | Show help message |
+| `--version`, `-v` | Show version number |
+| `--owner <name>` | GitHub repo owner (default: `clientIO`) |
+| `--branch <name>` | GitHub repo branch (default: `main`) |
+
+### Working with forks
+
+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
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `GITHUB_TOKEN` | Optional GitHub token to avoid API rate limiting |
+
+## Requirements
+
+- Node.js >= 22
+- Git

package/dist/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { list } from './commands/list.js';
+import { download } from './commands/download.js';
+import { DEFAULT_OWNER, DEFAULT_BRANCH } from './constants.js';
+import * as logger from './lib/logger.js';
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require('../package.json');
+const HELP = `
+${logger.bold('joint')} — Command-line tool for JointJS
+
+${logger.bold('Usage:')}
+  joint <command> [options]
+
+${logger.bold('Commands:')}
+  list                List available examples
+  download <name> [dest]  Download an example
+
+${logger.bold('Options:')}
+  --help, -h          Show this help message
+  --version, -v       Show version number
+  --owner <name>      GitHub repo owner (default: ${DEFAULT_OWNER})
+  --branch <name>     GitHub repo branch (default: ${DEFAULT_BRANCH})
+
+${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)
+        return undefined;
+    return args[index + 1];
+}
+function stripFlags(args) {
+    const result = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--owner' || args[i] === '--branch') {
+            i++; // skip the value
+        }
+        else {
+            result.push(args[i]);
+        }
+    }
+    return result;
+}
+async function main() {
+    const rawArgs = process.argv.slice(2);
+    if (rawArgs.length === 0 || rawArgs.includes('--help') || rawArgs.includes('-h')) {
+        console.log(HELP);
+        return;
+    }
+    if (rawArgs.includes('--version') || rawArgs.includes('-v')) {
+        console.log(VERSION);
+        return;
+    }
+    const options = {
+        owner: getFlag(rawArgs, '--owner') ?? DEFAULT_OWNER,
+        branch: getFlag(rawArgs, '--branch') ?? DEFAULT_BRANCH,
+    };
+    const args = stripFlags(rawArgs);
+    const command = args[0];
+    switch (command) {
+        case 'list':
+            await list(options);
+            break;
+        case 'download': {
+            const folder = args[1];
+            if (!folder) {
+                logger.error('Missing required argument: <name>\n');
+                logger.info('Usage: joint download <name> [dest]');
+                process.exit(1);
+            }
+            const target = args[2];
+            await download(folder, target, options);
+            break;
+        }
+        default:
+            logger.error(`Unknown command: "${command}"\n`);
+            logger.info('Run "joint --help" to see available commands.');
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    logger.error(err.message);
+    process.exit(1);
+});

package/dist/commands/download.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { listDemoFolders } from '../lib/github.js';
+import { sparseCheckout } from '../lib/git.js';
+import * as logger from '../lib/logger.js';
+export async function download(folder, target, options) {
+    logger.info(`Validating example "${folder}"...\n`);
+    const folders = await listDemoFolders(options);
+    if (!folders.includes(folder)) {
+        logger.error(`Example "${folder}" not found.`);
+        if (folders.length > 0) {
+            console.log(`\n${logger.bold('Available examples:')}\n`);
+            for (const f of folders) {
+                console.log(`  - ${f}`);
+            }
+            console.log();
+        }
+        else {
+            logger.warn('No examples are available yet.');
+        }
+        process.exit(1);
+    }
+    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);
+    }
+    logger.info(`Downloading "${folder}"...`);
+    await sparseCheckout(folder, dest, options);
+    logger.success(`\nDone! Example downloaded to ./${dirName}`);
+}

package/dist/commands/list.js

@@ -0,0 +1,15 @@
+import { listDemoFolders } from '../lib/github.js';
+import * as logger from '../lib/logger.js';
+export async function list(options) {
+    logger.info('Fetching available examples...\n');
+    const folders = await listDemoFolders(options);
+    if (folders.length === 0) {
+        logger.warn('No examples available yet.');
+        return;
+    }
+    console.log(logger.bold('Available examples:\n'));
+    for (const folder of folders) {
+        console.log(`  - ${folder}`);
+    }
+    console.log();
+}

package/dist/constants.js

@@ -0,0 +1,9 @@
+export const DEFAULT_OWNER = 'clientIO';
+export const DEFAULT_REPO = 'joint-demos';
+export const DEFAULT_BRANCH = 'main';
+export function getRepoUrl({ owner }) {
+    return `https://github.com/${owner}/${DEFAULT_REPO}.git`;
+}
+export function getGitHubApiUrl({ owner }) {
+    return `https://api.github.com/repos/${owner}/${DEFAULT_REPO}`;
+}

package/dist/lib/git.js

@@ -0,0 +1,34 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, cp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { getRepoUrl } from '../constants.js';
+function run(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, { cwd }, (err, stdout, stderr) => {
+            if (err) {
+                reject(new Error(stderr || err.message));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+export async function sparseCheckout(folder, dest, options) {
+    const repoUrl = getRepoUrl(options);
+    const tmp = await mkdtemp(join(tmpdir(), 'joint-cli-'));
+    try {
+        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);
+        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 });
+    }
+    finally {
+        await rm(tmp, { recursive: true, force: true });
+    }
+}

package/dist/lib/github.js

@@ -0,0 +1,32 @@
+import { getGitHubApiUrl } from '../constants.js';
+function buildHeaders() {
+    const headers = {
+        'Accept': 'application/vnd.github.v3+json',
+        'User-Agent': 'joint-cli',
+    };
+    const token = process.env.GITHUB_TOKEN;
+    if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+    }
+    return headers;
+}
+export async function listDemoFolders(options) {
+    const apiUrl = getGitHubApiUrl(options);
+    const url = `${apiUrl}/git/trees/${options.branch}?recursive=1`;
+    const response = await fetch(url, { headers: buildHeaders() });
+    if (!response.ok) {
+        if (response.status === 404) {
+            return [];
+        }
+        throw new Error(`GitHub API request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (!Array.isArray(data.tree)) {
+        return [];
+    }
+    // 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)
+        .map((item) => item.path)
+        .sort();
+}

package/dist/lib/logger.js

@@ -0,0 +1,21 @@
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const BOLD = '\x1b[1m';
+export function info(msg) {
+    console.log(`${CYAN}${msg}${RESET}`);
+}
+export function success(msg) {
+    console.log(`${GREEN}${msg}${RESET}`);
+}
+export function warn(msg) {
+    console.log(`${YELLOW}${msg}${RESET}`);
+}
+export function error(msg) {
+    console.error(`${RED}${msg}${RESET}`);
+}
+export function bold(msg) {
+    return `${BOLD}${msg}${RESET}`;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@joint/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Command-line tool for JointJS.",
+  "license": "MIT",
+  "bin": {
+    "joint": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "echo \"Publishing via NPM is not allowed!\" && exit 1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0"
+  },
+  "volta": {
+    "node": "22.14.0",
+    "npm": "11.2.0",
+    "yarn": "4.7.0"
+  }
+}