vibe-code-explainer 0.2.0 → 0.3.0

package/README.md

@@ -16,30 +16,57 @@ No more accepting code blindly.
 **Safe change (low/no risk):**
 
 ```
-┌─ code-explainer ─────────────────────────────
-│  src/app/page.tsx
-│
-│  Changed the page background from a solid dark color to a
-│  gradient that blends two shades of blue. Visual-only change,
-│  no logic or data affected.
-│
-│  Risk: ✅ None
-└──────────────────────────────────────────────
+╭─ vibe-code-explainer ─────────────────────────╮
+│                                                 │
+│  📄  src/app/page.tsx                           │
+│                                                 │
+│  ▸ Impact                                       │
+│    Changed page background from solid dark      │
+│    blue to a gradient.                          │
+│                                                 │
+│  ▸ How it works                                 │
+│    `bg-gradient-to-br` + `from-`/`to-` Tailwind │
+│    utilities generate a CSS linear-gradient.    │
+│                                                 │
+│  ▸ Why                                          │
+│    Tailwind: utility classes for gradients      │
+│    instead of writing custom CSS.               │
+│                                                 │
+│  ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄  │
+│                                                 │
+│  ✓  Risk: None                                  │
+│                                                 │
+╰─────────────────────────────────────────────────╯
 ```
 
 **Risky change (medium/high risk):**
 
 ```
-┌─ code-explainer ⚠️ ──────────────────────────
-│  🚨  .env
-│
-│  Adds a Stripe payment secret key directly in the environment
-│  file. This key gives access to your payment system.
-│
-│  Risk: 🚨 High
-│  A live payment API key is hardcoded in the file and should
-│  not be committed to version control.
-└──────────────────────────────────────────────
+╭─ vibe-code-explainer ─────────────────────────╮       ← red border
+│                                                 │
+│  📄  .env                                       │
+│                                                 │
+│  ▸ Impact                                       │
+│    Added a Stripe payment secret key directly   │
+│    in the environment file.                     │
+│                                                 │
+│  ▸ How it works                                 │
+│    `.env` files store environment variables,    │
+│    read by your code at runtime. `sk_live_`     │
+│    is Stripe's prefix for production keys.      │
+│                                                 │
+│  ▸ Why                                          │
+│    Convention: secrets live in .env files that  │
+│    are kept out of git via .gitignore.          │
+│                                                 │
+│  ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄ ─ ┄  │
+│                                                 │
+│  🚨  Risk: High                                 │
+│      A live Stripe production key is hardcoded. │
+│      Make sure .env is in .gitignore before     │
+│      committing.                                │
+│                                                 │
+╰─────────────────────────────────────────────────╯
 ```
 
 ---
@@ -112,9 +139,15 @@ exist, so you can set a global default and override per-project.
 
 #### 3. Detail level
 
-- **Standard** — 1–2 sentence explanation per change (recommended)
-- **Minimal** — one short sentence per change
-- **Verbose** — detailed bullet-point breakdown of every change
+This is also the **teacher mode** switch:
+
+- **Minimal** — single sentence describing the impact. **No teaching.** Use
+  this if you just want to know what changed without any educational content.
+- **Standard** — three sections per change: **Impact** (what changes for the
+  user), **How it works** (mechanical explanation of the syntax/concept),
+  **Why** (why this approach was used). Recommended.
+- **Verbose** — same three sections, each more in-depth (2–4 sentences).
+  Plus a fourth **Deeper dive** section with related terms to look up.
 
 #### 4. Language
 
@@ -123,10 +156,25 @@ Pick the language the explanations are written in. Supported:
 English, Portuguese, Spanish, French, German, Italian, Chinese, Japanese,
 Korean.
 
-Only the `summary` and `riskReason` fields are translated. JSON keys and the
-risk labels (`none` / `low` / `medium` / `high`) stay in English.
+Only the natural-language fields (impact, howItWorks, why, deepDive items,
+riskReason) are translated. JSON keys and risk labels (`none` / `low` /
+`medium` / `high`) stay in English so parsing stays stable.
+
+#### 5. Programming knowledge level (only when teaching is on)
+
+If you picked Standard or Verbose, the installer asks how much you already
+know about programming. This calibrates the depth of the teaching:
 
-#### 5. Model (Ollama only)
+- **Never programmed** — explanations start from "what is a variable" when
+  needed. Uses everyday-life analogies.
+- **Just starting out** — explains new technical terms, doesn't re-teach
+  basics like variables and functions.
+- **Read code with difficulty** — assumes core concepts, focuses on idiomatic
+  patterns and what specific syntax accomplishes.
+- **Code regularly** — concise. Mentions modern features, gotchas, and
+  alternatives rather than syntax basics.
+
+#### 6. Model (Ollama only)
 
 - If you have an NVIDIA GPU, the installer auto-detects your VRAM and picks
   the right model.
@@ -214,27 +262,50 @@ Every explanation includes a risk rating:
 
 ## Configuration
 
-Change any setting at any time by running:
+Change any setting at any time by running `config`. Which command depends on
+how you installed it:
+
+**If you installed globally** (the package is on your PATH):
+
+```bash
+vibe-code-explainer config
+```
+
+**If you installed per-project** (or want to be safe):
 
 ```bash
 npx vibe-code-explainer config
 ```
 
-This opens an interactive menu showing your current settings. Pick what you
-want to change, one at a time. Every change is saved immediately.
+Both commands do the same thing. Use whichever works in your shell. If you
+see a stale version run via `npx`, force the latest with:
+
+```bash
+npx vibe-code-explainer@latest config
+```
+
+The menu auto-detects whether to edit the project config (`./code-explainer.config.json`)
+or the global config (`~/.code-explainer.config.json`): project config wins
+if both exist.
+
+It opens an interactive menu showing your current settings. Pick what you
+want to change, one at a time. Every change is saved immediately. When you
+change the model, the tool checks whether Ollama already has it pulled and
+offers to download it on the spot if not.
 
 ```
 code-explainer config (project)
 
 Current settings:
-  Engine:        Local LLM (Ollama)
-  Model:         qwen3.5:4b
-  Ollama URL:    http://localhost:11434
-  Detail level:  standard
-  Language:      English
-  Hooks:         Edit ✓  Write ✓  Bash ✓
-  Excluded:      *.lock, dist/**, node_modules/**
-  Skip if slow:  8s
+  Engine:         Local LLM (Ollama)
+  Model:          qwen3.5:4b
+  Ollama URL:     http://localhost:11434
+  Detail level:   standard
+  Language:       English
+  Learner level:  Read code with difficulty
+  Hooks:          Edit ✓  Write ✓  Bash ✓
+  Excluded:       *.lock, dist/**, node_modules/**
+  Skip if slow:   8s
 
 ? What would you like to change?
   ❯ Engine
@@ -242,6 +313,7 @@ Current settings:
     Ollama URL
     Detail level
     Language
+    Learner level
     Enable/disable hooks
     File exclusions
     Latency timeout
@@ -266,8 +338,12 @@ If both exist, the project config takes precedence at runtime.
 - **Detail level** — minimal / standard / verbose. See
   [Install → Detail level](#3-detail-level) for what each produces.
 - **Language** — English, Portuguese, Spanish, French, German, Italian,
-  Chinese, Japanese, Korean. Applies to the `summary` and `riskReason`
-  fields; JSON keys and risk labels stay in English.
+  Chinese, Japanese, Korean. Applies to the natural-language fields (impact,
+  howItWorks, why, deepDive, riskReason); JSON keys and risk labels stay in
+  English.
+- **Learner level** — calibrates teaching depth. Options: never programmed /
+  just starting / read code with difficulty / code regularly. See
+  [Install → step 5](#5-programming-knowledge-level-only-when-teaching-is-on).
 - **Hooks** — turn on or off individually. If Bash explanations feel noisy,
   disable just that hook and keep Edit + Write.
 - **File exclusions** — glob patterns for files you never want explained.
@@ -294,6 +370,7 @@ Full config schema:
   "ollamaUrl": "http://localhost:11434",
   "detailLevel": "standard",
   "language": "en",
+  "learnerLevel": "intermediate",
   "hooks": {
     "edit": true,
     "write": true,
@@ -322,6 +399,7 @@ Field types:
 | `ollamaUrl` | Any valid URL (warns on non-loopback) |
 | `detailLevel` | `"minimal"` / `"standard"` / `"verbose"` |
 | `language` | `"en"` / `"pt"` / `"es"` / `"fr"` / `"de"` / `"it"` / `"zh"` / `"ja"` / `"ko"` |
+| `learnerLevel` | `"none"` / `"beginner"` / `"intermediate"` / `"regular"` |
 | `hooks.edit` / `hooks.write` / `hooks.bash` | `true` or `false` |
 | `exclude` | Array of glob patterns |
 | `skipIfSlowMs` | Number in milliseconds; `0` means never skip |
@@ -332,10 +410,14 @@ Changes take effect on the next Claude Code tool call — no restart needed.
 
 ## Session tools
 
+All commands below accept both forms: `vibe-code-explainer <cmd>` (if
+globally installed, on PATH) or `npx vibe-code-explainer <cmd>` (if per-project).
+
 ### Summary of what Claude has done
 
 ```bash
-npx vibe-code-explainer summary
+vibe-code-explainer summary
+# or: npx vibe-code-explainer summary
 ```
 
 Prints a report of every explained change in your current Claude Code session:
@@ -344,7 +426,8 @@ total changes, files touched, risk breakdown, and flagged unrelated files.
 ### Clear the session
 
 ```bash
-npx vibe-code-explainer session end
+vibe-code-explainer session end
+# or: npx vibe-code-explainer session end
 ```
 
 Clears the session state (tracked files and cache). Run this when you start a
@@ -353,7 +436,8 @@ new task so the drift-detection summary doesn't include old edits.
 ### Warm up the model
 
 ```bash
-npx vibe-code-explainer warmup
+vibe-code-explainer warmup
+# or: npx vibe-code-explainer warmup
 ```
 
 Sends a trivial diff to Ollama to pre-load the model. Useful if you closed and
@@ -365,17 +449,29 @@ slow (10–15 seconds) as the model gets loaded into VRAM.
 ## Uninstall
 
 ```bash
-npx vibe-code-explainer uninstall
+vibe-code-explainer uninstall
+# or: npx vibe-code-explainer uninstall
 ```
 
-Removes the PostToolUse hook entries from `.claude/settings.local.json` and
-deletes `code-explainer.config.json`. Other entries in `settings.local.json`
-(hooks from other tools, other settings) are preserved.
+The uninstaller auto-detects whether you have a project install, a global
+install, or both. If both exist, it asks which to remove.
+
+**Project uninstall:** removes the PostToolUse hook entries from
+`.claude/settings.local.json` and deletes `code-explainer.config.json`. Other
+entries (hooks from other tools, other settings) are preserved.
 
-Ollama and any pulled models stay installed. If you want to remove them:
+**Global uninstall:** removes the PostToolUse hooks from
+`~/.claude/settings.json` and deletes `~/.code-explainer.config.json`. The
+globally-installed npm package stays on disk — remove it with:
 
 ```bash
-ollama rm qwen2.5-coder:7b
+npm uninstall -g vibe-code-explainer
+```
+
+Ollama and any pulled models stay installed either way. To remove them:
+
+```bash
+ollama rm qwen3.5:4b
 # or whichever model you pulled
 ```
 
@@ -395,9 +491,10 @@ Most common causes, in order:
    ollama serve
    ```
    Then try another edit.
-3. **The engine is misconfigured.** Run `npx vibe-code-explainer config` and
-   check the engine and URL. Try switching to the Claude Code engine as a
-   test — if that works, Ollama is the issue.
+3. **The engine is misconfigured.** Run `vibe-code-explainer config` (or
+   `npx vibe-code-explainer config`) and check the engine and URL. Try
+   switching to the Claude Code engine as a test — if that works, Ollama is
+   the issue.
 4. **The file is excluded.** Check your `exclude` patterns in the config.
 
 ### The explanation took too long and got skipped
@@ -405,8 +502,8 @@ Most common causes, in order:
 Default timeout is 8 seconds. Cold starts with Ollama (first explanation
 after starting the service) can be 10–15 seconds. Two fixes:
 
-- Run `npx vibe-code-explainer warmup` right after starting Ollama.
-- Raise the timeout to 15 seconds via `npx vibe-code-explainer config →
+- Run `vibe-code-explainer warmup` right after starting Ollama.
+- Raise the timeout to 15 seconds via `vibe-code-explainer config →
   Latency timeout`.
 
 ### Explanations are low-quality
@@ -416,7 +513,7 @@ business logic, security-relevant changes). If explanations feel wrong on
 tricky diffs, switch to the Claude Code engine:
 
 ```bash
-npx vibe-code-explainer config
+vibe-code-explainer config
 # → Engine → Claude Code (native)
 ```
 
@@ -428,7 +525,7 @@ cost of API tokens per explanation.
 Add a glob pattern via the config menu:
 
 ```
-npx vibe-code-explainer config → File exclusions → Add a pattern
+vibe-code-explainer config → File exclusions → Add a pattern
 ```
 
 For example, `*.md` to skip all markdown files, or `src/generated/**` to skip
@@ -437,7 +534,7 @@ a whole directory.
 ### I want to turn off Bash explanations but keep Edit/Write
 
 ```
-npx vibe-code-explainer config → Enable/disable hooks
+vibe-code-explainer config → Enable/disable hooks
 ```
 
 Uncheck Bash, keep Edit and Write checked.

package/dist/{chunk-5NCRRHU7.js → chunk-JPDU5ASR.js}

@@ -15,6 +15,12 @@ var LANGUAGE_NAMES = {
   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");
@@ -25,6 +31,7 @@ var DEFAULT_CONFIG = {
   ollamaUrl: "http://localhost:11434",
   detailLevel: "standard",
   language: "en",
+  learnerLevel: "intermediate",
   hooks: {
     edit: true,
     write: true,
@@ -81,9 +88,10 @@ function loadConfig(configPath) {
 
 export {
   LANGUAGE_NAMES,
+  LEARNER_LEVEL_NAMES,
   CONFIG_FILENAME,
   getGlobalConfigPath,
   DEFAULT_CONFIG,
   loadConfig
 };
-//# sourceMappingURL=chunk-5NCRRHU7.js.map
+//# sourceMappingURL=chunk-JPDU5ASR.js.map

package/dist/chunk-JPDU5ASR.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\";\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  tool_response: string;\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: 8000,\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\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\nfunction tryReadJson(path: string): Partial<Config> | null {\n  if (!existsSync(path)) return null;\n  try {\n    return JSON.parse(readFileSync(path, \"utf-8\")) as Partial<Config>;\n  } catch {\n    return null;\n  }\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":";;;AAAA,SAAS,YAAY,oBAAoB;AACzC,SAAS,eAAe;AACxB,SAAS,YAAY;AAiBd,IAAM,iBAA2C;AAAA,EACtD,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAIO,IAAM,sBAAoD;AAAA,EAC/D,MAAM;AAAA,EACN,UAAU;AAAA,EACV,cAAc;AAAA,EACd,SAAS;AACX;AAoDO,IAAM,kBAAkB;AAExB,SAAS,sBAA8B;AAC5C,SAAO,KAAK,QAAQ,GAAG,6BAA6B;AACtD;AAEO,IAAM,iBAAyB;AAAA,EACpC,QAAQ;AAAA,EACR,aAAa;AAAA,EACb,WAAW;AAAA,EACX,aAAa;AAAA,EACb,UAAU;AAAA,EACV,cAAc;AAAA,EACd,OAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,MAAM;AAAA,EACR;AAAA,EACA,SAAS,CAAC,UAAU,WAAW,iBAAiB;AAAA,EAChD,cAAc;AAAA,EACd,YAAY;AAAA,IACV,iBAAiB;AAAA,MACf;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAEA,SAAS,YAAY,MAAc,SAAkC;AACnE,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG;AAAA,IACH,OAAO,EAAE,GAAG,KAAK,OAAO,GAAI,QAAQ,SAAS,CAAC,EAAG;AAAA,IACjD,YAAY;AAAA,MACV,GAAG,KAAK;AAAA,MACR,GAAI,QAAQ,cAAc,CAAC;AAAA,IAC7B;AAAA,EACF;AACF;AAEA,SAAS,YAAY,MAAsC;AACzD,MAAI,CAAC,WAAW,IAAI,EAAG,QAAO;AAC9B,MAAI;AACF,WAAO,KAAK,MAAM,aAAa,MAAM,OAAO,CAAC;AAAA,EAC/C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAYO,SAAS,WAAW,YAA4B;AACrD,QAAM,eAAe,YAAY,oBAAoB,CAAC;AACtD,QAAM,gBAAgB,YAAY,UAAU;AAE5C,MAAI,SAAS;AACb,MAAI,aAAc,UAAS,YAAY,QAAQ,YAAY;AAC3D,MAAI,cAAe,UAAS,YAAY,QAAQ,aAAa;AAC7D,SAAO;AACT;","names":[]}