gentle-pi 3.7.0 → 4.1.0

package/scripts/main-channel.mjs

@@ -0,0 +1,452 @@
+// Main channel: Gentle Shell and Gentle AI built from the latest `main` commits.
+//
+// Neither repository publishes main builds, so both are produced locally from
+// an exact commit SHA resolved at install or upgrade time:
+//   - Gentle AI: `go install <module>@<sha>` in a sealed Go environment, so the
+//     module source is verified by Go's checksum database (sum.golang.org), as
+//     the Windows release build already is. The binary must report a version
+//     naming that commit, then it is activated through the existing dev-binary
+//     override, which never falls back to the pinned binary silently.
+//   - Gentle Shell: the exact commit's source tarball, versioned
+//     `<version>-main.<sha12>` and packed without `prepack` (which runs the full
+//     test suite), then installed globally like any local tarball.
+// The recorded channel lets `gentle-shell upgrade` follow release or main.
+import { dirname, isAbsolute, join, posix, relative, win32 } from "node:path";
+import { gentleAiDevBinaryRegistrationPath, registerGentleAiDevBinary, unregisterGentleAiDevBinary } from "../runtime/gentle-ai-binary.mjs";
+import { acquireGo as acquirePinnedGo, installedGo } from "./installer-downloads.mjs";
+import { goAcquisition, pnpmGlobalBin, requirements } from "./installer-preflight.mjs";
+
+export const SHELL_REPOSITORY = "Gentleman-Programming/gentle-shell";
+export const GENTLE_AI_REPOSITORY = "Gentleman-Programming/gentle-ai";
+export const GENTLE_AI_MAIN_PACKAGE = "github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai";
+export const CHANNEL_SCHEMA = "gentle-shell.channel/v1";
+export const CHANNELS = Object.freeze(["release", "main"]);
+
+const SHA = /^[0-9a-f]{40}$/;
+const MINUTE = 60_000;
+const deadlines = Object.freeze({ build: 15 * MINUTE, version: 30_000, extract: 2 * MINUTE, pack: 5 * MINUTE });
+const MAX_SOURCE_BYTES = 100 * 1024 * 1024;
+
+export class MainChannelError extends Error {
+	constructor(code, message, cause) {
+		super(`${code}: ${message}`, cause === undefined ? undefined : { cause });
+		this.name = "MainChannelError";
+		this.code = code;
+	}
+}
+
+/** Same config home as the dev-binary override: GENTLE_PI_CONFIG_HOME or ~/.pi/gentle-ai. */
+export function configHome({ env, home }) {
+	return env.GENTLE_PI_CONFIG_HOME ?? join(home, ".pi", "gentle-ai");
+}
+export function channelStatePath(ctx) {
+	return join(configHome(ctx), "channel.json");
+}
+
+function validState(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value) || value.schema !== CHANNEL_SCHEMA) return null;
+	if (value.channel === "release" && Object.keys(value).length === 2) return { channel: "release" };
+	if (value.channel === "main" && Object.keys(value).length === 4 && SHA.test(value.shellCommit) && SHA.test(value.gentleAiCommit)) {
+		return { channel: "main", shellCommit: value.shellCommit, gentleAiCommit: value.gentleAiCommit };
+	}
+	return null;
+}
+
+/** The recorded channel; no record means release. A malformed record fails closed. */
+export async function readChannel(ctx, fs) {
+	let text;
+	try {
+		text = await fs.readFile(channelStatePath(ctx), "utf8");
+	} catch (error) {
+		if (error?.code === "ENOENT") return { channel: "release" };
+		throw new MainChannelError("channel-state-invalid", `${channelStatePath(ctx)} could not be read`);
+	}
+	let parsed = null;
+	try { parsed = validState(JSON.parse(text)); } catch { parsed = null; }
+	if (!parsed) throw new MainChannelError("channel-state-invalid", `${channelStatePath(ctx)} is not a valid ${CHANNEL_SCHEMA} record; fix or remove it`);
+	return parsed;
+}
+
+export async function writeChannel(ctx, state, fs) {
+	const record = { schema: CHANNEL_SCHEMA, ...state };
+	if (!validState(record)) throw new MainChannelError("channel-state-invalid", "refusing to record an invalid channel state");
+	const path = channelStatePath(ctx);
+	await fs.mkdir(dirname(path), { recursive: true });
+	await fs.writeFile(`${path}.tmp`, `${JSON.stringify(record)}\n`);
+	await fs.rename(`${path}.tmp`, path);
+}
+
+/** Latest commit of `main` as an exact SHA (GitHub's raw-SHA media type). */
+export async function resolveMainCommit(repository, { fetch }) {
+	let response;
+	try {
+		response = await fetch(`https://api.github.com/repos/${repository}/commits/main`, {
+			headers: { Accept: "application/vnd.github.sha", "User-Agent": "gentle-shell" },
+		});
+	} catch {
+		throw new MainChannelError("main-commit-unavailable", `the latest main commit of ${repository} could not be fetched`);
+	}
+	const sha = response?.ok ? String(await response.text()).trim() : "";
+	if (!SHA.test(sha)) {
+		throw new MainChannelError("main-commit-unavailable", `GitHub did not return the latest main commit of ${repository} (HTTP ${response?.status ?? "error"})`);
+	}
+	return sha;
+}
+
+export function mainVersion(baseVersion, commit) {
+	return `${baseVersion}-main.${commit.slice(0, 12)}`;
+}
+
+function succeeded(result) {
+	return result?.code === 0 && result.timedOut !== true && result.signal == null;
+}
+
+/** The failed command's bounded stderr tail as an error cause, or undefined when it printed nothing. */
+function stderrCause(result) {
+	const tail = typeof result?.stderrTail === "string" ? result.stderrTail.trim() : "";
+	return tail.length > 0 ? new Error(tail) : undefined;
+}
+
+/** On Windows, System32's bsdtar by absolute path: an MSYS tar earlier on PATH (Git for
+ * Windows' usr\bin) reads a drive-letter archive path such as `D:\...` as a remote host. */
+function tarCommand(platform) {
+	return platform === "win32" ? win32.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe") : "tar";
+}
+
+function sealedGoEnvironment(goPath, buildDirectory, platform) {
+	const temporary = join(buildDirectory, "tmp");
+	const base = {
+		// -modcacherw: Go makes its module cache read-only, which would stop its removal.
+		GOENV: "off", GOFLAGS: "-modcacherw", GOWORK: "off", GOTOOLCHAIN: "local", GOSUMDB: "sum.golang.org",
+		GONOSUMDB: "", GOPRIVATE: "", GONOPROXY: "", GOINSECURE: "", GOPROXY: "https://proxy.golang.org", CGO_ENABLED: "0",
+		GOBIN: join(buildDirectory, "gobin"), GOPATH: join(buildDirectory, "gopath"),
+		GOMODCACHE: join(buildDirectory, "gomodcache"), GOCACHE: join(buildDirectory, "gocache"),
+	};
+	if (platform === "win32") {
+		const root = process.env.SystemRoot ?? "C:\\Windows";
+		return { ...base, SystemRoot: root, TEMP: temporary, TMP: temporary, PATH: [dirname(goPath), join(root, "System32"), root].join(";") };
+	}
+	return { ...base, HOME: buildDirectory, TMPDIR: temporary, PATH: [dirname(goPath), "/usr/bin", "/bin"].join(":") };
+}
+
+/** Builds Gentle AI from `commit`, verifies the binary names it and registers it as the override. */
+export async function buildMainGentleAi({ commit, ctx, platform, goPath, run, fs }) {
+	if (!SHA.test(commit)) throw new MainChannelError("main-gentle-ai-unverified", "the Gentle AI commit is not an exact SHA");
+	const executable = platform === "win32" ? "gentle-ai.exe" : "gentle-ai";
+	const directory = join(configHome(ctx), "main", "gentle-ai", commit);
+	const buildDirectory = join(configHome(ctx), "main", ".build");
+	await fs.rm(buildDirectory, { recursive: true, force: true });
+	const env = sealedGoEnvironment(goPath, buildDirectory, platform);
+	for (const path of [env.GOBIN, env.GOPATH, env.GOMODCACHE, env.GOCACHE, join(buildDirectory, "tmp")]) await fs.mkdir(path, { recursive: true });
+	try {
+		const install = await run(goPath, ["install", `${GENTLE_AI_MAIN_PACKAGE}@${commit}`], { env, cwd: buildDirectory, deadlineMs: deadlines.build, stderrTail: 4096 });
+		if (!succeeded(install)) throw new MainChannelError("main-gentle-ai-build-failed", `go install ${GENTLE_AI_MAIN_PACKAGE}@${commit} failed`, stderrCause(install));
+		await fs.mkdir(directory, { recursive: true });
+		const binaryPath = join(directory, executable);
+		await fs.copyFile(join(env.GOBIN, executable), binaryPath);
+		if (platform !== "win32") await fs.chmod(binaryPath, 0o755);
+		// Go stamps the module pseudo-version, whose suffix is the commit's first 12 characters.
+		const probe = await run(binaryPath, ["version"], { env: { PATH: env.PATH }, deadlineMs: deadlines.version });
+		const match = succeeded(probe) && /^gentle-ai (\S+)$/m.exec(String(probe.stdout ?? ""));
+		if (!match || !match[1].endsWith(`-${commit.slice(0, 12)}`)) {
+			await fs.rm(directory, { recursive: true, force: true });
+			throw new MainChannelError("main-gentle-ai-unverified", `the built Gentle AI does not report commit ${commit.slice(0, 12)}`);
+		}
+		registerGentleAiDevBinary(binaryPath, ctx, platform);
+		return { binaryPath, version: match[1] };
+	} finally {
+		await fs.rm(buildDirectory, { recursive: true, force: true });
+	}
+}
+
+/** Packs Gentle Shell from `commit` as `<version>-main.<sha12>` without running `prepack`. */
+export async function packMainShell({ commit, ctx, fetch, run, pnpm, fs, platform = process.platform }) {
+	if (!SHA.test(commit)) throw new MainChannelError("main-shell-pack-failed", "the Gentle Shell commit is not an exact SHA");
+	const packages = join(configHome(ctx), "main", "packages");
+	const work = join(configHome(ctx), "main", ".source");
+	await fs.rm(work, { recursive: true, force: true });
+	await fs.mkdir(join(work, "src"), { recursive: true });
+	await fs.mkdir(packages, { recursive: true });
+	try {
+		let response;
+		try {
+			response = await fetch(`https://codeload.github.com/${SHELL_REPOSITORY}/tar.gz/${commit}`, { headers: { "User-Agent": "gentle-shell" } });
+		} catch {
+			response = null;
+		}
+		const bytes = response?.ok ? Buffer.from(await response.arrayBuffer()) : null;
+		if (!bytes || bytes.length === 0 || bytes.length > MAX_SOURCE_BYTES) {
+			throw new MainChannelError("main-shell-download-failed", `the Gentle Shell source for ${commit.slice(0, 12)} could not be downloaded`);
+		}
+		const archive = join(work, "source.tgz");
+		await fs.writeFile(archive, bytes);
+		const source = join(work, "src");
+		const extract = await run(tarCommand(platform), ["-xzf", archive, "-C", source, "--strip-components=1"], { deadlineMs: deadlines.extract, stderrTail: 4096 });
+		if (!succeeded(extract)) {
+			throw new MainChannelError("main-shell-pack-failed", "the Gentle Shell source archive could not be extracted", stderrCause(extract));
+		}
+		const manifestPath = join(source, "package.json");
+		const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+		if (manifest?.name !== "gentle-pi" || typeof manifest.version !== "string") {
+			throw new MainChannelError("main-shell-pack-failed", "the downloaded source is not the gentle-pi package");
+		}
+		manifest.version = mainVersion(manifest.version, commit);
+		// prepack runs the full test suite; postinstall (the native binary) stays.
+		if (manifest.scripts) {
+			delete manifest.scripts.prepack;
+			delete manifest.scripts.prepare;
+		}
+		await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, "\t")}\n`);
+		const pack = await run(pnpm.command, [...pnpm.prefix, "pack", "--pack-destination", packages], { cwd: source, deadlineMs: deadlines.pack });
+		const tgz = join(packages, `gentle-pi-${manifest.version}.tgz`);
+		if (!succeeded(pack) || !(await fs.stat(tgz).then((info) => info.isFile(), () => false))) {
+			throw new MainChannelError("main-shell-pack-failed", "the Gentle Shell main package could not be packed");
+		}
+		return tgz;
+	} finally {
+		await fs.rm(work, { recursive: true, force: true });
+	}
+}
+
+/** The installer runner's main-channel adapter over real network and files. */
+export function mainChannelAdapter({ fetch = globalThis.fetch, fs }) {
+	return {
+		resolveCommit: (repository) => resolveMainCommit(repository, { fetch }),
+		buildGentleAi: ({ commit, goPath, platform, ctx, run }) => buildMainGentleAi({ commit, ctx, platform, goPath, run, fs }),
+		packShell: ({ commit, ctx, run, pnpm, platform }) => packMainShell({ commit, ctx, fetch, run, pnpm, fs, platform }),
+		writeChannel: (ctx, state) => writeChannel(ctx, state, fs),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// `gentle-shell upgrade [--channel release|main]`
+// ---------------------------------------------------------------------------
+
+const STABLE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const UPGRADE_USAGE = "usage: gentle-shell upgrade [--channel release|main]";
+const INSTALL_DEADLINE = 20 * MINUTE;
+
+function parseUpgradeArgs(args) {
+	if (args.length === 0) return null;
+	let value;
+	if (args.length === 1 && args[0].startsWith("--channel=")) value = args[0].slice("--channel=".length);
+	else if (args.length === 2 && args[0] === "--channel") value = args[1];
+	if (!CHANNELS.includes(value)) throw new MainChannelError("upgrade-usage", UPGRADE_USAGE);
+	return value;
+}
+
+function older(left, right) {
+	const [a, b] = [STABLE.exec(left), STABLE.exec(right)];
+	if (!a || !b) return true;
+	for (let index = 1; index <= 3; index += 1) {
+		if (Number(a[index]) !== Number(b[index])) return Number(a[index]) < Number(b[index]);
+	}
+	return false;
+}
+
+function inside(parent, child) {
+	const path = relative(parent, child);
+	return path !== "" && !path.startsWith("..") && !isAbsolute(path);
+}
+
+/** The latest stable gentle-pi release on the npm registry. */
+export async function latestRelease(fetch) {
+	let version = null;
+	try {
+		const response = await fetch("https://registry.npmjs.org/gentle-pi/latest", { headers: { Accept: "application/json" } });
+		if (response?.ok) version = (await response.json())?.version;
+	} catch {
+		version = null;
+	}
+	if (typeof version !== "string" || !STABLE.test(version)) {
+		throw new MainChannelError("latest-release-unavailable", "the latest gentle-pi release could not be read from the npm registry");
+	}
+	return version;
+}
+
+/**
+ * Which package manager owns an installed package (gentle-pi unless `name` says
+ * otherwise), from real (symlink-free) paths: pnpm when it lives under PNPM_HOME,
+ * npm only when it is `<npm root -g>/<name>` itself, otherwise null — for example
+ * an `npm link` of a source checkout, which must never be reinstalled over.
+ * Paths follow `platform` (this host by default): case-insensitive on Windows.
+ */
+export function installOwner({ packageRoot, pnpmHome, npmRoot, name = "gentle-pi", platform = process.platform }) {
+	const path = platform === "win32" ? win32 : posix;
+	const comparable = (value) => (platform === "win32" ? value.toLowerCase() : value);
+	if (typeof packageRoot !== "string") return null;
+	if (typeof pnpmHome === "string") {
+		const rest = path.relative(pnpmHome, packageRoot);
+		if (rest !== "" && !rest.startsWith("..") && !path.isAbsolute(rest)) return "pnpm";
+	}
+	if (typeof npmRoot === "string" && comparable(path.relative(npmRoot, packageRoot)) === comparable(path.normalize(name))) return "npm";
+	return null;
+}
+
+/** How a package manager runs, as { command, prefix }: what the host's
+ * `invocation(name)` adapter returns when it has one (on Windows, node.exe and
+ * the manager's JS entry, or a native .exe), otherwise the command `which` finds,
+ * with no prefix. A Windows .cmd or .bat cannot run with shell:false, so it
+ * counts as missing. Null when it is missing.
+ */
+async function invocationOf(name, { which, invocation }, platform) {
+	const found = invocation ? await invocation(name) : await which(name).then((command) => (command ? { command, prefix: [] } : null));
+	if (!found || (platform === "win32" && /\.(?:cmd|bat)$/i.test(found.command))) return null;
+	return found;
+}
+
+async function npmGlobalRoot(npm, run, fs) {
+	if (!npm) return null;
+	const result = await run(npm.command, [...npm.prefix, "root", "-g"], { deadlineMs: deadlines.version });
+	const reported = succeeded(result) ? String(result.stdout ?? "").trim().split(/\r?\n/).at(-1) : "";
+	return isAbsolute(reported) ? fs.realpath(reported).catch(() => null) : null;
+}
+
+const OWNER_ADVICE = Object.freeze({ upgrade: "update it the way you installed it", uninstall: "remove it the way you installed it" });
+
+/**
+ * The package manager that owns this installation, as { name, command, prefix },
+ * or a typed refusal whose code names the `command` that asked (`upgrade` or
+ * `uninstall`). adapters: { fs, run, which, invocation? }, as runUpgrade takes them.
+ */
+export async function ownerManager({ ctx, platform, packageRoot, adapters, command: purpose = "upgrade" }) {
+	const { fs, run } = adapters;
+	const bin = pnpmGlobalBin({ platform, env: { HOME: ctx.home, ...ctx.env } });
+	const npm = await invocationOf("npm", adapters, platform);
+	const [pnpmHome, root, npmRoot] = await Promise.all([
+		bin ? fs.realpath(bin.pnpmHome).catch(() => null) : null,
+		fs.realpath(packageRoot).catch(() => null),
+		npmGlobalRoot(npm, run, fs),
+	]);
+	const name = installOwner({ packageRoot: root, pnpmHome, npmRoot, platform });
+	if (!name) {
+		throw new MainChannelError(`${purpose}-owner-unknown`, `neither pnpm nor npm owns ${root ?? packageRoot} (a linked source checkout, for example); ${OWNER_ADVICE[purpose]}`);
+	}
+	const manager = name === "npm" ? npm : await invocationOf("pnpm", adapters, platform);
+	if (!manager) {
+		throw new MainChannelError(`${purpose}-manager-missing`, `${name}, which owns this Gentle Shell installation, is not on PATH as a command this ${purpose} can run`);
+	}
+	return { name, ...manager };
+}
+
+async function installGlobal(manager, spec, run) {
+	const argv = manager.name === "pnpm" ? ["add", "-g", spec, "--allow-build=gentle-pi"] : ["install", "-g", spec];
+	if (!succeeded(await run(manager.command, [...manager.prefix, ...argv], { deadlineMs: INSTALL_DEADLINE }))) {
+		throw new MainChannelError("upgrade-install-failed", `${manager.name} could not install ${spec}`);
+	}
+}
+
+const REMOVE_GLOBAL = Object.freeze({ pnpm: Object.freeze(["remove", "-g", "gentle-pi"]), npm: Object.freeze(["uninstall", "-g", "gentle-pi"]) });
+
+/** The command that removes the global gentle-pi with `name` (pnpm or npm), as a user types it. */
+export function removeGlobalCommand(name) {
+	return `${name} ${REMOVE_GLOBAL[name].join(" ")}`;
+}
+
+/** Removes the global gentle-pi with the manager ownerManager resolved (its
+ * verified invocation); true when it succeeded. Nothing else is removed.
+ */
+export async function removeGlobalShell(manager, run) {
+	return succeeded(await run(manager.command, [...manager.prefix, ...REMOVE_GLOBAL[manager.name]], { deadlineMs: INSTALL_DEADLINE }));
+}
+
+/** Removes the dev-binary override only when it points at a main build this module made. */
+async function removeMainOverride(ctx, fs) {
+	try {
+		const registration = JSON.parse(await fs.readFile(gentleAiDevBinaryRegistrationPath(ctx), "utf8"));
+		if (typeof registration?.path === "string" && inside(join(configHome(ctx), "main", "gentle-ai"), registration.path)) {
+			unregisterGentleAiDevBinary(ctx);
+		}
+	} catch {
+		// No registration, or one that is not ours: leave it alone.
+	}
+}
+
+/** The Go a main build runs: the user's, only when it reports a stable version
+ * that meets requirements.go; otherwise the pinned Go the installer published
+ * under the config home (`tools/go`), downloaded and verified there by
+ * `acquire` when it is not published yet. A missing, older or unchecked Go is
+ * never run for the build, and the user's Go is never changed.
+ */
+async function mainGo({ userGo, pinnedGo, acquire, run }) {
+	if (userGo) {
+		const result = await run(userGo, ["version"], { deadlineMs: deadlines.version });
+		const match = succeeded(result) && /^go version go(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\.(0|[1-9]\d*))? \S+$/.exec(String(result.stdout ?? "").trim());
+		if (match && !older(`${match[1]}.${match[2]}.${match[3] ?? "0"}`, requirements.go)) return userGo;
+	}
+	if (pinnedGo) return pinnedGo;
+	try {
+		const { goPath } = await acquire();
+		return goPath;
+	} catch (error) {
+		// acquireGo wraps every failure; its cause names what went wrong (download, checksum, destination).
+		const reason = [error, error?.cause].filter((item) => item instanceof Error).map((item) => item.message).join(": ") || String(error);
+		throw new MainChannelError("main-requires-tools", `the main channel builds Gentle AI with Go ${requirements.go} or newer, and getting the pinned ` +
+			`Go ${goAcquisition.version} failed (${reason}); nothing was built, fix the cause, then run gentle-shell upgrade again`);
+	}
+}
+
+/**
+ * Updates Gentle Shell along its recorded channel (or the one `--channel` selects):
+ * release goes to the latest npm release, main to the latest `main` commits of
+ * Gentle Shell and Gentle AI, rebuilding only what moved. Returns the exit code;
+ * failures throw MainChannelError (`upgrade-usage` is a usage error).
+ * adapters: { fetch, run, fs, which, invocation?, migrate? }; npm and pnpm run as
+ * invocationOf resolves them (Windows hosts pass `invocation`). On release,
+ * `migrate({ latest, owner })` (S4) may move this installation to the bundled
+ * one first: null (no migration, or one that failed and left this package
+ * untouched) keeps the path below for this run, otherwise { code, installed }.
+ * `owner` is called only when a migration can happen.
+ */
+export async function runUpgrade({ args, ctx, platform, arch = process.arch, packageRoot, currentVersion, adapters, out }) {
+	const { fetch, run, fs, which } = adapters;
+	const requested = parseUpgradeArgs(args);
+	const state = await readChannel(ctx, fs);
+	const channel = requested ?? state.channel;
+	if (channel === "release") {
+		const latest = await latestRelease(fetch);
+		const migrated = adapters.migrate ? await adapters.migrate({ latest, owner: () => ownerManager({ ctx, platform, packageRoot, adapters }) }) : null;
+		if (migrated) {
+			// The old package may stay: it follows the release channel, without a main override.
+			if (migrated.installed) {
+				await removeMainOverride(ctx, fs);
+				await writeChannel(ctx, { channel: "release" }, fs);
+			}
+			return migrated.code;
+		}
+		if (state.channel === "release" && !older(currentVersion, latest)) {
+			out(`gentle-shell ${currentVersion} is already the latest release.`);
+			return 0;
+		}
+		await installGlobal(await ownerManager({ ctx, platform, packageRoot, adapters }), `gentle-pi@${latest}`, run);
+		await removeMainOverride(ctx, fs);
+		await writeChannel(ctx, { channel: "release" }, fs);
+		out(`Updated gentle-shell ${currentVersion} to ${latest} (release).`);
+		return 0;
+	}
+	const [userGo, pnpm] = [await which("go"), await invocationOf("pnpm", adapters, platform)];
+	const pinnedGo = installedGo(join(configHome(ctx), "tools", "go"), platform, arch);
+	if (!pnpm) {
+		throw new MainChannelError("main-requires-tools", "the main channel packs Gentle Shell with pnpm; put it on PATH (Gentle AI is built with your Go, or with a pinned Go downloaded for the build)");
+	}
+	const acquire = adapters.acquireGo ?? (() => acquirePinnedGo({ root: join(configHome(ctx), "tools", "go"), platform, arch }));
+	const gentleAiCommit = await resolveMainCommit(GENTLE_AI_REPOSITORY, { fetch });
+	const shellCommit = await resolveMainCommit(SHELL_REPOSITORY, { fetch });
+	const onMain = state.channel === "main";
+	const aiCurrent = onMain && state.gentleAiCommit === gentleAiCommit;
+	const shellCurrent = onMain && state.shellCommit === shellCommit && currentVersion.endsWith(`-main.${shellCommit.slice(0, 12)}`);
+	const summary = `Gentle Shell ${shellCommit.slice(0, 12)}, Gentle AI ${gentleAiCommit.slice(0, 12)}`;
+	if (aiCurrent && shellCurrent) {
+		out(`gentle-shell is already at the latest main: ${summary}.`);
+		return 0;
+	}
+	if (!aiCurrent) await buildMainGentleAi({ commit: gentleAiCommit, ctx, platform, goPath: await mainGo({ userGo, pinnedGo, acquire, run }), run, fs });
+	if (!shellCurrent) {
+		const manager = await ownerManager({ ctx, platform, packageRoot, adapters });
+		const tgz = await packMainShell({ commit: shellCommit, ctx, fetch, run, pnpm, fs, platform });
+		await installGlobal(manager, tgz, run);
+	}
+	await writeChannel(ctx, { channel: "main", shellCommit, gentleAiCommit }, fs);
+	out(`Updated to the latest main: ${summary}.`);
+	return 0;
+}

package/scripts/mirror-odd-routing.mjs

@@ -38,8 +38,8 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/gentleman-programming/gentle-ai/v3/internal/components/agentguidance"
-	"github.com/gentleman-programming/gentle-ai/v3/internal/model"
+	"github.com/gentleman-programming/gentle-ai/v4/internal/components/agentguidance"
+	"github.com/gentleman-programming/gentle-ai/v4/internal/model"
 )
 
 func main() {

package/scripts/npm-pack-result.mjs

@@ -0,0 +1,31 @@
+// npm <=11 emits an array; npm 12 emits a map keyed by package name.
+// Both consumers pack exactly one package. Never reinterpret npm error objects.
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isNonemptyString = (value) => typeof value === "string" && value.trim().length > 0;
+
+export function normalizeNpmPackResult(value) {
+	let entries;
+	if (Array.isArray(value)) {
+		entries = value;
+	} else if (isRecord(value)) {
+		const pairs = Object.entries(value);
+		if (!pairs.every(([name, entry]) => isRecord(entry) && entry.name === name)) {
+			throw new Error("npm pack returned a malformed named package map");
+		}
+		entries = pairs.map(([, entry]) => entry);
+	} else {
+		throw new Error("npm pack returned neither a package array nor a named package map");
+	}
+	if (entries.length !== 1) throw new Error("npm pack did not return exactly one package");
+	const entry = entries[0];
+	if (!isRecord(entry) || !isNonemptyString(entry.name) || !isNonemptyString(entry.filename)
+		|| !Array.isArray(entry.files) || entry.files.length === 0
+		|| !entry.files.every((file) => isRecord(file) && isNonemptyString(file.path))) {
+		throw new Error("npm pack returned malformed package metadata");
+	}
+	return [entry];
+}
+
+export function parseNpmPackResult(output) {
+	return normalizeNpmPackResult(JSON.parse(output));
+}