@cubis/foundry 0.3.62 → 0.3.64

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 route_resolve with an explicit workflow command, @agent mention, or compatibility alias before loading concrete skills.`,
+    );
+  }
+}
+
+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,
+      _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,
+    _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;
@@ -146,6 +188,24 @@ function collectReferencedMarkdownTargets(skillContent: string): string[] {
   return targets;
 }
 
+function normalizeInSkillMarkdownTarget(
+  skillDir: string,
+  target: string,
+): string | null {
+  const resolved = path.resolve(skillDir, target);
+  const relative = path.relative(skillDir, resolved);
+
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    return null;
+  }
+
+  if (path.basename(resolved).toLowerCase() === "skill.md") {
+    return null;
+  }
+
+  return relative.split(path.sep).join("/");
+}
+
 async function readReferencedMarkdownFiles(
   skillPath: string,
   skillContent: string,
@@ -218,6 +278,49 @@ 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)
+    .map((target) => normalizeInSkillMarkdownTarget(skillDir, target))
+    .filter((target): target is string => Boolean(target));
+  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 +338,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.64",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {
@@ -29,8 +29,8 @@
   "scripts": {
     "start": "npm run build:cli && node bin/cubis.js",
     "check": "npm run build:cli && node bin/cubis.js --help",
-    "test:attributes": "node scripts/validate-platform-attributes.mjs",
-    "test:attributes:strict": "node scripts/validate-platform-attributes.mjs --strict",
+    "test:attributes": "node scripts/validate-platform-attributes.mjs && node scripts/validate-shared-routing.mjs && node scripts/validate-skill-packaging.mjs && node scripts/validate-runtime-wiring.mjs && node scripts/generate-skills-index.mjs --check",
+    "test:attributes:strict": "node scripts/validate-platform-attributes.mjs --strict && node scripts/validate-shared-routing.mjs && node scripts/validate-skill-packaging.mjs && node scripts/validate-runtime-wiring.mjs && node scripts/generate-skills-index.mjs --check",
     "test:tech-md": "node scripts/test-tech-md-scanner.mjs",
     "test:smoke": "npm run build:cli && bash scripts/smoke-workflows.sh",
     "test:init:tty": "npm run build:cli && expect scripts/test-init-tty.exp bin/cubis.js",
@@ -40,6 +40,7 @@
     "generate:platform-assets": "node scripts/generate-platform-assets.mjs",
     "sync:skill-mirrors": "node scripts/sync-skill-mirrors.mjs",
     "generate:skills-index": "node scripts/generate-skills-index.mjs",
+    "check:skills-index": "node scripts/generate-skills-index.mjs --check",
     "generate:mcp-manifest": "node scripts/generate-mcp-manifest.mjs",
     "generate:mcp-rules-block": "node scripts/generate-mcp-rules-block.mjs",
     "inject:mcp-rules:codex": "node scripts/generate-mcp-rules-block.mjs --inject workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md",
@@ -62,7 +63,7 @@
     "generate:powers:sync": "node \"workflows/scripts/generate-powers.mjs\" --sync-skills --force",
     "build:cli": "tsc -p tsconfig.cli.json",
     "clean:cli": "rm -rf dist/cli",
-    "prepack": "npm run build:cli"
+    "prepack": "npm run build:cli && npm run check:skills-index"
   },
   "engines": {
     "node": ">=18.17"

package/src/cli/constants.ts

@@ -1,3 +1,3 @@
 export const CLI_NAME = "cbx";
 export const AGENT_ASSETS_SUBDIR = "workflows";
-export const DEFAULT_SKILL_PROFILE = "core";
+export const DEFAULT_SKILL_PROFILE = "full";