@repo-toolkit/confluence 0.9.0 → 0.11.0

package/index.d.ts

@@ -1,5 +1,22 @@
 import { FlagSpec } from '@repo-toolkit/publish-package';
-export { FlagSpec, isPlainObject, parseFlags, resolveCliOptions } from '@repo-toolkit/publish-package';
+
+interface MermaidBlock {
+    id: string;
+    source: string;
+}
+interface MarkdownConvertResult {
+    html: string;
+    mermaidBlocks: MermaidBlock[];
+}
+interface MarkdownConvertOptions {
+    /** Render ```html fenced blocks as inline HTML via the Confluence `html` macro instead of a code box. Default: false. */
+    renderHtmlBlocks?: boolean;
+}
+declare function isAllowedUrl(url: string): boolean;
+declare function markdownToStorage(markdown: string, options?: MarkdownConvertOptions): MarkdownConvertResult;
+declare function isRemoteUrl(src: string): boolean;
+declare function escapeXmlAttribute(text: string): string;
+declare function escapeAttachmentFilename(filename: string): string;
 
 interface ConfluenceClientOptions {
     baseUrl: string;
@@ -7,6 +24,41 @@ interface ConfluenceClientOptions {
     apiToken: string;
     fetch?: typeof fetch;
     userAgent?: string;
+    /** Timeout (ms) applied to every HTTP request. Default 30000. */
+    requestTimeoutMs?: number;
+    /** Retries for 429 / 5xx on safe methods (GET/HEAD/OPTIONS). Default 3; never applied to writes. */
+    maxRetries?: number;
+    /** Per-file maximum attachment upload size in bytes. Default 50 MB. */
+    maxUploadBytes?: number;
+}
+/**
+ * Narrow gateway covering only the attachment-list and binary upload methods the
+ * image/mermaid rewriters need. `ConfluenceClient` implements this interface;
+ * tests inject fakes that implement just these three methods.
+ */
+interface AttachmentGateway {
+    getAttachments(pageId: string): Promise<Attachment[]>;
+    uploadAttachment(pageId: string, filePath: string, comment?: string, filename?: string): Promise<Attachment>;
+    updateAttachmentData(pageId: string, attachmentId: string, filePath: string, comment?: string, filename?: string): Promise<Attachment>;
+}
+/**
+ * Narrow remote-mutation boundary consumed by the sync orchestrator and the
+ * image/mermaid rewriters. `ConfluenceClient` implements this interface; tests
+ * may inject any object whose method shapes match (typed fakes — no `unknown`
+ * cast required). Replacing the client also replaces the credentials/baseUrl
+ * requirement: the sync orchestrator relies solely on this gateway for remote
+ * work, so callers that supply their own gateway never need dummy credentials.
+ *
+ * The interface is the supported contract for custom clients: every method
+ * listed here is one the sync actually calls, and the signatures match the v1
+ * multipart + v2 JSON contract the bundled `ConfluenceClient` honors.
+ */
+interface ConfluenceGateway extends AttachmentGateway {
+    getSpaceIdByKey(spaceKey: string): Promise<string>;
+    getPagesByTitle(spaceId: string, title: string): Promise<Page[]>;
+    getPage(pageId: string): Promise<Page>;
+    createPage(input: CreatePageInput): Promise<Page>;
+    updatePage(input: UpdatePageInput): Promise<Page>;
 }
 interface PageBody {
     representation: 'storage' | 'atlas_doc' | 'wiki' | 'view' | 'export_view';
@@ -78,22 +130,27 @@ declare class ConfluenceApiError extends Error {
     readonly responseBody: string;
     constructor(message: string, status: number, endpoint: string, responseBody: string);
 }
-declare class ConfluenceClient {
+declare class ConfluenceClient implements ConfluenceGateway {
     private readonly baseUrl;
+    private readonly baseUrlOrigin;
     private readonly authHeader;
     private readonly fetchFn;
     private readonly userAgent;
+    private readonly requestTimeoutMs;
+    private readonly maxRetries;
+    private readonly maxUploadBytes;
     constructor(options: ConfluenceClientOptions);
     getSpaceIdByKey(spaceKey: string): Promise<string>;
-    getPageByTitle(spaceId: string, title: string): Promise<Page | undefined>;
+    getPagesByTitle(spaceId: string, title: string): Promise<Page[]>;
     getPage(pageId: string): Promise<Page>;
     createPage(input: CreatePageInput): Promise<Page>;
     updatePage(input: UpdatePageInput): Promise<Page>;
     getAttachments(pageId: string): Promise<Attachment[]>;
-    uploadAttachment(pageId: string, filePath: string, comment?: string): Promise<Attachment>;
-    updateAttachmentData(pageId: string, attachmentId: string, filePath: string, comment?: string): Promise<Attachment>;
+    uploadAttachment(pageId: string, filePath: string, comment?: string, filename?: string): Promise<Attachment>;
+    updateAttachmentData(pageId: string, attachmentId: string, filePath: string, comment?: string, filename?: string): Promise<Attachment>;
     private sendAttachmentMultipart;
     private requestJson;
+    private makeTimeoutSignal;
     private v2Url;
     private v1Url;
 }
@@ -111,26 +168,6 @@ declare function readDocTree(root: string, depth?: number): Promise<DocTree>;
 declare function isMarkdownName(name: string): boolean;
 declare function titleFromSegment(segment: string): string;
 
-interface MermaidBlock {
-    id: string;
-    source: string;
-}
-interface MarkdownConvertResult {
-    html: string;
-    mermaidBlocks: MermaidBlock[];
-}
-interface MarkdownConvertOptions {
-    /** Render ```html fenced blocks as inline HTML via the Confluence `html` macro instead of a code box. Default: false. */
-    renderHtmlBlocks?: boolean;
-}
-declare function markdownToStorage(markdown: string, options?: MarkdownConvertOptions): MarkdownConvertResult;
-declare function renderHtmlBlock(code: string): string;
-declare function renderInline(text: string): string;
-declare const LOCAL_IMAGE_PLACEHOLDER_RE: RegExp;
-declare function isRemoteUrl(src: string): boolean;
-declare function escapeXmlAttribute(text: string): string;
-declare function escapeAttachmentFilename(filename: string): string;
-
 interface RewriteResult {
     html: string;
     uploaded: ReadonlyArray<{
@@ -138,21 +175,112 @@ interface RewriteResult {
         attachment: Attachment;
     }>;
 }
+/**
+ * Equivalent of {@link RewriteResult} for a preflight pass: it produces the
+ * final HTML that would be emitted if uploads were allowed, plus the set of
+ * local sources that would require either a fresh upload or a content update.
+ *
+ * A preflight is `predictable` when every placeholder resolves to an existing
+ * attachment whose stored content hash matches the local source hash; in that
+ * state no upload is required and the produced HTML is byte-identical to a full
+ * rewrite.
+ */
+interface PreflightResult {
+    html: string;
+    /** Sources that would upload or update their attachment on a real rewrite. */
+    pending: ReadonlyArray<{
+        src: string;
+        filename: string;
+        hash: string;
+    }>;
+    /** Sources that already have a matching-content attachment and would be reused. */
+    reused: ReadonlyArray<{
+        src: string;
+        attachment: Attachment;
+    }>;
+}
 interface RewriteOptions {
     /** Directory used to resolve relative image src values. The markdown file's own dir. */
     markdownDir: string;
+    /** Documentation root used to confine local file reads. */
+    allowedRoot: string;
+    /** Maximum size accepted for an individual attachment source. */
+    maxAttachmentBytes?: number;
+    /** Maximum total size accepted across all uploaded sources in one document. */
+    maxTotalAttachmentBytes?: number;
+}
+/**
+ * Resolved view of a local image source after the same root-confined,
+ * regular-file, and size validation that {@link rewriteImagesToAttachments}
+ * applies at upload time. Used by the CFARC-03 local preflight so the dry
+ * validation pass before any API mutation never relaxes the trust boundary.
+ */
+interface ValidatedAttachmentSource {
+    /** Original `src` as it appeared in the markdown. */
+    src: string;
+    /** Real, root-confined absolute path on disk. */
+    abs: string;
+    /** Resolved content-addressed attachment filename (`<stem>-<hash16>.<ext>`). */
+    filename: string;
 }
-declare function rewriteImagesToAttachments(html: string, pageId: string, client: ConfluenceClient, options: RewriteOptions): Promise<RewriteResult>;
+/**
+ * Validate every local image placeholder in `html` against the same physical
+ * resolution, root confinement, regular-file, and size checks performed at
+ * upload time, returning the content-addressed filename each source would get.
+ * Throws on the first validation failure with the same message the upload path
+ * would produce — so a pre-mutation pass cannot relax the trust boundary.
+ *
+ * Performs no client work and no upload; reads file metadata and short-hashes
+ * file contents only.
+ */
+declare function validateAttachmentSources(html: string, options: RewriteOptions): ValidatedAttachmentSource[];
+declare function rewriteImagesToAttachments(html: string, pageId: string, client: AttachmentGateway, options: RewriteOptions): Promise<RewriteResult>;
+/**
+ * Compute the final HTML and a pending/reused plan without performing any
+ * upload, attachment mutation, or renderer spawn. Used by `skipUnchanged` to
+ * compare the would-be body byte-equal against the current page body before
+ * any remote mutation is considered.
+ *
+ * The preflight validates every local source (root confinement, regular
+ * file, size limits, missing/escaping) the same way {@link rewriteImagesToAttachments}
+ * does, so a dry-validation pass before a page PUT never relaxes the trust
+ * boundary established by CFSEC-02.
+ */
+declare function preflightImagesToAttachments(html: string, pageId: string, client: AttachmentGateway, options: RewriteOptions): Promise<PreflightResult>;
 
 interface MermaidRewriteResult {
     html: string;
-    /** Placeholders that could not be rendered (mmdc missing or render failure). Fallback source is in the original code macro. */
     fallbacks: string[];
     uploaded: ReadonlyArray<{
         id: string;
         attachment: Attachment;
     }>;
 }
+/**
+ * Equivalent of {@link MermaidRewriteResult} for a preflight pass: it produces
+ * the final HTML that would be emitted if rendering and uploads were allowed,
+ * plus the set of mermaid blocks that would require a fresh render/upload.
+ *
+ * A preflight is `predictable` when every mermaid block resolves to an existing
+ * attachment whose stored content hash matches the local source hash; in that
+ * state no `mmdc` spawn, attachment mutation, or render work is required.
+ */
+interface MermaidPreflightResult {
+    html: string;
+    /** Blocks that would render and/or upload on a real rewrite. */
+    pending: ReadonlyArray<{
+        id: string;
+        filename: string;
+        hash: string;
+    }>;
+    /** Blocks already matching an existing attachment by content hash. */
+    reused: ReadonlyArray<{
+        id: string;
+        attachment: Attachment;
+    }>;
+    /** Blocks that would fall back to a code macro when `mmdc` is unavailable. */
+    fallbacks: string[];
+}
 interface MermaidRewriteOptions {
     /** Override the mmdc binary path; otherwise discovered via PATH. */
     mmdcPath?: string;
@@ -160,8 +288,25 @@ interface MermaidRewriteOptions {
     renderHook?: (source: string, outFile: string) => Promise<void>;
     /** Force-enable or force-disable rendering regardless of PATH detection. When true, skips the mmdc probe. */
     available?: boolean;
+    /** Timeout (ms) for the mmdc subprocess and stream accumulation. Default 30000. */
+    renderTimeoutMs?: number;
+    /** Maximum bytes accumulated from stdout/stderr before rejecting. Default 1 MiB. */
+    maxStreamBytes?: number;
 }
-declare function rewriteMermaidBlocks(html: string, blocks: MermaidBlock[], pageId: string, client: ConfluenceClient, options?: MermaidRewriteOptions): Promise<MermaidRewriteResult>;
+declare function rewriteMermaidBlocks(html: string, blocks: MermaidBlock[], pageId: string, client: AttachmentGateway, options?: MermaidRewriteOptions): Promise<MermaidRewriteResult>;
+/**
+ * Compute the final HTML and a pending/reused plan without performing any
+ * `mmdc` spawn, attachment mutation, or upload. Used by `skipUnchanged` to
+ * compare the would-be body byte-equal against the current page body before
+ * any remote mutation or renderer work is considered.
+ *
+ * The preflight is conservative: a block that would fall back to a code macro
+ * (because `mmdc` would be unavailable when run) is reported in `fallbacks`
+ * and rendered into the predicted HTML as a code macro, matching the real
+ * rewrite path. Blocks already present as a code macro in the page body must
+ * remain a code macro to keep the comparison stable.
+ */
+declare function preflightMermaidBlocks(html: string, blocks: MermaidBlock[], pageId: string, client: AttachmentGateway, options?: MermaidRewriteOptions): Promise<MermaidPreflightResult>;
 
 declare const INTERACTIVE_FLAG: FlagSpec;
 interface ConfluenceSyncOptions {
@@ -181,14 +326,32 @@ interface ConfluenceSyncOptions {
     cwd?: string;
     /** Version-message suffix appended to every page/attachment PUT. */
     versionMessage?: string;
-    /** Skip uploads that would have no markdown changes (default: true). */
+    /**
+     * Skip uploads that would have no markdown changes (default: true).
+     *
+     * When true, a second identical sync performs no page PUT, no attachment
+     * mutation, and no Mermaid `mmdc` spawn: attachment and Mermaid names are
+     * content-addressed (sha256 of the source), so detecting an unchanged body
+     * produces byte-equal storage HTML to the current page body before any
+     * render/upload work is performed.
+     */
     skipUnchanged?: boolean;
     /** Render ```html fenced blocks as inline HTML via the Confluence `html` macro instead of a code box (default: false). */
     renderHtmlBlocks?: boolean;
-    /** Dry-run: walk the tree and print the plan but make no API calls. */
+    /**
+     * Dry-run: walk the tree and validate every markdown file and local image
+     * source (same preflight as a real sync) then print the plan, but make no
+     * API mutation calls. Credentials are not required under `--dry-run`.
+     */
     dryRun?: boolean;
-    /** Custom Confluence client instance (testing). When supplied, `username`/`apiToken`/`baseUrl` are ignored. */
-    client?: ConfluenceClient;
+    /**
+     * Custom Confluence gateway. Any object whose method shapes match
+     * {@link ConfluenceGateway} is accepted (typed fakes — no `unknown` cast).
+     * When supplied, `username`/`apiToken`/`baseUrl`/`spaceKey`/`parentPageId`
+     * are ignored by the orchestrator and the credential/baseUrl required-field
+     * checks are skipped — the gateway owns all remote work.
+     */
+    client?: ConfluenceGateway;
     /** Logger sink; defaults to `console`. */
     log?: (message: string) => void;
 }
@@ -205,7 +368,98 @@ interface ConfluenceSyncPlan {
     dryRun: boolean;
     renderHtmlBlocks: boolean;
 }
+/** A single markdown entry's locally-validated sync plan. */
+interface LocalSyncEntryPlan {
+    /** The original doc-tree entry this plan covers. */
+    entry: DocEntry;
+    /** Rendered storage HTML from `markdownToStorage` (placeholder macros intact). */
+    html: string;
+    /** Mermaid blocks parsed from the markdown source. */
+    mermaidBlocks: ReadonlyArray<MermaidBlock>;
+    /** Markdown file's directory, used to resolve relative image src values. */
+    markdownDir: string;
+    /** Whether the rendered body contains any local-image placeholders (`<ac:image data-local-src>`). */
+    hasLocalImages: boolean;
+    /** Whether the rendered body contains any Mermaid placeholder macros. */
+    hasMermaidBlocks: boolean;
+    /**
+     * Resolved content-addressed attachment sources for every local image
+     * placeholder, validated (root confinement, regular file, size limits) by
+     * the local preflight pass. Empty when the body has no local images.
+     */
+    attachments: ReadonlyArray<ValidatedAttachmentSource>;
+}
+/** Aggregate result of the local preflight pass over every doc-tree entry. */
+interface LocalSyncPlan {
+    entries: ReadonlyArray<LocalSyncEntryPlan>;
+}
+/**
+ * Structured report returned from {@link validateLocalSync}. Each defect names
+ * the doc-tree path that failed and the error message the upload path would
+ * have produced, so callers can fix local inputs without any remote mutation.
+ */
+interface LocalSyncValidationError {
+    entry: DocEntry;
+    error: Error;
+}
+declare class LocalSyncValidationAggregateError extends Error {
+    readonly defects: ReadonlyArray<LocalSyncValidationError>;
+    constructor(defects: ReadonlyArray<LocalSyncValidationError>);
+}
+/**
+ * Pre-read the document tree, convert every Markdown file to storage HTML,
+ * and validate every local image source (root confinement, regular file,
+ * size limits) using the same {@link validateAttachmentSources} path that
+ * {@link rewriteImagesToAttachments} applies at upload time.
+ *
+ * Runs against local files only — no client, no network, and no API mutation.
+ * Throws {@link LocalSyncValidationAggregateError} listing every defect so a
+ * caller can fix all local inputs in one pass instead of failing entry by
+ * entry after orphan pages or partial uploads have already occurred.
+ */
+declare function validateLocalSync(entries: ReadonlyArray<DocEntry>, plan: ConfluenceSyncPlan): LocalSyncPlan;
+/** A page successfully created or updated during the remote mutation phase. */
+interface SyncChange {
+    /** Doc-tree entry that was synced. */
+    entry: DocEntry;
+    /** Confluence page id that was created or updated. */
+    pageId: string;
+    /** Outcome: `created` (page POSTed, optionally with final body), `updated` (page PUT), or `unchanged` (skipUnchanged no-op). */
+    kind: 'created' | 'updated' | 'unchanged';
+}
+/** A single remote-mutation failure during the sync loop. */
+interface SyncFailure {
+    /** Doc-tree entry that failed. */
+    entry: DocEntry;
+    /** Underlying error from the remote call. */
+    error: Error;
+}
+/**
+ * Structured partial-mutation report. Thrown when the remote mutation phase
+ * fails after at least one page has been created/updated. Carries every
+ * successful {@link SyncChange}, the {@link SyncFailure} that aborted the run,
+ * and the doc-tree entries that remained unprocessed after the abort.
+ *
+ * The error message echoes the underlying failure message so existing
+ * `.rejects.toThrowError(/regex/)` assertions on remote errors keep matching.
+ */
+declare class SyncMutationError extends Error {
+    readonly changes: ReadonlyArray<SyncChange>;
+    readonly failure: SyncFailure;
+    readonly unprocessed: ReadonlyArray<DocEntry>;
+    constructor(input: {
+        changes: ReadonlyArray<SyncChange>;
+        failure: SyncFailure;
+        unprocessed: ReadonlyArray<DocEntry>;
+    });
+}
+/** Result shape returned by {@link syncConfluenceToDocs}. `void` is preserved
+ * for callers that ignore the return value; structured evidence is available
+ * when a full run completes without error. */
+interface SyncResult {
+    changes: ReadonlyArray<SyncChange>;
+}
 declare function resolveConfluenceSyncPlan(options?: ConfluenceSyncOptions): ConfluenceSyncPlan;
-declare function syncConfluenceToDocs(options?: ConfluenceSyncOptions): Promise<void>;
+declare function syncConfluenceToDocs(options?: ConfluenceSyncOptions): Promise<SyncResult | void>;
 
-export { type Attachment, ConfluenceApiError, ConfluenceClient, type ConfluenceClientOptions, type ConfluenceSyncOptions, type ConfluenceSyncPlan, type DocEntry, type DocTree, INTERACTIVE_FLAG, LOCAL_IMAGE_PLACEHOLDER_RE, type MarkdownConvertOptions, type MarkdownConvertResult, type MermaidBlock, type MermaidRewriteOptions, type MermaidRewriteResult, type Page, type PageBody, type PageVersion, escapeAttachmentFilename, escapeXmlAttribute, isMarkdownName, isRemoteUrl, markdownToStorage, readDocTree, renderHtmlBlock, renderInline, resolveConfluenceSyncPlan, resolveConfluenceSyncPlan as resolveSyncPlan, rewriteImagesToAttachments, rewriteMermaidBlocks, syncConfluenceToDocs, titleFromSegment };
+export { type Attachment, type AttachmentGateway, type PreflightResult as AttachmentPreflightResult, ConfluenceApiError, ConfluenceClient, type ConfluenceClientOptions, type ConfluenceGateway, type ConfluenceSyncOptions, type ConfluenceSyncPlan, type CreatePageInput, type DocEntry, type DocTree, INTERACTIVE_FLAG, type LocalSyncEntryPlan, type LocalSyncPlan, LocalSyncValidationAggregateError, type LocalSyncValidationError, type MarkdownConvertOptions, type MarkdownConvertResult, type MermaidBlock, type MermaidPreflightResult, type MermaidRewriteOptions, type MermaidRewriteResult, type Page, type PageBody, type PageVersion, type RewriteOptions, type RewriteResult, type SyncChange, type SyncFailure, SyncMutationError, type SyncResult, type UpdatePageInput, type ValidatedAttachmentSource, escapeAttachmentFilename, escapeXmlAttribute, isAllowedUrl, isMarkdownName, isRemoteUrl, markdownToStorage, preflightImagesToAttachments, preflightMermaidBlocks, readDocTree, resolveConfluenceSyncPlan, resolveConfluenceSyncPlan as resolveSyncPlan, rewriteImagesToAttachments, rewriteMermaidBlocks, syncConfluenceToDocs, titleFromSegment, validateAttachmentSources, validateLocalSync };