fix(v1-review): format CLI tables

Author: divitsheth

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "codealmanac",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "A living wiki for codebases, maintained by AI agents. Documents what the code can't say: decisions, flows, invariants, incidents, gotchas.",
   "keywords": [
     "wiki",
@@ -22,9 +22,9 @@
   },
   "type": "module",
   "bin": {
-    "codealmanac": "./dist/codealmanac.js",
-    "almanac": "./dist/codealmanac.js",
-    "alm": "./dist/codealmanac.js"
+    "codealmanac": "dist/codealmanac.js",
+    "almanac": "dist/codealmanac.js",
+    "alm": "dist/codealmanac.js"
   },
   "files": [
     "dist",

package.json

@@ -2,39 +2,40 @@ import {
   buildProviderSetupView,
   parseAgentSelection,
   type ProviderReadiness,
+  type ProviderSetupView,
 } from "../agent/provider-view.js";
 import {
   isAgentProviderId,
   readConfig,
   writeConfig,
   type AgentProviderId,
 } from "../update/config.js";
+import { formatTextTable } from "./table.js";
 
 export interface AgentsResult {
   stdout: string;
   stderr: string;
   exitCode: number;
 }
 
-export async function runAgentsList(): Promise<AgentsResult> {
-  const view = await buildProviderSetupView();
+export async function runAgentsList(opts: {
+  view?: ProviderSetupView;
+} = {}): Promise<AgentsResult> {
+  const view = opts.view ?? await buildProviderSetupView();
   const lines = ["codealmanac agents\n"];
-  for (const choice of view.choices) {
-    const selected = choice.selected ? "*" : " ";
-    const recommended = choice.recommended ? "recommended" : "";
-    const model = choice.effectiveModel ?? "provider default";
-    const detail = choice.account ?? choice.fixCommand ?? choice.detail;
-    lines.push(
-      [
-        selected,
-        choice.label.padEnd(6),
-        readinessLabel(choice.readiness).padEnd(15),
-        recommended.padEnd(11),
-        `model: ${model}`.padEnd(31),
-        detail,
-      ].join(" ").trimEnd(),
-    );
-  }
+  lines.push(
+    ...formatTextTable({
+      headers: ["DEFAULT", "AGENT", "STATUS", "RECOMMENDED", "MODEL", "DETAIL"],
+      rows: view.choices.map((choice) => [
+        choice.selected ? "*" : "",
+        choice.label,
+        readinessLabel(choice.readiness),
+        choice.recommended ? "recommended" : "",
+        choice.effectiveModel ?? "provider default",
+        choice.account ?? choice.fixCommand ?? choice.detail,
+      ]),
+    }),
+  );
   lines.push(
     "\nUse: almanac agents use <claude|codex|cursor>",
     "Set model: almanac agents model <provider> <model>",

src/commands/agents.ts

@@ -18,6 +18,7 @@ import {
   readConfigWithOrigins,
   serializeConfig,
 } from "../update/config.js";
+import { formatTextTable } from "./table.js";
 
 export interface ConfigResult {
   stdout: string;
@@ -37,11 +38,16 @@ export async function runConfigList(opts: {
   if (opts.json === true) {
     return ok(`${JSON.stringify(rows, null, 2)}\n`);
   }
-  const lines = rows.map((row) => {
-    const value = formatConfigValue(row.value);
-    return opts.showOrigin === true
-      ? `${row.key.padEnd(20)} ${value.padEnd(24)} ${row.origin}`
-      : `${row.key.padEnd(20)} ${value}`;
+  const lines = formatTextTable({
+    headers: opts.showOrigin === true
+      ? ["KEY", "VALUE", "ORIGIN"]
+      : ["KEY", "VALUE"],
+    rows: rows.map((row) => {
+      const value = formatConfigValue(row.value);
+      return opts.showOrigin === true
+        ? [row.key, value, row.origin]
+        : [row.key, value];
+    }),
   });
   return ok(`${lines.join("\n")}\n`);
 }

src/commands/config.ts

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import type { CommandResult } from "../cli/helpers.js";
 import { renderOutcome } from "../cli/outcome.js";
 import { findNearestAlmanacDir } from "../paths.js";
+import { formatTextTable } from "./table.js";
 import {
   finishRunRecord,
   markRunCancelled,
@@ -48,12 +49,7 @@ export async function runJobsList(
   if (views.length === 0) {
     return { stdout: "Jobs\n\nNo jobs found.\n", stderr: "", exitCode: 0 };
   }
-  const lines = ["Jobs", ""];
-  for (const view of views) {
-    lines.push(
-      `${view.id}  ${view.operation}  ${view.displayStatus}  ${formatMs(view.elapsedMs)}`,
-    );
-  }
+  const lines = ["Jobs", "", ...formatJobRows(views)];
   return { stdout: `${lines.join("\n")}\n`, stderr: "", exitCode: 0 };
 }
 
@@ -301,6 +297,18 @@ function formatMs(ms: number): string {
   return `${Math.round(minutes / 60)}h`;
 }
 
+function formatJobRows(views: RunView[]): string[] {
+  return formatTextTable({
+    headers: ["ID", "OPERATION", "STATUS", "ELAPSED"],
+    rows: views.map((view) => [
+      view.id,
+      view.operation,
+      view.displayStatus,
+      formatMs(view.elapsedMs),
+    ]),
+  });
+}
+
 function terminalAttachSummary(view: RunView): string {
   if (view.displayStatus !== "failed" && view.displayStatus !== "stale") {
     return "";

src/commands/jobs.ts

@@ -0,0 +1,35 @@
+export interface TextTable {
+  headers: string[];
+  rows: string[][];
+}
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+export function formatTextTable(table: TextTable): string[] {
+  if (table.headers.length === 0) return [];
+  const widths = table.headers.map((header, index) =>
+    Math.max(
+      visibleLength(header),
+      ...table.rows.map((row) => visibleLength(row[index] ?? "")),
+    ),
+  );
+  return [
+    formatTableRow(table.headers, widths),
+    ...table.rows.map((row) => formatTableRow(row, widths)),
+  ];
+}
+
+function formatTableRow(row: string[], widths: number[]): string {
+  return widths
+    .map((width, index) => padVisible(row[index] ?? "", width))
+    .join("  ")
+    .trimEnd();
+}
+
+function padVisible(value: string, width: number): string {
+  return `${value}${" ".repeat(Math.max(0, width - visibleLength(value)))}`;
+}
+
+function visibleLength(value: string): number {
+  return value.replace(ANSI_RE, "").length;
+}

src/commands/table.ts

@@ -3,6 +3,7 @@ import { ensureFreshIndex } from "../../indexer/index.js";
 import { resolveWikiRoot } from "../../indexer/resolve-wiki.js";
 import { openIndex } from "../../indexer/schema.js";
 import { indexDbPath } from "../../topics/paths.js";
+import { formatTextTable } from "../table.js";
 import type { TopicsCommandOutput, TopicsListOptions } from "./types.js";
 
 /**
@@ -57,11 +58,12 @@ export async function runTopicsList(
       };
     }
 
-    const slugWidth = rows.reduce((w, r) => Math.max(w, r.slug.length), 0);
-    const lines = rows.map((r) => {
-      const slug = r.slug.padEnd(slugWidth);
-      const count = `(${r.page_count} page${r.page_count === 1 ? "" : "s"})`;
-      return `${BLUE}${slug}${RST}  ${DIM}${count}${RST}`;
+    const lines = formatTextTable({
+      headers: ["TOPIC", "PAGES"],
+      rows: rows.map((r) => {
+        const count = `(${r.page_count} page${r.page_count === 1 ? "" : "s"})`;
+        return [`${BLUE}${r.slug}${RST}`, `${DIM}${count}${RST}`];
+      }),
     });
     return { stdout: `${lines.join("\n")}\n`, stderr: "", exitCode: 0 };
   } finally {

src/commands/topics/list.ts

@@ -594,7 +594,7 @@ export async function runCodexAppServer(
           clientInfo: {
             name: "codealmanac",
             title: "Code Almanac",
-            version: "0.2.7",
+            version: "0.2.8",
           },
           capabilities: {
             experimentalApi: true,

src/harness/providers/codex.ts

@@ -1,10 +1,65 @@
 import { describe, expect, it } from "vitest";
 
-import { runAgentsModel, runAgentsUse } from "../src/commands/agents.js";
+import { runAgentsList, runAgentsModel, runAgentsUse } from "../src/commands/agents.js";
 import { runConfigList } from "../src/commands/config.js";
 import { withTempHome } from "./helpers.js";
 
 describe("agents command", () => {
+  it("lists providers with column headers", async () => {
+    const result = await runAgentsList({
+      view: {
+        defaultProvider: "codex",
+        recommendedProvider: "codex",
+        choices: [
+          {
+            id: "codex",
+            label: "Codex",
+            selected: true,
+            recommended: true,
+            readiness: "ready",
+            ready: true,
+            installed: true,
+            authenticated: true,
+            effectiveModel: null,
+            providerDefaultModel: null,
+            configuredModel: null,
+            account: "user@example.com",
+            detail: "Logged in",
+            fixCommand: null,
+            modelChoices: [],
+          },
+          {
+            id: "cursor",
+            label: "Cursor",
+            selected: false,
+            recommended: false,
+            readiness: "missing",
+            ready: false,
+            installed: false,
+            authenticated: false,
+            effectiveModel: null,
+            providerDefaultModel: null,
+            configuredModel: null,
+            account: null,
+            detail: "missing",
+            fixCommand: "install cursor-agent",
+            modelChoices: [],
+          },
+        ],
+      },
+    });
+
+    expect(result.stdout).toContain(
+      "DEFAULT  AGENT   STATUS   RECOMMENDED  MODEL             DETAIL",
+    );
+    expect(result.stdout).toContain(
+      "*        Codex   ready    recommended  provider default  user@example.com",
+    );
+    expect(result.stdout).toContain(
+      "         Cursor  missing               provider default  install cursor-agent",
+    );
+  });
+
   it("requires an explicit model or --default", async () => {
     await withTempHome(async () => {
       const result = await runAgentsModel({ provider: "claude" });

test/agents-command.test.ts

@@ -18,6 +18,7 @@ describe("config command", () => {
       const result = await runConfigList({ showOrigin: true });
 
       expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("KEY                  VALUE    ORIGIN");
       expect(result.stdout).toContain("agent.default");
       expect(result.stdout).toContain("agent.models.claude");
       expect(result.stdout).toContain("default");