ralphctl 0.4.6 → 0.6.0

package/README.md

@@ -24,6 +24,21 @@ across repositories.**
 
 ---
 
+## Upgrading from 0.5.x to 0.6.0
+
+The rewrite changes the on-disk layout under `~/.ralphctl/`. Existing 0.5.x data is **not migrated automatically**.
+Before upgrading:
+
+1. Back up your existing data: `mv ~/.ralphctl ~/.ralphctl.0.5-backup`
+2. Install 0.6.0 (`pnpm install ralphctl@0.6.0` or via your package manager)
+3. Run `ralphctl project add` to register your projects in the new layout
+4. (Optional) Re-create sprints from your backup as needed
+
+ralphctl will detect a legacy layout on first launch and refuse to start until you back up + reset, with
+instructions printed.
+
+---
+
 ## Why ralphctl?
 
 AI coding agents are powerful but lose context on long tasks, need babysitting when things break, and have no way to
@@ -49,8 +64,8 @@ ralphctl handles the rest.
                                      with you      from specs    each task
 ```
 
-- **Dependency-ordered execution** — tasks run in the right sequence, one per repo at a time, with parallel execution
-  where possible
+- **Dependency-ordered execution** — tasks run strictly one at a time in topological order; the evaluator's read-only
+  `git status` check catches dirty trees so work doesn't compound on a broken state
 - **Generator-evaluator cycle** — an independent AI reviewer checks each task against its spec; if it fails, the
   generator gets feedback and iterates
 - **Context persistence** — sprint state, progress history, and task context survive across sessions; interrupted work
@@ -103,7 +118,8 @@ ralphctl sprint start
 - **Coordinate across repositories** — one sprint can span multiple repos with automatic dependency tracking
 - **Branch per sprint** — optional shared branch across every affected repo, with `sprint close --create-pr` to open
   pull requests when you're done
-- **Run tasks in parallel** — one per repo, with rate-limit backoff and automatic session resume
+- **Recover from rate limits** — automatic session resume across rate-limit pauses keeps the in-flight task's full
+  context when the provider restarts
 - **Separate the what from the how** — AI clarifies requirements first, then generates implementation tasks, with human
   approval gates
 - **Pick up where you left off** — full state persistence across sessions; interrupted work resumes automatically
@@ -174,14 +190,14 @@ export RALPHCTL_ROOT="/path/to/custom/data-dir"
 
 ### 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      |
+| 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 set-current` | Switch the current sprint        |
+| `ralphctl ticket add`         | Add a work item to a sprint      |
 
 ### AI-Assisted Planning
 
@@ -197,13 +213,10 @@ export RALPHCTL_ROOT="/path/to/custom/data-dir"
 | Command                    | Description                                            |
 | -------------------------- | ------------------------------------------------------ |
 | `ralphctl sprint start`    | Execute tasks with AI (`--branch` for a sprint branch) |
-| `ralphctl sprint health`   | Diagnose blockers and stale tasks                      |
-| `ralphctl sprint insights` | Analyze evaluator results across tasks                 |
-| `ralphctl status`          | Sprint overview with progress bar                      |
+| `ralphctl sprint progress` | Sprint progress with blocker / stale-task diagnostics  |
 | `ralphctl task list`       | List tasks in the current sprint                       |
-| `ralphctl task next`       | Show the next unblocked task                           |
 | `ralphctl sprint close`    | Close an active sprint (`--create-pr` for PRs)         |
-| `ralphctl sprint delete`   | Delete a sprint permanently                            |
+| `ralphctl sprint remove`   | Delete a sprint permanently                            |
 
 Run `ralphctl <command> --help` for details on any command.
 

package/dist/absolute-path-WUTZQ37D.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import {
+  AbsolutePath
+} from "./chunk-S3PTDH57.mjs";
+import "./chunk-WV4D2CPG.mjs";
+export {
+  AbsolutePath
+};

package/dist/chunk-6RDMCLWU.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import {
+  AbsolutePath
+} from "./chunk-S3PTDH57.mjs";
+
+// src/integration/persistence/storage-paths.ts
+import { mkdir } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+function defaultRoot() {
+  const fromEnv = process.env["RALPHCTL_ROOT"];
+  if (fromEnv !== void 0 && fromEnv.length > 0) {
+    return AbsolutePath.trustString(fromEnv);
+  }
+  return AbsolutePath.trustString(join(homedir(), ".ralphctl"));
+}
+function asAbsolute(p) {
+  return AbsolutePath.trustString(p);
+}
+function resolveStoragePaths(opts = {}) {
+  const root = opts.root ?? defaultRoot();
+  const configDir = asAbsolute(join(root, "config"));
+  const dataDir = asAbsolute(join(root, "data"));
+  const sprintsDir = asAbsolute(join(dataDir, "sprints"));
+  const cacheDir = asAbsolute(join(root, "cache"));
+  const logsDir = asAbsolute(join(root, "logs"));
+  const backupsDir = asAbsolute(join(root, "backups"));
+  const configFile = asAbsolute(join(configDir, "config.json"));
+  const projectsFile = asAbsolute(join(configDir, "projects.json"));
+  return {
+    root,
+    configDir,
+    dataDir,
+    sprintsDir,
+    cacheDir,
+    logsDir,
+    backupsDir,
+    configFile,
+    projectsFile,
+    sprintDir(id) {
+      return asAbsolute(join(sprintsDir, id));
+    },
+    sprintFile(id) {
+      return asAbsolute(join(sprintsDir, id, "sprint.json"));
+    },
+    tasksFile(id) {
+      return asAbsolute(join(sprintsDir, id, "tasks.json"));
+    },
+    progressFile(id) {
+      return asAbsolute(join(sprintsDir, id, "progress.md"));
+    },
+    requirementsAggregateFile(id) {
+      return asAbsolute(join(sprintsDir, id, "requirements.json"));
+    },
+    feedbackFile(id) {
+      return asAbsolute(join(sprintsDir, id, "feedback.md"));
+    },
+    refinementUnitDir(id, unitSlug) {
+      return asAbsolute(join(sprintsDir, id, "refinement", unitSlug));
+    },
+    ideationUnitDir(id, unitSlug) {
+      return asAbsolute(join(sprintsDir, id, "ideation", unitSlug));
+    },
+    planningDir(id) {
+      return asAbsolute(join(sprintsDir, id, "planning"));
+    },
+    executionUnitDir(id, unitSlug) {
+      return asAbsolute(join(sprintsDir, id, "execution", unitSlug));
+    },
+    doneCriteriaFile(id) {
+      return asAbsolute(join(sprintsDir, id, "done-criteria.md"));
+    }
+  };
+}
+async function ensureLayoutDirs(paths) {
+  const dirs = [
+    paths.configDir,
+    paths.sprintsDir,
+    paths.cacheDir,
+    paths.logsDir,
+    paths.backupsDir
+  ];
+  await Promise.all(dirs.map((d) => mkdir(d, { recursive: true })));
+}
+var ensuredRoots = /* @__PURE__ */ new Map();
+async function ensureLayoutDirsOnce(paths) {
+  const key = paths.root;
+  const existing = ensuredRoots.get(key);
+  if (existing !== void 0) return existing;
+  const pending = ensureLayoutDirs(paths);
+  ensuredRoots.set(key, pending);
+  try {
+    await pending;
+  } catch (err) {
+    ensuredRoots.delete(key);
+    throw err;
+  }
+}
+function resetEnsureLayoutDirsCache() {
+  ensuredRoots.clear();
+}
+
+export {
+  resolveStoragePaths,
+  ensureLayoutDirs,
+  ensureLayoutDirsOnce,
+  resetEnsureLayoutDirsCache
+};