@cubis/foundry 0.3.62 → 0.3.63

package/mcp/src/tools/skillGetReference.ts

@@ -0,0 +1,77 @@
+/**
+ * Cubis Foundry MCP Server – skill_get_reference tool.
+ *
+ * Returns a single validated markdown sidecar file for a skill.
+ */
+
+import { z } from "zod";
+import type { VaultManifest } from "../vault/types.js";
+import { readSkillReferenceFile } from "../vault/manifest.js";
+import {
+  buildSkillToolMetrics,
+  estimateTokensFromText,
+} from "../telemetry/tokenBudget.js";
+import { invalidInput, notFound } from "../utils/errors.js";
+
+export const skillGetReferenceName = "skill_get_reference";
+
+export const skillGetReferenceDescription =
+  "Get one validated markdown reference file for a skill by exact relative path.";
+
+export const skillGetReferenceSchema = z.object({
+  id: z.string().describe("The exact skill ID (directory name)"),
+  path: z
+    .string()
+    .describe("Exact relative markdown reference path exposed by skill_validate"),
+});
+
+function assertConcreteSkillId(id: string) {
+  if (id.startsWith("workflow-") || id.startsWith("agent-")) {
+    invalidInput(
+      `Skill id "${id}" appears to be a wrapper id. Use workflow/agent routing (for example $workflow-implement-track or $agent-backend-specialist) and call skill_get only for concrete skill ids.`,
+    );
+  }
+}
+
+export async function handleSkillGetReference(
+  args: z.infer<typeof skillGetReferenceSchema>,
+  manifest: VaultManifest,
+  charsPerToken: number,
+) {
+  const { id, path } = args;
+  assertConcreteSkillId(id);
+
+  const skill = manifest.skills.find((entry) => entry.id === id);
+  if (!skill) {
+    notFound("Skill", id);
+  }
+
+  let reference;
+  try {
+    reference = await readSkillReferenceFile(skill.path, path);
+  } catch (error) {
+    invalidInput(error instanceof Error ? error.message : String(error));
+  }
+
+  const metrics = buildSkillToolMetrics({
+    charsPerToken,
+    fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+    responseEstimatedTokens: estimateTokensFromText(
+      reference.content,
+      charsPerToken,
+    ),
+    responseCharacterCount: reference.content.length,
+  });
+
+  return {
+    content: [{ type: "text" as const, text: reference.content }],
+    structuredContent: {
+      skillId: id,
+      path: reference.relativePath,
+      metrics,
+    },
+    _meta: {
+      metrics,
+    },
+  };
+}

package/mcp/src/tools/skillTools.test.ts

@@ -6,8 +6,10 @@ import type { VaultManifest } from "../vault/types.js";
 import { handleSkillBrowseCategory } from "./skillBrowseCategory.js";
 import { handleSkillBudgetReport } from "./skillBudgetReport.js";
 import { handleSkillGet } from "./skillGet.js";
+import { handleSkillGetReference } from "./skillGetReference.js";
 import { handleSkillListCategories } from "./skillListCategories.js";
 import { handleSkillSearch } from "./skillSearch.js";
+import { handleSkillValidate } from "./skillValidate.js";
 
 function payload(result: { content: Array<{ text: string }> }): Record<string, unknown> {
   return JSON.parse(result.content[0].text) as Record<string, unknown>;
@@ -147,6 +149,76 @@ describe("skill tools", () => {
     expect(toolMetrics.loadedSkillEstimatedTokens).toBeGreaterThan(0);
   });
 
+  it("validates an exact skill id and exposes alias/reference metadata", async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-validate-"));
+    const skillFile = path.join(dir, "SKILL.md");
+    const referencesDir = path.join(dir, "references");
+    mkdirSync(referencesDir, { recursive: true });
+    writeFileSync(
+      skillFile,
+      [
+        "---",
+        "name: deprecated-skill",
+        "description: compatibility shim",
+        "metadata:",
+        "  deprecated: true",
+        "  replaced_by: canonical-skill",
+        "---",
+        "# Skill",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(path.join(referencesDir, "guide.md"), "# Guide", "utf8");
+
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "deprecated-skill",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillValidate(
+      { id: "deprecated-skill" },
+      manifest,
+      4,
+    );
+    const data = payload(result);
+    expect(data).toMatchObject({
+      id: "deprecated-skill",
+      exists: true,
+      canonicalId: "canonical-skill",
+      isAlias: true,
+      replacementId: "canonical-skill",
+    });
+    expect(data.availableReferences).toContain("references/guide.md");
+  });
+
+  it("returns exists=false for unknown exact skill ids", async () => {
+    const manifest = createManifest();
+    const result = await handleSkillValidate({ id: "missing" }, manifest, 4);
+    const data = payload(result);
+    expect(data).toMatchObject({
+      id: "missing",
+      exists: false,
+      canonicalId: null,
+    });
+  });
+
+  it("throws a wrapper guidance error when skill_validate receives workflow id", async () => {
+    const manifest = createManifest();
+    await expect(
+      handleSkillValidate({ id: "workflow-implement-track" }, manifest, 4),
+    ).rejects.toThrow("appears to be a wrapper id");
+  });
+
   it("includes referenced markdown files in skill_get by default", async () => {
     const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-default-"));
     const skillFile = path.join(dir, "SKILL.md");
@@ -296,6 +368,90 @@ describe("skill tools", () => {
     ).rejects.toThrow("appears to be a wrapper id");
   });
 
+  it("returns one validated reference file for skill_get_reference", async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-single-"));
+    const skillFile = path.join(dir, "SKILL.md");
+    const referencesDir = path.join(dir, "references");
+    mkdirSync(referencesDir, { recursive: true });
+    writeFileSync(
+      skillFile,
+      [
+        "---",
+        "name: single-ref-skill",
+        "description: one ref",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(
+      path.join(referencesDir, "guide.md"),
+      "# Guide\nOne file only",
+      "utf8",
+    );
+
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "single-ref-skill",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    const result = await handleSkillGetReference(
+      { id: "single-ref-skill", path: "references/guide.md" },
+      manifest,
+      4,
+    );
+    expect(result.content[0].text).toBe("# Guide\nOne file only");
+    expect(result.structuredContent).toMatchObject({
+      skillId: "single-ref-skill",
+      path: "references/guide.md",
+    });
+  });
+
+  it("rejects invalid reference paths for skill_get_reference", async () => {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "mcp-skill-ref-invalid-"));
+    const skillFile = path.join(dir, "SKILL.md");
+    writeFileSync(
+      skillFile,
+      ["---", "name: invalid-ref-skill", "description: invalid", "---", "# Skill"].join(
+        "\n",
+      ),
+      "utf8",
+    );
+    const skillBytes = statSync(skillFile).size;
+    const manifest: VaultManifest = {
+      categories: ["general"],
+      skills: [
+        {
+          id: "invalid-ref-skill",
+          category: "general",
+          path: skillFile,
+          fileBytes: skillBytes,
+        },
+      ],
+      fullCatalogBytes: skillBytes,
+      fullCatalogEstimatedTokens: Math.ceil(skillBytes / 4),
+    };
+
+    await expect(
+      handleSkillGetReference(
+        { id: "invalid-ref-skill", path: "../secret.md" },
+        manifest,
+        4,
+      ),
+    ).rejects.toThrow("Reference path");
+  });
+
   it("returns consolidated budget rollup for selected and loaded skills", () => {
     const manifest = createManifest();
     const result = handleSkillBudgetReport(

package/mcp/src/tools/skillValidate.ts

@@ -0,0 +1,101 @@
+/**
+ * Cubis Foundry MCP Server – skill_validate tool.
+ *
+ * Validates an exact skill ID before skill_get and exposes alias/reference info.
+ */
+
+import { z } from "zod";
+import type { VaultManifest } from "../vault/types.js";
+import {
+  listReferencedMarkdownPaths,
+  readSkillFrontmatter,
+} from "../vault/manifest.js";
+import {
+  buildSkillToolMetrics,
+  estimateTokensFromText,
+} from "../telemetry/tokenBudget.js";
+import { invalidInput } from "../utils/errors.js";
+
+export const skillValidateName = "skill_validate";
+
+export const skillValidateDescription =
+  "Validate an exact skill ID before loading it. Returns alias metadata and discoverable reference markdown paths.";
+
+export const skillValidateSchema = z.object({
+  id: z.string().describe("The exact skill ID (directory name) to validate"),
+});
+
+function assertConcreteSkillId(id: string) {
+  if (id.startsWith("workflow-") || id.startsWith("agent-")) {
+    invalidInput(
+      `Skill id "${id}" appears to be a wrapper id. Use workflow/agent routing (for example $workflow-implement-track or $agent-backend-specialist) and call skill_get only for concrete skill ids.`,
+    );
+  }
+}
+
+export async function handleSkillValidate(
+  args: z.infer<typeof skillValidateSchema>,
+  manifest: VaultManifest,
+  charsPerToken: number,
+) {
+  const { id } = args;
+  assertConcreteSkillId(id);
+
+  const skill = manifest.skills.find((entry) => entry.id === id);
+  if (!skill) {
+    const payload = {
+      id,
+      exists: false,
+      canonicalId: null,
+      category: null,
+      description: null,
+      isWrapper: false,
+      isAlias: false,
+      replacementId: null,
+      availableReferences: [],
+    };
+    const text = JSON.stringify(payload, null, 2);
+    const metrics = buildSkillToolMetrics({
+      charsPerToken,
+      fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+      responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
+      responseCharacterCount: text.length,
+    });
+
+    return {
+      content: [{ type: "text" as const, text }],
+      structuredContent: { ...payload, metrics },
+      _meta: { metrics },
+    };
+  }
+
+  const frontmatter = await readSkillFrontmatter(skill.path);
+  const replacementId =
+    frontmatter.metadata.replaced_by || frontmatter.metadata.alias_of || null;
+  const isAlias = Boolean(replacementId || frontmatter.metadata.deprecated);
+  const availableReferences = await listReferencedMarkdownPaths(skill.path);
+  const payload = {
+    id,
+    exists: true,
+    canonicalId: replacementId || skill.id,
+    category: skill.category,
+    description: frontmatter.description || skill.description || null,
+    isWrapper: false,
+    isAlias,
+    replacementId,
+    availableReferences,
+  };
+  const text = JSON.stringify(payload, null, 2);
+  const metrics = buildSkillToolMetrics({
+    charsPerToken,
+    fullCatalogEstimatedTokens: manifest.fullCatalogEstimatedTokens,
+    responseEstimatedTokens: estimateTokensFromText(text, charsPerToken),
+    responseCharacterCount: text.length,
+  });
+
+  return {
+    content: [{ type: "text" as const, text }],
+    structuredContent: { ...payload, metrics },
+    _meta: { metrics },
+  };
+}

package/mcp/src/vault/manifest.test.ts

@@ -6,9 +6,13 @@ import {
   buildManifest,
   enrichWithDescriptions,
   extractDescription,
+  listReferencedMarkdownPaths,
   parseDescriptionFromFrontmatter,
+  parseSkillFrontmatter,
+  readSkillFrontmatter,
   readFullSkillContent,
   readSkillContentWithReferences,
+  readSkillReferenceFile,
 } from "./manifest.js";
 
 const tempDirs: string[] = [];
@@ -60,6 +64,27 @@ describe("frontmatter description parsing", () => {
     const content = ["---", "name: no-description", "---", "# Body"].join("\n");
     expect(parseDescriptionFromFrontmatter(content, 100)).toBeUndefined();
   });
+
+  it("extracts metadata from skill frontmatter", () => {
+    const content = [
+      "---",
+      "name: alias-skill",
+      "description: Compatibility alias",
+      "metadata:",
+      "  deprecated: true",
+      "  replaced_by: canonical-skill",
+      "---",
+      "# Alias",
+    ].join("\n");
+
+    expect(parseSkillFrontmatter(content)).toEqual({
+      description: "Compatibility alias",
+      metadata: {
+        deprecated: "true",
+        replaced_by: "canonical-skill",
+      },
+    });
+  });
 });
 
 describe("skill content IO", () => {
@@ -92,6 +117,31 @@ describe("skill content IO", () => {
     await expect(readFullSkillContent(file)).resolves.toBe(body);
   });
 
+  it("reads frontmatter metadata from a skill file", async () => {
+    const dir = createTempDir("mcp-frontmatter-read-");
+    const file = path.join(dir, "SKILL.md");
+    writeFileSync(
+      file,
+      [
+        "---",
+        "name: frontmatter-read",
+        "description: Metadata body",
+        "metadata:",
+        "  alias_of: canonical-skill",
+        "---",
+        "# Content",
+      ].join("\n"),
+      "utf8",
+    );
+
+    await expect(readSkillFrontmatter(file)).resolves.toEqual({
+      description: "Metadata body",
+      metadata: {
+        alias_of: "canonical-skill",
+      },
+    });
+  });
+
   it("loads direct local markdown references from SKILL.md", async () => {
     const dir = createTempDir("mcp-refs-read-");
     const file = path.join(dir, "SKILL.md");
@@ -160,6 +210,57 @@ describe("skill content IO", () => {
       { relativePath: "overview.md", content: "# Overview\nSibling content" },
     ]);
   });
+
+  it("lists available reference paths from explicit and sibling markdown files", async () => {
+    const dir = createTempDir("mcp-refs-list-");
+    const file = path.join(dir, "SKILL.md");
+    const refsDir = path.join(dir, "references");
+    mkdirSync(refsDir, { recursive: true });
+    writeFileSync(
+      file,
+      [
+        "---",
+        "name: listed-refs",
+        "description: refs",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(path.join(refsDir, "guide.md"), "# Guide", "utf8");
+    writeFileSync(path.join(dir, "overview.md"), "# Overview", "utf8");
+
+    await expect(listReferencedMarkdownPaths(file)).resolves.toEqual([
+      "overview.md",
+      "references/guide.md",
+    ]);
+  });
+
+  it("reads one validated skill reference file", async () => {
+    const dir = createTempDir("mcp-ref-file-read-");
+    const file = path.join(dir, "SKILL.md");
+    const refsDir = path.join(dir, "references");
+    mkdirSync(refsDir, { recursive: true });
+    writeFileSync(
+      file,
+      [
+        "---",
+        "name: ref-reader",
+        "description: refs",
+        "---",
+        "# Skill",
+        "See [Guide](references/guide.md).",
+      ].join("\n"),
+      "utf8",
+    );
+    writeFileSync(path.join(refsDir, "guide.md"), "# Guide\nReference body", "utf8");
+
+    await expect(readSkillReferenceFile(file, "references/guide.md")).resolves.toEqual({
+      relativePath: "references/guide.md",
+      content: "# Guide\nReference body",
+    });
+  });
 });
 
 describe("manifest enrichment", () => {

package/mcp/src/vault/manifest.ts

@@ -101,6 +101,48 @@ export interface ReferencedSkillFile {
   content: string;
 }
 
+export interface SkillFrontmatter {
+  description?: string;
+  metadata: Record<string, string>;
+}
+
+function parseFrontmatter(content: string): { raw: string; body: string } {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+  if (!match) return { raw: "", body: content };
+  return { raw: match[1], body: content.slice(match[0].length) };
+}
+
+function parseMetadataFromFrontmatter(
+  frontmatter: string,
+): Record<string, string> {
+  const lines = frontmatter.split(/\r?\n/);
+  const metadata: Record<string, string> = {};
+  let inMetadata = false;
+
+  for (const line of lines) {
+    if (/^metadata\s*:\s*$/.test(line)) {
+      inMetadata = true;
+      continue;
+    }
+    if (!inMetadata) continue;
+    if (!line.trim()) continue;
+    if (!/^\s+/.test(line)) break;
+    const kv = line.match(/^\s+([A-Za-z0-9_-]+)\s*:\s*(.+)\s*$/);
+    if (!kv) continue;
+    metadata[kv[1]] = kv[2].trim().replace(/^['"]|['"]$/g, "");
+  }
+
+  return metadata;
+}
+
+export function parseSkillFrontmatter(content: string): SkillFrontmatter {
+  const { raw } = parseFrontmatter(content);
+  return {
+    description: parseDescriptionFromFrontmatter(content, Number.MAX_SAFE_INTEGER),
+    metadata: parseMetadataFromFrontmatter(raw),
+  };
+}
+
 function normalizeLinkTarget(rawTarget: string): string | null {
   let target = String(rawTarget || "").trim();
   if (!target) return null;
@@ -218,6 +260,47 @@ async function collectSiblingMarkdownTargets(
   return targets;
 }
 
+export async function listReferencedMarkdownPaths(
+  skillPath: string,
+  skillContent?: string,
+): Promise<string[]> {
+  const source = skillContent ?? (await readFullSkillContent(skillPath));
+  const skillDir = path.dirname(skillPath);
+  const explicitTargets = collectReferencedMarkdownTargets(source);
+  const siblingTargets = await collectSiblingMarkdownTargets(skillDir);
+  const merged = new Set<string>([...explicitTargets, ...siblingTargets]);
+  return [...merged].sort((a, b) => a.localeCompare(b)).slice(0, MAX_REFERENCED_FILES);
+}
+
+export async function readSkillReferenceFile(
+  skillPath: string,
+  relativePath: string,
+): Promise<ReferencedSkillFile> {
+  const normalized = String(relativePath || "").trim();
+  if (!normalized || !normalized.toLowerCase().endsWith(".md")) {
+    throw new Error("Reference path must be a non-empty relative markdown file.");
+  }
+
+  const available = await listReferencedMarkdownPaths(skillPath);
+  if (!available.includes(normalized)) {
+    throw new Error(
+      `Reference path "${normalized}" is not available for this skill.`,
+    );
+  }
+
+  const skillDir = path.dirname(skillPath);
+  const resolved = path.resolve(skillDir, normalized);
+  const relative = path.relative(skillDir, resolved);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`Reference path "${normalized}" escapes the skill directory.`);
+  }
+
+  return {
+    relativePath: relative.split(path.sep).join("/"),
+    content: await readFile(resolved, "utf8"),
+  };
+}
+
 /**
  * Read full SKILL.md content and any direct local markdown references declared
  * in the skill document. Reference discovery is one-hop (no recursive crawling).
@@ -235,6 +318,13 @@ export async function readSkillContentWithReferences(
   return { skillContent, references };
 }
 
+export async function readSkillFrontmatter(
+  skillPath: string,
+): Promise<SkillFrontmatter> {
+  const content = await readFullSkillContent(skillPath);
+  return parseSkillFrontmatter(content);
+}
+
 /**
  * Enrich skill pointers with descriptions (for browse/search results).
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.62",
+  "version": "0.3.63",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {