@jals1212/pi-spaces 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,56 @@ 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
+
+- Profiles in a config file (`~/.pi-spaces/config.json`, or `PI_SPACES_CONFIG`):
+  named descriptions of a program that runs Pi, with its base `home`,
+  `command`, spaces `dir`, `setup` command and `spaceEnv`. The format carries a
+  version (`"schema": "pi-spaces.config/v1"`); a newer version is refused with
+  a message that it needs a newer pi-spaces, and unknown keys are refused. A
+  built-in `pi` profile always exists and can be replaced. See the README.
+- `spaceEnv`: variables that exist only in spaces. Entering a space sets them
+  (`{home}` and `{name}` filled in) and moving between spaces recomputes
+  them. Going back to `base` puts back the values the base home had (kept in `PI_SPACES_BASE_ENV` meanwhile). Without
+  `spaceEnv`, whatever a program keeps outside its agent home stays shared with
+  the base home, as before. The variables pi-spaces sets itself are refused.
+- The extension applies the profile whose `home` is the base home: its
+  `spaceEnv` on `/space switch` and `pi --space`, its `dir` as the spaces
+  folder, and `/space new` names `pi-space setup <name>` when it has a `setup`.
+- `@jals1212/pi-spaces/config` exports the loader (`loadConfig`, `configPath`,
+  `profileByName`, `profileForHome`, `spaceEnvFor`, `activeProfile`,
+  `ConfigError`) for the `pi-space` command.
+
+### Changed
+
+- `completion` is a reserved name, for `pi-space completion`. A space already
+  named `completion` is no longer listed; rename its folder by hand.
+- The spaces folder is `PI_SPACES_DIR`, else the matching profile's `dir`, else
+  `spaces` next to the base home. `spacesDir` takes the profile's dir as an
+  optional third argument.
+- `relaunchEnv` and `planStartup` take an optional `spaceEnv`; without it they
+  behave exactly as before.
+- A config file that cannot be used never stops Pi: the extension warns once
+  when the session starts and behaves as with no file.
+
 ## 0.5.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,21 +67,105 @@ 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.
 
-**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`.
+**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`, `setup` and `completion`.
 
 ## 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 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
+
+| | |
+| --- | --- |
+| Location | `~/.pi-spaces/config.json` |
+| Change it | `PI_SPACES_CONFIG=<path>` (a leading `~` is your home folder; a relative path is taken from it). The `pi-space` command also takes `--config <path>` (see [`cli/README.md`](cli/README.md)). |
+| Missing | No profiles: Pi, spaces and `pi-space` behave as without this feature. |
+| Invalid | See [When the file is wrong](#when-the-file-is-wrong). |
+
+A complete example for a program called `my-launcher`, which keeps its own configuration outside its agent home:
+
+```json
+{
+  "schema": "pi-spaces.config/v1",
+  "profiles": {
+    "ml": {
+      "home": "~/.my-launcher/agent",
+      "command": "my-launcher --",
+      "setup": "my-launcher --home {home} setup",
+      "spaceEnv": { "MY_LAUNCHER_CONFIG_HOME": "{home}/config" }
+    }
+  }
+}
+```
+
+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`
+
+Top level (every other key is refused):
+
+| Key | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `schema` | string | yes | Exactly `"pi-spaces.config/v1"`. |
+| `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):
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `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 <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.
+
+### `spaceEnv`: what is separate and what is shared
+
+Pi keeps everything in its agent home, so a space separates it completely with no configuration. A program that runs Pi may also keep something **outside** that home (a configuration folder, say) and hand its location to Pi in an environment variable. When you switch, pi-spaces moves only the variables that point inside the old home (see [How switching works](#how-switching-works)); a variable that points elsewhere is not recognised as part of the home and stays as it was. So without `spaceEnv`, whatever the program keeps outside the agent home is **shared** between the base home and every space. That is the default on purpose: nothing is separated that you did not ask to separate.
+
+To separate it, name the variable in `spaceEnv`, with a value built from the space:
+
+- Entering a space sets the variable, from the template, with `{home}` the space's folder and `{name}` its name.
+- Going back to `base` puts back the value the base home had when you left it, or removes the variable when it had none, so the base home runs exactly as it was started. The base's values travel in `PI_SPACES_BASE_ENV` while you are in spaces.
+- Going from one space to another sets it again for the target; a value that pointed into the old space is replaced, not moved.
+- `pi --space <name>` does the same at startup.
+
+pi-spaces does not create what a variable points to; `setup` (or the program itself) does.
+
+### The built-in `pi` profile
+
+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
+
+The file says which format it uses in `schema`, so the format can grow without breaking files. This pi-spaces reads `pi-spaces.config/v1` only. A file with a newer `pi-spaces.config/vN` is refused with a message that it needs a newer pi-spaces (update the package); anything else in `schema`, or no `schema`, is refused as invalid. A newer format is never half-read.
+
+### When the file is wrong
+
+Unknown keys, wrong types, bad names, a `default` that names no profile, an unreadable file and invalid JSON are all refused with a message that names the file and the problem, for example `~/.pi-spaces/config.json: unknown key "hmoe" in profile "ml"; allowed keys are "home", "command", "dir", "setup" and "spaceEnv".` Pi never stops for it: the extension shows the message once as a warning when the session starts (on stderr without a terminal UI) and then behaves as if there were no file. A missing file is not an error.
 
 ## Configuration reference
 
 ### 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. `PI_SPACES_DIR` replaces it.
+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
 
@@ -89,9 +173,10 @@ Read:
 
 | Variable | Meaning |
 | --- | --- |
-| `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_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` | 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:
@@ -101,6 +186,7 @@ Set for the Pi a switch starts:
 | `PI_CODING_AGENT_DIR` | The space's folder, or the base home for `base`. |
 | `PI_SPACE` | The space's name. Unset in the base home. |
 | `PI_SPACES_BASE_HOME` | The home Pi started with, so `base` and the spaces folder survive switches. |
+| `PI_SPACES_BASE_ENV` | Only with a profile's `spaceEnv`, and only in a space: the base home's own values of those variables (JSON), put back when you return to `base`. |
 
 Set in every Pi this extension runs in, even one started without a switch, for its tools and the programs they start:
 
@@ -108,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
 
@@ -133,6 +219,7 @@ Pi reads its agent home once, when it starts, so a running session cannot move t
 
 - `PI_CODING_AGENT_DIR`, `PI_SPACE` and `PI_SPACES_BASE_HOME` are set as in [Environment variables](#environment-variables).
 - Any other variable whose value is the old home, or a path inside it, moves to the same path in the new home; in a list such as `PATH`, each entry moves on its own. This keeps variables that a launcher derived from the home consistent. `PWD` and `OLDPWD` are left alone.
+- With a [profile](#profiles) that has `spaceEnv`, those variables are then set, with `{home}` and `{name}` filled in, when the target is a space; when it is `base`, they get back the values the base home had (`PI_SPACES_BASE_ENV`).
 - The same options are kept, such as `--model`, `-e`, `--tools` and other extensions' options. The initial prompt, `@file` arguments, everything after `--`, and the session options (`-c`, `-r`, `--session`, `--session-id`, `--fork`, `--session-dir`, `--no-session`, `-n`) are dropped, because they belong to the home being left.
 - Switching works only in the interactive terminal.
 
@@ -164,7 +251,7 @@ npm test                         # links cli/ to this checkout, builds both, run
 pi -e ./extensions/spaces.ts     # try the extension without installing it
 ```
 
-`src/` is TypeScript. Pi loads the extension's TypeScript itself. The command in `cli/` imports the core as `@jals1212/pi-spaces/spaces`: the plain JavaScript in `dist/` that `npm run build` makes (Node does not strip types from files under `node_modules`). `npm pack` and `npm publish` build it first. `scripts/link-self.mjs` makes `cli/node_modules/@jals1212/pi-spaces` a link to this checkout, so the command's tests use the core from the working tree instead of from npm.
+`src/` is TypeScript. Pi loads the extension's TypeScript itself. The command in `cli/` imports the core as `@jals1212/pi-spaces/spaces` (and the profiles code as `@jals1212/pi-spaces/config`): the plain JavaScript in `dist/` that `npm run build` makes (Node does not strip types from files under `node_modules`). `npm pack` and `npm publish` build it first. `scripts/link-self.mjs` makes `cli/node_modules/@jals1212/pi-spaces` a link to this checkout, so the command's tests use the core from the working tree instead of from npm.
 
 Branches: work goes to `develop` through pull requests; `main` receives `develop` when a release closes.
 

package/dist/command.js

@@ -1,5 +1,6 @@
 // The /space command, kept apart from Pi's extension API so it can be tested directly.
 import { join } from "node:path";
+                                           
 import {               parseSpaceFlag, relaunchEnv, resolveSwitch } from "./relaunch.js";
 import {
 	activeSpace,
@@ -40,6 +41,8 @@ const SUBCOMMANDS = ["list", "new", "remove", "rename", "switch"];
 	                                                
 	                      
 	         
+	                                                                                                                          
+	                  
 	                                                                  
 	                                  
 	                                                     
@@ -55,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)
-					? `Created space "${name}" at ${path}. Prepare it from a shell with: pi-space setup ${name}. Then enter it with /space switch ${name}.`
+				hasSetupCommand(deps.env) || Boolean(deps.profile?.setup)
+					? `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",
 			);
@@ -153,7 +158,7 @@ function switchTo(name        , deps                  )       {
 	if (ctx.mode !== "tui") throw new SpaceError("/space switch needs the interactive terminal.");
 	const currentHome = deps.currentHome();
 	const target = resolveSwitch({ dir: deps.dir, name, currentHome, env: deps.env });
-	deps.relaunch(deps.command(), relaunchEnv(deps.env, { ...target, currentHome }));
+	deps.relaunch(deps.command(), relaunchEnv(deps.env, { ...target, currentHome, spaceEnv: deps.profile?.spaceEnv }));
 	ctx.ui.notify(
 		target.space === undefined ? "Switching to the base home; Pi restarts in it." : `Switching to space "${target.space}"; Pi restarts in it.`,
 		"info",

package/dist/config.js

@@ -0,0 +1,248 @@
+// The config file: named profiles that describe a program that runs Pi (its agent home, the command
+// that starts it, where its spaces live, how to set a space up, and the variables it needs per space).
+// Pure and host-agnostic: the file system, the environment and the user's home are all inputs.
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {           expandTilde, samePath } from "./spaces.js";
+
+/** The schema this version of pi-spaces reads. */
+export const SCHEMA = "pi-spaces.config/v1";
+const NEWER_SCHEMA = /^pi-spaces\.config\/v([1-9][0-9]*)$/;
+const PROFILE_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// Set by pi-spaces itself on every switch; a profile that set them would break switching.
+const RESERVED_VARIABLES = new Set(["PI_CODING_AGENT_DIR", "PI_SPACE", "PI_SPACE_HOME"]);
+const isReservedVariable = (name        ) => RESERVED_VARIABLES.has(name) || name.startsWith("PI_SPACES_");
+const TOP_KEYS = ["schema", "default", "profiles"];
+const PROFILE_KEYS = ["home", "command", "dir", "setup", "spaceEnv"];
+const BUILT_IN = "pi";
+
+export class ConfigError extends Error {
+	constructor(message        ) {
+		super(message);
+		this.name = "ConfigError";
+	}
+}
+
+/** A profile as written in the file: validated and trimmed, paths not yet expanded. */
+                              
+	             
+	              
+	                 
+	             
+	               
+	                                  
+ 
+
+                         
+	                                 
+	             
+	                                                                              
+	                 
+	                     
+	                        
+ 
+
+/** A profile with its paths resolved. `command`, `setup` and `spaceEnv` are set only when the profile has them. */
+                          
+	             
+	                           
+	             
+	                         
+	            
+	                 
+	               
+	                                                                              
+	                                  
+ 
+
+/** The config file: PI_SPACES_CONFIG (a relative value is taken from the user's home), else ~/.pi-spaces/config.json. */
+export function configPath(env     , home        )         {
+	const fromEnv = env.PI_SPACES_CONFIG?.trim();
+	if (fromEnv) return resolve(home, expandTilde(fromEnv, home));
+	return join(home, ".pi-spaces", "config.json");
+}
+
+function isObject(value         )                                   {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function reason(error         )         {
+	return error instanceof Error ? error.message : String(error);
+}
+
+                                       
+
+/**
+ * Reads and validates the config file. A missing file is no config (undefined). Anything else wrong
+ * throws a ConfigError that names the file and the problem; unknown keys are refused so typos fail loudly.
+ */
+export function loadConfig(path        , read                           = (file) => readFileSync(file, "utf8"))                     {
+	let text        ;
+	try {
+		text = read(path);
+	} catch (error) {
+		if ((error                         )?.code === "ENOENT") return undefined;
+		throw new ConfigError(`${path}: cannot be read: ${reason(error)}`);
+	}
+	const fail       = (problem) => {
+		throw new ConfigError(`${path}: ${problem}`);
+	};
+	let json         ;
+	try {
+		json = JSON.parse(text);
+	} catch (error) {
+		return fail(`not valid JSON: ${reason(error)}`);
+	}
+	if (!isObject(json)) return fail("the top level must be a JSON object.");
+	// The version first: a newer file may use keys this one does not know.
+	checkSchema(json.schema, "schema" in json, fail);
+	for (const key of Object.keys(json)) {
+		if (!TOP_KEYS.includes(key)) fail(`unknown key "${key}"; allowed keys are "schema", "default" and "profiles".`);
+	}
+	const config         = { path, profiles: parseProfiles(json.profiles, "profiles" in json, fail) };
+	if ("default" in json) {
+		const name = json.default;
+		if (typeof name !== "string" || name === "") return fail('"default" must be a string naming a profile.');
+		const known = profileNames(config);
+		if (!known.includes(name)) fail(`"default" names unknown profile "${name}"; known profiles: ${known.join(", ")}.`);
+		config.default = name;
+	}
+	return config;
+}
+
+function checkSchema(schema         , present         , fail      )       {
+	if (!present) fail(`"schema" is required; use "${SCHEMA}".`);
+	if (schema === SCHEMA) return;
+	const version = typeof schema === "string" ? NEWER_SCHEMA.exec(schema)?.[1] : undefined;
+	// Only a canonical vN with N above 1 is a newer version; v0 and v01 are just invalid.
+	if (version !== undefined && Number(version) > 1) {
+		fail(`"schema" is "${schema}", which needs a newer pi-spaces; this one reads "${SCHEMA}".`);
+	}
+	fail(`invalid "schema" ${JSON.stringify(schema)}; use "${SCHEMA}".`);
+}
+
+function parseProfiles(value         , present         , fail      )                {
+	if (!present) return [];
+	if (!isObject(value)) return fail('"profiles" must be an object of profiles.');
+	return Object.entries(value).map(([name, profile]) => parseProfile(name, profile, fail));
+}
+
+function parseProfile(name        , value         , fail      )              {
+	if (!PROFILE_NAME.test(name)) {
+		fail(`invalid profile name "${name}": use lowercase letters, digits, "-" and "_", starting with a letter or digit (at most 64 characters).`);
+	}
+	if (!isObject(value)) return fail(`profile "${name}" must be an object.`);
+	for (const key of Object.keys(value)) {
+		if (!PROFILE_KEYS.includes(key)) {
+			fail(`unknown key "${key}" in profile "${name}"; allowed keys are "home", "command", "dir", "setup" and "spaceEnv".`);
+		}
+	}
+	const spec              = { name };
+	for (const key of ["home", "command", "dir", "setup"]         ) {
+		if (!(key in value)) continue;
+		const text = value[key];
+		if (typeof text !== "string" || text.trim() === "") return fail(`"${key}" in profile "${name}" must be a non-empty string.`);
+		spec[key] = text.trim();
+	}
+	if ("spaceEnv" in value) spec.spaceEnv = parseSpaceEnv(name, value.spaceEnv, fail);
+	return spec;
+}
+
+function parseSpaceEnv(profile        , value         , fail      )                         {
+	if (!isObject(value)) return fail(`"spaceEnv" in profile "${profile}" must be an object of strings.`);
+	const entries                     = [];
+	for (const [key, text] of Object.entries(value)) {
+		if (!VARIABLE_NAME.test(key)) {
+			fail(`invalid variable name "${key}" in "spaceEnv" of profile "${profile}"; use letters, digits and "_", not starting with a digit.`);
+		}
+		if (isReservedVariable(key)) fail(`"${key}" in "spaceEnv" of profile "${profile}" is set by pi-spaces itself; choose another variable.`);
+		if (typeof text !== "string") return fail(`"spaceEnv.${key}" in profile "${profile}" must be a string.`);
+		entries.push([key, text]);
+	}
+	// fromEntries defines own properties, so a name such as __proto__ stays plain data.
+	return Object.fromEntries(entries);
+}
+
+/** The profile names, in file order, with `pi` last unless the file defines it. */
+export function profileNames(config                    )           {
+	const names = (config?.profiles ?? []).map((profile) => profile.name);
+	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.
+ * 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;
+	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(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,
+		dir: spec.dir === undefined ? join(dirname(base), "spaces") : resolve(home, expandTilde(spec.dir, home)),
+	};
+	const command = spec.command ?? (spec.name === BUILT_IN ? "pi" : undefined);
+	if (command !== undefined) profile.command = command;
+	if (spec.setup !== undefined) profile.setup = spec.setup;
+	if (spec.spaceEnv !== undefined) profile.spaceEnv = spec.spaceEnv;
+	return profile;
+}
+
+/** The profile with this name, or a ConfigError that lists the known ones. `pi` always exists. */
+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(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`. */
+export function profileForHome(config                    , baseHome        , env     , home        )                      {
+	for (const name of profileNames(config)) {
+		const profile = profileByName(config, name, env, home);
+		if (samePath(profile.home, baseHome)) return profile;
+	}
+	return undefined;
+}
+
+/** The templates with every `{home}` and `{name}` replaced. Replacer functions keep `$` literal. */
+export function expandSpaceEnv(templates                        , spaceHome        , spaceName        )                         {
+	const fill = (template        ) => template.replace(/\{home\}/g, () => spaceHome).replace(/\{name\}/g, () => spaceName);
+	return Object.fromEntries(Object.entries(templates).map(([key, template]) => [key, fill(template)]));
+}
+
+/** The variables a space gets: the profile's spaceEnv for this space's folder and name (none without spaceEnv). */
+export function spaceEnvFor(profile         , spaceHome        , spaceName        )                         {
+	return expandSpaceEnv(profile.spaceEnv ?? {}, spaceHome, spaceName);
+}
+
+/**
+ * The profile this Pi runs under, from the config file: the one whose home is the base home
+ * (PI_SPACES_BASE_HOME, else the agent home). An unusable file never stops Pi: it comes back as
+ * a warning and the result is the same as with no file.
+ */
+export function activeProfile(
+	env     ,
+	home        ,
+	agentHome        ,
+	read                           ,
+)                                                                {
+	const baseHome = env.PI_SPACES_BASE_HOME || agentHome;
+	let config                    ;
+	let warning                    ;
+	try {
+		config = loadConfig(configPath(env, home), read);
+	} catch (error) {
+		if (!(error instanceof ConfigError)) throw error;
+		warning = error.message;
+	}
+	return { profile: profileForHome(config, baseHome, env, home), warning };
+}

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/dist/relaunch.js

@@ -2,6 +2,7 @@
 // running the same Pi command again with PI_CODING_AGENT_DIR pointing at the space.
 import { spawnSync } from "node:child_process";
 import { delimiter, join, resolve, sep } from "node:path";
+import { expandSpaceEnv } from "./config.js";
 import { activeSpace, BASE, listSpaces,           SpaceError, validateName } from "./spaces.js";
 
 // Pi options that take a separate value, so the value is kept (or dropped) with them.
@@ -79,14 +80,18 @@ export function resolveSwitch(input
 }
 
 // PWD and OLDPWD describe the working directory, which the relaunch keeps.
-const NOT_REWRITTEN = new Set(["PI_SPACES_DIR", "PI_SPACES_BASE_HOME", "PWD", "OLDPWD"]);
+// PI_SPACES_BASE_ENV holds the base's own values, which must come back exactly as they were.
+const NOT_REWRITTEN = new Set(["PI_SPACES_DIR", "PI_SPACES_BASE_HOME", "PI_SPACES_BASE_ENV", "PWD", "OLDPWD"]);
 
 /**
  * The environment for the relaunched Pi. Every variable whose value is the current home,
  * or a path inside it, moves to the same path in the target home, so variables a host
  * set from the home stay consistent without this package knowing the host.
+ * With the profile's spaceEnv templates, those variables are then set for a space with `{home}` and `{name}`
+ * filled in, recomputed for each space. The base's own values of them are kept in PI_SPACES_BASE_ENV on the way
+ * out and put back on the way back, so the base home runs exactly as it was started.
  */
-export function relaunchEnv(env     , target                                        )      {
+export function relaunchEnv(env     , target                                                                           )      {
 	const from = resolve(target.currentHome);
 	const next      = {};
 	for (const [key, value] of Object.entries(env)) {
@@ -99,9 +104,37 @@ export function relaunchEnv(env     , target
 	next.PI_SPACES_BASE_HOME = target.baseHome;
 	if (target.space === undefined) delete next.PI_SPACE;
 	else next.PI_SPACE = target.space;
+	if (target.spaceEnv && Object.keys(target.spaceEnv).length > 0) {
+		const saved = baseValues(env, target);
+		for (const key of Object.keys(target.spaceEnv)) delete next[key];
+		if (target.space !== undefined) {
+			Object.assign(next, expandSpaceEnv(target.spaceEnv, target.targetHome, target.space));
+			next.PI_SPACES_BASE_ENV = JSON.stringify(saved);
+		} else {
+			Object.assign(next, saved);
+			delete next.PI_SPACES_BASE_ENV;
+		}
+	}
 	return next;
 }
 
+/**
+ * The base home's own values of the spaceEnv variables: read from the environment when leaving the base home,
+ * else the ones kept in PI_SPACES_BASE_ENV (none when it is missing or unreadable).
+ */
+function baseValues(env     , target                                                                           )                         {
+	const keys = Object.keys(target.spaceEnv ?? {});
+	if (resolve(target.currentHome) === resolve(target.baseHome)) {
+		return Object.fromEntries(keys.flatMap((key) => (env[key] === undefined ? [] : [[key, env[key]          ]])));
+	}
+	try {
+		const kept = JSON.parse(env.PI_SPACES_BASE_ENV ?? "{}");
+		return Object.fromEntries(keys.flatMap((key) => (typeof kept?.[key] === "string" ? [[key, kept[key]]] : [])));
+	} catch {
+		return {};
+	}
+}
+
                           
 	                
 	               
@@ -164,9 +197,10 @@ const PACKAGE_COMMANDS = new Set(["install", "remove", "uninstall", "update", "l
  * 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.
+ * `spaceEnv` is the matched profile's variable templates, applied by relaunchEnv.
  */
-export function planStartup(input                                                            )              {
-	const { proc, dir, currentHome, env } = input;
+export function planStartup(input                                                                                               )              {
+	const { proc, dir, currentHome, env, spaceEnv } = 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" };
@@ -183,7 +217,7 @@ export function planStartup(input
 		}
 		return { kind: "error", message: error.message };
 	}
-	return { kind: "relaunch", command: relaunchCommand(proc, args), env: relaunchEnv(env, { ...target, currentHome }) };
+	return { kind: "relaunch", command: relaunchCommand(proc, args), env: relaunchEnv(env, { ...target, currentHome, spaceEnv }) };
 }
 
 /** Runs the command now with inherited stdio and returns its exit code (1 when it cannot start). */