atlass 1.0.0 → 1.2.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
 
@@ -72,6 +74,87 @@ 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
+atlass jira search "safari login"                 # free text
+atlass jira search --project PROJ --assignee me   # my open issues in PROJ
+atlass jira search --status "In Progress"
+atlass jira search --jql "project = PROJ AND labels = regression"
+atlass jira search                                # recent issues
+```
+
+Friendly filters (`--project`, `--assignee`, `--status`, text) are AND'd
+together and ordered by most recently updated. `--assignee me` maps to the
+current user. `--jql` takes a raw query and cannot be combined with the friendly
+filters. Prints one issue per line (`KEY  status  summary`); use `--json` for
+machine output. Only the first `--limit` results are shown (default 25, max
+100).
+
+### Search Confluence pages
+
+```bash
+atlass confluence search "onboarding"
+atlass confluence search --space DOCS
+atlass confluence search --cql "label = runbook ORDER BY created DESC"
+atlass confluence search                          # recent pages
+```
+
+Friendly mode always constrains to pages, so every result is copy-able. `--cql`
+takes a raw query and cannot be combined with `--space` or text. Prints one page
+per line (`id  space  title`); `--json` and `--limit` work as for Jira.
+
+### Copy from search results
+
+Add `--copy` to any search to pick results interactively and copy each to
+Markdown (multi-select, needs an interactive terminal). With `--copy`, `--out`
+is a directory that every selected file is written into:
+
+```bash
+atlass jira search --project PROJ --copy --out ./tickets/
+atlass confluence search --space DOCS --copy
+```
+
+Copying continues on failure and reports a summary at the end.
+
 ### Output location
 
 By default files are written to the current directory, named after the issue
@@ -156,12 +239,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 { 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.0.0";
+var version = "1.2.0";
 //#endregion
 //#region src/api/client.ts
 var AtlassianClient = class {
@@ -17,27 +19,76 @@ 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
-		} });
-		if (!res.ok) throw httpError(res.status, path);
+	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);
+		}
 		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 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) {
+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}`);
-	return /* @__PURE__ */ new Error(`Request failed (${status}): ${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}`);
+	}
+	const detail = extractError(body);
+	return /* @__PURE__ */ new Error(`Request failed (${status}): ${detail || path}`);
+}
+function extractError(body) {
+	if (!body) return "";
+	try {
+		const json = JSON.parse(body);
+		if (json.errorMessages?.length) return json.errorMessages.join("; ");
+		if (json.message) return json.message;
+	} catch {}
+	return body.slice(0, 300);
 }
 //#endregion
 //#region src/config.ts
@@ -144,6 +195,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 "";
@@ -357,6 +603,25 @@ function uniqueName(name, used) {
 	return candidate;
 }
 //#endregion
+//#region src/util/html.ts
+const NAMED = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " "
+};
+function decodeEntities(text) {
+	return text.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (match, body) => {
+		if (body[0] === "#") {
+			const code = body[1] === "x" || body[1] === "X" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+			return Number.isFinite(code) && code >= 0 && code <= 1114111 ? String.fromCodePoint(code) : match;
+		}
+		return NAMED[body.toLowerCase()] ?? match;
+	});
+}
+//#endregion
 //#region src/api/confluence.ts
 async function fetchPage(client, site, id) {
 	const page = await client.getJson(`/wiki/api/v2/pages/${encodeURIComponent(id)}?body-format=atlas_doc_format`);
@@ -382,6 +647,71 @@ 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({
+		cql,
+		limit: String(params.limit),
+		expand: "space"
+	});
+	const results = (await client.getJson(`/wiki/rest/api/search?${query.toString()}`)).results ?? [];
+	return {
+		pages: results.filter((r) => r.content?.id).map((r) => ({
+			id: r.content?.id ?? "",
+			space: r.space?.key ?? r.resultGlobalContainer?.title ?? "",
+			title: decodeEntities(r.content?.title ?? r.title ?? ""),
+			url: r.url ? `${site}/wiki${r.url}` : ""
+		})),
+		hasMore: results.length === params.limit
+	};
+}
+function buildCql(params) {
+	if (params.cql) return params.cql;
+	const clauses = ["type = page"];
+	if (params.space) clauses.push(`space = ${cqlValue(params.space)}`);
+	if (params.text) clauses.push(`text ~ ${cqlValue(params.text)}`);
+	return `${clauses.join(" AND ")} ORDER BY lastmodified DESC`;
+}
+function cqlValue(value) {
+	return `"${value.replace(/(["\\])/g, "\\$1")}"`;
+}
 async function fetchSpaceKey(client, spaceId) {
 	if (!spaceId) return "";
 	try {
@@ -487,6 +817,84 @@ 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 match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+	if (!match) throw new Error("Not an atlass page file: no YAML frontmatter found.");
+	const fields = parseFrontmatter(match[1] ?? "");
+	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.");
+	const { bodyTitle, body } = splitBody(content.slice(match[0].length), fields["title"] ?? "");
+	return {
+		id,
+		version,
+		frontTitle: fields["title"] ?? "",
+		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"
+};
+function findLossyNodes(node) {
+	const counts = /* @__PURE__ */ new Map();
+	const visit = (n) => {
+		const label = LOSSY_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;
@@ -519,15 +927,165 @@ function parsePageId(input) {
 	if (fromQuery) return fromQuery[1];
 	return null;
 }
+function parseLimit(value) {
+	if (!value) return 25;
+	const n = Number.parseInt(value, 10);
+	if (!Number.isFinite(n) || n < 1) throw new Error(`Invalid --limit "${value}".`);
+	return Math.min(n, 100);
+}
+//#endregion
+//#region src/commands/search-run.ts
+const COPY_CONCURRENCY = 5;
+async function runSearch(rows, options, noun, copyOne) {
+	if (options.json) {
+		console.log(JSON.stringify(rows.map((r) => r.json), null, 2));
+		return;
+	}
+	if (rows.length === 0) {
+		console.log(`No matching ${noun.plural}.`);
+		return;
+	}
+	if (options.copy) {
+		if (options.out?.endsWith(".md")) throw new Error("--out must be a directory when using --copy; a .md file path would overwrite each selection.");
+		await copySelected(rows, noun, copyOne);
+		return;
+	}
+	for (const row of rows) console.log(formatRow(row));
+	if (options.hasMore) console.log(`\nShowing first ${options.limit}; refine with flags or raise --limit.`);
+}
+async function copySelected(rows, noun, copyOne) {
+	if (!process.stdin.isTTY) throw new Error("--copy requires an interactive terminal.");
+	const selected = await checkbox({
+		message: `Select ${noun.plural} to copy:`,
+		choices: rows.map((r) => ({
+			name: formatRow(r),
+			value: r.id
+		})),
+		pageSize: 20
+	});
+	if (selected.length === 0) {
+		console.log("Nothing selected.");
+		return;
+	}
+	let copied = 0;
+	const failures = [];
+	const queue = [...selected];
+	async function worker() {
+		for (let id = queue.shift(); id !== void 0; id = queue.shift()) try {
+			await copyOne(id);
+			copied++;
+		} catch (err) {
+			failures.push(`${id} (${err instanceof Error ? err.message : String(err)})`);
+		}
+	}
+	await Promise.all(Array.from({ length: Math.min(COPY_CONCURRENCY, selected.length) }, worker));
+	const summary = `Copied ${copied} ${copied === 1 ? noun.singular : noun.plural}`;
+	if (failures.length === 0) console.log(summary);
+	else console.log(`${summary}, failed ${failures.length}: ${failures.join(", ")}`);
+}
+function formatRow(row) {
+	const room = (process.stdout.columns ?? 80) - row.prefix.length - 2;
+	const text = room > 0 ? truncate(row.text, room) : "";
+	return text ? `${row.prefix}  ${text}` : row.prefix;
+}
+function truncate(text, max) {
+	const clean = text.replace(/\s+/g, " ").trim();
+	return clean.length <= max ? clean : `${clean.slice(0, Math.max(0, max - 3))}...`;
+}
 //#endregion
 //#region src/commands/confluence.ts
 async function confluenceCopy(arg, options) {
 	const auth = await requireAuth();
 	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(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.");
+	const auth = await requireAuth();
 	const client = new AtlassianClient(auth);
+	const limit = parseLimit(options.limit);
+	const { pages, hasMore } = await searchPages(client, auth.site, {
+		text: query,
+		space: options.space,
+		cql: options.cql,
+		limit
+	});
+	await runSearch(pages.map((p) => ({
+		id: p.id,
+		prefix: `${p.id}  ${p.space}`,
+		text: p.title,
+		json: {
+			id: p.id,
+			space: p.space,
+			title: p.title,
+			url: p.url
+		}
+	})), {
+		json: options.json,
+		copy: options.copy,
+		limit,
+		hasMore,
+		out: options.out
+	}, {
+		singular: "page",
+		plural: "pages"
+	}, (id) => copyPage(client, auth.site, id, options.out));
+}
+async function copyPage(client, site, id, out) {
 	console.log(`Fetching page ${id} ...`);
-	const page = await fetchPage(client, auth.site, id);
-	const target = resolveOutput(`${page.id}-${slugify(page.title)}`, options.out);
+	const page = await fetchPage(client, site, id);
+	const target = resolveOutput(`${page.id}-${slugify(page.title)}`, out);
 	const downloaded = await downloadAttachments(client, page.attachments, target.assetsDir, target.assetsDirName);
 	const resolveMedia = mediaResolver(downloaded);
 	const document = joinSections([
@@ -559,6 +1117,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(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 = [
@@ -599,6 +1245,33 @@ async function fetchIssue(client, site, key) {
 		}))
 	};
 }
+async function searchIssues(client, site, params) {
+	const jql = buildJql(params);
+	const query = new URLSearchParams({
+		jql,
+		maxResults: String(params.limit),
+		fields: "summary,status"
+	});
+	return ((await client.getJson(`/rest/api/3/search/jql?${query.toString()}`)).issues ?? []).map((i) => ({
+		key: i.key,
+		status: i.fields?.status?.name ?? "",
+		summary: decodeEntities(i.fields?.summary ?? ""),
+		url: `${site}/browse/${i.key}`
+	}));
+}
+function buildJql(params) {
+	if (params.jql) return params.jql;
+	const clauses = [];
+	if (params.project) clauses.push(`project = ${jqlValue(params.project)}`);
+	if (params.assignee) clauses.push(params.assignee === "me" ? "assignee = currentUser()" : `assignee = ${jqlValue(params.assignee)}`);
+	if (params.status) clauses.push(`status = ${jqlValue(params.status)}`);
+	if (params.text) clauses.push(`text ~ ${jqlValue(params.text)}`);
+	if (clauses.length === 0) clauses.push("updated >= -30d");
+	return `${clauses.join(" AND ")} ORDER BY updated DESC`;
+}
+function jqlValue(value) {
+	return `"${value.replace(/(["\\])/g, "\\$1")}"`;
+}
 async function fetchComments(client, key) {
 	return (await client.getJson(`/rest/api/3/issue/${encodeURIComponent(key)}/comment?maxResults=100&orderBy=created`)).comments.map((c) => ({
 		author: c.author?.displayName ?? "",
@@ -611,10 +1284,47 @@ async function fetchComments(client, key) {
 async function jiraCopy(arg, options) {
 	const auth = await requireAuth();
 	const key = await resolveKey(arg);
+	await copyIssue(new AtlassianClient(auth), auth.site, key, options.out);
+}
+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.");
+	const auth = await requireAuth();
 	const client = new AtlassianClient(auth);
+	const limit = parseLimit(options.limit);
+	const issues = await searchIssues(client, auth.site, {
+		text: query,
+		project: options.project,
+		assignee: options.assignee,
+		status: options.status,
+		jql: options.jql,
+		limit
+	});
+	await runSearch(issues.map((i) => ({
+		id: i.key,
+		prefix: `${i.key}  ${i.status}`,
+		text: i.summary,
+		json: {
+			key: i.key,
+			status: i.status,
+			summary: i.summary,
+			url: i.url
+		}
+	})), {
+		json: options.json,
+		copy: options.copy,
+		limit,
+		hasMore: issues.length === limit,
+		out: options.out
+	}, {
+		singular: "issue",
+		plural: "issues"
+	}, (key) => copyIssue(client, auth.site, key, options.out));
+}
+async function copyIssue(client, site, key, out) {
 	console.log(`Fetching ${key} ...`);
-	const issue = await fetchIssue(client, auth.site, key);
-	const target = resolveOutput(issue.key, options.out);
+	const issue = await fetchIssue(client, site, key);
+	const target = resolveOutput(issue.key, out);
 	const downloaded = await downloadAttachments(client, issue.attachments, target.assetsDir, target.assetsDirName);
 	const resolveMedia = mediaResolver(downloaded);
 	const document = joinSections([
@@ -659,8 +1369,13 @@ const auth = program.command("auth").description("Manage Atlassian credentials")
 auth.command("login").description("Store site, email, and API token").action(run(login));
 auth.command("logout").description("Remove stored credentials").action(run(logout));
 auth.command("status").description("Show the current login").action(run(status));
-program.command("jira").description("Jira commands").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));
-program.command("confluence").description("Confluence commands").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));
+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("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) {
 	return async (...args) => {

package/package.json

@@ -1,8 +1,12 @@
 {
 	"name": "atlass",
-	"version": "1.0.0",
-	"description": "CLI to copy Jira issues and Confluence pages to Markdown.",
+	"version": "1.2.0",
+	"description": "CLI to copy Jira issues and Confluence pages to Markdown, and update Confluence pages.",
 	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dan-livingston/atlass.git"
+	},
 	"bin": {
 		"atlass": "./dist/cli.mjs"
 	},
@@ -29,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",