pi-blackhole 0.4.2 → 0.4.3

package/src/pi-base/settings/validate-field.ts

@@ -0,0 +1,113 @@
+/**
+ * Field value validation utilities.
+ *
+ * Each `validateFieldValue` call checks a single value against the
+ * field's type-specific constraints (enum membership, boolean type,
+ * string no-newlines, number range / integer / values / step) and
+ * returns either `undefined` (valid) or a warning message string.
+ *
+ * The primary consumer is the settings modal (body.ts), which shows
+ * per-field warnings in the focused-row description area. Callers
+ * can also use this in ConfigManager to skip invalid values during
+ * save, or to repair loaded configs.
+ */
+
+import type { Field } from "./types";
+
+/**
+ * Validate a field value against the field's type-specific constraints.
+ *
+ * @param field - The field definition
+ * @param value - The value to validate
+ * @returns A warning message if invalid, `undefined` if valid
+ */
+export function validateFieldValue(
+  field: Field,
+  value: unknown,
+): string | undefined {
+  if (value === undefined || value === null) return undefined;
+
+  switch (field.type) {
+    case "enum": {
+      if (typeof value !== "string")
+        return `Must be a string, got ${typeof value}`;
+      if (!field.options.includes(value as never))
+        return `Must be one of: ${field.options.join(", ")}`;
+      return undefined;
+    }
+
+    case "boolean": {
+      if (typeof value !== "boolean")
+        return `Must be a boolean, got ${typeof value}`;
+      return undefined;
+    }
+
+    case "string": {
+      if (typeof value !== "string")
+        return `Must be a string, got ${typeof value}`;
+      if (value.includes("\n") || value.includes("\r"))
+        return "Must be a single-line string (no newlines)";
+      return undefined;
+    }
+
+    case "text": {
+      if (typeof value !== "string")
+        return `Must be a string, got ${typeof value}`;
+      return undefined;
+    }
+
+    case "number": {
+      if (typeof value !== "number" || !Number.isFinite(value))
+        return `Must be a finite number, got ${typeof value === "number" ? String(value) : typeof value}`;
+      if (field.integer && !Number.isInteger(value))
+        return "Must be an integer";
+      if (field.values !== undefined && field.values.length > 0) {
+        if (!field.values.includes(value))
+          return `Must be one of: ${field.values.join(", ")}`;
+      }
+      if (typeof field.min === "number" && value < field.min)
+        return `Must be at least ${field.min}`;
+      if (typeof field.max === "number" && value > field.max)
+        return `Must be at most ${field.max}`;
+      if (field.step !== undefined && field.step > 0) {
+        // Check alignment to step within floating-point tolerance
+        const min = field.min ?? 0;
+        const offset = value - min;
+        const rem = offset % field.step;
+        if (rem > 1e-9 && field.step - rem > 1e-9) {
+          return `Must be aligned to step ${field.step}`;
+        }
+      }
+      return undefined;
+    }
+
+    case "secret": {
+      if (typeof value !== "string")
+        return `Must be a string, got ${typeof value}`;
+      return undefined;
+    }
+
+    case "path": {
+      if (typeof value !== "string")
+        return `Must be a string, got ${typeof value}`;
+      return undefined;
+    }
+
+    case "model": {
+      if (typeof value !== "object" || value === null)
+        return `Must be an object with id, got ${typeof value}`;
+      const v = value as { id?: unknown };
+      if (typeof v.id !== "string")
+        return `Must have a string id, got ${typeof v.id}`;
+      return undefined;
+    }
+
+    case "action":
+    case "custom":
+      // Custom types can't be validated generically
+      return undefined;
+
+    default:
+      return undefined;
+  }
+}

package/src/pi-base/shell.ts

@@ -0,0 +1,117 @@
+/** Split a shell command string into tokens, preserving quoted strings. */
+export function tokenizeCommand(command: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let inSingle = false;
+  let inDouble = false;
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+    if (inSingle) {
+      current += ch;
+      if (ch === "'") inSingle = false;
+    } else if (inDouble) {
+      current += ch;
+      if (ch === '"') inDouble = false;
+      else if (ch === "\\" && i + 1 < command.length) current += command[++i];
+    } else if (ch === "'") {
+      current += ch;
+      inSingle = true;
+    } else if (ch === '"') {
+      current += ch;
+      inDouble = true;
+    } else if (ch === " " || ch === "\t") {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+    } else {
+      current += ch;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+/**
+ * Split a command string at the first unquoted pipe or redirect boundary.
+ *
+ * Shell operators: |  2>  >>  1>&2  <  &&  ||  ;
+ * We split on any of these that appear outside quotes.
+ *
+ * Returns [before, atAndAfter] or null if none found.
+ */
+export function splitShellBoundary(str: string): [string, string] | null {
+  // Match shell operators: |  ||  &&  ;  >  >>  2>  1>&2  <  etc.
+  // Anchored with ^ so match is O(1) per character, not O(N).
+  const pattern = /^(?:&&|\|\||[|&;<>]|(?:[12]?>>?[&]?[12]?))/;
+  let inSingle = false;
+  let inDouble = false;
+
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (inSingle) {
+      if (ch === "'") inSingle = false;
+    } else if (inDouble) {
+      if (ch === '"') inDouble = false;
+      else if (ch === "\\" && i + 1 < str.length) i++;
+    } else if (ch === "'") {
+      inSingle = true;
+    } else if (ch === '"') {
+      inDouble = true;
+    } else if (ch === "\\" && i + 1 < str.length) {
+      // Outside quotes: backslash escapes the next character
+      i++;
+    } else {
+      const rest = str.slice(i);
+      const m = rest.match(pattern);
+      if (m) {
+        return [str.slice(0, i).trimEnd(), str.slice(i)];
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Wrap a string in single quotes for safe shell passthrough.
+ * Already-quoted strings (single or double) are left as-is.
+ * Values without shell metacharacters are returned unchanged.
+ */
+const SHELL_META = /[\s{}()$`!'"\\|&;<>#*?[\]~]/;
+export function shellQuote(value: string): string {
+  // Already-quoted single: pass through only if no internal quotes break it
+  if (
+    value.startsWith("'") &&
+    value.endsWith("'") &&
+    !value.slice(1, -1).includes("'")
+  ) {
+    return value;
+  }
+  // Already-quoted double: pass through only if no internal quotes or expansion chars
+  if (
+    value.startsWith('"') &&
+    value.endsWith('"') &&
+    !value.slice(1, -1).includes('"') &&
+    !/[\\$`]/.test(value.slice(1, -1))
+  ) {
+    return value;
+  }
+  // No shell metacharacters - safe to pass through unchanged
+  if (!SHELL_META.test(value)) {
+    return value;
+  }
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/** Strip surrounding shell quotes from a string. */
+export function stripQuotes(s: string): string {
+  if (
+    s.length >= 2 &&
+    ((s.startsWith("'") && s.endsWith("'")) ||
+      (s.startsWith('"') && s.endsWith('"')))
+  ) {
+    return s.slice(1, -1);
+  }
+  return s;
+}

package/src/pi-base/types.ts

@@ -0,0 +1,6 @@
+/**
+ * Type guard: checks if a value is a non-null, non-array object.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/pi-base/ui.ts

@@ -0,0 +1,32 @@
+/**
+ * Common theme overlays for TUI components.
+ */
+export function overlaySelectListTheme(theme: {
+  fg: (color: string, text: string) => string;
+}) {
+  return {
+    selectedPrefix: (text: string) => theme.fg("accent", text),
+    selectedText: (text: string) => theme.fg("accent", text),
+    description: (text: string) => theme.fg("muted", text),
+    scrollInfo: (text: string) => theme.fg("dim", text),
+    noMatch: (text: string) => theme.fg("warning", text),
+  };
+}
+
+/**
+ * ANSI escape code constants.
+ */
+export const ESC = "\x1b";
+export const BEL = "\x07";
+export const ST = "\x1b\\"; // String Terminator for OSC 99 and tmux DCS
+export const RESET = "\x1b[0m";
+
+export type RGB = readonly [number, number, number];
+
+export function fgRGB(c: RGB): string {
+  return `\x1b[38;2;${c[0]};${c[1]};${c[2]}m`;
+}
+
+export function bgRGB(c: RGB): string {
+  return `\x1b[48;2;${c[0]};${c[1]};${c[2]}m`;
+}