@aaronshaf/confluence-cli 0.1.15

package/src/lib/errors.ts

@@ -0,0 +1,237 @@
+/**
+ * Error types for cn CLI with discriminated unions using _tag property
+ * These error types follow the Effect pattern for type-safe error handling
+ */
+
+/**
+ * Configuration-related errors (missing config, invalid config path)
+ */
+export class ConfigError extends Error {
+  readonly _tag = 'ConfigError' as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+/**
+ * File system operation errors
+ */
+export class FileSystemError extends Error {
+  readonly _tag = 'FileSystemError' as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'FileSystemError';
+  }
+}
+
+/**
+ * JSON parsing errors
+ */
+export class ParseError extends Error {
+  readonly _tag = 'ParseError' as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ParseError';
+  }
+}
+
+/**
+ * Schema validation errors
+ */
+export class ValidationError extends Error {
+  readonly _tag = 'ValidationError' as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * API request errors with status code
+ */
+export class ApiError extends Error {
+  readonly _tag = 'ApiError' as const;
+  readonly statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = 'ApiError';
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Rate limit errors (429 responses)
+ */
+export class RateLimitError extends Error {
+  readonly _tag = 'RateLimitError' as const;
+  readonly retryAfter?: number;
+
+  constructor(message: string, retryAfter?: number) {
+    super(message);
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Authentication errors (401, 403)
+ */
+export class AuthError extends Error {
+  readonly _tag = 'AuthError' as const;
+  readonly statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = 'AuthError';
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Sync operation errors
+ */
+export class SyncError extends Error {
+  readonly _tag = 'SyncError' as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'SyncError';
+  }
+}
+
+/**
+ * Network/connectivity errors
+ */
+export class NetworkError extends Error {
+  readonly _tag = 'NetworkError' as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'NetworkError';
+  }
+}
+
+/**
+ * Space not found errors
+ */
+export class SpaceNotFoundError extends Error {
+  readonly _tag = 'SpaceNotFoundError' as const;
+  readonly spaceKey: string;
+
+  constructor(spaceKey: string) {
+    super(`Space not found: ${spaceKey}`);
+    this.name = 'SpaceNotFoundError';
+    this.spaceKey = spaceKey;
+  }
+}
+
+/**
+ * Page not found errors (404 when updating)
+ */
+export class PageNotFoundError extends Error {
+  readonly _tag = 'PageNotFoundError' as const;
+  readonly pageId: string;
+
+  constructor(pageId: string) {
+    super(`Page not found: ${pageId}`);
+    this.name = 'PageNotFoundError';
+    this.pageId = pageId;
+  }
+}
+
+/**
+ * Version conflict errors (409 when updating with stale version)
+ */
+export class VersionConflictError extends Error {
+  readonly _tag = 'VersionConflictError' as const;
+  readonly localVersion: number;
+  readonly remoteVersion: number;
+
+  constructor(localVersion: number, remoteVersion: number) {
+    super(`Version conflict: local version ${localVersion} does not match remote version ${remoteVersion}`);
+    this.name = 'VersionConflictError';
+    this.localVersion = localVersion;
+    this.remoteVersion = remoteVersion;
+  }
+}
+
+/**
+ * Folder not found errors (404 when folder is deleted on Confluence)
+ * Per ADR-0023: Folder push workflow support
+ */
+export class FolderNotFoundError extends Error {
+  readonly _tag = 'FolderNotFoundError' as const;
+  readonly folderId: string;
+
+  constructor(folderId: string) {
+    super(`Folder not found: ${folderId}`);
+    this.name = 'FolderNotFoundError';
+    this.folderId = folderId;
+  }
+}
+
+/**
+ * Union type of all error types for comprehensive error handling
+ */
+export type CnError =
+  | ConfigError
+  | FileSystemError
+  | ParseError
+  | ValidationError
+  | ApiError
+  | RateLimitError
+  | AuthError
+  | SyncError
+  | NetworkError
+  | SpaceNotFoundError
+  | PageNotFoundError
+  | VersionConflictError
+  | FolderNotFoundError;
+
+/**
+ * Exit codes for CLI
+ */
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  GENERAL_ERROR: 1,
+  CONFIG_ERROR: 2,
+  AUTH_ERROR: 3,
+  NETWORK_ERROR: 4,
+  SPACE_NOT_FOUND: 5,
+  INVALID_ARGUMENTS: 6,
+  PAGE_NOT_FOUND: 7,
+  VERSION_CONFLICT: 8,
+  FOLDER_NOT_FOUND: 9,
+} as const;
+
+/**
+ * Get exit code for a given error
+ */
+export function getExitCodeForError(error: CnError): number {
+  switch (error._tag) {
+    case 'ConfigError':
+    case 'ValidationError':
+      return EXIT_CODES.CONFIG_ERROR;
+    case 'AuthError':
+      return EXIT_CODES.AUTH_ERROR;
+    case 'NetworkError':
+    case 'RateLimitError':
+      return EXIT_CODES.NETWORK_ERROR;
+    case 'SpaceNotFoundError':
+      return EXIT_CODES.SPACE_NOT_FOUND;
+    case 'PageNotFoundError':
+      return EXIT_CODES.PAGE_NOT_FOUND;
+    case 'VersionConflictError':
+      return EXIT_CODES.VERSION_CONFLICT;
+    case 'FolderNotFoundError':
+      return EXIT_CODES.FOLDER_NOT_FOUND;
+    default:
+      return EXIT_CODES.GENERAL_ERROR;
+  }
+}

package/src/lib/file-scanner.ts

@@ -0,0 +1,195 @@
+import { readFileSync, readdirSync, statSync, type Stats } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parseMarkdown } from './markdown/index.js';
+
+/**
+ * Directories to exclude from scanning
+ */
+export const EXCLUDED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  '.nuxt',
+  '.cache',
+  '.turbo',
+  'out',
+  'vendor',
+  '__pycache__',
+  '.venv',
+  'venv',
+]);
+
+/**
+ * Reserved filenames that should not be synced (used by coding agents)
+ * Checked case-insensitively
+ */
+export const RESERVED_FILENAMES = new Set(['claude.md', 'agents.md']);
+
+/**
+ * Scans a directory recursively for markdown files.
+ * Excludes common build/dependency directories and hidden files.
+ *
+ * @param directory - Root directory to scan for markdown files
+ * @returns Array of relative paths to markdown files, sorted alphabetically
+ *
+ * @example
+ * ```typescript
+ * const files = scanMarkdownFiles('/path/to/project');
+ * // Returns: ['README.md', 'docs/guide.md', 'docs/api/endpoints.md']
+ * ```
+ */
+export function scanMarkdownFiles(directory: string): string[] {
+  const files: string[] = [];
+
+  function scan(dir: string): void {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      // Skip hidden files/directories (starting with .)
+      if (entry.startsWith('.')) {
+        continue;
+      }
+
+      // Skip excluded directories
+      if (EXCLUDED_DIRS.has(entry)) {
+        continue;
+      }
+
+      const fullPath = join(dir, entry);
+      let stat: Stats;
+      try {
+        stat = statSync(fullPath);
+      } catch {
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        scan(fullPath);
+      } else if (stat.isFile() && entry.endsWith('.md')) {
+        // Skip reserved filenames (used by coding agents)
+        if (RESERVED_FILENAMES.has(entry.toLowerCase())) {
+          continue;
+        }
+        // Return path relative to the root directory
+        files.push(relative(directory, fullPath));
+      }
+    }
+  }
+
+  scan(directory);
+  return files.sort();
+}
+
+/**
+ * Represents a file that may need to be pushed
+ */
+export interface PushCandidate {
+  /** Relative path from directory root */
+  path: string;
+  /** Whether this is a new file (no page_id) or modified existing file */
+  type: 'new' | 'modified';
+  /** Title from frontmatter or filename */
+  title: string;
+  /** Page ID if it exists */
+  pageId?: string;
+}
+
+/**
+ * Detects which markdown files need to be pushed to Confluence.
+ *
+ * @param directory - Root directory to scan for changed files
+ * @returns Array of files that are new or modified since last sync
+ *
+ * Detection logic:
+ * - **New files**: have no `page_id` in frontmatter
+ * - **Modified files**: have `page_id` and file mtime > `synced_at` + 1 second
+ *
+ * The 1-second tolerance accounts for filesystem write timing during pull operations.
+ * Files without `synced_at` but with `page_id` are treated as modified.
+ *
+ * @example
+ * ```typescript
+ * const candidates = detectPushCandidates('/path/to/project');
+ * for (const candidate of candidates) {
+ *   console.log(`${candidate.type}: ${candidate.path}`);
+ * }
+ * ```
+ */
+export function detectPushCandidates(directory: string): PushCandidate[] {
+  const files = scanMarkdownFiles(directory);
+  const candidates: PushCandidate[] = [];
+
+  for (const relativePath of files) {
+    const fullPath = join(directory, relativePath);
+
+    let content: string;
+    try {
+      content = readFileSync(fullPath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const { frontmatter } = parseMarkdown(content);
+
+    // Get file title from frontmatter or filename
+    const filename = relativePath.split('/').pop()?.replace(/\.md$/, '') ?? relativePath.replace(/\.md$/, '');
+    const title = (frontmatter.title as string) || filename;
+
+    // New file - no page_id
+    if (!frontmatter.page_id) {
+      candidates.push({
+        path: relativePath,
+        type: 'new',
+        title,
+      });
+      continue;
+    }
+
+    // Existing file - check if modified since last sync
+    const syncedAt = frontmatter.synced_at as string | undefined;
+    if (!syncedAt) {
+      // No synced_at means it was never synced, treat as modified
+      candidates.push({
+        path: relativePath,
+        type: 'modified',
+        title,
+        pageId: frontmatter.page_id as string,
+      });
+      continue;
+    }
+
+    // Compare file mtime to synced_at
+    let stat: Stats;
+    try {
+      stat = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    const syncedAtTime = new Date(syncedAt).getTime();
+    const mtimeMs = stat.mtimeMs;
+
+    // Add 1 second tolerance to account for filesystem write timing
+    // during pull operations (file mtime is set slightly after synced_at)
+    const TOLERANCE_MS = 1000;
+
+    if (mtimeMs > syncedAtTime + TOLERANCE_MS) {
+      candidates.push({
+        path: relativePath,
+        type: 'modified',
+        title,
+        pageId: frontmatter.page_id as string,
+      });
+    }
+  }
+
+  return candidates;
+}