@theholocron/cli 3.34.5 → 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));
@@ -4649,7 +4762,7 @@ var dependencies_default = "name: Dependencies\n\non: # yamllint disable-line ru
 var deploy_default = "name: Deploy\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      type:\n        description: \"Type of deployment: docs or storybook\"\n        required: true\n        type: string\n      name:\n        description: Repo name prefix used to filter the docs site package (<name>-site); omit to run pnpm -C docs build\n        required: false\n        type: string\n        default: \"\"\n      storybook-projects:\n        description: >\n          JSON array of { \"name\"?, \"workingDir\", \"outputDir\"? } objects for storybook deploys.\n          Each is built via `pnpm -C <workingDir> build:storybook`. If \"name\" is provided the\n          output is placed under `sandbox/<name>/`; omit \"name\" for single-repo deploys and the\n          output lands directly in `sandbox/`.\n        type: string\n        required: false\n        default: \"[]\"\n      build-script:\n        description: pnpm script that builds the Storybook static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: build:storybook\n      output-dir:\n        description: Directory where Storybook writes its static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: storybook-static\n\njobs:\n  deploy:\n    name: Deploy\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      pages: write\n      id-token: write\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' && inputs.name != '' }}\n        env:\n          SITE_NAME: ${{ inputs.name }}\n        run: pnpm --filter @theholocron/\"$SITE_NAME\"-site build\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' && inputs.name == '' }}\n        run: pnpm -C docs build\n\n      - name: Build Storybook projects\n        if: ${{ inputs.storybook-projects != '[]' }}\n        env:\n          PROJECTS: ${{ inputs.storybook-projects }}\n        run: |\n          echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n            workingDir=$(echo \"$project\" | jq -r '.workingDir')\n            pnpm -C \"$workingDir\" build:storybook\n          done\n\n      - name: Build Storybook\n        if: ${{ inputs.type == 'storybook' && inputs.storybook-projects == '[]' }}\n        env:\n          BUILD_SCRIPT: ${{ inputs.build-script }}\n        run: pnpm run \"$BUILD_SCRIPT\"\n\n      - name: Assemble site\n        env:\n          DEPLOY_TYPE: ${{ inputs.type }}\n          PROJECTS: ${{ inputs.storybook-projects }}\n          STORYBOOK_OUTPUT_DIR: ${{ inputs.output-dir }}\n        run: |\n          mkdir -p _site\n          if [ \"$DEPLOY_TYPE\" = \"docs\" ]; then\n            cp -r docs/dist/. _site/\n          fi\n          if [ \"$PROJECTS\" != \"[]\" ]; then\n            echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n              name=$(echo \"$project\" | jq -r '.name // \"\"')\n              workingDir=$(echo \"$project\" | jq -r '.workingDir')\n              outputDir=$(echo \"$project\" | jq -r '.outputDir // \"storybook-static\"')\n              if [ -n \"$name\" ]; then\n                target=\"_site/sandbox/${name}\"\n              else\n                target=\"_site/sandbox\"\n              fi\n              mkdir -p \"$target\"\n              cp -r \"${workingDir}/${outputDir}/.\" \"$target/\"\n            done\n          elif [ \"$DEPLOY_TYPE\" = \"storybook\" ]; then\n            mkdir -p _site/sandbox\n            cp -r \"${STORYBOOK_OUTPUT_DIR}/.\" _site/sandbox/\n          fi\n\n      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1\n        name: Upload pages artifact\n        with:\n          path: _site\n\n      - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5\n        id: deployment\n        name: Deploy to GitHub Pages\n";
 //#endregion
 //#region src/templates/workflows/deploy-preview.yml
-var deploy_preview_default = "name: Deploy Preview\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      type:\n        description: \"Type of deployment: docs or storybook\"\n        required: true\n        type: string\n      name:\n        description: Repo name prefix used to filter the docs site package (<name>-site); omit to run pnpm -C docs build\n        required: false\n        type: string\n        default: \"\"\n      storybook-projects:\n        description: >\n          JSON array of { \"name\"?, \"workingDir\", \"outputDir\"? } objects for storybook deploys.\n          Each is built via `pnpm -C <workingDir> build:storybook`. If \"name\" is provided the\n          output is placed under `sandbox/<name>/`; omit \"name\" for single-repo deploys and the\n          output lands directly in `sandbox/`.\n        type: string\n        required: false\n        default: \"[]\"\n      build-script:\n        description: pnpm script that builds the Storybook static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: build:storybook\n      output-dir:\n        description: Directory where Storybook writes its static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: storybook-static\n      cloudflare-project:\n        description: >\n          Cloudflare Pages project name. Falls back to the CLOUDFLARE_PAGES_PROJECT\n          org variable when omitted — set that variable once and all repos get previews\n          without per-repo config.\n        required: false\n        type: string\n        default: \"\"\n\njobs:\n  deploy-preview:\n    name: Deploy Preview\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      deployments: write\n      pull-requests: write\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' && inputs.name != '' }}\n        env:\n          SITE_NAME: ${{ inputs.name }}\n        run: pnpm --filter @theholocron/\"$SITE_NAME\"-site build\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' && inputs.name == '' }}\n        run: pnpm -C docs build\n\n      - name: Build Storybook projects\n        if: ${{ inputs.storybook-projects != '[]' }}\n        env:\n          PROJECTS: ${{ inputs.storybook-projects }}\n        run: |\n          echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n            workingDir=$(echo \"$project\" | jq -r '.workingDir')\n            pnpm -C \"$workingDir\" build:storybook\n          done\n\n      - name: Build Storybook\n        if: ${{ inputs.type == 'storybook' && inputs.storybook-projects == '[]' }}\n        env:\n          BUILD_SCRIPT: ${{ inputs.build-script }}\n        run: pnpm run \"$BUILD_SCRIPT\"\n\n      - name: Assemble site\n        env:\n          DEPLOY_TYPE: ${{ inputs.type }}\n          SITE_NAME: ${{ inputs.name }}\n          PROJECTS: ${{ inputs.storybook-projects }}\n          STORYBOOK_OUTPUT_DIR: ${{ inputs.output-dir }}\n        run: |\n          mkdir -p _site\n          if [ \"$DEPLOY_TYPE\" = \"docs\" ]; then\n            if [ -n \"$SITE_NAME\" ]; then\n              # Site built with base: /<name>/ — nest under _site/<name>/ so asset\n              # paths match (/name/_astro/... → served at /name/_astro/...).\n              mkdir -p \"_site/${SITE_NAME}\"\n              cp -r docs/dist/. \"_site/${SITE_NAME}/\"\n              # Redirect root to the base path so the preview URL lands correctly.\n              printf \"/ /%s/ 301\\n\" \"$SITE_NAME\" > _site/_redirects\n            else\n              cp -r docs/dist/. _site/\n            fi\n          fi\n          if [ \"$PROJECTS\" != \"[]\" ]; then\n            echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n              name=$(echo \"$project\" | jq -r '.name // \"\"')\n              workingDir=$(echo \"$project\" | jq -r '.workingDir')\n              outputDir=$(echo \"$project\" | jq -r '.outputDir // \"storybook-static\"')\n              if [ -n \"$name\" ]; then\n                target=\"_site/sandbox/${name}\"\n              else\n                target=\"_site/sandbox\"\n              fi\n              mkdir -p \"$target\"\n              cp -r \"${workingDir}/${outputDir}/.\" \"$target/\"\n            done\n          elif [ \"$DEPLOY_TYPE\" = \"storybook\" ]; then\n            mkdir -p _site/sandbox\n            cp -r \"${STORYBOOK_OUTPUT_DIR}/.\" _site/sandbox/\n          fi\n\n      - uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0\n        id: deploy\n        name: Deploy to Cloudflare Pages\n        # Skip when neither the per-repo input nor the org variable is set.\n        if: ${{ inputs.cloudflare-project != '' || vars.CLOUDFLARE_PAGES_PROJECT != '' }}\n        with:\n          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}\n          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}\n          packageManager: npm\n          command: >-\n            pages deploy _site\n            --project-name ${{ inputs.cloudflare-project || vars.CLOUDFLARE_PAGES_PROJECT }}\n            --branch ${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}\n            --commit-dirty=true\n\n      - name: Report preview URL\n        if: ${{ steps.deploy.outputs.pages-deployment-alias-url != '' }}\n        env:\n          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          ALIAS: ${{ steps.deploy.outputs.pages-deployment-alias-url }}\n          SITE_NAME: ${{ inputs.name }}\n          PROJECT: ${{ inputs.cloudflare-project || vars.CLOUDFLARE_PAGES_PROJECT }}\n        run: |\n          PREVIEW_URL=\"${ALIAS%/}${SITE_NAME:+/${SITE_NAME}}/\"\n          # GITHUB_HEAD_REF is the PR branch name — links the deployment to this PR's sidebar widget.\n          PAYLOAD=$(printf '{\"ref\":\"%s\",\"environment\":\"%s\",\"description\":\"Cloudflare Pages\",\"production_environment\":false,\"auto_merge\":false,\"required_contexts\":[]}' \\\n            \"$GITHUB_HEAD_REF\" \"${PROJECT} (Preview)\")\n          DEPLOY_ID=$(echo \"$PAYLOAD\" | gh api \"repos/${GITHUB_REPOSITORY}/deployments\" \\\n            --method POST --input - | jq -r '.id')\n          gh api \"repos/${GITHUB_REPOSITORY}/deployments/${DEPLOY_ID}/statuses\" \\\n            --method POST --field state=success --field environment_url=\"${PREVIEW_URL}\"\n";
+var deploy_preview_default = "name: Deploy Preview\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      type:\n        description: \"Type of deployment: docs or storybook\"\n        required: true\n        type: string\n      name:\n        description: Repo name prefix used to filter the docs site package (<name>-site); omit to run pnpm -C docs build\n        required: false\n        type: string\n        default: \"\"\n      storybook-projects:\n        description: >\n          JSON array of { \"name\"?, \"workingDir\", \"outputDir\"? } objects for storybook deploys.\n          Each is built via `pnpm -C <workingDir> build:storybook`. If \"name\" is provided the\n          output is placed under `sandbox/<name>/`; omit \"name\" for single-repo deploys and the\n          output lands directly in `sandbox/`.\n        type: string\n        required: false\n        default: \"[]\"\n      build-script:\n        description: pnpm script that builds the Storybook static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: build:storybook\n      output-dir:\n        description: Directory where Storybook writes its static output (single storybook, type:storybook only)\n        type: string\n        required: false\n        default: storybook-static\n      cloudflare-project:\n        description: >\n          Cloudflare Pages project name. Falls back to the CLOUDFLARE_PAGES_PROJECT\n          org variable when omitted — set that variable once and all repos get previews\n          without per-repo config.\n        required: false\n        type: string\n        default: \"\"\n\njobs:\n  deploy-preview:\n    name: Deploy Preview\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      deployments: write\n      pull-requests: write\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' && inputs.name != '' }}\n        env:\n          SITE_NAME: ${{ inputs.name }}\n        run: pnpm --filter @theholocron/\"$SITE_NAME\"-site build\n\n      - name: Build docs site\n        if: ${{ inputs.type == 'docs' && inputs.name == '' }}\n        run: pnpm -C docs build\n\n      - name: Build Storybook projects\n        if: ${{ inputs.storybook-projects != '[]' }}\n        env:\n          PROJECTS: ${{ inputs.storybook-projects }}\n        run: |\n          echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n            workingDir=$(echo \"$project\" | jq -r '.workingDir')\n            pnpm -C \"$workingDir\" build:storybook\n          done\n\n      - name: Build Storybook\n        if: ${{ inputs.type == 'storybook' && inputs.storybook-projects == '[]' }}\n        env:\n          BUILD_SCRIPT: ${{ inputs.build-script }}\n        run: pnpm run \"$BUILD_SCRIPT\"\n\n      - name: Assemble site\n        env:\n          DEPLOY_TYPE: ${{ inputs.type }}\n          SITE_NAME: ${{ inputs.name }}\n          PROJECTS: ${{ inputs.storybook-projects }}\n          STORYBOOK_OUTPUT_DIR: ${{ inputs.output-dir }}\n        run: |\n          mkdir -p _site\n          if [ \"$DEPLOY_TYPE\" = \"docs\" ]; then\n            if [ -n \"$SITE_NAME\" ]; then\n              # Site built with base: /<name>/ — nest under _site/<name>/ so asset\n              # paths match (/name/_astro/... → served at /name/_astro/...).\n              mkdir -p \"_site/${SITE_NAME}\"\n              cp -r docs/dist/. \"_site/${SITE_NAME}/\"\n              # Redirect root to the base path so the preview URL lands correctly.\n              printf \"/ /%s/ 301\\n\" \"$SITE_NAME\" > _site/_redirects\n            else\n              cp -r docs/dist/. _site/\n            fi\n          fi\n          if [ \"$PROJECTS\" != \"[]\" ]; then\n            echo \"$PROJECTS\" | jq -c '.[]' | while IFS= read -r project; do\n              name=$(echo \"$project\" | jq -r '.name // \"\"')\n              workingDir=$(echo \"$project\" | jq -r '.workingDir')\n              outputDir=$(echo \"$project\" | jq -r '.outputDir // \"storybook-static\"')\n              if [ -n \"$name\" ]; then\n                target=\"_site/sandbox/${name}\"\n              else\n                target=\"_site/sandbox\"\n              fi\n              mkdir -p \"$target\"\n              cp -r \"${workingDir}/${outputDir}/.\" \"$target/\"\n            done\n          elif [ \"$DEPLOY_TYPE\" = \"storybook\" ]; then\n            mkdir -p _site/sandbox\n            cp -r \"${STORYBOOK_OUTPUT_DIR}/.\" _site/sandbox/\n          fi\n\n      - name: Install Wrangler\n        # The action's install step runs npm/pnpm in the repo root; pnpm fails\n        # because it rejects adding to a workspace root without -w, and npm fails\n        # because package.json contains pnpm catalog: references it cannot parse.\n        # Pre-installing from /tmp (no package.json) lets the action find wrangler\n        # already on PATH and skip its own install entirely.\n        working-directory: /tmp\n        run: npm install -g wrangler@4\n\n      - uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0\n        id: deploy\n        name: Deploy to Cloudflare Pages\n        # Skip when neither the per-repo input nor the org variable is set.\n        if: ${{ inputs.cloudflare-project != '' || vars.CLOUDFLARE_PAGES_PROJECT != '' }}\n        with:\n          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}\n          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}\n          packageManager: npm\n          command: >-\n            pages deploy _site\n            --project-name ${{ inputs.cloudflare-project || vars.CLOUDFLARE_PAGES_PROJECT }}\n            --branch ${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}\n            --commit-dirty=true\n\n      - name: Report preview URL\n        if: ${{ steps.deploy.outputs.pages-deployment-alias-url != '' }}\n        env:\n          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n          ALIAS: ${{ steps.deploy.outputs.pages-deployment-alias-url }}\n          SITE_NAME: ${{ inputs.name }}\n          PROJECT: ${{ inputs.cloudflare-project || vars.CLOUDFLARE_PAGES_PROJECT }}\n        run: |\n          PREVIEW_URL=\"${ALIAS%/}${SITE_NAME:+/${SITE_NAME}}/\"\n          # GITHUB_HEAD_REF is the PR branch name — links the deployment to this PR's sidebar widget.\n          PAYLOAD=$(printf '{\"ref\":\"%s\",\"environment\":\"%s\",\"description\":\"Cloudflare Pages\",\"production_environment\":false,\"auto_merge\":false,\"required_contexts\":[]}' \\\n            \"$GITHUB_HEAD_REF\" \"${PROJECT} (Preview)\")\n          DEPLOY_ID=$(echo \"$PAYLOAD\" | gh api \"repos/${GITHUB_REPOSITORY}/deployments\" \\\n            --method POST --input - | jq -r '.id')\n          gh api \"repos/${GITHUB_REPOSITORY}/deployments/${DEPLOY_ID}/statuses\" \\\n            --method POST --field state=success --field environment_url=\"${PREVIEW_URL}\"\n";
 //#endregion
 //#region src/templates/workflows/greetings.yml
 var greetings_default = "name: Greetings\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n\njobs:\n  greeting:\n    name: Greet first-time contributors\n    permissions:\n      issues: write\n      pull-requests: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 5\n    # Group by the issue/PR number so duplicate events don't race each other.\n    steps:\n      - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\n        name: Greet on first contribution\n        with:\n          script: |\n            // Only greet on the initial open — ignore synchronize, reopened, etc.\n            if (context.payload.action !== 'opened') return;\n\n            const actor = context.actor;\n            const { owner, repo } = context.repo;\n\n            // Payload inspection is more reliable than context.eventName for detecting\n            // whether this is an issue vs. PR event — works regardless of how GitHub\n            // propagates event names through workflow_call chains.\n            const isIssue = !!context.payload.issue && !context.payload.pull_request;\n            // listForRepo returns both issues and PRs (GitHub treats PRs as issues),\n            // sorted newest-first. Filter by type to track first-issue and first-PR\n            // independently, and avoid search-index eventual-consistency lag.\n            const { data: recent } = await github.rest.issues.listForRepo({\n              owner, repo,\n              creator: actor,\n              state: 'all',\n              per_page: 100\n            });\n\n            const sameType = recent.filter(item =>\n              isIssue ? !item.pull_request : !!item.pull_request\n            );\n\n            if (sameType.length !== 1) return;\n            const body = isIssue\n              ? `Hey @${actor}!\\n\\nWe really appreciate you taking the time to report an issue. The collaborators on this project attempt to help as many people as possible, but we are a limited number of volunteers, so it is possible that this will not be addressed as swiftly.\\n\\nYour patience is much appreciated and we will get back to you as quickly as possible.`\n              : `Hey @${actor}!\\n\\nWe really appreciate you taking the time to help out with this PR. The collaborators on this project attempt to help as many people as possible, but we are a limited number of volunteers, so it is possible that this will not be addressed as swiftly.\\n\\nYour patience is much appreciated and we will get back to you as quickly as possible.`;\n\n            await github.rest.issues.createComment({\n              owner,\n              repo,\n              issue_number: context.issue.number,\n              body\n            });\n";
@@ -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,