sdtk-wiki-kit 0.1.0 → 0.1.2

package/src/commands/help.js

@@ -7,6 +7,11 @@ Usage:
   sdtk-wiki --help
   sdtk-wiki --version
   sdtk-wiki init --help
+  sdtk-wiki ingest --help
+  sdtk-wiki compile --help
+  sdtk-wiki query --help
+  sdtk-wiki discover --help
+  sdtk-wiki maintain --help
   sdtk-wiki atlas build --help
   sdtk-wiki atlas open --help
   sdtk-wiki atlas watch --help
@@ -16,10 +21,25 @@ Usage:
   sdtk-wiki wiki discover --help
   sdtk-wiki wiki compile --help
   sdtk-wiki ask --help
+  sdtk-wiki search --help
   sdtk-wiki lint --help
 
+Simple personal-brain workflow:
+  sdtk-wiki init --no-open
+  sdtk-wiki ingest <source-root>
+  sdtk-wiki compile --mode safe [--apply]
+  sdtk-wiki query "<query>"
+  sdtk-wiki lint
+  sdtk-wiki discover --plan
+  sdtk-wiki maintain --mode safe
+
 R1 command model:
   init                 Initialize the SDTK-WIKI workspace.
+  ingest               Run local semantic extraction without handling timestamped JSON.
+  compile              Run safe personal-brain compile preview, optionally apply.
+  query                Search generated personal-brain pages locally without premium Ask.
+  discover             Write a local-only discovery plan from WIKI gap evidence.
+  maintain             Run safe lint, discover, and compile-preview maintenance reports.
   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.
@@ -27,10 +47,17 @@ R1 command model:
   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.
+  wiki compile         Preview or explicitly apply local personal-brain compile plans.
   ask                  Ask grounded questions over the built SDTK-WIKI graph.
+  search               Search generated personal-brain pages locally without premium Ask.
   lint                 Write a report-first, non-destructive wiki lint report.
 
+Advanced/audit workflow:
+  sdtk-wiki wiki extract --source-root <source-root> --dry-run
+  sdtk-wiki wiki compile --plan <extract-json> --dry-run
+  sdtk-wiki wiki compile --plan <apply-json> --apply --yes
+  sdtk-wiki search "<query>"
+
 Workspace paths:
   .sdtk/wiki           New SDTK-WIKI workspace target.
   .sdtk/wiki/graph     New SDTK-WIKI graph output target.
@@ -50,15 +77,23 @@ Premium Ask:
                        Requires .sdtk/wiki/graph plus local entitlement/runtime preconditions.
                        Query history, discover, compile, and cleanup automation are not enabled in R1.
 
+Local Search:
+  sdtk-wiki query      Beginner-friendly local deterministic search over .sdtk/wiki/personal-brain.
+  sdtk-wiki search     Deterministic, read-only local search over .sdtk/wiki/personal-brain.
+                       Does not require wiki.ask entitlement and does not perform LLM/RAG behavior.
+
 Maintenance:
+  sdtk-wiki discover --plan is a top-level alias for local-only discovery planning.
+  sdtk-wiki maintain --mode safe runs report-first lint/discover/compile-preview checks without apply.
   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.`);
+  sdtk-wiki wiki compile --dry-run writes a markdown preview plus JSON sidecar under .sdtk/wiki/reports.
+  sdtk-wiki wiki compile --apply --yes consumes only the JSON sidecar and writes create-only personal-brain pages.
+  It never rewrites pages, mutates raw/provenance files, or mutates .sdtk/atlas.`);
   return 0;
 }
 

package/src/commands/lint.js

@@ -13,13 +13,14 @@ function cmdLintHelp() {
   sdtk-wiki lint [--project-path <path>]
 
 Purpose:
-  Run report-first, non-destructive lint checks over canonical .sdtk/wiki content.
+  Run report-first, non-destructive lint checks over canonical .sdtk/wiki content and local source-quality evidence.
 
 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.
+  Source-quality checks report mojibake-like text, missing source URLs, weak titles, duplicate repo/source candidates, low-confidence extraction, and raw/graph/provenance coverage mismatch.
   Completed lint runs exit 0 even when findings exist.
   Missing workspace or fatal report-write failures exit non-zero.
 

package/src/commands/operations.js

@@ -0,0 +1,345 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { CliError, ValidationError } = require("../lib/errors");
+const { runWikiCompileApply, runWikiCompileDryRun } = require("../lib/wiki-compile");
+const { runWikiDiscoverPlan } = require("../lib/wiki-discover");
+const { runWikiExtractDryRun } = require("../lib/wiki-extract");
+const { runWikiLint } = require("../lib/wiki-lint");
+const { runWikiSearch } = require("../lib/wiki-search");
+const { getWikiReportsPath, resolveProjectPath } = require("../lib/wiki-paths");
+const { printHumanResult } = require("./search");
+
+const INGEST_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  "source-root": { type: "string" },
+};
+
+const COMPILE_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  mode: { type: "string" },
+  apply: { type: "boolean" },
+};
+
+const QUERY_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  json: { type: "boolean" },
+  limit: { type: "string" },
+};
+
+const DISCOVER_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  plan: { type: "boolean" },
+};
+
+const MAINTAIN_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  mode: { type: "string" },
+};
+
+function ensureProjectPath(projectPath) {
+  const resolved = resolveProjectPath(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 ensureSafeMode(mode, commandName) {
+  const resolvedMode = mode || "safe";
+  if (resolvedMode !== "safe") {
+    throw new ValidationError(
+      `sdtk-wiki ${commandName} supports only --mode safe in R1. Auto mode is deferred. No project files were changed.`
+    );
+  }
+  return resolvedMode;
+}
+
+function findLatestReport(projectPath, pattern) {
+  const reportsPath = getWikiReportsPath(projectPath);
+  if (!fs.existsSync(reportsPath) || !fs.statSync(reportsPath).isDirectory()) {
+    return null;
+  }
+  const matcher = new RegExp(`^${pattern}$`);
+  const files = fs.readdirSync(reportsPath)
+    .filter((name) => matcher.test(name))
+    .map((name) => {
+      const filePath = path.join(reportsPath, name);
+      return { filePath, mtimeMs: fs.statSync(filePath).mtimeMs };
+    })
+    .sort((a, b) => {
+      if (b.mtimeMs !== a.mtimeMs) return b.mtimeMs - a.mtimeMs;
+      return b.filePath.localeCompare(a.filePath);
+    });
+  return files.length > 0 ? files[0] : null;
+}
+
+function latestExtraction(projectPath) {
+  return findLatestReport(projectPath, "semantic-extraction-dry-run-.*\\.json");
+}
+
+function latestApplyPlan(projectPath) {
+  return findLatestReport(projectPath, "compile-apply-plan-.*\\.json");
+}
+
+function cmdIngestHelp() {
+  console.log(`SDTK-WIKI Ingest
+
+Usage:
+  sdtk-wiki ingest <source-root> [--project-path <path>]
+  sdtk-wiki ingest --source-root <path> [--project-path <path>]
+
+Purpose:
+  Run local semantic extraction over a Markdown source root and write a report under .sdtk/wiki/reports.
+
+Safety:
+  Local sources only.
+  No source mutation, personal-brain page writes, graph rebuild, web fetch, Ask, raw/provenance mutation, or .sdtk/atlas mutation.
+
+Next:
+  sdtk-wiki compile --mode safe`);
+  return 0;
+}
+
+function cmdCompileHelp() {
+  console.log(`SDTK-WIKI Compile
+
+Usage:
+  sdtk-wiki compile --mode safe [--project-path <path>]
+  sdtk-wiki compile --mode safe --apply [--project-path <path>]
+
+Purpose:
+  Use the latest semantic extraction report to write a compile preview and JSON sidecar, then optionally apply the sidecar.
+
+Safety:
+  Safe mode is the only R1 mode.
+  --apply still uses the existing JSON sidecar contract.
+  No delete, archive, rewrite, raw/provenance mutation, source mutation, web fetch, Ask, or .sdtk/atlas mutation.`);
+  return 0;
+}
+
+function cmdQueryHelp() {
+  console.log(`SDTK-WIKI Query
+
+Usage:
+  sdtk-wiki query [--project-path <path>] [--json] [--limit <n>] "<query>"
+
+Purpose:
+  Deterministically search generated personal-brain Markdown pages.
+
+Behavior:
+  Local search only.
+  No wiki.ask entitlement, LLM/RAG runtime, query history, or project mutation.
+  Use sdtk-wiki ask for premium grounded Q&A when wiki.ask preconditions are available.`);
+  return 0;
+}
+
+function cmdDiscoverHelp() {
+  console.log(`SDTK-WIKI Discover
+
+Usage:
+  sdtk-wiki discover --plan [--project-path <path>]
+
+Purpose:
+  Write a local-only discovery plan from existing wiki gap evidence.
+
+Safety:
+  Plan-only. No web fetch, source ingest, compile, apply, prune, delete, archive, query history, Ask, or .sdtk/atlas mutation.`);
+  return 0;
+}
+
+function cmdMaintainHelp() {
+  console.log(`SDTK-WIKI Maintain
+
+Usage:
+  sdtk-wiki maintain --mode safe [--project-path <path>]
+
+Purpose:
+  Run a report-first maintenance cycle: lint, discover plan, and compile preview when an extraction report exists.
+
+Safety:
+  Safe mode only.
+  No apply, delete, archive, source mutation, web fetch, Ask, query history, or .sdtk/atlas mutation.`);
+  return 0;
+}
+
+function resolveSourceRoot(flags, positional) {
+  if (flags["source-root"]) return flags["source-root"];
+  if (positional.length === 1) return positional[0];
+  if (positional.length > 1) {
+    throw new ValidationError("sdtk-wiki ingest accepts one source root. Quote paths that contain spaces. No project files were changed.");
+  }
+  throw new ValidationError("sdtk-wiki ingest requires <source-root> or --source-root <path>. No project files were changed.");
+}
+
+function cmdIngest(args) {
+  const { flags, positional } = parseFlags(args || [], INGEST_FLAG_DEFS);
+  if (flags.help) return cmdIngestHelp();
+  const projectPath = ensureProjectPath(flags["project-path"]);
+  const result = runWikiExtractDryRun({
+    projectPath,
+    sourceRootArg: resolveSourceRoot(flags, positional),
+  });
+  const extraction = result.extraction;
+
+  console.log(`[wiki] Semantic extraction report: ${result.reportPath}`);
+  console.log(`[wiki] Sources scanned: ${extraction.source_counts.scanned}`);
+  console.log(`[wiki] Sources indexed: ${extraction.source_counts.indexed}`);
+  console.log(`[wiki] Tool candidates: ${extraction.tool_entities.length}`);
+  console.log(`[wiki] Concept candidates: ${extraction.concepts.length}`);
+  console.log(`[wiki] Quality findings: ${extraction.source_quality_findings.length}`);
+  console.log("[wiki] No source files, personal-brain pages, raw/provenance state, graph outputs, or atlas compatibility files were modified.");
+  console.log("[wiki] Next: sdtk-wiki compile --mode safe");
+  return 0;
+}
+
+function runCompileDryRunFromLatestExtraction(projectPath) {
+  const extraction = latestExtraction(projectPath);
+  if (!extraction) {
+    throw new ValidationError(
+      "No semantic extraction report found. Run \"sdtk-wiki ingest <source-root>\" first. No project files were changed."
+    );
+  }
+  return runWikiCompileDryRun({ projectPath, planArg: extraction.filePath });
+}
+
+function ensureApplySidecar(projectPath) {
+  const extraction = latestExtraction(projectPath);
+  const sidecar = latestApplyPlan(projectPath);
+  if (!sidecar && !extraction) {
+    throw new ValidationError(
+      "No compile apply sidecar or semantic extraction report found. Run \"sdtk-wiki ingest <source-root>\" first. No project files were changed."
+    );
+  }
+  if (!sidecar || (extraction && extraction.mtimeMs > sidecar.mtimeMs)) {
+    const dryRun = runCompileDryRunFromLatestExtraction(projectPath);
+    return {
+      sidecarPath: dryRun.applyPlanPath,
+      dryRun,
+      createdFreshSidecar: true,
+    };
+  }
+  return {
+    sidecarPath: sidecar.filePath,
+    dryRun: null,
+    createdFreshSidecar: false,
+  };
+}
+
+function cmdCompile(args) {
+  const { flags } = parseFlags(args || [], COMPILE_FLAG_DEFS);
+  if (flags.help) return cmdCompileHelp();
+  ensureSafeMode(flags.mode, "compile");
+  const projectPath = ensureProjectPath(flags["project-path"]);
+
+  if (!flags.apply) {
+    const result = runCompileDryRunFromLatestExtraction(projectPath);
+    console.log(`[wiki] Compile dry-run preview: ${result.reportPath}`);
+    console.log(`[wiki] Compile apply JSON sidecar: ${result.applyPlanPath}`);
+    console.log(`[wiki] Operations: ${result.operations.length}`);
+    console.log(`[wiki] Unsupported operations: ${result.unsupportedCount}`);
+    console.log("[wiki] No wiki pages, raw sources, provenance, source files, or atlas compatibility files were modified.");
+    console.log("[wiki] Next: sdtk-wiki compile --mode safe --apply");
+    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;
+  }
+
+  const sidecar = ensureApplySidecar(projectPath);
+  const result = runWikiCompileApply({ projectPath, planArg: sidecar.sidecarPath });
+  console.log(`[wiki] Compile apply plan: ${result.planPath}`);
+  if (sidecar.createdFreshSidecar) {
+    console.log(`[wiki] Refreshed compile dry-run preview: ${sidecar.dryRun.reportPath}`);
+  }
+  console.log(`[wiki] Created files: ${result.created.length}`);
+  console.log(`[wiki] Unchanged files: ${result.unchanged.length}`);
+  console.log(`[wiki] Source-quality warnings: ${result.sourceQualityWarningCount}`);
+  console.log("[wiki] No source files, raw sources, provenance descriptors, or atlas compatibility files were modified.");
+  console.log("[wiki] Next: sdtk-wiki query \"multi-agent\"");
+  return 0;
+}
+
+function cmdQuery(args) {
+  const { flags, positional } = parseFlags(args || [], QUERY_FLAG_DEFS);
+  if (flags.help) return cmdQueryHelp();
+  const query = positional.join(" ");
+  const result = runWikiSearch({
+    projectPath: flags["project-path"],
+    query,
+    limit: flags.limit,
+  });
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log("[wiki] Query mode: local deterministic search. Premium Ask is not used.");
+    printHumanResult(result);
+  }
+  return 0;
+}
+
+function cmdDiscover(args) {
+  const { flags } = parseFlags(args || [], DISCOVER_FLAG_DEFS);
+  if (flags.help) return cmdDiscoverHelp();
+  if (!flags.plan) {
+    throw new ValidationError("sdtk-wiki discover requires --plan. No web/fetch/apply/auto behavior is enabled. 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 cmdMaintain(args) {
+  const { flags } = parseFlags(args || [], MAINTAIN_FLAG_DEFS);
+  if (flags.help) return cmdMaintainHelp();
+  ensureSafeMode(flags.mode, "maintain");
+  const projectPath = ensureProjectPath(flags["project-path"]);
+
+  const lint = runWikiLint({ projectPath });
+  const discover = runWikiDiscoverPlan({ projectPath });
+  const extraction = latestExtraction(projectPath);
+  let compile = null;
+  if (extraction) {
+    compile = runWikiCompileDryRun({ projectPath, planArg: extraction.filePath });
+  }
+
+  console.log(`[wiki] Maintain mode: safe`);
+  console.log(`[wiki] Lint report: ${lint.reportPath}`);
+  console.log(`[wiki] Discovery plan report: ${discover.reportPath}`);
+  if (compile) {
+    console.log(`[wiki] Compile dry-run preview: ${compile.reportPath}`);
+    console.log(`[wiki] Compile apply JSON sidecar: ${compile.applyPlanPath}`);
+  } else {
+    console.log("[wiki] Compile preview skipped: no semantic extraction report found. Run \"sdtk-wiki ingest <source-root>\".");
+  }
+  console.log("[wiki] No apply, source mutation, web fetch, Ask, query history, delete/archive, or atlas compatibility mutation was performed.");
+  return 0;
+}
+
+module.exports = {
+  cmdCompile,
+  cmdCompileHelp,
+  cmdDiscover,
+  cmdDiscoverHelp,
+  cmdIngest,
+  cmdIngestHelp,
+  cmdMaintain,
+  cmdMaintainHelp,
+  cmdQuery,
+  cmdQueryHelp,
+};

package/src/commands/search.js

@@ -0,0 +1,89 @@
+"use strict";
+
+const { parseFlags } = require("../lib/args");
+const { runWikiSearch } = require("../lib/wiki-search");
+
+const SEARCH_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  json: { type: "boolean" },
+  limit: { type: "string" },
+};
+
+function parseSearchFlags(args) {
+  return parseFlags(args || [], SEARCH_FLAG_DEFS);
+}
+
+function printSearchHelp() {
+  console.log(`SDTK-WIKI Local Search
+
+Usage:
+  sdtk-wiki search --project-path <path> "multi-agent"
+  sdtk-wiki search --project-path <path> --json --limit 10 "Claude Code"
+
+Purpose:
+  Deterministically search generated personal-brain Markdown pages.
+
+Inputs:
+  .sdtk/wiki/personal-brain/**/*.md
+
+Behavior:
+  Read-only and non-premium.
+  No wiki.ask entitlement is required.
+  No LLM, RAG, web search, query history, compile/apply, prune, or project mutation is performed.`);
+  return 0;
+}
+
+function printHumanResult(result) {
+  const lines = [
+    `Query: ${result.query}`,
+    `Search mode: ${result.searchMode}`,
+    `Personal brain: ${result.personalBrainPath}`,
+    `Scanned files: ${result.scannedFiles}`,
+    `Matches: ${result.totalMatches}`,
+    "",
+  ];
+
+  if (result.matches.length === 0) {
+    lines.push("No local personal-brain matches found.");
+  } else {
+    result.matches.forEach((match, index) => {
+      lines.push(`${index + 1}. ${match.path}`);
+      lines.push(`   title: ${match.title}`);
+      lines.push(`   score: ${match.score}`);
+      lines.push(`   why: ${match.why}`);
+      lines.push(`   snippet: ${match.snippet}`);
+      lines.push("");
+    });
+  }
+
+  lines.push("No entitlement, LLM/RAG runtime, query history, or project mutation was used.");
+  console.log(lines.join("\n").trimEnd());
+}
+
+function cmdSearch(args) {
+  const { flags, positional } = parseSearchFlags(args || []);
+  if (flags.help) {
+    return printSearchHelp();
+  }
+  const query = positional.join(" ");
+  const result = runWikiSearch({
+    projectPath: flags["project-path"],
+    query,
+    limit: flags.limit,
+  });
+
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHumanResult(result);
+  }
+  return 0;
+}
+
+module.exports = {
+  cmdSearch,
+  parseSearchFlags,
+  printHumanResult,
+  printSearchHelp,
+};