@quantile-co/factory-github 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quantile LLC
+
+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/dist/index.d.ts

@@ -0,0 +1,31 @@
+export interface Execution {
+  logFile?: string;
+  append?: boolean;
+  signal?: AbortSignal;
+}
+export type Execute = (program: string, args: readonly string[], execution?: Execution) => Promise<string>;
+export interface ActionInput {
+  planFile: string;
+  logFile: string;
+  signal?: AbortSignal;
+}
+export type Action = (input: ActionInput) => Promise<void>;
+export interface TransportOptions {
+  bucket: string;
+  repositoryId: string;
+  runId: string;
+  attempt: string;
+  scratchDirectory: string;
+  signal?: AbortSignal;
+}
+export declare class CommandFailure extends Error {
+  readonly exitCode: number;
+  constructor(exitCode: number, message: string);
+}
+export declare function processRunner(environment: NodeJS.ProcessEnv): Execute;
+export declare function plan(options: TransportOptions & {
+  summaryFile: string;
+}, action: Action, execute: Execute): Promise<string>;
+export declare function apply(options: TransportOptions & {
+  planReference: string;
+}, action: Action, execute: Execute): Promise<void>;

package/dist/index.js

@@ -0,0 +1,194 @@
+import { spawn } from "node:child_process";
+import { appendFileSync, chmodSync, closeSync, lstatSync, mkdirSync, openSync, rmSync } from "node:fs";
+import { constants } from "node:os";
+import { isAbsolute, join } from "node:path";
+// src/index.ts
+var CommandFailure = class extends Error {
+	exitCode;
+	constructor(exitCode, message) {
+		super(message);
+		this.exitCode = exitCode;
+	}
+};
+function processRunner(environment) {
+	return (program, args, options = {}) => new Promise((resolve, reject) => {
+		if (options.signal?.aborted) {
+			reject(new CommandFailure(130, "Command cancelled"));
+			return;
+		}
+		const fd = options.logFile ? openSync(options.logFile, options.append ? "a" : "w", 384) : void 0;
+		const grouped = process.platform !== "win32";
+		const child = spawn(program, [...args], {
+			env: environment,
+			detached: grouped,
+			stdio: [
+				"ignore",
+				fd ?? "pipe",
+				fd ?? "pipe"
+			]
+		});
+		let cancelled = false;
+		let failedToSpawn = false;
+		let killTimer;
+		const terminate = (signal) => {
+			if (!child.pid) return;
+			try {
+				if (grouped) process.kill(-child.pid, signal);
+				else child.kill(signal);
+			} catch (error) {
+				if (error.code !== "ESRCH") throw error;
+			}
+		};
+		const cancel = () => {
+			cancelled = true;
+			terminate("SIGTERM");
+			killTimer = setTimeout(() => terminate("SIGKILL"), 5e3);
+			killTimer.unref();
+		};
+		options.signal?.addEventListener("abort", cancel, { once: true });
+		const output = [];
+		child.stdout?.on("data", (data) => output.push(data));
+		child.stderr?.resume();
+		child.on("error", () => {
+			failedToSpawn = true;
+		});
+		child.on("close", (code, signal) => {
+			options.signal?.removeEventListener("abort", cancel);
+			if (killTimer) clearTimeout(killTimer);
+			if (cancelled) terminate("SIGKILL");
+			if (fd !== void 0) closeSync(fd);
+			const status = code && code > 0 ? code : signal ? 128 + constants.signals[signal] : cancelled ? 130 : failedToSpawn ? 1 : 0;
+			if (status === 0) resolve(Buffer.concat(output).toString("utf8").trim());
+			else reject(new CommandFailure(status, cancelled ? "Command cancelled" : `${program} failed`));
+		});
+	});
+}
+function validate(options) {
+	if (!/^[a-z0-9][a-z0-9._-]*$/.test(options.bucket)) throw new Error("Invalid state bucket");
+	for (const value of [
+		options.repositoryId,
+		options.runId,
+		options.attempt
+	]) if (!/^[1-9][0-9]*$/.test(value)) throw new Error("Invalid repository/run/attempt ID");
+	if (!isAbsolute(options.scratchDirectory)) throw new Error("Runner scratch directory must be absolute");
+}
+function privatePaths(options, phase) {
+	const directory = join(options.scratchDirectory, "saved-plan");
+	try {
+		mkdirSync(directory, { mode: 448 });
+	} catch (error) {
+		if (error.code === "EEXIST") throw new Error("Private scratch path already exists");
+		throw error;
+	}
+	const planFile = join(directory, "plan.tfplan");
+	const logFile = join(directory, `${phase}.log`);
+	try {
+		closeSync(openSync(logFile, "wx", 384));
+	} catch (error) {
+		rmSync(directory, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	return {
+		directory,
+		planFile,
+		logFile
+	};
+}
+function requirePlan(path) {
+	const info = lstatSync(path, { throwIfNoEntry: false });
+	if (!info?.isFile() || info.size === 0) throw new Error("No regular saved plan produced");
+	chmodSync(path, 384);
+}
+function base(options) {
+	return `gs://${options.bucket}/plans/${options.repositoryId}`;
+}
+async function failureLog(execute, logFile, destination) {
+	try {
+		await execute("gcloud", [
+			"storage",
+			"cp",
+			logFile,
+			destination,
+			"--if-generation-match=0",
+			"--quiet"
+		], { signal: AbortSignal.timeout(1e4) });
+	} catch {}
+}
+async function plan(options, action, execute) {
+	validate(options);
+	if (!isAbsolute(options.summaryFile)) throw new Error("Step summary path must be absolute");
+	const paths = privatePaths(options, "plan");
+	const destination = `${base(options)}/${options.runId}/${options.attempt}`;
+	try {
+		await action({
+			...paths,
+			signal: options.signal
+		});
+		requirePlan(paths.planFile);
+		await execute("gcloud", [
+			"storage",
+			"cp",
+			"--recursive",
+			paths.directory,
+			`${destination}/`,
+			"--if-generation-match=0",
+			"--quiet"
+		], { signal: options.signal });
+		const generation = await execute("gcloud", [
+			"storage",
+			"objects",
+			"describe",
+			`${destination}/saved-plan/plan.tfplan`,
+			"--raw",
+			"--format=value(generation)"
+		], { signal: options.signal });
+		if (!/^[1-9][0-9]*$/.test(generation)) throw new Error("Invalid saved-plan generation");
+		const reference = `${options.runId}/${options.attempt}/${generation}`;
+		appendFileSync(options.summaryFile, `Plan reference: ${reference}\n`, { mode: 384 });
+		return reference;
+	} catch (error) {
+		await failureLog(execute, paths.logFile, `${destination}/plan.log`);
+		throw error;
+	} finally {
+		rmSync(paths.directory, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function apply(options, action, execute) {
+	validate(options);
+	const reference = /^([1-9][0-9]*)\/([1-9][0-9]*)\/([1-9][0-9]*)$/.exec(options.planReference);
+	if (!reference) throw new Error("Expected reviewed run/attempt/generation");
+	const source = `${base(options)}/${reference[1]}/${reference[2]}/saved-plan/plan.tfplan#${reference[3]}`;
+	const paths = privatePaths(options, "apply");
+	try {
+		await execute("gcloud", [
+			"storage",
+			"cp",
+			source,
+			paths.planFile,
+			"--quiet"
+		], {
+			logFile: paths.logFile,
+			signal: options.signal
+		});
+		requirePlan(paths.planFile);
+		await action({
+			...paths,
+			signal: options.signal
+		});
+	} catch (error) {
+		await failureLog(execute, paths.logFile, `${base(options)}/apply/${options.runId}/${options.attempt}/apply.log`);
+		throw error;
+	} finally {
+		rmSync(paths.directory, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+export { CommandFailure, apply, plan, processRunner };

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@quantile-co/factory-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Private saved-plan transport for repository-owned deployment commands.",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quantile-co/factory.git",
+    "directory": "packages/github"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --maxWorkers=4"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.