@treeseed/cli 0.4.8 → 0.4.10

package/dist/cli/handlers/config.js

@@ -1,54 +1,124 @@
-import readline from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
-import { guidedResult } from "./utils.js";
+import {
+  applyTreeseedSafeRepairs,
+  collectTreeseedConfigContext,
+  findNearestTreeseedRoot
+} from "@treeseed/sdk/workflow-support";
+import { fail, guidedResult } from "./utils.js";
+import { buildCliConfigPages, runCliConfigEditor } from "./config-ui.js";
 import { createWorkflowSdk, renderWorkflowNextSteps, workflowErrorResult } from "./workflow.js";
+function normalizeConfigScopes(value) {
+  const requested = Array.isArray(value) ? value.map(String) : typeof value === "string" ? [value] : ["all"];
+  if (requested.includes("all")) {
+    return ["local", "staging", "prod"];
+  }
+  return ["local", "staging", "prod"].filter((scope) => requested.includes(scope));
+}
+function formatPrintEnvReports(payload) {
+  const lines = [];
+  for (const report of payload.reports ?? []) {
+    lines.push(`Resolved environment values for ${report.scope}`);
+    lines.push(payload.secretsRevealed ? "Secrets are shown." : "Secret values are masked.");
+    for (const entry of report.environment?.entries ?? []) {
+      lines.push(`${entry.id}=${entry.displayValue} (${entry.source})`);
+    }
+    lines.push("");
+    lines.push(`Provider connection checks for ${report.scope}`);
+    for (const check of report.provider?.checks ?? []) {
+      const status = check.ready ? "ready" : check.skipped ? "skipped" : "failed";
+      lines.push(`${check.provider}: ${status} - ${check.detail}`);
+    }
+    lines.push("");
+  }
+  return lines.filter((line, index, all) => !(line === "" && all[index - 1] === ""));
+}
+function renderConfigResult(commandName, result) {
+  const payload = result.payload;
+  const toolHealth = payload.toolHealth;
+  const summary = payload.mode === "print-env-only" ? "Treeseed config environment report completed." : payload.mode === "rotate-machine-key" ? "Treeseed machine key rotated successfully." : "Treeseed config completed successfully.";
+  return guidedResult({
+    command: commandName,
+    summary,
+    facts: [
+      { label: "Mode", value: payload.mode },
+      { label: "Scopes", value: Array.isArray(payload.scopes) ? payload.scopes.join(", ") : "(none)" },
+      { label: "Sync", value: payload.sync ?? "all" },
+      { label: "Safe repairs", value: Array.isArray(payload.repairs) ? payload.repairs.length : 0 },
+      { label: "Machine config", value: payload.configPath },
+      { label: "Machine key", value: payload.keyPath },
+      { label: "GitHub CLI", value: toolHealth?.githubCli?.available ? "ready" : "missing" },
+      { label: "gh act", value: toolHealth?.ghActExtension?.available ? "ready" : "missing" },
+      { label: "Docker", value: toolHealth?.dockerDaemon?.available ? "ready" : "missing" },
+      { label: "ACT verify", value: toolHealth?.actVerificationReady ? "ready" : "not ready" }
+    ],
+    nextSteps: renderWorkflowNextSteps(result),
+    report: payload
+  });
+}
 const handleConfig = async (invocation, context) => {
-  const rl = readline.createInterface({ input, output });
   try {
     const workflow = createWorkflowSdk(context, {
       write: context.outputFormat === "json" ? (() => {
-      }) : context.write,
-      prompt: async (message) => {
-        if (!process.stdin.isTTY || !process.stdout.isTTY) {
-          return "";
-        }
-        return rl.question(message);
-      }
+      }) : context.write
     });
+    const scopes = normalizeConfigScopes(invocation.args.environment);
+    const sync = invocation.args.sync;
+    const interactive = context.outputFormat !== "json" && process.stdin.isTTY && process.stdout.isTTY;
+    if (interactive && invocation.args.printEnvOnly !== true && invocation.args.rotateMachineKey !== true) {
+      const tenantRoot = findNearestTreeseedRoot(context.cwd) ?? context.cwd;
+      if (!tenantRoot) {
+        return fail("Treeseed config requires a Treeseed project. Run the command from inside a tenant or initialize one first.");
+      }
+      applyTreeseedSafeRepairs(tenantRoot);
+      const configContext = collectTreeseedConfigContext({
+        tenantRoot,
+        scopes,
+        env: context.env
+      });
+      const editorResult = await runCliConfigEditor(configContext, {
+        initialViewMode: invocation.args.full === true ? "full" : "startup"
+      });
+      if (editorResult === null) {
+        return fail("Treeseed config canceled.");
+      }
+      const updates = buildCliConfigPages(configContext, "all", editorResult.overrides, "full").map((page) => ({
+        scope: page.scope,
+        entryId: page.entry.id,
+        value: page.finalValue,
+        reused: !(page.key in editorResult.overrides)
+      }));
+      const result2 = await workflow.config({
+        environment: scopes,
+        sync,
+        printEnv: invocation.args.printEnv === true,
+        showSecrets: invocation.args.showSecrets === true,
+        nonInteractive: true,
+        updates
+      });
+      return renderConfigResult(invocation.commandName || "config", result2);
+    }
     const result = await workflow.config({
       environment: invocation.args.environment,
-      sync: invocation.args.sync,
+      sync,
       printEnv: invocation.args.printEnv === true,
       printEnvOnly: invocation.args.printEnvOnly === true,
       showSecrets: invocation.args.showSecrets === true,
       rotateMachineKey: invocation.args.rotateMachineKey === true,
       nonInteractive: context.outputFormat === "json"
     });
-    const payload = result.payload;
-    const toolHealth = payload.toolHealth;
-    const summary = payload.mode === "print-env-only" ? "Treeseed config environment report completed." : payload.mode === "rotate-machine-key" ? "Treeseed machine key rotated successfully." : "Treeseed config completed successfully.";
-    return guidedResult({
-      command: invocation.commandName || "config",
-      summary,
-      facts: [
-        { label: "Mode", value: payload.mode },
-        { label: "Scopes", value: Array.isArray(payload.scopes) ? payload.scopes.join(", ") : "(none)" },
-        { label: "Sync", value: payload.sync ?? "all" },
-        { label: "Safe repairs", value: Array.isArray(payload.repairs) ? payload.repairs.length : 0 },
-        { label: "Machine config", value: payload.configPath },
-        { label: "Machine key", value: payload.keyPath },
-        { label: "GitHub CLI", value: toolHealth?.githubCli?.available ? "ready" : "missing" },
-        { label: "gh act", value: toolHealth?.ghActExtension?.available ? "ready" : "missing" },
-        { label: "Docker", value: toolHealth?.dockerDaemon?.available ? "ready" : "missing" },
-        { label: "ACT verify", value: toolHealth?.actVerificationReady ? "ready" : "not ready" }
-      ],
-      nextSteps: renderWorkflowNextSteps(result),
-      report: payload
-    });
+    if (context.outputFormat !== "json" && result.payload.mode === "print-env-only") {
+      return {
+        exitCode: 0,
+        stdout: formatPrintEnvReports(result.payload),
+        report: {
+          command: invocation.commandName || "config",
+          ok: true,
+          ...result.payload
+        }
+      };
+    }
+    return renderConfigResult(invocation.commandName || "config", result);
   } catch (error) {
     return workflowErrorResult(error);
-  } finally {
-    rl.close();
   }
 };
 export {

package/dist/cli/handlers/export.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedCommandHandler } from '../types.js';
+export declare const handleExport: TreeseedCommandHandler;

package/dist/cli/handlers/export.js

@@ -0,0 +1,28 @@
+import { guidedResult } from "./utils.js";
+import { createWorkflowSdk, workflowErrorResult } from "./workflow.js";
+const handleExport = async (invocation, context) => {
+  try {
+    const directory = typeof invocation.positionals[0] === "string" && invocation.positionals[0].trim().length > 0 ? invocation.positionals[0] : void 0;
+    const result = await createWorkflowSdk(context).export({ directory });
+    const exported = result.payload;
+    return guidedResult({
+      command: "export",
+      summary: "Treeseed export completed successfully.",
+      facts: [
+        { label: "Directory", value: exported.directory },
+        { label: "Output", value: exported.outputPath },
+        { label: "Branch", value: exported.branch },
+        { label: "Timestamp", value: exported.timestamp },
+        { label: "Files", value: exported.summary?.totalFiles },
+        { label: "Tokens", value: exported.summary?.totalTokens },
+        { label: "Bundled paths", value: Array.isArray(exported.includedBundlePaths) ? exported.includedBundlePaths.length : 0 }
+      ],
+      report: exported
+    });
+  } catch (error) {
+    return workflowErrorResult(error);
+  }
+};
+export {
+  handleExport
+};

package/dist/cli/help-ui.d.ts

@@ -0,0 +1,3 @@
+import type { TreeseedCommandContext } from './operations-types.js';
+export declare function renderTreeseedHelpInk(commandName: string | null | undefined, context?: Pick<TreeseedCommandContext, 'outputFormat' | 'interactiveUi'>): Promise<number | null>;
+export declare function shouldUseInkHelp(context: Pick<TreeseedCommandContext, 'outputFormat' | 'interactiveUi'>): boolean;

package/dist/cli/help-ui.js

@@ -0,0 +1,490 @@
+import { Box, render, Text, useApp, useInput, useWindowSize } from "ink";
+import React from "react";
+import {
+  AppFrame,
+  clampOffset,
+  computeViewportLayout,
+  ensureVisible,
+  findClickableRegion,
+  popNavigationEntry,
+  pushNavigationEntry,
+  routeWheelDeltaToScrollRegion,
+  scrollOffsetByDelta,
+  scrollOffsetByPage,
+  SecondaryButton,
+  SidebarList,
+  StatusBar,
+  truncateLine,
+  wrapText
+} from "./ui/framework.js";
+import { useTerminalMouse } from "./ui/mouse.js";
+import { buildTreeseedHelpView } from "./help.js";
+function sidebarTopIndicatorNeeded(totalSize, viewportSize, offset) {
+  return totalSize > 0 && offset > 0;
+}
+function sidebarItemRect(layout, offset, index, totalSections) {
+  const itemTop = layout.topBarHeight + 1 + 1 + (sidebarTopIndicatorNeeded(totalSections, Math.max(1, layout.bodyHeight - 4), offset) ? 1 : 0);
+  return {
+    x: 1,
+    y: itemTop + index,
+    width: layout.sidebarWidth - 2,
+    height: 1
+  };
+}
+function detailRowRect(layout, rowIndex) {
+  return {
+    x: layout.sidebarWidth + 2,
+    y: layout.topBarHeight + 1 + rowIndex,
+    width: layout.contentWidth - 2,
+    height: 1
+  };
+}
+function toneForEntry(entry) {
+  switch (entry.accent) {
+    case "flag":
+      return { color: "magenta", bold: true };
+    case "argument":
+      return { color: entry.required ? "yellow" : "cyan", bold: true };
+    case "example":
+      return { color: "green", bold: true };
+    case "alias":
+    case "related":
+      return { color: "blue", bold: true };
+    case "command":
+    default:
+      return { color: "cyan", bold: true };
+  }
+}
+function styledWrap(text, width, style = {}, targetCommand) {
+  const wrapped = wrapText(text, width);
+  return wrapped.map((line, index) => ({
+    text: line,
+    ...style,
+    targetCommand: index === 0 ? targetCommand : void 0
+  }));
+}
+function buildSectionRows(section, width) {
+  const rows = [];
+  for (const entry of section.entries ?? []) {
+    rows.push(...styledWrap(entry.label, width, toneForEntry(entry), entry.targetCommand));
+    if (entry.summary) {
+      rows.push(...styledWrap(`  ${entry.summary}`, width, { color: "gray" }));
+    }
+    rows.push({ text: "", color: "gray" });
+  }
+  for (const line of section.lines ?? []) {
+    rows.push(...styledWrap(line, width, { color: "white" }));
+  }
+  while (rows.length > 0 && !rows.at(-1)?.text) {
+    rows.pop();
+  }
+  return rows.length > 0 ? rows : [{ text: "(empty)", color: "gray" }];
+}
+function computeHelpViewportLayout(rows, columns) {
+  const layout = computeViewportLayout(rows, columns, { topBarHeight: 4, footerHeight: 2 });
+  const sidebarWidth = Math.max(22, Math.min(30, Math.floor(layout.columns * 0.27)));
+  const contentWidth = Math.max(38, layout.columns - sidebarWidth - 1);
+  return {
+    ...layout,
+    sidebarWidth,
+    contentWidth
+  };
+}
+function detailViewport(rows, height, offset) {
+  const viewportSize = Math.max(1, height - 3);
+  const safeOffset = clampOffset(offset, rows.length, viewportSize);
+  return {
+    rows: rows.slice(safeOffset, safeOffset + viewportSize),
+    offset: safeOffset,
+    viewportSize,
+    totalSize: rows.length
+  };
+}
+function buttonLabel(label) {
+  return `[ ${label} ]`;
+}
+function buttonRect(label, x, y) {
+  return { x, y, width: buttonLabel(label).length, height: 1 };
+}
+function navigableRowIndices(rows) {
+  return rows.flatMap((row, index) => row.targetCommand ? [index] : []);
+}
+function nearestNavigableRow(rows, fromIndex = 0) {
+  const indices = navigableRowIndices(rows);
+  if (indices.length === 0) {
+    return -1;
+  }
+  const match = indices.find((index) => index >= fromIndex);
+  return match ?? indices[0] ?? -1;
+}
+function nextNavigableRow(rows, currentIndex, direction) {
+  const indices = navigableRowIndices(rows);
+  if (indices.length === 0) {
+    return -1;
+  }
+  if (currentIndex < 0) {
+    return direction > 0 ? indices[0] ?? -1 : indices.at(-1) ?? -1;
+  }
+  if (direction > 0) {
+    const next2 = indices.find((index) => index > currentIndex);
+    return next2 ?? currentIndex;
+  }
+  const reversed = [...indices].reverse();
+  const next = reversed.find((index) => index < currentIndex);
+  return next ?? currentIndex;
+}
+function HelpDetailPanel(props) {
+  const contentRows = Math.max(1, props.height - 3);
+  return React.createElement(
+    Box,
+    { flexDirection: "column", width: props.width, height: props.height, borderStyle: "round", borderColor: props.focused ? "cyan" : "gray", overflow: "hidden" },
+    React.createElement(Text, { color: "yellow", bold: true }, truncateLine(props.title, props.width - 2)),
+    ...Array.from({ length: contentRows }, (_, index) => {
+      const row = props.rows[index] ?? { text: "" };
+      const selected = index === props.selectedRowIndex && Boolean(row.targetCommand);
+      return React.createElement(
+        Text,
+        {
+          key: `detail-${index}`,
+          color: selected ? "black" : row.color ?? "white",
+          backgroundColor: selected ? "cyan" : void 0,
+          bold: row.bold
+        },
+        truncateLine(row.text, props.width - 2)
+      );
+    }),
+    React.createElement(
+      Text,
+      { color: "gray" },
+      truncateLine(
+        `${props.scrollState.offset > 0 ? "\u2191" : " "} ${props.scrollState.offset + props.scrollState.viewportSize < props.scrollState.totalSize ? "\u2193" : " "} lines ${props.scrollState.totalSize === 0 ? "0-0" : `${Math.min(props.scrollState.totalSize, props.scrollState.offset + 1)}-${Math.min(props.scrollState.totalSize, props.scrollState.offset + props.scrollState.viewportSize)}`} of ${props.scrollState.totalSize}`,
+        props.width - 2
+      )
+    )
+  );
+}
+async function renderTreeseedHelpInk(commandName, context = {}) {
+  if (!canRenderInkHelp({ outputFormat: context.outputFormat ?? "human", interactiveUi: context.interactiveUi })) {
+    return null;
+  }
+  return await new Promise((resolveSession) => {
+    let finished = false;
+    let instance;
+    const finish = (exitCode) => {
+      if (finished) return;
+      finished = true;
+      instance?.unmount();
+      resolveSession(exitCode);
+    };
+    function App() {
+      const { exit } = useApp();
+      const windowSize = useWindowSize();
+      const layout = computeHelpViewportLayout(windowSize?.rows ?? 24, windowSize?.columns ?? 100);
+      const [focusArea, setFocusArea] = React.useState("sidebar");
+      const [backHistory, setBackHistory] = React.useState([]);
+      const [forwardHistory, setForwardHistory] = React.useState([]);
+      const [currentCommand, setCurrentCommand] = React.useState(commandName ?? null);
+      const [sectionIndex, setSectionIndex] = React.useState(0);
+      const [sidebarOffset, setSidebarOffset] = React.useState(0);
+      const [detailOffset, setDetailOffset] = React.useState(0);
+      const [contentRowIndex, setContentRowIndex] = React.useState(-1);
+      const view = React.useMemo(() => buildTreeseedHelpView(currentCommand), [currentCommand]);
+      const safeSectionIndex = view.sections.length === 0 ? 0 : Math.min(sectionIndex, view.sections.length - 1);
+      const sidebarViewportSize = Math.max(1, layout.bodyHeight - 4);
+      const safeSidebarOffset = clampOffset(ensureVisible(safeSectionIndex, sidebarOffset, sidebarViewportSize), view.sections.length, sidebarViewportSize);
+      const visibleSections = view.sections.slice(safeSidebarOffset, safeSidebarOffset + sidebarViewportSize);
+      const selectedSection = view.sections[safeSectionIndex] ?? { id: "empty", title: "Help", lines: ["No help content is available."] };
+      const detailRows = buildSectionRows(selectedSection, layout.contentWidth - 2);
+      const safeContentRowIndex = contentRowIndex >= 0 && contentRowIndex < detailRows.length ? contentRowIndex : nearestNavigableRow(detailRows);
+      const detailView = detailViewport(detailRows, layout.bodyHeight, detailOffset);
+      const visibleSelectedRowIndex = safeContentRowIndex >= detailView.offset && safeContentRowIndex < detailView.offset + detailView.viewportSize ? safeContentRowIndex - detailView.offset : -1;
+      React.useEffect(() => {
+        if (safeSidebarOffset !== sidebarOffset) {
+          setSidebarOffset(safeSidebarOffset);
+        }
+      }, [safeSidebarOffset, sidebarOffset]);
+      React.useEffect(() => {
+        if (detailView.offset !== detailOffset) {
+          setDetailOffset(detailView.offset);
+        }
+      }, [detailView.offset, detailOffset]);
+      React.useEffect(() => {
+        setSectionIndex(0);
+        setSidebarOffset(0);
+        setDetailOffset(0);
+        setContentRowIndex(-1);
+        setFocusArea("sidebar");
+      }, [currentCommand]);
+      React.useEffect(() => {
+        setDetailOffset(0);
+        setContentRowIndex(nearestNavigableRow(detailRows));
+      }, [selectedSection.id]);
+      const navigateToCommand = React.useCallback((targetCommand) => {
+        if (!targetCommand) {
+          return;
+        }
+        setBackHistory((current) => pushNavigationEntry(current, currentCommand));
+        setForwardHistory([]);
+        setCurrentCommand(targetCommand);
+      }, [currentCommand]);
+      const goBack = React.useCallback(() => {
+        if (backHistory.length > 0) {
+          const { nextStack, popped } = popNavigationEntry(backHistory);
+          setBackHistory(nextStack);
+          setForwardHistory((current) => pushNavigationEntry(current, currentCommand));
+          setCurrentCommand(popped);
+          return;
+        }
+        if (currentCommand !== null) {
+          setForwardHistory((current) => pushNavigationEntry(current, currentCommand));
+          setCurrentCommand(null);
+          return;
+        }
+        exit();
+        finish(view.exitCode);
+      }, [backHistory, currentCommand, exit, view.exitCode]);
+      const goForward = React.useCallback(() => {
+        if (forwardHistory.length === 0) {
+          return;
+        }
+        const { nextStack, popped } = popNavigationEntry(forwardHistory);
+        setForwardHistory(nextStack);
+        setBackHistory((current) => pushNavigationEntry(current, currentCommand));
+        setCurrentCommand(popped);
+      }, [currentCommand, forwardHistory]);
+      const backLabel = currentCommand !== null ? "Back to Help" : backHistory.length > 0 ? "Back" : "Exit Help";
+      const backWidth = buttonLabel(backLabel).length;
+      const backX = Math.max(0, layout.columns - backWidth);
+      const topActionY = 3;
+      const backButtonRect = buttonRect(backLabel, backX, topActionY);
+      const sidebarRect = { x: 0, y: layout.topBarHeight, width: layout.sidebarWidth, height: layout.bodyHeight };
+      const detailRect = { x: layout.sidebarWidth + 1, y: layout.topBarHeight, width: layout.contentWidth, height: layout.bodyHeight };
+      const clickRegions = [
+        {
+          id: "top-action-back",
+          rect: backButtonRect,
+          onClick: goBack
+        },
+        ...visibleSections.map((section, index) => ({
+          id: `section:${section.id}`,
+          rect: sidebarItemRect(layout, safeSidebarOffset, index, view.sections.length),
+          onClick: () => {
+            setSectionIndex(safeSidebarOffset + index);
+            setFocusArea("sidebar");
+          }
+        })),
+        ...detailView.rows.flatMap((row, index) => row.targetCommand ? [{
+          id: `detail:${row.targetCommand}:${index}`,
+          rect: detailRowRect(layout, index),
+          onClick: () => {
+            setFocusArea("content");
+            setContentRowIndex(detailView.offset + index);
+            navigateToCommand(row.targetCommand);
+          }
+        }] : [])
+      ];
+      const scrollRegions = [
+        {
+          id: "help-sidebar",
+          rect: sidebarRect,
+          state: {
+            offset: safeSidebarOffset,
+            viewportSize: sidebarViewportSize,
+            totalSize: view.sections.length
+          },
+          onScroll: (offset) => {
+            setSidebarOffset(offset);
+            setSectionIndex(offset);
+          },
+          onFocus: () => setFocusArea("sidebar")
+        },
+        {
+          id: "help-detail",
+          rect: detailRect,
+          state: {
+            offset: detailView.offset,
+            viewportSize: detailView.viewportSize,
+            totalSize: detailView.totalSize
+          },
+          onScroll: (offset) => setDetailOffset(offset),
+          onFocus: () => setFocusArea("content")
+        }
+      ];
+      useTerminalMouse((event) => {
+        if (event.button === "scroll-up" || event.button === "scroll-down") {
+          const delta = event.button === "scroll-up" ? -1 : 1;
+          routeWheelDeltaToScrollRegion(scrollRegions, event.x, event.y, delta);
+          return;
+        }
+        if (event.action !== "release" || event.button !== "left") {
+          return;
+        }
+        findClickableRegion(clickRegions, event.x, event.y)?.onClick();
+      });
+      useInput((input, key) => {
+        if (key.ctrl && input === "c") {
+          exit();
+          finish(view.exitCode);
+          return;
+        }
+        if (key.escape || input === "q") {
+          exit();
+          finish(view.exitCode);
+          return;
+        }
+        if (input === "b" || input === "[" || key.backspace) {
+          goBack();
+          return;
+        }
+        if (input === "f" || input === "]") {
+          goForward();
+          return;
+        }
+        if (key.tab) {
+          setFocusArea((current) => current === "sidebar" ? "content" : "sidebar");
+          return;
+        }
+        if (focusArea === "sidebar") {
+          if (key.upArrow || input === "k") {
+            setSectionIndex((current) => Math.max(0, current - 1));
+            return;
+          }
+          if (key.downArrow || input === "j") {
+            setSectionIndex((current) => Math.min(Math.max(0, view.sections.length - 1), current + 1));
+            return;
+          }
+          if (key.pageUp) {
+            setSidebarOffset((current) => scrollOffsetByPage({ offset: current, viewportSize: sidebarViewportSize, totalSize: view.sections.length }, -1));
+            setSectionIndex((current) => Math.max(0, current - sidebarViewportSize));
+            return;
+          }
+          if (key.pageDown) {
+            setSidebarOffset((current) => scrollOffsetByPage({ offset: current, viewportSize: sidebarViewportSize, totalSize: view.sections.length }, 1));
+            setSectionIndex((current) => Math.min(Math.max(0, view.sections.length - 1), current + sidebarViewportSize));
+            return;
+          }
+        }
+        if (focusArea === "content") {
+          if (key.upArrow) {
+            const next = nextNavigableRow(detailRows, safeContentRowIndex, -1);
+            if (next >= 0) {
+              setContentRowIndex(next);
+              setDetailOffset((current) => ensureVisible(next, current, detailView.viewportSize));
+            } else {
+              setDetailOffset((current) => scrollOffsetByDelta({ offset: current, viewportSize: detailView.viewportSize, totalSize: detailView.totalSize }, -1));
+            }
+            return;
+          }
+          if (key.downArrow) {
+            const next = nextNavigableRow(detailRows, safeContentRowIndex, 1);
+            if (next >= 0) {
+              setContentRowIndex(next);
+              setDetailOffset((current) => ensureVisible(next, current, detailView.viewportSize));
+            } else {
+              setDetailOffset((current) => scrollOffsetByDelta({ offset: current, viewportSize: detailView.viewportSize, totalSize: detailView.totalSize }, 1));
+            }
+            return;
+          }
+          if (input === "k") {
+            setDetailOffset((current) => scrollOffsetByDelta({ offset: current, viewportSize: detailView.viewportSize, totalSize: detailView.totalSize }, -1));
+            return;
+          }
+          if (input === "j") {
+            setDetailOffset((current) => scrollOffsetByDelta({ offset: current, viewportSize: detailView.viewportSize, totalSize: detailView.totalSize }, 1));
+            return;
+          }
+          if (key.pageUp) {
+            setDetailOffset((current) => scrollOffsetByPage({ offset: current, viewportSize: detailView.viewportSize, totalSize: detailView.totalSize }, -1));
+            return;
+          }
+          if (key.pageDown) {
+            setDetailOffset((current) => scrollOffsetByPage({ offset: current, viewportSize: detailView.viewportSize, totalSize: detailView.totalSize }, 1));
+            return;
+          }
+          if (key.return && safeContentRowIndex >= 0) {
+            const targetCommand = detailRows[safeContentRowIndex]?.targetCommand;
+            if (targetCommand) {
+              navigateToCommand(targetCommand);
+            }
+            return;
+          }
+        }
+      });
+      const topBar = React.createElement(
+        Box,
+        { flexDirection: "column", width: layout.columns, overflow: "hidden" },
+        React.createElement(Text, { backgroundColor: "cyan", color: "black", bold: true }, truncateLine(` ${view.title} `, layout.columns)),
+        React.createElement(Text, { color: "white" }, truncateLine(view.subtitle ?? "", layout.columns)),
+        React.createElement(Text, { color: "gray" }, truncateLine(view.badge ?? "", layout.columns)),
+        React.createElement(
+          Box,
+          { width: layout.columns, justifyContent: "space-between" },
+          React.createElement(Text, { color: "gray" }, truncateLine(currentCommand === null ? "Main Help" : `Viewing ${currentCommand}`, Math.max(1, layout.columns - backButtonRect.width - 2))),
+          React.createElement(SecondaryButton, {
+            label: backLabel,
+            focused: false,
+            width: backButtonRect.width
+          })
+        )
+      );
+      const body = React.createElement(
+        Box,
+        { width: layout.columns, height: layout.bodyHeight, overflow: "hidden" },
+        React.createElement(SidebarList, {
+          width: layout.sidebarWidth,
+          height: layout.bodyHeight,
+          title: `${view.sidebarTitle}${focusArea === "sidebar" ? " \u2022 active" : ""}`,
+          focused: focusArea === "sidebar",
+          scrollState: {
+            offset: safeSidebarOffset,
+            viewportSize: sidebarViewportSize,
+            totalSize: view.sections.length
+          },
+          items: visibleSections.map((section, index) => ({
+            id: section.id,
+            label: section.title,
+            active: safeSidebarOffset + index === safeSectionIndex,
+            tone: "normal"
+          }))
+        }),
+        React.createElement(Text, null, " "),
+        React.createElement(HelpDetailPanel, {
+          width: layout.contentWidth,
+          height: layout.bodyHeight,
+          title: `${selectedSection.title}${focusArea === "content" ? " \u2022 active" : ""}`,
+          focused: focusArea === "content",
+          rows: detailView.rows,
+          selectedRowIndex: visibleSelectedRowIndex,
+          scrollState: {
+            offset: detailView.offset,
+            viewportSize: detailView.viewportSize,
+            totalSize: detailView.totalSize
+          }
+        })
+      );
+      const footer = React.createElement(StatusBar, {
+        width: layout.columns,
+        accent: focusArea === "content",
+        primary: "Wheel or PgUp/PgDn scroll the hovered or focused panel. Enter opens the selected command. b/[ goes back. f/] goes forward. q exits.",
+        secondary: `${view.statusSecondary}  Focus: ${focusArea}.`
+      });
+      return React.createElement(AppFrame, { layout, topBar, body, footer });
+    }
+    instance = render(React.createElement(App), { exitOnCtrlC: false });
+  });
+}
+function shouldUseInkHelp(context) {
+  return Boolean(context.interactiveUi !== false && canRenderInkHelp({ outputFormat: context.outputFormat ?? "human" }));
+}
+function canRenderInkHelp(context) {
+  return Boolean(
+    context.interactiveUi !== false && context.outputFormat !== "json" && !isNonHumanInteractiveEnvironment() && process.stdin.isTTY && process.stdout.isTTY
+  );
+}
+function isNonHumanInteractiveEnvironment() {
+  return process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true" || process.env.ACT === "true" || process.env.TREESEED_VERIFY_DRIVER === "act";
+}
+export {
+  renderTreeseedHelpInk,
+  shouldUseInkHelp
+};