bmalph 1.0.0 → 2.2.1

package/dist/installer.js

@@ -1,55 +1,109 @@
-import { cp, mkdir, readFile, readdir, writeFile, access } from "fs/promises";
+import { cp, mkdir, readFile, readdir, rm, chmod, rename } from "fs/promises";
 import { readFileSync } from "fs";
 import { join, basename, dirname } from "path";
 import { fileURLToPath } from "url";
+import { debug, warn } from "./utils/logger.js";
+import { formatError, isEnoent } from "./utils/errors.js";
+import { exists, atomicWriteFile } from "./utils/file-system.js";
+import { STATE_DIR, CONFIG_FILE } from "./utils/constants.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 export function getPackageVersion() {
     const pkgPath = join(__dirname, "..", "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-    return pkg.version;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function getBundledVersions() {
+    const versionsPath = join(__dirname, "..", "bundled-versions.json");
+    try {
+        const versions = JSON.parse(readFileSync(versionsPath, "utf-8"));
+        if (!versions || typeof versions.bmadCommit !== "string") {
+            throw new Error("Invalid bundled-versions.json structure: missing bmadCommit");
+        }
+        return {
+            bmadCommit: versions.bmadCommit,
+        };
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.includes("Invalid bundled-versions.json")) {
+            throw err;
+        }
+        throw new Error(`Failed to read bundled-versions.json at ${versionsPath}`, { cause: err });
+    }
 }
-export function getBmadDir() {
+export function getBundledBmadDir() {
     return join(__dirname, "..", "bmad");
 }
-export function getRalphDir() {
+export function getBundledRalphDir() {
     return join(__dirname, "..", "ralph");
 }
 export function getSlashCommandsDir() {
     return join(__dirname, "..", "slash-commands");
 }
+const TEMPLATE_PLACEHOLDERS = {
+    "PROMPT.md": "[YOUR PROJECT NAME]",
+    "AGENT.md": "pip install -r requirements.txt",
+};
+async function isTemplateCustomized(filePath, templateName) {
+    const placeholder = TEMPLATE_PLACEHOLDERS[templateName];
+    if (!placeholder)
+        return false;
+    try {
+        const content = await readFile(filePath, "utf-8");
+        return !content.includes(placeholder);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return false;
+        throw err;
+    }
+}
 export async function copyBundledAssets(projectDir) {
-    const bmadDir = getBmadDir();
-    const ralphDir = getRalphDir();
+    const bmadDir = getBundledBmadDir();
+    const ralphDir = getBundledRalphDir();
     const slashCommandsDir = getSlashCommandsDir();
     // Validate source directories exist
-    try {
-        await access(bmadDir);
-    }
-    catch {
+    if (!(await exists(bmadDir))) {
         throw new Error(`BMAD source directory not found at ${bmadDir}. Package may be corrupted.`);
     }
-    try {
-        await access(ralphDir);
-    }
-    catch {
+    if (!(await exists(ralphDir))) {
         throw new Error(`Ralph source directory not found at ${ralphDir}. Package may be corrupted.`);
     }
+    if (!(await exists(slashCommandsDir))) {
+        throw new Error(`Slash commands directory not found at ${slashCommandsDir}. Package may be corrupted.`);
+    }
+    // Atomic copy: write to temp dir, then swap with old
+    const bmadDest = join(projectDir, "_bmad");
+    const bmadTemp = join(projectDir, "_bmad.new");
+    await rm(bmadTemp, { recursive: true, force: true });
+    await cp(bmadDir, bmadTemp, { recursive: true, dereference: false });
     try {
-        await access(slashCommandsDir);
+        await rm(bmadDest, { recursive: true, force: true });
+        await rename(bmadTemp, bmadDest);
     }
-    catch {
-        throw new Error(`Slash commands directory not found at ${slashCommandsDir}. Package may be corrupted.`);
+    catch (err) {
+        // If rename fails, attempt to restore from temp
+        try {
+            await rename(bmadTemp, bmadDest);
+        }
+        catch {
+            // Best effort restore failed
+        }
+        throw err;
     }
-    // Copy BMAD files → _bmad/
-    await cp(bmadDir, join(projectDir, "_bmad"), { recursive: true });
     // Generate combined manifest from module-help.csv files
     await generateManifests(projectDir);
     // Generate _bmad/config.yaml
     const projectName = await deriveProjectName(projectDir);
-    await writeFile(join(projectDir, "_bmad/config.yaml"), `# BMAD Configuration - Generated by bmalph
+    const escapedName = projectName.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    await atomicWriteFile(join(projectDir, "_bmad/config.yaml"), `# BMAD Configuration - Generated by bmalph
 platform: claude-code
-project_name: ${projectName}
+project_name: "${escapedName}"
 output_folder: _bmad-output
 user_name: BMad
 communication_language: English
@@ -63,42 +117,91 @@ modules:
 `);
     // Copy Ralph templates → .ralph/
     await mkdir(join(projectDir, ".ralph"), { recursive: true });
-    await cp(join(ralphDir, "templates/PROMPT.md"), join(projectDir, ".ralph/PROMPT.md"));
-    await cp(join(ralphDir, "templates/AGENT.md"), join(projectDir, ".ralph/@AGENT.md"));
+    // Preserve customized PROMPT.md and @AGENT.md on upgrade
+    const promptCustomized = await isTemplateCustomized(join(projectDir, ".ralph/PROMPT.md"), "PROMPT.md");
+    const agentCustomized = await isTemplateCustomized(join(projectDir, ".ralph/@AGENT.md"), "AGENT.md");
+    if (!promptCustomized) {
+        await cp(join(ralphDir, "templates/PROMPT.md"), join(projectDir, ".ralph/PROMPT.md"), {
+            dereference: false,
+        });
+    }
+    if (!agentCustomized) {
+        await cp(join(ralphDir, "templates/AGENT.md"), join(projectDir, ".ralph/@AGENT.md"), {
+            dereference: false,
+        });
+    }
+    await cp(join(ralphDir, "RALPH-REFERENCE.md"), join(projectDir, ".ralph/RALPH-REFERENCE.md"), {
+        dereference: false,
+    });
+    // Copy .ralphrc from template (skip if user has customized it)
+    const ralphrcDest = join(projectDir, ".ralph/.ralphrc");
+    if (!(await exists(ralphrcDest))) {
+        await cp(join(ralphDir, "templates/ralphrc.template"), ralphrcDest, { dereference: false });
+    }
     // Copy Ralph loop and lib → .ralph/
     // Add version marker to ralph_loop.sh
     const loopContent = await readFile(join(ralphDir, "ralph_loop.sh"), "utf-8");
     const markerLine = `# bmalph-version: ${getPackageVersion()}`;
+    // Use .* to handle empty version (edge case) and EOF without newline
     const markedContent = loopContent.includes("# bmalph-version:")
-        ? loopContent.replace(/# bmalph-version: .+/, markerLine)
+        ? loopContent.replace(/# bmalph-version:.*/, markerLine)
         : loopContent.replace(/^(#!.+\r?\n)/, `$1${markerLine}\n`);
-    await writeFile(join(projectDir, ".ralph/ralph_loop.sh"), markedContent);
-    await cp(join(ralphDir, "lib"), join(projectDir, ".ralph/lib"), { recursive: true });
+    await atomicWriteFile(join(projectDir, ".ralph/ralph_loop.sh"), markedContent);
+    await chmod(join(projectDir, ".ralph/ralph_loop.sh"), 0o755);
+    await rm(join(projectDir, ".ralph/lib"), { recursive: true, force: true });
+    await cp(join(ralphDir, "lib"), join(projectDir, ".ralph/lib"), {
+        recursive: true,
+        dereference: false,
+    });
+    // Copy Ralph utilities → .ralph/
+    await cp(join(ralphDir, "ralph_import.sh"), join(projectDir, ".ralph/ralph_import.sh"), {
+        dereference: false,
+    });
+    await chmod(join(projectDir, ".ralph/ralph_import.sh"), 0o755);
+    await cp(join(ralphDir, "ralph_monitor.sh"), join(projectDir, ".ralph/ralph_monitor.sh"), {
+        dereference: false,
+    });
+    await chmod(join(projectDir, ".ralph/ralph_monitor.sh"), 0o755);
     // Install all slash commands → .claude/commands/
-    await mkdir(join(projectDir, ".claude/commands"), { recursive: true });
+    // Clean stale bmalph-owned commands before copying (preserve user-created commands)
+    const commandsDir = join(projectDir, ".claude/commands");
+    await mkdir(commandsDir, { recursive: true });
     const slashFiles = await readdir(slashCommandsDir);
-    for (const file of slashFiles) {
-        if (file.endsWith(".md")) {
-            await cp(join(slashCommandsDir, file), join(projectDir, ".claude/commands", file));
+    const bundledCommandNames = new Set(slashFiles.filter((f) => f.endsWith(".md")));
+    try {
+        const existingCommands = await readdir(commandsDir);
+        for (const file of existingCommands) {
+            if (file.endsWith(".md") && bundledCommandNames.has(file)) {
+                await rm(join(commandsDir, file), { force: true });
+            }
         }
     }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+    }
+    for (const file of bundledCommandNames) {
+        await cp(join(slashCommandsDir, file), join(commandsDir, file), { dereference: false });
+    }
     // Update .gitignore
     await updateGitignore(projectDir);
-    return {
-        updatedPaths: [
-            "_bmad/",
-            ".ralph/ralph_loop.sh",
-            ".ralph/lib/",
-            ".ralph/PROMPT.md",
-            ".ralph/@AGENT.md",
-            ".claude/commands/",
-            ".gitignore",
-        ],
-    };
+    const updatedPaths = [
+        "_bmad/",
+        ".ralph/ralph_loop.sh",
+        ".ralph/ralph_import.sh",
+        ".ralph/ralph_monitor.sh",
+        ".ralph/lib/",
+        ...(!promptCustomized ? [".ralph/PROMPT.md"] : []),
+        ...(!agentCustomized ? [".ralph/@AGENT.md"] : []),
+        ".ralph/RALPH-REFERENCE.md",
+        ".claude/commands/",
+        ".gitignore",
+    ];
+    return { updatedPaths };
 }
 export async function installProject(projectDir) {
     // Create user directories (not overwritten by upgrade)
-    await mkdir(join(projectDir, "bmalph/state"), { recursive: true });
+    await mkdir(join(projectDir, STATE_DIR), { recursive: true });
     await mkdir(join(projectDir, ".ralph/specs"), { recursive: true });
     await mkdir(join(projectDir, ".ralph/logs"), { recursive: true });
     await mkdir(join(projectDir, ".ralph/docs/generated"), { recursive: true });
@@ -106,34 +209,62 @@ export async function installProject(projectDir) {
 }
 async function deriveProjectName(projectDir) {
     try {
-        const configPath = join(projectDir, "bmalph/config.json");
+        const configPath = join(projectDir, CONFIG_FILE);
         const raw = await readFile(configPath, "utf-8");
         const config = JSON.parse(raw);
         if (config.name)
             return config.name;
     }
-    catch {
-        // config.json doesn't exist or is invalid — fall through
+    catch (err) {
+        if (!isEnoent(err)) {
+            warn(`Could not read ${CONFIG_FILE}: ${formatError(err)}`);
+        }
     }
     return basename(projectDir);
 }
-async function generateManifests(projectDir) {
+export async function generateManifests(projectDir) {
     const configDir = join(projectDir, "_bmad/_config");
     await mkdir(configDir, { recursive: true });
     const coreHelpPath = join(projectDir, "_bmad/core/module-help.csv");
     const bmmHelpPath = join(projectDir, "_bmad/bmm/module-help.csv");
+    // Validate CSV files exist before reading
+    if (!(await exists(coreHelpPath))) {
+        throw new Error(`Core module-help.csv not found at ${coreHelpPath}. BMAD installation may be incomplete.`);
+    }
+    if (!(await exists(bmmHelpPath))) {
+        throw new Error(`BMM module-help.csv not found at ${bmmHelpPath}. BMAD installation may be incomplete.`);
+    }
     const coreContent = await readFile(coreHelpPath, "utf-8");
     const bmmContent = await readFile(bmmHelpPath, "utf-8");
     // Extract header from core (first line) and data lines from both
     const coreLines = coreContent.trimEnd().split(/\r?\n/);
     const bmmLines = bmmContent.trimEnd().split(/\r?\n/);
-    const header = coreLines[0];
-    const coreData = coreLines.slice(1).filter((l) => l.trim());
-    const bmmData = bmmLines.slice(1).filter((l) => l.trim());
+    if (!coreLines[0]?.trim()) {
+        throw new Error(`Core module-help.csv is empty at ${coreHelpPath}`);
+    }
+    if (!bmmLines[0]?.trim()) {
+        throw new Error(`BMM module-help.csv is empty at ${bmmHelpPath}`);
+    }
+    const normalize = (line) => line.replace(/,+$/, "");
+    const header = normalize(coreLines[0]);
+    const bmmHeader = normalize(bmmLines[0]);
+    // Validate headers match (warn if mismatch but continue)
+    if (header && bmmHeader && header !== bmmHeader) {
+        warn(`CSV header mismatch detected. BMAD modules may have incompatible formats.`);
+        debug(`CSV header mismatch details - core: "${header.slice(0, 50)}...", bmm: "${bmmHeader.slice(0, 50)}..."`);
+    }
+    const coreData = coreLines
+        .slice(1)
+        .filter((l) => l.trim())
+        .map(normalize);
+    const bmmData = bmmLines
+        .slice(1)
+        .filter((l) => l.trim())
+        .map(normalize);
     const combined = [header, ...coreData, ...bmmData].join("\n") + "\n";
-    await writeFile(join(configDir, "task-manifest.csv"), combined);
-    await writeFile(join(configDir, "workflow-manifest.csv"), combined);
-    await writeFile(join(configDir, "bmad-help.csv"), combined);
+    await atomicWriteFile(join(configDir, "task-manifest.csv"), combined);
+    await atomicWriteFile(join(configDir, "workflow-manifest.csv"), combined);
+    await atomicWriteFile(join(configDir, "bmad-help.csv"), combined);
 }
 async function updateGitignore(projectDir) {
     const gitignorePath = join(projectDir, ".gitignore");
@@ -141,17 +272,23 @@ async function updateGitignore(projectDir) {
     try {
         existing = await readFile(gitignorePath, "utf-8");
     }
-    catch {
-        // File doesn't exist, start fresh
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
     }
+    // Split into lines for exact comparison (avoid substring matching issues)
+    const existingLines = new Set(existing
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean));
     const entries = [".ralph/logs/", "_bmad-output/"];
-    const newEntries = entries.filter((e) => !existing.includes(e));
+    const newEntries = entries.filter((e) => !existingLines.has(e));
     if (newEntries.length === 0)
         return;
     const suffix = existing.length > 0 && !existing.endsWith("\n")
         ? "\n" + newEntries.join("\n") + "\n"
         : newEntries.join("\n") + "\n";
-    await writeFile(gitignorePath, existing + suffix);
+    await atomicWriteFile(gitignorePath, existing + suffix);
 }
 export async function mergeClaudeMd(projectDir) {
     const claudeMdPath = join(projectDir, "CLAUDE.md");
@@ -194,26 +331,128 @@ Use \`/bmalph\` to navigate phases. Use \`/bmad-help\` to discover all commands.
 | \`/sm\` | Scrum Master | Sprint planning, status, coordination |
 | \`/dev\` | Developer | Implementation, coding |
 | \`/ux-designer\` | UX Designer | User experience, wireframes |
-| \`/tea\` | Test Engineer | Test design, validation |
+| \`/qa\` | QA Engineer | Test automation, quality assurance |
 `;
     let existing = "";
     try {
         existing = await readFile(claudeMdPath, "utf-8");
     }
-    catch {
-        // File doesn't exist, that's fine
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
     }
     if (existing.includes("## BMAD-METHOD Integration")) {
-        return; // Already merged
+        // Replace stale section with current content, preserving content after it
+        const sectionStart = existing.indexOf("## BMAD-METHOD Integration");
+        const before = existing.slice(0, sectionStart);
+        const afterSection = existing.slice(sectionStart);
+        // Find the next level-2 heading after the BMAD section start
+        const nextHeadingMatch = afterSection.match(/\n## (?!BMAD-METHOD Integration)/);
+        const after = nextHeadingMatch ? afterSection.slice(nextHeadingMatch.index) : "";
+        await atomicWriteFile(claudeMdPath, before.trimEnd() + "\n" + snippet + after);
+        return;
     }
-    await writeFile(claudeMdPath, existing + snippet);
+    await atomicWriteFile(claudeMdPath, existing + snippet);
 }
 export async function isInitialized(projectDir) {
+    return exists(join(projectDir, CONFIG_FILE));
+}
+export async function previewInstall(projectDir) {
+    const wouldCreate = [];
+    const wouldModify = [];
+    const wouldSkip = [];
+    // Directories that would be created
+    const dirsToCreate = [
+        `${STATE_DIR}/`,
+        ".ralph/specs/",
+        ".ralph/logs/",
+        ".ralph/docs/generated/",
+        "_bmad/",
+        ".claude/commands/",
+    ];
+    for (const dir of dirsToCreate) {
+        if (await exists(join(projectDir, dir))) {
+            if (dir === "_bmad/" || dir === ".claude/commands/") {
+                wouldModify.push(dir);
+            }
+        }
+        else {
+            wouldCreate.push(dir);
+        }
+    }
+    // Files that would be created/modified
+    const filesToCheck = [
+        { path: ".ralph/PROMPT.md", isTemplate: true },
+        { path: ".ralph/@AGENT.md", isTemplate: true },
+        { path: ".ralph/ralph_loop.sh", isTemplate: false },
+        { path: CONFIG_FILE, isTemplate: false },
+    ];
+    for (const file of filesToCheck) {
+        if (await exists(join(projectDir, file.path))) {
+            if (file.isTemplate) {
+                wouldModify.push(file.path);
+            }
+        }
+        else {
+            wouldCreate.push(file.path);
+        }
+    }
+    // .gitignore would be modified if it exists, created otherwise
+    if (await exists(join(projectDir, ".gitignore"))) {
+        wouldModify.push(".gitignore");
+    }
+    else {
+        wouldCreate.push(".gitignore");
+    }
+    // CLAUDE.md integration check
     try {
-        await access(join(projectDir, "bmalph/config.json"));
-        return true;
+        const claudeMd = await readFile(join(projectDir, "CLAUDE.md"), "utf-8");
+        if (claudeMd.includes("## BMAD-METHOD Integration")) {
+            wouldSkip.push("CLAUDE.md (already integrated)");
+        }
+        else {
+            wouldModify.push("CLAUDE.md");
+        }
     }
-    catch {
-        return false;
+    catch (err) {
+        if (isEnoent(err)) {
+            wouldCreate.push("CLAUDE.md");
+        }
+        else {
+            throw err;
+        }
+    }
+    return { wouldCreate, wouldModify, wouldSkip };
+}
+export async function previewUpgrade(projectDir) {
+    const managedPaths = [
+        { path: "_bmad/", isDir: true },
+        { path: ".ralph/ralph_loop.sh", isDir: false },
+        { path: ".ralph/ralph_import.sh", isDir: false },
+        { path: ".ralph/ralph_monitor.sh", isDir: false },
+        { path: ".ralph/lib/", isDir: true },
+        { path: ".ralph/PROMPT.md", isDir: false, templateName: "PROMPT.md" },
+        { path: ".ralph/@AGENT.md", isDir: false, templateName: "AGENT.md" },
+        { path: ".ralph/RALPH-REFERENCE.md", isDir: false },
+        { path: ".claude/commands/", isDir: true },
+        { path: ".gitignore", isDir: false },
+    ];
+    const wouldUpdate = [];
+    const wouldCreate = [];
+    const wouldPreserve = [];
+    for (const { path: p, templateName } of managedPaths) {
+        const fullPath = join(projectDir, p.replace(/\/$/, ""));
+        if (await exists(fullPath)) {
+            if (templateName && (await isTemplateCustomized(fullPath, templateName))) {
+                wouldPreserve.push(p);
+            }
+            else {
+                wouldUpdate.push(p);
+            }
+        }
+        else {
+            wouldCreate.push(p);
+        }
     }
+    return { wouldUpdate, wouldCreate, wouldPreserve };
 }

package/dist/transition/artifacts.d.ts

@@ -0,0 +1,2 @@
+export declare function findArtifactsDir(projectDir: string): Promise<string | null>;
+export declare function validateArtifacts(files: string[], artifactsDir: string): Promise<string[]>;

package/dist/transition/artifacts.js

@@ -0,0 +1,46 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { debug } from "../utils/logger.js";
+import { exists } from "../utils/file-system.js";
+export async function findArtifactsDir(projectDir) {
+    const candidates = [
+        "_bmad-output/planning-artifacts",
+        "_bmad-output/planning_artifacts",
+        "docs/planning",
+    ];
+    for (const candidate of candidates) {
+        const fullPath = join(projectDir, candidate);
+        debug(`Checking artifacts dir: ${fullPath}`);
+        if (await exists(fullPath)) {
+            debug(`Found artifacts at: ${fullPath}`);
+            return fullPath;
+        }
+    }
+    debug(`No artifacts found. Checked: ${candidates.join(", ")}`);
+    return null;
+}
+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 {
+            // Cannot read readiness file, skip
+        }
+    }
+    return warnings;
+}

package/dist/transition/context.d.ts

@@ -0,0 +1,19 @@
+import type { ProjectContext, TruncationInfo } from "./types.js";
+export interface ExtractProjectContextResult {
+    context: ProjectContext;
+    truncated: TruncationInfo[];
+}
+export interface ExtractSectionResult {
+    content: string;
+    wasTruncated: boolean;
+    originalLength: number;
+}
+export declare function extractSection(content: string, headingPattern: RegExp, maxLength?: number): string;
+export declare function extractSectionWithInfo(content: string, headingPattern: RegExp, maxLength?: number): ExtractSectionResult;
+export declare function extractProjectContext(artifacts: Map<string, string>): ExtractProjectContextResult;
+/**
+ * Converts truncation info into human-readable warnings.
+ */
+export declare function detectTruncation(truncated: TruncationInfo[]): string[];
+export declare function generateProjectContextMd(context: ProjectContext, projectName: string): string;
+export declare function generatePrompt(projectName: string, context?: ProjectContext): string;