@theholocron/holocron-plugin-github 5.0.0-alpha.339 → 5.0.0-alpha.340

package/README.md

@@ -1,7 +1,7 @@
 # `@theholocron/holocron-plugin-github`
 
-GitHub plugin for [Holocron](../cli). Implements five capabilities
-against the GitHub REST API:
+GitHub plugin for [Holocron](../cli). Implements six capabilities
+against the GitHub REST and GraphQL APIs:
 
 | Capability     | What this plugin does                                            |
 | -------------- | ---------------------------------------------------------------- |
@@ -10,6 +10,7 @@ against the GitHub REST API:
 | `secrets`      | GH Actions secrets (repo + environment + organization)           |
 | `environments` | Named deployment environments (reviewers, wait timers)           |
 | `issues`       | GitHub Issues as a tracker (with lifecycle slots)                |
+| `projects`     | GitHub Projects v2 boards (GraphQL)                              |
 
 ## Install
 
@@ -34,6 +35,7 @@ Each capability resolves its own fine-grained token so a compromised credential
 | `HOLOCRON_SYNC_TOKEN`    | `github.sync`    | `sync-github` command               |
 | `HOLOCRON_RELEASE_TOKEN` | `github.release` | semantic-release, GitHub releases   |
 | `HOLOCRON_ADMIN_TOKEN`   | `github.admin`   | `source`, `secrets`, `environments` |
+| `HOLOCRON_ORG_TOKEN`     | `github.org`     | `projects`                          |
 
 Store tokens once via the keyring so they are picked up automatically:
 
@@ -64,6 +66,29 @@ See the [token reference](https://docs.theholocron.dev/holocron/tokens/) for ful
 
 ```
 
+## `projects` capability
+
+GitHub Projects v2 boards over GraphQL, for `holocron project ...` (SPEC-0020, #1744). It uses the org token
+(`HOLOCRON_ORG_TOKEN`, keyring `github.org`) with the **Projects** organization permission. Items are keyed `#N` in the
+configured `repo` and `owner/repo#N` elsewhere.
+
+| Method      | What it does                                                                                                                                                               |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list`      | Every project of the organization, open and closed. `find` is the exact name among the open ones.                                                                          |
+| `create`    | Copies the board `template.source` names (fields, options, views, automation rules, no items), or creates a project and applies the template.                              |
+| `close`     | `updateProjectV2` with `closed: true`. Reversible.                                                                                                                         |
+| `read`      | Statuses, other fields, board and table views and automation rules.                                                                                                        |
+| `ensure`    | Adds what the template lists and the board lacks (options, fields, views, filters). Never deletes. Rules and view grouping the API cannot set come back as `todos`.        |
+| `items`     | Each issue or pull request with its status, category, whether it is open and its open blockers.                                                                            |
+| `setStatus` | Sets an item's status. Idempotent: `transitioned: false` when it is already there.                                                                                         |
+| `move`      | Puts open items on another board with status and priority (only where the target has none); closed and merged ones stay and are set to done when theirs is not a done one. |
+| `whoami`    | How many boards the token sees, for `holocron doctor`.                                                                                                                     |
+
+`ensure` is safe on a field that has items. `updateProjectV2Field` replaces a single select field's whole option list,
+and an option sent without its `id` blanks the field on every item, so `ensure` reads the field first, sends every
+existing option with its `id` in the template's order (new ones without), and stops when the field cannot be read. It
+also keeps the item values in memory and, if a re-read shows any gone, writes them back by option name and fails.
+
 ## Status
 
 **`v2.0.0-alpha.0`** — published on npm under the `alpha` dist-tag.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { Auth, AuthError, Ci, CiRun, CiRunFilter, Environment, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, PagesConfig, PluginToken, 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 { GitHubClient, GitHubClientOptions, createGitHubClient } from "@theholocron/github-client";
+import { Auth, AuthError, BoardItem, BoardState, BoardSummary, BoardTemplate, Ci, CiRun, CiRunFilter, EnsureReport, Environment, Environments, Issue, IssueSearchFilter, 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 { 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;
 /** Resolves the token for issue operations (`HOLOCRON_ISSUES_TOKEN`, keyring key `github.issues`). */
@@ -126,6 +126,68 @@ interface CanonicalLabel {
  * - Leaves unrecognised labels that aren't in `stale` untouched.
  */
 export declare function syncLabels(client: GitHubClient, repo: string, canonical: ReadonlyArray<CanonicalLabel>, stale: ReadonlyArray<string>): Promise<string>;
+/** Options of the GitHub `projects` capability. */
+interface ProjectsOptions {
+  /** The repository the provider is configured for, as `owner/name`; its items get the short key `#N`. */
+  repo: string;
+}
+/** The GitHub implementation of the `projects` capability, backed by Projects v2. */
+export declare class GitHubProjects implements Projects {
+  private readonly graphql;
+  /** Capability key, always `"projects"`. */
+  readonly key: "projects";
+  /** Provider name, always `"github"`. */
+  readonly providerName = "github";
+  private readonly repo;
+  constructor(graphql: GraphQLClient, opts: ProjectsOptions);
+  /** Every board of the organization, open and closed. */
+  list(owner: string): Promise<BoardSummary[]>;
+  /** The open board with exactly this name. */
+  find(owner: string, name: string): Promise<BoardSummary | undefined>;
+  /**
+   * Makes a board. With `template.source` naming an open board it is copied (fields, options, views and automation
+   * rules, no items); otherwise the board is created and brought in line with the template.
+   */
+  create(owner: string, name: string, template: BoardTemplate): Promise<BoardSummary>;
+  /** Closes the board; `updateProjectV2` with `closed: true` is the only way, and reversible. */
+  close(_owner: string, board: BoardSummary): Promise<void>;
+  /** The live board: statuses, other fields, views and automation rules. */
+  read(_owner: string, board: BoardSummary): Promise<BoardState>;
+  /**
+   * Brings the board in line with the template. Never deletes a field, option or view, and never sends an option
+   * list without ids. Stops (throws) when the status field cannot be read.
+   */
+  ensure(_owner: string, board: BoardSummary, template: BoardTemplate): Promise<EnsureReport>;
+  /**
+   * Makes a single select field hold the wanted options in order, every existing one sent with its id. Options the
+   * template does not mention stay, after the wanted ones. Returns what changed (`Blocked added`, `order set`).
+   */
+  private ensureOptions;
+  private createField;
+  private createView;
+  private updateView;
+  /** The board's issues and pull requests with their status, whether they are open and their open blockers. */
+  items(_owner: string, board: BoardSummary, template: BoardTemplate): Promise<BoardItem[]>;
+  /** Puts an item in a status; `transitioned` is false when it already is there. */
+  setStatus(_owner: string, board: BoardSummary, key: string, status: string): Promise<LifecycleResult>;
+  /**
+   * Puts the open items of `from` on `to` with their status and priority, only where the target has no value;
+   * closed and merged ones stay, and are set to the template's done status when theirs is not a done one.
+   */
+  move(_owner: string, from: BoardSummary, to: BoardSummary, template: BoardTemplate): Promise<MoveReport>;
+  /** A `holocron doctor` smoke check: how many boards the token sees in the configured repository's organization. */
+  whoami(): Promise<{
+    ok: boolean;
+    boards: number;
+  }>;
+  /** Sets a single select value by option name; a field or option the board lacks is skipped. */
+  private setOption;
+  private ownerId;
+  private readRaw;
+  private fetchItems;
+  private keyOf;
+  private parseKey;
+}
 interface SecretsOptions {
   repo: string;
 }
@@ -326,6 +388,8 @@ export declare function environments(ctx: PluginContext): Environments;
 export declare function ci(ctx: PluginContext): Ci;
 /** Builds the `issues` capability, passing the lifecycle labels when configured. */
 export declare function issues(ctx: PluginContext): Issues;
+/** Builds the `projects` capability: GitHub Projects v2 over GraphQL, with items keyed relative to the configured repo. */
+export declare function projects(ctx: PluginContext): Projects;
 /** Creates the plugin, resolving a token per capability when it is first used. */
 export declare function createPlugin(options: GitHubPluginOptions): {
   name: string;
@@ -338,6 +402,7 @@ export declare function createPlugin(options: GitHubPluginOptions): {
     secrets: () => Secrets;
     environments: () => Environments;
     issues: () => Issues;
+    projects: () => Projects;
   };
 };
 /**
@@ -347,4 +412,4 @@ export declare function createPlugin(options: GitHubPluginOptions): {
 export declare const AUTH_HINT: string;
 /** Every token this plugin takes, for `holocron doctor tokens`. */
 export declare const tokens: PluginToken[];
-export { type Auth, AuthError, type CanonicalLabel, type GitHubClientOptions, type NormalizedTeamEntry, type ResolveTokenInput, type TeamEntry, type TeamPermission, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createFeatureResolver, createGitHubClient };
+export { type Auth, AuthError, type CanonicalLabel, type GitHubClientOptions, type NormalizedTeamEntry, type ProjectsOptions, type ResolveTokenInput, type TeamEntry, type TeamPermission, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createFeatureResolver, createGitHubClient };

package/dist/index.mjs

@@ -376,6 +376,503 @@ function parseIssueNumber(key, owner, repoName) {
 	if (!/^\d+$/.test(num)) throw new Error(`Invalid GitHub issue key "${key}" — expected #N or N.`);
 	return parseInt(num, 10);
 }
+// src/capabilities/projects.ts
+/** The name of the single select field that holds an item's status. */
+const STATUS_FIELD = "Status";
+/** The name of the field `move` carries over besides the status. */
+const PRIORITY_FIELD = "Priority";
+const PROJECT_FIELDS = "id number title closed url";
+const BOARD_QUERY = `query($id: ID!) { node(id: $id) { ... on ProjectV2 {
+	${PROJECT_FIELDS}
+	fields(first: 100) { nodes {
+		... on ProjectV2FieldCommon { id name dataType }
+		... on ProjectV2SingleSelectField { options { id name color description } }
+	} }
+	views(first: 50) { nodes { id name layout filter groupByFields(first: 5) { nodes { ... on ProjectV2FieldCommon { name } } } } }
+	workflows(first: 50) { nodes { id name enabled } }
+} } }`;
+const ITEMS_QUERY = `query($id: ID!, $after: String) { node(id: $id) { ... on ProjectV2 {
+	items(first: 100, after: $after) {
+		pageInfo { hasNextPage endCursor }
+		nodes {
+			id
+			fieldValues(first: 30) { nodes { ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2FieldCommon { name } } } } }
+			content {
+				__typename
+				... on Issue { id number title state repository { nameWithOwner } blockedBy(first: 50) { nodes { number state repository { nameWithOwner } } } }
+				... on PullRequest { id number title state repository { nameWithOwner } }
+			}
+		}
+	}
+} } }`;
+const LIST_QUERY = `query($owner: String!, $after: String) { organization(login: $owner) { id projectsV2(first: 100, after: $after) {
+	pageInfo { hasNextPage endCursor }
+	nodes { ${PROJECT_FIELDS} }
+} } }`;
+const OWNER_QUERY = "query($owner: String!) { organization(login: $owner) { id } }";
+const SET_VALUE = `mutation($project: ID!, $item: ID!, $field: ID!, $option: String!) {
+	updateProjectV2ItemFieldValue(input: { projectId: $project, itemId: $item, fieldId: $field, value: { singleSelectOptionId: $option } }) { projectV2Item { id } }
+}`;
+const UPDATE_OPTIONS = `mutation($field: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]!) {
+	updateProjectV2Field(input: { fieldId: $field, singleSelectOptions: $options }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+}`;
+const DATA_TYPES = {
+	single_select: "SINGLE_SELECT",
+	text: "TEXT",
+	number: "NUMBER",
+	date: "DATE",
+	iteration: "ITERATION"
+};
+function fieldTypeOf(dataType) {
+	return Object.keys(DATA_TYPES).find((t) => DATA_TYPES[t] === dataType);
+}
+function toSummary(n) {
+	return {
+		id: n.id,
+		number: n.number,
+		name: n.title,
+		url: n.url,
+		closed: n.closed
+	};
+}
+function toOptionInput(o) {
+	return {
+		...o.id ? { id: o.id } : {},
+		name: o.name,
+		color: (o.color ?? "GRAY").toUpperCase(),
+		description: o.description ?? ""
+	};
+}
+/** The GitHub implementation of the `projects` capability, backed by Projects v2. */
+var GitHubProjects = class {
+	graphql;
+	/** Capability key, always `"projects"`. */
+	key = "projects";
+	/** Provider name, always `"github"`. */
+	providerName = "github";
+	repo;
+	constructor(graphql, opts) {
+		this.graphql = graphql;
+		this.repo = opts.repo;
+	}
+	/** Every board of the organization, open and closed. */
+	async list(owner) {
+		const boards = [];
+		let after = null;
+		for (;;) {
+			const page = (await this.graphql.query(LIST_QUERY, {
+				owner,
+				after
+			})).organization.projectsV2;
+			boards.push(...page.nodes.map(toSummary));
+			if (!page.pageInfo.hasNextPage) return boards;
+			after = page.pageInfo.endCursor;
+		}
+	}
+	/** The open board with exactly this name. */
+	async find(owner, name) {
+		return (await this.list(owner)).find((b) => !b.closed && b.name === name);
+	}
+	/**
+	* Makes a board. With `template.source` naming an open board it is copied (fields, options, views and automation
+	* rules, no items); otherwise the board is created and brought in line with the template.
+	*/
+	async create(owner, name, template) {
+		const ownerId = await this.ownerId(owner);
+		const source = template.source ? await this.find(owner, template.source) : void 0;
+		if (source) return toSummary((await this.graphql.query(`mutation($project: ID!, $owner: ID!, $title: String!) {
+	copyProjectV2(input: { projectId: $project, ownerId: $owner, title: $title, includeDraftIssues: false }) { projectV2 { ${PROJECT_FIELDS} } }
+}`, {
+			project: source.id,
+			owner: ownerId,
+			title: name
+		})).copyProjectV2.projectV2);
+		const board = toSummary((await this.graphql.query(`mutation($owner: ID!, $title: String!) {
+	createProjectV2(input: { ownerId: $owner, title: $title }) { projectV2 { ${PROJECT_FIELDS} } }
+}`, {
+			owner: ownerId,
+			title: name
+		})).createProjectV2.projectV2);
+		await this.ensure(owner, board, template);
+		return board;
+	}
+	/** Closes the board; `updateProjectV2` with `closed: true` is the only way, and reversible. */
+	async close(_owner, board) {
+		await this.graphql.query(`mutation($project: ID!) { updateProjectV2(input: { projectId: $project, closed: true }) { projectV2 { id } } }`, { project: board.id });
+	}
+	/** The live board: statuses, other fields, views and automation rules. */
+	async read(_owner, board) {
+		const raw = await this.readRaw(board.id);
+		const status = raw.fields.find((f) => f.name === STATUS_FIELD);
+		const fields = [];
+		for (const f of raw.fields) {
+			const type = fieldTypeOf(f.dataType);
+			if (!type || f.name === STATUS_FIELD) continue;
+			fields.push({
+				name: f.name,
+				type,
+				...f.options ? { options: f.options.map((o) => o.name) } : {}
+			});
+		}
+		const views = [];
+		for (const v of raw.views) {
+			const layout = v.layout === "BOARD_LAYOUT" ? "board" : v.layout === "TABLE_LAYOUT" ? "table" : void 0;
+			if (!layout) continue;
+			views.push({
+				name: v.name,
+				layout,
+				...v.filter ? { filter: v.filter } : {},
+				...v.groupBy[0] ? { groupBy: v.groupBy[0] } : {}
+			});
+		}
+		return {
+			board: raw.summary,
+			statuses: (status?.options ?? []).map((o) => o.name),
+			fields,
+			views,
+			rules: raw.rules.map(({ name, enabled }) => ({
+				name,
+				enabled
+			}))
+		};
+	}
+	/**
+	* Brings the board in line with the template. Never deletes a field, option or view, and never sends an option
+	* list without ids. Stops (throws) when the status field cannot be read.
+	*/
+	async ensure(_owner, board, template) {
+		const raw = await this.readRaw(board.id);
+		const status = raw.fields.find((f) => f.name === STATUS_FIELD && f.options);
+		if (!status) throw new Error(`cannot read the "${STATUS_FIELD}" field of board "${board.name}"; stopped before any write so no item loses its status`);
+		const changes = [];
+		const todos = [];
+		const statusChanges = await this.ensureOptions(board, status, template.statuses.map((s) => ({
+			name: s.name,
+			color: s.color,
+			description: s.description
+		})));
+		changes.push(...statusChanges.map((c) => `status ${c}`));
+		for (const want of template.fields) {
+			const have = raw.fields.find((f) => f.name === want.name);
+			if (!have) {
+				await this.createField(board.id, want);
+				changes.push(`field ${want.name} created`);
+				continue;
+			}
+			if (fieldTypeOf(have.dataType) !== want.type) {
+				todos.push(`field "${want.name}" is ${have.dataType} but the template says ${want.type}; change it by hand`);
+				continue;
+			}
+			if (want.type === "single_select" && have.options && want.options) {
+				const diff = await this.ensureOptions(board, have, want.options.map((name) => ({ name })));
+				changes.push(...diff.map((c) => `field ${want.name} option ${c}`));
+			}
+		}
+		for (const want of template.views) {
+			const have = raw.views.find((v) => v.name === want.name);
+			const layout = want.layout === "board" ? "BOARD_LAYOUT" : "TABLE_LAYOUT";
+			let viewId = have?.id;
+			if (!viewId) {
+				viewId = await this.createView(board.id, want.name, layout);
+				changes.push(`view ${want.name} created`);
+			} else if (have && have.layout !== layout) {
+				await this.updateView(viewId, { layout });
+				changes.push(`view ${want.name} layout set to ${want.layout}`);
+			}
+			if (want.filter !== void 0 && want.filter !== (have?.filter ?? "")) {
+				await this.updateView(viewId, { filter: want.filter });
+				changes.push(`view ${want.name} filter set`);
+			}
+			if (want.groupBy && have?.groupBy[0] !== want.groupBy) todos.push(`group view "${want.name}" by ${want.groupBy}; the API cannot set a view's grouping`);
+		}
+		for (const rule of template.rules ?? []) {
+			const have = raw.rules.find((r) => r.name === rule);
+			if (!have) todos.push(`create the automation rule "${rule}"; the API cannot create one`);
+			else if (!have.enabled) todos.push(`turn on the automation rule "${rule}"; the API cannot switch one`);
+		}
+		return {
+			created: false,
+			changes,
+			todos
+		};
+	}
+	/**
+	* Makes a single select field hold the wanted options in order, every existing one sent with its id. Options the
+	* template does not mention stay, after the wanted ones. Returns what changed (`Blocked added`, `order set`).
+	*/
+	async ensureOptions(board, field, wanted) {
+		/* v8 ignore next -- every caller passes a field it found with options; the fallback only satisfies the type */
+		const existing = field.options ?? [];
+		const next = [];
+		const changes = [];
+		for (const w of wanted) {
+			const have = existing.find((o) => o.name === w.name);
+			if (have) {
+				next.push({
+					id: have.id,
+					name: have.name,
+					color: (w.color ?? have.color).toUpperCase(),
+					description: w.description ?? have.description
+				});
+				if (next[next.length - 1].color !== have.color || next[next.length - 1].description !== have.description) changes.push(`${have.name} updated`);
+			} else {
+				next.push({
+					name: w.name,
+					color: (w.color ?? "GRAY").toUpperCase(),
+					description: w.description ?? ""
+				});
+				changes.push(`${w.name} added`);
+			}
+		}
+		for (const have of existing) if (!next.some((n) => n.id === have.id)) next.push({ ...have });
+		const sameOrder = next.length === existing.length && next.every((n, i) => n.id === existing[i]?.id);
+		if (changes.length === 0 && sameOrder) return [];
+		if (sameOrder === false && !changes.some((c) => c.endsWith("added"))) changes.push("order set");
+		const before = await this.fetchItems(board.id);
+		const snapshot = /* @__PURE__ */ new Map();
+		for (const item of before) {
+			const value = item.values[field.name];
+			if (value) snapshot.set(item.id, value);
+		}
+		await this.graphql.query(UPDATE_OPTIONS, {
+			field: field.id,
+			options: next.map(toOptionInput)
+		});
+		const afterField = (await this.readRaw(board.id)).fields.find((f) => f.id === field.id);
+		const afterItems = await this.fetchItems(board.id);
+		const afterValues = new Map(afterItems.map((i) => [i.id, i.values[field.name]]));
+		const lost = [...snapshot].filter(([itemId]) => !afterValues.get(itemId));
+		if (lost.length > 0) {
+			let restored = 0;
+			for (const [itemId, name] of lost) {
+				const option = afterField?.options?.find((o) => o.name === name);
+				if (!option) continue;
+				await this.graphql.query(SET_VALUE, {
+					project: board.id,
+					item: itemId,
+					field: field.id,
+					option: option.id
+				});
+				restored++;
+			}
+			throw new Error(`updating "${field.name}" on board "${board.name}" blanked ${lost.length} item value(s); wrote ${restored} back by option name`);
+		}
+		return changes;
+	}
+	async createField(projectId, want) {
+		await this.graphql.query(`mutation($project: ID!, $name: String!, $type: ProjectV2CustomFieldType!, $options: [ProjectV2SingleSelectFieldOptionInput!]) {
+	createProjectV2Field(input: { projectId: $project, name: $name, dataType: $type, singleSelectOptions: $options }) { projectV2Field { ... on ProjectV2SingleSelectField { id } } }
+}`, {
+			project: projectId,
+			name: want.name,
+			type: DATA_TYPES[want.type],
+			options: want.type === "single_select" ? (want.options ?? []).map((name) => toOptionInput({ name })) : void 0
+		});
+	}
+	async createView(projectId, name, layout) {
+		return (await this.graphql.query(`mutation($project: ID!, $name: String!, $layout: ProjectV2ViewLayout!) {
+	createProjectV2View(input: { projectId: $project, name: $name, layout: $layout }) { projectV2View { id } }
+}`, {
+			project: projectId,
+			name,
+			layout
+		})).createProjectV2View.projectV2View.id;
+	}
+	async updateView(viewId, change) {
+		await this.graphql.query(`mutation($view: ID!, $layout: ProjectV2ViewLayout, $filter: String) {
+	updateProjectV2View(input: { viewId: $view, layout: $layout, filter: $filter }) { projectV2View { id } }
+}`, {
+			view: viewId,
+			layout: change.layout,
+			filter: change.filter
+		});
+	}
+	/** The board's issues and pull requests with their status, whether they are open and their open blockers. */
+	async items(_owner, board, template) {
+		const categories = new Map(template.statuses.map((s) => [s.name, s.category]));
+		return (await this.fetchItems(board.id)).map((i) => {
+			const status = i.values[STATUS_FIELD];
+			const category = status ? categories.get(status) : void 0;
+			return {
+				key: this.keyOf(i.repo, i.number),
+				title: i.title,
+				open: i.open,
+				...status ? { status } : {},
+				...category ? { category } : {},
+				blockedBy: i.blockers.map((b) => this.keyOf(b.repo, b.number))
+			};
+		});
+	}
+	/** Puts an item in a status; `transitioned` is false when it already is there. */
+	async setStatus(_owner, board, key, status) {
+		const ref = this.parseKey(key);
+		const field = (await this.readRaw(board.id)).fields.find((f) => f.name === STATUS_FIELD && f.options);
+		const option = field?.options?.find((o) => o.name === status);
+		if (!field || !option) throw new Error(`board "${board.name}" has no status "${status}"`);
+		const item = (await this.fetchItems(board.id)).find((i) => i.repo === ref.repo && i.number === ref.number);
+		if (!item) throw new Error(`${key} is not on board "${board.name}"`);
+		if (item.values[STATUS_FIELD] === status) return {
+			transitioned: false,
+			status
+		};
+		await this.graphql.query(SET_VALUE, {
+			project: board.id,
+			item: item.id,
+			field: field.id,
+			option: option.id
+		});
+		return {
+			transitioned: true,
+			status,
+			via: "project field set"
+		};
+	}
+	/**
+	* Puts the open items of `from` on `to` with their status and priority, only where the target has no value;
+	* closed and merged ones stay, and are set to the template's done status when theirs is not a done one.
+	*/
+	async move(_owner, from, to, template) {
+		const report = {
+			moved: [],
+			kept: [],
+			left: []
+		};
+		const [source, target, fromRaw, toRaw] = await Promise.all([
+			this.fetchItems(from.id),
+			this.fetchItems(to.id),
+			this.readRaw(from.id),
+			this.readRaw(to.id)
+		]);
+		const done = template.statuses.find((s) => s.category === "done")?.name;
+		const doneNames = new Set(template.statuses.filter((s) => s.category === "done").map((s) => s.name));
+		const carried = [STATUS_FIELD, PRIORITY_FIELD];
+		for (const item of source) {
+			const key = this.keyOf(item.repo, item.number);
+			if (!item.open) {
+				const current = item.values[STATUS_FIELD];
+				if (done && (!current || !doneNames.has(current))) await this.setOption(from.id, fromRaw, item.id, STATUS_FIELD, done);
+				report.left.push(key);
+				continue;
+			}
+			let targetItem = target.find((t) => t.contentId === item.contentId);
+			if (targetItem) report.kept.push(key);
+			else {
+				const data = await this.graphql.query(`mutation($project: ID!, $content: ID!) { addProjectV2ItemById(input: { projectId: $project, contentId: $content }) { item { id } } }`, {
+					project: to.id,
+					content: item.contentId
+				});
+				targetItem = {
+					...item,
+					id: data.addProjectV2ItemById.item.id,
+					values: {}
+				};
+				report.moved.push(key);
+			}
+			for (const name of carried) {
+				const value = item.values[name];
+				if (value && !targetItem.values[name]) await this.setOption(to.id, toRaw, targetItem.id, name, value);
+			}
+		}
+		return report;
+	}
+	/** A `holocron doctor` smoke check: how many boards the token sees in the configured repository's organization. */
+	async whoami() {
+		try {
+			return {
+				ok: true,
+				boards: (await this.list(this.repo.split("/")[0] ?? "")).length
+			};
+		} catch {
+			return {
+				ok: false,
+				boards: 0
+			};
+		}
+	}
+	/** Sets a single select value by option name; a field or option the board lacks is skipped. */
+	async setOption(projectId, raw, itemId, fieldName, optionName) {
+		const field = raw.fields.find((f) => f.name === fieldName && f.options);
+		const option = field?.options?.find((o) => o.name === optionName);
+		if (!field || !option) return;
+		await this.graphql.query(SET_VALUE, {
+			project: projectId,
+			item: itemId,
+			field: field.id,
+			option: option.id
+		});
+	}
+	async ownerId(owner) {
+		return (await this.graphql.query(OWNER_QUERY, { owner })).organization.id;
+	}
+	async readRaw(id) {
+		const n = (await this.graphql.query(BOARD_QUERY, { id })).node;
+		if (!n) throw new Error(`board ${id} not found`);
+		return {
+			summary: toSummary(n),
+			fields: n.fields.nodes.filter((f) => f.id).map((f) => ({
+				id: f.id,
+				name: f.name,
+				dataType: f.dataType,
+				...f.options ? { options: f.options } : {}
+			})),
+			views: n.views.nodes.map((v) => ({
+				id: v.id,
+				name: v.name,
+				layout: v.layout,
+				filter: v.filter,
+				groupBy: (v.groupByFields?.nodes ?? []).map((g) => g.name)
+			})),
+			rules: n.workflows.nodes.map((w) => ({
+				id: w.id,
+				name: w.name,
+				enabled: w.enabled
+			}))
+		};
+	}
+	async fetchItems(id) {
+		const items = [];
+		let after = null;
+		for (;;) {
+			const page = (await this.graphql.query(ITEMS_QUERY, {
+				id,
+				after
+			})).node.items;
+			for (const n of page.nodes) {
+				const c = n.content;
+				if (!c || !c.repository) continue;
+				const values = {};
+				for (const v of n.fieldValues.nodes) if (v.name && v.field?.name) values[v.field.name] = v.name;
+				items.push({
+					id: n.id,
+					contentId: c.id,
+					repo: c.repository.nameWithOwner,
+					number: c.number,
+					title: c.title,
+					open: c.state === "OPEN",
+					values,
+					blockers: (c.blockedBy?.nodes ?? []).filter((b) => b.state === "OPEN").map((b) => ({
+						repo: b.repository.nameWithOwner,
+						number: b.number
+					}))
+				});
+			}
+			if (!page.pageInfo.hasNextPage) return items;
+			after = page.pageInfo.endCursor;
+		}
+	}
+	keyOf(repo, number) {
+		return repo === this.repo ? `#${number}` : `${repo}#${number}`;
+	}
+	parseKey(key) {
+		const m = /^(?:([^#\s]+))?#?(\d+)$/.exec(key.trim());
+		const hasRepo = key.includes("#") && m?.[1];
+		if (!m) throw new Error(`not an issue key: ${key}`);
+		return {
+			repo: hasRepo ? m[1] : this.repo,
+			number: Number(m[2])
+		};
+	}
+};
 // src/sodium.ts
 /**
 * libsodium sealed-box encryption for GitHub Actions secrets.
@@ -1166,6 +1663,10 @@ function issues(ctx) {
 	if (ctx.options.labels !== void 0) opts.labels = ctx.options.labels;
 	return new GitHubIssues(ctx.client, opts);
 }
+/** Builds the `projects` capability: GitHub Projects v2 over GraphQL, with items keyed relative to the configured repo. */
+function projects(ctx) {
+	return new GitHubProjects(ctx.client.graphql, { repo: ctx.repo });
+}
 /** Creates the plugin, resolving a token per capability when it is first used. */
 function createPlugin(options) {
 	function makeCtx(resolver) {
@@ -1253,7 +1754,8 @@ function createPlugin(options) {
 			ci: () => ci(makeCtx(resolveReadToken)),
 			secrets: () => makeSecrets(),
 			environments: () => environments(makeCtx(resolveAdminToken)),
-			issues: () => issues(makeCtx(resolveIssuesToken))
+			issues: () => issues(makeCtx(resolveIssuesToken)),
+			projects: () => projects(makeCtx(resolveOrgToken))
 		}
 	};
 }
@@ -1274,4 +1776,4 @@ const tokens = [
 	resolveUserSyncToken,
 	resolveOrgToken
 ].map((resolver) => resolver.token);
-export { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubSecrets, GitHubSource, ci, createFeatureResolver, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, resolveAdminToken, resolveDeployToken, resolveIssuesToken, resolveOrgToken, resolveReadToken, resolveReleaseToken, resolveSecretsToken, resolveSyncToken, resolveUserSyncToken, secrets, source, syncLabels, syncTeams, tokens, verifyToken };
+export { AUTH_HINT, AuthError, GitHubCi, GitHubEnvironments, GitHubIssues, GitHubProjects, GitHubSecrets, GitHubSource, ci, createFeatureResolver, createGitHubClient, createPlugin, encryptSecret, environments, issues, normalizeTeamEntry, projects, resolveAdminToken, resolveDeployToken, resolveIssuesToken, resolveOrgToken, resolveReadToken, resolveReleaseToken, resolveSecretsToken, resolveSyncToken, resolveUserSyncToken, secrets, source, syncLabels, syncTeams, tokens, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-github",
-  "version": "5.0.0-alpha.339",
+  "version": "5.0.0-alpha.340",
   "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.0.5",
-    "@theholocron/cli": "5.0.0-alpha.339",
-    "@theholocron/eslint-config": "^8.9.0-alpha.8",
     "@theholocron/fs-utils": "^1.17.0-alpha.1",
-    "@theholocron/github-client": "^1.58.0-alpha.7",
-    "@theholocron/http-client": "^1.58.0-alpha.7",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
-    "@theholocron/vitest-config": "^8.9.0-alpha.8",
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/http-client": "^1.58.0-alpha.8",
     "@theholocron/misc-utils": "^1.17.0-alpha.1",
-    "@theholocron/tsconfig": "^8.9.0-alpha.8"
+    "@theholocron/cli": "5.0.0-alpha.340",
+    "@theholocron/vitest-config": "^8.9.0-alpha.8",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
+    "@theholocron/tsconfig": "^8.9.0-alpha.8",
+    "@theholocron/github-client": "^1.58.0-alpha.8"
   },
   "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.339"
+    "@theholocron/cli": "5.0.0-alpha.340"
   },
   "engines": {
     "node": ">=22"