@llm4ts/shell 0.17.0 → 0.18.1

package/kits/mainframe-java/README.md

@@ -0,0 +1,31 @@
+# Kit: mainframe-java
+
+COBOL/JCL and IBM ACE estates to Spring Boot and Kafka Streams services.
+
+A kit bundles everything the engine's `modernize-*` flows need to know about
+one legacy source and one target stack (ADR 0014). This one ships four packs,
+the two scaffolds they seed an empty target from, and a deck of 25 COBOL
+translation pattern cards that extraction tags onto each program's
+traceability and implementation injects into the coder's prompt.
+
+| Pack                                                 | Legacy → target                   | Scaffold                | Replay |
+| ---------------------------------------------------- | --------------------------------- | ----------------------- | ------ |
+| [`cobol-springboot`](packs/cobol-springboot/pack.md) | COBOL/JCL → Spring Boot service   | `spring-boot-service`   | yes    |
+| [`cobol-kafka`](packs/cobol-kafka/pack.md)           | COBOL/JCL → Kafka Streams service | `kafka-streams-service` | yes    |
+| [`ace-integration`](packs/ace-integration/pack.md)   | ACE msgflow/ESQL → Spring Boot    | `spring-boot-service`   | no     |
+| [`ace-kafka`](packs/ace-kafka/pack.md)               | ACE msgflow/ESQL → Kafka Streams  | `kafka-streams-service` | yes    |
+
+Packs without a `replay:` command run phases 0–3 and 5; phase 4 needs a
+replay harness in the target repository to drive equivalence vectors.
+`cobol-kafka` adds its own cards under `packs/cobol-kafka/patterns/` for
+event-streaming idioms on top of the kit's deck.
+
+```sh
+llm4ts run modernize-pack-check --pack cobol-springboot --repo /path/to/legacy-estate
+llm4ts run modernize-survey --pack cobol-springboot --repo /path/to/legacy-estate
+```
+
+`cobol-springboot` is the default pack when `--pack` and `LLM4TS_PACK` are
+both unset. Copy a pack directory next to your work and pass its path to
+iterate on it before it joins a kit; `kits/test/packs.test.ts` shows what
+the flows require of a manifest.

package/{flows → kits/mainframe-java}/packs/ace-integration/pack.md

@@ -1,7 +1,7 @@
 # Pack: ace-integration
 
 source: ace
-scaffold: ../../fixtures/scaffolds/spring-boot-service
+scaffold: ../../scaffolds/spring-boot-service
 sources: .*\.(msgflow|esql)
 specs-dir: docs/specs
 features-dir: src/test/resources/features

package/{flows → kits/mainframe-java}/packs/ace-kafka/pack.md

@@ -1,7 +1,7 @@
 # Pack: ace-kafka
 
 source: ace
-scaffold: ../../fixtures/scaffolds/kafka-streams-service
+scaffold: ../../scaffolds/kafka-streams-service
 sources: .*\.(msgflow|esql)
 programs: .*\.(msgflow|esql)
 specs-dir: docs/specs

package/{flows → kits/mainframe-java}/packs/cobol-kafka/pack.md

@@ -1,7 +1,7 @@
 # Pack: cobol-kafka
 
 source: cobol
-scaffold: ../../fixtures/scaffolds/kafka-streams-service
+scaffold: ../../scaffolds/kafka-streams-service
 sources: .*\.(cbl|CBL|cpy|CPY|jcl|JCL)
 programs: .*\.(cbl|CBL|jcl|JCL)
 specs-dir: docs/specs

package/{flows → kits/mainframe-java}/packs/cobol-springboot/pack.md

@@ -1,7 +1,7 @@
 # Pack: cobol-springboot
 
 source: cobol
-scaffold: ../../fixtures/scaffolds/spring-boot-service
+scaffold: ../../scaffolds/spring-boot-service
 sources: .*\.(cbl|CBL|cpy|CPY|jcl|JCL)
 programs: .*\.(cbl|CBL|jcl|JCL)
 specs-dir: docs/specs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,8 @@
   "files": [
     "dist",
     "src",
-    "flows"
+    "flows",
+    "kits"
   ],
   "exports": {
     "./Cli": "./dist/Cli.js",
@@ -50,10 +51,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0-beta.102",
     "@effect/platform-node-shared": "4.0.0-beta.102",
-    "@llm4ts/core": "0.17.0",
-    "@llm4ts/flow": "0.17.0",
-    "@llm4ts/runner": "0.17.0",
-    "@llm4ts/modernize": "0.17.0"
+    "@llm4ts/core": "0.18.1",
+    "@llm4ts/flow": "0.18.1",
+    "@llm4ts/runner": "0.18.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.102"

package/src/Cli.ts

@@ -9,6 +9,7 @@ import * as Command from "effect/unstable/cli/Command"
 import * as Flag from "effect/unstable/cli/Flag"
 import { makeCliProgram } from "@llm4ts/runner/Cli"
 import { makeDoctorProgram } from "@llm4ts/runner/Doctor"
+import { builtinKitsDir, discoverKits, kitTierPaths, type DiscoveredKit } from "@llm4ts/runner/Kits"
 import {
   defaultTierPaths,
   discoverFlows,
@@ -32,17 +33,61 @@ export const builtinFlowsDir = (): string => fileURLToPath(new URL("../flows", i
 export const shellTierPaths = (options?: {
   readonly cwd?: string
   readonly environment?: Readonly<Record<string, string | undefined>>
-}): FlowTierPaths =>
-  defaultTierPaths({
-    cwd: options?.cwd ?? process.cwd(),
-    homeDir: homedir(),
-    environment: options?.environment ?? process.env,
-    builtinDir: builtinFlowsDir()
-  })
+}): FlowTierPaths => {
+  const cwd = options?.cwd ?? process.cwd()
+  const environment = options?.environment ?? process.env
+  const builtinKits = builtinKitsDir(builtinFlowsDir())
+  return {
+    ...defaultTierPaths({ cwd, homeDir: homedir(), environment, builtinDir: builtinFlowsDir() }),
+    kits: kitTierPaths({
+      cwd,
+      homeDir: homedir(),
+      environment,
+      ...(builtinKits === undefined ? {} : { builtinDir: builtinKits })
+    })
+  }
+}
 
 const tierLabel = (flow: DiscoveredFlow): string => {
+  const kit = flow.kit === undefined ? "" : ` kit:${flow.kit}`
   const shadows = flow.shadows.length === 0 ? "" : ` shadows ${flow.shadows.join(", ")}`
-  return `[${flow.tier}${shadows}]`
+  return `[${flow.tier}${kit}${shadows}]`
+}
+
+export const renderKitList = (
+  kits: ReadonlyArray<DiscoveredKit>,
+  options?: { readonly json?: boolean }
+): string => {
+  if (options?.json === true) {
+    return JSON.stringify(
+      kits.map((kit) => ({
+        name: kit.name,
+        tier: kit.tier,
+        path: kit.root,
+        ...(kit.description === undefined ? {} : { description: kit.description }),
+        packs: kit.packs,
+        flows: kit.flows,
+        shadows: kit.shadows
+      })),
+      undefined,
+      2
+    )
+  }
+  const nameWidth = kits.reduce((width, kit) => Math.max(width, kit.name.length), 0)
+  return kits
+    .flatMap((kit) => {
+      const shadows = kit.shadows.length === 0 ? "" : ` shadows ${kit.shadows.join(", ")}`
+      return [
+        [
+          kit.name.padEnd(nameWidth),
+          `[${kit.tier}${shadows}]`,
+          ...(kit.description === undefined ? [] : [kit.description])
+        ].join("  "),
+        ...(kit.packs.length === 0 ? [] : [`  packs: ${kit.packs.join(", ")}`]),
+        ...(kit.flows.length === 0 ? [] : [`  flows: ${kit.flows.join(", ")}`])
+      ]
+    })
+    .join("\n")
 }
 
 export const renderFlowList = (
@@ -55,6 +100,7 @@ export const renderFlowList = (
         name: flow.name,
         tier: flow.tier,
         path: flow.path,
+        ...(flow.kit === undefined ? {} : { kit: flow.kit }),
         ...(flow.description === undefined ? {} : { description: flow.description }),
         shadows: flow.shadows
       })),
@@ -121,6 +167,12 @@ const runCommand = Command.make(
         "Repository to run against, forwarded to the flow as --repo (defaults to the current directory)"
       )
     ),
+    pack: Flag.string("pack").pipe(
+      Flag.optional,
+      Flag.withDescription(
+        "Pack for the modernization flows, forwarded as LLM4TS_PACK: a kit pack name from `llm4ts kits`, kit/pack, or a directory holding pack.md"
+      )
+    ),
     verbose: Flag.boolean("verbose").pipe(Flag.withDescription("Stream verbose flow output"))
   },
   (config) =>
@@ -131,6 +183,9 @@ const runCommand = Command.make(
       if (config.verbose) {
         environment.LLM4TS_VERBOSITY = "verbose"
       }
+      if (config.pack._tag === "Some") {
+        environment.LLM4TS_PACK = config.pack.value
+      }
       const exitCode = yield* launchFlow({
         flowPath,
         taskArgs: [
@@ -161,6 +216,27 @@ const listCommand = Command.make(
     })
 ).pipe(Command.withDescription("List flows across the project, global, and built-in tiers"))
 
+const kitsCommand = Command.make(
+  "kits",
+  {
+    json: Flag.boolean("json").pipe(Flag.withDescription("Emit the listing as JSON"))
+  },
+  (config) =>
+    Effect.gen(function* () {
+      const tiers = shellTierPaths()
+      const kits = tiers.kits === undefined ? [] : discoverKits(tiers.kits)
+      if (kits.length === 0 && !config.json) {
+        yield* Console.error("no kits discovered — add kit directories under .llm4ts/kits/")
+        return
+      }
+      yield* Console.log(renderKitList(kits, { json: config.json }))
+    })
+).pipe(
+  Command.withDescription(
+    "List kits — packs, scaffolds, pattern cards, and flows — across the project, global, and built-in tiers"
+  )
+)
+
 const viewCommand = Command.make(
   "view",
   {
@@ -230,7 +306,14 @@ export const shellCommand = Command.make("llm4ts", {}, () =>
   Command.withDescription(
     "Interactive shell and CLI for llm4ts flows: discover, inspect, and run them."
   ),
-  Command.withSubcommands([runCommand, listCommand, viewCommand, askCommand, doctorCommand])
+  Command.withSubcommands([
+    runCommand,
+    listCommand,
+    kitsCommand,
+    viewCommand,
+    askCommand,
+    doctorCommand
+  ])
 )
 
 export const runShellCommand = (

package/src/FlowCatalog.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path"
 import * as Effect from "effect/Effect"
 import { FileSystem } from "effect/FileSystem"
+import { discoverKits, type KitTierPaths } from "@llm4ts/runner/Kits"
 
 export type FlowTier = "project" | "global" | "builtin"
 
@@ -8,12 +9,16 @@ export interface FlowTierPaths {
   readonly project?: string
   readonly global?: string
   readonly builtin?: string
+  /** Kit tiers whose `flows/` join the listing under the kit's tier (ADR 0014). */
+  readonly kits?: KitTierPaths
 }
 
 export interface DiscoveredFlow {
   readonly name: string
   readonly path: string
   readonly tier: FlowTier
+  /** The kit the flow ships in, when it is a kit flow rather than a tier's own. */
+  readonly kit?: string
   readonly description?: string
   readonly shadows: ReadonlyArray<FlowTier>
 }
@@ -69,7 +74,8 @@ const flowExtension = (entry: string): string | undefined =>
 
 const listTier = Effect.fn("@llm4ts/shell/FlowCatalog.listTier")(function* (
   tier: FlowTier,
-  directory: string
+  directory: string,
+  kit?: string
 ) {
   const fs = yield* FileSystem
   const entries = yield* fs.readDirectory(directory).pipe(Effect.orElseSucceed(() => []))
@@ -86,6 +92,7 @@ const listTier = Effect.fn("@llm4ts/shell/FlowCatalog.listTier")(function* (
       name: entry.slice(0, -extension.length),
       path,
       tier,
+      ...(kit === undefined ? {} : { kit }),
       ...(description === undefined ? {} : { description })
     })
   }
@@ -93,10 +100,11 @@ const listTier = Effect.fn("@llm4ts/shell/FlowCatalog.listTier")(function* (
 })
 
 /**
- * Discovers flows across the project, global, and built-in tiers. Precedence
- * is project > global > builtin, keyed by flow name; a shadowed tier is
- * recorded on the winning flow's `shadows` list. Missing or unreadable
- * directories contribute nothing.
+ * Discovers flows across the project, global, and built-in tiers, each tier's
+ * own `flows/` first and then the `flows/` of the kits discovered in that
+ * tier. Precedence is project > global > builtin, keyed by flow name; a
+ * shadowed tier is recorded on the winning flow's `shadows` list. Missing or
+ * unreadable directories contribute nothing.
  */
 export const discoverFlows = Effect.fn("@llm4ts/shell/FlowCatalog.discoverFlows")(function* (
   tiers: FlowTierPaths
@@ -105,17 +113,25 @@ export const discoverFlows = Effect.fn("@llm4ts/shell/FlowCatalog.discoverFlows"
     string,
     { flow: Omit<DiscoveredFlow, "shadows">; shadows: Array<FlowTier> }
   >()
+  const kits = tiers.kits === undefined ? [] : discoverKits(tiers.kits)
+  const record = (flow: Omit<DiscoveredFlow, "shadows">): void => {
+    const existing = byName.get(flow.name)
+    if (existing === undefined) {
+      byName.set(flow.name, { flow, shadows: [] })
+    } else {
+      existing.shadows.push(flow.tier)
+    }
+  }
   for (const tier of tierOrder) {
     const directory = tiers[tier]
-    if (directory === undefined) {
-      continue
+    if (directory !== undefined) {
+      for (const flow of yield* listTier(tier, directory)) {
+        record(flow)
+      }
     }
-    for (const flow of yield* listTier(tier, directory)) {
-      const existing = byName.get(flow.name)
-      if (existing === undefined) {
-        byName.set(flow.name, { flow, shadows: [] })
-      } else {
-        existing.shadows.push(tier)
+    for (const kit of kits.filter((candidate) => candidate.tier === tier)) {
+      for (const flow of yield* listTier(tier, join(kit.root, "flows"), kit.name)) {
+        record(flow)
       }
     }
   }