aiblueprint-cli 1.1.7 → 1.2.0

package/claude-code-config/scripts/command-validator/src/lib/validator.ts

@@ -0,0 +1,360 @@
+import { SAFE_COMMANDS, SECURITY_RULES } from "./security-rules";
+import type { ValidationResult } from "./types";
+
+export class CommandValidator {
+	validate(command: string, toolName = "Unknown"): ValidationResult {
+		const result: ValidationResult = {
+			isValid: true,
+			severity: "LOW",
+			violations: [],
+			sanitizedCommand: command,
+		};
+
+		if (!command || typeof command !== "string") {
+			result.isValid = false;
+			result.violations.push("Invalid command format");
+			return result;
+		}
+
+		if (command.length > 2000) {
+			result.isValid = false;
+			result.severity = "MEDIUM";
+			result.violations.push("Command too long (potential buffer overflow)");
+			return result;
+		}
+
+		if (/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\xFF]/.test(command)) {
+			result.isValid = false;
+			result.severity = "HIGH";
+			result.violations.push("Binary or encoded content detected");
+			return result;
+		}
+
+		const normalizedCmd = command.trim().toLowerCase();
+		const cmdParts = normalizedCmd.split(/\s+/);
+		const mainCommand = cmdParts[0].split("/").pop() || "";
+
+		if (mainCommand === "source" || mainCommand === "python") {
+			return result;
+		}
+
+		for (const pattern of SECURITY_RULES.DANGEROUS_PATTERNS) {
+			if (pattern.test(command)) {
+				result.isValid = false;
+				result.severity = "CRITICAL";
+				result.violations.push(`Dangerous pattern detected: ${pattern.source}`);
+			}
+		}
+
+		if (SECURITY_RULES.CRITICAL_COMMANDS.includes(mainCommand)) {
+			result.isValid = false;
+			result.severity = "CRITICAL";
+			result.violations.push(`Critical dangerous command: ${mainCommand}`);
+		}
+
+		if (SECURITY_RULES.PRIVILEGE_COMMANDS.includes(mainCommand)) {
+			result.isValid = false;
+			result.severity = "HIGH";
+			result.violations.push(`Privilege escalation command: ${mainCommand}`);
+		}
+
+		if (SECURITY_RULES.NETWORK_COMMANDS.includes(mainCommand)) {
+			result.isValid = false;
+			result.severity = "HIGH";
+			result.violations.push(`Network/remote access command: ${mainCommand}`);
+		}
+
+		if (SECURITY_RULES.SYSTEM_COMMANDS.includes(mainCommand)) {
+			result.isValid = false;
+			result.severity = "HIGH";
+			result.violations.push(`System manipulation command: ${mainCommand}`);
+		}
+
+		if (/rm\s+.*-rf\s/.test(command)) {
+			const isRmRfSafe = this.isRmRfCommandSafe(command);
+			if (!isRmRfSafe) {
+				result.isValid = false;
+				result.severity = "CRITICAL";
+				result.violations.push("rm -rf command targeting unsafe path");
+			}
+		}
+
+		if (SAFE_COMMANDS.includes(mainCommand) && result.violations.length === 0) {
+			return result;
+		}
+
+		if (command.includes("&&")) {
+			const chainedCommands = this.splitCommandChain(command);
+			let allSafe = true;
+			for (const chainedCmd of chainedCommands) {
+				const trimmedCmd = chainedCmd.trim();
+				const cmdParts = trimmedCmd.split(/\s+/);
+				const mainCommand = cmdParts[0];
+
+				if (
+					mainCommand === "source" ||
+					mainCommand === "python" ||
+					SAFE_COMMANDS.includes(mainCommand)
+				) {
+					continue;
+				}
+
+				const chainResult = this.validateSingleCommand(trimmedCmd, toolName);
+				if (!chainResult.isValid) {
+					result.isValid = false;
+					result.severity = chainResult.severity;
+					result.violations.push(
+						`Chained command violation: ${trimmedCmd} - ${chainResult.violations.join(", ")}`,
+					);
+					allSafe = false;
+				}
+			}
+			if (allSafe) {
+				return result;
+			}
+		}
+
+		if (command.includes(";") || command.includes("||")) {
+			const chainedCommands = this.splitCommandChain(command);
+			for (const chainedCmd of chainedCommands) {
+				const chainResult = this.validateSingleCommand(
+					chainedCmd.trim(),
+					toolName,
+				);
+				if (!chainResult.isValid) {
+					result.isValid = false;
+					result.severity = chainResult.severity;
+					result.violations.push(
+						`Chained command violation: ${chainedCmd.trim()} - ${chainResult.violations.join(", ")}`,
+					);
+				}
+			}
+			return result;
+		}
+
+		for (const path of SECURITY_RULES.PROTECTED_PATHS) {
+			if (command.includes(path)) {
+				if (
+					path === "/dev/" &&
+					(command.includes("/dev/null") ||
+						command.includes("/dev/stderr") ||
+						command.includes("/dev/stdout"))
+				) {
+					continue;
+				}
+
+				const cmdStart = command.trim();
+				let isSafeExecutable = false;
+				for (const safePath of SECURITY_RULES.SAFE_EXECUTABLE_PATHS) {
+					if (cmdStart.startsWith(safePath)) {
+						isSafeExecutable = true;
+						break;
+					}
+				}
+
+				const pathIndex = command.indexOf(path);
+				const beforePath = command.substring(0, pathIndex);
+				const redirectBeforePath = />\s*$/.test(beforePath.trim());
+
+				if (!isSafeExecutable && redirectBeforePath) {
+					result.isValid = false;
+					result.severity = "HIGH";
+					result.violations.push(
+						`Dangerous operation on protected path: ${path}`,
+					);
+				}
+			}
+		}
+
+		return result;
+	}
+
+	validateSingleCommand(
+		command: string,
+		_toolName = "Unknown",
+	): ValidationResult {
+		const result: ValidationResult = {
+			isValid: true,
+			severity: "LOW",
+			violations: [],
+			sanitizedCommand: command,
+		};
+
+		if (!command || typeof command !== "string") {
+			result.isValid = false;
+			result.violations.push("Invalid command format");
+			return result;
+		}
+
+		if (command.length > 2000) {
+			result.isValid = false;
+			result.severity = "MEDIUM";
+			result.violations.push("Command too long (potential buffer overflow)");
+			return result;
+		}
+
+		if (/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\xFF]/.test(command)) {
+			result.isValid = false;
+			result.severity = "HIGH";
+			result.violations.push("Binary or encoded content detected");
+			return result;
+		}
+
+		const normalizedCmd = command.trim().toLowerCase();
+		const cmdParts = normalizedCmd.split(/\s+/);
+		const mainCommand = cmdParts[0].split("/").pop() || "";
+
+		if (mainCommand === "source" || mainCommand === "python") {
+			return result;
+		}
+
+		for (const pattern of SECURITY_RULES.DANGEROUS_PATTERNS) {
+			if (pattern.test(command)) {
+				result.isValid = false;
+				result.severity = "CRITICAL";
+				result.violations.push(`Dangerous pattern detected: ${pattern.source}`);
+			}
+		}
+
+		if (SECURITY_RULES.CRITICAL_COMMANDS.includes(mainCommand)) {
+			result.isValid = false;
+			result.severity = "CRITICAL";
+			result.violations.push(`Critical dangerous command: ${mainCommand}`);
+		}
+
+		if (SECURITY_RULES.PRIVILEGE_COMMANDS.includes(mainCommand)) {
+			result.isValid = false;
+			result.severity = "HIGH";
+			result.violations.push(`Privilege escalation command: ${mainCommand}`);
+		}
+
+		if (SECURITY_RULES.NETWORK_COMMANDS.includes(mainCommand)) {
+			result.isValid = false;
+			result.severity = "HIGH";
+			result.violations.push(`Network/remote access command: ${mainCommand}`);
+		}
+
+		if (SECURITY_RULES.SYSTEM_COMMANDS.includes(mainCommand)) {
+			result.isValid = false;
+			result.severity = "HIGH";
+			result.violations.push(`System manipulation command: ${mainCommand}`);
+		}
+
+		if (/rm\s+.*-rf\s/.test(command)) {
+			const isRmRfSafe = this.isRmRfCommandSafe(command);
+			if (!isRmRfSafe) {
+				result.isValid = false;
+				result.severity = "CRITICAL";
+				result.violations.push("rm -rf command targeting unsafe path");
+			}
+		}
+
+		if (SAFE_COMMANDS.includes(mainCommand) && result.violations.length === 0) {
+			return result;
+		}
+
+		for (const path of SECURITY_RULES.PROTECTED_PATHS) {
+			if (command.includes(path)) {
+				if (
+					path === "/dev/" &&
+					(command.includes("/dev/null") ||
+						command.includes("/dev/stderr") ||
+						command.includes("/dev/stdout"))
+				) {
+					continue;
+				}
+
+				const cmdStart = command.trim();
+				let isSafeExecutable = false;
+				for (const safePath of SECURITY_RULES.SAFE_EXECUTABLE_PATHS) {
+					if (cmdStart.startsWith(safePath)) {
+						isSafeExecutable = true;
+						break;
+					}
+				}
+
+				const pathIndex = command.indexOf(path);
+				const beforePath = command.substring(0, pathIndex);
+				const redirectBeforePath = />\s*$/.test(beforePath.trim());
+
+				if (!isSafeExecutable && redirectBeforePath) {
+					result.isValid = false;
+					result.severity = "HIGH";
+					result.violations.push(
+						`Dangerous operation on protected path: ${path}`,
+					);
+				}
+			}
+		}
+
+		return result;
+	}
+
+	splitCommandChain(command: string): string[] {
+		const commands: string[] = [];
+		let current = "";
+		let inQuotes = false;
+		let quoteChar = "";
+
+		for (let i = 0; i < command.length; i++) {
+			const char = command[i];
+			const nextChar = command[i + 1];
+
+			if ((char === '"' || char === "'") && !inQuotes) {
+				inQuotes = true;
+				quoteChar = char;
+				current += char;
+			} else if (char === quoteChar && inQuotes) {
+				inQuotes = false;
+				quoteChar = "";
+				current += char;
+			} else if (inQuotes) {
+				current += char;
+			} else if (char === "&" && nextChar === "&") {
+				commands.push(current.trim());
+				current = "";
+				i++;
+			} else if (char === "|" && nextChar === "|") {
+				commands.push(current.trim());
+				current = "";
+				i++;
+			} else if (char === ";") {
+				commands.push(current.trim());
+				current = "";
+			} else {
+				current += char;
+			}
+		}
+
+		if (current.trim()) {
+			commands.push(current.trim());
+		}
+
+		return commands.filter((cmd) => cmd.length > 0);
+	}
+
+	isRmRfCommandSafe(command: string): boolean {
+		const rmRfMatch = command.match(/rm\s+.*-rf\s+([^\s;&|]+)/);
+		if (!rmRfMatch) {
+			return false;
+		}
+
+		const targetPath = rmRfMatch[1];
+
+		if (targetPath === "/" || targetPath.endsWith("/")) {
+			return false;
+		}
+
+		for (const safePath of SECURITY_RULES.SAFE_RM_PATHS) {
+			if (targetPath.startsWith(safePath)) {
+				return true;
+			}
+		}
+
+		if (!targetPath.startsWith("/")) {
+			return true;
+		}
+
+		return false;
+	}
+}

package/claude-code-config/scripts/command-validator/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		globals: true,
+	},
+});

package/claude-code-config/scripts/statusline/CLAUDE.md

@@ -0,0 +1,178 @@
+# Claude Code Statusline - Project Memory
+
+## Overview
+
+Clean, type-safe statusline implementation for Claude Code using Bun + TypeScript. Displays real-time session information, git status, context usage, and Claude API rate limits.
+
+## Project Setup & Configuration
+
+### Dependencies
+- **Bun**: Runtime (uses `$` for shell commands)
+- **@biomejs/biome**: Linting & formatting
+- **TypeScript**: Type safety
+
+No external npm packages required - pure Bun APIs.
+
+### Configuration in Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bun /Users/melvynx/.claude/scripts/statusline/src/index.ts",
+    "padding": 0
+  }
+}
+```
+
+### Authentication
+
+OAuth token stored in macOS Keychain:
+- **Service**: `Claude Code-credentials`
+- **Format**: JSON with `claudeAiOauth.accessToken`
+- **Token type**: `sk-ant-oat01-...` (OAuth token, not API key)
+- **Access**: `security find-generic-password -s "Claude Code-credentials" -w`
+
+## Architecture
+
+### Modular Design
+
+The project follows a clean architecture with separated concerns:
+
+```
+src/
+├── index.ts              # Main entry - orchestrates all components
+└── lib/
+    ├── types.ts          # TypeScript interfaces (HookInput)
+    ├── git.ts            # Git operations (branch, changes)
+    ├── context.ts        # Transcript parsing & context calculation
+    ├── usage-limits.ts   # Claude OAuth API integration
+    └── formatters.ts     # Display utilities & colors
+```
+
+### Data Flow
+
+```
+Claude Code Hook → stdin JSON → index.ts
+                                    ↓
+                    ┌───────────────┴───────────────┐
+                    ↓                               ↓
+            [Get Git Status]            [Get Context Data]
+                    ↓                               ↓
+            [Format Branch]             [Get Usage Limits]
+                    ↓                               ↓
+                    └───────────────┬───────────────┘
+                                    ↓
+                            [Build Output Lines]
+                                    ↓
+                            stdout (2 lines)
+```
+
+## Component Specifications
+
+### Context Calculation (`lib/context.ts`)
+- **Purpose**: Calculate token usage from Claude Code transcript files
+- **Algorithm**: Parses `.jsonl` transcript, finds most recent main-chain entry
+- **Tokens counted**: `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`
+- **Excludes**: Sidechain entries (agent calls), API error messages
+- **Output**: `{ tokens: number, percentage: number }` (0-100% of 200k context)
+
+### Usage Limits (`lib/usage-limits.ts`)
+- **Purpose**: Fetch Claude API rate limits from OAuth endpoint
+- **Auth**: Retrieves OAuth token from macOS Keychain (`Claude Code-credentials`)
+- **API**: `https://api.anthropic.com/api/oauth/usage`
+- **Data**: Five-hour window utilization + reset time
+- **Error handling**: Fails silently, returns null on errors
+
+### Git Status (`lib/git.ts`)
+- **Purpose**: Show current branch and uncommitted changes
+- **Detection**: Checks both staged and unstaged changes
+- **Output**: Branch name + line additions/deletions
+- **Display**: `main* (+123 -45)` with color coding
+
+### Formatters (`lib/formatters.ts`)
+- **Colors**: ANSI color codes for terminal output
+- **Token display**: `62.5K`, `1.2M` format
+- **Time formatting**: `3h21m`, `45m` for countdowns
+- **Reset time**: Calculates difference between API reset time and now
+
+## Output Specification
+
+### Line 1: Session Info
+```
+main* (+123 -45) | ~/.claude | Sonnet 4.5
+```
+
+### Line 2: Metrics
+```
+$0.17 (6m) | 62.5K tokens | 31% | 15% (3h27m)
+```
+
+**Components:**
+- `$0.17` - Session cost (USD)
+- `(6m)` - Session duration
+- `62.5K tokens` - Context tokens used (from transcript)
+- `31%` - Context percentage (tokens / 200k)
+- `15%` - Five-hour usage (from Claude API)
+- `(3h27m)` - Time until rate limit resets
+
+## Development
+
+### Testing
+
+```bash
+# Run test with fixture
+bun run test
+
+# Use custom fixture
+bun run test fixtures/custom.json
+
+# Manual test
+echo '{ ... }' | bun run start
+```
+
+### Code Conventions
+
+- **ALWAYS** use camelCase for variables and functions
+- Use TypeScript strict mode
+- Follow Biome formatting rules
+
+### Error Handling & Performance
+
+**Error Handling** - All components fail silently:
+- Missing transcript → 0 tokens, 0%
+- API failure → No usage limits shown
+- Git errors → "no-git" branch
+- Keychain access denied → No usage limits
+
+This ensures statusline never crashes Claude Code.
+
+**Performance Benchmarks:**
+- Context calculation: ~10-50ms (depends on transcript size)
+- API call: ~100-300ms (cached by Claude API)
+- Git operations: ~20-50ms
+- Total: < 500ms typical
+
+## Maintenance Guide
+
+### Adding New Metrics
+
+1. Add interface to `lib/types.ts`
+2. Create fetcher in `lib/*.ts`
+3. Import in `index.ts`
+4. Add to `buildSecondLine()`
+
+### Modifying Display
+
+- Colors: Edit `lib/formatters.ts` colors constant
+- Layout: Modify `buildFirstLine()` / `buildSecondLine()`
+- Formatting: Add functions to `lib/formatters.ts`
+
+## Known Limitations
+
+- macOS only (uses Keychain)
+- Requires `git` CLI for git status
+- Requires Claude Code OAuth (not API key)
+- Transcript must be accessible (permissions)

package/claude-code-config/scripts/statusline/README.md

@@ -0,0 +1,105 @@
+# Claude Code Statusline
+
+Clean, modular statusline for Claude Code with TypeScript + Bun.
+
+## Features
+
+- 🌿 Git branch with changes (+added -deleted)
+- 💰 Session cost and duration
+- 🧩 Context tokens used
+- 📊 Context percentage (0-100%)
+- ⏱️ Five-hour usage limit with reset time
+
+## Structure
+
+```
+src/
+├── index.ts              # Main entry point
+└── lib/
+    ├── types.ts          # TypeScript interfaces
+    ├── git.ts            # Git status
+    ├── context.ts        # Context calculation from transcript
+    ├── usage-limits.ts   # Claude API usage limits
+    └── formatters.ts     # Formatting utilities
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run the statusline (needs stdin JSON)
+echo '{ ... }' | bun run start
+
+# View today's spending
+bun run spend:today
+
+# View this month's spending
+bun run spend:month
+
+# Format code
+bun run format
+
+# Lint code
+bun run lint
+```
+
+## Spend Tracking
+
+The statusline automatically saves session data to `data/spend.json`. You can view your spending with:
+
+```bash
+# Today's sessions and cost
+bun run spend:today
+
+# This month's sessions grouped by date
+bun run spend:month
+```
+
+Each session tracks:
+- Cost (USD)
+- Duration
+- Lines added/removed
+- Working directory
+
+## Usage in Claude Code
+
+Update your `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bun /Users/melvynx/.claude/scripts/statusline/src/index.ts",
+    "padding": 0
+  }
+}
+```
+
+## Testing
+
+```bash
+echo '{
+  "session_id": "test",
+  "transcript_path": "/path/to/transcript.jsonl",
+  "cwd": "/path",
+  "model": {
+    "id": "claude-sonnet-4-5",
+    "display_name": "Sonnet 4.5"
+  },
+  "workspace": {
+    "current_dir": "/path",
+    "project_dir": "/path"
+  },
+  "version": "2.0.31",
+  "output_style": { "name": "default" },
+  "cost": {
+    "total_cost_usd": 0.15,
+    "total_duration_ms": 300000,
+    "total_api_duration_ms": 200000,
+    "total_lines_added": 100,
+    "total_lines_removed": 50
+  }
+}' | bun run start
+```

package/claude-code-config/scripts/statusline/biome.json

@@ -0,0 +1,34 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.3.2/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": false
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}

package/claude-code-config/scripts/statusline/fixtures/test-input.json

@@ -0,0 +1,25 @@
+{
+	"session_id": "06a7b019-03f8-4083-a9db-410d95cb01e6",
+	"transcript_path": "/Users/melvynx/.claude/projects/-Users-melvynx--claude/06a7b019-03f8-4083-a9db-410d95cb01e6.jsonl",
+	"cwd": "/Users/melvynx/.claude",
+	"model": {
+		"id": "claude-sonnet-4-5-20250929",
+		"display_name": "Sonnet 4.5"
+	},
+	"workspace": {
+		"current_dir": "/Users/melvynx/.claude",
+		"project_dir": "/Users/melvynx/.claude"
+	},
+	"version": "2.0.31",
+	"output_style": {
+		"name": "default"
+	},
+	"cost": {
+		"total_cost_usd": 0.17468000000000003,
+		"total_duration_ms": 385160,
+		"total_api_duration_ms": 252694,
+		"total_lines_added": 185,
+		"total_lines_removed": 75
+	},
+	"exceeds_200k_tokens": false
+}