jules-orchestrator-kit 0.29.1 → 0.32.0

package/src/ops/doctor-planner.mjs

@@ -0,0 +1,214 @@
+import { join, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+
+/**
+ * @typedef {import("../ux/capabilities.mjs").ActionPlan} ActionPlan
+ * @typedef {import("./doctor-registry.mjs").DoctorReport} DoctorReport
+ *
+ * @typedef {Object} FixPlanningContext
+ * @property {string} root
+ * @property {DoctorReport} report
+ * @property {string[]} selectedFixIds
+ * @property {Record<string, unknown>} [answers]
+ */
+
+/**
+ * Generate unified diff preview string for file creation/replacement.
+ * @param {string} path
+ * @param {string} oldContent
+ * @param {string} newContent
+ * @returns {string}
+ */
+function createDiffPreview(path, oldContent, newContent) {
+  const oldLines = oldContent ? oldContent.split("\n") : [];
+  const newLines = newContent ? newContent.split("\n") : [];
+  const lines = [];
+
+  lines.push(`--- a/${path}`);
+  lines.push(`+++ b/${path}`);
+  lines.push(`@@ -1,${oldLines.length || 0} +1,${newLines.length || 0} @@`);
+
+  for (const line of oldLines) {
+    lines.push(`-${line}`);
+  }
+  for (const line of newLines) {
+    lines.push(`+${line}`);
+  }
+
+  return lines.join("\n");
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function finalizePlan(plan) {
+  const { planHash: _oldHash, ...unsigned } = plan;
+  const planHash = "sha256:" + createHash("sha256").update(JSON.stringify(unsigned)).digest("hex");
+  return deepFreeze({ ...unsigned, planHash });
+}
+
+/**
+ * Plan diagnostic fixes into immutable ActionPlan objects.
+ * @param {FixPlanningContext} context
+ * @returns {Promise<ActionPlan[]>}
+ */
+export async function planDiagnosticFixes(context = {}) {
+  const root = resolve(context.root || process.cwd());
+  const report = context.report || { results: [] };
+  const selectedFixIds = Array.isArray(context.selectedFixIds) ? context.selectedFixIds : ["safe"];
+
+  const wantSafeOnly = selectedFixIds.includes("safe");
+  /** @type {ActionPlan[]} */
+  const plans = [];
+
+  for (const result of report.results || []) {
+    for (const fix of result.fixes || []) {
+      const isSelected = selectedFixIds.includes(fix.id) || (wantSafeOnly && fix.automatic);
+      if (!isSelected) continue;
+
+      if (fix.id === "config.create-default") {
+        const configPath = ".agent/config.yml";
+        const newContent = `# jules-orchestrator-kit configuration manifest
+version: 1
+tier: pro
+verify:
+  test: "npm test"
+  build: "npm run build"
+`;
+        const diff = createDiffPreview(configPath, "", newContent);
+        const planId = `PLAN-${Date.now()}-${randomUUID().slice(0, 8)}`;
+
+        plans.push({
+          schema: "agentctl/action-plan-v1",
+          id: planId,
+          kind: "config.create-default",
+          title: "Create default .agent/config.yml",
+          summary: "Generate initial configuration manifest for jules-orchestrator-kit",
+          risk: "low",
+          repository: root,
+          createdAt: new Date().toISOString(),
+          preconditions: [],
+          fileMutations: [
+            {
+              operation: "create",
+              path: configPath,
+              newContent,
+            },
+          ],
+          commandEffects: [],
+          stateTransitions: [],
+          preview: {
+            unifiedDiff: diff,
+            warnings: [],
+            estimatedImpact: ["Creates .agent/config.yml"],
+          },
+          confirmation: {
+            mode: "none",
+            prompt: "Apply default configuration?",
+          },
+          planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
+        });
+      } else if (fix.id === "state.rebuild-head") {
+        const dateStr = new Date().toISOString().split("T")[0];
+        const stateDir = join(root, ".agent", "state");
+        const headPath = `.agent/state/telemetry-${dateStr}.head`;
+        let tailHash = "0".repeat(64);
+        let segment = 0;
+        try {
+          const telemetryFiles = readdirSync(stateDir)
+            .filter((name) => name.startsWith(`telemetry-${dateStr}`) && name.endsWith(".jsonl"))
+            .sort((a, b) => {
+              const index = (name) => Number(name.match(/-(\d+)\.jsonl$/)?.[1] || 0);
+              return index(a) - index(b);
+            });
+          const lastFile = telemetryFiles.at(-1);
+          if (lastFile) {
+            const lines = readFileSync(join(stateDir, lastFile), "utf-8").split("\n").filter(Boolean);
+            const lastEntry = JSON.parse(lines.at(-1));
+            if (typeof lastEntry?.hash === "string") tailHash = lastEntry.hash;
+            const segmentMatch = lastFile.match(/-(\d+)\.jsonl$/);
+            segment = segmentMatch ? Number(segmentMatch[1]) : 0;
+          }
+        } catch (_) {}
+        const newContent = JSON.stringify({ v: 1, hash: tailHash, segment, ts: new Date().toISOString() });
+        const planId = `PLAN-${Date.now()}-${randomUUID().slice(0, 8)}`;
+
+        plans.push({
+          schema: "agentctl/action-plan-v1",
+          id: planId,
+          kind: "state.rebuild-head",
+          title: "Rebuild telemetry spine head pointer",
+          summary: "Re-initialize .head pointer for telemetry spine ledger",
+          risk: "low",
+          repository: root,
+          createdAt: new Date().toISOString(),
+          preconditions: [],
+          fileMutations: [
+            {
+              operation: "create",
+              path: headPath,
+              newContent,
+            },
+          ],
+          commandEffects: [],
+          stateTransitions: [],
+          preview: {
+            unifiedDiff: createDiffPreview(headPath, "", newContent),
+            warnings: [],
+            estimatedImpact: [`Creates ${headPath} pointer`],
+          },
+          confirmation: {
+            mode: "none",
+            prompt: "Rebuild telemetry head pointer?",
+          },
+          planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
+        });
+      } else if (fix.id === "locks.prune-stale") {
+        const locksDir = join(root, ".agent", "state", "locks");
+        if (existsSync(locksDir)) {
+          const lockFiles = readdirSync(locksDir).filter((f) => f.endsWith(".json"));
+          for (const lockFile of lockFiles) {
+            const lockRelPath = `.agent/state/locks/${lockFile}`;
+            const planId = `PLAN-${Date.now()}-${randomUUID().slice(0, 8)}`;
+
+            plans.push({
+              schema: "agentctl/action-plan-v1",
+              id: planId,
+              kind: "locks.prune-stale",
+              title: `Remove stale lock ${lockFile}`,
+              summary: `Prune inactive VFS lock file ${lockRelPath}`,
+              risk: "low",
+              repository: root,
+              createdAt: new Date().toISOString(),
+              preconditions: [],
+              fileMutations: [
+                {
+                  operation: "delete",
+                  path: lockRelPath,
+                },
+              ],
+              commandEffects: [],
+              stateTransitions: [],
+              preview: {
+                unifiedDiff: `--- a/${lockRelPath}\n+++ /dev/null\n`,
+                warnings: [],
+                estimatedImpact: [`Removes ${lockRelPath}`],
+              },
+              confirmation: {
+                mode: "none",
+                prompt: `Remove lock ${lockFile}?`,
+              },
+              planHash: "sha256:" + createHash("sha256").update(planId).digest("hex"),
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return plans.map(finalizePlan);
+}

package/src/ops/doctor-registry.mjs

@@ -0,0 +1,442 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+
+/**
+ * @typedef {"pass" | "warn" | "fail" | "skip" | "unknown"} DiagnosticStatus
+ * @typedef {"info" | "low" | "medium" | "high" | "critical"} DiagnosticSeverity
+ *
+ * @typedef {Object} DiagnosticEvidence
+ * @property {string} label
+ * @property {string | number | boolean} value
+ * @property {boolean} sensitive
+ *
+ * @typedef {Object} FixDescriptor
+ * @property {string} id
+ * @property {string} title
+ * @property {string} summary
+ * @property {"low" | "moderate" | "high" | "destructive"} risk
+ * @property {boolean} automatic
+ * @property {boolean} requiresProbe
+ *
+ * @typedef {Object} DiagnosticResult
+ * @property {"agentctl/diagnostic-result-v1"} schema
+ * @property {string} id
+ * @property {string} category
+ * @property {string} title
+ * @property {DiagnosticStatus} status
+ * @property {DiagnosticSeverity} severity
+ * @property {string} summary
+ * @property {number} durationMs
+ * @property {boolean} passive
+ * @property {DiagnosticEvidence[]} evidence
+ * @property {FixDescriptor[]} fixes
+ * @property {{ code: string, message: string }} [error]
+ *
+ * @typedef {Object} DoctorReport
+ * @property {"agentctl/doctor-report-v1"} schema
+ * @property {string} repository
+ * @property {string} [headSha]
+ * @property {string} generatedAt
+ * @property {boolean} activeProbe
+ * @property {Record<DiagnosticStatus, number>} summary
+ * @property {DiagnosticResult[]} results
+ * @property {string} reportHash
+ */
+
+/**
+ * Compute SHA-256 report hash for DoctorReport.
+ * @param {Omit<DoctorReport, "reportHash">} report
+ * @returns {string}
+ */
+export function computeReportHash(report) {
+  const payload = JSON.stringify({
+    schema: report.schema,
+    repository: report.repository,
+    generatedAt: report.generatedAt,
+    summary: report.summary,
+    results: report.results.map((r) => ({ id: r.id, status: r.status, summary: r.summary })),
+  });
+  return "sha256:" + createHash("sha256").update(payload).digest("hex");
+}
+
+/**
+ * Run diagnostic check suite across DAG.
+ * @param {Object} options
+ * @param {string} options.root
+ * @param {boolean} [options.activeProbe=false]
+ * @param {string[]} [options.selectedChecks]
+ * @returns {Promise<DoctorReport>}
+ */
+export async function runDoctorChecks(options = {}) {
+  const root = resolve(options.root || process.cwd());
+  const activeProbe = Boolean(options.activeProbe);
+  const _startTime = Date.now();
+
+  /** @type {DiagnosticResult[]} */
+  const results = [];
+
+  // Helper to append result
+  const addResult = (res) => {
+    results.push({
+      schema: "agentctl/diagnostic-result-v1",
+      durationMs: 0,
+      passive: !activeProbe,
+      evidence: [],
+      fixes: [],
+      ...res,
+    });
+  };
+
+  // 1. System Checks
+  // runtime.node
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split(".")[0], 10);
+  if (nodeMajor >= 20) {
+    addResult({
+      id: "runtime.node",
+      category: "System",
+      title: "Node.js Engine Version",
+      status: "pass",
+      severity: "info",
+      summary: `Node.js ${nodeVersion} satisfies runtime requirements (v20+)`,
+      evidence: [{ label: "nodeVersion", value: nodeVersion, sensitive: false }],
+    });
+  } else {
+    addResult({
+      id: "runtime.node",
+      category: "System",
+      title: "Node.js Engine Version",
+      status: "fail",
+      severity: "critical",
+      summary: `Node.js ${nodeVersion} is below required minimum v20.0.0`,
+      evidence: [{ label: "nodeVersion", value: nodeVersion, sensitive: false }],
+    });
+  }
+
+  // runtime.git
+  let gitPassed = false;
+  try {
+    const gitOut = execFileSync("git", ["--version"], { encoding: "utf-8", timeout: 5000 });
+    gitPassed = true;
+    addResult({
+      id: "runtime.git",
+      category: "System",
+      title: "Git Command Available",
+      status: "pass",
+      severity: "info",
+      summary: gitOut.trim(),
+      evidence: [{ label: "gitVersion", value: gitOut.trim(), sensitive: false }],
+    });
+  } catch (err) {
+    addResult({
+      id: "runtime.git",
+      category: "System",
+      title: "Git Command Available",
+      status: "fail",
+      severity: "critical",
+      summary: "Git executable not found or failed to run",
+      error: { code: "ENOENT", message: err.message },
+    });
+  }
+
+  // 2. Repository Checks
+
+  if (!gitPassed) {
+    addResult({
+      id: "repo.root",
+      category: "Repository",
+      title: "Repository Root Verification",
+      status: "skip",
+      severity: "info",
+      summary: "Skipped due to failed runtime.git check",
+    });
+    addResult({
+      id: "repo.dirty",
+      category: "Repository",
+      title: "Working Directory Cleanliness",
+      status: "skip",
+      severity: "info",
+      summary: "Skipped due to failed runtime.git check",
+    });
+  } else {
+    let isRepo = false;
+    let headSha = "";
+    try {
+      headSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf-8" }).trim();
+      isRepo = true;
+      addResult({
+        id: "repo.root",
+        category: "Repository",
+        title: "Repository Root Verification",
+        status: "pass",
+        severity: "info",
+        summary: `Valid repository at ${root} (HEAD: ${headSha.slice(0, 8)})`,
+        evidence: [{ label: "headSha", value: headSha, sensitive: false }],
+      });
+    } catch {
+      addResult({
+        id: "repo.root",
+        category: "Repository",
+        title: "Repository Root Verification",
+        status: "fail",
+        severity: "high",
+        summary: `Directory ${root} is not a valid Git repository`,
+      });
+    }
+
+    if (isRepo) {
+      try {
+        const statusOut = execFileSync("git", ["status", "--porcelain"], { cwd: root, encoding: "utf-8" }).trim();
+        const modifiedCount = statusOut ? statusOut.split("\n").length : 0;
+        if (modifiedCount === 0) {
+          addResult({
+            id: "repo.dirty",
+            category: "Repository",
+            title: "Working Directory Cleanliness",
+            status: "pass",
+            severity: "info",
+            summary: "Working tree is clean",
+            evidence: [{ label: "uncommittedFiles", value: 0, sensitive: false }],
+          });
+        } else {
+          addResult({
+            id: "repo.dirty",
+            category: "Repository",
+            title: "Working Directory Cleanliness",
+            status: "warn",
+            severity: "low",
+            summary: `Working tree has ${modifiedCount} uncommitted changes`,
+            evidence: [{ label: "uncommittedFiles", value: modifiedCount, sensitive: false }],
+          });
+        }
+      } catch {
+        addResult({
+          id: "repo.dirty",
+          category: "Repository",
+          title: "Working Directory Cleanliness",
+          status: "warn",
+          severity: "low",
+          summary: "Could not query git status",
+        });
+      }
+    }
+  }
+
+  // 3. Config Checks
+  const configCandidates = [
+    [".agent/config.yml", join(root, ".agent", "config.yml")],
+    [".agent/jules.yml", join(root, ".agent", "jules.yml")],
+  ];
+  const existingConfig = configCandidates.find(([, path]) => existsSync(path));
+  if (existingConfig) {
+    addResult({
+      id: "config.present",
+      category: "Config",
+      title: "Agent Configuration File",
+      status: "pass",
+      severity: "info",
+      summary: `${existingConfig[0]} exists`,
+      evidence: [{ label: "configPath", value: existingConfig[0], sensitive: false }],
+    });
+  } else {
+    addResult({
+      id: "config.present",
+      category: "Config",
+      title: "Agent Configuration File",
+      status: "warn",
+      severity: "medium",
+      summary: "Neither .agent/config.yml nor .agent/jules.yml exists",
+      fixes: [
+        {
+          id: "config.create-default",
+          title: "Create default config",
+          summary: "Initialize standard .agent/config.yml manifest",
+          risk: "low",
+          automatic: true,
+          requiresProbe: false,
+        },
+      ],
+    });
+  }
+
+  // 4. Verification Oracle Checks
+  const pkgPath = join(root, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      const testScript = pkg.scripts && pkg.scripts.test;
+      if (testScript) {
+        addResult({
+          id: "oracle.test",
+          category: "Verification",
+          title: "Test Oracle Configuration",
+          status: "pass",
+          severity: "info",
+          summary: `Test oracle script found: "npm test" -> "${testScript}"`,
+          evidence: [{ label: "testScript", value: testScript, sensitive: false }],
+        });
+      } else {
+        addResult({
+          id: "oracle.test",
+          category: "Verification",
+          title: "Test Oracle Configuration",
+          status: "warn",
+          severity: "medium",
+          summary: "package.json missing test script entry",
+        });
+      }
+    } catch {
+      addResult({
+        id: "oracle.test",
+        category: "Verification",
+        title: "Test Oracle Configuration",
+        status: "warn",
+        severity: "medium",
+        summary: "Malformed package.json file",
+      });
+    }
+  } else {
+    addResult({
+      id: "oracle.test",
+      category: "Verification",
+      title: "Test Oracle Configuration",
+      status: "pass",
+      severity: "info",
+      summary: "Non-Node workspace verified",
+    });
+  }
+
+  // 5. State & Telemetry Checks
+  const telemetryDate = new Date().toISOString().split("T")[0];
+  const telemetryHeadPath = join(root, ".agent", "state", `telemetry-${telemetryDate}.head`);
+  if (existsSync(telemetryHeadPath)) {
+    addResult({
+      id: "state.telemetry",
+      category: "State",
+      title: "Telemetry Spine Head Integrity",
+      status: "pass",
+      severity: "info",
+      summary: "Telemetry .head file present"
+    });
+  } else {
+    addResult({
+      id: "state.telemetry",
+      category: "State",
+      title: "Telemetry Spine Head Integrity",
+      status: "warn",
+      severity: "low",
+      summary: "Telemetry .head file missing; can be rebuilt from tail log",
+      fixes: [
+        {
+          id: "state.rebuild-head",
+          title: "Rebuild telemetry head",
+          summary: "Recompute .head SHA-256 pointer from tail log",
+          risk: "low",
+          automatic: true,
+          requiresProbe: false,
+        },
+      ],
+    });
+  }
+
+  // 6. VFS Locks Check
+  const locksDir = join(root, ".agent", "state", "locks");
+  let activeLockCount = 0;
+  let lockInspectionFailed = false;
+  try {
+    if (existsSync(locksDir)) {
+      const lockFiles = readdirSync(locksDir).filter((f) => f.endsWith(".json"));
+      activeLockCount = lockFiles.length;
+    }
+  } catch (_) {
+    lockInspectionFailed = true;
+    addResult({
+      id: "locks.active",
+      category: "State",
+      title: "VFS Active Locks",
+      status: "unknown",
+      severity: "medium",
+      summary: "Could not inspect VFS lock directory",
+    });
+  }
+  if (!lockInspectionFailed && activeLockCount === 0) {
+    addResult({
+      id: "locks.active",
+      category: "State",
+      title: "VFS Active Locks",
+      status: "pass",
+      severity: "info",
+      summary: "No active VFS locks present",
+    });
+  } else if (!lockInspectionFailed) {
+    addResult({
+      id: "locks.active",
+      category: "State",
+      title: "VFS Active Locks",
+      status: "warn",
+      severity: "medium",
+      summary: `${activeLockCount} active VFS lock(s) held`,
+      evidence: [{ label: "lockCount", value: activeLockCount, sensitive: false }],
+      fixes: [
+        {
+          id: "locks.prune-stale",
+          title: "Prune stale locks",
+          summary: "Remove locks owned by dead processes",
+          risk: "low",
+          automatic: true,
+          requiresProbe: false,
+        },
+      ],
+    });
+  }
+
+  // 7. Jules Provider Key Check
+  const hasApiKey = Boolean(process.env.JULES_API_KEY || process.env.GEMINI_API_KEY);
+  if (hasApiKey) {
+    addResult({
+      id: "provider.key",
+      category: "Jules",
+      title: "Jules Provider API Key",
+      status: "pass",
+      severity: "info",
+      summary: "API key environment variable detected",
+      evidence: [{ label: "keyConfigured", value: true, sensitive: false }],
+    });
+  } else {
+    addResult({
+      id: "provider.key",
+      category: "Jules",
+      title: "Jules Provider API Key",
+      status: "warn",
+      severity: "high",
+      summary: "Neither JULES_API_KEY nor GEMINI_API_KEY environment variable is set",
+      evidence: [{ label: "keyConfigured", value: false, sensitive: false }],
+    });
+  }
+
+  // Summarize count by status
+  const summary = { pass: 0, warn: 0, fail: 0, skip: 0, unknown: 0 };
+  for (const r of results) {
+    summary[r.status] = (summary[r.status] || 0) + 1;
+  }
+
+  const baseReport = {
+    schema: /** @type {const} */ ("agentctl/doctor-report-v1"),
+    repository: root,
+    generatedAt: new Date().toISOString(),
+    activeProbe,
+    summary,
+    results,
+  };
+
+  const reportHash = computeReportHash(baseReport);
+  /** @type {DoctorReport} */
+  const report = {
+    ...baseReport,
+    reportHash,
+  };
+
+  return report;
+}