@knpkv/confluence-to-markdown 0.6.0 → 0.7.0

package/dist/SyncEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SyncEngine.d.ts","sourceRoot":"","sources":["../src/SyncEngine.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAA;AAC7C,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACvG,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,KAAK,EAAgD,YAAY,EAAsB,MAAM,cAAc,CAAA;AAElH;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7E;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GACtF;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GACvF;IACA,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B,CAAA;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;AAExF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;IAChC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;CAC1C;AAED,KAAK,SAAS,GACV,QAAQ,GACR,cAAc,GACd,eAAe,GACf,eAAe,GACf,gBAAgB,GAChB,eAAe,GACf,cAAc,CAAA;;IAwBd;;OAEG;mBACY,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC;IAE7E;;OAEG;mBACY,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC;IAEvG;;OAEG;qBACc,MAAM,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC;;AAnCjE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,UAAW,SAAQ,eAoB7B;CAAG;AAEN;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAC7B,UAAU,EACV,KAAK,EACL,gBAAgB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,eAAe,GAAG,IAAI,CAAC,IAAI,GAAG,UAAU,GAAG,SAAS,CA61B/G,CAAA"}
+{"version":3,"file":"SyncEngine.d.ts","sourceRoot":"","sources":["../src/SyncEngine.ts"],"names":[],"mappings":"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"}

package/dist/SyncEngine.js

@@ -3,19 +3,43 @@
  *
  * @module
  */
-import * as Path from "@effect/platform/Path";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
 import { PageId } from "./Brand.js";
 import { ConfluenceClient } from "./ConfluenceClient.js";
 import { ConfluenceConfig } from "./ConfluenceConfig.js";
 import { FileSystemError, StructureError } from "./ConfluenceError.js";
 import { GitService } from "./GitService.js";
+import { AdfMetadataSidecarSchema, collectAdfMetadataHrefs, externalizeAdfMetadata, hydrateAdfMetadata } from "./internal/adfMetadata.js";
+import { parseMarkdown } from "./internal/frontmatter.js";
 import { computeHash, HashServiceLive } from "./internal/hashUtils.js";
 import { UserCache } from "./internal/userCache.js";
 import { LocalFileSystem } from "./LocalFileSystem.js";
 import { MarkdownConverter } from "./MarkdownConverter.js";
+/**
+ * Pretty-print an ADF JSON wire string for the `.source.json` companion file.
+ * Falls back to the raw string if it can't be parsed as JSON.
+ */
+const prettyAdf = (raw) => {
+    try {
+        return JSON.stringify(JSON.parse(raw), null, 2);
+    }
+    catch {
+        return raw;
+    }
+};
+/**
+ * Hash a markdown body in the form `readMarkdownFile` will later return it.
+ * `parseMarkdown` trims the body when reading, so the hash we store on
+ * frontmatter must hash the trimmed body too — otherwise every subsequent
+ * read sees a "changed" file and `push` keeps pushing a no-op update.
+ */
+const hashBody = (markdown) => computeHash(markdown.trim()).pipe(Effect.provide(HashServiceLive));
 /**
  * Sync engine service for Confluence <-> Markdown operations.
  *
@@ -33,7 +57,7 @@ import { MarkdownConverter } from "./MarkdownConverter.js";
  *
  * @category Sync
  */
-export class SyncEngine extends Context.Tag("@knpkv/confluence-to-markdown/SyncEngine")() {
+export class SyncEngine extends Context.Service()("@knpkv/confluence-to-markdown/SyncEngine") {
 }
 /**
  * Layer that provides SyncEngine.
@@ -46,9 +70,48 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
     const converter = yield* MarkdownConverter;
     const localFs = yield* LocalFileSystem;
     const pathService = yield* Path.Path;
+    const fs = yield* FileSystem.FileSystem;
     const git = yield* GitService;
     const userCache = yield* UserCache;
-    const docsPath = pathService.join(process.cwd(), config.docsPath);
+    const cwd = pathService.resolve(".");
+    const docsPath = pathService.join(cwd, config.docsPath);
+    const adfMetadataPath = (filePath, pageId) => pageId
+        ? pathService.join(pathService.dirname(filePath), `${pageId}.adf.json`)
+        : filePath.replace(/\.md$/, ".adf.json");
+    const adfMetadataHref = (filePath, pageId) => `./${pathService.basename(adfMetadataPath(filePath, pageId))}`;
+    const prepareMarkdownForFile = (filePath, markdown, pageId) => externalizeAdfMetadata(markdown, adfMetadataHref(filePath, pageId));
+    const writePreparedMarkdownWithAdfMetadata = (filePath, frontMatter, prepared) => Effect.gen(function* () {
+        yield* localFs.writeMarkdownFile(filePath, frontMatter, prepared.markdown);
+        const sidecarPath = adfMetadataPath(filePath, frontMatter.pageId);
+        if (prepared.sidecar !== null) {
+            yield* localFs.writeFile(sidecarPath, JSON.stringify(prepared.sidecar, null, 2) + "\n");
+        }
+        else if (yield* localFs.exists(sidecarPath)) {
+            yield* localFs.deleteFile(sidecarPath);
+        }
+    });
+    const readAdfMetadataSidecar = (sidecarPath) => Effect.gen(function* () {
+        const exists = yield* localFs.exists(sidecarPath);
+        if (!exists)
+            return null;
+        const raw = yield* fs.readFileString(sidecarPath).pipe(Effect.mapError((cause) => new FileSystemError({ operation: "read", path: sidecarPath, cause })));
+        const parsed = yield* Effect.try({
+            try: () => JSON.parse(raw),
+            catch: (cause) => new FileSystemError({ operation: "read", path: sidecarPath, cause })
+        });
+        return yield* Schema.decodeUnknownEffect(AdfMetadataSidecarSchema)(parsed).pipe(Effect.mapError((cause) => new FileSystemError({ operation: "read", path: sidecarPath, cause })));
+    });
+    const hydrateMarkdownForFile = (filePath, markdown) => Effect.gen(function* () {
+        const sidecars = new Map();
+        const dir = pathService.dirname(filePath);
+        for (const href of collectAdfMetadataHrefs(markdown)) {
+            const sidecarPath = pathService.resolve(dir, href);
+            const sidecar = yield* readAdfMetadataSidecar(sidecarPath);
+            if (sidecar !== null)
+                sidecars.set(href, sidecar);
+        }
+        return hydrateAdfMetadata(markdown, sidecars);
+    });
     /**
      * Build a map of relative path (without .md) to pageId for resolving parents.
      * e.g., "guide" -> pageId, "guide/getting-started" -> pageId
@@ -173,16 +236,16 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
     /**
      * Get user info with caching.
      */
-    const getUser = (accountId) => userCache.getOrFetch(accountId, client.getUser).pipe(Effect.catchAll(() => Effect.succeed(undefined)));
+    const getUser = (accountId) => userCache.getOrFetch(accountId, client.getUser).pipe(Effect.catchCause(() => Effect.succeed(undefined)));
     /**
      * Convert version content to markdown and front-matter.
      */
-    const versionToMarkdown = (pageId, version, title, parentId, position) => Effect.gen(function* () {
-        const htmlContent = version.body?.storage?.value ?? "";
-        const markdown = yield* converter.htmlToMarkdown(htmlContent, {
-            includeRawSource: config.saveSource
-        });
-        const contentHash = yield* computeHash(markdown).pipe(Effect.provide(HashServiceLive));
+    const versionToMarkdown = (filePath, pageId, version, title, parentId, position) => Effect.gen(function* () {
+        const adfJson = version.body?.atlas_doc_format?.value ?? "";
+        const rawMarkdown = yield* converter.adfToMarkdown(adfJson);
+        const prepared = prepareMarkdownForFile(filePath, rawMarkdown, pageId);
+        const { markdown } = prepared;
+        const contentHash = yield* hashBody(markdown);
         // Get author info
         const author = version.authorId ? yield* getUser(version.authorId) : undefined;
         const frontMatter = {
@@ -197,7 +260,7 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
             ...(author?.displayName ? { authorName: author.displayName } : {}),
             ...(author?.email ? { authorEmail: author.email } : {})
         };
-        return { markdown, frontMatter };
+        return { markdown, frontMatter, prepared };
     });
     /**
      * Pull a single page and its children recursively.
@@ -255,10 +318,10 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                 versionIdx++;
                 // Report progress
                 if (options.onProgress) {
-                    options.onProgress(versionIdx, totalVersions, `${fullPage.title} v${versionInfo.number}`);
+                    yield* options.onProgress(versionIdx, totalVersions, `${fullPage.title} v${versionInfo.number}`);
                 }
                 // Check if body content is available from the versions list
-                const bodyContent = versionInfo.page?.body?.storage?.value;
+                const bodyContent = versionInfo.page?.body?.atlas_doc_format?.value;
                 if (!bodyContent) {
                     // No body content available - history replay not supported
                     historyReplayFailed = true;
@@ -271,19 +334,19 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                     createdAt: versionInfo.createdAt,
                     message: versionInfo.message,
                     body: {
-                        storage: {
+                        atlas_doc_format: {
                             value: bodyContent,
-                            representation: "storage"
+                            representation: "atlas_doc_format"
                         }
                     }
                 };
-                const { frontMatter, markdown } = yield* versionToMarkdown(pageId, versionContent, versionInfo.page?.title ?? fullPage.title, effectiveParentId, page.position);
+                const { frontMatter, prepared } = yield* versionToMarkdown(filePath, pageId, versionContent, versionInfo.page?.title ?? fullPage.title, effectiveParentId, page.position);
                 // Write file
-                yield* localFs.writeMarkdownFile(filePath, frontMatter, markdown);
-                // Save source HTML if configured
-                if (config.saveSource && versionContent.body?.storage?.value) {
-                    const sourceFilePath = filePath.replace(/\.md$/, ".html");
-                    yield* localFs.writeFile(sourceFilePath, versionContent.body.storage.value);
+                yield* writePreparedMarkdownWithAdfMetadata(filePath, frontMatter, prepared);
+                // Save source ADF JSON if configured
+                if (config.saveSource && versionContent.body?.atlas_doc_format?.value) {
+                    const sourceFilePath = filePath.replace(/\.md$/, ".source.json");
+                    yield* localFs.writeFile(sourceFilePath, prettyAdf(versionContent.body.atlas_doc_format.value));
                 }
                 // Commit this version
                 const author = versionInfo.authorId ? yield* getUser(versionInfo.authorId) : undefined;
@@ -308,10 +371,8 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                 yield* Effect.logWarning("History replay not available. Confluence Cloud API does not return body content for historical versions. Falling back to simple pull.");
             }
             // Simple pull without history replay
-            const htmlContent = fullPage.body?.storage?.value ?? "";
-            let markdown = yield* converter.htmlToMarkdown(htmlContent, {
-                includeRawSource: config.saveSource
-            });
+            const adfJson = fullPage.body?.atlas_doc_format?.value ?? "";
+            let rawMarkdown = yield* converter.adfToMarkdown(adfJson);
             // Add child page links for index pages
             if (hasChildren && config.spaceKey) {
                 const childLinks = children
@@ -320,9 +381,11 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                     return `- [${child.title}](${pageUrl})`;
                 })
                     .join("\n");
-                markdown = markdown.trim() + "\n\n## Child Pages\n\n" + childLinks + "\n";
+                rawMarkdown = rawMarkdown.trim() + "\n\n## Child Pages\n\n" + childLinks + "\n";
             }
-            const contentHash = yield* computeHash(markdown).pipe(Effect.provide(HashServiceLive));
+            const prepared = prepareMarkdownForFile(filePath, rawMarkdown, pageId);
+            const { markdown } = prepared;
+            const contentHash = yield* hashBody(markdown);
             // Get author info
             const author = fullPage.version.authorId ? yield* getUser(fullPage.version.authorId) : undefined;
             // Write file
@@ -338,11 +401,11 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                 ...(author?.displayName ? { authorName: author.displayName } : {}),
                 ...(author?.email ? { authorEmail: author.email } : {})
             };
-            yield* localFs.writeMarkdownFile(filePath, frontMatter, markdown);
-            // Save source HTML if configured
-            if (config.saveSource && htmlContent) {
-                const sourceFilePath = filePath.replace(/\.md$/, ".html");
-                yield* localFs.writeFile(sourceFilePath, htmlContent);
+            yield* writePreparedMarkdownWithAdfMetadata(filePath, frontMatter, prepared);
+            // Save source ADF JSON if configured
+            if (config.saveSource && adfJson) {
+                const sourceFilePath = filePath.replace(/\.md$/, ".source.json");
+                yield* localFs.writeFile(sourceFilePath, prettyAdf(adfJson));
             }
         }
         // Pull children
@@ -369,28 +432,39 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
             // Switch to origin/confluence to pull updates there
             yield* git.checkout("origin/confluence");
         }
-        const rootPage = yield* client.getPage(config.rootPageId);
-        const result = yield* pullPage(rootPage, docsPath, options, gitInitialized);
-        // If git is initialized and we have changes but didn't replay history, auto-commit
-        if (gitInitialized && !options.replayHistory && result.pulled > 0) {
-            yield* git.addAll();
-            yield* git.commit({
-                message: `Pull from Confluence (${result.pulled} page${result.pulled !== 1 ? "s" : ""})`
-            }).pipe(Effect.catchTag("GitNoChangesError", () => Effect.void));
-        }
-        // Two-branch model: merge origin/confluence into current branch
-        if (hasRemoteBranch && originalBranch && originalBranch !== "origin/confluence") {
-            yield* git.checkout(originalBranch);
-            yield* git.merge("origin/confluence", {
-                message: `Merge remote changes from Confluence`
-            }).pipe(Effect.catchAll(() => Effect.void)); // May fail if no changes
-        }
-        return {
-            pulled: result.pulled,
-            skipped: 0,
-            commits: result.commits,
-            errors: []
-        };
+        const pullAndMerge = Effect.gen(function* () {
+            const rootPage = yield* client.getPage(config.rootPageId);
+            const result = yield* pullPage(rootPage, docsPath, options, gitInitialized);
+            // If git is initialized and we have changes but didn't replay history, auto-commit
+            if (gitInitialized && !options.replayHistory && result.pulled > 0) {
+                yield* git.addAll();
+                yield* git.commit({
+                    message: `Pull from Confluence (${result.pulled} page${result.pulled !== 1 ? "s" : ""})`
+                }).pipe(Effect.catchTag("GitNoChangesError", () => Effect.void));
+            }
+            // Two-branch model: merge origin/confluence into current branch
+            if (hasRemoteBranch && originalBranch && originalBranch !== "origin/confluence") {
+                yield* git.checkout(originalBranch);
+                yield* git.merge("origin/confluence", {
+                    message: `Merge remote changes from Confluence`
+                }).pipe(Effect.catchIf(() => true, () => Effect.void)); // May fail if no changes
+            }
+            return {
+                pulled: result.pulled,
+                skipped: 0,
+                commits: result.commits,
+                errors: []
+            };
+        });
+        // Any failure after the origin/confluence checkout (API, conversion,
+        // git) must not strand the repo on a detached HEAD — same protection
+        // as findUnpushedCommits. On success this re-checkout is a no-op.
+        // The restore itself can fail (a half-written pull leaves dirty files
+        // that differ between branches); that must be loud, not swallowed.
+        return yield* pullAndMerge.pipe(Effect.ensuring(hasRemoteBranch && originalBranch
+            ? git.checkout(originalBranch).pipe(Effect.catchCause((cause) => Effect.logWarning(`pull: could not restore branch '${originalBranch}' — the repo may still be on origin/confluence. ` +
+                `Restore manually with \`git checkout ${originalBranch}\` (stash local changes first if needed). Cause: ${String(cause)}`)))
+            : Effect.void));
     });
     /**
      * Push a single file's content to Confluence.
@@ -405,42 +479,36 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
             const baseName = pathService.basename(filePath, ".md");
             // For new pages, re-parse front-matter to get title
             // The localFile only has the content (body), not the original front-matter
-            const title = yield* Effect.tryPromise({
-                try: async () => {
-                    const fs = await import("node:fs/promises");
-                    const matter = await import("gray-matter");
-                    const rawFile = await fs.readFile(filePath, "utf-8");
-                    const parsed = matter.default(rawFile);
-                    return parsed.data.title ?? baseName;
-                },
-                catch: (cause) => new FileSystemError({ operation: "read", path: filePath, cause })
-            });
+            const rawFile = yield* fs.readFileString(filePath).pipe(Effect.mapError((cause) => new FileSystemError({ operation: "read", path: filePath, cause })));
+            const parsed = yield* parseMarkdown(filePath, rawFile);
+            const title = parsed.frontMatter?.title ?? baseName;
             // Resolve parent from directory structure
             const parentId = yield* resolveParent(filePath, pageIdMap);
-            // Convert markdown to HTML
-            const html = yield* converter.markdownToHtml(localFile.content);
+            // Convert markdown to ADF
+            const hydratedContent = yield* hydrateMarkdownForFile(filePath, localFile.content);
+            const adfValue = yield* converter.markdownToAdf(hydratedContent);
             // Create the page
             const createdPage = yield* client.createPage({
                 spaceId,
                 parentId,
                 title,
                 body: {
-                    representation: "storage",
-                    value: html
+                    representation: "atlas_doc_format",
+                    value: adfValue
                 }
             });
             // Set editor version to v2 (new editor)
-            yield* client.setEditorVersion(createdPage.id, "v2").pipe(Effect.catchAll((error) => {
+            yield* client.setEditorVersion(createdPage.id, "v2").pipe(Effect.catchIf(() => true, (error) => {
                 // Log warning but don't fail the push
                 return Effect.logWarning(`Failed to set editor v2 for page ${createdPage.id}: ${error.message}`);
             }));
             // Fetch canonical content back from Confluence
             const canonicalPage = yield* client.getPage(createdPage.id);
-            const canonicalHtml = canonicalPage.body?.storage?.value ?? "";
-            const canonicalMarkdown = yield* converter.htmlToMarkdown(canonicalHtml, {
-                includeRawSource: config.saveSource
-            });
-            const canonicalHash = yield* computeHash(canonicalMarkdown).pipe(Effect.provide(HashServiceLive));
+            const canonicalAdf = canonicalPage.body?.atlas_doc_format?.value ?? "";
+            const rawCanonicalMarkdown = yield* converter.adfToMarkdown(canonicalAdf);
+            const preparedCanonicalMarkdown = prepareMarkdownForFile(filePath, rawCanonicalMarkdown, createdPage.id);
+            const { markdown: canonicalMarkdown } = preparedCanonicalMarkdown;
+            const canonicalHash = yield* hashBody(canonicalMarkdown);
             // Write canonical content with full front-matter
             const newFrontMatter = {
                 pageId: createdPage.id,
@@ -450,7 +518,7 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                 parentId: parentId,
                 contentHash: canonicalHash
             };
-            yield* localFs.writeMarkdownFile(filePath, newFrontMatter, canonicalMarkdown);
+            yield* writePreparedMarkdownWithAdfMetadata(filePath, newFrontMatter, preparedCanonicalMarkdown);
             // Update pageIdMap with new page
             const key = relativePath.replace(/\.md$/, "");
             pageIdMap.set(key, createdPage.id);
@@ -463,7 +531,8 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
         }
         // Fetch current version to avoid conflicts
         const remotePage = yield* client.getPage(fm.pageId);
-        const html = yield* converter.markdownToHtml(localFile.content);
+        const hydratedContent = yield* hydrateMarkdownForFile(filePath, localFile.content);
+        const adfValue = yield* converter.markdownToAdf(hydratedContent);
         const updatedPage = yield* client.updatePage({
             id: fm.pageId,
             title: fm.title,
@@ -473,17 +542,17 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                 message: revisionMessage
             },
             body: {
-                representation: "storage",
-                value: html
+                representation: "atlas_doc_format",
+                value: adfValue
             }
         });
         // Fetch canonical content back from Confluence
         const canonicalPage = yield* client.getPage(fm.pageId);
-        const canonicalHtml = canonicalPage.body?.storage?.value ?? "";
-        const canonicalMarkdown = yield* converter.htmlToMarkdown(canonicalHtml, {
-            includeRawSource: config.saveSource
-        });
-        const canonicalHash = yield* computeHash(canonicalMarkdown).pipe(Effect.provide(HashServiceLive));
+        const canonicalAdf = canonicalPage.body?.atlas_doc_format?.value ?? "";
+        const rawCanonicalMarkdown = yield* converter.adfToMarkdown(canonicalAdf);
+        const preparedCanonicalMarkdown = prepareMarkdownForFile(filePath, rawCanonicalMarkdown, fm.pageId);
+        const { markdown: canonicalMarkdown } = preparedCanonicalMarkdown;
+        const canonicalHash = yield* hashBody(canonicalMarkdown);
         // Write canonical content with updated front-matter
         const newFrontMatter = {
             ...fm,
@@ -491,7 +560,7 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
             updated: new Date(canonicalPage.version.createdAt ?? new Date().toISOString()),
             contentHash: canonicalHash
         };
-        yield* localFs.writeMarkdownFile(filePath, newFrontMatter, canonicalMarkdown);
+        yield* writePreparedMarkdownWithAdfMetadata(filePath, newFrontMatter, preparedCanonicalMarkdown);
         return { pushed: true, created: false };
     });
     /**
@@ -514,30 +583,37 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
         const allCommits = yield* git.log({ n: 100 });
         if (allCommits.length === 0)
             return [];
-        const unpushed = [];
-        for (const commit of allCommits) {
-            yield* git.checkout(commit.hash);
-            let hasChanges = false;
-            for (const filePath of files) {
-                const exists = yield* localFs.exists(filePath);
-                if (!exists)
-                    continue;
-                const localFile = yield* localFs.readMarkdownFile(filePath);
-                if (!localFile.frontMatter) {
-                    hasChanges = true;
-                    break;
+        // We checkout each commit to compare content; restore HEAD before returning
+        // so subsequent pushFile() calls see the working-tree content the user staged,
+        // not whatever commit we last inspected.
+        const originalBranch = yield* git.getCurrentBranch();
+        const collect = Effect.gen(function* () {
+            const unpushed = [];
+            for (const commit of allCommits) {
+                yield* git.checkout(commit.hash);
+                let hasChanges = false;
+                for (const filePath of files) {
+                    const exists = yield* localFs.exists(filePath);
+                    if (!exists)
+                        continue;
+                    const localFile = yield* localFs.readMarkdownFile(filePath);
+                    if (!localFile.frontMatter) {
+                        hasChanges = true;
+                        break;
+                    }
+                    const currentHash = yield* computeHash(localFile.content).pipe(Effect.provide(HashServiceLive));
+                    if (currentHash !== localFile.frontMatter.contentHash) {
+                        hasChanges = true;
+                        break;
+                    }
                 }
-                const currentHash = yield* computeHash(localFile.content).pipe(Effect.provide(HashServiceLive));
-                if (currentHash !== localFile.frontMatter.contentHash) {
-                    hasChanges = true;
+                if (!hasChanges)
                     break;
-                }
+                unpushed.push({ hash: commit.hash, message: commit.message });
             }
-            if (!hasChanges)
-                break;
-            unpushed.push({ hash: commit.hash, message: commit.message });
-        }
-        return unpushed.reverse();
+            return unpushed.reverse();
+        });
+        return yield* collect.pipe(Effect.ensuring(originalBranch ? git.checkout(originalBranch).pipe(Effect.ignore) : Effect.void));
     });
     const push = (options) => Effect.gen(function* () {
         // Validate structure before push
@@ -564,7 +640,7 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                     pushed++;
                     continue;
                 }
-                const result = yield* pushFile(filePath, options.message ?? "Updated via confluence-to-markdown", spaceId, pageIdMap).pipe(Effect.catchAll((error) => Effect.succeed({
+                const result = yield* pushFile(filePath, options.message ?? "Updated via confluence-to-markdown", spaceId, pageIdMap).pipe(Effect.catchIf(() => true, (error) => Effect.succeed({
                     pushed: false,
                     created: false,
                     error: `Failed: ${error._tag}`
@@ -615,9 +691,9 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
                 const pageIdFromOrigin = yield* git.getFileContentAt("origin/confluence", deletedPath).pipe(Effect.map((content) => {
                     const match = content.match(/pageId:\s*['"]?(\d+)['"]?/);
                     return match ? match[1] : null;
-                }), Effect.catchAll(() => Effect.succeed(null)));
+                }), Effect.catchIf(() => true, () => Effect.succeed(null)));
                 if (pageIdFromOrigin) {
-                    yield* client.deletePage(PageId(pageIdFromOrigin)).pipe(Effect.tap(() => Effect.sync(() => deleted++)), Effect.catchAll((error) => {
+                    yield* client.deletePage(PageId(pageIdFromOrigin)).pipe(Effect.tap(() => Effect.sync(() => deleted++)), Effect.catchIf(() => true, (error) => {
                         errors.push(`Failed to delete page ${pageIdFromOrigin}: ${error.message}`);
                         return Effect.void;
                     }));
@@ -625,7 +701,7 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
             }
         }
         for (const filePath of sortedFiles) {
-            const result = yield* pushFile(filePath, revisionMessage, spaceId, pageIdMap).pipe(Effect.catchAll((error) => Effect.succeed({
+            const result = yield* pushFile(filePath, revisionMessage, spaceId, pageIdMap).pipe(Effect.catchIf(() => true, (error) => Effect.succeed({
                 pushed: false,
                 created: false,
                 error: `Failed to push ${filePath}: ${error._tag}`
@@ -639,7 +715,7 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
         }
         // Amend the last commit with canonical content
         yield* git.addAll();
-        yield* git.amend({ noEdit: true }).pipe(Effect.catchAll(() => Effect.void));
+        yield* git.amend({ noEdit: true }).pipe(Effect.catchIf(() => true, () => Effect.void));
         // Two-branch model: update origin/confluence to match HEAD
         if (hasRemoteBranch) {
             yield* git.updateBranch("origin/confluence", "HEAD");
@@ -665,13 +741,13 @@ export const layer = Layer.effect(SyncEngine, Effect.gen(function* () {
             const fm = localFile.frontMatter;
             const currentHash = yield* computeHash(localFile.content).pipe(Effect.provide(HashServiceLive));
             // Fetch remote page
-            const remotePage = yield* Effect.either(client.getPage(fm.pageId));
-            if (remotePage._tag === "Left") {
+            const remotePage = yield* Effect.result(client.getPage(fm.pageId));
+            if (Result.isFailure(remotePage)) {
                 statuses.push({ _tag: "LocalOnly", path: filePath, title: fm.title });
                 localOnly++;
                 continue;
             }
-            const page = remotePage.right;
+            const page = remotePage.success;
             const localChanged = currentHash !== fm.contentHash;
             const remoteChanged = page.version.number > fm.version;
             if (localChanged && remoteChanged) {