ktg-plugin-marketplace/scripts/okf-check.mjs

#!/usr/bin/env node
// okf-check.mjs — shared OKF-compatible second-brain conformance checker.
//
// The single cross-plugin acceptance gate for the convention in
// docs/okf-second-brain/spec.md. Validates one bundle root against the minimal
// contract (spec §3):
//   - every concept file (.md except index.md) MUST carry `type:` in frontmatter;
//     >= 1 file without type -> exit 1, count + names the files; 0 -> exit 0.
//   - recommended fields (resource/title/description/timestamp) -> WARNING, not error.
//   - the bundle-root index.md's `okf_version` is echoed for human comparison
//     (no auto-fetch — offline by design).
//
// Provenance: lifted from okr/scripts/okf-check.mjs (the de-facto reference
// implementation; spec §7) at c06e4d7 (2026-06-29), with English output + a vendored
// frontmatter reader so the catalog copy is self-contained. okr has since hardened its
// checker (skip innboks/dot-dirs + scoped checkBundle @ 3b45be7; BOM/CRLF normalization
// @ 482effb); this copy has NOT, so it has DIVERGED and is not verdict-identical with
// okr's current checker. Parity is a gate's output over a corpus, not a claim in this
// header — see docs/okf-second-brain/log.md. Run per bundle root.
// Zero npm dependencies (node: builtins).

import { readdirSync, readFileSync, existsSync } from 'node:fs';
import { join, relative } from 'node:path';
import { fileURLToPath } from 'node:url';
import { parseFrontmatter } from './okf-frontmatter.mjs';

const RECOMMENDED = ['resource', 'title', 'description', 'timestamp'];

// All concept files (.md except index.md) under root, recursively.
function walkConcepts(root) {
  const out = [];
  const walk = (dir) => {
    for (const e of readdirSync(dir, { withFileTypes: true })) {
      const p = join(dir, e.name);
      if (e.isDirectory()) walk(p);
      else if (e.isFile() && e.name.endsWith('.md') && e.name !== 'index.md') out.push(p);
    }
  };
  walk(root);
  return out;
}

// Read the root's okf_version (markdown text in index.md, not frontmatter). null if absent.
function rootOkfVersion(root) {
  const idx = join(root, 'index.md');
  if (!existsSync(idx)) return null;
  const m = readFileSync(idx, 'utf8').match(/^okf_version:\s*(.+)$/m);
  return m ? m[1].trim() : null;
}

export function checkBundle(root) {
  const concepts = walkConcepts(root);
  const missingType = [];
  const warnings = [];
  for (const f of concepts) {
    const { get } = parseFrontmatter(readFileSync(f, 'utf8'));
    const rel = relative(root, f);
    if (!get('type')) {
      missingType.push(rel);
      continue;
    }
    for (const field of RECOMMENDED) {
      if (!get(field)) warnings.push(`${rel}: missing recommended field "${field}"`);
    }
  }
  return {
    scanned: concepts.length,
    missingType,
    warnings,
    okfVersion: rootOkfVersion(root),
  };
}

// --- CLI ---
const isMain = process.argv[1]
  && fileURLToPath(import.meta.url) === process.argv[1];
if (isMain) {
  const root = process.argv[2];
  if (!root) {
    process.stderr.write('Usage: node okf-check.mjs <bundle-root>\n');
    process.exit(2);
  }
  if (!existsSync(root)) {
    process.stderr.write(`Bundle root does not exist: ${root}\n`);
    process.exit(2);
  }
  const r = checkBundle(root);
  const out = [];
  out.push(`OKF check: ${root}`);
  out.push(`  Concept files scanned: ${r.scanned}`);
  out.push(`  ${r.missingType.length} files without type:`);
  for (const f of r.missingType) out.push(`    - ${f}`);
  out.push(`  okf_version: ${r.okfVersion || 'MISSING (root index without okf_version)'}`);
  out.push(`  Warnings (recommended fields): ${r.warnings.length}`);
  for (const w of r.warnings) out.push(`    ! ${w}`);
  out.push(r.missingType.length === 0 ? 'OK: valid OKF bundle' : `FAIL: ${r.missingType.length} file(s) missing type:`);
  process.stdout.write(`${out.join('\n')}\n`);
  process.exit(r.missingType.length === 0 ? 0 : 1);
}