@rtorcato/repo-tooling 2.59.0

package/dist/cli/commands/setup.js

@@ -0,0 +1,501 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import inquirer from 'inquirer';
+import { LANGUAGES } from '../../languages/registry.js';
+import { generateConfigs } from '../generators/index.js';
+import { detectLanguage } from '../utils/detect-language.js';
+import { formatGeneratedFiles } from '../utils/format.js';
+import { installDependencies } from '../utils/install.js';
+import { LOCKFILE_NAME, writeLockfile } from '../utils/lockfile.js';
+import { buildPresetConfig, computeFileList, CONFIG_SCHEMA, PRESET_NAMES, validateProjectConfig, } from './setup-presets.js';
+/** `null` means the run was declined, not that it failed — see promptForConfig. */
+async function resolveConfig(options) {
+    if (options.config && options.preset) {
+        console.warn(chalk.yellow('⚠️  Both --config and --preset given; --config wins.\n'));
+    }
+    if (options.config) {
+        const configPath = path.resolve(options.config);
+        if (!(await fs.pathExists(configPath))) {
+            throw new Error(`Config file not found: ${configPath}`);
+        }
+        const raw = await fs.readJson(configPath);
+        // Accept the `.repo-tooling.json` lockfile itself as the config source, so a
+        // repo needs only one file: the lockfile already embeds the full
+        // ProjectConfig under `config`. Unwrap it here rather than requiring a
+        // separate hand-authored config file (#271).
+        const candidate = typeof raw === 'object' && raw !== null && 'config' in raw && 'version' in raw
+            ? raw.config
+            : raw;
+        const { valid, errors } = validateProjectConfig(candidate);
+        if (!valid) {
+            throw new Error(`Invalid config:\n  - ${errors.join('\n  - ')}`);
+        }
+        return candidate;
+    }
+    if (options.preset) {
+        if (!PRESET_NAMES.includes(options.preset)) {
+            throw new Error(`Unknown preset: ${options.preset}. Available: ${PRESET_NAMES.join(', ')}`);
+        }
+        const projectName = path.basename(path.resolve(options.directory));
+        return buildPresetConfig(options.preset, projectName);
+    }
+    return promptForConfig(path.resolve(options.directory));
+}
+export async function setupProject(options) {
+    if (options.configSchema) {
+        console.log(JSON.stringify(CONFIG_SCHEMA, null, 2));
+        return;
+    }
+    const targetDir = path.resolve(options.directory);
+    const interactive = !options.config && !options.preset;
+    const dryRun = options.dryRun === true;
+    if (interactive && !dryRun) {
+        console.log(chalk.cyan('\n🛠️  Welcome to JS Tooling Setup!\n'));
+        console.log(chalk.gray(`Setting up tooling in: ${targetDir}\n`));
+    }
+    try {
+        await fs.ensureDir(targetDir);
+        const config = await resolveConfig(options);
+        // The language picker bails out for a language whose module hasn't landed
+        // yet. It has already explained why — scaffolding a JS project into a Swift
+        // repo would be worse than doing nothing.
+        if (config === null)
+            return;
+        if (dryRun) {
+            const files = computeFileList(config);
+            console.log(JSON.stringify({ directory: targetDir, config, files }, null, 2));
+            return;
+        }
+        if (!interactive) {
+            const shape = config.language === 'swift' ? `Swift ${config.projectType}` : config.projectType;
+            console.log(chalk.cyan(`\n🛠️  Scaffolding ${shape} in ${targetDir}\n`));
+        }
+        console.log(chalk.cyan('\n📝 Generating configuration files...\n'));
+        await generateConfigs(config, targetDir);
+        await writeLockfile(targetDir, config);
+        // Both steps shell out to pnpm. A Swift package has no dependencies to
+        // install and no Biome to format with — SwiftPM resolves on first build,
+        // and `swiftlint --fix` is the formatter (it needs a Swift toolchain we
+        // can't assume is present).
+        if (!options.skipInstall && config.language !== 'swift') {
+            console.log(chalk.cyan('\n📦 Installing dependencies...\n'));
+            await installDependencies(config, targetDir);
+            // Format now that the linter/formatter is installed, so the scaffold
+            // passes its own `pnpm check` out of the box (templates are written by
+            // hand and don't match biome/prettier whitespace).
+            await formatGeneratedFiles(config, targetDir);
+        }
+        console.log(chalk.green('\n✅ Setup completed successfully!\n'));
+        showNextSteps(config, targetDir);
+    }
+    catch (error) {
+        console.error(chalk.red('\n❌ Setup failed:'), error);
+        process.exit(1);
+    }
+}
+/**
+ * Languages `setup` can scaffold. Deliberately separate from the registry's
+ * `supported` flag, which means "has doctor/fix checks" — a language can be
+ * auditable before it's scaffoldable (Swift was, between #286 and #288). Both
+ * the picker label and the gate below read from here, so the two can't drift.
+ */
+const SCAFFOLDABLE = ['js', 'swift'];
+/**
+ * Ask which language this repo is, defaulting to whatever the target dir looks
+ * like. Languages setup can't scaffold yet are still offered — hiding them reads
+ * as "repo-tooling is JS-only" when the honest answer is "not yet" (#139).
+ */
+async function promptForLanguage(targetDir) {
+    const detected = await detectLanguage(targetDir);
+    const { language } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'language',
+            message: '🗣️  What is the primary language of this repo?',
+            choices: Object.values(LANGUAGES).map((module) => ({
+                name: SCAFFOLDABLE.includes(module.id)
+                    ? module.label
+                    : `${module.label} (${module.supported ? 'doctor/fix only — no setup preset yet' : 'setup lands with its module'})`,
+                value: module.id,
+            })),
+            // 'unknown' is a bare dir mid-setup — JS is the historical default.
+            default: detected === 'unknown' ? 'js' : detected,
+        },
+    ]);
+    return LANGUAGES[language];
+}
+function explainNotScaffoldable(module) {
+    console.log(chalk.yellow(`\n⚠️  ${module.label} scaffolding isn't available yet.\n`));
+    console.log(chalk.gray(module.supported
+        ? `   doctor and fix already audit ${module.label} repos — both the language-agnostic\n` +
+            `   checks (CI, CodeQL, Dependabot, GitHub repo settings) and the ${module.label}-specific\n` +
+            '   ones:\n'
+        : `   doctor and fix already cover ${module.label} repos with the language-agnostic\n` +
+            '   checks (CI, CodeQL, Dependabot, GitHub repo settings):\n'));
+    console.log(chalk.gray('     npx @rtorcato/repo-tooling doctor\n'));
+    console.log(chalk.gray(`   ${module.label} setup presets are tracked at\n` +
+        '   https://github.com/rtorcato/repo-tooling/issues/139\n'));
+}
+/** `null` when the chosen language has no scaffolding yet; nothing is written. */
+async function promptForConfig(targetDir) {
+    const language = await promptForLanguage(targetDir);
+    // Gate on SCAFFOLDABLE, not `module.supported` — Swift is supported (#286)
+    // but has no preset yet (#288), and falling through here would write a
+    // package.json into a Swift repo.
+    if (!SCAFFOLDABLE.includes(language.id)) {
+        explainNotScaffoldable(language);
+        return null;
+    }
+    // Swift has exactly one shape to scaffold, so there is nothing to ask beyond
+    // the name: SwiftLint, Periphery and `swift test` are the standard, not
+    // options (see the `swift-library` preset). A wizard whose every question has
+    // one answer is worse than no wizard.
+    if (language.id === 'swift') {
+        const { projectName } = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'projectName',
+                message: '📦 What is your package name?',
+                default: path.basename(targetDir),
+                validate: (input) => input.trim().length > 0 || 'Package name is required',
+            },
+        ]);
+        return buildPresetConfig('swift-library', projectName);
+    }
+    // Narrowing for the question list below, which is JS-shaped throughout.
+    if (language.id !== 'js')
+        return null;
+    // Turborepo only makes sense in a pnpm-workspace monorepo, so the prompt is
+    // only offered when one is already present in the target dir.
+    const hasWorkspace = await fs.pathExists(path.join(targetDir, 'pnpm-workspace.yaml'));
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'projectName',
+            message: '📦 What is your project name?',
+            default: path.basename(process.cwd()),
+            validate: (input) => input.trim().length > 0 || 'Project name is required',
+        },
+        {
+            type: 'list',
+            name: 'projectType',
+            message: '🏗️  What type of project are you building?',
+            choices: [
+                { name: '📚 Library/Package', value: 'library' },
+                { name: '🌐 Web Application', value: 'web-app' },
+                { name: '🚀 Node.js API', value: 'node-api' },
+                { name: '⚡ Next.js App', value: 'nextjs-app' },
+                { name: '⚛️  React App', value: 'react-app' },
+            ],
+        },
+        {
+            type: 'confirm',
+            name: 'useTypeScript',
+            message: '📘 Do you want to use TypeScript?',
+            default: true,
+        },
+        {
+            type: 'list',
+            name: 'tsConfig',
+            message: '⚙️  Which TypeScript configuration?',
+            choices: (answers) => {
+                const baseChoices = [
+                    { name: '🔧 Base (General purpose)', value: 'base' },
+                    { name: '🖥️  Node.js', value: 'node' },
+                ];
+                if (answers.projectType === 'nextjs-app') {
+                    return [{ name: '⚡ Next.js', value: 'next' }, ...baseChoices];
+                }
+                if (answers.projectType === 'react-app' || answers.projectType === 'web-app') {
+                    return [{ name: '⚛️  React', value: 'react' }, ...baseChoices];
+                }
+                if (answers.projectType === 'node-api') {
+                    return [
+                        { name: '🚀 Express/API', value: 'express' },
+                        { name: '🖥️  Node.js', value: 'node' },
+                    ];
+                }
+                return baseChoices;
+            },
+            when: (answers) => answers.useTypeScript,
+        },
+        {
+            type: 'list',
+            name: 'lintingTool',
+            message: '🔍 Which linting/formatting tool?',
+            choices: [
+                { name: '⚡ Biome (Fast, all-in-one)', value: 'biome' },
+                { name: '🔧 ESLint (Configurable)', value: 'eslint' },
+                { name: '🔥 Both Biome + ESLint', value: 'both' },
+                { name: '❌ None', value: 'none' },
+            ],
+            default: 'biome',
+        },
+        {
+            type: 'list',
+            name: 'eslintConfig',
+            message: '🔧 Which ESLint configuration?',
+            choices: (answers) => {
+                const choices = [{ name: '🔧 Base configuration', value: 'base' }];
+                if (answers.projectType === 'nextjs-app') {
+                    choices.unshift({ name: '⚡ Next.js configuration', value: 'nextjs' });
+                }
+                return choices;
+            },
+            when: (answers) => answers.lintingTool === 'eslint' || answers.lintingTool === 'both',
+        },
+        {
+            type: 'confirm',
+            name: 'oxlint',
+            message: '🦀 Also run Oxlint alongside (50–100× faster than ESLint)?',
+            default: false,
+            when: (answers) => answers.lintingTool !== 'none',
+        },
+        {
+            type: 'list',
+            name: 'testingFramework',
+            message: '🧪 Which testing framework?',
+            choices: [
+                { name: '⚡ Vitest (Fast, Vite-powered)', value: 'vitest' },
+                { name: '🃏 Jest (Traditional)', value: 'jest' },
+                { name: '🎭 Playwright (E2E)', value: 'playwright' },
+                { name: '🌲 Cypress (E2E)', value: 'cypress' },
+                { name: '❌ None', value: 'none' },
+            ],
+            default: 'vitest',
+        },
+        {
+            type: 'list',
+            name: 'testEnvironment',
+            message: '🌍 Test environment?',
+            choices: [
+                { name: '🖥️  Node.js', value: 'node' },
+                { name: '🌐 Browser (DOM)', value: 'browser' },
+                { name: '🔄 Both', value: 'both' },
+            ],
+            when: (answers) => answers.testingFramework === 'jest',
+            default: 'node',
+        },
+        {
+            type: 'confirm',
+            name: 'gitHooks',
+            message: '🪝 Set up Git hooks (Husky + lint-staged)?',
+            default: true,
+        },
+        {
+            type: 'confirm',
+            name: 'commitLint',
+            message: '📝 Set up conventional commit linting?',
+            default: true,
+            when: (answers) => answers.gitHooks,
+        },
+        {
+            type: 'list',
+            name: 'releaseTool',
+            message: '🚀 Automated release tool?',
+            choices: [
+                { name: '📦 semantic-release (commit-message-driven)', value: 'semantic-release' },
+                { name: '📝 Changesets (changeset-file-driven, monorepo-friendly)', value: 'changesets' },
+                { name: '🙏 Release Please (Google, release-PR-driven)', value: 'release-please' },
+                { name: '❌ None', value: 'none' },
+            ],
+            default: 'semantic-release',
+            when: (answers) => answers.projectType === 'library',
+        },
+        {
+            type: 'confirm',
+            name: 'treeshakeCheck',
+            message: '🌳 Add a tree-shake verification check (apps/treeshake-check)?',
+            default: false,
+            when: (answers) => answers.projectType === 'library',
+        },
+        {
+            type: 'confirm',
+            name: 'publint',
+            message: '📦 Add publint to lint your package before publishing?',
+            default: true,
+            when: (answers) => answers.projectType === 'library',
+        },
+        {
+            type: 'confirm',
+            name: 'badges',
+            message: '🔖 Add status badges (CI, npm, coverage, license) to the README?',
+            default: true,
+        },
+        {
+            type: 'confirm',
+            name: 'securityAutomation',
+            message: '🛡️  Include security automation (Dependabot + CodeQL)?',
+            default: true,
+        },
+        {
+            type: 'confirm',
+            name: 'aiSetup',
+            message: '🤖 Add AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill)?',
+            default: true,
+        },
+        {
+            type: 'list',
+            name: 'orchestrator',
+            message: '🚀 Monorepo task orchestrator?',
+            choices: [
+                { name: '⚡ Turborepo (turbo.json)', value: 'turbo' },
+                { name: '🔷 Nx (nx.json)', value: 'nx' },
+                { name: '❌ None', value: 'none' },
+            ],
+            default: 'turbo',
+            when: () => hasWorkspace,
+        },
+        {
+            type: 'confirm',
+            name: 'tailwind',
+            message: '🎨 Add Tailwind CSS v4 (PostCSS plugin + globals.css)?',
+            default: true,
+            // Only meaningful for frontend project types.
+            when: (answers) => answers.projectType === 'web-app' ||
+                answers.projectType === 'react-app' ||
+                answers.projectType === 'nextjs-app',
+        },
+        {
+            type: 'list',
+            name: 'bundler',
+            message: '📦 Which bundler/build tool?',
+            choices: (answers) => {
+                const choices = [
+                    { name: '📦 tsup (TypeScript packages)', value: 'tsup' },
+                    { name: '⚡ esbuild (Fast bundling)', value: 'esbuild' },
+                    { name: '🍣 Rollup (library bundler)', value: 'rollup' },
+                    { name: '🦀 Rolldown (Rust, Rollup-compatible)', value: 'rolldown' },
+                    { name: '❌ None', value: 'none' },
+                ];
+                if (answers.projectType === 'web-app' || answers.projectType === 'react-app') {
+                    choices.unshift({ name: '⚡ Vite (Modern web apps)', value: 'vite' });
+                }
+                return choices;
+            },
+            when: (answers) => answers.projectType !== 'nextjs-app', // Next.js has its own bundler
+        },
+        {
+            type: 'confirm',
+            name: 'bun',
+            message: '🥟 Target the Bun runtime (bunfig.toml + Bun-typed tsconfig)?',
+            default: false,
+            // A runtime flag, not a project type — offer it for Node-compatible
+            // library/API targets, not the browser-framework types.
+            when: (answers) => answers.projectType === 'library' || answers.projectType === 'node-api',
+        },
+    ]);
+    return {
+        projectName: answers.projectName,
+        // The real answer from the language question above, not a hardcoded 'js'
+        // (#284) — the lockfile is what doctor/fix gate on later.
+        language: language.id,
+        projectType: answers.projectType,
+        typescript: {
+            enabled: answers.useTypeScript || false,
+            config: answers.tsConfig || 'base',
+        },
+        linting: {
+            tool: answers.lintingTool || 'none',
+            eslintConfig: answers.eslintConfig,
+        },
+        formatting: {
+            tool: answers.lintingTool === 'biome' || answers.lintingTool === 'both'
+                ? 'biome'
+                : answers.lintingTool === 'eslint'
+                    ? 'prettier'
+                    : 'none',
+        },
+        testing: {
+            framework: answers.testingFramework || 'none',
+            environment: answers.testEnvironment,
+        },
+        gitHooks: answers.gitHooks || false,
+        commitLint: answers.commitLint || false,
+        semanticRelease: answers.releaseTool === 'semantic-release',
+        changesets: answers.releaseTool === 'changesets',
+        releasePlease: answers.releaseTool === 'release-please',
+        oxlint: answers.oxlint || false,
+        securityAutomation: answers.securityAutomation ?? false,
+        bundler: answers.bundler || 'none',
+        treeshakeCheck: answers.treeshakeCheck || false,
+        publint: answers.publint ?? false,
+        badges: answers.badges ?? false,
+        aiSetup: answers.aiSetup ?? false,
+        turborepo: answers.orchestrator === 'turbo',
+        nx: answers.orchestrator === 'nx',
+        tailwind: answers.tailwind ?? false,
+        bun: answers.bun ?? false,
+    };
+}
+function showNextSteps(config, _targetDir) {
+    console.log(chalk.bold('\n📋 Next Steps:\n'));
+    const steps = [];
+    // Every step in the else-branch names a pnpm script. Swift's equivalents are
+    // SwiftPM and SwiftLint commands — and neither tool ships with the scaffold,
+    // so the last line is how to get them.
+    if (config.language === 'swift') {
+        steps.push('🏗️  Build with: swift build', '🧪 Run tests with: swift test', '🔍 Lint and format with: swiftlint --fix (CI runs swiftlint lint --strict)', '🧹 Find dead code with: periphery scan', '📦 Install both tools with: brew install swiftlint periphery');
+    }
+    else {
+        if (config.typescript.enabled) {
+            steps.push('🔧 Customize your tsconfig.json as needed');
+        }
+        if (config.linting.tool !== 'none') {
+            steps.push(`🔍 Run linting with: ${config.linting.tool === 'biome' ? 'pnpm biome check .' : 'pnpm eslint .'}`);
+        }
+        if (config.testing.framework !== 'none') {
+            steps.push(`🧪 Run tests with: pnpm ${config.testing.framework}`);
+        }
+        if (config.gitHooks) {
+            steps.push('🪝 Commit your changes to test the git hooks');
+        }
+    }
+    steps.push(`🔒 ${LOCKFILE_NAME} records your setup choices — doctor uses it to suppress intentional opt-outs`);
+    steps.push('📖 Check the generated README.md for more details');
+    steps.forEach((step, index) => {
+        console.log(`  ${index + 1}. ${step}`);
+    });
+    const skipped = collectSkippedFixSuggestions(config);
+    if (skipped.length > 0) {
+        console.log(chalk.bold('\n💡 Want to add something you skipped?\n'));
+        for (const s of skipped) {
+            console.log(`  ${chalk.gray('-')} ${s}`);
+        }
+    }
+    console.log(chalk.dim('\n📁 All configuration files have been generated in your project directory.'));
+    console.log(chalk.dim('   You can modify them to suit your specific needs.\n'));
+}
+function collectSkippedFixSuggestions(config) {
+    const suggestions = [];
+    // Every suggestion below is a JS fix target (husky, biome, vitest…). On a
+    // Swift repo they'd all be wrong — `fix` doesn't even offer them there — so
+    // the Swift scaffold gets only the doctor line at the end.
+    if (config.language === 'swift') {
+        return ['Run `npx @rtorcato/repo-tooling doctor` any time to audit drift'];
+    }
+    if (!config.gitHooks) {
+        suggestions.push('Run `npx @rtorcato/repo-tooling fix husky` to add git hooks later');
+    }
+    if (!config.commitLint) {
+        suggestions.push('Run `npx @rtorcato/repo-tooling fix commitlint` to add conventional-commit linting');
+    }
+    if (!config.semanticRelease && config.projectType === 'library') {
+        suggestions.push('Run `npx @rtorcato/repo-tooling fix semantic-release` to add automated releases');
+    }
+    if (!config.securityAutomation) {
+        suggestions.push('Run `npx @rtorcato/repo-tooling fix dependabot` and `fix codeql` for security automation');
+    }
+    if (config.linting.tool === 'none') {
+        suggestions.push('Run `npx @rtorcato/repo-tooling fix biome` or `fix eslint` to add linting');
+    }
+    if (config.testing.framework === 'none') {
+        suggestions.push('Run `npx @rtorcato/repo-tooling fix vitest` to add a test runner');
+    }
+    if (config.projectType === 'library' && !config.treeshakeCheck) {
+        suggestions.push('Run `npx @rtorcato/repo-tooling fix treeshake-check` to add an esbuild-based tree-shake assertion');
+    }
+    suggestions.push('Run `npx @rtorcato/repo-tooling doctor` any time to audit drift');
+    return suggestions;
+}

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

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { copyPreset, getPackageRoot } from '../utils/copy-preset.js';
+import { installSkillsInstallDocs } from './skills-install.js';
+/**
+ * All agent rule files are generated from one source of truth — the shipped
+ * Claude skill — so the guidance never drifts between agents. Only the
+ * location and the frontmatter differ per agent.
+ */
+const SOURCE = 'tooling/claude/repo-tooling.md';
+const BLOCK_START = '<!-- js-tooling:start -->';
+const BLOCK_END = '<!-- js-tooling:end -->';
+/** 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');
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!match)
+        return { description: '', body: raw.trim() };
+    const description = ((match[1] ?? '').match(/^description:\s*(.+)$/m)?.[1] ?? '').trim();
+    return { description, body: (match[2] ?? '').trim() };
+}
+/**
+ * Upsert a delimited js-tooling block into a file that may already hold the
+ * consumer's own content (AGENTS.md, copilot-instructions). Replaces an
+ * existing block, appends if the file exists without one, creates otherwise.
+ * Never clobbers surrounding content.
+ */
+export async function upsertBlock(filePath, body, markers = { start: BLOCK_START, end: BLOCK_END }) {
+    const { start: startMarker, end: endMarker } = markers;
+    const block = `${startMarker}\n${body}\n${endMarker}`;
+    if (await fs.pathExists(filePath)) {
+        const existing = await fs.readFile(filePath, 'utf8');
+        const start = existing.indexOf(startMarker);
+        const end = existing.indexOf(endMarker);
+        if (start !== -1 && end !== -1) {
+            const next = existing.slice(0, start) + block + existing.slice(end + endMarker.length);
+            await fs.writeFile(filePath, next);
+            return;
+        }
+        await fs.writeFile(filePath, `${existing.trimEnd()}\n\n${block}\n`);
+        return;
+    }
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, `${block}\n`);
+}
+/**
+ * Write CLAUDE.md as a thin pointer to AGENTS.md rather than duplicating the
+ * guidance — Claude Code reads both, and `@AGENTS.md` keeps a single source of
+ * truth. Merge-safe: only the delimited block is touched.
+ */
+export async function installClaudeMd(targetDir) {
+    const rel = 'CLAUDE.md';
+    const body = 'See @AGENTS.md for project and agent guidance (kept in sync by `repo-tooling fix ai`).';
+    await upsertBlock(path.join(targetDir, rel), body);
+    return rel;
+}
+/**
+ * Umbrella: install every AI agent file in one pass — AGENTS.md, the CLAUDE.md
+ * pointer, Cursor + Copilot rules, the Claude skill, and the commented MCP
+ * template. All are merge-safe or `.example`, so re-running is idempotent.
+ * Returns the written paths (relative to targetDir).
+ */
+export async function installAiSetup(targetDir) {
+    const written = [];
+    written.push(await installAgentRules(targetDir, 'agents-md'));
+    written.push(await installClaudeMd(targetDir));
+    written.push(await installAgentRules(targetDir, 'cursor'));
+    written.push(await installAgentRules(targetDir, 'copilot'));
+    written.push((await copyPreset('claude-skill', targetDir)).target);
+    written.push((await copyPreset('mcp-example', targetDir)).target);
+    // 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);
+    if (skillsDoc)
+        written.push(skillsDoc);
+    return written;
+}
+/** Install the repo-tooling rules for one agent. Returns the written path (relative). */
+export async function installAgentRules(targetDir, agent) {
+    const { description, body } = await readSkill();
+    switch (agent) {
+        case 'cursor': {
+            const rel = path.join('.cursor', 'rules', 'repo-tooling.mdc');
+            const file = path.join(targetDir, rel);
+            const frontmatter = `---\ndescription: ${description}\nglobs:\nalwaysApply: false\n---\n\n`;
+            await fs.ensureDir(path.dirname(file));
+            await fs.writeFile(file, `${frontmatter}${body}\n`);
+            // Remove the pre-rename rule so a re-run migrates it instead of leaving both.
+            await fs.remove(path.join(targetDir, '.cursor', 'rules', 'js-tooling.mdc'));
+            return rel;
+        }
+        case 'copilot': {
+            const rel = path.join('.github', 'copilot-instructions.md');
+            await upsertBlock(path.join(targetDir, rel), body);
+            return rel;
+        }
+        case 'agents-md': {
+            const rel = 'AGENTS.md';
+            await upsertBlock(path.join(targetDir, rel), body);
+            return rel;
+        }
+    }
+}