feat: add backup and restore with encrypted secrets

BackupService exports servers/profiles/projects to JSON bundle.
RestoreService imports with skip/overwrite/fail conflict strategies.
AES-256-GCM encryption for sensitive env vars via scrypt-derived keys.
REST endpoints and CLI commands for backup/restore operations.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/cli/src/commands/backup.ts

@@ -0,0 +1,80 @@
+import { Command } from 'commander';
+import fs from 'node:fs';
+import type { ApiClient } from '../api-client.js';
+
+export interface BackupDeps {
+  client: ApiClient;
+  log: (...args: unknown[]) => void;
+}
+
+export function createBackupCommand(deps: BackupDeps): Command {
+  const cmd = new Command('backup')
+    .description('Backup mcpctl configuration to a JSON file')
+    .option('-o, --output <path>', 'output file path', 'mcpctl-backup.json')
+    .option('-p, --password <password>', 'encrypt sensitive values with password')
+    .option('-r, --resources <types>', 'resource types to backup (comma-separated: servers,profiles,projects)')
+    .action(async (options: { output: string; password?: string; resources?: string }) => {
+      const body: Record<string, unknown> = {};
+      if (options.password) {
+        body.password = options.password;
+      }
+      if (options.resources) {
+        body.resources = options.resources.split(',').map((s) => s.trim());
+      }
+
+      const bundle = await deps.client.post('/api/v1/backup', body);
+      fs.writeFileSync(options.output, JSON.stringify(bundle, null, 2), 'utf-8');
+      deps.log(`Backup saved to ${options.output}`);
+    });
+
+  return cmd;
+}
+
+export function createRestoreCommand(deps: BackupDeps): Command {
+  const cmd = new Command('restore')
+    .description('Restore mcpctl configuration from a backup file')
+    .option('-i, --input <path>', 'backup file path', 'mcpctl-backup.json')
+    .option('-p, --password <password>', 'decryption password for encrypted backups')
+    .option('-c, --conflict <strategy>', 'conflict resolution: skip, overwrite, fail', 'skip')
+    .action(async (options: { input: string; password?: string; conflict: string }) => {
+      if (!fs.existsSync(options.input)) {
+        deps.log(`Error: File not found: ${options.input}`);
+        return;
+      }
+
+      const raw = fs.readFileSync(options.input, 'utf-8');
+      const bundle = JSON.parse(raw) as unknown;
+
+      const body: Record<string, unknown> = {
+        bundle,
+        conflictStrategy: options.conflict,
+      };
+      if (options.password) {
+        body.password = options.password;
+      }
+
+      const result = await deps.client.post<{
+        serversCreated: number;
+        serversSkipped: number;
+        profilesCreated: number;
+        profilesSkipped: number;
+        projectsCreated: number;
+        projectsSkipped: number;
+        errors: string[];
+      }>('/api/v1/restore', body);
+
+      deps.log('Restore complete:');
+      deps.log(`  Servers:  ${result.serversCreated} created, ${result.serversSkipped} skipped`);
+      deps.log(`  Profiles: ${result.profilesCreated} created, ${result.profilesSkipped} skipped`);
+      deps.log(`  Projects: ${result.projectsCreated} created, ${result.projectsSkipped} skipped`);
+
+      if (result.errors.length > 0) {
+        deps.log(`  Errors:`);
+        for (const err of result.errors) {
+          deps.log(`    - ${err}`);
+        }
+      }
+    });
+
+  return cmd;
+}

src/cli/src/index.ts

@@ -10,6 +10,7 @@ import { createApplyCommand } from './commands/apply.js';
 import { createSetupCommand } from './commands/setup.js';
 import { createClaudeCommand } from './commands/claude.js';
 import { createProjectCommand } from './commands/project.js';
+import { createBackupCommand, createRestoreCommand } from './commands/backup.js';
 import { ApiClient } from './api-client.js';
 import { loadConfig } from './config/index.js';
 
@@ -98,6 +99,16 @@ export function createProgram(): Command {
     log: (...args) => console.log(...args),
   }));
 
+  program.addCommand(createBackupCommand({
+    client,
+    log: (...args) => console.log(...args),
+  }));
+
+  program.addCommand(createRestoreCommand({
+    client,
+    log: (...args) => console.log(...args),
+  }));
+
   return program;
 }
 

src/cli/tests/commands/backup.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import { createBackupCommand, createRestoreCommand } from '../../src/commands/backup.js';
+
+const mockClient = {
+  get: vi.fn(),
+  post: vi.fn(),
+  put: vi.fn(),
+  delete: vi.fn(),
+};
+
+const log = vi.fn();
+
+describe('backup command', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  afterEach(() => {
+    // Clean up any created files
+    try { fs.unlinkSync('test-backup.json'); } catch { /* ignore */ }
+  });
+
+  it('creates backup command', () => {
+    const cmd = createBackupCommand({ client: mockClient as never, log });
+    expect(cmd.name()).toBe('backup');
+  });
+
+  it('calls API and writes file', async () => {
+    const bundle = { version: '1', servers: [], profiles: [], projects: [] };
+    mockClient.post.mockResolvedValue(bundle);
+
+    const cmd = createBackupCommand({ client: mockClient as never, log });
+    await cmd.parseAsync(['-o', 'test-backup.json'], { from: 'user' });
+
+    expect(mockClient.post).toHaveBeenCalledWith('/api/v1/backup', {});
+    expect(fs.existsSync('test-backup.json')).toBe(true);
+    expect(log).toHaveBeenCalledWith(expect.stringContaining('test-backup.json'));
+  });
+
+  it('passes password when provided', async () => {
+    mockClient.post.mockResolvedValue({ version: '1', servers: [], profiles: [], projects: [] });
+
+    const cmd = createBackupCommand({ client: mockClient as never, log });
+    await cmd.parseAsync(['-o', 'test-backup.json', '-p', 'secret'], { from: 'user' });
+
+    expect(mockClient.post).toHaveBeenCalledWith('/api/v1/backup', { password: 'secret' });
+  });
+
+  it('passes resource filter', async () => {
+    mockClient.post.mockResolvedValue({ version: '1', servers: [], profiles: [], projects: [] });
+
+    const cmd = createBackupCommand({ client: mockClient as never, log });
+    await cmd.parseAsync(['-o', 'test-backup.json', '-r', 'servers,profiles'], { from: 'user' });
+
+    expect(mockClient.post).toHaveBeenCalledWith('/api/v1/backup', {
+      resources: ['servers', 'profiles'],
+    });
+  });
+});
+
+describe('restore command', () => {
+  const testFile = 'test-restore-input.json';
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    fs.writeFileSync(testFile, JSON.stringify({
+      version: '1', servers: [], profiles: [], projects: [],
+    }));
+  });
+
+  afterEach(() => {
+    try { fs.unlinkSync(testFile); } catch { /* ignore */ }
+  });
+
+  it('creates restore command', () => {
+    const cmd = createRestoreCommand({ client: mockClient as never, log });
+    expect(cmd.name()).toBe('restore');
+  });
+
+  it('reads file and calls API', async () => {
+    mockClient.post.mockResolvedValue({
+      serversCreated: 1, serversSkipped: 0,
+      profilesCreated: 0, profilesSkipped: 0,
+      projectsCreated: 0, projectsSkipped: 0,
+      errors: [],
+    });
+
+    const cmd = createRestoreCommand({ client: mockClient as never, log });
+    await cmd.parseAsync(['-i', testFile], { from: 'user' });
+
+    expect(mockClient.post).toHaveBeenCalledWith('/api/v1/restore', expect.objectContaining({
+      bundle: expect.objectContaining({ version: '1' }),
+      conflictStrategy: 'skip',
+    }));
+    expect(log).toHaveBeenCalledWith('Restore complete:');
+  });
+
+  it('reports errors from restore', async () => {
+    mockClient.post.mockResolvedValue({
+      serversCreated: 0, serversSkipped: 0,
+      profilesCreated: 0, profilesSkipped: 0,
+      projectsCreated: 0, projectsSkipped: 0,
+      errors: ['Server "x" already exists'],
+    });
+
+    const cmd = createRestoreCommand({ client: mockClient as never, log });
+    await cmd.parseAsync(['-i', testFile], { from: 'user' });
+
+    expect(log).toHaveBeenCalledWith(expect.stringContaining('Errors'));
+  });
+
+  it('logs error for missing file', async () => {
+    const cmd = createRestoreCommand({ client: mockClient as never, log });
+    await cmd.parseAsync(['-i', 'nonexistent.json'], { from: 'user' });
+
+    expect(log).toHaveBeenCalledWith(expect.stringContaining('not found'));
+    expect(mockClient.post).not.toHaveBeenCalled();
+  });
+});