sdtk-wiki-kit 0.1.0

package/src/commands/init.js

@@ -0,0 +1,91 @@
+"use strict";
+
+const {
+  isWikiInitialized,
+  resolveWikiConfig,
+  writeWikiConfig,
+} = require("../lib/wiki-config");
+const { ensureWorkspace } = require("../lib/wiki-workspace");
+const { runBuild } = require("../lib/wiki-runner");
+const { INIT_FLAG_DEFS, parseWikiFlags } = require("../lib/wiki-flags");
+
+function hasHelp(args) {
+  return args.includes("-h") || args.includes("--help");
+}
+
+function cmdInitHelp() {
+  console.log(`Usage:
+  sdtk-wiki init --help
+
+Purpose:
+  Defines the SDTK-WIKI workspace contract for R1.
+
+Workspace contract:
+  .sdtk/wiki           New SDTK-WIKI workspace target.
+  .sdtk/wiki/graph     New SDTK-WIKI graph output target.
+  .sdtk/atlas          Legacy Atlas workspace remains readable.
+
+BK-102 behavior:
+  Help exits 0.
+  Runtime initialization is implemented in BK-103.
+
+Options:
+  --project-path <path>   Project root. Defaults to current working directory.
+  --output-dir <path>     Graph output dir under .sdtk/wiki. Defaults to .sdtk/wiki/graph.
+  --scan-root <path>      Repeatable markdown scan root.
+  --force                 Overwrite existing config.
+  --no-build              Write config only.
+  --no-open               Build graph but do not launch viewer.
+  --host <host>           Viewer host. Defaults to 127.0.0.1.
+  --port <port>           Viewer port. Defaults to 8765.
+  --verbose               Print builder details.`);
+  return 0;
+}
+
+async function cmdInit(args) {
+  if (hasHelp(args)) {
+    return cmdInitHelp();
+  }
+
+  const { flags } = parseWikiFlags(args, INIT_FLAG_DEFS);
+  const config = resolveWikiConfig(flags);
+  const { workspace } = ensureWorkspace(config.projectPath, config.outputDir);
+
+  if (isWikiInitialized(config.outputDir) && !flags.force) {
+    console.log(`[wiki] SDTK-WIKI already initialized at: ${config.outputDir}`);
+    console.log("[wiki] Use --force to overwrite existing config.");
+  } else {
+    writeWikiConfig(config);
+    console.log(`[wiki] Initialized SDTK-WIKI config: ${config.configPath}`);
+    console.log(`[wiki] Project root:  ${config.projectPath}`);
+    console.log(`[wiki] Output dir:    ${config.outputDir}`);
+    console.log(`[wiki] Legacy Atlas:  ${config.legacyAtlasDir}`);
+    console.log(`[wiki] Scan roots:    ${config.scanRoots.join(", ")}`);
+  }
+  console.log(`[wiki] Workspace:     ${workspace.workspaceRoot}`);
+  console.log(`[wiki] Manifest:      ${workspace.manifestPath}`);
+
+  if (flags["no-build"]) {
+    console.log("[wiki] --no-build specified; skipping initial build.");
+    return 0;
+  }
+
+  console.log("");
+  const buildResult = await runBuild(config);
+  console.log(`[wiki] Build complete: ${buildResult.docCount} docs, ${buildResult.nodeCount} nodes, ${buildResult.edgeCount} edges.`);
+
+  if (flags["no-open"]) {
+    console.log("[wiki] --no-open specified; skipping viewer launch.");
+    return 0;
+  }
+
+  const { openViewer } = require("../lib/wiki-runner");
+  const { url } = await openViewer(config, false);
+  console.log(`[wiki] Viewer: ${url}`);
+  return 0;
+}
+
+module.exports = {
+  cmdInit,
+  cmdInitHelp,
+};

package/src/commands/lint.js

@@ -0,0 +1,48 @@
+"use strict";
+
+const { LINT_FLAG_DEFS, parseWikiFlags } = require("../lib/wiki-flags");
+const { runWikiLint } = require("../lib/wiki-lint");
+
+function hasHelp(args) {
+  return args.includes("-h") || args.includes("--help");
+}
+
+function cmdLintHelp() {
+  console.log(`Usage:
+  sdtk-wiki lint --help
+  sdtk-wiki lint [--project-path <path>]
+
+Purpose:
+  Run report-first, non-destructive lint checks over canonical .sdtk/wiki content.
+
+Output:
+  .sdtk/wiki/reports/lint-report-YYYY-MM-DD.md
+
+Behavior:
+  Findings are written to the report and do not auto-modify wiki or source files.
+  Completed lint runs exit 0 even when findings exist.
+  Missing workspace or fatal report-write failures exit non-zero.
+
+Options:
+  --project-path <path>   Project root. Defaults to current working directory.`);
+  return 0;
+}
+
+function cmdLint(args) {
+  if (hasHelp(args)) {
+    return cmdLintHelp();
+  }
+
+  const { flags } = parseWikiFlags(args, LINT_FLAG_DEFS);
+  const result = runWikiLint({ projectPath: flags["project-path"] });
+
+  console.log(`[wiki] Lint report: ${result.reportPath}`);
+  console.log(`[wiki] Findings: ${result.totalFindings}`);
+  console.log("[wiki] No wiki or source content was auto-modified.");
+  return 0;
+}
+
+module.exports = {
+  cmdLint,
+  cmdLintHelp,
+};

package/src/commands/wiki.js

@@ -0,0 +1,251 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { CliError, ValidationError } = require("../lib/errors");
+const { runWikiCompileDryRun } = require("../lib/wiki-compile");
+const { runWikiDiscoverPlan } = require("../lib/wiki-discover");
+const { ingestLocalSource } = require("../lib/wiki-ingest");
+const { runWikiPruneDryRun } = require("../lib/wiki-prune");
+const { COMPILE_FLAG_DEFS, DISCOVER_FLAG_DEFS, PRUNE_FLAG_DEFS, parseWikiFlags } = require("../lib/wiki-flags");
+
+function hasHelp(args) {
+  return args.includes("-h") || args.includes("--help");
+}
+
+function cmdWikiHelp() {
+  console.log(`Usage:
+  sdtk-wiki wiki --help
+  sdtk-wiki wiki ingest --help
+  sdtk-wiki wiki prune --help
+  sdtk-wiki wiki discover --help
+  sdtk-wiki wiki compile --help
+
+Purpose:
+  Native SDTK-WIKI command namespace.
+
+Deferred:
+  web discover/fetch, compile/apply, destructive cleanup/archive, and payload snapshots remain deferred.
+  Web discover/improve must not be enabled by default in R1.`);
+  return 0;
+}
+
+function cmdWikiCompileHelp() {
+  console.log(`Usage:
+  sdtk-wiki wiki compile --plan <path> --project-path <path> --dry-run
+
+Purpose:
+  Write a compile dry-run preview from a local markdown or JSON plan.
+
+Writes:
+  .sdtk/wiki/reports/compile-dry-run-preview-YYYY-MM-DD.md
+
+Safety:
+  Preview-only.
+  No --apply behavior is implemented in BK-126.
+  No wiki page, raw source, provenance, atlas compatibility, discover, prune, query-history, or release mutation.
+  Unknown operation types are reported as unsupported_operation and cause a non-zero exit after the report is written.`);
+  return 0;
+}
+
+function cmdWikiIngestHelp() {
+  console.log(`Usage:
+  sdtk-wiki wiki ingest --project-path <path> --source <path>
+
+Purpose:
+  Register one local source in the metadata-only raw/source boundary.
+
+Writes:
+  .sdtk/wiki/raw
+  .sdtk/wiki/provenance
+
+Safety:
+  Local project files only.
+  Metadata-only registry; no source payload copy.
+  No compiled pages or graph/viewer rebuild side effects.`);
+  return 0;
+}
+
+function cmdWikiPruneHelp() {
+  console.log(`Usage:
+  sdtk-wiki wiki prune --dry-run --project-path <path>
+
+Purpose:
+  Write a report-only stale managed-page review for SDTK-WIKI.
+
+Writes:
+  .sdtk/wiki/reports/prune-dry-run-report-YYYY-MM-DD.md
+
+Safety:
+  Dry-run only.
+  Managed wiki pages under .sdtk/wiki/pages are scanned but not modified.
+  No delete, archive, apply, discover, compile, query-history, or Ask work.
+  Every finding keeps the never_delete_automatically safety posture.`);
+  return 0;
+}
+
+function cmdWikiDiscoverHelp() {
+  console.log(`Usage:
+  sdtk-wiki wiki discover --plan --project-path <path>
+
+Purpose:
+  Write a local-only discovery plan from existing SDTK-WIKI gap evidence.
+
+Writes:
+  .sdtk/wiki/reports/discover-plan-YYYY-MM-DD.md
+
+Safety:
+  plan-only.
+  No web fetch, source ingest, compile, apply, prune, delete, archive, query-history, or Ask work.
+  No --web, --fetch, --apply, --compile, or --auto mode is enabled in BK-125.`);
+  return 0;
+}
+
+function parseIngestFlags(args) {
+  const defs = {
+    "project-path": { type: "string" },
+    source: { type: "string" },
+  };
+  return parseWikiFlags(args, defs);
+}
+
+function parsePruneFlags(args) {
+  return parseWikiFlags(args, PRUNE_FLAG_DEFS);
+}
+
+function parseDiscoverFlags(args) {
+  return parseWikiFlags(args, DISCOVER_FLAG_DEFS);
+}
+
+function parseCompileFlags(args) {
+  return parseWikiFlags(args, COMPILE_FLAG_DEFS);
+}
+
+function ensureProjectPath(projectPath) {
+  const resolved = path.resolve(projectPath || process.cwd());
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolved}`);
+  }
+  return resolved;
+}
+
+function cmdWikiIngest(args) {
+  if (hasHelp(args)) return cmdWikiIngestHelp();
+  const { flags } = parseIngestFlags(args);
+  const projectPath = ensureProjectPath(flags["project-path"]);
+  const result = ingestLocalSource({
+    projectPath,
+    sourceArg: flags.source,
+  });
+
+  console.log(`[wiki] Ingested local source: ${result.sourcePath}`);
+  console.log(`[wiki] Raw registry: ${result.registryPath}`);
+  console.log(`[wiki] Provenance events: ${result.eventsPath}`);
+  console.log("[wiki] No compiled pages or graph outputs were regenerated.");
+  return 0;
+}
+
+function cmdWikiPrune(args) {
+  if (hasHelp(args)) return cmdWikiPruneHelp();
+  const { flags } = parsePruneFlags(args);
+  if (!flags["dry-run"]) {
+    throw new ValidationError(
+      'sdtk-wiki wiki prune requires --dry-run. Delete/archive/apply modes are not implemented. No project files were changed.'
+    );
+  }
+  const projectPath = ensureProjectPath(flags["project-path"]);
+  const result = runWikiPruneDryRun({ projectPath });
+
+  console.log(`[wiki] Prune dry-run report: ${result.reportPath}`);
+  console.log(`[wiki] Pages scanned: ${result.pagesScanned}`);
+  console.log(`[wiki] Findings: ${result.findings.length}`);
+  console.log("[wiki] No wiki pages were deleted or archived.");
+  return 0;
+}
+
+function cmdWikiDiscover(args) {
+  if (hasHelp(args)) return cmdWikiDiscoverHelp();
+  const { flags } = parseDiscoverFlags(args);
+  if (!flags.plan) {
+    throw new ValidationError(
+      'sdtk-wiki wiki discover requires --plan. Web/fetch/apply/compile/auto modes are not implemented. No project files were changed.'
+    );
+  }
+  const projectPath = ensureProjectPath(flags["project-path"]);
+  const result = runWikiDiscoverPlan({ projectPath });
+
+  console.log(`[wiki] Discovery plan report: ${result.reportPath}`);
+  console.log(`[wiki] Pages scanned: ${result.pageCount}`);
+  console.log(`[wiki] Plan items: ${result.items.length}`);
+  console.log("[wiki] No sources were fetched, ingested, compiled, applied, pruned, deleted, archived, or persisted.");
+  return 0;
+}
+
+function cmdWikiCompile(args) {
+  if (hasHelp(args)) return cmdWikiCompileHelp();
+  const { flags } = parseCompileFlags(args);
+  if (flags.apply) {
+    throw new ValidationError("--apply is deferred to BK-127. BK-126 supports compile dry-run preview only. No project files were changed.");
+  }
+  if (!flags["dry-run"]) {
+    throw new ValidationError("sdtk-wiki wiki compile requires --dry-run in BK-126. No project files were changed.");
+  }
+  if (!flags.plan) {
+    throw new ValidationError("sdtk-wiki wiki compile requires --plan <path>. No project files were changed.");
+  }
+  const projectPath = ensureProjectPath(flags["project-path"]);
+  const result = runWikiCompileDryRun({ projectPath, planArg: flags.plan });
+
+  console.log(`[wiki] Compile dry-run preview: ${result.reportPath}`);
+  console.log(`[wiki] Operations: ${result.operations.length}`);
+  console.log(`[wiki] Unsupported operations: ${result.unsupportedCount}`);
+  console.log("[wiki] No wiki pages, raw sources, provenance, or atlas compatibility files were modified.");
+  if (result.unsupportedCount > 0) {
+    throw new CliError(
+      `unsupported_operation: ${result.unsupportedCount} operation(s) are blocked. Review the compile dry-run preview report.`,
+      1
+    );
+  }
+  return 0;
+}
+
+function cmdWiki(args) {
+  if (!args || args.length === 0) {
+    return cmdWikiHelp();
+  }
+
+  const [subcommand, ...rest] = args;
+  if (subcommand === "-h" || subcommand === "--help") {
+    return cmdWikiHelp();
+  }
+  if (subcommand === "ingest") {
+    return cmdWikiIngest(rest);
+  }
+  if (subcommand === "prune") {
+    return cmdWikiPrune(rest);
+  }
+  if (subcommand === "discover") {
+    return cmdWikiDiscover(rest);
+  }
+  if (subcommand === "compile") {
+    return cmdWikiCompile(rest);
+  }
+
+  throw new CliError(
+    `Unknown wiki command: "${subcommand}". Run "sdtk-wiki wiki --help". No project files were changed.`,
+    1
+  );
+}
+
+module.exports = {
+  cmdWiki,
+  cmdWikiCompile,
+  cmdWikiCompileHelp,
+  cmdWikiDiscover,
+  cmdWikiDiscoverHelp,
+  cmdWikiHelp,
+  cmdWikiIngest,
+  cmdWikiIngestHelp,
+  cmdWikiPrune,
+  cmdWikiPruneHelp,
+};

package/src/index.js

@@ -0,0 +1,65 @@
+"use strict";
+
+const { cmdAtlas } = require("./commands/atlas");
+const { cmdAsk } = require("./commands/ask");
+const { cmdHelp } = require("./commands/help");
+const { cmdInit } = require("./commands/init");
+const { cmdLint } = require("./commands/lint");
+const { cmdWiki } = require("./commands/wiki");
+const { ValidationError } = require("./lib/errors");
+
+function getVersion() {
+  const pkg = require("../package.json");
+  return pkg.version;
+}
+
+function parseCommand(argv) {
+  if (!argv || argv.length === 0) {
+    return { command: "help", args: [] };
+  }
+
+  const [first, ...rest] = argv;
+  if (first === "-h" || first === "--help") {
+    return { command: "help", args: [] };
+  }
+  if (first === "-v" || first === "--version") {
+    return { command: "version", args: [] };
+  }
+
+  return { command: first, args: rest };
+}
+
+const COMMANDS = new Set(["help", "version", "init", "atlas", "wiki", "ask", "lint"]);
+
+async function run(argv) {
+  const { command, args } = parseCommand(argv);
+
+  if (!COMMANDS.has(command)) {
+    throw new ValidationError(
+      `Unknown command: "${command}". Run "sdtk-wiki --help" for available commands.`
+    );
+  }
+
+  switch (command) {
+    case "help":
+      return cmdHelp();
+    case "version":
+      console.log(`sdtk-wiki-kit ${getVersion()}`);
+      return 0;
+    case "init":
+      return cmdInit(args);
+    case "atlas":
+      return cmdAtlas(args);
+    case "wiki":
+      return cmdWiki(args);
+    case "ask":
+      return cmdAsk(args);
+    case "lint":
+      return cmdLint(args);
+  }
+}
+
+module.exports = {
+  parseCommand,
+  run,
+};

package/src/lib/args.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const { ValidationError } = require("./errors");
+
+function parseFlags(argv, defs) {
+  const flags = {};
+  const positional = [];
+  const aliasMap = {};
+
+  for (const [name, def] of Object.entries(defs)) {
+    if (def.alias) aliasMap[def.alias] = name;
+    if (def.type === "boolean") flags[name] = false;
+    else flags[name] = undefined;
+  }
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    if (!arg.startsWith("-")) {
+      positional.push(arg);
+      i++;
+      continue;
+    }
+
+    let key;
+    let inlineValue;
+
+    if (arg.includes("=")) {
+      const eqIdx = arg.indexOf("=");
+      key = arg.slice(0, eqIdx);
+      inlineValue = arg.slice(eqIdx + 1);
+    } else {
+      key = arg;
+    }
+
+    const stripped = key.replace(/^-{1,2}/, "");
+    const resolved = aliasMap[stripped] || stripped;
+
+    if (!(resolved in defs)) {
+      throw new ValidationError(`Unknown flag: ${key}`);
+    }
+
+    const def = defs[resolved];
+    if (def.type === "boolean") {
+      flags[resolved] = true;
+      i++;
+      continue;
+    }
+
+    let value = inlineValue;
+    if (value === undefined) {
+      i++;
+      if (i >= argv.length) {
+        throw new ValidationError(`Flag ${key} requires a value.`);
+      }
+      value = argv[i];
+    }
+    flags[resolved] = value;
+    i++;
+  }
+
+  return { flags, positional };
+}
+
+module.exports = {
+  parseFlags,
+};

package/src/lib/browser-open.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const { execFile } = require("child_process");
+
+function openBrowser(url) {
+  return new Promise((resolve) => {
+    let cmd;
+    let args;
+
+    if (process.platform === "win32") {
+      cmd = "cmd";
+      args = ["/c", "start", "", url];
+    } else if (process.platform === "darwin") {
+      cmd = "open";
+      args = [url];
+    } else {
+      cmd = "xdg-open";
+      args = [url];
+    }
+
+    execFile(cmd, args, { windowsHide: true }, (err) => {
+      if (err) {
+        console.error(`[wiki] Warning: could not open browser: ${err.message}`);
+      }
+      resolve();
+    });
+  });
+}
+
+module.exports = {
+  openBrowser,
+};

package/src/lib/errors.js

@@ -0,0 +1,29 @@
+"use strict";
+
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+
+class ValidationError extends CliError {
+  constructor(message) {
+    super(message, 1);
+    this.name = "ValidationError";
+  }
+}
+
+class DependencyError extends CliError {
+  constructor(message) {
+    super(message, 2);
+    this.name = "DependencyError";
+  }
+}
+
+module.exports = {
+  CliError,
+  DependencyError,
+  ValidationError,
+};