gentle-pi 4.0.0 → 4.2.0

package/lib/gentle-shell-launcher.ts

@@ -1,10 +1,11 @@
-import { join, resolve as resolvePath } from "node:path";
+import { isAbsolute, join, resolve as resolvePath } from "node:path";
+import { CHILD_PACKAGE_INJECTION_ENV, encodeChildPackageInjection, type ChildPackageInjection } from "./child-package-injection.ts";
 
 // The gentle-shell launcher: pure, side-effect-free functions over injected
 // env/fs/exec. `bin/gentle-shell.mjs` (T2) wires these into the real process,
 // filesystem and child process so this module stays fully unit-testable.
 
-export type LauncherCommand = "home" | "setup";
+export type LauncherCommand = "home" | "setup" | "upgrade" | "self-uninstall";
 
 // pi's own package-management subcommands (see pi's cli/args.ts printHelp
 // "Commands" list): each is dispatched by pi itself, before pi's own flag
@@ -35,11 +36,12 @@ export interface ParsedLauncherArgs {
 	error?: string;
 }
 
-// Home-subcommand parsing is deliberately shallow: `home` only counts as the
-// subcommand when it is argv[0], and everything after it is handed over
+// Home-, upgrade- and self-uninstall-subcommand parsing is deliberately shallow:
+// each only counts as the subcommand when it is argv[0], and everything after it is handed over
 // untouched as commandArgs — T2 owns interpreting `home link|isolated|<path>`.
+// `self-uninstall` is not `uninstall`, which stays pi's own alias for `remove`.
 export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
-	if (argv[0] === "home") {
+	if (argv[0] === "home" || argv[0] === "upgrade" || argv[0] === "self-uninstall") {
 		return {
 			link: false,
 			isolated: false,
@@ -47,7 +49,7 @@ export function parseLauncherArgs(argv: string[]): ParsedLauncherArgs {
 			packageRoot: undefined,
 			help: false,
 			version: false,
-			command: "home",
+			command: argv[0],
 			commandArgs: argv.slice(1),
 			passthrough: [],
 			piSubcommand: undefined,
@@ -188,35 +190,36 @@ export interface ResolveHomeInput {
 	config: LauncherConfig | undefined;
 }
 
-// Pi Subagents resolves `PI_CODING_AGENT_DIR || ~/.pi/agent`; `--link` reuses
-// that exact home so gentle-shell never diverges from the user's own pi.
+// Pi Subagents resolves `PI_CODING_AGENT_DIR || ~/.pi/agent`; this is the
+// user's own pi home when no Gentle Shell session is involved.
 function linkDir(env: Record<string, string | undefined>, homedir: string): string {
 	return env.PI_CODING_AGENT_DIR || join(homedir, ".pi", "agent");
 }
 
 // The isolated home replaces PI_CODING_AGENT_DIR for the whole session, so the
 // user's own Pi home travels in this variable for read-only features such as
-// /gentle:stats. An inherited value wins: a gentle-shell launched from inside
-// a Gentle Shell session sees the outer isolated home as PI_CODING_AGENT_DIR.
+// /gentle:stats and for `--link`. An inherited value wins: a gentle-shell
+// launched from inside a Gentle Shell session sees the outer isolated home as
+// PI_CODING_AGENT_DIR, so `--link` must not re-select it (#2015).
 export const USER_PI_HOME_ENV = "GENTLE_SHELL_USER_PI_HOME";
 
 export function userPiHome(env: Record<string, string | undefined>, homedir: string): string {
 	return env[USER_PI_HOME_ENV] || linkDir(env, homedir);
 }
 
-function isolatedDir(env: Record<string, string | undefined>, homedir: string): string {
+export function isolatedDir(env: Record<string, string | undefined>, homedir: string): string {
 	return env.GENTLE_SHELL_HOME || join(homedir, ".gentle-shell", "agent");
 }
 
 export function resolveHome(input: ResolveHomeInput): ResolvedHome {
 	const { args, env, homedir, config } = input;
 
-	if (args.link) return { mode: "link", dir: linkDir(env, homedir), source: "flag" };
+	if (args.link) return { mode: "link", dir: userPiHome(env, homedir), source: "flag" };
 	if (args.isolated) return { mode: "isolated", dir: isolatedDir(env, homedir), source: "flag" };
 	if (args.home !== undefined) return { mode: "path", dir: args.home, source: "flag" };
 
 	if (config !== undefined) {
-		if (config.mode === "link") return { mode: "link", dir: linkDir(env, homedir), source: "config" };
+		if (config.mode === "link") return { mode: "link", dir: userPiHome(env, homedir), source: "config" };
 		if (config.mode === "isolated") return { mode: "isolated", dir: isolatedDir(env, homedir), source: "config" };
 		return { mode: "path", dir: config.dir, source: "config" };
 	}
@@ -389,7 +392,7 @@ export function missingPiMessage(): string {
 
 // --- pi version gate ---------------------------------------------------------
 
-export const MIN_PI_VERSION = "0.99.1";
+export const MIN_PI_VERSION = "1.2.0";
 
 export type PiVersionCheck = { ok: true; version: string } | { ok: false; message: string; version?: string };
 
@@ -878,6 +881,10 @@ export interface BuildPiInvocationInput {
 	baseEnv: Record<string, string | undefined>;
 	// The OS home behind userPiHome's conventional ~/.pi/agent fallback.
 	homedir: string;
+	// The directory pi is spawned in, which pi resolves a relative -e path
+	// against. bin/gentle-shell.mjs spawns pi without a cwd, so this is the
+	// launcher's own process.cwd().
+	cwd: string;
 }
 
 export interface PiInvocation {
@@ -919,8 +926,15 @@ export interface PiInvocation {
 //   - Not takeOver, with a declaration: no injection at all — the target
 //     settings already load a gentle-pi the launcher accepts as-is (the
 //     `--link` case with a pi-managed install matching this launcher).
+//
+// The two injecting cases also export CHILD_PACKAGE_INJECTION_ENV (#1690) so
+// the subagent runner can give delegated children the same package. It holds
+// only the launcher's own computed -e set; passthrough -e flags (the managed
+// herdr extension, or one the user typed) are not part of it. Every other case
+// removes an inherited value, so a nested launch never leaks a stale signal.
 export function buildPiInvocation(input: BuildPiInvocationInput): PiInvocation {
 	const args = [...input.runtime.args];
+	let childInjection: ChildPackageInjection | undefined;
 
 	if (input.piSubcommand !== undefined) {
 		// No injection at all: pi must see the bare subcommand as argv[0].
@@ -945,23 +959,36 @@ export function buildPiInvocation(input: BuildPiInvocationInput): PiInvocation {
 			injected.add(input.packageRoot);
 			args.push("-e", input.packageRoot);
 		}
-
+		// The argv dedupe above compares raw strings; the signal dedupes again
+		// after absolutizing, so a relative and an absolute spelling of the same
+		// file appear once, in first-occurrence order.
+		const signalPaths = new Set([...injected].map((path) => absoluteExtensionPath(path, input.cwd)));
+		childInjection = { noExtensions: true, extensionPaths: [...signalPaths] };
 	} else if (input.declaration === undefined) {
 		args.push("-e", input.packageRoot);
+		childInjection = { noExtensions: false, extensionPaths: [absoluteExtensionPath(input.packageRoot, input.cwd)] };
 	}
 
 	args.push(...input.passthrough);
 
-	return {
-		command: input.runtime.command,
-		args,
-		env: {
-			...input.baseEnv,
-			PI_CODING_AGENT_DIR: input.home.dir,
-			GENTLE_PI_AGENT_HOME: input.home.dir,
-			[USER_PI_HOME_ENV]: userPiHome(input.baseEnv, input.homedir),
-		},
+	const env: Record<string, string | undefined> = {
+		...input.baseEnv,
+		PI_CODING_AGENT_DIR: input.home.dir,
+		GENTLE_PI_AGENT_HOME: input.home.dir,
+		[USER_PI_HOME_ENV]: userPiHome(input.baseEnv, input.homedir),
 	};
+	if (childInjection === undefined) delete env[CHILD_PACKAGE_INJECTION_ENV];
+	else env[CHILD_PACKAGE_INJECTION_ENV] = encodeChildPackageInjection(childInjection);
+
+	return { command: input.runtime.command, args, env };
+}
+
+// pi resolves a relative -e path against its spawn cwd. Children may run
+// elsewhere, so the signal carries the same file as an absolute path. Loose
+// entries can be relative when the isolated or linked home comes from a
+// relative env value.
+function absoluteExtensionPath(path: string, cwd: string): string {
+	return isAbsolute(path) ? path : resolvePath(cwd, path);
 }
 
 // --- spawn planning ------------------------------------------------------------
@@ -1148,6 +1175,9 @@ export function helpText(): string {
 		"Usage: gentle-shell [options] [-- pi-args...]",
 		"       gentle-shell home [link|isolated|<path>]",
 		"       gentle-shell [home selectors] setup [--dry-run]",
+		"       gentle-shell upgrade [--channel release|main]",
+		"       gentle-shell upgrade --rollback",
+		"       gentle-shell self-uninstall [--dry-run] [--yes] [--include-shared]",
 		"",
 		"Opens pi with the Gentle Shell package loaded, without touching your",
 		"vanilla pi installation.",
@@ -1167,19 +1197,40 @@ export function helpText(): string {
 		"                   (runs the package-local gentle-ai 'install --agent pi --scope global').",
 		"                   Accepts --dry-run, forwarded to gentle-ai. Accepts a home selector",
 		"                   (--link, --isolated, --home <dir>) before it.",
+		"                   Warns if configured MCP servers remain disabled; never re-enables them.",
+		"  upgrade          Update Gentle Shell along its channel: the latest release, or the latest",
+		"                   main commits of Gentle Shell and Gentle AI (built locally; needs Go and",
+		"                   pnpm). --channel switches the channel first. A bundled install (the web",
+		"                   installer's own Node, pnpm and Pi) follows the release channel only:",
+		"                   it installs the new version beside the current one, verifies it, then",
+		"                   switches; --rollback switches back to the previous kept version.",
+		"  self-uninstall   Remove Gentle Shell: its own data, the isolated home and the gentle-pi",
+		"                   package. Shows the plan first and asks before removing (--yes skips",
+		"                   the question). The shared ~/.pi/gentle-ai configuration is kept unless",
+		"                   you accept or pass --include-shared; --dry-run only shows the plan.",
+		"                   Never touches your pi home or custom --home homes.",
 		"",
 		"Managing packages:",
 		"  gentle-shell install npm:<pkg>   Run pi's own 'install' against the resolved home.",
 		"  gentle-shell remove <source>     Run pi's own 'remove' against the resolved home.",
 		"  gentle-shell list                Run pi's own 'list' against the resolved home.",
 		"  gentle-shell update [target]     Run pi's own 'update' against the resolved home.",
+		"                                   In a bundled install Pi ships pinned: 'update' without a package",
+		"                                   runs 'gentle-shell upgrade' instead of updating Pi.",
 		"  gentle-shell config              Run pi's own 'config' against the resolved home.",
 		"  gentle-shell auth <command>      Run pi's own 'auth' against the resolved home.",
+		"  'gentle-shell uninstall <source>' is pi's own alias for 'remove'; to remove Gentle",
+		"  Shell itself, use 'gentle-shell self-uninstall'.",
 		"  These run pi's own commands, forwarded verbatim, against the --isolated home",
 		"  (or your own pi home with --link). Running 'gentle-shell install npm:gentle-pi'",
 		"  inside the isolated home is unnecessary: gentle-shell already loads the",
 		"  package itself.",
 		"",
+		"Bundled interactive startup:",
+		"  Before opening Pi, checks for a newer release (at most 1.5 seconds).",
+		"  Choose Update now to upgrade and reopen, Not now, or Skip this version.",
+		"  Offline, unavailable checks, commands and noninteractive runs open normally.",
+		"",
 		"Environment variables:",
 		"  GENTLE_SHELL_PI       Path to the pi executable to run.",
 		"  GENTLE_SHELL_HOME     Directory for the isolated home (default: ~/.gentle-shell/agent).",

package/lib/gentle-shell-startup-flow.ts

@@ -0,0 +1,54 @@
+import { realpathSync, readFileSync } from "node:fs";
+import { join, relative, isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Resolve through the switched version, never the old launcher's captured pins.
+export async function resolveStartupRelaunch(input: {
+	root: string; home: string; platform: NodeJS.Platform; env: NodeJS.ProcessEnv; argv: string[];
+}): Promise<{ command: string; args: string[]; env: NodeJS.ProcessEnv }> {
+	const { activeVersion, prefixLayout } = await import("../scripts/bundled-install.mjs");
+	const layout = prefixLayout(input);
+	const id = activeVersion(layout);
+	if (!id) throw new Error("No active Gentle Shell after upgrade");
+	const versions = realpathSync(layout.versions);
+	const version = realpathSync(join(versions, id));
+	const inside = (root: string, file: string) => {
+		const path = relative(root, file);
+		return path !== "" && !path.startsWith("..") && !isAbsolute(path);
+	};
+	if (!inside(versions, version) || readFileSync(join(version, ".gentle-shell-version"), "utf8") !== `${id}\n`) {
+		throw new Error("Invalid active Gentle Shell version");
+	}
+	const pkg = join(version, "node_modules", "gentle-pi");
+	const modulePath = realpathSync(join(pkg, "scripts", "bundled-install.mjs"));
+	const entry = realpathSync(join(pkg, "bin", "gentle-shell.mjs"));
+	if (!inside(version, modulePath) || !inside(version, entry)) throw new Error("Active launcher escaped its version");
+	const release = await import(pathToFileURL(modulePath).href);
+	const next = release.prefixLayout(input);
+	return { command: next.node, args: [entry, ...input.argv], env: { ...input.env, GENTLE_SHELL_SKIP_STARTUP_UPDATE: "1" } };
+}
+
+// Only an explicit update selection may cross the existing upgrade boundary.
+export async function applyStartupChoice(choice: "update" | "skip" | "omit" | "cancel", effects: {
+	omit: () => void;
+	upgrade: () => Promise<number>;
+	relaunch: () => Promise<number>;
+	warn?: (message: string) => void;
+}): Promise<number | undefined> {
+	if (choice === "cancel") return 130;
+	if (choice === "omit") {
+		try { effects.omit(); }
+		catch { effects.warn?.("Could not remember the skipped release; continuing without saving."); }
+	}
+	if (choice !== "update") return undefined;
+	if (await effects.upgrade() !== 0) return undefined;
+	// A failed relaunch must not fall through to the captured old packageRoot.
+	return effects.relaunch();
+}
+
+export function omitStartupVersion(read: () => string | undefined, write: (text: string) => void, version: string): void {
+	const text = read();
+	const config = text === undefined ? {} : JSON.parse(text);
+	if (config === null || typeof config !== "object" || Array.isArray(config)) throw new Error("Invalid launcher config");
+	write(`${JSON.stringify({ ...config, skippedStartupRelease: version }, null, 2)}\n`);
+}

package/lib/gentle-shell-startup-update.ts

@@ -0,0 +1,92 @@
+import type { ParsedLauncherArgs } from "./gentle-shell-launcher.ts";
+
+export interface StartupUpdateOffer {
+	current: string;
+	latest: string;
+	notesUrl: string;
+}
+
+export interface StartupUpdateCheckOptions {
+	args: ParsedLauncherArgs;
+	env: Record<string, string | undefined>;
+	bundled: boolean;
+	inputTTY: boolean;
+	outputTTY: boolean;
+}
+
+export interface StartupUpdateLookupOptions {
+	current: string;
+	skipped?: string;
+	lookup: (signal: AbortSignal) => Promise<string | undefined>;
+	timeoutMs?: number;
+}
+
+export function shouldCheckStartupUpdate({ args, env, bundled, inputTTY, outputTTY }: StartupUpdateCheckOptions): boolean {
+	if (!bundled || !inputTTY || !outputTTY || args.command || args.piSubcommand || args.error || args.help || args.version || args.packageRoot !== undefined) {
+		return false;
+	}
+	if (env.GENTLE_PI_AGENTS_CHILD || env.PI_OFFLINE || env.GENTLE_SHELL_SKIP_STARTUP_UPDATE) {
+		return false;
+	}
+
+	// An allowlist keeps new command modes from accidentally showing a prompt.
+	for (let i = 0; i < args.passthrough.length; i += 1) {
+		const token = args.passthrough[i];
+		if (token === "--continue" || token === "-c") continue;
+		if (token.startsWith("--resume=") && token.length > "--resume=".length) continue;
+		if (token === "--resume" || token === "-r") {
+			const next = args.passthrough[i + 1];
+			if (next !== undefined && !next.startsWith("-")) i += 1;
+			continue;
+		}
+		return false;
+	}
+	return true;
+}
+
+function stableParts(version: string): string[] | undefined {
+	// No leading zeros, prefixes, whitespace, prereleases or build metadata.
+	const match = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(version);
+	return match && match[0] === version ? match.slice(1) : undefined;
+}
+
+function isNewer(latest: string[], current: string[]): boolean {
+	for (let i = 0; i < 3; i += 1) {
+		if (latest[i] === current[i]) continue;
+		// Decimal string comparison avoids rounding even for arbitrarily large parts.
+		return latest[i].length !== current[i].length
+			? latest[i].length > current[i].length
+			: latest[i] > current[i];
+	}
+	return false;
+}
+
+export async function findStartupUpdate({ current, skipped, lookup, timeoutMs = 1500 }: StartupUpdateLookupOptions): Promise<StartupUpdateOffer | undefined> {
+	const currentParts = stableParts(current);
+	if (!currentParts) return undefined;
+	const controller = new AbortController();
+	const deadline = Number.isFinite(timeoutMs) && timeoutMs >= 0 && timeoutMs <= 2_147_483_647 ? timeoutMs : 1500;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		const timeout = new Promise<undefined>((resolve) => {
+			timer = setTimeout(() => {
+				resolve(undefined);
+				controller.abort();
+			}, deadline);
+		});
+		// The race bounds startup even if the injected lookup ignores cancellation.
+		const latest = await Promise.race([lookup(controller.signal), timeout]);
+		if (latest === undefined || latest === skipped) return undefined;
+		const latestParts = stableParts(latest);
+		if (!latestParts || !isNewer(latestParts, currentParts)) return undefined;
+		return {
+			current,
+			latest,
+			notesUrl: `https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v${latest}`,
+		};
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}