@jals1212/pi-spaces 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 0.4.0
+
+### Added
+
+- `pi --space <name> <command> [args...]` runs one of Pi's package commands
+  (`install`, `remove`, `uninstall`, `update`, `list`) in a space, or in the
+  base home with `base`, through the same Pi: `pi --space work update
+  --extensions`. Options before `--space`, such as a launcher's own `-e`, are
+  left out, since Pi runs a package command only as its first argument.
+
+### Changed
+
+- The command words `list`, `new`, `remove`, `rename`, `switch`, `update`,
+  `install` and `uninstall` are reserved and can no longer name a space, so
+  `pi-space <name>` never reads as a command. A folder with such a name in the
+  spaces folder is no longer listed as a space.
+
 ## 0.3.0
 
 ### Added

package/README.md

@@ -45,8 +45,9 @@ 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 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 update --every                 # update the packages of base and of every space (optional CLI)
 pi-space                                # pick from a numbered list (optional CLI)
 ```
 
@@ -64,16 +65,17 @@ A new space starts empty except for a `settings.json` that declares this package
 | `/space rename <old> <new>` | Renames a space. The active space cannot be renamed. |
 | `/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. |
+| `pi --space <name> <command> [args...]` | Runs one of Pi's package commands (`install`, `remove`, `uninstall`, `update`, `list`) in a space, or in the base home with `base`: `pi --space work update --extensions`, `pi --space work install npm:<package>`. |
 
 The status line shows `◆ <name>` while a space is active, and nothing in the base home.
 
 Choosing an argument such as `switch` from the `/space ` suggestions only fills the line; press Enter again to run it. `/space` and Enter opens the picker in one step.
 
-**Names**: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters. `base` is reserved.
+**Names**: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters. `base` is reserved, and so are the command words `list`, `new`, `remove`, `rename`, `switch`, `update`, `install` and `uninstall`.
 
 ## 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, `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.
+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 rename <old> <new>` renames one, `pi-space remove <name>` deletes one, and `pi-space list` lists them. `pi-space list|update|install|uninstall <name|--every> ...` runs Pi's package commands in a space, or in every space. `--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> [command]`, 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
 
@@ -135,13 +137,15 @@ Pi reads its agent home once, when it starts, so a running session cannot move t
 
 `pi --space <name>` acts before Pi opens its interface or runs anything, so it keeps the prompt and the session options too, in every mode.
 
+`pi --space <name> <command> ...`, where `<command>` is one of Pi's package commands right after the name, runs Pi again in that home with only `<command> ...`: Pi runs a package command only as its first argument. Options before `--space`, such as a launcher's own `-e`, are left out. The same Pi runs it, so a launcher's own Pi manages the space's packages; `base` and the current home work too.
+
 ## 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 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`, `/space rename` and `pi-space --remove` refuse, before they ask:
+`/space remove`, `/space rename`, `pi-space remove` and `pi-space rename` refuse, before they ask:
 
 - `base` and the active space;
 - symlinks, and anything that is not a real folder directly inside the spaces folder;

package/dist/relaunch.js

@@ -123,10 +123,14 @@ export function relaunchCommand(proc       = process, args           = filterArg
 
 const SPACE_FLAG_ERROR = "--space needs a space name: pi --space <name>.";
 
-/** Finds --space <name> or --space=<name> before "--", and returns the other arguments unchanged. */
-export function parseSpaceFlag(args          )                                                                   {
+/**
+ * Finds --space <name> or --space=<name> before "--", and returns the other arguments unchanged,
+ * and the arguments that follow the name.
+ */
+export function parseSpaceFlag(args          )                                                                                        {
 	const rest           = [];
 	let name                    ;
+	let afterName           = [];
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === "--") {
@@ -138,36 +142,48 @@ export function parseSpaceFlag(args          )
 			if (value === undefined || value === "" || value.startsWith("-")) return { error: SPACE_FLAG_ERROR };
 			name = value;
 			i++;
+			afterName = args.slice(i + 1);
 		} else if (arg.startsWith("--space=")) {
 			name = arg.slice("--space=".length);
 			if (name === "") return { error: SPACE_FLAG_ERROR };
+			afterName = args.slice(i + 1);
 		} else {
 			rest.push(arg);
 		}
 	}
-	return { name, rest };
+	return { name, rest, afterName };
 }
 
+// Pi runs these only as its first argument, before extensions load.
+const PACKAGE_COMMANDS = new Set(["install", "remove", "uninstall", "update", "list"]);
+
                                                                                                                                    
 
 /**
  * What `pi --space <name>` does at startup: nothing without the flag or when Pi already runs in that
  * space; otherwise run Pi again in the space with every other argument, since nothing has run yet.
+ * `pi --space <name> <package command> ...` always runs Pi again, even in the current home, because
+ * Pi runs a package command (install, remove, uninstall, update, list) only as its first argument.
  */
 export function planStartup(input                                                            )              {
 	const { proc, dir, currentHome, env } = input;
 	const parsed = parseSpaceFlag(proc.argv.slice(2));
 	if ("error" in parsed) return { kind: "error", message: parsed.error };
 	if (parsed.name === undefined) return { kind: "none" };
+	// A package command runs alone: options before --space (a launcher may add its own) are for a session.
+	const packageCommand = PACKAGE_COMMANDS.has(parsed.afterName[0] ?? "");
+	const args = packageCommand ? parsed.afterName : parsed.rest;
 	let target              ;
 	try {
 		target = resolveSwitch({ dir, name: parsed.name, currentHome, env });
 	} catch (error) {
 		if (!(error instanceof SpaceError)) throw error;
-		if (error.message.startsWith("Already in")) return { kind: "none" };
+		if (error.message.startsWith("Already in")) {
+			return packageCommand ? { kind: "relaunch", command: relaunchCommand(proc, args), env } : { kind: "none" };
+		}
 		return { kind: "error", message: error.message };
 	}
-	return { kind: "relaunch", command: relaunchCommand(proc, parsed.rest), env: relaunchEnv(env, { ...target, currentHome }) };
+	return { kind: "relaunch", command: relaunchCommand(proc, args), env: relaunchEnv(env, { ...target, currentHome }) };
 }
 
 /** Runs the command now with inherited stdio and returns its exit code (1 when it cannot start). */

package/dist/spaces.js

@@ -37,9 +37,13 @@ export function spacesDir(env      = process.env, home         = osHomedir())
 	return join(dirname(resolve(baseHome)), "spaces");
 }
 
+// The words of the pi-space and /space commands, so a space name never reads as one.
+const COMMANDS = new Set(["list", "new", "remove", "rename", "switch", "update", "install", "uninstall"]);
+
 /** Returns the error message for an unusable name, or undefined when the name is valid. */
 export function validateName(name        )                     {
 	if (name === BASE) return `"${BASE}" is reserved for the home Pi started with.`;
+	if (COMMANDS.has(name)) return `"${name}" is reserved: it is a pi-space or /space command.`;
 	if (!NAME.test(name)) {
 		return `Invalid space name "${name}": use lowercase letters, digits, "-" and "_", starting with a letter or digit (at most 64 characters).`;
 	}

package/package.json

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

package/skills/pi-spaces/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-spaces
-description: "Trigger: pi-spaces, space, spaces, /space, pi-space, pi --space, PI_SPACE, PI_SPACE_HOME, PI_SPACES_COMMAND, which space, agent home, base home. Know which Pi space this session runs in, its home and start command, and how spaces are listed, created, switched and removed."
+description: "Trigger: pi-spaces, space, spaces, /space, pi-space, pi --space, PI_SPACE, PI_SPACE_HOME, PI_SPACES_COMMAND, which space, agent home, base home, update, install, uninstall. Know which Pi space this session runs in, its home and start command, and how spaces and their packages are listed, created, updated, switched and removed."
 license: MIT
 metadata:
   author: jals1212
@@ -27,11 +27,12 @@ Use when a task depends on which Pi agent home this session uses (settings, sign
 | Which space, home, command | `<pi_space>` section, or `echo "$PI_SPACE|$PI_SPACE_HOME|$PI_SPACES_COMMAND"` |
 | List spaces from a shell | `pi-space list` (optional `@jals1212/pi-spaces-cli`) |
 | Spaces folder | `PI_SPACES_DIR`, else `spaces` next to the base home (`PI_SPACES_BASE_HOME`, else this home) |
-| Create a space | `pi-space --new <name>`, or ask the user for `/space new <name>` |
+| Create a space | `pi-space new <name>`, or ask the user for `/space new <name>` |
 | Work in another space | User runs `/space switch <name>`, or `$PI_SPACES_COMMAND --space <name> "<prompt>"` |
-| Remove a space | User request only: `pi-space --remove <name> --yes` keeps a backup in `.backups` |
+| Remove a space | User request only: `pi-space remove <name> --yes` keeps a backup in `.backups` |
+| Packages of a space | `pi-space update <name|base|--every> --extensions`, `pi-space install <name> <source>`, `pi-space uninstall <name> <source>`, `pi-space list <name>`; without the CLI, `$PI_SPACES_COMMAND --space <name|base> update --extensions` |
 
-Names: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters; `base` is reserved for the base home.
+Names: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters; `base` (the base home) and the command words (`list`, `new`, `remove`, `rename`, `switch`, `update`, `install`, `uninstall`) are reserved.
 
 ## Execution Steps
 

package/src/relaunch.ts

@@ -123,10 +123,14 @@ export function relaunchCommand(proc: Proc = process, args: string[] = filterArg
 
 const SPACE_FLAG_ERROR = "--space needs a space name: pi --space <name>.";
 
-/** Finds --space <name> or --space=<name> before "--", and returns the other arguments unchanged. */
-export function parseSpaceFlag(args: string[]): { name: string | undefined; rest: string[] } | { error: string } {
+/**
+ * Finds --space <name> or --space=<name> before "--", and returns the other arguments unchanged,
+ * and the arguments that follow the name.
+ */
+export function parseSpaceFlag(args: string[]): { name: string | undefined; rest: string[]; afterName: string[] } | { error: string } {
 	const rest: string[] = [];
 	let name: string | undefined;
+	let afterName: string[] = [];
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === "--") {
@@ -138,36 +142,48 @@ export function parseSpaceFlag(args: string[]): { name: string | undefined; rest
 			if (value === undefined || value === "" || value.startsWith("-")) return { error: SPACE_FLAG_ERROR };
 			name = value;
 			i++;
+			afterName = args.slice(i + 1);
 		} else if (arg.startsWith("--space=")) {
 			name = arg.slice("--space=".length);
 			if (name === "") return { error: SPACE_FLAG_ERROR };
+			afterName = args.slice(i + 1);
 		} else {
 			rest.push(arg);
 		}
 	}
-	return { name, rest };
+	return { name, rest, afterName };
 }
 
+// Pi runs these only as its first argument, before extensions load.
+const PACKAGE_COMMANDS = new Set(["install", "remove", "uninstall", "update", "list"]);
+
 export type StartupPlan = { kind: "none" } | { kind: "error"; message: string } | { kind: "relaunch"; command: Command; env: Env };
 
 /**
  * What `pi --space <name>` does at startup: nothing without the flag or when Pi already runs in that
  * space; otherwise run Pi again in the space with every other argument, since nothing has run yet.
+ * `pi --space <name> <package command> ...` always runs Pi again, even in the current home, because
+ * Pi runs a package command (install, remove, uninstall, update, list) only as its first argument.
  */
 export function planStartup(input: { proc: Proc; dir: string; currentHome: string; env: Env }): StartupPlan {
 	const { proc, dir, currentHome, env } = input;
 	const parsed = parseSpaceFlag(proc.argv.slice(2));
 	if ("error" in parsed) return { kind: "error", message: parsed.error };
 	if (parsed.name === undefined) return { kind: "none" };
+	// A package command runs alone: options before --space (a launcher may add its own) are for a session.
+	const packageCommand = PACKAGE_COMMANDS.has(parsed.afterName[0] ?? "");
+	const args = packageCommand ? parsed.afterName : parsed.rest;
 	let target: SwitchTarget;
 	try {
 		target = resolveSwitch({ dir, name: parsed.name, currentHome, env });
 	} catch (error) {
 		if (!(error instanceof SpaceError)) throw error;
-		if (error.message.startsWith("Already in")) return { kind: "none" };
+		if (error.message.startsWith("Already in")) {
+			return packageCommand ? { kind: "relaunch", command: relaunchCommand(proc, args), env } : { kind: "none" };
+		}
 		return { kind: "error", message: error.message };
 	}
-	return { kind: "relaunch", command: relaunchCommand(proc, parsed.rest), env: relaunchEnv(env, { ...target, currentHome }) };
+	return { kind: "relaunch", command: relaunchCommand(proc, args), env: relaunchEnv(env, { ...target, currentHome }) };
 }
 
 /** Runs the command now with inherited stdio and returns its exit code (1 when it cannot start). */

package/src/spaces.ts

@@ -37,9 +37,13 @@ export function spacesDir(env: Env = process.env, home: string = osHomedir()): s
 	return join(dirname(resolve(baseHome)), "spaces");
 }
 
+// The words of the pi-space and /space commands, so a space name never reads as one.
+const COMMANDS = new Set(["list", "new", "remove", "rename", "switch", "update", "install", "uninstall"]);
+
 /** Returns the error message for an unusable name, or undefined when the name is valid. */
 export function validateName(name: string): string | undefined {
 	if (name === BASE) return `"${BASE}" is reserved for the home Pi started with.`;
+	if (COMMANDS.has(name)) return `"${name}" is reserved: it is a pi-space or /space command.`;
 	if (!NAME.test(name)) {
 		return `Invalid space name "${name}": use lowercase letters, digits, "-" and "_", starting with a letter or digit (at most 64 characters).`;
 	}