feat: ensure kill confirmation

Author: antongolub

README.md

@@ -81,23 +81,25 @@ const list = tree.sync({ pid: 123, recursive: true })
 ```
 
 ### kill(pid, opts?, callback?)
-Kills a process and optionally verifies it has exited.
+Kills a process and waits for it to exit. The returned promise resolves once the process is confirmed dead, or rejects on timeout.
 
 ```ts
 import { kill } from '@webpod/ps'
 
+// Sends SIGTERM, polls until the process is gone (default timeout 30s)
 await kill(12345)
 
 // With signal
 await kill(12345, 'SIGKILL')
 
-// With options and verification callback
-await kill(12345, { signal: 'SIGKILL', timeout: 10 }, (err, pid) => {
+// With custom timeout (seconds) and polling interval (ms)
+await kill(12345, { signal: 'SIGKILL', timeout: 10, interval: 250 })
+
+// With callback
+await kill(12345, (err, pid) => {
   // called when the process is confirmed dead or timeout is reached
 })
 ```
 
-When a `callback` is provided, `kill` polls the process list until the process disappears or the `timeout` (default 30s) is reached.
-
 ## License
 [MIT](./LICENSE)

src/main/ts/ps.ts

@@ -61,6 +61,8 @@ export type TPsLookupCallback = (err: any, processList?: TPsLookupEntry[]) => vo
 export type TPsKillOptions = {
   timeout?: number
   signal?: string | number | NodeJS.Signals
+  /** Polling interval in ms between exit checks (default 200). */
+  interval?: number
 }
 
 export type TPsTreeOpts = {
@@ -170,7 +172,7 @@ export const kill = (pid: string | number, opts?: TPsNext | TPsKillOptions | TPs
   if (typeof opts === 'string' || typeof opts === 'number') return kill(pid, { signal: opts }, next)
 
   const { promise, resolve, reject } = makeDeferred()
-  const { timeout = 30, signal = 'SIGTERM' } = opts || {}
+  const { timeout = 30, signal = 'SIGTERM', interval = 200 } = opts || {}
 
   try {
     process.kill(+pid, signal)
@@ -180,17 +182,14 @@ export const kill = (pid: string | number, opts?: TPsNext | TPsKillOptions | TPs
     return promise
   }
 
-  if (!next) {
-    resolve(pid)
-    return promise
-  }
-
   let confirmCount = 0
   let timedOut = false
 
   const timer = setTimeout(() => {
     timedOut = true
-    next(new Error('Kill process timeout'))
+    const err = new Error('Kill process timeout')
+    reject(err)
+    next?.(err)
   }, timeout * 1000)
 
   const poll = () =>
@@ -199,21 +198,21 @@ export const kill = (pid: string | number, opts?: TPsNext | TPsKillOptions | TPs
       if (err) {
         clearTimeout(timer)
         reject(err)
-        next(err, pid)
+        next?.(err, pid)
         return
       }
       if (list.length > 0) {
         confirmCount = Math.max(confirmCount - 1, 0)
-        poll()
+        setTimeout(poll, interval)
         return
       }
       confirmCount++
       if (confirmCount >= 5) {
         clearTimeout(timer)
         resolve(pid)
-        next(null, pid)
+        next?.(null, pid)
       } else {
-        poll()
+        setTimeout(poll, interval)
       }
     })
 

src/test/ts/ps.test.ts

@@ -3,7 +3,7 @@ import { describe, it, before, after } from 'node:test'
 import process from 'node:process'
 import { fork, execSync } from 'node:child_process'
 import * as path from 'node:path'
-import { kill, lookup, lookupSync, tree, treeSync, removeWmicPrefix, normalizeOutput } from '../../main/ts/ps.ts'
+import { kill, lookup, lookupSync, tree, treeSync, removeWmicPrefix, normalizeOutput, filterProcessList } from '../../main/ts/ps.ts'
 import { parse } from '@webpod/ingrid'
 
 const __dirname = new URL('.', import.meta.url).pathname
@@ -40,6 +40,14 @@ describe('lookup()', () => {
     assert.equal(list.length, 1)
     assert.equal(list[0].pid, pid)
   })
+
+  if (process.platform !== 'win32') {
+    it('supports custom psargs', async () => {
+      const list = await lookup({ pid, psargs: '-eo pid,ppid,args' })
+      assert.equal(list.length, 1)
+      assert.equal(list[0].pid, pid)
+    })
+  }
 })
 
 describe('lookupSync()', () => {
@@ -86,7 +94,6 @@ describe('tree()', () => {
     const childrenAll = await tree({ pid, recursive: true })
 
     await Promise.all(list.map(p => kill(p.pid)))
-    await kill(pid)
 
     assert.equal(children.length, 1)
     assert.equal(childrenAll.length, 2)
@@ -113,7 +120,6 @@ describe('treeSync()', () => {
     const childrenAll = treeSync({ pid, recursive: true })
 
     await Promise.all(list.map(p => kill(p.pid)))
-    await kill(pid)
 
     assert.equal(children.length, 1)
     assert.equal(childrenAll.length, 2)
@@ -170,6 +176,115 @@ describe('ps -eo vs ps -lx output comparison', { skip: process.platform === 'win
   })
 })
 
+describe('kill() edge cases', () => {
+  it('rejects when killing a non-existent pid', async () => {
+    await assert.rejects(() => kill(999999), { code: 'ESRCH' })
+  })
+
+  it('rejects with invalid signal', async () => {
+    const pid = spawnChild()
+    await assert.rejects(() => kill(pid, 'INVALID'))
+    killSafe(pid)
+  })
+
+  it('passes signal as string shorthand', async () => {
+    const pid = spawnChild()
+    await kill(pid, 'SIGKILL')
+    assert.equal((await lookup({ pid })).length, 0)
+  })
+
+  it('invokes callback on error for non-existent pid', async () => {
+    let cbErr: any
+    await kill(999999, (err) => { cbErr = err }).catch(() => {})
+    assert.ok(cbErr)
+  })
+})
+
+describe('kill() timeout', { skip: process.platform === 'win32' }, () => {
+  it('rejects on timeout when process stays alive', async () => {
+    // Signal 0 checks existence but doesn't actually kill — process stays alive, so poll times out
+    const pid = spawnChild()
+    await assert.rejects(
+      () => kill(pid, { signal: 0 as any, timeout: 1 }),
+      (err: Error) => err.message.includes('timeout')
+    )
+    killSafe(pid)
+  })
+})
+
+describe('tree() edge cases', () => {
+  it('accepts string pid', async () => {
+    const pid = spawnChild()
+    const children = await tree(String(pid))
+    assert.ok(Array.isArray(children))
+    killSafe(pid)
+  })
+
+  it('treeSync accepts number pid', () => {
+    const pid = spawnChild()
+    const children = treeSync(pid)
+    assert.ok(Array.isArray(children))
+    killSafe(pid)
+  })
+})
+
+describe('filterProcessList()', () => {
+  const list = [
+    { pid: '1', ppid: '0', command: '/usr/bin/node', arguments: ['server.js', '--port=3000'] },
+    { pid: '2', ppid: '1', command: '/usr/bin/python', arguments: ['app.py'] },
+    { pid: '3', ppid: '1', command: '/usr/bin/node', arguments: ['worker.js'] },
+  ]
+
+  it('filters by pid array', () => {
+    assert.equal(filterProcessList(list, { pid: ['1', '3'] }).length, 2)
+  })
+
+  it('filters by command regex', () => {
+    assert.equal(filterProcessList(list, { command: 'node' }).length, 2)
+  })
+
+  it('filters by arguments regex', () => {
+    assert.equal(filterProcessList(list, { arguments: 'port' }).length, 1)
+  })
+
+  it('filters by ppid', () => {
+    assert.equal(filterProcessList(list, { ppid: 1 }).length, 2)
+  })
+
+  it('returns all when no filters', () => {
+    assert.equal(filterProcessList(list).length, 3)
+  })
+})
+
+describe('normalizeOutput()', () => {
+  it('skips entries without pid', () => {
+    const data = [{ COMMAND: ['node'] }] as any
+    assert.equal(normalizeOutput(data).length, 0)
+  })
+
+  it('skips entries without command', () => {
+    const data = [{ PID: ['1'] }] as any
+    assert.equal(normalizeOutput(data).length, 0)
+  })
+
+  it('handles ARGS header (macOS)', () => {
+    const data = [{ PID: ['1'], PPID: ['0'], ARGS: ['/usr/bin/node server.js'] }] as any
+    const result = normalizeOutput(data)
+    assert.equal(result.length, 1)
+    assert.ok(result[0].command)
+  })
+
+  it('handles quoted paths on Windows', () => {
+    const data = [{
+      ProcessId: ['1'],
+      ParentProcessId: ['0'],
+      CommandLine: ['"C:\\Program Files\\node.exe" server.js']
+    }] as any
+    const result = normalizeOutput(data)
+    assert.equal(result.length, 1)
+  })
+})
+
 describe('removeWmicPrefix()', () => {
   it('extracts wmic output', () => {
     const input = `CommandLine
@@ -184,4 +299,10 @@ PS C:\\Users\\user>`
     const sliced = removeWmicPrefix(input).trim()
     assert.equal(sliced, input.slice(0, -'PS C:\\Users\\user>'.length - 1).trim())
   })
+
+  it('handles output without prompt suffix', () => {
+    const input = `ParentProcessId  ProcessId\n0                1`
+    const result = removeWmicPrefix(input)
+    assert.ok(result.includes('ProcessId'))
+  })
 })