bmalph 2.3.0 → 2.4.0

package/dist/reset.js

@@ -0,0 +1,181 @@
+import { readdir, readFile, rm } from "fs/promises";
+import { join, posix } from "path";
+import { getSlashCommandsDir } from "./installer.js";
+import { exists, atomicWriteFile } from "./utils/file-system.js";
+import { isEnoent } from "./utils/errors.js";
+import { BMAD_DIR, RALPH_DIR, BMALPH_DIR, BMAD_OUTPUT_DIR } from "./utils/constants.js";
+export async function buildResetPlan(projectDir, platform) {
+    const plan = {
+        directories: [],
+        commandFiles: [],
+        instructionsCleanup: null,
+        gitignoreLines: [],
+        warnings: [],
+    };
+    // Check which managed directories exist
+    for (const dir of [BMAD_DIR, RALPH_DIR, BMALPH_DIR]) {
+        if (await exists(join(projectDir, dir))) {
+            plan.directories.push(dir);
+        }
+    }
+    // Check for slash commands to remove (directory delivery only)
+    if (platform.commandDelivery.kind === "directory") {
+        const commandsDir = join(projectDir, platform.commandDelivery.dir);
+        if (await exists(commandsDir)) {
+            const bundledNames = await getBundledCommandNames();
+            try {
+                const existingFiles = await readdir(commandsDir);
+                for (const file of existingFiles) {
+                    if (file.endsWith(".md") && bundledNames.has(file)) {
+                        plan.commandFiles.push(posix.join(platform.commandDelivery.dir, file));
+                    }
+                }
+            }
+            catch (err) {
+                if (!isEnoent(err))
+                    throw err;
+            }
+        }
+    }
+    // Check instructions file for BMAD sections
+    try {
+        const content = await readFile(join(projectDir, platform.instructionsFile), "utf-8");
+        const sectionsToRemove = [];
+        if (content.includes(platform.instructionsSectionMarker)) {
+            sectionsToRemove.push(platform.instructionsSectionMarker);
+        }
+        // Codex (inline) also has a BMAD Commands section
+        if (platform.commandDelivery.kind === "inline" && content.includes("## BMAD Commands")) {
+            sectionsToRemove.push("## BMAD Commands");
+        }
+        if (sectionsToRemove.length > 0) {
+            plan.instructionsCleanup = {
+                path: platform.instructionsFile,
+                sectionsToRemove,
+            };
+        }
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+    }
+    // Check .gitignore for bmalph entries
+    try {
+        const content = await readFile(join(projectDir, ".gitignore"), "utf-8");
+        const existingLines = new Set(content
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean));
+        const bmalpEntries = [".ralph/logs/", "_bmad-output/"];
+        for (const entry of bmalpEntries) {
+            if (existingLines.has(entry)) {
+                plan.gitignoreLines.push(entry);
+            }
+        }
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+    }
+    // Warn about _bmad-output/
+    if (await exists(join(projectDir, BMAD_OUTPUT_DIR))) {
+        plan.warnings.push({
+            path: `${BMAD_OUTPUT_DIR}/`,
+            message: "Contains user planning artifacts — not removed by reset",
+        });
+    }
+    return plan;
+}
+async function getBundledCommandNames() {
+    const slashCommandsDir = getSlashCommandsDir();
+    try {
+        const files = await readdir(slashCommandsDir);
+        return new Set(files.filter((f) => f.endsWith(".md")));
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+        return new Set();
+    }
+}
+export async function executeResetPlan(projectDir, plan) {
+    // Delete managed directories
+    for (const dir of plan.directories) {
+        await rm(join(projectDir, dir), { recursive: true, force: true });
+    }
+    // Delete slash command files
+    for (const file of plan.commandFiles) {
+        await rm(join(projectDir, file), { force: true });
+    }
+    // Clean instructions file
+    if (plan.instructionsCleanup) {
+        const filePath = join(projectDir, plan.instructionsCleanup.path);
+        try {
+            let content = await readFile(filePath, "utf-8");
+            for (const marker of plan.instructionsCleanup.sectionsToRemove) {
+                content = removeSection(content, marker);
+            }
+            content = content.trim();
+            if (content.length === 0) {
+                await rm(filePath, { force: true });
+            }
+            else {
+                await atomicWriteFile(filePath, content + "\n");
+            }
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+        }
+    }
+    // Clean .gitignore
+    if (plan.gitignoreLines.length > 0) {
+        const filePath = join(projectDir, ".gitignore");
+        try {
+            const content = await readFile(filePath, "utf-8");
+            const cleaned = removeGitignoreLines(content, plan.gitignoreLines);
+            await atomicWriteFile(filePath, cleaned);
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+        }
+    }
+}
+function removeSection(content, marker) {
+    if (!content.includes(marker))
+        return content;
+    const sectionStart = content.indexOf(marker);
+    const before = content.slice(0, sectionStart);
+    const afterSection = content.slice(sectionStart);
+    // Find next level-2 heading that doesn't match this section's heading
+    const markerEscaped = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const nextHeadingMatch = afterSection.match(new RegExp(`\\n## (?!${markerEscaped.slice(3)})`));
+    const after = nextHeadingMatch ? afterSection.slice(nextHeadingMatch.index) : "";
+    return before.trimEnd() + after;
+}
+function removeGitignoreLines(content, linesToRemove) {
+    const removeSet = new Set(linesToRemove);
+    const lines = content.split(/\r?\n/);
+    const filtered = lines.filter((line) => !removeSet.has(line.trim()));
+    return filtered.join("\n");
+}
+export function planToDryRunActions(plan) {
+    const actions = [];
+    for (const dir of plan.directories) {
+        actions.push({ type: "delete", path: `${dir}/` });
+    }
+    for (const file of plan.commandFiles) {
+        actions.push({ type: "delete", path: file });
+    }
+    if (plan.instructionsCleanup) {
+        actions.push({ type: "modify", path: plan.instructionsCleanup.path });
+    }
+    if (plan.gitignoreLines.length > 0) {
+        actions.push({ type: "modify", path: ".gitignore" });
+    }
+    for (const warning of plan.warnings) {
+        actions.push({ type: "warn", path: warning.path, reason: warning.message });
+    }
+    return actions;
+}

package/dist/transition/artifact-scan.d.ts

@@ -0,0 +1,27 @@
+export interface ArtifactClassification {
+    phase: number;
+    name: string;
+    required: boolean;
+}
+export interface ScannedArtifact extends ArtifactClassification {
+    filename: string;
+}
+export interface PhaseArtifacts {
+    1: ScannedArtifact[];
+    2: ScannedArtifact[];
+    3: ScannedArtifact[];
+}
+export interface ProjectArtifactScan {
+    directory: string;
+    found: string[];
+    detectedPhase: number;
+    missing: string[];
+    phases: PhaseArtifacts;
+    nextAction: string;
+}
+export declare function classifyArtifact(filename: string): ArtifactClassification | null;
+export declare function scanArtifacts(files: string[]): PhaseArtifacts;
+export declare function detectPhase(phases: PhaseArtifacts): number;
+export declare function getMissing(phases: PhaseArtifacts): string[];
+export declare function suggestNext(phases: PhaseArtifacts, detectedPhase: number): string;
+export declare function scanProjectArtifacts(projectDir: string): Promise<ProjectArtifactScan | null>;

package/dist/transition/artifact-scan.js

@@ -0,0 +1,91 @@
+import { readdir } from "fs/promises";
+import { relative } from "path";
+import { findArtifactsDir } from "./artifacts.js";
+const ARTIFACT_RULES = [
+    { pattern: /brief/i, phase: 1, name: "Product Brief", required: false },
+    { pattern: /market/i, phase: 1, name: "Market Research", required: false },
+    { pattern: /domain/i, phase: 1, name: "Domain Research", required: false },
+    { pattern: /tech.*research/i, phase: 1, name: "Technical Research", required: false },
+    { pattern: /prd/i, phase: 2, name: "PRD", required: true },
+    { pattern: /ux/i, phase: 2, name: "UX Design", required: false },
+    { pattern: /architect/i, phase: 3, name: "Architecture", required: true },
+    { pattern: /epic|stor/i, phase: 3, name: "Epics & Stories", required: true },
+    { pattern: /readiness/i, phase: 3, name: "Readiness Report", required: true },
+];
+export function classifyArtifact(filename) {
+    for (const rule of ARTIFACT_RULES) {
+        if (rule.pattern.test(filename)) {
+            return { phase: rule.phase, name: rule.name, required: rule.required };
+        }
+    }
+    return null;
+}
+export function scanArtifacts(files) {
+    const phases = { 1: [], 2: [], 3: [] };
+    for (const file of files) {
+        const classification = classifyArtifact(file);
+        if (classification) {
+            const phaseKey = classification.phase;
+            phases[phaseKey].push({ ...classification, filename: file });
+        }
+    }
+    return phases;
+}
+export function detectPhase(phases) {
+    for (const phase of [3, 2, 1]) {
+        if (phases[phase].length > 0) {
+            return phase;
+        }
+    }
+    return 1;
+}
+export function getMissing(phases) {
+    const missing = [];
+    const foundNames = new Set([...phases[1], ...phases[2], ...phases[3]].map((a) => a.name));
+    for (const rule of ARTIFACT_RULES) {
+        if (rule.required && !foundNames.has(rule.name)) {
+            missing.push(rule.name);
+        }
+    }
+    return missing;
+}
+export function suggestNext(phases, detectedPhase) {
+    const foundNames = new Set([...phases[1], ...phases[2], ...phases[3]].map((a) => a.name));
+    if (detectedPhase <= 1 && phases[1].length === 0) {
+        return "Run /analyst to start analysis";
+    }
+    if (!foundNames.has("PRD")) {
+        return "Run /create-prd to create the PRD";
+    }
+    if (!foundNames.has("Architecture")) {
+        return "Run /architect to create architecture";
+    }
+    if (!foundNames.has("Epics & Stories")) {
+        return "Run /create-epics-stories to define epics and stories";
+    }
+    if (!foundNames.has("Readiness Report")) {
+        return "Run /architect to generate readiness report";
+    }
+    return "Run: bmalph implement";
+}
+export async function scanProjectArtifacts(projectDir) {
+    const artifactsDir = await findArtifactsDir(projectDir);
+    if (!artifactsDir) {
+        return null;
+    }
+    const files = await readdir(artifactsDir);
+    const phases = scanArtifacts(files);
+    const detectedPhase = detectPhase(phases);
+    const missing = getMissing(phases);
+    const nextAction = suggestNext(phases, detectedPhase);
+    const relativeDir = relative(projectDir, artifactsDir).replace(/\\/g, "/");
+    const found = files.filter((f) => classifyArtifact(f) !== null);
+    return {
+        directory: relativeDir,
+        found,
+        detectedPhase,
+        missing,
+        phases,
+        nextAction,
+    };
+}

package/dist/transition/artifacts.d.ts

@@ -1,2 +1,3 @@
 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

@@ -19,6 +19,7 @@ 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));

package/dist/transition/context.js

@@ -37,6 +37,8 @@ export function extractProjectContext(artifacts) {
     // Combine all content, keyed by likely role
     let prdContent = "";
     let archContent = "";
+    let uxContent = "";
+    let researchContent = "";
     for (const [filename, content] of artifacts) {
         if (/prd/i.test(filename))
             prdContent += "\n" + content;
@@ -44,6 +46,10 @@ export function extractProjectContext(artifacts) {
             archContent += "\n" + content;
         if (/readiness/i.test(filename))
             archContent += "\n" + content;
+        if (/ux/i.test(filename))
+            uxContent += "\n" + content;
+        if (/research|market|domain|brief/i.test(filename))
+            researchContent += "\n" + content;
     }
     const allContent = prdContent + "\n" + archContent;
     const truncated = [];
@@ -98,6 +104,28 @@ export function extractProjectContext(artifacts) {
                 /^##\s+Quality Attributes/m,
             ],
         },
+        {
+            field: "designGuidelines",
+            source: uxContent,
+            patterns: [
+                /^##\s+Design Principles/m,
+                /^##\s+Design System/m,
+                /^##\s+Core Experience/m,
+                /^##\s+User Flows/m,
+                /^##\s+Visual Foundation/m,
+            ],
+        },
+        {
+            field: "researchInsights",
+            source: researchContent,
+            patterns: [
+                /^##\s+Key Findings/m,
+                /^##\s+Recommendations/m,
+                /^##\s+Market Analysis/m,
+                /^##\s+Domain Insights/m,
+                /^##\s+Summary/m,
+            ],
+        },
     ];
     const context = {
         projectGoals: "",
@@ -107,6 +135,8 @@ export function extractProjectContext(artifacts) {
         scopeBoundaries: "",
         targetUsers: "",
         nonFunctionalRequirements: "",
+        designGuidelines: "",
+        researchInsights: "",
     };
     for (const { field, source, patterns } of fields) {
         const result = extractFromPatternsWithInfo(source, patterns);
@@ -140,6 +170,8 @@ export function generateProjectContextMd(context, projectName) {
         { heading: "Scope Boundaries", content: context.scopeBoundaries },
         { heading: "Target Users", content: context.targetUsers },
         { heading: "Non-Functional Requirements", content: context.nonFunctionalRequirements },
+        { heading: "Design Guidelines", content: context.designGuidelines },
+        { heading: "Research Insights", content: context.researchInsights },
     ];
     for (const { heading, content } of sections) {
         if (content) {
@@ -161,6 +193,8 @@ export function generatePrompt(projectName, context) {
             context.targetUsers && `### Target Users\n${context.targetUsers}`,
             context.nonFunctionalRequirements &&
                 `### Non-Functional Requirements\n${context.nonFunctionalRequirements}`,
+            context.designGuidelines && `### Design Guidelines\n${context.designGuidelines}`,
+            context.researchInsights && `### Research Insights\n${context.researchInsights}`,
         ]
             .filter(Boolean)
             .join("\n\n")

package/dist/transition/fix-plan.d.ts

@@ -10,6 +10,12 @@ export declare function detectOrphanedCompletedStories(existingItems: FixPlanIte
 /**
  * Detects stories that may have been renumbered by comparing titles.
  * Returns warnings when a completed story's title appears under a different ID.
+ * Skips stories that were already auto-preserved via title-based merge.
  */
-export declare function detectRenumberedStories(existingItems: FixPlanItemWithTitle[], newStories: Story[]): string[];
-export declare function mergeFixPlanProgress(newFixPlan: string, completedIds: Set<string>): string;
+export declare function detectRenumberedStories(existingItems: FixPlanItemWithTitle[], newStories: Story[], preservedIds?: Set<string>): string[];
+export declare function normalizeTitle(title: string): string;
+/**
+ * Builds a map from normalized (lowercased) title to story ID for completed items.
+ */
+export declare function buildCompletedTitleMap(items: FixPlanItemWithTitle[]): Map<string, string>;
+export declare function mergeFixPlanProgress(newFixPlan: string, completedIds: Set<string>, titleMap?: Map<string, string>, completedTitles?: Map<string, string>): string;

package/dist/transition/fix-plan.js

@@ -65,30 +65,56 @@ export function detectOrphanedCompletedStories(existingItems, newStoryIds) {
 /**
  * Detects stories that may have been renumbered by comparing titles.
  * Returns warnings when a completed story's title appears under a different ID.
+ * Skips stories that were already auto-preserved via title-based merge.
  */
-export function detectRenumberedStories(existingItems, newStories) {
+export function detectRenumberedStories(existingItems, newStories, preservedIds) {
     const warnings = [];
     // Build a map of new story titles (lowercased) to IDs
     const newTitleToId = new Map();
     for (const story of newStories) {
-        newTitleToId.set(story.title.toLowerCase().trim(), story.id);
+        newTitleToId.set(normalizeTitle(story.title), story.id);
     }
     // Check each completed story
     for (const item of existingItems) {
         if (!item.completed || !item.title)
             continue;
-        const normalizedTitle = item.title.toLowerCase().trim();
+        const normalizedTitle = normalizeTitle(item.title);
         const newId = newTitleToId.get(normalizedTitle);
         // If title exists under a different ID, warn about renumbering
-        if (newId && newId !== item.id) {
+        // (unless it was already auto-preserved)
+        if (newId && newId !== item.id && !preservedIds?.has(newId)) {
             warnings.push(`Story "${item.title}" appears to have been renumbered from ${item.id} to ${newId}. Completion status was not preserved.`);
         }
     }
     return warnings;
 }
-export function mergeFixPlanProgress(newFixPlan, completedIds) {
-    // Replace [ ] with [x] for completed story IDs
+export function normalizeTitle(title) {
+    return title.toLowerCase().trim();
+}
+/**
+ * Builds a map from normalized (lowercased) title to story ID for completed items.
+ */
+export function buildCompletedTitleMap(items) {
+    const map = new Map();
+    for (const item of items) {
+        if (item.completed && item.title) {
+            map.set(normalizeTitle(item.title), item.id);
+        }
+    }
+    return map;
+}
+export function mergeFixPlanProgress(newFixPlan, completedIds, titleMap, completedTitles) {
+    // Replace [ ] with [x] for completed story IDs or title matches
     return newFixPlan.replace(/^(\s*-\s*)\[ \](\s*Story\s+(\d+\.\d+):)/gm, (match, prefix, suffix, id) => {
-        return completedIds.has(id) ? `${prefix}[x]${suffix}` : match;
+        if (completedIds.has(id))
+            return `${prefix}[x]${suffix}`;
+        // Title-based fallback: check if title matches a completed story
+        if (titleMap && completedTitles) {
+            const title = titleMap.get(id);
+            if (title && completedTitles.has(normalizeTitle(title))) {
+                return `${prefix}[x]${suffix}`;
+            }
+        }
+        return match;
     });
 }

package/dist/transition/orchestration.d.ts

@@ -1,2 +1,2 @@
-import type { TransitionResult } from "./types.js";
-export declare function runTransition(projectDir: string): Promise<TransitionResult>;
+import type { TransitionResult, TransitionOptions } from "./types.js";
+export declare function runTransition(projectDir: string, options?: TransitionOptions): Promise<TransitionResult>;