@theholocron/dagobah 0.0.0-stage → 5.0.0-alpha.338

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

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# `@theholocron/dagobah`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs a web-standard handler (`(Request, env) => Response`) locally, for a development instance behind a tunnel. It
+loads the handler's secrets from a 1Password Environment, puts them in `process.env`, imports the handler, serves it
+on the loopback address and says where its logs go.
+
+Published for any project with a web-standard handler to run locally. `holocron dev serve` is built on it, and Sentinel's `scripts/serve.ts` was its first user.
+
+> Dagobah is the swamp where Luke trains, away from the real thing. This is where a handler runs before it ships.
+
+## Usage
+
+```ts
+import { serveHandler } from "@theholocron/dagobah";
+
+await serveHandler({
+  environment: "Sentinel - dev", // the 1Password Environment
+  required: ["GITHUB_APP_ID", "GITHUB_APP_PRIVATE_KEY", "SENTINEL_WEBHOOK_SECRET"],
+  logging: { tokenVar: "SENTINEL_AXIOM_INGEST_TOKEN", datasetVar: "AXIOM_DATASET" },
+  port: Number(process.env.PORT ?? 3000),
+  handler: async () => (await import("../src/handler/index.js")).handleWebhookRequest,
+});
+```
+
+- `loadDevEnv({ environment, required })`: the process wins over the Environment; throws naming (never showing)
+  what is missing. An unquoted multi-line value (a PEM key, which `op` prints that way) is read whole.
+- `startDevServer({ handle, env, port })`: loopback only; one log line per request (method, path, status).
+- `describeLogging(env, { tokenVar, datasetVar })`: one line, the dataset and never the token.

package/dist/index.d.mts

@@ -0,0 +1,93 @@
+import { spawnSync } from "node:child_process";
+/** What {@link loadDevEnv} needs: which 1Password Environment holds the secrets, and which variables must be set. */
+interface LoadDevEnvInput<K extends string = string> {
+  /** The name of the 1Password Environment, e.g. `Sentinel - dev`. */
+  environment: string;
+  /** The variables the app cannot start without. Loading throws, naming any that are in neither place. */
+  required: readonly K[];
+  /** The variables already in the process. These win over the Environment. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv | undefined;
+  /** Runs `op`. Defaults to `spawnSync`. */
+  spawn?: typeof spawnSync | undefined;
+}
+/** The environment the handler is given: the `required` variables, set, and anything else the Environment holds. */
+type DevEnv<K extends string = string> = NodeJS.ProcessEnv & Record<K, string>;
+/**
+ * The environment a local app runs with: the variables already in the process, and what the 1Password
+ * Environment `environment` holds for the rest (read with `op environment secret list`, the way the 1Password
+ * plugin reads one, so Touch ID asks once). The process wins, so a variable exported for one run overrides the
+ * Environment. The `required` ones must end up set; a message names the ones that are not, and never a
+ * value. Nothing is written to disk.
+ */
+export declare function loadDevEnv<K extends string>(input: LoadDevEnvInput<K>): DevEnv<K>;
+/** Which variables {@link describeLogging} reads. */
+interface DescribeLoggingOptions {
+  /** The variable holding the Axiom ingest token, e.g. `SENTINEL_AXIOM_INGEST_TOKEN`. */
+  tokenVar: string;
+  /** The variable holding the Axiom dataset, e.g. `AXIOM_DATASET`. */
+  datasetVar: string;
+}
+/**
+ * One line saying where this run's structured logs go: they ship to Axiom when both variables are set. Names the
+ * dataset (not a secret) and never the token, so a development run does not quietly write into production's dataset.
+ */
+export declare function describeLogging(env: Record<string, string | undefined>, options: DescribeLoggingOptions): string;
+/** What {@link startDevServer} needs: the handler to call, the environment to give it, and where to listen. */
+interface DevServerInput<E> {
+  /** The handler a request is passed to, with `env`. Sentinel's is `handleWebhookRequest`. */
+  handle: (request: Request, env: E) => Promise<Response>;
+  /** The environment handed to the handler on every request. */
+  env: E;
+  /** The port to listen on. `0` picks a free one. */
+  port: number;
+  /** The only path the handler is served on; any other is a 404. Defaults to `/api/webhook`, the path Vercel serves. */
+  path?: string | undefined;
+  /** One line per request: the method, the path and the status. Never a header or a body. Defaults to nothing. */
+  log?: ((line: string) => void) | undefined;
+}
+/** A running development server. */
+interface DevServer {
+  /** The address the handler is served on, e.g. `http://127.0.0.1:3000/api/webhook`. */
+  url: string;
+  /** Stops the server, ending any open connection. */
+  close: () => Promise<void>;
+}
+/**
+ * Serves a `(Request, env) => Response` handler over HTTP on the loopback address, for a development instance behind
+ * a tunnel: the same function the Vercel entry (e.g. Sentinel's `api/webhook.mjs`) calls, with the same web-standard `Request`. Only
+ * the handler's own path is served. A request is logged as one line (method, path, status) and nothing else, so no
+ * signature, token or payload reaches the terminal.
+ */
+export declare function startDevServer<E>(input: DevServerInput<E>): Promise<DevServer>;
+/** What {@link serveHandler} needs. */
+interface ServeHandlerInput<K extends string> {
+  /** The 1Password Environment holding the secrets, unless the process already has every `required` variable. */
+  environment: string;
+  /** The variables the handler cannot run without. */
+  required: readonly K[];
+  /** Imports the handler. Called after the environment is in `process.env`, because a handler that builds its logger from `process.env` when its module loads would otherwise see the wrong one. */
+  handler: () => Promise<(request: Request, env: Record<K, string> & NodeJS.ProcessEnv) => Promise<Response>>;
+  /** Which variables hold the Axiom token and dataset, to say where this run's logs go. Omit to say nothing about logs. */
+  logging?: DescribeLoggingOptions | undefined;
+  /** The port to listen on. `0` picks a free one. */
+  port: number;
+  /** The only path served. Default `/api/webhook`. */
+  path?: string | undefined;
+  /** The variables in the process. Default `process.env`. */
+  env?: NodeJS.ProcessEnv | undefined;
+  /** Runs `op` to read the Environment. Default `spawnSync`; a test passes a stub so no real `op` starts. */
+  spawn?: typeof spawnSync | undefined;
+  /** One line of output. Default `console.log`. */
+  log?: ((line: string) => void) | undefined;
+  /** Called on SIGINT and SIGTERM to stop the server and exit. Default `process.exit(0)` after the server closes. */
+  onSignal?: ((close: () => Promise<void>) => void) | undefined;
+}
+/**
+ * Runs a web-standard handler locally: loads its environment, puts it in `process.env`, imports the handler, serves
+ * it on the loopback address and says where it is listening and where its logs go. The server stops, and the process
+ * exits, on SIGINT and SIGTERM.
+ *
+ * @returns The running server.
+ */
+export declare function serveHandler<K extends string>(input: ServeHandlerInput<K>): Promise<DevServer>;
+export type { DescribeLoggingOptions, DevEnv, DevServer, DevServerInput, LoadDevEnvInput, ServeHandlerInput };

package/dist/index.mjs

@@ -0,0 +1,155 @@
+import { spawnSync } from "node:child_process";
+import { parse } from "dotenv";
+import { createServer } from "node:http";
+// src/quote-pem/quote-pem.ts
+/**
+* Wrap an unquoted PEM block in double quotes. `op environment secret list --format=dotenv` prints a multi-line
+* value (a private key) unquoted, which `dotenv` reads as its first line only; quoted, it reads the whole block.
+* A PEM holds no quote or backslash, so nothing needs escaping.
+*/
+function quotePem(text) {
+	return text.replace(/^([A-Za-z_][A-Za-z0-9_]*)=(-----BEGIN [^-]+-----[\s\S]*?-----END [^-]+-----)[ \t]*$/gm, "$1=\"$2\"");
+}
+// src/dev-env/dev-env.ts
+/**
+* The environment a local app runs with: the variables already in the process, and what the 1Password
+* Environment `environment` holds for the rest (read with `op environment secret list`, the way the 1Password
+* plugin reads one, so Touch ID asks once). The process wins, so a variable exported for one run overrides the
+* Environment. The `required` ones must end up set; a message names the ones that are not, and never a
+* value. Nothing is written to disk.
+*/
+function loadDevEnv(input) {
+	const REQUIRED = input.required;
+	const env = input.env ?? process.env;
+	const present = (name) => (env[name] ?? "") !== "";
+	let merged = env;
+	if (!REQUIRED.every(present)) {
+		const result = (input.spawn ?? spawnSync)("op", [
+			"environment",
+			"secret",
+			"list",
+			input.environment,
+			"--reveal",
+			"--format=dotenv"
+		], {
+			encoding: "utf8",
+			stdio: [
+				"inherit",
+				"pipe",
+				"pipe"
+			]
+		});
+		if (result.error || result.status !== 0) {
+			const why = result.error?.message ?? result.stderr.trim().split("\n")[0];
+			throw new Error(`could not read the 1Password Environment "${input.environment}": ${why || "op failed"}`);
+		}
+		merged = {
+			...parse(quotePem(String(result.stdout))),
+			...Object.fromEntries(Object.entries(env).filter(([, v]) => v !== void 0 && v !== ""))
+		};
+	}
+	const missing = REQUIRED.filter((name) => (merged[name] ?? "") === "");
+	if (missing.length > 0) throw new Error(`missing from the environment and from "${input.environment}": ${missing.join(", ")}`);
+	return merged;
+}
+// src/dev-logging/dev-logging.ts
+/**
+* One line saying where this run's structured logs go: they ship to Axiom when both variables are set. Names the
+* dataset (not a secret) and never the token, so a development run does not quietly write into production's dataset.
+*/
+function describeLogging(env, options) {
+	const token = env[options.tokenVar];
+	const dataset = env[options.datasetVar];
+	return token && dataset ? `logs: shipped to Axiom, dataset "${dataset}"` : `logs: not shipped to Axiom (${options.tokenVar} and ${options.datasetVar} are not both set)`;
+}
+// src/dev-server/dev-server.ts
+const LOOPBACK = "127.0.0.1";
+/** GitHub caps a webhook payload at 25 MB; anything larger is not one. */
+const MAX_BODY = 27262976;
+/** The request body, or `undefined` when it is larger than a webhook can be. */
+async function readBody(req) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		size += chunk.length;
+		if (size > MAX_BODY) return void 0;
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks);
+}
+/**
+* Serves a `(Request, env) => Response` handler over HTTP on the loopback address, for a development instance behind
+* a tunnel: the same function the Vercel entry (e.g. Sentinel's `api/webhook.mjs`) calls, with the same web-standard `Request`. Only
+* the handler's own path is served. A request is logged as one line (method, path, status) and nothing else, so no
+* signature, token or payload reaches the terminal.
+*/
+async function startDevServer(input) {
+	const path = input.path ?? "/api/webhook";
+	const log = input.log ?? (() => {});
+	const server = createServer(async (req, res) => {
+		const method = req.method;
+		const url = new URL(req.url, `http://${LOOPBACK}`);
+		const reply = (status, body, headers = {}) => {
+			log(`${method} ${url.pathname} ${status}`);
+			res.writeHead(status, headers);
+			res.end(body);
+		};
+		if (url.pathname !== path) return reply(404, "Not Found");
+		const hasBody = method !== "GET" && method !== "HEAD";
+		const body = hasBody ? await readBody(req) : void 0;
+		if (hasBody && body === void 0) return reply(413, "Payload Too Large");
+		const headers = new Headers();
+		for (let i = 0; i < req.rawHeaders.length; i += 2) headers.append(req.rawHeaders[i], req.rawHeaders[i + 1]);
+		try {
+			const response = await input.handle(new Request(`http://${req.headers.host}${req.url}`, {
+				method,
+				headers,
+				...body ? { body } : {}
+			}), input.env);
+			reply(response.status, Buffer.from(await response.arrayBuffer()), Object.fromEntries(response.headers));
+		} catch {
+			reply(500, "Internal Server Error");
+		}
+	});
+	await new Promise((resolve) => server.listen(input.port, LOOPBACK, resolve));
+	const { port } = server.address();
+	return {
+		url: `http://${LOOPBACK}:${port}${path}`,
+		close: () => new Promise((resolve) => {
+			server.close(() => resolve());
+			server.closeAllConnections();
+		})
+	};
+}
+// src/serve-handler/serve-handler.ts
+/**
+* Runs a web-standard handler locally: loads its environment, puts it in `process.env`, imports the handler, serves
+* it on the loopback address and says where it is listening and where its logs go. The server stops, and the process
+* exits, on SIGINT and SIGTERM.
+*
+* @returns The running server.
+*/
+async function serveHandler(input) {
+	const log = input.log ?? ((line) => console.log(line));
+	const settings = input.env ?? process.env;
+	const env = loadDevEnv({
+		environment: input.environment,
+		required: input.required,
+		env: settings,
+		...input.spawn ? { spawn: input.spawn } : {}
+	});
+	Object.assign(process.env, env);
+	const server = await startDevServer({
+		handle: await input.handler(),
+		env,
+		port: input.port,
+		...input.path ? { path: input.path } : {},
+		log
+	});
+	log(`listening on ${server.url}, secrets from "${input.environment}"`);
+	if (input.logging) log(describeLogging(env, input.logging));
+	const stop = input.onSignal ?? ((close) => void close().then(() => process.exit(0)));
+	for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => stop(server.close));
+	return server;
+}
+export { describeLogging, loadDevEnv, serveHandler, startDevServer };

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@theholocron/dagobah",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "5.0.0-alpha.338",
+  "description": "Local development server for a web-standard handler: loads its secrets from a 1Password Environment and serves it over HTTP behind a tunnel.",
+  "keywords": [
+    "dev-server",
+    "holocron",
+    "theholocron",
+    "tunnel"
+  ],
+  "homepage": "https://docs.theholocron.dev/holocron/dagobah/",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "cli/dagobah"
+  },
+  "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"
+  ],
+  "dependencies": {
+    "dotenv": "^17.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26",
+    "@vitest/coverage-v8": "^5.0.5",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "eslint": "^10.14.0",
+    "eslint-plugin-n": "^18.5.0",
+    "globals": "^17.14.0",
+    "tsdown": "^0.23.4",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5",
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
+    "@theholocron/vitest-config": "^8.9.0-alpha.8",
+    "@theholocron/tsconfig": "^8.9.0-alpha.8"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
 }