@caseyharalson/orrery 0.7.1

package/lib/cli/commands/resume.js

@@ -0,0 +1,146 @@
+const path = require("path");
+
+const { findPlanForCurrentBranch } = require("../../utils/plan-detect");
+const { updateStepsStatus } = require("../../orchestration/plan-loader");
+const { commit } = require("../../utils/git");
+const { orchestrate } = require("../../orchestration");
+
+function supportsColor() {
+  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+
+function colorize(text, color) {
+  if (!supportsColor()) return text;
+  const colors = {
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    reset: "\x1b[0m"
+  };
+  return `${colors[color] || ""}${text}${colors.reset}`;
+}
+
+module.exports = function registerResumeCommand(program) {
+  program
+    .command("resume")
+    .description("Unblock steps and resume orchestration")
+    .option("--step <id>", "Unblock a specific step before resuming")
+    .option("--all", "Unblock all blocked steps (default behavior)")
+    .option(
+      "--dry-run",
+      "Preview what would be unblocked without making changes"
+    )
+    .action(async (options) => {
+      // 1. Find plan for current branch
+      let match;
+      try {
+        match = findPlanForCurrentBranch();
+      } catch {
+        console.error("Error detecting plan from current branch.");
+        console.log(
+          "Make sure you're on a work branch (e.g., plan/feature-name)."
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      if (!match) {
+        console.error(
+          "Not on a work branch. No plan found for current branch."
+        );
+        console.log("\nTo resume a plan:");
+        console.log("  1. git checkout <work-branch>");
+        console.log("  2. orrery resume");
+        process.exitCode = 1;
+        return;
+      }
+
+      const { planFile, plan } = match;
+      const planFileName = path.basename(planFile);
+      console.log(`(detected plan: ${planFileName})\n`);
+
+      // 2. Check for blocked steps
+      const blockedSteps = plan.steps.filter((s) => s.status === "blocked");
+
+      // 3. If no blocked steps, skip to resume
+      if (blockedSteps.length === 0) {
+        console.log("No blocked steps to unblock.\n");
+
+        if (options.dryRun) {
+          console.log("Dry run: would resume orchestration.");
+          return;
+        }
+
+        console.log("Resuming orchestration...\n");
+        await orchestrate({ resume: true });
+        return;
+      }
+
+      // 4. Determine which steps to unblock
+      let stepsToUnblock = [];
+
+      if (options.step) {
+        // Unblock specific step
+        const step = blockedSteps.find((s) => s.id === options.step);
+        if (!step) {
+          console.error(
+            `Step "${options.step}" is not blocked or does not exist.`
+          );
+          console.log("\nBlocked steps:");
+          for (const s of blockedSteps) {
+            console.log(`  - ${s.id}`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+        stepsToUnblock = [step];
+      } else {
+        // Default: unblock all (--all is implicit)
+        stepsToUnblock = blockedSteps;
+      }
+
+      // 5. Dry-run mode: show preview
+      if (options.dryRun) {
+        console.log("Dry run - would unblock the following steps:\n");
+        for (const step of stepsToUnblock) {
+          console.log(`  ${step.id}`);
+          if (step.blocked_reason) {
+            console.log(`    (was blocked: ${step.blocked_reason})`);
+          }
+        }
+        console.log("\nThen would commit and resume orchestration.");
+        return;
+      }
+
+      // 6. Perform the unblock
+      const updates = stepsToUnblock.map((step) => ({
+        stepId: step.id,
+        status: "pending",
+        extras: { blocked_reason: null } // Clear the blocked_reason
+      }));
+
+      updateStepsStatus(planFile, updates);
+
+      console.log(`Unblocked ${stepsToUnblock.length} step(s):\n`);
+      for (const step of stepsToUnblock) {
+        console.log(`  ${colorize("pending", "yellow")} ${step.id}`);
+      }
+
+      // 7. Commit the plan file changes
+      const planName = planFileName.replace(/\.ya?ml$/, "");
+      const commitMessage = `chore: unblock steps in ${planName}`;
+      const commitHash = commit(commitMessage, [planFile], process.cwd());
+
+      if (commitHash) {
+        console.log(
+          `\nCommitted: ${commitMessage} (${commitHash.slice(0, 7)})`
+        );
+      } else {
+        console.log("\n(no changes to commit)");
+      }
+
+      // 8. Resume orchestration
+      console.log("\nResuming orchestration...\n");
+      await orchestrate({ resume: true });
+    });
+};

package/lib/cli/commands/status.js

@@ -0,0 +1,137 @@
+const path = require("path");
+
+const { getPlansDir } = require("../../utils/paths");
+const { getPlanFiles, loadPlan } = require("../../orchestration/plan-loader");
+const { findPlanForCurrentBranch } = require("../../utils/plan-detect");
+const { getCurrentBranch } = require("../../utils/git");
+
+function supportsColor() {
+  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+
+function colorize(text, color) {
+  if (!supportsColor()) return text;
+  const colors = {
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    reset: "\x1b[0m"
+  };
+  return `${colors[color] || ""}${text}${colors.reset}`;
+}
+
+function getPlanStatus(plan) {
+  if (plan.isSuccessful()) return "complete";
+  if (plan.steps.some((step) => step.status === "blocked")) return "blocked";
+  if (plan.steps.some((step) => step.status === "in_progress")) {
+    return "in_progress";
+  }
+  if (plan.metadata && plan.metadata.work_branch) return "in_flight";
+  return "pending";
+}
+
+function getStatusColor(status) {
+  if (status === "complete") return "green";
+  if (status === "in_progress" || status === "in_flight") return "yellow";
+  if (status === "blocked") return "red";
+  return null;
+}
+
+function formatStatusLabel(status) {
+  const color = getStatusColor(status);
+  const label = status.replace("_", " ");
+  return color ? colorize(label, color) : label;
+}
+
+function resolvePlanPath(planArg) {
+  if (!planArg) return null;
+  if (path.isAbsolute(planArg)) return planArg;
+  if (planArg.includes(path.sep)) return path.resolve(process.cwd(), planArg);
+  return path.join(getPlansDir(), planArg);
+}
+
+function summarizePlans(plans) {
+  let pendingSteps = 0;
+  let completedSteps = 0;
+
+  for (const plan of plans) {
+    for (const step of plan.steps) {
+      if (step.status === "pending") pendingSteps += 1;
+      if (step.status === "complete") completedSteps += 1;
+    }
+  }
+
+  return { pendingSteps, completedSteps };
+}
+
+function renderPlanList(plans) {
+  for (const plan of plans) {
+    const status = getPlanStatus(plan);
+    const label = formatStatusLabel(status);
+    console.log(`${label} ${plan.fileName}`);
+  }
+}
+
+function renderPlanDetail(plan) {
+  const status = getPlanStatus(plan);
+  console.log(`${formatStatusLabel(status)} ${plan.fileName}`);
+  for (const step of plan.steps) {
+    const stepLabel = formatStatusLabel(step.status || "pending");
+    const description = step.description ? ` - ${step.description}` : "";
+    console.log(`  ${stepLabel} ${step.id}${description}`);
+    // Display blocked reason if step is blocked
+    if (step.status === "blocked" && step.blocked_reason) {
+      console.log(`    Reason: ${step.blocked_reason}`);
+    }
+  }
+}
+
+module.exports = function registerStatusCommand(program) {
+  program
+    .command("status")
+    .description("Show orchestration status for plans in the current project")
+    .option("--plan <file>", "Show detailed status for a specific plan")
+    .action((options) => {
+      const plansDir = getPlansDir();
+      const planArg = options.plan;
+
+      if (planArg) {
+        const planPath = resolvePlanPath(planArg);
+        if (!planPath || !require("fs").existsSync(planPath)) {
+          console.error(`Plan not found: ${planArg}`);
+          process.exitCode = 1;
+          return;
+        }
+
+        const plan = loadPlan(planPath);
+        renderPlanDetail(plan);
+        return;
+      }
+
+      // Auto-detect plan when on a work branch
+      try {
+        const match = findPlanForCurrentBranch();
+        if (match) {
+          const currentBranch = getCurrentBranch(process.cwd());
+          console.log(`(detected plan for branch: ${currentBranch})\n`);
+          renderPlanDetail(match.plan);
+          return;
+        }
+      } catch {
+        // Not a git repo or other git error - fall through to list all plans
+      }
+
+      const planFiles = getPlanFiles(plansDir);
+      if (planFiles.length === 0) {
+        console.log("No plans found");
+        return;
+      }
+
+      const plans = planFiles.map((planFile) => loadPlan(planFile));
+      const { pendingSteps, completedSteps } = summarizePlans(plans);
+      console.log(
+        `${plans.length} plans, ${pendingSteps} pending steps, ${completedSteps} completed`
+      );
+      renderPlanList(plans);
+    });
+};

package/lib/cli/commands/validate-plan.js

@@ -0,0 +1,288 @@
+const fs = require("fs");
+const path = require("path");
+const YAML = require("yaml");
+
+const { loadPlan, savePlan } = require("../../orchestration/plan-loader");
+
+const REQUIRED_STEP_FIELDS = ["id", "description"];
+const VALID_STATUSES = ["pending", "in_progress", "complete", "blocked"];
+
+/**
+ * Check if a file path is a plan file that should be validated
+ */
+function isPlanFile(filePath) {
+  return (
+    filePath &&
+    filePath.includes("work/plans/") &&
+    (filePath.endsWith(".yaml") || filePath.endsWith(".yml"))
+  );
+}
+
+/**
+ * Read JSON from stdin (for hook mode)
+ */
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("readable", () => {
+      let chunk;
+      while ((chunk = process.stdin.read()) !== null) {
+        data += chunk;
+      }
+    });
+    process.stdin.on("end", () => {
+      resolve(data);
+    });
+    if (process.stdin.isTTY) {
+      resolve("");
+    }
+  });
+}
+
+/**
+ * Validate plan structure and return errors/warnings
+ */
+function validatePlanStructure(filePath) {
+  const errors = [];
+  const warnings = [];
+
+  if (!fs.existsSync(filePath)) {
+    return { errors: [`File not found: ${filePath}`], warnings, data: null };
+  }
+
+  const content = fs.readFileSync(filePath, "utf8");
+
+  let data;
+  try {
+    data = YAML.parse(content);
+  } catch (err) {
+    let errorMsg = `YAML Parse Error in ${path.basename(filePath)}:\n`;
+    errorMsg += `  ${err.reason}`;
+    if (err.mark) {
+      errorMsg += `\n  Line ${err.mark.line + 1}, Column ${err.mark.column + 1}`;
+
+      const lines = content.split("\n");
+      const errorLine = err.mark.line;
+      const startLine = Math.max(0, errorLine - 2);
+      const endLine = Math.min(lines.length - 1, errorLine + 2);
+
+      errorMsg += "\n\n  Context:";
+      for (let i = startLine; i <= endLine; i++) {
+        const prefix = i === errorLine ? ">>> " : "    ";
+        errorMsg += `\n  ${prefix}${i + 1}: ${lines[i]}`;
+      }
+    }
+    errorMsg += "\n\nCommon causes:";
+    errorMsg += "\n  - Unquoted strings containing colons (use double quotes)";
+    errorMsg += "\n  - Inconsistent indentation (use 2 spaces)";
+    errorMsg += "\n  - Special characters in values (quote the entire value)";
+    errorMsg += "\n\nExample fix:";
+    errorMsg += "\n  BAD:  criteria: Output shows: timestamp";
+    errorMsg += '\n  GOOD: criteria: "Output shows: timestamp"';
+
+    return { errors: [errorMsg], warnings, data: null };
+  }
+
+  if (!data) {
+    errors.push("Plan file is empty");
+    return { errors, warnings, data: null };
+  }
+
+  // Check for steps array
+  if (!data.steps) {
+    errors.push("Missing required 'steps' array");
+  } else if (!Array.isArray(data.steps)) {
+    errors.push("'steps' must be an array");
+  } else {
+    const stepIds = new Set();
+
+    data.steps.forEach((step, index) => {
+      const stepLabel = step.id
+        ? `step '${step.id}'`
+        : `step at index ${index}`;
+
+      for (const field of REQUIRED_STEP_FIELDS) {
+        if (!step[field]) {
+          errors.push(`${stepLabel}: missing required field '${field}'`);
+        }
+      }
+
+      if (step.id) {
+        if (stepIds.has(step.id)) {
+          errors.push(`Duplicate step ID: '${step.id}'`);
+        }
+        stepIds.add(step.id);
+      }
+
+      if (step.status && !VALID_STATUSES.includes(step.status)) {
+        errors.push(
+          `${stepLabel}: invalid status '${step.status}' (must be one of: ${VALID_STATUSES.join(", ")})`
+        );
+      }
+
+      if (step.deps) {
+        if (!Array.isArray(step.deps)) {
+          errors.push(`${stepLabel}: 'deps' must be an array`);
+        } else {
+          step.deps.forEach((dep) => {
+            if (typeof dep !== "string") {
+              errors.push(
+                `${stepLabel}: dependency must be a string, got ${typeof dep}`
+              );
+            }
+          });
+        }
+      }
+
+      if (step.files && !Array.isArray(step.files)) {
+        errors.push(`${stepLabel}: 'files' must be an array`);
+      }
+
+      if (step.commands && !Array.isArray(step.commands)) {
+        errors.push(`${stepLabel}: 'commands' must be an array`);
+      }
+
+      if (
+        step.criteria &&
+        step.criteria.includes(": ") &&
+        !step.criteria.startsWith('"')
+      ) {
+        warnings.push(
+          `${stepLabel}: 'criteria' contains ': ' - ensure this field is properly quoted in source`
+        );
+      }
+    });
+
+    // Validate dependency references
+    data.steps.forEach((step) => {
+      if (step.deps && Array.isArray(step.deps)) {
+        step.deps.forEach((dep) => {
+          if (!stepIds.has(dep)) {
+            errors.push(
+              `step '${step.id}': references unknown dependency '${dep}'`
+            );
+          }
+        });
+      }
+    });
+  }
+
+  if (!data.metadata) {
+    warnings.push("Missing 'metadata' section (recommended)");
+  }
+
+  return { errors, warnings, data };
+}
+
+/**
+ * Validate a plan file and optionally re-save to normalize formatting
+ */
+function validatePlan(filePath, options = {}) {
+  const { errors, warnings, data } = validatePlanStructure(filePath);
+
+  console.log(`\nValidating: ${path.basename(filePath)}\n`);
+
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log("✓ Plan is valid\n");
+    const stepCount = data.steps ? data.steps.length : 0;
+    console.log(`  Steps: ${stepCount}`);
+    if (data.steps) {
+      data.steps.forEach((step) => {
+        const status = step.status || "pending";
+        const desc = step.description || "";
+        console.log(
+          `    - ${step.id}: ${desc.substring(0, 50)}${desc.length > 50 ? "..." : ""} [${status}]`
+        );
+      });
+    }
+    console.log();
+
+    // Re-save to normalize formatting (uses same format as orchestrator)
+    if (!options.skipResave) {
+      const plan = loadPlan(filePath);
+      savePlan(plan);
+    }
+
+    return true;
+  }
+
+  if (errors.length > 0) {
+    console.error("✗ Validation errors:\n");
+    errors.forEach((err) => console.error(`  - ${err}`));
+    console.error();
+  }
+
+  if (warnings.length > 0) {
+    console.warn("⚠ Warnings:\n");
+    warnings.forEach((warn) => console.warn(`  - ${warn}`));
+    console.warn();
+
+    // Re-save valid plans with warnings too
+    if (errors.length === 0 && !options.skipResave) {
+      const plan = loadPlan(filePath);
+      savePlan(plan);
+    }
+  }
+
+  return errors.length === 0;
+}
+
+/**
+ * Run in hook mode - read file path from stdin JSON
+ */
+async function runAsHook() {
+  const input = await readStdin();
+
+  if (!input.trim()) {
+    process.exit(0);
+  }
+
+  let hookData;
+  try {
+    hookData = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath = hookData?.tool_input?.file_path;
+
+  if (!isPlanFile(filePath)) {
+    process.exit(0);
+  }
+
+  const isValid = validatePlan(filePath);
+  process.exit(isValid ? 0 : 2);
+}
+
+module.exports = registerValidatePlanCommand;
+module.exports.validatePlanStructure = validatePlanStructure;
+
+function registerValidatePlanCommand(program) {
+  program
+    .command("validate-plan")
+    .description("Validate a plan YAML file and normalize its formatting")
+    .argument(
+      "[file]",
+      "Path to the plan file (or reads from stdin for hook mode)"
+    )
+    .option("--no-resave", "Skip re-saving the file after validation")
+    .action(async (file, options) => {
+      if (!file) {
+        // Hook mode - read from stdin
+        await runAsHook();
+        return;
+      }
+
+      const filePath = path.resolve(file);
+
+      if (!fs.existsSync(filePath)) {
+        console.error(`File not found: ${file}`);
+        process.exitCode = 2;
+        return;
+      }
+
+      const isValid = validatePlan(filePath, { skipResave: !options.resave });
+      process.exitCode = isValid ? 0 : 2;
+    });
+}

package/lib/cli/index.js

@@ -0,0 +1,57 @@
+const path = require("path");
+const { Command } = require("commander");
+
+const registerInit = require("./commands/init");
+const registerInstallSkills = require("./commands/install-skills");
+const registerInstallDevcontainer = require("./commands/install-devcontainer");
+const registerOrchestrate = require("./commands/orchestrate");
+const registerStatus = require("./commands/status");
+const registerResume = require("./commands/resume");
+const registerValidatePlan = require("./commands/validate-plan");
+const registerIngestPlan = require("./commands/ingest-plan");
+const registerHelp = require("./commands/help");
+
+function getPackageVersion() {
+  const pkgPath = path.join(__dirname, "..", "..", "package.json");
+  const pkg = require(pkgPath);
+  return pkg.version || "0.0.0";
+}
+
+function buildProgram() {
+  const program = new Command();
+
+  program
+    .name("orrery")
+    .description("Structured workflow orchestration for AI agents")
+    .version(getPackageVersion(), "-v, --version")
+    .showHelpAfterError();
+
+  registerInit(program);
+  registerInstallSkills(program);
+  registerInstallDevcontainer(program);
+  registerOrchestrate(program);
+  registerStatus(program);
+  registerResume(program);
+  registerValidatePlan(program);
+  registerIngestPlan(program);
+  registerHelp(program);
+
+  program.on("command:*", (operands) => {
+    const [command] = operands;
+    console.error(`Unknown command: ${command}`);
+    program.outputHelp();
+    process.exitCode = 1;
+  });
+
+  return program;
+}
+
+function run(argv) {
+  const program = buildProgram();
+  program.parse(argv);
+}
+
+module.exports = {
+  buildProgram,
+  run
+};