gentle-pi 2.1.2 → 2.3.0

package/runtime/gentle-ai-binary.mjs

@@ -1,6 +1,7 @@
-// Generated by scripts/build-git-commit-transaction-runner.mjs. Do not edit.
+// Generated by scripts/build-runtime-modules.mjs. Do not edit.
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import {
 	GENTLE_AI_INSTALL_METHOD,
@@ -8,6 +9,7 @@ import {
 	GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,
 	GENTLE_AI_WINDOWS_SOURCE_PACKAGE_PATH,
 	GENTLE_AI_WINDOWS_SOURCE_TAG,
+	INSTALLER_VERSION,
 	isGentleAiWindowsGoVersionSupported,
 	isWindowsGoSumdbSourceTarget,
 	resolveGentleAiReleaseAsset,
@@ -15,7 +17,10 @@ import {
 import { fileURLToPath } from "node:url";
 
 export const GENTLE_AI_BINARY_MISSING_CODE = "package-local-binary-missing";
-export const GENTLE_AI_VERSION = "2.2.2";
+// Derived from the one authoritative pinned version in
+// scripts/gentle-ai-installer.mjs rather than repeating the literal here, so
+// the two can never independently drift apart the way they once did.
+export const GENTLE_AI_VERSION = INSTALLER_VERSION;
 
 export class PackageLocalGentleAiBinaryMissingError extends Error {
 	         code = GENTLE_AI_BINARY_MISSING_CODE;
@@ -43,6 +48,165 @@ function sha256(value        )         {
 	return createHash("sha256").update(value).digest("hex");
 }
 
+// ---------------------------------------------------------------------------
+// Dev-binary override — the maintainer field-test lane.
+//
+// Two explicit activation paths, in precedence order:
+//   1. GENTLE_PI_GENTLE_AI_DEV_BINARY (session override, absolute path), then
+//   2. the persistent registration file at
+//      <GENTLE_PI_CONFIG_HOME|~/.pi/gentle-ai>/dev-binary.json with the strict
+//      shape {"schema":"gentle-pi.dev-binary/v1","path":"<absolute path>"}.
+//
+// The registration deliberately pins no digest: it is the unpinned field-test
+// mode, and the binary at that path changes on every rebuild. Every resolution
+// re-validates the file and recomputes the sha256, so a rebuilt binary is
+// followed automatically with a fresh digest and no re-registration.
+//
+// Guardrails per resolution: absolute path, regular non-symlink file, POSIX
+// executable. Any failure — including a malformed registration document or a
+// registered-but-missing binary — is a typed error naming its origin, never a
+// silent fallback to the pinned binary: silently running the pin while the
+// maintainer believes he is field-testing main is the worst possible outcome.
+// With neither activation path present, the pinned supply-chain resolution
+// below stays byte-identical.
+// ---------------------------------------------------------------------------
+
+export const GENTLE_AI_DEV_BINARY_ENV = "GENTLE_PI_GENTLE_AI_DEV_BINARY";
+export const GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA = "gentle-pi.dev-binary/v1";
+export const GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE = "dev-binary-override-invalid";
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export class GentleAiDevBinaryOverrideError extends Error {
+	         code = GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE;
+	         source                        ;
+	         origin        ;
+	constructor(source                        , origin        , reason        ) {
+		super(`${GENTLE_AI_DEV_BINARY_OVERRIDE_INVALID_CODE}: ${origin} ${reason}. Fix or remove the override; the pinned binary is never used silently while an override is declared.`);
+		this.name = "GentleAiDevBinaryOverrideError";
+		this.source = source;
+		this.origin = origin;
+	}
+}
+
+let devBinaryEnvironmentTestingOverlay                                          ;
+
+/** Testing-only environment overlay; production code never calls this. */
+export function setGentleAiDevBinaryEnvironmentForTesting(environment                                          )       {
+	devBinaryEnvironmentTestingOverlay = environment;
+}
+
+function ambientDevBinaryEnvironment()                               {
+	return devBinaryEnvironmentTestingOverlay ?? { env: process.env, home: homedir() };
+}
+
+export function gentleAiDevBinaryRegistrationPath(environment                               = ambientDevBinaryEnvironment())         {
+	const configHome = environment.env.GENTLE_PI_CONFIG_HOME ?? join(environment.home, ".pi", "gentle-ai");
+	return join(configHome, "dev-binary.json");
+}
+
+function validateDevBinary(source                        , origin        , path        , platform        )                            {
+	if (typeof path !== "string" || path.length === 0) throw new GentleAiDevBinaryOverrideError(source, origin, "declares an empty dev binary path");
+	if (!isAbsolute(path)) throw new GentleAiDevBinaryOverrideError(source, origin, `must name an absolute path, received "${path}"`);
+	let details                              ;
+	try {
+		details = lstatSync(path);
+	} catch {
+		throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which does not exist`);
+	}
+	if (!details.isFile() || details.isSymbolicLink()) throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which is not a regular non-symlink file`);
+	if (platform !== "win32" && (details.mode & 0o111) === 0) throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which is not a POSIX executable`);
+	let digest        ;
+	try {
+		digest = sha256(readFileSync(path));
+	} catch {
+		throw new GentleAiDevBinaryOverrideError(source, origin, `names "${path}", which could not be read`);
+	}
+	return { source, origin, path, sha256: digest };
+}
+
+function readDevBinaryRegistration(registrationPath        )         {
+	let contents        ;
+	try {
+		contents = readFileSync(registrationPath, "utf8");
+	} catch {
+		throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "could not be read");
+	}
+	let parsed         ;
+	try {
+		parsed = JSON.parse(contents);
+	} catch {
+		throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "is not valid JSON");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "must be a JSON object");
+	const record = parsed                           ;
+	const keys = Object.keys(record).sort();
+	if (keys.length !== 2 || keys[0] !== "path" || keys[1] !== "schema") throw new GentleAiDevBinaryOverrideError("registration", registrationPath, `must carry exactly the keys "schema" and "path"`);
+	if (record.schema !== GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, `must declare schema ${GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA}`);
+	if (typeof record.path !== "string" || record.path.length === 0) throw new GentleAiDevBinaryOverrideError("registration", registrationPath, "must declare a non-empty string path");
+	return record.path;
+}
+
+/**
+ * Resolves the active dev-binary override, if any. Returns undefined only when
+ * neither activation path is present; a present-but-invalid override always
+ * throws a typed GentleAiDevBinaryOverrideError naming its origin.
+ */
+export function resolveGentleAiDevBinaryOverride(
+	environment                               = ambientDevBinaryEnvironment(),
+	platform = process.platform,
+)                                        {
+	const envValue = environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	if (envValue !== undefined && envValue.length > 0) return validateDevBinary("env", GENTLE_AI_DEV_BINARY_ENV, envValue, platform);
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	if (!existsSync(registrationPath)) return undefined;
+	return validateDevBinary("registration", registrationPath, readDevBinaryRegistration(registrationPath), platform);
+}
+
+/**
+ * Cheap presence probe: is a dev-binary override declared at all? Used by the
+ * native CLI to select the unpinned version gate without hashing the binary.
+ * Declared-but-invalid still counts as configured — the resolution path will
+ * fail loudly with the typed error instead of quietly using the pin.
+ */
+export function gentleAiDevBinaryOverrideConfigured(environment                               = ambientDevBinaryEnvironment())          {
+	const envValue = environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	if (envValue !== undefined && envValue.length > 0) return true;
+	return existsSync(gentleAiDevBinaryRegistrationPath(environment));
+}
+
+/** Validates and persistently registers a dev binary; returns the fresh override. */
+export function registerGentleAiDevBinary(
+	path        ,
+	environment                               = ambientDevBinaryEnvironment(),
+	platform = process.platform,
+)                                                                    {
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	const validated = validateDevBinary("registration", registrationPath, path, platform);
+	mkdirSync(dirname(registrationPath), { recursive: true });
+	writeFileSync(registrationPath, `${JSON.stringify({ schema: GENTLE_AI_DEV_BINARY_REGISTRATION_SCHEMA, path })}\n`);
+	return { registrationPath, override: validated };
+}
+
+/** Deletes the persistent registration; returns whether one existed. */
+export function unregisterGentleAiDevBinary(environment                               = ambientDevBinaryEnvironment())          {
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	if (!existsSync(registrationPath)) return false;
+	rmSync(registrationPath);
+	return true;
+}
+
 function isConfined(path        , directory        )          {
 	const relativePath = relative(directory, path);
 	return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
@@ -107,7 +271,14 @@ export function resolveGentleAiBinary(
 	packageRoot = dirname(dirname(fileURLToPath(import.meta.url))),
 	platform = process.platform,
 	readBinary                           = readFileSync,
+	environment                               = ambientDevBinaryEnvironment(),
 )         {
+	// The explicit dev-binary override wins over the pinned supply-chain path.
+	// Its typed errors propagate: a declared override never falls back to the
+	// pin. Without a declared override this call returns undefined and the
+	// pinned resolution below is byte-identical to the pre-override behavior.
+	const override = resolveGentleAiDevBinaryOverride(environment, platform);
+	if (override !== undefined) return override.path;
 	const binaryPath = gentleAiBinaryPath(packageRoot, platform);
 	const versionDirectory = dirname(binaryPath);
 	const manifestPath = join(versionDirectory, "integrity.json");