bmalph 2.2.1 → 2.4.0

package/dist/platform/copilot.js

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const copilotPlatform = {
+    id: "copilot",
+    displayName: "GitHub Copilot",
+    tier: "instructions-only",
+    instructionsFile: ".github/copilot-instructions.md",
+    commandDelivery: { kind: "none" },
+    instructionsSectionMarker: "## BMAD-METHOD Integration",
+    generateInstructionsSnippet: () => `
+## BMAD-METHOD Integration
+
+Ask the BMAD master agent to navigate phases. Ask for help to discover all available agents and workflows.
+
+### Phases
+
+| Phase | Focus | Key Agents |
+|-------|-------|-----------|
+| 1. Analysis | Understand the problem | Analyst agent |
+| 2. Planning | Define the solution | Product Manager agent |
+| 3. Solutioning | Design the architecture | Architect agent |
+
+### Workflow
+
+Work through Phases 1-3 using BMAD agents and workflows interactively.
+
+> **Note:** Ralph (Phase 4 — autonomous implementation) is not supported on this platform.
+
+### Available Agents
+
+| Agent | Role |
+|-------|------|
+| Analyst | Research, briefs, discovery |
+| Architect | Technical design, architecture |
+| Product Manager | PRDs, epics, stories |
+| Scrum Master | Sprint planning, status, coordination |
+| Developer | Implementation, coding |
+| UX Designer | User experience, wireframes |
+| QA Engineer | Test automation, quality assurance |
+`,
+    getDoctorChecks: () => [
+        {
+            id: "instructions-file",
+            label: ".github/copilot-instructions.md contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, ".github/copilot-instructions.md"), "utf-8");
+                    if (content.includes("BMAD-METHOD Integration")) {
+                        return { passed: true };
+                    }
+                    return {
+                        passed: false,
+                        detail: "missing BMAD-METHOD Integration section",
+                        hint: "Run: bmalph init",
+                    };
+                }
+                catch (err) {
+                    if (isEnoent(err)) {
+                        return {
+                            passed: false,
+                            detail: ".github/copilot-instructions.md not found",
+                            hint: "Run: bmalph init",
+                        };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/platform/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { Platform } from "./types.js";
+export declare const cursorPlatform: Platform;

package/dist/platform/cursor.js

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const cursorPlatform = {
+    id: "cursor",
+    displayName: "Cursor",
+    tier: "instructions-only",
+    instructionsFile: ".cursor/rules/bmad.mdc",
+    commandDelivery: { kind: "none" },
+    instructionsSectionMarker: "## BMAD-METHOD Integration",
+    generateInstructionsSnippet: () => `
+## BMAD-METHOD Integration
+
+Ask the BMAD master agent to navigate phases. Ask for help to discover all available agents and workflows.
+
+### Phases
+
+| Phase | Focus | Key Agents |
+|-------|-------|-----------|
+| 1. Analysis | Understand the problem | Analyst agent |
+| 2. Planning | Define the solution | Product Manager agent |
+| 3. Solutioning | Design the architecture | Architect agent |
+
+### Workflow
+
+Work through Phases 1-3 using BMAD agents and workflows interactively.
+
+> **Note:** Ralph (Phase 4 — autonomous implementation) is not supported on this platform.
+
+### Available Agents
+
+| Agent | Role |
+|-------|------|
+| Analyst | Research, briefs, discovery |
+| Architect | Technical design, architecture |
+| Product Manager | PRDs, epics, stories |
+| Scrum Master | Sprint planning, status, coordination |
+| Developer | Implementation, coding |
+| UX Designer | User experience, wireframes |
+| QA Engineer | Test automation, quality assurance |
+`,
+    getDoctorChecks: () => [
+        {
+            id: "instructions-file",
+            label: ".cursor/rules/bmad.mdc contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, ".cursor/rules/bmad.mdc"), "utf-8");
+                    if (content.includes("BMAD-METHOD Integration")) {
+                        return { passed: true };
+                    }
+                    return {
+                        passed: false,
+                        detail: "missing BMAD-METHOD Integration section",
+                        hint: "Run: bmalph init",
+                    };
+                }
+                catch (err) {
+                    if (isEnoent(err)) {
+                        return {
+                            passed: false,
+                            detail: ".cursor/rules/bmad.mdc not found",
+                            hint: "Run: bmalph init",
+                        };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/platform/detect.d.ts

@@ -0,0 +1,7 @@
+import type { PlatformId } from "./types.js";
+interface DetectionResult {
+    detected: PlatformId | null;
+    candidates: PlatformId[];
+}
+export declare function detectPlatform(projectDir: string): Promise<DetectionResult>;
+export {};

package/dist/platform/detect.js

@@ -0,0 +1,23 @@
+import { exists } from "../utils/file-system.js";
+import { join } from "path";
+const DETECTION_MARKERS = [
+    { platform: "claude-code", markers: [".claude"] },
+    { platform: "codex", markers: ["AGENTS.md"] },
+    { platform: "cursor", markers: [".cursor"] },
+    { platform: "windsurf", markers: [".windsurf"] },
+    { platform: "copilot", markers: [".github/copilot-instructions.md"] },
+    { platform: "aider", markers: [".aider.conf.yml"] },
+];
+export async function detectPlatform(projectDir) {
+    const candidates = [];
+    for (const { platform, markers } of DETECTION_MARKERS) {
+        for (const marker of markers) {
+            if (await exists(join(projectDir, marker))) {
+                candidates.push(platform);
+                break;
+            }
+        }
+    }
+    const detected = candidates.length === 1 ? (candidates[0] ?? null) : null;
+    return { detected, candidates };
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,4 @@
+export type { Platform, PlatformId, PlatformTier, CommandDelivery, PlatformDoctorCheck, } from "./types.js";
+export { getPlatform, getAllPlatforms, isPlatformId } from "./registry.js";
+export { resolveProjectPlatform } from "./resolve.js";
+export { detectPlatform } from "./detect.js";

package/dist/platform/index.js

@@ -0,0 +1,3 @@
+export { getPlatform, getAllPlatforms, isPlatformId } from "./registry.js";
+export { resolveProjectPlatform } from "./resolve.js";
+export { detectPlatform } from "./detect.js";

package/dist/platform/registry.d.ts

@@ -0,0 +1,4 @@
+import type { Platform, PlatformId } from "./types.js";
+export declare function getPlatform(id: PlatformId): Platform;
+export declare function getAllPlatforms(): Platform[];
+export declare function isPlatformId(value: string): value is PlatformId;

package/dist/platform/registry.js

@@ -0,0 +1,27 @@
+import { claudeCodePlatform } from "./claude-code.js";
+import { codexPlatform } from "./codex.js";
+import { cursorPlatform } from "./cursor.js";
+import { windsurfPlatform } from "./windsurf.js";
+import { copilotPlatform } from "./copilot.js";
+import { aiderPlatform } from "./aider.js";
+const PLATFORMS = new Map([
+    ["claude-code", claudeCodePlatform],
+    ["codex", codexPlatform],
+    ["cursor", cursorPlatform],
+    ["windsurf", windsurfPlatform],
+    ["copilot", copilotPlatform],
+    ["aider", aiderPlatform],
+]);
+export function getPlatform(id) {
+    const platform = PLATFORMS.get(id);
+    if (!platform) {
+        throw new Error(`Unknown platform: ${id}`);
+    }
+    return platform;
+}
+export function getAllPlatforms() {
+    return [...PLATFORMS.values()];
+}
+export function isPlatformId(value) {
+    return PLATFORMS.has(value);
+}

package/dist/platform/resolve.d.ts

@@ -0,0 +1,8 @@
+import type { Platform } from "./types.js";
+/**
+ * Resolve the platform for a project from its config, defaulting to claude-code.
+ *
+ * Used by doctor and upgrade commands to determine which platform checks and
+ * assets to use. Falls back to claude-code when config is missing or unreadable.
+ */
+export declare function resolveProjectPlatform(projectDir: string): Promise<Platform>;

package/dist/platform/resolve.js

@@ -0,0 +1,24 @@
+import { readConfig } from "../utils/config.js";
+import { isEnoent, formatError } from "../utils/errors.js";
+import { warn } from "../utils/logger.js";
+import { getPlatform } from "./registry.js";
+/**
+ * Resolve the platform for a project from its config, defaulting to claude-code.
+ *
+ * Used by doctor and upgrade commands to determine which platform checks and
+ * assets to use. Falls back to claude-code when config is missing or unreadable.
+ */
+export async function resolveProjectPlatform(projectDir) {
+    try {
+        const config = await readConfig(projectDir);
+        if (config?.platform) {
+            return getPlatform(config.platform);
+        }
+    }
+    catch (err) {
+        if (!isEnoent(err)) {
+            warn(`Failed to read project config: ${formatError(err)}`);
+        }
+    }
+    return getPlatform("claude-code");
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Platform abstraction layer for bmalph.
+ *
+ * Controls how `bmalph init/upgrade/doctor` install instruction files,
+ * deliver slash commands, and run health checks per platform.
+ */
+/** Supported platform identifiers. */
+export type PlatformId = "claude-code" | "codex" | "cursor" | "windsurf" | "copilot" | "aider";
+/** Full platforms support Phases 1-4 (planning + Ralph implementation). */
+/** Instructions-only platforms support Phases 1-3 (planning only). */
+export type PlatformTier = "full" | "instructions-only";
+/** How slash commands are delivered to the platform. */
+export type CommandDelivery = {
+    kind: "directory";
+    dir: string;
+} | {
+    kind: "inline";
+} | {
+    kind: "none";
+};
+/** Result of a single platform-specific doctor check. */
+export interface PlatformDoctorCheck {
+    id: string;
+    label: string;
+    check: (projectDir: string) => Promise<{
+        passed: boolean;
+        detail?: string;
+        hint?: string;
+    }>;
+}
+/** Platform definition controlling install, upgrade, and doctor behavior. */
+export interface Platform {
+    readonly id: PlatformId;
+    readonly displayName: string;
+    readonly tier: PlatformTier;
+    readonly instructionsFile: string;
+    readonly commandDelivery: CommandDelivery;
+    readonly instructionsSectionMarker: string;
+    readonly generateInstructionsSnippet: () => string;
+    readonly getDoctorChecks: () => PlatformDoctorCheck[];
+}

package/dist/platform/types.js

@@ -0,0 +1,7 @@
+/**
+ * Platform abstraction layer for bmalph.
+ *
+ * Controls how `bmalph init/upgrade/doctor` install instruction files,
+ * deliver slash commands, and run health checks per platform.
+ */
+export {};

package/dist/platform/windsurf.d.ts

@@ -0,0 +1,2 @@
+import type { Platform } from "./types.js";
+export declare const windsurfPlatform: Platform;

package/dist/platform/windsurf.js

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { isEnoent, formatError } from "../utils/errors.js";
+export const windsurfPlatform = {
+    id: "windsurf",
+    displayName: "Windsurf",
+    tier: "instructions-only",
+    instructionsFile: ".windsurf/rules/bmad.md",
+    commandDelivery: { kind: "none" },
+    instructionsSectionMarker: "## BMAD-METHOD Integration",
+    generateInstructionsSnippet: () => `
+## BMAD-METHOD Integration
+
+Ask the BMAD master agent to navigate phases. Ask for help to discover all available agents and workflows.
+
+### Phases
+
+| Phase | Focus | Key Agents |
+|-------|-------|-----------|
+| 1. Analysis | Understand the problem | Analyst agent |
+| 2. Planning | Define the solution | Product Manager agent |
+| 3. Solutioning | Design the architecture | Architect agent |
+
+### Workflow
+
+Work through Phases 1-3 using BMAD agents and workflows interactively.
+
+> **Note:** Ralph (Phase 4 — autonomous implementation) is not supported on this platform.
+
+### Available Agents
+
+| Agent | Role |
+|-------|------|
+| Analyst | Research, briefs, discovery |
+| Architect | Technical design, architecture |
+| Product Manager | PRDs, epics, stories |
+| Scrum Master | Sprint planning, status, coordination |
+| Developer | Implementation, coding |
+| UX Designer | User experience, wireframes |
+| QA Engineer | Test automation, quality assurance |
+`,
+    getDoctorChecks: () => [
+        {
+            id: "instructions-file",
+            label: ".windsurf/rules/bmad.md contains BMAD snippet",
+            check: async (projectDir) => {
+                try {
+                    const content = await readFile(join(projectDir, ".windsurf/rules/bmad.md"), "utf-8");
+                    if (content.includes("BMAD-METHOD Integration")) {
+                        return { passed: true };
+                    }
+                    return {
+                        passed: false,
+                        detail: "missing BMAD-METHOD Integration section",
+                        hint: "Run: bmalph init",
+                    };
+                }
+                catch (err) {
+                    if (isEnoent(err)) {
+                        return {
+                            passed: false,
+                            detail: ".windsurf/rules/bmad.md not found",
+                            hint: "Run: bmalph init",
+                        };
+                    }
+                    return { passed: false, detail: formatError(err), hint: "Check file permissions" };
+                }
+            },
+        },
+    ],
+};

package/dist/reset.d.ts

@@ -0,0 +1,18 @@
+import type { Platform } from "./platform/types.js";
+import type { DryRunAction } from "./utils/dryrun.js";
+export interface ResetPlan {
+    directories: string[];
+    commandFiles: string[];
+    instructionsCleanup: {
+        path: string;
+        sectionsToRemove: string[];
+    } | null;
+    gitignoreLines: string[];
+    warnings: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+export declare function buildResetPlan(projectDir: string, platform: Platform): Promise<ResetPlan>;
+export declare function executeResetPlan(projectDir: string, plan: ResetPlan): Promise<void>;
+export declare function planToDryRunActions(plan: ResetPlan): DryRunAction[];

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>;