@aaronshaf/confluence-cli 0.1.15

package/src/lib/sync/sync-specific.ts

@@ -0,0 +1,221 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import type { ConfluenceClient, User } from '../confluence-client/index.js';
+import { SyncError } from '../errors.js';
+import { RESERVED_FILENAMES } from '../file-scanner.js';
+import { buildPageLookupMapFromCache, type MarkdownConverter } from '../markdown/index.js';
+import { buildPageStateFromFiles } from '../page-state.js';
+import {
+  readSpaceConfig,
+  updateLastSync,
+  updatePageSyncInfo,
+  writeSpaceConfig,
+  type SpaceConfigWithState,
+} from '../space-config.js';
+import type { SyncOptions, SyncResult } from './sync-engine.js';
+
+/**
+ * Create a cached user fetcher to avoid redundant API calls
+ */
+function createUserFetcher(client: ConfluenceClient): (accountId: string | undefined) => Promise<User | undefined> {
+  const cache = new Map<string, User | undefined>();
+  return async (accountId: string | undefined): Promise<User | undefined> => {
+    if (!accountId) return undefined;
+    if (cache.has(accountId)) {
+      return cache.get(accountId);
+    }
+    try {
+      const user = await client.getUser(accountId);
+      cache.set(accountId, user);
+      return user;
+    } catch {
+      cache.set(accountId, undefined);
+      return undefined;
+    }
+  };
+}
+
+/**
+ * Validate that a path stays within a base directory (prevents path traversal)
+ */
+function assertPathWithinDirectory(baseDir: string, targetPath: string): void {
+  const resolvedBase = resolve(baseDir);
+  const resolvedTarget = resolve(baseDir, targetPath);
+  if (!resolvedTarget.startsWith(`${resolvedBase}/`) && resolvedTarget !== resolvedBase) {
+    throw new SyncError(`Path traversal detected: "${targetPath}" escapes base directory`);
+  }
+}
+
+/**
+ * Check if a path uses a reserved filename (used by coding agents)
+ */
+function isReservedPath(path: string): boolean {
+  return RESERVED_FILENAMES.has(basename(path).toLowerCase());
+}
+
+/**
+ * Fast path: resync specific pages without fetching the entire space
+ */
+export async function syncSpecificPages(
+  client: ConfluenceClient,
+  converter: MarkdownConverter,
+  baseUrl: string,
+  directory: string,
+  pageRefs: string[],
+  options: SyncOptions = {},
+): Promise<SyncResult> {
+  const result: SyncResult = {
+    success: true,
+    changes: { added: [], modified: [], deleted: [] },
+    warnings: [],
+    errors: [],
+    cancelled: false,
+  };
+  const progress = options.progress;
+
+  try {
+    let config = readSpaceConfig(directory);
+    if (!config) {
+      throw new SyncError('No space configuration found.');
+    }
+
+    // Build reverse lookup from localPath to pageId
+    // Per ADR-0024: config.pages is now Record<string, string> (pageId -> localPath)
+    const pathToPageId = new Map<string, string>();
+    for (const [pageId, localPath] of Object.entries(config.pages)) {
+      pathToPageId.set(localPath, pageId);
+    }
+
+    // Resolve page references to IDs
+    const pageIds: string[] = [];
+    for (const pageRef of pageRefs) {
+      const normalizedPath = pageRef.replace(/^\.\//, '');
+      const normalizedId = pathToPageId.get(normalizedPath);
+      const directId = pathToPageId.get(pageRef);
+
+      if (normalizedId) {
+        pageIds.push(normalizedId);
+      } else if (directId) {
+        pageIds.push(directId);
+      } else if (config.pages[pageRef]) {
+        pageIds.push(pageRef);
+      } else {
+        result.warnings.push(`Could not find page for: ${pageRef}`);
+      }
+    }
+
+    if (pageIds.length === 0) {
+      return result;
+    }
+
+    progress?.onFetchStart?.();
+    progress?.onFetchComplete?.(pageIds.length, 0);
+
+    // Build diff - all specified pages are "modified"
+    // Per ADR-0024: config.pages[pageId] is now just the localPath string
+    for (const pageId of pageIds) {
+      const localPath = config.pages[pageId];
+      if (localPath) {
+        const title =
+          localPath
+            .split('/')
+            .pop()
+            ?.replace('.md', '')
+            .replace(/readme$/i, '') || pageId;
+        result.changes.modified.push({
+          type: 'modified',
+          pageId,
+          title,
+          localPath,
+        });
+      }
+    }
+
+    progress?.onDiffComplete?.(0, result.changes.modified.length, 0);
+
+    if (options.dryRun) {
+      return result;
+    }
+
+    // Create cached user fetcher
+    const fetchUser = createUserFetcher(client);
+
+    // Build page state and lookup map for link conversion (ADR-0022, ADR-0024)
+    // Enable duplicate title warnings during sync
+    const pageStateBuildResult = buildPageStateFromFiles(directory, config.pages);
+    result.warnings.push(...pageStateBuildResult.warnings);
+    const pageLookupMap = buildPageLookupMapFromCache(pageStateBuildResult, true);
+
+    // Process each page
+    let currentChange = 0;
+    const totalChanges = result.changes.modified.length;
+
+    for (const change of result.changes.modified) {
+      currentChange++;
+      progress?.onPageStart?.(currentChange, totalChanges, change.title, 'modified');
+
+      // Skip reserved filenames (used by coding agents)
+      if (change.localPath && isReservedPath(change.localPath)) {
+        result.warnings.push(`Skipping page "${change.title}": reserved filename ${basename(change.localPath)}`);
+        continue;
+      }
+
+      try {
+        const fullPage = await client.getPage(change.pageId, true);
+        const labels = await client.getAllLabels(change.pageId);
+
+        // Per ADR-0024: config.pages[id] is just localPath, get parent title from path
+        let parentTitle: string | undefined;
+        const parentLocalPath = fullPage.parentId ? config.pages[fullPage.parentId] : undefined;
+        if (parentLocalPath) {
+          parentTitle = parentLocalPath.split('/').pop()?.replace('.md', '');
+        }
+
+        // Get author and last modifier user information (cached)
+        const author = await fetchUser(fullPage.authorId);
+        const lastModifier = await fetchUser(fullPage.version?.authorId);
+
+        const localPath = change.localPath ?? '';
+
+        // Convert to markdown with link conversion (ADR-0022)
+        // Note: childCount is undefined for specific-page syncs (requires full sync to compute)
+        const { markdown, warnings } = converter.convertPage(
+          fullPage,
+          labels,
+          parentTitle,
+          baseUrl,
+          author,
+          lastModifier,
+          localPath,
+          pageLookupMap,
+          undefined, // childCount not available in specific-page sync
+        );
+        result.warnings.push(...warnings.map((w) => `${fullPage.title}: ${w}`));
+
+        assertPathWithinDirectory(directory, localPath);
+        const fullPath = join(directory, localPath);
+        mkdirSync(dirname(fullPath), { recursive: true });
+        writeFileSync(fullPath, markdown, 'utf-8');
+
+        // Per ADR-0024: Only store pageId -> localPath mapping
+        // Version, title, timestamps are in frontmatter
+        config = updatePageSyncInfo(config, { pageId: change.pageId, localPath });
+        writeSpaceConfig(directory, config);
+
+        progress?.onPageComplete?.(currentChange, totalChanges, change.title, localPath);
+      } catch (error) {
+        result.errors.push(`Failed to sync page "${change.title}": ${error}`);
+        result.success = false;
+        progress?.onPageError?.(change.title, String(error));
+      }
+    }
+
+    config = updateLastSync(config);
+    writeSpaceConfig(directory, config);
+  } catch (error) {
+    result.errors.push(`Sync failed: ${error}`);
+    result.success = false;
+  }
+
+  return result;
+}

package/src/lib/sync/types.ts

@@ -0,0 +1,42 @@
+/** Sync diff types */
+export interface SyncChange {
+  type: 'added' | 'modified' | 'deleted';
+  pageId: string;
+  title: string;
+  localPath?: string;
+}
+
+export interface SyncDiff {
+  added: SyncChange[];
+  modified: SyncChange[];
+  deleted: SyncChange[];
+}
+
+/**
+ * Progress reporter for sync operations
+ */
+export interface SyncProgressReporter {
+  onFetchStart?: () => void;
+  onFetchComplete?: (pageCount: number, folderCount: number) => void;
+  onDiffComplete?: (added: number, modified: number, deleted: number) => void;
+  onPageStart?: (index: number, total: number, title: string, type: 'added' | 'modified' | 'deleted') => void;
+  onPageComplete?: (index: number, total: number, title: string, localPath: string) => void;
+  onPageError?: (title: string, error: string) => void;
+}
+
+export interface SyncOptions {
+  dryRun?: boolean;
+  force?: boolean;
+  forcePages?: string[]; // Page IDs or local paths to force resync
+  depth?: number;
+  progress?: SyncProgressReporter;
+  signal?: { cancelled: boolean };
+}
+
+export interface SyncResult {
+  success: boolean;
+  changes: SyncDiff;
+  warnings: string[];
+  errors: string[];
+  cancelled?: boolean;
+}

package/src/test/attachments.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test';
+import { HttpResponse, http } from 'msw';
+import { ConfluenceClient } from '../lib/confluence-client/client.js';
+import { createValidAttachment } from './msw-schema-validation.js';
+import { server } from './setup-msw.js';
+
+const testConfig = {
+  confluenceUrl: 'https://test.atlassian.net',
+  email: 'test@example.com',
+  apiToken: 'test-token',
+};
+
+describe('ConfluenceClient - attachment operations', () => {
+  test('lists attachments (empty by default)', async () => {
+    const client = new ConfluenceClient(testConfig);
+    const response = await client.getAttachments('page-123');
+    expect(response.results).toBeArray();
+    expect(response.results.length).toBe(0);
+  });
+
+  test('lists attachments when present', async () => {
+    server.use(
+      http.get('*/wiki/api/v2/pages/:pageId/attachments', () => {
+        return HttpResponse.json({
+          results: [createValidAttachment({ id: 'att-1', title: 'image.png', mediaType: 'image/png', fileSize: 2048 })],
+        });
+      }),
+    );
+
+    const client = new ConfluenceClient(testConfig);
+    const response = await client.getAttachments('page-123');
+    expect(response.results.length).toBe(1);
+    expect(response.results[0].id).toBe('att-1');
+    expect(response.results[0].title).toBe('image.png');
+  });
+
+  test('uploads attachment without throwing', async () => {
+    const client = new ConfluenceClient(testConfig);
+    await client.uploadAttachment('page-123', 'test.png', Buffer.from('fake-image-data'), 'image/png');
+  });
+
+  test('deletes attachment without throwing', async () => {
+    const client = new ConfluenceClient(testConfig);
+    await client.deleteAttachment('att-123');
+  });
+
+  test('throws on 401 when getting attachments', async () => {
+    server.use(
+      http.get('*/wiki/api/v2/pages/:pageId/attachments', () => {
+        return HttpResponse.json({ error: 'Unauthorized' }, { status: 401 });
+      }),
+    );
+
+    const client = new ConfluenceClient(testConfig);
+    await expect(client.getAttachments('page-123')).rejects.toThrow();
+  });
+
+  test('throws on 404 when deleting attachment', async () => {
+    server.use(
+      http.delete('*/wiki/api/v2/attachments/:attachmentId', () => {
+        return HttpResponse.json({ error: 'Not found' }, { status: 404 });
+      }),
+    );
+
+    const client = new ConfluenceClient(testConfig);
+    await expect(client.deleteAttachment('nonexistent')).rejects.toThrow();
+  });
+});

package/src/test/clone.test.ts

@@ -0,0 +1,373 @@
+import { afterEach, beforeEach, describe, expect, test, spyOn } from 'bun:test';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { http, HttpResponse } from 'msw';
+import { cloneCommand } from '../cli/commands/clone.js';
+import { server } from './setup-msw.js';
+import { createValidSpace, createValidPage } from './msw-schema-validation.js';
+
+describe('cloneCommand', () => {
+  let testDir: string;
+  let originalCwd: string;
+
+  beforeEach(() => {
+    // Create a unique test directory
+    testDir = join(tmpdir(), `cn-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+
+    // Change to test directory
+    originalCwd = process.cwd();
+    process.chdir(testDir);
+
+    // Mock config
+    process.env.HOME = testDir;
+    const configDir = join(testDir, '.cn');
+    mkdirSync(configDir, { recursive: true });
+    Bun.write(
+      join(configDir, 'config.json'),
+      JSON.stringify({
+        baseUrl: 'https://test.atlassian.net',
+        email: 'test@example.com',
+        apiToken: 'test-token',
+      }),
+    );
+  });
+
+  afterEach(() => {
+    // Restore original directory
+    process.chdir(originalCwd);
+
+    // Clean up test directory
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true });
+    }
+  });
+
+  describe('single space', () => {
+    beforeEach(() => {
+      // Mock API responses for single space
+      server.use(
+        http.get('*/wiki/api/v2/spaces', ({ request }) => {
+          const url = new URL(request.url);
+          const keys = url.searchParams.get('keys');
+          if (keys === 'TEST1') {
+            return HttpResponse.json({
+              results: [createValidSpace({ id: 'space-123', key: 'TEST1', name: 'Test Space 1' })],
+            });
+          }
+          return HttpResponse.json({ results: [] });
+        }),
+        http.get('*/wiki/api/v2/spaces/:spaceId/pages', () => {
+          return HttpResponse.json({
+            results: [
+              createValidPage({
+                id: 'page-1',
+                spaceId: 'space-123',
+                title: 'Home',
+                parentId: null,
+              }),
+            ],
+          });
+        }),
+        http.get('*/wiki/api/v2/pages/:pageId', () => {
+          return HttpResponse.json(
+            createValidPage({
+              id: 'page-1',
+              spaceId: 'space-123',
+              title: 'Home',
+              parentId: null,
+              body: '<p>Test content</p>',
+            }),
+          );
+        }),
+      );
+    });
+
+    test('clones a single space successfully', async () => {
+      await cloneCommand({ spaceKeys: ['TEST1'] });
+
+      // Verify directory was created
+      expect(existsSync(join(testDir, 'TEST1'))).toBe(true);
+
+      // Verify .confluence.json was created
+      expect(existsSync(join(testDir, 'TEST1', '.confluence.json'))).toBe(true);
+    });
+
+    test('throws error if directory already exists', async () => {
+      // Create directory first
+      mkdirSync(join(testDir, 'TEST1'));
+
+      const exitSpy = spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('process.exit called');
+      });
+
+      await expect(cloneCommand({ spaceKeys: ['TEST1'] })).rejects.toThrow('process.exit called');
+
+      exitSpy.mockRestore();
+    });
+  });
+
+  describe('multiple spaces', () => {
+    beforeEach(() => {
+      // Mock API responses for multiple spaces
+      server.use(
+        http.get('*/wiki/api/v2/spaces', ({ request }) => {
+          const url = new URL(request.url);
+          const keys = url.searchParams.get('keys');
+
+          if (keys === 'TEST1') {
+            return HttpResponse.json({
+              results: [createValidSpace({ id: 'space-123', key: 'TEST1', name: 'Test Space 1' })],
+            });
+          }
+          if (keys === 'TEST2') {
+            return HttpResponse.json({
+              results: [createValidSpace({ id: 'space-456', key: 'TEST2', name: 'Test Space 2' })],
+            });
+          }
+          if (keys === 'TEST3') {
+            return HttpResponse.json({
+              results: [createValidSpace({ id: 'space-789', key: 'TEST3', name: 'Test Space 3' })],
+            });
+          }
+          return HttpResponse.json({ results: [] });
+        }),
+        http.get('*/wiki/api/v2/spaces/:spaceId/pages', () => {
+          return HttpResponse.json({
+            results: [
+              createValidPage({
+                id: 'page-1',
+                spaceId: 'space-123',
+                title: 'Home',
+                parentId: null,
+              }),
+            ],
+          });
+        }),
+        http.get('*/wiki/api/v2/pages/:pageId', () => {
+          return HttpResponse.json(
+            createValidPage({
+              id: 'page-1',
+              spaceId: 'space-123',
+              title: 'Home',
+              parentId: null,
+              body: '<p>Test content</p>',
+            }),
+          );
+        }),
+      );
+    });
+
+    test('clones multiple spaces successfully', async () => {
+      await cloneCommand({ spaceKeys: ['TEST1', 'TEST2', 'TEST3'] });
+
+      // Verify all directories were created
+      expect(existsSync(join(testDir, 'TEST1'))).toBe(true);
+      expect(existsSync(join(testDir, 'TEST2'))).toBe(true);
+      expect(existsSync(join(testDir, 'TEST3'))).toBe(true);
+
+      // Verify .confluence.json was created for each
+      expect(existsSync(join(testDir, 'TEST1', '.confluence.json'))).toBe(true);
+      expect(existsSync(join(testDir, 'TEST2', '.confluence.json'))).toBe(true);
+      expect(existsSync(join(testDir, 'TEST3', '.confluence.json'))).toBe(true);
+    });
+
+    test('continues cloning when one space fails', async () => {
+      // Pre-create TEST2 directory to cause failure
+      mkdirSync(join(testDir, 'TEST2'));
+
+      const exitSpy = spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('process.exit called');
+      });
+
+      await expect(cloneCommand({ spaceKeys: ['TEST1', 'TEST2', 'TEST3'] })).rejects.toThrow('process.exit called');
+
+      // Verify TEST1 and TEST3 were still created
+      expect(existsSync(join(testDir, 'TEST1'))).toBe(true);
+      expect(existsSync(join(testDir, 'TEST3'))).toBe(true);
+
+      // Verify TEST2 already existed
+      expect(existsSync(join(testDir, 'TEST2', '.confluence.json'))).toBe(false);
+
+      // Verify process.exit was called with error code
+      expect(exitSpy).toHaveBeenCalled();
+
+      exitSpy.mockRestore();
+    });
+
+    test('exits with error code when all spaces fail', async () => {
+      // Pre-create all directories to cause all failures
+      mkdirSync(join(testDir, 'TEST1'));
+      mkdirSync(join(testDir, 'TEST2'));
+      mkdirSync(join(testDir, 'TEST3'));
+
+      const exitSpy = spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('process.exit called');
+      });
+
+      await expect(cloneCommand({ spaceKeys: ['TEST1', 'TEST2', 'TEST3'] })).rejects.toThrow('process.exit called');
+
+      expect(exitSpy).toHaveBeenCalled();
+
+      exitSpy.mockRestore();
+    });
+  });
+
+  describe('error handling', () => {
+    test('exits if not configured', async () => {
+      // Create a new test directory without config
+      const noConfigDir = join(tmpdir(), `cn-test-noconfig-${Date.now()}`);
+      mkdirSync(noConfigDir, { recursive: true });
+
+      // Save and override CN_CONFIG_PATH to point to directory without config
+      const savedConfigPath = process.env.CN_CONFIG_PATH;
+      process.env.CN_CONFIG_PATH = noConfigDir;
+
+      const exitSpy = spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('process.exit called');
+      });
+
+      try {
+        await expect(cloneCommand({ spaceKeys: ['TEST1'] })).rejects.toThrow('process.exit called');
+      } finally {
+        exitSpy.mockRestore();
+
+        // Restore
+        if (savedConfigPath) {
+          process.env.CN_CONFIG_PATH = savedConfigPath;
+        } else {
+          delete process.env.CN_CONFIG_PATH;
+        }
+
+        // Clean up
+        if (existsSync(noConfigDir)) {
+          rmSync(noConfigDir, { recursive: true });
+        }
+      }
+    });
+
+    test('handles space not found error', async () => {
+      // Mock API to return no spaces
+      server.use(
+        http.get('*/wiki/api/v2/spaces', () => {
+          return HttpResponse.json({ results: [] });
+        }),
+      );
+
+      const exitSpy = spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('process.exit called');
+      });
+
+      await expect(cloneCommand({ spaceKeys: ['NOTFOUND'] })).rejects.toThrow('process.exit called');
+
+      exitSpy.mockRestore();
+    });
+
+    test('handles duplicate space keys', async () => {
+      const exitSpy = spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('process.exit called');
+      });
+
+      await expect(cloneCommand({ spaceKeys: ['TEST1', 'TEST2', 'TEST1'] })).rejects.toThrow('process.exit called');
+
+      exitSpy.mockRestore();
+    });
+  });
+
+  describe('console output', () => {
+    beforeEach(() => {
+      // Mock API responses for console output tests
+      server.use(
+        http.get('*/wiki/api/v2/spaces', ({ request }) => {
+          const url = new URL(request.url);
+          const keys = url.searchParams.get('keys');
+          if (keys === 'TEST1' || keys === 'TEST2' || keys === 'TEST3') {
+            return HttpResponse.json({
+              results: [
+                createValidSpace({
+                  id: `space-${keys}`,
+                  key: keys || 'TEST1',
+                  name: `Test Space ${keys}`,
+                }),
+              ],
+            });
+          }
+          return HttpResponse.json({ results: [] });
+        }),
+        http.get('*/wiki/api/v2/spaces/:spaceId/pages', () => {
+          return HttpResponse.json({
+            results: [
+              createValidPage({
+                id: 'page-1',
+                spaceId: 'space-123',
+                title: 'Home',
+                parentId: null,
+              }),
+            ],
+          });
+        }),
+        http.get('*/wiki/api/v2/pages/:pageId', () => {
+          return HttpResponse.json(
+            createValidPage({
+              id: 'page-1',
+              spaceId: 'space-123',
+              title: 'Home',
+              parentId: null,
+              body: '<p>Test content</p>',
+            }),
+          );
+        }),
+      );
+    });
+
+    test('displays separator and progress for multiple spaces', async () => {
+      const consoleSpy = spyOn(console, 'log');
+
+      await cloneCommand({ spaceKeys: ['TEST1', 'TEST2', 'TEST3'] });
+
+      // Check for progress indicators
+      const output = consoleSpy.mock.calls.map((call) => call[0]).join('\n');
+      expect(output).toContain('Cloning 1/3:');
+      expect(output).toContain('Cloning 2/3:');
+      expect(output).toContain('Cloning 3/3:');
+      expect(output).toContain('Clone Summary');
+      expect(output).toContain('Successfully cloned:');
+
+      consoleSpy.mockRestore();
+    });
+
+    test('does not display separator for single space', async () => {
+      const consoleSpy = spyOn(console, 'log');
+
+      await cloneCommand({ spaceKeys: ['TEST1'] });
+
+      // Check that separator is NOT displayed
+      const output = consoleSpy.mock.calls.map((call) => call[0]).join('\n');
+      expect(output).not.toContain('Clone Summary');
+      expect(output).not.toContain('Cloning 1/1:');
+
+      consoleSpy.mockRestore();
+    });
+
+    test('displays failure details in summary', async () => {
+      // Pre-create TEST2 directory to cause failure
+      mkdirSync(join(testDir, 'TEST2'));
+
+      const consoleSpy = spyOn(console, 'log');
+      const exitSpy = spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('process.exit called');
+      });
+
+      await expect(cloneCommand({ spaceKeys: ['TEST1', 'TEST2', 'TEST3'] })).rejects.toThrow('process.exit called');
+
+      const output = consoleSpy.mock.calls.map((call) => call[0]).join('\n');
+      expect(output).toContain('Failed to clone:');
+      expect(output).toContain('TEST2');
+      expect(output).toContain('already exists');
+
+      consoleSpy.mockRestore();
+      exitSpy.mockRestore();
+    });
+  });
+});