@our2ndbrain/cli 1.1.3 → 2026.4.5

package/src/commands/update.js

@@ -8,12 +8,19 @@ const path = require('path');
 const fs = require('fs-extra');
 const chalk = require('chalk');
 const {
+  PACKAGE_ROOT,
   TEMPLATE_ROOT,
   FRAMEWORK_FILES,
   SMART_COPY_DIRS,
+  getFrameworkSourcePath,
   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');
@@ -30,6 +37,7 @@ const { copyObsidianDirSmart, MERGE_STRATEGIES } = require('../lib/obsidian');
 async function update(targetPath, options, log) {
   const resolvedPath = path.resolve(targetPath);
   const templateRoot = options.template ? path.resolve(options.template) : TEMPLATE_ROOT;
+  const packageRoot = options.template ? path.resolve(templateRoot, '..') : PACKAGE_ROOT;
 
   log.info(`Updating 2ndBrain project at: ${resolvedPath}`);
   log.info(`Using template from: ${templateRoot}`);
@@ -42,21 +50,22 @@ async function update(targetPath, options, log) {
   }
 
   if (options.dryRun) {
-    await performDryRun(resolvedPath, templateRoot, log);
+    await performDryRun(resolvedPath, templateRoot, packageRoot, log);
     return;
   }
 
   // Main update flow
-  await performUpdate(resolvedPath, templateRoot, options, log);
+  await performUpdate(resolvedPath, templateRoot, packageRoot, options, log);
 }
 
 /**
  * Perform dry run - show what would be updated
  * @param {string} resolvedPath - Target project path
  * @param {string} templateRoot - Template root path
+ * @param {string} packageRoot - Package root path
  * @param {Function} log - Logger function
  */
-async function performDryRun(resolvedPath, templateRoot, log) {
+async function performDryRun(resolvedPath, templateRoot, packageRoot, log) {
   log.warn('[DRY RUN] No files will be modified.');
   log.info('');
 
@@ -64,7 +73,7 @@ async function performDryRun(resolvedPath, templateRoot, log) {
 
   const result = await copyFilesSmart(
     FRAMEWORK_FILES,
-    templateRoot,
+    (file) => getFrameworkSourcePath(file, { templateRoot, packageRoot }),
     resolvedPath,
     { dryRun: true },
     (file, action, detail) => {
@@ -158,17 +167,18 @@ async function performDryRun(resolvedPath, templateRoot, log) {
  * Perform the actual update with user confirmation
  * @param {string} resolvedPath - Target project path
  * @param {string} templateRoot - Template root path
+ * @param {string} packageRoot - Package root path
  * @param {Object} options - Command options
  * @param {boolean} [options.yes] - Auto-confirm all updates
  * @param {Function} log - Logger function
  */
-async function performUpdate(resolvedPath, templateRoot, options, log) {
+async function performUpdate(resolvedPath, templateRoot, packageRoot, options, log) {
   log.info('Analyzing framework files...');
 
   // First pass: analyze all files
   const analysis = await copyFilesSmart(
     FRAMEWORK_FILES,
-    templateRoot,
+    (file) => getFrameworkSourcePath(file, { templateRoot, packageRoot }),
     resolvedPath,
     {},
     (file, action, detail) => {
@@ -213,12 +223,13 @@ async function performUpdate(resolvedPath, templateRoot, options, log) {
   if (userChoice === 'all') {
     // Apply all changes
     for (const change of changes) {
-      const src = path.join(templateRoot, change.file);
+      const src = getFrameworkSourcePath(change.file, { templateRoot, packageRoot });
+      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)`);
@@ -239,12 +250,13 @@ async function performUpdate(resolvedPath, templateRoot, options, log) {
     // Review each file individually
     for (const change of changes) {
       const file = change.file;
-      const src = path.join(templateRoot, file);
+      const src = getFrameworkSourcePath(file, { templateRoot, packageRoot });
+      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 +284,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 +312,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

@@ -6,8 +6,20 @@
 
 const path = require('path');
 
-// Template root directory (npm package root)
-const TEMPLATE_ROOT = path.resolve(__dirname, '../../');
+// npm package root containing CLI docs and metadata
+const PACKAGE_ROOT = path.resolve(__dirname, '../..');
+
+// Vault template root containing shipped vault assets
+const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, 'template');
+
+const PACKAGE_DOC_FILES = [
+  'AGENTS.md',
+  'README.md',
+  'README_en.md',
+  'CHANGELOG.md',
+  'CLAUDE.md',
+  'LICENSE',
+];
 
 /**
  * Framework files - managed by init/update/remove commands
@@ -16,6 +28,7 @@ const TEMPLATE_ROOT = path.resolve(__dirname, '../../');
 const FRAMEWORK_FILES = [
   'AGENTS.md',
   'README.md',
+  'README_en.md',
   'CHANGELOG.md',
   'CLAUDE.md',
   'LICENSE',
@@ -24,6 +37,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',
 ];
 
@@ -83,6 +97,32 @@ function getTemplatePath(relativePath, templateRoot = TEMPLATE_ROOT) {
   return path.join(templateRoot, relativePath);
 }
 
+/**
+ * Check whether a framework file is sourced from the package root docs.
+ * @param {string} relativePath - Relative framework file path
+ * @returns {boolean}
+ */
+function isPackageDocFile(relativePath) {
+  return PACKAGE_DOC_FILES.includes(relativePath);
+}
+
+/**
+ * Resolve the source path for a framework file.
+ * Package docs come from the npm package root; vault assets come from template/.
+ * @param {string} relativePath - Relative framework file path
+ * @param {Object} [options]
+ * @param {string} [options.templateRoot] - Template directory override
+ * @param {string} [options.packageRoot] - Package root override
+ * @returns {string} Absolute source path
+ */
+function getFrameworkSourcePath(
+  relativePath,
+  { templateRoot = TEMPLATE_ROOT, packageRoot = PACKAGE_ROOT } = {}
+) {
+  const sourceRoot = isPackageDocFile(relativePath) ? packageRoot : templateRoot;
+  return path.join(sourceRoot, relativePath);
+}
+
 /**
  * Check if a path is a 2ndBrain project
  * @param {string} targetPath - Path to check
@@ -99,7 +139,9 @@ function is2ndBrainProject(targetPath) {
 }
 
 module.exports = {
+  PACKAGE_ROOT,
   TEMPLATE_ROOT,
+  PACKAGE_DOC_FILES,
   FRAMEWORK_FILES,
   FRAMEWORK_DIRS,
   USER_DATA_DIRS,
@@ -108,5 +150,7 @@ module.exports = {
   INIT_ONLY_FILES,
   MARKER_FILE,
   getTemplatePath,
+  isPackageDocFile,
+  getFrameworkSourcePath,
   is2ndBrainProject,
 };

package/src/lib/files.js

@@ -8,6 +8,29 @@ const fs = require('fs-extra');
 const path = require('path');
 const { compareFiles, summarizeChanges, isBinaryFile, isLargeFile } = require('./diff');
 
+const README_ALIAS_FILES = new Set(['AGENTS.md', 'CLAUDE.md']);
+
+/**
+ * Resolve a template source file, falling back to README.md for symlink aliases
+ * that are not preserved by npm pack.
+ * @param {string} src - Preferred source file path
+ * @returns {Promise<string|null>} Resolved source path, or null if unavailable
+ */
+async function resolveSourcePath(src) {
+  if (await fs.pathExists(src)) {
+    return src;
+  }
+
+  if (README_ALIAS_FILES.has(path.basename(src))) {
+    const readmePath = path.join(path.dirname(src), 'README.md');
+    if (await fs.pathExists(readmePath)) {
+      return readmePath;
+    }
+  }
+
+  return null;
+}
+
 /**
  * Copy a file from source to destination
  * @param {string} src - Source file path
@@ -22,21 +45,23 @@ async function copyFile(src, dest) {
 /**
  * Copy multiple files from template to target
  * @param {string[]} files - Array of relative file paths
- * @param {string} templateRoot - Template root directory
+ * @param {string|Function} sourceRootOrResolver - Source root directory or resolver
  * @param {string} targetRoot - Target root directory
  * @param {Function} [onFile] - Callback for each file (relativePath, action)
  * @returns {Promise<{copied: string[], skipped: string[], errors: string[]}>}
  */
-async function copyFiles(files, templateRoot, targetRoot, onFile) {
+async function copyFiles(files, sourceRootOrResolver, targetRoot, onFile) {
   const result = { copied: [], skipped: [], errors: [] };
 
   for (const file of files) {
-    const src = path.join(templateRoot, file);
+    const requestedSrc = typeof sourceRootOrResolver === 'function'
+      ? sourceRootOrResolver(file)
+      : path.join(sourceRootOrResolver, file);
+    const src = await resolveSourcePath(requestedSrc);
     const dest = path.join(targetRoot, file);
 
     try {
-      // Check if source exists
-      if (!await fs.pathExists(src)) {
+      if (!src) {
         result.skipped.push(file);
         if (onFile) onFile(file, 'skip', 'source not found');
         continue;
@@ -218,25 +243,31 @@ async function compareFilesWrapper(src, dest) {
  * @param {string} dest - Destination file path
  * @param {Object} options - Copy options
  * @param {boolean} [options.force] - Force copy even if equal
+ * @param {boolean} [options.dryRun] - Compare only, do not write destination
  * @returns {Promise<{copied: boolean, unchanged: boolean, error?: string, change?: any}>}
  */
 async function copyFileWithCompare(src, dest, options = {}) {
   try {
-    // Check if source exists
-    if (!await fs.pathExists(src)) {
+    const resolvedSrc = await resolveSourcePath(src);
+    if (!resolvedSrc) {
       return { copied: false, unchanged: false, error: 'source not found' };
     }
 
     // Compare files if destination exists
-    const comparison = await compareFilesWrapper(src, dest);
+    const comparison = await compareFilesWrapper(resolvedSrc, dest);
 
     if (comparison.exists && comparison.equal && !options.force) {
       return { copied: false, unchanged: true };
     }
 
-    // Perform the copy
-    await fs.ensureDir(path.dirname(dest));
-    await fs.copy(src, dest);
+    let previousDestContent = '';
+    if (comparison.exists && !comparison.binary && !comparison.large) {
+      try {
+        previousDestContent = await fs.readFile(dest, 'utf8');
+      } catch {
+        previousDestContent = '';
+      }
+    }
 
     // Generate change summary
     let change = null;
@@ -247,11 +278,8 @@ async function copyFileWithCompare(src, dest, options = {}) {
         change = { large: true };
       } else {
         try {
-          const [srcContent, destContent] = await Promise.all([
-            fs.readFile(src, 'utf8'),
-            comparison.exists ? fs.readFile(dest, 'utf8') : '',
-          ]);
-          const summary = summarizeChanges(destContent, srcContent);
+          const srcContent = await fs.readFile(resolvedSrc, 'utf8');
+          const summary = summarizeChanges(previousDestContent, srcContent);
           change = { added: summary.added, removed: summary.removed };
         } catch {
           // If we can't read as text, mark as binary
@@ -260,6 +288,14 @@ async function copyFileWithCompare(src, dest, options = {}) {
       }
     }
 
+    if (options.dryRun) {
+      return { copied: false, unchanged: false, change };
+    }
+
+    // Perform the copy
+    await fs.ensureDir(path.dirname(dest));
+    await fs.copy(resolvedSrc, dest);
+
     return { copied: true, unchanged: false, change };
   } catch (err) {
     return { copied: false, unchanged: false, error: err.message };
@@ -269,7 +305,7 @@ async function copyFileWithCompare(src, dest, options = {}) {
 /**
  * Copy multiple files with smart comparison
  * @param {string[]} files - Array of relative file paths
- * @param {string} templateRoot - Template root directory
+ * @param {string|Function} sourceRootOrResolver - Source root directory or resolver
  * @param {string} targetRoot - Target root directory
  * @param {Object} options - Copy options
  * @param {boolean} [options.force] - Force copy even if equal
@@ -277,7 +313,7 @@ async function copyFileWithCompare(src, dest, options = {}) {
  * @param {Function} [onFile] - Callback for each file (relativePath, action, detail)
  * @returns {Promise<{copied: string[], skipped: string[], unchanged: string[], errors: string[], changes: Array}>}
  */
-async function copyFilesSmart(files, templateRoot, targetRoot, options = {}, onFile) {
+async function copyFilesSmart(files, sourceRootOrResolver, targetRoot, options = {}, onFile) {
   const result = {
     copied: [],
     skipped: [],
@@ -287,7 +323,9 @@ async function copyFilesSmart(files, templateRoot, targetRoot, options = {}, onF
   };
 
   for (const file of files) {
-    const src = path.join(templateRoot, file);
+    const src = typeof sourceRootOrResolver === 'function'
+      ? sourceRootOrResolver(file)
+      : path.join(sourceRootOrResolver, file);
     const dest = path.join(targetRoot, file);
 
     try {
@@ -335,6 +373,7 @@ module.exports = {
   createFile,
   isDirEmpty,
   compareFilesWrapper,
+  resolveSourcePath,
   copyFileWithCompare,
   copyFilesSmart,
 };