u-foo 1.0.0

package/scripts/context-decisions.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# context-decisions.sh
+# Show latest decisions from project context
+
+usage() {
+  cat <<'EOF'
+context-decisions.sh
+
+Show recent decisions from a decision log directory.
+
+Default behavior:
+  - Use .ufoo/context/DECISIONS/ (project-local decision log)
+
+Usage:
+  bash scripts/context-decisions.sh [options]
+
+Options:
+  -n <num>    Show last N decisions (default: 1)
+  -l          List all decisions (titles only)
+  -a          Show all decisions (full content)
+  -d <dir>    Use a specific decisions directory
+  -s <status> Filter by status: open, resolved, wontfix (default: open)
+              Use -s all to show all statuses
+  --help      Show this help
+
+Frontmatter format:
+  ---
+  status: open | resolved | wontfix
+  resolved_by: <agent>      # optional, who resolved it
+  resolved_at: <date>       # optional, when resolved
+  ---
+EOF
+}
+
+DECISIONS_DIR="${AI_CONTEXT_DECISIONS_DIR:-}"
+NUM=1
+LIST_ONLY=0
+SHOW_ALL=0
+STATUS_FILTER="open"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -n)
+      NUM="$2"
+      shift 2
+      ;;
+    -l)
+      LIST_ONLY=1
+      shift
+      ;;
+    -a)
+      SHOW_ALL=1
+      shift
+      ;;
+    -d|--dir)
+      DECISIONS_DIR="$2"
+      shift 2
+      ;;
+    -s)
+      STATUS_FILTER="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Default decisions directory
+if [[ -z "${DECISIONS_DIR}" ]]; then
+  DECISIONS_DIR=".ufoo/context/DECISIONS"
+fi
+
+# Extract status from frontmatter (defaults to "open" if no frontmatter)
+get_status() {
+  local file="$1"
+  local status
+  # Check if file starts with ---
+  if head -1 "$file" | grep -q '^---$'; then
+    status=$(awk '/^---$/{if(++c==2)exit} c==1 && /^status:/{print $2}' "$file")
+  fi
+  echo "${status:-open}"
+}
+
+# Check if file matches status filter
+matches_status() {
+  local file="$1"
+  if [[ "$STATUS_FILTER" == "all" ]]; then
+    return 0
+  fi
+  local status
+  status=$(get_status "$file")
+  [[ "$status" == "$STATUS_FILTER" ]]
+}
+
+if [[ ! -d "$DECISIONS_DIR" ]]; then
+  echo "No decisions directory found at $DECISIONS_DIR" >&2
+  exit 0
+fi
+
+# Get sorted decision files (newest first by filename)
+FILES=()
+while IFS= read -r f; do
+  FILES+=("$f")
+done < <(ls -1 "$DECISIONS_DIR"/*.md 2>/dev/null | sort -r)
+
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  echo "No decisions found."
+  exit 0
+fi
+
+if [[ $LIST_ONLY -eq 1 ]]; then
+  count=0
+  output=""
+  for f in "${FILES[@]}"; do
+    if matches_status "$f"; then
+      status=$(get_status "$f")
+      # Get title (skip frontmatter if present)
+      if head -1 "$f" | grep -q '^---$'; then
+        title=$(awk '/^---$/{if(++c==2){getline; print; exit}}' "$f" | sed 's/^# //')
+      else
+        title=$(head -1 "$f" | sed 's/^# //')
+      fi
+      output+="  [$status] $(basename "$f"): $title"$'\n'
+      ((count++))
+    fi
+  done
+  echo "=== Decisions (${count} ${STATUS_FILTER}, ${#FILES[@]} total) ==="
+  printf "%s" "$output"
+  exit 0
+fi
+
+# Filter files by status
+FILTERED_FILES=()
+for f in "${FILES[@]}"; do
+  if matches_status "$f"; then
+    FILTERED_FILES+=("$f")
+  fi
+done
+
+if [[ ${#FILTERED_FILES[@]} -eq 0 ]]; then
+  echo "No decisions with status '$STATUS_FILTER' found."
+  exit 0
+fi
+
+if [[ $SHOW_ALL -eq 1 ]]; then
+  NUM=${#FILTERED_FILES[@]}
+fi
+
+echo "=== Latest Decision(s) [${STATUS_FILTER}] ==="
+echo ""
+
+for ((i=0; i<NUM && i<${#FILTERED_FILES[@]}; i++)); do
+  f="${FILTERED_FILES[$i]}"
+  status=$(get_status "$f")
+  echo "--- $(basename "$f") [$status] ---"
+  cat "$f"
+  echo ""
+done

package/scripts/context-doctor.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+context-doctor.sh
+
+Quick diagnostics for context installations.
+
+Usage:
+  bash scripts/context-doctor.sh
+  bash scripts/context-doctor.sh --project <path-to-project-context>
+
+What it checks:
+  - Runs context-lint (protocol or project)
+  - Verifies decision listing works
+  - Warns if ~/.ufoo/modules/context is missing
+EOF
+}
+
+MODE="protocol"
+PROJECT_PATH=""
+REPO_ROOT="$(pwd)"
+CONTEXT_MODULE_PATH="$REPO_ROOT/modules/context"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --project)
+      MODE="project"
+      PROJECT_PATH="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+echo "=== context doctor ==="
+echo "Reminder: If you provide evaluation/recommendation/plan, write a decision before replying."
+
+if [[ "$MODE" == "project" ]]; then
+  if [[ -z "$PROJECT_PATH" ]]; then
+    echo "FAIL: --project requires a path" >&2
+    exit 1
+  fi
+  echo "Mode: project"
+  echo "Project: $PROJECT_PATH"
+  bash scripts/context-lint.sh --project "$PROJECT_PATH"
+  bash scripts/context-decisions.sh -n 1 -d "$PROJECT_PATH/DECISIONS" >/dev/null
+else
+  echo "Mode: protocol"
+  # In the ufoo monorepo, the protocol module lives under modules/context.
+  if [[ -d "$CONTEXT_MODULE_PATH" && -f "$CONTEXT_MODULE_PATH/SYSTEM.md" ]]; then
+    bash "$CONTEXT_MODULE_PATH/scripts/context-lint.sh"
+  else
+    bash scripts/context-lint.sh
+  fi
+  bash scripts/context-decisions.sh -n 1 >/dev/null 2>&1 || true
+fi
+
+if [[ ! -d "${HOME}/.ufoo/modules/context" ]]; then
+  echo "WARN: ${HOME}/.ufoo/modules/context not found (install via ufoo for best UX)"
+fi
+
+echo "Status: OK"

package/scripts/context-lint.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MODULE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+usage() {
+  cat <<'EOF'
+context-lint.sh
+
+Validate context protocol/project context structure.
+
+Usage:
+  bash scripts/context-lint.sh
+  bash scripts/context-lint.sh --project <path-to-project-context>
+
+Exit codes:
+  0  OK
+  1  Validation failed
+EOF
+}
+
+fail() {
+  printf 'FAIL: %s\n' "$1" >&2
+  FAILED=1
+}
+
+check_file() {
+  local path="$1"
+  if [[ ! -f "$path" ]]; then
+    fail "Missing file: $path"
+  fi
+}
+
+check_dir() {
+  local path="$1"
+  if [[ ! -d "$path" ]]; then
+    fail "Missing directory: $path"
+  fi
+}
+
+check_any_glob() {
+  local pattern="$1"
+  shopt -s nullglob
+  local matches=($pattern)
+  shopt -u nullglob
+  if (( ${#matches[@]} == 0 )); then
+    fail "Missing: $pattern"
+  fi
+}
+
+lint_protocol_repo() {
+  check_file "$MODULE_ROOT/README.md"
+  check_file "$MODULE_ROOT/SYSTEM.md"
+  check_file "$MODULE_ROOT/RULES.md"
+  check_file "$MODULE_ROOT/CONSTRAINTS.md"
+  check_file "$MODULE_ROOT/ASSUMPTIONS.md"
+  check_file "$MODULE_ROOT/TERMINOLOGY.md"
+  check_file "$MODULE_ROOT/DECISION-PROTOCOL.md"
+  check_file "$MODULE_ROOT/CONTEXT-STRUCTURE.md"
+  check_file "$MODULE_ROOT/HANDOFF.md"
+  check_file "$MODULE_ROOT/.gitignore"
+
+  # This repo is a distributable protocol module. It should not ship a project-local .ufoo/context/.
+  if ! grep -qE '^[[:space:]]*\.ufoo/context/([[:space:]]*(#.*)?)?$' "$MODULE_ROOT/.gitignore"; then
+    fail ".gitignore must ignore .ufoo/context/ (project-local truth) for the protocol repo"
+  fi
+
+  # UI/ICONS are resources and must live outside this repo (see decisions); do not allow drift.
+  if [[ -d "$MODULE_ROOT/UI" || -d "$MODULE_ROOT/ICONS" ]]; then
+    fail "UI/ and ICONS/ must not exist in this repo; they belong in resources"
+  fi
+}
+
+lint_project_context() {
+  local root="$1"
+  check_dir "$root"
+  check_file "$root/README.md"
+  check_file "$root/SYSTEM.md"
+  check_file "$root/CONSTRAINTS.md"
+  check_file "$root/ASSUMPTIONS.md"
+  check_file "$root/TERMINOLOGY.md"
+  check_dir "$root/DECISIONS"
+}
+
+main() {
+  FAILED=0
+
+  if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+    usage
+    exit 0
+  fi
+
+  if [[ "${1:-}" == "--project" ]]; then
+    if [[ $# -ne 2 ]]; then
+      usage >&2
+      exit 1
+    fi
+    lint_project_context "$2"
+  else
+    lint_protocol_repo
+  fi
+
+  if [[ "$FAILED" -ne 0 ]]; then
+    exit 1
+  fi
+
+  echo "OK"
+}
+
+main "$@"

package/scripts/doctor.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+context_mod="$repo_root/modules/context"
+
+if [[ ! -d "$context_mod" ]]; then
+  echo "FAIL: missing $context_mod" >&2
+  exit 1
+fi
+
+bash "$context_mod/scripts/context-lint.sh" >/dev/null
+
+echo "=== ufoo doctor ==="
+echo "Monorepo: $repo_root"
+echo "Modules:"
+echo "- context: $context_mod"
+if [[ -d "$repo_root/modules/resources" ]]; then
+  echo "- resources: $repo_root/modules/resources"
+fi
+
+echo "Status: OK"

package/scripts/init.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+context_mod="$repo_root/modules/context"
+bus_mod="$repo_root/modules/bus"
+resources_mod="$repo_root/modules/resources"
+agents_template="$repo_root/modules/AGENTS.template.md"
+
+usage() {
+  cat <<'USAGE'
+ufoo init
+
+Usage:
+  ufoo init [--modules context[,bus,resources]] [--project <dir>]
+
+Available modules:
+  context   - Shared context protocol (.ufoo/context/)
+  bus       - Agent event bus (.ufoo/bus/)
+  resources - UI/Icons resources
+
+Defaults:
+  --modules context
+  --project  <current directory>
+
+Examples:
+  ufoo init                           # Initialize context only
+  ufoo init --modules context,bus     # Initialize context + bus
+  ufoo init --modules context,bus,resources  # All modules
+USAGE
+}
+
+modules="context"
+project="$(pwd)"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --modules)
+      modules="$2"
+      shift 2
+      ;;
+    --project)
+      project="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Parse modules list
+IFS=',' read -ra MODULE_LIST <<< "$modules"
+
+echo "=== ufoo init ==="
+echo "Project directory: $project"
+echo "Modules: ${MODULE_LIST[*]}"
+echo ""
+
+agents_file="$project/AGENTS.md"
+claude_file="$project/CLAUDE.md"
+
+# Ensure AGENTS.md exists
+if [[ ! -f "$agents_file" ]]; then
+  printf '# Project Instructions\n\n`CLAUDE.md` points to this file. Please keep project instructions here (prefer edits in `AGENTS.md`).\n\n' >"$agents_file"
+fi
+
+# CLAUDE.md points to AGENTS.md
+printf 'AGENTS.md\n' >"$claude_file"
+
+# ============================================================================
+# Core: Create .ufoo directory and docs symlink
+# ============================================================================
+
+init_core() {
+  echo "[core] Initializing .ufoo core..."
+
+  mkdir -p "$project/.ufoo"
+
+  # Create docs symlink to ufoo installation docs
+  local docs_link="$project/.ufoo/docs"
+  local docs_target="$repo_root/docs"
+
+  if [[ -d "$docs_target" ]]; then
+    rm -f "$docs_link"
+    ln -sf "$docs_target" "$docs_link"
+    echo "[core] Created docs symlink: .ufoo/docs -> $docs_target"
+  fi
+
+  echo "[core] Done"
+}
+
+# ============================================================================
+# Inject ufoo template into AGENTS.md (always update)
+# ============================================================================
+
+inject_agents_template() {
+  echo "[template] Injecting ufoo template into AGENTS.md..."
+
+  if [[ ! -f "$agents_template" ]]; then
+    echo "[template] Warning: template file not found: $agents_template"
+    return
+  fi
+
+  local temp_file
+  temp_file=$(mktemp)
+
+  # Remove old ufoo block if exists (between <!-- ufoo --> and <!-- /ufoo -->)
+  if grep -q "<!-- ufoo -->" "$agents_file" 2>/dev/null; then
+    # Remove old block
+    sed '/<!-- ufoo -->/,/<!-- \/ufoo -->/d' "$agents_file" > "$temp_file"
+    mv "$temp_file" "$agents_file"
+    echo "[template] Removed old ufoo template block"
+  fi
+
+  # Also remove legacy blocks if they exist
+  for legacy in "<!-- ufoo-context -->" "<!-- ufoo-bus -->" "<!-- context -->" "<!-- bus -->"; do
+    local end_tag="${legacy/<!-- /<!-- \/}"
+    if grep -q "$legacy" "$agents_file" 2>/dev/null; then
+      sed "/$legacy/,/$end_tag/d" "$agents_file" > "$temp_file"
+      mv "$temp_file" "$agents_file"
+      echo "[template] Removed old $legacy block"
+    fi
+  done
+
+  # Append new template
+  echo "" >> "$agents_file"
+  cat "$agents_template" >> "$agents_file"
+
+  echo "[template] Template injected"
+}
+
+# ============================================================================
+# Module: context
+# ============================================================================
+
+init_context() {
+  echo "[context] Initializing .ufoo/context..."
+
+  if [[ ! -d "$context_mod" ]]; then
+    echo "FAIL: missing context module at $context_mod" >&2
+    exit 1
+  fi
+
+  ufoo_context="$project/.ufoo/context"
+  mkdir -p "$ufoo_context/DECISIONS"
+
+  # Create symlinks to templates (not copies)
+  local templates_dir="$context_mod/TEMPLATES"
+  if [[ -d "$templates_dir" ]]; then
+    for tpl in "$templates_dir"/*.md; do
+      if [[ -f "$tpl" ]]; then
+        local basename=$(basename "$tpl")
+        local target="$ufoo_context/$basename"
+        # Only create if not exists (preserve user modifications)
+        if [[ ! -e "$target" ]]; then
+          ln -sf "$tpl" "$target"
+        fi
+      fi
+    done
+  fi
+
+  echo "[context] Done: $ufoo_context"
+}
+
+# ============================================================================
+# Module: bus
+# ============================================================================
+
+init_bus() {
+  echo "[bus] Initializing .ufoo/bus..."
+
+  if [[ ! -d "$bus_mod" ]]; then
+    echo "FAIL: missing bus module at $bus_mod" >&2
+    exit 1
+  fi
+
+  ufoo_bus="$project/.ufoo/bus"
+  mkdir -p "$ufoo_bus"/{events,offsets,queues,logs,pids}
+
+  # Create bus.json if not exists
+  if [[ ! -f "$ufoo_bus/bus.json" ]]; then
+    local project_name
+    project_name=$(basename "$project")
+    cat > "$ufoo_bus/bus.json" << EOF
+{
+  "bus_id": "${project_name}-bus",
+  "created_at": "$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")",
+  "subscribers": {},
+  "agent_types": {},
+  "config": {
+    "poll_interval_ms": 3000,
+    "heartbeat_timeout_ms": 30000
+  }
+}
+EOF
+  fi
+
+  echo "[bus] Done: $ufoo_bus"
+}
+
+# ============================================================================
+# Module: resources
+# ============================================================================
+
+init_resources() {
+  echo "[resources] Initializing resources..."
+
+  if [[ ! -d "$resources_mod" ]]; then
+    echo "FAIL: missing resources module at $resources_mod" >&2
+    exit 1
+  fi
+
+  echo "[resources] Done (resources module needs no initialization, directly reference $resources_mod)"
+}
+
+# ============================================================================
+# Execute
+# ============================================================================
+
+# Always init core first
+init_core
+
+# Execute selected modules
+for mod in "${MODULE_LIST[@]}"; do
+  case "$mod" in
+    context)   init_context ;;
+    bus)       init_bus ;;
+    resources) init_resources ;;
+    *)
+      echo "Unknown module: $mod" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Always inject/update AGENTS.md template
+inject_agents_template
+
+echo ""
+echo "=== Initialization complete ==="