@alignfirst/pi-background 0.1.1 → 0.1.3

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
@@ -10,7 +10,7 @@ This package works independently of any project tooling and of the subagent exte
10
10
  pi install npm:@alignfirst/pi-background
11
11
  ```
12
12
 
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.
13
+ Requires the Node.js runtime declared in `engines.node`. See the [supported and tested baseline](https://github.com/paleo/alignfirst/blob/main/docs/pi-extensions.md#supported-and-tested-baseline) for Pi compatibility and checks not rerun after the dependency upgrade. 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
 
@@ -115,11 +115,13 @@ Linux cleanup verifies process-start identities before signalling. macOS uses pr
115
115
 
116
116
  ## Maintainer checks
117
117
 
118
+ From the repository root, complete `npm run build` before integration, including filtered files. Preflight checks provisioning only; rebuild after source changes.
119
+
118
120
  ```sh
121
+ npm run build
119
122
  npm test --workspace @alignfirst/pi-background
120
123
  npm run test:integration --workspace @alignfirst/pi-background
121
124
  npm run typecheck --workspace @alignfirst/pi-background
122
- npm run build --workspace @alignfirst/pi-background
123
125
  npm run lint --workspace @alignfirst/pi-background
124
126
  npm pack --workspace @alignfirst/pi-background --dry-run --json
125
127
  ```
@@ -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,38 +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 &&
170
- "code" in error &&
171
- (error.code === "ENOENT" || error.code === "ESRCH"))
172
- return;
173
- 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.");
174
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);
175
208
  }
176
209
  function signalTargets(targets, signal) {
177
210
  for (const target of targets.values()) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alignfirst/pi-background",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "Session-owned background shell jobs with bounded output and native Pi completion.",
5
5
  "license": "MIT",
6
6
  "author": "Thomas MUR",
@@ -38,12 +38,12 @@
38
38
  "typebox": "*"
39
39
  },
40
40
  "devDependencies": {
41
- "@earendil-works/pi-ai": "1.3.0",
42
- "@earendil-works/pi-coding-agent": "1.3.0",
43
- "@types/node": "~24.13.3",
41
+ "@earendil-works/pi-ai": "1.4.0",
42
+ "@earendil-works/pi-coding-agent": "1.4.0",
43
+ "@types/node": "~26.6.6",
44
44
  "rimraf": "~6.1.3",
45
- "typebox": "~1.3.23",
45
+ "typebox": "~1.4.3",
46
46
  "typescript": "~7.0.2",
47
- "vitest": "~5.0.1"
47
+ "vitest": "~5.0.5"
48
48
  }
49
49
  }