@masculinecache/chezmoi-axi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 masculinecache
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,309 @@
+# chezmoi-axi
+
+Agent-ergonomic TOON wrapper around [chezmoi](https://www.chezmoi.io/) for token-efficient dotfiles management.
+
+`chezmoi-axi` is a thin, [AXI](https://toonformat.dev/)-compliant bash CLI that wraps the `chezmoi` binary and emits
+[TOON](https://toonformat.dev/) on stdout — compact, token-efficient output that agents can consume without a
+JSON-parsing round trip. It stays close to chezmoi's own command surface: anything you would do with `chezmoi`
+you can do with `chezmoi-axi`, plus predictable list schemas, definitive empty states, aggregate counts, content
+truncation with a `--full` escape hatch, and structured errors with actionable suggestions.
+
+## Install
+
+```sh
+npm install -g @masculinecache/chezmoi-axi
+```
+
+Or copy the single self-contained script to a directory on `PATH`:
+
+```sh
+install -m 0755 chezmoi-axi ~/.local/bin/chezmoi-axi
+```
+
+Requires the `chezmoi` binary on `PATH` (install it with `brew install chezmoi`, your distro package manager, or
+[the official installer](https://www.chezmoi.io/install/)). The wrapper resolves the chezmoi source directory from
+`$HOME` at runtime (default `~/.local/share/chezmoi`), so it works on any machine without editing the script.
+
+## Usage
+
+```
+chezmoi-axi <command> [args]
+```
+
+Run with no arguments to see the home view (content first — live state, not a manual).
+
+```
+$ chezmoi-axi
+chezmoi:
+  bin: ~/.local/bin/chezmoi-axi
+  description: Agent-ergonomic chezmoi wrapper for dotfiles management
+  managed: 1039
+  changed: 2
+  encrypted: 38
+  last_sync: 2h ago
+help[3]:
+  Run `chezmoi-axi list --changed` to see pending changes
+  Run `chezmoi-axi diff` to review diffs
+  Run `chezmoi-axi list` to see all managed files
+```
+
+Every subcommand supports `--help` (and `-h`) with a concise usage summary. Unknown flags fail loudly, list the
+valid flags, and exit `2` so the agent self-corrects in one step.
+
+## Commands
+
+### `status`
+
+Home view — shows current state at a glance. This is the default when run with no arguments.
+
+```
+$ chezmoi-axi status
+```
+
+Outputs managed count, pending-diff count, encrypted count, and last sync time (derived from the most recent
+commit in the chezmoi source). The `bin:` line collapses paths under `$HOME` to `~`.
+
+### `list`
+
+List managed files with a minimal schema: `path`, `type`, `encrypted`.
+
+```
+$ chezmoi-axi list
+files[5]{path,type,encrypted}:
+  ~/.bashrc,shell,no
+  ~/.config/opencode/opencode.json,json,no
+  ~/.config/opencode/.groq-key,file,maybe
+  ~/.ssh/config,ssh,no
+  ~/.tmux.conf,config,no
+count: 5 of 1039 total
+help[2]:
+  Run `chezmoi-axi add <file>` to track a new file
+  Run `chezmoi-axi diff` to review changes
+```
+
+| Sub | Meaning |
+| --- | --- |
+| `list` | All managed files |
+| `list --changed` | Only files with pending diffs |
+| `list --encrypted` | Only encrypted (age) files |
+| `list --full` | Show every file (bypass the 50-row cap) |
+
+When the result exceeds 50 rows, the list is truncated to the first 50 and a help hint points at `--full` to see
+all of them. An empty result is stated explicitly:
+
+```
+files: 0 changed files found
+help[1]:
+  Run `chezmoi-axi list` to see all managed files
+```
+
+### `diff`
+
+Show differences between source state and installed files.
+
+```
+$ chezmoi-axi diff
+chezmoi-axi diff              # all diffs
+chezmoi-axi diff <file>       # diff for a specific file
+```
+
+Output is a TOON summary with one row per changed file plus aggregate counts:
+
+```
+diffs:
+  .bashrc
+  .tmux.conf
+summary: 2 files, +12 -3
+help[2]:
+  Run `chezmoi-axi apply` to apply these changes
+  Run `chezmoi-axi apply --preview` to dry-run first
+```
+
+`diff <file>` for a path not managed by chezmoi returns a structured error (exit `1`) with a suggestion to `add`
+it. An empty diff reports `diffs: 0 files with changes` (exit `0`).
+
+### `add`
+
+Add a file to chezmoi source state. Idempotent — no error if already tracked (exit `0`).
+
+```
+$ chezmoi-axi add ~/.config/app/config.json
+added: ~/.config/app/config.json
+summary: 1 added, 0 skipped
+help[2]:
+  Run `chezmoi-axi diff` to verify no drift
+  Run `chezmoi-axi commit` to commit and push
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--encrypt`, `-e` | Encrypt the file with age before adding |
+
+Already-managed files report `already managed:` and count as skipped, not failed. A missing file reports
+`error: file not found:`.
+
+### `re-add`
+
+Capture on-disk changes back to source state. Runs `chezmoi re-add --dry-run --verbose` first and branches on the
+tool's feedback.
+
+```
+$ chezmoi-axi re-add ~/.bashrc
+$ chezmoi-axi re-add --all      # re-add all changed files
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--all`, `-a` | Re-add all changed files |
+
+Verdicts per file:
+
+- **`re-added: <file>`** — change captured to source state.
+- **`skipped: template-managed`** — the source is a `.tmpl`; re-add cannot merge live-file edits into a
+  template, so it skips (exit `0`). Edit the template directly and verify with
+  `chezmoi execute-template < src | diff - <target>`.
+- **`in sync: <file>`** — nothing to capture.
+
+Summary: `summary: N re-added, N skipped (template-managed), N in sync`.
+
+### `apply`
+
+Apply source state to installed files.
+
+```
+$ chezmoi-axi apply              # apply
+$ chezmoi-axi apply --preview    # dry run — shows what would change
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--preview`, `-n` | Show what would change without applying (runs `diff`) |
+
+On success: `applied: changes applied successfully`. On failure: structured `error: chezmoi apply failed` with a
+`help` hint to `diff`.
+
+### `verify`
+
+Check that installed files match source state. Exit `0` if clean, `1` if drifted.
+
+```
+$ chezmoi-axi verify
+verify: all tracked files match source state
+help[2]:
+  Run `chezmoi-axi list` to see managed files
+  Run `chezmoi-axi diff` to check for pending changes
+```
+
+When drift is detected, it reports the count and returns exit `1` (which agents can branch on):
+
+```
+verify: 2 files have drifted from source state
+help[2]:
+  Run `chezmoi-axi diff` to see what changed
+  Run `chezmoi-axi re-add --all` to capture changes
+```
+
+### `sync`
+
+Pull remote changes and apply. Combines `git fetch` + `chezmoi update`.
+
+```
+$ chezmoi-axi sync               # fetch + apply
+$ chezmoi-axi sync --preview     # fetch + diff, no apply
+$ chezmoi-axi sync --force       # apply without prompting (resolves local drift, for cron)
+$ chezmoi-axi sync --branch dev  # sync a non-default branch explicitly
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--preview`, `-n` | Fetch remote and show the diff without applying |
+| `--force`, `-f` | Apply without prompting (resolves local drift; for cron) |
+| `--branch <name>` | Sync `<name>` instead of the default branch (escape hatch; checks the branch out if needed) |
+
+**Branch guard.** Sync only auto-checks out the default branch (`master`, detected from
+`origin/HEAD`) when the current branch is not the default. Before switching it checks for
+(a) uncommitted changes and (b) local work not yet in `origin/master` — HEAD is fully merged
+when it is an ancestor of `origin/master` or its only local commits are merge commits. If
+either check fails, sync **fails without switching or pulling** and reports a structured error
+naming the branch, the stranded commit count, and the recovery command:
+
+```
+error: sync blocked: branch 'feature' has live work (uncommitted: true, unpushed: 2)
+help[2]:
+  recover: commit or push on 'feature', then rerun `chezmoi-axi sync`
+  deliberate: run `chezmoi-axi sync --branch feature` to sync this branch anyway
+```
+
+Only a clean, fully-merged branch (all work already in `origin/master`, merge commits
+included) is auto-checked out to the default branch. To sync a
+non-default branch deliberately, pass `--branch <name>`.
+
+Every sync stamps ISO-8601 `start` and `end` lines — the `end` line carries the exit code — so the periodic
+crontab log is auditable:
+
+```
+[2026-08-28T09:15:00+0200] chezmoi-axi sync start
+[2026-08-28T09:15:03+0200] chezmoi-axi sync end rc=0
+```
+
+Before running, sync rotates the canonical cron log `~/.local/share/chezmoi/.chezmoi-sync.log` to `.old` once it
+exceeds 512 KiB (override with `CHEZMOI_SYNC_LOG_MAX` bytes); other redirections are untouched. It also exports a
+passphrase-free `GIT_SSH_COMMAND` deploy key so sync never prompts — safe for cron, agents, and headless contexts.
+
+### `commit` [message]
+
+Stage all chezmoi changes, commit, push, and open a PR. Uses conventional commits.
+
+```
+$ chezmoi-axi commit                          # auto-generated message
+$ chezmoi-axi commit "feat(app): add new config"
+```
+
+If the working tree is clean it reports `commit: nothing to commit` (exit `0`). Otherwise it auto-generates a
+`chore(dotfiles): update N managed files` message when none is given, pushes a timestamped branch, and opens a PR
+against `master` via `gh`.
+
+## Output
+
+Structured data is emitted as TOON on **stdout**. Errors also go to stdout, in a structured form with an
+actionable suggestion, and map to a stable exit code:
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | success (including no-ops and empty results) |
+| `1` | runtime error (e.g. file not found, drift detected, apply/sync failed) |
+| `2` | usage error (unknown flag, missing required arg, unknown command) |
+
+```
+$ chezmoi-axi list --bogus
+error: unknown flag: --bogus
+help: chezmoi-axi list [--changed] [--encrypted] [--full]
+```
+(exit 2)
+
+Unknown flags fail loudly and list the valid flags so the agent self-corrects in one step. `--help` is always
+allowed. No command prompts interactively — every operation is completable with flags alone. chezmoi's own
+errors are translated into the structured format above and raw dependency stack traces are never leaked to
+stdout.
+
+## Integrations
+
+`chezmoi-axi` follows the AXI ambient-context pattern: run it with no arguments (or `status`) to get a compact
+home-view dashboard that can be surfaced to an agent at session start. The same output powers the
+[installable skill](https://github.com/masculinecache/chezmoi-axi/blob/master/skills/chezmoi-axi/SKILL.md), which lets
+agents work with chezmoi through a stable TOON interface.
+
+## Development
+
+```sh
+bash -n chezmoi-axi                  # syntax check
+shellcheck -S error chezmoi-axi      # static analysis (error level)
+./tests/run.sh                       # test suite (bash only, no dependencies)
+```
+
+The test suite runs the executable through its public CLI surface (list, diff, add, re-add, sync, verify,
+structured errors, exit codes) against a mock `chezmoi` binary — no real dotfiles or network required.
+
+## License
+
+MIT

package/chezmoi-axi

@@ -0,0 +1,713 @@
+#!/usr/bin/env bash
+# chezmoi-axi — Agent-ergonomic chezmoi wrapper with TOON output
+# Follows AXI 10 principles: token-efficient, minimal schemas, structured errors
+set -euo pipefail
+
+BIN_PATH="${BASH_SOURCE[0]}"
+DESCRIPTION="Agent-ergonomic chezmoi wrapper for dotfiles management"
+CHEZMOI_SRC="${HOME}/.local/share/chezmoi"
+
+# --- Helpers ---
+
+die() {
+  echo "error: $1"
+  [[ -n "${2:-}" ]] && echo "help: $2"
+  exit 1
+}
+
+# Usage errors (unknown flag, missing required arg) exit 2 per AXI; runtime
+# errors (file not found, drift, etc.) exit 1 via die().
+usage_error() {
+  echo "error: $1"
+  [[ -n "${2:-}" ]] && echo "help: $2"
+  exit 2
+}
+
+help_hint() {
+  local hints=("$@")
+  if [[ ${#hints[@]} -gt 0 ]]; then
+    echo "help[${#hints[@]}]:"
+    for h in "${hints[@]}"; do
+      echo "  $h"
+    done
+  fi
+}
+
+toon_list() {
+  # $1 = header label, $2 = fields spec, then data lines
+  local label="$1" fields="$2"
+  shift 2
+  echo "${label}[$#]{${fields}}:"
+  for item in "$@"; do
+    echo "  $item"
+  done
+}
+
+# Map a target path (~/.ssh/config) to its source template entry if the target
+# is managed by a template (dot_ssh/config.tmpl). Prints the source path and
+# returns 0 if template-managed, 1 otherwise.
+template_source_for() {
+  local target="$1"
+  local rel="${target#$HOME/}"
+  local rel_dir rel_base mapped_dir=""
+  rel_dir=$(dirname "$rel")
+  rel_base=$(basename "$rel")
+
+  # Map dir components: .ssh -> dot_ssh
+  local p
+  IFS='/' read -ra parts <<< "$rel_dir"
+  for p in "${parts[@]}"; do
+    [[ -z "$p" || "$p" == "." ]] && continue
+    if [[ "$p" == .* ]]; then
+      mapped_dir="${mapped_dir}/dot_${p#.}"
+    else
+      mapped_dir="${mapped_dir}/${p}"
+    fi
+  done
+
+  # Map file component: .bashrc -> dot_bashrc
+  local src_base="$rel_base"
+  [[ "$src_base" == .* ]] && src_base="dot_${src_base#.}"
+
+  local candidates=("${CHEZMOI_SRC}${mapped_dir}/${src_base}.tmpl")
+  if [[ -n "$mapped_dir" ]]; then
+    candidates+=(
+      "${CHEZMOI_SRC}/private_${mapped_dir#/}/${src_base}.tmpl"
+      "${CHEZMOI_SRC}/encrypted_${mapped_dir#/}/${src_base}.tmpl"
+    )
+  else
+    candidates+=(
+      "${CHEZMOI_SRC}/private_${src_base}.tmpl"
+      "${CHEZMOI_SRC}/encrypted_${src_base}.tmpl"
+    )
+  fi
+
+  local c
+  for c in "${candidates[@]}"; do
+    if [[ -f "$c" ]]; then
+      echo "$c"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Re-add a single target with dry-run branch verdicts (Principle 5, 8).
+# Returns: 0 = re-added, 2 = skipped (template-managed), 3 = in sync
+readd_one() {
+  local f="$1"
+  f="${f/#\~/$HOME}"
+  [[ "$f" != /* ]] && f="${HOME}/${f}"   # normalize relative paths (--all mode)
+
+  if [[ ! -e "$f" ]]; then
+    echo "error: file not found: ~${f#"$HOME"}"
+    return 1
+  fi
+
+  local dry_out src
+  # -n -v: dry-run with verbose diff on stderr — the only re-add feedback that
+  # distinguishes "has changes" from "nothing to do". Without -v, --dry-run is
+  # silent even for files with pending changes.
+  dry_out=$(chezmoi re-add --dry-run --verbose "$f" 2>&1 || true)
+
+  if [[ -n "$dry_out" ]]; then
+    if chezmoi re-add "$f" >/dev/null 2>&1; then
+      echo "re-added: ~${f#"$HOME"}"
+      return 0
+    fi
+    echo "error: failed to re-add ~${f#"$HOME"}"
+    return 1
+  fi
+
+  # Empty dry-run: nothing would change. re-add silently skips template-managed
+  # files (documented: "chezmoi will not overwrite templates"; exits 0, no
+  # source change) — flag them instead of reporting success.
+  if src=$(template_source_for "$f"); then
+    echo "skipped: ~${f#"$HOME"} is template-managed (source ${src#$CHEZMOI_SRC/})"
+    echo "  re-add cannot merge live-file edits into a template - edit the template directly"
+    echo "  verify: chezmoi execute-template < ${src#$CHEZMOI_SRC/} | diff - ~${f#$HOME}"
+    return 2
+  fi
+
+  echo "in sync: ~${f#"$HOME"} (no changes to capture)"
+  return 3
+}
+
+# --- Commands ---
+
+cmd_status() {
+  local managed_count changed_count encrypted_count last_sync="never"
+
+  managed_count=$(chezmoi managed 2>/dev/null | wc -l || true)
+  changed_count=$(chezmoi diff 2>/dev/null | grep '^diff --git' | wc -l || true)
+  encrypted_count=$(find "$CHEZMOI_SRC" -name 'encrypted_*' -type f 2>/dev/null | wc -l || true)
+
+  # Last sync: most recent commit in chezmoi source
+  if [[ -d "$CHEZMOI_SRC/.git" ]]; then
+    local last_epoch
+    last_epoch=$(chezmoi git -- log -1 --format=%ct 2>/dev/null || echo 0)
+    if [[ "$last_epoch" -gt 0 ]]; then
+      local now diff_s
+      now=$(date +%s)
+      diff_s=$(( now - last_epoch ))
+      if (( diff_s < 3600 )); then
+        last_sync="$(( diff_s / 60 ))m ago"
+      elif (( diff_s < 86400 )); then
+        last_sync="$(( diff_s / 3600 ))h ago"
+      else
+        last_sync="$(( diff_s / 86400 ))d ago"
+      fi
+    fi
+  fi
+
+  echo "chezmoi:"
+  local bin_display="$BIN_PATH"
+  [[ "$bin_display" == "$HOME"* ]] && bin_display="~${bin_display#"$HOME"}"
+  echo "  bin: ${bin_display}"
+  echo "  description: ${DESCRIPTION}"
+  echo "  managed: ${managed_count}"
+  echo "  changed: ${changed_count}"
+  echo "  encrypted: ${encrypted_count}"
+  echo "  last_sync: ${last_sync}"
+
+  local hints=()
+  if (( changed_count > 0 )); then
+    hints+=("Run \`chezmoi-axi list --changed\` to see pending changes")
+    hints+=("Run \`chezmoi-axi diff\` to review diffs")
+  fi
+  hints+=("Run \`chezmoi-axi list\` to see all managed files")
+  help_hint "${hints[@]}"
+}
+
+cmd_list() {
+  local filter="all" full=false
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --changed)  filter="changed"; shift ;;
+      --encrypted) filter="encrypted"; shift ;;
+      --full)     full=true; shift ;;
+      -h|--help)
+        echo "Usage: chezmoi-axi list [--changed] [--encrypted] [--full]"
+        echo "  --changed    Show only files with pending diffs"
+        echo "  --encrypted  Show only encrypted files"
+        echo "  --full       Show every file (bypass the 50-row cap)"
+        exit 0 ;;
+      *) usage_error "unknown flag: $1" "chezmoi-axi list [--changed] [--encrypted] [--full]" ;;
+    esac
+  done
+
+  local files=()
+  case "$filter" in
+    changed)
+      while IFS= read -r line; do
+        local f
+        f=$(echo "$line" | sed 's|^diff --git a/.* b/||')
+        files+=("$f")
+      done < <(chezmoi diff 2>/dev/null | grep '^diff --git')
+      ;;
+    encrypted)
+      while IFS= read -r f; do
+        local target
+        target=$(basename "$f" | sed 's/^encrypted_//' | sed 's/\.age$//' | sed 's/^private_//')
+        # Map source name back to target path
+        local relpath="${f#$CHEZMOI_SRC/}"
+        relpath=$(echo "$relpath" | sed 's|^dot_|.|' | sed 's|^encrypted_||' | sed 's|\.age$||' | sed 's|^private_|.|')
+        files+=("~/${relpath}")
+      done < <(find "$CHEZMOI_SRC" -name 'encrypted_*' -type f 2>/dev/null)
+      ;;
+    all)
+      while IFS= read -r f; do
+        local relpath="${f#$CHEZMOI_SRC/}"
+        relpath=$(echo "$relpath" | sed 's|^dot_|.|' )
+        files+=("~/${relpath}")
+      done < <(chezmoi managed 2>/dev/null)
+      ;;
+  esac
+
+  local count=${#files[@]}
+  local total
+  total=$(chezmoi managed 2>/dev/null | wc -l || true)
+
+  if (( count == 0 )); then
+    echo "files: 0 ${filter} files found"
+    help_hint "Run \`chezmoi-axi list\` to see all managed files"
+    return 0
+  fi
+
+  # Truncate if >50 files (Principle 3); --full bypasses the cap (escape hatch)
+  local display_files=("${files[@]}")
+  local truncated=false
+  if [[ "$full" != "true" && "$count" -gt 50 ]]; then
+    display_files=("${files[@]:0:50}")
+    truncated=true
+  fi
+
+  echo "files[${count}]{path,type,encrypted}:"
+  for f in "${display_files[@]}"; do
+    local enc="no"
+    [[ "$f" == *"secret"* || "$f" == *"key"* || "$f" == *".env"* ]] && enc="maybe"
+    # Determine type from extension
+    local ext="${f##*.}"
+    local ftype="file"
+    [[ "$ext" == "sh" || "$ext" == "bash" || "$ext" == "zsh" ]] && ftype="shell"
+    [[ "$ext" == "json" ]] && ftype="json"
+    [[ "$ext" == "yaml" || "$ext" == "yml" ]] && ftype="yaml"
+    [[ "$ext" == "toml" ]] && ftype="toml"
+    [[ "$ext" == "conf" || "$ext" == "cfg" ]] && ftype="config"
+    [[ "$ext" == "age" ]] && ftype="encrypted"
+    echo "  ${f},${ftype},${enc}"
+  done
+
+  if (( count != total )); then
+    echo "count: ${count} of ${total} total"
+  fi
+  if [[ "$truncated" == "true" ]]; then
+    echo "  ... (${count} total, showing first 50)"
+    echo "help[1]: Run \`chezmoi-axi list --full\` for all ${count} files"
+  fi
+
+  local hints=()
+  hints+=("Run \`chezmoi-axi add <file>\` to track a new file")
+  [[ "$filter" == "all" ]] && hints+=("Run \`chezmoi-axi diff\` to review changes")
+  help_hint "${hints[@]}"
+}
+
+cmd_diff() {
+  local target="${1:-}"
+  local raw_diff
+
+  if [[ -n "$target" ]]; then
+    # Diff specific file
+    local src_path
+    src_path=$(chezmoi managed --include files 2>/dev/null | grep -i "$(basename "$target")" | head -1 || true)
+    if [[ -z "$src_path" ]]; then
+      die "file not managed by chezmoi: $target" "Run \`chezmoi-axi add $target\` to start tracking it"
+    fi
+    raw_diff=$(chezmoi diff -- "$target" 2>/dev/null || true)
+  else
+    raw_diff=$(chezmoi diff 2>/dev/null || true)
+  fi
+
+  if [[ -z "$raw_diff" ]]; then
+    echo "diffs: 0 files with changes"
+    help_hint "Run \`chezmoi-axi list\` to see all managed files"
+    return 0
+  fi
+
+  # Parse diff into TOON summary
+  local files_changed=0
+  local total_add=0
+  local total_del=0
+  echo "diffs:"
+  while IFS= read -r line; do
+    if [[ "$line" == diff\ --git* ]]; then
+      (( files_changed++ )) || true
+      local path
+      path=$(echo "$line" | sed 's|^diff --git a/.* b/||')
+      echo "  ${path}"
+    elif [[ "$line" == @@* ]]; then
+      local stats
+      stats=$(echo "$line" | grep -oP '[+-]\d+' | paste -sd' ' || true)
+      local adds dels
+      adds=$(echo "$stats" | grep -oP '\+\d+' | tr -d '+' | paste -sd'+' | bc 2>/dev/null || echo 0)
+      dels=$(echo "$stats" | grep -oP '-\d+' | tr -d '-' | paste -sd'+' | bc 2>/dev/null || echo 0)
+      (( total_add += adds )) || true
+      (( total_del += dels )) || true
+    fi
+  done <<< "$raw_diff"
+
+  echo "summary: ${files_changed} files, +${total_add} -${total_del}"
+
+  local hints=()
+  (( files_changed > 0 )) && hints+=("Run \`chezmoi-axi apply\` to apply these changes")
+  hints+=("Run \`chezmoi-axi apply --preview\` to dry-run first")
+  help_hint "${hints[@]}"
+}
+
+cmd_add() {
+  local encrypt=false
+  local files=()
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --encrypt|-e) encrypt=true; shift ;;
+      -h|--help)
+        echo "Usage: chezmoi-axi add [--encrypt] <file>..."
+        echo "  --encrypt  Encrypt the file with age before adding"
+        exit 0 ;;
+      -*) usage_error "unknown flag: $1" "chezmoi-axi add [--encrypt] <file>..." ;;
+      *)  files+=("$1"); shift ;;
+    esac
+  done
+
+  [[ ${#files[@]} -eq 0 ]] && usage_error "no files specified" "chezmoi-axi add [--encrypt] <file>..."
+
+  local added=0 skipped=0
+  for f in "${files[@]}"; do
+    # Expand ~ if present
+    f="${f/#\~/$HOME}"
+    if [[ ! -f "$f" ]]; then
+      echo "error: file not found: $f"
+      (( skipped++ )) || true
+      continue
+    fi
+
+    local args=()
+    [[ "$encrypt" == "true" ]] && args+=(--encrypt)
+
+    if chezmoi add "${args[@]}" "$f" 2>/dev/null; then
+      echo "added: ~${f#"$HOME"}"
+      (( added++ )) || true
+    else
+      # Check if already managed
+      if chezmoi managed 2>/dev/null | grep -q "$(basename "$f")"; then
+        echo "already managed: ~${f#"$HOME"}"
+        (( skipped++ )) || true
+      else
+        echo "error: failed to add ~${f#"$HOME"}"
+        (( skipped++ )) || true
+      fi
+    fi
+  done
+
+  echo "summary: ${added} added, ${skipped} skipped"
+  local hints=()
+  (( added > 0 )) && hints+=("Run \`chezmoi-axi diff\` to verify no drift")
+  (( added > 0 )) && hints+=("Run \`chezmoi-axi commit\` to commit and push")
+  (( added == 0 )) && hints+=("Run \`chezmoi-axi list\` to see what's managed")
+  help_hint "${hints[@]}"
+}
+
+cmd_readd() {
+  local add_all=false
+  local files=()
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --all|-a) add_all=true; shift ;;
+      -h|--help)
+        echo "Usage: chezmoi-axi re-add [--all] [file]..."
+        echo "  --all  Re-add all changed files"
+        exit 0 ;;
+      -*) usage_error "unknown flag: $1" "chezmoi-axi re-add [--all] [file]..." ;;
+      *)  files+=("$1"); shift ;;
+    esac
+  done
+
+  if [[ "$add_all" == "true" ]]; then
+    while IFS= read -r line; do
+      local f
+      f=$(echo "$line" | sed 's|^diff --git a/.* b/||')
+      files+=("$f")
+    done < <(chezmoi diff 2>/dev/null | grep '^diff --git')
+  fi
+
+  if [[ ${#files[@]} -eq 0 ]]; then
+    echo "re-added: 0 files (no changes detected)"
+    help_hint "Run \`chezmoi-axi list\` to see all managed files"
+    return 0
+  fi
+
+  local readded=0 skipped=0 insync=0 rc=0
+  for f in "${files[@]}"; do
+    readd_one "$f" || rc=$?
+    if   [[ $rc -eq 0 ]]; then (( readded++ )) || true
+    elif [[ $rc -eq 2 ]]; then (( skipped++ )) || true
+    elif [[ $rc -eq 3 ]]; then (( insync++ )) || true
+    fi
+    rc=0
+  done
+
+  echo "summary: ${readded} re-added, ${skipped} skipped (template-managed), ${insync} in sync"
+
+  local hints=()
+  (( skipped > 0 )) && hints+=("Run \`chezmoi-axi diff\` to review template drift")
+  (( readded > 0 )) && hints+=("Run \`chezmoi-axi diff\` to verify clean state")
+  (( readded > 0 )) && hints+=("Run \`chezmoi-axi commit\` to commit and push")
+  help_hint "${hints[@]}"
+}
+
+cmd_apply() {
+  local preview=false
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --preview|-n) preview=true; shift ;;
+      -h|--help)
+        echo "Usage: chezmoi-axi apply [--preview]"
+        echo "  --preview  Show what would change without applying"
+        exit 0 ;;
+      *) usage_error "unknown flag: $1" "chezmoi-axi apply [--preview]" ;;
+    esac
+  done
+
+  if [[ "$preview" == "true" ]]; then
+    cmd_diff
+    return
+  fi
+
+  local output
+  if output=$(chezmoi apply 2>&1); then
+    echo "applied: changes applied successfully"
+    help_hint "Run \`chezmoi-axi verify\` to confirm state"
+  else
+    echo "error: chezmoi apply failed"
+    echo "$output" | head -5
+    help_hint "Run \`chezmoi-axi diff\` to review what failed"
+    return 1
+  fi
+}
+
+cmd_verify() {
+  local drift_count=0
+  local output
+
+  # chezmoi verify exits 1 for untracked files too; use diff for actual drift detection
+  output=$(chezmoi verify 2>&1 || true)
+  drift_count=$(echo "$output" | grep -c 'has changed' || true)
+
+  # Also check if verify failed but produced no "has changed" lines (untracked files)
+  if (( drift_count > 0 )); then
+    echo "verify: ${drift_count} files have drifted from source state"
+    echo "$output" | head -10
+    help_hint "Run \`chezmoi-axi diff\` to see what changed" \
+              "Run \`chezmoi-axi re-add --all\` to capture changes"
+    return 1
+  fi
+
+  # Check for untracked files (files on disk not in source state)
+  local untracked
+  untracked=$(chezmoi managed --include files 2>/dev/null | wc -l || true)
+  local target_files
+  target_files=$(find "${HOME}" -maxdepth 1 -name '.*' -type f 2>/dev/null | wc -l || true)
+
+  echo "verify: all tracked files match source state"
+  help_hint "Run \`chezmoi-axi list\` to see managed files" \
+            "Run \`chezmoi-axi diff\` to check for pending changes"
+  return 0
+}
+
+cmd_sync() {
+  # Keep the periodic sync log bounded: rotate once past the cap.
+  # Applies to the canonical cron log only; other redirections stay untouched.
+  local sync_log="${CHEZMOI_SRC}/.chezmoi-sync.log"
+  local max_bytes="${CHEZMOI_SYNC_LOG_MAX:-524288}"
+  if [[ -f "$sync_log" && "$(wc -c <"$sync_log")" -ge "$max_bytes" ]]; then
+    cp "$sync_log" "$sync_log.old" && : > "$sync_log"
+  fi
+
+  echo "[$(date '+%Y-%m-%dT%H:%M:%S%z')] chezmoi-axi sync start"
+  local rc=0
+  _sync_run "$@" || rc=$?
+  echo "[$(date '+%Y-%m-%dT%H:%M:%S%z')] chezmoi-axi sync end rc=$rc"
+  return "$rc"
+}
+
+_sync_run() {
+  local preview=false force=false branch_arg=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --preview|-n) preview=true; shift ;;
+      --force|-f)   force=true; shift ;;
+      --branch)
+        if [[ $# -lt 2 || -z "${2:-}" || "${2:-}" == -* ]]; then
+          usage_error "--branch requires a branch name" "chezmoi-axi sync [--preview] [--force] [--branch <name>]"
+        fi
+        branch_arg="$2"; shift 2 ;;
+      -h|--help)
+        echo "Usage: chezmoi-axi sync [--preview] [--force] [--branch <name>]"
+        echo "  --preview        Fetch remote and show diff without applying"
+        echo "  --force          Apply without prompting (resolves local drift, for cron)"
+        echo "  --branch <name>  Sync a non-default branch explicitly (escape hatch)"
+        echo "Stamps start/end (with exit code) around every sync; rotates"
+        echo "  ~/.local/share/chezmoi/.chezmoi-sync.log to .old at 512 KiB"
+        echo "  (CHEZMOI_SYNC_LOG_MAX bytes, for the crontab redirect)"
+        return 0 ;;
+      *) usage_error "unknown flag: $1" "chezmoi-axi sync [--preview] [--force] [--branch <name>]" ;;
+    esac
+  done
+
+  # Force the passphrase-free deploy key for all git SSH operations so
+  # sync never prompts — safe for cron, agents, and headless contexts.
+  export GIT_SSH_COMMAND="ssh -i ~/.ssh/chezmoi-deploy-key -o IdentitiesOnly=yes -o BatchMode=yes"
+
+  echo "syncing: fetching remote changes..."
+  chezmoi git -- fetch origin 2>/dev/null || true
+
+  # Branch guard: never auto-switch away from a branch carrying live work.
+  local current_branch default_branch
+  current_branch=$(chezmoi git -- branch --show-current 2>/dev/null || true)
+  default_branch=$(chezmoi git -- rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|^origin/||' || true)
+  [[ -z "$default_branch" ]] && default_branch="master"
+
+  if [[ -n "$branch_arg" ]]; then
+    # Escape hatch: caller explicitly wants this branch synced.
+    if [[ "$current_branch" != "$branch_arg" ]]; then
+      if ! chezmoi git -- checkout "$branch_arg" >/dev/null 2>&1; then
+        die "cannot check out branch: ${branch_arg}" "Verify the branch exists: \`chezmoi git -- branch --list\`"
+      fi
+      echo "checked out: ${branch_arg}"
+    fi
+  elif [[ -n "$current_branch" && "$current_branch" != "$default_branch" ]]; then
+    # On a non-default branch: fail if there is live work, never auto-switch over it.
+    local dirty=false merged=false unpushed=0
+    [[ -n "$(chezmoi git -- status --porcelain 2>/dev/null || true)" ]] && dirty=true
+    # Fully merged means every commit's work is already on origin/<default>:
+    # either HEAD itself is an ancestor, or the only local commits are merge
+    # commits (e.g. a local merge of origin/<default> after a PR merge).
+    if chezmoi git -- merge-base --is-ancestor "HEAD" "origin/${default_branch}" 2>/dev/null; then
+      merged=true
+    else
+      unpushed=$({ chezmoi git -- log --oneline --no-merges "origin/${default_branch}..HEAD" 2>/dev/null || true; } | wc -l)
+    fi
+    if [[ "$dirty" == "true" || ("$merged" != "true" && "$unpushed" -gt 0) ]]; then
+      echo "error: sync blocked: branch '${current_branch}' has live work (uncommitted: ${dirty}, unpushed: ${unpushed})"
+      echo "help[2]:"
+      echo "  recover: commit or push on '${current_branch}', then rerun \`chezmoi-axi sync\`"
+      echo "  deliberate: run \`chezmoi-axi sync --branch ${current_branch}\` to sync this branch anyway"
+      return 1
+    fi
+    # Clean and fully merged: safe to auto-checkout the default branch.
+    if ! chezmoi git -- checkout "$default_branch" >/dev/null 2>&1; then
+      die "cannot check out default branch: ${default_branch}" "Check \`chezmoi git -- status\` in ${CHEZMOI_SRC}"
+    fi
+    echo "checked out: ${default_branch} (branch '${current_branch}' was clean and merged)"
+  fi
+
+  local remote_branch="$default_branch"
+  [[ -n "$branch_arg" ]] && remote_branch="$branch_arg"
+
+  local remote_commits
+  remote_commits=$({ chezmoi git -- log --oneline "HEAD..origin/${remote_branch}" 2>/dev/null || true; } | wc -l)
+
+  if [[ "$remote_commits" -eq 0 && "$force" != "true" ]]; then
+    echo "sync: already up to date"
+    help_hint "Run \`chezmoi-axi status\` for current state"
+    return 0
+  fi
+
+  if [[ "$remote_commits" -gt 0 ]]; then
+    echo "found: ${remote_commits} new commits on remote"
+  else
+    echo "sync: no new commits, applying to resolve local drift"
+  fi
+
+  if [[ "$preview" == "true" ]]; then
+    echo "diffs:"
+    chezmoi git -- diff --stat "HEAD" "origin/${remote_branch}" 2>/dev/null || true
+    help_hint "Run \`chezmoi-axi sync\` to apply these changes"
+    return 0
+  fi
+
+  local update_args=()
+  [[ "$force" == "true" ]] && update_args+=(--force)
+
+  local output
+  if output=$(chezmoi update "${update_args[@]}" 2>&1); then
+    echo "sync: pulled and applied${force:+ (force)}"
+  else
+    echo "error: chezmoi update failed"
+    echo "$output" | head -10
+    help_hint "Run \`chezmoi-axi diff\` to review what failed"
+    return 1
+  fi
+  help_hint "Run \`chezmoi-axi verify\` to confirm state"
+}
+
+cmd_commit() {
+  local message="${1:-}"
+
+  cd "$CHEZMOI_SRC" || die "chezmoi source dir not found: $CHEZMOI_SRC"
+
+  local changes
+  changes=$(git diff --name-only 2>/dev/null || true)
+  local untracked
+  untracked=$(git ls-files --others --exclude-standard 2>/dev/null || true)
+
+  if [[ -z "$changes" && -z "$untracked" ]]; then
+    echo "commit: nothing to commit"
+    help_hint "Run \`chezmoi-axi status\` for current state"
+    return 0
+  fi
+
+  # Auto-generate message if not provided
+  if [[ -z "$message" ]]; then
+    local file_count
+    file_count=$(echo -e "${changes}\n${untracked}" | grep -c '[^[:space:]]' || true)
+    message="chore(dotfiles): update ${file_count} managed files"
+  fi
+
+  # Stage all changes
+  git add -A 2>/dev/null
+  git commit -m "$message" 2>/dev/null
+
+  # Create branch and push
+  local branch="update-$(date +%Y%m%d-%H%M%S)"
+  git checkout -b "$branch" 2>/dev/null
+  git push -u origin "$branch" 2>/dev/null
+
+  # Open PR
+  local pr_url
+  pr_url=$(gh pr create \
+    --title "$message" \
+    --body "Auto-generated by chezmoi-axi" \
+    --base master 2>/dev/null || echo "")
+
+  if [[ -n "$pr_url" ]]; then
+    echo "commit: pushed and PR created"
+    echo "pr: ${pr_url}"
+  else
+    echo "commit: pushed to branch ${branch}"
+    echo "  Run \`gh pr create --base master\` to open a PR"
+  fi
+
+  # Return to master
+  git checkout master 2>/dev/null
+  git branch -d "$branch" 2>/dev/null || true
+
+  help_hint "Run \`chezmoi-axi status\` to verify state"
+}
+
+cmd_help() {
+  echo "chezmoi-axi — ${DESCRIPTION}"
+  echo ""
+  echo "Commands:"
+  echo "  status       Show current state at a glance"
+  echo "  list         List managed files [--changed] [--encrypted]"
+  echo "  diff         Show diffs between source and installed"
+  echo "  add          Add file to source state [--encrypt]"
+  echo "  re-add       Capture on-disk changes [--all]"
+  echo "  apply        Apply source state to installed files"
+  echo "  verify       Check files match source state"
+  echo "  sync         Pull remote and apply [--preview] [--force] [--branch <name>]"
+  echo "  commit       Commit, push, and open PR"
+  echo "  help         Show this help"
+  echo ""
+  echo "Run \`chezmoi-axi <command> --help\` for command-specific help"
+}
+
+# --- Main ---
+
+main() {
+  local cmd="${1:-status}"
+  shift || true
+
+  case "$cmd" in
+    status)   cmd_status "$@" ;;
+    list|ls)  cmd_list "$@" ;;
+    diff)     cmd_diff "$@" ;;
+    add)      cmd_add "$@" ;;
+    re-add)   cmd_readd "$@" ;;
+    apply)    cmd_apply "$@" ;;
+    verify)   cmd_verify "$@" ;;
+    sync)     cmd_sync "$@" ;;
+    commit)   cmd_commit "$@" ;;
+    help|-h|--help) cmd_help "$@" ;;
+    *)
+      echo "error: unknown command: $cmd"
+      echo "help: valid commands: status, list, diff, add, re-add, apply, verify, sync, commit, help"
+      exit 2
+      ;;
+  esac
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@masculinecache/chezmoi-axi",
+  "version": "0.1.0",
+  "description": "Agent-ergonomic TOON wrapper around chezmoi for token-efficient dotfiles management",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/masculinecache/chezmoi-axi.git"
+  },
+  "homepage": "https://github.com/masculinecache/chezmoi-axi#readme",
+  "bugs": {
+    "url": "https://github.com/masculinecache/chezmoi-axi/issues"
+  },
+  "keywords": [
+    "chezmoi",
+    "dotfiles",
+    "cli",
+    "bash",
+    "agent",
+    "axi",
+    "toon"
+  ],
+  "bin": {
+    "chezmoi-axi": "chezmoi-axi"
+  },
+  "files": [
+    "chezmoi-axi",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bash tests/run.sh"
+  },
+  "license": "MIT"
+}