sdtk-wiki-kit 0.1.0

package/src/lib/wiki-premium-loader.js

@@ -0,0 +1,364 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const SAFE_PACK_PART_RE = /^[A-Za-z0-9._-]+$/;
+const REQUIRED_ENTITLEMENT_FIELDS = [
+  "schema_version",
+  "customer_id",
+  "plan",
+  "products",
+  "capabilities",
+  "issued_at",
+  "expires_at",
+  "offline_grace_until",
+];
+const REQUIRED_PACK_FIELDS = [
+  "id",
+  "product",
+  "version",
+  "capabilities",
+  "source",
+  "sha256",
+];
+
+function isSafePackPathPart(value) {
+  return (
+    typeof value === "string" &&
+    SAFE_PACK_PART_RE.test(value) &&
+    value !== "." &&
+    value !== ".."
+  );
+}
+
+function getSuiteRoot() {
+  return path.join(os.homedir(), ".sdtk");
+}
+
+function getEntitlementsFile() {
+  return path.join(getSuiteRoot(), "entitlements.json");
+}
+
+function getPacksRoot() {
+  return path.join(getSuiteRoot(), "packs");
+}
+
+function resolvePublicKey() {
+  if (process.env.SDTK_ENTITLEMENT_PUBLIC_KEY) {
+    return process.env.SDTK_ENTITLEMENT_PUBLIC_KEY;
+  }
+
+  const bundledKeyPath = path.join(
+    __dirname,
+    "..",
+    "..",
+    "assets",
+    "keys",
+    "sdtk-entitlement-public.pem"
+  );
+  if (fs.existsSync(bundledKeyPath)) {
+    return fs.readFileSync(bundledKeyPath, "utf8");
+  }
+  return null;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = canonicalize(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function buildCanonicalPayload(manifest) {
+  const { signature: _signature, ...rest } = manifest;
+  return Buffer.from(JSON.stringify(canonicalize(rest)), "utf8");
+}
+
+function evaluateManifestObject(manifest, nowMs) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return { state: "malformed", manifest: null };
+  }
+
+  for (const field of REQUIRED_ENTITLEMENT_FIELDS) {
+    if (!(field in manifest)) {
+      return { state: "malformed", manifest };
+    }
+  }
+
+  if (typeof manifest.schema_version !== "number") {
+    return { state: "malformed", manifest };
+  }
+  if (typeof manifest.customer_id !== "string" || !manifest.customer_id) {
+    return { state: "malformed", manifest };
+  }
+  if (typeof manifest.plan !== "string" || !manifest.plan) {
+    return { state: "malformed", manifest };
+  }
+  if (
+    !manifest.products ||
+    typeof manifest.products !== "object" ||
+    Array.isArray(manifest.products)
+  ) {
+    return { state: "malformed", manifest };
+  }
+  if (!Array.isArray(manifest.capabilities)) {
+    return { state: "malformed", manifest };
+  }
+  if (
+    typeof manifest.issued_at !== "string" ||
+    typeof manifest.expires_at !== "string" ||
+    typeof manifest.offline_grace_until !== "string"
+  ) {
+    return { state: "malformed", manifest };
+  }
+  if (
+    !("signature" in manifest) ||
+    !manifest.signature ||
+    typeof manifest.signature !== "string"
+  ) {
+    return { state: "unsigned", manifest };
+  }
+
+  const publicKeyPem = resolvePublicKey();
+  if (!publicKeyPem) {
+    return { state: "untrusted-key", manifest };
+  }
+
+  let verified = false;
+  try {
+    const verifier = crypto.createVerify("RSA-SHA256");
+    verifier.update(buildCanonicalPayload(manifest));
+    verified = verifier.verify(publicKeyPem, Buffer.from(manifest.signature, "base64"));
+  } catch (_err) {
+    return { state: "invalid-signature", manifest };
+  }
+
+  if (!verified) {
+    return { state: "invalid-signature", manifest };
+  }
+
+  const now = nowMs !== undefined ? nowMs : Date.now();
+  const expiresAt = new Date(manifest.expires_at).getTime();
+  const graceUntil = new Date(manifest.offline_grace_until).getTime();
+  if (Number.isNaN(expiresAt) || Number.isNaN(graceUntil)) {
+    return { state: "malformed", manifest };
+  }
+  if (now < expiresAt) {
+    return { state: "active", manifest };
+  }
+  if (now < graceUntil) {
+    return { state: "grace", manifest };
+  }
+  return { state: "expired", manifest };
+}
+
+function loadEntitlementState() {
+  const filePath = getEntitlementsFile();
+  if (!fs.existsSync(filePath)) {
+    return { state: "missing", manifest: null };
+  }
+  try {
+    return evaluateManifestObject(JSON.parse(fs.readFileSync(filePath, "utf8")));
+  } catch (_err) {
+    return { state: "malformed", manifest: null };
+  }
+}
+
+function checkCapability(capability, entitlementState) {
+  const state = entitlementState && entitlementState.state;
+  const manifest = entitlementState && entitlementState.manifest;
+
+  if (state === "active" || state === "grace") {
+    const capabilities = manifest && Array.isArray(manifest.capabilities)
+      ? manifest.capabilities
+      : [];
+    if (capabilities.includes(capability)) {
+      return { allowed: true };
+    }
+    return {
+      allowed: false,
+      exitCode: 1,
+      reason: `Capability "${capability}" is not included in the local entitlement.`,
+    };
+  }
+
+  const integrityStates = new Set(["malformed", "unsigned", "untrusted-key", "invalid-signature"]);
+  return {
+    allowed: false,
+    exitCode: integrityStates.has(state) ? 3 : 1,
+    reason: `Capability "${capability}" is blocked because local entitlement state is "${state || "missing"}".`,
+  };
+}
+
+function computeSha256(bytes) {
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+function validatePackMeta(meta) {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+    return { valid: false, reason: "pack metadata is not an object" };
+  }
+
+  for (const field of REQUIRED_PACK_FIELDS) {
+    if (!(field in meta)) {
+      return { valid: false, reason: `missing required field: ${field}` };
+    }
+  }
+
+  if (!isSafePackPathPart(meta.id)) {
+    return { valid: false, reason: "id must be a safe identifier" };
+  }
+  if (!isSafePackPathPart(meta.product)) {
+    return { valid: false, reason: "product must be a safe identifier" };
+  }
+  if (!isSafePackPathPart(meta.version)) {
+    return { valid: false, reason: "version must be a safe identifier" };
+  }
+  if (!Array.isArray(meta.capabilities)) {
+    return { valid: false, reason: "capabilities must be an array" };
+  }
+  if (
+    !meta.source ||
+    typeof meta.source !== "object" ||
+    Array.isArray(meta.source) ||
+    meta.source.type !== "github-content" ||
+    typeof meta.source.path !== "string" ||
+    !meta.source.path
+  ) {
+    return { valid: false, reason: 'source.type must be "github-content" with a path' };
+  }
+  if (typeof meta.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(meta.sha256)) {
+    return { valid: false, reason: "sha256 must be a 64-character lowercase hex string" };
+  }
+  return { valid: true };
+}
+
+function getPackDir(packEntry) {
+  return path.join(getPacksRoot(), packEntry.product, packEntry.id, packEntry.version);
+}
+
+function getPackFile(packEntry) {
+  return path.join(getPackDir(packEntry), "pack.js");
+}
+
+function resolvePackState(packEntry) {
+  const validation = validatePackMeta(packEntry);
+  if (!validation.valid) {
+    return { state: "malformed", reason: validation.reason };
+  }
+
+  const packFile = getPackFile(packEntry);
+  const metaFile = path.join(getPackDir(packEntry), "pack.json");
+  if (!fs.existsSync(packFile) || !fs.existsSync(metaFile)) {
+    return {
+      state: "missing",
+      reason:
+        `Premium pack "${packEntry.id}@${packEntry.version}" is not installed for capability wiki.ask.`,
+    };
+  }
+
+  let cachedMeta;
+  try {
+    cachedMeta = JSON.parse(fs.readFileSync(metaFile, "utf8"));
+  } catch (_err) {
+    return { state: "malformed", reason: "pack.json could not be parsed" };
+  }
+
+  if (!cachedMeta || cachedMeta.sha256 !== packEntry.sha256) {
+    return { state: "stale", reason: "pack.json hash does not match signed manifest" };
+  }
+
+  let bytes;
+  try {
+    bytes = fs.readFileSync(packFile);
+  } catch (err) {
+    return { state: "malformed", reason: `pack.js could not be read: ${err.message}` };
+  }
+  if (computeSha256(bytes) !== packEntry.sha256) {
+    return { state: "stale", reason: "pack.js hash does not match signed manifest" };
+  }
+  return { state: "present" };
+}
+
+async function loadWikiAskHandler() {
+  const capability = "wiki.ask";
+  const entitlementState = loadEntitlementState();
+  const capabilityCheck = checkCapability(capability, entitlementState);
+  if (!capabilityCheck.allowed) {
+    return {
+      ok: false,
+      exitCode: capabilityCheck.exitCode,
+      message:
+        `${capabilityCheck.reason} Run SDTK activation or entitlement sync to install ` +
+        `the ${capability} premium runtime.`,
+    };
+  }
+
+  const manifest = entitlementState.manifest;
+  const packs = Array.isArray(manifest.premium_packs) ? manifest.premium_packs : [];
+  const packEntry = packs.find(
+    (pack) => Array.isArray(pack.capabilities) && pack.capabilities.includes(capability)
+  );
+  if (!packEntry) {
+    return {
+      ok: false,
+      exitCode: 1,
+      message:
+        `Premium pack providing "${capability}" is not available. Run SDTK activation ` +
+        `or entitlement sync to install the SDTK-WIKI Ask runtime.`,
+    };
+  }
+
+  const packState = resolvePackState(packEntry);
+  if (packState.state !== "present") {
+    return {
+      ok: false,
+      exitCode: packState.state === "malformed" ? 3 : 1,
+      message:
+        `Premium pack for "${capability}" is not ready (${packState.state}). ` +
+        (packState.reason || "Refresh the local entitlement/runtime cache."),
+    };
+  }
+
+  let packModule;
+  try {
+    packModule = require(getPackFile(packEntry));
+  } catch (err) {
+    return {
+      ok: false,
+      exitCode: 4,
+      message: `Failed to load SDTK-WIKI Ask runtime pack: ${err.message}`,
+    };
+  }
+
+  const handler = typeof packModule.wikiAsk === "function" ? packModule.wikiAsk : packModule.run;
+  if (typeof handler !== "function") {
+    return {
+      ok: false,
+      exitCode: 3,
+      message: 'SDTK-WIKI Ask runtime pack must export "wikiAsk" or "run".',
+    };
+  }
+
+  return { ok: true, handler, packEntry };
+}
+
+module.exports = {
+  buildCanonicalPayload,
+  canonicalize,
+  checkCapability,
+  evaluateManifestObject,
+  loadEntitlementState,
+  loadWikiAskHandler,
+  resolvePackState,
+};

package/src/lib/wiki-prune.js

@@ -0,0 +1,334 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { CliError, ValidationError } = require("./errors");
+const { parseFrontmatter } = require("./wiki-lint");
+const {
+  assertWikiWorkspaceWritePath,
+  getWikiGraphPath,
+  getWikiPagesPath,
+  getWikiProvenancePath,
+  getWikiProvenanceSourcesPath,
+  getWikiRawSourcesPath,
+  getWikiReportsPath,
+  getWikiWorkspacePath,
+  resolveProjectPath,
+} = require("./wiki-paths");
+
+const REPORT_PREFIX = "prune-dry-run-report";
+
+function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function todayStamp(date = new Date()) {
+  return date.toISOString().slice(0, 10);
+}
+
+function readJsonIfPresent(filePath, fallback = null) {
+  if (!fs.existsSync(filePath)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (error) {
+    return { __error: `Could not parse JSON at ${filePath}: ${error.message}` };
+  }
+}
+
+function listMarkdownPages(rootPath) {
+  if (!fs.existsSync(rootPath)) return [];
+  const results = [];
+  const stack = [rootPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(entryPath);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+        results.push(entryPath);
+      }
+    }
+  }
+  return results.sort((a, b) => a.localeCompare(b));
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function collectGraphDegree(graphPath) {
+  const graph = readJsonIfPresent(path.join(graphPath, "SDTK_DOC_GRAPH.json"), {});
+  const degree = new Map();
+  for (const node of asArray(graph.nodes)) {
+    if (node && node.id) degree.set(String(node.id), 0);
+  }
+  for (const edge of asArray(graph.edges)) {
+    if (!edge) continue;
+    const source = edge.source ? String(edge.source) : "";
+    const target = edge.target ? String(edge.target) : "";
+    if (source) degree.set(source, (degree.get(source) || 0) + 1);
+    if (target) degree.set(target, (degree.get(target) || 0) + 1);
+  }
+  return degree;
+}
+
+function indexActiveProvenance(projectPath) {
+  const data = readJsonIfPresent(getWikiProvenanceSourcesPath(projectPath), { sources: [] });
+  const sources = new Map();
+  for (const record of asArray(data.sources)) {
+    if (!record || !record.sourcePath) continue;
+    sources.set(toPosix(record.sourcePath), record);
+  }
+  return sources;
+}
+
+function collectRemovedSources(projectPath) {
+  const data = readJsonIfPresent(path.join(getWikiProvenancePath(projectPath), "changes.json"), {});
+  return new Set(asArray(data.removed).map(toPosix));
+}
+
+function indexRawSources(projectPath) {
+  const rawPath = getWikiRawSourcesPath(projectPath);
+  if (!fs.existsSync(rawPath)) {
+    return null;
+  }
+  const data = readJsonIfPresent(rawPath, { sources: [] });
+  const sources = new Map();
+  for (const record of asArray(data.sources)) {
+    if (!record || !record.sourcePath) continue;
+    sources.set(toPosix(record.sourcePath), record);
+  }
+  return sources;
+}
+
+function addSignal(signals, source, code, detail = "") {
+  signals.push({ source, code, detail });
+}
+
+function classifySignals(signals) {
+  const sources = new Set(signals.map((signal) => signal.source));
+  const hasBuildRemoved = signals.some((signal) => signal.code === "removed_source_from_build_provenance");
+  const hasRawInactive = signals.some((signal) => signal.source === "raw_registry");
+
+  if (sources.size >= 2 && (hasBuildRemoved || hasRawInactive)) {
+    return "strong_candidate";
+  }
+  if (hasBuildRemoved || hasRawInactive) {
+    return "candidate";
+  }
+  return "weak_signal";
+}
+
+function analyzePage({ filePath, pagesPath, projectPath, activeSources, removedSources, rawSources, graphDegree }) {
+  const text = fs.readFileSync(filePath, "utf-8");
+  const parsed = parseFrontmatter(text);
+  const fields = parsed.fields || {};
+  const relPagePath = toPosix(path.relative(projectPath, filePath));
+  const relToPages = toPosix(path.relative(pagesPath, filePath));
+  if (relToPages === "_index.md") {
+    return null;
+  }
+
+  const sourcePath = toPosix(fields.source_path || "");
+  const sourceHash = fields.source_hash || "";
+  const signals = [];
+
+  if (sourcePath && removedSources.has(sourcePath)) {
+    addSignal(signals, "build_provenance", "removed_source_from_build_provenance", sourcePath);
+  }
+
+  if (sourcePath) {
+    const activeRecord = activeSources.get(sourcePath);
+    if (!activeRecord) {
+      addSignal(signals, "active_provenance", "source_missing_from_active_provenance", sourcePath);
+    } else if (sourceHash && activeRecord.sourceHash && sourceHash !== activeRecord.sourceHash) {
+      addSignal(signals, "active_provenance", "source_hash_differs_from_active_provenance", sourcePath);
+    }
+  } else {
+    addSignal(signals, "page_frontmatter", "missing_source_path", relPagePath);
+  }
+
+  if (rawSources && sourcePath) {
+    const rawRecord = rawSources.get(sourcePath);
+    if (!rawRecord) {
+      addSignal(signals, "raw_registry", "raw_registry_binding_missing", sourcePath);
+    } else if (rawRecord.status && !["active", "ingested"].includes(String(rawRecord.status))) {
+      addSignal(signals, "raw_registry", `raw_registry_status_${rawRecord.status}`, sourcePath);
+    }
+  }
+
+  const relatedPages = Array.isArray(fields.related_pages) ? fields.related_pages : [];
+  if (sourcePath && (graphDegree.get(sourcePath) || 0) === 0 && relatedPages.length === 0) {
+    addSignal(signals, "lint_signal", "no_downstream_integration_signal", sourcePath);
+  }
+
+  const wordCount = String(parsed.body || "").split(/\s+/).filter(Boolean).length;
+  if (wordCount > 0 && wordCount < 25) {
+    addSignal(signals, "lint_signal", "thin_page_signal", `${wordCount} words`);
+  }
+
+  if (signals.length === 0) {
+    return null;
+  }
+
+  return {
+    pagePath: relPagePath,
+    pageId: fields.page_id || "",
+    title: fields.title || path.basename(filePath, ".md"),
+    sourcePath,
+    evidenceTier: classifySignals(signals),
+    safetyTier: "never_delete_automatically",
+    reasonCodes: signals.map((signal) => signal.code),
+    evidenceSources: Array.from(new Set(signals.map((signal) => signal.source))).sort(),
+    signals,
+  };
+}
+
+function tierSummary(findings) {
+  return findings.reduce(
+    (counts, finding) => {
+      counts[finding.evidenceTier] = (counts[finding.evidenceTier] || 0) + 1;
+      return counts;
+    },
+    { weak_signal: 0, candidate: 0, strong_candidate: 0 }
+  );
+}
+
+function recommendationForTier(tier) {
+  if (tier === "strong_candidate") {
+    return "Future explicit cleanup review only; do not delete automatically.";
+  }
+  if (tier === "candidate") {
+    return "Investigate as a stale candidate; not deletion proof.";
+  }
+  return "Investigate weak signal only.";
+}
+
+function renderReport({ projectPath, workspacePath, pagesScanned, findings, generatedAt }) {
+  const summary = tierSummary(findings);
+  const lines = [
+    "# SDTK-WIKI Prune Dry-Run Report",
+    "",
+    `Generated: ${generatedAt}`,
+    `Project path: ${projectPath}`,
+    `Workspace path: ${workspacePath}`,
+    `Pages scanned: ${pagesScanned}`,
+    `Findings: ${findings.length}`,
+    "",
+    "Report-only and non-destructive: no wiki pages were deleted or archived.",
+    "Safety posture: `never_delete_automatically` applies to every finding.",
+    "",
+    "## Evidence Tier Summary",
+    "",
+    "| Tier | Count | Meaning |",
+    "|---|---:|---|",
+    `| weak_signal | ${summary.weak_signal} | Investigate only. |`,
+    `| candidate | ${summary.candidate} | Candidate for investigation; not deletion proof. |`,
+    `| strong_candidate | ${summary.strong_candidate} | Future explicit cleanup review only. |`,
+    "| never_delete_automatically | all | No automatic delete/archive. |",
+    "",
+    "## Findings",
+    "",
+  ];
+
+  if (findings.length === 0) {
+    lines.push("No prune candidates were found.");
+  } else {
+    findings.forEach((finding, index) => {
+      lines.push(`### ${index + 1}. ${finding.pagePath}`);
+      lines.push("");
+      lines.push(`- Page ID: ${finding.pageId || "(missing)"}`);
+      lines.push(`- Title: ${finding.title || "(missing)"}`);
+      lines.push(`- Source path: ${finding.sourcePath || "(missing)"}`);
+      lines.push(`- Evidence tier: \`${finding.evidenceTier}\``);
+      lines.push("- Safety tier: `never_delete_automatically`");
+      lines.push(`- Recommendation: ${recommendationForTier(finding.evidenceTier)}`);
+      lines.push(`- Evidence sources: ${finding.evidenceSources.map((source) => `\`${source}\``).join(", ")}`);
+      lines.push(`- Reason codes: ${finding.reasonCodes.map((code) => `\`${code}\``).join(", ")}`);
+      lines.push("");
+    });
+  }
+
+  lines.push("");
+  lines.push("## Deferred Actions");
+  lines.push("");
+  lines.push("Delete, archive, apply, discover, compile, query-history, and Ask changes are outside BK-124.");
+  lines.push("");
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function ensureExistingWorkspace(projectPath) {
+  const workspacePath = getWikiWorkspacePath(projectPath);
+  if (!fs.existsSync(workspacePath) || !fs.statSync(workspacePath).isDirectory()) {
+    throw new ValidationError(
+      `No SDTK-WIKI workspace found at ${workspacePath}. Run "sdtk-wiki init" or "sdtk-wiki atlas build" first. No project files were changed.`
+    );
+  }
+  return workspacePath;
+}
+
+function runWikiPruneDryRun({ projectPath }) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}`);
+  }
+
+  try {
+    const workspacePath = ensureExistingWorkspace(resolvedProjectPath);
+    const pagesPath = getWikiPagesPath(resolvedProjectPath);
+    const reportsPath = getWikiReportsPath(resolvedProjectPath);
+    assertWikiWorkspaceWritePath(reportsPath, resolvedProjectPath);
+
+    const pages = listMarkdownPages(pagesPath);
+    const activeSources = indexActiveProvenance(resolvedProjectPath);
+    const removedSources = collectRemovedSources(resolvedProjectPath);
+    const rawSources = indexRawSources(resolvedProjectPath);
+    const graphDegree = collectGraphDegree(getWikiGraphPath(resolvedProjectPath));
+    const findings = pages
+      .map((filePath) =>
+        analyzePage({
+          filePath,
+          pagesPath,
+          projectPath: resolvedProjectPath,
+          activeSources,
+          removedSources,
+          rawSources,
+          graphDegree,
+        })
+      )
+      .filter(Boolean);
+
+    const generatedAt = new Date().toISOString();
+    const reportPath = path.join(reportsPath, `${REPORT_PREFIX}-${todayStamp(new Date(generatedAt))}.md`);
+    assertWikiWorkspaceWritePath(reportPath, resolvedProjectPath);
+    fs.mkdirSync(reportsPath, { recursive: true });
+    fs.writeFileSync(
+      reportPath,
+      renderReport({
+        projectPath: resolvedProjectPath,
+        workspacePath,
+        pagesScanned: pages.filter((filePath) => path.basename(filePath) !== "_index.md").length,
+        findings,
+        generatedAt,
+      }),
+      "utf-8"
+    );
+
+    return {
+      reportPath,
+      pagesScanned: pages.filter((filePath) => path.basename(filePath) !== "_index.md").length,
+      findings,
+      summary: tierSummary(findings),
+    };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError(`Failed to write SDTK-WIKI prune dry-run report: ${error.message}`);
+  }
+}
+
+module.exports = {
+  REPORT_PREFIX,
+  renderReport,
+  runWikiPruneDryRun,
+};