feat(builtins): add log command (non-standard, structured logging)

[chaliy]

Summary

A new, non-standard builtin for structured logging with levels, timestamps, and optional JSON output. Every serious script reinvents logging — making it a builtin standardizes the pattern.

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

Proposed Syntax

log <level> <message> [key=value...]

Proposed Levels

Level	Description
`debug`	Verbose diagnostic info (hidden by default)
`info`	Normal operational messages
`warn`	Warning conditions
`error`	Error conditions

Proposed Flags / Environment

Config	Description
`LOG_LEVEL` env var	Minimum level to display (default: `info`)
`LOG_FORMAT` env var	`text` (default) or `json`
`LOG_TIMESTAMP` env var	`true`/`false` — include timestamp (default: true)

Use Cases

# Basic logging
log info "Starting deployment"
log warn "Config file not found, using defaults"
log error "Failed to connect to database"

# With structured key-value pairs
log info "Request completed" status=200 duration=1.5s endpoint=/api/users
log error "Query failed" table=users query="SELECT *" err="timeout"

# Control level via environment
export LOG_LEVEL=debug
log debug "Verbose tracing info"

# JSON output for machine parsing
export LOG_FORMAT=json
log info "Deploy complete" version=1.2.3 env=production
# {"level":"info","msg":"Deploy complete","version":"1.2.3","env":"production","ts":"2024-01-15T10:30:00Z"}

# In scripts
deploy() {
    log info "Deploying version $1" version="$1"
    if ! ./build.sh; then
        log error "Build failed" version="$1"
        return 1
    fi
    log info "Deploy successful" version="$1"
}

Text Output Format

2024-01-15 10:30:00 [INFO]  Starting deployment
2024-01-15 10:30:01 [WARN]  Config file not found, using defaults
2024-01-15 10:30:02 [ERROR] Failed to connect to database

Implementation Notes

• All output goes to stderr (stdout is for data)
• Level filtering: messages below LOG_LEVEL are silently dropped
• Timestamps use interpreter's virtual time (not host time, per security spec)
• Key-value pairs are appended after the message
• JSON format uses serde_json for proper escaping
• Color output when stderr is a terminal: debug=gray, info=green, warn=yellow, error=red
• No color in bashkit's virtual environment (no real terminal), but the format supports it for realfs mode

[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("log: Structured logging. `log info \"msg\" key=val`. Levels: debug/info/warn/error. Set LOG_LEVEL/LOG_FORMAT env.")
}

Progressive disclosure levels

1. System prompt (above hint) — LLM knows levels and key=value syntax
2. log --help — env vars (LOG_LEVEL, LOG_FORMAT, LOG_TIMESTAMP), output formats
3. help log — full examples, JSON output format, color behavior

[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