geloforge 0.6.0 → 0.9.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 +84 -87
- package/VERSION +1 -1
- package/adapters/n8n/staging-audit-error-workflow.json +132 -0
- package/core/audit-learning.mjs +68 -0
- package/core/audit-provider.mjs +157 -0
- package/core/autonomous-audit.mjs +214 -0
- package/core/checkpoint.mjs +20 -10
- package/core/coding-loop.mjs +500 -0
- package/core/compatibility.json +1 -1
- package/core/context-cache.mjs +114 -0
- package/core/context-compiler.mjs +77 -10
- package/core/doctor.mjs +319 -0
- package/core/evidence-capture.mjs +24 -3
- package/core/hooks-init.mjs +245 -0
- package/core/mcp-init.mjs +13 -9
- package/core/mcp-lock.mjs +488 -0
- package/core/mcp-server.mjs +70 -8
- package/core/operation-approval.mjs +102 -0
- package/core/project-lock.mjs +49 -17
- package/core/project-status.mjs +68 -0
- package/core/promotion.mjs +90 -0
- package/core/runtime-files.mjs +40 -0
- package/core/skills-advisor.mjs +944 -0
- package/core/staging-audit.mjs +454 -0
- package/core/staging-evidence.mjs +127 -0
- package/core/task-manager.mjs +3 -1
- package/core/text-utils.mjs +63 -5
- package/core/worktrees.mjs +64 -0
- package/package.json +6 -2
- package/policies/approval-boundaries.md +4 -4
- package/policies/token-efficiency.md +9 -9
- package/schemas/approval-record.schema.json +9 -0
- package/scripts/geloforge.mjs +648 -14
- package/templates/project-starter/AGENTS.md +4 -3
package/README.md
CHANGED
|
@@ -1,141 +1,138 @@
|
|
|
1
1
|
# GeloForge
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Give your AI coding agents a shared memory — and make them prove their work.**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
[](https://github.com/63L0/GeloForge/releases/latest)
|
|
7
|
-
[](./LICENSE)
|
|
8
|
-
|
|
9
|
-

|
|
5
|
+
Switch freely between **Cursor, VS Code, Claude Code, Codex CLI, Gemini CLI, and Antigravity** without re-explaining your codebase or trusting unverified `"tests pass"` claims. GeloForge is a local-first, **zero-dependency** CLI + MCP server that stores decisions, scoped tasks, real command evidence, and clean handoffs right inside your repo.
|
|
10
6
|
|
|
11
|
-
[
|
|
12
|
-
|
|
13
|
-
|
|
7
|
+
[](https://github.com/63L0/GeloForge/actions/workflows/ci.yml)
|
|
8
|
+
[](https://www.npmjs.com/package/geloforge)
|
|
9
|
+
[](https://nodejs.org/)
|
|
10
|
+
[](./package.json)
|
|
11
|
+
[](./LICENSE)
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+

|
|
16
14
|
|
|
17
|
-
|
|
15
|
+
*[Read the full multi-session case study & reproduction steps →](./docs/dogfooding-v06.md)*
|
|
18
16
|
|
|
19
|
-
|
|
17
|
+
---
|
|
20
18
|
|
|
21
19
|
## Why GeloForge?
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
When you start a fresh AI chat or switch tools, yesterday’s context disappears. **GeloForge fixes that with plain Markdown/YAML files in your repo** — zero databases, zero cloud lock-in, and zero third-party runtime packages.
|
|
22
|
+
|
|
23
|
+
| Without GeloForge | With GeloForge |
|
|
24
24
|
| --- | --- |
|
|
25
|
-
|
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
25
|
+
| Re-explaining architecture & constraints in every new chat | **Compiled Context:** One deterministic packet (`brain/` + codebase map + skills) in seconds |
|
|
26
|
+
| Agents claiming *"fixed!"* without running tests | **Verified Evidence:** Real exit-code command checks (`verify` / `evidence capture`) gate task completion |
|
|
27
|
+
| Two AI tools overwriting each other's files | **Cooperative Leases:** Scope locks flag overlapping edits before files collide |
|
|
28
|
+
| Surprise MCP tool changes or unreviewed agent habits | **Pinned Tools & Signed Skills:** `mcp lock --check` catches tool drift; skills require owner approval |
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
---
|
|
31
31
|
|
|
32
32
|
## Quick start
|
|
33
33
|
|
|
34
|
-
**
|
|
34
|
+
**Prerequisites:** Node.js 20+ and Git installed. Pick whichever path feels easier:
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
### Option A — New to CLI? Paste this to your AI coding agent
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
npx geloforge
|
|
38
|
+
Copy this into **Cursor, Claude Code, Codex, Gemini CLI, or Antigravity** inside your project folder:
|
|
39
|
+
|
|
40
|
+
```text
|
|
41
|
+
Set up GeloForge in this repository safely. First run `npx geloforge adopt --dry-run` and explain what files will be added without modifying my existing code. After I confirm, run `npx geloforge adopt`, `npx geloforge mcp init`, `npx geloforge hooks init --dry-run`, and `npx geloforge doctor`. Then run `npx geloforge skills suggest` to recommend matching skills and ask what my first goal is. Do NOT edit my app code or auto-promote skills.
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
> Want ready-to-paste prompts for daily tasks, tests, and checkpoints? See **[Beginner AI Prompts](./docs/beginner-prompts.md)**.
|
|
45
|
+
|
|
46
|
+
### Option B — Run the CLI yourself
|
|
47
|
+
|
|
48
|
+
Run these from the root of any existing project:
|
|
45
49
|
|
|
46
50
|
```bash
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
+
# 1. Preview what files will be added (touches nothing)
|
|
52
|
+
npx geloforge adopt --dry-run
|
|
53
|
+
|
|
54
|
+
# 2. Add GeloForge Second Brain alongside your code + check health
|
|
55
|
+
npx geloforge adopt
|
|
56
|
+
npx geloforge status
|
|
57
|
+
npx geloforge doctor
|
|
51
58
|
```
|
|
52
59
|
|
|
53
|
-
|
|
60
|
+
**Connect your AI editor and optional ambient hooks:**
|
|
54
61
|
|
|
55
62
|
```bash
|
|
56
|
-
|
|
57
|
-
geloforge
|
|
58
|
-
geloforge adopt # Add project memory without overwriting your code
|
|
59
|
-
geloforge status
|
|
63
|
+
npx geloforge mcp init
|
|
64
|
+
npx geloforge hooks init --dry-run
|
|
60
65
|
```
|
|
61
66
|
|
|
62
|
-
|
|
67
|
+
This configures **Cursor, VS Code, Claude Code, and Gemini CLI** (add `--client antigravity` for Antigravity) and previews opt-in Git/agent hooks. Open your project, approve the folder's MCP prompt, and your agents can read tasks, context, and evidence automatically.
|
|
63
68
|
|
|
64
|
-
|
|
69
|
+
> Starting a brand-new project instead? See [Creating a new project](./docs/new-projects.md) or try the [5-minute quickstart](./docs/quickstart-5min.md).
|
|
65
70
|
|
|
66
|
-
|
|
71
|
+
---
|
|
67
72
|
|
|
68
73
|
## See it in action
|
|
69
74
|
|
|
70
|
-
Here
|
|
75
|
+
Here is the everyday 3-step loop — create a scoped task, hand your AI focused context, and require a passing test before marking it done:
|
|
71
76
|
|
|
72
77
|
```bash
|
|
73
|
-
# 1.
|
|
74
|
-
geloforge task new --title "
|
|
78
|
+
# 1. Define what you're working on and activate it
|
|
79
|
+
npx geloforge task new --title "Check input validation" --activate
|
|
75
80
|
|
|
76
|
-
# 2. Build a
|
|
77
|
-
geloforge context --task TASK-0001 --map
|
|
81
|
+
# 2. Build a compact, budget-aware context packet (with symbol map)
|
|
82
|
+
npx geloforge context --task TASK-0001 --map
|
|
78
83
|
|
|
79
|
-
# 3. Run your
|
|
80
|
-
geloforge verify -- node --test
|
|
84
|
+
# 3. Run your test suite — saves verified evidence + checkpoint, then completes the task
|
|
85
|
+
npx geloforge verify --task TASK-0001 -- node --test
|
|
81
86
|
```
|
|
82
87
|
|
|
83
|
-
|
|
88
|
+
Want to record an intermediate check *without* closing the task yet? Run:
|
|
84
89
|
|
|
85
|
-
|
|
90
|
+
```bash
|
|
91
|
+
npx geloforge evidence capture --task TASK-0001 -- node --test
|
|
92
|
+
```
|
|
86
93
|
|
|
87
|
-
|
|
94
|
+
If a check fails or times out, GeloForge marks the evidence as `draft` (never `verified`) and keeps the task open until the real test passes.
|
|
88
95
|
|
|
89
|
-
|
|
90
|
-
| --- | --- |
|
|
91
|
-
| **Project memory** | Keep decisions, requirements, and current state in Markdown/YAML inside your repository. |
|
|
92
|
-
| **Safe onboarding** | Add GeloForge to an existing codebase with `adopt` or scaffold a new one with `init`. |
|
|
93
|
-
| **Tasks + evidence** | Create scoped tasks and capture real command results instead of relying on AI claims. |
|
|
94
|
-
| **Context + code map** | Send a smaller, more relevant project summary to your chosen AI assistant. |
|
|
95
|
-
| **Cross-agent handoff** | Pass structured, checkable work between sessions or tools. |
|
|
96
|
-
| **Portable Agent Skills** | Use open-format `SKILL.md` packages, with validation and progressive loading. |
|
|
97
|
-
| **Reviewed skill improvements** | Draft improvements from evidence, require explicit authorization, track versions, and roll back. |
|
|
98
|
-
| **Co-Pilot & checkpoints** | Get ranked next steps, human approval reminders, and resumable session notes. |
|
|
99
|
-
| **Cooperative multi-IDE work** | Claim tasks and scopes, see peer collision warnings, and avoid accidental overlapping work. |
|
|
100
|
-
| **Local MCP interface** | Run `geloforge mcp init` to set up Cursor, VS Code, Claude Code, or Gemini CLI with project-scoped tools. |
|
|
101
|
-
|
|
102
|
-
**Compatible workflow:** Codex, Claude Code, Gemini CLI, Antigravity, or any assistant that can read text you provide. GeloForge does not automatically operate or connect to those tools.
|
|
96
|
+
---
|
|
103
97
|
|
|
104
|
-
##
|
|
98
|
+
## What you can do
|
|
105
99
|
|
|
106
|
-
|
|
100
|
+
- **Coordinate across AI tools** — Claim a file scope (`task claim --scope src/`) so parallel Cursor, Codex, or Claude sessions warn each other before editing the same files.
|
|
101
|
+
- **Pause and resume without losing context** — Save lightweight checkpoints (`checkpoint create`) or structured handoffs (`handoff`) carrying exact evidence IDs and next actions.
|
|
102
|
+
- **Pin MCP tool definitions** — Lock configured stdio MCP servers to `.geloforge/mcp-lock.json` and run `npx geloforge mcp lock --check` to catch added, removed, or silently altered tool schemas.
|
|
103
|
+
- **Run bounded coding loops** — Use `npx geloforge loop run --config <file>` for a capped `implement → verify → review → fix` cycle where failing tests always block completion.
|
|
104
|
+
- **Analyze & suggest skills** — Run `npx geloforge skills suggest` (or `--scaffold-draft`) to match existing skills and stage quarantined drafts for owner review and Ed25519 approval.
|
|
105
|
+
- **Check setup health in one command** — Run `npx geloforge doctor` for pass/warn/fail diagnostics with exact fixes, or `npx geloforge hooks init` to add lightweight Git, Claude Code, or Gemini CLI checks.
|
|
106
|
+
- **Isolate parallel work cleanly** — Manage clean-checked Git worktrees under `worktrees/` with `npx geloforge worktree add`.
|
|
107
107
|
|
|
108
|
-
|
|
109
|
-
your-project/
|
|
110
|
-
├── brain/ # Decisions, constraints, and project state
|
|
111
|
-
├── tasks/ # What needs to be done
|
|
112
|
-
├── evidence/ # Recorded checks (created when needed)
|
|
113
|
-
├── handoffs/ # Session/agent transfers (created when needed)
|
|
114
|
-
└── .agents/skills/ # Optional reusable SKILL.md packages
|
|
115
|
-
```
|
|
108
|
+
---
|
|
116
109
|
|
|
117
|
-
|
|
110
|
+
## How it fits your project
|
|
118
111
|
|
|
119
|
-
|
|
112
|
+
Everything GeloForge adds lives in clear, human-readable folders — never touching your existing source code:
|
|
120
113
|
|
|
121
|
-
|
|
|
114
|
+
| Folder | What lives here (in plain English) |
|
|
122
115
|
| --- | --- |
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
| [Security policy](./SECURITY.md) | Risks, trust boundaries, and reporting |
|
|
129
|
-
| [Changelog](./CHANGELOG.md) | What's changed in each release |
|
|
116
|
+
| `brain/` | Your project's source of truth: architecture, constraints, decisions, and `current.yaml` state |
|
|
117
|
+
| `tasks/` | Scoped `TASK-NNNN` contracts with clear objectives, file scope, and acceptance criteria |
|
|
118
|
+
| `evidence/` | Tamper-evident `EVID-NNNN` logs of actual commands, exit codes, and outputs |
|
|
119
|
+
| `handoffs/` | Recovery checkpoints (`CHKPT-NNNN`) and cross-agent `HANDOFF-NNNN` notes |
|
|
120
|
+
| `.agents/skills/` | Reviewed, reusable agent workflows unlocked on demand to save tokens |
|
|
130
121
|
|
|
131
|
-
|
|
122
|
+
---
|
|
132
123
|
|
|
133
|
-
##
|
|
124
|
+
## Documentation
|
|
134
125
|
|
|
135
|
-
|
|
126
|
+
- [Beginner AI prompts](./docs/beginner-prompts.md) — ready-to-paste prompts to let your AI agent set up and run GeloForge
|
|
127
|
+
- [5-minute quickstart](./docs/quickstart-5min.md) — fastest hands-on walkthrough for beginners
|
|
128
|
+
- [CLI and MCP guide](./docs/advanced-usage.md) — full command reference, MCP init/lock, worktrees, and coding loops
|
|
129
|
+
- [Portable Agent Skills](./docs/portable-skills.md) — progressive disclosure, linting, and Ed25519 skill promotion
|
|
130
|
+
- [Creating a new project](./docs/new-projects.md) — templates and domain profiles (`web`, `automation`, `desktop`, etc.)
|
|
131
|
+
- [Known limitations](./docs/known-limitations.md) & [Security policy](./SECURITY.md) — threat model, zero-network guarantees, and secret redaction
|
|
132
|
+
- [Changelog](./CHANGELOG.md) & [GitHub releases](https://github.com/63L0/GeloForge/releases)
|
|
136
133
|
|
|
137
|
-
|
|
134
|
+
## Contributing
|
|
138
135
|
|
|
139
|
-
|
|
136
|
+
Issues, bug reports, and pull requests are welcome! When reporting an issue, please share your OS, Node.js version, and the exact command you ran via [GitHub Issues](https://github.com/63L0/GeloForge/issues).
|
|
140
137
|
|
|
141
|
-
|
|
138
|
+
For local test setup and pull request checks, read the [contribution guide](./CONTRIBUTING.md).
|
package/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.
|
|
1
|
+
0.9.0
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "GeloForge Staging Failure Delivery",
|
|
3
|
+
"active": false,
|
|
4
|
+
"nodes": [
|
|
5
|
+
{
|
|
6
|
+
"id": "11c36462-4033-40dd-8557-7f4f9c7ad010",
|
|
7
|
+
"name": "Staging Error Trigger",
|
|
8
|
+
"type": "n8n-nodes-base.errorTrigger",
|
|
9
|
+
"typeVersion": 1,
|
|
10
|
+
"position": [
|
|
11
|
+
0,
|
|
12
|
+
280
|
|
13
|
+
],
|
|
14
|
+
"parameters": {}
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
"id": "11c36462-4033-40dd-8557-7f4f9c7ad011",
|
|
18
|
+
"name": "Select staging failure IDs",
|
|
19
|
+
"type": "n8n-nodes-base.code",
|
|
20
|
+
"typeVersion": 2,
|
|
21
|
+
"position": [
|
|
22
|
+
230,
|
|
23
|
+
280
|
|
24
|
+
],
|
|
25
|
+
"parameters": {
|
|
26
|
+
"jsCode": "const valid = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value);\nconst event = $input.first().json;\nconst workflowId = String(event.workflow?.id ?? '');\nconst executionId = String(event.execution?.id ?? '');\nif (!valid(workflowId) || !valid(executionId)) return [];\nreturn [{ json: { workflowId, executionId } }];"
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
"id": "11c36462-4033-40dd-8557-7f4f9c7ad012",
|
|
31
|
+
"name": "Get saved staging execution",
|
|
32
|
+
"type": "n8n-nodes-base.n8n",
|
|
33
|
+
"typeVersion": 1,
|
|
34
|
+
"position": [
|
|
35
|
+
460,
|
|
36
|
+
280
|
|
37
|
+
],
|
|
38
|
+
"parameters": {
|
|
39
|
+
"resource": "execution",
|
|
40
|
+
"operation": "get",
|
|
41
|
+
"executionId": "={{ $json.executionId }}",
|
|
42
|
+
"options": {
|
|
43
|
+
"activeWorkflows": true
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
"onError": "continueRegularOutput"
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
"id": "11c36462-4033-40dd-8557-7f4f9c7ad013",
|
|
50
|
+
"name": "Project audit evidence",
|
|
51
|
+
"type": "n8n-nodes-base.code",
|
|
52
|
+
"typeVersion": 2,
|
|
53
|
+
"position": [
|
|
54
|
+
690,
|
|
55
|
+
280
|
|
56
|
+
],
|
|
57
|
+
"parameters": {
|
|
58
|
+
"jsCode": "const ids = $('Select staging failure IDs').first().json;\nconst raw = $input.first().json;\nconst revision = raw.workflowVersionId ?? raw.workflowData?.versionId;\nconst result = raw.data?.resultData;\nconst runData = result?.runData;\nconst workflowNodes = raw.workflowData?.nodes;\nconst nodes = Array.isArray(workflowNodes) ? workflowNodes.map(node => node?.name ?? null) : null;\nconst matches = String(raw.id ?? '') === ids.executionId &&\n String(raw.workflowId ?? '') === ids.workflowId && raw.status === 'error';\nconst delivery = {\n environment: 'staging',\n ...ids,\n execution: matches ? {\n id: ids.executionId,\n workflowId: ids.workflowId,\n revision,\n status: raw.status,\n nodes,\n executed: runData && typeof runData === 'object' && !Array.isArray(runData) ? Object.keys(runData) : null,\n failedNode: result?.lastNodeExecuted ?? null,\n } : null,\n};\nconst deliveryId = String($execution.id ?? '');\nif (!/^[A-Za-z0-9_-]{1,64}$/.test(deliveryId)) throw new Error('Expected a saved delivery ID.');\nconst fileName = `failure-${ids.workflowId}-${ids.executionId}-${deliveryId}.json`;\nreturn [{\n json: { fileName },\n binary: { data: {\n data: Buffer.from(JSON.stringify(delivery), 'utf8').toString('base64'),\n mimeType: 'application/json',\n fileName,\n } },\n}];"
|
|
59
|
+
}
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"id": "11c36462-4033-40dd-8557-7f4f9c7ad014",
|
|
63
|
+
"name": "Write audit delivery",
|
|
64
|
+
"type": "n8n-nodes-base.readWriteFile",
|
|
65
|
+
"typeVersion": 1,
|
|
66
|
+
"position": [
|
|
67
|
+
920,
|
|
68
|
+
280
|
|
69
|
+
],
|
|
70
|
+
"parameters": {
|
|
71
|
+
"operation": "write",
|
|
72
|
+
"dataPropertyName": "data",
|
|
73
|
+
"fileName": "={{ '/files/geloforge-inbox/' + $json.fileName }}",
|
|
74
|
+
"options": {}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
],
|
|
78
|
+
"pinData": {},
|
|
79
|
+
"connections": {
|
|
80
|
+
"Staging Error Trigger": {
|
|
81
|
+
"main": [
|
|
82
|
+
[
|
|
83
|
+
{
|
|
84
|
+
"node": "Select staging failure IDs",
|
|
85
|
+
"type": "main",
|
|
86
|
+
"index": 0
|
|
87
|
+
}
|
|
88
|
+
]
|
|
89
|
+
]
|
|
90
|
+
},
|
|
91
|
+
"Select staging failure IDs": {
|
|
92
|
+
"main": [
|
|
93
|
+
[
|
|
94
|
+
{
|
|
95
|
+
"node": "Get saved staging execution",
|
|
96
|
+
"type": "main",
|
|
97
|
+
"index": 0
|
|
98
|
+
}
|
|
99
|
+
]
|
|
100
|
+
]
|
|
101
|
+
},
|
|
102
|
+
"Get saved staging execution": {
|
|
103
|
+
"main": [
|
|
104
|
+
[
|
|
105
|
+
{
|
|
106
|
+
"node": "Project audit evidence",
|
|
107
|
+
"type": "main",
|
|
108
|
+
"index": 0
|
|
109
|
+
}
|
|
110
|
+
]
|
|
111
|
+
]
|
|
112
|
+
},
|
|
113
|
+
"Project audit evidence": {
|
|
114
|
+
"main": [
|
|
115
|
+
[
|
|
116
|
+
{
|
|
117
|
+
"node": "Write audit delivery",
|
|
118
|
+
"type": "main",
|
|
119
|
+
"index": 0
|
|
120
|
+
}
|
|
121
|
+
]
|
|
122
|
+
]
|
|
123
|
+
}
|
|
124
|
+
},
|
|
125
|
+
"settings": {
|
|
126
|
+
"executionOrder": "v1",
|
|
127
|
+
"saveDataErrorExecution": "none",
|
|
128
|
+
"saveDataSuccessExecution": "none",
|
|
129
|
+
"saveManualExecutions": false,
|
|
130
|
+
"saveExecutionProgress": false
|
|
131
|
+
}
|
|
132
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import { AUDIT_CREATOR } from "./autonomous-audit.mjs";
|
|
3
|
+
import { assertSafeWithinRoot, validateSlug } from "./path-safety.mjs";
|
|
4
|
+
import { loadProjectManifestAndState } from "./project-locator.mjs";
|
|
5
|
+
import { withProjectLock } from "./project-lock.mjs";
|
|
6
|
+
import { readRuntimeJson, sha256 } from "./runtime-files.mjs";
|
|
7
|
+
import { draftSkillFromExperience, loadVerifiedSourceBundle, proposeSkillUpdate } from "./skills-lifecycle.mjs";
|
|
8
|
+
import { reportArtifactPath } from "./staging-audit.mjs";
|
|
9
|
+
import { verifyStagingReport } from "./staging-evidence.mjs";
|
|
10
|
+
import { getTask, listTasks } from "./task-manager.mjs";
|
|
11
|
+
|
|
12
|
+
export function learnFromStagingAudits({ projectDir, harnessDir, patternId, skillName, step }) {
|
|
13
|
+
const read = () => {
|
|
14
|
+
const project = loadProjectManifestAndState(projectDir, harnessDir);
|
|
15
|
+
const patterns = new Map();
|
|
16
|
+
const warnings = [];
|
|
17
|
+
for (const { id } of listTasks({ ...project, harnessDir, status: "completed" }).tasks) {
|
|
18
|
+
const { record } = getTask({ ...project, harnessDir, taskId: id });
|
|
19
|
+
if (record.created_by !== AUDIT_CREATOR) continue;
|
|
20
|
+
const artifact = reportArtifactPath(project.projectPaths, id);
|
|
21
|
+
try {
|
|
22
|
+
const source = readRuntimeJson(projectDir, artifact);
|
|
23
|
+
if (!source) continue;
|
|
24
|
+
const report = verifyStagingReport(source, id);
|
|
25
|
+
const { evidenceList } = loadVerifiedSourceBundle({ projectDir, harnessDir, evidenceIds: record.evidence_refs });
|
|
26
|
+
const evidence = evidenceList.find(({ data }) => data.task_id === id && data.verified_by === "geloforge-staging-report" &&
|
|
27
|
+
data.artifacts.some(({ path, sha256: digest }) => path === artifact && digest));
|
|
28
|
+
if (!evidence) throw new Error("Missing evidence binding.");
|
|
29
|
+
for (const { workflowId, node, pattern, reference } of report.findings) {
|
|
30
|
+
// A node definition gives useful context, but it does not show a recurring failure.
|
|
31
|
+
if (!node || reference !== "failed-at") continue;
|
|
32
|
+
const key = sha256(JSON.stringify([workflowId, node, pattern])).slice(0, 16);
|
|
33
|
+
if (!patterns.has(key)) patterns.set(key, { id: key, workflowId, node, pattern, executions: new Map() });
|
|
34
|
+
patterns.get(key).executions.set(report.executionId, {
|
|
35
|
+
executionId: report.executionId, evidenceId: evidence.data.id, revision: report.execution.revision,
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
} catch {
|
|
39
|
+
warnings.push(`Excluded ${id} because its report or evidence could not be verified.`);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
const recurring = [...patterns.values()].filter((pattern) => pattern.executions.size >= 2)
|
|
43
|
+
.map(({ executions, ...pattern }) => ({ ...pattern, executions: [...executions.values()] }));
|
|
44
|
+
return { patterns: recurring, warnings };
|
|
45
|
+
};
|
|
46
|
+
if (!patternId) {
|
|
47
|
+
if (skillName || step) throw new Error("Use --pattern before drafting a skill.");
|
|
48
|
+
return read();
|
|
49
|
+
}
|
|
50
|
+
return withProjectLock(projectDir, () => {
|
|
51
|
+
validateSlug(skillName);
|
|
52
|
+
const result = read();
|
|
53
|
+
const pattern = result.patterns.find(({ id }) => id === patternId);
|
|
54
|
+
if (!pattern) throw new Error("Recurring pattern is missing or its evidence is no longer verified.");
|
|
55
|
+
const evidenceIds = pattern.executions.map(({ evidenceId }) => evidenceId);
|
|
56
|
+
const note = step ?? `For ${pattern.pattern} failures in workflow ${pattern.workflowId}, check whether ${pattern.node} is the failing node and confirm the saved execution and revision before recommending a fix.`;
|
|
57
|
+
const options = { projectDir, harnessDir, evidenceIds, skillName };
|
|
58
|
+
const active = assertSafeWithinRoot(projectDir, `.agents/skills/${skillName}/SKILL.md`);
|
|
59
|
+
const proposal = fs.existsSync(active)
|
|
60
|
+
? proposeSkillUpdate({ ...options, reason: "Review a recurring staging failure pattern.", appendNote: note })
|
|
61
|
+
: draftSkillFromExperience({
|
|
62
|
+
...options, title: "Investigate recurring n8n staging failures",
|
|
63
|
+
description: "Review the saved n8n staging execution and confirm recurring failures against linked evidence.",
|
|
64
|
+
steps: [note], tags: ["n8n", "staging", pattern.pattern], triggers: ["n8n", "audit", pattern.pattern],
|
|
65
|
+
});
|
|
66
|
+
return { pattern, proposalDir: proposal.proposalDir, nextAction: "Review the draft, then use the existing skill signing and promotion commands." };
|
|
67
|
+
});
|
|
68
|
+
}
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
/** Headless audit adapters run outside the project and receive a bounded context packet. */
|
|
2
|
+
import fs from "node:fs";
|
|
3
|
+
import os from "node:os";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
import { execFile } from "node:child_process";
|
|
6
|
+
import { hasSecretContent, isForbiddenSecretPath, isSameOrInside } from "./path-safety.mjs";
|
|
7
|
+
import { readRegularFile, sha256 } from "./runtime-files.mjs";
|
|
8
|
+
|
|
9
|
+
const ENV_KEYS = new Set([
|
|
10
|
+
"PATH", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "SYSTEMROOT", "WINDIR",
|
|
11
|
+
"TMP", "TEMP", "TMPDIR", "LANG", "LC_ALL",
|
|
12
|
+
]);
|
|
13
|
+
|
|
14
|
+
export function executableIdentity(executable) {
|
|
15
|
+
const stat = fs.lstatSync(executable);
|
|
16
|
+
if (!stat.isFile()) throw new Error("Audit provider must be a regular executable file.");
|
|
17
|
+
return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export function buildProviderEnv(provider, extraEnv = null) {
|
|
21
|
+
const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => ENV_KEYS.has(key.toUpperCase())));
|
|
22
|
+
if (provider === "gemini") env.GEMINI_CLI_TRUST_WORKSPACE = "true";
|
|
23
|
+
if (extraEnv && typeof extraEnv === "object") {
|
|
24
|
+
for (const [k, v] of Object.entries(extraEnv)) {
|
|
25
|
+
if (typeof v === "string") env[k] = v;
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
return env;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function resolveAuditProvider(spec, projectDir) {
|
|
32
|
+
if (!spec || !["codex", "gemini", "antigravity"].includes(spec.provider) ||
|
|
33
|
+
typeof spec.executable !== "string" || !path.isAbsolute(spec.executable) ||
|
|
34
|
+
hasSecretContent(spec.executable) || isForbiddenSecretPath(spec.executable)) {
|
|
35
|
+
throw new Error("Supply a provider and absolute CLI executable path.");
|
|
36
|
+
}
|
|
37
|
+
const executable = fs.realpathSync(spec.executable);
|
|
38
|
+
if (isSameOrInside(executable, fs.realpathSync(projectDir)) || /\.(cmd|bat|ps1)$/i.test(executable)) {
|
|
39
|
+
throw new Error("Use a native provider executable or Node.js entry point outside the project.");
|
|
40
|
+
}
|
|
41
|
+
const identity = executableIdentity(executable);
|
|
42
|
+
const bytes = readRegularFile(executable, 384 * 1024 * 1024);
|
|
43
|
+
if (!bytes || executableIdentity(executable) !== identity) {
|
|
44
|
+
throw new Error("Configured provider executable is unavailable or changed during authorization.");
|
|
45
|
+
}
|
|
46
|
+
const runner = { provider: spec.provider, executable, digest: sha256(bytes) };
|
|
47
|
+
return { runner, identity };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Spawns an approved provider CLI executable with filtered environment, closed stdin payload,
|
|
52
|
+
* and automatic private temp-dir cleanup.
|
|
53
|
+
*/
|
|
54
|
+
export function runProviderProcess({
|
|
55
|
+
runner: { provider, executable },
|
|
56
|
+
identity,
|
|
57
|
+
prompt,
|
|
58
|
+
cwd = null,
|
|
59
|
+
inputFile = "audit-input.txt",
|
|
60
|
+
buildArgs,
|
|
61
|
+
timeoutMs,
|
|
62
|
+
signal,
|
|
63
|
+
requireJson = true,
|
|
64
|
+
}) {
|
|
65
|
+
if (signal?.aborted) throw new Error("Audit worker is stopping.");
|
|
66
|
+
if (executableIdentity(executable) !== identity) {
|
|
67
|
+
throw new Error("Audit provider executable changed. Restart with the approved executable.");
|
|
68
|
+
}
|
|
69
|
+
if (hasSecretContent(prompt)) throw new Error("Audit inputs contain credential-like content.");
|
|
70
|
+
const tempDir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), "geloforge-audit-"));
|
|
71
|
+
const finalPath = path.join(tempDir, "response.json");
|
|
72
|
+
const promptPath = path.join(tempDir, inputFile);
|
|
73
|
+
const workCwd = cwd ? fs.realpathSync(cwd) : tempDir;
|
|
74
|
+
let child;
|
|
75
|
+
const args = buildArgs({ finalPath, promptPath, provider });
|
|
76
|
+
const env = buildProviderEnv(provider);
|
|
77
|
+
const stop = () => child?.kill("SIGKILL");
|
|
78
|
+
const promise = new Promise((resolve, reject) => {
|
|
79
|
+
try {
|
|
80
|
+
fs.writeFileSync(promptPath, prompt, { mode: 0o600, flag: "wx" });
|
|
81
|
+
const isNodeEntry = /\.[cm]?js$/i.test(executable);
|
|
82
|
+
child = execFile(isNodeEntry ? process.execPath : executable, isNodeEntry ? [executable, ...args] : args, {
|
|
83
|
+
cwd: workCwd, env, timeout: timeoutMs, maxBuffer: 512 * 1024, killSignal: "SIGKILL", windowsHide: true,
|
|
84
|
+
}, (err, stdout) => {
|
|
85
|
+
try {
|
|
86
|
+
if (err) {
|
|
87
|
+
throw new Error(err.killed ? "Audit provider stopped or exceeded its timeout." :
|
|
88
|
+
"Audit provider failed to start or returned an unsuccessful response.");
|
|
89
|
+
}
|
|
90
|
+
const text = provider === "codex" ? (readRegularFile(finalPath)?.toString("utf8") ?? "") : String(stdout ?? "");
|
|
91
|
+
if (provider === "codex") {
|
|
92
|
+
let parsed = null;
|
|
93
|
+
try {
|
|
94
|
+
parsed = JSON.parse(text);
|
|
95
|
+
} catch {
|
|
96
|
+
if (requireJson) throw new Error("Audit provider returned invalid JSON.");
|
|
97
|
+
resolve({ parsed: null, rawText: text });
|
|
98
|
+
return;
|
|
99
|
+
}
|
|
100
|
+
if (parsed?.error) throw new Error("Unsuccessful response envelope.");
|
|
101
|
+
resolve(requireJson ? parsed : { parsed, rawText: text });
|
|
102
|
+
return;
|
|
103
|
+
}
|
|
104
|
+
let envelope = null;
|
|
105
|
+
try {
|
|
106
|
+
envelope = JSON.parse(text);
|
|
107
|
+
} catch {
|
|
108
|
+
if (requireJson) throw new Error("Audit provider returned invalid JSON.");
|
|
109
|
+
resolve({ parsed: null, rawText: text });
|
|
110
|
+
return;
|
|
111
|
+
}
|
|
112
|
+
if (envelope?.error || (provider === "antigravity" && envelope?.status !== "SUCCESS")) {
|
|
113
|
+
throw new Error("Unsuccessful response envelope.");
|
|
114
|
+
}
|
|
115
|
+
const innerRaw = typeof envelope.response === "string" ? envelope.response : JSON.stringify(envelope.response ?? "");
|
|
116
|
+
try {
|
|
117
|
+
const innerParsed = JSON.parse(innerRaw);
|
|
118
|
+
resolve(requireJson ? innerParsed : { parsed: innerParsed, rawText: innerRaw });
|
|
119
|
+
} catch {
|
|
120
|
+
if (requireJson) throw new Error("Audit provider returned invalid JSON.");
|
|
121
|
+
resolve({ parsed: null, rawText: innerRaw });
|
|
122
|
+
}
|
|
123
|
+
} catch (error) {
|
|
124
|
+
reject(err ? error : error);
|
|
125
|
+
}
|
|
126
|
+
});
|
|
127
|
+
child.stdin?.on("error", () => {});
|
|
128
|
+
child.stdin?.end(prompt, "utf8");
|
|
129
|
+
signal?.addEventListener("abort", stop, { once: true });
|
|
130
|
+
} catch (err) {
|
|
131
|
+
reject(err);
|
|
132
|
+
}
|
|
133
|
+
}).finally(() => {
|
|
134
|
+
signal?.removeEventListener("abort", stop);
|
|
135
|
+
fs.rmSync(tempDir, { recursive: true, force: true, maxRetries: 2 });
|
|
136
|
+
});
|
|
137
|
+
return { pid: child?.pid, promise, stop };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
export function startAuditProvider(resolvedProvider, prompt, { timeoutMs, signal } = {}) {
|
|
141
|
+
const request = "Follow the reporting format in the audit input provided on stdin (also saved in audit-input.txt) and return only the requested JSON. Do not run shell commands or modify files.";
|
|
142
|
+
return runProviderProcess({
|
|
143
|
+
...resolvedProvider,
|
|
144
|
+
prompt,
|
|
145
|
+
cwd: null,
|
|
146
|
+
inputFile: "audit-input.txt",
|
|
147
|
+
timeoutMs,
|
|
148
|
+
signal,
|
|
149
|
+
requireJson: true,
|
|
150
|
+
buildArgs: ({ finalPath, provider }) => ({
|
|
151
|
+
codex: ["--ask-for-approval", "never", "exec", "--sandbox", "read-only", "--skip-git-repo-check",
|
|
152
|
+
"--ephemeral", "--ignore-user-config", "--output-last-message", finalPath, request],
|
|
153
|
+
gemini: ["--approval-mode=plan", "--output-format=json", "--prompt", request],
|
|
154
|
+
antigravity: ["--mode=plan", "--sandbox", "--output-format=json", "--print", request],
|
|
155
|
+
}[provider]),
|
|
156
|
+
});
|
|
157
|
+
}
|