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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# `@theholocron/holocron-plugin-vercel`
+
+Vercel plugin for [Holocron](../cli). Implements the `deployment`
+capability against the [Vercel REST API](https://vercel.com/docs/rest-api).
+
+## Auth
+
+Token resolution order:
+
+1. `--token <PAT>` flag on the holocron invocation
+2. `HOLOCRON_VERCEL_TOKEN` env var
+3. `VERCEL_TOKEN` env var (the default the Vercel CLI also reads)
+
+If none are set, the plugin throws a clear error. No `vercel auth`
+fallback — Vercel's CLI auth is per-account and the scopes don't
+always cover what holocron needs at the API level. Explicit token only.
+
+## Config
+
+```jsonc
+// holocron.config.json
+{
+  "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.
+
+## Status
+
+**v0.0.0 — first port.** Capability covers:
+
+- `listProjects()` / `ensureProject()` — idempotent project create
+- `updateProjectSettings()` — toggle preview deploys, git-creates-deploys
+- `setEnvVar()` / `listEnvVars()` — per-target env vars
+- `triggerDeployment()` — branch deploys with optional named target
+- `getDeployment()` — fetch a deployment by id
+
+Out of scope for v1 (file a follow-up if needed):
+
+- Domain management (`addDomain` / `removeDomain`)
+- Deletion (`deleteProject`)
+- Marketplace integrations (e.g. `vercel install neon` for vault-managed databases)

package/dist/index.d.mts

@@ -0,0 +1,115 @@
+import { Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger } from "@theholocron/cli";
+
+//#region src/auth.d.ts
+/**
+ * Token resolution for the Vercel plugin.
+ *
+ * Resolution order:
+ *   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)
+ *
+ * No `vercel auth` fallback — Vercel CLI auth is per-account-scoped
+ * and the resulting tokens don't always cover team operations.
+ */
+declare class AuthError extends Error {
+  name: string;
+}
+interface ResolveTokenInput {
+  /** From `--token` CLI flag. */
+  cliToken?: string;
+  /** Env vars; passed in for testability. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+}
+declare function resolveToken(input?: ResolveTokenInput): string;
+//#endregion
+//#region src/rest.d.ts
+/**
+ * Thin REST wrapper around api.vercel.com.
+ *
+ * Differences from the GitHub REST client:
+ *  - Vercel uses simple `Bearer <token>` (no api-version header)
+ *  - Team scoping is a query-string param (`teamId=...`), not a path
+ *    prefix; the client appends it to every URL when configured
+ *  - 204 responses are honored the same way; transport failures get
+ *    wrapped in `ProviderApiError` with `status: 0` for clear hint
+ *    output
+ */
+interface RestClientOptions {
+  token: string;
+  /** Vercel team id. When set, scoped to that team for every request. */
+  teamId?: string;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+  body?: unknown;
+  /** Additional query-string params. */
+  query?: Record<string, string>;
+}
+declare class VercelRestClient {
+  private readonly token;
+  private readonly teamId?;
+  private readonly fetchImpl;
+  readonly baseUrl: string;
+  constructor(opts: RestClientOptions);
+  request<T>(path: string, opts?: RequestOptions): Promise<T>;
+}
+//#endregion
+//#region src/capabilities/deployment.d.ts
+interface DeploymentOptions {
+  /** Optional framework hint passed to project creates. Defaults to "nextjs". */
+  defaultFramework?: string;
+}
+declare class VercelDeployment implements Deployment {
+  private readonly rest;
+  readonly key: "deployment";
+  readonly providerName = "vercel";
+  private readonly defaultFramework;
+  constructor(rest: VercelRestClient, opts?: DeploymentOptions);
+  listProjects(): Promise<DeploymentProject[]>;
+  ensureProject(input: {
+    name: string;
+    framework?: string;
+    repo?: string;
+    rootDirectory?: string;
+  }): Promise<DeploymentProject>;
+  updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
+  listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
+  setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
+  triggerDeployment(input: {
+    projectId: string;
+    branch: string;
+    target?: DeploymentTrigger;
+  }): Promise<DeploymentRecord>;
+  getDeployment(deploymentId: string): Promise<DeploymentRecord>;
+  /** GET project by name with 404→null soft-skip. */
+  private getProjectByName;
+}
+//#endregion
+//#region src/index.d.ts
+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;
+  /** Override base URL for tests. */
+  baseUrl?: string;
+  /** Override `fetch` for tests. */
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: VercelPluginOptions;
+  rest: VercelRestClient;
+}
+declare function createContext(options?: VercelPluginOptions): PluginContext;
+declare function deployment(ctx: PluginContext): Deployment;
+declare function createPlugin(options?: VercelPluginOptions): {
+  name: string;
+  capabilities: {
+    deployment: () => Deployment;
+  };
+};
+//#endregion
+export { AuthError, PluginContext, ResolveTokenInput, VercelDeployment, VercelPluginOptions, VercelRestClient, createContext, createPlugin, deployment, resolveToken };

package/dist/index.mjs

@@ -0,0 +1,240 @@
+import { ProviderApiError } from "@theholocron/cli";
+//#region src/auth.ts
+/**
+* Token resolution for the Vercel plugin.
+*
+* Resolution order:
+*   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)
+*
+* No `vercel auth` fallback — Vercel CLI auth is per-account-scoped
+* and the resulting tokens don't always cover team operations.
+*/
+var AuthError = class extends Error {
+	name = "AuthError";
+};
+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.");
+	return token;
+}
+//#endregion
+//#region src/capabilities/deployment.ts
+/**
+* `deployment` capability for Vercel.
+*
+* Ported from rando-id/rando.id `packages/cli/src/adapters/vercel.ts`,
+* adapted to the holocron `Deployment` interface:
+*
+*   - `ensureProject` is the idempotent create (GET-then-POST), since
+*     `holocron setup` re-runs on every invocation
+*   - `setEnvVar` uses Vercel's `upsert=true` so it's idempotent
+*     create-or-update
+*   - `triggerDeployment` infers a branch preview when `target` is
+*     omitted; named targets ('production' / 'staging') opt into
+*     environment-scoped deploys
+*
+* Vercel encrypts env-var values at rest server-side; we send them as
+* `type: 'encrypted'`. Unlike GitHub Actions secrets, there's no
+* sealed-box / libsodium step on the client.
+*/
+var VercelDeployment = class {
+	rest;
+	key = "deployment";
+	providerName = "vercel";
+	defaultFramework;
+	constructor(rest, opts = {}) {
+		this.rest = rest;
+		this.defaultFramework = opts.defaultFramework ?? "nextjs";
+	}
+	async listProjects() {
+		return (await this.rest.request("/v10/projects")).projects.map(mapProject);
+	}
+	async ensureProject(input) {
+		const existing = await this.getProjectByName(input.name);
+		if (existing) return existing;
+		const body = {
+			name: input.name,
+			framework: input.framework ?? this.defaultFramework
+		};
+		if (input.repo) body.gitRepository = {
+			type: "github",
+			repo: input.repo
+		};
+		if (input.rootDirectory) body.rootDirectory = input.rootDirectory;
+		return mapProject(await this.rest.request("/v11/projects", {
+			method: "POST",
+			body
+		}));
+	}
+	async updateProjectSettings(projectId, settings) {
+		const body = {};
+		if (settings.previewDeploymentsDisabled !== void 0) body.previewDeploymentsDisabled = settings.previewDeploymentsDisabled;
+		if (settings.gitProviderCreateDeployments !== void 0) body.gitProviderOptions = { createDeployments: settings.gitProviderCreateDeployments };
+		return mapProject(await this.rest.request(`/v9/projects/${encodeURIComponent(projectId)}`, {
+			method: "PATCH",
+			body
+		}));
+	}
+	async listEnvVars(projectId, target) {
+		return (await this.rest.request(`/v9/projects/${encodeURIComponent(projectId)}/env`)).envs.filter((e) => e.target.includes(target)).map((e) => e.key);
+	}
+	async setEnvVar(projectId, target, name, value) {
+		await this.rest.request(`/v10/projects/${encodeURIComponent(projectId)}/env`, {
+			method: "POST",
+			query: { upsert: "true" },
+			body: {
+				key: name,
+				value,
+				target: [target],
+				type: "encrypted"
+			}
+		});
+	}
+	async triggerDeployment(input) {
+		const project = await this.rest.request(`/v10/projects/${encodeURIComponent(input.projectId)}`);
+		const repoId = project.link?.repoId;
+		if (!repoId) throw new ProviderApiError(`Vercel project "${project.name}" has no linked GitHub repo — cannot trigger a deployment. Link the repo first.`, 400, void 0);
+		return mapDeployment(await this.rest.request("/v13/deployments", {
+			method: "POST",
+			body: {
+				name: project.name,
+				gitSource: {
+					type: "github",
+					ref: input.branch,
+					repoId
+				},
+				...input.target ? { target: input.target } : {}
+			}
+		}), input.branch);
+	}
+	async getDeployment(deploymentId) {
+		const raw = await this.rest.request(`/v13/deployments/${encodeURIComponent(deploymentId)}`);
+		return mapDeployment(raw, raw.meta?.githubCommitRef ?? null);
+	}
+	/** GET project by name with 404→null soft-skip. */
+	async getProjectByName(name) {
+		try {
+			return mapProject(await this.rest.request(`/v10/projects/${encodeURIComponent(name)}`));
+		} catch (err) {
+			if (err instanceof ProviderApiError && err.status === 404) return null;
+			throw err;
+		}
+	}
+};
+function mapProject(raw) {
+	const project = {
+		id: raw.id,
+		name: raw.name,
+		gitLinked: Boolean(raw.link?.repoId),
+		rootDirectory: raw.rootDirectory ?? null
+	};
+	if (raw.framework) project.framework = raw.framework;
+	return project;
+}
+function mapDeployment(raw, branch) {
+	const record = {
+		id: raw.id,
+		url: raw.url,
+		branch,
+		status: normalizeState(raw.readyState)
+	};
+	if (raw.target) record.target = raw.target;
+	return record;
+}
+function normalizeState(s) {
+	switch (s) {
+		case "INITIALIZING":
+		case "QUEUED": return "queued";
+		case "BUILDING": return "building";
+		case "READY": return "ready";
+		case "ERROR": return "error";
+		case "CANCELED": return "cancelled";
+	}
+}
+//#endregion
+//#region src/rest.ts
+/**
+* Thin REST wrapper around api.vercel.com.
+*
+* Differences from the GitHub REST client:
+*  - Vercel uses simple `Bearer <token>` (no api-version header)
+*  - Team scoping is a query-string param (`teamId=...`), not a path
+*    prefix; the client appends it to every URL when configured
+*  - 204 responses are honored the same way; transport failures get
+*    wrapped in `ProviderApiError` with `status: 0` for clear hint
+*    output
+*/
+var VercelRestClient = class {
+	token;
+	teamId;
+	fetchImpl;
+	baseUrl;
+	constructor(opts) {
+		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(/\/+$/, "");
+	}
+	async request(path, opts = {}) {
+		const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`);
+		if (this.teamId) url.searchParams.set("teamId", this.teamId);
+		for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
+		const fullUrl = url.toString();
+		const headers = {
+			authorization: `Bearer ${this.token}`,
+			accept: "application/json"
+		};
+		const init = {
+			method: opts.method ?? "GET",
+			headers
+		};
+		if (opts.body !== void 0) {
+			headers["content-type"] = "application/json";
+			init.body = JSON.stringify(opts.body);
+		}
+		let res;
+		try {
+			res = await this.fetchImpl(fullUrl, init);
+		} catch (err) {
+			const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+			throw new ProviderApiError(`Vercel ${init.method} ${path} failed: ${detail}`, 0, void 0);
+		}
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			throw new ProviderApiError(`Vercel ${init.method} ${path} → ${res.status}`, res.status, body);
+		}
+		if (res.status === 204) return void 0;
+		const text = await res.text();
+		if (!text) return void 0;
+		return JSON.parse(text);
+	}
+};
+//#endregion
+//#region src/index.ts
+function createContext(options = {}) {
+	const restOpts = { token: resolveToken(options) };
+	if (options.teamId !== void 0) restOpts.teamId = options.teamId;
+	if (options.baseUrl !== void 0) restOpts.baseUrl = options.baseUrl;
+	if (options.fetch !== void 0) restOpts.fetch = options.fetch;
+	return {
+		options,
+		rest: new VercelRestClient(restOpts)
+	};
+}
+function deployment(ctx) {
+	const opts = {};
+	if (ctx.options.defaultFramework !== void 0) opts.defaultFramework = ctx.options.defaultFramework;
+	return new VercelDeployment(ctx.rest, opts);
+}
+function createPlugin(options = {}) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-vercel",
+		capabilities: { deployment: () => deployment(ctx) }
+	};
+}
+//#endregion
+export { AuthError, VercelDeployment, VercelRestClient, createContext, createPlugin, deployment, resolveToken };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@theholocron/holocron-plugin-vercel",
+  "version": "2.0.0-alpha.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-vercel"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "2.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@theholocron/tsconfig": "^4.1.0",
+    "@tsconfig/node-lts": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.6",
+    "eslint": "^9.36.0",
+    "globals": "^16.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6",
+    "tsdown": "^0.22.3",
+    "@theholocron/cli": "2.0.0-alpha.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "types": "./dist/index.d.mts"
+}