@zhixuan92/multi-model-agent 3.0.0

package/dist/install/codex-cli.js

@@ -0,0 +1,318 @@
+/**
+ * Codex CLI skill writer for install-skill.
+ *
+ * Task 9.7 scope: write/install and remove/uninstall of skills to
+ * the Codex CLI's managed block in `<homeDir>/.codex/AGENTS.md`.
+ *
+ * Managed block delimiters:
+ *   <!-- multi-model-agent:BEGIN -->
+ *   ... skill content ...
+ *   <!-- multi-model-agent:END -->
+ *
+ * Install behaviour:
+ *   - If AGENTS.md does NOT exist: create it with just the managed block.
+ *   - If AGENTS.md exists but has NO managed block markers: append the block
+ *     at the end with a blank-line separator.
+ *   - If AGENTS.md exists WITH managed block markers: replace the content
+ *     between (and including) the markers with the new managed block.
+ *   - User content OUTSIDE the markers is preserved verbatim.
+ *
+ * Uninstall behaviour:
+ *   - Remove the managed block (including markers) from AGENTS.md.
+ *   - If the file becomes empty or only whitespace after removal, delete the
+ *     file.
+ *   - If the file does not contain the markers, do nothing (no error).
+ *   - If the file does not exist, do nothing (no error).
+ *
+ * @include resolution:
+ *   Lines beginning with `@include _shared/<file>.md` are replaced with the
+ *   file content read from `<skillsRoot>/_shared/<file>.md`.  If the file
+ *   cannot be read, a warning is written to stderr and the line is omitted
+ *   from the output (the directive is NOT preserved — matching the Claude Code
+ *   writer behaviour).
+ *
+ * Security: @include paths must begin with `_shared/` and are resolved
+ * strictly within `<skillsRoot>/_shared/` to prevent path traversal.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+// ─── Constants ────────────────────────────────────────────────────────────────
+const MANAGED_BEGIN = '<!-- multi-model-agent:BEGIN -->';
+const MANAGED_END = '<!-- multi-model-agent:END -->';
+// ─── Managed block helpers ────────────────────────────────────────────────────
+/**
+ * Build the complete managed block string including delimiters.
+ *
+ * Block format:
+ *   <!-- multi-model-agent:BEGIN -->
+ *   <content>
+ *   <!-- multi-model-agent:END -->
+ *
+ * Key newline rules:
+ * - BEGIN is always followed by `\n` so content starts on its own line.
+ * - The content line(s) end with a newline. If content doesn't already end
+ *   with `\n`, we add one before END.
+ * - END is the final line of the block; no trailing newline is added after
+ *   END (the block ends with the `>` character of the END tag).
+ *
+ * This means the block always ends with `MANAGED_END` as the last characters
+ * of the file (no trailing newline after it).
+ */
+function buildManagedBlock(inlinedContent) {
+    const contentEndsWithNewline = inlinedContent.endsWith('\n');
+    // Block format: BEGIN + "\n" + content (ending with \n) + END
+    // No trailing newline after END — callers join suffix directly.
+    return `${MANAGED_BEGIN}\n${inlinedContent}${contentEndsWithNewline ? '' : '\n'}${MANAGED_END}`;
+}
+// ─── @include inlining (private) ─────────────────────────────────────────────
+/**
+ * Inline `@include _shared/<path>` directives in `content`.
+ *
+ * Each line matching `@include _shared/<path>` is replaced with the full
+ * content of the corresponding file under `<skillsRoot>/_shared/<path>`.
+ *
+ * Security constraints:
+ * - Only paths beginning with `_shared/` are accepted.
+ * - The resolved path must stay within `<skillsRoot>/_shared/`.  Path
+ *   traversal attempts (e.g. `_shared/../secrets.txt`) are rejected with a
+ *   warning and the directive line is dropped.
+ *
+ * Missing shared files:
+ * - A warning containing "missing shared file" is written to stderr.
+ * - The directive line is dropped (not preserved) — matching the Claude
+ *   Code writer behaviour as required by the brief.
+ *
+ * @param skillName  Used in warning messages to identify the skill.
+ * @param content    Raw skill content (may contain @include directives).
+ * @param skillsRoot Root directory containing `_shared/`.
+ * @returns The content with directives inlined.
+ */
+function inlineIncludes(skillName, content, skillsRoot) {
+    const lines = content.split('\n');
+    const result = [];
+    for (const line of lines) {
+        const match = line.match(/^@include\s+(.+)$/);
+        if (!match) {
+            result.push(line);
+            continue;
+        }
+        // Trim trailing whitespace from the path token.
+        const relativePath = match[1].trimEnd();
+        // Security: only accept paths beginning with `_shared/`
+        if (!relativePath.startsWith('_shared/')) {
+            process.stderr.write(`Warning: Codex CLI skill writer [${skillName}]: @include path must ` +
+                `start with "_shared/": ${relativePath}\n`);
+            continue;
+        }
+        // Security: reject path traversal attempts
+        const resolvedPath = path.resolve(skillsRoot, relativePath);
+        const sharedDir = path.resolve(skillsRoot, '_shared');
+        if (!resolvedPath.startsWith(sharedDir + path.sep) &&
+            resolvedPath !== sharedDir) {
+            process.stderr.write(`Warning: Codex CLI skill writer [${skillName}]: @include path ` +
+                `rejected (path traversal): ${relativePath}\n`);
+            continue;
+        }
+        const sharedFilePath = path.join(skillsRoot, relativePath);
+        try {
+            const sharedContent = fs.readFileSync(sharedFilePath, 'utf-8');
+            result.push(sharedContent);
+        }
+        catch (err) {
+            const nodeErr = err;
+            if (nodeErr.code === 'ENOENT') {
+                process.stderr.write(`Warning: Codex CLI skill writer [${skillName}]: missing shared ` +
+                    `file: ${sharedFilePath} (referenced by @include ${relativePath})\n`);
+                // Directive is dropped — do not push anything.
+            }
+            else {
+                // Permission errors, EISDIR, etc. — re-throw so the caller notices.
+                throw err;
+            }
+        }
+    }
+    return result.join('\n');
+}
+// ─── Marker helpers ────────────────────────────────────────────────────────────
+/**
+ * Returns true only when both managed block markers are present in
+ * `content` and BEGIN appears before END.  An orphan marker or corrupt
+ * ordering does NOT constitute a valid block.
+ */
+function hasManagedBlock(content) {
+    const beginIdx = content.indexOf(MANAGED_BEGIN);
+    const endIdx = content.indexOf(MANAGED_END);
+    return beginIdx !== -1 && endIdx !== -1 && beginIdx < endIdx;
+}
+// ─── Core write logic ─────────────────────────────────────────────────────────
+/**
+ * Find the span of the existing managed block (including both markers) in
+ * `content`.  Returns `{ prefix, suffix }` where `prefix` is everything
+ * before BEGIN and `suffix` is everything after the block's final character.
+ *
+ * The block always ends with `MANAGED_END` (no trailing newline after END).
+ * After END, there may be a structural newline (the newline that terminates
+ * the END line). This structural newline is NOT part of the user suffix — it
+ * belongs to the block boundary and must not appear as an extra blank line
+ * when prefix and suffix are joined.
+ *
+ * Edge cases:
+ * - If END is the last character of the file (no trailing newline), suffix
+ *   is empty.
+ * - If BEGIN and END are in corrupt order (END before BEGIN), returns null
+ *   so no user content is inadvertently destroyed.
+ */
+function splitAroundBlock(content) {
+    const beginIdx = content.indexOf(MANAGED_BEGIN);
+    const endIdx = content.indexOf(MANAGED_END);
+    // No valid block without both markers
+    if (beginIdx === -1 || endIdx === -1) {
+        return null;
+    }
+    // Corrupt order: END before BEGIN — treat as no valid block to protect
+    // user content from inadvertent removal.
+    if (beginIdx > endIdx) {
+        return null;
+    }
+    // suffix starts immediately after MANAGED_END (includes any trailing newlines).
+    // Callers decide how to handle the leading newlines in suffix:
+    //   - Install (replace): suffix begins with the separator between END and
+    //     following user content; joining block + suffix reconstructs the file.
+    //   - Uninstall: strip all leading newlines from suffix before joining.
+    const suffixStart = endIdx + MANAGED_END.length;
+    return {
+        prefix: content.slice(0, beginIdx),
+        suffix: content.slice(suffixStart),
+    };
+}
+/**
+ * Write (or overwrite) the managed block in the Codex CLI's AGENTS.md.
+ *
+ * The algorithm:
+ *   1. Inline @include directives.
+ *   2. Read existing file if present.
+ *   3. Determine new content: create / append / replace.
+ *   4. Write to disk.
+ *
+ * @throws If the AGENTS.md file exists but cannot be read.
+ * @throws If the AGENTS.md path is a directory.
+ */
+export function installCodexCli(opts) {
+    const agentsPath = path.join(opts.homeDir, '.codex', 'AGENTS.md');
+    // 1. Inline @include directives
+    const inlinedContent = inlineIncludes(opts.skillName, opts.content, opts.skillsRoot);
+    const block = buildManagedBlock(inlinedContent);
+    // 2. Read existing file
+    let existingContent;
+    let fileExists = false;
+    try {
+        const stat = fs.statSync(agentsPath);
+        if (stat.isDirectory()) {
+            throw new Error(`AGENTS.md path is a directory: ${agentsPath}`);
+        }
+        existingContent = fs.readFileSync(agentsPath, 'utf-8');
+        fileExists = true;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            existingContent = '';
+            fileExists = false;
+        }
+        else {
+            throw err;
+        }
+    }
+    // 3. Determine new content
+    let newContent;
+    if (!fileExists) {
+        // Case A: file does not exist → create with just the managed block
+        newContent = block;
+    }
+    else if (!hasManagedBlock(existingContent)) {
+        // Case B: file exists but no managed block → append with blank-line separator
+        //
+        // The block begins with BEGIN + "\n". To create exactly one blank line
+        // between existing content and the BEGIN marker:
+        //   - If existingContent ends with "\n": add one "\n" → existing ends with
+        //     "\n", block starts with "\n" → two newlines = one blank line. ✓
+        //   - If existingContent does NOT end with "\n": add "\n\n" → existing ends
+        //     with "\n", block starts with "\n" → two newlines = one blank line. ✓
+        newContent = existingContent.endsWith('\n')
+            ? `${existingContent}\n${block}`
+            : `${existingContent}\n\n${block}`;
+    }
+    else {
+        // Case C: file exists with managed block → replace it
+        const split = splitAroundBlock(existingContent);
+        if (split === null) {
+            // Both markers present but split returned null — corrupt marker order.
+            // Do not overwrite; append with separator instead.
+            newContent = existingContent.endsWith('\n')
+                ? `${existingContent}\n${block}`
+                : `${existingContent}\n\n${block}`;
+        }
+        else {
+            const { prefix, suffix } = split;
+            newContent = `${prefix}${block}${suffix}`;
+        }
+    }
+    // 4. Write to disk
+    fs.mkdirSync(path.join(opts.homeDir, '.codex'), { recursive: true });
+    fs.writeFileSync(agentsPath, newContent, 'utf-8');
+}
+// ─── Uninstall ────────────────────────────────────────────────────────────────
+/**
+ * Remove the managed block (including markers) from AGENTS.md.
+ *
+ * Behaviour:
+ *   - File does not exist → no-op.
+ *   - File has no managed block markers → no-op (file unchanged).
+ *   - File has managed block → remove it; write remaining content back.
+ *   - Remaining content is empty or whitespace-only → delete the file.
+ *
+ * @throws On filesystem errors other than ENOENT when reading/writing.
+ */
+export function uninstallCodexCli(homeDir) {
+    const agentsPath = path.join(homeDir, '.codex', 'AGENTS.md');
+    let content;
+    try {
+        content = fs.readFileSync(agentsPath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            // File does not exist — no-op.
+            return;
+        }
+        // Re-throw on read errors, preserving the original error context.
+        throw err;
+    }
+    if (!hasManagedBlock(content)) {
+        // No managed block to remove — file unchanged.
+        return;
+    }
+    const split = splitAroundBlock(content);
+    if (split === null) {
+        // Both markers present but split returned null — corrupt marker order.
+        // No safe block to remove — leave file unchanged.
+        return;
+    }
+    const { prefix, suffix } = split;
+    // Strip all leading newlines from suffix. The suffix begins with any
+    // newlines that followed MANAGED_END (including blank-line separators).
+    // Removing them avoids leaving orphan blank lines after the managed block
+    // is gone. The prefix already ends before BEGIN (including any trailing
+    // newlines the user placed before the block), so this does not disturb
+    // user-authored spacing in the prefix.
+    const trimmedSuffix = suffix.replace(/^\n+/, '');
+    const newContent = `${prefix}${trimmedSuffix}`;
+    if (newContent.trim() === '') {
+        // File is empty after removal — delete it.
+        fs.unlinkSync(agentsPath);
+    }
+    else {
+        fs.writeFileSync(agentsPath, newContent, 'utf-8');
+    }
+}
+//# sourceMappingURL=codex-cli.js.map

package/dist/install/codex-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-cli.js","sourceRoot":"","sources":["../../src/install/codex-cli.ts"],"names":[],"mappings":"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"}

package/dist/install/cursor.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Options for installing a Cursor skill.
+ *
+ * NOTE: `homeDir` is accepted for API parity with other skill writers
+ * (Claude Code, Gemini CLI, etc.) but is intentionally not used by this
+ * writer. The Cursor rules target path is always CWD-relative under
+ * `<cwd>/.cursor/rules/`, not homeDir-relative. This is intentional to
+ * keep Cursor rules scoped to the project directory.
+ */
+export interface CursorInstallOpts {
+    /**
+     * Raw skill content. May contain `@include _shared/<file>.md` directives
+     * which are inlined before writing.
+     */
+    content: string;
+    /**
+     * Working directory — replaces `process.cwd()`.
+     * Used to construct the CWD-relative target path:
+     * `<cwd>/.cursor/rules/multi-model-agent.mdc`
+     */
+    cwd: string;
+    /**
+     * Home directory. Accepted for API signature compatibility with other
+     * skill writers, but NOT used by this writer. Cursor rules are always
+     * written relative to `cwd`, not `homeDir`.
+     */
+    homeDir: string;
+    /**
+     * Where shared files live. The writer reads `<skillsRoot>/_shared/<path>`
+     * when inlining `@include` directives.
+     */
+    skillsRoot: string;
+    /**
+     * If true, overwrite the existing file. If false (default), skip writing
+     * when the file already exists.
+     */
+    force?: boolean;
+}
+/**
+ * Result of `installCursor`.
+ */
+export interface CursorInstallResult {
+    /**
+     * `true` if the file was written, `false` if it was skipped because it
+     * already exists and `force` was not set.
+     */
+    written: boolean;
+    /** The full path that was (or would have been) written. */
+    targetPath: string;
+}
+/**
+ * Install the multi-model-agent skill for Cursor.
+ *
+ * - Target path is `<cwd>/.cursor/rules/multi-model-agent.mdc` (CWD-relative).
+ * - Creates `<cwd>/.cursor/rules/` if it does not exist.
+ * - Inlines `@include` directives before writing (see `inlineIncludes`).
+ * - If the file already exists and `force` is not set, skips writing and
+ *   returns `written: false`.
+ *
+ * @param opts  Installation options (see `CursorInstallOpts`).
+ */
+export declare function installCursor(opts: CursorInstallOpts): CursorInstallResult;
+/**
+ * Uninstall the multi-model-agent Cursor skill.
+ *
+ * Removes `<cwd>/.cursor/rules/multi-model-agent.mdc`.
+ * This is a no-op when the file does not exist (no error is thrown).
+ *
+ * @param cwd  Working directory (replaces `process.cwd()`).
+ */
+export declare function uninstallCursor(cwd: string): void;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/install/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/install/cursor.ts"],"names":[],"mappings":"AA8BA;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAmB1E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAmBjD"}

package/dist/install/cursor.js

@@ -0,0 +1,81 @@
+/**
+ * Cursor skill writer.
+ *
+ * Writes the skill content to `<cwd>/.cursor/rules/multi-model-agent.mdc`.
+ *
+ * Before writing, inlines any `@include _shared/<file>.md` directives found in
+ * the content. The directive line is replaced with the full content of
+ * the corresponding shared file sourced from `<skillsRoot>/_shared/<path>`.
+ * The `@include` directive is NOT preserved in the written file.
+ *
+ * If a referenced shared file is missing (ENOENT):
+ * - A warning is logged to stderr.
+ * - The include line is removed from the output (not preserved).
+ * - Processing continues for remaining directives.
+ *
+ * Security constraints on `@include` directives:
+ * - Only paths beginning with `_shared/` are accepted.
+ * - The resolved path must stay within `<skillsRoot>/_shared/`.
+ *   Path traversal attempts (e.g. `_shared/../secrets.txt`) are rejected
+ *   with a warning and the directive line is dropped.
+ * - Non-`_shared/` paths are rejected with a warning and the directive
+ *   line is dropped.
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { inlineIncludes } from './include-utils.js';
+/**
+ * Install the multi-model-agent skill for Cursor.
+ *
+ * - Target path is `<cwd>/.cursor/rules/multi-model-agent.mdc` (CWD-relative).
+ * - Creates `<cwd>/.cursor/rules/` if it does not exist.
+ * - Inlines `@include` directives before writing (see `inlineIncludes`).
+ * - If the file already exists and `force` is not set, skips writing and
+ *   returns `written: false`.
+ *
+ * @param opts  Installation options (see `CursorInstallOpts`).
+ */
+export function installCursor(opts) {
+    const { content, cwd, skillsRoot, force } = opts;
+    const targetPath = path.join(cwd, '.cursor', 'rules', 'multi-model-agent.mdc');
+    if (!force && fs.existsSync(targetPath)) {
+        process.stderr.write(`Warning: Cursor skill writer: file already exists: ${targetPath} — skipping (use force: true to overwrite)\n`);
+        return { written: false, targetPath };
+    }
+    const rulesDir = path.join(cwd, '.cursor', 'rules');
+    fs.mkdirSync(rulesDir, { recursive: true, mode: 0o700 });
+    const finalContent = inlineIncludes('Cursor skill writer', content, skillsRoot);
+    fs.writeFileSync(targetPath, finalContent, 'utf-8');
+    return { written: true, targetPath };
+}
+/**
+ * Uninstall the multi-model-agent Cursor skill.
+ *
+ * Removes `<cwd>/.cursor/rules/multi-model-agent.mdc`.
+ * This is a no-op when the file does not exist (no error is thrown).
+ *
+ * @param cwd  Working directory (replaces `process.cwd()`).
+ */
+export function uninstallCursor(cwd) {
+    const targetPath = path.join(cwd, '.cursor', 'rules', 'multi-model-agent.mdc');
+    // Only remove the file if it exists and is a file (not a directory).
+    // This is a no-op when the path does not exist.
+    try {
+        const stat = fs.statSync(targetPath);
+        if (stat.isFile()) {
+            fs.unlinkSync(targetPath);
+        }
+        // If it's a directory or symlink to directory, do nothing — the brief
+        // specifies removing a file, not a directory tree.
+    }
+    catch (err) {
+        const nodeErr = err;
+        // ENOENT means the file doesn't exist — that's fine, we were asked to remove it
+        if (nodeErr.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=cursor.js.map

package/dist/install/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/install/cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAsDpD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,IAAuB;IACnD,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IAEjD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC;IAE/E,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACxC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,sDAAsD,UAAU,8CAA8C,CAC/G,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IACxC,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACpD,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAEzD,MAAM,YAAY,GAAG,cAAc,CAAC,qBAAqB,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAChF,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAEpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC;IAE/E,qEAAqE;IACrE,gDAAgD;IAChD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACrC,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YAClB,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC5B,CAAC;QACD,sEAAsE;QACtE,mDAAmD;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAA4B,CAAC;QAC7C,gFAAgF;QAChF,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/install/gemini-cli.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Options for installing a skill via the Gemini CLI writer.
+ */
+export interface GeminiCliInstallOpts {
+    /** Skill name (currently informational; writes always go to multi-model-agent extension). */
+    skillName: string;
+    /**
+     * Raw SKILL.md content. May contain `@include _shared/<file>.md` directives
+     * which are inlined before writing.
+     */
+    content: string;
+    /**
+     * Version string for the extension manifest's `version` field.
+     */
+    skillVersion: string;
+    /**
+     * The "home directory" that replaces `os.homedir()`.
+     * Must NOT default to `os.homedir()` — always required explicitly.
+     */
+    homeDir: string;
+    /**
+     * Where shared files live. The writer reads `<skillsRoot>/_shared/<file>.md`
+     * when inlining `@include` directives.
+     */
+    skillsRoot: string;
+}
+/**
+ * Inline `@include _shared/<file>.md` directives in `content`.
+ *
+ * Each line matching `@include <path>` (space after `@include`) is replaced with
+ * the full content of `<skillsRoot>/_shared/<path>`.
+ *
+ * If a shared file is missing:
+ * - A warning is written to stderr.
+ * - The include line is removed from the output (not preserved).
+ * - Processing continues for remaining directives.
+ *
+ * @param content     Raw SKILL.md content (may contain @include directives).
+ * @param skillsRoot  Root directory containing `_shared/` sub-directory.
+ * @returns The content with directives inlined.
+ */
+export declare function inlineIncludes(content: string, skillsRoot: string): string;
+/**
+ * Install a skill to the Gemini CLI extensions directory.
+ *
+ * Writes two files into `<homeDir>/.gemini/extensions/multi-model-agent/`:
+ *   1. `gemini-extension.json` — the extension manifest
+ *   2. `SKILL.md` — the skill content with @include directives inlined
+ *
+ * The directory (and any parent directories) are created with mode `0o700`.
+ * Calling this function multiple times overwrites the previous installation
+ * (idempotent).
+ *
+ * @param opts  Installation options (see `GeminiCliInstallOpts`).
+ */
+export declare function installGeminiCli(opts: GeminiCliInstallOpts): void;
+/**
+ * Uninstall the multi-model-agent Gemini CLI extension.
+ *
+ * Recursively removes `<homeDir>/.gemini/extensions/multi-model-agent/`.
+ * This is a no-op when the directory does not exist (no error is thrown).
+ *
+ * @param homeDir  The "home directory" that replaces `os.homedir()`.
+ */
+export declare function uninstallGeminiCli(homeDir: string): void;
+//# sourceMappingURL=gemini-cli.d.ts.map

package/dist/install/gemini-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-cli.d.ts","sourceRoot":"","sources":["../../src/install/gemini-cli.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6FAA6F;IAC7F,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA6B1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAuBjE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKxD"}