digital-brain 0.1.3 → 0.1.7

package/README.md

@@ -24,7 +24,7 @@ Digital Brain gives them a structured, local map of:
 npx digital-brain init
 ```
 
-The installer asks a short setup quiz: history window, primary focus, refresh cadence, always-on interval, active time window, outbound mode, and AI adapter setup.
+The installer asks a short setup quiz: setup mode, history window, primary focus, refresh cadence, always-on interval, active time window, outbound mode, and AI adapter setup.
 
 The quiz is mostly multiple choice. Pick with `A/B/C`, `1/2/3`, the exact value, or press Enter to accept the default. If you skip the vault path, Digital Brain creates a new folder in the current directory:
 
@@ -38,7 +38,7 @@ For a non-interactive setup:
 npx digital-brain init --yes
 ```
 
-For local always-on setup:
+Inside the quiz, choose `Auto mode` to use recommended always-on local refresh settings. You can also start there directly:
 
 ```bash
 npx digital-brain init --full-auto
@@ -46,6 +46,8 @@ npx digital-brain init --full-auto
 
 Full-auto means local repeated refreshes. It does not mean blind auto-send. WhatsApp sending still defaults to drafts or explicit confirmation, and the AI-disclosure guard stays enabled.
 
+`init` also runs a setup check. npm installs the package dependencies automatically, and Digital Brain does not require pip packages. If Python, WhatsApp for Mac, or optional Ollama setup is missing, the check prints the exact next step. See [docs/SETUP.md](docs/SETUP.md).
+
 For local development:
 
 ```bash
@@ -77,11 +79,22 @@ node ./bin/digital-brain.js init ./Digital Brain\ Vault
 ## Core Commands
 
 ```bash
-digital-brain init ./Digital Brain\ Vault
-digital-brain sync-whatsapp --vault ./Digital Brain\ Vault --days 30
-digital-brain extract --vault ./Digital Brain\ Vault --days 30
-digital-brain interpret --vault ./Digital Brain\ Vault --days 30
-digital-brain send-whatsapp --vault ./Digital Brain\ Vault --to "Name" --message "text"
+digital-brain init
+digital-brain run
+digital-brain doctor
+digital-brain send-whatsapp --to "Name" --message "text"
+```
+
+`init` remembers your vault globally, so `run` works from anywhere. `run` syncs WhatsApp, extracts relationships, and writes interpreted memory in one command.
+
+Use `digital-brain doctor` or `digital-brain tutorial` anytime to see dependency status and next steps.
+
+The lower-level commands still exist for debugging:
+
+```bash
+digital-brain sync-whatsapp
+digital-brain extract
+digital-brain interpret
 ```
 
 The sender drafts by default. Add `--yes` to actually send.

package/bin/digital-brain.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { copyDir, ensureDir, packageRoot, resolveVault } from "../lib/fs.js";
+import { copyDir, ensureDir, packageRoot, resolveVault, writeDefaultVault } from "../lib/fs.js";
 
 const root = packageRoot(import.meta.url);
 
@@ -19,7 +19,9 @@ async function main() {
   const args = parseArgs(argv);
 
   if (command === "init") await init(argv, args);
+  else if (command === "run" || command === "refresh") runRefresh(argv, args);
   else if (command === "doctor") doctor();
+  else if (command === "tutorial" || command === "setup-check") doctor({ tutorial: true });
   else if (command === "sync-whatsapp") runPython("digital_brain_whatsapp_mac_sync.py", argv);
   else if (command === "extract") runPython("digital_brain_relationship_extractor.py", argv);
   else if (command === "interpret") runPython("digital_brain_relationship_interpreter.py", argv);
@@ -31,6 +33,7 @@ async function init(argv, args) {
   const positional = argv.filter((arg) => !arg.startsWith("--"));
   const defaultVault = path.resolve(process.cwd(), "Digital Brain Vault");
   const fullAuto = toBoolean(args["full-auto"]);
+  let setupMode = fullAuto ? "full-auto" : "guided";
   let vault = positional[0] ? path.resolve(positional[0]) : args.yes ? defaultVault : "";
   let selfName = args["self-name"] || "";
   let connectAi = toBoolean(args["connect-ai"]);
@@ -49,18 +52,28 @@ async function init(argv, args) {
     vault ||= path.resolve(await ask(rl, "📁 Vault path", defaultVault, "Enter creates this folder if it does not exist."));
     selfName ||= await ask(rl, "👤 Your name", "Me");
     dataWindowDays = await askNumber(rl, "🕰️  History to import", dataWindowDays, { suffix: "days", min: 1 });
+    setupMode = await select(rl, "Setup mode", [
+      ["guided", "Guided", "Pick each setting yourself.", "🧭"],
+      ["full-auto", "Auto mode", "Use recommended always-on local refresh settings.", "⚡"],
+    ], setupMode);
     focus ||= await select(rl, "Primary focus", [
       ["relationship-memory", "Relationship memory", "Map people, tone, and recurring patterns.", "🧠"],
       ["reply-help", "Reply help", "Prioritize drafting guidance and typing-style matching.", "💬"],
       ["work-context", "Work context", "Prioritize collaborators, projects, and operational notes.", "💼"],
     ], "relationship-memory");
-    schedule = await select(rl, "Refresh cadence", [
-      ["manual", "Manual", "Only runs when you run a command.", "🖐️"],
-      ["daily", "Daily", "Good for a low-maintenance personal vault.", "🌅"],
-      ["hourly", "Hourly", "Keeps memory warm without running constantly.", "⏱️"],
-      ["every-30-min", "Every 30 minutes", "Useful for morning or work-window guidance.", "🔁"],
-      ["always-on", "Always-on local loop", "Runs repeatedly while your computer is awake.", "⚡"],
-    ], schedule);
+    if (setupMode === "full-auto") {
+      schedule = "always-on";
+      console.log("");
+      console.log("⚡ Auto mode selected: always-on local refresh, draft-first outbound, AI disclosure guard enabled.");
+    } else {
+      schedule = await select(rl, "Refresh cadence", [
+        ["manual", "Manual", "Only runs when you run a command.", "🖐️"],
+        ["daily", "Daily", "Good for a low-maintenance personal vault.", "🌅"],
+        ["hourly", "Hourly", "Keeps memory warm without running constantly.", "⏱️"],
+        ["every-30-min", "Every 30 minutes", "Useful for morning or work-window guidance.", "🔁"],
+        ["always-on", "Always-on local loop", "Runs repeatedly while your computer is awake.", "⚡"],
+      ], schedule);
+    }
     if (schedule === "always-on") {
       refreshIntervalMinutes = await askNumber(rl, "⏳ Always-on pull interval", refreshIntervalMinutes, {
         suffix: "minutes",
@@ -79,6 +92,7 @@ async function init(argv, args) {
       console.log("Full-auto/outbound confirmation was not accepted. Using manual refresh and draft-only outbound.");
       schedule = "manual";
       outboundMode = "draft";
+      setupMode = "guided";
     }
     rl.close();
   }
@@ -94,7 +108,7 @@ async function init(argv, args) {
     activeWindow,
     timezone,
     outboundMode,
-    setupMode: fullAuto ? "full-auto" : "guided",
+    setupMode,
     responsibilityAccepted,
     defaults: {
       enterUsesDefault: true,
@@ -109,6 +123,7 @@ async function init(argv, args) {
     },
   };
   writeConfig(vault, config);
+  writeDefaultVault(vault);
   writeRefreshScript(vault, config);
   writeWatchScript(vault, config);
 
@@ -120,43 +135,145 @@ async function init(argv, args) {
 
   console.log(`Digital Brain vault created: ${vault}`);
   console.log(`Config: ${path.join(vault, "digital-brain.config.json")}`);
+  console.log(`Default vault saved: ${vault}`);
   console.log(`Refresh script: ${path.join(vault, "Tools", "digital-brain-refresh.sh")}`);
   console.log(`Always-on script: ${path.join(vault, "Tools", "digital-brain-watch.sh")}`);
   console.log("Next:");
-  console.log(`  digital-brain sync-whatsapp --vault "${vault}" --days ${dataWindowDays}`);
-  console.log(`  digital-brain extract --vault "${vault}" --days ${dataWindowDays}`);
-  console.log(`  digital-brain interpret --vault "${vault}" --days ${dataWindowDays}`);
+  console.log("  digital-brain run");
   if (schedule === "always-on") console.log(`  "${path.join(vault, "Tools", "digital-brain-watch.sh")}"`);
+  printSetupCheck(vault, { tutorial: true });
 }
 
-function doctor() {
-  const checks = [
-    ["node", process.version],
-    ["python3", shell("python3", ["--version"])],
-    ["sqlite3", shell("sqlite3", ["--version"])],
-    ["ollama", shell("ollama", ["--version"], true)],
-  ];
-  for (const [name, value] of checks) {
-    console.log(`${name}: ${value || "not found"}`);
-  }
-  const macDb = path.join(os.homedir(), "Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite");
-  console.log(`WhatsApp Mac DB: ${fs.existsSync(macDb) ? macDb : "not found"}`);
+function doctor(options = {}) {
+  printSetupCheck(resolveVault(process.cwd()), options);
 }
 
 function runPython(script, argv) {
-  const resolved = withVault(argv);
-  const result = spawnSync("python3", [path.join(root, "scripts", script), ...resolved], { stdio: "inherit" });
+  const result = runPythonStep(script, withVault(argv));
   process.exit(result.status ?? 1);
 }
 
+function runRefresh(argv, args) {
+  const vault = getVaultFromArgs(argv);
+  const config = readVaultConfig(vault);
+  const days = String(args.days || args["data-window-days"] || config.dataWindowDays || 30);
+  const syncArgs = ["--vault", vault, "--days", days, "--markdown-mode", args["markdown-mode"] || "month"];
+  const extractArgs = ["--vault", vault, "--days", days];
+  const interpretArgs = ["--vault", vault, "--days", days];
+  if (args["min-messages"]) extractArgs.push("--min-messages", String(args["min-messages"]));
+  console.log(`Digital Brain refresh: ${vault}`);
+  for (const [label, script, stepArgs] of [
+    ["sync", "digital_brain_whatsapp_mac_sync.py", syncArgs],
+    ["extract", "digital_brain_relationship_extractor.py", extractArgs],
+    ["interpret", "digital_brain_relationship_interpreter.py", interpretArgs],
+  ]) {
+    if (toBoolean(args[`skip-${label}`])) {
+      console.log(`\n→ ${label} skipped`);
+      continue;
+    }
+    console.log(`\n→ ${label}`);
+    const result = runPythonStep(script, stepArgs);
+    if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
+  }
+  console.log("\nDigital Brain refresh complete.");
+}
+
+function runPythonStep(script, argv) {
+  return spawnSync("python3", [path.join(root, "scripts", script), ...argv], { stdio: "inherit" });
+}
+
 function runNode(script, argv) {
-  const result = spawnSync(process.execPath, [path.join(root, script), ...argv], { stdio: "inherit" });
+  const result = spawnSync(process.execPath, [path.join(root, script), ...withVault(argv)], { stdio: "inherit" });
   process.exit(result.status ?? 1);
 }
 
 function withVault(argv) {
   if (argv.includes("--vault") || argv.some((arg) => arg.startsWith("--vault="))) return argv;
-  return ["--vault", resolveVault(process.cwd()), ...argv];
+  return ["--vault", getVaultFromArgs(argv), ...argv];
+}
+
+function getVaultFromArgs(argv) {
+  const args = parseArgs(argv);
+  if (args.vault) return path.resolve(String(args.vault));
+  return resolveVault(process.cwd());
+}
+
+function readVaultConfig(vault) {
+  const file = path.join(vault, "digital-brain.config.json");
+  if (!fs.existsSync(file)) {
+    console.error(`No Digital Brain vault found. Run "digital-brain init" first, or pass --vault <path>.`);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function printSetupCheck(vault, options = {}) {
+  const pythonVersion = shell("python3", ["--version"], true);
+  const pythonSqlite = shell("python3", ["-c", "import sqlite3; print('ok')"], true);
+  const ollamaVersion = shell("ollama", ["--version"], true);
+  const macDb = path.join(os.homedir(), "Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite");
+  const checks = [
+    {
+      label: "Node",
+      ok: nodeMajor() >= 20,
+      value: process.version,
+      hint: "Install Node 20 or newer from https://nodejs.org.",
+    },
+    {
+      label: "Package dependencies",
+      ok: true,
+      value: "installed by npm",
+    },
+    {
+      label: "Python 3",
+      ok: Boolean(pythonVersion),
+      value: pythonVersion || "not found",
+      hint: "Install with: brew install python",
+    },
+    {
+      label: "Python sqlite3",
+      ok: pythonSqlite === "ok",
+      value: pythonSqlite === "ok" ? "available" : "not found",
+      hint: "Use a Python 3 build with sqlite3 support.",
+    },
+    {
+      label: "WhatsApp Mac database",
+      ok: fs.existsSync(macDb),
+      value: fs.existsSync(macDb) ? "found" : "not found yet",
+      hint: "Open WhatsApp for Mac and log in. If macOS blocks access, grant Terminal Full Disk Access.",
+    },
+    {
+      label: "Ollama",
+      ok: Boolean(ollamaVersion),
+      value: ollamaVersion || "optional",
+      hint: "Optional local LLM: brew install ollama",
+      optional: true,
+    },
+  ];
+
+  console.log("");
+  console.log("Setup check");
+  for (const check of checks) {
+    const icon = check.ok ? "✓" : check.optional ? "○" : "!";
+    console.log(`  ${icon} ${check.label}: ${check.value}`);
+    if (!check.ok && check.hint) console.log(`    ${check.hint}`);
+  }
+  if (fs.existsSync(path.join(vault, "digital-brain.config.json"))) {
+    console.log(`  ✓ Default vault: ${vault}`);
+  } else {
+    console.log("  ! Default vault: not set");
+    console.log("    Run: digital-brain init");
+  }
+
+  if (options.tutorial) {
+    console.log("");
+    console.log("How to use it");
+    console.log("  1. Open WhatsApp for Mac once and keep it logged in.");
+    console.log("  2. Run: digital-brain run");
+    console.log("  3. Ask your AI to use the generated vault notes for personal context.");
+    console.log("");
+    console.log("No pip install is needed. npm installs the package dependencies.");
+  }
 }
 
 function writeConfig(vault, config) {
@@ -173,9 +290,7 @@ set -euo pipefail
 VAULT="${vault.replace(/"/g, '\\"')}"
 DAYS="${days}"
 
-digital-brain sync-whatsapp --vault "$VAULT" --days "$DAYS" --markdown-mode month
-digital-brain extract --vault "$VAULT" --days "$DAYS"
-digital-brain interpret --vault "$VAULT" --days "$DAYS"
+digital-brain run --vault "$VAULT" --days "$DAYS" --markdown-mode month
 
 echo "Digital Brain refresh complete for $VAULT"
 `;
@@ -306,6 +421,10 @@ function shell(command, args, optional = false) {
   return (result.stdout || result.stderr).trim().split("\n")[0];
 }
 
+function nodeMajor() {
+  return Number(process.version.replace(/^v/, "").split(".")[0]);
+}
+
 function parseArgs(argv) {
   const out = {};
   for (let i = 0; i < argv.length; i += 1) {
@@ -341,10 +460,12 @@ function help() {
 
 Usage:
   digital-brain init [vault]
+  digital-brain run
   digital-brain doctor
-  digital-brain sync-whatsapp --vault <path> --days 30
-  digital-brain extract --vault <path> --days 30
-  digital-brain interpret --vault <path> --days 30
-  digital-brain send-whatsapp --vault <path> --to "Name" --message "Text" [--yes]
+  digital-brain tutorial
+  digital-brain sync-whatsapp --days 30
+  digital-brain extract --days 30
+  digital-brain interpret --days 30
+  digital-brain send-whatsapp --to "Name" --message "Text" [--yes]
 `);
 }

package/docs/AUTOMATIONS.md

@@ -10,6 +10,14 @@ Tools/digital-brain-refresh.sh
 
 That script runs sync, extract, and interpret using the install-time config.
 
+After setup, the normal manual command is:
+
+```bash
+digital-brain run
+```
+
+`init` saves your default vault in `~/.digital-brain/config.json`, so `run` does not need a vault path.
+
 ## Configurable At Install
 
 `digital-brain init` asks:
@@ -17,6 +25,7 @@ That script runs sync, extract, and interpret using the install-time config.
 - vault path
 - your name
 - history window in days
+- setup mode: guided or auto mode
 - primary focus: relationship memory, reply help, work context
 - refresh cadence: manual, daily, hourly, every 30 minutes, or always-on
 - refresh interval in minutes for always-on mode, clamped to a minimum of 1
@@ -44,15 +53,15 @@ The answers are saved in:
 digital-brain.config.json
 ```
 
-## Full Auto
+## Auto Mode
 
-Use:
+Choose `Auto mode` during `digital-brain init`, or use:
 
 ```bash
 digital-brain init --full-auto
 ```
 
-Full-auto configures local always-on refreshes with a 5 minute default interval. It still uses the local watch script, so it only runs while the machine and runner are awake.
+Auto mode configures local always-on refreshes with a 5 minute default interval. It still uses the local watch script, so it only runs while the machine and runner are awake.
 
 During the guided quiz, always-on and send-with-confirmation require an explicit responsibility check. Pressing Enter does not approve that check. If it is skipped, Digital Brain falls back to manual refresh and draft-only outbound.
 
@@ -63,7 +72,7 @@ Use a Codex cron automation pointed at the generated vault.
 Prompt:
 
 ```text
-Run `Tools/digital-brain-refresh.sh`. Verify completion and report only counts plus output paths. Do not print private message contents.
+Run `digital-brain run`. Verify completion and report only counts plus output paths. Do not print private message contents.
 ```
 
 Example schedule ideas:

package/docs/SETUP.md

@@ -0,0 +1,46 @@
+# Setup
+
+Digital Brain is designed to install with one npm command:
+
+```bash
+npx digital-brain init
+```
+
+npm installs the Node dependencies. No pip install is needed; the Python scripts only use the standard library.
+
+## What Init Checks
+
+After the quiz, `init` runs a setup check for:
+
+- Node 20+
+- npm package dependencies
+- Python 3
+- Python sqlite3 support
+- WhatsApp for Mac local database access
+- optional Ollama
+
+Run the check again anytime:
+
+```bash
+digital-brain doctor
+```
+
+For a short usage guide:
+
+```bash
+digital-brain tutorial
+```
+
+## What Cannot Be Silently Installed
+
+Digital Brain does not silently install or configure system apps.
+
+- WhatsApp for Mac must be installed and logged in by the user.
+- macOS may require Full Disk Access for the terminal app.
+- Ollama is optional and only needed for local LLM workflows.
+
+Once setup passes, normal use is:
+
+```bash
+digital-brain run
+```

package/lib/fs.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -28,5 +29,31 @@ export function resolveVault(cwd) {
     if (parent === current) break;
     current = parent;
   }
+  const configured = readDefaultVault();
+  if (configured) return configured;
   return path.resolve(cwd);
 }
+
+export function globalConfigPath() {
+  return path.join(os.homedir(), ".digital-brain", "config.json");
+}
+
+export function readDefaultVault() {
+  const file = globalConfigPath();
+  if (!fs.existsSync(file)) return "";
+  try {
+    const config = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (config.defaultVault && fs.existsSync(path.join(config.defaultVault, "digital-brain.config.json"))) {
+      return config.defaultVault;
+    }
+  } catch {
+    return "";
+  }
+  return "";
+}
+
+export function writeDefaultVault(vault) {
+  const file = globalConfigPath();
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, `${JSON.stringify({ defaultVault: vault }, null, 2)}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "digital-brain",
-  "version": "0.1.3",
+  "version": "0.1.7",
   "description": "Your private digital imprint for AI assistants.",
   "type": "module",
   "bin": {