ralphctl 0.1.0 → 0.1.2

package/src/utils/ids.ts

@@ -1,37 +0,0 @@
-import { randomBytes } from 'node:crypto';
-
-/**
- * Generate an 8-character UUID-like ID.
- * Used for tickets and tasks.
- */
-export function generateUuid8(): string {
-  return randomBytes(4).toString('hex');
-}
-
-/**
- * Sanitize a string into a URL/filesystem-safe slug.
- * Lowercase, alphanumeric + hyphens only, max 40 characters.
- */
-export function slugify(input: string, maxLength = 40): string {
-  return input
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .replace(/-{2,}/g, '-')
-    .slice(0, maxLength)
-    .replace(/-$/, ''); // Remove trailing hyphen if truncation created one
-}
-
-/**
- * Generate a sprint ID in the format: YYYYMMDD-HHmmss-<slug>
- * Lexicographically sortable by creation time.
- */
-export function generateSprintId(name?: string): string {
-  const now = new Date();
-  // Format: YYYYMMDD-HHmmss (remove non-digits from ISO string parts)
-  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
-  const time = now.toISOString().slice(11, 19).replace(/:/g, '');
-  const slug = name ? slugify(name) : generateUuid8();
-
-  return `${date}-${time}-${slug || generateUuid8()}`;
-}

package/src/utils/issue-fetch.ts

@@ -1,244 +0,0 @@
-import { spawnSync } from 'node:child_process';
-
-const MAX_COMMENTS = 20;
-
-export interface IssueComment {
-  author: string;
-  createdAt: string;
-  body: string;
-}
-
-export interface IssueData {
-  title: string;
-  body: string;
-  comments: IssueComment[];
-  url: string;
-}
-
-export interface ParsedIssueUrl {
-  host: 'github' | 'gitlab';
-  hostname: string;
-  owner: string;
-  repo: string;
-  number: number;
-}
-
-/**
- * Parse a GitHub or GitLab issue URL into its components.
- * Returns null if the URL is not a recognized issue URL.
- *
- * GitHub: https://github.com/owner/repo/issues/123
- * GitLab: https://gitlab.example.com/group/project/-/issues/456
- *         (any hostname with /-/issues/ path segment)
- */
-export function parseIssueUrl(url: string): ParsedIssueUrl | null {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return null;
-  }
-
-  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
-    return null;
-  }
-
-  const segments = parsed.pathname.split('/').filter(Boolean);
-
-  // GitHub: /owner/repo/issues/123
-  if (parsed.hostname === 'github.com') {
-    const owner = segments[0];
-    const repo = segments[1];
-    if (segments.length >= 4 && segments[2] === 'issues' && owner && repo) {
-      const num = Number(segments[3]);
-      if (Number.isInteger(num) && num > 0) {
-        return { host: 'github', hostname: parsed.hostname, owner, repo, number: num };
-      }
-    }
-    return null;
-  }
-
-  // GitLab (any hostname): /.../group/project/-/issues/456
-  const dashIdx = segments.indexOf('-');
-  if (dashIdx >= 2 && segments[dashIdx + 1] === 'issues') {
-    const num = Number(segments[dashIdx + 2]);
-    if (Number.isInteger(num) && num > 0) {
-      const repo = segments[dashIdx - 1];
-      if (repo) {
-        const owner = segments.slice(0, dashIdx - 1).join('/');
-        return { host: 'gitlab', hostname: parsed.hostname, owner, repo, number: num };
-      }
-    }
-  }
-
-  return null;
-}
-
-interface GhComment {
-  author?: { login?: string };
-  body?: string;
-  createdAt?: string;
-}
-
-interface GhIssueResponse {
-  title?: string;
-  body?: string;
-  comments?: GhComment[];
-}
-
-interface GlabNote {
-  author?: { username?: string };
-  body?: string;
-  created_at?: string;
-}
-
-interface GlabIssueResponse {
-  title?: string;
-  description?: string;
-  notes?: GlabNote[];
-}
-
-function fetchGitHubIssue(parsed: ParsedIssueUrl): IssueData {
-  const result = spawnSync(
-    'gh',
-    [
-      'issue',
-      'view',
-      String(parsed.number),
-      '--repo',
-      `${parsed.owner}/${parsed.repo}`,
-      '--json',
-      'title,body,comments',
-    ],
-    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30_000 }
-  );
-
-  if (result.status !== 0) {
-    const stderr = result.stderr.trim();
-    throw new IssueFetchError(`gh issue view failed: ${stderr || 'unknown error'}`);
-  }
-
-  const data = JSON.parse(result.stdout) as GhIssueResponse;
-
-  const comments: IssueComment[] = (data.comments ?? []).slice(-MAX_COMMENTS).map((c) => ({
-    author: c.author?.login ?? 'unknown',
-    createdAt: c.createdAt ?? '',
-    body: c.body ?? '',
-  }));
-
-  return {
-    title: data.title ?? '',
-    body: data.body ?? '',
-    comments,
-    url: `https://${parsed.hostname}/${parsed.owner}/${parsed.repo}/issues/${String(parsed.number)}`,
-  };
-}
-
-function fetchGitLabIssue(parsed: ParsedIssueUrl): IssueData {
-  // Fetch issue details
-  const result = spawnSync(
-    'glab',
-    ['issue', 'view', String(parsed.number), '--repo', `${parsed.owner}/${parsed.repo}`, '--output', 'json'],
-    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30_000 }
-  );
-
-  if (result.status !== 0) {
-    const stderr = result.stderr.trim();
-    throw new IssueFetchError(`glab issue view failed: ${stderr || 'unknown error'}`);
-  }
-
-  const data = JSON.parse(result.stdout) as GlabIssueResponse;
-
-  // Fetch issue notes (comments) separately
-  const notesResult = spawnSync(
-    'glab',
-    ['issue', 'note', 'list', String(parsed.number), '--repo', `${parsed.owner}/${parsed.repo}`, '--output', 'json'],
-    { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30_000 }
-  );
-
-  let comments: IssueComment[] = [];
-  if (notesResult.status === 0 && notesResult.stdout.trim()) {
-    try {
-      const notes = JSON.parse(notesResult.stdout) as GlabNote[];
-      comments = notes.slice(-MAX_COMMENTS).map((n) => ({
-        author: n.author?.username ?? 'unknown',
-        createdAt: n.created_at ?? '',
-        body: n.body ?? '',
-      }));
-    } catch {
-      // Non-fatal — continue without comments
-    }
-  }
-
-  return {
-    title: data.title ?? '',
-    body: data.description ?? '',
-    comments,
-    url: `https://${parsed.hostname}/${parsed.owner}/${parsed.repo}/-/issues/${String(parsed.number)}`,
-  };
-}
-
-/**
- * Fetch issue data from GitHub or GitLab using CLI tools.
- * Throws IssueFetchError on failure.
- */
-export function fetchIssue(parsed: ParsedIssueUrl): IssueData {
-  if (parsed.host === 'github') {
-    return fetchGitHubIssue(parsed);
-  }
-  return fetchGitLabIssue(parsed);
-}
-
-/**
- * Fetch issue data from a URL string. Convenience wrapper around parseIssueUrl + fetchIssue.
- * Returns null if the URL is not a recognized issue URL.
- * Throws IssueFetchError on fetch failure.
- */
-export function fetchIssueFromUrl(url: string): IssueData | null {
-  const parsed = parseIssueUrl(url);
-  if (!parsed) return null;
-  return fetchIssue(parsed);
-}
-
-/**
- * Format issue data as markdown context for AI prompts.
- */
-export function formatIssueContext(data: IssueData): string {
-  const lines: string[] = [];
-
-  lines.push('## Source Issue Data');
-  lines.push('');
-  lines.push(`> Fetched live from ${data.url}`);
-  lines.push('');
-  lines.push(`**Title:** ${data.title}`);
-  lines.push('');
-
-  if (data.body) {
-    lines.push('**Body:**');
-    lines.push('');
-    lines.push(data.body);
-    lines.push('');
-  }
-
-  if (data.comments.length > 0) {
-    lines.push(`**Comments (${String(data.comments.length)}):**`);
-    lines.push('');
-    for (const comment of data.comments) {
-      const timestamp = comment.createdAt ? ` (${comment.createdAt})` : '';
-      lines.push(`---`);
-      lines.push(`**@${comment.author}**${timestamp}:`);
-      lines.push('');
-      lines.push(comment.body);
-      lines.push('');
-    }
-  }
-
-  return lines.join('\n');
-}
-
-export class IssueFetchError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'IssueFetchError';
-  }
-}

package/src/utils/json-extract.ts

@@ -1,62 +0,0 @@
-/**
- * Extract a complete JSON structure (array or object) from text that may contain surrounding content.
- * Uses depth tracking to handle nested structures and strings containing brackets/braces.
- */
-function extractJsonStructure(output: string, open: string, close: string, typeName: string): string {
-  const start = output.indexOf(open);
-  if (start === -1) {
-    throw new Error(`No JSON ${typeName} found in output`);
-  }
-
-  let depth = 0;
-  let inString = false;
-  let escape = false;
-  for (let i = start; i < output.length; i++) {
-    const ch = output[i];
-    if (escape) {
-      escape = false;
-      continue;
-    }
-    if (ch === '\\' && inString) {
-      escape = true;
-      continue;
-    }
-    if (ch === '"') {
-      inString = !inString;
-      continue;
-    }
-    if (inString) continue;
-    if (ch === open) depth++;
-    if (ch === close) {
-      depth--;
-      if (depth === 0) {
-        return output.slice(start, i + 1);
-      }
-    }
-  }
-  throw new Error(`No complete JSON ${typeName} found in output`);
-}
-
-/**
- * Extract a complete JSON array from text that may contain surrounding content.
- * Uses bracket-depth tracking to handle nested arrays and strings containing brackets.
- *
- * @param output - The text containing a JSON array
- * @returns The extracted JSON array string
- * @throws Error if no complete JSON array is found
- */
-export function extractJsonArray(output: string): string {
-  return extractJsonStructure(output, '[', ']', 'array');
-}
-
-/**
- * Extract a complete JSON object from text that may contain surrounding content.
- * Uses brace-depth tracking to handle nested objects and strings containing braces.
- *
- * @param output - The text containing a JSON object
- * @returns The extracted JSON object string
- * @throws Error if no complete JSON object is found
- */
-export function extractJsonObject(output: string): string {
-  return extractJsonStructure(output, '{', '}', 'object');
-}

package/src/utils/multiline.ts

@@ -1,61 +0,0 @@
-import * as readline from 'node:readline';
-import { muted } from '@src/theme/index.ts';
-import { icons } from '@src/theme/ui.ts';
-
-export interface MultilineInputOptions {
-  /** Message/prompt to display */
-  message: string;
-  /** Default value (will be shown as initial lines) */
-  default?: string;
-  /** Hint text shown after the message */
-  hint?: string;
-}
-
-/**
- * Prompt for multiline input with paste support.
- * Ctrl+D to finish (standard Unix EOF).
- * Supports pasting multiline text including blank lines.
- *
- * @returns Joined lines as a single string
- */
-export async function multilineInput(options: MultilineInputOptions): Promise<string> {
-  const { message, default: defaultValue, hint = 'Ctrl+D to finish' } = options;
-
-  // Show the prompt with hint
-  console.log(`${icons.edit} ${message} ${muted(`(${hint})`)}`);
-
-  // If there's a default value, show it
-  if (defaultValue) {
-    console.log(muted('  Default:'));
-    for (const line of defaultValue.split('\n')) {
-      console.log(muted(`    ${line}`));
-    }
-    console.log('');
-  }
-
-  const lines: string[] = [];
-
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-    terminal: process.stdin.isTTY,
-  });
-
-  return new Promise<string>((resolve) => {
-    rl.on('line', (line) => {
-      lines.push(line);
-    });
-
-    rl.on('close', () => {
-      // Print newline after Ctrl+D for clean formatting
-      console.log('');
-
-      // Trim trailing empty lines
-      while (lines.length > 0 && lines.at(-1)?.trim() === '') {
-        lines.pop();
-      }
-
-      resolve(lines.join('\n'));
-    });
-  });
-}

package/src/utils/path-selector.ts

@@ -1,236 +0,0 @@
-import { execSync } from 'node:child_process';
-import { basename } from 'node:path';
-import type { Project, Repository } from '@src/schemas/index.ts';
-import { assertSafeCwd } from '@src/utils/paths.ts';
-
-/**
- * Result of path selection for a multi-repo project.
- */
-export interface PathSelectionResult {
-  /** Primary working path (where most work will happen) */
-  primary: string;
-  /** Additional paths to include for context */
-  additional: string[];
-}
-
-/**
- * Common keywords that map to path patterns.
- * Used for simple heuristic matching.
- */
-const PATH_KEYWORDS: Record<string, string[]> = {
-  frontend: ['frontend', 'client', 'web', 'ui', 'app'],
-  backend: ['backend', 'server', 'api', 'service'],
-  mobile: ['mobile', 'ios', 'android', 'app'],
-  shared: ['shared', 'common', 'lib', 'core', 'utils'],
-  docs: ['docs', 'documentation'],
-  infra: ['infra', 'infrastructure', 'deploy', 'k8s', 'terraform'],
-};
-
-/**
- * Extract keywords from text (title, description).
- */
-function extractKeywords(text: string): Set<string> {
-  // Normalize and split into words
-  const words = text
-    .toLowerCase()
-    .replace(/[^a-z0-9\s]/g, ' ')
-    .split(/\s+/)
-    .filter((w) => w.length > 2);
-
-  return new Set(words);
-}
-
-/**
- * Score a repository based on keyword matches.
- */
-function scoreRepo(repo: Repository, keywords: Set<string>): number {
-  const repoName = repo.name.toLowerCase();
-  const pathName = basename(repo.path).toLowerCase();
-  let score = 0;
-
-  // Check direct keyword matches in repo name or path basename
-  for (const keyword of keywords) {
-    if (repoName.includes(keyword) || pathName.includes(keyword)) {
-      score += 10;
-    }
-  }
-
-  // Check category keywords
-  for (const [category, categoryKeywords] of Object.entries(PATH_KEYWORDS)) {
-    // If text mentions a category
-    if (keywords.has(category)) {
-      for (const catKeyword of categoryKeywords) {
-        if (repoName.includes(catKeyword) || pathName.includes(catKeyword)) {
-          score += 5;
-        }
-      }
-    }
-
-    // If text mentions specific keywords from a category
-    for (const catKeyword of categoryKeywords) {
-      if (keywords.has(catKeyword) && (repoName.includes(catKeyword) || pathName.includes(catKeyword))) {
-        score += 8;
-      }
-    }
-  }
-
-  return score;
-}
-
-/**
- * Get recently modified paths from git history.
- * Returns paths that were modified in the last N commits.
- */
-function getRecentlyModifiedPaths(repos: Repository[], commits = 50): Map<string, number> {
-  const pathCounts = new Map<string, number>();
-
-  for (const repo of repos) {
-    try {
-      assertSafeCwd(repo.path);
-      // Get list of modified files from git log
-      const result = execSync(`git log -${String(commits)} --name-only --pretty=format:`, {
-        cwd: repo.path,
-        encoding: 'utf-8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-
-      // Count modifications per path
-      const currentCount = pathCounts.get(repo.path) ?? 0;
-      const files = result.split('\n').filter((f) => f.trim());
-      pathCounts.set(repo.path, currentCount + files.length);
-    } catch {
-      // Ignore git errors (path might not be a git repo)
-    }
-  }
-
-  return pathCounts;
-}
-
-/**
- * Find paths that are commonly co-modified.
- * If pathA is often changed with pathB, they might be related.
- */
-function getCoModifiedPaths(primaryPath: string, allRepos: Repository[]): string[] {
-  const coModified: string[] = [];
-
-  // This is a simplified version - just return paths that share recent commits
-  // A full implementation would analyze actual co-commit patterns
-
-  try {
-    assertSafeCwd(primaryPath);
-    // Get commit hashes for primary path
-    const primaryCommits = execSync('git log -20 --pretty=format:%H', {
-      cwd: primaryPath,
-      encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
-      .split('\n')
-      .filter((h) => h.trim());
-
-    const primarySet = new Set(primaryCommits);
-
-    // Check each other path for overlapping commits
-    for (const repo of allRepos) {
-      if (repo.path === primaryPath) continue;
-
-      try {
-        assertSafeCwd(repo.path);
-        const otherCommits = execSync('git log -20 --pretty=format:%H', {
-          cwd: repo.path,
-          encoding: 'utf-8',
-          stdio: ['pipe', 'pipe', 'pipe'],
-        })
-          .split('\n')
-          .filter((h) => h.trim());
-
-        // Count overlapping commits
-        const overlap = otherCommits.filter((h) => primarySet.has(h)).length;
-        if (overlap > 3) {
-          coModified.push(repo.path);
-        }
-      } catch {
-        // Ignore errors
-      }
-    }
-  } catch {
-    // Ignore errors
-  }
-
-  return coModified;
-}
-
-/**
- * Select relevant paths for a ticket based on context.
- *
- * @param project - Project with multiple repositories
- * @param context - Ticket context (title, description)
- * @returns Selected paths (primary + additional for context)
- */
-export function selectRelevantPaths(
-  project: Project,
-  context: { ticketTitle: string; ticketDescription?: string }
-): PathSelectionResult {
-  const repos = project.repositories;
-
-  // Single repo project - simple case
-  if (repos.length <= 1) {
-    return {
-      primary: repos[0]?.path ?? '',
-      additional: [],
-    };
-  }
-
-  // Extract keywords from ticket
-  const text = `${context.ticketTitle} ${context.ticketDescription ?? ''}`;
-  const keywords = extractKeywords(text);
-
-  // Score each repo based on keywords
-  const scores = repos.map((repo) => ({
-    repo,
-    score: scoreRepo(repo, keywords),
-  }));
-
-  // Sort by score (highest first)
-  scores.sort((a, b) => b.score - a.score);
-
-  // If we have clear winners (score > 0), use those
-  const scoredRepos = scores.filter((s) => s.score > 0);
-
-  if (scoredRepos.length > 0) {
-    const primary = scoredRepos[0]?.repo.path ?? repos[0]?.path ?? '';
-    const additional = scoredRepos.slice(1).map((s) => s.repo.path);
-    return { primary, additional };
-  }
-
-  // No keyword matches - use activity-based heuristic
-  const activityScores = getRecentlyModifiedPaths(repos);
-
-  // Sort by activity
-  const byActivity = repos
-    .map((repo) => ({
-      repo,
-      activity: activityScores.get(repo.path) ?? 0,
-    }))
-    .sort((a, b) => b.activity - a.activity);
-
-  const primary = byActivity[0]?.repo.path ?? repos[0]?.path ?? '';
-
-  // Get co-modified paths for context
-  const coModified = getCoModifiedPaths(primary, repos);
-
-  return {
-    primary,
-    additional: coModified,
-  };
-}
-
-/**
- * Select all paths (when user explicitly requests it).
- */
-export function selectAllPaths(project: Project): PathSelectionResult {
-  const [primary, ...additional] = project.repositories;
-  return {
-    primary: primary?.path ?? '',
-    additional: additional.map((r) => r.path),
-  };
-}