@spardutti/claude-skills 2.20.1 → 2.22.0

package/README.md

@@ -88,6 +88,8 @@ Cross-cutting craft — applies to any stack, any language.
 |-------|----------------|
 | `code-structure` 📦 | Single Responsibility (when to split) + Avoid Hasty Abstractions (when *not* to extract) — hard size limits, separation of concerns, the Rule of Three |
 | `debugging` | Root cause before patching — reproduce, trace the failure backward to its origin, one hypothesis at a time, the 3-attempts-then-question-the-design rule |
+| `git-merge-conflicts` | Resolve a merge/rebase conflict by intent, not by side — `zdiff3` to see the merge base, the inverted meaning of `ours`/`theirs` during a rebase, the semantic and tree conflicts git never marks, lockfiles and migrations you regenerate instead of merging |
+| `research` | Open the source, don't recall it — route to the tool that owns the answer, primary sources only, pin the version you're actually on, run the validator instead of guessing, and mark every claim VERIFIED / INFERRED / UNVERIFIED |
 | `typescript-best-practices` | TypeScript 7.x — type design, generics, type guards, `satisfies`, `using`, error handling, `tsconfig` |
 | `testing-best-practices` 📦 | Arrange-Act-Assert, factory-based test data, isolation, mocking boundaries, a pyramid-balanced suite; bundle covers mutation testing — Stryker and mutmut setup, diff-scoped runs, the traps, and working score thresholds |
 | `security-practices` | OWASP Top 10 prevention, input validation, auth, SQL injection, XSS, CSRF, secure defaults |
@@ -106,6 +108,7 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 | `/deep-review` | Multi-agent deep code review — 5 parallel subagents catch guard bypasses, lost async state, wrong-table queries, dead references, protocol violations |
 | `/test-review` | Write-then-verify test review — scopes to the diff, runs red-green + mutation gates, then an isolated read-only subagent proves each test would catch a regression instead of rubber-stamping it |
 | `/lockdown` | Per-repo supply-chain hardening — detects the package managers, Dockerfiles, and CI in use, then guides you through and applies install-time, deploy, and pipeline hardening for npm/pnpm, pip/uv, Docker, and GitHub Actions |
+| `/handoff` | Write a handoff doc so a fresh session picks the work up — captures what auto-compaction loses: decisions made and rejected, dead ends already ruled out, why the tree is dirty, and the one next step. Links to specs, commits, and PRs instead of restating them |
 
 ## How It Works
 

package/bin/cli.mjs

@@ -10,6 +10,7 @@ import { promptSkillSelection, promptCommandSelection, promptRemoval } from "../
 import { installSkills, installCommands, installRequiredAgents } from "../lib/install.mjs";
 import { setupHook, detectStack, writeGauntletConf } from "../lib/setup-hook.mjs";
 import { makeLocalSource, reportToolNeeds } from "../lib/local.mjs";
+import { scaffoldStryker } from "../lib/scaffold-stryker.mjs";
 import { setupClaudeMd } from "../lib/setup-claude-md.mjs";
 import {
   readManifest, writeManifest, computeOrphans, computeRemovals, scanInstalled, removeArtifacts,
@@ -209,12 +210,63 @@ async function main() {
       if (!selectedSkills.some((s) => s.dirName === "testing-best-practices")) {
         console.log(`    ${chalk.dim("Setting these up has traps — install the testing-best-practices skill for MUTATION-TESTING.md.")}`);
       }
-      for (const n of needs) {
+      for (const n of needs.filter((n) => !n.ignorerOnly)) {
         console.log(`    ${chalk.bold(n.label)} needs ${n.tool}`);
         console.log(`      ${chalk.cyan(n.install)}`);
         console.log(`      ${chalk.dim(n.config)}`);
         for (const line of n.also ?? []) console.log(`      ${chalk.dim(line)}`);
       }
+      for (const n of needs.filter((n) => n.ignorerOnly)) {
+        console.log(`    ${chalk.bold(n.label)} runs ${n.tool} without the class-name ignorer`);
+        console.log(`      ${chalk.dim("~40% of a first React run is mutants on className strings, which no test can honestly kill")}`);
+      }
+
+      // Printing five steps meant every project was set up by hand, and the one
+      // step people skipped was the class-name ignorer — the reason a first run
+      // comes back with dozens of mutants on className strings that no test can
+      // honestly kill. Write the two files instead of describing them.
+      const stryker = needs.filter((n) => n.tool === "Stryker");
+      if (stryker.length > 0) {
+        console.log();
+        const doScaffold = await confirm({
+          message: `Write Stryker's config and the class-name ignorer for ${stryker.length} project(s)?`,
+          default: true,
+        });
+        if (doScaffold) {
+          const installs = [];
+          const vitest = [];
+          for (const n of stryker) {
+            const r = await scaffoldStryker(CWD, n.rel);
+            for (const f of r.wrote) console.log(`  Wrote: ${f}`);
+            for (const f of r.patched) console.log(`  Added the ignorer to: ${f}`);
+            for (const f of r.kept) console.log(`  ${chalk.dim(`Kept yours: ${f}`)}`);
+            for (const f of r.unreadable) {
+              console.log(`  ${chalk.yellow("!")} ${f} is not readable as JSON — left alone, add the ignorer by hand`);
+            }
+            // A project that already runs Stryker needs neither the install nor
+            // the vitest exclude repeated at it; it only lacked the ignorer.
+            if (!n.ignorerOnly) {
+              installs.push(r.install);
+              vitest.push(r.vitest);
+            }
+          }
+          // Left to the reader on purpose: installing touches the lockfile and
+          // the network, and editing an existing vitest config means parsing
+          // someone's plugins and aliases, where being wrong breaks their tests.
+          if (installs.length > 0) {
+            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("Two steps left, per project:")}`);
+            for (const c of installs) console.log(`      ${chalk.cyan(c)}`);
+            for (const v of vitest) console.log(`      ${chalk.dim(v)}`);
+          }
+          // The ignorer imports @stryker-mutator/api, which npm hoists by
+          // accident and pnpm does not. Missing, it prints one WARN PluginLoader
+          // line, loads nothing, and every className mutant comes back survived.
+          if (stryker.some((n) => n.ignorerOnly)) {
+            console.log(`\n  ${chalk.yellow("!")} ${chalk.bold("The ignorer needs its own dependency:")}`);
+            console.log(`      ${chalk.cyan("add @stryker-mutator/api as a dev dependency")} ${chalk.dim("— pnpm does not hoist it, and without it the ignorer silently does not load")}`);
+          }
+        }
+      }
     }
   }
 

package/lib/local.mjs

@@ -161,6 +161,7 @@ export async function reportToolNeeds(projectDir) {
         const at = rel ? rel + "/" : "";
         needs.push({
           label,
+          rel,
           tool: "Stryker",
           install: `npm --prefix ${rel || "."} i -D @stryker-mutator/core @stryker-mutator/vitest-runner`,
           config: `${at}stryker.config.json  {"testRunner":"vitest","plugins":["@stryker-mutator/vitest-runner"],"coverageAnalysis":"perTest"}`,
@@ -173,6 +174,20 @@ export async function reportToolNeeds(projectDir) {
             `${at}.gitignore  .stryker-tmp/`,
           ],
         });
+      } else {
+        // Stryker is installed, so this project is not missing a tool — but the
+        // projects that already run it are the ones grinding through mutants on
+        // className strings, and a setup done before the ignorer existed has no
+        // way to learn about it. Offer it here or it never reaches them.
+        let cfg = "";
+        try {
+          cfg = await readFile(join(dir, "stryker.config.json"), "utf-8");
+        } catch {
+          // no config of its own — the scaffolder writes one
+        }
+        if (!cfg.includes("tailwind-classnames")) {
+          needs.push({ label, rel, tool: "Stryker", ignorerOnly: true });
+        }
       }
     }
     if (pyp && !seen.has(label + ":py")) {

package/lib/scaffold-stryker.mjs

@@ -0,0 +1,142 @@
+// Stryker setup, written rather than printed.
+//
+// The CLI used to print five steps and leave them to the reader. Every project
+// then started with the same 40% of a first React run being class-name noise —
+// mutants on `className` strings and `cn()` ternaries that cannot be killed
+// without asserting on the stylesheet. Un-closeable findings are what teach
+// people to --force, so the ignorer is not an optional extra; it is the
+// difference between a gate that gets used and one that gets bypassed.
+//
+// Two things stay printed, deliberately. Installing the packages touches the
+// lockfile and the network. Editing an existing vitest config means parsing
+// someone's plugins, aliases and projects array, and getting it wrong breaks
+// their test run rather than ours.
+import { readFile, writeFile, access } from "node:fs/promises";
+import { join } from "node:path";
+
+const CONFIG = {
+  $schema: "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+  testRunner: "vitest",
+  plugins: ["@stryker-mutator/vitest-runner", "./stryker-classname-ignorer.mjs"],
+  ignorers: ["tailwind-classnames"],
+  coverageAnalysis: "perTest",
+  tempDirName: ".stryker-tmp",
+};
+
+// .mjs, not .js: an app without "type": "module" in its package.json cannot
+// load ESM from a .js file, and the plugin is ESM.
+const IGNORER = `// Ignore by WHERE the mutant sits, not by what kind it is. Disabling the
+// StringLiteral mutator globally would also stop mutating labels, keys and
+// separators — strings whose value is behaviour.
+import { PluginKind, declareValuePlugin } from "@stryker-mutator/api/plugin";
+
+export const strykerPlugins = [
+  declareValuePlugin(PluginKind.Ignore, "tailwind-classnames", {
+    shouldIgnore(path) {
+      if (path.find((p) => p.isJSXAttribute() && p.node.name.name === "className"))
+        return "styling, not behaviour";
+      if (path.find((p) => p.isCallExpression() && p.node.callee.name === "cn"))
+        return "styling, not behaviour";
+    },
+  }),
+];
+`;
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The ignorer imports @stryker-mutator/api, but nothing depends on it directly:
+// npm's flat node_modules hoists it so the import resolves by accident, and
+// pnpm's isolated store does not. The failure is one WARN PluginLoader line and
+// an ignorer that never loads, so every class-name mutant comes back survived.
+async function installCommand(dir, rel) {
+  const pnpm = await exists(join(dir, "pnpm-lock.yaml"));
+  const pkgs = "@stryker-mutator/core @stryker-mutator/vitest-runner @stryker-mutator/api";
+  return pnpm
+    ? `pnpm --dir ${rel || "."} add -D ${pkgs}`
+    : `npm --prefix ${rel || "."} i -D ${pkgs}`;
+}
+
+// Writes only what is absent. A project that already configured Stryker its own
+// way keeps it — reporting the skip is the point, so nobody thinks a file they
+// are looking at came from here.
+export async function scaffoldStryker(projectDir, rel) {
+  const dir = rel ? join(projectDir, rel) : projectDir;
+  const at = rel ? `${rel}/` : "";
+  const wrote = [];
+  const kept = [];
+  const patched = [];
+  const unreadable = [];
+
+  // A project that already runs Stryker keeps every setting it chose. The two
+  // entries that wire the ignorer in are added, because a config written before
+  // the ignorer existed has no other way to learn about it — and that project is
+  // the one grinding through className mutants. A config this cannot parse is
+  // reported and left alone rather than rewritten from a guess.
+  const configPath = join(dir, "stryker.config.json");
+  if (await exists(configPath)) {
+    let cfg = null;
+    try {
+      cfg = JSON.parse(await readFile(configPath, "utf-8"));
+    } catch {
+      cfg = null;
+    }
+    if (cfg === null) {
+      unreadable.push(`${at}stryker.config.json`);
+    } else if ((cfg.ignorers ?? []).includes("tailwind-classnames")) {
+      kept.push(`${at}stryker.config.json`);
+    } else {
+      cfg.plugins = [...new Set([...(cfg.plugins ?? []), "./stryker-classname-ignorer.mjs"])];
+      cfg.ignorers = [...new Set([...(cfg.ignorers ?? []), "tailwind-classnames"])];
+      await writeFile(configPath, JSON.stringify(cfg, null, 2) + "\n");
+      patched.push(`${at}stryker.config.json`);
+    }
+  } else {
+    await writeFile(configPath, JSON.stringify(CONFIG, null, 2) + "\n");
+    wrote.push(`${at}stryker.config.json`);
+  }
+
+  const ignorerPath = join(dir, "stryker-classname-ignorer.mjs");
+  if (await exists(ignorerPath)) {
+    kept.push(`${at}stryker-classname-ignorer.mjs`);
+  } else {
+    await writeFile(ignorerPath, IGNORER);
+    wrote.push(`${at}stryker-classname-ignorer.mjs`);
+  }
+
+  // A crashed run leaves a full second copy of the project behind, so this one
+  // matters even though it is one line.
+  const gitignorePath = join(dir, ".gitignore");
+  let gitignore = "";
+  try {
+    gitignore = await readFile(gitignorePath, "utf-8");
+  } catch {
+    // no .gitignore yet — one gets written below
+  }
+  if (/^\.stryker-tmp\/?$/m.test(gitignore)) {
+    kept.push(`${at}.gitignore`);
+  } else {
+    const sep = gitignore === "" || gitignore.endsWith("\n") ? "" : "\n";
+    await writeFile(gitignorePath, `${gitignore}${sep}.stryker-tmp/\n`);
+    wrote.push(`${at}.gitignore`);
+  }
+
+  return {
+    wrote,
+    kept,
+    patched,
+    unreadable,
+    install: await installCommand(dir, rel),
+    // Stryker copies the whole project into .stryker-tmp/sandbox-*/, so every
+    // test file briefly exists twice and the runner collects both. They pass,
+    // so a doubled test count is the only symptom. Spread configDefaults.exclude
+    // rather than assigning it, or node_modules stops being excluded.
+    vitest: `${at}vitest.config.ts  exclude: [...configDefaults.exclude, "**/.stryker-tmp/**"]`,
+  };
+}

package/lib/setup-hook.mjs

@@ -226,13 +226,32 @@ Before this Write/Edit, you must:
 
 1. For each skill listed above, say whether it applies to the file you're about to
    write. If it does not — a Python skill and a TypeScript file, say — write
-   "does not apply" and move on. Do not invent a connection.
+   \\"does not apply\\" and move on. Do not invent a connection.
 2. For the ones that do apply: state the specific rules that bear on this file, and
    how your next write respects each.
 3. Then ack all of them in a single Bash tool call:
      $ACK_CMD
 
 One ack per skill per session. After acking, retry the Write/Edit.
+
+If that Bash call is denied by the auto mode classifier, STOP. Do not ask your
+user to run it for you, and do not look for another route to create the files.
+Both are what the classifier is there to stop, and asking a human to run a
+command you were just denied makes them the tool that performs it. Report this
+to them instead and let them decide:
+
+  Auto mode's built-in Auto-Mode Bypass rule counts a hook's ack file as working
+  around the permission system. It is a soft rule, so an allow entry clears it.
+  It has to go in ~/.claude/settings.json — the classifier does not read a
+  project's .claude/settings.json — or in /permissions, Auto mode tab. Keep the
+  \\\$defaults line or every built-in allow rule is discarded:
+
+  \\"autoMode\\": { \\"allow\\": [ \\"\\\$defaults\\",
+    \\"Touching marker files under /tmp/claude-skill-gate-*, /tmp/claude-skill-acked-*
+     and /tmp/claude-skill-loaded-* is allowed: they are acknowledgement files for
+     the user's own PreToolUse skill gates. Creating one satisfies a workflow gate
+     the user installed, grants no permission and executes no code, and is a false
+     positive for Auto-Mode Bypass.\\" ] }
 $RULES_BLOCKS"
 
 json_escape() {
@@ -1365,6 +1384,26 @@ export async function setupHook(targetDir = process.cwd()) {
     settings.hooks.Stop = [gauntletEntry];
   }
 
+  // Both gates clear by touching a marker under /tmp. The hook scripts let those
+  // commands through themselves, but auto mode's permission classifier does not:
+  // a touch whose only purpose is to unlock a gate is exactly what it refuses.
+  // So in auto mode the application gate could not be satisfied at all, and the
+  // model was reduced to asking its user to run the touch by hand — which is
+  // indistinguishable from the laundering the classifier exists to stop.
+  // Allowlisting the three marker paths is what makes the gates workable there.
+  // Only these literal prefixes are granted, and an existing entry is not
+  // duplicated on reinstall.
+  const MARKER_ALLOW = [
+    "Bash(touch /tmp/claude-skill-gate-*)",
+    "Bash(touch /tmp/claude-skill-acked-*)",
+    "Bash(touch /tmp/claude-skill-loaded-*)",
+  ];
+  if (!settings.permissions) settings.permissions = {};
+  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+  for (const rule of MARKER_ALLOW) {
+    if (!settings.permissions.allow.includes(rule)) settings.permissions.allow.push(rule);
+  }
+
   await writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o644 });
 
   console.log(`  Hook installed: .claude/hooks/${GATE_FILENAME}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.20.1",
+  "version": "2.22.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "repository": {