@awebai/oats 0.63.0 → 0.65.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.
Files changed (47) hide show
  1. package/README.md +14 -1
  2. package/bin/oats.mjs +158 -26
  3. package/docs/desktop-cli-api.md +127 -3
  4. package/docs/desktop.md +14 -5
  5. package/docs/execution-targets.md +9 -5
  6. package/docs/first-team.md +6 -0
  7. package/docs/implementation.md +17 -3
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-notes/v0.64.0.md +105 -0
  11. package/docs/release-notes/v0.65.0.md +187 -0
  12. package/docs/souls-and-instances.md +26 -6
  13. package/docs/tui.md +416 -238
  14. package/docs/upgrading.md +2 -1
  15. package/docs/workspaces.md +125 -1
  16. package/lib/core.mjs +43 -11
  17. package/lib/deployments.mjs +325 -0
  18. package/lib/resolved-deployment.mjs +37 -0
  19. package/lib/session-input.mjs +12 -2
  20. package/lib/workspace.mjs +2 -0
  21. package/package-catalog.json +1 -1
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/deployment-label.mjs +2 -2
  25. package/packages/client/deployment-list-cli.mjs +98 -0
  26. package/packages/client/deployment-list.mjs +91 -0
  27. package/packages/client/instance-tree.mjs +53 -3
  28. package/packages/client/keymap.mjs +106 -0
  29. package/packages/client/own-codes.mjs +2 -0
  30. package/packages/client/panel-views.mjs +1 -1
  31. package/packages/client/roster-sections.mjs +22 -6
  32. package/packages/client/workspace-admission.mjs +2 -1
  33. package/packages/tui/README.md +4 -4
  34. package/packages/tui/lib/actions.mjs +29 -5
  35. package/packages/tui/lib/client.mjs +3 -1
  36. package/packages/tui/lib/config.mjs +21 -14
  37. package/packages/tui/lib/main.mjs +108 -31
  38. package/packages/tui/lib/model.mjs +71 -41
  39. package/packages/tui/lib/read.mjs +15 -45
  40. package/packages/tui/lib/store.mjs +158 -39
  41. package/packages/tui/lib/term/through.mjs +40 -18
  42. package/packages/tui/lib/views/act.mjs +17 -13
  43. package/packages/tui/lib/views/frame.mjs +418 -421
  44. package/packages/tui/lib/views/help.mjs +41 -19
  45. package/packages/tui/lib/views/instances.mjs +38 -9
  46. package/packages/tui/lib/views/switcher.mjs +65 -21
  47. package/skills/oats-getting-started/SKILL.md +440 -170
@@ -21,6 +21,7 @@ import { ownEllipsis, shownLines } from "./term/text.mjs";
21
21
  import { textWidth } from "./term/width.mjs";
22
22
  import { windowOf } from "./views/scroll.mjs";
23
23
  import { SOUL_COLOURS } from "./views/souls.mjs";
24
+ import { leadRows } from "./views/switcher.mjs";
24
25
 
25
26
  /** The widest the word column of the list may be, in cells. */
26
27
  export const WORD_MAX = 20;
@@ -165,7 +166,7 @@ function build(state, at) {
165
166
  const heading = (deployment, label, path = null) => {
166
167
  const its = deploymentState(deployment), up = its.key === "live";
167
168
  // A machine's rows are what it reported at the last roster read: that time stands on its
168
- // heading only when the header's time is another, so the heading of a machine read with
169
+ // heading only when the time of this read (the help's top row) is another, so the heading of a machine read with
169
170
  // this one is its name alone. A deployment that is not live has its state and short reason
170
171
  // in the shared words instead, and no time.
171
172
  const read = up && deployment.local === false ? clockTime(state.rosterAt) : null;
@@ -215,7 +216,7 @@ function build(state, at) {
215
216
  // machine is in it: both read from the shared entries (`local`), never decided here.
216
217
  const away = [...new Set(deployments.filter((d) => d.local === false && text(d.machine)).map((d) => d.machine))];
217
218
  const machines = away.length, here = deployments.some((d) => d.local === true);
218
- // Whether a list stands under the header: not for a deployment of this machine that was never
219
+ // Whether a list stands in the sidebar: not for a deployment of this machine that was never
219
220
  // observed, nor for a machine that is not live and has no row kept. Each has only its reason.
220
221
  const observed = panel !== null && !gone && (local ? status === "observed" : live || instances.length > 0);
221
222
  return {
@@ -283,7 +284,7 @@ function flatten(base, cols, ascii) {
283
284
  * they changed. The flattening for the last width asked is kept beside it. */
284
285
  const MADE_FROM = ["entries", "remote", "memory", "notes", "rosterAt", "collecting", "ctxs", "open", "collapsed", "cli", "home", "retiring", "ascii"];
285
286
  let kept = null;
286
- /** The roster of a state: the rows in drawn order and what the header says, for a list pane
287
+ /** The roster of a state: the rows in drawn order and what the sidebar's title says, for a list pane
287
288
  * `cols` wide. Only `items` and `index` depend on the width; `rows`, the instances in drawn
288
289
  * order, do not. `at` stamps a machine's panel before any roster outcome was taken, which
289
290
  * never shows; it is passed on. */
@@ -502,17 +503,39 @@ function detailOf(state, r, item, now, acts) {
502
503
  return { title: row.instance, facts };
503
504
  }
504
505
 
505
- /** The heading of the deployments in `~/Agents` that are not served yet: the TUI's own. */
506
+ /** The heading of the rows of this computer's deployments list that this run does not serve: the TUI's own. */
506
507
  export const OFFERED_SECTION = "On this machine, not opened";
507
- export const MORE_FOLDERS = "More folders than are listed here.";
508
+
509
+ /** The words of this computer's deployments list (awebai/oats#1390) where they are a line of their
510
+ * own: the add of the deployment the run started in, when it failed (the line under the sidebar's title,
511
+ * once; the kernel's message says what to do, and is shown as it came), and a change to the list
512
+ * still running as the TUI leaves. */
513
+ export const LIST_WORDS = Object.freeze({
514
+ notAdded: (message) => Object.freeze([{ own: "This deployment was not added to this computer's list: " }, { shown: message }]),
515
+ /** An add or a remove still running as the TUI leaves: one line, after the screen is left. */
516
+ leaving: "oats: a change to this computer's list of deployments is still running; `oats deployments` shows the list.",
517
+ });
518
+
519
+ /** What the switcher says above its rows, as views/switcher.mjs leadRows reads it. */
520
+ const leadOf = (state) => ({ said: state.switcher.line, failure: state.listed.failure?.message ?? null, removing: state.switcher.removing !== null });
521
+ /** How many rows stand above the switcher's choices in an area `cols` wide (the switcher's is the
522
+ * whole width): what happened (`line`), that the last read of the list failed, and a Remove
523
+ * asked, as views/switcher.mjs leadRows draws them. The window of the choices is that much
524
+ * shorter, so none is hidden for them. */
525
+ export function switcherLead(state, cols) {
526
+ return leadRows(leadOf(state), Number.isInteger(cols) && cols > 0 ? cols : 80, { ascii: state.ascii }).length;
527
+ }
508
528
 
509
529
  /** The switcher's rows for a state, top to bottom: the workspaces this run can show, as the
510
530
  * shared home lists and words them; then the ones matched to no workspace under the shared
511
- * heading; then the deployments of `~/Agents` that are not served, under the TUI's own.
512
- * An item is `{ heading, shared }`, `{ own }`, or a choice: `{ key, label, place, notLiveText,
513
- * open, primary }` for a view (`primary` is the deployment Enter opens) and `{ key, label, place,
514
- * path, refused }` for an offered folder. `keys` are the choices in order; `selected` is the
515
- * key the selection stands on (the first choice when the state's own is not listed). */
531
+ * heading; then the rows of this computer's deployments list that this run does not serve, in
532
+ * the kernel's order, under the TUI's own. A served deployment's id and a row's path are both
533
+ * canonical, so a deployment opened in this run is never offered again.
534
+ * An item is `{ heading, shared }`, or a choice: `{ key, label, place, notLiveText, open,
535
+ * primary }` for a view (`primary` is the deployment Enter opens) and `{ key, label, place,
536
+ * path, state, refused }` for a row of the list (`state` the kernel's: views/switcher.mjs says a
537
+ * stale one in words). `keys` are the choices in order; `selected` is the key the selection
538
+ * stands on (the first choice when the state's own is not listed). */
516
539
  export function switcher(state, at = new Date(0).toISOString()) {
517
540
  const held = heldOf(state, at), views = viewModel(held, TERMS);
518
541
  const rows = workspaceChoiceRows(workspaceChoices(held, TERMS, views));
@@ -524,17 +547,17 @@ export function switcher(state, at = new Date(0).toISOString()) {
524
547
  });
525
548
  const shown = rows.filter((row) => choiceMatches(row, query));
526
549
  const matched = shown.filter((row) => !row.unattached).map(choice), unmatched = shown.filter((row) => row.unattached).map(choice);
527
- const offered = state.offered.offered
528
- .map(({ path, name }) => ({ key: `path\u0000${path}`, label: name, place: shortPath(path, { home: state.home }), path, refused: state.switcher.refused === path }))
550
+ const unserved = state.listed.rows.filter((row) => !state.ctxs.includes(row.path));
551
+ const offered = unserved
552
+ .map(({ path, name, state: listedState }) => ({ key: `path\u0000${path}`, label: name, place: shortPath(path, { home: state.home }), path, state: listedState, refused: state.switcher.refused === path }))
529
553
  .filter((item) => choiceMatches(item, query));
530
554
  const items = [
531
555
  ...matched,
532
556
  ...(unmatched.length ? [{ heading: UNMATCHED_SECTION, shared: true }, ...unmatched] : []),
533
557
  ...(offered.length ? [{ heading: OFFERED_SECTION, shared: false }, ...offered] : []),
534
- ...(state.offered.limited ? [{ own: MORE_FOLDERS }] : []),
535
558
  ];
536
559
  const keys = items.filter((item) => item.key !== undefined).map((item) => item.key);
537
- const total = rows.length + state.offered.offered.length;
560
+ const total = rows.length + unserved.length;
538
561
  return {
539
562
  items, keys, selected: keys.includes(state.switcher.selected) ? state.switcher.selected : keys[0] ?? null,
540
563
  empty: keys.length ? null : total ? "nomatch" : "none",
@@ -632,19 +655,29 @@ function paletteView(state, page, at) {
632
655
  };
633
656
  }
634
657
 
658
+ /** The rows the switcher's window has in an area `body` rows tall and `cols` wide: the lines above
659
+ * the choices take theirs (switcherLead), and the filter field one while it is typed or kept
660
+ * (views/frame.mjs). */
661
+ export const switcherHeight = (state, body, cols) => Math.max(1, body - switcherLead(state, cols) - (state.switcher.editing || state.switcher.query ? 1 : 0));
662
+
635
663
  /** What the views draw for a state. For the Instances view, in a list pane `page` rows tall and
636
- * `cols` wide: the header's facts, the rows of the window with their marks, and the selected
637
- * instance's detail. For the switcher, in a pane `page` rows tall: the window of its rows. Only
638
- * the rows in the pane are worked out. */
639
- export function model(state, { page, now, at, cols }) {
664
+ * `cols` wide: the title's facts, the rows of the window with their marks, and the selected
665
+ * instance's detail; the Souls and the Capabilities views' lists in the same pane, also under the
666
+ * help, which leaves the sidebar beside it (views/frame.mjs). For the switcher, the palette and
667
+ * the spawn prompt, in an area `body` rows tall (`page` when none is given): the window of their
668
+ * rows; `area` is the main area's width (`cols` when none is given), which the lines above the
669
+ * switcher's choices wrap to (views/frame.mjs mainArea). Only the rows in the pane are worked out. */
670
+ export function model(state, { page, body = page, now, at, cols, area = cols }) {
640
671
  const r = roster(state, at, cols);
672
+ // The view under the help, or under a confirmation, decides what the sidebar says.
673
+ const under = state.view === "help" || state.view === "act" ? state.back : state.view;
641
674
  const common = {
642
675
  view: state.view, focus: state.focus, ascii: state.ascii, actions: state.actions,
643
676
  // The filter of the view shown: the Souls view has one of its own.
644
677
  filter: state.view === "souls" ? state.souls.filter : state.view === "capabilities" ? state.capabilities.filter : state.filter,
645
678
  workspace: r.workspace, machines: r.machines, here: r.here, machine: r.machine, counts: r.counts, readAt: r.readAt, notice: r.notice, note: r.note, empty: r.empty, observed: r.observed,
646
679
  detailTop: state.detailTop, helpTop: state.helpTop, open: state.open !== null,
647
- detachKey: state.detachKey, opening: state.opening, openable: false, actable: [],
680
+ detachKey: state.detachKey, opening: state.opening, openable: false,
648
681
  terminal: state.terminal, onTerminal: false,
649
682
  // The panel's groups (views/frame.mjs), the split and the focused group; the panel stands while
650
683
  // any tab is open. `tabs` is the focused group's strip: each tab in order, the shown one marked,
@@ -652,35 +685,35 @@ export function model(state, { page, now, at, cols }) {
652
685
  split: state.split, group: state.group, panelOpen: state.tabs.length > 0, groups: groupsOf(state),
653
686
  tabs: groupsOf(state)[state.group].tabs,
654
687
  act: state.view === "act" && state.act ? actView(state) : null,
655
- // The leader waits for its key (the footer is its hint), and the palette, while it is open.
656
- leader: state.leader?.waiting === true, palette: state.palette === null ? null : paletteView(state, page, at),
657
- souls: state.view === "souls" ? soulsView(state, page, at) : null,
658
- capabilities: state.view === "capabilities" ? capabilitiesView(state, page, at) : null,
659
- spawn: state.spawn === null ? null : spawnView(state, page, at),
660
- // The line above the panes: the last outcome, else a spawn under way (outcomeOf).
688
+ // The leader waits for its key (the cheat sheet is its hint), and the palette, while it is open.
689
+ leader: state.leader?.waiting === true, palette: state.palette === null ? null : paletteView(state, body, at),
690
+ souls: under === "souls" ? soulsView(state, page, at) : null,
691
+ capabilities: under === "capabilities" ? capabilitiesView(state, page, at) : null,
692
+ spawn: state.spawn === null ? null : spawnView(state, body, at),
693
+ // The line under the sidebar's title: the last outcome, else a spawn under way (outcomeOf).
661
694
  outcome: outcomeOf(state),
662
695
  };
663
- // The view under the help, or under a confirmation, decides what the header says.
664
- const under = state.view === "help" || state.view === "act" ? state.back : state.view;
665
696
  if (under === "switcher") {
666
697
  const s = switcher(state, at);
667
698
  const at_ = s.selected === null ? -1 : s.items.findIndex((item) => item.key === s.selected);
668
- // The line that says what happened to the open workspace stands above the rows and takes one
669
- // of the pane's: the window is that much shorter, so no choice is hidden for it.
670
- const win = windowOf({ top: state.switcher.top, count: s.items.length, height: Math.max(1, page - (state.switcher.line ? 1 : 0)), keep: state.switcher.loose ? -1 : at_ });
699
+ // The lines above the rows take the pane's rows, and so does the filter field while it is
700
+ // typed or kept: the window is that much shorter, so no choice is hidden for them (switcherHeight).
701
+ const win = windowOf({ top: state.switcher.top, count: s.items.length, height: switcherHeight(state, body, area), keep: state.switcher.loose ? -1 : at_ });
671
702
  return {
672
703
  ...common, under, list: [], above: 0, below: 0, wordWidth: 0, detail: null,
673
- // Nothing of a workspace stands in the header while the switcher is shown.
704
+ // Nothing of a workspace stands in the sidebar while the switcher is shown.
674
705
  workspace: "", machines: 0, here: false, machine: null, counts: [], readAt: null, notice: null, note: null, empty: null, observed: true, outcome: null,
675
706
  filter: Object.freeze({ editing: state.switcher.editing, query: state.switcher.query }),
676
707
  switcher: {
677
708
  rows: s.items.slice(win.top, win.top + win.size).map((item) => (item.key === undefined ? item : { ...item, selected: item.key === s.selected })),
678
- above: win.above, below: win.below, empty: s.empty, said: state.switcher.line,
709
+ above: win.above, below: win.below, empty: s.empty, ...leadOf(state),
710
+ // Whether the remove key acts on the selected row: a row of the list (the cheat sheet names it then).
711
+ removable: s.items.some((item) => item.key === s.selected && item.path !== undefined),
679
712
  },
680
713
  };
681
714
  }
682
715
  const selected = state.selected === null ? -1 : r.index.get(state.selected) ?? -1;
683
- // What the detail, the footer and Enter read of the selected row is worked out once per paint.
716
+ // What the detail and Enter read of the selected row is worked out once per paint.
684
717
  const row = selected >= 0 ? r.items[selected].row : null, acts = row ? instanceActs(row) : null;
685
718
  const decision = row ? openDecision(state, row, acts) : null;
686
719
  // The window holds the selection, unless the list was scrolled away from it on purpose.
@@ -693,10 +726,6 @@ export function model(state, { page, now, at, cols }) {
693
726
  // Enter opens the selected agent's terminal now, or (`onTerminal`) goes to the one open on it.
694
727
  openable: decision?.open === true && state.opening === null,
695
728
  onTerminal: row !== null && state.terminal !== null && state.terminal.id === instanceId(row),
696
- // The acts whose key opens a confirmation now, read from the same instanceActs answer: the
697
- // footer names them. A key not named still answers, with the line that says why. A secondary
698
- // act (Retire while a retire runs) opens on its key and is not named.
699
- actable: row && state.opening === null ? ACT_VERBS.filter((verb) => !acts.acts.some((each) => each.verb === verb && each.secondary) && actDecision(state, row, acts, verb).open) : [],
700
729
  switcher: null,
701
730
  };
702
731
  }
@@ -722,7 +751,7 @@ export function localDeployments(state, at) {
722
751
  return heldDeployments(held).filter((w) => !w.remote).map((w) => ({ id: w.id, remote: false, instances: rowsOf(held, w.id) }));
723
752
  }
724
753
 
725
- /** The four acts on an instance, in the order the help, the footer and the keys know them. */
754
+ /** The four acts on an instance, in the order the help, the palette and the keys know them. */
726
755
  export const ACT_VERBS = Object.freeze(["stop", "retire", "start", "restart"]);
727
756
  const DONE = Object.freeze({ stop: "stopped", retire: "retired", start: "started", restart: "restarted" });
728
757
  /** The TUI's own words around the acts (docs/tui.md, "Stopping, starting, restarting and
@@ -763,7 +792,7 @@ export function buttonLabel(offer, verb, phase) {
763
792
  export const BUTTON_ORDER = Object.freeze(["close", "refresh", "check-again", "apply"]);
764
793
 
765
794
  /** Whether an act key on `row` opens a confirmation, and what the line says when it does not.
766
- * `acts` is the row's instanceActs answer, read once per paint (the footer) or per key, as
795
+ * `acts` is the row's instanceActs answer, read once per paint (the palette) or per key, as
767
796
  * openDecision reads it; nothing here decides which acts a row has.
768
797
  * { open: true, verb, id, name, kind, machine, label, home } a confirmation opens: `kind`
769
798
  * "lifecycle" for stop and retire (the shared confirmation), "start" for the TUI's own
@@ -968,7 +997,8 @@ function soulsView(state, page, at) {
968
997
  // Nothing held: the first read is in flight (or the deployment not read yet), or it failed.
969
998
  return reason && !s.held.reading ? { ...base, state: "failed", failure: soulCatalogFailure(reason) } : { ...base, state: "reading" };
970
999
  }
971
- const heading = reason ? { label: "Souls", path: null, state: null, short: soulCatalogFailure(reason), readAt: clockTime(entry.observedAt) } : null;
1000
+ // A failed re-read's heading: the accordion's row above it names the view, so it has no word of its own.
1001
+ const heading = reason ? { label: "", path: null, state: null, short: soulCatalogFailure(reason), readAt: clockTime(entry.observedAt) } : null;
972
1002
  const state_ = !s.all.length ? "none" : !s.rows.length ? "nomatch" : "rows";
973
1003
  const height = Math.max(1, page - (heading ? 1 : 0));
974
1004
  const at_ = s.selected ? s.rows.indexOf(s.selected) : -1;
@@ -1080,7 +1110,7 @@ function capabilitiesView(state, page, at) {
1080
1110
  if (!c.local) return { ...base, state: "none" };
1081
1111
  const entry = c.held?.entry ?? null, reason = entry?.reason ?? null;
1082
1112
  if (!c.listed) return reason && !c.held.reading ? { ...base, state: "failed", failure: catalogFailure("capabilities", reason) } : { ...base, state: "reading" };
1083
- const heading = c.heading ? { label: "Capabilities", path: null, state: null, short: catalogFailure("capabilities", reason), readAt: clockTime(entry.observedAt) } : null;
1113
+ const heading = c.heading ? { label: "", path: null, state: null, short: catalogFailure("capabilities", reason), readAt: clockTime(entry.observedAt) } : null;
1084
1114
  const state_ = !c.all.length ? "none" : !c.keys.length ? "nomatch" : "rows";
1085
1115
  const at_ = c.items.findIndex((item) => item.key !== undefined && item.key === c.selected);
1086
1116
  const win = windowOf({ top: v.top, count: c.items.length, height: capabilitiesHeight(c, page), keep: v.loose ? -1 : at_ });
@@ -11,11 +11,11 @@
11
11
  // functions (client.mjs), which decide what a roster, a row and a failed read are, once, for both
12
12
  // clients: the TUI never writes "stopped" for a row and never builds the collector's input by hand.
13
13
  import { execFile as nodeExecFile, spawn as nodeSpawn } from "node:child_process";
14
- import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, opendirSync, readSync, realpathSync, rmdirSync, statSync, unlinkSync } from "node:fs";
14
+ import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, realpathSync, rmdirSync, statSync, unlinkSync } from "node:fs";
15
15
  import { tmpdir } from "node:os";
16
- import { basename, dirname, join } from "node:path";
16
+ import { dirname, join } from "node:path";
17
17
  import { fileURLToPath } from "node:url";
18
- import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, deploymentsInside, failedEntry, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
18
+ import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, failedEntry, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
19
19
 
20
20
  /** A path made canonical: what the shared start rule checks a local home with (session-start.mjs
21
21
  * verifiedLocalHome). Throws for a path that cannot be resolved; the rule answers that as no home. */
@@ -61,26 +61,13 @@ export function leaveInstance(env) {
61
61
  /** A step that must not stop the ones after it: a child, a stream or a directory that is already gone. */
62
62
  const quietly = (act) => { try { return act(); } catch { return undefined; } };
63
63
 
64
- /** The filesystem the three functions below read when they are given none. findDeployment: one
64
+ /** The filesystem the two functions below read when they are given none. findDeployment: one
65
65
  * realpath and one stat of the start, then one lstat per directory. A symbolic link named
66
- * oats-local.yaml is not a deployment's file (lstat does not follow it).
67
- * `list(dir, limit)` is the look inside a folder the shared deploymentsInside asks for:
68
- * -> { entries: [{ name, isDirectory }], limited }. It reads at most `limit` entries, and one more
69
- * only to say whether the folder holds more (`limited`), so a folder of any size costs a bounded
70
- * read. `isDirectory` is the entry's own type: a link to a directory is not a directory, and
71
- * nothing is followed. It throws for a folder that cannot be opened; the shared function answers
72
- * that as a folder that holds nothing. */
66
+ * oats-local.yaml is not a deployment's file (lstat does not follow it). */
73
67
  const DEPLOYMENT_IO = Object.freeze({
74
68
  realpath: (path) => realpathSync(path),
75
69
  isDirectory: (path) => statSync(path).isDirectory(),
76
70
  isDeployment: (dir) => lstatSync(join(dir, "oats-local.yaml")).isFile(),
77
- list: (dir, limit) => {
78
- const handle = opendirSync(dir), entries = [];
79
- try {
80
- for (let entry; entries.length < limit && (entry = handle.readSync());) entries.push({ name: entry.name, isDirectory: entry.isDirectory() });
81
- return { entries, limited: entries.length >= limit && handle.readSync() !== null };
82
- } finally { quietly(() => handle.closeSync()); }
83
- },
84
71
  });
85
72
 
86
73
  /** The deployment `start` is in: (start directory, io?) -> { ok: true, deployment } | { ok: false, dir }.
@@ -102,34 +89,9 @@ export function findDeployment(start, io = {}) {
102
89
  }
103
90
  }
104
91
 
105
- /** The deployments the switcher offers unasked: those directly inside `<home>/Agents` that this run
106
- * does not serve. (home, served, io?) -> { offered: [{ path, name }], limited }.
107
- * Which folders are deployments, their order and the limit of the look are the shared
108
- * deploymentsInside's; this adds only what a run knows. Each path is made canonical (io.realpath)
109
- * BEFORE it is compared with `served`, whose ids are canonical: a `~/Agents` reached through a
110
- * link would otherwise offer a deployment the run already shows. One that cannot be resolved (it
111
- * went away since the look) is left out, and so is a second folder that leads to the same place.
112
- * `name` is the folder's name as it was listed, `path` the canonical one to admit. `limited` says
113
- * the folder holds more entries than were read. Nothing is read from any deployment: an offered
114
- * one is read when it is picked. Never throws: a missing or unreadable `~/Agents` offers nothing. */
115
- export function offeredDeployments(home, served, io = {}) {
116
- try {
117
- const { realpath, isDeployment, list } = { ...DEPLOYMENT_IO, ...io };
118
- const inside = deploymentsInside(join(home, "Agents"), { list, isDeployment });
119
- const taken = new Set(served), offered = [];
120
- for (const listed of inside.paths) {
121
- const path = quietly(() => realpath(listed));
122
- if (typeof path !== "string" || taken.has(path)) continue;
123
- taken.add(path);
124
- offered.push({ path, name: basename(listed) });
125
- }
126
- return { offered, limited: inside.limited };
127
- } catch { return { offered: [], limited: false }; }
128
- }
129
-
130
92
  /** Whether `path` is a deployment NOW: (path, io?) -> { ok: true, deployment } | { ok: false }.
131
- * Asked when an offered deployment is picked: the offer is as old as the last look, and the
132
- * folder may have stopped being a deployment since. The path is made canonical (io.realpath) and
93
+ * Asked when a row of this computer's deployments list is picked: the row is as old as the last
94
+ * read of the list, and the folder may have stopped being a deployment since. The path is made canonical (io.realpath) and
133
95
  * the shared validateWorkspace is asked about that directory itself. Unlike findDeployment it
134
96
  * walks nowhere: a folder that is no longer a deployment must not open the one above it in its
135
97
  * place. `deployment` is the canonical path, the id a served deployment has. Never throws. */
@@ -167,6 +129,14 @@ export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = no
167
129
  });
168
130
  }
169
131
 
132
+ /** The exec of the one kernel call made before the terminal is taken but the probe: the read of
133
+ * this computer's deployments list at a start outside every deployment (the shared
134
+ * cliDeploymentList's `io.exec`). execFile's signature for `node <bin> <argv…>`, as the probe
135
+ * runs the kernel, and NOT detached, as the probe is not: a Ctrl+C then ends it with the TUI. */
136
+ export function startExec(bin, argv, options, callback) {
137
+ return nodeExecFile(process.execPath, [bin, ...argv], options, callback);
138
+ }
139
+
170
140
  /** Where a change's output goes (createReader `files`). `dir()` makes the run's private directory
171
141
  * (mkdtemp: mode 0700, under the OS temp dir); `open` makes one file in it for the child alone
172
142
  * (0600, refused if it is there); `read(path, max)` reads back at most `max` bytes and one more,