@abdullahsahmad/work-kit 0.1.0

package/cli/src/engine/transitions.ts

@@ -0,0 +1,97 @@
+import { WorkKitState, PhaseName, SUBSTAGES_BY_PHASE } from "../state/schema.js";
+import { PHASE_ORDER } from "../config/phases.js";
+
+export interface NextStep {
+  type: "sub-stage" | "phase-boundary" | "complete" | "wait-for-user";
+  phase?: PhaseName;
+  subStage?: string;
+  message?: string;
+}
+
+/**
+ * Find the next pending sub-stage within a phase.
+ */
+export function nextSubStageInPhase(state: WorkKitState, phase: PhaseName): string | null {
+  const phaseState = state.phases[phase];
+  const subStages = SUBSTAGES_BY_PHASE[phase];
+
+  for (const ss of subStages) {
+    const ssState = phaseState.subStages[ss];
+    if (ssState && (ssState.status === "pending" || ssState.status === "in-progress")) {
+      return ss;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if all non-skipped sub-stages in a phase are completed.
+ */
+export function isPhaseComplete(state: WorkKitState, phase: PhaseName): boolean {
+  const phaseState = state.phases[phase];
+  return Object.values(phaseState.subStages).every(
+    (ss) => ss.status === "completed" || ss.status === "skipped"
+  );
+}
+
+/**
+ * Find the next phase that needs work.
+ */
+export function nextPhase(state: WorkKitState): PhaseName | null {
+  for (const phase of PHASE_ORDER) {
+    const ps = state.phases[phase];
+    if (ps.status === "pending" || ps.status === "in-progress") {
+      return phase;
+    }
+  }
+  return null;
+}
+
+/**
+ * Determine the next step in the workflow.
+ */
+export function determineNextStep(state: WorkKitState): NextStep {
+  if (state.status === "completed") {
+    return { type: "complete", message: "Work-kit is complete" };
+  }
+
+  const currentPhase = state.currentPhase;
+
+  if (!currentPhase) {
+    // Find the next phase
+    const next = nextPhase(state);
+    if (!next) {
+      return { type: "complete", message: "All phases complete" };
+    }
+    return { type: "phase-boundary", phase: next, message: `Starting ${next} phase` };
+  }
+
+  // Check if current phase is complete
+  if (isPhaseComplete(state, currentPhase)) {
+    // Find next phase
+    const phaseIndex = PHASE_ORDER.indexOf(currentPhase);
+    const remainingPhases = PHASE_ORDER.slice(phaseIndex + 1);
+
+    for (const phase of remainingPhases) {
+      const ps = state.phases[phase];
+      if (ps.status !== "skipped") {
+        // Phase boundary — wait for user confirmation before crossing
+        return {
+          type: "wait-for-user",
+          phase,
+          message: `${currentPhase} phase complete. Ready to start ${phase}. Proceed?`,
+        };
+      }
+    }
+
+    return { type: "complete", message: "All phases complete" };
+  }
+
+  // Find next sub-stage within current phase
+  const nextSS = nextSubStageInPhase(state, currentPhase);
+  if (nextSS) {
+    return { type: "sub-stage", phase: currentPhase, subStage: nextSS };
+  }
+
+  return { type: "complete", message: `${currentPhase} phase complete` };
+}

package/cli/src/index.ts

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { initCommand } from "./commands/init.js";
+import { statusCommand } from "./commands/status.js";
+import { nextCommand } from "./commands/next.js";
+import { completeCommand } from "./commands/complete.js";
+import { validateCommand } from "./commands/validate.js";
+import { contextCommand } from "./commands/context.js";
+import { loopbackCommand } from "./commands/loopback.js";
+import { workflowCommand } from "./commands/workflow.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { setupCommand } from "./commands/setup.js";
+import { upgradeCommand } from "./commands/upgrade.js";
+import { completionsCommand } from "./commands/completions.js";
+import { observeCommand } from "./commands/observe.js";
+import { uninstallCommand } from "./commands/uninstall.js";
+import { bold, green, yellow, red } from "./utils/colors.js";
+import type { Classification, PhaseName } from "./state/schema.js";
+
+const program = new Command();
+
+program
+  .name("work-kit")
+  .description("State machine orchestrator for work-kit development workflow")
+  .version("1.0.0");
+
+// ── init ─────────────────────────────────────────────────────────────
+
+program
+  .command("init")
+  .description("Create worktree and initialize state")
+  .requiredOption("--mode <mode>", "Workflow mode: full or auto")
+  .requiredOption("--description <text>", "Description of the work")
+  .option("--classification <type>", "Work classification (auto mode): bug-fix, small-change, refactor, feature, large-feature")
+  .option("--worktree-root <path>", "Override worktree root directory")
+  .action((opts) => {
+    try {
+      const result = initCommand({
+        mode: opts.mode as "full" | "auto",
+        description: opts.description,
+        classification: opts.classification as Classification | undefined,
+        worktreeRoot: opts.worktreeRoot,
+      });
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── next ─────────────────────────────────────────────────────────────
+
+program
+  .command("next")
+  .description("Get the next action to perform")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = nextCommand(opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── complete ─────────────────────────────────────────────────────────
+
+program
+  .command("complete <target>")
+  .description("Mark a phase/sub-stage as complete (e.g., plan/clarify)")
+  .option("--outcome <value>", "Outcome of the step (e.g., done, revise, broken, changes_requested)")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((target, opts) => {
+    try {
+      const result = completeCommand(target, opts.outcome, opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── status ───────────────────────────────────────────────────────────
+
+program
+  .command("status")
+  .description("Show current state summary")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = statusCommand(opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── context ──────────────────────────────────────────────────────────
+
+program
+  .command("context <phase>")
+  .description("Extract Final sections needed for a phase's agent")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((phase, opts) => {
+    try {
+      const result = contextCommand(phase as PhaseName, opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── validate ─────────────────────────────────────────────────────────
+
+program
+  .command("validate <phase>")
+  .description("Check prerequisites for a phase")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((phase, opts) => {
+    try {
+      const result = validateCommand(phase as PhaseName, opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── loopback ─────────────────────────────────────────────────────────
+
+program
+  .command("loopback")
+  .description("Register a loop-back transition")
+  .requiredOption("--from <source>", "Source phase/sub-stage (e.g., review/handoff)")
+  .requiredOption("--to <target>", "Target phase/sub-stage (e.g., build/core)")
+  .requiredOption("--reason <text>", "Reason for loop-back")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = loopbackCommand({
+        from: opts.from,
+        to: opts.to,
+        reason: opts.reason,
+        worktreeRoot: opts.worktreeRoot,
+      });
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── workflow ─────────────────────────────────────────────────────────
+
+program
+  .command("workflow")
+  .description("Manage auto-kit dynamic workflow")
+  .option("--add <step>", "Add a step (e.g., review/security)")
+  .option("--remove <step>", "Remove a step (e.g., test/e2e)")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = workflowCommand({
+        add: opts.add,
+        remove: opts.remove,
+        worktreeRoot: opts.worktreeRoot,
+      });
+      console.log(JSON.stringify(result, null, 2));
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── doctor ───────────────────────────────────────────────────────────
+
+program
+  .command("doctor")
+  .description("Check CLI installation, skills, and environment health")
+  .option("--json", "Output as JSON")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    const result = doctorCommand(opts.worktreeRoot);
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      for (const check of result.checks) {
+        const icon = check.status === "pass" ? green("\u2713") : check.status === "warn" ? yellow("!") : red("\u2717");
+        console.error(`  ${icon} ${bold(check.name)}: ${check.message}`);
+      }
+      console.error();
+      console.error(result.ok ? green("All checks passed.") : red("Some checks failed. Fix the issues above."));
+    }
+    process.exit(result.ok ? 0 : 1);
+  });
+
+// ── setup ────────────────────────────────────────────────────────────
+
+program
+  .command("setup [path]")
+  .description("Install work-kit skills into a project")
+  .action(async (targetPath) => {
+    await setupCommand(targetPath);
+  });
+
+// ── upgrade ───────────────────────────────────────────────────────────
+
+program
+  .command("upgrade")
+  .description("Update work-kit skills to the latest version")
+  .option("--worktree-root <path>", "Override project path")
+  .action(async (opts) => {
+    await upgradeCommand(opts.worktreeRoot);
+  });
+
+// ── completions ─────────────────────────────────────────────────────
+
+program
+  .command("completions <shell>")
+  .description("Output shell completions (bash, zsh, fish)")
+  .action((shell) => {
+    completionsCommand(shell);
+  });
+
+// ── observe ─────────────────────────────────────────────────────────
+
+program
+  .command("observe")
+  .description("Real-time dashboard of all active work items")
+  .option("--repo <path>", "Main repository root")
+  .action(async (opts) => {
+    await observeCommand({ mainRepo: opts.repo });
+  });
+
+// ── uninstall ────────────────────────────────────────────────────────
+
+program
+  .command("uninstall [path]")
+  .description("Remove work-kit skills from a project")
+  .action(async (targetPath) => {
+    await uninstallCommand(targetPath);
+  });
+
+program.parse();

package/cli/src/observer/data.ts

@@ -0,0 +1,237 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import type { WorkKitState, PhaseName } from "../state/schema.js";
+import { PHASE_NAMES, SUBSTAGES_BY_PHASE } from "../state/schema.js";
+import { readState, stateExists } from "../state/store.js";
+
+// ── View Types ──────────────────────────────────────────────────────
+
+export interface WorkItemView {
+  slug: string;
+  branch: string;
+  mode: string;
+  classification?: string;
+  status: string;
+  currentPhase: string | null;
+  currentSubStage: string | null;
+  startedAt: string;
+  progress: { completed: number; total: number; percent: number };
+  phases: { name: string; status: string }[];
+  loopbacks: { count: number; lastReason?: string; lastFrom?: string; lastTo?: string };
+}
+
+export interface CompletedItemView {
+  slug: string;
+  pr?: string;
+  completedAt: string;
+  phases: string;
+}
+
+export interface DashboardData {
+  activeItems: WorkItemView[];
+  completedItems: CompletedItemView[];
+  lastUpdated: Date;
+}
+
+// ── Worktree Discovery ──────────────────────────────────────────────
+
+export function discoverWorktrees(mainRepoRoot: string): string[] {
+  let output: string;
+  try {
+    output = execFileSync("git", ["worktree", "list", "--porcelain"], {
+      cwd: mainRepoRoot,
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+  } catch {
+    return [];
+  }
+
+  const worktrees: string[] = [];
+  const lines = output.split("\n");
+  for (const line of lines) {
+    if (line.startsWith("worktree ")) {
+      const wtPath = line.slice("worktree ".length).trim();
+      if (stateExists(wtPath)) {
+        worktrees.push(wtPath);
+      }
+    }
+  }
+
+  if (stateExists(mainRepoRoot) && !worktrees.includes(mainRepoRoot)) {
+    worktrees.push(mainRepoRoot);
+  }
+
+  return worktrees;
+}
+
+// ── Collect Single Work Item ────────────────────────────────────────
+
+export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
+  if (!stateExists(worktreeRoot)) return null;
+
+  let state: WorkKitState;
+  try {
+    state = readState(worktreeRoot);
+  } catch {
+    return null;
+  }
+
+  // Compute progress
+  let completed = 0;
+  let total = 0;
+  const phaseViews: { name: string; status: string }[] = [];
+
+  const phaseList: PhaseName[] = state.mode === "auto-kit" && state.workflow
+    ? getAutoKitPhases(state)
+    : [...PHASE_NAMES];
+
+  for (const phaseName of phaseList) {
+    const phase = state.phases[phaseName];
+    if (!phase) {
+      phaseViews.push({ name: phaseName, status: "pending" });
+      // Count substages for total
+      const subs = SUBSTAGES_BY_PHASE[phaseName] || [];
+      total += subs.length;
+      continue;
+    }
+
+    phaseViews.push({ name: phaseName, status: phase.status });
+
+    const subStageKeys = Object.keys(phase.subStages);
+    if (subStageKeys.length === 0) {
+      // Use default substages
+      const defaults = SUBSTAGES_BY_PHASE[phaseName] || [];
+      total += defaults.length;
+      if (phase.status === "completed") completed += defaults.length;
+      else if (phase.status === "skipped") completed += defaults.length;
+    } else {
+      for (const key of subStageKeys) {
+        total++;
+        const sub = phase.subStages[key];
+        if (sub.status === "completed" || sub.status === "skipped") {
+          completed++;
+        }
+      }
+    }
+  }
+
+  const percent = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+  // Loopback info
+  const loopbacks = state.loopbacks || [];
+  const loopbackView = {
+    count: loopbacks.length,
+    lastReason: loopbacks.length > 0 ? loopbacks[loopbacks.length - 1].reason : undefined,
+    lastFrom: loopbacks.length > 0
+      ? `${loopbacks[loopbacks.length - 1].from.phase}/${loopbacks[loopbacks.length - 1].from.subStage}`
+      : undefined,
+    lastTo: loopbacks.length > 0
+      ? `${loopbacks[loopbacks.length - 1].to.phase}/${loopbacks[loopbacks.length - 1].to.subStage}`
+      : undefined,
+  };
+
+  return {
+    slug: state.slug,
+    branch: state.branch,
+    mode: state.mode,
+    classification: state.classification,
+    status: state.status,
+    currentPhase: state.currentPhase,
+    currentSubStage: state.currentSubStage,
+    startedAt: state.started,
+    progress: { completed, total, percent },
+    phases: phaseViews,
+    loopbacks: loopbackView,
+  };
+}
+
+function getAutoKitPhases(state: WorkKitState): PhaseName[] {
+  if (!state.workflow) return [...PHASE_NAMES];
+  const phases = new Set<PhaseName>();
+  for (const step of state.workflow) {
+    if (step.included) phases.add(step.phase);
+  }
+  // Maintain canonical order
+  return PHASE_NAMES.filter(p => phases.has(p));
+}
+
+// ── Collect Completed Items ─────────────────────────────────────────
+
+export function collectCompletedItems(mainRepoRoot: string): CompletedItemView[] {
+  const indexPath = path.join(mainRepoRoot, ".claude", "work-kit", "index.md");
+  if (!fs.existsSync(indexPath)) return [];
+
+  let content: string;
+  try {
+    content = fs.readFileSync(indexPath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  const items: CompletedItemView[] = [];
+  // Parse markdown table or list entries
+  // Expected format: | slug | PR | date | phases |
+  // or list format: - slug (#PR) - date - phases
+  const lines = content.split("\n");
+  for (const line of lines) {
+    // Try table format: | slug | #PR | date | phases |
+    const tableMatch = line.match(/^\|\s*(.+?)\s*\|\s*(#?\d+)?\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|/);
+    if (tableMatch) {
+      const slug = tableMatch[1].trim();
+      if (slug === "Slug" || slug === "---" || slug.startsWith("-")) continue; // skip header
+      items.push({
+        slug,
+        pr: tableMatch[2]?.trim() || undefined,
+        completedAt: tableMatch[3].trim(),
+        phases: tableMatch[4].trim(),
+      });
+      continue;
+    }
+
+    // Try list format: - **slug** (#38) completed 2d ago — plan→review
+    const listMatch = line.match(/^[-*]\s+\*?\*?(.+?)\*?\*?\s+\(?(#\d+)?\)?\s*[-—]?\s*(.+?)?\s*[-—]\s*(.+)$/);
+    if (listMatch) {
+      items.push({
+        slug: listMatch[1].trim(),
+        pr: listMatch[2]?.trim() || undefined,
+        completedAt: listMatch[3]?.trim() || "",
+        phases: listMatch[4]?.trim() || "",
+      });
+    }
+  }
+
+  return items;
+}
+
+// ── Collect All Dashboard Data ──────────────────────────────────────
+
+export function collectDashboardData(mainRepoRoot: string, cachedWorktrees?: string[]): DashboardData {
+  const worktrees = cachedWorktrees ?? discoverWorktrees(mainRepoRoot);
+  const activeItems: WorkItemView[] = [];
+
+  for (const wt of worktrees) {
+    const item = collectWorkItem(wt);
+    if (item && item.status !== "completed") {
+      activeItems.push(item);
+    }
+  }
+
+  // Sort: in-progress first, then paused, then by start time
+  activeItems.sort((a, b) => {
+    const statusOrder: Record<string, number> = { "in-progress": 0, "paused": 1, "failed": 2 };
+    const aOrder = statusOrder[a.status] ?? 3;
+    const bOrder = statusOrder[b.status] ?? 3;
+    if (aOrder !== bOrder) return aOrder - bOrder;
+    return new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime();
+  });
+
+  const completedItems = collectCompletedItems(mainRepoRoot);
+
+  return {
+    activeItems,
+    completedItems,
+    lastUpdated: new Date(),
+  };
+}