@our2ndbrain/cli 1.1.3 → 2026.4.5

package/README_en.md

@@ -0,0 +1,108 @@
+# 🧠 2ndBrain
+
+> A lightweight entrypoint for AI agents and human collaborators: use the 2ndBrain template, CLI, and Skill to operate an Obsidian knowledge base together.
+
+[English](README_en.md) | [简体中文](README.md)
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![npm version](https://img.shields.io/npm/v/@our2ndbrain/cli.svg)](https://www.npmjs.com/package/@our2ndbrain/cli)
+
+## What This Repository Is
+
+If you hand this repository to an AI agent, this README should be the first file it reads.
+
+2ndBrain ships three things:
+
+- an Obsidian vault template with PARA folders, inboxes, and dashboards
+- a CLI for checking the environment, initializing a vault, and updating framework files
+- a 2ndBrain Skill that teaches the agent how to capture, organize, review, and process content
+
+This README keeps only the minimum needed for AI collaboration. For the fuller project and methodology reference, see the [detailed guide](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/docs/guide_en.md).
+
+## Quick Start
+
+The default path is `npx`:
+
+```bash
+npx @our2ndbrain/cli@latest check
+npx @our2ndbrain/cli@latest init my-brain
+cd my-brain
+npx @our2ndbrain/cli@latest member Alice
+```
+
+If the CLI is already installed globally, you can also use:
+
+```bash
+2ndbrain check
+2ndbrain init my-brain
+cd my-brain
+2ndbrain member Alice
+```
+
+## Initialize a Vault
+
+### Create a new 2ndBrain vault
+
+```bash
+npx @our2ndbrain/cli@latest check
+npx @our2ndbrain/cli@latest init my-brain
+cd my-brain
+npx @our2ndbrain/cli@latest member Alice
+```
+
+### Integrate into an existing Obsidian vault
+
+```bash
+cd my-existing-vault
+npx @our2ndbrain/cli@latest check
+npx @our2ndbrain/cli@latest init
+npx @our2ndbrain/cli@latest member Alice
+```
+
+After initialization, guide the user to:
+
+1. open the directory in Obsidian
+2. click "Trust author and enable plugins"
+3. create the first daily note and start capturing tasks and thoughts
+
+## Install the Skill
+
+The preferred installation path is the SSH git URL form:
+
+```bash
+npx skills add git@github.com:Our2ndBrain/2ndBrain-Template.git --skill 2ndbrain
+```
+
+To target a specific agent explicitly:
+
+```bash
+npx skills add git@github.com:Our2ndBrain/2ndBrain-Template.git --skill 2ndbrain -a claude-code
+npx skills add git@github.com:Our2ndBrain/2ndBrain-Template.git --skill 2ndbrain -a cursor
+npx skills add git@github.com:Our2ndBrain/2ndBrain-Template.git --skill 2ndbrain -a openclaw
+```
+
+If you are not using the `skills` CLI in that environment yet, you can still fall back to manually copying `skills/2ndbrain/`.
+
+The skill entrypoint is [SKILL.md](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/SKILL.md).
+
+## How AI Should Collaborate With Humans
+
+An AI agent using this template should at least follow these rules:
+
+- Run `2ndbrain check` or `npx @our2ndbrain/cli@latest check` before setup, initialization, or takeover.
+- Capture before organizing. If placement is unclear, write it to `10_Inbox/{member}/` first.
+- Write tasks to `10_Inbox/{member}/00_To-Do.md`. Do not hand-edit query-driven files such as `00_Dashboard/*.md` or `10_Inbox/*/01_Tasks.md`.
+- Follow the user's language instead of switching languages on your own.
+- Prefer the 2ndBrain Skill for capture, organize, review, content processing, and scheduled cleanup.
+- When you need detailed rules, read the Skill and its references instead of inferring policy from this README.
+
+## Deep Reading
+
+- [Detailed Guide (English)](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/docs/guide_en.md)
+- [详细指南（中文）](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/docs/guide.md)
+- [2ndBrain Skill](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/SKILL.md)
+- [Setup Reference](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/setup.md)
+- [Operations and Daily Review](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/operations.md)
+- [Content Processing](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/content-processing.md)
+- [Scheduling and Automation](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/scheduling.md)
+- [Task Conventions](https://github.com/Our2ndBrain/2ndBrain-Template/blob/main/skills/2ndbrain/references/task-conventions.md)

package/bin/2ndbrain.js

@@ -7,7 +7,7 @@
  */
 
 const { program } = require('commander');
-const { init, update, remove, member, completion } = require('../src');
+const { init, update, remove, member, completion, check, watch } = require('../src');
 const pkg = require('../package.json');
 
 // ANSI color codes for terminal output
@@ -93,6 +93,35 @@ program
     }
   });
 
+// Check command
+program
+  .command('check [path]')
+  .description('Check environment prerequisites (Node.js, Git, Obsidian, Agent CLI)')
+  .action(async (targetPath = '.', options) => {
+    try {
+      const passed = await check(targetPath, options, log);
+      if (!passed) process.exit(1);
+    } catch (err) {
+      log.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+// Watch command
+program
+  .command('watch [path]')
+  .description('Watch To-Do files for changes and auto-trigger inbox organization')
+  .option('-i, --interval <minutes>', 'Debounce interval in minutes (default: 5)', parseInt)
+  .option('--once', 'Exit after first triggered organization')
+  .action(async (targetPath = '.', options) => {
+    try {
+      await watch(targetPath, options, log);
+    } catch (err) {
+      log.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
 // Completion command
 program
   .command('completion <shell>')

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@our2ndbrain/cli",
-    "version": "1.1.3",
+    "version": "2026.4.5",
     "description": "CLI tool for 2ndBrain - A personal knowledge management system based on PARA + C-O-R-D + Append-and-Review",
     "keywords": [
         "2ndbrain",
@@ -24,31 +24,34 @@
     "files": [
         "bin/",
         "src/",
-        ".obsidian/",
-        "00_Dashboard/",
-        "10_Inbox/Agents/",
-        "99_System/",
+        "template/",
         "AGENTS.md",
         "CHANGELOG.md",
         "CLAUDE.md",
         "LICENSE",
-        "README.md"
+        "README.md",
+        "README_en.md"
     ],
     "bugs": {
         "url": "https://github.com/Our2ndBrain/2ndBrain-Template/issues"
     },
     "engines": {
-        "node": ">=16.0.0"
+        "node": ">=18.0.0"
     },
     "scripts": {
-        "version": "node scripts/version.js && git add CHANGELOG.md",
-        "postversion": "git push && git push --tags && npm publish"
+        "lint": "node scripts/lint.js && node scripts/check-workflow-pinning.js",
+        "pack:check": "node scripts/check-package.js",
+        "release": "node scripts/release.js",
+        "release:check": "node scripts/check-release.js",
+        "smoke:install": "node scripts/smoke-install.js",
+        "test": "node --test",
+        "version": "node scripts/version.js && git add CHANGELOG.md"
     },
     "dependencies": {
         "chalk": "^4.1.2",
         "commander": "^12.0.0",
-        "diff": "^5.2.0",
-        "fs-extra": "^11.2.0"
+        "diff": "^8.0.4",
+        "fs-extra": "^11.3.4"
     },
     "publishConfig": {
         "access": "public"

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

@@ -7,6 +7,7 @@
 const path = require('path');
 const fs = require('fs-extra');
 const {
+  PACKAGE_ROOT,
   TEMPLATE_ROOT,
   FRAMEWORK_FILES,
   FRAMEWORK_DIRS,
@@ -14,6 +15,7 @@ const {
   COPY_DIRS,
   SMART_COPY_DIRS,
   INIT_ONLY_FILES,
+  getFrameworkSourcePath,
   is2ndBrainProject,
 } = require('../lib/config');
 const { copyFiles, ensureDirs, createFile, isDirEmpty, copyFilesSmart } = require('../lib/files');
@@ -141,6 +143,7 @@ async function handleObsidianReset(obsidianSrc, obsidianDest, log, skipConfirmat
 async function init(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(`Initializing 2ndBrain project at: ${resolvedPath}`);
   log.info(`Using template from: ${templateRoot}`);
@@ -166,9 +169,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) {
@@ -217,7 +220,7 @@ async function init(targetPath, options, log) {
   log.info('Copying framework files...');
   const fileResult = await copyFilesSmart(
     FRAMEWORK_FILES,
-    templateRoot,
+    (file) => getFrameworkSourcePath(file, { templateRoot, packageRoot }),
     resolvedPath,
     {},
     (file, action, detail) => {
@@ -289,7 +292,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('');