sdtk-brain-kit 0.1.0

package/src/commands/operations.js

@@ -0,0 +1,357 @@
+"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-brain ${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-BRAIN Ingest
+
+Usage:
+  sdtk-brain ingest <source-root> [--project-path <path>]
+  sdtk-brain ingest --source-root <path> [--project-path <path>]
+
+Purpose:
+  Run local semantic extraction over Markdown and supported JSON source records and write a report under .brain/reports.
+
+Scope:
+  This pipeline researches EXTERNAL tool/repo knowledge referenced in your sources
+  (GitHub repos, comparisons, syntheses) — it is not a system-documentation extractor.
+  To index and query your own project docs, use "sdtk-brain init" / "sdtk-brain atlas build"
+  and then query/search/ask.
+
+Safety:
+  Local sources only.
+  No source mutation, local wiki page writes, graph rebuild, web fetch, Ask, raw/provenance mutation, or .brain-legacy-unused mutation.
+
+Next:
+  sdtk-brain compile --mode safe`);
+  return 0;
+}
+
+function cmdCompileHelp() {
+  console.log(`SDTK-BRAIN Compile
+
+Usage:
+  sdtk-brain compile --mode safe [--project-path <path>]
+  sdtk-brain 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.
+
+Scope:
+  Compiles the external tool/repo knowledge extracted by ingest into wiki/ pages
+  (sources, entities, comparisons, syntheses). Your own project docs are indexed by
+  "sdtk-brain atlas build" instead — no compile step needed there.
+
+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 .brain-legacy-unused mutation.`);
+  return 0;
+}
+
+function cmdQueryHelp() {
+  console.log(`SDTK-BRAIN Query
+
+Usage:
+  sdtk-brain query [--project-path <path>] [--json] [--limit <n>] "<query>"
+
+Purpose:
+  Deterministically search generated local wiki Markdown pages.
+
+Behavior:
+  Local search only.
+  No wiki.ask entitlement, LLM/RAG runtime, query history, or project mutation.
+  Use sdtk-brain ask for premium grounded Q&A when wiki.ask preconditions are available.`);
+  return 0;
+}
+
+function cmdDiscoverHelp() {
+  console.log(`SDTK-BRAIN Discover
+
+Usage:
+  sdtk-brain 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 .brain-legacy-unused mutation.`);
+  return 0;
+}
+
+function cmdMaintainHelp() {
+  console.log(`SDTK-BRAIN Maintain
+
+Usage:
+  sdtk-brain 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 .brain-legacy-unused 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-brain ingest accepts one source root. Quote paths that contain spaces. No project files were changed.");
+  }
+  throw new ValidationError("sdtk-brain 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(`[brain] Semantic extraction report: ${result.reportPath}`);
+  console.log(`[brain] Sources scanned: ${extraction.source_counts.scanned}`);
+  console.log(`[brain] Sources indexed: ${extraction.source_counts.indexed}`);
+  console.log(`[brain] Tool candidates: ${extraction.tool_entities.length}`);
+  console.log(`[brain] Concept candidates: ${extraction.concepts.length}`);
+  console.log(`[brain] Quality findings: ${extraction.source_quality_findings.length}`);
+  console.log("[brain] No source files, local wiki pages, raw/provenance state, graph outputs, or atlas compatibility files were modified.");
+  console.log("[brain] Next: sdtk-brain compile --mode safe");
+  return 0;
+}
+
+function runCompileDryRunFromLatestExtraction(projectPath) {
+  const extraction = latestExtraction(projectPath);
+  if (!extraction) {
+    throw new ValidationError(
+      "No semantic extraction report found. Run \"sdtk-brain 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-brain 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(`[brain] Compile dry-run preview: ${result.reportPath}`);
+    console.log(`[brain] Compile apply JSON sidecar: ${result.applyPlanPath}`);
+    console.log(`[brain] Operations: ${result.operations.length}`);
+    console.log(`[brain] Unsupported operations: ${result.unsupportedCount}`);
+    console.log("[brain] No wiki pages, raw sources, provenance, source files, or atlas compatibility files were modified.");
+    console.log("[brain] Next: sdtk-brain 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(`[brain] Compile apply plan: ${result.planPath}`);
+  if (sidecar.createdFreshSidecar) {
+    console.log(`[brain] Refreshed compile dry-run preview: ${sidecar.dryRun.reportPath}`);
+  }
+  console.log(`[brain] Created files: ${result.created.length}`);
+  console.log(`[brain] Unchanged files: ${result.unchanged.length}`);
+  console.log(`[brain] Scaffold created/skipped: ${result.scaffoldCreated.length}/${result.scaffoldSkipped.length}`);
+  console.log(`[brain] Source-quality warnings: ${result.sourceQualityWarningCount}`);
+  console.log("[brain] Canonical local wiki output is <project>/wiki; .brain remains internal state. No source files, raw sources, provenance descriptors, or atlas compatibility files were modified.");
+  console.log("[brain] Next: sdtk-brain 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("[brain] 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-brain 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(`[brain] Discovery plan report: ${result.reportPath}`);
+  console.log(`[brain] Pages scanned: ${result.pageCount}`);
+  console.log(`[brain] Plan items: ${result.items.length}`);
+  console.log("[brain] 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(`[brain] Maintain mode: safe`);
+  console.log(`[brain] Lint report: ${lint.reportPath}`);
+  console.log(`[brain] Discovery plan report: ${discover.reportPath}`);
+  if (compile) {
+    console.log(`[brain] Compile dry-run preview: ${compile.reportPath}`);
+    console.log(`[brain] Compile apply JSON sidecar: ${compile.applyPlanPath}`);
+  } else {
+    console.log("[brain] Compile preview skipped: no semantic extraction report found. Run \"sdtk-brain ingest <source-root>\".");
+  }
+  console.log("[brain] 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,94 @@
+"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-BRAIN Local Search
+
+Usage:
+  sdtk-brain search --project-path <path> "multi-agent"
+  sdtk-brain search --project-path <path> --json --limit 10 "Claude Code"
+
+Purpose:
+  Deterministically search generated local wiki Markdown pages.
+
+Inputs:
+  Union of the atlas pages (.brain/pages/**/*.md, built by "sdtk-brain atlas build")
+  and wiki/**/*.md, falling back to .brain/personal-brain/**/*.md for legacy workspaces.
+  Duplicate coverage of the same source is de-duplicated; the atlas version wins.
+  Each match reports its store (atlas | wiki).
+
+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}`,
+    `Wiki content: ${result.wikiContentPath}`,
+    `Wiki content mode: ${result.wikiContentMode}`,
+    `Scanned files: ${result.scannedFiles}`,
+    `Matches: ${result.totalMatches}`,
+    "",
+  ];
+
+  if (result.matches.length === 0) {
+    lines.push("No local wiki matches found.");
+  } else {
+    result.matches.forEach((match, index) => {
+      lines.push(`${index + 1}. ${match.path}`);
+      lines.push(`   store: ${match.store}`);
+      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,
+};

package/src/commands/status.js

@@ -0,0 +1,56 @@
+"use strict";
+
+// `sdtk-brain status` — truthful vault status, read-only.
+
+const fs = require("fs");
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { resolveProjectPath, getWikiWorkspacePath, getCanonicalWikiPath, getWikiGraphPath } = require("../lib/wiki-paths");
+
+const STATUS_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  vault: { type: "string" },
+};
+
+function countFiles(root, ext) {
+  if (!fs.existsSync(root)) {
+    return 0;
+  }
+  let count = 0;
+  const stack = [root];
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const p = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(p);
+      } else if (entry.isFile() && (!ext || p.endsWith(ext))) {
+        count += 1;
+      }
+    }
+  }
+  return count;
+}
+
+function cmdStatus(args) {
+  const { flags } = parseFlags(args || [], STATUS_FLAG_DEFS);
+  if (flags.help) {
+    console.log("Usage: sdtk-brain status [--vault <path>] — read-only vault status.");
+    return 0;
+  }
+  const vault = resolveProjectPath(flags.vault || process.cwd());
+  const wiki = getCanonicalWikiPath(vault);
+  const raw = path.join(vault, "raw");
+  const workspace = getWikiWorkspacePath(vault);
+  const viewer = path.join(getWikiGraphPath(vault), "viewer.html");
+
+  console.log(`[brain] Vault: ${vault}`);
+  console.log(`  Contract:  ${fs.existsSync(path.join(vault, "CLAUDE.md")) ? "CLAUDE.md present" : "CLAUDE.md MISSING — run sdtk-brain init"}`);
+  console.log(`  raw/:      ${countFiles(raw)} file(s)`);
+  console.log(`  wiki/:     ${countFiles(wiki, ".md")} page(s)`);
+  console.log(`  reports:   ${countFiles(path.join(workspace, "reports"))} report(s) under .brain/reports`);
+  console.log(`  viewer:    ${fs.existsSync(viewer) ? viewer : "not built yet — run sdtk-brain open"}`);
+  return 0;
+}
+
+module.exports = { cmdStatus };

package/src/lib/args.js

@@ -0,0 +1,76 @@
+"use strict";
+
+const { ValidationError } = require("./errors");
+
+function parseFlags(argv, defs) {
+  // Brain-wide convention: every command that takes --project-path also
+  // accepts --vault as a friendlier alias (a vault IS the project root here).
+  if (defs && defs["project-path"] && !defs.vault) {
+    defs = { ...defs, vault: { type: "string" } };
+  }
+  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++;
+  }
+
+  if (flags.vault !== undefined && flags["project-path"] === undefined) {
+    flags["project-path"] = flags.vault;
+  }
+  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(`[brain] 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,
+};