@erclx/aitk 0.8.0

package/scripts/core/bootstrap.sh

@@ -0,0 +1,81 @@
+#!/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"
+
+ZSHRC="${ZDOTDIR:-$HOME}/.zshrc"
+MARKER_OPEN="# >>> aitk aliases >>>"
+MARKER_CLOSE="# <<< aitk aliases <<<"
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed. See https://bun.sh, then re-run."
+}
+
+install_cli() {
+  log_step "Installing the aitk CLI"
+  bun install --cwd "$PROJECT_ROOT" >/dev/null
+  bun link --cwd "$PROJECT_ROOT" >/dev/null
+  log_info "Dependencies installed and aitk linked"
+}
+
+alias_block() {
+  cat <<EOF
+$MARKER_OPEN
+TOOLKIT="$PROJECT_ROOT"
+
+alias cl='claude'
+alias clr='cl -r'
+alias clc='cl -c'
+alias clw='cl -w'
+alias cls='cl --model sonnet'
+
+alias clp='claude --plugin-dir \$TOOLKIT/claude'
+alias clpc='clp -c'
+alias clps='clp --model sonnet'
+$MARKER_CLOSE
+EOF
+}
+
+install_aliases() {
+  log_step "Installing Claude Code shell aliases"
+
+  if [ -f "$ZSHRC" ] && grep -qF "$MARKER_OPEN" "$ZSHRC"; then
+    log_info "Aliases already present in $ZSHRC, skipping"
+    return
+  fi
+
+  if [ -f "$ZSHRC" ] && grep -qE "^alias clp=" "$ZSHRC"; then
+    log_warn "An unmanaged clp alias is already in $ZSHRC. Leaving it untouched."
+    log_warn "Remove it and re-run to switch to the managed block."
+    return
+  fi
+
+  printf '\n%s\n' "$(alias_block)" >>"$ZSHRC"
+  log_add "Appended aitk alias block to $ZSHRC"
+  log_info "Run 'source $ZSHRC' or open a new shell to load them"
+}
+
+verify_cli() {
+  log_step "Verifying the install"
+  if aitk --help >/dev/null 2>&1; then
+    log_info "aitk resolves on PATH"
+  else
+    log_warn "aitk not on PATH yet. Ensure \$BUN_INSTALL/bin is exported, then re-open your shell."
+  fi
+}
+
+main() {
+  open_timeline "aitk bootstrap"
+  trap close_timeline EXIT
+
+  check_dependencies
+  install_cli
+  install_aliases
+  verify_cli
+}
+
+main "$@"

package/scripts/core/check-plugin-boundary.sh

@@ -0,0 +1,45 @@
+#!/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)}"
+
+INTERNAL_ROOT="$PROJECT_ROOT/internal"
+PLUGIN_ROOT="$PROJECT_ROOT/claude"
+
+# `find` writes to stderr and returns non-zero for a missing root, inside a
+# process substitution whose status nothing reads. Without this the walk covers
+# nothing and the check reports the boundary clean having never measured it.
+if [ ! -d "$PLUGIN_ROOT" ]; then
+  echo "No plugin root at ${PLUGIN_ROOT#"$PROJECT_ROOT/"}, boundary unverifiable." >&2
+  exit 1
+fi
+
+# `realpath` resolves each walked path below. Absent, `set -e` aborts on the
+# substitution and the stage reports a leak for a tool that is not installed,
+# which is the same unmeasured-tree-with-a-verdict shape the guard above closes.
+if ! command -v realpath >/dev/null 2>&1; then
+  echo "realpath is not installed, boundary unverifiable." >&2
+  exit 1
+fi
+
+# The plugin reaches `standards/` and `snippets/` through symlinks, which an
+# installer dereferences with no code in the path to filter. Walking the plugin
+# tree with symlinks followed is what an install actually copies, so resolving
+# each file and rejecting anything under `internal/` asserts the boundary at the
+# only place it can be measured.
+leaked=""
+while IFS= read -r file; do
+  resolved=$(realpath "$file")
+  case "$resolved" in
+  "$INTERNAL_ROOT"/*) leaked="$leaked  ${file#"$PROJECT_ROOT/"} -> ${resolved#"$PROJECT_ROOT/"}"$'\n' ;;
+  esac
+done < <(find -L "$PLUGIN_ROOT" -type f)
+
+if [ -n "$leaked" ]; then
+  echo "Plugin ships toolkit-internal content:" >&2
+  printf '%s' "$leaked" >&2
+  echo "Author internal content under internal/, which nothing under claude/ reaches." >&2
+  exit 1
+fi

package/scripts/core/check-skill-paths.sh

@@ -0,0 +1,25 @@
+#!/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)}"
+
+SKILLS_DIR="$PROJECT_ROOT/claude/skills"
+
+# A shipped skill runs from a target project, where the toolkit's own wiki/ does
+# not exist. Anchoring on a non-path character keeps a target's .claude/wiki/ legal.
+BANNED_PATH_PATTERN='(^|[^[:alnum:]._/-])wiki/'
+
+[ -d "$SKILLS_DIR" ] || exit 0
+
+matches=$(grep -rnE "$BANNED_PATH_PATTERN" "$SKILLS_DIR" || true)
+
+[ -z "$matches" ] && exit 0
+
+echo "Shipped skills reference a repo-local path that does not exist in a target project:"
+echo "$matches" | sed "s|^$PROJECT_ROOT/||"
+echo
+echo "Reach supporting prose through an aitk docs command, a bundled reference, or inlined text."
+echo "A match inside a references/ folder is a generated copy. Fix the source under standards/bundled/."
+exit 1

package/scripts/core/clean.sh

@@ -0,0 +1,36 @@
+#!/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"
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
+}
+
+main() {
+  check_dependencies
+
+  echo -e "${GREY}┌${NC}"
+
+  echo -e "${GREY}├${NC} ${WHITE}Cleaning artifacts${NC}"
+  rm -rf node_modules
+
+  log_rem "node_modules/"
+
+  log_step "Cleaning cache"
+  bun pm cache rm
+  log_info "Package manager cache cleared"
+
+  log_step "Rehydrating project"
+  bun install
+  log_info "Dependencies installed"
+
+  echo -e "${GREY}└${NC}\n"
+  echo -e "${GREEN}✓ Clean complete${NC}"
+}
+
+main "$@"

package/scripts/core/install-check.sh

@@ -0,0 +1,93 @@
+#!/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"
+
+TMP_ROOT="$PROJECT_ROOT/.claude/.tmp/install-check"
+CLONE_DIR="$TMP_ROOT/clone"
+TARGET_DIR="$TMP_ROOT/target"
+KEEP=0
+
+for arg in "$@"; do
+  case "$arg" in
+  --keep) KEEP=1 ;;
+  --help | -h)
+    cat <<HELP
+Usage: scripts/core/install-check.sh [--keep]
+
+Verifies the README install path end to end:
+  1. Clones this repo into .claude/.tmp/install-check/clone
+  2. Runs bun install in the clone
+  3. Runs the CLI with --help to confirm it executes
+  4. Scaffolds a fresh project in .claude/.tmp/install-check/target
+  5. Runs aitk init and asserts a scaffold landed
+
+Flags:
+  --keep    Keep the tmp tree on exit for inspection
+HELP
+    exit 0
+    ;;
+  esac
+done
+
+cleanup() {
+  if [ "$KEEP" = "1" ]; then
+    log_info "Kept artifacts at $TMP_ROOT"
+  else
+    rm -rf "$TMP_ROOT"
+  fi
+  close_timeline
+}
+trap cleanup EXIT
+
+rm -rf "$TMP_ROOT"
+mkdir -p "$TMP_ROOT"
+
+open_timeline "Install verification"
+
+log_step "Clone"
+git clone --quiet "$PROJECT_ROOT" "$CLONE_DIR" 2>&1 | pipe_output || true
+log_info "Cloned to $CLONE_DIR"
+
+log_step "Install dependencies"
+(cd "$CLONE_DIR" && bun install --silent 2>&1 | pipe_output) || log_error "bun install failed"
+log_info "Dependencies installed"
+
+log_step "Confirm CLI runs"
+(cd "$CLONE_DIR" && bun run src/cli.ts --help >/dev/null) || log_error "aitk --help failed"
+log_info "aitk --help ran clean"
+
+log_step "Scaffold fresh project"
+mkdir -p "$TARGET_DIR"
+(cd "$TARGET_DIR" && git init --quiet)
+log_info "Initialized git in $TARGET_DIR"
+
+log_step "Run aitk init"
+(cd "$TARGET_DIR" && AITK_NON_INTERACTIVE=1 bun run "$CLONE_DIR/src/cli.ts" init --stack base 2>&1 | pipe_output) || log_error "aitk init failed"
+log_info "aitk init completed"
+
+log_step "Assert scaffold"
+# Every domain aitk init installs needs at least one path here. A domain with
+# no assertion can truncate silently: init still exits 0 because run_domain
+# catches a failed domain, and the gate stays green while the target is
+# missing everything that domain provides.
+for path in "CLAUDE.md" ".claude/snippets/compact-summary.md" ".claude/standards/prose.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" \
+  ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
+  ".claude/rules/core/000-constitution.md"; do
+  if [ ! -e "$TARGET_DIR/$path" ]; then
+    log_error "Missing after aitk init: $path"
+  fi
+  log_info "Found: $path"
+done
+
+if [ ! -x "$TARGET_DIR/scripts/verify.sh" ]; then
+  log_error "Not executable after aitk init: scripts/verify.sh"
+fi
+log_info "Executable: scripts/verify.sh"
+
+log_step "Verification passed"
+log_info "Manual check still needed: bun link and global aitk invocation"

package/scripts/core/regen-claude-copies.sh

@@ -0,0 +1,26 @@
+#!/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)}"
+
+mirror_dir() {
+  local src="$1"
+  local dest="$2"
+  local find_args=("${@:3}")
+
+  rm -rf "$dest"
+  while IFS= read -r file; do
+    local rel="${file#"$src"/}"
+    mkdir -p "$dest/$(dirname "$rel")"
+    cp "$file" "$dest/$rel"
+  done < <(find "$src" -type f "${find_args[@]}" | sort)
+}
+
+mirror_dir "$PROJECT_ROOT/standards" "$PROJECT_ROOT/.claude/standards" -name "*.md" -not -path "*/bundled/*"
+mirror_dir "$PROJECT_ROOT/snippets" "$PROJECT_ROOT/.claude/snippets" -name "*.md"
+
+# `internal/` is the surface the plugin does not symlink. Mirrored on its own so
+# toolkit sessions read it at a `.claude/` path like every other consumed copy.
+mirror_dir "$PROJECT_ROOT/internal" "$PROJECT_ROOT/.claude/internal" -name "*.md"

package/scripts/core/regen-indexes.sh

@@ -0,0 +1,10 @@
+#!/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"
+
+bun "$PROJECT_ROOT/src/cli.ts" indexes regen --root "$PROJECT_ROOT" --json >/dev/null

package/scripts/core/regen-skill-references.sh

@@ -0,0 +1,27 @@
+#!/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/frontmatter.sh"
+
+BUNDLED_DIR="$PROJECT_ROOT/standards/bundled"
+SKILLS_DIR="$PROJECT_ROOT/claude/skills"
+
+[ -d "$BUNDLED_DIR" ] || exit 0
+
+while IFS= read -r file; do
+  filename="$(basename "$file")"
+  consumers="$(read_frontmatter_field "$file" "consumers")"
+  [ -z "$consumers" ] && continue
+  IFS=',' read -ra skills <<<"$consumers"
+  for skill in "${skills[@]}"; do
+    skill="${skill// /}"
+    [ -z "$skill" ] && continue
+    dest_dir="$SKILLS_DIR/$skill/references"
+    mkdir -p "$dest_dir"
+    cp "$file" "$dest_dir/$filename"
+  done
+done < <(find "$BUNDLED_DIR" -type f -name "*.md" | sort)

package/scripts/core/snapshot.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+NESTED="${VERIFY_NESTED:-false}"
+
+log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
+log_error() {
+  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
+  exit 1
+}
+
+OUTPUT_FILE=".claude/.tmp/project/PROJECT-SNAPSHOT.md"
+
+check_dependencies() {
+  command -v find >/dev/null 2>&1 || log_error "find not installed"
+}
+
+load_gitignore_patterns() {
+  if [ ! -f ".gitignore" ]; then
+    echo ""
+    return
+  fi
+  grep -v '^\s*#' .gitignore | grep -v '^\s*$' | sed 's|/$||'
+}
+
+is_ignored() {
+  local name="$1"
+  local patterns="$2"
+
+  [ "$name" = ".git" ] && return 0
+  [ "$name" = "_" ] && return 0
+
+  while IFS= read -r pattern; do
+    [ -z "$pattern" ] && continue
+    # shellcheck disable=SC2053
+    if [[ "$name" == $pattern ]]; then
+      return 0
+    fi
+  done <<<"$patterns"
+
+  return 1
+}
+
+build_tree() {
+  local dir="${1:-.}"
+  local prefix="${2:-}"
+  local patterns="${3:-}"
+  local entries=()
+
+  while IFS= read -r entry; do
+    local name
+    name=$(basename "$entry")
+    is_ignored "$name" "$patterns" && continue
+    entries+=("$entry")
+  done < <(find "$dir" -maxdepth 1 -mindepth 1 | sort)
+
+  local count=${#entries[@]}
+  local i=0
+
+  for entry in "${entries[@]}"; do
+    i=$((i + 1))
+    local name
+    name=$(basename "$entry")
+    local connector="├──"
+    local child_prefix="${prefix}│   "
+
+    if [ "$i" -eq "$count" ]; then
+      connector="└──"
+      child_prefix="${prefix}    "
+    fi
+
+    if [ -d "$entry" ]; then
+      echo "${prefix}${connector} ${name}/"
+      build_tree "$entry" "$child_prefix" "$patterns"
+    else
+      echo "${prefix}${connector} ${name}"
+    fi
+  done
+}
+
+write_snapshot() {
+  local project_name
+  project_name=$(basename "$PWD")
+  local patterns
+  patterns=$(load_gitignore_patterns)
+
+  mkdir -p "$(dirname "$OUTPUT_FILE")"
+
+  {
+    echo "# Project Snapshot: $project_name"
+    echo ""
+    echo "## Structure"
+    echo ""
+    echo '```'
+    build_tree "." "" "$patterns"
+    echo '```'
+    echo ""
+
+    if [ -f "package.json" ]; then
+      echo "## package.json"
+      echo ""
+      echo '```json'
+      cat package.json
+      echo '```'
+      echo ""
+    fi
+  } >"$OUTPUT_FILE"
+}
+
+main() {
+  check_dependencies
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  echo -e "${GREY}├${NC} ${WHITE}Snapshot${NC}"
+  write_snapshot
+  log_info "Written to $OUTPUT_FILE"
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Snapshot complete${NC}"
+  fi
+}
+
+main "$@"

package/scripts/core/update.sh

@@ -0,0 +1,35 @@
+#!/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"
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
+}
+
+main() {
+  check_dependencies
+
+  echo -e "${GREY}┌${NC}"
+
+  echo -e "${GREY}├${NC} ${WHITE}Interactive dependency update${NC}"
+  echo -e "${GREY}│${NC}"
+  bun update --interactive
+
+  log_step "Verifying project health"
+  if [ -f "$SCRIPT_DIR/verify.sh" ]; then
+    VERIFY_NESTED=true "$SCRIPT_DIR/verify.sh"
+    log_info "All checks passed"
+  else
+    log_warn "Verification script not found, skipping."
+  fi
+
+  echo -e "${GREY}└${NC}\n"
+  echo -e "${GREEN}✓ Update complete${NC}"
+}
+
+main "$@"