📐 ZSHAND Header Standard¶

# ╔══════════════════════════════════════════════════════════════════════════════╗
# ║  Title — Short Description                                                 ║
# ║  Extended description line two if needed.                                  ║
# ║  Extended description line three if needed.                                ║
# ╚══════════════════════════════════════════════════════════════════════════════╝

# ── name — Short Description ────────────────────────────────────────────────

# ── SECTION NAME ─────────────────────────────────────────────────────────────

# ─────────────────────────────────────────────────────────────────────────────

# ── TARGET USERS ─────────────────────────────────────────────────────────────
#
#   👤 Human developers optimizing shell startup performance
#   🚀 CI/CD pipelines monitoring for performance regressions
#   🤖 AI assistants analyzing bottlenecks and suggesting fixes

# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   function_name <required_arg> [optional_arg]
#
#   $1  Description of first argument (type, required)
#   $2  Description of second argument (type, optional, default: value)
#
#   Returns: 0 on success, 1 on failure (see EXIT CODES)
#   Output:  Report to stdout (see OUTPUT)
#
#   Prerequisite:
#     Run `zprofile --full` first to generate timing data.

# ── TRIGGER ──────────────────────────────────────────────────────────────────
#
#   Keybinding:   Ctrl+E (configured in core/16_widgets.zsh)
#   Direct:       widget_name
#   ZLE register: zle -N widget_name
#   Verify:       bindkey | grep widget_name

# ── ENVIRONMENT ──────────────────────────────────────────────────────────────
#
#   ZSHAND_CACHE_DIR       string  $XDG_CACHE_HOME/zshand   Cache directory
#   ZSHAND_PROFILE_SHOW_ALL  bool  0                        Show all items
#   ZSHAND_PROFILE_VERBOSE   bool  0                        Debug output
#   COLUMNS                  int   auto                     Terminal width
#   ZSHAND_DEV_MODE          bool  0                        🟡 via .envrc

# ── LOAD ORDER ──────────────────────────────────────────────────────────────
#
#    1  shared_functions     Error handling, logging, utilities (always first)
#    2  startup              Early env checks, dev mode, clipboard
#    3  user_environment     User's env.zsh, secrets.zsh, config.toml exports
#    4  init.d               User's pre-core initialization scripts
#    5  core                 Framework engine, paths, audit, hooks, widgets
#    6  functions            User-facing shell functions
#    7  widgets              ZLE widgets (keybinding-driven tools)
#    8  hooks                Tool integrations (mise, atuin, docker, ssh-agent)
#    9  plugins              Third-party plugin loading
#   10  private_functions    Internal framework functions (_-prefixed)
#   11  post.d               User's post-core scripts and final overrides

# ── OUTPUT ───────────────────────────────────────────────────────────────────
#
#   stdout:
#     Formatted performance report with grading, bar charts, and
#     per-directory breakdown. Human-readable with ANSI color codes.
#     Pipe-safe: detects non-interactive and disables color.
#
#   stderr:
#     Warnings and errors prefixed with “✗” or “⚠”.
#     All errors include actionable fix instructions.
#
#   Icons:
#     👤  User-sourced item (from config directory)
#     📦  Framework-sourced item (from ZSHAND base)
#
#   Machine-readable:
#     Pipe to `grep -P '^\s+\d' | awk '{print $NF}'` to extract timing values.
#     Future: --json flag planned (see ROADMAP).

# ── PIPELINE ─────────────────────────────────────────────────────────────────
#
#   1  Argument validation    Check required paths exist         → exit 1
#   2  File discovery         Walk framework + user dirs         → exit 1
#   3  Merge resolution       User files override by basename    → continue
#   4  Concatenation          Assemble source with markers       → exit 1
#   5  Compilation            zcompile to .zwc bytecode          → exit 1

# ── WORKFLOW ─────────────────────────────────────────────────────────────────
#
#   1. Context Gathering
#      - Read staged changes (git diff --cached)
#      - Load project context via _get_project_context
#      - Fail: abort with "nothing staged" message
#
#   2. Prompt Construction
#      - Build AI prompt with context + diff
#      - Fail: falls back to manual commit

# ── ARGUMENTS ───────────────────────────────────────────────────────────────
#
#   $1  Directory path to check (string, required)
#       Must exist and be readable. Exit 1 if missing.
#   $2  Base directory for deps (string, optional, default: $ZSHAND)
#       Falls back to $ZSHAND if empty or unset.
#   $3  Quiet mode (bool, optional, default: false)
#       "true" suppresses all stdout output.

Describe "argument validation"
  It "exits 1 when directory path missing"
  It "uses ZSHAND as default base directory"
  It "suppresses output in quiet mode"
End

# ── OPTIONS ──────────────────────────────────────────────────────────────────
#
#   Positional:
#     <depth>     Tree depth level (1-9, default: 2)
#     <path>      Directory to analyze (default: cwd)
#
#   Flags:
#     -c [file]   Include file content (latest or specific path)
#     -e          Include sanitized .env keys (values stripped)
#     -h          Show help and exit
#     --verbose   Print debug information to stderr
#
#   Constraints:
#     -c and -e can be combined.
#     -h overrides all other flags (prints help and exits 0).

# ── FILES ────────────────────────────────────────────────────────────────────
#
#   Input:
#     $cache_dir/profile-timing.log   required  Raw timing data
#       Format: TYPE|NAME|START|END (pipe-delimited, one entry per line)
#       Perms:  644 (created by zprofile)
#
#   Output:
#     $cache_dir/zshand-full.zwc      generated  Compiled bytecode bundle
#       Perms:  644 (overwritten on each rebuild)
#       Cleanup: Stale .zwc removed by zprime --clean
#
#   Temp:
#     $cache_dir/.compile.lock         transient  Prevents concurrent builds
#       Cleaned up on exit (trap EXIT)

# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   awk          required  Floating point arithmetic
#   tput         required  Terminal width detection
#   gum          optional  Enhanced terminal UI (graceful fallback)
#     Install:   just install-gum  OR  brew install gum
#     Check:     command -v gum
#   zsh/datetime optional  Benchmark via EPOCHREALTIME
#     Version:   5.8+
#     Install:   zmodload zsh/datetime
#     Check:     zmodload zsh/datetime 2>/dev/null && echo ok

# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Report generated successfully
#   1  No timing data found (missing profile-timing.log)
#   1  Analysis failed (zero total time, divide-by-zero guard)
#   2  Invalid arguments (unrecognized option or bad path)
#
#   Signals:
#     SIGINT (Ctrl+C)  Cleans up temp files, exits 130
#     SIGTERM           Cleans up temp files, exits 143

#   0  Always (display function, no failure mode)

It "exits 0 on successful report generation"
It "exits 1 when timing data is missing"
It "exits 2 on invalid arguments"

# ── INTERNAL HELPERS ─────────────────────────────────────────────────────────
#
#   Floating point math wrappers (~L280, zsh integer-only workaround):
#     _fadd, _fsub, _fmul, _fdiv   Basic arithmetic (9 decimal places)
#     _fgt, _fge, _fle             Comparisons (via exit code)
#     _fms                         Convert seconds → milliseconds
#     _fpct                        Calculate percentage
#
#   Rendering (~L350):
#     _make_bar                    Render ▓░ progress bar (scaled to max)
#
#   Constants:
#     Widget slow threshold: 5ms (hardcoded)
#     Plugin slow threshold: 10ms (triggers lazy-load suggestion)

# ── GRADING SCALE ────────────────────────────────────────────────────────────
#
#   A   ★★★★  < 50ms    Excellent — near-instant startup
#   A-  ★★★☆  < 100ms   Great — barely perceptible delay
#   B   ★★★   < 150ms   Good — fast enough for most users
#   B-  ★★☆   < 200ms   Acceptable — room for improvement
#   C   ★★    < 250ms   Mediocre — consider optimizations
#   C-  ★☆    < 350ms   Slow — deferred loading recommended
#   D   ★     < 500ms   Poor — significant optimization needed
#   F         ≥ 500ms   Failing — major performance issues

# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Via Just (preferred)
#   just test              # Run full test suite
#   just test spec/unit    # Run specific spec
#   just bench             # Benchmark startup time
#
#   # Direct invocation
#   function_name
#   function_name "arg1"
#   # → Expected: "Success: processed 42 items"
#
#   # Scripted / CI usage
#   result=$(function_name | grep "pattern")
#   echo $?  # → 0 on success

Describe "via just"
  It "runs full test suite"
  It "runs specific spec"
End
Describe "direct invocation"
  It "succeeds with no arguments"
  It "succeeds with arg1"
End

# ── TROUBLESHOOTING ──────────────────────────────────────────────────────────
#
#   🔧 "No timing data found"
#     Cause:   Profiling data hasn't been generated yet.
#     Fix:     zprofile --full && _zshand_profile_bundle_report
#     Verify:  ls -la "$cache_dir/profile-timing.log"
#
#   🔧 "awk: cmd. line:1: error"
#     Cause:   Corrupted entries in timing log.
#     Inspect: head -20 "$cache_dir/profile-timing.log"
#     Fix:     zprofile --rebuild
#
#   🔧 "tput: unknown terminal"
#     Cause:   Terminal type not recognized by ncurses.
#     Fix:     export COLUMNS=120
#
#   🔧 "Permission denied"
#     Cause:   Cannot read cache directory or timing logs.
#     Inspect: ls -la "$cache_dir/"
#     Fix:     chmod 644 "$cache_dir/profile-timing.log"
#
#   🐛 Debug with zshdb (step-through):
#     zshdb build/profile_bundle_report.zsh

# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   No timing data       →  exit 1 with instructions
#   Missing gum          →  falls back to plain text automatically
#   Terminal too narrow   →  clamps to minimum 80 columns
#   Terminal too wide     →  caps at 200 columns for readability
#   Invalid timing data   →  skips malformed entries, warns on stderr
#   Zero total time      →  exit 1 instead of divide-by-zero
#   Missing exceptions   →  runs without filtering, flags all items
#   Empty cache dir      →  creates directory, or errors clearly
#   Non-interactive      →  detects pipe/redirect, disables color

Describe "edge cases"
  It "clamps terminal width to minimum 80"
  It "falls back to plain text when gum missing"
  It "exits 1 on zero total time"
End

# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   ShellCheck:  ✅ Clean (managed by Trunk, auto-run on commit)
#   shfmt:       ✅ Formatted per .editorconfig rules
#   Dialect:     zsh (default) / bash (for installers)
#
#   Overrides:
#     # shellcheck disable=SC2034  — Variable used by caller via eval
#     # shellcheck disable=SC2086  — Intentional word splitting for $opts
#
#   Verify:  trunk check <file>   OR   just lint

# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   ✅ Clean: ShellCheck + shfmt (Trunk-managed, no overrides)

# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads       Cache files, timing logs, framework source
#   Writes      stdout report (or "None — pure function")
#   Network     None (or: "ICMP ping to 8.8.8.8")
#   Privileges  None — user-level only (or: "sudo for apt")
#   Data        Shell metadata; no credentials or PII
#   Secrets     🟢 None (or: 🟡 ".envrc secrets via direnv")
#   Gitleaks    ✅ Clean (or: ⚠️ override needed — explain why)

#   🔒 Reads: None  Writes: stderr  Network: None  Gitleaks: ✅ Clean

# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:      spec/build/profile_bundle_report_spec.sh
#   Run:       just test spec/build/profile_bundle_report_spec.sh
#   Coverage:  Kcov via CI (target: 90%+)
#   Status:    ✅ Passing (last verified: 2026-02-05)
#
#   Must cover:
#     ✅ Report generation with valid timing data
#     ✅ Missing timing log → graceful error (exit 1)
#     ✅ Grade calculation at every boundary (A through F)
#     ✅ Gum rendering path vs plain text fallback
#     ✅ Terminal width clamping (narrow, wide, default)
#     ✅ Profile exception filtering
#     ⬜ Deferred/lazy operation analysis accuracy
#     ⬜ Real startup benchmark (3-run average) correctness
#     ⬜ CI pipeline integration (machine-readable output)
#
#   TODO:
#     - Add spec for ZSHAND_PROFILE_VERBOSE=1 output differences
#     - Add edge case spec for corrupted timing log entries
#     - Benchmark spec: verify Hyperfine threshold enforcement

# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/functions/dcopy_spec.sh
#   Run:     just test spec/functions/dcopy_spec.sh
#   Status:  ✅ Passing
#
#   Must cover:
#     ✅ Copies $PWD to clipboard successfully
#     ✅ Exits 1 when wl-copy missing
#     ✅ Handles paths with spaces and special characters
#     ⬜ Non-Wayland environment detection

# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec: spec/functions/dcopy_spec.sh    Run: just test spec/functions/
#   Status: ✅ Passing    Must cover: clipboard copy, missing dep, special chars

# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/hooks/01_mise_spec.sh (🚧 not yet written)
#   Status:  🚧 No spec
#
#   Must cover:
#     ⬜ Skip when mise not installed
#     ⬜ Cache regeneration when binary newer
#     ⬜ Cache directory creation failure
#     ⬜ Deferred activation timing

```sh
# spec/hooks/01_mise_spec.sh
Describe "01_mise.zsh"
  Include "hooks/01_mise.zsh"

  Describe "when mise is not installed"
    setup() { PATH="/empty"; }
    It "skips silently"
      When call source hooks/01_mise.zsh
      The status should be success
      The stderr should be blank
    End
  End

  Describe "cache management"
    It "regenerates cache when binary newer"
    It "creates cache directory if missing"
    It "handles cache directory creation failure"
  End
End
```

**Naming convention:** `spec/<dir>/<name>_spec.sh` mirrors `<dir>/<name>.zsh`.

**Common matchers:**

| Matcher | Usage |
|---------|-------|
| `The status should be success` | Exit code 0 |
| `The status should be failure` | Exit code non-zero |
| `The output should include "text"` | stdout contains |
| `The stderr should include "text"` | stderr contains |
| `The variable VAR should eq "val"` | Variable check |
| `The path "file" should be exist` | File exists |

# ── PERFORMANCE ──────────────────────────────────────────────────────────────
#
#   Execution time   <100ms typical, <5ms cached path
#   Complexity       O(n) where n = timing entries
#   Memory           ~4MB resident (report generation)
#
#   Baseline (2026-02-03, higtop):
#     just bench → mean 3.2ms ± 0.4ms (3-run warm)
#
#   Benchmark:
#     just bench                              # Full startup benchmark
#     hyperfine --warmup 3 'zsh -ic exit'     # Raw startup time
#     hyperfine --warmup 3 'source file.zsh'  # Single file load time
#
#   CI threshold:  Fails build if startup regresses > 10ms vs baseline
#   Regression:    Compare with `just bench --export-json` across commits

#   ⚡ Load time: <1ms  |  Complexity: O(1)  |  No benchmark needed

# ── TIPS ─────────────────────────────────────────────────────────────────────
#
#   Accuracy:
#     💡 Always run `zprofile` immediately before analysis for fresh data
#     💡 Use `zprofile --rebuild` if timing data seems stale
#     ⚠️  Profiled times include instrumentation overhead; real startup is faster
#     💡 The real startup benchmark (3-run average) shows actual user experience
#
#   Analysis:
#     💡 ZSHAND_PROFILE_SHOW_ALL=1 for the full component listing
#     💡 Set COLUMNS for consistent output when piping or scripting
#     💡 Pipe to `less -R` for color-preserving paging of long reports
#     💡 Focus on the bottleneck directory first — biggest wins there
#
#   Performance:
#     💡 Install gum for enhanced visual readability
#     💡 Items in profile-exceptions.conf are excluded from slow warnings
#     💡 Consider lazy-loading any plugin above 10ms
#     💡 Compare reports across framework versions for trend analysis
#     💡 Run `just bench` to verify improvements with Hyperfine

# ── AI INTEGRATION ───────────────────────────────────────────────────────────
#
#   Use cases:
#     🤖 Identify optimization opportunities from timing data
#     🤖 Suggest lazy-loading for slow components (>10ms threshold)
#     🤖 Compare performance across framework versions
#     🤖 Flag performance regressions in pull requests
#     🤖 Help diagnose slow startup issues via bottleneck analysis
#
#   Parsing patterns:
#     Timing log:   grep 'TYPE|NAME' $cache_dir/profile-timing.log
#     Grade:        grep -oP 'Grade: \K[A-F][+-]?'
#     Total time:   grep -oP 'Total: \K[\d.]+ms'
#     Slow items:   grep '⚠' (items flagged as slow)
#
#   AI-friendly features:
#     ✅ Structured, parseable output with reliable extraction patterns
#     ✅ Consistent error messages (grep-able, deterministic)
#     ✅ Pipe-separated timing log format (TYPE|NAME|START|END)
#     ✅ Idempotent — safe for repeated execution
#     ✅ Headers follow this standard for consistent context gathering

# ── HISTORY ──────────────────────────────────────────────────────────────────
#
#   v2.0  2026-02-03  ⚠️ Terminal-width awareness, gum integration, enhanced UI,
#                     real startup benchmarking, user/system item icons
#                     Breaking: removed --legacy flag, changed exit codes
#   v1.5  2025-08-15  Deferred/lazy operation analysis, performance grading
#   v1.0  2024-11-20  Initial implementation with basic text output

# ── ROADMAP ──────────────────────────────────────────────────────────────────
#
#   🟢 Soon:
#     - JSON output for programmatic consumption          [M]
#     - Historical trend analysis across multiple runs     [L]
#
#   🟡 Later:
#     - Memory profiling (RAM usage alongside timing)      [L]
#     - Configurable performance thresholds and alerting   [M]
#
#   🔵 Someday:
#     - AI-enhanced recommendations using pattern detection [XL]
#     - Flamegraph-style visualization for deep analysis    [XL]
#
#   Effort: [S] = hours, [M] = days, [L] = week, [XL] = multi-week

# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   Framework:
#     profile_time_all_widgets.zsh   Widget profiling data source
#     compile_profile_bundle.zsh     Bundle compilation with profiling
#     zprofile                       High-level profiling command (caller)
#     profile-exceptions.conf        Per-item performance exception rules
#
#   Specs:
#     spec/build/profile_bundle_report_spec.sh   Tests for this file
#
#   External:
#     gum                            https://github.com/charmbracelet/gum
#     awk                            https://www.gnu.org/software/gawk/manual/
#     tput                           https://man7.org/linux/man-pages/man1/tput.1.html
#     Zsh modules                    https://zsh.sourceforge.io/Doc/Release/Zsh-Modules.html
#
#   Tooling:
#     Justfile                       Task orchestration (just --list)
#     .devcontainer/                 Contributor onboarding
#     spec/                          ShellSpec test suite

spec/
├── build/
│   └── profile_bundle_report_spec.sh    # → build/profile_bundle_report.zsh
├── core/
│   └── 06_engine_spec.sh                # → core/06_engine.zsh
├── functions/
│   └── dcopy_spec.sh                    # → functions/dcopy.zsh
├── hooks/
│   └── 01_mise_spec.sh                  # → hooks/01_mise.zsh
└── spec_helper.sh                       # Shared setup (sourced by all specs)

# spec/functions/dcopy_spec.sh
Describe "dcopy.zsh"
  Include "functions/dcopy.zsh"

  # Maps to: USAGE section
  Describe "usage"
    It "copies current directory to clipboard"
      # ...
    End
  End

  # Maps to: EXIT CODES section
  Describe "exit codes"
    It "returns 0 on success"
    It "returns 1 when wl-copy missing"
  End

  # Maps to: EDGE CASES section
  Describe "edge cases"
    It "handles paths with spaces"
    It "handles paths with special characters"
  End

  # Maps to: ENVIRONMENT section
  Describe "environment"
    It "respects WAYLAND_DISPLAY"
  End
End

just test                              # All specs
just test spec/functions/              # One directory
just test spec/functions/dcopy_spec.sh # One file
just coverage                          # Kcov report (CI)

#!/usr/bin/env zsh
# ╔══════════════════════════════════════════════════════════════════════════════╗
# ║  ZSHAND Build System: Full Bundle Compiler                                 ║
# ║  Builds a single .zwc bytecode bundle containing the entire ZSHAND         ║
# ║  framework plus user config. Merges files in correct load order with       ║
# ║  user overrides, then compiles to optimized bytecode.                      ║
# ╚══════════════════════════════════════════════════════════════════════════════╝
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   _zshand_compile_full_bundle "$base" "$config" [cache_dir] [quiet]
#
#   $1  Base ZSHAND directory (string, required)
#   $2  User config directory ZSHAND_CONFIG_DIR (string, required)
#   $3  Cache directory (string, optional, default: ZSHAND_CACHE_DIR)
#   $4  "true" for quiet operation (bool, optional)
#
# ── ENVIRONMENT ──────────────────────────────────────────────────────────────
#
#   ZSHAND_CACHE_DIR    string  $XDG_CACHE_HOME/zshand   Cache directory
#   ZSHAND_CONFIG_DIR   string  $XDG_CONFIG_HOME/zshand  User config directory
#   ZSHAND_BASE_DIR     string  auto-detect              Framework root
#
# ── PIPELINE ─────────────────────────────────────────────────────────────────
#
#   1  Argument validation    Check required paths exist
#   2  File discovery         Walk framework + user dirs in load order
#   3  Merge resolution       User files override framework by basename
#   4  Concatenation          Assemble zshand-full.zsh with debug markers
#   5  Compilation            zcompile to zshand-full.zwc bytecode
#
# ── FILES ────────────────────────────────────────────────────────────────────
#
#   Input:
#     $base_dir/shared_functions/*.zsh   required  Framework shared functions
#     $config_dir/env.zsh                optional  User environment variables
#     $config_dir/secrets.zsh            optional  User API keys and tokens
#     $config_dir/config.toml            optional  Parsed to shell exports
#
#   Output:
#     $cache_dir/zshand-full.zsh         Concatenated source with markers
#     $cache_dir/zshand-full.zwc         Bytecode bundle (fast loading)
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   zcompile   required  Zsh bytecode compiler
#   find       required  File discovery in directories
#   sort       required  Deterministic file ordering
#
# ── PERFORMANCE ──────────────────────────────────────────────────────────────
#
#   Execution time   <200ms typical (depends on file count)
#   Complexity       O(n) where n = total framework + user files
#   File I/O         Two passes: discovery + concatenation
#
#   Benchmark:
#     just build
#     hyperfine 'zsh -c "source build/compile_full_bundle.zsh; ..."'
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Full bundle created successfully
#   1  Missing dependencies, invalid paths, or compilation failure
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Via Just
#   just build
#
#   # Direct invocation
#   _zshand_compile_full_bundle "$ZSHAND" "$ZSHAND_CONFIG"
#   _zshand_compile_full_bundle "$ZSHAND" "$ZSHAND_CONFIG" "/tmp/cache" true
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   No user config dir     Compiles framework-only bundle
#   Empty directories      Skips gracefully, no empty markers
#   Duplicate basenames    User file wins (override by convention)
#   Missing cache dir      Creates it automatically
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:      spec/build/compile_full_bundle_spec.sh
#   Run:       just test spec/build/compile_full_bundle_spec.sh
#   Coverage:  Kcov via CI (target: 90%+)
#   Status:    ✅ Passing
#
#   Must cover:
#     ✅ Argument validation (missing paths)
#     ✅ File discovery across all framework directories
#     ✅ User override resolution (duplicate basenames)
#     ✅ Concatenation with debug markers
#     ✅ zcompile bytecode generation
#     ⬜ Framework-only bundle (no user config)
#     ⬜ Empty directories in load order
#
#   TODO:
#     - Add spec for incremental rebuild (only changed dirs)
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   compile_profile_bundle.zsh     Profiling-instrumented variant
#   optimize_startup.zsh           Startup optimization passes
#   profile_bundle_report.zsh      Performance reporting (reference impl)
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env zsh
# ── 06_engine — High-Performance Execution Engine & Bootstrapper ────────────
#
# Core framework engine providing system initialization, command execution
# logging (zrun), and compilation/reload infrastructure (zprime). Handles
# Atuin daemon lifecycle, file permissions, completion generation, and
# .zwc bytecode compilation for optimal shell startup performance.
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   Loaded automatically during shell initialization (core loading sequence).
#   Functions become globally available after sourcing.
#
# ── BEHAVIOR ─────────────────────────────────────────────────────────────────
#
#   - System initialization: Atuin daemon, security, terminal titles
#   - Command execution: zrun wrapper with telemetry and validation
#   - Framework compilation: zprime engine for bytecode compilation
#   - Directory compilation: Single-directory rebuilds, incremental updates
#   - Completion generation: Atomic generation for external tools
#   - Bundle compilation: Framework directories into optimized .zwc bundles
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   zsh 5.0+   required  Base shell with zcompile support
#   date       required  Timestamp generation for logs
#   chmod      required  File permission enforcement
#   find       required  File discovery for compilation
#   atuin      optional  History sync daemon management
#   git        optional  Auto-backup before destructive operations
#   ping       optional  Network connectivity check
#   gh         optional  GitHub CLI completions
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Normal operation (functions loaded, zprime success)
#   1  Compilation failure or missing framework directory
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Execute with telemetry logging
#   zrun "mise install"
#
#   # Recompile and reload framework
#   zprime
#   zprime --quiet
#
#   # Via Just
#   just build
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   Missing atuin        Skips daemon management gracefully
#   No network           Defers sync, logs warning
#   Stale .zwc bundles   Detected and rebuilt automatically
#   Read-only filesystem  Logs warning, continues without compilation
#
# ── PERFORMANCE ──────────────────────────────────────────────────────────────
#
#   Load time     <5ms (sourced at every shell startup)
#   zprime time   <500ms typical (full framework recompile)
#   zrun overhead <1ms per invocation (telemetry wrapper)
#
#   Benchmark:
#     just bench
#     hyperfine --warmup 3 'zsh -ic exit'
#
#   CI threshold:  Core load must not regress startup by >2ms
#
# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads       Framework source files, cache directory, timing logs
#   Writes      .zwc bytecode bundles, completion files, cache data
#   Network     Atuin sync (via daemon), connectivity checks (ping)
#   Privileges  None (user-level only)
#   Data        Shell configuration and metadata; no credentials
#   Gitleaks    Clean (no secrets handled directly)
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:      spec/core/06_engine_spec.sh
#   Run:       just test spec/core/06_engine_spec.sh
#   Coverage:  Kcov via CI (target: 85%+)
#   Status:    ⚠️ Partial
#
#   Must cover:
#     ✅ zprime recompile and reload
#     ✅ zrun telemetry logging
#     ✅ Directory compilation (.zwc generation)
#     ✅ Atuin daemon start/stop lifecycle
#     ✅ Permission enforcement (chmod on sensitive files)
#     ⬜ Completion generation (atomic write)
#     ⬜ Incremental rebuild detection
#     ⬜ Network-offline graceful degradation
#     ⬜ Read-only filesystem handling
#
#   TODO:
#     - Add spec for completion generation race conditions
#     - Add benchmark spec: zprime must complete in <500ms
#     - Test zrun with commands that produce stderr
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   core/04_path.zsh        Path management and $PATH construction
#   core/08_audit.zsh       Security auditing and permission checks
#   build/optimize_startup.zsh   Startup optimization passes
#
# ─────────────────────────────────────────────────────────────────────────────

# ── dcopy — Copy Current Directory Path to Clipboard ─────────────────────────
#
# Copies $PWD to the system clipboard for use in terminals, editors, and
# AI assistants. Designed for Wayland environments with robust error handling.
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   dcopy
#
# ── OUTPUT ───────────────────────────────────────────────────────────────────
#
#   stdout:  Confirmation message with the copied path
#   stderr:  Error messages with exit code
#
# ── BEHAVIOR ─────────────────────────────────────────────────────────────────
#
#   - Uses $PWD directly (faster than external pwd)
#   - Handles path escaping for display
#   - Validates dependencies before attempting copy
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   wl-copy   required  Wayland clipboard utility
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Path copied successfully
#   1  Missing dependency or clipboard failure
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   dcopy             # Copy current directory
#   dcopy && cd /tmp  # Copy, then change dir
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   wl-copy missing    Exits 1 with install hint
#   Empty $PWD         Should not happen (always set by shell)
#   Path with spaces   Handled correctly via quoting
#   Non-Wayland env    Exits 1 (wl-copy requires Wayland)
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/functions/dcopy_spec.sh
#   Run:     just test spec/functions/dcopy_spec.sh
#   Status:  ✅ Passing
#
#   Must cover:
#     ✅ Copies $PWD to clipboard successfully
#     ✅ Exits 1 when wl-copy missing
#     ✅ Handles paths with spaces and special characters
#     ⬜ Non-Wayland environment detection
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   shared_functions/09_clipboard.zsh   Low-level clipboard abstraction
#   wl-copy                             https://github.com/bugaevc/wl-clipboard
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env zsh
# ── stderr_error — Red Error Message to stderr ───────────────────────────────
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   stderr_error "message"
#
# ── OUTPUT ───────────────────────────────────────────────────────────────────
#
#   stderr: Red "󱈸 ERROR:" prefix followed by message
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   None (uses only zsh builtins: print -P)
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Always (display function, no failure mode)
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   stderr_error "Config not found"
#   stderr_error "Failed to compile: $file"
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   Empty message      Prints prefix with no text (valid but odd)
#   Multi-line input   Each line gets the ERROR prefix
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads: None    Writes: stderr only    Network: None    Gitleaks: Clean
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec: spec/shared_functions/stderr_error_spec.sh
#   Run:  just test spec/shared_functions/stderr_error_spec.sh
#   Status: ✅ Passing    Must cover: output format, empty input
#
# ── HISTORY ──────────────────────────────────────────────────────────────────
#
#   v1.0  2024-11-20  Initial implementation
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   02_stderr_warn.zsh    Warning-level variant (yellow)
#   04_echo_info.zsh      Info-level variant (stdout, blue)
#
# ─────────────────────────────────────────────────────────────────────────────

# ╔══════════════════════════════════════════════════════════════════════════════╗
# ║  aicmit — AI-Assisted Git Commit Message Generator                         ║
# ║  Generates commit messages from project context, staged changes, and       ║
# ║  optional PROFILE.md documentation via AI prompt construction.             ║
# ╚══════════════════════════════════════════════════════════════════════════════╝
#
# ── TRIGGER ──────────────────────────────────────────────────────────────────
#
#   Direct invocation: aicmit
#   Keybinding: (configured in core/16_widgets.zsh)
#   ZLE registration: zle -N aicmit
#
# ── VERSION ──────────────────────────────────────────────────────────────────
#
#   V18 (Unified Lifecycle & Modular Context)
#
# ── WORKFLOW ─────────────────────────────────────────────────────────────────
#
#   1. Git Repository Validation
#      - Ensures repo exists with configured identity
#
#   2. Smart Staging
#      - Detects unstaged changes, offers interactive staging
#
#   3. Context Gathering (Adaptive)
#      - ≤3 files: full diff   >3 files: diff --stat
#
#   4. AI Prompt Construction
#      - Assembles directive with context, diff, and metadata
#
#   5. Clipboard Export
#      - Copies prompt to clipboard via wl-copy
#
# ── ENVIRONMENT ──────────────────────────────────────────────────────────────
#
#   AICMIT_AUTO_PUSH   bool   false   Auto-push after commit
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   git       required  Repository operations
#   wl-copy   required  Clipboard export
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Prompt generated and copied
#   1  Not in a git repo or nothing staged
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   aicmit                          # Generate commit prompt
#   AICMIT_AUTO_PUSH=1 aicmit      # Generate and auto-push
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   core/16_widgets.zsh   Widget keybinding registration
#   _get_project_context  Context gathering function
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env zsh
# ── 01_mise — Polyglot Runtime Manager with Cached Activation ────────────────
#
# Initializes mise for managing runtime versions. Uses intelligent caching
# to avoid subprocess overhead, regenerating only when mise binary updates.
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   Loaded automatically via core/18_hooks.zsh during shell initialization.
#
# ── BEHAVIOR ─────────────────────────────────────────────────────────────────
#
#   - Skips if mise not installed
#   - Cache: $XDG_CACHE_HOME/zshand/mise-activate.zsh
#   - Regenerates when cache missing or binary newer
#   - Deferred activation after first prompt
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   mise   required  Polyglot runtime manager
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Hook registered or skipped
#   1  Cache directory creation failure
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Force cache regeneration
#   rm ~/.cache/zshand/mise-activate.zsh
#   source hooks/01_mise.zsh
#
#   # Disable this hook entirely
#   # (remove or rename the file, or uninstall mise)
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   mise not installed     Skips entirely (no error, no warning)
#   Stale cache            Regenerated automatically on next shell start
#   Cache dir missing      Created with mkdir -p, warns on failure
#   Binary updated         Cache invalidated, regenerated on next source
#
# ── PERFORMANCE ──────────────────────────────────────────────────────────────
#
#   Load time     <1ms (cached path), ~50ms (cache miss / regeneration)
#   Strategy      Deferred activation + binary-timestamp caching
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads: mise binary, cache file    Writes: cache file    Network: None
#   Gitleaks: Clean
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/hooks/01_mise_spec.sh (🚧 not yet written)
#   Status:  🚧 No spec
#
#   Must cover:
#     ⬜ Skip when mise not installed
#     ⬜ Cache regeneration when binary newer
#     ⬜ Cache directory creation failure
#     ⬜ Deferred activation timing
#
# ── HISTORY ──────────────────────────────────────────────────────────────────
#
#   v1.1  2025-06-12  Added binary-timestamp caching, deferred activation
#   v1.0  2024-11-20  Initial implementation with direct eval
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   core/18_hooks.zsh     Hook loading infrastructure
#   mise                  https://mise.jdx.dev/
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env zsh
# ── 05_az_dev_mode_check — Auto-Rebuild When Stale (Dev Mode) ────────────────
#
# Automatically rebuilds stale bundles when ZSHAND_DEV_MODE=1 and
# ZSHAND_DEV_AUTO_REBUILD=1. Runs early in startup, before core loading.
# Only executes once per shell session via re-entrancy guard.
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   Loaded automatically during startup sequence.
#   Requires: ZSHAND_DEV_MODE=1, ZSHAND_DEV_AUTO_REBUILD=1
#
# ── ENVIRONMENT ──────────────────────────────────────────────────────────────
#
#   ZSHAND_DEV_MODE          bool  0  Enables dev mode (set via .envrc / direnv)
#   ZSHAND_DEV_AUTO_REBUILD  bool  0  Enables auto-rebuild on stale bundles
#   ZSHAND                   string    Framework root directory path
#
# ── BEHAVIOR ─────────────────────────────────────────────────────────────────
#
#   1  Re-entrancy guard     Only runs once per session
#   2  Environment check     Requires both DEV_MODE and AUTO_REBUILD
#   3  Framework validation  Ensures ZSHAND path is set
#   4  Dependency loading    Sources rebuild check and dir list functions
#   5  Stale detection       Scans framework directories for changes
#   6  Auto-rebuild          Silently runs zprime --quiet if stale
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   _zshand_check_needs_rebuild_directory()   Rebuild checking function
#   _ZSHAND_FRAMEWORK_DIRS                    Framework directory list
#   zprime                                    Framework rebuild function
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Check completed (rebuild triggered or not needed)
#   0  Skipped (dev mode disabled, or already ran this session)
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Enable dev mode (typically in .envrc)
#   export ZSHAND_DEV_MODE=1
#   export ZSHAND_DEV_AUTO_REBUILD=1
#
#   # Manually trigger check
#   _az_dev_mode_check
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   DEV_MODE unset       Skips silently (production behavior)
#   ZSHAND unset         Skips with no error (can't locate framework)
#   Already ran          Re-entrancy guard prevents duplicate work
#   zprime missing       Should not happen (loaded earlier in sequence)
#
# ── PERFORMANCE ──────────────────────────────────────────────────────────────
#
#   Load time   <1ms (guard check only when dev mode disabled)
#               <200ms (when rebuild is triggered via zprime)
#
#   Benchmark:  hyperfine --warmup 3 'ZSHAND_DEV_MODE=1 zsh -ic exit'
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads: framework source directories    Writes: .zwc bundles (via zprime)
#   Network: None    Gitleaks: Clean
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/startup/05_az_dev_mode_check_spec.sh
#   Run:     just test spec/startup/05_az_dev_mode_check_spec.sh
#   Status:  🚧 No spec
#
#   Must cover:
#     ⬜ Skip when DEV_MODE=0 or unset
#     ⬜ Skip when AUTO_REBUILD=0 or unset
#     ⬜ Re-entrancy guard prevents duplicate runs
#     ⬜ Triggers zprime when framework directories are stale
#     ⬜ Graceful skip when ZSHAND is unset
#
# ── HISTORY ──────────────────────────────────────────────────────────────────
#
#   v1.0  2025-03-10  Initial implementation with re-entrancy guard
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   lib/rebuild/check_with_deps.zsh   Rebuild checking logic
#   core/06_engine.zsh                zprime implementation
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env zsh
# ── aicontext — AI Context Generator for Code Assistants ─────────────────────
#
# Generates comprehensive project context manifests for AI coding assistants.
# Creates markdown with file tree, environment keys, and optional file content.
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   aicontext [depth] [path] [flags]
#
# ── OPTIONS ──────────────────────────────────────────────────────────────────
#
#   <depth>     Tree depth level (1-9, default: 2)
#   <path>      Directory to analyze (default: cwd)
#   -c [file]   Include file content
#   -e          Include sanitized .env keys
#   -h          Show help
#
# ── OUTPUT ───────────────────────────────────────────────────────────────────
#
#   Markdown manifest copied to clipboard containing:
#   - Directory tree, git branch, project type
#   - Environment variables (sanitized)
#   - Token estimate
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   tree      required  Directory visualization
#   wl-copy   required  Wayland clipboard
#   git       optional  Branch detection
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Context generated and copied
#   1  Missing dependencies or invalid arguments
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Via Just
#   just context
#
#   # Direct invocation
#   aicontext                   # Default 2-level tree
#   aicontext 4 ~/project -e   # Deep scan with env
#   aicontext 1 . -c main.py   # Include file content
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   tree not installed   Exits 1 with install hint
#   No .gitignore        tree runs without ignore filter
#   Binary files         Skipped via MIME type detection
#   Very deep trees      Capped by depth argument
#   No clipboard         Outputs to stdout instead of clipboard
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/bin/aicontext_spec.sh
#   Run:     just test spec/bin/aicontext_spec.sh
#   Status:  ⚠️ Partial
#
#   Must cover:
#     ✅ Default invocation (2-level tree, clipboard copy)
#     ✅ Custom depth and path arguments
#     ✅ -h flag shows help and exits 0
#     ✅ Missing tree dependency → exit 1
#     ⬜ -c flag includes file content
#     ⬜ -e flag sanitizes .env keys (no values leaked)
#     ⬜ Output to stdout when clipboard unavailable
#
#   TODO:
#     - Add spec for token estimate accuracy
#     - Add security spec: -e must never include secret values
#
# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads       Directory tree, .env files (keys only), git metadata
#   Writes      Clipboard (wl-copy)
#   Network     None
#   Data        Sanitizes .env values — only key names are included
#   Gitleaks    Clean (secrets never copied to manifest)
#
# ── HISTORY ──────────────────────────────────────────────────────────────────
#
#   v2.0  2025-09-01  Token estimation, -c file content flag, -e env sanitization
#   v1.0  2024-11-20  Basic tree + clipboard output
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   _get_project_context    Project metadata gathering function
#   tree                    https://mama.indstate.edu/users/ice/tree/
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env bash
# ── debian.sh — Debian/Ubuntu System Dependency Installer ────────────────────
#
# Installs system dependencies for zshand on Debian-based distributions.
# Handles packages, shell configuration, and framework setup.
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   bash installers/debian.sh
#
# ── PLATFORM ─────────────────────────────────────────────────────────────────
#
#   Debian, Ubuntu, and derivatives (apt-based)
#
# ── BEHAVIOR ─────────────────────────────────────────────────────────────────
#
#   1  Lock management       Prevents concurrent execution
#   2  Package installation  apt update + install core deps
#   3  Tool installation     Downloads tools not in repos
#   4  Shell configuration   Sets zsh as default shell
#   5  Framework setup       Runs modular directory/link scripts
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   sudo   required  Privileged package installation
#   apt    required  Debian package manager
#   curl   required  Tool downloads
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Installation completed
#   1  Failed or another instance running
#
# ── TROUBLESHOOTING ──────────────────────────────────────────────────────────
#
#   "Another instance is running"   → Remove lock: rm /tmp/zshand-install.lock
#   "Permission denied"             → Run with: sudo bash installers/debian.sh
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Fresh install on a new Debian machine
#   bash installers/debian.sh
#
#   # Via Dev Container (automatic)
#   # .devcontainer/postCreateCommand runs this for you
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   No internet          apt update fails with clear error
#   Already installed    Packages skip gracefully (apt idempotent)
#   Non-Debian distro    Exits with unsupported platform message
#   Concurrent runs      Lock file prevents corruption
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#   Note: Uses bash, not zsh — ShellCheck dialect set to bash
#
# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads       Package lists, /etc/os-release
#   Writes      System packages via apt, shell config via chsh
#   Network     Downloads packages from apt repos and GitHub releases
#   Privileges  Requires sudo for package installation
#   Data        System configuration only; no user data or credentials
#   Gitleaks    Clean (no secrets in installer scripts)
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/installers/debian_spec.sh (🚧 not yet written)
#   Status:  🚧 No spec (manual verification in Dev Container)
#
#   Must cover:
#     ⬜ Lock file prevents concurrent execution
#     ⬜ Core package installation completes
#     ⬜ Shell set to zsh after install
#     ⬜ Graceful failure on non-Debian systems
#
# ── HISTORY ──────────────────────────────────────────────────────────────────
#
#   v2.0  2025-04-15  Modular directory/link scripts, lock management
#   v1.0  2024-11-20  Monolithic package installation
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   installers/manjaro.sh        Manjaro/Arch variant
#   setup.zsh                    Framework setup entry point
#   .devcontainer/               One-click container setup
#
# ─────────────────────────────────────────────────────────────────────────────

# ── _zshand_network_monitor — Background Network State Tracker ───────────────
#
# Private background service that monitors connectivity and triggers Atuin
# sync on reconnection. Internal to the framework; not for direct user use.
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   _zshand_network_monitor
#   Called internally by _zshand_start_network_monitor() at shell init.
#   Enabled via: ZSHAND_NETWORK_MONITOR=1
#
# ── BEHAVIOR ─────────────────────────────────────────────────────────────────
#
#   - Network check: Pings 8.8.8.8 with 0.5s timeout
#   - State tracking: $ZSHAND_CACHE_DIR/network_state
#   - Sync trigger: atuin sync on offline → online transition
#   - Service lifecycle: 30s startup delay, 5min check interval
#   - Lock file coordination prevents duplicate monitors
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   atuin     required  History sync tool
#   ping      required  Network connectivity test
#   timeout   required  Command timeout wrapper
#   stat      optional  Lock file age check
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Monitor running normally (infinite loop, never exits cleanly)
#   1  Another instance already running (lock file exists)
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Enable network monitoring
#   export ZSHAND_NETWORK_MONITOR=1
#   # (monitor starts automatically at next shell init)
#
#   # Check if monitor is running
#   cat "$ZSHAND_CACHE_DIR/network_state"
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   No network at all    State stays "offline", no sync attempted
#   Lock file stale      Age check prevents permanent lock
#   atuin not installed  Should not happen (guard in caller)
#
# ── PERFORMANCE ──────────────────────────────────────────────────────────────
#
#   Background service — minimal CPU (<0.1% at 5min interval)
#   Memory: ~2MB resident (subshell with sleep loop)
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads       Lock file, network state file
#   Writes      Network state file, lock file
#   Network     ICMP ping to 8.8.8.8 (connectivity check)
#   Privileges  None (user-level only)
#   Gitleaks    Clean
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/private_functions/_zshand_network_monitor_spec.sh
#   Run:     just test spec/private_functions/
#   Status:  🚧 No spec
#
#   Must cover:
#     ⬜ Lock file prevents duplicate monitors
#     ⬜ Offline → online triggers atuin sync
#     ⬜ Stale lock file detection and cleanup
#     ⬜ Graceful behavior when atuin missing
#
# ── HISTORY ──────────────────────────────────────────────────────────────────
#
#   v1.0  2025-01-20  Initial implementation with lock file coordination
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   hooks/02_atuin.zsh    Atuin initialization hook
#   atuin                 https://atuin.sh/
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env zsh
# ── check_with_deps — Rebuild Check Including Dependencies ───────────────────
#
# Dependency-aware rebuild checking. Returns success (exit 0) if the
# directory or any of its declared dependencies needs recompilation.
# Enables efficient incremental rebuilds.
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   _zshand_check_needs_rebuild_directory_with_deps "/path/to/dir" [base_dir]
#
# ── ARGUMENTS ────────────────────────────────────────────────────────────────
#
#   $1  Directory path to check (string, required)
#   $2  Base directory for resolving dependencies (string, optional, default: $ZSHAND)
#
# ── BEHAVIOR ─────────────────────────────────────────────────────────────────
#
#   1  Validates directory path is provided
#   2  Checks if directory itself needs rebuild
#   3  Reads .zshand-deps manifest for declared dependencies
#   4  Checks each dependency for staleness
#   5  Returns 0 if any component needs rebuild, 1 otherwise
#
# ── FILES ────────────────────────────────────────────────────────────────────
#
#   $dir/.zshand-deps   optional  Dependency manifest (one dir name per line)
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   _zshand_check_needs_rebuild_directory   Core rebuild check
#   _zshand_read_manifest_deps              Manifest reader
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Rebuild needed (directory or dependency is stale)
#   1  No rebuild needed (everything is current)
#   1  Missing directory path argument
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   # Check if widgets directory needs rebuild
#   if _zshand_check_needs_rebuild_directory_with_deps "$ZSHAND/widgets"; then
#     echo "Rebuild needed"
#   fi
#
# ── EDGE CASES ───────────────────────────────────────────────────────────────
#
#   No .zshand-deps     Only checks the directory itself
#   Circular deps       Not detected (caller responsibility)
#   Missing base_dir    Falls back to $ZSHAND, skips if unset
#
# ── PERFORMANCE ──────────────────────────────────────────────────────────────
#
#   Execution time   <5ms (file stat operations only)
#   Complexity       O(d) where d = number of declared dependencies
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── SECURITY ─────────────────────────────────────────────────────────────────
#
#   Reads: .zshand-deps manifests, directory stats    Writes: None
#   Network: None    Gitleaks: Clean
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec:    spec/lib/rebuild/check_with_deps_spec.sh
#   Run:     just test spec/lib/rebuild/check_with_deps_spec.sh
#   Status:  ✅ Passing
#
#   Must cover:
#     ✅ Directory needs rebuild (stale .zwc)
#     ✅ Directory is current (no rebuild)
#     ✅ Dependency triggers rebuild
#     ✅ Missing directory path argument
#     ⬜ No .zshand-deps manifest
#     ⬜ Missing base_dir fallback
#
# ── HISTORY ──────────────────────────────────────────────────────────────────
#
#   v1.0  2025-02-10  Initial implementation with manifest-based dependency resolution
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   lib/rebuild/dirs.zsh          Framework directory listing
#   core/06_engine.zsh            zprime uses this for incremental rebuilds
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env shellspec
# ── profile_bundle_report_spec — Report Generator Tests ───────────────────
#
# Tests for build/profile_bundle_report.zsh covering report generation,
# grading boundaries, gum/plain-text paths, and error handling.
#
# ── RUN ──────────────────────────────────────────────────────────────────────
#
#   just test spec/build/profile_bundle_report_spec.sh
#   shellspec spec/build/profile_bundle_report_spec.sh
#
# ── FIXTURES ─────────────────────────────────────────────────────────────────
#
#   spec/fixtures/timing.log   Mock timing data
#   spec/fixtures/empty.log    Empty log for error path
#
# ── COVERAGE ─────────────────────────────────────────────────────────────────
#
#   Kcov target: 90%+ (measured in CI)
#
# ─────────────────────────────────────────────────────────────────────────────

#!/usr/bin/env shellspec
# spec/shared_functions/stderr_error_spec.sh

Describe 'stderr_error'
  It 'prints red error to stderr'
    When call stderr_error "test message"
    The stderr should include "ERROR:"
    The stderr should include "test message"
  End
End

# spec/spec_helper.sh - ShellSpec bootstrap
# Loaded automatically before all specs.
# See: https://github.com/shellspec/shellspec#spec_helpersh

set -eu
shellspec_spec_helper_configure() {
  : # Custom setup here
}

# ZSHAND Profile Report - Acceptable Slow Operations
#
# Format: pattern|max_time_ms|reason
#
#   pattern      Glob matching filename (e.g., "*.zsh" or "exact.zsh")
#   max_time_ms  Maximum acceptable time in milliseconds
#   reason       Why this operation is acceptable
#
# Examples:
#   10-you-should-use.zsh|20|Command suggestions worth the cost
#   02_atuin.zsh|15|History search integration justified
#
# Lines starting with # are comments.

# Dependencies for this directory (one per line)
core
private_functions

# ZSHAND Justfile — Development task orchestration
# Run `just --list` for available recipes.
# See: https://just.systems/man/en/

set shell := ["zsh", "-cu"]

# Run the full test suite
test *ARGS:
    shellspec {{ ARGS }}

# Benchmark shell startup time
bench:
    hyperfine --warmup 3 'zsh -ic exit'

# Lint all shell files
lint:
    trunk check

# .envrc — Auto-loaded by direnv on cd
# Manages development environment variables.
# Secrets: loaded from .env (gitignored) via dotenv
# See: https://direnv.net/

dotenv_if_exists .env
export ZSHAND_DEV_MODE=1

# .editorconfig — Consistent formatting across all editors
# See: https://editorconfig.org/

root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.zsh]
indent_size = 4

[Justfile]
indent_size = 4

// .devcontainer/devcontainer.json
// One-click dev environment for ZSHAND contributors.
// Opens in VS Code / Cursor with all tooling pre-installed.
// See: https://containers.dev/
{
  "name": "zshand-dev",
  "image": "mcr.microsoft.com/devcontainers/base:debian",
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {},
  },
  "postCreateCommand": "zsh setup.zsh",
}

✅ Good:
  ZSHAND_CACHE_DIR    string  auto     Cache directory
  ZSHAND_BASE_DIR     string  auto     Framework base
  COLUMNS             int     auto     Terminal width

❌ Bad:
  ZSHAND_CACHE_DIR string auto Cache directory
  ZSHAND_BASE_DIR string auto Framework base
  COLUMNS int auto Terminal width

markdown_extensions:
  - admonition # !!! tip, !!! warning, etc.
  - pymdownx.details # Collapsible admonitions (??? tip)
  - pymdownx.superfences # Nested code blocks inside admonitions
  - pymdownx.emoji: # :emoji: shortcodes
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.tabbed: # Tabbed content blocks
      alternate_style: true
  - toc:
      permalink: true # Anchor links on every heading

nav:
  - Home: index.md
  - Standards:
      - Header Standard: HEADER_STANDARD.md
  - ...

# ── SECTION NAME ─────────────────────────────────────────────────────────────

# ── name — Short Description ─────────────────────────────────────────────────
#
# ── USAGE ────────────────────────────────────────────────────────────────────
#
#   name [args]
#
# ── DEPENDENCIES ─────────────────────────────────────────────────────────────
#
#   dep_name   required  What it does
#
# ── EXIT CODES ───────────────────────────────────────────────────────────────
#
#   0  Success
#   1  Failure
#
# ── EXAMPLES ─────────────────────────────────────────────────────────────────
#
#   name arg1 arg2
#
# ── TESTING ──────────────────────────────────────────────────────────────────
#
#   Spec: spec/dir/name_spec.sh    Run: just test spec/dir/
#   Status: 🚧 No spec    Must cover: happy path, missing deps
#
# ── LINTING ──────────────────────────────────────────────────────────────────
#
#   Clean: ShellCheck + shfmt (Trunk-managed, no overrides)
#
# ── SEE ALSO ─────────────────────────────────────────────────────────────────
#
#   related_file.zsh   What it does
#
# ─────────────────────────────────────────────────────────────────────────────

🌍 Variable table:   NAME░░░░░░type░░░░default░░Description
📦 Dependency table: name░░░░░░required░Description
🚪 Exit code table:  0░░Description
⚠️ Edge case table:  Condition░░░░░░░░→ Behavior
📂 Files table:      path░░░░░░░░required░Description
🔒 Security table:   Field░░░░░░░Value

#   v2.0  2026-02-03  Description of what changed
#                     Continuation line (indented to description column)
#   v1.0  2024-11-20  Initial implementation