carnesen / cli Goto Github PK

For example the wrapping functionality that's used internally to wrap text in the tabular view e.g.

   hiding normal-branch echo      : Prints the provided arguments to the
                                    terminal

I can imagine a lot of scenarios where this would be useful to consumers of @carnesen/cli. Let's export it.

Or something like that to demo usage of JSON arguments

It might be nice if we made a built-in feature where it will automatically do a sensible thing on (maybe) --version if the root is a ICliCommand or version if it's a branch.

Currently we only got as far as a screen recording of the multiply command. It looks great though. Let's keep going down that path.

I have a few dangling open issues that I filed on the alwaysAI fork of this project : https://github.com/alwaysai/alwayscli/issues . Close those with a message announcing this library's documentation page which they may find useful.

Adopt a code of conduct to define community standards, signal a welcoming and inclusive project, and outline procedures for handling abuse.

-- GitHub docs
https://github.com/carnesen/cli/community
See also https://opensource.guide/code-of-conduct/

It'll be more accurate than client-side tracking #88 . I'm super curious to see how big of a difference it makes on page views especially with an engineer audience.

Now that we are publishing the generated documentation to the web #29 , let's make sure it's complete!

Expand this content as the face of both the documentation and the @carnesen/cli package on npmjs. Note that currently the image links in the readme on npmjs.com are broken https://www.npmjs.com/package/@carnesen/cli/v/0.5.0-22.

Sections to include

• "Core concepts" : key pieces of the @carnesen/cli API.

It would look really slick if we could put a screen recording for "how that works as a CLI" in the readme.

This task will be complete when the API docs are publish to the world wide web.

I was thinking about good use cases for a browser CLI and I think the best one is a hidden bespoke admin console for a front-end applications. Imagine a big browser app where if you hit CTRL-OPTION-T it opens up a terminal with a slick per-page custom console from which you can manipulate the state of the application. In our console we could toggle light and dark modes for example.

It would be slick if --copy copied it into copy paste buffer too

Now that we have come so far with the autocomplete functionality for CliRepl, it would be awesome if we leverage that command completion for Node.js CLIs executed in bash.

We could offer a CLI command to get these autocompletions into a shell that would look something like (for a CLI my-cli):

completionsCommand = CliCommand({
  name: 'completions',
  action() {
    return `
# This command is meant to be used as "eval $(my-cli completions)"
command -W ...
`

The user would do:

$ eval $(my-cli completions)

https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html
Personally I still use bash, but probably we could/should do this for other shells too.

Or maybe labels 1, 2, 3, 5, 7 as complexity estimates, agile-style.

As of this writing there are at least two non-carnesen projects using @carnesen/cli:
https://github.com/TobiaszCudnik/demo-grpc
https://github.com/RiseVision/rise-node
Contact them and offer assistance upgrading

We have extensive automated testing of the runtime behavior of this library. As a TypeScript-first library let's also automate testing of our types using the new-in-TypeScript-3.9 // @ts-expect-error Comments or some other type testing framework.

Add a section to the main readme file describing this repository's structure with links.

In a shell we can use single and double quotes to "escape" whitespace. For example, echo "foo bar" tells the shell to echo a single string foo bar whereas echo foo bar passes foo and bar as separate arguments to echo. Let's support something like this in the CliRepl so that people can supply input as e.g. parse '{"foo": "bar"}'or even simplyecho "foo"` and have it behave as they'd expect in a shell.

Here is an example of the scenario we want to support:

$ cloud users list
Error: Server responded 401. Did you run "cloud login" yet?

Currently the "cloud login" string is hard-coded into the error message so there's no way to know programmatically whether its referencing an actual command or not. It might be nice to build an abstraction for these links so they can be checked.

This is mostly for the non-TypeScript users, but it could also be very useful even for TypeScript users for example when auto-generating a command tree. Anyway, the feature would be a function checkCli or something like that. It would check the correctness of the command tree for types etc but also whether you have subcommands.length > 0 in branches and that kind of thing that isn't currently checked even by types.

For a password for example it's sometimes convenient for security purposes to pass in sensitive data via standard input

Right now cli.carnesen.com/examples does not work because it's being served by some Python 2.7 thing. Let's just serve the website as a Node.js service so we have total control. This will also give us flexibility in the future to do things like have browser terminal talking to a CLI on the host via websockets.

Also use ?ts=2 in the hyperlinks to set the indentation. Also link to the docs on the main page.

Let's create example/src readme.md files like https://github.com/carnesen/cli/blob/322b591cdf4b5738cb1ceb38330019a530c78e1d/examples/src/multiply/readme.md programmatically as a build step.

That API just isn't ready to be public. The consumer of that API in website can just require that module directly.

Use the opportunity to write a new command for cloning all @carnesen repos for archival and/or development purposes.

For this release, our second, we will have to figure out how to serve multiple versions in website-server.

It would be nice if we had a list of features (hidden leaf, hidden command, multi-line comment, special errors, etc.) with links to specific examples especially with #86 .

Until we get around to some other branding let's just use the www.carnesen.com favicons.

• Write up "Features" in readme.md
• Fill out "Structure" in readme.md
• Write examples/readme.md
• ValuedParser --> ArgGroup : #58
• Close alwayscli issues
• Contact dependents and offer upgrade assistance

Software projects should provide their users with clarity on the release and maintenance schedule. See Node.js for example. This task will be complete when we have defined our release and maintenance schedule.

Content goes into

• here
• changelog
• 0.5.0 commit message
• GitHub release

Should include the diff link

It would be super slick to get the initial "line" from the URL query string parameters so that we could link into the examples as live documentation for features.

Contractually MonaLisa must be acknowledged. XTerm.js is a pretty rad project too so let's thank them too. I imagine this being implemented as the same footer as the docs site, possibly even precisely that footer.

This should hopefully a be a pretty non-offensive tracker to our audience. Most of them will probably block it anyway. (I know I do which makes debugging harder.) But hopefully it will give us a better sense of our app's performance and what kind of errors we're encountering if any.

https://docs.datadoghq.com/real_user_monitoring/installation/?tab=us

As a published package, @carnesen/cli-examples should have a legitimate readme.md and changelog.md.

Currently the feature cli --help is undocumented. This task will be complete when it's accurately represented in the command-line usage and readme.md.

How cool would it be if we could get some live @carnesen/cli examples running in a browser app? Maybe we could run it in a browser directly. If that doesn't work for some reason, perhaps we could set up some kinda web socket situation and run the commands on the server and just have a terminal (e.g. xterm.js) running on the front end.

In Node.js, console.log

In the the browser currently we have a very hacky way of handling that:

This enhancement is to find or build a library for doing that pretty-printing for us in the browser.

For listing commands in usage a one-liner "summary" would be best but if you did command --help it would be better to get a more in-depth text description.

It's a pretty common requirement to provide an email address by command-line argument. Let's provide a factory for email arg groups with some validation built in.

• CliEmailArgGroup: string-valued for a single email
• CliEmailsArgGroup: string[]-values for multiple

The CliRepl in the cli-website module has really worked out well. The autocompletion is super slick. That feature is worthy of promotion to the main module @carnesen/cli and it should be possible too since we only lightly use the Terminal interface from XTerm.js. To do so we need to make CliRepl pure dependency-free JavaScript and suitable for Node.js too. Probably it should just be an ordinary object factory too like CliBranch etc. instead of a class like it is today.

Use cases:

• Browser: Dedicated browser CLIs like https://cli.carnesen.com
• Node.js: my-cli repl: The CliRepl autocompletion is really good and useful even when we have productized shell autocompletion. There will be really slick things we can do in the custom REPL that wouldn't be possible in a normal shell REPL. Think of it like the mysql or redis-cli REPLs.

It occurs to me that we can attach a CLI to the global context and access it through the console. That's for sure the simplest way to run a CLI in the browser. Let's formalize that concept as an MVP for browser CLI.

It would be great if --help could be autocompleted where it would be useful to the user

Also redirect /docs to /docs/latest

In the same way that we can generate usage documentation automatically in the terminal, lets write a function that generates html docs for a CLI

We'll point people to examples/src as a place to go to see examples of how to use the project. Let's be sure that source code has nice helpful tsdoc strings.