@theholocron/holocron-plugin-vercel 5.0.0-alpha.32 → 5.0.0-alpha.326

package/README.md

@@ -1,3 +1,5 @@
+<!-- alex disable host-hostess -->
+
 <!-- editorconfig-checker-disable-file -->
 
 # `@theholocron/holocron-plugin-vercel`
@@ -73,9 +75,9 @@ Capability covers:
   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 setup`.
+  `holocron repo setup`.
 
-Declare the production domain in the Vercel provider options. On `holocron 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,14 +28,18 @@ 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>;
   /**
@@ -49,56 +57,56 @@ declare class VercelDeployment implements Deployment {
    * `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 setup`'s custom-domain step) hands it straight to
+   * `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>;
+  /**
+   * Read-only: the CNAME Vercel recommends for `hostname`, whether or not the domain already resolves. Unlike
+   * `ensureCustomDomain` it never attaches the domain, and it keeps the answer when `misconfigured` is false, so
+   * `holocron doctor dns` can compare it with the zone. The record is DNS-only: a proxied record breaks Vercel's
+   * certificate issuance.
+   */
+  expectedDomainRecord(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;
   };
@@ -107,6 +115,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);
@@ -92,7 +103,7 @@ var VercelDeployment = class {
 	* `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 setup`'s custom-domain step) hands it straight to
+	* `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.
 	*/
@@ -120,6 +131,25 @@ var VercelDeployment = class {
 			}
 		};
 	}
+	/**
+	* Read-only: the CNAME Vercel recommends for `hostname`, whether or not the domain already resolves. Unlike
+	* `ensureCustomDomain` it never attaches the domain, and it keeps the answer when `misconfigured` is false, so
+	* `holocron doctor dns` can compare it with the zone. The record is DNS-only: a proxied record breaks Vercel's
+	* certificate issuance.
+	*/
+	async expectedDomainRecord(projectId, hostname) {
+		const cname = (await this.client().domains.config(hostname, projectId)).recommendedCNAME[0]?.value;
+		if (!cname) return null;
+		return {
+			zone: hostname,
+			record: {
+				type: "CNAME",
+				name: hostname,
+				content: cname,
+				proxied: false
+			}
+		};
+	}
 	async getProjectByName(name) {
 		try {
 			return mapProject(await this.client().projects.get(name));
@@ -147,6 +177,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) {
@@ -159,13 +190,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,
@@ -181,12 +207,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 {
@@ -199,16 +225,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) }
 	};
 }
@@ -217,5 +255,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.32",
+  "version": "5.0.0-alpha.326",
   "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.24.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/tsdown-config": "^8.0.0",
-    "@theholocron/vercel-client": "^1.24.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.32"
+    "vitest": "^5.0.5",
+    "@theholocron/cli": "5.0.0-alpha.326",
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/misc-utils": "^1.17.0-alpha.1",
+    "@theholocron/http-client": "^1.58.0-alpha.7",
+    "@theholocron/tsconfig": "^8.9.0-alpha.8",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
+    "@theholocron/vercel-client": "^1.58.0-alpha.7",
+    "@theholocron/vitest-config": "^8.9.0-alpha.8"
   },
   "peerDependencies": {
-    "@theholocron/vercel-client": "^1.24.0",
-    "@theholocron/cli": "5.0.0-alpha.32"
+    "@theholocron/misc-utils": "^1.16.0",
+    "@theholocron/vercel-client": "^1.43.1",
+    "@theholocron/cli": "5.0.0-alpha.326"
   },
   "peerDependenciesMeta": {
     "@theholocron/vercel-client": {}
@@ -62,11 +64,11 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown",
-    "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
+    "build": "tsdown",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "validate": "tsx scripts/validate.mjs",
-    "verification.typeSafety": "holocron run verification.typeSafety --",
-    "verification.unitTests": "holocron run verification.unitTests --"
+    "typecheck": "tsc --noEmit",
+    "validate:plugin": "tsx scripts/validate.mjs"
   }
 }