@herbertgao/pi-extensions 2026.8.12 → 2026.8.13

package/node_modules/@luxusai/pi-hindsight/extensions/tui/setup-tui-actions.ts

@@ -0,0 +1,201 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedConfig } from "../types.js";
+import {
+  buildConfigEditingFields,
+  inputDefaultForConfigEditingField,
+  parseConfigEditingFieldInput,
+  patchForConfigEditingField,
+  readConfigLayers,
+  type ConfigEditingField,
+  type FieldId,
+} from "../config/config-editing-model.js";
+import {
+  createMemoryOperations,
+  type MemoryOperationsDeps,
+} from "../operations/memory-operation-service.js";
+import { type ConfigScope, type ProjectConfigPatchInput } from "../config/config-writer.js";
+import { inputWithPrefill } from "./prefill-input.js";
+import { CANCEL } from "./setup-tui-types.js";
+
+const LOCAL_EMBED_GUIDANCE = [
+  "Local hindsight-embed guidance:",
+  "uvx hindsight-embed@latest profile create pi --port 8888",
+  "uvx hindsight-embed@latest -p pi bank create <bank-id>",
+  "uvx hindsight-embed@latest -p pi ui start",
+].join("\n");
+
+async function writeAndReload(
+  ctx: ExtensionCommandContext,
+  deps: MemoryOperationsDeps,
+  patch: ProjectConfigPatchInput,
+  scope: ConfigScope = "project",
+): Promise<void> {
+  const result = await createMemoryOperations(deps).configure(ctx.cwd, { ...patch, scope });
+  ctx.ui.notify(`Saved ${scope} config to ${result.path}; setup view reloaded.`, "info");
+}
+
+async function resetField(
+  ctx: ExtensionCommandContext,
+  deps: MemoryOperationsDeps,
+  field: ConfigEditingField,
+  scope: ConfigScope = "project",
+): Promise<void> {
+  await writeAndReload(ctx, deps, { resetDefaults: [field.resetKey] }, scope);
+}
+
+function settingPrompt(field: ConfigEditingField): string {
+  return [
+    field.label,
+    field.description,
+    `Effective: ${field.value} (${field.source ?? "default"})`,
+    `Environment: ${field.envValue ?? "not set"}`,
+    `Project: ${field.projectValue ?? "not set"}`,
+    `User: ${field.globalValue ?? "not set"}`,
+    `Default: ${field.defaultValue}`,
+    field.source === "env"
+      ? "Environment currently wins; project/user edits save for when env override is removed."
+      : "Changes save immediately.",
+  ].join("\n");
+}
+
+function scopeLabel(scope: ConfigScope): string {
+  return scope === "project" ? "Project" : "User";
+}
+
+function withScopedValues(field: ConfigEditingField, values: string[]): string[] {
+  const scoped = (field.editableScopes ?? ["project"]).flatMap((scope) =>
+    values.map((value) => `${scopeLabel(scope)}: ${value}`),
+  );
+  const resets = (field.editableScopes ?? ["project"]).flatMap((scope) => {
+    if (scope === "project" && field.projectValue !== undefined) return ["Remove project override"];
+    if (scope === "global" && field.globalValue !== undefined) return ["Remove user override"];
+    return [];
+  });
+  return [...scoped, ...resets, CANCEL];
+}
+
+function parseScopedAction(action: string): { scope: ConfigScope; value: string } | undefined {
+  if (action.startsWith("Project: "))
+    return { scope: "project", value: action.slice("Project: ".length) };
+  if (action.startsWith("User: ")) return { scope: "global", value: action.slice("User: ".length) };
+  return undefined;
+}
+
+async function chooseScope(
+  ctx: ExtensionCommandContext,
+  field: ConfigEditingField,
+): Promise<ConfigScope | undefined> {
+  const scopes = field.editableScopes ?? ["project"];
+  if (scopes.length === 1) return scopes[0];
+  const value = await ctx.ui.select(settingPrompt(field), scopes.map(scopeLabel).concat(CANCEL));
+  if (!value || value === CANCEL) return undefined;
+  return value === "User" ? "global" : "project";
+}
+
+async function handleResetAction(
+  action: string,
+  ctx: ExtensionCommandContext,
+  deps: MemoryOperationsDeps,
+  field: ConfigEditingField,
+): Promise<boolean> {
+  if (action === "Remove project override") {
+    await resetField(ctx, deps, field, "project");
+    return true;
+  }
+  if (action === "Remove user override") {
+    await resetField(ctx, deps, field, "global");
+    return true;
+  }
+  return false;
+}
+
+async function promptScopedValue(
+  ctx: ExtensionCommandContext,
+  deps: MemoryOperationsDeps,
+  field: ConfigEditingField,
+): Promise<{ scope: ConfigScope; value: string } | undefined> {
+  if (field.kind === "boolean" || field.kind === "select") {
+    const values = field.kind === "boolean" ? ["Enable", "Disable"] : (field.choices ?? []);
+    const action = await ctx.ui.select(settingPrompt(field), withScopedValues(field, values));
+    if (!action || action === CANCEL) return undefined;
+    if (await handleResetAction(action, ctx, deps, field)) return undefined;
+    return parseScopedAction(action);
+  }
+
+  const scope = await chooseScope(ctx, field);
+  if (!scope) return undefined;
+  const value = await inputWithPrefill(
+    ctx.ui,
+    settingPrompt(field),
+    inputDefaultForConfigEditingField(field.id, deps.getConfig(), deps.getProjectBankId()),
+  );
+  const parsed = parseConfigEditingFieldInput(field, value);
+  if (parsed === undefined) return undefined;
+  return { scope, value: parsed };
+}
+
+export async function handleResetFieldAction(args: {
+  ctx: ExtensionCommandContext;
+  deps: MemoryOperationsDeps;
+  config: ResolvedConfig;
+  projectBankId: string;
+  fieldId: FieldId;
+}): Promise<void> {
+  const field = buildConfigEditingFields(
+    args.config,
+    args.projectBankId,
+    readConfigLayers(args.ctx.cwd),
+  ).find((item) => item.id === args.fieldId);
+  if (field) {
+    await resetField(args.ctx, args.deps, field, field.source === "global" ? "global" : "project");
+  }
+}
+
+export async function handleFieldEdit(args: {
+  fieldId: FieldId;
+  ctx: ExtensionCommandContext;
+  deps: MemoryOperationsDeps;
+  config: ResolvedConfig;
+  projectBankId: string;
+}): Promise<void> {
+  const layers = readConfigLayers(args.ctx.cwd);
+  const field = buildConfigEditingFields(args.config, args.projectBankId, layers).find(
+    (item) => item.id === args.fieldId,
+  );
+  if (!field) return;
+
+  const scoped = await promptScopedValue(args.ctx, args.deps, field);
+  if (!scoped) return;
+  const patch = patchForConfigEditingField(field.id, scoped.value, args.config);
+  if (patch) await writeAndReload(args.ctx, args.deps, patch, scoped.scope);
+}
+
+export async function handleDeployment(
+  ctx: ExtensionCommandContext,
+  deps: MemoryOperationsDeps,
+  config: ResolvedConfig,
+): Promise<void> {
+  const value = await ctx.ui.select("Hindsight deployment", [
+    "Hindsight Cloud",
+    "Existing local/external API",
+    "Local hindsight-embed guidance",
+    CANCEL,
+  ]);
+  if (value === "Hindsight Cloud") {
+    const baseUrl = await ctx.ui.input("Hindsight Cloud base URL", config.hindsight.baseUrl);
+    if (baseUrl) await writeAndReload(ctx, deps, { baseUrl: baseUrl.trim() });
+    const envName = await ctx.ui.input("API key env var name", "HINDSIGHT_API_TOKEN");
+    if (envName) await writeAndReload(ctx, deps, { apiKeyEnvVar: envName.trim() });
+  } else if (value === "Existing local/external API") {
+    const baseUrl = await ctx.ui.input("Hindsight API base URL", config.hindsight.baseUrl);
+    if (baseUrl) await writeAndReload(ctx, deps, { baseUrl: baseUrl.trim() });
+  } else if (value === "Local hindsight-embed guidance") {
+    ctx.ui.notify(LOCAL_EMBED_GUIDANCE, "info");
+    const useDefault = await ctx.ui.select("Set API URL to http://localhost:8888?", [
+      "Yes",
+      "No",
+      CANCEL,
+    ]);
+    if (useDefault === "Yes") await writeAndReload(ctx, deps, { baseUrl: "http://localhost:8888" });
+  }
+}

package/node_modules/@luxusai/pi-hindsight/extensions/tui/setup-tui-facts.ts

@@ -0,0 +1,47 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedConfig } from "../types.js";
+import {
+  buildConfigEditingTabs,
+  readConfigLayers,
+  type ConfigEditingTab,
+} from "../config/config-editing-model.js";
+import type { MemoryOperationsDeps } from "../operations/memory-operation-service.js";
+import { listRetainReceipts } from "../lifecycle/retain-receipts.js";
+import { collectStatusHealthFacts } from "../utils/status-health.js";
+import { buildRetainReceiptStatusFacts } from "./setup-tui-render.js";
+import { RECEIPT_FACT_LIMIT, type SetupUiState } from "./setup-tui-types.js";
+
+export async function buildSetupTabs(args: {
+  ctx: ExtensionCommandContext;
+  config: ResolvedConfig;
+  projectBankId: string;
+  deps: MemoryOperationsDeps;
+  state: SetupUiState;
+}): Promise<ConfigEditingTab[]> {
+  const statusFacts = await collectStatusHealthFacts({
+    client: args.deps.getClient(),
+    config: args.config,
+    projectBankId: args.projectBankId,
+  });
+  const receiptFacts = buildRetainReceiptStatusFacts(
+    await listRetainReceipts(args.ctx.cwd, RECEIPT_FACT_LIMIT),
+  );
+  return buildConfigEditingTabs(
+    args.config,
+    args.projectBankId,
+    readConfigLayers(args.ctx.cwd),
+    [...buildInitHealthFacts(args.deps.getInitHealth?.()), ...statusFacts, ...receiptFacts],
+    { showAdvanced: Boolean(args.state.showAdvanced) },
+  );
+}
+
+export function buildInitHealthFacts(
+  initHealth: ReturnType<NonNullable<MemoryOperationsDeps["getInitHealth"]>>,
+): Array<[string, string]> {
+  if (!initHealth) return [];
+  if (initHealth.failures.length === 0) return [["Startup", `ok (${initHealth.checkedAt})`]];
+  return initHealth.failures.map((failure) => [
+    `Startup ${failure.subsystem}`,
+    `failed: ${failure.error}`,
+  ]);
+}

package/node_modules/@luxusai/pi-hindsight/extensions/tui/setup-tui-render.ts

@@ -0,0 +1,239 @@
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import type { ConfigEditingTab } from "../config/config-editing-model.js";
+import type { RetainReceipt } from "../lifecycle/retain-receipts.js";
+import { formatRetainOutcome } from "../queue/flush-presenter.js";
+import {
+  applySetupIntent,
+  currentSetupTab,
+  normalizeSetupUiState,
+  selectedSetupField,
+  selectedSetupIndex,
+  setupIntentFromInput,
+} from "./setup-flow.js";
+import {
+  HUB_ACTION_HELP,
+  RECEIPT_FACT_LIMIT,
+  type SetupActionId,
+  type SetupUiState,
+  type ThemeLike,
+} from "./setup-tui-types.js";
+
+const MIN_BODY_LINES = 30;
+const DOCS_BASE_URL = "https://luxus.github.io/pi-hindsight";
+
+const TAB_DOCS: Record<string, string> = {
+  Status: `${DOCS_BASE_URL}/guides/use-hindsight-status/`,
+  Connection: `${DOCS_BASE_URL}/start/installation/`,
+  Banks: `${DOCS_BASE_URL}/concepts/memory-banks/`,
+  Recall: `${DOCS_BASE_URL}/concepts/retain-recall-reflect/`,
+  Retain: `${DOCS_BASE_URL}/concepts/queue-durability/`,
+  Import: `${DOCS_BASE_URL}/guides/importing-sessions/`,
+  UI: `${DOCS_BASE_URL}/start/setup-tui/`,
+};
+
+function fitColumns(left: string, right: string, width: number): string {
+  if (width <= 0) return "";
+  if (width < 40) return truncateToWidth(`${left} ${right}`, width);
+  const rightWidth = Math.min(Math.max(12, visibleWidth(right)), Math.floor(width * 0.38));
+  const leftWidth = Math.max(1, width - rightWidth - 1);
+  return `${truncateToWidth(left, leftWidth)} ${truncateToWidth(right, rightWidth)}`;
+}
+
+function borderLine(
+  width: number,
+  left: string,
+  fill: string,
+  right: string,
+  theme: ThemeLike,
+): string {
+  return theme.fg("borderAccent", `${left}${fill.repeat(Math.max(0, width - 2))}${right}`);
+}
+
+function padVisibleRight(content: string, width: number): string {
+  const truncated = truncateToWidth(content, width);
+  return `${truncated}${" ".repeat(Math.max(0, width - visibleWidth(truncated)))}`;
+}
+
+function boxed(content: string, width: number, theme: ThemeLike): string {
+  if (width < 2) return truncateToWidth(content, width);
+  return `${theme.fg("borderAccent", "│")}${padVisibleRight(content, width - 2)}${theme.fg("borderAccent", "│")}`;
+}
+
+function shortDocumentId(documentId: string): string {
+  const parts = documentId.split(":");
+  if (parts[0] === "pi-explicit" && parts.length >= 3) return `${parts[0]}:${parts[2]}`;
+  return documentId;
+}
+
+function wrapWords(text: string, width: number): string[] {
+  if (width <= 0) return [""];
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines: string[] = [];
+  let current = "";
+  for (const word of words) {
+    if (!current) current = word;
+    else if (`${current} ${word}`.length <= width) current = `${current} ${word}`;
+    else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.length ? lines : [""];
+}
+
+export function buildRetainReceiptStatusFacts(receipts: RetainReceipt[]): Array<[string, string]> {
+  if (receipts.length === 0) return [["Retain receipts", "none"]];
+  return receipts.slice(0, RECEIPT_FACT_LIMIT).map((receipt, index) => {
+    const outcome = formatRetainOutcome(receipt.outcome);
+    const value = `${receipt.bankId} ${shortDocumentId(receipt.documentId)}${
+      outcome ? ` (${outcome})` : ""
+    }`;
+    return [index === 0 ? "Recent retain" : `Recent retain ${index + 1}`, value];
+  });
+}
+
+export function createSetupComponent(
+  tabs: ConfigEditingTab[],
+  theme: ThemeLike,
+  state: SetupUiState,
+  done: (action: SetupActionId | null) => void,
+): Component {
+  Object.assign(state, normalizeSetupUiState(tabs, state));
+
+  return {
+    render(width: number): string[] {
+      Object.assign(state, normalizeSetupUiState(tabs, state));
+      const tab = currentSetupTab(tabs, state) ?? tabs[0]!;
+      const lines: string[] = [];
+      const innerWidth = Math.max(0, width - 2);
+      const changedCount = tabs.reduce(
+        (count, item) => count + item.fields.filter((field) => field.changed).length,
+        0,
+      );
+      const horizontal = new DynamicBorder((s: string) => theme.fg("borderAccent", s));
+
+      lines.push(...horizontal.render(width));
+      lines.push(borderLine(width, "╭", "─", "╮", theme));
+      lines.push(
+        boxed(
+          ` ${theme.fg("accent", theme.bold("Hindsight setup"))} ${theme.fg("dim", "saved immediately after edit · changed values marked *")}`,
+          width,
+          theme,
+        ),
+      );
+      lines.push(
+        boxed(` ${theme.fg("dim", `${changedCount} changed from defaults`)}`, width, theme),
+      );
+      lines.push(boxed("", width, theme));
+
+      const tabLine = tabs
+        .map((item, index) => {
+          const dirty = item.fields.some((field) => field.changed) ? "*" : "";
+          const label = ` ${item.id}${dirty} `;
+          return index === state.tabIndex
+            ? theme.bg("selectedBg", theme.fg("accent", theme.bold(label)))
+            : theme.fg("muted", label);
+        })
+        .join(" ");
+      lines.push(boxed(tabLine, width, theme));
+      lines.push(boxed("", width, theme));
+
+      lines.push(
+        boxed(
+          theme.fg(
+            "accent",
+            theme.bold(tab.id === "Status" ? "Memory status" : `${tab.id} settings`),
+          ),
+          width,
+          theme,
+        ),
+      );
+      if (tab.facts) {
+        for (const [label, value] of tab.facts) {
+          lines.push(
+            boxed(
+              fitColumns(
+                `   ${theme.fg("muted", `${label}:`)}`,
+                theme.fg("text", value),
+                innerWidth,
+              ),
+              width,
+              theme,
+            ),
+          );
+        }
+      } else {
+        lines.push(
+          boxed(theme.fg("dim", fitColumns("Setting", "Value", innerWidth)), width, theme),
+        );
+      }
+
+      for (const [index, field] of tab.fields.entries()) {
+        const isSelected = index === selectedSetupIndex(tabs, state);
+        const marker = isSelected ? theme.fg("accent", "→") : " ";
+        const dirty = field.changed ? theme.fg("warning", "*") : " ";
+        const label = isSelected
+          ? theme.fg("accent", theme.bold(field.label))
+          : theme.fg("text", field.label);
+        const rawValue = `${field.value} [${field.source ?? "default"}]`;
+        const value = field.changed ? theme.fg("warning", rawValue) : theme.fg("text", rawValue);
+        lines.push(
+          boxed(fitColumns(`${marker}${dirty} ${label}`, value, innerWidth), width, theme),
+        );
+      }
+
+      const detailField = selectedSetupField(tabs, state);
+      if (detailField) {
+        lines.push(boxed("", width, theme));
+        lines.push(boxed(theme.fg("accent", theme.bold("Details")), width, theme));
+        const details = [
+          `Docs: ${TAB_DOCS[detailField.tab] ?? `${DOCS_BASE_URL}/reference/configuration/`}`,
+          detailField.description,
+          `Default: ${detailField.defaultValue}`,
+          ...(detailField.projectValue ? [`Project: ${detailField.projectValue}`] : []),
+          ...(detailField.globalValue ? [`User: ${detailField.globalValue}`] : []),
+          ...(detailField.envValue ? [`Env: ${detailField.envValue}`] : []),
+        ];
+        for (const detail of details) {
+          for (const line of wrapWords(detail, innerWidth - 3)) {
+            lines.push(boxed(`   ${theme.fg("dim", line)}`, width, theme));
+          }
+        }
+      } else if (tab.id === "Status") {
+        lines.push(boxed("", width, theme));
+        lines.push(boxed(theme.fg("accent", theme.bold("Docs")), width, theme));
+        for (const line of wrapWords(`Status guide: ${TAB_DOCS.Status}`, innerWidth - 3)) {
+          lines.push(boxed(`   ${theme.fg("dim", line)}`, width, theme));
+        }
+      }
+
+      while (lines.length < MIN_BODY_LINES) lines.push(boxed("", width, theme));
+
+      lines.push(
+        boxed(
+          theme.fg(
+            "dim",
+            state.showAdvanced
+              ? ` advanced · h/l tabs · j/k · enter edit · r reset ·${HUB_ACTION_HELP}`
+              : ` hub ·${HUB_ACTION_HELP}`,
+          ),
+          width,
+          theme,
+        ),
+      );
+      lines.push(borderLine(width, "╰", "─", "╯", theme));
+      lines.push(...horizontal.render(width));
+      return lines.map((line) => truncateToWidth(line, width));
+    },
+    handleInput(data: string): void {
+      const intent = setupIntentFromInput(data);
+      if (!intent) return;
+      const result = applySetupIntent(tabs, state, intent);
+      Object.assign(state, result.state);
+      if (result.kind === "action") done(result.action);
+    },
+    invalidate(): void {},
+  };
+}

package/node_modules/@luxusai/pi-hindsight/extensions/tui/setup-tui-types.ts

@@ -0,0 +1,50 @@
+import type { FieldId, TabId } from "../config/config-editing-model.js";
+
+/** Day-to-day hub actions reachable from the `/hindsight` TUI. */
+export type HubActionId =
+  | "choose-deployment"
+  | "guided-setup"
+  | "flush-queue"
+  | "set-mode"
+  | "next-opt-out"
+  | "apply-mental-models"
+  | "import-sessions"
+  | "run-doctor"
+  | "init-config"
+  | "toggle-advanced"
+  | "done";
+
+export type SetupActionId = FieldId | `reset:${FieldId}` | HubActionId;
+
+export type SetupStep = "config" | "profile" | "banks" | "review" | "done";
+
+export type SetupProfileChoice =
+  | "project-user"
+  | "project-only"
+  | "isolated-only"
+  | "user-only"
+  | "recall-only";
+
+export type SetupUiState = {
+  step?: SetupStep;
+  tabIndex: number;
+  selectedByTab: Partial<Record<TabId, number>>;
+  showAdvanced?: boolean;
+  profileChoice?: SetupProfileChoice;
+};
+
+export type ThemeLike = {
+  fg(
+    color: "accent" | "muted" | "dim" | "success" | "error" | "warning" | "borderAccent" | "text",
+    text: string,
+  ): string;
+  bg(color: "selectedBg", text: string): string;
+  bold(text: string): string;
+};
+
+export const RECEIPT_FACT_LIMIT = 3;
+export const CANCEL = "Cancel";
+
+/** Hub footer: status/setup/emergency first; import/templates/advanced demoted (agent tools own day-to-day edits). */
+export const HUB_ACTION_HELP =
+  " g guided · m mode · x next-opt-out · f flush · o doctor · n init · d deployment · i import · t templates · a advanced · q close ";