@theholocron/holocron-plugin-vercel 2.0.0-alpha.0 → 2.0.0-alpha.10

package/README.md

@@ -3,6 +3,12 @@
 Vercel plugin for [Holocron](../cli). Implements the `deployment`
 capability against the [Vercel REST API](https://vercel.com/docs/rest-api).
 
+## Install
+
+```bash
+pnpm add -D @theholocron/holocron-plugin-vercel@alpha
+```
+
 ## Auth
 
 Token resolution order:
@@ -20,18 +26,22 @@ always cover what holocron needs at the API level. Explicit token only.
 ```jsonc
 // holocron.config.json
 {
-  "providers": {
-    "deployment": ["vercel", { "teamId": "team_xxx" }]
-  }
+	"providers": {
+		"deployment": ["vercel", { "teamId": "team_xxx" }],
+	},
 }
 ```
 
 - `teamId` (optional) — Vercel team id. When set, all requests are
-  scoped to that team. Leave unset for personal-account projects.
+	scoped to that team. Leave unset for personal-account projects.
 
 ## Status
 
-**v0.0.0 — first port.** Capability covers:
+**`v2.0.0-alpha.0`** — published on npm under the `alpha` dist-tag.
+[Release notes](https://github.com/theholocron/holocron/releases/tag/v2.0.0-alpha.0).
+APIs may still shift before stable v2.0.0.
+
+Capability covers:
 
 - `listProjects()` / `ensureProject()` — idempotent project create
 - `updateProjectSettings()` — toggle preview deploys, git-creates-deploys
@@ -39,7 +49,7 @@ always cover what holocron needs at the API level. Explicit token only.
 - `triggerDeployment()` — branch deploys with optional named target
 - `getDeployment()` — fetch a deployment by id
 
-Out of scope for v1 (file a follow-up if needed):
+Out of scope for alpha.0 (file a follow-up if needed):
 
 - Domain management (`addDomain` / `removeDomain`)
 - Deletion (`deleteProject`)

package/dist/index.d.mts

@@ -4,10 +4,13 @@ import { Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRec
 /**
  * Token resolution for the Vercel plugin.
  *
- * Resolution order:
+ * Resolution order (matches the standard 4-step precedence set by
+ * `.notes/tech-auth-bootstrap.spec.md`):
  *   1. explicit `cliToken` argument (from `--token` flag)
  *   2. HOLOCRON_VERCEL_TOKEN env var (preferred — explicit intent)
  *   3. VERCEL_TOKEN env var (the default the Vercel CLI also reads)
+ *   4. keyring (com.theholocron.cli / "vercel")
+ *   5. AuthError naming all four options + the bootstrap hint
  *
  * No `vercel auth` fallback — Vercel CLI auth is per-account-scoped
  * and the resulting tokens don't always cover team operations.
@@ -20,6 +23,8 @@ interface ResolveTokenInput {
   cliToken?: string;
   /** Env vars; passed in for testability. Defaults to `process.env`. */
   env?: NodeJS.ProcessEnv;
+  /** Keyring lookup fn; passed in for testability. Defaults to `getToken(provider)`. */
+  keyring?: (provider: string) => string | null;
 }
 declare function resolveToken(input?: ResolveTokenInput): string;
 //#endregion
@@ -43,7 +48,7 @@ interface RestClientOptions {
   baseUrl?: string;
 }
 interface RequestOptions {
-  method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
   body?: unknown;
   /** Additional query-string params. */
   query?: Record<string, string>;
@@ -88,6 +93,27 @@ declare class VercelDeployment implements Deployment {
   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 {
   /** Vercel team id. Set when working with a team-owned project. */
@@ -111,5 +137,12 @@ declare function createPlugin(options?: VercelPluginOptions): {
     deployment: () => Deployment;
   };
 };
+/**
+ * One-line hint printed by `holocron auth set vercel` when no token
+ * is supplied or the supplied token is rejected. Points operators at
+ * https://vercel.com/account/tokens where PATs are minted with
+ * "Full Account" scope for team-level ops.
+ */
+declare const AUTH_HINT: string;
 //#endregion
-export { AuthError, PluginContext, ResolveTokenInput, VercelDeployment, VercelPluginOptions, VercelRestClient, createContext, createPlugin, deployment, resolveToken };
+export { AUTH_HINT, AuthError, PluginContext, ResolveTokenInput, VercelDeployment, VercelPluginOptions, VercelRestClient, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, deployment, resolveToken, verifyToken };

package/dist/index.mjs

@@ -1,12 +1,15 @@
-import { ProviderApiError } from "@theholocron/cli";
+import { ProviderApiError, getToken } from "@theholocron/cli";
 //#region src/auth.ts
 /**
 * Token resolution for the Vercel plugin.
 *
-* Resolution order:
+* Resolution order (matches the standard 4-step precedence set by
+* `.notes/tech-auth-bootstrap.spec.md`):
 *   1. explicit `cliToken` argument (from `--token` flag)
 *   2. HOLOCRON_VERCEL_TOKEN env var (preferred — explicit intent)
 *   3. VERCEL_TOKEN env var (the default the Vercel CLI also reads)
+*   4. keyring (com.theholocron.cli / "vercel")
+*   5. AuthError naming all four options + the bootstrap hint
 *
 * No `vercel auth` fallback — Vercel CLI auth is per-account-scoped
 * and the resulting tokens don't always cover team operations.
@@ -16,8 +19,9 @@ var AuthError = class extends Error {
 };
 function resolveToken(input = {}) {
 	const env = input.env ?? process.env;
-	const token = input.cliToken || env.HOLOCRON_VERCEL_TOKEN || env.VERCEL_TOKEN;
-	if (!token) throw new AuthError("no Vercel token found. Pass --token <PAT>, or set HOLOCRON_VERCEL_TOKEN / VERCEL_TOKEN.");
+	const keyring = input.keyring ?? getToken;
+	const token = input.cliToken || env["HOLOCRON_VERCEL_TOKEN"] || env["VERCEL_TOKEN"] || keyring("vercel");
+	if (!token) throw new AuthError("no Vercel token found. Pass --token <PAT>, set HOLOCRON_VERCEL_TOKEN / VERCEL_TOKEN, or run: holocron auth set vercel <PAT>");
 	return token;
 }
 //#endregion
@@ -176,7 +180,9 @@ var VercelRestClient = class {
 		this.token = opts.token;
 		if (opts.teamId !== void 0) this.teamId = opts.teamId;
 		this.fetchImpl = opts.fetch ?? globalThis.fetch;
-		this.baseUrl = (opts.baseUrl ?? "https://api.vercel.com").replace(/\/+$/, "");
+		let url = opts.baseUrl ?? "https://api.vercel.com";
+		while (url.endsWith("/")) url = url.slice(0, -1);
+		this.baseUrl = url;
 	}
 	async request(path, opts = {}) {
 		const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`);
@@ -213,6 +219,31 @@ var VercelRestClient = class {
 	}
 };
 //#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.
+*/
+async function verifyToken(token, opts = {}) {
+	const restOpts = { token };
+	if (opts.baseUrl !== void 0) restOpts.baseUrl = opts.baseUrl;
+	if (opts.fetch !== void 0) restOpts.fetch = opts.fetch;
+	const rest = new VercelRestClient(restOpts);
+	try {
+		const res = await rest.request("/v2/user");
+		return {
+			ok: true,
+			subject: `user @ ${res?.user?.email ?? res?.user?.username ?? res?.user?.name ?? res?.user?.id ?? "unknown"}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
 //#region src/index.ts
 function createContext(options = {}) {
 	const restOpts = { token: resolveToken(options) };
@@ -236,5 +267,12 @@ function createPlugin(options = {}) {
 		capabilities: { deployment: () => deployment(ctx) }
 	};
 }
+/**
+* One-line hint printed by `holocron auth set vercel` when no token
+* is supplied or the supplied token is rejected. Points operators at
+* https://vercel.com/account/tokens where PATs are minted with
+* "Full Account" scope for team-level ops.
+*/
+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 { AuthError, VercelDeployment, VercelRestClient, createContext, createPlugin, deployment, resolveToken };
+export { AUTH_HINT, AuthError, VercelDeployment, VercelRestClient, createContext, createPlugin, deployment, resolveToken, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-vercel",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0-alpha.10",
   "description": "Holocron plugin for Vercel. Implements the deployment capability against the Vercel REST API.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-vercel#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -21,7 +21,7 @@
     }
   },
   "peerDependencies": {
-    "@theholocron/cli": "2.0.0-alpha.0"
+    "@theholocron/cli": "2.0.0-alpha.10"
   },
   "devDependencies": {
     "@theholocron/tsconfig": "^4.1.0",
@@ -32,7 +32,8 @@
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
     "tsdown": "^0.22.3",
-    "@theholocron/cli": "2.0.0-alpha.0"
+    "tsx": "^4.22.4",
+    "@theholocron/cli": "2.0.0-alpha.10"
   },
   "publishConfig": {
     "access": "public"
@@ -47,7 +48,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
   },
   "types": "./dist/index.d.mts"
 }