@awebai/oats 0.61.0 → 0.62.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 +1 -1
- package/bin/oats.mjs +26 -11
- package/docs/capabilities.md +1 -1
- package/docs/execution-targets.md +49 -3
- package/docs/implementation.md +2 -1
- package/docs/named-test-runs.md +382 -0
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.62.0.md +223 -0
- package/docs/upgrading.md +133 -11
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +2 -2
- package/lib/doctor-capture.mjs +35 -0
- package/lib/session-viewer.mjs +86 -7
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/record/README.md +87 -13
- package/packages/record/bin/capture-hook.mjs +8 -0
- package/packages/record/bin/capture.mjs +143 -124
- package/packages/record/bin/recall.mjs +8 -3
- package/packages/record/bin/setup.mjs +115 -225
- package/packages/record/bin/turn-record.mjs +2 -2
- package/packages/record/docs/capture-service.md +1443 -28
- package/packages/record/docs/capture-status.schema.json +429 -12
- package/packages/record/lib/capture-admission.mjs +82 -0
- package/packages/record/lib/capture-aw-unit.mjs +137 -0
- package/packages/record/lib/capture-aw.mjs +31 -12
- package/packages/record/lib/capture-budget.mjs +31 -0
- package/packages/record/lib/capture-cc.mjs +39 -6
- package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
- package/packages/record/lib/capture-cleanup-work.mjs +77 -0
- package/packages/record/lib/capture-command-operation.mjs +37 -0
- package/packages/record/lib/capture-command-output.mjs +61 -0
- package/packages/record/lib/capture-command-worker.mjs +6 -0
- package/packages/record/lib/capture-command.mjs +48 -0
- package/packages/record/lib/capture-completion.mjs +152 -0
- package/packages/record/lib/capture-context.mjs +50 -0
- package/packages/record/lib/capture-default-roots.mjs +30 -0
- package/packages/record/lib/capture-discovery.mjs +114 -0
- package/packages/record/lib/capture-failures.mjs +45 -0
- package/packages/record/lib/capture-health-doctor.mjs +13 -0
- package/packages/record/lib/capture-health-installation.mjs +117 -0
- package/packages/record/lib/capture-health.mjs +116 -0
- package/packages/record/lib/capture-hook-ownership.mjs +58 -0
- package/packages/record/lib/capture-hook-runner.mjs +17 -0
- package/packages/record/lib/capture-hook.mjs +26 -0
- package/packages/record/lib/capture-index-inventory.mjs +205 -0
- package/packages/record/lib/capture-index-outcomes.mjs +113 -0
- package/packages/record/lib/capture-index-reset.mjs +109 -0
- package/packages/record/lib/capture-index-work.mjs +77 -0
- package/packages/record/lib/capture-issue-preparation.mjs +73 -0
- package/packages/record/lib/capture-issues.mjs +15 -2
- package/packages/record/lib/capture-lock.mjs +102 -16
- package/packages/record/lib/capture-native-unit.mjs +322 -0
- package/packages/record/lib/capture-pass.mjs +102 -0
- package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
- package/packages/record/lib/capture-retained-scratch.mjs +213 -0
- package/packages/record/lib/capture-retry.mjs +102 -0
- package/packages/record/lib/capture-run.mjs +125 -0
- package/packages/record/lib/capture-scratch.mjs +12 -3
- package/packages/record/lib/capture-service-definition.mjs +104 -0
- package/packages/record/lib/capture-service-install.mjs +362 -0
- package/packages/record/lib/capture-service-ownership.mjs +137 -0
- package/packages/record/lib/capture-service-runner.mjs +18 -0
- package/packages/record/lib/capture-small-snapshot.mjs +85 -0
- package/packages/record/lib/capture-source-discovery.mjs +319 -0
- package/packages/record/lib/capture-source-queue.mjs +199 -0
- package/packages/record/lib/capture-source-work.mjs +85 -0
- package/packages/record/lib/capture-state.mjs +16 -71
- package/packages/record/lib/capture-status.mjs +171 -0
- package/packages/record/lib/capture-supervisor.mjs +117 -0
- package/packages/record/lib/capture-watch.mjs +32 -0
- package/packages/record/lib/capture-work-session.mjs +238 -0
- package/packages/record/lib/capture-worker.mjs +58 -0
- package/packages/record/lib/derived-state.mjs +28 -15
- package/packages/record/lib/file-lines.mjs +22 -6
- package/packages/record/lib/formats.mjs +4 -3
- package/packages/record/lib/index-capture.mjs +97 -0
- package/packages/record/lib/index-db.mjs +3 -17
- package/packages/record/lib/index-reset.mjs +19 -0
- package/packages/record/lib/store.mjs +36 -11
- package/packages/record/lib/transcript-prefix.mjs +125 -0
- package/skills/oats-getting-started/SKILL.md +1 -1
- package/docs/macos-test-runs.md +0 -246
package/README.md
CHANGED
|
@@ -231,7 +231,7 @@ This README explains the framework and its direction. Advanced mechanisms such a
|
|
|
231
231
|
|
|
232
232
|
## Contributing and releases
|
|
233
233
|
|
|
234
|
-
Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS can be run on a
|
|
234
|
+
Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS, or on a Linux user's systemd manager, can be run by hand on a hosted runner: see [named test runs](docs/named-test-runs.md).
|
|
235
235
|
|
|
236
236
|
Versioned releases publish the kernel, Pi bridge and Desktop installers. Check the [release notes](docs/release-notes/) before changing an existing deployment; installing software does not automatically migrate knowledge or reconfigure live agents.
|
|
237
237
|
|
package/bin/oats.mjs
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* oats — the OATS command line.
|
|
4
4
|
*
|
|
5
|
-
* oats doctor [dir] [--soul <s>] [--json] show
|
|
5
|
+
* oats doctor [dir] [--soul <s>] [--json] show deployment and offline capture warnings; --soul: composition only
|
|
6
6
|
* oats onboard [<dir>] --workspace <ref> realize a workspace here (oats-local.yaml +
|
|
7
7
|
* agents/), then sync
|
|
8
8
|
* oats sync [--dir <d>] [--plan] [--json] discover the workspace, confirm membership,
|
|
@@ -25,6 +25,7 @@ import { constants as osConstants, homedir, tmpdir } from "node:os";
|
|
|
25
25
|
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
26
26
|
import { fileURLToPath } from "node:url";
|
|
27
27
|
import { performance } from "node:perf_hooks";
|
|
28
|
+
import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
|
|
28
29
|
import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
|
|
29
30
|
import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
|
|
30
31
|
import {
|
|
@@ -829,7 +830,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
|
829
830
|
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
830
831
|
composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
|
|
831
832
|
...(problems.length ? { problems } : {}),
|
|
832
|
-
warnings: hookEvents.warnings,
|
|
833
|
+
warnings: [...hookEvents.warnings, ...(soulName ? [] : doctorCaptureWarnings())],
|
|
833
834
|
};
|
|
834
835
|
}
|
|
835
836
|
/** Kernel/bridge version skew (published in lockstep from one tag), in every pi folder a launch
|
|
@@ -876,6 +877,7 @@ async function doctor(dir) {
|
|
|
876
877
|
for (const p of launchPreferences.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
|
|
877
878
|
const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
|
|
878
879
|
for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
|
|
880
|
+
if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
|
|
879
881
|
for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
|
|
880
882
|
for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
|
|
881
883
|
if (soulName) {
|
|
@@ -3463,7 +3465,13 @@ async function sessionCmd() {
|
|
|
3463
3465
|
if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
|
|
3464
3466
|
// --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
|
|
3465
3467
|
// status 20. Without it every key reaches the agent and there is no keyboard exit.
|
|
3466
|
-
|
|
3468
|
+
// What earlier attaches left (a viewer whose attach died without detaching): one line, on
|
|
3469
|
+
// stderr, before the client takes the terminal, and only when something was removed.
|
|
3470
|
+
const onSwept = ({ sessions, tables }) => {
|
|
3471
|
+
const n = (count, what) => `${count} ${what}${count === 1 ? "" : "s"}`;
|
|
3472
|
+
if (sessions + tables > 0) console.error(`oats: removed ${n(sessions, "leftover viewer session")} and ${n(tables, "key table")} of earlier attaches`);
|
|
3473
|
+
};
|
|
3474
|
+
process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key"), onSwept });
|
|
3467
3475
|
return;
|
|
3468
3476
|
}
|
|
3469
3477
|
if (args[1] === "inspect") result = inspectInstanceSession(home);
|
|
@@ -4070,12 +4078,12 @@ const EXPERIMENTAL_CMDS = new Set(["dress", "spawn", "segments", "mind"]);
|
|
|
4070
4078
|
async function recordCmd(sub) {
|
|
4071
4079
|
process.argv.splice(2, 1);
|
|
4072
4080
|
if (sub === "setup") {
|
|
4073
|
-
// setup writes a node into the user's Claude settings and into the capture
|
|
4081
|
+
// setup writes a node into the user's Claude settings and into the capture service's unit,
|
|
4074
4082
|
// and nothing rewrites them but setup run again: it is handed the rule's answer for the node
|
|
4075
4083
|
// running this kernel (docs/capabilities.md, "The node a hook writes down"). The script is
|
|
4076
4084
|
// imported into this process, so the variable is set here, over whatever the caller's
|
|
4077
4085
|
// environment held; packages/record imports nothing of the kernel.
|
|
4078
|
-
const { node, warning } = stableNode({ consequence: "the capture hooks and the capture
|
|
4086
|
+
const { node, warning } = stableNode({ consequence: "the capture hooks and the capture service stop when it goes away", remedy: "run `oats setup` again" });
|
|
4079
4087
|
if (warning) console.error(`oats: warning: ${warning}`);
|
|
4080
4088
|
process.env.OATS_NODE_BIN = node;
|
|
4081
4089
|
}
|
|
@@ -4885,8 +4893,8 @@ Usage:
|
|
|
4885
4893
|
[--launch-config <name>|none] command and preflight; read-only, nothing
|
|
4886
4894
|
[--harness r] [--model m] started; a named configuration is a unit, so
|
|
4887
4895
|
[--yolo | --no-yolo] --json a disagreeing --harness is refused
|
|
4888
|
-
oats doctor [dir] [--soul <name>] [--json] resolved targets
|
|
4889
|
-
--soul shows final composed AGENTS.md
|
|
4896
|
+
oats doctor [dir] [--soul <name>] [--json] resolved targets and offline capture warnings;
|
|
4897
|
+
--soul shows final composed AGENTS.md only
|
|
4890
4898
|
oats update [--check] [--yes] check npm for a newer kernel and move the pi bridge
|
|
4891
4899
|
[--dir <deployment>] in every pi folder the deployment's launches use
|
|
4892
4900
|
(docs/upgrading.md); then run oats doctor
|
|
@@ -4994,15 +5002,22 @@ Usage:
|
|
|
4994
5002
|
|
|
4995
5003
|
The turn record (core — every conversation captured, searchable, replicated):
|
|
4996
5004
|
oats capture [--watch|--status] land Claude Code/pi/codex sessions and aw
|
|
4997
|
-
[--owner <name>] [--root <dir>] client logs in the record
|
|
4998
|
-
|
|
5005
|
+
[--owner <name>] [--root <dir>] client logs in the record: one bounded
|
|
5006
|
+
supervised reconciliation pass; partial
|
|
5007
|
+
passes exit 0 with work pending
|
|
5008
|
+
oats capture --hook launch a detached pass; exit 0 means
|
|
5009
|
+
capture launched, not completed
|
|
5010
|
+
oats capture --health [--json] offline installation, run and issue
|
|
5011
|
+
diagnosis; captures nothing
|
|
4999
5012
|
oats capture --file <path> --format cc|pi|codex --home <instance home> [--json]
|
|
5000
5013
|
one session file (an archived session),
|
|
5001
5014
|
captured as --home capture would
|
|
5002
5015
|
oats recall [--kind k] [--thread t] search the whole record — mail, chat,
|
|
5003
5016
|
[--from f] [--show id] <query> sessions — with exact turn provenance
|
|
5004
|
-
oats setup [--owner <name>] [--
|
|
5005
|
-
[--no-service] [--no-hooks]
|
|
5017
|
+
oats setup [--owner <name>] [--root <dir>] [--replace-service]
|
|
5018
|
+
[--no-service] [--no-hooks] [--dry-run]
|
|
5019
|
+
install hooks + periodic capture
|
|
5020
|
+
(launchd/systemd), then run the first pass
|
|
5006
5021
|
|
|
5007
5022
|
oats experimental <dress|spawn|segments|mind> EXPERIMENTAL tools over the record —
|
|
5008
5023
|
selection and agent synthesis; unproven by
|
package/docs/capabilities.md
CHANGED
|
@@ -842,7 +842,7 @@ A package that also runs under a kernel older than the variable falls back to
|
|
|
842
842
|
`oats setup` is given the same answer: the kernel sets `OATS_NODE_BIN` in its
|
|
843
843
|
own process, over any value the caller's environment held, before it runs the
|
|
844
844
|
turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
|
|
845
|
-
into the capture hooks and the capture
|
|
845
|
+
into the capture hooks and the capture service's unit. In the third case
|
|
846
846
|
`oats setup` carries the warning, a dry run included.
|
|
847
847
|
|
|
848
848
|
### The worktree event
|
|
@@ -1103,6 +1103,50 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1103
1103
|
another session, another agent's terminal. Your own sessions keep your
|
|
1104
1104
|
setting.
|
|
1105
1105
|
|
|
1106
|
+
**An attach that dies without detaching leaves nothing behind.** A
|
|
1107
|
+
cgroup-wide `systemctl kill`, a stop timeout, oomd or a killed ssh can end
|
|
1108
|
+
`oats` and its tmux client together. `oats` itself then removes nothing, so
|
|
1109
|
+
the tmux server does. Once its client has attached, the viewer's client
|
|
1110
|
+
sets a `client-detached` hook on the viewer session alone: when a client
|
|
1111
|
+
leaves and none is left, the hook kills the viewer session. It is set after
|
|
1112
|
+
the attach, so a viewer whose client never attached is removed by `oats`
|
|
1113
|
+
or by the next attach's sweep. From then on, the server removes the viewer
|
|
1114
|
+
when its last client's connection drops without a word from the client:
|
|
1115
|
+
`oats` and its client SIGKILLed together (oomd, a stop timeout). A client
|
|
1116
|
+
that ends any other way (a hang-up, a termination, a `detach-client` from
|
|
1117
|
+
another client) is not seen by that hook: `oats` removes the viewer as it
|
|
1118
|
+
ends, or, if `oats` has died, the next attach's sweep does. The viewer never uses
|
|
1119
|
+
`destroy-unattached`: on tmux 3.4 it crashes the agents' server when another
|
|
1120
|
+
client detaches the viewer. A keyed viewer's key table (below)
|
|
1121
|
+
belongs to the server, not to the session, and its `client-detached` hook
|
|
1122
|
+
unbinds the table as it kills the session. For a viewer session that ends
|
|
1123
|
+
another way (its agent's window ends, a `kill-session`), a keyed viewer sets
|
|
1124
|
+
one global hook entry on the agents' server, `session-closed[900]`: when a
|
|
1125
|
+
session whose name is a viewer's closes, the entry unbinds the key table of
|
|
1126
|
+
that name. It is the only global hook entry OATS owns there.
|
|
1127
|
+
Every keyed viewer sets the same entry again, which leaves it unchanged,
|
|
1128
|
+
and no other index is touched. Keep your own `session-closed` hooks
|
|
1129
|
+
(`set-hook -g` in `~/.tmux.conf`) at other indexes: an entry of yours at
|
|
1130
|
+
900 is replaced. A global `client-detached` hook of yours does not run
|
|
1131
|
+
for a viewer's client whose connection dropped: the viewer session's own
|
|
1132
|
+
hook takes its place there. The entry needs `run-shell -C`, which tmux has from 3.2.
|
|
1133
|
+
Before 3.2 it does nothing, and the next attach's sweep removes the table.
|
|
1134
|
+
|
|
1135
|
+
Every attach also sweeps the server before it opens its viewer. It removes:
|
|
1136
|
+
|
|
1137
|
+
- a viewer session (`oatsview-<pid>-<8 hex>`) with no client attached,
|
|
1138
|
+
whose attaching process, the pid in its name, no longer exists;
|
|
1139
|
+
- a viewer key table whose session no longer exists.
|
|
1140
|
+
|
|
1141
|
+
The sweep keeps a viewer whose attach is alive, even with no client: its
|
|
1142
|
+
client may not have attached yet. It also never removes an attached
|
|
1143
|
+
viewer, anything not named as a viewer, or the `oatsview-locked` table
|
|
1144
|
+
that every viewer without a key shares. When it removed something, the
|
|
1145
|
+
attach prints one line on stderr before the viewer opens:
|
|
1146
|
+
`oats: removed <n> leftover viewer session(s) and <m> key table(s) of
|
|
1147
|
+
earlier attaches`. A failed sweep is not the attach's failure; the next
|
|
1148
|
+
attach sweeps again.
|
|
1149
|
+
|
|
1106
1150
|
On tmux 3.2 and later the viewer's tmux client asks for synchronized
|
|
1107
1151
|
output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
|
|
1108
1152
|
DEC mode 2026, so a terminal that receives a redraw in two pieces does not
|
|
@@ -1119,9 +1163,11 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1119
1163
|
The key is taken from the agent's input: the agent never receives it while
|
|
1120
1164
|
this viewer is attached. A keyed viewer reads a tmux key table of its own,
|
|
1121
1165
|
named as its temporary session and removed with it, so the key is bound
|
|
1122
|
-
for that viewer alone.
|
|
1123
|
-
|
|
1124
|
-
|
|
1166
|
+
for that viewer alone. The key's binding also removes the viewer session's
|
|
1167
|
+
`client-detached` hook before it detaches: the session outlives its client
|
|
1168
|
+
until `oats` has read that the key was used, and `oats` then removes it.
|
|
1169
|
+
Check the feature in `oats version --json` before passing the flag: a
|
|
1170
|
+
kernel without it ignores the flag and opens a viewer with no exit.
|
|
1125
1171
|
|
|
1126
1172
|
The key is one of these, spelled exactly (case-sensitive):
|
|
1127
1173
|
|
package/docs/implementation.md
CHANGED
|
@@ -79,7 +79,7 @@ and the rules its tests pin.
|
|
|
79
79
|
| `souls/` | this repository's own souls (a workspace member) |
|
|
80
80
|
| `docs/` | the reference pages, schemas, design records and release notes |
|
|
81
81
|
| `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
|
|
82
|
-
| `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane
|
|
82
|
+
| `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane, the assembly of release-notes entries, and the hand-started named test runs on macOS and Linux (`named-test-run.mjs`, with `macos-tests.mjs` and `linux-tests.mjs`: [named test runs](named-test-runs.md)) |
|
|
83
83
|
| `test/` | the kernel and CLI suites, with their fixtures |
|
|
84
84
|
|
|
85
85
|
## Kernel modules
|
|
@@ -96,6 +96,7 @@ and the rules its tests pin.
|
|
|
96
96
|
| `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
|
|
97
97
|
| `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
|
|
98
98
|
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
|
|
99
|
+
| `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
|
|
99
100
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
100
101
|
| `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
|
|
101
102
|
| `launch-preference.mjs` | a soul's launch preference, pure: the layers a new launch reads, the `Launch` report, and `launchKeysUnmatched`, the one function that decides which keys of `souls.launch` name no soul. It decides from a description of one read of the workspace (`soulsOffered` in `instance-resolution.mjs`, built from the discovery and its `soulsUnread`); a reader never computes the answer itself. What a read did not record, it did not establish: a discovery with no `soulsUnread` leaves every key unchecked (`unrecorded`), and a member's enumeration with no `soulsSkipped` counts as one with a soul skipped (`skippedSome` in `workspace.mjs`). `launchLayers` takes that description and carries the unmatched keys, so every caller that has layers has the fact, and `launchPreferenceUnmatched` is the one constructor of `E_LAUNCH_PREFERENCE_UNMATCHED` (its code and the bound of its texts are the exported `LAUNCH_PREFERENCE_UNMATCHED` and `LAUNCH_PROBLEM_TEXT_MAX`): `selectNewLaunch` throws it and `launchReportFor` reports it, both in `core.mjs`, before the refusals that describe the fall-through launch. `soulLaunchCommand` is the one place the command an answer suggests (`oats soul launch set\|remove …`) is rendered: the `fix` of a launch refusal (`harnessFix`, `launchConfigUnknownFix`, `launchConfigAmbiguous`), the texts about an unmatched key and `oats doctor`'s `remedy` all call it, and none tells a person to edit `souls.launch` in the file. The one exception is made there too: a key that holds a character the kernel never prints (`REFUSED_TEXT`) cannot be written into a command line, so the function gives no command and says the key is deleted from the file by hand; `launchKeyQuoted` is the one quoting of a key in a sentence, with such a character replaced (`safeText`). No sentence checks its key itself |
|
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
# Named test runs on macOS and Linux
|
|
2
|
+
|
|
3
|
+
Pull-request CI runs the tests on Linux, in its own way: sharded, and with no
|
|
4
|
+
working `systemctl --user`. Some tests need something CI does not give them,
|
|
5
|
+
and two workflows run them by hand:
|
|
6
|
+
|
|
7
|
+
- **macOS.** Some tests rest on what only macOS does: a file system that
|
|
8
|
+
ignores case, `/var` and `/tmp` as links, long temporary paths, the BSD
|
|
9
|
+
tools. [`macos-tests.yml`](../.github/workflows/macos-tests.yml) runs named
|
|
10
|
+
test files of a named ref on a macOS runner.
|
|
11
|
+
- **Linux, with a user manager.** Some tests drive the runner user's own
|
|
12
|
+
systemd manager, a real `.timer` and `.service` under `systemctl --user`.
|
|
13
|
+
[`linux-tests.yml`](../.github/workflows/linux-tests.yml) runs named test
|
|
14
|
+
files of a named ref on a Linux runner. Before the run, the workflow enables
|
|
15
|
+
lingering for the runner user and waits for that user's manager to answer.
|
|
16
|
+
|
|
17
|
+
A person starts either one by hand; no push and no pull request ever does. The
|
|
18
|
+
link of a run goes on a pull request as that pull request's macOS or Linux
|
|
19
|
+
evidence.
|
|
20
|
+
|
|
21
|
+
Neither is a second CI. A run runs the files you name, each alone, and nothing
|
|
22
|
+
else: not `npm test`, not a shard.
|
|
23
|
+
|
|
24
|
+
Both workflows run one implementation,
|
|
25
|
+
[`scripts/named-test-run.mjs`](../scripts/named-test-run.mjs). Each runner's
|
|
26
|
+
own part is a small script beside it:
|
|
27
|
+
[`scripts/macos-tests.mjs`](../scripts/macos-tests.mjs) and
|
|
28
|
+
[`scripts/linux-tests.mjs`](../scripts/linux-tests.mjs). Everything this page
|
|
29
|
+
says of "a run" holds for both, unless a section names one runner.
|
|
30
|
+
|
|
31
|
+
## Starting a run
|
|
32
|
+
|
|
33
|
+
You need write access to the repository. From a checkout:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
gh workflow run macos-tests.yml --ref main \
|
|
37
|
+
-f ref=my-branch \
|
|
38
|
+
-f files='test/tui-terminal.test.mjs test/fixture-isolation.test.mjs' \
|
|
39
|
+
-f tmux=true
|
|
40
|
+
gh run list --workflow=macos-tests.yml --limit 1
|
|
41
|
+
|
|
42
|
+
gh workflow run linux-tests.yml --ref main \
|
|
43
|
+
-f ref=my-branch \
|
|
44
|
+
-f files='test/some-real-manager.test.mjs'
|
|
45
|
+
gh run list --workflow=linux-tests.yml --limit 1
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Or use the repository's Actions page. Choose **macOS tests** or **Linux
|
|
49
|
+
tests**, then **Run workflow**. Leave the workflow's own branch at `main` (see
|
|
50
|
+
[What counts as evidence](#what-counts-as-evidence)).
|
|
51
|
+
|
|
52
|
+
| input | workflow | what it is |
|
|
53
|
+
|---|---|---|
|
|
54
|
+
| `ref` | both | The commit to test: a branch name, a tag name or a full commit id (40 characters) of this repository. |
|
|
55
|
+
| `files` | both | The test files, separated by spaces, commas or newlines. |
|
|
56
|
+
| `tmux` | macOS | `true` installs tmux first (`brew install tmux`). Off by default. Tests that need tmux skip without it. |
|
|
57
|
+
|
|
58
|
+
The Linux workflow has no `tmux` input. Whether tmux is on the runner's `PATH`
|
|
59
|
+
is printed in its header like any other fact of the runner.
|
|
60
|
+
|
|
61
|
+
## What a run accepts
|
|
62
|
+
|
|
63
|
+
The runner's script checks the whole request before anything of the ref is
|
|
64
|
+
checked out, installed or run. A refusal names every entry it refuses and why,
|
|
65
|
+
and the run fails having run nothing.
|
|
66
|
+
|
|
67
|
+
**The ref** must be a commit of this repository: one reachable from a branch
|
|
68
|
+
or a tag of `origin`.
|
|
69
|
+
|
|
70
|
+
- A name is made of `A-Z a-z 0-9 . _ / -`, does not start with `-` and has no
|
|
71
|
+
`..`. A branch whose name has another character is given by its full commit
|
|
72
|
+
id. The text is taken as typed: a space before or after it is refused too.
|
|
73
|
+
- A shortened commit id is refused: give all 40 characters.
|
|
74
|
+
- **A pull request's number is not accepted.** A pull request from a fork has
|
|
75
|
+
a head that is not this repository's commit, and nothing is ever fetched by
|
|
76
|
+
what you typed. Name the branch, or give the commit id, of a pull request
|
|
77
|
+
whose branch is in this repository.
|
|
78
|
+
- A name that is both a branch and a tag is accepted when both are the same
|
|
79
|
+
commit. Otherwise give the commit id of the one you mean.
|
|
80
|
+
|
|
81
|
+
**Each file** must match `test/**/*.test.mjs` or
|
|
82
|
+
`packages/<name>/test/**/*.test.mjs`, with path segments made of
|
|
83
|
+
`A-Z a-z 0-9 . _ -`, none starting with a dot. It must be a regular file at
|
|
84
|
+
that commit, not a symbolic link. A file named twice runs once.
|
|
85
|
+
|
|
86
|
+
## What a run does and prints
|
|
87
|
+
|
|
88
|
+
The job checks out two trees. `runner/` is the workflow's own commit, and the
|
|
89
|
+
script runs from it. `tested/` is the ref. Two trees are for two things: a
|
|
90
|
+
ref older than the workflow can be tested, and an honest branch cannot change
|
|
91
|
+
the runner by accident. They are not a defence against a commit that sets out
|
|
92
|
+
to forge its result (see [What a run does not protect](#what-a-run-does-not-protect)).
|
|
93
|
+
|
|
94
|
+
On Linux, two steps come before the validation, so that its header can report
|
|
95
|
+
their effect:
|
|
96
|
+
|
|
97
|
+
1. `sudo loginctl enable-linger "$USER"` starts the runner user's systemd
|
|
98
|
+
manager without a login session. It is the only privileged step, and
|
|
99
|
+
nothing is installed system-wide.
|
|
100
|
+
2. `XDG_RUNTIME_DIR=/run/user/<uid>` is set for the later steps, through
|
|
101
|
+
`$GITHUB_ENV`, so that `systemctl --user` finds the manager.
|
|
102
|
+
|
|
103
|
+
After the validation, the job installs as pull-request CI does: `npm ci` at
|
|
104
|
+
the root, then in `packages/desktop` without the Electron binary. Then it runs
|
|
105
|
+
each file alone, one after another, as a developer does: `node --test <file>`
|
|
106
|
+
from the root of the ref's tree.
|
|
107
|
+
|
|
108
|
+
The step **Validate the request and check out its commit** prints a header,
|
|
109
|
+
before any code of the ref has run. The header gives:
|
|
110
|
+
|
|
111
|
+
- the commit under test (full id) and the ref that was asked for;
|
|
112
|
+
- the workflow's own ref and commit, as the script reads them. Where a run
|
|
113
|
+
really ran from is GitHub's record of it, not this line: see
|
|
114
|
+
[What counts as evidence](#what-counts-as-evidence);
|
|
115
|
+
- on macOS, the macOS version; on Linux, the distribution and the kernel;
|
|
116
|
+
- the runner image and the architecture;
|
|
117
|
+
- on Linux:
|
|
118
|
+
- `XDG_RUNTIME_DIR`;
|
|
119
|
+
- whether lingering is on for the runner user (`loginctl show-user`);
|
|
120
|
+
- **whether the user manager answered**, with which state, how many
|
|
121
|
+
times it was asked and how long that took. Lingering only queues the
|
|
122
|
+
manager's start, so the step waits for it, at most 60 seconds in all.
|
|
123
|
+
Until the manager's bus is there, `systemctl --user` answers at once
|
|
124
|
+
(`offline` or `unknown`), so the step asks again every half second.
|
|
125
|
+
Once the bus is there, `systemctl --user is-system-running --wait` waits
|
|
126
|
+
for the manager to finish starting. `running` and `degraded` count as an
|
|
127
|
+
answer. `degraded` is a running manager with a failed unit, which the
|
|
128
|
+
image may have of its own;
|
|
129
|
+
- the Node version;
|
|
130
|
+
- whether the file system is case-sensitive, measured there (a file is made,
|
|
131
|
+
then looked for by another case);
|
|
132
|
+
- whether `tmux` is on `PATH`, and its version;
|
|
133
|
+
- whether a socket is at tmux's default place for the server named `oats`.
|
|
134
|
+
|
|
135
|
+
Its last line says so: `Everything above this line was printed before any code
|
|
136
|
+
of the ref ran.` On Linux, a user manager that did not answer ends the step
|
|
137
|
+
there instead. The header says what was answered, then `Refused: nothing was
|
|
138
|
+
installed or run.`, and the run fails before anything is installed.
|
|
139
|
+
|
|
140
|
+
The step **Run each file alone** prints the header again before the first
|
|
141
|
+
file. It is read after the installs, and the step says that it is the second
|
|
142
|
+
reading. On Linux the user manager is asked again, without waiting. If it does
|
|
143
|
+
not answer, no file runs and the run fails.
|
|
144
|
+
|
|
145
|
+
For each file the log has its output, then its counts (tests, passed, failed,
|
|
146
|
+
skipped, cancelled, todo), its exit status and its duration. One table of all
|
|
147
|
+
files ends the log, and the job's summary page repeats it.
|
|
148
|
+
|
|
149
|
+
**What fails a run:**
|
|
150
|
+
|
|
151
|
+
- A file fails when its exit status is not 0. A file that ends with status 0
|
|
152
|
+
and prints no summary, or whose summary counts a failed test, fails too. The
|
|
153
|
+
files after a failing one still run.
|
|
154
|
+
- A file that has not ended after its time is killed with its whole process
|
|
155
|
+
group and reported as timed out. The run goes on.
|
|
156
|
+
- **A tmux server left on the default socket.** A fixture that fails to
|
|
157
|
+
isolate its tmux server starts one at tmux's default place
|
|
158
|
+
(`<dir>/tmux-<uid>/oats`, where `<dir>` is `TMUX_TMPDIR`, else `/tmp`). On a
|
|
159
|
+
clean runner nothing fails because of it. So the script looks at that place
|
|
160
|
+
before the first file and after each file. The file after which a socket
|
|
161
|
+
first exists is marked in the table, and the run fails. Nothing is killed or
|
|
162
|
+
removed. If a socket is there before the first file, the header says so and
|
|
163
|
+
the check is skipped for that run.
|
|
164
|
+
- **On Linux, a user manager that does not answer**, at either step (above).
|
|
165
|
+
|
|
166
|
+
A file in which no test passed (every test skipped, for example without tmux,
|
|
167
|
+
or outside the workflow its guard names) is marked `no test passed`. It does
|
|
168
|
+
not fail the run.
|
|
169
|
+
|
|
170
|
+
## Guard contract
|
|
171
|
+
|
|
172
|
+
A test that only means something on one of these runners guards on facts the
|
|
173
|
+
runner gives it. Each workflow's `name:` is part of that guard, and it is a
|
|
174
|
+
contract: the workflow tests pin it (`test/macos-tests-workflow.test.mjs`,
|
|
175
|
+
`test/linux-tests-workflow.test.mjs`). Renaming a workflow turns every test
|
|
176
|
+
that guards on it into a skip.
|
|
177
|
+
|
|
178
|
+
| runner | the test runs only when |
|
|
179
|
+
|---|---|
|
|
180
|
+
| macOS | `GITHUB_WORKFLOW` is `macOS tests`, `GITHUB_EVENT_NAME` is `workflow_dispatch`, and `process.platform` is `darwin` |
|
|
181
|
+
| Linux | `GITHUB_WORKFLOW` is `Linux tests`, `GITHUB_EVENT_NAME` is `workflow_dispatch`, and `process.platform` is `linux` |
|
|
182
|
+
|
|
183
|
+
The run passes its environment to each file as a developer's shell would. It
|
|
184
|
+
leaves out the request's two variables, the runner's command files
|
|
185
|
+
(`GITHUB_ENV`, `GITHUB_OUTPUT`, `GITHUB_PATH`, `GITHUB_STATE`,
|
|
186
|
+
`GITHUB_STEP_SUMMARY`) and node's nested-run marker. So `GITHUB_WORKFLOW` and
|
|
187
|
+
`GITHUB_EVENT_NAME` reach the test, and on Linux so does `XDG_RUNTIME_DIR`.
|
|
188
|
+
|
|
189
|
+
A guard is a switch, not a proof. Anyone can set these variables on their own
|
|
190
|
+
machine, and a guarded test that runs there drives that machine's real
|
|
191
|
+
manager. A guarded test outside its runner skips, and a run of only skips is
|
|
192
|
+
not evidence (below).
|
|
193
|
+
|
|
194
|
+
## What counts as evidence
|
|
195
|
+
|
|
196
|
+
**A run is evidence for a commit whose diff has been reviewed.** A run of a
|
|
197
|
+
commit that nobody has read proves nothing about it: from its first install
|
|
198
|
+
step on, the commit's own code runs on the runner and can change what the run
|
|
199
|
+
prints (see [What a run does not protect](#what-a-run-does-not-protect)).
|
|
200
|
+
|
|
201
|
+
The pull request gives **the run's link**. From it, a run is evidence when all
|
|
202
|
+
of this holds. The first condition comes first because the others rest on it.
|
|
203
|
+
|
|
204
|
+
1. **The workflow ran from `main`, by GitHub's own record of the run.** Not
|
|
205
|
+
by the log. A run started from another branch uses that branch's workflow
|
|
206
|
+
file and that branch's script, so every line of its log, the header
|
|
207
|
+
included, is text that branch wrote. Ask GitHub about the run instead:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
gh run view <run id> --json event,headSha,workflowName
|
|
211
|
+
git fetch origin
|
|
212
|
+
git merge-base --is-ancestor <headSha> origin/main; echo $?
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
`event` must be `workflow_dispatch`. `workflowName` must be `macOS tests`
|
|
216
|
+
for macOS evidence, or `Linux tests` for Linux evidence. The last command
|
|
217
|
+
must print `0`: the workflow's commit is a commit of `main`. Anything else
|
|
218
|
+
is not a pass: `1` means the commit is not on `main`, and an error means
|
|
219
|
+
your clone does not have it. Check the commit, not the run's branch name: a
|
|
220
|
+
tag can carry a branch's name.
|
|
221
|
+
2. The `commit under test` in the validation step's header **equals the head
|
|
222
|
+
under review**. A run of an earlier head is evidence for that head only.
|
|
223
|
+
3. The run passed, and no file the pull request relies on is marked `no test
|
|
224
|
+
passed`. **A run of only skips is not evidence.**
|
|
225
|
+
|
|
226
|
+
The header also prints a `workflow ref` line. It is a convenience for
|
|
227
|
+
reading a run, and it is not proof of where the workflow ran from: the
|
|
228
|
+
workflow prints it.
|
|
229
|
+
|
|
230
|
+
With the first condition met, the log is the evidence. The job's summary page
|
|
231
|
+
is a convenience.
|
|
232
|
+
|
|
233
|
+
## Bounds
|
|
234
|
+
|
|
235
|
+
These are constants of the scripts, not inputs:
|
|
236
|
+
|
|
237
|
+
| bound | macOS | Linux |
|
|
238
|
+
|---|---|---|
|
|
239
|
+
| files in one run | at most 10 files | at most 10 files |
|
|
240
|
+
| time for one file, then its process group is killed | 5 minutes | 20 minutes |
|
|
241
|
+
| time for the job | 60 minutes | 240 minutes |
|
|
242
|
+
| wait for the user manager | none | 60 seconds at the validation step |
|
|
243
|
+
| runner | `macos-14` (arm64), Node 22 | `ubuntu-24.04` (x64), Node 22 |
|
|
244
|
+
|
|
245
|
+
A Linux file gets 20 minutes because the files that qualify the record
|
|
246
|
+
capture at scale ([#1108](https://github.com/awebai/oats/issues/1108)) run
|
|
247
|
+
capture passes of up to 300 seconds, and a first upgrade may need several.
|
|
248
|
+
The Linux job's 240 minutes hold ten such files and the installs, under
|
|
249
|
+
GitHub's 6-hour limit for a job.
|
|
250
|
+
|
|
251
|
+
The workflows' steps upload no artifact and save or restore no cache: the log
|
|
252
|
+
and the summary are all they leave. The token can read the repository's
|
|
253
|
+
contents and do nothing more, and the workflows name no secret. The code a
|
|
254
|
+
run executes can reach more than the workflow's own steps do: see
|
|
255
|
+
[What a run does not protect](#what-a-run-does-not-protect).
|
|
256
|
+
|
|
257
|
+
## What a run does not show
|
|
258
|
+
|
|
259
|
+
- **A clean machine, not yours.** The runner is a fresh image for each run.
|
|
260
|
+
It has no person's `PATH`, shell profile or login environment, and nothing
|
|
261
|
+
of an earlier run.
|
|
262
|
+
- **No real terminal.** No terminal emulator is attached to the tests.
|
|
263
|
+
- **One version and one architecture**: the image's, printed in the header.
|
|
264
|
+
- **A killed file's leftovers.** The script kills the process group of a file
|
|
265
|
+
that timed out. A tmux server has left that group by design, so a tmux
|
|
266
|
+
server of a killed file stays, and it is that test's to explain. On Linux,
|
|
267
|
+
a unit a test started under the user manager is not in the file's process
|
|
268
|
+
group either: it is the test's to stop.
|
|
269
|
+
- **Nothing about `main`.** A run started from `main` is listed among the
|
|
270
|
+
runs of main's head commit (`gh run list --commit <sha>`). It is also among
|
|
271
|
+
that commit's check runs, as `Named test files on macOS` or
|
|
272
|
+
`Named test files on Linux`. Its result is about the ref under test. It
|
|
273
|
+
says nothing about `main`, a failed run included. The commit's status
|
|
274
|
+
rollup does not hold these runs. A hand-started run can be the newest run
|
|
275
|
+
on `main`. So whoever checks `main` after a merge lists the runs by
|
|
276
|
+
workflow (`gh run list --workflow CI --branch main`) or reads the commit's
|
|
277
|
+
status rollup.
|
|
278
|
+
|
|
279
|
+
**What a Linux run does not show: a person's machine.** The user manager is
|
|
280
|
+
real systemd, but it runs on a hosted VM, not on a person's computer:
|
|
281
|
+
|
|
282
|
+
- The runner user has no login session. No PAM session was opened, no
|
|
283
|
+
graphical session exists, and no seat is assigned. Lingering, which the
|
|
284
|
+
workflow switched on, is what starts the manager. On a person's machine,
|
|
285
|
+
logging in starts it, and lingering is usually off: there, a user's timers
|
|
286
|
+
stop when the person logs out.
|
|
287
|
+
- The manager has none of a person's own units, environment
|
|
288
|
+
(`systemctl --user show-environment`) or `~/.config/systemd/user`. It has
|
|
289
|
+
only what the image and the test put there.
|
|
290
|
+
- It is one distribution, one systemd version and one image: Ubuntu 24.04,
|
|
291
|
+
as printed in the header. Another distribution's systemd or defaults are
|
|
292
|
+
not covered.
|
|
293
|
+
- Time is the VM's. A run shows what a timer does within the file's 20
|
|
294
|
+
minutes. It does not show a timer's behaviour across a suspend, a reboot or
|
|
295
|
+
days.
|
|
296
|
+
|
|
297
|
+
So a Linux run is evidence that the code drives `systemctl --user` correctly
|
|
298
|
+
on a working user manager. It is not evidence of how the code behaves on a
|
|
299
|
+
person's machine, which still needs a person's run there.
|
|
300
|
+
|
|
301
|
+
A pull request that asks for a person's run on a Mac still gets one.
|
|
302
|
+
|
|
303
|
+
## What a run does not protect
|
|
304
|
+
|
|
305
|
+
After the validation, the ref's own code runs on the runner as the runner's
|
|
306
|
+
user: its install scripts, then its tests. Pull-request CI does the same for
|
|
307
|
+
every branch.
|
|
308
|
+
|
|
309
|
+
**Protected, in a run whose workflow commit is `main`'s: the validation and
|
|
310
|
+
the header.** They are printed from the workflow's own commit, before any
|
|
311
|
+
code of the ref has run. A commit under test cannot change which commit the
|
|
312
|
+
header names, or get a refused request past it. In a run started from another
|
|
313
|
+
branch nothing is protected: the workflow and the script are that branch's
|
|
314
|
+
(see [What counts as evidence](#what-counts-as-evidence)).
|
|
315
|
+
|
|
316
|
+
**Not protected: everything after the first install step**, the per-file
|
|
317
|
+
results and the table included. From there on, the ref's code can change
|
|
318
|
+
anything the runner's user can, and so what the later steps print. The result
|
|
319
|
+
is as honest as the commit. On Linux that includes the user manager: the
|
|
320
|
+
ref's code can start, stop or change its units.
|
|
321
|
+
|
|
322
|
+
**Where the check is.** A forgery has to be in the commit's own tree, its lock
|
|
323
|
+
file included. The evidence names that exact commit, and the reviewer of the
|
|
324
|
+
pull request reads its diff. Pull-request CI has the same property.
|
|
325
|
+
|
|
326
|
+
**The cache scope of the default branch.** A run started from the default
|
|
327
|
+
branch belongs to it, and executes another branch's code. Such code can reach
|
|
328
|
+
that run's Actions cache scope, which every branch reads. Only somebody with
|
|
329
|
+
write access can do it, by pushing the branch and starting the run. In the
|
|
330
|
+
maintainers' words: a run of this workflow can write the default branch's
|
|
331
|
+
cache scope; nothing reads it; a workflow that starts to restore a cache
|
|
332
|
+
reopens this. No workflow of this repository restores an Actions cache, and
|
|
333
|
+
the repository's tests keep it so.
|
|
334
|
+
|
|
335
|
+
**The job's token.** It is within reach of the code a run executes. It can
|
|
336
|
+
read this repository's contents and nothing else, and that is why neither
|
|
337
|
+
workflow's `permissions` ever grows.
|
|
338
|
+
|
|
339
|
+
**Root on the Linux runner.** The hosted Linux runner's user can use `sudo`
|
|
340
|
+
without a password: that is how the workflow enables lingering. The ref's
|
|
341
|
+
code can use it too. The VM is discarded after the run, and the token's
|
|
342
|
+
reach does not grow with root.
|
|
343
|
+
|
|
344
|
+
## What the first Linux run from `main` proves
|
|
345
|
+
|
|
346
|
+
The Linux workflow can only be proven by a run of it from `main`. Its first
|
|
347
|
+
run, of an existing test file and a short check that `systemctl --user`
|
|
348
|
+
works, shows three things:
|
|
349
|
+
|
|
350
|
+
- the workflow starts and validates as the macOS one does;
|
|
351
|
+
- lingering and `XDG_RUNTIME_DIR` give that image a user manager that answers
|
|
352
|
+
within the bound. The header states the answer, how many times the manager
|
|
353
|
+
was asked and how long it took: an answer at the first ask, well under the
|
|
354
|
+
bound, shows that image did not need the wait;
|
|
355
|
+
- the installs and a per-file run work on that image.
|
|
356
|
+
|
|
357
|
+
It does not show what a guarded test sees, or does. The run's environment has
|
|
358
|
+
the facts the [Guard contract](#guard-contract) names, but no test file of
|
|
359
|
+
this repository guards on them yet. A guarded file's behaviour is shown when
|
|
360
|
+
such a file is dispatched, by its own run. The first run also does not show
|
|
361
|
+
that a later image still answers: every run's header says so again.
|
|
362
|
+
|
|
363
|
+
## The terms
|
|
364
|
+
|
|
365
|
+
The maintainers agreed these terms, the same for both workflows.
|
|
366
|
+
`test/macos-tests-workflow.test.mjs` and `test/linux-tests-workflow.test.mjs`
|
|
367
|
+
read the workflow files and pin each one, through the checks they share in
|
|
368
|
+
`test/helpers/named-tests-workflow.mjs`:
|
|
369
|
+
|
|
370
|
+
- `workflow_dispatch` is the only trigger;
|
|
371
|
+
- `permissions` is exactly `contents: read`; no secret is named; no artifact
|
|
372
|
+
is uploaded; no step saves or restores a cache;
|
|
373
|
+
- no input is written into a shell line: the ref and the file list reach the
|
|
374
|
+
script as environment variables;
|
|
375
|
+
- the checkout is the workflow's own commit, without its token left in the
|
|
376
|
+
checkout's configuration;
|
|
377
|
+
- the job has a timeout, and its concurrency group is its own and one per
|
|
378
|
+
run, so no later run cancels an earlier one;
|
|
379
|
+
- each workflow's `name:` is the one in [Guard contract](#guard-contract).
|
|
380
|
+
|
|
381
|
+
Change a bound or a term with the maintainers' decision, and change this page
|
|
382
|
+
and those tests in the same commit.
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.13.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.13.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
13
|
| `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
14
|
| `oats.aweb` | `v1.29.0` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
package/docs/packages.md
CHANGED
|
@@ -51,7 +51,7 @@ packages:
|
|
|
51
51
|
- **Bare version** (`v5.2.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.2.1` or `oats-framework/v1.13.
|
|
54
|
+
convention (`v5.2.1` or `oats-framework/v1.13.1`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,7 +74,7 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.13.
|
|
77
|
+
oats.framework: v1.13.1
|
|
78
78
|
oats.okf: v5.2.1
|
|
79
79
|
oats.aweb: v1.29.0
|
|
80
80
|
teams:
|
|
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
|
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
355
|
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.1", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.13.
|
|
362
|
-
resolves to tag `oats-framework/v1.13.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.13.1`
|
|
362
|
+
resolves to tag `oats-framework/v1.13.1`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|