@thejoseki/clawform 2.3.0 → 2.3.2

package/src/hooks/block-dangerous.js

@@ -1,62 +1,62 @@
-#!/usr/bin/env node
-/**
- * Clawform PreToolUse hook — CLI entry. Reads JSON event from stdin, resolves
- * the consumer's project root from the EVENT's `cwd` field (Claude Code sets
- * this on every hook event), and delegates to the pure `evaluate` in
- * block-dangerous-eval.js. Exits 2 with stderr on block.
- *
- * Why `event.cwd` instead of `process.env.CLAUDE_PROJECT_DIR`: the Claude Code
- * hook docs (anthropic.com/docs/claude-code/hooks) document `cwd` as part of
- * the stdin event payload but make no guarantee about CLAUDE_PROJECT_DIR being
- * set in the hook process env, particularly when the hook is registered via a
- * plugin's `hooks.json` (where `${CLAUDE_PLUGIN_ROOT}` substitutes into the
- * command path but the runtime env is undocumented). Relying on the env var
- * here risks a non-Acme consumer silently inheriting THIS repo's dogfood config
- * — exactly the security bug the composable refactor exists to prevent.
- * Fallback: process.env.CLAUDE_PROJECT_DIR → process.cwd() (the latter is
- * useful for dev-mode invocations from the repo root).
- *
- * Fail-LOUD on event-parse error → write to stderr + exit 0 so a buggy hook
- * never silently disables the safety net (the alternative — fail closed —
- * would deny every Bash call on any unrelated parse problem).
- *
- * Fail-LOUD on config-load error → write to stderr + continue with an empty
- * legacy-prefix list. Built-in blockers (delete-stack, s3 rb --force) still
- * fire; only the legacy-freeze gate is dropped, which is the correct outcome
- * when the consumer's clawform.config.json is broken or missing.
- */
-
-import { readFileSync } from 'node:fs';
-import { evaluate } from './block-dangerous-eval.js';
-import { loadProjectConfig } from '../lib/project-config.js';
-
-let event;
-try {
-  event = JSON.parse(readFileSync(0, 'utf8'));
-} catch (err) {
-  process.stderr.write(`[clawform hook] event parse failed (allowing tool call): ${err.message}\n`);
-  process.exit(0);
-}
-
-const projectDir = (typeof event?.cwd === 'string' && event.cwd) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
-
-let legacyPrefixes = [];
-try {
-  const cfg = loadProjectConfig({ projectDir });
-  legacyPrefixes = cfg.legacy_prefixes || [];
-} catch (err) {
-  process.stderr.write(`[clawform hook] consumer config load failed at ${projectDir} (legacy-freeze gate disabled, built-ins still fire): ${err.message}\n`);
-}
-
-const { block, warn, reason } = evaluate(event, { legacyPrefixes });
-if (block) {
-  process.stderr.write(`[clawform hook] ${reason}\n`);
-  process.exit(2);
-}
-
-// Advisory: the command runs, but the operator is told what the guard could
-// not see. Same posture as the catalog-freshness hook.
-if (warn) {
-  process.stderr.write(`[clawform hook] ${reason}\n`);
-  process.exit(0);
-}
+#!/usr/bin/env node
+/**
+ * Clawform PreToolUse hook — CLI entry. Reads JSON event from stdin, resolves
+ * the consumer's project root from the EVENT's `cwd` field (Claude Code sets
+ * this on every hook event), and delegates to the pure `evaluate` in
+ * block-dangerous-eval.js. Exits 2 with stderr on block.
+ *
+ * Why `event.cwd` instead of `process.env.CLAUDE_PROJECT_DIR`: the Claude Code
+ * hook docs (anthropic.com/docs/claude-code/hooks) document `cwd` as part of
+ * the stdin event payload but make no guarantee about CLAUDE_PROJECT_DIR being
+ * set in the hook process env, particularly when the hook is registered via a
+ * plugin's `hooks.json` (where `${CLAUDE_PLUGIN_ROOT}` substitutes into the
+ * command path but the runtime env is undocumented). Relying on the env var
+ * here risks a non-Acme consumer silently inheriting THIS repo's dogfood config
+ * — exactly the security bug the composable refactor exists to prevent.
+ * Fallback: process.env.CLAUDE_PROJECT_DIR → process.cwd() (the latter is
+ * useful for dev-mode invocations from the repo root).
+ *
+ * Fail-LOUD on event-parse error → write to stderr + exit 0 so a buggy hook
+ * never silently disables the safety net (the alternative — fail closed —
+ * would deny every Bash call on any unrelated parse problem).
+ *
+ * Fail-LOUD on config-load error → write to stderr + continue with an empty
+ * legacy-prefix list. Built-in blockers (delete-stack, s3 rb --force) still
+ * fire; only the legacy-freeze gate is dropped, which is the correct outcome
+ * when the consumer's clawform.config.json is broken or missing.
+ */
+
+import { readFileSync } from 'node:fs';
+import { evaluate } from './block-dangerous-eval.js';
+import { loadProjectConfig } from '../lib/project-config.js';
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8'));
+} catch (err) {
+  process.stderr.write(`[clawform hook] event parse failed (allowing tool call): ${err.message}\n`);
+  process.exit(0);
+}
+
+const projectDir = (typeof event?.cwd === 'string' && event.cwd) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+let legacyPrefixes = [];
+try {
+  const cfg = loadProjectConfig({ projectDir });
+  legacyPrefixes = cfg.legacy_prefixes || [];
+} catch (err) {
+  process.stderr.write(`[clawform hook] consumer config load failed at ${projectDir} (legacy-freeze gate disabled, built-ins still fire): ${err.message}\n`);
+}
+
+const { block, warn, reason } = evaluate(event, { legacyPrefixes });
+if (block) {
+  process.stderr.write(`[clawform hook] ${reason}\n`);
+  process.exit(2);
+}
+
+// Advisory: the command runs, but the operator is told what the guard could
+// not see. Same posture as the catalog-freshness hook.
+if (warn) {
+  process.stderr.write(`[clawform hook] ${reason}\n`);
+  process.exit(0);
+}

package/src/hooks/cfn-lint-after-edit-eval.js

@@ -1,30 +1,30 @@
-// Pure decision logic for the PostToolUse cfn-lint hook. Given a
-// PostToolUse event, returns { lint, file?, reason? } so the CLI shim
-// knows whether (and on which file) to spawn cfn-lint. Exported separately
-// so unit tests don't need to spawn anything.
-//
-// Trigger rules (intentionally narrow — we don't want to lint every YAML
-// the user touches):
-//   tool_name ∈ {Edit, Write, MultiEdit}
-//   tool_input.file_path is a string ending in .yaml or .yml
-//   the path contains a `cfn/` or `templates/` segment (path-separator agnostic)
-//
-// The path-segment check is what makes the hook safe to ship as a global
-// PostToolUse matcher: editing some-other-product/serverless.yaml elsewhere
-// won't trip cfn-lint just because it's a YAML file.
-
-const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
-const YAML_RE = /\.ya?ml$/i;
-// `[/\\]` covers POSIX and Windows separators; `(^|...)` matches either an
-// initial segment or a sub-segment. `(?=[/\\])` ensures it's a directory.
-const CFN_DIR_RE = /(^|[/\\])(cfn|templates)(?=[/\\])/i;
-
-export function shouldLint(event) {
-  const toolName = event?.tool_name;
-  if (!EDIT_TOOLS.has(toolName)) return { lint: false };
-  const file = event?.tool_input?.file_path;
-  if (typeof file !== 'string') return { lint: false };
-  if (!YAML_RE.test(file)) return { lint: false };
-  if (!CFN_DIR_RE.test(file)) return { lint: false };
-  return { lint: true, file };
-}
+// Pure decision logic for the PostToolUse cfn-lint hook. Given a
+// PostToolUse event, returns { lint, file?, reason? } so the CLI shim
+// knows whether (and on which file) to spawn cfn-lint. Exported separately
+// so unit tests don't need to spawn anything.
+//
+// Trigger rules (intentionally narrow — we don't want to lint every YAML
+// the user touches):
+//   tool_name ∈ {Edit, Write, MultiEdit}
+//   tool_input.file_path is a string ending in .yaml or .yml
+//   the path contains a `cfn/` or `templates/` segment (path-separator agnostic)
+//
+// The path-segment check is what makes the hook safe to ship as a global
+// PostToolUse matcher: editing some-other-product/serverless.yaml elsewhere
+// won't trip cfn-lint just because it's a YAML file.
+
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+const YAML_RE = /\.ya?ml$/i;
+// `[/\\]` covers POSIX and Windows separators; `(^|...)` matches either an
+// initial segment or a sub-segment. `(?=[/\\])` ensures it's a directory.
+const CFN_DIR_RE = /(^|[/\\])(cfn|templates)(?=[/\\])/i;
+
+export function shouldLint(event) {
+  const toolName = event?.tool_name;
+  if (!EDIT_TOOLS.has(toolName)) return { lint: false };
+  const file = event?.tool_input?.file_path;
+  if (typeof file !== 'string') return { lint: false };
+  if (!YAML_RE.test(file)) return { lint: false };
+  if (!CFN_DIR_RE.test(file)) return { lint: false };
+  return { lint: true, file };
+}

package/src/hooks/cfn-lint-after-edit.js

@@ -1,81 +1,81 @@
-#!/usr/bin/env node
-/**
- * Clawform PostToolUse hook — CLI entry. Spawns cfn-lint after Edit/Write/MultiEdit
- * on YAML files under cfn/ or templates/. Surfaces ERRORS back to Claude (exit 2 +
- * stderr) so it can self-correct; WARNINGS go to stderr at exit 0 (advisory). When
- * cfn-lint isn't installed, exits 0 silently — the hook is opt-in, not a gate.
- *
- * The pure decision logic lives in cfn-lint-after-edit-eval.js (unit-tested
- * separately).
- */
-
-import { readFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import { shouldLint } from './cfn-lint-after-edit-eval.js';
-
-let event;
-try {
-  event = JSON.parse(readFileSync(0, 'utf8'));
-} catch (err) {
-  // Fail-LOUD on parse error (allow the tool result through, but visibly warn).
-  process.stderr.write(`[clawform cfn-lint hook] event parse failed (skipping lint): ${err.message}\n`);
-  process.exit(0);
-}
-
-const decision = shouldLint(event);
-if (!decision.lint) process.exit(0);
-
-const r = spawnSync('cfn-lint', ['--format', 'json', decision.file], { encoding: 'utf8' });
-
-// cfn-lint not installed → silent skip. Hook stays opt-in for boxes without Python.
-if (r.error && (r.error.code === 'ENOENT' || r.error.errno === -2)) {
-  process.exit(0);
-}
-
-const stdout = (r.stdout ?? '').trim();
-if (!stdout) {
-  // No findings — clean lint pass. Exit 0 quietly.
-  process.exit(0);
-}
-
-let findings;
-try {
-  findings = JSON.parse(stdout);
-} catch {
-  process.stderr.write(`[clawform cfn-lint hook] could not parse cfn-lint output for ${decision.file} (skipping)\n`);
-  process.exit(0);
-}
-
-let errors = 0;
-let warnings = 0;
-const lines = [];
-for (const f of findings) {
-  const id = f.Rule?.Id ?? '?';
-  const loc = f.Location?.Start ? `L${f.Location.Start.LineNumber}` : '';
-  const msg = f.Message ?? '';
-  if (f.Level === 'Error') {
-    errors++;
-    lines.push(`  ✖ ${id} ${loc}: ${msg}`);
-  } else if (f.Level === 'Warning') {
-    warnings++;
-    lines.push(`  ⚠ ${id} ${loc}: ${msg}`);
-  }
-}
-
-if (errors > 0) {
-  // Errors get exit 2 + stderr so Claude sees them in the next turn and self-corrects.
-  process.stderr.write(
-    `[clawform cfn-lint hook] ${errors} error(s), ${warnings} warning(s) in ${decision.file}:\n` +
-      lines.join('\n') +
-      '\n',
-  );
-  process.exit(2);
-}
-
-if (warnings > 0) {
-  // Warnings stay advisory — user-visible, not blocking.
-  process.stderr.write(
-    `[clawform cfn-lint hook] ${warnings} warning(s) in ${decision.file}:\n` + lines.join('\n') + '\n',
-  );
-  process.exit(0);
-}
+#!/usr/bin/env node
+/**
+ * Clawform PostToolUse hook — CLI entry. Spawns cfn-lint after Edit/Write/MultiEdit
+ * on YAML files under cfn/ or templates/. Surfaces ERRORS back to Claude (exit 2 +
+ * stderr) so it can self-correct; WARNINGS go to stderr at exit 0 (advisory). When
+ * cfn-lint isn't installed, exits 0 silently — the hook is opt-in, not a gate.
+ *
+ * The pure decision logic lives in cfn-lint-after-edit-eval.js (unit-tested
+ * separately).
+ */
+
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { shouldLint } from './cfn-lint-after-edit-eval.js';
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8'));
+} catch (err) {
+  // Fail-LOUD on parse error (allow the tool result through, but visibly warn).
+  process.stderr.write(`[clawform cfn-lint hook] event parse failed (skipping lint): ${err.message}\n`);
+  process.exit(0);
+}
+
+const decision = shouldLint(event);
+if (!decision.lint) process.exit(0);
+
+const r = spawnSync('cfn-lint', ['--format', 'json', decision.file], { encoding: 'utf8' });
+
+// cfn-lint not installed → silent skip. Hook stays opt-in for boxes without Python.
+if (r.error && (r.error.code === 'ENOENT' || r.error.errno === -2)) {
+  process.exit(0);
+}
+
+const stdout = (r.stdout ?? '').trim();
+if (!stdout) {
+  // No findings — clean lint pass. Exit 0 quietly.
+  process.exit(0);
+}
+
+let findings;
+try {
+  findings = JSON.parse(stdout);
+} catch {
+  process.stderr.write(`[clawform cfn-lint hook] could not parse cfn-lint output for ${decision.file} (skipping)\n`);
+  process.exit(0);
+}
+
+let errors = 0;
+let warnings = 0;
+const lines = [];
+for (const f of findings) {
+  const id = f.Rule?.Id ?? '?';
+  const loc = f.Location?.Start ? `L${f.Location.Start.LineNumber}` : '';
+  const msg = f.Message ?? '';
+  if (f.Level === 'Error') {
+    errors++;
+    lines.push(`  ✖ ${id} ${loc}: ${msg}`);
+  } else if (f.Level === 'Warning') {
+    warnings++;
+    lines.push(`  ⚠ ${id} ${loc}: ${msg}`);
+  }
+}
+
+if (errors > 0) {
+  // Errors get exit 2 + stderr so Claude sees them in the next turn and self-corrects.
+  process.stderr.write(
+    `[clawform cfn-lint hook] ${errors} error(s), ${warnings} warning(s) in ${decision.file}:\n` +
+      lines.join('\n') +
+      '\n',
+  );
+  process.exit(2);
+}
+
+if (warnings > 0) {
+  // Warnings stay advisory — user-visible, not blocking.
+  process.stderr.write(
+    `[clawform cfn-lint hook] ${warnings} warning(s) in ${decision.file}:\n` + lines.join('\n') + '\n',
+  );
+  process.exit(0);
+}

package/src/hooks/check-catalog-fresh-eval.js

@@ -1,63 +1,63 @@
-// Pure decision logic for the PreToolUse `clawform deploy` catalog-freshness hook.
-// Returns { warn|block, reason? } so the CLI shim handles all I/O.
-//
-// Rule:
-//   - If the command is `clawform deploy ...`, the consumer is about to import live exports.
-//     Block (exit 2) if `.clawform/catalog/outputs-catalog.md` doesn't exist — the user has never
-//     run `clawform sync`, so every Fn::ImportValue is unverifiable and changeset failure
-//     at deploy time is the predictable next step.
-//   - If the catalog file exists but is stale (>STALE_HOURS), warn (advisory) — the export
-//     set probably changed underneath. User decides.
-//   - Otherwise let it pass.
-//
-// Stays pure: takes (event, {cwd, now, stat}) and returns a verdict. The shim
-// supplies real `cwd`, `Date.now()`, and `node:fs.statSync` — tests substitute fakes.
-
-import { CATALOG_DIR_REL } from '../lib/constants.js';
-
-const DEPLOY_RE = /(^|\s|;|&&|\|\|)clawform\s+deploy\b/;
-// Derived, not restated: the gate must read exactly where `sync` writes, or it
-// blocks every deploy with "run sync" even right after a successful sync.
-export const CATALOG_REL = `${CATALOG_DIR_REL}/outputs-catalog.md`;
-export const STALE_HOURS = 24;
-
-// Resolve catalog path relative to a working directory. The path module's
-// join is platform-aware; we accept either separator on input. Exported so
-// other hooks (session-context-eval.js) can reuse the same resolution
-// instead of re-deriving it (DRY — session-context reports the same
-// freshness signal this hook gates on).
-export function resolveCatalogPath(cwd) {
-  return cwd.endsWith('/') || cwd.endsWith('\\') ? cwd + CATALOG_REL : cwd + '/' + CATALOG_REL;
-}
-
-export function checkCatalog(event, { cwd, now, statSync }) {
-  if (event?.tool_name !== 'Bash') return { ok: true };
-  const cmd = event?.tool_input?.command;
-  if (typeof cmd !== 'string' || !DEPLOY_RE.test(cmd)) return { ok: true };
-
-  const path = resolveCatalogPath(cwd);
-
-  let stat;
-  try {
-    stat = statSync(path);
-  } catch {
-    return {
-      block: true,
-      reason:
-        `Catalog ${CATALOG_REL} is missing — run \`clawform sync\` before deploying so Fn::ImportValue references can be verified against live exports.`,
-    };
-  }
-
-  const ageMs = now - new Date(stat.mtime).getTime();
-  const ageHours = ageMs / 3_600_000;
-  if (ageHours > STALE_HOURS) {
-    return {
-      warn: true,
-      reason:
-        `Catalog ${CATALOG_REL} is ${Math.round(ageHours)}h old (>${STALE_HOURS}h). ` +
-        'Consider `clawform sync` before deploy if any upstream stack changed recently.',
-    };
-  }
-
-  return { ok: true };
-}
+// Pure decision logic for the PreToolUse `clawform deploy` catalog-freshness hook.
+// Returns { warn|block, reason? } so the CLI shim handles all I/O.
+//
+// Rule:
+//   - If the command is `clawform deploy ...`, the consumer is about to import live exports.
+//     Block (exit 2) if `.clawform/catalog/outputs-catalog.md` doesn't exist — the user has never
+//     run `clawform sync`, so every Fn::ImportValue is unverifiable and changeset failure
+//     at deploy time is the predictable next step.
+//   - If the catalog file exists but is stale (>STALE_HOURS), warn (advisory) — the export
+//     set probably changed underneath. User decides.
+//   - Otherwise let it pass.
+//
+// Stays pure: takes (event, {cwd, now, stat}) and returns a verdict. The shim
+// supplies real `cwd`, `Date.now()`, and `node:fs.statSync` — tests substitute fakes.
+
+import { CATALOG_DIR_REL } from '../lib/constants.js';
+
+const DEPLOY_RE = /(^|\s|;|&&|\|\|)clawform\s+deploy\b/;
+// Derived, not restated: the gate must read exactly where `sync` writes, or it
+// blocks every deploy with "run sync" even right after a successful sync.
+export const CATALOG_REL = `${CATALOG_DIR_REL}/outputs-catalog.md`;
+export const STALE_HOURS = 24;
+
+// Resolve catalog path relative to a working directory. The path module's
+// join is platform-aware; we accept either separator on input. Exported so
+// other hooks (session-context-eval.js) can reuse the same resolution
+// instead of re-deriving it (DRY — session-context reports the same
+// freshness signal this hook gates on).
+export function resolveCatalogPath(cwd) {
+  return cwd.endsWith('/') || cwd.endsWith('\\') ? cwd + CATALOG_REL : cwd + '/' + CATALOG_REL;
+}
+
+export function checkCatalog(event, { cwd, now, statSync }) {
+  if (event?.tool_name !== 'Bash') return { ok: true };
+  const cmd = event?.tool_input?.command;
+  if (typeof cmd !== 'string' || !DEPLOY_RE.test(cmd)) return { ok: true };
+
+  const path = resolveCatalogPath(cwd);
+
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    return {
+      block: true,
+      reason:
+        `Catalog ${CATALOG_REL} is missing — run \`clawform sync\` before deploying so Fn::ImportValue references can be verified against live exports.`,
+    };
+  }
+
+  const ageMs = now - new Date(stat.mtime).getTime();
+  const ageHours = ageMs / 3_600_000;
+  if (ageHours > STALE_HOURS) {
+    return {
+      warn: true,
+      reason:
+        `Catalog ${CATALOG_REL} is ${Math.round(ageHours)}h old (>${STALE_HOURS}h). ` +
+        'Consider `clawform sync` before deploy if any upstream stack changed recently.',
+    };
+  }
+
+  return { ok: true };
+}

package/src/hooks/check-catalog-fresh.js

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-/**
- * Clawform PreToolUse hook — catalog-freshness guard for `clawform deploy`.
- * Reads JSON event from stdin, delegates to pure `checkCatalog`, and:
- *   - exit 2 + stderr  → catalog missing (blocks deploy until clawform sync runs)
- *   - exit 0 + stderr  → catalog stale (>24h) — advisory only
- *   - exit 0 silent    → no deploy command, or catalog fresh
- *
- * Fail-LOUD on parse error so a buggy hook never silently disables the guard.
- */
-
-import { readFileSync, statSync } from 'node:fs';
-import { checkCatalog } from './check-catalog-fresh-eval.js';
-
-let event;
-try {
-  event = JSON.parse(readFileSync(0, 'utf8'));
-} catch (err) {
-  process.stderr.write(`[clawform catalog hook] event parse failed (allowing tool call): ${err.message}\n`);
-  process.exit(0);
-}
-
-const verdict = checkCatalog(event, { cwd: process.cwd(), now: Date.now(), statSync });
-
-if (verdict.block) {
-  process.stderr.write(`[clawform catalog hook] ${verdict.reason}\n`);
-  process.exit(2);
-}
-
-if (verdict.warn) {
-  process.stderr.write(`[clawform catalog hook] ${verdict.reason}\n`);
-  process.exit(0);
-}
+#!/usr/bin/env node
+/**
+ * Clawform PreToolUse hook — catalog-freshness guard for `clawform deploy`.
+ * Reads JSON event from stdin, delegates to pure `checkCatalog`, and:
+ *   - exit 2 + stderr  → catalog missing (blocks deploy until clawform sync runs)
+ *   - exit 0 + stderr  → catalog stale (>24h) — advisory only
+ *   - exit 0 silent    → no deploy command, or catalog fresh
+ *
+ * Fail-LOUD on parse error so a buggy hook never silently disables the guard.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { checkCatalog } from './check-catalog-fresh-eval.js';
+
+let event;
+try {
+  event = JSON.parse(readFileSync(0, 'utf8'));
+} catch (err) {
+  process.stderr.write(`[clawform catalog hook] event parse failed (allowing tool call): ${err.message}\n`);
+  process.exit(0);
+}
+
+const verdict = checkCatalog(event, { cwd: process.cwd(), now: Date.now(), statSync });
+
+if (verdict.block) {
+  process.stderr.write(`[clawform catalog hook] ${verdict.reason}\n`);
+  process.exit(2);
+}
+
+if (verdict.warn) {
+  process.stderr.write(`[clawform catalog hook] ${verdict.reason}\n`);
+  process.exit(0);
+}