@llm4ts/shell 0.17.0 → 0.18.1

package/kits/j2ee-nextjs/fixtures/demo-bank/preflight.mjs

@@ -0,0 +1,53 @@
+// Workshop preflight: verify the demo environment before the audience
+// arrives. Seeds both fixtures into a temp dir via their smoke checks and
+// verifies the tools the runbook depends on. Exits nonzero, loudly, on any
+// failure — fix everything red before demo day.
+import { execFileSync } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { dirname, join } from "node:path"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const failures = []
+
+const check = (label, run) => {
+  try {
+    run()
+    console.log(`ok    ${label}`)
+  } catch (error) {
+    failures.push(label)
+    console.error(`FAIL  ${label}: ${error.message ?? error}`)
+  }
+}
+
+const tool = (label, command, args) =>
+  check(label, () => execFileSync(command, args, { stdio: "pipe" }))
+
+tool("git available", "git", ["--version"])
+tool("node >= 20", "node", ["--version"])
+tool("pnpm available", "pnpm", ["--version"])
+tool("claude CLI available (the coder seat)", "claude", ["--version"])
+check("llm4ts CLI available", () => execFileSync("llm4ts", ["--version"], { stdio: "pipe" }))
+check("llm4ts kits ships j2ee-nextjs/j2ee-nextjs-spa (ADR 0014)", () => {
+  const kits = JSON.parse(execFileSync("llm4ts", ["kits", "--json"], { encoding: "utf8" }))
+  const kit = kits.find((candidate) => candidate.name === "j2ee-nextjs")
+  if (kit === undefined || !kit.packs.includes("j2ee-nextjs-spa")) {
+    throw new Error("the j2ee-nextjs kit or its j2ee-nextjs-spa pack is missing — upgrade @llm4ts/shell to 0.18.0+")
+  }
+})
+
+check("legacy fixture seeds + smoke", () =>
+  execFileSync("node", [join(here, "smoke-legacy-j2ee.mjs")], { stdio: "pipe" })
+)
+check("nextjs fixture seeds + smoke", () =>
+  execFileSync("node", [join(here, "smoke-nextjs.mjs")], { stdio: "pipe" })
+)
+
+if (process.env.LLM4TS_LEGACY_REPO === undefined) {
+  console.log("note  LLM4TS_LEGACY_REPO is not set yet — the runbook exports it in Act 0")
+}
+
+if (failures.length > 0) {
+  console.error(`\npreflight FAILED: ${failures.join("; ")}`)
+  process.exit(1)
+}
+console.log("\npreflight OK — run reset-demo.mjs to materialize the estate")

package/kits/j2ee-nextjs/fixtures/demo-bank/reset-demo.mjs

@@ -0,0 +1,40 @@
+// Workshop reset: (re)materialize the demo estate so every rehearsal and the
+// real run start identical. Wipes ONLY the two repos it owns under the given
+// root, re-seeds both fixtures, and warms the target's node_modules from the
+// pnpm store (run once with network before demo day; offline afterwards).
+import { execFileSync } from "node:child_process"
+import { existsSync, rmSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = resolve(process.argv[2] ?? ".demo-bank")
+const legacy = join(root, "legacy-j2ee")
+const target = join(root, "nextjs")
+
+for (const path of [legacy, target]) {
+  if (existsSync(path)) {
+    rmSync(path, { recursive: true, force: true })
+    console.log(`removed ${path}`)
+  }
+}
+
+const run = (command, args, cwd) =>
+  execFileSync(command, args, { stdio: "inherit", ...(cwd === undefined ? {} : { cwd }) })
+
+run("node", [join(here, "seed-legacy-j2ee.mjs"), legacy])
+run("node", [join(here, "seed-nextjs.mjs"), target])
+
+console.log("installing target dependencies (uses the warm pnpm store when offline)...")
+try {
+  run("pnpm", ["install", "--ignore-workspace", "--prefer-offline"], target)
+} catch {
+  console.error(
+    "pnpm install failed — if you are offline, warm the store once with network:\n" +
+      `  cd ${target} && pnpm install --ignore-workspace`
+  )
+  process.exit(1)
+}
+
+console.log(`\ndemo estate ready:\n  legacy: ${legacy}\n  target: ${target}`)
+console.log(`next: export LLM4TS_LEGACY_REPO=${legacy} (see RUNBOOK.md Act 0)`)

package/kits/j2ee-nextjs/fixtures/demo-bank/seed-legacy-j2ee.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Materialize the synthetic legacy J2EE fixture (kits/j2ee-nextjs/fixtures/demo-bank/legacy-j2ee)
+// as a standalone git repository. The demo flows need a real repo root, not a
+// subdirectory of llm4ts.
+//
+//   node kits/j2ee-nextjs/fixtures/demo-bank/seed-legacy-j2ee.mjs [target-dir] [--force]
+//
+// Default target: .demo-bank/legacy-j2ee under the current working directory.
+// Refuses to overwrite a non-empty target unless --force is given.
+// Deterministic: fixed commit author/committer and date, no network.
+
+import { execFileSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const fixtureDir = path.join(scriptDir, "legacy-j2ee")
+
+const args = process.argv.slice(2)
+const force = args.includes("--force")
+const positional = args.filter((a) => a !== "--force")
+
+if (positional.some((a) => a.startsWith("--"))) {
+  console.error(`unknown flag: ${positional.find((a) => a.startsWith("--"))}`)
+  console.error("usage: node seed-legacy-j2ee.mjs [target-dir] [--force]")
+  process.exit(2)
+}
+if (positional.length > 1) {
+  console.error("only one target directory may be supplied")
+  process.exit(2)
+}
+
+const target = path.resolve(positional[0] ?? path.join(process.cwd(), ".demo-bank", "legacy-j2ee"))
+
+if (!fs.existsSync(fixtureDir)) {
+  console.error(`fixture source missing: ${fixtureDir}`)
+  process.exit(1)
+}
+
+if (fs.existsSync(target) && fs.readdirSync(target).length > 0) {
+  if (!force) {
+    console.error(`target is not empty: ${target} (use --force to overwrite)`)
+    process.exit(2)
+  }
+  fs.rmSync(target, { recursive: true, force: true })
+}
+
+fs.mkdirSync(target, { recursive: true })
+fs.cpSync(fixtureDir, target, { recursive: true })
+
+// Fixed identity and date so seeded repos are deterministic.
+const gitEnv = {
+  ...process.env,
+  GIT_AUTHOR_NAME: "Demo Bank",
+  GIT_AUTHOR_EMAIL: "demo@example.invalid",
+  GIT_AUTHOR_DATE: "2020-01-01T00:00:00Z",
+  GIT_COMMITTER_NAME: "Demo Bank",
+  GIT_COMMITTER_EMAIL: "demo@example.invalid",
+  GIT_COMMITTER_DATE: "2020-01-01T00:00:00Z"
+}
+
+const git = (...gitArgs) =>
+  execFileSync("git", gitArgs, { cwd: target, env: gitEnv, stdio: "pipe" })
+
+git("init", "-q", "-b", "main")
+git("add", "-A")
+git("commit", "-q", "-m", "Import DemoBank legacy portal")
+
+console.log(target)

package/kits/j2ee-nextjs/fixtures/demo-bank/seed-nextjs.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Seed the DemoBank Next.js SPA fixture into a standalone git repository.
+//
+//   node kits/j2ee-nextjs/fixtures/demo-bank/seed-nextjs.mjs [target-dir] [--force]
+//
+// target-dir defaults to .demo-bank/nextjs (relative to the current working
+// directory). --force overwrites an existing target. node_modules, .next and
+// out are never copied. The initial commit is deterministic: fixed author
+// "Demo Bank <demo@example.invalid>" and fixed date 2020-01-01T00:00:00Z.
+//
+// Offline note: the fixture commits pnpm-lock.yaml. To install without
+// network in the seeded repo, warm the pnpm store once while online
+// (`pnpm install --ignore-workspace` in kits/j2ee-nextjs/fixtures/demo-bank/nextjs), then run
+// `pnpm install --ignore-workspace --offline` in the seeded copy.
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const SOURCE_DIR = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'nextjs',
+);
+
+const EXCLUDED_NAMES = new Set(['node_modules', '.next', 'out', '.git']);
+
+const AUTHOR_NAME = 'Demo Bank';
+const AUTHOR_EMAIL = 'demo@example.invalid';
+const COMMIT_DATE = '2020-01-01T00:00:00Z';
+
+function fail(message) {
+  process.stderr.write(`seed-nextjs: ${message}\n`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  let targetDir = null;
+  let force = false;
+  for (const arg of argv) {
+    if (arg === '--force') {
+      force = true;
+    } else if (arg.startsWith('--')) {
+      fail(`unknown option: ${arg}`);
+    } else if (targetDir === null) {
+      targetDir = arg;
+    } else {
+      fail(`unexpected argument: ${arg}`);
+    }
+  }
+  return {
+    targetDir: path.resolve(targetDir ?? path.join('.demo-bank', 'nextjs')),
+    force,
+  };
+}
+
+function git(cwd, args, env = {}) {
+  execFileSync('git', args, {
+    cwd,
+    stdio: ['ignore', 'ignore', 'inherit'],
+    env: { ...process.env, ...env },
+  });
+}
+
+const { targetDir, force } = parseArgs(process.argv.slice(2));
+
+if (!fs.existsSync(SOURCE_DIR)) {
+  fail(`fixture source not found: ${SOURCE_DIR}`);
+}
+
+if (fs.existsSync(targetDir)) {
+  if (!force) {
+    fail(`target already exists: ${targetDir} (use --force to overwrite)`);
+  }
+  fs.rmSync(targetDir, { recursive: true, force: true });
+}
+
+fs.mkdirSync(targetDir, { recursive: true });
+fs.cpSync(SOURCE_DIR, targetDir, {
+  recursive: true,
+  filter: (source) => !EXCLUDED_NAMES.has(path.basename(source)),
+});
+
+git(targetDir, ['init', '--quiet', '-b', 'main']);
+git(targetDir, ['add', '-A']);
+git(
+  targetDir,
+  [
+    '-c',
+    `user.name=${AUTHOR_NAME}`,
+    '-c',
+    `user.email=${AUTHOR_EMAIL}`,
+    '-c',
+    'commit.gpgsign=false',
+    'commit',
+    '--quiet',
+    '-m',
+    'Seed DemoBank Next.js SPA fixture',
+  ],
+  {
+    GIT_AUTHOR_NAME: AUTHOR_NAME,
+    GIT_AUTHOR_EMAIL: AUTHOR_EMAIL,
+    GIT_AUTHOR_DATE: COMMIT_DATE,
+    GIT_COMMITTER_NAME: AUTHOR_NAME,
+    GIT_COMMITTER_EMAIL: AUTHOR_EMAIL,
+    GIT_COMMITTER_DATE: COMMIT_DATE,
+  },
+);
+
+process.stdout.write(`Seeded DemoBank Next.js fixture at ${targetDir}\n`);

package/kits/j2ee-nextjs/fixtures/demo-bank/smoke-legacy-j2ee.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// Smoke check for the legacy J2EE fixture seed script. Deterministic and
+// network-free: seeds into a temp directory, asserts the produced git repo
+// contains the expected file set, and cleans up.
+//
+//   node kits/j2ee-nextjs/fixtures/demo-bank/smoke-legacy-j2ee.mjs
+
+import { execFileSync, spawnSync } from "node:child_process"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const seedScript = path.join(scriptDir, "seed-legacy-j2ee.mjs")
+
+const WEBAPP = "src/main/webapp"
+const JAVA = "src/main/java/com/demobank/legacy"
+
+// Explicit answer-key file list (relative to the seeded repo root).
+const expectedFiles = [
+  "PAGES.md",
+  "pom.xml",
+  // shared shell
+  `${WEBAPP}/WEB-INF/web.xml`,
+  `${WEBAPP}/header.jsp`,
+  `${WEBAPP}/footer.jsp`,
+  `${WEBAPP}/nav.jsp`,
+  `${WEBAPP}/js/jquery-1.12.4.min.js`,
+  `${WEBAPP}/js/validate.js`,
+  `${WEBAPP}/css/bank.css`,
+  // hero 1: account overview
+  `${WEBAPP}/accountOverview.jsp`,
+  `${JAVA}/web/AccountOverviewServlet.java`,
+  `${JAVA}/dto/AcctOvwDTO.java`,
+  `${JAVA}/esb/EsbAcctListService.java`,
+  // hero 2: beneficiary management
+  `${WEBAPP}/beneficiaryList.jsp`,
+  `${WEBAPP}/beneficiaryEdit.jsp`,
+  `${JAVA}/web/BeneficiaryServlet.java`,
+  `${JAVA}/dto/BenfDTO.java`,
+  `${JAVA}/esb/EsbBenfListService.java`,
+  `${JAVA}/esb/EsbBenfMaintService.java`,
+  // hero 3: wire transfer
+  `${WEBAPP}/transferStep1.jsp`,
+  `${WEBAPP}/transferStep2.jsp`,
+  `${WEBAPP}/transferConfirm.jsp`,
+  `${JAVA}/web/TransferServlet.java`,
+  `${JAVA}/web/TransferDraft.java`,
+  `${JAVA}/dto/TrfDTO.java`,
+  `${JAVA}/esb/EsbTrfValidateService.java`,
+  `${JAVA}/esb/EsbTrfExecService.java`,
+  // esb plumbing
+  `${JAVA}/esb/EsbGateway.java`,
+  `${JAVA}/esb/EsbException.java`,
+  // filler pages
+  `${WEBAPP}/login.jsp`,
+  `${WEBAPP}/dashboard.jsp`,
+  `${WEBAPP}/settings.jsp`,
+  `${WEBAPP}/help.jsp`,
+  `${WEBAPP}/messages.jsp`,
+  `${WEBAPP}/profile.jsp`,
+  // dead pages (unreferenced from nav/web.xml, but must exist)
+  `${WEBAPP}/oldTransfer.jsp`,
+  `${WEBAPP}/promoQ3.jsp`,
+  `${WEBAPP}/testHarness.jsp`
+]
+
+let tempRoot
+const failures = []
+try {
+  tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "demo-bank-smoke-"))
+  const repoDir = path.join(tempRoot, "legacy-j2ee")
+
+  const seed = spawnSync(process.execPath, [seedScript, repoDir], {
+    encoding: "utf8"
+  })
+  if (seed.status !== 0) {
+    console.error("seed script failed:")
+    console.error(seed.stdout)
+    console.error(seed.stderr)
+    process.exit(1)
+  }
+  const printed = seed.stdout.trim().split("\n").pop()
+  if (printed !== repoDir) {
+    failures.push(`seed script printed "${printed}", expected "${repoDir}"`)
+  }
+
+  if (!fs.existsSync(path.join(repoDir, ".git"))) {
+    failures.push("seeded target is not a git repository (.git missing)")
+  } else {
+    const head = execFileSync("git", ["-C", repoDir, "log", "--format=%an <%ae> %aI", "-1"], {
+      encoding: "utf8"
+    }).trim()
+    if (!head.startsWith("Demo Bank <demo@example.invalid> 2020-01-01")) {
+      failures.push(`unexpected commit identity/date: ${head}`)
+    }
+    const dirty = execFileSync("git", ["-C", repoDir, "status", "--porcelain"], {
+      encoding: "utf8"
+    }).trim()
+    if (dirty.length > 0) {
+      failures.push(`seeded repo has uncommitted files:\n${dirty}`)
+    }
+  }
+
+  for (const rel of expectedFiles) {
+    const abs = path.join(repoDir, rel)
+    if (!fs.existsSync(abs)) {
+      failures.push(`missing expected file: ${rel}`)
+    } else if (fs.statSync(abs).size === 0) {
+      failures.push(`expected file is empty: ${rel}`)
+    }
+  }
+
+  // Overwrite guard: re-seeding the same non-empty target must fail...
+  const second = spawnSync(process.execPath, [seedScript, repoDir], {
+    encoding: "utf8"
+  })
+  if (second.status === 0) {
+    failures.push("seed script overwrote a non-empty target without --force")
+  }
+  // ...and succeed with --force.
+  const forced = spawnSync(process.execPath, [seedScript, repoDir, "--force"], {
+    encoding: "utf8"
+  })
+  if (forced.status !== 0) {
+    failures.push(`seed script --force failed: ${forced.stderr}`)
+  }
+} finally {
+  if (tempRoot) {
+    fs.rmSync(tempRoot, { recursive: true, force: true })
+  }
+}
+
+if (failures.length > 0) {
+  console.error("legacy-j2ee smoke FAILED:")
+  for (const f of failures) {
+    console.error(`  - ${f}`)
+  }
+  process.exit(1)
+}
+
+console.log(`legacy-j2ee smoke OK: ${expectedFiles.length} files verified in seeded git repo`)

package/kits/j2ee-nextjs/fixtures/demo-bank/smoke-nextjs.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Smoke check for the DemoBank Next.js SPA fixture: seeds into a temp dir,
+// asserts the expected files exist and the seed commit is deterministic,
+// then cleans up. Network-free; safe for CI.
+//
+//   node kits/j2ee-nextjs/fixtures/demo-bank/smoke-nextjs.mjs
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SEED_SCRIPT = path.join(HERE, 'seed-nextjs.mjs');
+
+const EXPECTED_FILES = [
+  // Configs
+  'package.json',
+  'pnpm-lock.yaml',
+  'tsconfig.json',
+  'next.config.mjs',
+  'next-env.d.ts',
+  'eslint.config.mjs',
+  'vitest.config.ts',
+  '.gitignore',
+  // Docs
+  'README.md',
+  'CONTRIBUTING.md',
+  // Theme + design system
+  'src/theme/tokens.css',
+  'src/theme/components.css',
+  'src/components/Button.tsx',
+  'src/components/Field.tsx',
+  'src/components/Form.tsx',
+  'src/components/DataTable.tsx',
+  'src/components/Stepper.tsx',
+  'src/components/Card.tsx',
+  'src/components/PageLayout.tsx',
+  'src/components/index.ts',
+  // Auth stub + app shell
+  'src/auth/AuthProvider.tsx',
+  'src/app/layout.tsx',
+  'src/app/signed-in-badge.tsx',
+  'src/app/page.tsx',
+  // Exemplar pages
+  'src/app/cards/page.tsx',
+  'src/app/profile/page.tsx',
+  // Ports, adapters, registry
+  'src/services/registry.ts',
+  'src/services/cards/port.ts',
+  'src/services/cards/mock.ts',
+  'src/services/profile/port.ts',
+  'src/services/profile/mock.ts',
+  // Contracts
+  'contracts/cards.openapi.yaml',
+  'contracts/profile.openapi.yaml',
+  // Tests
+  'tests/cards.page.test.tsx',
+  'tests/profile.page.test.tsx',
+];
+
+const EXCLUDED_DIRS = ['node_modules', '.next', 'out'];
+
+function fail(message) {
+  process.stderr.write(`smoke-nextjs: FAIL: ${message}\n`);
+  process.exitCode = 1;
+}
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'demo-bank-smoke-'));
+const target = path.join(tempRoot, 'nextjs');
+
+try {
+  execFileSync(process.execPath, [SEED_SCRIPT, target], {
+    stdio: ['ignore', 'ignore', 'inherit'],
+  });
+
+  const missing = EXPECTED_FILES.filter(
+    (file) => !fs.existsSync(path.join(target, file)),
+  );
+  if (missing.length > 0) {
+    fail(`seeded repo is missing expected files:\n  - ${missing.join('\n  - ')}`);
+  }
+
+  for (const dir of EXCLUDED_DIRS) {
+    if (fs.existsSync(path.join(target, dir))) {
+      fail(`seeded repo must not contain ${dir}/`);
+    }
+  }
+
+  const gitLog = execFileSync(
+    'git',
+    ['log', '--format=%an <%ae> %at', 'main'],
+    { cwd: target, encoding: 'utf8' },
+  ).trim();
+  const commits = gitLog.length === 0 ? [] : gitLog.split('\n');
+  if (commits.length !== 1) {
+    fail(`expected exactly 1 seed commit, found ${commits.length}`);
+  }
+  // 1577836800 = 2020-01-01T00:00:00Z
+  const expectedAuthor = 'Demo Bank <demo@example.invalid> 1577836800';
+  if (commits[0] !== expectedAuthor) {
+    fail(
+      `seed commit is not deterministic:\n  expected: ${expectedAuthor}\n  actual:   ${commits[0]}`,
+    );
+  }
+
+  if (process.exitCode !== 1) {
+    process.stdout.write(
+      `smoke-nextjs: OK (${EXPECTED_FILES.length} files verified in seeded repo)\n`,
+    );
+  }
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+} finally {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}

package/{flows → kits/j2ee-nextjs/flows}/convert-all.js

@@ -23,13 +23,7 @@ import * as Effect from "effect/Effect";
 import { AdoConfig, makeAzureDevOpsTool } from "@llm4ts/flow/AzureDevOpsTool";
 import { BoardItem, composeBoardSync, makeAdoBoardSync, makeLocalBoardSync } from "@llm4ts/flow/BoardSync";
 import { describeFlowError } from "@llm4ts/flow/FlowError";
-import { Info } from "@llm4ts/flow/FlowEvents";
-import { stage } from "@llm4ts/flow/PlanExecution";
-import { asReadOnly, coderFromEnv } from "@llm4ts/runner/Connectors";
-import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
-import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
-import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore";
-import { nodeProcessExecutor } from "@llm4ts/runner/NodeProcessExecutor";
+import { Info, asReadOnly, coderFromEnv, nodePlainFileStore, nodeProcessExecutor, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
 import { conversionInventory, convertPage, migrationReport, setupConversion } from "./lib/convert.js";
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Convert the legacy estate into the destination SPA");

package/{flows → kits/j2ee-nextjs/flows}/convert-page.js

@@ -16,13 +16,9 @@
 // branch awaits human review; the conversion report is committed with it.
 // Token/cost figures are ESTIMATES (LLM4TS_ESTIMATE_MODEL,
 // LLM4TS_ESTIMATE_CHARS_PER_TOKEN). Pack: LLM4TS_PACK (default
-// packs/j2ee-nextjs-spa).
+// j2ee-nextjs-spa, from the j2ee-nextjs kit).
 import * as Effect from "effect/Effect";
-import { FlowAborted } from "@llm4ts/flow/FlowError";
-import { Info } from "@llm4ts/flow/FlowEvents";
-import { asReadOnly, coderFromEnv } from "@llm4ts/runner/Connectors";
-import { resolveFlowInput } from "@llm4ts/runner/FlowArgs";
-import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner";
+import { FlowAborted, Info, asReadOnly, coderFromEnv, resolveFlowInput, runFlowMain, runNode } from "@llm4ts/runner";
 import { convertPage, setupConversion } from "./lib/convert.js";
 const program = Effect.gen(function* () {
     const input = yield* resolveFlowInput("Convert one legacy page into the destination SPA");

package/{flows → kits/j2ee-nextjs/flows}/lib/convert.js

@@ -8,26 +8,16 @@ import * as Effect from "effect/Effect";
 import { Dimension } from "@llm4ts/core/eval/Eval";
 import { judge } from "@llm4ts/core/eval/Judge";
 import { TokenUsage } from "@llm4ts/core/Models";
-import { makeChat } from "@llm4ts/flow/Chat";
+import { FlowAborted, Info, Plan, implementPlanFlow, lintCommand, loadKitPatternCards, makeChat, makeNodeWorkspace, makePlanStore, mergeReviewResults, minimalReviewers, nodePlainFileStore, nodeProcessExecutor, openPack, reviewFingerprint, stage } from "@llm4ts/runner";
 import { budget, capped } from "@llm4ts/flow/Context";
-import { implementPlanFlow } from "@llm4ts/flow/Flow";
-import { FlowAborted } from "@llm4ts/flow/FlowError";
-import { FlowEvents, Info } from "@llm4ts/flow/FlowEvents";
+import { FlowEvents } from "@llm4ts/flow/FlowEvents";
 import { openApiFor, parsePageSpec, renderPageSpec } from "@llm4ts/flow/PageSpec";
 import { loadPatternCards, matchingPatternCards } from "@llm4ts/flow/Patterns";
-import { makePlanStore } from "@llm4ts/flow/Persistence";
-import { Plan, Task } from "@llm4ts/flow/Plan";
-import { stage } from "@llm4ts/flow/PlanExecution";
+import { Task } from "@llm4ts/flow/Plan";
 import { judgeAllPrograms } from "@llm4ts/flow/ProgramJudge";
-import { lintCommand, mergeReviewResults, minimalReviewers } from "@llm4ts/flow/Review";
 import { closureFor, surveyGraph } from "@llm4ts/flow/Survey";
 import { estimatedUsageOptionsFromEnv, makeEstimatedUsageMeter } from "@llm4ts/flow/EstimatedUsage";
 import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
-import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore";
-import { nodeProcessExecutor } from "@llm4ts/runner/NodeProcessExecutor";
-import { makeNodeWorkspace } from "@llm4ts/runner/NodeWorkspace";
-import { loadUniversalPatternCards, openPack } from "@llm4ts/runner/Packs";
-import { reviewFingerprint } from "@llm4ts/runner/ReviewFingerprint";
 export const positiveEnvInt = (environment, name, fallback) => {
     const raw = Number.parseInt(environment[name] ?? "", 10);
     return Number.isFinite(raw) && raw > 0 ? raw : fallback;
@@ -339,7 +329,7 @@ export const convertPage = Effect.fn("convert.page")(function* (deps, page) {
 /**
  * The common wiring of both conversion flows: metered seats (estimates-only
  * accounting), the two workspaces (legacy read-only limits, target default),
- * the pack (default `packs/j2ee-nextjs-spa`), and the pattern-card deck.
+ * the pack (default `j2ee-nextjs-spa`, from the kit), and the pattern-card deck.
  */
 export const setupConversion = Effect.fn("convert.setup")(function* (context, input, environment, flowDir) {
     const legacyRaw = environment.LLM4TS_LEGACY_REPO;
@@ -362,14 +352,14 @@ export const setupConversion = Effect.fn("convert.setup")(function* (context, in
     const opened = yield* stage(context.events, "pack", openPack({
         environment: {
             ...environment,
-            LLM4TS_PACK: environment.LLM4TS_PACK ?? "packs/j2ee-nextjs-spa"
+            LLM4TS_PACK: environment.LLM4TS_PACK ?? "j2ee-nextjs-spa"
         },
         launchDir: input.workspace,
         flowDir
     }));
     const cards = [
         ...(yield* loadPatternCards(opened.workspace, `${opened.dir}/patterns`)),
-        ...(yield* loadUniversalPatternCards([input.workspace, flowDir]))
+        ...(yield* loadKitPatternCards(opened))
     ];
     return {
         context: metered,

package/{flows → kits/j2ee-nextjs}/packs/j2ee-nextjs-spa/pack.md

@@ -1,8 +1,9 @@
 # Pack: j2ee-nextjs-spa
 
 source: jsp
-scaffold: ../../fixtures/scaffolds/nextjs-spa
+scaffold: ../../scaffolds/nextjs-spa
 sources: .*\.(jsp|java|xml)
+spec-schema: pagespec
 programs: .*\.jsp
 specs-dir: docs/modernization/specs
 features-dir: docs/modernization/features

package/{flows → kits/j2ee-nextjs}/packs/j2ee-nextjs-spa/prompts/spec.md

@@ -23,7 +23,11 @@ The spec markdown for a page has two mandatory parts:
        "domainName", "type" }] }],
      "apiCalls": [{ "operation": "<domain verb, e.g. listAccounts>",
        "method", "path", "esbService", "request": [{ "legacyName",
-       "domainName", "type" }], "response": [{ ... }] }],
+       "domainName", "type" }],
+       "response": [{ "legacyName", "domainName", "type" }]   // ad-hoc object, OR
+       "responseDto": "<domainName of one of the dtos>",       // the DTO returned,
+       "responseShape": "single" | "list"                     // a table screen is a list
+     }],
      "navigation": { "inbound": [], "outbound": [], "steps": [] },
      "sessionState": ["<what the session carries and why>"],
      "openQuestions": []

package/{flows → kits/j2ee-nextjs}/packs/jsp-bff-nextjs/pack.md

@@ -1,7 +1,7 @@
 # Pack: jsp-bff-nextjs
 
 source: jsp
-scaffold: ../../fixtures/scaffolds/spring-bff
+scaffold: ../../scaffolds/spring-bff
 sources: .*\.(jsp|java|xml)
 programs: .*\.(jsp|java)
 specs-dir: docs/specs

package/{flows → kits/j2ee-nextjs}/packs/jsp-nextjs/pack.md

@@ -1,7 +1,7 @@
 # Pack: jsp-nextjs
 
 source: jsp
-scaffold: ../../fixtures/scaffolds/nextjs-spa
+scaffold: ../../scaffolds/nextjs-spa
 sources: .*\.(jsp|java|xml)
 programs: .*\.(jsp|java)
 specs-dir: docs/specs