@jals1212/pi-spaces 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 0.7.0
+
+### Changed
+
+- The setup hint of `/space new` names the space with its profile, as
+  `pi-space` now requires: `pi-space setup <profile>/<name>`, where the
+  profile is the one of the running Pi (`pi` when no profile matches its base
+  home). `/space` itself still takes the bare name.
+
+### Fixed
+
+- The built-in `pi` profile no longer takes another profile's home: inside
+  the Pi of a program whose profile names its `home`, `PI_CODING_AGENT_DIR`
+  holds that home, and `pi` now keeps `~/.pi/agent` (its spaces in
+  `~/.pi/spaces`) instead of pointing at that program's home and spaces.
+
 ## 0.6.0
 
 ### Added

package/README.md

@@ -45,10 +45,10 @@ 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 update --every                 # update the packages of base and of every space (optional CLI)
-pi-space                                # pick from a numbered list (optional CLI)
+pi-space new pi/work                    # create a space of the profile "pi" (optional CLI)
+pi-space remove pi/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 of every profile (optional CLI)
+pi-space                                # pick a space of any profile: arrows, Enter, type to filter (optional CLI)
 ```
 
 A new space starts empty except for a `settings.json` that declares this package, so `/space` works inside it. Sign in and install packages there as you would in a fresh Pi.
@@ -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. When a setup command is set (`PI_SPACES_SETUP`), it names `pi-space setup <name>` to run from a shell. |
+| `/space new <name>` | Creates an empty space. When a setup command is set (the profile's `setup`, or `PI_SPACES_SETUP`), it names `pi-space setup <profile>/<name>` to run from a shell, with this Pi's profile (`pi` when none matches). |
 | `/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,7 +67,7 @@ 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. 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.
+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 pi/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.
 
@@ -75,13 +75,13 @@ 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, `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.
+The optional `@jals1212/pi-spaces-cli` package adds a `pi-space` command to your shell. It names every space as `<profile>/<name>` (`pi/work`, `my/base`): the profile is an entry of the [config file](#profiles), and `pi` (plain Pi) is always there. `pi-space` opens a picker of the spaces of every profile and starts Pi in the one you choose, `pi-space <profile>/<name> [pi args...]` starts Pi in a named space, `pi-space new <profile>/<name>` creates one, `pi-space rename <profile>/<old> <new>` renames one, `pi-space remove <profile>/<name>` deletes one, and `pi-space list` lists every profile's spaces. `pi-space list|update|install|uninstall <profile>/<name|--every> ...` runs Pi's package commands in a space, in a profile's spaces, or (`--every` alone) in every profile's. The profile says which program to run, where its spaces live and how to prepare a new space; `--command`, `--dir` and `--setup` override those for one call, for one named profile. `pi-space setup <profile>/<name|--every>` runs the setup command again. The command does not read `PI_SPACES_COMMAND`, `PI_SPACES_DIR` or `PI_SPACES_SETUP` as settings: they are what it hands to the Pi it starts. 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.
 
 ## Profiles
 
 A **profile** describes one program that runs Pi (plain Pi is one too): where its agent home is, the command that starts it, where its spaces live, how to prepare a new space, and the variables it needs per space. Profiles live in an optional JSON file, so you do not need shell variables or functions to tell pi-spaces about a program. Without the file, nothing changes: this is exactly how pi-spaces behaves without any configuration.
 
-The extension uses the profile whose `home` is the base home Pi started with (the one `base` goes back to); inside a space that is the home the space came from. The optional `pi-space` command ([`cli/README.md`](cli/README.md)) reads the same file and adds `--profile <name>` to pick a profile.
+The extension uses the profile whose `home` is the base home Pi started with (the one `base` goes back to); inside a space that is the home the space came from. The optional `pi-space` command ([`cli/README.md`](cli/README.md)) reads the same file, and the profile is the first word of every space it takes: `pi-space ml/work`. It does not use `default`: the profile is always named.
 
 ### The file
 
@@ -97,7 +97,6 @@ A complete example for a program called `my-launcher`, which keeps its own confi
 ```json
 {
   "schema": "pi-spaces.config/v1",
-  "default": "ml",
   "profiles": {
     "ml": {
       "home": "~/.my-launcher/agent",
@@ -109,7 +108,7 @@ A complete example for a program called `my-launcher`, which keeps its own confi
 }
 ```
 
-With that file, a space of `my-launcher` lives in `~/.my-launcher/spaces/<name>`, `/space new <name>` points you at `pi-space setup <name>`, and entering the space `work` starts Pi with `MY_LAUNCHER_CONFIG_HOME=~/.my-launcher/spaces/work/config`, while the base home gets no such variable from pi-spaces. An abbreviation or alias is optional sugar on top, for example `abbr -a ml 'pi-space --profile ml'` in fish or `alias ml='pi-space --profile ml'` in a POSIX shell.
+With that file, a space of `my-launcher` lives in `~/.my-launcher/spaces/<name>`, `/space new <name>` points you at `pi-space setup ml/<name>`, and entering the space `work` starts Pi with `MY_LAUNCHER_CONFIG_HOME=~/.my-launcher/spaces/work/config`, while the base home gets no such variable from pi-spaces. From a shell, `pi-space ml/work` starts that space, and an alias such as `alias mlw='pi-space ml/work'` is optional sugar on top.
 
 ### Schema `pi-spaces.config/v1`
 
@@ -118,7 +117,7 @@ Top level (every other key is refused):
 | Key | Type | Required | Meaning |
 | --- | --- | --- | --- |
 | `schema` | string | yes | Exactly `"pi-spaces.config/v1"`. |
-| `default` | string | no | The profile to use when none is asked for: a profile of the file, or `pi`. Without it, the built-in `pi` profile. |
+| `default` | string | no | Accepted and validated (it must name a profile of the file, or `pi`), but not used: neither the extension nor `pi-space` falls back to it. `pi-space` warns when it reads a file that has it; remove the key. |
 | `profiles` | object | no | Profiles by name. Names: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters. |
 
 A profile (every other key is refused; every key is optional):
@@ -128,7 +127,7 @@ A profile (every other key is refused; every key is optional):
 | `home` | string, not empty | `PI_CODING_AGENT_DIR`, else `~/.pi/agent` | The base agent home of the program: the home it starts Pi with, which `base` goes back to. `~` is your home folder; a relative path is taken from it. |
 | `command` | string, not empty | `pi` for the profile `pi`; none for the others | The command that starts the program (`my-launcher --`), in front of `--space <name>`. |
 | `dir` | string, not empty | `spaces` next to `home` (`~/.my-launcher/agent` gives `~/.my-launcher/spaces`) | The folder that holds the profile's spaces. `~` and relative paths as in `home`. |
-| `setup` | string, not empty | none | The command that prepares a new space; `{home}` and `{name}` become the space's folder and name. With it, `/space new` names `pi-space setup <name>`. |
+| `setup` | string, not empty | none | The command that prepares a new space; `{home}` and `{name}` become the space's folder and name. With it, `/space new` names `pi-space setup <profile>/<name>`. |
 | `spaceEnv` | object of strings | none | Variables that exist only in spaces; see below. Names: letters, digits and `_`, not starting with a digit; not `PI_CODING_AGENT_DIR`, `PI_SPACE`, `PI_SPACE_HOME` or any `PI_SPACES_*`, which pi-spaces sets itself. |
 
 All strings are trimmed. `{home}` and `{name}` are replaced everywhere they appear in a `spaceEnv` value (and `setup`), and `$` in a value stays literal.
@@ -148,7 +147,11 @@ pi-spaces does not create what a variable points to; `setup` (or the program its
 
 ### The built-in `pi` profile
 
-Plain Pi is always a profile named `pi`: command `pi`, home `PI_CODING_AGENT_DIR` (else `~/.pi/agent`), no setup, no `spaceEnv`. Naming `pi` in `profiles` replaces it as a whole; what that entry leaves out still takes the defaults above for `home` and `command`, never anything from the old built-in's other fields.
+Plain Pi is always a profile named `pi`: command `pi`, no setup, no `spaceEnv`. Its home is `PI_SPACES_BASE_HOME` (set inside a space), else `PI_CODING_AGENT_DIR`, else `~/.pi/agent`.
+
+Inside another program's Pi those variables hold that program's home. When a profile of the file names that folder as its `home`, `pi` does not take it and uses `~/.pi/agent`, so `pi/<name>` is still plain Pi there.
+
+Naming `pi` in `profiles` replaces it as a whole; what that entry leaves out still takes the defaults above for `home` and `command`, never anything from the old built-in's other fields.
 
 ### Schema versions
 
@@ -162,7 +165,7 @@ Unknown keys, wrong types, bad names, a `default` that names no profile, an unre
 
 ### Where spaces live
 
-In a `spaces` folder next to the home Pi starts with: `~/.pi/agent` keeps its spaces in `~/.pi/spaces/<name>/`. A program that runs Pi with its own home gets its own folder too, for example `~/.tool/agent` → `~/.tool/spaces`. The folder stays the same while you switch between spaces. A [profile](#profiles)'s `dir` replaces it for that profile's home, and `PI_SPACES_DIR` replaces both.
+In a `spaces` folder next to the home Pi starts with: `~/.pi/agent` keeps its spaces in `~/.pi/spaces/<name>/`. A program that runs Pi with its own home gets its own folder too, for example `~/.tool/agent` → `~/.tool/spaces`. The folder stays the same while you switch between spaces. A [profile](#profiles)'s `dir` replaces it for that profile's home, and `PI_SPACES_DIR` replaces both. The `pi-space` command does not read `PI_SPACES_DIR` (or `PI_SPACES_COMMAND` and `PI_SPACES_SETUP`) as a setting: it takes the folder from the profile or `--dir`, and sets the variable for the Pi it starts.
 
 ### Environment variables
 
@@ -172,8 +175,8 @@ Read:
 | --- | --- |
 | `PI_SPACES_DIR` | The spaces folder. A relative value is taken from your home folder. Default: the matching profile's `dir`, else `spaces` next to the base home. |
 | `PI_SPACES_CONFIG` | The [config file](#profiles) with the profiles. A leading `~` is your home folder and a relative value is taken from it. Default: `~/.pi-spaces/config.json`. |
-| `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_SPACES_COMMAND` | The program that starts Pi (default `pi`): told to the model and exported (see below). A switch starts Pi again with the command line it already has, so this is information, not a setting. |
+| `PI_SPACES_SETUP` | The command that prepares a new space. `/space new` names `pi-space setup <profile>/<name>` when it is set. The `pi-space` command sets it for the Pi it starts, from the profile or `--setup`; it does not read it from your shell. |
 | `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:
@@ -191,7 +194,7 @@ Set in every Pi this extension runs in, even one started without a switch, for i
 | --- | --- |
 | `PI_SPACE` | The active space's name, unset in the base home: the same variable a switch sets. |
 | `PI_SPACE_HOME` | The agent home this Pi runs with: the space's folder, or the base home. |
-| `PI_SPACES_COMMAND` | Kept when it has a value; set to `pi` when it is unset or blank. |
+| `PI_SPACES_COMMAND` | Kept when it has a value; set to `pi` when it is unset or blank. The `pi-space` command sets it for the Pi it starts (the profile's `command`, or `--command`), and the extension reads it to tell the model and the tools how Pi was started (see below); `pi-space` itself does not read it from your shell. |
 
 ### What the model is told
 

package/dist/command.js

@@ -58,11 +58,13 @@ export async function runSpaceCommand(args        , deps                  )
 	try {
 		if (sub === "list" && rest.length === 0) return list(deps);
 		if (sub === "new" && rest.length === 1) {
-			const path = createSpace(deps.dir, rest[0], deps.declaration());
-			const name = rest[0];
+			const [name] = rest;
+			const path = createSpace(deps.dir, name, deps.declaration());
+			// pi-space names a space with its profile; without a matching profile this Pi is plain pi.
+			const qualified = `${deps.profile?.name ?? "pi"}/${name}`;
 			ctx.ui.notify(
 				hasSetupCommand(deps.env) || Boolean(deps.profile?.setup)
-					? `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}. Prepare it from a shell with: pi-space setup ${qualified}. Then enter it with /space switch ${name}.`
 					: `Created space "${name}" at ${path}. Enter it with /space switch ${name}.`,
 				"info",
 			);

package/dist/config.js

@@ -170,15 +170,21 @@ export function profileNames(config                    )           {
 	return names.includes(BUILT_IN) ? names : [...names, BUILT_IN];
 }
 
-/** The built-in pi home: the base home inside a space (PI_SPACES_BASE_HOME), else PI_CODING_AGENT_DIR, else ~/.pi/agent. */
-function builtInHome(env     , home        )         {
+/**
+ * The built-in pi home: the base home inside a space (PI_SPACES_BASE_HOME), else PI_CODING_AGENT_DIR, else ~/.pi/agent.
+ * A home that a profile of the file names is that profile's, not pi's: inside the Pi of another program those
+ * variables hold that program's home, so pi keeps ~/.pi/agent.
+ */
+function builtInHome(config                    , env     , home        )         {
 	const fromEnv = env.PI_SPACES_BASE_HOME || env.PI_CODING_AGENT_DIR;
-	return fromEnv ? resolve(home, expandTilde(fromEnv, home)) : join(home, ".pi", "agent");
+	const found = fromEnv ? resolve(home, expandTilde(fromEnv, home)) : undefined;
+	const claimed = (path        ) => config?.profiles.some((spec) => spec.home !== undefined && samePath(resolve(home, expandTilde(spec.home, home)), path));
+	return found !== undefined && !claimed(found) ? found : join(home, ".pi", "agent");
 }
 
 /** Resolves a profile; what a profile omits for `home` falls back to the built-in pi's, and `pi` also gets its `command`. */
-function resolveProfile(spec             , env     , home        )          {
-	const base = spec.home === undefined ? builtInHome(env, home) : resolve(home, expandTilde(spec.home, home));
+function resolveProfile(config                    , spec             , env     , home        )          {
+	const base = spec.home === undefined ? builtInHome(config, env, home) : resolve(home, expandTilde(spec.home, home));
 	const profile          = {
 		name: spec.name,
 		home: base,
@@ -195,7 +201,7 @@ function resolveProfile(spec             , env     , home        )          {
 export function profileByName(config                    , name        , env     , home        )          {
 	const spec = config?.profiles.find((profile) => profile.name === name) ?? (name === BUILT_IN ? { name } : undefined);
 	if (spec === undefined) throw new ConfigError(`Unknown profile "${name}"; known profiles: ${profileNames(config).join(", ")}.`);
-	return resolveProfile(spec, env, home);
+	return resolveProfile(config, spec, env, home);
 }
 
 /** The profile whose home is the base home (the same place, real paths compared): the first in file order, then built-in `pi`. */

package/dist/context.js

@@ -20,7 +20,7 @@ export function spaceInfo(dir        , agentHome        , env     )            {
 	return {
 		space: activeSpace(dir, agentHome),
 		home: resolve(agentHome),
-		// A blank value counts as unset, so the default is pi, as in the pi-space command.
+		// A blank value counts as unset, so the default is pi (pi-space leaves it unset for a profile without a command).
 		command: env.PI_SPACES_COMMAND?.trim() || "pi",
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/pi-spaces",
-  "version": "0.6.0",
+  "version": "0.7.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

@@ -4,7 +4,7 @@ description: "Trigger: pi-spaces, space, spaces, /space, pi-space, pi --space, P
 license: MIT
 metadata:
   author: jals1212
-  version: "1.1"
+  version: "1.3"
 ---
 
 ## Activation Contract
@@ -14,10 +14,13 @@ Use when a task depends on which Pi agent home this session uses (settings, sign
 ## Hard Rules
 
 - Read where you run from the `<pi_space>` system prompt section; in a shell, from `PI_SPACE` (unset in the base home), `PI_SPACE_HOME` (this Pi's agent home) and `PI_SPACES_COMMAND` (the program that starts Pi, default `pi`). Never guess from `~/.pi/agent`.
+- The `pi-space` CLI names every space `<profile>/<name>` (`base` included, as `<profile>/base`); a bare name is refused. Nothing in the environment or the `<pi_space>` section names your own profile. To find it, take your base home (`PI_SPACES_BASE_HOME` when set, else `PI_SPACE_HOME`) and look in the config file for the profile whose `home` is that folder; no match means the built-in `pi`.
 - Files of this session's home (`settings.json`, `extensions/`, `sessions/`, installed packages) live under `PI_SPACE_HOME`; `pi install` and settings changes apply to this space only.
+- The config's `default` is not used by `pi-space` (it warns and ignores it); the profile is always named. `pi-space` does not read `PI_SPACES_COMMAND`, `PI_SPACES_DIR` or `PI_SPACES_SETUP` from the shell: a profile or `--command`, `--dir`, `--setup` (for one named profile) gives them.
 - Profiles live in `~/.pi-spaces/config.json`, or the file in `PI_SPACES_CONFIG`; its `schema` must be `pi-spaces.config/v1`. Read it to answer questions about profiles; edit it only when the user asks, and keep every key to the documented ones (unknown keys make the file invalid and ignored).
 - Never read `auth.json` or other credential files in any home.
-- You cannot move this session to another space. Ask the user to run `/space switch <name>` (interactive terminal only; Pi restarts), or start another Pi with `$PI_SPACES_COMMAND --space <name>`.
+- You cannot move this session to another space. Ask the user to run `/space switch <name>` (interactive terminal only; Pi restarts), or start another Pi with `$PI_SPACES_COMMAND --space <name>` (the space name there is bare: `work`; `pi-space` takes `<profile>/work`).
+- The Pi that `pi-space` starts runs as if started from a plain terminal for the named profile, even when you run it from inside another Pi or a space (it unwinds your space and sets `PI_CODING_AGENT_DIR` to that profile's home).
 - Never set `PI_CODING_AGENT_DIR` yourself, and never create, rename or delete space folders with file commands; use `/space` or `pi-space`.
 - Removing a space deletes everything in it: only on the user's explicit request, and keep the backup unless they say otherwise.
 
@@ -26,16 +29,18 @@ Use when a task depends on which Pi agent home this session uses (settings, sign
 | Need | Action |
 | --- | --- |
 | 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`) |
+| List spaces from a shell | `pi-space list` (optional `@jals1212/pi-spaces-cli`): every profile, each space as `<profile>/<name>` |
 | Spaces folder | `PI_SPACES_DIR`, else the `dir` of the profile whose `home` is the base home, else `spaces` next to the base home (`PI_SPACES_BASE_HOME`, else this home) |
 | Profiles, or why a variable differs per space | The config file (`PI_SPACES_CONFIG`, else `~/.pi-spaces/config.json`): a profile's `spaceEnv` variables are set only inside spaces (`{home}` and `{name}` filled in) and removed in base; without `spaceEnv` whatever a program keeps outside its agent home is shared with base |
-| 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`, `setup`, `completion`) are reserved.
+| Pick a space from a shell | bare `pi-space` on a terminal opens a picker of every profile's spaces (`<profile>/<name>`, `base` included) and starts Pi in the one chosen |
+| Rename a space | User request only: `pi-space rename <profile>/<old> <new>`; the new name alone or with the same profile (`<profile>/<new>`), a space never changes profile; refused for base and for the space you are in |
+| Create a space | `pi-space new <profile>/<name>`, or ask the user for `/space new <name>` (this Pi's profile); `pi-space new` also runs the profile's setup command when there is one (or `--setup <cmd>` for one call) |
+| Prepare a space for the program that runs Pi | `pi-space setup <profile>/<name>` (or `<profile>/--every`, or `--every` for every profile with a setup): 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>"`, or `pi-space <profile>/<name>` from a shell |
+| Remove a space | User request only: `pi-space remove <profile>/<name> --yes` keeps a backup in `.backups` |
+| Packages of a space | `pi-space update <profile>/<name|base|--every> --extensions` (`--every` alone: every profile), `pi-space install <profile>/<name> <source>`, `pi-space uninstall <profile>/<name> <source>`, `pi-space list <profile>/<name>`; without the CLI, `$PI_SPACES_COMMAND --space <name|base> update --extensions` |
+
+Names (the part after `<profile>/`; a profile name follows the same rule): 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`, `completion`) are reserved.
 
 ## Execution Steps
 

package/src/command.ts

@@ -58,11 +58,13 @@ export async function runSpaceCommand(args: string, deps: SpaceCommandDeps): Pro
 	try {
 		if (sub === "list" && rest.length === 0) return list(deps);
 		if (sub === "new" && rest.length === 1) {
-			const path = createSpace(deps.dir, rest[0], deps.declaration());
-			const name = rest[0];
+			const [name] = rest;
+			const path = createSpace(deps.dir, name, deps.declaration());
+			// pi-space names a space with its profile; without a matching profile this Pi is plain pi.
+			const qualified = `${deps.profile?.name ?? "pi"}/${name}`;
 			ctx.ui.notify(
 				hasSetupCommand(deps.env) || Boolean(deps.profile?.setup)
-					? `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}. Prepare it from a shell with: pi-space setup ${qualified}. Then enter it with /space switch ${name}.`
 					: `Created space "${name}" at ${path}. Enter it with /space switch ${name}.`,
 				"info",
 			);

package/src/config.ts

@@ -170,15 +170,21 @@ export function profileNames(config: Config | undefined): string[] {
 	return names.includes(BUILT_IN) ? names : [...names, BUILT_IN];
 }
 
-/** The built-in pi home: the base home inside a space (PI_SPACES_BASE_HOME), else PI_CODING_AGENT_DIR, else ~/.pi/agent. */
-function builtInHome(env: Env, home: string): string {
+/**
+ * The built-in pi home: the base home inside a space (PI_SPACES_BASE_HOME), else PI_CODING_AGENT_DIR, else ~/.pi/agent.
+ * A home that a profile of the file names is that profile's, not pi's: inside the Pi of another program those
+ * variables hold that program's home, so pi keeps ~/.pi/agent.
+ */
+function builtInHome(config: Config | undefined, env: Env, home: string): string {
 	const fromEnv = env.PI_SPACES_BASE_HOME || env.PI_CODING_AGENT_DIR;
-	return fromEnv ? resolve(home, expandTilde(fromEnv, home)) : join(home, ".pi", "agent");
+	const found = fromEnv ? resolve(home, expandTilde(fromEnv, home)) : undefined;
+	const claimed = (path: string) => config?.profiles.some((spec) => spec.home !== undefined && samePath(resolve(home, expandTilde(spec.home, home)), path));
+	return found !== undefined && !claimed(found) ? found : join(home, ".pi", "agent");
 }
 
 /** Resolves a profile; what a profile omits for `home` falls back to the built-in pi's, and `pi` also gets its `command`. */
-function resolveProfile(spec: ProfileSpec, env: Env, home: string): Profile {
-	const base = spec.home === undefined ? builtInHome(env, home) : resolve(home, expandTilde(spec.home, home));
+function resolveProfile(config: Config | undefined, spec: ProfileSpec, env: Env, home: string): Profile {
+	const base = spec.home === undefined ? builtInHome(config, env, home) : resolve(home, expandTilde(spec.home, home));
 	const profile: Profile = {
 		name: spec.name,
 		home: base,
@@ -195,7 +201,7 @@ function resolveProfile(spec: ProfileSpec, env: Env, home: string): Profile {
 export function profileByName(config: Config | undefined, name: string, env: Env, home: string): Profile {
 	const spec = config?.profiles.find((profile) => profile.name === name) ?? (name === BUILT_IN ? { name } : undefined);
 	if (spec === undefined) throw new ConfigError(`Unknown profile "${name}"; known profiles: ${profileNames(config).join(", ")}.`);
-	return resolveProfile(spec, env, home);
+	return resolveProfile(config, spec, env, home);
 }
 
 /** The profile whose home is the base home (the same place, real paths compared): the first in file order, then built-in `pi`. */

package/src/context.ts

@@ -20,7 +20,7 @@ export function spaceInfo(dir: string, agentHome: string, env: Env): SpaceInfo {
 	return {
 		space: activeSpace(dir, agentHome),
 		home: resolve(agentHome),
-		// A blank value counts as unset, so the default is pi, as in the pi-space command.
+		// A blank value counts as unset, so the default is pi (pi-space leaves it unset for a profile without a command).
 		command: env.PI_SPACES_COMMAND?.trim() || "pi",
 	};
 }