@pinta-ai/pinta-codex 1.2.0

package/tools/setup.ts

@@ -0,0 +1,288 @@
+/**
+ * One-shot installer for end users.
+ *
+ *   npm install && npm run setup
+ *
+ * Does everything a user needs in a single interactive command:
+ *   1. Builds dist/  (runs tsc if dist/index.js missing or --rebuild)
+ *   2. Prompts for OTLP endpoint & headers (migrates legacy keys if present)
+ *   3. Writes them to ~/.codex/pinta-codex.env
+ *   4. Enables `codex_hooks = true` in ~/.codex/config.toml (idempotent)
+ *   5. Merges this plugin's hooks into ~/.codex/hooks.json with absolute paths
+ *   6. Prints a summary of what to run next
+ *
+ * Safe to re-run. Each step is idempotent.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import readline from "node:readline";
+import { stdin, stdout } from "node:process";
+import {
+  CODEX_CONFIG_PATH,
+  CODEX_ENV_PATH,
+  CODEX_HOME,
+  CODEX_HOOKS_PATH,
+  PLUGIN_ENTRY,
+  PLUGIN_ROOT,
+  ensureCodexHooksEnabled,
+  loadResolvedTemplate,
+  mergeHooks,
+  migrateLegacyEnvKeys,
+  readEnvFile,
+  readJson,
+  writeEnvFile,
+  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",
+};
+
+function tty(): boolean {
+  return Boolean(stdout.isTTY);
+}
+function ok(msg: string): void {
+  const mark = tty() ? `${ANSI.green}✔${ANSI.reset}` : "OK";
+  stdout.write(`  ${mark}  ${msg}\n`);
+}
+function info(msg: string): void {
+  const mark = tty() ? `${ANSI.cyan}ℹ${ANSI.reset}` : "--";
+  stdout.write(`  ${mark}  ${msg}\n`);
+}
+function heading(title: string): void {
+  stdout.write(
+    tty() ? `\n${ANSI.bold}${title}${ANSI.reset}\n` : `\n## ${title}\n`,
+  );
+}
+
+// --- steps ---
+
+async function stepBuild(): Promise<void> {
+  heading("1. Build dist/");
+  const rebuild = process.argv.includes("--rebuild");
+  if (fs.existsSync(PLUGIN_ENTRY) && !rebuild) {
+    ok(`dist/index.js already present (pass --rebuild to force)`);
+    return;
+  }
+  info("running tsc...");
+  const result = spawnSync("npm", ["run", "build"], {
+    cwd: PLUGIN_ROOT,
+    stdio: "inherit",
+  });
+  if (result.status !== 0) {
+    stderrFail(`tsc failed with exit ${result.status}`);
+  }
+  ok(`built ${PLUGIN_ENTRY}`);
+}
+
+async function stepEnv(ask: AskFn): Promise<{ endpoint: string; headers: string }> {
+  heading("2. OTLP endpoint & headers");
+
+  // Migrate legacy keys to OTel-spec naming (writes .bak if migration occurs)
+  const renamed = migrateLegacyEnvKeys(CODEX_ENV_PATH);
+  for (const key of renamed) {
+    info(`migrated legacy key ${key} → OTel-spec name (.bak written)`);
+  }
+
+  const existingFile = readEnvFile(CODEX_ENV_PATH);
+  const currentEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+    ?? existingFile.OTEL_EXPORTER_OTLP_ENDPOINT
+    ?? "http://localhost:4318";
+  const currentHeaders = process.env.OTEL_EXPORTER_OTLP_HEADERS
+    ?? existingFile.OTEL_EXPORTER_OTLP_HEADERS
+    ?? "";
+
+  const endpoint = await ask("OTLP endpoint URL", currentEndpoint, {
+    validate: (v) => /^https?:\/\//.test(v) ? null : "must start with http:// or https://",
+  });
+  const headers = await ask("OTLP headers (key1=val1,key2=val2; blank if none)", currentHeaders, {
+    mask: true,
+    optional: true,
+  });
+
+  const merged: Record<string, string> = {
+    ...existingFile,
+    OTEL_EXPORTER_OTLP_ENDPOINT: endpoint,
+  };
+  if (headers) {
+    merged.OTEL_EXPORTER_OTLP_HEADERS = headers;
+  } else {
+    delete merged.OTEL_EXPORTER_OTLP_HEADERS;
+  }
+  writeEnvFile(CODEX_ENV_PATH, merged);
+  ok(`wrote ${CODEX_ENV_PATH}`);
+  return { endpoint, headers };
+}
+
+async function stepConfigToml(): Promise<void> {
+  heading("3. Enable codex_hooks feature");
+  let current = "";
+  try {
+    current = fs.readFileSync(CODEX_CONFIG_PATH, "utf-8");
+  } catch {
+    // file may not exist yet
+  }
+  const { next, changed } = ensureCodexHooksEnabled(current);
+  if (!changed) {
+    ok(`codex_hooks already enabled in ${CODEX_CONFIG_PATH}`);
+    return;
+  }
+  fs.mkdirSync(CODEX_HOME, { recursive: true });
+  fs.writeFileSync(CODEX_CONFIG_PATH, next, "utf-8");
+  ok(`updated ${CODEX_CONFIG_PATH}`);
+}
+
+async function stepHooks(): Promise<void> {
+  heading("4. Register hooks");
+  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";
+  const previous = fs.existsSync(CODEX_HOOKS_PATH)
+    ? fs.readFileSync(CODEX_HOOKS_PATH, "utf-8")
+    : null;
+  if (previous === serialized) {
+    ok(`${Object.keys(incoming.hooks).length} event(s) already registered in ${CODEX_HOOKS_PATH}`);
+    return;
+  }
+  fs.mkdirSync(CODEX_HOME, { recursive: true });
+  fs.writeFileSync(CODEX_HOOKS_PATH, serialized, "utf-8");
+  if (staleRemoved > 0) {
+    ok(`removed ${staleRemoved} stale pinta-codex ${staleRemoved === 1 ? "entry" : "entries"} (prior install at a different path)`);
+  }
+  ok(`wrote ${Object.keys(incoming.hooks).length} event(s) to ${CODEX_HOOKS_PATH}`);
+}
+
+async function stepSummary(endpoint: string): Promise<void> {
+  heading("Done");
+  stdout.write(
+    `  Run Codex to start streaming events:\n` +
+      `    ${tty() ? ANSI.bold : ""}codex${tty() ? ANSI.reset : ""}\n` +
+      `\n  Useful:\n` +
+      `    npm run doctor          # health check\n` +
+      `    npm run uninstall-hooks # remove this plugin's entries\n` +
+      `\n  Endpoint: ${endpoint}\n` +
+      `  Env file: ${CODEX_ENV_PATH}\n` +
+      `  Hooks:    ${CODEX_HOOKS_PATH}\n`,
+  );
+}
+
+// --- helpers ---
+
+function stderrFail(msg: string): never {
+  process.stderr.write(`[setup] ${msg}\n`);
+  process.exit(1);
+}
+
+interface PromptOpts {
+  mask?: boolean;
+  optional?: boolean;
+  validate?: (v: string) => string | null;
+}
+
+type AskFn = (label: string, defaultValue: string, opts?: PromptOpts) => Promise<string>;
+
+/**
+ * Build an ask() function that works in two modes:
+ *   - TTY: classic readline prompt loop with validation retries.
+ *   - Piped stdin (non-TTY): read all stdin upfront, consume one line per
+ *     question. We cannot retry a rejected value because there's no more input
+ *     — rejections throw instead.
+ *
+ * Why the split: node:readline/promises' `rl.question` hangs on the 2nd call
+ * when stdin is piped, making an interactive-only implementation unusable for
+ * scripted/CI setup runs.
+ */
+function buildAsk(): AskFn {
+  if (stdin.isTTY) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    const question = (prompt: string): Promise<string> =>
+      new Promise((resolve) => rl.question(prompt, resolve));
+    const ask: AskFn = async (label, defaultValue, opts = {}) => {
+      const shown = opts.mask && defaultValue ? "***" : defaultValue;
+      const suffix = defaultValue ? ` [${shown}]` : "";
+      while (true) {
+        const answer = (await question(`  ${label}${suffix}: `)).trim();
+        const value = answer === "" ? defaultValue : answer;
+        if (!value && !opts.optional) {
+          stdout.write(`    (required)\n`);
+          continue;
+        }
+        const err = opts.validate?.(value);
+        if (err) {
+          stdout.write(`    ${tty() ? ANSI.red : ""}${err}${tty() ? ANSI.reset : ""}\n`);
+          continue;
+        }
+        return value;
+      }
+    };
+    (ask as AskFn & { close: () => void }).close = () => rl.close();
+    return ask;
+  }
+
+  // Non-TTY: slurp all lines eagerly.
+  const lines: string[] = [];
+  let drained = false;
+  let pending: Array<() => void> = [];
+  const drain = (chunk: Buffer | string): void => {
+    const text = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    for (const raw of text.split("\n")) lines.push(raw);
+    // Split leaves a trailing empty element if input ended with \n; keep it
+    // because it's a legitimate "user pressed enter with nothing" answer.
+  };
+  stdin.on("data", drain);
+  stdin.once("end", () => {
+    drained = true;
+    const waiters = pending;
+    pending = [];
+    for (const w of waiters) w();
+  });
+
+  const waitForDrain = (): Promise<void> =>
+    drained ? Promise.resolve() : new Promise((resolve) => pending.push(resolve));
+
+  const ask: AskFn = async (label, defaultValue, opts = {}) => {
+    await waitForDrain();
+    const raw = lines.shift();
+    const answer = (raw ?? "").trim();
+    const value = answer === "" ? defaultValue : answer;
+    if (!value && !opts.optional) {
+      throw new Error(`${label}: required (stdin exhausted).`);
+    }
+    const err = opts.validate?.(value);
+    if (err) {
+      throw new Error(`${label}: ${err}`);
+    }
+    return value;
+  };
+  return ask;
+}
+
+// --- main ---
+
+async function main(): Promise<void> {
+  stdout.write(
+    tty()
+      ? `\n${ANSI.bold}Pinta Codex — one-shot setup${ANSI.reset}\n`
+      : `\nPinta Codex — one-shot setup\n`,
+  );
+  const ask = buildAsk();
+  try {
+    await stepBuild();
+    const { endpoint } = await stepEnv(ask);
+    await stepConfigToml();
+    await stepHooks();
+    await stepSummary(endpoint);
+  } finally {
+    (ask as AskFn & { close?: () => void }).close?.();
+  }
+}
+
+main().catch((err) => stderrFail(err instanceof Error ? err.message : String(err)));

package/tools/test-otlp.ts

@@ -0,0 +1,58 @@
+import { strict as assert } from 'node:assert';
+import { buildOtlpPayload } from '../src/core/otlp.js';
+
+let failures = 0;
+function check(name: string, fn: () => void): void {
+  try {
+    fn();
+    process.stdout.write(`  ok  ${name}\n`);
+  } catch (err) {
+    failures++;
+    process.stdout.write(`  FAIL ${name}\n    ${err instanceof Error ? err.message : err}\n`);
+  }
+}
+
+check('flattenEvent emits ingest.type=codex as first attribute', () => {
+  const payload = buildOtlpPayload({
+    event: {
+      hook_event_name: 'UserPromptSubmit',
+      session_id: 's1',
+      transcript_path: '/tmp/t',
+      cwd: '/home/u',
+      prompt: 'hi',
+    },
+    traceId: '01ARZ3NDEKTSV4RRFFQ69G5FAV',
+    now: 1700000000000,
+  });
+  const attrs = payload.resourceSpans[0].scopeSpans[0].spans[0].attributes;
+  assert.equal(attrs[0].key, 'ingest.type', `expected first attr to be ingest.type, got ${attrs[0].key}`);
+  assert.deepEqual(attrs[0].value, { stringValue: 'codex' });
+  assert.equal(attrs[1].key, 'codex.hook', `expected second attr to be codex.hook, got ${attrs[1].key}`);
+});
+
+check('flattenEvent still emits codex.hook and other codex.* attrs', () => {
+  const payload = buildOtlpPayload({
+    event: {
+      hook_event_name: 'PreToolUse',
+      session_id: 's1',
+      transcript_path: '/tmp/t',
+      cwd: '/home/u',
+      tool_name: 'Bash',
+      tool_input: { command: 'ls' },
+      tool_use_id: 'tu1',
+    },
+    traceId: '01ARZ3NDEKTSV4RRFFQ69G5FAV',
+    now: 1700000000000,
+  });
+  const attrs = payload.resourceSpans[0].scopeSpans[0].spans[0].attributes;
+  const keys = attrs.map((a: { key: string }) => a.key);
+  assert.ok(keys.includes('codex.hook'), `missing codex.hook; keys=${keys.join(',')}`);
+  assert.ok(keys.includes('codex.tool_name'), `missing codex.tool_name; keys=${keys.join(',')}`);
+  assert.ok(keys.includes('codex.tool_use_id'), `missing codex.tool_use_id; keys=${keys.join(',')}`);
+});
+
+if (failures > 0) {
+  process.stdout.write(`\n${failures} failure(s)\n`);
+  process.exit(1);
+}
+process.stdout.write('\nOK\n');

package/tools/test-redact.ts

@@ -0,0 +1,286 @@
+import { strict as assert } from "node:assert";
+import {
+  truncate,
+  redact,
+  MAX_BYTES,
+  PATTERNS,
+  collectMatches,
+  resolveOverlaps,
+  applyMatches,
+} from "../src/core/redact.js";
+
+let failures = 0;
+function check(name: string, fn: () => void): void {
+  try {
+    fn();
+    process.stdout.write(`  ok  ${name}\n`);
+  } catch (err) {
+    failures++;
+    process.stdout.write(`  FAIL ${name}\n    ${err instanceof Error ? err.message : err}\n`);
+  }
+}
+
+// --- truncate ---
+check("truncate: short input passes through", () => {
+  assert.equal(truncate("hello"), "hello");
+});
+
+check("truncate: long input is cut and tagged", () => {
+  const input = "a".repeat(MAX_BYTES + 100);
+  const out = truncate(input);
+  assert.equal(out.startsWith("a".repeat(MAX_BYTES)), true);
+  const headBytes = Buffer.from(out.split("…[TRUNCATED:")[0], "utf-8").length;
+  assert.equal(headBytes, MAX_BYTES, `head should be exactly MAX_BYTES, got ${headBytes}`);
+  assert.match(out, new RegExp(`…\\[TRUNCATED:${MAX_BYTES + 100}\\]$`));
+});
+
+check("truncate: input exactly at cap passes through", () => {
+  const input = "a".repeat(MAX_BYTES);
+  assert.equal(truncate(input), input);
+});
+
+check("truncate: counts bytes not codepoints (multibyte char)", () => {
+  // "한" is 3 bytes UTF-8. With a tiny synthetic cap we can't override MAX_BYTES,
+  // so verify the byte-aware byte count by ensuring a 100KB+ multibyte string
+  // is truncated and the original byte length appears in the tag.
+  const oneChar = "한"; // 3 bytes
+  const charsToExceed = Math.ceil(MAX_BYTES / 3) + 10;
+  const input = oneChar.repeat(charsToExceed);
+  const origBytes = Buffer.from(input, "utf-8").length;
+  const out = truncate(input);
+  const headBytes = Buffer.from(out.split("…[TRUNCATED:")[0], "utf-8").length;
+  // After slicing on a byte boundary, toString("utf-8") replaces any partial
+  // codepoint at the tail with U+FFFD (3 bytes), so headBytes may be up to
+  // MAX_BYTES + 2 when the boundary lands mid-codepoint. Allow for that.
+  assert.ok(headBytes <= MAX_BYTES + 2, `head exceeds MAX_BYTES+2: ${headBytes}`);
+  assert.match(out, new RegExp(`…\\[TRUNCATED:${origBytes}\\]$`));
+});
+
+interface PatternCase {
+  type: string;
+  input: string;
+  /** Substring(s) the *output* must contain. */
+  expectContains: string[];
+  /** Substring(s) the *output* must NOT contain (typically the original secret). */
+  expectMissing?: string[];
+  context?: "bash";
+}
+
+function applySinglePattern(input: string, type: string): string {
+  // Direct application of a single pattern's matches via the same algorithm
+  // redact() will use. We re-run regex here without the full pipeline so a
+  // pattern test fails when the regex is wrong, not when resolution is wrong.
+  const pattern = PATTERNS.find((x) => x.type === type);
+  if (!pattern) throw new Error(`no PATTERN with type=${type}`);
+  const re = new RegExp(pattern.regex.source, pattern.regex.flags);
+  let out = "";
+  let last = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(input)) !== null) {
+    const cg = pattern.captureGroup ?? 0;
+    const captured = m[cg];
+    if (captured === undefined) continue;
+    const captureStart = m.index + m[0].indexOf(captured);
+    const captureEnd = captureStart + captured.length;
+    out += input.slice(last, captureStart) + `[REDACTED:${pattern.type}]`;
+    last = captureEnd;
+    if (m.index === re.lastIndex) re.lastIndex++; // zero-length guard
+  }
+  out += input.slice(last);
+  return out;
+}
+
+const PATTERN_CASES: PatternCase[] = [
+  {
+    type: "aws_access_key",
+    input: "key=AKIAIOSFODNN7EXAMPLE end",
+    expectContains: ["[REDACTED:aws_access_key]"],
+    expectMissing: ["AKIAIOSFODNN7EXAMPLE"],
+  },
+  {
+    type: "aws_secret_key",
+    input: "AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+    expectContains: ["[REDACTED:aws_secret_key]"],
+    expectMissing: ["wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"],
+  },
+  {
+    type: "gcp_service_account",
+    input: '{"type":"service_account","project_id":"foo","private_key":"-----BEGIN PRIVATE KEY-----\\nABC\\n-----END PRIVATE KEY-----"}',
+    expectContains: ["[REDACTED:gcp_service_account]"],
+    expectMissing: ['"project_id":"foo"', "BEGIN PRIVATE KEY"],
+  },
+  {
+    type: "github_token",
+    input: "token=ghp_abcdefghijklmnopqrstuvwxyz0123456789AB end",
+    expectContains: ["[REDACTED:github_token]"],
+    expectMissing: ["ghp_abcdefghijklmnopqrstuvwxyz0123456789AB"],
+  },
+  {
+    type: "gitlab_token",
+    input: "GitLab: glpat-abcdefghijklmno12345",
+    expectContains: ["[REDACTED:gitlab_token]"],
+  },
+  {
+    type: "slack_token",
+    input: "xoxb-1234567890-abcdef0123456789",
+    expectContains: ["[REDACTED:slack_token]"],
+  },
+  {
+    type: "openai_key",
+    input: "OpenAI: sk-proj-abcdefghij0123456789ABCDEFGHIJ0123456789klmn",
+    expectContains: ["[REDACTED:openai_key]"],
+  },
+  {
+    type: "anthropic_key",
+    input: "Key: sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKL_-",
+    expectContains: ["[REDACTED:anthropic_key]"],
+  },
+  {
+    type: "stripe_key",
+    input: "stripe sk_live_abcdefghijklmnop0123456789",
+    expectContains: ["[REDACTED:stripe_key]"],
+  },
+  {
+    type: "jwt",
+    input: "Token eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJqb2huIn0.abc123def456ghi789jkl",
+    expectContains: ["[REDACTED:jwt]"],
+  },
+  {
+    type: "private_key_block",
+    input: "-----BEGIN RSA PRIVATE KEY-----\nMIIBOgIBAAJBAKj34GkxF...\n-----END RSA PRIVATE KEY-----",
+    expectContains: ["[REDACTED:private_key_block]"],
+    expectMissing: ["MIIBOgIBAAJBAKj34GkxF"],
+  },
+  {
+    type: "bearer_token",
+    input: "Authorization: Bearer abc123def456ghi789",
+    expectContains: ["Bearer [REDACTED:bearer_token]"],
+    expectMissing: ["abc123def456ghi789"],
+  },
+  {
+    type: "basic_auth",
+    input: "Authorization: Basic dXNlcjpwYXNzd29yZA==",
+    expectContains: ["Basic [REDACTED:basic_auth]"],
+  },
+  {
+    type: "db_url_password",
+    input: "DATABASE_URL=postgres://app:s3cret!@db:5432/foo",
+    expectContains: ["postgres://app:[REDACTED:db_url_password]@db:5432/foo"],
+    expectMissing: ["s3cret!"],
+  },
+  {
+    type: "cli_password_flag",
+    input: "mysql --password=hunter2 mydb",
+    expectContains: ["[REDACTED:cli_password_flag]"],
+    expectMissing: ["hunter2"],
+  },
+  {
+    type: "cli_password_short",
+    input: "mysql -phunter2 mydb",
+    expectContains: ["[REDACTED:cli_password_short]"],
+    expectMissing: ["hunter2"],
+    context: "bash",
+  },
+  {
+    type: "env_var_secret",
+    input: "OPENAI_API_KEY=sk-abc123def456",
+    expectContains: ["OPENAI_API_KEY=[REDACTED:env_var_secret]"],
+    expectMissing: ["sk-abc123def456"],
+  },
+];
+
+for (const tc of PATTERN_CASES) {
+  check(`pattern ${tc.type}`, () => {
+    const out = applySinglePattern(tc.input, tc.type);
+    for (const c of tc.expectContains) {
+      assert.ok(out.includes(c), `expected output to contain "${c}"; got: ${out}`);
+    }
+    for (const m of tc.expectMissing ?? []) {
+      assert.ok(!out.includes(m), `expected output to NOT contain "${m}"; got: ${out}`);
+    }
+  });
+}
+
+function pipeline(input: string, opts: { context?: "bash" } = {}): string {
+  const all = collectMatches(input, opts);
+  const kept = resolveOverlaps(all);
+  return applyMatches(input, kept);
+}
+
+check("overlap: bearer absorbs github_token inside it", () => {
+  const input = "Authorization: Bearer ghp_abcdefghijklmnopqrstuvwxyz0123456789AB";
+  const out = pipeline(input);
+  assert.ok(out.includes("Bearer [REDACTED:bearer_token]"), out);
+  assert.ok(!out.includes("[REDACTED:github_token]"), out);
+});
+
+check("overlap: env_var_secret wins over openai_key when capture spans key", () => {
+  const input = "OPENAI_API_KEY=sk-proj-abcdefghij0123456789ABCDEFGHIJ0123456789klmn";
+  const out = pipeline(input);
+  // env_var_secret has a wider whole-match (starts at OPENAI_API_KEY, ends at value end),
+  // so it wins under the start-asc / longest-on-tie rule.
+  assert.ok(out.includes("OPENAI_API_KEY=[REDACTED:env_var_secret]"), out);
+  assert.ok(!out.includes("[REDACTED:openai_key]"), out);
+});
+
+check("ordering: independent matches both applied", () => {
+  const input = "first AKIAIOSFODNN7EXAMPLE then ghp_abcdefghijklmnopqrstuvwxyz0123456789AB";
+  const out = pipeline(input);
+  assert.ok(out.includes("[REDACTED:aws_access_key]"), out);
+  assert.ok(out.includes("[REDACTED:github_token]"), out);
+});
+
+check("context guard: cli_password_short ignored without context", () => {
+  const input = "mysql -phunter2 mydb";
+  const out = pipeline(input); // no context
+  assert.equal(out.includes("[REDACTED:cli_password_short]"), false);
+});
+
+check("context guard: cli_password_short applied with bash context", () => {
+  const input = "mysql -phunter2 mydb";
+  const out = pipeline(input, { context: "bash" });
+  assert.ok(out.includes("[REDACTED:cli_password_short]"), out);
+});
+
+check("redact: empty string passes through", () => {
+  assert.equal(redact("", {}), "");
+});
+
+check("redact: combines multiple secrets", () => {
+  const input = "AKIAIOSFODNN7EXAMPLE and ghp_abcdefghijklmnopqrstuvwxyz0123456789AB";
+  const out = redact(input);
+  assert.ok(out.includes("[REDACTED:aws_access_key]"), out);
+  assert.ok(out.includes("[REDACTED:github_token]"), out);
+});
+
+// --- negative (false-positive guards) ---
+check("negative: 40-byte commit SHA ignored", () => {
+  const input = "commit 0123456789abcdef0123456789abcdef01234567 by alice";
+  assert.equal(redact(input), input);
+});
+
+check("negative: UUID ignored", () => {
+  const input = "uuid=550e8400-e29b-41d4-a716-446655440000 done";
+  assert.equal(redact(input), input);
+});
+
+check("negative: random base64 thumbnail not masked (no context)", () => {
+  const input = "thumb=YWJjZGVmZ2hpamtsbW5vcA== loaded";
+  assert.equal(redact(input), input);
+});
+
+check("negative: 40-char base64 alone (no aws_secret context) ignored", () => {
+  const input = "blob=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY end";
+  assert.equal(redact(input), input);
+});
+
+check("negative: dash-p in normal text without bash context ignored", () => {
+  const input = "see also -pretty option";
+  assert.equal(redact(input), input);
+});
+
+if (failures > 0) {
+  process.stdout.write(`\n${failures} failure(s)\n`);
+  process.exit(1);
+}
+process.stdout.write("\nOK\n");

package/tools/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "types": ["node"],
+    "lib": ["ES2022"],
+    "noEmit": true
+  },
+  "include": ["./**/*.ts"]
+}

package/tools/uninstall-hooks.ts

@@ -0,0 +1,39 @@
+/**
+ * Remove this plugin's entries from `~/.codex/hooks.json`.
+ *
+ * Matches entries whose `command` references this plugin's dist/index.js
+ * absolute path. Other users' hook entries are left untouched.
+ */
+
+import fs from "node:fs";
+import {
+  CODEX_HOOKS_PATH,
+  readJson,
+  stripPintaCodex,
+  type HooksFile,
+} from "./_lib.js";
+
+const dryRun = process.argv.includes("--dry-run");
+
+function main(): void {
+  if (!fs.existsSync(CODEX_HOOKS_PATH)) {
+    process.stdout.write(`[uninstall-hooks] nothing to do: ${CODEX_HOOKS_PATH} does not exist\n`);
+    return;
+  }
+  const existing: HooksFile = readJson(CODEX_HOOKS_PATH, { hooks: {} });
+  const { next, removed } = stripPintaCodex(existing);
+  const serialized = JSON.stringify(next, null, 2) + "\n";
+
+  if (dryRun) {
+    process.stdout.write(
+      `--- ${CODEX_HOOKS_PATH} (dry run, ${removed} entries would be removed) ---\n`,
+    );
+    process.stdout.write(serialized);
+    return;
+  }
+
+  fs.writeFileSync(CODEX_HOOKS_PATH, serialized, "utf-8");
+  process.stdout.write(`[uninstall-hooks] removed ${removed} entries from ${CODEX_HOOKS_PATH}\n`);
+}
+
+main();