@withpica/mcp-server 2.50.0 → 2.51.0

package/scripts/build-skills.ts

@@ -0,0 +1,229 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * ADR-140 Phase 2b — generator for `skills.generated.ts`.
+ *
+ * Reads `src/skills/<name>/SKILL.md` files, parses YAML frontmatter, and emits
+ * a TypeScript constant consumed by SkillsRegistry. Generation at build time
+ * (not runtime FS reads) so npm-published `dist/` ships bundled bytes — `.md`
+ * files are excluded by `.npmignore`.
+ *
+ * Frontmatter shape:
+ *   ---
+ *   name: kebab-case-name
+ *   description: one-line
+ *   triggers:
+ *     - phrase one
+ *     - phrase two
+ *   audience: manager / artist / etc
+ *   tools_required:
+ *     - tool_a
+ *     - tool_b
+ *   output: one-line description
+ *   ---
+ *
+ * Hand-rolled YAML parser (frontmatter only — no nested objects, no anchors).
+ * Adding a `js-yaml` dep would be overkill for the constrained shape.
+ *
+ * Re-runs are deterministic: same .md files produce a byte-identical output.
+ */
+
+import { readFileSync, readdirSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const MCP_SERVER_ROOT = join(__dirname, "..");
+const SKILLS_ROOT = join(MCP_SERVER_ROOT, "src/skills");
+const OUTPUT_PATH = join(SKILLS_ROOT, "skills.generated.ts");
+
+interface SkillFrontmatter {
+  name: string;
+  description: string;
+  triggers: string[];
+  audience: string;
+  tools_required: string[];
+  output: string;
+}
+
+interface ParsedSkill extends SkillFrontmatter {
+  body: string;
+}
+
+function parseFrontmatter(src: string, sourceFile: string): ParsedSkill {
+  // Strip leading HTML comment (copyright header) if present, then expect ---
+  let i = 0;
+  if (src.startsWith("<!--")) {
+    const end = src.indexOf("-->");
+    if (end === -1) {
+      throw new Error(`${sourceFile}: unterminated HTML comment header`);
+    }
+    i = end + 3;
+    // Skip whitespace/newlines
+    while (i < src.length && /\s/.test(src[i])) i++;
+  }
+
+  if (src.slice(i, i + 3) !== "---") {
+    throw new Error(`${sourceFile}: missing --- frontmatter opener`);
+  }
+  i += 3;
+  // Skip newline after opener
+  while (i < src.length && src[i] !== "\n") i++;
+  i++;
+
+  const closeIdx = src.indexOf("\n---", i);
+  if (closeIdx === -1) {
+    throw new Error(`${sourceFile}: missing --- frontmatter closer`);
+  }
+
+  const frontmatterText = src.slice(i, closeIdx);
+  const bodyStart = closeIdx + 4; // skip \n---
+  const body = src.slice(bodyStart).replace(/^\n+/, "").trimEnd() + "\n";
+
+  // Parse: key: value OR key: (list follows)
+  const fm: Record<string, string | string[]> = {};
+  const lines = frontmatterText.split("\n");
+  let currentListKey: string | null = null;
+
+  for (const line of lines) {
+    if (line.trim() === "") {
+      currentListKey = null;
+      continue;
+    }
+    const listItemMatch = line.match(/^\s+-\s+(.+)$/);
+    if (listItemMatch && currentListKey) {
+      (fm[currentListKey] as string[]).push(listItemMatch[1].trim());
+      continue;
+    }
+    const kvMatch = line.match(/^([a-z_][a-z0-9_]*)\s*:\s*(.*)$/i);
+    if (!kvMatch) continue;
+    const key = kvMatch[1];
+    const value = kvMatch[2].trim();
+    if (value === "") {
+      // List follows
+      fm[key] = [];
+      currentListKey = key;
+    } else {
+      fm[key] = value;
+      currentListKey = null;
+    }
+  }
+
+  // Validate required fields
+  const required = [
+    "name",
+    "description",
+    "triggers",
+    "audience",
+    "tools_required",
+    "output",
+  ];
+  for (const field of required) {
+    if (!(field in fm)) {
+      throw new Error(`${sourceFile}: missing required frontmatter field "${field}"`);
+    }
+  }
+  if (!Array.isArray(fm.triggers) || fm.triggers.length === 0) {
+    throw new Error(`${sourceFile}: triggers must be a non-empty list`);
+  }
+  if (!Array.isArray(fm.tools_required) || fm.tools_required.length === 0) {
+    throw new Error(`${sourceFile}: tools_required must be a non-empty list`);
+  }
+
+  return {
+    name: fm.name as string,
+    description: fm.description as string,
+    triggers: fm.triggers as string[],
+    audience: fm.audience as string,
+    tools_required: fm.tools_required as string[],
+    output: fm.output as string,
+    body,
+  };
+}
+
+function discoverSkills(): ParsedSkill[] {
+  if (!existsSync(SKILLS_ROOT)) {
+    return [];
+  }
+  const entries = readdirSync(SKILLS_ROOT, { withFileTypes: true });
+  const skills: ParsedSkill[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = join(SKILLS_ROOT, entry.name, "SKILL.md");
+    if (!existsSync(skillFile)) continue;
+    const src = readFileSync(skillFile, "utf-8");
+    const parsed = parseFrontmatter(src, `src/skills/${entry.name}/SKILL.md`);
+    if (parsed.name !== entry.name) {
+      throw new Error(
+        `src/skills/${entry.name}/SKILL.md: frontmatter name "${parsed.name}" must match directory name "${entry.name}"`,
+      );
+    }
+    skills.push(parsed);
+  }
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+  return skills;
+}
+
+function emit(skills: ParsedSkill[]): string {
+  const header = `// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Regenerated by \`scripts/build-skills.ts\` from \`src/skills/<name>/SKILL.md\`.
+ * Runs in \`prebuild\` and \`prepublishOnly\`. See ADR-140 Phase 2b.
+ */
+
+export interface Skill {
+  /** Stable kebab-case identifier matching the directory name. */
+  name: string;
+  /** One-line description shown in pica_skill_list. */
+  description: string;
+  /** Trigger phrases an agent should recognise as invoking this skill. */
+  triggers: string[];
+  /** Audience tag (manager / artist / sync supervisor / etc). */
+  audience: string;
+  /** Tools the skill body chains. Lint-checkable. */
+  tools_required: string[];
+  /** One-line output shape description. */
+  output: string;
+  /** Full skill methodology body — markdown, exposed by pica_skill_get. */
+  body: string;
+}
+
+`;
+  const lines: string[] = [header, "export const SKILLS: Record<string, Skill> = {"];
+  for (const skill of skills) {
+    lines.push(`  ${JSON.stringify(skill.name)}: {`);
+    lines.push(`    name: ${JSON.stringify(skill.name)},`);
+    lines.push(`    description: ${JSON.stringify(skill.description)},`);
+    lines.push(`    triggers: ${JSON.stringify(skill.triggers)},`);
+    lines.push(`    audience: ${JSON.stringify(skill.audience)},`);
+    lines.push(`    tools_required: ${JSON.stringify(skill.tools_required)},`);
+    lines.push(`    output: ${JSON.stringify(skill.output)},`);
+    lines.push(`    body: ${JSON.stringify(skill.body)},`);
+    lines.push(`  },`);
+  }
+  lines.push("};");
+  lines.push("");
+  lines.push(
+    `export const SKILL_NAMES: ReadonlyArray<string> = ${JSON.stringify(skills.map((s) => s.name))};`,
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+
+function main(): void {
+  const skills = discoverSkills();
+  const output = emit(skills);
+  writeFileSync(OUTPUT_PATH, output, "utf-8");
+  console.log(
+    `[build-skills] Wrote ${skills.length} skill(s) to src/skills/skills.generated.ts`,
+  );
+  for (const skill of skills) {
+    console.log(`  - ${skill.name} (${skill.body.length} bytes body)`);
+  }
+}
+
+main();

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/withpica/pica",
     "source": "github"
   },
-  "version": "2.50.0",
+  "version": "2.51.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@withpica/mcp-server",
-      "version": "2.50.0",
+      "version": "2.51.0",
       "transport": {
         "type": "stdio"
       }