bmalph 1.0.0 → 2.2.1

package/dist/utils/github.js

@@ -0,0 +1,230 @@
+import { formatError } from "./errors.js";
+const BMAD_REPO = {
+    owner: "bmad-code-org",
+    repo: "BMAD-METHOD",
+    branch: "main",
+};
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_MAX_CACHE_SIZE = 100;
+function classifyError(status, headers) {
+    if (status === 404) {
+        return "not-found";
+    }
+    if (status === 403) {
+        const remaining = headers.get("X-RateLimit-Remaining");
+        if (remaining === "0") {
+            return "rate-limit";
+        }
+    }
+    return "api-error";
+}
+function generateCompareUrl(repo, bundledSha, latestSha) {
+    return `https://github.com/${repo.owner}/${repo.repo}/compare/${bundledSha}...${latestSha}`;
+}
+function compareShas(bundledSha, latestShortSha) {
+    return latestShortSha.slice(0, 8) === bundledSha.slice(0, 8);
+}
+function buildUpstreamStatus(repo, bundledSha, latestShortSha) {
+    return {
+        bundledSha,
+        latestSha: latestShortSha,
+        isUpToDate: compareShas(bundledSha, latestShortSha),
+        compareUrl: generateCompareUrl(repo, bundledSha, latestShortSha),
+    };
+}
+/**
+ * GitHub API client with instance-level caching.
+ * Each instance maintains its own cache, improving testability.
+ */
+export class GitHubClient {
+    cache = new Map();
+    cacheTtlMs;
+    maxCacheSize;
+    constructor(options = {}) {
+        this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        this.maxCacheSize = options.maxCacheSize ?? DEFAULT_MAX_CACHE_SIZE;
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    getCacheStats() {
+        return { size: this.cache.size };
+    }
+    getCacheKey(repo) {
+        return `${repo.owner}/${repo.repo}/${repo.branch}`;
+    }
+    getCachedResult(repo) {
+        const key = this.getCacheKey(repo);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Remove stale entry immediately instead of leaving it in cache
+        if (Date.now() - entry.timestamp >= this.cacheTtlMs) {
+            this.cache.delete(key);
+            return null;
+        }
+        // Update lastAccessed for LRU tracking
+        entry.lastAccessed = Date.now();
+        return entry.data;
+    }
+    setCachedResult(repo, data) {
+        const key = this.getCacheKey(repo);
+        const now = Date.now();
+        // Clean up expired entries before checking size (prevents stale entries from occupying space)
+        for (const [k, v] of this.cache.entries()) {
+            if (now - v.timestamp >= this.cacheTtlMs) {
+                this.cache.delete(k);
+            }
+        }
+        // Evict oldest entry if cache is still at max size after cleanup (LRU eviction)
+        if (this.cache.size >= this.maxCacheSize && !this.cache.has(key)) {
+            let oldestKey = null;
+            let oldestTime = Infinity;
+            for (const [k, v] of this.cache.entries()) {
+                if (v.lastAccessed < oldestTime) {
+                    oldestTime = v.lastAccessed;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        this.cache.set(key, { data, timestamp: now, lastAccessed: now });
+    }
+    async fetchLatestCommit(repo, options = {}) {
+        // Check cache first
+        const cached = this.getCachedResult(repo);
+        if (cached) {
+            return { success: true, data: cached };
+        }
+        const url = `https://api.github.com/repos/${repo.owner}/${repo.repo}/commits/${repo.branch}`;
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                headers: {
+                    Accept: "application/vnd.github.v3+json",
+                    "User-Agent": "bmalph-cli",
+                },
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorType = classifyError(response.status, response.headers);
+                return {
+                    success: false,
+                    error: {
+                        type: errorType,
+                        message: `GitHub API error: ${response.status}`,
+                        status: response.status,
+                    },
+                };
+            }
+            const data = (await response.json());
+            // Validate response structure before accessing nested properties
+            if (!data ||
+                typeof data !== "object" ||
+                !("sha" in data) ||
+                typeof data.sha !== "string" ||
+                !("commit" in data) ||
+                !data.commit ||
+                typeof data.commit?.message !== "string" ||
+                !data.commit?.author ||
+                typeof data.commit?.author?.date !== "string") {
+                return {
+                    success: false,
+                    error: {
+                        type: "api-error",
+                        message: "Invalid response structure from GitHub API",
+                    },
+                };
+            }
+            const validData = data;
+            const commitInfo = {
+                sha: validData.sha,
+                shortSha: validData.sha.slice(0, 8),
+                message: validData.commit.message,
+                date: validData.commit.author.date,
+            };
+            // Cache successful result
+            this.setCachedResult(repo, commitInfo);
+            return { success: true, data: commitInfo };
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (err instanceof DOMException && err.name === "AbortError") {
+                return {
+                    success: false,
+                    error: {
+                        type: "timeout",
+                        message: `Request timed out after ${timeoutMs}ms`,
+                    },
+                };
+            }
+            return {
+                success: false,
+                error: {
+                    type: "network",
+                    message: `Network error: ${formatError(err)}`,
+                },
+            };
+        }
+    }
+    async checkUpstream(bundled) {
+        const errors = [];
+        let bmadStatus = null;
+        const bmadResult = await this.fetchLatestCommit(BMAD_REPO);
+        if (bmadResult.success) {
+            bmadStatus = buildUpstreamStatus(BMAD_REPO, bundled.bmadCommit, bmadResult.data.shortSha);
+        }
+        else {
+            errors.push({ ...bmadResult.error, repo: "bmad" });
+        }
+        return {
+            bmad: bmadStatus,
+            errors,
+        };
+    }
+}
+/**
+ * Determines why upstream checks were skipped based on error types.
+ */
+export function getSkipReason(errors) {
+    if (errors.length === 0)
+        return "unknown";
+    const types = new Set(errors.map((e) => e.type));
+    if (types.has("rate-limit"))
+        return "rate limited";
+    if (types.has("network"))
+        return "offline";
+    if (types.has("timeout"))
+        return "timeout";
+    return "error";
+}
+// Default client instance for backward compatibility
+const defaultClient = new GitHubClient();
+/**
+ * Clear the default client's cache.
+ * For testing, prefer creating a new GitHubClient instance instead.
+ */
+export function clearCache() {
+    defaultClient.clearCache();
+}
+/**
+ * Fetch the latest commit from a GitHub repository.
+ * Uses the default shared client instance.
+ */
+export async function fetchLatestCommit(repo, options = {}) {
+    return defaultClient.fetchLatestCommit(repo, options);
+}
+/**
+ * Check upstream repositories for updates.
+ * Uses the default shared client instance.
+ */
+export async function checkUpstream(bundled) {
+    return defaultClient.checkUpstream(bundled);
+}

package/dist/utils/json.js

@@ -1,4 +1,5 @@
 import { readFile } from "fs/promises";
+import { isEnoent } from "./errors.js";
 /**
  * Reads and parses a JSON file with proper error discrimination:
  * - File not found → returns null
@@ -11,7 +12,7 @@ export async function readJsonFile(path) {
         content = await readFile(path, "utf-8");
     }
     catch (err) {
-        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        if (isEnoent(err)) {
             return null;
         }
         throw err;
@@ -20,7 +21,6 @@ export async function readJsonFile(path) {
         return JSON.parse(content);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`Invalid JSON in ${path}: ${message}`);
+        throw new Error(`Invalid JSON in ${path}`, { cause: err });
     }
 }

package/dist/utils/logger.d.ts

@@ -1,3 +1,9 @@
 export declare function setVerbose(value: boolean): void;
 export declare function isVerbose(): boolean;
+export declare function setQuiet(value: boolean): void;
+export declare function isQuiet(): boolean;
 export declare function debug(message: string): void;
+export declare function info(message: string): void;
+export declare function warn(message: string): void;
+export declare function error(message: string): void;
+export declare function success(message: string): void;

package/dist/utils/logger.js

@@ -1,13 +1,40 @@
 import chalk from "chalk";
 let verbose = false;
+let quiet = false;
 export function setVerbose(value) {
     verbose = value;
 }
 export function isVerbose() {
     return verbose;
 }
+export function setQuiet(value) {
+    quiet = value;
+}
+export function isQuiet() {
+    return quiet;
+}
 export function debug(message) {
+    if (quiet)
+        return;
     if (verbose) {
         console.log(chalk.dim(`[debug] ${message}`));
     }
 }
+export function info(message) {
+    if (quiet)
+        return;
+    console.log(chalk.blue(message));
+}
+export function warn(message) {
+    if (quiet)
+        return;
+    console.log(chalk.yellow(message));
+}
+export function error(message) {
+    console.error(chalk.red(message));
+}
+export function success(message) {
+    if (quiet)
+        return;
+    console.log(chalk.green(message));
+}

package/dist/utils/state.d.ts

@@ -1,3 +1,4 @@
+import type { RalphLoopStatus } from "./validate.js";
 export interface BmalphState {
     currentPhase: number;
     status: "planning" | "implementing" | "completed";
@@ -20,10 +21,6 @@ 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;
-export interface RalphStatus {
-    loopCount: number;
-    status: "running" | "blocked" | "completed" | "not_started";
-    tasksCompleted: number;
-    tasksTotal: number;
-}
-export declare function readRalphStatus(projectDir: string): Promise<RalphStatus>;
+/** @deprecated Use RalphLoopStatus from validate.ts instead */
+export type RalphStatus = RalphLoopStatus;
+export declare function readRalphStatus(projectDir: string): Promise<RalphLoopStatus>;

package/dist/utils/state.js

@@ -1,20 +1,27 @@
-import { writeFile, mkdir, rename } from "fs/promises";
+import { mkdir } from "fs/promises";
 import { join } from "path";
 import { readJsonFile } from "./json.js";
-import { validateState } from "./validate.js";
-const STATE_DIR = "bmalph/state";
+import { validateState, validateRalphLoopStatus, normalizeRalphStatus } from "./validate.js";
+import { STATE_DIR, RALPH_STATUS_FILE } from "./constants.js";
+import { atomicWriteFile } from "./file-system.js";
+import { warn } from "./logger.js";
+import { formatError } from "./errors.js";
 export async function readState(projectDir) {
     const data = await readJsonFile(join(projectDir, STATE_DIR, "current-phase.json"));
     if (data === null)
         return null;
-    return validateState(data);
+    try {
+        return validateState(data);
+    }
+    catch (err) {
+        warn(`State file is corrupted, treating as uninitialized: ${formatError(err)}`);
+        return null;
+    }
 }
 export async function writeState(projectDir, state) {
     await mkdir(join(projectDir, STATE_DIR), { recursive: true });
     const target = join(projectDir, STATE_DIR, "current-phase.json");
-    const tmp = target + ".tmp";
-    await writeFile(tmp, JSON.stringify(state, null, 2) + "\n");
-    await rename(tmp, target);
+    await atomicWriteFile(target, JSON.stringify(state, null, 2) + "\n");
 }
 export function getPhaseLabel(phase) {
     const labels = {
@@ -31,34 +38,130 @@ export function getPhaseInfo(phase) {
             name: "Analysis",
             agent: "Analyst",
             commands: [
-                { code: "BP", name: "Brainstorm Project", agent: "analyst", description: "Expert guided facilitation through brainstorming techniques", required: false },
-                { code: "MR", name: "Market Research", agent: "analyst", description: "Market analysis, competitive landscape, customer needs", required: false },
-                { code: "DR", name: "Domain Research", agent: "analyst", description: "Industry domain deep dive, subject matter expertise", required: false },
-                { code: "TR", name: "Technical Research", agent: "analyst", description: "Technical feasibility, architecture options", required: false },
-                { code: "CB", name: "Create Brief", agent: "analyst", description: "Guided experience to nail down your product idea", required: false },
-                { code: "VB", name: "Validate Brief", agent: "analyst", description: "Validates product brief completeness", required: false },
+                {
+                    code: "BP",
+                    name: "Brainstorm Project",
+                    agent: "analyst",
+                    description: "Expert guided facilitation through brainstorming techniques",
+                    required: false,
+                },
+                {
+                    code: "MR",
+                    name: "Market Research",
+                    agent: "analyst",
+                    description: "Market analysis, competitive landscape, customer needs",
+                    required: false,
+                },
+                {
+                    code: "DR",
+                    name: "Domain Research",
+                    agent: "analyst",
+                    description: "Industry domain deep dive, subject matter expertise",
+                    required: false,
+                },
+                {
+                    code: "TR",
+                    name: "Technical Research",
+                    agent: "analyst",
+                    description: "Technical feasibility, architecture options",
+                    required: false,
+                },
+                {
+                    code: "CB",
+                    name: "Create Brief",
+                    agent: "analyst",
+                    description: "Guided experience to nail down your product idea",
+                    required: false,
+                },
+                {
+                    code: "VB",
+                    name: "Validate Brief",
+                    agent: "analyst",
+                    description: "Validates product brief completeness",
+                    required: false,
+                },
             ],
         },
         2: {
             name: "Planning",
             agent: "PM (John)",
             commands: [
-                { code: "CP", name: "Create PRD", agent: "pm", description: "Expert led facilitation to produce your PRD", required: true },
-                { code: "VP", name: "Validate PRD", agent: "pm", description: "Validate PRD is comprehensive and cohesive", required: false },
-                { code: "CU", name: "Create UX", agent: "ux-designer", description: "Guidance through realizing the plan for your UX", required: false },
-                { code: "VU", name: "Validate UX", agent: "ux-designer", description: "Validates UX design deliverables", required: false },
+                {
+                    code: "CP",
+                    name: "Create PRD",
+                    agent: "pm",
+                    description: "Expert led facilitation to produce your PRD",
+                    required: true,
+                },
+                {
+                    code: "VP",
+                    name: "Validate PRD",
+                    agent: "pm",
+                    description: "Validate PRD is comprehensive and cohesive",
+                    required: false,
+                },
+                {
+                    code: "CU",
+                    name: "Create UX",
+                    agent: "ux-designer",
+                    description: "Guidance through realizing the plan for your UX",
+                    required: false,
+                },
+                {
+                    code: "VU",
+                    name: "Validate UX",
+                    agent: "ux-designer",
+                    description: "Validates UX design deliverables",
+                    required: false,
+                },
             ],
         },
         3: {
             name: "Solutioning",
             agent: "Architect",
             commands: [
-                { code: "CA", name: "Create Architecture", agent: "architect", description: "Guided workflow to document technical decisions", required: true },
-                { code: "VA", name: "Validate Architecture", agent: "architect", description: "Validates architecture completeness", required: false },
-                { code: "CE", name: "Create Epics and Stories", agent: "pm", description: "Create the epics and stories listing", required: true },
-                { code: "VE", name: "Validate Epics and Stories", agent: "pm", description: "Validates epics and stories completeness", required: false },
-                { code: "TD", name: "Test Design", agent: "tea", description: "Create comprehensive test scenarios", required: false },
-                { code: "IR", name: "Implementation Readiness", agent: "architect", description: "Ensure PRD, UX, architecture, and stories are aligned", required: true },
+                {
+                    code: "CA",
+                    name: "Create Architecture",
+                    agent: "architect",
+                    description: "Guided workflow to document technical decisions",
+                    required: true,
+                },
+                {
+                    code: "VA",
+                    name: "Validate Architecture",
+                    agent: "architect",
+                    description: "Validates architecture completeness",
+                    required: false,
+                },
+                {
+                    code: "CE",
+                    name: "Create Epics and Stories",
+                    agent: "pm",
+                    description: "Create the epics and stories listing",
+                    required: true,
+                },
+                {
+                    code: "VE",
+                    name: "Validate Epics and Stories",
+                    agent: "pm",
+                    description: "Validates epics and stories completeness",
+                    required: false,
+                },
+                {
+                    code: "QA",
+                    name: "QA Automation Test",
+                    agent: "qa",
+                    description: "Generate automated API and E2E tests for implemented code",
+                    required: false,
+                },
+                {
+                    code: "IR",
+                    name: "Implementation Readiness",
+                    agent: "architect",
+                    description: "Ensure PRD, UX, architecture, and stories are aligned",
+                    required: true,
+                },
             ],
         },
         4: {
@@ -69,10 +172,28 @@ export function getPhaseInfo(phase) {
     };
     return info[phase] ?? { name: "Unknown", agent: "Unknown", commands: [] };
 }
+const DEFAULT_RALPH_STATUS = {
+    loopCount: 0,
+    status: "not_started",
+    tasksCompleted: 0,
+    tasksTotal: 0,
+};
 export async function readRalphStatus(projectDir) {
-    const data = await readJsonFile(join(projectDir, ".ralph/status.json"));
+    const data = await readJsonFile(join(projectDir, RALPH_STATUS_FILE));
     if (data === null) {
-        return { loopCount: 0, status: "not_started", tasksCompleted: 0, tasksTotal: 0 };
+        return DEFAULT_RALPH_STATUS;
+    }
+    try {
+        return validateRalphLoopStatus(data);
+    }
+    catch {
+        // camelCase validation failed — try bash snake_case format
+    }
+    try {
+        return normalizeRalphStatus(data);
+    }
+    catch (err) {
+        warn(`Ralph status file is corrupted, using defaults: ${formatError(err)}`);
+        return DEFAULT_RALPH_STATUS;
     }
-    return data;
 }

package/dist/utils/validate.d.ts

@@ -2,3 +2,43 @@ import type { BmalphConfig } from "./config.js";
 import type { BmalphState } from "./state.js";
 export declare function validateConfig(data: unknown): BmalphConfig;
 export declare function validateState(data: unknown): BmalphState;
+export interface CircuitBreakerState {
+    state: "CLOSED" | "HALF_OPEN" | "OPEN";
+    consecutive_no_progress: number;
+    reason?: string;
+}
+export declare function validateCircuitBreakerState(data: unknown): CircuitBreakerState;
+export interface RalphSession {
+    session_id: string;
+    created_at: string;
+    last_used?: string;
+}
+export declare function validateRalphSession(data: unknown): RalphSession;
+export interface RalphApiStatus {
+    calls_made_this_hour: number;
+    max_calls_per_hour: number;
+    status?: string;
+}
+export declare function validateRalphApiStatus(data: unknown): RalphApiStatus;
+export interface RalphLoopStatus {
+    loopCount: number;
+    status: "running" | "blocked" | "completed" | "not_started";
+    tasksCompleted: number;
+    tasksTotal: number;
+}
+export declare function validateRalphLoopStatus(data: unknown): RalphLoopStatus;
+export declare function normalizeRalphStatus(data: unknown): RalphLoopStatus;
+/**
+ * Validates a project name for filesystem safety.
+ * Checks for:
+ * - Empty names
+ * - Max length (100 characters)
+ * - Invalid filesystem characters (< > : " / \ | ? *)
+ * - Windows reserved names (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
+ * - Leading/trailing whitespace or dots
+ *
+ * @param name - The project name to validate
+ * @returns The validated name (unchanged if valid)
+ * @throws Error if the name is invalid
+ */
+export declare function validateProjectName(name: string): string;