bmalph 2.5.0 → 2.6.0

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

@@ -1,21 +0,0 @@
-import type { Story, FixPlanItemWithTitle } from "./types.js";
-export declare function generateFixPlan(stories: Story[], storiesFileName?: string): string;
-export declare function hasFixPlanProgress(content: string): boolean;
-export declare function parseFixPlan(content: string): FixPlanItemWithTitle[];
-/**
- * Detects completed stories that are no longer in the new BMAD output.
- * Returns warnings for each orphaned completed story.
- */
-export declare function detectOrphanedCompletedStories(existingItems: FixPlanItemWithTitle[], newStoryIds: Set<string>): string[];
-/**
- * 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[], 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/index.d.ts

@@ -1,9 +0,0 @@
-export type { ProjectContext, Story, TechStack, FixPlanItem, SpecsChange, TransitionResult, SpecFileType, Priority, SpecFileMetadata, SpecsIndex, } from "./types.js";
-export { parseStories, parseStoriesWithWarnings } from "./story-parsing.js";
-export { generateFixPlan, hasFixPlanProgress, parseFixPlan, mergeFixPlanProgress, } from "./fix-plan.js";
-export { detectTechStack, customizeAgentMd } from "./tech-stack.js";
-export { findArtifactsDir } from "./artifacts.js";
-export { extractSection, extractProjectContext, generateProjectContextMd, generatePrompt, } from "./context.js";
-export { generateSpecsChangelog, formatChangelog } from "./specs-changelog.js";
-export { detectSpecFileType, determinePriority, extractDescription, generateSpecsIndex, formatSpecsIndexMd, } from "./specs-index.js";
-export { runTransition } from "./orchestration.js";

package/dist/transition/orchestration.d.ts

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

package/dist/transition/preflight.d.ts

@@ -1,6 +0,0 @@
-import type { Story, PreflightIssue, PreflightResult } from "./types.js";
-export declare function validatePrd(content: string | null): PreflightIssue[];
-export declare function validateArchitecture(content: string | null): PreflightIssue[];
-export declare function validateStories(stories: Story[], parseWarnings: string[]): PreflightIssue[];
-export declare function validateReadiness(content: string | null): PreflightIssue[];
-export declare function runPreflight(artifactContents: Map<string, string>, files: string[], stories: Story[], parseWarnings: string[]): PreflightResult;

package/dist/transition/specs-changelog.d.ts

@@ -1,3 +0,0 @@
-import type { SpecsChange } from "./types.js";
-export declare function generateSpecsChangelog(oldSpecsDir: string, newSourceDir: string): Promise<SpecsChange[]>;
-export declare function formatChangelog(changes: SpecsChange[], timestamp: string): string;

package/dist/transition/specs-index.d.ts

@@ -1,22 +0,0 @@
-import type { SpecFileType, Priority, SpecsIndex } from "./types.js";
-/**
- * Detects the type of a spec file based on its filename.
- */
-export declare function detectSpecFileType(filename: string, content: string): SpecFileType;
-/**
- * Determines the reading priority for a spec file based on its type.
- */
-export declare function determinePriority(type: SpecFileType, _size: number): Priority;
-/**
- * Extracts a one-line description from file content.
- * Prefers the first heading, falls back to first non-empty line.
- */
-export declare function extractDescription(content: string, maxLength?: number): string;
-/**
- * Generates a specs index from a specs directory.
- */
-export declare function generateSpecsIndex(specsDir: string): Promise<SpecsIndex>;
-/**
- * Formats a specs index as markdown.
- */
-export declare function formatSpecsIndexMd(index: SpecsIndex): string;

package/dist/transition/story-parsing.d.ts

@@ -1,7 +0,0 @@
-import type { Story } from "./types.js";
-export interface ParseStoriesResult {
-    stories: Story[];
-    warnings: string[];
-}
-export declare function parseStories(content: string): Story[];
-export declare function parseStoriesWithWarnings(content: string): ParseStoriesResult;

package/dist/transition/tech-stack.d.ts

@@ -1,3 +0,0 @@
-import type { TechStack } from "./types.js";
-export declare function detectTechStack(content: string): TechStack | null;
-export declare function customizeAgentMd(template: string, stack: TechStack): string;

package/dist/transition/types.d.ts

@@ -1,82 +0,0 @@
-export interface ProjectContext {
-    projectGoals: string;
-    successMetrics: string;
-    architectureConstraints: string;
-    technicalRisks: string;
-    scopeBoundaries: string;
-    targetUsers: string;
-    nonFunctionalRequirements: string;
-    designGuidelines: string;
-    researchInsights: string;
-}
-export interface Story {
-    epic: string;
-    epicDescription: string;
-    id: string;
-    title: string;
-    description: string;
-    acceptanceCriteria: string[];
-}
-export interface TechStack {
-    setup: string;
-    test: string;
-    build: string;
-    dev: string;
-}
-export interface FixPlanItem {
-    id: string;
-    completed: boolean;
-}
-export interface FixPlanItemWithTitle extends FixPlanItem {
-    title?: string;
-}
-export interface TruncationInfo {
-    field: string;
-    originalLength: number;
-    truncatedTo: number;
-}
-export interface SpecsChange {
-    file: string;
-    status: "added" | "modified" | "removed";
-    summary?: string;
-}
-export type SpecFileType = "prd" | "architecture" | "stories" | "ux" | "test-design" | "readiness" | "sprint" | "brainstorm" | "research" | "other";
-export type Priority = "critical" | "high" | "medium" | "low";
-export interface SpecFileMetadata {
-    path: string;
-    size: number;
-    type: SpecFileType;
-    priority: Priority;
-    description: string;
-}
-export interface SpecsIndex {
-    generatedAt: string;
-    totalFiles: number;
-    totalSizeKb: number;
-    files: SpecFileMetadata[];
-}
-export type PreflightSeverity = "error" | "warning" | "info";
-export interface PreflightIssue {
-    id: string;
-    severity: PreflightSeverity;
-    message: string;
-    suggestion?: string;
-}
-export interface PreflightResult {
-    issues: PreflightIssue[];
-    pass: boolean;
-}
-export interface TransitionOptions {
-    force?: boolean;
-}
-export interface GeneratedFile {
-    path: string;
-    action: "created" | "updated";
-}
-export interface TransitionResult {
-    storiesCount: number;
-    warnings: string[];
-    fixPlanPreserved: boolean;
-    preflightIssues?: PreflightIssue[];
-    generatedFiles: GeneratedFile[];
-}

package/dist/utils/config.d.ts

@@ -1,13 +0,0 @@
-import type { PlatformId } from "../platform/types.js";
-export interface UpstreamVersions {
-    bmadCommit: string;
-}
-export interface BmalphConfig {
-    name: string;
-    description: string;
-    createdAt: string;
-    platform?: PlatformId;
-    upstreamVersions?: UpstreamVersions;
-}
-export declare function readConfig(projectDir: string): Promise<BmalphConfig | null>;
-export declare function writeConfig(projectDir: string, config: BmalphConfig): Promise<void>;

package/dist/utils/constants.d.ts

@@ -1,70 +0,0 @@
-/**
- * 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.
- */
-/** Maximum allowed project name length */
-export declare const MAX_PROJECT_NAME_LENGTH = 100;
-/** File size threshold for "large file" warnings (50 KB) */
-export declare const LARGE_FILE_THRESHOLD_BYTES = 50000;
-/** Default max length for extracted content snippets */
-export declare const DEFAULT_SNIPPET_MAX_LENGTH = 60;
-/** Max length for section extraction from documents (increased to preserve full BMAD specs) */
-export declare const SECTION_EXTRACT_MAX_LENGTH = 5000;
-/** Max characters for diff line preview */
-export declare const DIFF_LINE_PREVIEW_LENGTH = 50;
-/** Session age warning threshold (24 hours in milliseconds) */
-export declare const SESSION_AGE_WARNING_MS: number;
-/** API call usage warning threshold (percentage) */
-export declare const API_USAGE_WARNING_PERCENT = 90;
-/** Ralph working directory (contains loop, specs, logs) */
-export declare const RALPH_DIR = ".ralph";
-/** BMAD agents and workflows directory */
-export declare const BMAD_DIR = "_bmad";
-/** bmalph state directory (config, phase tracking) */
-export declare const BMALPH_DIR = "bmalph";
-/** BMAD output directory (planning artifacts) */
-export declare const BMAD_OUTPUT_DIR = "_bmad-output";
-/** Ralph logs directory */
-export declare const RALPH_LOGS_DIR = ".ralph/logs";
-/** Ralph specs directory (copied from _bmad-output) */
-export declare const RALPH_SPECS_DIR = ".ralph/specs";
-/** Claude Code slash commands directory */
-export declare const CLAUDE_COMMANDS_DIR = ".claude/commands";
-/** bmalph state subdirectory (inside BMALPH_DIR) */
-export declare const STATE_DIR = "bmalph/state";
-/** bmalph config file path */
-export declare const CONFIG_FILE = "bmalph/config.json";
-/** Ralph status file path */
-export declare const RALPH_STATUS_FILE = ".ralph/status.json";
-/**
- * Get absolute path to Ralph directory for a project.
- */
-export declare function getRalphDir(projectDir: string): string;
-/**
- * Get absolute path to BMAD directory for a project.
- */
-export declare function getBmadDir(projectDir: string): string;
-/**
- * Get absolute path to bmalph state directory for a project.
- */
-export declare function getBmalphDir(projectDir: string): string;
-/**
- * Get absolute path to BMAD output directory for a project.
- */
-export declare function getBmadOutputDir(projectDir: string): string;
-/**
- * Get absolute path to Ralph logs directory for a project.
- */
-export declare function getRalphLogsDir(projectDir: string): string;
-/**
- * Get absolute path to Ralph specs directory for a project.
- */
-export declare function getRalphSpecsDir(projectDir: string): string;
-/**
- * Get absolute path to Claude commands directory for a project.
- */
-export declare function getClaudeCommandsDir(projectDir: string): string;

package/dist/utils/dryrun.d.ts

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

package/dist/utils/errors.d.ts

@@ -1,63 +0,0 @@
-/**
- * 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/file-system.d.ts

@@ -1,24 +0,0 @@
-/**
- * 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/github.d.ts

@@ -1,83 +0,0 @@
-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 {};

package/dist/utils/json.d.ts

@@ -1,7 +0,0 @@
-/**
- * Reads and parses a JSON file with proper error discrimination:
- * - File not found → returns null
- * - Parse error → throws
- * - Permission error → throws
- */
-export declare function readJsonFile<T>(path: string): Promise<T | null>;

package/dist/utils/logger.d.ts

@@ -1,9 +0,0 @@
-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/state.d.ts

@@ -1,24 +0,0 @@
-import type { RalphLoopStatus } from "./validate.js";
-export interface BmalphState {
-    currentPhase: number;
-    status: "planning" | "implementing" | "completed";
-    startedAt: string;
-    lastUpdated: string;
-}
-export interface PhaseCommand {
-    code: string;
-    name: string;
-    agent: string;
-    description: string;
-    required: boolean;
-}
-export interface PhaseInfo {
-    name: string;
-    agent: string;
-    commands: PhaseCommand[];
-}
-export declare function readState(projectDir: string): Promise<BmalphState | null>;
-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 declare function readRalphStatus(projectDir: string): Promise<RalphLoopStatus>;

package/dist/utils/validate.d.ts

@@ -1,44 +0,0 @@
-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;

package/dist/watch/dashboard.d.ts

@@ -1,4 +0,0 @@
-import type { WatchOptions } from "./types.js";
-export declare function createRefreshCallback(projectDir: string, write: (s: string) => void): () => Promise<void>;
-export declare function setupTerminal(): () => void;
-export declare function startDashboard(options: WatchOptions): Promise<void>;

package/dist/watch/file-watcher.d.ts

@@ -1,9 +0,0 @@
-export declare class FileWatcher {
-    private intervalId;
-    private readonly intervalMs;
-    private readonly callback;
-    constructor(callback: () => void | Promise<void>, intervalMs?: number);
-    start(): void;
-    stop(): void;
-    private tick;
-}

package/dist/watch/renderer.d.ts

@@ -1,16 +0,0 @@
-import type { DashboardState, LoopInfo, CircuitBreakerInfo, StoryProgress, AnalysisInfo, LogEntry, ExecutionProgress, SessionInfo } from "./types.js";
-export declare function padRight(str: string, len: number): string;
-export declare function progressBar(completed: number, total: number, width: number): string;
-export declare function formatSessionAge(createdAt: string): string;
-export declare function formatStatus(status: string): string;
-export declare function formatCBState(state: string): string;
-export declare function box(title: string, lines: string[], cols: number): string;
-export declare function renderHeader(cols: number): string;
-export declare function renderLoopPanel(loop: LoopInfo | null, execution: ExecutionProgress | null, session: SessionInfo | null, cols: number): string;
-export declare function renderCircuitBreakerPanel(cb: CircuitBreakerInfo | null, cols: number): string;
-export declare function renderStoriesPanel(stories: StoryProgress | null, cols: number): string;
-export declare function renderSideBySide(left: string, right: string, cols: number): string;
-export declare function renderAnalysisPanel(analysis: AnalysisInfo | null, cols: number): string;
-export declare function renderLogsPanel(logs: LogEntry[], cols: number): string;
-export declare function renderFooter(lastUpdated: Date, cols: number): string;
-export declare function renderDashboard(state: DashboardState, cols?: number): string;

package/dist/watch/state-reader.d.ts

@@ -1,9 +0,0 @@
-import type { DashboardState, LoopInfo, CircuitBreakerInfo, StoryProgress, AnalysisInfo, ExecutionProgress, SessionInfo, LogEntry } from "./types.js";
-export declare function readDashboardState(projectDir: string): Promise<DashboardState>;
-export declare function readLoopInfo(projectDir: string): Promise<LoopInfo | null>;
-export declare function readCircuitBreakerInfo(projectDir: string): Promise<CircuitBreakerInfo | null>;
-export declare function readStoryProgress(projectDir: string): Promise<StoryProgress | null>;
-export declare function readAnalysisInfo(projectDir: string): Promise<AnalysisInfo | null>;
-export declare function readExecutionProgress(projectDir: string): Promise<ExecutionProgress | null>;
-export declare function readSessionInfo(projectDir: string): Promise<SessionInfo | null>;
-export declare function readRecentLogs(projectDir: string, maxLines?: number): Promise<LogEntry[]>;

package/dist/watch/types.d.ts

@@ -1,55 +0,0 @@
-export interface LoopInfo {
-    loopCount: number;
-    status: string;
-    lastAction: string;
-    callsMadeThisHour: number;
-    maxCallsPerHour: number;
-}
-export interface CircuitBreakerInfo {
-    state: "CLOSED" | "HALF_OPEN" | "OPEN";
-    consecutiveNoProgress: number;
-    totalOpens: number;
-    reason?: string;
-}
-export interface StoryProgress {
-    completed: number;
-    total: number;
-    nextStory: string | null;
-}
-export interface AnalysisInfo {
-    filesModified: number;
-    confidenceScore: number;
-    isTestOnly: boolean;
-    isStuck: boolean;
-    exitSignal: boolean;
-    hasPermissionDenials: boolean;
-    permissionDenialCount: number;
-}
-export interface ExecutionProgress {
-    status: "executing" | "idle";
-    elapsedSeconds: number;
-}
-export interface SessionInfo {
-    createdAt: string;
-    lastUsed?: string;
-}
-export interface LogEntry {
-    timestamp: string;
-    level: string;
-    message: string;
-}
-export interface DashboardState {
-    loop: LoopInfo | null;
-    circuitBreaker: CircuitBreakerInfo | null;
-    stories: StoryProgress | null;
-    analysis: AnalysisInfo | null;
-    execution: ExecutionProgress | null;
-    session: SessionInfo | null;
-    recentLogs: LogEntry[];
-    ralphCompleted: boolean;
-    lastUpdated: Date;
-}
-export interface WatchOptions {
-    interval: number;
-    projectDir: string;
-}