@alignfirst/pi-background 0.1.0 → 0.1.2

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 CHANGED
@@ -12,7 +12,7 @@ pi install npm:@alignfirst/pi-background
12
12
 
13
13
  Requires Node.js 22.19.0 or later. Tested with **Pi 1.3.0**, **Node 26.8.1 / 22.23.3**, and **Linux**. The exact Node 22.19.0 floor has not been exercised. macOS and Windows through WSL are supported targets but have not been exercised here. Native Windows is refused before process launch. Host peer ranges are `*` under Pi's package rules; they do not certify future Pi versions.
14
14
 
15
- Loading the extension starts no process or timer. Installation and loading do not install profiles, skills, or the other extension.
15
+ The package declares root `index.js` as its sole Pi extension entry. It forwards the default factory from compiled `dist/index.js`, so Pi displays the npm package label without `:dist`. Loading starts no process or timer. Installation and loading do not install profiles, skills, or the other extension.
16
16
 
17
17
  ## Actions
18
18
 
@@ -117,13 +117,14 @@ Linux cleanup verifies process-start identities before signalling. macOS uses pr
117
117
 
118
118
  ```sh
119
119
  npm test --workspace @alignfirst/pi-background
120
+ npm run test:integration --workspace @alignfirst/pi-background
120
121
  npm run typecheck --workspace @alignfirst/pi-background
121
122
  npm run build --workspace @alignfirst/pi-background
122
123
  npm run lint --workspace @alignfirst/pi-background
123
124
  npm pack --workspace @alignfirst/pi-background --dry-run --json
124
125
  ```
125
126
 
126
- `test/process-tree.test.ts` exercises real descendants, TERM resistance, separate groups, retained pipes, actual Pi/bash cleanup, parent shutdown, query failure/retry, and reaping. `test/lifecycle.test.ts` uses Pi's public session runtime and a local scripted provider to exercise scheduling and replacement. `test/tool.test.ts` covers public actions, startup/cancellation races, capacity, cleanup failures, and output limits. Deterministic tests require no external model or network request. `test/aligndev-integration.test.ts` adds real CLI subprocess tests through the packed extension; this is a test dependency only. Repository `npm run release:smoke` verifies standalone packed installs without either CLI. Opt-in Terra and real terminal lifecycle checks are documented in [Pi Extensions](../../docs/pi-extensions.md#checks).
127
+ `test/process-tree.test.ts` exercises real descendants, TERM resistance, separate groups, retained pipes, actual Pi/bash cleanup, parent shutdown, query failure/retry, and reaping. `test/lifecycle.test.ts` uses Pi's public session runtime and a local scripted provider to exercise scheduling and replacement. `test/tool.test.ts` covers public actions, startup/cancellation races, capacity, cleanup failures, and output limits. Deterministic tests require no external model or network request. `test/integration/aligndev-integration.test.ts` runs through `test:integration` and adds real CLI subprocess tests through the packed extension; this is a test dependency only. Repository `npm run release:smoke` verifies standalone packed installs without either CLI. Opt-in Terra and real terminal lifecycle checks are documented in [Pi Extensions](../../docs/pi-extensions.md#checks).
127
128
 
128
129
  The package-local `src/process-tree.ts` deliberately duplicates the small cleanup leaf from `pi-subagent`; propagate generic cleanup fixes and their conformance cases to both packages. Neither package imports the other at runtime.
129
130
 
@@ -20,4 +20,12 @@ export interface LaunchOptions {
20
20
  stderr: (chunk: Buffer) => void;
21
21
  inputError: (error: Error) => void;
22
22
  }
23
+ export interface Target {
24
+ pid: number;
25
+ ppid: number;
26
+ group: number;
27
+ identity: string;
28
+ zombie: boolean;
29
+ }
23
30
  export declare function launchManaged(options: LaunchOptions): ManagedProcess;
31
+ export declare function psTarget(line: string): Target;
@@ -1,7 +1,10 @@
1
1
  import { execFile, spawn } from "node:child_process";
2
- import { readFileSync } from "node:fs";
2
+ import { readdirSync, readFileSync } from "node:fs";
3
3
  const GRACE_MS = 5_000;
4
4
  const REAP_MS = 2_000;
5
+ const VANISHED_CODES = ["ENOENT", "ESRCH"];
6
+ // Under hidepid, other users' processes are unreadable; the scan skips them, as ps does.
7
+ const HIDDEN_CODES = [...VANISHED_CODES, "EPERM", "EACCES"];
5
8
  export function launchManaged(options) {
6
9
  if (process.platform !== "linux" && process.platform !== "darwin") {
7
10
  throw new Error("Background process supervision requires Linux, macOS, or Windows through WSL.");
@@ -130,6 +133,50 @@ async function refreshTargets(managed, targets, groups) {
130
133
  }
131
134
  }
132
135
  async function processTable() {
136
+ if (process.platform === "linux")
137
+ return linuxProcessTable();
138
+ return psProcessTable();
139
+ }
140
+ function linuxProcessTable() {
141
+ return readdirSync("/proc")
142
+ .filter((name) => /^\d+$/.test(name))
143
+ .flatMap((name) => {
144
+ const pid = Number(name);
145
+ const fields = readStatFields(pid, HIDDEN_CODES);
146
+ return fields ? [linuxTarget(pid, fields)] : [];
147
+ });
148
+ }
149
+ // The fields after the command name, or undefined when the read fails with a skipped code.
150
+ function readStatFields(pid, skippedCodes) {
151
+ try {
152
+ const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
153
+ return stat.slice(stat.lastIndexOf(")") + 2).split(" ");
154
+ }
155
+ catch (error) {
156
+ if (error instanceof Error &&
157
+ "code" in error &&
158
+ typeof error.code === "string" &&
159
+ skippedCodes.includes(error.code))
160
+ return;
161
+ throw error;
162
+ }
163
+ }
164
+ function linuxTarget(pid, fields) {
165
+ const [state, rawParent, rawGroup] = fields;
166
+ const ppid = Number(rawParent);
167
+ const group = Number(rawGroup);
168
+ if (![pid, ppid, group].every(Number.isSafeInteger) || pid < 1 || ppid < 0 || group < 0) {
169
+ throw new Error("Invalid /proc stat.");
170
+ }
171
+ return { pid, ppid, group, identity: statIdentity(fields), zombie: state === "Z" };
172
+ }
173
+ function statIdentity(fields) {
174
+ const identity = fields[19];
175
+ if (identity === undefined || !/^\d+$/.test(identity))
176
+ throw new Error("Invalid /proc stat.");
177
+ return identity;
178
+ }
179
+ async function psProcessTable() {
133
180
  const output = await new Promise((resolve, reject) => {
134
181
  execFile("/bin/ps", ["-axo", "pid=,ppid=,pgid=,stat=,lstart="], {
135
182
  timeout: 1_000,
@@ -140,36 +187,24 @@ async function processTable() {
140
187
  return output
141
188
  .split("\n")
142
189
  .filter((line) => line.trim() !== "")
143
- .flatMap((line) => {
144
- const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line);
145
- if (!match)
146
- throw new Error("Invalid process query record.");
147
- const [, rawPid, rawParent, rawGroup, state, started] = match;
148
- const pid = Number(rawPid);
149
- const ppid = Number(rawParent);
150
- const group = Number(rawGroup);
151
- if (![pid, ppid, group].every(Number.isSafeInteger) || pid < 1 || ppid < 0 || group < 0) {
152
- throw new Error("Unsafe process query record.");
153
- }
154
- const identity = process.platform === "linux" ? linuxIdentity(pid) : started;
155
- if (identity === undefined)
156
- return [];
157
- return [{ pid, ppid, group, identity, zombie: state.startsWith("Z") }];
158
- });
190
+ .map(psTarget);
159
191
  }
160
- function linuxIdentity(pid) {
161
- try {
162
- const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
163
- const identity = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
164
- if (identity === undefined || !/^\d+$/.test(identity))
165
- throw new Error("Invalid /proc stat.");
166
- return identity;
167
- }
168
- catch (error) {
169
- if (error instanceof Error && "code" in error && error.code === "ENOENT")
170
- return;
171
- throw error;
192
+ export function psTarget(line) {
193
+ const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line);
194
+ if (!match)
195
+ throw new Error("Invalid process query record.");
196
+ const [, rawPid, rawParent, rawGroup, state, started] = match;
197
+ const pid = Number(rawPid);
198
+ const ppid = Number(rawParent);
199
+ const group = Number(rawGroup);
200
+ if (![pid, ppid, group].every(Number.isSafeInteger) || pid < 1 || ppid < 0 || group < 0) {
201
+ throw new Error("Unsafe process query record.");
172
202
  }
203
+ return { pid, ppid, group, identity: started, zombie: state.startsWith("Z") };
204
+ }
205
+ function linuxIdentity(pid) {
206
+ const fields = readStatFields(pid, VANISHED_CODES);
207
+ return fields && statIdentity(fields);
173
208
  }
174
209
  function signalTargets(targets, signal) {
175
210
  for (const target of targets.values()) {
package/index.js ADDED
@@ -0,0 +1 @@
1
+ export { default } from "./dist/index.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alignfirst/pi-background",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Session-owned background shell jobs with bounded output and native Pi completion.",
5
5
  "license": "MIT",
6
6
  "author": "Thomas MUR",
@@ -19,6 +19,7 @@
19
19
  "node": ">=22.19.0"
20
20
  },
21
21
  "files": [
22
+ "index.js",
22
23
  "dist",
23
24
  "README.md",
24
25
  "LICENSE",
@@ -29,7 +30,7 @@
29
30
  },
30
31
  "pi": {
31
32
  "extensions": [
32
- "./dist/index.js"
33
+ "./index.js"
33
34
  ]
34
35
  },
35
36
  "peerDependencies": {
@@ -39,10 +40,10 @@
39
40
  "devDependencies": {
40
41
  "@earendil-works/pi-ai": "1.3.0",
41
42
  "@earendil-works/pi-coding-agent": "1.3.0",
42
- "@types/node": "~24.13.3",
43
+ "@types/node": "~26.6.5",
43
44
  "rimraf": "~6.1.3",
44
- "typebox": "~1.3.23",
45
+ "typebox": "~1.4.2",
45
46
  "typescript": "~7.0.2",
46
- "vitest": "~5.0.1"
47
+ "vitest": "~5.0.5"
47
48
  }
48
49
  }