@nolrm/contextkit 0.16.4 → 0.17.0

package/README.md

@@ -114,7 +114,7 @@ Each platform generates bridge files that the AI tool auto-reads. If a bridge fi
 /fix        # diagnose and fix bugs
 ```
 
-**Claude Code** — `CLAUDE.md` uses `@` imports to auto-load all standards into context every session (no manual reads needed, saves tokens). Skills in `.claude/skills/`.
+**Claude Code** — `CLAUDE.md` uses `@` imports to auto-load all standards into context every session (no manual reads needed, saves tokens). Skills in `.claude/skills/`. Also writes a PostToolUse hook to `.claude/settings.json` that runs format+lint after every file edit — auto-detected for Node.js (npm/pnpm/yarn/bun), Go, and Python.
 
 ```bash
 /analyze    # scan codebase and generate standards
@@ -258,7 +258,9 @@ If you have a screenshot, mockup, or design image relevant to the task, paste or
 
 ---
 
-## Git Hooks & Quality Gates
+## Hooks & Quality Gates
+
+ContextKit installs two kinds of hooks. **Git hooks** (pre-push, commit-msg) enforce quality at push time for the whole team. For **Claude Code** installs, a **PostToolUse hook** is also written to `.claude/settings.json` — it runs format+lint after every file edit in a Claude Code session, catching failures immediately rather than at push time.
 
 ContextKit can optionally install Git hooks during `ck install`. Uses `git config core.hooksPath` to point Git at `.contextkit/hooks/` — no external dependencies like Husky required. Works in any git repo, not just Node.js projects.
 

package/lib/integrations/claude-integration.js

@@ -44,6 +44,25 @@ class ClaudeIntegration extends BaseIntegration {
     await fs.ensureDir('.claude/skills');
     await this.addToGitignore('.claude/settings.local.json');
     await this.removeLegacyFiles();
+    await this._installHook();
+  }
+
+  async _installHook() {
+    try {
+      const HookDetector = require('../utils/hook-detector');
+      const ClaudeSettings = require('../utils/claude-settings');
+      const command = await new HookDetector().detect();
+      if (command) {
+        await new ClaudeSettings().addPostToolUseHook(command);
+        console.log(chalk.green(`  ✓ PostToolUse hook: ${command}`));
+      } else {
+        console.log(
+          chalk.dim(chalk.yellow('  ⚠  No format/lint tooling detected — PostToolUse hook skipped'))
+        );
+      }
+    } catch (err) {
+      console.log(chalk.yellow(`  ⚠  Could not install PostToolUse hook: ${err.message}`));
+    }
   }
 
   async addToGitignore(entry) {

package/lib/integrations/claude-integration.md

@@ -0,0 +1,39 @@
+# claude-integration.js
+
+The Claude Code platform integration. Installs `CLAUDE.md`, `.claude/rules/`, `.claude/skills/`, and a PostToolUse hook in `.claude/settings.json`.
+
+## Extends
+
+`BaseIntegration`
+
+## install(force = false)
+
+Runs the full Claude Code setup:
+1. Writes bridge file (`CLAUDE.md`) and generated files (rules, skills) via `super.install()`
+2. Ensures `.claude/skills/` directory exists
+3. Adds `.claude/settings.local.json` to `.gitignore`
+4. Removes legacy `.claude/commands/` files
+5. Detects project tooling and installs a PostToolUse hook in `.claude/settings.json`
+
+### Hook Installation (step 5)
+
+Uses `HookDetector` to detect the right format+lint command for the project (Node.js, Go, or Python). If a command is found, `ClaudeSettings.addPostToolUseHook()` writes it to `.claude/settings.json` with a `_contextkit: true` marker.
+
+- On success: logs `✓ PostToolUse hook: <command>`
+- No tooling detected: logs a dim yellow skip message
+- Any error: logs a yellow warning and continues (graceful degradation)
+
+Re-running `install()` (e.g. via `ck update → refreshIntegrations()`) replaces the existing ContextKit hook rather than duplicating it.
+
+## generatedFiles
+
+Listed in the constructor. Does **not** include `.claude/settings.json` — that file is a merge target, not overwritten.
+
+## Key Files Written
+
+| File | Type | Purpose |
+|---|---|---|
+| `CLAUDE.md` | Bridge (merged) | Auto-loaded every Claude Code session |
+| `.claude/rules/contextkit-*.md` | Generated | Scoped rules for standards, testing, code style |
+| `.claude/skills/*/SKILL.md` | Generated | All slash commands |
+| `.claude/settings.json` | Merged | PostToolUse hook entry (`_contextkit: true`) |

package/lib/utils/claude-settings.js

@@ -0,0 +1,67 @@
+const fs = require('fs-extra');
+const chalk = require('chalk');
+
+const SETTINGS_PATH = '.claude/settings.json';
+
+class ClaudeSettings {
+  async read() {
+    if (!(await fs.pathExists(SETTINGS_PATH))) return {};
+    try {
+      const raw = await fs.readFile(SETTINGS_PATH, 'utf8');
+      return JSON.parse(raw);
+    } catch {
+      console.warn(
+        chalk.yellow(`  ⚠  .claude/settings.json contains invalid JSON — skipping hook merge`)
+      );
+      return {};
+    }
+  }
+
+  async write(settings) {
+    await fs.ensureDir('.claude');
+    await fs.writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+  }
+
+  async addPostToolUseHook(command) {
+    if (!command) throw new Error('hook command is required');
+
+    const settings = await this.read();
+    settings.hooks = settings.hooks || {};
+
+    if (!Array.isArray(settings.hooks.PostToolUse)) {
+      if (settings.hooks.PostToolUse !== undefined) {
+        settings.hooks._contextkit_original_invalid = settings.hooks.PostToolUse;
+      }
+      settings.hooks.PostToolUse = [];
+    }
+
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => !entry._contextkit);
+
+    settings.hooks.PostToolUse.push({
+      matcher: 'Edit|Write',
+      hooks: [{ type: 'command', command }],
+      _contextkit: true,
+    });
+
+    await this.write(settings);
+  }
+
+  async removeContextKitHooks() {
+    const settings = await this.read();
+    if (!Array.isArray(settings.hooks?.PostToolUse)) return;
+
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => !entry._contextkit);
+
+    if (settings.hooks.PostToolUse.length === 0) {
+      delete settings.hooks.PostToolUse;
+    }
+
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+
+    await this.write(settings);
+  }
+}
+
+module.exports = ClaudeSettings;

package/lib/utils/claude-settings.md

@@ -0,0 +1,52 @@
+# claude-settings.js
+
+Reads, merges, and writes `.claude/settings.json` safely — adding or removing ContextKit-owned entries without clobbering user content.
+
+## Exports
+
+`ClaudeSettings` — class
+
+## Public API
+
+### `read() → Promise<object>`
+
+Returns the parsed contents of `.claude/settings.json`, or `{}` if the file does not exist. On invalid JSON, logs a yellow warning and returns `{}` (does not throw).
+
+### `write(settings) → Promise<void>`
+
+Writes the settings object to `.claude/settings.json` with 2-space indentation and a trailing newline. Creates `.claude/` if it does not exist.
+
+### `addPostToolUseHook(command) → Promise<void>`
+
+Adds a ContextKit-owned PostToolUse hook entry. Replaces any existing `_contextkit: true` entry rather than duplicating. Merges into existing file content — other keys (permissions, other hooks) are preserved.
+
+Throws `Error('hook command is required')` if `command` is falsy.
+
+Hook entry written:
+```json
+{
+  "matcher": "Edit|Write",
+  "hooks": [{ "type": "command", "command": "<command>" }],
+  "_contextkit": true
+}
+```
+
+### `removeContextKitHooks() → Promise<void>`
+
+Removes all `PostToolUse` entries where `_contextkit: true`. If the array becomes empty, deletes the `PostToolUse` key. If `hooks` becomes empty, deletes the `hooks` key. No-op if the file is absent.
+
+## Usage Example
+
+```javascript
+const ClaudeSettings = require('./claude-settings');
+
+const cs = new ClaudeSettings();
+await cs.addPostToolUseHook('pnpm run format && pnpm run lint --fix 2>&1 | tail -20');
+// → writes .claude/settings.json, merging into existing content
+```
+
+## Edge Cases & Notes
+
+- `PostToolUse` that is not an array: the original value is preserved under `_contextkit_original_invalid`, and a fresh array is started for ContextKit's entry
+- Invalid JSON in existing file: returns `{}` with a warning — the file is NOT overwritten (protects corrupted user files)
+- Thread safety: no file locking; not a concern for a CLI tool

package/lib/utils/hook-detector.js

@@ -0,0 +1,138 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+
+class HookDetector {
+  _commandExists(name) {
+    try {
+      execSync(`which ${name}`, { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  _pmPrefix(pm) {
+    switch (pm) {
+      case 'pnpm':
+        return 'pnpm run';
+      case 'yarn':
+        return 'yarn';
+      case 'bun':
+        return 'bun run';
+      default:
+        return 'npm run';
+    }
+  }
+
+  _lintFixCmd(pm, hasLintFix, hasLint) {
+    if (hasLintFix) {
+      switch (pm) {
+        case 'yarn':
+          return 'yarn lint:fix';
+        default:
+          return `${this._pmPrefix(pm)} lint:fix`;
+      }
+    }
+    if (hasLint) {
+      switch (pm) {
+        case 'pnpm':
+          return 'pnpm run lint --fix';
+        case 'yarn':
+          return 'yarn lint --fix';
+        case 'bun':
+          return 'bun run lint --fix';
+        default:
+          return 'npm run lint -- --fix';
+      }
+    }
+    return null;
+  }
+
+  async _detectNode(projectDir) {
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (!(await fs.pathExists(pkgPath))) return null;
+
+    let packageJson;
+    try {
+      const raw = await fs.readFile(pkgPath, 'utf8');
+      packageJson = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+
+    const scripts = packageJson.scripts || {};
+
+    let pm = 'npm';
+    if (await fs.pathExists(path.join(projectDir, 'bun.lockb'))) {
+      pm = 'bun';
+    } else if (await fs.pathExists(path.join(projectDir, 'pnpm-lock.yaml'))) {
+      pm = 'pnpm';
+    } else if (await fs.pathExists(path.join(projectDir, 'yarn.lock'))) {
+      pm = 'yarn';
+    }
+
+    const hasFormat = Boolean(scripts.format);
+    const hasLintFix = Boolean(scripts['lint:fix']);
+    const hasLint = Boolean(scripts.lint);
+
+    const parts = [];
+
+    if (hasFormat) {
+      const prefix = this._pmPrefix(pm);
+      parts.push(pm === 'yarn' ? `yarn format` : `${prefix} format`);
+    }
+
+    const lintCmd = this._lintFixCmd(pm, hasLintFix, hasLint);
+    if (lintCmd) {
+      parts.push(lintCmd);
+    }
+
+    if (parts.length === 0) return null;
+
+    return parts.join(' && ') + ' 2>&1 | tail -20';
+  }
+
+  async _detectGo(projectDir) {
+    if (!(await fs.pathExists(path.join(projectDir, 'go.mod')))) return null;
+
+    const parts = [];
+    if (this._commandExists('gofmt')) parts.push('gofmt -w .');
+    if (this._commandExists('golangci-lint')) parts.push('golangci-lint run 2>&1 | tail -20');
+
+    if (parts.length === 0) return null;
+
+    const cmd = parts.join(' && ');
+    // If only gofmt, add tail ourselves; if golangci-lint is present, it already has tail
+    return parts.length === 1 && parts[0] === 'gofmt -w .' ? cmd : cmd;
+  }
+
+  async _detectPython(projectDir) {
+    const hasPyproject = await fs.pathExists(path.join(projectDir, 'pyproject.toml'));
+    const hasRequirements = await fs.pathExists(path.join(projectDir, 'requirements.txt'));
+    if (!hasPyproject && !hasRequirements) return null;
+
+    const parts = [];
+    if (this._commandExists('black')) parts.push('black .');
+    if (this._commandExists('ruff')) parts.push('ruff check --fix . 2>&1 | tail -20');
+
+    if (parts.length === 0) return null;
+
+    return parts.join(' && ');
+  }
+
+  async detect(projectDir = process.cwd()) {
+    const node = await this._detectNode(projectDir);
+    if (node) return node;
+
+    const go = await this._detectGo(projectDir);
+    if (go) return go;
+
+    const python = await this._detectPython(projectDir);
+    if (python) return python;
+
+    return null;
+  }
+}
+
+module.exports = HookDetector;

package/lib/utils/hook-detector.md

@@ -0,0 +1,42 @@
+# hook-detector.js
+
+Detects the right PostToolUse hook command for a project based on its language, package manager, and available scripts.
+
+## Exports
+
+`HookDetector` — class
+
+## Public API
+
+### `detect(projectDir = process.cwd()) → Promise<string | null>`
+
+Returns a shell command string suitable for use as a Claude Code PostToolUse hook, or `null` if no format/lint tooling is detected.
+
+Tries three detectors in order: Node.js → Go → Python.
+
+## Usage Example
+
+```javascript
+const HookDetector = require('./hook-detector');
+
+const command = await new HookDetector().detect('/path/to/project');
+// → "pnpm run format && pnpm run lint --fix 2>&1 | tail -20"
+// → null (if no tooling found)
+```
+
+## Detection Logic
+
+| Stack | Trigger | PM detection | Command built from |
+|---|---|---|---|
+| Node.js | `package.json` exists | lockfile (`bun.lockb` > `pnpm-lock.yaml` > `yarn.lock` > `npm`) | `scripts.format`, `scripts['lint:fix']`, `scripts.lint` |
+| Go | `go.mod` exists | n/a | `gofmt` and/or `golangci-lint` (via `which`) |
+| Python | `pyproject.toml` or `requirements.txt` | n/a | `black` and/or `ruff` (via `which`) |
+
+For Node.js: `lint:fix` takes priority over `lint`. If only `lint` is present, `--fix` is appended (npm uses `-- --fix` separator; pnpm/yarn/bun pass args directly).
+
+## Edge Cases & Notes
+
+- Malformed `package.json` → returns `null`, does not throw
+- No scripts in `package.json` → returns `null`
+- Go/Python tools not on PATH → returns `null`
+- Node.js takes priority when multiple stack markers coexist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.16.4",
+  "version": "0.17.0",
   "description": "ContextKit - Context Engineering for AI Development. Provide rich context to AI through structured MD files with standards, code guides, and documentation. Works with Cursor, Claude, Aider, VS Code Copilot, and more.",
   "main": "lib/index.js",
   "bin": {