@jals1212/pi-spaces 0.5.0 → 0.7.0

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.7.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,22 +1,26 @@
 ---
 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.3"
 ---
 
 ## 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`.
+- The `pi-space` CLI names every space `<profile>/<name>` (`base` included, as `<profile>/base`); a bare name is refused. Nothing in the environment or the `<pi_space>` section names your own profile. To find it, take your base home (`PI_SPACES_BASE_HOME` when set, else `PI_SPACE_HOME`) and look in the config file for the profile whose `home` is that folder; no match means the built-in `pi`.
 - Files of this session's home (`settings.json`, `extensions/`, `sessions/`, installed packages) live under `PI_SPACE_HOME`; `pi install` and settings changes apply to this space only.
+- The config's `default` is not used by `pi-space` (it warns and ignores it); the profile is always named. `pi-space` does not read `PI_SPACES_COMMAND`, `PI_SPACES_DIR` or `PI_SPACES_SETUP` from the shell: a profile or `--command`, `--dir`, `--setup` (for one named profile) gives them.
+- Profiles live in `~/.pi-spaces/config.json`, or the file in `PI_SPACES_CONFIG`; its `schema` must be `pi-spaces.config/v1`. Read it to answer questions about profiles; edit it only when the user asks, and keep every key to the documented ones (unknown keys make the file invalid and ignored).
 - Never read `auth.json` or other credential files in any home.
-- You cannot move this session to another space. Ask the user to run `/space switch <name>` (interactive terminal only; Pi restarts), or start another Pi with `$PI_SPACES_COMMAND --space <name>`.
+- You cannot move this session to another space. Ask the user to run `/space switch <name>` (interactive terminal only; Pi restarts), or start another Pi with `$PI_SPACES_COMMAND --space <name>` (the space name there is bare: `work`; `pi-space` takes `<profile>/work`).
+- The Pi that `pi-space` starts runs as if started from a plain terminal for the named profile, even when you run it from inside another Pi or a space (it unwinds your space and sets `PI_CODING_AGENT_DIR` to that profile's home).
 - Never set `PI_CODING_AGENT_DIR` yourself, and never create, rename or delete space folders with file commands; use `/space` or `pi-space`.
 - Removing a space deletes everything in it: only on the user's explicit request, and keep the backup unless they say otherwise.
 
@@ -25,15 +29,18 @@ Use when a task depends on which Pi agent home this session uses (settings, sign
 | Need | Action |
 | --- | --- |
 | Which space, home, command | `<pi_space>` section, or `echo "$PI_SPACE|$PI_SPACE_HOME|$PI_SPACES_COMMAND"` |
-| List spaces from a shell | `pi-space list` (optional `@jals1212/pi-spaces-cli`) |
-| Spaces folder | `PI_SPACES_DIR`, else `spaces` next to the base home (`PI_SPACES_BASE_HOME`, else this home) |
-| Create a space | `pi-space new <name>`, or ask the user for `/space new <name>`; `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.
+| List spaces from a shell | `pi-space list` (optional `@jals1212/pi-spaces-cli`): every profile, each space as `<profile>/<name>` |
+| Spaces folder | `PI_SPACES_DIR`, else the `dir` of the profile whose `home` is the base home, else `spaces` next to the base home (`PI_SPACES_BASE_HOME`, else this home) |
+| Profiles, or why a variable differs per space | The config file (`PI_SPACES_CONFIG`, else `~/.pi-spaces/config.json`): a profile's `spaceEnv` variables are set only inside spaces (`{home}` and `{name}` filled in) and removed in base; without `spaceEnv` whatever a program keeps outside its agent home is shared with base |
+| Pick a space from a shell | bare `pi-space` on a terminal opens a picker of every profile's spaces (`<profile>/<name>`, `base` included) and starts Pi in the one chosen |
+| Rename a space | User request only: `pi-space rename <profile>/<old> <new>`; the new name alone or with the same profile (`<profile>/<new>`), a space never changes profile; refused for base and for the space you are in |
+| Create a space | `pi-space new <profile>/<name>`, or ask the user for `/space new <name>` (this Pi's profile); `pi-space new` also runs the profile's setup command when there is one (or `--setup <cmd>` for one call) |
+| Prepare a space for the program that runs Pi | `pi-space setup <profile>/<name>` (or `<profile>/--every`, or `--every` for every profile with a setup): runs the setup command (`{home}` and `{name}` become the space's folder and name) with the space as `PI_CODING_AGENT_DIR`; never in base |
+| Work in another space | User runs `/space switch <name>`, or `$PI_SPACES_COMMAND --space <name> "<prompt>"`, or `pi-space <profile>/<name>` from a shell |
+| Remove a space | User request only: `pi-space remove <profile>/<name> --yes` keeps a backup in `.backups` |
+| Packages of a space | `pi-space update <profile>/<name|base|--every> --extensions` (`--every` alone: every profile), `pi-space install <profile>/<name> <source>`, `pi-space uninstall <profile>/<name> <source>`, `pi-space list <profile>/<name>`; without the CLI, `$PI_SPACES_COMMAND --space <name|base> update --extensions` |
+
+Names (the part after `<profile>/`; a profile name follows the same rule): lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters; `base` (the base home) and the command words (`list`, `new`, `remove`, `rename`, `switch`, `update`, `install`, `uninstall`, `setup`, `completion`) are reserved.
 
 ## Execution Steps
 
@@ -47,4 +54,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. */
@@ -55,11 +58,13 @@ export async function runSpaceCommand(args: string, deps: SpaceCommandDeps): Pro
 	try {
 		if (sub === "list" && rest.length === 0) return list(deps);
 		if (sub === "new" && rest.length === 1) {
-			const path = createSpace(deps.dir, rest[0], deps.declaration());
-			const name = rest[0];
+			const [name] = rest;
+			const path = createSpace(deps.dir, name, deps.declaration());
+			// pi-space names a space with its profile; without a matching profile this Pi is plain pi.
+			const qualified = `${deps.profile?.name ?? "pi"}/${name}`;
 			ctx.ui.notify(
-				hasSetupCommand(deps.env)
-					? `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: 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,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 { 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.
+ * A home that a profile of the file names is that profile's, not pi's: inside the Pi of another program those
+ * variables hold that program's home, so pi keeps ~/.pi/agent.
+ */
+function builtInHome(config: Config | undefined, env: Env, home: string): string {
+	const fromEnv = env.PI_SPACES_BASE_HOME || env.PI_CODING_AGENT_DIR;
+	const found = fromEnv ? resolve(home, expandTilde(fromEnv, home)) : undefined;
+	const claimed = (path: string) => config?.profiles.some((spec) => spec.home !== undefined && samePath(resolve(home, expandTilde(spec.home, home)), path));
+	return found !== undefined && !claimed(found) ? found : join(home, ".pi", "agent");
+}
+
+/** Resolves a profile; what a profile omits for `home` falls back to the built-in pi's, and `pi` also gets its `command`. */
+function resolveProfile(config: Config | undefined, spec: ProfileSpec, env: Env, home: string): Profile {
+	const base = spec.home === undefined ? builtInHome(config, env, home) : resolve(home, expandTilde(spec.home, home));
+	const profile: Profile = {
+		name: spec.name,
+		home: base,
+		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(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: 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/context.ts

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

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);
 }