anon-pi 0.13.0 → 0.15.0

package/src/anon-pi.ts

@@ -1579,21 +1579,22 @@ export function keyProject(fields: KeptKeyFields): string {
 }
 
 /**
- * PURE: pick the RUNNING anon-pi containers a `forward`/`ports` should offer.
- * Filters the supplied running managed containers (each with its decoded key
- * fields) to those on `machine`, optionally narrowed to `project` (its leaf cwd
- * name). With no project, every anon-pi container on the machine qualifies. The
- * caller resolves 0 (error) / 1 (auto) / many (picker).
+ * PURE: pick the RUNNING anon-pi containers a `forward`/`ports`/`snapshot` should
+ * offer. Filters the supplied running managed containers (each with its decoded
+ * key fields) OPTIONALLY by `machine` (undefined = every machine qualifies, used
+ * by `snapshot` where the machine is only a narrowing filter) and OPTIONALLY by
+ * `project` (its leaf cwd name). The caller resolves 0 (error) / 1 (auto) / many
+ * (picker).
  */
 export function resolveManagedMatches(args: {
 	containers: readonly ManagedContainer[];
-	machine: string;
+	machine?: string;
 	project?: string;
 }): ManagedContainer[] {
 	const {containers, machine, project} = args;
 	return containers.filter((c) => {
 		const f = parseKeptKey(c.key);
-		if (f.machine !== machine) return false;
+		if (machine !== undefined && f.machine !== machine) return false;
 		if (project !== undefined && keyProject(f) !== project) return false;
 		return true;
 	});
@@ -2032,6 +2033,71 @@ export function deriveProjectUsage(args: {
 	});
 }
 
+/**
+ * ONE session group a `machine snapshot` can carry over: a `sessions/<slug>/`
+ * dir in the source home. `project` is the project name when the slug matches a
+ * known project's `projectSessionSlug` (else undefined: an ORPHAN slug with no
+ * matching project, still offered, labelled by its raw slug so nothing hides).
+ * `label` is the human row text. `slug` is the exact dir name to copy/delete.
+ */
+export interface SnapshotSessionGroup {
+	slug: string;
+	project?: string;
+	label: string;
+}
+
+/**
+ * PURE: the cpSync filter predicate for a snapshot's "copy the home MINUS the
+ * sessions subtree" copy: true = copy `src`, false = skip it. It rejects the
+ * sessions dir itself and everything beneath it (`<sessionsDir>` and
+ * `<sessionsDir>/...`), and copies everything else. Extracted so the
+ * home-minus-sessions contract is unit-testable without the fs.
+ */
+export function copyIncludesForHomeMinusSessions(
+	src: string,
+	sessionsDir: string,
+): boolean {
+	return src !== sessionsDir && !src.startsWith(sessionsDir + '/');
+}
+
+/**
+ * PURE: map the session-dir slugs PRESENT under a source machine's `sessions/`
+ * to per-project rows a snapshot's carry-over picker offers. For each present
+ * slug, if it equals `projectSessionSlug(<project>)` for a known project, it is a
+ * PROJECT row (labelled by the project name); otherwise an ORPHAN-slug row
+ * (labelled by the raw slug, so a session with no current project folder is
+ * still shown, never silently dropped). Rows are sorted: named projects first
+ * (case-insensitive by name), then orphan slugs (by slug), for a stable picker.
+ * The caller (CLI) does the actual copy/delete of each chosen slug dir.
+ */
+export function snapshotSessionGroups(args: {
+	presentSlugs: readonly string[];
+	projects: readonly string[];
+}): SnapshotSessionGroup[] {
+	const slugToProject = new Map<string, string>();
+	for (const p of args.projects) {
+		// projectSessionSlug validates the name; a bad project name throws, which is
+		// correct (the projects list comes from real folder names).
+		slugToProject.set(projectSessionSlug(p), p);
+	}
+	const rows: SnapshotSessionGroup[] = args.presentSlugs.map((slug) => {
+		const project = slugToProject.get(slug);
+		return project !== undefined
+			? {slug, project, label: project}
+			: {slug, label: `${slug}  (no current project folder)`};
+	});
+	const lc = (s: string): string => s.toLowerCase();
+	return rows.sort((a, b) => {
+		// named projects before orphan slugs; within each, by their label key.
+		const an = a.project !== undefined ? 0 : 1;
+		const bn = b.project !== undefined ? 0 : 1;
+		if (an !== bn) return an - bn;
+		const ak = lc(a.project ?? a.slug);
+		const bk = lc(b.project ?? b.slug);
+		return ak < bk ? -1 : ak > bk ? 1 : 0;
+	});
+}
+
 /**
  * What ONE selectable menu row launches, so the CLI can dispatch a chosen entry
  * without re-deriving anything:
@@ -2907,16 +2973,18 @@ export function anonPiVersion(): string | undefined {
  *   - `set-image <name> <ref>`: name validated; the new image ref (non-empty).
  *   - `rm <name> [--yes]`: name validated; `yes` skips the confirm (the CLI
  *     still enforces the non-TTY abort when `yes` is false).
- *   - `snapshot <machine> <new-name> [--image-tag <ref>]`: both names validated;
- *     commits the source machine's running container into a new image and
- *     creates <new-name> pinned to it (the CLI does the netcage commit + create).
+ *   - `snapshot <new-name> [-m <machine>] [--image-tag <ref>]`: the sole
+ *     positional is the NEW machine name (validated); `-m <machine>` is an
+ *     OPTIONAL filter (which running container to commit when several are up),
+ *     NOT a required source. The CLI auto-detects the running container (picker
+ *     when several match), commits it, and creates <new-name> pinned to it.
  */
 export type MachineCommand =
 	| {verb: 'create'; name: string; image?: string}
 	| {verb: 'list'}
 	| {verb: 'set-image'; name: string; image: string}
 	| {verb: 'rm'; name: string; yes: boolean}
-	| {verb: 'snapshot'; source: string; name: string; imageTag?: string};
+	| {verb: 'snapshot'; name: string; machine?: string; imageTag?: string};
 
 /**
  * PURE: parse the tokens AFTER `machine` into a MachineCommand. Validates the
@@ -3013,15 +3081,22 @@ export function parseMachineArgs(args: readonly string[]): MachineCommand {
 	}
 
 	if (verb === 'snapshot') {
-		// snapshot <source-machine> <new-name> [--image-tag <ref>]: commit the
-		// source machine's running container into a new image and create <new-name>
-		// pinned to it. Both names are validated (safe machine segments); the
-		// image tag, if given, is a free-form ref.
-		let source: string | undefined;
+		// snapshot <new-name> [-m <machine>] [--image-tag <ref>]: commit a RUNNING
+		// container into a new image and create <new-name> pinned to it. The sole
+		// positional is the new machine name; `-m` is an OPTIONAL filter (which
+		// container when several are up), not a required source. The CLI auto-detects
+		// the container (picker when several match).
 		let name: string | undefined;
+		let machine: string | undefined;
 		let imageTag: string | undefined;
 		for (let i = 0; i < rest.length; i++) {
 			const a = rest[i];
+			if (a === '-m' || a === '--machine') {
+				const v = rest[++i];
+				if (v === undefined) fail(`${a} needs a machine name`);
+				machine = validateName(v as string, 'machine');
+				continue;
+			}
 			if (a === '--image-tag') {
 				const v = rest[++i];
 				if (v === undefined) fail('--image-tag needs an image ref');
@@ -3029,20 +3104,15 @@ export function parseMachineArgs(args: readonly string[]): MachineCommand {
 				continue;
 			}
 			if (a.startsWith('-')) fail(`unknown option: ${a}`);
-			if (source === undefined) {
-				source = validateName(a, 'machine');
-			} else if (name === undefined) {
-				name = validateName(a, 'machine');
-			} else {
-				fail(`machine snapshot takes <machine> <new-name>, got extra: ${a}`);
-			}
+			if (name !== undefined)
+				fail(`machine snapshot takes one <new-name>, got extra: ${a}`);
+			name = validateName(a, 'machine');
 		}
-		if (source === undefined || name === undefined)
-			fail('machine snapshot needs a <machine> and a <new-name>');
+		if (name === undefined) fail('machine snapshot needs a <new-name>');
 		return {
 			verb: 'snapshot',
-			source: source as string,
 			name: name as string,
+			machine: nonEmpty(machine),
 			imageTag: nonEmpty(imageTag),
 		};
 	}

package/src/cli.ts

@@ -12,6 +12,7 @@
 // egress.
 
 import {
+	cpSync,
 	existsSync,
 	mkdirSync,
 	readdirSync,
@@ -80,6 +81,9 @@ import {
 	resolveRunVsStart,
 	serializeMachineJson,
 	snapshotImageRef,
+	snapshotSessionGroups,
+	copyIncludesForHomeMinusSessions,
+	type SnapshotSessionGroup,
 	serializeConfigJson,
 	setImageWarning,
 	keptContainerKey,
@@ -682,7 +686,7 @@ function runMachine(machineArgs: string[]): number {
 			case 'rm':
 				return machineRm(env, cmd.name, cmd.yes);
 			case 'snapshot':
-				return machineSnapshot(env, cmd.source, cmd.name, cmd.imageTag);
+				return machineSnapshot(env, cmd.name, cmd.machine, cmd.imageTag);
 		}
 	} catch (e) {
 		return reportAnonPiError(e);
@@ -831,21 +835,23 @@ function machineRm(env: AnonPiEnv, name: string, yes: boolean): number {
 }
 
 /**
- * `machine snapshot <source> <new-name> [--image-tag <ref>]`: commit the source
- * machine's RUNNING jailed container into a new image and create <new-name>
- * pinned to it. The user does interactive system work in a session (e.g.
- * `sudo apt install`), then, WITHOUT having exited (the default `--rm` would
- * have destroyed the container), preserves that exact environment as a new
- * machine. podman pauses the container during commit and unpauses, so the live
- * session survives. The new machine gets a FRESH home (image and home are
- * orthogonal; snapshot keeps the SOFTWARE, not the conversations). Forced egress
- * is untouched: commit is a local podman op, and the snapshot machine relaunches
+ * `machine snapshot <new-name> [-m <machine>] [--image-tag <ref>]`: commit a
+ * RUNNING jailed container into a new image and create <new-name> pinned to it.
+ * The user does interactive system work in a session (e.g. `sudo apt install`),
+ * then, WITHOUT having exited (the default `--rm` would have destroyed the
+ * container), preserves that exact environment as a new machine. The container
+ * to commit is AUTO-DETECTED from the running anon-pi containers (a picker when
+ * several are up); `-m <machine>` is an OPTIONAL filter, not a required source.
+ * podman pauses the container during commit and unpauses, so the live session
+ * survives. The new machine gets a FRESH home (image and home are orthogonal;
+ * snapshot keeps the SOFTWARE, not the conversations). Forced egress is
+ * untouched: commit is a local podman op, and the snapshot machine relaunches
  * through the same forced-egress jail.
  */
 function machineSnapshot(
 	env: AnonPiEnv,
-	source: string,
 	name: string,
+	machine: string | undefined,
 	imageTag: string | undefined,
 ): number {
 	// Refuse to clobber an existing target machine FIRST (before netcage / any
@@ -862,9 +868,9 @@ function machineSnapshot(
 
 	if (!hasNetcage()) return netcageMissing();
 
-	// Resolve the ONE running anon-pi container for the SOURCE machine (reuse the
-	// forward/ports running-container resolution, scoped by machine).
-	const target = resolveRunningContainer(source, 'snapshot');
+	// Auto-detect the running anon-pi container to commit (optionally filtered by
+	// -m <machine>); reuses the forward/ports running-container resolution.
+	const target = resolveRunningContainer(machine, 'snapshot');
 	if (target === undefined) return 1;
 
 	const imageRef = imageTag ?? snapshotImageRef(name, new Date());
@@ -879,21 +885,133 @@ function machineSnapshot(
 		return committed;
 	}
 
-	// Create the machine pinned to the committed image (its home seeds on first
-	// launch, exactly like `machine create`).
+	// Create the machine pinned to the committed image.
 	mkdirSync(machineHomeDir(env, name), {recursive: true});
 	writeFileSync(
 		machineJsonPath(env, name),
 		serializeMachineJson({image: imageRef}),
 	);
+
+	// The source machine is the machine of the container we committed (its stamped
+	// key carries it). Copy its home into the new machine's home, EXCEPT the
+	// sessions subtree (conversations are handled separately below). Copying the
+	// config/extensions is safe + preferable to a fresh seed here: the new image IS
+	// the committed source filesystem, so the home's extensions/binaries are
+	// correct-for-the-new-image (and the copied seed marker means no reseed).
+	const sourceMachine = parseKeptKey(target.key).machine;
+	if (sourceMachine !== undefined) {
+		copyHomeMinusSessions(env, sourceMachine, name);
+	}
+
 	process.stdout.write(
-		`anon-pi: snapshotted machine ${JSON.stringify(source)} into ${JSON.stringify(name)} ` +
+		`anon-pi: snapshotted ${target.name} into machine ${JSON.stringify(name)} ` +
 			`(image ${imageRef}) at ${targetDir}.\n` +
-			`Its home seeds fresh on first launch, e.g. \`anon-pi -m ${name} --shell\`.\n`,
+			(sourceMachine !== undefined
+				? `Copied ${JSON.stringify(sourceMachine)}'s home (config + extensions) into it.\n`
+				: 'Its home seeds fresh on first launch.\n'),
 	);
+
+	// Offer the source's conversation history, grouped by project, opt-in per
+	// project (default none). TTY only; a non-TTY snapshot carries no sessions.
+	if (sourceMachine !== undefined) {
+		carryOverSessions(env, sourceMachine, name);
+	}
 	return 0;
 }
 
+/**
+ * Recursively copy machine <source>'s home into machine <dest>'s home, EXCLUDING
+ * the `.pi/agent/sessions/` subtree (conversations are carried over separately,
+ * per-project, opt-in). Best-effort: an absent source home is a no-op (the dest
+ * just stays fresh). Uses cpSync with a filter that rejects the sessions dir and
+ * anything under it.
+ */
+function copyHomeMinusSessions(
+	env: AnonPiEnv,
+	source: string,
+	dest: string,
+): void {
+	const srcHome = machineHomeDir(env, source);
+	if (!existsSync(srcHome)) return;
+	const destHome = machineHomeDir(env, dest);
+	const sessionsPath = machineSessionsDir(env, source);
+	cpSync(srcHome, destHome, {
+		recursive: true,
+		// Exclude the sessions dir itself and everything beneath it (pure predicate).
+		filter: (src) => copyIncludesForHomeMinusSessions(src, sessionsPath),
+	});
+}
+
+/**
+ * Offer the source machine's pi conversation history (grouped BY PROJECT) as an
+ * opt-in carry-over into the new machine. Each present `sessions/<slug>/` group
+ * is a project row (or an orphan-slug row); DEFAULT all UNSELECTED, per-project
+ * COPY or SKIP. Copy duplicates that session dir into the new home. There is NO
+ * per-row move; after the copies, ONE confirmed (default No) step can delete the
+ * copied groups from the SOURCE home (the only "move"). No-TTY: copy nothing.
+ */
+function carryOverSessions(env: AnonPiEnv, source: string, dest: string): void {
+	const presentSlugs = readDirNames(machineSessionsDir(env, source));
+	if (presentSlugs.length === 0) return;
+
+	if (!process.stdin.isTTY) {
+		process.stderr.write(
+			`anon-pi: ${presentSlugs.length} conversation group(s) on ${JSON.stringify(source)} ` +
+				'were NOT copied (no TTY to choose). The new machine starts with no history.\n',
+		);
+		return;
+	}
+
+	// Label rows by project name (matching the machine-invariant slug); an orphan
+	// slug with no current project folder is still offered by its raw slug.
+	const config = readJsonConfig(env);
+	const projectsRoot = resolveProjectsRoot({env, config});
+	const groups = snapshotSessionGroups({
+		presentSlugs,
+		projects: readDirNames(projectsRoot),
+	});
+
+	process.stderr.write(
+		`anon-pi: ${JSON.stringify(source)} has ${groups.length} conversation group(s) ` +
+			'(by project). Choose COPY or SKIP for each (default SKIP):\n',
+	);
+	const copied: SnapshotSessionGroup[] = [];
+	for (const g of groups) {
+		const ans = promptLine(`  ${g.label}  [copy/SKIP]: `);
+		if (ans !== undefined && /^c(opy)?$/i.test(ans.trim())) {
+			const from = join(machineSessionsDir(env, source), g.slug);
+			const to = join(machineSessionsDir(env, dest), g.slug);
+			mkdirSync(machineSessionsDir(env, dest), {recursive: true});
+			cpSync(from, to, {recursive: true});
+			copied.push(g);
+		}
+	}
+
+	if (copied.length === 0) {
+		process.stderr.write('anon-pi: no conversation groups copied.\n');
+		return;
+	}
+	process.stderr.write(
+		`anon-pi: copied ${copied.length} conversation group(s) into ${JSON.stringify(dest)}.\n`,
+	);
+
+	// The ONLY "move": an explicit, confirmed, default-No delete from the SOURCE.
+	const ans = promptLine(
+		`Also DELETE the ${copied.length} copied group(s) from source machine ${JSON.stringify(source)}? [y/N] `,
+	);
+	if (ans !== undefined && /^y(es)?$/i.test(ans.trim())) {
+		for (const g of copied) {
+			rmSync(join(machineSessionsDir(env, source), g.slug), {
+				recursive: true,
+				force: true,
+			});
+		}
+		process.stderr.write(
+			`anon-pi: removed ${copied.length} group(s) from ${JSON.stringify(source)}.\n`,
+		);
+	}
+}
+
 // --- the destructive cleanup verbs (thin I/O over the pure resolvers) --------
 //
 // `--delete-home [<machine>]` and `--delete-project <project>` REPLACE the old
@@ -2114,22 +2232,29 @@ USAGE
   anon-pi machine list                            list machines and their images
   anon-pi machine set-image <name> <ref>          re-pin the image (WARNS; no reseed)
   anon-pi machine rm <name> [--yes]               delete the machine + its home
-  anon-pi machine snapshot <machine> <new-name> [--image-tag <ref>]
-                                                  commit <machine>'s RUNNING container
-                                                  into a new image + create <new-name>
+  anon-pi machine snapshot <new-name> [-m <machine>] [--image-tag <ref>]
+                                                  commit a RUNNING container into a
+                                                  new image + create <new-name>
 
 A machine is an image + a persistent host home (machines/<name>/{machine.json,home/}).
 The home is seeded on FIRST LAUNCH, not at create. \`set-image\` re-pins only and
 warns (the home was built for the old image); \`rm\` confirms on a TTY, skips with
 \`--yes\`, and aborts non-interactively without it.
 
-\`snapshot\` captures the CURRENT filesystem of <machine>'s running jailed
-container (e.g. after \`sudo apt install\`) into a new image and creates
-<new-name> pinned to it, so you can preserve an environment you built
-interactively WITHOUT having pre-decided \`--keep\`. The container must still be
-RUNNING (do not exit the session); podman pauses it briefly during the commit.
-The new machine gets a FRESH home (the image is the software, the home is
-separate). Same forced-egress jail on relaunch.
+\`snapshot\` captures the CURRENT filesystem of a RUNNING jailed container (e.g.
+after \`sudo apt install\`) into a new image and creates <new-name> pinned to it,
+so you can preserve an environment you built interactively WITHOUT having
+pre-decided \`--keep\`. The container is auto-detected from the running anon-pi
+containers (a picker when several are up); \`-m <machine>\` is an OPTIONAL filter,
+not a required source. The container must still be RUNNING (do not exit the
+session); podman pauses it briefly during the commit. Same forced-egress jail on
+relaunch.
+
+The source machine's HOME is copied into the new machine (config + extensions +
+dotfiles), MINUS its conversations. Conversations are offered separately, grouped
+BY PROJECT, opt-in per project (default SKIP), COPY or SKIP each (no TTY => none
+copied). After copying, one confirmed step (default No) can DELETE the copied
+groups from the source machine (the only "move"); COPY never touches the source.
 `;
 
 // --- impure helpers ---------------------------------------------------------
@@ -2303,14 +2428,16 @@ function resolveForwardTarget(
 }
 
 /**
- * Resolve the ONE running anon-pi container for a MACHINE (no project scope, no
- * port hints), for `machine snapshot`. Filters the running managed containers by
- * machine: 0 => error (start a session first), 1 => it, many => an arrow-key
- * picker labelled by each container's project + name. Returns undefined on
- * no-match or a cancelled pick (reason printed). TTY needed only for the picker.
+ * Resolve the ONE running anon-pi container to act on, for `machine snapshot`.
+ * The container is what matters; `machine` is an OPTIONAL narrowing filter
+ * (undefined = every running anon-pi container qualifies). 0 => error (start a
+ * session first), 1 => it, many => an arrow-key picker labelled by each
+ * container's machine + project + name (so a cross-machine list is
+ * distinguishable). Returns undefined on no-match or a cancelled pick (reason
+ * printed). TTY needed only for the picker.
  */
 function resolveRunningContainer(
-	machine: string,
+	machine: string | undefined,
 	verb: string,
 ): ManagedContainer | undefined {
 	const matches = resolveManagedMatches({
@@ -2318,10 +2445,12 @@ function resolveRunningContainer(
 		machine,
 		project: undefined,
 	});
+	const scope =
+		machine !== undefined ? ` for machine ${JSON.stringify(machine)}` : '';
 	if (matches.length === 0) {
 		process.stderr.write(
-			`anon-pi: no running anon-pi container for machine ${JSON.stringify(machine)}. ` +
-				`Start a session (e.g. \`anon-pi -m ${machine} --shell\`), do your work, and ` +
+			`anon-pi: no running anon-pi container${scope}. ` +
+				'Start a session (e.g. `anon-pi <project>`), do your work, and ' +
 				`WITHOUT exiting run \`anon-pi machine ${verb}\` from another terminal.\n`,
 		);
 		return undefined;
@@ -2330,15 +2459,20 @@ function resolveRunningContainer(
 
 	if (!process.stdin.isTTY) {
 		process.stderr.write(
-			`anon-pi: ${matches.length} running containers on machine ${JSON.stringify(machine)}; ` +
-				'a terminal is needed to pick one.\n',
+			`anon-pi: ${matches.length} running containers${scope}; a terminal is needed ` +
+				'to pick one (or narrow with `-m <machine>`).\n',
 		);
 		return undefined;
 	}
 	const entries: MenuEntry[] = matches.map((c) => {
-		const proj = keyProject(parseKeptKey(c.key));
+		const f = parseKeptKey(c.key);
+		const proj = keyProject(f);
 		const label = proj === '' ? '(shell)' : proj;
-		return {kind: 'project', project: c.ref, label: `${label} [${c.name}]`};
+		return {
+			kind: 'project',
+			project: c.ref,
+			label: `${f.machine ?? '?'} / ${label} [${c.name}]`,
+		};
 	});
 	const picked = select(entries, {
 		header: `anon-pi: pick a container to ${verb} (\u2191/\u2193 move, Enter select, Ctrl-C quit)`,