@capybara-hq/device 0.1.0-rc.10 → 0.1.0-rc.12

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 (45) hide show
  1. package/README.md +51 -27
  2. package/dist/cli.d.ts +13 -2
  3. package/dist/cli.js +25 -4
  4. package/dist/client.d.ts +11 -3
  5. package/dist/client.js +18 -8
  6. package/dist/commands/drain.d.ts +3 -3
  7. package/dist/commands/drain.js +5 -4
  8. package/dist/commands/login.d.ts +3 -0
  9. package/dist/commands/login.js +33 -5
  10. package/dist/commands/logout.d.ts +2 -0
  11. package/dist/commands/logout.js +1 -1
  12. package/dist/commands/mode.d.ts +23 -6
  13. package/dist/commands/mode.js +24 -3
  14. package/dist/commands/service.d.ts +11 -4
  15. package/dist/commands/service.js +122 -65
  16. package/dist/commands/signal.d.ts +6 -2
  17. package/dist/commands/signal.js +7 -4
  18. package/dist/commands/start.d.ts +4 -0
  19. package/dist/commands/start.js +12 -5
  20. package/dist/commands/stop.d.ts +18 -7
  21. package/dist/commands/stop.js +20 -8
  22. package/dist/exec/docker.d.ts +24 -2
  23. package/dist/exec/docker.js +176 -2
  24. package/dist/exec/fs-helper.d.ts +7 -3
  25. package/dist/exec/fs-helper.js +70 -2
  26. package/dist/exec/host.d.ts +9 -1
  27. package/dist/exec/host.js +20 -0
  28. package/dist/exec/listing.d.ts +35 -0
  29. package/dist/exec/listing.js +157 -0
  30. package/dist/exec/os.d.ts +14 -2
  31. package/dist/exec/os.js +59 -13
  32. package/dist/exec/switch.d.ts +20 -4
  33. package/dist/exec/switch.js +39 -4
  34. package/dist/exec/types.d.ts +13 -1
  35. package/dist/pid.d.ts +33 -4
  36. package/dist/pid.js +91 -35
  37. package/dist/server-ops.d.ts +6 -4
  38. package/dist/server-ops.js +90 -17
  39. package/dist/service/launchd.d.ts +9 -6
  40. package/dist/service/launchd.js +22 -7
  41. package/dist/service/manager.d.ts +41 -0
  42. package/dist/service/manager.js +91 -0
  43. package/dist/service/systemd.d.ts +2 -0
  44. package/dist/service/systemd.js +8 -0
  45. package/package.json +2 -2
@@ -1,14 +1,11 @@
1
- import { execFileSync } from "node:child_process";
2
1
  import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
3
- import { dirname } from "node:path";
2
+ import { dirname, join } from "node:path";
4
3
  import { fileURLToPath } from "node:url";
5
4
  import { readRunning } from "../pid.js";
6
- import { LAUNCHD_LABEL, plistContent, plistPath } from "../service/launchd.js";
5
+ import { hasLoginService } from "../service/installed.js";
6
+ import { plistContent, plistPath } from "../service/launchd.js";
7
+ import { defaultRunSystem, launchdTarget, managerState, packageVersionAt, serviceBinPath, } from "../service/manager.js";
7
8
  import { SYSTEMD_UNIT, unitContent, unitPath } from "../service/systemd.js";
8
- import { PROGRAM_VERSION } from "../version.js";
9
- function defaultRun(cmd, args) {
10
- execFileSync(cmd, args, { stdio: "pipe" });
11
- }
12
9
  /** The bin script next to this package's `dist` (or `src`) directory. */
13
10
  function defaultBinPath() {
14
11
  return fileURLToPath(new URL("../../bin/capybara-device.mjs", import.meta.url));
@@ -27,6 +24,8 @@ export function serviceEnv(env) {
27
24
  export const SERVICE_POLL_MS = 200;
28
25
  /** How long install / uninstall wait for `launchctl bootout` to finish (it is asynchronous). */
29
26
  export const SERVICE_GONE_TIMEOUT_MS = 10_000;
27
+ /** How long `service start|restart` wait for the program to be running. */
28
+ export const SERVICE_UP_TIMEOUT_MS = 10_000;
30
29
  /** The waits before each retry of a `launchctl bootstrap` that failed with error 5. */
31
30
  export const BOOTSTRAP_BACKOFF_MS = [500, 1000, 2000];
32
31
  /**
@@ -34,7 +33,7 @@ export const BOOTSTRAP_BACKOFF_MS = [500, 1000, 2000];
34
33
  * (systemd user), removes it, or reports whether it is loaded and running.
35
34
  */
36
35
  export async function serviceCommand(action, deps) {
37
- const run = deps.run ?? defaultRun;
36
+ const run = deps.run ?? defaultRunSystem;
38
37
  const spec = {
39
38
  nodePath: deps.nodePath ?? process.execPath,
40
39
  binPath: deps.binPath ?? defaultBinPath(),
@@ -45,7 +44,7 @@ export async function serviceCommand(action, deps) {
45
44
  if (deps.platform === "darwin")
46
45
  return await launchd(action, spec, deps, run);
47
46
  if (deps.platform === "linux")
48
- return systemd(action, spec, deps, run);
47
+ return await systemd(action, spec, deps, run);
49
48
  }
50
49
  catch (e) {
51
50
  deps.err(`capybara-device service ${action} failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -67,30 +66,85 @@ function failureText(e) {
67
66
  function isBootstrapIoError(e) {
68
67
  return e.status === 5 || /Bootstrap failed: 5:/.test(failureText(e));
69
68
  }
69
+ /** The pid file's program, checked to be this program (never trusted on the file alone). */
70
+ function running(deps) {
71
+ return readRunning(deps.stateDir, {
72
+ ...(deps.kill && { kill: deps.kill }),
73
+ ...(deps.ps && { ps: deps.ps }),
74
+ });
75
+ }
76
+ function where(deps) {
77
+ return {
78
+ home: deps.home,
79
+ platform: deps.platform,
80
+ ...(deps.uid !== undefined && { uid: deps.uid }),
81
+ };
82
+ }
83
+ const NOT_INSTALLED = "capybara-device service is not installed. Install it: capybara-device service install";
70
84
  /**
71
- * One status report: installed? running (and at which version)? When the running program is older
72
- * than the installed package, a stale daemon after an upgrade — a restart makes it current.
85
+ * One status report, in four shapes: not installed; installed but not loaded; loaded but the
86
+ * program is not running (it exited: the reason is in service.log); running, with its pid and
87
+ * version, plus a restart line when the package the service file runs is a different version (a
88
+ * stale daemon after an upgrade). Exit code 0 only when running.
73
89
  */
74
- function reportStatus(deps, state, installedVersion) {
75
- if (!state.installed) {
76
- deps.out("capybara-device service is not installed. Install it: capybara-device service install");
90
+ function reportStatus(deps, run) {
91
+ const at = where(deps);
92
+ if (!hasLoginService(at.home, at.platform)) {
93
+ deps.out(NOT_INSTALLED);
94
+ return 1;
95
+ }
96
+ const state = managerState(at, run);
97
+ if (!state.loaded) {
98
+ deps.out("capybara-device service is installed but not loaded. Start it: capybara-device service start");
77
99
  return 1;
78
100
  }
79
- const running = readRunning(deps.stateDir);
80
- if (running === undefined || !state.loaded) {
81
- deps.out("capybara-device service is installed, but nothing is running. Start it: capybara-device service start");
101
+ if (state.pid === undefined) {
102
+ deps.out("capybara-device service is loaded, but the program is not running: it exited. The reason " +
103
+ `is at the end of ${join(deps.stateDir, "service.log")}; once it is fixed: ` +
104
+ "capybara-device service restart");
82
105
  return 1;
83
106
  }
84
- deps.out(`capybara-device service is loaded; running (pid ${running.pid}, ${running.version ?? "version unknown"}).`);
85
- if (running.version !== installedVersion) {
86
- deps.out(`installed ${installedVersion} — restart it: capybara-device service restart`);
107
+ const program = running(deps);
108
+ const version = program?.pid === state.pid ? program.version : undefined;
109
+ deps.out(`capybara-device service is loaded; running (pid ${state.pid}, ${version ?? "version unknown"}).`);
110
+ const bin = serviceBinPath(at);
111
+ const installed = bin === undefined ? undefined : packageVersionAt(bin);
112
+ if (installed !== undefined && version !== installed) {
113
+ deps.out(`installed ${installed} — restart it: capybara-device service restart`);
87
114
  }
88
115
  return 0;
89
116
  }
117
+ /**
118
+ * Refuses to start the service while a program started outside it runs (`capybara-device start`
119
+ * in a terminal): two programs would fight over the one connection of this device.
120
+ */
121
+ function foregroundRunning(deps, state) {
122
+ const program = running(deps);
123
+ if (program === undefined || program.pid === state.pid)
124
+ return false;
125
+ deps.err(`capybara-device is already running outside the service (pid ${program.pid}). Stop it first: capybara-device stop`);
126
+ return true;
127
+ }
128
+ /** Waits until the service manager runs the program (a pid other than `previous`). */
129
+ async function cameUp(deps, run, sleep, previous) {
130
+ for (let waited = 0;; waited += SERVICE_POLL_MS) {
131
+ const pid = managerState(where(deps), run).pid;
132
+ if (pid !== undefined && pid !== previous)
133
+ return true;
134
+ if (waited >= SERVICE_UP_TIMEOUT_MS)
135
+ return false;
136
+ await sleep(SERVICE_POLL_MS);
137
+ }
138
+ }
139
+ /** The failure of a start or restart whose program is not running afterwards. */
140
+ function didNotComeBack(deps, action) {
141
+ deps.err(`capybara-device service ${action} failed: the program is not running. The reason is at the ` +
142
+ `end of ${join(deps.stateDir, "service.log")}.`);
143
+ return 1;
144
+ }
90
145
  async function launchd(action, spec, deps, run) {
91
146
  const file = plistPath(deps.home);
92
- const domain = `gui/${deps.uid ?? process.getuid?.() ?? 501}`;
93
- const service = `${domain}/${LAUNCHD_LABEL}`;
147
+ const { domain, service } = launchdTarget(deps.uid);
94
148
  const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
95
149
  const tryRun = (args) => {
96
150
  try {
@@ -101,15 +155,7 @@ async function launchd(action, spec, deps, run) {
101
155
  }
102
156
  };
103
157
  /** Whether launchd still knows the service (`launchctl print` fails once it is gone). */
104
- const loaded = () => {
105
- try {
106
- run("launchctl", ["print", service]);
107
- return true;
108
- }
109
- catch {
110
- return false;
111
- }
112
- };
158
+ const loaded = () => managerState(where(deps), run).loaded;
113
159
  /** Boots the service out and waits until launchd has let it go (bootout returns before that). */
114
160
  const bootout = async () => {
115
161
  tryRun(["bootout", service]);
@@ -142,27 +188,31 @@ async function launchd(action, spec, deps, run) {
142
188
  }
143
189
  }
144
190
  };
145
- const installed = () => existsSync(file);
146
- if (action === "status") {
147
- return reportStatus(deps, { installed: installed(), loaded: loaded() }, PROGRAM_VERSION);
148
- }
191
+ const installed = () => hasLoginService(deps.home, "darwin");
192
+ if (action === "status")
193
+ return reportStatus(deps, run);
149
194
  if (action === "start" || action === "restart") {
150
195
  if (!installed()) {
151
- deps.err("capybara-device service is not installed. Install it: capybara-device service install");
196
+ deps.err(NOT_INSTALLED);
152
197
  return 1;
153
198
  }
154
- if (action === "start" && loaded()) {
199
+ const state = managerState(where(deps), run);
200
+ if (action === "start" && state.pid !== undefined) {
155
201
  deps.out("The capybara-device login service is already running.");
156
202
  return 0;
157
203
  }
158
- if (action === "restart" && loaded()) {
159
- // Reloads the program from the plist's bin, so a newer package takes effect.
160
- tryRun(["kickstart", "-k", service]);
161
- deps.out("Restarted the capybara-device login service.");
162
- return 0;
204
+ if (foregroundRunning(deps, state))
205
+ return 1;
206
+ if (state.loaded) {
207
+ // Loaded: run the program again from the plist's bin (a newer package takes effect); a
208
+ // loaded service whose program exited is started without a kill.
209
+ run("launchctl", state.pid === undefined ? ["kickstart", service] : ["kickstart", "-k", service]);
163
210
  }
164
- if (!(await bootstrap()))
211
+ else if (!(await bootstrap())) {
165
212
  return 1;
213
+ }
214
+ if (!(await cameUp(deps, run, sleep, state.pid)))
215
+ return didNotComeBack(deps, action);
166
216
  deps.out(action === "restart"
167
217
  ? "Restarted the capybara-device login service."
168
218
  : "Started the capybara-device login service.");
@@ -170,15 +220,19 @@ async function launchd(action, spec, deps, run) {
170
220
  }
171
221
  if (action === "stop") {
172
222
  if (!installed()) {
173
- deps.err("capybara-device service is not installed. Install it: capybara-device service install");
223
+ deps.err(NOT_INSTALLED);
174
224
  return 1;
175
225
  }
176
226
  if (!loaded()) {
177
227
  deps.out("The capybara-device login service is not running.");
178
228
  return 0;
179
229
  }
180
- // Unload, never a signal: KeepAlive would start a signalled program straight back up.
230
+ // Unload, never a signal: KeepAlive would start a program that exits non-zero straight back.
181
231
  await bootout();
232
+ if (loaded()) {
233
+ deps.err(`capybara-device service stop failed: launchd still has the service loaded. Check with: launchctl print ${service}`);
234
+ return 1;
235
+ }
182
236
  deps.out("Stopped the capybara-device login service; running commands ended. It starts again at the next login or with: capybara-device service start");
183
237
  return 0;
184
238
  }
@@ -198,40 +252,43 @@ async function launchd(action, spec, deps, run) {
198
252
  deps.out("Removed the capybara-device login service.");
199
253
  return 0;
200
254
  }
201
- function systemd(action, spec, deps, run) {
255
+ async function systemd(action, spec, deps, run) {
202
256
  const file = unitPath(deps.home);
203
- const active = () => {
204
- try {
205
- run("systemctl", ["--user", "is-active", "--quiet", SYSTEMD_UNIT]);
206
- return true;
207
- }
208
- catch {
209
- return false;
210
- }
211
- };
212
- const installed = () => existsSync(file);
213
- if (action === "status") {
214
- return reportStatus(deps, { installed: installed(), loaded: active() }, PROGRAM_VERSION);
215
- }
257
+ const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
258
+ const active = () => managerState(where(deps), run).loaded;
259
+ const installed = () => hasLoginService(deps.home, "linux");
260
+ if (action === "status")
261
+ return reportStatus(deps, run);
216
262
  if (action === "start" || action === "stop" || action === "restart") {
217
263
  if (!installed()) {
218
- deps.err("capybara-device service is not installed. Install it: capybara-device service install");
264
+ deps.err(NOT_INSTALLED);
219
265
  return 1;
220
266
  }
221
- if (action === "start" && active()) {
267
+ const state = managerState(where(deps), run);
268
+ if (action === "start" && state.loaded) {
222
269
  deps.out("The capybara-device login service is already running.");
223
270
  return 0;
224
271
  }
225
- if (action === "stop" && !active()) {
272
+ if (action === "stop" && !state.loaded) {
226
273
  deps.out("The capybara-device login service is not running.");
227
274
  return 0;
228
275
  }
276
+ if (action !== "stop" && !state.loaded && foregroundRunning(deps, state))
277
+ return 1;
229
278
  run("systemctl", ["--user", action, SYSTEMD_UNIT]);
279
+ if (action === "stop") {
280
+ if (active()) {
281
+ deps.err(`capybara-device service stop failed: the unit is still active. Check with: systemctl --user status ${SYSTEMD_UNIT}`);
282
+ return 1;
283
+ }
284
+ deps.out("Stopped the capybara-device login service; running commands ended. It starts again at the next login or with: capybara-device service start");
285
+ return 0;
286
+ }
287
+ if (!(await cameUp(deps, run, sleep, state.pid)))
288
+ return didNotComeBack(deps, action);
230
289
  deps.out(action === "start"
231
290
  ? "Started the capybara-device login service."
232
- : action === "restart"
233
- ? "Restarted the capybara-device login service."
234
- : "Stopped the capybara-device login service; running commands ended. It starts again at the next login or with: capybara-device service start");
291
+ : "Restarted the capybara-device login service.");
235
292
  return 0;
236
293
  }
237
294
  if (action === "install") {
@@ -1,2 +1,6 @@
1
- /** Sends `signal` to the running program; exit code 0 when it was signalled, 1 when none runs. */
2
- export declare function signalRunning(stateDir: string, signal: NodeJS.Signals, message: string, out: (line: string) => void, err: (line: string) => void, kill?: typeof process.kill): number;
1
+ import { type ProcessChecks } from "../pid.js";
2
+ /**
3
+ * Sends `signal` to the running program; exit code 0 when it was signalled, 1 when none runs. A
4
+ * pid the file names but that is not this program any more is never signalled.
5
+ */
6
+ export declare function signalRunning(stateDir: string, signal: NodeJS.Signals, message: string, out: (line: string) => void, err: (line: string) => void, checks?: ProcessChecks): number;
@@ -1,13 +1,16 @@
1
1
  import { readRunningPid } from "../pid.js";
2
- /** Sends `signal` to the running program; exit code 0 when it was signalled, 1 when none runs. */
3
- export function signalRunning(stateDir, signal, message, out, err, kill = process.kill) {
4
- const pid = readRunningPid(stateDir, kill);
2
+ /**
3
+ * Sends `signal` to the running program; exit code 0 when it was signalled, 1 when none runs. A
4
+ * pid the file names but that is not this program any more is never signalled.
5
+ */
6
+ export function signalRunning(stateDir, signal, message, out, err, checks = {}) {
7
+ const pid = readRunningPid(stateDir, checks);
5
8
  if (pid === undefined) {
6
9
  err("capybara-device is not running.");
7
10
  return 1;
8
11
  }
9
12
  try {
10
- kill(pid, signal);
13
+ (checks.kill ?? process.kill)(pid, signal);
11
14
  }
12
15
  catch (e) {
13
16
  err(`Could not signal pid ${pid}: ${e.message}`);
@@ -1,5 +1,6 @@
1
1
  import { connect } from "../client.js";
2
2
  import type { Executor } from "../exec/types.js";
3
+ import { type ProcessLookup } from "../pid.js";
3
4
  import { PolicyStore } from "../policy-store.js";
4
5
  import { type Credential } from "../state.js";
5
6
  export interface StartDeps {
@@ -19,6 +20,9 @@ export interface StartDeps {
19
20
  /** The process whose signals stop and drain the program. */
20
21
  proc?: Pick<NodeJS.Process, "on" | "off" | "pid">;
21
22
  kill?: typeof process.kill;
23
+ ps?: ProcessLookup;
24
+ /** The environment (default: process.env): tells whether the service manager started this. */
25
+ env?: Record<string, string | undefined>;
22
26
  connect?: typeof connect;
23
27
  }
24
28
  /** Printed once when policy.json was written before auto mode (spec §4.4). */
@@ -6,6 +6,7 @@ import { readRunningPid, removePid, writePid } from "../pid.js";
6
6
  import { PolicyStore } from "../policy-store.js";
7
7
  import { hasLoginService } from "../service/installed.js";
8
8
  import { rotateServiceLog } from "../service/launchd.js";
9
+ import { startedByServiceManager } from "../service/manager.js";
9
10
  import { readCredential } from "../state.js";
10
11
  import { PROGRAM_VERSION } from "../version.js";
11
12
  /** Printed once when policy.json was written before auto mode (spec §4.4). */
@@ -26,7 +27,9 @@ export async function start(deps) {
26
27
  return 1;
27
28
  }
28
29
  if (cred === undefined) {
29
- // Terminal: exit 0 so a service manager does not restart it until someone logs in.
30
+ // A deliberate stop: exit 0, which the service manager does not restart (launchd
31
+ // `KeepAlive { SuccessfulExit: false }`, systemd `Restart=on-failure`) until someone logs in
32
+ // and starts it.
30
33
  err("Not logged in. Run capybara-device login --url <url> first.");
31
34
  return 0;
32
35
  }
@@ -35,13 +38,17 @@ export async function start(deps) {
35
38
  return 1;
36
39
  }
37
40
  const where = deps.service ?? { home: homedir(), platform: process.platform };
38
- if (hasLoginService(where.home, where.platform)) {
39
- // The service manager runs exactly this command, so it must keep working; say how to control
40
- // the one that is installed.
41
+ if (hasLoginService(where.home, where.platform) &&
42
+ !startedByServiceManager(deps.env ?? process.env, proc.pid)) {
43
+ // Started in a terminal while a service is installed: say how to control the installed one.
44
+ // The service manager runs exactly this command, so it must keep working, without the hint.
41
45
  out("capybara-device runs as a login service on this machine. Restart it with: capybara-device service restart");
42
46
  }
43
47
  rotateServiceLog(stateDir);
44
- const running = readRunningPid(stateDir, deps.kill);
48
+ const running = readRunningPid(stateDir, {
49
+ ...(deps.kill && { kill: deps.kill }),
50
+ ...(deps.ps && { ps: deps.ps }),
51
+ });
45
52
  if (running !== undefined && running !== proc.pid) {
46
53
  err(`capybara-device is already running (pid ${running}). Stop it first: capybara-device stop`);
47
54
  return 1;
@@ -1,9 +1,20 @@
1
+ import { type ProcessChecks } from "../pid.js";
2
+ import { type RunSystem } from "../service/manager.js";
3
+ export interface StopOptions extends ProcessChecks {
4
+ /** Where the login service would be installed, and on which platform (default: this machine). */
5
+ service?: {
6
+ home: string;
7
+ platform: NodeJS.Platform;
8
+ uid?: number;
9
+ };
10
+ /** Asks the service manager (default: execFileSync). */
11
+ run?: RunSystem;
12
+ }
1
13
  /**
2
- * `stop`: SIGTERM to the running program. A machine that runs the program as a login service is
3
- * stopped through it instead: launchd's `KeepAlive` (and systemd's restart) would start a signalled
4
- * program straight back up, so `service stop` (which unloads the service) is the honest path.
14
+ * `stop`: SIGTERM to the running program. When the service manager runs that program (launchd has
15
+ * the service loaded, systemd has the unit active, and its pid is the running one), `stop` refuses
16
+ * and points at `service stop`, which unloads the service: a signalled service program would be
17
+ * started again by the restart policy, or would leave a service that looks loaded but stays down.
18
+ * A program started in a terminal is signalled as before, with or without a service installed.
5
19
  */
6
- export declare function stop(stateDir: string, out: (line: string) => void, err: (line: string) => void, kill?: typeof process.kill, service?: {
7
- home: string;
8
- platform: NodeJS.Platform;
9
- }): number;
20
+ export declare function stop(stateDir: string, out: (line: string) => void, err: (line: string) => void, opts?: StopOptions): number;
@@ -1,16 +1,28 @@
1
1
  import { homedir } from "node:os";
2
+ import { readRunning } from "../pid.js";
2
3
  import { hasLoginService } from "../service/installed.js";
4
+ import { defaultRunSystem, managerState } from "../service/manager.js";
3
5
  import { signalRunning } from "./signal.js";
4
6
  /**
5
- * `stop`: SIGTERM to the running program. A machine that runs the program as a login service is
6
- * stopped through it instead: launchd's `KeepAlive` (and systemd's restart) would start a signalled
7
- * program straight back up, so `service stop` (which unloads the service) is the honest path.
7
+ * `stop`: SIGTERM to the running program. When the service manager runs that program (launchd has
8
+ * the service loaded, systemd has the unit active, and its pid is the running one), `stop` refuses
9
+ * and points at `service stop`, which unloads the service: a signalled service program would be
10
+ * started again by the restart policy, or would leave a service that looks loaded but stays down.
11
+ * A program started in a terminal is signalled as before, with or without a service installed.
8
12
  */
9
- export function stop(stateDir, out, err, kill, service) {
10
- const where = service ?? { home: homedir(), platform: process.platform };
13
+ export function stop(stateDir, out, err, opts = {}) {
14
+ const where = opts.service ?? { home: homedir(), platform: process.platform };
15
+ const checks = {
16
+ ...(opts.kill && { kill: opts.kill }),
17
+ ...(opts.ps && { ps: opts.ps }),
18
+ };
11
19
  if (hasLoginService(where.home, where.platform)) {
12
- err("capybara-device runs as a login service on this machine. Stop it with: capybara-device service stop");
13
- return 1;
20
+ const state = managerState(where, opts.run ?? defaultRunSystem);
21
+ const program = readRunning(stateDir, checks);
22
+ if (state.loaded && program !== undefined && state.pid === program.pid) {
23
+ err("capybara-device runs as a login service on this machine. Stop it with: capybara-device service stop");
24
+ return 1;
25
+ }
14
26
  }
15
- return signalRunning(stateDir, "SIGTERM", "Stopping capybara-device.", out, err, kill);
27
+ return signalRunning(stateDir, "SIGTERM", "Stopping capybara-device.", out, err, checks);
16
28
  }
@@ -1,5 +1,5 @@
1
- import { type DeviceExecArgs, type ExecResult, type SandboxRoots } from "@capybara-hq/plugin-sdk";
2
- import type { Policy } from "../state.js";
1
+ import { type DeviceExecArgs, type DeviceListResult, type DeviceScanResult, type ExecResult, type SandboxRoots } from "@capybara-hq/plugin-sdk";
2
+ import type { Policy, SandboxMode } from "../state.js";
3
3
  import { type Executor } from "./types.js";
4
4
  /** The version of the published sandbox images this program runs commands in. */
5
5
  export declare const SANDBOX_IMAGE_TAG = "0.1.0-rc.5";
@@ -134,6 +134,28 @@ export declare class DockerExecutor implements Executor {
134
134
  size: number;
135
135
  isDir: boolean;
136
136
  } | null>;
137
+ /**
138
+ * `path` made absolute and normalized, refused unless it lies lexically under the container's
139
+ * workspace: a container device offers its workspace only, in either mode (spec §4.2).
140
+ */
141
+ private workspacePath;
142
+ /**
143
+ * Whether the device directory is marked and holds all three roots. `list` and `scan` only
144
+ * read: a removed root under a marked directory lost its files and is never recreated empty
145
+ * (`ensureContainer` would create it), and an unmarked or vanished directory gets no roots either.
146
+ */
147
+ private rootsIntact;
148
+ /**
149
+ * Runs {@link LIST_SCRIPT} in the container (as the `sandbox` user, like the file operations):
150
+ * links resolve in the container, so whatever a command there does to the workspace, the answer
151
+ * shows only what the container itself can see, never the host behind the bind mount. A stopped
152
+ * container is started first, as for the file operations.
153
+ */
154
+ private listOp;
155
+ /** Lists a container workspace directory, read in the container, in either mode. */
156
+ list(_mode: SandboxMode, path: string, limit: number, signal?: AbortSignal): Promise<DeviceListResult>;
157
+ /** Scans a container workspace directory, read in the container ({@link list}'s rules). */
158
+ scan(_mode: SandboxMode, base: string, signal?: AbortSignal): Promise<DeviceScanResult>;
137
159
  /** Kills the container processes of one marker (exact) or marker prefix. */
138
160
  private killScript;
139
161
  private killMarker;