@sebastienrousseau/dotfiles 0.2.500 → 0.2.502

package/scripts/dot/commands/agents.sh

@@ -0,0 +1,325 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# shellcheck shell=bash
+#
+# scripts/dot/commands/agents.sh
+#
+# `dot agents` — multi-harness AI agent configuration manager.
+#
+# Closes the #1 competitive gap identified in HARD_AUDIT_2026:
+# every other dotfiles framework either targets one AI tool or
+# requires hand-maintenance of N parallel config files. This command
+# keeps CLAUDE.md (canonical) and AGENTS.md (cross-harness standard)
+# in sync, plus stubs the Cursor/Codex tool-specific formats.
+#
+# Subcommands:
+#   render   Regenerate AGENTS.md and tool-specific stubs from CLAUDE.md.
+#   check    Verify AGENTS.md tracks CLAUDE.md (exit 0 in sync, 1 drifted).
+#   list     Show which harnesses are recognised + their target paths.
+#
+# Reads:  CLAUDE.md (repo root) — the canonical agent context.
+# Writes: AGENTS.md, .cursor/rules/dotfiles.mdc, .codex/config.toml
+#         (only when invoked with `render`).
+
+set -euo pipefail
+
+# shellcheck disable=SC1091
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/ui.sh"
+source "$SCRIPT_DIR/../lib/utils.sh"
+
+_agents_repo_root() {
+  # Resolve the chezmoi source dir (where CLAUDE.md/AGENTS.md live).
+  # We REQUIRE the resolved dir to contain `.chezmoidata.toml` so a
+  # user running `dot agents render` from inside some other git
+  # checkout doesn't accidentally write CLAUDE.md/AGENTS.md/.cursor/
+  # /.codex/ into that repo. Round-2 audit C-finding.
+  #
+  # On a CI runner `chezmoi source-path` may return a default path
+  # like `$HOME/.local/share/chezmoi` that doesn't exist on disk —
+  # we treat that as "not a match" and fall through to git, rather
+  # than accepting the wrong candidate.
+  local candidate=""
+  if command -v chezmoi >/dev/null 2>&1; then
+    candidate="$(chezmoi source-path 2>/dev/null || true)"
+    if [[ -n "$candidate" && ! -f "$candidate/.chezmoidata.toml" ]]; then
+      candidate=""
+    fi
+  fi
+  if [[ -z "$candidate" ]]; then
+    candidate="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || true)"
+  fi
+  if [[ -z "$candidate" ]] || [[ ! -f "$candidate/.chezmoidata.toml" ]]; then
+    return 1
+  fi
+  printf '%s\n' "$candidate"
+}
+
+_agents_canonical() {
+  printf "%s/CLAUDE.md" "$(_agents_repo_root)"
+}
+
+_agents_targets() {
+  # printed one-per-line: <harness>\t<path-relative-to-repo-root>
+  # Closes the round-2 audit gap #3 — harness parity with
+  # TonyCasey/ai-dotfiles-manager (who covers 9 surfaces; we now
+  # cover 12 to maintain a margin).
+  local root
+  root="$(_agents_repo_root)"
+  cat <<EOF
+agents-md	$root/AGENTS.md
+cursor	$root/.cursor/rules/dotfiles.mdc
+codex	$root/.codex/config.toml
+windsurf	$root/.windsurf/rules.md
+zed	$root/.zed/agent-config.toml
+roo	$root/.roo/rules.md
+cline	$root/.clinerules
+aider	$root/.aider.conf.yml
+continue	$root/.continuerc.json
+jules	$root/.jules/system.md
+gemini	$root/.gemini/GEMINI.md
+EOF
+}
+
+# Strip the leading HTML comment header (everything up to the first blank
+# line after the `-->`), the H1 title line (which differs by design
+# between CLAUDE.md / AGENTS.md), and the trailing cross-reference
+# block. Leaves the comparable content body.
+_agents_body() {
+  local file="$1"
+  awk '
+    BEGIN { in_header = 0; saw_close = 0; emit = 0 }
+    /^<!--/ && NR <= 5 { in_header = 1; next }
+    in_header && /-->/ { in_header = 0; saw_close = 1; next }
+    in_header { next }
+    saw_close && /^$/ && !emit { emit = 1; next }
+    saw_close && emit { print }
+    !saw_close { emit = 1; print }
+  ' "$file" |
+    # Drop the H1 (`# CLAUDE.md ...` or `# AGENTS.md ...`) and the
+    # trailing "Need richer context?" footer if present.
+    awk '
+      /^# (CLAUDE|AGENTS)\.md/ { next }
+      /^---$/ { trailer = 1; next }
+      trailer && /^\*\*Need richer context\?\*\*/ { next }
+      trailer && NF == 0 { next }
+      { trailer = 0; print }
+    '
+}
+
+cmd_agents() {
+  local subcommand="${1:-list}"
+  shift || true
+
+  case "$subcommand" in
+    list)
+      ui_header "Agent harness targets"
+      echo ""
+      ui_table_begin "Harness" "Target Path" "Status"
+      while IFS=$'\t' read -r harness path; do
+        if [[ -f "$path" ]]; then
+          ui_table_add "$harness" "$path" "rendered"
+        else
+          ui_table_add "$harness" "$path" "not yet rendered"
+        fi
+      done < <(_agents_targets)
+      ui_table_end
+      ;;
+    check)
+      local claude_md agents_md
+      claude_md="$(_agents_canonical)"
+      agents_md="$(_agents_repo_root)/AGENTS.md"
+      if [[ ! -f "$claude_md" ]]; then
+        ui_err "CLAUDE.md" "not found at $claude_md"
+        return 2
+      fi
+      if [[ ! -f "$agents_md" ]]; then
+        ui_warn "AGENTS.md" "missing — run 'dot agents render'"
+        return 1
+      fi
+      # Diff the bodies (header comments differ by design).
+      # `--ignore-blank-lines` so the trailing newline from the footer
+      # block doesn't false-positive as drift.
+      if diff -q --ignore-blank-lines <(_agents_body "$claude_md") <(_agents_body "$agents_md") >/dev/null 2>&1; then
+        ui_ok "AGENTS.md" "in sync with CLAUDE.md"
+        return 0
+      fi
+      ui_warn "AGENTS.md" "drifted from CLAUDE.md — run 'dot agents render'"
+      return 1
+      ;;
+    render)
+      local claude_md root
+      claude_md="$(_agents_canonical)"
+      root="$(_agents_repo_root)"
+      [[ -f "$claude_md" ]] || {
+        ui_err "CLAUDE.md" "not found at $claude_md"
+        return 2
+      }
+
+      # 1. AGENTS.md — body of CLAUDE.md + AGENTS.md cross-reference header.
+      local agents_md="$root/AGENTS.md"
+      {
+        cat <<'HEADER'
+<!--
+  AGENTS.md — Cross-harness AI agent guidelines for this repository.
+
+  This file follows the AGENTS.md standard (originated by OpenAI in
+  August 2025, stewarded since December 2025 by the Linux Foundation
+  Agentic AI Foundation). Native readers: Codex CLI, GitHub Copilot,
+  Cursor, Windsurf, Amp, Devin, and a growing list of other agents.
+
+  Canonical source: CLAUDE.md (Claude Code uses CLAUDE.md natively).
+  This file is kept in sync via `dot agents render`. Edit CLAUDE.md
+  first; do not hand-edit AGENTS.md.
+-->
+
+HEADER
+        # Replace the title line so the rendered file declares its
+        # purpose, but pass everything else through unchanged.
+        _agents_body "$claude_md" | sed '1s/^# CLAUDE\.md.*/# AGENTS.md — AI Assistant Guidelines/'
+        cat <<'FOOTER'
+
+---
+
+**Need richer context?** This file is the cross-harness summary. Claude Code reads the full canonical version from [`CLAUDE.md`](./CLAUDE.md). Both files are kept in sync via `dot agents render`.
+FOOTER
+      } >"$agents_md"
+      chmod 0644 "$agents_md" 2>/dev/null || true
+      ui_ok "AGENTS.md" "rendered → $agents_md"
+
+      # 2. Cursor rules — MDC format, points at CLAUDE.md/AGENTS.md.
+      local cursor_dir="$root/.cursor/rules"
+      mkdir -p "$cursor_dir"
+      cat >"$cursor_dir/dotfiles.mdc" <<'MDC'
+---
+description: Repo conventions for the dotfiles project (sourced from CLAUDE.md/AGENTS.md)
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+See `AGENTS.md` and `CLAUDE.md` in the repository root for the full
+project conventions, repository layout, testing, and CI policy. This
+Cursor rule file exists so Cursor's rule engine picks up the same
+context; do not duplicate content here — keep CLAUDE.md canonical.
+MDC
+      chmod 0644 "$cursor_dir/dotfiles.mdc" 2>/dev/null || true
+      ui_ok "Cursor" "rendered → $cursor_dir/dotfiles.mdc"
+
+      # 3. Codex CLI config stub — declares the AGENTS.md path.
+      local codex_dir="$root/.codex"
+      mkdir -p "$codex_dir"
+      cat >"$codex_dir/config.toml" <<'TOML'
+# Codex CLI config — points at the AGENTS.md cross-harness context.
+# Codex reads AGENTS.md natively; this file is a project-scoped pin so
+# the CLI prefers the in-repo guidance over any global default.
+project_context = "AGENTS.md"
+TOML
+      chmod 0644 "$codex_dir/config.toml" 2>/dev/null || true
+      ui_ok "Codex" "rendered → $codex_dir/config.toml"
+
+      # 4-11. Per-harness rules files. All eight emitters reuse the
+      # same body extracted from CLAUDE.md so a single edit propagates
+      # consistently. The header differs per harness so each tool sees
+      # syntax it expects (front-matter style, comment block, etc.).
+      _agents_render_markdown_with_header() {
+        local _path="$1" _harness="$2" _header="$3"
+        mkdir -p "$(dirname "$_path")"
+        {
+          printf '%s\n\n' "$_header"
+          _agents_body "$claude_md"
+          # Heredoc instead of printf — Codacy/shellcheck flags
+          # printf-with-backticks-in-single-quotes (SC2016) as
+          # ambiguous even when the backticks are literal Markdown.
+          cat <<'FOOTER'
+
+---
+
+**Canonical source:** [`CLAUDE.md`](./CLAUDE.md) — keep in sync via `dot agents render`.
+FOOTER
+        } >"$_path"
+        chmod 0644 "$_path" 2>/dev/null || true
+        ui_ok "$_harness" "rendered → $_path"
+      }
+
+      # 4. Windsurf — looks for `.windsurf/rules.md`.
+      _agents_render_markdown_with_header "$root/.windsurf/rules.md" \
+        "Windsurf" "# Windsurf project rules
+
+These rules govern Cascade and the Windsurf agent inside this repository."
+
+      # 5. Roo — looks for `.roo/rules.md`.
+      _agents_render_markdown_with_header "$root/.roo/rules.md" \
+        "Roo" "# Roo project rules"
+
+      # 6. Cline — looks for `.clinerules` (no extension).
+      _agents_render_markdown_with_header "$root/.clinerules" \
+        "Cline" "# Cline workspace rules"
+
+      # 7. Jules — looks for `.jules/system.md`.
+      _agents_render_markdown_with_header "$root/.jules/system.md" \
+        "Jules" "# Jules system prompt"
+
+      # 8. Gemini — looks for `.gemini/GEMINI.md`.
+      _agents_render_markdown_with_header "$root/.gemini/GEMINI.md" \
+        "Gemini" "# Gemini agent rules"
+
+      # 9. Zed — config pointer (TOML).
+      local zed_dir="$root/.zed"
+      mkdir -p "$zed_dir"
+      cat >"$zed_dir/agent-config.toml" <<'TOML'
+# Zed agent config — points at AGENTS.md for the cross-harness body.
+# Zed reads this file when its agent mode is enabled; the actual rule
+# body lives in AGENTS.md (which `dot agents render` keeps current).
+agent_context = "AGENTS.md"
+TOML
+      chmod 0644 "$zed_dir/agent-config.toml" 2>/dev/null || true
+      ui_ok "Zed" "rendered → $zed_dir/agent-config.toml"
+
+      # 10. Aider — YAML pointer to AGENTS.md / CLAUDE.md.
+      cat >"$root/.aider.conf.yml" <<'YML'
+# Aider config — surfaces the cross-harness context bundle.
+# Aider's `--read` flag pulls in AGENTS.md / CLAUDE.md per session.
+read:
+  - AGENTS.md
+  - CLAUDE.md
+YML
+      chmod 0644 "$root/.aider.conf.yml" 2>/dev/null || true
+      ui_ok "Aider" "rendered → $root/.aider.conf.yml"
+
+      # 11. Continue — JSON pointer used by VS Code / JetBrains plugin.
+      cat >"$root/.continuerc.json" <<'JSON'
+{
+  "_comment": "Continue config pointer — see AGENTS.md for the full body.",
+  "systemMessage": "Apply the rules in AGENTS.md (canonical source: CLAUDE.md). Run `dot agents render` if the two drift."
+}
+JSON
+      chmod 0644 "$root/.continuerc.json" 2>/dev/null || true
+      ui_ok "Continue" "rendered → $root/.continuerc.json"
+
+      ui_info "Hint" "commit AGENTS.md alongside CLAUDE.md changes (or add to your pre-commit hook)"
+      ;;
+    --help | -h | help)
+      cat <<EOF
+Usage: dot agents <subcommand>
+
+Subcommands:
+  list     Show which agent harnesses are recognised and their target paths
+  check    Verify AGENTS.md tracks CLAUDE.md (exit 0 in sync, 1 drifted)
+  render   Regenerate AGENTS.md + 10 harness-specific files from CLAUDE.md
+
+CLAUDE.md is the canonical source. AGENTS.md follows the cross-harness
+standard read by Codex, Copilot, Cursor, Windsurf, Amp, and Devin.
+
+Harnesses covered by 'render':
+  agents-md, cursor, codex, windsurf, zed, roo, cline,
+  aider, continue, jules, gemini.
+EOF
+      ;;
+    *)
+      ui_err "Unknown subcommand" "$subcommand"
+      echo "Run 'dot agents --help' for usage." >&2
+      return 1
+      ;;
+  esac
+}

package/scripts/dot/commands/ai.sh

@@ -28,9 +28,10 @@ if [[ ! -d "$PATTERN_DIR" ]]; then
 fi
 
 _show_ai_bridge_usage() {
-  echo "Usage: dot cl|copilot|gemini|kiro|autohand|vibe|qwen|zai --pattern [name] \"prompt\""
+  echo "Usage: dot cl|codex|copilot|gemini|goose|kiro|autohand|vibe|qwen|zai --pattern [name] \"prompt\""
   echo ""
   echo "Available Patterns:"
+  # shellcheck disable=SC2012
   ls -1 "$PATTERN_DIR" 2>/dev/null | sed 's/\.md$//' | sed 's/^/  - /' || echo "  (none)"
 }
 
@@ -57,18 +58,72 @@ _ai_refresh_status_cache() {
   tmp_file="$(mktemp)"
   mkdir -p "$AI_CACHE_DIR"
 
-  local entry category role name bin desc present version
+  local total=${#ai_entries[@]}
+
+  # Cold-cache refresh runs `$bin --version` for every tool — node-
+  # based ones are slow to start, so the total can hit 15-30s. Show a
+  # spinner so the user has feedback.
+  ui_spinner_start "Probing $total AI tools (cached for ${AI_STATUS_TTL}s)"
+
+  local jobs="${DOTFILES_AI_PROBE_JOBS:-$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)}"
+  local probe_dir
+  probe_dir="$(mktemp -d)"
+
+  # Probe via xargs -P. The probe logic lives INLINE in the bash -c
+  # string rather than as an exported function, because `export -f`
+  # doesn't always survive across bash invocations on every platform
+  # (notably macOS bash 3.2 needs the BASH_FUNC_*() env-var format,
+  # which subtly breaks for some shells in PATH). Inlining sidesteps
+  # the inheritance question entirely.
+  local i=0
+  local entry
+  local indexed=()
   for entry in "${ai_entries[@]}"; do
-    IFS='|' read -r category role name bin desc <<<"$entry"
-    if has_command "$bin"; then
-      present=1
-      version=$(_ai_extract_version "$bin")
+    indexed+=("$i|$entry")
+    i=$((i + 1))
+  done
+  # shellcheck disable=SC2016
+  local probe_script='
+    payload="$1"
+    out_dir="$2"
+    i="${payload%%|*}"
+    entry="${payload#*|}"
+    IFS="|" read -r category role name bin desc <<<"$entry"
+    if command -v "$bin" >/dev/null 2>&1; then
+      output=$("$bin" --version 2>/dev/null | head -1) || true
+      version=$(printf "%s" "$output" | sed "s/^[^0-9]*//" | sed "s/[[:space:]]*$//" | sed "s/\.$//")
+      printf "%s\t1\t%s\n" "$bin" "$version" >"$out_dir/$i"
     else
-      present=0
-      version=""
+      printf "%s\t0\t\n" "$bin" >"$out_dir/$i"
     fi
-    printf '%s\t%s\t%s\n' "$bin" "$present" "$version" >>"$tmp_file"
+  '
+  # NOTE: `-I{}` already implies one input line per invocation. Adding
+  # `-n1` on top triggers a BSD-xargs quirk where the input line is
+  # word-split on whitespace ("0|Agents (autonomous)|..." → multiple
+  # entries). Use only `-I{}`.
+  #
+  # ALSO: feed null-delimited records (`-0`) so apostrophes and
+  # other quote-like characters in the descriptions ("Block's coding
+  # agent") don't trigger xargs's "unterminated quote" parser.
+  printf '%s\0' "${indexed[@]}" |
+    xargs -0 -I{} -P"$jobs" \
+      bash -c "$probe_script" _ {} "$probe_dir" \
+      2>/dev/null || true
+
+  # Re-assemble in original entry order.
+  local n
+  for ((n = 0; n < i; n++)); do
+    [[ -f "$probe_dir/$n" ]] && cat "$probe_dir/$n" >>"$tmp_file"
   done
+  rm -rf "$probe_dir"
+
+  # Guard with `|| true` because ui_spinner_stop's last line evaluates
+  # to rc=1 when stdout is a TTY (the `[[ ! -t 1 ]] && printf` short-
+  # circuit). Under `set -euo pipefail` that rc would kill the script
+  # right before we get to write the cache, leaving the user with a
+  # silent broken cold-cache run. Defence in depth — the function
+  # now also has an explicit `return 0` upstream.
+  ui_spinner_stop || true
 
   mv "$tmp_file" "$AI_STATUS_CACHE_FILE"
 }
@@ -81,7 +136,9 @@ _ai_get_cached_status() {
 _ai_mise_pkg() {
   case "$1" in
     claude) echo "npm:@anthropic-ai/claude-code" ;;
+    codex) echo "npm:@openai/codex" ;;
     copilot) echo "npm:@github/copilot" ;;
+    goose) echo "pipx:goose-ai" ;;
     aider) echo "pipx:aider-chat" ;;
     opencode) echo "npm:opencode-ai" ;;
     sgpt) echo "pipx:shell-gpt" ;;
@@ -102,7 +159,9 @@ cmd_ai_status() {
   # category|role|name|binary|description
   local -a ai_clis=(
     "Agents (autonomous)|agent|Claude Code|claude|Anthropic CLI agent"
+    "Agents (autonomous)|agent|Codex CLI|codex|OpenAI Codex agent"
     "Agents (autonomous)|agent|Copilot CLI|copilot|GitHub Copilot CLI"
+    "Agents (autonomous)|agent|Goose|goose|Block's coding agent"
     "Coding (interactive)|coding|Aider|aider|AI pair programmer"
     "Coding (interactive)|coding|OpenCode|opencode|Terminal coding assistant"
     "Coding (interactive)|coding|Autohand Code|autohand|Autohand coding agent"
@@ -350,12 +409,18 @@ ${prompt}"
     cl | claude)
       printf "%s" "$full_prompt" | claude
       ;;
+    codex)
+      printf "%s" "$full_prompt" | codex
+      ;;
     copilot)
       copilot -sp "$full_prompt"
       ;;
     gemini)
       printf "%s" "$full_prompt" | gemini chat
       ;;
+    goose)
+      printf "%s" "$full_prompt" | goose session start
+      ;;
     kiro | kiro-cli)
       printf "%s" "$full_prompt" | kiro-cli chat
       ;;
@@ -404,7 +469,7 @@ case "${1:-}" in
     shift
     cmd_ai_query "$@"
     ;;
-  cl | claude | copilot | gemini | kiro | sgpt | ollama | opencode | aider | autohand | vibe | qwen | zai)
+  cl | claude | codex | copilot | gemini | goose | kiro | sgpt | ollama | opencode | aider | autohand | vibe | qwen | zai)
     tool="$1"
     shift
     run_ai_with_context "$tool" "$@"

package/scripts/dot/commands/aliases.sh

@@ -40,11 +40,11 @@ cmd_aliases() {
     list)
       ui_header "Aliases"
       echo ""
-      printf "  %-18s %-42s %s\n" "Name" "Value" "Source"
-      echo "  $(printf '%.18s' '------------------') $(printf '%.42s' '------------------------------------------') -------------------------"
-      emit_alias_manifest | sort -t $'\t' -k1,1 | while IFS=$'\t' read -r name value file line; do
-        printf "  %-18s %-42s %s:%s\n" "$name" "${value:0:42}" "${file##*/}" "$line"
-      done
+      ui_table_begin "Name" "Value" "Source"
+      while IFS=$'\t' read -r name value file line; do
+        ui_table_add "$name" "${value:0:60}" "${file##*/}:$line"
+      done < <(emit_alias_manifest | sort -t $'\t' -k1,1)
+      ui_table_end
       ;;
     search)
       local query="${1:-}"
@@ -60,9 +60,11 @@ cmd_aliases() {
         ui_warn "No matches" "$query"
         return 1
       fi
-      printf "%s\n" "$results" | while IFS=$'\t' read -r name value file line; do
-        printf "  %-18s %-42s %s:%s\n" "$name" "${value:0:42}" "$file" "$line"
-      done
+      ui_table_begin "Name" "Value" "Source"
+      while IFS=$'\t' read -r name value file line; do
+        ui_table_add "$name" "${value:0:60}" "$file:$line"
+      done <<<"$results"
+      ui_table_end
       ;;
     why)
       local alias_name="${1:-}"

package/scripts/dot/commands/core.sh

@@ -77,13 +77,19 @@ cmd_diff() {
 }
 
 cmd_status() {
-  local out
-  out="$(chezmoi status "$@" || true)"
+  local out rc=0
+  # Capture chezmoi's stderr too so an actual tool failure surfaces
+  # to the user instead of being indistinguishable from a clean tree.
+  out="$(chezmoi status "$@" 2>&1)" || rc=$?
+  ui_header "Dotfiles Status"
+  if [[ "$rc" -ne 0 ]]; then
+    ui_err "chezmoi" "exited $rc"
+    [[ -n "$out" ]] && printf "%s\n" "$out"
+    return "$rc"
+  fi
   if [[ -z "$out" ]]; then
-    ui_header "Dotfiles Status"
     ui_ok "Clean" "no local drift detected"
   else
-    ui_header "Dotfiles Status"
     printf "%s\n" "$out"
   fi
 }