mdkg 0.1.0 → 0.1.2

package/dist/graph/capabilities_indexer.js

@@ -0,0 +1,231 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPABILITY_VISIBILITIES = exports.CAPABILITY_KINDS = exports.CAPABILITIES_INDEX_RELATIVE_PATH = void 0;
+exports.resolveCapabilitiesIndexPath = resolveCapabilitiesIndexPath;
+exports.buildCapabilitiesIndex = buildCapabilitiesIndex;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const indexer_1 = require("./indexer");
+const skills_indexer_1 = require("./skills_indexer");
+exports.CAPABILITIES_INDEX_RELATIVE_PATH = ".mdkg/index/capabilities.json";
+exports.CAPABILITY_KINDS = ["skill", "spec", "work", "core", "design"];
+exports.CAPABILITY_VISIBILITIES = ["private", "internal", "public"];
+const CAPABILITY_CACHE_VERSION = 1;
+function toPosixPath(value) {
+    return value.split(path_1.default.sep).join("/");
+}
+function sourceHash(content) {
+    return `sha256:${crypto_1.default.createHash("sha256").update(content).digest("hex")}`;
+}
+function extractHeadings(content) {
+    const headings = [];
+    for (const line of content.split(/\r?\n/)) {
+        const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        headings.push({ level: match[1].length, text: match[2].trim() });
+    }
+    return headings;
+}
+function workspaceVisibility(config, alias) {
+    return config.workspaces[alias]?.visibility ?? "private";
+}
+function workspaceMdkgPrefix(entry) {
+    const wsPath = entry.path === "." ? "" : `${toPosixPath(entry.path).replace(/\/+$/, "")}/`;
+    const mdkgDir = toPosixPath(entry.mdkg_dir).replace(/^\/+|\/+$/g, "");
+    return `${wsPath}${mdkgDir}/`;
+}
+function classifyNodeCapability(node, config) {
+    if (node.type === "spec") {
+        return "spec";
+    }
+    if (node.type === "work") {
+        return "work";
+    }
+    const workspace = config.workspaces[node.ws];
+    if (!workspace) {
+        return undefined;
+    }
+    const nodePath = toPosixPath(node.path);
+    const prefix = workspaceMdkgPrefix(workspace);
+    if (!nodePath.startsWith(prefix)) {
+        return undefined;
+    }
+    const relativeToMdkg = nodePath.slice(prefix.length);
+    if (relativeToMdkg.startsWith("core/")) {
+        return "core";
+    }
+    if (relativeToMdkg.startsWith("design/")) {
+        return "design";
+    }
+    return undefined;
+}
+function pickAttributes(attributes, keys) {
+    const picked = {};
+    for (const key of keys) {
+        if (attributes[key] !== undefined) {
+            picked[key] = attributes[key];
+        }
+    }
+    return picked;
+}
+function nodeCapabilityRecord(root, config, node, kind, indexedAt) {
+    const absolutePath = path_1.default.resolve(root, node.path);
+    const content = fs_1.default.readFileSync(absolutePath, "utf8");
+    const record = {
+        kind,
+        workspace: node.ws,
+        visibility: workspaceVisibility(config, node.ws),
+        id: node.id,
+        qid: node.qid,
+        path: toPosixPath(node.path),
+        title: node.title,
+        tags: [...node.tags],
+        refs: [...node.refs],
+        aliases: [...node.aliases],
+        links: [...node.links],
+        artifacts: [...node.artifacts],
+        updated: node.updated,
+        indexed_at: indexedAt,
+        source_hash: sourceHash(content),
+        headings: extractHeadings(content),
+        node_type: node.type,
+    };
+    if (kind === "spec") {
+        record.spec = pickAttributes(node.attributes, [
+            "version",
+            "role",
+            "runtime_mode",
+            "work_contracts",
+            "requested_capabilities",
+            "skill_refs",
+            "tool_refs",
+            "model_refs",
+            "wasm_component_refs",
+            "runtime_image_refs",
+            "subagent_refs",
+            "resource_profile",
+            "update_policy",
+        ]);
+    }
+    if (kind === "work") {
+        record.work = pickAttributes(node.attributes, [
+            "version",
+            "agent_id",
+            "kind",
+            "pricing_model",
+            "required_capabilities",
+            "skill_refs",
+            "tool_refs",
+            "model_refs",
+            "wasm_component_refs",
+            "runtime_image_refs",
+            "subagent_refs",
+            "inputs",
+            "outputs",
+            "receipt_required",
+        ]);
+    }
+    return record;
+}
+function skillCapabilityRecord(root, config, skill, indexedAt) {
+    const absolutePath = path_1.default.resolve(root, skill.path);
+    const content = fs_1.default.readFileSync(absolutePath, "utf8");
+    return {
+        kind: "skill",
+        workspace: skill.ws,
+        visibility: workspaceVisibility(config, skill.ws),
+        id: skill.id,
+        qid: skill.qid,
+        path: toPosixPath(skill.path),
+        title: skill.name,
+        name: skill.name,
+        description: skill.description,
+        slug: skill.slug,
+        tags: [...skill.tags],
+        refs: [],
+        aliases: [skill.slug, ...skill.tags],
+        links: [...skill.links],
+        artifacts: [],
+        indexed_at: indexedAt,
+        source_hash: sourceHash(content),
+        headings: extractHeadings(content),
+        skill: {
+            version: skill.version,
+            authors: [...skill.authors],
+            has_scripts: skill.has_scripts,
+            has_references: skill.has_references,
+            extensions: skill.extensions,
+        },
+    };
+}
+function workspaceSkillsRoot(root, entry) {
+    return path_1.default.resolve(root, entry.path, entry.mdkg_dir, "skills");
+}
+function buildWorkspaceSkillCapabilities(root, config, indexedAt) {
+    const records = [];
+    for (const alias of Object.keys(config.workspaces).sort()) {
+        const workspace = config.workspaces[alias];
+        if (!workspace.enabled) {
+            continue;
+        }
+        const skillsRoot = workspaceSkillsRoot(root, workspace);
+        for (const candidate of (0, skills_indexer_1.listSkillMarkdownFiles)(skillsRoot)) {
+            const skill = (0, skills_indexer_1.buildSkillIndexEntryForWorkspace)(root, alias, candidate.slug, candidate.filePath);
+            records.push(skillCapabilityRecord(root, config, skill, indexedAt));
+        }
+    }
+    return records;
+}
+function sortRecords(records) {
+    return [...records].sort((a, b) => {
+        for (const [left, right] of [
+            [a.workspace, b.workspace],
+            [a.kind, b.kind],
+            [a.id, b.id],
+            [a.path, b.path],
+        ]) {
+            const compared = left.localeCompare(right);
+            if (compared !== 0) {
+                return compared;
+            }
+        }
+        return 0;
+    });
+}
+function resolveCapabilitiesIndexPath(root, config) {
+    return path_1.default.resolve(root, config.capabilities.cache_path);
+}
+function buildCapabilitiesIndex(root, config, nodeIndex) {
+    const index = nodeIndex ?? (0, indexer_1.buildIndex)(root, config);
+    const records = [];
+    const generatedAt = new Date().toISOString();
+    for (const node of Object.values(index.nodes)) {
+        const kind = classifyNodeCapability(node, config);
+        if (!kind) {
+            continue;
+        }
+        records.push(nodeCapabilityRecord(root, config, node, kind, generatedAt));
+    }
+    records.push(...buildWorkspaceSkillCapabilities(root, config, generatedAt));
+    const sortedRecords = sortRecords(records);
+    return {
+        meta: {
+            tool: config.tool,
+            schema_version: config.schema_version,
+            cache_version: CAPABILITY_CACHE_VERSION,
+            generated_at: generatedAt,
+            root,
+            workspaces: Object.keys(config.workspaces)
+                .filter((alias) => config.workspaces[alias].enabled)
+                .sort(),
+            record_count: sortedRecords.length,
+        },
+        records: sortedRecords,
+    };
+}

package/dist/graph/frontmatter.js

@@ -48,6 +48,25 @@ exports.DEFAULT_FRONTMATTER_KEY_ORDER = [
     "proposal_status",
     "proposal_kind",
     "evidence_refs",
+    "archive_kind",
+    "source_path",
+    "stored_path",
+    "compressed_path",
+    "mime_type",
+    "byte_size",
+    "sha256",
+    "compressed_sha256",
+    "visibility",
+    "provenance",
+    "ingest_status",
+    "input_refs",
+    "requested_outputs",
+    "constraint_refs",
+    "artifact_policy",
+    "proof_refs",
+    "attestation_refs",
+    "input_hashes",
+    "output_hashes",
     "tags",
     "owners",
     "links",

package/dist/graph/index_cache.js

@@ -10,6 +10,7 @@ const path_1 = __importDefault(require("path"));
 const sort_1 = require("../util/sort");
 const indexer_1 = require("./indexer");
 const staleness_1 = require("./staleness");
+const bundle_imports_1 = require("./bundle_imports");
 function readIndex(indexPath) {
     try {
         const raw = fs_1.default.readFileSync(indexPath, "utf8");
@@ -29,22 +30,38 @@ function loadIndex(options) {
     const useCache = options.useCache ?? true;
     const allowReindex = options.allowReindex ?? options.config.index.auto_reindex;
     const tolerant = options.tolerant ?? options.config.index.tolerant;
+    const includeImports = options.includeImports ?? true;
     const indexPath = path_1.default.resolve(options.root, options.config.index.global_index_path);
+    const withImports = (index, rebuilt, stale) => {
+        if (!includeImports || Object.keys(options.config.bundle_imports).length === 0) {
+            return { index, rebuilt, stale, warnings: [] };
+        }
+        const imports = (0, bundle_imports_1.buildBundleImportsIndex)(options.root, options.config);
+        if (allowReindex) {
+            (0, bundle_imports_1.writeBundleImportsIndex)((0, bundle_imports_1.resolveBundleImportsIndexPath)(options.root), imports.index);
+        }
+        return {
+            index: (0, bundle_imports_1.mergeBundleImportsIntoIndex)(index, imports),
+            rebuilt,
+            stale: stale || (0, bundle_imports_1.isBundleImportsIndexStale)(options.root, options.config),
+            warnings: (0, bundle_imports_1.importWarnings)(imports),
+        };
+    };
     if (!useCache) {
         const index = (0, indexer_1.buildIndex)(options.root, options.config, { tolerant });
-        return { index, rebuilt: true, stale: false };
+        return withImports(index, true, false);
     }
     const stale = (0, staleness_1.isIndexStale)(options.root, options.config);
     if (fs_1.default.existsSync(indexPath) && !stale) {
-        return { index: readIndex(indexPath), rebuilt: false, stale: false };
+        return withImports(readIndex(indexPath), false, false);
     }
     if (allowReindex) {
         const index = (0, indexer_1.buildIndex)(options.root, options.config, { tolerant });
         writeIndex(indexPath, index);
-        return { index, rebuilt: true, stale };
+        return withImports(index, true, stale);
     }
     if (fs_1.default.existsSync(indexPath)) {
-        return { index: readIndex(indexPath), rebuilt: false, stale: true };
+        return withImports(readIndex(indexPath), false, true);
     }
     throw new Error("index missing and auto-reindex is disabled");
 }

package/dist/graph/indexer.js

@@ -141,7 +141,10 @@ function buildIndex(root, config, options = {}) {
         nodes,
         reverse_edges,
     };
-    (0, validate_graph_1.validateGraph)(index, { allowMissing: tolerant });
+    (0, validate_graph_1.validateGraph)(index, {
+        allowMissing: tolerant,
+        externalWorkspaces: new Set(Object.keys(config.bundle_imports ?? {})),
+    });
     const latestCheckpointByWorkspace = {};
     for (const alias of workspaceAliases) {
         const candidates = Object.values(nodes)

package/dist/graph/node.js

@@ -5,7 +5,9 @@ exports.parseNode = parseNode;
 const frontmatter_1 = require("./frontmatter");
 const edges_1 = require("./edges");
 const agent_file_types_1 = require("./agent_file_types");
+const archive_file_1 = require("./archive_file");
 const id_1 = require("../util/id");
+const refs_1 = require("../util/refs");
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const DEC_ID_RE = /^dec-[0-9]+$/;
 exports.WORK_TYPES = new Set(["epic", "feat", "task", "bug", "checkpoint", "test"]);
@@ -22,6 +24,7 @@ exports.ALLOWED_TYPES = new Set([
     "bug",
     "checkpoint",
     "test",
+    "archive",
     ...agent_file_types_1.AGENT_FILE_TYPES,
 ]);
 const DEC_STATUS = new Set(["proposed", "accepted", "rejected", "superseded"]);
@@ -119,6 +122,17 @@ function normalizeIdList(values, key, filePath, allowPortableIds = false) {
         return value;
     });
 }
+function normalizeRefsList(values, key, filePath, allowPortableOrUriRefs = false) {
+    if (!allowPortableOrUriRefs) {
+        return normalizeIdList(values, key, filePath);
+    }
+    return values.map((value) => {
+        if (!(0, refs_1.validatePortableOrUriRef)(value)) {
+            throw formatError(filePath, `${key} entries must be portable ids or URI refs`);
+        }
+        return value;
+    });
+}
 function normalizeSkillList(values, filePath) {
     return values.map((value, index) => {
         const normalized = value.toLowerCase();
@@ -166,11 +180,13 @@ function parseNode(content, filePath, options) {
         throw formatError(filePath, `type must be one of ${Array.from(exports.ALLOWED_TYPES).join(", ")}`);
     }
     const isAgentType = (0, agent_file_types_1.isAgentFileType)(type);
+    const isPortableType = isAgentType || (0, archive_file_1.isArchiveType)(type);
     const schema = requireTemplateSchema(type, options.templateSchemas, filePath);
     validateTemplateKeys(frontmatter, schema, filePath);
     (0, agent_file_types_1.validateAgentFrontmatter)(type, frontmatter, filePath);
+    (0, archive_file_1.validateArchiveFrontmatter)(type, frontmatter, filePath);
     const idValue = requireLowercase(expectString(frontmatter, "id", filePath), "id", filePath);
-    const id = isAgentType
+    const id = isPortableType
         ? requirePortableIdFormat(idValue, "id", filePath)
         : requireIdFormat(idValue, "id", filePath);
     const title = expectString(frontmatter, "title", filePath);
@@ -214,7 +230,7 @@ function parseNode(content, filePath, options) {
     const owners = requireLowercaseList(optionalList(frontmatter, "owners", filePath), "owners", filePath);
     const links = optionalList(frontmatter, "links", filePath);
     const artifacts = optionalList(frontmatter, "artifacts", filePath);
-    const refs = normalizeIdList(optionalList(frontmatter, "refs", filePath), "refs", filePath, isAgentType);
+    const refs = normalizeRefsList(optionalList(frontmatter, "refs", filePath), "refs", filePath, isPortableType);
     const aliases = requireLowercaseList(optionalList(frontmatter, "aliases", filePath), "aliases", filePath);
     const skillsRaw = optionalList(frontmatter, "skills", filePath);
     const skills = normalizeSkillList(skillsRaw, filePath);
@@ -232,8 +248,11 @@ function parseNode(content, filePath, options) {
             throw formatError(filePath, "supersedes must be a dec-# id");
         }
     }
-    const edges = (0, edges_1.extractEdges)(frontmatter, filePath, { allowPortableRefs: isAgentType });
-    const attributes = (0, agent_file_types_1.extractAgentAttributes)(type, frontmatter);
+    const edges = (0, edges_1.extractEdges)(frontmatter, filePath, { allowPortableRefs: isPortableType });
+    const attributes = {
+        ...(0, agent_file_types_1.extractAgentAttributes)(type, frontmatter),
+        ...(0, archive_file_1.extractArchiveAttributes)(type, frontmatter),
+    };
     return {
         id,
         type,

package/dist/graph/node_body.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readNodeBody = readNodeBody;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const frontmatter_1 = require("./frontmatter");
+const zip_1 = require("../util/zip");
+const errors_1 = require("../util/errors");
+function readImportedBody(root, node) {
+    const source = node.source;
+    if (!source?.imported) {
+        throw new Error("node is not imported");
+    }
+    const bundlePath = path_1.default.resolve(root, source.bundle_path);
+    if (!fs_1.default.existsSync(bundlePath)) {
+        throw new errors_1.NotFoundError(`bundle not found for ${node.qid}: ${source.bundle_path}`);
+    }
+    const entry = (0, zip_1.readZipEntries)(fs_1.default.readFileSync(bundlePath)).find((candidate) => candidate.name === source.original_path);
+    if (!entry) {
+        throw new errors_1.NotFoundError(`bundle entry not found for ${node.qid}: ${source.original_path}`);
+    }
+    return (0, frontmatter_1.parseFrontmatter)(entry.data.toString("utf8"), source.original_path).body.trimEnd();
+}
+function readNodeBody(root, node) {
+    if (node.source?.imported) {
+        return readImportedBody(root, node);
+    }
+    const filePath = path_1.default.resolve(root, node.path);
+    if (!fs_1.default.existsSync(filePath)) {
+        throw new errors_1.NotFoundError(`file not found for ${node.qid}: ${node.path}`);
+    }
+    const content = fs_1.default.readFileSync(filePath, "utf8");
+    return (0, frontmatter_1.parseFrontmatter)(content, filePath).body.trimEnd();
+}

package/dist/graph/skills_indexer.js

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SKILL_SLUG_RE = exports.SKILLS_INDEX_RELATIVE_PATH = void 0;
+exports.listSkillMarkdownFiles = listSkillMarkdownFiles;
 exports.resolveSkillsRoot = resolveSkillsRoot;
 exports.resolveSkillsIndexPath = resolveSkillsIndexPath;
+exports.buildSkillIndexEntryForWorkspace = buildSkillIndexEntryForWorkspace;
 exports.buildSkillIndexEntry = buildSkillIndexEntry;
 exports.buildSkillsIndex = buildSkillsIndex;
 const fs_1 = __importDefault(require("fs"));
@@ -107,7 +109,7 @@ function resolveSkillsRoot(root, config) {
 function resolveSkillsIndexPath(root) {
     return path_1.default.resolve(root, exports.SKILLS_INDEX_RELATIVE_PATH);
 }
-function buildSkillIndexEntry(root, slug, filePath) {
+function buildSkillIndexEntryForWorkspace(root, workspace, slug, filePath) {
     if (!exports.SKILL_SLUG_RE.test(slug)) {
         throw new Error(`${filePath}: skill slug must be kebab-case`);
     }
@@ -128,8 +130,8 @@ function buildSkillIndexEntry(root, slug, filePath) {
     return {
         slug,
         id: `skill:${slug}`,
-        qid: `root:skill:${slug}`,
-        ws: "root",
+        qid: `${workspace}:skill:${slug}`,
+        ws: workspace,
         type: "skill",
         name,
         description,
@@ -144,6 +146,9 @@ function buildSkillIndexEntry(root, slug, filePath) {
         ochatr,
     };
 }
+function buildSkillIndexEntry(root, slug, filePath) {
+    return buildSkillIndexEntryForWorkspace(root, "root", slug, filePath);
+}
 function buildSkillsIndex(root, config) {
     const skillsRoot = resolveSkillsRoot(root, config);
     const files = listSkillMarkdownFiles(skillsRoot);

package/dist/graph/template_schema.js

@@ -4,9 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadTemplateSchemas = loadTemplateSchemas;
+exports.loadTemplateSchemasWithInfo = loadTemplateSchemasWithInfo;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const frontmatter_1 = require("./frontmatter");
+const builtin_1 = require("../templates/builtin");
 function listMarkdownFiles(dir) {
     if (!fs_1.default.existsSync(dir)) {
         return [];
@@ -45,9 +47,12 @@ function addKeyToSchema(schema, key, kind, filePath) {
     }
 }
 function loadTemplateSchemas(root, config, requiredTypes) {
+    return loadTemplateSchemasWithInfo(root, config, requiredTypes).schemas;
+}
+function loadTemplateSchemasWithInfo(root, config, requiredTypes) {
     const templateRoot = path_1.default.resolve(root, config.templates.root_path, config.templates.default_set);
     const files = listMarkdownFiles(templateRoot);
-    if (files.length === 0) {
+    if (files.length === 0 && !requiredTypes) {
         throw new Error(`no templates found at ${templateRoot}`);
     }
     const schemas = {};
@@ -75,12 +80,35 @@ function loadTemplateSchemas(root, config, requiredTypes) {
             addKeyToSchema(schema, key, kind, filePath);
         }
     }
+    const fallbackTypes = [];
     if (requiredTypes) {
         const required = Array.from(requiredTypes, (value) => value.toLowerCase());
-        const missing = required.filter((value) => !schemas[value]);
-        if (missing.length > 0) {
-            throw new Error(`template schema missing for type(s): ${missing.join(", ")}`);
+        for (const missingType of required.filter((value) => !schemas[value])) {
+            const bundledPath = (0, builtin_1.requireBundledTemplatePath)(missingType);
+            const content = fs_1.default.readFileSync(bundledPath, "utf8");
+            const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, bundledPath);
+            const typeValue = frontmatter.type;
+            if (typeValue !== missingType) {
+                throw new Error(`bundled template fallback type mismatch for ${missingType}: ${bundledPath}`);
+            }
+            const schema = {
+                type: missingType,
+                allowedKeys: new Set(),
+                keyKinds: {},
+                listKeys: new Set(),
+            };
+            schemas[missingType] = schema;
+            for (const [key, value] of Object.entries(frontmatter)) {
+                const kind = getValueKind(value);
+                addKeyToSchema(schema, key, kind, bundledPath);
+            }
+            fallbackTypes.push(missingType);
         }
     }
-    return schemas;
+    return {
+        schemas,
+        templateRoot,
+        bundledTemplateRoot: (0, builtin_1.resolveBundledTemplateRoot)(),
+        fallbackTypes,
+    };
 }