bmalph 1.0.0 → 2.2.1

package/dist/utils/constants.js

@@ -0,0 +1,97 @@
+/**
+ * Centralized constants for bmalph.
+ *
+ * Path constants define the standard directory names used throughout
+ * the bmalph project for BMAD, Ralph, and Claude Code integration.
+ *
+ * Numeric thresholds are used for validation, file processing, and health checks.
+ */
+import { join } from "path";
+// =============================================================================
+// Validation thresholds
+// =============================================================================
+/** Maximum allowed project name length */
+export const MAX_PROJECT_NAME_LENGTH = 100;
+// =============================================================================
+// File processing thresholds
+// =============================================================================
+/** File size threshold for "large file" warnings (50 KB) */
+export const LARGE_FILE_THRESHOLD_BYTES = 50000;
+/** Default max length for extracted content snippets */
+export const DEFAULT_SNIPPET_MAX_LENGTH = 60;
+/** Max length for section extraction from documents (increased to preserve full BMAD specs) */
+export const SECTION_EXTRACT_MAX_LENGTH = 5000;
+/** Max characters for diff line preview */
+export const DIFF_LINE_PREVIEW_LENGTH = 50;
+// =============================================================================
+// Health check thresholds
+// =============================================================================
+/** Session age warning threshold (24 hours in milliseconds) */
+export const SESSION_AGE_WARNING_MS = 24 * 60 * 60 * 1000;
+/** API call usage warning threshold (percentage) */
+export const API_USAGE_WARNING_PERCENT = 90;
+// =============================================================================
+// Path constants
+// =============================================================================
+/** Ralph working directory (contains loop, specs, logs) */
+export const RALPH_DIR = ".ralph";
+/** BMAD agents and workflows directory */
+export const BMAD_DIR = "_bmad";
+/** bmalph state directory (config, phase tracking) */
+export const BMALPH_DIR = "bmalph";
+/** BMAD output directory (planning artifacts) */
+export const BMAD_OUTPUT_DIR = "_bmad-output";
+/** Ralph logs directory */
+export const RALPH_LOGS_DIR = ".ralph/logs";
+/** Ralph specs directory (copied from _bmad-output) */
+export const RALPH_SPECS_DIR = ".ralph/specs";
+/** Claude Code slash commands directory */
+export const CLAUDE_COMMANDS_DIR = ".claude/commands";
+/** bmalph state subdirectory (inside BMALPH_DIR) */
+export const STATE_DIR = "bmalph/state";
+/** bmalph config file path */
+export const CONFIG_FILE = "bmalph/config.json";
+/** Ralph status file path */
+export const RALPH_STATUS_FILE = ".ralph/status.json";
+/**
+ * Get absolute path to Ralph directory for a project.
+ */
+export function getRalphDir(projectDir) {
+    return join(projectDir, RALPH_DIR);
+}
+/**
+ * Get absolute path to BMAD directory for a project.
+ */
+export function getBmadDir(projectDir) {
+    return join(projectDir, BMAD_DIR);
+}
+/**
+ * Get absolute path to bmalph state directory for a project.
+ */
+export function getBmalphDir(projectDir) {
+    return join(projectDir, BMALPH_DIR);
+}
+/**
+ * Get absolute path to BMAD output directory for a project.
+ */
+export function getBmadOutputDir(projectDir) {
+    return join(projectDir, BMAD_OUTPUT_DIR);
+}
+/**
+ * Get absolute path to Ralph logs directory for a project.
+ */
+export function getRalphLogsDir(projectDir) {
+    return join(projectDir, RALPH_LOGS_DIR);
+}
+/**
+ * Get absolute path to Ralph specs directory for a project.
+ */
+export function getRalphSpecsDir(projectDir) {
+    return join(projectDir, RALPH_SPECS_DIR);
+}
+/**
+ * Get absolute path to Claude commands directory for a project.
+ */
+export function getClaudeCommandsDir(projectDir) {
+    return join(projectDir, CLAUDE_COMMANDS_DIR);
+}

package/dist/utils/dryrun.d.ts

@@ -0,0 +1,7 @@
+export interface DryRunAction {
+    type: "create" | "modify" | "skip";
+    path: string;
+    reason?: string;
+}
+export declare function logDryRunAction(action: DryRunAction): void;
+export declare function formatDryRunSummary(actions: DryRunAction[]): string;

package/dist/utils/dryrun.js

@@ -0,0 +1,48 @@
+import chalk from "chalk";
+export function logDryRunAction(action) {
+    const prefix = chalk.dim("[dry-run]");
+    switch (action.type) {
+        case "create":
+            console.log(`${prefix} Would create: ${chalk.green(action.path)}`);
+            break;
+        case "modify":
+            console.log(`${prefix} Would modify: ${chalk.yellow(action.path)}`);
+            break;
+        case "skip":
+            console.log(`${prefix} Would skip: ${chalk.dim(action.path)}${action.reason ? ` (${action.reason})` : ""}`);
+            break;
+    }
+}
+export function formatDryRunSummary(actions) {
+    if (actions.length === 0) {
+        return chalk.dim("No changes would be made.");
+    }
+    const lines = [];
+    lines.push(chalk.blue("\n[dry-run] Would perform the following actions:\n"));
+    const creates = actions.filter((a) => a.type === "create");
+    const modifies = actions.filter((a) => a.type === "modify");
+    const skips = actions.filter((a) => a.type === "skip");
+    if (creates.length > 0) {
+        lines.push(chalk.green("Would create:"));
+        for (const action of creates) {
+            lines.push(`  ${action.path}`);
+        }
+        lines.push("");
+    }
+    if (modifies.length > 0) {
+        lines.push(chalk.yellow("Would modify:"));
+        for (const action of modifies) {
+            lines.push(`  ${action.path}`);
+        }
+        lines.push("");
+    }
+    if (skips.length > 0) {
+        lines.push(chalk.dim("Would skip:"));
+        for (const action of skips) {
+            lines.push(`  ${action.path}${action.reason ? ` (${action.reason})` : ""}`);
+        }
+        lines.push("");
+    }
+    lines.push(chalk.dim("No changes made."));
+    return lines.join("\n");
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Error formatting utilities for consistent error handling.
+ *
+ * Provides helper functions to safely extract error messages from
+ * unknown error types (catch blocks receive `unknown` in TypeScript).
+ */
+/**
+ * Extract error message from an unknown error value.
+ *
+ * @param error - Any caught error (Error instance, string, or other)
+ * @returns The error message as a string
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   console.error(formatError(err));
+ * }
+ * ```
+ */
+/**
+ * Check if an error is an ENOENT (file not found) filesystem error.
+ *
+ * @param err - Any caught error value
+ * @returns true if the error is an Error with code "ENOENT"
+ */
+export declare function isEnoent(err: unknown): boolean;
+export declare function formatError(error: unknown): string;
+/**
+ * Create a formatted error message with a prefix.
+ *
+ * @param prefix - Context for the error (e.g., "Failed to read file")
+ * @param error - The caught error
+ * @returns Formatted message like "Failed to read file: <error message>"
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await readFile(path);
+ * } catch (err) {
+ *   throw new Error(formatErrorMessage("Failed to read config", err));
+ * }
+ * ```
+ */
+export declare function formatErrorMessage(prefix: string, error: unknown): string;
+/**
+ * Wrap an async command function with standard error handling.
+ *
+ * Catches any errors, prints them in red to stderr, and sets process.exitCode to 1.
+ * Uses process.exitCode instead of process.exit() to allow graceful cleanup.
+ *
+ * @param fn - Async function to execute
+ * @returns Promise that resolves when the function completes (or error is handled)
+ *
+ * @example
+ * ```ts
+ * export async function myCommand(options: MyOptions): Promise<void> {
+ *   await withErrorHandling(() => runMyCommand(options));
+ * }
+ * ```
+ */
+export declare function withErrorHandling(fn: () => Promise<void>): Promise<void>;

package/dist/utils/errors.js

@@ -0,0 +1,86 @@
+/**
+ * Error formatting utilities for consistent error handling.
+ *
+ * Provides helper functions to safely extract error messages from
+ * unknown error types (catch blocks receive `unknown` in TypeScript).
+ */
+/**
+ * Extract error message from an unknown error value.
+ *
+ * @param error - Any caught error (Error instance, string, or other)
+ * @returns The error message as a string
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   console.error(formatError(err));
+ * }
+ * ```
+ */
+/**
+ * Check if an error is an ENOENT (file not found) filesystem error.
+ *
+ * @param err - Any caught error value
+ * @returns true if the error is an Error with code "ENOENT"
+ */
+export function isEnoent(err) {
+    return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+export function formatError(error) {
+    if (error instanceof Error) {
+        if (error.cause) {
+            return `${error.message}: ${formatError(error.cause)}`;
+        }
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * Create a formatted error message with a prefix.
+ *
+ * @param prefix - Context for the error (e.g., "Failed to read file")
+ * @param error - The caught error
+ * @returns Formatted message like "Failed to read file: <error message>"
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await readFile(path);
+ * } catch (err) {
+ *   throw new Error(formatErrorMessage("Failed to read config", err));
+ * }
+ * ```
+ */
+export function formatErrorMessage(prefix, error) {
+    return `${prefix}: ${formatError(error)}`;
+}
+/**
+ * Wrap an async command function with standard error handling.
+ *
+ * Catches any errors, prints them in red to stderr, and sets process.exitCode to 1.
+ * Uses process.exitCode instead of process.exit() to allow graceful cleanup.
+ *
+ * @param fn - Async function to execute
+ * @returns Promise that resolves when the function completes (or error is handled)
+ *
+ * @example
+ * ```ts
+ * export async function myCommand(options: MyOptions): Promise<void> {
+ *   await withErrorHandling(() => runMyCommand(options));
+ * }
+ * ```
+ */
+export async function withErrorHandling(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        const message = formatError(err);
+        // Import chalk dynamically to avoid circular dependencies
+        const chalk = await import("chalk");
+        console.error(chalk.default.red(`Error: ${message}`));
+        process.exitCode = 1;
+    }
+}

package/dist/utils/file-system.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Checks whether a file or directory exists at the given path.
+ */
+export declare function exists(path: string): Promise<boolean>;
+/**
+ * Writes content to a file atomically using a temp file + rename.
+ * Prevents partial writes from corrupting the target file.
+ */
+export declare function atomicWriteFile(target: string, content: string): Promise<void>;
+/**
+ * Recursively gets all files from a directory.
+ * Returns relative paths using forward slashes (cross-platform).
+ */
+export declare function getFilesRecursive(dir: string, basePath?: string): Promise<string[]>;
+export interface FileWithContent {
+    path: string;
+    size: number;
+    content: string;
+}
+/**
+ * Recursively gets all markdown files from a directory with their content.
+ * Returns relative paths using forward slashes (cross-platform).
+ */
+export declare function getMarkdownFilesWithContent(dir: string, basePath?: string): Promise<FileWithContent[]>;

package/dist/utils/file-system.js

@@ -0,0 +1,99 @@
+import { access, readFile, readdir, stat, writeFile, rename, unlink } from "fs/promises";
+import { join, extname } from "path";
+import { randomUUID } from "crypto";
+import { isEnoent } from "./errors.js";
+/**
+ * Checks whether a file or directory exists at the given path.
+ */
+export async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return false;
+        throw err;
+    }
+}
+/**
+ * Writes content to a file atomically using a temp file + rename.
+ * Prevents partial writes from corrupting the target file.
+ */
+export async function atomicWriteFile(target, content) {
+    const tmp = `${target}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tmp, content, { flag: "wx" });
+        await rename(tmp, target);
+    }
+    catch (err) {
+        try {
+            await unlink(tmp);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw err;
+    }
+}
+/**
+ * Recursively gets all files from a directory.
+ * Returns relative paths using forward slashes (cross-platform).
+ */
+export async function getFilesRecursive(dir, basePath = "") {
+    const files = [];
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                const subFiles = await getFilesRecursive(join(dir, entry.name), relativePath);
+                files.push(...subFiles);
+            }
+            else {
+                files.push(relativePath);
+            }
+        }
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+    }
+    return files;
+}
+/**
+ * Recursively gets all markdown files from a directory with their content.
+ * Returns relative paths using forward slashes (cross-platform).
+ */
+export async function getMarkdownFilesWithContent(dir, basePath = "") {
+    const files = [];
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const fullPath = join(dir, entry.name);
+            const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                const subFiles = await getMarkdownFilesWithContent(fullPath, relativePath);
+                files.push(...subFiles);
+            }
+            else if (entry.isFile() && extname(entry.name).toLowerCase() === ".md") {
+                const stats = await stat(fullPath);
+                const content = await readFile(fullPath, "utf-8");
+                files.push({
+                    path: relativePath,
+                    size: stats.size,
+                    content,
+                });
+            }
+        }
+    }
+    catch (err) {
+        if (!isEnoent(err))
+            throw err;
+    }
+    return files;
+}

package/dist/utils/github.d.ts

@@ -0,0 +1,83 @@
+import type { BundledVersions } from "../installer.js";
+export interface RepoInfo {
+    owner: string;
+    repo: string;
+    branch: string;
+}
+export interface CommitInfo {
+    sha: string;
+    shortSha: string;
+    message: string;
+    date: string;
+}
+export type GitHubErrorType = "network" | "timeout" | "rate-limit" | "not-found" | "api-error";
+export interface GitHubError {
+    type: GitHubErrorType;
+    message: string;
+    repo?: string;
+    status?: number;
+}
+export type FetchResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: GitHubError;
+};
+export interface UpstreamStatus {
+    bundledSha: string;
+    latestSha: string;
+    isUpToDate: boolean;
+    compareUrl: string;
+}
+export interface CheckUpstreamResult {
+    bmad: UpstreamStatus | null;
+    errors: GitHubError[];
+}
+interface FetchOptions {
+    timeoutMs?: number;
+}
+interface GitHubClientOptions {
+    cacheTtlMs?: number;
+    maxCacheSize?: number;
+}
+interface CacheStats {
+    size: number;
+}
+/**
+ * GitHub API client with instance-level caching.
+ * Each instance maintains its own cache, improving testability.
+ */
+export declare class GitHubClient {
+    private cache;
+    private cacheTtlMs;
+    private maxCacheSize;
+    constructor(options?: GitHubClientOptions);
+    clearCache(): void;
+    getCacheStats(): CacheStats;
+    private getCacheKey;
+    private getCachedResult;
+    private setCachedResult;
+    fetchLatestCommit(repo: RepoInfo, options?: FetchOptions): Promise<FetchResult<CommitInfo>>;
+    checkUpstream(bundled: BundledVersions): Promise<CheckUpstreamResult>;
+}
+/**
+ * Determines why upstream checks were skipped based on error types.
+ */
+export declare function getSkipReason(errors: GitHubError[]): string;
+/**
+ * Clear the default client's cache.
+ * For testing, prefer creating a new GitHubClient instance instead.
+ */
+export declare function clearCache(): void;
+/**
+ * Fetch the latest commit from a GitHub repository.
+ * Uses the default shared client instance.
+ */
+export declare function fetchLatestCommit(repo: RepoInfo, options?: FetchOptions): Promise<FetchResult<CommitInfo>>;
+/**
+ * Check upstream repositories for updates.
+ * Uses the default shared client instance.
+ */
+export declare function checkUpstream(bundled: BundledVersions): Promise<CheckUpstreamResult>;
+export {};