Add a @mermaidchart/cli CLI tool for accessing Mermaid Chart

.github/workflows/build.yml

@@ -9,7 +9,7 @@ jobs:
     strategy:
       matrix:
         node: ['18.18.x']
-        pkg: ['sdk']
+        pkg: ['sdk', 'cli']
     runs-on:
       labels: ubuntu-latest
     steps:
@@ -30,6 +30,9 @@ jobs:
         run: |
           pnpm install --frozen-lockfile --filter='...${{ matrix.pkg }}'
 
+      - name: Lint (if present) ${{ matrix.pkg }}
+        run: pnpm --if-present --filter='${{ matrix.pkg }}' lint
+
       - name: Test ${{ matrix.pkg }}
         run: |
           pnpm --filter='${{ matrix.pkg }}' test

README.md

@@ -12,6 +12,10 @@ The OpenAPI YAML file is located at [./openapi.yaml](./openapi.yaml).
 
 - [Javascript/Typescript](./packages/sdk)
 
+## CLI
+
+- [`@mermaidchart/cli` command-line interface](./packages/cli)
+
 ## Plugins
 
 - [VSCode (to be migrated here)](https://github.com/Mermaid-Chart/vscode-mermaid-chart/)

cSpell.json

@@ -5,6 +5,7 @@
     "Cataa",
     "colour",
     "Cookiebot",
+    "gantt",
     "jsnext",
     "lintstagedrc",
     "mermaidchart",

packages/cli/.eslintrc.cjs

@@ -0,0 +1,16 @@
+module.exports = /** @type {import("eslint").Linter.Config} */ ({
+  root: false, // mono-repo
+  parser: '@typescript-eslint/parser',
+  ignorePatterns: ['*.cjs'],
+  parserOptions: {
+    ecmaVersion: 2022, // support node v18 features
+    allowAutomaticSingleRunInference: true,
+    sourceType: 'module',
+    project: ['./tsconfig.json'],
+    tsconfigRootDir: __dirname,
+    parser: '@typescript-eslint/parser',
+  },
+  rules: {
+    "no-console": ["warn"], // TODO: fix all of these
+  }
+});

packages/cli/README.md

@@ -0,0 +1,92 @@
+# @mermaidchart/cli
+
+CLI for interacting with https://MermaidChart.com, the platform that makes collaborating with Mermaid diagrams easy!
+
+## Installation
+
+`@mermaidcart/cli` is tested to work with Node.JS v18.18.0 or later.
+
+We recommend installation using [npx](https://docs.npmjs.com/cli/v10/commands/npx)
+to automatically download, cache, and run `@mermaidcart/cli`, as it comes with
+most Node.JS installations.
+
+```bash
+npx @mermaidchart/cli --help
+```
+
+## Usage
+
+```bash
+npx @mermaidchart/cli <command>
+```
+
+Use `--help` to see options!
+
+```bash
+npx @mermaidchart/cli --help
+```
+
+`@mermaidchart/cli` allows you to easily sync local diagrams with your diagrams
+on https://mermaidchart.com.
+
+### `login`
+
+Firstly, go to https://www.mermaidchart.com/app/user/settings and generate an
+API key, which you can then setup by running:
+
+```bash
+npx @mermaidchart/cli login
+```
+
+### `link` an existing Mermaid diagram to MermaidChart.com
+
+You can link a local Mermaid diagram to MermaidChart using:
+
+```bash
+npx @mermaidchart/cli link ./path/to/my/mermaid-digram.mmd
+```
+
+This will add an `id: xxxx-xxxxx-xxxxx` field to your diagram's YAML frontmatter,
+which points to the diagram on MermaidChart.com:
+
+````markdown
+```mermaid
+---
+title: My diagram
+id: xxxx-xxxxx-xxxxx # this field is created by @mermaidchart/cli
+---
+flowchart
+  x[My Diagram]
+```
+````
+
+### `push` local changes to MermaidChart.com
+
+Once you've made some local changes, you can `push` your changes to MermaidChart.com
+
+```console
+$ npx @mermaidchart/cli push ./path/to/my/mermaid-digram.mmd
+✅ - ./path/to/my/mermaid-digram.mmd was pushed
+```
+
+### `pull` changes from MermaidChart.com
+
+You can use `pull` to pull down changes from MermaidChart.com.
+
+```console
+$ npx @mermaidchart/cli pull ./path/to/my/mermaid-digram.mmd
+✅ - ./path/to/my/mermaid-digram.mmd was updated
+```
+
+Or use the `--check` flag to throw an error if your local file would have been
+updated:
+
+```console
+$ npx @mermaidchart/cli pull ./path/to/my/mermaid-digram.mmd
+❌ - ./path/to/my/mermaid-digram.mmd would be updated
+```
+
+## Contributing
+
+For local development and testing, you can `pnpm dev` to run the CLI,
+`pnpm run lint` to run linting, and `pnpm test` to run unit tests.

packages/cli/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@mermaidchart/cli",
+  "version": "0.1.0-alpha.0",
+  "description": "CLI for interacting with https://MermaidChart.com, the platform that makes collaborating with Mermaid diagrams easy",
+  "main": "index.js",
+  "bin": {
+    "mermaid-chart": "dist/cli.js"
+  },
+  "//1": "temporarily disable pushing until we finish progress on this",
+  "private": true,
+  "engines": {
+    "node": "^18.18.0 || ^20.0.0"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint src/ && prettier --check src/",
+    "lint:fix": "eslint --fix src/ && prettier --write src/",
+    "prepare": "tsc --build tsconfig.json",
+    "test": "vitest"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "directory": "packages/cli",
+    "url": "git+https://github.com/Mermaid-Chart/plugins.git"
+  },
+  "keywords": [
+    "mermaid",
+    "mermaidchart",
+    "cli"
+  ],
+  "author": "Alois Klink <[email protected]> (https://github.com/aloisklink)",
+  "//2": "TODO: decide on a license once this code is finished",
+  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://github.com/Mermaid-Chart/plugins/issues"
+  },
+  "homepage": "https://github.com/Mermaid-Chart/plugins/tree/main/packages/cli#readme",
+  "devDependencies": {
+    "@cspell/eslint-plugin": "^8.0.0",
+    "@tsconfig/node18": "^18.2.2",
+    "@tsconfig/strictest": "^2.0.2",
+    "@types/iarna__toml": "^2.0.5",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^18.18.11",
+    "@typescript-eslint/eslint-plugin": "^6.11.0",
+    "@typescript-eslint/parser": "^6.11.0",
+    "eslint": "^8.54.0",
+    "tsx": "^3.12.8",
+    "typescript": "^5.2.2",
+    "vitest": "^0.34.6"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "^11.1.0",
+    "@iarna/toml": "^2.2.5",
+    "@inquirer/input": "^1.2.14",
+    "@inquirer/select": "^1.3.1",
+    "@mermaidchart/sdk": "workspace:^",
+    "commander": "^11.1.0",
+    "js-yaml": "^4.1.0"
+  }
+}

packages/cli/src/cli.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { createCommanderCommand } from './commander.js';
+
+createCommanderCommand()
+  .parseAsync()
+  .catch((error) => {
+    console.error(error); // eslint-disable-line no-console
+    process.exitCode = 1;
+  });