buninu 0.4.0 → 0.4.2

package/apps/bunmsh/help/curl.md

@@ -0,0 +1,181 @@
+## curl
+
+Transfer a URL over HTTP or HTTPS, built on Bun's own `fetch`.
+
+This is a **fallback builtin**: a real `curl` found on `PATH` always wins, so
+scripts keep the system binary where there is one and still run on a device
+that has none. `builtin curl` selects this implementation explicitly.
+
+### Usage
+
+```sh
+curl [OPTIONS] URL...
+```
+
+A URL with no scheme gets one: `http://` by default, `https://` when the port
+is `443`, or whatever `--proto-default` says. So `curl localhost:8080` and
+`curl example.com/page` work the way they do with the real curl. Only `http`
+and `https` are supported; anything else fails with exit code `1`.
+
+### Options and forms
+
+#### Output and files
+
+- `-o, --output FILE`: Write the body to `FILE` instead of stdout. `-o -`
+  means stdout. Repeat it to pair one target with each URL, in order.
+- `-O, --remote-name`: Save under the filename from the URL path.
+- `--remote-name-all`: Treat every URL as if it had its own `-O`.
+- `-J, --remote-header-name`: With `-O`, prefer the name in the
+  `Content-Disposition` header.
+- `--output-dir DIR`: Write `-o`/`-O` files under `DIR`.
+- `--create-dirs`: Create missing parent directories for the output file.
+- `-a, --append`: Append to the output file instead of truncating it.
+- `-C, --continue-at OFFSET|-`: Resume a partial download. `-` sizes the
+  existing file and asks for the rest with a `Range` header; the file is
+  appended to when the server answers `206`, and rewritten when it answers
+  `200` and ignored the range. A `416` answer means the local file is already
+  complete: nothing is written and the exit status is `0`.
+- `-D, --dump-header FILE`: Write the response headers to `FILE` (`-` for
+  stdout).
+- `-i, --include`: Print the response headers before the body. With `-L`,
+  every hop's headers are printed, as the real curl does.
+- `-I, --head`: Send `HEAD` and print the response headers.
+- `-w, --write-out FORMAT`: Print `FORMAT` after the transfer, with
+  `%{variable}` substitutions and `\n`, `\t`, `\r` escapes. `@FILE` (or `@-`)
+  reads the format from a file. Supported variables: `url`, `url_effective`,
+  `method`, `scheme`, `http_code`, `response_code`, `http_version`,
+  `num_redirects`, `num_headers`, `redirect_url`, `size_download`,
+  `size_upload`, `size_header`, `size_request`, `speed_download`,
+  `speed_upload`, `content_type`, `filename_effective`, `remote_ip`,
+  `remote_port`, `ssl_verify_result`, `exitcode`, `errormsg`, `time_total`,
+  `time_namelookup`, `time_connect`, `time_appconnect`, `time_pretransfer`,
+  `time_starttransfer`, `time_redirect`, `header_json`, `json`, `stdout`,
+  `stderr`.
+
+#### Request shaping
+
+- `-X, --request METHOD`: Set the request method.
+- `-H, --header 'Name: value'`: Add or replace a header. `'Name;'` sends an
+  empty value; `'Name:'` removes a header that would otherwise be sent.
+- `-d, --data DATA`, `--data-ascii DATA`: `POST` body; `@file` reads a file
+  (newlines stripped) and `@-` reads stdin. Repeats join with `&`.
+- `--data-raw DATA`: Same, but `@` has no special meaning.
+- `--data-binary DATA`: Same, but a `@file` is sent byte for byte.
+- `--data-urlencode DATA`: Percent-encode before sending. Accepts `content`,
+  `=content`, `name=content`, `@file`, and `name@file`.
+- `--json DATA`: `--data-binary` plus `Content-Type: application/json` and
+  `Accept: application/json`. `@file` and `@-` work here too.
+- `-G, --get`: Move the data onto the query string and send `GET`.
+- `-F, --form 'name=value'`, `--form-string`: `multipart/form-data`. `@file`
+  attaches a file, `<file` sends its contents as the field value, and
+  `;type=` / `;filename=` set the part's type and name.
+- `-T, --upload-file FILE`: `PUT` the file (`-` reads stdin).
+- `-u, --user USER[:PASSWORD]`: HTTP basic authentication.
+- `--oauth2-bearer TOKEN`: Send `Authorization: Bearer TOKEN`.
+- `-A, --user-agent NAME`: Override the default `curl/8.14.1`.
+- `-e, --referer URL`: Send a `Referer` header; a trailing `;auto` is ignored.
+- `-b, --cookie 'k=v'`: Send a `Cookie` header.
+- `-r, --range RANGE`: Send `Range: bytes=RANGE`.
+- `--compressed`: Ask for and transparently decode a compressed response.
+  Without it, no `Accept-Encoding` is negotiated, matching curl's default.
+- `-x, --proxy URL`: Send the request through a proxy.
+
+#### Redirects, failure, and timing
+
+- `-L, --location`: Follow redirects. `301`/`302`/`303` turn a `POST` into a
+  `GET`; `307`/`308` keep the method and body. `Authorization` is dropped when
+  the host changes, unless `--location-trusted` is given.
+- `--max-redirs N`: Cap the redirect chain (default 50, `-1` for unlimited).
+  Exceeding it fails with exit code `47`.
+- `-f, --fail`: No body output on HTTP errors; exit `22` instead.
+- `--fail-with-body`: Print the body and still exit `22`.
+- `-k, --insecure`: Do not verify the server certificate.
+- `-m, --max-time SECONDS`, `--connect-timeout SECONDS`: Abort a slow
+  transfer with exit code `28`.
+- `--retry N`, `--retry-delay SECONDS`, `--retry-all-errors`,
+  `--retry-connrefused`: Retry connection failures, timeouts, and the
+  transient statuses `408`, `429`, `500`, `502`, `503`, and `504`.
+
+#### Reporting
+
+- `-s, --silent`: No progress meter and no error messages.
+- `-S, --show-error`: Keep error messages while `-s` is in effect.
+- `-#, --progress-bar`: A single-bar progress display instead of the meter.
+- `--no-progress-meter`: Keep errors, drop the meter.
+- `-v, --verbose`: Trace the request and response headers on stderr.
+- `-V, --version`: Print the version banner.
+
+Like the real curl, the progress meter is shown only when the body is *not*
+being painted on the terminal — a `-o`/`-O` download or a redirected stdout
+gets a meter, `curl URL` at a prompt does not.
+
+#### Accepted and ignored
+
+These are parsed so a script does not die on them, and then have no effect,
+because `fetch` either handles that part itself or does not expose it:
+`--cacert`, `--capath`, `-E/--cert`, `--key`, `--interface`, `--limit-rate`,
+`--resolve`, `--connect-to`, `--unix-socket`, `--noproxy`, `--proxy-user`,
+`--proxy-header`, `-n/--netrc`, `-c/--cookie-jar`, `-z/--time-cond`,
+`-R/--remote-time`, `-N/--no-buffer` (output is always streamed anyway),
+`-g/--globoff` (URL globbing is not performed, so `{}` and `[]` are already
+literal), `-q/--disable`, `-4`, `-6`, `--http1.0`, `--http1.1`, `--http2`,
+`--http3`, `--tlsv1.x`, `--tcp-nodelay`, `--keepalive`, `--anyauth`,
+`--basic`, `--digest`, `-Z/--parallel`, `--max-filesize`, `--path-as-is`.
+
+### Where it differs from the system curl
+
+- `fetch` reports header names in lower case, so `-i`, `-I`, `-D`, and `-v`
+  rebuild the conventional capitalisation (`Content-Type`, `ETag`) and list
+  the headers in `fetch`'s order rather than the server's wire order.
+- The negotiated HTTP version is not exposed, so status lines are written as
+  `HTTP/1.1`.
+- Bun adds a `Connection: keep-alive` request header of its own.
+- The progress meter is a look-alike: same columns, not the same arithmetic.
+- URL globbing (`{a,b}`, `[1-10]`) is not implemented.
+- `fetch` forbids a body on `GET` and `HEAD`, so `-X GET -d ...` sends the
+  request without the data; use `-G` to put it on the query string instead.
+
+### Exit status
+
+`0` on success, `1` unsupported protocol, `2` bad usage, `3` malformed URL,
+`6` host not resolved, `7` connection failed, `22` HTTP error with `-f`,
+`23` write error, `26` local file could not be read, `28` timeout,
+`47` too many redirects, `56` connection reset, `60` certificate problem.
+
+### Example
+
+```sh
+curl -s -o /dev/null -w '%{http_code} %{content_type}\n' example.com
+```
+
+Output:
+
+```text
+200 text/html
+```
+
+The invocations a package script tends to use:
+
+```sh
+curl -kLO https://example.com/pkg.tar.gz
+curl -C - -kLO https://example.com/pkg.tar.gz
+curl -fsSL https://example.com/install.sh | sh
+curl -#k https://example.com/pkg.tar.gz.sha256
+curl -kfsS https://example.com/probe >/dev/null 2>/dev/null
+curl localhost:8080
+```
+
+Calling a JSON API — enough for the OpenAI chat completions endpoint:
+
+```sh
+curl -sS https://api.openai.com/v1/chat/completions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'
+```
+
+`--json` shortens that, and `-N` streaming responses arrive chunk by chunk:
+
+```sh
+curl -sN --json @request.json https://api.openai.com/v1/chat/completions
+```

package/apps/bunmsh/help/kill.md

@@ -12,6 +12,22 @@ kill [-SIGNAL] PID ...
 
 - `-SIGNAL`: Select a signal by name or number; the default is SIGTERM.
 - `-0`: Check whether a process can be signalled without sending a signal.
+- `-l`: List the signal names this runtime knows.
+
+### Windows
+
+Windows has no signals to deliver. The runtime turns SIGTERM, SIGINT, and
+SIGKILL into an unconditional `TerminateProcess`, refuses every other name,
+and in no case touches the target's children. So on Windows every terminating
+signal is sent as `taskkill /PID PID /T /F` instead: `/T` reaches the children
+the runtime would leave running, and `/F` is what makes it work on a console
+process that has no message loop to close.
+
+The consequence is that the signal name is accepted but not honoured there —
+`kill -HUP PID` terminates the process rather than failing, and nothing gets
+the chance to shut down gracefully. `-0` is the exception: it asks whether the
+PID exists without touching it, which `taskkill` cannot express, so it still
+goes through the runtime.
 
 ### Example
 

package/apps/bunmsh/help/pspa.md

@@ -0,0 +1,38 @@
+## pspa
+
+List every process as a PID and its full command line.
+
+### Usage
+
+```sh
+pspa
+```
+
+It is a PATH-fallback builtin, so an executable named `pspa` found in `PATH`
+wins; `builtin pspa` selects this implementation. It takes no options — pipe
+it into `grep` to narrow the listing, and into `kill` to act on what you find.
+
+[`pspac`](#pspac) prints the same listing with the PID and the command line
+coloured.
+
+On POSIX systems this is `ps -eo pid,args`, and its output is passed through
+untouched. Reading `ps` over a pipe is also what keeps the command lines
+whole: procps truncates them at the terminal width when it is writing straight
+to a terminal.
+
+Windows has no `ps`, so the same two columns are queried from
+`Win32_Process` through PowerShell and laid out the same way, with the image
+name standing in for a system process that reports no command line.
+
+### Example
+
+```sh
+pspa | grep bun
+```
+
+Output:
+
+```text
+ 1004 bun ./src/main.js
+ 1220 bun run dev
+```

package/apps/bunmsh/help/pspac.md

@@ -0,0 +1,57 @@
+## pspac
+
+The `pspa` process listing, coloured.
+
+### Usage
+
+```sh
+pspac
+```
+
+It is a PATH-fallback builtin taking no options, and it lists exactly what
+[`pspa`](#pspa) lists — same processes, same two columns, same order. Strip
+the colour off its output and you have `pspa`'s byte for byte.
+
+Like `catfancy`, it always colours rather than sniffing for a terminal, so the
+plain listing is always one command away: use `pspa` when the output is going
+somewhere that wants plain text.
+
+### What gets coloured
+
+The PID is painted as the number it is. The COMMAND column is a shell command
+line, so it is highlighted as one, using micro's `syntax/sh.yaml` rules and
+its `colorschemes/monokai.micro` colours — the same palette `catfancy` uses,
+so a command line reads the same here as in a previewed script:
+
+- Command names, shell keywords, flags, numbers, variables, quoted strings,
+  and comments each take their own colour.
+- Quoted strings and comments are regions, so a `#` inside an argument does
+  not turn the rest of the line into a comment.
+- Later rules win, exactly as in the editor: `--cat` is a flag, not the
+  coreutils `cat`.
+
+Two things a process listing needs that a script does not:
+
+- The directory in front of the program is dimmed. It is the part an absolute
+  path buries the answer in, and `ps` prints a lot of it.
+- The program's own name is coloured as a command whether or not sh.yaml's
+  word lists have heard of it — the file has to guess a command from a list,
+  while here the first token is known to be one.
+
+A kernel thread such as `[kworker/0:1]` has no program, path, or arguments to
+take apart, so it recedes as a whole.
+
+### Example
+
+```sh
+pspac
+```
+
+Output:
+
+```text
+  PID COMMAND
+    1 /init
+ 8824 /data/data/com.termux/files/usr/bin/bash -l
+ 8955 bun run dev
+```

package/apps/bunmsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunmsh",
-  "version": "0.2.0",
+  "version": "0.3.3",
   "description": "Cross-platform command shell for Bun JavaScript",
   "license": "MIT",
   "type": "module",
@@ -10,7 +10,8 @@
   },
   "scripts": {
     "start": "bun ./src/main.js",
-    "test": "bun test"
+    "test": "bun test",
+    "genallhelp": "bun ./src/main.js -c 'builtin cat --exclude help/README.md help/*.md' > help/README.md"
   },
   "keywords": [
     "bun",
@@ -21,6 +22,9 @@
   "assets": [
     "README.md",
     "CHANGELOG.md",
+    "LICENSE",
+    "LICENSE-MKSH",
+    "LICENSE-MICRO",
     "help"
   ]
 }

package/apps/bunmsh/src/completion.js

@@ -75,6 +75,21 @@ export function completionContext(line, cursor = line.length) {
       quote = ch;
       continue;
     }
+    //  `$(` opens a nested command list, so what follows it is a command
+    //  name again rather than a continuation of the word being typed.
+    if (ch === "$" && source[i + 1] === "(") {
+      finishWord();
+      command = true;
+      token = "";
+      i++;
+      wordStart = i + 1;
+      continue;
+    }
+    if (ch === ")") {
+      finishWord();
+      wordStart = i + 1;
+      continue;
+    }
     if (ch === ";" || ch === "|" || ch === "&" || ch === "\n") {
       finishWord();
       command = true;
@@ -96,9 +111,38 @@ export function completionContext(line, cursor = line.length) {
     command: command && !assignment && quote === null,
     prefix: token,
     start: wordStart,
+    quote,
   };
 }
 
+//  A `$` with a name being typed after it: `$NAME`, `${NAME`, `${#NAME`.
+//  Everything else a `$` can begin is left alone, because none of it is a
+//  name in progress: `$(` opens a command substitution, `$?`/`$1`/`$$` are
+//  already complete, and a backslash-escaped `\$` is a literal dollar sign.
+export function variableContext(line, cursor = line.length) {
+  const source = line.slice(0, cursor);
+  const match = /\$(\{#?)?([A-Za-z_][A-Za-z0-9_]*)?$/.exec(source);
+  if (!match) return null;
+  if (source[match.index - 1] === "$") return null;
+  let backslashes = 0;
+  for (let i = match.index - 1; i >= 0 && source[i] === "\\"; i--) backslashes++;
+  if (backslashes % 2) return null;
+  const name = match[2] ?? "";
+  return {
+    start: match.index,
+    text: match[0],
+    lead: match[0].slice(0, match[0].length - name.length),
+    brace: Boolean(match[1]),
+    prefix: name,
+  };
+}
+
+//  `${NAME` completes to `${NAME}`: the brace it opened is part of the name
+//  being written, so finishing the name finishes the brace too.
+export function variableCompletion(context, name) {
+  return `${context.lead}${name}${context.brace ? "}" : ""}`;
+}
+
 export function historyGhost(history, line) {
   if (!line) return null;
   for (let i = history.length - 1; i >= 0; i--) {
@@ -199,6 +243,78 @@ export class CommandIndex {
   }
 }
 
+//  A JavaScript line is not shell text, so the shell's own word-splitting says
+//  nothing useful about it: `Bun.file("/tm` is one long word to a tokenizer
+//  that only breaks on whitespace. This reads it as JavaScript instead, and
+//  answers the two questions worth asking there — is the cursor inside a
+//  string literal, where a path is being typed, or on a `$.` property, where
+//  a shell variable name is.
+//
+//  Strings are tracked with a stack so that an interpolation is code again:
+//  inside `\`${...}\`` a `$.` completes, and the template only resumes after
+//  the closing brace.
+export function javascriptContext(line, cursor = line.length) {
+  const source = line.slice(0, cursor);
+  const stack = [];
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    const top = stack.at(-1);
+    if (top?.kind === "string") {
+      if (ch === "\\") { i++; continue; }
+      if (top.quote === "`" && ch === "$" && source[i + 1] === "{") {
+        stack.push({ kind: "code" });
+        i++;
+        continue;
+      }
+      if (ch === top.quote) stack.pop();
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      stack.push({ kind: "string", quote: ch, start: i + 1 });
+      continue;
+    }
+    if (ch === "}" && top?.kind === "code") stack.pop();
+  }
+  const top = stack.at(-1);
+  //  An unclosed string is a path being typed, whatever else is on the line.
+  if (top?.kind === "string")
+    return { kind: "path", prefix: source.slice(top.start), quote: top.quote, text: source.slice(top.start) };
+  //  `$` alone is the table object itself, so only the property form
+  //  completes: a name is being written only after the dot.
+  const match = /\$\.([A-Za-z_][A-Za-z0-9_]*)?$/.exec(source);
+  if (!match) return null;
+  const name = match[1] ?? "";
+  return { kind: "variable", prefix: name, text: match[0], lead: "$.", brace: false };
+}
+
+//  Names come from the shell's own variable table, so completion offers what
+//  expansion would actually find — exported or not, and including anything
+//  JavaScript mode wrote through `$`.
+export class VariableIndex {
+  constructor() {
+    this.names = [];
+    this.signature = null;
+  }
+
+  sync(state) {
+    const keys = Object.keys(state.env);
+    const signature = keys.join("\0");
+    if (signature === this.signature) return;
+    this.signature = signature;
+    this.names = keys.sort();
+  }
+
+  matches(state, prefix) {
+    this.sync(state);
+    return prefix ? prefixMatches(this.names, prefix) : [...this.names];
+  }
+
+  first(state, prefix) {
+    this.sync(state);
+    return prefix ? firstPrefixMatch(this.names, prefix) : null;
+  }
+}
+
 export class FileIndex {
   constructor(ttl = 10_000) {
     this.ttl = ttl;