daemora 1.0.0-alpha.0

package/dist/skills/SkillLoader.js

@@ -0,0 +1,336 @@
+/**
+ * SkillLoader — discovers skills from a root directory. Handles:
+ *
+ *   1. Standalone .md files:  skills/email.md (name from frontmatter)
+ *   2. Directories with SKILL.md:  skills/coding-agent/SKILL.md
+ *   3. Directories with skill.yaml + *.md: skills/camsnap/skill.yaml
+ *   4. Nested category directories: skills/mlops/training/axolotl/SKILL.md
+ *
+ * Never throws. Bad skills are reported in `skipped`, the rest load.
+ *
+ * Linked files (references/, templates/, scripts/, assets/) are
+ * discovered per-skill and surfaced through Skill.linkedFiles so
+ * skill_view can list them without another walk.
+ */
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, extname, join, resolve } from "node:path";
+import matter from "gray-matter";
+import { createLogger } from "../util/logger.js";
+import { scanContent } from "./SecurityScanner.js";
+import { SkillSnapshot } from "./SkillSnapshot.js";
+import { skillFrontmatterSchema } from "./types.js";
+const log = createLogger("skills.loader");
+/** Directory names skipped when walking for category/skill dirs. */
+const WALK_SKIP = new Set([".git", ".github", ".hub", "node_modules", "_template"]);
+/** Subdirs scanned for linked files under a skill dir. */
+const LINKED_SUBDIRS = ["references", "templates", "scripts", "assets"];
+/** File extensions allowed per linked subdir. Empty = any. */
+const LINKED_EXTS = {
+    references: [".md", ".txt"],
+    templates: [".md", ".yaml", ".yml", ".json", ".py", ".sh", ".tex", ".html"],
+    scripts: [".py", ".sh", ".bash", ".js", ".ts", ".rb"],
+    assets: [], // any
+};
+export class SkillLoader {
+    skillsRoot;
+    bodyCache = new Map();
+    snapshot;
+    // Extra roots are optional secondary trees walked alongside the primary
+    // skillsRoot. The agent's bundled skills live in `skillsRoot`, while
+    // user-created skills (from POST /api/skills/custom) live in a separate
+    // tree under the data dir so they survive package upgrades.
+    extraRoots;
+    constructor(skillsRoot, snapshotPath, extraRoots = []) {
+        this.skillsRoot = skillsRoot;
+        this.snapshot = snapshotPath ? new SkillSnapshot(skillsRoot, snapshotPath) : undefined;
+        this.extraRoots = extraRoots;
+    }
+    async loadAll() {
+        const root = resolve(this.skillsRoot);
+        const loaded = [];
+        const skipped = [];
+        await this.walk(root, loaded, skipped);
+        for (const extra of this.extraRoots) {
+            await this.walk(resolve(extra), loaded, skipped);
+        }
+        // Persist manifest for next warm start. Snapshot is advisory — we
+        // always do the full walk, but the mtime manifest tells us if the
+        // tree changed at all (external change detection / future hot-reload).
+        if (this.snapshot) {
+            try {
+                const manifest = await this.snapshot.buildManifest();
+                await this.snapshot.writeSnapshot(manifest);
+            }
+            catch (e) {
+                log.warn({ err: e.message }, "snapshot write failed (non-fatal)");
+            }
+        }
+        log.info({ loaded: loaded.length, skipped: skipped.length, root }, "skills scan complete");
+        return { loaded, skipped };
+    }
+    /**
+     * True iff the on-disk snapshot's manifest matches the live tree.
+     * Callers can use this to decide whether to skip a full loadAll.
+     * Fast — just mtimes + sizes, no file parsing.
+     */
+    async isFresh() {
+        if (!this.snapshot)
+            return false;
+        const prev = await this.snapshot.readSnapshot();
+        if (!prev)
+            return false;
+        return this.snapshot.isFresh(prev.manifest);
+    }
+    /**
+     * Walk `dir` recursively looking for either:
+     *   - Standalone *.md skill files
+     *   - Skill dirs containing SKILL.md / skill.md / skill.yaml / README.md
+     * When a skill dir is found we do NOT recurse into it (linked files
+     * live under that skill, not as separate skills).
+     */
+    async walk(dir, loaded, skipped) {
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            log.warn({ dir }, "skills dir unreadable");
+            return;
+        }
+        entries.sort((a, b) => a.localeCompare(b));
+        for (const entry of entries) {
+            if (entry.startsWith(".") || entry.startsWith("_"))
+                continue;
+            if (WALK_SKIP.has(entry))
+                continue;
+            const full = join(dir, entry);
+            let s;
+            try {
+                s = await stat(full);
+            }
+            catch {
+                continue;
+            }
+            if (s.isFile() && extname(entry) === ".md") {
+                const r = await this.loadFromMd(full, entry.replace(/\.md$/, ""));
+                if (r.kind === "ok")
+                    loaded.push(r.skill);
+                else
+                    skipped.push(r.issue);
+                continue;
+            }
+            if (!s.isDirectory())
+                continue;
+            // Is this a skill directory?
+            if (await this.looksLikeSkillDir(full)) {
+                const r = await this.loadFromDir(full);
+                if (r.kind === "ok")
+                    loaded.push(r.skill);
+                else
+                    skipped.push(r.issue);
+                continue;
+            }
+            // Otherwise treat as category and recurse.
+            await this.walk(full, loaded, skipped);
+        }
+    }
+    async looksLikeSkillDir(dir) {
+        const dirName = basename(dir);
+        const candidates = ["SKILL.md", "skill.md", `${dirName}.md`, "README.md", "skill.yaml"];
+        for (const n of candidates) {
+            try {
+                const s = await stat(join(dir, n));
+                if (s.isFile())
+                    return true;
+            }
+            catch { /* next */ }
+        }
+        return false;
+    }
+    async loadFromMd(file, fallbackId) {
+        let raw;
+        try {
+            raw = await readFile(file, "utf-8");
+        }
+        catch (e) {
+            return { kind: "err", issue: { dir: file, reason: "unreadable", cause: e } };
+        }
+        return this.parseSkillFile(raw, file, basename(file, ".md"), fallbackId, {
+            references: [], templates: [], scripts: [], assets: [],
+        });
+    }
+    async loadFromDir(dir) {
+        const dirName = basename(dir);
+        const linkedFiles = await this.scanLinkedFiles(dir);
+        // Try SKILL.md / skill.md / <dir>.md / README.md
+        for (const name of ["SKILL.md", "skill.md", `${dirName}.md`, "README.md"]) {
+            const file = join(dir, name);
+            try {
+                const raw = await readFile(file, "utf-8");
+                return this.parseSkillFile(raw, file, dir, dirName, linkedFiles);
+            }
+            catch { /* try next */ }
+        }
+        // Try skill.yaml + first *.md as body
+        try {
+            const yamlFile = join(dir, "skill.yaml");
+            const yamlRaw = await readFile(yamlFile, "utf-8");
+            const files = await readdir(dir);
+            const mdFile = files.find((f) => f.endsWith(".md"));
+            let body = "";
+            if (mdFile) {
+                try {
+                    body = await readFile(join(dir, mdFile), "utf-8");
+                }
+                catch { }
+            }
+            const fullRaw = `---\n${yamlRaw}\n---\n${body}`;
+            return this.parseSkillFile(fullRaw, yamlFile, dir, dirName, linkedFiles);
+        }
+        catch { /* no yaml */ }
+        // Fallback: any *.md in dir
+        try {
+            const files = await readdir(dir);
+            const md = files.find((f) => f.endsWith(".md") && !f.startsWith("_"));
+            if (md) {
+                const file = join(dir, md);
+                const raw = await readFile(file, "utf-8");
+                return this.parseSkillFile(raw, file, dir, dirName, linkedFiles);
+            }
+        }
+        catch { }
+        return { kind: "err", issue: { dir, reason: "no skill file found" } };
+    }
+    async scanLinkedFiles(skillDir) {
+        const out = {
+            references: [], templates: [], scripts: [], assets: [],
+        };
+        for (const sub of LINKED_SUBDIRS) {
+            const subPath = join(skillDir, sub);
+            try {
+                const st = await stat(subPath);
+                if (!st.isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const exts = LINKED_EXTS[sub];
+            await this.collectFiles(subPath, sub, exts, out[sub], skillDir);
+            out[sub].sort((a, b) => a.localeCompare(b));
+        }
+        return {
+            references: out.references, templates: out.templates,
+            scripts: out.scripts, assets: out.assets,
+        };
+    }
+    async collectFiles(dir, relPrefix, exts, into, skillDir) {
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.startsWith("."))
+                continue;
+            const full = join(dir, e);
+            let s;
+            try {
+                s = await stat(full);
+            }
+            catch {
+                continue;
+            }
+            if (s.isFile()) {
+                if (exts.length > 0 && !exts.includes(extname(e)))
+                    continue;
+                into.push(full.slice(skillDir.length + 1));
+            }
+            else if (s.isDirectory()) {
+                await this.collectFiles(full, `${relPrefix}/${e}`, exts, into, skillDir);
+            }
+        }
+    }
+    parseSkillFile(raw, file, dir, fallbackId, linkedFiles) {
+        let parsed;
+        try {
+            const m = matter(raw);
+            parsed = { data: m.data ?? {}, content: m.content ?? "" };
+        }
+        catch (e) {
+            return { kind: "err", issue: { dir, reason: "invalid frontmatter", cause: e } };
+        }
+        if (!parsed.data["id"] && parsed.data["name"]) {
+            parsed.data["id"] = String(parsed.data["name"]).toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9_-]/g, "");
+        }
+        if (!parsed.data["id"])
+            parsed.data["id"] = fallbackId;
+        if (!parsed.data["name"])
+            parsed.data["name"] = String(parsed.data["id"]);
+        if (!parsed.data["description"]) {
+            const firstLine = parsed.content.trim().split("\n")[0]?.replace(/^#+\s*/, "").trim();
+            parsed.data["description"] = firstLine || String(parsed.data["name"]);
+        }
+        const validation = skillFrontmatterSchema.safeParse(parsed.data);
+        if (!validation.success) {
+            return { kind: "err", issue: { dir, reason: `validation: ${validation.error.message.slice(0, 200)}` } };
+        }
+        const meta = {
+            ...validation.data,
+            id: validation.data.id || fallbackId,
+        };
+        if (!meta.enabled) {
+            return { kind: "err", issue: { dir, reason: "disabled" } };
+        }
+        // Warn on injection patterns but still load — the agent needs to
+        // see suspicious content to reason about it. Critical guard is at
+        // skill_manage write-time, not load-time.
+        const scan = scanContent(parsed.content);
+        if (scan.blocked) {
+            log.warn({ dir, pattern: scan.pattern }, "skill content matched threat pattern");
+        }
+        const skill = {
+            meta, dir, file,
+            contentHash: sha256(raw),
+            linkedFiles,
+            loadBody: () => this.readBody(file, parsed.content),
+        };
+        return { kind: "ok", skill };
+    }
+    async readBody(file, fallback) {
+        let mtimeMs;
+        try {
+            const s = await stat(file);
+            mtimeMs = s.mtimeMs;
+        }
+        catch {
+            return fallback;
+        }
+        const cached = this.bodyCache.get(file);
+        if (cached && cached.mtimeMs === mtimeMs)
+            return cached.body;
+        let raw;
+        try {
+            raw = await readFile(file, "utf-8");
+        }
+        catch {
+            return fallback;
+        }
+        let body;
+        try {
+            body = matter(raw).content ?? "";
+        }
+        catch {
+            body = raw;
+        }
+        this.bodyCache.set(file, { mtimeMs, body });
+        return body;
+    }
+}
+function sha256(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+//# sourceMappingURL=SkillLoader.js.map

package/dist/skills/SkillLoader.js.map

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

package/dist/skills/SkillRegistry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SkillRegistry — in-memory store of loaded skills + matching API.
+ *
+ * Filtering rules:
+ *   - `requires_tools` / `requires_integrations` / `platforms` / `fallback_for_tools`
+ *     all participate in the `visible()` pass. A skill is hidden if its
+ *     preconditions don't hold (avoids showing the agent a skill it
+ *     literally can't act on).
+ *
+ * System prompt injection:
+ *   - `renderIndexForPrompt()` emits the full flat index (hermes pattern):
+ *     one line per visible skill with name + description. The model
+ *     decides which to load via `skill_view(name)`.
+ */
+import type { Skill, SkillLinkedFiles } from "./types.js";
+export interface SkillMatch {
+    readonly skill: Skill;
+    readonly score: number;
+}
+export interface SkillFilter {
+    readonly availableTools: ReadonlySet<string>;
+    readonly enabledIntegrations: ReadonlySet<string>;
+    /** Current OS platform for filtering (defaults to process.platform). */
+    readonly platform?: string;
+}
+export declare class SkillRegistry {
+    private readonly byId;
+    constructor(skills: readonly Skill[]);
+    get size(): number;
+    get(id: string): Skill | undefined;
+    list(): readonly Skill[];
+    /**
+     * Replace the registry contents in place. Preserves the instance
+     * identity so anyone holding a reference (crews, tools, system-prompt
+     * builder) sees the new set without needing to re-wire.
+     */
+    replace(skills: readonly Skill[]): void;
+    /** Skills the agent can actually use right now (all requirements met). */
+    visible(filter: SkillFilter): readonly Skill[];
+    /**
+     * Render the flat skill index for the system prompt (hermes pattern).
+     *
+     * Format:
+     *   ## Available Skills
+     *   Before replying, scan the skills below. If any matches or is even
+     *   partially relevant, you MUST call skill_view(name) and follow it.
+     *
+     *     - skill-id: description (≤200 chars)
+     *
+     * Keeps ~80-100 bytes per skill so hundreds of skills fit well within
+     * the cached system prompt.
+     */
+    renderIndexForPrompt(filter: SkillFilter): string;
+    /**
+     * Read a supporting file under a skill's directory. Used by skill_view
+     * when the agent requests a specific reference/template/script file.
+     * Rejects paths that escape the skill dir.
+     */
+    getLinkedFile(skillId: string, relPath: string): Promise<{
+        kind: "ok";
+        path: string;
+        content: string;
+    } | {
+        kind: "err";
+        reason: string;
+    }>;
+    /** Return linked files for a skill, for skill_view response. */
+    linkedFiles(skillId: string): SkillLinkedFiles | null;
+    /**
+     * Deprecated matcher — kept for tooling that wants to highlight
+     * likely-relevant skills in UIs. Not used by the agent system prompt
+     * anymore (hermes pattern: agent sees all skills, decides itself).
+     *
+     * @deprecated Use `renderIndexForPrompt()` instead.
+     */
+    match(query: string, filter: SkillFilter, limit?: number, minScore?: number): readonly SkillMatch[];
+}
+//# sourceMappingURL=SkillRegistry.d.ts.map

package/dist/skills/SkillRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillRegistry.d.ts","sourceRoot":"","sources":["../../src/skills/SkillRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClD,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;gBAE9B,MAAM,EAAE,SAAS,KAAK,EAAE;IAIpC,IAAI,IAAI,IAAI,MAAM,CAA2B;IAE7C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAElC,IAAI,IAAI,SAAS,KAAK,EAAE;IAExB;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI;IAKvC,0EAA0E;IAC1E,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,KAAK,EAAE;IAqB9C;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM;IAmBjD;;;;OAIG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAC1D;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAC7C;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAClC;IAyBD,gEAAgE;IAChE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAKrD;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,SAAI,EAAE,QAAQ,SAAI,GAAG,SAAS,UAAU,EAAE;CAkB1F"}

package/dist/skills/SkillRegistry.js

@@ -0,0 +1,185 @@
+/**
+ * SkillRegistry — in-memory store of loaded skills + matching API.
+ *
+ * Filtering rules:
+ *   - `requires_tools` / `requires_integrations` / `platforms` / `fallback_for_tools`
+ *     all participate in the `visible()` pass. A skill is hidden if its
+ *     preconditions don't hold (avoids showing the agent a skill it
+ *     literally can't act on).
+ *
+ * System prompt injection:
+ *   - `renderIndexForPrompt()` emits the full flat index (hermes pattern):
+ *     one line per visible skill with name + description. The model
+ *     decides which to load via `skill_view(name)`.
+ */
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, normalize } from "node:path";
+export class SkillRegistry {
+    byId;
+    constructor(skills) {
+        this.byId = new Map(skills.map((s) => [s.meta.id, s]));
+    }
+    get size() { return this.byId.size; }
+    get(id) { return this.byId.get(id); }
+    list() { return Array.from(this.byId.values()); }
+    /**
+     * Replace the registry contents in place. Preserves the instance
+     * identity so anyone holding a reference (crews, tools, system-prompt
+     * builder) sees the new set without needing to re-wire.
+     */
+    replace(skills) {
+        this.byId.clear();
+        for (const s of skills)
+            this.byId.set(s.meta.id, s);
+    }
+    /** Skills the agent can actually use right now (all requirements met). */
+    visible(filter) {
+        const platform = (filter.platform ?? process.platform).toLowerCase();
+        return this.list().filter((s) => {
+            for (const t of s.meta.requires_tools) {
+                if (!filter.availableTools.has(t))
+                    return false;
+            }
+            for (const i of s.meta.requires_integrations) {
+                if (!filter.enabledIntegrations.has(i))
+                    return false;
+            }
+            if (s.meta.platforms.length > 0) {
+                const ok = s.meta.platforms.some((p) => platformMatches(platform, p));
+                if (!ok)
+                    return false;
+            }
+            // fallback_for_tools: hide this skill if the primary tool IS available
+            for (const t of s.meta.fallback_for_tools) {
+                if (filter.availableTools.has(t))
+                    return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Render the flat skill index for the system prompt (hermes pattern).
+     *
+     * Format:
+     *   ## Available Skills
+     *   Before replying, scan the skills below. If any matches or is even
+     *   partially relevant, you MUST call skill_view(name) and follow it.
+     *
+     *     - skill-id: description (≤200 chars)
+     *
+     * Keeps ~80-100 bytes per skill so hundreds of skills fit well within
+     * the cached system prompt.
+     */
+    renderIndexForPrompt(filter) {
+        const visible = this.visible(filter);
+        if (visible.length === 0)
+            return "";
+        const sorted = [...visible].sort((a, b) => a.meta.id.localeCompare(b.meta.id));
+        const lines = [
+            "## Available Skills",
+            "Before replying, scan the skills below. If any matches your task — even partially — " +
+                "call `skill_view(name)` first and follow its instructions. " +
+                "If you discover a reusable approach not covered, save it with `skill_manage(action=\"create\", ...)`.",
+            "",
+        ];
+        for (const s of sorted) {
+            const desc = truncate(s.meta.description, 200);
+            lines.push(`  - ${s.meta.id}: ${desc}`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Read a supporting file under a skill's directory. Used by skill_view
+     * when the agent requests a specific reference/template/script file.
+     * Rejects paths that escape the skill dir.
+     */
+    async getLinkedFile(skillId, relPath) {
+        const skill = this.byId.get(skillId);
+        if (!skill)
+            return { kind: "err", reason: `unknown skill: ${skillId}` };
+        if (!relPath || isAbsolute(relPath)) {
+            return { kind: "err", reason: "file_path must be a relative path" };
+        }
+        const normalized = normalize(relPath);
+        if (normalized.startsWith("..") || normalized.includes("..")) {
+            return { kind: "err", reason: "file_path escapes skill directory" };
+        }
+        const allowedPrefixes = ["references/", "templates/", "scripts/", "assets/"];
+        if (!allowedPrefixes.some((p) => normalized.startsWith(p) || normalized.startsWith(p.replace("/", "\\")))) {
+            return { kind: "err", reason: "file_path must start with references/, templates/, scripts/, or assets/" };
+        }
+        const full = join(skill.dir, normalized);
+        try {
+            const content = await readFile(full, "utf-8");
+            return { kind: "ok", path: normalized, content };
+        }
+        catch (e) {
+            return { kind: "err", reason: `unable to read ${normalized}: ${e.message}` };
+        }
+    }
+    /** Return linked files for a skill, for skill_view response. */
+    linkedFiles(skillId) {
+        const s = this.byId.get(skillId);
+        return s ? s.linkedFiles : null;
+    }
+    /**
+     * Deprecated matcher — kept for tooling that wants to highlight
+     * likely-relevant skills in UIs. Not used by the agent system prompt
+     * anymore (hermes pattern: agent sees all skills, decides itself).
+     *
+     * @deprecated Use `renderIndexForPrompt()` instead.
+     */
+    match(query, filter, limit = 5, minScore = 1) {
+        const terms = tokenize(query);
+        if (terms.size === 0)
+            return [];
+        const visible = this.visible(filter);
+        const matches = [];
+        for (const skill of visible) {
+            const haystack = tokenize(`${skill.meta.name} ${skill.meta.description} ${skill.meta.triggers.join(" ")}`);
+            let score = 0;
+            for (const term of terms) {
+                if (haystack.has(term))
+                    score += 1;
+            }
+            const triggerHits = skill.meta.triggers.filter((t) => terms.has(t.toLowerCase())).length;
+            score += triggerHits * 2;
+            if (score >= minScore)
+                matches.push({ skill, score });
+        }
+        matches.sort((a, b) => b.score - a.score);
+        return matches.slice(0, limit);
+    }
+}
+const STOPWORDS = new Set([
+    "a", "an", "and", "as", "at", "be", "by", "do", "for", "from", "have", "i",
+    "in", "is", "it", "of", "on", "or", "the", "to", "with", "you",
+]);
+function tokenize(s) {
+    const out = new Set();
+    for (const raw of s.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 2)
+            continue;
+        if (STOPWORDS.has(raw))
+            continue;
+        out.add(raw);
+    }
+    return out;
+}
+function truncate(s, max) {
+    const trimmed = s.trim().replace(/\s+/g, " ");
+    if (trimmed.length <= max)
+        return trimmed;
+    return trimmed.slice(0, max - 1) + "…";
+}
+const PLATFORM_ALIAS = {
+    darwin: "darwin", macos: "darwin", mac: "darwin", osx: "darwin",
+    linux: "linux",
+    win32: "win32", windows: "win32", win: "win32",
+};
+function platformMatches(current, declared) {
+    const d = PLATFORM_ALIAS[declared.toLowerCase()] ?? declared.toLowerCase();
+    const c = PLATFORM_ALIAS[current.toLowerCase()] ?? current.toLowerCase();
+    return c === d || c.startsWith(d);
+}
+//# sourceMappingURL=SkillRegistry.js.map

package/dist/skills/SkillRegistry.js.map

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