@caseyharalson/orrery 0.7.1

package/lib/orchestration/plan-loader.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const YAML = require("yaml");
+
+/**
+ * Load a plan from a YAML file
+ * @param {string} filePath - Absolute path to the plan YAML file
+ * @returns {Object} - Parsed plan object with helper methods
+ */
+function loadPlan(filePath) {
+  const content = fs.readFileSync(filePath, "utf8");
+  const doc = YAML.parseDocument(content);
+  const data = doc.toJS();
+
+  return {
+    filePath,
+    fileName: path.basename(filePath),
+    doc,
+    metadata: data.metadata || {},
+    steps: data.steps || [],
+
+    /**
+     * Get set of completed step IDs
+     * @returns {Set<string>}
+     */
+    getCompletedSteps() {
+      return new Set(
+        this.steps.filter((s) => s.status === "complete").map((s) => s.id)
+      );
+    },
+
+    /**
+     * Get set of blocked step IDs
+     * @returns {Set<string>}
+     */
+    getBlockedSteps() {
+      return new Set(
+        this.steps.filter((s) => s.status === "blocked").map((s) => s.id)
+      );
+    },
+
+    /**
+     * Check if all steps are complete or blocked
+     * @returns {boolean}
+     */
+    isComplete() {
+      return this.steps.every(
+        (s) => s.status === "complete" || s.status === "blocked"
+      );
+    },
+
+    /**
+     * Check if all steps are complete (none blocked)
+     * @returns {boolean}
+     */
+    isSuccessful() {
+      return this.steps.every((s) => s.status === "complete");
+    }
+  };
+}
+
+/**
+ * Save a plan back to its YAML file (preserves comments)
+ * @param {Object} plan - The plan object (with filePath, doc, metadata, steps)
+ */
+function savePlan(plan) {
+  const metadataNode = plan.doc.get("metadata", true);
+  const stepsNode = plan.doc.get("steps", true);
+
+  // Update metadata fields in-place
+  if (metadataNode) {
+    for (const [key, value] of Object.entries(plan.metadata)) {
+      metadataNode.set(key, value);
+    }
+  }
+
+  // Update step fields in-place
+  if (stepsNode && stepsNode.items) {
+    for (let i = 0; i < plan.steps.length; i++) {
+      const stepData = plan.steps[i];
+      const stepNode = stepsNode.items[i];
+      if (stepNode) {
+        for (const [key, value] of Object.entries(stepData)) {
+          stepNode.set(key, value);
+        }
+      }
+    }
+  }
+
+  fs.writeFileSync(plan.filePath, plan.doc.toString(), "utf8");
+}
+
+/**
+ * Update a specific step's status in a plan file (preserves comments)
+ * @param {string} filePath - Path to the plan file
+ * @param {string} stepId - ID of the step to update
+ * @param {string} status - New status value (pending, in_progress, complete, blocked)
+ * @param {Object} [extras] - Optional extra fields to update (e.g., blockedReason)
+ */
+function updateStepStatus(filePath, stepId, status, extras = {}) {
+  const content = fs.readFileSync(filePath, "utf8");
+  const doc = YAML.parseDocument(content);
+  const stepsNode = doc.get("steps", true);
+
+  if (!stepsNode || !stepsNode.items) return;
+
+  for (const stepNode of stepsNode.items) {
+    const idNode = stepNode.get("id", true);
+    if (idNode && String(idNode) === stepId) {
+      stepNode.set("status", status);
+      for (const [key, value] of Object.entries(extras)) {
+        stepNode.set(key, value);
+      }
+      break;
+    }
+  }
+
+  fs.writeFileSync(filePath, doc.toString(), "utf8");
+}
+
+/**
+ * Update multiple steps' status at once (preserves comments)
+ * @param {string} filePath - Path to the plan file
+ * @param {Array<{stepId: string, status: string, extras?: Object}>} updates - Array of updates
+ */
+function updateStepsStatus(filePath, updates) {
+  const content = fs.readFileSync(filePath, "utf8");
+  const doc = YAML.parseDocument(content);
+  const stepsNode = doc.get("steps", true);
+
+  if (!stepsNode || !stepsNode.items) return;
+
+  const updateMap = new Map(updates.map((u) => [u.stepId, u]));
+
+  for (const stepNode of stepsNode.items) {
+    const idNode = stepNode.get("id", true);
+    const stepId = idNode ? String(idNode) : null;
+    const update = updateMap.get(stepId);
+
+    if (update) {
+      stepNode.set("status", update.status);
+      for (const [key, value] of Object.entries(update.extras || {})) {
+        if (value === null) {
+          stepNode.delete(key); // Remove field when null
+        } else {
+          stepNode.set(key, value);
+        }
+      }
+    }
+  }
+
+  fs.writeFileSync(filePath, doc.toString(), "utf8");
+}
+
+/**
+ * Get all YAML plan files in a directory
+ * @param {string} dir - Directory to scan
+ * @returns {string[]} - Array of absolute file paths, sorted by name
+ */
+function getPlanFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+    .map((f) => path.join(dir, f))
+    .sort();
+}
+
+/**
+ * Move a completed plan to the completed directory
+ * @param {string} planFile - Current path of the plan
+ * @param {string} completedDir - Destination directory
+ */
+function movePlanToCompleted(planFile, completedDir) {
+  const fileName = path.basename(planFile);
+  const destPath = path.join(completedDir, fileName);
+
+  if (!fs.existsSync(completedDir)) {
+    fs.mkdirSync(completedDir, { recursive: true });
+  }
+
+  fs.renameSync(planFile, destPath);
+  return destPath;
+}
+
+/**
+ * Get filenames of completed plans (for exclusion filtering)
+ * @param {string} completedDir - Path to completed directory
+ * @returns {Set<string>} - Set of filenames
+ */
+function getCompletedPlanNames(completedDir) {
+  if (!fs.existsSync(completedDir)) return new Set();
+
+  return new Set(
+    fs
+      .readdirSync(completedDir)
+      .filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"))
+  );
+}
+
+module.exports = {
+  loadPlan,
+  savePlan,
+  updateStepStatus,
+  updateStepsStatus,
+  getPlanFiles,
+  movePlanToCompleted,
+  getCompletedPlanNames
+};

package/lib/orchestration/progress-tracker.js

@@ -0,0 +1,208 @@
+/**
+ * Progress Tracker for Plan Orchestration
+ *
+ * Tracks step completion, elapsed time, and provides ETA estimates
+ * during plan execution.
+ */
+
+class ProgressTracker {
+  /**
+   * @param {number} totalSteps - Total number of steps in the plan
+   * @param {string} planFileName - Name of the plan file for display
+   */
+  constructor(totalSteps, planFileName) {
+    this.totalSteps = totalSteps;
+    this.planFileName = planFileName;
+    this.completedCount = 0;
+    this.blockedCount = 0;
+    this.startTime = Date.now();
+    this.stepCompletionTimes = []; // Duration of each completed step
+    this.stepStartTimes = new Map(); // stepId -> startTime
+  }
+
+  /**
+   * Initialize counts from existing plan state (for resume mode)
+   * @param {Object} plan - The loaded plan object
+   */
+  initializeFromPlan(plan) {
+    for (const step of plan.steps) {
+      if (step.status === "complete") {
+        this.completedCount++;
+      } else if (step.status === "blocked") {
+        this.blockedCount++;
+      }
+    }
+  }
+
+  /**
+   * Record when step(s) begin execution
+   * @param {string[]} stepIds - Array of step IDs starting
+   */
+  recordStart(stepIds) {
+    const now = Date.now();
+    for (const stepId of stepIds) {
+      this.stepStartTimes.set(stepId, now);
+    }
+  }
+
+  /**
+   * Record a step completing successfully
+   * @param {string} stepId - The completed step ID
+   */
+  recordComplete(stepId) {
+    this.completedCount++;
+    const startTime = this.stepStartTimes.get(stepId);
+    if (startTime) {
+      const duration = Date.now() - startTime;
+      this.stepCompletionTimes.push(duration);
+      this.stepStartTimes.delete(stepId);
+    }
+  }
+
+  /**
+   * Record a step becoming blocked
+   * @param {string} stepId - The blocked step ID
+   */
+  recordBlocked(stepId) {
+    this.blockedCount++;
+    this.stepStartTimes.delete(stepId);
+  }
+
+  /**
+   * Get elapsed time since tracking started
+   * @returns {number} Elapsed time in milliseconds
+   */
+  getElapsed() {
+    return Date.now() - this.startTime;
+  }
+
+  /**
+   * Get estimated time remaining based on average step duration
+   * @returns {number|null} Estimated remaining time in ms, or null if not calculable
+   */
+  getEstimatedRemaining() {
+    if (this.stepCompletionTimes.length === 0) {
+      return null; // No data yet
+    }
+
+    const avgStepTime =
+      this.stepCompletionTimes.reduce((a, b) => a + b, 0) /
+      this.stepCompletionTimes.length;
+
+    const remainingSteps =
+      this.totalSteps - this.completedCount - this.blockedCount;
+
+    return avgStepTime * remainingSteps;
+  }
+
+  /**
+   * Format duration in human-readable format
+   * @param {number} ms - Duration in milliseconds
+   * @returns {string} Formatted string like "2m 30s" or "1h 5m"
+   */
+  formatDuration(ms) {
+    if (ms < 1000) {
+      return "<1s";
+    }
+
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+
+    if (hours > 0) {
+      const remainingMinutes = minutes % 60;
+      return `${hours}h ${remainingMinutes}m`;
+    } else if (minutes > 0) {
+      const remainingSeconds = seconds % 60;
+      return `${minutes}m ${remainingSeconds}s`;
+    } else {
+      return `${seconds}s`;
+    }
+  }
+
+  /**
+   * Get completion percentage
+   * @returns {number} Percentage complete (0-100)
+   */
+  getPercentComplete() {
+    const processed = this.completedCount + this.blockedCount;
+    return Math.round((processed / this.totalSteps) * 100);
+  }
+
+  /**
+   * Log the start of plan execution
+   */
+  logStart() {
+    const initialComplete = this.completedCount;
+    const initialBlocked = this.blockedCount;
+    const pending = this.totalSteps - initialComplete - initialBlocked;
+
+    console.log(`[Progress] Starting plan: ${this.planFileName}`);
+    console.log(
+      `[Progress] Total steps: ${this.totalSteps} (${pending} pending, ${initialComplete} complete, ${initialBlocked} blocked)`
+    );
+  }
+
+  /**
+   * Log when step(s) start
+   * @param {string[]} stepIds - Array of step IDs starting
+   */
+  logStepStart(stepIds) {
+    this.recordStart(stepIds);
+    const processed = this.completedCount + this.blockedCount;
+    const stepList = stepIds.join(", ");
+
+    if (stepIds.length === 1) {
+      console.log(
+        `[Progress] Starting ${stepList} (${processed + 1} of ${this.totalSteps})`
+      );
+    } else {
+      console.log(
+        `[Progress] Starting ${stepIds.length} steps: ${stepList} (${processed + 1}-${processed + stepIds.length} of ${this.totalSteps})`
+      );
+    }
+  }
+
+  /**
+   * Log current progress after step completion
+   */
+  logProgress() {
+    const processed = this.completedCount + this.blockedCount;
+    const percent = this.getPercentComplete();
+    const elapsed = this.formatDuration(this.getElapsed());
+    const eta = this.getEstimatedRemaining();
+
+    let progressLine = `[Progress] ${processed}/${this.totalSteps} steps (${percent}%) | Elapsed: ${elapsed}`;
+
+    if (eta !== null) {
+      progressLine += ` | ETA: ${this.formatDuration(eta)}`;
+    } else {
+      progressLine += " | ETA: Calculating...";
+    }
+
+    console.log(progressLine);
+  }
+
+  /**
+   * Log final summary when plan execution ends
+   */
+  logSummary() {
+    const totalTime = this.formatDuration(this.getElapsed());
+    const avgTime =
+      this.stepCompletionTimes.length > 0
+        ? this.formatDuration(
+            this.stepCompletionTimes.reduce((a, b) => a + b, 0) /
+              this.stepCompletionTimes.length
+          )
+        : "N/A";
+
+    console.log(`[Progress] === Summary ===`);
+    console.log(
+      `[Progress] Total: ${this.totalSteps} steps (${this.completedCount} complete, ${this.blockedCount} blocked)`
+    );
+    console.log(`[Progress] Time: ${totalTime}`);
+    console.log(`[Progress] Avg step time: ${avgTime}`);
+  }
+}
+
+module.exports = { ProgressTracker };

package/lib/orchestration/report-format.js

@@ -0,0 +1,80 @@
+/**
+ * Report Format Definition (Single Source of Truth)
+ *
+ * IMPORTANT: Any changes to the structure or instructions below MUST be manually
+ * reflected in: agent/skills/orrery-report/SKILL.md
+ */
+
+// 1. Define the Expected Shape (The Contract)
+const REPORT_FIELDS = {
+  stepId: "The ID of the step being executed (string)",
+  status: "One of: 'complete', 'blocked'",
+  summary: "A concise summary of what was done (string)",
+  artifacts: "Array of file paths created or modified (string[])",
+  testResults: "Optional: Test outcome summary (string, e.g., '2/2 passed')",
+  blockedReason: "Required if status is 'blocked' (string)",
+  commitMessage:
+    "A meaningful commit message (string, e.g., 'feat: add login endpoint')"
+};
+
+// 2. Generate the Instruction for the Agent
+function getFormatInstructions() {
+  return `## Output Contract
+
+Output one JSON object per step to stdout. You may output multiple objects if processing multiple steps.
+
+Success Example:
+{"stepId": "step-1", "status": "complete", "summary": "Implemented login", "artifacts": ["src/auth.js"], "testResults": "5/5 passed", "commitMessage": "feat: add user authentication"}
+
+Blocked Example:
+{"stepId": "step-2", "status": "blocked", "blockedReason": "API is down", "summary": "Could not verify"}
+
+Rules:
+- JSON must be valid and on a single line.
+- Do not wrap in markdown blocks (just raw JSON).
+- Each step result must be a separate JSON object.`;
+}
+
+// 3. Validate/Normalize the incoming data
+function validateAgentOutput(data) {
+  if (!data || typeof data !== "object") {
+    throw new Error("Report data must be an object");
+  }
+
+  // Required fields
+  if (!data.stepId || typeof data.stepId !== "string") {
+    throw new Error("Report missing required field: stepId (string)");
+  }
+
+  if (!data.status || !["complete", "blocked"].includes(data.status)) {
+    throw new Error(
+      `Invalid status: ${data.status}. Must be 'complete' or 'blocked'`
+    );
+  }
+
+  // Conditional requirements
+  if (data.status === "blocked" && !data.blockedReason) {
+    throw new Error(
+      "Report with status 'blocked' must include 'blockedReason'"
+    );
+  }
+
+  // Normalize optional fields
+  return {
+    stepId: data.stepId,
+    status: data.status,
+    summary:
+      data.summary ||
+      (data.status === "blocked" ? "Step blocked" : "Step completed"),
+    artifacts: Array.isArray(data.artifacts) ? data.artifacts : [],
+    testResults: data.testResults || null,
+    blockedReason: data.blockedReason || null,
+    commitMessage: data.commitMessage || `feat: complete step ${data.stepId}`
+  };
+}
+
+module.exports = {
+  REPORT_FIELDS,
+  getFormatInstructions,
+  validateAgentOutput
+};