@kynetic-ai/spec 0.1.2 → 0.3.0

package/dist/parser/meta.js

@@ -7,34 +7,80 @@
  * - Conventions: project rules and standards
  * - Observations: feedback about processes
  */
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { ulid } from 'ulid';
-import { MetaManifestSchema, AgentSchema, WorkflowSchema, ConventionSchema, ObservationSchema, SessionContextSchema, getMetaItemType, } from '../schema/index.js';
-import { readYamlFile, writeYamlFilePreserveFormat, expandIncludePattern, getAuthor } from './yaml.js';
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { ulid } from "ulid";
+import { AgentSchema, ConventionSchema, getMetaItemType, isSkill, MetaManifestSchema, ObservationSchema, SessionContextSchema, SkillSchema, WorkflowRunsFileSchema, WorkflowSchema, } from "../schema/index.js";
+import { expandIncludePattern, getAuthor, readYamlFile, writeYamlFilePreserveFormat, } from "./yaml.js";
 /**
- * Find the meta manifest file (kynetic.meta.yaml)
+ * Find the meta manifest file.
+ *
+ * Discovery algorithm:
+ * 1. Check for explicit name: kynetic.meta.yaml (backward compat)
+ * 2. If not found, scan directory for *.meta.yaml files
+ * 3. For each candidate, validate it contains a 'kynetic_meta:' version field
+ * 4. Return first valid match (alphabetically after explicit name)
+ *
+ * AC: @meta-manifest-discovery ac-1, ac-2, ac-3
  */
 export async function findMetaManifest(specDir) {
-    const candidates = ['kynetic.meta.yaml'];
-    for (const candidate of candidates) {
-        const filePath = path.join(specDir, candidate);
-        try {
-            await fs.access(filePath);
-            return filePath;
-        }
-        catch {
-            // File doesn't exist, try next
+    // AC: @meta-manifest-discovery ac-1, ac-3 - explicit name has priority
+    const priorityPath = path.join(specDir, "kynetic.meta.yaml");
+    try {
+        await fs.access(priorityPath);
+        return priorityPath;
+    }
+    catch {
+        // Continue to glob fallback
+    }
+    // AC: @meta-manifest-discovery ac-2, ac-3 - glob fallback with validation
+    try {
+        const entries = await fs.readdir(specDir);
+        // AC: @meta-manifest-discovery ac-3 - alphabetical order
+        const candidates = entries
+            .filter((f) => f.endsWith(".meta.yaml"))
+            .sort();
+        for (const candidate of candidates) {
+            const filePath = path.join(specDir, candidate);
+            try {
+                const raw = await readYamlFile(filePath);
+                // AC: @meta-manifest-discovery ac-2 - validate kynetic_meta version field
+                if (raw && typeof raw === "object" && "kynetic_meta" in raw) {
+                    return filePath;
+                }
+            }
+            catch {
+                // Skip invalid files
+            }
         }
     }
+    catch {
+        // Directory read failed
+    }
     return null;
 }
+/**
+ * Get the base name (slug) from a manifest path.
+ * E.g., "kynetic.yaml" -> "kynetic", "myproject.spec.yaml" -> "myproject"
+ */
+function getManifestBaseName(manifestPath) {
+    if (!manifestPath)
+        return "kynetic";
+    const fileName = path.basename(manifestPath);
+    // Remove .yaml extension
+    let baseName = fileName.replace(/\.yaml$/, "");
+    // Remove .spec suffix if present
+    baseName = baseName.replace(/\.spec$/, "");
+    return baseName || "kynetic";
+}
 /**
  * Get the meta manifest file path.
+ * Derives from main manifest name (e.g., myproject.yaml -> myproject.meta.yaml)
  * Returns path even if file doesn't exist yet.
  */
 export function getMetaManifestPath(ctx) {
-    return path.join(ctx.specDir, 'kynetic.meta.yaml');
+    const baseName = getManifestBaseName(ctx.manifestPath);
+    return path.join(ctx.specDir, `${baseName}.meta.yaml`);
 }
 /**
  * Load meta items from a single file.
@@ -45,10 +91,11 @@ async function loadMetaFile(filePath) {
         workflows: [],
         conventions: [],
         observations: [],
+        skills: [],
     };
     try {
         const raw = await readYamlFile(filePath);
-        if (!raw || typeof raw !== 'object') {
+        if (!raw || typeof raw !== "object") {
             return result;
         }
         const obj = raw;
@@ -88,6 +135,16 @@ async function loadMetaFile(filePath) {
                 }
             }
         }
+        // Parse skills
+        // AC: @skill-meta-type ac-4 - skills loaded with _sourceFile set
+        if (Array.isArray(obj.skills)) {
+            for (const skill of obj.skills) {
+                const parsed = SkillSchema.safeParse(skill);
+                if (parsed.success) {
+                    result.skills.push({ ...parsed.data, _sourceFile: filePath });
+                }
+            }
+        }
     }
     catch {
         // File doesn't exist or parse error
@@ -97,6 +154,7 @@ async function loadMetaFile(filePath) {
 /**
  * Load the meta context from a kspec context.
  * Loads meta manifest and follows includes.
+ * AC: @skill-meta-type ac-4 - MetaContext.skills contains LoadedSkill objects with _sourceFile set
  */
 export async function loadMetaContext(ctx) {
     const result = {
@@ -106,6 +164,7 @@ export async function loadMetaContext(ctx) {
         workflows: [],
         conventions: [],
         observations: [],
+        skills: [],
     };
     const manifestPath = await findMetaManifest(ctx.specDir);
     if (!manifestPath) {
@@ -122,6 +181,7 @@ export async function loadMetaContext(ctx) {
             result.workflows.push(...items.workflows);
             result.conventions.push(...items.conventions);
             result.observations.push(...items.observations);
+            result.skills.push(...items.skills);
             return result;
         }
         result.manifest = parsed.data;
@@ -131,6 +191,7 @@ export async function loadMetaContext(ctx) {
         result.workflows.push(...manifestItems.workflows);
         result.conventions.push(...manifestItems.conventions);
         result.observations.push(...manifestItems.observations);
+        result.skills.push(...manifestItems.skills);
         // Process includes
         const includes = parsed.data.includes || [];
         const manifestDir = path.dirname(manifestPath);
@@ -142,6 +203,7 @@ export async function loadMetaContext(ctx) {
                 result.workflows.push(...items.workflows);
                 result.conventions.push(...items.conventions);
                 result.observations.push(...items.observations);
+                result.skills.push(...items.skills);
             }
         }
     }
@@ -160,41 +222,68 @@ export function getMetaStats(meta) {
         conventions: meta.conventions.length,
         observations: meta.observations.length,
         unresolvedObservations: meta.observations.filter((o) => !o.resolved).length,
+        skills: meta.skills.length,
     };
 }
 /**
- * Find a meta item by reference (ULID, short ULID, or id)
+ * Resolve a meta reference to its item, type, and ULID.
+ *
+ * This is the unified resolver for meta items that consolidates various
+ * ref-to-item resolution patterns. Handles ULID prefixes, full ULIDs,
+ * semantic IDs (id field for agents/workflows/skills), and domains (conventions).
+ *
+ * AC: @skill-meta-type ac-5 - skills returned by semantic id lookup
+ * AC: @skill-meta-type ac-6 - skills returned by ULID prefix lookup
+ * AC: @skill-meta-integration ac-4 - skills included in resolution
  */
-export function findMetaItemByRef(meta, ref) {
-    const cleanRef = ref.startsWith('@') ? ref.slice(1) : ref;
+export function resolveMetaRef(meta, ref) {
+    const cleanRef = ref.startsWith("@") ? ref.slice(1) : ref;
     // Search all item types
     const allItems = [
         ...meta.agents,
         ...meta.workflows,
         ...meta.conventions,
         ...meta.observations,
+        ...meta.skills,
     ];
     for (const item of allItems) {
         // Match full ULID
-        if (item._ulid === cleanRef)
-            return item;
+        if (item._ulid === cleanRef) {
+            return { item, type: getMetaItemType(item), ulid: item._ulid };
+        }
         // Match short ULID (prefix)
-        if (item._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()))
-            return item;
-        // Match by id (for agents and workflows)
-        if ('id' in item && item.id === cleanRef)
-            return item;
+        if (item._ulid.toLowerCase().startsWith(cleanRef.toLowerCase())) {
+            return { item, type: getMetaItemType(item), ulid: item._ulid };
+        }
+        // Match by id (for agents, workflows, and skills)
+        if ("id" in item && item.id === cleanRef) {
+            return { item, type: getMetaItemType(item), ulid: item._ulid };
+        }
         // Match by domain (for conventions)
-        if ('domain' in item && item.domain === cleanRef)
-            return item;
+        if ("domain" in item && item.domain === cleanRef) {
+            return { item, type: getMetaItemType(item), ulid: item._ulid };
+        }
     }
-    return undefined;
+    return null;
+}
+/**
+ * Find a meta item by reference (ULID, short ULID, or id)
+ *
+ * This is a convenience wrapper around resolveMetaRef that returns just the item.
+ * Use resolveMetaRef when you also need the type and ULID.
+ *
+ * AC: @skill-meta-type ac-5 - skills returned by semantic id lookup
+ * AC: @skill-meta-type ac-6 - skills returned by ULID prefix lookup
+ */
+export function findMetaItemByRef(meta, ref) {
+    const result = resolveMetaRef(meta, ref);
+    return result?.item;
 }
 /**
  * Determine if an item is a meta item type
  */
 export function isMetaItemType(type) {
-    return ['agent', 'workflow', 'convention', 'observation'].includes(type);
+    return ["agent", "workflow", "convention", "observation", "skill"].includes(type);
 }
 // ============================================================
 // META ITEM CRUD
@@ -222,7 +311,7 @@ export function createObservation(type, content, options = {}) {
         content,
         workflow_ref: options.workflow_ref,
         created_at: new Date().toISOString(),
-        author: options.author ?? getAuthor(),
+        author: options.author ?? getAuthor(options.configAuthor),
         resolved: false,
         resolution: null,
     };
@@ -237,11 +326,12 @@ export async function saveObservation(ctx, observation) {
     await fs.mkdir(dir, { recursive: true });
     // Load existing manifest
     let manifest = {
-        kynetic_meta: '1.0',
+        kynetic_meta: "1.0",
         agents: [],
         workflows: [],
         conventions: [],
         observations: [],
+        skills: [],
         includes: [],
     };
     try {
@@ -290,13 +380,142 @@ export async function deleteObservation(ctx, ulid) {
         return false;
     }
 }
-// Re-export the getMetaItemType function
-export { getMetaItemType };
+/**
+ * Get the path for skill content file.
+ * Skills are stored in .kspec/skills/<id>/SKILL.md
+ */
+export function getSkillContentPath(ctx, skillId) {
+    return path.join(ctx.specDir, "skills", skillId, "SKILL.md");
+}
+/**
+ * Load skill content from the SKILL.md file.
+ * AC: @skill-meta-type ac-3 - loadSkillContent returns full markdown content
+ * AC: @skill-content-model ac-1 - loadSkillContent returns markdown content as a string
+ */
+export async function loadSkillContent(ctx, skill) {
+    const contentPath = getSkillContentPath(ctx, skill.id);
+    try {
+        const content = await fs.readFile(contentPath, "utf-8");
+        return content;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the docs directory path for a skill.
+ * Skills can have supporting docs at .kspec/skills/<id>/docs/
+ */
+export function getSkillDocsPath(ctx, skillId) {
+    return path.join(ctx.specDir, "skills", skillId, "docs");
+}
+/**
+ * Load skill documentation files from the docs/ subdirectory.
+ * AC: @skill-content-model ac-2 - loadSkillDocs returns array of doc objects
+ */
+export async function loadSkillDocs(ctx, skill) {
+    const docsPath = getSkillDocsPath(ctx, skill.id);
+    const docs = [];
+    try {
+        const entries = await fs.readdir(docsPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith(".md")) {
+                const filePath = path.join(docsPath, entry.name);
+                try {
+                    const content = await fs.readFile(filePath, "utf-8");
+                    docs.push({
+                        name: entry.name,
+                        path: filePath,
+                        content,
+                    });
+                }
+                catch {
+                    // Skip files that can't be read
+                }
+            }
+        }
+    }
+    catch {
+        // docs directory doesn't exist or can't be read
+    }
+    return docs;
+}
+/**
+ * Get the path to a supporting directory for a skill.
+ * AC: @supporting-files-convention ac-1
+ */
+export function getSkillSupportingDirPath(ctx, skillId, dirType) {
+    return path.join(ctx.specDir, "skills", skillId, dirType);
+}
+/**
+ * Load files from a skill's supporting directory.
+ * AC: @supporting-files-convention ac-1 - references files are accessible
+ *
+ * @param ctx - Kspec context
+ * @param skill - The skill to load files from
+ * @param dirType - The supporting directory type (references, scripts, assets, docs)
+ * @returns Array of files found in the directory
+ */
+export async function loadSkillSupportingFiles(ctx, skill, dirType) {
+    const dirPath = getSkillSupportingDirPath(ctx, skill.id, dirType);
+    const files = [];
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile()) {
+                const filePath = path.join(dirPath, entry.name);
+                try {
+                    const content = await fs.readFile(filePath, "utf-8");
+                    files.push({
+                        name: entry.name,
+                        path: filePath,
+                        content,
+                        dirType,
+                    });
+                }
+                catch {
+                    // Skip files that can't be read (e.g., binary files)
+                }
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read - return empty array
+    }
+    return files;
+}
+/**
+ * List which supporting directories exist for a skill.
+ * AC: @supporting-files-convention ac-1
+ *
+ * @returns Array of directory types that exist for the skill
+ */
+export async function listSkillSupportingDirs(ctx, skillId) {
+    const dirs = [];
+    const allDirs = ["references", "scripts", "assets", "docs"];
+    for (const dirType of allDirs) {
+        const dirPath = getSkillSupportingDirPath(ctx, skillId, dirType);
+        try {
+            const stat = await fs.stat(dirPath);
+            if (stat.isDirectory()) {
+                dirs.push(dirType);
+            }
+        }
+        catch {
+            // Directory doesn't exist
+        }
+    }
+    return dirs;
+}
+// Re-export the getMetaItemType and isSkill functions
+export { getMetaItemType, isSkill };
 // ============================================================
 // GENERIC META ITEM CRUD
 // ============================================================
 /**
- * Save any meta item (agent, workflow, convention) to the manifest
+ * Save any meta item (agent, workflow, convention, skill) to the manifest
+ * AC: @skill-parser ac-1 - skill is appended to manifest.skills and written to disk
+ * AC: @skill-parser ac-2 - .kspec/skills/<id>/ directory is created for skills
  */
 export async function saveMetaItem(ctx, item, itemType) {
     const manifestPath = getMetaManifestPath(ctx);
@@ -305,11 +524,12 @@ export async function saveMetaItem(ctx, item, itemType) {
     await fs.mkdir(dir, { recursive: true });
     // Load existing manifest
     let manifest = {
-        kynetic_meta: '1.0',
+        kynetic_meta: "1.0",
         agents: [],
         workflows: [],
         conventions: [],
         observations: [],
+        skills: [],
         includes: [],
     };
     try {
@@ -327,12 +547,14 @@ export async function saveMetaItem(ctx, item, itemType) {
     // Get the appropriate array
     const getArray = () => {
         switch (itemType) {
-            case 'agent':
+            case "agent":
                 return manifest.agents;
-            case 'workflow':
+            case "workflow":
                 return manifest.workflows;
-            case 'convention':
+            case "convention":
                 return manifest.conventions;
+            case "skill":
+                return manifest.skills;
         }
     };
     const array = getArray();
@@ -345,9 +567,16 @@ export async function saveMetaItem(ctx, item, itemType) {
         array.push(cleanItem);
     }
     await saveMetaManifest(manifestPath, manifest);
+    // AC: @skill-parser ac-2 - Create skill content directory
+    if (itemType === "skill" && "id" in item) {
+        const skillDir = path.join(ctx.specDir, "skills", item.id);
+        await fs.mkdir(skillDir, { recursive: true });
+    }
 }
 /**
  * Delete any meta item from the manifest
+ * AC: @skill-parser ac-3 - skill is removed from manifest.skills
+ * AC: @skill-parser ac-4 - .kspec/skills/<id>/ directory is deleted for skills
  */
 export async function deleteMetaItem(ctx, itemUlid, itemType) {
     const manifestPath = getMetaManifestPath(ctx);
@@ -360,14 +589,16 @@ export async function deleteMetaItem(ctx, itemUlid, itemType) {
         const manifest = parsed.data;
         const getArray = () => {
             switch (itemType) {
-                case 'agent':
+                case "agent":
                     return manifest.agents;
-                case 'workflow':
+                case "workflow":
                     return manifest.workflows;
-                case 'convention':
+                case "convention":
                     return manifest.conventions;
-                case 'observation':
+                case "observation":
                     return manifest.observations;
+                case "skill":
+                    return manifest.skills;
             }
         };
         const array = getArray();
@@ -375,6 +606,19 @@ export async function deleteMetaItem(ctx, itemUlid, itemType) {
         if (index < 0) {
             return false;
         }
+        // AC: @skill-parser ac-4 - Delete skill directory before removing from manifest
+        if (itemType === "skill") {
+            const skill = array[index];
+            if (skill.id) {
+                const skillDir = path.join(ctx.specDir, "skills", skill.id);
+                try {
+                    await fs.rm(skillDir, { recursive: true, force: true });
+                }
+                catch {
+                    // Directory might not exist, that's fine
+                }
+            }
+        }
         array.splice(index, 1);
         await saveMetaManifest(manifestPath, manifest);
         return true;
@@ -390,7 +634,7 @@ export async function deleteMetaItem(ctx, itemUlid, itemType) {
  * Get the session context file path
  */
 export function getSessionContextPath(ctx) {
-    return path.join(ctx.specDir, '.kspec-session');
+    return path.join(ctx.specDir, ".kspec-session");
 }
 /**
  * Load session context (or return empty context if not exists)
@@ -399,7 +643,7 @@ export async function loadSessionContext(ctx) {
     const contextPath = getSessionContextPath(ctx);
     try {
         const raw = await readYamlFile(contextPath);
-        if (!raw || typeof raw !== 'object') {
+        if (!raw || typeof raw !== "object") {
             return {
                 focus: null,
                 threads: [],
@@ -438,4 +682,93 @@ export async function saveSessionContext(ctx, context) {
     context.updated_at = new Date().toISOString();
     await writeYamlFilePreserveFormat(contextPath, context);
 }
+// ============================================================
+// WORKFLOW RUNS
+// ============================================================
+/**
+ * Get the workflow runs file path.
+ * Derives from main manifest name (e.g., myproject.yaml -> myproject.runs.yaml)
+ */
+export function getWorkflowRunsPath(ctx) {
+    const baseName = getManifestBaseName(ctx.manifestPath);
+    return path.join(ctx.specDir, `${baseName}.runs.yaml`);
+}
+/**
+ * Load workflow runs from file
+ */
+export async function loadWorkflowRuns(ctx) {
+    const runsPath = getWorkflowRunsPath(ctx);
+    try {
+        const raw = await readYamlFile(runsPath);
+        const parsed = WorkflowRunsFileSchema.safeParse(raw);
+        if (!parsed.success) {
+            return [];
+        }
+        return parsed.data.runs;
+    }
+    catch {
+        // File doesn't exist
+        return [];
+    }
+}
+/**
+ * Save a workflow run (create or update)
+ */
+export async function saveWorkflowRun(ctx, run) {
+    const runsPath = getWorkflowRunsPath(ctx);
+    // Load existing runs
+    const runs = await loadWorkflowRuns(ctx);
+    // Update or add
+    const existingIndex = runs.findIndex((r) => r._ulid === run._ulid);
+    if (existingIndex >= 0) {
+        runs[existingIndex] = run;
+    }
+    else {
+        runs.push(run);
+    }
+    // Save back
+    const runsFile = {
+        kynetic_runs: "1.0",
+        runs,
+    };
+    await writeYamlFilePreserveFormat(runsPath, runsFile);
+}
+/**
+ * Update an existing workflow run
+ */
+export async function updateWorkflowRun(ctx, run) {
+    await saveWorkflowRun(ctx, run);
+}
+/**
+ * Find a workflow run by reference (ULID or ULID prefix)
+ */
+export async function findWorkflowRunByRef(ctx, ref) {
+    const runs = await loadWorkflowRuns(ctx);
+    const cleanRef = ref.startsWith("@") ? ref.slice(1) : ref;
+    return runs.find((r) => r._ulid === cleanRef ||
+        r._ulid.toLowerCase().startsWith(cleanRef.toLowerCase()));
+}
+/**
+ * Find active workflow runs
+ */
+export async function findActiveRuns(ctx) {
+    const runs = await loadWorkflowRuns(ctx);
+    return runs.filter((r) => r.status === "active");
+}
+/**
+ * Delete workflow runs by ULIDs
+ * AC: @workflow-prune ac-1, ac-2, ac-3, ac-4
+ */
+export async function deleteWorkflowRuns(ctx, ulidsToDelete) {
+    const runsPath = getWorkflowRunsPath(ctx);
+    const runs = await loadWorkflowRuns(ctx);
+    // Filter out runs to delete
+    const remainingRuns = runs.filter((r) => !ulidsToDelete.includes(r._ulid));
+    // Save back
+    const runsFile = {
+        kynetic_runs: "1.0",
+        runs: remainingRuns,
+    };
+    await writeYamlFilePreserveFormat(runsPath, runsFile);
+}
 //# sourceMappingURL=meta.js.map