@leonardo-marziali/ad-lfl-kit 0.0.0-development

package/exec.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+/*
+ * Locates a CLI shim across platforms.
+ *
+ * Hooks don't inherit a login shell, so PATH can be missing the toolchain
+ * entirely; looking beside process.execPath is the reliable first guess for
+ * anything installed alongside node (npx, npm). But the shim is only a bare
+ * name on POSIX — on Windows it's `<name>.cmd` — and it isn't always installed
+ * next to the node binary (system package managers, some version managers).
+ * So probe the real candidates, and fall back to a bare name for PATH lookup.
+ *
+ * `extraDirs` covers binaries that are never node-adjacent — a CLI installed
+ * by Homebrew or mise, say. Callers that pass nothing behave exactly as they
+ * did before the option existed.
+ */
+function resolveBin(name, options = {}) {
+  const { extraDirs = [] } = options;
+  const dirs = [path.dirname(process.execPath), ...extraDirs];
+  const candidates = process.platform === 'win32' ? [`${name}.cmd`, `${name}.exe`, name] : [name];
+
+  for (const dir of dirs) {
+    if (!dir) continue;
+    for (const candidate of candidates) {
+      const full = path.join(dir, candidate);
+      if (fs.existsSync(full)) return full;
+    }
+  }
+  return candidates[0];
+}
+
+/*
+ * cmd.exe consumes the argument string itself, and spawnSync only space-joins
+ * argv when shell:true — so quote each argument here. Runs of backslashes
+ * before a quote (and at the very end) are doubled first, since cmd.exe would
+ * otherwise treat them as escaping the quote.
+ */
+function quoteForCmd(arg) {
+  const value = String(arg)
+    .replace(/(\\*)"/g, '$1$1""')
+    .replace(/(\\+)$/, '$1$1');
+  return `"${value}"`;
+}
+
+/*
+ * Runs a CLI shim. On Windows the shim is a .cmd batch file, which Node
+ * refuses to spawn without a shell, so route through one there (with
+ * arguments quoted by hand); everywhere else spawn argv directly, so no shell
+ * ever parses a file path.
+ */
+function runBin(name, args, options = {}) {
+  const { extraDirs, ...spawnOptions } = options;
+  const bin = resolveBin(name, { extraDirs });
+
+  if (process.platform === 'win32') {
+    return spawnSync(quoteForCmd(bin), args.map(quoteForCmd), {
+      ...spawnOptions,
+      shell: true,
+      windowsVerbatimArguments: true,
+    });
+  }
+  return spawnSync(bin, args, spawnOptions);
+}
+
+module.exports = { resolveBin, quoteForCmd, runBin };

package/hook-input.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const fs = require('node:fs');
+
+/*
+ * Claude Code delivers the hook payload on stdin. Reading fd 0 throws when
+ * there's nothing attached (a hook invoked by hand, some test harnesses), and
+ * a hook that crashes on startup is worse than one that does nothing, so
+ * failure reads as "no input".
+ */
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/*
+ * Returns the parsed hook payload, or null when stdin held nothing parseable.
+ * Callers treat null as "not enough information to act" and return quietly.
+ */
+function readHookInput() {
+  try {
+    return JSON.parse(readStdin() || '{}');
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { readStdin, readHookInput };

package/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/*
+ * Agentic development lint-fix-loop kit: the session-scoped "track what was
+ * touched, then check it before the session ends" pattern, shared by the
+ * plugins in this marketplace.
+ */
+
+module.exports = {
+  ...require('./exec'),
+  ...require('./hook-input'),
+  ...require('./state'),
+  ...require('./track'),
+  ...require('./loop'),
+};

package/loop.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const path = require('node:path');
+const { readAttempts, writeAttempts, cleanup } = require('./state');
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+/*
+ * The Stop/SubagentStop half of the loop: check the files this session
+ * touched, and if they don't pass, block the stop with decision:"continue" so
+ * Claude is handed the failures and keeps working.
+ *
+ * The loop is capped so it can't run forever. Hitting the cap is not success —
+ * `onCap` gets the last report so the caller can say what it's giving up on
+ * (and, if it has a safe mechanical fallback, apply it) before the stop is
+ * allowed through.
+ *
+ * Every exit path either cleans up its state or persists an incremented
+ * attempt count; leaving both undone would strand the session in a loop that
+ * re-runs the same check with the same counter forever.
+ *
+ * Callers supply:
+ *   files       — absolute paths to check (already filtered to their scope)
+ *   fix         — optional, mechanically fixes what it can before checking
+ *   check       — returns { failed, report }
+ *   onCap       — optional, called instead of blocking once attempts run out
+ *   buildMessage— returns { stopReason?, systemMessage } for the block payload
+ *
+ * Returns { blocked, reason } describing which path was taken, so hooks and
+ * their tests can assert on the outcome rather than on stdout alone.
+ */
+function runFixLoop({
+  input,
+  dir,
+  stateFiles,
+  attemptsFile = path.join(dir, 'attempts.json'),
+  maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  files,
+  fix,
+  check,
+  onCap,
+  buildMessage,
+  write = (text) => process.stdout.write(text),
+}) {
+  if (!input) return { blocked: false, reason: 'no-input' };
+
+  if (!files || files.length === 0) {
+    cleanup(dir, stateFiles);
+    return { blocked: false, reason: 'no-files' };
+  }
+
+  const attempts = readAttempts(attemptsFile);
+
+  let outcome;
+  try {
+    if (fix) fix(files);
+    outcome = check(files);
+  } catch (error) {
+    /*
+     * A check that can't run at all is not a check that failed. Leave the
+     * state in place so the next stop retries, and let the caller report it —
+     * blocking on a broken toolchain would trap the session.
+     */
+    return { blocked: false, reason: 'error', error };
+  }
+
+  if (!outcome.failed) {
+    cleanup(dir, stateFiles);
+    return { blocked: false, reason: 'clean' };
+  }
+
+  if (attempts >= maxAttempts) {
+    if (onCap) onCap({ files, outcome, maxAttempts });
+    cleanup(dir, stateFiles);
+    return { blocked: false, reason: 'cap', outcome };
+  }
+
+  const attempt = attempts + 1;
+  writeAttempts(attemptsFile, attempt);
+
+  const { stopReason, systemMessage } = buildMessage({ attempt, maxAttempts, outcome, files });
+
+  write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: input.hook_event_name || 'Stop',
+        decision: 'continue',
+        ...(stopReason ? { stopReason } : {}),
+        systemMessage,
+      },
+    }),
+  );
+
+  return { blocked: true, reason: 'blocked', attempt, outcome };
+}
+
+module.exports = { runFixLoop, DEFAULT_MAX_ATTEMPTS };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@leonardo-marziali/ad-lfl-kit",
+  "version": "0.0.0-development",
+  "description": "Agentic development lint-fix-loop kit: session-scoped file tracking and a capped Stop-hook fix loop for Claude Code plugins.",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "hooks",
+    "lint",
+    "fix-loop"
+  ],
+  "author": {
+    "name": "Leonardo Marziali",
+    "url": "https://github.com/leonardo-marziali"
+  },
+  "homepage": "https://github.com/leonardo-marziali/agentic-development-kit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonardo-marziali/agentic-development-kit.git",
+    "directory": "packages/ad-lfl-kit"
+  },
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "exec.js",
+    "hook-input.js",
+    "state.js",
+    "track.js",
+    "loop.js"
+  ],
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"__tests__/*.test.js\"",
+    "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-coverage-exclude=\"**/__tests__/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info \"__tests__/*.test.js\""
+  }
+}

package/state.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+/*
+ * Session-scoped directory for a hook's own bookkeeping.
+ *
+ * Prefers the plugin's own data dir, which persists across plugin updates;
+ * falls back to tmp so hooks still work when CLAUDE_PLUGIN_DATA isn't set
+ * (a repo-local hook, or an older Claude Code). The namespace keeps two
+ * plugins' state apart under a shared base.
+ */
+function stateDir({ sessionId, namespace }) {
+  const base = process.env.CLAUDE_PLUGIN_DATA
+    ? path.join(process.env.CLAUDE_PLUGIN_DATA, namespace)
+    : path.join(os.tmpdir(), namespace);
+  return path.join(base, sessionId || 'unknown-session');
+}
+
+/*
+ * The tracked-file list is append-only newline-delimited text. Entries can go
+ * stale within a session — a file gets tracked, then deleted or renamed — so
+ * filter to what still exists on every read rather than trusting the list.
+ */
+function readTrackedFiles(listFile) {
+  if (!fs.existsSync(listFile)) return [];
+  return [...new Set(fs.readFileSync(listFile, 'utf8').split('\n').filter(Boolean))].filter(
+    (file) => fs.existsSync(file),
+  );
+}
+
+function appendTrackedFile(listFile, absPath) {
+  const existing = fs.existsSync(listFile)
+    ? fs.readFileSync(listFile, 'utf8').split('\n').filter(Boolean)
+    : [];
+  if (!existing.includes(absPath)) {
+    fs.appendFileSync(listFile, absPath + '\n');
+  }
+}
+
+function readAttempts(attemptsFile) {
+  if (!fs.existsSync(attemptsFile)) return 0;
+  try {
+    return JSON.parse(fs.readFileSync(attemptsFile, 'utf8')).count || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeAttempts(attemptsFile, count) {
+  fs.mkdirSync(path.dirname(attemptsFile), { recursive: true });
+  fs.writeFileSync(attemptsFile, JSON.stringify({ count }));
+}
+
+/*
+ * Removes only the files this hook owns, then drops the directory if that
+ * leaves it empty — a blind recursive rmSync would also wipe state another
+ * hook in the same session still has pending.
+ */
+function cleanup(dir, ownStateFiles) {
+  for (const name of ownStateFiles) {
+    try {
+      fs.rmSync(path.join(dir, name), { force: true });
+    } catch {
+      // best effort
+    }
+  }
+  try {
+    fs.rmdirSync(dir);
+  } catch {
+    // not empty (another hook's state still pending) or already gone
+  }
+}
+
+module.exports = {
+  stateDir,
+  readTrackedFiles,
+  appendTrackedFile,
+  readAttempts,
+  writeAttempts,
+  cleanup,
+};

package/track.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { appendTrackedFile } = require('./state');
+
+/*
+ * The PostToolUse half of the loop: records the file a tool just wrote, so the
+ * Stop hook only ever inspects files this session actually touched — never
+ * pre-existing content the user didn't ask us to police.
+ *
+ * `matches` decides what's in scope for the calling plugin and receives the
+ * resolved absolute path. Returns the path that was tracked, or null when the
+ * event wasn't one we care about — callers generally ignore the return and
+ * just let the hook exit.
+ */
+function trackTouchedFile({ input, listFile, matches }) {
+  if (!input) return null;
+  if (!/^(Edit|Write)$/.test(input.tool_name || '')) return null;
+
+  const filePath = input.tool_input?.file_path;
+  if (!filePath) return null;
+
+  /*
+   * Tool inputs may carry a relative path; it resolves against the session's
+   * cwd, not this hook process's, which can differ.
+   */
+  const cwd = input.cwd || process.cwd();
+  const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+
+  if (!fs.existsSync(absPath)) return null;
+  if (typeof matches === 'function' && !matches(absPath)) return null;
+
+  fs.mkdirSync(path.dirname(listFile), { recursive: true });
+  appendTrackedFile(listFile, absPath);
+  return absPath;
+}
+
+module.exports = { trackTouchedFile };