@gadicc/loom 2.4.0 → 2.5.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.
@@ -0,0 +1,215 @@
1
+ /**
2
+ * Host access for machine-wide CPU slots (docs/machine-slots.md): the pool
3
+ * directory, safe opens of its files, and the `/proc` reads that labels
4
+ * and tickets rely on. Linux only; callers decide what other platforms do.
5
+ */
6
+ import { constants, fstatSync, lstatSync, mkdirSync, openSync } from "node:fs";
7
+ import { closeSync, readFileSync } from "node:fs";
8
+ import { join } from "node:path";
9
+ import process from "node:process";
10
+
11
+ /** Where the per-user pool lives, and why it is or is not usable. */
12
+ export type SlotDirectory =
13
+ | { status: "ready"; path: string }
14
+ | { status: "unavailable"; reason: string };
15
+
16
+ /** Checks one directory level Loom owns: real, ours, private to us. */
17
+ function checkLevel(path: string, uid: number, create: boolean) {
18
+ if (create) {
19
+ try {
20
+ mkdirSync(path, { mode: 0o700 });
21
+ } catch (error) {
22
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
23
+ }
24
+ }
25
+ const info = lstatSync(path);
26
+ if (!info.isDirectory()) return `${path} is not a real directory`;
27
+ if (info.uid !== uid) return `${path} belongs to another user`;
28
+ if ((info.mode & 0o022) !== 0) return `${path} is writable by other users`;
29
+ return null;
30
+ }
31
+
32
+ /**
33
+ * Resolves the pool directory: `/run/user/<uid>/loom/slots` when that runtime
34
+ * directory exists and is this user's (whatever `XDG_RUNTIME_DIR` says, so a
35
+ * scrubbed environment cannot split the pool), else `/tmp/loom-<uid>/slots`.
36
+ * `LOOM_SLOTS_DIR` overrides it for tests. Every level Loom creates is made
37
+ * mode 0700 and must be a real directory, owned by this user and writable by
38
+ * no one else; otherwise there is no pool.
39
+ */
40
+ export function resolveSlotDirectory(
41
+ env: Readonly<Record<string, string | undefined>> = process.env,
42
+ uid: number | undefined = process.getuid?.(),
43
+ ): SlotDirectory {
44
+ if (uid === undefined) {
45
+ return { status: "unavailable", reason: "no POSIX user identity" };
46
+ }
47
+ try {
48
+ if (env.LOOM_SLOTS_DIR) {
49
+ const problem = checkLevel(env.LOOM_SLOTS_DIR, uid, true);
50
+ return problem
51
+ ? { status: "unavailable", reason: problem }
52
+ : { status: "ready", path: env.LOOM_SLOTS_DIR };
53
+ }
54
+ const runtime = `/run/user/${uid}`;
55
+ let base: string;
56
+ let levels: string[];
57
+ if (checkLevelIfPresent(runtime, uid)) {
58
+ base = join(runtime, "loom");
59
+ levels = [base, join(base, "slots")];
60
+ } else {
61
+ base = join("/tmp", `loom-${uid}`);
62
+ levels = [base, join(base, "slots")];
63
+ }
64
+ for (const level of levels) {
65
+ const problem = checkLevel(level, uid, true);
66
+ if (problem) return { status: "unavailable", reason: problem };
67
+ }
68
+ return { status: "ready", path: levels[levels.length - 1] };
69
+ } catch (error) {
70
+ return {
71
+ status: "unavailable",
72
+ reason: error instanceof Error ? error.message : String(error),
73
+ };
74
+ }
75
+ }
76
+
77
+ function checkLevelIfPresent(path: string, uid: number): boolean {
78
+ try {
79
+ return checkLevel(path, uid, false) === null;
80
+ } catch {
81
+ return false;
82
+ }
83
+ }
84
+
85
+ /**
86
+ * Opens a pool file without following a symlink and without truncating it,
87
+ * creating it (mode 0600) unless `existingOnly`. The open file must be a
88
+ * regular file owned by this user with exactly one link; anything else is
89
+ * closed and refused, so a planted link can never be written through.
90
+ * Returns null when `existingOnly` and the file is gone.
91
+ */
92
+ export function openPoolFile(
93
+ path: string,
94
+ options: { existingOnly?: boolean; exclusive?: boolean } = {},
95
+ uid: number | undefined = process.getuid?.(),
96
+ ): number | null {
97
+ const flags =
98
+ constants.O_RDWR |
99
+ constants.O_NOFOLLOW |
100
+ (options.existingOnly ? 0 : constants.O_CREAT) |
101
+ (options.exclusive ? constants.O_EXCL : 0);
102
+ // Not every runtime honours O_NOFOLLOW (Deno's node:fs ignores it), so the
103
+ // path is also checked before the open and matched to the descriptor after.
104
+ let before: ReturnType<typeof lstatSync> | undefined;
105
+ try {
106
+ before = lstatSync(path);
107
+ } catch (error) {
108
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
109
+ if (options.existingOnly) return null;
110
+ }
111
+ if (before && !before.isFile())
112
+ throw new Error(`${path} is not a private regular file`);
113
+ let fd: number;
114
+ try {
115
+ fd = openSync(path, flags, 0o600);
116
+ } catch (error) {
117
+ if (
118
+ options.existingOnly &&
119
+ (error as NodeJS.ErrnoException).code === "ENOENT"
120
+ )
121
+ return null;
122
+ throw error;
123
+ }
124
+ const info = fstatSync(fd);
125
+ let after: ReturnType<typeof lstatSync> | undefined;
126
+ try {
127
+ after = lstatSync(path);
128
+ } catch {
129
+ after = undefined;
130
+ }
131
+ if (
132
+ !info.isFile() ||
133
+ info.uid !== uid ||
134
+ info.nlink !== 1 ||
135
+ !after?.isFile() ||
136
+ after.ino !== info.ino ||
137
+ after.dev !== info.dev
138
+ ) {
139
+ closeSync(fd);
140
+ throw new Error(`${path} is not a private regular file`);
141
+ }
142
+ return fd;
143
+ }
144
+
145
+ /** A process's scheduler state and start time, from `/proc/<pid>/stat`. */
146
+ export interface ProcessStat {
147
+ /** Single-letter state; `T` and `t` are stopped. */
148
+ state: string;
149
+ /** Start time in clock ticks since boot; with the pid, a unique identity. */
150
+ start: string;
151
+ /** Parent pid. */
152
+ ppid: number;
153
+ }
154
+
155
+ /** Parses `/proc/<pid>/stat`, whose command name may hold spaces and parentheses. */
156
+ export function parseProcessStat(text: string): ProcessStat | null {
157
+ const close = text.lastIndexOf(")");
158
+ if (close < 0) return null;
159
+ const fields = text
160
+ .slice(close + 1)
161
+ .trim()
162
+ .split(/\s+/);
163
+ // Field 3 (state) is the first after the name; field 22 (starttime) the 20th.
164
+ if (
165
+ fields.length < 20 ||
166
+ !/^\d+$/.test(fields[19]) ||
167
+ !/^\d+$/.test(fields[1])
168
+ )
169
+ return null;
170
+ return { state: fields[0], start: fields[19], ppid: Number(fields[1]) };
171
+ }
172
+
173
+ /** Reads a live process's stat, or null when it no longer exists. */
174
+ export function readProcessStat(pid: number): ProcessStat | null {
175
+ try {
176
+ return parseProcessStat(readFileSync(`/proc/${pid}/stat`, "utf8"));
177
+ } catch {
178
+ return null;
179
+ }
180
+ }
181
+
182
+ /**
183
+ * This process's ancestors as `pid:start` keys, walking `/proc` parent links,
184
+ * so a holder can be recognised as an ancestor even when the environment
185
+ * that named its grant was scrubbed on the way down.
186
+ */
187
+ export function ancestorKeys(
188
+ pid: number = process.pid,
189
+ stat: (pid: number) => ProcessStat | null = readProcessStat,
190
+ ): Set<string> {
191
+ const keys = new Set<string>();
192
+ let current = stat(pid)?.ppid ?? 0;
193
+ for (let depth = 0; current > 1 && depth < 256; depth++) {
194
+ const info = stat(current);
195
+ if (!info) break;
196
+ keys.add(`${current}:${info.start}`);
197
+ current = info.ppid;
198
+ }
199
+ return keys;
200
+ }
201
+
202
+ /** Reads the hybrid core types Linux reports, as performance and efficiency CPU lists. */
203
+ export function readCoreTypes(
204
+ read: (path: string) => string | undefined = (path) => {
205
+ try {
206
+ return readFileSync(path, "utf8");
207
+ } catch {
208
+ return undefined;
209
+ }
210
+ },
211
+ ): string[] {
212
+ return ["/sys/devices/cpu_core/cpus", "/sys/devices/cpu_atom/cpus"]
213
+ .map((path) => read(path)?.trim())
214
+ .filter((text): text is string => Boolean(text));
215
+ }
@@ -47,6 +47,7 @@ import {
47
47
  writeGeneratedActivation,
48
48
  type GeneratedActivation,
49
49
  } from "./generatedWorkflow.ts";
50
+ import { runSlotsCommand } from "./machineSlotsCommand.ts";
50
51
  import {
51
52
  beginGeneratedDev,
52
53
  assertGeneratedDevTransition,
@@ -23787,6 +23788,15 @@ function printHelp({ out }: CliOutput) {
23787
23788
  out(
23788
23789
  " test resources doctor Inspect local/CI resource limits without changing policy (--json, --test-profile local|ci).",
23789
23790
  );
23791
+ out(
23792
+ " slots run [--min n] [--max n] [--label text] -- <command> Wait for CPUs from the machine-wide pool, then run pinned to them (--wait-timeout minutes, --allow-unpooled, --quiet).",
23793
+ );
23794
+ out(
23795
+ " slots pin -- <command> Run a light command on the pool's CPUs, off the reserved cores, without waiting.",
23796
+ );
23797
+ out(
23798
+ " slots status Show the machine-wide CPU pool, its holders and waiters (--json).",
23799
+ );
23790
23800
  out(
23791
23801
  " init Set up package/Deno config, loom.json, managed AGENTS.md guidance, first-party links, and package skills.",
23792
23802
  );
@@ -26637,6 +26647,12 @@ export async function runCli(
26637
26647
  json: { type: "boolean" },
26638
26648
  "test-profile": { type: "string" },
26639
26649
  "cpu-mode": { type: "string" },
26650
+ min: { type: "string" },
26651
+ max: { type: "string" },
26652
+ label: { type: "string" },
26653
+ "wait-timeout": { type: "string" },
26654
+ "allow-unpooled": { type: "boolean" },
26655
+ quiet: { type: "boolean" },
26640
26656
  workers: { type: "string" },
26641
26657
  "quiet-test-resources": { type: "boolean" },
26642
26658
  "dry-run": { type: "boolean" },
@@ -26686,11 +26702,25 @@ export async function runCli(
26686
26702
  const resourceRun = command === "test" && arg1 === "run";
26687
26703
  const resourceDoctor =
26688
26704
  command === "test" && arg1 === "resources" && arg2 === "doctor";
26705
+ const slotsCommand = command === "slots";
26706
+ // Slot flags belong to `loom slots`; per-subcommand checks are its own.
26707
+ if (
26708
+ !slotsCommand &&
26709
+ (parsed.values.min !== undefined ||
26710
+ parsed.values.max !== undefined ||
26711
+ parsed.values.label !== undefined ||
26712
+ parsed.values["wait-timeout"] !== undefined ||
26713
+ parsed.values["allow-unpooled"] ||
26714
+ parsed.values.quiet)
26715
+ ) {
26716
+ io.err("Slot flags apply only to loom slots; no command ran.");
26717
+ return 120;
26718
+ }
26689
26719
  // A generic dry-run flag must never be silently ignored by another command
26690
26720
  // that could provision resources. Refuse before automatic local-dev sync.
26691
26721
  if (
26692
26722
  (parsed.values["dry-run"] && !resourceRun) ||
26693
- (parsed.values.json && !resourceDoctor) ||
26723
+ (parsed.values.json && !resourceDoctor && !slotsCommand) ||
26694
26724
  (!resourceRun &&
26695
26725
  (parsed.values.workers !== undefined ||
26696
26726
  parsed.values["cpu-mode"] !== undefined ||
@@ -26725,6 +26755,8 @@ export async function runCli(
26725
26755
  command !== "status" &&
26726
26756
  !addListOnly &&
26727
26757
  !testResourceDoctor &&
26758
+ // The machine pool is not a project's: no package sync, in any directory.
26759
+ command !== "slots" &&
26728
26760
  !(command === "test" && arg1 === "run" && parsed.values["dry-run"]) &&
26729
26761
  !productionCheck &&
26730
26762
  !parsed.values["no-sync"]
@@ -26885,6 +26917,26 @@ export async function runCli(
26885
26917
  { profile: parsed.values["test-profile"], json: parsed.values.json },
26886
26918
  io,
26887
26919
  );
26920
+ case "slots":
26921
+ if (arg1 !== "status" && !args.includes("--")) {
26922
+ io.err("Use -- before the command to run.");
26923
+ return 120;
26924
+ }
26925
+ return await runSlotsCommand(
26926
+ cwd,
26927
+ arg1,
26928
+ arg1 === "status" ? [] : args.slice(args.indexOf("--") + 1),
26929
+ {
26930
+ min: parsed.values.min,
26931
+ max: parsed.values.max,
26932
+ label: parsed.values.label,
26933
+ waitTimeout: parsed.values["wait-timeout"],
26934
+ allowUnpooled: parsed.values["allow-unpooled"],
26935
+ quiet: parsed.values.quiet,
26936
+ json: parsed.values.json,
26937
+ },
26938
+ io,
26939
+ );
26888
26940
  case "env":
26889
26941
  return await runEnvCommand(
26890
26942
  cwd,
@@ -24,6 +24,7 @@ export function planManagedTest(
24
24
  report: TestResourceReport,
25
25
  workers: string | undefined,
26
26
  cpuMode = "inherit",
27
+ slotGrant?: string,
27
28
  ): ManagedTestPlan {
28
29
  if (
29
30
  (report.profile === "local" && !workers) ||
@@ -92,10 +93,16 @@ export function planManagedTest(
92
93
  "Local memory headroom is unavailable or below the desktop floor (exit 121)",
93
94
  );
94
95
  }
96
+ // Inside a machine-slots grant (docs/machine-slots.md) the grant is the
97
+ // capacity; pinning already narrows the inherited CPUs to it.
98
+ const slots = /^\d+$/.test(slotGrant ?? "") ? Number(slotGrant) : 0;
99
+ if (report.profile === "local" && slots >= 1)
100
+ ceiling = Math.min(ceiling, slots);
95
101
  return { workers: ceiling, cpus, epoch: selection?.epoch ?? null, warnings };
96
102
  }
97
103
 
98
- async function executable(name: string): Promise<string> {
104
+ /** Finds an executable on PATH, or throws naming it. */
105
+ export async function executable(name: string): Promise<string> {
99
106
  for (const directory of (process.env.PATH ?? "").split(delimiter)) {
100
107
  if (!directory) continue;
101
108
  const path = join(
@@ -112,10 +119,34 @@ async function executable(name: string): Promise<string> {
112
119
  throw new Error(`Required executable ${name} is unavailable`);
113
120
  }
114
121
 
115
- function launch(
122
+ /** How {@link launch} runs a command beyond its name, arguments and cwd. */
123
+ export interface LaunchOptions {
124
+ /** The child's environment; defaults to this process's. */
125
+ env?: NodeJS.ProcessEnv;
126
+ /**
127
+ * After the child exits, how long to wait for the rest of its own process
128
+ * group (non-terminal runs only) before returning; 0 does not wait.
129
+ */
130
+ groupGraceMs?: number;
131
+ /** Label for launcher errors on stderr. */
132
+ name?: string;
133
+ /**
134
+ * In a terminal, outlive the job's own Ctrl-C and Ctrl-\: the terminal
135
+ * delivers them to the job, and this process returns only when it exits.
136
+ */
137
+ holdInterrupts?: boolean;
138
+ }
139
+
140
+ /**
141
+ * Runs a command to completion with the launcher's signal rules: without a
142
+ * terminal the child leads its own process group and signals go to the whole
143
+ * group; with one, the terminal's job control already reaches it.
144
+ */
145
+ export function launch(
116
146
  command: string,
117
147
  args: string[],
118
148
  cwd: string,
149
+ options: LaunchOptions = {},
119
150
  ): Promise<{ code: number; signal?: NodeJS.Signals }> {
120
151
  return new Promise((done) => {
121
152
  const foreground =
@@ -126,7 +157,7 @@ function launch(
126
157
  const grouped = process.platform !== "win32" && !foreground;
127
158
  const child = spawn(command, args, {
128
159
  cwd,
129
- env: process.env,
160
+ env: options.env ?? process.env,
130
161
  stdio: "inherit",
131
162
  detached: grouped,
132
163
  });
@@ -134,6 +165,11 @@ function launch(
134
165
  const signals: NodeJS.Signals[] = foreground
135
166
  ? ["SIGTERM", "SIGHUP"]
136
167
  : ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
168
+ // The terminal already sent these to the job; only wait for it.
169
+ const held: NodeJS.Signals[] =
170
+ foreground && options.holdInterrupts ? ["SIGINT", "SIGQUIT"] : [];
171
+ const ignore = () => {};
172
+ for (const signal of held) process.on(signal, ignore);
137
173
  let receivedSignal: NodeJS.Signals | undefined;
138
174
  const handlers = signals.map((signal) => {
139
175
  const handler = () => {
@@ -156,23 +192,44 @@ function launch(
156
192
  if (settled) return;
157
193
  settled = true;
158
194
  for (const item of handlers) process.off(item.signal, item.handler);
195
+ for (const signal of held) process.off(signal, ignore);
159
196
  done(value);
160
197
  };
161
198
  child.once("error", (error) => {
162
- console.error(`Loom test launcher: ${error.message}`);
199
+ console.error(
200
+ `${options.name ?? "Loom test launcher"}: ${error.message}`,
201
+ );
163
202
  finish({ code: 120 });
164
203
  });
165
- child.once("close", (code, signal) =>
166
- finish({
204
+ child.once("close", (code, signal) => {
205
+ const result = {
167
206
  code: code ?? 1,
168
207
  ...((receivedSignal ?? signal)
169
208
  ? { signal: receivedSignal ?? signal ?? undefined }
170
209
  : {}),
171
- }),
172
- );
210
+ };
211
+ if (grouped && child.pid && options.groupGraceMs)
212
+ void groupEmpty(child.pid, options.groupGraceMs).then(() =>
213
+ finish(result),
214
+ );
215
+ else finish(result);
216
+ });
173
217
  });
174
218
  }
175
219
 
220
+ /** Waits until no process is left in a group, or the grace runs out. */
221
+ async function groupEmpty(pgid: number, graceMs: number): Promise<void> {
222
+ const until = Date.now() + graceMs;
223
+ while (Date.now() < until) {
224
+ try {
225
+ process.kill(-pgid, 0);
226
+ } catch {
227
+ return;
228
+ }
229
+ await new Promise((resolve) => setTimeout(resolve, 100));
230
+ }
231
+ }
232
+
176
233
  /** Run only the verified finite Vitest adapter; all resource diagnostics use stderr. */
177
234
  export async function runManagedTestCommand(
178
235
  cwd: string,
@@ -206,7 +263,12 @@ export async function runManagedTestCommand(
206
263
  let taskset: string | undefined;
207
264
  try {
208
265
  report = await inspectTestResources({ profile: options.profile });
209
- plan = planManagedTest(report, options.workers, options.cpuMode);
266
+ plan = planManagedTest(
267
+ report,
268
+ options.workers,
269
+ options.cpuMode,
270
+ process.env.LOOM_SLOTS,
271
+ );
210
272
  node = await executable("node");
211
273
  if (plan.cpus) taskset = await executable("taskset");
212
274
  } catch (error) {