@dieulc/workflow 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dieuluucanh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @dieulc/workflow
+
+Plan↔Build mode, questionnaire, subagent explore, todos and shadow-checkpoint rewind for Pi.
+
+## Features
+
+- **Plan / Build duality** — `Plan` tool gating (`edit`/`write` blocked in plan), `Build` restores full tools; tab + `CtrlAlt+p` shortcuts, `--workflow-plan` flag
+- **Questionnaire** — 1–4 questions with headers/options, dedup freeform aliases, inline `↳ Your answer:` editor
+- **Explore (subagents)** — parallel `pi --mode json` subagents (`max 8`, concurrency 4), `session_shutdown` kill, `activeSubagents`
+- **Todos** — plan-faithful todo list (global step refs + statuses + phase groups) that persists across Plan/Build/Default modes. `workflow_todo` (`list/update/done/pending/add/toggle/sync/clear`) with industry-style wholesale `update` (send the COMPLETE list; omitted items are removed) plus idempotent `done`/`pending`, lenient `[DONE:<ref>]` markers, throttled Claude-Code-style reminders, a tool-result footer, and a stale ⚠ notice — but **no forced turns and no heuristic auto-completion** (reference: Claude Code / OpenCode / Codex practice).
+- **Rewind** — shadow bare-repo checkpoints per cwd (`agent/checkpoints/checkpoint-<slug>.git`), `isDirty` + `createSafetySnapshot` + `restoreCode`
+- **Plannotator bridge** — `plannotator:request/review-result/plan-approved` events, inline markdown handoff (`ScrollView` → inline scrollback), `getUtcDatePrefix` / `normalizePlanPath` for `.pi/plans/<UTC-date>-<slug>.md`
+- **Model roles** — Planner/Explorer/Builder roles with one model + thinking level each (`roles.ts`, `~/.pi/agent/roles.json` v2). `/plan` switches to the planner model, `/build` to the builder model, `explore` subagents use the explorer model. `/role` opens a tabbed picker (scoped models first, `Ctrl+O` for all).
+
+## Install
+
+```bash
+pi install npm:@dieulc/workflow            # latest
+pi install npm:@dieulc/workflow@0.1.0      # pinned
+pi install -l npm:@dieulc/workflow         # project-local (.pi/settings.json)
+pi -e npm:@dieulc/workflow                 # try without installing
+```
+
+Manage it with `pi list`, `pi update --extensions`, `pi remove npm:@dieulc/workflow`. Requires Pi on Node ≥ 22.19; the Pi core packages (`@earendil-works/*`, `typebox`) are provided by Pi at runtime and declared as peer dependencies.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/plan` / `/workflow` | Enter plan mode (tool gating + switches session model to planner model `high` thinking) |
+| `/build` | Enter build mode (full tools + switches session model to builder model `medium` thinking) |
+| `/rewind` | Pick checkpoint to restore |
+| `/todos` | Show todo list |
+| `/btw` | Queue note for next turn |
+| `/role` | Config screen: one model + thinking per role (planner/explorer/builder tabs, custom roles included). CLI: `list`, `set <role> <provider/model> [thinking]`, `use <role\|auto>`, `add/remove/reset` |
+
+## Settings
+
+Role config lives in `~/.pi/agent/roles.json` v2 (user) with optional per-project override at `<cwd>/.pi/roles.json` (per-role replace). Each role holds exactly one `{provider, id, thinking}`. v1 `modelPool` files are discarded and reseeded on load. Seeded with defaults on first run. No extra `settings.json` keys — respects `theme`, `modelRegistry`, and `plannotator` phases from `agent/plannotator.json`.
+
+## How it works
+
+See `index.ts`, `checkpoint.ts` (shadow bare-repo), `utils.ts` (safe-command gating, todo/plan extraction), `roles.ts` (role registry, one model per role). Hot-reload via `/reload` when placed in `~/.pi/agent/extensions/workflow/` or loaded via `pi.extensions` manifest.
+
+### Todo protocol (industry-aligned)
+
+- **Canonical refs**: every todo row is numbered **globally** `1..N`; those numbers are the only refs the model ever needs. Refs are canonical positions — they are recomputed as `1..N` after every mutation (plan merge, `update`, session restore), so the pinned widget, handoff messages, tool output and `workflow_todo` refs always show the same numbers (no 11–20 drift). The plan's per-phase labels (e.g. `Phase B: 1..3`) are preserved only as display metadata (`(plan label B2)`). Integer refs resolve by canonical `ref` → positional `step` → unique `label`; the resolver also accepts `Group/Label`, `Label@Group`, `#N` and unique text (≥8 chars).
+- **States**: `pending` → `in_progress` → `completed` (+ `cancelled`). Exactly one `in_progress` at a time (the harness normalizes extras). `completed` is kept as a derived legacy field for old sessions/external readers.
+- **Update**: `workflow_todo {action:"update", todos:[{ref?, text?, status?}]}` replaces the whole list — TodoWrite/todowrite/update_plan semantics. A `ref` is resolved by canonical ref, then normalized text, then leniently by plan label / group-qualified ref / unique text; a ref that had to be resolved leniently (or matched nothing and was added) is reported under `Warnings:` in the tool result. `done`/`pending` are idempotent single-item sets; `toggle` is a convenience flip; `add` appends an ad-hoc item; `sync` re-extracts the plan file, matches steps by exact text then by plan label (so model-rewritten wording reunites instead of duplicating), **preserves agent-added items** (reported as `kept N agent-added`) and never un-completes (status rank merge); `clear` empties.
+- **Reminder cadence** (Claude Code-style throttle): a hidden `[TODO LIST]` context block is injected only when `turnsSinceLastTodoWrite ≥ TURNS_SINCE_WRITE` **and** `turnsSinceLastReminder ≥ TURNS_BETWEEN_REMINDERS` (`=3`). Unresolved `[DONE:…]` refs from the previous turn bypass the throttle once so the model learns the right numbers. A one-line `[TODO …]` footer is appended to the first successful `edit`/`write`/`bash` result of each turn.
+- **Stale notice (no forced turns)**: if a run mutated files but recorded no todo progress, the user gets one `⚠` status marker + a `ctx.ui.notify` (30 s dedupe); plan-file `- [x]` ticks are reconciled at `agent_end` in all modes, skipped when the plan content is unchanged (path+hash guard). No auto-completion — the list is never marked done based on intent. Legacy lists that already contain duplicate rows are not auto-merged; run `/todos clear` (or approve a new plan) to reset.
+
+## Development
+
+```bash
+cd agent/extensions/workflow
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # node --test utils.todo.test.ts
+```
+
+Plain TypeScript, no build step — Pi loads `index.ts` directly (via jiti). From the repo root, `npm run verify` checks this package's manifest, tarball contents, tests and load path before a release. Live reload: edit the `.ts` file and run `/reload` in Pi.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/checkpoint.ts

@@ -0,0 +1,302 @@
+/**
+ * Shadow bare-repo checkpoint manager for workflow rewind — file snapshots.
+ *
+ * Each cwd gets a per-worktree bare repo under <agentDir>/checkpoints/checkpoint-<slug>.git
+ * Snapshots are created before LLM edits (turn_start) and keyed by session leaf entryId.
+ * Uses pi.exec (direct spawn, bypasses workflow/utils.ts isSafeCommand gating on bash tool).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const MAX_CHECKPOINTS_PER_SESSION = 100;
+
+function slugifyCwd(cwd: string): string {
+  const normalized = cwd.replace(/\\/g, "/").toLowerCase();
+  return (
+    normalized
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 80) || "root"
+  );
+}
+
+export function shadowDirFor(cwd: string): string {
+  const slug = slugifyCwd(cwd);
+  return path.join(getAgentDir(), "checkpoints", `checkpoint-${slug}.git`);
+}
+
+export function shadowWorkTreeFile(shadowDir: string): string {
+  return path.join(shadowDir, "pi-work-tree");
+}
+
+export async function gitShadow(
+  pi: ExtensionAPI,
+  cwd: string,
+  args: string[],
+  opts?: { signal?: AbortSignal },
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const shadowDir = shadowDirFor(cwd);
+  const fullArgs = [
+    "--git-dir",
+    shadowDir,
+    "--work-tree",
+    cwd,
+    "-c",
+    "core.autocrlf=false",
+    ...args,
+  ];
+  try {
+    const res: any = await (pi as any).exec(
+      "git",
+      fullArgs,
+      opts?.signal ? { signal: opts.signal } : undefined,
+    );
+    // pi.exec returns {stdout, stderr, exitCode?} or {code, stdout, stderr}
+    return {
+      stdout: String(res?.stdout ?? res?.output ?? ""),
+      stderr: String(res?.stderr ?? res?.error ?? ""),
+      exitCode:
+        typeof res?.exitCode === "number"
+          ? res.exitCode
+          : typeof res?.code === "number"
+            ? res.code
+            : 0,
+    };
+  } catch (e: any) {
+    return {
+      stdout: String(e?.stdout ?? ""),
+      stderr: String(e?.stderr ?? e?.message ?? ""),
+      exitCode: 1,
+    };
+  }
+}
+
+export function isGitRepoSync(cwd: string): boolean {
+  let cur = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(cur, ".git"))) return true;
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return false;
+}
+
+export async function isGitRepo(
+  pi: ExtensionAPI,
+  cwd: string,
+): Promise<boolean> {
+  // Prefer quick fs check first, fallback to git rev-parse if fs misses (worktree etc.)
+  if (isGitRepoSync(cwd)) return true;
+  try {
+    const r: any = await (pi as any).exec("git", [
+      "rev-parse",
+      "--is-inside-work-tree",
+    ]);
+    const out = String(r?.stdout ?? "").trim();
+    return out === "true";
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureShadow(
+  pi: ExtensionAPI,
+  cwd: string,
+): Promise<void> {
+  const dir = shadowDirFor(cwd);
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(path.dirname(dir), { recursive: true });
+      await (pi as any).exec("git", ["init", "--bare", dir]);
+    } else if (!fs.existsSync(path.join(dir, "HEAD"))) {
+      await (pi as any).exec("git", ["init", "--bare", dir]);
+    }
+    // Ensure pi-work-tree sidecar reflects current cwd (handles cwd moves)
+    try {
+      const wtFile = shadowWorkTreeFile(dir);
+      const prev = fs.existsSync(wtFile)
+        ? fs.readFileSync(wtFile, "utf8").trim()
+        : "";
+      if (prev !== path.resolve(cwd)) {
+        fs.writeFileSync(wtFile, path.resolve(cwd), "utf8");
+      }
+    } catch {}
+    // Mirror local excludes so checkout respects local .gitignore additions
+    try {
+      const localExclude = path.join(cwd, ".git", "info", "exclude");
+      const shadowExclude = path.join(dir, "info", "exclude");
+      if (fs.existsSync(localExclude)) {
+        try {
+          fs.mkdirSync(path.dirname(shadowExclude), { recursive: true });
+        } catch {}
+        const content = fs.readFileSync(localExclude, "utf8");
+        fs.writeFileSync(shadowExclude, content, "utf8");
+      }
+    } catch {}
+  } catch {}
+}
+
+async function getHeadRef(
+  pi: ExtensionAPI,
+  cwd: string,
+): Promise<string | null> {
+  const r = await gitShadow(pi, cwd, ["rev-parse", "HEAD"]);
+  const sha = r.stdout.trim();
+  if (r.exitCode !== 0 || !sha || sha.includes("unknown revision")) return null;
+  if (!/^[0-9a-f]{4,40}$/i.test(sha)) return null;
+  return sha;
+}
+
+async function capCheckpoints(pi: ExtensionAPI, cwd: string): Promise<void> {
+  try {
+    const r = await gitShadow(pi, cwd, ["rev-list", "--count", "HEAD"]);
+    const count = parseInt(r.stdout.trim(), 10);
+    if (!Number.isFinite(count) || count <= MAX_CHECKPOINTS_PER_SESSION) return;
+    // Bounded history: keep only the newest MAX commits by resetting to a shallower depth.
+    // For bare repo with linear history we retain all objects but GC will prune unreachable.
+    // Simple gc to keep disk bounded — no destructive branch delete for v1.
+    await gitShadow(pi, cwd, ["gc", "--prune=now", "--quiet"]);
+  } catch (e: unknown) {
+    void e;
+  }
+}
+
+export async function createCheckpoint(
+  pi: ExtensionAPI,
+  cwd: string,
+  entryId: string,
+  promptFirstLine: string,
+): Promise<{ ref: string | null }> {
+  if (!entryId) return { ref: null };
+  const repo = await isGitRepo(pi, cwd);
+  if (!repo) return { ref: null };
+  try {
+    await ensureShadow(pi, cwd);
+  } catch {
+    return { ref: null };
+  }
+  try {
+    // git add -A for tracked files only (respects .gitignore), exclude internal dirs
+    // Use pathspec excludes to avoid snapshotting agent internals if they live inside cwd.
+    await gitShadow(pi, cwd, [
+      "add",
+      "-A",
+      "--",
+      ".",
+      ":(exclude).git",
+      ":(exclude)agent/checkpoints",
+      ":(exclude)agent/sessions",
+      ":(exclude).pi/plans",
+    ]);
+    // Commit even if empty so each user prompt gets a ref (allow-empty)
+    const msg = `checkpoint: ${promptFirstLine.slice(0, 80).replace(/"/g, "'")} entryId=${entryId}`;
+    const commit = await gitShadow(pi, cwd, [
+      "-c",
+      "commit.gpgsign=false",
+      "-c",
+      "core.hooksPath=/dev/null",
+      "commit",
+      "--allow-empty",
+      "-m",
+      msg,
+      "--author",
+      "checkpoint@pi-code <checkpoint@pi-code>",
+    ]);
+    // If nothing to commit and allow-empty still creates, commit succeeds. If no HEAD yet, first commit also succeeds.
+    void commit;
+    const ref = await getHeadRef(pi, cwd);
+    if (ref) {
+      await capCheckpoints(pi, cwd);
+      return { ref };
+    }
+    return { ref: null };
+  } catch {
+    return { ref: null };
+  }
+}
+
+export async function isDirty(pi: ExtensionAPI, cwd: string): Promise<boolean> {
+  const r = await gitShadow(pi, cwd, ["status", "--porcelain"]);
+  return r.stdout.trim().length > 0;
+}
+
+export async function createSafetySnapshot(
+  pi: ExtensionAPI,
+  cwd: string,
+): Promise<{ ref: string | null }> {
+  return createCheckpoint(
+    pi,
+    cwd,
+    `safety-${Date.now()}`,
+    "pre-restore safety",
+  );
+}
+
+export async function restoreCode(
+  pi: ExtensionAPI,
+  cwd: string,
+  ref: string,
+  opts?: { signal?: AbortSignal },
+): Promise<{ restored: boolean; skipped: number }> {
+  const repo = await isGitRepo(pi, cwd);
+  if (!repo) return { restored: false, skipped: 0 };
+  // Nested repo guard: if cwd contains a .git but shadow pi-work-tree diverges, abort would cross boundary
+  try {
+    const sd = shadowDirFor(cwd);
+    const wtFile = shadowWorkTreeFile(sd);
+    if (fs.existsSync(wtFile)) {
+      const recorded = fs.readFileSync(wtFile, "utf8").trim();
+      if (recorded && path.resolve(recorded) !== path.resolve(cwd)) {
+        // cwd moved since snapshot — still allow restore to recorded worktree is safe because --work-tree is explicit
+        // Just warn via return, not hard abort; caller decides.
+      }
+    }
+    // Abort if nested .git under CWD would be traversed incorrectly — checkout excludes .git so safe, but flag nested case
+    // We do not abort; we just exclude .git from checkout path.
+  } catch {}
+  try {
+    // Checkout tracked files to cwd
+    const r = await gitShadow(
+      pi,
+      cwd,
+      ["checkout", "-f", ref, "--", "."],
+      opts,
+    );
+    if (r.exitCode !== 0) {
+      // Fallback to restore if checkout fails (e.g., ref is empty commit)
+      const r2 = await gitShadow(
+        pi,
+        cwd,
+        ["restore", "--source", ref, "."],
+        opts,
+      );
+      if (r2.exitCode !== 0) return { restored: false, skipped: 0 };
+    }
+    return { restored: true, skipped: 0 };
+  } catch {
+    return { restored: false, skipped: 0 };
+  }
+}
+
+export function findPersistedRef(
+  branch: any[],
+  targetId: string,
+): string | null {
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const e: any = branch[i];
+    if (
+      e?.type === "custom" &&
+      e?.customType === "workflow-checkpoint" &&
+      e?.data?.entryId === targetId &&
+      typeof e?.data?.ref === "string" &&
+      e.data.ref.trim()
+    ) {
+      return e.data.ref.trim();
+    }
+  }
+  return null;
+}