@erclx/aitk 0.8.0

package/scripts/core/verify.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/worktree.sh"
+
+NESTED="${VERIFY_NESTED:-false}"
+WRITE="${VERIFY_WRITE:-true}"
+SCOPED=true
+CHANGED_FILES=""
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
+}
+
+print_usage() {
+  echo "Usage: bun run check [--all]"
+  echo "  --all   Run every stage instead of scoping shell, types, and tests to changed files"
+  echo "  --help  Print this message"
+}
+
+parse_args() {
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+    --all) SCOPED=false ;;
+    -h | --help)
+      print_usage
+      exit 0
+      ;;
+    *) log_error "Unknown argument: $arg" ;;
+    esac
+  done
+}
+
+# Union of the branch's committed diff, the working tree, and untracked files.
+# A wider set only means running more stages, so every fallback widens.
+collect_changed_files() {
+  [ "$SCOPED" = true ] || return 0
+
+  local base head local_baseline=false
+  # origin/main, not local main. On main itself the local ref is HEAD, so a commit
+  # not yet pushed would drop out of the changed set and skip the scoped stages.
+  base=$(git -C "$PROJECT_ROOT" merge-base HEAD origin/main 2>/dev/null) || base=""
+  if [ -z "$base" ]; then
+    local_baseline=true
+    base=$(git -C "$PROJECT_ROOT" merge-base HEAD main 2>/dev/null) || base=""
+  fi
+  if [ -z "$base" ]; then
+    SCOPED=false
+    log_warn "No merge base with main. Running every stage."
+    return 0
+  fi
+
+  # Without a remote baseline, a merge base equal to HEAD hides committed work.
+  if [ "$local_baseline" = true ]; then
+    head=$(git -C "$PROJECT_ROOT" rev-parse HEAD 2>/dev/null) || head=""
+    if [ -z "$head" ] || [ "$base" = "$head" ]; then
+      SCOPED=false
+      log_warn "No pushed baseline to compare against. Running every stage."
+      return 0
+    fi
+  fi
+
+  CHANGED_FILES=$({
+    git -C "$PROJECT_ROOT" diff --name-only "$base" HEAD
+    git -C "$PROJECT_ROOT" diff --name-only HEAD
+    git -C "$PROJECT_ROOT" ls-files --others --exclude-standard
+  } | sort -u)
+}
+
+has_changed() {
+  [ "$SCOPED" = true ] || return 0
+  printf '%s\n' "$CHANGED_FILES" | grep -qE "$1"
+}
+
+run_check() {
+  local cmd=$1
+  local err_msg=$2
+  local output
+  if ! output=$(eval "$cmd" 2>&1); then
+    echo "$output" | pipe_output
+    log_error "$err_msg"
+  fi
+  echo "$output" | pipe_output
+}
+
+# Whatever plugin and marketplace manifests the repo currently carries, so the
+# stage picks up a new one without an edit here. Both listings honor .gitignore,
+# which keeps linked worktrees and dependency copies out.
+collect_plugin_manifests() {
+  {
+    git -C "$PROJECT_ROOT" ls-files -- '*.claude-plugin/plugin.json' '*.claude-plugin/marketplace.json'
+    git -C "$PROJECT_ROOT" ls-files --others --exclude-standard -- '*.claude-plugin/plugin.json' '*.claude-plugin/marketplace.json'
+  } | sort -u
+}
+
+assert_no_drift() {
+  local paths=$1
+  local err_msg=$2
+  run_check "cd $PROJECT_ROOT && git diff --exit-code --quiet -- $paths" "$err_msg"
+  run_check "cd $PROJECT_ROOT && [ -z \"\$(git ls-files --others --exclude-standard -- $paths)\" ]" "$err_msg"
+}
+
+main() {
+  check_dependencies
+  parse_args "$@"
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  repair_bare_flag
+  collect_changed_files
+
+  if [ "$WRITE" = true ]; then
+    echo -e "${GREY}├${NC} ${WHITE}Formatting${NC}"
+    run_check "bun run format" "Format failed"
+    log_info "Format applied"
+  else
+    echo -e "${GREY}├${NC} ${WHITE}Format check${NC}"
+    run_check "bun run check:format" "Format check failed"
+    log_info "Format check passed"
+  fi
+
+  log_step "Indexes"
+  run_check "bash $PROJECT_ROOT/scripts/core/regen-indexes.sh" "Index regen failed"
+  assert_no_drift "'*index.md'" "Indexes drifted. Run bun run check and commit the updated index files."
+  log_info "Indexes clean"
+
+  log_step "Consumed copies"
+  run_check "bash $PROJECT_ROOT/scripts/core/regen-claude-copies.sh" "Consumed-copy regen failed"
+  assert_no_drift ".claude/standards .claude/snippets .claude/internal" "Consumed copies drifted. Run bun run check and commit .claude/standards, .claude/snippets, and .claude/internal."
+  log_info "Consumed copies clean"
+
+  log_step "Skill references"
+  run_check "bash $PROJECT_ROOT/scripts/core/regen-skill-references.sh" "Skill-reference regen failed"
+  assert_no_drift "claude/skills/*/references" "Skill references drifted. Run bun run check and commit the updated reference files."
+  log_info "Skill references clean"
+
+  log_step "Skill paths"
+  run_check "bash $PROJECT_ROOT/scripts/core/check-skill-paths.sh" "Shipped skills reference a repo-local path."
+  log_info "Skill paths clean"
+
+  log_step "Plugin boundary"
+  run_check "bash $PROJECT_ROOT/scripts/core/check-plugin-boundary.sh" "Plugin ships toolkit-internal content."
+  log_info "Plugin boundary clean"
+
+  log_step "Plugin manifests"
+  if ! command -v claude >/dev/null 2>&1; then
+    log_info "Skipped, claude is not installed"
+  else
+    local manifests manifest
+    manifests=$(collect_plugin_manifests)
+    if [ -z "$manifests" ]; then
+      log_info "Skipped, no manifests present"
+    else
+      while IFS= read -r manifest; do
+        run_check "cd $PROJECT_ROOT && claude plugin validate --strict '$manifest'" "Manifest validation failed: $manifest"
+      done <<<"$manifests"
+      log_info "Manifests valid"
+    fi
+  fi
+
+  log_step "Spelling"
+  run_check "bun run check:spell" "Spell check failed"
+  log_info "Spell check passed"
+
+  log_step "Shell"
+  if has_changed '\.sh$|^package\.json$'; then
+    run_check "bun run check:shell" "Shell check failed"
+    log_info "Shell check passed"
+  else
+    log_info "Skipped, no shell changes"
+  fi
+
+  log_step "Types"
+  if has_changed '^src/|^tsconfig\.json$|^package\.json$'; then
+    run_check "bun run check:types" "Typecheck failed"
+    log_info "Typecheck passed"
+  else
+    log_info "Skipped, no TypeScript changes"
+  fi
+
+  log_step "Tests"
+  if has_changed '^src/|^vitest\.config\.ts$|^tsconfig\.json$|^package\.json$'; then
+    run_check "bun run test" "Tests failed"
+    log_info "Tests passed"
+  else
+    log_info "Skipped, no TypeScript changes"
+  fi
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Verification passed${NC}"
+  fi
+}
+
+main "$@"

package/scripts/docs/list.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/frontmatter.sh"
+
+DOCS_DIR="$PROJECT_ROOT/docs"
+CONTEXT_DIR="$PROJECT_ROOT/.claude/context"
+
+INTERNAL_TOPICS=" ci development extensions sandbox "
+
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} aitk docs list [options]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
+  echo -e "${GREY}│${NC}    --json       ${GREY}# Emit machine-readable JSON${NC}"
+  echo -e "${GREY}│${NC}    -h, --help   ${GREY}# Show this help message${NC}"
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+
+is_target_facing() {
+  case "$1" in
+  "Agent surface" | "Domain references") return 0 ;;
+  *) return 1 ;;
+  esac
+}
+
+is_internal_topic() {
+  case "$INTERNAL_TOPICS" in
+  *" $1 "*) return 0 ;;
+  *) return 1 ;;
+  esac
+}
+
+list_text() {
+  local file name description category
+  log_step "Docs"
+  while IFS= read -r file; do
+    name=$(basename "$file" .md)
+    [ "$name" = "index" ] && continue
+    category=$(read_frontmatter_field "$file" "category")
+    is_target_facing "$category" || continue
+    description=$(read_frontmatter_field "$file" "description")
+    log_info "$name : $description"
+  done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+
+  # Absent in a registry install, which ships docs/ without .claude/
+  if [ -d "$CONTEXT_DIR" ]; then
+    log_step "Domain context"
+    while IFS= read -r file; do
+      name=$(basename "$file" .md)
+      [ "$name" = "index" ] && continue
+      is_internal_topic "$name" && continue
+      description=$(read_frontmatter_field "$file" "description")
+      log_info "$name : $description"
+    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  fi
+}
+
+emit_json_entry() {
+  local name="$1" description="$2" category="$3" target="$4"
+  [ "$JSON_FIRST" -eq 0 ] && printf ','
+  jq -nc \
+    --arg name "$name" \
+    --arg description "$description" \
+    --arg category "$category" \
+    --arg target "$target" \
+    '{name: $name, description: $description, category: $category, target: $target}'
+  JSON_FIRST=0
+}
+
+list_json() {
+  local file name description category
+  JSON_FIRST=1
+  printf '['
+  while IFS= read -r file; do
+    name=$(basename "$file" .md)
+    [ "$name" = "index" ] && continue
+    category=$(read_frontmatter_field "$file" "category")
+    is_target_facing "$category" || continue
+    description=$(read_frontmatter_field "$file" "description")
+    emit_json_entry "$name" "$description" "$category" "docs/$(basename "$file")"
+  done < <(find "$DOCS_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+
+  if [ -d "$CONTEXT_DIR" ]; then
+    while IFS= read -r file; do
+      name=$(basename "$file" .md)
+      [ "$name" = "index" ] && continue
+      is_internal_topic "$name" && continue
+      description=$(read_frontmatter_field "$file" "description")
+      emit_json_entry "$name" "$description" "" ".claude/context/$(basename "$file")"
+    done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md" | sort)
+  fi
+  printf ']'
+}
+
+main() {
+  local json=0
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+    -h | --help) show_help ;;
+    --json)
+      json=1
+      shift
+      ;;
+    *) log_error "Unknown option: $1" ;;
+    esac
+  done
+
+  trap close_timeline EXIT
+
+  if [ "$json" -eq 1 ]; then
+    printf '{"docs":'
+    list_json
+    printf '}\n'
+    exit 0
+  fi
+
+  list_text
+}
+
+main "$@"

package/scripts/gov/list.sh

@@ -0,0 +1,234 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+
+STACKS_DIR="$PROJECT_ROOT/governance/stacks"
+RULES_DIR="$PROJECT_ROOT/governance/rules"
+
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} aitk gov list [options]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
+  echo -e "${GREY}│${NC}    --stacks    ${GREY}# Only list stacks${NC}"
+  echo -e "${GREY}│${NC}    --rules     ${GREY}# Only list rules${NC}"
+  echo -e "${GREY}│${NC}    --json      ${GREY}# Emit machine-readable JSON${NC}"
+  echo -e "${GREY}│${NC}    -h, --help  ${GREY}# Show this help message${NC}"
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+
+read_frontmatter_field() {
+  local file="$1"
+  local field="$2"
+  awk -v f="$field" '
+    BEGIN { fm = 0 }
+    /^---$/ { fm++; if (fm > 1) exit; next }
+    fm == 1 {
+      if (match($0, "^" f ":")) {
+        val = substr($0, RLENGTH + 1)
+        sub(/^[[:space:]]+/, "", val)
+        sub(/^[\x27"]/, "", val)
+        sub(/[\x27"]$/, "", val)
+        print val
+        exit
+      }
+    }
+  ' "$file"
+}
+
+read_frontmatter_paths() {
+  local file="$1"
+  awk '
+    BEGIN { fm = 0; in_paths = 0 }
+    /^---$/ { fm++; if (fm > 1) exit; next }
+    fm == 1 {
+      if (in_paths) {
+        if (match($0, /^[[:space:]]*-[[:space:]]+/)) {
+          val = substr($0, RLENGTH + 1)
+          sub(/^[\x27"]/, "", val)
+          sub(/[\x27"]$/, "", val)
+          print val
+          next
+        }
+        in_paths = 0
+      }
+      if ($0 == "paths:") { in_paths = 1 }
+    }
+  ' "$file"
+}
+
+rule_domain() {
+  local file="$1"
+  local rel="${file#"$RULES_DIR"/}"
+  echo "${rel%%/*}"
+}
+
+stack_rules_array() {
+  local toml="$1"
+  grep -oE '"[0-9]{3}-[a-z0-9-]+"' "$toml" | sed 's/"//g'
+}
+
+json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  printf '%s' "$s"
+}
+
+list_stacks_text() {
+  log_step "Stacks"
+  local toml
+  for toml in "$STACKS_DIR"/*.toml; do
+    local name
+    name=$(basename "$toml" .toml)
+    local extends
+    extends=$(grep '^extends' "$toml" | cut -d'"' -f2)
+    local rule_count
+    rule_count=$(stack_rules_array "$toml" | wc -l)
+    if [ -n "$extends" ]; then
+      log_info "$name (extends: $extends, $rule_count rules)"
+    else
+      log_info "$name ($rule_count rules)"
+    fi
+  done
+}
+
+list_rules_text() {
+  log_step "Rules"
+  local file
+  while IFS= read -r file; do
+    local name
+    name=$(basename "$file" .md)
+    local domain
+    domain=$(rule_domain "$file")
+    local desc
+    desc=$(read_frontmatter_field "$file" "description")
+    log_info "$name [$domain] $desc"
+  done < <(find "$RULES_DIR" -type f -name "*.md" | sort)
+}
+
+list_stacks_json() {
+  local first=1
+  local toml
+  printf '['
+  for toml in "$STACKS_DIR"/*.toml; do
+    local name
+    name=$(basename "$toml" .toml)
+    local extends
+    extends=$(grep '^extends' "$toml" | cut -d'"' -f2)
+    local rules_json="["
+    local first_rule=1
+    local rule
+    while IFS= read -r rule; do
+      [ -z "$rule" ] && continue
+      if [ "$first_rule" -eq 0 ]; then
+        rules_json+=","
+      fi
+      rules_json+="\"$rule\""
+      first_rule=0
+    done < <(stack_rules_array "$toml")
+    rules_json+="]"
+    if [ "$first" -eq 0 ]; then
+      printf ','
+    fi
+    if [ -n "$extends" ]; then
+      printf '{"name":"%s","extends":"%s","rules":%s}' "$name" "$extends" "$rules_json"
+    else
+      printf '{"name":"%s","extends":null,"rules":%s}' "$name" "$rules_json"
+    fi
+    first=0
+  done
+  printf ']'
+}
+
+list_rules_json() {
+  local first=1
+  local file
+  printf '['
+  while IFS= read -r file; do
+    local name
+    name=$(basename "$file" .md)
+    local domain
+    domain=$(rule_domain "$file")
+    local desc
+    desc=$(read_frontmatter_field "$file" "description")
+
+    local paths_json="null"
+    local paths_collected=()
+    while IFS= read -r p; do
+      [ -n "$p" ] && paths_collected+=("$p")
+    done < <(read_frontmatter_paths "$file")
+    if [ "${#paths_collected[@]}" -gt 0 ]; then
+      paths_json="["
+      local first_p=1
+      local p
+      for p in "${paths_collected[@]}"; do
+        [ "$first_p" -eq 0 ] && paths_json+=","
+        paths_json+="\"$(json_escape "$p")\""
+        first_p=0
+      done
+      paths_json+="]"
+    fi
+
+    if [ "$first" -eq 0 ]; then
+      printf ','
+    fi
+    printf '{"name":"%s","domain":"%s","description":"%s","paths":%s}' \
+      "$name" "$domain" "$(json_escape "$desc")" "$paths_json"
+    first=0
+  done < <(find "$RULES_DIR" -type f -name "*.md" | sort)
+  printf ']'
+}
+
+main() {
+  local show_stacks=1
+  local show_rules=1
+  local json=0
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+    -h | --help) show_help ;;
+    --stacks)
+      show_rules=0
+      shift
+      ;;
+    --rules)
+      show_stacks=0
+      shift
+      ;;
+    --json)
+      json=1
+      shift
+      ;;
+    *) log_error "Unknown option: $1" ;;
+    esac
+  done
+
+  trap close_timeline EXIT
+
+  if [ "$json" -eq 1 ]; then
+    printf '{'
+    if [ "$show_stacks" -eq 1 ]; then
+      printf '"stacks":'
+      list_stacks_json
+      [ "$show_rules" -eq 1 ] && printf ','
+    fi
+    if [ "$show_rules" -eq 1 ]; then
+      printf '"rules":'
+      list_rules_json
+    fi
+    printf '}\n'
+    exit 0
+  fi
+
+  [ "$show_stacks" -eq 1 ] && list_stacks_text
+  [ "$show_rules" -eq 1 ] && list_rules_text
+}
+
+main "$@"

package/scripts/lib/frontmatter.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+# Reads one frontmatter field from a markdown file.
+#
+# Kept in bash because the list commands call it once per field per file
+# inside a loop, where shelling into the CLI would cost a process per read.
+# The index engine that used to live here is TypeScript, in src/indexes/.
+read_frontmatter_field() {
+  local file="$1"
+  local key="$2"
+  awk -v key="$key" '
+    NR == 1 && /^---$/ { in_fm = 1; next }
+    in_fm && /^---$/ { exit }
+    in_fm {
+      prefix = key ": "
+      if (index($0, prefix) == 1) {
+        val = substr($0, length(prefix) + 1)
+        if (length(val) >= 2) {
+          first = substr(val, 1, 1)
+          last = substr(val, length(val), 1)
+          if ((first == "\"" && last == "\"") || (first == "'\''" && last == "'\''")) {
+            val = substr(val, 2, length(val) - 2)
+          }
+        }
+        print val
+        exit
+      }
+    }
+  ' "$file"
+}

package/scripts/lib/gov.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# Sole survivor of the gov lib. Called once per rule file inside install and
+# sandbox loops, where routing through the CLI would cost a process per file.
+
+rule_subdir() {
+  local src="$1"
+  local rules_root="${2:-$PROJECT_ROOT/governance/rules}"
+  local rel="${src#"$rules_root/"}"
+  local subdir
+  subdir=$(dirname "$rel")
+  [ "$subdir" = "." ] && subdir=""
+  echo "$subdir"
+}