anon-pi 0.7.0 → 0.9.0

package/src/anon-pi.ts

@@ -30,7 +30,7 @@
 // init's proxy detect/verify decisions). cli.ts owns only the impure edges (fs,
 // the interactive TUI, the netcage query, the spawn).
 
-import {existsSync} from 'node:fs';
+import {existsSync, readFileSync} from 'node:fs';
 import {homedir} from 'node:os';
 import {dirname, join, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
@@ -433,7 +433,9 @@ export const ROOT_TOKEN = '.';
  * reserved-name concept is explicit and extendable. `--mount`'s `/work` is a
  * CONTAINER path, not a name in this namespace, so it needs no reservation.
  */
-export const RESERVED_NAMES: readonly string[] = ['.', '..'];
+export const RESERVED_NAMES: readonly string[] = ['.', '..', 'pi'];
+// NOTE: `pi` is reserved so the `anon-pi pi <args…>` passthrough token
+// (PI_PASSTHROUGH_TOKEN) can never be shadowed by a project named `pi`.
 
 /** What a name names, for a clear validation error. */
 export type NameKind = 'machine' | 'project';
@@ -523,6 +525,24 @@ export function resolveCwd(kind: RootKind, token: string): string {
 	return `${rootCwd(kind)}/${validateName(token, 'project')}`;
 }
 
+/**
+ * PURE: the launch cwd for a resolved (mode, rootKind, project). With a project
+ * token it resolves under the active root (resolveCwd). With NO project: a
+ * `shell` sits at the machine home (`/root`) — the "sit on the machine" mode —
+ * while `pi` (a `--session`/`--resume` launch that pi cwd-switches itself) starts
+ * at the projects root (`rootCwd`), a real pi launch position. `menu` never
+ * reaches here (it is argv-less). Shared by resolveRunPlan + keptContainerKey so
+ * the run cwd and the container-identity key always agree.
+ */
+export function launchCwd(
+	mode: LaunchMode,
+	kind: RootKind,
+	project: string | undefined,
+): string {
+	if (project !== undefined) return resolveCwd(kind, project);
+	return mode === 'shell' ? CONTAINER_HOME_ROOT : rootCwd(kind);
+}
+
 /** Parsed shape of config.json. All fields optional (a hand-edited file may omit any). */
 export interface AnonPiConfig {
 	/** socks5h proxy URL. */
@@ -586,14 +606,54 @@ function nonEmpty(v: string | undefined): string | undefined {
 	return v && v.trim() !== '' ? v.trim() : undefined;
 }
 
+/**
+ * PURE: expand a leading `~` / `~/` in a user-supplied HOST path to the given
+ * home (`node:path.resolve` does NOT do this — it would produce a literal `~`
+ * directory). Only a LEADING `~` (bare or before a separator) is expanded; a `~`
+ * elsewhere is left alone. Used everywhere anon-pi takes a host path from a
+ * human (the projects root, `--mount`), so `~/dev/x` means `$HOME/dev/x`.
+ */
+export function expandTilde(p: string, home: string): string {
+	if (p === '~') return home;
+	if (p.startsWith('~/') || p.startsWith('~\\')) {
+		return join(home, p.slice(2));
+	}
+	return p;
+}
+
+/**
+ * netcage's default podman graphroot (podman's global `--root`). Since netcage
+ * v0.7.0 (host-identity hardening, ADR-0013) EVERY netcage podman call runs
+ * against a private, username-free store at this path, NOT the operator's
+ * default rootless store. So an image anon-pi builds with a plain `podman build`
+ * lands in the WRONG store and `netcage run` cannot see it (it tries to pull the
+ * `localhost/…` ref and fails). anon-pi must place a built image into THIS store.
+ * Overridable via NETCAGE_GRAPHROOT (netcage's own test-seam env), so a caller
+ * that points netcage elsewhere stays in sync.
+ */
+export const NETCAGE_DEFAULT_GRAPHROOT = '/var/tmp/netcage-storage';
+
+/**
+ * PURE: resolve netcage's podman graphroot the same way netcage does: the
+ * NETCAGE_GRAPHROOT env override when set, else the fixed default. anon-pi builds
+ * images into this store so `netcage run` finds them. This is a temporary
+ * coupling to a netcage-internal path; it goes away once netcage exposes a
+ * `build`/`load` verb (then anon-pi delegates to netcage instead).
+ */
+export function resolveNetcageGraphroot(
+	penv: Record<string, string | undefined>,
+): string {
+	const p = penv.NETCAGE_GRAPHROOT;
+	return p && p.trim() !== '' ? p.trim() : NETCAGE_DEFAULT_GRAPHROOT;
+}
+
 /**
  * PURE: resolve the projects root (the host dir mounted at /projects) with the
  * decided precedence, highest first:
  *   --mount (CLI) > env ANON_PI_PROJECTS > machine.json.projects >
  *   config.json.projects > built-in <home>/projects
- * This task delivers the config/env/machine layers; `mountParent` is the
- * documented top slot the later --mount CLI task threads in (pass the resolved
- * host parent). A relative override is resolved to an absolute path.
+ * A leading `~` in any override is expanded to $HOME; a relative override is
+ * resolved to an absolute path.
  */
 export function resolveProjectsRoot(args: {
 	env: AnonPiEnv;
@@ -608,7 +668,7 @@ export function resolveProjectsRoot(args: {
 		nonEmpty(env.projects) ??
 		nonEmpty(machine?.projects) ??
 		nonEmpty(config?.projects);
-	if (pick !== undefined) return resolve(pick);
+	if (pick !== undefined) return resolve(expandTilde(pick, env.home));
 	return builtinProjectsRoot(env);
 }
 
@@ -782,14 +842,105 @@ export interface ParsedLaunch {
 	piArgs?: string[];
 }
 
+/**
+ * pi flags that make sense with NO anon-pi project, so `anon-pi <flag> ...`
+ * launches pi (at the projects root) and forwards this flag + everything after
+ * it verbatim. Two families:
+ *  - SESSION selection (`--session <id>` etc.): pi finds the session file (in the
+ *    always-mounted machine home) and switches to its own project cwd, so no
+ *    project is needed. Mirrors pi's own resume hint (`pi --session <id>`), so
+ *    pasting `anon-pi --session <id>` just works.
+ *  - QUERY (`--list-models`/`--models`): pi prints + exits, no project relevant.
+ * For arbitrary pi flags with no project (e.g. `--model x`), use the explicit
+ * `anon-pi pi <args…>` passthrough instead.
+ */
+const PI_NO_PROJECT_FLAGS: ReadonlySet<string> = new Set([
+	// session selection
+	'--session',
+	'--session-id',
+	'--resume',
+	'-r',
+	'--continue',
+	'-c',
+	'--fork',
+	// query-and-exit
+	'--list-models',
+	'--models',
+]);
+
+/** True iff `a` is a pi flag anon-pi accepts with no project (see PI_NO_PROJECT_FLAGS). */
+function isPiNoProjectFlag(a: string): boolean {
+	return PI_NO_PROJECT_FLAGS.has(a);
+}
+
+/**
+ * The explicit pi-passthrough token: `anon-pi pi <args…>` runs pi with the given
+ * args and NO project (the general escape hatch for any pi flag). It is a
+ * RESERVED project name (see RESERVED_NAMES) so a project can never shadow it.
+ */
+export const PI_PASSTHROUGH_TOKEN = 'pi';
+
+/**
+ * PURE: whether forwarded pi args request pi's NON-INTERACTIVE (print) mode,
+ * i.e. contain `-p`/`--print`. This is the ONLY headless shape (it needs no
+ * TTY): other forwarded args (`--session <id>`, `--model x`, ...) are still
+ * INTERACTIVE and need a TTY + `-it`. Shared by the CLI's no-TTY discipline and
+ * the RunPlan's `-it` decision so they agree.
+ */
+export function isHeadlessPiArgs(
+	piArgs: readonly string[] | undefined,
+): boolean {
+	return !!piArgs && piArgs.some((a) => a === '-p' || a === '--print');
+}
+
+/**
+ * Finish parsing a NO-PROJECT pi launch (`anon-pi --session <id> ...`,
+ * `anon-pi --list-models`, or the explicit `anon-pi pi <args…>`): pi mode, NO
+ * project (pi picks its own cwd / prints + exits), the flag(s) + rest forwarded.
+ * `--shell` is incompatible (a shell forwards no pi args).
+ */
+function finishPiNoProjectLaunch(args: {
+	machine: string;
+	machineExplicit: boolean;
+	mountParent?: string;
+	keep: boolean;
+	rm: boolean;
+	shell: boolean;
+	piArgs: string[];
+	fail: (msg: string) => never;
+}): ParsedLaunch {
+	if (args.keep && args.rm) {
+		args.fail(
+			'--keep and --rm are contradictory (pick one; --rm is the default)',
+		);
+	}
+	if (args.shell) {
+		args.fail(
+			'--shell forwards no pi args (a shell has no session/query). Drop --shell.',
+		);
+	}
+	return {
+		mode: 'pi',
+		machine: args.machine,
+		machineExplicit: args.machineExplicit,
+		project: undefined,
+		mountParent: args.mountParent,
+		keep: args.keep,
+		piArgs: args.piArgs,
+	};
+}
+
 /**
  * PURE: parse grammar A into a ParsedLaunch. Consumes the anon-pi flags
  * (`-m <machine>`, `--shell`, `--mount <parent>`, `--keep`/`--rm`) LEFT of the
  * project positional; the FIRST bare positional is the project (`.` allowed as
  * the root token). In pi mode every token AFTER the project is forwarded to pi
  * verbatim (so `anon-pi recon -p '...'` works) — anon-pi flags must come before
- * the project. In shell/menu mode a stray extra positional is an error (bash has
- * no forwarded-args grammar; the menu takes no project).
+ * the project. A pi session-resume flag (`--session <id>`, `--continue`,
+ * `--resume`, `--fork <id>`) in the project position starts a NO-project pi
+ * launch that forwards to pi (pi resolves the session + cwd itself). In
+ * shell/menu mode a stray extra positional is an error (bash has no
+ * forwarded-args grammar; the menu takes no project).
  *
  * Validates the project name and the `-m` machine name via validateName (the
  * reserved-name guard); `--mount <parent>` is a HOST path in its own namespace,
@@ -845,6 +996,44 @@ export function parseLaunchArgs(args: readonly string[]): ParsedLaunch {
 			i++;
 			break;
 		}
+		if (a === PI_PASSTHROUGH_TOKEN) {
+			// `anon-pi pi <args…>`: the explicit passthrough. Run pi with the
+			// following args and NO project (pi picks its own cwd, or prints + exits
+			// for a query). The general escape hatch for ANY pi flag with no project
+			// (`anon-pi pi --model x`, `anon-pi pi --export out.html --session <id>`).
+			return finishPiNoProjectLaunch({
+				machine,
+				machineExplicit: machineSet,
+				mountParent,
+				keep: keepSeen,
+				rm: rmSeen,
+				shell,
+				piArgs: args.slice(i + 1),
+				fail,
+			});
+		}
+		if (isPiNoProjectFlag(a)) {
+			// A pi flag that needs NO anon-pi project (`--session <id>`/`--continue`/
+			// `--fork` resume by id; `--list-models`/`--models` print + exit). pi
+			// resolves its own cwd (or just prints), so anon-pi launches pi at the
+			// projects root and forwards this flag + everything after it verbatim.
+			// This makes pi's own "To resume: pi --session <id>" hint usable as
+			// `anon-pi --session <id>`. (For ARBITRARY pi flags with no project, use
+			// the explicit `anon-pi pi <args…>` passthrough.)
+			piArgs = args.slice(i);
+			project = undefined;
+			i = args.length;
+			return finishPiNoProjectLaunch({
+				machine,
+				machineExplicit: machineSet,
+				mountParent,
+				keep: keepSeen,
+				rm: rmSeen,
+				shell,
+				piArgs,
+				fail,
+			});
+		}
 		if (a.startsWith('-')) {
 			fail(`unknown option: ${a}`);
 		}
@@ -959,10 +1148,7 @@ export function resolveRunPlan(
 	// Which root the cwd resolves under: /work when --mount, else /projects.
 	const rootKind: RootKind = mounted ? 'mount' : 'projects';
 
-	// cwd: shell with no project sits at the machine home (/root); otherwise the
-	// project token (a name or `.`) resolves under the active root uniformly.
-	const cwd =
-		project === undefined ? CONTAINER_HOME_ROOT : resolveCwd(rootKind, project);
+	const cwd = launchCwd(mode, rootKind, project);
 
 	const fresh = homeFresh(machine.home);
 	const seedVersion = intent.seedVersion ?? SEED_VERSION;
@@ -974,7 +1160,7 @@ export function resolveRunPlan(
 	// (podman fails to allocate a TTY on a non-tty stdin). The CLI's broader
 	// no-TTY discipline (erroring when an interactive mode has no TTY) is a later
 	// task; here the argv simply omits -it for the one headless shape.
-	const headless = mode === 'pi' && !!intent.piArgs && intent.piArgs.length > 0;
+	const headless = mode === 'pi' && isHeadlessPiArgs(intent.piArgs);
 
 	const netcageArgs: string[] = ['run'];
 	// --rm by DEFAULT (throwaway); --keep leaves the container kept.
@@ -1134,13 +1320,12 @@ export type RunVsStart = {action: 'run'} | {action: 'start'; ref: string};
  * its internal shape is not a contract (compare only keys this function makes).
  */
 export function keptContainerKey(intent: LaunchIntent): string {
-	const {machine, projectsRoot, project, mountParent} = intent;
+	const {machine, mode, projectsRoot, project, mountParent} = intent;
 	const mounted = nonEmpty(mountParent) !== undefined;
 	const rootKind: RootKind = mounted ? 'mount' : 'projects';
 	// The same cwd resolution resolveRunPlan uses, so the key names the exact
 	// container a matching launch would run in (its conversation key).
-	const cwd =
-		project === undefined ? CONTAINER_HOME_ROOT : resolveCwd(rootKind, project);
+	const cwd = launchCwd(mode, rootKind, project);
 	return [
 		`machine=${machine.name}`,
 		`projectsRoot=${projectsRoot}`,
@@ -1889,6 +2074,73 @@ export interface ProxyFinding {
 	processHint?: string;
 }
 
+/** What `netcage detect-proxy --json` reports (the fields anon-pi consumes). */
+export interface NetcageDetectProxy {
+	schemaVersion?: number;
+	candidates?: Array<{
+		port?: number;
+		open?: boolean;
+		socks5?: boolean;
+		processHint?: string;
+	}>;
+	exitIP?: string;
+}
+
+/**
+ * PURE: map a parsed `netcage detect-proxy --json` result into anon-pi's
+ * ProxyFinding[] (so init can REUSE netcage's SOCKS scanner instead of its own
+ * probe, and both render through the same formatProxyFindings). The host is
+ * 127.0.0.1 (detect-proxy probes loopback); the socks5 boolean becomes a
+ * SocksHandshake verdict; the structural port hint is attached from
+ * DEFAULT_SOCKS_PROBE_PORTS by port. Tolerates missing/garbage (returns []).
+ * The per-candidate processHint is NOT copied onto each finding (it is host-wide;
+ * the CLI passes it once as formatProxyFindings' note).
+ */
+export function findingsFromNetcageDetect(
+	raw: NetcageDetectProxy | undefined,
+): ProxyFinding[] {
+	const rows = raw?.candidates;
+	if (!Array.isArray(rows)) return [];
+	const hintByPort = new Map(
+		DEFAULT_SOCKS_PROBE_PORTS.map((p) => [p.port, p.hint]),
+	);
+	const out: ProxyFinding[] = [];
+	for (const c of rows) {
+		if (!c || typeof c.port !== 'number') continue;
+		const open = c.open === true;
+		const handshake: SocksHandshake | undefined = !open
+			? undefined
+			: c.socks5 === true
+				? {socks5: true, method: 0}
+				: {socks5: false, reason: 'not SOCKS5'};
+		out.push({
+			host: '127.0.0.1',
+			port: c.port,
+			open,
+			handshake,
+			portHint: hintByPort.get(c.port),
+		});
+	}
+	return out;
+}
+
+/**
+ * PURE: the host-wide process note from a `netcage detect-proxy --json` result:
+ * the FIRST candidate that carries a `processHint` (they are all the same
+ * host-wide hint). Returns undefined when none. Rendered ONCE by the CLI (not
+ * per port), same as the local-probe path.
+ */
+export function processNoteFromNetcageDetect(
+	raw: NetcageDetectProxy | undefined,
+): string | undefined {
+	for (const c of raw?.candidates ?? []) {
+		if (c && typeof c.processHint === 'string' && c.processHint.trim() !== '') {
+			return c.processHint.trim();
+		}
+	}
+	return undefined;
+}
+
 /**
  * The set of substrings a findings line must NEVER contain: known exit-provider
  * / VPN brand names. This is the machine-checkable half of the never-label rule
@@ -2096,6 +2348,22 @@ function shippedFile(rel: string): string | undefined {
 	return undefined;
 }
 
+/**
+ * anon-pi's own version, read from the package.json shipped in the package root
+ * (resolved via shippedFile). Returns undefined if it cannot be found/parsed, so
+ * `--version` can fall back to a placeholder. Read-only.
+ */
+export function anonPiVersion(): string | undefined {
+	const pkg = shippedFile('package.json');
+	if (!pkg) return undefined;
+	try {
+		const parsed = JSON.parse(readFileSync(pkg, 'utf8')) as {version?: unknown};
+		return typeof parsed.version === 'string' ? parsed.version : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 // --- The `machine {create,list,set-image,rm}` verbs (pure parts) -------------
 //
 // Machines are first-class: an image + a persistent host home
@@ -2281,7 +2549,12 @@ export const HELP = `anon-pi - run pi on anonymized, jailed machines (netcage: f
 USAGE
   anon-pi                        MENU: pick a project (pi), a shell, or a new project
   anon-pi <project>              pi in the project (${CONTAINER_PROJECTS_ROOT}/<project>); exit pi -> host
-  anon-pi <project> <pi-args…>   forward args to pi (headless/one-shot; no TTY needed)
+  anon-pi <project> <pi-args…>   forward args to pi (e.g. -p for a headless one-shot)
+  anon-pi --session <id>         resume a pi session by id (forwarded to pi; no project needed)
+  anon-pi --continue             continue your most recent pi session (also -r/--resume, --fork)
+  anon-pi --list-models          list the models pi sees (also --models; no project needed)
+  anon-pi pi <pi-args…>          run pi with ANY args and no project (the passthrough)
+  anon-pi --version              print anon-pi's version (also -V)
   anon-pi --shell [<project>]    a jailed bash (at ~, or cd'd into <project>) - the project-hopper
   anon-pi -m <machine> [<p>]     the same, on <machine> (its own image + home + conversations)
   anon-pi --mount <parent> [<p>] root at a HOST parent folder instead of the projects root