forgehive 0.7.7 → 0.7.9

package/README.md

@@ -16,7 +16,7 @@
   <img src="https://img.shields.io/badge/typescript-5.8-blue" alt="TypeScript">
   <img src="https://img.shields.io/badge/tests-273%20passing-success" alt="273 tests">
   <img src="https://img.shields.io/badge/bundle-259KB-lightgrey" alt="259KB bundle">
-  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
+  <img src="https://img.shields.io/badge/license-Elastic%202.0-orange" alt="Elastic License 2.0">
 </p>
 
 ---
@@ -45,9 +45,9 @@ Claude loses all project knowledge between sessions. forgehive solves this by wr
 
 ---
 
-## Status: v0.7.5 — Stable
+## Status: v0.7.7 — Stable
 
-273 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.
+297 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.
 
 **Stable — use with confidence:**
 
@@ -125,7 +125,7 @@ npm link           # makes 'fh' available globally
 Verify the installation:
 
 ```bash
-fh --version       # should print 0.7.5
+fh --version       # should print 0.7.7
 fh --help          # lists all available commands
 ```
 
@@ -890,6 +890,8 @@ npm test            # node --import tsx/esm --test test/*.test.ts
 
 | Version | What's new |
 |---|---|
+| **0.7.7** | User Guide (`docs/user-guide.md`) included in npm package; Documentation table in README |
+| **0.7.6** | YAML shape fix in `fh docs user`; frontmatter regex fix; 8 new tests for HIGH RISK paths |
 | **0.7.5** | `fh --version` reads from `package.json` (no longer hardcoded) |
 | **0.7.4** | Party slash commands installed by `fh init` (`/party`, `/review-party`, `/design-party`, `/full-party`, `/security-party`) |
 | **0.7.3** | User Docs generation (`fh docs user`, `fh docs api`, `fh docs list`) |
@@ -901,4 +903,4 @@ npm test            # node --import tsx/esm --test test/*.test.ts
 
 ## License
 
-MIT
+Elastic License 2.0 (ELv2) — kostenlos selbst hosten für den eigenen Betrieb. Weiterverkauf als Managed Service nicht erlaubt.

package/dist/cli.js

@@ -2753,6 +2753,8 @@ var init_harness = __esm({
 init_js_yaml();
 import fs31 from "node:fs";
 import path32 from "node:path";
+import { spawnSync as spawnSync12 } from "node:child_process";
+import { createInterface } from "node:readline";
 
 // src/scanner.ts
 import fs from "node:fs";
@@ -6550,7 +6552,7 @@ function generateUserGuide(projectRoot2, forgehiveDir2) {
   lines.push("## Overview");
   lines.push("");
   if (memFiles["project.md"]) {
-    const content = memFiles["project.md"].replace(/^---[\s\S]*?---\n/, "").trim();
+    const content = memFiles["project.md"].replace(/^---[\s\S]*?---\n?/, "").trim();
     lines.push(content);
   } else {
     lines.push(`${projectName} is a ${lang ?? "software"} application.`);
@@ -6585,7 +6587,7 @@ function generateUserGuide(projectRoot2, forgehiveDir2) {
   }
   lines.push("```");
   lines.push("");
-  if (Array.isArray(entryPoints) && entryPoints.length > 0) {
+  if ((lang === "typescript" || lang === "javascript") && Array.isArray(entryPoints) && entryPoints.length > 0) {
     lines.push("## Getting Started");
     lines.push("");
     lines.push("```bash");
@@ -6596,7 +6598,7 @@ function generateUserGuide(projectRoot2, forgehiveDir2) {
   if (memFiles["stack.md"]) {
     lines.push("## Configuration");
     lines.push("");
-    const content = memFiles["stack.md"].replace(/^---[\s\S]*?---\n/, "").trim();
+    const content = memFiles["stack.md"].replace(/^---[\s\S]*?---\n?/, "").trim();
     lines.push(content);
     lines.push("");
   }
@@ -6682,7 +6684,7 @@ USAGE
   fh <command> [subcommand] [options]
 
 SETUP
-  fh init                          Set up forgehive in the current project
+  fh init [--yes]                  Set up forgehive in the current project
   fh confirm                       Activate capabilities (draft \u2192 confirmed)
   fh rollback                      Remove forgehive from the project
   fh status                        Show current project state
@@ -6759,41 +6761,77 @@ function loadClaudeMdBlock() {
   if (!fs31.existsSync(templatePath)) return "## forgehive\n\nSee .forgehive/ for configuration.";
   return fs31.readFileSync(templatePath, "utf8");
 }
-if (command === "init") {
-  const forgehiveDirExists = fs31.existsSync(forgehiveDir);
-  if (forgehiveDirExists && !rest.includes("--force")) {
-    console.log(`\u26A0 .forgehive/ existiert bereits in diesem Projekt.`);
-    console.log(`  Nutze 'fh init --force' um neu zu initialisieren (\xFCberschreibt capabilities.yaml).`);
-    console.log(`  Nutze 'fh scan --update' um nur den Scan zu aktualisieren.`);
-    process.exit(0);
+async function promptConfirm(question) {
+  if (!process.stdin.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      resolve(a === "y" || a === "yes" || a === "");
+    });
+  });
+}
+function buildCapabilitySummary(ids) {
+  if (ids.length === 0) return "  Erkannt: (keine Capabilities)";
+  const lines = [];
+  for (let i = 0; i < ids.length && lines.length < 4; i += 4) {
+    lines.push("  \u2022 " + ids.slice(i, i + 4).join(" \xB7 "));
   }
-  console.log("\u{1F50D} Analysiere Projekt...\n");
-  const scanResult = scan(projectRoot);
-  const tierCount = [1, 2, 3].map((t) => scanResult.signals.filter((s) => s.tier === t).length);
-  console.log(`  \u2713 ${tierCount[0]} Technologie-Signale erkannt`);
-  console.log(`  \u2713 ${tierCount[1]} Infrastruktur-Signale erkannt`);
-  console.log(`  \u2713 ${tierCount[2]} Kontext-Signale erkannt`);
-  console.log();
-  const capMap = mapSignalsToCapabilities(scanResult);
-  const block = loadClaudeMdBlock();
-  writeForgehiveDir(projectRoot, scanResult, capMap, block);
-  const hash = computeHash(projectRoot);
-  fs31.writeFileSync(path32.join(forgehiveDir, ".scan-hash"), hash, "utf8");
-  const runtimeDir = path32.join(
-    path32.dirname(new URL(import.meta.url).pathname),
-    "..",
-    "forgehive"
-  );
-  initForgehiveRuntime(forgehiveDir, runtimeDir);
-  console.log("\u2713 .forgehive/ eingerichtet");
-  console.log("\u2713 CLAUDE.md aktualisiert\n");
-  console.log("Erkannte Capabilities:");
-  for (const cap of capMap.confirmed) {
-    console.log(`  + ${cap.id} (aus ${cap.source})`);
-  }
-  console.log("\nN\xE4chster Schritt:");
-  console.log("  Pr\xFCfe .forgehive/capabilities.yaml und f\xFChre dann aus:");
-  console.log("  fh confirm\n");
+  return "  Erkannt:\n" + lines.join("\n");
+}
+if (command === "init") {
+  (async () => {
+    const gitCheck = spawnSync12("git", ["--version"], { stdio: "ignore" });
+    if (gitCheck.error || gitCheck.status !== 0) {
+      console.error("Fehler: git nicht gefunden.");
+      console.error("  Installation: https://git-scm.com");
+      process.exit(1);
+    }
+    const forgehiveDirExists = fs31.existsSync(forgehiveDir);
+    if (forgehiveDirExists && !rest.includes("--force")) {
+      console.log(`\u26A0 .forgehive/ existiert bereits in diesem Projekt.`);
+      console.log(`  Nutze 'fh init --force' um neu zu initialisieren (\xFCberschreibt capabilities.yaml).`);
+      console.log(`  Nutze 'fh scan --update' um nur den Scan zu aktualisieren.`);
+      process.exit(0);
+    }
+    console.log("\u{1F50D} Analysiere Projekt...\n");
+    const scanResult = scan(projectRoot);
+    const tierCount = [1, 2, 3].map((t) => scanResult.signals.filter((s) => s.tier === t).length);
+    console.log(`  \u2713 ${tierCount[0]} Technologie-Signale erkannt`);
+    console.log(`  \u2713 ${tierCount[1]} Infrastruktur-Signale erkannt`);
+    console.log(`  \u2713 ${tierCount[2]} Kontext-Signale erkannt`);
+    console.log();
+    const capMap = mapSignalsToCapabilities(scanResult);
+    const block = loadClaudeMdBlock();
+    writeForgehiveDir(projectRoot, scanResult, capMap, block);
+    const hash = computeHash(projectRoot);
+    fs31.writeFileSync(path32.join(forgehiveDir, ".scan-hash"), hash, "utf8");
+    const runtimeDir = path32.join(
+      path32.dirname(new URL(import.meta.url).pathname),
+      "..",
+      "forgehive"
+    );
+    initForgehiveRuntime(forgehiveDir, runtimeDir);
+    console.log("\u2713 forgehive initialisiert\n");
+    console.log(buildCapabilitySummary(capMap.confirmed.map((c) => c.id)));
+    console.log();
+    if (subcommand === "--yes" || rest.includes("--yes")) {
+      confirm(projectRoot);
+      console.log("\u2713 Capabilities best\xE4tigt\n");
+    } else {
+      const ok = await promptConfirm("  Capabilities best\xE4tigen? [Y/n] ");
+      if (ok) {
+        confirm(projectRoot);
+        console.log("\u2713 Capabilities best\xE4tigt\n");
+      } else {
+        console.log("  \xDCberpr\xFCfe .forgehive/capabilities.yaml, dann: fh confirm\n");
+      }
+    }
+  })().catch((err) => {
+    console.error(`Fehler: ${err.message}`);
+    process.exit(1);
+  });
 } else if (command === "confirm") {
   try {
     confirm(projectRoot);

package/docs/user-guide.md

@@ -1,6 +1,6 @@
 # forgehive — User Guide
 
-> Version 0.7.6 · [npm](https://www.npmjs.com/package/forgehive) · `npm install -g forgehive`
+> Version 0.7.7 · [npm](https://www.npmjs.com/package/forgehive) · `npm install -g forgehive`
 
 forgehive (`fh`) gives Claude Code persistent memory about your project. Without it, Claude forgets everything between sessions — your stack, your conventions, your decisions. With it, Claude opens every session already knowing your codebase.
 
@@ -17,7 +17,7 @@ Requires **Node.js ≥ 18** and **Claude Code** (`claude` CLI). Installs two ali
 Verify:
 
 ```bash
-fh --version   # prints 0.7.6
+fh --version   # prints 0.7.7
 fh --help      # full command reference
 ```
 
@@ -106,7 +106,12 @@ The memory files in `.forgehive/memory/` are the most important part of forgehiv
 
 ```bash
 fh docs adr "Use Postgres over MongoDB"
-fh memory adr list    # list all ADRs
+```
+
+**List all ADRs:**
+
+```bash
+fh memory adr list
 ```
 
 **View all memory:**

package/forgehive/commands/fh-refactor.md

@@ -0,0 +1,116 @@
+You are running the ForgeHive refactor workflow.
+
+## Refactor Workflow
+
+**Agenten:** Kai (Plan) → Viktor + Sam + Eli (parallel)
+
+**Mission:** Strukturierter Code-Umbau — erst verstehen und planen, dann parallel implementieren, testen und dokumentieren.
+
+## Protocol
+
+### Step 0: Scope klären
+
+Frage den User:
+
+---
+
+**Was soll refactored werden?**
+
+Gib eine der folgenden Angaben:
+- **Freie Beschreibung** — z.B. „die Docs-Generierung soll sauberer modularisiert werden"
+- **Dateipfade** — z.B. `src/docs.ts`, `src/cli.ts`
+- **Ziel-Statement** — z.B. „extrahiere generateUserGuide in ein eigenes Modul"
+
+---
+
+Wenn der Scope unklar ist: frage nach, bis das Ziel eindeutig ist.
+
+Dann führt **Kai** (Principal Engineer) die Ist-Analyse durch:
+1. Lese alle betroffenen Dateien
+2. Führe `git diff HEAD` aus (aktuelle uncommitted Änderungen)
+3. Liste alle Exports der Scope-Dateien und wo sie importiert werden
+4. Identifiziere Abhängigkeiten (wer importiert was aus den Scope-Dateien)
+
+### Step 1: Refactor-Plan erstellen (Kai)
+
+Erstelle folgenden Plan:
+
+```
+## Refactor-Plan: <Ziel>
+
+**Ziel:** <Ein Satz>
+
+**Betroffene Dateien:**
+- src/foo.ts → src/foo/index.ts + src/foo/helpers.ts
+
+**Bewegte Exports:**
+- `helperFn` aus foo.ts → foo/helpers.ts (re-exportiert aus foo/index.ts)
+
+**Breaking Changes:** keine / [Liste]
+
+**Risiken:** [z.B. zirkuläre Imports möglich bei X]
+
+**Nicht geändert:** [öffentliche API, bestehende Tests für Y, ...]
+```
+
+⚠️ **USER-APPROVAL GATE** — kein Code ohne explizites OK. Warte auf Bestätigung.
+
+### Step 2: Parallel Party starten
+
+Nach Approval:
+
+```bash
+fh party run refactor
+```
+
+Alle drei Agenten erhalten Kai's genehmigten Refactor-Plan als Kontext.
+
+**Viktor** (Systems Architect):
+- Implementiert die Änderungen Datei für Datei nach Plan
+- Darf nicht ohne User-Freigabe vom Plan abweichen
+- Meldet unvorhergesehene Abhängigkeiten explizit
+
+**Sam** (Quality Architect):
+- Liest bestehende Tests für betroffene Dateien
+- Schreibt neue Tests für umbenannte/verschobene Exports
+- Fixiert Tests die durch den Refactor brechen
+- Führt Testsuit am Ende aus — alle grün?
+
+**Eli** (Documentation Architect):
+- Aktualisiert Inline-Kommentare in geänderten Dateien
+- Aktualisiert Referenzen in README und docs/
+- Schreibt CHANGELOG-Eintrag für den Refactor
+
+### Step 3: Verifikation
+
+```bash
+fh party status
+```
+
+Synthesebericht erstellen:
+
+```
+## Refactor-Abschlussbericht
+
+### Viktor — Implementierung
+[Was wurde umgebaut]
+
+### Sam — Tests
+[Welche Tests angepasst/neu — Teststatus: ✅ alle grün / ⚠️ N fehlgeschlagen]
+
+### Eli — Dokumentation
+[Was wurde aktualisiert]
+
+### Offene Punkte
+[Was blieb unerledigt oder braucht Follow-up]
+
+### Verdict: ✅ Fertig / ⚠️ Offen
+```
+
+Abschlussfrage: **„Soll ich direkt einen Commit erstellen?"**
+
+### Step 4: Cleanup
+
+```bash
+fh party cleanup
+```

package/forgehive/commands/review-party.md

@@ -8,55 +8,74 @@ You are running a Review Party using ForgeHive.
 
 ## Protocol
 
-### Step 1: Launch the party
+### Step 0: Scope selection
+
+**Before doing anything else**, ask the user what to review:
+
+---
+
+**Was soll reviewed werden?**
+
+1. **Aktuelle Änderungen** — uncommitted working tree (`git diff HEAD`)
+2. **Letzter Commit** — `git diff HEAD~1..HEAD`
+3. **Branch vs main** — alles seit dem Abzweigen (`git diff main...HEAD`)
+4. **Letzte N Commits** — Anzahl angeben
+5. **Commit-Range** — z.B. `abc123..def456`
+6. **Spezifische Dateien** — Dateipfade angeben
+7. **PR** — PR-Nummer oder Branch-Name angeben
+
+---
+
+Wait for the user's answer. Then resolve the scope to a concrete `git diff` command and show the `--stat` output to confirm:
 
-Run:
 ```bash
-fh party run --set review
+# Example for option 3:
+git diff main...HEAD --stat
 ```
 
-This spins up isolated git worktrees for Kai, Sam, and Eli. Each agent reviews the current diff in parallel.
-
-### Step 2: Set the scope
+If the diff is empty or the result looks wrong, say so and ask the user to clarify before proceeding.
 
-Before the party starts, specify what is being reviewed — a branch name, a PR, or a commit range:
+### Step 1: Launch the party
 
+Once the scope is confirmed, run:
 ```bash
-git diff main...HEAD --stat   # show what changed
+fh party run review
 ```
 
-Share this with the party so all three agents review the same surface area.
+This spins up isolated git worktrees for Kai, Sam, and Eli.
+
+### Step 2: Dispatch agents in parallel
 
-### Step 3: Parallel review
+Pass each agent the confirmed scope and diff summary. Each agent works independently:
 
-**Kai** (Principal Engineer) — in his worktree:
-- Reviews code quality and correctness
+**Kai** (Principal Engineer):
+- Reviews code quality and correctness within the scoped diff
 - Flags bugs, logic errors, and anti-patterns
 - Checks for ambiguous naming, hidden coupling, and missing error handling
 - Labels findings: `[BUG]`, `[DESIGN]`, `[NIT]`, `[Q]`, `[+]`
 
-**Sam** (Quality Architect) — in his worktree:
+**Sam** (Quality Architect):
 - Checks test coverage for the changed code
 - Identifies missing edge cases, error states, and boundary conditions
-- Flags paths that are high-risk but untested
-- Proposes specific tests for any gaps found
+- Flags high-risk untested paths
+- Proposes specific tests for gaps
 
-**Eli** (Documentation Architect) — in his worktree:
-- Checks if README and docs reflect the changes
+**Eli** (Documentation Architect):
+- Checks if README and docs reflect the changes in scope
 - Flags missing or outdated inline documentation
-- Reviews any CHANGELOG entries for accuracy
+- Reviews CHANGELOG entries for accuracy
 - Checks that public API changes are documented
 
-### Step 4: Check status
+### Step 3: Check status
 
-After each agent completes their review:
+After each agent completes:
 ```bash
 fh party status
 ```
 
-### Step 5: Synthesize findings
+### Step 4: Synthesize findings
 
-Collect the three reports and merge them into a unified review:
+Merge the three reports into a unified review:
 
 1. **Blocking issues** — anything from Kai or Sam that must be fixed before merge
 2. **Test gaps** — Sam's missing coverage items
@@ -65,7 +84,7 @@ Collect the three reports and merge them into a unified review:
 
 Present the synthesized report to the user and ask: **"Soll ich die Blocking Issues direkt fixen?"**
 
-### Step 6: Cleanup
+### Step 5: Cleanup
 
 ```bash
 fh party cleanup

package/forgehive/party/defaults.yaml

@@ -41,3 +41,11 @@ sets:
     models:
       vera: claude-opus-4-7
       sam: claude-sonnet-4-6
+  refactor:
+    agents: [viktor, sam, eli]
+    trigger: "/fh-refactor"
+    description: "Refactor — Implementierung + Tests + Doku parallel"
+    models:
+      viktor: claude-opus-4-7
+      sam: claude-sonnet-4-6
+      eli: claude-sonnet-4-6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgehive",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Context-aware AI development environment — one binary, your stack.",
   "type": "module",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "files": [
     "dist/",
-    "docs/",
+    "docs/user-guide.md",
     "forgehive/"
   ],
   "keywords": [
@@ -22,6 +22,7 @@
     "forgehive",
     "development"
   ],
+  "license": "Elastic-2.0",
   "engines": {
     "node": ">=18"
   },