pi-background-run 0.1.0 → 0.2.0
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 +38 -3
- package/extension/index.test.ts +573 -59
- package/extension/index.ts +452 -101
- package/package.json +8 -4
- package/skill/run-bg/SKILL.md +15 -7
package/README.md
CHANGED
|
@@ -34,9 +34,9 @@ Restart pi after install so the extension loads.
|
|
|
34
34
|
| Tool | Purpose |
|
|
35
35
|
| ------ | --------- |
|
|
36
36
|
| `bgrun` | Launch a command detached in the background. Optional `name` gives the job a short human-readable label. Returns `started: <job-id>` immediately. Wakes the session automatically on completion. |
|
|
37
|
-
| `bgstatus` |
|
|
37
|
+
| `bgstatus` | Show job status. With an id: any job's state + exit code. Without: this session's running jobs (finished jobs hidden by default — pass `includeDone: true` or set `showCompletedJobs`). Jobs from other sessions are only listed when `adoptForeignJobs` is enabled. |
|
|
38
38
|
| `bgtail` | Print the last N lines of a job's log (default 40), stripping the exit marker. |
|
|
39
|
-
| `bgclean` | Remove old job logs (
|
|
39
|
+
| `bgclean` | Remove old job logs. Default retention: `cleanupDays` config (7 days). Always runs — not throttled. |
|
|
40
40
|
|
|
41
41
|
`bgwait` and `bgkill` are not provided — the pi port has no shell runner. Use
|
|
42
42
|
`bash` with `kill` if you ever need to stop a running job.
|
|
@@ -72,9 +72,44 @@ exit code even after a restart.
|
|
|
72
72
|
|
|
73
73
|
## Configuration
|
|
74
74
|
|
|
75
|
+
The jobs dir (`~/.pi-bgrun/jobs`) is shared by **every pi session on the
|
|
76
|
+
machine**. By default each session only *tracks its own jobs*: the widget and
|
|
77
|
+
`bgstatus` listings show this session's running jobs, and finished jobs are
|
|
78
|
+
hidden (ask for them explicitly with `bgstatus includeDone: true`). Jobs
|
|
79
|
+
started by other sessions can still be inspected by id, but they don't clutter
|
|
80
|
+
your widget.
|
|
81
|
+
|
|
82
|
+
Configuration is layered (later wins): **defaults ← user config file ← project
|
|
83
|
+
config file (trusted projects only) ← environment variables**.
|
|
84
|
+
|
|
85
|
+
- User: `~/.pi/agent/pi-bgrun.json`
|
|
86
|
+
- Project: `<project>/.pi/pi-bgrun.json`
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"adoptForeignJobs": false,
|
|
91
|
+
"showCompletedJobs": false,
|
|
92
|
+
"cleanupDays": 7,
|
|
93
|
+
"jobsDir": "/some/other/dir"
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Environment variables (same knobs, handy for one-off overrides):
|
|
98
|
+
|
|
75
99
|
| Variable | Default | Description |
|
|
76
|
-
|
|
100
|
+
| --- | --- | --- |
|
|
77
101
|
| `PI_BGRUN_DIR` | `~/.pi-bgrun/jobs` | Override where job logs are stored. |
|
|
102
|
+
| `PI_BGRUN_FOREIGN_JOBS` | `false` | Adopt other sessions' running jobs into this session's widget and job list. Adopted jobs are polled so they leave the widget when they finish. |
|
|
103
|
+
| `PI_BGRUN_SHOW_COMPLETED` | `false` | Include finished jobs in `bgstatus` listings by default. |
|
|
104
|
+
| `PI_BGRUN_CLEANUP_DAYS` | `7` | Log retention for auto-clean sweeps and the `bgclean` default. |
|
|
105
|
+
|
|
106
|
+
### Log cleanup
|
|
107
|
+
|
|
108
|
+
- **Auto-sweep** runs at `session_start` and `session_shutdown`, but at most
|
|
109
|
+
**once per `cleanupDays`** (tracked by a `.last-clean` marker in the jobs dir)
|
|
110
|
+
— restart-heavy workflows don't re-sweep on every launch.
|
|
111
|
+
- **Manual** `bgclean` always runs immediately and refreshes the marker.
|
|
112
|
+
- Running jobs are never swept while their pid is alive.
|
|
78
113
|
|
|
79
114
|
## Status
|
|
80
115
|
|