@spardutti/claude-skills 2.33.8 → 2.35.0

package/README.md

@@ -131,7 +131,7 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 
 | Command | What it does |
 |---------|--------------|
-| `/ship` | Unified delivery pipeline — commit → gate → PR → merge → release. The gate is the one enforcement moment: it checks the diff's file lengths, audits it against the skills installed in the project, and mutation-tests the changed lines to prove the tests would catch a break — **fixing what it finds** rather than handing you a list. It runs before the **PR**, not before every commit: its scope is the whole branch, so gating each commit re-mutated every file the branch had ever touched. `--force` skips it. No argument steps through interactively; `/ship pr` runs through PR creation; `/ship release` runs the full pipeline |
+| `/ship` | Unified delivery pipeline — commit → gate → PR → merge → release. The gate is the one enforcement moment: it checks the diff's file lengths and that new files sit in their kind folder, audits it against the skills installed in the project, and mutation-tests the changed lines to prove the tests would catch a break — **fixing what it finds** rather than handing you a list. It runs before the **PR**, not before every commit: its scope is the whole branch, so gating each commit re-mutated every file the branch had ever touched. `--force` skips it. No argument steps through interactively; `/ship pr` runs through PR creation; `/ship release` runs the full pipeline |
 | `/discover` | Find the right problem before deciding what to build — diverges first: generates competing framings through blind subagents under forced constraints, stress-tests the winner with a blind critic, and refuses to converge until every open question is answered or deferred, then drafts scope, non-goals, edge cases and success criteria for you to correct. Run before `/plan-feature` |
 | `/plan-feature` | Integration-first feature planning, then building — 3 parallel subagents scan for reusable code, patterns and touch points, grounded clarifying questions follow, and on your go the same agent builds the plan |
 | `/refactor` | Detect size / complexity / duplication / coupling issues via 4 parallel subagents, then refactor |
@@ -169,7 +169,13 @@ Every install writes a manifest at `.claude/.claude-skills.json` recording what
 npx @spardutti/claude-skills --sync
 ```
 
-`--sync` refreshes every tracked item to the latest catalog and prunes stale ones in one shot — no menu. For a project that predates the manifest, the first normal run offers a one-time cleanup of `.claude/` content no longer in the catalog.
+`--sync` refreshes every tracked item, and any hooks the project already has, to the latest catalog and prunes stale ones in one shot — no menu. For a project that predates the manifest, the first normal run offers a one-time cleanup of `.claude/` content no longer in the catalog.
+
+`--sync-all[=dir]` does the same for every project under `dir` (default: your home folder) that has a manifest, fetching the catalog once:
+
+```bash
+npx @spardutti/claude-skills --sync-all
+```
 
 `--local[=path]` reads the catalog from a working copy instead of GitHub, so an unreleased change can be installed and tried without publishing it first:
 
@@ -185,7 +191,7 @@ commands/      Slash commands installed to .claude/commands/
 agents/        Subagent definitions — commands declare which they need via requires-agents
 scripts/       validate-skills.mjs — checks skill length caps and reference integrity
                gauntlet.sh — the Stop-hook verification gates, embedded by the CLI
-               ship-gate.sh — /ship's file-length and mutation checks, behind an exit code
+               ship-gate.sh — /ship's file-length, folder-structure and mutation checks, behind an exit code
                ship-gate-hook.sh — refuses gh pr create/merge without a ship-gate receipt
                version-check.sh — SessionStart nudge when a newer catalog is published
                gauntlet-selftest.sh — behavioural tests for the hooks (runs on pre-push)

package/bin/cli.mjs

@@ -2,15 +2,16 @@
 
 import { confirm } from "@inquirer/prompts";
 import chalk from "chalk";
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
 import { fetchSkills, fetchCommands, fetchAgents } from "../lib/github.mjs";
 import { promptSkillSelection, promptCommandSelection, promptRemoval } from "../lib/prompt.mjs";
 import { installSkills, installCommands, installRequiredAgents } from "../lib/install.mjs";
 import { makeLocalSource } from "../lib/local.mjs";
 import { runPostInstall } from "../lib/post-install.mjs";
-import { setupHook } from "../lib/setup-hook.mjs";
+import { runSync, runSyncAll } from "../lib/sync.mjs";
 import {
   readManifest, writeManifest, computeOrphans, computeRemovals, scanInstalled, removeArtifacts,
   MANIFEST_FILE,
@@ -20,38 +21,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 const CWD = process.cwd();
 
-// `--sync`: re-install everything the manifest records (refreshed to the latest
-// catalog), refresh hooks the project already has, and prune anything removed upstream.
-async function runSync(manifest, catalog) {
-  if (!manifest) {
-    console.log(`  ${chalk.yellow("Nothing to sync")} — no manifest in this project. Run without --sync first.\n`);
-    return;
-  }
-  const orphans = computeOrphans(manifest, catalog);
-  const orphanCount = orphans.skills.length + orphans.commands.length + orphans.agents.length;
-  if (orphanCount > 0) {
-    await removeArtifacts(CWD, orphans);
-    console.log(`  ${chalk.green("✔")} Pruned ${orphanCount} item(s) removed from the catalog.`);
-  }
-
-  const skills = catalog.skills.filter((s) => manifest.skills.includes(s.dirName));
-  const commands = catalog.commands.filter((c) => manifest.commands.includes(c.fileName));
-  if (skills.length > 0) { console.log(); await installSkills(skills); }
-  if (commands.length > 0) { console.log(); await installCommands(commands); }
-  const { installed } = await installRequiredAgents(commands, catalog.agents, CWD);
-  if (existsSync(join(CWD, ".claude", "hooks", "skill-gate.sh"))) { console.log(); await setupHook(CWD); }
-
-  await writeManifest(CWD, {
-    catalogVersion: pkg.version,
-    skills: skills.map((s) => s.dirName),
-    commands: commands.map((c) => c.fileName),
-    agents: installed.map((a) => a.fileName),
-  });
-  console.log(`\n  ${chalk.green("✔")} ${chalk.bold(`Synced to catalog v${pkg.version}.`)}\n`);
-}
-
 async function main() {
   const isSync = process.argv.includes("--sync");
+  // --sync-all[=dir] syncs every project under dir (default: home) from one catalog fetch.
+  const syncAllArg = process.argv.find((a) => a === "--sync-all" || a.startsWith("--sync-all="));
+  const syncAllRoot = syncAllArg ? resolve(syncAllArg.split("=")[1] || homedir()) : null;
 
   // --local[=path] reads the catalog from a working copy instead of GitHub, so an
   // unreleased change can be installed and tried without publishing it first.
@@ -71,10 +45,10 @@ async function main() {
     fetchers.fetchSkills(), fetchers.fetchCommands(), fetchers.fetchAgents(),
   ]);
   const catalog = { skills, commands, agents };
+  if (syncAllRoot) return runSyncAll(syncAllRoot, catalog, pkg.version);
+  if (isSync) return runSync(CWD, catalog, pkg.version);
   const manifest = await readManifest(CWD);
 
-  if (isSync) return runSync(manifest, catalog);
-
   // --- Prune items renamed or removed from the catalog upstream ---
   const orphans = computeOrphans(manifest, catalog);
   const orphanNames = [...orphans.skills, ...orphans.commands, ...orphans.agents];

package/hooks/ship-gate-structure.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Sourced by ship-gate.sh: a new file must sit in the folder named for its kind.
+# Only ADDED files are judged, so a repo laid out the old way cannot get worse and need not move.
+
+STRUCTURE_JS_KINDS="components|hooks|api|queries|schemas|types|utils|stores|test"
+STRUCTURE_KIND_FILE='(^|[._])(router|routes|controller|service|schema|model)s?\.[cm]?[jt]s$|(Router|Routes|Controller|Service|Schema|Model)s?\.[cm]?[jt]s$'
+
+# --no-renames: a move must show up as an add, or renaming a misplaced file would slip through.
+added_files() {
+  { git diff --no-renames --diff-filter=A --name-only "$BASE"...HEAD 2>/dev/null
+    git diff --no-renames --diff-filter=A --name-only HEAD 2>/dev/null
+    git ls-files --others --exclude-standard 2>/dev/null; } | sort -u
+}
+
+has_subject() {  # has_subject <test path>: a file the test is named for, in the same folder
+  d=$(dirname "$1")
+  stem=$(basename "$1" | sed -E 's/\.(test|spec)\.[^.]+$//')
+  while :; do
+    for e in ts tsx js jsx mjs cjs astro; do [ -f "$d/$stem.$e" ] && return 0; done
+    case "$stem" in *.*) stem=${stem%.*} ;; *) return 1 ;; esac
+  done
+}
+
+feature_misplaced() {  # feature_misplaced <path below features/<name>/>
+  case "$1" in
+    index.*) ;;
+    */*) printf '%s' "${1%%/*}" | grep -qxE "$STRUCTURE_JS_KINDS" \
+           || echo "${1%%/*}/ is not a kind folder ($STRUCTURE_JS_KINDS)" ;;
+    *) echo "loose at the feature root, where only index.* belongs" ;;
+  esac
+}
+
+js_misplaced() {  # js_misplaced <path> <owner>
+  f=$1; b=${f##*/}; parent=$(basename "$(dirname "$f")")
+  if printf '%s' "$b" | grep -qE '\.(test|spec)\.[^.]+$'; then
+    printf '%s' "/$f" | grep -qE '/(e2e|tests?)/' && return
+    has_subject "$f" || echo "a test sits beside the file it tests, and nothing here is named ${b%%.*}"
+    return
+  fi
+  rest=$(printf '%s' "/$f" | sed -nE 's#.*/features/[^/]+/##p')
+  if [ -n "$rest" ]; then feature_misplaced "$rest"; return; fi
+  kinds="components|hooks|queries|api|schemas|types|utils"
+  grep -qs '"express"' "$2/package.json" && kinds="$kinds|routes|controllers|services|middleware|models"
+  if printf '%s' "/$f" | grep -qE "/src/($kinds)/"; then
+    echo "sorted by kind first; it belongs in <domain>/<kind>/ or shared/<kind>/"
+  elif printf '%s' "$b" | grep -qE '^use[A-Z].*\.[jt]sx?$' && ! printf '%s' "/$f" | grep -qE '/(hooks|queries)/'; then
+    echo "a hook belongs in hooks/ or queries/"
+  elif printf '%s' "$b" | grep -qE "$STRUCTURE_KIND_FILE" \
+       && ! printf '%s' "$parent" | grep -qxE 'routes|controllers|services|schemas|models|api|queries|types'; then
+    echo "the kind is in the filename; it belongs in a kind folder"
+  fi
+}
+
+py_misplaced() {  # py_misplaced <path>
+  f=$1; b=${f##*/}; d=$(dirname "$f"); parent=${d##*/}
+  case "$b" in
+    test_*.py|*_test.py|conftest.py)
+      printf '%s' "/$f" | grep -qE '/tests/' || echo "tests live under tests/, mirroring the app"
+      return ;;
+  esac
+  k=$(printf '%s' "$b" | sed -nE 's/^(.*_)?(router|service|schema|model)s?\.py$/\2/p')
+  if [ -n "$k" ] && [ "$parent" != "${k}s" ]; then
+    echo "the kind is in the filename; it belongs in ${k}s/"
+  elif printf '%s' "$parent" | grep -qxE 'routers|services|schemas|models' && [ -f "$(dirname "$d")/main.py" ]; then
+    echo "sorted by kind first; it belongs in <domain>/$parent/"
+  fi
+}
+
+structure_check() {
+  bad=""; count=0
+  while IFS= read -r f; do
+    [ -f "$f" ] && ! is_ignored "$f" || continue
+    printf '%s' "/$f" | grep -qE '/(node_modules|\.stryker-tmp|mutants)/' && continue
+    o=$(owner_of "$f")
+    case "$f" in
+      *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.astro) why=$(js_misplaced "$f" "$o") ;;
+      *.py) grep -qis fastapi "$o/pyproject.toml" || continue; why=$(py_misplaced "$f") ;;
+      *) continue ;;
+    esac
+    count=$((count+1))
+    [ -n "$why" ] && bad="$bad  $f — $why
+"
+  done <<< "$(added_files)"
+  echo
+  if [ -n "$bad" ]; then
+    echo "STRUCTURE — new files outside their kind folder:"
+    printf '%s' "$bad"
+    echo "  Move them (Project Structure in the react, fastapi or express skill), or ship with --force."
+    echo
+    return 1
+  fi
+  echo "STRUCTURE — ok, $count new file(s) in their kind folder"
+  echo
+}
+
+# Called when nothing else in the diff is gated, so the gate would otherwise pass it.
+structure_fail() {
+  echo "ship-gate: FAIL — deal with the findings above, then run this again."
+  echo "           To ship anyway: bash .claude/hooks/ship-gate.sh --force"
+  rm -f "$RECEIPT"
+  exit 1
+}

package/hooks/ship-gate.sh

@@ -46,7 +46,7 @@
 set -uo pipefail
 
 HERE=$(cd "$(dirname "$0")" && pwd)
-. "$HERE/ship-gate-projects.sh" || { echo "ship-gate: cannot read $HERE/ship-gate-projects.sh"; exit 1; }
+. "$HERE/ship-gate-projects.sh" && . "$HERE/ship-gate-structure.sh" || { echo "ship-gate: cannot read its helpers in $HERE"; exit 1; }
 
 MODE=""
 case "${1:-}" in
@@ -76,7 +76,7 @@ GAUNTLET_MAX_LINES=200
 GAUNTLET_MUTATE=""
 GAUNTLET_SOURCE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|gd"
 GAUNTLET_IGNORE_EXT="md|mdx|txt|rst|adoc|jsonc?|ya?ml|toml|lock|cfg|ini|env|csv|tsv|sql|html|css|scss|svg|png|jpg|jpeg|gif|webp|ico|pdf|woff2?|ttf|otf|mp3|mp4|wav|zip|gz|tres|tscn|import|godot"
-GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alembic/versions/*.py */components/ui/*.tsx */*.config.*"
+GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alembic/versions/*.py */components/ui/*.tsx */hooks/use-mobile.ts */*.config.*"
 # Length-checked and skill-audited like everything else, but not mutated.
 # Mutation pays on logic and burns time on presentation: a component's mutants
 # are class names, copy and JSX shape, none of which is behaviour, and one
@@ -159,6 +159,8 @@ if [ -n "$IGNORED" ]; then
   printf '%s\n' "$IGNORED" | sed 's/^/  /'
 fi
 
+[ -n "$FILES" ] && echo "ship-gate: $(printf '%s\n' "$FILES" | wc -l) changed code file(s), base $(git rev-parse --short "$BASE")"
+STATUS=0; structure_check || { STATUS=1; [ -z "$FILES" ] && structure_fail; }
 if [ -z "$FILES" ]; then
   # "I recognised nothing" is not "there is nothing", and the gate used to report
   # both as a PASS. A Godot repo changed only .gd files, which no extension in
@@ -183,10 +185,6 @@ if [ -z "$FILES" ]; then
   exit 0
 fi
 
-echo "ship-gate: $(printf '%s\n' "$FILES" | wc -l) changed code file(s), base $(git rev-parse --short "$BASE")"
-echo
-STATUS=0
-
 # ------------------------------------------------- check 1: file length (hard)
 OVER=""
 LARGEST=0

package/lib/setup-hook.mjs

@@ -27,6 +27,7 @@ const APPLICATION_GATE_FILENAME = "skill-application-gate.sh";
 const GAUNTLET_FILENAME = "gauntlet.sh";
 const SHIP_GATE_FILENAME = "ship-gate.sh";
 const SHIP_GATE_PROJECTS_FILENAME = "ship-gate-projects.sh";
+const SHIP_GATE_STRUCTURE_FILENAME = "ship-gate-structure.sh";
 const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
 const VERSION_CHECK_FILENAME = "version-check.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
@@ -106,6 +107,7 @@ export async function setupHook(targetDir = process.cwd()) {
     GAUNTLET_FILENAME,
     SHIP_GATE_FILENAME,
     SHIP_GATE_PROJECTS_FILENAME,
+    SHIP_GATE_STRUCTURE_FILENAME,
     SHIP_GATE_HOOK_FILENAME,
     VERSION_CHECK_FILENAME,
   ]) {

package/lib/sync.mjs

@@ -0,0 +1,81 @@
+import chalk from "chalk";
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { installSkills, installCommands, installRequiredAgents } from "./install.mjs";
+import { setupHook } from "./setup-hook.mjs";
+import { readManifest, writeManifest, computeOrphans, removeArtifacts, MANIFEST_FILE } from "./manifest.mjs";
+
+const SEARCH_DEPTH = 5;
+
+// Re-install everything the manifest records (refreshed to the latest catalog),
+// refresh hooks the project already has, and prune anything removed upstream.
+export async function runSync(dir, catalog, version) {
+  const manifest = await readManifest(dir);
+  if (!manifest) {
+    console.log(`  ${chalk.yellow("Nothing to sync")} — no manifest in this project. Run without --sync first.\n`);
+    return false;
+  }
+  const orphans = computeOrphans(manifest, catalog);
+  const orphanCount = orphans.skills.length + orphans.commands.length + orphans.agents.length;
+  if (orphanCount > 0) {
+    await removeArtifacts(dir, orphans);
+    console.log(`  ${chalk.green("✔")} Pruned ${orphanCount} item(s) removed from the catalog.`);
+  }
+
+  const skills = catalog.skills.filter((s) => manifest.skills.includes(s.dirName));
+  const commands = catalog.commands.filter((c) => manifest.commands.includes(c.fileName));
+  if (skills.length > 0) { console.log(); await installSkills(skills, dir); }
+  if (commands.length > 0) { console.log(); await installCommands(commands, dir); }
+  const { installed } = await installRequiredAgents(commands, catalog.agents, dir);
+  if (existsSync(join(dir, ".claude", "hooks", "skill-gate.sh"))) { console.log(); await setupHook(dir); }
+
+  await writeManifest(dir, {
+    catalogVersion: version,
+    skills: skills.map((s) => s.dirName),
+    commands: commands.map((c) => c.fileName),
+    agents: installed.map((a) => a.fileName),
+  });
+  console.log(`\n  ${chalk.green("✔")} ${chalk.bold(`Synced to catalog v${version}.`)}\n`);
+  return true;
+}
+
+export async function findProjects(root, depth = SEARCH_DEPTH) {
+  if (existsSync(join(root, ".claude", MANIFEST_FILE))) return [root];
+  if (depth === 0) return [];
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith(".") || e.name === "node_modules") continue;
+    found.push(...(await findProjects(join(root, e.name), depth - 1)));
+  }
+  return found;
+}
+
+export async function runSyncAll(root, catalog, version) {
+  const projects = await findProjects(root);
+  if (projects.length === 0) {
+    console.log(`  ${chalk.yellow("No projects found")} under ${root} with .claude/${MANIFEST_FILE}.\n`);
+    return;
+  }
+  const failed = [];
+  for (const dir of projects) {
+    console.log(chalk.bold.cyan(`── ${dir}`));
+    try {
+      await runSync(dir, catalog, version);
+    } catch (err) {
+      failed.push(basename(dir));
+      console.log(`  ${chalk.red("Error:")} ${err.message}\n`);
+    }
+  }
+  const ok = projects.length - failed.length;
+  console.log(`  ${chalk.green("✔")} ${chalk.bold(`${ok} of ${projects.length} project(s) synced to v${version}.`)}`);
+  if (failed.length > 0) console.log(`  ${chalk.red("✘")} Failed: ${failed.join(", ")}`);
+  console.log();
+  if (failed.length > 0) process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.33.8",
+  "version": "2.35.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
     "claude-skills": "bin/cli.mjs"
   },
   "scripts": {
-    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
+    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {