ralphctl 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,15 @@
 [![npm version](https://img.shields.io/npm/v/ralphctl?style=flat&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/ralphctl)
+[![npm downloads](https://img.shields.io/npm/dm/ralphctl?style=flat&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/ralphctl)
 [![CI](https://github.com/lukas-grigis/ralphctl/actions/workflows/ci.yml/badge.svg)](https://github.com/lukas-grigis/ralphctl/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat&logo=opensourceinitiative&logoColor=white)](./LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/node-%E2%89%A5_24-5fa04e?style=flat&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4?style=flat&logo=prettier&logoColor=white)](https://prettier.io/)
+[![ESLint](https://img.shields.io/badge/ESLint-4b32c3?style=flat&logo=eslint&logoColor=white)](https://eslint.org/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat&logo=git&logoColor=white)](./CONTRIBUTING.md)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-191919?style=flat&logo=anthropic&logoColor=white)](https://docs.anthropic.com/en/docs/claude-code)
+[![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-000?style=flat&logo=githubcopilot&logoColor=white)](https://docs.github.com/en/copilot/github-copilot-in-the-cli)
+[![Built with Donuts](https://img.shields.io/badge/%F0%9F%8D%A9-Built_with_Donuts-ff6f00?style=flat)](https://github.com/lukas-grigis/ralphctl)
 
 ```
   🍩 ██████╗  █████╗ ██╗     ██████╗ ██╗  ██╗ ██████╗████████╗██╗     🍩
@@ -87,30 +93,47 @@ Or just run `ralphctl` with no arguments for an interactive menu that walks you
 
 ## CLI Overview
 
+### Getting Started
+
+| Command                                          | Description                         |
+| ------------------------------------------------ | ----------------------------------- |
+| `ralphctl`                                       | Interactive menu mode (recommended) |
+| `ralphctl doctor`                                | Check environment health            |
+| `ralphctl config set provider <claude\|copilot>` | Set AI provider                     |
+| `ralphctl config show`                           | Show current configuration          |
+| `ralphctl completion install`                    | Enable shell tab-completion         |
+
+### Project & Sprint Setup
+
+| Command                  | Description                      |
+| ------------------------ | -------------------------------- |
+| `ralphctl project add`   | Register a project and its repos |
+| `ralphctl sprint create` | Create a new sprint (draft)      |
+| `ralphctl sprint list`   | List all sprints                 |
+| `ralphctl sprint show`   | Show current sprint details      |
+| `ralphctl sprint switch` | Quick sprint switcher            |
+| `ralphctl ticket add`    | Add a work item to a sprint      |
+
+### AI-Assisted Planning
+
 | Command                        | Description                             |
 | ------------------------------ | --------------------------------------- |
-| `ralphctl`                     | Interactive menu mode                   |
-| `ralphctl doctor`              | Check environment health and setup      |
-| `ralphctl config show`         | Show current configuration              |
-| `ralphctl config set`          | Set configuration values                |
-| `ralphctl project add`         | Register a project and its repos        |
-| `ralphctl sprint create`       | Create a new sprint                     |
-| `ralphctl sprint list`         | List all sprints                        |
-| `ralphctl sprint show`         | Show current sprint details             |
-| `ralphctl sprint switch`       | Quick sprint switcher                   |
-| `ralphctl ticket add`          | Add a work item to a sprint             |
-| `ralphctl sprint refine`       | Refine requirements with AI             |
-| `ralphctl sprint plan`         | Generate tasks from requirements        |
+| `ralphctl sprint refine`       | Clarify requirements with AI (WHAT)     |
+| `ralphctl sprint plan`         | Generate tasks from requirements (HOW)  |
 | `ralphctl sprint ideate`       | Quick single-session refine + plan      |
 | `ralphctl sprint requirements` | Export refined requirements to markdown |
-| `ralphctl sprint start`        | Execute tasks with AI                   |
-| `ralphctl sprint health`       | Diagnose blockers and stale tasks       |
-| `ralphctl sprint close`        | Close an active sprint                  |
-| `ralphctl sprint delete`       | Delete a sprint permanently             |
-| `ralphctl task list`           | List tasks in the current sprint        |
-| `ralphctl task next`           | Show the next unblocked task            |
-| `ralphctl dashboard`           | Sprint overview with progress bar       |
-| `ralphctl completion install`  | Enable shell tab-completion             |
+
+### Execution & Monitoring
+
+| Command                  | Description                       |
+| ------------------------ | --------------------------------- |
+| `ralphctl sprint start`  | Execute tasks with AI             |
+| `ralphctl sprint health` | Diagnose blockers and stale tasks |
+| `ralphctl dashboard`     | Sprint overview with progress bar |
+| `ralphctl task list`     | List tasks in the current sprint  |
+| `ralphctl task next`     | Show the next unblocked task      |
+| `ralphctl sprint close`  | Close an active sprint            |
+| `ralphctl sprint delete` | Delete a sprint permanently       |
 
 Run `ralphctl <command> --help` for details on any command.
 
@@ -127,6 +150,18 @@ ralphctl config set provider copilot     # Use GitHub Copilot
 
 Auto-prompts on first AI command if not set. Both CLIs must be in your PATH and authenticated.
 
+### Provider Differences
+
+| Feature                     | Claude Code                          | GitHub Copilot                                                       |
+| --------------------------- | ------------------------------------ | -------------------------------------------------------------------- |
+| Status                      | GA                                   | Public preview                                                       |
+| Headless execution          | `-p --output-format json`            | `-p -s --autopilot --no-ask-user`                                    |
+| Session IDs                 | In JSON output (`session_id`)        | Captured via `--share` output file                                   |
+| Session resume (`--resume`) | Full support                         | Supported when session ID is available                               |
+| Per-tool permissions        | Settings files + `--permission-mode` | `--allow-all-tools` (all-or-nothing by default)                      |
+| Fine-grained tool control   | `allow`/`deny` in settings files     | `--allow-tool`, `--deny-tool` flags (not yet used)                   |
+| Rate limit detection        | Validated patterns                   | Borrowed from Claude — not yet validated against real Copilot errors |
+
 ---
 
 ## Documentation
@@ -158,14 +193,13 @@ export RALPHCTL_ROOT="/path/to/custom/data-dir"
 git clone https://github.com/lukas-grigis/ralphctl.git
 cd ralphctl
 pnpm install
-pnpm dev --help          # Run CLI in dev mode
-pnpm build               # Type check
+pnpm dev --help          # Run CLI in dev mode (tsx, no build needed)
+pnpm build               # Compile for npm distribution (tsup)
+pnpm typecheck           # Type check
 pnpm test                # Run tests
 pnpm lint                # Lint
 ```
 
-No compilation step — the CLI runs TypeScript source directly via [tsx](https://tsx.is/).
-
 ---
 
 ## Contributing

package/dist/add-HGJCLWED.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import {
+  addSingleTicketInteractive,
+  ticketAddCommand
+} from "./chunk-MNMQC36F.mjs";
+import "./chunk-7TG3EAQ2.mjs";
+import "./chunk-WGHJI3OI.mjs";
+import "./chunk-EKMZZRWI.mjs";
+import "./chunk-6PYTKGB5.mjs";
+import "./chunk-QBXHAXHI.mjs";
+export {
+  addSingleTicketInteractive,
+  ticketAddCommand
+};

package/dist/add-MRGCS3US.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import {
+  addCheckScriptToRepository,
+  projectAddCommand
+} from "./chunk-MRKOFVTM.mjs";
+import "./chunk-NTWO2LXB.mjs";
+import "./chunk-7TG3EAQ2.mjs";
+import "./chunk-WGHJI3OI.mjs";
+import "./chunk-6PYTKGB5.mjs";
+import "./chunk-QBXHAXHI.mjs";
+export {
+  addCheckScriptToRepository,
+  projectAddCommand
+};

package/dist/chunk-6PYTKGB5.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+
+// src/utils/paths.ts
+import { fileURLToPath } from "url";
+import { dirname, isAbsolute, join, resolve, sep } from "path";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { lstat, realpath, stat } from "fs/promises";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+function getRepoRoot() {
+  let dir = __dirname;
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = dirname(dir);
+  }
+  return join(__dirname, "..", "..");
+}
+function getDataDir() {
+  return process.env["RALPHCTL_ROOT"] ?? join(homedir(), ".ralphctl");
+}
+function getConfigPath() {
+  return join(getDataDir(), "config.json");
+}
+function getProjectsFilePath() {
+  return join(getDataDir(), "projects.json");
+}
+function getSprintsDir() {
+  return join(getDataDir(), "sprints");
+}
+function getSprintDir(sprintId) {
+  const sprintsDir = getSprintsDir();
+  const resolved = resolve(sprintsDir, sprintId);
+  if (!resolved.startsWith(sprintsDir + sep) && resolved !== sprintsDir) {
+    throw new Error(`Path traversal detected in sprint ID: ${sprintId}`);
+  }
+  return resolved;
+}
+function getSprintFilePath(sprintId) {
+  return join(getSprintDir(sprintId), "sprint.json");
+}
+function getTasksFilePath(sprintId) {
+  return join(getSprintDir(sprintId), "tasks.json");
+}
+function getProgressFilePath(sprintId) {
+  return join(getSprintDir(sprintId), "progress.md");
+}
+function getRefinementDir(sprintId, ticketId) {
+  return join(getSprintDir(sprintId), "refinement", ticketId);
+}
+function getPlanningDir(sprintId) {
+  return join(getSprintDir(sprintId), "planning");
+}
+function getIdeateDir(sprintId, ticketId) {
+  return join(getSprintDir(sprintId), "ideation", ticketId);
+}
+function getSchemaPath(schemaName) {
+  return join(getRepoRoot(), "schemas", schemaName);
+}
+function assertSafeCwd(path) {
+  if (!path || path.includes("\0") || path.includes("\n") || path.includes("\r")) {
+    throw new Error("Unsafe path for cwd: contains null bytes or newlines");
+  }
+  if (!isAbsolute(path)) {
+    throw new Error(`Unsafe path for cwd: must be absolute, got: ${path}`);
+  }
+}
+function expandTilde(path) {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return homedir() + path.slice(1);
+  return path;
+}
+async function validateProjectPath(path) {
+  try {
+    const resolved = resolve(expandTilde(path));
+    const lstats = await lstat(resolved);
+    if (lstats.isSymbolicLink()) {
+      const realPath = await realpath(resolved);
+      const realStats = await stat(realPath);
+      if (!realStats.isDirectory()) {
+        return "Symlink target is not a directory";
+      }
+      return true;
+    }
+    if (!lstats.isDirectory()) {
+      return "Path is not a directory";
+    }
+    return true;
+  } catch {
+    return "Directory does not exist";
+  }
+}
+
+// src/utils/storage.ts
+import { access, appendFile, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
+import { dirname as dirname2 } from "path";
+var ValidationError = class extends Error {
+  path;
+  constructor(message, path, cause) {
+    super(message, { cause });
+    this.name = "ValidationError";
+    this.path = path;
+  }
+};
+var FileNotFoundError = class extends Error {
+  path;
+  constructor(message, path) {
+    super(message);
+    this.name = "FileNotFoundError";
+    this.path = path;
+  }
+};
+async function ensureDir(dirPath) {
+  await mkdir(dirPath, { recursive: true });
+}
+async function removeDir(dirPath) {
+  await rm(dirPath, { recursive: true, force: true });
+}
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function listDirs(dirPath) {
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+async function readValidatedJson(filePath, schema) {
+  let content;
+  try {
+    content = await readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      throw new FileNotFoundError(`File not found: ${filePath}`, filePath);
+    }
+    throw err;
+  }
+  let data;
+  try {
+    data = JSON.parse(content);
+  } catch (err) {
+    throw new ValidationError(`Invalid JSON in ${filePath}`, filePath, err);
+  }
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+    throw new ValidationError(`Validation failed for ${filePath}:
+${issues}`, filePath, result.error);
+  }
+  return result.data;
+}
+async function writeValidatedJson(filePath, data, schema) {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+    throw new ValidationError(`Validation failed before writing to ${filePath}:
+${issues}`, filePath, result.error);
+  }
+  await ensureDir(dirname2(filePath));
+  await writeFile(filePath, JSON.stringify(result.data, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
+}
+async function appendToFile(filePath, content) {
+  await ensureDir(dirname2(filePath));
+  await appendFile(filePath, content, { encoding: "utf-8", mode: 384 });
+}
+async function readTextFile(filePath) {
+  try {
+    return await readFile(filePath, "utf-8");
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      throw new FileNotFoundError(`File not found: ${filePath}`, filePath);
+    }
+    throw err;
+  }
+}
+
+// src/schemas/index.ts
+import { z } from "zod";
+var SprintStatusSchema = z.enum(["draft", "active", "closed"]);
+var TaskStatusSchema = z.enum(["todo", "in_progress", "done"]);
+var RequirementStatusSchema = z.enum(["pending", "approved"]);
+var RepositorySchema = z.object({
+  name: z.string().min(1),
+  // Auto-derived from basename(path)
+  path: z.string().min(1),
+  // Absolute path
+  checkScript: z.string().optional()
+  // e.g., "pnpm install && pnpm typecheck && pnpm lint && pnpm test"
+});
+var ProjectSchema = z.object({
+  name: z.string().min(1).regex(/^[a-z0-9-]+$/, "Project name must be a slug (lowercase, numbers, hyphens only)"),
+  displayName: z.string().min(1),
+  repositories: z.array(RepositorySchema).min(1),
+  description: z.string().optional()
+});
+var ProjectsSchema = z.array(ProjectSchema);
+var TicketSchema = z.object({
+  id: z.string().min(1),
+  // Internal UUID8 (auto-generated)
+  title: z.string().min(1),
+  description: z.string().optional(),
+  link: z.url().optional(),
+  projectName: z.string().min(1),
+  // References Project.name
+  affectedRepositories: z.array(z.string()).optional(),
+  // Repository paths selected during planning
+  requirementStatus: RequirementStatusSchema.default("pending"),
+  requirements: z.string().optional()
+  // Refined requirements (set during sprint refine)
+});
+var TaskSchema = z.object({
+  id: z.string().min(1),
+  // UUID8
+  name: z.string().min(1),
+  description: z.string().optional(),
+  steps: z.array(z.string()).default([]),
+  status: TaskStatusSchema.default("todo"),
+  order: z.number().int().positive(),
+  ticketId: z.string().optional(),
+  // References Ticket.id (internal)
+  blockedBy: z.array(z.string()).default([]),
+  projectPath: z.string().min(1),
+  // Single path for execution
+  verified: z.boolean().default(false),
+  // Whether verification passed
+  verificationOutput: z.string().optional()
+  // Output from verification run
+});
+var TasksSchema = z.array(TaskSchema);
+var ImportTaskSchema = z.object({
+  id: z.string().optional(),
+  // Local ID for referencing in blockedBy
+  name: z.string().min(1),
+  // Required
+  description: z.string().optional(),
+  steps: z.array(z.string()).optional(),
+  ticketId: z.string().optional(),
+  blockedBy: z.array(z.string()).optional(),
+  projectPath: z.string().min(1)
+  // Required - execution directory
+});
+var ImportTasksSchema = z.array(ImportTaskSchema);
+var RefinedRequirementSchema = z.object({
+  ref: z.string().min(1),
+  requirements: z.string().min(1)
+});
+var RefinedRequirementsSchema = z.array(RefinedRequirementSchema);
+var IdeateOutputSchema = z.object({
+  requirements: z.string().min(1),
+  tasks: ImportTasksSchema
+});
+var SprintSchema = z.object({
+  id: z.string().regex(/^\d{8}-\d{6}-[a-z0-9-]+$/, "Invalid sprint ID format"),
+  name: z.string().min(1),
+  status: SprintStatusSchema.default("draft"),
+  createdAt: z.iso.datetime(),
+  activatedAt: z.iso.datetime().nullable().default(null),
+  closedAt: z.iso.datetime().nullable().default(null),
+  tickets: z.array(TicketSchema).default([]),
+  checkRanAt: z.record(z.string(), z.iso.datetime()).default({}),
+  branch: z.string().nullable().default(null)
+});
+var AiProviderSchema = z.enum(["claude", "copilot"]);
+var ConfigSchema = z.object({
+  currentSprint: z.string().nullable().default(null),
+  aiProvider: AiProviderSchema.nullable().default(null),
+  editor: z.string().nullable().default(null)
+});
+
+export {
+  getDataDir,
+  getConfigPath,
+  getProjectsFilePath,
+  getSprintsDir,
+  getSprintDir,
+  getSprintFilePath,
+  getTasksFilePath,
+  getProgressFilePath,
+  getRefinementDir,
+  getPlanningDir,
+  getIdeateDir,
+  getSchemaPath,
+  assertSafeCwd,
+  expandTilde,
+  validateProjectPath,
+  ValidationError,
+  FileNotFoundError,
+  ensureDir,
+  removeDir,
+  fileExists,
+  listDirs,
+  readValidatedJson,
+  writeValidatedJson,
+  appendToFile,
+  readTextFile,
+  SprintStatusSchema,
+  TaskStatusSchema,
+  RequirementStatusSchema,
+  ProjectsSchema,
+  TasksSchema,
+  ImportTasksSchema,
+  RefinedRequirementsSchema,
+  IdeateOutputSchema,
+  SprintSchema,
+  AiProviderSchema,
+  ConfigSchema
+};

package/dist/chunk-7TG3EAQ2.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// src/utils/exit-codes.ts
+var EXIT_SUCCESS = 0;
+var EXIT_ERROR = 1;
+var EXIT_NO_TASKS = 2;
+var EXIT_ALL_BLOCKED = 3;
+var EXIT_INTERRUPTED = 130;
+function exitWithCode(code) {
+  process.exit(code);
+}
+
+export {
+  EXIT_SUCCESS,
+  EXIT_ERROR,
+  EXIT_NO_TASKS,
+  EXIT_ALL_BLOCKED,
+  EXIT_INTERRUPTED,
+  exitWithCode
+};