Brewdoc:Auto Sync

MIT License

Copyright (c) 2025-2026 Maxim Kochetkov (kochetkov-ma)
https://github.com/kochetkov-ma/claude-brewcode

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.

#!/bin/sh
# Detects auto-sync mode from arguments
# Usage: detect-mode.sh "$@"
# Output: MODE|ARG|FLAGS (e.g., "STATUS||" or "PROJECT||optimize")
#
# Modes:
#   STATUS||[flags]          - "status"
#   INIT|<path>|[flags]      - "init <path> [prompt]"
#   GLOBAL||[flags]          - "global"
#   PROJECT||[flags]         - empty args
#   FILE|<path>|[flags]      - single file path (*.md)
#   FOLDER|<path>|[flags]    - folder path
#
# Flags:
#   -o, --optimize           - Enable optimization (adds "optimize" to FLAGS)

set -e

# --- Phase 1: Extract flags from arguments ---

FLAGS=""
CLEAN_ARGS=""

for arg in "$@"; do
  case "$arg" in
    -o|--optimize)
      FLAGS="optimize"
      ;;
    *)
      if [ -z "$CLEAN_ARGS" ]; then
        CLEAN_ARGS="$arg"
      else
        CLEAN_ARGS="$CLEAN_ARGS $arg"
      fi
      ;;
  esac
done

# --- Phase 2: Detect mode from cleaned arguments ---

# Normalize: lowercase, trim whitespace
ARGS_LOWER=$(echo "$CLEAN_ARGS" | tr '[:upper:]' '[:lower:]' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')

# Empty args = PROJECT mode
if [ -z "$ARGS_LOWER" ]; then
  echo "PROJECT||$FLAGS"
  exit 0
fi

# Check for "status"
if [ "$ARGS_LOWER" = "status" ]; then
  echo "STATUS||$FLAGS"
  exit 0
fi

# Check for bare "init" without arguments
if [ "$ARGS_LOWER" = "init" ]; then
  echo "ERROR|init requires a path argument|$FLAGS" >&2
  exit 1
fi

# Check for "init <path>"
if echo "$ARGS_LOWER" | grep -qE '^init[[:space:]]+'; then
  INIT_ARGS=$(echo "$CLEAN_ARGS" | sed 's/^[^[:space:]][^[:space:]]*[[:space:]][[:space:]]*//')
  echo "INIT|$INIT_ARGS|$FLAGS"
  exit 0
fi

# Check for "global"
if [ "$ARGS_LOWER" = "global" ]; then
  echo "GLOBAL||$FLAGS"
  exit 0
fi

# Check if it's a file path (ends with .md)
if echo "$CLEAN_ARGS" | grep -qE '\.md$'; then
  echo "FILE|$CLEAN_ARGS|$FLAGS"
  exit 0
fi

# Check if it's a folder path
if [ -d "$CLEAN_ARGS" ]; then
  echo "FOLDER|$CLEAN_ARGS|$FLAGS"
  exit 0
fi

# Check if path looks like a folder (contains / but no .md)
if echo "$CLEAN_ARGS" | grep -qE '^[./~]' && ! echo "$CLEAN_ARGS" | grep -qE '\.md$'; then
  echo "FOLDER|$CLEAN_ARGS|$FLAGS"
  exit 0
fi

# Default: treat as PROJECT mode with the args as context
echo "WARN: unrecognized argument '$CLEAN_ARGS', defaulting to PROJECT mode" >&2
echo "PROJECT|$CLEAN_ARGS|$FLAGS"

#!/bin/sh
# Discovers files with auto-sync enabled
# Usage: discover.sh [search_path] [output_format]
#   search_path   - Directory to search (default: .)
#   output_format - paths (default) | json | typed

set -e

SEARCH_PATH="${1:-.}"
OUTPUT_FORMAT="${2:-paths}"
MAX_FILES="${MAX_FILES:-50}"

# Explicit path detection: if path contains rules/, agents/, skills/ - user explicitly requested it
is_explicit_managed_path() {
  case "$SEARCH_PATH" in
    */rules|*/rules/*|*/agents|*/agents/*|*/skills|*/skills/*) return 0 ;;
    *) return 1 ;;
  esac
}

# Build exclusion args for managed directories (only when auto-scanning)
build_exclusions() {
  if is_explicit_managed_path; then
    echo ""  # No exclusions for explicit paths
  else
    # Exclude rules/, agents/, skills/ from auto-scan (only by explicit request)
    echo "-not -path */rules/* -not -path */agents/* -not -path */skills/*"
  fi
}

# Find files with auto-sync: enabled (YAML frontmatter only)
find_autosync_files() {
  _exclusions=$(build_exclusions)
  # shellcheck disable=SC2086
  _all=$(find "$SEARCH_PATH" -name "*.md" \
    -not -path '*/.git/*' \
    -not -path '*/node_modules/*' \
    -not -path '*/.claude/tasks/*' \
    $_exclusions \
    -exec grep -lE '^auto-sync:[[:space:]]*enabled' {} + \
    2>/dev/null | sort -u || true)
  _count=$(echo "$_all" | grep -c . || true)
  if [ "$_count" -gt "$MAX_FILES" ]; then
    echo "WARN: found $_count files, capped to $MAX_FILES (set MAX_FILES to override)" >&2
    echo "$_all" | head -n "$MAX_FILES"
  else
    echo "$_all"
  fi
}

# Detect type from file path
detect_type() {
  _path="$1"
  _base=$(basename "$_path")

  if [ "$_base" = "CLAUDE.md" ]; then
    echo "config"
  elif echo "$_path" | grep -qE '(^|/)skills/'; then
    echo "skill"
  elif echo "$_path" | grep -qE '(^|/)agents/'; then
    echo "agent"
  elif echo "$_path" | grep -qE '(^|/)rules/'; then
    echo "rule"
  else
    echo "doc"
  fi
}

# Output as paths (one per line)
output_paths() {
  find_autosync_files
}

# Output as JSON array
output_json() {
  FILES=$(find_autosync_files)
  if [ -z "$FILES" ]; then
    echo "[]"
    return
  fi
  echo "["
  echo "$FILES" | sed 's/.*/  "&"/' | sed '$!s/$/,/'
  echo "]"
}

# Output as typed (TYPE|PATH per line)
output_typed() {
  FILES=$(find_autosync_files)
  if [ -z "$FILES" ]; then
    return
  fi
  echo "$FILES" | while IFS= read -r file; do
    _type=$(detect_type "$file")
    echo "${_type}|${file}"
  done
}

# Main
case "$OUTPUT_FORMAT" in
  paths)
    output_paths
    ;;
  json)
    output_json
    ;;
  typed)
    output_typed
    ;;
  *)
    echo "Usage: discover.sh [search_path] [output_format]" >&2
    echo "  search_path   - Directory to search (default: .)" >&2
    echo "  output_format - paths (default) | json | typed" >&2
    exit 1
    ;;
esac

#!/bin/sh
# INDEX operations for auto-sync
# Usage: index-ops.sh <command> [args...]
#
# Format: {"p":"path","t":"type","u":"YYYY-MM-DD","pr":"default"}
#   p  = relative path (identity key)
#   t  = type (skill/agent/rule/config/doc)
#   u  = last sync date (YYYY-MM-DD)
#   pr = protocol ("default" or "override")
#
# Commands:
#   read <index_path>                         - Read and validate INDEX
#   add <index_path> <json_entry>             - Add entry from JSON
#   add <index_path> <path> <type> [protocol] - Add entry from positional args (date=today)
#   update <index_path> <path> <field> <val>  - Update entry field by path
#   remove <index_path> <path>                - Remove entry by path
#   stale <index_path> [days]                 - Find stale entries (default: 7)

set -e

CMD="${1:-help}"
shift 2>/dev/null || true

require_jq() {
  if ! command -v jq >/dev/null 2>&1; then
    echo "X jq is required but not installed" >&2
    echo "  Install: brew install jq" >&2
    exit 1
  fi
}

threshold_date() {
  days="$1"
  if date -v-1d +%Y-%m-%d >/dev/null 2>&1; then
    date -v-"${days}"d +%Y-%m-%d
  else
    date -d "-${days} days" +%Y-%m-%d
  fi
}

cmd_read() {
  index_path="${1:-}"
  if [ -z "$index_path" ]; then
    echo "X Missing index_path" >&2
    echo "Usage: index-ops.sh read <index_path>" >&2
    exit 1
  fi
  if [ ! -f "$index_path" ]; then
    echo "X INDEX not found: $index_path" >&2
    exit 1
  fi
  require_jq
  grep -v "^#" "$index_path" | while IFS= read -r line; do
    if [ -n "$line" ]; then
      echo "$line" | jq -c '.' 2>/dev/null || echo "X Invalid JSON: $line" >&2
    fi
  done
}

cmd_add() {
  index_path="${1:-}"
  arg2="${2:-}"
  arg3="${3:-}"
  arg4="${4:-default}"
  if [ -z "$index_path" ] || [ -z "$arg2" ]; then
    echo "X Missing arguments" >&2
    echo "Usage: index-ops.sh add <index_path> <json_entry>" >&2
    echo "       index-ops.sh add <index_path> <path> <type> [protocol]" >&2
    exit 1
  fi
  require_jq
  # Detect format: JSON (starts with {) or positional args
  case "$arg2" in
    \{*)
      # JSON format
      entry="$arg2"
      if ! echo "$entry" | jq -e '.' >/dev/null 2>&1; then
        echo "X Invalid JSON entry" >&2
        exit 1
      fi
      ;;
    *)
      # Positional format: <path> <type> [protocol]
      if [ -z "$arg3" ]; then
        echo "X Missing type argument" >&2
        echo "Usage: index-ops.sh add <index_path> <path> <type> [protocol]" >&2
        exit 1
      fi
      today=$(date +%Y-%m-%d)
      entry=$(jq -nc --arg p "$arg2" --arg t "$arg3" --arg u "$today" --arg pr "$arg4" \
        '{p:$p, t:$t, u:$u, pr:$pr}')
      ;;
  esac
  path=$(echo "$entry" | jq -r '.p')
  if [ -f "$index_path" ] && grep -v "^#" "$index_path" 2>/dev/null | jq -r '.p' 2>/dev/null | grep -qxF "$path"; then
    echo "X Entry already exists: $path" >&2
    echo "  Use 'update' to modify existing entries" >&2
    exit 1
  fi
  echo "$entry" >> "$index_path"
  echo "V Added: $path"
}

cmd_update() {
  # NOTE: read-modify-write is NOT atomic. Callers must invoke sequentially (SKILL.md guarantees this).
  index_path="${1:-}"
  path="${2:-}"
  field="${3:-}"
  value="${4:-}"
  if [ -z "$index_path" ] || [ -z "$path" ] || [ -z "$field" ] || [ -z "$value" ]; then
    echo "X Missing arguments" >&2
    echo "Usage: index-ops.sh update <index_path> <path> <field> <value>" >&2
    exit 1
  fi
  case "$field" in
    p|t|u|pr) ;;
    *) echo "X Invalid field: $field (allowed: p, t, u, pr)" >&2; exit 1 ;;
  esac
  require_jq
  tmp_file=$(mktemp)
  trap 'rm -f "$tmp_file"' EXIT
  found=false
  while IFS= read -r line; do
    case "$line" in
      \#*) echo "$line" ;;
      "")  ;; # Empty lines dropped intentionally — JSONL has no empty-line semantics
      *)
        entry_path=$(echo "$line" | jq -r '.p' 2>/dev/null)
        if [ "$entry_path" = "$path" ]; then
          echo "$line" | jq -c --arg v "$value" ".${field} = \$v"
          found=true
        else
          echo "$line"
        fi
        ;;
    esac
  done < "$index_path" > "$tmp_file"
  if [ "$found" = true ]; then
    mv "$tmp_file" "$index_path"
    echo "V Updated: $path.$field = $value"
  else
    rm "$tmp_file"
    echo "X Entry not found: $path" >&2
    exit 1
  fi
}

cmd_remove() {
  index_path="${1:-}"
  path="${2:-}"
  if [ -z "$index_path" ] || [ -z "$path" ]; then
    echo "X Missing arguments" >&2
    echo "Usage: index-ops.sh remove <index_path> <path>" >&2
    exit 1
  fi
  require_jq
  tmp_file=$(mktemp)
  trap 'rm -f "$tmp_file"' EXIT
  found=false
  while IFS= read -r line; do
    case "$line" in
      \#*) echo "$line" ;;
      "")  ;; # Empty lines dropped intentionally — JSONL has no empty-line semantics
      *)
        entry_path=$(echo "$line" | jq -r '.p' 2>/dev/null)
        if [ "$entry_path" = "$path" ]; then
          found=true
        else
          echo "$line"
        fi
        ;;
    esac
  done < "$index_path" > "$tmp_file"
  if [ "$found" = true ]; then
    mv "$tmp_file" "$index_path"
    echo "V Removed: $path"
  else
    rm "$tmp_file"
    echo "X Entry not found: $path" >&2
    exit 1
  fi
}

cmd_stale() {
  index_path="${1:-}"
  days="${2:-7}"
  if [ -z "$index_path" ]; then
    echo "X Missing index_path" >&2
    echo "Usage: index-ops.sh stale <index_path> [days]" >&2
    exit 1
  fi
  case "$days" in
    ''|*[!0-9]*) echo "X days must be a positive integer, got: $days" >&2; exit 1 ;;
    0) echo "X days must be > 0, got: 0" >&2; exit 1 ;;
  esac
  if [ ! -f "$index_path" ]; then
    echo "X INDEX not found: $index_path" >&2
    exit 1
  fi
  require_jq
  cutoff=$(threshold_date "$days")
  grep -v "^#" "$index_path" 2>/dev/null | while IFS= read -r line; do
    if [ -n "$line" ]; then
      entry_date=$(echo "$line" | jq -r '.u // empty' 2>/dev/null)
      if [ -z "$entry_date" ]; then
        echo "$line"
      elif expr "$entry_date" \< "$cutoff" > /dev/null 2>&1; then
        echo "$line"
      fi
    fi
  done
}

cmd_help() {
  echo "INDEX operations for auto-sync"
  echo ""
  echo "Usage: index-ops.sh <command> [args...]"
  echo ""
  echo "Format: {\"p\":\"path\",\"t\":\"type\",\"u\":\"YYYY-MM-DD\",\"pr\":\"default\"}"
  echo ""
  echo "Commands:"
  echo "  read <index_path>                         - Read and validate INDEX"
  echo "  add <index_path> <json_entry>             - Add entry from JSON"
  echo "  add <index_path> <path> <type> [protocol] - Add entry (date=today, protocol=default)"
  echo "  update <index_path> <path> <field> <val>  - Update entry field by path"
  echo "  remove <index_path> <path>                - Remove entry by path"
  echo "  stale <index_path> [days]                 - Find stale entries (default: 7)"
  echo ""
  echo "Examples:"
  echo "  index-ops.sh add idx.jsonl '{\"p\":\"file.md\",\"t\":\"doc\",\"u\":\"2026-02-11\",\"pr\":\"default\"}'"
  echo "  index-ops.sh add idx.jsonl file.md doc"
  echo "  index-ops.sh add idx.jsonl file.md skill override"
}

case "$CMD" in
  read)   cmd_read "$@" ;;
  add)    cmd_add "$@" ;;
  update) cmd_update "$@" ;;
  remove) cmd_remove "$@" ;;
  stale)  cmd_stale "$@" ;;
  help|--help|-h)
    cmd_help
    ;;
  *)
    echo "X Unknown command: $CMD" >&2
    cmd_help >&2
    exit 1
    ;;
esac