@zhixuan92/multi-model-agent 5.0.2 → 5.1.0

package/dist/skill-install/disabled-state.js

@@ -0,0 +1,96 @@
+/**
+ * disabled-state.ts — the persistent "skills disabled" sentinel.
+ *
+ * `mmagent disable` writes this file; `sync-skills` (and the npm postinstall
+ * hook that shells out to it) consults it so an upgrade never silently
+ * reinstalls skills the user deliberately turned off. `mmagent enable` clears
+ * the relevant targets and, when none remain, deletes the file.
+ *
+ * Stored at ~/.multi-model/skills-disabled.json — the same directory as the
+ * install manifest and auth token, with matching 0o700/0o600 permissions.
+ *
+ * The sentinel is target-aware: it records *which* clients are disabled so a
+ * `disable --target=cursor` does not block syncing claude-code.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { z } from 'zod';
+import { ALL_CLIENTS, manifestDir } from './manifest.js';
+const DISABLED_NAME = 'skills-disabled.json';
+// Derive the client enum from ALL_CLIENTS so a new client never silently
+// fails sentinel validation. z.enum needs a non-empty literal tuple.
+const clientEnum = z.enum(ALL_CLIENTS);
+const disabledStateSchema = z.object({
+    version: z.literal(1),
+    disabledAt: z.number().int().nonnegative(),
+    cliVersion: z.string(),
+    targets: z.array(clientEnum),
+});
+/** Full path to the sentinel file. */
+export function disabledStatePath(homeDir) {
+    return path.join(manifestDir(homeDir), DISABLED_NAME);
+}
+/**
+ * Read and validate the sentinel. Returns null when absent, unreadable, or
+ * structurally invalid — a malformed sentinel must never wedge sync-skills.
+ */
+export function readDisabledState(homeDir) {
+    try {
+        const raw = fs.readFileSync(disabledStatePath(homeDir), 'utf-8');
+        const parsed = disabledStateSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The set of currently-disabled clients (empty when the sentinel is absent). */
+export function disabledTargets(homeDir) {
+    return readDisabledState(homeDir)?.targets ?? [];
+}
+/**
+ * Mark `targets` as disabled, unioned with any already-disabled clients.
+ * Returns the resulting disabled set (stable ALL_CLIENTS order).
+ */
+export function addDisabledTargets(homeDir, targets, cliVersion) {
+    const current = new Set(disabledTargets(homeDir));
+    for (const t of targets)
+        current.add(t);
+    const merged = ALL_CLIENTS.filter((c) => current.has(c));
+    writeDisabledState(homeDir, {
+        version: 1,
+        disabledAt: Date.now(),
+        cliVersion,
+        targets: merged,
+    });
+    return merged;
+}
+/**
+ * Clear `targets` from the disabled set. Deletes the sentinel file entirely
+ * once nothing remains disabled. Returns the still-disabled set.
+ */
+export function clearDisabledTargets(homeDir, targets) {
+    const existing = readDisabledState(homeDir);
+    if (existing === null)
+        return [];
+    const remaining = existing.targets.filter((t) => !targets.includes(t));
+    if (remaining.length === 0) {
+        try {
+            fs.rmSync(disabledStatePath(homeDir), { force: true });
+        }
+        catch {
+            /* best effort — an absent file is the desired end state anyway */
+        }
+        return [];
+    }
+    writeDisabledState(homeDir, { ...existing, targets: remaining });
+    return remaining;
+}
+function writeDisabledState(homeDir, state) {
+    fs.mkdirSync(manifestDir(homeDir), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(disabledStatePath(homeDir), JSON.stringify(state, null, 2) + '\n', {
+        encoding: 'utf-8',
+        mode: 0o600,
+    });
+}
+//# sourceMappingURL=disabled-state.js.map

package/dist/skill-install/disabled-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disabled-state.js","sourceRoot":"","sources":["../../src/skill-install/disabled-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAe,MAAM,eAAe,CAAC;AAEtE,MAAM,aAAa,GAAG,sBAAsB,CAAC;AAE7C,yEAAyE;AACzE,qEAAqE;AACrE,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,WAA+C,CAAC,CAAC;AAE3E,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC1C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC;CAC7B,CAAC,CAAC;AAIH,sCAAsC;AACtC,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,IAAI,EAAE,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA2B,EAC3B,OAAiB,EACjB,UAAkB;IAElB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,kBAAkB,CAAC,OAAO,EAAE;QAC1B,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;QACtB,UAAU;QACV,OAAO,EAAE,MAAM;KAChB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA2B,EAAE,OAAiB;IACjF,MAAM,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;QACpE,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,kBAAkB,CAAC,OAAO,EAAE,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;IACjE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,kBAAkB,CAAC,OAA2B,EAAE,KAAoB;IAC3E,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrE,EAAE,CAAC,aAAa,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE;QAClF,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;AACL,CAAC"}

package/dist/skill-install/discover.d.ts

@@ -0,0 +1,29 @@
+import type { Client } from './manifest.js';
+export declare const SUPPORTED_SKILLS: readonly ["multi-model-agent", "mma-delegate", "mma-audit", "mma-review", "mma-debug", "mma-execute-plan", "mma-retry", "mma-context-blocks", "mma-investigate", "mma-research", "mma-explore", "mma-journal-record", "mma-journal-recall"];
+/** Thrown when a skill's SKILL.md cannot be read from the bundled skills directory. */
+export declare class SkillNotFoundError extends Error {
+    readonly code: "skill_not_found";
+    constructor(skillName: string, checkedPath: string);
+}
+export declare function skillsRootCandidates(here: string): string[];
+export declare function pickSkillsRoot(here: string, exists?: (p: string) => boolean): string;
+/**
+ * Return the absolute path to the skills root directory. Production: the
+ * bundled `packages/server/src/skills/` (or its dist mirror). Tests pass
+ * a fixture path explicitly.
+ */
+export declare function getSkillsRoot(skillsRoot?: string): string;
+/**
+ * Read the content of a skill's SKILL.md file. Returns null if the file
+ * does not exist; propagates other I/O errors so callers can distinguish
+ * "skill not found" from "can't access skill".
+ */
+export declare function readSkillContent(skillName: string, skillsRoot?: string): string | null;
+/**
+ * Return the per-client install directories where skills are written as
+ * subdirectories. Only includes clients that use the per-skill directory
+ * model (claude-code and codex). Gemini and Cursor bundle skills into a
+ * single file/extension and are not included.
+ */
+export declare function discoverPerClientInstallDirs(homeDir?: string): Partial<Record<Client, string>>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/skill-install/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/skill-install/discover.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,eAAO,MAAM,gBAAgB,6OAcnB,CAAC;AAEX,uFAAuF;AACvF,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBAC/B,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAOnD;AAYD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAgB3D;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAuB,GAC7C,MAAM,CAMR;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQtF;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAM9F"}

package/dist/skill-install/discover.js

@@ -0,0 +1,104 @@
+// Skill discovery — locates packaged SKILL.md files on disk and reads them.
+// Extracted from cli/install-skill.ts as part of Ch 7 Task 39.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const SUPPORTED_SKILLS = [
+    'multi-model-agent',
+    'mma-delegate',
+    'mma-audit',
+    'mma-review',
+    'mma-debug',
+    'mma-execute-plan',
+    'mma-retry',
+    'mma-context-blocks',
+    'mma-investigate',
+    'mma-research',
+    'mma-explore',
+    'mma-journal-record',
+    'mma-journal-recall',
+];
+/** Thrown when a skill's SKILL.md cannot be read from the bundled skills directory. */
+export class SkillNotFoundError extends Error {
+    code = 'skill_not_found';
+    constructor(skillName, checkedPath) {
+        super(`Skill '${skillName}' not found. ` +
+            `Checked: ${checkedPath}. ` +
+            `Available skills: ${SUPPORTED_SKILLS.join(', ')}`);
+    }
+}
+// Discover.ts lives in `packages/core/src/tool-surface/` (or its dist mirror).
+// Skills are bundled by the server package at `packages/server/src/skills/`
+// (copied to `packages/server/dist/skills/` at build time, then shipped on
+// the `@zhixuan92/multi-model-agent` npm package as `dist/skills/`).
+// Probe candidates for both monorepo dev layouts and the two npm-installed
+// layouts (hoisted siblings, or core nested under server).
+//
+// Exported (and parameterized on `here` + `exists`) so the candidate logic
+// can be unit-tested against fixtures that mimic each layout — the v4.0.1
+// regression was a missing prod candidate.
+export function skillsRootCandidates(here) {
+    return [
+        // Dev source: packages/core/src/tool-surface -> packages/server/src/skills
+        path.resolve(here, '..', '..', '..', 'server', 'src', 'skills'),
+        // Dev built: packages/core/dist/tool-surface -> packages/server/dist/skills
+        path.resolve(here, '..', '..', '..', 'server', 'dist', 'skills'),
+        // npm install (hoisted): node_modules/@zhixuan92/multi-model-agent-core/dist/tool-surface
+        //                     -> node_modules/@zhixuan92/multi-model-agent/dist/skills
+        path.resolve(here, '..', '..', '..', 'multi-model-agent', 'dist', 'skills'),
+        // npm install (core nested under server):
+        //   .../multi-model-agent/node_modules/@zhixuan92/multi-model-agent-core/dist/tool-surface
+        // -> .../multi-model-agent/dist/skills
+        path.resolve(here, '..', '..', '..', '..', '..', 'dist', 'skills'),
+        // Last-resort fallback for any caller that bundles skills inside core.
+        path.resolve(here, '..', 'skills'),
+    ];
+}
+export function pickSkillsRoot(here, exists = fs.existsSync) {
+    const candidates = skillsRootCandidates(here);
+    for (const c of candidates) {
+        if (exists(c))
+            return c;
+    }
+    return candidates[0];
+}
+const DEFAULT_SKILLS_ROOT = pickSkillsRoot(path.dirname(fileURLToPath(import.meta.url)));
+/**
+ * Return the absolute path to the skills root directory. Production: the
+ * bundled `packages/server/src/skills/` (or its dist mirror). Tests pass
+ * a fixture path explicitly.
+ */
+export function getSkillsRoot(skillsRoot) {
+    return skillsRoot ?? DEFAULT_SKILLS_ROOT;
+}
+/**
+ * Read the content of a skill's SKILL.md file. Returns null if the file
+ * does not exist; propagates other I/O errors so callers can distinguish
+ * "skill not found" from "can't access skill".
+ */
+export function readSkillContent(skillName, skillsRoot) {
+    const skillFile = path.join(getSkillsRoot(skillsRoot), skillName, 'SKILL.md');
+    try {
+        return fs.readFileSync(skillFile, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/**
+ * Return the per-client install directories where skills are written as
+ * subdirectories. Only includes clients that use the per-skill directory
+ * model (claude-code and codex). Gemini and Cursor bundle skills into a
+ * single file/extension and are not included.
+ */
+export function discoverPerClientInstallDirs(homeDir) {
+    const h = homeDir ?? os.homedir();
+    return {
+        'claude-code': path.join(h, '.claude', 'skills'),
+        'codex': path.join(h, '.codex', 'skills'),
+    };
+}
+//# sourceMappingURL=discover.js.map

package/dist/skill-install/discover.js.map

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

package/dist/skill-install/include-utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Inline `@include _shared/<path>` directives in `content`.
+ *
+ * Each line matching `@include _shared/<path>` (space after `@include`) is
+ * replaced with the full content of `<skillsRoot>/_shared/<path>`.
+ *
+ * Security constraints:
+ * - Only paths beginning with `_shared/` are accepted.
+ * - The resolved path must stay within `<skillsRoot>/_shared/`.
+ *   Path traversal attempts are rejected with a warning and the directive
+ *   line is dropped.
+ *
+ * If a shared file is missing (ENOENT):
+ * - A warning is written to stderr.
+ * - The include line is removed from the output (not preserved).
+ * - Processing continues for remaining directives.
+ *
+ * Other I/O errors (permission denied, EISDIR, etc.) are re-thrown so the
+ * caller can distinguish them from a simple missing-file case.
+ *
+ * @param skillContext  Used in warning messages to identify the skill context.
+ * @param content       Raw skill content (may contain @include directives).
+ * @param skillsRoot    Root directory containing `_shared/` sub-directory.
+ * @returns The content with directives inlined.
+ */
+export declare function inlineIncludes(skillContext: string, content: string, skillsRoot: string): string;
+//# sourceMappingURL=include-utils.d.ts.map

package/dist/skill-install/include-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-utils.d.ts","sourceRoot":"","sources":["../../src/skill-install/include-utils.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,MAAM,CA6DR"}

package/dist/skill-install/include-utils.js

@@ -0,0 +1,90 @@
+/**
+ * Shared include-inlining utilities for skill writers.
+ *
+ * Provides a common implementation for `@include _shared/<path>` directive
+ * processing, used by all skill writers (Claude Code, Cursor, etc.).
+ *
+ * @module
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Regex matching a line that starts with `@include ` (exact space after
+ * `@include`) followed by a relative path.
+ */
+const INCLUDE_RE = /^@include\s+(.+)$/;
+/**
+ * Inline `@include _shared/<path>` directives in `content`.
+ *
+ * Each line matching `@include _shared/<path>` (space after `@include`) is
+ * replaced with the full content of `<skillsRoot>/_shared/<path>`.
+ *
+ * Security constraints:
+ * - Only paths beginning with `_shared/` are accepted.
+ * - The resolved path must stay within `<skillsRoot>/_shared/`.
+ *   Path traversal attempts are rejected with a warning and the directive
+ *   line is dropped.
+ *
+ * If a shared file is missing (ENOENT):
+ * - A warning is written to stderr.
+ * - The include line is removed from the output (not preserved).
+ * - Processing continues for remaining directives.
+ *
+ * Other I/O errors (permission denied, EISDIR, etc.) are re-thrown so the
+ * caller can distinguish them from a simple missing-file case.
+ *
+ * @param skillContext  Used in warning messages to identify the skill context.
+ * @param content       Raw skill content (may contain @include directives).
+ * @param skillsRoot    Root directory containing `_shared/` sub-directory.
+ * @returns The content with directives inlined.
+ */
+export function inlineIncludes(skillContext, content, skillsRoot) {
+    const lines = content.split('\n');
+    const result = [];
+    for (const line of lines) {
+        const match = INCLUDE_RE.exec(line);
+        if (!match) {
+            result.push(line);
+            continue;
+        }
+        const relativePath = match[1] ?? '';
+        // Security: only accept paths beginning with `_shared/`
+        if (!relativePath.startsWith('_shared/')) {
+            process.stderr.write(`Warning: ${skillContext}: @include path must start with ` +
+                `"_shared/": ${relativePath}\n`);
+            // Directive line is dropped — do not push anything.
+            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: ${skillContext}: @include path rejected ` +
+                `(path traversal): ${relativePath}\n`);
+            // Directive line is dropped.
+            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') {
+                // Missing shared file — warn and drop the directive line.
+                const detail = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`Warning: ${skillContext}: shared file not found: ` +
+                    `${sharedFilePath} (referenced by @include ${relativePath}) — ${detail}\n`);
+                // Line is dropped — do not push anything.
+            }
+            else {
+                // Permission errors, EISDIR, etc. — re-throw so the caller notices.
+                throw err;
+            }
+        }
+    }
+    return result.join('\n');
+}
+//# sourceMappingURL=include-utils.js.map

package/dist/skill-install/include-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-utils.js","sourceRoot":"","sources":["../../src/skill-install/include-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,OAAe,EACf,UAAkB;IAElB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,SAAS;QACX,CAAC;QAED,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAEpC,wDAAwD;QACxD,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YACzC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,YAAY,kCAAkC;gBAC1D,eAAe,YAAY,IAAI,CAChC,CAAC;YACF,oDAAoD;YACpD,SAAS;QACX,CAAC;QAED,2CAA2C;QAC3C,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QACtD,IACE,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC;YAC9C,YAAY,KAAK,SAAS,EAC1B,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,YAAY,2BAA2B;gBACnD,qBAAqB,YAAY,IAAI,CACtC,CAAC;YACF,6BAA6B;YAC7B,SAAS;QACX,CAAC;QAED,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QAE3D,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,EAAE,CAAC,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;YAC/D,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,GAA4B,CAAC;YAC7C,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC9B,0DAA0D;gBAC1D,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,YAAY,2BAA2B;oBACnD,GAAG,cAAc,4BAA4B,YAAY,OAAO,MAAM,IAAI,CAC3E,CAAC;gBACF,0CAA0C;YAC5C,CAAC;iBAAM,CAAC;gBACN,oEAAoE;gBACpE,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/dist/skill-install/manifest.d.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+/** Union of all supported AI client targets. */
+export type Client = 'claude-code' | 'gemini' | 'codex' | 'cursor';
+/** All known client values — used for --all-targets and target validation. */
+export declare const ALL_CLIENTS: readonly Client[];
+/**
+ * Detect which AI client directories exist in the home directory.
+ * Checks for evidence of each known client:
+ * - claude-code: ~/.claude/ directory present (installs skills under ~/.claude/skills/)
+ * - gemini:       ~/.gemini/extensions/ directory present
+ * - codex:        ~/.codex/ directory present (installs skills under ~/.codex/skills/)
+ * - cursor:       ~/.cursor/rules/ directory present
+ *
+ * The claude-code check deliberately accepts ~/.claude/ as sufficient signal
+ * even when ~/.claude/skills/ does not yet exist (fresh install with no skills).
+ */
+export declare function detectClients(homeDir: string): Client[];
+declare const manifestEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    skillVersion: z.ZodString;
+    installedAt: z.ZodNumber;
+    targets: z.ZodArray<z.ZodEnum<{
+        gemini: "gemini";
+        "claude-code": "claude-code";
+        cursor: "cursor";
+        codex: "codex";
+    }>>;
+}, z.core.$strip>;
+declare const installManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    entries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        skillVersion: z.ZodString;
+        installedAt: z.ZodNumber;
+        targets: z.ZodArray<z.ZodEnum<{
+            gemini: "gemini";
+            "claude-code": "claude-code";
+            cursor: "cursor";
+            codex: "codex";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type InstallManifest = z.infer<typeof installManifestSchema>;
+export type ManifestEntry = z.infer<typeof manifestEntrySchema>;
+/** Thrown when the manifest declares a version newer than this mmagent supports. */
+export declare class FutureManifestError extends Error {
+    constructor(version: number);
+}
+/** Thrown when the manifest JSON parses but fails Zod structural validation. */
+export declare class ManifestSchemaValidationError extends Error {
+    constructor(manifestPath: string, issues: z.ZodError);
+}
+/** The directory where the manifest file lives. */
+export declare function manifestDir(homeDir?: string): string;
+/** Full path to the manifest file. */
+export declare function manifestPath(homeDir?: string): string;
+/**
+ * Return all manifest entries, newest-first.
+ */
+export declare function listEntries(homeDir?: string): ManifestEntry[];
+/**
+ * Append (or update) the entry for `skillName`.
+ *
+ * - New entry: creates with de-duplicated `newTargets`.
+ * - Existing entry: merges `newTargets` into existing targets (no duplicates),
+ *   refreshes `version` and `installedAt`.
+ *
+ * In both paths the stored `targets` array is a fresh copy — caller mutations
+ * after the call do not affect the in-memory object or persisted manifest.
+ *
+ * Returns the resulting entry.
+ */
+export declare function appendEntry(skillName: string, skillVersion: string, newTargets: Client[], homeDir?: string): ManifestEntry;
+/**
+ * Remove `targets` from the entry for `skillName`.
+ * If `targets` is omitted or empty, removes the entire entry.
+ * Returns the removed targets (or all targets for a full removal),
+ * or an empty array if the skill wasn't in the manifest.
+ */
+export declare function removeEntry(skillName: string, targets?: Client[], homeDir?: string): Client[];
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/skill-install/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/skill-install/manifest.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gDAAgD;AAChD,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEnE,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,SAAS,MAAM,EAAiD,CAAC;AAE3F;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAOvD;AAUD,QAAA,MAAM,mBAAmB;;;;;;;;;;iBAKvB,CAAC;AAEH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;iBAGzB,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,oFAAoF;AACpF,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,gFAAgF;AAChF,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ;CAKrD;AAID,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,sCAAsC;AACtC,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAwED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAE7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,CAAC,EAAE,MAAM,GACf,aAAa,CA+Bf;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,MAAM,EAAO,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,EAAE,CAsBV"}