atlass 1.1.0 → 1.3.0

package/README.md

@@ -1,10 +1,12 @@
 # atlass
 
-CLI to copy Jira issues and Confluence pages to Markdown.
+CLI to copy Jira issues and Confluence pages to Markdown, and push edits back to
+Confluence.
 
 Fetches an issue or page from Atlassian Cloud, converts its rich content to
 Markdown, writes a `.md` file with YAML frontmatter, and downloads any
-attachments alongside it.
+attachments alongside it. Confluence pages can be edited locally and updated
+back on the server.
 
 ## Install
 
@@ -61,6 +63,40 @@ atlass jira copy            # prompts for the key or URL
 Accepts an issue key or any URL containing one. Writes `PROJ-123.md` to the
 current directory.
 
+### Update a Jira issue
+
+Copy an issue, edit the Markdown, then push the description back:
+
+```bash
+atlass jira update PROJ-123.md
+atlass jira update                     # prompts for the file path
+atlass jira update file.md --dry-run   # show what would change, write nothing
+atlass jira update file.md --summary   # also push the H1 as the issue summary
+```
+
+The issue key comes from the file's frontmatter. The body is everything between
+the H1 and the `## Comments` section; the frontmatter, the H1, and the
+`## Comments` / `## Attachments` sections are not sent.
+
+Only the description is updated by default. Pass `--summary` to also push the H1
+as the new issue summary.
+
+Notes and safety:
+
+- The body is converted from Markdown to ADF. Only the standard constructs the
+  copy produces round-trip (headings, lists, task lists, code, blockquotes,
+  tables, rules, inline marks, links). Jira-specific content (panels, macros)
+  was flattened to plain Markdown on copy and cannot be rebuilt. When the live
+  description still contains such content, the update warns and asks for
+  confirmation before overwriting.
+- Jira has no page-style version number, so staleness is checked against the
+  frontmatter `updated` timestamp. If the issue changed since you copied it, the
+  update aborts so you can re-copy. `--force` overrides this and the data-loss
+  confirmation.
+- Image changes are not supported yet. External image URLs are kept as external
+  media, but a local image reference aborts the update (edit text only), and a
+  server-side image in the description is reported before it would be removed.
+
 ### Copy a Confluence page
 
 ```bash
@@ -72,6 +108,44 @@ atlass confluence copy     # prompts for the id or URL
 Accepts a numeric page id or a page URL. Writes `123456-title-slug.md` to the
 current directory.
 
+### Update a Confluence page
+
+Copy a page, edit the Markdown, then push it back:
+
+```bash
+atlass confluence update 123456-title-slug.md
+atlass confluence update            # prompts for the file path
+atlass confluence update file.md --dry-run   # show what would change, write nothing
+atlass confluence update file.md --title     # also rename the page to the H1
+atlass confluence update file.md -m "fix typo"
+```
+
+The page id and version come from the file's frontmatter, so the file is
+self-describing. The body is everything between the H1 and the `## Comments`
+section; the frontmatter, the H1, and the `## Comments` / `## Attachments`
+sections are not sent as page content.
+
+Only the body is updated by default. Pass `--title` to also push the H1 as the
+new page title.
+
+Notes and safety:
+
+- The body is converted from Markdown to ADF. Only the standard constructs the
+  copy produces round-trip (headings, lists, task lists, code, blockquotes,
+  tables, rules, inline marks, links, images). Confluence-specific content
+  (panels, expands, macros, layouts) was flattened to plain Markdown on copy
+  and cannot be rebuilt. When the live page still contains such content, the
+  update warns and asks for confirmation before overwriting.
+- Before writing, the current server version is checked against the frontmatter
+  version. If the page changed since you copied it, the update aborts so you can
+  re-copy. `--force` overrides this and the data-loss confirmation.
+- Images referenced in the body are uploaded as attachments (matched by name and
+  size, so unchanged images are not re-uploaded). Local paths resolve relative
+  to the Markdown file; a missing local image aborts the update. External image
+  URLs are kept as external media.
+- Each update adds a version with the message `Updated via atlass` (override
+  with `--message`).
+
 ### Search Jira issues
 
 ```bash
@@ -199,12 +273,15 @@ pnpm dev       # build in watch mode
 
 - `src/cli.ts` command wiring (commander)
 - `src/commands/` `auth`, `jira`, `confluence` command handlers
-- `src/api/` fetch client, Jira and Confluence endpoints, attachment downloader
-- `src/adf/` ADF to Markdown converter (unit tested)
-- `src/markdown/` frontmatter, comments, attachments, media resolver
+- `src/api/` fetch client, Jira and Confluence endpoints, attachment up/download
+- `src/adf/` ADF to Markdown and Markdown to ADF converters (unit tested)
+- `src/markdown/` frontmatter, comments, attachments, media resolver, update source
 - `src/config.ts`, `src/credentials.ts` config file and keyring
 - `src/util/` key/id parsing and output path resolution
 
 The ADF to Markdown converter in `src/adf/to-markdown.ts` is a single hand
 rolled walker shared by both commands. Confluence page bodies are requested as
-`atlas_doc_format` so they flow through the same converter as Jira.
+`atlas_doc_format` so they flow through the same converter as Jira. The reverse
+direction, `src/adf/from-markdown.ts`, tokenizes Markdown with `marked` and
+emits ADF for the Confluence update command; it covers the same clean subset the
+copy produces.

package/dist/cli.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { checkbox, input, password } from "@inquirer/prompts";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { checkbox, confirm, input, password } from "@inquirer/prompts";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { Entry } from "@napi-rs/keyring";
+import { marked } from "marked";
+import { randomUUID } from "node:crypto";
 //#region package.json
-var version = "1.1.0";
+var version = "1.3.0";
 //#endregion
 //#region src/api/client.ts
 var AtlassianClient = class {
@@ -17,11 +19,15 @@ var AtlassianClient = class {
 		const basic = Buffer.from(`${auth.email}:${auth.token}`).toString("base64");
 		this.authHeader = `Basic ${basic}`;
 	}
-	async request(path, accept) {
-		const res = await fetch(`${this.site}${path}`, { headers: {
-			Authorization: this.authHeader,
-			Accept: accept
-		} });
+	async request(path, init) {
+		const res = await fetch(`${this.site}${path}`, {
+			method: init.method,
+			body: init.body,
+			headers: {
+				Authorization: this.authHeader,
+				...init.headers
+			}
+		});
 		if (!res.ok) {
 			const body = await res.text().catch(() => "");
 			throw httpError(res.status, path, body);
@@ -29,17 +35,55 @@ var AtlassianClient = class {
 		return res;
 	}
 	async getJson(path) {
-		return (await this.request(path, "application/json")).json();
+		return (await this.request(path, { headers: { Accept: "application/json" } })).json();
+	}
+	async putJson(path, body) {
+		return (await this.request(path, {
+			method: "PUT",
+			headers: {
+				Accept: "application/json",
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(body)
+		})).json();
+	}
+	async put(path, body) {
+		await this.request(path, {
+			method: "PUT",
+			headers: {
+				Accept: "application/json",
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(body)
+		});
+	}
+	async postMultipart(path, filename, bytes) {
+		const form = new FormData();
+		const blob = new Blob([bytes]);
+		form.append("file", blob, filename);
+		return (await this.request(path, {
+			method: "POST",
+			headers: {
+				Accept: "application/json",
+				"X-Atlassian-Token": "nocheck"
+			},
+			body: form
+		})).json();
 	}
 	async getBinary(url) {
 		const path = url.startsWith("http") ? new URL(url).pathname + new URL(url).search : url;
-		const res = await this.request(path, "*/*");
+		const res = await this.request(path, { headers: { Accept: "*/*" } });
 		return new Uint8Array(await res.arrayBuffer());
 	}
 };
 function httpError(status, path, body = "") {
 	if (status === 401 || status === 403) return /* @__PURE__ */ new Error("Authentication failed (401/403). Run `atlass auth login` to update your token.");
 	if (status === 404) return /* @__PURE__ */ new Error(`Not found (404): ${path}`);
+	if (status === 409) {
+		const detail = extractError(body);
+		return /* @__PURE__ */ new Error(`Conflict (409): ${detail || "the page changed on the server"}`);
+	}
+	if (status === 413) return /* @__PURE__ */ new Error("Payload too large (413): the page or an attachment exceeds the size limit.");
 	if (status === 400) {
 		const detail = extractError(body);
 		return /* @__PURE__ */ new Error(`Bad request (400): ${detail || path}`);
@@ -161,6 +205,201 @@ async function status() {
 	console.log(`Token: ${hasToken ? "stored in keyring" : "MISSING (run `atlass auth login`)"}`);
 }
 //#endregion
+//#region src/adf/from-markdown.ts
+function markdownToAdf(md, options = {}) {
+	const ctx = { resolveImage: options.resolveImage ?? defaultResolveImage };
+	return {
+		type: "doc",
+		version: 1,
+		content: blocks(marked.lexer(md), ctx)
+	};
+}
+function blocks(tokens, ctx) {
+	const out = [];
+	for (const token of tokens) out.push(...block(token, ctx));
+	return out;
+}
+function block(token, ctx) {
+	switch (token.type) {
+		case "space": return [];
+		case "heading": return [{
+			type: "heading",
+			attrs: { level: clampLevel$1(token.depth) },
+			content: inline(token.tokens ?? [], ctx)
+		}];
+		case "paragraph": return paragraph(token.tokens ?? [], ctx);
+		case "text": return paragraph(token.tokens ?? [textToken(token.text)], ctx);
+		case "list": return [list(token, ctx)];
+		case "code": return [codeBlock(token)];
+		case "blockquote": return [{
+			type: "blockquote",
+			content: blocks(token.tokens ?? [], ctx)
+		}];
+		case "table": return [table(token, ctx)];
+		case "hr": return [{ type: "rule" }];
+		case "html": return [];
+		default: return [];
+	}
+}
+function paragraph(tokens, ctx) {
+	const out = [];
+	let buffer = [];
+	const flush = () => {
+		if (buffer.length === 0) return;
+		const nodes = inline(buffer, ctx);
+		if (nodes.length > 0) out.push({
+			type: "paragraph",
+			content: nodes
+		});
+		buffer = [];
+	};
+	for (const token of tokens) if (token.type === "image") {
+		flush();
+		const image = token;
+		const node = ctx.resolveImage(image.href, image.text ?? "");
+		if (node) out.push(node);
+	} else buffer.push(token);
+	flush();
+	return out;
+}
+function list(token, ctx) {
+	if (token.items.length > 0 && token.items.every((i) => i.task)) return {
+		type: "taskList",
+		attrs: { localId: randomUUID() },
+		content: token.items.map((item) => ({
+			type: "taskItem",
+			attrs: {
+				localId: randomUUID(),
+				state: item.checked ? "DONE" : "TODO"
+			},
+			content: inline(itemInline(item), ctx)
+		}))
+	};
+	const node = {
+		type: token.ordered ? "orderedList" : "bulletList",
+		content: token.items.map((item) => listItem(item, ctx))
+	};
+	const start = Number(token.start);
+	if (token.ordered && Number.isFinite(start) && start !== 1) node.attrs = { order: start };
+	return node;
+}
+function listItem(item, ctx) {
+	const children = blocks(item.tokens.filter((t) => t.type !== "checkbox"), ctx);
+	if (children.length === 0) children.push({
+		type: "paragraph",
+		content: []
+	});
+	return {
+		type: "listItem",
+		content: children
+	};
+}
+function itemInline(item) {
+	const first = item.tokens.find((t) => t.type === "text");
+	if (first && "tokens" in first && first.tokens) return first.tokens;
+	return [textToken(item.text)];
+}
+function codeBlock(token) {
+	return {
+		type: "codeBlock",
+		attrs: token.lang ? { language: token.lang } : {},
+		content: token.text.length > 0 ? [{
+			type: "text",
+			text: token.text
+		}] : []
+	};
+}
+function table(token, ctx) {
+	return {
+		type: "table",
+		content: [{
+			type: "tableRow",
+			content: token.header.map((cell) => tableCell(cell, "tableHeader", ctx))
+		}, ...token.rows.map((row) => ({
+			type: "tableRow",
+			content: row.map((cell) => tableCell(cell, "tableCell", ctx))
+		}))]
+	};
+}
+function tableCell(cell, type, ctx) {
+	return {
+		type,
+		content: [{
+			type: "paragraph",
+			content: inline(cell.tokens, ctx)
+		}]
+	};
+}
+function inline(tokens, ctx, marks = []) {
+	const out = [];
+	for (const token of tokens) out.push(...inlineNode(token, ctx, marks));
+	return out;
+}
+function inlineNode(token, ctx, marks) {
+	switch (token.type) {
+		case "text":
+		case "escape": {
+			const t = token;
+			if ("tokens" in t && t.tokens?.length) return inline(t.tokens, ctx, marks);
+			return textNode(t.text, marks);
+		}
+		case "strong": return inline(token.tokens, ctx, withMark(marks, { type: "strong" }));
+		case "em": return inline(token.tokens, ctx, withMark(marks, { type: "em" }));
+		case "del": return inline(token.tokens, ctx, withMark(marks, { type: "strike" }));
+		case "codespan": return textNode(token.text, withMark(marks, { type: "code" }));
+		case "link": {
+			const link = token;
+			return inline(link.tokens, ctx, withMark(marks, {
+				type: "link",
+				attrs: { href: link.href }
+			}));
+		}
+		case "br": return [{ type: "hardBreak" }];
+		case "html": return textNode(token.text, marks);
+		default: return "text" in token && token.text ? textNode(token.text, marks) : [];
+	}
+}
+function textNode(text, marks) {
+	if (text.length === 0) return [];
+	const node = {
+		type: "text",
+		text
+	};
+	if (marks.length > 0) node.marks = marks;
+	return [node];
+}
+function withMark(marks, mark) {
+	return [...marks.filter((m) => m.type !== mark.type), mark];
+}
+function defaultResolveImage(href, alt) {
+	return {
+		type: "mediaSingle",
+		attrs: { layout: "center" },
+		content: [{
+			type: "media",
+			attrs: alt ? {
+				type: "external",
+				url: href,
+				alt
+			} : {
+				type: "external",
+				url: href
+			}
+		}]
+	};
+}
+function textToken(text) {
+	return {
+		type: "text",
+		raw: text,
+		text,
+		escaped: false
+	};
+}
+function clampLevel$1(value) {
+	return Math.min(6, Math.max(1, Math.trunc(value) || 1));
+}
+//#endregion
 //#region src/adf/to-markdown.ts
 function adfToMarkdown(doc, options = {}) {
 	if (!doc) return "";
@@ -418,6 +657,43 @@ async function fetchPage(client, site, id) {
 		comments
 	};
 }
+async function fetchPageState(client, id) {
+	const page = await client.getJson(`/wiki/api/v2/pages/${encodeURIComponent(id)}?body-format=atlas_doc_format`);
+	return {
+		version: page.version?.number ?? 0,
+		title: page.title,
+		body: parseAdf(page.body?.atlas_doc_format?.value)
+	};
+}
+async function listAttachments(client, id) {
+	return (await client.getJson(`/wiki/api/v2/pages/${encodeURIComponent(id)}/attachments?limit=250`)).results.map((a) => ({
+		filename: a.title ?? a.id,
+		fileId: a.fileId ?? a.id,
+		size: typeof a.fileSize === "number" ? a.fileSize : -1
+	}));
+}
+async function uploadAttachment(client, pageId, filename, bytes) {
+	const fileId = (await client.postMultipart(`/wiki/rest/api/content/${encodeURIComponent(pageId)}/child/attachment`, filename, bytes)).results?.[0]?.extensions?.fileId;
+	if (fileId) return fileId;
+	const match = (await listAttachments(client, pageId)).find((a) => a.filename === filename);
+	if (match) return match.fileId;
+	throw new Error(`Upload of "${filename}" did not return a fileId.`);
+}
+async function updatePage(client, id, params) {
+	return (await client.putJson(`/wiki/api/v2/pages/${encodeURIComponent(id)}`, {
+		id,
+		status: "current",
+		title: params.title,
+		body: {
+			representation: "atlas_doc_format",
+			value: JSON.stringify(params.body)
+		},
+		version: {
+			number: params.version,
+			message: params.message
+		}
+	})).version?.number ?? params.version;
+}
 async function searchPages(client, site, params) {
 	const cql = buildCql(params);
 	const query = new URLSearchParams({
@@ -551,6 +827,108 @@ function joinSections(sections) {
 	return `${sections.filter((s) => s.trim().length > 0).join("\n\n")}\n`;
 }
 //#endregion
+//#region src/markdown/update-source.ts
+function parseUpdateSource(content) {
+	const { fields, bodyTitle, body } = splitFile(content);
+	const id = fields["id"];
+	if (!id) throw new Error("Frontmatter is missing the page `id`; re-copy the page.");
+	const version = Number(fields["version"]);
+	if (!Number.isFinite(version)) throw new Error("Frontmatter is missing a numeric `version`; re-copy the page.");
+	return {
+		id,
+		version,
+		frontTitle: fields["title"] ?? "",
+		bodyTitle,
+		body
+	};
+}
+function parseJiraUpdateSource(content) {
+	const { fields, bodyTitle, body } = splitFile(content);
+	const key = fields["key"];
+	if (!key) throw new Error("Frontmatter is missing the issue `key`; re-copy the issue.");
+	return {
+		key,
+		updated: fields["updated"] ?? "",
+		bodyTitle,
+		body
+	};
+}
+function splitFile(content) {
+	const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+	if (!match) throw new Error("Not an atlass file: no YAML frontmatter found.");
+	const fields = parseFrontmatter(match[1] ?? "");
+	const { bodyTitle, body } = splitBody(content.slice(match[0].length), fields["title"] ?? "");
+	return {
+		fields,
+		bodyTitle,
+		body
+	};
+}
+function parseFrontmatter(block) {
+	const out = {};
+	for (const line of block.split("\n")) {
+		const m = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+		if (!m) continue;
+		const key = m[1] ?? "";
+		let value = (m[2] ?? "").trim();
+		if (value.startsWith("\"") && value.endsWith("\"")) value = value.slice(1, -1).replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
+		out[key] = value;
+	}
+	return out;
+}
+function splitBody(rest, fallbackTitle) {
+	const lines = rest.split("\n");
+	let bodyTitle = fallbackTitle;
+	let start = 0;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		if (line.startsWith("# ")) {
+			bodyTitle = line.slice(2).trim();
+			start = i + 1;
+			break;
+		}
+		if (line.trim().length > 0) break;
+	}
+	let end = lines.length;
+	for (let i = start; i < lines.length; i++) if (/^## (Comments|Attachments)\s*$/.test(lines[i] ?? "")) {
+		end = i;
+		break;
+	}
+	const body = lines.slice(start, end).join("\n").trim();
+	return {
+		bodyTitle,
+		body
+	};
+}
+const LOSSY_LABELS = {
+	panel: "panel",
+	expand: "expand",
+	nestedExpand: "expand",
+	decisionList: "decision list",
+	layoutSection: "layout",
+	extension: "macro",
+	bodiedExtension: "macro",
+	inlineExtension: "macro"
+};
+const JIRA_LOSSY_LABELS = {
+	...LOSSY_LABELS,
+	media: "image",
+	mediaInline: "image"
+};
+function findLossyNodes(node, labels = LOSSY_LABELS) {
+	const counts = /* @__PURE__ */ new Map();
+	const visit = (n) => {
+		const label = labels[n.type];
+		if (label) counts.set(label, (counts.get(label) ?? 0) + 1);
+		for (const child of n.content ?? []) visit(child);
+	};
+	if (node) visit(node);
+	return counts;
+}
+function formatLossy(counts) {
+	return [...counts.entries()].map(([label, n]) => `${n} ${label}${n === 1 ? "" : "s"}`).join(", ");
+}
+//#endregion
 //#region src/util/output-path.ts
 function resolveOutput(defaultBase, out) {
 	let filePath;
@@ -655,6 +1033,56 @@ async function confluenceCopy(arg, options) {
 	const id = await resolveId(arg);
 	await copyPage(new AtlassianClient(auth), auth.site, id, options.out);
 }
+async function confluenceUpdate(arg, options) {
+	const file = arg ?? await input({
+		message: "Path to the page Markdown file:",
+		required: true
+	});
+	const src = parseUpdateSource(await readFile(file, "utf8"));
+	const client = new AtlassianClient(await requireAuth());
+	const state = await fetchPageState(client, src.id);
+	if (state.version !== src.version && !options.force) throw new Error(`Page changed on the server since you copied it (local v${src.version}, server v${state.version}). Re-copy the page or pass --force.`);
+	const dir = dirname(resolve(file));
+	const attachments = await listAttachments(client, src.id);
+	const plan = await planImages(dir, collectImageHrefs(src.body), attachments);
+	const lossy = findLossyNodes(state.body);
+	const nextVersion = state.version + 1;
+	const newTitle = options.title && src.bodyTitle ? src.bodyTitle : state.title;
+	if (options.dryRun) {
+		printDryRun$1(src.id, state.title, newTitle, state.version, nextVersion, lossy, plan);
+		return;
+	}
+	if (lossy.size > 0 && !options.force) {
+		if (!await confirm({
+			message: `This page contains ${formatLossy(lossy)} that Markdown cannot represent and will be removed. Continue?`,
+			default: false
+		})) {
+			console.log("Aborted.");
+			return;
+		}
+	}
+	const collection = `contentId-${src.id}`;
+	const fileIds = /* @__PURE__ */ new Map();
+	for (const [href, entry] of plan) if (entry.kind === "upload") {
+		console.log(`Uploading ${entry.filename} ...`);
+		fileIds.set(href, await uploadAttachment(client, src.id, entry.filename, await readFile(entry.path)));
+	} else if (entry.kind === "reuse") fileIds.set(href, entry.fileId);
+	const body = markdownToAdf(src.body, { resolveImage: (href, alt) => {
+		const entry = plan.get(href);
+		if (!entry) return void 0;
+		if (entry.kind === "external") return externalMedia(href, alt);
+		const fileId = fileIds.get(href);
+		return fileId ? fileMedia(fileId, collection, alt) : void 0;
+	} });
+	if (!body.content || body.content.length === 0) throw new Error("Refusing to update: the converted body is empty.");
+	const version = await updatePage(client, src.id, {
+		title: newTitle,
+		version: nextVersion,
+		body,
+		message: options.message ?? "Updated via atlass"
+	});
+	console.log(`Updated page ${src.id} to version ${version}.`);
+}
 async function confluenceSearch(query, options) {
 	if (options.cql && (query || options.space)) throw new Error("--cql cannot be combined with a text query or --space.");
 	if (options.json && options.copy) throw new Error("--json and --copy cannot be used together.");
@@ -723,6 +1151,94 @@ async function resolveId(arg) {
 	if (!id) throw new Error(`Could not find a page id in "${raw}".`);
 	return id;
 }
+function collectImageHrefs(md) {
+	const hrefs = /* @__PURE__ */ new Set();
+	marked.walkTokens(marked.lexer(md), (token) => {
+		if (token.type === "image") hrefs.add(token.href);
+	});
+	return [...hrefs];
+}
+async function planImages(dir, hrefs, attachments) {
+	const byName = new Map(attachments.map((a) => [a.filename, a]));
+	const plan = /* @__PURE__ */ new Map();
+	const missing = [];
+	for (const href of hrefs) {
+		if (isExternal(href)) {
+			plan.set(href, { kind: "external" });
+			continue;
+		}
+		const path = isAbsolute(href) ? href : resolve(dir, href);
+		let size;
+		try {
+			size = (await stat(path)).size;
+		} catch {
+			missing.push(href);
+			continue;
+		}
+		const filename = basename(path);
+		const existing = byName.get(filename);
+		if (existing && existing.size === size) plan.set(href, {
+			kind: "reuse",
+			fileId: existing.fileId,
+			filename
+		});
+		else plan.set(href, {
+			kind: "upload",
+			path,
+			filename,
+			existed: existing !== void 0
+		});
+	}
+	if (missing.length > 0) throw new Error(`Image file(s) not found: ${missing.join(", ")}`);
+	return plan;
+}
+function isExternal(href) {
+	return /^[a-z][a-z0-9+.-]*:\/\//i.test(href);
+}
+function externalMedia(href, alt) {
+	const attrs = {
+		type: "external",
+		url: href
+	};
+	if (alt) attrs["alt"] = alt;
+	return {
+		type: "mediaSingle",
+		attrs: { layout: "center" },
+		content: [{
+			type: "media",
+			attrs
+		}]
+	};
+}
+function fileMedia(fileId, collection, alt) {
+	const attrs = {
+		type: "file",
+		id: fileId,
+		collection
+	};
+	if (alt) attrs["alt"] = alt;
+	return {
+		type: "mediaSingle",
+		attrs: { layout: "center" },
+		content: [{
+			type: "media",
+			attrs
+		}]
+	};
+}
+function printDryRun$1(id, currentTitle, newTitle, currentVersion, nextVersion, lossy, plan) {
+	const entries = [...plan.values()];
+	const added = entries.filter((e) => e.kind === "upload" && !e.existed).length;
+	const changed = entries.filter((e) => e.kind === "upload" && e.existed).length;
+	const reused = entries.filter((e) => e.kind === "reuse").length;
+	const external = entries.filter((e) => e.kind === "external").length;
+	console.log(`Dry run for page ${id} "${currentTitle}"`);
+	console.log(`  version: ${currentVersion} -> ${nextVersion}`);
+	if (newTitle !== currentTitle) console.log(`  title:   "${currentTitle}" -> "${newTitle}"`);
+	console.log(`  images:  ${added} new, ${changed} changed, ${reused} reused, ${external} external`);
+	if (lossy.size > 0) console.log(`  warning: ${formatLossy(lossy)} will be removed`);
+	console.log("  nothing was written (dry run)");
+}
 //#endregion
 //#region src/api/jira.ts
 const FIELDS = [
@@ -763,6 +1279,11 @@ async function fetchIssue(client, site, key) {
 		}))
 	};
 }
+async function updateIssue(client, key, update) {
+	const fields = { description: update.description };
+	if (update.summary !== void 0) fields["summary"] = update.summary;
+	await client.put(`/rest/api/3/issue/${encodeURIComponent(key)}`, { fields });
+}
 async function searchIssues(client, site, params) {
 	const jql = buildJql(params);
 	const query = new URLSearchParams({
@@ -804,6 +1325,41 @@ async function jiraCopy(arg, options) {
 	const key = await resolveKey(arg);
 	await copyIssue(new AtlassianClient(auth), auth.site, key, options.out);
 }
+async function jiraUpdate(arg, options) {
+	const src = parseJiraUpdateSource(await readFile(arg ?? await input({
+		message: "Path to the issue Markdown file:",
+		required: true
+	}), "utf8"));
+	const auth = await requireAuth();
+	const client = new AtlassianClient(auth);
+	const issue = await fetchIssue(client, auth.site, src.key);
+	const stale = issue.updated !== src.updated;
+	const { local, external } = classifyImages(src.body);
+	const lossy = findLossyNodes(issue.description, JIRA_LOSSY_LABELS);
+	const newSummary = options.summary && src.bodyTitle ? src.bodyTitle : issue.summary;
+	if (options.dryRun) {
+		printDryRun(src.key, issue.summary, newSummary, stale, external.length, local, lossy);
+		return;
+	}
+	if (local.length > 0) throw new Error(`jira update does not support image changes yet. Remove local image reference(s) or edit text only: ${local.join(", ")}`);
+	if (stale && !options.force) throw new Error(`Issue changed on the server since you copied it (local ${src.updated || "unknown"}, server ${issue.updated}). Re-copy the issue or pass --force.`);
+	if (lossy.size > 0 && !options.force) {
+		if (!await confirm({
+			message: `This issue's description contains ${formatLossy(lossy)} that Markdown cannot represent and will be removed. Continue?`,
+			default: false
+		})) {
+			console.log("Aborted.");
+			return;
+		}
+	}
+	const description = markdownToAdf(src.body);
+	if (!description.content || description.content.length === 0) throw new Error("Refusing to update: the converted description is empty.");
+	await updateIssue(client, src.key, {
+		description,
+		summary: options.summary && newSummary !== issue.summary ? newSummary : void 0
+	});
+	console.log(`Updated ${src.key}.`);
+}
 async function jiraSearch(query, options) {
 	if (options.jql && (query || options.project || options.assignee || options.status)) throw new Error("--jql cannot be combined with a text query or other filters.");
 	if (options.json && options.copy) throw new Error("--json and --copy cannot be used together.");
@@ -879,6 +1435,32 @@ function report(filePath, assetCount) {
 	const suffix = assetCount > 0 ? ` (+${assetCount} attachment${assetCount === 1 ? "" : "s"})` : "";
 	console.log(`Wrote ${filePath}${suffix}`);
 }
+function classifyImages(md) {
+	const local = [];
+	const external = [];
+	const seen = /* @__PURE__ */ new Set();
+	marked.walkTokens(marked.lexer(md), (token) => {
+		if (token.type !== "image") return;
+		const href = token.href;
+		if (seen.has(href)) return;
+		seen.add(href);
+		if (/^[a-z][a-z0-9+.-]*:\/\//i.test(href)) external.push(href);
+		else local.push(href);
+	});
+	return {
+		local,
+		external
+	};
+}
+function printDryRun(key, currentSummary, newSummary, stale, externalImages, localImages, lossy) {
+	console.log(`Dry run for ${key} "${currentSummary}"`);
+	if (newSummary !== currentSummary) console.log(`  summary: "${currentSummary}" -> "${newSummary}"`);
+	if (externalImages > 0) console.log(`  images:  ${externalImages} external`);
+	if (localImages.length > 0) console.log(`  blocked: ${localImages.length} local image(s) not supported (edit text only)`);
+	if (lossy.size > 0) console.log(`  warning: ${formatLossy(lossy)} will be removed`);
+	if (stale) console.log(`  stale:   server changed since copy (would refuse without --force)`);
+	console.log("  nothing was written (dry run)");
+}
 //#endregion
 //#region src/cli.ts
 const program = new Command();
@@ -889,9 +1471,11 @@ auth.command("logout").description("Remove stored credentials").action(run(logou
 auth.command("status").description("Show the current login").action(run(status));
 const jira = program.command("jira").description("Jira commands");
 jira.command("copy [issue]").description("Copy a Jira issue (key or URL) to a Markdown file").option("-o, --out <path>", "output file or directory").action(run(jiraCopy));
+jira.command("update [file]").description("Update a Jira issue description from an edited Markdown file").option("--summary", "also push the H1 as the issue summary").option("-f, --force", "skip the stale-issue and data-loss checks").option("--dry-run", "show what would change without writing").action(run(jiraUpdate));
 jira.command("search [query]").description("Search Jira issues (text query, filters, or --jql)").option("-p, --project <key>", "limit to a project").option("-a, --assignee <who>", "limit to an assignee (or 'me')").option("-s, --status <status>", "limit to a status").option("--jql <jql>", "raw JQL query (ignores other filters)").option("-l, --limit <n>", "max results (default 25, max 100)").option("--json", "output results as JSON").option("-c, --copy", "pick results to copy to Markdown").option("-o, --out <dir>", "output directory for --copy").action(run(jiraSearch));
 const confluence = program.command("confluence").description("Confluence commands");
 confluence.command("copy [page]").description("Copy a Confluence page (id or URL) to a Markdown file").option("-o, --out <path>", "output file or directory").action(run(confluenceCopy));
+confluence.command("update [file]").description("Update a Confluence page from an edited Markdown file").option("--title", "also push the H1 as the page title").option("-m, --message <text>", "version message (default 'Updated via atlass')").option("-f, --force", "skip the stale-version and data-loss checks").option("--dry-run", "show what would change without writing").action(run(confluenceUpdate));
 confluence.command("search [query]").description("Search Confluence pages (text query, --space, or --cql)").option("-s, --space <key>", "limit to a space").option("--cql <cql>", "raw CQL query (ignores other filters)").option("-l, --limit <n>", "max results (default 25, max 100)").option("--json", "output results as JSON").option("-c, --copy", "pick results to copy to Markdown").option("-o, --out <dir>", "output directory for --copy").action(run(confluenceSearch));
 program.parseAsync().catch(fail);
 function run(fn) {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "atlass",
-	"version": "1.1.0",
-	"description": "CLI to copy Jira issues and Confluence pages to Markdown.",
+	"version": "1.3.0",
+	"description": "CLI to copy Jira issues and Confluence pages to Markdown, and update Confluence pages.",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -33,7 +33,8 @@
 	"dependencies": {
 		"@inquirer/prompts": "^8.5.2",
 		"@napi-rs/keyring": "^1.3.0",
-		"commander": "^15.0.0"
+		"commander": "^15.0.0",
+		"marked": "^18.0.5"
 	},
 	"devDependencies": {
 		"@types/node": "^25.6.2",