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

aloisklink · 2023-11-27T18:36:05Z

📖 Description

Note

This PR is stacked on top of:

fix(sdk): fix the required params of the setDocument() command #17

Add a @mermaidchart/cli package that can link/pull/push diagrams, e.g.

me@pc:~$ npx mermaid-chart link ./my-diagram.mmd 
? Select a project to upload your document to personal
me@pc:~$ npx mermaid-chart push ./my-diagram.mmd
✅ - ./my-diagram.mmd  was pushed
me@pc:~$ npx mermaid-chart pull ./my-diagram.mmd  
✅ - ./my-diagram.mmd  is up to date

me@pc:~$ npx @mermaidchart/cli --help
Usage: mermaid-cli [options] [command]

CLI for interacting with https://MermaidChart.com, the platform that makes
collaborating with Mermaid diagrams easy.

Options:
  -V, --version               output the version number
  -c, --config <config_file>  The path to the config file to use. (default:
                              "/home/me/.config/mermaid-chart.toml")
  -h, --help                  display help for command

Commands:
  whoami                      Display Mermaid Chart username
  login                       Login to a Mermaid Chart account
  logout                      Log out of a Mermaid Chart account
  link <path>                 Link the given Mermaid diagram to Mermaid Chart
  pull [options] <path>       Pulls a document from from Mermaid Chart
  push <path>                 Push a local diagram to Mermaid Chart
  help [command]              display help for command

Configuration file

The configuration file is a TOML file that's stored in:

Linux: ~/.config/mermaid-config.toml
MacOS: ~/Library/Application Support/mermaid-config.toml
Windows: %AppData%\mermaid-config.toml

Currently, the allowed fields are:

# TOML config file for mermaid-chart
[mermaid-chart]
base_url = "https://test.mermaidchart.com" # optional, defaults to https://mermaidchart.com
auth_token = "xxxxxx-xxxxxxx-xxxxxxxx" # set by `mermaid-chart login`.

Todo

~~ESLint is currently broken, I think due to the version of TypeScript I'm using.~~
- Fixed: I needed to install @typescript-eslint/parser v6.
Add OAuth login. Currently, users have to manually go to https://www.mermaidchart.com/app/user/settings to generate a key.
Currently, we can only pull or push a single diagram at a time. It would be better to support multiple diagrams at once (e.g. using a glob).
- Will be implemented by PR feat(cli): support pull/push/link on multiple mermaid files at once #15
Test on MacOS/Windows.
- MacOS/Windows are now tested in CI: ci(build): run GitHub Actions on MacOS and Windows #14, which helped find the bug in f234f3e. We still need manual/usability tests, though.
Support keeping comments in YAML frontmatter, as they're currently all removed.
- Will be fixed by fix(cli): keep comments in YAML frontmatter #21
Publish to NPM.
- We first need to make a new release of @mermaidchart/sdk.

vercel · 2023-11-27T18:36:13Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
office-plugin-site	⬜️ Ignored (Inspect)	Visit Preview		Apr 16, 2024 6:38am

aloisklink · 2023-11-27T18:38:08Z

packages/cli/package.json

+  "//2": "TODO: decide on a license once this code is finished",
+  "license": "UNLICENSED",


@knsv, what do you want the license for this package to be?

MIT is the license in the root of the repo, so we could use that: https://github.com/Mermaid-Chart/plugins/blob/main/LICENSE

packages/cli/test/fixtures/connected-diagram.mmd

aloisklink · 2023-12-06T10:46:37Z

packages/cli/README.md

+```bash
+npx @mermaidchart/cli --help
+```


We can't test this until we've published this package to NPM, but it should work!

Add an initial @mermaidchart/cli package that can `link`/`pull`/`push` diagrams.

Move the implementation of `push`/`pull`/`link` into their own functions, so that we can reuse them to add the feature for sync Mermaid diagrams from within markdown files.

According to https://web.archive.org/web/20120905053951/http://download.microsoft.com/download/e/6/a/e6aa654f-cccb-421e-9b50-3392e9886084/VistaFileSysNamespaces.pdf, this environment variable it ALLCAPS and at least in Node.JS, it's case-sensitive.

Add a `pnpm run dev` command to make testing/development easier.

Recommend using [npx][] to automatically install, cache, and run @mermaidchart/cli, e.g. with `npx @mermaidchart/cli`, as npx comes with most Node.JS installations. This doesn't currently work since we haven't published this package to NPM, however. [npx]: https://docs.npmjs.com/cli/v10/commands/npx

sidharthv96 · 2024-04-16T04:46:26Z

packages/cli/README.md

+### `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
+```


Can we use OAuth before releasing?

IMO, since it's not a mandatory feature that's block the v0.1.0 release, I think it can wait for a future minor release (e.g. v0.1.1)!

But yep, we should definitely add it to make it easier for users to sign-in!

sidharthv96 · 2024-04-16T05:03:12Z

packages/cli/src/commander.ts

+
+export function createCommanderCommand() {
+  const program = createCommand('mermaid-cli')
+    .version('0.1.0-alpha.0') // TODO: how can we keep this synced with package.json


Can't we import it from the json file? That's how we do in mermaid.

Fixed by 480df29

I think in a previous version of this library, I had the file in src/index.ts, but I compiled the output into ./index.js. So require("../package.json"); would have had to have switched to require("./package.json");. But now I'm using a dist/ folder, so the import path to package.json is the same!

sidharthv96 · 2024-04-16T05:05:19Z

packages/cli/src/methods.ts

+   * If set, the user has said to use the projectId to create all documents
+   * in.
+   */
+  selectedProjectId?: string;


nit: Consistency

Suggested change

selectedProjectId?: string;

selectedProjectID?: string;

👍

I'll look into fixing all of these before we make the first release, but after #22 is merged, to avoid causing merge conflicts.

Currently, this value is hard coded, which isn't great, since it means we need to update the value in two places each time we make a new release. This is a bit slower than the old version, but it shouldn't be too much slower, unless the user is still using a HDD.

aloisklink added the enhancement label Nov 27, 2023

aloisklink commented Nov 27, 2023

View reviewed changes

packages/cli/test/fixtures/connected-diagram.mmd Show resolved Hide resolved

aloisklink force-pushed the feat/add-mermaid-chart-cli branch 2 times, most recently from 7210e5b to 08f9cf9 Compare November 28, 2023 14:40

aloisklink mentioned this pull request Nov 29, 2023

ci(build): run GitHub Actions on MacOS and Windows #14

Merged

aloisklink force-pushed the feat/add-mermaid-chart-cli branch from c56defb to 849112d Compare December 1, 2023 13:42

This was referenced Dec 1, 2023

feat(cli): support pull/push/link on multiple mermaid files at once #15

Merged

feat(cli): support mermaid diagrams within GFM (github flavored markdown) #16

Merged

Base automatically changed from feat/add-setDocument-to-sdk to main December 4, 2023 08:54

aloisklink marked this pull request as ready for review December 4, 2023 09:28

aloisklink requested a review from jgreywolf December 4, 2023 09:28

aloisklink commented Dec 6, 2023

View reviewed changes

aloisklink added 8 commits March 6, 2024 15:56

feat(sdk): make MermaidChart#baseURL public

c995911

feat(cli): initial @mermaidchart/cli package

aae6376

Add an initial @mermaidchart/cli package that can `link`/`pull`/`push` diagrams.

ci(test): lint packages/cli in CI

bafd02c

refactor(cli): split up push/pull/link` funcs

8b4e889

Move the implementation of `push`/`pull`/`link` into their own functions, so that we can reuse them to add the feature for sync Mermaid diagrams from within markdown files.

docs: link to packages/cli in README.md

a2eee2e

build(cli): add a pnpm run dev command

0c58222

Add a `pnpm run dev` command to make testing/development easier.

aloisklink force-pushed the feat/add-mermaid-chart-cli branch from c7b84c0 to 3211343 Compare March 6, 2024 16:12

aloisklink changed the base branch from main to fix/setDocument-specify-that-projectID-is-required March 6, 2024 16:14

This was referenced Apr 10, 2024

feat(cli)!: use a URL id in the frontmatter #20

Merged

fix(cli): keep comments in YAML frontmatter #21

Merged

Base automatically changed from fix/setDocument-specify-that-projectID-is-required to main April 10, 2024 14:16

aloisklink mentioned this pull request Apr 11, 2024

feat(cli): support reading auth token in CLI with --auth-token and in ENV with MERMAID_CHART_AUTH_TOKEN #22

Merged

sidharthv96 reviewed Apr 16, 2024

View reviewed changes

sidharthv96 approved these changes Apr 16, 2024

View reviewed changes

aloisklink merged commit 354b144 into main Apr 16, 2024
6 checks passed

aloisklink deleted the feat/add-mermaid-chart-cli branch April 16, 2024 08:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

aloisklink commented Nov 27, 2023 •

edited

Loading

vercel bot commented Nov 27, 2023 •

edited

Loading

aloisklink Nov 27, 2023

aloisklink Dec 6, 2023

sidharthv96 Apr 16, 2024

aloisklink Apr 16, 2024

sidharthv96 Apr 16, 2024

aloisklink Apr 16, 2024

sidharthv96 Apr 16, 2024

aloisklink Apr 16, 2024

		"//2": "TODO: decide on a license once this code is finished",
		"license": "UNLICENSED",

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

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

Conversation

aloisklink commented Nov 27, 2023 • edited Loading

📖 Description

Configuration file

Todo

vercel bot commented Nov 27, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

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

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

aloisklink commented Nov 27, 2023 •

edited

Loading

vercel bot commented Nov 27, 2023 •

edited

Loading