@rtorcato/repo-tooling 3.8.7 → 3.9.0

package/README.md

@@ -1,6 +1,6 @@
 <picture>
-  <source media="(max-width: 640px)" srcset="./banner-mobile.png">
-  <img src="./banner.png" alt="repo-tooling banner" width="1600">
+  <source media="(max-width: 640px)" srcset="./brand/banner-mobile.png">
+  <img src="./brand/banner.png" alt="repo-tooling banner" width="1600">
 </picture>
 
 <br>

package/dist/base/checks.js

@@ -99,6 +99,58 @@ export async function checkCommunityHealth(dir) {
         hint: 'Run `npx @rtorcato/repo-tooling fix community-health` to scaffold them',
     };
 }
+const BRAND_HINT = 'Run `npx @rtorcato/repo-tooling fix brand` to scaffold brand/ (SVG sources + render.sh), then run `brand/render.sh`';
+/** The two banners the README consumes — the pair `brand/` exists to keep regenerable. */
+const BANNERS = ['banner', 'banner-mobile'];
+/**
+ * Brand assets (#395). A committed PNG with no SVG beside it can't be
+ * recoloured, retitled or resized — which was the state of every repo in the
+ * family but one. Three signals, all language-agnostic:
+ *
+ * 1. a rendered banner with no `brand/<name>.svg` source
+ * 2. a `brand/` folder with no `render.sh` — sources nobody can render
+ * 3. a README still pointing at the pre-amendment root-level `./banner.png`
+ *
+ * A repo with no brand images at all is `optional-missing`, not a finding:
+ * there's nothing broken to fix, and banners are opt-in.
+ */
+export async function checkBrand(dir) {
+    const check = 'Brand assets';
+    const has = (rel) => fs.pathExists(path.join(dir, rel));
+    const problems = [];
+    const orphans = [];
+    for (const name of BANNERS) {
+        const rendered = (await has(`${name}.png`)) || (await has(`brand/${name}.png`));
+        if (rendered && !(await has(`brand/${name}.svg`)))
+            orphans.push(`${name}.png`);
+    }
+    if (orphans.length > 0) {
+        problems.push(`${orphans.join(' + ')} committed with no brand/*.svg source`);
+    }
+    const brandDir = await has('brand');
+    if (brandDir && !(await has('brand/render.sh'))) {
+        problems.push('brand/ has no render.sh — the PNGs cannot be regenerated');
+    }
+    const readmePath = path.join(dir, 'README.md');
+    if (await fs.pathExists(readmePath)) {
+        const readme = await fs.readFile(readmePath, 'utf-8');
+        if (/(?<!brand\/)banner(?:-mobile)?\.png/.test(readme)) {
+            problems.push('README points at root-level banner PNGs (the spec moved them to brand/)');
+        }
+    }
+    if (problems.length > 0) {
+        return { check, status: 'drift', detail: problems.join('; '), hint: BRAND_HINT };
+    }
+    if (!brandDir) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: 'no brand/ folder — the repo ships no regenerable brand sources',
+            hint: BRAND_HINT,
+        };
+    }
+    return { check, status: 'ok', detail: 'brand/ holds the SVG sources and render.sh' };
+}
 /**
  * `org/action@vN`, the only form the generators emit. Same shape as the scan in
  * tests/cli/generators/action-pins.test.ts — major-only, because that's the

package/dist/base/fixers.js

@@ -13,6 +13,7 @@
  */
 import chalk from 'chalk';
 import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
+import { generateBrand } from '../cli/generators/brand.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
 import { generateCodeowners, generateEditorConfig } from '../cli/generators/misc.js';
@@ -21,6 +22,7 @@ import { copyPreset } from '../cli/utils/copy-preset.js';
 import { detectLanguage } from '../cli/utils/detect-language.js';
 import { resolveLanguageModule } from '../languages/registry.js';
 import { applyGithubSettings } from './github-settings.js';
+import { closeCompletedMilestones } from './milestones.js';
 /** The repo's language module, resolved from its marker files. */
 async function moduleFor(targetDir) {
     return resolveLanguageModule(await detectLanguage(targetDir));
@@ -114,6 +116,19 @@ export const BASE_FIXERS = [
             return { filesWritten: await applyGithubSettings(targetDir) };
         },
     },
+    {
+        target: 'milestones',
+        description: 'Close 100%-complete open milestones on GitHub via gh api (mutates the remote repo, not files). Never deletes or creates one',
+        appliesTo: ['Milestones'],
+        outputs: ['GitHub milestones (remote, via gh api)'],
+        // safe-add for the same reason github-settings is: it exempts this fixer
+        // from the `--diff` shadow-run, which executes run() for a mere preview.
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            return { filesWritten: await closeCompletedMilestones(targetDir) };
+        },
+    },
     {
         target: 'codeowners',
         description: 'Scaffold .github/CODEOWNERS with commented examples',
@@ -144,10 +159,33 @@ export const BASE_FIXERS = [
             return { filesWritten };
         },
     },
+    {
+        target: 'brand',
+        description: 'Scaffold brand/ — banner, mobile-banner and social-card SVG sources + render.sh, and repoint a README still on root-level banner paths',
+        appliesTo: ['Brand assets'],
+        outputs: [
+            'brand/banner.svg',
+            'brand/banner-mobile.svg',
+            'brand/social-card.svg',
+            'brand/render.sh',
+            'README.md',
+        ],
+        // Every SVG is written only when absent and the README edit rewrites two
+        // image paths — hand-edited art is never clobbered.
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            const filesWritten = await generateBrand(pkg, targetDir);
+            if (filesWritten.some((f) => f.endsWith('.svg'))) {
+                console.error(chalk.dim('   next: run `brand/render.sh` to render the PNGs (needs librsvg — `brew install librsvg`)'));
+            }
+            return { filesWritten };
+        },
+    },
     {
         target: 'ai',
         description: 'Install all AI agent files at once (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill, MCP example)',
-        appliesTo: ['AI setup'],
+        appliesTo: ['AI setup', 'Claude worktree settings'],
         outputs: [
             'AGENTS.md',
             'CLAUDE.md',
@@ -155,6 +193,8 @@ export const BASE_FIXERS = [
             '.github/copilot-instructions.md',
             '.claude/skills/repo-tooling.md',
             '.mcp.json.example',
+            // Only written for a repo with a package.json — nothing to symlink otherwise.
+            '.claude/settings.json',
             // Only written when the repo ships its own skills/<name>/SKILL.md.
             'README.md',
         ],

package/dist/base/milestones.js

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import { realGhExec } from './github-settings.js';
+/**
+ * Milestone hygiene (#397). `doctor` already audits GitHub-side state, and an
+ * open milestone at 100% is the same class of drift: "open" stops meaning "in
+ * flight", so the milestone list carries no signal.
+ *
+ * Read-only, on the same `gh` seam as github-settings.ts. No repo probe is
+ * needed — `gh` expands `{owner}/{repo}` from the remote itself.
+ */
+const CHECK = 'Milestones';
+/**
+ * A milestone with no completion criterion can never close, so it is
+ * structurally a label. Warned about, never fixed — the call is the
+ * maintainer's.
+ */
+const CATCH_ALL_TITLE = /backlog|post-\d|someday/i;
+const skip = (reason) => ({
+    check: CHECK,
+    status: 'ok',
+    detail: `skipped — ${reason}`,
+});
+const titles = (ms) => ms.map((m) => `"${m.title}"`).join(', ');
+async function readMilestones(gh) {
+    // `-X GET` is load-bearing: `-f`/`-F` without an explicit method make `gh`
+    // switch to POST, which would hit the *create* milestone endpoint. With it,
+    // the fields land in the query string and the path keeps gh's
+    // {owner}/{repo} placeholders intact.
+    const r = await gh([
+        'api',
+        '-X',
+        'GET',
+        'repos/{owner}/{repo}/milestones',
+        '-f',
+        'state=all',
+        '-F',
+        'per_page=100',
+    ]);
+    if (!r.ok)
+        return null;
+    try {
+        const parsed = JSON.parse(r.stdout);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function classify(milestones) {
+    const open = milestones.filter((m) => m.state === 'open');
+    return {
+        // The number guard is the injection boundary: it is interpolated into the
+        // PATCH path by the fixer below.
+        complete: open.filter((m) => m.open_issues === 0 && m.closed_issues > 0 && Number.isInteger(m.number)),
+        // GitHub renders the bar as closed/total, so an empty milestone is a
+        // permanent 0% that can never move.
+        empty: open.filter((m) => m.open_issues === 0 && m.closed_issues === 0),
+        catchAll: open.filter((m) => CATCH_ALL_TITLE.test(m.title)),
+    };
+}
+/**
+ * The catch-all warning rides in `detail` rather than being its own finding:
+ * `fix` deliberately can't resolve it (converting a milestone to a label is a
+ * planning decision), and a permanently-unfixable drift row would nag forever.
+ */
+const catchAllNote = (catchAll) => catchAll.length === 0
+    ? ''
+    : ` — note: ${titles(catchAll)} has no completion criterion so it can never close; that is a label, not a milestone`;
+export async function checkMilestones(dir, exec) {
+    // Cheap gate first: no .git → never spawn (keeps tmp-dir doctor runs offline).
+    if (!(await fs.pathExists(path.join(dir, '.git'))))
+        return skip('not a git repository');
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const milestones = await readMilestones(gh);
+    if (!milestones)
+        return skip('could not read milestones');
+    // Using no milestones at all is a legitimate choice, not drift.
+    if (milestones.length === 0)
+        return skip('repo uses no milestones');
+    const { complete, empty, catchAll } = classify(milestones);
+    const deltas = [];
+    if (complete.length)
+        deltas.push(`100% complete but still open: ${titles(complete)}`);
+    if (empty.length)
+        deltas.push(`no issues, so a permanent 0%: ${titles(empty)}`);
+    const note = catchAllNote(catchAll);
+    if (deltas.length)
+        return {
+            check: CHECK,
+            status: 'drift',
+            detail: deltas.join('; ') + note,
+            hint: 'Run `npx @rtorcato/repo-tooling fix milestones` to close the 100%-complete ones. Empty milestones are left alone — file their issues or delete them by hand',
+        };
+    return {
+        check: CHECK,
+        status: 'ok',
+        detail: `${milestones.length} milestone(s); none complete-but-open or empty${note}`,
+    };
+}
+/**
+ * Closes every open milestone that is 100% complete. Deliberately the only
+ * mutation: deleting an empty milestone or creating a missing one would destroy
+ * or invent planning intent. Idempotent — a clean repo is a no-op.
+ *
+ * Advisories go to `console.error`; stdout carries the `--json` payload (#357).
+ */
+export async function closeCompletedMilestones(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        console.error(chalk.gray('   skipped — not a git repository'));
+        return [];
+    }
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const milestones = await readMilestones(gh);
+    if (!milestones) {
+        console.error(chalk.gray('   skipped — could not read milestones'));
+        return [];
+    }
+    const { complete, empty } = classify(milestones);
+    const closed = [];
+    for (const m of complete) {
+        const r = await gh([
+            'api',
+            '-X',
+            'PATCH',
+            `repos/{owner}/{repo}/milestones/${m.number}`,
+            '-f',
+            'state=closed',
+        ]);
+        if (r.ok)
+            closed.push(`closed milestone "${m.title}"`);
+        else
+            console.error(chalk.yellow(`   could not close "${m.title}": ${r.stderr.trim() || 'gh error'}`));
+    }
+    if (empty.length)
+        console.error(chalk.gray(`   left ${empty.length} empty milestone(s) alone — file their issues or delete them by hand`));
+    if (closed.length === 0)
+        console.error(chalk.gray('   no 100%-complete open milestones to close'));
+    return closed;
+}

package/dist/cli/commands/doctor.js

@@ -13,11 +13,12 @@ import { SWIFT_GIT_HOOKS, runSwiftChecks } from '../../languages/swift/checks.js
 import { readSwiftPackage, renderSwiftWorkflow } from '../../languages/swift/ci.js';
 import { detectLanguage } from '../utils/detect-language.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
+import { checkMilestones } from '../../base/milestones.js';
 import { checkGitIdentity } from '../../base/git-identity.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
-import { checkAiSetup, checkCodeowners, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
-import { allDeps, checkAreTheTypesWrong, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
+import { checkAiSetup, checkBrand, checkCodeowners, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
+import { allDeps, checkAreTheTypesWrong, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
 export { evaluateNodeVersion };
 const PACKAGE = '@rtorcato/repo-tooling';
 // Detects the broken-release-on-protected-main footgun: a workflow that runs
@@ -163,9 +164,12 @@ async function runBaseChecks(dir, lock, opts) {
     // GitHub repo-settings drift (branch protection, merge settings, workflow
     // permissions). Read-only; self-skips as `ok` outside a live GitHub repo.
     results.push(...(await checkGitHubSettings(dir)));
+    // Milestone hygiene (#397) — same seam, same self-skip.
+    results.push(await checkMilestones(dir));
     results.push(await checkGitLabCI(dir));
     results.push(await checkCodeowners(dir));
     results.push(await checkCommunityHealth(dir));
+    results.push(await checkBrand(dir));
     results.push(await checkAiSetup(dir));
     results.push(await checkReadmeBadges(dir, opts.badges.audience, opts.badges.fixTarget));
     results.push(await checkCoverageUpload(dir));
@@ -304,6 +308,7 @@ export async function runDoctor(dir) {
     results.push(await checkTreeshakeSetup(targetDir, pkg));
     results.push(await checkPnpmWorkspace(targetDir, pkg));
     results.push(await checkBuildApprovals(targetDir, pkg));
+    results.push(await checkClaudeWorktreeSettings(targetDir));
     // Turborepo is monorepo-only — only surface the check when a workspace exists.
     if (await fs.pathExists(path.join(targetDir, 'pnpm-workspace.yaml'))) {
         results.push(await checkTurborepo(targetDir));

package/dist/cli/commands/fix-targets.js

@@ -28,6 +28,7 @@ export const FIX_TARGETS = {
     'Merge settings': 'github-settings',
     'Workflow permissions': 'github-settings',
     'Code-scanning gate': 'github-settings',
+    Milestones: 'milestones',
     CODEOWNERS: 'codeowners',
     'GitLab CI': 'gitlab-ci',
     Turborepo: 'turborepo',
@@ -41,8 +42,10 @@ export const FIX_TARGETS = {
     'are-the-types-wrong': 'attw',
     publint: 'publint',
     'README badges': 'badges',
+    'Brand assets': 'brand',
     TypeDoc: 'typedoc',
     'AI setup': 'ai',
+    'Claude worktree settings': 'ai',
 };
 /**
  * Where the Swift module's fixers shadow (or extend) the JS-named defaults
@@ -154,6 +157,9 @@ export function declinedInLock(lock, checkName) {
         case 'README badges':
             return c.badges === false;
         case 'AI setup':
+        // The same recorded choice: the worktree settings are part of what
+        // `fix ai` writes, so a repo that declined AI setup declined them too.
+        case 'Claude worktree settings':
             return c.aiSetup === false;
         case 'Turborepo':
             return c.turborepo === false;

package/dist/cli/commands/setup-presets.js

@@ -273,7 +273,7 @@ export function computeFileList(config) {
     // so it's written for every JS scaffold.
     files.push('pnpm-workspace.yaml');
     if (config.aiSetup) {
-        files.push('AGENTS.md', 'CLAUDE.md', '.cursor/rules/repo-tooling.mdc', '.github/copilot-instructions.md', '.claude/skills/repo-tooling.md', '.mcp.json.example');
+        files.push('AGENTS.md', 'CLAUDE.md', '.cursor/rules/repo-tooling.mdc', '.github/copilot-instructions.md', '.claude/skills/repo-tooling.md', '.mcp.json.example', '.claude/settings.json');
     }
     if (config.turborepo)
         files.push('turbo.json');

package/dist/cli/generators/agent-rules.js

@@ -28,6 +28,60 @@ export function hasStaleAgentBlock(content) {
     const end = content.indexOf(BLOCK_END, bodyStart);
     return content.slice(bodyStart, end === -1 ? undefined : end).includes(LEGACY_TOOL_NAME);
 }
+export const CLAUDE_SETTINGS_FILE = path.join('.claude', 'settings.json');
+/**
+ * Directories Claude Code symlinks from the main checkout into a fresh
+ * worktree instead of leaving the agent to reinstall them (#396). An agent
+ * working a per-issue worktree can typecheck immediately rather than paying a
+ * full `pnpm install` first, on every issue.
+ */
+export const WORKTREE_SYMLINK_DIRS = ['node_modules'];
+function asObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Parsed `.claude/settings.json`, or null when absent, malformed, or not an object. */
+export async function readClaudeSettings(targetDir) {
+    try {
+        return asObject(await fs.readJson(path.join(targetDir, CLAUDE_SETTINGS_FILE)));
+    }
+    catch {
+        return null;
+    }
+}
+/** The `worktree.symlinkDirectories` entries already recorded, ignoring junk. */
+export function worktreeSymlinkDirs(settings) {
+    const dirs = asObject(settings?.worktree)?.symlinkDirectories;
+    return Array.isArray(dirs) ? dirs.filter((d) => typeof d === 'string') : [];
+}
+/**
+ * Upsert `worktree.symlinkDirectories` into `.claude/settings.json`. Repos
+ * already keep `hooks` and `permissions` in that file, so only the one key is
+ * merged and everything else survives — the same contract the AGENTS.md and
+ * copilot-instructions blocks give.
+ *
+ * Returns the written path, or null when there is nothing to write: a repo with
+ * no package.json has no node_modules to symlink (Swift, Python, Perl), and a
+ * file that doesn't parse is left for a human rather than clobbered.
+ */
+export async function installClaudeSettings(targetDir) {
+    if (!(await fs.pathExists(path.join(targetDir, 'package.json'))))
+        return null;
+    const file = path.join(targetDir, CLAUDE_SETTINGS_FILE);
+    const exists = await fs.pathExists(file);
+    const settings = exists ? await readClaudeSettings(targetDir) : {};
+    if (!settings)
+        return null;
+    const existing = worktreeSymlinkDirs(settings);
+    const symlinkDirectories = [
+        ...existing,
+        ...WORKTREE_SYMLINK_DIRS.filter((d) => !existing.includes(d)),
+    ];
+    const worktree = { ...asObject(settings.worktree), symlinkDirectories };
+    await fs.outputJson(file, { ...settings, worktree }, { spaces: 2 });
+    return CLAUDE_SETTINGS_FILE;
+}
 /** Read the shipped skill and split its frontmatter from the markdown body. */
 async function readSkill() {
     const raw = await fs.readFile(path.join(getPackageRoot(), SOURCE), 'utf8');
@@ -86,6 +140,10 @@ export async function installAiSetup(targetDir) {
     written.push(await installAgentRules(targetDir, 'copilot'));
     written.push((await copyPreset('claude-skill', targetDir)).target);
     written.push((await copyPreset('mcp-example', targetDir)).target);
+    // Only for repos that have node_modules to symlink — see installClaudeSettings.
+    const claudeSettings = await installClaudeSettings(targetDir);
+    if (claudeSettings)
+        written.push(claudeSettings);
     // If this repo ships its own skills (skills/<name>/SKILL.md), document their
     // one-command `npx skills add` install in README.md. No-op for repos without.
     const skillsDoc = await installSkillsInstallDocs(targetDir);

package/dist/cli/generators/brand.js

@@ -0,0 +1,284 @@
+/**
+ * Brand generator (#395) — the sources half of the brand-asset spec (#318).
+ *
+ * #318 standardised *which* images a repo ships; this writes **where they come
+ * from**: `brand/` holds the SVG sources and `brand/render.sh` renders them to
+ * PNG, so a banner can be recoloured, retitled or resized instead of being a
+ * committed binary nobody can regenerate.
+ *
+ * Everything in the emitted SVGs is derived from the consuming repo — name and
+ * tagline from its package.json, accent from its own docs theme or favicon —
+ * and falls back to a neutral grey. Nothing about any particular org is baked
+ * in; the templates are meant to be hand-edited afterwards.
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+/** Grey, so an unbranded repo reads as unbranded rather than borrowing a colour. */
+const NEUTRAL_ACCENT = '#8b95a7';
+/** The cool counter-glow in the corner opposite the accent one. Fixed — it reads as depth, not brand. */
+const COUNTER_GLOW = '#6e7bff';
+const INK = '#0A0E16';
+const TEXT = '#e6edf3';
+const MUTED = '#9ba6b8';
+function esc(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/**
+ * Greedy word wrap to a character budget. Character-budgeted rather than
+ * measured because there is no text metric available here — the templates are
+ * meant to be nudged by hand once rendered.
+ */
+export function wrapText(text, maxChars, maxLines) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        const next = line ? `${line} ${word}` : word;
+        if (next.length > maxChars && line) {
+            lines.push(line);
+            line = word;
+            if (lines.length === maxLines)
+                break;
+        }
+        else {
+            line = next;
+        }
+    }
+    if (lines.length < maxLines && line)
+        lines.push(line);
+    // Anything that didn't fit is dropped rather than overflowing the canvas.
+    if (lines.length === maxLines && text.length > lines.join(' ').length) {
+        lines[maxLines - 1] = `${lines[maxLines - 1]}…`;
+    }
+    return lines;
+}
+/** Near-black and near-white are background, not brand — skip them when sniffing a favicon. */
+function isBackgroundColour(hex) {
+    const n = Number.parseInt(hex.slice(1), 16);
+    const r = (n >> 16) & 0xff;
+    const g = (n >> 8) & 0xff;
+    const b = n & 0xff;
+    const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    return luminance < 60 || luminance > 225;
+}
+/**
+ * The docs site's own accent, which is the most deliberate colour choice a repo
+ * makes. Prefers the dark-mode value: these banners sit on a dark canvas.
+ */
+async function accentFromDocsTheme(targetDir) {
+    const file = path.join(targetDir, 'apps', 'docs', 'src', 'css', 'custom.css');
+    if (!(await fs.pathExists(file)))
+        return null;
+    const css = await fs.readFile(file, 'utf-8');
+    const dark = css.match(/\[data-theme=["']dark["']\][\s\S]*?--ifm-color-primary:\s*(#[0-9a-fA-F]{6})/);
+    if (dark?.[1])
+        return dark[1];
+    return css.match(/--ifm-color-primary:\s*(#[0-9a-fA-F]{6})/)?.[1] ?? null;
+}
+/** Failing that, the favicon's own ink — the other place a repo commits its colour. */
+async function accentFromFavicon(targetDir) {
+    const candidates = [path.join('apps', 'docs', 'static', 'img', 'favicon.svg'), 'favicon.svg'];
+    for (const rel of candidates) {
+        const file = path.join(targetDir, rel);
+        if (!(await fs.pathExists(file)))
+            continue;
+        const svg = await fs.readFile(file, 'utf-8');
+        for (const [hex] of svg.matchAll(/#[0-9a-fA-F]{6}\b/g)) {
+            if (!isBackgroundColour(hex))
+                return hex;
+        }
+    }
+    return null;
+}
+export async function resolveBrandMeta(pkg, targetDir) {
+    const pkgName = typeof pkg?.name === 'string' ? pkg.name : undefined;
+    const name = pkgName?.split('/').pop() ?? path.basename(path.resolve(targetDir));
+    const description = typeof pkg?.description === 'string' ? pkg.description : '';
+    const accent = (await accentFromDocsTheme(targetDir)) ?? (await accentFromFavicon(targetDir)) ?? NEUTRAL_ACCENT;
+    return {
+        name,
+        tagline: description || 'Add a one-line tagline to package.json "description".',
+        accent,
+        install: pkgName && pkg?.private !== true ? pkgName : null,
+    };
+}
+/**
+ * The logo mark: a rounded square in the accent carrying the project's initial.
+ * Authored on a 32 viewBox so it matches the favicon's geometry and can be
+ * swapped for the real favicon glyph verbatim.
+ */
+function mark(meta, translate, scale) {
+    const initial = esc((meta.name[0] ?? '?').toUpperCase());
+    return `	<!-- Logo mark: a 32 viewBox, so the real favicon glyph can be pasted in over it. -->
+	<g transform="translate(${translate}) scale(${scale})">
+		<rect width="32" height="32" rx="8" fill="${meta.accent}"/>
+		<text x="16" y="23" text-anchor="middle" font-family="Avenir Next" font-weight="800" font-size="19" fill="${INK}">${initial}</text>
+	</g>`;
+}
+/** `repo-tooling` renders as a muted `repo-` and an accented `tooling`. */
+function wordmark(meta) {
+    const i = meta.name.lastIndexOf('-');
+    if (i <= 0)
+        return `<tspan fill="${meta.accent}">${esc(meta.name)}</tspan>`;
+    return `<tspan fill="${TEXT}">${esc(meta.name.slice(0, i + 1))}</tspan><tspan fill="${meta.accent}">${esc(meta.name.slice(i + 1))}</tspan>`;
+}
+function taglineBlock(meta, opts) {
+    // Three lines: every canvas has room for a third, and cutting a real tagline
+    // short is worse than one extra line of copy.
+    const lines = wrapText(meta.tagline, opts.maxChars, 3);
+    // librsvg does not reset x on a y-only tspan, so every line repeats x.
+    const tspans = lines
+        .map((l, i) => `\t\t<tspan x="${opts.x}" y="${opts.y + i * opts.step}">${esc(l)}</tspan>`)
+        .join('\n');
+    const anchor = opts.centred ? ' text-anchor="middle"' : '';
+    return `	<text${anchor} font-family="Avenir Next" font-weight="500" font-size="${opts.size}" fill="${MUTED}">
+${tspans}
+	</text>`;
+}
+/** The install pill. Omitted entirely for a repo with nothing to `npm i`. */
+function installPanel(meta, opts) {
+    if (!meta.install)
+        return '';
+    return `
+	<rect x="${opts.x}" y="${opts.y}" width="${opts.w}" height="${opts.h}" rx="14" fill="#11151d" stroke="#232936" stroke-width="1"/>
+	<text xml:space="preserve" x="${opts.x + opts.w / 2}" y="${opts.y + opts.h / 2 + opts.size / 3}" text-anchor="middle" font-family="Menlo" font-size="${opts.size}"><tspan fill="${meta.accent}">npm i </tspan><tspan fill="${TEXT}">${esc(meta.install)}</tspan></text>`;
+}
+function canvas(meta, w, h, glow) {
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" role="img" aria-label="${esc(meta.name)} — ${esc(meta.tagline)}">
+	<defs>
+		<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+			<stop offset="0" stop-color="#0d1117"/>
+			<stop offset="1" stop-color="#090c13"/>
+		</linearGradient>
+		<radialGradient id="glow" cx="${glow.cx}" cy="${glow.cy}" r="0.55">
+			<stop offset="0" stop-color="${meta.accent}" stop-opacity="0.15"/>
+			<stop offset="1" stop-color="${meta.accent}" stop-opacity="0"/>
+		</radialGradient>
+		<radialGradient id="glow2" cx="0.92" cy="1" r="0.5">
+			<stop offset="0" stop-color="${COUNTER_GLOW}" stop-opacity="0.12"/>
+			<stop offset="1" stop-color="${COUNTER_GLOW}" stop-opacity="0"/>
+		</radialGradient>
+	</defs>
+
+	<rect width="${w}" height="${h}" fill="url(#bg)"/>
+	<rect width="${w}" height="${h}" fill="url(#glow)"/>
+	<rect width="${w}" height="${h}" fill="url(#glow2)"/>
+`;
+}
+/** 1280×320 README banner — left-aligned lockup, install pill on the right. */
+export function bannerSvg(meta) {
+    return `${canvas(meta, 1280, 320, { cx: 0.16, cy: 0 })}
+${mark(meta, '60 88', 2.25)}
+
+	<text x="156" y="150" font-family="Avenir Next" font-weight="800" font-size="62" letter-spacing="-1.5">${wordmark(meta)}</text>
+
+${taglineBlock(meta, { x: 62, y: 198, step: 28, size: 20, centred: false, maxChars: 44 })}
+${installPanel(meta, { x: 845, y: 118, w: 378, h: 84, size: 20 })}
+</svg>
+`;
+}
+/** 1280×786 mobile banner — the same content stacked so it stays legible on a phone. */
+export function bannerMobileSvg(meta) {
+    return `${canvas(meta, 1280, 786, { cx: 0.12, cy: 0.05 })}
+${mark(meta, '565 104', 4.6875)}
+
+	<text x="640" y="360" text-anchor="middle" font-family="Avenir Next" font-weight="800" font-size="76" letter-spacing="-1.8">${wordmark(meta)}</text>
+
+${taglineBlock(meta, { x: 640, y: 510, step: 44, size: 30, centred: true, maxChars: 42 })}
+${installPanel(meta, { x: 427, y: 650, w: 426, h: 78, size: 24 })}
+</svg>
+`;
+}
+/** 1280×640 Open Graph / GitHub social card. Keep content inside an ~8% safe inset. */
+export function socialCardSvg(meta) {
+    return `${canvas(meta, 1280, 640, { cx: 0.1, cy: 0.05 })}
+${mark(meta, '590 120', 3.125)}
+
+	<text x="640" y="300" text-anchor="middle" font-family="Avenir Next" font-weight="800" font-size="76" letter-spacing="-1.8">${wordmark(meta)}</text>
+
+${taglineBlock(meta, { x: 640, y: 372, step: 42, size: 28, centred: true, maxChars: 44 })}
+${installPanel(meta, { x: 427, y: 470, w: 426, h: 78, size: 24 })}
+</svg>
+`;
+}
+/**
+ * The render script. Sizes come from the #318 spec. It self-skips outputs whose
+ * source or destination doesn't exist, so the same script works in a repo with
+ * no docs site.
+ */
+export const RENDER_SH = `#!/usr/bin/env bash
+# Render the committed brand PNGs from their SVG sources.
+# Sizes come from the brand-asset spec: 1280x320 banner, 1280x786 mobile,
+# 1280x640 social card, 512x512 PWA icon.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+if ! command -v rsvg-convert >/dev/null 2>&1; then
+	echo "brand/render.sh needs librsvg — install it with: brew install librsvg" >&2
+	echo "(apt: apt-get install librsvg2-bin)" >&2
+	exit 1
+fi
+
+rsvg-convert -w 1280 -h 320 brand/banner.svg        -o brand/banner.png
+rsvg-convert -w 1280 -h 786 brand/banner-mobile.svg -o brand/banner-mobile.png
+echo "rendered: brand/banner.png brand/banner-mobile.png"
+
+# The docs-site assets, rendered only when the site exists to hold them.
+img=apps/docs/static/img
+if [ -d "$img" ]; then
+	rsvg-convert -w 1280 -h 640 brand/social-card.svg -o "$img/social-card.png"
+	echo "rendered: $img/social-card.png"
+	if [ -f "$img/favicon.svg" ]; then
+		rsvg-convert -w 512 -h 512 "$img/favicon.svg" -o "$img/favicon-512.png"
+		echo "rendered: $img/favicon-512.png"
+	fi
+fi
+`;
+/** Write `contents` at `rel` only when absent, so re-running never clobbers hand-edited art. */
+async function writeIfMissing(targetDir, rel, contents, mode) {
+    const file = path.join(targetDir, rel);
+    if (await fs.pathExists(file))
+        return null;
+    await fs.ensureDir(path.dirname(file));
+    await fs.writeFile(file, contents, mode ? { mode } : undefined);
+    return rel;
+}
+/**
+ * Repoint a README still using the pre-amendment root-level banner paths at
+ * `brand/`. Only the two banner `srcset`/`src` values move — nothing else in the
+ * README is touched.
+ */
+export async function repointReadmeBanners(targetDir) {
+    const file = path.join(targetDir, 'README.md');
+    if (!(await fs.pathExists(file)))
+        return null;
+    const readme = await fs.readFile(file, 'utf-8');
+    const next = readme.replace(/(?<!brand\/)(?:\.\/)?(banner(?:-mobile)?\.png)/g, './brand/$1');
+    if (next === readme)
+        return null;
+    await fs.writeFile(file, next);
+    return 'README.md';
+}
+/**
+ * Scaffold `brand/`: three SVG sources + the render script, then repoint a
+ * README still on the old root-level paths. Every file is written only when
+ * absent, so `fix brand` is idempotent.
+ */
+export async function generateBrand(pkg, targetDir) {
+    const meta = await resolveBrandMeta(pkg, targetDir);
+    const written = [];
+    const files = [
+        ['brand/banner.svg', bannerSvg(meta)],
+        ['brand/banner-mobile.svg', bannerMobileSvg(meta)],
+        ['brand/social-card.svg', socialCardSvg(meta)],
+        ['brand/render.sh', RENDER_SH, 0o755],
+    ];
+    for (const [rel, contents, mode] of files) {
+        const w = await writeIfMissing(targetDir, rel, contents, mode);
+        if (w)
+            written.push(w);
+    }
+    const readme = await repointReadmeBanners(targetDir);
+    if (readme)
+        written.push(readme);
+    return written;
+}

package/dist/languages/js/checks.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { hookHasUncommented } from '../../base/checks.js';
+import { CLAUDE_SETTINGS_FILE, readClaudeSettings, worktreeSymlinkDirs, } from '../../cli/generators/agent-rules.js';
 import { WORKSPACE_FILE, dependsOnEsbuild, familyGlob, missingPnpmSettings, } from '../../cli/generators/pnpm-workspace.js';
 const PACKAGE = '@rtorcato/repo-tooling';
 const NODE_MIN_MAJOR = 22;
@@ -951,6 +952,44 @@ export async function checkTreeshakeSetup(dir, pkg) {
         hint: 'Run `npx @rtorcato/repo-tooling fix treeshake-check` to scaffold an esbuild metafile assertion',
     };
 }
+/**
+ * A Claude Code worktree starts with no node_modules, so every agent working
+ * one pays a full install before it can typecheck, lint or test — unless
+ * `.claude/settings.json` tells Claude to symlink the directory from the main
+ * checkout (#396). JS-only: the other language modules have nothing to symlink.
+ */
+export async function checkClaudeWorktreeSettings(dir) {
+    const check = 'Claude worktree settings';
+    const hint = `Run \`npx ${PACKAGE} fix ai\` to merge worktree.symlinkDirectories into ${CLAUDE_SETTINGS_FILE}`;
+    if (!(await fs.pathExists(path.join(dir, CLAUDE_SETTINGS_FILE)))) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: `no ${CLAUDE_SETTINGS_FILE} — agent worktrees reinstall node_modules from scratch`,
+            hint,
+        };
+    }
+    const settings = await readClaudeSettings(dir);
+    if (!settings) {
+        return {
+            check,
+            status: 'drift',
+            detail: `${CLAUDE_SETTINGS_FILE} is not a readable JSON object`,
+            // `fix ai` deliberately skips an unparseable file rather than clobbering
+            // hand-written hooks/permissions, so this one is on the human.
+            hint: `Repair the JSON in ${CLAUDE_SETTINGS_FILE} by hand — \`fix ai\` refuses to overwrite it`,
+        };
+    }
+    if (worktreeSymlinkDirs(settings).includes('node_modules')) {
+        return { check, status: 'ok', detail: 'worktree.symlinkDirectories carries node_modules' };
+    }
+    return {
+        check,
+        status: 'optional-missing',
+        detail: `${CLAUDE_SETTINGS_FILE} has no worktree.symlinkDirectories entry for node_modules`,
+        hint,
+    };
+}
 export async function checkTurborepo(dir) {
     const hasTurbo = await fs.pathExists(path.join(dir, 'turbo.json'));
     const hasNx = await fs.pathExists(path.join(dir, 'nx.json'));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.8.7",
+	"version": "3.9.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [