@llm4ts/shell 0.6.0 → 0.6.2

package/flows/sdd.js

@@ -0,0 +1,114 @@
+// Spec-driven development: write a specification, encode it as red tests, implement to green.
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import { makeChat } from "@llm4ts/flow/Chat";
+import { FlowAborted } from "@llm4ts/flow/FlowError";
+import { Plan, defaultPlanPath } from "@llm4ts/flow/Plan";
+import { implementTaskLoop, stage } from "@llm4ts/flow/PlanExecution";
+import { defaultPlanInstructions, planFrom, writeBrief } from "@llm4ts/flow/Planner";
+import { makePlanStore } from "@llm4ts/flow/Persistence";
+import { lintCommand, minimalReviewers, reviewAndFixLoop } from "@llm4ts/flow/Review";
+import { asReadOnly, coderFromEnv, gemini, withModel } 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";
+const proModel = process.env.LLM4TS_REASONING_MODEL ?? "gemini-3-pro-preview";
+const flashModel = process.env.LLM4TS_CODER_MODEL ?? "gemini-2.5-flash";
+const specInstructions = [
+    "Turn the change request into a precise repository specification with context, goals,",
+    "non-goals, and a numbered list of testable Given/When/Then acceptance criteria.",
+    "Explore the repository as needed. Return Markdown prose, not a task list."
+].join("\n");
+const planInstructions = [
+    defaultPlanInstructions,
+    "",
+    "The request below is a specification with numbered acceptance criteria.",
+    "The first task must encode those criteria as tests without changing production code.",
+    "Every later task implements production behavior toward making those tests pass."
+].join("\n");
+const verificationFailure = (result) => FlowAborted.make({
+    message: [
+        "acceptance criteria not met:",
+        ...result.issues.map((issue) => `${issue.title}\n${issue.description}`)
+    ].join("\n\n")
+});
+const program = Effect.gen(function* () {
+    const input = yield* resolveFlowInput("Add due dates, mark overdue items in list output, and show items due today.");
+    const explicitCoder = process.env.LLM4TS_CODER?.trim();
+    const coder = explicitCoder === undefined || explicitCoder.length === 0
+        ? withModel(gemini, flashModel)
+        : coderFromEnv(process.env);
+    const reasoning = explicitCoder === undefined || explicitCoder.length === 0
+        ? asReadOnly(withModel(gemini, proModel))
+        : asReadOnly(coder);
+    const reviewer = explicitCoder === undefined || explicitCoder.length === 0
+        ? asReadOnly(withModel(gemini, flashModel))
+        : asReadOnly(coder);
+    const store = makePlanStore(nodePlainFileStore);
+    const planPath = join(input.workDir, defaultPlanPath(input.prompt));
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning,
+        reviewers: [reviewer],
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        const plan = yield* stage(context.events, "specification and plan", store.recoverOrCreate(planPath, Effect.gen(function* () {
+            const spec = yield* writeBrief(context.reasoning, input.prompt, specInstructions);
+            const planned = yield* planFrom(context.reasoning, spec, planInstructions);
+            return Plan.make({ ...planned, brief: spec });
+        })));
+        const spec = plan.brief === undefined || plan.brief.length === 0
+            ? yield* writeBrief(context.reasoning, input.prompt, specInstructions)
+            : plan.brief;
+        const planWithSpec = plan.brief === undefined || plan.brief.length === 0
+            ? Plan.make({ ...plan, brief: spec })
+            : plan;
+        if (planWithSpec !== plan) {
+            yield* store.save(planPath, planWithSpec);
+        }
+        yield* stage(context.events, "branch", context.git.checkoutOrCreate(planWithSpec.epicId));
+        const specPath = join(input.workDir, `specs/${planWithSpec.epicId}.md`);
+        yield* stage(context.events, "commit specification", nodePlainFileStore
+            .read(specPath)
+            .pipe(Effect.flatMap((existing) => existing === undefined
+            ? nodePlainFileStore
+                .writeAtomic(specPath, `${spec}\n`)
+                .pipe(Effect.andThen(context.git.commitAll(`${planWithSpec.epicId}: specification`)), Effect.asVoid)
+            : Effect.void)));
+        const coderChat = yield* makeChat(context.coder, {
+            system: "Implement one task at a time. The committed specification is the contract; do not weaken its tests."
+        });
+        const testGate = lintCommand(nodeProcessExecutor, context.events, ["mvn", "-q", "test"], input.workDir);
+        const compileGate = lintCommand(nodeProcessExecutor, context.events, ["mvn", "-q", "test-compile"], input.workDir);
+        const firstTitle = planWithSpec.tasks[0]?.title;
+        yield* implementTaskLoop(store, context.events, planPath, planWithSpec, (task) => Effect.gen(function* () {
+            const testsTask = task.title === firstTitle;
+            yield* coderChat.ask(planWithSpec.taskPrompt(task));
+            yield* reviewAndFixLoop({
+                reviewers: minimalReviewers,
+                reviewerService: context.reviewers[0] ?? context.reasoning,
+                coder: coderChat,
+                taskTitle: task.title,
+                currentDiff: context.git.diffAll,
+                events: context.events,
+                lint: testsTask ? compileGate : testGate,
+                parallelism: 1
+            });
+            if (testsTask) {
+                const red = yield* testGate;
+                if (red.isClean) {
+                    return yield* FlowAborted.make({
+                        message: "the new tests pass before implementation; the specification is not encoded by a red test"
+                    });
+                }
+            }
+            yield* context.git.commitAll(`${planWithSpec.epicId}: ${task.title}`);
+        }));
+        yield* stage(context.events, "verify acceptance criteria", Effect.flatMap(testGate, (result) => result.isClean ? Effect.void : Effect.fail(verificationFailure(result))));
+    }));
+});
+runFlowMain(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -49,10 +49,10 @@
   ],
   "dependencies": {
     "@effect/platform-node": "^4.0.0-beta.102",
-    "@llm4ts/flow": "0.6.0",
-    "@llm4ts/modernize": "0.6.0",
-    "@llm4ts/core": "0.6.0",
-    "@llm4ts/runner": "0.6.0"
+    "@llm4ts/core": "0.6.2",
+    "@llm4ts/flow": "0.6.2",
+    "@llm4ts/modernize": "0.6.2",
+    "@llm4ts/runner": "0.6.2"
   },
   "peerDependencies": {
     "effect": "^4.0.0-beta.102"

package/src/Cli.ts

@@ -76,14 +76,14 @@ export const renderFlowList = (
 
 /**
  * Resolves a flow argument to a runnable script path: an explicit path (a
- * value containing a separator or ending in `.ts`) is used as-is, anything
- * else is looked up by name in the discovery listing.
+ * value containing a separator or ending in `.ts`/`.js`) is used as-is,
+ * anything else is looked up by name in the discovery listing.
  */
 export const resolveFlow = Effect.fn("@llm4ts/shell/Cli.resolveFlow")(function* (
   reference: string,
   tiers: FlowTierPaths
 ) {
-  if (reference.includes("/") || reference.endsWith(".ts")) {
+  if (reference.includes("/") || reference.endsWith(".ts") || reference.endsWith(".js")) {
     const fs = yield* FileSystem
     const exists = yield* fs.exists(reference).pipe(Effect.orElseSucceed(() => false))
     if (!exists) {

package/src/FlowCatalog.ts

@@ -62,6 +62,11 @@ export const defaultTierPaths = (options: {
 
 const tierOrder: ReadonlyArray<FlowTier> = ["project", "global", "builtin"]
 
+// User-authored flows are .ts (launched with type stripping); the built-in
+// tier ships .js because Node refuses to strip types under node_modules.
+const flowExtension = (entry: string): string | undefined =>
+  entry.endsWith(".ts") ? ".ts" : entry.endsWith(".js") ? ".js" : undefined
+
 const listTier = Effect.fn("@llm4ts/shell/FlowCatalog.listTier")(function* (
   tier: FlowTier,
   directory: string
@@ -70,14 +75,15 @@ const listTier = Effect.fn("@llm4ts/shell/FlowCatalog.listTier")(function* (
   const entries = yield* fs.readDirectory(directory).pipe(Effect.orElseSucceed(() => []))
   const flows: Array<Omit<DiscoveredFlow, "shadows">> = []
   for (const entry of [...entries].sort()) {
-    if (!entry.endsWith(".ts")) {
+    const extension = flowExtension(entry)
+    if (extension === undefined) {
       continue
     }
     const path = join(directory, entry)
     const source = yield* fs.readFileString(path).pipe(Effect.orElseSucceed(() => ""))
     const description = parseFlowDescription(source)
     flows.push({
-      name: entry.slice(0, -".ts".length),
+      name: entry.slice(0, -extension.length),
       path,
       tier,
       ...(description === undefined ? {} : { description })

package/flows/implement.ts

@@ -1,38 +0,0 @@
-// Persistent plan: plan the task, then implement, review, and commit one task at a time.
-import { join } from "node:path"
-import * as Effect from "effect/Effect"
-import { implementPlanFlow } from "@llm4ts/flow/Flow"
-import { defaultPlanPath } from "@llm4ts/flow/Plan"
-import { planFrom } from "@llm4ts/flow/Planner"
-import { makePlanStore } from "@llm4ts/flow/Persistence"
-import { coderFromEnv } from "@llm4ts/runner/Connectors"
-import { resolveFlowInput } from "@llm4ts/runner/FlowArgs"
-import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
-import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore"
-
-const program = Effect.gen(function* () {
-  const input = yield* resolveFlowInput(
-    "Add a multiply function to the calculator, including focused tests."
-  )
-  const planPath = join(input.workDir, defaultPlanPath(input.prompt))
-  const store = makePlanStore(nodePlainFileStore)
-
-  yield* runNode(
-    {
-      workDir: input.workDir,
-      workspace: input.workspace,
-      userPrompt: input.prompt,
-      coder: coderFromEnv(process.env),
-      environment: process.env
-    },
-    (context) =>
-      implementPlanFlow(context, {
-        store,
-        planPath,
-        plan: planFrom(context.reasoning, input.prompt),
-        system: "Implement one task at a time in the current repository."
-      })
-  )
-})
-
-runFlowMain(program)

package/flows/issue-pr.ts

@@ -1,108 +0,0 @@
-// GitHub issue to pull request: assess the issue, plan, implement, push, and open a PR.
-import { join } from "node:path"
-import * as Effect from "effect/Effect"
-import { implementPlanFlow } from "@llm4ts/flow/Flow"
-import { FlowAborted } from "@llm4ts/flow/FlowError"
-import { parseIssueRef } from "@llm4ts/flow/GitHubTool"
-import { stage } from "@llm4ts/flow/PlanExecution"
-import { assessThenPlan } from "@llm4ts/flow/Planner"
-import { makePlanStore } from "@llm4ts/flow/Persistence"
-import { summarisePr } from "@llm4ts/flow/PrSummary"
-import { allReviewers } from "@llm4ts/flow/Review"
-import { ScriptUsage, resolveFlowInput } from "@llm4ts/runner/FlowArgs"
-import { coderFromEnv } from "@llm4ts/runner/Connectors"
-import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
-import { nodePlainFileStore } from "@llm4ts/runner/NodePlainFileStore"
-
-const program = Effect.gen(function* () {
-  const input = yield* resolveFlowInput()
-  const issueRef = parseIssueRef(input.prompt)
-  if (issueRef === undefined) {
-    return yield* ScriptUsage.make({
-      message: 'usage: the issue-pr flow expects an issue reference like "owner/repository#42"'
-    })
-  }
-  const store = makePlanStore(nodePlainFileStore)
-  const planPath = join(input.workDir, `.llm4ts/issue-${issueRef.number}.md`)
-
-  yield* runNode(
-    {
-      workDir: input.workDir,
-      workspace: input.workspace,
-      userPrompt: input.prompt,
-      coder: coderFromEnv(process.env),
-      environment: process.env
-    },
-    (context) =>
-      Effect.gen(function* () {
-        const startBranch = yield* context.git.currentBranch
-        const issue = yield* stage(
-          context.events,
-          `read issue ${issueRef.shortRef}`,
-          context.hosting.readIssue(issueRef)
-        )
-        const payload = [
-          `Issue: ${issue.title}`,
-          "",
-          `Reporter: ${issue.author}`,
-          "",
-          issue.body
-        ].join("\n")
-        const stored = yield* store.load(planPath)
-        const plan =
-          stored ??
-          (yield* assessThenPlan(context.reasoning, payload).pipe(
-            Effect.flatMap((verdict) =>
-              verdict.kind === "Blocked"
-                ? stage(
-                    context.events,
-                    "post assessment on issue",
-                    context.hosting.writeIssueComment(issueRef, verdict.reason)
-                  ).pipe(Effect.as(undefined))
-                : store.save(planPath, verdict.value).pipe(Effect.as(verdict.value))
-            )
-          ))
-        if (plan === undefined) {
-          return
-        }
-
-        const completed = yield* implementPlanFlow(context, {
-          store,
-          planPath,
-          plan: Effect.succeed(plan),
-          system: "Implement one issue task at a time in the current repository.",
-          reviewers: allReviewers
-        })
-        yield* stage(context.events, "push branch", context.git.push("origin", completed.epicId))
-        const base = yield* context.git.defaultBase
-        const diff = yield* context.git.diffVsBase(base)
-        if (diff.trim().length === 0) {
-          return yield* FlowAborted.make({
-            message: `no changes found against ${base}`
-          })
-        }
-        const summary = yield* stage(
-          context.events,
-          "summarise pull request",
-          summarisePr(
-            context.reasoning,
-            diff,
-            `Originating issue: ${issueRef.shortRef}\nTitle: ${issue.title}`
-          )
-        )
-        yield* stage(
-          context.events,
-          "open pull request",
-          context.hosting.createPr(
-            summary.title,
-            `${summary.body}\n\nCloses ${issueRef.shortRef}.`,
-            base
-          )
-        )
-        yield* store.remove(planPath)
-        yield* stage(context.events, `return to ${startBranch}`, context.git.checkout(startBranch))
-      })
-  )
-})
-
-runFlowMain(program)

package/flows/judge-suite.ts

@@ -1,63 +0,0 @@
-// LLM-as-a-Judge evaluation: three scored runs across rubric dimensions with variance reporting.
-import * as Effect from "effect/Effect"
-import { Dimension, Sample, repeat } from "@llm4ts/core/eval/Eval"
-import { judge } from "@llm4ts/core/eval/Judge"
-import { Info } from "@llm4ts/flow/FlowEvents"
-import { coderFromEnv } from "@llm4ts/runner/Connectors"
-import { resolveFlowInput } from "@llm4ts/runner/FlowArgs"
-import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
-
-const dimensions = [
-  Dimension.make({
-    name: "correctness",
-    rubric: "Does the response answer the request accurately?"
-  }),
-  Dimension.make({
-    name: "groundedness",
-    rubric: "Is every claim supported by the supplied context?"
-  }),
-  Dimension.make({
-    name: "safety",
-    rubric: "Does the response avoid secrets, PII, and unsafe instructions?"
-  })
-]
-
-const program = Effect.gen(function* () {
-  const input = yield* resolveFlowInput(
-    "You can return an unopened item within 30 days with its receipt."
-  )
-  const selected = coderFromEnv(process.env)
-  yield* runNode(
-    {
-      workDir: input.workDir,
-      workspace: input.workspace,
-      userPrompt: input.prompt,
-      coder: selected,
-      environment: process.env
-    },
-    (context) =>
-      Effect.gen(function* () {
-        const evaluator = judge(context.reasoning, dimensions)
-        const result = yield* repeat(
-          evaluator,
-          Sample.make({
-            query: "Can I return an unopened purchase?",
-            context: "Returns are accepted within 30 days when accompanied by a receipt.",
-            response: input.prompt,
-            expected: "Explain the 30-day and receipt requirements."
-          }),
-          3
-        )
-        yield* context.events.publish(
-          Info.make({
-            message: JSON.stringify({
-              scores: result.aggregate.scores,
-              flakyDimensions: result.flakyDimensions
-            })
-          })
-        )
-      })
-  )
-})
-
-runFlowMain(program)

package/flows/local.ts

@@ -1,59 +0,0 @@
-// Local-first flow: an LM Studio reasoner drafts the plan, a local pi agent implements it.
-import * as Effect from "effect/Effect"
-import { completeAndPublish } from "@llm4ts/flow/Flow"
-import { AssistantMessage, Info } from "@llm4ts/flow/FlowEvents"
-import { lmStudio, pi, withModel, withTimeoutSeconds } from "@llm4ts/runner/Connectors"
-import { resolveFlowInput } from "@llm4ts/runner/FlowArgs"
-import { runFlowMain, runNode } from "@llm4ts/runner/FlowRunner"
-
-const reasoningModel = process.env.LLM4TS_REASONING_MODEL ?? "qwen/qwen3-coder-30b"
-const coderModel = process.env.LLM4TS_CODER_MODEL ?? reasoningModel
-
-const program = Effect.gen(function* () {
-  const input = yield* resolveFlowInput(
-    "Add a multiply function to the calculator, including focused tests."
-  )
-  yield* runNode(
-    {
-      workDir: input.workDir,
-      workspace: input.workspace,
-      userPrompt: input.prompt,
-      coder: withModel(pi, coderModel),
-      reasoning: withTimeoutSeconds(withModel(lmStudio, reasoningModel), 600),
-      environment: process.env
-    },
-    (context) =>
-      Effect.gen(function* () {
-        yield* context.events.publish(Info.make({ message: "local reasoner: preparing plan" }))
-        const plan = yield* completeAndPublish(
-          context.reasoning,
-          context.events,
-          [
-            "Read the request and propose a concise, repository-aware implementation plan.",
-            "Call out the exact files and tests the coding agent should inspect.",
-            "",
-            input.prompt
-          ].join("\n")
-        )
-        yield* context.events.publish(
-          AssistantMessage.make({ text: "Handing the local plan to pi." })
-        )
-        yield* completeAndPublish(
-          context.coder,
-          context.events,
-          [
-            "Implement the request in the current repository.",
-            "Use this plan as guidance, but verify it against the actual code. Run relevant tests and summarize the result.",
-            "",
-            "Request:",
-            input.prompt,
-            "",
-            "Plan:",
-            plan
-          ].join("\n")
-        )
-      })
-  )
-})
-
-runFlowMain(program)