@mepuka/skygent 0.2.0

package/src/cli/derive.ts

@@ -0,0 +1,205 @@
+import { Args, Command, Options } from "@effect/cli";
+import { Clock, Effect, Option } from "effect";
+import { filterExprSignature, isEffectfulFilter } from "../domain/filter.js";
+import { defaultStoreConfig } from "../domain/defaults.js";
+import { StoreName } from "../domain/primitives.js";
+import { DerivationEngine } from "../services/derivation-engine.js";
+import { StoreManager } from "../services/store-manager.js";
+import { ViewCheckpointStore } from "../services/view-checkpoint-store.js";
+import { OutputManager } from "../services/output-manager.js";
+import { filterJsonDescription } from "./filter-help.js";
+import { parseFilterExpr } from "./filter-input.js";
+import { writeJson } from "./output.js";
+import { storeOptions } from "./store.js";
+import { CliInputError } from "./errors.js";
+import { logInfo } from "./logging.js";
+import type { FilterEvaluationMode } from "../domain/derivation.js";
+import { CliPreferences } from "./preferences.js";
+import { withExamples } from "./help.js";
+import { filterOption } from "./shared-options.js";
+
+const sourceArg = Args.text({ name: "source" }).pipe(
+  Args.withSchema(StoreName),
+  Args.withDescription("Source store name")
+);
+const targetArg = Args.text({ name: "target" }).pipe(
+  Args.withSchema(StoreName),
+  Args.withDescription("Target (derived) store name")
+);
+
+const filterJsonOption = Options.text("filter-json").pipe(
+  Options.withDescription(
+    filterJsonDescription("EventTime mode supports pure filters only.")
+  ),
+  Options.optional
+);
+
+const modeOption = Options.choice("mode", ["event-time", "derive-time"]).pipe(
+  Options.withDescription("Filter evaluation mode (default: event-time)"),
+  Options.withDefault("event-time" as const)
+);
+
+const resetFlag = Options.boolean("reset").pipe(
+  Options.withDescription("Reset the target store before deriving")
+);
+
+const yesFlag = Options.boolean("yes").pipe(
+  Options.withAlias("y"),
+  Options.withDescription("Confirm destructive operations")
+);
+
+const mapMode = (mode: "event-time" | "derive-time"): FilterEvaluationMode => {
+  return mode === "event-time" ? "EventTime" : "DeriveTime";
+};
+
+export const deriveCommand = Command.make(
+  "derive",
+  {
+    source: sourceArg,
+    target: targetArg,
+    filter: filterOption,
+    filterJson: filterJsonOption,
+    mode: modeOption,
+    reset: resetFlag,
+    yes: yesFlag
+  },
+  ({ source, target, filter, filterJson, mode, reset, yes }) =>
+    Effect.gen(function* () {
+      const startTime = yield* Clock.currentTimeMillis;
+      const engine = yield* DerivationEngine;
+      const checkpoints = yield* ViewCheckpointStore;
+      const manager = yield* StoreManager;
+      const outputManager = yield* OutputManager;
+      const preferences = yield* CliPreferences;
+
+      // Parse filter expression
+      const filterExpr = yield* parseFilterExpr(filter, filterJson);
+
+      // Validation 1: EventTime mode guard for effectful filters
+      // Defense-in-depth: CLI validates for UX (user-friendly errors),
+      // service validates for safety (in case called from other contexts)
+      const evaluationMode = mapMode(mode);
+      if (evaluationMode === "EventTime" && isEffectfulFilter(filterExpr)) {
+        return yield* CliInputError.make({
+          message:
+            "EventTime mode does not allow Trending/HasValidLinks filters. Use --mode derive-time for effectful filters.",
+          cause: { filterExpr, mode: evaluationMode }
+        });
+      }
+
+      // Validation 2: Reset requires --yes confirmation
+      if (reset && !yes) {
+        return yield* CliInputError.make({
+          message: "--reset is destructive. Re-run with --yes to confirm.",
+          cause: { reset: true, yes: false }
+        });
+      }
+
+      // Validation 3: Source and target must be different
+      if (source === target) {
+        return yield* CliInputError.make({
+          message: "Source and target stores must be different.",
+          cause: { source, target }
+        });
+      }
+
+      // Validation 4: Filter or mode change detection (only if not resetting)
+      if (!reset) {
+        const checkpointOption = yield* checkpoints.load(target, source);
+        if (Option.isSome(checkpointOption)) {
+          const checkpoint = checkpointOption.value;
+          const newFilterHash = filterExprSignature(filterExpr);
+          if (checkpoint.filterHash !== newFilterHash || checkpoint.evaluationMode !== evaluationMode) {
+            const message = [
+              "Derivation settings have changed since last derivation.",
+              `Previous filter hash: ${checkpoint.filterHash}`,
+              `New filter hash:      ${newFilterHash}`,
+              `Previous mode:        ${checkpoint.evaluationMode}`,
+              `New mode:             ${evaluationMode}`,
+              "",
+              "This would result in inconsistent data. Options:",
+              "  1. Use --reset --yes to discard existing data and start fresh",
+              "  2. Use the same filter expression as before",
+              "  3. Derive into a new target store"
+            ].join("\n");
+
+            return yield* CliInputError.make({
+              message,
+              cause: {
+                oldHash: checkpoint.filterHash,
+                newHash: newFilterHash,
+                oldMode: checkpoint.evaluationMode,
+                newMode: evaluationMode
+              }
+            });
+          }
+        }
+      }
+
+      // Load store references
+      const sourceRef = yield* storeOptions.loadStoreRef(source);
+      const targetOption = yield* manager.getStore(target);
+      const targetRef = yield* Option.match(targetOption, {
+        onNone: () =>
+          manager.createStore(target, defaultStoreConfig).pipe(
+            Effect.tap(() => logInfo("Auto-created target store", { target }))
+          ),
+        onSome: Effect.succeed
+      });
+
+      // Execute derivation
+      const result = yield* engine.derive(sourceRef, targetRef, filterExpr, {
+        mode: evaluationMode,
+        reset
+      });
+
+      const materialized = yield* outputManager.materializeStore(targetRef);
+      if (materialized.filters.length > 0) {
+        yield* logInfo("Materialized filter outputs", {
+          store: targetRef.name,
+          filters: materialized.filters.map((spec) => spec.name)
+        });
+      }
+
+      // Calculate duration and percentage
+      const endTime = yield* Clock.currentTimeMillis;
+      const duration = (endTime - startTime) / 1000;
+      const percentage = result.eventsProcessed > 0 
+        ? ((result.eventsMatched / result.eventsProcessed) * 100).toFixed(1)
+        : "0.0";
+      
+      // Human-friendly summary (always shown)
+      yield* logInfo(
+        `Derived ${result.eventsMatched} posts (${percentage}%) from ${sourceRef.name} → ${targetRef.name} in ${duration.toFixed(1)}s`
+      );
+
+      // Output result with context
+      if (preferences.compact) {
+        yield* writeJson({
+          source: sourceRef.name,
+          target: targetRef.name,
+          mode: evaluationMode,
+          ...result
+        });
+        return;
+      }
+
+      yield* writeJson({
+        source: sourceRef.name,
+        target: targetRef.name,
+        mode: evaluationMode,
+        result
+      });
+    })
+).pipe(
+  Command.withDescription(
+    withExamples(
+      "Derive a target store from a source store by applying a filter",
+      [
+        "skygent derive source-store derived-store --filter 'hashtag:#ai'",
+        "skygent derive source-store derived-store --filter 'hashtag:#ai' --mode derive-time"
+      ],
+      ["Tip: use --reset --yes if you need to rebuild with a new filter or mode."]
+    )
+  )
+);

package/src/cli/doc/annotation.ts

@@ -0,0 +1,36 @@
+import * as Ansi from "@effect/printer-ansi/Ansi";
+
+export type Annotation =
+  | "label" | "value" | "dim" | "accent" | "muted" | "connector"
+  | "error" | "warning" | "metric" | "badge"
+  | "storeName" | "storeName:root" | "storeName:derived"
+  | "status:ready" | "status:stale" | "status:unknown" | "status:source"
+  | "sync:current" | "sync:stale" | "sync:empty" | "sync:unknown"
+  | "author" | "hashtag" | "link" | "timestamp" | "embed" | "cycle";
+
+export const toAnsi = (a: Annotation): Ansi.Ansi => {
+  switch (a) {
+    case "label": case "dim": case "muted": case "connector": return Ansi.blackBright;
+    case "value": return Ansi.white;
+    case "storeName": return Ansi.cyan;
+    case "storeName:root": return Ansi.combine(Ansi.cyan, Ansi.bold);
+    case "storeName:derived": return Ansi.magenta;
+    case "status:ready": return Ansi.green;
+    case "status:stale": return Ansi.red;
+    case "status:unknown": return Ansi.yellow;
+    case "status:source": return Ansi.cyan;
+    case "sync:current": return Ansi.green;
+    case "sync:stale": case "sync:unknown": return Ansi.yellow;
+    case "sync:empty": return Ansi.blackBright;
+    case "accent": return Ansi.cyan;
+    case "error": return Ansi.red;
+    case "warning": case "cycle": return Ansi.yellow;
+    case "metric": return Ansi.whiteBright;
+    case "badge": return Ansi.bold;
+    case "author": return Ansi.combine(Ansi.cyan, Ansi.bold);
+    case "hashtag": return Ansi.blue;
+    case "link": return Ansi.underlined;
+    case "timestamp": return Ansi.blackBright;
+    case "embed": return Ansi.magenta;
+  }
+};

package/src/cli/doc/filter.ts

@@ -0,0 +1,69 @@
+import * as Doc from "@effect/printer/Doc";
+import type { Annotation } from "./annotation.js";
+import { ann, field } from "./primitives.js";
+import type { FilterCondition, FilterDescription } from "../../domain/filter-describe.js";
+
+type SDoc = Doc.Doc<Annotation>;
+
+const titleCase = (value: string) => value.replace(/\b\w/g, (char) => char.toUpperCase());
+
+const conditionLine = (condition: FilterCondition): string => {
+  const prefix = condition.negated ? "Must NOT " : "Must ";
+  switch (condition.type) {
+    case "Hashtag":       return `${prefix}have hashtag: ${condition.value}`;
+    case "Author":        return `${prefix}be from: ${condition.value}`;
+    case "AuthorIn":      return `${prefix}be from one of: ${condition.value}`;
+    case "HashtagIn":     return `${prefix}have hashtag in: ${condition.value}`;
+    case "Contains":      return `${prefix}contain: ${condition.value}`;
+    case "IsReply":       return `${prefix}be a reply`;
+    case "IsQuote":       return `${prefix}be a quote`;
+    case "IsRepost":      return `${prefix}be a repost`;
+    case "IsOriginal":    return `${prefix}be an original post`;
+    case "Engagement":    return `${prefix}meet engagement: ${condition.value}`;
+    case "HasImages":     return `${prefix}include images`;
+    case "HasVideo":      return `${prefix}include video`;
+    case "HasLinks":      return `${prefix}include links`;
+    case "HasMedia":      return `${prefix}include media`;
+    case "HasEmbed":      return `${prefix}include embeds`;
+    case "Language":      return `${prefix}be in: ${condition.value}`;
+    case "Regex":         return `${prefix}match regex: ${condition.value}`;
+    case "DateRange":     return `${prefix}be in date range: ${condition.value}`;
+    case "HasValidLinks": return `${prefix}have valid links`;
+    case "Trending":      return `${prefix}match trending: ${condition.value}`;
+    default:              return `${prefix}match ${condition.type}: ${condition.value}`;
+  }
+};
+
+export const renderFilterDescriptionDoc = (description: FilterDescription): SDoc => {
+  const lines: SDoc[] = [];
+  lines.push(ann("value", Doc.text(description.summary)));
+
+  if (description.conditions.length > 0) {
+    lines.push(Doc.empty);
+    lines.push(ann("label", Doc.text("Breakdown:")));
+    for (const condition of description.conditions) {
+      lines.push(Doc.hsep([ann("dim", Doc.text("-")), Doc.text(conditionLine(condition))]));
+    }
+  }
+
+  lines.push(Doc.empty);
+  lines.push(ann("label", Doc.text("Mode compatibility:")));
+  lines.push(Doc.hsep([
+    ann("dim", Doc.text("-")),
+    Doc.text("EventTime:"),
+    ann(description.eventTimeCompatible ? "status:ready" : "status:stale",
+      Doc.text(description.eventTimeCompatible ? "YES" : "NO"))
+  ]));
+  lines.push(Doc.hsep([
+    ann("dim", Doc.text("-")),
+    Doc.text("DeriveTime:"),
+    ann("status:ready", Doc.text("YES"))
+  ]));
+
+  lines.push(Doc.empty);
+  lines.push(field("Effectful", description.effectful ? "Yes" : "No"));
+  lines.push(field("Estimated cost", titleCase(description.estimatedCost)));
+  lines.push(field("Complexity", `${titleCase(description.complexity)} (${description.conditionCount} conditions, ${description.negationCount} negations)`));
+
+  return Doc.vsep(lines);
+};

package/src/cli/doc/index.ts

@@ -0,0 +1,9 @@
+export type { Annotation } from "./annotation.js";
+export { toAnsi } from "./annotation.js";
+export { renderPlain, renderAnsi } from "./render.js";
+export { ann, label, value, field, badge, connector, metric } from "./primitives.js";
+export type { RenderContext, TreeConfig } from "./tree.js";
+export { renderTree } from "./tree.js";
+export { renderPostCompact, renderPostCard } from "./post.js";
+export { renderThread } from "./thread.js";
+export { renderFilterDescriptionDoc } from "./filter.js";

package/src/cli/doc/post.ts

@@ -0,0 +1,155 @@
+import * as Doc from "@effect/printer/Doc";
+import type { Annotation } from "./annotation.js";
+import { ann, metric } from "./primitives.js";
+import { collapseWhitespace, normalizeWhitespace, truncate } from "../../domain/format.js";
+import type { Post } from "../../domain/post.js";
+import type { PostEmbed } from "../../domain/bsky.js";
+
+type SDoc = Doc.Doc<Annotation>;
+
+const renderEmbedSummary = (embed: PostEmbed): SDoc => {
+  switch (embed._tag) {
+    case "Images":    return Doc.text(`[Images: ${embed.images.length}]`);
+    case "External":  return Doc.text(`[Link: ${truncate(embed.title || embed.uri, 40)}]`);
+    case "Video":     return Doc.text("[Video]");
+    case "Record":
+      return Doc.text(
+        embed.record._tag === "RecordView"
+          ? `[Quote: @${embed.record.author.handle}]`
+          : "[Quote]"
+      );
+    case "RecordWithMedia":
+      return Doc.text(
+        embed.record._tag === "RecordView"
+          ? `[Quote: @${embed.record.author.handle} + media]`
+          : "[Quote + media]"
+      );
+    default:          return Doc.text("[Embed]");
+  }
+};
+
+const wrapText = (text: string, maxWidth?: number): ReadonlyArray<string> => {
+  const normalized = normalizeWhitespace(text);
+  if (!maxWidth || maxWidth <= 0) {
+    const lines = normalized.split("\n");
+    return lines.length > 0 ? lines : [normalized];
+  }
+  const lines: string[] = [];
+  const paragraphs = normalized.split("\n");
+  for (const paragraph of paragraphs) {
+    if (paragraph.length === 0) {
+      lines.push("");
+      continue;
+    }
+    const words = paragraph.split(" ");
+    let current = "";
+    const flushCurrent = () => {
+      if (current.length > 0) {
+        lines.push(current);
+        current = "";
+      }
+    };
+    for (let word of words) {
+      while (word.length > maxWidth && maxWidth > 1) {
+        const chunk = word.slice(0, maxWidth - 1);
+        flushCurrent();
+        lines.push(`${chunk}-`);
+        word = word.slice(maxWidth - 1);
+      }
+      if (current.length === 0) {
+        current = word;
+        continue;
+      }
+      if (current.length + 1 + word.length <= maxWidth) {
+        current = `${current} ${word}`;
+      } else {
+        lines.push(current);
+        current = word;
+      }
+    }
+    flushCurrent();
+  }
+  return lines.length > 0 ? lines : [normalized];
+};
+
+export const renderPostCompact = (post: Post): SDoc => {
+  const text = post.text ?? "";
+  const parts: SDoc[] = [
+    ann("author", Doc.text(`@${post.author}`)),
+    ann("dim", Doc.text("·")),
+    ann("timestamp", Doc.text(post.createdAt.toISOString().slice(0, 10))),
+    Doc.text(truncate(collapseWhitespace(text), 60))
+  ];
+  if (post.metrics) {
+    const m = post.metrics;
+    if (m.likeCount != null && m.likeCount > 0) parts.push(metric("♥", m.likeCount));
+    if (m.repostCount != null && m.repostCount > 0) parts.push(metric("↻", m.repostCount));
+    if (m.replyCount != null && m.replyCount > 0) parts.push(metric("💬", m.replyCount));
+  }
+  return Doc.hsep(parts);
+};
+
+/** Returns an array of Doc lines suitable for multi-line tree rendering.
+ *  When used standalone, combine with `Doc.vsep(renderPostCard(post))`. */
+export const renderPostCard = (post: Post): ReadonlyArray<SDoc> => {
+  const text = post.text ?? "";
+  const lines: SDoc[] = [];
+
+  lines.push(Doc.hsep([
+    ann("author", Doc.text(`@${post.author}`)),
+    ann("dim", Doc.text("·")),
+    ann("timestamp", Doc.text(post.createdAt.toISOString()))
+  ]));
+
+  const paragraphs = normalizeWhitespace(text).split("\n");
+  lines.push(Doc.vsep(paragraphs.map((paragraph) => Doc.reflow(paragraph))));
+
+  if (post.embed) lines.push(ann("embed", renderEmbedSummary(post.embed)));
+
+  if (post.metrics) {
+    const parts: SDoc[] = [];
+    const m = post.metrics;
+    if (m.likeCount != null && m.likeCount > 0) parts.push(metric("♥", m.likeCount));
+    if (m.repostCount != null && m.repostCount > 0) parts.push(metric("↻", m.repostCount));
+    if (m.replyCount != null && m.replyCount > 0) parts.push(metric("💬", m.replyCount));
+    if (m.quoteCount != null && m.quoteCount > 0) parts.push(metric("❝", m.quoteCount));
+    if (parts.length > 0) lines.push(Doc.hsep(parts));
+  }
+
+  return lines;
+};
+
+export const renderPostCardLines = (
+  post: Post,
+  options?: { lineWidth?: number }
+): ReadonlyArray<SDoc> => {
+  const text = post.text ?? "";
+  const lines: SDoc[] = [];
+
+  lines.push(Doc.hsep([
+    ann("author", Doc.text(`@${post.author}`)),
+    ann("dim", Doc.text("·")),
+    ann("timestamp", Doc.text(post.createdAt.toISOString()))
+  ]));
+
+  const textLines = wrapText(text, options?.lineWidth);
+  for (const line of textLines) {
+    lines.push(Doc.text(line));
+  }
+
+  if (post.embed) {
+    lines.push(ann("embed", renderEmbedSummary(post.embed)));
+  }
+
+  if (post.metrics) {
+    const parts: SDoc[] = [];
+    const m = post.metrics;
+    if (m.likeCount != null && m.likeCount > 0) parts.push(metric("♥", m.likeCount));
+    if (m.repostCount != null && m.repostCount > 0) parts.push(metric("↻", m.repostCount));
+    if (m.replyCount != null && m.replyCount > 0) parts.push(metric("💬", m.replyCount));
+    if (m.quoteCount != null && m.quoteCount > 0) parts.push(metric("❝", m.quoteCount));
+    if (parts.length > 0) lines.push(Doc.hsep(parts));
+  }
+
+  return lines;
+};

package/src/cli/doc/primitives.ts

@@ -0,0 +1,25 @@
+import * as Doc from "@effect/printer/Doc";
+import { pipe } from "effect/Function";
+import type { Annotation } from "./annotation.js";
+
+type SDoc = Doc.Doc<Annotation>;
+
+export const ann = (a: Annotation, doc: SDoc): SDoc => Doc.annotate(doc, a);
+
+export const label = (text: string): SDoc => ann("label", Doc.text(text));
+export const value = (text: string): SDoc => ann("value", Doc.text(text));
+
+export const field = (key: string, val: string, keyWidth?: number): SDoc =>
+  Doc.hsep([
+    keyWidth ? pipe(label(key + ":"), Doc.fillBreak(keyWidth)) : label(key + ":"),
+    value(val)
+  ]);
+
+export const badge = (text: string, annotation: Annotation): SDoc =>
+  ann(annotation, Doc.text(`[${text}]`));
+
+export const connector = (text: string): SDoc =>
+  ann("connector", Doc.text(text));
+
+export const metric = (icon: string, count: number): SDoc =>
+  ann("metric", Doc.text(`${icon} ${new Intl.NumberFormat("en-US").format(count)}`));

package/src/cli/doc/render.ts

@@ -0,0 +1,18 @@
+import * as Doc from "@effect/printer/Doc";
+import * as AnsiDoc from "@effect/printer-ansi/AnsiDoc";
+import type { Annotation } from "./annotation.js";
+import { toAnsi } from "./annotation.js";
+
+export const renderPlain = (doc: Doc.Doc<Annotation>, width?: number): string => {
+  const plain = Doc.unAnnotate(doc);
+  return width
+    ? Doc.render(plain, { style: "pretty", options: { lineWidth: width } })
+    : Doc.render(plain, { style: "pretty" });
+};
+
+export const renderAnsi = (doc: Doc.Doc<Annotation>, width?: number): string => {
+  const ansiDoc = Doc.reAnnotate(doc, toAnsi);
+  return width
+    ? AnsiDoc.render(ansiDoc, { style: "pretty", options: { lineWidth: width } })
+    : AnsiDoc.render(ansiDoc, { style: "pretty" });
+};

package/src/cli/doc/table.ts

@@ -0,0 +1,114 @@
+import * as Doc from "@effect/printer/Doc";
+import { pipe } from "effect/Function";
+import type { Annotation } from "./annotation.js";
+import { renderAnsi, renderPlain } from "./render.js";
+import { ann, label, value } from "./primitives.js";
+import { displayWidth } from "../../domain/text-width.js";
+
+export type SDoc = Doc.Doc<Annotation>;
+
+export interface TableColumn {
+  readonly header: string;
+  readonly width?: number;
+}
+
+export interface TableConfig {
+  readonly columns: ReadonlyArray<TableColumn>;
+  readonly rows: ReadonlyArray<ReadonlyArray<string>>;
+  readonly trimEnd?: boolean;
+}
+
+export const calculateColumnWidths = (
+  columns: ReadonlyArray<TableColumn>,
+  rows: ReadonlyArray<ReadonlyArray<string>>
+): ReadonlyArray<number> => {
+  return columns.map((column, index) => {
+    const contentWidths = rows.map((row) => displayWidth(row[index] ?? ""));
+    return Math.max(displayWidth(column.header), ...contentWidths);
+  });
+};
+
+export const buildCell = (
+  content: string,
+  width: number,
+  style?: "label" | "value" | "dim"
+): SDoc => {
+  const doc = style === "label" 
+    ? label(content) 
+    : style === "dim" 
+      ? ann("dim", Doc.text(content))
+      : value(content);
+  
+  return pipe(doc, Doc.fillBreak(width));
+};
+
+export const buildRow = (
+  cells: ReadonlyArray<string>,
+  widths: ReadonlyArray<number>,
+  styles?: ReadonlyArray<"label" | "value" | "dim" | undefined>,
+  trimEnd = false
+): SDoc => {
+  const cellDocs = cells.map((cell, i) => {
+    const style = styles?.[i];
+    return buildCell(cell, widths[i] ?? 0, style);
+  });
+  
+  const row = Doc.hsep(cellDocs);
+  
+  if (trimEnd) {
+    return pipe(
+      row,
+      Doc.render({ style: "pretty" }),
+      (str: string) => str.trimEnd(),
+      Doc.text
+    );
+  }
+  
+  return row;
+};
+
+export const buildTableDoc = (config: TableConfig): SDoc => {
+  const { columns, rows, trimEnd = false } = config;
+  
+  const widths = calculateColumnWidths(columns, rows);
+  
+  const headerCells = columns.map((col, i) => 
+    buildCell(col.header, widths[i] ?? 0, "label")
+  );
+  const header = Doc.hsep(headerCells);
+  
+  const separatorCells = widths.map((w) => ann("dim", Doc.text("-".repeat(w))));
+  const separator = Doc.hsep(separatorCells);
+  
+  const dataRows = rows.map((row) => {
+    const dataCells = row.map((cell, i) => buildCell(cell, widths[i] ?? 0, "value"));
+    const dataRow = Doc.hsep(dataCells);
+    
+    if (trimEnd) {
+      return pipe(
+        dataRow,
+        Doc.render({ style: "pretty" }),
+        (str: string) => str.trimEnd(),
+        Doc.text
+      );
+    }
+    
+    return dataRow;
+  });
+  
+  return Doc.vsep([header, separator, ...dataRows]);
+};
+
+export const renderTable = (config: TableConfig, ansi = false): string => {
+  const doc = buildTableDoc(config);
+  return ansi ? renderAnsi(doc) : renderPlain(doc);
+};
+
+export const renderTableLegacy = (
+  headers: ReadonlyArray<string>,
+  rows: ReadonlyArray<ReadonlyArray<string>>,
+  trimEnd = true
+): string => {
+  const columns = headers.map((header) => ({ header }));
+  return renderTable({ columns, rows, trimEnd });
+};

package/src/cli/doc/thread.ts

@@ -0,0 +1,46 @@
+import * as Doc from "@effect/printer/Doc";
+import type { Annotation } from "./annotation.js";
+import { renderTree } from "./tree.js";
+import { renderPostCompact, renderPostCardLines } from "./post.js";
+import type { Post } from "../../domain/post.js";
+
+export const renderThread = (
+  posts: ReadonlyArray<Post>,
+  options?: { compact?: boolean; lineWidth?: number }
+): Doc.Doc<Annotation> => {
+  const byUri = new Map(posts.map((p) => [String(p.uri), p]));
+  const childMap = new Map<string, Post[]>();
+  const roots: Post[] = [];
+
+  for (const post of posts) {
+    const parentUri = post.reply?.parent.uri ? String(post.reply.parent.uri) : undefined;
+    if (parentUri && byUri.has(parentUri)) {
+      const siblings = childMap.get(parentUri) ?? [];
+      siblings.push(post);
+      childMap.set(parentUri, siblings);
+    } else {
+      roots.push(post);
+    }
+  }
+
+  const sortPosts = (arr: Post[]) =>
+    arr.sort((a, b) =>
+      a.createdAt.getTime() - b.createdAt.getTime() || a.uri.localeCompare(b.uri)
+    );
+
+  sortPosts(roots);
+  for (const children of childMap.values()) sortPosts(children);
+
+  const cardOptions =
+    options?.lineWidth === undefined ? undefined : { lineWidth: options.lineWidth };
+  const render = options?.compact
+    ? renderPostCompact
+    : (post: Post) => renderPostCardLines(post, cardOptions);
+
+  return renderTree<Post, undefined>(roots, {
+    children: (post) =>
+      (childMap.get(String(post.uri)) ?? []).map((p) => ({ node: p, edge: undefined })),
+    renderNode: (post) => render(post),
+    key: (post) => String(post.uri),
+  });
+};