sdtk-wiki-kit 0.1.0

package/src/lib/wiki-ask.js

@@ -0,0 +1,175 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { CliError } = require("./errors");
+const { getWikiGraphPath, resolveProjectPath } = require("./wiki-paths");
+const { loadWikiAskHandler } = require("./wiki-premium-loader");
+
+const INDEX_FILE = "SDTK_DOC_INDEX.json";
+const GRAPH_FILE = "SDTK_DOC_GRAPH.json";
+const DEFAULT_MAX_SOURCES = 6;
+
+function readJsonFile(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (err) {
+    throw new CliError(`${label} could not be read from ${filePath}: ${err.message}`, 3);
+  }
+}
+
+function assertWikiGraphReady(projectPath) {
+  const graphPath = getWikiGraphPath(projectPath);
+  const indexPath = path.join(graphPath, INDEX_FILE);
+  const graphFilePath = path.join(graphPath, GRAPH_FILE);
+
+  if (!fs.existsSync(graphPath) || !fs.statSync(graphPath).isDirectory()) {
+    throw new CliError(
+      `SDTK-WIKI Ask requires a built wiki graph at .sdtk/wiki/graph. ` +
+        `Run "sdtk-wiki atlas build" before running "sdtk-wiki ask".`,
+      1
+    );
+  }
+  if (!fs.existsSync(indexPath) || !fs.existsSync(graphFilePath)) {
+    throw new CliError(
+      `SDTK-WIKI Ask requires ${INDEX_FILE} and ${GRAPH_FILE} under .sdtk/wiki/graph. ` +
+        `Run "sdtk-wiki atlas build" to rebuild the graph.`,
+      1
+    );
+  }
+
+  return { graphPath, indexPath, graphFilePath };
+}
+
+function extractDocumentPath(document) {
+  return (
+    document.path ||
+    document.sourcePath ||
+    document.relativePath ||
+    document.id ||
+    document.title ||
+    "unknown"
+  );
+}
+
+function extractDocumentText(document) {
+  const candidates = [
+    document.body_markdown,
+    document.markdown,
+    document.content,
+    document.summary,
+    document.excerpt,
+    document.text,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate;
+    }
+  }
+  return "";
+}
+
+function buildSources(index, sourceFilters, maxSources) {
+  const documents = Array.isArray(index.documents) ? index.documents : [];
+  const filters = (sourceFilters || []).map((item) => item.trim()).filter(Boolean);
+  const limit = Number.isInteger(maxSources) && maxSources > 0 ? maxSources : DEFAULT_MAX_SOURCES;
+
+  return documents
+    .map((document) => {
+      const sourcePath = extractDocumentPath(document);
+      return {
+        id: document.id || sourcePath,
+        path: sourcePath,
+        title: document.title || sourcePath,
+        text: extractDocumentText(document),
+      };
+    })
+    .filter((source) => {
+      if (filters.length === 0) {
+        return true;
+      }
+      return filters.some((filter) => source.id === filter || source.path === filter);
+    })
+    .slice(0, limit);
+}
+
+function normalizeCitations(citations) {
+  if (!Array.isArray(citations)) {
+    return [];
+  }
+  return citations
+    .map((citation) => {
+      if (typeof citation === "string") {
+        return citation;
+      }
+      if (citation && typeof citation === "object") {
+        return citation.path || citation.sourcePath || citation.id || citation.title || "";
+      }
+      return "";
+    })
+    .filter(Boolean);
+}
+
+function normalizeAskResult(rawResult, context) {
+  const result = rawResult && typeof rawResult === "object" ? rawResult : {};
+  const answer =
+    typeof result.answer === "string"
+      ? result.answer
+      : typeof result.answer_markdown === "string"
+        ? result.answer_markdown
+        : "";
+
+  return {
+    capability: "wiki.ask",
+    question: context.question,
+    answer,
+    citations: normalizeCitations(result.citations),
+    confidence: result.confidence,
+    graphPath: context.graphPath,
+  };
+}
+
+async function runWikiAsk(options) {
+  const projectPath = resolveProjectPath(options.projectPath);
+  const question = String(options.question || "").trim();
+  if (!question) {
+    throw new CliError('Missing required question. Use "sdtk-wiki ask --question <text>".', 1);
+  }
+
+  const graphInfo = assertWikiGraphReady(projectPath);
+  const index = readJsonFile(graphInfo.indexPath, INDEX_FILE);
+  const graph = readJsonFile(graphInfo.graphFilePath, GRAPH_FILE);
+  const sources = buildSources(index, options.sources, options.maxSources);
+
+  const handlerState = await loadWikiAskHandler();
+  if (!handlerState.ok) {
+    throw new CliError(handlerState.message, handlerState.exitCode);
+  }
+
+  const context = {
+    capability: "wiki.ask",
+    question,
+    projectPath,
+    graphPath: graphInfo.graphPath,
+    indexPath: graphInfo.indexPath,
+    graphFilePath: graphInfo.graphFilePath,
+    graph,
+    sources,
+    maxSources: options.maxSources,
+  };
+
+  let rawResult;
+  try {
+    rawResult = await handlerState.handler(context);
+  } catch (err) {
+    throw new CliError(`SDTK-WIKI Ask runtime failed: ${err.message}`, 4);
+  }
+
+  return normalizeAskResult(rawResult, context);
+}
+
+module.exports = {
+  buildSources,
+  normalizeAskResult,
+  runWikiAsk,
+};

package/src/lib/wiki-compile.js

@@ -0,0 +1,287 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { CliError, ValidationError } = require("./errors");
+const {
+  assertWikiWorkspaceWritePath,
+  getWikiReportsPath,
+  getWikiWorkspacePath,
+  isPathInsideOrEqual,
+  resolveProjectPath,
+} = require("./wiki-paths");
+
+const REPORT_PREFIX = "compile-dry-run-preview";
+const ALLOWED_OPERATION_TYPES = new Set([
+  "append_section",
+  "create_page",
+  "add_relation",
+  "add_source_ref",
+]);
+
+function todayStamp(date = new Date()) {
+  return date.toISOString().slice(0, 10);
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function isRemoteUrl(value) {
+  return /^(?:https?|ftp):\/\//i.test(String(value || ""));
+}
+
+function resolvePlanPath(planArg, projectPath) {
+  if (!planArg) {
+    throw new ValidationError("sdtk-wiki wiki compile requires --plan <path>. No project files were changed.");
+  }
+  if (isRemoteUrl(planArg)) {
+    throw new ValidationError("Remote URL plan inputs are not supported for compile dry-run preview. No project files were changed.");
+  }
+
+  const candidate = path.isAbsolute(planArg) ? path.resolve(planArg) : path.resolve(projectPath, planArg);
+  if (!isPathInsideOrEqual(candidate, projectPath)) {
+    throw new ValidationError(`--plan must resolve inside the project root: ${candidate}. No project files were changed.`);
+  }
+  if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
+    throw new ValidationError(`--plan is not a valid file: ${candidate}. No project files were changed.`);
+  }
+  return candidate;
+}
+
+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 parseJsonPlan(planPath) {
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(planPath, "utf-8"));
+  } catch (error) {
+    throw new ValidationError(`Invalid JSON compile plan: ${error.message}. No project files were changed.`);
+  }
+  if (!payload || !Array.isArray(payload.operations)) {
+    throw new ValidationError("Invalid compile plan: JSON plan must contain an operations array. No project files were changed.");
+  }
+  return payload.operations;
+}
+
+function parseMarkdownPlan(planPath) {
+  const text = fs.readFileSync(planPath, "utf-8");
+  const lines = text.split(/\r?\n/);
+  const operations = [];
+  let current = null;
+
+  function flush() {
+    if (current && Object.keys(current).length > 1) {
+      operations.push(current);
+    }
+    current = null;
+  }
+
+  for (const line of lines) {
+    const heading = line.match(/^###\s+(.+?)\s*$/);
+    if (heading) {
+      flush();
+      current = { operation_id: heading[1].trim() };
+      continue;
+    }
+    const bullet = line.match(/^\s*-\s*([A-Za-z0-9_]+):\s*(.+?)\s*$/);
+    if (bullet && current) {
+      current[bullet[1]] = bullet[2];
+    }
+  }
+  flush();
+
+  if (operations.length === 0 || operations.every((operation) => !operation.operation_type)) {
+    throw new ValidationError(
+      "Invalid markdown compile plan: expected structured operation blocks with operation_type. No project files were changed."
+    );
+  }
+  return operations;
+}
+
+function parsePlanOperations(planPath) {
+  const ext = path.extname(planPath).toLowerCase();
+  if (ext === ".json") {
+    return parseJsonPlan(planPath);
+  }
+  if (ext === ".md" || ext === ".markdown") {
+    return parseMarkdownPlan(planPath);
+  }
+  throw new ValidationError(`Unsupported plan format: ${ext || "(none)"}. Use .md, .markdown, or .json. No project files were changed.`);
+}
+
+function splitRefs(value) {
+  if (Array.isArray(value)) return value.map(String).filter(Boolean);
+  return String(value || "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function expectedMutationFor(operation) {
+  switch (operation.operation_type) {
+    case "append_section":
+      return `Would append an evidence-backed section to ${operation.target_page_path || operation.target_page_id || "(target missing)"}.`;
+    case "create_page":
+      return `Would create managed page ${operation.target_page_path || operation.target_page_id || "(target missing)"}.`;
+    case "add_relation":
+      return `Would add a related-page relation for ${operation.target_page_path || operation.target_page_id || "(target missing)"}.`;
+    case "add_source_ref":
+      return `Would add source reference metadata for ${operation.target_page_path || operation.target_page_id || "(target missing)"}.`;
+    default:
+      return "No mutation would be allowed; operation type is unsupported in BK-126.";
+  }
+}
+
+function normalizeOperation(rawOperation, index) {
+  const operationType = String(rawOperation.operation_type || rawOperation.operationType || "").trim();
+  const isSupported = ALLOWED_OPERATION_TYPES.has(operationType);
+  const operation = {
+    operation_id: String(rawOperation.operation_id || rawOperation.operationId || `operation-${String(index + 1).padStart(3, "0")}`),
+    source_id: String(rawOperation.source_id || rawOperation.sourceId || "unknown_source"),
+    source_hash: String(rawOperation.source_hash || rawOperation.sourceHash || ""),
+    revision: String(rawOperation.revision || ""),
+    target_page_id: String(rawOperation.target_page_id || rawOperation.targetPageId || ""),
+    target_page_path: String(rawOperation.target_page_path || rawOperation.targetPagePath || ""),
+    operation_type: operationType || "unsupported_operation",
+    requested_operation_type: operationType || "(missing)",
+    proposed_content_summary: String(rawOperation.proposed_content_summary || rawOperation.proposedContentSummary || ""),
+    evidence_refs: splitRefs(rawOperation.evidence_refs || rawOperation.evidenceRefs),
+    confidence: String(rawOperation.confidence || "unknown"),
+    review_status: String(rawOperation.review_status || rawOperation.reviewStatus || "needs_review"),
+    validation_status: isSupported ? "supported" : "unsupported_operation",
+  };
+  operation.expected_mutation_if_applied = expectedMutationFor(operation);
+  if (!isSupported) {
+    operation.operation_type = "unsupported_operation";
+    operation.review_status = "blocked";
+  }
+  return operation;
+}
+
+function summarizeOperations(operations) {
+  const counts = {};
+  for (const operation of operations) {
+    counts[operation.operation_type] = (counts[operation.operation_type] || 0) + 1;
+  }
+  return counts;
+}
+
+function renderReport({ projectPath, workspacePath, planPath, generatedAt, operations }) {
+  const summary = summarizeOperations(operations);
+  const sortedTypes = Array.from(new Set([...Array.from(ALLOWED_OPERATION_TYPES), "unsupported_operation"]));
+  const unsupported = operations.filter((operation) => operation.validation_status === "unsupported_operation");
+  const lines = [
+    "# SDTK-WIKI Compile Dry-Run Preview",
+    "",
+    `Generated: ${generatedAt}`,
+    `Project path: ${projectPath}`,
+    `Workspace path: ${workspacePath}`,
+    `Input plan path: ${planPath}`,
+    `Operations: ${operations.length}`,
+    "",
+    "No wiki pages, raw sources, provenance, or atlas compatibility files were modified.",
+    "Preview-only: apply, page mutation, raw mutation, provenance mutation, discover, prune, query-history, and release work are outside BK-126.",
+    "",
+    "## Operation Counts",
+    "",
+    "| Operation type | Count |",
+    "|---|---:|",
+    ...sortedTypes.map((type) => `| \`${type}\` | ${summary[type] || 0} |`),
+    "",
+    "## Proposed Operations",
+    "",
+  ];
+
+  if (operations.length === 0) {
+    lines.push("No operations were proposed by the input plan.");
+  } else {
+    for (const operation of operations) {
+      lines.push(`### ${operation.operation_id}`);
+      lines.push("");
+      lines.push(`- operation_type: \`${operation.operation_type}\``);
+      if (operation.operation_type === "unsupported_operation") {
+        lines.push(`- requested_operation_type: \`${operation.requested_operation_type}\``);
+      }
+      lines.push(`- Validation status: ${operation.validation_status}`);
+      lines.push(`- source_id: ${operation.source_id}`);
+      lines.push(`- source_hash_or_revision: ${operation.source_hash || operation.revision || "(missing)"}`);
+      lines.push(`- target_page_id: ${operation.target_page_id || "(missing)"}`);
+      lines.push(`- target_page_path: ${operation.target_page_path || "(missing)"}`);
+      lines.push(`- proposed_content_summary: ${operation.proposed_content_summary || "(missing)"}`);
+      lines.push(`- evidence_refs: ${operation.evidence_refs.length > 0 ? operation.evidence_refs.join(", ") : "(missing)"}`);
+      lines.push(`- confidence: ${operation.confidence}`);
+      lines.push(`- review_status: ${operation.review_status}`);
+      lines.push(`- Expected mutation if applied: ${operation.expected_mutation_if_applied}`);
+      lines.push("");
+    }
+  }
+
+  lines.push("## Unsupported / Blocked Operations");
+  lines.push("");
+  if (unsupported.length === 0) {
+    lines.push("- None.");
+  } else {
+    for (const operation of unsupported) {
+      lines.push(`- ${operation.operation_id}: unsupported_operation for requested type \`${operation.requested_operation_type}\`.`);
+    }
+  }
+  lines.push("");
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function runWikiCompileDryRun({ projectPath, planArg }) {
+  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 planPath = resolvePlanPath(planArg, resolvedProjectPath);
+    const rawOperations = parsePlanOperations(planPath);
+    const operations = rawOperations.map((operation, index) => normalizeOperation(operation, index));
+    const reportsPath = getWikiReportsPath(resolvedProjectPath);
+    assertWikiWorkspaceWritePath(reportsPath, resolvedProjectPath);
+    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,
+        planPath,
+        generatedAt,
+        operations,
+      }),
+      "utf-8"
+    );
+
+    return {
+      reportPath,
+      operations,
+      summary: summarizeOperations(operations),
+      unsupportedCount: operations.filter((operation) => operation.validation_status === "unsupported_operation").length,
+    };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError(`Failed to write SDTK-WIKI compile dry-run preview: ${error.message}`);
+  }
+}
+
+module.exports = {
+  ALLOWED_OPERATION_TYPES,
+  REPORT_PREFIX,
+  renderReport,
+  runWikiCompileDryRun,
+};

package/src/lib/wiki-config.js

@@ -0,0 +1,180 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { ValidationError } = require("./errors");
+const {
+  getLegacyAtlasPath,
+  getWikiGraphPath,
+  getWikiWorkspacePath,
+  isPathInsideOrEqual,
+} = require("./wiki-paths");
+
+const CONFIG_SCHEMA_VERSION = 1;
+const DEFAULT_PORT = 8765;
+const DEFAULT_HOST = "127.0.0.1";
+
+const DEFAULT_EXCLUDES = [
+  ".git",
+  ".sdtk/wiki",
+  ".sdtk/atlas",
+  "node_modules",
+  ".venv",
+  "venv",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  "__pycache__",
+];
+
+function resolveWikiConfig(flags = {}) {
+  const projectPath = flags["project-path"]
+    ? path.resolve(flags["project-path"])
+    : process.cwd();
+
+  if (!fs.existsSync(projectPath) || !fs.statSync(projectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${projectPath}`);
+  }
+
+  const defaultOutputDir = getWikiGraphPath(projectPath);
+  const outputDir = flags["output-dir"]
+    ? path.resolve(flags["output-dir"])
+    : defaultOutputDir;
+  const workspaceRoot = getWikiWorkspacePath(projectPath);
+  if (!isPathInsideOrEqual(outputDir, workspaceRoot)) {
+    throw new ValidationError(
+      `--output-dir must stay under project-local .sdtk/wiki workspace: ${outputDir}`
+    );
+  }
+  const configPath = path.join(outputDir, "config.json");
+  const legacyAtlasDir = getLegacyAtlasPath(projectPath);
+
+  let persisted = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      persisted = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    } catch (_) {
+      persisted = {};
+    }
+  }
+
+  let scanRoots;
+  if (flags["scan-root"] && flags["scan-root"].length > 0) {
+    scanRoots = flags["scan-root"].map((r) => path.resolve(r));
+  } else if (
+    persisted.scanRoots &&
+    Array.isArray(persisted.scanRoots) &&
+    persisted.scanRoots.length > 0
+  ) {
+    scanRoots = persisted.scanRoots.map((r) => path.resolve(r));
+  } else {
+    scanRoots = [projectPath];
+  }
+
+  const excludes =
+    persisted.excludes && Array.isArray(persisted.excludes)
+      ? persisted.excludes
+      : DEFAULT_EXCLUDES.slice();
+
+  const host = flags.host || persisted.host || DEFAULT_HOST;
+  const port = flags.port
+    ? parseInt(flags.port, 10)
+    : persisted.port || DEFAULT_PORT;
+
+  if (Number.isNaN(port) || port < 1 || port > 65535) {
+    throw new ValidationError(`Invalid --port value: ${flags.port}`);
+  }
+
+  return {
+    projectPath,
+    outputDir,
+    configPath,
+    legacyAtlasDir,
+    scanRoots,
+    excludes,
+    host,
+    port,
+    verbose: !!flags.verbose,
+  };
+}
+
+function writeWikiConfig(config) {
+  fs.mkdirSync(config.outputDir, { recursive: true });
+
+  const payload = {
+    schemaVersion: CONFIG_SCHEMA_VERSION,
+    product: "SDTK-WIKI",
+    projectPath: config.projectPath,
+    outputDir: config.outputDir,
+    legacyAtlasDir: config.legacyAtlasDir,
+    scanRoots: config.scanRoots,
+    excludes: config.excludes,
+    host: config.host,
+    port: config.port,
+  };
+
+  fs.writeFileSync(config.configPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+}
+
+function isWikiInitialized(outputDir) {
+  return fs.existsSync(path.join(outputDir, "config.json"));
+}
+
+function isWikiBuilt(outputDir) {
+  return (
+    fs.existsSync(path.join(outputDir, "SDTK_DOC_INDEX.json")) &&
+    fs.existsSync(path.join(outputDir, "viewer.html"))
+  );
+}
+
+function isLegacyAtlasBuilt(projectPath) {
+  const legacyDir = getLegacyAtlasPath(projectPath);
+  return isWikiBuilt(legacyDir);
+}
+
+function readBuildMeta(outputDir) {
+  const indexPath = path.join(outputDir, "SDTK_DOC_INDEX.json");
+  if (!fs.existsSync(indexPath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(indexPath, "utf-8"));
+    return { generated: data.generated || null, count: data.count || 0 };
+  } catch (_) {
+    return null;
+  }
+}
+
+function readGraphMeta(outputDir) {
+  const graphPath = path.join(outputDir, "SDTK_DOC_GRAPH.json");
+  if (!fs.existsSync(graphPath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(graphPath, "utf-8"));
+    return {
+      nodeCount: data.node_count || 0,
+      edgeCount: data.edge_count || 0,
+    };
+  } catch (_) {
+    return null;
+  }
+}
+
+function resolveBuilderPath() {
+  return path.resolve(__dirname, "..", "..", "assets", "atlas", "build_atlas.py");
+}
+
+module.exports = {
+  CONFIG_SCHEMA_VERSION,
+  DEFAULT_EXCLUDES,
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  isLegacyAtlasBuilt,
+  isWikiBuilt,
+  isWikiInitialized,
+  readBuildMeta,
+  readGraphMeta,
+  resolveBuilderPath,
+  resolveWikiConfig,
+  writeWikiConfig,
+};