sdtk-brain-kit 0.1.0

package/bin/sdtk-brain.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+"use strict";
+
+// `sdtk-brain` — standalone second-brain vault CLI (BK-319).
+// A vault is a user-chosen folder: raw/ (immutable sources) -> wiki/ (compiled
+// knowledge), .brain/ (machine state), workspace/ (scratch). The agent reading
+// the vault per its CLAUDE.md contract is the knowledge engine — there is
+// deliberately no `ask` verb, no LLM, no network, no SDTK skill dependency.
+
+function helpText() {
+  return [
+    "sdtk-brain — local-first second-brain vault CLI",
+    "",
+    "Usage:",
+    "  sdtk-brain init [--vault <path>]        Scaffold a vault (raw/ + wiki/ + workspace/ + CLAUDE.md)",
+    "  sdtk-brain ingest <file|dir>            Semantic extraction over raw sources (report-first)",
+    "  sdtk-brain compile --mode safe [--apply]  Compile extraction into wiki/ knowledge pages",
+    "  sdtk-brain search [--json] \"<query>\"     Deterministic search over the vault wiki",
+    "  sdtk-brain lint                         Report-first wiki hygiene (orphans, links, stale)",
+    "  sdtk-brain maintain --mode safe         Lint + discover + compile preview in one pass",
+    "  sdtk-brain discover --plan              Gap-analysis plan from wiki evidence",
+    "  sdtk-brain enrich --source github --mode review  Review-only external repo metadata report",
+    "  sdtk-brain open [--no-open]             Build + open the docs/graph viewer over the vault",
+    "  sdtk-brain status                       Vault status",
+    "  sdtk-brain --help | --version",
+    "",
+    "The vault's own CLAUDE.md is the agent operating contract: open the vault",
+    "in your agent (or Obsidian) and ask questions there — the agent reads the",
+    "wiki and synthesizes; this CLI only provides the deterministic rails.",
+    "",
+    "Everything is local: no LLM, no network, no telemetry, no entitlement.",
+  ].join("\n");
+}
+
+function main(argv) {
+  const command = argv[0];
+
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    console.log(helpText());
+    return 0;
+  }
+  if (command === "--version" || command === "-v" || command === "version") {
+    // eslint-disable-next-line global-require
+    console.log(`sdtk-brain-kit ${require("../package.json").version}`);
+    return 0;
+  }
+
+  /* eslint-disable global-require */
+  try {
+    if (command === "init") {
+      return require("../src/commands/init").cmdInit(argv.slice(1));
+    }
+    if (command === "status") {
+      return require("../src/commands/status").cmdStatus(argv.slice(1));
+    }
+    if (command === "open") {
+      require("../src/commands/open").cmdOpen(argv.slice(1)).then((code) => {
+        process.exitCode = code;
+      }).catch((err) => {
+        console.error(`sdtk-brain open: ${err.message}`);
+        process.exitCode = typeof err.exitCode === "number" ? err.exitCode : 4;
+      });
+      return 0;
+    }
+    if (command === "search") {
+      return require("../src/commands/search").cmdSearch(argv.slice(1));
+    }
+    if (command === "enrich") {
+      return require("../src/commands/enrich").cmdEnrich(argv.slice(1));
+    }
+    const ops = require("../src/commands/operations");
+    if (command === "ingest") return ops.cmdIngest(argv.slice(1));
+    if (command === "compile") return ops.cmdCompile(argv.slice(1));
+    if (command === "lint") return require("../src/commands/lint").cmdLint(argv.slice(1));
+    if (command === "maintain") return ops.cmdMaintain(argv.slice(1));
+    if (command === "discover") return ops.cmdDiscover(argv.slice(1));
+  } catch (err) {
+    console.error(`sdtk-brain: ${err.message}`);
+    return typeof err.exitCode === "number" ? err.exitCode : 4;
+  }
+  /* eslint-enable global-require */
+
+  console.error(`sdtk-brain: unknown command '${command}'.`);
+  console.error("Run `sdtk-brain --help` for usage.");
+  return 2;
+}
+
+process.exitCode = main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "sdtk-brain-kit",
+  "version": "0.1.0",
+  "description": "Standalone local-first second-brain vault CLI: immutable raw/ sources compiled into a markdown wiki/ knowledge layer, maintained by rails (ingest, compile, lint, search, graph viewer) while your agent is the knowledge engine.",
+  "type": "commonjs",
+  "bin": {
+    "sdtk-brain": "bin/sdtk-brain.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "templates/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "sync:shared": "node scripts/sync-shared-assets.js",
+    "test": "node scripts/brain-smoke.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/brain-smoke.test.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+// Offline smoke: init -> ingest -> compile --apply -> search on a temp vault.
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const BIN = path.resolve(__dirname, "..", "bin", "sdtk-brain.js");
+const vault = fs.mkdtempSync(path.join(os.tmpdir(), "brain-smoke-"));
+const run = (...args) => execFileSync(process.execPath, [BIN, ...args], { cwd: vault, encoding: "utf8" });
+run("init");
+fs.writeFileSync(path.join(vault, "raw", "inbox", "note.md"),
+  "# Note\n\nsmoke-token here.\n\nhttps://github.com/example/smoke-tool\n");
+run("ingest", path.join(vault, "raw", "inbox"));
+run("compile", "--mode", "safe", "--apply");
+const out = run("search", "--json", "smoke-token");
+const data = JSON.parse(out);
+if (!data.matches.length) { console.error("smoke FAIL: no match"); process.exit(1); }
+console.log("brain smoke: PASS");

package/scripts/sync-shared-assets.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+"use strict";
+// L-5 shared-infra sync: copy the canonical builder/scorer/viewer from
+// sdtk-wiki (source of truth) into this kit. The repo test
+// tests/test_sdtk_brain_cli.py::test_shared_assets_are_byte_identical_with_wiki
+// is the drift guard — run this script whenever it goes red.
+const fs = require("fs");
+const path = require("path");
+const HERE = path.resolve(__dirname, "..");
+const WIKI = path.resolve(HERE, "..", "..", "..", "sdtk-wiki", "distribution", "sdtk-wiki-kit");
+const SHARED = [
+  "src/lib/wiki-build.js",
+  "src/lib/wiki-score.js",
+  "assets/atlas/doc_atlas_viewer_template.html",
+  "assets/atlas/vendor/mermaid.min.js",
+];
+for (const rel of SHARED) {
+  const src = path.join(WIKI, rel);
+  const dest = path.join(HERE, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  console.log(`[sync] ${rel}`);
+}
+console.log("[sync] shared assets synced from sdtk-wiki (canonical).");

package/src/commands/enrich.js

@@ -0,0 +1,55 @@
+"use strict";
+
+const { parseFlags } = require("../lib/args");
+const { ValidationError } = require("../lib/errors");
+const { runWikiGithubEnrichmentReview } = require("../lib/wiki-enrich");
+
+const ENRICH_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  "project-path": { type: "string" },
+  source: { type: "string" },
+  mode: { type: "string" },
+};
+
+function cmdEnrichHelp() {
+  console.log(`SDTK-BRAIN Enrich
+
+Usage:
+  sdtk-brain enrich --source github --mode review [--project-path <path>]
+
+Purpose:
+  Write an explicit opt-in GitHub enrichment review report from local wiki evidence.
+
+Scope:
+  Enriches EXTERNAL tool/repo candidates surfaced by the ingest/compile pipeline.
+  Not related to your own project docs — those are indexed by "sdtk-brain atlas build".
+
+Safety:
+  Review mode only in R1.
+  No network fetch, page rewrite, source mutation, apply, entitlement change, or .brain-legacy-unused mutation.
+  Network-backed metadata verification requires a later controller-approved slice.`);
+  return 0;
+}
+
+function cmdEnrich(args) {
+  const { flags } = parseFlags(args || [], ENRICH_FLAG_DEFS);
+  if (flags.help) return cmdEnrichHelp();
+  if (flags.source !== "github") {
+    throw new ValidationError("sdtk-brain enrich requires --source github in R1. No project files were changed.");
+  }
+  const mode = flags.mode || "review";
+  if (mode !== "review") {
+    throw new ValidationError("sdtk-brain enrich supports only --mode review in R1. No project files were changed.");
+  }
+  const result = runWikiGithubEnrichmentReview({ projectPath: flags["project-path"] });
+  console.log(`[brain] GitHub enrichment review: ${result.markdownPath}`);
+  console.log(`[brain] JSON report: ${result.jsonPath}`);
+  console.log(`[brain] Candidates: ${result.records.length}`);
+  console.log("[brain] Review-only local metadata. No network fetch, page rewrite, source mutation, or .brain-legacy-unused mutation was performed.");
+  return 0;
+}
+
+module.exports = {
+  cmdEnrich,
+  cmdEnrichHelp,
+};

package/src/commands/init.js

@@ -0,0 +1,108 @@
+"use strict";
+
+// `sdtk-brain init` — scaffold a vault (BK-319, OQ-BR-1 locked: CWD-as-vault
+// with a fail-closed refusal when the target is non-empty and not already a
+// vault; vaults are standalone user-chosen folders, never product repos).
+
+const fs = require("fs");
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { ValidationError } = require("../lib/errors");
+
+const INIT_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  vault: { type: "string" },
+};
+
+const RAW_DIRS = ["inbox", "articles", "papers", "repos", "notes", "meetings", "archive"];
+const VAULT_MARKERS = ["CLAUDE.md", "raw", "wiki"];
+
+function templatePath(name) {
+  return path.join(__dirname, "..", "..", "templates", name);
+}
+
+function looksLikeVault(target) {
+  return VAULT_MARKERS.every((marker) => fs.existsSync(path.join(target, marker)));
+}
+
+function printInitHelp() {
+  console.log(`sdtk-brain init
+
+Usage:
+  sdtk-brain init [--vault <path>]
+
+Scaffolds a second-brain vault:
+  raw/        immutable sources (inbox, articles, papers, repos, notes, meetings, archive)
+  wiki/       compiled knowledge layer (pages are created by compile --apply and by your agent)
+  workspace/  scratch space and exports
+  CLAUDE.md   the agent operating contract (how the vault is maintained)
+  README.md   human orientation
+
+Safety:
+  Defaults to the current directory as the vault. Refuses a target that is
+  not empty unless it already looks like a vault (re-runs are idempotent and
+  never overwrite existing files). Never scaffolds into a product repo.`);
+  return 0;
+}
+
+function writeIfAbsent(filePath, content, created) {
+  if (fs.existsSync(filePath)) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf-8");
+  created.push(filePath);
+}
+
+function cmdInit(args) {
+  const { flags } = parseFlags(args || [], INIT_FLAG_DEFS);
+  if (flags.help) {
+    return printInitHelp();
+  }
+
+  const target = path.resolve(flags.vault || process.cwd());
+  fs.mkdirSync(target, { recursive: true });
+
+  const entries = fs.readdirSync(target).filter((name) => !name.startsWith("."));
+  if (entries.length > 0 && !looksLikeVault(target)) {
+    throw new ValidationError(
+      `Target is not empty and does not look like a vault: ${target}. ` +
+        "A vault is a standalone folder (never a product repo). Pick an empty " +
+        "folder or pass --vault <path>. No files were changed."
+    );
+  }
+
+  const created = [];
+  for (const dir of RAW_DIRS) {
+    const p = path.join(target, "raw", dir);
+    if (!fs.existsSync(p)) {
+      fs.mkdirSync(p, { recursive: true });
+      created.push(p);
+    }
+  }
+  for (const dir of ["wiki", "workspace", path.join(".brain", "reports")]) {
+    const p = path.join(target, dir);
+    if (!fs.existsSync(p)) {
+      fs.mkdirSync(p, { recursive: true });
+      created.push(p);
+    }
+  }
+
+  writeIfAbsent(path.join(target, "CLAUDE.md"), fs.readFileSync(templatePath("VAULT_CLAUDE.md"), "utf-8"), created);
+  writeIfAbsent(path.join(target, "README.md"), fs.readFileSync(templatePath("VAULT_README.md"), "utf-8"), created);
+  writeIfAbsent(
+    path.join(target, ".gitignore"),
+    ".brain/\nworkspace/\n",
+    created
+  );
+
+  console.log(`[brain] Vault ready: ${target}`);
+  console.log(`[brain] Created: ${created.length} (existing files are never overwritten)`);
+  console.log("[brain] Next: drop a source into raw/inbox, then run:");
+  console.log("[brain]   sdtk-brain ingest raw/inbox");
+  console.log("[brain]   sdtk-brain compile --mode safe --apply");
+  console.log("[brain]   sdtk-brain search \"<topic>\"   ·   sdtk-brain open");
+  return 0;
+}
+
+module.exports = { cmdInit, looksLikeVault };

package/src/commands/lint.js

@@ -0,0 +1,50 @@
+"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-brain lint --help
+  sdtk-brain lint [--project-path <path>]
+
+Purpose:
+  Run report-first, non-destructive lint checks over canonical .brain content and local source-quality evidence.
+
+Output:
+  .brain/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.
+  Local wiki quality metrics report frontmatter coverage, required sections, source refs, internal links, stub ratio, giant pages, density, and source evidence coverage.
+  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(`[brain] Lint report: ${result.reportPath}`);
+  console.log(`[brain] Findings: ${result.totalFindings}`);
+  console.log("[brain] No wiki or source content was auto-modified.");
+  return 0;
+}
+
+module.exports = {
+  cmdLint,
+  cmdLintHelp,
+};

package/src/commands/open.js

@@ -0,0 +1,59 @@
+"use strict";
+
+// `sdtk-brain open` — build the vault knowledge graph (shared atlas builder,
+// L-5) and open the self-contained viewer. The viewer is a single HTML file
+// with the graph JSON inlined, so file:// works without any server.
+
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { buildAtlas, DEFAULT_EXCLUDE_FRAGS } = require("../lib/wiki-build");
+const { openBrowser } = require("../lib/browser-open");
+const { resolveProjectPath, getWikiGraphPath } = require("../lib/wiki-paths");
+
+const OPEN_FLAG_DEFS = {
+  help: { type: "boolean", alias: "h" },
+  vault: { type: "string" },
+  "no-open": { type: "boolean" },
+};
+
+function printOpenHelp() {
+  console.log(`sdtk-brain open
+
+Usage:
+  sdtk-brain open [--vault <path>] [--no-open]
+
+Builds the vault knowledge graph over wiki/ and raw/ (shared SDTK atlas
+builder) into .brain/graph and opens the self-contained viewer.html
+(docs view + graph view). --no-open builds without launching a browser.
+
+Local-only: no server is required — the viewer inlines its data.`);
+  return 0;
+}
+
+async function cmdOpen(args) {
+  const { flags } = parseFlags(args || [], OPEN_FLAG_DEFS);
+  if (flags.help) {
+    return printOpenHelp();
+  }
+
+  const vault = resolveProjectPath(flags.vault || process.cwd());
+  const outputDir = getWikiGraphPath(vault);
+  const excludes = [...DEFAULT_EXCLUDE_FRAGS, ".brain", "workspace"];
+  const scanRoots = [path.join(vault, "wiki"), path.join(vault, "raw")]
+    .filter((root) => require("fs").existsSync(root));
+  if (scanRoots.length === 0) {
+    console.error("[brain] Nothing to index: no wiki/ or raw/ under the vault. Run `sdtk-brain init` first.");
+    return 1;
+  }
+
+  const result = await buildAtlas({ projectRoot: vault, outputDir, scanRoots, excludes });
+  const viewer = path.join(outputDir, "viewer.html");
+  console.log(`[brain] Graph: ${result.node_count} nodes, ${result.edge_count} edges`);
+  console.log(`[brain] Viewer: ${viewer}`);
+  if (!flags["no-open"]) {
+    openBrowser(viewer);
+  }
+  return 0;
+}
+
+module.exports = { cmdOpen };