@repo-toolkit/confluence 0.19.0 → 0.21.0

package/index.d.ts

@@ -18,6 +18,7 @@ declare function isRemoteUrl(src: string): boolean;
 declare function escapeXmlAttribute(text: string): string;
 declare function escapeAttachmentFilename(filename: string): string;
 
+declare const CONFLUENCE_MANAGED_LABEL = "repo-toolkit-confluence";
 interface ConfluenceClientOptions {
     baseUrl: string;
     username: string;
@@ -59,6 +60,23 @@ interface ConfluenceGateway extends AttachmentGateway {
     getPage(pageId: string): Promise<Page>;
     createPage(input: CreatePageInput): Promise<Page>;
     updatePage(input: UpdatePageInput): Promise<Page>;
+    getPageDescendants(pageId: string): Promise<PageDescendant[]>;
+    getPageLabels(pageId: string): Promise<PageLabel[]>;
+    addManagedLabel(pageId: string): Promise<void>;
+    deletePage(pageId: string): Promise<void>;
+}
+interface PageDescendant {
+    id: string;
+    type: string;
+    title?: string;
+    parentId?: string;
+    depth?: number;
+    status?: string;
+}
+interface PageLabel {
+    name: string;
+    prefix: string;
+    id?: string;
 }
 interface PageBody {
     representation: 'storage' | 'atlas_doc' | 'wiki' | 'view' | 'export_view';
@@ -145,6 +163,11 @@ declare class ConfluenceClient implements ConfluenceGateway {
     getPage(pageId: string): Promise<Page>;
     createPage(input: CreatePageInput): Promise<Page>;
     updatePage(input: UpdatePageInput): Promise<Page>;
+    getPageDescendants(pageId: string): Promise<PageDescendant[]>;
+    getPageLabels(pageId: string): Promise<PageLabel[]>;
+    addManagedLabel(pageId: string): Promise<void>;
+    deletePage(pageId: string): Promise<void>;
+    private listAll;
     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>;
@@ -167,6 +190,11 @@ interface DocTree {
 declare function readDocTree(root: string, depth?: number): Promise<DocTree>;
 declare function isMarkdownName(name: string): boolean;
 declare function titleFromSegment(segment: string): string;
+declare const PAGE_TITLE_STRATEGIES: readonly ["filename-stem", "filename", "sentence-case-parent", "sentence-case-parents", "sentence-case-path"];
+type PageTitleStrategy = (typeof PAGE_TITLE_STRATEGIES)[number];
+declare const DEFAULT_PAGE_TITLE_STRATEGY: PageTitleStrategy;
+declare function resolvePageTitleStrategy(value: unknown): PageTitleStrategy;
+declare function pageTitleFromSegments(segments: readonly string[], strategy: PageTitleStrategy): string;
 
 interface RewriteResult {
     html: string;
@@ -336,10 +364,29 @@ interface ConfluenceSyncOptions {
      * render/upload work is performed.
      */
     skipUnchanged?: boolean;
+    /**
+     * Leaf page title strategy (default: `filename-stem`). Applied only to
+     * Markdown leaf pages; folder-generated parent pages keep their raw
+     * directory-segment titles. See {@link PAGE_TITLE_STRATEGIES}.
+     */
+    pageTitleStrategy?: PageTitleStrategy;
     /** Render ```html fenced blocks as inline HTML via the Confluence `html` macro instead of a code box (default: false). */
     renderHtmlBlocks?: boolean;
     /** Repository URL appended to synced pages as an italic source notice. */
     repositoryUrl?: string;
+    /**
+     * Destructive reset (default: false). When true, a real sync first moves
+     * every page descendant of `parentPageId` — including manual/unlabeled
+     * pages — to the Confluence trash, then recreates the local hierarchy.
+     * `parentPageId` itself is never deleted.
+     */
+    clean?: boolean;
+    /**
+     * Update the target parent summary (default: true). When true, a successful
+     * real sync fetches and merges a deterministic tool-managed region into the
+     * parent page body, preserving all external content.
+     */
+    updateParentPage?: boolean;
     /**
      * 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
@@ -370,11 +417,24 @@ interface ConfluenceSyncPlan {
     dryRun: boolean;
     renderHtmlBlocks: boolean;
     repositoryUrl: string;
+    /** Destructive reset flag; resolved from {@link ConfluenceSyncOptions.clean} with default false. */
+    clean: boolean;
+    /** Parent-summary flag; resolved from {@link ConfluenceSyncOptions.updateParentPage} with default true. */
+    updateParentPage: boolean;
+    /** Validated leaf page title strategy applied during planning. */
+    pageTitleStrategy: PageTitleStrategy;
 }
 /** A single markdown entry's locally-validated sync plan. */
 interface LocalSyncEntryPlan {
     /** The original doc-tree entry this plan covers. */
     entry: DocEntry;
+    /**
+     * The resolved Confluence page title for this leaf entry, computed once via
+     * {@link pageTitleFromSegments} with the plan's {@link ConfluenceSyncPlan.pageTitleStrategy}.
+     * Consumed verbatim by local hierarchy validation, dry-run output, remote
+     * lookup, create, and update paths.
+     */
+    title: string;
     /** Rendered storage HTML from `markdownToStorage` (placeholder macros intact). */
     html: string;
     /** Mermaid blocks parsed from the markdown source. */
@@ -461,8 +521,97 @@ declare class SyncMutationError extends Error {
  * when a full run completes without error. */
 interface SyncResult {
     changes: ReadonlyArray<SyncChange>;
+    /** Page ids that received the global ownership marker during this run. */
+    labelsAdded: ReadonlyArray<string>;
+    /** Page ids trashed by the explicit `clean: true` pre-sync reset. */
+    cleanDeletions: ReadonlyArray<string>;
+    /** Page ids trashed by the default label-gated prune after a successful sync. */
+    pruneDeletions: ReadonlyArray<string>;
+    /** Stale labeled pages retained because an unlabeled, non-page, or otherwise
+     * retained descendant made deletion unsafe. */
+    blocked: ReadonlyArray<string>;
+    /** Parent-summary outcome: `updated` when the parent body changed, `unchanged` when already equal, `skipped` when opt-out. */
+    parentStatus: 'updated' | 'unchanged' | 'skipped';
+}
+/** A single failed clean/prune deletion. */
+interface ReconciliationFailure {
+    pageId: string;
+    error: Error;
+}
+/**
+ * Structured partial-mutation report for the clean and prune phases. Thrown
+ * when trashing a page fails mid-phase. Carries every completed deletion, the
+ * failed page, and the planned deletions that were never attempted.
+ */
+declare class ReconciliationError extends Error {
+    readonly phase: 'clean' | 'prune';
+    readonly completed: ReadonlyArray<string>;
+    readonly failure: ReconciliationFailure;
+    readonly unprocessed: ReadonlyArray<string>;
+    constructor(input: {
+        phase: 'clean' | 'prune';
+        completed: ReadonlyArray<string>;
+        failure: ReconciliationFailure;
+        unprocessed: ReadonlyArray<string>;
+    });
 }
+declare class ParentSummaryError extends Error {
+    readonly phase: 'parent-summary';
+    readonly changes: ReadonlyArray<SyncChange>;
+    readonly labelsAdded: ReadonlyArray<string>;
+    readonly cleanDeletions: ReadonlyArray<string>;
+    readonly pruneDeletions: ReadonlyArray<string>;
+    readonly blocked: ReadonlyArray<string>;
+    readonly failure: ReconciliationFailure;
+    constructor(input: {
+        changes: ReadonlyArray<SyncChange>;
+        labelsAdded: ReadonlyArray<string>;
+        cleanDeletions: ReadonlyArray<string>;
+        pruneDeletions: ReadonlyArray<string>;
+        blocked: ReadonlyArray<string>;
+        failure: ReconciliationFailure;
+    });
+}
+/** One inventoried descendant of the target page, annotated with ownership. */
+interface RemoteInventoryEntry {
+    id: string;
+    type: string;
+    parentId?: string;
+    depth?: number;
+    title?: string;
+    /** Whether the page carries the exact global ownership marker. */
+    labeled: boolean;
+}
+/** Outcome of the pure deletion planners. */
+interface DeletionPlan {
+    /** Page ids to trash, ordered deepest-first (children before parents). */
+    deletions: ReadonlyArray<string>;
+    /** Stale labeled pages retained because deleting them would also remove a
+     * retained (unlabeled, non-page, or expected) descendant. */
+    blocked: ReadonlyArray<string>;
+}
+/**
+ * Pure label-gated stale-page planner. Protects the target page, expected
+ * (mapped) ids, unlabeled pages, non-page content, and any stale page with a
+ * retained descendant. Throws when the inventory is too incomplete to verify
+ * ancestry safely.
+ */
+declare function planStalePruning(input: {
+    parentPageId: string;
+    expectedIds: ReadonlySet<string>;
+    inventory: ReadonlyArray<RemoteInventoryEntry>;
+}): DeletionPlan;
+/**
+ * Pure explicit-clean planner. Trash every page descendant regardless of
+ * label. Fails closed before any deletion when the subtree contains non-page
+ * content whose retention cannot be proven, or when the inventory is
+ * incomplete.
+ */
+declare function planCleanDeletions(input: {
+    parentPageId: string;
+    inventory: ReadonlyArray<RemoteInventoryEntry>;
+}): DeletionPlan;
 declare function resolveConfluenceSyncPlan(options?: ConfluenceSyncOptions): ConfluenceSyncPlan;
 declare function syncConfluenceToDocs(options?: ConfluenceSyncOptions): Promise<SyncResult | void>;
 
-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 };
+export { type Attachment, type AttachmentGateway, type PreflightResult as AttachmentPreflightResult, CONFLUENCE_MANAGED_LABEL, ConfluenceApiError, ConfluenceClient, type ConfluenceClientOptions, type ConfluenceGateway, type ConfluenceSyncOptions, type ConfluenceSyncPlan, type CreatePageInput, DEFAULT_PAGE_TITLE_STRATEGY, type DeletionPlan, 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, PAGE_TITLE_STRATEGIES, type Page, type PageBody, type PageDescendant, type PageLabel, type PageTitleStrategy, type PageVersion, ParentSummaryError, ReconciliationError, type ReconciliationFailure, type RemoteInventoryEntry, type RewriteOptions, type RewriteResult, type SyncChange, type SyncFailure, SyncMutationError, type SyncResult, type UpdatePageInput, type ValidatedAttachmentSource, escapeAttachmentFilename, escapeXmlAttribute, isAllowedUrl, isMarkdownName, isRemoteUrl, markdownToStorage, pageTitleFromSegments, planCleanDeletions, planStalePruning, preflightImagesToAttachments, preflightMermaidBlocks, readDocTree, resolveConfluenceSyncPlan, resolvePageTitleStrategy, resolveConfluenceSyncPlan as resolveSyncPlan, rewriteImagesToAttachments, rewriteMermaidBlocks, syncConfluenceToDocs, titleFromSegment, validateAttachmentSources, validateLocalSync };