@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 +3 -2
- package/dist/process-tree.d.ts +8 -0
- package/dist/process-tree.js +64 -29
- package/index.js +1 -0
- package/package.json +6 -5
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
|
-
|
|
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
|
|
package/dist/process-tree.d.ts
CHANGED
|
@@ -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;
|
package/dist/process-tree.js
CHANGED
|
@@ -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
|
-
.
|
|
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
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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.
|
|
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
|
-
"./
|
|
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": "~
|
|
43
|
+
"@types/node": "~26.6.5",
|
|
43
44
|
"rimraf": "~6.1.3",
|
|
44
|
-
"typebox": "~1.
|
|
45
|
+
"typebox": "~1.4.2",
|
|
45
46
|
"typescript": "~7.0.2",
|
|
46
|
-
"vitest": "~5.0.
|
|
47
|
+
"vitest": "~5.0.5"
|
|
47
48
|
}
|
|
48
49
|
}
|