@skill-graph/cli 0.5.6

package/scripts/migrate-skill-v3-to-v4.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * Skill Graph codemod: schema_version 3 -> 4.
+ *
+ * Transforms a SKILL.md file, a skill directory, or a directory of skills from
+ * the v3 frontmatter shape to the v4 naming contract.
+ *
+ * Transformations:
+ *
+ *   1. schema_version: 3              -> schema_version: 4
+ *   2. skill.v3.schema.json           -> skill.v4.schema.json
+ *   3. browse_category: <value>       -> category: <value>
+ *   4. category: <path>               -> domain: <path>
+ *   5. category_path: <path>          -> domain: <path>
+ *   6. project_tags: [...]            -> workspace_tags: [...]
+ *   7. routing_groups: [...]          -> routing_bundles: [...]
+ *
+ * What this codemod does NOT do:
+ *   - Does not author a workspace config. Workspace/project ownership is
+ *     generated from `.skill-graph/config.json`, not written into portable
+ *     SKILL.md files.
+ *   - Does not infer missing domain paths. If a v3 skill had only
+ *     browse_category, v4 keeps only category.
+ *
+ * Line-based transformation: preserves comments, quoting style, and
+ * indentation as authored. It only rewrites top-level frontmatter keys.
+ *
+ * Usage:
+ *   node scripts/migrate-skill-v3-to-v4.js <path>
+ *   node scripts/migrate-skill-v3-to-v4.js skills/
+ *   node scripts/migrate-skill-v3-to-v4.js --dry-run <path>
+ *   node scripts/migrate-skill-v3-to-v4.js --include-template <path>
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { workspaceRoot } = require('./lib/roots');
+
+const REPO_ROOT = workspaceRoot();
+const TEMPLATE_PATH = path.join(REPO_ROOT, 'examples', 'skill-metadata-template.md');
+
+function splitFrontmatter(text) {
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  if (lines[0] !== '---') return null;
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') { closeIdx = i; break; }
+  }
+  if (closeIdx === -1) return null;
+  return { lines, closeIdx };
+}
+
+function migrateLine(line) {
+  if (line.includes('https://skillgraph.dev/schemas/skill.v3.schema.json')) {
+    return line.replace('https://skillgraph.dev/schemas/skill.v3.schema.json', 'https://skillgraph.dev/schemas/skill.v4.schema.json');
+  }
+  let m = line.match(/^(\s*)schema_version(\s*:\s*)(["']?)3\3(\s*(?:#.*)?)$/);
+  if (m) return `${m[1]}schema_version${m[2]}${m[3]}4${m[3]}${m[4]}`;
+
+  m = line.match(/^(\s*)browse_category(\s*:.*)$/);
+  if (m) return `${m[1]}category${m[2]}`;
+
+  m = line.match(/^(\s*)category_path(\s*:.*)$/);
+  if (m) return `${m[1]}domain${m[2]}`;
+
+  m = line.match(/^(\s*)category(\s*:.*)$/);
+  if (m) return `${m[1]}domain${m[2]}`;
+
+  m = line.match(/^(\s*)project_tags(\s*:.*)$/);
+  if (m) return `${m[1]}workspace_tags${m[2]}`;
+
+  m = line.match(/^(\s*)routing_groups(\s*:.*)$/);
+  if (m) return `${m[1]}routing_bundles${m[2]}`;
+
+  return line;
+}
+
+function migrateFile(filePath) {
+  const oldText = fs.readFileSync(filePath, 'utf8');
+  const split = splitFrontmatter(oldText);
+  if (!split) return { changed: false, newText: oldText, error: 'no frontmatter block found' };
+
+  const lines = split.lines.slice();
+  let changed = false;
+  for (let i = 1; i < split.closeIdx; i++) {
+    const next = migrateLine(lines[i]);
+    if (next !== lines[i]) {
+      lines[i] = next;
+      changed = true;
+    }
+  }
+  return { changed, newText: lines.join('\n'), error: null };
+}
+
+function collectSkillFiles(targetPath, out = []) {
+  if (!fs.existsSync(targetPath)) return out;
+  const stat = fs.statSync(targetPath);
+  if (stat.isFile()) {
+    if (path.basename(targetPath) === 'SKILL.md' || targetPath.endsWith('.md')) out.push(targetPath);
+    return out;
+  }
+  const directSkill = path.join(targetPath, 'SKILL.md');
+  if (fs.existsSync(directSkill)) out.push(directSkill);
+  for (const entry of fs.readdirSync(targetPath, { withFileTypes: true })) {
+    if (entry.isDirectory()) collectSkillFiles(path.join(targetPath, entry.name), out);
+  }
+  return [...new Set(out)];
+}
+
+function parseArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('Usage: migrate-skill-v3-to-v4.js [--dry-run] [--all] [--skill <name>] [--include-template] [<path>...]');
+    console.log('Default mode writes files. Use --dry-run to preview without writing.');
+    console.log('Must specify --all, --skill <name>, or a positional <path>.');
+    process.exit(0);
+  }
+
+  const skillIdx = argv.indexOf('--skill');
+  const skill = skillIdx !== -1 ? argv[skillIdx + 1] : null;
+  // Positional targets are non-flag args, excluding the --skill value if present.
+  const targets = argv.filter((a, i) => {
+    if (a.startsWith('--')) return false;
+    if (skillIdx !== -1 && i === skillIdx + 1) return false;
+    return true;
+  });
+  return {
+    dryRun: argv.includes('--dry-run'),
+    all: argv.includes('--all'),
+    includeTemplate: argv.includes('--include-template'),
+    skill,
+    targets,
+    hasSkillFlag: skillIdx !== -1,
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  // Arg validation: require at least one targeting argument.
+  if (args.hasSkillFlag && (!args.skill || args.skill.startsWith('--'))) {
+    console.error('ERROR: --skill requires a skill name argument.');
+    process.exit(1);
+  }
+  if (!args.all && !args.skill && args.targets.length === 0) {
+    console.error('ERROR: must specify --skill <name>, --all, or a target path.');
+    process.exit(1);
+  }
+
+  let targetArgs;
+  if (args.skill) {
+    targetArgs = [path.join('skills', args.skill)];
+  } else if (args.all) {
+    targetArgs = ['skills'];
+  } else {
+    targetArgs = args.targets;
+  }
+
+  const targets = [];
+  for (const target of targetArgs) {
+    targets.push(...collectSkillFiles(path.resolve(REPO_ROOT, target)));
+  }
+  if (args.includeTemplate) targets.push(TEMPLATE_PATH);
+
+  if (args.skill && targets.length === 0) {
+    console.error(`ERROR: skill '${args.skill}' not found. Check the skill name and try again.`);
+    process.exit(1);
+  }
+
+  let changed = 0;
+  let failed = 0;
+  for (const filePath of [...new Set(targets)]) {
+    const rel = path.relative(REPO_ROOT, filePath).split(path.sep).join('/');
+    const result = migrateFile(filePath);
+    if (result.error) {
+      console.error(`FAIL  ${rel}: ${result.error}`);
+      failed++;
+      continue;
+    }
+    if (!result.changed) {
+      console.log(`SKIP  ${rel} (already v4 or nothing to migrate)`);
+      continue;
+    }
+    changed++;
+    if (args.dryRun) {
+      console.log(`WOULD ${rel}`);
+    } else {
+      fs.writeFileSync(filePath, result.newText, 'utf8');
+      console.log(`OK    ${rel}`);
+    }
+  }
+
+  console.log(`${args.dryRun ? 'Would migrate' : 'Migrated'} ${changed} file(s); ${failed} failed.`);
+  if (failed > 0) process.exit(1);
+}
+
+if (require.main === module) main();
+
+module.exports = { migrateFile, migrateLine };

package/scripts/migrate-skill-v5-to-v6.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+/**
+ * Skill Graph codemod: schema_version 5 -> 6.
+ *
+ * Transforms a SKILL.md file, a skill directory, or a directory of skills from
+ * the v5 frontmatter shape to v6.
+ *
+ * Transformations:
+ *
+ *   1. schema_version: "5" | 5         -> schema_version: 6
+ *   2. metadata.concept.{mental_model,
+ *      purpose, boundary, analogy,
+ *      misconception}                  -> flat top-level fields under metadata:
+ *      (only when nested sub-field is NOT pipe-empty; v6 retires `taxonomy`)
+ *   3. concept block retained for v5 back-compat (v6 schema anyOf rule)
+ *   4. Body `## Concept Card` section retention: this codemod does NOT touch
+ *      body content. Body section is retired in v6 but removal is out of
+ *      scope here — handle separately if needed.
+ *
+ * What this codemod does NOT do:
+ *   - Does not author flat fields when nested sub-field is pipe-empty ("|") or
+ *     missing. The comprehension grader surfaces the gap; hand-authoring
+ *     produces better content than null-promotion.
+ *   - Does not lift `definition` (covered by `description`) or `taxonomy`
+ *     (covered by `category` + `relations.broader`). Both are retired in v6.
+ *   - Does not delete the nested concept block. The v6 schema retains it via
+ *     anyOf for v5 back-compat; the migration doc explains the deprecation.
+ *   - Does not bump body content, headings, or `## Concept Card` sections.
+ *
+ * Line-based transformation: preserves comments, quoting style, and
+ * indentation as authored. Only inserts flat fields and rewrites the
+ * schema_version line.
+ *
+ * Usage:
+ *   node scripts/migrate-skill-v5-to-v6.js <path>
+ *   node scripts/migrate-skill-v5-to-v6.js skills/
+ *   node scripts/migrate-skill-v5-to-v6.js --dry-run <path>          # default
+ *   node scripts/migrate-skill-v5-to-v6.js --apply <path>
+ *   node scripts/migrate-skill-v5-to-v6.js --skill ref-patterns
+ *
+ * Default mode is dry-run. Pass --apply to write changes.
+ *
+ * See: skill-metadata-protocol/docs/migrations/v5-to-v6.md
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { workspaceRoot } = require('./lib/roots');
+
+const REPO_ROOT = workspaceRoot();
+const V6_FIELDS = ['mental_model', 'purpose', 'boundary', 'analogy', 'misconception'];
+
+function splitFrontmatter(text) {
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  if (lines[0] !== '---') return null;
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') { closeIdx = i; break; }
+  }
+  if (closeIdx === -1) return null;
+  return { lines, closeIdx };
+}
+
+// Find a line `<indent><field>:<rest>` within [start, end). Returns
+// { index, indent, rest } or null. Matches indent ≤ 4 spaces (root or
+// under `metadata:`).
+function findFieldLine(lines, field, start, end) {
+  const re = new RegExp(`^([ \\t]{0,4})${field}:[ \\t]*(.*)$`);
+  for (let i = start; i < end; i++) {
+    const m = lines[i].match(re);
+    if (m) return { index: i, indent: m[1], rest: m[2] };
+  }
+  return null;
+}
+
+// Unwrap a YAML-quoted JSON-stringified string into a plain JSON string.
+// Examples:
+//   '"{\\"definition\\":\\"...\\"}"'   -> '{"definition":"..."}'
+//   '{"definition":"..."}'              -> unchanged
+function unwrapQuotedJson(raw) {
+  let s = raw.trim();
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    s = s.slice(1, -1);
+  }
+  // Unescape YAML-escaped quotes and newlines.
+  s = s.replace(/\\"/g, '"').replace(/\\n/g, '\n');
+  return s;
+}
+
+function parseConceptValue(raw) {
+  const s = unwrapQuotedJson(raw);
+  if (!s.startsWith('{')) return null;
+  try {
+    return JSON.parse(s);
+  } catch (e) {
+    return { __parseError: e.message };
+  }
+}
+
+function isPipeEmpty(v) {
+  if (v === undefined || v === null) return true;
+  const s = String(v).trim();
+  return s === '' || s === '|' || s === '""' || s === "''";
+}
+
+// Format a string value as a YAML field. Single-line -> double-quoted with
+// escaping. Multi-line -> block-scalar with `|` and proper indentation.
+function formatFieldValue(indent, field, value) {
+  const str = String(value);
+  if (!str.includes('\n')) {
+    // Single-line: double-quote with embedded-quote and backslash escape.
+    const escaped = str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `${indent}${field}: "${escaped}"`;
+  }
+  // Multi-line: block-scalar (|) at +2 indent
+  const childIndent = indent + '  ';
+  const body = str.split('\n').map(line => `${childIndent}${line}`).join('\n');
+  return `${indent}${field}: |\n${body}`;
+}
+
+function migrateFile(filePath) {
+  const oldText = fs.readFileSync(filePath, 'utf8');
+  const split = splitFrontmatter(oldText);
+  if (!split) return { changed: false, newText: oldText, error: 'no frontmatter block found', stats: null };
+
+  const lines = split.lines.slice();
+  const fmStart = 1;
+  const fmEnd = split.closeIdx; // exclusive
+
+  const stats = {
+    schemaBumped: false,
+    fieldsLifted: [],
+    fieldsSkippedPipeEmpty: [],
+    fieldsSkippedAlreadyFlat: [],
+    conceptFound: false,
+    conceptParseError: null,
+  };
+
+  // 1. Bump schema_version "5" | 5 -> 6
+  const schemaLine = findFieldLine(lines, 'schema_version', fmStart, fmEnd);
+  if (schemaLine) {
+    const val = schemaLine.rest.trim();
+    if (val === '"5"' || val === "'5'" || val === '5') {
+      lines[schemaLine.index] = `${schemaLine.indent}schema_version: 6`;
+      stats.schemaBumped = true;
+    }
+  }
+
+  // 2. Locate concept block (single-line JSON-stringified value at any indent ≤ 4).
+  const conceptLine = findFieldLine(lines, 'concept', fmStart, fmEnd);
+  if (!conceptLine) {
+    // No concept block to migrate; bump-only file.
+    return finalize();
+  }
+  stats.conceptFound = true;
+
+  const concept = parseConceptValue(conceptLine.rest);
+  if (!concept) {
+    // concept: value isn't a JSON object — maybe it's already a YAML-block-scalar
+    // shape (rare). Leave it untouched.
+    return finalize();
+  }
+  if (concept.__parseError) {
+    stats.conceptParseError = concept.__parseError;
+    return finalize();
+  }
+
+  // 3. For each v6 field, lift to flat top-level (at same indent as concept:)
+  //    when nested sub-field is non-empty AND no flat field already exists.
+  const insertLines = [];
+  for (const field of V6_FIELDS) {
+    const existingFlat = findFieldLine(lines, field, fmStart, fmEnd);
+    if (existingFlat) {
+      stats.fieldsSkippedAlreadyFlat.push(field);
+      continue;
+    }
+    const nestedVal = concept[field];
+    if (isPipeEmpty(nestedVal)) {
+      stats.fieldsSkippedPipeEmpty.push(field);
+      continue;
+    }
+    insertLines.push(formatFieldValue(conceptLine.indent, field, nestedVal));
+    stats.fieldsLifted.push(field);
+  }
+
+  if (insertLines.length > 0) {
+    // Insert flat fields BEFORE the concept: line (so they read together,
+    // flat first as canonical, nested second as v5 back-compat).
+    lines.splice(conceptLine.index, 0, ...insertLines);
+  }
+
+  return finalize();
+
+  function finalize() {
+    const changed = stats.schemaBumped || stats.fieldsLifted.length > 0;
+    return { changed, newText: lines.join('\n'), error: null, stats };
+  }
+}
+
+function collectSkillFiles(targetPath, out = []) {
+  if (!fs.existsSync(targetPath)) return out;
+  const stat = fs.statSync(targetPath);
+  if (stat.isFile()) {
+    if (path.basename(targetPath) === 'SKILL.md' || targetPath.endsWith('.md')) out.push(targetPath);
+    return out;
+  }
+  const directSkill = path.join(targetPath, 'SKILL.md');
+  if (fs.existsSync(directSkill)) out.push(directSkill);
+  for (const entry of fs.readdirSync(targetPath, { withFileTypes: true })) {
+    if (entry.isDirectory()) collectSkillFiles(path.join(targetPath, entry.name), out);
+  }
+  return [...new Set(out)];
+}
+
+function parseArgs(argv) {
+  // Default to dry-run; --apply opts into mutation.
+  const args = { apply: false, skill: null, targets: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--apply') args.apply = true;
+    else if (a === '--dry-run') args.apply = false;
+    else if (a === '--skill') args.skill = argv[++i];
+    else if (a === '--help' || a === '-h') {
+      console.log('Usage: migrate-skill-v5-to-v6.js [--dry-run|--apply] [--skill <name>] [<path>...]');
+      console.log('Default mode is dry-run. Default target is skills/.');
+      process.exit(0);
+    } else if (!a.startsWith('--')) args.targets.push(a);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  let targets = [];
+  if (args.skill) {
+    targets.push(path.resolve(REPO_ROOT, 'skills', args.skill, 'SKILL.md'));
+  } else {
+    const targetArgs = args.targets.length > 0 ? args.targets : ['skills'];
+    for (const target of targetArgs) {
+      targets.push(...collectSkillFiles(path.resolve(REPO_ROOT, target)));
+    }
+    targets = [...new Set(targets)];
+  }
+
+  let touched = 0;
+  let bumpedOnly = 0;
+  let liftedTotal = 0;
+  let parseErrors = 0;
+  let alreadyV6 = 0;
+  let noConcept = 0;
+
+  for (const filePath of targets) {
+    const rel = path.relative(REPO_ROOT, filePath).split(path.sep).join('/');
+    const result = migrateFile(filePath);
+    if (result.error) {
+      console.error(`FAIL  ${rel}: ${result.error}`);
+      continue;
+    }
+    const s = result.stats || {};
+    if (s.conceptParseError) {
+      console.error(`PARSE ${rel}: concept JSON unparseable — ${s.conceptParseError}`);
+      parseErrors++;
+      continue;
+    }
+    if (!result.changed) {
+      if (!s.conceptFound) noConcept++;
+      else alreadyV6++;
+      continue;
+    }
+    touched++;
+    if (s.fieldsLifted.length === 0 && s.schemaBumped) bumpedOnly++;
+    liftedTotal += s.fieldsLifted.length;
+
+    const detail = [
+      s.schemaBumped ? 'schema:5→6' : null,
+      s.fieldsLifted.length > 0 ? `lift:[${s.fieldsLifted.join(',')}]` : null,
+      s.fieldsSkippedPipeEmpty.length > 0 ? `skip-empty:[${s.fieldsSkippedPipeEmpty.join(',')}]` : null,
+      s.fieldsSkippedAlreadyFlat.length > 0 ? `skip-flat:[${s.fieldsSkippedAlreadyFlat.join(',')}]` : null,
+    ].filter(Boolean).join(' ');
+
+    if (args.apply) {
+      fs.writeFileSync(filePath, result.newText, 'utf8');
+      console.log(`OK    ${rel}  | ${detail}`);
+    } else {
+      console.log(`WOULD ${rel}  | ${detail}`);
+    }
+  }
+
+  console.log('');
+  console.log(`${args.apply ? 'Migrated' : 'Would migrate'} ${touched} file(s).`);
+  console.log(`  bumped-only (no liftable fields): ${bumpedOnly}`);
+  console.log(`  total v6 fields lifted:           ${liftedTotal}`);
+  console.log(`  already v6 (no changes needed):   ${alreadyV6}`);
+  console.log(`  no concept block (v6-shaped):     ${noConcept}`);
+  console.log(`  concept JSON parse errors:        ${parseErrors}`);
+  if (parseErrors > 0) process.exit(1);
+}
+
+if (require.main === module) main();
+
+module.exports = { migrateFile, parseConceptValue, formatFieldValue };

package/scripts/restructure-by-category.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+const fs = require("node:fs");
+const path = require("node:path");
+const { execSync } = require("node:child_process");
+
+const ROOT = path.resolve(__dirname, "../../skills/skills");
+const APPLY = process.argv.includes("--apply");
+const QUORUM = 3;
+const VALID = ["foundations", "engineering", "design", "quality", "agent", "product"];
+
+function readFrontmatter(filePath) {
+  const lines = fs.readFileSync(filePath, "utf8").split("\n");
+  if (lines[0] !== "---") return { category: null, domain: null };
+  let inMeta = false, category = null, domain = null;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === "---") break;
+    if (/^metadata:\s*$/.test(line)) { inMeta = true; continue; }
+    if (inMeta && /^[a-zA-Z_]/.test(line)) inMeta = false;
+    if (inMeta) {
+      const c = line.match(/^\s+category:\s*['"]?([a-z]+)['"]?\s*$/);
+      if (c) category = c[1];
+      const d = line.match(/^\s+domain:\s*['"]?([a-z0-9/-]+)['"]?\s*$/);
+      if (d) domain = d[1];
+    } else {
+      const c = line.match(/^category:\s*['"]?([a-z]+)['"]?\s*$/);
+      if (c && !category) category = c[1];
+      const d = line.match(/^domain:\s*['"]?([a-z0-9/-]+)['"]?\s*$/);
+      if (d && !domain) domain = d[1];
+    }
+  }
+  return { category, domain };
+}
+
+const skills = [];
+const errors = [];
+for (const e of fs.readdirSync(ROOT, { withFileTypes: true })) {
+  if (!e.isDirectory() || e.name.startsWith("_") || e.name.startsWith(".")) continue;
+  const md = path.join(ROOT, e.name, "SKILL.md");
+  if (!fs.existsSync(md)) continue;
+  const fm = readFrontmatter(md);
+  if (!fm.category || !VALID.includes(fm.category)) {
+    errors.push({ name: e.name, reason: `category=${fm.category}` });
+    continue;
+  }
+  skills.push({ name: e.name, currentPath: path.join(ROOT, e.name), category: fm.category, domain: fm.domain });
+}
+
+const counts = new Map();
+for (const s of skills) {
+  if (!s.domain) continue;
+  const k = `${s.category}/${s.domain}`;
+  counts.set(k, (counts.get(k) || 0) + 1);
+}
+const planned = skills.map((s) => {
+  const k = s.domain ? `${s.category}/${s.domain}` : null;
+  const useSub = k && counts.get(k) >= QUORUM;
+  const rel = useSub
+    ? path.join(s.category, s.domain.split("/").pop(), s.name)
+    : path.join(s.category, s.name);
+  return { ...s, targetPath: path.join(ROOT, rel), targetRel: rel };
+});
+
+console.log(`${planned.length} skills, ${errors.length} errors`);
+if (errors.length) console.log("Errors:", errors);
+
+if (!APPLY) {
+  console.log("Dry-run. Pass --apply.");
+  process.exit(0);
+}
+
+let moved = 0, failed = 0;
+for (const s of planned) {
+  if (s.currentPath === s.targetPath) continue;
+  const dir = path.dirname(s.targetPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  try {
+    execSync(`git mv "${s.currentPath}" "${s.targetPath}"`, { cwd: ROOT, stdio: "pipe" });
+    moved++;
+  } catch (err) {
+    failed++;
+    console.error(`FAIL ${s.name}: ${err.message.split("\n")[0]}`);
+  }
+}
+console.log(`Moved ${moved}, failed ${failed}.`);