@repo-toolkit/confluence 0.19.0 → 0.20.0

package/README.md

@@ -76,6 +76,7 @@ Flags:
   italic source notice. The `--folder` path is added to the notice link when it
   is relative to `--cwd`. When omitted, GitHub Actions runs infer this from
   `GITHUB_SERVER_URL` and `GITHUB_REPOSITORY`.
+- `--page-title-strategy <value>` — leaf page title strategy (default: `filename-stem`). One of `filename-stem`, `filename`, `sentence-case-parent`, `sentence-case-parents`, `sentence-case-path`. Applied only to Markdown leaf pages; folder-generated parent pages keep their raw directory-segment titles. See [leaf page title strategies](#leaf-page-title-strategies).
 - `--skip-unchanged` / `--no-skip-unchanged` — skip pages whose body is unchanged (default: `skip`)
 - `--dry-run` — walk the doc tree and validate every markdown file and local
   image source (same preflight as a real sync) then log the plan. No API
@@ -93,26 +94,49 @@ both read for every option. Boolean env values accept `true|1|yes|on` /
 `false|0|no|off` (empty string is falsy); any other value exits nonzero with
 `Invalid boolean value for <ENV_NAME>: <raw>`.
 
-| Option                  | `CONFLUENCE_*`                  | `INPUT_*` (Actions form)                      |
-| ----------------------- | ------------------------------- | --------------------------------------------- |
-| folder                  | `CONFLUENCE_FOLDER`             | `INPUT_FOLDER`                                |
-| username                | `CONFLUENCE_USERNAME`           | `INPUT_USERNAME`                              |
-| apiToken                | `CONFLUENCE_API_TOKEN`          | `INPUT_API-TOKEN`, `INPUT_PASSWORD`           |
-| apiTokenFile            | `CONFLUENCE_API_TOKEN_FILE`     | `INPUT_API-TOKEN-FILE`, `INPUT_PASSWORD-FILE` |
-| baseUrl                 | `CONFLUENCE_BASE_URL`           | `INPUT_CONFLUENCE-BASE-URL`                   |
-| spaceKey                | `CONFLUENCE_SPACE_KEY`          | `INPUT_SPACE-KEY`                             |
-| parentPageId            | `CONFLUENCE_PARENT_PAGE_ID`     | `INPUT_PARENT-PAGE-ID`                        |
-| versionMessage          | `CONFLUENCE_VERSION_MESSAGE`    | `INPUT_VERSION-MESSAGE`                       |
-| repositoryUrl           | `CONFLUENCE_REPOSITORY_URL`     | `INPUT_REPOSITORY-URL`                        |
-| skipUnchanged (bool)    | `CONFLUENCE_SKIP_UNCHANGED`     | `INPUT_SKIP-UNCHANGED`                        |
-| dryRun (bool)           | `CONFLUENCE_DRY_RUN`            | `INPUT_DRY-RUN`                               |
-| renderHtmlBlocks (bool) | `CONFLUENCE_RENDER_HTML_BLOCKS` | `INPUT_RENDER-HTML-BLOCKS`                    |
+| Option                  | `CONFLUENCE_*`                   | `INPUT_*` (Actions form)                      |
+| ----------------------- | -------------------------------- | --------------------------------------------- |
+| folder                  | `CONFLUENCE_FOLDER`              | `INPUT_FOLDER`                                |
+| username                | `CONFLUENCE_USERNAME`            | `INPUT_USERNAME`                              |
+| apiToken                | `CONFLUENCE_API_TOKEN`           | `INPUT_API-TOKEN`, `INPUT_PASSWORD`           |
+| apiTokenFile            | `CONFLUENCE_API_TOKEN_FILE`      | `INPUT_API-TOKEN-FILE`, `INPUT_PASSWORD-FILE` |
+| baseUrl                 | `CONFLUENCE_BASE_URL`            | `INPUT_CONFLUENCE-BASE-URL`                   |
+| spaceKey                | `CONFLUENCE_SPACE_KEY`           | `INPUT_SPACE-KEY`                             |
+| parentPageId            | `CONFLUENCE_PARENT_PAGE_ID`      | `INPUT_PARENT-PAGE-ID`                        |
+| versionMessage          | `CONFLUENCE_VERSION_MESSAGE`     | `INPUT_VERSION-MESSAGE`                       |
+| repositoryUrl           | `CONFLUENCE_REPOSITORY_URL`      | `INPUT_REPOSITORY-URL`                        |
+| pageTitleStrategy       | `CONFLUENCE_PAGE_TITLE_STRATEGY` | `INPUT_PAGE-TITLE-STRATEGY`                   |
+| skipUnchanged (bool)    | `CONFLUENCE_SKIP_UNCHANGED`      | `INPUT_SKIP-UNCHANGED`                        |
+| dryRun (bool)           | `CONFLUENCE_DRY_RUN`             | `INPUT_DRY-RUN`                               |
+| renderHtmlBlocks (bool) | `CONFLUENCE_RENDER_HTML_BLOCKS`  | `INPUT_RENDER-HTML-BLOCKS`                    |
 
 Errors, `--help`, and all log lines never print the supplied token value. The
 secret-file loader wraps fs errors via `Error.cause` (`Failed to read
 apiTokenFile at <path>`, `apiTokenFile at <path> is empty`) without revealing
 the file contents.
 
+## Leaf page title strategies
+
+Leaf Confluence page titles are derived from the Markdown file's relative path segments. Directory segments become synthetic parent-page titles and retain their raw segment text for every strategy — only the Markdown leaf file uses `pageTitleStrategy`.
+
+| Strategy                  | Behavior                                                                                      | Example for `community-nodes/cdogs-document-generator/credentials.md`   |
+| ------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `filename-stem` (default) | Original filename without the final `.md` extension                                           | `credentials`                                                           |
+| `filename`                | Original filename including extension                                                         | `credentials.md`                                                        |
+| `sentence-case-parent`    | Sentence-case filename stem plus immediate parent folder                                      | `Credentials (cdogs-document-generator)`                                |
+| `sentence-case-parents`   | Sentence-case filename stem plus all parent folders                                           | `Credentials (community-nodes/cdogs-document-generator)`                |
+| `sentence-case-path`      | Sentence-case filename stem plus all parent folders and original filename including extension | `Credentials (community-nodes/cdogs-document-generator/credentials.md)` |
+
+Sentence case is deterministic and dependency-free: remove only the final case-insensitive `.md`; replace each run of `-` and `_` with one space; trim; lowercase ASCII letters; uppercase the first ASCII letter. Digits and other punctuation are preserved. Examples: `failed-deployment.md` → `Failed deployment`, `n8n_setup.md` → `N8n setup`, `README.md` → `Readme`. Parent folders are the segments before the filename, joined with `/` exactly as stored. Preserve the original filename and extension casing in `filename` and inside `sentence-case-path` (for example, `Guide.MD` remains `Guide.MD` where the original filename is included).
+
+Root-file behavior: for `sentence-case-parent` and `sentence-case-parents` the parentheses are omitted when a file is directly under the documentation root (`overview.md` → `Overview`). For `sentence-case-path`, the root parenthesized path is the filename itself (`overview.md` → `Overview (overview.md)`).
+
+### Migration and uniqueness notes
+
+> **Changing the strategy changes title-based identity.** Sync is additive and non-pruning and looks up Confluence pages by title under parent. Switching the strategy therefore seeks a new title and may **create a new page while leaving the old page untouched** — it does not rename, move, or delete existing pages. Operators must manually rename, delete, or archive old generated pages (or migrate them) before switching strategies in production.
+
+Path-based strategies reduce predictable local collisions (for example, repeated basenames such as `credentials.md` or `README.md` in separate subtrees) but cannot guarantee uniqueness against unrelated or manually created pages already present in the target Confluence space. Existing spaces may still cause Confluence API conflicts if a generated title collides with an unrelated page under the same parent. Do not truncate or hash titles locally; if Confluence imposes a remote title-length limit, the existing API error behavior applies.
+
 ## JavaScript API
 
 ```ts
@@ -126,6 +150,7 @@ await syncConfluenceToDocs({
   spaceKey: 'ENG',
   parentPageId: '123456789',
   versionMessage: 'chore(docs): sync',
+  pageTitleStrategy: 'sentence-case-parents', // optional; default: 'filename-stem'
 });
 ```
 
@@ -185,6 +210,7 @@ inputs:
   space-key: { required: true }
   parent-page-id: { required: true }
   version-message: { required: false }
+  page-title-strategy: { required: false, default: 'filename-stem' }
   dry-run: { required: false, default: 'false' }
   skip-unchanged: { required: false, default: 'true' }
   render-html-blocks: { required: false, default: 'false' }

package/cli.js

@@ -588,6 +588,64 @@ function titleFromSegment(segment) {
   }
   return segment;
 }
+var PAGE_TITLE_STRATEGIES = [
+  "filename-stem",
+  "filename",
+  "sentence-case-parent",
+  "sentence-case-parents",
+  "sentence-case-path"
+];
+var DEFAULT_PAGE_TITLE_STRATEGY = "filename-stem";
+function resolvePageTitleStrategy(value) {
+  if (value === void 0 || value === null) {
+    return DEFAULT_PAGE_TITLE_STRATEGY;
+  }
+  if (typeof value === "string" && PAGE_TITLE_STRATEGIES.includes(value)) {
+    return value;
+  }
+  throw new Error(
+    `Invalid pageTitleStrategy: expected one of ${PAGE_TITLE_STRATEGIES.join(", ")}, got ${JSON.stringify(value)}`
+  );
+}
+function sentenceCaseStem(filename) {
+  let stem = filename;
+  if (/\.md$/i.test(stem)) {
+    stem = stem.slice(0, stem.length - MARKDOWN_EXT.length);
+  }
+  let out = stem.replace(/[-_]+/g, " ").trim().replace(/[A-Z]/g, (c) => c.toLowerCase());
+  const firstLetter = /[a-z]/.exec(out);
+  if (firstLetter) {
+    const i = firstLetter.index;
+    out = out.slice(0, i) + out.charAt(i).toUpperCase() + out.slice(i + 1);
+  }
+  return out;
+}
+function pageTitleFromSegments(segments, strategy) {
+  const filename = segments.length > 0 ? segments[segments.length - 1] : "";
+  const parents = segments.slice(0, segments.length - 1);
+  switch (strategy) {
+    case "filename-stem":
+      return titleFromSegment(filename);
+    case "filename":
+      return filename;
+    case "sentence-case-parent": {
+      const title = sentenceCaseStem(filename);
+      if (parents.length === 0) {
+        return title;
+      }
+      return `${title} (${parents[parents.length - 1]})`;
+    }
+    case "sentence-case-parents": {
+      const title = sentenceCaseStem(filename);
+      if (parents.length === 0) {
+        return title;
+      }
+      return `${title} (${parents.join("/")})`;
+    }
+    case "sentence-case-path":
+      return `${sentenceCaseStem(filename)} (${[...parents, filename].join("/")})`;
+  }
+}
 
 // src/markdown.ts
 var STORAGE_LINE_BREAK = "<br />";
@@ -1631,6 +1689,7 @@ function validateLocalSync(entries, plan) {
       }) : [];
       plans.push({
         entry,
+        title: pageTitleFromSegments(entry.segments, plan.pageTitleStrategy),
         html: body,
         mermaidBlocks,
         markdownDir,
@@ -1660,6 +1719,7 @@ var SyncMutationError = class extends Error {
   }
 };
 function resolveConfluenceSyncPlan(options = {}) {
+  const pageTitleStrategy = resolvePageTitleStrategy(options.pageTitleStrategy);
   const cwd = resolve2(options.cwd ?? process.cwd());
   const folder = resolveInputPath(cwd, options.folder ?? "");
   if (!options.folder) {
@@ -1706,7 +1766,8 @@ function resolveConfluenceSyncPlan(options = {}) {
     skipUnchanged: options.skipUnchanged ?? true,
     dryRun: options.dryRun ?? false,
     renderHtmlBlocks: options.renderHtmlBlocks === true,
-    repositoryUrl
+    repositoryUrl,
+    pageTitleStrategy
   };
 }
 async function syncConfluenceToDocs(options = {}) {
@@ -1717,15 +1778,15 @@ async function syncConfluenceToDocs(options = {}) {
     log(`No markdown files found under ${plan.folder}`);
     return;
   }
-  validateLocalHierarchy(tree.entries);
   const localPlan = validateLocalSync(tree.entries, plan);
+  validateLocalHierarchy(localPlan.entries, plan.pageTitleStrategy);
   if (plan.dryRun) {
     log("[dry-run] Walking documentation tree only.");
     for (const entryPlan of localPlan.entries) {
       const attCount = entryPlan.attachments.length;
       const mermaidCount = entryPlan.mermaidBlocks.length;
       log(
-        `[dry-run] would sync ${entryPlan.entry.segments.join("/")}` + (attCount > 0 ? ` (${attCount} attachment${attCount === 1 ? "" : "s"} validated)` : "") + (mermaidCount > 0 ? ` (${mermaidCount} mermaid block${mermaidCount === 1 ? "" : "s"})` : "")
+        `[dry-run] would sync ${entryPlan.entry.segments.join("/")} as "${entryPlan.title}"` + (attCount > 0 ? ` (${attCount} attachment${attCount === 1 ? "" : "s"} validated)` : "") + (mermaidCount > 0 ? ` (${mermaidCount} mermaid block${mermaidCount === 1 ? "" : "s"})` : "")
       );
     }
     return;
@@ -1763,7 +1824,7 @@ async function syncEntry(entryPlan, plan, client, cache, log, changes) {
     const isLast = idx === segments.length - 1;
     const segment = segments[idx] ?? "";
     if (isLast && isMarkdownName(segment)) {
-      const title = titleFromSegment(segment);
+      const title = entryPlan.title;
       const leafNeedsUploads = hasLocalImages || hasMermaidBlocks;
       const existing = await cache.find(title, currentParentId);
       if (!existing && !leafNeedsUploads) {
@@ -1822,7 +1883,7 @@ async function syncEntry(entryPlan, plan, client, cache, log, changes) {
       return;
     }
     if (isMarkdownName(segment)) {
-      const title = titleFromSegment(segment);
+      const title = pageTitleFromSegments(segments.slice(0, idx + 1), plan.pageTitleStrategy);
       const page2 = await cache.findOrCreate(title, currentParentId);
       currentParentId = page2.id;
       continue;
@@ -1953,14 +2014,15 @@ async function predictBody(html, mermaidBlocks, pageId, client, ctx) {
   }
   return predicted;
 }
-function validateLocalHierarchy(entries) {
+function validateLocalHierarchy(entries, strategy) {
   const seen = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
+  for (const entryPlan of entries) {
+    const { entry } = entryPlan;
     let parentKey = "";
     for (let index = 0; index < entry.segments.length; index += 1) {
       const segment = entry.segments[index] ?? "";
       const isLast = index === entry.segments.length - 1;
-      const title = isMarkdownName(segment) ? titleFromSegment(segment) : segment;
+      const title = isMarkdownName(segment) ? isLast ? entryPlan.title : pageTitleFromSegments(entry.segments.slice(0, index + 1), strategy) : segment;
       const kind = isLast && isMarkdownName(segment) ? "file" : "dir";
       const key = `${parentKey}::${title}`;
       const existing = seen.get(key);
@@ -1986,6 +2048,7 @@ var SPECS = [
   { name: "parent-page-id" },
   { name: "version-message" },
   { name: "repository-url" },
+  { name: "page-title-strategy" },
   { name: "skip-unchanged", boolean: true, negatable: true },
   { name: "dry-run", boolean: true },
   { name: "render-html-blocks", boolean: true },
@@ -2031,6 +2094,7 @@ Environment variables (CLI form; GitHub Action INPUT_* form is also read):
   CONFLUENCE_PARENT_PAGE_ID            Numeric parent page id
   CONFLUENCE_VERSION_MESSAGE            Version-message suffix for every PUT
   CONFLUENCE_REPOSITORY_URL            Repository URL appended to synced pages
+  CONFLUENCE_PAGE_TITLE_STRATEGY       Leaf page title strategy (default: filename-stem)
   CONFLUENCE_SKIP_UNCHANGED            true|false (default: true)
   CONFLUENCE_DRY_RUN                   true|false (default: false)
   CONFLUENCE_RENDER_HTML_BLOCKS        true|false (default: false)
@@ -2051,6 +2115,8 @@ Options:
   --parent-page-id <id>         Numeric page id under which docs will be published (required)
   --version-message <text>      Commit message appended to every page/attachment PUT
   --repository-url <url>        Repository URL appended to synced pages as an italic notice
+  --page-title-strategy <value> Leaf page title strategy: filename-stem (default), filename,
+                                sentence-case-parent, sentence-case-parents, sentence-case-path
   --skip-unchanged               Skip pages whose body is unchanged (default: true)
   --no-skip-unchanged           Re-upload every page even when unchanged
   --dry-run                     Walk the doc tree and print the plan without API calls
@@ -2092,6 +2158,7 @@ var ENV_BINDINGS = [
   { envName: "INPUT_PARENT-PAGE-ID", key: "parentPageId", kind: "string" },
   { envName: "INPUT_VERSION-MESSAGE", key: "versionMessage", kind: "string" },
   { envName: "INPUT_REPOSITORY-URL", key: "repositoryUrl", kind: "string" },
+  { envName: "INPUT_PAGE-TITLE-STRATEGY", key: "pageTitleStrategy", kind: "string" },
   { envName: "INPUT_DRY-RUN", key: "dryRun", kind: "boolean" },
   { envName: "INPUT_SKIP-UNCHANGED", key: "skipUnchanged", kind: "boolean" },
   { envName: "INPUT_RENDER-HTML-BLOCKS", key: "renderHtmlBlocks", kind: "boolean" },
@@ -2104,6 +2171,7 @@ var ENV_BINDINGS = [
   { envName: "CONFLUENCE_PARENT_PAGE_ID", key: "parentPageId", kind: "string" },
   { envName: "CONFLUENCE_VERSION_MESSAGE", key: "versionMessage", kind: "string" },
   { envName: "CONFLUENCE_REPOSITORY_URL", key: "repositoryUrl", kind: "string" },
+  { envName: "CONFLUENCE_PAGE_TITLE_STRATEGY", key: "pageTitleStrategy", kind: "string" },
   { envName: "CONFLUENCE_DRY_RUN", key: "dryRun", kind: "boolean" },
   { envName: "CONFLUENCE_SKIP_UNCHANGED", key: "skipUnchanged", kind: "boolean" },
   { envName: "CONFLUENCE_RENDER_HTML_BLOCKS", key: "renderHtmlBlocks", kind: "boolean" }
@@ -2116,6 +2184,10 @@ function optionsFromEnv(env = process.env) {
       continue;
     }
     if (kind === "string") {
+      if (key === "pageTitleStrategy") {
+        options[key] = raw;
+        continue;
+      }
       if (!isStringOptionKey(key)) {
         continue;
       }
@@ -2156,6 +2228,9 @@ function buildOptions(result) {
   setIfString(options, "parentPageId", values["parent-page-id"]);
   setIfString(options, "versionMessage", values["version-message"]);
   setIfString(options, "repositoryUrl", values["repository-url"]);
+  if (values["page-title-strategy"] !== void 0) {
+    options.pageTitleStrategy = values["page-title-strategy"];
+  }
   if (values["skip-unchanged"] !== void 0) {
     options.skipUnchanged = values["skip-unchanged"] === "true";
   }

package/index.d.ts

@@ -167,6 +167,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,6 +341,12 @@ 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. */
@@ -370,11 +381,20 @@ interface ConfluenceSyncPlan {
     dryRun: boolean;
     renderHtmlBlocks: boolean;
     repositoryUrl: string;
+    /** 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. */
@@ -465,4 +485,4 @@ interface SyncResult {
 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, ConfluenceApiError, ConfluenceClient, type ConfluenceClientOptions, type ConfluenceGateway, type ConfluenceSyncOptions, type ConfluenceSyncPlan, type CreatePageInput, DEFAULT_PAGE_TITLE_STRATEGY, 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 PageTitleStrategy, type PageVersion, type RewriteOptions, type RewriteResult, type SyncChange, type SyncFailure, SyncMutationError, type SyncResult, type UpdatePageInput, type ValidatedAttachmentSource, escapeAttachmentFilename, escapeXmlAttribute, isAllowedUrl, isMarkdownName, isRemoteUrl, markdownToStorage, pageTitleFromSegments, preflightImagesToAttachments, preflightMermaidBlocks, readDocTree, resolveConfluenceSyncPlan, resolvePageTitleStrategy, resolveConfluenceSyncPlan as resolveSyncPlan, rewriteImagesToAttachments, rewriteMermaidBlocks, syncConfluenceToDocs, titleFromSegment, validateAttachmentSources, validateLocalSync };

package/index.js

@@ -574,6 +574,64 @@ function titleFromSegment(segment) {
   }
   return segment;
 }
+var PAGE_TITLE_STRATEGIES = [
+  "filename-stem",
+  "filename",
+  "sentence-case-parent",
+  "sentence-case-parents",
+  "sentence-case-path"
+];
+var DEFAULT_PAGE_TITLE_STRATEGY = "filename-stem";
+function resolvePageTitleStrategy(value) {
+  if (value === void 0 || value === null) {
+    return DEFAULT_PAGE_TITLE_STRATEGY;
+  }
+  if (typeof value === "string" && PAGE_TITLE_STRATEGIES.includes(value)) {
+    return value;
+  }
+  throw new Error(
+    `Invalid pageTitleStrategy: expected one of ${PAGE_TITLE_STRATEGIES.join(", ")}, got ${JSON.stringify(value)}`
+  );
+}
+function sentenceCaseStem(filename) {
+  let stem = filename;
+  if (/\.md$/i.test(stem)) {
+    stem = stem.slice(0, stem.length - MARKDOWN_EXT.length);
+  }
+  let out = stem.replace(/[-_]+/g, " ").trim().replace(/[A-Z]/g, (c) => c.toLowerCase());
+  const firstLetter = /[a-z]/.exec(out);
+  if (firstLetter) {
+    const i = firstLetter.index;
+    out = out.slice(0, i) + out.charAt(i).toUpperCase() + out.slice(i + 1);
+  }
+  return out;
+}
+function pageTitleFromSegments(segments, strategy) {
+  const filename = segments.length > 0 ? segments[segments.length - 1] : "";
+  const parents = segments.slice(0, segments.length - 1);
+  switch (strategy) {
+    case "filename-stem":
+      return titleFromSegment(filename);
+    case "filename":
+      return filename;
+    case "sentence-case-parent": {
+      const title = sentenceCaseStem(filename);
+      if (parents.length === 0) {
+        return title;
+      }
+      return `${title} (${parents[parents.length - 1]})`;
+    }
+    case "sentence-case-parents": {
+      const title = sentenceCaseStem(filename);
+      if (parents.length === 0) {
+        return title;
+      }
+      return `${title} (${parents.join("/")})`;
+    }
+    case "sentence-case-path":
+      return `${sentenceCaseStem(filename)} (${[...parents, filename].join("/")})`;
+  }
+}
 
 // src/markdown.ts
 var STORAGE_LINE_BREAK = "<br />";
@@ -1618,6 +1676,7 @@ function validateLocalSync(entries, plan) {
       }) : [];
       plans.push({
         entry,
+        title: pageTitleFromSegments(entry.segments, plan.pageTitleStrategy),
         html: body,
         mermaidBlocks,
         markdownDir,
@@ -1647,6 +1706,7 @@ var SyncMutationError = class extends Error {
   }
 };
 function resolveConfluenceSyncPlan(options = {}) {
+  const pageTitleStrategy = resolvePageTitleStrategy(options.pageTitleStrategy);
   const cwd = resolve2(options.cwd ?? process.cwd());
   const folder = resolveInputPath(cwd, options.folder ?? "");
   if (!options.folder) {
@@ -1693,7 +1753,8 @@ function resolveConfluenceSyncPlan(options = {}) {
     skipUnchanged: options.skipUnchanged ?? true,
     dryRun: options.dryRun ?? false,
     renderHtmlBlocks: options.renderHtmlBlocks === true,
-    repositoryUrl
+    repositoryUrl,
+    pageTitleStrategy
   };
 }
 async function syncConfluenceToDocs(options = {}) {
@@ -1704,15 +1765,15 @@ async function syncConfluenceToDocs(options = {}) {
     log(`No markdown files found under ${plan.folder}`);
     return;
   }
-  validateLocalHierarchy(tree.entries);
   const localPlan = validateLocalSync(tree.entries, plan);
+  validateLocalHierarchy(localPlan.entries, plan.pageTitleStrategy);
   if (plan.dryRun) {
     log("[dry-run] Walking documentation tree only.");
     for (const entryPlan of localPlan.entries) {
       const attCount = entryPlan.attachments.length;
       const mermaidCount = entryPlan.mermaidBlocks.length;
       log(
-        `[dry-run] would sync ${entryPlan.entry.segments.join("/")}` + (attCount > 0 ? ` (${attCount} attachment${attCount === 1 ? "" : "s"} validated)` : "") + (mermaidCount > 0 ? ` (${mermaidCount} mermaid block${mermaidCount === 1 ? "" : "s"})` : "")
+        `[dry-run] would sync ${entryPlan.entry.segments.join("/")} as "${entryPlan.title}"` + (attCount > 0 ? ` (${attCount} attachment${attCount === 1 ? "" : "s"} validated)` : "") + (mermaidCount > 0 ? ` (${mermaidCount} mermaid block${mermaidCount === 1 ? "" : "s"})` : "")
       );
     }
     return;
@@ -1750,7 +1811,7 @@ async function syncEntry(entryPlan, plan, client, cache, log, changes) {
     const isLast = idx === segments.length - 1;
     const segment = segments[idx] ?? "";
     if (isLast && isMarkdownName(segment)) {
-      const title = titleFromSegment(segment);
+      const title = entryPlan.title;
       const leafNeedsUploads = hasLocalImages || hasMermaidBlocks;
       const existing = await cache.find(title, currentParentId);
       if (!existing && !leafNeedsUploads) {
@@ -1809,7 +1870,7 @@ async function syncEntry(entryPlan, plan, client, cache, log, changes) {
       return;
     }
     if (isMarkdownName(segment)) {
-      const title = titleFromSegment(segment);
+      const title = pageTitleFromSegments(segments.slice(0, idx + 1), plan.pageTitleStrategy);
       const page2 = await cache.findOrCreate(title, currentParentId);
       currentParentId = page2.id;
       continue;
@@ -1940,14 +2001,15 @@ async function predictBody(html, mermaidBlocks, pageId, client, ctx) {
   }
   return predicted;
 }
-function validateLocalHierarchy(entries) {
+function validateLocalHierarchy(entries, strategy) {
   const seen = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
+  for (const entryPlan of entries) {
+    const { entry } = entryPlan;
     let parentKey = "";
     for (let index = 0; index < entry.segments.length; index += 1) {
       const segment = entry.segments[index] ?? "";
       const isLast = index === entry.segments.length - 1;
-      const title = isMarkdownName(segment) ? titleFromSegment(segment) : segment;
+      const title = isMarkdownName(segment) ? isLast ? entryPlan.title : pageTitleFromSegments(entry.segments.slice(0, index + 1), strategy) : segment;
       const kind = isLast && isMarkdownName(segment) ? "file" : "dir";
       const key = `${parentKey}::${title}`;
       const existing = seen.get(key);
@@ -1962,8 +2024,10 @@ function validateLocalHierarchy(entries) {
 export {
   ConfluenceApiError,
   ConfluenceClient,
+  DEFAULT_PAGE_TITLE_STRATEGY,
   INTERACTIVE_FLAG,
   LocalSyncValidationAggregateError,
+  PAGE_TITLE_STRATEGIES,
   SyncMutationError,
   escapeAttachmentFilename,
   escapeXmlAttribute,
@@ -1971,10 +2035,12 @@ export {
   isMarkdownName,
   isRemoteUrl,
   markdownToStorage,
+  pageTitleFromSegments,
   preflightImagesToAttachments,
   preflightMermaidBlocks,
   readDocTree,
   resolveConfluenceSyncPlan,
+  resolvePageTitleStrategy,
   resolveConfluenceSyncPlan as resolveSyncPlan,
   rewriteImagesToAttachments,
   rewriteMermaidBlocks,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@repo-toolkit/confluence",
   "description": "Sync a folder of markdown docs to Confluence pages and attachments (GitHub Action compatible)",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "sideEffects": false,
   "keywords": [
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@repo-toolkit/publish-package": "0.19.0"
+    "@repo-toolkit/publish-package": "0.20.0"
   },
   "files": [
     "**/*",