@skill-graph/cli 0.5.6

package/schemas/vocabulary/keywords.json

@@ -0,0 +1,180 @@
+{
+  "$comment": "Controlled vocabulary for the `keywords` field across Skill Graph skills. Prevents drift like 'e-commerce' vs 'ecommerce' as a library scales. Scope: soft-advisory — skill-lint.js emits a WARNING (not an error) when a skill uses a keyword not in this list. Update when a genuinely new domain emerges; do not over-curate.",
+  "version": "1.0.0",
+  "last_updated": "2026-05-11",
+  "synonyms": {
+    "e-commerce": "ecommerce",
+    "eCommerce": "ecommerce",
+    "e commerce": "ecommerce",
+    "nextjs": "next.js",
+    "nextJS": "next.js",
+    "NextJS": "next.js",
+    "dev": "engineering",
+    "development": "engineering",
+    "a11y": "accessibility",
+    "i18n": "internationalization",
+    "localisation": "localization",
+    "postgres": "postgresql",
+    "postgreSQL": "postgresql",
+    "nodeJS": "node.js",
+    "nodejs": "node.js",
+    "typescript-strict": "typescript",
+    "ts": "typescript",
+    "js": "javascript"
+  },
+  "canonical": [
+    "accessibility",
+    "agent-framework",
+    "skill-md",
+    "ai-agents",
+    "analytics",
+    "api",
+    "api-design",
+    "architecture",
+    "auditing",
+    "authentication",
+    "authorization",
+    "automation",
+    "async-api",
+    "backend",
+    "benchmarking",
+    "browser-automation",
+    "build-tooling",
+    "caching",
+    "ci-cd",
+    "cli",
+    "cloudevents",
+    "code-quality",
+    "code-review",
+    "compliance",
+    "configuration",
+    "content-strategy",
+    "contracts",
+    "copywriting",
+    "cron",
+    "css",
+    "dashboard",
+    "data-migration",
+    "data-modeling",
+    "data-pipeline",
+    "data-visualization",
+    "database",
+    "dbt",
+    "debugging",
+    "deployment",
+    "design-system",
+    "design-tokens",
+    "devops",
+    "docker",
+    "documentation",
+    "domain-driven-design",
+    "ecommerce",
+    "encryption",
+    "engineering",
+    "entity-resolution",
+    "error-handling",
+    "evaluation",
+    "event-contract",
+    "event-driven",
+    "fallback-strategy",
+    "feature-flags",
+    "fetch",
+    "financial-metrics",
+    "form-validation",
+    "form-ux",
+    "forms",
+    "frontend",
+    "fulfillment",
+    "gdpr",
+    "graphql",
+    "grounding",
+    "hitl",
+    "hooks",
+    "html",
+    "information-architecture",
+    "inngest",
+    "integration",
+    "internationalization",
+    "interaction-feedback",
+    "interaction-patterns",
+    "javascript",
+    "json",
+    "knowledge-graph",
+    "layout",
+    "legal",
+    "linear",
+    "linting",
+    "load-testing",
+    "localization",
+    "logging",
+    "markdown",
+    "layout-composition",
+    "mcp",
+    "memory",
+    "metrics",
+    "microcopy",
+    "middleware",
+    "migration",
+    "motion-design",
+    "multi-tenancy",
+    "neon",
+    "next.js",
+    "node.js",
+    "observability",
+    "ontology",
+    "orchestration",
+    "payments",
+    "performance",
+    "playwright",
+    "postgresql",
+    "prisma",
+    "privacy",
+    "product-strategy",
+    "prompt-engineering",
+    "provenance",
+    "quality",
+    "radix-ui",
+    "rate-limiting",
+    "react",
+    "real-time",
+    "refactoring",
+    "regression-testing",
+    "reliability",
+    "rendering",
+    "responsive",
+    "rest",
+    "retry",
+    "review",
+    "rls",
+    "routing",
+    "scss",
+    "security",
+    "seo",
+    "shopify",
+    "skill-audit",
+    "skill-graph",
+    "skill-routing",
+    "skill-scaffolding",
+    "stripe",
+    "taxonomy",
+    "telemetry",
+    "testing",
+    "theme",
+    "threading",
+    "tokens",
+    "tooling",
+    "typescript",
+    "ui",
+    "unit-testing",
+    "ux",
+    "validation",
+    "vercel",
+    "version-control",
+    "visual-design",
+    "webhook",
+    "websocket",
+    "woocommerce",
+    "workflow",
+    "yaml"
+  ]
+}

package/schemas/vocabulary/workspace_tags.json

@@ -0,0 +1,23 @@
+{
+  "$comment": "Controlled vocabulary for the `workspace_tags` field. Adopters declare their own literal project handles in their workspace config (`.skill-graph/config.json`); only `skill-graph` (this repo) is shipped as a literal handle. Semantic tags below are illustrative categories cross-project tags commonly fall into. Extend with your own. Scope: soft-advisory; skill-lint.js emits WARNING (not error) for unknown tags.",
+  "version": "2.0.0",
+  "last_updated": "2026-05-14",
+  "literal_project_handles": [
+    "skill-graph"
+  ],
+  "semantic_tags": [
+    "ecommerce",
+    "saas",
+    "b2b",
+    "b2c",
+    "ai-agent",
+    "design-system",
+    "infrastructure",
+    "analytics",
+    "integrations"
+  ],
+  "synonyms": {
+    "e-commerce": "ecommerce",
+    "eCommerce": "ecommerce"
+  }
+}

package/scripts/__tests__/migrate-skill-v2-to-v3.test.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Tests for migrate-skill-v2-to-v3.js CLI safety surface.
+ *
+ * Verifies exit codes and flag behaviour without touching migration logic.
+ * Uses spawnSync so each test is fully isolated from the current process.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const SCRIPT = path.join(REPO_ROOT, 'scripts', 'migrate-skill-v2-to-v3.js');
+
+// ---------------------------------------------------------------------------
+// Minimal v2 SKILL.md fixture (has a field to migrate: family → browse_category).
+// ---------------------------------------------------------------------------
+const V2_FIXTURE = `---
+schema_version: 2
+name: test-skill
+family: Testing
+---
+# Test Skill
+`;
+
+// A skill that is already v3 — nothing to migrate.
+const V3_FIXTURE = `---
+schema_version: 3
+name: test-skill
+browse_category: Testing
+---
+# Test Skill
+`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function run(args) {
+  return spawnSync(process.execPath, [SCRIPT, ...args], {
+    encoding: 'utf8',
+    env: process.env,
+  });
+}
+
+function withTempDir(fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'v2-to-v3-test-'));
+  try {
+    return fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function writeFixture(dir, skillName, content) {
+  const skillDir = path.join(dir, skillName);
+  fs.mkdirSync(skillDir, { recursive: true });
+  const skillMd = path.join(skillDir, 'SKILL.md');
+  fs.writeFileSync(skillMd, content, 'utf8');
+  return skillMd;
+}
+
+// ---------------------------------------------------------------------------
+// Test harness
+// ---------------------------------------------------------------------------
+
+let passed = 0;
+let failed = 0;
+
+function test(label, fn) {
+  try {
+    fn();
+    process.stdout.write(`PASS migrate-skill-v2-to-v3: ${label}\n`);
+    passed++;
+  } catch (err) {
+    process.stderr.write(`FAIL migrate-skill-v2-to-v3: ${label}\n  ${err.message}\n`);
+    failed++;
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg);
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: --help exits 0, prints usage, writes nothing.
+// ---------------------------------------------------------------------------
+test('--help exits 0 and prints usage', () => {
+  const result = run(['--help']);
+  assert(result.status === 0, `expected exit 0, got ${result.status}`);
+  assert(result.stdout.includes('Usage:'), `expected "Usage:" in stdout, got: ${result.stdout}`);
+});
+
+// ---------------------------------------------------------------------------
+// Test 2: No args exits 1 with error message.
+// ---------------------------------------------------------------------------
+test('no args exits 1 with error', () => {
+  const result = run([]);
+  assert(result.status === 1, `expected exit 1, got ${result.status}`);
+  assert(
+    result.stderr.includes('must specify') || result.stderr.includes('ERROR'),
+    `expected error in stderr, got: ${result.stderr}`
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Test 3: --skill <nonexistent> exits 1.
+// ---------------------------------------------------------------------------
+test('--skill <nonexistent> exits 1', () => {
+  const result = run(['--skill', 'does-not-exist-skill-xyz']);
+  assert(result.status === 1, `expected exit 1, got ${result.status}`);
+});
+
+// ---------------------------------------------------------------------------
+// Test 4: --all --dry-run exits 0, reports 0 files migrated.
+// ---------------------------------------------------------------------------
+test('--all --dry-run exits 0, reports 0 files migrated', () => {
+  // --all scans the repo's skills/ dir which is empty / does not exist in
+  // the skill-graph repo itself — this is the "already fully migrated" case.
+  const result = run(['--all', '--dry-run']);
+  assert(
+    result.status === 0,
+    `expected exit 0, got ${result.status}\nstdout: ${result.stdout}\nstderr: ${result.stderr}`
+  );
+  assert(
+    result.stdout.includes('0 file') || result.stdout.includes('0 would'),
+    `expected 0-files report, got: ${result.stdout}`
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Test 5: --dry-run with a v2 file exits 0 and shows DIFF, not OK.
+// ---------------------------------------------------------------------------
+test('--dry-run shows DIFF and exits 0 for a v2 file', () => {
+  withTempDir(dir => {
+    const skillMd = writeFixture(dir, 'test-skill', V2_FIXTURE);
+    // Pass the SKILL.md path directly as a positional argument.
+    const result = run(['--dry-run', skillMd]);
+    assert(
+      result.status === 0,
+      `expected exit 0, got ${result.status}\nstdout: ${result.stdout}\nstderr: ${result.stderr}`
+    );
+    assert(
+      result.stdout.includes('DIFF') || result.stdout.includes('SKIP') || result.stdout.includes('would migrate'),
+      `expected dry-run marker in stdout, got: ${result.stdout}`
+    );
+    // Verify the file was NOT modified.
+    const afterContent = fs.readFileSync(skillMd, 'utf8');
+    assert(afterContent === V2_FIXTURE, 'dry-run must not write the file');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+process.stdout.write(`\nmigrate-skill-v2-to-v3: ${passed} passed, ${failed} failed.\n`);
+if (failed > 0) process.exit(1);

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Tests for migrate-skill-v3-to-v4.js CLI safety surface.
+ *
+ * Verifies exit codes and flag behaviour without touching migration logic.
+ * Uses spawnSync so each test is fully isolated from the current process.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const SCRIPT = path.join(REPO_ROOT, 'scripts', 'migrate-skill-v3-to-v4.js');
+
+// ---------------------------------------------------------------------------
+// Minimal v3 SKILL.md fixture (has a field to migrate: browse_category).
+// ---------------------------------------------------------------------------
+const V3_FIXTURE = `---
+schema_version: 3
+name: test-skill
+browse_category: Testing
+---
+# Test Skill
+`;
+
+// A skill that is already v4 — nothing to migrate.
+const V4_FIXTURE = `---
+schema_version: 4
+name: test-skill
+category: Testing
+---
+# Test Skill
+`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function run(args, env) {
+  return spawnSync(process.execPath, [SCRIPT, ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+}
+
+function withTempDir(fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'v3-to-v4-test-'));
+  try {
+    return fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function writeFixture(dir, content) {
+  const skillDir = path.join(dir, 'test-skill');
+  fs.mkdirSync(skillDir, { recursive: true });
+  const skillMd = path.join(skillDir, 'SKILL.md');
+  fs.writeFileSync(skillMd, content, 'utf8');
+  return skillMd;
+}
+
+// ---------------------------------------------------------------------------
+// Test harness
+// ---------------------------------------------------------------------------
+
+let passed = 0;
+let failed = 0;
+
+function test(label, fn) {
+  try {
+    fn();
+    process.stdout.write(`PASS migrate-skill-v3-to-v4: ${label}\n`);
+    passed++;
+  } catch (err) {
+    process.stderr.write(`FAIL migrate-skill-v3-to-v4: ${label}\n  ${err.message}\n`);
+    failed++;
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg);
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: --help exits 0, prints usage, writes nothing.
+// ---------------------------------------------------------------------------
+test('--help exits 0 and prints usage', () => {
+  withTempDir(dir => {
+    const result = run(['--help']);
+    assert(result.status === 0, `expected exit 0, got ${result.status}`);
+    assert(result.stdout.includes('Usage:'), `expected "Usage:" in stdout, got: ${result.stdout}`);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test 2: No args exits 1 with error message.
+// ---------------------------------------------------------------------------
+test('no args exits 1 with error', () => {
+  const result = run([]);
+  assert(result.status === 1, `expected exit 1, got ${result.status}`);
+  assert(
+    result.stderr.includes('must specify') || result.stderr.includes('ERROR'),
+    `expected error in stderr, got: ${result.stderr}`
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Test 3: --skill <nonexistent> exits 1.
+// ---------------------------------------------------------------------------
+test('--skill <nonexistent> exits 1', () => {
+  const result = run(['--skill', 'does-not-exist-skill-xyz']);
+  assert(result.status === 1, `expected exit 1, got ${result.status}`);
+});
+
+// ---------------------------------------------------------------------------
+// Test 4: --all --dry-run exits 0, reports 0 files (already v4 or empty).
+// ---------------------------------------------------------------------------
+test('--all --dry-run exits 0, reports 0 files (already v4)', () => {
+  // --all scans the repo's skills/ dir which is empty / does not exist in
+  // the skill-graph repo itself — all skills are already v4 or above.
+  const result = run(['--all', '--dry-run']);
+  assert(
+    result.status === 0,
+    `expected exit 0, got ${result.status}\nstdout: ${result.stdout}\nstderr: ${result.stderr}`
+  );
+  assert(
+    result.stdout.includes('0 file(s)'),
+    `expected "0 file(s)" in output, got: ${result.stdout}`
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Test 5: --dry-run with a v3 file exits 0 and prints WOULD, not OK.
+// ---------------------------------------------------------------------------
+test('--dry-run shows WOULD and exits 0 for a v3 file', () => {
+  withTempDir(dir => {
+    const skillMd = writeFixture(dir, V3_FIXTURE);
+    // Pass the file directly as a positional argument.
+    const result = run(['--dry-run', skillMd]);
+    assert(result.status === 0, `expected exit 0, got ${result.status}\nstdout: ${result.stdout}\nstderr: ${result.stderr}`);
+    assert(result.stdout.includes('WOULD'), `expected "WOULD" in stdout, got: ${result.stdout}`);
+    assert(!result.stdout.includes('OK    '), `expected no "OK" writes in dry-run mode, got: ${result.stdout}`);
+    // Verify the file was NOT modified.
+    const afterContent = fs.readFileSync(skillMd, 'utf8');
+    assert(afterContent === V3_FIXTURE, 'dry-run must not write the file');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+process.stdout.write(`\nmigrate-skill-v3-to-v4: ${passed} passed, ${failed} failed.\n`);
+if (failed > 0) process.exit(1);

package/scripts/__tests__/test-export-parser-drift.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Regression tests for export, frontmatter parsing, drift URL handling, and
+ * schema-conditional lint enforcement.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { buildExportedSkill, extractBody, normalizeExportName } = require('../export-skill');
+const { parseFrontmatter } = require('../lib/parse-frontmatter');
+const { sha256TruthSource } = require('../skill-graph-drift');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+function fail(msg) {
+  process.stderr.write(`FAIL test-export-parser-drift: ${msg}\n`);
+  process.exit(1);
+}
+
+function assert(condition, msg) {
+  if (!condition) fail(msg);
+}
+
+function assertIncludes(value, expected, msg) {
+  if (!String(value).includes(expected)) {
+    fail(`${msg}; expected ${JSON.stringify(expected)} in ${JSON.stringify(String(value).slice(0, 500))}`);
+  }
+}
+
+const crlfSkill = [
+  '---',
+  'schema_version: 4',
+  'name: org/foo:bar',
+  'description: "Use when testing export behavior. Do NOT use for production docs."',
+  'version: 1.0.0',
+  'type: capability',
+  'category: quality',
+  'scope: portable',
+  'owner: test',
+  'freshness: "2026-05-13"',
+  'drift_check:',
+  '  last_verified: "2026-05-13"',
+  'eval_artifacts: none',
+  'eval_state: unverified',
+  'routing_eval: absent',
+  'workspace_tags: [ecommerce, shopify]',
+  'grounding:',
+  '  truth_sources:',
+  '    - path: docs/field-reference.md',
+  '      line_range: { start: 1, end: 3 }',
+  '---',
+  '# Body',
+  '',
+  'Body survives CRLF export.',
+  '',
+].join('\r\n');
+
+assert(extractBody(crlfSkill).startsWith('# Body'), 'extractBody should preserve CRLF bodies');
+
+const exported = buildExportedSkill(crlfSkill);
+assert(exported, 'buildExportedSkill should return output for parseable input');
+assertIncludes(exported, 'name: org-foo-bar', 'export should normalize namespaced Skill Graph names');
+assertIncludes(exported, '# Body', 'export should include source body');
+assert(normalizeExportName('org/foo:bar') === 'org-foo-bar', 'normalizeExportName should replace / and : with hyphens');
+
+const parsed = parseFrontmatter(crlfSkill);
+assert(Array.isArray(parsed.workspace_tags), 'inline arrays should parse as arrays');
+assert(parsed.workspace_tags[0] === 'ecommerce', 'inline array values should parse as scalars');
+assert(
+  parsed.grounding.truth_sources[0].line_range &&
+  parsed.grounding.truth_sources[0].line_range.start === 1 &&
+  parsed.grounding.truth_sources[0].line_range.end === 3,
+  'inline maps should parse as objects'
+);
+
+const parsedSequenceObject = parseFrontmatter([
+  '---',
+  'relations:',
+  '  boundary:',
+  '    - { skill: debugging, reason: "runtime failure" }',
+  '---',
+  '',
+].join('\n'));
+assert(
+  parsedSequenceObject.relations.boundary[0].skill === 'debugging',
+  'inline object sequence items should parse as objects'
+);
+
+const remoteHash = sha256TruthSource('https://example.com/spec');
+assert(remoteHash.external, 'remote truth sources should be marked external');
+assert(remoteHash.hash === null, 'remote truth sources should not be locally hashed');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-graph-lint-'));
+try {
+  const skillDir = path.join(tempRoot, 'deprecated-missing');
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), [
+    '---',
+    'schema_version: 4',
+    'name: deprecated-missing',
+    'description: "Use when testing conditional lint enforcement. Do NOT use for real skills."',
+    'version: 1.0.0',
+    'type: capability',
+    'category: quality',
+    'scope: portable',
+    'owner: test',
+    'freshness: "2026-05-13"',
+    'drift_check:',
+    '  last_verified: "2026-05-13"',
+    'eval_artifacts: none',
+    'eval_state: unverified',
+    'routing_eval: absent',
+    'stability: deprecated',
+    'comprehension_state: present',
+    '---',
+    '# Deprecated Missing',
+    '',
+    '## Coverage',
+    'Enough text to avoid section-empty warnings while testing conditionals.',
+    '',
+    '## Philosophy',
+    'Enough text to avoid section-empty warnings while testing conditionals.',
+    '',
+    '## Verification',
+    'Enough text to avoid section-empty warnings while testing conditionals.',
+    '',
+    '## Do NOT Use When',
+    'Enough text to avoid section-empty warnings while testing conditionals.',
+    '',
+  ].join('\n'), 'utf8');
+
+  const result = spawnSync(
+    process.execPath,
+    [path.join(REPO_ROOT, 'scripts', 'skill-lint.js'), skillDir, '--no-color', '--skip-generator-parity'],
+    { cwd: REPO_ROOT, encoding: 'utf8' }
+  );
+  const output = `${result.stdout}\n${result.stderr}`;
+  assert(result.status === 1, 'lint should fail for missing conditional fields');
+  assertIncludes(output, 'stability: deprecated requires superseded_by field', 'lint should enforce deprecated replacement');
+  assertIncludes(output, 'comprehension_state: present requires concept field', 'lint should enforce concept block');
+} finally {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+process.stdout.write('PASS test-export-parser-drift: export/parser/drift/lint edge cases covered\n');