@caseyharalson/orrery 0.11.0 → 0.13.0

package/lib/utils/git.js

@@ -22,7 +22,9 @@ function git(command, cwd) {
   } catch (error) {
     // Return stderr if available, otherwise throw
     if (error.stderr) {
-      throw new Error(`git ${command} failed: ${error.stderr.trim()}`);
+      throw new Error(`git ${command} failed: ${error.stderr.trim()}`, {
+        cause: error
+      });
     }
     throw error;
   }
@@ -34,7 +36,12 @@ function git(command, cwd) {
  * @returns {string} - Current branch name
  */
 function getCurrentBranch(cwd) {
-  return git("rev-parse --abbrev-ref HEAD", cwd);
+  try {
+    return git("rev-parse --abbrev-ref HEAD", cwd);
+  } catch {
+    // Unborn branch (no commits yet) — symbolic-ref still works
+    return git("symbolic-ref --short HEAD", cwd);
+  }
 }
 
 /**
@@ -232,6 +239,22 @@ function getUncommittedDiff(cwd, files) {
   }
 }
 
+/**
+ * Derive a plan ID from a plan filename (for lock/worktree naming).
+ * @param {string} planFileName - Plan filename (e.g., "2026-01-11-add-dummy-script.yaml")
+ * @returns {string} - Plan ID (e.g., "add-dummy-script")
+ */
+function derivePlanId(planFileName) {
+  let name = planFileName.replace(/\.ya?ml$/, "");
+  name = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+  name = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return name;
+}
+
 /**
  * Derive a branch name from a plan filename
  * @param {string} planFileName - Plan filename (e.g., "2026-01-11-add-dummy-script.yaml")
@@ -334,6 +357,30 @@ function listWorktrees(cwd) {
   return worktrees;
 }
 
+/**
+ * Get the main (first) worktree root path.
+ * Useful for finding the true repo root from inside a linked worktree.
+ * @param {string} cwd - Working directory (can be inside any worktree)
+ * @returns {string} - Absolute path to the main worktree
+ */
+function getMainRepoRoot(cwd) {
+  const worktrees = listWorktrees(cwd);
+  if (worktrees.length === 0) {
+    throw new Error("No worktrees found");
+  }
+  return worktrees[0].worktree;
+}
+
+/**
+ * Add a worktree for an existing branch (without creating a new branch).
+ * @param {string} worktreePath - Path where the worktree will be created
+ * @param {string} branchName - Existing branch to check out in the worktree
+ * @param {string} cwd - Working directory of the main repository
+ */
+function addWorktreeExistingBranch(worktreePath, branchName, cwd) {
+  git(`worktree add "${worktreePath}" ${branchName}`, cwd);
+}
+
 /**
  * Get commits between two refs
  * @param {string} fromRef - Starting reference (exclusive)
@@ -396,11 +443,14 @@ module.exports = {
   hasUncommittedChanges,
   getUncommittedDiff,
   deriveBranchName,
+  derivePlanId,
   stash,
   stashPop,
   addWorktree,
+  addWorktreeExistingBranch,
   removeWorktree,
   listWorktrees,
+  getMainRepoRoot,
   getCommitRange,
   cherryPick,
   cherryPickAbort,

package/lib/utils/lock.js

@@ -0,0 +1,235 @@
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const { getWorkDir } = require("./paths");
+
+const LOCK_FILE = "exec.lock";
+
+/**
+ * Get the lock file path.
+ * @param {string} [planId] - Optional plan ID for per-plan locks
+ * @returns {string} - Path to the lock file
+ */
+function getLockPath(planId) {
+  const fileName = planId ? `exec-${planId}.lock` : LOCK_FILE;
+  return path.join(getWorkDir(), fileName);
+}
+
+/**
+ * Check if a process with the given PID is running.
+ * @param {number} pid - Process ID
+ * @returns {boolean}
+ */
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a PID belongs to an orrery process.
+ * @param {number} pid - Process ID
+ * @returns {boolean}
+ */
+function isOrreryProcess(pid) {
+  try {
+    // Linux: read /proc/<pid>/cmdline (null-separated args)
+    const cmdlinePath = `/proc/${pid}/cmdline`;
+    if (fs.existsSync(cmdlinePath)) {
+      const raw = fs.readFileSync(cmdlinePath, "utf8");
+      const args = raw.split("\0").filter(Boolean);
+      // Check if any argument ends with the orrery binary (bin/orrery.js or bin/orrery)
+      return args.some(
+        (arg) => arg.endsWith("bin/orrery.js") || arg.endsWith("bin/orrery")
+      );
+    }
+
+    // macOS/other: use ps
+    const args = execSync(`ps -p ${pid} -o args=`, {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    return args.includes("bin/orrery.js") || args.includes("bin/orrery ");
+  } catch {
+    // Cannot determine — treat as stale (safe default)
+    return false;
+  }
+}
+
+/**
+ * Read and parse the lock file.
+ * @param {string} [planId] - Optional plan ID for per-plan locks
+ * @returns {{pid: number, startedAt: string, command: string, planId?: string, worktreePath?: string}|null}
+ */
+function readLock(planId) {
+  const lockPath = getLockPath(planId);
+  try {
+    const content = fs.readFileSync(lockPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Attempt to acquire the execution lock.
+ * @param {string} [planId] - Optional plan ID for per-plan locks
+ * @param {{worktreePath?: string}} [extras] - Extra fields to store in the lock
+ * @returns {{acquired: boolean, reason?: string, pid?: number}}
+ */
+function acquireLock(planId, extras) {
+  const lockPath = getLockPath(planId);
+  const lockData = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    command: process.argv.slice(2).join(" ")
+  };
+  if (planId) lockData.planId = planId;
+  if (extras && extras.worktreePath) {
+    lockData.worktreePath = extras.worktreePath;
+  }
+
+  // Check for existing lock
+  const existing = readLock(planId);
+  if (existing) {
+    const running = isProcessRunning(existing.pid);
+    if (running && isOrreryProcess(existing.pid)) {
+      return {
+        acquired: false,
+        reason: `Another orrery process is running (PID ${existing.pid}, started ${existing.startedAt})`,
+        pid: existing.pid
+      };
+    }
+
+    // Stale lock — remove it
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+
+  // Atomic create
+  try {
+    fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + "\n", {
+      flag: "wx"
+    });
+    return { acquired: true };
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      // Race condition — another process acquired between check and write
+      const raceWinner = readLock(planId);
+      return {
+        acquired: false,
+        reason: `Another orrery process just started (PID ${raceWinner?.pid || "unknown"})`,
+        pid: raceWinner?.pid
+      };
+    }
+    return {
+      acquired: false,
+      reason: `Failed to create lock file: ${err.message}`
+    };
+  }
+}
+
+/**
+ * Release the execution lock (only if owned by current process).
+ * @param {string} [planId] - Optional plan ID for per-plan locks
+ */
+function releaseLock(planId) {
+  const lockPath = getLockPath(planId);
+  const existing = readLock(planId);
+
+  if (existing && existing.pid === process.pid) {
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Get the current lock status (read-only).
+ * @param {string} [planId] - Optional plan ID for per-plan locks
+ * @returns {{locked: boolean, pid?: number, startedAt?: string, stale: boolean, planId?: string, worktreePath?: string}}
+ */
+function getLockStatus(planId) {
+  const existing = readLock(planId);
+
+  if (!existing) {
+    return { locked: false, stale: false };
+  }
+
+  const running = isProcessRunning(existing.pid);
+  const isOrrery = running && isOrreryProcess(existing.pid);
+
+  const status = {
+    locked: isOrrery,
+    pid: existing.pid,
+    startedAt: existing.startedAt,
+    stale: !isOrrery
+  };
+  if (existing.planId) status.planId = existing.planId;
+  if (existing.worktreePath) status.worktreePath = existing.worktreePath;
+  return status;
+}
+
+/**
+ * List all per-plan locks in the work directory.
+ * @returns {Array<{planId: string, pid: number, startedAt: string, active: boolean, stale: boolean, worktreePath?: string}>}
+ */
+function listPlanLocks() {
+  const workDir = getWorkDir();
+  const results = [];
+
+  let entries;
+  try {
+    entries = fs.readdirSync(workDir);
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    const match = entry.match(/^exec-(.+)\.lock$/);
+    if (!match) continue;
+
+    const planId = match[1];
+    const lockPath = path.join(workDir, entry);
+    let lockData;
+    try {
+      lockData = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    } catch {
+      continue;
+    }
+
+    const running = isProcessRunning(lockData.pid);
+    const active = running && isOrreryProcess(lockData.pid);
+
+    const info = {
+      planId,
+      pid: lockData.pid,
+      startedAt: lockData.startedAt,
+      active,
+      stale: !active
+    };
+    if (lockData.worktreePath) info.worktreePath = lockData.worktreePath;
+    results.push(info);
+  }
+
+  return results;
+}
+
+module.exports = {
+  acquireLock,
+  releaseLock,
+  getLockStatus,
+  listPlanLocks,
+  readLock,
+  isProcessRunning,
+  isOrreryProcess
+};

package/lib/utils/paths.js

@@ -1,7 +1,9 @@
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 
 const WORK_DIR_ENV = "ORRERY_WORK_DIR";
+const REPO_ROOT_ENV = "ORRERY_REPO_ROOT";
 
 function ensureDir(dirPath) {
   if (!fs.existsSync(dirPath)) {
@@ -10,12 +12,45 @@ function ensureDir(dirPath) {
   return dirPath;
 }
 
+/**
+ * Get the effective repo root for path resolution.
+ * Uses ORRERY_REPO_ROOT if set (when running inside a worktree), otherwise process.cwd().
+ * @returns {string} - Resolved repo root path
+ */
+function getEffectiveRoot() {
+  const envRoot = process.env[REPO_ROOT_ENV];
+  if (envRoot && envRoot.trim()) {
+    return path.resolve(envRoot.trim());
+  }
+  return path.resolve(process.cwd());
+}
+
+/**
+ * Generate a deterministic project identifier from the current working directory.
+ * Format: <sanitized-basename>-<hash8>
+ * When ORRERY_REPO_ROOT is set (inside a worktree), uses that instead of cwd
+ * so the project ID stays consistent.
+ * @returns {string} - Project identifier
+ */
+function getProjectId() {
+  const cwd = getEffectiveRoot();
+  const basename = path.basename(cwd) || "root";
+  const sanitized = basename.replace(/[^a-zA-Z0-9._-]/g, "_");
+  const hash = crypto
+    .createHash("sha256")
+    .update(cwd)
+    .digest("hex")
+    .slice(0, 8);
+  return `${sanitized}-${hash}`;
+}
+
 function getWorkDir() {
   const envDir = process.env[WORK_DIR_ENV];
   if (envDir && envDir.trim()) {
-    return ensureDir(envDir.trim());
+    const projectScoped = path.join(envDir.trim(), getProjectId());
+    return ensureDir(projectScoped);
   }
-  return ensureDir(path.join(process.cwd(), ".agent-work"));
+  return ensureDir(path.join(getEffectiveRoot(), ".agent-work"));
 }
 
 function getPlansDir() {
@@ -34,10 +69,18 @@ function getTempDir() {
   return ensureDir(path.join(getWorkDir(), "temp"));
 }
 
+function isWorkDirExternal() {
+  const workDir = path.resolve(getWorkDir());
+  const root = getEffectiveRoot();
+  return !workDir.startsWith(root + path.sep) && workDir !== root;
+}
+
 module.exports = {
   getWorkDir,
   getPlansDir,
   getCompletedDir,
   getReportsDir,
-  getTempDir
+  getTempDir,
+  getProjectId,
+  isWorkDirExternal
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caseyharalson/orrery",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Workflow planning and orchestration CLI for AI agents",
   "license": "MIT",
   "author": "Casey Haralson",
@@ -52,7 +52,8 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "eslint": "^9.39.2",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.1",
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.8.1"
   }