@cad0p/pi-usage 0.0.0-stage → 0.11.2

package/src/gentle-pi/rail-patch.js

@@ -0,0 +1,335 @@
+/**
+ * gentle-pi paints its right rail from a hardcoded allowlist, so a part that
+ * another extension registers under any other key is never rendered. This module
+ * owns the single anchored edit that appends piQuota's part to that allowlist,
+ * plus the detection that tells a patch wiped by a package update apart from an
+ * unrecognized gentle-pi revision.
+ *
+ * The edit is deliberately narrow: it rewrites one array literal and leaves every
+ * other byte of the file untouched. An unrecognized shape is reported instead of
+ * guessed at, because a wrong rewrite of another extension's layout would break
+ * the whole rail.
+ *
+ * CLI (used by install.sh and available for manual repair):
+ *   node src/gentle-pi/rail-patch.js --status | --apply | --revert [--dir <path>]
+ */
+
+import { copyFileSync, existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** The rail part piQuota registers, and the key this module adds to the allowlist. */
+export const GENTLE_PI_PART = "quota";
+
+const LAYOUT_RELATIVE = join("lib", "shell-sidebar-layout.ts");
+const BACKUP_SUFFIX = ".pi-quota-backup";
+const TEMP_SUFFIX = ".pi-quota-tmp";
+
+/** Default package roots, in the order a Pi installation is likely to have them. */
+const PACKAGE_ROOTS = [
+  join(homedir(), ".pi", "agent", "npm", "node_modules", "gentle-pi"),
+  join(homedir(), ".pi", "agent", "gentle-ai", "node_modules", "gentle-pi"),
+];
+
+/**
+ * @typedef {"patched" | "unpatched" | "unknown" | "missing"} RailPatchState
+ * @typedef {{ state: RailPatchState, sections: string[], detail: string }} RailPatchInspection
+ * @typedef {{ ok: boolean, changed: boolean, state: RailPatchState, detail: string, backupPath?: string }} RailPatchResult
+ */
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function reason(error) {
+  const message = /** @type {{ message?: string }} */ (error)?.message;
+  return message ?? String(error);
+}
+
+/**
+ * Every `const sections = [...]` allowlist in the file, each with its own offsets
+ * so a rewrite can replace exactly one of them. Matches both simple `.map()` chains
+ * (gentle-pi 3.x) and filtered/chained pipelines like `.filter(...).map()` (gentle-pi 4.x+).
+ *
+ * @param {string} text
+ * @returns {Array<{ text: string, inner: string, index: number }>}
+ */
+function findSectionAllowlists(text) {
+  const pattern = /(?:const|let|var)\s+sections\s*=\s*\[([^\]]*)\]/g;
+  /** @type {Array<{ text: string, inner: string, index: number }>} */
+  const found = [];
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    found.push({ text: match[0], inner: match[1], index: match.index });
+  }
+  return found;
+}
+
+/**
+ * @param {string} inner
+ * @returns {string[]}
+ */
+function keysOf(inner) {
+  const pattern = /["']([^"']+)["']/g;
+  /** @type {string[]} */
+  const keys = [];
+  let match;
+  while ((match = pattern.exec(inner)) !== null) keys.push(match[1]);
+  return keys;
+}
+
+/**
+ * Append a key while preserving the spacing and quote style of the entries already present.
+ *
+ * @param {string} inner
+ * @param {string} part
+ * @returns {string}
+ */
+function appendPart(inner, part) {
+  const quote = /'/.test(inner) && !/"/.test(inner) ? "'" : '"';
+  const entry = `${quote}${part}${quote}`;
+  const trimmed = inner.replace(/\s+$/, "");
+  return trimmed === "" ? entry : `${trimmed}, ${entry}`;
+}
+
+/**
+ * Drop a key together with the comma that joined it, so the remaining entries keep
+ * their original text and `["a", "b", "quota"]` becomes `["a", "b"]` rather than a
+ * list with a dangling separator.
+ *
+ * @param {string} inner
+ * @param {string} part
+ * @returns {string}
+ */
+function dropPart(inner, part) {
+  const escaped = part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const trailing = new RegExp(`,\\s*["']${escaped}["']\\s*$`);
+  if (trailing.test(inner)) return inner.replace(trailing, "");
+  const leading = new RegExp(`["']${escaped}["']\\s*,\\s*`);
+  if (leading.test(inner)) return inner.replace(leading, "");
+  // The part can be the only entry, and then there is no comma to remove with it.
+  const only = new RegExp(`^\\s*["']${escaped}["']\\s*$`);
+  if (only.test(inner)) return "";
+  return inner;
+}
+
+/**
+ * @param {string} layoutPath
+ * @param {string} text
+ */
+function writeAtomically(layoutPath, text) {
+  const temp = `${layoutPath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(temp, text, "utf-8");
+    renameSync(temp, layoutPath);
+  } catch (error) {
+    try {
+      unlinkSync(temp);
+    } catch {
+      // The temp file is either gone or unreachable; the caller reports the real failure.
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {string} dir
+ * @returns {{ dir: string, layoutPath: string, present: boolean }}
+ */
+function layoutFor(dir) {
+  const layoutPath = join(dir, LAYOUT_RELATIVE);
+  return { dir, layoutPath, present: existsSync(layoutPath) };
+}
+
+/**
+ * Locate the installed gentle-pi package and the layout file this module edits.
+ * An explicit `dir` or `PI_QUOTA_GENTLE_PI_DIR` is authoritative: when it holds no
+ * layout file the answer is "not present" rather than a different installation.
+ *
+ * @param {{ dir?: string }} [options]
+ * @returns {{ dir: string, layoutPath: string, present: boolean }}
+ */
+export function resolveGentlePiLayout(options = {}) {
+  if (options.dir) return layoutFor(options.dir);
+  const override = process.env.PI_QUOTA_GENTLE_PI_DIR;
+  if (override) return layoutFor(override);
+  for (const root of PACKAGE_ROOTS) {
+    const layout = layoutFor(root);
+    if (layout.present) return layout;
+  }
+  return layoutFor(PACKAGE_ROOTS[0]);
+}
+
+/**
+ * @param {{ layoutPath: string }} options
+ * @returns {RailPatchInspection}
+ */
+export function inspectRailPatch({ layoutPath }) {
+  let text;
+  try {
+    text = readFileSync(layoutPath, "utf-8");
+  } catch (error) {
+    return { state: "missing", sections: [], detail: `cannot read ${layoutPath}: ${reason(error)}` };
+  }
+
+  const allowlists = findSectionAllowlists(text);
+  if (allowlists.length === 0) {
+    return { state: "unknown", sections: [], detail: "no rail section allowlist found; refusing to guess" };
+  }
+  if (allowlists.length > 1) {
+    return { state: "unknown", sections: [], detail: `expected one rail section allowlist, found ${allowlists.length}` };
+  }
+
+  const sections = keysOf(allowlists[0].inner);
+  if (sections.includes(GENTLE_PI_PART)) {
+    return { state: "patched", sections, detail: `the rail already renders "${GENTLE_PI_PART}"` };
+  }
+  return { state: "unpatched", sections, detail: `the rail renders: ${sections.join(", ") || "(nothing)"}` };
+}
+
+/**
+ * Append the part to the allowlist. Idempotent, atomic, and verified: the file is
+ * re-read after the write and restored from the backup when the result does not
+ * read back as patched.
+ *
+ * @param {{ layoutPath: string }} options
+ * @returns {RailPatchResult}
+ */
+export function applyRailPatch({ layoutPath }) {
+  const inspected = inspectRailPatch({ layoutPath });
+  if (inspected.state === "patched") {
+    return { ok: true, changed: false, state: "patched", detail: inspected.detail };
+  }
+  if (inspected.state !== "unpatched") {
+    return { ok: false, changed: false, state: inspected.state, detail: inspected.detail };
+  }
+
+  let original;
+  try {
+    original = readFileSync(layoutPath, "utf-8");
+  } catch (error) {
+    return { ok: false, changed: false, state: "missing", detail: `cannot read ${layoutPath}: ${reason(error)}` };
+  }
+
+  const allowlist = findSectionAllowlists(original)[0];
+  const replacement = `const sections = [${appendPart(allowlist.inner, GENTLE_PI_PART)}]`;
+  const patched = original.slice(0, allowlist.index) + replacement + original.slice(allowlist.index + allowlist.text.length);
+
+  const backupPath = `${layoutPath}${BACKUP_SUFFIX}`;
+  try {
+    if (!existsSync(backupPath)) copyFileSync(layoutPath, backupPath);
+    writeAtomically(layoutPath, patched);
+  } catch (error) {
+    return { ok: false, changed: false, state: "unpatched", detail: `could not write ${layoutPath}: ${reason(error)}`, backupPath };
+  }
+
+  const verified = inspectRailPatch({ layoutPath });
+  if (verified.state !== "patched") {
+    try {
+      writeAtomically(layoutPath, readFileSync(backupPath, "utf-8"));
+    } catch {
+      // The restore is best effort; the report below is the authoritative outcome.
+    }
+    return { ok: false, changed: true, state: verified.state, detail: `the edit did not read back as patched (${verified.detail}); restored from backup`, backupPath };
+  }
+  return { ok: true, changed: true, state: "patched", detail: `added "${GENTLE_PI_PART}" to the rail allowlist`, backupPath };
+}
+
+/**
+ * Remove the part from the allowlist, restoring the original bytes for a file this
+ * module patched.
+ *
+ * @param {{ layoutPath: string }} options
+ * @returns {RailPatchResult}
+ */
+export function revertRailPatch({ layoutPath }) {
+  const inspected = inspectRailPatch({ layoutPath });
+  if (inspected.state === "missing" || inspected.state === "unknown") {
+    return { ok: false, changed: false, state: inspected.state, detail: inspected.detail };
+  }
+  if (inspected.state === "unpatched") {
+    return { ok: true, changed: false, state: "unpatched", detail: `the rail already excludes "${GENTLE_PI_PART}"` };
+  }
+
+  let original;
+  try {
+    original = readFileSync(layoutPath, "utf-8");
+  } catch (error) {
+    return { ok: false, changed: false, state: "missing", detail: `cannot read ${layoutPath}: ${reason(error)}` };
+  }
+
+  const allowlist = findSectionAllowlists(original)[0];
+  const replacement = `const sections = [${dropPart(allowlist.inner, GENTLE_PI_PART)}]`;
+  const reverted = original.slice(0, allowlist.index) + replacement + original.slice(allowlist.index + allowlist.text.length);
+
+  const backupPath = `${layoutPath}${BACKUP_SUFFIX}`;
+  try {
+    writeAtomically(layoutPath, reverted);
+  } catch (error) {
+    return { ok: false, changed: false, state: "patched", detail: `could not write ${layoutPath}: ${reason(error)}`, backupPath };
+  }
+
+  const verified = inspectRailPatch({ layoutPath });
+  if (verified.state !== "unpatched") {
+    try {
+      copyFileSync(backupPath, layoutPath);
+    } catch {
+      // The restore is best effort; the report below is the authoritative outcome.
+    }
+    return { ok: false, changed: true, state: verified.state, detail: `the revert did not read back as unpatched (${verified.detail}); restored from backup`, backupPath };
+  }
+  return { ok: true, changed: true, state: "unpatched", detail: `removed "${GENTLE_PI_PART}" from the rail allowlist`, backupPath };
+}
+
+/**
+ * The validator the extension and the installer both call: report whether the rail
+ * renders the part, and repair it when a gentle-pi update wiped the patch.
+ *
+ * @param {{ layoutPath: string }} options
+ * @returns {RailPatchResult & { repaired: boolean }}
+ */
+export function ensureRailPatch({ layoutPath }) {
+  const inspected = inspectRailPatch({ layoutPath });
+  if (inspected.state === "patched") {
+    return { repaired: false, ok: true, changed: false, state: "patched", detail: inspected.detail };
+  }
+  const applied = applyRailPatch({ layoutPath });
+  return { ...applied, repaired: applied.changed === true };
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {number}
+ */
+function runCli(argv) {
+  const action = argv.includes("--revert") ? "revert" : argv.includes("--apply") ? "apply" : "status";
+  const dirIndex = argv.indexOf("--dir");
+  const dir = dirIndex >= 0 ? argv[dirIndex + 1] : undefined;
+
+  const layout = resolveGentlePiLayout(dir ? { dir } : {});
+  if (!layout.present) {
+    process.stdout.write(`gentle-pi not found at ${layout.layoutPath}\n`);
+    process.stdout.write("nothing to do: piQuota renders its own widget without the rail\n");
+    return 0;
+  }
+
+  if (action === "status") {
+    const inspected = inspectRailPatch({ layoutPath: layout.layoutPath });
+    process.stdout.write(`gentle-pi: ${layout.layoutPath}\n`);
+    process.stdout.write(`rail patch: ${inspected.state} (${inspected.detail})\n`);
+    if (inspected.state !== "patched") {
+      process.stdout.write("run `piquota gentle-pi apply`, or let the extension repair it at session start\n");
+    }
+    return inspected.state === "unknown" ? 1 : 0;
+  }
+
+  const result = action === "revert" ? revertRailPatch({ layoutPath: layout.layoutPath }) : applyRailPatch({ layoutPath: layout.layoutPath });
+  process.stdout.write(`gentle-pi: ${layout.layoutPath}\n`);
+  process.stdout.write(`rail patch: ${result.state} — ${result.detail}\n`);
+  if (result.backupPath) process.stdout.write(`backup: ${result.backupPath}\n`);
+  return result.ok ? 0 : 1;
+}
+
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) process.exit(runCli(process.argv.slice(2)));

package/src/http.js

@@ -0,0 +1,182 @@
+/**
+ * Minimal timed JSON HTTP helpers.
+ *
+ * Every outbound request in this project goes through here so that timeouts,
+ * redaction of secrets and error normalization stay in one place.
+ */
+
+const DEFAULT_TIMEOUT_MS = 15000;
+
+/**
+ * Redact credential-looking substrings from arbitrary text before it can reach
+ * a log, a terminal or an error message.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function redact(value) {
+  let text = typeof value === "string" ? value : String(value ?? "");
+  text = text.replace(/[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}/g, "<email>");
+  text = text.replace(/\beyJ[\w-]{8,}\.[\w-]{8,}\.[\w-]{4,}\b/g, "<jwt>");
+  text = text.replace(/\b(sk-[A-Za-z0-9_-]{6})[A-Za-z0-9_-]+/g, "$1<redacted>");
+  text = text.replace(/\b(ya29\.)[A-Za-z0-9_-]+/g, "$1<redacted>");
+  text = text.replace(/\b(1\/\/)[A-Za-z0-9_-]+/g, "$1<redacted>");
+  text = text.replace(/\b(rt\.[\w.]{4})[A-Za-z0-9_-]+/g, "$1<redacted>");
+  text = text.replace(/\b(Bearer\s+)[A-Za-z0-9._~+/-]+=*/gi, "$1<redacted>");
+  text = text.replace(/\b((?:__Host-console_session|auth)=)[^;\s]+/gi, "$1<redacted>");
+  return text;
+}
+
+/**
+ * @typedef {Object} HttpResult
+ * @property {boolean} ok
+ * @property {number} status
+ * @property {unknown} [body]      Parsed JSON body when parsing succeeded.
+ * @property {string} [text]       Raw body when JSON parsing failed or on error.
+ * @property {string} [error]      Redacted, human-readable failure reason.
+ * @property {boolean} [authError] True for 401/403, which callers surface as a
+ *                                 "sign in again" degradation.
+ * @property {string | null} [authMessage] The provider's own error message for a
+ *                                 401/403, redacted and length-capped. Callers
+ *                                 that need to distinguish "revoked key" from
+ *                                 "plan not active" use it; the generic error
+ *                                 text stays the same for everyone else.
+ */
+
+/**
+ * Read a provider's JSON error message from a 401/403 body.
+ *
+ * The status alone cannot tell a revoked credential from a valid credential
+ * whose workspace is not entitled to the product, and both Pi and the vendor
+ * return that distinction in the body. Never throws: an unreadable body is
+ * simply no detail.
+ *
+ * @param {{ text?: () => Promise<string> }} response
+ * @returns {Promise<string | null>}
+ */
+async function readAuthMessage(response) {
+  let raw = "";
+  try {
+    raw = await response.text();
+  } catch {
+    return null;
+  }
+  if (!raw || raw.trim() === "") return null;
+  let message = null;
+  try {
+    const body = JSON.parse(raw);
+    const value = body?.error?.message ?? body?.message ?? body?.error;
+    message = typeof value === "string" ? value : null;
+  } catch {
+    return null;
+  }
+  if (!message) return null;
+  return redact(message).replace(/\s+/g, " ").trim().slice(0, 120) || null;
+}
+
+/**
+ * Perform one request and parse a JSON body.
+ *
+ * @param {string} url
+ * @param {{
+ *   method?: string,
+ *   headers?: Record<string, string>,
+ *   body?: string,
+ *   timeoutMs?: number,
+ *   fetchFn?: typeof fetch,
+ * }} [options]
+ * @returns {Promise<HttpResult>}
+ */
+export async function requestJson(url, options = {}) {
+  const fetchFn = options.fetchFn ?? fetch;
+  const controller = new AbortController();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetchFn(url, {
+      method: options.method ?? "GET",
+      headers: options.headers,
+      body: options.body,
+      signal: controller.signal,
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      return {
+        ok: false,
+        status: response.status,
+        authError: true,
+        authMessage: await readAuthMessage(response),
+        error: `sign-in expired (HTTP ${response.status})`,
+      };
+    }
+
+    if (response.status === 429) {
+      const rawHeader = response.headers?.get?.("retry-after")?.trim();
+      let retrySec = null;
+      if (rawHeader) {
+        if (/^\d+$/.test(rawHeader)) {
+          retrySec = Number(rawHeader);
+        } else {
+          const parsed = Date.parse(rawHeader);
+          if (!Number.isNaN(parsed)) {
+            retrySec = Math.max(0, Math.round((parsed - Date.now()) / 1000));
+          }
+        }
+      }
+      return {
+        ok: false,
+        status: 429,
+        error: retrySec !== null
+          ? `rate limited (HTTP 429); retry in ${retrySec}s`
+          : "rate limited (HTTP 429); retry in a minute",
+      };
+    }
+
+    if (!response.ok) {
+      let detail = "";
+      try {
+        detail = (await response.text()).slice(0, 200);
+      } catch {
+        // Body is optional: the status alone is enough to report the failure.
+      }
+      return {
+        ok: false,
+        status: response.status,
+        error: detail
+          ? `HTTP ${response.status}: ${redact(detail).replace(/\s+/g, " ")}`
+          : `HTTP ${response.status}`,
+      };
+    }
+
+    const raw = await response.text();
+    if (raw.trim() === "") {
+      return { ok: true, status: response.status, body: null };
+    }
+    try {
+      return { ok: true, status: response.status, body: JSON.parse(raw) };
+    } catch {
+      return {
+        ok: false,
+        status: response.status,
+        text: raw,
+        error: "response was not valid JSON",
+      };
+    }
+  } catch (error) {
+    const name = /** @type {{ name?: string, message?: string }} */ (error)?.name;
+    const message = /** @type {{ message?: string }} */ (error)?.message ?? String(error);
+    const cause = /** @type {{ cause?: { code?: string, message?: string } }} */ (error)?.cause;
+    const causeCode = cause?.code ?? cause?.message;
+    const detail = causeCode && typeof causeCode === "string" && !message.includes(causeCode)
+      ? `${message}: ${causeCode}`
+      : message;
+    return {
+      ok: false,
+      status: 0,
+      error: name === "AbortError" ? `timed out after ${timeoutMs}ms` : redact(detail),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}