claude-code-backup 1.0.0

package/src/commands/config-cmd.js

@@ -0,0 +1,139 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig, requireConfig, expandPath } from '../core/config.js';
+import { log } from '../utils/logger.js';
+
+export function runConfig(action, key, value) {
+  switch (action) {
+    case 'show':           return showConfig();
+    case 'set':            return setConfig(key, value);
+    case 'add-dir':        return addDir(key);
+    case 'remove-dir':     return removeDir(key);
+    case 'add-project':    return addProject(key);
+    case 'remove-project': return removeProject(key);
+    default:
+      log.error(`Unknown action: "${action}"`);
+      log.info('Valid actions:');
+      log.dim('  show');
+      log.dim('  set <key> <value>');
+      log.dim('  add-dir <path>         — fully mirror a directory');
+      log.dim('  remove-dir <path>');
+      log.dim('  add-project <path>     — back up only CLAUDE.md from a project root');
+      log.dim('  remove-project <path>');
+      process.exit(1);
+  }
+}
+
+function showConfig() {
+  const config = loadConfig();
+  if (!config) {
+    log.warn('Not configured yet. Run: claude-backup init');
+    return;
+  }
+  const safe = JSON.parse(JSON.stringify(config));
+  if (safe.github?.pat) {
+    safe.github.pat = safe.github.pat.slice(0, 8) + '••••••••';
+  }
+  console.log(chalk.bold('\nCurrent config:\n'));
+  console.log(JSON.stringify(safe, null, 2));
+  console.log('');
+}
+
+function setConfig(key, value) {
+  if (!key || value === undefined) {
+    log.error('Usage: claude-backup config set <key> <value>');
+    log.dim('Example: claude-backup config set auto_sync.debounce_ms 3000');
+    process.exit(1);
+  }
+  const config = requireConfig();
+  const parts = key.split('.');
+  let obj = config;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (typeof obj[parts[i]] !== 'object') obj[parts[i]] = {};
+    obj = obj[parts[i]];
+  }
+  let parsed = value;
+  if (value === 'true') parsed = true;
+  else if (value === 'false') parsed = false;
+  else if (!isNaN(value) && value !== '') parsed = Number(value);
+
+  obj[parts[parts.length - 1]] = parsed;
+  saveConfig(config);
+  log.success(`Set ${key} = ${key.includes('pat') ? '••••' : parsed}`);
+}
+
+function addDir(dirPath) {
+  if (!dirPath) {
+    log.error('Usage: claude-backup config add-dir <path>');
+    process.exit(1);
+  }
+  const config = requireConfig();
+  const expanded = expandPath(dirPath);
+  if (config.watched_dirs.some(d => d === dirPath || d === expanded)) {
+    log.warn('Directory is already in the watch list');
+    return;
+  }
+  config.watched_dirs.push(expanded);
+  saveConfig(config);
+  log.success(`Added watched dir: ${expanded}`);
+}
+
+function removeDir(dirPath) {
+  if (!dirPath) {
+    log.error('Usage: claude-backup config remove-dir <path>');
+    process.exit(1);
+  }
+  const config = requireConfig();
+  const expanded = expandPath(dirPath);
+  const before = config.watched_dirs.length;
+  config.watched_dirs = config.watched_dirs.filter(
+    d => d !== dirPath && d !== expanded
+  );
+  if (config.watched_dirs.length < before) {
+    saveConfig(config);
+    log.success(`Removed watched dir: ${expanded}`);
+  } else {
+    log.warn('Directory not found in watch list');
+  }
+}
+
+function addProject(dirPath) {
+  if (!dirPath) {
+    log.error('Usage: claude-backup config add-project <project-root-path>');
+    log.dim('Only the CLAUDE.md file at that path will be backed up.');
+    process.exit(1);
+  }
+  const config = requireConfig();
+  if (!config.claude_md_dirs) config.claude_md_dirs = [];
+  const expanded = expandPath(dirPath);
+  if (config.claude_md_dirs.some(d => d === dirPath || d === expanded)) {
+    log.warn('Project is already in the list');
+    return;
+  }
+  config.claude_md_dirs.push(expanded);
+  saveConfig(config);
+  log.success(`Added project: ${expanded}`);
+  log.dim(`Will back up: ${expanded}/CLAUDE.md`);
+}
+
+function removeProject(dirPath) {
+  if (!dirPath) {
+    log.error('Usage: claude-backup config remove-project <project-root-path>');
+    process.exit(1);
+  }
+  const config = requireConfig();
+  if (!config.claude_md_dirs) {
+    log.warn('No projects configured');
+    return;
+  }
+  const expanded = expandPath(dirPath);
+  const before = config.claude_md_dirs.length;
+  config.claude_md_dirs = config.claude_md_dirs.filter(
+    d => d !== dirPath && d !== expanded
+  );
+  if (config.claude_md_dirs.length < before) {
+    saveConfig(config);
+    log.success(`Removed project: ${expanded}`);
+  } else {
+    log.warn('Project not found in list');
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,138 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { homedir } from 'os';
+import { join } from 'path';
+import { loadConfig, saveConfig } from '../core/config.js';
+import { ensureRepo } from '../backends/github.js';
+import { log } from '../utils/logger.js';
+
+export async function runInit() {
+  log.header('Claude Backup — Setup Wizard');
+
+  const existing = loadConfig();
+
+  // ── Step 1: GitHub PAT ───────────────────────────────────────────────────
+  console.log(chalk.bold.underline('Step 1 of 4 — GitHub Personal Access Token') + '\n');
+  console.log('claude-backup needs a PAT with ' + chalk.cyan('"repo"') + ' scope to create');
+  console.log('and push to a private GitHub repository on your behalf.\n');
+  console.log(chalk.bold('  Create your token here:'));
+  console.log('  ' + chalk.underline.blue('https://github.com/settings/tokens/new') + '\n');
+  console.log(chalk.dim('  Instructions:'));
+  console.log(chalk.dim('  1. Note name → e.g. "claude-backup"'));
+  console.log(chalk.dim('  2. Expiration → your preference (No expiration is fine)'));
+  console.log(chalk.dim('  3. Scopes → tick  ') + chalk.cyan('repo') + chalk.dim('  (the top-level checkbox covers everything needed)'));
+  console.log(chalk.dim('  4. Click "Generate token" and copy the value\n'));
+  console.log(chalk.dim('  Fine-grained token alternative:'));
+  console.log(chalk.dim('  ' + chalk.underline('https://github.com/settings/personal-access-tokens/new')));
+  console.log(chalk.dim('  → Repository permissions: Contents (Read & Write), Metadata (Read)\n'));
+
+  const { pat } = await inquirer.prompt([
+    {
+      type: 'password',
+      name: 'pat',
+      message: 'Paste your GitHub PAT:',
+      default: existing?.github?.pat || '',
+      validate: v => v.trim().length > 0 || 'PAT is required',
+    },
+  ]);
+
+  // ── Step 2: Repo & branch ────────────────────────────────────────────────
+  console.log('\n' + chalk.bold.underline('Step 2 of 4 — Repository & Branch') + '\n');
+  console.log(chalk.dim('  The repo will be created as private if it does not exist yet.\n'));
+
+  const { repo, branch } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'repo',
+      message: 'GitHub repo name (e.g. yourname/claude-backup):',
+      default: existing?.github?.repo || '',
+      validate: v =>
+        /^[\w.-]+\/[\w.-]+$/.test(v.trim()) || 'Format must be owner/repo',
+    },
+    {
+      type: 'input',
+      name: 'branch',
+      message: 'Branch name:',
+      default: existing?.github?.branch || 'main',
+    },
+  ]);
+
+  // ── Step 3: Watched dirs & filters ───────────────────────────────────────
+  console.log('\n' + chalk.bold.underline('Step 3 of 4 — Watched Directories & Filters') + '\n');
+  console.log(chalk.dim('  These directories are fully mirrored to GitHub on every change.\n'));
+
+  const { watched_dirs, exclude, debounce_ms } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'watched_dirs',
+      message: 'Directories to watch (comma-separated):',
+      default: existing?.watched_dirs?.join(', ') || join(homedir(), '.claude'),
+      filter: v => v.split(',').map(s => s.trim()).filter(Boolean),
+    },
+    {
+      type: 'input',
+      name: 'exclude',
+      message: 'Files to exclude (comma-separated, * wildcards ok):',
+      default:
+        existing?.exclude?.join(', ') ||
+        'settings.local.json, *.log, .DS_Store',
+      filter: v => v.split(',').map(s => s.trim()).filter(Boolean),
+    },
+    {
+      type: 'number',
+      name: 'debounce_ms',
+      message: 'Debounce delay in ms (wait time after a change before pushing):',
+      default: existing?.auto_sync?.debounce_ms ?? 2000,
+    },
+  ]);
+
+  // ── Step 4: Project CLAUDE.md files ──────────────────────────────────────
+  console.log('\n' + chalk.bold.underline('Step 4 of 4 — Project CLAUDE.md Files') + '\n');
+  console.log('Each Claude Code project can have a ' + chalk.cyan('CLAUDE.md') + ' file at its root.');
+  console.log('These contain project-specific instructions Claude reads at the start of every session.\n');
+  console.log(chalk.dim('  Only the CLAUDE.md file is backed up from each path — not your source code.\n'));
+  console.log(chalk.dim('  Example paths:'));
+  console.log(chalk.dim(`  ${join(homedir(), 'projects', 'my-app')}`));
+  console.log(chalk.dim(`  ${join(homedir(), 'work', 'client-site')}\n`));
+
+  const { claude_md_dirs } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'claude_md_dirs',
+      message: 'Project root directories with CLAUDE.md (comma-separated, blank to skip):',
+      default: existing?.claude_md_dirs?.join(', ') || '',
+      filter: v => v.split(',').map(s => s.trim()).filter(Boolean),
+    },
+  ]);
+
+  // ── Save & connect ───────────────────────────────────────────────────────
+  console.log('');
+
+  const config = {
+    backend: 'github',
+    github: {
+      pat: pat.trim(),
+      repo: repo.trim(),
+      branch: branch.trim(),
+    },
+    watched_dirs,
+    claude_md_dirs,
+    exclude,
+    auto_sync: { debounce_ms },
+  };
+
+  saveConfig(config);
+  log.success('Config saved  (~/.config/claude-backup/config.json, chmod 600)');
+
+  try {
+    await ensureRepo(config);
+    log.success('GitHub setup complete\n');
+    log.info('Next steps:');
+    log.dim('  claude-backup push                — do your first backup now');
+    log.dim('  claude-backup service install     — enable auto-sync on login');
+  } catch (err) {
+    log.error(`GitHub setup failed: ${err.message}`);
+    if (process.env.DEBUG) console.error(err);
+    process.exit(1);
+  }
+}

package/src/commands/pull.js

@@ -0,0 +1,161 @@
+import { existsSync, mkdirSync, copyFileSync, cpSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { requireConfig, CONFIG_DIR, REPO_DIR, expandPath } from '../core/config.js';
+import { fetchForRestore, getHistory } from '../backends/github.js';
+import { log, spinner } from '../utils/logger.js';
+
+function walkRepoDir(dir, results = [], rel = '') {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.name === '.git' || entry.name === 'backup-manifest.json') continue;
+    const fullPath = join(dir, entry.name);
+    const relPath = rel ? join(rel, entry.name) : entry.name;
+    if (entry.isDirectory()) {
+      walkRepoDir(fullPath, results, relPath);
+    } else if (entry.isFile()) {
+      results.push({ repoPath: fullPath, rel: relPath });
+    }
+  }
+  return results;
+}
+
+function buildRestoreOps(manifest) {
+  const repoFiles = walkRepoDir(REPO_DIR);
+  const ops = [];
+
+  for (const { repoPath, rel } of repoFiles) {
+    // rel looks like "Users_apple_.claude/settings.json"
+    const sep = rel.indexOf('/') !== -1 ? rel.indexOf('/') : rel.indexOf('\\');
+    const label = sep === -1 ? rel : rel.slice(0, sep);
+    const rest = sep === -1 ? '' : rel.slice(sep + 1);
+
+    const targetBase = manifest[label];
+    if (!targetBase) continue;
+
+    ops.push({
+      src: repoPath,
+      dest: join(expandPath(targetBase), rest),
+    });
+  }
+
+  return ops;
+}
+
+export async function runPull(options) {
+  const config = requireConfig();
+
+  let ref;
+
+  if (options.history) {
+    const spin = spinner('Loading commit history...').start();
+    const history = await getHistory(config);
+    spin.stop();
+
+    if (history.length === 0) {
+      log.warn('No commits found. Run: claude-backup push first');
+      return;
+    }
+
+    const { chosen } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'chosen',
+        message: 'Select a backup to restore:',
+        choices: history.map(c => ({
+          name: `${String(c.date).slice(0, 16)}  ${c.message}  (${String(c.hash).slice(0, 7)})`,
+          value: c.hash,
+        })),
+      },
+    ]);
+    ref = chosen;
+  }
+
+  const spin = spinner('Fetching backup from GitHub...').start();
+  let manifest;
+  try {
+    manifest = await fetchForRestore(config, ref);
+    spin.stop();
+  } catch (err) {
+    spin.fail(`Fetch failed: ${err.message}`);
+    if (process.env.DEBUG) console.error(err);
+    process.exit(1);
+  }
+
+  if (!manifest || Object.keys(manifest).length === 0) {
+    log.error('No backup manifest found. The repo may be empty or from an older version.');
+    return;
+  }
+
+  const ops = buildRestoreOps(manifest);
+  if (ops.length === 0) {
+    log.warn('No files to restore — watched dirs may not match this backup');
+    return;
+  }
+
+  if (options.dryRun) {
+    log.header('Dry run — files that would be restored:');
+    for (const { dest } of ops) {
+      console.log(chalk.cyan('  →'), dest);
+    }
+    log.info(`\nTotal: ${ops.length} file(s)`);
+    return;
+  }
+
+  log.info(`Will restore ${ops.length} file(s) to:`);
+  const preview = ops.slice(0, 8);
+  for (const { dest } of preview) {
+    console.log(chalk.dim('  ' + dest));
+  }
+  if (ops.length > 8) {
+    console.log(chalk.dim(`  ... and ${ops.length - 8} more`));
+  }
+
+  const { confirmed } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirmed',
+      message: 'Proceed? A safety snapshot of your current state will be created first.',
+      default: false,
+    },
+  ]);
+
+  if (!confirmed) {
+    log.info('Restore cancelled');
+    return;
+  }
+
+  // Safety snapshot — copy current watched dirs to a timestamped backup
+  const snapshotDir = join(CONFIG_DIR, `pre-restore-${Date.now()}`);
+  const snapSpin = spinner('Creating safety snapshot of current state...').start();
+  mkdirSync(snapshotDir, { recursive: true });
+  for (const rawDir of config.watched_dirs) {
+    const dir = expandPath(rawDir);
+    if (existsSync(dir)) {
+      const label = dir.replace(/[^a-zA-Z0-9]/g, '_');
+      try {
+        cpSync(dir, join(snapshotDir, label), { recursive: true });
+      } catch {}
+    }
+  }
+  snapSpin.succeed(`Safety snapshot saved → ${snapshotDir}`);
+
+  // Restore
+  const restoreSpin = spinner(`Restoring ${ops.length} files...`).start();
+  let count = 0;
+  for (const { src, dest } of ops) {
+    mkdirSync(dirname(dest), { recursive: true });
+    try {
+      copyFileSync(src, dest);
+      count++;
+    } catch {}
+  }
+  restoreSpin.succeed(`Restored ${count} file(s)`);
+  log.success('Restore complete');
+}

package/src/commands/push.js

@@ -0,0 +1,14 @@
+import { requireConfig } from '../core/config.js';
+import { push } from '../backends/github.js';
+import { log } from '../utils/logger.js';
+
+export async function runPush(options) {
+  const config = requireConfig();
+  try {
+    await push(config, options.message);
+  } catch (err) {
+    log.error(`Push failed: ${err.message}`);
+    if (process.env.DEBUG) console.error(err);
+    process.exit(1);
+  }
+}

package/src/commands/service.js

@@ -0,0 +1,168 @@
+import { writeFileSync, existsSync, unlinkSync } from 'fs';
+import { exec, spawn } from 'child_process';
+import { promisify } from 'util';
+import { LAUNCHD_PLIST, LAUNCHD_LABEL, LOG_FILE, ERROR_LOG_FILE } from '../core/config.js';
+import { log } from '../utils/logger.js';
+
+const execAsync = promisify(exec);
+
+function buildPlist(nodePath, scriptPath) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LAUNCHD_LABEL}</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodePath}</string>
+    <string>${scriptPath}</string>
+    <string>watch</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+
+  <key>StandardOutPath</key>
+  <string>${LOG_FILE}</string>
+
+  <key>StandardErrorPath</key>
+  <string>${ERROR_LOG_FILE}</string>
+</dict>
+</plist>`;
+}
+
+async function loadService() {
+  const uid = process.getuid();
+  // Try modern launchctl first (macOS 13+), fall back to legacy
+  try {
+    await execAsync(`launchctl bootstrap gui/${uid} "${LAUNCHD_PLIST}"`);
+  } catch {
+    await execAsync(`launchctl load -w "${LAUNCHD_PLIST}"`);
+  }
+}
+
+async function unloadService() {
+  const uid = process.getuid();
+  try {
+    await execAsync(`launchctl bootout gui/${uid}/${LAUNCHD_LABEL}`);
+  } catch {
+    try {
+      await execAsync(`launchctl unload -w "${LAUNCHD_PLIST}"`);
+    } catch {}
+  }
+}
+
+async function installService() {
+  const nodePath = process.execPath;   // path to the node binary running this script
+  const scriptPath = process.argv[1];  // absolute path to claude-backup.js
+
+  const plist = buildPlist(nodePath, scriptPath);
+  writeFileSync(LAUNCHD_PLIST, plist, 'utf8');
+  log.info(`Plist written to: ${LAUNCHD_PLIST}`);
+
+  try {
+    // Unload first in case already loaded
+    await unloadService();
+  } catch {}
+
+  try {
+    await loadService();
+    log.success('Service installed and started');
+    log.dim(`Node:    ${nodePath}`);
+    log.dim(`Script:  ${scriptPath}`);
+    log.dim(`Stdout:  ${LOG_FILE}`);
+    log.dim(`Stderr:  ${ERROR_LOG_FILE}`);
+    log.info('The watcher will now auto-start on every login');
+  } catch (err) {
+    log.error(`Failed to start service: ${err.message}`);
+    log.dim('Try running manually: launchctl load -w ' + LAUNCHD_PLIST);
+  }
+}
+
+async function uninstallService() {
+  if (!existsSync(LAUNCHD_PLIST)) {
+    log.warn('Service is not installed');
+    return;
+  }
+  try {
+    await unloadService();
+    log.success('Service stopped and unloaded');
+  } catch (err) {
+    log.warn(`Could not unload: ${err.message}`);
+  }
+  unlinkSync(LAUNCHD_PLIST);
+  log.success('Service plist removed — auto-sync disabled');
+}
+
+async function serviceStatus() {
+  if (!existsSync(LAUNCHD_PLIST)) {
+    log.warn('Service is not installed');
+    log.dim('Run: claude-backup service install');
+    return;
+  }
+
+  const uid = process.getuid();
+  try {
+    // Modern approach
+    const { stdout } = await execAsync(
+      `launchctl print gui/${uid}/${LAUNCHD_LABEL} 2>/dev/null`
+    );
+    const pidMatch = stdout.match(/pid\s*=\s*(\d+)/);
+    if (pidMatch) {
+      log.success(`Service is running  (PID: ${pidMatch[1]})`);
+    } else {
+      log.warn('Service is loaded but not currently running');
+    }
+  } catch {
+    // Fallback to list
+    try {
+      const { stdout } = await execAsync(`launchctl list | grep "${LAUNCHD_LABEL}"`);
+      const parts = stdout.trim().split(/\s+/);
+      if (parts[0] !== '-') {
+        log.success(`Service is running  (PID: ${parts[0]})`);
+      } else {
+        log.warn(`Service is loaded but stopped  (last exit code: ${parts[1]})`);
+      }
+    } catch {
+      log.warn('Service is not running');
+    }
+  }
+
+  log.dim(`Plist:  ${LAUNCHD_PLIST}`);
+  log.dim(`Log:    ${LOG_FILE}`);
+  log.dim(`Errors: ${ERROR_LOG_FILE}`);
+}
+
+async function serviceLogs() {
+  if (!existsSync(LOG_FILE)) {
+    log.warn(`Log file not found: ${LOG_FILE}`);
+    log.dim('The service may not have run yet');
+    return;
+  }
+  log.dim(`Tailing: ${LOG_FILE}  (Ctrl+C to stop)\n`);
+  const tail = spawn('tail', ['-f', LOG_FILE], { stdio: 'inherit' });
+  tail.on('close', () => process.exit(0));
+  process.on('SIGINT', () => { tail.kill(); process.exit(0); });
+}
+
+export async function runService(action) {
+  switch (action) {
+    case 'install':   return installService();
+    case 'uninstall': return uninstallService();
+    case 'status':    return serviceStatus();
+    case 'logs':      return serviceLogs();
+    default:
+      log.error(`Unknown action: "${action}"`);
+      log.info('Valid actions: install | uninstall | status | logs');
+      process.exit(1);
+  }
+}