feat(builtins): add assert command (non-standard)

[chaliy]

Summary

A new, non-standard builtin for first-class test assertions with clear error messages. Useful for self-verifying scripts, CI pipelines, and inline correctness checks.

Note: This is a bashkit-specific extension, not a standard Bash command.

Proposed Syntax

assert <test-expression> [message]

Behavior

• Evaluates the expression using the same logic as test/[
• If true: silent, exit 0
• If false: prints assertion failure message to stderr, exits with code 1
• If set -e is active, assertion failure stops the script (desired behavior)

Use Cases

# Basic value check
result=$(compute_something)
assert [ "$result" = "expected" ] "compute_something returned '$result', expected 'expected'"

# File existence
assert [ -f "/app/config.json" ] "Config file missing"

# Non-empty output
output=$(curl -s https://api.example.com/health)
assert [ -n "$output" ] "Health check returned empty response"

# Numeric comparison
count=$(wc -l < data.csv)
assert [ "$count" -gt 0 ] "data.csv is empty"

# In CI scripts
./build.sh
assert [ -f "dist/app.js" ] "Build did not produce dist/app.js"

# Multiple assertions as lightweight tests
assert [ "$(echo hello | tr a-z A-Z)" = "HELLO" ] "tr uppercase failed"
assert [ "$(expr 2 + 2)" = "4" ] "arithmetic broken"

Error Output Format

assertion failed: Config file missing
  expression: [ -f /app/config.json ]
  at: script.sh:15

Implementation Notes

• Expression parsing reuses test/[ builtin logic
• Message is optional — without it, prints the expression itself
• $LINENO and ${BASH_SOURCE} provide location info
• Could support assert_eq val1 val2 [message] as a shorthand
• Exit code 1 on failure (not 2 like test syntax errors)
• Works naturally with set -e — script stops on first failed assertion

[chaliy]

System Prompt & Progressive Disclosure

Non-standard builtin — LLMs will not know about it. System prompt must teach, but briefly.

llm_hint() — ONE line

fn llm_hint(&self) -> Option<&'static str> {
    Some("assert: Test assertion. `assert [ \"$x\" = \"expected\" ] \"message\"`. Exits 1 on failure.")
}

Progressive disclosure levels

1. System prompt (above hint) — LLM knows syntax and behavior
2. assert --help — supported test expressions, error output format
3. help assert — full examples and integration with set -e

[chaliy]

Documentation Requirements

Since this is a non-standard (invented) builtin, it must be documented in two places:

1. README.md — Add to the "Built-in Commands" table under a new Extensions category row (non-standard bashkit-specific commands, clearly marked as extensions)
2. crates/bashkit/docs/extensions.md — Create or update a dedicated extensions guide covering all invented builtins, with short descriptions, examples, and rationale for why each exists

This ensures users discover these commands and understand they are bashkit-specific, not standard Bash.

[chaliy]

Resolved in PR #585 or #588