mdkg 0.0.2 → 0.0.4

package/dist/commands/skill.js

@@ -0,0 +1,359 @@
+"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;
+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");
+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 (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`);
+}

package/dist/commands/skill_support.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_REGISTRY_END = exports.SKILL_REGISTRY_START = void 0;
+exports.resolveSkillTemplatePath = resolveSkillTemplatePath;
+exports.loadSkillTemplate = loadSkillTemplate;
+exports.renderSkillTemplate = renderSkillTemplate;
+exports.registryTemplate = registryTemplate;
+exports.ensureSkillsRegistry = ensureSkillsRegistry;
+exports.refreshSkillsRegistry = refreshSkillsRegistry;
+exports.formatSkillCard = formatSkillCard;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const skills_indexer_1 = require("../graph/skills_indexer");
+exports.SKILL_REGISTRY_START = "<!-- mdkg:skill-registry:start -->";
+exports.SKILL_REGISTRY_END = "<!-- mdkg:skill-registry:end -->";
+function renderYamlList(values) {
+    return `[${values.join(", ")}]`;
+}
+function renderOptionalLine(key, values) {
+    if (values.length === 0) {
+        return "";
+    }
+    return `${key}: ${renderYamlList(values)}\n`;
+}
+function resolveSkillTemplatePath() {
+    return path_1.default.resolve(__dirname, "..", "init", "skills", "SKILL.md.example");
+}
+function loadSkillTemplate() {
+    const templatePath = resolveSkillTemplatePath();
+    if (!fs_1.default.existsSync(templatePath)) {
+        throw new Error(`missing skill template artifact: ${templatePath}`);
+    }
+    return fs_1.default.readFileSync(templatePath, "utf8");
+}
+function renderSkillTemplate(data) {
+    const template = loadSkillTemplate();
+    return template
+        .replace("{{name}}", data.name)
+        .replace("{{description}}", data.description)
+        .replace("{{tags_block}}", renderOptionalLine("tags", data.tags))
+        .replace("{{authors_block}}", renderOptionalLine("authors", data.authors))
+        .replace("{{links_block}}", renderOptionalLine("links", data.links));
+}
+function registryTemplate() {
+    return [
+        "# Skills Registry",
+        "",
+        "This directory stores Agent Skills packages used by mdkg tooling and orchestrators.",
+        "",
+        "Use `mdkg skill new <slug> \"<name>\" --description \"...\"` to scaffold a new skill from the built-in Anthropic-aligned template.",
+        "Use `CLI_COMMAND_MATRIX.md` as the canonical command and flag reference when updating skill procedures.",
+        "",
+        "## Conventions",
+        "",
+        "- One folder per skill slug.",
+        "- Use `SKILL.md` as the canonical skill entrypoint.",
+        "- Keep procedures deterministic and avoid embedding secrets.",
+        "- Create `scripts/` only when deterministic execution cannot be expressed safely as instructions.",
+        "",
+        "## Registered Skills",
+        "",
+        `${exports.SKILL_REGISTRY_START}`,
+        "_No skills registered yet. Run `mdkg skill new` to add one._",
+        `${exports.SKILL_REGISTRY_END}`,
+        "",
+    ].join("\n");
+}
+function renderRegistryLines(skillsIndex) {
+    const skills = Object.values(skillsIndex.skills).sort((a, b) => a.slug.localeCompare(b.slug));
+    if (skills.length === 0) {
+        return ["_No skills registered yet. Run `mdkg skill new` to add one._"];
+    }
+    const lines = [];
+    for (const skill of skills) {
+        lines.push(`- \`${skill.slug}\``);
+        lines.push(`  - name: \`${skill.name}\``);
+        const stageTag = skill.tags.find((tag) => tag.startsWith("stage:"));
+        if (stageTag) {
+            lines.push(`  - stage: \`${stageTag}\``);
+        }
+        const writerTag = skill.tags.find((tag) => tag.startsWith("writer:"));
+        if (writerTag) {
+            lines.push(`  - writer role: \`${writerTag}\``);
+        }
+        lines.push(`  - description: ${skill.description}`);
+    }
+    return lines;
+}
+function replaceManagedSection(raw, lines) {
+    const managed = `${exports.SKILL_REGISTRY_START}\n${lines.join("\n")}\n${exports.SKILL_REGISTRY_END}`;
+    if (raw.includes(exports.SKILL_REGISTRY_START) && raw.includes(exports.SKILL_REGISTRY_END)) {
+        const pattern = new RegExp(`${exports.SKILL_REGISTRY_START}[\\s\\S]*?${exports.SKILL_REGISTRY_END}`, "m");
+        const replaced = raw.replace(pattern, managed);
+        return replaced.endsWith("\n") ? replaced : `${replaced}\n`;
+    }
+    const trimmed = raw.trimEnd();
+    const prefix = trimmed.length > 0 ? `${trimmed}\n\n## Registered Skills\n\n` : "## Registered Skills\n\n";
+    return `${prefix}${managed}\n`;
+}
+function ensureSkillsRegistry(root, config) {
+    const skillsRoot = (0, skills_indexer_1.resolveSkillsRoot)(root, config);
+    const registryPath = path_1.default.join(skillsRoot, "registry.md");
+    if (!fs_1.default.existsSync(registryPath)) {
+        fs_1.default.mkdirSync(path_1.default.dirname(registryPath), { recursive: true });
+        fs_1.default.writeFileSync(registryPath, registryTemplate(), "utf8");
+    }
+    return registryPath;
+}
+function refreshSkillsRegistry(root, config) {
+    const registryPath = ensureSkillsRegistry(root, config);
+    const raw = fs_1.default.readFileSync(registryPath, "utf8");
+    const index = (0, skills_indexer_1.buildSkillsIndex)(root, config);
+    const updated = replaceManagedSection(raw, renderRegistryLines(index));
+    fs_1.default.writeFileSync(registryPath, updated, "utf8");
+}
+function formatSkillCard(skill) {
+    return [skill.qid, "skill", "-/-", skill.name, skill.path].join(" | ");
+}