@jals1212/pi-spaces 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,40 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 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

@@ -71,17 +71,98 @@ The status line shows `◆ <name>` while a space is active. In the base home it
 
 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.
 
+## 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 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",
+  "default": "ml",
+  "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 <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.
+
+### 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 | The profile to use when none is asked for: a profile of the file, or `pi`. Without it, the built-in `pi` profile. |
+| `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 <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`, 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.
+
+### 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.
 
 ### Environment variables
 
@@ -89,7 +170,8 @@ 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_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_CODING_AGENT_DIR` | Pi's agent home; its parent holds the default spaces folder. Default: `~/.pi/agent`. |
@@ -101,6 +183,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:
 
@@ -133,6 +216,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 +248,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"];
 	                                                
 	                      
 	         
+	                                                                                                                          
+	                  
 	                                                                  
 	                                  
 	                                                     
@@ -58,7 +61,7 @@ export async function runSpaceCommand(args        , deps                  )
 			const path = createSpace(deps.dir, rest[0], deps.declaration());
 			const name = rest[0];
 			ctx.ui.notify(
-				hasSetupCommand(deps.env)
+				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}. Enter it with /space switch ${name}.`,
 				"info",
@@ -153,7 +156,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,242 @@
+// 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. */
+function builtInHome(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");
+}
+
+/** 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));
+	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(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/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). */

package/dist/spaces.js

@@ -17,28 +17,31 @@ export class SpaceError extends Error {
                                                      
                                                                                          
 
-function expandTilde(path        , home        )         {
+/** Expands a leading `~` to the given home folder. */
+export function expandTilde(path        , home        )         {
 	if (path === "~") return home;
 	if (path.startsWith("~/")) return join(home, path.slice(2));
 	return path;
 }
 
 /**
- * The folder that holds every space: PI_SPACES_DIR, else a `spaces` folder next to the base home
+ * The folder that holds every space: PI_SPACES_DIR, else the dir of the profile that matches the base home
+ * (an absolute path, from the config file), else a `spaces` folder next to the base home
  * (~/.pi/agent gives ~/.pi/spaces), so every program that runs Pi with its own home keeps its own spaces.
  * The base home is the one Pi started with (PI_SPACES_BASE_HOME inside a space), else Pi's agent home.
  */
-export function spacesDir(env      = process.env, home         = osHomedir())         {
+export function spacesDir(env      = process.env, home         = osHomedir(), profileDir         )         {
 	const fromEnv = env.PI_SPACES_DIR;
 	// A relative value resolves against the user's home, never the working directory.
 	if (fromEnv) return resolve(home, expandTilde(fromEnv, home));
+	if (profileDir) return profileDir;
 	const agentHome = env.PI_CODING_AGENT_DIR ? expandTilde(env.PI_CODING_AGENT_DIR, home) : join(home, ".pi", "agent");
 	const baseHome = env.PI_SPACES_BASE_HOME || agentHome;
 	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", "setup"]);
+const COMMANDS = new Set(["list", "new", "remove", "rename", "switch", "update", "install", "uninstall", "setup", "completion"]);
 
 /** True when PI_SPACES_SETUP holds a setup command, not just blanks. */
 export function hasSetupCommand(env     )          {
@@ -235,7 +238,8 @@ function localPackageName(folder        )                     {
 	}
 }
 
-function samePath(a        , b        )          {
+/** True when both paths are the same place: real paths when they exist, resolved paths otherwise. */
+export function samePath(a        , b        )          {
 	return realOrResolved(a) === realOrResolved(b);
 }
 

package/extensions/spaces.ts

@@ -1,9 +1,11 @@
 // pi-spaces: named Pi agent homes. Adds /space and shows the active space in the status line.
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { completeSpaceArgs, runSpaceCommand, statusText } from "../src/command.ts";
+import { activeProfile } from "../src/config.ts";
 import { addSpaceSection, exportSpaceInfo, spaceInfo } from "../src/context.ts";
 import { planStartup, relaunchCommand, runNow, scheduleRelaunch } from "../src/relaunch.ts";
 import { findOwnDeclaration, spacesDir } from "../src/spaces.ts";
@@ -12,9 +14,15 @@ const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const packageName: string = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).name;
 
 export default function (pi: ExtensionAPI) {
+	// The profile of the config file that describes this Pi's base home, if any. A file that cannot be used never
+	// stops Pi: it is reported once, at session start, and Pi behaves as with no file.
+	const { profile, warning } = activeProfile(process.env, homedir(), getAgentDir());
+	let warned = false;
+	const dir = spacesDir(process.env, homedir(), profile?.dir);
+
 	// `pi --space <name>` is handled here, before the terminal UI starts and before any prompt runs:
 	// Pi runs again in the space with every other argument, and this process exits with its code.
-	const plan = planStartup({ proc: process, dir: spacesDir(), currentHome: getAgentDir(), env: process.env });
+	const plan = planStartup({ proc: process, dir, currentHome: getAgentDir(), env: process.env, spaceEnv: profile?.spaceEnv });
 	if (plan.kind === "error") {
 		process.stderr.write(`pi-spaces: ${plan.message}\n`);
 		process.exit(1);
@@ -22,19 +30,24 @@ export default function (pi: ExtensionAPI) {
 	if (plan.kind === "relaunch") process.exit(runNow(plan.command, plan.env));
 
 	// Where this Pi runs: exported for tools and the programs they start, and told to the model before each run.
-	const info = spaceInfo(spacesDir(), getAgentDir(), process.env);
+	const info = spaceInfo(dir, getAgentDir(), process.env);
 	exportSpaceInfo(process.env, info);
 	pi.on("before_agent_start", (event) => addSpaceSection(event.systemPromptOptions, info));
 
 	pi.registerFlag("space", { description: "Start Pi in this space (see /space list)", type: "string" });
 
 	pi.on("session_start", (_event, ctx) => {
-		ctx.ui.setStatus("space", statusText(spacesDir(), getAgentDir()));
+		ctx.ui.setStatus("space", statusText(dir, getAgentDir()));
+		if (warning !== undefined && !warned) {
+			warned = true;
+			if (ctx.hasUI) ctx.ui.notify(`pi-spaces: ${warning}`, "warning");
+			else process.stderr.write(`pi-spaces: ${warning}\n`);
+		}
 	});
 
 	pi.registerCommand("space", {
 		description: "Pick a Pi space to switch to, or list, create, remove and rename spaces (separate agent homes)",
-		getArgumentCompletions: (prefix) => completeSpaceArgs(prefix, spacesDir()),
+		getArgumentCompletions: (prefix) => completeSpaceArgs(prefix, dir),
 		handler: async (args, ctx) => {
 			// Without a UI (print and JSON modes) notifications go nowhere, so they go to stderr;
 			// stdout stays free for Pi's own output.
@@ -43,9 +56,10 @@ export default function (pi: ExtensionAPI) {
 				: (message: string) => void process.stderr.write(`${message}\n`);
 			await runSpaceCommand(args, {
 				ctx: { mode: ctx.mode, hasUI: ctx.hasUI, shutdown: () => ctx.shutdown(), ui: { notify, confirm: (t, m) => ctx.ui.confirm(t, m), select: (t, o) => ctx.ui.select(t, o) } },
-				dir: spacesDir(),
+				dir,
 				currentHome: getAgentDir,
 				env: process.env,
+				profile,
 				declaration: () => findOwnDeclaration(getAgentDir(), packageName, packageRoot),
 				command: () => relaunchCommand(),
 				relaunch: scheduleRelaunch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/pi-spaces",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Named spaces for Pi: keep several agent homes (sign-ins, packages, settings) and pick one by name.",
   "license": "MIT",
   "author": "jals1212",
@@ -20,6 +20,7 @@
   "type": "module",
   "exports": {
     "./spaces": "./dist/spaces.js",
+    "./config": "./dist/config.js",
     "./package.json": "./package.json"
   },
   "pi": {

package/skills/pi-spaces/SKILL.md

@@ -1,20 +1,21 @@
 ---
 name: pi-spaces
-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."
+description: "Trigger: pi-spaces, space, spaces, /space, pi-space, pi --space, PI_SPACE, PI_SPACE_HOME, PI_SPACES_COMMAND, PI_SPACES_SETUP, PI_SPACES_CONFIG, profile, 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
-  version: "1.0"
+  version: "1.1"
 ---
 
 ## Activation Contract
 
-Use when a task depends on which Pi agent home this session uses (settings, sign-ins, installed packages, sessions), or when the user asks about spaces. A space is a separate Pi agent home kept in a folder of the spaces folder; the base home is the one Pi started with. Pi reads its home once at startup, so one process stays in one space.
+Use when a task depends on which Pi agent home this session uses (settings, sign-ins, installed packages, sessions), or when the user asks about spaces. A space is a separate Pi agent home kept in a folder of the spaces folder; the base home is the one Pi started with. A profile (an entry of the optional config file) describes a program that runs Pi: its base home, command, spaces folder, setup command and per-space variables. Pi reads its home once at startup, so one process stays in one space.
 
 ## 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`.
 - 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.
+- 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>`.
 - Never set `PI_CODING_AGENT_DIR` yourself, and never create, rename or delete space folders with file commands; use `/space` or `pi-space`.
@@ -26,14 +27,15 @@ 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) |
+| 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`) 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`, `completion`) are reserved.
 
 ## Execution Steps
 
@@ -47,4 +49,4 @@ State the space (or "base home"), the agent home path, and the command or `/spac
 
 ## References
 
-- `../../README.md` — commands, environment variables and how switching works.
+- `../../README.md` — commands, environment variables, the profiles file (schema, `spaceEnv`) and how switching works.

package/src/command.ts

@@ -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 type { Profile } from "./config.ts";
 import { type Command, parseSpaceFlag, relaunchEnv, resolveSwitch } from "./relaunch.ts";
 import {
 	activeSpace,
@@ -40,6 +41,8 @@ export interface SpaceCommandDeps {
 	/** The agent home this Pi process runs with. */
 	currentHome(): string;
 	env: Env;
+	/** The profile that matches the base home, if any: its spaceEnv applies to switches and its setup to the `new` notice. */
+	profile?: Profile;
 	/** This package's declaration for a new space's settings.json. */
 	declaration(): PackageDeclaration;
 	/** The command that starts this Pi process again. */
@@ -58,7 +61,7 @@ export async function runSpaceCommand(args: string, deps: SpaceCommandDeps): Pro
 			const path = createSpace(deps.dir, rest[0], deps.declaration());
 			const name = rest[0];
 			ctx.ui.notify(
-				hasSetupCommand(deps.env)
+				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}. Enter it with /space switch ${name}.`,
 				"info",
@@ -153,7 +156,7 @@ function switchTo(name: string, deps: SpaceCommandDeps): void {
 	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/src/config.ts

@@ -0,0 +1,242 @@
+// 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 { type Env, expandTilde, samePath } from "./spaces.ts";
+
+/** 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: string) => 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: string) {
+		super(message);
+		this.name = "ConfigError";
+	}
+}
+
+/** A profile as written in the file: validated and trimmed, paths not yet expanded. */
+export interface ProfileSpec {
+	name: string;
+	home?: string;
+	command?: string;
+	dir?: string;
+	setup?: string;
+	spaceEnv?: Record<string, string>;
+}
+
+export interface Config {
+	/** The file it was read from. */
+	path: string;
+	/** The profile used when none is asked for; a profile of the file or `pi`. */
+	default?: string;
+	/** In file order. */
+	profiles: ProfileSpec[];
+}
+
+/** A profile with its paths resolved. `command`, `setup` and `spaceEnv` are set only when the profile has them. */
+export interface Profile {
+	name: string;
+	/** The base agent home. */
+	home: string;
+	/** The spaces folder. */
+	dir: string;
+	command?: string;
+	setup?: string;
+	/** Variable templates; `{home}` and `{name}` are filled in by spaceEnvFor. */
+	spaceEnv?: Record<string, string>;
+}
+
+/** 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: Env, home: string): string {
+	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: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function reason(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+type Fail = (problem: string) => never;
+
+/**
+ * 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: string, read: (path: string) => string = (file) => readFileSync(file, "utf8")): Config | undefined {
+	let text: string;
+	try {
+		text = read(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
+		throw new ConfigError(`${path}: cannot be read: ${reason(error)}`);
+	}
+	const fail: Fail = (problem) => {
+		throw new ConfigError(`${path}: ${problem}`);
+	};
+	let json: unknown;
+	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: 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: unknown, present: boolean, fail: Fail): void {
+	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: unknown, present: boolean, fail: Fail): ProfileSpec[] {
+	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: string, value: unknown, fail: Fail): ProfileSpec {
+	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: ProfileSpec = { name };
+	for (const key of ["home", "command", "dir", "setup"] as const) {
+		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: string, value: unknown, fail: Fail): Record<string, string> {
+	if (!isObject(value)) return fail(`"spaceEnv" in profile "${profile}" must be an object of strings.`);
+	const entries: [string, string][] = [];
+	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: Config | undefined): string[] {
+	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. */
+function builtInHome(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");
+}
+
+/** 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));
+	const profile: 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: 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);
+}
+
+/** 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: Config | undefined, baseHome: string, env: Env, home: string): Profile | undefined {
+	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: Record<string, string>, spaceHome: string, spaceName: string): Record<string, string> {
+	const fill = (template: string) => 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: Profile, spaceHome: string, spaceName: string): Record<string, string> {
+	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: Env,
+	home: string,
+	agentHome: string,
+	read?: (path: string) => string,
+): { profile: Profile | undefined; warning: string | undefined } {
+	const baseHome = env.PI_SPACES_BASE_HOME || agentHome;
+	let config: Config | undefined;
+	let warning: string | undefined;
+	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/src/relaunch.ts

@@ -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.ts";
 import { activeSpace, BASE, listSpaces, type Env, SpaceError, validateName } from "./spaces.ts";
 
 // Pi options that take a separate value, so the value is kept (or dropped) with them.
@@ -79,14 +80,18 @@ export function resolveSwitch(input: { dir: string; name: string; currentHome: s
 }
 
 // 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: Env, target: SwitchTarget & { currentHome: string }): Env {
+export function relaunchEnv(env: Env, target: SwitchTarget & { currentHome: string; spaceEnv?: Record<string, string> }): Env {
 	const from = resolve(target.currentHome);
 	const next: Env = {};
 	for (const [key, value] of Object.entries(env)) {
@@ -99,9 +104,37 @@ export function relaunchEnv(env: Env, target: SwitchTarget & { currentHome: stri
 	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: Env, target: SwitchTarget & { currentHome: string; spaceEnv?: Record<string, string> }): Record<string, string> {
+	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] as string]])));
+	}
+	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 {};
+	}
+}
+
 export interface Command {
 	command: string;
 	args: string[];
@@ -164,9 +197,10 @@ export type StartupPlan = { kind: "none" } | { kind: "error"; message: string }
  * 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: { proc: Proc; dir: string; currentHome: string; env: Env }): StartupPlan {
-	const { proc, dir, currentHome, env } = input;
+export function planStartup(input: { proc: Proc; dir: string; currentHome: string; env: Env; spaceEnv?: Record<string, string> }): StartupPlan {
+	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: { proc: Proc; dir: string; currentHome: strin
 		}
 		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). */

package/src/spaces.ts

@@ -17,28 +17,31 @@ export class SpaceError extends Error {
 export type Env = Record<string, string | undefined>;
 export type PackageDeclaration = string | ({ source: string } & Record<string, unknown>);
 
-function expandTilde(path: string, home: string): string {
+/** Expands a leading `~` to the given home folder. */
+export function expandTilde(path: string, home: string): string {
 	if (path === "~") return home;
 	if (path.startsWith("~/")) return join(home, path.slice(2));
 	return path;
 }
 
 /**
- * The folder that holds every space: PI_SPACES_DIR, else a `spaces` folder next to the base home
+ * The folder that holds every space: PI_SPACES_DIR, else the dir of the profile that matches the base home
+ * (an absolute path, from the config file), else a `spaces` folder next to the base home
  * (~/.pi/agent gives ~/.pi/spaces), so every program that runs Pi with its own home keeps its own spaces.
  * The base home is the one Pi started with (PI_SPACES_BASE_HOME inside a space), else Pi's agent home.
  */
-export function spacesDir(env: Env = process.env, home: string = osHomedir()): string {
+export function spacesDir(env: Env = process.env, home: string = osHomedir(), profileDir?: string): string {
 	const fromEnv = env.PI_SPACES_DIR;
 	// A relative value resolves against the user's home, never the working directory.
 	if (fromEnv) return resolve(home, expandTilde(fromEnv, home));
+	if (profileDir) return profileDir;
 	const agentHome = env.PI_CODING_AGENT_DIR ? expandTilde(env.PI_CODING_AGENT_DIR, home) : join(home, ".pi", "agent");
 	const baseHome = env.PI_SPACES_BASE_HOME || agentHome;
 	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", "setup"]);
+const COMMANDS = new Set(["list", "new", "remove", "rename", "switch", "update", "install", "uninstall", "setup", "completion"]);
 
 /** True when PI_SPACES_SETUP holds a setup command, not just blanks. */
 export function hasSetupCommand(env: Env): boolean {
@@ -235,7 +238,8 @@ function localPackageName(folder: string): string | undefined {
 	}
 }
 
-function samePath(a: string, b: string): boolean {
+/** True when both paths are the same place: real paths when they exist, resolved paths otherwise. */
+export function samePath(a: string, b: string): boolean {
 	return realOrResolved(a) === realOrResolved(b);
 }