@llm4ts/shell 2.3.1 → 2.4.0

package/flows/lib/pack-fork.js

@@ -0,0 +1,173 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { ScriptUsage } from "@llm4ts/runner";
+export const parseTargetKind = (environment) => {
+    const raw = environment.LLM4TS_TARGET_KIND?.trim().toLowerCase();
+    if (raw === "frontend" || raw === "backend") {
+        return Effect.succeed(raw);
+    }
+    return Effect.fail(ScriptUsage.make({
+        message: "LLM4TS_TARGET_KIND must be 'frontend' or 'backend' " +
+            `(got ${raw === undefined || raw.length === 0 ? "unset" : `'${raw}'`})`
+    }));
+};
+const forkAsPattern = /^[a-z][a-z0-9-]*$/;
+export const parseForkAs = (environment) => {
+    const raw = environment.LLM4TS_FORK_AS?.trim();
+    if (raw !== undefined && forkAsPattern.test(raw)) {
+        return Effect.succeed(raw);
+    }
+    return Effect.fail(ScriptUsage.make({
+        message: "LLM4TS_FORK_AS must be a lowercase kebab-case name, e.g. 'acmecorp-nextjs' " +
+            `(got ${raw === undefined || raw.length === 0 ? "unset" : `'${raw}'`})`
+    }));
+};
+export const frontendPasses = [
+    {
+        heading: "Tech Stack & Dependencies",
+        instructions: "Identify the exact frontend framework and version (e.g. Next.js App Router vs " +
+            "Pages Router), the language (TypeScript/JavaScript), the package manager, and " +
+            "the state/data libraries already in use. List every direct dependency from the " +
+            "grounding files below that a coding agent adding a new feature is likely to " +
+            "need (forms, HTTP/data fetching, dates, validation) and name which package " +
+            "already covers it, so no duplicate gets added."
+    },
+    {
+        heading: "Naming, Routing & Architecture",
+        instructions: "Explore the repository's folder structure, then describe: file and folder " +
+            "naming conventions (casing, suffixes), how new pages/routes are added and " +
+            "where they live, component naming conventions, and where shared " +
+            "utilities/constants/hooks live. Use real example paths from this repository, " +
+            "not generic advice."
+    },
+    {
+        heading: "Shared Components, Design System & Style",
+        instructions: "Explore the repository for a shared component library or design system (its " +
+            "location, how components are composed and exported, whether there's theming " +
+            "or design tokens), and the CSS/styling approach in use (Tailwind, CSS " +
+            "Modules, styled-components, or other). Describe how an existing shared " +
+            "component should be found and reused rather than rebuilt. If there is no " +
+            "design system, say so explicitly rather than inventing one."
+    },
+    {
+        heading: "Auth, Permissions & Data Fetching",
+        instructions: "Explore how authentication and authorization are implemented (the " +
+            "library/provider, where session/user state lives, how a route or component " +
+            "checks permissions), and how data is fetched/mutated (React Query, SWR, " +
+            "server actions, or plain fetch — and where that logic conventionally lives). " +
+            "Describe the pattern precisely enough that a new feature can follow it " +
+            "without inventing a new one."
+    }
+];
+export const backendPasses = [
+    {
+        heading: "Tech Stack & Dependencies",
+        instructions: "Identify the exact backend framework and version (e.g. Spring Boot), the JVM " +
+            "language, the build tool, and the database/persistence technology in use. " +
+            "List every direct dependency from the grounding files below that a coding " +
+            "agent adding a new feature is likely to need (HTTP client, JSON mapping, " +
+            "validation, testing) and name which dependency already covers it, so no " +
+            "duplicate gets added."
+    },
+    {
+        heading: "Naming & Architecture",
+        instructions: "Explore the repository's package structure, then describe: package and class " +
+            "naming conventions (controllers, services, repositories, DTOs, entities), and " +
+            "the layering/module boundaries already established (e.g. controller → " +
+            "service → repository, or a domain-driven module split). Use real example " +
+            "package/class names from this repository."
+    },
+    {
+        heading: "Data, Persistence & Shared Resources",
+        instructions: "Explore how entities/persistence are modeled (JPA conventions, migration " +
+            "tool such as Flyway/Liquibase, transaction handling), and where " +
+            "shared/common resources live (shared utility classes, common exception " +
+            "handling, cross-cutting concerns). Describe the pattern precisely enough " +
+            "that a new feature reuses what's there instead of rebuilding it."
+    },
+    {
+        heading: "Auth, API & Testing Conventions",
+        instructions: "Explore how security/auth is configured (the security framework, JWT/OAuth " +
+            "setup, role-based or method-level access control), the REST API conventions " +
+            "in use (URL/versioning scheme, error response shape, OpenAPI usage), and the " +
+            "testing conventions (unit vs integration test structure, fixtures/mocking " +
+            "approach). Describe each precisely enough to follow without inventing a new " +
+            "one."
+    }
+];
+export const passesForTargetKind = (kind) => kind === "frontend" ? frontendPasses : backendPasses;
+export const conventionPassAsk = (pass, grounding) => [
+    pass.instructions,
+    `Respond with a single markdown section starting with "## ${pass.heading}".`,
+    "If a topic doesn't apply to this repository, say so explicitly rather than " +
+        "inventing one.",
+    ...(grounding === undefined || grounding.length === 0
+        ? []
+        : [`Repository files for grounding:\n\n${grounding}`])
+].join("\n\n");
+export class ConventionSection extends Schema.Class("ConventionSection")({
+    markdown: Schema.String
+}) {
+}
+export const conventionSectionJsonSchema = {
+    type: "object",
+    properties: {
+        markdown: {
+            type: "string",
+            description: "A markdown section (starting with a ## heading) describing the findings " +
+                "for this category."
+        }
+    },
+    required: ["markdown"]
+};
+export const techStackGroundingFiles = (kind) => kind === "frontend"
+    ? ["package.json", "tsconfig.json"]
+    : ["pom.xml", "build.gradle", "build.gradle.kts"];
+export const readGroundingFiles = (workspace, paths) => Effect.gen(function* () {
+    const sections = [];
+    for (const path of paths) {
+        const content = yield* workspace
+            .read(path)
+            .pipe(Effect.catch(() => Effect.succeed(undefined)));
+        if (content !== undefined) {
+            sections.push(`### ${path}\n\n\`\`\`\n${content}\n\`\`\``);
+        }
+    }
+    return sections.join("\n\n");
+});
+export const forkPackMarkdown = (sourcePackMd, forkedName) => {
+    const [, ...rest] = sourcePackMd.split("\n");
+    const withoutScaffold = rest.filter((line) => !/^scaffold:\s*/.test(line));
+    return [`# Pack: ${forkedName}`, ...withoutScaffold].join("\n");
+};
+export const forkedReadme = (sourcePackName, forkedName, kind, sourceRepo) => [
+    `# Forked pack — ${forkedName}`,
+    "",
+    `Forked by the pack-fork flow from '${sourcePackName}', analyzing '${sourceRepo}' ` +
+        `as a ${kind} target repository.`,
+    "",
+    "- pack.md — the source pack, copied verbatim except for the dropped `scaffold:` " +
+        "line (this pack targets a repository that already exists).",
+    "- conventions.md — this repository's own architecture, dependencies, naming, " +
+        "and design conventions, captured by analyzing the real target repository. " +
+        "Read directly by modernize-implement's generation prompt.",
+    "- reviewers/target-conventions.md — a post-hoc review lens checking new code " +
+        "against conventions.md.",
+    "",
+    "Review conventions.md against what you know of the target repository, then flip " +
+        "the marker below and point LLM4TS_PACK at this fork."
+].join("\n");
+export const targetConventionsReviewer = [
+    "Verify the diff stays inside this repository's established conventions — see " +
+        "conventions.md in this pack for the specifics captured when this pack was " +
+        "forked from the target repository.",
+    "",
+    "Flag, and only flag:",
+    "- A new dependency added when an existing one in this repo already covers the " + "same need.",
+    "- A new shared component, utility, or auth/permission pattern introduced instead " +
+        "of reusing the one this repo already has.",
+    "- Naming, folder, or style conventions that diverge from what conventions.md " + "describes.",
+    "",
+    "Do not flag anything conventions.md doesn't mention — silence there means this " +
+        "pack's fork never captured an opinion on it."
+].join("\n");

package/flows/modernize-implement.js

@@ -206,6 +206,11 @@ const program = Effect.gen(function* () {
             pack.lessons === undefined
                 ? undefined
                 : `Lessons from previous modernization runs — apply them:\n${pack.lessons}`,
+            pack.conventions === undefined
+                ? undefined
+                : "This repository's own established conventions, captured from the real " +
+                    "target repository — reuse them, stay inside them:\n" +
+                    pack.conventions,
             playbook.length === 0
                 ? undefined
                 : "Pattern cards cited by the specs — the translation playbook (advisory, the specs win):\n\n" +

package/flows/pack-fork.js

@@ -0,0 +1,137 @@
+// Forks an existing pack into a new, project-tier pack whose conventions.md
+// and reviewers/target-conventions.md describe a REAL, already-in-production
+// target repository — so a later modernize-implement run (LLM4TS_PACK
+// pointed at the fork) writes new code that reuses this repo's own
+// architecture, shared components, and conventions instead of guessing.
+// See docs/adr/0018-pack-fork.md.
+//
+// Runs rooted at the TARGET repository (`--repo <target>`) — there is no
+// legacy repository in this flow at all. Requires:
+//   LLM4TS_PACK=<source pack>       resolved as for any flow (default cobol-springboot)
+//   LLM4TS_TARGET_KIND=frontend|backend
+//   LLM4TS_FORK_AS=<new pack name>  lowercase kebab-case
+//
+// The forked pack lands at
+// `<repo>/.llm4ts/kits/forked/packs/<LLM4TS_FORK_AS>/` — a dedicated
+// project-tier kit named "forked", never the source pack's own kit name
+// (Kits.ts dedupes kits by name across tiers; reusing the source kit's name
+// would hide its other packs from this project). `scaffold:` is dropped:
+// the whole point is that the target repository already exists.
+//
+// One-shot, not resumable: re-running overwrites the previous fork under
+// the same LLM4TS_FORK_AS name.
+import { basename, join, relative as relativePath, resolve as resolvePath } from "node:path";
+import { rmSync } from "node:fs";
+import * as Effect from "effect/Effect";
+import { structuredAndPublish } from "@llm4ts/flow/Flow";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { withDraftApproval } from "@llm4ts/flow/Approval";
+import { legacySourceWorkspaceLimits, workspaceLimitsFromEnv } from "@llm4ts/flow/Workspace";
+import { asReadOnly, coderFromEnv, makeNodeWorkspace, nodePlainFileStore, openPack, resolveFlowInput, runFlowMain, runNode, ScriptUsage, stage } from "@llm4ts/runner";
+import { ConventionSection, conventionPassAsk, conventionSectionJsonSchema, forkPackMarkdown, forkedReadme, parseForkAs, parseTargetKind, passesForTargetKind, readGroundingFiles, targetConventionsReviewer, techStackGroundingFiles } from "./lib/pack-fork.js";
+const forkPackFiles = Effect.fn("flows/pack-fork.forkPackFiles")(function* (source, destinationAbs, files) {
+    // `source.dir` is "." for an absolute-path pack reference (Packs.ts's
+    // `locatePack`), "packs/<name>" for a relative-directory or kit pack
+    // reference — never assume it's non-empty. `join`/`relative` from
+    // node:path normalize the "." case correctly where manual string
+    // concatenation or `.slice()` would not.
+    const packMdPath = join(source.dir, "pack.md");
+    const entries = yield* source.workspace.discover(join(source.dir, "**"));
+    for (const relative_ of entries) {
+        if (relative_ === packMdPath) {
+            continue;
+        }
+        const content = yield* source.workspace
+            .read(relative_)
+            .pipe(Effect.catch(() => Effect.succeed(undefined)));
+        if (content === undefined) {
+            continue;
+        }
+        const suffix = relativePath(source.dir, relative_);
+        yield* files.writeAtomic(join(destinationAbs, suffix), content);
+    }
+});
+const forkKitPatterns = Effect.fn("flows/pack-fork.forkKitPatterns")(function* (source, destinationAbs, files) {
+    if (source.kit === undefined) {
+        return;
+    }
+    const entries = yield* source.workspace
+        .discover(join("patterns", "**"))
+        .pipe(Effect.catch(() => Effect.succeed([])));
+    for (const relative_ of entries) {
+        const content = yield* source.workspace
+            .read(relative_)
+            .pipe(Effect.catch(() => Effect.succeed(undefined)));
+        if (content === undefined) {
+            continue;
+        }
+        yield* files.writeAtomic(join(destinationAbs, relative_), content);
+    }
+});
+const program = Effect.gen(function* () {
+    const input = yield* resolveFlowInput("Analyze the target repository and fork the pack with its conventions.");
+    const targetKind = yield* parseTargetKind(process.env);
+    const forkAs = yield* parseForkAs(process.env);
+    const coder = asReadOnly(coderFromEnv(process.env));
+    const files = nodePlainFileStore;
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning: coder,
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        const repo = yield* makeNodeWorkspace(input.workDir, workspaceLimitsFromEnv(process.env, legacySourceWorkspaceLimits));
+        const opened = yield* stage(context.events, "pack", openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+        }));
+        const destinationRel = join(".llm4ts", "kits", "forked", "packs", forkAs);
+        const destinationAbs = join(input.workDir, destinationRel);
+        // Guard BEFORE any read of the source pack or the "clean" rmSync
+        // below: if LLM4TS_PACK and LLM4TS_FORK_AS resolve to the same
+        // directory — reachable by cd-ing into the target repo and setting
+        // LLM4TS_PACK=forked/<name> for a re-fork, exactly as this flow's
+        // own closing message instructs — the clean stage would delete the
+        // pack this run is about to read, including any uncommitted human
+        // edits such as the approval-marker flip.
+        const sourceDirAbs = resolvePath(join(opened.workspace.root, opened.dir));
+        if (sourceDirAbs === resolvePath(destinationAbs)) {
+            return yield* ScriptUsage.make({
+                message: `LLM4TS_PACK resolves to '${sourceDirAbs}', the same directory ` +
+                    `LLM4TS_FORK_AS='${forkAs}' would fork into — forking a pack into itself ` +
+                    "would delete it before it's read. Point LLM4TS_PACK at a different source " +
+                    "pack, or choose a different LLM4TS_FORK_AS."
+            });
+        }
+        const grounding = yield* stage(context.events, "grounding", readGroundingFiles(repo, techStackGroundingFiles(targetKind)));
+        const passes = passesForTargetKind(targetKind);
+        const sections = [];
+        for (const [index, pass] of passes.entries()) {
+            const prompt = conventionPassAsk(pass, index === 0 ? grounding : undefined);
+            const result = yield* stage(context.events, pass.heading, structuredAndPublish(context.reasoning, context.events, prompt, ConventionSection, conventionSectionJsonSchema));
+            sections.push(result.markdown);
+        }
+        const conventionsMd = sections.join("\n\n");
+        yield* stage(context.events, "clean", Effect.sync(() => rmSync(destinationAbs, { recursive: true, force: true })));
+        yield* stage(context.events, "fork", forkPackFiles(opened, destinationAbs, files));
+        yield* stage(context.events, "fork patterns", forkKitPatterns(opened, destinationAbs, files));
+        const sourcePackMd = yield* opened.workspace.read(`${opened.dir}/pack.md`);
+        yield* files.writeAtomic(join(destinationAbs, "pack.md"), forkPackMarkdown(sourcePackMd, forkAs));
+        yield* files.writeAtomic(join(destinationAbs, "conventions.md"), conventionsMd);
+        yield* files.writeAtomic(join(destinationAbs, "reviewers", "target-conventions.md"), targetConventionsReviewer);
+        yield* files.writeAtomic(join(destinationAbs, "README.md"), withDraftApproval(forkedReadme(opened.pack.name, forkAs, targetKind, basename(input.workDir))));
+        yield* stage(context.events, "commit", context.git
+            .commitPaths(`pack-fork: fork '${opened.pack.name}' as '${forkAs}'`, [destinationRel])
+            .pipe(Effect.asVoid));
+        yield* context.events.publish(Info.make({
+            message: `forked pack ready — review ${destinationRel}/README.md and ` +
+                `${destinationRel}/conventions.md, set '- [x] Approved', then from ` +
+                `inside ${input.workDir} run modernize-implement with ` +
+                `LLM4TS_PACK=forked/${forkAs}`
+        }));
+    }));
+});
+runFlowMain(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.3.1",
+  "version": "2.4.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/flow": "2.3.1",
-    "@llm4ts/core": "2.3.1",
-    "@llm4ts/runner": "2.3.1"
+    "@llm4ts/core": "2.4.0",
+    "@llm4ts/runner": "2.4.0",
+    "@llm4ts/flow": "2.4.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.115"