@enfocussw/switch-scripting-context 0.1.0

package/dist/init.js

@@ -0,0 +1,894 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRoutingTable = parseRoutingTable;
+exports.apiFiles = apiFiles;
+exports.parseKeyRules = parseKeyRules;
+exports.prefixDocPaths = prefixDocPaths;
+exports.generateAgentsMd = generateAgentsMd;
+exports.generateGeminiMd = generateGeminiMd;
+exports.generateWindsurfRules = generateWindsurfRules;
+exports.generateZedRules = generateZedRules;
+exports.generateClineRules = generateClineRules;
+exports.generateContinueRule = generateContinueRule;
+exports.generateAiderConf = generateAiderConf;
+exports.aiderReadConflict = aiderReadConflict;
+exports.buildIdMap = buildIdMap;
+exports.findMarkerRange = findMarkerRange;
+exports.packageVersion = packageVersion;
+exports.versionStamp = versionStamp;
+exports.stripGitignoreEntry = stripGitignoreEntry;
+exports.run = run;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+// ─── Markers ─────────────────────────────────────────────────────────────────
+const MARKER_BEGIN = '<!-- switch-scripting-context begin -->';
+const MARKER_END = '<!-- switch-scripting-context end -->';
+const HTML_MARKERS = { begin: MARKER_BEGIN, end: MARKER_END };
+// YAML has no HTML comments, so a YAML config file marks its section with # comments instead.
+const YAML_MARKERS = {
+    begin: '# switch-scripting-context begin',
+    end: '# switch-scripting-context end',
+};
+// ─── Shared content (single source of truth for all generated tool files) ────
+/** Package root, whether running from src/ (ts-node) or dist/. */
+function packageRoot() {
+    return path.resolve(__dirname, '..');
+}
+/**
+ * The routing table in docs/switch-scripting.md is the single source of truth for
+ * which API docs exist and when to load each one. Everything the CLI generates is
+ * derived from it, so a new doc file needs registering in exactly one place here
+ * (plus README.md, which init.test.ts checks).
+ */
+function parseRoutingTable(root = packageRoot()) {
+    const hub = fs.readFileSync(path.join(root, 'docs', 'switch-scripting.md'), 'utf8');
+    const docs = [];
+    for (const line of hub.split('\n')) {
+        // | `<switch-api|switch-project|switch-appstore>/<file>.md` | <contents> | <load when> |
+        const m = /^\|\s*`(switch-api|switch-project|switch-appstore)\/([a-z0-9-]+\.md)`\s*\|(.*)\|(.*)\|\s*$/.exec(line);
+        if (m)
+            docs.push({ file: `${m[1]}/${m[2]}`, loadWhen: m[4].trim() });
+    }
+    if (docs.length === 0) {
+        throw new Error('No API docs found in docs/switch-scripting.md — the routing table format changed. ' +
+            'Generated tool config would be empty; fix parseRoutingTable() before publishing.');
+    }
+    return docs;
+}
+/** Filenames only, in routing-table order. */
+function apiFiles(root) {
+    return parseRoutingTable(root).map(d => d.file);
+}
+/**
+ * The bullets under "## Key rules" in docs/switch-scripting.md, verbatim. Like the routing table,
+ * the hub is the single source: tools that get the rules inlined see exactly what the hub says.
+ */
+function parseKeyRules(root = packageRoot()) {
+    const hub = fs.readFileSync(path.join(root, 'docs', 'switch-scripting.md'), 'utf8');
+    const m = /^## Key rules\n([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(hub);
+    const rules = m ? m[1].trim() : '';
+    if (!rules.startsWith('- ')) {
+        throw new Error('No "## Key rules" list found in docs/switch-scripting.md. Inlined tool config would have ' +
+            'no rules; fix parseKeyRules() before publishing.');
+    }
+    return rules;
+}
+/**
+ * Rewrites each backticked doc path (`switch-api/job.md`, `switch-project/`) to start with the
+ * docs folder, so it resolves from the project root rather than from the hub's own folder.
+ */
+function prefixDocPaths(text, docsDir) {
+    return text.replace(/`((?:switch-api|switch-project|switch-appstore)\/[^`]*)`/g, (_, p) => `\`${docsDir}/${p}\``);
+}
+/**
+ * Key rules for a tool that can't import the hub. Doc paths in the hub are relative to the docs
+ * folder, so they get the docs folder prefixed to resolve from the project root.
+ */
+function inlineCoreRules(docsDir) {
+    const rules = prefixDocPaths(parseKeyRules(), docsDir);
+    // The hub states the read-first rule above its table; this list form needs its own wording.
+    return `## Core rules
+
+- Read the matching file from the API reference list below before answering any question about Switch scripting, not only before writing code, including short and yes/no questions. These rules only summarise; Switch often differs from what general Node.js knowledge suggests.
+${rules}`;
+}
+// ─── Content generators ──────────────────────────────────────────────────────
+// Claude Code and Gemini CLI resolve @file imports themselves, so their generated
+// block is just a pointer to switch-scripting.md; the routing table and key rules
+// living there are the actual instructions. Codex, Windsurf, Zed, Cline, and Continue
+// don't reliably follow that import syntax, so their generators (generateInlineBlock)
+// paste the hub's key rules and routing table directly into the generated file
+// instead. Aider has no instructions file at all; its config loads the hub as a
+// read-only file. Don't collapse these into one shared generator; the split is
+// deliberate, not duplication.
+function generateClaudeMd(docsDir) {
+    return `${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+@${docsDir}/switch-scripting.md
+${MARKER_END}`;
+}
+function generateCopilotInstructions(docsDir) {
+    return `${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+This project uses Enfocus Switch scripting (Node.js/TypeScript).
+Consult the Switch scripting reference before answering questions about Switch scripting or writing or modifying code.
+
+#file:../${docsDir}/switch-scripting.md
+${MARKER_END}`;
+}
+function generateCopilotScopedInstructions(docsDir) {
+    return `---
+applyTo: "**/*.ts"
+---
+${MARKER_BEGIN}
+You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
+
+#file:../../${docsDir}/switch-scripting.md
+${MARKER_END}`;
+}
+// alwaysApply keeps the rules in context for questions too. Globs alone attach them only when a
+// matching file is in the chat.
+function generateCursorMdc(docsDir) {
+    return `---
+description: Enfocus Switch scripting rules and API reference for Node.js/TypeScript scripts
+alwaysApply: true
+---
+
+${MARKER_BEGIN}
+You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
+
+${inlineCoreRules(docsDir)}
+
+## API reference
+
+Load the file matching the task below. \`${docsDir}/switch-scripting.md\` repeats these rules and
+this index, and adds a short summary of the execution environment:
+
+${inlineApiFileList(docsDir)}
+${MARKER_END}`;
+}
+// ─── Inline block (for tools without @file import support) ──────────────────
+function inlineApiFileList(docsDir) {
+    return parseRoutingTable()
+        .map(d => `- \`${docsDir}/${d.file}\` — ${d.loadWhen}`)
+        .join('\n');
+}
+function generateInlineBlock(docsDir) {
+    return `You are working on an Enfocus Switch scripting project (Node.js/TypeScript).
+
+${inlineCoreRules(docsDir)}
+
+## API reference
+
+Load the file matching the task below. \`${docsDir}/switch-scripting.md\` repeats these rules and
+this index, and adds a short summary of the execution environment:
+
+${inlineApiFileList(docsDir)}`;
+}
+function generateAgentsMd(docsDir) {
+    return `${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+${generateInlineBlock(docsDir)}
+${MARKER_END}`;
+}
+function generateGeminiMd(docsDir) {
+    return `${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+@${docsDir}/switch-scripting.md
+${MARKER_END}`;
+}
+function generateWindsurfRules(docsDir) {
+    return `${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+${generateInlineBlock(docsDir)}
+${MARKER_END}`;
+}
+function generateZedRules(docsDir) {
+    return `${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+${generateInlineBlock(docsDir)}
+${MARKER_END}`;
+}
+function generateClineRules(docsDir) {
+    return `${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+${generateInlineBlock(docsDir)}
+${MARKER_END}`;
+}
+// Continue reads every Markdown file in .continue/rules/. alwaysApply keeps the rules in context
+// for questions too, not only when a matching file is open.
+function generateContinueRule(docsDir) {
+    return `---
+name: Switch scripting
+description: Enfocus Switch scripting rules and API reference for Node.js/TypeScript scripts
+alwaysApply: true
+---
+
+${MARKER_BEGIN}
+## Switch Scripting (Enfocus Switch)
+
+${generateInlineBlock(docsDir)}
+${MARKER_END}`;
+}
+// Aider resolves a relative read path against the folder it was started from, not the git root,
+// so this entry only works when Aider starts at the project root.
+function generateAiderConf(docsDir) {
+    return `${YAML_MARKERS.begin}
+read:
+  - ${docsDir}/switch-scripting.md
+${YAML_MARKERS.end}`;
+}
+/**
+ * A second top-level read key would not merge with the user's own: Aider keeps only the last
+ * one, so appending ours would silently drop every file the user already loads.
+ */
+function aiderReadConflict(existing, docsDir) {
+    if (!/^read\s*:/m.test(existing))
+        return null;
+    return `it already has a read: key. Add ${docsDir}/switch-scripting.md to that list yourself.`;
+}
+// ─── Tool registry ───────────────────────────────────────────────────────────
+const TOOL_REGISTRY = [
+    {
+        id: 'claude',
+        label: 'Claude Code',
+        aliases: ['ClawCode'],
+        altIds: ['clawcode'],
+        files: [
+            {
+                targetPath: (root) => path.join(root, 'CLAUDE.md'),
+                generate: generateClaudeMd,
+            },
+        ],
+    },
+    {
+        id: 'copilot',
+        label: 'GitHub Copilot',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.github', 'copilot-instructions.md'),
+                generate: generateCopilotInstructions,
+            },
+            {
+                targetPath: (root) => path.join(root, '.github', 'instructions', 'switch-scripting.instructions.md'),
+                generate: generateCopilotScopedInstructions,
+            },
+        ],
+    },
+    {
+        id: 'cursor',
+        label: 'Cursor',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.cursor', 'rules', 'switch-scripting.mdc'),
+                generate: generateCursorMdc,
+                previousFrontmatter: [
+                    '---\ndescription: Enfocus Switch scripting rules and API reference for Node.js/TypeScript scripts\n' +
+                        'globs: ["**/*.ts", "**/*.js"]\nalwaysApply: false\n---',
+                ],
+            },
+        ],
+    },
+    {
+        id: 'codex',
+        label: 'Codex CLI / OpenCode / Pi',
+        altIds: ['opencode', 'pi'],
+        files: [
+            {
+                targetPath: (root) => path.join(root, 'AGENTS.md'),
+                generate: generateAgentsMd,
+            },
+        ],
+    },
+    {
+        id: 'gemini',
+        label: 'Gemini CLI',
+        files: [
+            {
+                targetPath: (root) => path.join(root, 'GEMINI.md'),
+                generate: generateGeminiMd,
+            },
+        ],
+    },
+    {
+        id: 'windsurf',
+        label: 'Windsurf',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.windsurfrules'),
+                generate: generateWindsurfRules,
+            },
+        ],
+    },
+    {
+        id: 'zed',
+        label: 'Zed',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.rules'),
+                generate: generateZedRules,
+            },
+        ],
+    },
+    {
+        id: 'cline',
+        label: 'Cline',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.clinerules'),
+                generate: generateClineRules,
+            },
+        ],
+    },
+    {
+        id: 'continue',
+        label: 'Continue',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.continue', 'rules', 'switch-scripting.md'),
+                generate: generateContinueRule,
+            },
+        ],
+    },
+    {
+        id: 'aider',
+        label: 'Aider',
+        files: [
+            {
+                targetPath: (root) => path.join(root, '.aider.conf.yml'),
+                generate: generateAiderConf,
+                markers: YAML_MARKERS,
+                appendConflict: aiderReadConflict,
+            },
+        ],
+    },
+];
+// ─── ID map ──────────────────────────────────────────────────────────────────
+function buildIdMap(registry) {
+    const map = new Map();
+    for (const t of registry) {
+        map.set(t.id, t.id);
+        for (const alt of t.altIds ?? [])
+            map.set(alt, t.id);
+    }
+    return map;
+}
+// ─── Merge logic ─────────────────────────────────────────────────────────────
+function findMarkerRange(content, markers = HTML_MARKERS) {
+    const begin = content.indexOf(markers.begin);
+    const end = content.indexOf(markers.end);
+    if (begin === -1 || end === -1)
+        return null;
+    if (begin >= end)
+        return null;
+    return [begin, end + markers.end.length];
+}
+function resolveFileAction(targetPath, file, docsDir, force) {
+    const block = file.generate(docsDir);
+    const markers = file.markers ?? HTML_MARKERS;
+    if (!fs.existsSync(targetPath)) {
+        return { path: targetPath, action: 'create', content: block };
+    }
+    if (force) {
+        return { path: targetPath, action: 'overwrite', content: block };
+    }
+    const existing = fs.readFileSync(targetPath, 'utf8');
+    const range = findMarkerRange(existing, markers);
+    if (range) {
+        // The Cursor .mdc and Copilot scoped-instructions blocks carry frontmatter above the marker,
+        // and only the marker range is replaced. Writing the block whole would stack a second copy of
+        // that frontmatter on every re-run, so drop one of the two copies.
+        const frontmatter = block.slice(0, block.indexOf(markers.begin)).trim();
+        let before = existing.slice(0, range[0]);
+        let incoming = block;
+        if (frontmatter) {
+            if (ownFrontmatter(file, docsDir).includes(before.replace(/\r\n/g, '\n').trim())) {
+                before = ''; // our own frontmatter from an earlier run; the block's copy replaces it
+            }
+            else {
+                // User-written or user-edited frontmatter, or init appended below the user's own content.
+                // Leave what is there and write only the marker section.
+                incoming = block.slice(block.indexOf(markers.begin));
+            }
+        }
+        const updated = before + incoming + existing.slice(range[1]);
+        return { path: targetPath, action: 'merge-replace', content: updated };
+    }
+    const reason = file.appendConflict?.(existing, docsDir);
+    if (reason) {
+        return { path: targetPath, action: 'skip', content: existing, reason };
+    }
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    return { path: targetPath, action: 'merge-append', content: existing + separator + block + '\n' };
+}
+function applyFileAction(action, dryRun) {
+    const rel = path.relative(process.cwd(), action.path);
+    if (action.action === 'skip') {
+        console.log(`  ${rel} → skipped: ${action.reason}`);
+        return;
+    }
+    const label = action.action === 'create' ? 'created'
+        : action.action === 'overwrite' ? 'overwritten'
+            : action.action === 'merge-replace' ? 'updated (replaced Switch section)'
+                : 'updated (appended Switch section)';
+    if (dryRun) {
+        console.log(`  [dry-run] ${rel} → ${label}`);
+        return;
+    }
+    const dir = path.dirname(action.path);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(action.path, action.content, 'utf8');
+    console.log(`  ${rel} → ${label}`);
+}
+// ─── Docs copy ────────────────────────────────────────────────────────────────
+/** Paths under docs/ that are never shipped to a consuming project. */
+const DOCS_EXCLUDE = ['superpowers', 'temp'];
+function copyDocs(packageRoot, destDir, dryRun) {
+    const src = path.join(packageRoot, 'docs');
+    const rel = path.relative(process.cwd(), destDir);
+    if (dryRun) {
+        if (fs.existsSync(destDir)) {
+            console.log(`  [dry-run] ${rel}/ → wiped (removes files from a previous version, e.g. after a doc was renamed or moved)`);
+        }
+        console.log(`  [dry-run] Copying docs/ → ${rel}/`);
+        return;
+    }
+    // destDir is entirely owned by this tool (see the .gitignore comment it writes), so wiping
+    // it first is safe. Without this, a doc renamed or moved between versions (e.g. a docs/
+    // folder restructuring) would leave the old file behind forever: cpSync only adds/overwrites,
+    // it never removes, and destDir is gitignored so nothing would surface the staleness.
+    if (fs.existsSync(destDir)) {
+        fs.rmSync(destDir, { recursive: true, force: true });
+    }
+    // The published tarball already omits these, but init may run from a git clone.
+    fs.cpSync(src, destDir, {
+        recursive: true,
+        filter: (from) => {
+            const rel = path.relative(src, from);
+            if (!rel)
+                return true;
+            const [top] = rel.split(path.sep);
+            return !DOCS_EXCLUDE.includes(top) && path.basename(from) !== '.DS_Store';
+        },
+    });
+    console.log(`  docs → ${path.relative(process.cwd(), destDir)}/`);
+}
+// ─── Version stamp ───────────────────────────────────────────────────────────
+/** The hub file in the copied docs folder that carries the version stamp. */
+const HUB_FILE = 'switch-scripting.md';
+/** The running package's own version, so a git-clone install stamps what actually ran. */
+function packageVersion(root = packageRoot()) {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+}
+/** The comment init writes as the first line of the copied hub file. */
+function versionStamp(version) {
+    return `<!-- switch-scripting-context ${version} -->`;
+}
+/**
+ * Records which version produced the copied docs, so a consumer can tell what is installed
+ * without having recorded it at install time. Only the copy is stamped: the repo's own
+ * docs/switch-scripting.md is generated output and a stamp there would fight the generator.
+ * copyDocs wipes destDir on every run, so there is never a stale stamp to remove.
+ */
+function stampDocsVersion(packageRoot, destDir, dryRun) {
+    const stamp = versionStamp(packageVersion(packageRoot));
+    const hubPath = path.join(destDir, HUB_FILE);
+    const rel = path.relative(process.cwd(), hubPath);
+    if (dryRun) {
+        console.log(`  [dry-run] ${rel} → first line ${stamp}`);
+        return;
+    }
+    fs.writeFileSync(hubPath, `${stamp}\n${fs.readFileSync(hubPath, 'utf8')}`, 'utf8');
+    console.log(`  ${rel} → stamped ${stamp}`);
+}
+/**
+ * The hub's doc paths are relative to its own folder, but Claude Code and Gemini import it into a
+ * file at the project root, and agents then resolve `switch-api/job.md` from there. In a 72-run
+ * Haiku test almost half the runs began with a failed read of such a path. The copy gets the docs
+ * folder prefixed to every path; the repo's hub keeps the short form the generator writes.
+ */
+function resolveHubPaths(destDir, docsDir, dryRun) {
+    const hubPath = path.join(destDir, HUB_FILE);
+    const rel = path.relative(process.cwd(), hubPath);
+    if (dryRun) {
+        console.log(`  [dry-run] ${rel} → doc paths prefixed with ${docsDir}/`);
+        return;
+    }
+    fs.writeFileSync(hubPath, prefixDocPaths(fs.readFileSync(hubPath, 'utf8'), docsDir), 'utf8');
+    console.log(`  ${rel} → doc paths prefixed with ${docsDir}/`);
+}
+// ─── Legacy docs folder ──────────────────────────────────────────────────────
+/** Docs folder name written by versions before the rename to docs-for-agents. */
+const LEGACY_DOCS_DIR = 'switch-docs';
+/**
+ * Delete the docs folder an older version wrote under its old name.
+ *
+ * init regenerates every AI config block in place, so after an upgrade the configs point at
+ * the new folder and nothing reads the old one. It is gitignored, so nothing surfaces it
+ * either, but an agent grepping the project still finds and loads the stale copy. The folder
+ * is only removed when it holds the hub file init writes, so a folder of the same name that
+ * this tool did not create is left alone.
+ */
+function removeLegacyDocsDir(targetRoot, docsDir, dryRun) {
+    if (docsDir === LEGACY_DOCS_DIR)
+        return;
+    const legacyDir = path.join(targetRoot, LEGACY_DOCS_DIR);
+    if (!fs.existsSync(path.join(legacyDir, HUB_FILE)))
+        return;
+    if (dryRun) {
+        console.log(`  [dry-run] ${LEGACY_DOCS_DIR}/ → deleted (docs folder from an earlier version)`);
+    }
+    else {
+        fs.rmSync(legacyDir, { recursive: true, force: true });
+        console.log(`  ${LEGACY_DOCS_DIR}/ → deleted (docs folder from an earlier version)`);
+    }
+    removeGitignoreEntry(targetRoot, LEGACY_DOCS_DIR, dryRun);
+}
+// ─── .gitignore update ───────────────────────────────────────────────────────
+function updateGitignore(targetRoot, docsDir, dryRun) {
+    const gitignorePath = path.join(targetRoot, '.gitignore');
+    const entry = `\n# switch-scripting-context (AI context docs — re-generate with npx switch-scripting-context init)\n${docsDir}/\n`;
+    if (!fs.existsSync(gitignorePath))
+        return;
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    if (content.includes(`${docsDir}/`))
+        return;
+    if (dryRun) {
+        console.log(`  [dry-run] .gitignore → append ${docsDir}/ entry`);
+        return;
+    }
+    // entry opens with its own blank-line separator, so normalise what the file already
+    // ends with. Without this, appending after an entry that was just removed leaves a
+    // widening gap in the file on every upgrade.
+    fs.writeFileSync(gitignorePath, content.replace(/\n*$/, '\n') + entry, 'utf8');
+    console.log(`  .gitignore → appended ${docsDir}/ entry`);
+}
+/** AI config files that init may have created, for all tools or only the given tool ids. */
+function aiConfigFiles(targetRoot, docsDir, tools) {
+    return TOOL_REGISTRY
+        .filter(t => !tools || tools.includes(t.id))
+        .flatMap(t => t.files.map(file => ({ filePath: file.targetPath(targetRoot, docsDir), file })));
+}
+/** The frontmatter a generator writes above the marker, trimmed; empty if it writes none. */
+function generatedFrontmatter(file, docsDir) {
+    const generated = file.generate(docsDir);
+    return generated.slice(0, generated.indexOf((file.markers ?? HTML_MARKERS).begin)).trim();
+}
+/** Frontmatter init writes now or wrote in an earlier version. Empty when the file has none. */
+function ownFrontmatter(file, docsDir) {
+    const current = generatedFrontmatter(file, docsDir);
+    return current ? [current, ...(file.previousFrontmatter ?? [])] : [];
+}
+/** Deletes now-empty folders from dir upwards, stopping at targetRoot. */
+function removeEmptyDirs(dir, targetRoot) {
+    while (dir !== targetRoot && dir.startsWith(targetRoot + path.sep) && fs.readdirSync(dir).length === 0) {
+        fs.rmdirSync(dir);
+        dir = path.dirname(dir);
+    }
+}
+function removeAiConfig(filePath, file, docsDir, targetRoot, dryRun) {
+    if (!fs.existsSync(filePath))
+        return;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const eol = raw.includes('\r\n') ? '\r\n' : '\n';
+    const content = raw.replace(/\r\n/g, '\n');
+    const range = findMarkerRange(content, file.markers);
+    if (!range)
+        return; // nothing from us in this file
+    const rel = path.relative(process.cwd(), filePath);
+    let before = content.slice(0, range[0]).trim();
+    const after = content.slice(range[1]).trim();
+    // Copilot scoped instructions, Cursor .mdc, and Continue rules put frontmatter above the marker. Only an exact
+    // copy of what the generator writes counts as ours; edited or user-written frontmatter stays.
+    for (const ours of ownFrontmatter(file, docsDir)) {
+        if (before === ours) {
+            before = '';
+            break;
+        }
+        if (before.endsWith('\n' + ours)) {
+            // init appended our block, frontmatter included, below the user's own content
+            before = before.slice(0, -ours.length).trim();
+            break;
+        }
+    }
+    if (!before && !after) {
+        // File is entirely our content — delete it
+        if (dryRun) {
+            console.log(`  [dry-run] ${rel} → deleted`);
+            return;
+        }
+        fs.unlinkSync(filePath);
+        removeEmptyDirs(path.dirname(filePath), targetRoot);
+        console.log(`  ${rel} → deleted`);
+    }
+    else {
+        // File has other content — strip our section
+        const stripped = (before ? before + '\n' : '') + (after ? '\n' + after + '\n' : '');
+        if (dryRun) {
+            console.log(`  [dry-run] ${rel} → removed Switch section`);
+            return;
+        }
+        fs.writeFileSync(filePath, stripped.replace(/\n/g, eol), 'utf8');
+        console.log(`  ${rel} → removed Switch section`);
+    }
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Drop the `docsDir/` line init added, together with the comment line directly above it.
+ * The comment and the path are matched as one unit so that a project carrying entries for
+ * two docs folders (one left by an older version, one current) keeps the comment belonging
+ * to the entry that stays.
+ */
+function stripGitignoreEntry(content, docsDir) {
+    const pattern = new RegExp(`(\n# switch-scripting-context \\(AI context docs[^\n]*\\))?\n${escapeRegExp(docsDir)}/\n`, 'g');
+    return content.replace(pattern, '\n');
+}
+function removeGitignoreEntry(targetRoot, docsDir, dryRun) {
+    const gitignorePath = path.join(targetRoot, '.gitignore');
+    if (!fs.existsSync(gitignorePath))
+        return;
+    const content = fs.readFileSync(gitignorePath, 'utf8');
+    const updated = stripGitignoreEntry(content, docsDir);
+    if (updated === content)
+        return;
+    if (dryRun) {
+        console.log(`  [dry-run] .gitignore → removed ${docsDir}/ entry`);
+        return;
+    }
+    fs.writeFileSync(gitignorePath, updated, 'utf8');
+    console.log(`  .gitignore → removed ${docsDir}/ entry`);
+}
+function remove(options) {
+    const targetRoot = process.cwd();
+    const docsDestDir = path.join(targetRoot, options.docsDir);
+    if (options.dryRun)
+        console.log('\nDry run — no files will be written.\n');
+    const tools = options.tools;
+    const partial = tools && !TOOL_REGISTRY.every(t => tools.includes(t.id));
+    if (partial) {
+        // Removing some tools leaves the rest configured, and they still reference the docs folder.
+        // Listing every tool leaves nothing referencing it, so that falls through to a full remove.
+        console.log('Cleaning AI config files...');
+        for (const { filePath, file } of aiConfigFiles(targetRoot, options.docsDir, options.tools)) {
+            removeAiConfig(filePath, file, options.docsDir, targetRoot, options.dryRun);
+        }
+        console.log('\nDone.\n');
+        return;
+    }
+    // 1. Remove docs dir
+    console.log('Removing docs...');
+    if (fs.existsSync(docsDestDir)) {
+        if (options.dryRun) {
+            console.log(`  [dry-run] ${options.docsDir}/ → deleted`);
+        }
+        else {
+            fs.rmSync(docsDestDir, { recursive: true, force: true });
+            console.log(`  ${options.docsDir}/ → deleted`);
+        }
+    }
+    else {
+        console.log(`  ${options.docsDir}/ → not found, skipping`);
+    }
+    removeLegacyDocsDir(targetRoot, options.docsDir, options.dryRun);
+    // 2. Remove AI config sections / files
+    console.log('\nCleaning AI config files...');
+    for (const { filePath, file } of aiConfigFiles(targetRoot, options.docsDir)) {
+        removeAiConfig(filePath, file, options.docsDir, targetRoot, options.dryRun);
+    }
+    // 3. Update .gitignore
+    console.log('\nUpdating .gitignore...');
+    removeGitignoreEntry(targetRoot, options.docsDir, options.dryRun);
+    console.log('\nDone.\n');
+}
+// ─── Main init ───────────────────────────────────────────────────────────────
+function init(options) {
+    const targetRoot = process.cwd();
+    const packageRoot = path.resolve(__dirname, '..');
+    const docsDestDir = path.join(targetRoot, options.docsDir);
+    if (options.dryRun)
+        console.log('\nDry run — no files will be written.\n');
+    // 1. Copy docs
+    console.log('Copying docs...');
+    removeLegacyDocsDir(targetRoot, options.docsDir, options.dryRun);
+    copyDocs(packageRoot, docsDestDir, options.dryRun);
+    stampDocsVersion(packageRoot, docsDestDir, options.dryRun);
+    resolveHubPaths(docsDestDir, options.docsDir, options.dryRun);
+    // 2. Generate AI config files
+    const toolActions = [];
+    for (const toolDef of TOOL_REGISTRY) {
+        if (!options.tools.includes(toolDef.id))
+            continue;
+        for (const f of toolDef.files) {
+            toolActions.push({ targetPath: f.targetPath(targetRoot, options.docsDir), file: f });
+        }
+    }
+    if (toolActions.length > 0) {
+        console.log('\nGenerating AI config files...');
+        for (const { targetPath, file } of toolActions) {
+            const action = resolveFileAction(targetPath, file, options.docsDir, options.force);
+            applyFileAction(action, options.dryRun);
+        }
+    }
+    // 3. Update .gitignore
+    console.log('\nUpdating .gitignore...');
+    updateGitignore(targetRoot, options.docsDir, options.dryRun);
+    console.log('\nDone. Re-run after upgrading switch-scripting-context to refresh docs and config.\n');
+}
+// ─── CLI arg parsing ──────────────────────────────────────────────────────────
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const subcommand = args[0] ?? 'help';
+    let toolsExplicit = false;
+    const initOptions = {
+        tools: TOOL_REGISTRY.map(t => t.id),
+        docsDir: 'docs-for-agents',
+        force: false,
+        dryRun: false,
+    };
+    const removeOptions = {
+        docsDir: 'docs-for-agents',
+        dryRun: false,
+    };
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--force') {
+            initOptions.force = true;
+        }
+        else if (arg === '--dry-run') {
+            initOptions.dryRun = true;
+            removeOptions.dryRun = true;
+        }
+        else if (arg === '--tools' && args[i + 1]) {
+            const idMap = buildIdMap(TOOL_REGISTRY);
+            const raw = args[++i].split(',').map(s => s.trim());
+            const invalid = raw.filter(t => !idMap.has(t));
+            if (invalid.length > 0) {
+                const allValid = [...idMap.keys()].sort().join(', ');
+                console.error(`Unknown tool(s): ${invalid.join(', ')}. Valid values: ${allValid}`);
+                process.exit(1);
+            }
+            initOptions.tools = raw.map(t => idMap.get(t));
+            removeOptions.tools = initOptions.tools;
+            toolsExplicit = true;
+        }
+        else if (arg === '--docs-dir' && args[i + 1]) {
+            initOptions.docsDir = args[++i];
+            removeOptions.docsDir = initOptions.docsDir;
+        }
+        else if (arg.startsWith('--')) {
+            console.error(`Unknown option: ${arg}`);
+            process.exit(1);
+        }
+    }
+    return { subcommand, initOptions, removeOptions, toolsExplicit };
+}
+// ─── Interactive tool prompt ──────────────────────────────────────────────────
+function toolPromptLabel(t) {
+    if (t.aliases && t.aliases.length > 0) {
+        return `${t.label}  (also covers ${t.aliases.join(', ')})`;
+    }
+    return t.label;
+}
+async function promptTools() {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    console.log('\nWhich coding agent(s) do you use?');
+    console.log('Enter numbers separated by spaces (or press Enter to select all):\n');
+    TOOL_REGISTRY.forEach((t, i) => console.log(`  ${i + 1}) ${toolPromptLabel(t)}`));
+    console.log();
+    return new Promise((resolve) => {
+        rl.question('> ', (answer) => {
+            rl.close();
+            const trimmed = answer.trim();
+            if (!trimmed) {
+                resolve(TOOL_REGISTRY.map(t => t.id));
+                return;
+            }
+            const indices = trimmed.split(/[\s,]+/).map(n => parseInt(n, 10) - 1);
+            const valid = indices.filter(i => i >= 0 && i < TOOL_REGISTRY.length);
+            if (valid.length === 0) {
+                resolve(TOOL_REGISTRY.map(t => t.id));
+                return;
+            }
+            resolve(valid.map(i => TOOL_REGISTRY[i].id));
+        });
+    });
+}
+function printHelp() {
+    console.log(`
+Usage: switch-scripting-context <command> [options]
+
+Commands:
+  init      Copy docs and generate AI context config files
+  remove    Remove files and config added by init (all of it, or only some tools' config)
+
+Options (init):
+  --tools <list>    Comma-separated tools to configure
+                    IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline,
+                         continue, aider
+                    Aliases: opencode, pi (→ codex), clawcode (→ claude)
+                    Default: all tools
+  --docs-dir <dir>  Destination folder for docs in target project (default: docs-for-agents)
+  --force           Overwrite existing AI config files rather than merging
+  --dry-run         Print what would happen without writing any files
+  --help            Show this help message
+
+Options (remove):
+  --tools <list>    Only remove these tools' config; keeps the docs folder and other tools
+                    Default: remove everything, same as listing every tool
+  --docs-dir <dir>  Docs folder to remove (default: docs-for-agents)
+  --dry-run         Print what would happen without writing any files
+
+Examples:
+  npx switch-scripting-context init
+  npx switch-scripting-context init --tools claude,copilot
+  npx switch-scripting-context init --docs-dir ai-docs --dry-run
+  npx switch-scripting-context remove
+  npx switch-scripting-context remove --dry-run
+  npx switch-scripting-context remove --tools cursor
+`);
+}
+// ─── Entry point ─────────────────────────────────────────────────────────────
+async function run(argv = process.argv) {
+    const { subcommand, initOptions, removeOptions, toolsExplicit } = parseArgs(argv);
+    if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+        printHelp();
+    }
+    else if (subcommand === 'init') {
+        if (!toolsExplicit) {
+            initOptions.tools = await promptTools();
+        }
+        init(initOptions);
+    }
+    else if (subcommand === 'remove') {
+        remove(removeOptions);
+    }
+    else {
+        console.error(`Unknown command: ${subcommand}`);
+        printHelp();
+        process.exit(1);
+    }
+}