pi-spaces 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,22 @@ commands and options and a patch version fixes.
6
6
 
7
7
  ## Unreleased
8
8
 
9
+ ## 0.18.0
10
+
11
+ ### Changed
12
+
13
+ - `/space new` with a setup command creates only the space's folder, waiting for its setup (a `.pi-space-new` file holds
14
+ the declaration), so the setup command makes `agent/` itself: gentle-shell 4.8 leaves alone a `--home` that already
15
+ has content. `pi-space setup` adds the declaration once the setup succeeds.
16
+
17
+ - The README's gentle-shell profile sets `GENTLE_PI_CONFIG_HOME` to `{space}`: gentle-shell 4.8 adds `gentle-ai` to it,
18
+ so `{space}/gentle-ai` gave `<space>/gentle-ai/gentle-ai`.
19
+
20
+ ### Added
21
+
22
+ - `pi-spaces/spaces` exports `createSpaceRoot`, `markPending`, `finishPending` and `declareInHome`; `spaceHome` and
23
+ `isRooted` count a space waiting for its setup as rooted.
24
+
9
25
  ## 0.17.0
10
26
 
11
27
  ### Added
package/README.md CHANGED
@@ -98,7 +98,7 @@ pi-space remove pi/work # delete it, after asking; keeps a backu
98
98
  pi-space update --every # update the packages of base and of every space of every profile
99
99
  ```
100
100
 
101
- A new space is a folder with an `agent/` folder inside it, empty except for `agent/settings.json`, which declares this package so `/space` works inside it. Sign in and install packages there as you would in a fresh Pi. Spaces made by an older version have no `agent/` folder and keep working as they are; see [Moving an old space](#moving-an-old-space).
101
+ A new space is a folder with an `agent/` folder inside it, empty except for `agent/settings.json`, which declares this package so `/space` works inside it. When the profile has a setup command, `agent/` is left to that command, which makes it (a launcher such as gentle-shell only sets up a home it made itself), and the declaration joins the `settings.json` it wrote. Sign in and install packages there as you would in a fresh Pi. Spaces made by an older version have no `agent/` folder and keep working as they are; see [Moving an old space](#moving-an-old-space).
102
102
 
103
103
  ## Commands in Pi
104
104
 
@@ -106,7 +106,7 @@ A new space is a folder with an `agent/` folder inside it, empty except for `age
106
106
  | --- | --- |
107
107
  | `/space` | Opens a list of the other spaces and restarts Pi in the one you pick. Without the interactive terminal it lists them instead. |
108
108
  | `/space list` | Lists `base` and every space, with `*` on the active one. |
109
- | `/space new <name>` | Creates an empty space (its folder, with `agent/` inside). When a setup command is set (the profile's `commands.setup`, or `PI_SPACES_SETUP`), it names `pi-space setup <profile>/<name>` to run from a shell, with this Pi's profile (`pi` when none matches). |
109
+ | `/space new <name>` | Creates an empty space (its folder, with `agent/` inside). When a setup command is set (the profile's `commands.setup`, or `PI_SPACES_SETUP`), it creates only the folder, waiting for its setup, and names `pi-space setup <profile>/<name>` to run from a shell, with this Pi's profile (`pi` when none matches): the setup makes `agent/`, then the declaration joins its `settings.json`. |
110
110
  | `/space switch <name>` | Restarts Pi in that space. `base` is the home Pi started with. |
111
111
  | `/space switch` | Same as `/space`. |
112
112
  | `/space rename <old> <new>` | Renames a space. The active space cannot be renamed. |
@@ -280,14 +280,14 @@ Keep the `spaceEnv` of the program's own config home: without it, a space's `--h
280
280
 
281
281
  ### Example: gentle-shell
282
282
 
283
- For whoever uses gentle-shell, this is a profile for it. The base runs `gentle-shell` as it is, and each space gets its own config folder, `gentle-ai`, next to its `agent/` folder through `spaceEnv`:
283
+ For whoever uses gentle-shell, this is a profile for it. The base runs `gentle-shell` as it is, and each space gets its own config folder, `gentle-ai`, next to its `agent/` folder through `spaceEnv` (gentle-shell 4.8 adds `gentle-ai` to `GENTLE_PI_CONFIG_HOME`, so it names the space's root; an older gentle-shell took `{space}/gentle-ai`):
284
284
 
285
285
  ```toml
286
286
  schema = "pi-spaces.config/v2"
287
287
 
288
288
  [profiles.gentle]
289
289
  home = "~/.gentle-shell/agent"
290
- spaceEnv = { GENTLE_PI_CONFIG_HOME = "{space}/gentle-ai" }
290
+ spaceEnv = { GENTLE_PI_CONFIG_HOME = "{space}" }
291
291
 
292
292
  [profiles.gentle.commands]
293
293
  base = "gentle-shell"
@@ -308,7 +308,7 @@ setup = "gentle-shell --home {home} setup"
308
308
  "space": "gentle-shell --home {home}",
309
309
  "setup": "gentle-shell --home {home} setup"
310
310
  },
311
- "spaceEnv": { "GENTLE_PI_CONFIG_HOME": "{space}/gentle-ai" }
311
+ "spaceEnv": { "GENTLE_PI_CONFIG_HOME": "{space}" }
312
312
  }
313
313
  }
314
314
  }
package/dist/command.js CHANGED
@@ -11,9 +11,11 @@ import {
11
11
  backupSpace,
12
12
  checkRemovable,
13
13
  createSpace,
14
+ createSpaceRoot,
14
15
 
15
16
  hasSetupCommand,
16
17
  listSpaces,
18
+ markPending,
17
19
 
18
20
  removeSpace,
19
21
  renameSpace,
@@ -65,11 +67,20 @@ export async function runSpaceCommand(args , deps )
65
67
  if (sub === "list" && rest.length === 0) return list(deps);
66
68
  if (sub === "new" && rest.length === 1) {
67
69
  const [name] = rest;
68
- const path = createSpace(deps.dir, name, deps.declaration());
70
+ const withSetup = hasSetupCommand(deps.env) || Boolean(deps.profile?.setup);
71
+ // With a setup command the agent home is left to pi-space setup: a launcher such as gentle-shell only provisions
72
+ // a home it made, and the declaration joins its settings once the setup succeeds.
73
+ let path ;
74
+ if (withSetup) {
75
+ path = createSpaceRoot(deps.dir, name);
76
+ markPending(path, deps.declaration());
77
+ } else {
78
+ path = createSpace(deps.dir, name, deps.declaration());
79
+ }
69
80
  // pi-space names a space with its profile; without a matching profile this Pi is plain pi.
70
81
  const qualified = `${deps.profile?.name ?? "pi"}/${name}`;
71
82
  ctx.ui.notify(
72
- hasSetupCommand(deps.env) || Boolean(deps.profile?.setup)
83
+ withSetup
73
84
  ? `Created space "${name}" at ${path}. Prepare it from a shell with: pi-space setup ${qualified}. Then enter it with /space switch ${name}.`
74
85
  : `Created space "${name}" at ${path}. Enter it with /space switch ${name}.`,
75
86
  "info",
package/dist/spaces.js CHANGED
@@ -8,6 +8,11 @@ import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
8
8
  export const BASE = "base";
9
9
  /** The folder inside a space's root that is its agent home. */
10
10
  export const AGENT = "agent";
11
+ /**
12
+ * The file in a new space's root that waits for its setup command: the space is rooted, but its agent home is left to
13
+ * the setup, and the declaration it holds joins the settings.json the setup wrote once the setup succeeds.
14
+ */
15
+ export const PENDING = ".pi-space-new";
11
16
  const NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
12
17
 
13
18
  export class SpaceError extends Error {
@@ -84,17 +89,21 @@ export function listSpaces(dir ) {
84
89
 
85
90
  /**
86
91
  * The agent home of the space whose root is `root`: `<root>/agent` when that is a real folder (a symlink or a file named
87
- * agent does not count), else the root itself, an old space whose folder is the agent home. Pi's own agent home never has
88
- * a folder named agent, so the folder tells the two layouts apart.
92
+ * agent does not count) or when the space still waits for its setup (PENDING), else the root itself, an old space whose
93
+ * folder is the agent home. Pi's own agent home never has a folder named agent, so the folder tells the two layouts apart.
89
94
  */
90
95
  export function spaceHome(root ) {
91
- const home = join(root, AGENT);
92
- return isRealFolder(home) ? home : root;
96
+ return isRooted(root) ? join(root, AGENT) : root;
93
97
  }
94
98
 
95
- /** True when the space with this root keeps its agent home in `<root>/agent`. */
99
+ /** True when the space with this root keeps its agent home in `<root>/agent`, or will once its setup makes it. */
96
100
  export function isRooted(root ) {
97
- return isRealFolder(join(root, AGENT));
101
+ return isRealFolder(join(root, AGENT)) || isPending(root);
102
+ }
103
+
104
+ /** True when the space with this root waits for its setup command (its root holds PENDING). */
105
+ export function isPending(root ) {
106
+ return existsSync(join(root, PENDING));
98
107
  }
99
108
 
100
109
  /** The space whose agent home is the given one (`<root>/agent`, or the root of an old space), or undefined. */
@@ -122,16 +131,86 @@ function isInside(child , parent ) {
122
131
  * /space works inside it. Returns the root.
123
132
  */
124
133
  export function createSpace(dir , name , declaration ) {
134
+ const path = createSpaceRoot(dir, name);
135
+ declareInHome(join(path, AGENT), declaration);
136
+ return path;
137
+ }
138
+
139
+ /**
140
+ * Creates a space's root alone, without its agent home, so a setup command can make that home itself (a launcher such as
141
+ * gentle-shell only provisions a home it made). Returns the root.
142
+ */
143
+ export function createSpaceRoot(dir , name ) {
125
144
  assertName(name);
126
145
  const path = join(dir, name);
127
146
  if (existsSync(path) || isSymlink(path)) throw new SpaceError(`Space "${name}" already exists.`);
128
147
  mkdirSync(dir, { recursive: true });
129
148
  mkdirSync(path);
130
- mkdirSync(join(path, AGENT));
131
- writeFileSync(join(path, AGENT, "settings.json"), `${JSON.stringify({ packages: [declaration] }, null, 2)}\n`);
132
149
  return path;
133
150
  }
134
151
 
152
+ /**
153
+ * Marks a new space's root as waiting for its setup command, with the declaration to add once it succeeds (none for a
154
+ * space that does not declare this package).
155
+ */
156
+ export function markPending(root , declaration ) {
157
+ writeFileSync(join(root, PENDING), `${JSON.stringify(declaration === undefined ? {} : { declaration }, null, 2)}\n`);
158
+ }
159
+
160
+ /**
161
+ * Finishes a space whose setup succeeded: adds the declaration its PENDING file holds to the settings.json of its agent
162
+ * home (making both when the setup did not) and removes the file. False when the space was not waiting for a setup.
163
+ */
164
+ export function finishPending(root ) {
165
+ const file = join(root, PENDING);
166
+ if (!existsSync(file)) return false;
167
+ let pending ;
168
+ try {
169
+ pending = JSON.parse(readFileSync(file, "utf8"));
170
+ } catch {
171
+ throw new SpaceError(`${file} is not valid JSON; fix or delete it and run pi-space setup again.`);
172
+ }
173
+ declareInHome(join(root, AGENT), pending.declaration);
174
+ rmSync(file);
175
+ return true;
176
+ }
177
+
178
+ function sourceOf(entry ) {
179
+ const source = typeof entry === "string" ? entry : (entry )?.source;
180
+ return typeof source === "string" ? source : undefined;
181
+ }
182
+
183
+ /** Two package sources name the same package: npm sources by package name, whatever their version; others as written. */
184
+ function sameSource(a , b ) {
185
+ if (a === undefined || b === undefined) return false;
186
+ if (a.startsWith("npm:") && b.startsWith("npm:")) return npmName(a) === npmName(b);
187
+ return a === b;
188
+ }
189
+
190
+ /**
191
+ * Makes the agent home when it is missing and adds the declaration to its settings.json, keeping everything already
192
+ * there; a package with the same source is not declared twice. Without a declaration it only makes sure the file exists.
193
+ */
194
+ export function declareInHome(home , declaration ) {
195
+ mkdirSync(home, { recursive: true });
196
+ const file = join(home, "settings.json");
197
+ let settings = {};
198
+ if (existsSync(file)) {
199
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
200
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new SpaceError(`${file} is not a JSON object.`);
201
+ settings = parsed ;
202
+ if (!declaration) return;
203
+ }
204
+ if (declaration) {
205
+ if (settings.packages !== undefined && !Array.isArray(settings.packages)) throw new SpaceError(`${file} has "packages" that is not a list.`);
206
+ const packages = (settings.packages ) ?? [];
207
+ const wanted = sourceOf(declaration);
208
+ if (packages.some((entry) => sameSource(sourceOf(entry), wanted))) return;
209
+ settings.packages = [...packages, declaration];
210
+ }
211
+ writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
212
+ }
213
+
135
214
  function isSymlink(path ) {
136
215
  try {
137
216
  return lstatSync(path).isSymbolicLink();
@@ -267,6 +346,7 @@ export function migrateSpace(
267
346
  ) {
268
347
  assertName(name);
269
348
  const root = join(dir, name);
349
+ if (isPending(root)) throw new SpaceError(`Space "${name}" is waiting for its setup command, which makes its agent home; run pi-space setup.`);
270
350
  if (isRooted(root)) throw new SpaceError(`Space "${name}" already has its agent home in ${join(root, AGENT)}.`);
271
351
  checkRemovable(dir, name, agentHome, protect, userHome, "migrate");
272
352
  const home = join(root, AGENT);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-spaces",
3
- "version": "0.17.0",
3
+ "version": "0.18.0",
4
4
  "description": "Named spaces for Pi: keep several agent homes (sign-ins, packages, settings) and pick one by name.",
5
5
  "license": "MIT",
6
6
  "author": "jals1212",
@@ -35,7 +35,7 @@ Use when a task depends on which Pi agent home this session uses (settings, sign
35
35
  | 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 |
36
36
  | Pin a space to a repository (like `.nvmrc`) | `pi-space pin <profile>/<name>` writes `.pi/pi-space/space` (one line `<profile>/<name>`) and a self-ignoring `.pi/pi-space/.gitignore` in the git root; a bare `pi-space` there or below then starts that space at once (a space named on the command line wins; `pi-space pick` opens the picker); `pi-space pin` alone opens a picker to choose it on a terminal (the pinned space marked `⌂`), `pi-space pin --show` prints it, `pi-space unpin` removes it. From inside Pi, the user can pin this session's own space with `/space pin` and remove it with `/space unpin`. Only `pi-space` reads the marker; Pi and `/space switch` do not |
37
37
  | 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 |
38
- | 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), and asks whether the space declares the extension: pass `--extension` or `--no-extension` when running it for the user, since there is no terminal to answer |
38
+ | 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), which makes `<space>/agent` itself (the declaration is added after it succeeds; `/space new` with a setup command leaves the space waiting until `pi-space setup` runs), and asks whether the space declares the extension: pass `--extension` or `--no-extension` when running it for the user, since there is no terminal to answer |
39
39
  | Prepare a space for the program that runs Pi | `pi-space setup <profile>/<name>` (or `<profile>/base`, `<profile>/--every` for base then its spaces, or `--every` for the base and spaces of every profile with a setup, which pi has not by default; the profile's `commands.setup`): runs the setup command (`{home}` becomes the space's agent home, `{space}` its root folder and `{name}` its name) with the agent home as `PI_CODING_AGENT_DIR`; in base `{home}` is the profile's home and `{name}` is `base` |
40
40
  | Work in another space | User runs `/space switch <name>` (with a v2 profile it runs `commands.space`, or `<commands.base> --space <name>`; `/space switch base` runs `commands.base`; otherwise Pi starts again), or `$PI_SPACES_COMMAND --space <name> "<prompt>"` (only when the command has no `{home}` or `{name}`), or `pi-space <profile>/<name>` from a shell |
41
41
  | Give an old space the `agent/` layout | User request only: `pi-space migrate <profile>/<name>` (or `<profile>/--every`, `--every`): copies the space to `.backups`, then moves its content into `<space>/agent/`; refuses base, the space you are in and a space that already has `agent/` |
package/src/command.ts CHANGED
@@ -11,9 +11,11 @@ import {
11
11
  backupSpace,
12
12
  checkRemovable,
13
13
  createSpace,
14
+ createSpaceRoot,
14
15
  type Env,
15
16
  hasSetupCommand,
16
17
  listSpaces,
18
+ markPending,
17
19
  type PackageDeclaration,
18
20
  removeSpace,
19
21
  renameSpace,
@@ -65,11 +67,20 @@ export async function runSpaceCommand(args: string, deps: SpaceCommandDeps): Pro
65
67
  if (sub === "list" && rest.length === 0) return list(deps);
66
68
  if (sub === "new" && rest.length === 1) {
67
69
  const [name] = rest;
68
- const path = createSpace(deps.dir, name, deps.declaration());
70
+ const withSetup = hasSetupCommand(deps.env) || Boolean(deps.profile?.setup);
71
+ // With a setup command the agent home is left to pi-space setup: a launcher such as gentle-shell only provisions
72
+ // a home it made, and the declaration joins its settings once the setup succeeds.
73
+ let path: string;
74
+ if (withSetup) {
75
+ path = createSpaceRoot(deps.dir, name);
76
+ markPending(path, deps.declaration());
77
+ } else {
78
+ path = createSpace(deps.dir, name, deps.declaration());
79
+ }
69
80
  // pi-space names a space with its profile; without a matching profile this Pi is plain pi.
70
81
  const qualified = `${deps.profile?.name ?? "pi"}/${name}`;
71
82
  ctx.ui.notify(
72
- hasSetupCommand(deps.env) || Boolean(deps.profile?.setup)
83
+ withSetup
73
84
  ? `Created space "${name}" at ${path}. Prepare it from a shell with: pi-space setup ${qualified}. Then enter it with /space switch ${name}.`
74
85
  : `Created space "${name}" at ${path}. Enter it with /space switch ${name}.`,
75
86
  "info",
package/src/spaces.ts CHANGED
@@ -8,6 +8,11 @@ import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
8
8
  export const BASE = "base";
9
9
  /** The folder inside a space's root that is its agent home. */
10
10
  export const AGENT = "agent";
11
+ /**
12
+ * The file in a new space's root that waits for its setup command: the space is rooted, but its agent home is left to
13
+ * the setup, and the declaration it holds joins the settings.json the setup wrote once the setup succeeds.
14
+ */
15
+ export const PENDING = ".pi-space-new";
11
16
  const NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
12
17
 
13
18
  export class SpaceError extends Error {
@@ -84,17 +89,21 @@ export function listSpaces(dir: string): string[] {
84
89
 
85
90
  /**
86
91
  * The agent home of the space whose root is `root`: `<root>/agent` when that is a real folder (a symlink or a file named
87
- * agent does not count), else the root itself, an old space whose folder is the agent home. Pi's own agent home never has
88
- * a folder named agent, so the folder tells the two layouts apart.
92
+ * agent does not count) or when the space still waits for its setup (PENDING), else the root itself, an old space whose
93
+ * folder is the agent home. Pi's own agent home never has a folder named agent, so the folder tells the two layouts apart.
89
94
  */
90
95
  export function spaceHome(root: string): string {
91
- const home = join(root, AGENT);
92
- return isRealFolder(home) ? home : root;
96
+ return isRooted(root) ? join(root, AGENT) : root;
93
97
  }
94
98
 
95
- /** True when the space with this root keeps its agent home in `<root>/agent`. */
99
+ /** True when the space with this root keeps its agent home in `<root>/agent`, or will once its setup makes it. */
96
100
  export function isRooted(root: string): boolean {
97
- return isRealFolder(join(root, AGENT));
101
+ return isRealFolder(join(root, AGENT)) || isPending(root);
102
+ }
103
+
104
+ /** True when the space with this root waits for its setup command (its root holds PENDING). */
105
+ export function isPending(root: string): boolean {
106
+ return existsSync(join(root, PENDING));
98
107
  }
99
108
 
100
109
  /** The space whose agent home is the given one (`<root>/agent`, or the root of an old space), or undefined. */
@@ -122,16 +131,86 @@ function isInside(child: string, parent: string): boolean {
122
131
  * /space works inside it. Returns the root.
123
132
  */
124
133
  export function createSpace(dir: string, name: string, declaration: PackageDeclaration): string {
134
+ const path = createSpaceRoot(dir, name);
135
+ declareInHome(join(path, AGENT), declaration);
136
+ return path;
137
+ }
138
+
139
+ /**
140
+ * Creates a space's root alone, without its agent home, so a setup command can make that home itself (a launcher such as
141
+ * gentle-shell only provisions a home it made). Returns the root.
142
+ */
143
+ export function createSpaceRoot(dir: string, name: string): string {
125
144
  assertName(name);
126
145
  const path = join(dir, name);
127
146
  if (existsSync(path) || isSymlink(path)) throw new SpaceError(`Space "${name}" already exists.`);
128
147
  mkdirSync(dir, { recursive: true });
129
148
  mkdirSync(path);
130
- mkdirSync(join(path, AGENT));
131
- writeFileSync(join(path, AGENT, "settings.json"), `${JSON.stringify({ packages: [declaration] }, null, 2)}\n`);
132
149
  return path;
133
150
  }
134
151
 
152
+ /**
153
+ * Marks a new space's root as waiting for its setup command, with the declaration to add once it succeeds (none for a
154
+ * space that does not declare this package).
155
+ */
156
+ export function markPending(root: string, declaration?: PackageDeclaration): void {
157
+ writeFileSync(join(root, PENDING), `${JSON.stringify(declaration === undefined ? {} : { declaration }, null, 2)}\n`);
158
+ }
159
+
160
+ /**
161
+ * Finishes a space whose setup succeeded: adds the declaration its PENDING file holds to the settings.json of its agent
162
+ * home (making both when the setup did not) and removes the file. False when the space was not waiting for a setup.
163
+ */
164
+ export function finishPending(root: string): boolean {
165
+ const file = join(root, PENDING);
166
+ if (!existsSync(file)) return false;
167
+ let pending: { declaration?: PackageDeclaration };
168
+ try {
169
+ pending = JSON.parse(readFileSync(file, "utf8"));
170
+ } catch {
171
+ throw new SpaceError(`${file} is not valid JSON; fix or delete it and run pi-space setup again.`);
172
+ }
173
+ declareInHome(join(root, AGENT), pending.declaration);
174
+ rmSync(file);
175
+ return true;
176
+ }
177
+
178
+ function sourceOf(entry: unknown): string | undefined {
179
+ const source = typeof entry === "string" ? entry : (entry as { source?: unknown } | null)?.source;
180
+ return typeof source === "string" ? source : undefined;
181
+ }
182
+
183
+ /** Two package sources name the same package: npm sources by package name, whatever their version; others as written. */
184
+ function sameSource(a: string | undefined, b: string | undefined): boolean {
185
+ if (a === undefined || b === undefined) return false;
186
+ if (a.startsWith("npm:") && b.startsWith("npm:")) return npmName(a) === npmName(b);
187
+ return a === b;
188
+ }
189
+
190
+ /**
191
+ * Makes the agent home when it is missing and adds the declaration to its settings.json, keeping everything already
192
+ * there; a package with the same source is not declared twice. Without a declaration it only makes sure the file exists.
193
+ */
194
+ export function declareInHome(home: string, declaration?: PackageDeclaration): void {
195
+ mkdirSync(home, { recursive: true });
196
+ const file = join(home, "settings.json");
197
+ let settings: Record<string, unknown> = {};
198
+ if (existsSync(file)) {
199
+ const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
200
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new SpaceError(`${file} is not a JSON object.`);
201
+ settings = parsed as Record<string, unknown>;
202
+ if (!declaration) return;
203
+ }
204
+ if (declaration) {
205
+ if (settings.packages !== undefined && !Array.isArray(settings.packages)) throw new SpaceError(`${file} has "packages" that is not a list.`);
206
+ const packages = (settings.packages as unknown[] | undefined) ?? [];
207
+ const wanted = sourceOf(declaration);
208
+ if (packages.some((entry) => sameSource(sourceOf(entry), wanted))) return;
209
+ settings.packages = [...packages, declaration];
210
+ }
211
+ writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
212
+ }
213
+
135
214
  function isSymlink(path: string): boolean {
136
215
  try {
137
216
  return lstatSync(path).isSymbolicLink();
@@ -267,6 +346,7 @@ export function migrateSpace(
267
346
  ): Migration {
268
347
  assertName(name);
269
348
  const root = join(dir, name);
349
+ if (isPending(root)) throw new SpaceError(`Space "${name}" is waiting for its setup command, which makes its agent home; run pi-space setup.`);
270
350
  if (isRooted(root)) throw new SpaceError(`Space "${name}" already has its agent home in ${join(root, AGENT)}.`);
271
351
  checkRemovable(dir, name, agentHome, protect, userHome, "migrate");
272
352
  const home = join(root, AGENT);