@llm4ts/shell 0.2.0

package/src/FlowLaunch.ts

@@ -0,0 +1,99 @@
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import { constants } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+export class FlowLaunchError extends Schema.TaggedErrorClass<FlowLaunchError>()("FlowLaunch", {
+  message: Schema.String
+}) {}
+
+/**
+ * True when the flow script cannot resolve `@llm4ts/runner` from its own
+ * location — a global flow, a built-in copy, or a bare repository. Project
+ * flows inside a repository that installs `@llm4ts/*` resolve their own pin
+ * and need no help (the project-wins policy of ADR 0006). Implemented as the
+ * same `node_modules` directory walk ESM resolution performs, so the check
+ * stays honest under test runners that patch the module system.
+ */
+export const needsResolveFallback = (flowPath: string): boolean => {
+  let directory = dirname(resolve(flowPath))
+  while (true) {
+    if (existsSync(join(directory, "node_modules", "@llm4ts", "runner", "package.json"))) {
+      return false
+    }
+    const parent = dirname(directory)
+    if (parent === directory) {
+      return true
+    }
+    directory = parent
+  }
+}
+
+// In the published package the hook is the compiled sibling; when running
+// from src (tests), it is the TypeScript source, which the child can load
+// because it always runs with type stripping enabled.
+const resolveFallbackUrl = (() => {
+  const compiled = new URL("./ResolveFallback.js", import.meta.url)
+  return existsSync(fileURLToPath(compiled))
+    ? compiled.href
+    : new URL("./ResolveFallback.ts", import.meta.url).href
+})()
+
+export interface LaunchFlowOptions {
+  readonly flowPath: string
+  readonly taskArgs: ReadonlyArray<string>
+  readonly environment?: Readonly<Record<string, string | undefined>>
+  readonly cwd?: string
+  /** Overrides `LLM4TS_CODER` in the child for this run only. */
+  readonly coder?: string
+  /** `inherit` shares the terminal (the default); tests use `ignore`. */
+  readonly stdio?: "inherit" | "ignore"
+}
+
+/**
+ * Runs a flow script as a child `node` process with type stripping, the
+ * terminal inherited, and the task text appended to argv. While the child
+ * runs, SIGINT is ignored in the parent so Ctrl-C reaches the whole
+ * foreground process group and the shell survives to resume. Resolves with
+ * the child's exit code (`128 + signal` when terminated by a signal).
+ */
+export const launchFlow = (options: LaunchFlowOptions): Effect.Effect<number, FlowLaunchError> =>
+  Effect.callback<number, FlowLaunchError>((resume) => {
+    const environment = { ...(options.environment ?? process.env) }
+    if (options.coder !== undefined) {
+      environment.LLM4TS_CODER = options.coder
+    }
+    const nodeArgs = ["--experimental-strip-types"]
+    if (needsResolveFallback(options.flowPath)) {
+      nodeArgs.push("--import", resolveFallbackUrl)
+    }
+    const child = spawn(process.execPath, [...nodeArgs, options.flowPath, ...options.taskArgs], {
+      stdio: options.stdio ?? "inherit",
+      env: environment,
+      ...(options.cwd === undefined ? {} : { cwd: options.cwd })
+    })
+    const ignoreSigint = (): void => {}
+    process.on("SIGINT", ignoreSigint)
+    const restoreSigint = (): void => {
+      process.removeListener("SIGINT", ignoreSigint)
+    }
+    child.on("error", (error) => {
+      restoreSigint()
+      resume(Effect.fail(new FlowLaunchError({ message: error.message })))
+    })
+    child.on("exit", (code, signal) => {
+      restoreSigint()
+      if (signal !== null) {
+        resume(Effect.succeed(128 + (constants.signals[signal] ?? 15)))
+      } else {
+        resume(Effect.succeed(code ?? 1))
+      }
+    })
+    return Effect.sync(() => {
+      restoreSigint()
+      child.kill("SIGINT")
+    })
+  })

package/src/Menu.ts

@@ -0,0 +1,123 @@
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import { FileSystem } from "effect/FileSystem"
+import * as Prompt from "effect/unstable/cli/Prompt"
+import { coderChoices, findOnPath, resolvedCoderToken } from "./CoderChoice.ts"
+import { discoverFlows, type DiscoveredFlow, type FlowTierPaths } from "./FlowCatalog.ts"
+import { launchFlow } from "./FlowLaunch.ts"
+
+type MenuAction = "run" | "view" | "exit"
+
+const flowChoice = (flow: DiscoveredFlow): Prompt.SelectChoice<DiscoveredFlow> => {
+  const shadows = flow.shadows.length === 0 ? "" : ` (shadows ${flow.shadows.join(", ")})`
+  return {
+    title: `${flow.name} [${flow.tier}]${shadows}`,
+    value: flow,
+    ...(flow.description === undefined ? {} : { description: flow.description })
+  }
+}
+
+const selectFlow = Effect.fn("@llm4ts/shell/Menu.selectFlow")(function* (tiers: FlowTierPaths) {
+  const flows = yield* discoverFlows(tiers)
+  if (flows.length === 0) {
+    yield* Console.error("no flows discovered — add scripts under .llm4ts/flows/")
+    return undefined
+  }
+  return yield* Prompt.run(
+    Prompt.select({
+      message: "Which flow?",
+      choices: flows.map(flowChoice)
+    })
+  )
+})
+
+const selectCoder = Effect.fn("@llm4ts/shell/Menu.selectCoder")(function* (
+  environment: Readonly<Record<string, string | undefined>>
+) {
+  const resolved = resolvedCoderToken(environment)
+  const choices: Array<Prompt.SelectChoice<string | undefined>> = [
+    {
+      title: `environment default (${resolved})`,
+      value: undefined,
+      description: "Use LLM4TS_CODER as-is"
+    },
+    ...coderChoices.map(
+      (choice): Prompt.SelectChoice<string | undefined> => ({
+        title:
+          findOnPath(choice.executable, environment) === undefined
+            ? choice.token
+            : `${choice.token} ✓ found`,
+        value: choice.token
+      })
+    )
+  ]
+  return yield* Prompt.run(Prompt.select({ message: "Which coding agent?", choices }))
+})
+
+const runFlowInteractive = Effect.fn("@llm4ts/shell/Menu.runFlowInteractive")(function* (
+  tiers: FlowTierPaths
+) {
+  const flow = yield* selectFlow(tiers)
+  if (flow === undefined) {
+    return
+  }
+  if (flow.description !== undefined) {
+    yield* Console.log(`${flow.name}: ${flow.description}`)
+  }
+  const task = yield* Prompt.run(
+    Prompt.text({ message: "Task text (empty uses the flow's default)" })
+  )
+  const coder = yield* selectCoder(process.env)
+  const exitCode = yield* launchFlow({
+    flowPath: flow.path,
+    taskArgs: task.trim().length === 0 ? [] : [task],
+    ...(coder === undefined ? {} : { coder })
+  })
+  yield* exitCode === 0
+    ? Console.log(`${flow.name} completed`)
+    : Console.error(`${flow.name} exited with code ${exitCode}`)
+})
+
+const viewFlowInteractive = Effect.fn("@llm4ts/shell/Menu.viewFlowInteractive")(function* (
+  tiers: FlowTierPaths
+) {
+  const flow = yield* selectFlow(tiers)
+  if (flow === undefined) {
+    return
+  }
+  const fs = yield* FileSystem
+  const source = yield* fs.readFileString(flow.path).pipe(Effect.orElseSucceed(() => ""))
+  yield* Console.log(source.trimEnd())
+})
+
+/**
+ * The interactive main menu: run a flow, view a flow, exit. Ctrl-C inside a
+ * prompt quits the menu cleanly rather than crashing the shell.
+ */
+export const mainMenu = Effect.fn("@llm4ts/shell/Menu.mainMenu")(function* (tiers: FlowTierPaths) {
+  while (true) {
+    const action = yield* Prompt.run(
+      Prompt.select<MenuAction>({
+        message: "llm4ts shell",
+        choices: [
+          { title: "Run a flow", value: "run" },
+          { title: "View a flow", value: "view" },
+          { title: "Exit", value: "exit" }
+        ]
+      })
+    ).pipe(Effect.catchTag("QuitError", () => Effect.succeed<MenuAction>("exit")))
+    switch (action) {
+      case "run": {
+        yield* runFlowInteractive(tiers).pipe(Effect.catchTag("QuitError", () => Effect.void))
+        break
+      }
+      case "view": {
+        yield* viewFlowInteractive(tiers).pipe(Effect.catchTag("QuitError", () => Effect.void))
+        break
+      }
+      case "exit": {
+        return
+      }
+    }
+  }
+})

package/src/Package.ts

@@ -0,0 +1,11 @@
+import { createRequire } from "node:module"
+import * as Schema from "effect/Schema"
+
+const Manifest = Schema.Struct({ version: Schema.String })
+
+const manifest = Schema.decodeUnknownSync(Manifest)(
+  createRequire(import.meta.url)("../package.json")
+)
+
+export const packageName = "@llm4ts/shell"
+export const packageVersion: string = manifest.version

package/src/ResolveFallback.ts

@@ -0,0 +1,31 @@
+/**
+ * Module-resolution fallback registered in flow child processes via
+ * `--import`. Resolution is tried normally first, so a project-local
+ * `node_modules` with its own `@llm4ts/*` pin always wins; only when a bare
+ * specifier fails to resolve from the flow's own location is it retried
+ * anchored at this file — the shell's installation, whose dependencies
+ * include `@llm4ts/*` and `effect`. See ADR 0006.
+ */
+import { registerHooks } from "node:module"
+
+const anchor = import.meta.url
+
+const isBareSpecifier = (specifier: string): boolean =>
+  !specifier.startsWith(".") &&
+  !specifier.startsWith("/") &&
+  !specifier.startsWith("file:") &&
+  !specifier.startsWith("node:") &&
+  !specifier.startsWith("data:")
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    try {
+      return nextResolve(specifier, context)
+    } catch (error) {
+      if (isBareSpecifier(specifier) && context.parentURL !== anchor) {
+        return nextResolve(specifier, { ...context, parentURL: anchor })
+      }
+      throw error
+    }
+  }
+})

package/src/cli-main.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import * as NodeServices from "@effect/platform-node/NodeServices"
+import * as Effect from "effect/Effect"
+import { runShellCommand } from "./Cli.ts"
+
+const exitCodeFor = (error: unknown): number => {
+  if (typeof error === "object" && error !== null && "_tag" in error) {
+    switch (error._tag) {
+      case "ShellUsage":
+      case "ShowHelp":
+        return 2
+      default:
+        return 1
+    }
+  }
+  return 1
+}
+
+const errorMessage = (error: unknown): string | undefined => {
+  if (typeof error === "object" && error !== null && "_tag" in error) {
+    if (error._tag === "ShowHelp") {
+      // Help (with any parse errors) was already rendered by the command runner.
+      return undefined
+    }
+    if ("message" in error && typeof error.message === "string") {
+      return error.message
+    }
+  }
+  return String(error)
+}
+
+Effect.runFork(
+  runShellCommand(process.argv.slice(2)).pipe(
+    Effect.match({
+      onFailure: (error) =>
+        Effect.sync(() => {
+          const message = errorMessage(error)
+          if (message !== undefined) {
+            process.stderr.write(`llm4ts: ${message}\n`)
+          }
+          process.exitCode = exitCodeFor(error)
+        }),
+      onSuccess: () => Effect.void
+    }),
+    Effect.flatten,
+    Effect.provide(NodeServices.layer)
+  )
+)