@skill-graph/cli 0.5.6

package/scripts/lint/check-stability-promotion.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * Stability promotion gate for SKILL.md files (lint check 14).
+ *
+ * **S1 — stability: stable requires promotion criteria (WARN)**
+ *   A skill that declares `stability: stable` is claiming its content is
+ *   settled and suitable for production dependence. This check enforces that
+ *   the claim is backed by evidence across five independently-checked criteria.
+ *
+ *   All failures are WARN level — never ERROR. Setting `stability: stable`
+ *   does not break builds; it triggers an audit trail so authors know which
+ *   criteria remain unmet. This design choice is intentional: 141 skills are
+ *   currently `experimental`. If violations were errors, a single `stable`
+ *   claim on an unready skill would block the entire lint run for that skill.
+ *   Warnings surface the gap without creating a false blocker.
+ *
+ *   The five promotion criteria (all checked independently — no short-circuit):
+ *
+ *     1. `eval_state` ≠ `unverified` — evals have been run at least once.
+ *        `passing` or `monitored` both satisfy this criterion.
+ *
+ *     2. `eval_score` ≥ 4.0 (80% of the 0.0–5.0 audit scale) — the most
+ *        recent graded audit score meets the quality bar. Absent `eval_score`
+ *        fails this criterion because an unscored skill has no evidence of
+ *        quality.
+ *
+ *     3. `routing_eval: present` — routing coverage is explicitly evaluated.
+ *        A stable skill must prove it activates correctly, not just claim it
+ *        does.
+ *
+ *     4. `drift_check.last_verified` within the last 90 days — the skill has
+ *        been actively maintained. A last_verified date older than 90 days
+ *        indicates the content may have drifted from its truth sources.
+ *
+ *     5. `grounding.truth_sources` populated (for `scope: codebase` and
+ *        `scope: reference` skills) OR `scope: portable` (general skills with
+ *        no codebase tie-in are exempt from this criterion). A stable
+ *        codebase/reference skill must declare what it is grounded in.
+ *
+ * @module lint/check-stability-promotion
+ */
+
+'use strict';
+
+/**
+ * Minimum eval score to qualify for stable promotion.
+ * Maps to 80% of the 0.0–5.0 audit scale used by scripts/skill-audit.js.
+ */
+const STABLE_EVAL_SCORE_THRESHOLD = 4.0;
+
+/**
+ * Maximum age in days for drift_check.last_verified before a stable skill
+ * is considered potentially drifted.
+ */
+const STABLE_DRIFT_MAX_DAYS = 90;
+
+/**
+ * Scope values that require grounding.truth_sources to be populated.
+ * portable-scope skills are exempt (criterion 5 does not apply).
+ */
+const GROUNDING_REQUIRED_SCOPES = ['codebase', 'reference'];
+
+/**
+ * Run the stability-promotion check on one SKILL.md file.
+ *
+ * Only fires when `stability === "stable"`. When the skill is experimental
+ * or deprecated, or when `stability` is absent, this function returns early
+ * with empty arrays.
+ *
+ * All findings are WARN level. The caller is responsible for routing them
+ * into the warning track rather than the error track.
+ *
+ * @param {object} opts
+ * @param {string}  opts.filePath    - Path to the file (used in messages only).
+ * @param {string}  opts.sourceText  - Full file content.
+ * @param {object}  opts.fm          - Parsed frontmatter object.
+ * @param {Date}    [opts.today]     - Reference date for age checks (injectable
+ *                                     for tests; defaults to new Date()).
+ *
+ * @returns {{
+ *   errors:   Array<{message: string, line: number, column: number, help: string}>,
+ *   warnings: Array<{message: string, line: number, column: number, help: string}>
+ * }}
+ */
+function checkStabilityPromotion(opts) {
+  const { sourceText, fm } = opts;
+  const today = opts.today || new Date();
+  const warnings = [];
+
+  if (!fm || fm.stability !== 'stable') return { errors: [], warnings };
+
+  // Locate the `stability` key in the frontmatter for code-frame anchoring.
+  const keyLine = locateKey(sourceText, 'stability') || { line: 1, column: 1 };
+
+  // ── Criterion 1: eval_state ≠ "unverified" ─────────────────────────────────
+  // eval_state must be "passing" or "monitored" to qualify.
+  const evalState = fm.eval_state || (fm.eval && fm.eval.content_state);
+  if (!evalState || evalState === 'unverified') {
+    warnings.push({
+      message: `stability: stable — criterion 1 unmet: eval_state is "${evalState || 'absent'}" (must be "passing" or "monitored")`,
+      line: keyLine.line,
+      column: keyLine.column,
+      help: 'Run the eval suite, verify results, and set eval_state to "passing" or "monitored". See docs/field-reference.md § eval_state.',
+    });
+  }
+
+  // ── Criterion 2: eval_score ≥ 4.0 ──────────────────────────────────────────
+  // The 0.0–5.0 audit score; absent or below threshold fails.
+  const evalScore = fm.eval_score;
+  if (typeof evalScore !== 'number') {
+    warnings.push({
+      message: `stability: stable — criterion 2 unmet: eval_score is absent (must be ≥ ${STABLE_EVAL_SCORE_THRESHOLD} on the 0.0–5.0 scale)`,
+      line: keyLine.line,
+      column: keyLine.column,
+      help: 'Run `node scripts/skill-audit.js` to produce a graded score and record it in eval_score. See docs/field-reference.md § eval_score.',
+    });
+  } else if (evalScore < STABLE_EVAL_SCORE_THRESHOLD) {
+    warnings.push({
+      message: `stability: stable — criterion 2 unmet: eval_score ${evalScore} < ${STABLE_EVAL_SCORE_THRESHOLD} (80% threshold on the 0.0–5.0 scale)`,
+      line: keyLine.line,
+      column: keyLine.column,
+      help: `Improve the skill until eval_score reaches ${STABLE_EVAL_SCORE_THRESHOLD}. Run \`node scripts/skill-audit.js\` to grade. See docs/field-reference.md § eval_score.`,
+    });
+  }
+
+  // ── Criterion 3: routing_eval: present ─────────────────────────────────────
+  const routingEval = fm.routing_eval || (fm.eval && fm.eval.routing_coverage);
+  if (routingEval !== 'present') {
+    warnings.push({
+      message: `stability: stable — criterion 3 unmet: routing_eval is "${routingEval || 'absent'}" (must be "present")`,
+      line: keyLine.line,
+      column: keyLine.column,
+      help: 'Populate examples[] and anti_examples[], then verify with `node scripts/skill-graph-routing-eval.js`. Set routing_eval to "present" once the harness passes. See docs/field-reference.md § routing_eval.',
+    });
+  }
+
+  // ── Criterion 4: drift_check.last_verified within 90 days ──────────────────
+  const lastVerified = fm.drift_check && fm.drift_check.last_verified;
+  if (!lastVerified) {
+    warnings.push({
+      message: `stability: stable — criterion 4 unmet: drift_check.last_verified is absent (must be within last ${STABLE_DRIFT_MAX_DAYS} days)`,
+      line: keyLine.line,
+      column: keyLine.column,
+      help: `Set a drift baseline and verify: \`node scripts/skill-graph-drift.js --record --apply <skill-path>\`. See docs/field-reference.md § drift_check.`,
+    });
+  } else {
+    const verifiedDate = new Date(lastVerified);
+    if (Number.isNaN(verifiedDate.getTime())) {
+      warnings.push({
+        message: `stability: stable — criterion 4 unmet: drift_check.last_verified "${lastVerified}" is not a valid ISO 8601 date`,
+        line: keyLine.line,
+        column: keyLine.column,
+        help: 'Use ISO 8601 format (YYYY-MM-DD). See docs/field-reference.md § drift_check.',
+      });
+    } else {
+      const daysOld = (today.getTime() - verifiedDate.getTime()) / (24 * 60 * 60 * 1000);
+      if (daysOld > STABLE_DRIFT_MAX_DAYS) {
+        warnings.push({
+          message: `stability: stable — criterion 4 unmet: drift_check.last_verified is ${Math.round(daysOld)} days ago (limit: ${STABLE_DRIFT_MAX_DAYS} days)`,
+          line: keyLine.line,
+          column: keyLine.column,
+          help: `Re-verify against truth sources and update drift_check.last_verified: \`node scripts/skill-graph-drift.js --record --apply <skill-path>\`.`,
+        });
+      }
+    }
+  }
+
+  // ── Criterion 5: grounding.truth_sources populated (codebase/reference) ────
+  // portable-scope skills are exempt — they have no codebase tie-in.
+  const scope = fm.scope;
+  if (GROUNDING_REQUIRED_SCOPES.includes(scope)) {
+    const truthSources =
+      fm.grounding && Array.isArray(fm.grounding.truth_sources)
+        ? fm.grounding.truth_sources
+        : [];
+    if (truthSources.length === 0) {
+      warnings.push({
+        message: `stability: stable — criterion 5 unmet: grounding.truth_sources is absent or empty (required for scope: ${scope})`,
+        line: keyLine.line,
+        column: keyLine.column,
+        help: 'Declare at least one truth source in grounding.truth_sources. See docs/field-reference.md § grounding and docs/skill-metadata-protocol.md § Stability Promotion Criteria.',
+      });
+    }
+  }
+  // portable-scope skills are implicitly exempt (criterion 5 does not apply).
+
+  return { errors: [], warnings };
+}
+
+/**
+ * Locate a YAML key in the frontmatter block and return its { line, column }.
+ * Mirrors the pattern used in check-routing-eval.js.
+ *
+ * @param {string} sourceText - Full file content.
+ * @param {string} key        - YAML key name to locate.
+ * @returns {{ line: number, column: number } | null}
+ */
+function locateKey(sourceText, key) {
+  const lines = sourceText.split('\n');
+  let dashCount = 0;
+  let inside = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      dashCount++;
+      if (dashCount === 1) { inside = true; continue; }
+      if (dashCount === 2) break;
+    }
+    if (!inside) continue;
+    const m = lines[i].match(new RegExp(`^(\\s*)${key}\\s*:`));
+    if (m) return { line: i + 1, column: m[1].length + 1 };
+  }
+  return null;
+}
+
+module.exports = {
+  checkStabilityPromotion,
+  STABLE_EVAL_SCORE_THRESHOLD,
+  STABLE_DRIFT_MAX_DAYS,
+  GROUNDING_REQUIRED_SCOPES,
+};

package/scripts/lint/format-code-frame.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Code-frame formatter for skill-lint error messages.
+ *
+ * Renders a diagnostic in the style popularised by Babel and Rust:
+ *
+ *   skills/a11y/SKILL.md:3:1
+ *
+ *   1 | ---
+ *   2 | schema_version: 2
+ * > 3 | nme: a11y
+ *     | ^ unknown field: nme
+ *   4 | description: "..."
+ *   5 | version: 1.0.0
+ *
+ *   help: Remove or rename 'nme' to a known field. See docs/field-reference.md.
+ *
+ * Zero external dependencies. Uses only Node.js built-ins.
+ *
+ * @module lint/format-code-frame
+ */
+
+'use strict';
+
+// ANSI colour codes. Disabled when noColor === true.
+const COLORS = {
+  red:    '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan:   '\x1b[36m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  reset:  '\x1b[0m',
+};
+
+/**
+ * Return a colour-escaped string, or the plain string if colour is disabled.
+ *
+ * @param {string} text
+ * @param {string} colorCode - Key from the COLORS map.
+ * @param {boolean} noColor  - When true, no ANSI codes are emitted.
+ * @returns {string}
+ */
+function colorize(text, colorCode, noColor) {
+  if (noColor) return text;
+  return `${COLORS[colorCode] || ''}${text}${COLORS.reset}`;
+}
+
+/**
+ * Format a diagnostic message with a code frame.
+ *
+ * @param {object} opts
+ * @param {string}   opts.filePath    - Path to the file, relative to repo root.
+ * @param {number}   opts.line        - 1-based line number of the error.
+ * @param {number}   [opts.column=1]  - 1-based column number of the error.
+ * @param {string}   opts.message     - Short error description (no trailing period needed).
+ * @param {string}   [opts.help]      - Optional help/fix hint shown after the frame.
+ * @param {string}   opts.sourceText  - Full text of the file (used to extract the frame).
+ * @param {'error'|'warn'} [opts.severity='error'] - Controls caret colour.
+ * @param {boolean}  [opts.noColor=false] - Suppress ANSI codes (CI / --no-color).
+ * @param {number}   [opts.context=2]    - Lines of context above and below the target line.
+ * @returns {string} Multi-line formatted diagnostic string.
+ */
+function formatCodeFrame(opts) {
+  const {
+    filePath,
+    line,
+    column = 1,
+    message,
+    help,
+    sourceText,
+    severity = 'error',
+    noColor = false,
+    context = 2,
+  } = opts;
+
+  const lines = sourceText.split('\n');
+  const targetIdx = line - 1; // 0-based
+
+  // Guard against out-of-range line numbers.
+  if (targetIdx < 0 || targetIdx >= lines.length) {
+    return formatSimple({ filePath, line, column, message, help, severity, noColor });
+  }
+
+  const firstLine = Math.max(0, targetIdx - context);
+  const lastLine  = Math.min(lines.length - 1, targetIdx + context);
+
+  // Width of the line-number gutter (right-aligned).
+  const gutterWidth = String(lastLine + 1).length;
+
+  const caretColor = severity === 'warn' ? 'yellow' : 'red';
+  const labelColor = severity === 'warn' ? 'yellow' : 'red';
+  const label      = severity === 'warn' ? 'warn' : 'error';
+
+  // Header: file:line:col
+  const header = colorize(
+    `${filePath}:${line}:${column}`,
+    'cyan',
+    noColor
+  );
+
+  // Severity prefix
+  const severityLabel = colorize(`[${label}]`, labelColor, noColor);
+
+  const frameLines = [];
+
+  for (let i = firstLine; i <= lastLine; i++) {
+    const lineNum   = i + 1;
+    const gutter    = String(lineNum).padStart(gutterWidth);
+    const isTarget  = i === targetIdx;
+    const indicator = isTarget ? colorize('>', 'bold', noColor) : ' ';
+    const gutterStr = colorize(`${gutter} |`, 'dim', noColor);
+
+    if (isTarget) {
+      frameLines.push(`${indicator} ${gutterStr} ${lines[i]}`);
+      // Caret line
+      const caretPad = ' '.repeat(gutterWidth + 4 + (column - 1));
+      const caret    = colorize('^', caretColor, noColor);
+      const caretMsg = colorize(message, caretColor, noColor);
+      frameLines.push(`${caretPad}${caret} ${caretMsg}`);
+    } else {
+      frameLines.push(`  ${gutterStr} ${lines[i]}`);
+    }
+  }
+
+  const parts = [
+    '',
+    `${severityLabel} ${header}`,
+    '',
+    ...frameLines,
+    '',
+  ];
+
+  if (help) {
+    parts.push(colorize(`  help: ${help}`, 'dim', noColor));
+    parts.push('');
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Fallback when line number is out of range — plain file:line:col + message.
+ * @private
+ */
+function formatSimple({ filePath, line, column, message, help, severity, noColor }) {
+  const labelColor = severity === 'warn' ? 'yellow' : 'red';
+  const label      = severity === 'warn' ? 'warn' : 'error';
+  const parts = [
+    `${colorize(`[${label}]`, labelColor, noColor)} ${colorize(`${filePath}:${line}:${column}`, 'cyan', noColor)} ${message}`,
+  ];
+  if (help) parts.push(colorize(`  help: ${help}`, 'dim', noColor));
+  return parts.join('\n');
+}
+
+/**
+ * Locate the line and column of the first occurrence of a YAML key in the
+ * frontmatter block of a SKILL.md file.
+ *
+ * Returns { line: 1-based, column: 1-based } or { line: 1, column: 1 } as a
+ * fallback if the key is not found.
+ *
+ * @param {string} sourceText - Full file text.
+ * @param {string} key        - YAML key to find (exact match, at the start of a line after optional spaces).
+ * @returns {{ line: number, column: number }}
+ */
+function locateYamlKey(sourceText, key) {
+  const lines = sourceText.split('\n');
+  const pattern = new RegExp(`^(\\s*)${escapeRegex(key)}\\s*:`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = pattern.exec(lines[i]);
+    if (m) {
+      return { line: i + 1, column: m[1].length + 1 };
+    }
+  }
+  return { line: 1, column: 1 };
+}
+
+/**
+ * Locate the line and column of the first occurrence of an H2 section header
+ * in the body of a SKILL.md file.
+ *
+ * @param {string} sourceText - Full file text.
+ * @param {string} heading    - Heading text without '## ' prefix (e.g. 'Verification').
+ * @returns {{ line: number, column: number }}
+ */
+function locateH2Section(sourceText, heading) {
+  const lines = sourceText.split('\n');
+  const target = `## ${heading}`;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimEnd() === target) {
+      return { line: i + 1, column: 1 };
+    }
+  }
+  return { line: 1, column: 1 };
+}
+
+/**
+ * Escape special regex characters in a string.
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = { formatCodeFrame, locateYamlKey, locateH2Section };

package/scripts/marketplace-install.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * marketplace-install.js — Install a skill from the Skill Graph marketplace.
+ *
+ * Fetches a skill from a remote registry (GitHub or npm) and writes it into
+ * the local skill library. This is a minimal stub — the full implementation
+ * will follow in SH-6110.
+ *
+ * Usage:
+ *   node scripts/marketplace-install.js <slug>
+ *   node scripts/marketplace-install.js <slug> --source <registry-url>
+ *   node scripts/marketplace-install.js --list
+ *   node scripts/marketplace-install.js --help
+ *
+ * Flags:
+ *   --source <url>   Override the default registry URL.
+ *   --list           List skills available in the default registry.
+ *   --dry-run        Show what would be installed without writing anything.
+ *   --force          Overwrite if the skill already exists locally.
+ *   --output <dir>   Override the local output directory (default: skills/).
+ */
+
+'use strict';
+
+const DEFAULT_REGISTRY = 'https://raw.githubusercontent.com/jacob-balslev/skills/main/skills';
+
+function printHelp() {
+  process.stdout.write(`Usage: skill-graph add <slug> [options]
+
+Install a skill from the marketplace into your local skill library.
+
+Arguments:
+  <slug>           Skill slug to install (e.g. "debugging", "code-review")
+
+Options:
+  --source <url>   Registry URL (default: ${DEFAULT_REGISTRY})
+  --dry-run        Show what would be installed without writing files
+  --force          Overwrite an existing local skill
+  --output <dir>   Local directory to install into (default: skills/)
+  --list           List skills available in the registry
+  --help           Show this help
+
+Examples:
+  skill-graph add debugging
+  skill-graph add code-review --dry-run
+  skill-graph add a11y --force --output ./my-skills
+  skill-graph add --list
+`);
+}
+
+async function listSkills(registryUrl) {
+  process.stdout.write(`Listing skills from: ${registryUrl}\n`);
+  process.stdout.write(`\nThis feature requires the full SH-6110 implementation.\n`);
+  process.stdout.write(`For now, browse available skills at:\n`);
+  process.stdout.write(`  https://github.com/jacob-balslev/skills/tree/main/skills\n`);
+}
+
+async function installSkill(slug, opts) {
+  if (!slug) {
+    process.stderr.write('Error: missing required argument <slug>\n\n');
+    printHelp();
+    process.exit(1);
+  }
+
+  const registryUrl = opts.source || DEFAULT_REGISTRY;
+  const skillUrl = `${registryUrl}/${slug}/SKILL.md`;
+
+  process.stdout.write(`Installing skill: ${slug}\n`);
+  process.stdout.write(`Registry: ${registryUrl}\n`);
+  process.stdout.write(`Source: ${skillUrl}\n\n`);
+
+  if (opts['dry-run']) {
+    process.stdout.write(`[dry-run] Would fetch: ${skillUrl}\n`);
+    process.stdout.write(`[dry-run] Would write: ${opts.output || 'skills'}/${slug}/SKILL.md\n`);
+    return;
+  }
+
+  // Full implementation follows in SH-6110 (install verification).
+  // For now, direct users to the canonical install method.
+  process.stderr.write(`Full marketplace install is not yet implemented.\n`);
+  process.stderr.write(`\nTo install skills manually:\n`);
+  process.stderr.write(`  1. Visit: ${skillUrl}\n`);
+  process.stderr.write(`  2. Copy the file to: ${opts.output || 'skills'}/${slug}/SKILL.md\n`);
+  process.stderr.write(`\nFull install support is tracked in SH-6110.\n`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const opts = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') { opts.help = true; }
+    else if (arg === '--dry-run') { opts['dry-run'] = true; }
+    else if (arg === '--force') { opts.force = true; }
+    else if (arg === '--list') { opts.list = true; }
+    else if (arg === '--source' && argv[i + 1]) { opts.source = argv[++i]; }
+    else if (arg === '--output' && argv[i + 1]) { opts.output = argv[++i]; }
+    else if (!arg.startsWith('--')) { positional.push(arg); }
+  }
+  opts._positional = positional;
+  return opts;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (args.list) {
+    await listSkills(args.source || DEFAULT_REGISTRY);
+    process.exit(0);
+  }
+
+  const slug = args._positional[0];
+  await installSkill(slug, args);
+}
+
+main().catch(err => {
+  process.stderr.write(`Error: ${err.message}\n`);
+  process.exit(1);
+});