bmalph 2.4.0 → 2.5.0

package/README.md

@@ -26,6 +26,10 @@ bmalph provides:
 - `bmalph upgrade` — Update to latest versions
 - `bmalph doctor` — Check installation health
 - `bmalph implement` — Transition from BMAD to Ralph
+- `bmalph check-updates` — Check for upstream updates
+- `bmalph status` — Show project status and phase
+- `bmalph reset` — Remove all bmalph files
+- `bmalph watch` — Live Ralph loop dashboard
 
 ## Supported Platforms
 
@@ -203,6 +207,8 @@ BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
 | `bmalph check-updates` | Check if bundled BMAD/Ralph versions are up to date |
 | `bmalph status`        | Show current project status and phase               |
 | `bmalph implement`     | Transition BMAD planning artifacts to Ralph format  |
+| `bmalph reset`         | Remove all bmalph files from the project            |
+| `bmalph watch`         | Live dashboard showing Ralph loop status            |
 
 ### Global options
 
@@ -222,6 +228,7 @@ BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
 | `-n, --name <name>`        | Project name                                                                       | directory name |
 | `-d, --description <desc>` | Project description                                                                | (prompted)     |
 | `--platform <id>`          | Target platform (`claude-code`, `codex`, `cursor`, `windsurf`, `copilot`, `aider`) | auto-detect    |
+| `--dry-run`                | Preview changes without writing files                                              |                |
 
 ### implement options
 
@@ -235,6 +242,12 @@ BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
 | -------- | -------------- |
 | `--json` | Output as JSON |
 
+### doctor options
+
+| Flag     | Description    |
+| -------- | -------------- |
+| `--json` | Output as JSON |
+
 ### status options
 
 | Flag     | Description    |
@@ -248,9 +261,22 @@ BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2
 | `--force`   | Skip confirmation prompts |
 | `--dry-run` | Preview changes           |
 
+### reset options
+
+| Flag        | Description              |
+| ----------- | ------------------------ |
+| `--dry-run` | Preview changes          |
+| `--force`   | Skip confirmation prompt |
+
+### watch options
+
+| Flag              | Description                                      |
+| ----------------- | ------------------------------------------------ |
+| `--interval <ms>` | Refresh interval in milliseconds (default: 2000) |
+
 ## Slash Commands
 
-bmalph installs 50 slash commands (45 BMAD + 5 bmalph). Command delivery varies by platform:
+bmalph installs 51 slash commands (45 BMAD + 6 bmalph). Command delivery varies by platform:
 
 - **Claude Code** — installed as files in `.claude/commands/` (invoke with `/command-name`)
 - **OpenAI Codex** — inlined in `AGENTS.md` (reference agents by name)
@@ -405,25 +431,33 @@ ls -la .ralph/
 
 ### Reset Installation
 
-If something goes wrong, you can manually reset:
+The simplest way to remove all bmalph files:
 
 ```bash
-# Remove bmalph directories (preserves your project code)
-rm -rf _bmad .ralph bmalph
-
-# Also remove platform-specific files:
-# Claude Code:  rm -rf .claude/commands/  and remove bmalph section from CLAUDE.md
-# Codex:        remove bmalph sections from AGENTS.md
-# Cursor:       rm .cursor/rules/bmad.mdc
-# Windsurf:     rm .windsurf/rules/bmad.md
-# Copilot:      remove bmalph sections from .github/copilot-instructions.md
-# Aider:        remove bmalph sections from CONVENTIONS.md
-# See the Supported Platforms table for your platform's files.
-
-# Reinitialize
-bmalph init
+bmalph reset
 ```
 
+Use `--dry-run` to preview what will be removed, or `--force` to skip confirmation.
+
+#### Manual removal
+
+If the CLI is unavailable, remove these directories and files manually:
+
+```bash
+rm -rf _bmad/ .ralph/ bmalph/
+```
+
+Then remove the bmalph-managed sections from your instructions file. The file depends on your platform:
+
+- **Claude Code** — remove `.claude/commands/` and bmalph section from `CLAUDE.md`
+- **Codex** — remove bmalph sections from `AGENTS.md`
+- **Cursor** — remove `.cursor/rules/bmad.mdc`
+- **Windsurf** — remove `.windsurf/rules/bmad.md`
+- **Copilot** — remove bmalph sections from `.github/copilot-instructions.md`
+- **Aider** — remove bmalph sections from `CONVENTIONS.md`
+
+See the [Supported Platforms](#supported-platforms) table for details. After manual removal, run `bmalph init` to reinitialize.
+
 ## Quick Examples
 
 ### Initialize a new project

package/dist/cli.js

@@ -8,6 +8,7 @@ import { checkUpdatesCommand } from "./commands/check-updates.js";
 import { statusCommand } from "./commands/status.js";
 import { implementCommand } from "./commands/implement.js";
 import { resetCommand } from "./commands/reset.js";
+import { watchCommand } from "./commands/watch.js";
 import { setVerbose, setQuiet } from "./utils/logger.js";
 import { getPackageVersion } from "./installer.js";
 import { isEnoent } from "./utils/errors.js";
@@ -92,4 +93,9 @@ program
     .option("--dry-run", "Preview changes without removing files")
     .option("--force", "Skip confirmation prompt")
     .action(async (opts) => resetCommand({ ...opts, projectDir: await resolveAndValidateProjectDir() }));
+program
+    .command("watch")
+    .description("Live dashboard showing Ralph loop status, circuit breaker, and activity")
+    .option("--interval <ms>", "Refresh interval in milliseconds (default: 2000)")
+    .action(async (opts) => watchCommand({ ...opts, projectDir: await resolveAndValidateProjectDir() }));
 void program.parseAsync();

package/dist/commands/doctor.d.ts

@@ -37,15 +37,4 @@ export declare function runDoctor(options: DoctorOptions): Promise<DoctorResult>
  * Core checks + platform doctor checks + trailing checks.
  */
 export declare function buildCheckRegistry(platform: Platform): CheckDefinition[];
-/**
- * Static registry for backward compatibility with existing tests.
- * Uses claude-code platform checks (slash-command + claude-md).
- *
- * Note: The check ids here ("slash-command", "claude-md") intentionally differ
- * from the live buildCheckRegistry path which uses platform-provided ids
- * ("instructions-file"). This is for test backward compatibility only.
- *
- * @deprecated Use `buildCheckRegistry(platform)` for platform-aware checks.
- */
-export declare const CHECK_REGISTRY: CheckDefinition[];
 export {};

package/dist/commands/doctor.js

@@ -1,6 +1,5 @@
 import chalk from "chalk";
 import { readFile, stat } from "fs/promises";
-import { exists } from "../utils/file-system.js";
 import { join } from "path";
 import { readJsonFile } from "../utils/json.js";
 import { readConfig } from "../utils/config.js";
@@ -451,51 +450,3 @@ export function buildCheckRegistry(platform) {
     }));
     return [...CORE_CHECKS, ...platformChecks, ...TRAILING_CHECKS];
 }
-/**
- * Static registry for backward compatibility with existing tests.
- * Uses claude-code platform checks (slash-command + claude-md).
- *
- * Note: The check ids here ("slash-command", "claude-md") intentionally differ
- * from the live buildCheckRegistry path which uses platform-provided ids
- * ("instructions-file"). This is for test backward compatibility only.
- *
- * @deprecated Use `buildCheckRegistry(platform)` for platform-aware checks.
- */
-export const CHECK_REGISTRY = (() => {
-    // Inline claude-code platform checks to avoid async import at module level
-    const slashCommandCheck = {
-        id: "slash-command",
-        run: async (projectDir) => {
-            if (await exists(join(projectDir, ".claude/commands/bmalph.md"))) {
-                return { label: ".claude/commands/bmalph.md present", passed: true };
-            }
-            return {
-                label: ".claude/commands/bmalph.md present",
-                passed: false,
-                detail: "not found",
-                hint: "Run: bmalph init",
-            };
-        },
-    };
-    const claudeMdCheck = {
-        id: "claude-md",
-        run: async (projectDir) => {
-            const label = "CLAUDE.md contains BMAD snippet";
-            const hint = "Run: bmalph init";
-            try {
-                const content = await readFile(join(projectDir, "CLAUDE.md"), "utf-8");
-                if (content.includes("BMAD-METHOD Integration")) {
-                    return { label, passed: true };
-                }
-                return { label, passed: false, detail: "missing BMAD-METHOD Integration section", hint };
-            }
-            catch (err) {
-                if (isEnoent(err)) {
-                    return { label, passed: false, detail: "CLAUDE.md not found", hint };
-                }
-                return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
-            }
-        },
-    };
-    return [...CORE_CHECKS, slashCommandCheck, claudeMdCheck, ...TRAILING_CHECKS];
-})();

package/dist/commands/init.js

@@ -1,10 +1,12 @@
 import chalk from "chalk";
 import inquirer from "inquirer";
 import { writeConfig } from "../utils/config.js";
-import { installProject, mergeInstructionsFile, isInitialized, hasExistingBmadDir, previewInstall, getBundledVersions, } from "../installer.js";
+import { installProject, mergeInstructionsFile, isInitialized, previewInstall, getBundledVersions, } from "../installer.js";
 import { formatDryRunSummary } from "../utils/dryrun.js";
 import { validateProjectName } from "../utils/validate.js";
 import { withErrorHandling } from "../utils/errors.js";
+import { exists } from "../utils/file-system.js";
+import { join } from "path";
 import { isPlatformId, getPlatform } from "../platform/registry.js";
 import { detectPlatform } from "../platform/detect.js";
 export async function initCommand(options) {
@@ -62,7 +64,7 @@ async function runInit(options) {
         console.log("Use 'bmalph upgrade' to update bundled assets to the latest version.");
         return;
     }
-    if (await hasExistingBmadDir(projectDir)) {
+    if (await exists(join(projectDir, "_bmad"))) {
         console.log(chalk.cyan("Existing BMAD installation detected."));
         console.log("Framework files in _bmad/ will be replaced with the managed version.");
         console.log("Planning artifacts in _bmad-output/ will not be modified.\n");

package/dist/commands/status.js

@@ -43,6 +43,11 @@ export async function runStatus(options) {
     const nextAction = artifactScan && phaseDetected
         ? artifactScan.nextAction
         : getNextAction(phase, status, ralphStatus, platform);
+    // Detect when Ralph completed but bmalph state hasn't caught up
+    const completionMismatch = phase === 4 &&
+        status === "implementing" &&
+        ralphStatus !== null &&
+        ralphStatus.status === "completed";
     if (options.json) {
         const output = {
             phase,
@@ -68,6 +73,9 @@ export async function runStatus(options) {
         if (nextAction) {
             output.nextAction = nextAction;
         }
+        if (completionMismatch) {
+            output.completionMismatch = true;
+        }
         console.log(JSON.stringify(output, null, 2));
         return;
     }
@@ -97,7 +105,12 @@ export async function runStatus(options) {
         console.log(chalk.bold("  Ralph Loop"));
         console.log(`    ${chalk.cyan("Status:")} ${chalk.dim("not started")}`);
     }
-    if (nextAction) {
+    if (completionMismatch) {
+        console.log("");
+        console.log(chalk.green("  Ralph has completed all tasks."));
+        console.log(`  ${chalk.cyan("Next:")} Review changes and update project phase`);
+    }
+    else if (nextAction) {
         console.log("");
         console.log(`  ${chalk.cyan("Next:")} ${nextAction}`);
     }

package/dist/commands/watch.d.ts

@@ -0,0 +1,6 @@
+interface WatchCommandOptions {
+    interval?: string;
+    projectDir: string;
+}
+export declare function watchCommand(options: WatchCommandOptions): Promise<void>;
+export {};

package/dist/commands/watch.js

@@ -0,0 +1,19 @@
+import { readConfig } from "../utils/config.js";
+import { withErrorHandling } from "../utils/errors.js";
+import { startDashboard } from "../watch/dashboard.js";
+const DEFAULT_INTERVAL_MS = 2000;
+export async function watchCommand(options) {
+    await withErrorHandling(() => runWatch(options));
+}
+async function runWatch(options) {
+    const projectDir = options.projectDir;
+    const config = await readConfig(projectDir);
+    if (!config) {
+        throw new Error("Project not initialized. Run: bmalph init");
+    }
+    const interval = options.interval ? parseInt(options.interval, 10) : DEFAULT_INTERVAL_MS;
+    if (isNaN(interval) || interval < 500) {
+        throw new Error("Interval must be a number >= 500 (milliseconds)");
+    }
+    await startDashboard({ projectDir, interval });
+}

package/dist/installer.d.ts

@@ -28,12 +28,6 @@ export declare function generateManifests(projectDir: string): Promise<void>;
  * Creates the file if it doesn't exist, replaces an existing BMAD section on upgrade.
  */
 export declare function mergeInstructionsFile(projectDir: string, platform?: Platform): Promise<void>;
-/**
- * @deprecated Use `mergeInstructionsFile(projectDir)` instead.
- * Kept for backward compatibility during migration.
- */
-export declare function mergeClaudeMd(projectDir: string): Promise<void>;
 export declare function isInitialized(projectDir: string): Promise<boolean>;
-export declare function hasExistingBmadDir(projectDir: string): Promise<boolean>;
 export declare function previewInstall(projectDir: string, platform?: Platform): Promise<PreviewInstallResult>;
 export declare function previewUpgrade(projectDir: string, platform?: Platform): Promise<PreviewUpgradeResult>;

package/dist/installer.js

@@ -424,19 +424,9 @@ export async function mergeInstructionsFile(projectDir, platform) {
     }
     await atomicWriteFile(instructionsPath, existing + snippet);
 }
-/**
- * @deprecated Use `mergeInstructionsFile(projectDir)` instead.
- * Kept for backward compatibility during migration.
- */
-export async function mergeClaudeMd(projectDir) {
-    return mergeInstructionsFile(projectDir);
-}
 export async function isInitialized(projectDir) {
     return exists(join(projectDir, CONFIG_FILE));
 }
-export async function hasExistingBmadDir(projectDir) {
-    return exists(join(projectDir, "_bmad"));
-}
 export async function previewInstall(projectDir, platform) {
     const p = platform ?? (await getDefaultPlatform());
     const wouldCreate = [];

package/dist/transition/artifacts.d.ts

@@ -1,3 +1 @@
 export declare function findArtifactsDir(projectDir: string): Promise<string | null>;
-/** @deprecated Use `runPreflight` from `./preflight.js` instead. Kept for backward compatibility. */
-export declare function validateArtifacts(files: string[], artifactsDir: string): Promise<string[]>;

package/dist/transition/artifacts.js

@@ -1,4 +1,3 @@
-import { readFile } from "fs/promises";
 import { join } from "path";
 import { debug } from "../utils/logger.js";
 import { exists } from "../utils/file-system.js";
@@ -19,29 +18,3 @@ export async function findArtifactsDir(projectDir) {
     debug(`No artifacts found. Checked: ${candidates.join(", ")}`);
     return null;
 }
-/** @deprecated Use `runPreflight` from `./preflight.js` instead. Kept for backward compatibility. */
-export async function validateArtifacts(files, artifactsDir) {
-    const warnings = [];
-    const hasPrd = files.some((f) => /prd/i.test(f));
-    if (!hasPrd) {
-        warnings.push("No PRD document found in planning artifacts");
-    }
-    const hasArchitecture = files.some((f) => /architect/i.test(f));
-    if (!hasArchitecture) {
-        warnings.push("No architecture document found in planning artifacts");
-    }
-    // Check readiness report for NO-GO
-    const readinessFile = files.find((f) => /readiness/i.test(f));
-    if (readinessFile) {
-        try {
-            const content = await readFile(join(artifactsDir, readinessFile), "utf-8");
-            if (/NO[-\s]?GO/i.test(content)) {
-                warnings.push("Readiness report indicates NO-GO status");
-            }
-        }
-        catch {
-            warnings.push("Could not read readiness report — NO-GO status unverified");
-        }
-    }
-    return warnings;
-}

package/dist/transition/index.d.ts

@@ -2,7 +2,7 @@ export type { ProjectContext, Story, TechStack, FixPlanItem, SpecsChange, Transi
 export { parseStories, parseStoriesWithWarnings } from "./story-parsing.js";
 export { generateFixPlan, hasFixPlanProgress, parseFixPlan, mergeFixPlanProgress, } from "./fix-plan.js";
 export { detectTechStack, customizeAgentMd } from "./tech-stack.js";
-export { findArtifactsDir, validateArtifacts } from "./artifacts.js";
+export { findArtifactsDir } from "./artifacts.js";
 export { extractSection, extractProjectContext, generateProjectContextMd, generatePrompt, } from "./context.js";
 export { generateSpecsChangelog, formatChangelog } from "./specs-changelog.js";
 export { detectSpecFileType, determinePriority, extractDescription, generateSpecsIndex, formatSpecsIndexMd, } from "./specs-index.js";

package/dist/transition/index.js

@@ -5,7 +5,7 @@ export { generateFixPlan, hasFixPlanProgress, parseFixPlan, mergeFixPlanProgress
 // Tech stack detection
 export { detectTechStack, customizeAgentMd } from "./tech-stack.js";
 // Artifacts
-export { findArtifactsDir, validateArtifacts } from "./artifacts.js";
+export { findArtifactsDir } from "./artifacts.js";
 // Context
 export { extractSection, extractProjectContext, generateProjectContextMd, generatePrompt, } from "./context.js";
 // Specs changelog

package/dist/utils/state.d.ts

@@ -21,6 +21,4 @@ export declare function readState(projectDir: string): Promise<BmalphState | nul
 export declare function writeState(projectDir: string, state: BmalphState): Promise<void>;
 export declare function getPhaseLabel(phase: number): string;
 export declare function getPhaseInfo(phase: number): PhaseInfo;
-/** @deprecated Use RalphLoopStatus from validate.ts instead */
-export type RalphStatus = RalphLoopStatus;
 export declare function readRalphStatus(projectDir: string): Promise<RalphLoopStatus>;

package/dist/utils/validate.js

@@ -176,6 +176,7 @@ const BASH_STATUS_MAP = {
     stopped: "blocked",
     completed: "completed",
     success: "completed",
+    graceful_exit: "completed",
 };
 export function normalizeRalphStatus(data) {
     assertObject(data, "normalizeRalphStatus");

package/dist/watch/dashboard.d.ts

@@ -0,0 +1,4 @@
+import type { WatchOptions } from "./types.js";
+export declare function createRefreshCallback(projectDir: string, write: (s: string) => void): () => Promise<void>;
+export declare function setupTerminal(): () => void;
+export declare function startDashboard(options: WatchOptions): Promise<void>;

package/dist/watch/dashboard.js

@@ -0,0 +1,60 @@
+import { readDashboardState } from "./state-reader.js";
+import { renderDashboard } from "./renderer.js";
+import { FileWatcher } from "./file-watcher.js";
+const CLEAR_SCREEN = "\x1B[2J\x1B[H";
+const HIDE_CURSOR = "\x1B[?25l";
+const SHOW_CURSOR = "\x1B[?25h";
+export function createRefreshCallback(projectDir, write) {
+    return async () => {
+        const state = await readDashboardState(projectDir);
+        const output = renderDashboard(state);
+        write(CLEAR_SCREEN + output + "\n");
+    };
+}
+export function setupTerminal() {
+    if (process.stdout.isTTY) {
+        process.stdout.write(HIDE_CURSOR);
+    }
+    return () => {
+        if (process.stdout.isTTY) {
+            process.stdout.write(SHOW_CURSOR);
+        }
+        if (process.stdin.isTTY && process.stdin.setRawMode) {
+            process.stdin.setRawMode(false);
+        }
+        process.stdin.pause();
+    };
+}
+export async function startDashboard(options) {
+    const { projectDir, interval } = options;
+    const cleanup = setupTerminal();
+    const refresh = createRefreshCallback(projectDir, (s) => process.stdout.write(s));
+    const watcher = new FileWatcher(refresh, interval);
+    return new Promise((resolve) => {
+        const stop = () => {
+            watcher.stop();
+            cleanup();
+            resolve();
+        };
+        if (process.stdin.isTTY && process.stdin.setRawMode) {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.setEncoding("utf-8");
+            process.stdin.on("data", (data) => {
+                if (data === "q" || data === "\x03") {
+                    stop();
+                }
+            });
+        }
+        const onResize = () => {
+            void refresh();
+        };
+        process.stdout.on("resize", onResize);
+        const onSignal = () => {
+            stop();
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+        watcher.start();
+    });
+}

package/dist/watch/file-watcher.d.ts

@@ -0,0 +1,9 @@
+export declare class FileWatcher {
+    private intervalId;
+    private readonly intervalMs;
+    private readonly callback;
+    constructor(callback: () => void | Promise<void>, intervalMs?: number);
+    start(): void;
+    stop(): void;
+    private tick;
+}

package/dist/watch/file-watcher.js

@@ -0,0 +1,27 @@
+export class FileWatcher {
+    intervalId = null;
+    intervalMs;
+    callback;
+    constructor(callback, intervalMs = 2000) {
+        this.callback = callback;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        void this.tick();
+        this.intervalId = setInterval(() => void this.tick(), this.intervalMs);
+    }
+    stop() {
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    async tick() {
+        try {
+            await this.callback();
+        }
+        catch {
+            // Swallow errors to keep polling alive
+        }
+    }
+}

package/dist/watch/renderer.d.ts

@@ -0,0 +1,16 @@
+import type { DashboardState, LoopInfo, CircuitBreakerInfo, StoryProgress, AnalysisInfo, LogEntry, ExecutionProgress, SessionInfo } from "./types.js";
+export declare function padRight(str: string, len: number): string;
+export declare function progressBar(completed: number, total: number, width: number): string;
+export declare function formatSessionAge(createdAt: string): string;
+export declare function formatStatus(status: string): string;
+export declare function formatCBState(state: string): string;
+export declare function box(title: string, lines: string[], cols: number): string;
+export declare function renderHeader(cols: number): string;
+export declare function renderLoopPanel(loop: LoopInfo | null, execution: ExecutionProgress | null, session: SessionInfo | null, cols: number): string;
+export declare function renderCircuitBreakerPanel(cb: CircuitBreakerInfo | null, cols: number): string;
+export declare function renderStoriesPanel(stories: StoryProgress | null, cols: number): string;
+export declare function renderSideBySide(left: string, right: string, cols: number): string;
+export declare function renderAnalysisPanel(analysis: AnalysisInfo | null, cols: number): string;
+export declare function renderLogsPanel(logs: LogEntry[], cols: number): string;
+export declare function renderFooter(lastUpdated: Date, cols: number): string;
+export declare function renderDashboard(state: DashboardState, cols?: number): string;