@rtorcato/repo-tooling 2.59.0

package/dist/cli/generators/treeshake.js

@@ -0,0 +1,148 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * Inspect package.exports and return non-root subpath candidates (e.g. './foo' → 'foo').
+ * Skips '.', types-only entries, and wildcard patterns ('./*').
+ */
+export function inferSubpathsFromExports(pkg) {
+    const exports = pkg?.exports;
+    if (!exports || typeof exports !== 'object') {
+        return { allCandidates: [], defaultAllowed: null };
+    }
+    const candidates = [];
+    for (const key of Object.keys(exports)) {
+        if (key === '.' || !key.startsWith('./'))
+            continue;
+        if (key.includes('*'))
+            continue;
+        const trimmed = key.replace(/^\.\//, '');
+        if (!trimmed)
+            continue;
+        candidates.push(trimmed);
+    }
+    return {
+        allCandidates: candidates,
+        defaultAllowed: candidates[0] ?? null,
+    };
+}
+function renderCheckScript(opts) {
+    const allowed = JSON.stringify([opts.allowedSubpath]);
+    const forbidden = JSON.stringify(opts.forbiddenSubpaths, null, '\t');
+    return `import { build } from 'esbuild'
+
+const ALLOWED_MODULES = ${allowed}
+
+const FORBIDDEN_MODULES = ${forbidden}
+
+const result = await build({
+\tentryPoints: ['src/entry.ts'],
+\tbundle: true,
+\tformat: 'esm',
+\tplatform: 'browser',
+\tconditions: ['import', 'browser'],
+\twrite: false,
+\tmetafile: true,
+\tminify: false,
+})
+
+const inputs = Object.keys(result.metafile.inputs)
+const distInputs = inputs.filter((p) => p.includes('/dist/'))
+const leaks = distInputs.filter((p) =>
+\tFORBIDDEN_MODULES.some((m) => new RegExp(\`/dist/\${m}/\`).test(p))
+)
+const allowed = distInputs.filter((p) =>
+\tALLOWED_MODULES.some((m) => new RegExp(\`/dist/\${m}/\`).test(p))
+)
+
+const bundleBytes = result.outputFiles?.[0]?.contents.byteLength ?? 0
+
+console.log(\`Bundle size: \${bundleBytes} bytes\`)
+console.log(\`dist inputs in bundle (\${distInputs.length}):\`)
+for (const p of distInputs) console.log(\`  \${p}\`)
+
+if (leaks.length > 0) {
+\tconsole.error('\\n❌ Tree-shaking leak — forbidden modules in the bundle:')
+\tfor (const p of leaks) console.error(\`  \${p}\`)
+\tprocess.exit(1)
+}
+
+if (allowed.length === 0) {
+\tconsole.error(
+\t\t'\\n❌ Expected at least one allowed-subpath input — entry may have failed to resolve.'
+\t)
+\tprocess.exit(1)
+}
+
+console.log('\\n✅ Tree-shaking OK — only allowed inputs present.')
+`;
+}
+function renderEntry(workspaceName, allowedSubpath) {
+    return `export * from '${workspaceName}/${allowedSubpath}'\n`;
+}
+// The treeshake-check app lives under apps/ and depends on the root package via
+// `workspace:*`, which only resolves when a pnpm-workspace.yaml declares apps/*.
+// pnpm 11 fails install (ERR_PNPM_IGNORED_BUILDS) on any dependency with an
+// unapproved build script, approved via the `allowBuilds` map (package →
+// boolean — pnpm 11 ignores the older `onlyBuiltDependencies` list). Approve
+// the ones this monorepo shape needs:
+//   - esbuild: the tree-shake check builds with it
+//   - sharp:   pulled in by the common apps/docs (Docusaurus) path; built
+//   - core-js: also pulled by apps/docs, but its postinstall is unwanted → false
+// Naming a package that isn't installed is a harmless no-op, so seeding the
+// docs-path entries keeps `pnpm install` green the moment an apps/docs is added.
+const WORKSPACE_YAML = `packages:
+  - 'apps/*'
+
+allowBuilds:
+  esbuild: true
+  sharp: true
+  core-js: false
+`;
+/**
+ * Ensure a pnpm-workspace.yaml exists that globs apps/* (needed for the
+ * treeshake-check app's `workspace:*` dep to resolve). Never clobbers an
+ * existing file. Returns the relative path if written, else null.
+ */
+async function ensureWorkspaceYaml(targetDir) {
+    const wsPath = path.join(targetDir, 'pnpm-workspace.yaml');
+    if (await fs.pathExists(wsPath))
+        return null;
+    await fs.writeFile(wsPath, WORKSPACE_YAML);
+    return 'pnpm-workspace.yaml';
+}
+export async function generateTreeshakeCheck(targetDir, opts) {
+    const appDir = opts.appDir ?? 'apps/treeshake-check';
+    const root = path.join(targetDir, appDir);
+    await fs.ensureDir(path.join(root, 'src'));
+    const pkgName = `${opts.workspaceName.replace(/^@/, '').replace(/\//g, '-')}-treeshake-check`;
+    const packageJson = {
+        name: pkgName,
+        version: '0.0.0',
+        private: true,
+        type: 'module',
+        scripts: {
+            check: 'node check.mjs',
+        },
+        dependencies: {
+            [opts.workspaceName]: 'workspace:*',
+        },
+        devDependencies: {
+            esbuild: '^0.28.0',
+        },
+    };
+    const checkPath = path.join(root, 'check.mjs');
+    const entryPath = path.join(root, 'src', 'entry.ts');
+    const pkgPath = path.join(root, 'package.json');
+    await fs.writeJson(pkgPath, packageJson, { spaces: 2 });
+    await fs.writeFile(checkPath, renderCheckScript(opts));
+    await fs.writeFile(entryPath, renderEntry(opts.workspaceName, opts.allowedSubpath));
+    const written = [
+        path.join(appDir, 'package.json'),
+        path.join(appDir, 'check.mjs'),
+        path.join(appDir, 'src', 'entry.ts'),
+    ];
+    const workspaceFile = await ensureWorkspaceYaml(targetDir);
+    if (workspaceFile)
+        written.push(workspaceFile);
+    return written;
+}

package/dist/cli/generators/tsconfig.js

@@ -0,0 +1,27 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+export async function generateTSConfig(config, targetDir) {
+    const tsconfigPath = path.join(targetDir, 'tsconfig.json');
+    // Base configuration extends our tooling. The shared presets anchor `paths`
+    // with ${configDir}, so no local baseUrl/paths is needed (baseUrl is
+    // deprecated in TS 5.9, removed in TS 7.0). Refs: https://aka.ms/ts6
+    // Targeting Bun (#225) means the Bun-typed preset (adds `types: ['bun']`),
+    // regardless of the chosen project config — Bun is a runtime flag, not a type.
+    const preset = config.bun ? 'bun' : config.typescript.config;
+    const tsconfig = {
+        extends: `@rtorcato/repo-tooling/typescript/${preset}`,
+        compilerOptions: {},
+        include: ['src/**/*', 'reset.d.ts'],
+        exclude: ['node_modules', 'dist', 'build'],
+    };
+    // Adjust for project type
+    if (config.projectType === 'library') {
+        tsconfig.compilerOptions.outDir = './dist';
+        tsconfig.compilerOptions.rootDir = './src';
+    }
+    if (config.projectType === 'nextjs-app') {
+        tsconfig.include = ['next-env.d.ts', 'src', 'app', 'pages', 'components', 'reset.d.ts'];
+        tsconfig.exclude.push('.next');
+    }
+    await fs.writeJson(tsconfigPath, tsconfig, { spaces: 2 });
+}

package/dist/cli/generators/turborepo.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * Scaffold a starter turbo.json for a pnpm-workspace monorepo. Turborepo 2.x
+ * (`tasks`, not the pre-2.0 `pipeline`). The defaults cover the common
+ * build/lint/typecheck/test/dev pipeline; teams tune outputs per repo.
+ */
+export async function generateTurborepo(targetDir) {
+    const filepath = path.join(targetDir, 'turbo.json');
+    await fs.writeJson(filepath, TURBO_CONFIG, { spaces: 2 });
+    return 'turbo.json';
+}
+const TURBO_CONFIG = {
+    $schema: 'https://turborepo.com/schema.json',
+    tasks: {
+        build: {
+            dependsOn: ['^build'],
+            // Covers both plain bundlers (dist) and Next.js apps; cache is invalidated
+            // on source changes. Drop what your packages don't emit.
+            outputs: ['dist/**', '.next/**', '!.next/cache/**'],
+        },
+        lint: {},
+        typecheck: {
+            dependsOn: ['^build'],
+        },
+        test: {
+            dependsOn: ['^build'],
+            outputs: ['coverage/**'],
+        },
+        dev: {
+            cache: false,
+            persistent: true,
+        },
+    },
+};

package/dist/cli/generators/typedoc.js

@@ -0,0 +1,40 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+const DOCS_WORKFLOW = `name: 📚 Docs
+on:
+  push:
+    branches: [main]
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm docs
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: \${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+`;
+export async function generateTypedocConfig(pkg, targetDir) {
+    const name = pkg?.name ?? 'My Library';
+    const config = {
+        extends: ['@rtorcato/repo-tooling/typedoc'],
+        entryPoints: ['./src/index.ts'],
+        name,
+    };
+    await fs.writeJson(path.join(targetDir, 'typedoc.json'), config, { spaces: 2 });
+}
+export async function generateTypedocWorkflow(targetDir) {
+    const workflowsDir = path.join(targetDir, '.github', 'workflows');
+    await fs.ensureDir(workflowsDir);
+    await fs.writeFile(path.join(workflowsDir, 'docs.yml'), DOCS_WORKFLOW);
+    return '.github/workflows/docs.yml';
+}

package/dist/cli/index.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import chalk from 'chalk';
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import packageJson from '../../package.json' with { type: 'json' };
+import { doctorCommand } from './commands/doctor.js';
+import { fixCommand } from './commands/fix.js';
+import { setupProject } from './commands/setup.js';
+import { copyPreset, PRESETS } from './utils/copy-preset.js';
+async function isSelfRepo(dir) {
+    try {
+        const pkg = await fs.readJson(path.join(dir, 'package.json'));
+        return pkg.name === '@rtorcato/repo-tooling';
+    }
+    catch {
+        return false;
+    }
+}
+const program = new Command();
+program
+    .name('@rtorcato/repo-tooling')
+    .description('🛠️  JavaScript and TypeScript tooling setup for modern projects')
+    .version(packageJson.version);
+program
+    .command('setup')
+    .alias('init')
+    .description('🚀 Setup tooling for a new or existing project')
+    .option('-d, --directory <path>', 'Target directory for setup', process.cwd())
+    .option('--skip-install', 'Skip installing dependencies')
+    .option('--preset <name>', 'Skip prompts; use defaults for a project type')
+    .option('--config <path>', 'Skip prompts; read a ProjectConfig or .repo-tooling.json lockfile from <path>')
+    .option('--dry-run', 'Print the resolved config and file list, write nothing')
+    .option('--config-schema', 'Print the JSON Schema for ProjectConfig and exit')
+    .action(setupProject);
+program
+    .command('copy <config>')
+    .description('📋 Copy a specific configuration file to current directory')
+    .action(async (config) => {
+    if (!(config in PRESETS)) {
+        console.error(chalk.red(`\n❌ Unknown configuration: ${config}`));
+        console.log(chalk.gray('Available configurations:'));
+        for (const [key, { desc }] of Object.entries(PRESETS)) {
+            console.log(`  ${chalk.green('●')} ${chalk.bold(key)}: ${chalk.gray(desc)}`);
+        }
+        console.log();
+        process.exit(1);
+    }
+    try {
+        const result = await copyPreset(config);
+        console.log(chalk.green(`\n✅ Copied ${result.desc}`));
+        console.log(chalk.gray(`   From: ${result.source}`));
+        console.log(chalk.gray(`   To:   ${result.target}\n`));
+    }
+    catch (error) {
+        console.error(chalk.red(`\n❌ Error copying configuration: ${error}\n`));
+    }
+});
+const TOOL_CATALOG = [
+    {
+        name: 'TypeScript',
+        description: 'Base, React, Next.js, Node.js, Express, Bun tsconfig presets',
+        exports: [
+            '@rtorcato/repo-tooling/typescript/base',
+            '@rtorcato/repo-tooling/typescript/react',
+            '@rtorcato/repo-tooling/typescript/next',
+            '@rtorcato/repo-tooling/typescript/node',
+            '@rtorcato/repo-tooling/typescript/express',
+            '@rtorcato/repo-tooling/typescript/bun',
+            '@rtorcato/repo-tooling/typescript/test',
+            '@rtorcato/repo-tooling/typescript/reset',
+        ],
+        fixTarget: 'tsconfig',
+    },
+    {
+        name: 'Bun',
+        description: 'Bun runtime/test-runner config (bunfig.toml + Bun-typed tsconfig)',
+        exports: ['@rtorcato/repo-tooling/typescript/bun'],
+        fixTarget: 'bun',
+    },
+    {
+        name: 'ESLint',
+        description: 'Base and Next.js ESLint configurations',
+        exports: ['@rtorcato/repo-tooling/eslint/base', '@rtorcato/repo-tooling/eslint/nextjs'],
+        fixTarget: 'eslint',
+    },
+    {
+        name: 'Biome',
+        description: 'Fast formatter and linter configuration',
+        exports: ['@rtorcato/repo-tooling/biome'],
+        fixTarget: 'biome',
+    },
+    {
+        name: 'Prettier',
+        description: 'Code formatter configuration',
+        exports: ['@rtorcato/repo-tooling/prettier'],
+        fixTarget: 'prettier',
+    },
+    {
+        name: 'Vitest',
+        description: 'Testing framework configuration',
+        exports: [
+            '@rtorcato/repo-tooling/vitest/config',
+            '@rtorcato/repo-tooling/vitest/react',
+            '@rtorcato/repo-tooling/vitest/setup',
+        ],
+        fixTarget: 'vitest',
+    },
+    {
+        name: 'Jest',
+        description: 'Testing framework presets for browser and Node.js',
+        exports: [
+            '@rtorcato/repo-tooling/jest-presets/browser/jest-preset',
+            '@rtorcato/repo-tooling/jest-presets/node/jest-preset',
+        ],
+        fixTarget: null,
+    },
+    {
+        name: 'Playwright',
+        description: 'End-to-end testing configuration',
+        exports: ['@rtorcato/repo-tooling/playwright'],
+        fixTarget: null,
+    },
+    {
+        name: 'Cypress',
+        description: 'End-to-end testing configuration',
+        exports: ['@rtorcato/repo-tooling/cypress'],
+        fixTarget: 'cypress',
+    },
+    {
+        name: 'Commitlint',
+        description: 'Conventional commit linting',
+        exports: ['@rtorcato/repo-tooling/commitlint/config'],
+        fixTarget: 'commitlint',
+    },
+    {
+        name: 'Husky',
+        description: 'Git hooks for pre-commit validation',
+        exports: [],
+        fixTarget: 'husky',
+    },
+    {
+        name: 'lint-staged',
+        description: 'Run linters on staged files (pairs with Husky)',
+        exports: [],
+        fixTarget: 'husky',
+    },
+    {
+        name: 'Semantic Release',
+        description: 'Automated versioning and publishing',
+        exports: [
+            '@rtorcato/repo-tooling/semantic-release',
+            '@rtorcato/repo-tooling/semantic-release/github',
+            '@rtorcato/repo-tooling/semantic-release/docker',
+        ],
+        fixTarget: 'semantic-release',
+    },
+    {
+        name: 'Changesets',
+        description: 'Monorepo-friendly release tool (alternative to semantic-release)',
+        exports: ['@rtorcato/repo-tooling/changesets'],
+        fixTarget: 'changesets',
+    },
+    {
+        name: 'Release Please',
+        description: 'Release-PR-driven release tool (alternative to semantic-release)',
+        exports: ['@rtorcato/repo-tooling/release-please'],
+        fixTarget: 'release-please',
+    },
+    {
+        name: 'Oxlint',
+        description: 'Rust-based linter (additive to Biome/ESLint)',
+        exports: ['@rtorcato/repo-tooling/oxlint'],
+        fixTarget: 'oxlint',
+    },
+    {
+        name: 'tsup',
+        description: 'TypeScript bundler configuration',
+        exports: ['@rtorcato/repo-tooling/tsup'],
+        fixTarget: null,
+    },
+    {
+        name: 'TypeDoc',
+        description: 'API documentation generation for TypeScript library projects',
+        exports: ['@rtorcato/repo-tooling/typedoc'],
+        fixTarget: 'typedoc',
+    },
+    {
+        name: 'Docs site',
+        description: 'Docusaurus docs site (apps/docs) with shared tokens + GitHub Pages deploy',
+        exports: [],
+        fixTarget: 'docs-site',
+    },
+    {
+        name: 'esbuild',
+        description: 'Fast JavaScript bundler configuration',
+        exports: ['@rtorcato/repo-tooling/esbuild'],
+        fixTarget: null,
+    },
+    {
+        name: 'Vite',
+        description: 'Modern web app build tool configuration',
+        exports: ['@rtorcato/repo-tooling/vite'],
+        fixTarget: null,
+    },
+    {
+        name: 'EditorConfig',
+        description: 'Cross-editor formatting consistency (.editorconfig)',
+        exports: [],
+        fixTarget: 'editorconfig',
+    },
+    {
+        name: '.nvmrc',
+        description: 'Pin Node version per repository',
+        exports: [],
+        fixTarget: 'nvmrc',
+    },
+    {
+        name: 'knip',
+        description: 'Find unused files, exports, and dependencies',
+        exports: [],
+        fixTarget: 'knip',
+    },
+    {
+        name: 'Dependabot',
+        description: 'Weekly automated dependency updates',
+        exports: [],
+        fixTarget: 'dependabot',
+    },
+    {
+        name: 'Renovate',
+        description: 'Weekly automated dependency updates (alternative to Dependabot)',
+        exports: [],
+        fixTarget: 'renovate',
+    },
+    {
+        name: 'CodeQL',
+        description: 'GitHub security scanning workflow',
+        exports: [],
+        fixTarget: 'codeql',
+    },
+    {
+        name: 'SwiftLint',
+        description: 'Swift linter configuration (lint + --fix; pairs with `swiftlint --strict` in CI)',
+        exports: [],
+        fixTarget: 'swiftlint',
+    },
+    {
+        name: 'Periphery',
+        description: 'Swift dead-code scanner configuration (retains public API for SwiftPM libraries)',
+        exports: [],
+        fixTarget: 'periphery',
+    },
+    {
+        name: 'AI Agent Setup',
+        description: 'Scaffold AGENTS.md, CLAUDE.md, Cursor/Copilot rules, Claude skill, MCP example',
+        exports: [],
+        fixTarget: 'ai',
+    },
+];
+program
+    .command('list')
+    .alias('ls')
+    .description('📋 List all available tooling configurations')
+    .option('--json', 'Emit machine-readable JSON output')
+    .action((options) => {
+    if (options.json) {
+        console.log(JSON.stringify({ tools: TOOL_CATALOG }, null, 2));
+        return;
+    }
+    console.log(chalk.cyan('\n🛠️  Available tooling configurations:\n'));
+    for (const { name, description } of TOOL_CATALOG) {
+        console.log(`  ${chalk.green('●')} ${chalk.bold(name)}: ${chalk.gray(description)}`);
+    }
+    console.log(chalk.dim('\n💡 Run `repo-tooling setup` for a new project'));
+    console.log(chalk.dim('   or `repo-tooling fix` to apply missing pieces to an existing one\n'));
+});
+program
+    .command('doctor')
+    .description('🩺 Diagnose project alignment with @rtorcato/repo-tooling presets')
+    .option('-d, --directory <path>', 'Target directory to diagnose', process.cwd())
+    .option('--json', 'Emit machine-readable JSON output')
+    .action(doctorCommand);
+program
+    .command('fix [target]')
+    .description('🔧 Apply scaffolders for items doctor flagged')
+    .option('-d, --directory <path>', 'Target directory', process.cwd())
+    .option('--yes', 'Assume yes to all prompts (including drift overwrites)')
+    .option('--dry-run', 'Print what would change without writing files')
+    .option('--json', 'Emit machine-readable JSON output (implies --yes)')
+    .option('--list', 'List all registered fix targets and exit')
+    .option('--resync', 'Re-scaffold every file recorded in .repo-tooling.json')
+    .option('--diff', 'Show a unified diff of each change before confirming')
+    .action((target, options) => fixCommand(target, {
+    directory: options.directory,
+    yes: options.yes,
+    dryRun: options.dryRun,
+    json: options.json,
+    list: options.list,
+    resync: options.resync,
+    diff: options.diff,
+}));
+program.hook('preAction', async (_, actionCommand) => {
+    const name = actionCommand.name();
+    if (name === 'setup' || name === 'doctor' || name === 'fix') {
+        // `fix --list` is read-only and safe to run anywhere, including this repo.
+        if (name === 'fix' && actionCommand.opts().list)
+            return;
+        // Dogfood escape hatch (#273): allow read-only `doctor` against this repo
+        // so CI can audit our own config the same way it does consumers'. Scoped
+        // to doctor — the mutating setup/fix stay blocked even with the flag set.
+        if (name === 'doctor' && process.env.REPO_TOOLING_ALLOW_SELF === '1')
+            return;
+        const dir = actionCommand.opts().directory ?? process.cwd();
+        if (await isSelfRepo(dir)) {
+            console.log(chalk.yellow('\n⚠️  This command cannot be run inside the @rtorcato/repo-tooling repo itself.\n'));
+            console.log(chalk.gray('   setup and doctor are for consumer projects, not for the tooling repo.\n'));
+            process.exit(0);
+        }
+    }
+});
+// Handle unknown commands
+program.on('command:*', () => {
+    console.error(chalk.red(`\n❌ Unknown command: ${program.args.join(' ')}`));
+    console.log(chalk.gray('See --help for a list of available commands.\n'));
+    process.exit(1);
+});
+// Show help if no arguments
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}
+program.parse();

package/dist/cli/utils/copy-preset.js

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+export const PRESETS = {
+    biome: {
+        source: 'tooling/biome/biome.json',
+        target: 'biome.json',
+        desc: 'Biome formatter and linter configuration',
+    },
+    bun: {
+        source: 'tooling/bun/bunfig.toml',
+        target: 'bunfig.toml',
+        desc: 'Bun runtime/test-runner configuration',
+    },
+    nx: {
+        source: 'tooling/nx/nx.json',
+        target: 'nx.json',
+        desc: 'Nx monorepo task-orchestrator configuration',
+    },
+    changesets: {
+        source: 'tooling/changesets/config.json',
+        target: '.changeset/config.json',
+        desc: 'Changesets release-tool configuration',
+    },
+    'release-please': {
+        source: 'tooling/release-please/release-please-config.json',
+        target: 'release-please-config.json',
+        desc: 'Release Please release-tool configuration',
+    },
+    oxlint: {
+        source: 'tooling/oxlint/oxlintrc.json',
+        target: '.oxlintrc.json',
+        desc: 'Oxlint linter configuration (additive to Biome)',
+    },
+    tsconfig: {
+        source: 'tooling/typescript/tsconfig.base.json',
+        target: 'tsconfig.json',
+        desc: 'TypeScript base configuration',
+    },
+    swiftlint: {
+        source: 'tooling/swift/swiftlint.yml',
+        target: '.swiftlint.yml',
+        desc: 'SwiftLint configuration (lint + --fix; the standard swift-common runs)',
+    },
+    periphery: {
+        source: 'tooling/swift/periphery.yml',
+        target: '.periphery.yml',
+        desc: 'Periphery dead-code scan configuration (retains public API)',
+    },
+    'claude-skill': {
+        source: 'tooling/claude/repo-tooling.md',
+        target: '.claude/skills/repo-tooling.md',
+        desc: 'Claude Code skill for driving the repo-tooling CLI',
+        legacyTarget: '.claude/skills/js-tooling.md',
+    },
+    'mcp-example': {
+        source: 'tooling/mcp/mcp.json.example',
+        target: '.mcp.json.example',
+        desc: 'Commented MCP server template (copy to .mcp.json to activate)',
+    },
+    'docusaurus-sync-changelog': {
+        source: 'tooling/docusaurus/sync-changelog.mjs',
+        target: 'scripts/sync-changelog.mjs',
+        desc: 'Canonical CHANGELOG → docs sync script for Docusaurus sites',
+    },
+    'docusaurus-theme-tokens': {
+        source: 'tooling/docusaurus/theme-tokens.css',
+        target: 'apps/docs/src/css/_jt-tokens.css',
+        desc: 'Shared Docusaurus design tokens (Geist + navy surfaces; accent per-project)',
+    },
+    'docusaurus-theme': {
+        source: 'tooling/docusaurus/theme.css',
+        target: 'apps/docs/src/css/theme.css',
+        desc: 'Shared Docusaurus component theme (navbar, cards, sidebar, footer, tables; accent-agnostic — @import after docusaurus-theme-tokens)',
+    },
+};
+export function getPackageRoot() {
+    const cliFile = new URL(import.meta.url).pathname;
+    return path.dirname(path.dirname(path.dirname(path.dirname(cliFile))));
+}
+export async function copyPreset(name, targetDir = process.cwd()) {
+    const preset = PRESETS[name];
+    const packageRoot = getPackageRoot();
+    const sourcePath = path.join(packageRoot, preset.source);
+    const targetPath = path.join(targetDir, preset.target);
+    await fs.copy(sourcePath, targetPath);
+    // Remove the pre-rename artifact so a re-run migrates it instead of leaving both.
+    if (preset.legacyTarget) {
+        const legacyPath = path.join(targetDir, preset.legacyTarget);
+        if (legacyPath !== targetPath)
+            await fs.remove(legacyPath);
+    }
+    return {
+        source: preset.source,
+        target: preset.target,
+        targetPath,
+        desc: preset.desc,
+    };
+}