@llm4ts/shell 2.10.0 → 2.11.0

package/flows/epic-stories.js

@@ -3,6 +3,8 @@
 //   llm4ts run epic-stories --repo ~/demo/portal "Add the current account and wire transfers"
 //   llm4ts run epic-stories --repo ~/demo/portal -- --plan-only "…"   # write the plan and stop
 //   llm4ts run epic-stories --repo ~/demo/portal -- --land            # land the finished epic on main
+//   llm4ts run epic-stories --repo ~/demo/portal -- --list            # the repository's epics
+//   llm4ts run epic-stories --repo ~/demo/portal -- --epic <id>       # resume one, no text needed
 //
 // The reasoning seat (LLM4TS_REASONER, default claude) splits the epic,
 // reviews every task and judges every story; the coder seat (LLM4TS_CODER,
@@ -26,7 +28,8 @@ import { FlowAborted, Info, asReadOnly, nodePlainFileStore, nodeProcessExecutor,
 import { landEpic } from "@llm4ts/flow/Landing";
 import { implementStoriesFlow } from "@llm4ts/flow/Stories";
 import { makeStoryPlanStore, validateStoryPlan } from "@llm4ts/flow/StoryPlan";
-import { awaitServer, combineTotals, epicIdFor, flagsFromEnvironment, gateCommands, gatesIn, generateStoryPlan, httpProbe, judgeStory, localCoderServer, parseEpicArgs, reasonerFromEnvironment, serverHealthUrl, setupIn, storyCoderFromEnvironment, verifyBlockedOn, worktreeRootFor, worktreeSetupCommand } from "./lib/epic-stories.js";
+import * as Console from "effect/Console";
+import { awaitServer, chooseEpic, epicsDir, listEpics, renderEpicList, combineTotals, epicIdFor, flagsFromEnvironment, gateCommands, gatesIn, generateStoryPlan, httpProbe, judgeStory, localCoderServer, parseEpicArgs, reasonerFromEnvironment, serverHealthUrl, setupIn, storyCoderFromEnvironment, verifyBlockedOn, worktreeRootFor, worktreeSetupCommand } from "./lib/epic-stories.js";
 /** `LLM4TS_CODER_MODEL` / `LLM4TS_REASONING_MODEL`: pi takes `provider/model` (e.g. `openai-codex/gpt-5.5`). */
 const withOptionalModel = (config, model) => {
     const trimmed = model?.trim();
@@ -40,14 +43,33 @@ const defaultEpic = "Add the retail customer's current account (Conto) with bala
     "transfers (Bonifico) with beneficiary, review, SCA confirmation, and history.";
 const program = Effect.gen(function* () {
     const flags = yield* parseEpicArgs(process.argv.slice(2));
-    const input = yield* resolveFlowInput(defaultEpic, flags.rest);
+    // The epic is chosen before any seat is resolved: the text given, `--epic`,
+    // or the one epic not landed yet (`chooseEpic`); `--list` only lists.
+    const given = yield* resolveFlowInput("", flags.rest);
+    const files = nodePlainFileStore;
+    const epics = yield* listEpics(files, given.workDir);
+    if (flags.list) {
+        yield* Console.log(renderEpicList(epics));
+        return;
+    }
+    const choice = yield* chooseEpic({
+        text: given.prompt,
+        epic: flags.epic,
+        epics,
+        defaultEpic
+    });
+    const input = {
+        ...given,
+        prompt: choice._tag === "Existing" ? choice.epic.epic : choice.prompt
+    };
     const coderFlags = flagsFromEnvironment(process.env.LLM4TS_CODER_FLAGS);
     const reasoning = withExtraFlags(withOptionalModel(yield* reasonerFromEnvironment(process.env), process.env.LLM4TS_REASONING_MODEL), flagsFromEnvironment(process.env.LLM4TS_REASONING_FLAGS));
     const coder = withExtraFlags(withOptionalModel(yield* storyCoderFromEnvironment(process.env), process.env.LLM4TS_CODER_MODEL), coderFlags);
     const localServer = localCoderServer(process.env.LLM4TS_CODER_MODEL, coderFlags, process.env);
-    const files = nodePlainFileStore;
-    const epicId = epicIdFor(input.prompt);
-    const stateDir = join(input.workDir, ".llm4ts", "epics", epicId);
+    // A new epic's id (and state folder) is derived from its text; an existing
+    // one keeps its folder, whatever text is on the command line.
+    const epicId = choice._tag === "Existing" ? choice.epic.dir : epicIdFor(input.prompt);
+    const stateDir = join(epicsDir(input.workDir), epicId);
     const planPath = join(stateDir, "plan.md");
     const estimateOptions = estimatedUsageOptionsFromEnv(process.env);
     const contextBudget = budget(process.env);
@@ -79,6 +101,7 @@ const program = Effect.gen(function* () {
                 files,
                 stateDir,
                 target: flags.land,
+                keepWorktrees: flags.keepWorktrees,
                 gates: gatesIn(nodeProcessExecutor, events, gateCommands(process.env)),
                 system: ["House rules of the target repository (CONTRIBUTING.md):", guidance].join("\n")
             });

package/flows/lib/epic-stories.js

@@ -1,6 +1,7 @@
 // Shared core of the epic-stories flow (ADR 0013): the operator flags, the
 // story-plan generator prompt and schema, the story judge, the gate runner,
 // and seat selection. The executor itself is `@llm4ts/flow/Stories`.
+import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
@@ -10,17 +11,24 @@ import { TokenUsage } from "@llm4ts/core/Models";
 import { cap } from "@llm4ts/flow/Context";
 import { structuredAndPublish } from "@llm4ts/flow/Flow";
 import { Info } from "@llm4ts/flow/FlowEvents";
-import { BlockedVerdict } from "@llm4ts/flow/Stories";
+import { EpicLanded, EpicLandedVersion, landedPath } from "@llm4ts/flow/Landing";
+import { loadVersioned } from "@llm4ts/flow/Persistence";
+import { BlockedVerdict, StoryState, StoryStateVersion } from "@llm4ts/flow/Stories";
 import { stableHash } from "@llm4ts/flow/Plan";
 import { ReviewIssue } from "@llm4ts/flow/Review";
-import { StoryPlan, dependenciesOf, pathsNamedIn } from "@llm4ts/flow/StoryPlan";
+import { StoryPlan, dependenciesOf, makeStoryPlanStore, pathsNamedIn } from "@llm4ts/flow/StoryPlan";
 import { claude, coderIds, pi } from "@llm4ts/runner/Connectors";
 import { FlowAborted, FlowLlmError, ReviewResult, ScriptUsage, coderFor, lintCommand, mergeReviewResults } from "@llm4ts/runner";
 export const epicUsage = [
     "epic-stories flags:",
     "  --plan-only         write (or re-validate) the story plan and stop",
     "  --land[=<branch>]   land the finished epic on <branch> (default main): merge the branch in,",
-    "                      let the coder fix conflicts and red gates (3 rounds), then merge",
+    "                      let the coder fix conflicts and red gates (3 rounds), then merge;",
+    "                      afterwards the story worktrees and merged story branches go",
+    "  --keep-worktrees    with --land: keep the story worktrees and branches",
+    "  --list              list this repository's epics (id, stories merged, landed) and stop",
+    "  --epic <id>         work on an existing epic by id, no text needed. Without text or",
+    "                      --epic, the one epic not landed yet is chosen; several stop the run",
     "  --concurrency <n>   stories implemented at once (default 3)",
     "  --fail-fast         stop the epic at the first failed story",
     "Seats: LLM4TS_REASONER (claude|gemini|…, default claude) splits, reviews, judges;",
@@ -37,6 +45,9 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
     let failFast = false;
     let concurrency;
     let land;
+    let keepWorktrees = false;
+    let list = false;
+    let epic;
     const rest = [];
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index] ?? "";
@@ -46,6 +57,22 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
         else if (argument === "--fail-fast") {
             failFast = true;
         }
+        else if (argument === "--keep-worktrees") {
+            keepWorktrees = true;
+        }
+        else if (argument === "--list") {
+            list = true;
+        }
+        else if (argument === "--epic" || argument.startsWith("--epic=")) {
+            const value = argument.includes("=") ? argument.slice("--epic=".length) : argv[index + 1];
+            if (!argument.includes("=")) {
+                index += 1;
+            }
+            if (value === undefined || value.trim().length === 0 || value.startsWith("--")) {
+                return yield* ScriptUsage.make({ message: `--epic needs an epic id\n${epicUsage}` });
+            }
+            epic = value.trim();
+        }
         else if (argument === "--land" || argument.startsWith("--land=")) {
             // `--land=<branch>`, never a separate word: the epic text may follow.
             const branch = argument.includes("=") ? argument.slice("--land=".length).trim() : "main";
@@ -73,8 +100,93 @@ export const parseEpicArgs = (argv) => Effect.gen(function* () {
             rest.push(argument);
         }
     }
-    return { planOnly, failFast, concurrency, land, rest };
+    return { planOnly, failFast, concurrency, land, keepWorktrees, list, epic, rest };
 });
+export const epicsDir = (workDir) => join(workDir, ".llm4ts", "epics");
+/** Every epic with a plan in this repository, oldest folder name first. */
+export const listEpics = (files, workDir) => Effect.gen(function* () {
+    const root = epicsDir(workDir);
+    const entries = yield* Effect.tryPromise(() => readdir(root, { withFileTypes: true })).pipe(Effect.catch(() => Effect.succeed([])));
+    const store = makeStoryPlanStore(files);
+    const summaries = [];
+    for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const stateDir = join(root, entry.name);
+        const plan = yield* store
+            .load(join(stateDir, "plan.md"))
+            .pipe(Effect.catch(() => Effect.succeed(undefined)));
+        if (plan === undefined) {
+            continue;
+        }
+        let merged = 0;
+        for (const story of plan.stories) {
+            const state = yield* loadVersioned(files, join(stateDir, "stories", `${story.id}.json`), StoryStateVersion, StoryState).pipe(Effect.catch(() => Effect.succeed(undefined)));
+            if (state?.status === "merged") {
+                merged += 1;
+            }
+        }
+        const landed = yield* loadVersioned(files, landedPath(stateDir), EpicLandedVersion, EpicLanded).pipe(Effect.catch(() => Effect.succeed(undefined)));
+        summaries.push({
+            dir: entry.name,
+            stateDir,
+            epicId: plan.epicId,
+            epic: plan.epic,
+            stories: plan.stories.length,
+            merged,
+            landed: landed?.target
+        });
+    }
+    return summaries;
+});
+export const renderEpicList = (epics) => epics.length === 0
+    ? "no epics in this repository yet: give an epic's text to plan one"
+    : [
+        `epics (${epics.length}):`,
+        ...epics.flatMap((epic) => [
+            `- ${epic.epicId} · ${epic.merged}/${epic.stories} stories merged · ${epic.landed === undefined
+                ? epic.merged === epic.stories
+                    ? "finished, not landed"
+                    : "in progress"
+                : `landed on ${epic.landed}`}  (--epic ${epic.epicId})`,
+            `  "${epic.epic.length > 110 ? `${epic.epic.slice(0, 109)}…` : epic.epic}"`
+        ])
+    ].join("\n");
+/**
+ * The epic text given wins (a new epic, or the existing one with that exact
+ * text); `--epic` picks an existing one; with neither, the one epic not yet
+ * landed is chosen. Several candidates, or none left, stop the run with the
+ * list — never a silent guess. With no epic at all, the flow's default text.
+ */
+export const chooseEpic = (args) => {
+    if (args.epic !== undefined) {
+        const found = args.epics.find((epic) => epic.dir === args.epic || epic.epicId === args.epic);
+        return found === undefined
+            ? Effect.fail(ScriptUsage.make({
+                message: `no epic '${args.epic}' in this repository\n${renderEpicList(args.epics)}`
+            }))
+            : Effect.succeed({ _tag: "Existing", epic: found });
+    }
+    if (args.text.trim().length > 0) {
+        return Effect.succeed({ _tag: "Text", prompt: args.text });
+    }
+    const open = args.epics.filter((epic) => epic.landed === undefined);
+    if (open.length === 1 && open[0] !== undefined) {
+        return Effect.succeed({ _tag: "Existing", epic: open[0] });
+    }
+    if (open.length > 1) {
+        return Effect.fail(ScriptUsage.make({
+            message: `several epics are open here; pick one with --epic <id>, or give an epic's text\n${renderEpicList(open)}`
+        }));
+    }
+    if (args.epics.length > 0) {
+        return Effect.fail(ScriptUsage.make({
+            message: `every epic here has landed; give the new epic's text to plan it\n${renderEpicList(args.epics)}`
+        }));
+    }
+    return Effect.succeed({ _tag: "Text", prompt: args.defaultEpic });
+};
 // ---- Seats --------------------------------------------------------------------
 /** The reasoning seat: `LLM4TS_REASONER`, any coder id, default claude. Unknown names fail typed. */
 export const reasonerFromEnvironment = (environment) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-rc.115",
     "@effect/platform-node-shared": "4.0.0-rc.115",
-    "@llm4ts/core": "2.10.0",
-    "@llm4ts/flow": "2.10.0",
-    "@llm4ts/runner": "2.10.0"
+    "@llm4ts/core": "2.11.0",
+    "@llm4ts/flow": "2.11.0",
+    "@llm4ts/runner": "2.11.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"