phuctm97/shell.how

Explain shell commands using next-generation autocomplete Fig.

shell.how ·

Explain shell commands using next-generation autocomplete from Fig.

Contributing

Requirements

• Node 14

• Yarn 1.22+

Setup

1. Install requirements

2. Clone the repository

3. Run yarn to install dependencies

Develop

Tech stack

• TypeScript

• Next.js

• Tailwind CSS

• Recoil for state management, it works natively with React concurrent mode & has builtin caching, allows lean pattern for querying dynamic data (see hooks/use-spec.ts)

• React concurrent mode for loading data before rendering components & handling errors

Start development

• Run yarn start to start development

• Commit adhering to Angular commit convention, use yarn commit or Code conventional commits to commit interactively

• Submit a PR and make sure required status checks pass

• When a PR is merged or code is pushed to main:

  • Vercel deploys latest changes to shell.how

  • Github validates and creates a new release if there're relevant changes

Understand parser

The parser has 2 steps:

1. Escape and split the string into tokens delimited white space, a quoted string is a single token. Nested quotes are supported, too.

2. Load Fig's autocomplete spec for the command (the first token from step 1). Iterate through the tokens, validate, and annotate the tokens with information from the spec.

interface Token extends SimpleToken, Fig.BaseSuggestion {
  indices: [number, number]; // [start, end], end is exclusive
  value: string; // a copy of [start, end) from original string
  type: "command" | "subcommand" | "option" | "argument";
}

Author

Minh-Phuc Tran (@phuctm97) - Fig

shell.how's Issues

Reporting a vulnerability

Hello!

I hope you are doing well!

We are a security research team. Our tool automatically detected a vulnerability in this repository. We want to disclose it responsibly. GitHub has a feature called Private vulnerability reporting, which enables security research to privately disclose a vulnerability. Unfortunately, it is not enabled for this repository.

Can you enable it, so that we can report it?

Thanks in advance!

PS: you can read about how to enable private vulnerability reporting here: https://docs.github.com/en/code-security/security-advisories/repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository

Reporting a vulnerability

Hello!

I hope you are doing well!

We are a security research team. Our tool automatically detected a vulnerability in this repository. We want to disclose it responsibly. GitHub has a feature called Private vulnerability reporting, which enables security research to privately disclose a vulnerability. Unfortunately, it is not enabled for this repository.

Can you enable it, so that we can report it?

Thanks in advance!

PS: you can read about how to enable private vulnerability reporting here: https://docs.github.com/en/code-security/security-advisories/repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository

v1.1

Some of features would be really awesome to have in the next release 🚀:

• Parser: Handle single-quoted strings.
• Parser: Other improvements to make sure parser's first step always return correct number of tokens.
• Parser: Handle advanced syntax of options: grouped options, option using =
• Parser: Handle arguments with isOptional, isPersistent, isRepeatable, etc, differently.
• Performance: Install Fig's completion spec locally and static render first result → avoid (many) network calls client-side.
• SEO: Generate static sitemaps for all commands defined in spec → increase SEO, potentially make this the best place to search & learn shell command 🔥.
• Socials: Generate OG image dynamically for command being queried.

Support Substitutions

IE: sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Option is unknown with ls

I get an error with ls -la --sort=date

Sudo subcommands invalid

https://www.shell.how/sudo%20apt%20update

I think this shows enough 😆

support for newer node version

as a fig user i was excited to build and play with shell.how as well as considering it likely to be helpful in building/debugging fig completions.

however, the node 14 requirement is a show-stopper as V8 8.6 is required to build node for the arm64 architecture (for m1 macs) which as far as i know is only available in node 15 and greater.

while i know it is technically possible to run node 14 in translated/rosetta mode, i'm not interested in pursuing that bag of hurt.

Fails to parse some commands

Hey there!

It looks like we can break the command parsing pretty easily. Here are some examples:

• https://www.shell.how/tar%20xzf%20foo.tar.gz (tar xzf foo.tar.gz)
• https://www.shell.how/ls%20-lah (ls -lah)