@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/@luxusai/pi-hindsight/extensions/tui/prefill-input.ts

@@ -0,0 +1,105 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder, keyHint } from "@earendil-works/pi-coding-agent";
+import {
+  decodeKittyPrintable,
+  getKeybindings,
+  Input,
+  type Component,
+} from "@earendil-works/pi-tui";
+
+/**
+ * True when the keystroke would insert text into Pi's Input
+ * (printable or Kitty CSI-u printable). Used for select-all prefill replace.
+ */
+export function isPrefillReplacingInput(data: string): boolean {
+  if (!data) return false;
+  if (decodeKittyPrintable(data) !== undefined) return true;
+  for (let i = 0; i < data.length; i += 1) {
+    const code = data.charCodeAt(i);
+    if (code < 32 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) return false;
+  }
+  return true;
+}
+
+type PrefillTheme = {
+  fg: (name: string, text: string) => string;
+};
+
+/**
+ * Input dialog with a visible prefill. First printable keystroke replaces the
+ * whole prefill (select-all UX). Enter keeps the current value; Esc cancels.
+ * Empty prefill falls through to stock `ui.input`.
+ */
+export async function inputWithPrefill(
+  ui: Pick<ExtensionUIContext, "input" | "custom">,
+  title: string,
+  prefill: string,
+): Promise<string | undefined> {
+  const initial = prefill;
+  // No prefill, or host without custom UI (tests / RPC stubs): stock input.
+  if (!initial || typeof ui.custom !== "function") return ui.input(title, initial);
+
+  return ui.custom<string | undefined>((tui, theme, _keybindings, done) =>
+    createPrefillInputComponent({
+      title,
+      prefill: initial,
+      theme: theme as PrefillTheme,
+      done,
+      requestRender: () => tui.requestRender(),
+    }),
+  );
+}
+
+export function createPrefillInputComponent(args: {
+  title: string;
+  prefill: string;
+  theme: PrefillTheme;
+  done: (value: string | undefined) => void;
+  requestRender: () => void;
+}): Component & { handleInput(data: string): void; dispose?(): void } {
+  const input = new Input();
+  input.setValue(args.prefill);
+  // Move cursor to end so the prefill reads as an editable default.
+  input.handleInput("\x05");
+  let pristine = true;
+  const border = new DynamicBorder((s) => args.theme.fg("borderAccent", s));
+
+  return {
+    render(width: number): string[] {
+      return [
+        ...border.render(width),
+        "",
+        args.theme.fg("accent", args.title),
+        "",
+        ...input.render(width),
+        "",
+        `${keyHint("tui.select.confirm", "submit")}  ${keyHint("tui.select.cancel", "cancel")}`,
+        "",
+        ...border.render(width),
+      ];
+    },
+    invalidate() {
+      input.invalidate();
+      border.invalidate();
+    },
+    handleInput(data: string) {
+      const kb = getKeybindings();
+      if (kb.matches(data, "tui.select.confirm") || data === "\n") {
+        args.done(input.getValue());
+        return;
+      }
+      if (kb.matches(data, "tui.select.cancel")) {
+        args.done(undefined);
+        return;
+      }
+      if (pristine && isPrefillReplacingInput(data)) {
+        input.setValue("");
+        pristine = false;
+      } else if (pristine) {
+        pristine = false;
+      }
+      input.handleInput(data);
+      args.requestRender();
+    },
+  };
+}

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

@@ -0,0 +1,189 @@
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import type { ConfigEditingField, ConfigEditingTab } from "../config/config-editing-model.js";
+import type {
+  SetupActionId,
+  SetupProfileChoice,
+  SetupStep,
+  SetupUiState,
+} from "./setup-tui-types.js";
+
+export type SetupIntent =
+  | { type: "close" }
+  | { type: "chooseDeployment" }
+  | { type: "guidedSetup" }
+  | { type: "flushQueue" }
+  | { type: "setMode" }
+  | { type: "nextOptOut" }
+  | { type: "applyMentalModels" }
+  | { type: "importSessions" }
+  | { type: "runDoctor" }
+  | { type: "initConfig" }
+  | { type: "toggleAdvanced" }
+  | { type: "moveTab"; delta: number }
+  | { type: "moveSelection"; delta: number }
+  | { type: "resetSelectedField" }
+  | { type: "editSelectedField" }
+  | { type: "startGuidedSetup" }
+  | { type: "chooseProfile"; profile: SetupProfileChoice }
+  | { type: "back" }
+  | { type: "finish" };
+
+export type SetupResult =
+  | { kind: "state"; state: SetupUiState }
+  | { kind: "action"; action: SetupActionId | null; state: SetupUiState };
+
+function defaultStep(step: SetupStep | undefined): SetupStep {
+  return step ?? "config";
+}
+
+function normalizedTabIndex(tabs: ConfigEditingTab[], tabIndex: number): number {
+  if (tabs.length === 0) return 0;
+  return Math.min(Math.max(0, tabIndex), tabs.length - 1);
+}
+
+function selectedIndexForTab(tab: ConfigEditingTab | undefined, state: SetupUiState): number {
+  if (!tab) return 0;
+  return Math.min(state.selectedByTab[tab.id] ?? 0, Math.max(0, tab.fields.length - 1));
+}
+
+function withState(state: SetupUiState): SetupResult {
+  return { kind: "state", state };
+}
+
+function withAction(action: SetupActionId | null, state: SetupUiState): SetupResult {
+  return { kind: "action", action, state };
+}
+
+function nextStep(step: SetupStep): SetupStep {
+  if (step === "profile") return "banks";
+  if (step === "banks") return "review";
+  if (step === "review") return "done";
+  return step;
+}
+
+function previousStep(step: SetupStep): SetupStep {
+  if (step === "profile") return "config";
+  if (step === "banks") return "profile";
+  if (step === "review") return "banks";
+  if (step === "done") return "review";
+  return step;
+}
+
+export function normalizeSetupUiState(tabs: ConfigEditingTab[], state: SetupUiState): SetupUiState {
+  const tabIndex = normalizedTabIndex(tabs, state.tabIndex);
+  const tab = tabs[tabIndex];
+  const selectedByTab = { ...state.selectedByTab };
+  if (tab) selectedByTab[tab.id] = selectedIndexForTab(tab, { ...state, tabIndex, selectedByTab });
+  return {
+    ...state,
+    step: defaultStep(state.step),
+    tabIndex,
+    selectedByTab,
+  };
+}
+
+export function currentSetupTab(
+  tabs: ConfigEditingTab[],
+  state: SetupUiState,
+): ConfigEditingTab | undefined {
+  return tabs[normalizedTabIndex(tabs, state.tabIndex)];
+}
+
+export function selectedSetupIndex(tabs: ConfigEditingTab[], state: SetupUiState): number {
+  return selectedIndexForTab(currentSetupTab(tabs, state), normalizeSetupUiState(tabs, state));
+}
+
+export function selectedSetupField(
+  tabs: ConfigEditingTab[],
+  state: SetupUiState,
+): ConfigEditingField | undefined {
+  const normalized = normalizeSetupUiState(tabs, state);
+  return currentSetupTab(tabs, normalized)?.fields[selectedSetupIndex(tabs, normalized)];
+}
+
+export function setupIntentFromInput(data: string): SetupIntent | undefined {
+  if (matchesKey(data, Key.escape) || data === "q") return { type: "close" };
+  if (data === "d") return { type: "chooseDeployment" };
+  if (data === "g") return { type: "guidedSetup" };
+  if (data === "f") return { type: "flushQueue" };
+  if (data === "m") return { type: "setMode" };
+  if (data === "x") return { type: "nextOptOut" };
+  if (data === "t") return { type: "applyMentalModels" };
+  if (data === "i") return { type: "importSessions" };
+  if (data === "o") return { type: "runDoctor" };
+  if (data === "n") return { type: "initConfig" };
+  if (matchesKey(data, Key.left) || data === "h" || data === "<") {
+    return { type: "moveTab", delta: -1 };
+  }
+  if (matchesKey(data, Key.right) || data === "l" || data === ">") {
+    return { type: "moveTab", delta: 1 };
+  }
+  if (matchesKey(data, Key.up) || data === "k") return { type: "moveSelection", delta: -1 };
+  if (matchesKey(data, Key.down) || data === "j") return { type: "moveSelection", delta: 1 };
+  if (data === "r") return { type: "resetSelectedField" };
+  if (data === "a") return { type: "toggleAdvanced" };
+  if (matchesKey(data, Key.enter)) return { type: "editSelectedField" };
+  return undefined;
+}
+
+export function applySetupIntent(
+  tabs: ConfigEditingTab[],
+  state: SetupUiState,
+  intent: SetupIntent,
+): SetupResult {
+  const normalized = normalizeSetupUiState(tabs, state);
+  if (intent.type === "close") return withAction(null, normalized);
+  if (intent.type === "chooseDeployment") return withAction("choose-deployment", normalized);
+  if (intent.type === "guidedSetup") return withAction("guided-setup", normalized);
+  if (intent.type === "flushQueue") return withAction("flush-queue", normalized);
+  if (intent.type === "setMode") return withAction("set-mode", normalized);
+  if (intent.type === "nextOptOut") return withAction("next-opt-out", normalized);
+  if (intent.type === "applyMentalModels") return withAction("apply-mental-models", normalized);
+  if (intent.type === "importSessions") return withAction("import-sessions", normalized);
+  if (intent.type === "runDoctor") return withAction("run-doctor", normalized);
+  if (intent.type === "initConfig") return withAction("init-config", normalized);
+  if (intent.type === "toggleAdvanced") return withAction("toggle-advanced", normalized);
+  if (intent.type === "finish") return withAction("done", { ...normalized, step: "done" });
+  if (intent.type === "startGuidedSetup") return withState({ ...normalized, step: "profile" });
+  if (intent.type === "chooseProfile") {
+    return withState({
+      ...normalized,
+      profileChoice: intent.profile,
+      step: nextStep("profile"),
+    });
+  }
+  if (intent.type === "back") {
+    return withState({ ...normalized, step: previousStep(defaultStep(normalized.step)) });
+  }
+
+  const tab = currentSetupTab(tabs, normalized);
+  if (!tab || tabs.length === 0) return withState(normalized);
+
+  if (intent.type === "moveTab") {
+    const tabIndex = (normalized.tabIndex + intent.delta + tabs.length) % tabs.length;
+    const nextTab = tabs[tabIndex];
+    const selectedByTab = { ...normalized.selectedByTab };
+    if (nextTab)
+      selectedByTab[nextTab.id] = selectedIndexForTab(nextTab, { ...normalized, tabIndex });
+    return withState({ ...normalized, tabIndex, selectedByTab });
+  }
+
+  if (intent.type === "moveSelection") {
+    if (tab.fields.length === 0) return withState(normalized);
+    const index = selectedIndexForTab(tab, normalized);
+    return withState({
+      ...normalized,
+      selectedByTab: {
+        ...normalized.selectedByTab,
+        [tab.id]: (index + intent.delta + tab.fields.length) % tab.fields.length,
+      },
+    });
+  }
+
+  const field = selectedSetupField(tabs, normalized);
+  if (intent.type === "resetSelectedField") {
+    return field?.changed ? withAction(`reset:${field.id}`, normalized) : withState(normalized);
+  }
+  if (intent.type === "editSelectedField") return withAction(field?.id ?? null, normalized);
+  return withState(normalized);
+}

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

@@ -0,0 +1,299 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { checkHindsight, createHindsightClient } from "../client/client.js";
+import type { MemoryOperationsDeps } from "../operations/memory-operation-service.js";
+import { createMemoryOperations } from "../operations/memory-operation-service.js";
+import type { HindsightLikeClient, ResolvedConfig } from "../types.js";
+import { apiKeyEnvName } from "../config/config-editing-registry.js";
+
+export const LOCAL_DEFAULT_BASE_URL = "http://localhost:8888";
+const DOCS_BASE_URL = "https://luxus.github.io/pi-hindsight";
+const CLOUD_SIGNUP_URL = "https://ui.hindsight.vectorize.io/signup";
+const INSTALL_URL = "https://hindsight.vectorize.io/developer/installation";
+
+export type ServerProbeResult = {
+  ok: boolean;
+  baseUrl: string;
+  usedApiKey: boolean;
+  error?: string;
+};
+
+/** Result of the guided-setup server connection step. */
+export type SetupServerConnection = {
+  /** false = cancel guided setup entirely */
+  continue: boolean;
+  /** true when proceeding without a reachable server (skip network offers) */
+  offline: boolean;
+  serverReachable: boolean;
+  baseUrl?: string;
+};
+
+function normalizeBaseUrl(url: string): string {
+  return url.trim().replace(/\/$/, "") || LOCAL_DEFAULT_BASE_URL;
+}
+
+/** Ordered unique base URLs to try during guided setup. */
+export function buildServerProbeCandidates(config: ResolvedConfig): string[] {
+  const configured = normalizeBaseUrl(config.hindsight.baseUrl);
+  const candidates = [configured];
+  if (configured !== LOCAL_DEFAULT_BASE_URL) candidates.push(LOCAL_DEFAULT_BASE_URL);
+  return [...new Set(candidates)];
+}
+
+export function hasResolvedApiKey(config: ResolvedConfig): boolean {
+  return Boolean(config.hindsight.apiKey?.trim());
+}
+
+export function formatServerProbeDocs(): string {
+  return [
+    "Pi Hindsight docs:",
+    `  Setup TUI: ${DOCS_BASE_URL}/start/setup-tui/`,
+    `  Getting started: ${DOCS_BASE_URL}/start/getting-started/`,
+    `  Minimal config: ${DOCS_BASE_URL}/start/minimal-config/`,
+    `Hindsight server: ${INSTALL_URL}`,
+    `Hindsight Cloud signup: ${CLOUD_SIGNUP_URL}`,
+  ].join("\n");
+}
+
+export function formatServerProbeSuccess(result: ServerProbeResult): string {
+  const key = result.usedApiKey ? "with API key" : "without API key";
+  return `Hindsight server reachable at ${result.baseUrl} (${key}).`;
+}
+
+export function formatServerProbeFailure(args: {
+  results: ServerProbeResult[];
+  hasApiKey: boolean;
+  apiKeyEnvLabel: string;
+}): string {
+  const lines = args.results.map((result) => {
+    const key = result.usedApiKey ? "with key" : "no key";
+    return `  • ${result.baseUrl} (${key}): ${result.error ?? "unreachable"}`;
+  });
+  return [
+    "Could not reach a Hindsight server yet.",
+    ...lines,
+    `API key: ${args.hasApiKey ? "resolved" : `not set (${args.apiKeyEnvLabel})`}`,
+    "",
+    "Local embed often needs no key. Cloud / locked APIs need HINDSIGHT_API_TOKEN (or HINDSIGHT_API_KEY / your env name).",
+    "Cloud base URL comes from your Hindsight dashboard after signup — not a fixed public URL.",
+  ].join("\n");
+}
+
+export function formatApiKeyRestartRequired(envName: string): string {
+  return [
+    `Saved API key env ref “${envName}”, but it is not set in this Pi process.`,
+    `Export it, then restart Pi so the key is available:`,
+    `  export ${envName}=…`,
+    `  # restart Pi, then re-run /hindsight guided setup`,
+    "Or continue offline now for config-only setup (no mental models / import until online).",
+  ].join("\n");
+}
+
+export async function probeHindsightBaseUrl(args: {
+  config: ResolvedConfig;
+  baseUrl: string;
+  createClient?: (config: ResolvedConfig) => HindsightLikeClient;
+  check?: typeof checkHindsight;
+}): Promise<ServerProbeResult> {
+  const baseUrl = normalizeBaseUrl(args.baseUrl);
+  const createClient = args.createClient ?? createHindsightClient;
+  const check = args.check ?? checkHindsight;
+  const probeConfig: ResolvedConfig = {
+    ...args.config,
+    hindsight: { ...args.config.hindsight, baseUrl },
+  };
+  const client = createClient(probeConfig);
+  const health = await check(client, "setup-probe");
+  return {
+    ok: health.ok,
+    baseUrl,
+    usedApiKey: hasResolvedApiKey(probeConfig),
+    ...(health.error ? { error: health.error } : {}),
+  };
+}
+
+export async function probeHindsightCandidates(args: {
+  config: ResolvedConfig;
+  /** When probing the configured URL, prefer the live runtime client (tests/hooks). */
+  configuredClient?: HindsightLikeClient;
+  createClient?: (config: ResolvedConfig) => HindsightLikeClient;
+  check?: typeof checkHindsight;
+}): Promise<{ ok: ServerProbeResult | undefined; attempts: ServerProbeResult[] }> {
+  const attempts: ServerProbeResult[] = [];
+  const check = args.check ?? checkHindsight;
+  const configured = normalizeBaseUrl(args.config.hindsight.baseUrl);
+  for (const baseUrl of buildServerProbeCandidates(args.config)) {
+    let result: ServerProbeResult;
+    if (baseUrl === configured && args.configuredClient) {
+      const health = await check(args.configuredClient, "setup-probe");
+      result = {
+        ok: health.ok,
+        baseUrl,
+        usedApiKey: hasResolvedApiKey(args.config),
+        ...(health.error ? { error: health.error } : {}),
+      };
+    } else {
+      result = await probeHindsightBaseUrl({
+        config: args.config,
+        baseUrl,
+        ...(args.createClient ? { createClient: args.createClient } : {}),
+        ...(args.check ? { check: args.check } : {}),
+      });
+    }
+    attempts.push(result);
+    if (result.ok) return { ok: result, attempts };
+  }
+  return { ok: undefined, attempts };
+}
+
+async function chooseOfflineOrCancel(
+  ctx: ExtensionCommandContext,
+  title: string,
+): Promise<SetupServerConnection> {
+  const choice = await ctx.ui.select(title, [
+    "Continue offline (config only)",
+    "Cancel guided setup",
+  ]);
+  if (!choice || choice === "Cancel guided setup") {
+    return { continue: false, offline: false, serverReachable: false };
+  }
+  ctx.ui.notify(
+    "Continuing guided setup offline. Mental models and import are skipped until a server is reachable.",
+    "warning",
+  );
+  return { continue: true, offline: true, serverReachable: false };
+}
+
+/**
+ * Guided-setup step: health-check Hindsight, recover base URL / API key env, show docs.
+ * Returns offline=true when continuing without a reachable server (caller should skip MM/import).
+ */
+export async function ensureServerConnectionForSetup(args: {
+  ctx: ExtensionCommandContext;
+  deps: MemoryOperationsDeps;
+  cwd: string;
+}): Promise<SetupServerConnection> {
+  const { ctx, deps, cwd } = args;
+  ctx.ui.notify(formatServerProbeDocs(), "info");
+  ctx.ui.notify("Checking Hindsight server connectivity…", "info");
+
+  let config = deps.getConfig();
+  let attempts = 0;
+  const maxAttempts = 4;
+  /** After saving an env ref that is missing in-process, do not re-probe empty. */
+  let pendingKeyRestart = false;
+
+  while (attempts < maxAttempts) {
+    attempts += 1;
+
+    if (pendingKeyRestart) {
+      ctx.ui.notify(
+        "API key env is configured in project config but not loaded in this process. Restart Pi after exporting the key, or continue offline.",
+        "warning",
+      );
+      const choice = await ctx.ui.select("API key requires restart", [
+        "Cancel guided setup (export key + restart Pi)",
+        "Continue offline (config only)",
+      ]);
+      if (!choice || choice.startsWith("Cancel")) {
+        return { continue: false, offline: false, serverReachable: false };
+      }
+      ctx.ui.notify(
+        "Continuing guided setup offline. Mental models and import are skipped until a server is reachable.",
+        "warning",
+      );
+      return { continue: true, offline: true, serverReachable: false };
+    }
+
+    const { ok, attempts: probeAttempts } = await probeHindsightCandidates({
+      config,
+      configuredClient: deps.getClient(),
+    });
+    if (ok) {
+      if (normalizeBaseUrl(config.hindsight.baseUrl) !== ok.baseUrl) {
+        await createMemoryOperations(deps).configure(cwd, { baseUrl: ok.baseUrl });
+        deps.reloadConfig?.(cwd);
+        config = deps.getConfig();
+      }
+      ctx.ui.notify(formatServerProbeSuccess(ok), "info");
+      return {
+        continue: true,
+        offline: false,
+        serverReachable: true,
+        baseUrl: ok.baseUrl,
+      };
+    }
+
+    const apiKeyEnvLabel =
+      apiKeyEnvName(config) !== "not set" ? apiKeyEnvName(config) : "HINDSIGHT_API_TOKEN";
+    ctx.ui.notify(
+      formatServerProbeFailure({
+        results: probeAttempts,
+        hasApiKey: hasResolvedApiKey(config),
+        apiKeyEnvLabel,
+      }),
+      "warning",
+    );
+
+    if (!hasResolvedApiKey(config)) {
+      const setKey = await ctx.ui.confirm(
+        "Configure API key env var?",
+        `No API key is resolved. Local servers often work without one. Cloud needs export ${apiKeyEnvLabel}=… then restart Pi. Save env var name to project config?`,
+      );
+      if (setKey) {
+        const envName = await ctx.ui.input("API key environment variable name", apiKeyEnvLabel);
+        if (envName?.trim()) {
+          await createMemoryOperations(deps).configure(cwd, {
+            apiKeyEnvVar: envName.trim(),
+          });
+          deps.reloadConfig?.(cwd);
+          config = deps.getConfig();
+          if (!hasResolvedApiKey(config)) {
+            ctx.ui.notify(formatApiKeyRestartRequired(envName.trim()), "warning");
+            pendingKeyRestart = true;
+            // Do not empty-reprobe; next loop handles restart vs offline.
+            continue;
+          }
+          // Key resolved after reload (unlikely mid-process unless injected) → re-probe.
+          continue;
+        }
+      }
+    } else {
+      const alt = await ctx.ui.confirm(
+        "Try a different base URL?",
+        "API key is set but the server was unreachable. Paste a Cloud/self-hosted API base URL from your Hindsight dashboard?",
+      );
+      if (alt) {
+        const url = await ctx.ui.input(
+          "Hindsight API base URL",
+          config.hindsight.baseUrl || LOCAL_DEFAULT_BASE_URL,
+        );
+        if (url?.trim()) {
+          await createMemoryOperations(deps).configure(cwd, { baseUrl: url.trim() });
+          deps.reloadConfig?.(cwd);
+          config = deps.getConfig();
+          continue;
+        }
+      }
+    }
+
+    const choice = await ctx.ui.select("Server still unreachable", [
+      "Retry health check",
+      "Continue offline (config only)",
+      "Cancel guided setup",
+    ]);
+    if (!choice || choice === "Cancel guided setup") {
+      return { continue: false, offline: false, serverReachable: false };
+    }
+    if (choice === "Retry health check") continue;
+    ctx.ui.notify(
+      "Continuing guided setup offline. Mental models and import are skipped until a server is reachable.",
+      "warning",
+    );
+    return { continue: true, offline: true, serverReachable: false };
+  }
+
+  return chooseOfflineOrCancel(
+    ctx,
+    "Still no server after several attempts. Continue offline or cancel?",
+  );
+}