ralphctl 0.1.0

package/src/utils/detect-scripts.ts

@@ -0,0 +1,247 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Canonical project-type detection and script suggestion.
+ *
+ * Used during `project add` and `project repo add` to pre-fill setup/verify
+ * scripts as editable suggestions. NOT used at runtime — scripts must come
+ * from explicit repo config only.
+ */
+
+export type ProjectType = 'node' | 'python' | 'go' | 'rust' | 'java-gradle' | 'java-maven' | 'makefile' | 'other';
+
+export interface CheckCandidate {
+  label: string;
+  command: string;
+  selected: boolean;
+}
+
+export interface DetectionResult {
+  type: ProjectType;
+  typeLabel: string;
+  installCommand: string | null;
+  candidates: CheckCandidate[];
+}
+
+/**
+ * Detect project type from files in the path.
+ */
+export function detectProjectType(projectPath: string): ProjectType {
+  if (existsSync(join(projectPath, 'package.json'))) return 'node';
+  if (existsSync(join(projectPath, 'pyproject.toml')) || existsSync(join(projectPath, 'setup.py'))) return 'python';
+  if (existsSync(join(projectPath, 'go.mod'))) return 'go';
+  if (existsSync(join(projectPath, 'Cargo.toml'))) return 'rust';
+  if (existsSync(join(projectPath, 'build.gradle')) || existsSync(join(projectPath, 'build.gradle.kts')))
+    return 'java-gradle';
+  if (existsSync(join(projectPath, 'pom.xml'))) return 'java-maven';
+  if (existsSync(join(projectPath, 'Makefile'))) return 'makefile';
+  return 'other';
+}
+
+/**
+ * Get human-readable label for project type.
+ */
+export function getProjectTypeLabel(type: ProjectType): string {
+  const labels: Record<ProjectType, string> = {
+    node: 'Node.js',
+    python: 'Python',
+    go: 'Go',
+    rust: 'Rust',
+    'java-gradle': 'Java (Gradle)',
+    'java-maven': 'Java (Maven)',
+    makefile: 'Makefile',
+    other: 'Unknown',
+  };
+  return labels[type];
+}
+
+// ---------------------------------------------------------------------------
+// Internal: Node.js package manager detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the Node.js package manager from lockfiles.
+ */
+function detectNodePackageManager(projectPath: string): string {
+  if (existsSync(join(projectPath, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(join(projectPath, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+// ---------------------------------------------------------------------------
+// Ecosystem detector registry
+// ---------------------------------------------------------------------------
+
+interface EcosystemDetector {
+  type: ProjectType;
+  label: string;
+  detect: (path: string) => boolean;
+  getInstallCommand: (path: string) => string | null;
+  getCandidates: (path: string) => CheckCandidate[];
+}
+
+/** Alias groups for Node.js script detection — first match wins per group. */
+const NODE_PRIMARY_GROUPS: { label: string; aliases: string[] }[] = [
+  { label: 'linting', aliases: ['lint', 'eslint', 'lint:check'] },
+  { label: 'type checking', aliases: ['typecheck', 'type-check', 'tsc', 'check-types'] },
+  { label: 'tests', aliases: ['test', 'test:unit', 'test:run', 'vitest', 'jest'] },
+];
+
+const NODE_FALLBACK_GROUPS: { label: string; aliases: string[] }[] = [
+  { label: 'build', aliases: ['build', 'compile'] },
+];
+
+function readPackageJsonScripts(projectPath: string): Record<string, string> {
+  try {
+    const raw = readFileSync(join(projectPath, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw) as { scripts?: Record<string, string> };
+    return pkg.scripts ?? {};
+  } catch {
+    return {};
+  }
+}
+
+const nodeDetector: EcosystemDetector = {
+  type: 'node',
+  label: 'Node.js',
+  detect: (path) => existsSync(join(path, 'package.json')),
+  getInstallCommand: (path) => {
+    const pm = detectNodePackageManager(path);
+    return `${pm} install`;
+  },
+  getCandidates: (path) => {
+    const scripts = readPackageJsonScripts(path);
+    const pm = detectNodePackageManager(path);
+    const run = pm === 'npm' ? 'npm run' : pm;
+    const candidates: CheckCandidate[] = [];
+
+    for (const group of NODE_PRIMARY_GROUPS) {
+      const match = group.aliases.find((name) => name in scripts);
+      if (match) {
+        candidates.push({ label: group.label, command: `${run} ${match}`, selected: true });
+      }
+    }
+
+    if (candidates.length === 0) {
+      for (const group of NODE_FALLBACK_GROUPS) {
+        const match = group.aliases.find((name) => name in scripts);
+        if (match) {
+          candidates.push({ label: group.label, command: `${run} ${match}`, selected: false });
+        }
+      }
+    }
+
+    return candidates;
+  },
+};
+
+const pythonDetector: EcosystemDetector = {
+  type: 'python',
+  label: 'Python',
+  detect: (path) => existsSync(join(path, 'pyproject.toml')) || existsSync(join(path, 'setup.py')),
+  getInstallCommand: (path) => {
+    if (existsSync(join(path, 'uv.lock'))) return 'uv sync';
+    if (existsSync(join(path, 'requirements.txt'))) return 'pip install -r requirements.txt';
+    if (existsSync(join(path, 'pyproject.toml'))) return 'pip install -e .';
+    return null;
+  },
+  getCandidates: () => [{ label: 'tests', command: 'pytest', selected: true }],
+};
+
+const goDetector: EcosystemDetector = {
+  type: 'go',
+  label: 'Go',
+  detect: (path) => existsSync(join(path, 'go.mod')),
+  getInstallCommand: () => 'go mod download',
+  getCandidates: () => [
+    { label: 'tests', command: 'go test ./...', selected: true },
+    { label: 'vet', command: 'go vet ./...', selected: true },
+  ],
+};
+
+const rustDetector: EcosystemDetector = {
+  type: 'rust',
+  label: 'Rust',
+  detect: (path) => existsSync(join(path, 'Cargo.toml')),
+  getInstallCommand: () => 'cargo build',
+  getCandidates: () => [
+    { label: 'tests', command: 'cargo test', selected: true },
+    { label: 'clippy', command: 'cargo clippy', selected: false },
+  ],
+};
+
+const gradleDetector: EcosystemDetector = {
+  type: 'java-gradle' as ProjectType,
+  label: 'Java (Gradle)',
+  detect: (path) => existsSync(join(path, 'build.gradle')) || existsSync(join(path, 'build.gradle.kts')),
+  getInstallCommand: () => null,
+  getCandidates: () => [{ label: 'clean build', command: './gradlew clean build', selected: true }],
+};
+
+const mavenDetector: EcosystemDetector = {
+  type: 'java-maven' as ProjectType,
+  label: 'Java (Maven)',
+  detect: (path) => existsSync(join(path, 'pom.xml')),
+  getInstallCommand: () => null,
+  getCandidates: () => [{ label: 'clean install', command: 'mvn clean install', selected: true }],
+};
+
+const makefileDetector: EcosystemDetector = {
+  type: 'makefile' as ProjectType,
+  label: 'Makefile',
+  detect: (path) => existsSync(join(path, 'Makefile')),
+  getInstallCommand: () => null,
+  getCandidates: () => [{ label: 'check/test', command: 'make check || make test', selected: true }],
+};
+
+/** Ordered by priority — first match wins. */
+const ECOSYSTEM_REGISTRY: EcosystemDetector[] = [
+  nodeDetector,
+  pythonDetector,
+  goDetector,
+  rustDetector,
+  gradleDetector,
+  mavenDetector,
+  makefileDetector,
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect ecosystem and return structured check-script candidates.
+ * Returns null if the project type is unrecognized ('other').
+ */
+export function detectCheckScriptCandidates(projectPath: string): DetectionResult | null {
+  for (const detector of ECOSYSTEM_REGISTRY) {
+    if (detector.detect(projectPath)) {
+      return {
+        type: detector.type,
+        typeLabel: detector.label,
+        installCommand: detector.getInstallCommand(projectPath),
+        candidates: detector.getCandidates(projectPath),
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Convenience wrapper: detect ecosystem and combine install command with
+ * pre-selected candidates into a single shell command string.
+ * Returns null if no ecosystem is detected.
+ */
+export function suggestCheckScript(projectPath: string): string | null {
+  const result = detectCheckScriptCandidates(projectPath);
+  if (!result) return null;
+
+  const parts: string[] = [];
+  if (result.installCommand) parts.push(result.installCommand);
+
+  const selected = result.candidates.filter((c) => c.selected).map((c) => c.command);
+  parts.push(...selected);
+
+  return parts.length > 0 ? parts.join(' && ') : null;
+}

package/src/utils/editor-input.ts

@@ -0,0 +1,41 @@
+import { editor } from '@inquirer/prompts';
+import { resolveEditor } from '@src/utils/editor.ts';
+
+export interface EditorInputOptions {
+  /** Message/prompt to display */
+  message: string;
+  /** Default value (pre-populated in the editor) */
+  default?: string;
+}
+
+/**
+ * Open the user's configured editor for multiline text input.
+ * Uses @inquirer/editor under the hood, with the editor resolved from config.
+ *
+ * Falls back to readline-based multilineInput when stdin is not a TTY.
+ */
+export async function editorInput(options: EditorInputOptions): Promise<string> {
+  // Non-TTY fallback: delegate to readline-based multilineInput
+  if (!process.stdin.isTTY) {
+    const { multilineInput } = await import('@src/utils/multiline.ts');
+    return multilineInput({ message: options.message, default: options.default });
+  }
+
+  const editorCmd = await resolveEditor();
+
+  // Temporarily set VISUAL so @inquirer/editor uses our configured editor
+  const prevVisual = process.env['VISUAL'];
+  process.env['VISUAL'] = editorCmd;
+
+  try {
+    const result = await editor({
+      message: options.message,
+      default: options.default,
+      postfix: '.md',
+    });
+    return result.trim();
+  } finally {
+    if (prevVisual === undefined) delete process.env['VISUAL'];
+    else process.env['VISUAL'] = prevVisual;
+  }
+}

package/src/utils/editor.ts

@@ -0,0 +1,37 @@
+import { select } from '@inquirer/prompts';
+import { getEditor, setEditor } from '@src/store/config.ts';
+import { emoji } from '@src/theme/ui.ts';
+
+/**
+ * Resolve the configured editor command.
+ * Reads from config; if not set, prompts the user to choose and saves the selection.
+ */
+export async function resolveEditor(): Promise<string> {
+  const stored = await getEditor();
+  if (stored) return stored;
+
+  const choice = await select({
+    message: `${emoji.donut} Which editor should open for multiline input?`,
+    choices: [
+      { name: 'Sublime Text', value: 'subl -w' },
+      { name: 'VS Code', value: 'code --wait' },
+      { name: 'Vim', value: 'vim' },
+      { name: 'Nano', value: 'nano' },
+      { name: 'Use $EDITOR env var', value: '__env__' },
+    ],
+  });
+
+  if (choice === '__env__') {
+    const envEditor = process.env['VISUAL'] ?? process.env['EDITOR'];
+    if (!envEditor) {
+      // Fallback: no env var set, default to vim
+      await setEditor('vim');
+      return 'vim';
+    }
+    await setEditor(envEditor);
+    return envEditor;
+  }
+
+  await setEditor(choice);
+  return choice;
+}

package/src/utils/exit-codes.ts

@@ -0,0 +1,27 @@
+/**
+ * Exit codes for CLI commands.
+ * Using structured exit codes enables scripting and CI/CD integration.
+ */
+
+/** Success - all requested operations completed successfully */
+export const EXIT_SUCCESS = 0;
+
+/** Error - validation failed, missing params, execution error, etc. */
+export const EXIT_ERROR = 1;
+
+/** No tasks - no tasks available to execute */
+export const EXIT_NO_TASKS = 2;
+
+/** All blocked - remaining tasks are blocked by dependencies */
+export const EXIT_ALL_BLOCKED = 3;
+
+/** Interrupted - SIGINT received (standard Unix convention: 128 + 2) */
+export const EXIT_INTERRUPTED = 130;
+
+/**
+ * Exit with the given code (wrapper for testability).
+ * In non-interactive mode, commands should use this to signal outcome.
+ */
+export function exitWithCode(code: number): never {
+  process.exit(code);
+}

package/src/utils/file-lock.ts

@@ -0,0 +1,135 @@
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/**
+ * Simple file-based lock for preventing concurrent access.
+ * Uses a .lock file with process info.
+ */
+
+export class LockAcquisitionError extends Error {
+  public readonly lockPath: string;
+
+  constructor(message: string, lockPath: string) {
+    super(message);
+    this.name = 'LockAcquisitionError';
+    this.lockPath = lockPath;
+  }
+}
+
+export interface LockInfo {
+  pid: number;
+  timestamp: number;
+}
+
+/** How long (ms) before a lock file is considered stale. Override with RALPHCTL_LOCK_TIMEOUT_MS (1 to 3600000). */
+const parsed = parseInt(process.env['RALPHCTL_LOCK_TIMEOUT_MS'] ?? '', 10);
+export const LOCK_TIMEOUT_MS = parsed > 0 && parsed <= 3_600_000 ? parsed : 30_000;
+
+/** Delay (ms) between retry attempts when a lock is held by another process. */
+export const RETRY_DELAY_MS = 50;
+
+/** Maximum number of retries before giving up (~5 seconds at default RETRY_DELAY_MS). */
+export const MAX_RETRIES = 100;
+
+function getLockPath(filePath: string): string {
+  return `${filePath}.lock`;
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if a lock file is stale (old process that may have crashed).
+ */
+async function isLockStale(lockPath: string): Promise<boolean> {
+  try {
+    const content = await readFile(lockPath, 'utf-8');
+    const info: LockInfo = JSON.parse(content) as LockInfo;
+
+    // Check if lock is old enough to be considered stale
+    const age = Date.now() - info.timestamp;
+    if (age > LOCK_TIMEOUT_MS) {
+      return true;
+    }
+
+    // Check if the process is still running (only works for same-machine processes)
+    try {
+      process.kill(info.pid, 0); // signal 0 tests existence
+      return false; // Process exists
+    } catch {
+      return true; // Process doesn't exist
+    }
+  } catch {
+    // Lock file is corrupted or unreadable, consider it stale
+    return true;
+  }
+}
+
+/**
+ * Acquire a lock on a file path.
+ * Returns a release function that must be called when done.
+ */
+export async function acquireLock(filePath: string): Promise<() => Promise<void>> {
+  const lockPath = getLockPath(filePath);
+  const lockInfo: LockInfo = {
+    pid: process.pid,
+    timestamp: Date.now(),
+  };
+
+  let retries = 0;
+
+  while (retries < MAX_RETRIES) {
+    try {
+      // Ensure directory exists
+      await mkdir(dirname(lockPath), { recursive: true });
+
+      // Try to create lock file exclusively
+      await writeFile(lockPath, JSON.stringify(lockInfo), { flag: 'wx', mode: 0o600 });
+
+      // Success - return release function
+      return async () => {
+        try {
+          await unlink(lockPath);
+        } catch {
+          // Ignore errors during cleanup
+        }
+      };
+    } catch (err) {
+      // File exists - check if stale
+      if (err instanceof Error && 'code' in err && err.code === 'EEXIST') {
+        if (await isLockStale(lockPath)) {
+          // Remove stale lock and retry immediately
+          try {
+            await unlink(lockPath);
+          } catch {
+            // Ignore - another process may have grabbed it
+          }
+          continue;
+        }
+
+        // Lock is active, wait and retry
+        retries++;
+        await sleep(RETRY_DELAY_MS);
+        continue;
+      }
+
+      throw err;
+    }
+  }
+
+  throw new LockAcquisitionError(`Failed to acquire lock after ${String(MAX_RETRIES)} retries`, lockPath);
+}
+
+/**
+ * Execute a function with a file lock.
+ * Automatically acquires and releases the lock.
+ */
+export async function withFileLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+  const release = await acquireLock(filePath);
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+}

package/src/utils/git.ts

@@ -0,0 +1,185 @@
+import { spawnSync } from 'node:child_process';
+import { assertSafeCwd } from '@src/utils/paths.ts';
+
+/**
+ * Git utility functions for branch management.
+ *
+ * All functions validate their cwd via assertSafeCwd() before running
+ * any git commands — no raw user input reaches the shell.
+ */
+
+// Branch name pattern: alphanumeric, hyphens, underscores, dots, and slashes.
+// Rejects control chars, spaces, ~, ^, :, ?, *, [, \, consecutive dots, trailing dots/slashes/locks.
+const BRANCH_NAME_RE = /^[a-zA-Z0-9/_.-]+$/;
+const BRANCH_NAME_INVALID_PATTERNS = [/\.\./, /\.$/, /\/$/, /\.lock$/, /^-/, /\/\//];
+
+/**
+ * Validate a branch name is safe for git operations.
+ * Based on `git check-ref-format` rules.
+ */
+export function isValidBranchName(name: string): boolean {
+  if (!name || name.length > 250) return false;
+  if (!BRANCH_NAME_RE.test(name)) return false;
+  for (const pattern of BRANCH_NAME_INVALID_PATTERNS) {
+    if (pattern.test(name)) return false;
+  }
+  return true;
+}
+
+/**
+ * Get the current branch name.
+ * Returns 'HEAD' if in detached HEAD state.
+ */
+export function getCurrentBranch(cwd: string): string {
+  assertSafeCwd(cwd);
+  const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    throw new Error(`Failed to get current branch in ${cwd}: ${result.stderr.trim()}`);
+  }
+  return result.stdout.trim();
+}
+
+/**
+ * Check if a local branch exists.
+ */
+export function branchExists(cwd: string, name: string): boolean {
+  assertSafeCwd(cwd);
+  if (!isValidBranchName(name)) {
+    throw new Error(`Invalid branch name: ${name}`);
+  }
+  const result = spawnSync('git', ['show-ref', '--verify', `refs/heads/${name}`], {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return result.status === 0;
+}
+
+/**
+ * Create a new branch and check it out, or check out if it already exists.
+ * Idempotent — safe to call on resume/crash recovery.
+ */
+export function createAndCheckoutBranch(cwd: string, name: string): void {
+  assertSafeCwd(cwd);
+  if (!isValidBranchName(name)) {
+    throw new Error(`Invalid branch name: ${name}`);
+  }
+
+  const current = getCurrentBranch(cwd);
+  if (current === name) {
+    return; // Already on the requested branch
+  }
+
+  if (branchExists(cwd, name)) {
+    // Branch exists — just check it out
+    const result = spawnSync('git', ['checkout', name], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+      throw new Error(`Failed to checkout branch '${name}' in ${cwd}: ${result.stderr.trim()}`);
+    }
+  } else {
+    // Create and checkout new branch
+    const result = spawnSync('git', ['checkout', '-b', name], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+      throw new Error(`Failed to create branch '${name}' in ${cwd}: ${result.stderr.trim()}`);
+    }
+  }
+}
+
+/**
+ * Verify that the repo is on the expected branch.
+ * Returns true if current branch matches expected.
+ */
+export function verifyCurrentBranch(cwd: string, expected: string): boolean {
+  const current = getCurrentBranch(cwd);
+  return current === expected;
+}
+
+/**
+ * Detect the default branch (main or master) from remote origin.
+ * Falls back to checking local branches if no remote is configured.
+ * Throws on unexpected git errors (permissions, corrupted repo, etc.).
+ */
+export function getDefaultBranch(cwd: string): string {
+  assertSafeCwd(cwd);
+  const result = spawnSync('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  if (result.status === 0) {
+    // refs/remotes/origin/main → main
+    const ref = result.stdout.trim();
+    const parts = ref.split('/');
+    return parts[parts.length - 1] ?? 'main';
+  }
+
+  // "not a symbolic ref" — remote ref not configured, safe to fall through
+  const stderr = result.stderr.trim();
+  if (stderr.includes('is not a symbolic ref') || stderr.includes('No such ref')) {
+    if (branchExists(cwd, 'main')) return 'main';
+    if (branchExists(cwd, 'master')) return 'master';
+    return 'main';
+  }
+
+  // Unexpected error — don't swallow it
+  throw new Error(`Failed to detect default branch in ${cwd}: ${stderr}`);
+}
+
+/**
+ * Check if the working directory has uncommitted changes (staged or unstaged).
+ */
+export function hasUncommittedChanges(cwd: string): boolean {
+  assertSafeCwd(cwd);
+  const result = spawnSync('git', ['status', '--porcelain'], {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    throw new Error(`Failed to check git status in ${cwd}: ${result.stderr.trim()}`);
+  }
+  return result.stdout.trim().length > 0;
+}
+
+/**
+ * Generate a branch name from a sprint ID.
+ * Format: `ralphctl/<sprint-id>`
+ */
+export function generateBranchName(sprintId: string): string {
+  return `ralphctl/${sprintId}`;
+}
+
+/**
+ * Check if the `gh` CLI is available in PATH.
+ */
+export function isGhAvailable(): boolean {
+  const result = spawnSync('gh', ['--version'], {
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return result.status === 0;
+}
+
+/**
+ * Check if the `glab` CLI is available in PATH.
+ */
+export function isGlabAvailable(): boolean {
+  const result = spawnSync('glab', ['--version'], {
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return result.status === 0;
+}