frontmcp 1.2.1 → 1.4.0

package/src/commands/build/exec/cli-runtime/plugin-emitter.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Plugin emitter for issue #411 — turn a FrontMCP server's metadata into
+ * a Claude Code plugin folder (`.claude/plugins/<bin>/`) or a Codex
+ * `mcp_servers` entry. Shared by the dev-tool `frontmcp install` command
+ * and the per-bin `<bin> install -p claude|codex` command.
+ *
+ * Design constraints (from planning/issues/411.md):
+ *  - Pure helper module — no side-effects at import time.
+ *  - All filesystem ops go through `@frontmcp/utils`.
+ *  - Re-running install must be idempotent: managed files tracked in
+ *    `_meta.frontmcp.managedFiles`; user-added files in the plugin
+ *    directory are NEVER deleted.
+ *  - Manifest written deterministically (sorted keys, fixed spacing) so
+ *    snapshots are stable and re-runs are no-ops when nothing changed.
+ *  - Codex emitter writes a TOML fragment without pulling in a TOML
+ *    dependency — only the `[[mcp_servers]]` shape is needed.
+ */
+export interface PluginEmitterSkillInput {
+    name: string;
+    description: string;
+    /**
+     * Tags from `@Skill({ tags })`. Forwarded into the synthesized SKILL.md
+     * frontmatter so Claude Code's filesystem loader can index by tag.
+     */
+    tags?: string[];
+    /** License from `@Skill({ license })`. Forwarded into the synthesized frontmatter. */
+    license?: string;
+    /** Absolute path to SKILL.md. When missing, only frontmatter is emitted. */
+    instructionFile?: string;
+    /** Absolute paths to the skill's resource subdirectories. */
+    resourceDirs?: {
+        references?: string;
+        examples?: string;
+        scripts?: string;
+        assets?: string;
+    };
+}
+export interface PluginEmitterCommandInput {
+    /** Slash-command name without leading `/`. */
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+export interface EmitClaudePluginOptions {
+    /** Root dir under which `<name>/` will be created. */
+    destRoot: string;
+    name: string;
+    version: string;
+    description: string;
+    /** MCP server invocation command (e.g. the bin name, or `node ./dist/main.js`). */
+    mcpCommand: string;
+    /** Typically `['serve', '--stdio']`. */
+    mcpArgs: string[];
+    /** Env-var names (placeholder values) to surface in `mcpServers.<bin>.env`. */
+    envHints: string[];
+    skills: PluginEmitterSkillInput[];
+    commands: PluginEmitterCommandInput[];
+    /** Used for `_meta.frontmcp.installedBy`. */
+    cliVersion: string;
+    /** If true: plan only, do not write. */
+    dryRun?: boolean;
+}
+export interface EmitClaudePluginResult {
+    pluginDir: string;
+    manifest: ClaudePluginManifest;
+    /** Absolute paths written (or that WOULD be written when dryRun). */
+    filesWritten: string[];
+    /** Absolute paths of pre-existing user files left in place. */
+    filesPreserved: string[];
+    /** Managed files from a previous install that were removed this run. */
+    filesRemoved: string[];
+}
+export interface ClaudePluginManifest {
+    name: string;
+    version: string;
+    description: string;
+    mcpServers: Record<string, McpServerEntry>;
+    skills: string[];
+    commands?: string[];
+    _meta: {
+        frontmcp: {
+            installedBy: string;
+            installedAt: string;
+            bin: string;
+            binVersion: string;
+            managedFields: string[];
+            managedFiles: string[];
+        };
+    };
+}
+export interface McpServerEntry {
+    command: string;
+    args: string[];
+    transport?: 'stdio';
+    env?: Record<string, string>;
+}
+export interface EmitCodexOptions {
+    /** `~/.codex/config.toml` typically. */
+    configPath: string;
+    name: string;
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    dryRun?: boolean;
+}
+export interface EmitCodexResult {
+    written: boolean;
+    previousVersion?: string;
+    /** Final TOML content (or what would be written when dryRun). */
+    configContent: string;
+}
+/**
+ * Validate a plugin name before it touches the filesystem or TOML blocks.
+ * Rejects anything that could traverse out of the destination directory,
+ * inject newlines into the codex block markers (`# frontmcp:codex-start:<name>`
+ * / `# frontmcp:codex-end:<name>` — finding from #411 review), or smuggle
+ * TOML-significant characters past the `tomlString` quoting.
+ *
+ * The allowed set is intentionally narrow — npm-style scoped names
+ * (`@scope/name`) are NOT allowed since the `@` and `/` characters would
+ * still produce surprising directory layouts. Callers that need scoped
+ * names should sanitise first.
+ */
+/**
+ * Validate a slash-command name (frontmatter / body content). Same rules
+ * as `assertValidPluginName` so a malicious command name cannot inject
+ * YAML directives or new markdown sections via interpolated body text
+ * in `renderCommandFile`.
+ */
+export declare function assertValidCommandName(name: string, where: string): void;
+export declare function assertValidPluginName(name: string, where: string): void;
+/**
+ * Returns true when `rel` resolves to a path strictly inside `pluginDir`.
+ * Defends `emitClaudePlugin` and `removeClaudePlugin` against a tampered
+ * prior `plugin.json` whose `_meta.frontmcp.managedFiles` entries try to
+ * escape the plugin root with `../` traversals or absolute paths.
+ */
+export declare function isPluginContainedPath(pluginDir: string, rel: string): boolean;
+export declare function emitClaudePlugin(opts: EmitClaudePluginOptions): Promise<EmitClaudePluginResult>;
+export declare function removeClaudePlugin(args: {
+    destRoot: string;
+    name: string;
+}): Promise<{
+    removed: string[];
+    preserved: string[];
+    pluginDir: string;
+}>;
+export declare function readInstalledPluginVersion(pluginDir: string): Promise<string | undefined>;
+export declare function emitCodexEntry(opts: EmitCodexOptions): Promise<EmitCodexResult>;
+export declare function removeCodexEntry(args: {
+    configPath: string;
+    name: string;
+}): Promise<{
+    removed: boolean;
+    configContent: string;
+}>;

package/src/commands/build/exec/cli-runtime/plugin-emitter.js

@@ -0,0 +1,512 @@
+"use strict";
+/**
+ * Plugin emitter for issue #411 — turn a FrontMCP server's metadata into
+ * a Claude Code plugin folder (`.claude/plugins/<bin>/`) or a Codex
+ * `mcp_servers` entry. Shared by the dev-tool `frontmcp install` command
+ * and the per-bin `<bin> install -p claude|codex` command.
+ *
+ * Design constraints (from planning/issues/411.md):
+ *  - Pure helper module — no side-effects at import time.
+ *  - All filesystem ops go through `@frontmcp/utils`.
+ *  - Re-running install must be idempotent: managed files tracked in
+ *    `_meta.frontmcp.managedFiles`; user-added files in the plugin
+ *    directory are NEVER deleted.
+ *  - Manifest written deterministically (sorted keys, fixed spacing) so
+ *    snapshots are stable and re-runs are no-ops when nothing changed.
+ *  - Codex emitter writes a TOML fragment without pulling in a TOML
+ *    dependency — only the `[[mcp_servers]]` shape is needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidCommandName = assertValidCommandName;
+exports.assertValidPluginName = assertValidPluginName;
+exports.isPluginContainedPath = isPluginContainedPath;
+exports.emitClaudePlugin = emitClaudePlugin;
+exports.removeClaudePlugin = removeClaudePlugin;
+exports.readInstalledPluginVersion = readInstalledPluginVersion;
+exports.emitCodexEntry = emitCodexEntry;
+exports.removeCodexEntry = removeCodexEntry;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const utils_1 = require("@frontmcp/utils");
+const skill_md_compose_1 = require("./skill-md-compose");
+// ============================================================================
+// Claude plugin emitter
+// ============================================================================
+/**
+ * Validate a plugin name before it touches the filesystem or TOML blocks.
+ * Rejects anything that could traverse out of the destination directory,
+ * inject newlines into the codex block markers (`# frontmcp:codex-start:<name>`
+ * / `# frontmcp:codex-end:<name>` — finding from #411 review), or smuggle
+ * TOML-significant characters past the `tomlString` quoting.
+ *
+ * The allowed set is intentionally narrow — npm-style scoped names
+ * (`@scope/name`) are NOT allowed since the `@` and `/` characters would
+ * still produce surprising directory layouts. Callers that need scoped
+ * names should sanitise first.
+ */
+/**
+ * Validate a slash-command name (frontmatter / body content). Same rules
+ * as `assertValidPluginName` so a malicious command name cannot inject
+ * YAML directives or new markdown sections via interpolated body text
+ * in `renderCommandFile`.
+ */
+function assertValidCommandName(name, where) {
+    assertValidPluginName(name, where);
+}
+function assertValidPluginName(name, where) {
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new Error(`Invalid plugin name passed to ${where}: must be a non-empty string`);
+    }
+    if (name.length > 64) {
+        throw new Error(`Invalid plugin name "${name}" passed to ${where}: must be 64 chars or fewer`);
+    }
+    if (name === '.' || name === '..') {
+        throw new Error(`Invalid plugin name "${name}" passed to ${where}: must not be "." or ".."`);
+    }
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) {
+        throw new Error(`Invalid plugin name "${name}" passed to ${where}: must match /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/ (no slashes, newlines, or special chars)`);
+    }
+}
+/**
+ * Returns true when `rel` resolves to a path strictly inside `pluginDir`.
+ * Defends `emitClaudePlugin` and `removeClaudePlugin` against a tampered
+ * prior `plugin.json` whose `_meta.frontmcp.managedFiles` entries try to
+ * escape the plugin root with `../` traversals or absolute paths.
+ */
+function isPluginContainedPath(pluginDir, rel) {
+    if (typeof rel !== 'string' || rel.length === 0)
+        return false;
+    if (path.isAbsolute(rel))
+        return false;
+    const resolved = path.resolve(pluginDir, rel);
+    const relative = path.relative(pluginDir, resolved);
+    if (relative === '')
+        return false; // never delete the plugin dir itself via a managedFile entry
+    return !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+const FRAMEWORK_MANAGED_FIELDS = [
+    'name',
+    'version',
+    'description',
+    'mcpServers',
+    'skills',
+    'commands',
+    '_meta.frontmcp',
+];
+async function emitClaudePlugin(opts) {
+    assertValidPluginName(opts.name, 'emitClaudePlugin');
+    const pluginDir = path.join(opts.destRoot, opts.name);
+    const claudePluginDir = path.join(pluginDir, '.claude-plugin');
+    const manifestPath = path.join(claudePluginDir, 'plugin.json');
+    // Read prior manifest (idempotency baseline) — file may not exist on first install.
+    const previousManifest = await readPluginManifest(manifestPath);
+    const previouslyManaged = previousManifest?._meta?.frontmcp?.managedFiles ?? [];
+    // Build the new file plan in deterministic order.
+    const plannedFiles = [];
+    // Skills subtree. Validate the name before it lands in a filesystem
+    // path or in synthesized SKILL.md frontmatter — same rules as command
+    // names (issue #411 security pass), so a malicious `@Skill({ name: '../x' })`
+    // can't escape the plugin tree.
+    for (const skill of [...opts.skills].sort((a, b) => a.name.localeCompare(b.name))) {
+        assertValidPluginName(skill.name, 'emitClaudePlugin.skill');
+        const skillDir = path.join(pluginDir, 'skills', skill.name);
+        const skillMd = path.join(skillDir, 'SKILL.md');
+        plannedFiles.push({
+            absPath: skillMd,
+            relPath: path.relative(pluginDir, skillMd),
+            action: async () => {
+                await (0, utils_1.ensureDir)(skillDir);
+                const body = skill.instructionFile && (await (0, utils_1.fileExists)(skill.instructionFile))
+                    ? await (0, utils_1.readFile)(skill.instructionFile)
+                    : '';
+                // The instruction file is typically a raw markdown body authored by
+                // the user; Claude Code's filesystem loader needs YAML frontmatter
+                // with at least `name` + `description`. composeSkillMd preserves a
+                // pre-existing frontmatter block verbatim and otherwise synthesizes
+                // one from the decorator metadata we plumbed through bin-meta.json.
+                await (0, utils_1.writeFile)(skillMd, (0, skill_md_compose_1.composeSkillMd)({ name: skill.name, description: skill.description, tags: skill.tags, license: skill.license }, body));
+            },
+        });
+        for (const kind of ['references', 'examples', 'scripts', 'assets']) {
+            const src = skill.resourceDirs?.[kind];
+            if (!src)
+                continue;
+            const dest = path.join(skillDir, kind);
+            plannedFiles.push({
+                absPath: dest,
+                relPath: path.relative(pluginDir, dest),
+                action: async () => {
+                    await (0, utils_1.ensureDir)(skillDir);
+                    if (await (0, utils_1.fileExists)(src)) {
+                        await (0, utils_1.cp)(src, dest, { recursive: true });
+                    }
+                },
+            });
+        }
+    }
+    // Commands subtree. Validate each command name before it lands in the
+    // markdown body or the filesystem path — same rules as the plugin name.
+    for (const cmd of [...opts.commands].sort((a, b) => a.name.localeCompare(b.name))) {
+        assertValidCommandName(cmd.name, 'emitClaudePlugin.command');
+        const cmdPath = path.join(pluginDir, 'commands', `${cmd.name}.md`);
+        plannedFiles.push({
+            absPath: cmdPath,
+            relPath: path.relative(pluginDir, cmdPath),
+            action: async () => {
+                await (0, utils_1.ensureDir)(path.dirname(cmdPath));
+                await (0, utils_1.writeFile)(cmdPath, renderCommandFile(cmd, opts.name));
+            },
+        });
+    }
+    // Build the manifest. Manifest is itself a managed file and appears last in
+    // managedFiles so removal-on-uninstall happens after subtree cleanup.
+    const newManagedFiles = plannedFiles.map((f) => f.relPath).sort();
+    const manifest = {
+        name: opts.name,
+        version: opts.version,
+        description: opts.description,
+        mcpServers: {
+            [opts.name]: makeMcpServerEntry(opts),
+        },
+        skills: opts.skills.map((s) => s.name).sort(),
+        ...(opts.commands.length > 0 ? { commands: opts.commands.map((c) => c.name).sort() } : {}),
+        _meta: {
+            frontmcp: {
+                installedBy: `frontmcp@${opts.cliVersion}`,
+                installedAt: new Date().toISOString(),
+                bin: opts.name,
+                binVersion: opts.version,
+                managedFields: [...FRAMEWORK_MANAGED_FIELDS].sort(),
+                managedFiles: newManagedFiles,
+            },
+        },
+    };
+    // Merge any user-owned top-level keys back in from the previous manifest.
+    const mergedManifest = mergeUserManifestFields(manifest, previousManifest);
+    // Compute the file delta. We don't `rm -rf` the plugin dir; we only:
+    //   1. Remove previously-managed files that are no longer in newManagedFiles.
+    //   2. Write/overwrite the new managed files.
+    //   3. Write the manifest.
+    const previousSet = new Set(previouslyManaged);
+    const newSet = new Set(newManagedFiles);
+    const removed = [];
+    const written = [];
+    if (!opts.dryRun) {
+        await (0, utils_1.ensureDir)(claudePluginDir);
+        // 1. Drop stale managed files. Guard against a tampered prior manifest
+        // that may have injected escape-paths into `managedFiles`.
+        for (const rel of previousSet) {
+            if (newSet.has(rel))
+                continue;
+            if (!isPluginContainedPath(pluginDir, rel))
+                continue;
+            const abs = path.join(pluginDir, rel);
+            if (await (0, utils_1.fileExists)(abs)) {
+                await (0, utils_1.rm)(abs, { recursive: true, force: true });
+                removed.push(abs);
+            }
+        }
+        // 2. Write new/refreshed managed files.
+        for (const f of plannedFiles) {
+            await f.action();
+            written.push(f.absPath);
+        }
+        // 3. Manifest.
+        await (0, utils_1.writeFile)(manifestPath, serializeManifest(mergedManifest));
+        written.push(manifestPath);
+    }
+    else {
+        written.push(...plannedFiles.map((f) => f.absPath), manifestPath);
+    }
+    const preserved = previousManifest
+        ? Object.keys(previousManifest)
+            .filter((k) => !FRAMEWORK_MANAGED_FIELDS.includes(k) && k !== '_meta')
+            .map((k) => `<plugin.json>.${k}`)
+        : [];
+    return {
+        pluginDir,
+        manifest: mergedManifest,
+        filesWritten: written,
+        filesPreserved: preserved,
+        filesRemoved: removed,
+    };
+}
+async function removeClaudePlugin(args) {
+    assertValidPluginName(args.name, 'removeClaudePlugin');
+    const pluginDir = path.join(args.destRoot, args.name);
+    const manifestPath = path.join(pluginDir, '.claude-plugin', 'plugin.json');
+    const manifest = await readPluginManifest(manifestPath);
+    const removed = [];
+    const preserved = [];
+    if (!manifest) {
+        return { removed, preserved, pluginDir };
+    }
+    // A tampered `plugin.json` could have injected paths like `../../etc/foo`
+    // into `_meta.frontmcp.managedFiles` to coerce `rm` outside `pluginDir`
+    // on uninstall. Guard each entry against escaping the plugin root.
+    const managed = manifest._meta?.frontmcp?.managedFiles ?? [];
+    for (const rel of managed) {
+        if (!isPluginContainedPath(pluginDir, rel))
+            continue;
+        const abs = path.join(pluginDir, rel);
+        if (await (0, utils_1.fileExists)(abs)) {
+            await (0, utils_1.rm)(abs, { recursive: true, force: true });
+            removed.push(abs);
+        }
+    }
+    if (await (0, utils_1.fileExists)(manifestPath)) {
+        await (0, utils_1.rm)(manifestPath, { force: true });
+        removed.push(manifestPath);
+    }
+    // Bottom-up empty-dir cleanup. Stops at first non-empty dir, preserving
+    // user-added files.
+    await cleanupEmptyDirs(pluginDir, preserved);
+    return { removed, preserved, pluginDir };
+}
+async function readInstalledPluginVersion(pluginDir) {
+    const manifestPath = path.join(pluginDir, '.claude-plugin', 'plugin.json');
+    const manifest = await readPluginManifest(manifestPath);
+    return manifest?._meta?.frontmcp?.binVersion;
+}
+// ============================================================================
+// Codex emitter
+// ============================================================================
+const CODEX_BLOCK_START = '# frontmcp:codex-start';
+const CODEX_BLOCK_END = '# frontmcp:codex-end';
+async function emitCodexEntry(opts) {
+    assertValidPluginName(opts.name, 'emitCodexEntry');
+    const existing = (await (0, utils_1.fileExists)(opts.configPath)) ? await (0, utils_1.readFile)(opts.configPath) : '';
+    const previousVersion = extractCodexEntryComment(existing, opts.name);
+    const newBlock = renderCodexBlock(opts);
+    const merged = replaceCodexBlock(existing, opts.name, newBlock);
+    if (!opts.dryRun) {
+        await (0, utils_1.ensureDir)(path.dirname(opts.configPath));
+        await (0, utils_1.writeFile)(opts.configPath, merged);
+    }
+    return {
+        written: !opts.dryRun,
+        previousVersion,
+        configContent: merged,
+    };
+}
+async function removeCodexEntry(args) {
+    assertValidPluginName(args.name, 'removeCodexEntry');
+    if (!(await (0, utils_1.fileExists)(args.configPath))) {
+        return { removed: false, configContent: '' };
+    }
+    const existing = await (0, utils_1.readFile)(args.configPath);
+    const stripped = stripCodexBlock(existing, args.name);
+    const removed = stripped !== existing;
+    if (removed) {
+        await (0, utils_1.writeFile)(args.configPath, stripped);
+    }
+    return { removed, configContent: stripped };
+}
+// ============================================================================
+// Internals
+// ============================================================================
+function makeMcpServerEntry(opts) {
+    const entry = {
+        command: opts.mcpCommand,
+        args: opts.mcpArgs,
+        transport: 'stdio',
+    };
+    if (opts.envHints.length > 0) {
+        const env = {};
+        for (const name of opts.envHints.slice().sort()) {
+            env[name] = `\${${name}}`;
+        }
+        entry.env = env;
+    }
+    return entry;
+}
+async function readPluginManifest(manifestPath) {
+    if (!(await (0, utils_1.fileExists)(manifestPath)))
+        return undefined;
+    try {
+        const raw = await (0, utils_1.readFile)(manifestPath);
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function mergeUserManifestFields(next, previous) {
+    if (!previous)
+        return next;
+    const out = { ...next };
+    // Preserve user-added entries in mcpServers other than the framework-owned one.
+    if (previous.mcpServers && typeof previous.mcpServers === 'object') {
+        const mergedMcp = { ...next.mcpServers };
+        for (const [k, v] of Object.entries(previous.mcpServers)) {
+            if (k !== next.name)
+                mergedMcp[k] = v;
+        }
+        out.mcpServers = sortObjectKeys(mergedMcp);
+    }
+    // Preserve any unknown top-level key the user added.
+    for (const [k, v] of Object.entries(previous)) {
+        if (!FRAMEWORK_MANAGED_FIELDS.includes(k) && k !== '_meta' && !(k in out)) {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function serializeManifest(manifest) {
+    return JSON.stringify(sortObjectKeys(manifest), null, 2) + '\n';
+}
+function sortObjectKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map((v) => sortObjectKeys(v));
+    }
+    if (value && typeof value === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortObjectKeys(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function renderCommandFile(cmd, binName) {
+    const args = cmd.arguments ?? [];
+    const argHint = args
+        .map((a) => (a.required === false ? `[${a.name}]` : `<${a.name}>`))
+        .join(' ');
+    const fm = ['---'];
+    if (cmd.description)
+        fm.push(`description: ${JSON.stringify(cmd.description)}`);
+    if (argHint)
+        fm.push(`argument-hint: ${JSON.stringify(argHint)}`);
+    fm.push('---', '');
+    const body = [
+        `Invokes the MCP prompt \`${cmd.name}\` from the \`${binName}\` server.`,
+        '',
+        `See \`${binName} prompt get ${cmd.name}\` for the latest argument list.`,
+        '',
+    ];
+    return fm.join('\n') + '\n' + body.join('\n');
+}
+/**
+ * Bottom-up empty-directory cleanup after `removeClaudePlugin`. We only
+ * remove a directory when:
+ *   1. it's a framework-managed directory we know we created
+ *      (`commands/`, `skills/`, `skills/<name>/`, `.claude-plugin/`,
+ *      and the plugin root itself), AND
+ *   2. it is empty (`readdir` returns []).
+ *
+ * Any user-added file under those dirs blocks the cleanup at that level
+ * and bubbles all the way up — so a single user file anywhere in the
+ * plugin tree leaves the entire tree (and the plugin dir itself) intact.
+ * We never traverse INTO user-added subdirs.
+ */
+async function cleanupEmptyDirs(root, _preserved) {
+    if (!(await (0, utils_1.fileExists)(root)))
+        return;
+    // `readdir` and `rm` are imported statically at the top of this module so
+    // the file bundles cleanly into the per-bin CLI (esbuild can't resolve
+    // `await import('@frontmcp/utils')` inside a CJS bundle, which manifests
+    // as a runtime "Dynamic require of fs is not supported" error when the
+    // bin's own `uninstall -p claude` walks the plugin tree).
+    // Pass 1: each per-skill folder under skills/ (one level deep).
+    const skillsDir = path.join(root, 'skills');
+    if (await (0, utils_1.fileExists)(skillsDir)) {
+        for (const entry of await safeReaddir(utils_1.readdir, skillsDir)) {
+            const sub = path.join(skillsDir, entry);
+            await removeIfEmpty(sub, utils_1.rm, utils_1.readdir);
+        }
+    }
+    // Pass 2: framework-managed dirs directly under the plugin root.
+    for (const sub of ['commands', 'skills', '.claude-plugin']) {
+        await removeIfEmpty(path.join(root, sub), utils_1.rm, utils_1.readdir);
+    }
+    // Pass 3: the plugin root itself (only if user added nothing).
+    await removeIfEmpty(root, utils_1.rm, utils_1.readdir);
+}
+async function removeIfEmpty(dir, rmFn, readdirFn) {
+    if (!(await (0, utils_1.fileExists)(dir)))
+        return;
+    const entries = await safeReaddir(readdirFn, dir);
+    if (entries.length === 0) {
+        await rmFn(dir, { recursive: true, force: true });
+    }
+}
+async function safeReaddir(readdirFn, dir) {
+    try {
+        return await readdirFn(dir);
+    }
+    catch {
+        return [];
+    }
+}
+// ----- Codex TOML -----
+function renderCodexBlock(opts) {
+    const lines = [];
+    lines.push(`${CODEX_BLOCK_START}:${opts.name}`);
+    lines.push(`[[mcp_servers]]`);
+    lines.push(`name = ${tomlString(opts.name)}`);
+    lines.push(`command = ${tomlString(opts.command)}`);
+    lines.push(`args = [${opts.args.map(tomlString).join(', ')}]`);
+    if (opts.env && Object.keys(opts.env).length > 0) {
+        const entries = Object.entries(opts.env)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${tomlBareKey(k)} = ${tomlString(v)}`);
+        lines.push(`env = { ${entries.join(', ')} }`);
+    }
+    lines.push(`${CODEX_BLOCK_END}:${opts.name}`);
+    return lines.join('\n');
+}
+function replaceCodexBlock(existing, name, newBlock) {
+    const start = `${CODEX_BLOCK_START}:${name}`;
+    const end = `${CODEX_BLOCK_END}:${name}`;
+    const startIdx = existing.indexOf(start);
+    if (startIdx === -1) {
+        // Normalize the existing content to end in exactly one newline before
+        // appending the new block, so we don't double-up on first insert.
+        const normalized = existing.length === 0 ? '' : existing.replace(/\n*$/, '\n');
+        const sep = normalized.length === 0 ? '' : '\n';
+        return `${normalized}${sep}${newBlock}\n`;
+    }
+    const endIdx = existing.indexOf(end, startIdx);
+    if (endIdx === -1) {
+        // Corrupt block — treat as missing and append fresh.
+        return `${existing.replace(/\n*$/, '\n')}\n${newBlock}\n`;
+    }
+    const before = existing.slice(0, startIdx);
+    const after = existing.slice(endIdx + end.length).replace(/^\n/, '');
+    return `${before}${newBlock}\n${after}`;
+}
+function stripCodexBlock(existing, name) {
+    const start = `${CODEX_BLOCK_START}:${name}`;
+    const end = `${CODEX_BLOCK_END}:${name}`;
+    const startIdx = existing.indexOf(start);
+    if (startIdx === -1)
+        return existing;
+    const endIdx = existing.indexOf(end, startIdx);
+    if (endIdx === -1)
+        return existing;
+    const before = existing.slice(0, startIdx).replace(/\n+$/, '\n');
+    const after = existing.slice(endIdx + end.length).replace(/^\n+/, '\n');
+    return (before + after).replace(/\n{3,}/g, '\n\n');
+}
+function extractCodexEntryComment(content, name) {
+    // Optional: look for an `# version:` comment inside the block; for now we
+    // just return undefined since the block itself doesn't carry a version.
+    void content;
+    void name;
+    return undefined;
+}
+function tomlString(value) {
+    // Basic strings: escape backslash + double-quote, encode common control chars.
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    return `"${escaped}"`;
+}
+function tomlBareKey(key) {
+    return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlString(key);
+}
+//# sourceMappingURL=plugin-emitter.js.map