bmalph 1.0.0 → 2.2.1

package/dist/commands/doctor.js

@@ -1,67 +1,55 @@
 import chalk from "chalk";
-import { access, readFile, stat } from "fs/promises";
+import { readFile, stat } from "fs/promises";
+import { exists } from "../utils/file-system.js";
 import { join } from "path";
 import { readJsonFile } from "../utils/json.js";
-export async function doctorCommand() {
-    try {
-        await runDoctor();
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(chalk.red(`Error: ${message}`));
-        process.exit(1);
-    }
-}
-async function runDoctor() {
-    const projectDir = process.cwd();
-    const results = [];
-    // 1. Node version
-    const major = parseInt(process.versions.node.split(".")[0]);
-    results.push({
-        label: "Node version >= 20",
-        passed: major >= 20,
-        detail: major >= 20 ? `v${process.versions.node}` : `got v${process.versions.node}`,
-    });
-    // 2. bash available
-    const bashAvailable = await checkBashAvailable();
-    results.push({
-        label: "bash available",
-        passed: bashAvailable,
-        detail: bashAvailable ? undefined : "bash not found in PATH",
+import { readConfig } from "../utils/config.js";
+import { getBundledVersions } from "../installer.js";
+import { checkUpstream, getSkipReason } from "../utils/github.js";
+import { isEnoent, formatError, withErrorHandling } from "../utils/errors.js";
+import { validateCircuitBreakerState, validateRalphSession, validateRalphApiStatus, } from "../utils/validate.js";
+import { SESSION_AGE_WARNING_MS, API_USAGE_WARNING_PERCENT, CONFIG_FILE, RALPH_STATUS_FILE, } from "../utils/constants.js";
+export async function doctorCommand(options) {
+    await withErrorHandling(async () => {
+        const { failed } = await runDoctor(options);
+        if (!options.json && failed > 0) {
+            process.exitCode = 1;
+        }
     });
-    // 3. config.json exists and valid
-    const configResult = await checkConfig(projectDir);
-    results.push(configResult);
-    // 4. _bmad/ directory with expected structure
-    const bmadResult = await checkDir(join(projectDir, "_bmad"), "_bmad/ directory present");
-    results.push(bmadResult);
-    // 5. .ralph/ralph_loop.sh present and has content
-    const loopResult = await checkFileHasContent(join(projectDir, ".ralph/ralph_loop.sh"), "ralph_loop.sh present and has content");
-    results.push(loopResult);
-    // 6. .ralph/lib/ present
-    const libResult = await checkDir(join(projectDir, ".ralph/lib"), ".ralph/lib/ directory present");
-    results.push(libResult);
-    // 7. .claude/commands/bmalph.md present
-    const slashResult = await checkFileExists(join(projectDir, ".claude/commands/bmalph.md"), ".claude/commands/bmalph.md present");
-    results.push(slashResult);
-    // 8. CLAUDE.md contains BMAD snippet
-    const claudeMdResult = await checkClaudeMd(projectDir);
-    results.push(claudeMdResult);
-    // 9. .gitignore has required entries
-    const gitignoreResult = await checkGitignore(projectDir);
-    results.push(gitignoreResult);
-    // 10. Version marker check
-    const versionResult = await checkVersionMarker(projectDir);
-    results.push(versionResult);
+}
+export async function runDoctor(options) {
+    const projectDir = options.projectDir;
+    // Run all checks from the registry
+    const results = await Promise.all(CHECK_REGISTRY.map((check) => check.run(projectDir)));
     // Output
+    const passed = results.filter((r) => r.passed).length;
+    const failed = results.filter((r) => !r.passed).length;
+    if (options.json) {
+        const output = {
+            results: results.map((r) => ({
+                label: r.label,
+                passed: r.passed,
+                ...(r.detail && { detail: r.detail }),
+                ...(r.hint && { hint: r.hint }),
+            })),
+            summary: {
+                passed,
+                failed,
+                total: results.length,
+            },
+        };
+        console.log(JSON.stringify(output, null, 2));
+        return { passed, failed };
+    }
     console.log(chalk.bold("bmalph doctor\n"));
     for (const r of results) {
         const icon = r.passed ? chalk.green("\u2713") : chalk.red("\u2717");
         const detail = r.detail ? chalk.dim(` (${r.detail})`) : "";
         console.log(`  ${icon} ${r.label}${detail}`);
+        if (!r.passed && r.hint) {
+            console.log(chalk.yellow(`     → ${r.hint}`));
+        }
     }
-    const passed = results.filter((r) => r.passed).length;
-    const failed = results.filter((r) => !r.passed).length;
     console.log("");
     if (failed === 0) {
         console.log(chalk.green(`${passed} passed, all checks OK`));
@@ -69,6 +57,7 @@ async function runDoctor() {
     else {
         console.log(`${chalk.green(`${passed} passed`)}, ${chalk.red(`${failed} failed`)}`);
     }
+    return { passed, failed };
 }
 async function checkBashAvailable() {
     const { execSync } = await import("child_process");
@@ -81,55 +70,104 @@ async function checkBashAvailable() {
         return false;
     }
 }
+// =============================================================================
+// Check functions - each conforms to CheckFunction signature
+// =============================================================================
+async function checkNodeVersion(_projectDir) {
+    const major = parseInt(process.versions.node.split(".")[0]);
+    return {
+        label: "Node version >= 20",
+        passed: major >= 20,
+        detail: major >= 20 ? `v${process.versions.node}` : `got v${process.versions.node}`,
+        hint: major >= 20 ? undefined : "Install Node.js 20+ from nodejs.org or run: nvm install 20",
+    };
+}
+async function checkBash(_projectDir) {
+    const bashAvailable = await checkBashAvailable();
+    return {
+        label: "bash available",
+        passed: bashAvailable,
+        detail: bashAvailable ? undefined : "bash not found in PATH",
+        hint: bashAvailable
+            ? undefined
+            : process.platform === "win32"
+                ? "Install Git Bash or WSL: https://git-scm.com/downloads"
+                : "Install bash via your package manager (apt, brew, etc.)",
+    };
+}
+async function checkBmadDir(projectDir) {
+    return checkDir(join(projectDir, "_bmad"), "_bmad/ directory present", "Run: bmalph init");
+}
+async function checkRalphLoop(projectDir) {
+    return checkFileHasContent(join(projectDir, ".ralph/ralph_loop.sh"), "ralph_loop.sh present and has content", "Run: bmalph upgrade");
+}
+async function checkRalphLib(projectDir) {
+    return checkDir(join(projectDir, ".ralph/lib"), ".ralph/lib/ directory present", "Run: bmalph upgrade");
+}
+async function checkSlashCommand(projectDir) {
+    return checkFileExists(join(projectDir, ".claude/commands/bmalph.md"), ".claude/commands/bmalph.md present", "Run: bmalph init");
+}
 async function checkConfig(projectDir) {
-    const path = join(projectDir, "bmalph/config.json");
+    const label = "bmalph/config.json exists and valid";
+    const hint = "Run: bmalph init";
+    const path = join(projectDir, CONFIG_FILE);
     try {
         const data = await readJsonFile(path);
         if (data === null) {
-            return { label: "bmalph/config.json exists and valid", passed: false, detail: "file not found" };
+            return { label, passed: false, detail: "file not found", hint };
         }
-        return { label: "bmalph/config.json exists and valid", passed: true };
+        return { label, passed: true };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : "invalid";
-        return { label: "bmalph/config.json exists and valid", passed: false, detail: msg };
+        return { label, passed: false, detail: msg, hint };
     }
 }
-async function checkDir(dirPath, label) {
+async function checkDir(dirPath, label, hint) {
     try {
         const s = await stat(dirPath);
         return { label, passed: s.isDirectory() };
     }
-    catch {
-        return { label, passed: false, detail: "not found" };
+    catch (err) {
+        if (isEnoent(err)) {
+            return { label, passed: false, detail: "not found", hint };
+        }
+        return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
     }
 }
-async function checkFileExists(filePath, label) {
-    try {
-        await access(filePath);
+async function checkFileExists(filePath, label, hint) {
+    if (await exists(filePath)) {
         return { label, passed: true };
     }
-    catch {
-        return { label, passed: false, detail: "not found" };
-    }
+    return { label, passed: false, detail: "not found", hint };
 }
-async function checkFileHasContent(filePath, label) {
+async function checkFileHasContent(filePath, label, hint) {
     try {
         const content = await readFile(filePath, "utf-8");
         return { label, passed: content.trim().length > 0 };
     }
-    catch {
-        return { label, passed: false, detail: "not found" };
+    catch (err) {
+        if (isEnoent(err)) {
+            return { label, passed: false, detail: "not found", hint };
+        }
+        return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
     }
 }
 async function checkClaudeMd(projectDir) {
     const label = "CLAUDE.md contains BMAD snippet";
+    const hint = "Run: bmalph init";
     try {
         const content = await readFile(join(projectDir, "CLAUDE.md"), "utf-8");
-        return { label, passed: content.includes("BMAD-METHOD Integration") };
+        if (content.includes("BMAD-METHOD Integration")) {
+            return { label, passed: true };
+        }
+        return { label, passed: false, detail: "missing BMAD-METHOD Integration section", hint };
     }
-    catch {
-        return { label, passed: false, detail: "CLAUDE.md not found" };
+    catch (err) {
+        if (isEnoent(err)) {
+            return { label, passed: false, detail: "CLAUDE.md not found", hint };
+        }
+        return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
     }
 }
 async function checkGitignore(projectDir) {
@@ -137,18 +175,42 @@ async function checkGitignore(projectDir) {
     const required = [".ralph/logs/", "_bmad-output/"];
     try {
         const content = await readFile(join(projectDir, ".gitignore"), "utf-8");
-        const missing = required.filter((e) => !content.includes(e));
+        // Use line-by-line comparison to avoid substring matching issues
+        const existingLines = new Set(content
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean));
+        const missing = required.filter((e) => !existingLines.has(e));
         if (missing.length === 0) {
             return { label, passed: true };
         }
-        return { label, passed: false, detail: `missing: ${missing.join(", ")}` };
+        return {
+            label,
+            passed: false,
+            detail: `missing: ${missing.join(", ")}`,
+            hint: `Add to .gitignore: ${missing.join(" ")}`,
+        };
     }
-    catch {
-        return { label, passed: false, detail: ".gitignore not found" };
+    catch (err) {
+        if (isEnoent(err)) {
+            return {
+                label,
+                passed: false,
+                detail: ".gitignore not found",
+                hint: "Create .gitignore with: .ralph/logs/ _bmad-output/",
+            };
+        }
+        return {
+            label,
+            passed: false,
+            detail: `error: ${formatError(err)}`,
+            hint: "Check file permissions on .gitignore",
+        };
     }
 }
 async function checkVersionMarker(projectDir) {
     const label = "version marker matches";
+    const hint = "Run: bmalph upgrade";
     try {
         const content = await readFile(join(projectDir, ".ralph/ralph_loop.sh"), "utf-8");
         const match = content.match(/# bmalph-version: (.+)/);
@@ -160,9 +222,216 @@ async function checkVersionMarker(projectDir) {
         if (match[1].trim() === current) {
             return { label, passed: true, detail: `v${current}` };
         }
-        return { label, passed: false, detail: `installed: ${match[1].trim()}, current: ${current}` };
+        return {
+            label,
+            passed: false,
+            detail: `installed: ${match[1].trim()}, current: ${current}`,
+            hint,
+        };
     }
-    catch {
-        return { label, passed: true, detail: "no marker found" };
+    catch (err) {
+        if (isEnoent(err)) {
+            return { label, passed: true, detail: "no marker found" };
+        }
+        return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
+    }
+}
+async function checkUpstreamVersions(projectDir) {
+    const label = "upstream versions tracked";
+    const hint = "Run: bmalph upgrade";
+    try {
+        const config = await readConfig(projectDir);
+        if (!config) {
+            return { label, passed: false, detail: "config not found", hint: "Run: bmalph init" };
+        }
+        if (!config.upstreamVersions) {
+            return { label, passed: true, detail: "not tracked (pre-1.2.0 install)" };
+        }
+        const bundled = getBundledVersions();
+        const { bmadCommit } = config.upstreamVersions;
+        const bmadMatch = bmadCommit === bundled.bmadCommit;
+        if (bmadMatch) {
+            return {
+                label,
+                passed: true,
+                detail: `BMAD:${bmadCommit.slice(0, 8)}`,
+            };
+        }
+        return {
+            label,
+            passed: false,
+            detail: `outdated: BMAD:${bmadCommit.slice(0, 8)}→${bundled.bmadCommit.slice(0, 8)}`,
+            hint,
+        };
+    }
+    catch (err) {
+        return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
+    }
+}
+async function checkCircuitBreaker(projectDir) {
+    const label = "circuit breaker";
+    const statePath = join(projectDir, ".ralph/.circuit_breaker_state");
+    try {
+        const content = await readFile(statePath, "utf-8");
+        const parsed = JSON.parse(content);
+        const state = validateCircuitBreakerState(parsed);
+        if (state.state === "CLOSED") {
+            return {
+                label,
+                passed: true,
+                detail: `CLOSED (${state.consecutive_no_progress} loops without progress)`,
+            };
+        }
+        if (state.state === "HALF_OPEN") {
+            return { label, passed: true, detail: `HALF_OPEN - monitoring` };
+        }
+        // OPEN state is a failure
+        return {
+            label,
+            passed: false,
+            detail: `OPEN - ${state.reason ?? "stagnation detected"}`,
+            hint: "Ralph detected stagnation. Review logs with: bmalph status",
+        };
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            return { label, passed: true, detail: "not running" };
+        }
+        return {
+            label,
+            passed: false,
+            detail: "corrupt state file",
+            hint: "Delete .ralph/.circuit_breaker_state and restart Ralph",
+        };
+    }
+}
+async function checkRalphSession(projectDir) {
+    const label = "Ralph session";
+    const sessionPath = join(projectDir, ".ralph/.ralph_session");
+    try {
+        const content = await readFile(sessionPath, "utf-8");
+        const parsed = JSON.parse(content);
+        const session = validateRalphSession(parsed);
+        if (!session.session_id || session.session_id === "") {
+            return { label, passed: true, detail: "no active session" };
+        }
+        const createdAt = new Date(session.created_at);
+        const now = new Date();
+        const ageMs = now.getTime() - createdAt.getTime();
+        // Handle negative age (future timestamp) gracefully
+        if (ageMs < 0) {
+            return {
+                label,
+                passed: false,
+                detail: "invalid timestamp (future)",
+                hint: "Delete .ralph/.ralph_session to reset",
+            };
+        }
+        const ageHours = Math.floor(ageMs / (1000 * 60 * 60));
+        const ageMinutes = Math.floor((ageMs % (1000 * 60 * 60)) / (1000 * 60));
+        const ageStr = ageHours > 0 ? `${ageHours}h${ageMinutes}m` : `${ageMinutes}m`;
+        // Warn if session is older than threshold
+        const maxAgeHours = Math.floor(SESSION_AGE_WARNING_MS / (1000 * 60 * 60));
+        if (ageMs >= SESSION_AGE_WARNING_MS) {
+            return {
+                label,
+                passed: false,
+                detail: `${ageStr} old (max ${maxAgeHours}h)`,
+                hint: "Session is stale. Start a fresh Ralph session",
+            };
+        }
+        return { label, passed: true, detail: ageStr };
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            return { label, passed: true, detail: "no active session" };
+        }
+        return {
+            label,
+            passed: false,
+            detail: "corrupt session file",
+            hint: "Delete .ralph/.ralph_session to reset",
+        };
+    }
+}
+async function checkApiCalls(projectDir) {
+    const label = "API calls this hour";
+    const statusPath = join(projectDir, RALPH_STATUS_FILE);
+    try {
+        const content = await readFile(statusPath, "utf-8");
+        const parsed = JSON.parse(content);
+        const status = validateRalphApiStatus(parsed);
+        const calls = status.calls_made_this_hour;
+        const max = status.max_calls_per_hour;
+        // Avoid division by zero
+        if (max <= 0) {
+            return { label, passed: true, detail: `${calls}/unlimited` };
+        }
+        const percentage = (calls / max) * 100;
+        // Warn if approaching limit
+        if (percentage >= API_USAGE_WARNING_PERCENT) {
+            return {
+                label,
+                passed: false,
+                detail: `${calls}/${max} (approaching limit)`,
+                hint: "Wait for rate limit reset or increase API quota",
+            };
+        }
+        return { label, passed: true, detail: `${calls}/${max}` };
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            return { label, passed: true, detail: "not running" };
+        }
+        return {
+            label,
+            passed: false,
+            detail: "corrupt status file",
+            hint: "Delete .ralph/status.json to reset",
+        };
+    }
+}
+async function checkUpstreamGitHubStatus(_projectDir) {
+    const label = "upstream status";
+    try {
+        const bundled = getBundledVersions();
+        const result = await checkUpstream(bundled);
+        // Check if request failed
+        if (result.bmad === null) {
+            const reason = getSkipReason(result.errors);
+            return { label, passed: true, detail: `skipped: ${reason}` };
+        }
+        return {
+            label,
+            passed: true,
+            detail: `BMAD: ${result.bmad.isUpToDate ? "up to date" : "behind"}`,
+        };
+    }
+    catch (err) {
+        return { label, passed: true, detail: `skipped: ${formatError(err)}` };
     }
 }
+// =============================================================================
+// Check Registry - defines all checks in execution order
+// =============================================================================
+/**
+ * Registry of all doctor checks in execution order.
+ * Each check has a unique ID and a run function that takes a project directory.
+ */
+export const CHECK_REGISTRY = [
+    { id: "node-version", run: checkNodeVersion },
+    { id: "bash-available", run: checkBash },
+    { id: "config-valid", run: checkConfig },
+    { id: "bmad-dir", run: checkBmadDir },
+    { id: "ralph-loop", run: checkRalphLoop },
+    { id: "ralph-lib", run: checkRalphLib },
+    { id: "slash-command", run: checkSlashCommand },
+    { id: "claude-md", run: checkClaudeMd },
+    { id: "gitignore", run: checkGitignore },
+    { id: "version-marker", run: checkVersionMarker },
+    { id: "upstream-versions", run: checkUpstreamVersions },
+    { id: "circuit-breaker", run: checkCircuitBreaker },
+    { id: "ralph-session", run: checkRalphSession },
+    { id: "api-calls", run: checkApiCalls },
+    { id: "upstream-github", run: checkUpstreamGitHubStatus },
+];

package/dist/commands/init.d.ts

@@ -1,6 +1,8 @@
 interface InitOptions {
     name?: string;
     description?: string;
+    dryRun?: boolean;
+    projectDir: string;
 }
 export declare function initCommand(options: InitOptions): Promise<void>;
 export {};

package/dist/commands/init.js

@@ -1,27 +1,40 @@
 import chalk from "chalk";
 import inquirer from "inquirer";
 import { writeConfig } from "../utils/config.js";
-import { installProject, mergeClaudeMd, isInitialized } from "../installer.js";
+import { installProject, mergeClaudeMd, isInitialized, previewInstall, getBundledVersions, } from "../installer.js";
+import { formatDryRunSummary } from "../utils/dryrun.js";
+import { validateProjectName } from "../utils/validate.js";
+import { withErrorHandling } from "../utils/errors.js";
 export async function initCommand(options) {
-    try {
-        await runInit(options);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(chalk.red(`Error: ${message}`));
-        process.exit(1);
-    }
+    await withErrorHandling(() => runInit(options));
 }
 async function runInit(options) {
-    const projectDir = process.cwd();
+    const projectDir = options.projectDir;
     if (await isInitialized(projectDir)) {
         console.log(chalk.yellow("bmalph is already initialized in this project."));
-        console.log("Use 'bmalph reset --hard' to reinitialize.");
+        console.log("Use 'bmalph upgrade' to update bundled assets to the latest version.");
+        return;
+    }
+    // Handle dry-run mode
+    if (options.dryRun) {
+        const preview = await previewInstall(projectDir);
+        const actions = [
+            ...preview.wouldCreate.map((p) => ({ type: "create", path: p })),
+            ...preview.wouldModify.map((p) => ({ type: "modify", path: p })),
+            ...preview.wouldSkip.map((p) => ({ type: "skip", path: p })),
+        ];
+        console.log(formatDryRunSummary(actions));
         return;
     }
     let name = options.name;
     let description = options.description;
     if (!name || !description) {
+        if (!process.stdin.isTTY) {
+            throw new Error("Non-interactive mode requires --name and --description flags");
+        }
+        // Derive default name from directory, with fallback for edge cases
+        const dirName = projectDir.split(/[/\\]/).pop();
+        const defaultName = dirName && dirName.trim() ? dirName : "my-project";
         const answers = await inquirer.prompt([
             ...(name
                 ? []
@@ -30,7 +43,7 @@ async function runInit(options) {
                         type: "input",
                         name: "name",
                         message: "Project name:",
-                        default: projectDir.split(/[/\\]/).pop(),
+                        default: defaultName,
                     },
                 ]),
             ...(description
@@ -46,15 +59,28 @@ async function runInit(options) {
         name = name ?? answers.name;
         description = description ?? answers.description;
     }
+    // Validate project name (filesystem safety, reserved names, etc.)
+    if (!name) {
+        throw new Error("Project name cannot be empty");
+    }
+    const validatedName = validateProjectName(name);
     console.log(chalk.blue("\nInstalling BMAD + Ralph..."));
     await installProject(projectDir);
+    const bundledVersions = getBundledVersions();
     const config = {
-        name: name,
+        name: validatedName,
         description: description ?? "",
         createdAt: new Date().toISOString(),
+        upstreamVersions: bundledVersions,
     };
-    await writeConfig(projectDir, config);
-    await mergeClaudeMd(projectDir);
+    try {
+        await writeConfig(projectDir, config);
+        await mergeClaudeMd(projectDir);
+    }
+    catch (err) {
+        throw new Error(`Partial installation: files were copied but configuration failed. ` +
+            `Run 'bmalph init' again to retry.`, { cause: err });
+    }
     console.log(chalk.green("\nbmalph initialized successfully!"));
     console.log(`\n  Project: ${chalk.bold(config.name)}`);
     console.log(`\nInstalled:`);

package/dist/commands/status.d.ts

@@ -1 +1,7 @@
-export declare function statusCommand(): Promise<void>;
+interface StatusOptions {
+    json?: boolean;
+    projectDir: string;
+}
+export declare function statusCommand(options: StatusOptions): Promise<void>;
+export declare function runStatus(options: StatusOptions): Promise<void>;
+export {};