@salesforce/sfdx-agent-harness-claude 0.6.0 → 0.7.0

package/dist/skill-loader.d.ts

@@ -0,0 +1,61 @@
+import { LogBus } from '@salesforce/agentic-common';
+/**
+ * One discovered skill: the absolute path to its `SKILL.md` and the
+ * description string the loader will surface to the model via the
+ * `skills` MCP tool catalog. The frontmatter `name` (or the
+ * skill folder basename, if the frontmatter is missing) is the key in
+ * the {@link SkillMap}; this struct holds the rest.
+ */
+export type SkillEntry = {
+    /** Absolute path to the resolved `SKILL.md` file. */
+    path: string;
+    /**
+     * Skill description from the YAML frontmatter `description:` field, trimmed.
+     * Empty string when the frontmatter omits `description:`. Surfaced verbatim
+     * in the `load_skill` tool description so the model can pick the right
+     * skill without reading the body.
+     */
+    description: string;
+};
+/**
+ * Discovered skill catalog: skill name → entry. The name is what the
+ * model passes back when it invokes `mcp__skill_bridge__load_skill`.
+ */
+export type SkillMap = Map<string, SkillEntry>;
+/**
+ * Resolve `config.skills` paths into a `Map<skillName, SkillEntry>`.
+ * Each entry in `skillPaths` may be:
+ *
+ * - A `SKILL.md` file path → one skill (named from frontmatter or
+ *   parent folder basename).
+ * - A folder containing `SKILL.md` → one skill.
+ * - A parent folder containing one or more skill subfolders, each with
+ *   its own `SKILL.md` → many skills. Subfolders without a `SKILL.md`
+ *   are silently skipped so consumers can drop arbitrary subdirectories
+ *   into their skill roots without breaking the loader.
+ *
+ * Mirrors `composeRulesAppend`'s contract for path validation: a
+ * configured entry that does not exist or that the harness cannot
+ * `stat` rejects `createAgent`, matching the rules-loader behavior so
+ * a typo in `config.skills` fails loud at registration time rather
+ * than silently dropping the skill at every turn.
+ *
+ * Skill name resolution: the frontmatter `name:` field wins; if it is
+ * missing or empty the parent-folder basename is used. When two
+ * configured paths resolve to the same name, **first writer wins** —
+ * the second entry is dropped. (Mirrors the behavior of
+ * `Map.set`-with-collision semantics; consumers who configure
+ * overlapping skill roots see only the first occurrence.)
+ *
+ * Frontmatter `description:` is captured verbatim (trimmed) and stored
+ * for the MCP server to surface in the tool description. When absent,
+ * the entry's `description` is the empty string.
+ *
+ * Frontmatter parsing is intentionally regex-based, not full YAML —
+ * `splitFrontmatterAndBody` from `@salesforce/agentic-common` already
+ * keeps the parser dependency-free, and the only fields this loader
+ * needs are `name` and `description`. A future requirement that needs
+ * structured frontmatter can swap in a YAML parser without changing
+ * the public shape of `SkillMap`.
+ */
+export declare function buildSkillMap(skillPaths: readonly string[] | undefined, logBus?: LogBus): Promise<SkillMap>;

package/dist/skill-loader.js

@@ -0,0 +1,153 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { getErrorMessage, LogBus, splitFrontmatterAndBody } from '@salesforce/agentic-common';
+const SKILL_FILE_NAME = 'SKILL.md';
+const FRONTMATTER_NAME_RE = /^name:\s*(.+?)\s*$/m;
+const FRONTMATTER_DESCRIPTION_RE = /^description:\s*(.+?)\s*$/m;
+/**
+ * Resolve `config.skills` paths into a `Map<skillName, SkillEntry>`.
+ * Each entry in `skillPaths` may be:
+ *
+ * - A `SKILL.md` file path → one skill (named from frontmatter or
+ *   parent folder basename).
+ * - A folder containing `SKILL.md` → one skill.
+ * - A parent folder containing one or more skill subfolders, each with
+ *   its own `SKILL.md` → many skills. Subfolders without a `SKILL.md`
+ *   are silently skipped so consumers can drop arbitrary subdirectories
+ *   into their skill roots without breaking the loader.
+ *
+ * Mirrors `composeRulesAppend`'s contract for path validation: a
+ * configured entry that does not exist or that the harness cannot
+ * `stat` rejects `createAgent`, matching the rules-loader behavior so
+ * a typo in `config.skills` fails loud at registration time rather
+ * than silently dropping the skill at every turn.
+ *
+ * Skill name resolution: the frontmatter `name:` field wins; if it is
+ * missing or empty the parent-folder basename is used. When two
+ * configured paths resolve to the same name, **first writer wins** —
+ * the second entry is dropped. (Mirrors the behavior of
+ * `Map.set`-with-collision semantics; consumers who configure
+ * overlapping skill roots see only the first occurrence.)
+ *
+ * Frontmatter `description:` is captured verbatim (trimmed) and stored
+ * for the MCP server to surface in the tool description. When absent,
+ * the entry's `description` is the empty string.
+ *
+ * Frontmatter parsing is intentionally regex-based, not full YAML —
+ * `splitFrontmatterAndBody` from `@salesforce/agentic-common` already
+ * keeps the parser dependency-free, and the only fields this loader
+ * needs are `name` and `description`. A future requirement that needs
+ * structured frontmatter can swap in a YAML parser without changing
+ * the public shape of `SkillMap`.
+ */
+export async function buildSkillMap(skillPaths, logBus) {
+    const map = new Map();
+    if (!skillPaths || skillPaths.length === 0)
+        return map;
+    for (const entry of skillPaths) {
+        let stats;
+        try {
+            stats = await fs.stat(entry);
+        }
+        catch (err) {
+            throw new Error(`Failed to load skills from "${entry}": ${getErrorMessage(err)}`, { cause: err });
+        }
+        if (stats.isFile()) {
+            if (path.basename(entry) !== SKILL_FILE_NAME)
+                continue;
+            await ingestSkillFile(entry, map, logBus);
+            continue;
+        }
+        if (!stats.isDirectory())
+            continue;
+        // Single-skill folder containing SKILL.md?
+        const candidate = path.join(entry, SKILL_FILE_NAME);
+        if (await isFile(candidate)) {
+            await ingestSkillFile(candidate, map, logBus);
+            continue;
+        }
+        // Parent folder: enumerate immediate subdirectories.
+        let children;
+        try {
+            children = await fs.readdir(entry, { withFileTypes: true });
+        }
+        catch (err) {
+            throw new Error(`Failed to load skills from "${entry}": ${getErrorMessage(err)}`, { cause: err });
+        }
+        for (const child of children) {
+            if (!child.isDirectory())
+                continue;
+            const childSkillMd = path.join(entry, child.name, SKILL_FILE_NAME);
+            if (!(await isFile(childSkillMd)))
+                continue;
+            await ingestSkillFile(childSkillMd, map, logBus);
+        }
+    }
+    return map;
+}
+async function ingestSkillFile(skillMdPath, map, logBus) {
+    let raw;
+    try {
+        raw = await fs.readFile(skillMdPath, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`Failed to read skill file "${skillMdPath}": ${getErrorMessage(err)}`, { cause: err });
+    }
+    const { frontmatter } = splitFrontmatterAndBody(raw);
+    const fm = frontmatter ?? '';
+    const name = readField(fm, FRONTMATTER_NAME_RE) ?? path.basename(path.dirname(skillMdPath));
+    const description = readField(fm, FRONTMATTER_DESCRIPTION_RE) ?? '';
+    if (!name)
+        return;
+    if (map.has(name)) {
+        // First-writer-wins by design (consumers can layer skill folders),
+        // but warn so the silent shadow doesn't burn debugging time.
+        const winner = map.get(name);
+        logBus?.warn(`Skill name "${name}" already loaded; ignoring duplicate at "${skillMdPath}".`, {
+            skillName: name,
+            keptPath: winner.path,
+            ignoredPath: skillMdPath,
+        });
+        return;
+    }
+    map.set(name, { path: skillMdPath, description });
+}
+function readField(frontmatter, re) {
+    const match = re.exec(frontmatter);
+    if (!match?.[1])
+        return undefined;
+    const trimmed = match[1].trim();
+    if (trimmed.length === 0)
+        return undefined;
+    // Strip a single matched pair of YAML scalar quotes (`"..."` or
+    // `'...'`). YAML allows quoting frontmatter scalars to escape colons,
+    // leading whitespace, etc., and most authors with descriptions
+    // containing punctuation will reach for quotes. A regex-based reader
+    // (kept for the no-YAML-runtime stance) would otherwise capture the
+    // quotes verbatim — the resulting `name:` key would include them and
+    // the model's `load_skill({ skill: '<name>' })` call would miss the
+    // catalog entry. Mastra's full YAML parser strips quotes; this keeps
+    // the cross-harness contract on the same observable shape.
+    if (trimmed.length >= 2) {
+        const first = trimmed.charAt(0);
+        const last = trimmed.charAt(trimmed.length - 1);
+        if ((first === '"' || first === "'") && first === last) {
+            return trimmed.slice(1, -1);
+        }
+    }
+    return trimmed;
+}
+async function isFile(p) {
+    try {
+        const s = await fs.stat(p);
+        return s.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=skill-loader.js.map

package/dist/skill-loader.js.map

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