Crust CLI Framework

Crust is a modular ecosystem of packages designed for building TypeScript and Bun-native CLI tools. Key packages include:

• @crustjs/crust: CLI tooling for building and distributing standalone executables.
• @crustjs/core: The engine for command definition, argument parsing, routing, plugins, and error handling.
• @crustjs/extensions: Official extensions providing help, version, and completion functionality.
• @crustjs/style: The foundation for terminal styling.
• @crustjs/progress: Progress indicators for managing async CLI tasks.
• @crustjs/prompts: Tools for creating interactive terminal prompts.
• @crustjs/store: Typed persistence with separation for config, data, state, and cache.
• @crustjs/skills: Generates agent skills from Crust command definitions.
• @crustjs/create: A headless scaffolding engine for building your own create-xxx tools.
• create-crust: The primary project scaffolding tool.

When running crust build without a specific --target, the tool generates a distribution package in the dist/ directory containing:

1. Platform-specific binaries: Named dist/<name>-<target> (e.g., dist/my-cli-bun-darwin-arm64).
2. A Shell Resolver: A file named dist/cli (customizable via --resolver) which is a #!/usr/bin/env bash script. It detects the host platform via uname and uses exec to run the correct binary with no child process overhead.
3. A Windows Resolver: A dist/cli.cmd batch file for Windows support.

This resolver is what you should point to in your package.json's bin field to allow users to run your CLI regardless of their OS.

# Default multi-target build output structure
dist/
├── cli                                  # Shell resolver (entry point)
├── cli.cmd                              # Windows batch resolver
├── my-cli-bun-linux-x64-baseline        # Linux x64 binary
├── my-cli-bun-linux-arm64               # Linux ARM64 binary
├── my-cli-bun-darwin-x64                # macOS Intel binary
├── my-cli-bun-darwin-arm64              # macOS Apple Silicon binary
├── my-cli-bun-windows-x64-baseline.exe  # Windows x64 binary
└── my-cli-bun-windows-arm64.exe         # Windows ARM64 binary

The noColor extension implements standard boolean negation for the color flag. It modifies the environment for the duration of the command execution and restores previous values once finished.

Flag Behavior

• --color: Sets FORCE_COLOR=3 and clears NO_COLOR. This forces ANSI truecolor output, overriding non-TTY detection. Any library sensitive to FORCE_COLOR will obey this.
• --no-color: Sets NO_COLOR=1 and clears FORCE_COLOR. This suppresses colors following the no-color.org specification, while still allowing non-color modifiers and hyperlinks to follow standard TTY detection.

CLI Usage Examples

my-cli --color
my-cli --no-color
my-cli deploy --no-color

Important Notes

• No Default: If the flag is omitted, the extension does nothing. Color detection remains the responsibility of @crustjs/style (using standard NO_COLOR, FORCE_COLOR, and TTY detection).
• Concurrency: In overlapping programmatic runs, the last-writer-wins policy applies while active. The ambient environment is restored once the last run finishes.

To use Crust effectively, understand these core architectural principles:

• Inference over annotation: Types flow automatically from your command definitions (args and flags) to your command handlers. You do not need to use decorators, code generation, or manual generics.
• Immutable Builders: Definitions and Extensions are treated as frozen data. Every method call on a builder returns a new builder instance.
• One-way Pattern: The recommended pattern is to use defineCommand() for every command and instantiate new Crust() exactly once at the root of your application.
• Composable Modules: The core (@crustjs/core) is zero-dependency. Features like help, versioning, and completions are provided via Extensions attached at the root, and build tooling is provided by @crustjs/crust.
• Subcommands and Inheritance: You can build nested command trees. Subcommands can inherit flags from parent commands by setting inherit: true.
• Contexts: These are named command dependencies that are constructed lazily only for the specific command path being resolved.

When an application is invoked, Crust follows a strict sequence of operations to ensure proper setup, validation, and cleanup:

1. Prepare definitions: Apply Extensions and check for command/flag/alias collisions.
2. Route: Resolve the command path.
3. Parse syntax: Consume positional and flag tokens.
4. Run preRun hooks: Invoke Extension hooks in .extend() order. Returning ctx.finish() from a hook skips remaining hooks, validation, and the Command Handler.
5. Validate structure: Enforce required values and choices.
6. Apply schemas: Validate and transform schema-backed inputs.
7. Construct Contexts: Create Context values in topological order based on their requirements.
8. Run the Command Handler: Execute the core logic.
9. Dispose Contexts: Run Symbol.dispose or Symbol.asyncDispose in reverse construction order (even if a failure occurs).
10. Run postRun hooks: Invoke Extension hooks in reverse .extend() order. This acts as the finally block for the invocation.