@fenglimg/fabric-cli 2.2.0 → 2.3.0-rc.1

package/dist/chunk-PP7QVRXH.js

@@ -0,0 +1,565 @@
+#!/usr/bin/env node
+import {
+  ensureStoreProjectBinding,
+  migrateRootConfig,
+  tree
+} from "./chunk-VQKXTMWH.js";
+import {
+  resolveDevMode
+} from "./chunk-WA3DYGSY.js";
+import {
+  paint,
+  symbol
+} from "./chunk-SL77FXX7.js";
+import {
+  detectAliasLinkDrift,
+  missingRequiredStores,
+  syncStoreAliasLinks,
+  unboundAvailableStores
+} from "./chunk-7V4XMLQ2.js";
+import {
+  loadProjectConfig
+} from "./chunk-I5F5BHWI.js";
+import {
+  loadGlobalConfig,
+  resolveGlobalRoot
+} from "./chunk-FNHDQTPC.js";
+import {
+  getDoctorTranslator,
+  t
+} from "./chunk-HORSMSZL.js";
+
+// src/commands/doctor.ts
+import { confirm, isCancel } from "@clack/prompts";
+import { defineCommand } from "citty";
+import {
+  appendEventLedgerEvent,
+  runDoctorApplyLint as runDoctorFixKnowledge,
+  runDoctorFix,
+  runDoctorReport
+} from "@fenglimg/fabric-server";
+
+// src/install/backfill-unbound-project.ts
+import { detectUnboundProject } from "@fenglimg/fabric-server";
+async function backfillUnboundProject(projectRoot, globalRoot = resolveGlobalRoot()) {
+  const violation = detectUnboundProject(projectRoot);
+  if (violation === null) {
+    return null;
+  }
+  const result = await ensureStoreProjectBinding(projectRoot, violation.alias, { globalRoot });
+  return {
+    alias: violation.alias,
+    project_id: result.project_id,
+    active_project: result.active_project
+  };
+}
+
+// src/commands/doctor.ts
+import { sectionBar } from "@fenglimg/fabric-shared/theme";
+
+// src/store/doctor-checks.ts
+import { join } from "path";
+import { findStoreExecutableViolations, storeRelativePathForMount } from "@fenglimg/fabric-shared";
+function storeDoctorChecks(projectRoot, globalRoot = resolveGlobalRoot()) {
+  const diagnostics = [];
+  const global = loadGlobalConfig(globalRoot);
+  if (global === null) {
+    diagnostics.push({
+      code: "no_global_config",
+      severity: "warn",
+      message: "no global Fabric config \u2014 run `fabric install --global <url>`"
+    });
+    return diagnostics;
+  }
+  for (const missing of missingRequiredStores(projectRoot, globalRoot)) {
+    diagnostics.push({
+      code: "missing_required_store",
+      severity: "warn",
+      ref: missing.id,
+      message: `required store '${missing.id}' is not mounted; run \`fabric store mount\``
+    });
+  }
+  for (const store of unboundAvailableStores(projectRoot, globalRoot)) {
+    diagnostics.push({
+      code: "unbound_available_store",
+      severity: "info",
+      ref: store.alias,
+      message: `store '${store.alias}' is mounted but not bound to this project; run \`fabric store bind ${store.alias}\` to read its knowledge here (then \`fabric store switch-write ${store.alias}\` to write team knowledge into it)`
+    });
+  }
+  const aliasDrift = detectAliasLinkDrift(globalRoot);
+  if (aliasDrift.length > 0) {
+    diagnostics.push({
+      code: "store_alias_link_drift",
+      severity: "info",
+      ref: aliasDrift.join(", "),
+      message: `by-alias readability link(s) out of sync for ${aliasDrift.join(", ")}; run \`fabric doctor --fix\` to repair ~/.fabric/stores/by-alias/`
+    });
+  }
+  for (const store of global.stores) {
+    if (store.remote === void 0 && store.personal !== true) {
+      diagnostics.push({
+        code: "local_only_store",
+        severity: "info",
+        ref: store.alias,
+        message: `store '${store.alias}' is local-only; add a git remote to back it up`
+      });
+    }
+    const violations = findStoreExecutableViolations(join(globalRoot, storeRelativePathForMount(store)));
+    if (violations.length > 0) {
+      diagnostics.push({
+        code: "executable_in_store",
+        severity: "warn",
+        ref: store.alias,
+        message: `store '${store.alias}' contains executable/script files (${violations.slice(0, 3).join(", ")}${violations.length > 3 ? ", \u2026" : ""}) \u2014 stores are data-only; Fabric never runs them (S65)`
+      });
+    }
+  }
+  return diagnostics;
+}
+
+// src/commands/doctor.ts
+import { buildDebugBundle } from "@fenglimg/fabric-shared";
+var FIX_KNOWLEDGE_CODE_LABELS = {
+  knowledge_pending_auto_archive: "archive (git mv, pending)",
+  knowledge_index_drift: "counter bump (agents.meta)",
+  knowledge_session_hints_stale: "cache delete"
+};
+var PLAN_PREVIEW_LIMIT = 12;
+var doctorCommand = defineCommand({
+  meta: {
+    name: "doctor",
+    description: t("cli.doctor.description")
+  },
+  args: {
+    target: {
+      type: "string",
+      description: t("cli.doctor.args.target.description")
+    },
+    fix: {
+      type: "boolean",
+      description: t("cli.doctor.args.fix.description"),
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: t("cli.doctor.args.json.description"),
+      default: false
+    },
+    // v2.1.0-rc.1 P6 (S40): emit a redacted diagnostic bundle (config + store
+    // diagnostics; events excluded by default). Every string is secret-redacted
+    // so the bundle is safe to paste into a bug report. Read-only.
+    // EPIC-009: hidden flag (internal debug tool).
+    "debug-bundle": {
+      type: "boolean",
+      description: "Emit a redacted diagnostic bundle (config + store health) for bug reports",
+      default: false
+    },
+    // EPIC-009: hidden flag (CI automation).
+    yes: {
+      type: "boolean",
+      description: t("cli.doctor.args.yes.description"),
+      default: false
+    },
+    // EPIC-009: hidden flag (advanced output).
+    verbose: {
+      type: "boolean",
+      description: t("cli.doctor.args.verbose.description"),
+      default: false
+    },
+    // EPIC-009: hidden flag (preview --fix without writing).
+    "dry-run": {
+      type: "boolean",
+      description: t("cli.doctor.args.dry-run.description"),
+      default: false
+    },
+    // EPIC-009: hidden flag (strict mode for CI).
+    strict: {
+      type: "boolean",
+      description: t("cli.doctor.args.strict.description"),
+      default: false
+    }
+  },
+  async run({ args }) {
+    const workspaceRoot = process.cwd();
+    const resolution = resolveDevMode(args.target, workspaceRoot);
+    const dt = getDoctorTranslator(resolution.target);
+    const fix = args.fix === true;
+    if (args["debug-bundle"] === true) {
+      const globalRoot = resolveGlobalRoot();
+      let config = {};
+      try {
+        config = {
+          global: loadGlobalConfig(globalRoot) ?? null,
+          project: loadProjectConfig(resolution.target) ?? null
+        };
+      } catch {
+        config = {};
+      }
+      const bundle = buildDebugBundle({
+        config,
+        diagnostics: collectStoreDiagnostics(resolution.target)
+      });
+      writeStdout(JSON.stringify(bundle, null, 2));
+      return;
+    }
+    let fixKnowledgeReport = null;
+    let fixReport = null;
+    let unboundProjectFix = null;
+    let rootConfigMigration = null;
+    let report;
+    if (fix) {
+      const preReport = await runDoctorReport(resolution.target);
+      const plan = computeFixKnowledgePlan(preReport);
+      if (args["dry-run"] === true) {
+        if (plan.totalCount > 0) {
+          renderFixKnowledgePlan(plan);
+        }
+        report = preReport;
+      } else {
+        if (plan.totalCount > 0) {
+          renderFixKnowledgePlan(plan);
+          const decision = await resolveFixKnowledgeConsent({
+            yesFlag: args.yes === true,
+            envBypass: process.env.FABRIC_NONINTERACTIVE === "1",
+            plan
+          });
+          if (decision === "abort") {
+            process.exitCode = 1;
+            return;
+          }
+        }
+        rootConfigMigration = migrateRootConfig(resolution.target);
+        unboundProjectFix = await backfillUnboundProject(resolution.target);
+        fixReport = await runDoctorFix(resolution.target);
+        syncStoreAliasLinks();
+        fixKnowledgeReport = await runDoctorFixKnowledge(resolution.target);
+        report = fixKnowledgeReport?.report ?? preReport;
+      }
+    } else {
+      report = await runDoctorReport(resolution.target);
+    }
+    const storeDiagnostics = collectStoreDiagnostics(resolution.target);
+    if (args.json === true) {
+      writeStdout(
+        JSON.stringify(
+          {
+            ...fixKnowledgeReport ?? fixReport ?? report,
+            store_diagnostics: storeDiagnostics,
+            ...unboundProjectFix === null ? {} : { unbound_project_fix: unboundProjectFix },
+            ...rootConfigMigration?.migrated === true ? { root_config_migration: rootConfigMigration } : {}
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      if (fixReport != null) {
+        writeStdout(fixReport.message);
+        if (unboundProjectFix !== null) {
+          writeStdout(
+            dt("cli.doctor.unbound-project-backfilled", {
+              alias: unboundProjectFix.alias,
+              project: unboundProjectFix.active_project
+            })
+          );
+        }
+        if (rootConfigMigration?.migrated === true) {
+          writeStdout(
+            `config: migrated legacy root fabric.config.json \u2192 .fabric/fabric-config.json${rootConfigMigration.mergedKeys.length > 0 ? ` (merged: ${rootConfigMigration.mergedKeys.join(", ")})` : ""}`
+          );
+        }
+      }
+      if (fixKnowledgeReport != null) {
+        writeStdout(fixKnowledgeReport.message);
+        if (fixKnowledgeReport.aborted && fixKnowledgeReport.abort_reason !== void 0) {
+          writeStderr(fixKnowledgeReport.abort_reason);
+        }
+        renderFixKnowledgeMutations(fixKnowledgeReport, dt);
+      }
+      if (fix && args["dry-run"] === true) {
+        writeStdout(dt("cli.doctor.fix-dry-run-banner"));
+      }
+      renderHumanReport(report, dt, args.verbose === true);
+      renderStoreDiagnostics(storeDiagnostics);
+    }
+    await emitDoctorRunEventBestEffort(resolution.target, {
+      mode: fixKnowledgeReport != null ? "fix-knowledge" : "lint",
+      issues: report.fixable_errors.length + report.manual_errors.length + report.warnings.length,
+      mutations: fixKnowledgeReport != null ? fixKnowledgeReport.mutations.filter((m) => m.applied).length : void 0
+    });
+    if (fixKnowledgeReport != null) {
+      if (fixKnowledgeReport.aborted) {
+        process.exitCode = 1;
+        return;
+      }
+      if (fixKnowledgeReport.mutations.some((m) => !m.applied)) {
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (report.status === "error" || args.strict === true && (report.status === "warn" || report.warnings.length > 0)) {
+      process.exitCode = 1;
+    }
+  }
+});
+var doctor_default = doctorCommand;
+function renderHumanReport(report, dt, verbose) {
+  writeStdout(renderDoctorHeader(report));
+  renderTldrHeader(report, dt, verbose);
+  const checksBlock = renderDoctorChecks(report, verbose);
+  if (checksBlock.length > 0) {
+    writeStdout(checksBlock);
+  }
+  const opts = { verbose, dt };
+  writeIssueSection(dt("doctor.section.fixable"), report.fixable_errors, opts);
+  writeIssueSection(dt("doctor.section.manual"), report.manual_errors, opts);
+  writeIssueSection(dt("doctor.section.warnings"), report.warnings, opts);
+  renderPayloadLimits(report, dt);
+}
+function collectStoreDiagnostics(projectRoot) {
+  try {
+    return storeDoctorChecks(projectRoot);
+  } catch {
+    return [];
+  }
+}
+function renderStoreDiagnostics(diagnostics) {
+  const block = renderDoctorStoreHealth(diagnostics);
+  if (block.length === 0) {
+    return;
+  }
+  writeStdout("");
+  writeStdout(block);
+}
+function renderDoctorHeader(report) {
+  return `${sectionBar(`fabric doctor \xB7 ${report.summary.target}`)} ${renderStatus(report.status)}`;
+}
+function renderDoctorStoreHealth(diagnostics) {
+  if (diagnostics.length === 0) {
+    return "";
+  }
+  const rows = diagnostics.map((diagnostic) => {
+    const mark = diagnostic.severity === "error" ? symbol.error : diagnostic.severity === "warn" ? symbol.warn : "[info]";
+    const ref = diagnostic.ref === void 0 ? "" : ` [${diagnostic.ref}]`;
+    return { text: `${mark}${ref} ${diagnostic.message}` };
+  });
+  return `${sectionBar("Store Health")}
+${tree(rows)}`;
+}
+function renderDoctorChecks(report, verbose) {
+  const rows = report.checks.filter((check) => verbose || check.status !== "ok").map((check) => ({ text: `${renderStatus(check.status)} ${check.name}: ${check.message}` }));
+  if (rows.length === 0) {
+    return "";
+  }
+  return `${sectionBar("Checks")}
+${tree(rows)}`;
+}
+function renderPayloadLimits(report, dt) {
+  const limits = report.summary.payload_limits;
+  if (limits === void 0) {
+    return;
+  }
+  writeStdout("");
+  writeStdout(dt("doctor.section.payload-limits"));
+  writeStdout(
+    `- ${dt("doctor.payload-limits.line", {
+      warnKb: String(Math.round(limits.warn_bytes / 1024)),
+      hardKb: String(Math.round(limits.hard_bytes / 1024)),
+      source: limits.source
+    })}`
+  );
+}
+function renderFixKnowledgeMutations(fixKnowledgeReport, dt) {
+  if (fixKnowledgeReport.mutations.length === 0) {
+    return;
+  }
+  writeStdout("");
+  writeStdout(dt("doctor.section.fix-knowledge-mutations"));
+  for (const mutation of fixKnowledgeReport.mutations) {
+    const marker = mutation.applied ? symbol.ok : symbol.error;
+    const errSuffix = mutation.applied || mutation.error === void 0 ? "" : ` (${mutation.error})`;
+    writeStdout(`${marker} ${mutation.kind}: ${mutation.path} [${mutation.detail}]${errSuffix}`);
+  }
+}
+function writeIssueSection(title, issues, options) {
+  if (issues.length === 0) {
+    return;
+  }
+  writeStdout("");
+  writeStdout(title);
+  for (const issue of issues) {
+    writeStdout(`- ${issue.code}: ${issue.message}`);
+    if (issue.actionHint !== void 0 && issue.actionHint.length > 0) {
+      if (issue.audience === "maintainer" && !options.verbose) {
+        writeStdout(`  \u2192 ${options.dt("doctor.maintainer-hint-folded")}`);
+      } else {
+        writeStdout(`  \u2192 ${issue.actionHint}`);
+      }
+    }
+  }
+}
+function renderTldrHeader(report, dt, verbose) {
+  const ranked = [];
+  for (const issue of report.fixable_errors) {
+    ranked.push({ severity: "fixable", code: issue.code, message: issue.message, actionHint: issue.actionHint, audience: issue.audience });
+  }
+  for (const issue of report.manual_errors) {
+    ranked.push({ severity: "manual", code: issue.code, message: issue.message, actionHint: issue.actionHint, audience: issue.audience });
+  }
+  for (const issue of report.warnings) {
+    ranked.push({ severity: "warn", code: issue.code, message: issue.message, actionHint: issue.actionHint, audience: issue.audience });
+  }
+  if (ranked.length === 0) {
+    writeStdout(`${symbol.ok} TL;DR: all 48 checks green \u2014 nothing to fix.`);
+    return;
+  }
+  const top3 = ranked.slice(0, 3);
+  writeStdout(
+    `TL;DR (top ${top3.length} of ${ranked.length}, severity order: fixable\u2192manual\u2192warn):`
+  );
+  for (const item of top3) {
+    const marker = item.severity === "fixable" ? symbol.error : item.severity === "manual" ? symbol.error : symbol.warn;
+    const truncated = item.message.length > 140 ? `${item.message.slice(0, 137)}...` : item.message;
+    writeStdout(`  ${marker} ${item.code}: ${truncated}`);
+    if (item.actionHint !== void 0 && item.actionHint.length > 0) {
+      writeStdout(
+        item.audience === "maintainer" && !verbose ? `    \u2192 ${dt("doctor.maintainer-hint-folded")}` : `    \u2192 ${item.actionHint}`
+      );
+    }
+  }
+}
+function renderStatus(status) {
+  if (status === "ok") {
+    return symbol.ok;
+  }
+  if (status === "warn") {
+    return symbol.warn;
+  }
+  return symbol.error;
+}
+function writeStdout(message) {
+  process.stdout.write(`${message}
+`);
+}
+async function emitDoctorRunEventBestEffort(projectRoot, payload) {
+  try {
+    await appendEventLedgerEvent(projectRoot, {
+      event_type: "doctor_run",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      mode: payload.mode,
+      issues: payload.issues,
+      ...payload.mutations !== void 0 ? { mutations: payload.mutations } : {}
+    });
+  } catch {
+  }
+}
+function writeStderr(message) {
+  process.stderr.write(`${message}
+`);
+}
+function computeFixKnowledgePlan(report) {
+  const buckets = {};
+  const sources = [
+    ...report.fixable_errors,
+    ...report.warnings
+  ];
+  for (const issue of sources) {
+    if (FIX_KNOWLEDGE_CODE_LABELS[issue.code] === void 0) continue;
+    if (!Array.isArray(buckets[issue.code])) {
+      buckets[issue.code] = [];
+    }
+    buckets[issue.code].push(issue);
+  }
+  const codes = Object.keys(buckets).sort(
+    (a, b) => FIX_KNOWLEDGE_CODE_LABELS[a].localeCompare(FIX_KNOWLEDGE_CODE_LABELS[b])
+  );
+  const perCodeLines = [];
+  let totalCount = 0;
+  for (const code of codes) {
+    const items = buckets[code];
+    totalCount += items.length;
+    perCodeLines.push(`  - ${FIX_KNOWLEDGE_CODE_LABELS[code]}: ${items.length}`);
+  }
+  const previewLines = [];
+  const flattened = codes.flatMap((c) => buckets[c]);
+  for (const item of flattened.slice(0, PLAN_PREVIEW_LIMIT)) {
+    const where = item.path !== void 0 && item.path.length > 0 ? `${item.path}` : "(no path)";
+    previewLines.push(`    \u2022 ${where} \u2014 ${item.message}`);
+  }
+  if (flattened.length > PLAN_PREVIEW_LIMIT) {
+    previewLines.push(`    \u2022 ... and ${flattened.length - PLAN_PREVIEW_LIMIT} more`);
+  }
+  return { totalCount, perCodeLines, previewLines };
+}
+function renderFixKnowledgePlan(plan) {
+  writeStdout("");
+  writeStdout(`${paint.warn("fix-knowledge mutation plan")} (${plan.totalCount} total)`);
+  for (const line of plan.perCodeLines) {
+    writeStdout(line);
+  }
+  if (plan.previewLines.length > 0) {
+    writeStdout("");
+    writeStdout("  preview:");
+    for (const line of plan.previewLines) {
+      writeStdout(line);
+    }
+  }
+}
+async function resolveFixKnowledgeConsent(options) {
+  if (options.yesFlag || options.envBypass) {
+    return "proceed";
+  }
+  if (process.stdin.isTTY !== true) {
+    writeStderr(
+      "doctor --fix-knowledge: stdin is not a TTY and neither --yes nor FABRIC_NONINTERACTIVE=1 is set. Refusing to mutate."
+    );
+    return "abort";
+  }
+  const message = `About to apply ${options.plan.totalCount} mutation(s) to knowledge entries (frontmatter writes + git mv + cache deletes). Proceed?`;
+  const answer = await confirm({
+    message,
+    initialValue: false
+  });
+  if (isCancel(answer) || answer !== true) {
+    writeStderr("doctor --fix-knowledge: aborted by user.");
+    return "abort";
+  }
+  return "proceed";
+}
+function renderDoctorFilteredHelp() {
+  const lines = [];
+  lines.push(paint.ai("fabric doctor") + " \u2014 Diagnose and fix Fabric workspace issues");
+  lines.push("");
+  lines.push(`${paint.human("USAGE")}`);
+  lines.push(`  fabric doctor [OPTIONS]`);
+  lines.push("");
+  lines.push(`${paint.human("OPTIONS")}`);
+  lines.push("");
+  const exposedOptions = [
+    ["--target <path>", "Override project root (defaults to cwd)"],
+    ["--fix", "Auto-fix issues (derived-state + knowledge frontmatter/git mv)"],
+    ["--json", "Output as JSON for programmatic consumption"],
+    ["--verbose", "Show maintainer-audience action hints"]
+  ];
+  for (const [flag, desc] of exposedOptions) {
+    lines.push(`  ${paint.ai(flag)}  ${desc}`);
+  }
+  lines.push("");
+  lines.push(`${paint.human("EXAMPLES")}`);
+  lines.push(`  ${paint.ai("fabric doctor")}        # Run diagnostics`);
+  lines.push(`  ${paint.ai("fabric doctor --fix")}  # Fix derived-state + knowledge issues`);
+  lines.push("");
+  lines.push(paint.human("Run `fabric doctor` to see a full diagnostic report. Audits \u2192 `fabric audit`."));
+  writeStdout(lines.join("\n"));
+}
+
+export {
+  doctorCommand,
+  doctor_default,
+  renderDoctorHeader,
+  renderDoctorStoreHealth,
+  renderDoctorChecks,
+  renderTldrHeader,
+  renderDoctorFilteredHelp
+};

package/dist/chunk-SL77FXX7.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+// src/colors.ts
+import {
+  isColorEnabled as themeColorEnabled,
+  paint as themePaint,
+  symbol as themeSymbol
+} from "@fenglimg/fabric-shared/theme";
+import stringWidth from "string-width";
+function isColorEnabled() {
+  return themeColorEnabled();
+}
+function tokenPainter(token) {
+  return (value) => themePaint(token, value, isColorEnabled());
+}
+var paint = {
+  success: tokenPainter("success"),
+  warn: tokenPainter("warn"),
+  error: tokenPainter("error"),
+  drift: tokenPainter("drift"),
+  ai: tokenPainter("ai"),
+  human: tokenPainter("human"),
+  muted: tokenPainter("muted")
+};
+var symbol = {
+  get ok() {
+    return themeSymbol("ok", isColorEnabled());
+  },
+  get warn() {
+    return themeSymbol("warn", isColorEnabled());
+  },
+  get error() {
+    return themeSymbol("error", isColorEnabled());
+  }
+};
+function displayWidth(value) {
+  return stringWidth(value);
+}
+function padEnd(value, width, char = " ") {
+  const fill = char.length > 0 ? char : " ";
+  let result = value;
+  while (displayWidth(result) < width) {
+    result += fill;
+  }
+  return result;
+}
+
+export {
+  isColorEnabled,
+  paint,
+  symbol,
+  displayWidth,
+  padEnd
+};

package/dist/{chunk-3D7B2UAZ.js → chunk-VQKXTMWH.js}

@@ -1,18 +1,24 @@
 #!/usr/bin/env node
+import {
+  displayWidth,
+  isColorEnabled,
+  padEnd,
+  paint
+} from "./chunk-SL77FXX7.js";
 import {
   regenerateBindingsSnapshot
-} from "./chunk-PTGQAZEW.js";
+} from "./chunk-GGDVZCD6.js";
 import {
   storeBind,
   storeProjectCreate,
   storeProjectList,
   storeSetWriteRoute,
   storeSwitchWrite
-} from "./chunk-QPAW6IYT.js";
+} from "./chunk-7V4XMLQ2.js";
 import {
   loadProjectConfig,
   saveProjectConfig
-} from "./chunk-QFIVFZRH.js";
+} from "./chunk-I5F5BHWI.js";
 
 // src/install/migrate-root-config.ts
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
@@ -79,6 +85,38 @@ function migrateRootConfig(projectRoot) {
   return result;
 }
 
+// src/tui/structure.ts
+function tree(items, opts = {}) {
+  const on = isColorEnabled();
+  const indent = opts.indent ?? "  ";
+  const mid = on ? "\u251C\u2500 " : "+- ";
+  const last = on ? "\u2514\u2500 " : "`- ";
+  return items.map((it, i) => {
+    const branch = paint.muted(i === items.length - 1 ? last : mid);
+    const marker = it.marker ? `${it.marker} ` : "";
+    return `${indent}${branch}${marker}${it.text}`;
+  }).join("\n");
+}
+function grid(rows, opts = {}) {
+  const on = isColorEnabled();
+  const gap = opts.gap ?? 2;
+  const cols = rows.length > 0 ? Math.max(...rows.map((r) => r.length)) : 0;
+  const widths = [];
+  for (let c = 0; c < cols; c++) {
+    widths[c] = Math.max(0, ...rows.map((r) => displayWidth(r[c] ?? "")));
+  }
+  const sep = " ".repeat(gap);
+  const lines = rows.map(
+    (r) => r.map((cell, c) => c === r.length - 1 ? cell ?? "" : padEnd(cell ?? "", widths[c])).join(sep)
+  );
+  if (opts.rule && lines.length > 0) {
+    const total = widths.reduce((a, b) => a + b, 0) + gap * Math.max(0, cols - 1);
+    const ruleLine = paint.muted((on ? "\u2500" : "-").repeat(total));
+    lines.splice(1, 0, ruleLine);
+  }
+  return lines.join("\n");
+}
+
 // src/install/store-project-onboarding.ts
 import { execFileSync } from "child_process";
 import { randomUUID } from "crypto";
@@ -145,5 +183,7 @@ export {
   migrateRootConfig,
   suggestStoreProjectId,
   normalizeStoreProjectId,
-  ensureStoreProjectBinding
+  ensureStoreProjectBinding,
+  tree,
+  grid
 };