@theholocron/holocron-plugin-netlify 2.0.0-alpha.1

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,106 @@
+<!-- editorconfig-checker-disable-file -->
+
+# `@theholocron/holocron-plugin-netlify`
+
+Netlify plugin for [Holocron](../cli). Implements the
+`deployment` capability against [`@theholocron/netlify-client`](https://github.com/theholocron/clients/tree/main/packages/netlify-client),
+plus exports `verifyToken` + `AUTH_HINT` for use by `holocron auth`.
+
+## Install
+
+```bash
+pnpm add -D @theholocron/holocron-plugin-netlify@alpha
+```
+
+## Auth
+
+Token resolution order (matches the standard 4-step precedence set by
+`docs/wiki/specifications/tech-auth-bootstrap.spec.md`):
+
+1. `--token <TOKEN>` flag on the holocron invocation
+2. `HOLOCRON_NETLIFY_TOKEN` env var (preferred — explicit intent)
+3. `NETLIFY_AUTH_TOKEN` env var (Netlify-native)
+4. **Keyring** — `com.theholocron.cli` service, account `netlify`
+5. `AuthError` naming all four options + the bootstrap hint
+
+## Setup
+
+```bash
+# Generate a Netlify API token (see vendor docs), then:
+holocron auth set netlify <TOKEN>
+holocron auth check netlify    # verify
+```
+
+## Config
+
+```jsonc
+{
+  "providers": {
+    "deployment": "netlify",
+  },
+}
+```
+
+Plugin options, via the tuple form:
+
+```jsonc
+{
+  "providers": {
+    "deployment": [
+      "netlify",
+      {
+        // Required for ensureProject/listProjects — Netlify's
+        // create-site endpoint is scoped to /{account_slug}/sites.
+        "accountSlug": "iamnewton",
+        // Required for listEnvVars/setEnvVar — Netlify's env var API
+        // is scoped to /accounts/{account_id}/env, by id not slug.
+        // Non-secret identifier, safe to commit (same status as
+        // Vercel's teamId / Cloudflare's accountId elsewhere in this org).
+        "accountId": "6ac41cd9a87355ef3d13d261",
+        // Custom domain `holocron setup` attaches to the site.
+        "domain": "sentinel.theholocron.dev",
+      },
+    ],
+  },
+}
+```
+
+## What's implemented
+
+Thin wrapper over `@theholocron/netlify-client`'s `sites` / `deploys` /
+`env` / `user` resources — see that package for the actual REST calls.
+Verified against Netlify's real API, not only mocks: a live smoke test
+(create a site, deploy real content via the client's in-memory zip
+builder, poll to `ready`, fetch the live URL) using this plugin's own
+built `createPlugin()` output.
+
+- `listProjects` / `ensureProject` → `sites.list` / `sites.create`
+- `deployFunction` → `deploys.createFromZip` — Netlify runs no build
+  step for a raw zip upload, so the caller (Sentinel's own stage-deploy
+  script) is responsible for already having resolved dependencies into
+  the file set, the same discipline Vercel's `deployFunction` path
+  requires via its own trimmed/pinned `package.json`.
+- `getDeployment` → `deploys.get`
+- `listEnvVars` / `setEnvVar` → `env.list` / `env.set`
+- `ensureCustomDomain` → `sites.update({ custom_domain })`; returns a
+  CNAME record unconditionally (Netlify has no DNS-misconfiguration
+  check to consult the way Vercel does, so idempotency relies on
+  `Dns.upsertRecord()` being a safe no-op on an already-correct record)
+
+Required by the `Deployment` interface but **not exercised by any
+current consumer** (best-effort, see inline comments in
+`src/capabilities/deployment.ts`):
+
+- `updateProjectSettings` — Netlify has no direct equivalent of Vercel's
+  git-linked-project settings; no-ops to `sites.get`.
+- `triggerDeployment` → `sites.triggerBuild`, untested against a real
+  git-linked Netlify site.
+
+Not implemented: `listPreviewDeployments` / `deletePreviewDeployments`
+(both optional on the interface) — no current consumer needs
+branch-preview listing/cleanup.
+
+## Status
+
+Implemented for Sentinel's migration off Vercel
+(`.notes/tech-sentinel-deploy-target-netlify.spec.md`, holocron#940).

package/dist/index.d.mts

@@ -0,0 +1,131 @@
+import { NetlifyClient } from "@theholocron/netlify-client";
+import { AuthError, DeployFunctionConfig, DeployFunctionResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, DnsRecordRequest, ResolveTokenInput } from "@theholocron/cli";
+//#region src/auth.d.ts
+declare const resolveToken: (input?: ResolveTokenInput) => string;
+//#endregion
+//#region src/capabilities/deployment.d.ts
+interface NetlifyDeploymentOptions {
+  /**
+   * Required for `ensureProject` / `listProjects` (create/list use
+   * Netlify's `/{account_slug}/sites` path).
+   */
+  accountSlug?: string;
+  /**
+   * Required for `listEnvVars` / `setEnvVar` (Netlify's env var API is
+   * scoped to `/accounts/{account_id}/env`, by id — not slug).
+   */
+  accountId?: string;
+  /** Custom domain `holocron setup` should attach to the site. */
+  domain?: string;
+}
+declare class NetlifyDeployment implements Deployment {
+  private readonly client;
+  private readonly opts;
+  readonly key: "deployment";
+  readonly providerName = "netlify";
+  readonly domain?: string;
+  constructor(client: () => NetlifyClient, opts?: NetlifyDeploymentOptions);
+  listProjects(): Promise<DeploymentProject[]>;
+  /** Create if missing, otherwise return existing — matched by exact name. */
+  ensureProject(input: {
+    name: string;
+    framework?: string;
+    repo?: string;
+    rootDirectory?: string;
+  }): Promise<DeploymentProject>;
+  /**
+   * Netlify has no direct equivalent of Vercel's git-linked project
+   * settings (`previewDeploymentsDisabled` / `gitProviderCreateDeployments`)
+   * — Sentinel's site isn't git-linked at all. Best-effort: return the
+   * project unchanged. Revisit if a future consumer needs a real mapping.
+   */
+  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>;
+  /**
+   * No Git integration in Sentinel's usage (file-based deploy only), but
+   * REQUIRED by the interface. Netlify's branch-triggered-build endpoint
+   * is the closest analog for a git-linked site; untested against a real
+   * git-linked Netlify site since no current consumer exercises this path.
+   */
+  triggerDeployment(input: {
+    projectId: string;
+    branch: string;
+    target?: DeploymentTrigger;
+  }): Promise<DeploymentRecord>;
+  getDeployment(deploymentId: string): Promise<DeploymentRecord>;
+  /**
+   * Zips `config.files` (plain text, per the interface contract) and
+   * uploads it as a one-shot deploy. Netlify runs no build step for a
+   * raw zip upload — the caller (Sentinel's own stage-deploy script) is
+   * responsible for having already resolved dependencies into the file
+   * set, the same discipline Vercel's `deployFunction` path already
+   * requires via its own trimmed/pinned package.json.
+   */
+  deployFunction(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
+  /**
+   * Idempotent: PATCHing the same `custom_domain` twice is a no-op on
+   * Netlify's side. Unlike Vercel, Netlify's API has no DNS-misconfiguration
+   * check to consult — it's returned unconditionally once set, which is
+   * safe because `Dns.upsertRecord()` on the receiving end is itself
+   * idempotent (re-upserting an already-correct CNAME is a no-op there).
+   */
+  ensureCustomDomain(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
+  private findSiteByName;
+  private requireAccountId;
+}
+//#endregion
+//#region src/verify-token.d.ts
+/**
+ * `verifyToken` — plugin-level export used by `holocron auth set` +
+ * `holocron auth check`. Hits Netlify's `GET /user` (current token's
+ * identity) and translates the response into the normalized
+ * `VerifyTokenResult` shape.
+ *
+ * Kept as a standalone function (not a capability method) so the auth
+ * command can call it without initializing the full plugin — plugin
+ * construction requires an already-resolved token, which is exactly
+ * what we don't have yet at bootstrap time.
+ */
+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 NetlifyPluginOptions extends ResolveTokenInput, NetlifyDeploymentOptions {
+  /** Override base URL for tests. */
+  baseUrl?: string;
+  /** Override `fetch` for tests. */
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: NetlifyPluginOptions;
+  /** Memoized client — the token is resolved on first use, not at plugin load. */
+  client: () => NetlifyClient;
+}
+declare function createContext(options: NetlifyPluginOptions): PluginContext;
+declare function deployment(ctx: PluginContext): Deployment;
+declare function createPlugin(options: NetlifyPluginOptions): {
+  name: string;
+  capabilities: {
+    deployment: () => Deployment;
+  };
+};
+/**
+ * One-line hint printed by `holocron auth set netlify` when no token is
+ * supplied or the supplied token is rejected.
+ */
+declare const AUTH_HINT: string;
+//#endregion
+export { AUTH_HINT, AuthError, NetlifyDeployment, type NetlifyDeploymentOptions, NetlifyPluginOptions, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, deployment, resolveToken, verifyToken };

package/dist/index.mjs

@@ -0,0 +1,208 @@
+import { createNetlifyClient } from "@theholocron/netlify-client";
+import { AuthError, createResolveToken } from "@theholocron/cli";
+import { ProviderApiError } from "@theholocron/http-client";
+//#region src/auth.ts
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_NETLIFY_TOKEN",
+	vendorEnvName: "NETLIFY_AUTH_TOKEN",
+	keyringService: "netlify",
+	errorMessage: "no Netlify token found. Pass --token <TOKEN>, set HOLOCRON_NETLIFY_TOKEN / NETLIFY_AUTH_TOKEN, or run: holocron auth set netlify <TOKEN>"
+});
+//#endregion
+//#region src/capabilities/deployment.ts
+const TERMINAL_READY = /* @__PURE__ */ new Set(["ready", "current"]);
+const TERMINAL_ERROR = /* @__PURE__ */ new Set(["error"]);
+function toDeploymentProject(site) {
+	return {
+		id: site.id,
+		name: site.name,
+		gitLinked: false,
+		rootDirectory: null
+	};
+}
+function toDeploymentRecord(deploy) {
+	const record = {
+		id: deploy.id,
+		url: deploy.ssl_url || deploy.url,
+		branch: deploy.branch,
+		status: TERMINAL_READY.has(deploy.state) ? "ready" : TERMINAL_ERROR.has(deploy.state) ? "error" : "building",
+		createdAt: deploy.created_at
+	};
+	if (deploy.error_message) record.errorMessage = deploy.error_message;
+	return record;
+}
+/** Netlify's deploy contexts map onto Holocron's `production` / `staging` as: production stays production, everything else is staging. */
+function toNetlifyContext(target) {
+	return target === "production" ? "production" : "branch-deploy";
+}
+var NetlifyDeployment = class {
+	client;
+	opts;
+	key = "deployment";
+	providerName = "netlify";
+	domain;
+	constructor(client, opts = {}) {
+		this.client = client;
+		this.opts = opts;
+		if (opts.domain !== void 0) this.domain = opts.domain;
+	}
+	async listProjects() {
+		return (await this.client().sites.list()).map(toDeploymentProject);
+	}
+	/** Create if missing, otherwise return existing — matched by exact name. */
+	async ensureProject(input) {
+		const existing = await this.findSiteByName(input.name);
+		if (existing) return toDeploymentProject(existing);
+		const accountSlug = this.opts.accountSlug;
+		if (!accountSlug) throw new Error("@theholocron/holocron-plugin-netlify: ensureProject needs `accountSlug` in plugin options (Netlify's create-site endpoint is scoped to /{account_slug}/sites)");
+		try {
+			return toDeploymentProject(await this.client().sites.create(accountSlug, { name: input.name }));
+		} catch (err) {
+			if (err instanceof ProviderApiError && (err.status === 422 || err.status === 409)) {
+				const recheck = await this.findSiteByName(input.name);
+				if (recheck) return toDeploymentProject(recheck);
+			}
+			throw err;
+		}
+	}
+	/**
+	* Netlify has no direct equivalent of Vercel's git-linked project
+	* settings (`previewDeploymentsDisabled` / `gitProviderCreateDeployments`)
+	* — Sentinel's site isn't git-linked at all. Best-effort: return the
+	* project unchanged. Revisit if a future consumer needs a real mapping.
+	*/
+	async updateProjectSettings(projectId, _settings) {
+		return toDeploymentProject(await this.client().sites.get(projectId));
+	}
+	async listEnvVars(projectId, target) {
+		const accountId = this.requireAccountId();
+		const context = toNetlifyContext(target);
+		return (await this.client().env.list(accountId, projectId)).filter((v) => v.values.some((value) => value.context === context)).map((v) => v.key);
+	}
+	async setEnvVar(projectId, target, name, value) {
+		const accountId = this.requireAccountId();
+		await this.client().env.set(accountId, projectId, name, toNetlifyContext(target), value);
+	}
+	/**
+	* No Git integration in Sentinel's usage (file-based deploy only), but
+	* REQUIRED by the interface. Netlify's branch-triggered-build endpoint
+	* is the closest analog for a git-linked site; untested against a real
+	* git-linked Netlify site since no current consumer exercises this path.
+	*/
+	async triggerDeployment(input) {
+		const build = await this.client().sites.triggerBuild(input.projectId);
+		if (!build.deploy_id) throw new Error("@theholocron/holocron-plugin-netlify: triggerDeployment got no deploy_id back from Netlify");
+		return toDeploymentRecord(await this.client().deploys.get(build.deploy_id));
+	}
+	async getDeployment(deploymentId) {
+		return toDeploymentRecord(await this.client().deploys.get(deploymentId));
+	}
+	/**
+	* Zips `config.files` (plain text, per the interface contract) and
+	* uploads it as a one-shot deploy. Netlify runs no build step for a
+	* raw zip upload — the caller (Sentinel's own stage-deploy script) is
+	* responsible for having already resolved dependencies into the file
+	* set, the same discipline Vercel's `deployFunction` path already
+	* requires via its own trimmed/pinned package.json.
+	*/
+	async deployFunction(projectId, config) {
+		const deploy = await this.client().deploys.createFromZip(projectId, config.files, { draft: config.target === void 0 });
+		return {
+			deploymentId: deploy.id,
+			url: deploy.ssl_url || deploy.url
+		};
+	}
+	/**
+	* Idempotent: PATCHing the same `custom_domain` twice is a no-op on
+	* Netlify's side. Unlike Vercel, Netlify's API has no DNS-misconfiguration
+	* check to consult — it's returned unconditionally once set, which is
+	* safe because `Dns.upsertRecord()` on the receiving end is itself
+	* idempotent (re-upserting an already-correct CNAME is a no-op there).
+	*/
+	async ensureCustomDomain(projectId, hostname) {
+		const site = await this.client().sites.get(projectId);
+		if (site.custom_domain !== hostname) await this.client().sites.update(projectId, { custom_domain: hostname });
+		const labels = hostname.split(".");
+		return {
+			zone: labels.length > 2 ? labels.slice(-2).join(".") : hostname,
+			record: {
+				type: "CNAME",
+				name: hostname,
+				content: new URL(site.ssl_url || site.url).hostname
+			}
+		};
+	}
+	async findSiteByName(name) {
+		return (await this.client().sites.list()).find((s) => s.name === name);
+	}
+	requireAccountId() {
+		if (!this.opts.accountId) throw new Error("@theholocron/holocron-plugin-netlify: env var methods need `accountId` in plugin options (Netlify's env API is scoped to /accounts/{account_id}/env)");
+		return this.opts.accountId;
+	}
+};
+//#endregion
+//#region src/verify-token.ts
+/**
+* `verifyToken` — plugin-level export used by `holocron auth set` +
+* `holocron auth check`. Hits Netlify's `GET /user` (current token's
+* identity) and translates the response into the normalized
+* `VerifyTokenResult` shape.
+*
+* Kept as a standalone function (not a capability method) so the auth
+* command can call it without initializing the full plugin — plugin
+* construction requires an already-resolved token, which is exactly
+* what we don't have yet at bootstrap time.
+*/
+async function verifyToken(token, opts = {}) {
+	const client = createNetlifyClient({
+		token,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
+	try {
+		const user = await client.user.get();
+		return {
+			ok: true,
+			subject: `user @ ${user?.email ?? user?.full_name ?? user?.id ?? "unknown"}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+function createContext(options) {
+	let client;
+	return {
+		options,
+		client: () => client ??= createNetlifyClient({
+			token: resolveToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})
+	};
+}
+function deployment(ctx) {
+	const opts = {};
+	if (ctx.options.accountSlug !== void 0) opts.accountSlug = ctx.options.accountSlug;
+	if (ctx.options.accountId !== void 0) opts.accountId = ctx.options.accountId;
+	if (ctx.options.domain !== void 0) opts.domain = ctx.options.domain;
+	return new NetlifyDeployment(ctx.client, opts);
+}
+function createPlugin(options) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-netlify",
+		capabilities: { deployment: () => deployment(ctx) }
+	};
+}
+/**
+* One-line hint printed by `holocron auth set netlify` when no token is
+* supplied or the supplied token is rejected.
+*/
+const AUTH_HINT = "generate a Netlify Personal Access Token at https://app.netlify.com/user/applications#personal-access-tokens, then run: holocron auth set netlify <TOKEN>";
+//#endregion
+export { AUTH_HINT, AuthError, NetlifyDeployment, createContext, createPlugin, deployment, resolveToken, verifyToken };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@theholocron/holocron-plugin-netlify",
+  "version": "2.0.0-alpha.1",
+  "description": "Holocron plugin for Netlify. Implements the deployment capability against Netlify's REST API, plus exports verifyToken + AUTH_HINT for `holocron auth`.",
+  "keywords": [
+    "deployment",
+    "holocron",
+    "netlify",
+    "plugin"
+  ],
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-netlify#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-netlify"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@theholocron/http-client": "^1.36.0",
+    "@theholocron/netlify-client": "^1.36.0",
+    "@theholocron/tsconfig": "^8.4.5",
+    "@types/node": "^26",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.8.1",
+    "globals": "^17.11.0",
+    "tsdown": "^0.22.14",
+    "tsx": "4.23.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@theholocron/cli": "5.0.0-alpha.109"
+  },
+  "peerDependencies": {
+    "@theholocron/netlify-client": "^1.36.0",
+    "@theholocron/cli": "5.0.0-alpha.109"
+  },
+  "peerDependenciesMeta": {
+    "@theholocron/netlify-client": {}
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "delivery.build": "tsdown",
+    "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
+    "test:watch": "vitest",
+    "validate": "tsx scripts/validate.mjs",
+    "verification.typeSafety": "holocron run verification.typeSafety --",
+    "verification.unitTests": "holocron run verification.unitTests --"
+  }
+}