@gutenye/script.js 1.1.0 → 2.0.0

package/README.md

@@ -1,85 +1,99 @@
-# 🧩 Script.js 🧩
+# Script.js
 
-**Write shell scripts in JavaScript** and leverage the power of JavaScript’s simplicity and flexibility to make your shell scripting easier and faster. Why struggle with the complexity of Bash or other shell scripting languages when you already know JavaScript? Script.js allows you to write and run complex shell scripts using JavaScript, saving you time and reducing errors.
+**Write shell scripts in JavaScript** and leverage the power of JavaScript's simplicity and flexibility to make your shell scripting easier and faster. Why struggle with the complexity of Bash or other shell scripting languages when you already know JavaScript? Script.js allows you to write and run complex shell scripts using JavaScript, saving you time and reducing errors.
 
 **Show your ❤️ and support by starring this project and following the author, [Guten Ye](https://github.com/gutenye)!**
 
-[![Stars](https://img.shields.io/github/stars/gutenye/script.js?style=social)](https://github.com/gutenye/script.js) [![NPM Version](https://img.shields.io/npm/v/@gutenye/script.js)](https://www.npmjs.com/package/@gutenye/script.js) [![License](https://img.shields.io/github/license/gutenye/script.js?color=blue)](https://github.com/gutenye/script.js/blob/main/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-blue)](https://github.com/gutenye/script.js#-contribute)
+[![Stars](https://img.shields.io/github/stars/gutenye/script.js?style=social)](https://github.com/gutenye/script.js) [![NPM Version](https://img.shields.io/npm/v/@gutenye/script.js)](https://www.npmjs.com/package/@gutenye/script.js) [![License](https://img.shields.io/github/license/gutenye/script.js?color=blue)](https://github.com/gutenye/script.js/blob/main/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-blue)](https://github.com/gutenye/script.js#contribute)
 
-## 🌟 Features
+## Features
 
-- **Fast to write**: The most important factor in script writing is **speed**. With Script.js, you can quickly open the editor, write a few lines of code, and run it instantly. Thanks to global commands, you don’t need to worry about import statements, and more. Writing a script is enjoyable and efficient.
-- **Fun to run**: A major benefit of using a script is **autocompletion**. Script.js includes built-in autocompletion support. Running a script is fun and seamless.
-- **JavaScript Power**: Writing complex scripts in JavaScript and access the entire JavaScript ecosystem.
-- **Familiar Syntax**: Write your shell commands just like you would in Bash, with full support for redirection, pipes, environment variables, and more.
+- **Fast to write**: Global commands mean no imports needed. Open the editor, write a few lines, and run it.
+- **Fun to run**: Built-in autocompletion support via Carapace.
+- **JavaScript Power**: Access the entire JavaScript ecosystem.
 - **Subcommands**: Create and organize subcommands effortlessly.
-- **Help Documentation**: Auto-generate command help documentation for better user experience.
-- **Fast Execution**: Fast to execute your scripts.
+- **Help Documentation**: Auto-generated command help with argument validation.
+- **Fast Execution**: Powered by Bun for fast startup and execution.
 
-## 🚀 Getting Started
+## Getting Started
 
-### 1️⃣ Install
+### 1. Install
 
 First, make sure [Bun](https://bun.sh) and [Carapace](https://github.com/carapace-sh/carapace-bin) are installed.
 
-To install Script.js, run:
-
 ```sh
 npm install -g @gutenye/script.js
 ```
 
-### 2️⃣ Write Your First Script
+### 2. Write Your First Script
 
-Create a file named `hello.js` and add the following code:
+**Via script.js** — globals are set up automatically, no imports needed:
 
 ```ts
 #!/usr/bin/env script.js
 
+app.meta("hello");
+
+app
+  .cmd("greetings", "Say hello")
+  .add("[...files]", "Files", ["$files"])
+  .add((files, ctx) => {
+    $`ls -l ${files}`;
+  });
+```
+
+**Via import** — use as a library in any Bun script:
+
+```ts
+#!/usr/bin/env bun
+
+import { app, $ } from "@gutenye/script.js";
+
+app.meta("hello");
+
 app
-  .name('hello.js')
-  .enableCompletion()
-
-app.command('greetings [files...]')
-  .completion({
-    positionalany: ['$files'],
-  })
-  .action((files, options) => {
-    $`
-      ls -l ${files}
-      echo ${files} | wc -l
-    `
-  })
+  .cmd("greetings", "Say hello")
+  .add("[...files]", "Files", ["$files"])
+  .add((files, ctx) => {
+    $`ls -l ${files}`;
+  });
+
+await app.run();
 ```
 
-### 3️⃣ Run the script
+### 3. Run the script
 
 You can use `<Tab>` to autocomplete arguments or options while using the script.
 
 ```sh
-chmod +x hello.js   # Make the script executable
-./hello.js          # First run to create completion file
-./hello.js <Tab>    # Use Tab key for autocompletion
+chmod +x hello         # Make the script executable
+./hello                # First run to create completion file
+./hello <Tab>          # Use Tab key for autocompletion
 ```
 
-## 📖 Documentation
+## Documentation
 
-- [Create Commands](./docs/Create%20Commands.md): Create commands and subcommands
+- [Create Commands](./docs/Create%20Commands.md): Create commands, subcommands, and manage dependencies
 - [Completion](./docs/Completion.md): Customize the autocompletion
 - [Global Commands](./docs/Global%20Commands.md): List of global variables and commands
+- [Ake](./src/ake): A task runner supports shell autocompletion
 
-## 🙇 Thanks
+## v2
 
-- [Bun](https://github.com/oven-sh/bun): Incredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one
-- [Carapace](https://github.com/carapace-sh/carapace-bin): A multi-shell completion binary
-- [Zurk](https://github.com/webpod/zurk): A generic process spawner
-- [Zx](https://github.com/google/zx): A tool for writing better scripts
-- [Commander.js](https://github.com/tj/commander.js): node.js command-line interfaces made easy
+v2 is a complete rewrite from scratch. It removes heavy dependencies, replacing them with a lightweight, custom-built CLI framework. A cleaner syntax, the smallest set of global variables, and using vanilla JavaScript as much as possible. You should be able to write scripts quickly without looking up documentation — if you know JavaScript, you know the API.
 
-## 🤝 Contribute
+See [Migration from v1](./docs/Migration.md) for a full migration guide.
+
+Looking for v1 documentation [here](https://github.com/gutenye/script.js/tree/v1)
+
+## Thanks
+
+- [Bun](https://github.com/oven-sh/bun): Incredibly fast JavaScript runtime, bundler, test runner, and package manager
+- [Carapace](https://github.com/carapace-sh/carapace-bin): A multi-shell completion binary
 
-We love contributions! Whether you’re fixing bugs, adding features, or improving documentation, your involvement makes this project better.
+## Contribute
 
-**How to Contribute:**
+We love contributions! Whether you're fixing bugs, adding features, or improving documentation, your involvement makes this project better.
 
 1. Fork the Repository
 2. Open a Pull Request on Github

package/package.json

@@ -1,14 +1,34 @@
 {
   "name": "@gutenye/script.js",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Write shell scripts in JavaScript",
-  "keywords": ["shell", "script", "bash", "exec", "spawn", "zx", "bunshell"],
+  "keywords": [
+    "shell",
+    "script",
+    "bash",
+    "exec",
+    "spawn",
+    "zx",
+    "bunshell"
+  ],
   "license": "MIT",
   "repository": "github:gutenye/script.js",
   "type": "module",
-  "files": ["src", "tsconfig.json", "build", "!**/__tests__"],
+  "exports": {
+    "bun": "./src/index.ts",
+    "default": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "tsconfig.json",
+    "build",
+    "!**/__tests__"
+  ],
   "bin": {
-    "script.js": "src/script.ts"
+    "script.js": "src/script.ts",
+    "a": "src/ake.ts",
+    "ake": "src/ake.ts",
+    "akectl": "src/akectl.ts"
   },
   "scripts": {
     "test": "bun test",
@@ -19,26 +39,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@gutenye/commander-completion-carapace": "^1.0.9",
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "csv-parse": "^5.5.6",
-    "lodash-es": "^4.17.21",
-    "table": "^6.8.2",
-    "tiny-invariant": "^1.3.3",
-    "yaml": "^2.6.0",
-    "zx": "^8.2.1"
+    "yaml": "^2.6.0"
   },
   "peerDependencies": {
     "typescript": "^5.7.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
+    "@biomejs/biome": "^2.4.4",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/bun": "latest",
-    "@types/lodash-es": "^4.17.12",
-    "conventional-changelog-conventionalcommits": "^8.0.0",
-    "tsc-alias": "^1.8.10"
+    "conventional-changelog-conventionalcommits": "^8.0.0"
   }
 }

package/src/Argument.ts

@@ -0,0 +1,40 @@
+export class Argument {
+  rawName: string
+  name: string
+  description: string
+  required: boolean
+  variadic: boolean
+  completion: string[] | (() => string[])
+  defaultValue: any
+
+  constructor(
+    rawName: string,
+    description = '',
+    completion: string[] | (() => string[]) = [],
+  ) {
+    this.rawName = rawName.trim()
+    const { name, required, variadic, defaultValue } =
+      Argument.parseName(rawName)
+    this.name = name
+    this.required = required
+    this.variadic = variadic
+    this.description = description
+    this.completion = completion
+    this.defaultValue = defaultValue
+  }
+
+  toString() {
+    return this.rawName
+  }
+
+  static parseName(rawName: string) {
+    const trimmed = rawName.trim()
+    const required = trimmed.startsWith('<')
+    const variadic = trimmed.includes('...')
+    const inner = trimmed.replace(/[<>[\].]/g, '').trim()
+    const eqIndex = inner.indexOf('=')
+    const name = eqIndex !== -1 ? inner.slice(0, eqIndex) : inner
+    const defaultValue = eqIndex !== -1 ? inner.slice(eqIndex + 1) : undefined
+    return { name, required, variadic, defaultValue }
+  }
+}

package/src/Command.ts

@@ -0,0 +1,288 @@
+import { Argument } from './Argument'
+import { installCompletion } from './completion'
+import { Option } from './Option'
+import { parseArgv } from './parseArgv'
+
+export class Command {
+  name?: string
+  description?: string
+  aliases: string[] = []
+  action!: (...args: any[]) => void | Promise<void>
+  arguments: Argument[] = []
+  commands: Command[] = []
+  options: Option[] = []
+  #defaultCommand?: Command
+  #extraHelp?: string
+
+  meta(inputName: string, description = '') {
+    const { name, aliases } = this.#parseAliases(inputName)
+    this.name = name
+    this.aliases = aliases
+    this.description = description
+    return this
+  }
+
+  help(text?: string) {
+    if (text != null) {
+      this.#extraHelp = text.trim()
+      return this
+    }
+    console.log(this.helpText())
+  }
+
+  cmd(inputName?: string, description = '') {
+    const command = new Command()
+    if (inputName) {
+      const { name, aliases } = this.#parseAliases(inputName)
+      command.name = name
+      command.aliases = aliases
+      command.description = description
+      this.commands.push(command)
+    } else {
+      this.#defaultCommand = command
+    }
+    return command
+  }
+
+  async invoke(text: string, ...args: any[]) {
+    if (args.length === 0) {
+      return this.parse(text.split(/ +/))
+    }
+    const command = this.#findCommand(text)
+    if (!command) {
+      throw new Error(`Unknown command: ${text}`)
+    }
+    return command.action?.(...args)
+  }
+
+  async runViaScriptJs() {
+    installCompletion(this, { scriptPath: Bun.argv[2] })
+    return this.parse(Bun.argv.slice(3))
+  }
+
+  // runViaBun
+  async run() {
+    installCompletion(this, { scriptPath: Bun.main })
+    return this.parse(Bun.argv.slice(2))
+  }
+
+  async parse(argv: string[]): Promise<void> {
+    const commandName = argv[0]
+    if (commandName === '-h') {
+      console.log(this.helpText())
+      return process.exit(0)
+    }
+    if (!commandName) {
+      if (this.#defaultCommand) {
+        return this.#runDefault(argv)
+      }
+      console.log(this.helpText())
+      return process.exit(0)
+    }
+    const command = this.#findCommand(commandName)
+    if (!command) {
+      if (this.#defaultCommand) {
+        return this.#runDefault(argv)
+      }
+      console.log(this.helpText())
+      console.error(`\nUnknown command: ${commandName}`)
+      return process.exit(1)
+    }
+    const commandArgv = argv.slice(1)
+    if (command.commands.length > 0 || command.#defaultCommand) {
+      return command.parse(commandArgv)
+    }
+    if (commandArgv.includes('-h')) {
+      console.log(command.helpText())
+      return process.exit(0)
+    }
+    const { positionals, options } = parseArgv(
+      commandArgv,
+      command.arguments,
+      command.options,
+    )
+    const context: Context = { argv: commandArgv }
+    await this.#invokeAction(command, positionals, options, context)
+  }
+
+  a = this.add.bind(this)
+
+  add(...args: any[]) {
+    if (typeof args[0] === 'function') {
+      this.action = args[0]
+    } else {
+      let [inputName, description, completionOrDefault] = args
+
+      if (typeof description !== 'string') {
+        if (completionOrDefault) {
+          throw new Error(
+            'Invalid third argument, should be a(name, description, completion) format',
+          )
+        }
+        completionOrDefault = description
+        description = ''
+      }
+
+      const name = inputName.trim()
+      if (name.startsWith('-')) {
+        this.options.push(new Option(name, description, completionOrDefault))
+      } else {
+        this.arguments.push(
+          new Argument(name, description, completionOrDefault),
+        )
+      }
+    }
+
+    return this
+  }
+
+  helpText() {
+    const lines: string[] = []
+    const name = this.name || 'app'
+    if (this.commands.length > 0) {
+      lines.push(`Usage: ${name} <command>`)
+      lines.push('')
+      lines.push('Commands:')
+      const labels = this.commands.map((c) => {
+        const names = [c.name, ...c.aliases]
+          .sort((a, b) => (a?.length ?? 0) - (b?.length ?? 0))
+          .join(', ')
+        const args = c.#argsText()
+        return args ? `${names} ${args}` : names
+      })
+      const maxLen = Math.max(...labels.map((l) => l.length))
+      for (let i = 0; i < this.commands.length; i++) {
+        const padded = labels[i].padEnd(maxLen + 2)
+        lines.push(`  ${padded}${this.commands[i].description || ''}`)
+      }
+    } else {
+      const args = this.#argsText()
+      const usage = args ? `${name} ${args}` : name
+      lines.push(`Usage: ${usage}`)
+      if (this.description) {
+        lines.push('')
+        lines.push(this.description)
+      }
+      if (this.arguments.length > 0) {
+        lines.push('')
+        lines.push('Arguments:')
+        const maxLen = Math.max(...this.arguments.map((a) => a.name.length))
+        for (const arg of this.arguments) {
+          const padded = arg.name.padEnd(maxLen + 2)
+          const choices = Command.#choicesText(arg.completion)
+          const desc = [arg.description, choices].filter(Boolean).join(' ')
+          lines.push(`  ${padded}${desc}`)
+        }
+      }
+      if (this.options.length > 0) {
+        lines.push('')
+        lines.push('Options:')
+        const flags = this.options.map(String)
+        const maxLen = Math.max(...flags.map((f) => f.length))
+        for (let i = 0; i < this.options.length; i++) {
+          const padded = flags[i].padEnd(maxLen + 2)
+          const choices = Command.#choicesText(this.options[i].completion)
+          const desc = [this.options[i].description, choices]
+            .filter(Boolean)
+            .join(' ')
+          lines.push(`  ${padded}${desc}`)
+        }
+      }
+    }
+    if (this.#extraHelp) {
+      lines.push('')
+      lines.push(this.#extraHelp)
+    }
+    return lines.join('\n')
+  }
+
+  async #runDefault(argv: string[]) {
+    const cmd = this.#defaultCommand as Command
+    const { positionals, options } = parseArgv(argv, cmd.arguments, cmd.options)
+    const context: Context = { argv }
+    await this.#invokeAction(cmd, positionals, options, context)
+  }
+
+  async #invokeAction(
+    command: Command,
+    positionals: any[],
+    options: Record<string, any>,
+    context: Context,
+  ) {
+    const error =
+      Command.#validateOptions(command, options) ??
+      Command.#validateChoices(command, positionals)
+    if (error) {
+      console.log(command.helpText())
+      console.error(`\n${error}`)
+      return process.exit(1)
+    }
+    const args = [...positionals]
+    if (command.options.length > 0) {
+      args.push(options)
+    }
+    args.push(context)
+    await command.action?.(...args)
+  }
+
+  #argsText() {
+    return this.arguments.map(String).join(' ')
+  }
+
+  static #validateOptions(
+    command: Command,
+    options: Record<string, any>,
+  ): string | null {
+    for (const opt of command.options) {
+      if (opt.required && options[opt.attributeName] == null) {
+        return `Missing required value for option: ${opt}`
+      }
+    }
+    return null
+  }
+
+  static #validateChoices(command: Command, positionals: any[]): string | null {
+    for (let i = 0; i < command.arguments.length; i++) {
+      const arg = command.arguments[i]
+      const value = positionals[i]
+      if (value == null) continue
+      if (typeof arg.completion === 'function') continue
+      if (arg.completion.length === 0) continue
+      if (arg.completion.some((c) => c.startsWith('$') || /^[<[]/.test(c)))
+        continue
+      const values = arg.variadic ? value : [value]
+      for (const v of values) {
+        if (!arg.completion.includes(v)) {
+          return `Invalid value for ${arg.name}: '${v}' (expected: ${arg.completion.join(', ')})`
+        }
+      }
+    }
+    return null
+  }
+
+  static #choicesText(completion: string[] | (() => string[])): string {
+    const values = typeof completion === 'function' ? completion() : completion
+    if (values.length === 0) return ''
+    const text = values.join(', ')
+    if (text.length <= 40) return `(${text})`
+    return `(${text.slice(0, 37)}...)`
+  }
+
+  #findCommand(name: string) {
+    return this.commands.find(
+      (command) => command.name === name || command.aliases.includes(name),
+    )
+  }
+
+  #parseAliases(inputName: string) {
+    const names = inputName.split('|').map((alias) => alias.trim())
+    const [name, ...aliases] = names
+    return { name, aliases }
+  }
+}
+
+export const app = new Command()
+
+type Context = {
+  argv: string[]
+}

package/src/Option.ts

@@ -0,0 +1,70 @@
+export class Option {
+  rawFlags: string
+  short?: string
+  long?: string
+  description: string
+  required: boolean
+  optional: boolean
+  variadic: boolean
+  negate: boolean
+  attributeName: string
+  completion: string[] | (() => string[])
+  defaultValue: any
+
+  constructor(
+    rawFlags: string,
+    description = '',
+    defaultValueOrCompletion: any = undefined,
+  ) {
+    this.rawFlags = rawFlags
+    this.description = description
+
+    const parts = rawFlags.split('|').map((s) => s.trim())
+    for (const part of parts) {
+      if (part.startsWith('--')) {
+        this.long = part.split(/\s/)[0]
+      } else if (part.startsWith('-')) {
+        const token = part.split(/\s/)[0]
+        if (token.startsWith('--')) {
+          this.long = token
+        } else {
+          this.short = token
+        }
+      }
+    }
+
+    this.required = rawFlags.includes('<')
+    this.optional = rawFlags.includes('[')
+    this.variadic = rawFlags.includes('...')
+    this.negate = this.long?.startsWith('--no-') ?? false
+
+    if (this.long) {
+      let key = this.long.replace(/^--/, '')
+      if (this.negate) key = key.replace(/^no-/, '')
+      this.attributeName = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+    } else if (this.short) {
+      this.attributeName = this.short.replace(/^-/, '')
+    } else {
+      this.attributeName = ''
+    }
+
+    if (
+      Array.isArray(defaultValueOrCompletion) ||
+      typeof defaultValueOrCompletion === 'function'
+    ) {
+      this.completion = defaultValueOrCompletion
+      this.defaultValue = undefined
+    } else {
+      this.completion = []
+      this.defaultValue = defaultValueOrCompletion
+    }
+  }
+
+  toString() {
+    return this.rawFlags.replaceAll('|', ',')
+  }
+
+  isBoolean() {
+    return !this.required && !this.optional && !this.negate
+  }
+}

package/src/ake/README.md

@@ -0,0 +1,44 @@
+# Ake
+
+> A task runner supports shell autocompletion
+
+## Start
+
+1. Create an ake file
+
+edit `./ake` file, and make it executable `chmod +x ake`
+
+```ts
+#!/usr/bin/env script.js
+
+app.cmd('greetings')
+  .add(() => {
+    console.log('greetings')
+  })
+```
+
+2. Run it
+
+```sh
+ake greetings   # find the ake file and runs it
+```
+
+3. Supports Shell Completion 
+
+- Follow [guide](./completions) to setup
+
+```sh
+ake <Tab> # uses ake file's completion
+```
+
+## Use a template
+
+Create `~/bin.src/ake/template`
+
+## Put ake file in another location
+
+Doesn't touch original project files
+
+```sh
+akectl init remote # create in ~/bin.src/ake/<dir>
+```