@awebai/oats 0.66.0 → 0.67.1
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/bin/oats.mjs +66 -13
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +217 -6
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +6 -5
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/servers.md +3 -2
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +570 -176
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +1 -1
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +5 -1
- package/lib/materialize.mjs +62 -11
- package/lib/servers.mjs +15 -6
- package/lib/soul-composition.mjs +7 -3
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +37 -5
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +3 -1
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +85 -24
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +62 -9
- package/packages/client/spawn-naming.mjs +31 -0
- package/packages/client/spawn-preview-cli.mjs +22 -7
- package/packages/client/spawn-preview-contract.mjs +24 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +47 -2
- package/packages/tui/README.md +3 -3
- package/packages/tui/lib/actions.mjs +57 -14
- package/packages/tui/lib/client.mjs +8 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +40 -13
- package/packages/tui/lib/model.mjs +167 -63
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +148 -54
- package/packages/tui/lib/term/keys.mjs +19 -5
- package/packages/tui/lib/term/kitty.mjs +36 -11
- package/packages/tui/lib/term/through.mjs +61 -28
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +109 -26
- package/packages/tui/lib/views/instances.mjs +59 -20
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/skills/oats-getting-started/SKILL.md +13 -8
package/docs/upgrading.md
CHANGED
|
@@ -1,5 +1,44 @@
|
|
|
1
1
|
# Upgrading OATS on a host
|
|
2
2
|
|
|
3
|
+
This page opens with the upgrade to the latest version. The steps that are
|
|
4
|
+
the same for every release follow, then what each older release asks of a
|
|
5
|
+
host that comes from it.
|
|
6
|
+
|
|
7
|
+
## Upgrading to the latest version
|
|
8
|
+
|
|
9
|
+
The latest version is **OATS 0.67.1** ([release notes](release-notes/v0.67.1.md)).
|
|
10
|
+
The 0.67.1 Desktop accepts OATS CLIs `>=0.26.0 <0.68.0`.
|
|
11
|
+
|
|
12
|
+
**First, read the `## Upgrade` section of every release after yours, up to
|
|
13
|
+
0.67.1,** in the [release notes](release-notes/): it says what to do before
|
|
14
|
+
the CLI changes, and what else must change with it (the Desktop, another
|
|
15
|
+
tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
|
|
16
|
+
names the releases that ask for more than the steps below. `oats version`
|
|
17
|
+
prints the version you have.
|
|
18
|
+
|
|
19
|
+
Then, on each host:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
# 0. where the Desktop is installed: Desktop 0.67.1 first
|
|
23
|
+
npm install -g @awebai/oats@0.67.1 # 1. the CLI
|
|
24
|
+
oats update # 2. in each deployment: the plan, then it asks before it runs
|
|
25
|
+
oats doctor # 3. in the same deployment
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The Desktop's installers are the assets of the
|
|
29
|
+
[GitHub Release](https://github.com/awebai/oats/releases) of that version
|
|
30
|
+
([OATS Desktop](desktop.md#install)). Then restart the pi sessions that were
|
|
31
|
+
running: a session keeps the bridge it loaded when it started.
|
|
32
|
+
[The steps](#the-steps) says what each step does and why they come in this
|
|
33
|
+
order.
|
|
34
|
+
|
|
35
|
+
An agent with the oats.setup capability does this with you through its
|
|
36
|
+
`/oats-upgrade` skill. It reads this page and the release notes at the
|
|
37
|
+
latest release's tag, never the copy in the installed CLI, which describes
|
|
38
|
+
the version you are upgrading from.
|
|
39
|
+
|
|
40
|
+
## The steps
|
|
41
|
+
|
|
3
42
|
Upgrading OATS means three things, in this order, on each host, and one
|
|
4
43
|
before them where the Desktop is installed:
|
|
5
44
|
|
|
@@ -14,17 +53,14 @@ must be at the same version: a pi session with an older bridge runs old
|
|
|
14
53
|
extension code against a new kernel. A host that launches no pi instance has
|
|
15
54
|
no bridge, and step 2 has nothing to move.
|
|
16
55
|
|
|
17
|
-
**A release's own steps are in its notes
|
|
18
|
-
|
|
19
|
-
[release notes](release-notes/) first: it says what to do before the CLI
|
|
20
|
-
changes, and what else must change with it (the Desktop, another tool, a
|
|
21
|
-
package pin). This page is the part that is the same for every release.
|
|
56
|
+
**A release's own steps are in its notes**, in its `## Upgrade` section.
|
|
57
|
+
This page is the part that is the same for every release.
|
|
22
58
|
|
|
23
59
|
**Why the Desktop goes first.** A Desktop accepts a CLI up to its own minor
|
|
24
60
|
version and refuses a newer one: with the CLI moved first, the Desktop that
|
|
25
61
|
is still running lists no instance until it is replaced. The new Desktop
|
|
26
62
|
accepts the older CLI in the meantime. The CLI can move by two commands, the
|
|
27
|
-
`npm install`
|
|
63
|
+
`npm install` and an `oats update` whose plan installs it: step 0 comes
|
|
28
64
|
before either.
|
|
29
65
|
|
|
30
66
|
**Package versions are a different thing.** `oats update` moves the CLI and
|
|
@@ -32,18 +68,8 @@ the bridge, never a package. A deployment's capabilities come from the
|
|
|
32
68
|
packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
|
|
33
69
|
([Packages](packages.md)).
|
|
34
70
|
|
|
35
|
-
## The steps
|
|
36
|
-
|
|
37
|
-
```sh
|
|
38
|
-
# 0. where the Desktop is installed: the new version's Desktop first
|
|
39
|
-
npm install -g @awebai/oats # 1. the CLI
|
|
40
|
-
oats update # 2. in a deployment: the plan, then it asks before it runs
|
|
41
|
-
oats doctor # 3. in the same deployment
|
|
42
|
-
```
|
|
43
|
-
|
|
44
71
|
Run steps 2 and 3 in every deployment on the host, or name one from anywhere
|
|
45
|
-
with `oats update --dir <deployment>`.
|
|
46
|
-
running: a session keeps the bridge it loaded when it started.
|
|
72
|
+
with `oats update --dir <deployment>`.
|
|
47
73
|
|
|
48
74
|
In a terminal, `oats update` shows its plan and asks before it runs anything.
|
|
49
75
|
Without a terminal (a script, an agent's shell) it runs only with `--yes`.
|
|
@@ -74,7 +100,66 @@ Versions are compared as semver, so a prerelease is below its release:
|
|
|
74
100
|
no other version: a local build `0.53.0+build.1` is `0.53.0`, and nothing is
|
|
75
101
|
installed over it.
|
|
76
102
|
|
|
77
|
-
##
|
|
103
|
+
## Coming from an older version
|
|
104
|
+
|
|
105
|
+
Read the `## Upgrade` section of every release after yours, up to the
|
|
106
|
+
latest: each release's own steps are there, and only there. This list is a
|
|
107
|
+
guide to them, not a replacement: it names, newest first, the releases whose
|
|
108
|
+
Upgrade section asks a host for more than [the steps](#the-steps), the order
|
|
109
|
+
of the Desktop and the CLI, and an optional package pin. A change a script
|
|
110
|
+
must follow is in its release's Upgrade section whether or not it is listed
|
|
111
|
+
here.
|
|
112
|
+
|
|
113
|
+
- **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
|
|
114
|
+
0.67.1:** the leader is Ctrl+X in OATS Desktop and in `oats tui`, on every
|
|
115
|
+
platform; a leader you rebound is kept. A `tui.json` that gives `ctrl+x` to an action and names no leader
|
|
116
|
+
stops `oats tui` from starting: give that action another key, or name a
|
|
117
|
+
leader ([Change the keys](tui.md#change-the-keys-tuijson)). On Linux and
|
|
118
|
+
Windows the shared shortcuts are Ctrl+Alt; a terminal that passes
|
|
119
|
+
Ctrl+Shift apart from Ctrl takes the Ctrl+Shift option.
|
|
120
|
+
- **[0.66.0](release-notes/v0.66.0.md#upgrade):** `oats tui` moves its key
|
|
121
|
+
file to `~/.oats/config/tui.json`; `oats server connect` needs `--dir`.
|
|
122
|
+
- **[0.62.0](release-notes/v0.62.0.md#upgrade):** after the CLI, run
|
|
123
|
+
`oats setup` once per user on each host, from that user's shell: the
|
|
124
|
+
capture service ([Capture service release order](#capture-service-release-order)).
|
|
125
|
+
- **[0.61.0](release-notes/v0.61.0.md#upgrade):** restart a pi instance stuck
|
|
126
|
+
on its opening task once the bridge has moved; `oats onboard`'s
|
|
127
|
+
`next.spawn` names the soul that holds oats.setup.
|
|
128
|
+
- **[0.60.0](release-notes/v0.60.0.md#upgrade):** `running` in
|
|
129
|
+
`oats status --json` means the harness is running.
|
|
130
|
+
- **[0.59.0](release-notes/v0.59.0.md#upgrade):** with oats.aweb 1.28.0, a
|
|
131
|
+
host that needs the wake broker installs it once (`oats aweb wake install`,
|
|
132
|
+
from its own login session); `oats tui`'s back key is pressed twice.
|
|
133
|
+
- **[0.58.0](release-notes/v0.58.0.md#upgrade):** on a Mac, upgrade the CLI
|
|
134
|
+
before the next reboot.
|
|
135
|
+
- **[0.57.1](release-notes/v0.57.1.md#upgrade):** upgrade the hosts a Desktop
|
|
136
|
+
reaches over `--server` too; `oats tui`'s panel needs tmux 3.2 or later.
|
|
137
|
+
- **[0.57.0](release-notes/v0.57.0.md#upgrade):** a retire plan taken before
|
|
138
|
+
the upgrade is refused once (`E_PLAN_STALE`); `oats worktree remove` may
|
|
139
|
+
refuse with `E_CHILDREN_RUNNING`; with oats.okf 5.2.0, new spawns carry the
|
|
140
|
+
harvest duty unless the soul opts out.
|
|
141
|
+
- **[0.56.0](release-notes/v0.56.0.md#upgrade):** new refusal codes for
|
|
142
|
+
scripts; `open-workspace` in `tui.json` is `open`; a launch gets only its
|
|
143
|
+
capabilities' declared environment.
|
|
144
|
+
- **[0.55.1](release-notes/v0.55.1.md#upgrade):** pin oats.aweb 1.27.3 and run
|
|
145
|
+
`oats sync`: on 1.27.2, readiness reports every home the host wake broker
|
|
146
|
+
serves as `unavailable`.
|
|
147
|
+
- **[0.55.0](release-notes/v0.55.0.md#upgrade):** the first capture after the
|
|
148
|
+
upgrade takes longer.
|
|
149
|
+
- **[0.53.0](release-notes/v0.53.0.md#upgrade):** from 0.51 or earlier, do
|
|
150
|
+
0.52.0's steps first (aw 1.36.33 or later, before `oats sync`); once the
|
|
151
|
+
CLI is 0.53.0, run `oats update` in each deployment that launches pi (an
|
|
152
|
+
older CLI's `oats update` moves the default pi folder only); run
|
|
153
|
+
`oats setup` again where it was run; restart Claude Code instances on a
|
|
154
|
+
Homebrew `node`; rerun `oats aweb resident create` for an existing
|
|
155
|
+
resident custody unit; `oats doctor` names unmatched `souls.launch` keys.
|
|
156
|
+
|
|
157
|
+
**Coming from before 0.53.0:** read the whole notes of every release after
|
|
158
|
+
yours: up to 0.39.0 the section may be called `## Upgrading` or
|
|
159
|
+
`## Upgrading from <version>`, and some releases give their order under
|
|
160
|
+
another heading (0.49.0's oats.okf 5.0 cutover, for one).
|
|
161
|
+
|
|
162
|
+
### Capture service release order
|
|
78
163
|
|
|
79
164
|
The bounded periodic capture service (service A) is **not shipped in
|
|
80
165
|
[0.56.0](release-notes/v0.56.0.md) through [0.61.0](release-notes/v0.61.0.md)**
|
|
@@ -85,16 +170,13 @@ existing capture watcher, and upgrading to any of them does not install the
|
|
|
85
170
|
periodic service. The capture algorithms and recovery commands already
|
|
86
171
|
released do not prove that migration happened.
|
|
87
172
|
|
|
88
|
-
For those released versions, follow their own Upgrade sections and
|
|
89
|
-
|
|
90
|
-
Desktop accepts CLIs `>=0.26.0 <0.62.0`, and a 0.60 Desktop refuses a 0.61.0 CLI.
|
|
173
|
+
For those released versions, follow their own Upgrade sections and
|
|
174
|
+
[the steps](#the-steps), the target Desktop before the CLI.
|
|
91
175
|
|
|
92
176
|
Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
|
|
93
177
|
release. Read 0.62.0's Upgrade section and keep this order: install the
|
|
94
|
-
Desktop of the release you upgrade to first (
|
|
95
|
-
|
|
96
|
-
Desktop `>=0.26.0 <0.65.0`, the 0.65.0 Desktop `>=0.26.0 <0.66.0`, the 0.66.0 Desktop `>=0.26.0 <0.67.0`), then that
|
|
97
|
-
release's CLI and matching pi bridge. Only **after
|
|
178
|
+
Desktop of the release you upgrade to first (its notes give the CLIs
|
|
179
|
+
it accepts), then that release's CLI and matching pi bridge. Only **after
|
|
98
180
|
installing that CLI**, run its setup conversion once per user on each host,
|
|
99
181
|
from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
|
|
100
182
|
watcher is replaced by the periodic service; foreign or disabled definitions
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.13.
|
|
57
|
+
oats.framework: v1.13.5 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.2.1
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
@@ -180,13 +180,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
|
|
|
180
180
|
* declaration may not cover them: these exact names, and every exact name
|
|
181
181
|
* starting with one of these prefixes (the events log; the stop, restart and
|
|
182
182
|
* start receipts and locks; the rollback marker; AGENTS.md backups; the
|
|
183
|
-
* attachments directory). This is the one list: a new kernel-written top-level
|
|
183
|
+
* attachments directory; the instance colour, `.oats-color.json`). This is the one list: a new kernel-written top-level
|
|
184
184
|
* home entry MUST be added here and to the `not` patterns of
|
|
185
185
|
* `retirement.disposable.home` in docs/capability-manifest.schema.json. A
|
|
186
186
|
* prefix declaration can reach none of them except through `.oats-`, which is
|
|
187
187
|
* refused whole; `.oats-<provider>` as an exact name stays declarable. */
|
|
188
188
|
const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
|
|
189
|
-
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments"];
|
|
189
|
+
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color"];
|
|
190
190
|
|
|
191
191
|
/** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
|
|
192
192
|
* name or prefix), "kernel-owned", or undefined when it is sound. */
|
package/lib/core.mjs
CHANGED
|
@@ -50,6 +50,7 @@ import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
|
|
|
50
50
|
import { createSessionPaneInspector, inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
|
|
51
51
|
import { appendEvent, incarnationOf, liveWaiting, recordStartBoundary, retireRefusedReason } from "./instance-events.mjs";
|
|
52
52
|
import { killGroup } from "./process-group.mjs";
|
|
53
|
+
import { NAMING_TIMEOUT_MS, suggestInstanceName } from "./instance-naming.mjs";
|
|
53
54
|
import { interruptExitStatus, isStartToken, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
|
|
54
55
|
import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, claimUnheld, claimWrite, readClaim, releaseClaim, removeGoneClaim, shownHolder, unwritableCode } from "./claim.mjs";
|
|
55
56
|
import { isInstant as isInstantString, readRetireState } from "./retire-state.mjs";
|
|
@@ -62,6 +63,7 @@ import { PANE_PATH_FIX, harnessNotOnPanePath, harnessUnavailable, launchConfigAm
|
|
|
62
63
|
import { shq, shellWord } from "./shell-word.mjs";
|
|
63
64
|
import { CONFIG_DIR_VAR, HARNESS_FOLDER_VAR, claudeTrusts, codexTrustsRoot, harnessConfigFile, harnessTrustWarning, launchConfigFolder } from "./harness-trust.mjs";
|
|
64
65
|
async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
|
|
66
|
+
async function plannedSkillsDefault(prepared) { const m = await import("./instance-resolution.mjs"); return m.plannedPreparedSkills(prepared); }
|
|
65
67
|
// Capability rows for a PREPARED spawn (workspace model): the one function that
|
|
66
68
|
// turns a Resolution's modules into the row shape hooks/environment/requirements/
|
|
67
69
|
// retirement consume. Called twice per spawn — PLANNED before the home exists
|
|
@@ -90,6 +92,7 @@ import { assertSameWorktreeHead, gitRead, gitRefPresence, gitRepoRead, gitRepoRu
|
|
|
90
92
|
import { systemTool } from "./system-tools.mjs";
|
|
91
93
|
import { creatorPlacement, serverScopePlan, serverScopeUnit, serverScopeWarning } from "./tmux-server-scope.mjs";
|
|
92
94
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
95
|
+
import { readInstanceColor } from "./instance-color.mjs";
|
|
93
96
|
/** The package and capability id grammar (namespaced, lowercase): an id names a
|
|
94
97
|
* directory (a home's module copy), so no path spelling fits it. */
|
|
95
98
|
const PACKAGE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
|
|
@@ -608,7 +611,9 @@ export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME
|
|
|
608
611
|
"OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS", "OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS", "OATS_TEST_PROCESS_START_PS",
|
|
609
612
|
// The test seams of #915: the cgroup the kernel judges itself in, and the directories its systemd-run
|
|
610
613
|
// comes from (lib/tmux-server-scope.mjs, lib/system-tools.mjs).
|
|
611
|
-
"OATS_TEST_CGROUP", "OATS_TEST_SYSTEM_TOOL_DIRS"
|
|
614
|
+
"OATS_TEST_CGROUP", "OATS_TEST_SYSTEM_TOOL_DIRS",
|
|
615
|
+
// The test seam of #1421 §3: the naming call's time limit (lib/instance-naming.mjs NAMING_TIMEOUT_MS).
|
|
616
|
+
"OATS_TEST_NAMING_TIMEOUT_MS"]);
|
|
612
617
|
export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
|
|
613
618
|
const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
|
|
614
619
|
export function validateLaunchConfig(name, entry, where) {
|
|
@@ -3822,6 +3827,20 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3822
3827
|
}
|
|
3823
3828
|
}
|
|
3824
3829
|
|
|
3830
|
+
// --suggest-name (feature spawn-suggest-name, awebai/oats#1421 §3): a preview that also chooses the
|
|
3831
|
+
// name, by a naming call through this launch's harness and executable, under its environment, after
|
|
3832
|
+
// the preflight's probes and within its one budget (below, where the executable is known). Until
|
|
3833
|
+
// then the preview proceeds with the numbered name, holding any refusal that is that name's own
|
|
3834
|
+
// (`provisional`); a suggested name is then placed exactly as `--name <suggested>` is, so the
|
|
3835
|
+
// preview's instance, home, branch and decision are that preview's, and an apply with `--name
|
|
3836
|
+
// <instance> --expect-decision <revision>` matches it. Otherwise the numbered name stands, its held
|
|
3837
|
+
// refusal with it. `naming` says which, and why; a failed call is never an error.
|
|
3838
|
+
let naming, provisional;
|
|
3839
|
+
const suggesting = o.suggestName === true;
|
|
3840
|
+
if (suggesting) {
|
|
3841
|
+
if (o.preview !== true) throw oatsError("E_BAD_ARGS", "--suggest-name is a preview's: it chooses the name a spawn would get; pass --preview");
|
|
3842
|
+
if (o.name !== undefined || o.purpose !== undefined || o.instance !== undefined) throw oatsError("E_BAD_ARGS", "--suggest-name chooses the name: it takes no --name or --purpose");
|
|
3843
|
+
}
|
|
3825
3844
|
if (o.name !== undefined && (o.purpose !== undefined || o.instance !== undefined)) throw oatsError("E_BAD_ARGS", "name and purpose are mutually exclusive: --name is the exact instance name, --purpose derives <soul>-<purpose>");
|
|
3826
3845
|
let instance;
|
|
3827
3846
|
if (o.name !== undefined) instance = explicitInstanceName(o.name);
|
|
@@ -3951,6 +3970,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3951
3970
|
// too, since the anchor's instance.json is re-pointed.
|
|
3952
3971
|
let anchorHome;
|
|
3953
3972
|
let anchorRoot;
|
|
3973
|
+
let reverseShadow = () => null;
|
|
3954
3974
|
if (relativeTo) {
|
|
3955
3975
|
const hits = [];
|
|
3956
3976
|
for (const h of findInstanceHomes(root, relativeTo)) hits.push({ root, home: h.home });
|
|
@@ -3985,11 +4005,16 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3985
4005
|
// relation=parent re-points the ANCHOR at the NEW instance by bare name:
|
|
3986
4006
|
// that reverse edge must round-trip from the ANCHOR's root as well.
|
|
3987
4007
|
if (relation === "parent") {
|
|
3988
|
-
const rev = findInstanceHome(chosen.root, instance);
|
|
3989
4008
|
// The new instance does not exist yet — a hit here IS a shadow.
|
|
3990
|
-
|
|
3991
|
-
|
|
3992
|
-
|
|
4009
|
+
reverseShadow = (name) => {
|
|
4010
|
+
const rev = findInstanceHome(chosen.root, name);
|
|
4011
|
+
return rev ? Object.assign(
|
|
4012
|
+
new Error(`relation "parent": an existing instance named "${name}" (${rev.home}) would shadow the new instance from the anchor's root — the re-pointed edge would resolve to the wrong instance; pick a different --purpose or --name`),
|
|
4013
|
+
{ code: "E_RELATIVE_AMBIGUOUS" }) : null;
|
|
4014
|
+
};
|
|
4015
|
+
const shadow = reverseShadow(instance);
|
|
4016
|
+
if (shadow && !suggesting) throw shadow;
|
|
4017
|
+
provisional ??= shadow ?? undefined;
|
|
3993
4018
|
}
|
|
3994
4019
|
}
|
|
3995
4020
|
}
|
|
@@ -4070,47 +4095,54 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4070
4095
|
}
|
|
4071
4096
|
}
|
|
4072
4097
|
|
|
4073
|
-
|
|
4074
|
-
|
|
4075
|
-
|
|
4076
|
-
|
|
4077
|
-
|
|
4078
|
-
|
|
4079
|
-
|
|
4080
|
-
|
|
4081
|
-
|
|
4082
|
-
|
|
4083
|
-
|
|
4084
|
-
|
|
4085
|
-
|
|
4086
|
-
|
|
4087
|
-
|
|
4088
|
-
|
|
4089
|
-
|
|
4090
|
-
|
|
4091
|
-
|
|
4092
|
-
|
|
4093
|
-
|
|
4094
|
-
|
|
4095
|
-
|
|
4096
|
-
|
|
4097
|
-
|
|
4098
|
-
|
|
4099
|
-
|
|
4098
|
+
// The home and its placement checks, for a name: the numbered one here, a suggested one again below.
|
|
4099
|
+
const place = (name) => {
|
|
4100
|
+
const home = join(agent._dir, "instances", name);
|
|
4101
|
+
// A home that exists already is the same refusal as losing the exclusive mkdir below (a
|
|
4102
|
+
// concurrent apply that got there first, or anything else): E_PLACEMENT_TAKEN, nothing created.
|
|
4103
|
+
if (existsSync(home)) throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${name} already exists at ${home}; nothing was created by this call`), { instance: name, home });
|
|
4104
|
+
// AUTHORITATIVE placement check, on the DESTINATION rather than on lexical
|
|
4105
|
+
// paths, immediately before the first side effect. The earlier root/agent-dir
|
|
4106
|
+
// checks are lexical and can be walked around by a symlink anywhere along the
|
|
4107
|
+
// way — `agents/alias -> <linked-worktree>/agents/dev`, or a pre-existing
|
|
4108
|
+
// `agent._dir/instances` symlink — which classifies as the primary checkout
|
|
4109
|
+
// while the home is really created in the worktree (reviewer-249aa7b).
|
|
4110
|
+
// Resolving through the nearest existing ancestor is what closes that.
|
|
4111
|
+
const homeReal = realPathOrNearest(home);
|
|
4112
|
+
const homeCanonical = canonicalDeploymentPath(homeReal);
|
|
4113
|
+
if (resolve(homeCanonical) !== resolve(homeReal)) {
|
|
4114
|
+
throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} resolves to ${homeReal}, inside a linked Git worktree — homes must be created in the primary checkout (${homeCanonical}); a symlink on the path to the agent directory or its instances/ dir does not change where the home really lands`);
|
|
4115
|
+
}
|
|
4116
|
+
// CONTAINMENT, which the check above does not give. canonicalDeploymentPath
|
|
4117
|
+
// only redirects paths inside a LINKED WORKTREE; an escape to a directory Git
|
|
4118
|
+
// does not own at all comes back unchanged and passed (reviewer-aggregate2 —
|
|
4119
|
+
// reproduced: a pre-existing `instances/` symlink to a sibling temp dir spawned
|
|
4120
|
+
// successfully, reporting a home under the deployment while the real one, with
|
|
4121
|
+
// the capability credentials a hook writes into it, was created outside).
|
|
4122
|
+
// The home must BE the immediate `instances/` child of the resolved agent
|
|
4123
|
+
// directory, and that directory must live in this deployment.
|
|
4124
|
+
const withinDir = (child, parent) => {
|
|
4125
|
+
const rel = relative(parent, child);
|
|
4126
|
+
return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
|
|
4127
|
+
};
|
|
4128
|
+
const agentDirReal = realPathOrNearest(agent._dir);
|
|
4129
|
+
// The only base is the agents root: souls and capability-defined agents alike
|
|
4130
|
+
// live directly under it (the 0.25 local-agents/ bases are gone). The root itself
|
|
4131
|
+
// may legitimately be a symlink (it is the deployment anchor, and OATS is pointed
|
|
4132
|
+
// AT it); the agent dirs OATS derives from it may not lead somewhere else.
|
|
4133
|
+
const allowedBases = [realPathOrNearest(root)];
|
|
4134
|
+
if (!allowedBases.some((b) => withinDir(agentDirReal, b))) {
|
|
4135
|
+
throw oatsError("E_NO_CANONICAL_ROOT", `agent directory for "${agent.name}" resolves to ${agentDirReal}, which is outside this deployment (${allowedBases.join(", ")}) — a symlinked agent directory would place the home, and any capability credentials written into it, outside the deployment entirely`);
|
|
4136
|
+
}
|
|
4137
|
+
const expectedHome = join(agentDirReal, "instances", name);
|
|
4138
|
+
if (resolve(homeReal) !== resolve(expectedHome)) {
|
|
4139
|
+
throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} resolves to ${homeReal}, not to ${expectedHome} — a symlinked instances/ directory does not change where the home really lands, and OATS will not create an instance (or the capability credentials that go in it) outside the agent's own directory`);
|
|
4140
|
+
}
|
|
4141
|
+
return { home, homeReal, expectedHome };
|
|
4100
4142
|
};
|
|
4101
|
-
|
|
4102
|
-
|
|
4103
|
-
|
|
4104
|
-
// may legitimately be a symlink (it is the deployment anchor, and OATS is pointed
|
|
4105
|
-
// AT it); the agent dirs OATS derives from it may not lead somewhere else.
|
|
4106
|
-
const allowedBases = [realPathOrNearest(root)];
|
|
4107
|
-
if (!allowedBases.some((b) => withinDir(agentDirReal, b))) {
|
|
4108
|
-
throw oatsError("E_NO_CANONICAL_ROOT", `agent directory for "${agent.name}" resolves to ${agentDirReal}, which is outside this deployment (${allowedBases.join(", ")}) — a symlinked agent directory would place the home, and any capability credentials written into it, outside the deployment entirely`);
|
|
4109
|
-
}
|
|
4110
|
-
const expectedHome = join(agentDirReal, "instances", instance);
|
|
4111
|
-
if (resolve(homeReal) !== resolve(expectedHome)) {
|
|
4112
|
-
throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} resolves to ${homeReal}, not to ${expectedHome} — a symlinked instances/ directory does not change where the home really lands, and OATS will not create an instance (or the capability credentials that go in it) outside the agent's own directory`);
|
|
4113
|
-
}
|
|
4143
|
+
let home, homeReal, expectedHome;
|
|
4144
|
+
try { ({ home, homeReal, expectedHome } = place(instance)); }
|
|
4145
|
+
catch (e) { if (!suggesting) throw e; provisional ??= e; home = join(agent._dir, "instances", instance); }
|
|
4114
4146
|
// Compose and PREFLIGHT before the home exists. Composition is pure (it only
|
|
4115
4147
|
// reads the soul, config chain and capability content), so resolving it here
|
|
4116
4148
|
// lets every "declared but missing" failure happen with zero side effects to
|
|
@@ -4132,8 +4164,14 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4132
4164
|
// Where this launch will run (launchEnvironment): what its configuration sets, else its pane's.
|
|
4133
4165
|
// `expectedEnv` is the preflight's answer, over the pane this plan expects; the launch reads the
|
|
4134
4166
|
// session it actually gets (below). A spawn that launches nothing has no pane to read.
|
|
4135
|
-
|
|
4136
|
-
|
|
4167
|
+
// The pane's working directory only resolves the relative entries of its PATH and its harness
|
|
4168
|
+
// configuration folders. While the name is open (a suggesting preview), a sibling of the homes that
|
|
4169
|
+
// no instance can be named stands in for the home: its `..` entries resolve as the home's do, and
|
|
4170
|
+
// nothing is inside either, so the executable and the probes are the ones the final home would get,
|
|
4171
|
+
// and the naming call runs that same executable.
|
|
4172
|
+
const paneCwd = suggesting ? join(agent._dir, "instances", ".oats-suggest-name") : home;
|
|
4173
|
+
const launchEnvOn = (pane, removed = []) => launchEnvironment({ configEnv: launchConfig?.env, configName: launchConfig?.name, removed, env: process.env, pane, cwd: paneCwd });
|
|
4174
|
+
const expectedEnv = launchEnvOn(launch ? () => expectedPaneEnvironment(tmuxSessionPlan, session, undefined, paneCwd) : NO_LAUNCH);
|
|
4137
4175
|
// A launched harness is looked up where its pane will look it up (launchLookup): this is the
|
|
4138
4176
|
// preflight against the expected PATH; the launch looks again on the session it gets. Without a
|
|
4139
4177
|
// launch (or a known destination) the lookup is this process's PATH, as before.
|
|
@@ -4174,8 +4212,33 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4174
4212
|
const note = unestablishedNote(expectedEnv, [...new Set(checks.flatMap(([, names]) => names))]);
|
|
4175
4213
|
return note ? `${checks.map(([what]) => what).join(", ")}: ${note}` : null;
|
|
4176
4214
|
};
|
|
4177
|
-
if (o.preview === true) { preflight = { status: previewPreflightBudget?.exhausted ? "timeout" : "complete", budgetMs: preflightBudgetMs, elapsedMs: Date.now() - preflightStarted }; previewPreflightBudget = null; }
|
|
4178
4215
|
const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
|
|
4216
|
+
// The naming call (#1421 §3): the probes have run, so it takes what is left of their budget (at most
|
|
4217
|
+
// its own 20 s). Its time counts in the preflight's elapsedMs, but the preflight's status stays its
|
|
4218
|
+
// checks': a call the budget ends is `naming.reason` "timeout", and the numbered preview it leaves is
|
|
4219
|
+
// as confirmable as a plain one.
|
|
4220
|
+
let suggested;
|
|
4221
|
+
if (suggesting) {
|
|
4222
|
+
const seam = Number(process.env.OATS_TEST_NAMING_TIMEOUT_MS), own = seam > 0 ? seam : NAMING_TIMEOUT_MS;
|
|
4223
|
+
const left = preflightStarted + preflightBudgetMs - Date.now(), souls = deploymentSoulNames(root, o.prepared), homes = deploymentInstanceHomes(root);
|
|
4224
|
+
let windows;
|
|
4225
|
+
const suggestion = yield () => suggestInstanceName({
|
|
4226
|
+
soulName: agent.name, harness, bin, instanceModel: model || null, task, timeoutMs: Math.min(own, left),
|
|
4227
|
+
env: () => launchEffectiveEnv({ base: process.env, configEnv: launchConfig?.env || {}, launch: expectedEnv, harness }),
|
|
4228
|
+
taken: (n) => homes.has(n) || souls.has(n) || (windows ??= oatsTmuxWindows(session)).includes(n),
|
|
4229
|
+
});
|
|
4230
|
+
naming = suggestion.naming;
|
|
4231
|
+
suggested = suggestion.name;
|
|
4232
|
+
}
|
|
4233
|
+
if (o.preview === true) { preflight = { status: previewPreflightBudget?.exhausted ? "timeout" : "complete", budgetMs: preflightBudgetMs, elapsedMs: Date.now() - preflightStarted }; previewPreflightBudget = null; }
|
|
4234
|
+
// A suggested name is placed as `--name` places it (its shadow, its home); otherwise the numbered name
|
|
4235
|
+
// keeps its own refusal.
|
|
4236
|
+
if (suggested) {
|
|
4237
|
+
instance = suggested;
|
|
4238
|
+
const shadow = reverseShadow(instance);
|
|
4239
|
+
if (shadow) throw shadow;
|
|
4240
|
+
({ home, homeReal, expectedHome } = place(instance));
|
|
4241
|
+
} else if (provisional) throw provisional;
|
|
4179
4242
|
|
|
4180
4243
|
if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
|
|
4181
4244
|
// K6: everything a spawn decides is decided by here — and nothing has been
|
|
@@ -4226,10 +4289,15 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4226
4289
|
if (o.preview === true) {
|
|
4227
4290
|
const decision = buildDecision();
|
|
4228
4291
|
// Workspace model (M3): the preview reports what APPLY will produce — every
|
|
4229
|
-
// module as a capability (name + origin) and every module skill
|
|
4230
|
-
//
|
|
4292
|
+
// module as a capability (name + origin) and every module skill with a
|
|
4293
|
+
// `module:<cap>` source — not the classic chain's view. The skill names are the
|
|
4294
|
+
// ones materialize copies, by its own precedence (lib/materialize.mjs
|
|
4295
|
+
// plannedModuleSkills: the resolution's rows, else the manifest's, else skills/*
|
|
4296
|
+
// read over the remote), so a root of skills (`skills: ["skills"]`) lists each skill
|
|
4297
|
+
// under it and a manifest with no `skills` its skills/ children, as
|
|
4298
|
+
// `inspect --soul --composed-skills` does.
|
|
4231
4299
|
const preparedCapabilities = o.prepared.resolution.modules.map((m) => ({ name: m.name, origin: m.from.kind === "package" ? `package:${m.from.package}@${m.from.version}` : `member:${m.from.repoKey}@${m.from.commit}` }));
|
|
4232
|
-
const preparedSkills =
|
|
4300
|
+
const preparedSkills = (yield () => (o.plannedSkills ?? plannedSkillsDefault)(o.prepared)).map((s) => ({ name: s.name, source: `module:${s.module}` }));
|
|
4233
4301
|
// R5 (0.25.2, decision 14): the preview shows the provider payloads the apply
|
|
4234
4302
|
// will record — `providers` is the --provider map exactly as parsed (what the
|
|
4235
4303
|
// operator typed; prepareInstance keeps it on prepared.spawn.providers) and
|
|
@@ -4260,6 +4328,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4260
4328
|
relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
|
|
4261
4329
|
policy: { childSpawns: ownChildPolicy }, executable: bin, capabilities: preparedCapabilities,
|
|
4262
4330
|
skills: [...expectedResources.filter((r) => r.type === "skill-tree" && !r.deferred).flatMap((r) => r.entries || []), ...preparedSkills], task: task || null,
|
|
4331
|
+
...(naming ? { naming } : {}),
|
|
4263
4332
|
});
|
|
4264
4333
|
}
|
|
4265
4334
|
if (o.expectDecision !== undefined) {
|
|
@@ -5343,7 +5412,9 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
|
|
|
5343
5412
|
// `retire` is only ever the value read above: a record that carries one (hand-edited, or
|
|
5344
5413
|
// copied from a row) never stands in for it.
|
|
5345
5414
|
const { retire: _recordedRetire, ...recorded } = meta;
|
|
5346
|
-
|
|
5415
|
+
// Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
|
|
5416
|
+
// null, after the record so that nothing in instance.json stands in for it.
|
|
5417
|
+
return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
|
|
5347
5418
|
|
|
5348
5419
|
});
|
|
5349
5420
|
};
|
|
@@ -5892,7 +5963,8 @@ function retireGitProbe(repo, args, { encoding } = {}) {
|
|
|
5892
5963
|
* MUST be added in the same change to the names a capability may not declare
|
|
5893
5964
|
* as its own (`retirement.disposable.home`: KERNEL_HOME_NAMES and
|
|
5894
5965
|
* KERNEL_HOME_NAME_PREFIXES in lib/capability-contract.mjs, and the schema). */
|
|
5895
|
-
|
|
5966
|
+
// `.oats-color.json` (feature instance-color) is presentation anyone may change at any time: never work.
|
|
5967
|
+
const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json"]);
|
|
5896
5968
|
const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/];
|
|
5897
5969
|
/** Harness project settings in the home are configuration, not work: the
|
|
5898
5970
|
* home's `.claude/` is harness layout the kernel already shapes (the skills
|
|
@@ -9838,7 +9910,7 @@ const claimCommand = (action) => action === "stop" ? "oats instance stop" : `oat
|
|
|
9838
9910
|
/** What each verb that meets a held claim says it did not do: the words its refusals end with,
|
|
9839
9911
|
* before any effect. After a takeover ended a dead holder's step, every verb says the same
|
|
9840
9912
|
* (lib/errors.mjs nothingAfter). */
|
|
9841
|
-
const CLAIM_NOTHING = { retire: "nothing was done", stop: "nothing was stopped", "worktree add": "no tree was made" };
|
|
9913
|
+
const CLAIM_NOTHING = { retire: "nothing was done", stop: "nothing was stopped", "worktree add": "no tree was made", "instance color": "the colour was not changed" };
|
|
9842
9914
|
|
|
9843
9915
|
/** The refusals of `arriving` ("retire", "stop", or "worktree add", which reads the claim and does
|
|
9844
9916
|
* not take it) of `name` (home `home`) that meets the lifecycle claim `lock`, as lib/claim.mjs asks
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/** An instance's colour (feature instance-color, awebai/oats#1421 §2): presentation, never identity
|
|
2
|
+
* or an address. Anyone may set it at any time; it is a home file of its own, `<home>/.oats-color.json`,
|
|
3
|
+
* so that a start or restart, which rewrites instance.json, can never lose it.
|
|
4
|
+
*
|
|
5
|
+
* The record is `{ colorApi: 1, color, at }`, written atomically (writeThroughPrivateFile) at mode
|
|
6
|
+
* 0600; clearing removes the file. A reader takes a regular file only, without following a link, up
|
|
7
|
+
* to RECORD_MAX bytes: anything that is not a valid record reads as no colour (null), never an
|
|
8
|
+
* error. Dependency-free: the status rows, inspect and the command all read it through here. */
|
|
9
|
+
import { lstatSync, rmSync } from "node:fs";
|
|
10
|
+
import { join } from "node:path";
|
|
11
|
+
import { readFileHead } from "./bounded-read.mjs";
|
|
12
|
+
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
13
|
+
|
|
14
|
+
/** The closed palette, the clients' own (packages/client/soul-colors.mjs SOUL_COLORS): the kernel
|
|
15
|
+
* imports nothing from packages/, so it keeps this copy, which test/instance-color.test.mjs pins equal. */
|
|
16
|
+
export const INSTANCE_COLORS = Object.freeze(["sand", "sage", "slate", "mauve", "clay", "olive"]);
|
|
17
|
+
/** The record's own version, and the command answer's. */
|
|
18
|
+
export const COLOR_API = 1;
|
|
19
|
+
export const INSTANCE_COLOR_API = 1;
|
|
20
|
+
/** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
|
|
21
|
+
* fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
|
|
22
|
+
export const COLOR_FILE = ".oats-color.json";
|
|
23
|
+
/** A record larger than this is not one. */
|
|
24
|
+
export const RECORD_MAX = 4096;
|
|
25
|
+
|
|
26
|
+
/** A palette name exactly, else null: what a reader keeps of any value (a relayed row's included). */
|
|
27
|
+
export const paletteColor = (value) => (typeof value === "string" && INSTANCE_COLORS.includes(value) ? value : null);
|
|
28
|
+
|
|
29
|
+
/** The colour `home` records, or null: no file, not a regular file (a link is never followed), over
|
|
30
|
+
* RECORD_MAX bytes, unreadable, not JSON, another colorApi or a name outside the palette. Never throws. */
|
|
31
|
+
export function readInstanceColor(home) {
|
|
32
|
+
try {
|
|
33
|
+
const { bytes, size } = readFileHead(join(home, COLOR_FILE), RECORD_MAX + 1);
|
|
34
|
+
if (size > RECORD_MAX) return null;
|
|
35
|
+
const record = JSON.parse(bytes.toString("utf8"));
|
|
36
|
+
if (!record || typeof record !== "object" || Array.isArray(record) || record.colorApi !== COLOR_API) return null;
|
|
37
|
+
return paletteColor(record.color);
|
|
38
|
+
} catch { return null; }
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Record `color` (a palette name) for `home`, or remove the record when `color` is null.
|
|
42
|
+
* → `{ color, changed }`. The colour the home already shows is no change: nothing is written. A clear
|
|
43
|
+
* removes whatever file stands at the name (an unreadable one included) and is a change only when a
|
|
44
|
+
* colour was shown. The caller validated `color` and holds the right to change the home. */
|
|
45
|
+
export function writeInstanceColor(home, color, { now = () => new Date() } = {}) {
|
|
46
|
+
const path = join(home, COLOR_FILE);
|
|
47
|
+
const before = readInstanceColor(home);
|
|
48
|
+
if (color === null) {
|
|
49
|
+
let present = false;
|
|
50
|
+
try { lstatSync(path); present = true; } catch (e) { if (e?.code !== "ENOENT") throw e; }
|
|
51
|
+
if (present) rmSync(path, { force: true });
|
|
52
|
+
return { color: null, changed: before !== null };
|
|
53
|
+
}
|
|
54
|
+
if (before === color) return { color, changed: false };
|
|
55
|
+
const bytes = JSON.stringify({ colorApi: COLOR_API, color, at: now().toISOString() }) + "\n";
|
|
56
|
+
writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
|
|
57
|
+
return { color, changed: true };
|
|
58
|
+
}
|