@our2ndbrain/cli 1.1.3 → 2026.4.4

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
@@ -31,12 +54,11 @@ async function copyFiles(files, templateRoot, targetRoot, onFile) {
   const result = { copied: [], skipped: [], errors: [] };
 
   for (const file of files) {
-    const src = path.join(templateRoot, file);
+    const src = await resolveSourcePath(path.join(templateRoot, file));
     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 +240,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 +275,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 +285,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 };
@@ -335,6 +368,7 @@ module.exports = {
   createFile,
   isDirEmpty,
   compareFilesWrapper,
+  resolveSourcePath,
   copyFileWithCompare,
   copyFilesSmart,
 };

package/AGENTS.md

@@ -1,193 +0,0 @@
-# AGENTS.md
-
-> This is the project guide for AI assistants. When helping users operate this project, please follow these rules.
-
-## Installing 2ndBrain CLI
-
-```bash
-# Use npx to run directly (recommended)
-npx @our2ndbrain/cli@latest <command>
-
-# Or install globally
-npm install -g @our2ndbrain/cli
-2ndbrain <command>
-```
-
-## Project Overview
-
-**2ndBrain** is a personal knowledge management system based on PARA + C-O-R-D + Append-and-Review, using Obsidian as the frontend tool.
-
-## Directory Structure Conventions
-
-```
-2ndBrain/
-├── 00_Dashboard/          # Dashboards: task aggregation entry point
-├── 10_Inbox/              # Inbox: journals land here
-│   └── {MemberName}/      #   One subdirectory per member
-├── 20_Areas/              # Areas: long-term focus areas
-├── 30_Projects/           # Projects: things with clear goals
-├── 40_Resources/          # Resources: reference materials
-├── 90_Archives/           # Archives: completed or inactive items
-└── 99_System/             # System: templates, scripts and config
-    ├── Scripts/           #   Automation scripts
-    └── Templates/         #   Note templates
-```
-
-## Core Rules
-
-### 1. Task Format
-
-All tasks use Markdown checkbox format:
-
-```markdown
-- [ ] Task description #tag 📅 2026-01-15
-```
-
-### 2. Tag Conventions
-
-| Tag | Purpose |
-|-----|---------|
-| `#next` | Next task to do |
-| `#waiting` | Waiting on others |
-| `#someday` | Later task |
-| `#read` / `#watch` / `#listen` | Read/watch/listen lists |
-| `📅 YYYY-MM-DD` | Due date |
-
-### 3. Journal Heading Structure
-
-Use the following headings in journals to categorize content. Dashboards will auto-recognize them:
-
-- `## 💼 Works` - Work tasks
-- `## 💡 Thoughts` - Ideas and inspirations
-- `## 📚 Readings` - Reading list
-
-### 4. File Placement Rules
-
-- **All new content** → First put in journals under `10_Inbox/{member}/`
-- **Clear goals** → `30_Projects/`
-- **Long-term maintenance** → `20_Areas/`
-- **Reference materials** → `40_Resources/`
-- **No longer active** → `90_Archives/`
-
-## Common Operations
-
-### Creating a New Member
-
-Use CLI command:
-
-```bash
-npx @our2ndbrain/cli@latest member {MemberName}
-```
-
-This creates:
-- `10_Inbox/{MemberName}/01_Tasks.md` - Personal task dashboard
-- `10_Inbox/{MemberName}/09_Done.md` - Personal completion record
-- `.obsidian/daily-notes.json` - Configures journal to save to that member directory
-
-> 💡 Use `--no-config` option for team collaboration to avoid overwriting other members' config.
-
-## AI Assistant Notes
-
-1. **Don't modify Dataview queries in dashboard files**
-   - Global dashboards: `00_Dashboard/01_All_Tasks.md` and `09_All_Done.md`
-   - Personal dashboards: `10_Inbox/{member}/01_Tasks.md` and `09_Done.md`
-   - These are auto-generated dashboards. Only modify tasks in journals, dashboards will auto-update.
-
-2. **Use template when creating journals**
-   - Template located at `99_System/Templates/tpl_daily_note.md`
-   - Journal naming format: `YYYY-MM-DD.md`
-
-3. **After task completion**
-   - Change `- [ ]` to `- [x]`
-   - Tasks plugin will auto-add completion date `✅ YYYY-MM-DD`
-
-4. **Follow user's language preference**
-   - Adapt responses to user's language settings
-   - Match the language used in the conversation
-
-## Agent Collaboration Design
-
-AI assistants and humans **coexist collaboratively** in 2ndBrain. Agents can directly operate all directories (`20_Areas/`, `30_Projects/`, `40_Resources/`, etc.), only need a shared workspace to record work logs.
-
-### Shared Workspace
-
-All Agents share the `10_Inbox/Agents/` directory (note: plural), using a single-file Journal mode:
-
-```
-10_Inbox/Agents/
-└── Journal.md    # All Agents' work logs (append-and-review)
-```
-
-### Journal Format
-
-Uses **append-and-review** mode:
-- **Append**: New content appended to file end, separated by delimiters per entry
-- **Review**: Periodically review TODOs, check off when complete; valuable content can be output to other directories
-
-```markdown
-# Agent Journal
-
----
-2026-01-14 15:30 | Cursor
-
-Executed xxx task...
-
-- [ ] Discovered issue #next
-
----
-2026-01-14 16:45 | Claude Desktop
-
-Optimized yyy...
-
-## 💡 Improvement Suggestions
-
-- Suggest zzz
-```
-
-### Why This Design?
-
-| Feature | Reason |
-|---------|--------|
-| **Shared directory** | Agents aren't "people", don't need isolated personal spaces |
-| **Single file** | Read once for full context, highest efficiency |
-| **Append-and-Review** | Simple writing + periodic organization, follows C-O-R-D workflow |
-| **Timestamp + Agent name** | Know who did what when |
-
-### Review Workflow
-
-Journal content can be output to other directories during review:
-
-| Content Type | Output Target |
-|-------------|---------------|
-| Completed TODOs | Check off `[x]` stay in place |
-| Discovered issues/solutions | → `30_Projects/` related projects |
-| Reusable experience | → `40_Resources/` or `20_Areas/` |
-| Error post-mortem | Keep in Journal as history |
-
-### When to Write Journal
-
-- After executing complex tasks (migration, refactoring, batch modifications)
-- When discovering issues that need fixing
-- When having improvement suggestions
-- When encountering failures or anomalies
-
-### Work Principles
-
-1. **Prefer improving tools over bypassing them** - Manual operations are non-reproducible and error-prone. When encountering scenarios not supported by tools, improve the tool first then execute.
-2. **Pay attention to naming consistency** - Tool design should consider naming differences to avoid sync failures due to inconsistent naming.
-
-### Tasks in Journal
-
-Agents can write todo tasks in Journal, Dashboard dashboards will auto-recognize:
-
-```markdown
-- [ ] Discovered xxx needs fixing #next
-- [ ] Suggest adding yyy feature #someday 📅 2026-01-30
-```
-
-> 💡 **Note**: Tasks with `#someday` tag will appear in "Future Plans" section, regardless of whether they have a due date. This is the dedicated area for "later" tasks.
-
-## Reference Links
-
-- [README.md](README.md) - Complete project documentation
-- [Template repository](https://github.com/Our2ndBrain/2ndBrain-Template) - Open source template

package/CLAUDE.md

@@ -1,153 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-**2ndBrain** is a personal knowledge management system CLI tool published as `@our2ndbrain/cli`. It combines three methodologies:
-- **PARA**: Projects, Areas, Resources, Archives organizational structure
-- **C-O-R-D**: Collect → Organize → Review → Do workflow
-- **Append-and-Review**: Karpathy's note-taking approach (append first, organize during review)
-
-The CLI provides an Obsidian-based template with a Node.js CLI tool for setup and management. The tool is designed for both individual and team use, with Git integration for synchronization.
-
-## CLI Commands
-
-### Installation and Usage
-```bash
-# Use npx directly (recommended)
-npx @our2ndbrain/cli@latest <command>
-
-# Or install globally
-npm install -g @our2ndbrain/cli
-2ndbrain <command>
-```
-
-### Available Commands
-- `2ndbrain init [path]` - Initialize new project from template
-- `2ndbrain member <name> [path]` - Add new member directory
-- `2ndbrain update [path]` - Update framework files with diff preview
-- `2ndbrain remove [path]` - Remove framework files
-
-### Command Options
-**init**: `-f, --force` (overwrite), `-t, --template <path>` (custom template)
-**member**: `-f, --force` (overwrite), `--no-config` (skip Obsidian config)
-**update**: `-d, --dry-run` (preview), `-t, --template <path>` (custom template)
-**remove**: `-d, --dry-run` (preview), `-f, --force` (skip confirmation)
-
-### Publishing
-```bash
-npm version <major|minor|patch>  # Updates CHANGELOG.md via scripts/version.js
-# postversion hook runs: git push && git push --tags && npm publish
-```
-
-## Architecture
-
-### Entry Points
-- `bin/2ndbrain.js` - CLI entry point (Commander.js)
-- `src/index.js` - Main module that exports commands
-
-### Core Modules
-
-**src/lib/config.js** - Framework file definitions
-- `FRAMEWORK_FILES`: Files managed by init/update/remove (AGENTS.md, README.md, CHANGELOG.md, CLAUDE.md, dashboards, templates)
-- `FRAMEWORK_DIRS`: Directories created during init (00_Dashboard, 10_Inbox/Agents, 99_System)
-- `USER_DATA_DIRS`: Never touched by CLI (20_Areas, 30_Projects, 40_Resources, 90_Archives)
-- `COPY_DIRS`: Directories copied entirely (e.g., .obsidian with plugins)
-- `MARKER_FILE`: `AGENTS.md` - identifies a 2ndBrain project
-
-**src/lib/files.js** - File operations
-- `copyFiles()` - Basic file copying
-- `copyFilesSmart()` - Copy with comparison, dry-run support, change tracking
-- `removeFiles()` - File removal with tracking
-- `ensureDirs()` / `removeEmptyDirs()` - Directory management
-
-**src/lib/diff.js** - File comparison utilities
-- Uses `diff` npm package for line/word comparison
-- `compareFiles()` - Detects binary/large files, compares contents
-- `summarizeChanges()` - Returns added/removed line counts
-- `generateDiff()` / `formatDiffForTerminal()` - Unified diff with colors
-- Large file threshold: 100KB
-
-**src/lib/prompt.js** - Interactive prompts
-- `confirm()` - Yes/no prompts with defaults
-- `select()` - Multi-option selection
-- `confirmBatchUpdates()` - Bulk update confirmation
-- Special handling for binary/large files
-
-**src/commands/init.js** - Project initialization
-- Validates target directory (checks for existing 2ndBrain projects or non-empty dirs)
-- Creates framework and user data directories
-- Copies framework files and .obsidian config
-- Creates init-only files (e.g., 10_Inbox/Agents/Journal.md)
-
-**src/commands/member.js** - Member directory creation
-- Validates project is a 2ndBrain project
-- Creates `10_Inbox/{member}/` directory
-- Processes template files with `{{MEMBER_NAME}}` placeholder replacement
-- Updates `.obsidian/daily-notes.json` (unless `--no-config`)
-
-**src/commands/update.js** - Framework file updates
-- Compares template files with existing files
-- Shows diff with colored output for changes
-- Supports batch (all), review (individual), or skip modes
-- Also updates member dashboards using latest templates
-
-**src/commands/remove.js** - Framework file removal
-- Removes only framework files (never user data directories)
-- Cleans up empty directories
-
-### Key Design Patterns
-
-**Smart File Management**: Files are compared before copying to avoid unnecessary writes. Binary and large files are detected and handled specially.
-
-**Template System**: Member files use `{{MEMBER_NAME}}` placeholder that gets replaced during `member` command execution.
-
-**Framework vs User Data Separation**:
-- Framework files: Managed by CLI, can be updated/removed
-- User data directories: Created during init, never modified by CLI
-- This allows users to keep their content while updating framework
-
-**Dry Run Mode**: Both `update` and `remove` support `--dry-run` to preview changes before applying.
-
-## Directory Structure (PARA)
-
-```
-2ndBrain/
-├── 00_Dashboard/          # Task aggregation dashboards (Dataview/Tasks queries)
-├── 10_Inbox/              # Collection point (daily journals)
-│   ├── Agents/            # AI assistant shared workspace
-│   └── {MemberName}/      # Each member's personal directory
-├── 20_Areas/              # Long-term focus areas
-├── 30_Projects/           # Goal-oriented work
-├── 40_Resources/          # Reference materials
-├── 90_Archives/           # Completed/inactive content
-└── 99_System/             # Templates and scripts
-```
-
-## Task Format Convention
-
-Tasks use Markdown checkbox format with tags and dates:
-```markdown
-- [ ] Task description #tag 📅 YYYY-MM-DD
-```
-
-Tags: `#next` (do next), `#waiting` (waiting on others), `#someday` (later), `#read`/`#watch`/`#listen` (consume lists)
-
-## Dependencies
-
-- `commander` - CLI framework
-- `chalk` - Terminal colors
-- `fs-extra` - Enhanced file system operations
-- `diff` - File comparison/diff generation
-
-## Node.js Requirement
-
-Node.js >= 16.0.0 (specified in package.json `engines`)
-
-## Important Notes
-
-- The CLI is published as an npm package, so template files are bundled via `package.json` `files` field
-- `.obsidian/` directory is included in the package to provide pre-configured plugins
-- `AGENTS.md` serves as both documentation and the marker file for identifying 2ndBrain projects
-- Member directories are excluded from automatic updates (must be re-run manually if needed)