@llm4ts/shell 2.10.0 → 2.12.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, appDirFor, gateCommands, gatesIn, inAppDir, generateStoryPlan, httpProbe, judgeStory, localCoderServer, parseEpicArgs, reasonerFromEnvironment, serverHealthUrl, setupAgentEnabled, 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);
@@ -73,13 +95,19 @@ const program = Effect.gen(function* () {
         if (flags.planOnly) {
             return;
         }
+        // Setup and gates run where the application is, in every checkout.
+        const appDir = yield* appDirFor(input.workDir, process.env);
+        if (appDir !== ".") {
+            yield* events.publish(Info.make({ message: `app dir: ${appDir} (setup and gates run there; LLM4TS_APP_DIR)` }));
+        }
         if (flags.land !== undefined) {
             const landed = yield* landEpic(context, {
                 plan,
                 files,
                 stateDir,
                 target: flags.land,
-                gates: gatesIn(nodeProcessExecutor, events, gateCommands(process.env)),
+                keepWorktrees: flags.keepWorktrees,
+                gates: inAppDir(appDir, gatesIn(nodeProcessExecutor, events, gateCommands(process.env))),
                 system: ["House rules of the target repository (CONTRIBUTING.md):", guidance].join("\n")
             });
             yield* events.publish(Info.make({
@@ -103,7 +131,12 @@ const program = Effect.gen(function* () {
                 message: "this runner cannot rebind seats to a worktree (no contextFor)"
             });
         }
-        const gates = gatesIn(nodeProcessExecutor, events, gateCommands(process.env));
+        const appDirNote = appDir === "."
+            ? []
+            : [
+                `The application lives in ${appDir}/ — its package.json, sources and tests; the gates run there.`
+            ];
+        const gates = inAppDir(appDir, gatesIn(nodeProcessExecutor, events, gateCommands(process.env)));
         const setupCommand = worktreeSetupCommand(process.env);
         const healthUrl = serverHealthUrl(localServer, process.env);
         const report = yield* implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {
@@ -128,7 +161,10 @@ const program = Effect.gen(function* () {
             }),
             ...(setupCommand === undefined
                 ? {}
-                : { setup: setupIn(nodeProcessExecutor, events, setupCommand) }),
+                : {
+                    setup: inAppDir(appDir, setupIn(nodeProcessExecutor, events, setupCommand)),
+                    setupAgent: setupAgentEnabled(process.env)
+                }),
             gates,
             // With a roster, the judge and the verifier are leased per story,
             // away from the executor coding it (ADR 0019).
@@ -143,7 +179,8 @@ const program = Effect.gen(function* () {
                 "House rules of the target repository (CONTRIBUTING.md):",
                 guidance,
                 "",
-                `Imitate the exemplar feature before inventing anything. Story id: ${story.id}.`
+                `Imitate the exemplar feature before inventing anything. Story id: ${story.id}.`,
+                ...appDirNote
             ].join("\n")),
             concurrency,
             failFast: flags.failFast

package/flows/lib/epic-stories.js

@@ -1,7 +1,8 @@
 // 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 { join } from "node:path";
+import { readdir } from "node:fs/promises";
+import { isAbsolute, join, normalize } from "node:path";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import { Dimension, Sample } from "@llm4ts/core/eval/Eval";
@@ -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;",
@@ -29,6 +37,9 @@ export const epicUsage = [
     "       add CLI flags (key=value;key=value). LLM4TS_GATES overrides the gate commands;",
     "       LLM4TS_WORKTREE_SETUP (default: pnpm install --offline) prepares each worktree;",
     "       LLM4TS_WORKTREE_ROOT (default: <repo>.worktrees beside the repository) holds them;",
+    "       LLM4TS_APP_DIR (e.g. frontend) runs setup and gates in that subfolder; unset, a",
+    "       repository without a root package.json uses its one subfolder that has one;",
+    "       LLM4TS_SETUP_AGENT=1 gives the coder one turn to fix a failed setup, then reruns it;",
     "       LLM4TS_CODER_HEALTH_URL is polled after the coder's serving engine goes down."
 ].join("\n");
 /** The flow's own flags, taken out before the shared `--repo`/prompt parsing sees the rest. */
@@ -37,6 +48,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 +60,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 +103,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) => {
@@ -432,6 +547,45 @@ export const judgeStory = (reasoning, story, diff, budget, plan) => judge(reason
     response: cap(diff, budget).text
 }))
     .pipe(Effect.mapError(FlowLlmError.from), Effect.map((scored) => subBar(scored, story)));
+// ---- App directory ----------------------------------------------------------------
+/** Folders never taken for the application: dependencies, build output, llm4ts state. */
+const ignoredAppDirs = new Set(["node_modules", "dist", "build", "out", "coverage"]);
+const hasPackageJson = (dir) => Effect.tryPromise(() => readdir(dir)).pipe(Effect.map((names) => names.includes("package.json")), Effect.catch(() => Effect.succeed(false)));
+/**
+ * Where setup and gates run, relative to a checkout: `LLM4TS_APP_DIR` when set
+ * (`.` for the root); otherwise the root when it has a `package.json`, else
+ * its ONE first-level subfolder that has one (a Next.js app in `frontend/`).
+ * Several candidates, or none, keep the root — the setup error then names it.
+ * The value is relative so it applies to every worktree and the epic checkout.
+ */
+export const appDirFor = (workDir, environment) => Effect.gen(function* () {
+    const configured = environment.LLM4TS_APP_DIR?.trim();
+    if (configured !== undefined && configured.length > 0) {
+        const normalized = normalize(configured);
+        const relative = normalized.replace(/[\\/]+$/, "");
+        if (isAbsolute(normalized) || relative === ".." || /^\.\.[\\/]/.test(relative)) {
+            return yield* ScriptUsage.make({
+                message: `LLM4TS_APP_DIR must be a folder inside the repository, got '${configured}'`
+            });
+        }
+        return relative.length === 0 ? "." : relative;
+    }
+    if (yield* hasPackageJson(workDir)) {
+        return ".";
+    }
+    const entries = yield* Effect.tryPromise(() => readdir(workDir, { withFileTypes: true })).pipe(Effect.catch(() => Effect.succeed([])));
+    const candidates = [];
+    for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith(".") && !ignoredAppDirs.has(entry.name)) {
+            if (yield* hasPackageJson(join(workDir, entry.name))) {
+                candidates.push(entry.name);
+            }
+        }
+    }
+    return candidates.length === 1 ? (candidates[0] ?? ".") : ".";
+});
+/** Runs a per-checkout step in the app directory of whichever checkout it is given. */
+export const inAppDir = (appDir, step) => (workDir) => step(appDir === "." ? workDir : join(workDir, appDir));
 // ---- Worktree setup --------------------------------------------------------------
 export const defaultWorktreeSetup = ["pnpm", "install", "--offline"];
 /**
@@ -450,13 +604,19 @@ export const worktreeSetupCommand = (environment) => {
         .filter((part) => part.length > 0);
     return parts.length === 0 ? undefined : parts;
 };
+/**
+ * `LLM4TS_SETUP_AGENT=1` (or `true`/`on`): a failed setup gets one coder turn
+ * to make the worktree ready, then runs again as the check. Off by default.
+ */
+export const setupAgentEnabled = (environment) => /^(1|true|on|yes)$/i.test(environment.LLM4TS_SETUP_AGENT?.trim() ?? "");
+const output = (result) => result.issues.map((issue) => issue.description).join("\n");
 /** Runs the setup command in a worktree; a non-zero exit fails the story with the output. */
 export const setupIn = (process, events, command) => (workDir) => Effect.flatMap(lintCommand(process, events, command, workDir), (result) => result.isClean
     ? Effect.void
     : FlowAborted.make({
-        message: `worktree setup failed (${command.join(" ")}):\n${result.issues
-            .map((issue) => issue.description)
-            .join("\n")}`
+        message: `worktree setup failed (${command.join(" ")}):\n${output(result)}${/ERR_PNPM_NO_PKG_MANIFEST|ENOENT.*package\.json/.test(output(result))
+            ? "\n(the application is not at this folder: set LLM4TS_APP_DIR to its subfolder)"
+            : ""}`
     }));
 // ---- Gates ---------------------------------------------------------------------
 export const defaultGateCommands = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.10.0",
+  "version": "2.12.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.12.0",
+    "@llm4ts/flow": "2.12.0",
+    "@llm4ts/runner": "2.12.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"