feat(builtins): add yaml command (non-standard, simplified yq)

[chaliy]

Summary

A new, non-standard builtin providing simple YAML operations, mirroring the json builtin (#561) semantics. YAML is the dominant config format (Kubernetes, CI/CD, Ansible, Docker Compose, GitHub Actions) — yet shell tooling for it is poor. yq exists but isn't standard and has competing incompatible versions.

Note: This is a bashkit-specific extension, not a standard command. Mirrors the json builtin API for consistency.

Proposed Syntax

yaml <subcommand> [args...] [< input]

Proposed Subcommands

Subcommand	Description
yaml get .path	Extract value at dot-notation path
yaml set .path value	Set value at path
yaml delete .path	Remove key at path
yaml merge file1 file2	Deep merge two YAML documents
yaml keys	List top-level keys
yaml type .path	Print type (string, number, mapping, sequence, bool, null)
yaml valid	Validate YAML (exit 0 if valid, 1 if not)
yaml fmt	Pretty-print / normalize YAML
yaml each .path	Iterate sequence, output one element per line
yaml to-json	Convert YAML to JSON
yaml from-json	Convert JSON to YAML

Use Cases

# Read a value from config
yaml get .database.host < config.yaml
# localhost

# Set a value
yaml set .database.port 5432 < config.yaml > updated.yaml

# Merge configs (override takes precedence)
yaml merge defaults.yaml overrides.yaml > config.yaml

# Validate before deploying
if yaml valid < deployment.yaml; then
    kubectl apply -f deployment.yaml
fi

# Iterate over list items
yaml each .services < docker-compose.yaml
# web
# db
# redis

# Extract nested value from GitHub Actions
yaml get .jobs.build.runs-on < .github/workflows/ci.yaml
# ubuntu-latest

# Convert between formats
yaml to-json < config.yaml | json get .version
cat config.json | yaml from-json > config.yaml

# Pipeline: modify and write back
cat deployment.yaml \
  | yaml set .spec.replicas 3 \
  | yaml set .spec.template.spec.containers[0].image "app:v2" \
  > deployment-updated.yaml

# Multi-document support (--- separator)
yaml get .metadata.name --document 1 < multi.yaml

Proposed Flags

Flag	Description
--document N / -d N	Select Nth document in multi-document YAML (0-indexed, default 0)
--all-documents	Apply operation to all documents
--in-place FILE / -i FILE	Modify file in place

Path Notation

Same dot notation as json builtin for consistency:

• .foo.bar — nested key access
• .items[0] — sequence index
• .items[-1] — last element
• .items[*] — all elements
• . — root document

YAML-Specific Considerations

Feature	Handling
Multi-document (---)	--document N to select, default is first
Anchors & aliases (&/*)	Resolved on read, not preserved on write
Comments	Preserved where possible (best-effort)
Quoted strings	Round-trip preserves quoting style
Flow vs block style	yaml fmt normalizes to block style
Tags (!!str, !!int)	Supported but rarely needed
null vs missing	yaml get returns empty string + exit 1 for missing; literal "null" for explicit null

Implementation Notes

• Use serde_yaml or yaml-rust2 crate for parsing/serialization
• Path resolution logic shared with json builtin (extract into common module)
• yaml to-json and yaml from-json enable interop with jq for complex queries
• Multi-document YAML is common in Kubernetes — must handle --- separators
• Comment preservation is a differentiator vs yq — use a parser that tracks comments if possible
• Exit codes match json builtin: 0 = success, 1 = path not found or invalid YAML
• YAML is a superset of JSON, so yaml can also parse JSON input

[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("yaml: Simple YAML get/set/merge/each, mirrors json builtin. `yaml get .key < f.yaml`. Also: yaml to-json, yaml from-json.")
}

Progressive disclosure levels

1. System prompt (above hint) — LLM knows it mirrors json API
2. yaml --help — subcommand list, --document N flag
3. yaml get --help — path notation, multi-document handling
4. help yaml — full examples including Kubernetes/CI use cases

[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