pi-ask-popup 0.1.0 → 0.1.1

package/src/ask-user-question.ts

@@ -74,7 +74,9 @@ export const BEL = "\x07";
  */
 function emitTerminalAttention(): void {
   try {
-    if (process.stdout.isTTY) process.stdout.write(BEL);
+    if (process.stdout.isTTY) {
+      process.stdout.write(BEL);
+    }
   } catch {
     // Best effort. Failing to get someone's attention must not stop the
     // questionnaire from being asked.
@@ -127,6 +129,8 @@ type SessionLoad =
       message: string;
     };
 
+type LoadConfigInput = { agentDir: string; projectDir?: string };
+
 /**
  * Load the render graph on first use, guarding its two failure shapes.
  *
@@ -158,7 +162,7 @@ export async function loadQuestionnaireSession(
       message: `${ERROR_SESSION_LOAD_FAILED} (cause: ${cause})`,
     };
   }
-  if (typeof mod.QuestionnaireSession !== "function") {
+  if (!(mod.QuestionnaireSession instanceof Function)) {
     const keys = JSON.stringify(Object.keys(mod));
     return {
       ok: false,
@@ -183,22 +187,31 @@ function registerCollapseKeyListener(
   sessionRef: SessionRef,
   overlayHandleRef: OverlayHandleRef,
 ): (() => void) | undefined {
-  if (collapseKey === COLLAPSE_KEY_OFF || typeof ctx.ui.onTerminalInput !== "function") {
+  if (collapseKey === COLLAPSE_KEY_OFF || !(ctx.ui.onTerminalInput instanceof Function)) {
     return undefined;
   }
   let hasAnnouncedHide = false;
   return ctx.ui.onTerminalInput((data) => {
     const handle = overlayHandleRef.current;
-    if (!handle) return undefined;
+    if (!handle) {
+      return undefined;
+    }
     // Act only while this questionnaire is hidden (its own input is
     // unreachable) or actually focused. With another overlay on top, the key
     // belongs to that one; toggling from underneath it would be baffling.
-    if (!handle.isHidden() && !handle.isFocused()) return undefined;
-    if (!matchesKey(data, collapseKey as Parameters<typeof matchesKey>[1])) return undefined;
+    if (!handle.isHidden() && !handle.isFocused()) {
+      return undefined;
+    }
+    // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
+    if (!matchesKey(data, collapseKey as Parameters<typeof matchesKey>[1])) {
+      return undefined;
+    }
     // Kitty-protocol terminals report press, repeat and release separately.
     // Toggling on all three would make a tap reopen what it just closed, and a
     // held key flicker.
-    if (isKeyRelease(data) || isKeyRepeat(data)) return { consume: true };
+    if (isKeyRelease(data) || isKeyRepeat(data)) {
+      return { consume: true };
+    }
     sessionRef.current?.toggleCollapsedExternal();
     if (handle.isHidden() && !hasAnnouncedHide) {
       // Once only. The dialog has just vanished, so say how to get it back —
@@ -251,7 +264,9 @@ function makeSessionFactory(config: {
           const editorCommand = SettingsManager.create(ctx.cwd, undefined, {
             projectTrusted: ctx.isProjectTrusted(),
           }).getExternalEditorCommand();
-          if (!editorCommand) throw new Error("No external editor command is configured");
+          if (!editorCommand) {
+            throw new Error("No external editor command is configured");
+          }
           return await editWithExternalEditor(tui, editorCommand, value);
         } catch (error) {
           // Reported, then undefined, which the session reads as "keep the
@@ -341,12 +356,13 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
  * exists to prevent. The collapse key, a local UI preference, does read both
  * layers.
  */
-function loadGuidance(): {
-  guidance: ReturnType<typeof validateGuidanceFields>;
-  warnings: readonly string[];
-} {
+function loadGuidance() {
   const { config, warnings } = loadConfig({ agentDir: getAgentDir() });
-  return { guidance: validateGuidanceFields(config.guidance), warnings };
+  const result = {
+    guidance: validateGuidanceFields(config.guidance),
+    warnings,
+  };
+  return result;
 }
 
 export function registerAskPopupTool(pi: ExtensionAPI): void {
@@ -365,10 +381,15 @@ export function registerAskPopupTool(pi: ExtensionAPI): void {
     parameters: QuestionParamsSchema,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const typed = params as unknown as QuestionParams;
-      if (!ctx.hasUI) return rejectWithoutUi();
+      // SAFETY: params is validated by QuestionParamsSchema via validateQuestionnaire immediately after narrowing.
+      const typed = params as QuestionParams;
+      if (!ctx.hasUI) {
+        return rejectWithoutUi();
+      }
 
-      for (const warning of pendingWarnings) ctx.ui.notify?.(warning, "warning");
+      for (const warning of pendingWarnings) {
+        ctx.ui.notify?.(warning, "warning");
+      }
       pendingWarnings = [];
 
       const validation = validateQuestionnaire(typed);
@@ -385,6 +406,7 @@ export function registerAskPopupTool(pi: ExtensionAPI): void {
       // Hosts that advertise their mode go straight to the walker and never
       // import the render graph at all. Older RPC builds fall through to the
       // undefined-result backstop below.
+      // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
       if ((ctx as { mode?: string }).mode === "rpc" && hasDialogUI(ctx.ui)) {
         return runRpcPath(pi, ctx.ui, typed);
       }
@@ -393,7 +415,8 @@ export function registerAskPopupTool(pi: ExtensionAPI): void {
       // primitives is malformed, and calling `custom` on it throws a bare
       // TypeError that reaches the model as a broken tool rather than an
       // unsupported one. Answer honestly instead: nobody saw the questions.
-      if (typeof (ctx.ui as { custom?: unknown }).custom !== "function") {
+      // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
+      if (!((ctx.ui as { custom?: unknown }).custom instanceof Function)) {
         return resolveUndefinedResult(ctx, typed);
       }
 
@@ -414,12 +437,13 @@ export function registerAskPopupTool(pi: ExtensionAPI): void {
       // Both layers here: unlike guidance, this only binds a key in the user's
       // own terminal, and a project pinning a shortcut that suits its docs is
       // reasonable. `resolveCollapseKey` refuses anything malformed.
-      const collapseKey = resolveCollapseKey(
-        loadConfig({
-          agentDir: getAgentDir(),
-          ...(ctx.isProjectTrusted() ? { projectDir: ctx.cwd } : {}),
-        }).config,
-      );
+      const configInput: LoadConfigInput = {
+        agentDir: getAgentDir(),
+      };
+      if (ctx.isProjectTrusted()) {
+        configInput.projectDir = ctx.cwd;
+      }
+      const collapseKey = resolveCollapseKey(loadConfig(configInput).config);
 
       const sessionRef: SessionRef = { current: null };
       const overlayHandleRef: OverlayHandleRef = { current: undefined };
@@ -461,7 +485,9 @@ export function registerAskPopupTool(pi: ExtensionAPI): void {
           },
         );
 
-        if (result === undefined) return resolveUndefinedResult(ctx, typed);
+        if (result === undefined) {
+          return resolveUndefinedResult(ctx, typed);
+        }
         return buildQuestionnaireResponse(result, typed);
       } finally {
         removeOverlayInputListener?.();

package/src/config.ts

@@ -2,6 +2,25 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
 
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { readonly [key: string]: JsonValue };
+type JsonRecord = Record<string, JsonValue>;
+
+function isRecord(value: unknown): value is JsonRecord;
+function isRecord(value: JsonValue | undefined): value is JsonRecord;
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
 /** Key spec for the overlay collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
 export type CollapseKeySpec = string;
 
@@ -72,32 +91,34 @@ export function configPaths(sources: ConfigSources): string[] {
  * check-then-read pair races, and this keeps the no-write guarantee obvious —
  * nothing here can create a file or a parent directory.
  */
-function readLayer(path: string, warnings: string[]): Record<string, unknown> {
+function readLayer(path: string, warnings: string[]): JsonRecord {
   let text: string;
   try {
     text = readFileSync(path, "utf8");
   } catch (err) {
+    // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
     if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
       warnings.push(`pi-ask-popup: cannot read ${path} — ${(err as Error).message}`);
     }
     return {};
   }
   try {
     const parsed: unknown = JSON.parse(text);
-    // `typeof null === "object"` and so is an array; a config file is neither.
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    if (!isRecord(parsed)) {
       warnings.push(`pi-ask-popup: ${path} is not a JSON object, ignoring it`);
       return {};
     }
-    return parsed as Record<string, unknown>;
+    return parsed;
   } catch (err) {
+    // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
     warnings.push(`pi-ask-popup: invalid JSON in ${path}, ignoring it — ${(err as Error).message}`);
     return {};
   }
 }
 
 function nonEmptyString(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
+  return isNonEmptyString(value) ? value : undefined;
 }
 
 /**
@@ -106,19 +127,26 @@ function nonEmptyString(value: unknown): string | undefined {
  * the tool still registers.
  */
 export function validateGuidanceFields(fields: unknown): GuidanceFields {
-  if (fields === null || typeof fields !== "object") return {};
-  const g = fields as Record<string, unknown>;
+  if (!isRecord(fields)) {
+    return {};
+  }
+  const g = fields;
   const out: GuidanceFields = {};
   const description = nonEmptyString(g.description);
-  if (description !== undefined) out.description = description;
+  if (description !== undefined) {
+    out.description = description;
+  }
   const promptSnippet = nonEmptyString(g.promptSnippet);
-  if (promptSnippet !== undefined) out.promptSnippet = promptSnippet;
+  if (promptSnippet !== undefined) {
+    out.promptSnippet = promptSnippet;
+  }
   const guidelines = g.promptGuidelines;
   if (
     Array.isArray(guidelines) &&
     guidelines.length > 0 &&
     guidelines.every((s) => nonEmptyString(s) !== undefined)
   ) {
+    // SAFETY: guidelines elements are validated as non-empty strings above; preserving string array type is safe.
     out.promptGuidelines = guidelines as string[];
   }
   return out;
@@ -135,7 +163,9 @@ export function loadConfig(sources: ConfigSources): ConfigLoadResult {
   for (const path of configPaths(sources)) {
     const raw = readLayer(path, warnings);
     const collapseKey = nonEmptyString(raw.collapseKey);
-    if (collapseKey !== undefined) config.collapseKey = collapseKey;
+    if (collapseKey !== undefined) {
+      config.collapseKey = collapseKey;
+    }
     const guidance = validateGuidanceFields(raw.guidance);
     if (Object.keys(guidance).length > 0) {
       config.guidance = { ...config.guidance, ...guidance };
@@ -183,7 +213,9 @@ const SPECIAL_KEYS = new Set([
 const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
 
 function isBaseKey(key: string): boolean {
-  if (key.length !== 1) return SPECIAL_KEYS.has(key);
+  if (key.length !== 1) {
+    return SPECIAL_KEYS.has(key);
+  }
   return (key >= "a" && key <= "z") || (key >= "0" && key <= "9") || SYMBOL_KEYS.has(key);
 }
 
@@ -199,12 +231,18 @@ function isBaseKey(key: string): boolean {
  * user types, anywhere.
  */
 function isValidCollapseKeySpec(spec: string): boolean {
-  if (!spec || spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
+  if (!spec || spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) {
+    return false;
+  }
   const parts = spec.split("+");
   const base = parts[parts.length - 1] ?? "";
   const modifiers = parts.slice(0, -1);
-  if (modifiers.length !== new Set(modifiers).size) return false;
-  if (!modifiers.every((m) => MODIFIERS.has(m))) return false;
+  if (modifiers.length !== new Set(modifiers).size) {
+    return false;
+  }
+  if (!modifiers.every((m) => MODIFIERS.has(m))) {
+    return false;
+  }
   return isBaseKey(base);
 }
 
@@ -220,17 +258,21 @@ export function resolveCollapseKey(config: {
   collapseKey?: CollapseKeySpec | undefined;
 }): CollapseKeySpec {
   const raw = config.collapseKey?.trim().toLowerCase();
-  if (raw === undefined || raw === "") return DEFAULT_COLLAPSE_KEY;
-  if (raw === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
+  if (raw === undefined || raw === "") {
+    return DEFAULT_COLLAPSE_KEY;
+  }
+  if (raw === COLLAPSE_KEY_OFF) {
+    return COLLAPSE_KEY_OFF;
+  }
   return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
 }
 
 // The only compound-word names in SPECIAL_KEYS — capitalizing the first letter
 // alone would render them "Pageup" and "Pagedown".
-const COMPOUND_KEY_DISPLAY: Record<string, string> = {
+const COMPOUND_KEY_DISPLAY = {
   pageup: "PageUp",
   pagedown: "PageDown",
-};
+} satisfies Record<string, string>;
 
 /**
  * Pretty-print a resolved spec for UI copy: `"ctrl+]"` → `"Ctrl+]"`, `"alt+o"` →
@@ -241,10 +283,11 @@ const COMPOUND_KEY_DISPLAY: Record<string, string> = {
 export function formatKeySpecForDisplay(spec: CollapseKeySpec): string {
   return spec
     .split("+")
-    .map(
-      (part) =>
-        COMPOUND_KEY_DISPLAY[part] ??
-        (part.length <= 1 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1)),
-    )
+    .map((part) => {
+      if (part === "pageup" || part === "pagedown") {
+        return COMPOUND_KEY_DISPLAY[part];
+      }
+      return part.length <= 1 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1);
+    })
     .join("+");
 }

package/src/rpc-fallback.ts

@@ -58,8 +58,9 @@ export type DialogUI = {
 
 /** Whether the host implements the select and input primitives. */
 export function hasDialogUI(ui: unknown): ui is DialogUI {
-  const u = ui as Partial<Record<"select" | "input", unknown>> | null | undefined;
-  return typeof u?.select === "function" && typeof u?.input === "function";
+  // SAFETY: safe cast — value is validated at boundary or test fixture with known shape.
+  const u = ui as Partial<DialogUI> | null | undefined;
+  return u?.select instanceof Function && u?.input instanceof Function;
 }
 
 type Option = QuestionData["options"][number];
@@ -105,12 +106,16 @@ export async function runRpcQuestionnaire(
   const dialogOpts = params.timeout === undefined ? undefined : { timeout: params.timeout };
   for (let qi = 0; qi < params.questions.length; qi++) {
     const q = params.questions[qi];
-    if (!q) continue;
+    if (!q) {
+      continue;
+    }
     const header = q.header ? `[${q.header}] ` : "";
     const answer = q.multiSelect
       ? await askMultiSelect(ui, q, qi, header, dialogOpts)
       : await askSingleSelect(ui, q, qi, header, dialogOpts);
-    if (answer === undefined) return { answers, cancelled: true };
+    if (answer === undefined) {
+      return { answers, cancelled: true };
+    }
     answers.push(answer);
   }
   return { answers, cancelled: false };
@@ -127,29 +132,35 @@ async function askSingleSelect(
   const options = q.options.map(formatOptionLine);
   options.push(`${q.options.length + 1}. ${ROW_INTENT_META.other.label}`);
   const chosen = await ui.select(`${header}${q.question}${buildPreviewBlock(q)}`, options, opts);
-  if (chosen === undefined || chosen === null) return undefined;
+  if (chosen === undefined || chosen === null) {
+    return undefined;
+  }
   const idx = parseIndex(chosen, options.length);
   // A host that returns something outside the list it was given is
   // indistinguishable from a dismissal. Treating it as one beats fabricating
   // an answer the user never gave.
-  if (idx === null) return undefined;
+  if (idx === null) {
+    return undefined;
+  }
   const option = q.options[idx];
   if (option) {
-    return {
+    const answer: QuestionAnswer = {
       questionIndex,
       question: q.question,
       kind: "option",
       answer: option.label,
-      // Spread rather than assigned: the envelope's contract is that the key is
-      // absent when there was no preview, not present and undefined.
-      ...(option.preview !== undefined && option.preview.length > 0
-        ? { preview: option.preview }
-        : {}),
     };
+    if (option.preview !== undefined && option.preview.length > 0) {
+      // SAFETY: preview is an optional string; present only when non-empty per contract.
+      (answer as QuestionAnswer & { preview: string }).preview = option.preview;
+    }
+    return answer;
   }
   // The "Type something." row, which is the one index past the authored options.
   const typed = await ui.input(`${header}${q.question}\n\n${CUSTOM_ANSWER_TITLE}`, "", opts);
-  if (typed === undefined || typed === null) return undefined;
+  if (typed === undefined || typed === null) {
+    return undefined;
+  }
   return { questionIndex, question: q.question, kind: "custom", answer: typed };
 }
 
@@ -167,7 +178,9 @@ async function askMultiSelect(
     MULTI_SELECT_PLACEHOLDER,
     opts,
   );
-  if (value === undefined || value === null) return undefined;
+  if (value === undefined || value === null) {
+    return undefined;
+  }
   const trimmed = value.trim();
   if (trimmed.length === 0) {
     // A deliberate empty commit, the same as pressing Next with nothing ticked.
@@ -186,7 +199,9 @@ async function askMultiSelect(
     const selected: string[] = [];
     for (const i of indices) {
       const label = q.options[i]?.label;
-      if (label !== undefined && !selected.includes(label)) selected.push(label);
+      if (label !== undefined && !selected.includes(label)) {
+        selected.push(label);
+      }
     }
     return { questionIndex, question: q.question, kind: "multi", answer: null, selected };
   }

package/src/state/build-questionnaire.ts

@@ -235,7 +235,9 @@ class QuestionnaireBuilder {
       let max = 0;
       for (const tab of tabs) {
         const h = tab.bodyHeights(width).max;
-        if (h > max) max = h;
+        if (h > max) {
+          max = h;
+        }
       }
       return Math.max(1, max);
     };

package/src/state/external-editor.ts

@@ -23,7 +23,9 @@ function runEditor(command: string, file: string): Promise<void> {
   const [editor, ...args] = command.split(" ");
   // Unreachable given the caller's check, but the destructure is typed as
   // possibly-undefined and a bare assertion here would be worse.
-  if (!editor) return Promise.reject(new Error("External editor command is empty"));
+  if (!editor) {
+    return Promise.reject(new Error("External editor command is empty"));
+  }
 
   return new Promise((resolve, reject) => {
     const child = spawn(editor, [...args, file], {
@@ -64,7 +66,9 @@ export async function editWithExternalEditor(
   // TUI has already been stopped, makes a misconfigured editor command flash
   // the screen off and back on before reporting a problem that was knowable
   // from the start.
-  if (command.trim().length === 0) throw new Error("External editor command is empty");
+  if (command.trim().length === 0) {
+    throw new Error("External editor command is empty");
+  }
 
   const tempDir = mkdtempSync(join(tmpdir(), "pi-ask-popup-"));
   const tempFile = join(tempDir, "answer.md");