@knpkv/jira-cli 0.1.1 → 1.0.0

package/src/internal/frontmatter.ts

@@ -9,8 +9,22 @@
  * @internal
  */
 import matter from "gray-matter"
+import * as yaml from "js-yaml"
 import type { Issue } from "../IssueService.js"
 
+/**
+ * `gray-matter` ships a default YAML engine that calls `js-yaml`'s `safeDump`/
+ * `safeLoad`, both removed in `js-yaml` 4. The workspace pins `js-yaml` to 4.x
+ * (security override), so we supply an engine backed by the 4.x `dump`/`load`
+ * API, which is safe by default.
+ *
+ * @internal
+ */
+const yamlEngine = {
+  parse: (str: string): object => (yaml.load(str) as object) ?? {},
+  stringify: (data: object): string => yaml.dump(data)
+}
+
 /**
  * Front-matter data for a Jira issue.
  *
@@ -69,7 +83,7 @@ export const extractFrontMatter = (issue: Issue): IssueFrontMatter => ({
 export const serializeIssue = (issue: Issue): string => {
   const frontMatter = extractFrontMatter(issue)
   const content = buildMarkdownContent(issue)
-  return matter.stringify(content, frontMatter)
+  return matter.stringify(content, frontMatter, { engines: { yaml: yamlEngine } })
 }
 
 /**

package/src/internal/oauthServer.ts

@@ -10,21 +10,20 @@
  *
  * @internal
  */
-import * as HttpRouter from "@effect/platform/HttpRouter"
-import * as HttpServer from "@effect/platform/HttpServer"
-import type { ServeError } from "@effect/platform/HttpServerError"
-import * as HttpServerRequest from "@effect/platform/HttpServerRequest"
-import * as HttpServerResponse from "@effect/platform/HttpServerResponse"
 import { OAuthError } from "@knpkv/atlassian-common/auth"
 import * as Context from "effect/Context"
 import * as Deferred from "effect/Deferred"
 import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
 import * as Fiber from "effect/Fiber"
 import * as Layer from "effect/Layer"
+import * as Scope from "effect/Scope"
+import { HttpRouter, HttpServer, HttpServerResponse } from "effect/unstable/http"
+import type * as HttpServerError from "effect/unstable/http/HttpServerError"
 
 const DEFAULT_PORT = 8585
-const MAX_PORT_ATTEMPTS = 10
-
+const MAX_PORT = 8594
+type HttpServerInstance = Effect.Success<typeof HttpServer.HttpServer>
 /**
  * Factory service for creating HTTP servers.
  * This allows mocking the server creation in tests.
@@ -34,7 +33,7 @@ const MAX_PORT_ATTEMPTS = 10
 export interface HttpServerFactory {
   readonly createServerLayer: (port: number) => Layer.Layer<
     HttpServer.HttpServer,
-    ServeError,
+    HttpServerError.ServeError,
     never
   >
 }
@@ -44,10 +43,10 @@ export interface HttpServerFactory {
  *
  * @category Services
  */
-export class HttpServerFactoryTag extends Context.Tag("@knpkv/jira-cli/HttpServerFactory")<
+export class HttpServerFactoryTag extends Context.Service<
   HttpServerFactoryTag,
   HttpServerFactory
->() {}
+>()("@knpkv/jira-cli/HttpServerFactory") {}
 
 /**
  * Create a HttpServerFactory layer from a layer factory function.
@@ -59,50 +58,12 @@ export class HttpServerFactoryTag extends Context.Tag("@knpkv/jira-cli/HttpServe
  * @category Layers
  */
 export const makeHttpServerFactory = (
-  createLayerFn: (port: number) => Layer.Layer<HttpServer.HttpServer, ServeError, never>
+  createLayerFn: (port: number) => Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError, never>
 ): Layer.Layer<HttpServerFactoryTag> =>
   Layer.succeed(HttpServerFactoryTag, {
     createServerLayer: createLayerFn
   })
 
-/**
- * Check if a port is available by attempting to start a server.
- */
-const isPortAvailable = (port: number): Effect.Effect<boolean, never, HttpServerFactoryTag> =>
-  Effect.gen(function*() {
-    const factory = yield* HttpServerFactoryTag
-    const serverLayer = factory.createServerLayer(port)
-
-    const result = yield* Layer.build(serverLayer).pipe(
-      Effect.scoped,
-      Effect.as(true),
-      Effect.catchAll(() => Effect.succeed(false))
-    )
-    return result
-  })
-
-/**
- * Find an available port starting from the default.
- */
-const findAvailablePort = (): Effect.Effect<number, OAuthError, HttpServerFactoryTag> =>
-  Effect.gen(function*() {
-    for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
-      const port = DEFAULT_PORT + attempt
-      const available = yield* isPortAvailable(port)
-      if (available) {
-        return port
-      }
-    }
-    return yield* Effect.fail(
-      new OAuthError({
-        step: "authorize",
-        cause: `Could not find available port (tried ${DEFAULT_PORT}-${
-          DEFAULT_PORT + MAX_PORT_ATTEMPTS - 1
-        }). Close other applications using these ports.`
-      })
-    )
-  })
-
 /**
  * Result from the OAuth callback server.
  */
@@ -128,15 +89,32 @@ export const startCallbackServer = (
 ): Effect.Effect<CallbackServerResult, OAuthError, HttpServerFactoryTag> =>
   Effect.gen(function*() {
     const factory = yield* HttpServerFactoryTag
-    const port = yield* findAvailablePort()
     const deferred = yield* Deferred.make<string, OAuthError>()
-    const readyDeferred = yield* Deferred.make<void, OAuthError>()
-
-    const app = HttpRouter.empty.pipe(
-      HttpRouter.get(
-        "/callback",
+    const serverScope = yield* Scope.make()
+    const buildServerContext = (port: number): Effect.Effect<
+      { readonly context: Context.Context<HttpServer.HttpServer>; readonly port: number },
+      OAuthError
+    > =>
+      Layer.buildWithScope(factory.createServerLayer(port), serverScope).pipe(
+        Effect.map((context) => ({ context, port })),
+        Effect.catchCause((cause) =>
+          port < MAX_PORT
+            ? buildServerContext(port + 1)
+            : Effect.fail(new OAuthError({ step: "authorize", cause }))
+        )
+      )
+    const { context: serverContext } = yield* buildServerContext(DEFAULT_PORT)
+    const server: HttpServerInstance = Context.get(serverContext, HttpServer.HttpServer)
+    const port = yield* (server.address._tag === "TcpAddress"
+      ? Effect.succeed(server.address.port)
+      : Effect.fail(new OAuthError({ step: "authorize", cause: "OAuth callback server must listen on a TCP port" })))
+
+    const router = yield* HttpRouter.make
+    yield* router.add(
+      "GET",
+      "/callback",
+      (req) =>
         Effect.gen(function*() {
-          const req = yield* HttpServerRequest.HttpServerRequest
           const url = new URL(req.url, `http://localhost:${port}`)
           const code = url.searchParams.get("code")
           const state = url.searchParams.get("state")
@@ -178,26 +156,21 @@ export const startCallbackServer = (
             "<html><body><h1>Success!</h1><p>You can close this window and return to the terminal.</p></body></html>"
           )
         })
-      )
     )
+    const app = router.asHttpEffect()
 
-    const serverLayer = factory.createServerLayer(port)
-
-    const serverFiber = yield* HttpServer.serve(app).pipe(
-      Layer.provide(serverLayer),
-      Layer.build,
-      Effect.tap(() => Deferred.succeed(readyDeferred, undefined)),
-      Effect.tapError((err) => Deferred.fail(readyDeferred, new OAuthError({ step: "authorize", cause: err }))),
-      Effect.flatMap(() => Effect.never),
-      Effect.scoped,
-      Effect.fork
+    const serverFiber = yield* HttpServer.serveEffect(app).pipe(
+      Effect.provide(serverContext),
+      Effect.provideService(Scope.Scope, serverScope),
+      Effect.forkIn(serverScope)
     )
 
-    yield* Deferred.await(readyDeferred)
-
     return {
       codePromise: Deferred.await(deferred),
-      shutdown: Fiber.interrupt(serverFiber).pipe(Effect.asVoid),
+      shutdown: Effect.gen(function*() {
+        yield* Fiber.interrupt(serverFiber)
+        yield* Scope.close(serverScope, Exit.void)
+      }),
       port
     }
   })

package/src/internal/openBrowser.ts

@@ -0,0 +1,31 @@
+/**
+ * Cross-platform browser launcher backed by Effect v4 child process services.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect"
+import type * as PlatformError from "effect/PlatformError"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+
+const run = (
+  command: string,
+  args: ReadonlyArray<string>
+): Effect.Effect<void, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function*() {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+    yield* spawner.exitCode(
+      ChildProcess.make(command, args, {
+        stdin: "ignore",
+        stdout: "ignore",
+        stderr: "ignore"
+      })
+    )
+  })
+
+export const openBrowser = (
+  url: string
+): Effect.Effect<void, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner> =>
+  run("open", [url]).pipe(
+    Effect.catch(() => run("xdg-open", [url])),
+    Effect.catch(() => run("rundll32.exe", ["url.dll,FileProtocolHandler", url]))
+  )

package/src/internal/sync/baseline.ts

@@ -0,0 +1,27 @@
+/**
+ * Sync Baseline helpers.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { SyncValidationError, SyncWorkspaceError } from "../../JiraCliError.js"
+import { SyncBaselineSchema } from "./schemas.js"
+import type { SyncBaseline } from "./types.js"
+
+export const parseSyncBaseline = (
+  path: string,
+  content: string
+): Effect.Effect<SyncBaseline, SyncWorkspaceError | SyncValidationError> =>
+  Effect.gen(function*() {
+    const raw = yield* Effect.try({
+      try: () => JSON.parse(content) as unknown,
+      catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse Sync Baseline JSON", path, cause })
+    })
+    return yield* Schema.decodeUnknownEffect(SyncBaselineSchema)(raw).pipe(
+      Effect.map((baseline) => baseline as SyncBaseline),
+      Effect.mapError((cause) => new SyncValidationError({ message: "Invalid Sync Baseline", path, cause }))
+    )
+  })
+
+export const serializeSyncBaseline = (baseline: SyncBaseline): string => `${JSON.stringify(baseline, null, 2)}\n`

package/src/internal/sync/changes.ts

@@ -0,0 +1,118 @@
+/**
+ * Baseline comparison for Jira Markdown Sync planning.
+ *
+ * @internal
+ */
+import { fieldValuesEqual } from "./fieldValues.js"
+import type {
+  PlannedFieldChange,
+  SyncBaselineFields,
+  SyncFieldPath,
+  SyncFieldValue,
+  SyncValidationFailure
+} from "./types.js"
+
+export interface CompareIssueFieldsInput {
+  readonly issueId: string
+  readonly issueKey: string
+  readonly baseline: SyncBaselineFields
+  readonly jira: SyncBaselineFields
+  readonly document: SyncBaselineFields
+}
+
+export interface CompareIssueFieldsResult {
+  readonly changes: ReadonlyArray<PlannedFieldChange>
+  readonly validationFailures: ReadonlyArray<SyncValidationFailure>
+}
+
+export const compareIssueFields = (input: CompareIssueFieldsInput): CompareIssueFieldsResult => {
+  const changes: Array<PlannedFieldChange> = []
+  const validationFailures: Array<SyncValidationFailure> = []
+
+  compareField(input, "summary", input.baseline.summary, input.jira.summary, input.document.summary, changes)
+  compareField(
+    input,
+    "description",
+    input.baseline.description,
+    input.jira.description,
+    input.document.description,
+    changes
+  )
+  compareField(input, "labels", input.baseline.labels, input.jira.labels, input.document.labels, changes)
+
+  const customFieldNames = new Set([
+    ...Object.keys(input.baseline.customFields),
+    ...Object.keys(input.jira.customFields),
+    ...Object.keys(input.document.customFields)
+  ])
+
+  for (const name of customFieldNames) {
+    const field = `customFields.${name}` as const
+    const baseline = input.baseline.customFields[name]?.value
+    const jira = input.jira.customFields[name]?.value
+    const document = input.document.customFields[name]?.value
+
+    if (baseline === undefined || jira === undefined || document === undefined) {
+      validationFailures.push({
+        _tag: "ValidationFailure",
+        issueKey: input.issueKey,
+        field,
+        message: `Missing reconciled custom field "${name}"`
+      })
+      continue
+    }
+
+    compareField(input, field, baseline, jira, document, changes)
+  }
+
+  return { changes, validationFailures }
+}
+
+const compareField = (
+  input: Pick<CompareIssueFieldsInput, "issueId" | "issueKey">,
+  field: SyncFieldPath,
+  baselineValue: SyncFieldValue,
+  jiraValue: SyncFieldValue,
+  documentValue: SyncFieldValue,
+  changes: Array<PlannedFieldChange>
+) => {
+  const jiraChanged = !syncFieldValueEquals(jiraValue, baselineValue)
+  const documentChanged = !syncFieldValueEquals(documentValue, baselineValue)
+
+  if (!jiraChanged && !documentChanged) return
+
+  if (jiraChanged && !documentChanged) {
+    changes.push({
+      _tag: "RemoteOnly",
+      issueId: input.issueId,
+      issueKey: input.issueKey,
+      field,
+      jiraValue
+    })
+    return
+  }
+
+  if (!jiraChanged && documentChanged) {
+    changes.push({
+      _tag: "LocalOnly",
+      issueId: input.issueId,
+      issueKey: input.issueKey,
+      field,
+      documentValue
+    })
+    return
+  }
+
+  changes.push({
+    _tag: "Conflict",
+    issueId: input.issueId,
+    issueKey: input.issueKey,
+    field,
+    baselineValue,
+    jiraValue,
+    documentValue
+  })
+}
+
+export const syncFieldValueEquals = (left: SyncFieldValue, right: SyncFieldValue): boolean =>
+  fieldValuesEqual(left, right)

package/src/internal/sync/config.ts

@@ -0,0 +1,76 @@
+/**
+ * Workspace Config parsing and serialization.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as yaml from "js-yaml"
+import { SyncValidationError, SyncWorkspaceError } from "../../JiraCliError.js"
+import { WorkspaceConfigSchema } from "./schemas.js"
+import type { WorkspaceConfig } from "./types.js"
+
+export const parseWorkspaceConfig = (
+  path: string,
+  content: string
+): Effect.Effect<WorkspaceConfig, SyncWorkspaceError | SyncValidationError> =>
+  Effect.gen(function*() {
+    const raw = yield* Effect.try({
+      try: () => yaml.load(content) ?? {},
+      catch: (cause) => new SyncWorkspaceError({ message: "Failed to parse workspace config YAML", path, cause })
+    })
+    const config = yield* Schema.decodeUnknownEffect(WorkspaceConfigSchema)(raw).pipe(
+      Effect.map((config) => config as WorkspaceConfig),
+      Effect.mapError((cause) =>
+        new SyncValidationError({ message: "Invalid Jira Markdown Sync workspace config", path, cause })
+      )
+    )
+    yield* validateCustomFieldDeclarations(path, config)
+    return config
+  })
+
+export const serializeWorkspaceConfig = (config: WorkspaceConfig): string => yaml.dump(config, { lineWidth: 100 })
+
+export const makeDefaultWorkspaceConfig = (siteUrl: string): WorkspaceConfig => ({
+  version: 1,
+  siteUrl,
+  documentsDir: "issues",
+  customFields: []
+})
+
+const validateCustomFieldDeclarations = (
+  path: string,
+  config: WorkspaceConfig
+): Effect.Effect<void, SyncValidationError> =>
+  Effect.gen(function*() {
+    const displayNames = new Map<string, number>()
+    const fieldIds = new Set<string>()
+
+    for (const field of config.customFields) {
+      displayNames.set(field.displayName, (displayNames.get(field.displayName) ?? 0) + 1)
+      if (field.fieldId) {
+        if (fieldIds.has(field.fieldId)) {
+          return yield* Effect.fail(
+            new SyncValidationError({
+              message: `Duplicate Requested Custom Field id "${field.fieldId}"`,
+              field: field.displayName,
+              path
+            })
+          )
+        }
+        fieldIds.add(field.fieldId)
+      }
+    }
+
+    for (const field of config.customFields) {
+      if ((displayNames.get(field.displayName) ?? 0) > 1 && !field.fieldId) {
+        return yield* Effect.fail(
+          new SyncValidationError({
+            message: `Duplicate Requested Custom Field "${field.displayName}" must specify fieldId`,
+            field: field.displayName,
+            path
+          })
+        )
+      }
+    }
+  })

package/src/internal/sync/document.ts

@@ -0,0 +1,201 @@
+/**
+ * Parser and serializer for strict Jira Markdown Sync Issue Documents.
+ *
+ * @internal
+ */
+import matter from "gray-matter"
+import * as yaml from "js-yaml"
+import { SyncValidationError } from "../../JiraCliError.js"
+import type {
+  AcceptedComment,
+  AttachmentReference,
+  CommentDraft,
+  IssueDocument,
+  IssueDocumentFrontMatter
+} from "./types.js"
+
+const yamlEngine = {
+  parse: (str: string): object => (yaml.load(str) as object) ?? {},
+  stringify: (data: object): string => yaml.dump(data)
+}
+
+export const DESCRIPTION_SECTION = "Description"
+export const NEW_COMMENTS_SECTION = "New Comments"
+export const COMMENTS_SECTION = "Comments"
+export const ATTACHMENTS_SECTION = "Attachments"
+export const LOCAL_NOTES_SECTION = "Local Notes"
+
+const BUILT_IN_SECTIONS = new Set([
+  DESCRIPTION_SECTION,
+  NEW_COMMENTS_SECTION,
+  COMMENTS_SECTION,
+  ATTACHMENTS_SECTION,
+  LOCAL_NOTES_SECTION
+])
+
+export const serializeIssueDocument = (document: IssueDocument): string => {
+  const body = [
+    `# ${document.frontMatter.issueKey}: ${document.frontMatter.summary}`,
+    "",
+    section(DESCRIPTION_SECTION, document.description),
+    ...Object.entries(document.multilineCustomFields).map(([name, content]) => section(name, content)),
+    section(NEW_COMMENTS_SECTION, serializeCommentDrafts(document.commentDrafts)),
+    section(COMMENTS_SECTION, serializeAcceptedComments(document.acceptedComments)),
+    section(ATTACHMENTS_SECTION, serializeAttachments(document.attachments)),
+    section(LOCAL_NOTES_SECTION, document.localNotes)
+  ].filter((part) => part.length > 0).join("\n")
+
+  return matter.stringify(body, document.frontMatter, { engines: { yaml: yamlEngine } })
+}
+
+export const parseIssueDocument = (path: string, content: string): IssueDocument => {
+  const parsed = matter(content, { engines: { yaml: yamlEngine } })
+  const frontMatter = parseFrontMatter(path, parsed.data)
+  const sections = parseSections(path, parsed.content)
+
+  const description = sections.get(DESCRIPTION_SECTION) ?? fail(path, `Missing ${DESCRIPTION_SECTION} section`)
+  const localNotes = sections.get(LOCAL_NOTES_SECTION) ?? ""
+  const multilineCustomFields = Object.fromEntries(
+    [...sections.entries()].filter(([name]) => !BUILT_IN_SECTIONS.has(name))
+  )
+
+  return {
+    frontMatter,
+    description,
+    multilineCustomFields,
+    commentDrafts: parseCommentDrafts(path, sections.get(NEW_COMMENTS_SECTION) ?? ""),
+    acceptedComments: parseAcceptedComments(sections.get(COMMENTS_SECTION) ?? ""),
+    attachments: parseAttachments(sections.get(ATTACHMENTS_SECTION) ?? ""),
+    localNotes
+  }
+}
+
+const section = (name: string, content: string): string => {
+  const normalized = content.trim()
+  return normalized.length > 0 ? `## ${name}\n\n${normalized}\n` : `## ${name}\n`
+}
+
+const parseFrontMatter = (path: string, data: Record<string, unknown>): IssueDocumentFrontMatter => {
+  const requiredString = (key: string): string => {
+    const value = data[key]
+    if (typeof value !== "string") fail(path, `Missing or invalid front matter field "${key}"`)
+    return value as string
+  }
+
+  const nullableString = (key: string): string | null => {
+    const value = data[key]
+    if (value === null || value === undefined) return null
+    if (typeof value !== "string") fail(path, `Invalid front matter field "${key}"`)
+    return value as string
+  }
+
+  const userValue = (key: string) => {
+    const value = data[key]
+    if (value === null || value === undefined) return null
+    if (typeof value !== "object") fail(path, `Invalid user field "${key}"`)
+    const record = value as Record<string, unknown>
+    if (typeof record["accountId"] !== "string" || typeof record["displayName"] !== "string") {
+      fail(path, `Invalid user field "${key}"`)
+    }
+    return {
+      accountId: record["accountId"] as string,
+      displayName: record["displayName"] as string
+    }
+  }
+
+  const labels = data["labels"]
+  if (!Array.isArray(labels) || labels.some((label) => typeof label !== "string")) {
+    fail(path, `Missing or invalid front matter field "labels"`)
+  }
+
+  const customFields = data["customFields"]
+  if (customFields === null || typeof customFields !== "object" || Array.isArray(customFields)) {
+    fail(path, `Missing or invalid front matter field "customFields"`)
+  }
+
+  return {
+    issueId: requiredString("issueId"),
+    issueKey: requiredString("issueKey"),
+    summary: requiredString("summary"),
+    status: requiredString("status"),
+    issueType: requiredString("issueType"),
+    priority: nullableString("priority"),
+    assignee: userValue("assignee"),
+    reporter: userValue("reporter"),
+    labels: labels as ReadonlyArray<string>,
+    customFields: customFields as IssueDocumentFrontMatter["customFields"]
+  }
+}
+
+const parseSections = (path: string, content: string): Map<string, string> => {
+  const lines = content.split(/\r?\n/)
+  const sections = new Map<string, Array<string>>()
+  let current: string | null = null
+
+  for (const line of lines) {
+    const match = /^## (.+)$/.exec(line)
+    if (match?.[1]) {
+      current = match[1].trim()
+      if (sections.has(current)) fail(path, `Duplicate section "${current}"`)
+      sections.set(current, [])
+    } else if (current) {
+      sections.get(current)?.push(line)
+    }
+  }
+
+  return new Map([...sections.entries()].map(([name, body]) => [name, trimOuterBlankLines(body).join("\n")]))
+}
+
+const serializeCommentDrafts = (drafts: ReadonlyArray<CommentDraft>): string =>
+  drafts.map((draft) => `<!-- draftId: ${draft.draftId} -->\n${draft.body.trim()}`).join("\n\n")
+
+const parseCommentDrafts = (path: string, content: string): ReadonlyArray<CommentDraft> => {
+  if (content.trim().length === 0) return []
+  const parts = content.split(/(?=<!-- draftId: )/g).filter((part) => part.trim().length > 0)
+  return parts.map((part) => {
+    const match = /^<!-- draftId: ([^ ]+) -->\n?([\s\S]*)$/.exec(part.trim())
+    const draftId = match?.[1] ?? fail(path, "Malformed comment draft marker")
+    return { draftId, body: match?.[2]?.trim() ?? "" }
+  })
+}
+
+const serializeAcceptedComments = (comments: ReadonlyArray<AcceptedComment>): string =>
+  comments.map((comment) =>
+    `### ${comment.author} - ${comment.created}\n<!-- jiraCommentId: ${comment.id} -->\n\n${comment.body.trim()}`
+  ).join("\n\n")
+
+const parseAcceptedComments = (content: string): ReadonlyArray<AcceptedComment> => {
+  if (content.trim().length === 0) return []
+  const parts = content.split(/(?=^### )/gm).filter((part) => part.trim().length > 0)
+  return parts.flatMap((part) => {
+    const match = /^### (.+) - (.+)\n<!-- jiraCommentId: ([^ ]+) -->\n?([\s\S]*)$/.exec(part.trim())
+    if (!match?.[1] || !match[2] || !match[3]) return []
+    return [{
+      author: match[1],
+      created: match[2],
+      id: match[3],
+      body: match[4]?.trim() ?? ""
+    }]
+  })
+}
+
+const serializeAttachments = (attachments: ReadonlyArray<AttachmentReference>): string =>
+  attachments.map((attachment) => `- [${attachment.filename}](${attachment.url})`).join("\n")
+
+const parseAttachments = (content: string): ReadonlyArray<AttachmentReference> =>
+  content.split(/\r?\n/).flatMap((line) => {
+    const match = /^- \[(.+)]\((.+)\)$/.exec(line.trim())
+    return match?.[1] && match[2] ? [{ filename: match[1], url: match[2] }] : []
+  })
+
+const trimOuterBlankLines = (lines: ReadonlyArray<string>): ReadonlyArray<string> => {
+  let start = 0
+  let end = lines.length
+  while (start < end && lines[start]?.trim() === "") start++
+  while (end > start && lines[end - 1]?.trim() === "") end--
+  return lines.slice(start, end)
+}
+
+const fail = (path: string, message: string): never => {
+  throw new SyncValidationError({ message, path })
+}