@jals1212/pi-spaces 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,33 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 0.2.0
+
+### Added
+
+- `/space remove` asks, after the confirmation, whether to keep a backup:
+  the space moves to `.backups/<name>-<UTC time>` in the spaces folder, and
+  keeping one is the first choice. `--yes` keeps a backup, and `--no-backup`
+  deletes without one. `backupSpace` and `BACKUPS` in the core do it, with the
+  same checks as `removeSpace`.
+
+### Changed
+
+- `/space remove <name> --yes` now keeps a backup instead of deleting the
+  space; add `--no-backup` to delete it as before.
+
+### Fixed
+
+- `/space new` copies a local path that loads another copy of this package
+  (a folder whose `package.json` is named `@jals1212/pi-spaces`) instead of
+  writing the folder of the copy that runs.
+- `/space remove` and `backupSpace` report a backup that cannot be written
+  (for example a read-only spaces folder) as an error that says the space was
+  not removed and offers `--no-backup`, instead of a raw filesystem error.
+- `findOwnDeclaration` takes an optional fallback, answered when nothing
+  matches, and an empty package folder matches a local path only by its
+  `package.json` name.
+
 ## 0.1.1
 
 ### Changed

package/README.md

@@ -45,6 +45,8 @@ From your shell:
 ```sh
 pi --space work                         # start Pi in "work"
 pi --space work "review this branch"    # with a prompt
+pi-space --new work                     # create a space (optional CLI)
+pi-space --remove work                  # delete it, after asking; keeps a backup unless told not to (optional CLI)
 pi-space                                # pick from a numbered list (optional CLI)
 ```
 
@@ -60,7 +62,7 @@ A new space starts empty except for a `settings.json` that declares this package
 | `/space switch <name>` | Restarts Pi in that space. `base` is the home Pi started with. |
 | `/space switch` | Same as `/space`. |
 | `/space rename <old> <new>` | Renames a space. The active space cannot be renamed. |
-| `/space remove <name>` | Deletes a space after asking. `--yes` skips the question; it is required without a dialog (print and JSON modes). |
+| `/space remove <name> [--yes] [--no-backup]` | Deletes a space after asking, then asks whether to keep a backup in `<spaces folder>/.backups` (keeping one is first in the list; dismissing the question keeps the space). `--yes` skips the questions and keeps a backup; it is required without a dialog (print and JSON modes). `--no-backup` deletes without one. |
 | `pi --space <name>` | Starts Pi directly in a space, keeping the prompt and every other option. |
 
 The status line shows `space: <name>` while a space is active, and nothing in the base home.
@@ -71,7 +73,7 @@ Choosing an argument such as `switch` from the `/space ` suggestions only fills
 
 ## The `pi-space` command
 
-The optional `@jals1212/pi-spaces-cli` package adds a `pi-space` command to your shell: `pi-space` picks a space from a numbered list and starts Pi in it, `pi-space <name> [pi args...]` starts Pi in a named space, and `pi-space list` lists them. `PI_SPACES_COMMAND` makes it run another program that runs Pi. It only runs `pi --space <name>`, so this extension must be installed in the home it opens. See [`cli/README.md`](cli/README.md) for the commands, `PI_SPACES_COMMAND` and the exit status.
+The optional `@jals1212/pi-spaces-cli` package adds a `pi-space` command to your shell: `pi-space` picks a space from a numbered list and starts Pi in it, `pi-space <name> [pi args...]` starts Pi in a named space, `pi-space --new <name>` creates one, `pi-space --remove <name>` deletes one, and `pi-space list` lists them. `--command` and `--dir` (or `PI_SPACES_COMMAND` and `PI_SPACES_DIR`) make it run another program that runs Pi, with that program's spaces. It only runs `pi --space <name>`, so this extension must be installed in the home it opens. See [`cli/README.md`](cli/README.md) for the commands, the options and the exit status.
 
 ## Configuration reference
 
@@ -119,17 +121,19 @@ Pi reads its agent home once, when it starts, so a running session cannot move t
 
 ## What it leaves on your machine
 
-Only the spaces you create, each a folder in the spaces folder, and its `settings.json`. Pi fills a space as it would any home. Removing a space deletes its folder; nothing else is written outside it.
+Only the spaces you create, each a folder in the spaces folder, and its `settings.json`. Pi fills a space as it would any home. Removing a space moves its folder to `.backups/<name>-<UTC time>` in the spaces folder, or deletes it with `--no-backup` or when you choose so; nothing else is written outside it. A backup is a whole space: move it back to restore it (`mv ~/.pi/spaces/.backups/work-2026-10-28T14-30-05Z ~/.pi/spaces/work`), or delete it when you no longer need it. Backups are never removed for you, and `.backups` is never listed as a space.
 
 ## Safety
 
-`/space remove` and `/space rename` refuse:
+`/space remove`, `/space rename` and `pi-space --remove` refuse, before they ask:
 
 - `base` and the active space;
 - symlinks, and anything that is not a real folder directly inside the spaces folder;
 - a space that holds the current or base home;
 - a spaces folder that is the filesystem root, your home folder, or the agent home (or inside it).
 
+A backup also needs `.backups` to be a real folder, not a symlink or a file.
+
 ## Development
 
 Two packages live in this repository: the Pi extension and its shared core at the root (`@jals1212/pi-spaces`), and the `pi-space` command in `cli/` (`@jals1212/pi-spaces-cli`).

package/dist/command.js

@@ -1,9 +1,24 @@
 // The /space command, kept apart from Pi's extension API so it can be tested directly.
 import { join } from "node:path";
 import {               relaunchEnv, resolveSwitch } from "./relaunch.js";
-import { activeSpace, BASE, checkRemovable, createSpace,           listSpaces,                          removeSpace, renameSpace, SpaceError } from "./spaces.js";
+import {
+	activeSpace,
+	BACKUPS,
+	BASE,
+	backupSpace,
+	checkRemovable,
+	createSpace,
+	         
+	listSpaces,
+	                        
+	removeSpace,
+	renameSpace,
+	SpaceError,
+} from "./spaces.js";
 
-export const USAGE = "Usage: /space [list | new <name> | remove <name> | rename <old> <new> | switch [<name>]]";
+export const USAGE = "Usage: /space [list | new <name> | remove <name> [--yes] [--no-backup] | rename <old> <new> | switch [<name>]]";
+const KEEP_BACKUP = "Keep a backup";
+const NO_BACKUP = "Delete without a backup";
 const SUBCOMMANDS = ["list", "new", "remove", "rename", "switch"];
 
                                       
@@ -43,9 +58,8 @@ export async function runSpaceCommand(args        , deps                  )
 			ctx.ui.notify(`Created space "${rest[0]}" at ${path}. Enter it with /space switch ${rest[0]}.`, "info");
 			return;
 		}
-		if (sub === "remove" && (rest.length === 1 || (rest.length === 2 && rest[1] === "--yes"))) {
-			return await remove(rest[0], rest[1] === "--yes", deps);
-		}
+		const removal = sub === "remove" ? parseRemove(rest) : undefined;
+		if (removal) return await remove(removal, deps);
 		if (sub === "rename" && rest.length === 2) {
 			renameSpace(deps.dir, rest[0], rest[1], deps.currentHome(), protectedHomes(deps));
 			ctx.ui.notify(`Renamed space "${rest[0]}" to "${rest[1]}".`, "info");
@@ -69,8 +83,24 @@ function list(deps                  )       {
 	deps.ctx.ui.notify(lines.join("\n"), "info");
 }
 
-async function remove(name        , yes         , deps                  )                {
+                   
+	             
+	             
+	                
+ 
+
+/** remove <name> with --yes and --no-backup after it, each at most once, in any order. */
+function parseRemove(rest          )                      {
+	const [name, ...flags] = rest;
+	if (name === undefined || name.startsWith("-")) return undefined;
+	if (flags.some((flag) => flag !== "--yes" && flag !== "--no-backup") || new Set(flags).size !== flags.length) return undefined;
+	return { name, yes: flags.includes("--yes"), backup: !flags.includes("--no-backup") };
+}
+
+/** Without --yes it asks to remove, then (without --no-backup) whether to keep a backup, keeping one first in the list. */
+async function remove({ name, yes, backup }         , deps                  )                {
 	const { ctx } = deps;
+	let keep = backup;
 	if (!yes) {
 		if (!ctx.hasUI) throw new SpaceError(`Removing a space needs confirmation; run /space remove ${name} --yes.`);
 		// Fail before asking when the space cannot be removed anyway.
@@ -79,10 +109,18 @@ async function remove(name        , yes         , deps                  )
 			`Remove space "${name}"?`,
 			`This deletes ${join(deps.dir, name)} and everything in it: sign-ins, packages, settings and sessions.`,
 		);
-		if (!ok) {
+		const choice = ok && backup ? await ctx.ui.select(`Keep a backup of "${name}" in ${join(deps.dir, BACKUPS)}?`, [KEEP_BACKUP, NO_BACKUP]) : undefined;
+		// Dismissing the backup question is not an answer to it, so nothing is removed.
+		if (!ok || (backup && choice === undefined)) {
 			ctx.ui.notify(`Kept space "${name}".`, "info");
 			return;
 		}
+		keep = backup && choice === KEEP_BACKUP;
+	}
+	if (keep) {
+		const path = backupSpace(deps.dir, name, deps.currentHome(), protectedHomes(deps));
+		ctx.ui.notify(`Removed space "${name}"; its backup is ${path}.`, "info");
+		return;
 	}
 	removeSpace(deps.dir, name, deps.currentHome(), protectedHomes(deps));
 	ctx.ui.notify(`Removed space "${name}".`, "info");

package/dist/spaces.js

@@ -149,6 +149,48 @@ export function removeSpace(dir        , name        , agentHome        , protec
 	rmSync(checkRemovable(dir, name, agentHome, protect, userHome), { recursive: true, force: true });
 }
 
+/** The folder inside the spaces folder that holds removed spaces; its leading dot keeps it from being a space. */
+export const BACKUPS = ".backups";
+
+/**
+ * Removes a space by moving it to <spaces folder>/.backups/<name>-<UTC time>, after checkRemovable.
+ * Returns the backup's path. A second backup in the same second gets a number; nothing is overwritten.
+ */
+export function backupSpace(
+	dir        ,
+	name        ,
+	agentHome        ,
+	protect           = [],
+	userHome         = osHomedir(),
+	now       = new Date(),
+)         {
+	const from = checkRemovable(dir, name, agentHome, protect, userHome);
+	const folder = join(dir, BACKUPS);
+	if ((existsSync(folder) || isSymlink(folder)) && !isRealFolder(folder)) {
+		throw new SpaceError(`The backups folder ${folder} is not a folder; move it away and try again.`);
+	}
+	try {
+		mkdirSync(folder, { recursive: true });
+	} catch (error) {
+		throw backupFailed(name, error);
+	}
+	const stamp = `${now.toISOString().slice(0, 19).replaceAll(":", "-")}Z`;
+	let to = join(folder, `${name}-${stamp}`);
+	for (let n = 2; existsSync(to) || isSymlink(to); n++) to = join(folder, `${name}-${stamp}-${n}`);
+	// Inside the spaces folder, so the same filesystem: a rename, never a copy.
+	try {
+		renameSync(from, to);
+	} catch (error) {
+		throw backupFailed(name, error);
+	}
+	return to;
+}
+
+function backupFailed(name        , error         )             {
+	const reason = error instanceof Error ? error.message : String(error);
+	return new SpaceError(`Could not back up space "${name}": ${reason}. The space was not removed; fix that, or remove it without a backup with --no-backup.`);
+}
+
 /** Renames a space after the same safety checks as removal. The new name must be free. */
 export function renameSpace(dir        , oldName        , newName        , agentHome        , protect           = [], userHome         = osHomedir())       {
 	assertName(oldName);
@@ -174,22 +216,39 @@ function gitRepoName(source        )         {
 	return withoutRef.replace(/\.git$/, "").split(/[/:]/).pop() ?? "";
 }
 
+/** The name in a local package folder's package.json, or undefined when there is none. */
+function localPackageName(folder        )                     {
+	try {
+		const name = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"))?.name;
+		return typeof name === "string" ? name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 function samePath(a        , b        )          {
 	return realOrResolved(a) === realOrResolved(b);
 }
 
 /**
  * This package's declaration in the current home's settings.json, so a new space loads it the same way.
- * A local path is made absolute. Without a match (for example when loaded with -e), the package folder itself.
+ * A local path matches when it is the package folder or another folder whose package.json has this package's name,
+ * and is made absolute. Without a match (for example when loaded with -e), the fallback, which is the package folder itself
+ * unless given. An empty packageRoot (unknown folder) matches a local path only by its package.json name.
  */
-export function findOwnDeclaration(agentHome        , packageName        , packageRoot        )                     {
+export function findOwnDeclaration(
+	agentHome        ,
+	packageName        ,
+	packageRoot        ,
+	fallback                     = packageRoot,
+)                     {
 	let packages         ;
 	try {
 		packages = JSON.parse(readFileSync(join(agentHome, "settings.json"), "utf8"))?.packages;
 	} catch {
-		return packageRoot;
+		return fallback;
 	}
-	if (!Array.isArray(packages)) return packageRoot;
+	if (!Array.isArray(packages)) return fallback;
 	const repo = packageName.split("/").pop() ?? packageName;
 	for (const entry of packages) {
 		const source = typeof entry === "string" ? entry : typeof entry?.source === "string" ? entry.source : undefined;
@@ -199,11 +258,11 @@ export function findOwnDeclaration(agentHome        , packageName        , packa
 			if (npmName(source) === packageName) match = source;
 		} else if (isLocalSource(source)) {
 			const absolute = isAbsolute(source) ? source : resolve(agentHome, expandTilde(source, osHomedir()));
-			if (samePath(absolute, packageRoot)) match = absolute;
+			if ((packageRoot !== "" && samePath(absolute, packageRoot)) || localPackageName(absolute) === packageName) match = absolute;
 		} else if (gitRepoName(source) === repo) {
 			match = source;
 		}
 		if (match !== undefined) return typeof entry === "string" ? match : { ...entry, source: match };
 	}
-	return packageRoot;
+	return fallback;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/pi-spaces",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Named spaces for Pi: keep several agent homes (sign-ins, packages, settings) and pick one by name.",
   "license": "MIT",
   "author": "jals1212",

package/src/command.ts

@@ -1,9 +1,24 @@
 // The /space command, kept apart from Pi's extension API so it can be tested directly.
 import { join } from "node:path";
 import { type Command, relaunchEnv, resolveSwitch } from "./relaunch.ts";
-import { activeSpace, BASE, checkRemovable, createSpace, type Env, listSpaces, type PackageDeclaration, removeSpace, renameSpace, SpaceError } from "./spaces.ts";
+import {
+	activeSpace,
+	BACKUPS,
+	BASE,
+	backupSpace,
+	checkRemovable,
+	createSpace,
+	type Env,
+	listSpaces,
+	type PackageDeclaration,
+	removeSpace,
+	renameSpace,
+	SpaceError,
+} from "./spaces.ts";
 
-export const USAGE = "Usage: /space [list | new <name> | remove <name> | rename <old> <new> | switch [<name>]]";
+export const USAGE = "Usage: /space [list | new <name> | remove <name> [--yes] [--no-backup] | rename <old> <new> | switch [<name>]]";
+const KEEP_BACKUP = "Keep a backup";
+const NO_BACKUP = "Delete without a backup";
 const SUBCOMMANDS = ["list", "new", "remove", "rename", "switch"];
 
 export interface SpaceCommandContext {
@@ -43,9 +58,8 @@ export async function runSpaceCommand(args: string, deps: SpaceCommandDeps): Pro
 			ctx.ui.notify(`Created space "${rest[0]}" at ${path}. Enter it with /space switch ${rest[0]}.`, "info");
 			return;
 		}
-		if (sub === "remove" && (rest.length === 1 || (rest.length === 2 && rest[1] === "--yes"))) {
-			return await remove(rest[0], rest[1] === "--yes", deps);
-		}
+		const removal = sub === "remove" ? parseRemove(rest) : undefined;
+		if (removal) return await remove(removal, deps);
 		if (sub === "rename" && rest.length === 2) {
 			renameSpace(deps.dir, rest[0], rest[1], deps.currentHome(), protectedHomes(deps));
 			ctx.ui.notify(`Renamed space "${rest[0]}" to "${rest[1]}".`, "info");
@@ -69,8 +83,24 @@ function list(deps: SpaceCommandDeps): void {
 	deps.ctx.ui.notify(lines.join("\n"), "info");
 }
 
-async function remove(name: string, yes: boolean, deps: SpaceCommandDeps): Promise<void> {
+interface Removal {
+	name: string;
+	yes: boolean;
+	backup: boolean;
+}
+
+/** remove <name> with --yes and --no-backup after it, each at most once, in any order. */
+function parseRemove(rest: string[]): Removal | undefined {
+	const [name, ...flags] = rest;
+	if (name === undefined || name.startsWith("-")) return undefined;
+	if (flags.some((flag) => flag !== "--yes" && flag !== "--no-backup") || new Set(flags).size !== flags.length) return undefined;
+	return { name, yes: flags.includes("--yes"), backup: !flags.includes("--no-backup") };
+}
+
+/** Without --yes it asks to remove, then (without --no-backup) whether to keep a backup, keeping one first in the list. */
+async function remove({ name, yes, backup }: Removal, deps: SpaceCommandDeps): Promise<void> {
 	const { ctx } = deps;
+	let keep = backup;
 	if (!yes) {
 		if (!ctx.hasUI) throw new SpaceError(`Removing a space needs confirmation; run /space remove ${name} --yes.`);
 		// Fail before asking when the space cannot be removed anyway.
@@ -79,10 +109,18 @@ async function remove(name: string, yes: boolean, deps: SpaceCommandDeps): Promi
 			`Remove space "${name}"?`,
 			`This deletes ${join(deps.dir, name)} and everything in it: sign-ins, packages, settings and sessions.`,
 		);
-		if (!ok) {
+		const choice = ok && backup ? await ctx.ui.select(`Keep a backup of "${name}" in ${join(deps.dir, BACKUPS)}?`, [KEEP_BACKUP, NO_BACKUP]) : undefined;
+		// Dismissing the backup question is not an answer to it, so nothing is removed.
+		if (!ok || (backup && choice === undefined)) {
 			ctx.ui.notify(`Kept space "${name}".`, "info");
 			return;
 		}
+		keep = backup && choice === KEEP_BACKUP;
+	}
+	if (keep) {
+		const path = backupSpace(deps.dir, name, deps.currentHome(), protectedHomes(deps));
+		ctx.ui.notify(`Removed space "${name}"; its backup is ${path}.`, "info");
+		return;
 	}
 	removeSpace(deps.dir, name, deps.currentHome(), protectedHomes(deps));
 	ctx.ui.notify(`Removed space "${name}".`, "info");

package/src/spaces.ts

@@ -149,6 +149,48 @@ export function removeSpace(dir: string, name: string, agentHome: string, protec
 	rmSync(checkRemovable(dir, name, agentHome, protect, userHome), { recursive: true, force: true });
 }
 
+/** The folder inside the spaces folder that holds removed spaces; its leading dot keeps it from being a space. */
+export const BACKUPS = ".backups";
+
+/**
+ * Removes a space by moving it to <spaces folder>/.backups/<name>-<UTC time>, after checkRemovable.
+ * Returns the backup's path. A second backup in the same second gets a number; nothing is overwritten.
+ */
+export function backupSpace(
+	dir: string,
+	name: string,
+	agentHome: string,
+	protect: string[] = [],
+	userHome: string = osHomedir(),
+	now: Date = new Date(),
+): string {
+	const from = checkRemovable(dir, name, agentHome, protect, userHome);
+	const folder = join(dir, BACKUPS);
+	if ((existsSync(folder) || isSymlink(folder)) && !isRealFolder(folder)) {
+		throw new SpaceError(`The backups folder ${folder} is not a folder; move it away and try again.`);
+	}
+	try {
+		mkdirSync(folder, { recursive: true });
+	} catch (error) {
+		throw backupFailed(name, error);
+	}
+	const stamp = `${now.toISOString().slice(0, 19).replaceAll(":", "-")}Z`;
+	let to = join(folder, `${name}-${stamp}`);
+	for (let n = 2; existsSync(to) || isSymlink(to); n++) to = join(folder, `${name}-${stamp}-${n}`);
+	// Inside the spaces folder, so the same filesystem: a rename, never a copy.
+	try {
+		renameSync(from, to);
+	} catch (error) {
+		throw backupFailed(name, error);
+	}
+	return to;
+}
+
+function backupFailed(name: string, error: unknown): SpaceError {
+	const reason = error instanceof Error ? error.message : String(error);
+	return new SpaceError(`Could not back up space "${name}": ${reason}. The space was not removed; fix that, or remove it without a backup with --no-backup.`);
+}
+
 /** Renames a space after the same safety checks as removal. The new name must be free. */
 export function renameSpace(dir: string, oldName: string, newName: string, agentHome: string, protect: string[] = [], userHome: string = osHomedir()): void {
 	assertName(oldName);
@@ -174,22 +216,39 @@ function gitRepoName(source: string): string {
 	return withoutRef.replace(/\.git$/, "").split(/[/:]/).pop() ?? "";
 }
 
+/** The name in a local package folder's package.json, or undefined when there is none. */
+function localPackageName(folder: string): string | undefined {
+	try {
+		const name = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"))?.name;
+		return typeof name === "string" ? name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 function samePath(a: string, b: string): boolean {
 	return realOrResolved(a) === realOrResolved(b);
 }
 
 /**
  * This package's declaration in the current home's settings.json, so a new space loads it the same way.
- * A local path is made absolute. Without a match (for example when loaded with -e), the package folder itself.
+ * A local path matches when it is the package folder or another folder whose package.json has this package's name,
+ * and is made absolute. Without a match (for example when loaded with -e), the fallback, which is the package folder itself
+ * unless given. An empty packageRoot (unknown folder) matches a local path only by its package.json name.
  */
-export function findOwnDeclaration(agentHome: string, packageName: string, packageRoot: string): PackageDeclaration {
+export function findOwnDeclaration(
+	agentHome: string,
+	packageName: string,
+	packageRoot: string,
+	fallback: PackageDeclaration = packageRoot,
+): PackageDeclaration {
 	let packages: unknown;
 	try {
 		packages = JSON.parse(readFileSync(join(agentHome, "settings.json"), "utf8"))?.packages;
 	} catch {
-		return packageRoot;
+		return fallback;
 	}
-	if (!Array.isArray(packages)) return packageRoot;
+	if (!Array.isArray(packages)) return fallback;
 	const repo = packageName.split("/").pop() ?? packageName;
 	for (const entry of packages) {
 		const source = typeof entry === "string" ? entry : typeof entry?.source === "string" ? entry.source : undefined;
@@ -199,11 +258,11 @@ export function findOwnDeclaration(agentHome: string, packageName: string, packa
 			if (npmName(source) === packageName) match = source;
 		} else if (isLocalSource(source)) {
 			const absolute = isAbsolute(source) ? source : resolve(agentHome, expandTilde(source, osHomedir()));
-			if (samePath(absolute, packageRoot)) match = absolute;
+			if ((packageRoot !== "" && samePath(absolute, packageRoot)) || localPackageName(absolute) === packageName) match = absolute;
 		} else if (gitRepoName(source) === repo) {
 			match = source;
 		}
 		if (match !== undefined) return typeof entry === "string" ? match : { ...entry, source: match };
 	}
-	return packageRoot;
+	return fallback;
 }