synap 0.7.0 → 0.8.0

package/.claude/skills/synap-assistant/SKILL.md

@@ -36,7 +36,33 @@ When assisting users with their synap entries:
 
 ## User Preferences (Memory)
 
-synap stores long-term user preferences at `~/.config/synap/user-preferences.md`.
+synap stores user data in a configurable data directory (default: `~/.config/synap/`).
+
+**Data files (syncable):**
+- `entries.json` - Active entries
+- `archive.json` - Archived entries  
+- `user-preferences.md` - Agent memory / user preferences
+
+**Config files (local only):**
+- `config.json` - Settings (including `dataDir` for custom data location)
+- `deletion-log.json` - Audit trail for restore
+
+### Custom Data Directory (for sync)
+
+Users can point synap to a custom folder (e.g., a git repo for multi-device sync):
+
+```bash
+synap config dataDir ~/synap-data
+# Or during setup:
+synap setup
+```
+
+When custom `dataDir` is set:
+- Data files go to the custom location
+- Config stays in `~/.config/synap/`
+- User can sync data folder via git, Dropbox, iCloud, etc.
+
+### Preferences Operations
 
 - Read preferences at the start of a session when present.
 - Prefer idempotent updates with `synap preferences set --section "Tag Meanings" --entry "#urgent = must do today"`.
@@ -377,8 +403,47 @@ synap import backup.json --merge             # Update existing + add new
 synap import backup.json --skip-existing     # Only add new
 ```
 
+#### `synap config`
+View or update configuration.
+
+```bash
+synap config                                 # Show all settings + paths
+synap config dataDir                         # Show data directory
+synap config dataDir ~/synap-data            # Set custom data directory
+synap config --reset                         # Reset to defaults
+```
+
 ## Workflow Patterns
 
+### Multi-Device Sync Setup
+
+For users who want to sync their synap across devices:
+
+1. **Set custom data directory:**
+   ```bash
+   synap config dataDir ~/synap-data
+   ```
+
+2. **Initialize git (optional):**
+   ```bash
+   cd ~/synap-data
+   git init
+   git remote add origin git@github.com:user/synap-data.git
+   ```
+
+3. **Daily sync workflow:**
+   ```bash
+   cd ~/synap-data && git pull    # Start of day
+   # ... use synap normally ...
+   cd ~/synap-data && git add . && git commit -m "sync" && git push  # End of day
+   ```
+
+4. **On a new device:**
+   ```bash
+   git clone git@github.com:user/synap-data.git ~/synap-data
+   synap config dataDir ~/synap-data
+   ```
+
 ### Daily Review
 
 Run this each morning to get oriented:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synap",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A CLI for externalizing your working memory",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -2032,6 +2032,8 @@ async function main() {
     .option('--json', 'Output as JSON')
     .action(async (options) => {
       const fs = require('fs');
+      const os = require('os');
+      const path = require('path');
 
       let hasEntries = false;
       if (fs.existsSync(storage.ENTRIES_FILE)) {
@@ -2043,16 +2045,9 @@ async function main() {
         }
       }
 
-      let createdEntry = null;
-      if (!hasEntries) {
-        createdEntry = await storage.addEntry({
-          content: 'My first thought',
-          type: config.defaultType || 'idea',
-          source: 'setup'
-        });
-      }
-
       let skillResult = { prompted: false };
+      let dataLocationResult = { configured: false };
+      
       if (!options.json) {
         console.log('');
         console.log(chalk.bold('Welcome to synap!\n'));
@@ -2061,19 +2056,93 @@ async function main() {
 
         console.log('Let\'s get you set up:\n');
 
-        console.log('[1/3] Quick capture test...');
-        if (createdEntry) {
+        // Step 1: Data location (only ask if not already configured)
+        const currentConfig = storage.loadConfig();
+        console.log('[1/4] Data location...');
+        
+        if (currentConfig.dataDir) {
+          console.log(`      ${chalk.gray('Already configured:')} ${storage.DATA_DIR}`);
+          dataLocationResult.configured = true;
+          dataLocationResult.path = storage.DATA_DIR;
+        } else {
+          const { select, input } = await import('@inquirer/prompts');
+          const dataChoice = await select({
+            message: 'Where should synap store your data?',
+            choices: [
+              { 
+                name: `Default (${path.join(os.homedir(), '.config', 'synap')})`, 
+                value: 'default',
+                description: 'Recommended for most users'
+              },
+              { 
+                name: 'Custom path (for git sync, Dropbox, iCloud)', 
+                value: 'custom',
+                description: 'Choose a custom folder for syncing across devices'
+              }
+            ]
+          });
+
+          if (dataChoice === 'custom') {
+            const defaultSuggestion = path.join(os.homedir(), 'synap-data');
+            const customPath = await input({
+              message: 'Enter path for synap data:',
+              default: defaultSuggestion,
+              validate: (val) => {
+                if (!val.trim()) return 'Path is required';
+                const expanded = val.replace(/^~/, os.homedir());
+                const parentDir = path.dirname(expanded);
+                if (!fs.existsSync(parentDir)) {
+                  return `Parent directory does not exist: ${parentDir}`;
+                }
+                return true;
+              }
+            });
+
+            const expanded = customPath.replace(/^~/, os.homedir());
+            
+            // Create directory if needed
+            if (!fs.existsSync(expanded)) {
+              fs.mkdirSync(expanded, { recursive: true });
+            }
+
+            // Save to config
+            currentConfig.dataDir = customPath;
+            storage.saveConfig(currentConfig);
+            storage.refreshDataDir();
+            
+            console.log(`      ${chalk.green('✓')} Data directory set to: ${expanded}`);
+            dataLocationResult.configured = true;
+            dataLocationResult.path = expanded;
+            dataLocationResult.custom = true;
+          } else {
+            console.log(`      ${chalk.green('✓')} Using default location: ${storage.DATA_DIR}`);
+            dataLocationResult.configured = true;
+            dataLocationResult.path = storage.DATA_DIR;
+          }
+        }
+
+        // Step 2: Quick capture test
+        console.log('\n[2/4] Quick capture test...');
+        let createdEntry = null;
+        if (!hasEntries) {
+          createdEntry = await storage.addEntry({
+            content: 'My first thought',
+            type: config.defaultType || 'idea',
+            source: 'setup'
+          });
           console.log(`      synap add "My first thought"`);
           console.log(`      ${chalk.green('✓')} Created entry ${createdEntry.id.slice(0, 8)}`);
         } else {
           console.log(`      ${chalk.gray('Existing entries detected, skipping.')}`);
         }
 
-        console.log('\n[2/3] Configuration...');
+        // Step 3: Configuration
+        console.log('\n[3/4] Configuration...');
         console.log(`      Default type: ${chalk.cyan(config.defaultType || 'idea')}`);
         console.log(`      Change with: ${chalk.cyan('synap config defaultType todo')}`);
 
-        console.log('\n[3/3] Claude Code Integration');
+        // Step 4: Claude Code Integration
+        console.log('\n[4/4] Claude Code Integration');
         const { confirm } = await import('@inquirer/prompts');
         const shouldInstall = await confirm({
           message: 'Install Claude skill for AI assistance?',
@@ -2105,10 +2174,26 @@ async function main() {
         console.log(`  ${chalk.cyan('synap todo "Something to do"')}`);
         console.log(`  ${chalk.cyan('synap focus')}`);
         console.log(`  ${chalk.cyan('synap review daily')}`);
+        
+        if (dataLocationResult.custom) {
+          console.log(chalk.bold('\n📁 Sync tip:'));
+          console.log(`  Your data is stored in: ${chalk.cyan(dataLocationResult.path)}`);
+          console.log(`  To sync with git: ${chalk.gray('cd ' + dataLocationResult.path + ' && git init')}`);
+        }
         console.log('');
         return;
       }
 
+      // JSON mode - minimal interaction
+      let createdEntry = null;
+      if (!hasEntries) {
+        createdEntry = await storage.addEntry({
+          content: 'My first thought',
+          type: config.defaultType || 'idea',
+          source: 'setup'
+        });
+      }
+
       console.log(JSON.stringify({
         success: true,
         mode: hasEntries ? 'existing' : 'first-run',
@@ -2149,7 +2234,15 @@ async function main() {
       // No key: show all config
       if (!key) {
         if (options.json) {
-          console.log(JSON.stringify({ success: true, config: currentConfig, defaults }, null, 2));
+          console.log(JSON.stringify({ 
+            success: true, 
+            config: currentConfig, 
+            defaults,
+            paths: {
+              configDir: storage.CONFIG_DIR,
+              dataDir: storage.DATA_DIR
+            }
+          }, null, 2));
         } else {
           console.log(chalk.bold('Configuration:\n'));
           for (const [k, v] of Object.entries(currentConfig)) {
@@ -2158,6 +2251,9 @@ async function main() {
             const displayValue = Array.isArray(v) ? v.join(', ') || '(none)' : (v === null ? '(null)' : v);
             console.log(`  ${chalk.cyan(k)}: ${displayValue}${defaultNote}`);
           }
+          console.log(chalk.bold('\nPaths:'));
+          console.log(`  ${chalk.cyan('configDir')}: ${storage.CONFIG_DIR}`);
+          console.log(`  ${chalk.cyan('dataDir')}: ${storage.DATA_DIR}`);
           console.log(chalk.gray('\nUse: synap config <key> <value> to set a value'));
         }
         return;
@@ -2201,16 +2297,42 @@ async function main() {
         parsedValue = value.split(',').map(t => t.trim()).filter(Boolean);
       } else if (key === 'editor' && (value === 'null' || value === '')) {
         parsedValue = null;
+      } else if (key === 'dataDir') {
+        // Handle dataDir specially
+        if (value === 'null' || value === '') {
+          parsedValue = null;
+        } else {
+          // Expand ~ but keep the ~ in storage for portability
+          const expanded = value.replace(/^~/, require('os').homedir());
+          // Create directory if it doesn't exist
+          if (!fs.existsSync(expanded)) {
+            fs.mkdirSync(expanded, { recursive: true });
+            if (!options.json) {
+              console.log(chalk.gray(`Created directory: ${expanded}`));
+            }
+          }
+          // Store the original value (with ~ if used)
+          parsedValue = value;
+        }
       }
 
       currentConfig[key] = parsedValue;
       storage.saveConfig(currentConfig);
 
+      // If dataDir changed, refresh the storage paths
+      if (key === 'dataDir') {
+        storage.refreshDataDir();
+      }
+
       if (options.json) {
         console.log(JSON.stringify({ success: true, key, value: parsedValue }));
       } else {
         const displayValue = Array.isArray(parsedValue) ? parsedValue.join(', ') : parsedValue;
         console.log(chalk.green(`Set ${key} = ${displayValue}`));
+        if (key === 'dataDir') {
+          console.log(chalk.gray(`Data will be stored in: ${storage.DATA_DIR}`));
+          console.log(chalk.yellow('\nNote: Restart synap for changes to take full effect.'));
+        }
       }
     });
 

package/src/deletion-log.js

@@ -1,21 +1,27 @@
 /**
  * deletion-log.js - Audit logging for deleted entries, enables restore
+ * 
+ * The deletion log is stored in DATA_DIR (syncable across devices)
  */
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
+const storage = require('./storage');
 
-// Storage directory
-const CONFIG_DIR = process.env.SYNAP_DIR || path.join(os.homedir(), '.config', 'synap');
-const DELETION_LOG_FILE = path.join(CONFIG_DIR, 'deletion-log.json');
+/**
+ * Get deletion log file path (dynamic, based on DATA_DIR)
+ */
+function getDeletionLogPath() {
+  return path.join(storage.DATA_DIR, 'deletion-log.json');
+}
 
 /**
- * Ensure config directory exists
+ * Ensure data directory exists
  */
-function ensureConfigDir() {
-  if (!fs.existsSync(CONFIG_DIR)) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+function ensureDataDir() {
+  const dataDir = storage.DATA_DIR;
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
   }
 }
 
@@ -32,12 +38,13 @@ function atomicWriteSync(filePath, data) {
  * Load deletion log
  */
 function loadLog() {
-  ensureConfigDir();
-  if (!fs.existsSync(DELETION_LOG_FILE)) {
+  ensureDataDir();
+  const logFile = getDeletionLogPath();
+  if (!fs.existsSync(logFile)) {
     return [];
   }
   try {
-    return JSON.parse(fs.readFileSync(DELETION_LOG_FILE, 'utf8'));
+    return JSON.parse(fs.readFileSync(logFile, 'utf8'));
   } catch {
     return [];
   }
@@ -47,8 +54,8 @@ function loadLog() {
  * Save deletion log
  */
 function saveLog(log) {
-  ensureConfigDir();
-  atomicWriteSync(DELETION_LOG_FILE, log);
+  ensureDataDir();
+  atomicWriteSync(getDeletionLogPath(), log);
 }
 
 /**

package/src/preferences.js

@@ -1,5 +1,7 @@
 /**
  * preferences.js - User preferences storage and helpers
+ * 
+ * User preferences are stored in DATA_DIR (syncable) not CONFIG_DIR
  */
 
 const fs = require('fs');
@@ -7,7 +9,6 @@ const path = require('path');
 const storage = require('./storage');
 
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'user-preferences-template.md');
-const PREFERENCES_FILE = path.join(storage.CONFIG_DIR, 'user-preferences.md');
 const MAX_LINES = 500;
 const SECTION_ALIASES = new Map([
   ['about', 'About Me'],
@@ -21,14 +22,22 @@ const SECTION_ALIASES = new Map([
   ['behavioral', 'Behavioral Preferences']
 ]);
 
-function ensureConfigDir() {
-  if (!fs.existsSync(storage.CONFIG_DIR)) {
-    fs.mkdirSync(storage.CONFIG_DIR, { recursive: true });
+/**
+ * Get current preferences file path (dynamic, based on DATA_DIR)
+ */
+function getPreferencesFilePath() {
+  return path.join(storage.DATA_DIR, 'user-preferences.md');
+}
+
+function ensureDataDir() {
+  const dataDir = storage.DATA_DIR;
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
   }
 }
 
 function getPreferencesPath() {
-  return PREFERENCES_FILE;
+  return getPreferencesFilePath();
 }
 
 function readTemplate() {
@@ -62,22 +71,24 @@ function savePreferences(content) {
     throw new Error(validation.error);
   }
 
-  ensureConfigDir();
-  const tmpPath = `${PREFERENCES_FILE}.tmp`;
+  ensureDataDir();
+  const preferencesFile = getPreferencesFilePath();
+  const tmpPath = `${preferencesFile}.tmp`;
   fs.writeFileSync(tmpPath, content, 'utf8');
-  fs.renameSync(tmpPath, PREFERENCES_FILE);
+  fs.renameSync(tmpPath, preferencesFile);
   return content;
 }
 
 function loadPreferences() {
-  ensureConfigDir();
-  if (!fs.existsSync(PREFERENCES_FILE)) {
+  ensureDataDir();
+  const preferencesFile = getPreferencesFilePath();
+  if (!fs.existsSync(preferencesFile)) {
     const template = readTemplate();
     savePreferences(template);
     return template;
   }
 
-  const content = fs.readFileSync(PREFERENCES_FILE, 'utf8');
+  const content = fs.readFileSync(preferencesFile, 'utf8');
   const validation = validatePreferences(content);
   if (!validation.valid) {
     throw new Error(validation.error);
@@ -349,6 +360,6 @@ module.exports = {
   appendToSection,
   resetPreferences,
   validatePreferences,
-  PREFERENCES_FILE,
+  get PREFERENCES_FILE() { return getPreferencesFilePath(); },
   TEMPLATE_PATH
 };

package/src/storage.js

@@ -7,16 +7,30 @@ const path = require('path');
 const os = require('os');
 const { v4: uuidv4 } = require('uuid');
 
-// Storage directory
-const CONFIG_DIR = process.env.SYNAP_DIR || path.join(os.homedir(), '.config', 'synap');
-const ENTRIES_FILE = path.join(CONFIG_DIR, 'entries.json');
-const ARCHIVE_FILE = path.join(CONFIG_DIR, 'archive.json');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+// =============================================================================
+// Directory Resolution (XDG-compliant with backward compatibility)
+// =============================================================================
 
-// Valid types, statuses, and date formats
-const VALID_TYPES = ['idea', 'project', 'feature', 'todo', 'question', 'reference', 'note'];
-const VALID_STATUSES = ['raw', 'active', 'wip', 'someday', 'done', 'archived'];
-const VALID_DATE_FORMATS = ['relative', 'absolute', 'locale'];
+/**
+ * Resolve the config directory path
+ * Priority:
+ *   1. SYNAP_CONFIG_DIR env var (explicit override for config only)
+ *   2. SYNAP_DIR env var (legacy - affects both config and data)
+ *   3. Default: ~/.config/synap
+ */
+function resolveConfigDir() {
+  if (process.env.SYNAP_CONFIG_DIR) {
+    return process.env.SYNAP_CONFIG_DIR;
+  }
+  if (process.env.SYNAP_DIR) {
+    return process.env.SYNAP_DIR;
+  }
+  return path.join(os.homedir(), '.config', 'synap');
+}
+
+// Config directory - always local, not synced
+const CONFIG_DIR = resolveConfigDir();
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 
 /**
  * Ensure config directory exists
@@ -27,6 +41,90 @@ function ensureConfigDir() {
   }
 }
 
+/**
+ * Load configuration (needed before resolving DATA_DIR)
+ */
+function loadConfigRaw() {
+  ensureConfigDir();
+  if (!fs.existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Resolve the data directory path
+ * Priority:
+ *   1. SYNAP_DATA_DIR env var (explicit override for data only)
+ *   2. config.json -> dataDir setting
+ *   3. SYNAP_DIR env var (legacy - affects both config and data)
+ *   4. Default: ~/.local/share/synap (XDG compliant)
+ */
+function resolveDataDir() {
+  // 1. Explicit env var override for data
+  if (process.env.SYNAP_DATA_DIR) {
+    return process.env.SYNAP_DATA_DIR;
+  }
+
+  // 2. Config file setting
+  const rawConfig = loadConfigRaw();
+  if (rawConfig.dataDir) {
+    // Expand ~ to home directory
+    const expanded = rawConfig.dataDir.replace(/^~/, os.homedir());
+    return expanded;
+  }
+
+  // 3. Legacy env var (affects both config and data)
+  if (process.env.SYNAP_DIR) {
+    return process.env.SYNAP_DIR;
+  }
+
+  // 4. Default: XDG-compliant data directory
+  return path.join(os.homedir(), '.local', 'share', 'synap');
+}
+
+// Resolve DATA_DIR at module load time
+// This will be re-evaluated if config changes require restart
+let DATA_DIR = resolveDataDir();
+
+// Data files (syncable)
+let ENTRIES_FILE = path.join(DATA_DIR, 'entries.json');
+let ARCHIVE_FILE = path.join(DATA_DIR, 'archive.json');
+
+/**
+ * Refresh data directory paths (call after config change)
+ */
+function refreshDataDir() {
+  DATA_DIR = resolveDataDir();
+  ENTRIES_FILE = path.join(DATA_DIR, 'entries.json');
+  ARCHIVE_FILE = path.join(DATA_DIR, 'archive.json');
+}
+
+/**
+ * Get current data directory path
+ */
+function getDataDir() {
+  return DATA_DIR;
+}
+
+/**
+ * Ensure data directory exists
+ */
+function ensureDataDir() {
+  if (!fs.existsSync(DATA_DIR)) {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+  }
+}
+
+// Valid types, statuses, and date formats
+const VALID_TYPES = ['idea', 'project', 'feature', 'todo', 'question', 'reference', 'note'];
+const VALID_STATUSES = ['raw', 'active', 'wip', 'someday', 'done', 'archived'];
+const VALID_DATE_FORMATS = ['relative', 'absolute', 'locale'];
+
 /**
  * Atomic file write - write to temp file then rename
  */
@@ -40,7 +138,7 @@ function atomicWriteSync(filePath, data) {
  * Load entries from file
  */
 function loadEntries() {
-  ensureConfigDir();
+  ensureDataDir();
   if (!fs.existsSync(ENTRIES_FILE)) {
     return { version: 1, entries: [] };
   }
@@ -55,7 +153,7 @@ function loadEntries() {
  * Save entries to file
  */
 function saveEntries(data) {
-  ensureConfigDir();
+  ensureDataDir();
   atomicWriteSync(ENTRIES_FILE, data);
 }
 
@@ -63,7 +161,7 @@ function saveEntries(data) {
  * Load archived entries
  */
 function loadArchive() {
-  ensureConfigDir();
+  ensureDataDir();
   if (!fs.existsSync(ARCHIVE_FILE)) {
     return { version: 1, entries: [] };
   }
@@ -78,7 +176,7 @@ function loadArchive() {
  * Save archived entries
  */
 function saveArchive(data) {
-  ensureConfigDir();
+  ensureDataDir();
   atomicWriteSync(ARCHIVE_FILE, data);
 }
 
@@ -91,7 +189,8 @@ function loadConfig() {
     defaultType: 'idea',
     defaultTags: [],
     editor: null, // Falls back to EDITOR env var in CLI
-    dateFormat: 'relative'
+    dateFormat: 'relative',
+    dataDir: null // Custom data directory (null = use default)
   };
 
   if (!fs.existsSync(CONFIG_FILE)) {
@@ -123,6 +222,12 @@ function loadConfig() {
         .map(t => t.trim());
     }
 
+    // Validate dataDir if set
+    if (config.dataDir !== null && typeof config.dataDir !== 'string') {
+      console.warn(`Warning: Invalid dataDir in config. Ignoring.`);
+      config.dataDir = null;
+    }
+
     return config;
   } catch (err) {
     console.warn(`Warning: Could not parse config.json: ${err.message}`);
@@ -138,7 +243,8 @@ function getDefaultConfig() {
     defaultType: 'idea',
     defaultTags: [],
     editor: null,
-    dateFormat: 'relative'
+    dateFormat: 'relative',
+    dataDir: null
   };
 }
 
@@ -170,6 +276,17 @@ function validateConfigValue(key, value) {
     case 'editor':
       // Any string or null is valid
       break;
+    case 'dataDir':
+      // Path validation - must be a valid path string or null
+      if (value !== null && value !== 'null' && typeof value === 'string') {
+        const expanded = value.replace(/^~/, os.homedir());
+        // Check if parent directory exists (we'll create the target if needed)
+        const parentDir = path.dirname(expanded);
+        if (!fs.existsSync(parentDir)) {
+          return { valid: false, error: `Parent directory does not exist: ${parentDir}` };
+        }
+      }
+      break;
   }
   return { valid: true };
 }
@@ -1018,9 +1135,12 @@ module.exports = {
   validateConfigValue,
   saveConfig,
   parseDate,
+  refreshDataDir,
+  getDataDir,
   CONFIG_DIR,
-  ENTRIES_FILE,
-  ARCHIVE_FILE,
+  get DATA_DIR() { return DATA_DIR; },
+  get ENTRIES_FILE() { return ENTRIES_FILE; },
+  get ARCHIVE_FILE() { return ARCHIVE_FILE; },
   VALID_TYPES,
   VALID_STATUSES,
   VALID_DATE_FORMATS