truecourse 0.5.1 → 0.5.2

package/README.md

@@ -90,12 +90,26 @@ truecourse rules llm --disable                 # Disable LLM rules
 
 ### Git Hooks
 
-TrueCourse can install a pre-commit hook that blocks commits with critical violations:
+TrueCourse can install a pre-commit hook that blocks commits introducing new violations at or above a configured severity:
 
 ```bash
 truecourse hooks install              # Install pre-commit hook
 truecourse hooks uninstall            # Remove pre-commit hook
-truecourse hooks status               # Show hook installation status
+truecourse hooks status               # Show hook status + config
+```
+
+On every commit the hook runs `truecourse analyze --diff` against the repo's last full analysis and blocks if any newly-introduced violation matches the configured block severities. **Commits will take as long as a full diff analysis** — on large repos that can be tens of seconds per commit. `truecourse hooks install` warns you and requires confirmation before writing the hook.
+
+**First-time setup:** run `truecourse analyze` once to establish a baseline. Without it the hook can't diff.
+
+**Bypass:** `git commit --no-verify` (standard git).
+
+**Configuration** — `hooks install` seeds `<repo>/.truecourse/hooks.yaml` with starter defaults; commit the file so your team shares one policy. The hook reads only from this file — if you delete it, the hook warns and passes every commit (no hidden code-level defaults). Current shape:
+
+```yaml
+pre-commit:
+  block-on: [critical, high]   # severities. Valid: info|low|medium|high|critical
+  llm: false                   # run LLM rules on every commit (tokens per commit)
 ```
 
 ### Telemetry
@@ -131,13 +145,14 @@ TrueCourse ships with **1,200+ deterministic rules** and **100 LLM rules** acros
 
 TrueCourse includes [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) for conversational analysis from within Claude Code.
 
-Run `truecourse add` to install skills to `.claude/skills/truecourse/` in your project.
+The first `truecourse analyze` (or `truecourse add`) in a fresh repo asks whether to install skills into `.claude/skills/truecourse/`. Re-runs skip the prompt if skills are already present. Pass `--install-skills` / `--no-skills` to bypass the prompt explicitly.
 
 | Skill | What it does |
 |---|---|
 | `/truecourse-analyze` | Runs analysis or diff check, summarizes results |
 | `/truecourse-list` | Shows full violation details |
 | `/truecourse-fix` | Lists fixable violations, applies changes |
+| `/truecourse-hooks` | Installs, configures, or removes the pre-commit hook |
 
 ## Language Support
 
@@ -172,6 +187,10 @@ pnpm build              # Build all packages
 
 TrueCourse collects anonymous usage data (event type, language, file count range, OS). No source code, file paths, or violation details are collected. Opt out with `truecourse telemetry disable` or `TRUECOURSE_TELEMETRY=0`.
 
+## Contact
+
+Questions, feedback, or security reports: **Mushegh Gevorgyan** — [mushegh@truecourse.dev](mailto:mushegh@truecourse.dev).
+
 ## License
 
 MIT

package/cli.mjs

@@ -130434,6 +130434,11 @@ var jsYaml = {
 };
 
 // tools/cli/src/commands/hooks.ts
+init_dist4();
+init_paths();
+init_registry();
+init_analysis_store();
+init_diff_in_process();
 init_helpers();
 var HOOK_IDENTIFIER = "# TrueCourse pre-commit hook";
 var HOOK_SCRIPT = `#!/bin/sh
@@ -130441,29 +130446,35 @@ ${HOOK_IDENTIFIER}
 # Installed by: truecourse hooks install
 # Bypass with: git commit --no-verify
 
-exec truecourse hooks run
+exec npx -y truecourse hooks run
+`;
+var SEVERITIES2 = ["info", "low", "medium", "high", "critical"];
+var HOOKS_YAML_TEMPLATE = `# TrueCourse pre-commit hook config.
+# Commit this file \u2014 it's the team-shared policy for what blocks a commit.
+# Check the live values with \`truecourse hooks status\`.
+pre-commit:
+  # Severities that block a commit when the diff surfaces NEW violations
+  # at that level. Valid: info, low, medium, high, critical.
+  block-on:
+    - critical
+    - high
+
+  # Run LLM-powered rules on every commit? Off by default (no tokens per
+  # commit). Set to true for deeper semantic checks at the commit gate \u2014
+  # each commit will then cost tokens.
+  llm: false
 `;
-var DEFAULT_BLOCK_ON = [
-  "security/deterministic/hardcoded-secret",
-  { severity: "critical" }
-];
-var DEFAULT_TIMEOUT_MS = 3e4;
 function findGitDir(from) {
   let dir = from;
   while (true) {
     const gitPath = path21.join(dir, ".git");
     if (fs16.existsSync(gitPath)) {
       const stat = fs16.statSync(gitPath);
-      if (stat.isDirectory()) {
-        return gitPath;
-      }
+      if (stat.isDirectory()) return gitPath;
       if (stat.isFile()) {
         const content = fs16.readFileSync(gitPath, "utf-8").trim();
         const match2 = content.match(/^gitdir:\s*(.+)$/);
-        if (match2) {
-          const resolved = path21.resolve(dir, match2[1]);
-          return resolved;
-        }
+        if (match2) return path21.resolve(dir, match2[1]);
       }
     }
     const parent = path21.dirname(dir);
@@ -130474,46 +130485,68 @@ function findGitDir(from) {
 function findProjectRoot(from) {
   let dir = from;
   while (true) {
-    if (fs16.existsSync(path21.join(dir, ".git"))) {
-      return dir;
-    }
+    if (fs16.existsSync(path21.join(dir, ".git"))) return dir;
     const parent = path21.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
-function parseTimeout(value) {
-  const match2 = value.match(/^(\d+)\s*(s|ms|m)?$/);
-  if (!match2) return DEFAULT_TIMEOUT_MS;
-  const num = parseInt(match2[1], 10);
-  const unit = match2[2] || "s";
-  if (unit === "ms") return num;
-  if (unit === "m") return num * 6e4;
-  return num * 1e3;
-}
 function loadConfig(projectRoot) {
   const configPath = path21.join(projectRoot, ".truecourse", "hooks.yaml");
-  if (!fs16.existsSync(configPath)) return {};
+  if (!fs16.existsSync(configPath)) return null;
+  let parsed;
   try {
     const raw = fs16.readFileSync(configPath, "utf-8");
-    return jsYaml.load(raw) || {};
-  } catch {
-    return {};
+    parsed = jsYaml.load(raw) || {};
+  } catch (err) {
+    console.error(`Error parsing ${configPath}: ${err.message}`);
+    process.exit(1);
   }
+  const preCommit = parsed["pre-commit"] ?? {};
+  const rawBlockOn = preCommit["block-on"];
+  if (!Array.isArray(rawBlockOn)) {
+    console.error(
+      `Invalid ${configPath}: \`pre-commit.block-on\` must be an array of severity names.`
+    );
+    console.error(`  Valid severities: ${SEVERITIES2.join(", ")}`);
+    process.exit(1);
+  }
+  const invalid = rawBlockOn.filter(
+    (s) => typeof s !== "string" || !SEVERITIES2.includes(s)
+  );
+  if (invalid.length > 0) {
+    console.error(
+      `Invalid ${configPath}: unknown value(s) in \`pre-commit.block-on\`: ${invalid.map((v) => JSON.stringify(v)).join(", ")}`
+    );
+    console.error(`  Valid severities: ${SEVERITIES2.join(", ")}`);
+    process.exit(1);
+  }
+  return {
+    blockOn: rawBlockOn,
+    llm: preCommit.llm === true,
+    configPath
+  };
 }
-function getBlockRules(config2) {
-  return config2["pre-commit"]?.["block-on"] ?? DEFAULT_BLOCK_ON;
-}
-function getTimeoutMs(config2) {
-  const raw = config2["pre-commit"]?.timeout;
-  return raw ? parseTimeout(raw) : DEFAULT_TIMEOUT_MS;
-}
-function runHooksInstall() {
+var INSTALL_WARNING = "The pre-commit hook runs `truecourse analyze --diff` on every commit.\nCommits will take as long as a full diff analysis of this repo \u2014\non large repos that can be tens of seconds per commit.";
+async function runHooksInstall() {
   const gitDir = findGitDir(process.cwd());
   if (!gitDir) {
     console.error("Error: Not a git repository.");
     process.exit(1);
   }
+  if (isInteractive()) {
+    O2.warn(INSTALL_WARNING);
+    const proceed = await ot2({
+      message: "Install the pre-commit hook?",
+      initialValue: false
+    });
+    if (q(proceed) || !proceed) {
+      pt("Install cancelled.");
+      process.exit(0);
+    }
+  } else {
+    console.log(INSTALL_WARNING);
+  }
   const hooksDir = path21.join(gitDir, "hooks");
   fs16.mkdirSync(hooksDir, { recursive: true });
   const hookPath = path21.join(hooksDir, "pre-commit");
@@ -130531,6 +130564,16 @@ function runHooksInstall() {
   fs16.writeFileSync(hookPath, HOOK_SCRIPT, { mode: 493 });
   console.log("TrueCourse pre-commit hook installed.");
   console.log(`  ${hookPath}`);
+  const projectRoot = findProjectRoot(process.cwd());
+  if (projectRoot) {
+    const cfgDir = path21.join(projectRoot, ".truecourse");
+    const cfgPath = path21.join(cfgDir, "hooks.yaml");
+    if (!fs16.existsSync(cfgPath)) {
+      fs16.mkdirSync(cfgDir, { recursive: true });
+      fs16.writeFileSync(cfgPath, HOOKS_YAML_TEMPLATE);
+      console.log(`  ${cfgPath} (starter config \u2014 edit to customize, commit to share with the team)`);
+    }
+  }
 }
 function runHooksUninstall() {
   const gitDir = findGitDir(process.cwd());
@@ -130568,125 +130611,97 @@ function runHooksStatus() {
   }
   const projectRoot = findProjectRoot(process.cwd());
   if (projectRoot) {
-    const configPath = path21.join(projectRoot, ".truecourse", "hooks.yaml");
-    if (fs16.existsSync(configPath)) {
-      console.log(`
-Config: ${configPath}`);
-      const config2 = loadConfig(projectRoot);
-      const blockRules = getBlockRules(config2);
-      console.log("Block on:");
-      for (const rule of blockRules) {
-        if (typeof rule === "string") {
-          console.log(`  - ${rule}`);
-        } else {
-          console.log(`  - severity: ${rule.severity}`);
-        }
-      }
-      const timeoutMs = getTimeoutMs(config2);
-      console.log(`Timeout: ${timeoutMs / 1e3}s`);
+    const cfg = loadConfig(projectRoot);
+    if (!cfg) {
+      console.log(
+        "\nNo `.truecourse/hooks.yaml` \u2014 hook has no policy. Run `truecourse hooks install` to generate one."
+      );
     } else {
-      console.log("\nNo config file. Using defaults (block on: security/deterministic/hardcoded-secret, severity: critical).");
-    }
-  }
-}
-function shouldBlock(violation, blockRules) {
-  for (const rule of blockRules) {
-    if (typeof rule === "string") {
-      if (violation.ruleKey === rule || violation.ruleKey.endsWith(`/${rule}`)) {
-        return true;
-      }
-    } else if (rule.severity) {
-      if (violation.severity.toLowerCase() === rule.severity.toLowerCase()) {
-        return true;
-      }
+      console.log(`
+Config: ${cfg.configPath}`);
+      console.log(`Block on severities: ${cfg.blockOn.join(", ")}`);
+      console.log(`LLM rules on commit: ${cfg.llm ? "enabled (tokens per commit)" : "disabled"}`);
     }
   }
-  return false;
 }
 async function runHooksRun() {
-  const startTime = Date.now();
   process.stdout.write("TrueCourse pre-commit check...");
   const projectRoot = findProjectRoot(process.cwd());
   if (!projectRoot) {
     console.log(" skipped (not a git repository)");
     process.exit(0);
   }
-  const config2 = loadConfig(projectRoot);
-  const blockRules = getBlockRules(config2);
-  const timeoutMs = getTimeoutMs(config2);
-  let stagedFiles;
+  let hasStaged = false;
   try {
     const output = execSync5("git diff --cached --name-only --diff-filter=ACM", {
       encoding: "utf-8",
       cwd: projectRoot
     }).trim();
-    stagedFiles = output ? output.split("\n") : [];
+    hasStaged = output.length > 0;
   } catch {
     console.log(" skipped (git error)");
     process.exit(0);
   }
-  if (stagedFiles.length === 0) {
+  if (!hasStaged) {
     console.log(" \u2714 passed (no staged files)");
     process.exit(0);
   }
-  let parseCode2;
-  let detectLanguage2;
-  let checkCodeRules2;
-  let CODE_RULES2;
-  try {
-    const analyzer = await Promise.resolve().then(() => (init_dist6(), dist_exports2));
-    parseCode2 = analyzer.parseCode;
-    detectLanguage2 = analyzer.detectLanguage;
-    checkCodeRules2 = analyzer.checkCodeRules;
-    CODE_RULES2 = analyzer.CODE_RULES;
-    await analyzer.initParsers();
-  } catch {
-    console.log(" skipped (analyzer not available)");
+  const cfg = loadConfig(projectRoot);
+  if (!cfg) {
+    console.log(" skipped");
+    console.error(
+      "No `.truecourse/hooks.yaml` found. The pre-commit hook has no policy to\nenforce \u2014 run `truecourse hooks install` to generate one."
+    );
     process.exit(0);
   }
-  const supportedFiles = stagedFiles.filter((f) => detectLanguage2(f) !== null);
-  if (supportedFiles.length === 0) {
-    console.log(" \u2714 passed");
-    process.exit(0);
+  const repoDir = resolveRepoDir(process.cwd());
+  const project = repoDir ? getProjectByPath(repoDir) ?? registerProject(repoDir) : null;
+  if (!project || !readLatest(project.path)) {
+    console.log("");
+    console.error(
+      "No baseline analysis yet. Run `truecourse analyze` once in this repo before\nthe pre-commit hook can block new violations. Or bypass this commit with\n`git commit --no-verify`."
+    );
+    process.exit(1);
   }
-  const allViolations = [];
-  for (const filePath of supportedFiles) {
-    if (Date.now() - startTime > timeoutMs) {
-      console.log("\n  Warning: timeout reached, skipping remaining files.");
-      break;
-    }
-    const language = detectLanguage2(filePath);
-    if (!language) continue;
-    let content;
-    try {
-      content = execSync5(`git show ":${filePath}"`, {
-        encoding: "utf-8",
-        cwd: projectRoot,
-        maxBuffer: 5 * 1024 * 1024
-        // 5MB
-      });
-    } catch {
-      continue;
-    }
-    try {
-      const tree = parseCode2(content, language);
-      const violations = checkCodeRules2(tree, filePath, content, CODE_RULES2, language);
-      allViolations.push(...violations);
-    } catch {
-      continue;
+  const abortController = new AbortController();
+  const onSigint = () => abortController.abort();
+  process.on("SIGINT", onSigint);
+  process.stdout.write(" running analysis...");
+  let newViolations;
+  try {
+    const { diff } = await diffInProcess(project, {
+      signal: abortController.signal,
+      enableLlmRulesOverride: cfg.llm,
+      // Pre-approved: the user opted into LLM-in-hook by setting llm: true
+      // in hooks.yaml, so we don't re-prompt for the token cost estimate.
+      onLlmEstimate: async () => true
+    });
+    newViolations = diff.newViolations;
+  } catch (err) {
+    console.log("");
+    if (err instanceof DOMException && err.name === "AbortError") {
+      console.error("Pre-commit check cancelled.");
+      process.exit(130);
     }
+    console.error(`Pre-commit check failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    process.removeListener("SIGINT", onSigint);
   }
-  const blocking = allViolations.filter((v) => shouldBlock(v, blockRules));
+  const blockSet = new Set(cfg.blockOn);
+  const blocking = newViolations.filter((v) => blockSet.has(v.severity.toLowerCase()));
   if (blocking.length === 0) {
-    console.log(" \u2714 passed");
+    console.log(` \u2714 passed (${newViolations.length} new violations, none at or above ${cfg.blockOn.join("/")})`);
     process.exit(0);
   }
   console.log("\n");
   for (const v of blocking) {
     const icon = severityIcon(v.severity);
     const color = severityColor(v.severity);
+    const location = v.filePath ? `${v.filePath}${v.lineStart ? `:${v.lineStart}` : ""}` : "(no file)";
     console.log(` ${color(`${icon} BLOCKED`)}: ${v.title}`);
-    console.log(`   ${v.filePath}:${v.lineStart} \u2014 ${v.content}`);
+    console.log(`   ${location} \u2014 ${v.content}`);
+    if (v.fixPrompt) console.log(`   Fix: ${v.fixPrompt}`);
     console.log("");
   }
   console.log("Commit blocked. Fix the issue or bypass with --no-verify.");
@@ -130695,7 +130710,7 @@ async function runHooksRun() {
 
 // tools/cli/src/index.ts
 var program2 = new Command();
-program2.name("truecourse").version("0.5.1").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
+program2.name("truecourse").version("0.5.2").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
 var dashboardCmd = program2.command("dashboard").description("Start the TrueCourse dashboard and open it in your browser").option("--reconfigure", "Re-prompt for console vs background service mode").option("--service", "Run as a background service (skips mode prompt)").option("--console", "Run in this terminal (skips mode prompt)").action(async (options) => {
   if (options.service && options.console) {
     console.error("error: --service and --console are mutually exclusive");
@@ -130774,8 +130789,8 @@ telemetryCmd.command("status").description("Show current telemetry status").acti
   }
 });
 var hooksCmd = program2.command("hooks").description("Manage git hooks");
-hooksCmd.command("install").description("Install pre-commit hook").action(() => {
-  runHooksInstall();
+hooksCmd.command("install").description("Install pre-commit hook").action(async () => {
+  await runHooksInstall();
 });
 hooksCmd.command("uninstall").description("Remove pre-commit hook").action(() => {
   runHooksUninstall();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "truecourse",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Visualize your codebase architecture as an interactive graph",
   "type": "module",
   "bin": {
@@ -21,6 +21,10 @@
     "node-windows": "^1.0.0-beta.8"
   },
   "license": "MIT",
+  "author": {
+    "name": "Mushegh Gevorgyan",
+    "email": "mushegh@truecourse.dev"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/truecourse-ai/truecourse"

package/skills/truecourse/truecourse-analyze/SKILL.md

@@ -18,7 +18,7 @@ Run architecture analysis on the current repository using TrueCourse.
 - **Full analysis** stashes any uncommitted changes, analyzes the clean working tree, then unstashes. The user's uncommitted work is preserved.
 - **Diff check** analyzes the full working tree (including uncommitted changes — it does NOT stash) and compares the result against the last full analysis baseline. The report lists violations newly introduced and violations resolved since that baseline. Prefer diff for in-progress work where the user is iterating on changes.
 - **Always invoke via `npx -y`** — without `-y`, npx will hang on the "Ok to proceed?" prompt whenever the user hasn't cached the latest `truecourse` version (which happens every time we publish a new release).
-- **LLM rules cost real money.** Never pass `--llm` without first relaying the cost estimate to the user and getting approval. See the LLM flow below.
+- **LLM rules cost tokens.** Never pass `--llm` without first relaying the token estimate to the user and getting approval. See the LLM flow below.
 
 ## Instructions
 
@@ -30,7 +30,7 @@ Ask the user whether they want a **full analysis** or a **diff check**. If they
 
 ### 2. Decide on LLM rules
 
-LLM rules add higher-value insights but cost money per run. Ask the user one question: **"Run LLM-powered rules this time?"** If the user is unsure, offer to run deterministic-only first (free, fast) and add LLM later.
+LLM rules add higher-value insights but cost tokens per run. Ask the user one question: **"Run LLM-powered rules this time?"** If the user is unsure, offer to run deterministic-only first (no tokens, fast) and add LLM later.
 
 - If **user approves LLM**: append `--llm` to the command.
 - If **user declines LLM or wants a free run**: append `--no-llm`.

package/skills/truecourse/truecourse-hooks/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: truecourse-hooks
+description: Install, configure, or remove the TrueCourse pre-commit hook
+user_invocable: true
+triggers:
+  - install the pre-commit hook
+  - set up truecourse hooks
+  - enable truecourse hook
+  - check hook status
+  - remove pre-commit hook
+  - change what the hook blocks
+  - edit hook config
+---
+
+# TrueCourse Hooks
+
+Install, configure, and manage the pre-commit hook that blocks new violations before they land in git.
+
+## Important
+
+- **Always invoke via `npx -y`** — without `-y`, npx will hang on the "Ok to proceed?" prompt whenever the user hasn't cached the latest `truecourse` version.
+- **The hook makes commits slower.** Every commit runs `truecourse analyze --diff`. On large repos that can be tens of seconds per commit. Make sure the user knows before you install.
+- **Baseline required.** The hook needs a `truecourse analyze` to have run at least once in the repo — otherwise every commit is blocked with "run analyze first". If the user hasn't, suggest running `/truecourse-analyze` first (or `npx -y truecourse analyze`).
+- **`hooks.yaml` is the single source of truth.** Installation creates `<repo>/.truecourse/hooks.yaml` with defaults; edit it to change policy. The file is meant to be committed so the whole team shares one hook config.
+
+## Instructions
+
+### 1. Figure out what the user wants
+
+- "install", "set up", "enable" → **Install flow**
+- "status", "is the hook active", "what does it block" → **Status flow**
+- "uninstall", "remove", "disable" → **Uninstall flow**
+- "change what blocks", "make it stricter/looser", "add/remove severities", "enable LLM" → **Configure flow**
+
+### 2. Install flow
+
+1. Tell the user the tradeoff upfront: commits will be slower; this repo needs a `truecourse analyze` baseline; policy lives in `.truecourse/hooks.yaml` which they should commit.
+2. Run:
+   ```
+   npx -y truecourse hooks install
+   ```
+3. Relay the output. Two files get created:
+   - `.git/hooks/pre-commit` (the script git invokes)
+   - `.truecourse/hooks.yaml` (starter policy, blocks `critical` and `high` by default, LLM off)
+4. If the user hasn't run a full analysis in this repo, suggest `/truecourse-analyze` — without it, every commit will be blocked with "no baseline" until they do.
+
+### 3. Status flow
+
+Run:
+```
+npx -y truecourse hooks status
+```
+Relay the output. It reports whether the hook is installed, the config path, the block severities, and whether LLM is on.
+
+### 4. Uninstall flow
+
+Run:
+```
+npx -y truecourse hooks uninstall
+```
+Only removes the git hook script. `hooks.yaml` is preserved (it's team policy, not install state).
+
+### 5. Configure flow
+
+The config lives at `<repo>/.truecourse/hooks.yaml`. Use the Read and Edit tools — do not shell out through `truecourse` for edits.
+
+Schema:
+```yaml
+pre-commit:
+  block-on: [critical, high]   # valid: info, low, medium, high, critical
+  llm: false                   # true = LLM rules on every commit (tokens per commit)
+```
+
+Common edits the user might ask for:
+- **Stricter** ("block medium too"): `block-on: [critical, high, medium]`
+- **Permissive** ("only block criticals"): `block-on: [critical]`
+- **Enable LLM** ("run full checks on commit"): set `llm: true`. Warn the user this spends tokens on every commit — confirm before flipping it.
+
+After editing, run `npx -y truecourse hooks status` so they can verify the parsed values match their intent.
+
+### 6. When the user hits a blocked commit
+
+If a user comes to you saying "my commit got blocked" or similar:
+- The hook's stdout already listed the blocking violations (file, line, title, severity).
+- Offer to run `/truecourse-fix` to apply fix suggestions to those violations.
+- If they want to ship anyway, remind them of `git commit --no-verify` (standard git bypass).