@our2ndbrain/cli 1.1.3 → 2026.4.4

package/src/commands/check.js

@@ -0,0 +1,199 @@
+/**
+ * 2ndBrain CLI - Check Command
+ *
+ * Cross-platform environment check. All platform detection is handled
+ * in Node.js — agents never need to write shell/PowerShell scripts.
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { is2ndBrainProject } = require('../lib/config');
+
+const MIN_NODE_MAJOR = 18;
+
+function commandExists(cmd) {
+  try {
+    const isWin = process.platform === 'win32';
+    if (isWin) {
+      execFileSync('where', [cmd], { stdio: 'pipe' });
+    } else {
+      execFileSync('which', [cmd], { stdio: 'pipe' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getCommandVersion(cmd, args = ['--version']) {
+  try {
+    return execFileSync(cmd, args, { stdio: 'pipe', encoding: 'utf8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function checkObsidianInstalled() {
+  switch (process.platform) {
+    case 'darwin':
+      return fs.existsSync('/Applications/Obsidian.app');
+    case 'win32': {
+      const localAppData = process.env.LOCALAPPDATA || '';
+      return fs.existsSync(path.join(localAppData, 'Programs', 'Obsidian', 'Obsidian.exe'));
+    }
+    default:
+      return commandExists('obsidian');
+  }
+}
+
+function getObsidianInstallHint() {
+  switch (process.platform) {
+    case 'darwin':
+      return 'brew install --cask obsidian  (或从 https://obsidian.md/ 下载)';
+    case 'win32':
+      return 'winget install Obsidian.MD.Obsidian  (或从 https://obsidian.md/ 下载)';
+    default:
+      return '从 https://obsidian.md/ 下载 AppImage';
+  }
+}
+
+function getNodeInstallHint() {
+  switch (process.platform) {
+    case 'darwin':
+      return 'brew install node';
+    case 'win32':
+      return 'winget install OpenJS.NodeJS.LTS  (或从 https://nodejs.org/ 下载)';
+    default:
+      return 'sudo apt install nodejs npm  (Debian/Ubuntu) 或从 https://nodejs.org/ 下载';
+  }
+}
+
+function getObsidianCLIPathHint() {
+  switch (process.platform) {
+    case 'darwin':
+      return '在 ~/.zshrc 中添加:\nexport PATH="$PATH:/Applications/Obsidian.app/Contents/MacOS"';
+    case 'win32':
+      return '系统设置 → 环境变量 → Path → 新增:\nC:\\Users\\<用户名>\\AppData\\Local\\Programs\\Obsidian\\';
+    default:
+      return 'sudo ln -s /opt/obsidian/obsidian /usr/local/bin/obsidian';
+  }
+}
+
+async function check(targetPath, _options, log) {
+  const results = [];
+  let allPassed = true;
+
+  log.info('\n🧠 2ndBrain 环境检测\n');
+
+  // 1. Node.js version
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  if (nodeMajor >= MIN_NODE_MAJOR) {
+    results.push({ ok: true, label: `Node.js ${nodeVersion}` });
+  } else {
+    results.push({
+      ok: false,
+      label: `Node.js ${nodeVersion} (需要 >= ${MIN_NODE_MAJOR})`,
+      hint: getNodeInstallHint(),
+    });
+    allPassed = false;
+  }
+
+  // 2. Git
+  const gitVersion = getCommandVersion('git');
+  if (gitVersion) {
+    results.push({ ok: true, label: `Git ${gitVersion.replace('git version ', '')}` });
+  } else {
+    results.push({
+      ok: false,
+      label: 'Git 未安装',
+      hint: process.platform === 'win32'
+        ? 'winget install Git.Git'
+        : process.platform === 'darwin'
+          ? 'brew install git'
+          : 'sudo apt install git',
+    });
+    allPassed = false;
+  }
+
+  // 3. Obsidian app
+  if (checkObsidianInstalled()) {
+    results.push({ ok: true, label: 'Obsidian 已安装' });
+  } else {
+    results.push({
+      ok: false,
+      label: 'Obsidian 未安装',
+      hint: getObsidianInstallHint(),
+    });
+    allPassed = false;
+  }
+
+  // 4. Obsidian CLI
+  if (commandExists('obsidian')) {
+    const obsVersion = getCommandVersion('obsidian');
+    results.push({ ok: true, label: `Obsidian CLI ${obsVersion || '可用'}` });
+  } else {
+    results.push({
+      ok: false,
+      label: 'Obsidian CLI 未配置',
+      hint: `在 Obsidian Settings > General > CLI 中启用，然后配置 PATH:\n${getObsidianCLIPathHint()}`,
+    });
+    // Obsidian CLI is optional, don't fail the whole check
+  }
+
+  // 5. 2ndBrain project (if path given)
+  const resolvedPath = path.resolve(targetPath);
+  if (fs.existsSync(resolvedPath)) {
+    if (is2ndBrainProject(resolvedPath)) {
+      results.push({ ok: true, label: `2ndBrain 知识库: ${resolvedPath}` });
+    } else {
+      results.push({
+        ok: false,
+        label: `${resolvedPath} 不是 2ndBrain 知识库`,
+        hint: `运行: 2ndbrain init ${targetPath}`,
+      });
+    }
+  }
+
+  // 6. Agent CLI (openclaw or claude)
+  if (commandExists('openclaw')) {
+    results.push({ ok: true, label: 'OpenClaw CLI 可用' });
+  } else if (commandExists('claude')) {
+    results.push({ ok: true, label: 'Claude CLI 可用' });
+  } else {
+    results.push({
+      ok: false,
+      label: 'Agent CLI 未找到 (openclaw / claude)',
+      hint: '安装 OpenClaw: https://docs.openclaw.ai/start\n或 Claude Code: https://code.claude.com',
+    });
+  }
+
+  // Print results
+  for (const r of results) {
+    if (r.ok) {
+      log.success(`  ✓ ${r.label}`);
+    } else {
+      log.error(`  ✗ ${r.label}`);
+      if (r.hint) {
+        log.warn(`    → ${r.hint.split('\n').join('\n    → ')}`);
+      }
+    }
+  }
+
+  log.info('');
+
+  if (allPassed) {
+    log.success('所有必要组件已就绪 ✓\n');
+  } else {
+    log.warn('部分组件缺失，请按上方提示安装\n');
+  }
+
+  return allPassed;
+}
+
+module.exports = check;
+module.exports.MIN_NODE_MAJOR = MIN_NODE_MAJOR;
+module.exports.commandExists = commandExists;
+module.exports.getCommandVersion = getCommandVersion;
+module.exports.checkObsidianInstalled = checkObsidianInstalled;

package/src/commands/completion.js

@@ -25,7 +25,7 @@ _2ndbrain_completions() {
   local cmd="\${COMP_WORDS[1]}"
 
   # Top-level commands
-  local commands="init update remove member completion"
+  local commands="init update remove member check watch completion"
 
   case "\$cmd" in
     init)
@@ -55,6 +55,14 @@ _2ndbrain_completions() {
     member)
       COMPREPLY=( $(compgen -W "-f --force --no-config -h --help" -- "\$cur") )
       ;;
+    check)
+      COMPREPLY=( $(compgen -W "-h --help" -- "\$cur") )
+      [[ -z "\$cur" || "\$cur" != -* ]] && COMPREPLY+=( $(compgen -d -- "\$cur") )
+      ;;
+    watch)
+      COMPREPLY=( $(compgen -W "-i --interval --once -h --help" -- "\$cur") )
+      [[ -z "\$cur" || "\$cur" != -* ]] && COMPREPLY+=( $(compgen -d -- "\$cur") )
+      ;;
     completion)
       COMPREPLY=( $(compgen -W "bash zsh fish" -- "\$cur") )
       ;;
@@ -78,6 +86,8 @@ _2ndbrain() {
     'update:Update framework files from template'
     'remove:Remove framework files (preserves user data)'
     'member:Initialize a new member directory'
+    'check:Check environment prerequisites'
+    'watch:Watch To-Do files and trigger inbox organization'
     'completion:Generate shell completion script'
   )
 
@@ -122,6 +132,18 @@ _2ndbrain() {
             '1:name:' \\
             '2:path:_directories'
           ;;
+        check)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[Show help]' \\
+            '1:path:_directories'
+          ;;
+        watch)
+          _arguments \\
+            '(-i --interval)'{-i,--interval}'[Debounce interval in minutes]:minutes:' \\
+            '--once[Exit after first triggered organization]' \\
+            '(-h --help)'{-h,--help}'[Show help]' \\
+            '1:path:_directories'
+          ;;
         completion)
           _arguments \\
             '1:shell:(bash zsh fish)'
@@ -144,6 +166,8 @@ complete -c 2ndbrain -n '__fish_use_subcommand' -a 'init' -d 'Initialize a new 2
 complete -c 2ndbrain -n '__fish_use_subcommand' -a 'update' -d 'Update framework files from template'
 complete -c 2ndbrain -n '__fish_use_subcommand' -a 'remove' -d 'Remove framework files'
 complete -c 2ndbrain -n '__fish_use_subcommand' -a 'member' -d 'Initialize a new member directory'
+complete -c 2ndbrain -n '__fish_use_subcommand' -a 'check' -d 'Check environment prerequisites'
+complete -c 2ndbrain -n '__fish_use_subcommand' -a 'watch' -d 'Watch To-Do files and trigger inbox organization'
 complete -c 2ndbrain -n '__fish_use_subcommand' -a 'completion' -d 'Generate shell completion script'
 
 # Global options
@@ -173,6 +197,16 @@ complete -c 2ndbrain -n '__fish_seen_subcommand_from member' -s f -l force -d 'F
 complete -c 2ndbrain -n '__fish_seen_subcommand_from member' -l no-config -d 'Skip Obsidian config update'
 complete -c 2ndbrain -n '__fish_seen_subcommand_from member' -s h -l help -d 'Show help'
 
+# check options
+complete -c 2ndbrain -n '__fish_seen_subcommand_from check' -s h -l help -d 'Show help'
+complete -c 2ndbrain -n '__fish_seen_subcommand_from check' -a '(__fish_complete_directories)'
+
+# watch options
+complete -c 2ndbrain -n '__fish_seen_subcommand_from watch' -s i -l interval -d 'Debounce interval in minutes' -r
+complete -c 2ndbrain -n '__fish_seen_subcommand_from watch' -l once -d 'Exit after first triggered organization'
+complete -c 2ndbrain -n '__fish_seen_subcommand_from watch' -s h -l help -d 'Show help'
+complete -c 2ndbrain -n '__fish_seen_subcommand_from watch' -a '(__fish_complete_directories)'
+
 # completion options
 complete -c 2ndbrain -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'
 `;

package/src/commands/init.js

@@ -166,9 +166,9 @@ async function init(targetPath, options, log) {
 
   // Scan existing directory for smart integration
   const scan = await scanExistingDirectory(resolvedPath);
-  const isIntegrateMode = !isEmpty && scan.hasFiles && !isExistingProject;
+  const isIntegrationMode = !isEmpty && scan.hasFiles && !isExistingProject;
 
-  if (isIntegrateMode) {
+  if (isIntegrationMode) {
     log.info('');
     log.info('Integration mode: Merging 2ndBrain framework into existing vault');
     if (scan.hasUserDataDirs.size > 0) {
@@ -289,7 +289,7 @@ async function init(targetPath, options, log) {
 
   // Summary
   log.info('');
-  log.success(isIntegrateMode ? '2ndBrain framework integrated!' : '2ndBrain project initialized!');
+  log.success(isIntegrationMode ? '2ndBrain framework integrated!' : '2ndBrain project initialized!');
   log.info(`  Created: ${fileResult.copied.length} files`);
   if (fileResult.unchanged.length > 0) {
     log.info(`  Skipped: ${fileResult.unchanged.length} existing files`);

package/src/commands/member.js

@@ -18,6 +18,7 @@ const PLACEHOLDER = '{{MEMBER_NAME}}';
  * Member files configuration
  */
 const MEMBER_FILES = [
+  { template: 'tpl_member_todo.md', output: '00_To-Do.md' },
   { template: 'tpl_member_tasks.md', output: '01_Tasks.md' },
   { template: 'tpl_member_done.md', output: '09_Done.md' },
 ];
@@ -28,7 +29,7 @@ const MEMBER_FILES = [
  * @param {string} targetPath - Target project path
  * @param {Object} options - Command options
  * @param {boolean} [options.force] - Force overwrite existing member
- * @param {boolean} [options.noConfig] - Skip Obsidian config update
+ * @param {boolean} [options.config] - Whether to update Obsidian config (set false by --no-config)
  * @param {Object} log - Logger object
  */
 async function member(memberName, targetPath, options, log) {
@@ -110,6 +111,7 @@ async function member(memberName, targetPath, options, log) {
   log.success('🎉 Member init complete!');
   log.info('');
   log.info('Created files:');
+  log.info(`  - 10_Inbox/${memberName}/00_To-Do.md (append-only task list)`);
   log.info(`  - 10_Inbox/${memberName}/01_Tasks.md (personal dashboard)`);
   log.info(`  - 10_Inbox/${memberName}/09_Done.md (done records)`);
   log.info('');

package/src/commands/update.js

@@ -13,7 +13,12 @@ const {
   SMART_COPY_DIRS,
   is2ndBrainProject,
 } = require('../lib/config');
-const { copyFilesSmart, copyFileWithCompare, createFile } = require('../lib/files');
+const {
+  copyFilesSmart,
+  copyFileWithCompare,
+  createFile,
+  resolveSourcePath,
+} = require('../lib/files');
 const { generateDiff, formatDiffForTerminal, areContentsEqual, isBinaryFile, isLargeFile, LARGE_FILE_THRESHOLD } = require('../lib/diff');
 const { confirm, confirmBatchUpdates, confirmFile, confirmBinaryFile, confirmLargeFile } = require('../lib/prompt');
 const { copyObsidianDirSmart, MERGE_STRATEGIES } = require('../lib/obsidian');
@@ -214,11 +219,12 @@ async function performUpdate(resolvedPath, templateRoot, options, log) {
     // Apply all changes
     for (const change of changes) {
       const src = path.join(templateRoot, change.file);
+      const resolvedSrc = await resolveTemplateSourcePath(src, change.file);
       const dest = path.join(resolvedPath, change.file);
 
       // Handle special cases
       if (change.large && !options.yes) {
-        const stats = await fs.stat(src);
+        const stats = await fs.stat(resolvedSrc);
         const confirmed = await confirmLargeFile(change.file, stats.size);
         if (!confirmed) {
           log.warn(`  ~ ${change.file} (skipped)`);
@@ -240,11 +246,12 @@ async function performUpdate(resolvedPath, templateRoot, options, log) {
     for (const change of changes) {
       const file = change.file;
       const src = path.join(templateRoot, file);
+      const resolvedSrc = await resolveTemplateSourcePath(src, file);
       const dest = path.join(resolvedPath, file);
 
       // Handle special files
       if (change.large) {
-        const stats = await fs.stat(src);
+        const stats = await fs.stat(resolvedSrc);
         const confirmed = await confirmLargeFile(file, stats.size);
         if (!confirmed) {
           log.warn(`  ~ ${file} (skipped)`);
@@ -272,7 +279,7 @@ async function performUpdate(resolvedPath, templateRoot, options, log) {
 
       const [oldContent, newContent] = await Promise.all([
         fs.readFile(dest, 'utf8').catch(() => ''),
-        fs.readFile(src, 'utf8'),
+        fs.readFile(resolvedSrc, 'utf8'),
       ]);
 
       const diffText = generateDiff(oldContent, newContent, file, file);
@@ -300,6 +307,20 @@ async function performUpdate(resolvedPath, templateRoot, options, log) {
   await updateMemberDashboards(resolvedPath, templateRoot, options, log);
 }
 
+/**
+ * Resolve the actual template source path for a framework file.
+ * @param {string} src - Preferred source file path
+ * @param {string} file - Relative framework file path for error messages
+ * @returns {Promise<string>} Resolved source file path
+ */
+async function resolveTemplateSourcePath(src, file) {
+  const resolvedSrc = await resolveSourcePath(src);
+  if (!resolvedSrc) {
+    throw new Error(`Template source file not found: ${file}`);
+  }
+  return resolvedSrc;
+}
+
 /**
  * Update .obsidian directory with smart merge strategies
  * @param {string} resolvedPath - Target project path

package/src/commands/watch.js

@@ -0,0 +1,212 @@
+/**
+ * 2ndBrain CLI - Watch Command
+ *
+ * File watcher that monitors To-Do files for changes and triggers
+ * lightweight inbox organization via openclaw/claude agent CLI.
+ * Pure Node.js — works on macOS, Windows, and Linux.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync, spawn } = require('child_process');
+const { is2ndBrainProject } = require('../lib/config');
+
+const DEFAULT_INTERVAL_MINUTES = 5;
+const LOCK_FILE = '.2ndbrain-watch-lock';
+
+function detectAgentCLI() {
+  const isWin = process.platform === 'win32';
+  const whichCmd = isWin ? 'where' : 'which';
+
+  try {
+    execFileSync(whichCmd, ['openclaw'], { stdio: 'pipe' });
+    return 'openclaw';
+  } catch { /* not found */ }
+
+  try {
+    execFileSync(whichCmd, ['claude'], { stdio: 'pipe' });
+    return 'claude';
+  } catch { /* not found */ }
+
+  return null;
+}
+
+function buildOrganizePrompt(vaultPath) {
+  return [
+    '你已安装 2ndbrain skill。请按照该 skill 的整理指令集执行：',
+    '1. 读取所有 10_Inbox/*/00_To-Do.md 中 ## Inbox 下的未分类任务',
+    '2. 分类、打标签、移动到项目 Heading',
+    '3. 完成的任务归档到 09_Done.md',
+    '4. 生成整理报告写入当日日记',
+    `Vault 路径: ${vaultPath}`,
+  ].join('\n');
+}
+
+function triggerAgent(agentCLI, vaultPath, log) {
+  const prompt = buildOrganizePrompt(vaultPath);
+
+  let child;
+  if (agentCLI === 'openclaw') {
+    child = spawn('openclaw', ['agent', '--agent', 'main', '--message', prompt, '--local'], {
+      stdio: 'ignore',
+      detached: true,
+      cwd: vaultPath,
+    });
+  } else {
+    child = spawn('claude', ['-p', prompt], {
+      stdio: 'ignore',
+      detached: true,
+      cwd: vaultPath,
+    });
+  }
+
+  child.unref();
+  log.info(`  → 已触发 ${agentCLI} 执行整理 (PID: ${child.pid})`);
+  return child.pid;
+}
+
+function findToDoFiles(vaultPath) {
+  const inboxDir = path.join(vaultPath, '10_Inbox');
+  if (!fs.existsSync(inboxDir)) return [];
+
+  const files = [];
+  try {
+    const entries = fs.readdirSync(inboxDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === 'Agents') continue;
+      const todoFile = path.join(inboxDir, entry.name, '00_To-Do.md');
+      if (fs.existsSync(todoFile)) {
+        files.push(todoFile);
+      }
+    }
+  } catch { /* ignore read errors */ }
+  return files;
+}
+
+async function watch(targetPath, options, log) {
+  const vaultPath = path.resolve(targetPath);
+  const intervalMinutes = options.interval || DEFAULT_INTERVAL_MINUTES;
+  const once = options.once || false;
+
+  if (!is2ndBrainProject(vaultPath)) {
+    log.error(`${vaultPath} 不是 2ndBrain 知识库。请先运行: 2ndbrain init ${targetPath}`);
+    process.exit(1);
+  }
+
+  const agentCLI = detectAgentCLI();
+  if (!agentCLI) {
+    log.error('未找到 Agent CLI (openclaw / claude)。');
+    log.warn('请安装 OpenClaw (https://docs.openclaw.ai/start) 或 Claude Code (https://code.claude.com)');
+    process.exit(1);
+  }
+
+  const todoFiles = findToDoFiles(vaultPath);
+  if (todoFiles.length === 0) {
+    log.error('未找到任何 To-Do 文件。请先运行: 2ndbrain member <name>');
+    process.exit(1);
+  }
+
+  log.info('\n🧠 2ndBrain Watch 模式\n');
+  log.info(`  知识库: ${vaultPath}`);
+  log.info(`  Agent CLI: ${agentCLI}`);
+  log.info(`  防抖间隔: ${intervalMinutes} 分钟`);
+  log.info(`  监听文件:`);
+  for (const f of todoFiles) {
+    log.info(`    - ${path.relative(vaultPath, f)}`);
+  }
+  log.info('\n  按 Ctrl+C 退出\n');
+
+  const lockFile = path.join(vaultPath, LOCK_FILE);
+  let debounceTimer = null;
+  const watchers = [];
+
+  function isLocked() {
+    if (!fs.existsSync(lockFile)) return false;
+    try {
+      const lockTime = parseInt(fs.readFileSync(lockFile, 'utf8'), 10);
+      // Lock expires after 30 minutes
+      if (Date.now() - lockTime > 30 * 60 * 1000) {
+        fs.unlinkSync(lockFile);
+        return false;
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function acquireLock() {
+    fs.writeFileSync(lockFile, String(Date.now()));
+  }
+
+  function releaseLock() {
+    try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+  }
+
+  function onFileChange(filename) {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    const now = new Date().toLocaleTimeString();
+    log.info(`  [${now}] 检测到变化: ${filename}`);
+    log.info(`  [${now}] 等待 ${intervalMinutes} 分钟后触发整理...`);
+
+    debounceTimer = setTimeout(() => {
+      if (isLocked()) {
+        log.warn('  上一次整理尚未完成，跳过本次触发');
+        return;
+      }
+
+      acquireLock();
+      const triggerTime = new Date().toLocaleTimeString();
+      log.success(`  [${triggerTime}] 防抖结束，触发整理`);
+
+      triggerAgent(agentCLI, vaultPath, log);
+
+      // Release lock after a reasonable time
+      setTimeout(() => releaseLock(), 10 * 60 * 1000);
+
+      if (once) {
+        log.info('\n  --once 模式，退出\n');
+        cleanup();
+        process.exit(0);
+      }
+    }, intervalMinutes * 60 * 1000);
+  }
+
+  // Set up file watchers
+  for (const todoFile of todoFiles) {
+    try {
+      const watcher = fs.watch(todoFile, (eventType) => {
+        if (eventType === 'change') {
+          onFileChange(path.relative(vaultPath, todoFile));
+        }
+      });
+      watchers.push(watcher);
+    } catch (err) {
+      log.warn(`  无法监听 ${path.relative(vaultPath, todoFile)}: ${err.message}`);
+    }
+  }
+
+  function cleanup() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    for (const w of watchers) {
+      try { w.close(); } catch { /* ignore */ }
+    }
+    releaseLock();
+  }
+
+  process.on('SIGINT', () => {
+    log.info('\n\n  正在退出...\n');
+    cleanup();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(0);
+  });
+}
+
+module.exports = watch;

package/src/index.js

@@ -7,6 +7,8 @@ const update = require('./commands/update');
 const remove = require('./commands/remove');
 const member = require('./commands/member');
 const completion = require('./commands/completion');
+const check = require('./commands/check');
+const watch = require('./commands/watch');
 
 module.exports = {
   init,
@@ -14,4 +16,6 @@ module.exports = {
   remove,
   member,
   completion,
+  check,
+  watch,
 };

package/src/lib/config.js

@@ -24,6 +24,7 @@ const FRAMEWORK_FILES = [
   '99_System/Templates/tpl_daily_note.md',
   '99_System/Templates/tpl_member_tasks.md',
   '99_System/Templates/tpl_member_done.md',
+  '99_System/Templates/tpl_member_todo.md',
   '99_System/Scripts/init_member.sh',
 ];