ralphctl 0.1.0

package/src/commands/project/add.ts

@@ -0,0 +1,336 @@
+import { existsSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { input, select } from '@inquirer/prompts';
+import { error, muted } from '@src/theme/index.ts';
+import { validateProjectPath } from '@src/utils/paths.ts';
+import { createProject, ProjectExistsError } from '@src/store/project.ts';
+import type { Project, Repository } from '@src/schemas/index.ts';
+import {
+  createSpinner,
+  emoji,
+  field,
+  log,
+  showError,
+  showNextStep,
+  showSuccess,
+  showTip,
+  showWarning,
+} from '@src/theme/ui.ts';
+import { EXIT_ERROR, exitWithCode } from '@src/utils/exit-codes.ts';
+import { browseDirectory } from '@src/interactive/file-browser.ts';
+import { detectCheckScriptCandidates, suggestCheckScript } from '@src/utils/detect-scripts.ts';
+
+export interface ProjectAddOptions {
+  name?: string;
+  displayName?: string;
+  paths?: string[];
+  description?: string;
+  checkScript?: string;
+  interactive?: boolean; // Set by REPL, not a CLI flag
+}
+
+function validateSlug(slug: string): boolean {
+  return /^[a-z0-9-]+$/.test(slug);
+}
+
+/**
+ * Check if a path is a git repository.
+ */
+function isGitRepo(path: string): boolean {
+  try {
+    const gitDir = join(path, '.git');
+    return existsSync(gitDir) && statSync(gitDir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if an AI provider instructions file exists (CLAUDE.md or .github/copilot-instructions.md).
+ */
+function hasAiInstructions(repoPath: string): boolean {
+  return existsSync(join(repoPath, 'CLAUDE.md')) || existsSync(join(repoPath, '.github', 'copilot-instructions.md'));
+}
+
+/**
+ * Add check script to a repository interactively.
+ * Exported so `project repo add` can reuse the same flow.
+ */
+export async function addCheckScriptToRepository(repo: Repository): Promise<Repository> {
+  let suggested: string | null = null;
+
+  try {
+    const detection = detectCheckScriptCandidates(repo.path);
+    if (detection) {
+      log.success(`  Detected: ${detection.typeLabel}`);
+      suggested = suggestCheckScript(repo.path);
+    }
+  } catch {
+    // Auto-detection failed, continue with manual entry
+  }
+
+  const checkInput = await input({
+    message: '  Check script (optional):',
+    default: suggested ?? undefined,
+  });
+  const checkScript = checkInput.trim() || undefined;
+
+  return {
+    ...repo,
+    checkScript,
+  };
+}
+
+export async function projectAddCommand(options: ProjectAddOptions = {}): Promise<void> {
+  let name: string;
+  let displayName: string;
+  let repositories: Repository[];
+  let description: string | undefined;
+
+  if (options.interactive === false) {
+    // Non-interactive mode: validate required params
+    const errors: string[] = [];
+    const trimmedName = options.name?.trim();
+    const trimmedDisplayName = options.displayName?.trim();
+
+    if (!trimmedName) {
+      errors.push('--name is required');
+    } else if (!validateSlug(trimmedName)) {
+      errors.push('--name must be a slug (lowercase, numbers, hyphens only)');
+    }
+
+    if (!trimmedDisplayName) {
+      errors.push('--display-name is required');
+    }
+
+    if (!options.paths || options.paths.length === 0) {
+      errors.push('--path is required (at least one)');
+    }
+
+    // Validate paths
+    if (options.paths) {
+      const spinner = options.paths.length > 1 ? createSpinner('Validating repository paths...').start() : null;
+      for (const path of options.paths) {
+        const resolved = resolve(path.trim());
+        const validation = await validateProjectPath(resolved);
+        if (validation !== true) {
+          errors.push(`--path ${path}: ${validation}`);
+        }
+      }
+      spinner?.succeed('Paths validated');
+    }
+
+    if (errors.length > 0 || !trimmedName || !trimmedDisplayName || !options.paths) {
+      showError('Validation failed');
+      for (const e of errors) {
+        log.item(error(e));
+      }
+      console.log('');
+      exitWithCode(EXIT_ERROR);
+    }
+
+    name = trimmedName;
+    displayName = trimmedDisplayName;
+    // Convert paths to repositories with auto-derived names
+    // In non-interactive mode, apply CLI flags if provided (otherwise no scripts)
+    repositories = options.paths.map((p) => {
+      const resolved = resolve(p.trim());
+      const repo: Repository = { name: basename(resolved), path: resolved };
+      if (options.checkScript) repo.checkScript = options.checkScript;
+      return repo;
+    });
+    const trimmedDesc = options.description?.trim();
+    description = trimmedDesc === '' ? undefined : trimmedDesc;
+  } else {
+    // Interactive mode (default) - prompt for missing params
+    name = await input({
+      message: 'Project name (slug):',
+      default: options.name?.trim(),
+      validate: (v) => {
+        const trimmed = v.trim();
+        if (trimmed.length === 0) return 'Name is required';
+        if (!validateSlug(trimmed)) return 'Must be lowercase with hyphens only';
+        return true;
+      },
+    });
+    name = name.trim();
+
+    displayName = await input({
+      message: 'Display name:',
+      default: options.displayName?.trim() ?? name,
+      validate: (v) => (v.trim().length > 0 ? true : 'Display name is required'),
+    });
+    displayName = displayName.trim();
+
+    // Collect repositories
+    repositories = [];
+
+    // Add any paths from options first
+    if (options.paths) {
+      for (const p of options.paths) {
+        const resolved = resolve(p.trim());
+        const validation = await validateProjectPath(resolved);
+        if (validation === true) {
+          repositories.push({ name: basename(resolved), path: resolved });
+        }
+      }
+    }
+
+    // Ask for at least one path if none provided
+    if (repositories.length === 0) {
+      const pathMethod = await select({
+        message: `${emoji.donut} How to specify repository path?`,
+        choices: [
+          { name: 'Browse filesystem', value: 'browse', description: 'Navigate from home folder' },
+          { name: 'Use current directory', value: 'cwd', description: process.cwd() },
+          { name: 'Type path manually', value: 'manual' },
+        ],
+      });
+
+      let firstPath: string;
+
+      if (pathMethod === 'browse') {
+        const browsed = await browseDirectory('Select repository directory:');
+        if (!browsed) {
+          showError('No directory selected');
+          exitWithCode(EXIT_ERROR);
+        }
+        firstPath = browsed;
+      } else if (pathMethod === 'cwd') {
+        firstPath = process.cwd();
+      } else {
+        firstPath = await input({
+          message: 'Repository path:',
+          default: process.cwd(),
+          validate: async (v) => {
+            const result = await validateProjectPath(v.trim());
+            return result;
+          },
+        });
+        firstPath = firstPath.trim();
+      }
+
+      const resolved = resolve(firstPath);
+      const validation = await validateProjectPath(resolved);
+      if (validation !== true) {
+        showError(`Invalid path: ${validation}`);
+        exitWithCode(EXIT_ERROR);
+      }
+      repositories.push({ name: basename(resolved), path: resolved });
+    }
+
+    // Process first repository with scripts
+    const firstRepo = repositories[0];
+    if (firstRepo) {
+      // Check for git repo
+      if (!isGitRepo(firstRepo.path)) {
+        showWarning('Path is not a git repository');
+      }
+
+      // Check for AI instructions file
+      if (!hasAiInstructions(firstRepo.path)) {
+        showTip('Add CLAUDE.md or .github/copilot-instructions.md for better AI assistance');
+      }
+
+      // Add scripts to first repository
+      log.info(`\nConfiguring: ${firstRepo.name}`);
+      repositories[0] = await addCheckScriptToRepository(firstRepo);
+    }
+
+    // Ask for additional paths
+    let addMore = true;
+    while (addMore) {
+      const addAction = await select({
+        message: `${emoji.donut} Add another repository?`,
+        choices: [
+          { name: 'No, done adding repositories', value: 'done' },
+          { name: 'Browse filesystem', value: 'browse' },
+          { name: 'Type path manually', value: 'manual' },
+        ],
+      });
+
+      if (addAction === 'done') {
+        addMore = false;
+      } else if (addAction === 'browse') {
+        const browsed = await browseDirectory('Select repository directory:');
+        if (browsed) {
+          const resolved = resolve(browsed);
+          const validation = await validateProjectPath(resolved);
+          if (validation === true) {
+            const newRepo = { name: basename(resolved), path: resolved };
+            log.success(`Added: ${newRepo.name}`);
+            // Add scripts for this repository
+            const repoWithScripts = await addCheckScriptToRepository(newRepo);
+            repositories.push(repoWithScripts);
+          } else {
+            log.error(`Invalid path: ${validation}`);
+          }
+        }
+      } else {
+        const additionalPath = await input({
+          message: 'Repository path:',
+        });
+
+        if (additionalPath.trim() === '') {
+          addMore = false;
+        } else {
+          const resolved = resolve(additionalPath.trim());
+          const validation = await validateProjectPath(resolved);
+          if (validation === true) {
+            const newRepo = { name: basename(resolved), path: resolved };
+            log.success(`Added: ${newRepo.name}`);
+            // Add scripts for this repository
+            const repoWithScripts = await addCheckScriptToRepository(newRepo);
+            repositories.push(repoWithScripts);
+          } else {
+            log.error(`Invalid path: ${validation}`);
+          }
+        }
+      }
+    }
+
+    description = await input({
+      message: 'Description (optional):',
+      default: options.description?.trim(),
+    });
+    const trimmedDescInteractive = description.trim();
+    description = trimmedDescInteractive === '' ? undefined : trimmedDescInteractive;
+  }
+
+  try {
+    const project: Project = {
+      name,
+      displayName,
+      repositories,
+      description,
+    };
+
+    const created = await createProject(project);
+
+    showSuccess('Project added!', [
+      ['Name', created.name],
+      ['Display Name', created.displayName],
+    ]);
+    if (created.description) {
+      console.log(field('Description', created.description));
+    }
+    console.log(field('Repositories', ''));
+    for (const repo of created.repositories) {
+      log.item(`${repo.name} → ${repo.path}`);
+      if (repo.checkScript) {
+        console.log(`        Check: ${repo.checkScript}`);
+      } else {
+        console.log(`        Check: ${muted('(not configured)')}`);
+      }
+    }
+    console.log('');
+  } catch (err) {
+    if (err instanceof ProjectExistsError) {
+      showError(`Project "${name}" already exists.`);
+      showNextStep(`ralphctl project remove ${name}`, 'remove existing project first');
+      log.newline();
+    } else {
+      throw err;
+    }
+  }
+}

package/src/commands/project/index.ts

@@ -0,0 +1,104 @@
+import type { Command } from 'commander';
+import { projectAddCommand } from '@src/commands/project/add.ts';
+import { projectListCommand } from '@src/commands/project/list.ts';
+import { projectRepoAddCommand, projectRepoRemoveCommand } from '@src/commands/project/repo.ts';
+import { projectShowCommand } from '@src/commands/project/show.ts';
+import { projectRemoveCommand } from '@src/commands/project/remove.ts';
+
+export function registerProjectCommands(program: Command): void {
+  const project = program.command('project').description('Manage projects');
+
+  project.addHelpText(
+    'after',
+    `
+Examples:
+  $ ralphctl project add --name api --display-name "API Server" --path ~/code/api
+  $ ralphctl project list
+  $ ralphctl project show api
+  $ ralphctl project repo add api ~/code/api-v2
+`
+  );
+
+  project
+    .command('add')
+    .description('Add/update project')
+    .option('--name <name>', 'Slug (lowercase, numbers, hyphens)')
+    .option('--display-name <name>', 'Human-readable name')
+    .option('--path <path...>', 'Repository path (repeatable)')
+    .option('--description <desc>', 'Optional description')
+    .option('--check-script <cmd>', 'Check command (install + verify)')
+    .option('-n, --no-interactive', 'Non-interactive mode (error on missing params)')
+    .action(
+      async (opts: {
+        name?: string;
+        displayName?: string;
+        path?: string[];
+        description?: string;
+        checkScript?: string;
+        interactive?: boolean;
+      }) => {
+        await projectAddCommand({
+          name: opts.name,
+          displayName: opts.displayName,
+          paths: opts.path,
+          description: opts.description,
+          checkScript: opts.checkScript,
+          // --no-interactive sets interactive=false, otherwise true (prompt for missing)
+          interactive: opts.interactive !== false,
+        });
+      }
+    );
+
+  project.command('list').description('List all projects').action(projectListCommand);
+
+  project
+    .command('show [name]')
+    .description('Show project details')
+    .action(async (name?: string) => {
+      await projectShowCommand(name ? [name] : []);
+    });
+
+  project
+    .command('remove [name]')
+    .description('Remove a project')
+    .option('-y, --yes', 'Skip confirmation')
+    .action(async (name?: string, opts?: { yes?: boolean }) => {
+      const args: string[] = [];
+      if (name) args.push(name);
+      if (opts?.yes) args.push('-y');
+      await projectRemoveCommand(args);
+    });
+
+  const repo = project.command('repo').description('Manage project repositories');
+
+  repo.addHelpText(
+    'after',
+    `
+Examples:
+  $ ralphctl project repo add my-app ~/code/new-service
+  $ ralphctl project repo remove my-app ~/code/old-service
+`
+  );
+
+  repo
+    .command('add [name] [path]')
+    .description('Add repository to project')
+    .action(async (name?: string, pathArg?: string) => {
+      const args: string[] = [];
+      if (name) args.push(name);
+      if (pathArg) args.push(pathArg);
+      await projectRepoAddCommand(args);
+    });
+
+  repo
+    .command('remove [name] [path]')
+    .description('Remove repository from project')
+    .option('-y, --yes', 'Skip confirmation')
+    .action(async (name?: string, pathArg?: string, opts?: { yes?: boolean }) => {
+      const args: string[] = [];
+      if (name) args.push(name);
+      if (pathArg) args.push(pathArg);
+      if (opts?.yes) args.push('-y');
+      await projectRepoRemoveCommand(args);
+    });
+}

package/src/commands/project/list.ts

@@ -0,0 +1,31 @@
+import { colors, muted } from '@src/theme/index.ts';
+import { listProjects } from '@src/store/project.ts';
+import { icons, log, printHeader, showEmpty } from '@src/theme/ui.ts';
+
+export async function projectListCommand(): Promise<void> {
+  const projects = await listProjects();
+
+  if (projects.length === 0) {
+    showEmpty('projects', 'Add one with: ralphctl project add');
+    return;
+  }
+
+  printHeader('Projects', icons.project);
+
+  for (const project of projects) {
+    const repoCount = muted(
+      `(${String(project.repositories.length)} repo${project.repositories.length !== 1 ? 's' : ''})`
+    );
+    log.raw(`${colors.highlight(project.name)}  ${project.displayName}  ${repoCount}`);
+    for (const repo of project.repositories) {
+      log.item(`${repo.name} ${muted('→')} ${muted(repo.path)}`);
+    }
+    if (project.description) {
+      log.dim(`    ${project.description}`);
+    }
+    log.newline();
+  }
+
+  log.dim(`Showing ${String(projects.length)} project(s)`);
+  log.newline();
+}

package/src/commands/project/remove.ts

@@ -0,0 +1,43 @@
+import { confirm } from '@inquirer/prompts';
+import { muted } from '@src/theme/index.ts';
+import { getProject, ProjectNotFoundError, removeProject } from '@src/store/project.ts';
+import { selectProject } from '@src/interactive/selectors.ts';
+import { showError, showSuccess } from '@src/theme/ui.ts';
+
+export async function projectRemoveCommand(args: string[]): Promise<void> {
+  const skipConfirm = args.includes('-y') || args.includes('--yes');
+  let projectName = args.find((a) => !a.startsWith('-'));
+
+  if (!projectName) {
+    const selected = await selectProject('Select project to remove:');
+    if (!selected) return;
+    projectName = selected;
+  }
+
+  try {
+    const project = await getProject(projectName);
+
+    if (!skipConfirm) {
+      const confirmed = await confirm({
+        message: `Remove project "${project.displayName}" (${project.name})?`,
+        default: false,
+      });
+
+      if (!confirmed) {
+        console.log(muted('\nProject removal cancelled.\n'));
+        return;
+      }
+    }
+
+    await removeProject(projectName);
+    showSuccess('Project removed', [['Name', projectName]]);
+    console.log('');
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      showError(`Project not found: ${projectName}`);
+      console.log('');
+    } else {
+      throw err;
+    }
+  }
+}

package/src/commands/project/repo.ts

@@ -0,0 +1,118 @@
+import { basename, resolve } from 'node:path';
+import { confirm, input, select } from '@inquirer/prompts';
+import { muted } from '@src/theme/index.ts';
+import { addProjectRepo, getProject, ProjectNotFoundError, removeProjectRepo } from '@src/store/project.ts';
+import { selectProject } from '@src/interactive/selectors.ts';
+import { emoji, log, showError, showSuccess } from '@src/theme/ui.ts';
+import { addCheckScriptToRepository } from '@src/commands/project/add.ts';
+
+export async function projectRepoAddCommand(args: string[]): Promise<void> {
+  let projectName = args[0];
+  let path = args[1];
+
+  // Interactive: select project if not provided
+  if (!projectName) {
+    const selected = await selectProject('Select project to add repository to:');
+    if (!selected) return;
+    projectName = selected;
+  }
+
+  // Interactive: ask for path if not provided
+  path ??= await input({
+    message: `${emoji.donut} Repository path to add:`,
+    validate: (v) => (v.trim().length > 0 ? true : 'Path is required'),
+  });
+
+  try {
+    const resolvedPath = resolve(path);
+    const bareRepo = { name: basename(resolvedPath), path: resolvedPath };
+
+    // Prompt for setup/verify scripts (with heuristic suggestions)
+    log.info(`\nConfiguring: ${bareRepo.name}`);
+    const repoWithScripts = await addCheckScriptToRepository(bareRepo);
+
+    const project = await addProjectRepo(projectName, repoWithScripts);
+    showSuccess('Repository added', [['Project', projectName]]);
+    log.newline();
+    log.info('Current repositories:');
+    for (const repo of project.repositories) {
+      log.item(`${repo.name} → ${repo.path}`);
+    }
+    log.newline();
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      showError(`Project not found: ${projectName}`);
+      log.newline();
+    } else if (err instanceof Error) {
+      showError(err.message);
+      log.newline();
+    } else {
+      throw err;
+    }
+  }
+}
+
+export async function projectRepoRemoveCommand(args: string[]): Promise<void> {
+  const skipConfirm = args.includes('-y') || args.includes('--yes');
+  const filteredArgs = args.filter((a) => !a.startsWith('-'));
+  let projectName = filteredArgs[0];
+  let path = filteredArgs[1];
+
+  // Interactive: select project if not provided
+  if (!projectName) {
+    const selected = await selectProject('Select project to remove repository from:');
+    if (!selected) return;
+    projectName = selected;
+  }
+
+  try {
+    const project = await getProject(projectName);
+
+    // Interactive: select repository if not provided
+    if (!path) {
+      if (project.repositories.length === 0) {
+        console.log(muted('\nNo repositories to remove.\n'));
+        return;
+      }
+
+      path = await select({
+        message: `${emoji.donut} Select repository to remove:`,
+        choices: project.repositories.map((r) => ({
+          name: `${r.name} (${r.path})`,
+          value: r.path,
+        })),
+      });
+    }
+
+    if (!skipConfirm) {
+      const confirmed = await confirm({
+        message: `Remove repository "${path}" from project "${project.displayName}"?`,
+        default: false,
+      });
+
+      if (!confirmed) {
+        console.log(muted('\nRepository removal cancelled.\n'));
+        return;
+      }
+    }
+
+    const updatedProject = await removeProjectRepo(projectName, path);
+    showSuccess('Repository removed', [['Project', projectName]]);
+    log.newline();
+    log.info('Remaining repositories:');
+    for (const repo of updatedProject.repositories) {
+      log.item(`${repo.name} → ${repo.path}`);
+    }
+    log.newline();
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      showError(`Project not found: ${projectName}`);
+      log.newline();
+    } else if (err instanceof Error) {
+      showError(err.message);
+      log.newline();
+    } else {
+      throw err;
+    }
+  }
+}

package/src/commands/project/show.ts

@@ -0,0 +1,49 @@
+import { colors, muted } from '@src/theme/index.ts';
+import { getProject, ProjectNotFoundError } from '@src/store/project.ts';
+import { selectProject } from '@src/interactive/selectors.ts';
+import { icons, labelValue, log, renderCard, showError } from '@src/theme/ui.ts';
+
+export async function projectShowCommand(args: string[]): Promise<void> {
+  let projectName = args[0];
+
+  if (!projectName) {
+    const selected = await selectProject('Select project to show:');
+    if (!selected) return;
+    projectName = selected;
+  }
+
+  try {
+    const project = await getProject(projectName);
+
+    // Project info card
+    const infoLines: string[] = [labelValue('Name', project.name), labelValue('Display Name', project.displayName)];
+    if (project.description) {
+      infoLines.push(labelValue('Description', project.description));
+    }
+    infoLines.push(labelValue('Repositories', String(project.repositories.length)));
+
+    log.newline();
+    console.log(renderCard(`${icons.project} ${project.displayName}`, infoLines));
+
+    // Repository cards
+    for (const repo of project.repositories) {
+      log.newline();
+      const repoLines: string[] = [labelValue('Path', repo.path)];
+      if (repo.checkScript) {
+        repoLines.push(labelValue('Check', colors.info(repo.checkScript)));
+      } else {
+        repoLines.push(muted('No check script configured'));
+      }
+      console.log(renderCard(`  ${repo.name}`, repoLines));
+    }
+
+    log.newline();
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      showError(`Project not found: ${projectName}`);
+      log.newline();
+    } else {
+      throw err;
+    }
+  }
+}