@llm4ts/shell 0.2.0

package/flows/sdd.ts

@@ -0,0 +1,181 @@
+// 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,
+  type ReviewResult
+} 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: ReviewResult): FlowAborted =>
+  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

@@ -0,0 +1,66 @@
+{
+  "name": "@llm4ts/shell",
+  "version": "0.2.0",
+  "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "llm4ts": "./dist/cli-main.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "flows"
+  ],
+  "exports": {
+    "./Cli": "./dist/Cli.js",
+    "./CoderChoice": "./dist/CoderChoice.js",
+    "./FlowCatalog": "./dist/FlowCatalog.js",
+    "./FlowLaunch": "./dist/FlowLaunch.js",
+    "./Menu": "./dist/Menu.js",
+    "./Package": "./dist/Package.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "tsc -b tsconfig.json --clean",
+    "test": "vitest run test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/riccardomerolla/llm4ts.git",
+    "directory": "packages/shell"
+  },
+  "homepage": "https://github.com/riccardomerolla/llm4ts#readme",
+  "bugs": {
+    "url": "https://github.com/riccardomerolla/llm4ts/issues"
+  },
+  "keywords": [
+    "llm",
+    "effect",
+    "ai",
+    "agents",
+    "workflow",
+    "cli",
+    "typescript"
+  ],
+  "dependencies": {
+    "@effect/platform-node": "^4.0.0-beta.102",
+    "@llm4ts/core": "workspace:*",
+    "@llm4ts/flow": "workspace:*",
+    "@llm4ts/runner": "workspace:*"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0-beta.102"
+  },
+  "devDependencies": {
+    "effect": "^4.0.0-beta.102"
+  }
+}

package/src/Cli.ts

@@ -0,0 +1,230 @@
+import { homedir } from "node:os"
+import { fileURLToPath } from "node:url"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import { FileSystem } from "effect/FileSystem"
+import * as Schema from "effect/Schema"
+import * as Argument from "effect/unstable/cli/Argument"
+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 {
+  defaultTierPaths,
+  discoverFlows,
+  type DiscoveredFlow,
+  type FlowTierPaths
+} from "./FlowCatalog.ts"
+import { launchFlow } from "./FlowLaunch.ts"
+import { mainMenu } from "./Menu.ts"
+import { packageVersion } from "./Package.ts"
+
+export class ShellUsageError extends Schema.TaggedErrorClass<ShellUsageError>()("ShellUsage", {
+  message: Schema.String
+}) {}
+
+export class ShellActionError extends Schema.TaggedErrorClass<ShellActionError>()("ShellAction", {
+  message: Schema.String
+}) {}
+
+export const builtinFlowsDir = (): string => fileURLToPath(new URL("../flows", import.meta.url))
+
+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()
+  })
+
+const tierLabel = (flow: DiscoveredFlow): string => {
+  const shadows = flow.shadows.length === 0 ? "" : ` shadows ${flow.shadows.join(", ")}`
+  return `[${flow.tier}${shadows}]`
+}
+
+export const renderFlowList = (
+  flows: ReadonlyArray<DiscoveredFlow>,
+  options?: { readonly json?: boolean }
+): string => {
+  if (options?.json === true) {
+    return JSON.stringify(
+      flows.map((flow) => ({
+        name: flow.name,
+        tier: flow.tier,
+        path: flow.path,
+        ...(flow.description === undefined ? {} : { description: flow.description }),
+        shadows: flow.shadows
+      })),
+      undefined,
+      2
+    )
+  }
+  const nameWidth = flows.reduce((width, flow) => Math.max(width, flow.name.length), 0)
+  return flows
+    .map((flow) =>
+      [
+        flow.name.padEnd(nameWidth),
+        tierLabel(flow),
+        ...(flow.description === undefined ? [] : [flow.description])
+      ].join("  ")
+    )
+    .join("\n")
+}
+
+/**
+ * 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.
+ */
+export const resolveFlow = Effect.fn("@llm4ts/shell/Cli.resolveFlow")(function* (
+  reference: string,
+  tiers: FlowTierPaths
+) {
+  if (reference.includes("/") || reference.endsWith(".ts")) {
+    const fs = yield* FileSystem
+    const exists = yield* fs.exists(reference).pipe(Effect.orElseSucceed(() => false))
+    if (!exists) {
+      return yield* new ShellUsageError({ message: `flow script not found: ${reference}` })
+    }
+    return reference
+  }
+  const flows = yield* discoverFlows(tiers)
+  const found = flows.find((flow) => flow.name === reference)
+  if (found === undefined) {
+    const known = flows.map((flow) => flow.name).join(", ")
+    return yield* new ShellUsageError({
+      message:
+        known.length === 0
+          ? `unknown flow '${reference}' (no flows discovered)`
+          : `unknown flow '${reference}' (known flows: ${known})`
+    })
+  }
+  return found.path
+})
+
+const runCommand = Command.make(
+  "run",
+  {
+    flow: Argument.string("flow").pipe(
+      Argument.withDescription("Flow name from `llm4ts list`, or a path to a flow script")
+    ),
+    task: Argument.string("task").pipe(
+      Argument.variadic(),
+      Argument.withDescription("Task text passed to the flow")
+    ),
+    verbose: Flag.boolean("verbose").pipe(Flag.withDescription("Stream verbose flow output"))
+  },
+  (config) =>
+    Effect.gen(function* () {
+      const tiers = shellTierPaths()
+      const flowPath = yield* resolveFlow(config.flow, tiers)
+      const environment: Record<string, string | undefined> = { ...process.env }
+      if (config.verbose) {
+        environment.LLM4TS_VERBOSITY = "verbose"
+      }
+      const exitCode = yield* launchFlow({
+        flowPath,
+        taskArgs: config.task,
+        environment
+      })
+      yield* Effect.sync(() => {
+        process.exitCode = exitCode
+      })
+    })
+).pipe(Command.withDescription("Run a discovered flow as a child process"))
+
+const listCommand = Command.make(
+  "list",
+  {
+    json: Flag.boolean("json").pipe(Flag.withDescription("Emit the listing as JSON"))
+  },
+  (config) =>
+    Effect.gen(function* () {
+      const flows = yield* discoverFlows(shellTierPaths())
+      if (flows.length === 0 && !config.json) {
+        yield* Console.error("no flows discovered")
+        return
+      }
+      yield* Console.log(renderFlowList(flows, { json: config.json }))
+    })
+).pipe(Command.withDescription("List flows across the project, global, and built-in tiers"))
+
+const viewCommand = Command.make(
+  "view",
+  {
+    flow: Argument.string("flow").pipe(
+      Argument.withDescription("Flow name from `llm4ts list`, or a path to a flow script")
+    )
+  },
+  (config) =>
+    Effect.gen(function* () {
+      const flowPath = yield* resolveFlow(config.flow, shellTierPaths())
+      const fs = yield* FileSystem
+      const source = yield* fs
+        .readFileString(flowPath)
+        .pipe(Effect.mapError(() => new ShellActionError({ message: `cannot read ${flowPath}` })))
+      yield* Console.log(source.trimEnd())
+    })
+).pipe(Command.withDescription("Print a flow's source"))
+
+const askCommand = Command.make(
+  "ask",
+  {
+    prompt: Argument.string("prompt").pipe(
+      Argument.variadic(),
+      Argument.withDescription("Prompt streamed once to the selected coding agent")
+    ),
+    repo: Flag.string("repo").pipe(
+      Flag.optional,
+      Flag.withDescription("Repository to run against (defaults to the current directory)")
+    )
+  },
+  (config) =>
+    Effect.gen(function* () {
+      if (config.prompt.length === 0) {
+        return yield* new ShellUsageError({ message: "ask needs a prompt" })
+      }
+      const argv = [
+        config.prompt.join(" "),
+        ...(config.repo._tag === "Some" ? ["--repo", config.repo.value] : [])
+      ]
+      yield* makeCliProgram(argv).pipe(
+        Effect.mapError((error) =>
+          error._tag === "ScriptUsage"
+            ? new ShellUsageError({ message: error.message })
+            : new ShellActionError({ message: error.message })
+        )
+      )
+    })
+).pipe(Command.withDescription("Stream a one-shot prompt to the selected coding agent"))
+
+const doctorCommand = Command.make("doctor", {}, () =>
+  Effect.gen(function* () {
+    const report = yield* makeDoctorProgram()
+    yield* Console.log(report.trimEnd())
+  })
+).pipe(Command.withDescription("Report available connectors and credentials"))
+
+export const shellCommand = Command.make("llm4ts", {}, () =>
+  Effect.gen(function* () {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+      return yield* new ShellUsageError({
+        message: "no command given and no interactive terminal; try `llm4ts --help`"
+      })
+    }
+    yield* mainMenu(shellTierPaths())
+  })
+).pipe(
+  Command.withDescription(
+    "Interactive shell and CLI for llm4ts flows: discover, inspect, and run them."
+  ),
+  Command.withSubcommands([runCommand, listCommand, viewCommand, askCommand, doctorCommand])
+)
+
+export const runShellCommand = (
+  argv: ReadonlyArray<string>
+): Effect.Effect<void, unknown, Command.Environment> =>
+  Command.runWith(shellCommand, { version: packageVersion })(argv)

package/src/CoderChoice.ts

@@ -0,0 +1,58 @@
+import { accessSync, constants } from "node:fs"
+import { delimiter, join } from "node:path"
+
+/**
+ * The coder tokens `coderFromEnv` accepts as `LLM4TS_CODER` values, each with
+ * the executable name the corresponding CLI connector spawns. The tokens are
+ * the connector identity vocabulary of `@llm4ts/core/Models` narrowed to the
+ * CLI coding agents the runner exposes.
+ */
+export interface CoderChoice {
+  readonly token: string
+  readonly executable: string
+}
+
+export const coderChoices: ReadonlyArray<CoderChoice> = [
+  { token: "claude", executable: "claude" },
+  { token: "codex", executable: "codex" },
+  { token: "gemini", executable: "gemini" },
+  { token: "pi", executable: "pi" },
+  { token: "agy", executable: "agy" },
+  { token: "grok", executable: "grok" },
+  { token: "cursor", executable: "cursor-agent" },
+  { token: "opencode", executable: "opencode" }
+]
+
+/**
+ * Locates an executable on `PATH` without spawning a process. Decoration
+ * only: an undetected CLI stays selectable, mirroring orca's wizard probing.
+ */
+export const findOnPath = (
+  executable: string,
+  environment: Readonly<Record<string, string | undefined>> = process.env
+): string | undefined => {
+  const searchPath = environment.PATH
+  if (searchPath === undefined || searchPath.length === 0) {
+    return undefined
+  }
+  for (const directory of searchPath.split(delimiter)) {
+    if (directory.length === 0) {
+      continue
+    }
+    const candidate = join(directory, executable)
+    try {
+      accessSync(candidate, constants.X_OK)
+      return candidate
+    } catch {
+      continue
+    }
+  }
+  return undefined
+}
+
+export const resolvedCoderToken = (
+  environment: Readonly<Record<string, string | undefined>> = process.env
+): string => {
+  const token = environment.LLM4TS_CODER ?? environment.LLM4ZIO_CODER ?? "claude"
+  return coderChoices.some((choice) => choice.token === token) ? token : "claude"
+}

package/src/FlowCatalog.ts

@@ -0,0 +1,119 @@
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import { FileSystem } from "effect/FileSystem"
+
+export type FlowTier = "project" | "global" | "builtin"
+
+export interface FlowTierPaths {
+  readonly project?: string
+  readonly global?: string
+  readonly builtin?: string
+}
+
+export interface DiscoveredFlow {
+  readonly name: string
+  readonly path: string
+  readonly tier: FlowTier
+  readonly description?: string
+  readonly shadows: ReadonlyArray<FlowTier>
+}
+
+/**
+ * The first non-empty `//` comment line within the file's leading block of
+ * blank lines and `//` comments is the flow's one-line description. A bare or
+ * whitespace-only `//` line is skipped, never returned as an empty
+ * description; the scan stops at the first line that is neither blank nor a
+ * `//` comment.
+ */
+export const parseFlowDescription = (source: string): string | undefined => {
+  for (const line of source.split("\n")) {
+    const trimmed = line.trim()
+    if (trimmed.length === 0) {
+      continue
+    }
+    if (!trimmed.startsWith("//")) {
+      return undefined
+    }
+    const text = trimmed.slice(2).trim()
+    if (text.length > 0) {
+      return text
+    }
+  }
+  return undefined
+}
+
+export const defaultTierPaths = (options: {
+  readonly cwd: string
+  readonly homeDir: string
+  readonly environment?: Readonly<Record<string, string | undefined>>
+  readonly builtinDir?: string
+}): FlowTierPaths => {
+  const environment = options.environment ?? process.env
+  const configHome =
+    environment.XDG_CONFIG_HOME !== undefined && environment.XDG_CONFIG_HOME.length > 0
+      ? environment.XDG_CONFIG_HOME
+      : join(options.homeDir, ".config")
+  return {
+    project: join(options.cwd, ".llm4ts", "flows"),
+    global: join(configHome, "llm4ts", "flows"),
+    ...(options.builtinDir === undefined ? {} : { builtin: options.builtinDir })
+  }
+}
+
+const tierOrder: ReadonlyArray<FlowTier> = ["project", "global", "builtin"]
+
+const listTier = Effect.fn("@llm4ts/shell/FlowCatalog.listTier")(function* (
+  tier: FlowTier,
+  directory: string
+) {
+  const fs = yield* FileSystem
+  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")) {
+      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),
+      path,
+      tier,
+      ...(description === undefined ? {} : { description })
+    })
+  }
+  return flows
+})
+
+/**
+ * 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.
+ */
+export const discoverFlows = Effect.fn("@llm4ts/shell/FlowCatalog.discoverFlows")(function* (
+  tiers: FlowTierPaths
+) {
+  const byName = new Map<
+    string,
+    { flow: Omit<DiscoveredFlow, "shadows">; shadows: Array<FlowTier> }
+  >()
+  for (const tier of tierOrder) {
+    const directory = tiers[tier]
+    if (directory === undefined) {
+      continue
+    }
+    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)
+      }
+    }
+  }
+  return [...byName.values()]
+    .map(({ flow, shadows }): DiscoveredFlow => ({ ...flow, shadows }))
+    .sort((left, right) => left.name.localeCompare(right.name))
+})