vanara 0.1.0 → 0.2.0

package/catalog/skills/caching-strategies/scripts/ttl-jitter.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Runnable helper: compute a jittered TTL so a batch of cache keys never expires
+// in lockstep (the synchronized-expiry stampede). Demonstrates an *executed*,
+// verifiable example asset.
+//
+// Usage:
+//   node ttl-jitter.mjs <baseSeconds> [jitterRatio]   # print one jittered TTL
+//   node ttl-jitter.mjs --selftest                    # run built-in test cases
+
+const MIN_TTL = 1;
+
+// Returns an integer TTL within [base*(1-ratio), base*(1+ratio)], floored at MIN_TTL.
+export function jitteredTtl(baseSeconds, jitterRatio = 0.1, rand = Math.random) {
+  if (!Number.isFinite(baseSeconds) || baseSeconds <= 0)
+    throw new RangeError('baseSeconds must be a positive number');
+  if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1)
+    throw new RangeError('jitterRatio must be in [0, 1]');
+  const delta = baseSeconds * jitterRatio;
+  const offset = (rand() * 2 - 1) * delta;            // uniform in [-delta, +delta]
+  return Math.max(MIN_TTL, Math.round(baseSeconds + offset));
+}
+
+// Inclusive bounds the result is guaranteed to fall within.
+export function jitterBounds(baseSeconds, jitterRatio = 0.1) {
+  const delta = baseSeconds * jitterRatio;
+  return {
+    min: Math.max(MIN_TTL, Math.round(baseSeconds - delta)),
+    max: Math.max(MIN_TTL, Math.round(baseSeconds + delta)),
+  };
+}
+
+function selftest() {
+  const cases = [];
+  const record = (name, pass, detail = '') => cases.push({ name, pass, detail });
+
+  // 1. Many samples stay within ±ratio bounds (fuzz with the real RNG).
+  {
+    const base = 300, ratio = 0.1;
+    const { min, max } = jitterBounds(base, ratio);
+    let allInBounds = true;
+    let sawSpread = new Set();
+    for (let i = 0; i < 10000; i++) {
+      const t = jitteredTtl(base, ratio);
+      if (t < min || t > max) { allInBounds = false; break; }
+      sawSpread.add(t);
+    }
+    record('stays within ±10% bounds over 10k samples', allInBounds, `[${min}, ${max}]`);
+    record('produces a spread of values (not constant)', sawSpread.size > 10,
+      `${sawSpread.size} distinct values`);
+  }
+
+  // 2. Extreme RNG values hit the exact bounds (deterministic injection).
+  {
+    const lo = jitteredTtl(300, 0.1, () => 0);   // rand=0 -> -delta
+    const hi = jitteredTtl(300, 0.1, () => 1);   // rand=1 -> +delta (1 is exclusive in Math.random, tested as edge)
+    record('rand=0 yields the low bound (270)', lo === 270, `got ${lo}`);
+    record('rand~1 yields the high bound (330)', hi === 330, `got ${hi}`);
+  }
+
+  // 3. Floor at MIN_TTL: tiny base with full jitter never drops below 1.
+  {
+    let neverBelowMin = true;
+    for (let i = 0; i < 1000; i++) {
+      if (jitteredTtl(1, 1.0) < MIN_TTL) { neverBelowMin = false; break; }
+    }
+    record('never returns below MIN_TTL', neverBelowMin, `MIN_TTL=${MIN_TTL}`);
+  }
+
+  // 4. Zero jitter is a pure passthrough.
+  record('jitterRatio=0 returns base unchanged', jitteredTtl(300, 0) === 300,
+    `got ${jitteredTtl(300, 0)}`);
+
+  // 5. Invalid inputs throw.
+  const throws = (fn) => { try { fn(); return false; } catch { return true; } };
+  record('rejects non-positive base', throws(() => jitteredTtl(0)));
+  record('rejects out-of-range ratio', throws(() => jitteredTtl(300, 2)));
+
+  let allPass = true;
+  for (const { name, pass, detail } of cases) {
+    if (!pass) allPass = false;
+    console.log(`${pass ? '✓' : '✗'} ${name}${detail ? `  (${detail})` : ''}`);
+  }
+  console.log(allPass ? '\nAll selftests passed.' : '\nSelftests FAILED.');
+  process.exit(allPass ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') {
+  selftest();
+} else if (arg) {
+  const base = Number(arg);
+  const ratio = process.argv[3] !== undefined ? Number(process.argv[3]) : 0.1;
+  const { min, max } = jitterBounds(base, ratio);
+  console.log(`jitteredTtl(${base}, ${ratio}) = ${jitteredTtl(base, ratio)}  (range [${min}, ${max}])`);
+} else {
+  console.log('Usage: node ttl-jitter.mjs <baseSeconds> [jitterRatio]');
+  console.log('       node ttl-jitter.mjs --selftest');
+  process.exit(2);
+}

package/catalog/skills/conventional-commits/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: conventional-commits
+description: Write Conventional Commits — the type(scope)!: subject + body + footer spec — so history is readable and changelogs and SemVer bumps can be derived automatically. Use when committing, configuring commitlint, designing release tooling, or deciding feat vs fix vs breaking change.
+type: skill
+version: 2.0.0
+updated: 2026-06-29
+---
+# Conventional Commits
+
+A commit message is the only documentation guaranteed to travel with a change forever. Conventional
+Commits turn that prose into a **structured, machine-parseable record**: a tool can read your history and
+derive the next version number and a categorized changelog without a human touching either. This skill is
+the deep reference for the spec, the trade-offs, and the failure modes. Heavy detail lives in
+`references/`; copy-paste config in `examples/`; a runnable linter in `scripts/`.
+
+## Mental model
+
+Every commit answers three questions, and the format maps one-to-one onto them:
+
+| Question | Where it lives |
+|---|---|
+| What kind of change? | the **type** (`feat`, `fix`, …) |
+| Where, narrowly? | the optional **scope** (`feat(auth):`) |
+| Does it break callers? | the `!` marker and/or `BREAKING CHANGE:` footer |
+| Why, in prose? | the **body** |
+| What does it reference/close? | the **footer** (`Refs:`, `Closes:`) |
+
+The header is for machines and scanners; the body is for the next human. Get the header structurally
+correct and your release tooling does the rest for free.
+
+## The spec
+
+```
+<type>(<optional scope>)<optional !>: <subject>
+<blank line>
+<optional body — wrapped prose explaining the why, may span paragraphs>
+<blank line>
+<optional footer(s) — BREAKING CHANGE: …, Refs: #123, Closes: #456, Co-Authored-By: …>
+```
+
+Rules that the linter enforces (see `scripts/lint-commit.mjs`):
+
+1. **Type** is required, lowercase, from the allowed set below.
+2. **Scope** is optional, in parentheses, a lowercase noun for the affected area (`api`, `auth`, `deps`).
+3. **`!`** before the colon flags a breaking change.
+4. **Subject** follows `: ` (colon-space), is imperative mood, lowercase, no trailing period, and the
+   whole header is **≤ 72 characters** (50 is the ideal — it keeps `git log --oneline` and GitHub from
+   truncating).
+
+The full grammar, footer tokens, and revert/merge conventions are in `references/spec.md`.
+
+## Allowed types
+
+| Type | Use for | SemVer impact |
+|---|---|---|
+| `feat` | a new user-facing feature | **MINOR** |
+| `fix` | a bug fix | **PATCH** |
+| `docs` | documentation only | none |
+| `style` | formatting, whitespace, no code change | none |
+| `refactor` | code change that neither fixes a bug nor adds a feature | none |
+| `perf` | a performance improvement | PATCH |
+| `test` | adding or correcting tests | none |
+| `build` | build system or dependencies | none |
+| `ci` | CI configuration and scripts | none |
+| `chore` | maintenance, no production code change | none |
+| `revert` | reverts a previous commit | varies |
+
+Any commit with a `!` or `BREAKING CHANGE:` footer is a **MAJOR** bump, regardless of type. Keep the set
+small and team-agreed — inventing per-developer types defeats the automation. See
+`references/breaking-changes-semver.md` for the precise type → version mapping.
+
+## Why bother (the automation payoff)
+
+The structure is not bureaucracy — it unlocks tooling you'd otherwise hand-maintain:
+
+- **Automated versioning:** `semantic-release` / Changesets read the commits since the last tag and pick
+  MAJOR / MINOR / PATCH from the types. No more "what should this version be?" debates.
+- **Generated changelogs:** commits group by type into a categorized `CHANGELOG.md` with links to PRs and
+  issues, written from the footers.
+- **Scannable history:** filtering by type answers "what features shipped this quarter?" in one command:
+
+```bash
+git log --oneline --grep '^feat' v1.4.0..HEAD   # every feature since the last release
+git log --oneline --grep 'BREAKING CHANGE'      # every breaking change, ever
+```
+
+- **Reviewable diffs:** one logical change per commit means reviewers and `git bisect` operate on
+  coherent units instead of tangled mega-commits.
+
+## Scoping commits (one logical change)
+
+A perfect message on a tangled commit is still a bad commit. Each commit should be **one coherent change**
+that builds and passes tests on its own — don't mix a refactor with a feature, or a fix with a formatting
+sweep. This makes `git revert`, `git bisect`, and cherry-picks surgical instead of all-or-nothing. The
+discipline of staging hunks (`git add -p`) to separate concerns is covered in `references/scoping-commits.md`.
+
+## Common pitfalls and failure modes
+
+- **Past tense / capitalized subject** (`Added login`) — the convention is imperative, lowercase: `add
+  login`. A useful test: the subject should complete the sentence "If applied, this commit will ___".
+- **A scope that's really a type** (`feat(fix):`) — scope is a *place* (`auth`), not a kind of change.
+- **Forgotten breaking-change marker** — renaming a public field as a plain `refactor:` ships a MAJOR
+  break as a no-bump release and silently breaks downstream consumers. Always add `!` + a `BREAKING
+  CHANGE:` footer explaining the migration.
+- **Junk-drawer `chore:`** — using `chore` for everything erases the signal. A dependency bump that fixes
+  a CVE is a `fix`; a new capability is a `feat`.
+- **Header over 72 chars** — it truncates in `git log --oneline`, GitHub, and changelog output. Move
+  detail into the body.
+- **Mega-commits** ("WIP", "fixes") — unparseable by tooling and impossible to revert cleanly.
+- **Enforcing only on the final squash** — if you squash-merge, the *PR title* becomes the commit; lint
+  that, not just local commits, or the rule has no teeth.
+
+## When NOT to use / trade-offs
+
+- **Solo throwaway prototypes** — the changelog/versioning payoff is zero; the ceremony is pure overhead.
+- **Squash-merge-only teams** — per-commit discipline matters less; instead enforce the convention on PR
+  titles via a CI check and let local commits be messy.
+- **Non-software repos** (docs sites, infra-as-data) — the type vocabulary often doesn't fit; a lighter
+  convention may serve better.
+- **The cost:** it adds friction and requires a `commitlint` gate plus team buy-in to stay consistent.
+  Half-adopted, it's worse than nothing because the automation can't trust the data. Adopt it fully (with
+  the `commit-msg` hook in `examples/commitlint.config.js`) or not at all.
+
+## Files in this package
+
+- `references/spec.md` — full grammar: header, body, footers, revert/merge, FAQ
+- `references/breaking-changes-semver.md` — `!` vs `BREAKING CHANGE:` and exact type → SemVer mapping
+- `references/scoping-commits.md` — splitting work into atomic commits with `git add -p`
+- `examples/commit-examples.md` — annotated good and bad messages across every type
+- `examples/commitlint.config.js` — zero-config-friendly commitlint setup + husky `commit-msg` hook
+- `scripts/lint-commit.mjs` — runnable Node linter for a commit header, with `--selftest`
+
+Pairs with the `ci-pipeline-design` skill (gate commits in CI), the `changelog-writing` skill (turn the
+history into release notes), and the `code-reviewer` agent. See the
+[Conventional Commits spec](https://www.conventionalcommits.org/) for the canonical wording.

package/catalog/skills/conventional-commits/examples/commit-examples.md

@@ -0,0 +1,60 @@
+# Annotated Commit Examples
+
+Copy these shapes. Each shows the header, and where useful, body and footers.
+
+## Good
+
+A feature with context and an issue reference:
+
+```
+feat(orders): add cursor pagination to the list endpoint
+
+Offset pagination scanned the whole table on deep pages and double-counted
+rows under concurrent inserts. Cursor pagination keeps queries O(limit)
+regardless of depth.
+
+Refs: #214
+```
+
+A plain bug fix (PATCH):
+
+```
+fix(auth): treat an expired token as 401, not 500
+```
+
+A breaking change — `!` plus a migration footer (MAJOR):
+
+```
+refactor(api)!: drop the deprecated v0 auth header
+
+BREAKING CHANGE: clients must send `Authorization: Bearer <token>`.
+The `X-Api-Key` header is no longer read.
+```
+
+A performance fix (PATCH) and a docs-only change (no release):
+
+```
+perf(search): memoize the analyzer to cut p99 by 40ms
+```
+```
+docs: document the cursor pagination contract
+```
+
+A scoped dependency bump that closes a security issue — note it's a `fix`, not `chore`:
+
+```
+fix(deps): bump qs to 6.11.2 to patch CVE-2022-24999
+
+Closes: #301
+```
+
+## Bad — and the fix
+
+| Bad | Why | Fixed |
+|---|---|---|
+| `Added user login` | past tense, capitalized | `feat(auth): add user login` |
+| `fix: Fixed the bug.` | capital + trailing period + vague | `fix(cart): reject negative quantities` |
+| `feat(fix): patch thing` | scope is a type, not a place | `fix(thing): handle empty payload` |
+| `chore: rewrite payment retries` | hides a real fix as no-release noise | `fix(payments): retry idempotently on timeout` |
+| `update stuff and refactor and fix tests` | three changes, no type | three separate commits |
+| `feat: implement the entire new dashboard with charts, filters, export, and dark mode toggle` | 80+ char header | shorten subject, push detail to body |

package/catalog/skills/conventional-commits/examples/commitlint.config.js

@@ -0,0 +1,31 @@
+// commitlint configuration enforcing Conventional Commits.
+//
+// Setup (install dev deps in your own project — this skill ships zero deps):
+//   npm i -D @commitlint/cli @commitlint/config-conventional husky
+//   npx husky init
+//   echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg
+//
+// With the commit-msg hook in place, every `git commit` is validated locally.
+// In CI, also lint PR titles for squash-merge workflows (see ci-pipeline-design).
+
+/** @type {import('@commitlint/types').UserConfig} */
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    // Restrict types to the agreed set (mirrors this skill's "Allowed types").
+    'type-enum': [
+      2,
+      'always',
+      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'],
+    ],
+    // Scope is optional, but when present must be one of these known areas.
+    // Drop this rule, or extend the list, to match your repo's modules.
+    'scope-enum': [2, 'always', ['api', 'web', 'auth', 'orders', 'payments', 'deps', 'ci', 'release']],
+    'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
+    'subject-empty': [2, 'never'],
+    'subject-full-stop': [2, 'never', '.'],
+    'header-max-length': [2, 'always', 72],
+    'body-leading-blank': [2, 'always'],
+    'footer-leading-blank': [2, 'always'],
+  },
+};

package/catalog/skills/conventional-commits/references/breaking-changes-semver.md

@@ -0,0 +1,50 @@
+# Breaking Changes and SemVer Mapping
+
+Conventional Commits exists to make [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`)
+automatic. This is the exact mapping release tools use.
+
+## Type → version bump
+
+| Commit | Bump | Example: from `1.4.2` |
+|---|---|---|
+| any commit with `!` or `BREAKING CHANGE:` footer | **MAJOR** | → `2.0.0` |
+| `feat:` | **MINOR** | → `1.5.0` |
+| `fix:` | **PATCH** | → `1.4.3` |
+| `perf:` | PATCH | → `1.4.3` |
+| `docs:` / `style:` / `refactor:` / `test:` / `build:` / `ci:` / `chore:` | no release | `1.4.2` |
+
+The highest-priority change across all commits since the last tag wins: one `feat` among twenty `chore`s
+still produces a MINOR release; one breaking change produces a MAJOR.
+
+## Two ways to mark a break
+
+Both are valid; you can use either or both. The `!` is the scannable signal; the footer carries the
+migration note. **Prefer using both** so humans get the explanation:
+
+```
+feat(api)!: require Bearer tokens on all endpoints
+
+BREAKING CHANGE: the legacy `X-Api-Key` header is no longer accepted.
+Migrate by exchanging your key for a token at POST /v1/auth/token.
+```
+
+A breaking change can ride on **any** type — `fix!:` is a bug fix that also breaks the contract.
+
+## Pre-1.0.0 caveat
+
+SemVer treats `0.y.z` as unstable: anything may break at any time. Many tools therefore map a breaking
+change to a **MINOR** bump (`0.4.0 → 0.5.0`) rather than `1.0.0` until you explicitly cut `1.0.0`.
+Configure this deliberately — accidentally shipping `1.0.0` signals an API-stability promise you may not
+be ready to make.
+
+## What actually counts as "breaking"
+
+Breaking = an existing consumer following the documented contract would now fail. Examples:
+
+- Removing or renaming a public field, endpoint, function, or CLI flag.
+- Changing a default value, response shape, or error code clients branch on.
+- Tightening validation so previously-accepted input is now rejected.
+- Raising a minimum runtime/engine version.
+
+Adding an *optional* field, a new endpoint, or a new enum value is **additive** (MINOR), not breaking —
+provided clients are built to ignore unknown fields.

package/catalog/skills/conventional-commits/references/scoping-commits.md

@@ -0,0 +1,42 @@
+# Scoping Commits — One Logical Change
+
+A flawless message on a tangled commit is still a bad commit. The hardest part of good history isn't
+wording — it's deciding **what belongs in one commit**.
+
+## The atomic-commit rule
+
+Each commit should be a single coherent change that **builds and passes tests on its own**. If you can't
+describe it in one Conventional Commit subject without using "and", it's probably two commits.
+
+Good signs:
+- `git revert <sha>` would cleanly back out exactly one concern.
+- `git bisect` landing on this commit points at a single suspect.
+- A reviewer can hold the whole change in their head.
+
+## Splitting a messy working tree
+
+When you've already written tangled changes, stage them by concern instead of `git add .`:
+
+```bash
+git add -p              # interactively stage hunks — accept only the fix's hunks
+git commit -m "fix: reject negative quantity in cart total"
+git add -p              # now stage the refactor hunks
+git commit -m "refactor: extract priceFor() from CartTotal"
+```
+
+`git add -p` walks each hunk and asks y/n/s (split). It's the single most useful habit for clean history.
+For changes that can't be hunk-split (intertwined lines), use `git stash` to park one concern while you
+commit the other, or `git restore --staged -p` to unstage.
+
+## Anti-patterns
+
+- **"WIP" / "fixes" / "stuff"** — unparseable, unreviewable. Squash or reword before merge.
+- **The end-of-day mega-commit** — a day's unrelated work in one blob. Commit as you finish each unit.
+- **Mixing formatting with logic** — a Prettier sweep buried in a feature hides the real change in noise.
+  Do formatting in its own `style:` commit.
+
+## Rewriting before you push
+
+History is cheap to fix *before* it's shared. Use `git rebase -i` to squash fixups, reorder, and reword
+local commits into a clean series. Once pushed to a shared branch, leave it alone (or coordinate) — never
+rewrite published history others have built on.

package/catalog/skills/conventional-commits/references/spec.md

@@ -0,0 +1,78 @@
+# The Conventional Commits Grammar
+
+The canonical spec is [conventionalcommits.org](https://www.conventionalcommits.org/). This is a working
+summary with the parts teams trip over.
+
+## Structure
+
+```
+<type>[(<scope>)][!]: <subject>
+
+[body]
+
+[footer(s)]
+```
+
+- Exactly one blank line separates header, body, and footers.
+- The header is a single line. Everything machine-read lives here.
+
+## Header
+
+| Part | Required | Rules |
+|---|---|---|
+| type | yes | lowercase; from the agreed set |
+| scope | no | `(noun)`; lowercase; the affected area |
+| `!` | no | breaking-change flag, placed right before `:` |
+| `: ` | yes | colon then a single space |
+| subject | yes | imperative, lowercase start, no trailing `.`, header ≤ 72 chars |
+
+The "imperative mood" test: the subject should complete *"If applied, this commit will ___"*. So write
+`fix: handle null cursor`, not `fixed null cursor` or `fixes null cursor`.
+
+## Body
+
+- Free-form, wrapped at ~72 columns.
+- Explain **why** the change exists and any context the diff can't show. Do not restate the diff.
+- May contain multiple paragraphs and bullet lists.
+
+## Footers
+
+Footers follow the [git trailer](https://git-scm.com/docs/git-interpret-trailers) format —
+`Token: value`, one per line, after a blank line:
+
+```
+BREAKING CHANGE: the `token` field was renamed to `accessToken`.
+Refs: #214
+Closes: #220
+Reviewed-by: Jordan Lee
+Co-Authored-By: A. Dev <a.dev@example.com>
+```
+
+- `BREAKING CHANGE:` (uppercase, with a space) is special: its presence forces a MAJOR bump. `BREAKING-CHANGE:`
+  (hyphen) is accepted as a synonym by parsers.
+- Issue references (`Closes #220`) let platforms auto-close issues on merge.
+
+## Reverts
+
+```
+revert: let us never speak of the night deploy again
+
+This reverts commit 676104e.
+```
+
+The footer `This reverts commit <sha>.` is what `git revert` generates and what tooling looks for.
+
+## Merge commits
+
+Merge commits are typically excluded from changelog generation (they have no single type). Squash-merge
+workflows collapse a branch into one commit — make sure the **squash subject** is itself a valid
+Conventional Commit, because that is the message that lands on the main branch.
+
+## FAQ
+
+- **Multiple types in one change?** Split the commit. One logical change → one type.
+- **Where do `scope`s come from?** Define a fixed list per repo (e.g. `api`, `web`, `auth`, `deps`) and
+  enforce it via `scope-enum` in commitlint so they stay consistent.
+- **Capital or lowercase subject?** Lowercase by convention; some teams allow sentence case — pick one and
+  lint it.
+- **Emoji (gitmoji)?** A different convention. Don't mix it with Conventional Commits or parsers choke.

package/catalog/skills/conventional-commits/scripts/lint-commit.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// Runnable check: validates a Conventional Commit *header* against the spec from
+// this skill — type, optional scope, optional `!`, colon-space, and a subject
+// within a 72-char total header. Zero dependencies, Node built-ins only.
+//
+// Usage:
+//   node lint-commit.mjs "feat(api): add pagination"   # check a literal header
+//   echo "fix: handle null" | node lint-commit.mjs      # check from stdin
+//   node lint-commit.mjs --selftest                     # run built-in test cases
+
+const ALLOWED_TYPES = [
+  'feat', 'fix', 'docs', 'style', 'refactor',
+  'perf', 'test', 'build', 'ci', 'chore', 'revert',
+];
+const MAX_HEADER = 72;
+
+// type(scope)!: subject  — scope and ! are optional; capture each part.
+const HEADER_RE = /^(?<type>[a-z]+)(?:\((?<scope>[^()\s]+)\))?(?<bang>!)?: (?<subject>.+)$/;
+
+export function lintHeader(header) {
+  const failures = [];
+  if (typeof header !== 'string' || header.length === 0) {
+    return { ok: false, failures: ['header is empty'] };
+  }
+  if (header.length > MAX_HEADER) {
+    failures.push(`header is ${header.length} chars (max ${MAX_HEADER})`);
+  }
+  const m = header.match(HEADER_RE);
+  if (!m) {
+    failures.push('does not match "type(scope)!: subject" (need a lowercase type and ": " separator)');
+    return { ok: false, failures };
+  }
+  const { type, scope, subject } = m.groups;
+  if (!ALLOWED_TYPES.includes(type)) {
+    failures.push(`type "${type}" is not allowed (use one of: ${ALLOWED_TYPES.join(', ')})`);
+  }
+  if (scope !== undefined && scope !== scope.toLowerCase()) {
+    failures.push(`scope "${scope}" must be lowercase`);
+  }
+  if (subject.trim().length === 0) {
+    failures.push('subject is empty');
+  }
+  if (/^[A-Z]/.test(subject)) {
+    failures.push('subject should start lowercase (imperative mood)');
+  }
+  if (/\.$/.test(subject)) {
+    failures.push('subject must not end with a period');
+  }
+  return { ok: failures.length === 0, failures };
+}
+
+function check(label, header) {
+  const trimmed = String(header).split('\n')[0].trimEnd();
+  const { ok, failures } = lintHeader(trimmed);
+  if (ok) console.log(`✓ ${label}: valid commit header`);
+  else {
+    console.error(`✗ ${label}: "${trimmed}"`);
+    failures.forEach((f) => console.error(`    - ${f}`));
+  }
+  return ok;
+}
+
+function selftest() {
+  const cases = {
+    'valid feat':          'feat: add cursor pagination',
+    'valid scope':         'feat(orders): add cursor pagination',
+    'valid breaking':      'refactor(api)!: drop v0 auth header',
+    'valid fix':           'fix(auth): treat expired token as 401',
+    'invalid type':        'feature: add thing',
+    'invalid capitalized': 'feat: Add thing',
+    'invalid period':      'fix: handle null cursor.',
+    'invalid no-colon':    'feat add thing',
+    'invalid too-long':    'feat: ' + 'x'.repeat(80),
+    'invalid upper scope': 'feat(API): add thing',
+  };
+  let allExpected = true;
+  for (const [name, header] of Object.entries(cases)) {
+    const { ok } = lintHeader(header);
+    const shouldPass = name.startsWith('valid');
+    const correct = ok === shouldPass;
+    allExpected &&= correct;
+    console.log(
+      `${correct ? '✓' : '✗'} selftest ${name}: ` +
+      `${ok ? 'valid' : 'invalid'} (expected ${shouldPass ? 'valid' : 'invalid'})`
+    );
+  }
+  process.exit(allExpected ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(check('header', arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(check('stdin', buf) ? 0 : 1));
+}