@aaronshaf/confluence-cli 0.1.15

package/src/lib/space-config.ts

@@ -0,0 +1,264 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Schema } from 'effect';
+
+/**
+ * Legacy page sync info schema for migration detection
+ * Per ADR-0024: This format is deprecated in favor of frontmatter as source of truth
+ * @deprecated Use page mappings (pageId -> localPath) instead
+ */
+const LegacyPageSyncInfoSchema = Schema.Struct({
+  pageId: Schema.String,
+  version: Schema.Number,
+  lastModified: Schema.optional(Schema.String),
+  localPath: Schema.String,
+  title: Schema.optional(Schema.String),
+});
+
+/**
+ * Legacy page sync information - kept for migration support
+ * Per ADR-0024: Version, title, lastModified now read from frontmatter
+ * @deprecated Use page mappings and read frontmatter for full info
+ */
+export type PageSyncInfo = Schema.Schema.Type<typeof LegacyPageSyncInfoSchema>;
+
+/**
+ * Folder sync info schema for tracking created folders
+ * Per ADR-0023: Folder push workflow support
+ */
+const FolderSyncInfoSchema = Schema.Struct({
+  folderId: Schema.String,
+  title: Schema.String,
+  parentId: Schema.optional(Schema.String),
+  localPath: Schema.String, // Directory path, e.g., "docs/api"
+});
+
+/**
+ * Folder sync information stored in .confluence.json
+ * Per ADR-0023: Folder push workflow support
+ */
+export type FolderSyncInfo = Schema.Schema.Type<typeof FolderSyncInfoSchema>;
+
+/**
+ * Space configuration schema
+ */
+const SpaceConfigSchema = Schema.Struct({
+  spaceKey: Schema.String,
+  spaceId: Schema.String,
+  spaceName: Schema.String,
+  lastSync: Schema.optional(Schema.String),
+  syncState: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+});
+
+export type SpaceConfig = Schema.Schema.Type<typeof SpaceConfigSchema>;
+
+/**
+ * Full space configuration schema including sync state
+ * Per ADR-0024: pages is now a simple mapping (pageId -> localPath)
+ * Version, title, and timestamps are read from frontmatter when needed
+ */
+const SpaceConfigWithStateSchema = Schema.Struct({
+  spaceKey: Schema.String,
+  spaceId: Schema.String,
+  spaceName: Schema.String,
+  lastSync: Schema.optional(Schema.String),
+  syncState: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+  pages: Schema.Record({ key: Schema.String, value: Schema.String }), // pageId -> localPath
+  folders: Schema.optional(Schema.Record({ key: Schema.String, value: FolderSyncInfoSchema })),
+});
+
+/**
+ * Full space configuration including sync state
+ * Per ADR-0024: pages is now Record<string, string> (pageId -> localPath)
+ */
+export type SpaceConfigWithState = Schema.Schema.Type<typeof SpaceConfigWithStateSchema>;
+
+/**
+ * Detect if pages object is in legacy format (object values vs string values)
+ */
+function isLegacyFormat(pages: Record<string, unknown>): boolean {
+  const firstValue = Object.values(pages)[0];
+  return typeof firstValue === 'object' && firstValue !== null;
+}
+
+/**
+ * Migrate legacy pages format to new format
+ * Legacy: { pageId: { pageId, version, localPath, ... } }
+ * New: { pageId: localPath }
+ */
+function migrateLegacyPages(pages: Record<string, unknown>): Record<string, string> {
+  const migrated: Record<string, string> = {};
+  for (const [id, page] of Object.entries(pages)) {
+    if (typeof page === 'object' && page !== null && 'localPath' in page) {
+      migrated[id] = (page as { localPath: string }).localPath;
+    }
+  }
+  return migrated;
+}
+
+const CONFIG_FILENAME = '.confluence.json';
+
+/**
+ * Read space configuration from the current directory
+ * Validates the config against the schema for security
+ * Per ADR-0024: Auto-migrates legacy format to new format
+ */
+export function readSpaceConfig(directory: string): SpaceConfigWithState | null {
+  const configPath = join(directory, CONFIG_FILENAME);
+
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(content);
+
+    // Check for legacy format and migrate if needed (ADR-0024)
+    // Note: If multiple processes read the config simultaneously during migration,
+    // both may attempt to write. This is acceptable for a CLI tool since:
+    // 1. Migration is idempotent (same result regardless of which write wins)
+    // 2. Concurrent CLI invocations on the same space are rare in practice
+    if (parsed.pages && Object.keys(parsed.pages).length > 0 && isLegacyFormat(parsed.pages)) {
+      const migratedPages = migrateLegacyPages(parsed.pages);
+      const migrated = { ...parsed, pages: migratedPages };
+
+      // Write migrated config back to disk
+      writeFileSync(configPath, JSON.stringify(migrated, null, 2), 'utf-8');
+
+      // Validate and return migrated config
+      return Schema.decodeUnknownSync(SpaceConfigWithStateSchema)(migrated);
+    }
+
+    // Validate against schema to prevent malformed config attacks
+    return Schema.decodeUnknownSync(SpaceConfigWithStateSchema)(parsed);
+  } catch {
+    // Invalid config file - return null to indicate no valid config
+    return null;
+  }
+}
+
+/**
+ * Write space configuration to the current directory
+ */
+export function writeSpaceConfig(directory: string, config: SpaceConfigWithState): void {
+  const configPath = join(directory, CONFIG_FILENAME);
+  writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+/**
+ * Check if a directory has space configuration
+ */
+export function hasSpaceConfig(directory: string): boolean {
+  return existsSync(join(directory, CONFIG_FILENAME));
+}
+
+/**
+ * Create initial space configuration
+ */
+export function createSpaceConfig(spaceKey: string, spaceId: string, spaceName: string): SpaceConfigWithState {
+  return {
+    spaceKey,
+    spaceId,
+    spaceName,
+    pages: {},
+  };
+}
+
+/**
+ * Update the last sync time in the configuration
+ */
+export function updateLastSync(config: SpaceConfigWithState): SpaceConfigWithState {
+  return {
+    ...config,
+    lastSync: new Date().toISOString(),
+  };
+}
+
+/**
+ * Add or update a page in the sync state
+ * Per ADR-0024: Only stores the mapping (pageId -> localPath)
+ * Version, title, timestamps are read from frontmatter when needed
+ *
+ * @param config - Current space configuration
+ * @param pageInfo - Page info (only pageId and localPath are stored)
+ */
+export function updatePageSyncInfo(
+  config: SpaceConfigWithState,
+  pageInfo: { pageId: string; localPath: string },
+): SpaceConfigWithState {
+  return {
+    ...config,
+    pages: {
+      ...config.pages,
+      [pageInfo.pageId]: pageInfo.localPath,
+    },
+  };
+}
+
+/**
+ * Remove a page from the sync state
+ */
+export function removePageSyncInfo(config: SpaceConfigWithState, pageId: string): SpaceConfigWithState {
+  const { [pageId]: _, ...remainingPages } = config.pages;
+  return {
+    ...config,
+    pages: remainingPages,
+  };
+}
+
+/**
+ * Get all tracked page IDs
+ */
+export function getTrackedPageIds(config: SpaceConfigWithState): string[] {
+  return Object.keys(config.pages);
+}
+
+/**
+ * Add or update a folder in the sync state
+ * Per ADR-0023: Folder push workflow support
+ */
+export function updateFolderSyncInfo(config: SpaceConfigWithState, folderInfo: FolderSyncInfo): SpaceConfigWithState {
+  return {
+    ...config,
+    folders: {
+      ...(config.folders || {}),
+      [folderInfo.folderId]: folderInfo,
+    },
+  };
+}
+
+/**
+ * Get a folder by its local path
+ * Per ADR-0023: Folder push workflow support
+ */
+export function getFolderByPath(config: SpaceConfigWithState, localPath: string): FolderSyncInfo | undefined {
+  if (!config.folders) return undefined;
+  for (const folder of Object.values(config.folders)) {
+    if (folder.localPath === localPath) {
+      return folder;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Get a folder by its ID
+ * Per ADR-0023: Folder push workflow support
+ */
+export function getFolderById(config: SpaceConfigWithState, folderId: string): FolderSyncInfo | undefined {
+  return config.folders?.[folderId];
+}
+
+/**
+ * Remove a folder from the sync state
+ * Per ADR-0023: Folder push workflow support
+ */
+export function removeFolderSyncInfo(config: SpaceConfigWithState, folderId: string): SpaceConfigWithState {
+  if (!config.folders) return config;
+  const { [folderId]: _, ...remainingFolders } = config.folders;
+  return {
+    ...config,
+    folders: remainingFolders,
+  };
+}

package/src/lib/sync/cleanup.ts

@@ -0,0 +1,50 @@
+import { existsSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { assertPathWithinDirectory } from './folder-path.js';
+
+/**
+ * Clean up old files that weren't re-downloaded during force sync
+ * Per ADR-0024: previouslyTrackedPages is Record<string, string> (pageId -> localPath)
+ *
+ * @param directory - Space directory
+ * @param previouslyTrackedPages - Pages tracked before force sync
+ * @param currentPages - Current page mappings after sync
+ * @returns Array of warning messages for failed cleanups
+ */
+export function cleanupOldFiles(
+  directory: string,
+  previouslyTrackedPages: Record<string, string>,
+  currentPages: Record<string, string>,
+): string[] {
+  const warnings: string[] = [];
+  const newTrackedPaths = new Set(Object.values(currentPages));
+
+  for (const [pageId, localPath] of Object.entries(previouslyTrackedPages)) {
+    // Skip if this path was re-used by a new page
+    if (newTrackedPaths.has(localPath)) continue;
+    // Skip if page was re-downloaded (exists in new config)
+    if (currentPages[pageId]) continue;
+
+    try {
+      assertPathWithinDirectory(directory, localPath);
+      const fullPath = join(directory, localPath);
+      if (existsSync(fullPath)) {
+        unlinkSync(fullPath);
+        // Clean up empty parent directories
+        let parentDir = dirname(fullPath);
+        while (parentDir !== directory) {
+          if (existsSync(parentDir) && readdirSync(parentDir).length === 0) {
+            rmSync(parentDir, { recursive: true });
+            parentDir = dirname(parentDir);
+          } else {
+            break;
+          }
+        }
+      }
+    } catch (err) {
+      warnings.push(`Failed to clean up old file ${localPath}: ${err}`);
+    }
+  }
+
+  return warnings;
+}

package/src/lib/sync/folder-path.ts

@@ -0,0 +1,61 @@
+/**
+ * Path and folder utilities for sync operations
+ * Per ADR-0023: Folder push workflow support
+ */
+
+import { resolve } from 'node:path';
+import type { ContentItem, Folder } from '../confluence-client/index.js';
+import { SyncError } from '../errors.js';
+import { RESERVED_FILENAMES } from '../file-scanner.js';
+import { slugify } from '../markdown/index.js';
+
+/**
+ * Validate that a path stays within a base directory (prevents path traversal)
+ * @throws SyncError if path escapes the base directory
+ */
+export 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 page title would generate a reserved filename (CLAUDE.md, AGENTS.md) */
+export const wouldGenerateReservedFilename = (title: string): boolean => RESERVED_FILENAMES.has(`${slugify(title)}.md`);
+
+/**
+ * Generate the local path for a folder based on hierarchy
+ * Per ADR-0023: Folder push workflow support
+ */
+export function generateFolderPath(folder: Folder, contentMap: Map<string, ContentItem>): string {
+  const parentChain: string[] = [];
+  let currentId: string | undefined | null = folder.parentId;
+
+  // Track visited IDs to prevent infinite loops from circular references
+  const visited = new Set<string>();
+
+  // Build parent chain
+  while (currentId && !visited.has(currentId)) {
+    visited.add(currentId);
+    const parent = contentMap.get(currentId);
+    if (parent) {
+      parentChain.unshift(slugify(parent.title));
+      currentId = parent.parentId;
+    } else {
+      break;
+    }
+  }
+
+  // Warn if we detected a circular reference (loop exited because of visited check)
+  if (currentId && visited.has(currentId)) {
+    console.warn(
+      `Warning: Circular reference detected in folder hierarchy for "${folder.title}" (id: ${folder.id}). Path may be truncated.`,
+    );
+  }
+
+  // Add this folder's slug
+  parentChain.push(slugify(folder.title));
+
+  return parentChain.join('/');
+}

package/src/lib/sync/index.ts

@@ -0,0 +1,2 @@
+export { SyncEngine } from './sync-engine.js';
+export type { SyncChange, SyncDiff, SyncOptions, SyncProgressReporter, SyncResult } from './types.js';

package/src/lib/sync/link-resolution-pass.ts

@@ -0,0 +1,139 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildPageLookupMapFromCache, confluenceLinkToRelativePath } from '../markdown/link-converter.js';
+import { buildPageStateFromFiles, type PageStateCache } from '../page-state.js';
+import type { SpaceConfigWithState } from '../space-config.js';
+
+/**
+ * Decode common HTML entities in a string
+ * Handles the most common entities: & < > " '
+ */
+function decodeHtmlEntities(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'");
+}
+
+/**
+ * Result of second pass link resolution
+ */
+export interface LinkResolutionResult {
+  filesUpdated: number;
+  linksResolved: number;
+  warnings: string[];
+}
+
+/**
+ * Extract unresolved Confluence links from markdown content
+ * These are links that couldn't be resolved in the first pass and remain as:
+ * - Raw HTML: <ac:link><ri:page ri:content-title="..."/></ac:link>
+ * - Confluence URLs: [text](https://site.atlassian.net/wiki/...)
+ *
+ * @param content - Markdown content to scan
+ * @returns Array of {title, fullMatch} for each unresolved link
+ */
+function extractUnresolvedLinks(content: string): Array<{ title: string; fullMatch: string; linkText: string }> {
+  const unresolvedLinks: Array<{ title: string; fullMatch: string; linkText: string }> = [];
+
+  // Match <ac:link> elements with ri:page
+  // Pattern: <ac:link>...<ri:page ri:content-title="Title" .../>...</ac:link>
+  const acLinkPattern =
+    /<ac:link>\s*<ri:page[^>]*ri:content-title=["']([^"']+)["'][^>]*\/>\s*(?:<ac:plain-text-link-body><!\[CDATA\[([^\]]*)\]\]><\/ac:plain-text-link-body>)?\s*<\/ac:link>/g;
+
+  let match: RegExpExecArray | null;
+  while ((match = acLinkPattern.exec(content)) !== null) {
+    // Decode HTML entities in title (e.g., "Page &amp; Info" -> "Page & Info")
+    const decodedTitle = decodeHtmlEntities(match[1]);
+    const decodedLinkText = match[2] ? decodeHtmlEntities(match[2]) : decodedTitle;
+
+    unresolvedLinks.push({
+      title: decodedTitle,
+      fullMatch: match[0],
+      linkText: decodedLinkText,
+    });
+  }
+
+  return unresolvedLinks;
+}
+
+/**
+ * Perform second pass link resolution on all markdown files
+ *
+ * After the initial pull, some links couldn't be resolved because their target pages
+ * hadn't been pulled yet. This function rebuilds the page lookup map and resolves
+ * those links.
+ *
+ * Per ADR-0022: Converts Confluence page links to relative markdown paths
+ *
+ * @param directory - Space directory containing markdown files
+ * @param config - Space configuration with page mappings
+ * @returns Result with count of files and links updated
+ */
+export function resolveLinksSecondPass(directory: string, config: SpaceConfigWithState): LinkResolutionResult {
+  const result: LinkResolutionResult = {
+    filesUpdated: 0,
+    linksResolved: 0,
+    warnings: [],
+  };
+
+  // Rebuild page state cache from all files
+  const pageStateBuildResult = buildPageStateFromFiles(directory, config.pages);
+  const pageState: PageStateCache = pageStateBuildResult;
+  result.warnings.push(...pageStateBuildResult.warnings);
+
+  // Rebuild page lookup map with complete set of pages
+  const pageLookupMap = buildPageLookupMapFromCache(pageState, false);
+
+  // Scan all tracked pages for unresolved links
+  for (const [_pageId, localPath] of Object.entries(config.pages)) {
+    const fullPath = join(directory, localPath);
+
+    let content: string;
+    try {
+      content = readFileSync(fullPath, 'utf-8');
+    } catch (error) {
+      result.warnings.push(`Could not read ${localPath}: ${error}`);
+      continue;
+    }
+
+    // Find unresolved links in this file
+    const unresolvedLinks = extractUnresolvedLinks(content);
+    if (unresolvedLinks.length === 0) {
+      continue; // No unresolved links, skip this file
+    }
+
+    // Try to resolve each link
+    let updatedContent = content;
+    let linksResolvedInFile = 0;
+
+    for (const link of unresolvedLinks) {
+      // Try to convert to relative path
+      const relativePath = confluenceLinkToRelativePath(link.title, localPath, pageLookupMap);
+
+      if (relativePath) {
+        // Replace the unresolved link with markdown link
+        const markdownLink = `[${link.linkText}](${relativePath})`;
+        updatedContent = updatedContent.replace(link.fullMatch, markdownLink);
+        linksResolvedInFile++;
+      }
+      // If still can't resolve, leave it as-is (page might be in different space or deleted)
+    }
+
+    // Write updated content if any links were resolved
+    if (linksResolvedInFile > 0) {
+      try {
+        writeFileSync(fullPath, updatedContent, 'utf-8');
+        result.filesUpdated++;
+        result.linksResolved += linksResolvedInFile;
+      } catch (error) {
+        result.warnings.push(`Failed to update ${localPath}: ${error}`);
+      }
+    }
+  }
+
+  return result;
+}