@aaronshaf/confluence-cli 0.1.15

package/src/lib/markdown/reference-updater.ts

@@ -0,0 +1,251 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { parseMarkdown, serializeMarkdown } from './frontmatter.js';
+
+/**
+ * Prefix for relative paths in markdown links
+ */
+const RELATIVE_PREFIX = './';
+
+/**
+ * Directories to exclude when scanning for markdown files
+ */
+const EXCLUDE_DIRS = ['node_modules', '.git', 'dist', 'build', '.cache'];
+
+/**
+ * Result of updating references in a file
+ */
+export interface ReferenceUpdateResult {
+  filePath: string;
+  updatedCount: number;
+}
+
+/**
+ * Statistics for file scanning operations
+ */
+interface ScanStats {
+  failedFiles: number;
+  failedDirs: number;
+}
+
+/**
+ * Find all markdown files in a directory recursively
+ * Excludes node_modules, .git, and other common ignore patterns
+ *
+ * @param directory - Root directory to scan
+ * @param excludeOldFile - Optional file path to exclude
+ * @param excludeNewFile - Optional file path to exclude
+ * @param stats - Optional stats object to track errors
+ * @returns Array of absolute file paths
+ */
+function findMarkdownFiles(
+  directory: string,
+  excludeOldFile?: string,
+  excludeNewFile?: string,
+  stats?: ScanStats,
+): string[] {
+  const results: string[] = [];
+  const excludeDirs = EXCLUDE_DIRS;
+
+  function scan(dir: string): void {
+    try {
+      const entries = readdirSync(dir);
+
+      for (const entry of entries) {
+        const fullPath = join(dir, entry);
+
+        // Skip if this is one of the excluded files
+        if ((excludeOldFile && fullPath === excludeOldFile) || (excludeNewFile && fullPath === excludeNewFile)) {
+          continue;
+        }
+
+        try {
+          const stat = statSync(fullPath);
+
+          if (stat.isDirectory()) {
+            // Skip excluded directories
+            if (!excludeDirs.includes(entry)) {
+              scan(fullPath);
+            }
+          } else if (stat.isFile() && entry.endsWith('.md')) {
+            results.push(fullPath);
+          }
+        } catch (error) {
+          // Track files/dirs we can't access (likely permission issues)
+          if (stats) stats.failedFiles++;
+          if (process.env.DEBUG) {
+            console.error(`Failed to stat ${fullPath}:`, error);
+          }
+        }
+      }
+    } catch (error) {
+      // Track directories we can't read (likely permission issues)
+      if (stats) stats.failedDirs++;
+      if (process.env.DEBUG) {
+        console.error(`Failed to read directory ${dir}:`, error);
+      }
+    }
+  }
+
+  scan(directory);
+  return results;
+}
+
+/**
+ * Update references in a markdown file from oldPath to newPath
+ * Returns the number of references updated, or -1 if processing failed
+ */
+function updateReferencesInFile(
+  filePath: string,
+  oldRelativePath: string,
+  newRelativePath: string,
+  spaceRoot: string,
+): number {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const { frontmatter, content: markdown } = parseMarkdown(content);
+
+    // Calculate what the old path would look like from this file's perspective
+    const fileDir = dirname(filePath);
+    const oldAbsolutePath = join(spaceRoot, oldRelativePath);
+    const newAbsolutePath = join(spaceRoot, newRelativePath);
+
+    // Calculate relative paths from this file to the old and new locations
+    const oldLinkFromFile = relative(fileDir, oldAbsolutePath);
+    const newLinkFromFile = relative(fileDir, newAbsolutePath);
+
+    // Links in markdown may or may not have ./ prefix, so we need to check both forms
+    // Paths starting with . (including ./ and ../) are kept as-is; others get ./ prefix added
+    const oldLinkWithPrefix = oldLinkFromFile.startsWith('.')
+      ? oldLinkFromFile
+      : `${RELATIVE_PREFIX}${oldLinkFromFile}`;
+    const oldLinkWithoutPrefix = oldLinkFromFile.startsWith('./') ? oldLinkFromFile.slice(2) : oldLinkFromFile;
+    const newLinkWithoutPrefix = newLinkFromFile.startsWith('./') ? newLinkFromFile.slice(2) : newLinkFromFile;
+
+    let updatedMarkdown = markdown;
+    let updateCount = 0;
+
+    // Try matching with ./ prefix first
+    const patternWithPrefix = createMarkdownLinkPattern(oldLinkWithPrefix);
+    const matchesWithPrefix = markdown.match(patternWithPrefix);
+    if (matchesWithPrefix) {
+      updateCount += matchesWithPrefix.length;
+      updatedMarkdown = updatedMarkdown.replace(patternWithPrefix, (_match, linkText) => {
+        return `[${linkText}](${oldLinkWithPrefix.startsWith('./') ? `${RELATIVE_PREFIX}${newLinkWithoutPrefix}` : newLinkWithoutPrefix})`;
+      });
+    }
+
+    // Also try matching without ./ prefix (common in markdown)
+    if (!oldLinkFromFile.startsWith('.')) {
+      const patternWithoutPrefix = createMarkdownLinkPattern(oldLinkWithoutPrefix);
+      const matchesWithoutPrefix = updatedMarkdown.match(patternWithoutPrefix);
+      if (matchesWithoutPrefix) {
+        updateCount += matchesWithoutPrefix.length;
+        updatedMarkdown = updatedMarkdown.replace(patternWithoutPrefix, (_match, linkText) => {
+          return `[${linkText}](${newLinkWithoutPrefix})`;
+        });
+      }
+    }
+
+    // Write updated content if any changes were made
+    if (updateCount > 0) {
+      const updatedContent = serializeMarkdown(frontmatter, updatedMarkdown);
+      writeFileSync(filePath, updatedContent, 'utf-8');
+    }
+
+    return updateCount;
+  } catch (error) {
+    // Track files that can't be processed (likely permission issues or malformed frontmatter)
+    if (process.env.DEBUG) {
+      console.error(`Failed to update references in ${filePath}:`, error);
+    }
+    return -1; // Signal processing failure
+  }
+}
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Create a regex pattern to match markdown links with a specific href
+ * Handles complex link text including nested brackets and parentheses
+ *
+ * Pattern explanation:
+ * - \[ - opening bracket
+ * - ([^\[\]]+(?:\[[^\]]*\][^\[\]]*)*) - captures link text including nested brackets:
+ *   - [^\[\]]+ - one or more non-bracket characters
+ *   - (?:\[[^\]]*\][^\[\]]*)* - zero or more groups of [nested] followed by non-brackets
+ * - \] - closing bracket
+ * - \(${escapedLink}\) - the exact link path in parentheses
+ *
+ * This handles cases like [text], [text [nested]], [text (with) parens], etc.
+ *
+ * Known limitations (not currently supported):
+ * - Links with titles: [text](path.md "title")
+ * - Reference-style links: [text][ref] with [ref]: path.md
+ *
+ * @param link - The link href to match (will be escaped)
+ * @returns RegExp pattern that matches markdown links with the given href
+ */
+function createMarkdownLinkPattern(link: string): RegExp {
+  const escapedLink = escapeRegex(link);
+  return new RegExp(`\\[([^\\[\\]]+(?:\\[[^\\]]*\\][^\\[\\]]*)*)\\]\\(${escapedLink}\\)`, 'g');
+}
+
+/**
+ * Update all references to a renamed file across the entire space
+ * Per ADR-0022: When files are renamed, update all markdown links pointing to them
+ *
+ * Performance note: This scans all markdown files in the space directory.
+ * For large repositories, consider implementing an index of links or limiting
+ * the scan to common parent directories.
+ *
+ * @param spaceRoot - Absolute path to space root directory
+ * @param oldPath - Old path relative to space root
+ * @param newPath - New path relative to space root
+ * @returns Array of files that were updated with the number of references changed
+ */
+export function updateReferencesAfterRename(
+  spaceRoot: string,
+  oldPath: string,
+  newPath: string,
+): ReferenceUpdateResult[] {
+  const results: ReferenceUpdateResult[] = [];
+  const scanStats: ScanStats = { failedFiles: 0, failedDirs: 0 };
+  let failedProcessing = 0;
+
+  // Find all markdown files in the space (except the renamed file at both old and new locations)
+  const oldFullPath = join(spaceRoot, oldPath);
+  const newFullPath = join(spaceRoot, newPath);
+  const markdownFiles = findMarkdownFiles(spaceRoot, oldFullPath, newFullPath, scanStats);
+
+  // Update references in each file
+  for (const filePath of markdownFiles) {
+    const updatedCount = updateReferencesInFile(filePath, oldPath, newPath, spaceRoot);
+
+    if (updatedCount > 0) {
+      results.push({
+        filePath: relative(spaceRoot, filePath),
+        updatedCount,
+      });
+    } else if (updatedCount === -1) {
+      failedProcessing++;
+    }
+  }
+
+  // Log summary of errors if any occurred
+  const totalErrors = scanStats.failedFiles + scanStats.failedDirs + failedProcessing;
+  if (totalErrors > 0 && process.env.DEBUG) {
+    console.warn(
+      `Reference update encountered ${totalErrors} errors: ` +
+        `${scanStats.failedFiles} files, ${scanStats.failedDirs} directories (scan), ` +
+        `${failedProcessing} files (processing)`,
+    );
+  }
+
+  return results;
+}

package/src/lib/markdown/slugify.ts

@@ -0,0 +1,32 @@
+/**
+ * Slugify a string for use as a filename
+ * Converts titles to URL-friendly lowercase strings
+ */
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '') // Remove special characters except spaces and hyphens
+    .replace(/\s+/g, '-') // Replace spaces with hyphens
+    .replace(/-+/g, '-') // Collapse multiple hyphens
+    .replace(/^-+|-+$/g, ''); // Trim hyphens from start and end
+}
+
+/**
+ * Generate a unique filename by appending a counter if needed
+ */
+export function generateUniqueFilename(baseName: string, existingNames: Set<string>, extension = '.md'): string {
+  const slug = slugify(baseName);
+  const filename = `${slug}${extension}`;
+
+  if (!existingNames.has(filename)) {
+    return filename;
+  }
+
+  let counter = 2;
+  while (existingNames.has(`${slug}-${counter}${extension}`)) {
+    counter++;
+  }
+
+  return `${slug}-${counter}${extension}`;
+}

package/src/lib/page-state.ts

@@ -0,0 +1,195 @@
+/**
+ * Page state module - builds full page info from frontmatter
+ * Per ADR-0024: Frontmatter is the source of truth for sync state
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { EXCLUDED_DIRS, RESERVED_FILENAMES } from './file-scanner.js';
+import { parseMarkdown, type PageFrontmatter } from './markdown/index.js';
+
+/**
+ * Default version for pages without a version in frontmatter
+ */
+const DEFAULT_VERSION = 1;
+
+/**
+ * Full page information combining mapping and frontmatter data
+ */
+export interface FullPageInfo {
+  pageId: string;
+  localPath: string;
+  title: string;
+  version: number;
+  updatedAt?: string;
+  syncedAt?: string;
+}
+
+/**
+ * Cache of all page information built from files
+ */
+export interface PageStateCache {
+  pages: Map<string, FullPageInfo>;
+  pathToPageId: Map<string, string>;
+}
+
+/**
+ * Result of building page state, including any warnings
+ */
+export interface PageStateBuildResult extends PageStateCache {
+  warnings: string[];
+}
+
+/**
+ * Build full page state by scanning markdown files and reading frontmatter
+ *
+ * @param directory - Space root directory
+ * @param pageMappings - Page mappings from .confluence.json (pageId -> localPath)
+ * @returns PageStateBuildResult with all page info and any warnings
+ */
+export function buildPageStateFromFiles(directory: string, pageMappings: Record<string, string>): PageStateBuildResult {
+  const pages = new Map<string, FullPageInfo>();
+  const pathToPageId = new Map<string, string>();
+  const warnings: string[] = [];
+
+  // Read frontmatter from each mapped file
+  // Only add to pathToPageId if page is successfully parsed
+  const resolvedDirectory = resolve(directory);
+
+  for (const [pageId, localPath] of Object.entries(pageMappings)) {
+    const fullPath = resolve(directory, localPath);
+
+    // Path traversal protection: ensure resolved path is within directory
+    if (!fullPath.startsWith(resolvedDirectory)) {
+      warnings.push(`Skipping path outside directory for page ${pageId}: ${localPath}`);
+      continue;
+    }
+
+    if (!existsSync(fullPath)) {
+      // File doesn't exist - skip (might have been deleted)
+      warnings.push(`File not found for page ${pageId}: ${localPath}`);
+      continue;
+    }
+
+    try {
+      const content = readFileSync(fullPath, 'utf-8');
+      const { frontmatter } = parseMarkdown(content);
+
+      // Warn if frontmatter page_id doesn't match mapping key
+      if (frontmatter.page_id && frontmatter.page_id !== pageId) {
+        warnings.push(
+          `Page ID mismatch for ${localPath}: mapping has "${pageId}", frontmatter has "${frontmatter.page_id}"`,
+        );
+      }
+
+      const pageInfo: FullPageInfo = {
+        pageId,
+        localPath,
+        title: frontmatter.title || '',
+        version: frontmatter.version || DEFAULT_VERSION,
+        updatedAt: frontmatter.updated_at,
+        syncedAt: frontmatter.synced_at,
+      };
+
+      pages.set(pageId, pageInfo);
+      pathToPageId.set(localPath, pageId);
+    } catch (error) {
+      // Failed to read/parse file - skip but warn
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      warnings.push(`Failed to parse frontmatter for ${localPath}: ${errorMsg}`);
+    }
+  }
+
+  return { pages, pathToPageId, warnings };
+}
+
+/**
+ * Get page info for a single file by reading its frontmatter
+ *
+ * @param directory - Space root directory
+ * @param localPath - Relative path to the file
+ * @returns FullPageInfo or null if file doesn't exist or has no page_id
+ */
+export function getPageInfoByPath(directory: string, localPath: string): FullPageInfo | null {
+  const fullPath = join(directory, localPath);
+
+  if (!existsSync(fullPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(fullPath, 'utf-8');
+    const { frontmatter } = parseMarkdown(content);
+
+    // Must have page_id to be a tracked page
+    if (!frontmatter.page_id) {
+      return null;
+    }
+
+    return {
+      pageId: frontmatter.page_id,
+      localPath,
+      title: frontmatter.title || '',
+      version: frontmatter.version || DEFAULT_VERSION,
+      updatedAt: frontmatter.updated_at,
+      syncedAt: frontmatter.synced_at,
+    };
+  } catch {
+    // Return null for any parse errors (malformed YAML, encoding issues, etc.)
+    // This is intentional - callers treat unreadable files the same as files without page_id.
+    // Use buildPageStateFromFiles() instead if you need detailed error reporting.
+    return null;
+  }
+}
+
+/**
+ * Scan directory for all markdown files and build page state
+ * This is used when we need full state but don't have mappings (e.g., initial scan)
+ *
+ * @param directory - Space root directory
+ * @returns PageStateCache with all discovered pages
+ */
+export function scanDirectoryForPages(directory: string): PageStateCache {
+  const pages = new Map<string, FullPageInfo>();
+  const pathToPageId = new Map<string, string>();
+
+  function scanDir(dir: string): void {
+    const entries = readdirSync(dir);
+
+    for (const entry of entries) {
+      // Skip hidden files/directories
+      if (entry.startsWith('.')) {
+        continue;
+      }
+
+      // Skip excluded directories
+      if (EXCLUDED_DIRS.has(entry)) {
+        continue;
+      }
+
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+
+      if (stat.isDirectory()) {
+        scanDir(fullPath);
+      } else if (entry.endsWith('.md')) {
+        // Skip reserved filenames (used by coding agents)
+        if (RESERVED_FILENAMES.has(entry.toLowerCase())) {
+          continue;
+        }
+
+        const localPath = relative(directory, fullPath);
+        const pageInfo = getPageInfoByPath(directory, localPath);
+
+        if (pageInfo) {
+          pages.set(pageInfo.pageId, pageInfo);
+          pathToPageId.set(localPath, pageInfo.pageId);
+        }
+      }
+    }
+  }
+
+  scanDir(directory);
+
+  return { pages, pathToPageId };
+}

package/src/lib/resolve-page-target.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve a page target argument to a page ID.
+ *
+ * Accepts:
+ * - A path ending in .md or containing /: reads frontmatter to extract page_id
+ * - A numeric string: used directly as the page ID
+ * - Otherwise: throws with a usage hint
+ */
+
+import { readFileSync } from 'node:fs';
+import { extractPageId } from './markdown/frontmatter.js';
+
+export function resolvePageTarget(target: string): string {
+  if (target.endsWith('.md') || target.includes('/')) {
+    let content: string;
+    try {
+      content = readFileSync(target, 'utf-8');
+    } catch {
+      throw new Error(`File not found: ${target}`);
+    }
+    const pageId = extractPageId(content);
+    if (!pageId) {
+      throw new Error(`No page_id found in frontmatter of ${target}`);
+    }
+    return pageId;
+  }
+
+  if (/^\d+$/.test(target)) {
+    return target;
+  }
+
+  throw new Error(`Invalid page target: "${target}". Provide a page ID (numeric) or a path to a .md file.`);
+}