@knpkv/confluence-to-markdown 0.5.0 → 0.7.0

package/src/commands/layers.ts

@@ -1,11 +1,13 @@
 /**
  * Layer definitions for CLI commands.
  */
-import * as NodeContext from "@effect/platform-node/NodeContext"
 import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient"
+import * as NodeServices from "@effect/platform-node/NodeServices"
 import * as NodeTerminal from "@effect/platform-node/NodeTerminal"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import { layer as AdfSchemaValidatorLayer } from "../AdfSchemaValidator.js"
+import { layer as AtlaskitTransformersLayer } from "../AtlaskitTransformers.js"
 import type { PageId } from "../Brand.js"
 import { ConfluenceAuth, layer as ConfluenceAuthLayer } from "../ConfluenceAuth.js"
 import { ConfluenceClient, type ConfluenceClientConfig, layer as ConfluenceClientLayer } from "../ConfluenceClient.js"
@@ -21,6 +23,11 @@ import { layer as MarkdownConverterLayer } from "../MarkdownConverter.js"
 import { layer as SyncEngineLayer, SyncEngine } from "../SyncEngine.js"
 import { getAuth } from "./shared.js"
 
+const ConverterPipeline = MarkdownConverterLayer.pipe(
+  Layer.provide(AtlaskitTransformersLayer),
+  Layer.provide(AdfSchemaValidatorLayer)
+)
+
 // Dummy config layer for help/init
 const DummyConfigLayer = ConfluenceConfigLayerFromValues({
   rootPageId: "dummy" as PageId,
@@ -35,16 +42,16 @@ const DummyConfigLayer = ConfluenceConfigLayerFromValues({
 const DummyConfluenceClientLayer = Layer.succeed(
   ConfluenceClient,
   ConfluenceClient.of({
-    getPage: () => Effect.dieMessage("Not configured"),
-    getChildren: () => Effect.dieMessage("Not configured"),
-    getAllChildren: () => Effect.dieMessage("Not configured"),
-    createPage: () => Effect.dieMessage("Not configured"),
-    updatePage: () => Effect.dieMessage("Not configured"),
-    deletePage: () => Effect.dieMessage("Not configured"),
-    getPageVersions: () => Effect.dieMessage("Not configured"),
-    getUser: () => Effect.dieMessage("Not configured"),
-    getSpaceId: () => Effect.dieMessage("Not configured"),
-    setEditorVersion: () => Effect.dieMessage("Not configured")
+    getPage: () => Effect.die("Not configured"),
+    getChildren: () => Effect.die("Not configured"),
+    getAllChildren: () => Effect.die("Not configured"),
+    createPage: () => Effect.die("Not configured"),
+    updatePage: () => Effect.die("Not configured"),
+    deletePage: () => Effect.die("Not configured"),
+    getPageVersions: () => Effect.die("Not configured"),
+    getUser: () => Effect.die("Not configured"),
+    getSpaceId: () => Effect.die("Not configured"),
+    setEditorVersion: () => Effect.die("Not configured")
   })
 )
 
@@ -52,15 +59,15 @@ const DummyConfluenceClientLayer = Layer.succeed(
 const DummySyncEngineLayer = Layer.succeed(
   SyncEngine,
   SyncEngine.of({
-    pull: () => Effect.dieMessage("Not configured - run 'confluence clone' first"),
+    pull: () => Effect.die("Not configured - run 'confluence clone' first"),
     push: (_options: { dryRun: boolean; message?: string }) =>
-      Effect.dieMessage("Not configured - run 'confluence clone' first"),
-    status: () => Effect.dieMessage("Not configured - run 'confluence clone' first")
+      Effect.die("Not configured - run 'confluence clone' first"),
+    status: () => Effect.die("Not configured - run 'confluence clone' first")
   })
 )
 
 // Dummy git layer for auth/minimal
-const notConfigured = () => Effect.dieMessage("Not configured - run 'confluence clone' first")
+const notConfigured = () => Effect.die("Not configured - run 'confluence clone' first")
 const DummyGitServiceLayer = Layer.succeed(
   GitService,
   GitService.of({
@@ -100,22 +107,22 @@ const DummyGitServiceLayer = Layer.succeed(
 const DummyConfluenceAuthLayer = Layer.succeed(
   ConfluenceAuth,
   ConfluenceAuth.of({
-    configure: () => Effect.dieMessage("Not configured"),
+    configure: () => Effect.die("Not configured"),
     isConfigured: () => Effect.succeed(false),
-    login: () => Effect.dieMessage("Not configured"),
-    logout: () => Effect.dieMessage("Not configured"),
-    getAccessToken: () => Effect.dieMessage("Not configured"),
-    getCloudId: () => Effect.dieMessage("Not configured"),
+    login: () => Effect.die("Not configured"),
+    logout: () => Effect.die("Not configured"),
+    getAccessToken: () => Effect.die("Not configured"),
+    getCloudId: () => Effect.die("Not configured"),
     getCurrentUser: () => Effect.succeed(null),
     isLoggedIn: () => Effect.succeed(false)
   })
 )
 
 // Auth layer with HTTP client
-const AuthLive = ConfluenceAuthLayer.pipe(Layer.provide(NodeHttpClient.layer))
+const AuthLive = ConfluenceAuthLayer.pipe(Layer.provide(NodeHttpClient.layerFetch))
 
 // Build client layer dynamically based on auth
-const ConfluenceClientLive = Layer.unwrapEffect(
+const ConfluenceClientLive = Layer.unwrap(
   Effect.gen(function*() {
     const auth = yield* getAuth()
     const config = yield* ConfluenceConfig
@@ -136,12 +143,12 @@ export const AppLayer = SyncEngineLayer.pipe(
   Layer.provideMerge(UserCacheLayer),
   Layer.provideMerge(GitServiceLayer),
   Layer.provideMerge(ConfluenceClientLive),
-  Layer.provideMerge(MarkdownConverterLayer),
+  Layer.provideMerge(ConverterPipeline),
   Layer.provideMerge(LocalFileSystemLayer),
   Layer.provideMerge(ConfluenceConfigLayer()),
   Layer.provideMerge(AuthLive),
-  Layer.provideMerge(NodeHttpClient.layer),
-  Layer.provideMerge(NodeContext.layer)
+  Layer.provideMerge(NodeHttpClient.layerFetch),
+  Layer.provideMerge(NodeServices.layer)
 )
 
 /**
@@ -152,11 +159,11 @@ export const AuthOnlyLayer = DummySyncEngineLayer.pipe(
   Layer.provideMerge(DummyGitServiceLayer),
   Layer.provideMerge(DummyConfluenceClientLayer),
   Layer.provideMerge(AuthLive),
-  Layer.provideMerge(MarkdownConverterLayer),
+  Layer.provideMerge(ConverterPipeline),
   Layer.provideMerge(LocalFileSystemLayer),
   Layer.provideMerge(DummyConfigLayer),
-  Layer.provideMerge(NodeHttpClient.layer),
-  Layer.provideMerge(NodeContext.layer)
+  Layer.provideMerge(NodeHttpClient.layerFetch),
+  Layer.provideMerge(NodeServices.layer)
 )
 
 /**
@@ -167,11 +174,11 @@ export const MinimalLayer = DummySyncEngineLayer.pipe(
   Layer.provideMerge(GitServiceLayer),
   Layer.provideMerge(DummyConfluenceClientLayer),
   Layer.provideMerge(DummyConfluenceAuthLayer),
-  Layer.provideMerge(MarkdownConverterLayer),
+  Layer.provideMerge(ConverterPipeline),
   Layer.provideMerge(LocalFileSystemLayer),
   Layer.provideMerge(DummyConfigLayer),
   Layer.provideMerge(NodeTerminal.layer),
-  Layer.provideMerge(NodeContext.layer)
+  Layer.provideMerge(NodeServices.layer)
 )
 
 /**
@@ -182,19 +189,35 @@ export const CloneLayer = DummySyncEngineLayer.pipe(
   Layer.provideMerge(GitServiceLayer),
   Layer.provideMerge(DummyConfluenceClientLayer),
   Layer.provideMerge(AuthLive),
-  Layer.provideMerge(MarkdownConverterLayer),
+  Layer.provideMerge(ConverterPipeline),
+  Layer.provideMerge(LocalFileSystemLayer),
+  Layer.provideMerge(DummyConfigLayer),
+  Layer.provideMerge(NodeHttpClient.layerFetch),
+  Layer.provideMerge(NodeTerminal.layer),
+  Layer.provideMerge(NodeServices.layer)
+)
+
+/**
+ * Fetch layer - needs auth + converter but no config, sync engine, or git workspace.
+ */
+export const FetchLayer = DummySyncEngineLayer.pipe(
+  Layer.provideMerge(UserCacheLayer),
+  Layer.provideMerge(DummyGitServiceLayer),
+  Layer.provideMerge(DummyConfluenceClientLayer),
+  Layer.provideMerge(AuthLive),
+  Layer.provideMerge(ConverterPipeline),
   Layer.provideMerge(LocalFileSystemLayer),
   Layer.provideMerge(DummyConfigLayer),
-  Layer.provideMerge(NodeHttpClient.layer),
+  Layer.provideMerge(NodeHttpClient.layerFetch),
   Layer.provideMerge(NodeTerminal.layer),
-  Layer.provideMerge(NodeContext.layer)
+  Layer.provideMerge(NodeServices.layer)
 )
 
 /**
  * Determine which layer to use based on command.
  */
-export const getLayerType = (): "full" | "auth" | "clone" | "minimal" => {
-  const cmd = process.argv[2]
+export const getLayerType = (argv: ReadonlyArray<string>): "full" | "auth" | "clone" | "fetch" | "minimal" => {
+  const cmd = argv[0]
   // auth commands need auth layer only
   if (cmd === "auth") {
     return "auth"
@@ -203,8 +226,12 @@ export const getLayerType = (): "full" | "auth" | "clone" | "minimal" => {
   if (cmd === "clone") {
     return "clone"
   }
-  // --help, -h, --version don't need config
-  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "--version") {
+  // fetch needs auth + converter but no existing config
+  if (cmd === "fetch") {
+    return "fetch"
+  }
+  // skills/help/version don't need config
+  if (!cmd || cmd === "skills" || cmd === "--help" || cmd === "-h" || cmd === "--version") {
     return "minimal"
   }
   return "full"

package/src/commands/new.ts

@@ -1,10 +1,10 @@
 /**
  * New page command for Confluence CLI.
  */
-import { Command, Prompt } from "@effect/cli"
-import * as Path from "@effect/platform/Path"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
+import * as Path from "effect/Path"
+import { Command, Prompt } from "effect/unstable/cli"
 import { ConfluenceConfig } from "../ConfluenceConfig.js"
 import { LocalFileSystem } from "../LocalFileSystem.js"
 import { flattenPageTree } from "./pageTree.js"
@@ -24,7 +24,8 @@ export const newCommand = Command.make("new", {}, () =>
     const config = yield* ConfluenceConfig
     const pathService = yield* Path.Path
 
-    const docsPath = pathService.join(process.cwd(), config.docsPath)
+    const cwd = pathService.resolve(".")
+    const docsPath = pathService.join(cwd, config.docsPath)
 
     // Build page tree
     yield* Console.log("Scanning page structure...")
@@ -89,7 +90,7 @@ export const newCommand = Command.make("new", {}, () =>
       "\n<!-- Write your page content here -->\n"
     )
 
-    const relativePath = pathService.relative(process.cwd(), filePath)
+    const relativePath = pathService.relative(cwd, filePath)
     yield* Console.log(`Created new page: ${relativePath}`)
     yield* Console.log("")
     yield* Console.log("Next steps:")

package/src/commands/pageInput.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared page input parsing for commands that accept Confluence page IDs.
+ */
+import * as Effect from "effect/Effect"
+import { ConfigError } from "../ConfluenceError.js"
+
+export interface PageInput {
+  readonly url?: string | undefined
+  readonly pageId?: string | undefined
+  readonly baseUrl?: string | undefined
+}
+
+export interface ResolvedPageInput {
+  readonly pageId: string
+  readonly baseUrl: string
+}
+
+const isSupportedHost = (host: string): boolean => /^[a-z0-9-]+\.atlassian\.(?:net|com)$/.test(host)
+
+const isNumericPageId = (segment: string): boolean => /^[0-9]+$/.test(segment)
+
+export const validatePageId = (input: string): Effect.Effect<string, ConfigError> => {
+  const pageId = input.trim()
+  return pageId.length > 0 && isNumericPageId(pageId)
+    ? Effect.succeed(pageId)
+    : Effect.fail(new ConfigError({ message: `Invalid Confluence page ID: ${input}` }))
+}
+
+export const validateBaseUrl = (input: string): Effect.Effect<string, ConfigError> =>
+  Effect.gen(function*() {
+    const url = yield* Effect.try({
+      try: () => new URL(input.trim()),
+      catch: () => new ConfigError({ message: `Invalid Confluence URL: ${input}` })
+    })
+    if (url.protocol !== "https:" || url.pathname !== "/" || !isSupportedHost(url.host)) {
+      return yield* Effect.fail(
+        new ConfigError({
+          message: `Invalid Confluence URL: ${input}. Expected format: https://yoursite.atlassian.net`
+        })
+      )
+    }
+    return `${url.protocol}//${url.host}`
+  })
+
+export const parseConfluencePageUrl = (input: string): Effect.Effect<ResolvedPageInput, ConfigError> =>
+  Effect.gen(function*() {
+    const url = yield* Effect.try({
+      try: () => new URL(input.trim()),
+      catch: () => new ConfigError({ message: `Invalid Confluence page URL: ${input}` })
+    })
+
+    if (url.protocol !== "https:" || !isSupportedHost(url.host)) {
+      return yield* Effect.fail(
+        new ConfigError({
+          message: `Unsupported Confluence page URL: ${input}. Expected an https Atlassian Cloud URL.`
+        })
+      )
+    }
+
+    const segments = url.pathname.split("/").filter((segment) => segment.length > 0)
+    const pagesIndex = segments.indexOf("pages")
+    const pageIdFromPages = pagesIndex >= 0 ? segments[pagesIndex + 1] : undefined
+    const pageId = pagesIndex >= 0
+      ? pageIdFromPages && isNumericPageId(pageIdFromPages) ? pageIdFromPages : undefined
+      : segments.find(isNumericPageId)
+
+    if (!pageId) {
+      return yield* Effect.fail(new ConfigError({ message: `Could not find a page ID in URL: ${input}` }))
+    }
+
+    return {
+      pageId,
+      baseUrl: `${url.protocol}//${url.host}`
+    }
+  })
+
+export const resolvePageInput = (input: PageInput): Effect.Effect<ResolvedPageInput, ConfigError> =>
+  Effect.gen(function*() {
+    const url = input.url?.trim()
+    const pageId = input.pageId?.trim()
+    const baseUrl = input.baseUrl?.trim()
+
+    if (url && (pageId || baseUrl)) {
+      return yield* Effect.fail(
+        new ConfigError({ message: "Use either --url or --page-id/--base-url, not both." })
+      )
+    }
+
+    if (url) {
+      return yield* parseConfluencePageUrl(url)
+    }
+
+    if (!pageId || !baseUrl) {
+      return yield* Effect.fail(
+        new ConfigError({ message: "Both --page-id and --base-url are required when --url is not provided." })
+      )
+    }
+
+    return {
+      pageId: yield* validatePageId(pageId),
+      baseUrl: yield* validateBaseUrl(baseUrl)
+    }
+  })

package/src/commands/root.ts

@@ -0,0 +1,59 @@
+/**
+ * Root CLI command composition.
+ */
+import { makeInstallCommand } from "@knpkv/agent-skills"
+import * as Console from "effect/Console"
+import { Command } from "effect/unstable/cli"
+import {
+  authCommand,
+  cloneCommand,
+  commitCommand,
+  deleteCommand,
+  diffCommand,
+  fetchCommand,
+  logCommand,
+  newCommand,
+  pullCommand,
+  pushCommand,
+  statusCommand
+} from "./index.js"
+
+export interface ConfluenceCommandOptions {
+  readonly fetch?: typeof fetchCommand
+}
+
+const skillsInstall = makeInstallCommand({
+  description: "Install the Confluence agent skill",
+  name: "install",
+  skills: ["confluence"]
+})
+
+const skillsCommand = Command.make(
+  "skills",
+  {},
+  () => Console.log("Usage: confluence skills install")
+).pipe(
+  Command.withDescription("Agent skill commands"),
+  Command.withSubcommands([skillsInstall])
+)
+
+export const makeConfluenceCommand = (options: ConfluenceCommandOptions = {}) =>
+  Command.make("confluence").pipe(
+    Command.withDescription("Sync Confluence pages to local markdown"),
+    Command.withSubcommands([
+      cloneCommand,
+      authCommand,
+      pullCommand,
+      pushCommand,
+      statusCommand,
+      commitCommand,
+      logCommand,
+      diffCommand,
+      options.fetch ?? fetchCommand,
+      newCommand,
+      deleteCommand,
+      skillsCommand
+    ])
+  )
+
+export const confluenceCommand = makeConfluenceCommand()

package/src/commands/sync.ts

@@ -1,10 +1,12 @@
 /**
  * Sync commands (pull, push, status) for Confluence CLI.
  */
-import { Command, Options } from "@effect/cli"
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
+import { Command, Flag as Options } from "effect/unstable/cli"
 import { GitService } from "../GitService.js"
+import { writeStdout } from "../internal/stdio.js"
+import type { ProgressCallback } from "../SyncEngine.js"
 import { SyncEngine } from "../SyncEngine.js"
 
 // === Pull command ===
@@ -24,16 +26,15 @@ export const pullCommand = Command.make(
     Effect.gen(function*() {
       const engine = yield* SyncEngine
       yield* Console.log("Pulling pages from Confluence...")
-      const onProgress = (current: number, total: number, message: string) => {
-        process.stdout.write(`\r  Replaying history: ${current}/${total} - ${message}`)
-      }
+      const onProgress: ProgressCallback = (current, total, message) =>
+        writeStdout(`\r  Replaying history: ${current}/${total} - ${message}`)
       const result = yield* engine.pull({
         force,
         replayHistory,
         ...(replayHistory ? { onProgress } : {})
       })
       if (replayHistory) {
-        process.stdout.write("\r" + " ".repeat(80) + "\r")
+        yield* writeStdout("\r" + " ".repeat(80) + "\r")
       }
       yield* Console.log(`Pulled ${result.pulled} pages`)
       if (result.commits > 0) {
@@ -91,7 +92,7 @@ export const statusCommand = Command.make("status", {}, () =>
       const gitStatus = yield* git.status()
       const commitCount = yield* git.log({ n: 1 }).pipe(
         Effect.map((commits) => commits.length > 0 ? "has commits" : "no commits"),
-        Effect.catchAll(() => Effect.succeed("unknown"))
+        Effect.catchIf(() => true, () => Effect.succeed("unknown"))
       )
       yield* Console.log(`Git: initialized (${commitCount})`)
       if (gitStatus.hasChanges) {

package/src/index.ts

@@ -6,6 +6,9 @@
  * @packageDocumentation
  */
 
+export { AdfSchemaValidator, layer as AdfSchemaValidatorLayer } from "./AdfSchemaValidator.js"
+export { type WalkerWarning, type WalkResult } from "./AdfWalker.js"
+export { AtlaskitTransformers, layer as AtlaskitTransformersLayer, type Transformers } from "./AtlaskitTransformers.js"
 export * from "./Brand.js"
 export { ConfluenceAuth, type ConfluenceAuthService, layer as ConfluenceAuthLayer } from "./ConfluenceAuth.js"
 export {
@@ -35,21 +38,3 @@ export {
   SyncEngine,
   type SyncStatus
 } from "./SyncEngine.js"
-
-// AST types
-export * from "./ast/index.js"
-
-// Parsers
-export { parseConfluenceHtml } from "./parsers/ConfluenceParser.js"
-export { parseMarkdown } from "./parsers/MarkdownParser.js"
-
-// Serializers
-export { serializeToConfluence } from "./serializers/ConfluenceSerializer.js"
-export { serializeToMarkdown } from "./serializers/MarkdownSerializer.js"
-
-// Bi-directional schemas
-export { DocumentFromConfluence } from "./schemas/ConfluenceSchema.js"
-export { DocumentFromMarkdown } from "./schemas/MarkdownSchema.js"
-
-// Schema converter errors
-export { MigrationError, ParseError, SerializeError } from "./SchemaConverterError.js"

package/src/internal/NodeLayers.ts

@@ -1,8 +1,7 @@
 /**
  * Node.js-specific layer implementations.
  *
- * This is the ONLY file that should import directly from node:* modules.
- * All other code should use Effect platform abstractions.
+ * This file wires package-specific Node runtime layers.
  *
  * @module
  * @internal

package/src/internal/adfMetadata.ts

@@ -0,0 +1,145 @@
+/**
+ * External sidecar storage for ADF placeholder metadata.
+ *
+ * Markdown stays readable by replacing large `attrs={...}` / `node={...}`
+ * blobs with `ref=./page.adf.json#id`; the sidecar stores decoded JSON.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+
+export type AdfMetadataKind = "attrs" | "marks" | "node"
+
+export const AdfMetadataEntrySchema = Schema.Struct({
+  kind: Schema.Literals(["attrs", "marks", "node"]),
+  value: Schema.Unknown
+})
+
+export const AdfMetadataSidecarSchema = Schema.Struct({
+  version: Schema.Literal(1),
+  entries: Schema.Record(Schema.String, AdfMetadataEntrySchema)
+})
+
+export type AdfMetadataEntry = typeof AdfMetadataEntrySchema.Type
+export type AdfMetadataSidecar = typeof AdfMetadataSidecarSchema.Type
+
+const stableStringify = (v: unknown): string => {
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`
+  if (v !== null && typeof v === "object") {
+    const entries = Object.entries(v as Record<string, unknown>)
+      .filter(([, value]) => value !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, value]) => `${JSON.stringify(k)}:${stableStringify(value)}`)
+    return `{${entries.join(",")}}`
+  }
+  return JSON.stringify(v) ?? "null"
+}
+
+const markerKinds: ReadonlyArray<AdfMetadataKind> = ["node", "attrs", "marks"]
+
+const markerType = (line: string): string => {
+  const match = /<!--\s*adf:([A-Za-z][A-Za-z0-9]*)/.exec(line)
+  return match?.[1] ?? "metadata"
+}
+
+const fromBase64 = (b64: string): string => {
+  const bin = atob(b64)
+  return new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)))
+}
+
+const parseMetadataValue = (raw: string): unknown | null => {
+  const trimmed = raw.trim()
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed) as unknown
+    } catch {
+      return null
+    }
+  }
+
+  try {
+    const decoded = fromBase64(trimmed)
+    if (!decoded.startsWith("{") && !decoded.startsWith("[")) return null
+    return JSON.parse(decoded) as unknown
+  } catch {
+    return null
+  }
+}
+
+const externalizeLine = (
+  line: string,
+  sidecarHref: string,
+  nextId: (type: string) => string,
+  entries: Record<string, AdfMetadataEntry>
+): string => {
+  if (!line.includes("<!-- adf:") || line.includes("<!-- adf:/")) return line
+  const end = line.lastIndexOf("-->")
+  if (end === -1) return line
+
+  for (const kind of markerKinds) {
+    const needle = ` ${kind}=`
+    const keyStart = line.indexOf(needle)
+    if (keyStart === -1 || keyStart > end) continue
+
+    const valueStart = keyStart + needle.length
+    const raw = line.slice(valueStart, end).trim()
+    const value = parseMetadataValue(raw)
+    if (value === null) return line
+
+    const id = nextId(markerType(line))
+    entries[id] = { kind, value }
+    return `${line.slice(0, keyStart)} ref=${sidecarHref}#${id} ${line.slice(end)}`
+  }
+
+  return line
+}
+
+export const externalizeAdfMetadata = (
+  markdown: string,
+  sidecarHref: string
+): { readonly markdown: string; readonly sidecar: AdfMetadataSidecar | null } => {
+  const entries: Record<string, AdfMetadataEntry> = {}
+  let counter = 0
+  const nextId = (type: string): string => `${type}-${++counter}`
+  const lines = markdown.split("\n").map((line) => externalizeLine(line, sidecarHref, nextId, entries))
+  return {
+    markdown: lines.join("\n"),
+    sidecar: Object.keys(entries).length > 0 ? { version: 1, entries } : null
+  }
+}
+
+export const collectAdfMetadataHrefs = (markdown: string): ReadonlySet<string> => {
+  const hrefs = new Set<string>()
+  for (const line of markdown.split("\n")) {
+    if (!line.includes("<!-- adf:") || !line.includes(" ref=")) continue
+    const end = line.lastIndexOf("-->")
+    const refStart = line.indexOf(" ref=")
+    if (end === -1 || refStart === -1 || refStart > end) continue
+    const rawRef = line.slice(refStart + " ref=".length, end).trim()
+    const href = rawRef.includes("#") ? rawRef.slice(0, rawRef.lastIndexOf("#")) : rawRef
+    if (href.length > 0) hrefs.add(href)
+  }
+  return hrefs
+}
+
+const hydrateLine = (line: string, sidecars: ReadonlyMap<string, AdfMetadataSidecar>): string => {
+  if (!line.includes("<!-- adf:") || !line.includes(" ref=")) return line
+  const end = line.lastIndexOf("-->")
+  const refStart = line.indexOf(" ref=")
+  if (end === -1 || refStart === -1 || refStart > end) return line
+
+  const rawRef = line.slice(refStart + " ref=".length, end).trim()
+  const href = rawRef.includes("#") ? rawRef.slice(0, rawRef.lastIndexOf("#")) : rawRef
+  const id = rawRef.includes("#") ? rawRef.slice(rawRef.lastIndexOf("#") + 1) : rawRef
+  const sidecar = sidecars.get(href)
+  if (!sidecar) return line
+  const entry = sidecar.entries[id]
+  if (!entry) return line
+
+  return `${line.slice(0, refStart)} ${entry.kind}=${stableStringify(entry.value)} ${line.slice(end)}`
+}
+
+export const hydrateAdfMetadata = (
+  markdown: string,
+  sidecars: ReadonlyMap<string, AdfMetadataSidecar>
+): string => markdown.split("\n").map((line) => hydrateLine(line, sidecars)).join("\n")

package/src/internal/cleanMarkdown.ts

@@ -0,0 +1,15 @@
+/**
+ * Remove Confluence round-trip metadata from markdown intended for reading.
+ */
+
+const ADF_COMMENT_PATTERN = /<!--\s*adf:[\s\S]*?-->/g
+
+export const cleanMarkdown = (markdown: string): string => {
+  const cleaned = markdown
+    .replace(ADF_COMMENT_PATTERN, "")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim()
+
+  return cleaned.length > 0 ? `${cleaned}\n` : ""
+}