Toolbox.sh — POSIX CLI Toolkit and Generator

Toolbox.sh is a shell framework for Git-style command suites: a dispatcher maps command paths to executable files, shared libraries provide logging, argument parsing and configuration, and a JSON manifest can describe a new project. The repository contains the source scaffold, command templates and a TAP-style test harness.

flowchart LR
    M["manifest.json"] --> G["tools/generate"]
    G --> S["generated project"]
    S --> B["bin/<name>"]
    B --> R["resolve command path"]
    R --> C["tools/<path>"]
    C --> L["lib/*.sh"]
    C --> H["metadata-driven help"]

    style G fill:#1f6feb,stroke:#58a6ff,color:#fff
    style C fill:#238636,stroke:#3fb950,color:#fff
    style H fill:#8250df,stroke:#bc8cff,color:#fff

Loading

Quick start

The version probe is copy-pasteable from the current checkout:

/bin/sh bin/toolbox --version
/bin/sh bin/toolbox help

Both commands exit successfully: the first prints toolbox 0.1.0, the second lists five discovered commands. ./bin/toolbox also runs directly. The Linux run behind these results is reproducible with:

sh devtools/linux-run.sh

The generator sequence is:

cat >manifest.json <<'JSON'
["status", {"name": "report", "commands": ["daily"]}]
JSON
/bin/sh bin/toolbox generate --name depot --manifest manifest.json --dest ./depot
cd depot
/bin/sh bin/depot help

The sequence completes, and /bin/sh bin/depot help lists the generated report and status commands with the project's own name and version in the help text. sh tests/run inside depot runs the generated tests/commands.t, which checks every command in the manifest and passes.

Architecture

The top-level tree and a generated tree use the same dispatcher and library shape. Directories below tools/ are command groups; an executable __main file represents the group itself.

flowchart TD
    U["user: toolbox <command> [args]"] --> D["bin/toolbox"]
    D --> O["global options and config"]
    D --> Q["tools/<command path>"]
    Q --> P["leaf script"]
    Q --> N["group/__main"]
    P --> K["lib/common.sh<br/>lib/log.sh<br/>lib/args.sh<br/>lib/config.sh"]
    N --> K
    P --> T["lib/cmd.sh metadata"]
    N --> T
    T --> H["help and completion metadata"]

    style D fill:#1f6feb,stroke:#58a6ff,color:#fff
    style K fill:#9e6a03,stroke:#d29922,color:#fff
    style H fill:#8250df,stroke:#bc8cff,color:#fff

Loading

Capabilities

Area	Source	Role	Checked in Linux
Dispatch	bin/toolbox, lib/common.sh	Resolves leaf and grouped command paths.	help lists five commands; hello Alice gets its argument.
Command metadata	lib/cmd.sh, command scripts	Renders usage, options, subcommands and examples.	depot report daily --help renders with the project name.
New commands	tools/new, templates/command/	Copies and fills a leaf or group stub.	new --group demo creates demo/__main.
Project generation	tools/generate, templates/project/	Copies a skeleton, renames its dispatcher and creates manifest paths.	Exits 0; nested report daily runs. Its generated tests pass 10/10.
Completion	tools/completion	Emits shell completion from command metadata.	__all_commands works under dash; not installed into a shell.
Tests	tests/run, tests/*.t	Runs the TAP-style checks.	55/55 under dash and bash.

Results

These values come from devtools/linux-run.sh in python:3.12-slim-bookworm, where /bin/sh is dash, at commit 4b13dec:

Check	Result
tracked files	61
tracked executable files	26
./bin/toolbox --version exit status	0
discovered commands in help	5
tests/run under dash / bash	55 / 55 passed, exit 0
generator exit status	0
generated project tests/run	10 / 10 passed, exit 0

Details are in docs/measurement.md.

Repository layout

Path	Responsibility
bin/toolbox	Top-level dispatcher and global option handling.
lib/	Shared shell libraries for resolution, logging, arguments, config and metadata.
tools/	Built-in commands such as generate, new, hello and completion.
templates/command/	Leaf, group and ignore-file templates.
templates/project/	Files copied into a generated project.
tests/	TAP-like shell tests and their harness.
docs/	Component write-ups, measurements and the Linux run.
devtools/	measure.py probe and the linux-run.sh container run.

Known limitations

• The dispatcher and the generated projects target POSIX sh. Bash-specific syntax in a command file will not be caught by the framework.
• tests/run is a TAP-style harness with no external dependencies; it exercises the dispatcher, tools/new and the generator (including the generated project's own suite), and tests/regressions.t holds regression checks for previously fixed bugs. sh tests/docker.sh runs it in a Debian container. It is not a matrix of shells or platforms.
• The generator writes a skeleton from a fixed template set. A project that needs a different layout has to diverge from the template after generation.
• The checks run on Linux only. The two macOS-specific fixes (6b1fe41 and c58633c) were not re-run on macOS.

Bugs are tracked as GitHub issues.

Further documentation

• docs/architecture.md — dispatcher and scaffold structure.
• docs/GENERATOR_GUIDE.md — manifest and generation lifecycle.
• docs/commands.md — command metadata and conventions.
• docs/measurement.md — the Linux run behind every result.