@jals1212/pi-spaces 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 0.5.0
+
+### Added
+
+- `/space new` names `pi-space setup <name>` when `PI_SPACES_SETUP` holds a
+  setup command, so a space a program needs prepared is not entered bare.
+
+### Changed
+
+- `setup` is a reserved name, as the other command words are. A space already
+  named `setup` is no longer listed; rename its folder by hand.
+
+## 0.4.1
+
+### Changed
+
+- The status line shows `◆ base` in the base home when pi-spaces opened it
+  (`pi --space base`, `pi-space base`, or a switch back to base); Pi started
+  plainly still shows nothing there.
+
 ## 0.4.0
 
 ### Added

package/README.md

@@ -59,7 +59,7 @@ A new space starts empty except for a `settings.json` that declares this package
 | --- | --- |
 | `/space` | Opens a list of the other spaces and restarts Pi in the one you pick. Without the interactive terminal it lists them instead. |
 | `/space list` | Lists `base` and every space, with `*` on the active one. |
-| `/space new <name>` | Creates an empty space. |
+| `/space new <name>` | Creates an empty space. When a setup command is set (`PI_SPACES_SETUP`), it names `pi-space setup <name>` to run from a shell. |
 | `/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. |
@@ -67,15 +67,15 @@ A new space starts empty except for a `settings.json` that declares this package
 | `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.
+The status line shows `◆ <name>` while a space is active. In the base home it shows `◆ base` when pi-spaces opened it (`pi --space base`, `pi-space base`, or `/space switch base`), and nothing when Pi was started plainly.
 
 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, and so are the command words `list`, `new`, `remove`, `rename`, `switch`, `update`, `install` and `uninstall`.
+**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`, `uninstall` and `setup`.
 
 ## 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 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.
+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, and `--setup` (or `PI_SPACES_SETUP`) gives that program's command to prepare a new space: `pi-space new` runs it, and `pi-space setup <name|--every>` runs it again. 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
 
@@ -91,6 +91,7 @@ Read:
 | --- | --- |
 | `PI_SPACES_DIR` | The spaces folder. A relative value is taken from your home folder. Default: `spaces` next to the base home. |
 | `PI_SPACES_COMMAND` | For the `pi-space` command ([`cli/README.md`](cli/README.md)): the program to run, before `--space <name>`. Default: `pi`. |
+| `PI_SPACES_SETUP` | For the `pi-space` command: the command that prepares a new space. `/space new` names `pi-space setup <name>` when it is set. |
 | `PI_CODING_AGENT_DIR` | Pi's agent home; its parent holds the default spaces folder. Default: `~/.pi/agent`. |
 
 Set for the Pi a switch starts:

package/dist/command.js

@@ -1,6 +1,6 @@
 // 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 {               parseSpaceFlag, relaunchEnv, resolveSwitch } from "./relaunch.js";
 import {
 	activeSpace,
 	BACKUPS,
@@ -9,6 +9,7 @@ import {
 	checkRemovable,
 	createSpace,
 	         
+	hasSetupCommand,
 	listSpaces,
 	                        
 	removeSpace,
@@ -55,7 +56,13 @@ export async function runSpaceCommand(args        , deps                  )
 		if (sub === "list" && rest.length === 0) return list(deps);
 		if (sub === "new" && rest.length === 1) {
 			const path = createSpace(deps.dir, rest[0], deps.declaration());
-			ctx.ui.notify(`Created space "${rest[0]}" at ${path}. Enter it with /space switch ${rest[0]}.`, "info");
+			const name = rest[0];
+			ctx.ui.notify(
+				hasSetupCommand(deps.env)
+					? `Created space "${name}" at ${path}. Prepare it from a shell with: pi-space setup ${name}. Then enter it with /space switch ${name}.`
+					: `Created space "${name}" at ${path}. Enter it with /space switch ${name}.`,
+				"info",
+			);
 			return;
 		}
 		const removal = sub === "remove" ? parseRemove(rest) : undefined;
@@ -154,10 +161,17 @@ function switchTo(name        , deps                  )       {
 	ctx.shutdown();
 }
 
-/** Status line text: the active space, or nothing in the base home. */
-export function statusText(dir        , currentHome        )                     {
+/**
+ * Status line text: the active space; in the base home, `◆ base` only when pi-spaces opened it
+ * (`pi --space base`, which `pi-space base` runs, or a switch back to base, which sets
+ * PI_SPACES_BASE_HOME), and nothing when Pi was started plainly.
+ */
+export function statusText(dir        , currentHome        , proc                     = process, env      = process.env)                     {
 	const active = activeSpace(dir, currentHome);
-	return active === undefined ? undefined : `◆ ${active}`;
+	if (active !== undefined) return `◆ ${active}`;
+	const parsed = parseSpaceFlag(proc.argv.slice(2));
+	const openedBySpaces = ("name" in parsed && parsed.name === BASE) || Boolean(env.PI_SPACES_BASE_HOME);
+	return openedBySpaces ? `◆ ${BASE}` : undefined;
 }
 
 export function completeSpaceArgs(prefix        , dir        )                                            {

package/dist/spaces.js

@@ -38,7 +38,12 @@ export function spacesDir(env      = process.env, home         = osHomedir())
 }
 
 // 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"]);
+const COMMANDS = new Set(["list", "new", "remove", "rename", "switch", "update", "install", "uninstall", "setup"]);
+
+/** True when PI_SPACES_SETUP holds a setup command, not just blanks. */
+export function hasSetupCommand(env     )          {
+	return (env.PI_SPACES_SETUP ?? "").trim() !== "";
+}
 
 /** Returns the error message for an unusable name, or undefined when the name is valid. */
 export function validateName(name        )                     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/pi-spaces",
-  "version": "0.4.0",
+  "version": "0.5.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, 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."
+description: "Trigger: pi-spaces, space, spaces, /space, pi-space, pi --space, PI_SPACE, PI_SPACE_HOME, PI_SPACES_COMMAND, PI_SPACES_SETUP, which space, agent home, base home, update, install, uninstall, setup. Know which Pi space this session runs in, its home and start command, and how spaces and their packages are listed, created, set up, updated, switched and removed."
 license: MIT
 metadata:
   author: jals1212
@@ -27,12 +27,13 @@ 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>`; `pi-space new` also runs the setup command when there is one (`--setup <cmd>` or `PI_SPACES_SETUP`) |
+| Prepare a space for the program that runs Pi | `pi-space setup <name|--every>`: runs the setup command (`{home}` and `{name}` become the space's folder and name) with the space as `PI_CODING_AGENT_DIR`; never in base |
 | 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` |
 | 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` (the base home) and the command words (`list`, `new`, `remove`, `rename`, `switch`, `update`, `install`, `uninstall`) are reserved.
+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`, `setup`) are reserved.
 
 ## Execution Steps
 

package/src/command.ts

@@ -1,6 +1,6 @@
 // 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 { type Command, parseSpaceFlag, relaunchEnv, resolveSwitch } from "./relaunch.ts";
 import {
 	activeSpace,
 	BACKUPS,
@@ -9,6 +9,7 @@ import {
 	checkRemovable,
 	createSpace,
 	type Env,
+	hasSetupCommand,
 	listSpaces,
 	type PackageDeclaration,
 	removeSpace,
@@ -55,7 +56,13 @@ export async function runSpaceCommand(args: string, deps: SpaceCommandDeps): Pro
 		if (sub === "list" && rest.length === 0) return list(deps);
 		if (sub === "new" && rest.length === 1) {
 			const path = createSpace(deps.dir, rest[0], deps.declaration());
-			ctx.ui.notify(`Created space "${rest[0]}" at ${path}. Enter it with /space switch ${rest[0]}.`, "info");
+			const name = rest[0];
+			ctx.ui.notify(
+				hasSetupCommand(deps.env)
+					? `Created space "${name}" at ${path}. Prepare it from a shell with: pi-space setup ${name}. Then enter it with /space switch ${name}.`
+					: `Created space "${name}" at ${path}. Enter it with /space switch ${name}.`,
+				"info",
+			);
 			return;
 		}
 		const removal = sub === "remove" ? parseRemove(rest) : undefined;
@@ -154,10 +161,17 @@ function switchTo(name: string, deps: SpaceCommandDeps): void {
 	ctx.shutdown();
 }
 
-/** Status line text: the active space, or nothing in the base home. */
-export function statusText(dir: string, currentHome: string): string | undefined {
+/**
+ * Status line text: the active space; in the base home, `◆ base` only when pi-spaces opened it
+ * (`pi --space base`, which `pi-space base` runs, or a switch back to base, which sets
+ * PI_SPACES_BASE_HOME), and nothing when Pi was started plainly.
+ */
+export function statusText(dir: string, currentHome: string, proc: { argv: string[] } = process, env: Env = process.env): string | undefined {
 	const active = activeSpace(dir, currentHome);
-	return active === undefined ? undefined : `◆ ${active}`;
+	if (active !== undefined) return `◆ ${active}`;
+	const parsed = parseSpaceFlag(proc.argv.slice(2));
+	const openedBySpaces = ("name" in parsed && parsed.name === BASE) || Boolean(env.PI_SPACES_BASE_HOME);
+	return openedBySpaces ? `◆ ${BASE}` : undefined;
 }
 
 export function completeSpaceArgs(prefix: string, dir: string): { value: string; label: string }[] | null {

package/src/spaces.ts

@@ -38,7 +38,12 @@ export function spacesDir(env: Env = process.env, home: string = osHomedir()): s
 }
 
 // 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"]);
+const COMMANDS = new Set(["list", "new", "remove", "rename", "switch", "update", "install", "uninstall", "setup"]);
+
+/** True when PI_SPACES_SETUP holds a setup command, not just blanks. */
+export function hasSetupCommand(env: Env): boolean {
+	return (env.PI_SPACES_SETUP ?? "").trim() !== "";
+}
 
 /** Returns the error message for an unusable name, or undefined when the name is valid. */
 export function validateName(name: string): string | undefined {