@casomoltd/tooling 0.20.0

package/README.md

@@ -0,0 +1,281 @@
+# @casomoltd/tooling
+
+Shared linting, formatting, commit config, and CLI tools for Casomo Ltd's repos.
+
+## What's included
+
+### Exports
+
+| Export | Description |
+|---|---|
+| `@casomoltd/tooling/eslint` | `createBaseConfig()` — ESLint flat config with Next.js, TypeScript, and SonarJS |
+| `@casomoltd/tooling/eslint-lib` | ESLint config variant for library packages |
+| `@casomoltd/tooling/prettier` | Prettier config object |
+| `@casomoltd/tooling/commitlint` | commitlint config with `no-ai-attribution` plugin |
+| `@casomoltd/tooling/knip` | Knip config for unused exports/dependencies |
+| `@casomoltd/tooling/jscpd` | Copy-paste detection config |
+| `@casomoltd/tooling/readability` | `scoreText()` — readability scoring for page content |
+
+### Bin commands
+
+| Command | Description |
+|---|---|
+| `check-version` | Pre-push guard — rejects push if `package.json` version hasn't changed vs `origin/main` |
+| `pre-push` | Husky pre-push hook — runs check, build, then version/tag guards |
+| `pre-commit` | Husky pre-commit hook — runs `npm run check` |
+| `commit-msg` | Husky commit-msg hook — runs commitlint |
+| `readability` | Measure reading difficulty of page content |
+| `screenshot` | Capture a dev server page via Puppeteer |
+
+## Install
+
+Consumed as a **git dependency** — it's shared config + CLI scripts,
+not a registry package. Add it to a consumer's `devDependencies`:
+
+```json
+"@casomoltd/tooling": "github:casomoltd/tooling#semver:^0.10.0"
+```
+
+The repo is public, so installs need no token. The `files` allowlist
+plus the `verify-pack` leak-gate keep the installed surface to
+configs/CLI only.
+
+## Husky hooks
+
+The package provides shared hook commands so all repos enforce
+the same standards. Wire them up in `.husky/`:
+
+**.husky/pre-commit**
+```
+pre-commit
+```
+
+**.husky/commit-msg**
+```
+commit-msg $1
+```
+
+**.husky/pre-push**
+```
+pre-push
+```
+
+Each repo defines its own `check` script in `package.json` —
+the hooks call `npm run check` which runs whatever checks that
+repo needs (lint, typecheck, spell, etc.).
+
+**Note:** The tooling repo itself calls scripts by path in its
+hooks (e.g. `./bin/check-version.sh`) because it can't resolve
+its own bin commands via `node_modules/.bin`.
+
+## Markdown / skills lint
+
+`bin/skills-lint.config.mjs` is a stock remark config (`remark-frontmatter` +
+`remark-validate-links` + `remark-lint-frontmatter-schema`) that validates a
+Claude Code skills/agents/docs tree: every `SKILL.md` / `agents/*.md` has
+parseable YAML frontmatter with `name` + `description`, and every relative link
+and `#anchor` resolves. tooling runs it over its own `skills/` in `npm run
+check` (`lint:skills`) — catching the breakage a rename or hand-edit leaves that
+Claude Code's loader silently swallows.
+
+To gate a consumer repo's docs (link/anchor integrity) at its own pre-commit,
+install the remark toolchain and point it at the shipped config:
+
+```bash
+npm i -D remark-cli remark-frontmatter remark-validate-links remark-lint-frontmatter-schema
+```
+
+```json
+"lint:md": "remark --frail --quiet --no-stdout --rc-path node_modules/@casomoltd/tooling/bin/skills-lint.config.mjs docs"
+```
+
+Append `&& npm run lint:md` to your `check` script. The config resolves the
+plugins from your repo's `node_modules` and the schema (shipped beside it)
+relative to your cwd; the frontmatter schema only matches `SKILL.md`/`agents`
+files, so for plain docs it acts as a link/anchor check. Requires a tooling
+version that ships the config.
+
+## Screenshot tool
+
+Capture the running dev server for visual inspection:
+
+```bash
+npm run ss              # 1280×800 desktop capture
+npm run ss contact      # desktop capture of /contact
+npm run ss -- --width 390 --height 844   # mobile capture
+npm run ss contact --width 390           # mobile /contact
+```
+
+**Options:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--width <n>` | 1280 | Viewport width in pixels |
+| `--height <n>` | 800 | Viewport height in pixels |
+
+Add these scripts to your `package.json`:
+
+```json
+{
+  "screenshot": "screenshot",
+  "ss": "npm run screenshot --"
+}
+```
+
+Screenshots are saved to `.claude/screenshots/`. Set
+`SCREENSHOT_URL` to override the default `http://localhost:3000`.
+
+## Quality gates
+
+There is no CI — all quality gates run locally via git hooks.
+Code should be deployment-ready by the time it's pushed to
+the remote.
+
+- **pre-commit**: Runs commitlint only (fast).
+- **pre-push**: Runs the full suite — `npm run check`,
+  `npm run build`, then version and tag guards. This ensures
+  lint, typecheck, spelling, and version bumps are all verified
+  before code reaches the remote.
+
+## Usage
+
+**.prettierrc.js**
+```js
+module.exports = require('@casomoltd/tooling/prettier');
+```
+
+**commitlint.config.cjs**
+```cjs
+module.exports = require('@casomoltd/tooling/commitlint');
+```
+
+**eslint.config.mjs**
+```js
+import { createBaseConfig } from '@casomoltd/tooling/eslint';
+```
+
+The ESLint config uses a factory function that receives
+resolved imports from the consumer to avoid module resolution
+issues across package boundaries.
+
+## Local development
+
+Changes to tooling require a push to `main` to publish (the
+workflow runs automatically). Consuming repos then pick up
+changes with `npm update @casomoltd/tooling`.
+
+For fast iteration while editing tooling config locally, use
+`npm link` to temporarily symlink your local checkout:
+
+```bash
+# in the consuming repo
+npm link ../tooling
+```
+
+This overrides the published version until the next
+`npm install`, which restores the registry version.
+
+## Claude Code skills (plugin)
+
+This repo is a Claude Code plugin (`.claude-plugin/`) shipping the **generic,
+public engineering standards** we work to across three agent-facing surfaces —
+**skills**, **hooks**, and **agents**. Business-specific ones live in private
+workspace config, not here.
+
+The tooling serves three consumers: **Claude** (the editing workflow) → these
+plugin surfaces; **CI + git-hooks** (automation) → the npm `bin` scripts; manual
+human CLI is no longer a design target.
+
+**Authoring standard:** creating or editing a skill/agent follows
+[`docs/skill-agent-schema.md`](docs/skill-agent-schema.md) — the interface schema
+(three profiles — procedural skill · agent · standard/rubric — plus a frontmatter
+decision table) that keeps these units composing without overlap.
+
+| Skill | Description |
+|---|---|
+| `/casomoltd:commit` | Run checks and commit cleanly (no bump, no push) |
+| `/casomoltd:release-version` | Bump → push → CI publish/deploy (the release tail) |
+| `/casomoltd:frontend-design` | Distinctive, production-grade frontend UI |
+| `/casomoltd:python-style` | Python code-generation style rules |
+| `/casomoltd:typescript` | TypeScript data modelling and type design |
+| `/casomoltd:screenshot` | Capture and analyse a dev server page |
+| `/casomoltd:design-pass` | Map → review → refactor a package (drives `design-xray` + `code-review`) |
+| `/casomoltd:draft-design-spec` | Author a browser-reviewable HTML design spec from a brief and iterate on it before writing code (drives `design-xray`) |
+
+Enable the plugin by adding this repo as a marketplace and installing it:
+
+```bash
+/plugin marketplace add casomoltd/tooling
+/plugin install casomoltd@casomo-tooling
+```
+
+Skills then load namespaced as `/casomoltd:<name>`.
+
+### Hooks
+
+The plugin also ships generic **PreToolUse hooks** (`hooks/`) that guard
+command/shell intent no linter or commit hook can see: confirm before
+`git push`, hard-block destructive git, `npm version major`, global installs,
+and edits that weaken TypeScript strictness. (They deliberately don't duplicate
+what commitlint/eslint already enforce — see `hooks/README.md`.) The guards are
+advisory — they ask you to confirm when they can't read a call's input, and
+never hard-block on their own malfunction. They require **Node ≥ 22.18 / ≥ 24**
+(they run as TypeScript `.mts` via native type-stripping — no build step).
+
+See [`hooks/README.md`](hooks/README.md) for the full rule set, the file map,
+how the hooks relate to `settings.json` permissions and skill `allowed-tools`,
+and the TypeScript / vendored-types design rationale.
+
+### Agents
+
+Three namespaced agents (`agents/`), each read-only on what it inspects and
+preloading the relevant house standard as its rubric — `typescript` for
+`.ts/.tsx`, `python-style` for `.py`, `docs-style` for markdown. `design-xray` and
+`docs-xray` persist only their own report (see *Report output*, below).
+
+**`casomoltd:code-review`** enforces the *judgment-level* half of the standards —
+the design calls a linter can't make (typed identifiers, static/varying
+separation, swallowed exceptions; class design, polymorphism over type-codes,
+value objects, EAFP, framework-first, test naming). It **complements, never
+duplicates**: eslint/ruff own the mechanical rules, the built-in `/code-review`
+owns correctness bugs, this owns the house design standards. Namespaced so it
+doesn't collide with the bundled `/code-review`. Invoke with
+`@agent-casomoltd:code-review` (or let Claude auto-delegate); it reports findings
+and never edits.
+
+**`casomoltd:design-xray`** takes a package or diff and returns the *structural*
+picture: a doc-ready module inventory + mermaid class-hierarchy diagram, a weight
+table (which modules/classes are too heavy or thin), prioritized design findings,
+a ranked handoff of refactor targets, and a verdict on whether a heavier pattern
+(e.g. a state machine) is warranted yet or premature. It feeds forward — its map
+lifts straight into package docs, and its targets drive `code-review` and a
+refactor pass. The `/casomoltd:design-pass` skill chains the three
+(x-ray → code-review → refactor), and `/casomoltd:draft-design-spec` reuses its
+current-state map as the "before" picture when authoring a pre-implementation
+design spec. Like its sibling it visualizes and judges structure only — no
+correctness bugs (that's `/code-review`), no lint (eslint/ruff).
+
+**`casomoltd:docs-xray`** is the same idea for a *documentation* corpus: it walks
+every markdown doc (README, `CLAUDE.md`, `docs/`, skill/agent definitions) and
+returns a map — each doc's heading tree + outbound pointers, plus a mermaid
+reference-graph of how the docs link — and a coherence report: orphan docs nothing
+links to, stale cross-references whose summary has drifted from the target,
+duplicated coverage, and missing back-links. It judges structure and
+cross-reference coherence against `docs-style` — not mechanical broken links
+(that's a markdown link linter) or prose voice (a content reviewer).
+
+**Report output & `SCRATCH_DIR`.** `design-xray` and `docs-xray` persist their
+report — the `.md` plus an `.html` rendered by `bin/render-report.mjs` — so it
+outlives the run and opens in a browser. Each writes to a gitignored
+`<repo-root>/scratch/<agent>/` by default. Set the optional **`SCRATCH_DIR`** env
+var to pool every report under one shared location instead (`$SCRATCH_DIR/<agent>/`)
+— e.g. a multi-repo workspace collecting reports in one place rather than scattering
+them per-repo. Publishing a report to a hosted claude.ai artifact is orchestrator-
+only and on explicit request; the agents never do it.
+
+## Package distribution
+
+The product libraries (`@casomoltd/paye-calc`, `@casomoltd/nhs-pay`)
+publish to the public npm registry via OIDC trusted publishing — install
+with no auth or `.npmrc`. `@casomoltd/tooling` is **not** published; it's
+consumed as a git dependency from this (public) repo.

package/bin/check-tags.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# Ensure push.followTags is enabled when pushing to main.
+# Non-main branches skip this check.
+
+PUSHING_MAIN=false
+while read -r _ _ REMOTE_REF _; do
+  case "$REMOTE_REF" in
+    refs/heads/main) PUSHING_MAIN=true ;;
+  esac
+done
+
+if [ "$PUSHING_MAIN" = false ]; then
+  exit 0
+fi
+
+FOLLOW=$(git config --get push.followTags 2>/dev/null)
+
+if [ "$FOLLOW" != "true" ]; then
+  echo "push.followTags is not enabled."
+  echo "Run: git config push.followTags true"
+  exit 1
+fi

package/bin/check-version.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Reject push to main if version hasn't changed vs origin/main.
+# Non-main branches skip this check.
+
+PUSHING_MAIN=false
+while read -r _ _ REMOTE_REF _; do
+  case "$REMOTE_REF" in
+    refs/heads/main) PUSHING_MAIN=true ;;
+  esac
+done
+
+if [ "$PUSHING_MAIN" = false ]; then
+  exit 0
+fi
+
+LOCAL_VERSION=$(node -p "require('./package.json').version")
+REMOTE_VERSION=$(git show origin/main:package.json 2>/dev/null \
+  | node -p \
+    "JSON.parse(require('fs').readFileSync(0)).version" \
+    2>/dev/null)
+
+if [ "$LOCAL_VERSION" = "$REMOTE_VERSION" ]; then
+  echo \
+    "Version unchanged ($LOCAL_VERSION)." \
+    "Run: npm version patch|minor|major"
+  exit 1
+fi
+
+echo "Version: $REMOTE_VERSION -> $LOCAL_VERSION"

package/bin/commit-msg.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+npx --no -- commitlint --edit "$1"

package/bin/pre-commit.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+npm run check

package/bin/pre-push.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Capture ref info from git — sub-scripts need it to detect
+# whether we're pushing to main.
+PRE_PUSH_REFS=$(cat)
+export PRE_PUSH_REFS
+
+# Uniform pre-push for every repo: check, build, then the version/tag gates.
+# `npm run build` must exist in EVERY repo so this line never has to special-case
+# one. Where a repo produces no build output (a source-only repo like tooling,
+# consumed as a git-dep), define build as a no-op (`"build": "echo ..."`) rather
+# than omitting it — a missing script would abort the push with "Missing script:
+# build", which once made it ambiguous whether a source-only repo was even
+# pushable. No-op keeps the step honest and uniform.
+npm run check \
+  && npm run build \
+  && echo "$PRE_PUSH_REFS" | check-version \
+  && echo "$PRE_PUSH_REFS" | check-tags

package/bin/readability.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * Measure reading difficulty of site pages from source files.
+ *
+ * Usage:
+ *   npm run readability [-- slug] [-- --pretty] [-- --max-grade <n>]
+ *
+ * Arguments:
+ *   slug        Optional path segment (e.g. "finance/mortgage-calculator").
+ *               If omitted, all pages discovered in src/app/ are checked.
+ *   --pretty    Print a human-readable table alongside JSON output.
+ *   --max-grade Maximum consensus grade level (default: 12).
+ *
+ * Per-repo config:
+ *   Place a readability.config.mjs in the project root to override
+ *   defaults. Exports: wordSubs (object), maxGrade (number).
+ *
+ * Exit codes:
+ *   0  All pages pass the grade threshold
+ *   1  One or more pages exceed the threshold
+ */
+
+import {parseArgs} from "node:util";
+import path from "node:path";
+import {loadConfig} from "./utils.mjs";
+import {
+  discoverSlugs,
+  extractText,
+  scoreText,
+  formatPretty,
+  DEFAULT_MAX_GRADE,
+  DEFAULT_WORD_SUBS,
+} from "../readability/index.mjs";
+
+const PROJECT_ROOT = process.cwd();
+const SRC_APP = path.join(PROJECT_ROOT, "src", "app");
+
+// ---------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------
+
+async function main() {
+  const {values, positionals} = parseArgs({
+    options: {
+      pretty: {type: "boolean", default: false},
+      "max-grade": {type: "string"},
+    },
+    allowPositionals: true,
+  });
+
+  const config = await loadConfig("readability.config.mjs");
+
+  const wordSubs = config.wordSubs ?? DEFAULT_WORD_SUBS;
+  const maxGrade =
+    values["max-grade"] != null
+      ? Number(values["max-grade"])
+      : (config.maxGrade ?? DEFAULT_MAX_GRADE);
+
+  const slug = positionals[0];
+  const slugs = slug
+    ? [`/${slug.replace(/^\//, "")}`]
+    : discoverSlugs(SRC_APP);
+
+  const pages = [];
+  for (const s of slugs) {
+    try {
+      const rel = s === "/" ? "" : s.slice(1);
+      const filePath = path.join(SRC_APP, rel, "page.tsx");
+      const text = extractText(filePath);
+      const result = scoreText(text, wordSubs);
+      const pass =
+        result.consensusGrade == null ||
+        result.consensusGrade <= maxGrade;
+      pages.push({slug: s, ...result, pass});
+    } catch (err) {
+      pages.push({
+        slug: s,
+        wordCount: 0,
+        scores: null,
+        consensusGrade: null,
+        pass: true,
+        error: err.message,
+      });
+    }
+  }
+
+  const allPassed = pages.every((p) => p.pass);
+  const threshold = {maxGrade};
+  const results = {pages, threshold, allPassed};
+
+  if (values.pretty) {
+    console.error(formatPretty(results, threshold));
+  }
+  console.log(JSON.stringify(results, null, 2));
+
+  process.exit(allPassed ? 0 : 1);
+}
+
+main();

package/bin/render-report.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * Render a markdown + mermaid report to a self-contained HTML file and open it
+ * in the browser — the reliable renderer for agent reports (docs-xray,
+ * design-xray) whose mermaid diagrams render unreliably in editor previews.
+ *
+ * The report `.md` is inlined into an HTML harness that loads `marked` and
+ * `mermaid` from CDN, so the output is one portable file — no build step, no
+ * editor extension. Write reports into a repo-local dir (e.g. `scratch/`), not
+ * `/tmp`: sandboxed browsers (snap/flatpak) often can't read outside $HOME.
+ *
+ * Usage:
+ *   node bin/render-report.mjs <report.md> [--no-open]
+ *
+ * Arguments:
+ *   <report.md>  Path to the markdown report. The HTML is written next to it as
+ *                <report>.html.
+ *   --no-open    Write the HTML but don't launch a browser (print the path only).
+ *
+ * Exit codes:
+ *   0  HTML written (and opened unless --no-open)
+ *   1  Bad arguments or the input file is missing
+ */
+import {spawn} from "node:child_process";
+import {existsSync, readFileSync, writeFileSync} from "node:fs";
+import {resolve} from "node:path";
+
+const args = process.argv.slice(2);
+const noOpen = args.includes("--no-open");
+const mdPath = args.find((a) => !a.startsWith("--"));
+
+if (!mdPath || !existsSync(mdPath)) {
+  console.error("usage: render-report.mjs <report.md> [--no-open]");
+  process.exit(1);
+}
+
+const htmlPath = mdPath.replace(/\.md$/, "") + ".html";
+
+// A mermaid classDiagram rejects union/bracket types in a member line
+// (`date|None`, `list[Item]`) — soften them inside class bodies so an imperfect
+// source (e.g. a design-xray map) still renders. Scoped to classDiagram fences
+// only, so other diagrams (docs-xray flowcharts) are left untouched.
+const softenClassDiagrams = (text) =>
+  text.replace(/```mermaid\n([\s\S]*?)```/g, (block, body) =>
+    /\bclassDiagram\b/.test(body)
+      ? "```mermaid\n" +
+        body.replace(/\{[^{}]*\}/g, (b) =>
+          b.replace(/\|/g, " or ").replace(/[[\]]/g, ""),
+        ) +
+        "```"
+      : block,
+  );
+
+// Inline the markdown in a <script type="text/markdown"> so its backticks and
+// fences aren't parsed as HTML. The only hazard is a literal </script> in the
+// source, which we defuse.
+const md = softenClassDiagrams(readFileSync(mdPath, "utf8")).replaceAll(
+  "</script>",
+  "<\\/script>",
+);
+
+const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${mdPath}</title>
+<style>
+  body { max-width: 1200px; margin: 2rem auto; padding: 0 1.5rem;
+         font: 15px/1.6 system-ui, sans-serif; color: #1a1a1a; }
+  h1, h2, h3 { line-height: 1.25; }
+  h2 { border-bottom: 1px solid #eee; padding-bottom: .3rem; margin-top: 2.5rem; }
+  table { border-collapse: collapse; margin: 1rem 0; font-size: 14px; }
+  th, td { border: 1px solid #ddd; padding: 6px 10px; text-align: left; vertical-align: top; }
+  th { background: #f7f7f7; }
+  code { background: #f4f4f4; padding: 1px 5px; border-radius: 3px; font-size: .9em; }
+  pre { background: #f7f7f7; padding: 1rem; border-radius: 6px; overflow-x: auto; }
+  pre.mermaid { background: #fff; }
+  a { color: #0b66c3; }
+</style>
+</head>
+<body>
+<div id="content">Rendering…</div>
+<script id="md" type="text/markdown">
+${md}
+</script>
+<script type="module">
+import { marked } from "https://cdn.jsdelivr.net/npm/marked/lib/marked.esm.js";
+import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+mermaid.initialize({ startOnLoad: false, theme: "neutral" });
+const el = document.getElementById("content");
+el.innerHTML = marked.parse(document.getElementById("md").textContent);
+// marked emits mermaid fences as <code class="language-mermaid">; mermaid wants
+// <pre class="mermaid">.
+el.querySelectorAll("code.language-mermaid").forEach((c) => {
+  const pre = document.createElement("pre");
+  pre.className = "mermaid";
+  pre.textContent = c.textContent;
+  c.closest("pre").replaceWith(pre);
+});
+await mermaid.run({ querySelector: ".mermaid" });
+</script>
+</body>
+</html>
+`;
+
+writeFileSync(htmlPath, html);
+const url = `file://${resolve(htmlPath)}`;
+console.log(url);
+
+if (!noOpen) {
+  // text/html must be associated with a browser, not a mail client; if the
+  // opener mis-routes on Linux, run e.g.
+  //   xdg-mime default firefox_firefox.desktop text/html
+  const opener = process.platform === "darwin" ? "open" : "xdg-open";
+  spawn(opener, [url], {detached: true, stdio: "ignore"}).unref();
+}

package/bin/schemas/frontmatter.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude Code skill/agent frontmatter",
+  "description": "The loader needs name + description; anything else (tools, model, user-invocable, argument-hint, allowed-tools…) is allowed. Validating this catches the case Claude Code swallows silently — malformed YAML loads with empty metadata.",
+  "type": "object",
+  "required": ["name", "description"],
+  "properties": {
+    "name": {"type": "string", "minLength": 1},
+    "description": {"type": "string", "minLength": 1}
+  }
+}

package/bin/screenshot.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * Capture a screenshot of the running dev server.
+ *
+ * Usage:
+ *   npm run ss [page] [--width <n>] [--height <n>]
+ *
+ * Arguments:
+ *   page  Optional path segment appended to the base URL. Also used as the
+ *         filename prefix. Defaults to "base" (captures the root page).
+ *
+ * Options:
+ *   --preset <name>  Viewport preset: mobile (390×844),
+ *                    tablet (768×1024), desktop (1280×800)
+ *   --width <n>      Viewport width in pixels (default: 1280)
+ *   --height <n>     Viewport height in pixels (default: 800)
+ *
+ * When --preset is given it overrides --width and --height.
+ *
+ * Examples:
+ *   npm run ss                          # 1280×800 desktop
+ *   npm run ss --preset mobile          # 390×844 mobile
+ *   npm run ss contact --preset tablet  # /contact at 768×1024
+ *
+ * Environment:
+ *   SCREENSHOT_URL  Base URL to capture (default: http://localhost:3000)
+ *
+ * Output:
+ *   .claude/screenshots/{page}-{timestamp}.png  Timestamped capture
+ *   .claude/screenshots/latest.png              Always the most recent capture
+ */
+
+import { parseArgs } from "node:util";
+import path from "path";
+import fs from "fs";
+
+// puppeteer is an optional peer dependency (it pulls Chromium, ~200MB), so
+// consumers that never screenshot don't install it. Load it lazily and fail
+// loud if the screenshot bin is invoked without it.
+async function loadPuppeteer() {
+  try {
+    return (await import("puppeteer")).default;
+  } catch {
+    throw new Error(
+      "puppeteer is not installed — add it as a devDependency " +
+        "(npm i -D puppeteer) to use the screenshot bin.",
+    );
+  }
+}
+
+const BASE_URL =
+  process.env.SCREENSHOT_URL || "http://localhost:3000";
+const OUTPUT_DIR = path.join(
+  process.cwd(),
+  ".claude",
+  "screenshots",
+);
+
+const PRESETS = {
+  mobile: { width: 390, height: 844 },
+  tablet: { width: 768, height: 1024 },
+  desktop: { width: 1280, height: 800 },
+};
+
+const { values, positionals } = parseArgs({
+  options: {
+    preset: { type: "string" },
+    width: { type: "string", default: "1280" },
+    height: { type: "string", default: "800" },
+  },
+  allowPositionals: true,
+});
+
+async function serverIsUp(url) {
+  try {
+    await fetch(url, {signal: AbortSignal.timeout(3000)});
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function screenshot() {
+  if (!(await serverIsUp(BASE_URL))) {
+    console.error(
+      `screenshot: server not reachable at ${BASE_URL}\n` +
+      `Start the dev server first (npm run dev).`,
+    );
+    process.exit(1);
+  }
+
+  const pageName = positionals[0] || "base";
+  const preset = values.preset
+    ? PRESETS[values.preset]
+    : undefined;
+  if (values.preset && !preset) {
+    const names = Object.keys(PRESETS).join(", ");
+    throw new Error(
+      `Unknown preset "${values.preset}". ` +
+        `Choose from: ${names}`,
+    );
+  }
+  const width = preset?.width ?? Number(values.width);
+  const height = preset?.height ?? Number(values.height);
+  const safePrefix = pageName.replace(/\//g, "-");
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/[:.]/g, "-");
+  const filename = `${safePrefix}-${timestamp}.png`;
+
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+
+  const puppeteer = await loadPuppeteer();
+  const browser = await puppeteer.launch({
+    headless: true,
+    args: ["--no-sandbox", "--disable-setuid-sandbox"],
+  });
+
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width, height });
+
+    const url =
+      pageName === "base"
+        ? BASE_URL
+        : `${BASE_URL}/${pageName}`;
+    console.log(`Navigating to ${url}...`);
+
+    await page.goto(url, {
+      waitUntil: "networkidle0",
+      timeout: 30000,
+    });
+
+    const filepath = path.join(OUTPUT_DIR, filename);
+    const latestPath = path.join(OUTPUT_DIR, "latest.png");
+
+    await page.screenshot({ path: filepath, fullPage: true });
+    fs.copyFileSync(filepath, latestPath);
+
+    console.log(`Screenshot saved: ${filepath}`);
+    console.log(`Latest alias: ${latestPath}`);
+  } finally {
+    await browser.close();
+  }
+}
+
+screenshot().catch((err) => {
+  console.error("Screenshot failed:", err.message);
+  process.exit(1);
+});

package/bin/skills-lint.config.mjs

@@ -0,0 +1,44 @@
+// remark config for linting a Claude Code skills/agents/docs tree — the basic
+// smoke test that catches most breakage a rename or hand-edit leaves behind:
+// invalid YAML frontmatter and broken markdown links/anchors. Nothing custom,
+// just three stock remark plugins.
+//
+//   remark-frontmatter             recognise the `---` YAML block
+//   remark-validate-links          every relative link + #anchor resolves
+//   remark-lint-frontmatter-schema frontmatter parses and has name+description
+//
+// Run with cwd = the repo being linted, pointing remark at this file:
+//   remark --frail --quiet --no-stdout --rc-path <this> <paths…>
+// (`--frail` turns findings into a non-zero exit — the gate.) Both the file
+// globs and the schema path are resolved relative to cwd by the plugin, so the
+// schema — which lives here in `tooling` — is expressed relative to whatever
+// cwd remark runs in, letting one config serve tooling's CI and a consumer
+// repo's hook alike.
+import path from "node:path";
+import {fileURLToPath} from "node:url";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkValidateLinks from "remark-validate-links";
+import remarkLintFrontmatterSchema from "remark-lint-frontmatter-schema";
+
+const schemaAbs = fileURLToPath(
+  new URL("./schemas/frontmatter.schema.json", import.meta.url),
+);
+const schema = path.relative(process.cwd(), schemaAbs);
+
+// `**` skips dot-directories, so the plain globs match a non-dot tree (tooling's
+// own `skills/`) while the `.claude/**` variants reach a repo's `.claude/` tree
+// (where every consumer's skills + agents actually live). One config, both.
+const targets = [
+  "**/SKILL.md",
+  ".claude/**/SKILL.md",
+  "**/agents/*.md",
+  ".claude/**/agents/*.md",
+];
+
+export default {
+  plugins: [
+    remarkFrontmatter,
+    [remarkValidateLinks, {repository: false}],
+    [remarkLintFrontmatterSchema, {schemas: {[schema]: targets}}],
+  ],
+};

package/bin/utils.mjs

@@ -0,0 +1,19 @@
+/**
+ * Shared helpers for CLI bin scripts.
+ */
+
+import path from "node:path";
+import fs from "node:fs";
+import {pathToFileURL} from "node:url";
+
+/**
+ * Load an optional per-repo config file from cwd.
+ *
+ * Each CLI tool looks for `<tool>.config.mjs` (e.g.
+ * `readability.config.mjs`) in the consumer's project root.
+ */
+export async function loadConfig(filename) {
+  const cfgPath = path.join(process.cwd(), filename);
+  if (!fs.existsSync(cfgPath)) return {};
+  return import(pathToFileURL(cfgPath).href);
+}

package/bin/verify-pack.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Hard leak-gate: assert the files a consumer would receive (via the
+// `files` allowlist, on publish OR git-dependency install) never escape
+// the allowlist and never look like a secret. Defence-in-depth on top of
+// package.json "files" — this fails CI if that allowlist is ever loosened
+// or a secret-bearing file sneaks in. The tooling repo is public, so the
+// published/installed surface must stay configs + CLI only.
+import {execSync} from "node:child_process";
+
+// Dirs/files a consumer is allowed to receive. npm always adds
+// package.json + LICENSE regardless of the allowlist, so permit those too.
+const ALLOWED_PREFIXES = [
+  "bin/",
+  "eslint/",
+  "prettier/",
+  "commitlint/",
+  "knip/",
+  "jscpd/",
+  "readability/",
+];
+const ALLOWED_FILES = ["README.md", "package.json", "LICENSE", "LICENSE.md"];
+
+// Anything matching these must never ship, even from an allowed dir.
+const SECRET_PATTERN =
+  /(^|\/)(\.env(\..*)?|.*settings\.local\.json|.*\.pem|id_[rd]sa|.*\.key|\.npmrc)$/i;
+
+const raw = execSync("npm pack --dry-run --json", {encoding: "utf8"});
+const files = JSON.parse(raw)[0].files.map((entry) => entry.path);
+
+const escaped = files.filter(
+  (f) =>
+    !ALLOWED_FILES.includes(f) &&
+    !ALLOWED_PREFIXES.some((prefix) => f.startsWith(prefix)),
+);
+const secrets = files.filter((f) => SECRET_PATTERN.test(f));
+
+if (escaped.length || secrets.length) {
+  if (escaped.length) {
+    console.error("✖ files outside the allowlist:\n  " + escaped.join("\n  "));
+  }
+  if (secrets.length) {
+    console.error("✖ secret-like files in package:\n  " + secrets.join("\n  "));
+  }
+  process.exit(1);
+}
+
+console.log(`verify-pack OK — ${files.length} files, all within allowlist`);

package/commitlint/index.cjs

@@ -0,0 +1,22 @@
+module.exports = {
+  rules: {
+    'header-max-length': [2, 'always', 50],
+    'body-max-line-length': [2, 'always', 72],
+    'no-ai-attribution': [2, 'always'],
+  },
+  plugins: [
+    {
+      rules: {
+        'no-ai-attribution': ({ header, body }) => {
+          const fullMessage = `${header}\n${body || ''}`.toLowerCase();
+          const forbidden = ['anthropic', 'claude', 'co-authored-by'];
+          const found = forbidden.filter((term) => fullMessage.includes(term));
+          return [
+            found.length === 0,
+            `Commit must not mention AI tools: found "${found.join(', ')}"`,
+          ];
+        },
+      },
+    },
+  ],
+};

package/eslint/index.mjs

@@ -0,0 +1,51 @@
+/**
+ * Creates the shared ESLint base config.
+ *
+ * Consumers must pass the resolved imports since this package
+ * has no dependencies of its own.
+ *
+ * @param {{ defineConfig, globalIgnores }} eslintConfig - from "eslint/config"
+ * @param {Array} nextVitals - from "eslint-config-next/core-web-vitals"
+ * @param {Array} nextTs - from "eslint-config-next/typescript"
+ * @param {{ configs: { recommended: object } }} sonarjs - from "eslint-plugin-sonarjs"
+ */
+export function createBaseConfig({
+  defineConfig,
+  globalIgnores,
+  nextVitals,
+  nextTs,
+  sonarjs,
+}) {
+  return defineConfig([
+    ...nextVitals,
+    ...nextTs,
+    sonarjs.configs.recommended,
+    globalIgnores([
+      ".next/**",
+      "out/**",
+      "build/**",
+      "next-env.d.ts",
+      ".prettierrc.js",
+    ]),
+    {
+      files: ["**/*.cjs"],
+      rules: {
+        "@typescript-eslint/no-require-imports": "off",
+      },
+    },
+    {
+      rules: {
+        "max-len": [
+          "error",
+          {
+            code: 88,
+            ignoreUrls: true,
+            ignoreStrings: true,
+            ignoreTemplateLiterals: true,
+            ignoreRegExpLiterals: true,
+          },
+        ],
+      },
+    },
+  ]);
+}

package/eslint/lib.mjs

@@ -0,0 +1,40 @@
+/**
+ * Creates a shared ESLint config for TypeScript libraries
+ * (non-Next.js projects).
+ *
+ * Consumers must pass the resolved imports since this package
+ * has no dependencies of its own.
+ *
+ * @param {{ config: Function }} tseslint - from "typescript-eslint"
+ * @param {{ configs: { recommended: object } }} sonarjs
+ *   - from "eslint-plugin-sonarjs"
+ */
+export function createLibConfig({tseslint, sonarjs}) {
+  return tseslint.config(
+    ...tseslint.configs.recommended,
+    sonarjs.configs.recommended,
+    {
+      ignores: ['dist/**', 'node_modules/**'],
+    },
+    {
+      files: ['**/*.cjs'],
+      rules: {
+        '@typescript-eslint/no-require-imports': 'off',
+      },
+    },
+    {
+      rules: {
+        'max-len': [
+          'error',
+          {
+            code: 88,
+            ignoreUrls: true,
+            ignoreStrings: true,
+            ignoreTemplateLiterals: true,
+            ignoreRegExpLiterals: true,
+          },
+        ],
+      },
+    },
+  );
+}

package/jscpd/index.json

@@ -0,0 +1,5 @@
+{
+  "threshold": 5,
+  "reporters": ["console"],
+  "ignore": ["**/dist/**", "**/node_modules/**", "**/*.lock"]
+}

package/knip/index.json

@@ -0,0 +1,4 @@
+{
+  "ignore": ["dist/**"],
+  "ignoreDependencies": []
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@casomoltd/tooling",
+  "version": "0.20.0",
+  "description": "Casomo's shared dev config: ESLint, Prettier, commitlint, knip & jscpd presets and dev CLIs (git hooks, readability, screenshots)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/casomoltd/tooling.git"
+  },
+  "files": [
+    "bin/",
+    "eslint/",
+    "prettier/",
+    "commitlint/",
+    "knip/",
+    "jscpd/",
+    "readability/",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "node bin/verify-pack.mjs && tsc --noEmit -p hooks/tsconfig.json && node hooks/test.mts && npm run lint:skills",
+    "lint:skills": "remark --frail --quiet --no-stdout --rc-path bin/skills-lint.config.mjs skills docs",
+    "build": "echo 'no-op: source-only repo (consumed as a git-dep), nothing to build'",
+    "prepare": "husky || true"
+  },
+  "exports": {
+    "./eslint": "./eslint/index.mjs",
+    "./eslint-lib": "./eslint/lib.mjs",
+    "./prettier": "./prettier/index.js",
+    "./commitlint": "./commitlint/index.cjs",
+    "./knip": "./knip/index.json",
+    "./jscpd": "./jscpd/index.json",
+    "./readability": "./readability/index.mjs"
+  },
+  "bin": {
+    "check-tags": "./bin/check-tags.sh",
+    "check-version": "./bin/check-version.sh",
+    "commit-msg": "./bin/commit-msg.sh",
+    "pre-commit": "./bin/pre-commit.sh",
+    "pre-push": "./bin/pre-push.sh",
+    "readability": "./bin/readability.mjs",
+    "screenshot": "./bin/screenshot.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "text-readability": "^1.1.1"
+  },
+  "peerDependencies": {
+    "@commitlint/cli": ">=20",
+    "eslint": ">=9",
+    "eslint-config-next": ">=16",
+    "eslint-plugin-sonarjs": ">=3",
+    "jscpd": ">=4",
+    "knip": ">=5",
+    "puppeteer": ">=24"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "husky": "^9.1.7",
+    "remark-cli": "^12.0.1",
+    "remark-frontmatter": "^5.0.0",
+    "remark-lint-frontmatter-schema": "^3.15.4",
+    "remark-validate-links": "^13.1.0",
+    "typescript": "^6.0.3"
+  }
+}

package/prettier/index.js

@@ -0,0 +1,7 @@
+module.exports = {
+  arrowParens: 'avoid',
+  bracketSameLine: true,
+  bracketSpacing: false,
+  singleQuote: true,
+  trailingComma: 'all',
+};

package/readability/index.mjs

@@ -0,0 +1,182 @@
+/**
+ * Readability scoring for Next.js page content.
+ *
+ * Extracts prose from JSX source files and computes scores
+ * against 7 readability formulas. Designed to be called from
+ * the CLI wrapper or programmatically.
+ */
+
+import rs from "text-readability";
+import fs from "node:fs";
+import path from "node:path";
+
+export const DEFAULT_MAX_GRADE = 12;
+
+export const DEFAULT_WORD_SUBS = {
+  calculators: "tools",
+  calculator: "tool",
+};
+
+// -------------------------------------------------------------------
+// Discover page slugs from an app-router directory
+// -------------------------------------------------------------------
+
+export function discoverSlugs(srcAppDir) {
+  const entries = fs.readdirSync(srcAppDir, {recursive: true});
+  return entries
+    .filter((e) => e.endsWith("page.tsx"))
+    .map((e) => {
+      const dir = path.dirname(e);
+      return dir === "." ? "/" : `/${dir}`;
+    })
+    .sort();
+}
+
+// -------------------------------------------------------------------
+// Extract prose text from a page.tsx source file
+// -------------------------------------------------------------------
+
+export function extractText(filePath) {
+  const source = fs.readFileSync(filePath, "utf-8");
+
+  const jsxText = [];
+  const tagContentRe = />([^<>{]+)</g;
+  let match;
+  while ((match = tagContentRe.exec(source)) !== null) {
+    const text = match[1].trim();
+    if (text) jsxText.push(text);
+  }
+
+  // String literals that look like readable prose
+  const stringRe = /['"`]([A-Z][^'"`]{20,})['"`]/g;
+  while ((match = stringRe.exec(source)) !== null) {
+    jsxText.push(match[1].trim());
+  }
+
+  // Terminate fragments so formulas count separate sentences
+  const SENT_END = /[.!?]$/;
+  const terminated = jsxText.map((t) =>
+    SENT_END.test(t) ? t : t + "."
+  );
+
+  let text = terminated.join(" ");
+  text = text.replace(/\{[^}]*\}/g, " ");
+  text = text.replace(/&nbsp;/g, " ");
+  text = text.replace(/&amp;/g, "&");
+  text = text.replace(/&lt;/g, "<");
+  text = text.replace(/&gt;/g, ">");
+  text = text.replace(/&[a-z]+;/g, " ");
+  text = text.replace(/\s+/g, " ").trim();
+
+  return text;
+}
+
+// -------------------------------------------------------------------
+// Compute readability scores
+// -------------------------------------------------------------------
+
+function round(n) {
+  return Math.round(n * 10) / 10;
+}
+
+function applyWordSubs(text, wordSubs) {
+  let out = text;
+  for (const [word, sub] of Object.entries(wordSubs)) {
+    out = out.replace(
+      new RegExp(`\\b${word}\\b`, "gi"),
+      sub,
+    );
+  }
+  return out;
+}
+
+export function scoreText(text, wordSubs = DEFAULT_WORD_SUBS) {
+  const wordCount = text.split(/\s+/).filter(Boolean).length;
+  if (wordCount < 100) {
+    return {wordCount, scores: null, consensusGrade: null};
+  }
+  const normalized = applyWordSubs(text, wordSubs);
+  const scores = {
+    fleschReadingEase: round(
+      rs.fleschReadingEase(normalized),
+    ),
+    fleschKincaidGrade: round(
+      rs.fleschKincaidGrade(normalized),
+    ),
+    gunningFog: round(rs.gunningFog(normalized)),
+    colemanLiau: round(rs.colemanLiauIndex(normalized)),
+    smog: round(rs.smogIndex(normalized)),
+    ari: round(
+      rs.automatedReadabilityIndex(normalized),
+    ),
+    daleChall: round(
+      rs.daleChallReadabilityScore(normalized),
+    ),
+  };
+  const gradeScores = [
+    scores.fleschKincaidGrade,
+    scores.gunningFog,
+    scores.colemanLiau,
+    scores.smog,
+    scores.ari,
+  ];
+  gradeScores.sort((a, b) => a - b);
+  const consensusGrade = round(
+    gradeScores[Math.floor(gradeScores.length / 2)],
+  );
+  return {wordCount, scores, consensusGrade};
+}
+
+// -------------------------------------------------------------------
+// Pretty-print a human-readable table
+// -------------------------------------------------------------------
+
+function pad(n) {
+  return n == null ? "N/A" : String(n).padStart(6);
+}
+
+export function formatPretty(results, threshold) {
+  const lines = [];
+  for (const r of results.pages) {
+    const status = r.pass ? "PASS" : "FAIL";
+    lines.push(`\n${status}  ${r.slug}`);
+    lines.push("─".repeat(44));
+    if (!r.scores) {
+      lines.push("  (too few words to score)");
+      continue;
+    }
+    lines.push(
+      `  Flesch Reading Ease   ${pad(r.scores.fleschReadingEase)}`,
+    );
+    lines.push(
+      `  Flesch-Kincaid Grade  ${pad(r.scores.fleschKincaidGrade)}`,
+    );
+    lines.push(
+      `  Gunning Fog           ${pad(r.scores.gunningFog)}`,
+    );
+    lines.push(
+      `  Coleman-Liau          ${pad(r.scores.colemanLiau)}`,
+    );
+    lines.push(
+      `  SMOG                  ${pad(r.scores.smog)}`,
+    );
+    lines.push(
+      `  ARI                   ${pad(r.scores.ari)}`,
+    );
+    lines.push(
+      `  Dale-Chall            ${pad(r.scores.daleChall)}`,
+    );
+    lines.push("─".repeat(44));
+    lines.push(
+      `  Consensus Grade Level ${pad(r.consensusGrade)}`,
+    );
+    lines.push(
+      `  Word Count            ${r.wordCount.toLocaleString()}`,
+    );
+  }
+  lines.push(
+    `\nThreshold: grade ${threshold.maxGrade} | ` +
+      `${results.allPassed ? "All passed" : "FAILURES DETECTED"}`,
+  );
+  return lines.join("\n");
+}