atlass 1.2.0 → 1.4.0

package/README.md

@@ -63,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
@@ -129,6 +163,19 @@ 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).
 
+### List Jira projects
+
+```bash
+atlass jira projects            # every project you can browse
+atlass jira projects pay        # filter by key or name
+atlass jira projects --json     # machine output
+```
+
+A discovery aid for the `--project` filter above: it fetches every project
+(paginated, ordered by key) and prints one per line as an aligned `KEY  Name`
+list. An optional query filters by key or name server-side. `--json` emits
+`{ key, name, id, type, url }` per project.
+
 ### Search Confluence pages
 
 ```bash

package/dist/cli.mjs

@@ -8,7 +8,7 @@ import { Entry } from "@napi-rs/keyring";
 import { marked } from "marked";
 import { randomUUID } from "node:crypto";
 //#region package.json
-var version = "1.2.0";
+var version = "1.4.0";
 //#endregion
 //#region src/api/client.ts
 var AtlassianClient = class {
@@ -47,6 +47,16 @@ var AtlassianClient = class {
 			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]);
@@ -819,14 +829,11 @@ function joinSections(sections) {
 //#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 { 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.");
-	const { bodyTitle, body } = splitBody(content.slice(match[0].length), fields["title"] ?? "");
 	return {
 		id,
 		version,
@@ -835,6 +842,28 @@ function parseUpdateSource(content) {
 		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")) {
@@ -881,10 +910,15 @@ const LOSSY_LABELS = {
 	bodiedExtension: "macro",
 	inlineExtension: "macro"
 };
-function findLossyNodes(node) {
+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 = LOSSY_LABELS[n.type];
+		const label = labels[n.type];
 		if (label) counts.set(label, (counts.get(label) ?? 0) + 1);
 		for (const child of n.content ?? []) visit(child);
 	};
@@ -1015,7 +1049,7 @@ async function confluenceUpdate(arg, options) {
 	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);
+		printDryRun$1(src.id, state.title, newTitle, state.version, nextVersion, lossy, plan);
 		return;
 	}
 	if (lossy.size > 0 && !options.force) {
@@ -1192,7 +1226,7 @@ function fileMedia(fileId, collection, alt) {
 		}]
 	};
 }
-function printDryRun(id, currentTitle, newTitle, currentVersion, nextVersion, lossy, plan) {
+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;
@@ -1220,13 +1254,16 @@ const FIELDS = [
 	"updated",
 	"attachment"
 ].join(",");
+function browseUrl(site, key) {
+	return `${site}/browse/${key}`;
+}
 async function fetchIssue(client, site, key) {
 	const issue = await client.getJson(`/rest/api/3/issue/${encodeURIComponent(key)}?fields=${FIELDS}`);
 	const comments = await fetchComments(client, key);
 	const f = issue.fields;
 	return {
 		key: issue.key,
-		url: `${site}/browse/${issue.key}`,
+		url: browseUrl(site, issue.key),
 		summary: f.summary ?? "",
 		type: f.issuetype?.name ?? "",
 		status: f.status?.name ?? "",
@@ -1245,6 +1282,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({
@@ -1256,7 +1298,7 @@ async function searchIssues(client, site, params) {
 		key: i.key,
 		status: i.fields?.status?.name ?? "",
 		summary: decodeEntities(i.fields?.summary ?? ""),
-		url: `${site}/browse/${i.key}`
+		url: browseUrl(site, i.key)
 	}));
 }
 function buildJql(params) {
@@ -1269,6 +1311,33 @@ function buildJql(params) {
 	if (clauses.length === 0) clauses.push("updated >= -30d");
 	return `${clauses.join(" AND ")} ORDER BY updated DESC`;
 }
+const PROJECT_PAGE_SIZE = 50;
+async function listProjects(client, site, query) {
+	const projects = [];
+	for (let startAt = 0;;) {
+		const res = await client.getJson(`/rest/api/3/project/search?${projectSearchQuery(query, startAt)}`);
+		const values = res.values ?? [];
+		for (const p of values) projects.push({
+			key: p.key,
+			name: p.name,
+			id: p.id,
+			type: p.projectTypeKey ?? "",
+			url: browseUrl(site, p.key)
+		});
+		if (res.isLast || values.length === 0) break;
+		startAt += values.length;
+	}
+	return projects;
+}
+function projectSearchQuery(query, startAt) {
+	const params = new URLSearchParams({
+		orderBy: "key",
+		maxResults: String(PROJECT_PAGE_SIZE),
+		startAt: String(startAt)
+	});
+	if (query) params.set("query", query);
+	return params.toString();
+}
 function jqlValue(value) {
 	return `"${value.replace(/(["\\])/g, "\\$1")}"`;
 }
@@ -1281,11 +1350,63 @@ async function fetchComments(client, key) {
 }
 //#endregion
 //#region src/commands/jira.ts
+async function jiraProjects(query, options) {
+	const auth = await requireAuth();
+	const projects = await listProjects(new AtlassianClient(auth), auth.site, query);
+	if (options.json) {
+		console.log(JSON.stringify(projects, null, 2));
+		return;
+	}
+	if (projects.length === 0) {
+		console.log("No matching projects.");
+		return;
+	}
+	for (const line of formatProjectRows(projects)) console.log(line);
+}
+function formatProjectRows(projects) {
+	const width = Math.max(...projects.map((p) => p.key.length));
+	return projects.map((p) => `${p.key.padEnd(width)}  ${p.name}`);
+}
 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 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.");
@@ -1361,6 +1482,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();
@@ -1370,7 +1517,9 @@ auth.command("login").description("Store site, email, and API token").action(run
 auth.command("logout").description("Remove stored credentials").action(run(logout));
 auth.command("status").description("Show the current login").action(run(status));
 const jira = program.command("jira").description("Jira commands");
+jira.command("projects [query]").description("List projects (optionally filtered by key or name)").option("--json", "output results as JSON").action(run(jiraProjects));
 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));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "atlass",
-	"version": "1.2.0",
+	"version": "1.4.0",
 	"description": "CLI to copy Jira issues and Confluence pages to Markdown, and update Confluence pages.",
 	"license": "MIT",
 	"repository": {