gflows 0.1.17 → 1.0.0

package/src/run-state.ts

@@ -0,0 +1,165 @@
+/**
+ * Persist multi-step gflows operations so continue / undo / abort can recover.
+ * State lives under .git/gflows/ (gitignored by nature of .git).
+ * @module run-state
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** One planned step in a multi-step operation. */
+export interface RunStep {
+  /** Step id for resume (e.g. merge-main, tag, merge-dev, delete, push). */
+  id: string;
+  /** Human description. */
+  label: string;
+  /** Opaque payload for the step executor. */
+  data?: Record<string, unknown>;
+}
+
+/** Suspended or completed run record. */
+export interface GflowsRunState {
+  /** Command that created this run (finish, sync, …). */
+  command: string;
+  /** ISO timestamp when started. */
+  startedAt: string;
+  /** Status of the run. */
+  status: "running" | "suspended" | "completed";
+  /** Index of next step to execute. */
+  nextStep: number;
+  /** Planned steps. */
+  steps: RunStep[];
+  /** Snapshot for undo (branch tips, tag created, previous HEAD, etc.). */
+  undo: Record<string, unknown>;
+  /** Extra context (branch, type, config names, flags). */
+  context: Record<string, unknown>;
+  /** Last error message when suspended. */
+  lastError?: string;
+}
+
+const STATE_DIR = "gflows";
+const ACTIVE_FILE = "run.json";
+const LAST_FILE = "last.json";
+
+function gitGflowsDir(repoRoot: string): string {
+  return join(repoRoot, ".git", STATE_DIR);
+}
+
+function activePath(repoRoot: string): string {
+  return join(gitGflowsDir(repoRoot), ACTIVE_FILE);
+}
+
+function lastPath(repoRoot: string): string {
+  return join(gitGflowsDir(repoRoot), LAST_FILE);
+}
+
+function ensureDir(repoRoot: string): void {
+  const dir = gitGflowsDir(repoRoot);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Reads the active (suspended/running) run state, or null.
+ */
+export function readActiveRun(repoRoot: string): GflowsRunState | null {
+  const path = activePath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return JSON.parse(raw) as GflowsRunState;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads the last completed run (for undo), or null.
+ */
+export function readLastRun(repoRoot: string): GflowsRunState | null {
+  const path = lastPath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return JSON.parse(raw) as GflowsRunState;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes active run state.
+ */
+export function writeActiveRun(repoRoot: string, state: GflowsRunState): void {
+  ensureDir(repoRoot);
+  writeFileSync(activePath(repoRoot), `${JSON.stringify(state, null, 2)}\n`, "utf-8");
+}
+
+/**
+ * Clears active run state (after abort or successful complete move to last).
+ */
+export function clearActiveRun(repoRoot: string): void {
+  const path = activePath(repoRoot);
+  if (existsSync(path)) {
+    unlinkSync(path);
+  }
+}
+
+/**
+ * Marks run completed and moves it to last.json for undo; clears active.
+ */
+export function completeRun(repoRoot: string, state: GflowsRunState): void {
+  ensureDir(repoRoot);
+  const done: GflowsRunState = {
+    ...state,
+    status: "completed",
+    nextStep: state.steps.length,
+  };
+  writeFileSync(lastPath(repoRoot), `${JSON.stringify(done, null, 2)}\n`, "utf-8");
+  clearActiveRun(repoRoot);
+}
+
+/**
+ * Clears last completed run (after undo).
+ */
+export function clearLastRun(repoRoot: string): void {
+  const path = lastPath(repoRoot);
+  if (existsSync(path)) {
+    unlinkSync(path);
+  }
+}
+
+/**
+ * Creates a new running state and persists it.
+ */
+export function startRun(
+  repoRoot: string,
+  command: string,
+  steps: RunStep[],
+  context: Record<string, unknown>,
+  undo: Record<string, unknown>,
+): GflowsRunState {
+  const state: GflowsRunState = {
+    command,
+    startedAt: new Date().toISOString(),
+    status: "running",
+    nextStep: 0,
+    steps,
+    undo,
+    context,
+  };
+  writeActiveRun(repoRoot, state);
+  return state;
+}
+
+/**
+ * Suspends the active run after a failure (e.g. merge conflict).
+ */
+export function suspendRun(repoRoot: string, state: GflowsRunState, lastError: string): void {
+  writeActiveRun(repoRoot, {
+    ...state,
+    status: "suspended",
+    lastError,
+  });
+}

package/src/tui/HubHome.tsx

@@ -0,0 +1,343 @@
+/**
+ * Hub home screen — status map, actions, slash prompt (Ink).
+ * @module tui/HubHome
+ */
+
+import { homedir } from "node:os";
+import { Box, Text, useInput, useStdout } from "ink";
+import type React from "react";
+import { useEffect, useMemo, useState } from "react";
+import { getCurrentBranch, resolveRepoRoot } from "../git.js";
+import { type RecommendAction, recommend } from "../recommend.js";
+import { getVersion } from "../version.js";
+import { collectVizSnapshot, type VizSnapshot } from "../viz.js";
+
+const ACCENT = "#E88C4A";
+const MUTED = "#8A8A8A";
+const FG = "#E6E6E6";
+const GREEN = "#78C88C";
+const YELLOW = "#DCB450";
+
+type ActionItem = { id: string; label: string; hint?: string };
+
+/**
+ * Props for the hub home view.
+ */
+export interface HubHomeProps {
+  cwd: string;
+  flash?: string;
+  onAction: (id: string) => void;
+  onSlash: (command: string) => void;
+  onQuit: () => void;
+}
+
+/**
+ * Main hub dashboard.
+ */
+export function HubHome({
+  cwd,
+  flash,
+  onAction,
+  onSlash,
+  onQuit,
+}: HubHomeProps): React.ReactElement {
+  const { stdout } = useStdout();
+  const cols = stdout?.columns ?? 80;
+  const rows = stdout?.rows ?? 24;
+
+  const [snap, setSnap] = useState<VizSnapshot | null>(null);
+  const [branch, setBranch] = useState("—");
+  const [repoPath, setRepoPath] = useState(cwd);
+  const [selected, setSelected] = useState(0);
+  const [input, setInput] = useState("");
+  const [showHelp, setShowHelp] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const version = useMemo(() => getVersion(), []);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const root = await resolveRepoRoot(cwd);
+        const b = (await getCurrentBranch(root, {})) ?? "detached";
+        const s = await collectVizSnapshot(cwd);
+        if (!cancelled) {
+          setRepoPath(root);
+          setBranch(b);
+          setSnap(s);
+        }
+      } catch {
+        if (!cancelled) {
+          setSnap(null);
+          setBranch("—");
+        }
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  const rec = snap ? recommend(snap) : null;
+  const actions = useMemo(() => buildActions(snap, rec?.action ?? null), [snap, rec?.action]);
+
+  useEffect(() => {
+    if (selected >= actions.length) setSelected(Math.max(0, actions.length - 1));
+  }, [actions.length, selected]);
+
+  useInput((ch, key) => {
+    if (key.ctrl && ch === "c") {
+      onQuit();
+      return;
+    }
+    if (key.escape) {
+      if (input || showHelp) {
+        setInput("");
+        setShowHelp(false);
+        return;
+      }
+      onQuit();
+      return;
+    }
+    if (ch === "?" && input === "") {
+      setShowHelp((v) => !v);
+      return;
+    }
+    if (ch === "q" && input === "") {
+      onQuit();
+      return;
+    }
+    if (key.upArrow) {
+      setSelected((i) => Math.max(0, i - 1));
+      return;
+    }
+    if (key.downArrow) {
+      setSelected((i) => Math.min(actions.length - 1, i + 1));
+      return;
+    }
+    if (key.backspace || key.delete) {
+      setInput((s) => [...s].slice(0, -1).join(""));
+      return;
+    }
+    if (key.return) {
+      const cmd = input.trim();
+      if (cmd.startsWith("/")) {
+        setInput("");
+        onSlash(cmd);
+        return;
+      }
+      const action = actions[selected];
+      if (!action || action.id === "quit") {
+        onQuit();
+        return;
+      }
+      onAction(action.id);
+      return;
+    }
+    if (ch && !key.ctrl && !key.meta && ch >= " ") {
+      setInput((s) => s + ch);
+    }
+  });
+
+  const pathShort = shortPath(repoPath);
+  const tips = tipLines(snap);
+  const next = nextLines(rec, snap);
+  const branches = branchLines(snap);
+  const listBudget = Math.max(3, Math.min(8, rows - 18));
+  const start = Math.max(0, Math.min(selected - listBudget + 2, actions.length - listBudget));
+  const visible = actions.slice(start, start + listBudget);
+  const frameWidth = Math.max(40, cols - 2);
+
+  return (
+    <Box flexDirection="column" width={cols} height={rows}>
+      <Box
+        flexDirection="column"
+        borderStyle="round"
+        borderColor={ACCENT}
+        width={frameWidth}
+        paddingX={1}
+      >
+        <Text bold color={FG}>
+          Welcome to gflows{" "}
+          <Text color={MUTED} dimColor>
+            v{version}
+          </Text>
+        </Text>
+        <Text color={MUTED}>Git branching workflow · main + dev + short-lived branches</Text>
+        <Text color={MUTED}>{pathShort}</Text>
+
+        {flash ? (
+          <Box marginTop={1}>
+            <Text color={YELLOW}>│ {flash}</Text>
+          </Box>
+        ) : null}
+
+        <Box marginTop={1} flexDirection="row">
+          <Box width="50%" flexDirection="column" paddingRight={1}>
+            <Text bold color={ACCENT}>
+              Tips for getting started
+            </Text>
+            {tips.map((line) => (
+              <Text key={line} color={MUTED}>
+                {line}
+              </Text>
+            ))}
+          </Box>
+          <Box width="50%" flexDirection="column">
+            <Text bold color={ACCENT}>
+              What's next
+            </Text>
+            {next.map((line) => (
+              <Text
+                key={line}
+                color={line.startsWith("→") ? GREEN : MUTED}
+                bold={line.startsWith("→")}
+              >
+                {line}
+              </Text>
+            ))}
+          </Box>
+        </Box>
+
+        <Box marginY={1} flexDirection="column">
+          <Text bold color={FG}>
+            Branches
+          </Text>
+          {loading ? (
+            <Text color={MUTED}>Loading…</Text>
+          ) : (
+            branches.slice(0, 7).map((line) => (
+              <Text key={line} color={MUTED}>
+                {line}
+              </Text>
+            ))
+          )}
+        </Box>
+
+        <Text color={MUTED}>Actions · ↑↓ select · enter · /command (wizards stay in-app)</Text>
+        {visible.map((a, i) => {
+          const abs = start + i;
+          const active = abs === selected;
+          return (
+            <Text key={a.id} color={active ? FG : MUTED} bold={active}>
+              {active ? <Text color={ACCENT}>❯ </Text> : "  "}
+              {a.label}
+              {a.hint ? (
+                <Text color={MUTED}>
+                  {"  "}
+                  {a.hint}
+                </Text>
+              ) : null}
+            </Text>
+          );
+        })}
+
+        <Box marginTop={1} flexDirection="column">
+          <Text>
+            <Text color={ACCENT}>❯ </Text>
+            {input || <Text color={MUTED}>type /start /finish /sync …</Text>}
+            {input ? <Text color={ACCENT}>█</Text> : null}
+          </Text>
+          <Text color={MUTED}>
+            {showHelp
+              ? "/init /start /sync /pr /finish /doctor /help  ·  esc clear  ·  ctrl+c quit"
+              : "? for shortcuts"}
+          </Text>
+        </Box>
+      </Box>
+
+      <Box width={cols} justifyContent="space-between">
+        <Text backgroundColor="#282828" color={MUTED}>
+          {" "}
+          <Text color={ACCENT}>/init</Text> start sync pr finish{" "}
+        </Text>
+        <Text backgroundColor="#282828" color={MUTED}>
+          {" "}
+          {pathShort} <Text color={ACCENT}></Text> <Text color={FG}>{branch}</Text>{" "}
+        </Text>
+      </Box>
+      {rec?.action === "init" ? <Text color={YELLOW}> Setup incomplete — run /init</Text> : null}
+    </Box>
+  );
+}
+
+function shortPath(p: string): string {
+  const home = homedir();
+  if (p.startsWith(home)) return `~${p.slice(home.length)}`;
+  return p;
+}
+
+function tipLines(snap: VizSnapshot | null): string[] {
+  if (!snap || snap.needsInit) {
+    return [
+      "1. /init or select Initialize",
+      "2. /start (wizard in hub)",
+      "3. commit → /sync · /pr · /finish",
+    ];
+  }
+  return [
+    "• /start — wizard stays in this UI",
+    "• /sync — update from base",
+    "• /pr then /finish when ready",
+  ];
+}
+
+function nextLines(rec: ReturnType<typeof recommend> | null, snap: VizSnapshot | null): string[] {
+  if (!rec) return ["Not a git repo", "cd into a repo, then reopen"];
+  return [`→ ${rec.label}`, rec.detail, snap?.current ? `on ${snap.current}` : ""].filter(Boolean);
+}
+
+function branchLines(snap: VizSnapshot | null): string[] {
+  if (!snap) return ["(no repo)"];
+  const lines: string[] = [];
+  if (snap.suspended) lines.push(`⚠ suspended: ${snap.suspended}`);
+  for (const row of snap.rows) {
+    if (row.type !== "main" && row.type !== "dev") continue;
+    const mark = row.current ? "●" : "○";
+    lines.push(`${mark} ${row.name}  [${row.type}]`);
+  }
+  const workflow = snap.rows.filter((r) => r.type !== "main" && r.type !== "dev");
+  if (workflow.length === 0) {
+    lines.push("  (no workflow branches)");
+  } else {
+    for (let i = 0; i < workflow.length; i++) {
+      const row = workflow[i];
+      if (!row) continue;
+      const elbow = i === workflow.length - 1 ? "└─" : "├─";
+      const mark = row.current ? "●" : "○";
+      const ab = row.ahead === 0 && row.behind === 0 ? "synced" : `+${row.ahead}/-${row.behind}`;
+      lines.push(`${elbow} ${mark} ${row.name}  (${row.type}) ${ab}`);
+    }
+  }
+  return lines;
+}
+
+function buildActions(snap: VizSnapshot | null, recommended: RecommendAction | null): ActionItem[] {
+  const items: ActionItem[] = [];
+  const push = (id: string, label: string, hint?: string) => {
+    items.push({ id, label, hint });
+  };
+  if (snap?.needsInit) push("init", "Initialize repo", "/init");
+  push("start", "Start new work", "/start");
+  push("sync", "Sync with base", "/sync");
+  push("pr", "Open pull request", "/pr");
+  push("finish", "Finish / merge branch", "/finish");
+  if (snap?.suspended) push("continue", "Continue suspended", "/continue");
+  push("switch", "Switch branch", "/switch");
+  push("list", "List branches", "/list");
+  push("doctor", "Doctor", "/doctor");
+  push("help", "Help", "/help");
+  push("quit", "Quit", "q");
+
+  const prefer = recommended && recommended !== "commit" ? recommended : null;
+  if (prefer) {
+    const idx = items.findIndex((a) => a.id === prefer);
+    if (idx >= 0) {
+      const [item] = items.splice(idx, 1);
+      if (item) items.unshift({ ...item, label: `★ ${item.label.replace(/^★ /, "")}` });
+    }
+  }
+  return items;
+}

package/src/tui/HubShell.tsx

@@ -0,0 +1,186 @@
+/**
+ * Persistent Ink hub shell: home map + in-app wizards (no Clack drop-out for prompts).
+ * @module tui/HubShell
+ */
+
+import { Box, Text, useApp, useInput } from "ink";
+import type React from "react";
+import { useState } from "react";
+import { FinishFlow, StartFlow, SyncFlow } from "./flows.js";
+import { HubHome } from "./HubHome.js";
+import { WizardFrame } from "./prompts.js";
+
+const ACCENT = "#E88C4A";
+const MUTED = "#8A8A8A";
+const FG = "#E6E6E6";
+
+/** Outcome of one hub session (Ink unmounts after this). */
+export type HubSessionResult = { kind: "quit" } | { kind: "run"; argv: string[] };
+
+type Screen =
+  | { id: "home"; flash?: string }
+  | { id: "start" }
+  | { id: "finish" }
+  | { id: "sync" }
+  | { id: "notice"; message: string };
+
+/**
+ * Props for the hub shell.
+ */
+export interface HubShellProps {
+  cwd: string;
+  onDone: (result: HubSessionResult) => void;
+}
+
+/**
+ * Fullscreen hub with embedded wizards.
+ */
+export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
+  const { exit } = useApp();
+  const [screen, setScreen] = useState<Screen>({ id: "home" });
+
+  const finish = (result: HubSessionResult) => {
+    onDone(result);
+    exit();
+  };
+
+  const cancelWizard = () => setScreen({ id: "home" });
+  const runArgv = (argv: string[]) => finish({ kind: "run", argv });
+
+  const handleSlash = (raw: string) => {
+    const parts = raw.slice(1).trim().split(/\s+/);
+    const cmd = (parts[0] ?? "").toLowerCase();
+    const rest = parts.slice(1);
+
+    if (!cmd || cmd === "quit" || cmd === "exit" || cmd === "q") {
+      finish({ kind: "quit" });
+      return;
+    }
+
+    if (cmd === "start") {
+      if (rest.length >= 2) {
+        const type = rest[0] ?? "feature";
+        const name = rest[1] ?? "";
+        runArgv(["start", type, name, "-P", ...rest.slice(2)]);
+        return;
+      }
+      setScreen({ id: "start" });
+      return;
+    }
+    if (cmd === "finish") {
+      if (rest.length > 0) {
+        runArgv(["finish", "-y", "-P", ...rest]);
+        return;
+      }
+      setScreen({ id: "finish" });
+      return;
+    }
+    if (cmd === "sync") {
+      if (rest.length > 0) {
+        runArgv(["sync", "--force", ...rest]);
+        return;
+      }
+      setScreen({ id: "sync" });
+      return;
+    }
+    if (cmd === "viz") {
+      setScreen({ id: "home", flash: "Branch map is shown on this screen." });
+      return;
+    }
+
+    const known = new Set([
+      "init",
+      "pr",
+      "continue",
+      "switch",
+      "list",
+      "doctor",
+      "help",
+      "config",
+      "bump",
+      "status",
+    ]);
+    if (!known.has(cmd)) {
+      setScreen({
+        id: "notice",
+        message: `Unknown /${cmd} — press ? on the home screen for shortcuts.`,
+      });
+      return;
+    }
+
+    runArgv([cmd, ...rest]);
+  };
+
+  const handleHome = (action: string) => {
+    if (action === "quit") {
+      finish({ kind: "quit" });
+      return;
+    }
+    if (action === "start") {
+      setScreen({ id: "start" });
+      return;
+    }
+    if (action === "finish") {
+      setScreen({ id: "finish" });
+      return;
+    }
+    if (action === "sync") {
+      setScreen({ id: "sync" });
+      return;
+    }
+    runArgv([action]);
+  };
+
+  if (screen.id === "start") {
+    return <StartFlow onCancel={cancelWizard} onDone={runArgv} />;
+  }
+  if (screen.id === "finish") {
+    return <FinishFlow onCancel={cancelWizard} onDone={runArgv} />;
+  }
+  if (screen.id === "sync") {
+    return <SyncFlow onCancel={cancelWizard} onDone={runArgv} />;
+  }
+  if (screen.id === "notice") {
+    return (
+      <PressEnter
+        title="Notice"
+        message={screen.message}
+        onDone={() => setScreen({ id: "home" })}
+      />
+    );
+  }
+
+  return (
+    <HubHome
+      cwd={cwd}
+      flash={screen.flash}
+      onAction={handleHome}
+      onSlash={handleSlash}
+      onQuit={() => finish({ kind: "quit" })}
+    />
+  );
+}
+
+function PressEnter({
+  title,
+  message,
+  onDone,
+}: {
+  title: string;
+  message: string;
+  onDone: () => void;
+}): React.ReactElement {
+  useInput((_ch, key) => {
+    if (key.return || key.escape) onDone();
+  });
+
+  return (
+    <WizardFrame title={title}>
+      <Text color={FG}>{message}</Text>
+      <Box marginTop={1}>
+        <Text color={MUTED}>Press enter to continue</Text>
+        <Text color={ACCENT}> █</Text>
+      </Box>
+    </WizardFrame>
+  );
+}