@theholocron/holocron-plugin-vercel 5.0.0-alpha.27 → 5.0.0-alpha.271

package/README.md

@@ -64,13 +64,27 @@ 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); this method only
-  adds the domain, reading the challenge to finish DNS setup is the
-  caller's own job today (no `Wiki.dnsRecord()`-style shared surface
-  for it yet)
+- `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:
+
+```ts
+providers: {
+	deployment: ["vercel", { teamId: "team_…", domain: "sentinel.example.com" }],
+	dns: "cloudflare",
+}
+```
 
 Out of scope for alpha.0 (file a follow-up if needed):
 

package/dist/index.d.mts

@@ -1,17 +1,19 @@
-import { AuthError, DeployFunctionConfig, DeployFunctionResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, 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
+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 repo setup` should attach to this project. */
+  domain?: string;
 }
-declare class VercelDeployment implements Deployment {
+export declare class VercelDeployment implements Deployment {
   private readonly client;
   readonly key: "deployment";
   readonly providerName = "vercel";
+  readonly domain?: string;
   private readonly defaultFramework;
   constructor(client: () => VercelClient$1, opts?: DeploymentOptions);
   listProjects(): Promise<DeploymentProject[]>;
@@ -32,63 +34,55 @@ declare class VercelDeployment implements Deployment {
   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 — Vercel needs a DNS record (usually CNAME, a
-   * unique per-project target) created before it routes traffic. This
-   * method only adds the domain; reading the verification challenge
-   * needed to finish is the caller's job (`client().domains.add()`'s
-   * own return value carries it) — Sentinel has no `holocron setup`
-   * orchestration to hand it to, so there's no shared "here's the DNS
-   * record" surface to route it through the way `Wiki.dnsRecord()`
-   * does today.
+   * 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<void>;
+  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 {
+export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
+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 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 {
+export interface PluginContext {
   options: VercelPluginOptions;
   client: () => VercelClient;
 }
-declare function createContext(options?: VercelPluginOptions): PluginContext;
-declare function deployment(ctx: PluginContext): Deployment;
-declare function createPlugin(options?: VercelPluginOptions): {
+export declare function createContext(options?: VercelPluginOptions): PluginContext;
+export declare function deployment(ctx: PluginContext): Deployment;
+export declare function createPlugin(options?: VercelPluginOptions): {
   name: string;
+  probes: {
+    connection: import("@theholocron/cli").Probe;
+  };
   capabilities: {
     deployment: () => Deployment;
   };
@@ -97,6 +91,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,22 +1,26 @@
-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
 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
 var VercelDeployment = class {
 	client;
 	key = "deployment";
 	providerName = "vercel";
+	domain;
 	defaultFramework;
 	constructor(client, opts = {}) {
 		this.client = client;
 		this.defaultFramework = opts.defaultFramework ?? "nextjs";
+		this.domain = opts.domain;
 	}
 	async listProjects() {
 		const { projects } = await this.client().projects.list();
@@ -76,23 +80,47 @@ 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 — Vercel needs a DNS record (usually CNAME, a
-	* unique per-project target) created before it routes traffic. This
-	* method only adds the domain; reading the verification challenge
-	* needed to finish is the caller's job (`client().domains.add()`'s
-	* own return value carries it) — Sentinel has no `holocron setup`
-	* orchestration to hand it to, so there's no shared "here's the DNS
-	* record" surface to route it through the way `Wiki.dnsRecord()`
-	* does today.
+	* 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;
-		await this.client().domains.add(projectId, hostname);
+		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: apexName,
+			record: {
+				type: "CNAME",
+				name: hostname,
+				content: cname
+			}
+		};
 	}
 	async getProjectByName(name) {
 		try {
@@ -121,6 +149,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) {
@@ -133,13 +162,7 @@ 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
 async function verifyToken(token, opts = {}) {
 	const client = createVercelClient({
 		token,
@@ -155,12 +178,11 @@ 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
 function createContext(options = {}) {
 	let client;
 	return {
@@ -176,12 +198,23 @@ function createContext(options = {}) {
 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);
 }
 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) }
 	};
 }
@@ -190,5 +223,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.27",
+  "version": "5.0.0-alpha.271",
   "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.27"
+    "vitest": "^5.0.5",
+    "@theholocron/eslint-config": "^8.9.0-alpha.3",
+    "@theholocron/cli": "5.0.0-alpha.271",
+    "@theholocron/http-client": "^1.58.0-alpha.2",
+    "@theholocron/misc-utils": "^1.16.1-alpha.1",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
+    "@theholocron/tsconfig": "^8.9.0-alpha.3",
+    "@theholocron/vercel-client": "^1.58.0-alpha.2",
+    "@theholocron/vitest-config": "^8.9.0-alpha.3"
   },
   "peerDependencies": {
-    "@theholocron/vercel-client": "^1.23.0",
-    "@theholocron/cli": "5.0.0-alpha.27"
+    "@theholocron/misc-utils": "^1.16.0",
+    "@theholocron/vercel-client": "^1.43.1",
+    "@theholocron/cli": "5.0.0-alpha.271"
   },
   "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"
   }
 }