@theholocron/holocron-plugin-github 5.0.0-alpha.374 → 5.0.0-alpha.375

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AddedItem, Auth, AuthError, BoardItem, BoardItemInput, BoardState, BoardSummary, BoardTemplate, Ci, CiRun, CiRunFilter, EnsureReport, Environment, Environments, ImportOptions, ImportResult, Issue, IssueRecord, IssueSearchFilter, IssueSelector, Issues, LabelDef, LifecycleResult, LifecycleSlot, MoveReport, PagesConfig, PluginToken, Projects, PullRequest, RepoRef, RepoSettings, ResolveTokenInput, Ruleset, SecretScope, Secrets, Source, SourceBranch, SourceFile, SourceRepoInfo, SourceRulesetDetail, SourceSecurity, SourceTeamMember, TeamEntry, TeamEntry as TeamEntry$1, TeamPermission, TeamPermission as TeamPermission$1, TrackerDoctorReport, TrackerUser, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, createFeatureResolver } from "@theholocron/cli";
+import { AddedItem, Auth, AuthError, BoardItem, BoardItemInput, BoardState, BoardSummary, BoardTemplate, Ci, CiRun, CiRunFilter, EnsureReport, Environment, Environments, ImportOptions, ImportResult, Issue, IssueRecord, IssueSearchFilter, IssueSelector, Issues, LabelDef, LifecycleResult, LifecycleSlot, MoveReport, PagesConfig, PluginToken, Projects, PullRequest, RepoRef, RepoSettings, ResolveTokenInput, Ruleset, SecretScope, Secrets, Source, SourceBranch, SourceFile, SourceRepoInfo, SourceRulesetDetail, SourceSecurity, SourceTeamMember, SyncResult, TeamEntry, TeamEntry as TeamEntry$1, TeamPermission, TeamPermission as TeamPermission$1, TrackerDoctorReport, TrackerUser, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, createFeatureResolver } from "@theholocron/cli";
 import { GitHubClient, GitHubClientOptions, GraphQLClient, createGitHubClient } from "@theholocron/github-client";
 /** Resolves the token for read-only GitHub access (`HOLOCRON_READ_TOKEN`, keyring key `github.read`). */
 export declare const resolveReadToken: import("@theholocron/cli").FeatureResolver;
@@ -108,6 +108,8 @@ export declare class GitHubIssues implements Issues {
   export(selector: IssueSelector): Promise<IssueRecord[]>;
   /** Makes the records as issues; one already made by an earlier run is skipped. */
   import(records: IssueRecord[], options?: ImportOptions): Promise<ImportResult[]>;
+  /** Like `import`, and it also updates what an earlier import or sync made, for `holocron sync issues`. */
+  sync(records: IssueRecord[], options?: ImportOptions): Promise<SyncResult[]>;
   private resolveMilestone;
   private removeStatusLabels;
   private mapIssue;

package/dist/index.mjs

@@ -188,7 +188,8 @@ async function exportIssues(client, repo, selector) {
 		raw = await listAll(client, repo, { milestone: String(milestone.number) });
 	} else if (selector.all) raw = await listAll(client, repo, {});
 	else throw new Error("export needs keys, a milestone or all");
-	const issues = raw.filter((i) => !i.pull_request && !(selector.openOnly && i.state === "closed"));
+	const since = selector.since ? Date.parse(selector.since) : void 0;
+	const issues = raw.filter((i) => !i.pull_request && !(selector.openOnly && i.state === "closed") && (since === void 0 || Date.parse(i.updated_at) >= since));
 	const records = [];
 	for (const issue of issues) {
 		const comments = await client.issues.listComments(repo, issue.number);
@@ -199,6 +200,7 @@ async function exportIssues(client, repo, selector) {
 		}).catch(() => void 0))?.repository.issue;
 		const { labels, priority } = splitLabels(issue.labels.map((l) => l.name));
 		const body = issue.body?.replace(MARKER, "").trimEnd();
+		const migratedFrom = issue.body ? MARKER.exec(issue.body)?.[1] : void 0;
 		records.push({
 			key: `#${issue.number}`,
 			url: issue.html_url,
@@ -222,7 +224,8 @@ async function exportIssues(client, repo, selector) {
 				createdAt: c.created_at
 			})),
 			createdAt: issue.created_at ?? issue.updated_at,
-			updatedAt: issue.updated_at
+			updatedAt: issue.updated_at,
+			...migratedFrom ? { migratedFrom } : {}
 		});
 	}
 	return records;
@@ -246,10 +249,7 @@ async function importIssues(client, repo, records, options = {}) {
 			});
 			continue;
 		}
-		const dropped = ["createdAt (GitHub sets it; the original date is in the text)"];
-		if (record.assignee) dropped.push("assignee (not mapped)");
-		if (record.parent) dropped.push("parent (not set on GitHub)");
-		if (record.blockedBy.length > 0) dropped.push("blockedBy (not set on GitHub)");
+		const dropped = droppedFor(record);
 		if (options.dryRun) {
 			results.push({
 				source: record.key,
@@ -258,32 +258,51 @@ async function importIssues(client, repo, records, options = {}) {
 			});
 			continue;
 		}
-		const milestoneName = options.milestone ?? record.milestone;
-		const milestone = milestoneName ? await ensureMilestone(client, repo, milestoneName) : void 0;
-		const labels = [...record.labels, ...record.priority && record.priority !== "none" ? [`priority: ${record.priority}`] : []];
-		const created = await client.issues.createIssue(repo, {
-			title: record.title,
-			body: withProvenance(record),
-			...labels.length > 0 ? { labels } : {},
-			...milestone !== void 0 ? { milestone } : {}
-		});
-		for (const comment of record.comments) {
-			const who = comment.author ? `**${comment.author}**` : "Someone";
-			await client.issues.createComment(repo, created.number, `${who} commented on ${comment.createdAt}:\n\n${comment.body}`);
-		}
-		if (record.closed) await client.issues.updateIssue(repo, created.number, {
-			state: "closed",
-			state_reason: "completed"
-		});
+		const number = await createFromRecord(client, repo, record, options);
 		results.push({
 			source: record.key,
-			key: `#${created.number}`,
+			key: `#${number}`,
 			created: true,
 			dropped
 		});
 	}
 	return results;
 }
+/** What GitHub cannot hold of this record, for the report. */
+function droppedFor(record) {
+	const dropped = ["createdAt (GitHub sets it; the original date is in the text)"];
+	if (record.assignee) dropped.push("assignee (not mapped)");
+	if (record.parent) dropped.push("parent (not set on GitHub)");
+	if (record.blockedBy.length > 0) dropped.push("blockedBy (not set on GitHub)");
+	return dropped;
+}
+/** The labels a record becomes on GitHub: its own, plus `priority: <level>` (GitHub's priority is a label). */
+function labelsFor(record) {
+	return [...record.labels, ...record.priority && record.priority !== "none" ? [`priority: ${record.priority}`] : []];
+}
+/** The text a comment gets when it is copied: GitHub cannot post as another author or backdate. */
+function renderComment(comment) {
+	return `${comment.author ? `**${comment.author}**` : "Someone"} commented on ${comment.createdAt}:\n\n${comment.body}`;
+}
+/** Makes one issue from a record, with its comments, and closes it when the record is closed; returns its number. */
+async function createFromRecord(client, repo, record, options) {
+	const milestoneName = options.milestone ?? record.milestone;
+	const milestone = milestoneName ? await ensureMilestone(client, repo, milestoneName) : void 0;
+	const labels = labelsFor(record);
+	const created = await client.issues.createIssue(repo, {
+		title: record.title,
+		body: withProvenance(record),
+		...labels.length > 0 ? { labels } : {},
+		...milestone !== void 0 ? { milestone } : {}
+	});
+	for (const comment of record.comments) await client.issues.createComment(repo, created.number, renderComment(comment));
+	if (record.closed) await client.issues.updateIssue(repo, created.number, {
+		state: "closed",
+		state_reason: "completed"
+	});
+	return created.number;
+}
+/** The text of a migrated issue: the record's body, then where it came from and the marker a second run looks for. */
 function withProvenance(record) {
 	return `${record.body ? `${record.body}\n\n` : ""}---\n_Migrated from [${record.key}](${record.url}); created ${record.createdAt}._\n<!-- holocron:migrated-from ${record.url} -->`;
 }
@@ -311,6 +330,90 @@ async function findMilestone(client, repo, ref) {
 async function ensureMilestone(client, repo, title) {
 	return (await findMilestone(client, repo, title))?.number ?? (await client.issues.createMilestone(repo, title)).number;
 }
+// src/capabilities/issues-sync.ts
+const COMMENT_HEADER = /^(?:\*\*.*?\*\*|Someone) commented on (\S+?):\n/;
+/** Whether GitHub is asking to be left alone: a 429, or a 403 that says it is a rate limit. */
+function isRateLimited(err) {
+	return err instanceof ProviderApiError && (err.status === 429 || err.status === 403 && /rate limit/i.test(`${err.message} ${String(err.details)}`));
+}
+const normalize = (text) => text.replace(/\r\n/g, "\n").trim();
+const sorted = (names) => names.map((n) => n.toLowerCase()).sort().join("\n");
+/** Makes the records missing from the repo and updates the ones an earlier run made. See the file comment. */
+async function syncIssues(client, repo, records, options = {}) {
+	const existing = /* @__PURE__ */ new Map();
+	for (const issue of await listAll(client, repo, {})) {
+		const url = issue.body ? MARKER.exec(issue.body)?.[1] : void 0;
+		if (url) existing.set(url, issue);
+	}
+	const results = [];
+	for (const record of records) try {
+		const found = existing.get(record.url);
+		results.push(found ? await update(client, repo, found, record, options) : await create(client, repo, record, options));
+	} catch (err) {
+		if (isRateLimited(err)) return results;
+		throw err;
+	}
+	return results;
+}
+async function create(client, repo, record, options) {
+	const dropped = droppedFor(record);
+	if (options.dryRun) return {
+		source: record.key,
+		created: true,
+		updated: false,
+		changes: [],
+		dropped
+	};
+	const number = await createFromRecord(client, repo, record, options);
+	return {
+		source: record.key,
+		key: `#${number}`,
+		created: true,
+		updated: false,
+		changes: [],
+		dropped
+	};
+}
+async function update(client, repo, issue, record, options) {
+	const patch = {};
+	const changes = [];
+	if (issue.title !== record.title) {
+		patch.title = record.title;
+		changes.push("title");
+	}
+	const body = withProvenance(record);
+	if (normalize(issue.body) !== normalize(body)) {
+		patch.body = body;
+		changes.push("description");
+	}
+	if (issue.state === "closed" !== record.closed) {
+		patch.state = record.closed ? "closed" : "open";
+		if (record.closed) patch.state_reason = "completed";
+		changes.push("state");
+	}
+	const current = issue.labels.map((l) => l.name);
+	const finalLabels = [...labelsFor(record), ...current.filter((n) => n.toLowerCase().startsWith("status:"))];
+	if (sorted(finalLabels) !== sorted(current)) {
+		patch.labels = finalLabels;
+		changes.push("labels");
+	}
+	const comments = await client.issues.listComments(repo, issue.number);
+	const seen = new Set(comments.map((c) => COMMENT_HEADER.exec(c.body)?.[1]));
+	const missing = record.comments.filter((c) => !seen.has(c.createdAt));
+	if (missing.length > 0) changes.push("comments");
+	if (!options.dryRun) {
+		if (Object.keys(patch).length > 0) await client.issues.updateIssue(repo, issue.number, patch);
+		for (const comment of missing) await client.issues.createComment(repo, issue.number, renderComment(comment));
+	}
+	return {
+		source: record.key,
+		key: `#${issue.number}`,
+		created: false,
+		updated: changes.length > 0,
+		changes,
+		dropped: droppedFor(record)
+	};
+}
 // src/capabilities/issues.ts
 /** The GitHub implementation of the `issues` capability, backed by GitHub Issues and status labels. */
 var GitHubIssues = class {
@@ -495,6 +598,10 @@ var GitHubIssues = class {
 	import(records, options) {
 		return importIssues(this.client, this.repo, records, options);
 	}
+	/** Like `import`, and it also updates what an earlier import or sync made, for `holocron sync issues`. */
+	sync(records, options) {
+		return syncIssues(this.client, this.repo, records, options);
+	}
 	async resolveMilestone(ref) {
 		if (/^\d+$/.test(ref)) return parseInt(ref, 10);
 		const match = (await this.client.issues.listMilestones(this.repo, { state: "all" })).find((m) => m.title.toLowerCase() === ref.toLowerCase());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "5.0.0-alpha.374",
+  "version": "5.0.0-alpha.375",
   "description": "Holocron plugin for GitHub. Implements source, ci, secrets, environments, and issues capabilities against the GitHub REST API.",
   "keywords": [
     "ci",
@@ -44,21 +44,21 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^5.1.0",
-    "@theholocron/cli": "5.0.0-alpha.374",
+    "@theholocron/cli": "5.0.0-alpha.375",
     "@theholocron/eslint-config": "^8.9.0-alpha.12",
     "@theholocron/fs-utils": "^1.17.0-alpha.2",
-    "@theholocron/http-client": "^1.58.0-alpha.20",
+    "@theholocron/github-client": "^1.58.0-alpha.21",
     "@theholocron/misc-utils": "^1.17.0-alpha.2",
+    "@theholocron/http-client": "^1.58.0-alpha.21",
     "@theholocron/tsconfig": "^8.9.0-alpha.12",
-    "@theholocron/github-client": "^1.58.0-alpha.20",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.12",
-    "@theholocron/vitest-config": "^8.9.0-alpha.12"
+    "@theholocron/vitest-config": "^8.9.0-alpha.12",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.12"
   },
   "peerDependencies": {
     "@theholocron/fs-utils": "^1.16.0",
     "@theholocron/github-client": "^1.58.0",
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/cli": "5.0.0-alpha.374"
+    "@theholocron/cli": "5.0.0-alpha.375"
   },
   "engines": {
     "node": ">=22"