@fcamblor/on-changes-run 0.0.1

package/README.md

@@ -0,0 +1,75 @@
+# on-changes-run
+
+Run commands when files matching a glob pattern change between executions. Designed as a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) lifecycle hook (`Stop` / `SubagentStop`).
+
+## How it works
+
+1. On each run, `on-changes-run` snapshots the SHA-256 hashes of files that are in the git diff (unstaged + staged) and match the provided glob pattern.
+2. It compares this snapshot with the one stored from the previous execution.
+3. If any files changed between the two runs, it executes the specified commands in parallel.
+4. On the **first run**, it stores a baseline and exits successfully without running any commands.
+
+State is persisted in `<git-root>/.claude/on-changes-run.state.json`.
+
+## Installation
+
+```bash
+npx on-changes-run --on '<glob>' --exec '<command>'
+```
+
+No installation needed when using `npx`.
+
+## Usage
+
+```bash
+npx on-changes-run \
+  --on "frontend/**/*.ts" \
+  --exec "cd frontend && npm run lint" \
+  --exec "cd frontend && npm run typecheck"
+```
+
+### Options
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--on <glob>` | Glob pattern to match changed files | Yes |
+| `--exec <command>` | Shell command to run (repeatable) | Yes |
+| `--exec-timeout <seconds>` | Timeout per command (default: 300) | No |
+
+### Exit codes
+
+- `0` — All commands succeeded (or no changes detected)
+- `1` — At least one command failed (error output is printed to stderr)
+
+## Claude Code Hook Configuration
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx on-changes-run --on 'frontend/**/*.ts' --exec 'cd frontend && npm run lint' --exec 'cd frontend && npm run typecheck'"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx on-changes-run --on 'backend/**/*.kt' --exec 'cd backend && ./gradlew lint' --exec 'cd backend && ./gradlew build'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+When a command fails, its stdout/stderr is printed to stderr so the LLM can interpret the errors and fix the issues.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import picomatch from 'picomatch';
+import { getGitRoot, getHeadSha, getDiffFiles } from './git.js';
+import { computeHashes, loadState, saveState, findChangedFiles } from './state.js';
+import { executeAll, printFailures } from './executor.js';
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+function parseCliArgs() {
+    const program = new Command();
+    program
+        .name('on-changes-run')
+        .description('Run commands when files matching a glob pattern change between executions')
+        .requiredOption('--on <glob>', 'Glob pattern to match changed files against')
+        .requiredOption('--exec <command>', 'Command to execute (repeatable, run in parallel)', collect, [])
+        .option('--exec-timeout <seconds>', 'Timeout per command in seconds', '300')
+        .parse(process.argv);
+    const opts = program.opts();
+    return {
+        on: opts.on,
+        exec: opts.exec,
+        execTimeout: parseInt(opts.execTimeout, 10),
+    };
+}
+async function readStdin() {
+    if (process.stdin.isTTY) {
+        return '';
+    }
+    return new Promise((resolve) => {
+        const chunks = [];
+        process.stdin.on('data', (chunk) => chunks.push(chunk));
+        process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        process.stdin.on('error', () => resolve(''));
+        setTimeout(() => {
+            process.stdin.destroy();
+            resolve(Buffer.concat(chunks).toString('utf-8'));
+        }, 1000);
+    });
+}
+async function main() {
+    const args = parseCliArgs();
+    // Consume stdin (Claude Code hook context) without blocking
+    await readStdin();
+    const gitRoot = await getGitRoot();
+    const headSha = await getHeadSha();
+    // Get files in git diff (unstaged + staged)
+    const diffFiles = await getDiffFiles();
+    // Filter diff files by glob pattern
+    const isMatch = picomatch(args.on);
+    const matchingFiles = diffFiles.filter((f) => isMatch(f));
+    // Compute hashes for matching diff files
+    const currentHashes = await computeHashes(gitRoot, matchingFiles);
+    const currentState = { headSha, fileHashes: currentHashes };
+    // Load previous state
+    const previousState = loadState(gitRoot, args.on);
+    if (!previousState) {
+        // First run: store baseline, exit successfully
+        process.stderr.write(`on-changes-run: first run for pattern "${args.on}", storing baseline (${matchingFiles.length} files tracked)\n`);
+        await saveState(gitRoot, args.on, currentState);
+        process.exit(0);
+    }
+    // Detect changes between previous and current snapshots
+    const changedFiles = findChangedFiles(previousState.fileHashes, currentHashes);
+    // Always save new state
+    await saveState(gitRoot, args.on, currentState);
+    if (changedFiles.length === 0) {
+        process.exit(0);
+    }
+    process.stderr.write(`on-changes-run: ${changedFiles.length} file(s) changed matching "${args.on}", running ${args.exec.length} command(s)\n`);
+    // Run all commands in parallel
+    const timeoutMs = args.execTimeout * 1000;
+    const results = await executeAll(args.exec, timeoutMs);
+    const failures = results.filter((r) => r.exitCode !== 0);
+    if (failures.length > 0) {
+        printFailures(failures);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+main().catch((err) => {
+    process.stderr.write(`on-changes-run: fatal error: ${err}\n`);
+    process.exit(1);
+});

package/dist/executor.d.ts

@@ -0,0 +1,7 @@
+import type { CommandResult } from './types.js';
+/** Execute a single shell command and capture its output */
+export declare function executeCommand(command: string, timeoutMs: number): Promise<CommandResult>;
+/** Execute multiple commands in parallel */
+export declare function executeAll(commands: string[], timeoutMs: number): Promise<CommandResult[]>;
+/** Print details of failed commands to stderr */
+export declare function printFailures(failures: CommandResult[]): void;

package/dist/executor.js

@@ -0,0 +1,38 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+/** Execute a single shell command and capture its output */
+export async function executeCommand(command, timeoutMs) {
+    try {
+        const { stdout, stderr } = await execAsync(command, {
+            maxBuffer: 10 * 1024 * 1024,
+            timeout: timeoutMs,
+        });
+        return { command, exitCode: 0, stdout, stderr };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            command,
+            exitCode: err.code ?? 1,
+            stdout: err.stdout ?? '',
+            stderr: err.stderr ?? '',
+        };
+    }
+}
+/** Execute multiple commands in parallel */
+export async function executeAll(commands, timeoutMs) {
+    return Promise.all(commands.map((cmd) => executeCommand(cmd, timeoutMs)));
+}
+/** Print details of failed commands to stderr */
+export function printFailures(failures) {
+    for (const f of failures) {
+        process.stderr.write(`\n--- FAILED: ${f.command} (exit code ${f.exitCode}) ---\n`);
+        if (f.stdout) {
+            process.stderr.write(`[stdout]\n${f.stdout}\n`);
+        }
+        if (f.stderr) {
+            process.stderr.write(`[stderr]\n${f.stderr}\n`);
+        }
+    }
+}

package/dist/git.d.ts

@@ -0,0 +1,6 @@
+/** Returns absolute path to git repository root */
+export declare function getGitRoot(): Promise<string>;
+/** Returns current HEAD commit SHA */
+export declare function getHeadSha(): Promise<string>;
+/** Returns deduplicated list of files in the git diff (unstaged + staged), relative to git root */
+export declare function getDiffFiles(): Promise<string[]>;

package/dist/git.js

@@ -0,0 +1,30 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** Returns absolute path to git repository root */
+export async function getGitRoot() {
+    const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel']);
+    return stdout.trim();
+}
+/** Returns current HEAD commit SHA */
+export async function getHeadSha() {
+    const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD']);
+    return stdout.trim();
+}
+/** Returns deduplicated list of files in the git diff (unstaged + staged), relative to git root */
+export async function getDiffFiles() {
+    const [unstaged, staged] = await Promise.all([
+        execFileAsync('git', ['diff', '--name-only', 'HEAD']).catch(() => ({ stdout: '' })),
+        execFileAsync('git', ['diff', '--cached', '--name-only']).catch(() => ({ stdout: '' })),
+    ]);
+    const files = new Set();
+    for (const line of unstaged.stdout.trim().split('\n')) {
+        if (line)
+            files.add(line);
+    }
+    for (const line of staged.stdout.trim().split('\n')) {
+        if (line)
+            files.add(line);
+    }
+    return [...files];
+}

package/dist/state.d.ts

@@ -0,0 +1,11 @@
+import type { PatternState } from './types.js';
+/** Compute SHA-256 hash of a file's content on disk */
+export declare function computeFileHash(absolutePath: string): Promise<string>;
+/** Compute hashes for multiple files in parallel */
+export declare function computeHashes(gitRoot: string, relativePaths: string[]): Promise<Record<string, string>>;
+/** Load previous state for a given pattern from the state file */
+export declare function loadState(gitRoot: string, pattern: string): PatternState | null;
+/** Save state for a given pattern to the state file */
+export declare function saveState(gitRoot: string, pattern: string, state: PatternState): Promise<void>;
+/** Find files that changed between two snapshots */
+export declare function findChangedFiles(previous: Record<string, string>, current: Record<string, string>): string[];

package/dist/state.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const STATE_FILENAME = '.claude/on-changes-run.state.json';
+/** Compute SHA-256 hash of a file's content on disk */
+export async function computeFileHash(absolutePath) {
+    const content = await readFile(absolutePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+/** Compute hashes for multiple files in parallel */
+export async function computeHashes(gitRoot, relativePaths) {
+    const entries = await Promise.all(relativePaths.map(async (rel) => {
+        try {
+            const hash = await computeFileHash(join(gitRoot, rel));
+            return [rel, hash];
+        }
+        catch {
+            // File may have been deleted since git diff was run
+            return null;
+        }
+    }));
+    return Object.fromEntries(entries.filter((e) => e !== null));
+}
+/** Load previous state for a given pattern from the state file */
+export function loadState(gitRoot, pattern) {
+    const statePath = join(gitRoot, STATE_FILENAME);
+    try {
+        const raw = readFileSync(statePath, 'utf-8');
+        const stateFile = JSON.parse(raw);
+        return stateFile[pattern] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Save state for a given pattern to the state file */
+export async function saveState(gitRoot, pattern, state) {
+    const statePath = join(gitRoot, STATE_FILENAME);
+    let stateFile = {};
+    try {
+        const raw = await readFile(statePath, 'utf-8');
+        stateFile = JSON.parse(raw);
+    }
+    catch {
+        // File doesn't exist yet, start fresh
+    }
+    stateFile[pattern] = state;
+    await mkdir(join(gitRoot, '.claude'), { recursive: true });
+    await writeFile(statePath, JSON.stringify(stateFile, null, 2) + '\n');
+}
+/** Find files that changed between two snapshots */
+export function findChangedFiles(previous, current) {
+    const changed = [];
+    // Files that are new or have different hashes
+    for (const [path, hash] of Object.entries(current)) {
+        if (previous[path] !== hash) {
+            changed.push(path);
+        }
+    }
+    // Files that were in the previous snapshot but not in the current one
+    for (const path of Object.keys(previous)) {
+        if (!(path in current)) {
+            changed.push(path);
+        }
+    }
+    return changed;
+}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+/** Per-glob-pattern persisted state */
+export interface PatternState {
+    /** HEAD commit SHA at time of last run */
+    headSha: string;
+    /** Map of relative file path -> content hash (SHA-256 hex) */
+    fileHashes: Record<string, string>;
+}
+/** Root state file shape, keyed by glob pattern */
+export interface StateFile {
+    [globPattern: string]: PatternState;
+}
+/** Parsed CLI arguments */
+export interface CliArgs {
+    on: string;
+    exec: string[];
+    execTimeout: number;
+}
+/** Result of running a single command */
+export interface CommandResult {
+    command: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fcamblor/on-changes-run",
+  "version": "0.0.1",
+  "description": "Claude Code lifecycle hook: run commands when file changes are detected",
+  "license": "MIT",
+  "author": {
+    "name": "fcamblor"
+  },
+  "type": "module",
+  "bin": {
+    "on-changes-run": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "picomatch": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.0",
+    "@types/node": "^22.0.0",
+    "@types/picomatch": "^3.0.0"
+  }
+}