@pinta-ai/pinta-codex 1.2.0

package/tools/_lib.ts

@@ -0,0 +1,274 @@
+/**
+ * Shared helpers for setup / doctor / install-hooks / uninstall-hooks.
+ *
+ * Keeps path resolution, config-file I/O, and TOML toggling in one place so
+ * the scripts stay thin and stay consistent.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export const PLUGIN_ROOT = path.resolve(__dirname, "..");
+export const PLUGIN_ENTRY = path.join(PLUGIN_ROOT, "dist", "index.js");
+
+export const CODEX_HOME = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+export const CODEX_HOOKS_PATH = path.join(CODEX_HOME, "hooks.json");
+export const CODEX_CONFIG_PATH = path.join(CODEX_HOME, "config.toml");
+export const CODEX_ENV_PATH = path.join(CODEX_HOME, "pinta-codex.env");
+
+export interface HookCommand {
+  type: "command";
+  command: string;
+  timeout?: number;
+  statusMessage?: string;
+}
+export interface HookMatcher {
+  matcher?: string;
+  hooks: HookCommand[];
+}
+export interface HooksFile {
+  hooks: Record<string, HookMatcher[]>;
+}
+
+// --- JSON helpers ---
+
+export function readJson<T>(p: string, fallback: T): T {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8")) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+// --- env file ("KEY=VALUE" per line) ---
+
+export function readEnvFile(p: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  let content: string;
+  try {
+    content = fs.readFileSync(p, "utf-8");
+  } catch {
+    return out;
+  }
+  for (const raw of content.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const idx = line.indexOf("=");
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim();
+    let value = line.slice(idx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key) out[key] = value;
+  }
+  return out;
+}
+
+export function writeEnvFile(p: string, values: Record<string, string>): void {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const body = Object.entries(values)
+    .map(([k, v]) => `${k}=${v}`)
+    .join("\n");
+  fs.writeFileSync(p, body + "\n", "utf-8");
+}
+
+/**
+ * Migrate legacy `PINTA_CODEX_*` keys to OTel-spec names.
+ * - PINTA_CODEX_ENDPOINT → OTEL_EXPORTER_OTLP_ENDPOINT
+ * - PINTA_CODEX_API_KEY  → OTEL_EXPORTER_OTLP_HEADERS=x-pinta-relay-token=<value>
+ *
+ * If migration occurs, writes `<path>.bak` with the original content first
+ * (idempotent — won't overwrite an existing .bak), then writes the file with
+ * the new keys. Existing OTel-spec keys win and are preserved as-is.
+ *
+ * Returns the list of legacy keys that were migrated, or empty array if no
+ * migration was needed.
+ */
+export function migrateLegacyEnvKeys(p: string): string[] {
+  if (!fs.existsSync(p)) return [];
+  const original = fs.readFileSync(p, "utf-8");
+  const values = readEnvFile(p);
+  const renamed: string[] = [];
+
+  if (values.PINTA_CODEX_ENDPOINT && !values.OTEL_EXPORTER_OTLP_ENDPOINT) {
+    values.OTEL_EXPORTER_OTLP_ENDPOINT = values.PINTA_CODEX_ENDPOINT;
+    delete values.PINTA_CODEX_ENDPOINT;
+    renamed.push("PINTA_CODEX_ENDPOINT");
+  }
+  if (values.PINTA_CODEX_API_KEY && !values.OTEL_EXPORTER_OTLP_HEADERS) {
+    values.OTEL_EXPORTER_OTLP_HEADERS = `x-pinta-relay-token=${values.PINTA_CODEX_API_KEY}`;
+    delete values.PINTA_CODEX_API_KEY;
+    renamed.push("PINTA_CODEX_API_KEY");
+  }
+
+  if (renamed.length === 0) return [];
+
+  const bakPath = `${p}.bak`;
+  if (!fs.existsSync(bakPath)) {
+    fs.writeFileSync(bakPath, original, "utf-8");
+  }
+  writeEnvFile(p, values);
+  return renamed;
+}
+
+// --- TOML: minimal, targeted `[features].codex_hooks = true` toggle ---
+
+/**
+ * Ensure `[features] codex_hooks = true` is set in the TOML source.
+ * Preserves unrelated content; only touches the features section.
+ *
+ * Handles:
+ *   - no file / empty file  → append section
+ *   - no [features] section → append section
+ *   - [features] present, key missing → insert key
+ *   - key present with different value → replace value
+ *   - key already true → no change
+ */
+export function ensureCodexHooksEnabled(content: string): {
+  next: string;
+  changed: boolean;
+} {
+  const sectionHeader = /^\[features\]\s*$/m;
+  const match = content.match(sectionHeader);
+  if (!match) {
+    const sep = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+    const suffix = content.length === 0 ? "" : "\n";
+    return {
+      next: content + sep + suffix + "[features]\ncodex_hooks = true\n",
+      changed: true,
+    };
+  }
+
+  const sectionStart = match.index! + match[0].length;
+  const rest = content.slice(sectionStart);
+  const nextSection = rest.match(/\n\[[^\]]+\]\s*$/m);
+  const sectionEnd = nextSection ? sectionStart + nextSection.index! : content.length;
+  const body = content.slice(sectionStart, sectionEnd);
+
+  const keyRe = /^(\s*)codex_hooks\s*=\s*(true|false|"[^"]*"|'[^']*')\s*$/m;
+  const keyMatch = body.match(keyRe);
+  if (keyMatch) {
+    if (keyMatch[2] === "true") return { next: content, changed: false };
+    const replaced = body.replace(keyRe, `${keyMatch[1] ?? ""}codex_hooks = true`);
+    return {
+      next: content.slice(0, sectionStart) + replaced + content.slice(sectionEnd),
+      changed: true,
+    };
+  }
+
+  const sep = body.length === 0 || body.endsWith("\n") ? "" : "\n";
+  const insert = `${sep}codex_hooks = true\n`;
+  return {
+    next: content.slice(0, sectionStart) + body + insert + content.slice(sectionEnd),
+    changed: true,
+  };
+}
+
+export function isCodexHooksEnabled(content: string): boolean {
+  const sectionHeader = /^\[features\]\s*$/m;
+  const match = content.match(sectionHeader);
+  if (!match) return false;
+  const sectionStart = match.index! + match[0].length;
+  const rest = content.slice(sectionStart);
+  const nextSection = rest.match(/\n\[[^\]]+\]\s*$/m);
+  const sectionEnd = nextSection ? sectionStart + nextSection.index! : content.length;
+  const body = content.slice(sectionStart, sectionEnd);
+  const keyRe = /^\s*codex_hooks\s*=\s*(true|"true"|'true')\s*$/m;
+  return keyRe.test(body);
+}
+
+// --- hooks.json merge ---
+
+const STALE_PINTA_CODEX_RE = /\/pinta-codex(?:\/[^\s]*)?\/dist\/index\.js\b/;
+
+export function isPintaCodexEntry(cmd: HookCommand): boolean {
+  if (cmd.command.includes(PLUGIN_ENTRY)) return true;
+  return STALE_PINTA_CODEX_RE.test(cmd.command);
+}
+
+/** True when the entry points at a pinta-codex path other than the current PLUGIN_ENTRY. */
+export function isStalePintaCodexEntry(cmd: HookCommand): boolean {
+  if (cmd.command.includes(PLUGIN_ENTRY)) return false;
+  return STALE_PINTA_CODEX_RE.test(cmd.command);
+}
+
+/** Load the plugin's bundled template and resolve ${CODEX_PLUGIN_ROOT} → PLUGIN_ROOT. */
+export function loadResolvedTemplate(): HooksFile {
+  const templatePath = path.join(PLUGIN_ROOT, "hooks.json");
+  const template: HooksFile = readJson(templatePath, { hooks: {} });
+  const out: HooksFile = { hooks: {} };
+  for (const [eventName, matchers] of Object.entries(template.hooks)) {
+    out.hooks[eventName] = matchers.map((m) => ({
+      ...m,
+      hooks: m.hooks.map((h) => ({
+        ...h,
+        command: h.command.replace(/\$\{CODEX_PLUGIN_ROOT\}/g, PLUGIN_ROOT),
+      })),
+    }));
+  }
+  return out;
+}
+
+/**
+ * Merge `incoming` into `existing`, removing any prior pinta-codex entries
+ * first (both exact-path matches and stale entries from prior installs that
+ * used a different path).
+ */
+export function mergeHooks(
+  existing: HooksFile,
+  incoming: HooksFile,
+): { next: HooksFile; staleRemoved: number } {
+  const merged: HooksFile = { hooks: { ...existing.hooks } };
+  let staleRemoved = 0;
+  for (const [eventName, incomingMatchers] of Object.entries(incoming.hooks)) {
+    const current = merged.hooks[eventName] ?? [];
+    const cleaned = current
+      .map((m) => {
+        const staleBefore = m.hooks.filter((h) => isStalePintaCodexEntry(h)).length;
+        staleRemoved += staleBefore;
+        const kept = m.hooks.filter((h) => !isPintaCodexEntry(h));
+        return { ...m, hooks: kept };
+      })
+      .filter((m) => m.hooks.length > 0);
+    merged.hooks[eventName] = [...cleaned, ...incomingMatchers];
+  }
+  return { next: merged, staleRemoved };
+}
+
+export function stripPintaCodex(existing: HooksFile): {
+  next: HooksFile;
+  removed: number;
+} {
+  const cleaned: HooksFile = { hooks: {} };
+  let removed = 0;
+  for (const [eventName, matchers] of Object.entries(existing.hooks)) {
+    const next = matchers
+      .map((m) => {
+        const before = m.hooks.length;
+        const kept = m.hooks.filter((h) => !isPintaCodexEntry(h));
+        removed += before - kept.length;
+        return { ...m, hooks: kept };
+      })
+      .filter((m) => m.hooks.length > 0);
+    if (next.length > 0) cleaned.hooks[eventName] = next;
+  }
+  return { next: cleaned, removed };
+}
+
+export function countRegisteredEvents(existing: HooksFile): number {
+  let n = 0;
+  for (const matchers of Object.values(existing.hooks)) {
+    for (const m of matchers) {
+      if (m.hooks.some((h) => isPintaCodexEntry(h))) {
+        n++;
+        break;
+      }
+    }
+  }
+  return n;
+}

package/tools/doctor.ts

@@ -0,0 +1,250 @@
+/**
+ * Health check. Run when something looks off or before filing a bug.
+ *
+ *   npm run doctor
+ *
+ * Never mutates state — read-only. Exits 0 if everything is green, 1 if any
+ * check fails. Yellow warnings do not fail the exit code.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  CODEX_CONFIG_PATH,
+  CODEX_ENV_PATH,
+  CODEX_HOOKS_PATH,
+  PLUGIN_ENTRY,
+  PLUGIN_ROOT,
+  countRegisteredEvents,
+  isCodexHooksEnabled,
+  readEnvFile,
+  readJson,
+  type HooksFile,
+} from "./_lib.js";
+
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+};
+const useColor = Boolean(process.stdout.isTTY);
+const c = (code: string, s: string) => (useColor ? `${code}${s}${ANSI.reset}` : s);
+
+type Status = "pass" | "warn" | "fail";
+interface Result {
+  status: Status;
+  label: string;
+  detail?: string;
+  hint?: string;
+}
+
+const results: Result[] = [];
+function pass(label: string, detail?: string): void {
+  results.push({ status: "pass", label, detail });
+}
+function warn(label: string, detail: string, hint?: string): void {
+  results.push({ status: "warn", label, detail, hint });
+}
+function fail(label: string, detail: string, hint?: string): void {
+  results.push({ status: "fail", label, detail, hint });
+}
+
+// --- checks ---
+
+function checkDist(): void {
+  if (!fs.existsSync(PLUGIN_ENTRY)) {
+    fail("dist/index.js", "missing", "Run 'npm run build' (or 'npm run setup').");
+    return;
+  }
+  pass("dist/index.js", PLUGIN_ENTRY);
+}
+
+function checkEnv(): { endpoint?: string; headers?: string } {
+  const fromFile = readEnvFile(CODEX_ENV_PATH);
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+    ?? fromFile.OTEL_EXPORTER_OTLP_ENDPOINT
+    ?? process.env.PINTA_CODEX_ENDPOINT
+    ?? fromFile.PINTA_CODEX_ENDPOINT;
+  const headers = process.env.OTEL_EXPORTER_OTLP_HEADERS
+    ?? fromFile.OTEL_EXPORTER_OTLP_HEADERS
+    ?? (process.env.PINTA_CODEX_API_KEY
+        ? `x-pinta-relay-token=${process.env.PINTA_CODEX_API_KEY}`
+        : undefined)
+    ?? (fromFile.PINTA_CODEX_API_KEY
+        ? `x-pinta-relay-token=${fromFile.PINTA_CODEX_API_KEY}`
+        : undefined);
+
+  const usingLegacy = !!(fromFile.PINTA_CODEX_ENDPOINT || fromFile.PINTA_CODEX_API_KEY
+    || process.env.PINTA_CODEX_ENDPOINT || process.env.PINTA_CODEX_API_KEY);
+
+  if (endpoint) {
+    pass("OTLP endpoint", endpoint);
+    if (usingLegacy) {
+      warn("legacy keys", "PINTA_CODEX_* keys still in use", "Run 'npm run setup' to migrate to OTEL_EXPORTER_OTLP_* (auto-renames + writes .bak).");
+    }
+  } else {
+    fail("OTLP endpoint", "not configured", "Run 'npm run setup' or set OTEL_EXPORTER_OTLP_ENDPOINT.");
+  }
+  return { endpoint, headers };
+}
+
+function checkCodexHooksFlag(): void {
+  let content = "";
+  try {
+    content = fs.readFileSync(CODEX_CONFIG_PATH, "utf-8");
+  } catch {
+    fail(
+      "codex_hooks flag",
+      `${CODEX_CONFIG_PATH} not found`,
+      "Run 'npm run setup' to create it.",
+    );
+    return;
+  }
+  if (isCodexHooksEnabled(content)) {
+    pass("codex_hooks flag", "[features].codex_hooks = true");
+  } else {
+    fail(
+      "codex_hooks flag",
+      "not enabled in config.toml",
+      "Add [features] codex_hooks = true, or run 'npm run setup'.",
+    );
+  }
+}
+
+function checkHooksRegistered(): void {
+  if (!fs.existsSync(CODEX_HOOKS_PATH)) {
+    fail(
+      "hooks.json",
+      `${CODEX_HOOKS_PATH} not found`,
+      "Run 'npm run install-hooks' (or 'npm run setup').",
+    );
+    return;
+  }
+  const existing: HooksFile = readJson(CODEX_HOOKS_PATH, { hooks: {} });
+  const registered = countRegisteredEvents(existing);
+  if (registered === 0) {
+    fail(
+      "hooks.json",
+      "no pinta-codex entries",
+      "Run 'npm run install-hooks'.",
+    );
+    return;
+  }
+  pass("hooks.json", `${registered} event(s) registered`);
+
+  for (const [eventName, matchers] of Object.entries(existing.hooks)) {
+    for (const m of matchers) {
+      for (const h of m.hooks) {
+        if (!h.command.includes(PLUGIN_ENTRY)) continue;
+        // Extract the file path from `node <abs-path>` and verify it exists.
+        const parts = h.command.split(/\s+/);
+        const script = parts[parts.length - 1];
+        if (!fs.existsSync(script)) {
+          warn(
+            `hooks.json:${eventName}`,
+            `command references missing file: ${script}`,
+            "Plugin may have moved — run 'npm run install-hooks' from the current location.",
+          );
+        }
+      }
+    }
+  }
+}
+
+async function checkEndpointReachability(endpoint?: string): Promise<void> {
+  if (!endpoint) {
+    warn("endpoint reachability", "skipped (no endpoint configured)");
+    return;
+  }
+  const url = `${endpoint.replace(/\/+$/, "")}/traces`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  try {
+    // HEAD /traces commonly returns 404 or 405 on POST-only backends (e.g.
+    // Fastify won't auto-register HEAD for a POST route and falls through to
+    // 404). Any HTTP response proves the host is reachable; we only fail on
+    // transport-level errors (DNS, connect, TLS, timeout).
+    const res = await fetch(url, { method: "HEAD", signal: controller.signal });
+    pass("endpoint reachability", `${url} → HTTP ${res.status}`);
+  } catch (err) {
+    fail(
+      "endpoint reachability",
+      `cannot reach ${url}: ${err instanceof Error ? err.message : String(err)}`,
+      "Check network / VPN / OTEL_EXPORTER_OTLP_ENDPOINT value.",
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function checkRetryQueue(): void {
+  const pluginData = process.env.CODEX_PLUGIN_DATA || path.join(PLUGIN_ROOT, ".plugin-data");
+  const queuePath = path.join(pluginData, "failed-spans.jsonl");
+  if (!fs.existsSync(queuePath)) {
+    pass("retry queue", "empty");
+    return;
+  }
+  const content = fs.readFileSync(queuePath, "utf-8");
+  const lines = content.split("\n").filter((l) => l.trim().length > 0).length;
+  if (lines === 0) {
+    pass("retry queue", "empty");
+  } else if (lines < 100) {
+    pass("retry queue", `${lines} pending`);
+  } else if (lines < 1000) {
+    warn(
+      "retry queue",
+      `${lines} pending entries`,
+      "Large backlog — next hook will try to drain. Check endpoint reachability.",
+    );
+  } else {
+    fail(
+      "retry queue",
+      `${lines} entries (cap 1000)`,
+      "Queue is full. Drops will occur. Fix transport then wait for flush.",
+    );
+  }
+}
+
+// --- reporter ---
+
+function printResults(): number {
+  process.stdout.write(c(ANSI.bold, "\nPinta Codex — health check\n\n"));
+  let failed = 0;
+  for (const r of results) {
+    const glyph = r.status === "pass"
+      ? c(ANSI.green, "✔")
+      : r.status === "warn"
+      ? c(ANSI.yellow, "!")
+      : c(ANSI.red, "✘");
+    const label = c(ANSI.bold, r.label.padEnd(24));
+    const detail = r.detail ? c(ANSI.dim, r.detail) : "";
+    process.stdout.write(`  ${glyph}  ${label}${detail}\n`);
+    if (r.hint) {
+      process.stdout.write(`      ${c(ANSI.cyan, "→ " + r.hint)}\n`);
+    }
+    if (r.status === "fail") failed++;
+  }
+  const summary = failed === 0
+    ? c(ANSI.green, "\nAll checks passed.\n")
+    : c(ANSI.red, `\n${failed} check(s) failed.\n`);
+  process.stdout.write(summary);
+  return failed === 0 ? 0 : 1;
+}
+
+// --- main ---
+
+async function main(): Promise<void> {
+  checkDist();
+  const { endpoint } = checkEnv();
+  checkCodexHooksFlag();
+  checkHooksRegistered();
+  await checkEndpointReachability(endpoint);
+  checkRetryQueue();
+  process.exit(printResults());
+}
+
+main();

package/tools/install-hooks.ts

@@ -0,0 +1,71 @@
+/**
+ * Merge this plugin's hooks into `~/.codex/hooks.json` with the plugin's
+ * absolute path baked in.
+ *
+ * See `tools/_lib.ts` for the heavy lifting. For the rationale, see README.md
+ * (section "Install") and doctor's "hooks.json" check.
+ *
+ * Usage:
+ *   npx tsx tools/install-hooks.ts              # merge into ~/.codex/hooks.json
+ *   npx tsx tools/install-hooks.ts --dry-run    # print the final file, don't write
+ *   CODEX_HOME=/abs/path npx tsx tools/install-hooks.ts
+ */
+
+import fs from "node:fs";
+import {
+  CODEX_HOME,
+  CODEX_HOOKS_PATH,
+  PLUGIN_ENTRY,
+  loadResolvedTemplate,
+  mergeHooks,
+  readJson,
+  type HooksFile,
+} from "./_lib.js";
+
+const dryRun = process.argv.includes("--dry-run");
+
+function main(): void {
+  if (!fs.existsSync(PLUGIN_ENTRY)) {
+    process.stderr.write(
+      `[install-hooks] plugin entry missing: ${PLUGIN_ENTRY}\n` +
+        `  Run 'npm run build' before installing hooks.\n`,
+    );
+    process.exit(1);
+  }
+
+  const incoming = loadResolvedTemplate();
+  const existing: HooksFile = readJson(CODEX_HOOKS_PATH, { hooks: {} });
+  const { next: merged, staleRemoved } = mergeHooks(existing, incoming);
+  const serialized = JSON.stringify(merged, null, 2) + "\n";
+
+  if (dryRun) {
+    process.stdout.write(`--- ${CODEX_HOOKS_PATH} (dry run) ---\n`);
+    process.stdout.write(serialized);
+    return;
+  }
+
+  const previous = fs.existsSync(CODEX_HOOKS_PATH)
+    ? fs.readFileSync(CODEX_HOOKS_PATH, "utf-8")
+    : null;
+
+  if (previous === serialized) {
+    process.stdout.write(`[install-hooks] already up to date: ${CODEX_HOOKS_PATH}\n`);
+    process.stdout.write(`[install-hooks] plugin entry: ${PLUGIN_ENTRY}\n`);
+    return;
+  }
+
+  fs.mkdirSync(CODEX_HOME, { recursive: true });
+  fs.writeFileSync(CODEX_HOOKS_PATH, serialized, "utf-8");
+  if (staleRemoved > 0) {
+    process.stdout.write(
+      `[install-hooks] removed ${staleRemoved} stale pinta-codex ` +
+        `${staleRemoved === 1 ? "entry" : "entries"} (prior install at a different path)\n`,
+    );
+  }
+  process.stdout.write(
+    `[install-hooks] ${previous === null ? "created" : "updated"} ${CODEX_HOOKS_PATH}\n`,
+  );
+  process.stdout.write(`[install-hooks] plugin entry: ${PLUGIN_ENTRY}\n`);
+}
+
+main();