@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/kata/commands.ts

@@ -0,0 +1,355 @@
+/**
+ * Kata Command — /kata
+ *
+ * One command, one wizard. Routes to smart entry or status.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { deriveState } from "./state.js";
+import { KataDashboardOverlay } from "./dashboard-overlay.js";
+import { showSmartEntry, showQueue, showDiscuss } from "./guided-flow.js";
+import { startAuto, stopAuto, isAutoActive, isAutoPaused } from "./auto.js";
+import {
+  getGlobalKataPreferencesPath,
+  getLegacyGlobalKataPreferencesPath,
+  getProjectKataPreferencesPath,
+  loadGlobalKataPreferences,
+  loadProjectKataPreferences,
+  loadEffectiveKataPreferences,
+  resolveAllSkillReferences,
+} from "./preferences.js";
+import { loadFile, saveFile } from "./files.js";
+import {
+  formatDoctorIssuesForPrompt,
+  formatDoctorReport,
+  runKataDoctor,
+  selectDoctorScope,
+  filterDoctorIssues,
+} from "./doctor.js";
+import { loadPrompt } from "./prompt-loader.js";
+
+function dispatchDoctorHeal(
+  pi: ExtensionAPI,
+  scope: string | undefined,
+  reportText: string,
+  structuredIssues: string,
+): void {
+  const workflowPath =
+    process.env.KATA_WORKFLOW_PATH ??
+    join(process.env.HOME ?? "~", ".kata-cli", "KATA-WORKFLOW.md");
+  const workflow = readFileSync(workflowPath, "utf-8");
+  const prompt = loadPrompt("doctor-heal", {
+    doctorSummary: reportText,
+    structuredIssues,
+    scopeLabel: scope ?? "active milestone / blocking scope",
+    doctorCommandSuffix: scope ? ` ${scope}` : "",
+  });
+
+  const content = `Read the following Kata workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${prompt}`;
+
+  pi.sendMessage(
+    { customType: "kata-doctor-heal", content, display: false },
+    { triggerTurn: true },
+  );
+}
+
+export function registerKataCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("kata", {
+    description:
+      "Kata — Kata Workflow: /kata auto|stop|status|queue|prefs|doctor",
+
+    getArgumentCompletions: (prefix: string) => {
+      const subcommands = [
+        "auto",
+        "stop",
+        "status",
+        "queue",
+        "discuss",
+        "prefs",
+        "doctor",
+      ];
+      const parts = prefix.trim().split(/\s+/);
+
+      if (parts.length <= 1) {
+        return subcommands
+          .filter((cmd) => cmd.startsWith(parts[0] ?? ""))
+          .map((cmd) => ({ value: cmd, label: cmd }));
+      }
+
+      if (parts[0] === "auto" && parts.length <= 2) {
+        const flagPrefix = parts[1] ?? "";
+        return ["--verbose"]
+          .filter((f) => f.startsWith(flagPrefix))
+          .map((f) => ({ value: `auto ${f}`, label: f }));
+      }
+
+      if (parts[0] === "prefs" && parts.length <= 2) {
+        const subPrefix = parts[1] ?? "";
+        return ["global", "project", "status"]
+          .filter((cmd) => cmd.startsWith(subPrefix))
+          .map((cmd) => ({ value: `prefs ${cmd}`, label: cmd }));
+      }
+
+      if (parts[0] === "doctor") {
+        const modePrefix = parts[1] ?? "";
+        const modes = ["fix", "heal", "audit"];
+
+        if (parts.length <= 2) {
+          return modes
+            .filter((cmd) => cmd.startsWith(modePrefix))
+            .map((cmd) => ({ value: `doctor ${cmd}`, label: cmd }));
+        }
+
+        return [];
+      }
+
+      return [];
+    },
+
+    async handler(args: string, ctx: ExtensionCommandContext) {
+      const trimmed = (typeof args === "string" ? args : "").trim();
+
+      if (trimmed === "status") {
+        await handleStatus(ctx);
+        return;
+      }
+
+      if (trimmed === "prefs" || trimmed.startsWith("prefs ")) {
+        await handlePrefs(trimmed.replace(/^prefs\s*/, "").trim(), ctx);
+        return;
+      }
+
+      if (trimmed === "doctor" || trimmed.startsWith("doctor ")) {
+        await handleDoctor(trimmed.replace(/^doctor\s*/, "").trim(), ctx, pi);
+        return;
+      }
+
+      if (trimmed === "auto" || trimmed.startsWith("auto ")) {
+        const verboseMode = trimmed.includes("--verbose");
+        await startAuto(ctx, pi, process.cwd(), verboseMode);
+        return;
+      }
+
+      if (trimmed === "stop") {
+        if (!isAutoActive() && !isAutoPaused()) {
+          ctx.ui.notify("Auto-mode is not running.", "info");
+          return;
+        }
+        await stopAuto(ctx, pi);
+        return;
+      }
+
+      if (trimmed === "queue") {
+        await showQueue(ctx, pi, process.cwd());
+        return;
+      }
+
+      if (trimmed === "discuss") {
+        await showDiscuss(ctx, pi, process.cwd());
+        return;
+      }
+
+      if (trimmed === "") {
+        await showSmartEntry(ctx, pi, process.cwd());
+        return;
+      }
+
+      ctx.ui.notify(
+        `Unknown: /kata ${trimmed}. Use /kata, /kata auto, /kata stop, /kata status, /kata queue, /kata discuss, /kata prefs [global|project|status], or /kata doctor [audit|fix|heal] [M###/S##].`,
+        "warning",
+      );
+    },
+  });
+}
+
+async function handleStatus(ctx: ExtensionCommandContext): Promise<void> {
+  const basePath = process.cwd();
+  const state = await deriveState(basePath);
+
+  if (state.registry.length === 0) {
+    ctx.ui.notify("No Kata milestones found. Run /kata to start.", "info");
+    return;
+  }
+
+  await ctx.ui.custom<void>(
+    (tui, theme, _kb, done) => {
+      return new KataDashboardOverlay(tui, theme, () => done());
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        width: "70%",
+        minWidth: 60,
+        maxHeight: "90%",
+        anchor: "center",
+      },
+    },
+  );
+}
+
+export async function fireStatusViaCommand(
+  ctx: import("@mariozechner/pi-coding-agent").ExtensionContext,
+): Promise<void> {
+  await handleStatus(ctx as ExtensionCommandContext);
+}
+
+async function handlePrefs(
+  args: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const trimmed = args.trim();
+
+  if (trimmed === "" || trimmed === "global") {
+    await ensurePreferencesFile(getGlobalKataPreferencesPath(), ctx, "global");
+    return;
+  }
+
+  if (trimmed === "project") {
+    await ensurePreferencesFile(getProjectKataPreferencesPath(), ctx, "project");
+    return;
+  }
+
+  if (trimmed === "status") {
+    const globalPrefs = loadGlobalKataPreferences();
+    const projectPrefs = loadProjectKataPreferences();
+    const canonicalGlobal = getGlobalKataPreferencesPath();
+    const legacyGlobal = getLegacyGlobalKataPreferencesPath();
+    const globalStatus = globalPrefs
+      ? `present: ${globalPrefs.path}${globalPrefs.path === legacyGlobal ? " (legacy fallback)" : ""}`
+      : `missing: ${canonicalGlobal}`;
+    const projectStatus = projectPrefs
+      ? `present: ${projectPrefs.path}`
+      : `missing: ${getProjectKataPreferencesPath()}`;
+
+    const lines = [
+      `Kata skill prefs — global ${globalStatus}; project ${projectStatus}`,
+    ];
+
+    const effective = loadEffectiveKataPreferences();
+    let hasUnresolved = false;
+    if (effective) {
+      const report = resolveAllSkillReferences(
+        effective.preferences,
+        process.cwd(),
+      );
+      const resolved = [...report.resolutions.values()].filter(
+        (r) => r.method !== "unresolved",
+      );
+      hasUnresolved = report.warnings.length > 0;
+      if (resolved.length > 0 || hasUnresolved) {
+        lines.push(
+          `Skills: ${resolved.length} resolved, ${report.warnings.length} unresolved`,
+        );
+      }
+      if (hasUnresolved) {
+        lines.push(`Unresolved: ${report.warnings.join(", ")}`);
+      }
+    }
+
+    ctx.ui.notify(lines.join("\n"), hasUnresolved ? "warning" : "info");
+    return;
+  }
+
+  ctx.ui.notify("Usage: /kata prefs [global|project|status]", "info");
+}
+
+async function handleDoctor(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  const trimmed = args.trim();
+  const parts = trimmed ? trimmed.split(/\s+/) : [];
+  const mode =
+    parts[0] === "fix" || parts[0] === "heal" || parts[0] === "audit"
+      ? parts[0]
+      : "doctor";
+  const requestedScope = mode === "doctor" ? parts[0] : parts[1];
+  const scope = await selectDoctorScope(process.cwd(), requestedScope);
+  const effectiveScope = mode === "audit" ? requestedScope : scope;
+  const report = await runKataDoctor(process.cwd(), {
+    fix: mode === "fix" || mode === "heal",
+    scope: effectiveScope,
+  });
+
+  const reportText = formatDoctorReport(report, {
+    scope: effectiveScope,
+    includeWarnings: mode === "audit",
+    maxIssues: mode === "audit" ? 50 : 12,
+    title:
+      mode === "audit"
+        ? "Kata doctor audit."
+        : mode === "heal"
+          ? "Kata doctor heal prep."
+          : undefined,
+  });
+
+  ctx.ui.notify(reportText, report.ok ? "info" : "warning");
+
+  if (mode === "heal") {
+    const unresolved = filterDoctorIssues(report.issues, {
+      scope: effectiveScope,
+      includeWarnings: true,
+    });
+    const actionable = unresolved.filter(
+      (issue) =>
+        issue.severity === "error" ||
+        issue.code === "all_tasks_done_missing_slice_uat" ||
+        issue.code === "slice_checked_missing_uat",
+    );
+    if (actionable.length === 0) {
+      ctx.ui.notify(
+        "Doctor heal found nothing actionable to hand off to the LLM.",
+        "info",
+      );
+      return;
+    }
+
+    const structuredIssues = formatDoctorIssuesForPrompt(actionable);
+    dispatchDoctorHeal(pi, effectiveScope, reportText, structuredIssues);
+    ctx.ui.notify(
+      `Doctor heal dispatched ${actionable.length} issue(s) to the LLM.`,
+      "info",
+    );
+  }
+}
+
+async function ensurePreferencesFile(
+  path: string,
+  ctx: ExtensionCommandContext,
+  scope: "global" | "project",
+): Promise<void> {
+  if (!existsSync(path)) {
+    const template = await loadFile(
+      join(
+        dirname(fileURLToPath(import.meta.url)),
+        "templates",
+        "preferences.md",
+      ),
+    );
+    if (!template) {
+      ctx.ui.notify("Could not load Kata preferences template.", "error");
+      return;
+    }
+    await saveFile(path, template);
+    ctx.ui.notify(`Created ${scope} Kata skill preferences at ${path}`, "info");
+  } else {
+    ctx.ui.notify(
+      `Using existing ${scope} Kata skill preferences at ${path}`,
+      "info",
+    );
+  }
+
+  await ctx.waitForIdle();
+  await ctx.reload();
+  ctx.ui.notify(
+    `Edit ${path} to update ${scope} Kata skill preferences.`,
+    "info",
+  );
+}

package/src/resources/extensions/kata/crash-recovery.ts

@@ -0,0 +1,85 @@
+/**
+ * Kata Crash Recovery
+ *
+ * Detects interrupted auto-mode sessions via a lock file.
+ * Written on auto-start, updated on each unit dispatch, deleted on clean stop.
+ * If the lock file exists on next startup, the previous session crashed.
+ *
+ * The lock records the pi session file path so crash recovery can read the
+ * surviving JSONL (pi appends entries incrementally via appendFileSync,
+ * so the file on disk reflects every tool call up to the crash point).
+ */
+
+import { writeFileSync, readFileSync, unlinkSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { kataRoot } from "./paths.js";
+
+const LOCK_FILE = "auto.lock";
+
+export interface LockData {
+  pid: number;
+  startedAt: string;
+  unitType: string;
+  unitId: string;
+  unitStartedAt: string;
+  completedUnits: number;
+  /** Path to the pi session JSONL file that was active when this unit started. */
+  sessionFile?: string;
+}
+
+function lockPath(basePath: string): string {
+  return join(kataRoot(basePath), LOCK_FILE);
+}
+
+/** Write or update the lock file with current auto-mode state. */
+export function writeLock(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  completedUnits: number,
+  sessionFile?: string,
+): void {
+  try {
+    const data: LockData = {
+      pid: process.pid,
+      startedAt: new Date().toISOString(),
+      unitType,
+      unitId,
+      unitStartedAt: new Date().toISOString(),
+      completedUnits,
+      sessionFile,
+    };
+    writeFileSync(lockPath(basePath), JSON.stringify(data, null, 2), "utf-8");
+  } catch { /* non-fatal */ }
+}
+
+/** Remove the lock file on clean stop. */
+export function clearLock(basePath: string): void {
+  try {
+    const p = lockPath(basePath);
+    if (existsSync(p)) unlinkSync(p);
+  } catch { /* non-fatal */ }
+}
+
+/** Check if a crash lock exists and return its data. */
+export function readCrashLock(basePath: string): LockData | null {
+  try {
+    const p = lockPath(basePath);
+    if (!existsSync(p)) return null;
+    const raw = readFileSync(p, "utf-8");
+    return JSON.parse(raw) as LockData;
+  } catch {
+    return null;
+  }
+}
+
+/** Format crash info for display or injection into a prompt. */
+export function formatCrashInfo(lock: LockData): string {
+  return [
+    `Previous auto-mode session was interrupted.`,
+    `  Was executing: ${lock.unitType} (${lock.unitId})`,
+    `  Started at: ${lock.unitStartedAt}`,
+    `  Units completed before crash: ${lock.completedUnits}`,
+    `  PID: ${lock.pid}`,
+  ].join("\n");
+}