@llm4ts/flow 2.32.0 → 2.33.0

package/src/Port.ts

@@ -0,0 +1,178 @@
+// Porting a code base file by file (ADR 0028): the manifest, its batches, the
+// deterministic target path, the machine-readable PORT STATUS trailer every
+// draft ends with, and the pilot report. Pure; the flows own the seats.
+import { basename, dirname, extname } from "node:path"
+import * as Schema from "effect/Schema"
+import { DraftApprovalMarker } from "./Approval.ts"
+import type { QueueOutcome } from "./WorkQueue.ts"
+
+export class PortEntry extends Schema.Class<PortEntry>("PortEntry")({
+  /** Repo-relative source path; also the queue item id. */
+  id: Schema.String,
+  source: Schema.String,
+  target: Schema.String,
+  loc: Schema.Int
+}) {}
+
+/**
+ * The target path of a source, from the pack's `target:` template:
+ * `{{dir}}` (the source's directory, "" at the root), `{{base}}` (its name
+ * without extension), `{{ext}}` (the extension without the dot), `{{path}}`
+ * (the whole source path).
+ */
+export const targetPathOf = (template: string, source: string): string => {
+  const dir = dirname(source)
+  const ext = extname(source)
+  const rendered = template
+    .replaceAll("{{dir}}", dir === "." ? "" : dir)
+    .replaceAll("{{base}}", basename(source, ext))
+    .replaceAll("{{ext}}", ext.replace(/^\./u, ""))
+    .replaceAll("{{path}}", source)
+  return rendered.replace(/^\/+/u, "").replaceAll("//", "/")
+}
+
+export const linesOf = (text: string): number =>
+  text.length === 0 ? 0 : text.split(/\r?\n/u).filter((line) => line.trim().length > 0).length
+
+export interface BatchPolicy {
+  /** Files per batch. Default 100. */
+  readonly files?: number
+  /** A batch whose first file is longer than this (lines) shrinks to `small`. Default 2200. */
+  readonly bigLoc?: number
+  /** Default 6. */
+  readonly small?: number
+}
+
+/** Contiguous batches of the manifest; a batch led by a big file is small (the Bun rule). */
+export const batchesOf = (
+  entries: ReadonlyArray<PortEntry>,
+  policy: BatchPolicy = {}
+): ReadonlyArray<ReadonlyArray<PortEntry>> => {
+  const files = Math.max(1, policy.files ?? 100)
+  const bigLoc = policy.bigLoc ?? 2_200
+  const small = Math.max(1, policy.small ?? 6)
+  const batches: Array<ReadonlyArray<PortEntry>> = []
+  let index = 0
+  while (index < entries.length) {
+    const first = entries[index]
+    const size = first !== undefined && first.loc > bigLoc ? small : files
+    batches.push(entries.slice(index, index + size))
+    index += size
+  }
+  return batches
+}
+
+export const PortConfidence = Schema.Literals(["high", "medium", "low"])
+export type PortConfidence = typeof PortConfidence.Type
+
+export interface PortStatus {
+  readonly confidence: PortConfidence | undefined
+  readonly todos: number | undefined
+  readonly notes: string | undefined
+}
+
+const statusWindow = 40
+
+/**
+ * The PORT STATUS trailer of a draft: in any comment syntax, within the last
+ * lines of the file, `confidence: high|medium|low`, `todos: <n>`, `notes: …`.
+ * All undefined when the draft has no trailer.
+ */
+export const portStatusIn = (text: string): PortStatus => {
+  const lines = text.split(/\r?\n/u)
+  const tail = lines.slice(Math.max(0, lines.length - statusWindow))
+  const start = tail.findIndex((line) => /PORT STATUS/u.test(line))
+  if (start < 0) {
+    return { confidence: undefined, todos: undefined, notes: undefined }
+  }
+  const block = tail.slice(start).join("\n")
+  const confidence = /confidence:\s*(high|medium|low)\b/iu.exec(block)?.[1]?.toLowerCase()
+  const todos = /todos?:\s*(\d+)/iu.exec(block)?.[1]
+  const notes = /notes?:\s*(.+)$/imu.exec(block)?.[1]?.trim()
+  return {
+    confidence:
+      confidence === "high" || confidence === "medium" || confidence === "low"
+        ? confidence
+        : undefined,
+    todos: todos === undefined ? undefined : Number.parseInt(todos, 10),
+    notes: notes === undefined || notes.length === 0 ? undefined : notes.replace(/\s*\*\/\s*$/u, "")
+  }
+}
+
+/** The instruction every implementer gets: how to end the file. */
+export const portStatusInstruction = (comment: string): string =>
+  [
+    `End the file with a machine-readable trailer in ${comment} comments, exactly this shape:`,
+    `${comment} PORT STATUS`,
+    `${comment} source: <the source path>`,
+    `${comment} confidence: high | medium | low`,
+    `${comment} todos: <number of TODO(port) markers you left>`,
+    `${comment} notes: <one line: what you could not translate faithfully, or "none">`,
+    "`confidence: low` means the logic is probably wrong and must be re-read against the source."
+  ].join("\n")
+
+export interface PilotFacts {
+  readonly outcomes: ReadonlyArray<QueueOutcome>
+  readonly piloted: number
+  readonly remaining: number
+  readonly elapsedMs: number
+  readonly estimatedCostUsd: number | undefined
+}
+
+const minutes = (ms: number): string => `${(ms / 60_000).toFixed(1)} min`
+
+/** The pilot report (R7 of the plan): rates measured, totals extrapolated, an approval to continue. */
+export const renderPilotReport = (facts: PilotFacts): string => {
+  const done = facts.outcomes.filter((outcome) => outcome.status === "done")
+  const failed = facts.outcomes.filter((outcome) => outcome.status === "failed")
+  const count = (level: PortConfidence) =>
+    done.filter((outcome) => outcome.confidence === level).length
+  const todos = done.reduce((sum, outcome) => sum + (outcome.todos ?? 0), 0)
+  const perItemMs = facts.piloted === 0 ? 0 : facts.elapsedMs / facts.piloted
+  const perItemCost =
+    facts.estimatedCostUsd === undefined || facts.piloted === 0
+      ? undefined
+      : facts.estimatedCostUsd / facts.piloted
+  return [
+    "# Port pilot",
+    "",
+    `- piloted: ${facts.piloted} file(s), ${done.length} done, ${failed.length} failed, in ${minutes(facts.elapsedMs)}`,
+    `- confidence: ${count("high")} high, ${count("medium")} medium, ${count("low")} low; ${todos} TODO(port) marker(s)`,
+    ...(perItemCost === undefined
+      ? []
+      : [
+          `- cost: ~$${(facts.estimatedCostUsd ?? 0).toFixed(2)} (~$${perItemCost.toFixed(3)} per file)`
+        ]),
+    `- remaining: ${facts.remaining} file(s) → about ${minutes(perItemMs * facts.remaining)} at this rate${
+      perItemCost === undefined ? "" : ` and ~$${(perItemCost * facts.remaining).toFixed(2)}`
+    }`,
+    "",
+    ...(failed.length === 0
+      ? []
+      : [
+          "## Failed",
+          "",
+          ...failed.map((outcome) => `- ${outcome.id}: ${outcome.note ?? ""}`),
+          ""
+        ]),
+    "Read the drafted files beside their sources, then tick the box to let the next run",
+    "port the rest; edit `prompts/porting.md` in the pack first if the drafts show a",
+    "pattern the rulebook should settle.",
+    "",
+    DraftApprovalMarker,
+    ""
+  ].join("\n")
+}
+
+/** A whole new file rendered as a unified diff of additions, for reviewers that judge diffs. */
+export const asAddedFileDiff = (path: string, content: string): string => {
+  const lines = content.split(/\r?\n/u)
+  return [
+    `diff --git a/${path} b/${path}`,
+    "new file mode 100644",
+    "--- /dev/null",
+    `+++ b/${path}`,
+    `@@ -0,0 +1,${lines.length} @@`,
+    ...lines.map((line) => `+${line}`)
+  ].join("\n")
+}

package/src/Retro.ts

@@ -9,7 +9,7 @@
  * tasks appended to a story's plan, or a story entry edited in the epic
  * plan (which restarts that story). Nothing is applied unreviewed.
  */
-import { join } from "node:path"
+import { join, resolve, sep } from "node:path"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
 import * as Schema from "effect/Schema"
@@ -1278,7 +1278,14 @@ export const applyApprovedRetros = Effect.fn("@llm4ts/flow/Retro.apply")(functio
         yield* say(`${runId}: rule edit to ${edit.target} is not allowed; skipped`)
         continue
       }
-      const path = join(options.rulesRoot, edit.target)
+      const root = resolve(options.rulesRoot)
+      const path = resolve(root, edit.target)
+      // The allowlist already rejects absolute paths and `..`; this keeps the
+      // resolved file under the repository root whatever the string looked like.
+      if (path !== root && !path.startsWith(`${root}${sep}`)) {
+        yield* say(`${runId}: rule edit to ${edit.target} resolves outside the repository; skipped`)
+        continue
+      }
       const existing = yield* files.read(path).pipe(Effect.catch(() => Effect.succeed(undefined)))
       const next = applyRuleEdit(existing, edit)
       if (next === undefined) {

package/src/WorkQueue.ts

@@ -0,0 +1,194 @@
+// A mechanical work queue (ADR 0028): many small units with a filesystem
+// "done" predicate, worked in rounds under a concurrency cap, each unit's
+// failure becoming the next round's item, progress persisted as a ledger so
+// a rerun resumes where the run stopped. The Bun port's shape; a story is a
+// feature with a DAG and a judge, a queue item is a file with a predicate.
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { Stalled, describeFlowError, type FlowError } from "./FlowError.ts"
+import {
+  Info,
+  StageCompleted,
+  StageFailed,
+  StageStarted,
+  type FlowEventsShape
+} from "./FlowEvents.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+export interface QueueItem {
+  readonly id: string
+}
+
+export const Confidence = Schema.Literals(["high", "medium", "low"])
+
+/** One line of the ledger: what happened to one item in one round. */
+export class QueueOutcome extends Schema.Class<QueueOutcome>("QueueOutcome")({
+  id: Schema.String,
+  round: Schema.Int,
+  status: Schema.Literals(["done", "failed"]),
+  ms: Schema.Number,
+  note: Schema.optionalKey(Schema.String),
+  confidence: Schema.optionalKey(Confidence),
+  todos: Schema.optionalKey(Schema.Int),
+  at: Schema.Number
+}) {}
+
+const encodeOutcome = Schema.encodeSync(Schema.fromJsonString(QueueOutcome))
+const decodeOutcome = Schema.decodeUnknownOption(Schema.fromJsonString(QueueOutcome))
+
+/** What a unit of work reports back; the queue records it. */
+export interface WorkResult {
+  readonly note?: string
+  readonly confidence?: "high" | "medium" | "low"
+  readonly todos?: number
+}
+
+export interface RunQueueOptions<Item extends QueueItem> {
+  readonly label: string
+  readonly items: ReadonlyArray<Item>
+  /** The filesystem predicate: an item whose output exists is done, whatever the ledger says. */
+  readonly done: (item: Item) => Effect.Effect<boolean, FlowError>
+  /** One unit of work: implement, review, fix; the queue catches its failure. */
+  readonly work: (item: Item, round: number) => Effect.Effect<WorkResult, FlowError>
+  readonly events: FlowEventsShape
+  readonly concurrency?: number
+  /** Rounds over the items that failed; default 3. */
+  readonly maxRounds?: number
+  /** Where outcomes are appended, one JSON line each; omit to keep none. */
+  readonly ledger?: { readonly files: PlainFileStoreShape; readonly path: string }
+  /** After every round: the done items of that round, for a commit. */
+  readonly afterRound?: (
+    round: number,
+    done: ReadonlyArray<Item>,
+    failed: ReadonlyArray<Item>
+  ) => Effect.Effect<void, FlowError>
+}
+
+export interface QueueReport<Item extends QueueItem> {
+  readonly outcomes: ReadonlyArray<QueueOutcome>
+  readonly rounds: number
+  /** Items still not done when the queue stopped. */
+  readonly pending: ReadonlyArray<Item>
+  /** Items that were already done before the first round (a resume). */
+  readonly skipped: ReadonlyArray<Item>
+}
+
+export const readLedger = (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.Effect<ReadonlyArray<QueueOutcome>, FlowError> =>
+  Effect.map(files.read(path), (text) =>
+    (text ?? "")
+      .split("\n")
+      .filter((line) => line.trim().length > 0)
+      .flatMap((line) => {
+        const decoded = decodeOutcome(line)
+        return decoded._tag === "Some" ? [decoded.value] : []
+      })
+  )
+
+/**
+ * Works the items that are not done, round after round, until every item is
+ * done, the rounds run out, or a round makes no progress (typed `Stalled`).
+ */
+export const runQueue = Effect.fn("@llm4ts/flow/WorkQueue.run")(function* <Item extends QueueItem>(
+  options: RunQueueOptions<Item>
+): Effect.fn.Return<QueueReport<Item>, FlowError> {
+  const concurrency = Math.max(1, options.concurrency ?? 4)
+  const maxRounds = Math.max(1, options.maxRounds ?? 3)
+  const outcomes: Array<QueueOutcome> = []
+  const record = (outcome: QueueOutcome): Effect.Effect<void, FlowError> =>
+    Effect.gen(function* () {
+      outcomes.push(outcome)
+      if (options.ledger !== undefined) {
+        yield* options.ledger.files.append(options.ledger.path, `${encodeOutcome(outcome)}\n`)
+      }
+    })
+
+  const skipped: Array<Item> = []
+  let pending: Array<Item> = []
+  for (const item of options.items) {
+    if (yield* options.done(item)) {
+      skipped.push(item)
+    } else {
+      pending.push(item)
+    }
+  }
+  if (skipped.length > 0) {
+    yield* options.events.publish(
+      Info.make({
+        message: `${options.label}: ${skipped.length} of ${options.items.length} item(s) already done; ${pending.length} to go`
+      })
+    )
+  }
+
+  let rounds = 0
+  while (pending.length > 0 && rounds < maxRounds) {
+    rounds += 1
+    const round = rounds
+    yield* options.events.publish(
+      Info.make({ message: `${options.label}: round ${round}, ${pending.length} item(s)` })
+    )
+    const results = yield* Effect.forEach(
+      pending,
+      (item) =>
+        Effect.gen(function* () {
+          const stage = `${options.label} ${item.id}`
+          yield* options.events.publish(StageStarted.make({ stage, lane: item.id }))
+          const started = yield* Clock.currentTimeMillis
+          const result = yield* options.work(item, round).pipe(
+            Effect.map((value) => ({ ok: true as const, value })),
+            Effect.catch((error: FlowError) =>
+              Effect.succeed({ ok: false as const, error: describeFlowError(error) })
+            )
+          )
+          const ended = yield* Clock.currentTimeMillis
+          // The predicate decides, not the work's own account of itself.
+          const finished = result.ok && (yield* options.done(item))
+          const outcome = QueueOutcome.make({
+            id: item.id,
+            round,
+            status: finished ? "done" : "failed",
+            ms: ended - started,
+            at: ended,
+            ...(result.ok
+              ? {
+                  ...(finished
+                    ? {}
+                    : { note: result.value.note ?? "the work ended but left no output" }),
+                  ...(finished && result.value.note !== undefined
+                    ? { note: result.value.note }
+                    : {}),
+                  ...(result.value.confidence === undefined
+                    ? {}
+                    : { confidence: result.value.confidence }),
+                  ...(result.value.todos === undefined ? {} : { todos: result.value.todos })
+                }
+              : { note: result.error })
+          })
+          yield* record(outcome)
+          yield* options.events.publish(
+            finished
+              ? StageCompleted.make({ stage, lane: item.id })
+              : StageFailed.make({ stage, lane: item.id, message: outcome.note ?? "failed" })
+          )
+          return { item, finished }
+        }),
+      { concurrency }
+    )
+    const done = results.filter((entry) => entry.finished).map((entry) => entry.item)
+    const failed = results.filter((entry) => !entry.finished).map((entry) => entry.item)
+    if (options.afterRound !== undefined) {
+      yield* options.afterRound(round, done, failed)
+    }
+    if (done.length === 0 && failed.length > 0) {
+      return yield* Stalled.make({
+        signal: "no-progress",
+        detail: `${options.label}: round ${round} finished none of its ${failed.length} item(s)`
+      })
+    }
+    pending = failed
+  }
+  return { outcomes, rounds, pending, skipped }
+})