@glxmart/boss-cli 1.0.0-beta.0

package/dist/assets/docker-compose/docker-compose.yml

@@ -0,0 +1,52 @@
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: boss-postgres
+    environment:
+      POSTGRES_USER: boss
+      POSTGRES_PASSWORD: bosssecret
+      POSTGRES_DB: boss_knowledge
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U boss"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  qdrant:
+    image: qdrant/qdrant:latest
+    container_name: boss-qdrant
+    ports:
+      - "6333:6333"
+      - "6334:6334"
+    volumes:
+      - qdrant_data:/qdrant/storage
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:6333/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  embeddings:
+    image: ghcr.io/huggingface/text-embeddings-inference:latest
+    container_name: boss-embeddings
+    ports:
+      - "8080:80"
+    environment:
+      - MODEL_ID=BAAI/bge-large-en-v1.5
+      - MAX_BATCH_SIZE=32
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+  qdrant_data:
+

package/dist/assets/git-hooks/commit-msg.sh

@@ -0,0 +1,102 @@
+#!/bin/sh
+# Commit message validation hook
+# Strictly enforces Conventional Commits v1.0.0 specification
+# See: https://www.conventionalcommits.org/en/v1.0.0/
+
+. "$(dirname "$0")/_/husky.sh"
+
+commit_msg=$(cat "$1")
+
+# Extract the first line (subject line)
+first_line=$(echo "$commit_msg" | head -n1)
+
+# Validate format: <type>[optional scope][optional !]: <description>
+# According to spec: "Commits MUST be prefixed with a type, which consists of a noun, 
+# feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space."
+
+# Pattern breakdown:
+# - Type: lowercase word (feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert, etc.)
+# - Optional scope: (word) - noun in parentheses
+# - Optional !: for breaking changes
+# - Required: : (colon) followed by space
+# - Description: rest of the line (at least one character)
+if ! echo "$first_line" | grep -qE "^[a-z]+(\\([a-z0-9-]+\\))?(!)?: .+"; then
+  echo "❌ Invalid commit message format!"
+  echo ""
+  echo "Commit messages MUST follow Conventional Commits v1.0.0 specification:"
+  echo "  <type>[optional scope][optional !]: <description>"
+  echo ""
+  echo "Required format:"
+  echo "  type(scope): description"
+  echo "  type!: description        (breaking change)"
+  echo "  type(scope)!: description (breaking change with scope)"
+  echo ""
+  echo "Common types:"
+  echo "  feat:     A new feature"
+  echo "  fix:      A bug fix"
+  echo "  docs:     Documentation only changes"
+  echo "  style:    Changes that do not affect code meaning (formatting, etc.)"
+  echo "  refactor: Code change that neither fixes a bug nor adds a feature"
+  echo "  perf:     Performance improvement"
+  echo "  test:     Adding or updating tests"
+  echo "  chore:    Changes to build process or auxiliary tools"
+  echo "  ci:       Changes to CI configuration"
+  echo "  build:    Changes to build system or dependencies"
+  echo "  revert:   Reverts a previous commit"
+  echo ""
+  echo "Examples:"
+  echo "  ✅ feat(orchestrator): add retry logic"
+  echo "  ✅ fix(agents): handle container errors"
+  echo "  ✅ docs: update architecture guide"
+  echo "  ✅ feat!: change API signature"
+  echo "  ✅ fix(api)!: remove deprecated endpoint"
+  echo "  ❌ update code                    (missing type)"
+  echo "  ❌ feat:fix bug                    (missing space after colon)"
+  echo "  ❌ FEAT: add feature               (type should be lowercase)"
+  echo ""
+  echo "Your message:"
+  echo "  $first_line"
+  echo ""
+  echo "Full specification: https://www.conventionalcommits.org/en/v1.0.0/"
+  exit 1
+fi
+
+# Validate minimum description length (at least 3 characters after colon and space)
+description=$(echo "$first_line" | sed -E 's/^[a-z]+(\\([a-z0-9-]+\\))?(!)?: //')
+if [ ${#description} -lt 3 ]; then
+  echo "❌ Commit description too short (minimum 3 characters)"
+  echo ""
+  echo "Your description: '$description'"
+  exit 1
+fi
+
+# Validate maximum length for first line (recommended 72 characters per spec)
+# Note: Spec doesn't require this, but it's a best practice
+if [ ${#first_line} -gt 100 ]; then
+  echo "⚠️  Warning: First line of commit message exceeds 100 characters"
+  echo "   Recommended: Keep first line under 72 characters for better readability"
+  echo "   Your first line: ${#first_line} characters"
+  echo ""
+  echo "   Consider breaking into multiple lines:"
+  echo "   type(scope): short summary"
+  echo ""
+  echo "   Longer description can go in the body."
+  echo ""
+fi
+
+# Validate that type is lowercase (spec says case insensitive, but lowercase is conventional)
+type=$(echo "$first_line" | sed -E 's/^([a-z]+).*/\\1/')
+if ! echo "$type" | grep -qE '^[a-z]+$'; then
+  echo "⚠️  Warning: Commit type should be lowercase"
+  echo "   Found: '$type'"
+  echo ""
+fi
+
+# Check for BREAKING CHANGE footer (if body exists)
+if echo "$commit_msg" | grep -qiE "^BREAKING CHANGE:"; then
+  echo "ℹ️  Breaking change detected in footer"
+  echo "   Consider using '!' in type prefix for consistency"
+fi
+
+echo "✅ Commit message follows Conventional Commits specification"
+

package/dist/assets/git-hooks/pre-commit-check.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Pre-commit hook script
+#
+# Runs static analysis on staged files only to ensure code quality
+# before commits. Fast enough to run on every commit.
+
+set -e
+
+echo "🔍 Running pre-commit checks..."
+
+# Run lint-staged (handles staged files only: ESLint, Prettier, TypeScript)
+# lint-staged is configured in package.json to run on staged files
+echo "  ✓ Running lint-staged (ESLint + Prettier + TypeScript on staged files)..."
+pnpm exec lint-staged
+
+# Run tests for changed files
+echo ""
+bash scripts/test-changed.sh
+
+echo "✅ Pre-commit checks passed!"
+

package/dist/assets/git-hooks/pre-commit.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Run pre-commit checks script
+bash scripts/pre-commit-check.sh
+

package/dist/assets/git-hooks/pre-push.sh

@@ -0,0 +1,154 @@
+#!/bin/bash
+# Pre-push hook
+# Prevents direct pushes to main and validates code before push
+
+# Get the current branch name
+current_branch=$(git symbolic-ref --short HEAD 2>/dev/null)
+
+# Prevent direct pushes to main (including initial push)
+FIRST_PUSH_TO_MAIN=false
+if [ "$current_branch" = "main" ]; then
+  # Check if this is the very first push (no remote main exists yet)
+  if ! git ls-remote --heads origin main > /dev/null 2>&1; then
+    echo "⚠️  Warning: This appears to be the first push to main"
+    echo "   For initial setup, empty main is allowed, but main branch protection will be enforced after setup"
+    echo "   Future pushes to main will be blocked - use feature branches and PRs instead"
+    FIRST_PUSH_TO_MAIN=true
+    
+    # Check if main branch is empty (only empty commit or minimal files like README/.gitignore)
+    # Count non-trivial files (exclude .gitignore, README.md, LICENSE, etc.)
+    file_count=$(git ls-tree -r HEAD --name-only 2>/dev/null | grep -v -E '^(README\.md|LICENSE|\.gitignore|\.gitattributes)$' | wc -l | tr -d ' ')
+    
+    if [ "$file_count" -eq 0 ]; then
+      echo "✅ Main branch is empty - skipping validation checks for initial empty push"
+      echo "✅ Pre-push validation passed!"
+      exit 0
+    else
+      echo "⚠️  Main branch contains files - validation checks will run"
+    fi
+  else
+    echo "❌ Direct push to main is not allowed!"
+    echo ""
+    echo "Please create a feature branch and submit a PR instead:"
+    echo "  git checkout -b feature/your-feature-name"
+    echo "  git push -u origin feature/your-feature-name"
+    echo "  gh pr create  # or use GitHub UI"
+    echo ""
+    echo "For emergency hotfixes, see: docs/emergency-bypass-procedure.md"
+    exit 1
+  fi
+fi
+
+echo "🔍 Running pre-push validation..."
+
+# Run comprehensive checks
+echo "  ✓ Running typecheck..."
+if ! pnpm typecheck > /dev/null 2>&1; then
+  echo "❌ TypeScript errors detected. Fix them before pushing."
+  pnpm typecheck
+  exit 1
+fi
+
+# Run linting
+echo "  ✓ Running lint check..."
+if ! pnpm lint > /dev/null 2>&1; then
+  echo "❌ Linting errors detected. Fix them before pushing."
+  pnpm lint
+  exit 1
+fi
+
+# Run security checks
+echo "  ✓ Running security checks..."
+if ! bash scripts/security-check.sh; then
+  echo "❌ Security checks failed. Review and fix before pushing."
+  exit 1
+fi
+
+# Run unit tests (fast, exclude integration tests)
+echo "  ✓ Running unit tests..."
+if ! pnpm test:unit > /dev/null 2>&1; then
+  echo "❌ Unit tests failing. Fix them before pushing."
+  pnpm test:unit
+  exit 1
+fi
+
+# Check for unused exports (warn only, not blocking)
+echo "  ✓ Checking for unused exports..."
+if ! pnpm check:unused > /dev/null 2>&1; then
+  echo "⚠️  Warning: Unused exports detected. Run 'pnpm check:unused' for details."
+  echo "   (This is a warning, not blocking)"
+fi
+
+# Warn if no tests in staged commits (skip for first empty push to main)
+if [ "$FIRST_PUSH_TO_MAIN" != "true" ]; then
+  echo "  ✓ Checking for tests..."
+  # Check if remote branch exists (for first push, it won't)
+  if git ls-remote --heads origin $current_branch > /dev/null 2>&1; then
+    # Remote branch exists - check diff
+    test_files=$(git diff origin/$current_branch..HEAD --name-only 2>/dev/null | grep -E '\.(test|spec)\.(ts|tsx|js|jsx)$' || true)
+  else
+    # First push - check all files in HEAD for test files
+    # Use git ls-tree to check committed files
+    test_files=$(git ls-tree -r HEAD --name-only 2>/dev/null | grep -E '\.(test|spec)\.(ts|tsx|js|jsx)$' || true)
+  fi
+
+  # If test_files is empty, try alternative detection methods
+  if [ -z "$test_files" ]; then
+    # Method 1: Check all files in HEAD
+    all_files=$(git ls-tree -r HEAD --name-only 2>/dev/null || true)
+    if [ -n "$all_files" ]; then
+      test_files_alt=$(echo "$all_files" | grep -E '\.(test|spec)\.(ts|tsx|js|jsx)$' || true)
+      if [ -n "$test_files_alt" ]; then
+        test_files="$test_files_alt"
+      fi
+    fi
+    
+    # Method 2: If still empty, check working directory (for uncommitted test files)
+    if [ -z "$test_files" ]; then
+      test_files_wd=$(find . -type f \( -name "*.test.ts" -o -name "*.test.tsx" -o -name "*.test.js" -o -name "*.test.jsx" -o -name "*.spec.ts" -o -name "*.spec.tsx" -o -name "*.spec.js" -o -name "*.spec.jsx" \) ! -path "*/node_modules/*" ! -path "*/.git/*" 2>/dev/null | head -5 || true)
+      if [ -n "$test_files_wd" ]; then
+        # Only use working directory files if they're tracked by git
+        for file in $test_files_wd; do
+          if git ls-files --error-unmatch "$file" >/dev/null 2>&1; then
+            test_files="${test_files:+$test_files }$file"
+          fi
+        done
+      fi
+    fi
+  fi
+
+  if [ -z "$test_files" ]; then
+    echo "⚠️  Warning: No test files in commits being pushed"
+    echo "   TDD Constitution requires tests before implementation"
+    # Allow bypass only in CI environments, but block in all other cases (including BOSS automated pushes)
+    if [ -n "${CI:-}" ]; then
+      echo "   (Allowing in CI environment, but tests should still be added)"
+    elif [ -t 0 ]; then
+      # Interactive terminal - ask user
+      echo "   Continue? (y/N)"
+      read -r response
+      if [ "$response" != "y" ]; then
+        echo "Push cancelled. Add tests first!"
+        exit 1
+      fi
+    else
+      # Non-interactive but not CI (e.g., BOSS automated push) - block it
+      echo "❌ Push blocked: TDD Constitution requires tests before implementation"
+      echo "   Add test files and commit them before pushing."
+      echo "   Expected pattern: *.test.ts, *.test.tsx, *.spec.ts, *.spec.tsx (or .js/.jsx variants)"
+      exit 1
+    fi
+  else
+    # Show found test files (limit to first 3 to avoid clutter)
+    test_file_count=$(echo "$test_files" | wc -l | tr -d ' ')
+    if [ "$test_file_count" -le 3 ]; then
+      echo "   ✓ Found test files: $(echo "$test_files" | tr '\n' ' ')"
+    else
+      echo "   ✓ Found $test_file_count test files (showing first 3): $(echo "$test_files" | head -3 | tr '\n' ' ')"
+    fi
+  fi
+fi
+
+echo "✅ Pre-push validation passed!"
+echo ""
+

package/dist/assets/git-hooks/security-check.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Security check script
+# Runs basic security checks before push
+
+set -e
+
+# Check for common security issues in staged files
+staged_files=$(git diff --cached --name-only --diff-filter=ACM || true)
+
+if [ -z "$staged_files" ]; then
+  # If no staged files, check all tracked files
+  staged_files=$(git ls-files || true)
+fi
+
+# Check for hardcoded secrets (basic check)
+if echo "$staged_files" | xargs grep -lE '(password|secret|api_key|private_key|access_token)\s*[:=]\s*["'\''][^"'\'']+["'\'']' 2>/dev/null; then
+  echo "⚠️  Warning: Potential hardcoded secrets detected"
+  echo "   Review the files above for sensitive information"
+  echo "   (This is a basic check, review manually)"
+fi
+
+# Check for TODO/FIXME comments that might indicate security issues
+if echo "$staged_files" | xargs grep -lE 'TODO.*(security|auth|password|secret|vulnerability)' 2>/dev/null; then
+  echo "⚠️  Warning: Security-related TODOs found"
+  echo "   Review and address before pushing"
+fi
+
+# If npm audit is available, run it (non-blocking)
+if command -v pnpm &> /dev/null; then
+  if pnpm audit --audit-level=moderate 2>/dev/null | grep -qE '(moderate|high|critical)'; then
+    echo "⚠️  Warning: Security vulnerabilities found in dependencies"
+    echo "   Run 'pnpm audit' for details"
+    echo "   Run 'pnpm audit fix' to attempt automatic fixes"
+    # Don't block, just warn
+  fi
+fi
+
+echo "✅ Security checks passed"
+exit 0
+

package/dist/assets/git-hooks/test-changed.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# Test changed files script
+# Runs tests related to staged TypeScript files
+# Only runs if tests are fast enough (optional optimization)
+
+set -e
+
+# Get list of staged TypeScript files
+changed_files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.ts$' || true)
+
+if [ -z "$changed_files" ]; then
+  echo "ℹ️  No TypeScript files changed, skipping tests"
+  exit 0
+fi
+
+# Find related test files (exclude e2e, integration, and container tests)
+test_files=""
+for file in $changed_files; do
+  # Skip e2e and integration tests - too slow for pre-commit
+  if echo "$file" | grep -qE '(tests/(e2e|integration)/|\.(e2e|integration)\.test\.ts$)'; then
+    continue
+  fi
+  
+  # Skip if file is already a test file
+  if echo "$file" | grep -q '\.test\.ts$'; then
+    # Skip container tests that require Docker
+    if echo "$file" | grep -qE '(mock-container|container.*test)'; then
+      echo "  ⏭️  Skipping $file (requires containers/Docker)"
+      continue
+    fi
+    if [ -f "$file" ]; then
+      test_files="$test_files $file"
+    fi
+    continue
+  fi
+
+  # Convert src/foo/bar.ts -> tests/foo/bar.test.ts
+  test_file=$(echo "$file" | sed 's|^src/|tests/|' | sed 's|\.ts$|.test.ts|')
+
+  if [ -f "$test_file" ]; then
+    # Skip e2e and integration tests - too slow for pre-commit
+    if echo "$test_file" | grep -qE 'tests/(e2e|integration)/'; then
+      echo "  ⏭️  Skipping $test_file (e2e/integration test)"
+      continue
+    fi
+    # Skip container tests that require Docker
+    if echo "$test_file" | grep -qE '(mock-container|container.*test)'; then
+      echo "  ⏭️  Skipping $test_file (requires containers/Docker)"
+      continue
+    fi
+    test_files="$test_files $test_file"
+  fi
+done
+
+if [ -z "$test_files" ]; then
+  echo "ℹ️  No related test files found for changed files"
+  exit 0
+fi
+
+echo "🧪 Running tests for changed files..."
+for test_file in $test_files; do
+  echo "  Running: $test_file"
+done
+
+# Run the tests and capture output
+test_output=$(pnpm vitest run $test_files --reporter=dot 2>&1 || true)
+echo "$test_output"
+
+# Check if tests actually passed (look for test summary before potential worker cleanup crash)
+if echo "$test_output" | grep -q "✓.*tests"; then
+  # Tests passed, check for actual test failures
+  if echo "$test_output" | grep -qE "(✗|FAIL|failed)"; then
+    echo "❌ Tests for changed files failed"
+    exit 1
+  else
+    echo "✅ Tests for changed files passed"
+    exit 0
+  fi
+else
+  # No test summary found, something went wrong
+  echo "❌ Tests for changed files failed"
+  exit 1
+fi
+

package/dist/assets/github-workflows/CODEOWNERS

@@ -0,0 +1,3 @@
+# BOSS Project Code Owners
+* @${githubUser}
+

package/dist/assets/github-workflows/boss-ci.yml

@@ -0,0 +1,40 @@
+name: BOSS CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: latest
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Type check
+        run: pnpm typecheck
+      
+      - name: Lint
+        run: pnpm lint
+      
+      - name: Test
+        run: pnpm test
+      
+      - name: Coverage
+        run: pnpm test:coverage
+        continue-on-error: true
+

package/dist/assets/github-workflows/boss-gates.yml

@@ -0,0 +1,28 @@
+name: BOSS Quality Gates
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  quality-gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: latest
+      
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      
+      - name: Run quality gates
+        run: pnpm test:gates
+