geloforge 0.7.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 +91 -26
- package/VERSION +1 -1
- package/core/audit-provider.mjs +91 -22
- package/core/coding-loop.mjs +500 -0
- package/core/compatibility.json +1 -1
- package/core/context-cache.mjs +4 -3
- package/core/context-compiler.mjs +77 -10
- package/core/doctor.mjs +319 -0
- package/core/hooks-init.mjs +245 -0
- package/core/mcp-init.mjs +3 -2
- package/core/mcp-lock.mjs +488 -0
- package/core/mcp-server.mjs +70 -8
- package/core/project-lock.mjs +49 -17
- package/core/project-status.mjs +42 -0
- package/core/skills-advisor.mjs +944 -0
- package/core/text-utils.mjs +63 -5
- package/package.json +2 -1
- package/scripts/geloforge.mjs +420 -7
package/README.md
CHANGED
|
@@ -1,73 +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
|
-
GeloForge is a local CLI that stores decisions, scoped tasks, command
|
|
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.
|
|
6
6
|
|
|
7
7
|
[](https://github.com/63L0/GeloForge/actions/workflows/ci.yml)
|
|
8
8
|
[](https://www.npmjs.com/package/geloforge)
|
|
9
|
+
[](https://nodejs.org/)
|
|
10
|
+
[](./package.json)
|
|
9
11
|
[](./LICENSE)
|
|
10
12
|
|
|
11
13
|

|
|
12
14
|
|
|
13
|
-
[
|
|
15
|
+
*[Read the full multi-session case study & reproduction steps →](./docs/dogfooding-v06.md)*
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Why GeloForge?
|
|
20
|
+
|
|
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
|
+
| --- | --- |
|
|
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
|
+
|
|
30
|
+
---
|
|
14
31
|
|
|
15
32
|
## Quick start
|
|
16
33
|
|
|
17
|
-
|
|
34
|
+
**Prerequisites:** Node.js 20+ and Git installed. Pick whichever path feels easier:
|
|
35
|
+
|
|
36
|
+
### Option A — New to CLI? Paste this to your AI coding agent
|
|
37
|
+
|
|
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
|
+
```
|
|
43
|
+
|
|
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:
|
|
18
49
|
|
|
19
50
|
```bash
|
|
51
|
+
# 1. Preview what files will be added (touches nothing)
|
|
20
52
|
npx geloforge adopt --dry-run
|
|
53
|
+
|
|
54
|
+
# 2. Add GeloForge Second Brain alongside your code + check health
|
|
21
55
|
npx geloforge adopt
|
|
22
56
|
npx geloforge status
|
|
57
|
+
npx geloforge doctor
|
|
23
58
|
```
|
|
24
59
|
|
|
25
|
-
|
|
60
|
+
**Connect your AI editor and optional ambient hooks:**
|
|
26
61
|
|
|
27
|
-
|
|
62
|
+
```bash
|
|
63
|
+
npx geloforge mcp init
|
|
64
|
+
npx geloforge hooks init --dry-run
|
|
65
|
+
```
|
|
28
66
|
|
|
29
|
-
|
|
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.
|
|
30
68
|
|
|
31
|
-
|
|
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).
|
|
32
70
|
|
|
33
|
-
|
|
71
|
+
---
|
|
34
72
|
|
|
35
73
|
## See it in action
|
|
36
74
|
|
|
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:
|
|
76
|
+
|
|
37
77
|
```bash
|
|
78
|
+
# 1. Define what you're working on and activate it
|
|
38
79
|
npx geloforge task new --title "Check input validation" --activate
|
|
80
|
+
|
|
81
|
+
# 2. Build a compact, budget-aware context packet (with symbol map)
|
|
39
82
|
npx geloforge context --task TASK-0001 --map
|
|
83
|
+
|
|
84
|
+
# 3. Run your test suite — saves verified evidence + checkpoint, then completes the task
|
|
40
85
|
npx geloforge verify --task TASK-0001 -- node --test
|
|
41
86
|
```
|
|
42
87
|
|
|
43
|
-
|
|
88
|
+
Want to record an intermediate check *without* closing the task yet? Run:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
npx geloforge evidence capture --task TASK-0001 -- node --test
|
|
92
|
+
```
|
|
93
|
+
|
|
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.
|
|
95
|
+
|
|
96
|
+
---
|
|
44
97
|
|
|
45
98
|
## What you can do
|
|
46
99
|
|
|
47
|
-
- **Coordinate
|
|
48
|
-
- **
|
|
49
|
-
- **
|
|
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
|
+
|
|
108
|
+
---
|
|
50
109
|
|
|
51
110
|
## How it fits your project
|
|
52
111
|
|
|
53
|
-
|
|
112
|
+
Everything GeloForge adds lives in clear, human-readable folders — never touching your existing source code:
|
|
113
|
+
|
|
114
|
+
| Folder | What lives here (in plain English) |
|
|
54
115
|
| --- | --- |
|
|
55
|
-
| `brain/` |
|
|
56
|
-
| `tasks/` | Scoped
|
|
57
|
-
| `evidence/` |
|
|
58
|
-
| `handoffs/` |
|
|
59
|
-
| `.agents/skills/` | Reviewed, reusable agent workflows |
|
|
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 |
|
|
121
|
+
|
|
122
|
+
---
|
|
60
123
|
|
|
61
124
|
## Documentation
|
|
62
125
|
|
|
63
|
-
- [
|
|
64
|
-
- [
|
|
65
|
-
- [
|
|
66
|
-
- [
|
|
67
|
-
- [
|
|
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)
|
|
68
133
|
|
|
69
134
|
## Contributing
|
|
70
135
|
|
|
71
|
-
|
|
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).
|
|
72
137
|
|
|
73
|
-
For local setup and pull request checks,
|
|
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
|
package/core/audit-provider.mjs
CHANGED
|
@@ -11,12 +11,23 @@ const ENV_KEYS = new Set([
|
|
|
11
11
|
"TMP", "TEMP", "TMPDIR", "LANG", "LC_ALL",
|
|
12
12
|
]);
|
|
13
13
|
|
|
14
|
-
function executableIdentity(executable) {
|
|
14
|
+
export function executableIdentity(executable) {
|
|
15
15
|
const stat = fs.lstatSync(executable);
|
|
16
16
|
if (!stat.isFile()) throw new Error("Audit provider must be a regular executable file.");
|
|
17
17
|
return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
|
|
18
18
|
}
|
|
19
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
|
+
|
|
20
31
|
export function resolveAuditProvider(spec, projectDir) {
|
|
21
32
|
if (!spec || !["codex", "gemini", "antigravity"].includes(spec.provider) ||
|
|
22
33
|
typeof spec.executable !== "string" || !path.isAbsolute(spec.executable) ||
|
|
@@ -36,53 +47,111 @@ export function resolveAuditProvider(spec, projectDir) {
|
|
|
36
47
|
return { runner, identity };
|
|
37
48
|
}
|
|
38
49
|
|
|
39
|
-
|
|
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
|
+
}) {
|
|
40
65
|
if (signal?.aborted) throw new Error("Audit worker is stopping.");
|
|
41
|
-
if (executableIdentity(executable) !== identity)
|
|
66
|
+
if (executableIdentity(executable) !== identity) {
|
|
67
|
+
throw new Error("Audit provider executable changed. Restart with the approved executable.");
|
|
68
|
+
}
|
|
42
69
|
if (hasSecretContent(prompt)) throw new Error("Audit inputs contain credential-like content.");
|
|
43
|
-
|
|
44
|
-
const
|
|
45
|
-
const
|
|
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;
|
|
46
74
|
let child;
|
|
47
|
-
const
|
|
48
|
-
const
|
|
49
|
-
codex: ["--ask-for-approval", "never", "exec", "--sandbox", "read-only", "--skip-git-repo-check",
|
|
50
|
-
"--ephemeral", "--ignore-user-config", "--output-last-message", finalPath, request],
|
|
51
|
-
gemini: ["--approval-mode=plan", "--output-format=json", "--prompt", request],
|
|
52
|
-
antigravity: ["--mode=plan", "--sandbox", "--output-format=json", "--print", request],
|
|
53
|
-
}[provider];
|
|
54
|
-
const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => ENV_KEYS.has(key.toUpperCase())));
|
|
75
|
+
const args = buildArgs({ finalPath, promptPath, provider });
|
|
76
|
+
const env = buildProviderEnv(provider);
|
|
55
77
|
const stop = () => child?.kill("SIGKILL");
|
|
56
78
|
const promise = new Promise((resolve, reject) => {
|
|
57
79
|
try {
|
|
58
|
-
fs.writeFileSync(
|
|
80
|
+
fs.writeFileSync(promptPath, prompt, { mode: 0o600, flag: "wx" });
|
|
59
81
|
const isNodeEntry = /\.[cm]?js$/i.test(executable);
|
|
60
82
|
child = execFile(isNodeEntry ? process.execPath : executable, isNodeEntry ? [executable, ...args] : args, {
|
|
61
|
-
cwd, env, timeout: timeoutMs, maxBuffer:
|
|
83
|
+
cwd: workCwd, env, timeout: timeoutMs, maxBuffer: 512 * 1024, killSignal: "SIGKILL", windowsHide: true,
|
|
62
84
|
}, (err, stdout) => {
|
|
63
85
|
try {
|
|
64
86
|
if (err) {
|
|
65
87
|
throw new Error(err.killed ? "Audit provider stopped or exceeded its timeout." :
|
|
66
88
|
"Audit provider failed to start or returned an unsuccessful response.");
|
|
67
89
|
}
|
|
68
|
-
const text = provider === "codex" ? readRegularFile(finalPath)?.toString("utf8") : stdout;
|
|
69
|
-
|
|
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
|
+
}
|
|
70
112
|
if (envelope?.error || (provider === "antigravity" && envelope?.status !== "SUCCESS")) {
|
|
71
113
|
throw new Error("Unsuccessful response envelope.");
|
|
72
114
|
}
|
|
73
|
-
const
|
|
74
|
-
|
|
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
|
+
}
|
|
75
123
|
} catch (error) {
|
|
76
|
-
reject(err ? error :
|
|
124
|
+
reject(err ? error : error);
|
|
77
125
|
}
|
|
78
126
|
});
|
|
127
|
+
child.stdin?.on("error", () => {});
|
|
128
|
+
child.stdin?.end(prompt, "utf8");
|
|
79
129
|
signal?.addEventListener("abort", stop, { once: true });
|
|
80
130
|
} catch (err) {
|
|
81
131
|
reject(err);
|
|
82
132
|
}
|
|
83
133
|
}).finally(() => {
|
|
84
134
|
signal?.removeEventListener("abort", stop);
|
|
85
|
-
fs.rmSync(
|
|
135
|
+
fs.rmSync(tempDir, { recursive: true, force: true, maxRetries: 2 });
|
|
86
136
|
});
|
|
87
137
|
return { pid: child?.pid, promise, stop };
|
|
88
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
|
+
}
|