@drkmttr/adhere 0.18.1 → 0.23.0

package/src/create/ask.ts

@@ -0,0 +1,363 @@
+/**
+ * What `adhere rules create` asks the coding agent, and the answers it
+ * decodes: the rule's shape, code in the repo for the user to judge, and the
+ * rule file itself.
+ */
+import { type Agent, askAgent } from "#create/agents.ts";
+import { spinning } from "#create/look.ts";
+import { type OxlintCatalog, oxlintCatalog, oxlintRuleIds } from "#oxlint/catalog.ts";
+import { Effect, Schema, SchemaGetter } from "effect";
+import skill from "../../skills/adhere/SKILL.md" with { type: "text" };
+
+export class RuleNotCreated extends Schema.TaggedError<RuleNotCreated>()("RuleNotCreated", {
+  message: Schema.String,
+}) {}
+
+const KNOWN_LINTERS = new Set(oxlintRuleIds);
+
+/**
+ * What a rule's options look like on the wire: one plain JSON string, parsed
+ * once here. Not `Schema.fromJsonString`, which marks it with a
+ * `contentMediaType` that strict structured outputs reject.
+ */
+const OptionsFromJson = Schema.String.pipe(
+  Schema.decodeTo(Schema.Array(Schema.Json), {
+    decode: SchemaGetter.parseJson() as SchemaGetter.Getter<ReadonlyArray<Schema.Json>, string>,
+    encode: SchemaGetter.stringifyJson(),
+  }),
+);
+
+/**
+ * A native rule id, a plain string on the wire: the catalog has more ids than
+ * a provider's largest enum takes, so the catalog check runs here instead.
+ */
+const Linter = Schema.String.check(
+  Schema.makeFilter((id) =>
+    KNOWN_LINTERS.has(id) ? undefined : "not an oxlint rule in adhere's catalog",
+  ),
+);
+
+/** The agent's answer: `linter` and its options are compact on the wire, a decoded pair here. */
+export const Shape = Schema.Struct({
+  linter: Schema.NullOr(Linter),
+  linterOptions: OptionsFromJson,
+  mechanical: Schema.Boolean,
+  mechanicalReason: Schema.String,
+  scope: Schema.Literals(["project", "org"]),
+  scopeReason: Schema.String,
+  format: Schema.Literals(["markdown", "typescript"]),
+  formatReason: Schema.String,
+  typeAware: Schema.Boolean,
+  reads: Schema.Array(Schema.Literals(["workspacePackages", "dependents"])),
+  contextReason: Schema.String,
+  names: Schema.Array(Schema.String),
+});
+export type Shape = typeof Shape.Type;
+
+const Candidate = Schema.Struct({
+  file: Schema.String,
+  startLine: Schema.Int,
+  endLine: Schema.Int,
+  violation: Schema.Boolean,
+  reason: Schema.String,
+});
+export type Candidate = typeof Candidate.Type;
+export const Candidates = Schema.Struct({ candidates: Schema.Array(Candidate) });
+
+/**
+ * A diagnostic location on the wire: strict structured outputs require every
+ * property, so agents send `null` when a location does not matter. Internally
+ * `null` decodes to `undefined`, which `JSON.stringify` then omits.
+ */
+const Location = Schema.NullOr(Schema.Int).pipe(
+  Schema.decodeTo(Schema.UndefinedOr(Schema.Int), {
+    decode: SchemaGetter.transform((value: number | null) => value ?? undefined),
+    encode: SchemaGetter.transform((value: number | undefined) => value ?? null),
+  }),
+);
+
+/** One diagnostic an oxlint plugin must report for an invalid example. */
+const PluginError = Schema.Struct({
+  message: Schema.String,
+  line: Location,
+  column: Location,
+});
+
+/** An invalid example for an oxlint plugin: code and the diagnostics it must produce. */
+const PluginInvalid = Schema.Struct({
+  code: Schema.String,
+  errors: Schema.Array(PluginError),
+});
+
+/** An agent's oxlint JS plugin rule, and the examples that show it works. */
+export const PluginDraft = Schema.Struct({
+  plugin: Schema.String,
+  pluginName: Schema.String,
+  ruleName: Schema.String,
+  valid: Schema.Array(Schema.String),
+  invalid: Schema.Array(PluginInvalid),
+});
+export type PluginDraft = typeof PluginDraft.Type;
+
+/** Code from the repo the user has judged: where it is, as the file holds it, and whether it breaks the rule. */
+export interface Reviewed {
+  readonly where: string;
+  readonly code: string;
+  readonly violation: boolean;
+  /** Whether the user's call matched the agent's. */
+  readonly agreed: boolean;
+  /** What the user added to the call, when they did. */
+  readonly note?: string;
+}
+
+export const shapePrompt = (
+  idea: string,
+  catalog: OxlintCatalog = oxlintCatalog,
+) => `You are helping write a rule for adhere, a linter for conventions a normal linter cannot check: a model, Jev, judges each source file against each rule. A rule lives in .adhere/rules/<topic>/<name>/, either in this repository, for its own code, or in the organization's shared rules repository, which every repository installs from.
+
+The user wants a rule for: ${idea}
+
+Look at this repository as much as you need, then answer:
+- linter: a string holding the id of one native oxlint rule listed below that already checks exactly this, or null. Do not name a rule that is not listed.
+- linterOptions: a string holding that rule's own settings as a JSON array, exactly as a config writes them after the severity; for example the string '[{"paths": [{"name": "lodash"}]}]' for no-restricted-imports banning lodash, or '[{"max": 200}]' for max-lines. Use '[]' only when the rule's default settings already enforce this idea; a rule that does nothing until configured (no-restricted-imports, no-restricted-globals, no-restricted-properties, no-restricted-exports, id-length, max-lines, max-params, no-magic-numbers, unicorn/filename-case, typescript/no-restricted-types) always needs its settings here. When linter is null, use '[]'.
+- mechanical: true when a small custom oxlint JS plugin that sees only the syntax tree and its scopes could decide this; false when it needs TypeScript types, the text of other files, a different parser, or anything else oxlint's JS plugins cannot see. When typeAware is true, mechanical must be false.
+- mechanicalReason: one sentence saying why.
+- scope: "project" when the rule is about this repository's own code, "org" when it would hold in any of the organization's repositories.
+- scopeReason: one sentence saying why.
+- format: "markdown" for a RULE.md, the rule's text and examples; nearly every rule is one. "typescript" for a RULE.ts, only when judging a file needs something neither the file nor the shared context below shows, such as a schema or a list another file holds: its appendState hook reads it and adds it to what Jev reads for that rule.
+- formatReason: one sentence saying why.
+- typeAware: true when judging needs the compiler's view of the file: the types of the names it uses, or the declarations of what it uses from other files. It is slower and costs more, so false unless the file cannot show it.
+- reads: the shared context it needs: "workspacePackages", the workspace packages the file imports and their directories, and "dependents", what depends on the file. Empty when the code is enough.
+- contextReason: one sentence saying why typeAware and reads are as you set them.
+- names: three ids for the rule, each "topic/rule-name" in lowercase kebab case. Reuse a topic from .adhere/rules/ where one fits.
+
+The catalog below is bundled with adhere and was generated from oxlint ${catalog.version}; the oxlint installed in this repository may be a different version, so a listed rule can be absent there and an installed native rule can be missing from this list. Its native rules follow, one per line as "id — what it checks". Use these ids exactly; a rule not listed here is not one adhere treats as native.
+
+${catalog.rules.map((rule) => `- ${rule.id} — ${rule.summary} (${rule.category}${rule.typeAware ? ", type-aware" : ""})`).join("\n")}`;
+
+export const examplesPrompt = (
+  idea: string,
+  id: string,
+) => `Find code in this repository to test the adhere rule ${id}: ${idea}
+
+Give up to six excerpts, a mix of code that breaks the rule and code that follows it; borderline cases are the most useful. Each is the repo-relative file, the excerpt's first and last line numbers, at most 15 lines apart, violation: whether it breaks the rule, and reason: one sentence saying why. Use only code that exists, and give none when there is none.`;
+
+const contextOf = (shape: Shape) =>
+  [
+    "`code`",
+    ...shape.reads.map((read) => `\`${read}\``),
+    ...(shape.typeAware ? ["`symbols`", "`references`"] : []),
+  ].join(", ");
+
+const readsInstruction = (shape: Shape) => {
+  const reads = [...shape.reads, ...(shape.typeAware ? ["symbols", "references"] : [])];
+  if (reads.length === 0) return "Declare no `reads`: the code alone is enough.";
+  return `Declare the context Jev needs beside the code as \`reads: [${reads.map((read) => `"${read}"`).join(", ")}]\` ${shape.format === "typescript" ? "in `defineRule({...})`" : "in its front matter"}. A rule's \`reads\` is a declaration, not an enablement: the project's config still decides what Jev reads, and lint warns that the rule may be less accurate until a declared read is enabled.`;
+};
+
+const typescriptFormat = (shape: Shape) =>
+  `Write it as a RULE.ts, because ${shape.formatReason} It imports defineRule from "@drkmttr/adhere" and default-exports defineRule({ description, details, must, never, reads, appendState }). appendState(state, file, Bun) runs before each request for the rule: file is { path, contents }, its path absolute, and Bun is Bun's API, as in Bun.file(path).text() or new Bun.Glob(pattern). What it returns is spread over the request's state; name each key it adds in the description, in backticks. Helpers go in the same file.`;
+
+const reviewedOf = (reviewed: ReadonlyArray<Reviewed>) =>
+  reviewed.length === 0
+    ? "No code from the repository was judged: write short examples of your own."
+    : `The user judged this code from the repository. Base the rule's examples on what shows it best; you need not use all of it. Where the user overruled your first call, word the rule so the difference is clear.\n\n${reviewed
+        .map(
+          ({ where, code, violation, agreed, note }) =>
+            `${violation ? "Breaks the rule" : "Does not break the rule"}, ${where}${agreed ? "" : " (overruled)"}${note === undefined ? "" : `\nThe user's note: ${note}`}\n\`\`\`\n${code}\n\`\`\``,
+        )
+        .join("\n\n")}`;
+
+export const writePrompt = (
+  idea: string,
+  id: string,
+  shape: Shape,
+  reviewed: ReadonlyArray<Reviewed>,
+) => `${skill}
+
+---
+
+Using the reference above, write the rule file for this adhere rule.
+
+Rule id: ${id}
+What it enforces: ${idea}
+What Jev reads beside the rule: ${contextOf(shape)}
+${readsInstruction(shape)}
+${shape.format === "typescript" ? typescriptFormat(shape) : "Write it as a RULE.md."}
+
+${reviewedOf(reviewed)}
+
+Reply with only the file's contents, starting with its ${shape.format === "typescript" ? "imports" : "front matter"}.`;
+
+/**
+ * Asks for an oxlint JS plugin rule. The reply is a self-contained ESLint v9
+ * plain-ESM plugin: oxlint loads it as written, so no TypeScript, imports, or
+ * build-tool helpers.
+ */
+export const pluginPrompt = (
+  idea: string,
+  id: string,
+  reviewed: ReadonlyArray<Reviewed>,
+) => `Write one rule for oxlint as a JS plugin. The rule is called ${id}; it enforces: ${idea}
+
+Oxlint's JS plugin API is ESLint v9's. Write a plain ESM module:
+- No TypeScript, no imports, no Vite+ or build-tool helpers, no dependencies: oxlint loads the file as it is.
+- Default-export { meta: { name: "<pluginName>" }, rules: { "<ruleName>": rule } }.
+- The rule is { meta: { schema: [], messages: {...} }, create(context) { return { SomeNode(node) { ... } }; } }.
+- Report with context.report({ message: "a literal message", node }) so the expected diagnostic is exact. Do not use messageId.
+- Judge only the syntax tree and scopes. Oxlint JS plugins cannot see TypeScript types, other files' contents, or another parser's AST; do not reach for them.
+- pluginName and ruleName are lowercase kebab case. pluginName must not be one oxlint has natively, such as eslint, typescript, react, import, jsdoc, jest, vitest, unicorn, jsx-a11y, nextjs, node, promise, vue, oxc, or react-perf.
+- Give at least two valid snippets that must report nothing, and at least two invalid snippets. Each invalid snippet carries every diagnostic it must produce: message exactly as context.report writes it; line (1-based) and column (0-based) are always present: use null when a diagnostic's position does not matter.
+
+${reviewedOf(reviewed)}
+
+Answer with JSON: plugin (the module's whole source), pluginName, ruleName, valid (code strings), invalid (objects with code and errors, each { message, line, column }, with line and column null when unspecified).`;
+
+/** What to send back to the agent once its plugin or examples fail oxlint's RuleTester. */
+export const pluginFixPrompt = (
+  prompt: string,
+  draft: PluginDraft,
+  problems: ReadonlyArray<string>,
+) => `${prompt}
+
+Your last answer failed its own tests:
+${problems.map((problem) => `- ${problem}`).join("\n")}
+
+The plugin was:
+
+\`\`\`js
+${draft.plugin}
+\`\`\`
+
+The examples were:
+${draft.valid.map((code, index) => `Valid ${index + 1}:\n\`\`\`\n${code}\n\`\`\``).join("\n")}
+${draft.invalid
+  .map(
+    (example, index) =>
+      `Invalid ${index + 1}:\n\`\`\`\n${example.code}\n\`\`\`\nExpected: ${JSON.stringify(example.errors.map((error) => ({ message: error.message, line: error.line ?? null, column: error.column ?? null })))}`,
+  )
+  .join("\n")}
+
+Fix the rule or the examples so every valid example reports nothing and every invalid example reports exactly the diagnostics it expects. Reply with only the corrected JSON.`;
+
+/** The agent's revised native settings, as the wire holds them: a JSON array in a string. */
+export const NativeRevision = Schema.Struct({ options: OptionsFromJson });
+export type NativeRevision = typeof NativeRevision.Type;
+
+/**
+ * What the trial found, as the agent reads it: the saved report's path, the
+ * files it judged, and what the user made of each finding.
+ */
+export const inspectionPrompt = (report: string, id: string) =>
+  `adhere trialled the rule ${id} on real files without installing it. The full report is at ${report}. Read it, and read the source files it names, then answer in plain text:
+- Whether the rule catches what it should and what it should not, citing the report's findings.
+- Which findings look like false positives or false negatives, and why.
+- Concrete changes to the rule's wording or examples, if any.
+Do not edit files. Keep it short.`;
+
+/** Asks for the adhere rule again, with what the trial found and what the user made of it. */
+export const adhereRevisionPrompt = (
+  idea: string,
+  id: string,
+  shape: Shape,
+  draft: string,
+  evidence: string,
+) => `${skill}
+
+---
+
+Revise the adhere rule ${id}. It enforces: ${idea}
+What Jev reads beside the rule: ${contextOf(shape)}
+${readsInstruction(shape)}
+${shape.format === "typescript" ? typescriptFormat(shape) : "Write it as a RULE.md."}
+
+A trial judged real files against the current rule. What it found, and what the user made of it:
+
+${evidence}
+
+The current file:
+
+${draft}
+
+Keep what the evidence supports and change what it contradicts. Reply with only the corrected file, starting with its ${shape.format === "typescript" ? "imports" : "front matter"}.`;
+
+/** Asks for the oxlint plugin again, with what the trial found and what the user made of it. */
+export const pluginRevisionPrompt = (
+  idea: string,
+  id: string,
+  draft: PluginDraft,
+  evidence: string,
+) => `Revise the oxlint JS plugin rule ${id}; it enforces: ${idea}
+
+A trial ran the current plugin on real files. What it found, and what the user made of it:
+
+${evidence}
+
+The current plugin:
+
+\`\`\`js
+${draft.plugin}
+\`\`\`
+
+Its examples were:
+${draft.valid.map((code, index) => `Valid ${index + 1}:\n\`\`\`\n${code}\n\`\`\``).join("\n")}
+${draft.invalid
+  .map(
+    (example, index) =>
+      `Invalid ${index + 1}:\n\`\`\`\n${example.code}\n\`\`\`\nExpected: ${JSON.stringify(example.errors.map((error) => ({ message: error.message, line: error.line ?? null, column: error.column ?? null })))}`,
+  )
+  .join("\n")}
+
+Keep the API rules: plain ESM, no imports, default-export { meta, rules }, and report with context.report({ message, node }). Reply with only JSON: plugin, pluginName, ruleName, valid, invalid, as before.`;
+
+/** Asks for the native rule's settings again, with what the trial found and what the user made of it. */
+export const nativeRevisionPrompt = (
+  idea: string,
+  id: string,
+  options: ReadonlyArray<unknown>,
+  evidence: string,
+) => `Revise the settings for the oxlint rule ${id}; it should enforce: ${idea}
+
+A trial ran it on real files with the settings ${JSON.stringify(options)}. What it found, and what the user made of it:
+
+${evidence}
+
+Answer with JSON: options, a string holding the rule's settings as a JSON array, exactly as a config writes them after the severity. Use "[]" only when the rule's default settings enforce the idea.`;
+
+/** An agent's reply as the file it holds, without the fence it may wrap it in. */
+export const unfenced = (text: string) =>
+  /^\s*```[a-z]*\n([\s\S]*?)\n```\s*$/.exec(text)?.[1] ?? text.trim();
+
+export const asking = (agent: Agent, what: string, cwd: string, prompt: string, schema?: object) =>
+  spinning(
+    `Asking ${agent} ${what}`,
+    Effect.tryPromise({
+      try: () => askAgent(agent, prompt, cwd, schema),
+      catch: (cause) =>
+        new RuleNotCreated({ message: cause instanceof Error ? cause.message : String(cause) }),
+    }),
+  );
+
+export const askingFor = <A, I>(
+  agent: Agent,
+  what: string,
+  cwd: string,
+  prompt: string,
+  Answer: Schema.Codec<A, I>,
+) =>
+  asking(
+    agent,
+    what,
+    cwd,
+    prompt,
+    Schema.toJsonSchemaDocument(Answer, { onExcessProperty: "error" }).schema,
+  ).pipe(
+    Effect.flatMap((text) =>
+      Schema.decodeUnknownEffect(Schema.fromJsonString(Answer))(text).pipe(
+        Effect.mapError(
+          (problem) =>
+            new RuleNotCreated({ message: `${agent}'s answer did not decode: ${problem.message}` }),
+        ),
+      ),
+    ),
+  );

package/src/create/examples.ts

@@ -0,0 +1,94 @@
+/**
+ * Code from the repository that shows a rule, read from the file itself and
+ * put to the user, who says whether each excerpt breaks the rule.
+ */
+import { type Agent } from "#create/agents.ts";
+import {
+  type Candidate,
+  Candidates,
+  type Reviewed,
+  askingFor,
+  examplesPrompt,
+} from "#create/ask.ts";
+import { excerpt, line, note, said, warn } from "#create/look.ts";
+import { Effect, FileSystem, Option, Path } from "effect";
+import { Prompt } from "effect/cli";
+
+/**
+ * Shows the user each excerpt the agent found, read from the file itself with
+ * three lines either side, and asks whether it breaks the rule. An excerpt
+ * that does not match the repo is left out.
+ */
+export const review = (agent: Agent, root: string, candidates: ReadonlyArray<Candidate>) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const reviewed: Array<Reviewed> = [];
+    let missing = 0;
+    for (const [index, candidate] of candidates.entries()) {
+      const file = path.resolve(root, candidate.file);
+      const where = path.relative(root, file);
+      const text = where.startsWith("..")
+        ? Option.none()
+        : yield* fs.readFileString(file).pipe(Effect.option);
+      const lines = Option.getOrElse(text, () => "").split("\n");
+      const start = candidate.startLine;
+      if (Option.isNone(text) || start < 1 || start > lines.length) {
+        missing++;
+        continue;
+      }
+      const end = Math.min(Math.max(candidate.endLine, start), start + 14, lines.length);
+      const at = where + ":" + (start === end ? start : start + "-" + end);
+      yield* line("");
+      yield* line(at + " (" + (index + 1) + " of " + candidates.length + ")");
+      yield* excerpt(lines, {
+        from: Math.max(1, start - 3),
+        to: Math.min(lines.length, end + 3),
+        start,
+        end,
+      });
+      yield* said(
+        agent + ": " + (candidate.violation ? "breaks it" : "follows it") + ". " + candidate.reason,
+      );
+      const violation = yield* Prompt.run(
+        Prompt.Confirm({ message: "Is this a violation?", initial: candidate.violation }),
+      );
+      const note = (yield* Prompt.run(
+        Prompt.String({ message: "Note for the agent (optional)", default: "" }),
+      )).trim();
+      reviewed.push({
+        where: at,
+        code: lines.slice(start - 1, end).join("\n"),
+        violation,
+        agreed: violation === candidate.violation,
+        ...(note === "" ? {} : { note }),
+      });
+    }
+    if (missing > 0) {
+      yield* note(
+        "Left out " + missing + " excerpt" + (missing === 1 ? "" : "s") + " not found in the repo.",
+      );
+    }
+    return reviewed;
+  });
+
+/**
+ * Asks the agent for excerpts in the project the user is in, then puts them to
+ * the user. An agent that cannot search the repo leaves the examples to the
+ * rule's draft.
+ */
+export const reviewedInRepository = (agent: Agent, root: string, idea: string, id: string) =>
+  Effect.gen(function* () {
+    const found = yield* askingFor(
+      agent,
+      "for code to judge",
+      root,
+      examplesPrompt(idea, id),
+      Candidates,
+    ).pipe(
+      Effect.catch(({ message }) =>
+        warn("No code from the repo: " + message).pipe(Effect.as({ candidates: [] })),
+      ),
+    );
+    return yield* review(agent, root, found.candidates);
+  });

package/src/create/look.ts

@@ -0,0 +1,191 @@
+/**
+ * How `adhere rules create` looks: Clack's rail, drawn by effect/cli's own
+ * prompts through their theme, with the wizard's own lines hung on the same
+ * rail, and a spinner, as `gum spin` draws one, while an agent works.
+ */
+import { highlightedLines } from "#workflows/format.ts";
+import { ruleBodyOf } from "#markdown.ts";
+import { Status, clearingStatus } from "#services/Status.ts";
+import { Console, Duration, Effect, Fiber } from "effect";
+import { Prompt } from "effect/cli";
+
+const rgbColor = (r: number, g: number, b: number) => `\x1B[38;2;${r};${g};${b}m`;
+const colorCode = (n: number) => `\x1B[38;5;${n}m`;
+const COLORS = {
+  PURPLE: colorCode(99),
+  KIWI: colorCode(156),
+  PINK: colorCode(212),
+  FG: rgbColor(220, 220, 240),
+  MUTED: rgbColor(180, 180, 190),
+  RED: colorCode(197),
+  ACCENT: rgbColor(242, 205, 205),
+};
+
+/** One column of left padding, so the whole wizard sits clear of the terminal's edge. */
+const PAD = " ";
+
+/**
+ * The prompts' theme. Every symbol carries `PAD`, so each prompt's rows start
+ * where the rail's do; `pointerSmall` also pads a validation error and adds
+ * one space before the `›` that ends an active row.
+ */
+export const look: Partial<Prompt.Theme> = {
+  // primaryColor: `\x1B[0;37m`,
+  // mutedColor: COLORS.MUTED,
+  successColor: COLORS.KIWI,
+  submittedColor: COLORS.PURPLE,
+  errorColor: COLORS.RED,
+  // toggleSeparator: " / ",
+  // passwordMask: `${COLORS.MUTED}*${ESC}`,
+  // prefix: `│\n│${COLORS.PINK} ◇${ESC}`,
+  // prefix: `\n ◇`,
+  // tick: `\n ✓`,
+  // tick: `│\n│${COLORS.KIWI} ✓${ESC}`,
+  // pointer: `${COLORS.PURPLE}‣${ESC}`,
+  arrowUp: "↑ ",
+  arrowDown: "↓ ",
+  prefix: `${PAD}?`,
+  pointer: `${PAD}❯`,
+  pointerSmall: `${PAD}›`,
+  ellipsis: "…",
+  tick: `${PAD}✔`,
+  descriptionSeparator: "\n\n  - ",
+  checkboxOn: "󰄲",
+  checkboxOff: "",
+  colors: true,
+};
+
+const columns = () => process.stderr.columns ?? 80;
+
+/** `text` wrapped to the terminal, each further line indented under the separator as the first is. */
+export const indented = (text: string) =>
+  Bun.wrapAnsi(text, Math.max(columns() - 5, 20)).replaceAll("\n", "\n    ");
+
+/**
+ * Renders the body of a rule for preview, preserving its YAML frontmatter.
+ * The frontmatter is shown as-is so its metadata stays visible; the body is
+ * rendered with Bun's native Markdown-to-ANSI renderer.
+ */
+export const renderMarkdown = (text: string) =>
+  Effect.gen(function* () {
+    const theme = yield* Prompt.Theme;
+    const body = ruleBodyOf(text);
+    const prefix = text.slice(0, text.length - body.length);
+    const rendered = Bun.markdown
+      .ansi(body, {
+        colors: theme.colors,
+        columns: Math.max(columns() - 4, 20),
+      })
+      .trimEnd();
+    return prefix + rendered;
+  });
+
+type Color = (theme: Prompt.Theme) => string;
+const muted: Color = (theme) => theme.mutedColor;
+const primary: Color = (theme) => theme.primaryColor;
+const accent: Color = (_theme) => COLORS.PINK;
+
+const paint = (theme: Prompt.Theme, text: string, color?: Color) =>
+  theme.colors && color !== undefined ? `${color(theme)}${text}\x1b[0m` : text;
+
+/**
+ * Prints `text` beside `symbol`, wrapped to the terminal, its further lines
+ * beside `bar`, in color when the theme has colors.
+ */
+const rail = (symbol: string, symbolColor: Color, text: string, textColor?: Color, bar = "│") =>
+  Effect.gen(function* () {
+    const theme = yield* Prompt.Theme;
+    const [first = "", ...rest] = Bun.wrapAnsi(text, Math.max(columns() - 4, 20), {
+      hard: true,
+      trim: false,
+    }).split("\n");
+    yield* Console.error(
+      [
+        `${PAD}${paint(theme, symbol, symbolColor)}  ${paint(theme, first, textColor)}`,
+        ...rest.map(
+          (line) => `${PAD}${paint(theme, bar, muted)}  ${paint(theme, line, textColor)}`,
+        ),
+      ].join("\n"),
+    );
+  });
+
+export const intro = (text: string) => rail("┌", muted, text);
+export const line = (text: string) => rail("│", muted, text);
+export const note = (text: string) => rail("│", muted, text, muted);
+export const warn = (text: string) => rail("▲", () => "\x1b[33m", text);
+export const outro = (text: string) =>
+  rail("└", (theme) => theme.successColor, text, undefined, " ");
+
+/** A choice the agent made, not the user: what it chose, and why, muted beneath. */
+export const decided = (what: string, why: string) =>
+  rail("◇", (theme) => theme.successColor, what).pipe(Effect.andThen(note(why)));
+
+/** What the agent says about something it shows the user, accented and in italics. */
+export const said = (text: string) =>
+  rail("│", muted, text, (theme) => `${theme.primaryColor}\x1b[3m`);
+
+/**
+ * Prints lines `from` to `to` of a file's `lines`, numbered from 1, on the
+ * rail: the excerpt's lines `start` to `end` marked and highlighted as a
+ * report highlights code, and the rest muted. A line too long for the
+ * terminal is cut.
+ */
+export const excerpt = (
+  lines: ReadonlyArray<string>,
+  range: {
+    readonly from: number;
+    readonly to: number;
+    readonly start: number;
+    readonly end: number;
+  },
+) =>
+  Effect.gen(function* () {
+    const theme = yield* Prompt.Theme;
+    const width = String(range.to).length;
+    const room = Math.max(columns() - width - 9, 20);
+    const cut = lines.slice(range.from - 1, range.to).map((text) => {
+      const flat = text.replaceAll("\t", "  ");
+      return flat.length > room ? `${flat.slice(0, room - 1)}…` : flat;
+    });
+    // Highlighted together, so a comment or template opened above an excerpt line colors it.
+    const colored = highlightedLines(cut.join("\n"), theme.colors);
+    const rows = cut.map((text, index) => {
+      const number = String(range.from + index).padStart(width);
+      const inside = range.from + index >= range.start && range.from + index <= range.end;
+      const marker = inside ? paint(theme, "▌", primary) : " ";
+      const body = inside
+        ? `${paint(theme, number, muted)}  ${colored[index] ?? text}`
+        : paint(theme, `${number}  ${text}`, muted);
+      return `${PAD}${paint(theme, "│", muted)}  ${marker} ${body}`;
+    });
+    yield* Console.error(rows.join("\n"));
+  });
+
+const frames = ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"];
+
+/**
+ * Runs `effect` beside a spinner and `text` on the status line, then leaves
+ * `text` on the rail with how long it took. Where the status line shows
+ * nothing, as off a terminal, only that last line is printed.
+ */
+export const spinning = <A, E, R>(text: string, effect: Effect.Effect<A, E, R>) =>
+  Effect.gen(function* () {
+    const theme = yield* Prompt.Theme;
+    const status = yield* Status;
+    let frame = 0;
+    yield* line("");
+    // The status line redraws at most every 100 ms.
+    const spinner = yield* Effect.forkChild(
+      Effect.suspend(() =>
+        status.show(
+          `${PAD}${paint(theme, frames[frame++ % frames.length] ?? "", accent)}  ${paint(theme, `${text}…`, muted)}`,
+        ),
+      ).pipe(Effect.andThen(Effect.sleep("110 millis")), Effect.forever),
+    );
+    const [took, result] = yield* Effect.timed(effect).pipe(
+      Effect.ensuring(Fiber.interrupt(spinner)),
+      clearingStatus,
+    );
+    yield* note(`${text} · ${Math.max(1, Math.round(Duration.toSeconds(took)))}s`);
+    return result;
+  });