jules-orchestrator-kit 0.29.1 → 0.31.0

package/src/ops/checkpoint.mjs

@@ -0,0 +1,167 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { git, changedFiles, diffText } from "../git.mjs";
+import { resolveRoot } from "../config.mjs";
+
+export class CheckpointError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = "CheckpointError";
+    this.code = opts.code || 1;
+  }
+}
+
+/**
+ * Ensures checkpoint storage directory exists.
+ */
+export function getCheckpointDir(root = resolveRoot()) {
+  const dir = join(root, ".agent", "state", "checkpoints");
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (_) {}
+  return dir;
+}
+
+/**
+ * Creates an atomic pre-flight snapshot of the repository state before an agent task runs.
+ * @param {string} sessionId
+ * @param {object} options
+ * @returns {object} Checkpoint metadata
+ */
+export function createCheckpoint(sessionId = `session-${Date.now()}`, options = {}) {
+  const root = options.root || resolveRoot();
+  const dir = getCheckpointDir(root);
+
+  let headSha = "";
+  try {
+    headSha = git(["rev-parse", "HEAD"], { cwd: root, ignoreError: true }).trim();
+  } catch (_) {}
+
+  let branch = "";
+  try {
+    branch = git(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: root, ignoreError: true }).trim();
+  } catch (_) {}
+
+  const uncommittedFiles = changedFiles(root, branch || "main", "working-tree");
+  const diffContent = diffText(root, branch || "main", "working-tree");
+
+  const snapshot = {
+    version: 1,
+    id: sessionId,
+    timestamp: new Date().toISOString(),
+    headSha,
+    branch,
+    uncommittedFiles,
+    diffContent,
+  };
+
+  const snapshotPath = join(dir, `${sessionId}.json`);
+  writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), "utf-8");
+
+  // Keep last 10 checkpoints
+  pruneCheckpoints(root, 10);
+
+  return snapshot;
+}
+
+/**
+ * Restores working tree and git state to a previously saved checkpoint.
+ * @param {string} sessionId or '--latest'
+ * @param {object} options
+ * @returns {object} Restore result summary
+ */
+export function restoreCheckpoint(sessionId = "--latest", options = {}) {
+  const root = options.root || resolveRoot();
+  const dir = getCheckpointDir(root);
+
+  let targetId = sessionId;
+  if (!targetId || targetId === "--latest" || targetId === "latest") {
+    const list = listCheckpoints(root);
+    if (list.length === 0) {
+      throw new CheckpointError("No checkpoints found to restore.");
+    }
+    targetId = list[0].id;
+  }
+
+  const snapshotFile = join(dir, `${targetId}.json`);
+  if (!existsSync(snapshotFile)) {
+    throw new CheckpointError(`Checkpoint snapshot file not found for session '${targetId}'.`);
+  }
+
+  let snapshot;
+  try {
+    snapshot = JSON.parse(readFileSync(snapshotFile, "utf-8"));
+  } catch (err) {
+    throw new CheckpointError(`Corrupted checkpoint file '${targetId}.json': ${err.message}`);
+  }
+
+  if (snapshot.headSha) {
+    try {
+      git(["reset", "--hard", snapshot.headSha], { cwd: root, ignoreError: true });
+    } catch (err) {
+      throw new CheckpointError(`Failed git reset --hard ${snapshot.headSha}: ${err.message}`);
+    }
+  }
+
+  // Clean untracked files generated during session
+  try {
+    git(["clean", "-fd"], { cwd: root, ignoreError: true });
+  } catch (_) {}
+
+  return {
+    ok: true,
+    id: snapshot.id,
+    headSha: snapshot.headSha,
+    restoredAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Lists all active checkpoints ordered by timestamp descending.
+ */
+export function listCheckpoints(root = resolveRoot()) {
+  const dir = getCheckpointDir(root);
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  const items = [];
+
+  for (const file of files) {
+    const filePath = join(dir, file);
+    try {
+      const data = JSON.parse(readFileSync(filePath, "utf-8"));
+      items.push({
+        id: data.id || file.replace(/\.json$/, ""),
+        timestamp: data.timestamp || new Date(statSync(filePath).mtimeMs).toISOString(),
+        headSha: data.headSha || "",
+        branch: data.branch || "",
+        filePath,
+      });
+    } catch (_) {}
+  }
+
+  items.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+  return items;
+}
+
+/**
+ * Prunes checkpoints keeping only the most recent N sessions.
+ */
+export function pruneCheckpoints(root = resolveRoot(), maxRetention = 10) {
+  const list = listCheckpoints(root);
+  if (list.length <= maxRetention) return 0;
+
+  const toRemove = list.slice(maxRetention);
+  let prunedCount = 0;
+
+  for (const item of toRemove) {
+    try {
+      if (existsSync(item.filePath)) {
+        rmSync(item.filePath, { force: true });
+        prunedCount++;
+      }
+    } catch (_) {}
+  }
+
+  return prunedCount;
+}

package/src/ops/command-registry.mjs

@@ -0,0 +1,274 @@
+/**
+ * @typedef {"low" | "moderate" | "high" | "destructive"} RiskLevel
+ * @typedef {"Create" | "Inspect" | "Operate" | "Repair" | "Configure"} CommandCategory
+ *
+ * @typedef {Object} CommandFlag
+ * @property {string} name
+ * @property {"boolean" | "string"} type
+ * @property {string} description
+ * @property {any} [default]
+ *
+ * @typedef {Object} CommandDescriptor
+ * @property {string} id
+ * @property {string[]} path
+ * @property {string} title
+ * @property {string} description
+ * @property {CommandCategory} category
+ * @property {boolean} mutates
+ * @property {RiskLevel} risk
+ * @property {"never" | "optional" | "authoring-auto"} interactive
+ * @property {boolean} requiresRepository
+ * @property {string[]} shortcuts
+ * @property {string[]} examples
+ * @property {CommandFlag[]} flags
+ */
+
+/** @type {CommandDescriptor[]} */
+export const COMMAND_REGISTRY = [
+  {
+    id: "doctor",
+    path: ["doctor"],
+    title: "doctor",
+    description: "Run repository diagnostics and guided fixes",
+    category: "Repair",
+    mutates: false,
+    risk: "low",
+    interactive: "optional",
+    requiresRepository: true,
+    shortcuts: ["d", "doc"],
+    examples: [
+      "agentctl doctor",
+      "agentctl doctor --interactive",
+      "agentctl doctor --fix safe --yes",
+      "agentctl doctor --json",
+    ],
+    flags: [
+      { name: "interactive", type: "boolean", description: "Open full-screen diagnostic matrix" },
+      { name: "fix", type: "string", description: "Apply fix classes (e.g. 'safe' or check IDs)" },
+      { name: "probe", type: "boolean", description: "Enable active network/execution probes" },
+      { name: "json", type: "boolean", description: "Output structured JSON doctor report" },
+      { name: "yes", type: "boolean", description: "Bypass interactive confirmation for safe fixes" },
+    ],
+  },
+  {
+    id: "queue",
+    path: ["queue"],
+    title: "queue",
+    description: "Browse and manage canonical task queue",
+    category: "Operate",
+    mutates: false,
+    risk: "low",
+    interactive: "optional",
+    requiresRepository: true,
+    shortcuts: ["q"],
+    examples: [
+      "agentctl queue",
+      "agentctl queue --interactive",
+      "agentctl queue --json",
+    ],
+    flags: [
+      { name: "interactive", type: "boolean", description: "Open full-screen queue dashboard" },
+      { name: "json", type: "boolean", description: "Output structured JSON queue snapshot" },
+      { name: "limit", type: "string", description: "Maximum tasks to include in snapshot" },
+    ],
+  },
+  {
+    id: "swarm",
+    path: ["swarm"],
+    title: "swarm",
+    description: "Inspect active worker slots and concurrency scheduler",
+    category: "Operate",
+    mutates: false,
+    risk: "low",
+    interactive: "optional",
+    requiresRepository: true,
+    shortcuts: ["s"],
+    examples: [
+      "agentctl swarm",
+      "agentctl swarm --interactive",
+      "agentctl swarm --json",
+    ],
+    flags: [
+      { name: "interactive", type: "boolean", description: "Open full-screen swarm dashboard" },
+      { name: "json", type: "boolean", description: "Output structured JSON swarm snapshot" },
+    ],
+  },
+  {
+    id: "task-create",
+    path: ["task", "create"],
+    title: "task create",
+    description: "Author a scoped, falsifiable task",
+    category: "Create",
+    mutates: true,
+    risk: "moderate",
+    interactive: "authoring-auto",
+    requiresRepository: true,
+    shortcuts: ["tc", "create"],
+    examples: [
+      'agentctl task create --title "Fix webhook" --prompt "Add retry handling" --verify-cmd "npm test"',
+      "agentctl task create --interactive",
+    ],
+    flags: [
+      { name: "title", type: "string", description: "Short title for task" },
+      { name: "prompt", type: "string", description: "Detailed task instructions" },
+      { name: "verify-cmd", type: "string", description: "Verification command" },
+      { name: "interactive", type: "boolean", description: "Launch interactive task wizard" },
+    ],
+  },
+  {
+    id: "task-optimize",
+    path: ["task", "optimize"],
+    title: "task optimize",
+    description: "Score task prompt falsifiability and static path resolution",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["to", "optimize"],
+    examples: [
+      'agentctl task optimize "Fix JWT token expiry in src/auth.js"',
+      'agentctl task optimize "Refactor auth" --fix',
+      'agentctl task optimize --file prompt.txt --json',
+    ],
+    flags: [
+      { name: "fix", type: "boolean", description: "Synthesize optimized markdown task envelope" },
+      { name: "json", type: "boolean", description: "Output structured JSON prompt evaluation" },
+      { name: "file", type: "string", description: "Path to text file containing task prompt" },
+      { name: "dir", type: "string", description: "Target repository directory root" },
+    ],
+  },
+  {
+    id: "init",
+    path: ["init"],
+    title: "init",
+    description: "Configure Stack Oracle and Jules provider manifests",
+    category: "Configure",
+    mutates: true,
+    risk: "moderate",
+    interactive: "optional",
+    requiresRepository: true,
+    shortcuts: ["i"],
+    examples: [
+      "agentctl init",
+      "agentctl init --interactive",
+      "agentctl init --tier pro --yes",
+    ],
+    flags: [
+      { name: "tier", type: "string", description: "Target configuration tier (free, pro, enterprise)" },
+      { name: "interactive", type: "boolean", description: "Launch interactive onboarding wizard" },
+      { name: "yes", type: "boolean", description: "Accept auto-detected Stack Oracle defaults" },
+    ],
+  },
+  {
+    id: "dashboard",
+    path: ["dashboard"],
+    title: "dashboard",
+    description: "Start local web dashboard server",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: true,
+    shortcuts: ["dash"],
+    examples: [
+      "agentctl dashboard",
+      "agentctl dashboard --port 3000",
+    ],
+    flags: [
+      { name: "port", type: "string", description: "HTTP server port (default 3000)" },
+      { name: "host", type: "string", description: "Bind host address (default 127.0.0.1)" },
+    ],
+  },
+  {
+    id: "status",
+    path: ["status"],
+    title: "status",
+    description: "Show operating status and health summary",
+    category: "Inspect",
+    mutates: false,
+    risk: "low",
+    interactive: "never",
+    requiresRepository: false,
+    shortcuts: ["st"],
+    examples: [
+      "agentctl status",
+      "agentctl status --json",
+    ],
+    flags: [
+      { name: "json", type: "boolean", description: "Output status in JSON format" },
+    ],
+  },
+];
+
+/**
+ * Lookup command descriptor by ID, command path, or shortcut alias.
+ * @param {string} idOrAlias
+ * @returns {CommandDescriptor | null}
+ */
+export function getCommandDescriptor(idOrAlias) {
+  if (!idOrAlias) return null;
+  const target = String(idOrAlias).trim().toLowerCase();
+
+  return (
+    COMMAND_REGISTRY.find((cmd) => {
+      if (cmd.id.toLowerCase() === target) return true;
+      if (cmd.path.join(" ").toLowerCase() === target) return true;
+      if (cmd.shortcuts.some((s) => s.toLowerCase() === target)) return true;
+      return false;
+    }) || null
+  );
+}
+
+/**
+ * List commands filtered by category.
+ * @param {CommandCategory} [category]
+ * @returns {CommandDescriptor[]}
+ */
+export function listCommandsByCategory(category) {
+  if (!category) return COMMAND_REGISTRY;
+  return COMMAND_REGISTRY.filter((cmd) => cmd.category === category);
+}
+
+/**
+ * Format clean CLI --help text for a command descriptor.
+ * @param {CommandDescriptor} descriptor
+ * @returns {string}
+ */
+export function formatCommandHelp(descriptor) {
+  const lines = [];
+  lines.push(`Usage: agentctl ${descriptor.path.join(" ")} [flags]`);
+  lines.push("");
+  lines.push(`Description: ${descriptor.description}`);
+  lines.push(`Category:    ${descriptor.category}`);
+  lines.push(`Risk Tier:   ${descriptor.risk.toUpperCase()}`);
+  lines.push("");
+
+  if (descriptor.flags && descriptor.flags.length > 0) {
+    lines.push("Flags:");
+    for (const flag of descriptor.flags) {
+      lines.push(`  --${flag.name.padEnd(16)} ${flag.description}`);
+    }
+    lines.push("");
+  }
+
+  if (descriptor.examples && descriptor.examples.length > 0) {
+    lines.push("Examples:");
+    for (const ex of descriptor.examples) {
+      lines.push(`  $ ${ex}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format JSON representation of full command registry.
+ * @returns {{ ok: true, commands: CommandDescriptor[] }}
+ */
+export function formatRegistryJson() {
+  return {
+    ok: true,
+    commands: COMMAND_REGISTRY,
+  };
+}

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);
+}