Write down what the converter must be, before any of it is built

AGENTS.md

@@ -0,0 +1,69 @@
+# Working in this repo
+
+Decisions that a reader would otherwise relitigate. Everything about *using* the library is in
+`README.md`; what is still to build, and what is still undecided, is in `todo.md`.
+
+## 1. Two formats, never three
+
+ADF and one markdown flavour. **No HTML** — not as an output, not as an intermediate, not as a
+convenience export. A consumer that wants HTML renders the markdown itself, with its own escaping
+and its own stylesheet; a consumer that wants neither shows the markdown verbatim, which is what the
+first one does.
+
+Three formats would mean six directions to keep lossless instead of two.
+
+## 2. The round-trip is the product
+
+`markdownToAdf(adfToMarkdown(doc))` must equal `doc`. Anything less and a consumer that lets someone
+edit a ticket destroys what it could not represent — a panel, a mention, an attachment — in a
+document it did not author.
+
+That is why the flavour is *extended*: markdown has no syntax for most of what ADF holds, so the
+flavour invents it. Designing that syntax is the first real task, and it is open (`todo.md`).
+
+Two consequences to settle before any node is implemented, not after:
+
+- **What happens to a node the library does not know.** The documented ADF node set is not the whole
+  schema, and Atlassian adds to it. Whether an unknown node is carried opaquely, refused, or dropped
+  is a correctness decision for the whole library, and it decides the return shape of both functions.
+- **Whether a lossless document must stay readable to a plain markdown reader.** Anything the flavour
+  invents is noise to a reader that does not know it. How much noise is acceptable bounds the syntax.
+
+Round-trip equality is a property to test over a corpus, not a claim to make in prose.
+
+## 3. Zero runtime dependencies
+
+Nothing in `dependencies`, ever. TypeScript and whatever the tests need are `devDependencies`, and
+they never reach a consumer. A markdown parser is exactly the dependency this rule exists to refuse:
+the flavour is not CommonMark, so a general parser would have to be extended into one anyway.
+
+## 4. The package contract
+
+- **ESM only.** No CommonJS build, no dual-package hazard.
+- **Two entrypoints.** The built JavaScript for ordinary consumers, and the TypeScript source for
+  consumers that run TypeScript directly through Node's type stripping — the first consumer is one,
+  which is why this exists.
+- **Types for both.** The JavaScript entrypoint ships `.d.ts` beside it; the TypeScript entrypoint is
+  its own types.
+- **Published to public npmjs as `@larvit/atlassian-adf-converter`**, matching `@larvit/log`. Public
+  means the source is public: the Gitea repo starts private, and going public — with the LICENSE in
+  place — is a step before the first publish, not after it.
+- **Exact versions.** `save-exact=true` in `.npmrc`, as in every other repo here.
+
+## 5. Nothing about any consumer
+
+No Jira, no HTTP, no REST response shapes, no plainpages, no issue keys. The library takes a document
+tree and returns a string, or the reverse. A consumer's concern that leaks in here is a seam nobody
+declared — and the reason this is a library at all rather than a file in the client that needed it.
+
+## 6. Tests first, in Docker
+
+Write the test for the behaviour wanted, then implement until it passes. `node --test`, beside the
+code. Node, tsc and npm never run on the host — a compose service or a `docker run` against a
+**full patch version** image tag (`node:24.19.0-alpine3.24`, never `node:24`), so the same commit
+builds the same thing on a different day.
+
+## 7. Style
+
+Two-space indent, alphabetically sorted object keys, strict TypeScript. Failures are values, not
+exceptions: a function that both returns a result and throws for some inputs has two error channels.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Larv IT AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,42 @@
+# @larvit/atlassian-adf-converter
+
+Lossless conversion between **Atlassian Document Format** (ADF) and an extended markdown flavour
+that can carry the nodes plain markdown has no syntax for.
+
+**Status: specification only. No code is implemented yet.** `todo.md` holds the plan and the design
+questions still open; `AGENTS.md` holds the decisions already made.
+
+## What it is for
+
+Jira Cloud's REST v3 API hands out issue descriptions and comment bodies as ADF — a JSON node tree,
+ProseMirror-shaped — and takes them back the same way. There is no Atlassian endpoint that converts
+it: `pf-editor-service/convert` was decommissioned and
+[JRACLOUD-77436](https://jira.atlassian.com/browse/JRACLOUD-77436) is still an open request. The npm
+ecosystem covers one direction each, drops what markdown cannot express, and none of it round-trips.
+
+A client that shows a ticket and lets someone edit it needs both directions, and needs them
+lossless — otherwise saving an edit silently destroys the panels, mentions and attachments that were
+in someone else's ticket. That is what this library is.
+
+## The intended shape
+
+Two pure functions and their types. No I/O, no network, no configuration:
+
+```ts
+adfToMarkdown(document: AdfDocument): string
+markdownToAdf(markdown: string): AdfDocument
+```
+
+The published package is ESM only, has **no runtime dependencies**, and offers two entrypoints — the
+built JavaScript for ordinary consumers, and the TypeScript source for consumers that run TypeScript
+directly (Node's type stripping), with exported types either way. `AGENTS.md` §4 has the contract.
+
+## The first consumer
+
+[`plainpages-plugin-fastjira`](https://gitea.larvit.se/larvit/plainpages-plugin-fastjira) — a
+server-rendered Jira client. Its read-only ticket view shows the markdown this library produces
+verbatim, with no HTML rendering anywhere; its later write paths post back what this library
+converts the other way. **That view is blocked on `0.1.0`,** and it needs `adfToMarkdown` first.
+
+The library knows nothing about that consumer. No Jira, no HTTP, no REST shapes, no plainpages — a
+document tree in, a string out, and the reverse.

todo.md

@@ -0,0 +1,57 @@
+# Todo
+
+The plan, in order. Nothing here is built yet.
+
+## Open design questions — settle these first
+
+None of them have an answer yet, and each one changes what every later milestone implements.
+
+- [ ] **The flavour's syntax.** Markdown has no syntax for most of ADF. Every node in the inventory
+      below that is not plain markdown needs one, and the set has to be internally consistent rather
+      than invented node by node. Prior art worth reading before choosing: CommonMark's generic
+      directives proposal, MDX, Obsidian's and Pandoc's extensions, and what Atlassian's own
+      `editor-markdown-transformer` does (it is lossy — read it for the failure modes, not the design).
+- [ ] **The unknown-node policy** (AGENTS.md §2). Carried opaquely, refused, or dropped — it decides
+      the return shape of both functions, so it cannot be retrofitted.
+- [ ] **How readable a converted document must stay** to a reader that does not know the flavour.
+- [ ] **Whether plain CommonMark is valid input** to `markdownToAdf`. A human typing ordinary
+      markdown into a comment box is the second consumer's whole write path.
+- [ ] **Table fidelity.** ADF tables carry column widths, colspan, rowspan, header rows and cell
+      background colours; markdown tables carry none of it.
+- [ ] **Identity-bearing nodes.** `mention` holds an account id, `media` an attachment id, `emoji` a
+      shortcode plus an id. The rendered text is not enough to reconstruct them, so the syntax has to
+      carry the id — and then a document is only portable within the site it came from.
+
+## Milestones
+
+- [ ] **0 — Scaffold.** `package.json` with the §4 contract, `tsconfig.json`, `.npmrc`, LICENSE (MIT,
+      Larv IT AB), the Docker tooling setup, and `.gitea/workflows/ci.yml` gating branches. Mirror
+      `plainpages` for the workflow shape: `runs-on: docker-host`, actions pinned to semver tags.
+- [ ] **1 — Settle the flavour.** Write the syntax down as this repo's specification before
+      implementing it, and make the round-trip corpus from it.
+- [ ] **2 — `adfToMarkdown`.** The direction the first consumer needs. Ships `0.1.0`.
+- [ ] **3 — `markdownToAdf`.**
+- [ ] **4 — Round-trip property tests** over a corpus of real Jira documents, both ways. Not a
+      milestone that follows 2 and 3 so much as the thing that proves them.
+- [ ] **5 — Release pipeline.** Tag-triggered publish to public npmjs, `NPM_TOKEN` secret, the repo
+      made public with the LICENSE in place first (AGENTS.md §4).
+
+## The ADF inventory to cover
+
+From Atlassian's [structure
+reference](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/). **It is
+not the whole schema** — real payloads also carry `taskList`/`taskItem`, `decisionList`/`decisionItem`,
+`layoutSection`/`layoutColumn`, `blockCard`/`embedCard`, `extension`/`bodiedExtension`/`inlineExtension`
+and `placeholder`, none of which are documented there. Treat the documented set as the floor, not the
+ceiling, and see the unknown-node policy above.
+
+| | |
+| --- | --- |
+| Top-level block | `blockquote` `bodiedSyncBlock` `bulletList` `codeBlock` `expand` `heading` `mediaGroup` `mediaSingle` `multiBodiedExtension` `orderedList` `panel` `paragraph` `rule` `syncBlock` `table` |
+| Child block | `blockTaskItem` `extensionFrame` `listItem` `media` `nestedExpand` `tableCell` `tableHeader` `tableRow` |
+| Inline | `date` `emoji` `hardBreak` `inlineCard` `mediaInline` `mention` `status` `text` |
+| Marks | `border` `code` `em` `link` `strike` `strong` `subsup` `textColor` `underline` |
+
+Plain markdown already covers `blockquote`, `bulletList`, `codeBlock`, `heading`, `orderedList`,
+`paragraph`, `rule`, `listItem`, `hardBreak`, `text`, and the `code`, `em`, `link`, `strike` and
+`strong` marks. Everything else is what the flavour is for.