@awebai/oats 0.52.0 → 0.54.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/README.md +2 -1
- package/bin/oats.mjs +314 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +696 -60
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +184 -12
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1288 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +239 -16
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +310 -0
- package/docs/workspaces.md +123 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +18 -5
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +404 -60
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +75 -27
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/skills/oats-getting-started/SKILL.md +8 -2
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
/** The pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: which
|
|
2
|
+
* folders those are, the bridge found in each, and what `oats update` does there
|
|
3
|
+
* (awebai/oats#991, #852). `oats doctor` warns from the same list.
|
|
4
|
+
*
|
|
5
|
+
* This module only reads: the environment it is given, the launch configurations it is given
|
|
6
|
+
* and each folder's bridge `package.json`. Nothing here runs `pi` or `npm`; `oats update`
|
|
7
|
+
* (bin/oats.mjs) runs the steps the plan names.
|
|
8
|
+
*
|
|
9
|
+
* A pi folder of the deployment is the default (`~/.pi/agent`), this process's own
|
|
10
|
+
* `PI_CODING_AGENT_DIR`, and the `PI_CODING_AGENT_DIR` of each launch configuration whose
|
|
11
|
+
* harness is pi: "the ambient one and each launch configuration's", as `trustTargets`
|
|
12
|
+
* (harness-trust-write.mjs) lists the claude and codex configuration files. Homes' recorded
|
|
13
|
+
* launches are not read: a home keeps a launch its configuration no longer has, and the list
|
|
14
|
+
* would then depend on every home.
|
|
15
|
+
*
|
|
16
|
+
* `oats update` moves forward only (awebai/oats#1011): the CLI to a newer version of the
|
|
17
|
+
* registry, a bridge to the version the kernel has after the run. Neither is ever moved back,
|
|
18
|
+
* and the registry's answer is checked to be one version before anything is made of it.
|
|
19
|
+
*
|
|
20
|
+
* The move is one `pi install` over the installed bridge, never an uninstall first: pi
|
|
21
|
+
* replaces the settings entry and the files of the same package, and an install that fails
|
|
22
|
+
* leaves the old ones in place (established with pi 1.0.2). The folder's version is read
|
|
23
|
+
* back after each step, so a pi that behaves otherwise is a named failure, not a silent one. */
|
|
24
|
+
import { existsSync, readFileSync, realpathSync } from "node:fs";
|
|
25
|
+
import { isAbsolute, join, resolve } from "node:path";
|
|
26
|
+
import { homedir } from "node:os";
|
|
27
|
+
import { compareVersions, parseVersion } from "./resolve.mjs";
|
|
28
|
+
import { safeText } from "./refused-text.mjs";
|
|
29
|
+
|
|
30
|
+
export const PI_BRIDGE = "@awebai/oats-pi";
|
|
31
|
+
const KERNEL_PACKAGE = "@awebai/oats";
|
|
32
|
+
/** The variable that moves pi's folder. */
|
|
33
|
+
export const PI_FOLDER_VAR = "PI_CODING_AGENT_DIR";
|
|
34
|
+
|
|
35
|
+
const real = (p) => { try { return realpathSync.native(p); } catch { return resolve(p); } };
|
|
36
|
+
const userHome = (env) => env.HOME || homedir();
|
|
37
|
+
/** A leading `~` is the user's home, as the kernel reads it for pi's resource folder (core.mjs). */
|
|
38
|
+
const expandHome = (p, env) => p.replace(/^~(?=$|\/)/, () => userHome(env));
|
|
39
|
+
/** One shell word: as is when it needs no quoting, else single-quoted. */
|
|
40
|
+
const shellWord = (value) => /^[A-Za-z0-9_\/.,:@%+=-]+$/.test(value) ? value : "'" + value.replaceAll("'", "'\"'\"'") + "'";
|
|
41
|
+
const bridgeSpec = (target) => `npm:${PI_BRIDGE}@${target}`;
|
|
42
|
+
const configsNamed = (names) => `launch configuration${names.length > 1 ? "s" : ""} ${names.join(", ")}`;
|
|
43
|
+
|
|
44
|
+
/** One published version as `npm view <package> version` prints it: three numbers and an
|
|
45
|
+
* optional prerelease, at most 256 characters (npm's own limit). No `v`, no partial version,
|
|
46
|
+
* no build metadata, no blank: a subset of what `parseVersion` (resolve.mjs) reads. */
|
|
47
|
+
const PUBLISHED_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
|
|
48
|
+
|
|
49
|
+
/** What a registry lookup printed, checked to be one version and nothing else before it reaches
|
|
50
|
+
* a step, an argument or the screen (awebai/oats#1011): the line, its one line ending aside.
|
|
51
|
+
* `lookup` is the command that was asked, for the message.
|
|
52
|
+
* → { version } | { problem }, the answer in `problem` made safe to print: bounded, its control
|
|
53
|
+
* characters shown as escapes or replaced (refused-text.mjs). */
|
|
54
|
+
export function registryVersion(stdout, lookup) {
|
|
55
|
+
const text = String(stdout ?? "").replace(/\r?\n$/, "");
|
|
56
|
+
if (text.length <= 256 && PUBLISHED_VERSION.test(text)) return { version: text };
|
|
57
|
+
return { problem: `\`${lookup}\` answered ${text ? safeText(JSON.stringify(text), 80) : "nothing"}, which is not a version` };
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Version `a` against `b` by the kernel's own ordering (`compareVersions`, resolve.mjs, the
|
|
61
|
+
* one the compatibility check uses): negative, zero or positive. A prerelease is below its
|
|
62
|
+
* release, and build metadata orders nothing (`0.53.0+build.1` equals `0.53.0`). null when
|
|
63
|
+
* either is not a version: what cannot be compared is neither ahead nor the same. */
|
|
64
|
+
function versionOrder(a, b) {
|
|
65
|
+
const pa = parseVersion(a), pb = parseVersion(b);
|
|
66
|
+
return pa && pb ? compareVersions(pa, pb) : null;
|
|
67
|
+
}
|
|
68
|
+
const isAhead = (a, b) => versionOrder(a, b) > 0;
|
|
69
|
+
/** The same version: the same text, or two spellings that compare equal. */
|
|
70
|
+
const sameVersion = (a, b) => a === b || versionOrder(a, b) === 0;
|
|
71
|
+
|
|
72
|
+
/** The kernel's own lookup, as arguments: the version the registry lists for the CLI. */
|
|
73
|
+
export const kernelLookup = () => ["npm", "view", KERNEL_PACKAGE, "version"];
|
|
74
|
+
|
|
75
|
+
/** What that lookup says, from what spawnSync returned for it (`ran`, both streams captured):
|
|
76
|
+
* → { version }, checked (registryVersion), or { problem }, the message that stops the update.
|
|
77
|
+
* Nothing npm printed reaches the screen as it came, on either stream: a failed lookup's error
|
|
78
|
+
* output is in the message bounded and made safe to print, and a lookup that ended well has its
|
|
79
|
+
* error output dropped. */
|
|
80
|
+
export function kernelLookupResult(ran) {
|
|
81
|
+
if (ran.error || ran.status !== 0) {
|
|
82
|
+
const said = String(ran.stderr ?? "").trim();
|
|
83
|
+
return { problem: `cannot check npm for the latest version: ${ran.error ? ran.error.message : `exit ${ran.status ?? ran.signal}`}${said ? `: ${safeText(JSON.stringify(said), 300)}` : ""}` };
|
|
84
|
+
}
|
|
85
|
+
const checked = registryVersion(ran.stdout, kernelLookup().join(" "));
|
|
86
|
+
return checked.problem ? { problem: `${checked.problem}. Nothing was changed. Run \`oats update\` again.` } : checked;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** The CLI's own part of `oats update`, forward only: the install `step` only when the registry's
|
|
90
|
+
* version is newer than the installed one, and the `target` of the bridges, which is the
|
|
91
|
+
* version the kernel has after the run. An installed version ahead of the registry (a checkout,
|
|
92
|
+
* a build not yet published) is left alone, with the `note` that says so; one that is the same
|
|
93
|
+
* version (a local build's metadata aside) is left alone too. An installed version that cannot
|
|
94
|
+
* be compared is another version, and the step is proposed. `registry` is a checked version
|
|
95
|
+
* (registryVersion).
|
|
96
|
+
* → { installed, registry, target, ahead, step?: { argv, display }, note? } */
|
|
97
|
+
export function planCliUpdate(installed, registry) {
|
|
98
|
+
if (isAhead(installed, registry)) return { installed, registry, target: installed, ahead: true, note: `The installed ${installed} is ahead of the registry's ${registry}: nothing to do for the CLI.` };
|
|
99
|
+
if (sameVersion(installed, registry)) return { installed, registry, target: installed, ahead: false };
|
|
100
|
+
const argv = ["npm", "install", "-g", `${KERNEL_PACKAGE}@${registry}`];
|
|
101
|
+
return { installed, registry, target: registry, ahead: false, step: { argv, display: argv.join(" ") } };
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** The lookup `oats update` makes before any step, as arguments: the bridge's exact version on
|
|
105
|
+
* the registry, with npm told to revalidate its cache (awebai/oats#852). */
|
|
106
|
+
export const bridgeLookup = (target) => ["npm", "view", `${PI_BRIDGE}@${target}`, "version", "--prefer-online"];
|
|
107
|
+
|
|
108
|
+
/** What that lookup says, from what spawnSync returned for it (`ran`): null when the version was
|
|
109
|
+
* seen (exit 0 and the checked answer is the target's version: npm answers a local build's
|
|
110
|
+
* `0.53.0+build.1` with the `0.53.0` it lists), else the message that stops the update.
|
|
111
|
+
* An answer that is not a version is said to be that, with the lookup named; any other is "not
|
|
112
|
+
* seen", an older npm's exit 0 with no output included. When the installed kernel is ahead of
|
|
113
|
+
* the registry (`cli`, from planCliUpdate), the message says so: its bridge is not one that
|
|
114
|
+
* appears in a few minutes. */
|
|
115
|
+
export function bridgeLookupProblem(ran, cli) {
|
|
116
|
+
const { target } = cli;
|
|
117
|
+
const answered = !ran.error && ran.status === 0 && String(ran.stdout ?? "").trim() ? registryVersion(ran.stdout, bridgeLookup(target).join(" ")) : null;
|
|
118
|
+
if (answered?.problem) return `${answered.problem}. Nothing was changed, and every bridge is in place. Run \`oats update\` again.`;
|
|
119
|
+
if (answered?.version && sameVersion(answered.version, target)) return null;
|
|
120
|
+
const why = ran.error ? ran.error.message : ran.status !== 0 ? `exit ${ran.status}` : answered ? `it answered ${answered.version}` : "no answer";
|
|
121
|
+
const notSeen = `${PI_BRIDGE}@${target} was not seen on the registry (npm view: ${why})`;
|
|
122
|
+
if (cli.ahead) return `${notSeen}: the installed kernel ${cli.installed} is ahead of the registry's ${cli.registry}, so its bridge may not be published. Nothing was changed, and every bridge is in place. Run \`oats update\` again once npm lists ${cli.installed}.`;
|
|
123
|
+
return `${notSeen}: a version is listed a few minutes after it is published. Nothing was changed, and every bridge is in place. Run \`oats update\` again in a few minutes.`;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** The pi folder a launch configuration's `env` names: `{dir}` from a literal or a {fromEnv}
|
|
127
|
+
* resolved from the host `base`; `{problem}` when the reference is not set on this host or the
|
|
128
|
+
* path is not absolute; null when the configuration leaves it to the host. The rule and the
|
|
129
|
+
* wording of `launchConfigDir` (harness-trust.mjs), which is keyed by the harnesses that have
|
|
130
|
+
* folder trust and so cannot name pi. */
|
|
131
|
+
export function launchConfigPiFolder(configEnv = {}, base = process.env) {
|
|
132
|
+
if (!Object.hasOwn(configEnv || {}, PI_FOLDER_VAR)) return null;
|
|
133
|
+
const v = configEnv[PI_FOLDER_VAR];
|
|
134
|
+
const named = typeof v === "string" ? v : base[v?.fromEnv];
|
|
135
|
+
if (named === undefined) return { problem: `${PI_FOLDER_VAR} references ${v?.fromEnv}, not set on this host`, fromEnv: v?.fromEnv };
|
|
136
|
+
const dir = expandHome(named, base);
|
|
137
|
+
return isAbsolute(dir) ? { dir } : { problem: `${PI_FOLDER_VAR} ${JSON.stringify(named)} is not an absolute path` };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** The pi folders of a deployment, in a fixed order: the default, this process's own, then each
|
|
141
|
+
* pi launch configuration's in name order. Folders are deduplicated by real path; one keeps
|
|
142
|
+
* every reason it is listed for, and the path it was first named by. A folder that cannot be
|
|
143
|
+
* resolved is listed with its `problem` and no `dir`, never dropped.
|
|
144
|
+
* → [{ dir, real, reasons: [{ kind: "default" | "shell" | "launch-config", name?, executable? }], problem? }] */
|
|
145
|
+
export function piFolders({ env = process.env, launchConfigs = {} } = {}) {
|
|
146
|
+
const folders = [], byReal = new Map();
|
|
147
|
+
const add = (dir, reason) => {
|
|
148
|
+
const key = real(dir);
|
|
149
|
+
if (byReal.has(key)) { byReal.get(key).reasons.push(reason); return; }
|
|
150
|
+
const folder = { dir, real: key, reasons: [reason] };
|
|
151
|
+
byReal.set(key, folder);
|
|
152
|
+
folders.push(folder);
|
|
153
|
+
};
|
|
154
|
+
const unresolved = (reason, found) => folders.push({ dir: null, real: null, reasons: [reason], problem: found.problem, ...(found.fromEnv ? { fromEnv: found.fromEnv } : {}) });
|
|
155
|
+
add(join(userHome(env), ".pi", "agent"), { kind: "default" });
|
|
156
|
+
// An empty value is not set, as core.mjs reads it (piAgentDir).
|
|
157
|
+
if (env[PI_FOLDER_VAR]) {
|
|
158
|
+
const found = launchConfigPiFolder({ [PI_FOLDER_VAR]: env[PI_FOLDER_VAR] }, env);
|
|
159
|
+
if (found.problem) unresolved({ kind: "shell" }, found); else add(found.dir, { kind: "shell" });
|
|
160
|
+
}
|
|
161
|
+
for (const config of Object.values(launchConfigs).filter((c) => c.harness === "pi").sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
|
|
162
|
+
const found = launchConfigPiFolder(config.env, env);
|
|
163
|
+
if (!found) continue;
|
|
164
|
+
// A relative executable is a path against the deployment directory, as a launch resolves it.
|
|
165
|
+
const executable = config.executable?.includes("/") && !isAbsolute(config.executable) && config.source ? resolve(config.source, config.executable) : config.executable;
|
|
166
|
+
const reason = { kind: "launch-config", name: config.name, ...(executable !== undefined ? { executable } : {}) };
|
|
167
|
+
if (found.problem) unresolved(reason, found); else add(found.dir, reason);
|
|
168
|
+
}
|
|
169
|
+
return folders;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** Why a folder is looked at: "the default", "this shell's PI_CODING_AGENT_DIR", "launch configurations a, b". */
|
|
173
|
+
export function whyLookedAt(folder) {
|
|
174
|
+
const configs = folder.reasons.filter((r) => r.kind === "launch-config").map((r) => r.name);
|
|
175
|
+
return [
|
|
176
|
+
...(folder.reasons.some((r) => r.kind === "default") ? ["the default"] : []),
|
|
177
|
+
...(folder.reasons.some((r) => r.kind === "shell") ? [`this shell's ${PI_FOLDER_VAR}`] : []),
|
|
178
|
+
...(configs.length ? [configsNamed(configs)] : []),
|
|
179
|
+
].join(", ");
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/** The bridge in a pi folder, read where pi installs it:
|
|
183
|
+
* → { status: "no-folder" | "no-bridge" | "installed" | "unreadable", file, version?, problem? } */
|
|
184
|
+
export function piBridgeState(dir) {
|
|
185
|
+
const file = join(dir, "npm", "node_modules", ...PI_BRIDGE.split("/"), "package.json");
|
|
186
|
+
if (!existsSync(dir)) return { status: "no-folder", file };
|
|
187
|
+
if (!existsSync(file)) return { status: "no-bridge", file };
|
|
188
|
+
let version;
|
|
189
|
+
try { version = JSON.parse(readFileSync(file, "utf8")).version; } catch { return { status: "unreadable", file, problem: `${file} cannot be read as JSON` }; }
|
|
190
|
+
if (typeof version !== "string" || !version) return { status: "unreadable", file, problem: `${file} names no version` };
|
|
191
|
+
return { status: "installed", file, version };
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/** `piFolders`, each resolved one with the `bridge` found in it. */
|
|
195
|
+
export function piBridgeFolders(options) {
|
|
196
|
+
return piFolders(options).map((folder) => folder.dir ? { ...folder, bridge: piBridgeState(folder.dir) } : folder);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** `oats doctor`'s warnings: one per folder whose bridge is not the kernel's version (two
|
|
200
|
+
* spellings that compare equal are one version, as in the plan below), and one per folder that
|
|
201
|
+
* could not be looked at. A folder that does not exist or holds no bridge is not a skew.
|
|
202
|
+
* A bridge ahead of the kernel is a skew too, with its own ending: `oats update` moves no bridge
|
|
203
|
+
* back, and doctor reads no registry, so it says what ends the skew instead of "run `oats update`". */
|
|
204
|
+
export function piBridgeSkewWarnings(folders, kernelVersion) {
|
|
205
|
+
const warnings = [];
|
|
206
|
+
for (const folder of folders) {
|
|
207
|
+
const why = whyLookedAt(folder);
|
|
208
|
+
if (folder.problem) warnings.push(`pi bridge not checked — ${why}: ${folder.problem}, so its pi folder could not be looked at; \`oats update\` says what to run there`);
|
|
209
|
+
else if (folder.bridge.status === "unreadable") warnings.push(`pi bridge not checked in ${folder.dir} (${why}) — ${folder.bridge.problem}; \`oats update\` says what to run there`);
|
|
210
|
+
else if (folder.bridge.status === "installed" && !sameVersion(folder.bridge.version, kernelVersion)) {
|
|
211
|
+
const ending = isAhead(folder.bridge.version, kernelVersion)
|
|
212
|
+
? `the bridge is ahead of the kernel, and \`oats update\` never moves a bridge back. The skew ends when the kernel is at ${folder.bridge.version} (\`oats update\` moves it once npm lists that version), or when the kernel's bridge is installed there by hand (docs/upgrading.md, "By hand")`
|
|
213
|
+
: "run `oats update` (they publish in lockstep)";
|
|
214
|
+
warnings.push(`version skew — kernel ${kernelVersion}, pi bridge ${folder.bridge.version} in ${folder.dir} (${why}); ${ending}`);
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
return warnings;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** What `oats update` does in each folder to bring its bridge to `target`, the version the
|
|
221
|
+
* kernel has after the run (planCliUpdate):
|
|
222
|
+
* - `move`: the bridge is at another version, and not ahead of `target`; `step` is the one
|
|
223
|
+
* command, as arguments. A version that cannot be compared is another version.
|
|
224
|
+
* - `leave`: already at `target` (the same version, a build's metadata aside), or `ahead` of
|
|
225
|
+
* it: a bridge is never moved back.
|
|
226
|
+
* - `none`: no folder, or no bridge in it. `oats update` installs no first bridge.
|
|
227
|
+
* - `skip`: not touched, with the `detail` and, where there are any, the `commands` to run
|
|
228
|
+
* there: a folder that does not resolve, a bridge that cannot be read, or a folder named only
|
|
229
|
+
* by launch configurations that run their own executable (update never runs a wrapper).
|
|
230
|
+
* One command per distinct executable, each with the configurations it is for (`where`) when
|
|
231
|
+
* there are several.
|
|
232
|
+
* The step runs the plain `pi` on PATH with PI_CODING_AGENT_DIR set to the folder, except for
|
|
233
|
+
* the default folder when `env` sets none, and with pi's npm told to revalidate its cache.
|
|
234
|
+
* `detail` is the plan's line for the folder: what was found there, then what happens.
|
|
235
|
+
* → the folders, each with { action, detail, ahead?, commands?: [{ command, where? }], step?: { argv, env, display } } */
|
|
236
|
+
export function planPiBridges(folders, target, { env = process.env } = {}) {
|
|
237
|
+
return folders.map((folder) => {
|
|
238
|
+
const wrapped = folder.reasons.every((r) => r.kind === "launch-config" && r.executable !== undefined);
|
|
239
|
+
// The programs a by-hand command names: the plain `pi`, or each distinct executable of the
|
|
240
|
+
// configurations, in their order, with the names of those that run it.
|
|
241
|
+
const programs = new Map();
|
|
242
|
+
for (const r of wrapped ? folder.reasons : []) programs.set(r.executable, [...(programs.get(r.executable) ?? []), r.name]);
|
|
243
|
+
if (!wrapped) programs.set("pi", []);
|
|
244
|
+
const byHand = (folderWord, where) => [...programs].map(([program, names]) => {
|
|
245
|
+
const said = where ?? (programs.size > 1 ? `for ${configsNamed(names)}` : null);
|
|
246
|
+
return { command: `${PI_FOLDER_VAR}=${folderWord} ${shellWord(program)} install ${bridgeSpec(target)}`, ...(said ? { where: said } : {}) };
|
|
247
|
+
});
|
|
248
|
+
if (folder.problem) {
|
|
249
|
+
return { ...folder, action: "skip", detail: `not touched: ${folder.problem}`, ...(folder.fromEnv ? { commands: byHand(`"$${folder.fromEnv}"`, `where ${folder.fromEnv} is set`) } : {}) };
|
|
250
|
+
}
|
|
251
|
+
const { bridge } = folder;
|
|
252
|
+
if (bridge.status === "no-folder") return { ...folder, action: "none", detail: "no bridge (the folder does not exist): not touched" };
|
|
253
|
+
if (bridge.status === "no-bridge") return { ...folder, action: "none", detail: "no bridge: not touched" };
|
|
254
|
+
if (bridge.status === "unreadable") return { ...folder, action: "skip", detail: `bridge not read: not touched: ${bridge.problem}`, commands: byHand(shellWord(folder.dir)) };
|
|
255
|
+
if (sameVersion(bridge.version, target)) return { ...folder, action: "leave", detail: `bridge ${bridge.version}: left alone, already at ${target}` };
|
|
256
|
+
if (isAhead(bridge.version, target)) return { ...folder, action: "leave", ahead: true, detail: `bridge ${bridge.version}: left alone, ahead of ${target}` };
|
|
257
|
+
if (wrapped) {
|
|
258
|
+
const names = folder.reasons.map((r) => r.name);
|
|
259
|
+
return { ...folder, action: "skip", detail: `bridge ${bridge.version}: not touched: ${configsNamed(names)} run${names.length > 1 ? " their" : "s its"} own executable, and \`oats update\` runs no wrapper`, commands: byHand(shellWord(folder.dir)) };
|
|
260
|
+
}
|
|
261
|
+
const setsFolder = !(folder.reasons.some((r) => r.kind === "default") && !env[PI_FOLDER_VAR]);
|
|
262
|
+
const stepEnv = { ...(setsFolder ? { [PI_FOLDER_VAR]: folder.dir } : {}), npm_config_prefer_online: "true" };
|
|
263
|
+
const argv = ["pi", "install", bridgeSpec(target)];
|
|
264
|
+
const display = [...Object.entries(stepEnv).map(([name, value]) => `${name}=${shellWord(value)}`), ...argv.map(shellWord)].join(" ");
|
|
265
|
+
return { ...folder, action: "move", detail: `bridge ${bridge.version}: move to ${target}`, step: { argv, env: stepEnv, display } };
|
|
266
|
+
});
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/** The plan's lines, two or more per folder: the folder and why it is looked at, what happens
|
|
270
|
+
* there, and each command to run where update does not. Then one line when the installed kernel
|
|
271
|
+
* is ahead of the registry (`cli`, from planCliUpdate) and a bridge is to move to its version:
|
|
272
|
+
* the plan makes no lookup, so it does not know that this version is published, and the run
|
|
273
|
+
* stops before any step when it is not (bridgeLookupProblem). */
|
|
274
|
+
export function piBridgePlanLines(plan, cli = {}) {
|
|
275
|
+
const lines = [];
|
|
276
|
+
for (const entry of plan) {
|
|
277
|
+
lines.push(` ${entry.dir ?? "(not resolved)"} (${whyLookedAt(entry)})`);
|
|
278
|
+
lines.push(` ${entry.detail}`);
|
|
279
|
+
for (const { command, where } of entry.commands ?? []) lines.push(` run there${where ? `, ${where}` : ""}: ${command}`);
|
|
280
|
+
}
|
|
281
|
+
if (cli.ahead && plan.some((entry) => entry.step)) lines.push(` A bridge moves to ${cli.target} only if ${PI_BRIDGE}@${cli.target} is published: the installed kernel is ahead of the registry's ${cli.registry}, and a run checks that before any step.`);
|
|
282
|
+
return lines;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/** Why a bridge step did not do its work, or null when the folder is now at `target` (as the plan
|
|
286
|
+
* reads "the same version"): the run's own failure (`problem`), or a run that ended well with
|
|
287
|
+
* another version in the folder. */
|
|
288
|
+
export function piBridgeStepProblem(entry, target, problem) {
|
|
289
|
+
if (problem) return problem;
|
|
290
|
+
const now = piBridgeState(entry.dir);
|
|
291
|
+
return now.status === "installed" && sameVersion(now.version, target) ? null : `pi ended without an error, but the bridge there is not ${target}`;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/** The message of a step that failed: the folder and the exact step to run again, what the
|
|
295
|
+
* folder holds now (read from it, not assumed), and the folders not reached. `entry` is the
|
|
296
|
+
* folder of the failed step, absent when the step was not a folder's (the CLI's own). */
|
|
297
|
+
export function piBridgeFailure({ entry, display, problem, notReached = [] }) {
|
|
298
|
+
const lines = [];
|
|
299
|
+
if (entry) {
|
|
300
|
+
const now = piBridgeState(entry.dir), before = entry.bridge.version;
|
|
301
|
+
const holds = now.status === "installed" ? (now.version === before ? `the bridge there is still ${before}` : `the bridge there is now ${now.version}`)
|
|
302
|
+
: now.status === "unreadable" ? `the bridge there cannot be read (${now.problem})`
|
|
303
|
+
: "the bridge is now ABSENT there: a pi session started with this folder has no OATS extension until the step succeeds";
|
|
304
|
+
lines.push(`step failed in ${entry.dir} (${whyLookedAt(entry)}): ${problem}`, ` ${holds}`, ` run it again: ${display}`);
|
|
305
|
+
} else lines.push(`step failed: ${display}: ${problem}`, " no pi folder was touched");
|
|
306
|
+
if (notReached.length) lines.push(` not reached (run \`oats update\` again for ${notReached.length > 1 ? "them" : "it"}):`, ...notReached.map((e) => ` ${e.dir} (${whyLookedAt(e)})`));
|
|
307
|
+
return lines.join("\n");
|
|
308
|
+
}
|
package/lib/refused-text.mjs
CHANGED
|
@@ -15,3 +15,14 @@ export function safeText(text, max) {
|
|
|
15
15
|
const points = [...String(text).replace(REFUSED_TEXT_ALL, "\uFFFD")];
|
|
16
16
|
return points.length > max ? `${points.slice(0, max - 1).join("")}…` : points.join("");
|
|
17
17
|
}
|
|
18
|
+
|
|
19
|
+
/** A line of text on its way to a terminal: every REFUSED_TEXT character spelled `\u{<hex>}`, the
|
|
20
|
+
* rest as it is. For text a command prints that the kernel did not write (a path as the system
|
|
21
|
+
* resolved it, a hook's own words): the name stays readable, and it cannot clear the screen, hide
|
|
22
|
+
* or reorder what is beside it, or write a line of its own. The one function for that: a printer
|
|
23
|
+
* of any command calls this one. `safeText` is for text that is stored or put in an answer, where
|
|
24
|
+
* such a character is replaced and the text is cut. JSON is never passed through this: an
|
|
25
|
+
* answer's strings are what they are. */
|
|
26
|
+
export function terminalText(line) {
|
|
27
|
+
return String(line).replace(REFUSED_TEXT_ALL, (c) => `\\u{${c.codePointAt(0).toString(16)}}`);
|
|
28
|
+
}
|