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 CHANGED
@@ -1,73 +1,138 @@
1
1
  # GeloForge
2
2
 
3
- **Project memory and verification for AI-assisted development.**
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 results, and handoffs alongside your code.
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
  [![CI on main](https://github.com/63L0/GeloForge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/63L0/GeloForge/actions/workflows/ci.yml)
8
8
  [![npm version](https://img.shields.io/npm/v/geloforge?label=npm)](https://www.npmjs.com/package/geloforge)
9
+ [![Node 20+](https://img.shields.io/badge/node-20%2B-brightgreen)](https://nodejs.org/)
10
+ [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-blue)](./package.json)
9
11
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
10
12
 
11
13
  ![Two scripted MCP sessions demonstrating overlapping file leases, verified test evidence, and a signed skill approval.](./docs/media/geloforge-v06-demo.gif)
12
14
 
13
- [Case study and reproduction steps](./docs/dogfooding-v06.md)
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
- With Node.js 20+ and Git installed, run this from the root of an existing repository.
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
- The preview lists the files GeloForge would add. Adoption keeps existing project files intact. CI tests Node 20 and 22 on Linux, macOS, and Windows.
60
+ **Connect your AI editor and optional ambient hooks:**
26
61
 
27
- Run `npx geloforge mcp init` to configure Cursor, VS Code, Claude Code, and Gemini CLI for the project. Open the project in your client and review any MCP trust prompt.
62
+ ```bash
63
+ npx geloforge mcp init
64
+ npx geloforge hooks init --dry-run
65
+ ```
28
66
 
29
- [5-minute quickstart](./docs/quickstart-5min.md)
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
- ## Why GeloForge?
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
- When work moves between people or coding agents, the repository carries the decisions, task scope, and last verified check. The next session can load those records as focused context. GeloForge uses local files and has zero third-party runtime dependencies.
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
- Use the task ID printed by `task new` and your project’s own test command. A passing `verify` records the command result, saves a checkpoint, and completes the task. Use `npx geloforge evidence capture --task TASK-0001 -- node --test` to record a check and keep a task open.
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 changes.** Claim a file scope to catch overlapping leases between GeloForge clients before editing.
48
- - **Resume or hand off work.** Save checkpoints and share open tasks, verified evidence, and next actions with the next session.
49
- - **Reuse reviewed workflows.** Draft portable `SKILL.md` files from evidence, then use signed approvals to promote or roll back versions.
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
- | Path | Contents |
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/` | Decisions, constraints, architecture, and operational state |
56
- | `tasks/` | Scoped task contracts |
57
- | `evidence/` | Recorded command checks and their outcomes |
58
- | `handoffs/` | Handoff and checkpoint records |
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
- - [CLI and MCP guide](./docs/advanced-usage.md)
64
- - [Portable Agent Skills](./docs/portable-skills.md)
65
- - [Creating a new project](./docs/new-projects.md)
66
- - [Known limitations](./docs/known-limitations.md) and [security policy](./SECURITY.md)
67
- - [Changelog](./CHANGELOG.md) and [GitHub releases](https://github.com/63L0/GeloForge/releases)
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
- Report reproducible issues with your OS, Node version, and the command you ran. [Open an issue](https://github.com/63L0/GeloForge/issues)
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, see the [contribution guide](./CONTRIBUTING.md).
138
+ For local test setup and pull request checks, read the [contribution guide](./CONTRIBUTING.md).
package/VERSION CHANGED
@@ -1 +1 @@
1
- 0.7.0
1
+ 0.9.0
@@ -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
- export function startAuditProvider({ runner: { provider, executable }, identity }, prompt, { timeoutMs, signal } = {}) {
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) throw new Error("Audit provider executable changed. Restart with the approved executable.");
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
- // Prompt text goes in a private file. No project directory or staging credentials are given to the CLI.
44
- const cwd = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), "geloforge-audit-"));
45
- const finalPath = path.join(cwd, "response.json");
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 request = "Read audit-input.txt in the current directory. Follow its reporting format and return only the requested JSON. Use local file reads only.";
48
- const args = {
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(path.join(cwd, "audit-input.txt"), prompt, { mode: 0o600, flag: "wx" });
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: 256 * 1024, killSignal: "SIGKILL", windowsHide: true,
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
- const envelope = JSON.parse(text);
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 response = provider === "codex" ? envelope : JSON.parse(envelope.response);
74
- resolve(response);
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 : new Error("Audit provider returned invalid JSON."));
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(cwd, { recursive: true, force: true, maxRetries: 2 });
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
+ }