learning_ai_common_plat/.windsurf/workflows/audit-repo-health.md

description
Cross-repo health audit — verify pnpm config, Dockerfiles, next.config.ts, and workspace consistency

Cross-Repo Health Audit

Systematically verify consistency across all ByteLyst product repos. Catches drift in pnpm config, Dockerfiles, next.config.ts, and workspace setup.

Run this after: pnpm migrations, Dockerfile changes, @bytelyst/* package additions, or periodic maintenance.

1. Check packageManager field in all root package.json files

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== packageManager in root package.json ==="
for repo in \
  learning_ai_common_plat \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_peakpulse \
  learning_ai_notes \
  learning_ai_flowmonk \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  printf "%-40s " "$repo:"
  grep '"packageManager"' "$REPOS_DIR/$repo/package.json" 2>/dev/null || echo "MISSING"
done

Expect: all repos show "packageManager": "pnpm@10.6.5". Fix any MISSING entries.

2. Check node_modules in .gitignore

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== node_modules in .gitignore ==="
for repo in \
  learning_ai_common_plat \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_peakpulse \
  learning_ai_notes \
  learning_ai_flowmonk \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  printf "%-40s " "$repo:"
  grep -c 'node_modules' "$REPOS_DIR/$repo/.gitignore" 2>/dev/null || echo "MISSING"
done

Expect: all repos have at least 1 match. Fix any with 0 or MISSING.

3. Check .dockerignore exists and does NOT exclude .docker-deps

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== .dockerignore health ==="
for repo in \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_peakpulse \
  learning_ai_notes \
  learning_ai_flowmonk \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  di="$REPOS_DIR/$repo/.dockerignore"
  if [ ! -f "$di" ]; then
    echo "$repo: MISSING .dockerignore"
  elif grep -q 'docker-deps' "$di"; then
    echo "$repo: BUG — .dockerignore excludes .docker-deps"
  else
    echo "$repo: OK"
  fi
done

Expect: all OK. Any BUG entries will break Docker builds.

4. Check stale package-lock.json files

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== Stale package-lock.json ==="
for repo in \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_peakpulse \
  learning_ai_notes \
  learning_ai_flowmonk \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  found=$(find "$REPOS_DIR/$repo" -name "package-lock.json" -not -path "*/node_modules/*" 2>/dev/null)
  if [ -n "$found" ]; then echo "STALE: $found"; fi
done
echo "(empty = all clean)"

Expect: no output. Remove any stale lockfiles found.

5. Check Dockerfiles use node:22-slim and have NODE_TLS

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== Dockerfile base image + NODE_TLS ==="
for repo in \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_peakpulse \
  learning_ai_notes \
  learning_ai_flowmonk \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  for df in $(git -C "$REPOS_DIR/$repo" ls-files '*/Dockerfile' 2>/dev/null); do
    full="$REPOS_DIR/$repo/$df"
    base=$(grep -m1 '^FROM' "$full" | awk '{print $2}')
    tls=$(grep -c 'NODE_TLS_REJECT_UNAUTHORIZED' "$full" 2>/dev/null)
    status="OK"
    [[ "$base" == *alpine* ]] && status="WARN:alpine"
    [[ "$tls" == "0" && "$df" != *python* ]] && status="$status WARN:no-NODE_TLS"
    echo "$repo/$df: base=$base tls=$tls $status"
  done
done

Expect: all use node:22-slim, all have NODE_TLS refs > 0. Fix any WARN entries.

6. Check next.config.ts has transpilePackages + symlinks

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== next.config.ts: transpilePackages + symlinks ==="
for repo in \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_notes \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  for cfg in $(find "$REPOS_DIR/$repo" -maxdepth 2 -name "next.config.ts" -not -path "*/node_modules/*" 2>/dev/null); do
    relpath="${cfg#$REPOS_DIR/}"
    tp=$(grep -c 'transpilePackages' "$cfg")
    sl=$(grep -c 'symlinks' "$cfg")
    status="OK"
    [[ "$tp" == "0" ]] && status="MISSING:transpilePackages"
    [[ "$sl" == "0" ]] && status="$status MISSING:symlinks"
    echo "$relpath: transpile=$tp symlinks=$sl $status"
  done
done

Expect: all show transpile>0 and symlinks>0. Fix any MISSING entries.

7. Check pnpm-workspace.yaml includes common-plat packages

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== pnpm-workspace.yaml includes common-plat ==="
for repo in \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_peakpulse \
  learning_ai_notes \
  learning_ai_flowmonk \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  ws="$REPOS_DIR/$repo/pnpm-workspace.yaml"
  if [ ! -f "$ws" ]; then
    echo "$repo: MISSING pnpm-workspace.yaml"
  elif grep -q 'common_plat' "$ws"; then
    echo "$repo: OK"
  else
    echo "$repo: MISSING common-plat in workspace"
  fi
done

Expect: all OK. Fix any MISSING entries.

8. Check docker-prep.sh uses shared prep-consumer

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== docker-prep.sh uses shared prep-consumer ==="
for repo in \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_peakpulse \
  learning_ai_notes \
  learning_ai_flowmonk \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  script="$REPOS_DIR/$repo/scripts/docker-prep.sh"
  if [ ! -f "$script" ]; then
    echo "$repo: NO docker-prep.sh"
  elif grep -q 'prep-consumer' "$script"; then
    echo "$repo: OK (shared wrapper)"
  else
    echo "$repo: WARN — legacy docker-prep.sh"
  fi
done

Expect: all OK. Legacy scripts should be replaced with the shared wrapper.

9. Check verify scripts reference correct package filter names

// turbo

REPOS_DIR="/Users/sd9235/code/mygh"
echo "=== Root verify scripts ==="
for repo in \
  learning_voice_ai_agent \
  learning_ai_clock \
  learning_ai_fastgap \
  learning_ai_jarvis_jr \
  learning_ai_peakpulse \
  learning_ai_notes \
  learning_ai_flowmonk \
  learning_ai_trails \
  learning_ai_local_memory_gpt; do
  printf "%-40s " "$repo:"
  node -e "const p=require('$REPOS_DIR/$repo/package.json'); console.log(p.scripts?.verify || 'NONE')" 2>/dev/null
done

Review output manually — ensure --filter names match actual package names in sub-packages.

10. Summarize findings and fix

For each issue found:

1. Fix the file in the affected repo
2. Commit with message: fix(repo): <description of fix>
3. Push to origin

Run /gitea-ci after all fixes to verify full CI passes.