@llm4ts/shell 2.11.0 → 2.12.0

package/flows/epic-stories.js

@@ -29,7 +29,7 @@ import { landEpic } from "@llm4ts/flow/Landing";
 import { implementStoriesFlow } from "@llm4ts/flow/Stories";
 import { makeStoryPlanStore, validateStoryPlan } from "@llm4ts/flow/StoryPlan";
 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";
+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();
@@ -95,6 +95,11 @@ 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,
@@ -102,7 +107,7 @@ const program = Effect.gen(function* () {
                 stateDir,
                 target: flags.land,
                 keepWorktrees: flags.keepWorktrees,
-                gates: gatesIn(nodeProcessExecutor, events, gateCommands(process.env)),
+                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({
@@ -126,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 }, {
@@ -151,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).
@@ -166,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

@@ -2,7 +2,7 @@
 // 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 { 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";
@@ -37,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. */
@@ -544,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"];
 /**
@@ -562,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.11.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.11.0",
-    "@llm4ts/flow": "2.11.0",
-    "@llm4ts/runner": "2.11.0"
+    "@llm4ts/core": "2.12.0",
+    "@llm4ts/flow": "2.12.0",
+    "@llm4ts/runner": "2.12.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"