@theholocron/holocron-plugin-vercel 5.0.0-alpha.28 → 5.0.0-alpha.280

package/README.md

@@ -64,13 +64,18 @@ Capability covers:
   an app) — `defaultFramework` only applies to `ensureProject()`'s
   Git-linked path.
 - `getDeployment()` — fetch a deployment by id
-- `ensureCustomDomain()` — idempotent add (list → check → add). Adding
-  a domain new to the Vercel account returns `verified: false` with a
-  DNS verification challenge (usually a CNAME to a per-project target
-  Vercel generates — never a fixed well-known host). The returned DNS
-  record is handed to the configured `dns` provider by `holocron setup`.
-
-Declare the production domain in the Vercel provider options. On `holocron setup`,
+- `ensureCustomDomain()` — idempotent add (list → add-if-missing →
+  check DNS routing). Ownership (`verified`) and DNS routing are
+  separate: once a team already owns a domain's apex, every new
+  subdomain auto-verifies immediately with no fresh challenge, so
+  attachment alone can't tell you whether traffic is actually routed
+  to Vercel yet. `domains.config()` answers that regardless of
+  ownership state, returning a per-project CNAME target — never a
+  fixed well-known host — only when DNS isn't already configured. The
+  returned DNS record is handed to the configured `dns` provider by
+  `holocron repo setup`.
+
+Declare the production domain in the Vercel provider options. On `holocron repo setup`,
 the domain is attached to the project and any Vercel verification CNAME is
 upserted through the configured DNS provider:
 

package/dist/index.d.mts

@@ -1,22 +1,26 @@
-import { AuthError, DeployFunctionConfig, DeployFunctionResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, DnsRecordRequest, ResolveTokenInput } from "@theholocron/cli";
+import { AuthError, DeployFunctionConfig, DeployFunctionResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, DnsRecordRequest, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
 import { VercelClient, VercelClient as VercelClient$1, VercelClientOptions, createVercelClient } from "@theholocron/vercel-client";
-//#region src/auth.d.ts
-declare const resolveToken: (input?: ResolveTokenInput) => string;
-//#endregion
-//#region src/capabilities/deployment.d.ts
+/** Resolves the Vercel token from `--token`, `HOLOCRON_VERCEL_TOKEN`, `VERCEL_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
+export declare const resolveToken: import("@theholocron/cli").TokenResolver;
+/** Every token this plugin takes, for `holocron doctor tokens`. */
+export declare const tokens: PluginToken[];
 interface DeploymentOptions {
   /** Optional framework hint passed to project creates. Defaults to "nextjs". */
   defaultFramework?: string;
-  /** Custom domain that `holocron setup` should attach to this project. */
+  /** Custom domain that `holocron repo setup` should attach to this project. */
   domain?: string;
 }
-declare class VercelDeployment implements Deployment {
+/** The `deployment` capability for Vercel: projects, environment variables, deployments, functions and custom domains. */
+export declare class VercelDeployment implements Deployment {
   private readonly client;
+  /** The capability key, always `deployment`. */
   readonly key: "deployment";
+  /** The provider name, `vercel`. */
   readonly providerName = "vercel";
   readonly domain?: string;
   private readonly defaultFramework;
   constructor(client: () => VercelClient$1, opts?: DeploymentOptions);
+  /** Lists the projects the token can see, mapped to the provider-neutral shape. */
   listProjects(): Promise<DeploymentProject[]>;
   ensureProject(input: {
     name: string;
@@ -24,74 +28,78 @@ declare class VercelDeployment implements Deployment {
     repo?: string;
     rootDirectory?: string;
   }): Promise<DeploymentProject>;
+  /** Updates a project's preview-deployment and Git-provider deployment settings and returns the updated project. */
   updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
+  /** Lists the names of the project's environment variables that apply to `target`. */
   listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
+  /** Creates or updates (upsert) an environment variable on the project for `target`. */
   setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
   triggerDeployment(input: {
     projectId: string;
     branch: string;
     target?: DeploymentTrigger;
   }): Promise<DeploymentRecord>;
+  /** Fetches a deployment by id; the record's branch is the deployment's Git commit ref, or `null` when it has none. */
   getDeployment(deploymentId: string): Promise<DeploymentRecord>;
   deployFunction(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
   /**
-   * Idempotent — no-op when `hostname` is already on the project,
-   * matching `Deployment.ensureCustomDomain`'s contract (never break
-   * on re-runs, per CLAUDE.md's probe-then-act standard). Adding it
-   * the first time returns `verified: false` for a domain new to this
-   * Vercel account, plus a `verification` challenge — usually CNAME, a
-   * unique per-project target Vercel generates (never a fixed
-   * well-known host, confirmed via Vercel's own docs). Returned as a
-   * `DnsRecordRequest` — the caller (e.g. `holocron setup`'s
-   * custom-domain step) hands it straight to `dns.upsertRecord()`,
-   * same as `Wiki.dnsRecord()` already does for the wiki's own domain.
+   * Idempotent — matches `Deployment.ensureCustomDomain`'s contract
+   * (never break on re-runs, per CLAUDE.md's probe-then-act standard).
+   *
+   * Ownership (`domains.add`'s `verified`) and DNS routing are separate
+   * concerns: once a team already owns the domain's apex (true for any
+   * org with more than one project on the same domain), every new
+   * subdomain auto-verifies immediately with no `verification`
+   * challenge — re-adding an already-attached domain returns 409, not
+   * a fresh one. So attachment alone can't tell us whether traffic is
+   * actually routed to Vercel yet. `domains.config()` (Vercel's DNS
+   * *configuration* check) answers that regardless of ownership state:
+   * `misconfigured` + a `recommendedCNAME`, per-project, never a fixed
+   * well-known host — always read it from this response, never
+   * hardcode it. Returned as a `DnsRecordRequest` — the caller (e.g.
+   * `holocron repo setup`'s custom-domain step) hands it straight to
+   * `dns.upsertRecord()`, same as `Wiki.dnsRecord()` already does for
+   * the wiki's own domain.
    */
   ensureCustomDomain(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
   private getProjectByName;
 }
-//#endregion
-//#region src/verify-token.d.ts
-/**
- * `verifyToken` — plugin-level export used by `holocron auth set` +
- * `holocron auth check`. Hits `GET /v2/user` and translates the
- * response into the normalized `VerifyTokenResult` shape.
- */
-interface VerifyTokenSuccess {
-  ok: true;
-  subject: string;
-}
-interface VerifyTokenFailure {
-  ok: false;
-  message: string;
-}
-type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
 interface VerifyTokenOptions {
   baseUrl?: string;
   fetch?: typeof fetch;
 }
-declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
-//#endregion
-//#region src/index.d.ts
-interface VercelPluginOptions extends ResolveTokenInput {
+/** Checks a Vercel token by fetching the current user; the success subject is `user @` followed by the email, username, name or id, the failure carries the error message. */
+export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
+/** Options for the Vercel plugin: token resolution, team, defaults for new projects and test overrides. */
+export interface VercelPluginOptions extends ResolveTokenInput {
   /** Vercel team id. Set when working with a team-owned project. */
   teamId?: string;
   /** Default framework slug for new project creates. Defaults to "nextjs". */
   defaultFramework?: string;
-  /** Custom domain that `holocron setup` should attach to the Vercel project. */
+  /** Custom domain that `holocron repo setup` should attach to the Vercel project. */
   domain?: string;
   /** Override base URL for tests. */
   baseUrl?: string;
   /** Override `fetch` for tests. */
   fetch?: typeof fetch;
 }
-interface PluginContext {
+/** What the plugin's capabilities share: the options and a lazily built client. */
+export interface PluginContext {
+  /** The options the plugin was created with. */
   options: VercelPluginOptions;
+  /** Builds the Vercel client on first call and reuses it; the token is resolved then, not at plugin load. */
   client: () => VercelClient;
 }
-declare function createContext(options?: VercelPluginOptions): PluginContext;
-declare function deployment(ctx: PluginContext): Deployment;
-declare function createPlugin(options?: VercelPluginOptions): {
+/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
+export declare function createContext(options?: VercelPluginOptions): PluginContext;
+/** Builds the `deployment` capability from a plugin context, passing on `defaultFramework` and `domain` when set. */
+export declare function deployment(ctx: PluginContext): Deployment;
+/** Creates the Vercel plugin: a `connection` probe and the `deployment` capability. */
+export declare function createPlugin(options?: VercelPluginOptions): {
   name: string;
+  probes: {
+    connection: import("@theholocron/cli").Probe;
+  };
   capabilities: {
     deployment: () => Deployment;
   };
@@ -100,6 +108,5 @@ declare function createPlugin(options?: VercelPluginOptions): {
  * One-line hint printed by `holocron auth set vercel` when no token
  * is supplied or the supplied token is rejected.
  */
-declare const AUTH_HINT: string;
-//#endregion
-export { AUTH_HINT, AuthError, PluginContext, type ResolveTokenInput, type VercelClient, type VercelClientOptions, VercelDeployment, VercelPluginOptions, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, createVercelClient, deployment, resolveToken, verifyToken };
+export declare const AUTH_HINT: string;
+export { AuthError, type ResolveTokenInput, type VercelClient, type VercelClientOptions, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createVercelClient };

package/dist/index.mjs

@@ -1,17 +1,23 @@
-import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+import { AuthError, ProviderApiError, connectionProbe, createResolveToken } from "@theholocron/cli";
 import { createVercelClient } from "@theholocron/vercel-client";
-//#region src/auth.ts
+import { errorMessage } from "@theholocron/misc-utils";
+// src/auth.ts
+/** Resolves the Vercel token from `--token`, `HOLOCRON_VERCEL_TOKEN`, `VERCEL_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
 const resolveToken = createResolveToken({
 	envName: "HOLOCRON_VERCEL_TOKEN",
 	vendorEnvName: "VERCEL_TOKEN",
 	keyringService: "vercel",
 	errorMessage: "no Vercel token found. Pass --token <PAT>, set HOLOCRON_VERCEL_TOKEN / VERCEL_TOKEN, or run: holocron auth set vercel <PAT>"
 });
-//#endregion
-//#region src/capabilities/deployment.ts
+/** Every token this plugin takes, for `holocron doctor tokens`. */
+const tokens = [resolveToken.token];
+// src/capabilities/deployment.ts
+/** The `deployment` capability for Vercel: projects, environment variables, deployments, functions and custom domains. */
 var VercelDeployment = class {
 	client;
+	/** The capability key, always `deployment`. */
 	key = "deployment";
+	/** The provider name, `vercel`. */
 	providerName = "vercel";
 	domain;
 	defaultFramework;
@@ -20,6 +26,7 @@ var VercelDeployment = class {
 		this.defaultFramework = opts.defaultFramework ?? "nextjs";
 		this.domain = opts.domain;
 	}
+	/** Lists the projects the token can see, mapped to the provider-neutral shape. */
 	async listProjects() {
 		const { projects } = await this.client().projects.list();
 		return projects.map(mapProject);
@@ -34,16 +41,19 @@ var VercelDeployment = class {
 			rootDirectory: input.rootDirectory
 		}));
 	}
+	/** Updates a project's preview-deployment and Git-provider deployment settings and returns the updated project. */
 	async updateProjectSettings(projectId, settings) {
 		return mapProject(await this.client().projects.update(projectId, {
 			previewDeploymentsDisabled: settings.previewDeploymentsDisabled,
 			gitProviderOptions: settings.gitProviderCreateDeployments !== void 0 ? { createDeployments: settings.gitProviderCreateDeployments } : void 0
 		}));
 	}
+	/** Lists the names of the project's environment variables that apply to `target`. */
 	async listEnvVars(projectId, target) {
 		const { envs } = await this.client().env.list(projectId);
 		return envs.filter((e) => e.target.includes(target)).map((e) => e.key);
 	}
+	/** Creates or updates (upsert) an environment variable on the project for `target`. */
 	async setEnvVar(projectId, target, name, value) {
 		await this.client().env.set(projectId, target, name, value);
 	}
@@ -58,6 +68,7 @@ var VercelDeployment = class {
 			target: input.target
 		}), input.branch);
 	}
+	/** Fetches a deployment by id; the record's branch is the deployment's Git commit ref, or `null` when it has none. */
 	async getDeployment(deploymentId) {
 		const raw = await this.client().deployments.get(deploymentId);
 		return mapDeployment(raw, raw.meta?.githubCommitRef ?? null);
@@ -78,30 +89,45 @@ var VercelDeployment = class {
 		};
 	}
 	/**
-	* Idempotent — no-op when `hostname` is already on the project,
-	* matching `Deployment.ensureCustomDomain`'s contract (never break
-	* on re-runs, per CLAUDE.md's probe-then-act standard). Adding it
-	* the first time returns `verified: false` for a domain new to this
-	* Vercel account, plus a `verification` challenge — usually CNAME, a
-	* unique per-project target Vercel generates (never a fixed
-	* well-known host, confirmed via Vercel's own docs). Returned as a
-	* `DnsRecordRequest` — the caller (e.g. `holocron setup`'s
-	* custom-domain step) hands it straight to `dns.upsertRecord()`,
-	* same as `Wiki.dnsRecord()` already does for the wiki's own domain.
+	* Idempotent — matches `Deployment.ensureCustomDomain`'s contract
+	* (never break on re-runs, per CLAUDE.md's probe-then-act standard).
+	*
+	* Ownership (`domains.add`'s `verified`) and DNS routing are separate
+	* concerns: once a team already owns the domain's apex (true for any
+	* org with more than one project on the same domain), every new
+	* subdomain auto-verifies immediately with no `verification`
+	* challenge — re-adding an already-attached domain returns 409, not
+	* a fresh one. So attachment alone can't tell us whether traffic is
+	* actually routed to Vercel yet. `domains.config()` (Vercel's DNS
+	* *configuration* check) answers that regardless of ownership state:
+	* `misconfigured` + a `recommendedCNAME`, per-project, never a fixed
+	* well-known host — always read it from this response, never
+	* hardcode it. Returned as a `DnsRecordRequest` — the caller (e.g.
+	* `holocron repo setup`'s custom-domain step) hands it straight to
+	* `dns.upsertRecord()`, same as `Wiki.dnsRecord()` already does for
+	* the wiki's own domain.
 	*/
 	async ensureCustomDomain(projectId, hostname) {
 		const { domains: existing } = await this.client().domains.list(projectId);
-		if (existing.some((d) => d.name === hostname)) return null;
-		const result = await this.client().domains.add(projectId, hostname);
-		if (result.verified) return null;
-		const challenge = result.verification?.find((v) => v.type === "CNAME");
-		if (!challenge) return null;
+		let apexName = existing.find((d) => d.name === hostname)?.apexName;
+		if (!apexName) try {
+			apexName = (await this.client().domains.add(projectId, hostname)).apexName;
+		} catch (err) {
+			if (!(err instanceof ProviderApiError && err.status === 409)) throw err;
+			const { domains: refreshed } = await this.client().domains.list(projectId);
+			apexName = refreshed.find((d) => d.name === hostname)?.apexName;
+		}
+		if (!apexName) return null;
+		const config = await this.client().domains.config(hostname, projectId);
+		if (!config.misconfigured) return null;
+		const cname = config.recommendedCNAME[0]?.value;
+		if (!cname) return null;
 		return {
-			zone: result.apexName,
+			zone: apexName,
 			record: {
 				type: "CNAME",
 				name: hostname,
-				content: challenge.value
+				content: cname
 			}
 		};
 	}
@@ -132,6 +158,7 @@ function mapDeployment(raw, branch) {
 		status: normalizeState(raw.readyState)
 	};
 	if (raw.target) record.target = raw.target;
+	if (raw.errorMessage) record.errorMessage = raw.errorMessage;
 	return record;
 }
 function normalizeState(s) {
@@ -144,13 +171,8 @@ function normalizeState(s) {
 		case "CANCELED": return "cancelled";
 	}
 }
-//#endregion
-//#region src/verify-token.ts
-/**
-* `verifyToken` — plugin-level export used by `holocron auth set` +
-* `holocron auth check`. Hits `GET /v2/user` and translates the
-* response into the normalized `VerifyTokenResult` shape.
-*/
+// src/verify-token.ts
+/** Checks a Vercel token by fetching the current user; the success subject is `user @` followed by the email, username, name or id, the failure carries the error message. */
 async function verifyToken(token, opts = {}) {
 	const client = createVercelClient({
 		token,
@@ -166,12 +188,12 @@ async function verifyToken(token, opts = {}) {
 	} catch (err) {
 		return {
 			ok: false,
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
-//#endregion
-//#region src/index.ts
+// src/index.ts
+/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
 function createContext(options = {}) {
 	let client;
 	return {
@@ -184,16 +206,28 @@ function createContext(options = {}) {
 		})
 	};
 }
+/** Builds the `deployment` capability from a plugin context, passing on `defaultFramework` and `domain` when set. */
 function deployment(ctx) {
 	const opts = {};
 	if (ctx.options.defaultFramework !== void 0) opts.defaultFramework = ctx.options.defaultFramework;
 	if (ctx.options.domain !== void 0) opts.domain = ctx.options.domain;
 	return new VercelDeployment(ctx.client, opts);
 }
+/** Creates the Vercel plugin: a `connection` probe and the `deployment` capability. */
 function createPlugin(options = {}) {
 	const ctx = createContext(options);
 	return {
 		name: "@theholocron/holocron-plugin-vercel",
+		probes: { connection: connectionProbe({
+			provider: "Vercel",
+			url: options.baseUrl ?? "https://api.vercel.com",
+			fetch: options.fetch,
+			token: () => resolveToken(options),
+			verify: (token) => verifyToken(token, {
+				baseUrl: options.baseUrl,
+				fetch: options.fetch
+			})
+		}) },
 		capabilities: { deployment: () => deployment(ctx) }
 	};
 }
@@ -202,5 +236,4 @@ function createPlugin(options = {}) {
 * is supplied or the supplied token is rejected.
 */
 const AUTH_HINT = "generate a Vercel Personal Access Token at https://vercel.com/account/tokens (scope: Full Account for team ops), then run: holocron auth set vercel <PAT>";
-//#endregion
-export { AUTH_HINT, AuthError, VercelDeployment, createContext, createPlugin, createVercelClient, deployment, resolveToken, verifyToken };
+export { AUTH_HINT, AuthError, VercelDeployment, createContext, createPlugin, createVercelClient, deployment, resolveToken, tokens, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-vercel",
-  "version": "5.0.0-alpha.28",
+  "version": "5.0.0-alpha.280",
   "description": "Holocron plugin for Vercel. Implements the deployment capability against the Vercel REST API.",
   "keywords": [
     "deployment",
@@ -8,12 +8,12 @@
     "plugin",
     "vercel"
   ],
-  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-vercel#readme",
+  "homepage": "https://docs.theholocron.dev/holocron/plugins/vercel/",
   "bugs": "https://github.com/theholocron/holocron/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/theholocron/holocron.git",
-    "directory": "packages/holocron-plugin-vercel"
+    "directory": "plugins/holocron-plugin-vercel"
   },
   "license": "MIT",
   "author": "Newton Koumantzelis",
@@ -30,27 +30,29 @@
     "dist"
   ],
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.0.0",
-    "@theholocron/http-client": "^1.23.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/tsdown-config": "^8.0.0",
-    "@theholocron/vercel-client": "^1.23.0",
-    "@theholocron/vitest-config": "^8.0.0",
     "@types/node": "^26",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^5.0.5",
     "@vitest/eslint-plugin": "^1.6.27",
     "eslint": "^10.8.1",
     "eslint-plugin-n": "^18.3.0",
     "globals": "^17.11.0",
-    "tsdown": "^0.22.14",
-    "tsx": "4.23.12",
+    "tsdown": "^0.23.3",
+    "tsx": "4.23.15",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.28"
+    "vitest": "^5.0.5",
+    "@theholocron/cli": "5.0.0-alpha.280",
+    "@theholocron/tsconfig": "^8.9.0-alpha.4",
+    "@theholocron/misc-utils": "^1.16.1-alpha.3",
+    "@theholocron/http-client": "^1.58.0-alpha.3",
+    "@theholocron/eslint-config": "^8.9.0-alpha.4",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.4",
+    "@theholocron/vercel-client": "^1.58.0-alpha.3",
+    "@theholocron/vitest-config": "^8.9.0-alpha.4"
   },
   "peerDependencies": {
-    "@theholocron/vercel-client": "^1.23.0",
-    "@theholocron/cli": "5.0.0-alpha.28"
+    "@theholocron/misc-utils": "^1.16.0",
+    "@theholocron/vercel-client": "^1.43.1",
+    "@theholocron/cli": "5.0.0-alpha.280"
   },
   "peerDependenciesMeta": {
     "@theholocron/vercel-client": {}
@@ -63,10 +65,10 @@
   },
   "scripts": {
     "delivery.build": "tsdown",
-    "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
+    "sourceQuality.staticAnalysis": "eslint .",
     "test:watch": "vitest",
     "validate": "tsx scripts/validate.mjs",
-    "verification.typeSafety": "holocron run verification.typeSafety --",
-    "verification.unitTests": "holocron run verification.unitTests --"
+    "verification.typeSafety": "tsc --noEmit",
+    "verification.unitTests": "vitest run"
   }
 }