forgehive 0.6.0

package/README.md

@@ -0,0 +1,631 @@
+<p align="center">
+  <img src="logo/ForgeHiveAI_final_logo.png" width="160" alt="ForgeHiveAI Logo">
+</p>
+
+<h1 align="center">
+  <strong style="color:#f97316">Forge</strong><span>Hive</span><sup>AI</sup>
+</h1>
+
+<p align="center">
+  Context-aware AI development environment — one binary, your stack.<br>
+  <code>fh init</code> &nbsp;·&nbsp; <code>fh confirm</code> &nbsp;·&nbsp; Claude knows your codebase.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node.js ≥ 18">
+  <img src="https://img.shields.io/badge/typescript-5.8-blue" alt="TypeScript">
+  <img src="https://img.shields.io/badge/tests-217%20passing-success" alt="217 tests">
+  <img src="https://img.shields.io/badge/bundle-205KB-lightgrey" alt="205KB bundle">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
+</p>
+
+---
+
+## What is ForgeHiveAI?
+
+**forgehive** (`fh`) is a CLI that permanently equips Claude Code with your codebase context — and actively checks generated code for security issues.
+
+Claude loses all project knowledge between sessions. forgehive solves this by writing a `.forgehive/` directory into your target project that Claude reads automatically at every session start.
+
+**Core capabilities:**
+
+- **Stack Scanner** — detects tech stack, dependencies, and project structure automatically
+- **Persistent Memory** — context and session notes survive every restart
+- **Party Mode** — specialized agent sets, each agent in its own isolated git worktree
+- **MCP Wiring** — preconfigured connectors for 10 services, API keys stored securely in `~/.forgehive/`
+- **Security Suite** — SAST, secret scanner, CVE check, CISO reports (GDPR/SOC2/HIPAA)
+- **AGENTS.md** — cross-tool standard (Cursor, Copilot, Gemini CLI, Codex, Windsurf)
+
+**Design principle:** writes exclusively to `.forgehive/` in the target project. No globbing outside the project root. Never overwrites files it didn't create.
+
+---
+
+## Status: Early Alpha (v0.6)
+
+This is an early release. The codebase is clean — TypeScript, 217 passing tests, single bundle — but several features have not yet been tested against a real project.
+
+**Stable — use with confidence:**
+
+| Feature | State |
+|---|---|
+| `fh init` — stack scan + `.forgehive/` setup | stable |
+| `fh confirm` / `fh rollback` | stable |
+| CLAUDE.md block merge (idempotent, 3 cases) | stable |
+| `fh security scan` — secrets + SAST | stable |
+| `fh security deps` — CVE check | stable |
+| `fh security report` — compliance reports | stable |
+| `fh memory` — show, clean, export, snapshot | stable |
+| MCP credential store (`fh mcp auth`) | stable |
+
+**Experimental — works in tests, not yet live-validated:**
+
+| Feature | State |
+|---|---|
+| `fh party run` — multi-agent worktree sessions | experimental |
+| `fh skills regen` — AI-assisted skill generation | experimental |
+| `fh cost` — session cost parsing from `~/.claude/` | experimental |
+| Guardrails bash hook in live Claude Code sessions | experimental |
+
+If you run into issues, please open an issue on GitHub. The most valuable feedback right now is a real `fh init` run on your project — does Claude actually pick up the context?
+
+---
+
+## Prerequisites
+
+- **Node.js ≥ 18** — check with `node --version`
+- **Claude Code** installed and configured (`claude` CLI available)
+- **git** — required for Party Mode worktrees and the guardrails hook
+
+---
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install -g forgehive
+```
+
+This makes both `fh` and `forgehive` available globally.
+
+### From source (for development)
+
+```bash
+git clone https://github.com/matharnica/forgehive
+cd forgehive
+npm install
+npm run build      # compiles to dist/cli.js (~205 KB)
+npm link           # makes 'fh' available globally
+```
+
+Verify the installation:
+
+```bash
+fh --version       # should print 0.6.0
+fh --help          # lists all available commands
+```
+
+---
+
+## Quick Start
+
+### Step 1: Initialize your project
+
+Navigate to any project you want Claude to understand, then run:
+
+```bash
+cd my-project
+fh init
+```
+
+`fh init` does the following in order:
+1. Scans your project — detects language, framework, dependencies, directory structure
+2. Creates `.forgehive/` with the full harness (capabilities, memory, skills, permissions)
+3. Merges a context block into `CLAUDE.md` (creates it if it doesn't exist, never overwrites existing content)
+4. Writes `AGENTS.md` to the project root (cross-tool agent standard)
+5. Installs 16 expert skill files into `.forgehive/skills/expert/`
+
+### Step 2: Confirm the detected stack
+
+```bash
+fh confirm
+```
+
+This changes `capabilities.yaml` from `status: draft` to `status: confirmed`. Claude won't use the context as authoritative until it's confirmed — this gives you a chance to review what was detected before committing to it.
+
+After confirmation, open a new Claude Code session in the project. Claude will automatically read `.forgehive/` and know your stack, constraints, and memory.
+
+### Step 3: Run a security audit (recommended)
+
+```bash
+fh security scan          # finds secrets and SAST vulnerabilities
+fh security deps          # checks npm dependencies for known CVEs
+fh security report gdpr   # generates a CISO-ready compliance report
+```
+
+---
+
+## Commands Reference
+
+### Setup & Lifecycle
+
+| Command | Description |
+|---|---|
+| `fh init` | Scan project, create `.forgehive/`, merge CLAUDE.md block, write AGENTS.md |
+| `fh confirm` | Confirm `capabilities.yaml` — activates context for Claude |
+| `fh rollback` | Remove `.forgehive/` and the CLAUDE.md block cleanly |
+| `fh status` | Show current project status, drift warning if scan is outdated |
+
+**When to use `fh rollback`:** If you want to remove forgehive from a project entirely. It removes exactly the block it inserted into CLAUDE.md (nothing else) and deletes `.forgehive/`.
+
+---
+
+### Scan
+
+| Command | Description |
+|---|---|
+| `fh scan --update` | Re-scan the project (run after adding new dependencies) |
+| `fh scan --check` | Hash check — is the snapshot still current? |
+
+The scan stores a hash of the project state. `fh scan --check` compares the current state against the stored hash and warns if dependencies or structure have changed significantly since the last scan.
+
+---
+
+### Status & Cost Tracking
+
+| Command | Description |
+|---|---|
+| `fh status` | Show status of `.forgehive/`, confirmation state, last scan date |
+| `fh cost` | Show Claude session costs from `~/.claude/` (all time) |
+| `fh cost today` | Costs for today only |
+| `fh cost week` | Costs for the current week |
+| `fh cost --limit 20` | Set a hard spend limit of $20 |
+| `fh cost --alert 15` | Set an alert threshold at $15 |
+| `fh cost --limit 20 --alert 15` | Set both at once |
+
+**How spend limits work:** Once set, `fh cost` checks your current spend against the configured limits every time it runs. When the alert threshold is reached, it prints a warning. When the hard limit is reached, it exits with a non-zero code — you can use this in CI or hooks to stop work automatically.
+
+---
+
+### Security Suite
+
+The security suite consists of five commands:
+
+#### `fh security scan`
+
+```bash
+fh security scan
+```
+
+Runs two scanners in sequence:
+
+1. **Secret Scanner** — searches all source files for exposed credentials using 8 regex patterns:
+   - Anthropic API keys (`sk-ant-...`)
+   - OpenAI API keys (`sk-...` non-Anthropic)
+   - GitHub tokens (`ghp_...`)
+   - AWS Access Key IDs (`AKIA...`)
+   - Slack bot tokens (`xoxb-...`)
+   - PEM private keys (`-----BEGIN ... PRIVATE KEY`)
+   - Generic password assignments (`password = "..."`)
+   - Generic token assignments (`token = "..."`)
+
+2. **SAST Scanner** — static analysis for 6 vulnerability classes:
+   - SQL Injection (HIGH)
+   - XSS / unescaped output (HIGH)
+   - `eval()` usage (HIGH)
+   - Path traversal (`../` in file operations) (MEDIUM)
+   - Weak random numbers (`Math.random()` in security contexts) (LOW)
+   - Hardcoded credentials in source (CRITICAL)
+
+**Exit codes:** exits 1 if CRITICAL or HIGH findings exist — safe to use in CI pipelines.
+
+Secrets are **never** stored verbatim. Findings show only the first 6 characters followed by `***`.
+
+#### `fh security deps`
+
+```bash
+fh security deps
+```
+
+Runs `npm audit` and formats the output. Shows vulnerable packages grouped by severity (critical, high, moderate, low) with CVE identifiers and fix recommendations.
+
+#### `fh security report`
+
+```bash
+fh security report          # no compliance framework
+fh security report gdpr     # GDPR-specific checks and recommendations
+fh security report soc2     # SOC 2 Type II relevant controls
+fh security report hipaa    # HIPAA technical safeguard checklist
+```
+
+Generates a Markdown CISO report at `.forgehive/security-report.md`. The report includes:
+- Overall risk score (CLEAN / LOW / MEDIUM / HIGH / CRITICAL)
+- Secret scan results
+- SAST findings with file paths and line numbers
+- Dependency vulnerabilities
+- Compliance-mode-specific recommendations and gaps
+- Timestamp and project metadata
+
+#### `fh security audit`
+
+```bash
+fh security audit
+```
+
+Displays the audit trail — every `fh security` command execution is logged in JSONL format to `.forgehive/audit.log`. Shows timestamp, command, user, and outcome. Useful for compliance documentation.
+
+#### `fh security permissions`
+
+```bash
+fh security permissions
+```
+
+Shows `permissions.yaml` — the file access control list for each agent. Each agent (Nora, Eli, Remy, Suki, Viktor, Kai, Sam, Vera) has explicit `read`, `write`, and `deny` lists. This prevents agents from accidentally touching files outside their scope.
+
+---
+
+### Memory
+
+Memory files live in `.forgehive/memory/` and are read by Claude at session start via the CLAUDE.md block.
+
+| Command | Description |
+|---|---|
+| `fh memory` | Show all memory file contents |
+| `fh memory show` | Same as above |
+| `fh memory clean` | Delete state files older than 30 days |
+| `fh memory export` | Export all memory to a single Markdown file (stdout) |
+| `fh memory export ./backup.md` | Export to a specific path |
+| `fh memory prune 60` | List memory files not updated in 60 days |
+| `fh memory prune 60 --remove` | Same, but delete them |
+| `fh memory snapshot export` | Export memory as a JSON bundle (for team sharing) |
+| `fh memory snapshot export ./team-memory.json` | Export to path |
+| `fh memory snapshot import ./team-memory.json` | Import bundle (skips existing files) |
+| `fh memory adr list` | List all Architecture Decision Records |
+| `fh memory adr "Use Postgres over MongoDB"` | Create a new ADR |
+
+**Memory files created by `fh init`:**
+
+| File | Purpose |
+|---|---|
+| `MEMORY.md` | Index file — lists all other memory files |
+| `project.md` | Project context, open decisions, goals |
+| `feedback.md` | Corrections and confirmed approaches from Claude sessions |
+| `stack.md` | Stack details the scanner can't detect (auth patterns, deploy targets) |
+| `adrs/` | Architecture Decision Records |
+
+**Team snapshots:** `fh memory snapshot export` bundles all memory files into a single JSON file you can commit or share. `fh memory snapshot import` imports it idempotently — existing files are never overwritten, only new files are added.
+
+---
+
+### Party Mode
+
+Party Mode runs specialized agent sets in parallel, each in an isolated git worktree.
+
+```bash
+fh party                    # show current party configuration
+fh party --set build        # set default party to 'build'
+fh party run                # start the default party
+fh party run security       # start the security party specifically
+fh party status             # show active party session
+fh party cleanup            # remove finished worktrees
+```
+
+**Available party sets:**
+
+| Set | Agents | Claude Code trigger |
+|---|---|---|
+| `build` | Viktor + Kai + Sam | `/party` |
+| `design` | Suki + Viktor | `/design-party` |
+| `review` | Kai + Sam + Eli | `/review-party` |
+| `security` | Vera + Sam | `/security-party` |
+| `full` | All 8 agents | `/full-party` |
+
+**Model mapping** — assign specific Claude models per agent:
+
+```bash
+fh party --model-map "viktor:claude-opus-4-7,kai:claude-sonnet-4-6,sam:claude-haiku-4-5"
+```
+
+**How isolation works:** `fh party run` creates one git worktree per agent under `.forgehive/worktrees/<agent-name>/`. Each agent works in its own branch and filesystem copy. Worktrees are cleaned up with `fh party cleanup` or automatically when the session ends cleanly.
+
+---
+
+### MCP (Model Context Protocol)
+
+#### Quick wiring for common services
+
+```bash
+fh wire linear       # configure Linear MCP server in .mcp.json
+fh wire slack        # configure Slack MCP server
+fh wire github       # configure GitHub MCP server
+```
+
+Supported services for `fh wire`: `linear`, `slack`, `github`, `sentry`, `notion`, `postgres`, `jira`, `pagerduty`, `datadog`, `figma`
+
+This writes the correct MCP server configuration to `.mcp.json` in the project root. Claude Code picks up `.mcp.json` automatically.
+
+#### Credential management
+
+API keys are stored encrypted at `~/.forgehive/credentials.json` (chmod 600, user-only access):
+
+```bash
+fh mcp auth add github GITHUB_TOKEN=ghp_yourtoken
+fh mcp auth add linear LINEAR_API_KEY=lin_api_key
+fh mcp auth add slack SLACK_BOT_TOKEN=xoxb-... SLACK_TEAM_ID=T123
+
+fh mcp auth list             # show which services have stored credentials
+fh mcp auth remove github    # delete credentials for a service
+```
+
+#### Registry search and install
+
+```bash
+fh mcp search "database"              # search Smithery registry
+fh mcp add @modelcontextprotocol/server-postgres
+fh mcp add @smithery/some-server --env API_KEY SECRET_KEY
+```
+
+**Trust Layer:** `fh mcp add` checks the npm scope before installing. Trusted scopes:
+- `@modelcontextprotocol` — official MCP servers
+- `@anthropic` — Anthropic packages
+- `@smithery` — Smithery registry
+- `@github` — GitHub packages
+- `@microsoft` — Microsoft packages
+
+Unscoped packages or unknown scopes trigger a warning before installation proceeds.
+
+---
+
+### Skills
+
+Skills are Markdown instruction files that Claude reads when you reference them in a session.
+
+```bash
+fh skills list              # show all available skills
+fh skills regen             # regenerate skills from templates (AI-assisted)
+fh skills pull <git-url>    # pull expert skills from a team git repo
+```
+
+**Pulling team skills:**
+
+```bash
+fh skills pull https://github.com/my-team/ai-skills.git
+```
+
+Clones the repo with `--depth=1`, copies all `.md` files from the `skills/expert/` subdirectory (or root if no `skills/expert/` exists) into `.forgehive/skills/expert/`. Existing files are not overwritten.
+
+**Expert Skills installed by `fh init` (16 files):**
+
+| Skill | Coverage |
+|---|---|
+| `typescript-patterns` | Type-safe patterns, generics, discriminated unions |
+| `testing-strategies` | TDD, test design, coverage strategies |
+| `api-design` | REST, versioning, error responses |
+| `git-conventions` | Commit messages, branching, PR hygiene |
+| `error-handling` | Error hierarchies, recovery patterns |
+| `security-checklist` | Pre-deploy security review |
+| `performance-patterns` | Profiling, caching, async patterns |
+| `code-review` | Review checklist and feedback patterns |
+| `clean-architecture` | Dependency rules, layering, boundaries |
+| `database-patterns` | Query optimization, migrations, indexing |
+| `monorepo-patterns` | Workspace setup, shared packages, tooling |
+| `observability` | Logging, tracing, metrics |
+| `owasp-top10` | A01–A10 with TypeScript examples |
+| `auth-security` | bcrypt, JWT, session security, MFA |
+| `gdpr-compliance` | PII classification, consent, right to erasure |
+| `security-checklist` | SAST integration, secret management |
+
+---
+
+## What `fh init` Creates
+
+```
+my-project/
+  .forgehive/
+    capabilities.yaml          ← detected stack (status: draft → confirmed)
+    scan-result.yaml           ← raw scanner output
+    .scan-hash                 ← checksum for fh scan --check
+    harness/
+      architecture.md          ← codebase overview for Claude
+      constraints.yaml         ← max_lines, require_tests, style rules
+      permissions.yaml         ← per-agent file access control (read/write/deny)
+    memory/
+      MEMORY.md                ← index of all memory files
+      project.md               ← project context and open decisions
+      feedback.md              ← corrections + confirmed approaches
+      stack.md                 ← stack details the scanner can't detect
+      adrs/                    ← architecture decision records
+    skills/
+      generated/               ← AI-generated skills (fh skills regen)
+      expert/                  ← 16 preinstalled expert skills
+      workflows/               ← MCP workflow skills
+    worktrees/                 ← isolated git worktrees (fh party run)
+    audit.log                  ← JSONL audit trail (fh security commands)
+    cost-config.yaml           ← spend limits (fh cost --limit/--alert)
+  AGENTS.md                    ← cross-tool agent standard
+  CLAUDE.md                    ← forgehive block inserted, rest preserved
+```
+
+---
+
+## CLAUDE.md Merge Behavior
+
+`fh init` **never overwrites** CLAUDE.md. Three cases:
+
+| State | Action |
+|---|---|
+| No CLAUDE.md exists | Create new file with forgehive block |
+| CLAUDE.md exists, no forgehive block | Append block at the end |
+| CLAUDE.md exists, block already present | Replace only the block |
+
+The block is delimited by `<!-- forgehive:start -->` and `<!-- forgehive:end -->` markers. `fh rollback` removes exactly this block and nothing else.
+
+---
+
+## AGENTS.md — Cross-Tool Standard
+
+`fh init` generates `AGENTS.md` in the project root following the Linux Foundation / AAIF standard. This file is read automatically by:
+
+- **Cursor** — agent behavior configuration
+- **GitHub Copilot** — workspace instructions
+- **Gemini CLI** — project context
+- **OpenAI Codex** — coding guidelines
+- **Windsurf** — agent policies
+
+You only maintain one file; all tools benefit.
+
+---
+
+## Agents
+
+| Agent | Role | Party Sets |
+|---|---|---|
+| **Nora** | Senior Research Analyst | full |
+| **Eli** | Technical Writer | review, full |
+| **Remy** | Creative Strategist | full |
+| **Suki** | UX Designer | design, full |
+| **Viktor** | System Architect | build, design, full |
+| **Kai** | Senior Engineer | build, review, full |
+| **Sam** | QA & Test Architect | build, review, security, full |
+| **Vera** | Security Analyst (OWASP, GDPR, Auth) | security, full |
+
+---
+
+## Guardrails
+
+`fh init` installs a Bash hook at `.claude/settings.json` that blocks:
+
+**Secrets in staged git files:**
+- Anthropic API keys (`sk-ant-...`)
+- GitHub tokens (`ghp_...`)
+- AWS Access Key IDs (`AKIA...`)
+- Slack bot tokens (`xoxb-...`)
+- PEM private keys
+
+**Dangerous commands:**
+- `git push --force`
+- `git reset --hard`
+- `rm -rf /`
+- `DROP TABLE`
+
+The hook fires on every bash command execution in Claude Code and exits 1 if a match is found.
+
+---
+
+## Typical Workflows
+
+### New project setup
+
+```bash
+cd my-project
+fh init
+fh confirm
+# Open Claude Code → Claude now has full context
+```
+
+### After adding new dependencies
+
+```bash
+npm install new-package
+fh scan --update    # re-scan to pick up new dependency
+fh confirm          # re-confirm the updated capabilities
+```
+
+### Weekly security check
+
+```bash
+fh security scan            # check for secrets and SAST issues
+fh security deps            # check for new CVEs in dependencies
+fh security report gdpr     # update compliance report
+```
+
+### Sharing context with the team
+
+```bash
+fh memory snapshot export ./team-context.json
+git add team-context.json
+git commit -m "chore: update shared forgehive context"
+
+# On another machine:
+fh memory snapshot import ./team-context.json
+```
+
+### Starting a multi-agent build session
+
+```bash
+fh party --set build
+fh party run
+# → Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
+# → Each Claude Code session opens in its own isolated worktree
+
+fh party status     # check what's running
+fh party cleanup    # clean up after the session
+```
+
+### Connecting Linear and GitHub
+
+```bash
+fh wire linear
+fh mcp auth add linear LINEAR_API_KEY=lin_api_...
+
+fh wire github
+fh mcp auth add github GITHUB_TOKEN=ghp_...
+
+# Credentials stored at ~/.forgehive/credentials.json (chmod 600)
+fh mcp auth list    # verify both services are stored
+```
+
+---
+
+## Configuration Files
+
+### `.forgehive/capabilities.yaml`
+
+Auto-generated by `fh init`, confirmed by `fh confirm`. Contains:
+- `status`: `draft` | `confirmed`
+- Detected language, framework, package manager
+- Key directories and entry points
+- Test configuration
+
+Edit this file manually to correct anything the scanner got wrong, then run `fh confirm` again.
+
+### `.forgehive/harness/constraints.yaml`
+
+Defines Claude's behavior rules for this project:
+- `max_lines_per_file`: soft limit for file size
+- `require_tests`: whether to require tests for new code
+- `test_framework`: which test runner to use
+- Style and formatting preferences
+
+### `.forgehive/harness/permissions.yaml`
+
+Per-agent file access control. Default permissions are conservative — agents can only read/write files relevant to their role. Edit to expand or restrict access.
+
+### `~/.forgehive/credentials.json`
+
+Global credential store (chmod 600). Managed exclusively via `fh mcp auth` commands — do not edit manually.
+
+---
+
+## Tech Stack
+
+| | |
+|---|---|
+| Runtime | Node.js ≥ 18, ESM |
+| Language | TypeScript |
+| Build | esbuild → `dist/cli.js` (~205 KB, single bundle) |
+| Type check | `tsc --noEmit` |
+| Tests | `node:test` (native) + tsx ESM loader, 217 tests |
+| Dependencies | `js-yaml` (sole runtime dependency) |
+
+```bash
+npm run build       # esbuild → dist/cli.js
+npm run typecheck   # tsc --noEmit
+npm test            # node --import tsx/esm --test test/*.test.ts
+```
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};