geloforge 0.7.0 → 0.9.1

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,151 @@
1
1
  # GeloForge
2
2
 
3
- **Project memory and verification for AI-assisted development.**
3
+ **Stop re-explaining your codebase — give every AI coding agent a shared, proof-verified memory.**
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, Claude Code, VS Code, Codex CLI, Gemini CLI, and Antigravity** without losing architectural context, risking overlapping edits, or trusting hallucinated `"tests pass!"` claims. GeloForge is a local-first, **zero-dependency** CLI and MCP server that keeps project memory, scoped tasks, real test receipts, pinned MCP tools, and portable skills right inside your Git 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
- ![Two scripted MCP sessions demonstrating overlapping file leases, verified test evidence, and a signed skill approval.](./docs/media/geloforge-v06-demo.gif)
13
+ **Zero databases. Zero cloud lock-in. Zero external runtime packages.** Just plain Markdown, YAML, and JSON schemas checked into your repository.
12
14
 
13
- [Case study and reproduction steps](./docs/dogfooding-v06.md)
15
+ ![Two scripted MCP sessions demonstrating overlapping file leases, verified test evidence, and a signed skill approval.](https://raw.githubusercontent.com/63L0/GeloForge/main/docs/media/geloforge-v06-demo.gif)
16
+
17
+ *[Read the full multi-session case study & reproduction steps →](./docs/dogfooding-v06.md)*
18
+
19
+ ---
20
+
21
+ ## Why GeloForge?
22
+
23
+ Every time you open a fresh AI chat or jump from one coding tool to another, hard-won decisions vanish. GeloForge gives your whole stack one deterministic **Second Brain**:
24
+
25
+ | Without GeloForge | With GeloForge |
26
+ | --- | --- |
27
+ | Re-explaining specs, architecture, and bugs in every chat | **Contextual BM25 & 3-Zone Packets:** Deterministic context (`brain/` + 15-lang symbol map + skills) in seconds |
28
+ | Agents claiming *"fixed!"* without running tests | **Evidence-Gated Tasks:** Real exit-code receipts (`verify` / `evidence capture`) block fake completion |
29
+ | Two AI tools silently overwriting each other's files | **Cooperative Leases & Worktrees:** Scope claims flag collisions early; Git worktrees isolate parallel work |
30
+ | Surprise MCP tool changes or unreviewed agent habits | **Pinned MCP Tools & Signed Skills:** `mcp lock --check` detects schema drift; skills stay quarantined until approved |
31
+ | Guesswork setup and unnoticed config drift | **Skill Advisor, Doctor & Hooks:** Analyze goals for skills, check health in one command, and run opt-in guardrails |
32
+
33
+ ---
14
34
 
15
35
  ## Quick start
16
36
 
17
- With Node.js 20+ and Git installed, run this from the root of an existing repository.
37
+ **Prerequisites:** Node.js 20+ and Git installed (`npx geloforge` works immediately — no global install required).
38
+
39
+ ### Option A — New to CLI? Paste this to your AI coding agent
40
+
41
+ Open **Cursor, Claude Code, Codex, Gemini CLI, or Antigravity** inside your project folder and paste:
42
+
43
+ ```text
44
+ 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.
45
+ ```
46
+
47
+ > Want ready-to-paste prompts for tasks, tests, checkpoints, and skill drafting? See **[Beginner AI Prompts](./docs/beginner-prompts.md)**.
48
+
49
+ ### Option B — Run the CLI yourself (30 seconds)
18
50
 
19
51
  ```bash
52
+ # 1. Preview safely without touching existing code
20
53
  npx geloforge adopt --dry-run
54
+
55
+ # 2. Onboard your repo + run one-command health diagnostics
21
56
  npx geloforge adopt
22
57
  npx geloforge status
23
- ```
58
+ npx geloforge doctor
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
+ # 3. Connect AI editors (Cursor, VS Code, Claude Code, Gemini CLI, or --client antigravity)
61
+ npx geloforge mcp init
26
62
 
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.
63
+ # 4. Preview optional ambient guardrails (Git pre-commit, Claude Stop, Gemini AfterAgent)
64
+ npx geloforge hooks init --dry-run
65
+ ```
28
66
 
29
- [5-minute quickstart](./docs/quickstart-5min.md)
67
+ Starting from scratch instead? Scaffold an isolated project with one of 5 domain profiles (`web`, `desktop`, `mobile`, `automation`, `ai-system`):
30
68
 
31
- ## Why GeloForge?
69
+ ```bash
70
+ npx geloforge init --name "My Web App" --profile web --git
71
+ ```
72
+
73
+ > Guides: [5-minute quickstart](./docs/quickstart-5min.md) · [Creating a new project](./docs/new-projects.md)
32
74
 
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.
75
+ ---
34
76
 
35
77
  ## See it in action
36
78
 
79
+ Use one repeatable proof-backed workflow from goal discovery through verified completion:
80
+
37
81
  ```bash
38
- npx geloforge task new --title "Check input validation" --activate
39
- npx geloforge context --task TASK-0001 --map
82
+ # 1. Discover matching skills or stage a quarantined draft for your goal
83
+ npx geloforge skills suggest --goal "Harden checkout webhook validation"
84
+
85
+ # 2. Create a scoped task and compile a budget-aware context packet + symbol map
86
+ npx geloforge task new --title "Harden checkout webhook validation" --activate
87
+ npx geloforge context --task TASK-0001 --map --skills
88
+
89
+ # 3. Capture intermediate test receipts (without closing the task yet)
90
+ npx geloforge evidence capture --task TASK-0001 -- node --test
91
+
92
+ # 4. Verify & complete — fails closed as `draft` if tests fail; saves checkpoint on pass
40
93
  npx geloforge verify --task TASK-0001 -- node --test
41
94
  ```
42
95
 
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.
96
+ If any check fails or times out, GeloForge records `draft` evidence (never `verified`) and refuses to mark the task verified until real checks pass.
97
+
98
+ ---
44
99
 
45
100
  ## What you can do
46
101
 
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.
102
+ ### Smart Memory & Token-Efficient Context
103
+ - **Contextual BM25 & 3-Zone Context Compiler:** `npx geloforge context` ranks Markdown headings and docs with zero-dependency BM25, anchors critical policies/conflicts at edge positions to fight context rot, and supports `quick`/`working`/`deep` budgets, `--from-diff`, `--exclude-unverified`, and opt-in `--cache`.
104
+ - **15+ Language Codebase Symbol Map:** Add `--map` to extract `.gitignore`-aware function/class outlines and 1-hop import boosts (JS/TS, Python, Go, Rust, Java, C#, Kotlin, C/C++, Shell, SQL, Markdown, JSON, YAML, TOML) while hard-blocking `.env*`, keys, binaries, and build folders.
105
+ - **Session Checkpoints & Verified Cross-Agent Handoffs:** Save `CHKPT-NNNN` resume notes (`checkpoint create|resume`) and inspect `HANDOFF-NNNN` packets (`handoff --inspect`) that separate audited `EVID-*` receipts from `unverified_claims` and flag Git HEAD drift.
106
+
107
+ ### Verification, Security & Governance
108
+ - **Command-Backed Evidence & Secret Redaction:** `verify` and `evidence capture` spawn checks directly (`shell: false`), redact detected secrets, and let `task done --require-evidence` block unverified completion.
109
+ - **MCP Tool-Surface Pinning (`mcp lock`):** Snapshot configured stdio MCP server tool schemas to `.geloforge/mcp-lock.json` via canonical SHA-256 digests and run `npx geloforge mcp lock --check` to catch silent tool poisoning or schema drift.
110
+ - **Signed Governance & Zero-Network Reliability:** Gate ADR/constraint edits (`proposal preview|sign|promote`) and skill promotions on pinned Ed25519 keys, transactional rollback journals, cross-process `.state.lock` protection, zero external network calls, and offline regression evals (`npm run eval`).
111
+
112
+ ### Skills, MCP & Multi-Agent Workflows
113
+ - **Project/Goal Skills Advisor (`skills suggest`):** Inspect project markers, active tasks, and `--goal` strings to recommend matching [agentskills.io](https://agentskills.io)-compatible `SKILL.md` workflows, stage quarantined drafts (`--scaffold-draft`), statically security-lint (`skills lint`), and promote/rollback safely (`skills promote|rollback`) with progressive Tier 0/1/2 token loading.
114
+ - **Zero-Dependency MCP Server (`geloforge mcp`):** 6 project-confined MCP tools (`geloforge_status`, `geloforge_recommend`, `geloforge_context`, `geloforge_task`, `geloforge_checkpoint`, `geloforge_skills`) with `--read-only` support, `input_examples`, and self-correcting error hints.
115
+ - **Bounded Coding Loops & Opt-In Staging Audits:** Run capped `implement → verify → review → fix` cycles (`loop run`) gated by fail-closed `policy_checks`, or automate staging error audits (`autonomous watch|learn`) with n8n failure delivery and multi-provider adapters (`codex`, `gemini`, `antigravity`).
116
+ - **Cooperative File Leases & Git Worktrees:** Claim scopes (`task claim --scope src/`) so parallel editors warn on overlapping work automatically, and manage isolated checkouts with `worktree add|remove`.
117
+
118
+ ### Diagnostics & Ambient Guardrails
119
+ - **One-Command Diagnostics (`geloforge doctor`):** Audit Node version, Second Brain schemas (`12` strict JSON schemas), Git state, peer leases, skill lint, MCP lock drift, and hook status with actionable fix commands.
120
+ - **Opt-In Ambient Hooks (`geloforge hooks init`):** Add lightweight Git `pre-commit` validation/lock checks plus Claude Code (`hooks.Stop`) and Gemini CLI (`hooks.AfterAgent`) reminders while preserving existing settings — zero background daemons.
121
+ - **Human-in-the-Loop Co-Pilot (`geloforge recommend`):** Surface ranked next actions, pending skill drafts, open conflicts (`CONF-NNNN`), and active peer leases without auto-executing destructive edits.
122
+
123
+ ---
50
124
 
51
125
  ## How it fits your project
52
126
 
53
- | Path | Contents |
127
+ Everything GeloForge creates lives in readable project folders — never modifying your application source code:
128
+
129
+ | Folder | Purpose |
54
130
  | --- | --- |
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 |
131
+ | `brain/` | Source of truth: PRD, constraints, architecture decisions (`ADR-*`), and `state/current.yaml` |
132
+ | `tasks/` | Scoped `TASK-NNNN` contracts with objectives, file scope, and acceptance criteria |
133
+ | `evidence/` | Tamper-evident `EVID-NNNN` logs of real commands, exit codes, and redacted outputs |
134
+ | `handoffs/` | Recovery checkpoints (`CHKPT-NNNN`) and structured cross-agent `HANDOFF-NNNN` records |
135
+ | `.agents/skills/` | Reviewed reusable workflows unlocked on demand (`proposals/skills/` isolates unapproved drafts) |
136
+
137
+ ---
60
138
 
61
139
  ## Documentation
62
140
 
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)
141
+ - [Beginner AI prompts](./docs/beginner-prompts.md) — ready-to-paste prompts so any AI agent can run GeloForge for you
142
+ - [5-minute quickstart](./docs/quickstart-5min.md) — fastest hands-on CLI walkthrough
143
+ - [CLI and MCP guide](./docs/advanced-usage.md) — full command flags, `mcp lock`, `loop run`, worktrees, and staging audits
144
+ - [Portable Agent Skills](./docs/portable-skills.md) — progressive disclosure, static security lint, and Ed25519 promotion
145
+ - [Creating a new project](./docs/new-projects.md) — greenfield starter templates and 5 domain profiles
146
+ - [Known limitations](./docs/known-limitations.md) & [Security policy](./SECURITY.md) — trust boundaries and offline safety model
147
+ - [Changelog](./CHANGELOG.md) & [GitHub releases](https://github.com/63L0/GeloForge/releases)
68
148
 
69
149
  ## Contributing
70
150
 
71
- Report reproducible issues with your OS, Node version, and the command you ran. [Open an issue](https://github.com/63L0/GeloForge/issues)
72
-
73
- For local setup and pull request checks, see the [contribution guide](./CONTRIBUTING.md).
151
+ Issues, bug reports, and pull requests are welcome! Share your OS, Node.js version, and command output via [GitHub Issues](https://github.com/63L0/GeloForge/issues). For local tests and PR checks, read [CONTRIBUTING.md](./CONTRIBUTING.md).
package/VERSION CHANGED
@@ -1 +1 @@
1
- 0.7.0
1
+ 0.9.1
@@ -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
+ }