@llm4ts/shell 2.44.0 → 2.45.0

package/flows/lib/epic-stories.js

@@ -40,7 +40,7 @@ import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/f
 import { landEpic } from "@llm4ts/flow/Landing";
 import { deferredPath, implementStoriesFlow } from "@llm4ts/flow/Stories";
 import { validateStoryPlan } from "@llm4ts/flow/StoryPlan";
-import { asReadOnly, nodePlainFileStore, nodeProcessExecutor, resolveFlowInput, runNode, stage, withModel } from "@llm4ts/runner";
+import { asReadOnly, nodePlainFileStore, nodeProcessExecutor, openPack, resolveFlowInput, runNode, stage, withModel } from "@llm4ts/runner";
 import { claude, coderIds, judgmentConnectorFromEnvironment, pi } from "@llm4ts/runner/Connectors";
 import { FlowAborted, FlowLlmError, ReviewResult, ScriptUsage, coderFor, lintCommand } from "@llm4ts/runner";
 export const epicUsage = [
@@ -73,9 +73,11 @@ export const epicUsage = [
     "Seats: LLM4TS_REASONER (claude|gemini|…, default claude) splits, reviews, judges;",
     "       LLM4TS_CODER (default pi) implements; LLM4TS_REASONING_MODEL / LLM4TS_CODER_MODEL",
     "       pick their models (pi: provider/model); LLM4TS_CODER_FLAGS / LLM4TS_REASONING_FLAGS",
-    "       add CLI flags (key=value;key=value). LLM4TS_GATES overrides the gate commands",
-    "       (default: those of pnpm typecheck|lint|test|build the app's package.json defines);",
-    "       LLM4TS_WORKTREE_SETUP (default: pnpm install --offline) prepares each worktree;",
+    "       add CLI flags (key=value;key=value). LLM4TS_PACK (or llm4ts run --pack) uses",
+    "       that pack's gates; LLM4TS_GATES overrides them (otherwise: pnpm typecheck|lint|",
+    "       test|build, each only when the app's package.json defines that script);",
+    "       LLM4TS_WORKTREE_SETUP prepares each worktree (default: the pack's setup:, or",
+    "       pnpm install --offline with no pack; empty: none);",
     "       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;",
@@ -1119,13 +1121,15 @@ export const inAppDir = (appDir, step) => (workDir, ...rest) => step(appDir ===
 export const defaultWorktreeSetup = ["pnpm", "install", "--offline"];
 /**
  * `LLM4TS_WORKTREE_SETUP="pnpm install --offline"` (the default) prepares
- * each story worktree; an empty value disables the step. Offline by default:
- * the runbook warms the pnpm store once, and a workshop stage has no network.
+ * each story worktree; an empty value disables the step. Unset, a selected
+ * pack's `setup:` is the command, and a pack without one runs none: its
+ * target is not assumed to be a pnpm project. Offline by default: the
+ * runbook warms the pnpm store once, and a workshop stage has no network.
  */
-export const worktreeSetupCommand = (environment) => {
+export const worktreeSetupCommand = (environment, pack) => {
     const raw = environment.LLM4TS_WORKTREE_SETUP;
     if (raw === undefined) {
-        return defaultWorktreeSetup;
+        return pack === undefined ? defaultWorktreeSetup : pack.setup;
     }
     const parts = raw
         .trim()
@@ -1166,25 +1170,67 @@ export const appScripts = (files, appRoot) => files.read(join(appRoot, "package.
     ? Effect.succeed(undefined)
     : Effect.map(Schema.decodeUnknownEffect(PackageScripts)(text), (manifest) => new Set(Object.keys(manifest.scripts ?? {})))), Effect.catch(() => Effect.succeed(undefined)));
 /**
- * `LLM4TS_GATES="pnpm typecheck;pnpm test"` overrides the four defaults.
- * Without it, a default gate runs only when the application defines that
- * script: a Next.js app has `lint` and `build` but seldom `typecheck`, and
+ * `LLM4TS_GATES="pnpm typecheck;pnpm test"` wins. Otherwise `packGates` —
+ * the selected pack's `## Gates`, in manifest order — are the commands, and
+ * an empty list stays empty (it is not filled with the defaults). With no
+ * pack, a default gate runs only when the application defines that script:
+ * a Next.js app has `lint` and `build` but seldom `typecheck`, and
  * `pnpm typecheck` there fails with "Command not found", not a red gate.
  */
-export const gateCommands = (environment, scripts) => {
+export const gateCommands = (environment, scripts, packGates) => {
     const raw = environment.LLM4TS_GATES?.trim();
-    if (raw === undefined || raw.length === 0) {
-        return scripts === undefined
-            ? defaultGateCommands
-            : defaultGateCommands.filter((command) => scripts.has(command[1] ?? ""));
+    if (raw !== undefined && raw.length > 0) {
+        return raw
+            .split(";")
+            .map((command) => command
+            .trim()
+            .split(/\s+/)
+            .filter((part) => part.length > 0))
+            .filter((command) => command.length > 0);
     }
-    return raw
-        .split(";")
-        .map((command) => command
-        .trim()
-        .split(/\s+/)
-        .filter((part) => part.length > 0))
-        .filter((command) => command.length > 0);
+    if (packGates !== undefined) {
+        return packGates;
+    }
+    return scripts === undefined
+        ? defaultGateCommands
+        : defaultGateCommands.filter((command) => scripts.has(command[1] ?? ""));
+};
+/**
+ * The pack `LLM4TS_PACK` names (what `llm4ts run --pack` forwards), opened
+ * before any seat is resolved so a wrong name fails before the planner
+ * spends anything. Unset, there is none — a pack is never implied:
+ * `openPack` would otherwise load `cobol-springboot`, which is the
+ * modernization flows' default, not an epic's.
+ */
+export const selectedPack = (options) => (options.environment.LLM4TS_PACK?.trim() ?? "").length === 0
+    ? Effect.succeed(undefined)
+    : Effect.map(openPack({
+        environment: options.environment,
+        launchDir: options.launchDir,
+        flowDir: options.flowDir
+    }), (opened) => opened.pack);
+/** The run's gates: `LLM4TS_GATES`, else the selected pack's `## Gates`, else the defaults. */
+export const epicGateCommands = (options) => {
+    const override = (options.environment.LLM4TS_GATES?.trim() ?? "").length > 0;
+    return {
+        commands: gateCommands(options.environment, options.scripts, options.pack === undefined
+            ? undefined
+            : (options.pack.gateList ?? Object.values(options.pack.gates))),
+        source: override ? "override" : options.pack === undefined ? "defaults" : "pack",
+        ...(options.pack === undefined ? {} : { packName: options.pack.name })
+    };
+};
+/** The line the run prints before the first gate. */
+export const gateListMessage = (resolved) => {
+    if (resolved.commands.length === 0) {
+        return resolved.source === "pack"
+            ? `gates: none (pack '${resolved.packName ?? ""}' defines none; set LLM4TS_GATES)`
+            : "gates: none (the app defines none of typecheck, lint, test, build; set LLM4TS_GATES)";
+    }
+    const listed = resolved.commands.map((command) => command.join(" ")).join(" · ");
+    return resolved.source === "pack"
+        ? `gates: ${listed} (pack ${resolved.packName})`
+        : `gates: ${listed}`;
 };
 /** The gate runner lives in `@llm4ts/flow/Gates` (ADR 0027); re-exported for forks and tests. */
 export { gatesIn };
@@ -1421,6 +1467,12 @@ export const runEpicStories = (options) => Effect.gen(function* () {
                 ? choice.request
                 : choice.prompt
     };
+    // The pack whose `## Gates` the run uses; a wrong name fails here, not after planning.
+    const pack = yield* selectedPack({
+        environment: process.env,
+        launchDir: given.workspace,
+        flowDir: import.meta.dirname
+    });
     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);
@@ -1571,12 +1623,13 @@ export const runEpicStories = (options) => Effect.gen(function* () {
                 message: `app dir: ${appDir} (setup and gates run there; LLM4TS_APP_DIR)`
             }));
         }
-        const commands = gateCommands(process.env, yield* appScripts(files, join(input.workDir, appDir)));
-        yield* events.publish(Info.make({
-            message: commands.length === 0
-                ? "gates: none (the app defines none of typecheck, lint, test, build; set LLM4TS_GATES)"
-                : `gates: ${commands.map((command) => command.join(" ")).join(" · ")}`
-        }));
+        const resolvedGates = epicGateCommands({
+            environment: process.env,
+            scripts: yield* appScripts(files, join(input.workDir, appDir)),
+            pack
+        });
+        const commands = resolvedGates.commands;
+        yield* events.publish(Info.make({ message: gateListMessage(resolvedGates) }));
         // The Node the gates would run on is the one on PATH, not the one
         // the application pins; a mismatch is a red first story that says
         // nothing about Node. Ask now, and name both.
@@ -1644,7 +1697,7 @@ export const runEpicStories = (options) => Effect.gen(function* () {
             ];
         const gates = inAppDir(appDir, gatesIn(nodeProcessExecutor, events, commands, gateRunOptions(process.env)));
         const testCommand = testGateCommand(commands);
-        const setupCommand = worktreeSetupCommand(process.env);
+        const setupCommand = worktreeSetupCommand(process.env, pack);
         const healthUrl = serverHealthUrl(localServer, process.env);
         // The executor over one unit: the epic's plan or one refine round.
         const runUnit = (work) => implementStoriesFlow({ ...context, reasoning: reasoningMeter.service }, {

package/kits/j2ee-nextjs/packs/j2ee-nextjs-spa/pack.md

@@ -9,6 +9,7 @@ specs-dir: docs/modernization/specs
 features-dir: docs/modernization/features
 program-files: (?:src/app/<NAME>(?:/.*)?|src/services/<NAME>(?:/.*)?|contracts/<NAME>\.openapi\.yaml|tests/<NAME>\..*)
 feature-files: (?:src/services/<NAME>(?:/.*)?|contracts/<NAME>\.openapi\.yaml)
+setup: pnpm install --offline
 
 ## Gates
 

package/kits/j2ee-nextjs/packs/jsp-nextjs/pack.md

@@ -6,6 +6,7 @@ sources: .*\.(jsp|java|xml)
 programs: .*\.(jsp|java)
 specs-dir: docs/specs
 features-dir: features
+setup: npm install --offline
 
 ## Gates
 

package/kits/port/packs/scala-ts/pack.md

@@ -7,6 +7,7 @@ target: {{dir}}/{{base}}.ts
 comment: //
 specs-dir: docs/port
 features-dir: docs/port/features
+setup: pnpm install --offline
 
 ## Gates
 

package/kits/soap-ace/fixtures/demo-bank-soap/RUNBOOK.md

@@ -112,10 +112,13 @@ Review `.llm4ts/epics/<epic-id>/plan.md` in the ACE repository (edit it to
 re-plan), then run the command `plan` printed:
 
 ```bash
-LLM4TS_GATES="bash scripts/ace-gates.sh build;bash scripts/ace-gates.sh test" LLM4TS_WORKTREE_SETUP= \
-  llm4ts run epic-stories --repo ~/work/conti-ace -- --concurrency 2 "<the epic sentence>"
+llm4ts run epic-stories --pack ace12-rest --repo ~/work/conti-ace -- \
+  --concurrency 2 "<the epic sentence>"
 ```
 
+The pack supplies the gates (`bash scripts/ace-gates.sh build` and `test`)
+and declares no `setup:`, so the story worktrees skip `pnpm install`.
+
 Each story lands on its own branch and merges into `epic/<epic-id>` after its
 gates and judge pass; nothing reaches `main` without a human. The board and
 report live under `.llm4ts/epics/<epic-id>/`. Azure DevOps mirroring is the

package/kits/soap-ace/flows/soap-epic.js

@@ -196,8 +196,7 @@ const program = Effect.gen(function* () {
         }
         yield* say([
             "next: review the plan, commit the seed in the ACE repository, then run",
-            `  LLM4TS_GATES="bash scripts/ace-gates.sh build;bash scripts/ace-gates.sh test" LLM4TS_WORKTREE_SETUP= \\`,
-            `    llm4ts run epic-stories --repo ${targetRoot} -- --concurrency 2 ${JSON.stringify(epicSentence(file.design, api, service))}`
+            `  llm4ts run epic-stories --pack ace12-rest --repo ${targetRoot} -- --concurrency 2 ${JSON.stringify(epicSentence(file.design, api, service))}`
         ].join("\n"));
     }));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.44.0",
+  "version": "2.45.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",
     "@effect/platform-node-shared": "4.0.0",
-    "@llm4ts/core": "2.44.0",
-    "@llm4ts/runner": "2.44.0",
-    "@llm4ts/flow": "2.44.0"
+    "@llm4ts/flow": "2.45.0",
+    "@llm4ts/core": "2.45.0",
+    "@llm4ts/runner": "2.45.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"