HarperFast / HarperFast/harper
[Epic] Component-spawned process supervision (substituted child_process module)
- Dominant language
- JavaScript
- Stars
- 89
- Forks
- 10
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 200
Description
Tracking epic for Harper's substituted `child_process` module — the replacement that `security/jsLoader.ts` hands to component code in place of the real Node builtin (`security/jsLoader.ts:918-1127`), and the single-process PID-file supervisor behind it.
The substitute exists to give components a *supervised* way to run a sidecar process: an `allowedSpawnCommands` allowlist, a mandatory `options.name`, a `/pids/.pid` lock so only one process per name runs across all threads, and an optional `options.version` that replaces a running process when the caller bumps it. Several of those guarantees do not hold as written.
### In scope
- Argument marshalling between the wrapper's fixed `(command, args, options, callback)` shape and each wrapped function's real Node signature.
- PID-file lock lifecycle: acquisition, the version-replacement handoff, cleanup on exit, stale-file recovery.
- Validation of `options.name` and `options.version`.
- `ExistingProcessWrapper` — the ChildProcess-like object returned when a process is adopted rather than spawned.
- The `/pids/` namespace and how names from independent components share it.
### Out of scope
- **Whether the substitution is reached at all.** Loader paths that hand component code the *real* `child_process` (CJS `require`, compartment mode, natively-loaded npm dependencies) are an access-control enforcement gap, and live under [[Epic] Access-control enforcement gaps](https://github.com/HarperFast/harper/issues/1646) with the other allowlist bypasses — see harper#1924 and harper#1929.
- **The component install/deploy spawn path** in `components/Application.ts` (`waitForConfirmedTermination`, `processGroupIsAlive`) — a different supervisor with its own defects; see harper#2076 and harper#2072.
Routing rule: if the defect is in what the substitute *does* once you reach it, it belongs here. If it is about *reaching* the substitute (or not), it belongs in #1646.
---
_Filed by KrAIs (Claude Opus 5), from source confirmation against `origin/main` @ `f8a5aa90a` (v5.2.4) while documenting this module for HarperFast/documentation#634._
Contributor guide
Research direction
Start with security/jsLoader.ts:918-1127 and trace the substituted child_process wrapper and PID-file supervisor. Review argument marshalling, validation, lock lifecycle, ExistingProcessWrapper, and the shared pids namespace against the guarantees listed here. Done requires resolving the identified defects with coverage for the affected supervision behavior, though this epic does not name specific tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- backend, security
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100