@kata-sh/cli 0.1.0 → 0.1.1

package/src/resources/extensions/kata/workspace-index.ts

@@ -0,0 +1,203 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { loadFile, parsePlan, parseRoadmap } from "./files.ts";
+import {
+  milestonesDir,
+  resolveMilestoneFile,
+  resolveSliceFile,
+  resolveSlicePath,
+  resolveTaskFile,
+  resolveTasksDir,
+} from "./paths.ts";
+import { deriveState } from "./state.ts";
+import { type ValidationIssue, validateCompleteBoundary, validatePlanBoundary } from "./observability-validator.ts";
+import { getSliceBranchName } from "./worktree.ts";
+
+export interface WorkspaceTaskTarget {
+  id: string;
+  title: string;
+  done: boolean;
+  planPath?: string;
+  summaryPath?: string;
+}
+
+export interface WorkspaceSliceTarget {
+  id: string;
+  title: string;
+  done: boolean;
+  planPath?: string;
+  summaryPath?: string;
+  uatPath?: string;
+  tasksDir?: string;
+  branch?: string;
+  tasks: WorkspaceTaskTarget[];
+}
+
+export interface WorkspaceMilestoneTarget {
+  id: string;
+  title: string;
+  roadmapPath?: string;
+  slices: WorkspaceSliceTarget[];
+}
+
+export interface WorkspaceScopeTarget {
+  scope: string;
+  label: string;
+  kind: "project" | "milestone" | "slice" | "task";
+}
+
+export interface KataWorkspaceIndex {
+  milestones: WorkspaceMilestoneTarget[];
+  active: {
+    milestoneId?: string;
+    sliceId?: string;
+    taskId?: string;
+    phase: string;
+  };
+  scopes: WorkspaceScopeTarget[];
+  validationIssues: ValidationIssue[];
+}
+
+function findMilestoneIds(basePath: string): string[] {
+  try {
+    return readdirSync(milestonesDir(basePath), { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => {
+        const match = entry.name.match(/^(M\d+)/);
+        return match ? match[1] : entry.name;
+      })
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function titleFromRoadmapHeader(content: string, fallbackId: string): string {
+  const roadmap = parseRoadmap(content);
+  return roadmap.title.replace(/^M\d+[^:]*:\s*/, "") || fallbackId;
+}
+
+async function indexSlice(basePath: string, milestoneId: string, sliceId: string, fallbackTitle: string, done: boolean): Promise<WorkspaceSliceTarget> {
+  const planPath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN") ?? undefined;
+  const summaryPath = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY") ?? undefined;
+  const uatPath = resolveSliceFile(basePath, milestoneId, sliceId, "UAT") ?? undefined;
+  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId) ?? undefined;
+
+  const tasks: WorkspaceTaskTarget[] = [];
+  let title = fallbackTitle;
+
+  if (planPath) {
+    const content = await loadFile(planPath);
+    if (content) {
+      const plan = parsePlan(content);
+      title = plan.title || fallbackTitle;
+      for (const task of plan.tasks) {
+        tasks.push({
+          id: task.id,
+          title: task.title,
+          done: task.done,
+          planPath: resolveTaskFile(basePath, milestoneId, sliceId, task.id, "PLAN") ?? undefined,
+          summaryPath: resolveTaskFile(basePath, milestoneId, sliceId, task.id, "SUMMARY") ?? undefined,
+        });
+      }
+    }
+  }
+
+  return {
+    id: sliceId,
+    title,
+    done,
+    planPath,
+    summaryPath,
+    uatPath,
+    tasksDir,
+    branch: getSliceBranchName(milestoneId, sliceId),
+    tasks,
+  };
+}
+
+export async function indexWorkspace(basePath: string): Promise<KataWorkspaceIndex> {
+  const milestoneIds = findMilestoneIds(basePath);
+  const milestones: WorkspaceMilestoneTarget[] = [];
+  const validationIssues: ValidationIssue[] = [];
+
+  for (const milestoneId of milestoneIds) {
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP") ?? undefined;
+    let title = milestoneId;
+    const slices: WorkspaceSliceTarget[] = [];
+
+    if (roadmapPath) {
+      const roadmapContent = await loadFile(roadmapPath);
+      if (roadmapContent) {
+        const roadmap = parseRoadmap(roadmapContent);
+        title = titleFromRoadmapHeader(roadmapContent, milestoneId);
+        for (const slice of roadmap.slices) {
+          const indexedSlice = await indexSlice(basePath, milestoneId, slice.id, slice.title, slice.done);
+          slices.push(indexedSlice);
+          validationIssues.push(...await validatePlanBoundary(basePath, milestoneId, slice.id));
+          validationIssues.push(...await validateCompleteBoundary(basePath, milestoneId, slice.id));
+        }
+      }
+    }
+
+    milestones.push({ id: milestoneId, title, roadmapPath, slices });
+  }
+
+  const state = await deriveState(basePath);
+  const active = {
+    milestoneId: state.activeMilestone?.id,
+    sliceId: state.activeSlice?.id,
+    taskId: state.activeTask?.id,
+    phase: state.phase,
+  };
+
+  const scopes: WorkspaceScopeTarget[] = [{ scope: "project", label: "project", kind: "project" }];
+  for (const milestone of milestones) {
+    scopes.push({ scope: milestone.id, label: `${milestone.id}: ${milestone.title}`, kind: "milestone" });
+    for (const slice of milestone.slices) {
+      scopes.push({ scope: `${milestone.id}/${slice.id}`, label: `${milestone.id}/${slice.id}: ${slice.title}`, kind: "slice" });
+      for (const task of slice.tasks) {
+        scopes.push({
+          scope: `${milestone.id}/${slice.id}/${task.id}`,
+          label: `${milestone.id}/${slice.id}/${task.id}: ${task.title}`,
+          kind: "task",
+        });
+      }
+    }
+  }
+
+  return { milestones, active, scopes, validationIssues };
+}
+
+export async function listDoctorScopeSuggestions(basePath: string): Promise<Array<{ value: string; label: string }>> {
+  const index = await indexWorkspace(basePath);
+  const activeSliceScope = index.active.milestoneId && index.active.sliceId
+    ? `${index.active.milestoneId}/${index.active.sliceId}`
+    : null;
+
+  const ordered = [...index.scopes].filter(scope => scope.kind !== "project");
+  ordered.sort((a, b) => {
+    if (activeSliceScope && a.scope === activeSliceScope) return -1;
+    if (activeSliceScope && b.scope === activeSliceScope) return 1;
+    return a.scope.localeCompare(b.scope);
+  });
+
+  return ordered.map(scope => ({ value: scope.scope, label: scope.label }));
+}
+
+export async function getSuggestedNextCommands(basePath: string): Promise<string[]> {
+  const index = await indexWorkspace(basePath);
+  const scope = index.active.milestoneId && index.active.sliceId
+    ? `${index.active.milestoneId}/${index.active.sliceId}`
+    : index.active.milestoneId;
+
+  const commands = new Set<string>();
+  if (index.active.phase === "planning") commands.add("/kata");
+  if (index.active.phase === "executing" || index.active.phase === "summarizing") commands.add("/kata auto");
+  if (scope) commands.add(`/kata doctor ${scope}`);
+  if (scope) commands.add(`/kata doctor fix ${scope}`);
+  if (index.validationIssues.length > 0 && scope) commands.add(`/kata doctor audit ${scope}`);
+  commands.add("/kata status");
+  return [...commands];
+}

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

@@ -0,0 +1,182 @@
+/**
+ * Kata Slice Branch Management
+ *
+ * Simple branch-per-slice workflow. No worktrees, no registry.
+ * Runtime state (metrics, activity, lock, STATE.md) is gitignored
+ * so branch switches are clean.
+ *
+ * Flow:
+ *   1. ensureSliceBranch() — create + checkout slice branch
+ *   2. agent does work, commits
+ *   3. mergeSliceToMain() — checkout main, squash-merge, delete branch
+ */
+
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+
+export interface MergeSliceResult {
+  branch: string;
+  mergedCommitMessage: string;
+  deletedBranch: boolean;
+}
+
+function runGit(basePath: string, args: string[], options: { allowFailure?: boolean } = {}): string {
+  try {
+    return execSync(`git ${args.join(" ")}`, {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim();
+  } catch (error) {
+    if (options.allowFailure) return "";
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`git ${args.join(" ")} failed in ${basePath}: ${message}`);
+  }
+}
+
+export function getSliceBranchName(milestoneId: string, sliceId: string): string {
+  return `kata/${milestoneId}/${sliceId}`;
+}
+
+export function getMainBranch(basePath: string): string {
+  const symbolic = runGit(basePath, ["symbolic-ref", "refs/remotes/origin/HEAD"], { allowFailure: true });
+  if (symbolic) {
+    const match = symbolic.match(/refs\/remotes\/origin\/(.+)$/);
+    if (match) return match[1]!;
+  }
+
+  const mainExists = runGit(basePath, ["show-ref", "--verify", "refs/heads/main"], { allowFailure: true });
+  if (mainExists) return "main";
+
+  const masterExists = runGit(basePath, ["show-ref", "--verify", "refs/heads/master"], { allowFailure: true });
+  if (masterExists) return "master";
+
+  return runGit(basePath, ["branch", "--show-current"]);
+}
+
+export function getCurrentBranch(basePath: string): string {
+  return runGit(basePath, ["branch", "--show-current"]);
+}
+
+function branchExists(basePath: string, branch: string): boolean {
+  try {
+    runGit(basePath, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure the slice branch exists and is checked out.
+ * Creates the branch from main if it doesn't exist.
+ * Returns true if the branch was newly created.
+ */
+export function ensureSliceBranch(basePath: string, milestoneId: string, sliceId: string): boolean {
+  const branch = getSliceBranchName(milestoneId, sliceId);
+  const current = getCurrentBranch(basePath);
+
+  if (current === branch) return false;
+
+  const mainBranch = getMainBranch(basePath);
+  let created = false;
+
+  if (!branchExists(basePath, branch)) {
+    runGit(basePath, ["branch", branch, mainBranch]);
+    created = true;
+  }
+
+  runGit(basePath, ["checkout", branch]);
+  return created;
+}
+
+/**
+ * Auto-commit any dirty files in the current working tree.
+ * Returns the commit message used, or null if already clean.
+ */
+export function autoCommitCurrentBranch(
+  basePath: string, unitType: string, unitId: string,
+): string | null {
+  const status = runGit(basePath, ["status", "--short"]);
+  if (!status.trim()) return null;
+
+  runGit(basePath, ["add", "-A"]);
+
+  const staged = runGit(basePath, ["diff", "--cached", "--stat"]);
+  if (!staged.trim()) return null;
+
+  const message = `chore(${unitId}): auto-commit after ${unitType}`;
+  runGit(basePath, ["commit", "-m", JSON.stringify(message)]);
+  return message;
+}
+
+/**
+ * Switch to main, auto-committing any dirty files on the current branch first.
+ */
+export function switchToMain(basePath: string): void {
+  const mainBranch = getMainBranch(basePath);
+  const current = getCurrentBranch(basePath);
+  if (current === mainBranch) return;
+
+  // Auto-commit if dirty
+  autoCommitCurrentBranch(basePath, "pre-switch", current);
+
+  runGit(basePath, ["checkout", mainBranch]);
+}
+
+/**
+ * Squash-merge a completed slice branch to main.
+ * Expects to already be on main (call switchToMain first).
+ * Deletes the branch after merge.
+ */
+export function mergeSliceToMain(
+  basePath: string, milestoneId: string, sliceId: string, sliceTitle: string,
+): MergeSliceResult {
+  const branch = getSliceBranchName(milestoneId, sliceId);
+  const mainBranch = getMainBranch(basePath);
+
+  const current = getCurrentBranch(basePath);
+  if (current !== mainBranch) {
+    throw new Error(`Expected to be on ${mainBranch}, found ${current}`);
+  }
+
+  if (!branchExists(basePath, branch)) {
+    throw new Error(`Slice branch ${branch} does not exist`);
+  }
+
+  const ahead = runGit(basePath, ["rev-list", "--count", `${mainBranch}..${branch}`]);
+  if (Number(ahead) <= 0) {
+    throw new Error(`Slice branch ${branch} has no commits ahead of ${mainBranch}`);
+  }
+
+  runGit(basePath, ["merge", "--squash", branch]);
+  const mergedCommitMessage = `feat(${milestoneId}/${sliceId}): ${sliceTitle}`;
+  runGit(basePath, ["commit", "-m", JSON.stringify(mergedCommitMessage)]);
+  runGit(basePath, ["branch", "-D", branch]);
+
+  return {
+    branch,
+    mergedCommitMessage,
+    deletedBranch: true,
+  };
+}
+
+/**
+ * Check if we're currently on a slice branch (not main).
+ */
+export function isOnSliceBranch(basePath: string): boolean {
+  const current = getCurrentBranch(basePath);
+  return current.startsWith("kata/");
+}
+
+/**
+ * Get the active slice branch name, or null if on main.
+ */
+export function getActiveSliceBranch(basePath: string): string | null {
+  try {
+    const current = getCurrentBranch(basePath);
+    return current.startsWith("kata/") ? current : null;
+  } catch {
+    return null;
+  }
+}