@knpkv/confluence-to-markdown 0.5.0 → 0.7.0

package/src/GitService.ts

@@ -3,17 +3,13 @@
  *
  * @module
  */
-import * as NodeCommandExecutor from "@effect/platform-node/NodeCommandExecutor"
-import * as NodeContext from "@effect/platform-node/NodeContext"
-import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
-import * as NodePath from "@effect/platform-node/NodePath"
-import * as CommandExecutor from "@effect/platform/CommandExecutor"
-import type * as PlatformError from "@effect/platform/Error"
-import * as FileSystem from "@effect/platform/FileSystem"
-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 type * as PlatformError from "effect/PlatformError"
+import { ChildProcessSpawner } from "effect/unstable/process"
 import {
   GitError,
   GitMergeConflictError,
@@ -249,10 +245,10 @@ export interface GitServiceShape {
  *
  * @category Service
  */
-export class GitService extends Context.Tag("@knpkv/confluence-to-markdown/GitService")<
+export class GitService extends Context.Service<
   GitService,
   GitServiceShape
->() {}
+>()("@knpkv/confluence-to-markdown/GitService") {}
 
 /**
  * Map PlatformError to GitError.
@@ -260,13 +256,15 @@ export class GitService extends Context.Tag("@knpkv/confluence-to-markdown/GitSe
 const mapFsError = (error: PlatformError.PlatformError): GitError =>
   new GitError({ command: "filesystem", message: error.message })
 
-// Dependencies layer for git operations (CommandExecutor + FileSystem + Path + NodeContext)
-// NodeCommandExecutor requires FileSystem, so use provideMerge to satisfy its dependencies
-const GitDepsLive = NodeCommandExecutor.layer.pipe(
-  Layer.provideMerge(NodeFileSystem.layer),
-  Layer.provideMerge(NodePath.layer),
-  Layer.provideMerge(NodeContext.layer)
-)
+const existsOrFalse = (
+  effect: Effect.Effect<boolean, PlatformError.PlatformError>
+): Effect.Effect<boolean> =>
+  effect.pipe(
+    Effect.catchIf(
+      (error): error is PlatformError.PlatformError => error._tag === "PlatformError",
+      () => Effect.succeed(false)
+    )
+  )
 
 /**
  * Copy a single file, creating parent directories as needed.
@@ -279,7 +277,7 @@ const copyFileFn = (
 ): Effect.Effect<void, GitError> =>
   Effect.gen(function*() {
     const destDir = pathService.dirname(dest)
-    yield* fs.makeDirectory(destDir, { recursive: true }).pipe(Effect.catchAll(() => Effect.void))
+    yield* fs.makeDirectory(destDir, { recursive: true }).pipe(Effect.mapError(mapFsError))
     yield* fs.copyFile(source, dest).pipe(Effect.mapError(mapFsError))
   })
 
@@ -293,7 +291,7 @@ const copyDirectoryFn = (
   dest: string
 ): Effect.Effect<void, GitError> =>
   Effect.gen(function*() {
-    yield* fs.makeDirectory(dest, { recursive: true }).pipe(Effect.catchAll(() => Effect.void))
+    yield* fs.makeDirectory(dest, { recursive: true }).pipe(Effect.mapError(mapFsError))
 
     const entries = yield* fs.readDirectory(source).pipe(Effect.mapError(mapFsError))
 
@@ -321,7 +319,7 @@ const copyMarkdownFilesFn = (
   dest: string
 ): Effect.Effect<void, GitError> =>
   Effect.gen(function*() {
-    const exists = yield* fs.exists(source).pipe(Effect.catchAll(() => Effect.succeed(false)))
+    const exists = yield* existsOrFalse(fs.exists(source))
     if (!exists) {
       return
     }
@@ -349,7 +347,7 @@ const copyMarkdownFilesFn = (
 
 // Get paths helper - takes pathService as param
 const getPaths = (pathService: Path.Path) => {
-  const cwd = process.cwd()
+  const cwd = pathService.resolve(".")
   const confluenceDir = pathService.join(cwd, ".confluence")
   const gitDir = pathService.join(confluenceDir, ".git")
   return { cwd, confluenceDir, gitDir, pathService }
@@ -358,7 +356,7 @@ const getPaths = (pathService: Path.Path) => {
 // Ensure initialized helper - takes fs and gitDir
 const ensureInitializedFn = (fs: FileSystem.FileSystem, gitDir: string) =>
   Effect.gen(function*() {
-    const initialized = yield* fs.exists(gitDir).pipe(Effect.catchAll(() => Effect.succeed(false)))
+    const initialized = yield* existsOrFalse(fs.exists(gitDir))
     if (!initialized) {
       return yield* Effect.fail(new GitNotInitializedError())
     }
@@ -368,17 +366,18 @@ const ensureInitializedFn = (fs: FileSystem.FileSystem, gitDir: string) =>
 const make = Effect.gen(function*() {
   const fs = yield* FileSystem.FileSystem
   const pathService = yield* Path.Path
-  const commandExecutor = yield* CommandExecutor.CommandExecutor
+  const childProcessSpawner = yield* ChildProcessSpawner.ChildProcessSpawner
   const paths = getPaths(pathService)
   const { confluenceDir, cwd, gitDir } = paths
 
   // Create context with captured services for providing to returned Effects
-  const depsContext: Context.Context<FileSystem.FileSystem | Path.Path | CommandExecutor.CommandExecutor> = Context
-    .empty().pipe(
-      Context.add(FileSystem.FileSystem, fs),
-      Context.add(Path.Path, pathService),
-      Context.add(CommandExecutor.CommandExecutor, commandExecutor)
-    )
+  const depsContext: Context.Context<FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner> =
+    Context
+      .empty().pipe(
+        Context.add(FileSystem.FileSystem, fs),
+        Context.add(Path.Path, pathService),
+        Context.add(ChildProcessSpawner.ChildProcessSpawner, childProcessSpawner)
+      )
 
   // Helper to provide deps to an effect - uses any for R since we know depsContext covers all needs
   const provideDeps = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E> =>
@@ -396,11 +395,7 @@ const make = Effect.gen(function*() {
       )
     )
 
-  const isInitialized = () =>
-    Effect.succeed(fs).pipe(
-      Effect.flatMap((f) => f.exists(gitDir)),
-      Effect.catchAll(() => Effect.succeed(false))
-    )
+  const isInitialized = () => existsOrFalse(fs.exists(gitDir))
 
   const init = () =>
     provideDeps(
@@ -410,12 +405,12 @@ const make = Effect.gen(function*() {
           Effect.catchTag("GitError", () => Effect.fail(new GitNotInstalledError({ message: "Git not found" })))
         )
 
-        const exists = yield* fs.exists(confluenceDir).pipe(Effect.catchAll(() => Effect.succeed(false)))
+        const exists = yield* existsOrFalse(fs.exists(confluenceDir))
         if (!exists) {
           yield* fs.makeDirectory(confluenceDir, { recursive: true }).pipe(Effect.mapError(mapFsError))
         }
 
-        const gitExists = yield* fs.exists(gitDir).pipe(Effect.catchAll(() => Effect.succeed(false)))
+        const gitExists = yield* existsOrFalse(fs.exists(gitDir))
         if (!gitExists) {
           yield* runGit(["init"], confluenceDir)
           // Configure local git user for commits (needed in CI environments)
@@ -583,7 +578,7 @@ const make = Effect.gen(function*() {
             const sourcePath = pathService.join(absoluteDocsPath, pattern)
             const destPath = pathService.join(confluenceDir, pattern)
 
-            const exists = yield* fs.exists(sourcePath).pipe(Effect.catchAll(() => Effect.succeed(false)))
+            const exists = yield* existsOrFalse(fs.exists(sourcePath))
             if (exists) {
               const stat = yield* fs.stat(sourcePath).pipe(Effect.mapError(mapFsError))
               if (stat.type === "Directory") {
@@ -614,7 +609,7 @@ const make = Effect.gen(function*() {
             const sourcePath = pathService.join(confluenceDir, pattern)
             const destPath = pathService.join(absoluteDocsPath, pattern)
 
-            const exists = yield* fs.exists(sourcePath).pipe(Effect.catchAll(() => Effect.succeed(false)))
+            const exists = yield* existsOrFalse(fs.exists(sourcePath))
             if (exists) {
               const stat = yield* fs.stat(sourcePath).pipe(Effect.mapError(mapFsError))
               if (stat.type === "Directory") {
@@ -842,18 +837,13 @@ const make = Effect.gen(function*() {
   })
 })
 
-// Layer with deps - requires FileSystem, Path, CommandExecutor
-const layerWithDeps: Layer.Layer<
-  GitService,
-  never,
-  FileSystem.FileSystem | Path.Path | CommandExecutor.CommandExecutor
-> = Layer.effect(GitService, make)
-
 /**
- * Create GitService layer with all platform dependencies.
+ * Create GitService layer.
  *
  * @category Layers
  */
-export const layer = layerWithDeps.pipe(
-  Layer.provide(GitDepsLive)
-)
+export const layer: Layer.Layer<
+  GitService,
+  never,
+  FileSystem.FileSystem | Path.Path | ChildProcessSpawner.ChildProcessSpawner
+> = Layer.effect(GitService, make)

package/src/LocalFileSystem.ts

@@ -3,11 +3,11 @@
  *
  * @module
  */
-import * as FileSystem from "@effect/platform/FileSystem"
-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 type { ContentHash } from "./Brand.js"
 import type { FrontMatterError } from "./ConfluenceError.js"
 import { FileSystemError } from "./ConfluenceError.js"
@@ -59,9 +59,7 @@ export interface PageTreeNode {
  *
  * @category FileSystem
  */
-export class LocalFileSystem extends Context.Tag(
-  "@knpkv/confluence-to-markdown/LocalFileSystem"
-)<
+export class LocalFileSystem extends Context.Service<
   LocalFileSystem,
   {
     /**
@@ -135,7 +133,7 @@ export class LocalFileSystem extends Context.Tag(
       content: string
     ) => Effect.Effect<void, FileSystemError>
   }
->() {}
+>()("@knpkv/confluence-to-markdown/LocalFileSystem") {}
 
 /**
  * Layer that provides LocalFileSystem.
@@ -180,7 +178,7 @@ export const layer: Layer.Layer<LocalFileSystem, never, FileSystem.FileSystem |
       Effect.gen(function*() {
         const dir = pathService.dirname(filePath)
         yield* fs.makeDirectory(dir, { recursive: true }).pipe(
-          Effect.catchAll(() => Effect.void)
+          Effect.mapError((cause) => new FileSystemError({ operation: "mkdir", path: dir, cause }))
         )
 
         const serialized = serializeMarkdown(frontMatter, content)
@@ -257,7 +255,7 @@ export const layer: Layer.Layer<LocalFileSystem, never, FileSystem.FileSystem |
       Effect.gen(function*() {
         const dir = pathService.dirname(filePath)
         yield* fs.makeDirectory(dir, { recursive: true }).pipe(
-          Effect.catchAll(() => Effect.void)
+          Effect.mapError((cause) => new FileSystemError({ operation: "mkdir", path: dir, cause }))
         )
 
         // Atomic write: write to temp file, then rename
@@ -289,7 +287,7 @@ export const layer: Layer.Layer<LocalFileSystem, never, FileSystem.FileSystem |
       Effect.gen(function*() {
         const dir = pathService.dirname(filePath)
         yield* fs.makeDirectory(dir, { recursive: true }).pipe(
-          Effect.catchAll(() => Effect.void)
+          Effect.mapError((cause) => new FileSystemError({ operation: "mkdir", path: dir, cause }))
         )
 
         const serialized = serializeNewPageMarkdown(frontMatter, content)

package/src/MarkdownConverter.ts

@@ -1,26 +1,30 @@
 /**
- * HTML to Markdown conversion service using AST-based approach.
+ * ADF ↔ Markdown conversion facade.
+ *
+ * Push (markdown → ADF) routes through the official `@atlaskit` markdown
+ * + JSON transformers and is strictly validated by `AdfSchemaValidator` —
+ * we author that side, so schema failures are bugs. Pull (ADF → markdown)
+ * routes through the in-package `AdfWalker`; incoming validation is advisory
+ * (logged, not thrown) because Confluence Cloud routinely emits documents the
+ * canonical schema lags behind.
  *
  * @module
  */
+import type { DocNode } from "@atlaskit/adf-schema"
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
 import * as Schema from "effect/Schema"
-import type { Document } from "./ast/Document.js"
+import { revertPlaceholders } from "./AdfPlaceholders.js"
+import { AdfSchemaValidator } from "./AdfSchemaValidator.js"
+import { walk, type WalkerWarning } from "./AdfWalker.js"
+import { AtlaskitTransformers } from "./AtlaskitTransformers.js"
+import type { AdfSchemaError, AtlaskitTransformersError } from "./ConfluenceError.js"
 import { ConversionError } from "./ConfluenceError.js"
-import { parseConfluenceHtml } from "./parsers/ConfluenceParser.js"
-import { parseMarkdown } from "./parsers/MarkdownParser.js"
-import { ParseError, type SerializeError } from "./SchemaConverterError.js"
-import { ConfluenceToMarkdown, DocumentFromHast, DocumentFromMdast } from "./schemas/ConversionSchema.js"
-import { HastFromHtml } from "./schemas/hast/index.js"
-import { MdastFromMarkdown } from "./schemas/mdast/index.js"
-import { PreprocessedHtmlFromConfluence } from "./schemas/preprocessing/index.js"
-import { serializeToConfluence } from "./serializers/ConfluenceSerializer.js"
-import { type SerializeOptions, serializeToMarkdown } from "./serializers/MarkdownSerializer.js"
 
 /**
- * Markdown conversion service for HTML <-> GFM conversion.
+ * Markdown conversion service. Public surface is two delegating methods —
+ * `adfToMarkdown` (pull) and `markdownToAdf` (push).
  *
  * @example
  * ```typescript
@@ -29,163 +33,124 @@ import { type SerializeOptions, serializeToMarkdown } from "./serializers/Markdo
  *
  * const program = Effect.gen(function* () {
  *   const converter = yield* MarkdownConverter
- *   const md = yield* converter.htmlToMarkdown("<h1>Hello</h1><p>World</p>")
- *   console.log(md) // # Hello\n\nWorld
+ *   const md = yield* converter.adfToMarkdown(adfJson)
  * })
- *
- * Effect.runPromise(
- *   program.pipe(Effect.provide(MarkdownConverter.layer))
- * )
  * ```
  *
  * @category Conversion
  */
-export class MarkdownConverter extends Context.Tag(
-  "@knpkv/confluence-to-markdown/MarkdownConverter"
-)<
+export class MarkdownConverter extends Context.Service<
   MarkdownConverter,
   {
     /**
-     * Convert Confluence storage format (HTML) to GitHub Flavored Markdown.
-     */
-    readonly htmlToMarkdown: (
-      html: string,
-      options?: SerializeOptions
-    ) => Effect.Effect<string, ConversionError>
-
-    /**
-     * Convert GitHub Flavored Markdown to HTML (Confluence storage format).
-     */
-    readonly markdownToHtml: (markdown: string) => Effect.Effect<string, ConversionError>
-
-    /**
-     * Parse Confluence HTML to Document AST.
-     */
-    readonly htmlToAst: (html: string) => Effect.Effect<Document, ParseError>
-
-    /**
-     * Parse Markdown to Document AST.
-     */
-    readonly markdownToAst: (markdown: string) => Effect.Effect<Document, ParseError>
-
-    /**
-     * Serialize Document AST to Confluence HTML.
+     * Convert an ADF JSON document (as wire-format string) to GitHub Flavored
+     * Markdown. Checks against the canonical @atlaskit/adf-schema before
+     * walking; violations are logged as warnings (remote drift), and only a
+     * document too malformed to walk at all fails with ConversionError.
      */
-    readonly astToHtml: (doc: Document) => Effect.Effect<string, SerializeError>
+    readonly adfToMarkdown: (adfJson: string) => Effect.Effect<string, ConversionError>
 
     /**
-     * Serialize Document AST to Markdown.
+     * Convert GitHub Flavored Markdown to a JSON-stringified ADF document.
+     * Routes through the official @atlaskit transformers; validates the
+     * produced ADF against the canonical schema before stringification.
      */
-    readonly astToMarkdown: (doc: Document) => Effect.Effect<string, SerializeError>
+    readonly markdownToAdf: (markdown: string) => Effect.Effect<string, ConversionError>
+  }
+>()("@knpkv/confluence-to-markdown/MarkdownConverter") {}
+
+const warningSummary = (w: WalkerWarning): string => {
+  switch (w._tag) {
+    case "UnsupportedNode":
+      return `${w._tag} ${w.nodeType}`
+    case "LossyMark":
+      return `${w._tag} ${w.mark}`
+    case "MediaWithoutUrl":
+      return `${w._tag} ${w.mediaId}`
+    case "UnsupportedExtension":
+      return `${w._tag} ${w.nodeType} ${w.extensionKey || "?"}`
   }
->() {}
+}
+
+const toConversionError = (
+  direction: "adfToMarkdown" | "markdownToAdf"
+) =>
+(cause: AdfSchemaError | AtlaskitTransformersError | { readonly cause: unknown }): ConversionError =>
+  new ConversionError({ direction, cause })
+
+// The least structure the walker needs: a doc node with a content array.
+// Anything failing this isn't "schema drift", it's not an ADF document —
+// advisory validation must not let it through (walking `null` is a defect;
+// walking `{}` silently produces an empty page).
+const isWalkableDoc = Schema.is(Schema.Struct({
+  type: Schema.Literal("doc"),
+  content: Schema.Array(Schema.Unknown)
+}))
 
 /**
  * Layer that provides the MarkdownConverter service.
  *
  * @category Layers
  */
-export const layer: Layer.Layer<MarkdownConverter> = Layer.succeed(
+export const layer: Layer.Layer<
   MarkdownConverter,
-  MarkdownConverter.of({
-    htmlToMarkdown: (html, options) =>
-      Effect.gen(function*() {
-        // Use AST-based approach to preserve colors, underlines, etc.
-        const doc = yield* parseConfluenceHtml(html).pipe(
-          Effect.mapError((e) => new ConversionError({ direction: "htmlToMarkdown", cause: e.message }))
-        )
-        return yield* serializeToMarkdown(doc, options).pipe(
-          Effect.mapError((e) => new ConversionError({ direction: "htmlToMarkdown", cause: e.message }))
-        )
-      }),
+  never,
+  AtlaskitTransformers | AdfSchemaValidator
+> = Layer.effect(
+  MarkdownConverter,
+  Effect.gen(function*() {
+    const transformers = yield* AtlaskitTransformers
+    const validator = yield* AdfSchemaValidator
 
-    markdownToHtml: (markdown) =>
+    const adfToMarkdown = (adfJson: string): Effect.Effect<string, ConversionError> =>
       Effect.gen(function*() {
-        // Use AST-based approach for consistency
-        const doc = yield* parseMarkdown(markdown).pipe(
-          Effect.mapError((e) => new ConversionError({ direction: "markdownToHtml", cause: e.message }))
-        )
-        return yield* serializeToConfluence(doc).pipe(
-          Effect.mapError((e) => new ConversionError({ direction: "markdownToHtml", cause: e.message }))
+        const raw = yield* Effect.try({
+          try: () => JSON.parse(adfJson),
+          catch: (cause) => new ConversionError({ direction: "adfToMarkdown", cause })
+        })
+        // Incoming validation is advisory: the canonical @atlaskit schema is
+        // routinely stricter than what Confluence Cloud actually emits (old
+        // revisions, experimental nodes), so a failure here usually means
+        // "schema drift", not "broken document". Log + continue. Outgoing
+        // validation stays strict because we control that side.
+        const doc = yield* validator.check(raw, "incoming").pipe(
+          Effect.catchTag("AdfSchemaError", (err) =>
+            isWalkableDoc(raw)
+              ? Effect.gen(function*() {
+                yield* Effect.logWarning(
+                  `adf schema (incoming): ${err.issues.length} issue(s); first: ${
+                    err.issues.slice(0, 3).map((i) =>
+                      `${i.instancePath ?? "?"} ${i.keyword ?? "?"} ${i.message ?? ""}`.trim()
+                    ).join(" | ")
+                  }`
+                )
+                return raw as DocNode
+              })
+              : Effect.fail(toConversionError("adfToMarkdown")(err)))
         )
-      }),
-
-    htmlToAst: (html) => parseConfluenceHtml(html),
-
-    markdownToAst: (markdown) => parseMarkdown(markdown),
-
-    astToHtml: (doc) => serializeToConfluence(doc),
-
-    astToMarkdown: (doc) => serializeToMarkdown(doc)
-  })
-)
-
-/**
- * Schema-based layer for MarkdownConverter using Effect Schema transforms.
- *
- * This is an alternative implementation that uses the new Schema-based
- * conversion pipeline. It provides the same API as the default layer.
- *
- * Note: For full fidelity, continue to use the default layer. This schema-based
- * layer is useful for simpler use cases or when you want to leverage Schema
- * composition.
- *
- * @example
- * ```typescript
- * import { MarkdownConverter, schemaBasedLayer } from "@knpkv/confluence-to-markdown/MarkdownConverter"
- * import { Effect } from "effect"
- *
- * const program = Effect.gen(function* () {
- *   const converter = yield* MarkdownConverter
- *   const md = yield* converter.htmlToMarkdown("<h1>Hello</h1>")
- * })
- *
- * Effect.runPromise(
- *   program.pipe(Effect.provide(schemaBasedLayer))
- * )
- * ```
- *
- * @category Layers
- */
-export const schemaBasedLayer: Layer.Layer<MarkdownConverter> = Layer.succeed(
-  MarkdownConverter,
-  MarkdownConverter.of({
-    // Note: Schema-based layer doesn't support includeRawSource option yet
-    htmlToMarkdown: (html, options) =>
-      Effect.gen(function*() {
-        if (options?.includeRawSource !== undefined) {
-          yield* Effect.logWarning("schemaBasedLayer: includeRawSource option is not supported, use default layer")
+        const { markdown, warnings } = walk(doc)
+        for (const w of warnings) {
+          yield* Effect.logWarning(`adf walker: ${warningSummary(w)}`, w)
         }
-        return yield* Schema.decode(ConfluenceToMarkdown)(html)
-      }).pipe(
-        Effect.mapError((e) => new ConversionError({ direction: "htmlToMarkdown", cause: e.message }))
-      ),
+        return markdown
+      })
 
-    markdownToHtml: (markdown) =>
-      Schema.encode(ConfluenceToMarkdown)(markdown).pipe(
-        Effect.mapError((e) => new ConversionError({ direction: "markdownToHtml", cause: e.message }))
-      ),
-
-    htmlToAst: (html) =>
-      Effect.gen(function*() {
-        const preprocessed = yield* Schema.decode(PreprocessedHtmlFromConfluence)(html)
-        const hast = yield* Schema.decode(HastFromHtml)(preprocessed)
-        return yield* Schema.decode(DocumentFromHast)(hast)
-      }).pipe(
-        Effect.mapError((e) => new ParseError({ source: "confluence", message: e.message }))
-      ),
-
-    markdownToAst: (markdown) =>
+    const markdownToAdf = (markdown: string): Effect.Effect<string, ConversionError> =>
       Effect.gen(function*() {
-        const mdast = yield* Schema.decode(MdastFromMarkdown)(markdown)
-        return yield* Schema.decode(DocumentFromMdast)(mdast)
-      }).pipe(
-        Effect.mapError((e) => new ParseError({ source: "markdown", message: e.message }))
-      ),
-
-    // For serialization, continue using the existing serializers for full fidelity
-    astToHtml: (doc) => serializeToConfluence(doc),
+        const adf = yield* transformers.use(({ json, md }) => json.encode(md.parse(markdown))).pipe(
+          Effect.mapError(toConversionError("markdownToAdf"))
+        )
+        // The walker emits HTML/comment placeholders for Confluence-only nodes
+        // (status, extension). @atlaskit's markdown transformer doesn't know
+        // these, so they come through as plain text. Rewrite them back into
+        // the structured nodes Confluence expects before validation.
+        const reverted = revertPlaceholders(adf)
+        const validated = yield* validator.check(reverted, "outgoing").pipe(
+          Effect.mapError(toConversionError("markdownToAdf"))
+        )
+        return JSON.stringify(validated)
+      })
 
-    astToMarkdown: (doc) => serializeToMarkdown(doc)
+    return MarkdownConverter.of({ adfToMarkdown, markdownToAdf })
   })
 )

package/src/Schemas.ts

@@ -3,6 +3,7 @@
  *
  * @module
  */
+import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
 import { ContentHashSchema, PageIdSchema, SpaceKeySchema } from "./Brand.js"
 
@@ -27,18 +28,18 @@ export const ConfluenceConfigFileSchema = Schema.Struct({
   rootPageId: PageIdSchema,
   /** Confluence Cloud base URL */
   baseUrl: Schema.String.pipe(
-    Schema.pattern(/^https:\/\/[a-z0-9-]+\.atlassian\.net$/)
+    Schema.check(Schema.isPattern(/^https:\/\/[a-z0-9-]+\.atlassian\.net$/))
   ),
   /** Optional space key */
   spaceKey: Schema.optional(SpaceKeySchema),
   /** Local docs path (default: .confluence/docs) */
-  docsPath: Schema.optionalWith(Schema.String, { default: () => ".confluence/docs" }),
+  docsPath: Schema.String.pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(".confluence/docs"))),
   /** Glob patterns to exclude from sync */
-  excludePatterns: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+  excludePatterns: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed([]))),
   /** Save original Confluence HTML alongside markdown (default: false) */
-  saveSource: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  saveSource: Schema.Boolean.pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(false))),
   /** Glob patterns for files to track in git */
-  trackedPaths: Schema.optionalWith(Schema.Array(Schema.String), { default: () => ["**/*.md"] })
+  trackedPaths: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultTypeKey(Effect.succeed(["**/*.md"])))
 })
 
 /**
@@ -71,9 +72,9 @@ export const PageFrontMatterSchema = Schema.Struct({
   /** Confluence page ID */
   pageId: PageIdSchema,
   /** Page version number */
-  version: Schema.Number.pipe(Schema.int(), Schema.positive()),
+  version: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
   /** Page title */
-  title: Schema.String.pipe(Schema.nonEmptyString()),
+  title: Schema.NonEmptyString,
   /** Last updated timestamp (ISO8601) */
   updated: Schema.DateFromString,
   /** Parent page ID (optional) */
@@ -104,7 +105,7 @@ export type PageFrontMatter = Schema.Schema.Type<typeof PageFrontMatterSchema>
  */
 export const NewPageFrontMatterSchema = Schema.Struct({
   /** Page title */
-  title: Schema.String.pipe(Schema.nonEmptyString()),
+  title: Schema.NonEmptyString,
   /** Parent page ID (optional, determined by directory structure) */
   parentId: Schema.optional(PageIdSchema)
 })
@@ -125,9 +126,9 @@ export const SyncStateSchema = Schema.Struct({
   /** Last sync timestamp */
   lastSync: Schema.DateFromString,
   /** Map of page ID to sync info */
-  pages: Schema.Record({
-    key: Schema.String,
-    value: Schema.Struct({
+  pages: Schema.Record(
+    Schema.String,
+    Schema.Struct({
       /** Local file path */
       localPath: Schema.String,
       /** Last synced version */
@@ -135,7 +136,7 @@ export const SyncStateSchema = Schema.Struct({
       /** Content hash at last sync */
       contentHash: ContentHashSchema
     })
-  })
+  )
 })
 
 /**
@@ -163,7 +164,7 @@ export const PageResponseSchema = Schema.Struct({
   }),
   body: Schema.optional(
     Schema.Struct({
-      storage: Schema.optional(
+      atlas_doc_format: Schema.optional(
         Schema.Struct({
           value: Schema.String,
           representation: Schema.optional(Schema.String)
@@ -204,7 +205,7 @@ export const PageListItemSchema = Schema.Struct({
   })),
   body: Schema.optional(
     Schema.Struct({
-      storage: Schema.optional(
+      atlas_doc_format: Schema.optional(
         Schema.Struct({
           value: Schema.String,
           representation: Schema.optional(Schema.String)
@@ -377,7 +378,7 @@ export const PageVersionSchema = Schema.Struct({
       title: Schema.optional(Schema.String),
       body: Schema.optional(
         Schema.Struct({
-          storage: Schema.optional(
+          atlas_doc_format: Schema.optional(
             Schema.Struct({
               value: Schema.String,
               representation: Schema.optional(Schema.String)
@@ -413,7 +414,7 @@ export const PageVersionContentSchema = Schema.Struct({
   /** Page content */
   body: Schema.optional(
     Schema.Struct({
-      storage: Schema.optional(
+      atlas_doc_format: Schema.optional(
         Schema.Struct({
           value: Schema.String,
           representation: Schema.optional(Schema.String)