openlore 2.0.0

package/dist/utils/shutdown.js

@@ -0,0 +1,238 @@
+/**
+ * Graceful shutdown handling for openlore CLI
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { OPENLORE_DIR, ARTIFACT_SHUTDOWN_STATE } from '../constants.js';
+/**
+ * Manages graceful shutdown with cleanup callbacks
+ */
+export class ShutdownManager {
+    callbacks = [];
+    isShuttingDown = false;
+    state = null;
+    stateFile;
+    handlers = new Map();
+    handlersAttached = false;
+    constructor(projectPath = process.cwd(), options) {
+        this.stateFile = path.join(projectPath, OPENLORE_DIR, ARTIFACT_SHUTDOWN_STATE);
+        // Skip handlers in test environment or when explicitly disabled
+        if (!options?.skipHandlers && process.env.NODE_ENV !== 'test') {
+            this.setupHandlers();
+        }
+    }
+    setupHandlers() {
+        if (this.handlersAttached)
+            return;
+        this.handlersAttached = true;
+        const sigintHandler = () => this.handleShutdown('SIGINT');
+        const sigtermHandler = () => this.handleShutdown('SIGTERM');
+        const exceptionHandler = (error) => {
+            console.error('\n❌ Uncaught exception:', error.message);
+            this.handleShutdown('uncaughtException');
+        };
+        const rejectionHandler = (reason) => {
+            console.error('\n❌ Unhandled rejection:', reason);
+            this.handleShutdown('unhandledRejection');
+        };
+        // Store handlers for potential cleanup
+        this.handlers.set('SIGINT', sigintHandler);
+        this.handlers.set('SIGTERM', sigtermHandler);
+        this.handlers.set('uncaughtException', exceptionHandler);
+        this.handlers.set('unhandledRejection', rejectionHandler);
+        // Handle Ctrl+C
+        process.on('SIGINT', sigintHandler);
+        // Handle termination signal
+        process.on('SIGTERM', sigtermHandler);
+        // Handle uncaught exceptions
+        process.on('uncaughtException', exceptionHandler);
+        // Handle unhandled promise rejections
+        process.on('unhandledRejection', rejectionHandler);
+    }
+    /**
+     * Remove all registered signal handlers (for testing)
+     */
+    removeHandlers() {
+        for (const [event, handler] of this.handlers) {
+            process.removeListener(event, handler);
+        }
+        this.handlers.clear();
+        this.handlersAttached = false;
+    }
+    async handleShutdown(signal) {
+        if (this.isShuttingDown) {
+            console.log('\n⚠️  Force quitting...');
+            process.exit(1);
+        }
+        this.isShuttingDown = true;
+        console.log('\n\n🛑 Interrupted! Cleaning up...');
+        // Save state if we have one
+        if (this.state) {
+            await this.saveState();
+        }
+        // Run cleanup callbacks in reverse order (copy to avoid mutating the array)
+        for (const callback of [...this.callbacks].reverse()) {
+            try {
+                await callback();
+            }
+            catch (error) {
+                console.error('Cleanup error:', error);
+            }
+        }
+        // Show resume suggestion
+        this.showResumeSuggestion();
+        process.exit(signal === 'SIGINT' ? 130 : 1);
+    }
+    /**
+     * Register a cleanup callback to run on shutdown
+     */
+    onCleanup(callback) {
+        this.callbacks.push(callback);
+    }
+    /**
+     * Remove a cleanup callback
+     */
+    removeCleanup(callback) {
+        const index = this.callbacks.indexOf(callback);
+        if (index !== -1) {
+            this.callbacks.splice(index, 1);
+        }
+    }
+    /**
+     * Set the current state for potential resume
+     */
+    setState(state) {
+        this.state = {
+            phase: state.phase ?? 'init',
+            currentFiles: state.currentFiles,
+            savedResults: state.savedResults,
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Clear state (call on successful completion)
+     */
+    clearState() {
+        this.state = null;
+        // Remove state file if it exists
+        try {
+            if (fs.existsSync(this.stateFile)) {
+                fs.unlinkSync(this.stateFile);
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    /**
+     * Save state to file for potential resume
+     */
+    async saveState() {
+        if (!this.state)
+            return;
+        try {
+            const dir = path.dirname(this.stateFile);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(this.stateFile, JSON.stringify(this.state, null, 2));
+            console.log(`📝 State saved to ${this.stateFile}`);
+        }
+        catch (error) {
+            console.error('Failed to save state:', error);
+        }
+    }
+    /**
+     * Load previous shutdown state
+     */
+    loadState() {
+        try {
+            if (fs.existsSync(this.stateFile)) {
+                const content = fs.readFileSync(this.stateFile, 'utf-8');
+                return JSON.parse(content);
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return null;
+    }
+    /**
+     * Check if there's a previous interrupted session
+     */
+    hasPreviousState() {
+        return this.loadState() !== null;
+    }
+    showResumeSuggestion() {
+        if (!this.state)
+            return;
+        console.log('\n📋 To resume from where you left off:');
+        switch (this.state.phase) {
+            case 'init':
+                console.log('   Run: openlore init');
+                break;
+            case 'analyze':
+                console.log('   Run: openlore analyze');
+                if (this.state.savedResults) {
+                    console.log(`   Partial analysis saved to: ${this.state.savedResults}`);
+                }
+                break;
+            case 'generate':
+                console.log('   Run: openlore generate');
+                if (this.state.savedResults) {
+                    console.log(`   Partial specs saved to: ${this.state.savedResults}`);
+                }
+                break;
+            case 'verify':
+                console.log('   Run: openlore verify');
+                break;
+        }
+        console.log('');
+    }
+    /**
+     * Check if shutdown is in progress
+     */
+    isInProgress() {
+        return this.isShuttingDown;
+    }
+}
+// Global shutdown manager instance
+let globalManager = null;
+/**
+ * Get or create the global shutdown manager
+ */
+export function getShutdownManager(projectPath) {
+    if (!globalManager) {
+        globalManager = new ShutdownManager(projectPath);
+    }
+    return globalManager;
+}
+/**
+ * Register a cleanup callback with the global manager
+ */
+export function onShutdown(callback) {
+    getShutdownManager().onCleanup(callback);
+}
+/**
+ * Set current state for potential resume
+ */
+export function setShutdownState(state) {
+    getShutdownManager().setState(state);
+}
+/**
+ * Clear shutdown state (call on successful completion)
+ */
+export function clearShutdownState() {
+    getShutdownManager().clearState();
+}
+/**
+ * Create a scope that sets/clears state automatically
+ */
+export async function withShutdownState(state, fn) {
+    const manager = getShutdownManager();
+    manager.setState(state);
+    const result = await fn();
+    manager.clearState();
+    return result;
+}
+//# sourceMappingURL=shutdown.js.map

package/dist/utils/shutdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../../src/utils/shutdown.ts"],"names":[],"mappings":"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"}

package/examples/bmad/README.md

@@ -0,0 +1,113 @@
+# BMAD assets for openlore
+
+BMAD Method implementation of the [openlore agentic workflow pattern](../../docs/agentic-workflows/README.md).
+
+See [docs/agentic-workflows/BMAD.md](../../docs/agentic-workflows/BMAD.md) for the full integration guide.
+
+## OpenSpec spec baseline
+
+`search_specs` and `check_spec_drift` are only useful if specs exist. The Architect agent
+runs `openlore generate` during onboarding — that creates the baseline. Without it,
+`search_specs` returns empty and `check_spec_drift` flags everything as uncovered.
+
+| State | What to do |
+|---|---|
+| First time on this codebase | Run `openlore analyze && openlore generate` during onboarding (covered in `tasks/onboarding.md`) |
+| Specs exist | `search_specs` and `check_spec_drift` work as expected |
+| Specs missing mid-project | Run `openlore generate $PROJECT_ROOT` — takes a few minutes, only needed once |
+
+The `implement-story.md` task detects this automatically and tells you what to do.
+
+## Workflow
+
+```mermaid
+flowchart TD
+    ONBOARD["openlore analyze + generate\n(one-time baseline)"]
+
+    subgraph ARCH ["🏛️ Architecture"]
+        ONBOARD --> OVERVIEW["get_architecture_overview\nget_refactor_report"]
+        OVERVIEW --> PROPOSAL["generate_change_proposal × epic\nannotate_story × story\n→ risk_context pre-filled"]
+    end
+
+    subgraph PLAN ["📋 Sprint Planning"]
+        PROPOSAL --> SPRINT["sprint-planning.md\nconflict detection\nrefactor ordering"]
+        SPRINT --> GATE{risk ≥ 70?}
+        GATE -- yes --> REFACTOR["refactor.md\n🔴 refactor first"]
+        GATE -- no --> LOCKED["Sprint locked"]
+        REFACTOR --> SPRINT
+    end
+
+    subgraph IMPL ["⚙️ Per Story"]
+        LOCKED --> ORIENT["orient + analyze_impact\n(confirm risk_context)"]
+        ORIENT --> CODE["implement"]
+        CODE --> TESTS["tests green ✅"]
+        TESTS --> DRIFT["check_spec_drift"]
+        DRIFT --> DONE["story done ✅"]
+    end
+
+    style ONBOARD fill:#f0f0f0,stroke:#999
+    style REFACTOR fill:#fdd,stroke:#c00
+```
+
+## Setup (BMAD via npm)
+
+### Prerequisites
+
+- Node.js 20+
+- BMAD installed in your project: `npx bmad-method install`
+- openlore MCP server running and indexed (`openlore analyze && openlore generate`)
+
+### Step 1 — Copy assets into your BMAD project
+
+```bash
+# From your project root (where _bmad/ lives)
+cp /path/to/openlore/examples/bmad/agents/architect.md \
+   _bmad/_memory/architect-sidecar/openlore.md
+
+cp /path/to/openlore/examples/bmad/tasks/*.md \
+   _bmad/openlore/tasks/
+
+cp /path/to/openlore/examples/bmad/templates/*.md \
+   _bmad/openlore/templates/
+```
+
+### Step 2 — Install the architect customization
+
+```bash
+cp /path/to/openlore/examples/bmad/setup/architect.customize.yaml \
+   _bmad/_config/customizations/architect.customize.yaml
+```
+
+This tells the BMAD Architect agent to load the openlore structural analysis
+instructions every time it starts, via the sidecar mechanism.
+
+### Step 3 — Recompile BMAD agents
+
+```bash
+npx bmad-method install
+```
+
+BMAD recompiles the Architect agent with the new customization. The compiled
+markdown agent file now includes a `Load COMPLETE file` directive pointing to
+`_bmad/_memory/architect-sidecar/openlore.md`.
+
+### Step 4 — Start an architecture session
+
+Open your IDE and start a conversation with the BMAD Architect agent.
+The agent will automatically load the openlore instructions and begin
+with Phase 0 (Structural Reality) before any design work.
+
+---
+
+## Contents
+
+| Path | Purpose | Where it goes in BMAD |
+|---|---|---|
+| `agents/architect.md` | Architect sidecar — structural analysis before architecture | `_bmad/_memory/architect-sidecar/openlore.md` |
+| `agents/dev-brownfield.md` | Dev agent fallback gate when planning was skipped | `_bmad/_memory/dev-sidecar/openlore-fallback.md` *(optional)* |
+| `tasks/onboarding.md` | One-time baseline: analyze + generate specs | `_bmad/openlore/tasks/` |
+| `tasks/sprint-planning.md` | Sprint validation: conflict detection, refactor ordering | `_bmad/openlore/tasks/` |
+| `tasks/implement-story.md` | Implementation: risk-proportional orient → code → tests → drift | `_bmad/openlore/tasks/` |
+| `tasks/refactor.md` | Safe refactor task for risk ≥ 70 stories | `_bmad/openlore/tasks/` |
+| `templates/story.md` | Story template with `risk_context` section | `_bmad/openlore/templates/` |
+| `setup/architect.customize.yaml` | BMAD customization — enables sidecar load | `_bmad/_config/customizations/` |

package/examples/bmad/agents/architect.md

@@ -0,0 +1,226 @@
+# Agent: Architect — openlore extension
+
+> **This file is a sidecar for the BMAD `architect` agent.**
+>
+> **Setup (one-time):**
+> ```bash
+> # 1. Copy this file into your BMAD project
+> cp examples/bmad/agents/architect.md _bmad/_memory/architect-sidecar/openlore.md
+>
+> # 2. Install the customization that tells BMAD to load it
+> cp examples/bmad/setup/architect.customize.yaml \
+>    _bmad/_config/customizations/architect.customize.yaml
+>
+> # 3. Recompile BMAD agents
+> npx bmad-method install
+> ```
+>
+> After that, the Architect agent loads this file automatically at session start.
+> No manual step needed in the conversation.
+>
+> Requires: openlore MCP server connected and onboarding completed
+> (see `tasks/onboarding.md`).
+
+---
+
+## Core Principle
+
+The architecture document MUST reflect the reality of the code,
+not just the desired target state. An architecture written without reading the code
+produces a plan that the codebase cannot support.
+
+**Produce two documents:**
+1. **Structural Reality** — what the code actually is (openlore output)
+2. **Target Architecture** — what you want it to become (your design)
+
+The gap between them is the technical debt backlog.
+
+---
+
+## Phase 0 — Structural Reality (run before any design work)
+
+### Step 0.1 — Architecture overview
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_architecture_overview</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Extract:
+- **Domain clusters** → existing logical boundaries
+- **Cross-cluster dependencies** → where coupling is highest
+- **Critical hubs** → functions that act as bottlenecks
+- **Entry points** → where control enters the system
+
+If this returns an error, run `analyze_codebase` first.
+
+### Step 0.2 — Risk landscape
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_refactor_report</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Classify each high-priority candidate:
+
+| Function | Issues | Priority | Classification |
+|---|---|---|---|
+| ... | high_fan_out | 85 | 🔴 no-touch zone |
+| ... | in_cycle | 62 | 🟠 isolate before touching |
+| ... | multi_requirement | 38 | 🟡 document carefully |
+
+**No-touch zones** (priority ≥ 70): any story touching these functions is **blocked**
+until a refactor story is completed first.
+
+### Step 0.3 — Structural debt
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_duplicate_report</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT"}</arguments>
+</use_mcp_tool>
+```
+
+Note clone groups — they amplify the cost of any feature that touches duplicated logic.
+
+### Step 0.4 — Critical hubs
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>get_critical_hubs</tool_name>
+  <arguments>{"directory": "$PROJECT_ROOT", "limit": 10, "minFanIn": 3}</arguments>
+</use_mcp_tool>
+```
+
+Hubs with high fan-in are the riskiest insertion points. Note their recommended approach
+(`extract`, `split`, `facade`, `delegate`).
+
+---
+
+## Phase 1 — Feature / Epic Impact Assessment
+
+For each epic or major feature in scope, generate a change proposal:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>generate_change_proposal</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "description": "$EPIC_DESCRIPTION",
+    "slug": "$EPIC_SLUG"
+  }</arguments>
+</use_mcp_tool>
+```
+
+From each proposal:
+- **domainsAffected** → which spec domains this epic touches
+- **maxRiskScore** → overall risk level of this epic
+- **requirementsTouched** → existing requirements this epic overlaps or extends
+
+Build an epic risk matrix:
+
+| Epic | Domains | Max Risk | Blocking Refactors |
+|---|---|---|---|
+| Add payment retry | payment, api | 🔴 82 | refactor `processPayment` first |
+| User email validation | auth, user | 🟢 18 | none |
+
+---
+
+## Phase 2 — Architecture Document
+
+Write `docs/architecture.md` (or the BMAD equivalent) with two mandatory sections:
+
+### Section: Structural Reality
+
+```markdown
+## Structural Reality (as-is)
+
+> Generated from openlore analysis on {date}.
+> Re-run `openlore analyze --force` before each planning cycle.
+
+### Domain Map
+
+{paste architecture overview clusters and dependencies}
+
+### No-Touch Zones
+
+Functions that MUST NOT be modified without a prior refactor story:
+
+| Function | File | Risk | Issues |
+|---|---|---|---|
+
+### Known Debt
+
+- N clone groups detected
+- N cyclic dependencies
+
+### Critical Hubs
+
+Functions requiring the most careful change management:
+
+| Function | Fan-in | Recommended approach |
+|---|---|---|
+```
+
+### Section: Target Architecture
+
+Design the future state here — new domains, desired boundaries, patterns to introduce.
+**For each structural gap between reality and target, create a technical debt story.**
+
+---
+
+## Phase 3 — Technical Debt Backlog
+
+For every no-touch zone, create a **refactor story** in the BMAD backlog:
+
+Use the template `bmad/templates/story.md` with:
+- Story type: `technical-debt`
+- Title: `Refactor {function}: {issue}`
+- Blocking: list stories that cannot proceed until this is done
+- **Won't Do**: at minimum one item — scope the refactor tightly (e.g. "Won't change the public API", "Won't refactor callers")
+- **Acceptance Criteria**: must be testable — state observable outcomes (e.g. "riskScore drops below 70", "no caller changes required")
+
+These stories MUST be sprint-scheduled before any story that depends on the refactored function.
+
+---
+
+## Phase 4 — Annotate Stories with Risk Context
+
+For each story in the backlog, run `annotate_story` — do not fill `risk_context` manually.
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>annotate_story</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "storyFilePath": "$STORY_FILE_PATH",
+    "description": "$STORY_TITLE — $PRIMARY_AC"
+  }</arguments>
+</use_mcp_tool>
+```
+
+The tool reads the story file, runs `orient` + `analyze_impact`, and writes the
+`risk_context` section directly. Existing sections are replaced, not appended.
+
+Re-run after any completed refactor story — risk scores change as the code evolves.
+
+The Dev Agent reads this context at sprint time — it does **not** discover it.
+
+---
+
+## Absolute Constraints
+
+- Never write a target architecture without first completing Phase 0
+- Never assign a story touching a no-touch zone without a blocking refactor story in the backlog
+- Always run `annotate_story` on stories before they enter a sprint — never fill risk_context manually
+- Re-run Phase 0 at the start of each planning cycle — the structural reality changes

package/examples/bmad/agents/dev-brownfield.md

@@ -0,0 +1,69 @@
+# Agent: Developer — No-Planning Fallback
+
+> **Load this ONLY when:**
+> - No architect analysis was done and stories have no `risk_context`
+> - Onboarding to a completely unknown codebase mid-project
+> - The sprint planning task was skipped
+>
+> In normal usage, `bmad/tasks/implement-story.md` is sufficient —
+> the risk context from planning makes this override unnecessary.
+
+---
+
+## What this adds
+
+When `risk_context` is absent from a story, this override enforces a full
+structural gate at implementation time as a safety net.
+
+For every story, before writing code:
+
+1. Call `orient` with the story description
+2. Call `analyze_impact` on the top 3 functions
+3. If any `riskScore ≥ 70`: stop, propose a refactor story, do not proceed
+
+This replicates at dev time what should have happened at planning time.
+
+---
+
+## When to stop using this
+
+Once the Architect Agent has run `bmad/tasks/onboarding.md` and
+`bmad/agents/architect.md`, and stories have `risk_context` populated,
+**remove this override**. It adds cost (extra MCP calls) with no benefit
+once planning is done correctly.
+
+---
+
+## Gate
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>orient</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "task": "$STORY_TITLE — $AC1",
+    "limit": 7
+  }</arguments>
+</use_mcp_tool>
+```
+
+For each of the top 3 functions:
+
+```xml
+<use_mcp_tool>
+  <server_name>openlore</server_name>
+  <tool_name>analyze_impact</tool_name>
+  <arguments>{
+    "directory": "$PROJECT_ROOT",
+    "symbol": "$FUNCTION_NAME",
+    "depth": 2
+  }</arguments>
+</use_mcp_tool>
+```
+
+| riskScore | Action |
+|---|---|
+| < 40 | Proceed |
+| 40–69 | Proceed with care — protect listed callers |
+| ≥ 70 | Stop — create refactor story, block this story |

package/examples/bmad/setup/architect.customize.yaml

@@ -0,0 +1,14 @@
+# openlore extension for the BMAD Architect agent
+#
+# Drop this file at: _bmad/_config/customizations/architect.customize.yaml
+# Then re-run: npx bmad-method install
+#
+# What it does: instructs the Architect agent to load the openlore structural
+# analysis instructions as a sidecar before starting any design work.
+
+customize:
+  metadata:
+    hasSidecar: true
+  critical-actions:
+    Appends:
+      - "Load COMPLETE file {project-root}/_bmad/_memory/architect-sidecar/openlore.md"