@theholocron/holocron-plugin-neon 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,48 @@
+# `@theholocron/holocron-plugin-neon`
+
+Neon plugin for [Holocron](../cli). Implements the `storage`
+capability against [Neon's REST API](https://api-docs.neon.tech/reference/getting-started-with-neon-api).
+
+## Auth
+
+Token resolution order:
+
+1. `--token <PAT>` flag on the holocron invocation
+2. `HOLOCRON_NEON_API_KEY` env var
+3. `NEON_API_KEY` env var (the default Neon's own CLI reads)
+
+## Config
+
+```jsonc
+{
+  "providers": {
+    "storage": ["neon", { "projectId": "ancient-resonance-…" }]
+  }
+}
+```
+
+- `projectId` (required) — the Neon project id. The plugin binds to
+  this project; every method operates within it.
+
+## What's implemented
+
+| Method                  | What it does                                              |
+| ----------------------- | --------------------------------------------------------- |
+| `getConnectionString`   | Fetches the connection URI for a branch. `pooled: true` returns the PgBouncer URL. |
+| `listBranches`          | All branches on the bound project.                        |
+| `createBranch`          | Provisions a branch + a read_write compute endpoint inline (so the next connection-string call doesn't 404). |
+| `destroyBranch`         | DELETEs a branch.                                         |
+| `resetBranch`           | Restores one branch to match another (Neon "restore branch" endpoint). |
+| `enableExtension`       | Runs `CREATE EXTENSION IF NOT EXISTS "..."` against the branch's default database via Neon's run_sql endpoint. Used for PostGIS, pgvector, etc. |
+
+Vercel-managed Neon orgs reject project-create at the Neon API level
+("organization is managed by Vercel"). For those setups, provision
+the project via Vercel's marketplace integration (`vercel install
+neon`) — the project becomes visible to Neon's API afterward and
+holocron can take it from there. Marketplace provisioning is out of
+scope for this plugin (covered by `holocron-plugin-vercel` if needed
+later).
+
+## Status
+
+**v0.0.0 — first port.**

package/dist/index.d.mts

@@ -0,0 +1,105 @@
+import { ConnectionStringOptions, Storage, StorageBranch } from "@theholocron/cli";
+
+//#region src/auth.d.ts
+/**
+ * Token resolution for the Neon plugin.
+ *
+ * Resolution order:
+ *   1. explicit `cliToken` argument (from `--token` flag)
+ *   2. HOLOCRON_NEON_API_KEY env var (preferred — explicit intent)
+ *   3. NEON_API_KEY env var (the default Neon CLI reads)
+ */
+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 console.neon.tech/api/v2.
+ *
+ * Same pattern as the GitHub + Vercel REST clients — bearer auth,
+ * JSON-only bodies, transport-failure wrapping with status: 0 so the
+ * orchestrator's soft-skip path sees a clear "Neon GET /path failed"
+ * message instead of a generic `TypeError: fetch failed`.
+ */
+interface RestClientOptions {
+  token: string;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+  body?: unknown;
+  query?: Record<string, string>;
+}
+declare class NeonRestClient {
+  private readonly token;
+  private readonly fetchImpl;
+  readonly baseUrl: string;
+  constructor(opts: RestClientOptions);
+  request<T>(path: string, opts?: RequestOptions): Promise<T>;
+}
+//#endregion
+//#region src/capabilities/storage.d.ts
+interface StorageOptions {
+  projectId: string;
+}
+declare class NeonStorage implements Storage {
+  private readonly rest;
+  readonly key: "storage";
+  readonly providerName = "neon";
+  private readonly base;
+  constructor(rest: NeonRestClient, opts: StorageOptions);
+  getConnectionString(scope: string, options?: ConnectionStringOptions): Promise<string>;
+  listBranches(): Promise<StorageBranch[]>;
+  createBranch(input: {
+    name: string;
+    from?: string;
+  }): Promise<StorageBranch>;
+  destroyBranch(branch: string): Promise<void>;
+  resetBranch(input: {
+    branch: string;
+    from: string;
+  }): Promise<void>;
+  enableExtension(input: {
+    branch: string;
+    extension: string;
+  }): Promise<void>;
+  /**
+   * The first database on a branch — the "default" for connection-string
+   * and extension purposes. Throws if the branch has no databases (which
+   * means it was created without an endpoint and needs initialization).
+   */
+  private firstDatabase;
+}
+//#endregion
+//#region src/index.d.ts
+interface NeonPluginOptions extends ResolveTokenInput {
+  /** Neon project id this plugin is bound to. Required. */
+  projectId: string;
+  /** Override base URL for tests. */
+  baseUrl?: string;
+  /** Override `fetch` for tests. */
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: NeonPluginOptions;
+  rest: NeonRestClient;
+}
+declare function createContext(options: NeonPluginOptions): PluginContext;
+declare function storage(ctx: PluginContext): Storage;
+declare function createPlugin(options: NeonPluginOptions): {
+  name: string;
+  capabilities: {
+    storage: () => Storage;
+  };
+};
+//#endregion
+export { AuthError, NeonPluginOptions, NeonRestClient, NeonStorage, PluginContext, ResolveTokenInput, createContext, createPlugin, resolveToken, storage };

package/dist/index.mjs

@@ -0,0 +1,185 @@
+import { ProviderApiError } from "@theholocron/cli";
+//#region src/auth.ts
+/**
+* Token resolution for the Neon plugin.
+*
+* Resolution order:
+*   1. explicit `cliToken` argument (from `--token` flag)
+*   2. HOLOCRON_NEON_API_KEY env var (preferred — explicit intent)
+*   3. NEON_API_KEY env var (the default Neon CLI reads)
+*/
+var AuthError = class extends Error {
+	name = "AuthError";
+};
+function resolveToken(input = {}) {
+	const env = input.env ?? process.env;
+	const token = input.cliToken || env.HOLOCRON_NEON_API_KEY || env.NEON_API_KEY;
+	if (!token) throw new AuthError("no Neon API key found. Pass --token <KEY>, or set HOLOCRON_NEON_API_KEY / NEON_API_KEY.");
+	return token;
+}
+//#endregion
+//#region src/capabilities/storage.ts
+/**
+* `storage` capability for Neon.
+*
+* Ported from rando-id/rando.id `adapters/neon.ts`, bound to a single
+* Neon project (the `projectId` plugin option). All methods operate
+* within that project.
+*
+* Branch ops use Neon's REST API directly. `enableExtension` runs SQL
+* against the branch's default database via the `run_sql` endpoint —
+* Neon doesn't have a dedicated "create extension" endpoint, so this
+* goes through SQL.
+*
+* Project-create is deliberately omitted: Vercel-managed Neon orgs
+* reject create at the API level, and the recipe (`vercel install neon`
+* → wait for project to appear → bind by id) is unavoidable for those
+* setups. The plugin assumes the project already exists and is bound
+* via `projectId` in options.
+*/
+var NeonStorage = class {
+	rest;
+	key = "storage";
+	providerName = "neon";
+	base;
+	constructor(rest, opts) {
+		this.rest = rest;
+		if (!opts.projectId) throw new Error("NeonStorage requires `projectId` in options");
+		this.base = `/projects/${opts.projectId}`;
+	}
+	async getConnectionString(scope, options = {}) {
+		const db = await this.firstDatabase(scope);
+		const params = {
+			branch_id: scope,
+			database_name: db.name,
+			role_name: db.owner_name,
+			pooled: options.pooled ? "true" : "false"
+		};
+		return (await this.rest.request(`${this.base}/connection_uri`, { query: params })).uri;
+	}
+	async listBranches() {
+		return (await this.rest.request(`${this.base}/branches`)).branches.map(mapBranch);
+	}
+	async createBranch(input) {
+		return mapBranch((await this.rest.request(`${this.base}/branches`, {
+			method: "POST",
+			body: {
+				branch: {
+					name: input.name,
+					...input.from ? { parent_id: input.from } : {}
+				},
+				endpoints: [{ type: "read_write" }]
+			}
+		})).branch);
+	}
+	async destroyBranch(branch) {
+		await this.rest.request(`${this.base}/branches/${encodeURIComponent(branch)}`, { method: "DELETE" });
+	}
+	async resetBranch(input) {
+		await this.rest.request(`${this.base}/branches/${encodeURIComponent(input.branch)}/restore`, {
+			method: "POST",
+			body: { source_branch_id: input.from }
+		});
+	}
+	async enableExtension(input) {
+		const db = await this.firstDatabase(input.branch);
+		await this.rest.request(`${this.base}/branches/${encodeURIComponent(input.branch)}/databases/${encodeURIComponent(db.name)}/run_sql`, {
+			method: "POST",
+			body: { query: `CREATE EXTENSION IF NOT EXISTS "${input.extension}"` }
+		});
+	}
+	/**
+	* The first database on a branch — the "default" for connection-string
+	* and extension purposes. Throws if the branch has no databases (which
+	* means it was created without an endpoint and needs initialization).
+	*/
+	async firstDatabase(branchId) {
+		const db = (await this.rest.request(`${this.base}/branches/${encodeURIComponent(branchId)}/databases`)).databases[0];
+		if (!db) throw new ProviderApiError(`Neon branch ${branchId} has no databases — initialize the branch first`, 404, void 0);
+		return db;
+	}
+};
+function mapBranch(raw) {
+	return {
+		id: raw.id,
+		name: raw.name,
+		parentId: raw.parent_id ?? null,
+		createdAt: raw.created_at
+	};
+}
+//#endregion
+//#region src/rest.ts
+/**
+* Thin REST wrapper around console.neon.tech/api/v2.
+*
+* Same pattern as the GitHub + Vercel REST clients — bearer auth,
+* JSON-only bodies, transport-failure wrapping with status: 0 so the
+* orchestrator's soft-skip path sees a clear "Neon GET /path failed"
+* message instead of a generic `TypeError: fetch failed`.
+*/
+var NeonRestClient = class {
+	token;
+	fetchImpl;
+	baseUrl;
+	constructor(opts) {
+		this.token = opts.token;
+		this.fetchImpl = opts.fetch ?? globalThis.fetch;
+		this.baseUrl = (opts.baseUrl ?? "https://console.neon.tech/api/v2").replace(/\/+$/, "");
+	}
+	async request(path, opts = {}) {
+		const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`);
+		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(`Neon ${init.method} ${path} failed: ${detail}`, 0, void 0);
+		}
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			throw new ProviderApiError(`Neon ${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) {
+	if (!options.projectId) throw new Error("@theholocron/holocron-plugin-neon requires `projectId` in options");
+	const restOpts = { token: resolveToken(options) };
+	if (options.baseUrl !== void 0) restOpts.baseUrl = options.baseUrl;
+	if (options.fetch !== void 0) restOpts.fetch = options.fetch;
+	return {
+		options,
+		rest: new NeonRestClient(restOpts)
+	};
+}
+function storage(ctx) {
+	return new NeonStorage(ctx.rest, { projectId: ctx.options.projectId });
+}
+function createPlugin(options) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-neon",
+		capabilities: { storage: () => storage(ctx) }
+	};
+}
+//#endregion
+export { AuthError, NeonRestClient, NeonStorage, createContext, createPlugin, resolveToken, storage };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@theholocron/holocron-plugin-neon",
+  "version": "2.0.0-alpha.0",
+  "description": "Holocron plugin for Neon. Implements the storage capability against Neon's REST API — branch ops, connection strings, extensions.",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-neon#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-neon"
+  },
+  "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"
+}