vibe-code-explainer 0.3.4 → 0.3.5

package/dist/chunk-GEAH6PTG.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+// src/cli/flags.ts
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx !== -1) {
+        const name = arg.slice(2, eqIdx);
+        const value = arg.slice(eqIdx + 1);
+        flags[name] = value;
+      } else {
+        flags[arg.slice(2)] = true;
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const name = arg.slice(1);
+      flags[name] = true;
+    } else {
+      positional.push(arg);
+    }
+    i++;
+  }
+  return { flags, positional };
+}
+function flagBool(flags, ...names) {
+  return names.some((n) => flags[n] === true || flags[n] !== void 0);
+}
+
+export {
+  parseFlags,
+  flagBool
+};
+//# sourceMappingURL=chunk-GEAH6PTG.js.map

package/dist/chunk-GEAH6PTG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/flags.ts"],"sourcesContent":["/**\n * Hand-rolled CLI flag parser — no library dependency.\n *\n * Supports:\n *   --flag          boolean flag (value: true)\n *   --flag=value    string flag\n *   --flag value    string flag (next positional arg is consumed as value)\n *\n * Returns:\n *   flags    — Record of flag name → string | true\n *   positional — remaining args that are not flags or flag values\n */\nexport interface ParsedFlags {\n  flags: Record<string, string | true>;\n  positional: string[];\n}\n\nexport function parseFlags(args: string[]): ParsedFlags {\n  const flags: Record<string, string | true> = {};\n  const positional: string[] = [];\n\n  let i = 0;\n  while (i < args.length) {\n    const arg = args[i];\n\n    if (arg.startsWith(\"--\")) {\n      const eqIdx = arg.indexOf(\"=\");\n      if (eqIdx !== -1) {\n        // --flag=value  (only this form captures a string value)\n        const name = arg.slice(2, eqIdx);\n        const value = arg.slice(eqIdx + 1);\n        flags[name] = value;\n      } else {\n        // --flag  (always boolean; no peek-consume to avoid positional ambiguity)\n        flags[arg.slice(2)] = true;\n      }\n    } else if (arg.startsWith(\"-\") && arg.length === 2) {\n      // Short flags: -j, -y\n      const name = arg.slice(1);\n      flags[name] = true;\n    } else {\n      positional.push(arg);\n    }\n\n    i++;\n  }\n\n  return { flags, positional };\n}\n\nexport function flagBool(flags: Record<string, string | true>, ...names: string[]): boolean {\n  return names.some((n) => flags[n] === true || flags[n] !== undefined);\n}\n\nexport function flagString(\n  flags: Record<string, string | true>,\n  name: string\n): string | undefined {\n  const v = flags[name];\n  return typeof v === \"string\" ? v : undefined;\n}\n"],"mappings":";;;AAiBO,SAAS,WAAW,MAA6B;AACtD,QAAM,QAAuC,CAAC;AAC9C,QAAM,aAAuB,CAAC;AAE9B,MAAI,IAAI;AACR,SAAO,IAAI,KAAK,QAAQ;AACtB,UAAM,MAAM,KAAK,CAAC;AAElB,QAAI,IAAI,WAAW,IAAI,GAAG;AACxB,YAAM,QAAQ,IAAI,QAAQ,GAAG;AAC7B,UAAI,UAAU,IAAI;AAEhB,cAAM,OAAO,IAAI,MAAM,GAAG,KAAK;AAC/B,cAAM,QAAQ,IAAI,MAAM,QAAQ,CAAC;AACjC,cAAM,IAAI,IAAI;AAAA,MAChB,OAAO;AAEL,cAAM,IAAI,MAAM,CAAC,CAAC,IAAI;AAAA,MACxB;AAAA,IACF,WAAW,IAAI,WAAW,GAAG,KAAK,IAAI,WAAW,GAAG;AAElD,YAAM,OAAO,IAAI,MAAM,CAAC;AACxB,YAAM,IAAI,IAAI;AAAA,IAChB,OAAO;AACL,iBAAW,KAAK,GAAG;AAAA,IACrB;AAEA;AAAA,EACF;AAEA,SAAO,EAAE,OAAO,WAAW;AAC7B;AAEO,SAAS,SAAS,UAAyC,OAA0B;AAC1F,SAAO,MAAM,KAAK,CAAC,MAAM,MAAM,CAAC,MAAM,QAAQ,MAAM,CAAC,MAAM,MAAS;AACtE;","names":[]}

package/dist/chunk-GU4Y5ZWY.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+// src/config/schema.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { z } from "zod";
+var LANGUAGE_NAMES = {
+  en: "English",
+  pt: "Portuguese",
+  es: "Spanish",
+  fr: "French",
+  de: "German",
+  it: "Italian",
+  zh: "Chinese",
+  ja: "Japanese",
+  ko: "Korean"
+};
+var LEARNER_LEVEL_NAMES = {
+  none: "Never programmed",
+  beginner: "Just starting out",
+  intermediate: "Read code with difficulty",
+  regular: "Code regularly"
+};
+var CONFIG_FILENAME = "code-explainer.config.json";
+function getGlobalConfigPath() {
+  return join(homedir(), ".code-explainer.config.json");
+}
+var DEFAULT_CONFIG = {
+  engine: "ollama",
+  ollamaModel: "qwen3.5:4b",
+  ollamaUrl: "http://localhost:11434",
+  detailLevel: "standard",
+  language: "en",
+  learnerLevel: "intermediate",
+  hooks: {
+    edit: true,
+    write: true,
+    bash: true
+  },
+  exclude: ["*.lock", "dist/**", "node_modules/**"],
+  skipIfSlowMs: 3e4,
+  bashFilter: {
+    capturePatterns: [
+      "rm",
+      "mv",
+      "cp",
+      "mkdir",
+      "npm install",
+      "pip install",
+      "yarn add",
+      "pnpm add",
+      "chmod",
+      "chown",
+      "git checkout",
+      "git reset",
+      "git revert",
+      "sed -i"
+    ]
+  }
+};
+var EngineSchema = z.enum(["ollama", "claude"]);
+var DetailLevelSchema = z.enum(["minimal", "standard", "verbose"]);
+var LanguageSchema = z.enum(["en", "pt", "es", "fr", "de", "it", "zh", "ja", "ko"]);
+var LearnerLevelSchema = z.enum(["none", "beginner", "intermediate", "regular"]);
+var HooksConfigSchema = z.object({
+  edit: z.boolean().default(true),
+  write: z.boolean().default(true),
+  bash: z.boolean().default(true)
+}).default({});
+var BashFilterConfigSchema = z.object({
+  capturePatterns: z.array(z.string()).default([])
+}).default({});
+var ConfigSchema = z.object({
+  engine: EngineSchema.default("ollama"),
+  ollamaModel: z.string().min(1).default("qwen3.5:4b"),
+  ollamaUrl: z.string().url().default("http://localhost:11434"),
+  detailLevel: DetailLevelSchema.default("standard"),
+  language: LanguageSchema.default("en"),
+  learnerLevel: LearnerLevelSchema.default("intermediate"),
+  hooks: HooksConfigSchema,
+  exclude: z.array(z.string()).default(["*.lock", "dist/**", "node_modules/**"]),
+  skipIfSlowMs: z.coerce.number().int().min(0).default(3e4),
+  bashFilter: BashFilterConfigSchema
+});
+function validateConfig(raw) {
+  const result = ConfigSchema.safeParse(raw);
+  if (result.success) return result.data;
+  const issues = result.error.issues.map((i) => `  ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
+  throw new Error(`[code-explainer] Invalid config:
+${issues}`);
+}
+function mergeConfig(base, overlay) {
+  return {
+    ...base,
+    ...overlay,
+    hooks: { ...base.hooks, ...overlay.hooks ?? {} },
+    bashFilter: {
+      ...base.bashFilter,
+      ...overlay.bashFilter ?? {}
+    }
+  };
+}
+function tryReadJson(path) {
+  if (!existsSync(path)) return null;
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`[code-explainer] Config file ${path} is not valid JSON: ${msg}`);
+  }
+  const partial = ConfigSchema.partial().safeParse(raw);
+  if (!partial.success) {
+    const issues = partial.error.issues.map((i) => `  ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
+    throw new Error(`[code-explainer] Invalid config in ${path}:
+${issues}`);
+  }
+  return partial.data;
+}
+function loadConfig(configPath) {
+  const globalConfig = tryReadJson(getGlobalConfigPath());
+  const projectConfig = tryReadJson(configPath);
+  let result = DEFAULT_CONFIG;
+  if (globalConfig) result = mergeConfig(result, globalConfig);
+  if (projectConfig) result = mergeConfig(result, projectConfig);
+  return result;
+}
+
+export {
+  LANGUAGE_NAMES,
+  LEARNER_LEVEL_NAMES,
+  CONFIG_FILENAME,
+  getGlobalConfigPath,
+  DEFAULT_CONFIG,
+  ConfigSchema,
+  validateConfig,
+  loadConfig
+};
+//# sourceMappingURL=chunk-GU4Y5ZWY.js.map

package/dist/chunk-GU4Y5ZWY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config/schema.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { z } from \"zod\";\n\nexport type Engine = \"ollama\" | \"claude\";\nexport type DetailLevel = \"minimal\" | \"standard\" | \"verbose\";\nexport type RiskLevel = \"none\" | \"low\" | \"medium\" | \"high\";\n\nexport type Language =\n  | \"en\"\n  | \"pt\"\n  | \"es\"\n  | \"fr\"\n  | \"de\"\n  | \"it\"\n  | \"zh\"\n  | \"ja\"\n  | \"ko\";\n\nexport const LANGUAGE_NAMES: Record<Language, string> = {\n  en: \"English\",\n  pt: \"Portuguese\",\n  es: \"Spanish\",\n  fr: \"French\",\n  de: \"German\",\n  it: \"Italian\",\n  zh: \"Chinese\",\n  ja: \"Japanese\",\n  ko: \"Korean\",\n};\n\nexport type LearnerLevel = \"none\" | \"beginner\" | \"intermediate\" | \"regular\";\n\nexport const LEARNER_LEVEL_NAMES: Record<LearnerLevel, string> = {\n  none: \"Never programmed\",\n  beginner: \"Just starting out\",\n  intermediate: \"Read code with difficulty\",\n  regular: \"Code regularly\",\n};\n\nexport interface HooksConfig {\n  edit: boolean;\n  write: boolean;\n  bash: boolean;\n}\n\nexport interface BashFilterConfig {\n  capturePatterns: string[];\n}\n\nexport interface Config {\n  engine: Engine;\n  ollamaModel: string;\n  ollamaUrl: string;\n  detailLevel: DetailLevel;\n  language: Language;\n  learnerLevel: LearnerLevel;\n  hooks: HooksConfig;\n  exclude: string[];\n  skipIfSlowMs: number;\n  bashFilter: BashFilterConfig;\n}\n\nexport interface DeepDiveItem {\n  term: string;\n  explanation: string;\n}\n\nexport interface ExplanationResult {\n  impact: string;\n  howItWorks: string;\n  why: string;\n  deepDive: DeepDiveItem[];\n  isSamePattern: boolean;\n  samePatternNote: string;\n  risk: RiskLevel;\n  riskReason: string;\n}\n\nexport interface HookPayload {\n  session_id: string;\n  transcript_path: string;\n  cwd: string;\n  permission_mode: string;\n  hook_event_name: string;\n  tool_name: string;\n  tool_input: Record<string, unknown>;\n  // Claude Code sends this as an object for Edit/Write/MultiEdit and a string\n  // for Bash; type it as unknown so consumers validate before use.\n  tool_response: unknown;\n}\n\nexport const CONFIG_FILENAME = \"code-explainer.config.json\";\n\nexport function getGlobalConfigPath(): string {\n  return join(homedir(), \".code-explainer.config.json\");\n}\n\nexport const DEFAULT_CONFIG: Config = {\n  engine: \"ollama\",\n  ollamaModel: \"qwen3.5:4b\",\n  ollamaUrl: \"http://localhost:11434\",\n  detailLevel: \"standard\",\n  language: \"en\",\n  learnerLevel: \"intermediate\",\n  hooks: {\n    edit: true,\n    write: true,\n    bash: true,\n  },\n  exclude: [\"*.lock\", \"dist/**\", \"node_modules/**\"],\n  skipIfSlowMs: 30000,\n  bashFilter: {\n    capturePatterns: [\n      \"rm\",\n      \"mv\",\n      \"cp\",\n      \"mkdir\",\n      \"npm install\",\n      \"pip install\",\n      \"yarn add\",\n      \"pnpm add\",\n      \"chmod\",\n      \"chown\",\n      \"git checkout\",\n      \"git reset\",\n      \"git revert\",\n      \"sed -i\",\n    ],\n  },\n};\n\n// ---------------------------------------------------------------------------\n// Zod schema — used to validate and parse config files at load time.\n// Using z.coerce where sensible so that older config files with slightly\n// different types (e.g., skipIfSlowMs stored as a string) still work.\n// ---------------------------------------------------------------------------\n\nconst EngineSchema = z.enum([\"ollama\", \"claude\"]);\nconst DetailLevelSchema = z.enum([\"minimal\", \"standard\", \"verbose\"]);\nconst LanguageSchema = z.enum([\"en\", \"pt\", \"es\", \"fr\", \"de\", \"it\", \"zh\", \"ja\", \"ko\"]);\nconst LearnerLevelSchema = z.enum([\"none\", \"beginner\", \"intermediate\", \"regular\"]);\n\nconst HooksConfigSchema = z.object({\n  edit: z.boolean().default(true),\n  write: z.boolean().default(true),\n  bash: z.boolean().default(true),\n}).default({});\n\nconst BashFilterConfigSchema = z.object({\n  capturePatterns: z.array(z.string()).default([]),\n}).default({});\n\nexport const ConfigSchema = z.object({\n  engine: EngineSchema.default(\"ollama\"),\n  ollamaModel: z.string().min(1).default(\"qwen3.5:4b\"),\n  ollamaUrl: z.string().url().default(\"http://localhost:11434\"),\n  detailLevel: DetailLevelSchema.default(\"standard\"),\n  language: LanguageSchema.default(\"en\"),\n  learnerLevel: LearnerLevelSchema.default(\"intermediate\"),\n  hooks: HooksConfigSchema,\n  exclude: z.array(z.string()).default([\"*.lock\", \"dist/**\", \"node_modules/**\"]),\n  skipIfSlowMs: z.coerce.number().int().min(0).default(30000),\n  bashFilter: BashFilterConfigSchema,\n});\n\nexport type ConfigInput = z.input<typeof ConfigSchema>;\n\n/**\n * Validate a raw JSON object against the config schema.\n * Returns a typed Config on success, or throws a ZodError-derived Error with\n * a human-readable message listing all invalid fields.\n */\nexport function validateConfig(raw: unknown): Config {\n  const result = ConfigSchema.safeParse(raw);\n  if (result.success) return result.data;\n\n  const issues = result.error.issues\n    .map((i) => `  ${i.path.join(\".\") || \"<root>\"}: ${i.message}`)\n    .join(\"\\n\");\n  throw new Error(`[code-explainer] Invalid config:\\n${issues}`);\n}\n\nfunction mergeConfig(base: Config, overlay: Partial<Config>): Config {\n  return {\n    ...base,\n    ...overlay,\n    hooks: { ...base.hooks, ...(overlay.hooks ?? {}) },\n    bashFilter: {\n      ...base.bashFilter,\n      ...(overlay.bashFilter ?? {}),\n    },\n  };\n}\n\n/**\n * Read and parse a config file. Returns the partial config or null if the\n * file is missing. Throws if the JSON is malformed or fails schema validation\n * (so callers surface useful errors rather than silently using defaults).\n */\nfunction tryReadJson(path: string): Partial<Config> | null {\n  if (!existsSync(path)) return null;\n  let raw: unknown;\n  try {\n    raw = JSON.parse(readFileSync(path, \"utf-8\"));\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    throw new Error(`[code-explainer] Config file ${path} is not valid JSON: ${msg}`);\n  }\n  // Partial validation: only validate keys that are present. Unknown keys are\n  // ignored (forward-compat). We re-use ConfigSchema with .partial() so that\n  // missing keys fall through to the DEFAULT_CONFIG merger rather than errors.\n  const partial = ConfigSchema.partial().safeParse(raw);\n  if (!partial.success) {\n    const issues = partial.error.issues\n      .map((i) => `  ${i.path.join(\".\") || \"<root>\"}: ${i.message}`)\n      .join(\"\\n\");\n    throw new Error(`[code-explainer] Invalid config in ${path}:\\n${issues}`);\n  }\n  return partial.data as Partial<Config>;\n}\n\n/**\n * Load config with three-level resolution, most specific first:\n *   1. Project config (passed as configPath) — overrides everything\n *   2. Global user config (~/.code-explainer.config.json)\n *   3. Built-in defaults\n *\n * A project config that lacks a field falls through to the global; a global\n * that lacks a field falls through to defaults. This lets a global install\n * set everyone's defaults while still allowing per-project overrides.\n */\nexport function loadConfig(configPath: string): Config {\n  const globalConfig = tryReadJson(getGlobalConfigPath());\n  const projectConfig = tryReadJson(configPath);\n\n  let result = DEFAULT_CONFIG;\n  if (globalConfig) result = mergeConfig(result, globalConfig);\n  if (projectConfig) result = mergeConfig(result, projectConfig);\n  return result;\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-2PUO5G3C.js → chunk-KK76JK7S.js}

@@ -26,10 +26,7 @@ function buildCodeExplainerEntries(hookScriptPath) {
 function isCodeExplainerHook(cmd) {
   return cmd.includes(HOOK_MARKER) && cmd.includes("post-tool");
 }
-function mergeHooksIntoSettings(projectRoot, hookScriptPath, { useLocal = true } = {}) {
-  const claudeDir = join(projectRoot, ".claude");
-  const filename = useLocal ? "settings.local.json" : "settings.json";
-  const settingsPath = join(claudeDir, filename);
+function mergeHooksAtPath(settingsPath, hookScriptPath) {
   let settings = {};
   let created = false;
   if (existsSync(settingsPath)) {
@@ -49,8 +46,9 @@ function mergeHooksIntoSettings(projectRoot, hookScriptPath, { useLocal = true }
     }
   } else {
     created = true;
-    if (!existsSync(claudeDir)) {
-      mkdirSync(claudeDir, { recursive: true });
+    const parent = dirname(settingsPath);
+    if (!existsSync(parent)) {
+      mkdirSync(parent, { recursive: true });
     }
   }
   if (!settings.hooks) settings.hooks = {};
@@ -64,90 +62,7 @@ function mergeHooksIntoSettings(projectRoot, hookScriptPath, { useLocal = true }
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   return { created, path: settingsPath };
 }
-function removeHooksFromSettings(projectRoot, { useLocal = true } = {}) {
-  const candidates = useLocal ? [".claude/settings.local.json", ".claude/settings.json"] : [".claude/settings.json"];
-  let removedAny = false;
-  let lastPath = null;
-  for (const rel of candidates) {
-    const path = join(projectRoot, rel);
-    if (!existsSync(path)) continue;
-    let settings;
-    try {
-      settings = JSON.parse(readFileSync(path, "utf-8"));
-    } catch {
-      continue;
-    }
-    if (!settings.hooks?.PostToolUse) continue;
-    const before = JSON.stringify(settings.hooks.PostToolUse);
-    settings.hooks.PostToolUse = settings.hooks.PostToolUse.map((entry) => ({
-      ...entry,
-      hooks: entry.hooks.filter((h) => !isCodeExplainerHook(h.command))
-    })).filter((entry) => entry.hooks.length > 0);
-    const after = JSON.stringify(settings.hooks.PostToolUse);
-    if (before !== after) {
-      if (settings.hooks.PostToolUse.length === 0) {
-        delete settings.hooks.PostToolUse;
-      }
-      if (Object.keys(settings.hooks).length === 0) {
-        delete settings.hooks;
-      }
-      writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
-      removedAny = true;
-      lastPath = path;
-    }
-  }
-  return { removed: removedAny, path: lastPath };
-}
-function mergeHooksIntoUserSettings(hookScriptPath) {
-  const userClaudeDir = join(homedir(), ".claude");
-  const settingsPath = join(userClaudeDir, "settings.json");
-  let settings = {};
-  let created = false;
-  if (existsSync(settingsPath)) {
-    const raw = readFileSync(settingsPath, "utf-8");
-    try {
-      settings = JSON.parse(raw);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(
-        `[code-explainer] Cannot merge hooks into ${settingsPath}. The file is not valid JSON. Fix: repair the JSON manually or delete the file to regenerate. Original error: ${msg}`
-      );
-    }
-    if (typeof settings !== "object" || settings === null || Array.isArray(settings)) {
-      throw new Error(
-        `[code-explainer] Cannot merge hooks into ${settingsPath}. The file does not contain a JSON object at the top level.`
-      );
-    }
-  } else {
-    created = true;
-    if (!existsSync(userClaudeDir)) {
-      mkdirSync(userClaudeDir, { recursive: true });
-    }
-  }
-  if (!settings.hooks) settings.hooks = {};
-  const ourEntries = {
-    PostToolUse: [
-      {
-        matcher: "Edit|Write|MultiEdit",
-        hooks: [{ type: "command", command: `node "${hookScriptPath}"` }]
-      },
-      {
-        matcher: "Bash",
-        hooks: [{ type: "command", command: `node "${hookScriptPath}"` }]
-      }
-    ]
-  };
-  const existingPostTool = settings.hooks.PostToolUse ?? [];
-  const cleaned = existingPostTool.map((entry) => ({
-    ...entry,
-    hooks: entry.hooks.filter((h) => !isCodeExplainerHook(h.command))
-  })).filter((entry) => entry.hooks.length > 0);
-  settings.hooks.PostToolUse = [...cleaned, ...ourEntries.PostToolUse];
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-  return { created, path: settingsPath };
-}
-function removeHooksFromUserSettings() {
-  const settingsPath = join(homedir(), ".claude", "settings.json");
+function removeHooksAtPath(settingsPath) {
   if (!existsSync(settingsPath)) return { removed: false, path: null };
   let settings;
   try {
@@ -168,11 +83,36 @@ function removeHooksFromUserSettings() {
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   return { removed: true, path: settingsPath };
 }
+function mergeHooksIntoSettings(projectRoot, hookScriptPath, { useLocal = true } = {}) {
+  const filename = useLocal ? "settings.local.json" : "settings.json";
+  const settingsPath = join(projectRoot, ".claude", filename);
+  return mergeHooksAtPath(settingsPath, hookScriptPath);
+}
+function mergeHooksIntoUserSettings(hookScriptPath) {
+  const settingsPath = join(homedir(), ".claude", "settings.json");
+  return mergeHooksAtPath(settingsPath, hookScriptPath);
+}
+function removeHooksFromSettings(projectRoot, { useLocal = true } = {}) {
+  const candidates = useLocal ? [".claude/settings.local.json", ".claude/settings.json"] : [".claude/settings.json"];
+  let removedAny = false;
+  let lastPath = null;
+  for (const rel of candidates) {
+    const r = removeHooksAtPath(join(projectRoot, rel));
+    if (r.removed) {
+      removedAny = true;
+      lastPath = r.path;
+    }
+  }
+  return { removed: removedAny, path: lastPath };
+}
+function removeHooksFromUserSettings() {
+  return removeHooksAtPath(join(homedir(), ".claude", "settings.json"));
+}
 
 export {
   mergeHooksIntoSettings,
-  removeHooksFromSettings,
   mergeHooksIntoUserSettings,
+  removeHooksFromSettings,
   removeHooksFromUserSettings
 };
-//# sourceMappingURL=chunk-2PUO5G3C.js.map
+//# sourceMappingURL=chunk-KK76JK7S.js.map

package/dist/chunk-KK76JK7S.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config/merge.ts"],"sourcesContent":["import { existsSync, readFileSync, writeFileSync, mkdirSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\n\nexport const HOOK_MARKER = \"code-explainer\";\n\ninterface HookMatcherEntry {\n  matcher: string;\n  hooks: Array<{\n    type: \"command\";\n    command: string;\n  }>;\n}\n\ninterface ClaudeSettings {\n  hooks?: Record<string, HookMatcherEntry[]>;\n  [key: string]: unknown;\n}\n\nfunction buildHookCommand(hookScriptPath: string): string {\n  return `node \"${hookScriptPath}\"`;\n}\n\nfunction buildCodeExplainerEntries(hookScriptPath: string): Record<string, HookMatcherEntry[]> {\n  const command = buildHookCommand(hookScriptPath);\n  return {\n    PostToolUse: [\n      {\n        matcher: \"Edit|Write|MultiEdit\",\n        hooks: [{ type: \"command\", command }],\n      },\n      {\n        matcher: \"Bash\",\n        hooks: [{ type: \"command\", command }],\n      },\n    ],\n  };\n}\n\nfunction isCodeExplainerHook(cmd: string): boolean {\n  return cmd.includes(HOOK_MARKER) && cmd.includes(\"post-tool\");\n}\n\nexport interface MergeResult {\n  created: boolean;\n  path: string;\n}\n\n/**\n * Core merge: read/parse/merge-and-write at a specific settings path.\n * Creates the parent dir if needed. Preserves all existing hooks and other\n * top-level keys. Idempotent — removes previous code-explainer entries\n * before adding the new ones so re-running does not duplicate.\n *\n * Throws if the existing file is malformed JSON or not a top-level object.\n */\nfunction mergeHooksAtPath(settingsPath: string, hookScriptPath: string): MergeResult {\n  let settings: ClaudeSettings = {};\n  let created = false;\n\n  if (existsSync(settingsPath)) {\n    const raw = readFileSync(settingsPath, \"utf-8\");\n    try {\n      settings = JSON.parse(raw);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      throw new Error(\n        `[code-explainer] Cannot merge hooks into ${settingsPath}. The file is not valid JSON. Fix: repair the JSON manually (check for trailing commas, unquoted keys) or delete the file to regenerate. Original error: ${msg}`\n      );\n    }\n    if (typeof settings !== \"object\" || settings === null || Array.isArray(settings)) {\n      throw new Error(\n        `[code-explainer] Cannot merge hooks into ${settingsPath}. The file does not contain a JSON object at the top level. Fix: ensure the file starts with { and ends with }.`\n      );\n    }\n  } else {\n    created = true;\n    const parent = dirname(settingsPath);\n    if (!existsSync(parent)) {\n      mkdirSync(parent, { recursive: true });\n    }\n  }\n\n  if (!settings.hooks) settings.hooks = {};\n\n  const ourEntries = buildCodeExplainerEntries(hookScriptPath);\n  const existingPostTool = settings.hooks.PostToolUse ?? [];\n\n  // Remove any previous code-explainer entries to keep idempotency.\n  const cleaned = existingPostTool\n    .map((entry) => ({\n      ...entry,\n      hooks: entry.hooks.filter((h) => !isCodeExplainerHook(h.command)),\n    }))\n    .filter((entry) => entry.hooks.length > 0);\n\n  settings.hooks.PostToolUse = [...cleaned, ...ourEntries.PostToolUse];\n\n  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + \"\\n\");\n\n  return { created, path: settingsPath };\n}\n\n/**\n * Core remove: read/filter/write at a specific settings path.\n * Silently skips missing or malformed files (we don't want to corrupt\n * unrelated user config during an uninstall).\n */\nfunction removeHooksAtPath(settingsPath: string): { removed: boolean; path: string | null } {\n  if (!existsSync(settingsPath)) return { removed: false, path: null };\n\n  let settings: ClaudeSettings;\n  try {\n    settings = JSON.parse(readFileSync(settingsPath, \"utf-8\"));\n  } catch {\n    return { removed: false, path: null };\n  }\n\n  if (!settings.hooks?.PostToolUse) return { removed: false, path: null };\n\n  const before = JSON.stringify(settings.hooks.PostToolUse);\n  settings.hooks.PostToolUse = settings.hooks.PostToolUse\n    .map((entry) => ({\n      ...entry,\n      hooks: entry.hooks.filter((h) => !isCodeExplainerHook(h.command)),\n    }))\n    .filter((entry) => entry.hooks.length > 0);\n  const after = JSON.stringify(settings.hooks.PostToolUse);\n\n  if (before === after) return { removed: false, path: null };\n\n  if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;\n  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;\n\n  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + \"\\n\");\n  return { removed: true, path: settingsPath };\n}\n\n/**\n * Merge code-explainer hooks into a project's .claude/settings[.local].json.\n */\nexport function mergeHooksIntoSettings(\n  projectRoot: string,\n  hookScriptPath: string,\n  { useLocal = true }: { useLocal?: boolean } = {}\n): MergeResult {\n  const filename = useLocal ? \"settings.local.json\" : \"settings.json\";\n  const settingsPath = join(projectRoot, \".claude\", filename);\n  return mergeHooksAtPath(settingsPath, hookScriptPath);\n}\n\n/**\n * Merge code-explainer hooks into the user-level ~/.claude/settings.json,\n * so hooks fire in every project. Used by the global install path.\n */\nexport function mergeHooksIntoUserSettings(hookScriptPath: string): MergeResult {\n  const settingsPath = join(homedir(), \".claude\", \"settings.json\");\n  return mergeHooksAtPath(settingsPath, hookScriptPath);\n}\n\n/**\n * Remove all code-explainer hook entries from a project's settings files,\n * preserving other hooks and config.\n */\nexport function removeHooksFromSettings(\n  projectRoot: string,\n  { useLocal = true }: { useLocal?: boolean } = {}\n): { removed: boolean; path: string | null } {\n  const candidates = useLocal\n    ? [\".claude/settings.local.json\", \".claude/settings.json\"]\n    : [\".claude/settings.json\"];\n\n  let removedAny = false;\n  let lastPath: string | null = null;\n\n  for (const rel of candidates) {\n    const r = removeHooksAtPath(join(projectRoot, rel));\n    if (r.removed) {\n      removedAny = true;\n      lastPath = r.path;\n    }\n  }\n\n  return { removed: removedAny, path: lastPath };\n}\n\n/**\n * Remove code-explainer hook entries from ~/.claude/settings.json.\n */\nexport function removeHooksFromUserSettings(): { removed: boolean; path: string | null } {\n  return removeHooksAtPath(join(homedir(), \".claude\", \"settings.json\"));\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-XW3S5GNV.js → chunk-VJN7Y4SI.js}

@@ -4,31 +4,79 @@ import {
 } from "./chunk-7OCVIDC7.js";
 
 // src/session/tracker.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, appendFileSync as appendFileSync2, unlinkSync as unlinkSync2, mkdirSync as mkdirSync2, readdirSync, statSync } from "fs";
-import { tmpdir as tmpdir2 } from "os";
-import { join as join2 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2, appendFileSync as appendFileSync2, unlinkSync as unlinkSync2, readdirSync, statSync } from "fs";
+import { join as join3 } from "path";
 
 // src/cache/explanation-cache.ts
 import { createHash } from "crypto";
-import { existsSync, readFileSync, appendFileSync, unlinkSync, mkdirSync } from "fs";
-import { tmpdir } from "os";
+import { existsSync as existsSync2, readFileSync, appendFileSync, writeFileSync, renameSync, unlinkSync } from "fs";
+import { join as join2 } from "path";
+
+// src/session/session-id.ts
+var SAFE_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+function isSafeSessionId(id) {
+  return typeof id === "string" && SAFE_ID_PATTERN.test(id);
+}
+function assertSafeSessionId(id) {
+  if (!isSafeSessionId(id)) {
+    throw new Error(`unsafe session id: ${JSON.stringify(id)}`);
+  }
+}
+
+// src/session/tmpdir.ts
+import { existsSync, mkdirSync } from "fs";
+import { tmpdir, userInfo } from "os";
 import { join } from "path";
 function getUserTmpDir() {
-  const dir = join(tmpdir(), `code-explainer-${process.getuid?.() ?? "user"}`);
+  let suffix;
+  try {
+    const info = userInfo();
+    suffix = typeof info.username === "string" && info.username ? info.username : "user";
+  } catch {
+    suffix = "user";
+  }
+  suffix = suffix.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64) || "user";
+  const dir = join(tmpdir(), `code-explainer-${suffix}`);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true, mode: 448 });
   }
   return dir;
 }
+
+// src/cache/explanation-cache.ts
+var CACHE_ROTATE_THRESHOLD = 500;
+var CACHE_COMPACT_TARGET = 250;
 function getCacheFilePath(sessionId) {
-  return join(getUserTmpDir(), `cache-${sessionId}.jsonl`);
+  assertSafeSessionId(sessionId);
+  return join2(getUserTmpDir(), `cache-${sessionId}.jsonl`);
 }
 function hashDiff(diff) {
   return createHash("sha256").update(diff, "utf-8").digest("hex");
 }
+function rotateCacheIfNeeded(path) {
+  try {
+    const content = readFileSync(path, "utf-8");
+    const lines = content.split("\n").filter((l) => l.trim());
+    if (lines.length <= CACHE_ROTATE_THRESHOLD) return;
+    const seen = /* @__PURE__ */ new Map();
+    for (const line2 of lines) {
+      try {
+        const entry = JSON.parse(line2);
+        seen.set(entry.hash, entry);
+      } catch {
+      }
+    }
+    const unique = Array.from(seen.values());
+    const compacted = unique.slice(-CACHE_COMPACT_TARGET);
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, compacted.map((e) => JSON.stringify(e)).join("\n") + "\n", { mode: 384 });
+    renameSync(tmp, path);
+  } catch {
+  }
+}
 function getCached(sessionId, diff) {
   const path = getCacheFilePath(sessionId);
-  if (!existsSync(path)) return void 0;
+  if (!existsSync2(path)) return void 0;
   const hash = hashDiff(diff);
   try {
     const content = readFileSync(path, "utf-8");
@@ -52,12 +100,13 @@ function setCached(sessionId, diff, result) {
   const entry = { hash: hashDiff(diff), result };
   try {
     appendFileSync(path, JSON.stringify(entry) + "\n", { mode: 384 });
+    rotateCacheIfNeeded(path);
   } catch {
   }
 }
 function clearCache(sessionId) {
   const path = getCacheFilePath(sessionId);
-  if (existsSync(path)) {
+  if (existsSync2(path)) {
     try {
       unlinkSync(path);
     } catch {
@@ -487,15 +536,10 @@ function stripAnsi(s) {
 
 // src/session/tracker.ts
 var TWO_HOURS_MS = 2 * 60 * 60 * 1e3;
-function getUserTmpDir2() {
-  const dir = join2(tmpdir2(), `code-explainer-${process.getuid?.() ?? "user"}`);
-  if (!existsSync2(dir)) {
-    mkdirSync2(dir, { recursive: true, mode: 448 });
-  }
-  return dir;
-}
+var CLEANUP_THROTTLE_MS = 60 * 1e3;
 function getSessionFilePath(sessionId) {
-  return join2(getUserTmpDir2(), `session-${sessionId}.jsonl`);
+  assertSafeSessionId(sessionId);
+  return join3(getUserTmpDir(), `session-${sessionId}.jsonl`);
 }
 function recordEntry(sessionId, entry) {
   const path = getSessionFilePath(sessionId);
@@ -506,7 +550,7 @@ function recordEntry(sessionId, entry) {
 }
 function readSession(sessionId) {
   const path = getSessionFilePath(sessionId);
-  if (!existsSync2(path)) return [];
+  if (!existsSync3(path)) return [];
   try {
     const content = readFileSync2(path, "utf-8");
     return content.split("\n").filter((l) => l.trim()).map((line2) => {
@@ -520,19 +564,34 @@ function readSession(sessionId) {
     return [];
   }
 }
-function getRecentSummaries(sessionId, n) {
-  const entries = readSession(sessionId);
-  if (entries.length === 0) return [];
-  return entries.slice(-n).map((e) => `${e.file}: ${e.summary}`);
+function getRecentSummaries(sessionId, n, entries) {
+  const all = entries ?? readSession(sessionId);
+  if (all.length === 0) return [];
+  return all.slice(-n).map((e) => `${e.file}: ${e.summary}`);
+}
+function getCleanupTimestampPath() {
+  return join3(getUserTmpDir(), ".last-cleanup");
 }
 function cleanStaleSessionFiles() {
   try {
-    const dir = getUserTmpDir2();
+    const tsPath = getCleanupTimestampPath();
     const now = Date.now();
+    if (existsSync3(tsPath)) {
+      try {
+        const ts = parseInt(readFileSync2(tsPath, "utf-8").trim(), 10);
+        if (!isNaN(ts) && now - ts < CLEANUP_THROTTLE_MS) return;
+      } catch {
+      }
+    }
+    try {
+      writeFileSync2(tsPath, String(now), { mode: 384 });
+    } catch {
+    }
+    const dir = getUserTmpDir();
     const entries = readdirSync(dir);
     for (const name of entries) {
       if (!name.startsWith("session-") && !name.startsWith("cache-")) continue;
-      const filePath = join2(dir, name);
+      const filePath = join3(dir, name);
       try {
         const stat = statSync(filePath);
         if (now - stat.mtimeMs > TWO_HOURS_MS) {
@@ -549,33 +608,56 @@ function getSessionIdFromEnv() {
 }
 function findLatestSession() {
   try {
-    const dir = getUserTmpDir2();
+    const dir = getUserTmpDir();
     const entries = readdirSync(dir).filter((n) => n.startsWith("session-") && n.endsWith(".jsonl")).map((n) => ({
       name: n,
       id: n.slice("session-".length, -".jsonl".length),
-      mtime: statSync(join2(dir, n)).mtimeMs
+      mtime: statSync(join3(dir, n)).mtimeMs
     })).sort((a, b) => b.mtime - a.mtime);
     return entries[0]?.id;
   } catch {
     return void 0;
   }
 }
-async function printSummary() {
+async function printSummary({ json = false } = {}) {
   const sessionId = getSessionIdFromEnv() ?? findLatestSession();
   if (!sessionId) {
-    process.stderr.write("[code-explainer] No active session found. Session data is created when Claude Code makes changes.\n");
+    if (json) {
+      process.stdout.write(JSON.stringify({ error: "No active session found" }) + "\n");
+    } else {
+      process.stderr.write("[code-explainer] No active session found. Session data is created when Claude Code makes changes.\n");
+    }
     return;
   }
   const entries = readSession(sessionId);
   if (entries.length === 0) {
-    process.stderr.write(`[code-explainer] Session '${sessionId}' has no recorded changes yet.
+    if (json) {
+      process.stdout.write(JSON.stringify({ sessionId, totalChanges: 0, files: [], risks: { none: 0, low: 0, medium: 0, high: 0 } }) + "\n");
+    } else {
+      process.stderr.write(`[code-explainer] Session '${sessionId}' has no recorded changes yet.
 `);
+    }
     return;
   }
   const related = entries.filter((e) => !e.unrelated);
   const unrelated = entries.filter((e) => e.unrelated);
   const uniqueFiles = Array.from(new Set(entries.map((e) => e.file)));
   const unrelatedFiles = Array.from(new Set(unrelated.map((e) => e.file)));
+  const risks = { none: 0, low: 0, medium: 0, high: 0 };
+  for (const e of entries) risks[e.risk]++;
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      sessionId,
+      totalChanges: entries.length,
+      filesCount: uniqueFiles.length,
+      relatedChanges: related.length,
+      unrelatedChanges: unrelated.length,
+      unrelatedFiles,
+      risks,
+      entries: entries.map((e) => ({ file: e.file, risk: e.risk, summary: e.summary, unrelated: !!e.unrelated }))
+    }, null, 2) + "\n");
+    return;
+  }
   const alert = formatDriftAlert(uniqueFiles.length, unrelatedFiles);
   printToStderr(alert);
   process.stderr.write(`
@@ -587,8 +669,6 @@ Total changes: ${entries.length}
 `);
   process.stderr.write(`Unrelated/risky: ${unrelated.length}
 `);
-  const risks = { none: 0, low: 0, medium: 0, high: 0 };
-  for (const e of entries) risks[e.risk]++;
   process.stderr.write(`
 Risk breakdown:
 `);
@@ -608,7 +688,7 @@ async function endSession() {
     return;
   }
   const sessionPath = getSessionFilePath(sessionId);
-  if (existsSync2(sessionPath)) {
+  if (existsSync3(sessionPath)) {
     try {
       unlinkSync2(sessionPath);
     } catch {
@@ -620,6 +700,7 @@ async function endSession() {
 }
 
 export {
+  isSafeSessionId,
   getCached,
   setCached,
   formatExplanationBox,
@@ -634,4 +715,4 @@ export {
   printSummary,
   endSession
 };
-//# sourceMappingURL=chunk-XW3S5GNV.js.map
+//# sourceMappingURL=chunk-VJN7Y4SI.js.map