sdtk-wiki-kit 0.1.0

package/assets/keys/sdtk-entitlement-public.pem

@@ -0,0 +1,11 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Z3VS5JJcds3xfn/bB9l
+TjVvTvZ1r8r8kAjQAj0r7O4JkX4KzK4S2E8jZK3vZ7Jz7m8Lq5Zx3V9B9R1K1X2C
+3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2G3H4I5
+J6K7L8M9N0O1P2Q3R4S5T6U7V8W9X0Y1Z2A3B4C5D6E7F8G9H0I1J2K3L4M5N6O7P8
+Q9R0S1T2U3V4W5X6Y7Z8A9B0C1D2E3F4G5H6I7J8K9L0M1N2O3P4Q5R6S7T8U9V0W1
+X2Y3Z4A5B6C7D8E9F0G1H2I3J4K5L6M7N8O9P0Q1R2S3T4U5V6W7X8Y9Z0A1B2C3D4
+E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2G3H4I5J6K7
+L8M9N0O1P2Q3R4S5T6U7V8W9X0Y1Z2A3B4C5D6E7F8G9H0I1J2K3L4M5N6O7P8Q9
+AQIDAQAB
+-----END PUBLIC KEY-----

package/bin/sdtk-wiki.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { run } = require("../src/index");
+
+run(process.argv.slice(2))
+  .then((exitCode) => {
+    process.exitCode = Number.isInteger(exitCode) ? exitCode : 0;
+  })
+  .catch((error) => {
+    console.error(`sdtk-wiki: ${error.message}`);
+    process.exitCode = typeof error.exitCode === "number" ? error.exitCode : 4;
+  });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "sdtk-wiki-kit",
+  "version": "0.1.0",
+  "description": "Project-local wiki and knowledge graph toolkit for SDTK workspaces.",
+  "bin": {
+    "sdtk-wiki": "bin/sdtk-wiki.js"
+  },
+  "main": "src/index.js",
+  "type": "commonjs",
+  "files": [
+    "bin/",
+    "src/",
+    "assets/keys/sdtk-entitlement-public.pem",
+    "assets/atlas/build_atlas.py",
+    "assets/atlas/doc_atlas_viewer_template.html",
+    "assets/atlas/vendor/mermaid.min.js"
+  ],
+  "scripts": {
+    "test": "powershell -ExecutionPolicy Bypass -Command \"$ErrorActionPreference = 'Stop'; Set-Location '..\\..\\..\\..'; python -m unittest tests.test_sdtk_wiki_cli\"",
+    "pack:smoke": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18.13.0"
+  },
+  "keywords": [
+    "sdtk-wiki",
+    "wiki",
+    "knowledge-graph",
+    "cli",
+    "toolkit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codexsdtk/sdtk-toolkit.git",
+    "directory": "products/sdtk-wiki/distribution/sdtk-wiki-kit"
+  },
+  "homepage": "https://github.com/codexsdtk/sdtk-toolkit/tree/main/products/sdtk-wiki/distribution/sdtk-wiki-kit",
+  "bugs": {
+    "url": "https://github.com/codexsdtk/sdtk-toolkit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/ask.js

@@ -0,0 +1,139 @@
+"use strict";
+
+const { parseFlags } = require("../lib/args");
+const { runWikiAsk } = require("../lib/wiki-ask");
+const { saveQueryHistoryRecord } = require("../lib/wiki-query-history");
+
+const ASK_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  question: { type: "string", alias: "q" },
+  "project-path": { type: "string" },
+  json: { type: "boolean" },
+  source: { type: "string" },
+  "max-sources": { type: "string" },
+  "save-query": { type: "boolean" },
+};
+
+function parseAskFlags(args) {
+  const sources = [];
+  const filteredArgs = [];
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === "--source") {
+      i++;
+      if (i < args.length) {
+        sources.push(args[i]);
+        i++;
+      }
+    } else if (arg.startsWith("--source=")) {
+      sources.push(arg.slice("--source=".length));
+      i++;
+    } else {
+      filteredArgs.push(arg);
+      i++;
+    }
+  }
+
+  const { flags, positional } = parseFlags(filteredArgs, ASK_FLAG_DEFS);
+  flags.source = sources.length > 0 ? sources : flags.source ? [flags.source] : [];
+  return { flags, positional };
+}
+
+function printAskHelp() {
+  console.log(`SDTK-WIKI Ask
+
+Usage:
+  sdtk-wiki ask --question "<text>" [--project-path <path>] [--json] [--save-query]
+  sdtk-wiki ask --question "<text>" [--source <id-or-path>] [--max-sources <n>]
+
+Capability:
+  wiki.ask             Canonical SDTK-WIKI Ask capability.
+
+Inputs:
+  .sdtk/wiki/graph     Required built wiki graph. Run "sdtk-wiki atlas build" first.
+
+Behavior:
+  Executes a local premium wiki.ask runtime pack when entitlement and graph preconditions pass.
+  Fails closed when the graph, entitlement, or runtime pack is missing.
+  Query history is off by default.
+  --save-query writes one redacted JSON record under .sdtk/wiki/queries after a successful answer.
+  Full question and full answer are not stored by default.`);
+  return 0;
+}
+
+function formatHumanResult(result, queryHistory) {
+  const lines = [
+    "Answer:",
+    result.answer || "(No answer returned by SDTK-WIKI Ask runtime.)",
+    "",
+    "Citations:",
+  ];
+
+  if (result.citations.length) {
+    for (const citation of result.citations) {
+      lines.push(`- ${citation}`);
+    }
+  } else {
+    lines.push("- none");
+  }
+
+  if (result.confidence) {
+    lines.push("", `Confidence: ${result.confidence}`);
+  }
+  lines.push("", "Capability: wiki.ask");
+  if (queryHistory && queryHistory.saved) {
+    lines.push("", `Query record: ${queryHistory.recordPath}`);
+  }
+  return lines.join("\n");
+}
+
+async function cmdAsk(args) {
+  const { flags, positional } = parseAskFlags(args || []);
+  if (flags.help) {
+    return printAskHelp();
+  }
+
+  const question = flags.question || positional.join(" ");
+  const maxSources =
+    flags["max-sources"] !== undefined ? Number.parseInt(flags["max-sources"], 10) : undefined;
+
+  const result = await runWikiAsk({
+    question,
+    projectPath: flags["project-path"],
+    sources: flags.source,
+    maxSources,
+  });
+  const queryHistory = { saved: false };
+
+  if (flags["save-query"]) {
+    try {
+      const saved = saveQueryHistoryRecord({
+        projectPath: flags["project-path"],
+        question,
+        result,
+      });
+      queryHistory.saved = true;
+      queryHistory.recordPath = saved.recordPath;
+    } catch (err) {
+      queryHistory.warning = `Query history was not saved: ${err.message}`;
+      console.error(`sdtk-wiki warning: ${queryHistory.warning}`);
+    }
+  }
+
+  if (flags.json) {
+    const payload = flags["save-query"] ? { ...result, queryHistory } : result;
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(formatHumanResult(result, queryHistory));
+  }
+  return 0;
+}
+
+module.exports = {
+  cmdAsk,
+  formatHumanResult,
+  parseAskFlags,
+  printAskHelp,
+};

package/src/commands/atlas.js

@@ -0,0 +1,339 @@
+"use strict";
+
+const fs = require("fs");
+const { ValidationError } = require("../lib/errors");
+const {
+  isWikiBuilt,
+  isWikiInitialized,
+  readBuildMeta,
+  readGraphMeta,
+  resolveWikiConfig,
+  writeWikiConfig,
+} = require("../lib/wiki-config");
+const { ensureWorkspace, getWorkspaceStatus } = require("../lib/wiki-workspace");
+const { openViewer, runBuild } = require("../lib/wiki-runner");
+const {
+  BASE_FLAG_DEFS,
+  OPEN_FLAG_DEFS,
+  WATCH_FLAG_DEFS,
+  parseWikiFlags,
+} = require("../lib/wiki-flags");
+
+const ATLAS_COMMANDS = new Set(["build", "open", "watch", "status"]);
+
+function hasHelp(args) {
+  return args.includes("-h") || args.includes("--help");
+}
+
+function cmdAtlasOverviewHelp() {
+  console.log(`Usage:
+  sdtk-wiki atlas <command> --help
+
+Commands:
+  build       SDTK-WIKI graph build via the atlas compatibility namespace.
+  open        SDTK-WIKI viewer open via the atlas compatibility namespace.
+  watch       SDTK-WIKI watcher via the atlas compatibility namespace.
+  status      SDTK-WIKI graph status via the atlas compatibility namespace.
+
+Compatibility:
+  "atlas" remains the R1 compatibility namespace for existing workflows.
+  sdtk-wiki defaults to .sdtk/wiki/graph.
+  Legacy .sdtk/atlas remains readable and is never auto-deleted.`);
+  return 0;
+}
+
+function cmdAtlasSubcommandHelp(subcommand) {
+  const descriptions = {
+    build: "Build the SDTK-WIKI graph from project-local sources.",
+    open: "Open the SDTK-WIKI graph viewer.",
+    watch: "Watch project-local sources and refresh the graph.",
+    status: "Report SDTK-WIKI graph workspace status.",
+  };
+
+  console.log(`Usage:
+  sdtk-wiki atlas ${subcommand} --help
+
+Purpose:
+  ${descriptions[subcommand]}
+
+BK-103 behavior:
+  Help exits 0.
+  Runtime execution is implemented for local deterministic graph/viewer commands.
+  Free graph/viewer commands do not require activation.
+
+Workspace:
+  New target: .sdtk/wiki
+  Graph target: .sdtk/wiki/graph
+  Legacy readable path: .sdtk/atlas`);
+  return 0;
+}
+
+async function cmdAtlasBuild(args) {
+  const { flags } = parseWikiFlags(args, BASE_FLAG_DEFS);
+  const config = resolveWikiConfig(flags);
+  ensureWorkspace(config.projectPath, config.outputDir);
+
+  if (!isWikiInitialized(config.outputDir)) {
+    console.log("[wiki] SDTK-WIKI not initialized. Run: sdtk-wiki init");
+    console.log(`[wiki] Output dir: ${config.outputDir}`);
+  }
+
+  const startMs = Date.now();
+  const buildResult = await runBuild(config);
+  const durationMs = Date.now() - startMs;
+
+  console.log("");
+  console.log("[wiki] Build summary:");
+  console.log(`  Documents:  ${buildResult.docCount}`);
+  console.log(`  Graph nodes: ${buildResult.nodeCount}`);
+  console.log(`  Graph edges: ${buildResult.edgeCount}`);
+  console.log(`  Wiki pages:  ${buildResult.pageCount}`);
+  console.log(`  Output dir:  ${config.outputDir}`);
+  if (buildResult.provenancePath) {
+    console.log(`  Provenance:  ${buildResult.provenancePath}`);
+  }
+  console.log(`  Duration:    ${(durationMs / 1000).toFixed(1)}s`);
+  if (buildResult.generated) {
+    console.log(`  Generated:   ${buildResult.generated}`);
+  }
+  return 0;
+}
+
+function resolveReadableViewerConfig(config) {
+  if (isWikiBuilt(config.outputDir)) {
+    return { config, source: "wiki" };
+  }
+  if (isWikiBuilt(config.legacyAtlasDir)) {
+    return {
+      config: {
+        ...config,
+        outputDir: config.legacyAtlasDir,
+      },
+      source: "legacy-atlas",
+    };
+  }
+  return { config, source: "missing" };
+}
+
+async function cmdAtlasOpen(args) {
+  const { flags } = parseWikiFlags(args, OPEN_FLAG_DEFS);
+  const config = resolveWikiConfig(flags);
+  const resolved = resolveReadableViewerConfig(config);
+
+  if (resolved.source === "missing") {
+    console.error("[wiki] No SDTK-WIKI graph build found.");
+    console.error(`  Expected: ${config.outputDir}/viewer.html`);
+    console.error(`  Legacy readable fallback: ${config.legacyAtlasDir}/viewer.html`);
+    console.error("  Run: sdtk-wiki init");
+    console.error("  Or:  sdtk-wiki atlas build");
+    return 1;
+  }
+
+  if (resolved.source === "legacy-atlas") {
+    console.log(`[wiki] Using legacy Atlas output read-only: ${resolved.config.outputDir}`);
+    console.log("[wiki] No files will be migrated or deleted.");
+  }
+
+  const noOpen = !!flags["no-open"];
+  const { server } = await openViewer(resolved.config, noOpen);
+
+  if (noOpen) {
+    if (server) server.close();
+    return 0;
+  }
+
+  console.log("[wiki] Press Ctrl+C to stop the viewer server.");
+  await new Promise(() => {});
+  return 0;
+}
+
+async function cmdAtlasWatch(args) {
+  const { flags } = parseWikiFlags(args, WATCH_FLAG_DEFS);
+  const config = resolveWikiConfig(flags);
+
+  if (!isWikiInitialized(config.outputDir)) {
+    console.log("[wiki] SDTK-WIKI not initialized. Running init first...");
+    writeWikiConfig(config);
+    console.log(`[wiki] Initialized SDTK-WIKI config: ${config.configPath}`);
+  }
+
+  const DEBOUNCE_MS = 800;
+  let debounceTimer = null;
+  let rebuilding = false;
+
+  async function rebuild(reason) {
+    if (rebuilding) return;
+    rebuilding = true;
+    console.log(`\n[wiki] Change detected (${reason}). Rebuilding...`);
+    try {
+      const buildResult = await runBuild(config);
+      console.log(`[wiki] Rebuild complete: ${buildResult.docCount} docs, ${buildResult.nodeCount} nodes, ${buildResult.pageCount} pages.`);
+    } catch (err) {
+      console.error(`[wiki] Rebuild failed: ${err.message}`);
+    } finally {
+      rebuilding = false;
+    }
+  }
+
+  console.log("[wiki] Running initial build...");
+  try {
+    const buildResult = await runBuild(config);
+    console.log(`[wiki] Initial build complete: ${buildResult.docCount} docs, ${buildResult.pageCount} pages.`);
+  } catch (err) {
+    console.error(`[wiki] Initial build failed: ${err.message}`);
+  }
+
+  let viewerServer = null;
+  if (!flags["no-open"] && isWikiBuilt(config.outputDir)) {
+    const result = await openViewer(config, false);
+    viewerServer = result.server;
+  }
+
+  const watchers = [];
+  for (const scanRoot of config.scanRoots) {
+    if (!fs.existsSync(scanRoot)) {
+      console.log(`[wiki] Warning: scan root does not exist, skipping watch: ${scanRoot}`);
+      continue;
+    }
+
+    try {
+      const watcher = fs.watch(scanRoot, { recursive: true }, (eventType, filename) => {
+        if (!filename || !filename.endsWith(".md")) return;
+        if (debounceTimer) clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          rebuild(`${eventType}: ${filename}`);
+        }, DEBOUNCE_MS);
+      });
+
+      watcher.on("error", (err) => {
+        console.error(`[wiki] Watch error on ${scanRoot}: ${err.message}`);
+      });
+
+      watchers.push(watcher);
+      console.log(`[wiki] Watching: ${scanRoot}`);
+    } catch (err) {
+      console.error(`[wiki] Could not watch ${scanRoot}: ${err.message}`);
+    }
+  }
+
+  if (watchers.length === 0) {
+    console.error("[wiki] No scan roots could be watched. Exiting.");
+    return 1;
+  }
+
+  console.log("[wiki] Watching for markdown changes. Press Ctrl+C to stop.");
+
+  function shutdown() {
+    console.log("\n[wiki] Stopping watch...");
+    if (debounceTimer) clearTimeout(debounceTimer);
+    for (const w of watchers) {
+      try { w.close(); } catch (_) {}
+    }
+    if (viewerServer) {
+      try { viewerServer.close(); } catch (_) {}
+    }
+    process.exit(0);
+  }
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  await new Promise(() => {});
+  return 0;
+}
+
+async function cmdAtlasStatus(args) {
+  const { flags } = parseWikiFlags(args, BASE_FLAG_DEFS);
+  let config;
+  try {
+    config = resolveWikiConfig(flags);
+  } catch (err) {
+    console.error(`[wiki] Config error: ${err.message}`);
+    return 1;
+  }
+
+  const initialized = isWikiInitialized(config.outputDir);
+  const built = isWikiBuilt(config.outputDir);
+  const legacyBuilt = isWikiBuilt(config.legacyAtlasDir);
+  const workspaceStatus = getWorkspaceStatus(config.projectPath);
+
+  console.log("[wiki] Status");
+  console.log("=".repeat(40));
+  console.log(`  Initialized:       ${initialized ? "yes" : "no"}`);
+  console.log(`  Built:             ${built ? "yes" : "no"}`);
+  console.log(`  Manifest:          ${workspaceStatus.manifestExists ? "yes" : "no"}`);
+  console.log(`  Schema version:    ${workspaceStatus.schemaVersion || "n/a"}`);
+  console.log(`  Legacy readable:   ${legacyBuilt ? "yes" : "no"}`);
+  console.log(`  Project root:      ${config.projectPath}`);
+  console.log(`  Workspace root:    ${workspaceStatus.workspace.workspaceRoot}`);
+  console.log(`  Output dir:        ${config.outputDir}`);
+  console.log(`  Legacy Atlas dir:  ${config.legacyAtlasDir}`);
+  console.log(`  Scan roots:        ${config.scanRoots.join(", ")}`);
+  console.log(`  Viewer host:       ${config.host}:${config.port}`);
+
+  if (built) {
+    const meta = readBuildMeta(config.outputDir);
+    const graphMeta = readGraphMeta(config.outputDir);
+    if (meta) {
+      console.log(`  Last build:        ${meta.generated || "unknown"}`);
+      console.log(`  Documents:         ${meta.count}`);
+    }
+    if (graphMeta) {
+      console.log(`  Graph nodes:       ${graphMeta.nodeCount}`);
+      console.log(`  Graph edges:       ${graphMeta.edgeCount}`);
+    }
+  } else if (legacyBuilt) {
+    console.log("");
+    console.log("[wiki] Legacy .sdtk/atlas build is readable for open/status fallback.");
+    console.log("[wiki] It will not be auto-migrated or deleted.");
+  }
+
+  if (!initialized) {
+    console.log("");
+    console.log("[wiki] Hint: run 'sdtk-wiki init' to initialize SDTK-WIKI for this project.");
+  } else if (!built) {
+    console.log("");
+    console.log("[wiki] Hint: run 'sdtk-wiki atlas build' to build the local document graph.");
+  }
+
+  return 0;
+}
+
+async function cmdAtlas(args) {
+  if (!args || args.length === 0) {
+    return cmdAtlasOverviewHelp();
+  }
+
+  const [subcommand, ...rest] = args;
+  if (subcommand === "-h" || subcommand === "--help") {
+    return cmdAtlasOverviewHelp();
+  }
+
+  if (!ATLAS_COMMANDS.has(subcommand)) {
+    throw new ValidationError(
+      `Unknown atlas command: "${subcommand}". Run "sdtk-wiki atlas --help".`
+    );
+  }
+
+  if (hasHelp(rest)) {
+    return cmdAtlasSubcommandHelp(subcommand);
+  }
+
+  switch (subcommand) {
+    case "build":
+      return cmdAtlasBuild(rest);
+    case "open":
+      return cmdAtlasOpen(rest);
+    case "watch":
+      return cmdAtlasWatch(rest);
+    case "status":
+      return cmdAtlasStatus(rest);
+  }
+}
+
+module.exports = {
+  ATLAS_COMMANDS,
+  cmdAtlas,
+  cmdAtlasOverviewHelp,
+  cmdAtlasSubcommandHelp,
+};

package/src/commands/deferred.js

@@ -0,0 +1,14 @@
+"use strict";
+
+const { CliError } = require("../lib/errors");
+
+function cmdDeferredAsk() {
+  throw new CliError(
+    "This deferred Ask helper is not part of the active sdtk-wiki command path. Use sdtk-wiki ask --help for the native wiki.ask runtime contract.",
+    1
+  );
+}
+
+module.exports = {
+  cmdDeferredAsk,
+};

package/src/commands/help.js

@@ -0,0 +1,67 @@
+"use strict";
+
+function cmdHelp() {
+  console.log(`SDTK-WIKI
+
+Usage:
+  sdtk-wiki --help
+  sdtk-wiki --version
+  sdtk-wiki init --help
+  sdtk-wiki atlas build --help
+  sdtk-wiki atlas open --help
+  sdtk-wiki atlas watch --help
+  sdtk-wiki atlas status --help
+  sdtk-wiki wiki ingest --help
+  sdtk-wiki wiki prune --help
+  sdtk-wiki wiki discover --help
+  sdtk-wiki wiki compile --help
+  sdtk-wiki ask --help
+  sdtk-wiki lint --help
+
+R1 command model:
+  init                 Initialize the SDTK-WIKI workspace.
+  atlas build          Build graph/viewer plus local wiki pages/provenance.
+  atlas open           Open or serve the local graph viewer.
+  atlas watch          Watch markdown sources and rebuild the graph.
+  atlas status         Report graph workspace status.
+  wiki ingest          Register one local source in metadata-only raw/provenance state.
+  wiki prune           Write a report-only dry-run stale managed-page review.
+  wiki discover        Write a local-only discovery plan from WIKI gap evidence.
+  wiki compile         Write a compile dry-run preview from a local plan.
+  ask                  Ask grounded questions over the built SDTK-WIKI graph.
+  lint                 Write a report-first, non-destructive wiki lint report.
+
+Workspace paths:
+  .sdtk/wiki           New SDTK-WIKI workspace target.
+  .sdtk/wiki/graph     New SDTK-WIKI graph output target.
+  .sdtk/wiki/pages     Generated local wiki page target.
+  .sdtk/wiki/raw       Metadata-only local source registry target.
+  .sdtk/wiki/provenance Generated source provenance target.
+  .sdtk/atlas          Legacy Atlas workspace, readable for compatibility.
+  Write paths must stay under project-local .sdtk/wiki.
+
+Compatibility:
+  Existing sdtk-spec atlas commands remain the R1 compatibility path.
+  sdtk-spec atlas keeps compatibility output under .sdtk/atlas.
+  SDTK-WIKI reads legacy .sdtk/atlas output for compatibility and never auto-deletes it.
+
+Premium Ask:
+  sdtk-wiki ask        Canonical SDTK-WIKI Q&A command for capability wiki.ask.
+                       Requires .sdtk/wiki/graph plus local entitlement/runtime preconditions.
+                       Query history, discover, compile, and cleanup automation are not enabled in R1.
+
+Maintenance:
+  sdtk-wiki wiki prune --dry-run is report-only and writes under .sdtk/wiki/reports.
+  It never deletes, archives, applies, or mutates .sdtk/atlas.`);
+  console.log(`
+  sdtk-wiki wiki discover --plan is plan-only and writes under .sdtk/wiki/reports.
+  It never fetches web sources, ingests sources, compiles pages, applies edits, prunes, or mutates .sdtk/atlas.`);
+  console.log(`
+  sdtk-wiki wiki compile --dry-run writes a compile dry-run preview under .sdtk/wiki/reports.
+  It never applies changes, rewrites pages, mutates raw/provenance files, or mutates .sdtk/atlas.`);
+  return 0;
+}
+
+module.exports = {
+  cmdHelp,
+};