carnesen / cli Goto Github PK
View Code? Open in Web Editor NEWA command-line interface (CLI) framework for Node.js and web browser
Home Page: https://cli.carnesen.com
License: MIT License
A command-line interface (CLI) framework for Node.js and web browser
Home Page: https://cli.carnesen.com
License: MIT License
Also redirect /docs to /docs/latest
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.
That API just isn't ready to be public. The consumer of that API in website can just require that module directly.
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.
It would be slick if --copy copied it into copy paste buffer too
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.
Add a section to the main readme file describing this repository's structure with links.
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.
Or maybe labels 1, 2, 3, 5, 7 as complexity estimates, agile-style.
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.
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
Or something like that to demo usage of JSON arguments
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 simply
echo "foo"` and have it behave as they'd expect in a shell.
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/
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.
It would be great if --help could be autocompleted where it would be useful to the user
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 emailCliEmailsArgGroup
: string[]
-values for multipleUntil we get around to some other branding let's just use the www.carnesen.com favicons.
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.
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
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:
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.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.
Now that we are publishing the generated documentation to the web #29 , let's make sure it's complete!
It would look really slick if we could put a screen recording for "how that works as a CLI" in the readme.
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.
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.
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.
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.
This task will be complete when the API docs are publish to the world wide web.
As a published package, @carnesen/cli-examples should have a legitimate readme.md and changelog.md.
In the the browser currently we have a very hacky way of handling that:
Lines 173 to 188 in 9d807d4
This enhancement is to find or build a library for doing that pretty-printing for us in the browser.
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 .
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
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.
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.
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.
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.
Also use ?ts=2
in the hyperlinks to set the indentation. Also link to the docs on the main page.
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
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.
For this release, our second, we will have to figure out how to serve multiple versions in website-server.
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.
Use the opportunity to write a new command for cloning all @carnesen repos for archival and/or development purposes.
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.
For a password for example it's sometimes convenient for security purposes to pass in sensitive data via standard input
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.
Content goes into
Should include the diff link
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.