mdkg 0.0.3 → 0.0.5

package/dist/commands/skill.js

@@ -0,0 +1,374 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSkillNewCommand = runSkillNewCommand;
+exports.runSkillListCommand = runSkillListCommand;
+exports.runSkillShowCommand = runSkillShowCommand;
+exports.runSkillSearchCommand = runSkillSearchCommand;
+exports.runSkillValidateCommand = runSkillValidateCommand;
+exports.runSkillSyncCommand = runSkillSyncCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const skills_indexer_1 = require("../graph/skills_indexer");
+const skills_index_cache_1 = require("../graph/skills_index_cache");
+const skills_index_cache_2 = require("../graph/skills_index_cache");
+const errors_1 = require("../util/errors");
+const skill_support_1 = require("./skill_support");
+const query_output_1 = require("./query_output");
+const event_support_1 = require("./event_support");
+const skill_mirror_1 = require("./skill_mirror");
+function parseCsvList(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+function normalizeLowercaseList(raw) {
+    return parseCsvList(raw).map((value) => value.toLowerCase());
+}
+function normalizeSlug(raw) {
+    const slug = raw.trim().toLowerCase();
+    if (!skills_indexer_1.SKILL_SLUG_RE.test(slug)) {
+        throw new errors_1.UsageError(`skill slug must be kebab-case: ${raw}`);
+    }
+    return slug;
+}
+function resolveSkillPaths(root, slug) {
+    const config = (0, config_1.loadConfig)(root);
+    const skillsRoot = (0, skills_indexer_1.resolveSkillsRoot)(root, config);
+    const skillDir = path_1.default.join(skillsRoot, slug);
+    return {
+        skillDir,
+        canonicalPath: path_1.default.join(skillDir, "SKILL.md"),
+        compatPath: path_1.default.join(skillDir, "SKILLS.md"),
+    };
+}
+function validateSingleSkill(root, slug) {
+    const { skillDir, canonicalPath, compatPath } = resolveSkillPaths(root, slug);
+    const warnings = [];
+    const errors = [];
+    const hasCanonical = fs_1.default.existsSync(canonicalPath);
+    const hasCompat = fs_1.default.existsSync(compatPath);
+    if (!fs_1.default.existsSync(skillDir)) {
+        throw new errors_1.NotFoundError(`skill not found: ${slug}`);
+    }
+    if (hasCanonical && hasCompat) {
+        errors.push(`${skillDir}: both SKILL.md and SKILLS.md exist`);
+        return { warnings, errors };
+    }
+    if (!hasCanonical && !hasCompat) {
+        errors.push(`${skillDir}: missing SKILL.md or SKILLS.md`);
+        return { warnings, errors };
+    }
+    const skillPath = hasCanonical ? canonicalPath : compatPath;
+    if (!hasCanonical) {
+        warnings.push(`${path_1.default.relative(root, compatPath)}: using legacy SKILLS.md compatibility file`);
+    }
+    try {
+        (0, skills_indexer_1.buildSkillIndexEntry)(root, slug, skillPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "unknown skill validation error";
+        errors.push(message);
+    }
+    return { warnings, errors };
+}
+function maybeLine(label, values) {
+    if (values.length === 0) {
+        return undefined;
+    }
+    return `${label}: ${values.join(", ")}`;
+}
+function filterSkills(skills, tags, tagsMode = "any") {
+    const normalizedTags = tags?.map((value) => value.toLowerCase()).filter(Boolean) ?? [];
+    if (normalizedTags.length === 0) {
+        return skills;
+    }
+    return skills.filter((skill) => {
+        const skillTags = new Set(skill.tags.map((value) => value.toLowerCase()));
+        if (tagsMode === "all") {
+            return normalizedTags.every((value) => skillTags.has(value));
+        }
+        return normalizedTags.some((value) => skillTags.has(value));
+    });
+}
+function buildSkillSearchText(skill) {
+    const ochatrTokens = Object.entries(skill.ochatr).flatMap(([key, value]) => {
+        if (Array.isArray(value)) {
+            return [key, ...value];
+        }
+        if (typeof value === "boolean") {
+            return [key, value ? "true" : "false"];
+        }
+        return [key, value];
+    });
+    const tokens = [
+        skill.slug,
+        skill.id,
+        skill.qid,
+        skill.name,
+        skill.description,
+        skill.path,
+        ...skill.tags,
+        ...skill.authors,
+        ...skill.links,
+        ...ochatrTokens,
+    ];
+    return tokens.join(" ").toLowerCase();
+}
+function matchesSkillQuery(skill, terms) {
+    const text = buildSkillSearchText(skill);
+    for (const term of terms) {
+        if (!text.includes(term)) {
+            return false;
+        }
+    }
+    return true;
+}
+function runSkillNewCommand(options) {
+    const root = options.root;
+    const config = (0, config_1.loadConfig)(root);
+    const slug = normalizeSlug(options.slug);
+    const name = options.name.trim();
+    const description = options.description.trim();
+    if (!name) {
+        throw new errors_1.UsageError("skill name cannot be empty");
+    }
+    if (!description) {
+        throw new errors_1.UsageError("skill description cannot be empty");
+    }
+    const tags = normalizeLowercaseList(options.tags);
+    const authors = parseCsvList(options.authors);
+    const links = parseCsvList(options.links);
+    const skillsRoot = (0, skills_indexer_1.resolveSkillsRoot)(root, config);
+    const skillDir = path_1.default.join(skillsRoot, slug);
+    const canonicalPath = path_1.default.join(skillDir, "SKILL.md");
+    const compatPath = path_1.default.join(skillDir, "SKILLS.md");
+    const force = Boolean(options.force);
+    if (fs_1.default.existsSync(compatPath)) {
+        throw new errors_1.UsageError(`legacy compatibility file exists for ${slug}; migrate SKILLS.md before scaffolding`);
+    }
+    if (fs_1.default.existsSync(canonicalPath) && !force) {
+        throw new errors_1.UsageError(`skill already exists: ${path_1.default.relative(root, canonicalPath)} (use --force to overwrite)`);
+    }
+    fs_1.default.mkdirSync(skillDir, { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.join(skillDir, "references"), { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.join(skillDir, "assets"), { recursive: true });
+    if (options.withScripts) {
+        fs_1.default.mkdirSync(path_1.default.join(skillDir, "scripts"), { recursive: true });
+    }
+    const content = (0, skill_support_1.renderSkillTemplate)({
+        name,
+        description,
+        tags,
+        authors,
+        links,
+    });
+    fs_1.default.writeFileSync(canonicalPath, content, "utf8");
+    (0, skill_support_1.ensureSkillsRegistry)(root, config);
+    (0, skill_support_1.refreshSkillsRegistry)(root, config);
+    if ((0, skill_mirror_1.shouldMaintainSkillMirrors)(root)) {
+        (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true, force });
+    }
+    if (config.index.auto_reindex) {
+        const skillsIndex = (0, skills_indexer_1.buildSkillsIndex)(root, config);
+        (0, skills_index_cache_2.writeSkillsIndex)((0, skills_indexer_1.resolveSkillsIndexPath)(root), skillsIndex);
+    }
+    (0, event_support_1.appendAutomaticEvent)({
+        root,
+        ws: "root",
+        kind: "SKILL_CREATED",
+        status: "ok",
+        refs: [`skill:${slug}`],
+        notes: `skill created via mdkg skill new`,
+        runId: options.runId,
+        skill: slug,
+        now: options.now,
+    });
+    console.log(`skill created: root:skill:${slug} (${path_1.default.relative(root, canonicalPath)})`);
+}
+function runSkillListCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const { index, rebuilt, stale } = (0, skills_index_cache_1.loadSkillsIndex)({
+        root: options.root,
+        config,
+        useCache: !options.noCache,
+        allowReindex: !options.noReindex,
+    });
+    if (stale && !rebuilt && !options.noCache) {
+        console.error("warning: skills index is stale; run mdkg index to refresh");
+    }
+    const skills = filterSkills(Object.values(index.skills), options.tags, options.tagsMode ?? "any").sort((a, b) => a.qid.localeCompare(b.qid));
+    if (options.json) {
+        (0, query_output_1.writeJson)({
+            command: "list",
+            kind: "skill",
+            count: skills.length,
+            items: skills.map(query_output_1.toSkillSummaryJson),
+        });
+        return;
+    }
+    (0, query_output_1.writeCount)(skills.length, skills.length === 0 ? "no skills matched current filters" : undefined);
+    for (const skill of skills) {
+        console.log((0, skill_support_1.formatSkillCard)(skill));
+    }
+}
+function runSkillShowCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const slug = normalizeSlug(options.slug);
+    const { index, rebuilt, stale } = (0, skills_index_cache_1.loadSkillsIndex)({
+        root: options.root,
+        config,
+        useCache: !options.noCache,
+        allowReindex: !options.noReindex,
+    });
+    if (stale && !rebuilt && !options.noCache) {
+        console.error("warning: skills index is stale; run mdkg index to refresh");
+    }
+    const skill = index.skills[slug];
+    if (!skill) {
+        throw new errors_1.NotFoundError(`skill not found: ${slug}`);
+    }
+    const skillPath = path_1.default.resolve(options.root, skill.path);
+    let body = "";
+    if (!options.metaOnly) {
+        if (!fs_1.default.existsSync(skillPath)) {
+            throw new errors_1.NotFoundError(`file not found for ${skill.id}: ${skill.path}`);
+        }
+        body = fs_1.default.readFileSync(skillPath, "utf8").trimEnd();
+    }
+    if (options.json) {
+        (0, query_output_1.writeJson)({
+            command: "show",
+            kind: "skill",
+            item: (0, query_output_1.toSkillDetailJson)(skill, options.metaOnly ? undefined : body),
+        });
+        return;
+    }
+    if (options.metaOnly) {
+        const lines = [];
+        lines.push((0, skill_support_1.formatSkillCard)(skill));
+        lines.push(`description: ${skill.description}`);
+        const tagsLine = maybeLine("tags", skill.tags);
+        if (tagsLine) {
+            lines.push(tagsLine);
+        }
+        if (skill.version) {
+            lines.push(`version: ${skill.version}`);
+        }
+        const authorsLine = maybeLine("authors", skill.authors);
+        if (authorsLine) {
+            lines.push(authorsLine);
+        }
+        const linksLine = maybeLine("links", skill.links);
+        if (linksLine) {
+            lines.push(linksLine);
+        }
+        lines.push(`has_scripts: ${skill.has_scripts ? "true" : "false"}`);
+        lines.push(`has_references: ${skill.has_references ? "true" : "false"}`);
+        for (const [key, value] of Object.entries(skill.ochatr).sort(([a], [b]) => a.localeCompare(b))) {
+            if (Array.isArray(value)) {
+                lines.push(`${key}: ${value.join(", ")}`);
+                continue;
+            }
+            if (typeof value === "boolean") {
+                lines.push(`${key}: ${value ? "true" : "false"}`);
+                continue;
+            }
+            lines.push(`${key}: ${value}`);
+        }
+        console.log(lines.join("\n"));
+        return;
+    }
+    console.log(body);
+}
+function runSkillSearchCommand(options) {
+    const query = options.query.trim();
+    if (!query) {
+        throw new errors_1.UsageError("search query cannot be empty");
+    }
+    const config = (0, config_1.loadConfig)(options.root);
+    const { index, rebuilt, stale } = (0, skills_index_cache_1.loadSkillsIndex)({
+        root: options.root,
+        config,
+        useCache: !options.noCache,
+        allowReindex: !options.noReindex,
+    });
+    if (stale && !rebuilt && !options.noCache) {
+        console.error("warning: skills index is stale; run mdkg index to refresh");
+    }
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const skills = filterSkills(Object.values(index.skills), options.tags, options.tagsMode ?? "any")
+        .filter((skill) => matchesSkillQuery(skill, terms))
+        .sort((a, b) => a.qid.localeCompare(b.qid));
+    if (options.json) {
+        (0, query_output_1.writeJson)({
+            command: "search",
+            kind: "skill",
+            count: skills.length,
+            items: skills.map(query_output_1.toSkillSummaryJson),
+        });
+        return;
+    }
+    (0, query_output_1.writeCount)(skills.length, skills.length === 0 ? `no skills matched query "${query}"` : undefined);
+    for (const skill of skills) {
+        console.log((0, skill_support_1.formatSkillCard)(skill));
+    }
+}
+function runSkillValidateCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const targetSlug = options.slug?.trim().toLowerCase();
+    const warnings = [];
+    const errors = [];
+    if (targetSlug) {
+        const result = validateSingleSkill(options.root, normalizeSlug(targetSlug));
+        warnings.push(...result.warnings);
+        errors.push(...result.errors);
+    }
+    else {
+        const skillsRoot = (0, skills_indexer_1.resolveSkillsRoot)(options.root, config);
+        if (fs_1.default.existsSync(skillsRoot)) {
+            const entries = fs_1.default.readdirSync(skillsRoot, { withFileTypes: true });
+            for (const entry of entries.filter((value) => value.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+                const result = validateSingleSkill(options.root, entry.name.toLowerCase());
+                warnings.push(...result.warnings);
+                errors.push(...result.errors);
+            }
+        }
+    }
+    for (const warning of Array.from(new Set(warnings))) {
+        console.error(`warning: ${warning}`);
+    }
+    if (errors.length > 0) {
+        for (const error of Array.from(new Set(errors))) {
+            console.error(error);
+        }
+        throw new errors_1.ValidationError(`skill validation failed with ${Array.from(new Set(errors)).length} error(s)`);
+    }
+    if (targetSlug) {
+        console.log(`skill validation ok: ${targetSlug} (1 skill checked)`);
+        return;
+    }
+    const checkedCount = fs_1.default.existsSync((0, skills_indexer_1.resolveSkillsRoot)(options.root, config))
+        ? fs_1.default
+            .readdirSync((0, skills_indexer_1.resolveSkillsRoot)(options.root, config), { withFileTypes: true })
+            .filter((value) => value.isDirectory()).length
+        : 0;
+    console.log(`skill validation ok: ${checkedCount} skill${checkedCount === 1 ? "" : "s"} checked`);
+}
+function runSkillSyncCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const result = (0, skill_mirror_1.syncSkillMirrors)({
+        root: options.root,
+        config,
+        createRoots: true,
+        force: options.force,
+    });
+    console.log(`skill mirror sync ok: ${result.synced} synced, ${result.pruned} pruned across ${result.targets} target${result.targets === 1 ? "" : "s"}`);
+}

package/dist/commands/skill_mirror.js

@@ -0,0 +1,290 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncSkillMirrors = syncSkillMirrors;
+exports.shouldMaintainSkillMirrors = shouldMaintainSkillMirrors;
+exports.auditSkillMirrors = auditSkillMirrors;
+exports.scaffoldMirrorRoots = scaffoldMirrorRoots;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const skills_indexer_1 = require("../graph/skills_indexer");
+const errors_1 = require("../util/errors");
+const MIRROR_PRODUCTS = ["agents", "claude"];
+const MANIFEST_FILE = ".mdkg-managed.json";
+const MANAGED_ROOT_MARKERS = [
+    path_1.default.join(".mdkg", "core", "SOUL.md"),
+    path_1.default.join(".mdkg", "core", "HUMAN.md"),
+];
+const ALLOWED_ROOT_ENTRIES = ["SKILL.md", "references", "assets", "scripts"];
+function resolveMirrorTargets(root) {
+    return MIRROR_PRODUCTS.map((product) => {
+        const rootDir = path_1.default.join(root, `.${product}`);
+        const skillsRoot = path_1.default.join(rootDir, "skills");
+        return {
+            product,
+            rootDir,
+            skillsRoot,
+            manifestPath: path_1.default.join(skillsRoot, MANIFEST_FILE),
+        };
+    });
+}
+function readManifest(target) {
+    if (!fs_1.default.existsSync(target.manifestPath)) {
+        return new Set();
+    }
+    try {
+        const parsed = JSON.parse(fs_1.default.readFileSync(target.manifestPath, "utf8"));
+        if (!Array.isArray(parsed.managed_slugs)) {
+            return new Set();
+        }
+        return new Set(parsed.managed_slugs
+            .map((value) => String(value).trim().toLowerCase())
+            .filter(Boolean));
+    }
+    catch {
+        return new Set();
+    }
+}
+function writeManifest(target, managed) {
+    const payload = {
+        managed_slugs: Array.from(new Set(Array.from(managed).map((value) => value.toLowerCase()))).sort(),
+    };
+    fs_1.default.mkdirSync(target.skillsRoot, { recursive: true });
+    fs_1.default.writeFileSync(target.manifestPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+function shouldCreateMirrorRoots(root) {
+    if (MANAGED_ROOT_MARKERS.some((relPath) => fs_1.default.existsSync(path_1.default.join(root, relPath)))) {
+        return true;
+    }
+    return resolveMirrorTargets(root).some((target) => fs_1.default.existsSync(target.rootDir) || fs_1.default.existsSync(target.skillsRoot));
+}
+function listAllowedEntries(dirPath) {
+    if (!fs_1.default.existsSync(dirPath)) {
+        return [];
+    }
+    const entries = [];
+    const queue = [dirPath];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const dirEntries = fs_1.default.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of dirEntries) {
+            const fullPath = path_1.default.join(current, entry.name);
+            const relPath = path_1.default.relative(dirPath, fullPath).replace(/\\/g, "/");
+            if (entry.isDirectory()) {
+                entries.push(`${relPath}/`);
+                queue.push(fullPath);
+            }
+            else if (entry.isFile()) {
+                entries.push(relPath);
+            }
+        }
+    }
+    return entries.sort();
+}
+function resolveSkillDocPath(skillDir) {
+    const canonicalPath = path_1.default.join(skillDir, "SKILL.md");
+    const compatPath = path_1.default.join(skillDir, "SKILLS.md");
+    if (fs_1.default.existsSync(canonicalPath) && fs_1.default.existsSync(compatPath)) {
+        throw new errors_1.UsageError(`${skillDir}: both SKILL.md and SKILLS.md exist; fix the canonical skill first`);
+    }
+    if (fs_1.default.existsSync(canonicalPath)) {
+        return canonicalPath;
+    }
+    if (fs_1.default.existsSync(compatPath)) {
+        return compatPath;
+    }
+    throw new errors_1.UsageError(`${skillDir}: missing SKILL.md or SKILLS.md`);
+}
+function loadCanonicalSources(root, config) {
+    const index = (0, skills_indexer_1.buildSkillsIndex)(root, config);
+    return Object.values(index.skills)
+        .sort((a, b) => a.slug.localeCompare(b.slug))
+        .map((entry) => {
+        const docPath = path_1.default.resolve(root, entry.path);
+        return {
+            slug: entry.slug,
+            sourceDir: path_1.default.dirname(docPath),
+            docPath,
+        };
+    });
+}
+function copyDir(srcDir, destDir) {
+    fs_1.default.mkdirSync(destDir, { recursive: true });
+    const entries = fs_1.default.readdirSync(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path_1.default.join(srcDir, entry.name);
+        const destPath = path_1.default.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else if (entry.isFile()) {
+            fs_1.default.mkdirSync(path_1.default.dirname(destPath), { recursive: true });
+            fs_1.default.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+function materializeSkillMirror(source, destDir) {
+    fs_1.default.rmSync(destDir, { recursive: true, force: true });
+    fs_1.default.mkdirSync(destDir, { recursive: true });
+    fs_1.default.copyFileSync(source.docPath, path_1.default.join(destDir, "SKILL.md"));
+    for (const entry of ["references", "assets", "scripts"]) {
+        const srcPath = path_1.default.join(source.sourceDir, entry);
+        if (fs_1.default.existsSync(srcPath) && fs_1.default.statSync(srcPath).isDirectory()) {
+            copyDir(srcPath, path_1.default.join(destDir, entry));
+        }
+    }
+}
+function collectExpectedSkillTree(source) {
+    const expected = new Map();
+    expected.set("SKILL.md", fs_1.default.readFileSync(source.docPath, "utf8"));
+    for (const entry of ["references", "assets", "scripts"]) {
+        const srcPath = path_1.default.join(source.sourceDir, entry);
+        if (!fs_1.default.existsSync(srcPath) || !fs_1.default.statSync(srcPath).isDirectory()) {
+            continue;
+        }
+        expected.set(`${entry}/`, "dir");
+        for (const relPath of listAllowedEntries(srcPath)) {
+            const absolute = path_1.default.join(srcPath, relPath.replace(/\/$/, ""));
+            expected.set(`${entry}/${relPath}`, relPath.endsWith("/") ? "dir" : fs_1.default.readFileSync(absolute, "utf8"));
+        }
+    }
+    return expected;
+}
+function collectActualSkillTree(destDir) {
+    const entries = new Map();
+    if (!fs_1.default.existsSync(destDir)) {
+        return { entries, hasUnexpectedRootEntry: false };
+    }
+    const rootEntries = fs_1.default.readdirSync(destDir, { withFileTypes: true });
+    let hasUnexpectedRootEntry = false;
+    for (const entry of rootEntries) {
+        if (!ALLOWED_ROOT_ENTRIES.includes(entry.name)) {
+            hasUnexpectedRootEntry = true;
+            continue;
+        }
+        const fullPath = path_1.default.join(destDir, entry.name);
+        if (entry.isFile()) {
+            entries.set(entry.name, fs_1.default.readFileSync(fullPath, "utf8"));
+            continue;
+        }
+        if (!entry.isDirectory()) {
+            hasUnexpectedRootEntry = true;
+            continue;
+        }
+        entries.set(`${entry.name}/`, "dir");
+        for (const relPath of listAllowedEntries(fullPath)) {
+            const absolute = path_1.default.join(fullPath, relPath.replace(/\/$/, ""));
+            entries.set(`${entry.name}/${relPath}`, relPath.endsWith("/") ? "dir" : fs_1.default.readFileSync(absolute, "utf8"));
+        }
+    }
+    return { entries, hasUnexpectedRootEntry };
+}
+function isManagedSkillTreeInSync(source, destDir) {
+    const expected = collectExpectedSkillTree(source);
+    const actual = collectActualSkillTree(destDir);
+    if (actual.hasUnexpectedRootEntry) {
+        return false;
+    }
+    if (expected.size !== actual.entries.size) {
+        return false;
+    }
+    for (const [relPath, content] of expected.entries()) {
+        if (!actual.entries.has(relPath) || actual.entries.get(relPath) !== content) {
+            return false;
+        }
+    }
+    return true;
+}
+function syncSkillMirrors(options) {
+    const sources = loadCanonicalSources(options.root, options.config);
+    const createRoots = Boolean(options.createRoots);
+    const force = Boolean(options.force);
+    const targets = resolveMirrorTargets(options.root);
+    let synced = 0;
+    let pruned = 0;
+    let touchedTargets = 0;
+    for (const target of targets) {
+        const shouldManageTarget = createRoots || fs_1.default.existsSync(target.skillsRoot) || fs_1.default.existsSync(target.rootDir);
+        if (!shouldManageTarget) {
+            continue;
+        }
+        touchedTargets += 1;
+        fs_1.default.mkdirSync(target.skillsRoot, { recursive: true });
+        const managed = readManifest(target);
+        for (const source of sources) {
+            const destDir = path_1.default.join(target.skillsRoot, source.slug);
+            const exists = fs_1.default.existsSync(destDir);
+            if (exists && !managed.has(source.slug) && !force) {
+                throw new errors_1.UsageError(`${path_1.default.relative(options.root, destDir)} already exists and is not mdkg-managed; rerun \`mdkg skill sync --force\` to replace it`);
+            }
+            materializeSkillMirror(source, destDir);
+            managed.add(source.slug);
+            synced += 1;
+        }
+        for (const slug of Array.from(managed)) {
+            if (sources.some((source) => source.slug === slug)) {
+                continue;
+            }
+            const destDir = path_1.default.join(target.skillsRoot, slug);
+            if (fs_1.default.existsSync(destDir)) {
+                fs_1.default.rmSync(destDir, { recursive: true, force: true });
+                pruned += 1;
+            }
+            managed.delete(slug);
+        }
+        writeManifest(target, managed);
+    }
+    return { synced, pruned, targets: touchedTargets };
+}
+function shouldMaintainSkillMirrors(root) {
+    return shouldCreateMirrorRoots(root);
+}
+function auditSkillMirrors(root, config) {
+    const shouldAudit = shouldCreateMirrorRoots(root);
+    if (!shouldAudit) {
+        return [];
+    }
+    const warnings = [];
+    const sources = loadCanonicalSources(root, config);
+    const sourceBySlug = new Map(sources.map((source) => [source.slug, source]));
+    for (const target of resolveMirrorTargets(root)) {
+        if (!fs_1.default.existsSync(target.skillsRoot)) {
+            warnings.push(`${path_1.default.relative(root, target.skillsRoot)}: mirror root missing; run \`mdkg skill sync\``);
+            continue;
+        }
+        const managed = readManifest(target);
+        if (!fs_1.default.existsSync(target.manifestPath)) {
+            warnings.push(`${path_1.default.relative(root, target.manifestPath)}: mirror manifest missing; run \`mdkg skill sync\``);
+        }
+        for (const source of sources) {
+            const destDir = path_1.default.join(target.skillsRoot, source.slug);
+            if (!fs_1.default.existsSync(destDir)) {
+                warnings.push(`${path_1.default.relative(root, destDir)}: missing mirrored skill; run \`mdkg skill sync\``);
+                continue;
+            }
+            if (!managed.has(source.slug)) {
+                warnings.push(`${path_1.default.relative(root, destDir)}: conflicting unmanaged mirror; rerun \`mdkg skill sync --force\` to replace it`);
+                continue;
+            }
+            if (!isManagedSkillTreeInSync(source, destDir)) {
+                warnings.push(`${path_1.default.relative(root, destDir)}: mirrored skill drift detected; run \`mdkg skill sync\``);
+            }
+        }
+        for (const slug of managed) {
+            if (!sourceBySlug.has(slug)) {
+                warnings.push(`${path_1.default.relative(root, path_1.default.join(target.skillsRoot, slug))}: stale mirrored skill; run \`mdkg skill sync\``);
+            }
+        }
+    }
+    return warnings;
+}
+function scaffoldMirrorRoots(root) {
+    for (const target of resolveMirrorTargets(root)) {
+        fs_1.default.mkdirSync(target.skillsRoot, { recursive: true });
+        if (!fs_1.default.existsSync(target.manifestPath)) {
+            writeManifest(target, []);
+        }
+    }
+}