@aaronshaf/confluence-cli 0.1.15

package/src/lib/confluence-client/search-operations.ts

@@ -0,0 +1,60 @@
+import { Effect, Schema, pipe } from 'effect';
+import { ApiError, AuthError, NetworkError, RateLimitError } from '../errors.js';
+import { SearchResponseSchema, type SearchResponse } from './types.js';
+
+/** Retry schedule shared with client — exponential backoff capped at ~160s */
+import { Schedule } from 'effect';
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const rateLimitRetrySchedule = Schedule.exponential(BASE_DELAY_MS).pipe(
+  Schedule.jittered,
+  Schedule.whileInput((error: unknown) => error instanceof RateLimitError),
+  Schedule.upTo(MAX_RETRIES * BASE_DELAY_MS * 32),
+);
+
+/**
+ * Search pages using CQL (Effect version)
+ * Uses GET /wiki/rest/api/search (v1 API - not prefixed with /api/v2)
+ */
+export function searchEffect(
+  baseUrl: string,
+  authHeader: string,
+  cql: string,
+  limit = 10,
+): Effect.Effect<SearchResponse, ApiError | AuthError | NetworkError | RateLimitError> {
+  const url = `${baseUrl}/wiki/rest/api/search?cql=${encodeURIComponent(cql)}&limit=${limit}`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        headers: { Authorization: authHeader, Accept: 'application/json' },
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+      if (response.status === 401) throw new AuthError('Invalid credentials', 401);
+      if (response.status === 403) throw new AuthError('Access denied', 403);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new ApiError(`Search failed: ${response.status} ${errorText}`, response.status);
+      }
+      return response.json();
+    },
+    catch: (error) => {
+      if (error instanceof RateLimitError || error instanceof AuthError || error instanceof ApiError) return error;
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(
+    makeRequest,
+    Effect.flatMap((data) =>
+      Schema.decodeUnknown(SearchResponseSchema)(data).pipe(
+        Effect.mapError((e) => new ApiError(`Invalid response: ${e}`, 500)),
+      ),
+    ),
+    Effect.retry(rateLimitRetrySchedule),
+  );
+}

package/src/lib/confluence-client/types.ts

@@ -0,0 +1,329 @@
+import { Schema } from 'effect';
+
+/**
+ * Confluence API v2 type definitions
+ * These schemas are used for both validation and type inference
+ */
+
+/**
+ * User information
+ */
+export const UserSchema = Schema.Struct({
+  accountId: Schema.String,
+  displayName: Schema.optional(Schema.String),
+  email: Schema.optional(Schema.String),
+});
+export type User = Schema.Schema.Type<typeof UserSchema>;
+
+/**
+ * Space information from Confluence API v2
+ */
+export const SpaceSchema = Schema.Struct({
+  id: Schema.String,
+  key: Schema.String,
+  name: Schema.String,
+  type: Schema.optional(Schema.String),
+  status: Schema.optional(Schema.String),
+  homepageId: Schema.optional(Schema.String),
+  description: Schema.optional(
+    Schema.NullOr(
+      Schema.Struct({
+        plain: Schema.optional(
+          Schema.Struct({
+            value: Schema.String,
+          }),
+        ),
+      }),
+    ),
+  ),
+  _links: Schema.optional(
+    Schema.Struct({
+      webui: Schema.optional(Schema.String),
+    }),
+  ),
+});
+export type Space = Schema.Schema.Type<typeof SpaceSchema>;
+
+/**
+ * List of spaces response
+ */
+export const SpacesResponseSchema = Schema.Struct({
+  results: Schema.Array(SpaceSchema),
+  _links: Schema.optional(
+    Schema.Struct({
+      next: Schema.optional(Schema.String),
+    }),
+  ),
+});
+export type SpacesResponse = Schema.Schema.Type<typeof SpacesResponseSchema>;
+
+/**
+ * Page version information
+ */
+export const VersionSchema = Schema.Struct({
+  number: Schema.Number,
+  createdAt: Schema.optional(Schema.String),
+  authorId: Schema.optional(Schema.String),
+});
+export type Version = Schema.Schema.Type<typeof VersionSchema>;
+
+/**
+ * Page body content
+ */
+export const BodySchema = Schema.Struct({
+  storage: Schema.optional(
+    Schema.Struct({
+      value: Schema.String,
+      representation: Schema.optional(Schema.String),
+    }),
+  ),
+});
+export type Body = Schema.Schema.Type<typeof BodySchema>;
+
+/**
+ * Label information
+ */
+export const LabelSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  prefix: Schema.optional(Schema.String),
+});
+export type Label = Schema.Schema.Type<typeof LabelSchema>;
+
+/**
+ * Page information from Confluence API v2
+ */
+export const PageSchema = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  spaceId: Schema.String,
+  status: Schema.optional(Schema.String),
+  parentId: Schema.optional(Schema.NullOr(Schema.String)),
+  parentType: Schema.optional(Schema.NullOr(Schema.String)),
+  authorId: Schema.optional(Schema.String),
+  ownerId: Schema.optional(Schema.String),
+  createdAt: Schema.optional(Schema.String),
+  version: Schema.optional(VersionSchema),
+  body: Schema.optional(BodySchema),
+  _links: Schema.optional(
+    Schema.Struct({
+      webui: Schema.optional(Schema.String),
+      editui: Schema.optional(Schema.String),
+      tinyui: Schema.optional(Schema.String),
+    }),
+  ),
+});
+export type Page = Schema.Schema.Type<typeof PageSchema>;
+
+/**
+ * List of pages response
+ */
+export const PagesResponseSchema = Schema.Struct({
+  results: Schema.Array(PageSchema),
+  _links: Schema.optional(
+    Schema.Struct({
+      next: Schema.optional(Schema.String),
+    }),
+  ),
+});
+export type PagesResponse = Schema.Schema.Type<typeof PagesResponseSchema>;
+
+/**
+ * Labels response
+ */
+export const LabelsResponseSchema = Schema.Struct({
+  results: Schema.Array(LabelSchema),
+  _links: Schema.optional(
+    Schema.Struct({
+      next: Schema.optional(Schema.String),
+    }),
+  ),
+});
+export type LabelsResponse = Schema.Schema.Type<typeof LabelsResponseSchema>;
+
+/**
+ * Folder information from Confluence API v2
+ */
+export const FolderSchema = Schema.Struct({
+  id: Schema.String,
+  type: Schema.Literal('folder'),
+  title: Schema.String,
+  parentId: Schema.optional(Schema.NullOr(Schema.String)),
+  parentType: Schema.optional(Schema.NullOr(Schema.String)),
+  authorId: Schema.optional(Schema.String),
+  ownerId: Schema.optional(Schema.String),
+  createdAt: Schema.optional(Schema.Union(Schema.String, Schema.Number)),
+  status: Schema.optional(Schema.String),
+  version: Schema.optional(VersionSchema),
+});
+export type Folder = Schema.Schema.Type<typeof FolderSchema>;
+
+/**
+ * Content item - either a page or folder
+ */
+export type ContentItem = Page | Folder;
+
+/**
+ * Check if content item is a folder
+ */
+export function isFolder(item: ContentItem): item is Folder {
+  return 'type' in item && item.type === 'folder';
+}
+
+/**
+ * Error response for version conflicts (409)
+ */
+export interface VersionConflictResponse {
+  version?: {
+    number?: number;
+  };
+}
+
+/**
+ * Request body for updating a page
+ */
+export const UpdatePageRequestSchema = Schema.Struct({
+  id: Schema.String,
+  status: Schema.String,
+  title: Schema.String,
+  body: Schema.Struct({
+    representation: Schema.Literal('storage'),
+    value: Schema.String,
+  }),
+  version: Schema.Struct({
+    number: Schema.Number,
+    message: Schema.optional(Schema.String),
+  }),
+});
+export type UpdatePageRequest = Schema.Schema.Type<typeof UpdatePageRequestSchema>;
+
+/**
+ * Request body for creating a new page
+ */
+export const CreatePageRequestSchema = Schema.Struct({
+  spaceId: Schema.String,
+  status: Schema.String,
+  title: Schema.String,
+  parentId: Schema.optional(Schema.String),
+  body: Schema.Struct({
+    representation: Schema.Literal('storage'),
+    value: Schema.String,
+  }),
+});
+export type CreatePageRequest = Schema.Schema.Type<typeof CreatePageRequestSchema>;
+
+/**
+ * Request body for creating a new folder
+ */
+export const CreateFolderRequestSchema = Schema.Struct({
+  spaceId: Schema.String,
+  title: Schema.String,
+  parentId: Schema.optional(Schema.String),
+});
+export type CreateFolderRequest = Schema.Schema.Type<typeof CreateFolderRequestSchema>;
+
+/**
+ * Comment information from Confluence API v2
+ */
+export const CommentSchema = Schema.Struct({
+  id: Schema.String,
+  status: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  body: Schema.optional(BodySchema),
+  version: Schema.optional(VersionSchema),
+  authorId: Schema.optional(Schema.String),
+  createdAt: Schema.optional(Schema.String),
+});
+export type Comment = Schema.Schema.Type<typeof CommentSchema>;
+
+export const CommentsResponseSchema = Schema.Struct({
+  results: Schema.Array(CommentSchema),
+  _links: Schema.optional(
+    Schema.Struct({
+      next: Schema.optional(Schema.String),
+    }),
+  ),
+});
+export type CommentsResponse = Schema.Schema.Type<typeof CommentsResponseSchema>;
+
+/**
+ * Attachment information from Confluence API v2
+ */
+export const AttachmentSchema = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  status: Schema.optional(Schema.String),
+  mediaType: Schema.optional(Schema.String),
+  fileSize: Schema.optional(Schema.Number),
+  webuiLink: Schema.optional(Schema.String),
+  downloadLink: Schema.optional(Schema.String),
+  version: Schema.optional(VersionSchema),
+});
+export type Attachment = Schema.Schema.Type<typeof AttachmentSchema>;
+
+export const AttachmentsResponseSchema = Schema.Struct({
+  results: Schema.Array(AttachmentSchema),
+  _links: Schema.optional(
+    Schema.Struct({
+      next: Schema.optional(Schema.String),
+    }),
+  ),
+});
+export type AttachmentsResponse = Schema.Schema.Type<typeof AttachmentsResponseSchema>;
+
+/**
+ * Search result item from CQL search
+ */
+export const SearchResultItemSchema = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  type: Schema.optional(Schema.String),
+  status: Schema.optional(Schema.String),
+  space: Schema.optional(
+    Schema.Struct({
+      id: Schema.optional(Schema.String),
+      key: Schema.optional(Schema.String),
+      name: Schema.optional(Schema.String),
+    }),
+  ),
+  url: Schema.optional(Schema.String),
+  excerpt: Schema.optional(Schema.String),
+  lastModified: Schema.optional(Schema.String),
+  content: Schema.optional(
+    Schema.Struct({
+      id: Schema.optional(Schema.String),
+      type: Schema.optional(Schema.String),
+      title: Schema.optional(Schema.String),
+      _links: Schema.optional(
+        Schema.Struct({
+          webui: Schema.optional(Schema.String),
+        }),
+      ),
+    }),
+  ),
+});
+export type SearchResultItem = Schema.Schema.Type<typeof SearchResultItemSchema>;
+
+export const SearchResponseSchema = Schema.Struct({
+  results: Schema.Array(SearchResultItemSchema),
+  totalSize: Schema.optional(Schema.Number),
+  start: Schema.optional(Schema.Number),
+  limit: Schema.optional(Schema.Number),
+});
+export type SearchResponse = Schema.Schema.Type<typeof SearchResponseSchema>;
+
+/**
+ * Page with children tree structure (for building hierarchy)
+ */
+export interface PageTreeNode {
+  page: Page;
+  children: PageTreeNode[];
+}
+
+/**
+ * Content tree node (page or folder with children)
+ */
+export interface ContentTreeNode {
+  item: ContentItem;
+  children: ContentTreeNode[];
+}

package/src/lib/confluence-client/user-operations.ts

@@ -0,0 +1,58 @@
+import { Effect, Schema, pipe } from 'effect';
+import { Schedule } from 'effect';
+import { ApiError, AuthError, NetworkError, RateLimitError } from '../errors.js';
+import { UserSchema, type User } from './types.js';
+
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const rateLimitRetrySchedule = Schedule.exponential(BASE_DELAY_MS).pipe(
+  Schedule.jittered,
+  Schedule.whileInput((error: unknown) => error instanceof RateLimitError),
+  Schedule.upTo(MAX_RETRIES * BASE_DELAY_MS * 32),
+);
+
+/**
+ * Get user information by account ID (Effect version)
+ * Uses v1 API as v2 does not have a user endpoint
+ */
+export function getUserEffect(
+  baseUrl: string,
+  authHeader: string,
+  accountId: string,
+): Effect.Effect<User, ApiError | AuthError | NetworkError | RateLimitError> {
+  const url = `${baseUrl}/wiki/rest/api/user?accountId=${encodeURIComponent(accountId)}`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        headers: { Authorization: authHeader, Accept: 'application/json' },
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+      if (response.status === 401) throw new AuthError('Invalid credentials', 401);
+      if (response.status === 403) throw new AuthError('Access denied', 403);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new ApiError(`API request failed: ${response.status} ${errorText}`, response.status);
+      }
+      return response.json();
+    },
+    catch: (error) => {
+      if (error instanceof RateLimitError || error instanceof AuthError || error instanceof ApiError) return error;
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(
+    makeRequest,
+    Effect.flatMap((data) =>
+      Schema.decodeUnknown(UserSchema)(data).pipe(
+        Effect.mapError((e) => new ApiError(`Invalid user response: ${e}`, 500)),
+      ),
+    ),
+    Effect.retry(rateLimitRetrySchedule),
+  );
+}

package/src/lib/dependency-sorter.ts

@@ -0,0 +1,233 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, normalize, relative } from 'node:path';
+import type { PushCandidate } from './file-scanner.js';
+
+/**
+ * Extract all local markdown links from content.
+ *
+ * Matches markdown links like [text](path.md) but excludes:
+ * - http:// and https:// URLs
+ * - Links to non-.md files
+ *
+ * @param content - Markdown content to extract links from
+ * @returns Array of relative paths (as written in the markdown)
+ */
+export function extractLocalLinks(content: string): string[] {
+  // Match markdown links: [text](path.md) or [text](path.md#anchor)
+  // The text part can contain nested brackets (e.g., [text [nested]](link.md))
+  // Pattern explanation:
+  // \[([^\[\]]+(?:\[[^\]]*\][^\[\]]*)*)\] - Match [text] allowing nested brackets
+  // \(([^)#]+\.md)(?:#[^)]*)?\) - Match (path.md) or (path.md#anchor)
+  const linkPattern = /\[([^[\]]+(?:\[[^\]]*\][^[\]]*)*)\]\(([^)#]+\.md)(?:#[^)]*)?\)/g;
+
+  const links: string[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = linkPattern.exec(content)) !== null) {
+    const linkPath = match[2];
+
+    // Skip external URLs
+    if (linkPath.startsWith('http://') || linkPath.startsWith('https://')) {
+      continue;
+    }
+
+    // Remove any anchor fragments (e.g., file.md#section -> file.md)
+    const pathWithoutAnchor = linkPath.split('#')[0];
+
+    links.push(pathWithoutAnchor);
+  }
+
+  return links;
+}
+
+/**
+ * Resolve a link path relative to the source file's directory.
+ *
+ * @param linkPath - The link path as written in markdown
+ * @param sourceFilePath - The path of the file containing the link (relative to directory)
+ * @returns Normalized path relative to directory root
+ */
+function resolveLinkPath(linkPath: string, sourceFilePath: string): string {
+  // Get the directory containing the source file
+  const sourceDir = dirname(sourceFilePath);
+
+  // Join and normalize the path
+  const resolvedPath = normalize(join(sourceDir, linkPath));
+
+  return resolvedPath;
+}
+
+/**
+ * Sort push candidates by dependencies so linked-to pages are pushed first.
+ *
+ * Uses Kahn's algorithm for topological sorting with cycle detection.
+ * If cycles are detected, the files involved in cycles are still included
+ * in the output (in their original relative order).
+ *
+ * @param candidates - Array of push candidates to sort
+ * @param directory - Root directory for resolving file paths
+ * @returns Object containing:
+ *   - sorted: Candidates sorted so dependencies come first
+ *   - cycles: Array of detected cycles (each cycle is array of paths)
+ */
+export function sortByDependencies(
+  candidates: PushCandidate[],
+  directory: string,
+): { sorted: PushCandidate[]; cycles: string[][] } {
+  // Build a set of candidate paths for quick lookup
+  const candidatePaths = new Set(candidates.map((c) => c.path));
+
+  // Build dependency graph: file -> files it depends on (links to)
+  // dependsOn[A] = [B, C] means A links to B and C
+  const dependsOn = new Map<string, Set<string>>();
+
+  // Build reverse graph: file -> files that depend on it (link to it)
+  // dependedBy[B] = [A] means A links to B
+  const dependedBy = new Map<string, Set<string>>();
+
+  // Initialize maps for all candidates
+  for (const candidate of candidates) {
+    dependsOn.set(candidate.path, new Set());
+    dependedBy.set(candidate.path, new Set());
+  }
+
+  // Read each candidate's content and extract dependencies
+  for (const candidate of candidates) {
+    const fullPath = join(directory, candidate.path);
+
+    let content: string;
+    try {
+      content = readFileSync(fullPath, 'utf-8');
+    } catch {
+      // If we can't read the file, skip dependency analysis for it
+      continue;
+    }
+
+    const links = extractLocalLinks(content);
+
+    for (const link of links) {
+      // Resolve the link relative to the candidate's location
+      const resolvedLink = resolveLinkPath(link, candidate.path);
+
+      // Only track dependencies that are also candidates
+      if (candidatePaths.has(resolvedLink)) {
+        // candidate.path depends on resolvedLink
+        dependsOn.get(candidate.path)?.add(resolvedLink);
+        dependedBy.get(resolvedLink)?.add(candidate.path);
+      }
+    }
+  }
+
+  // Kahn's algorithm for topological sort
+  // Start with nodes that have no dependencies
+  const sorted: PushCandidate[] = [];
+  const candidateMap = new Map(candidates.map((c) => [c.path, c]));
+
+  // Queue of nodes with no remaining dependencies
+  const queue: string[] = [];
+
+  // Count of unprocessed dependencies for each node
+  const inDegree = new Map<string, number>();
+
+  // Initialize in-degrees
+  for (const candidate of candidates) {
+    const deps = dependsOn.get(candidate.path);
+    const depCount = deps?.size ?? 0;
+    inDegree.set(candidate.path, depCount);
+
+    if (depCount === 0) {
+      queue.push(candidate.path);
+    }
+  }
+
+  // Process queue
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) break;
+
+    const candidate = candidateMap.get(current);
+    if (candidate) {
+      sorted.push(candidate);
+    }
+
+    // For each file that depends on current, decrement its in-degree
+    const dependents = dependedBy.get(current);
+    if (dependents) {
+      for (const dependent of dependents) {
+        const currentDegree = inDegree.get(dependent) ?? 0;
+        const newDegree = currentDegree - 1;
+        inDegree.set(dependent, newDegree);
+
+        if (newDegree === 0) {
+          queue.push(dependent);
+        }
+      }
+    }
+  }
+
+  // Detect cycles: any nodes not in sorted output are part of cycles
+  const cycles: string[][] = [];
+  const sortedPaths = new Set(sorted.map((c) => c.path));
+  const remainingPaths = candidates.filter((c) => !sortedPaths.has(c.path)).map((c) => c.path);
+
+  if (remainingPaths.length > 0) {
+    // Find cycles using DFS
+    const visited = new Set<string>();
+    const inStack = new Set<string>();
+
+    function findCycles(node: string, path: string[]): void {
+      if (inStack.has(node)) {
+        // Found a cycle - extract it from path
+        const cycleStart = path.indexOf(node);
+        const cycle = path.slice(cycleStart);
+        cycles.push(cycle);
+        return;
+      }
+
+      if (visited.has(node)) {
+        return;
+      }
+
+      visited.add(node);
+      inStack.add(node);
+      path.push(node);
+
+      const deps = dependsOn.get(node);
+      if (deps) {
+        for (const dep of deps) {
+          if (remainingPaths.includes(dep)) {
+            findCycles(dep, [...path]);
+          }
+        }
+      }
+
+      inStack.delete(node);
+    }
+
+    for (const start of remainingPaths) {
+      if (!visited.has(start)) {
+        findCycles(start, []);
+      }
+    }
+
+    // Add remaining candidates to sorted output, prioritizing new pages first
+    // so they get created and receive page_ids before modified pages are pushed.
+    // This allows modified pages to resolve links to the newly created pages.
+    const remainingCandidates = remainingPaths
+      .map((path) => candidateMap.get(path))
+      .filter((c): c is PushCandidate => c !== undefined)
+      .sort((a, b) => {
+        // New pages first, then modified
+        if (a.type === 'new' && b.type !== 'new') return -1;
+        if (a.type !== 'new' && b.type === 'new') return 1;
+        // Within same type, preserve original order (alphabetical)
+        return remainingPaths.indexOf(a.path) - remainingPaths.indexOf(b.path);
+      });
+
+    for (const candidate of remainingCandidates) {
+      sorted.push(candidate);
+    }
+  }
+
+  return { sorted, cycles };
+}