@theholocron/cli 3.34.6 → 3.35.0

package/dist/capabilities/index.d.mts

@@ -157,6 +157,14 @@ interface Source extends ProviderIdentity {
    * Optional — providers that don't support setting a homepage omit this.
    */
   syncHomepage?(homepage: string): Promise<string>;
+  /**
+   * Fetch a pull request by number. The `repo` override lets callers look up
+   * a PR in a different repo than the one the plugin is scoped to — useful
+   * when the cleanup command targets another repo's PR (e.g. docs PR from
+   * the holocron repo context).
+   * Optional — providers without a PR concept omit this.
+   */
+  getPullRequest?(number: number, repo?: string): Promise<PullRequest>;
   /**
    * Enable or update GitHub Pages for the repository.
    * Idempotent: POST to create, PUT to update existing settings.
@@ -178,6 +186,17 @@ interface PagesConfig {
   /** Enforce HTTPS. Only effective once the custom domain is DNS-verified. */
   https?: boolean;
 }
+interface PullRequest {
+  number: number;
+  title: string;
+  /** "open" | "closed" — GitHub marks merged PRs as "closed". */
+  state: "open" | "closed";
+  /** True when the PR was merged (as opposed to closed without merging). */
+  merged: boolean;
+  /** The head branch name (e.g. "fix/my-change"). */
+  branch: string;
+  url: string;
+}
 type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
 interface CiRun {
   id: string | number;
@@ -340,6 +359,7 @@ interface DeploymentRecord {
   /** Named environment if one was targeted; undefined for branch previews. */
   target?: DeploymentTrigger;
   status: "queued" | "building" | "ready" | "error" | "cancelled";
+  createdAt?: string;
 }
 interface Deployment extends ProviderIdentity {
   readonly key: "deployment";
@@ -366,6 +386,16 @@ interface Deployment extends ProviderIdentity {
     target?: DeploymentTrigger;
   }): Promise<DeploymentRecord>;
   getDeployment(deploymentId: string): Promise<DeploymentRecord>;
+  /**
+   * List preview deployments for a specific branch alias (e.g. "repo-pr-42").
+   * Optional — providers that don't support listing by branch omit this.
+   */
+  listPreviewDeployments?(projectId: string, branch: string): Promise<DeploymentRecord[]>;
+  /**
+   * Delete specific preview deployments by id. Returns the count deleted.
+   * Optional — providers that don't support deletion omit this.
+   */
+  deletePreviewDeployments?(projectId: string, deploymentIds: string[]): Promise<number>;
   /**
    * Add a custom domain (or wildcard) to the project. Idempotent — no-op
    * when the domain is already present. Optional: providers without a custom
@@ -616,4 +646,4 @@ type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
 type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
 declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
 //#endregion
-export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, NormalizedAuthUser, Notifications, Observability, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, isMulti };
+export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, NormalizedAuthUser, Notifications, Observability, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, isMulti };

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import path, { basename, dirname, join, relative, resolve } from "node:path";
-import { input, select } from "@inquirer/prompts";
+import { checkbox, input, select } from "@inquirer/prompts";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { AuthError, ProviderApiError, ProviderApiError as ProviderApiError$1 } from "@theholocron/http-client";
@@ -491,6 +491,216 @@ async function tryLoadHint(importer, packageName) {
 	}
 }
 //#endregion
+//#region src/loader.ts
+var LoaderError = class extends Error {
+	name = "LoaderError";
+};
+var PluginLoader = class {
+	config;
+	context;
+	importer;
+	registry = /* @__PURE__ */ new Map();
+	constructor(config, context, importer = defaultImporter) {
+		this.config = config;
+		this.context = context;
+		this.importer = importer;
+	}
+	/** Imports every configured plugin and builds the capability registry. */
+	async load() {
+		const entries = Object.entries(this.config.providers);
+		for (const [key, entry] of entries) {
+			if (!entry) continue;
+			if (entry.cardinality === "single") this.registry.set(key, await this.loadOne(key, entry.tuple));
+			else {
+				const impls = [];
+				for (const tuple of entry.tuples) impls.push(await this.loadOne(key, tuple));
+				this.registry.set(key, impls);
+			}
+		}
+	}
+	/**
+	* Type-safe lookup. Single-cardinality keys return one impl;
+	* many-cardinality keys return an array. `ResolvedCapability<K>`
+	* encodes the split via the `CARDINALITY` map.
+	*/
+	get(key) {
+		const impl = this.registry.get(key);
+		if (impl === void 0) throw new LoaderError(`capability \`${key}\` is not loaded — is it declared in holocron.config.json?`);
+		return impl;
+	}
+	/** Whether a capability has been loaded. */
+	has(key) {
+		return this.registry.has(key);
+	}
+	/** All capability keys currently loaded. Useful for the doctor command. */
+	loadedKeys() {
+		return Array.from(this.registry.keys());
+	}
+	/** Internal — invoke a plugin's capability factory and return the impl. */
+	async loadOne(key, tuple) {
+		const mod = await this.importer(tuple.packageName).catch((err) => {
+			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
+		});
+		if (isPluginModule(mod)) {
+			const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
+			const factory = mod.createPlugin({
+				...this.projectDefaults(),
+				...this.context,
+				...effectiveToken !== void 0 ? { cliToken: effectiveToken } : {},
+				cliTokens: void 0,
+				...tuple.options
+			}).capabilities[key];
+			if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
+			return factory();
+		}
+		if (isCapabilityConfigModule(mod)) {
+			const cap = mod.default;
+			return this.loadOne(key, {
+				provider: cap.provider,
+				packageName: resolvePluginPackage(cap.provider),
+				options: {
+					...cap.options,
+					...tuple.options
+				}
+			});
+		}
+		throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\` or a capability config ({ provider, options? })`);
+	}
+	/**
+	* Project-level defaults that get merged into every plugin's options
+	* unless overridden by the CLI context or per-plugin tuple options.
+	* See `.notes/tech-setup-and-config.spec.md` §Design.
+	*/
+	projectDefaults() {
+		const defaults = {};
+		if (this.config.repo?.name) defaults.repo = this.config.repo.name;
+		return defaults;
+	}
+};
+/** Default importer — native dynamic import. */
+const defaultImporter = async (pkg) => {
+	return import(pkg);
+};
+function isPluginModule(mod) {
+	return typeof mod.createPlugin === "function";
+}
+function isCapabilityConfigModule(mod) {
+	return typeof mod.default?.provider === "string";
+}
+//#endregion
+//#region src/commands/cleanup-preview.ts
+function prStateLabel(pr) {
+	if (pr.merged) return style.success("merged");
+	if (pr.state === "closed") return style.dim("closed (not merged)");
+	return style.warn("open");
+}
+async function runCleanupPreview(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	// c8 ignore next -- real PluginLoader construction is integration-level; unit tests always supply loader
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	if (!loader.has("source")) throw new Error("source capability is not configured — add a source provider to holocron.config.json");
+	const source = loader.get("source");
+	if (!source.getPullRequest) throw new Error(`${source.providerName} source provider does not support getPullRequest`);
+	let pr;
+	try {
+		pr = await source.getPullRequest(input.prNumber, input.repo);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to fetch PR #${input.prNumber}: ${message}`, { cause: err });
+	}
+	const branch = `${(input.repo ?? input.loaded.resolved.repo?.name ?? "").split("/").pop()}-pr-${pr.number}`;
+	print("");
+	print(`${style.header(`PR #${pr.number}`)} — ${pr.title}`);
+	print(`  Status : ${prStateLabel(pr)}  |  Branch : ${style.dim(pr.branch)}`);
+	print(`  URL    : ${style.dim(pr.url)}`);
+	print(`  CF alias : ${style.dim(branch)}`);
+	print("");
+	if (!loader.has("deployment")) throw new Error("deployment capability is not configured — add a deployment provider to holocron.config.json");
+	const deploy = loader.get("deployment");
+	if (!deploy.listPreviewDeployments || !deploy.deletePreviewDeployments) throw new Error(`${deploy.providerName} deployment provider does not support preview cleanup`);
+	let deployments;
+	try {
+		deployments = await deploy.listPreviewDeployments(input.project, branch);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to list deployments: ${message}`, { cause: err });
+	}
+	if (deployments.length === 0) {
+		print(style.dim(`No deployments found for branch ${branch}.`));
+		return {
+			pr,
+			branch,
+			found: 0,
+			deleted: 0,
+			status: "none"
+		};
+	}
+	print(`Found ${deployments.length} deployment${deployments.length === 1 ? "" : "s"} for ${style.dim(branch)}:`);
+	print("");
+	if (pr.state === "open") {
+		print(style.warn(`PR #${pr.number} is still open. Deleting its preview deployments will break the live preview link.`));
+		print(style.warn("Nothing is pre-selected — check the deployments you want to remove."));
+		print("");
+	}
+	const choices = deployments.map((d) => {
+		return {
+			name: `${d.id.includes(":") ? d.id.split(":").pop() : d.id}  ${d.createdAt ? style.dim(d.createdAt.slice(0, 10)) : ""}  ${style.dim(d.url)}`,
+			value: d.id,
+			checked: pr.state !== "open"
+		};
+	});
+	let selected;
+	try {
+		selected = await checkbox({
+			message: "Select deployments to delete (space to toggle, a to select all, enter to confirm):",
+			choices
+		});
+	} catch {
+		print(style.dim("Aborted."));
+		return {
+			pr,
+			branch,
+			found: deployments.length,
+			deleted: 0,
+			status: "aborted"
+		};
+	}
+	if (selected.length === 0) {
+		print(style.dim("Nothing selected — no deployments deleted."));
+		return {
+			pr,
+			branch,
+			found: deployments.length,
+			deleted: 0,
+			status: "aborted"
+		};
+	}
+	print("");
+	try {
+		const count = await deploy.deletePreviewDeployments(input.project, selected);
+		print(style.success(`Deleted ${count} deployment${count === 1 ? "" : "s"}.`));
+		return {
+			pr,
+			branch,
+			found: deployments.length,
+			deleted: count,
+			status: "ok"
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		print(style.fail(message));
+		return {
+			pr,
+			branch,
+			found: deployments.length,
+			deleted: 0,
+			status: "fail",
+			message
+		};
+	}
+}
+//#endregion
 //#region src/commands/clone.ts
 function encodeTokenForGitHttpAuth(token) {
 	const trimmed = token.trim();
@@ -593,103 +803,6 @@ async function runClone(input) {
 	};
 }
 //#endregion
-//#region src/loader.ts
-var LoaderError = class extends Error {
-	name = "LoaderError";
-};
-var PluginLoader = class {
-	config;
-	context;
-	importer;
-	registry = /* @__PURE__ */ new Map();
-	constructor(config, context, importer = defaultImporter) {
-		this.config = config;
-		this.context = context;
-		this.importer = importer;
-	}
-	/** Imports every configured plugin and builds the capability registry. */
-	async load() {
-		const entries = Object.entries(this.config.providers);
-		for (const [key, entry] of entries) {
-			if (!entry) continue;
-			if (entry.cardinality === "single") this.registry.set(key, await this.loadOne(key, entry.tuple));
-			else {
-				const impls = [];
-				for (const tuple of entry.tuples) impls.push(await this.loadOne(key, tuple));
-				this.registry.set(key, impls);
-			}
-		}
-	}
-	/**
-	* Type-safe lookup. Single-cardinality keys return one impl;
-	* many-cardinality keys return an array. `ResolvedCapability<K>`
-	* encodes the split via the `CARDINALITY` map.
-	*/
-	get(key) {
-		const impl = this.registry.get(key);
-		if (impl === void 0) throw new LoaderError(`capability \`${key}\` is not loaded — is it declared in holocron.config.json?`);
-		return impl;
-	}
-	/** Whether a capability has been loaded. */
-	has(key) {
-		return this.registry.has(key);
-	}
-	/** All capability keys currently loaded. Useful for the doctor command. */
-	loadedKeys() {
-		return Array.from(this.registry.keys());
-	}
-	/** Internal — invoke a plugin's capability factory and return the impl. */
-	async loadOne(key, tuple) {
-		const mod = await this.importer(tuple.packageName).catch((err) => {
-			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
-		});
-		if (isPluginModule(mod)) {
-			const effectiveToken = this.context.cliTokens?.[tuple.provider] ?? this.context.cliToken;
-			const factory = mod.createPlugin({
-				...this.projectDefaults(),
-				...this.context,
-				...effectiveToken !== void 0 ? { cliToken: effectiveToken } : {},
-				cliTokens: void 0,
-				...tuple.options
-			}).capabilities[key];
-			if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
-			return factory();
-		}
-		if (isCapabilityConfigModule(mod)) {
-			const cap = mod.default;
-			return this.loadOne(key, {
-				provider: cap.provider,
-				packageName: resolvePluginPackage(cap.provider),
-				options: {
-					...cap.options,
-					...tuple.options
-				}
-			});
-		}
-		throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\` or a capability config ({ provider, options? })`);
-	}
-	/**
-	* Project-level defaults that get merged into every plugin's options
-	* unless overridden by the CLI context or per-plugin tuple options.
-	* See `.notes/tech-setup-and-config.spec.md` §Design.
-	*/
-	projectDefaults() {
-		const defaults = {};
-		if (this.config.repo?.name) defaults.repo = this.config.repo.name;
-		return defaults;
-	}
-};
-/** Default importer — native dynamic import. */
-const defaultImporter = async (pkg) => {
-	return import(pkg);
-};
-function isPluginModule(mod) {
-	return typeof mod.createPlugin === "function";
-}
-function isCapabilityConfigModule(mod) {
-	return typeof mod.default?.provider === "string";
-}
-//#endregion
 //#region src/commands/deploy.ts
 async function runDeploy(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -5805,6 +5918,33 @@ try {
 			branch: argv.branch,
 			...argv.target ? { target: argv.target } : {}
 		})).status === "fail") process.exitCode = 1;
+	}).command("cleanup-preview <pr>", "List and delete Cloudflare Pages preview deployments for a GitHub PR", (y) => y.positional("pr", {
+		type: "number",
+		demandOption: true,
+		describe: "PR number to clean up"
+	}).option("project", {
+		type: "string",
+		demandOption: true,
+		describe: "Cloudflare Pages project name (e.g. theholocron-preview)"
+	}).option("repo", {
+		type: "string",
+		describe: "GitHub repo as owner/name — defaults to the repo in holocron.config"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const loaded = await loadConfig(argv.cwd);
+		if ((await runCleanupPreview({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			prNumber: argv.pr,
+			project: argv.project,
+			...argv.repo ? { repo: argv.repo } : {}
+		})).status === "fail") process.exitCode = 1;
 	}).command("npm", "npm-related monorepo utilities", (y) => y.command("bump-versions <new-version>", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (yy) => yy.positional("new-version", {
 		type: "string",
 		demandOption: true,