@fusengine/harness 0.1.12 → 0.1.13

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.
Files changed (2) hide show
  1. package/README.md +106 -41
  2. package/package.json +111 -23
package/README.md CHANGED
@@ -1,68 +1,133 @@
1
1
  # @fusengine/harness
2
2
 
3
- Harness-agnostic toolkit for AI coding agents. One package, modular subpaths,
4
- **Bun-native** (the `exports` map points at the TypeScript source — no build step).
3
+ A **harness-agnostic enforcement engine** for AI coding agents. It ports the
4
+ guard/gate logic of a Claude Code plugin into one reusable, **Bun-native** npm
5
+ package that runs on **any** harness — Claude Code, OpenAI Codex, Cursor, Cline,
6
+ Gemini CLI — plus a cli-mode fallback for Aider / Windsurf / OpenHands.
5
7
 
6
- It splits cleanly into a **pure policy core** (no harness coupling) and **thin
7
- adapters** that wire it into a specific harness's hook system.
8
+ It splits cleanly into a **pure policy core** (no harness coupling, fully tested)
9
+ and **thin per-harness adapters** that map a hook payload to the policy and back
10
+ to that harness's native response.
8
11
 
9
- ## Why
10
-
11
- The same guard logic (file-size limits, APEX freshness, framework detection,
12
- git guards, project memory) was duplicated across Python + TypeScript hooks and
13
- bound to one harness. This package is the single, tested source of truth — and
14
- it knows which harness it's running in.
12
+ ```
13
+ detect → init (pre+post hooks) → `harness hook` → guards + APEX gates → native deny/ask
14
+ ```
15
15
 
16
16
  ## Install
17
17
 
18
18
  ```sh
19
- bun add @fusengine/harness
19
+ npm i -g @fusengine/harness # for the CLI (harness init/hook/check)
20
+ # or, as a library:
21
+ bun add @fusengine/harness # Bun reads the TS source directly — no build step
20
22
  ```
21
23
 
22
- ## Modules
24
+ ## Quickstart
23
25
 
24
- | Subpath | What |
25
- |---------|------|
26
- | `@fusengine/harness/detect` | `detectHarness()` / `detectMode()` — Claude Code, Codex, Cursor, Cline, Gemini, opencode, Windsurf, Copilot, Aider, Kiro, Goose, Amp (env signals + `AGENT`/`AI_AGENT` standards). `mode` is `hook` or `cli`. |
27
- | `@fusengine/harness/policy` | `evaluate(ctx)` → `{ decision, message }`; `evaluateFileSize`, `detectProjectType`, `detectFramework`, git/install guard patterns. |
28
- | `@fusengine/harness/config` | `resolveTtlSec` / `resolveMaxLines` (env-driven, robust parse), `ttlLabel`, `splitTarget`. |
29
- | `@fusengine/harness/memory` | Per-project "never reproduce" lessons: throttle state, multi-project registry by git root. |
30
- | `@fusengine/harness/cache` | `compactMarkdown`, `queryHash`, `jaccardSimilar`, atomic JSON I/O, MCP response extraction. |
31
- | `@fusengine/harness/freshness` | `isDocConsulted` (Context7 + Exa), trivial-edit counter. |
32
- | `@fusengine/harness/refs` | Frontmatter parsing, glob→regex, SOLID reference scoring/routing. |
33
- | `@fusengine/harness/state` | Directory locks, daily APEX state, task.json helpers. |
34
- | `@fusengine/harness/statusline` | Formatters, ANSI colors, progress/gradient bars. |
35
- | `@fusengine/harness/adapters/claude` | Claude Code adapter: read stdin → policy → `hookSpecificOutput`. |
36
-
37
- ## Usage
26
+ ```sh
27
+ cd your-project
28
+ harness init # detects the harness, writes its pre+post hooks
29
+ export FUSE_HARNESS_REFS=.claude/skills # (optional) activate the SOLID-read gate
30
+ ```
38
31
 
39
- ```ts
40
- import { detectHarness, detectMode } from "@fusengine/harness/detect";
41
- import { evaluate } from "@fusengine/harness/policy";
32
+ That's it. `init` writes the wiring file for the detected harness
33
+ (`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
34
+ `.gemini/settings.json`, or `.clinerules/hooks/PreToolUse`+`PostToolUse`), each
35
+ pointing at `harness hook <id>`. From then on every tool-use is gated, and the
36
+ session activity (agents run, docs consulted, refs read) is recorded
37
+ automatically under `<harness-dir>/harness/`.
42
38
 
43
- const { id, mode } = detectHarness(); // e.g. { id: "cursor", mode: "hook" }
39
+ ### CLI
44
40
 
45
- const verdict = evaluate({ tool: "Write", filePath: "src/big.ts", content });
46
- if (verdict.decision === "deny") console.error(verdict.message);
41
+ | Command | What it does |
42
+ |---------|--------------|
43
+ | `harness init [id]` | Write the pre+post hook wiring for the detected (or named) harness. |
44
+ | `harness hook <id>` | Runtime: read a hook payload on stdin, gate (pre) or record (post), print the native response. (Hooks call this — you don't.) |
45
+ | `harness check` | cli-mode: check staged files in a pre-commit step, exit non-zero on a violation. For harnesses without hooks. |
46
+
47
+ cli-mode (Aider / Windsurf / OpenHands), as a pre-commit step:
48
+
49
+ ```sh
50
+ # .husky/pre-commit
51
+ npx harness check
47
52
  ```
48
53
 
49
- Claude Code hook (thin adapter):
54
+ ## What it enforces
55
+
56
+ Ten portable guards + the APEX gate chain, all evaluated before a tool runs:
57
+
58
+ | Guard / gate | Fires on |
59
+ |---|---|
60
+ | file-size (SOLID) | a code file over `FUSE_SOLID_MAX_LINES` (default 100) |
61
+ | git | destructive git (`push --force`, `reset --hard`, …) |
62
+ | bash-write | `python3 -c` / `sed -i` / redirects to code files |
63
+ | install | `npm/pip/brew/...` installs (asks) |
64
+ | security | `rm -rf /`, fork bombs, `curl \| sh`; `sudo` (asks) |
65
+ | interface-separation | top-level interface/type/protocol in a component/controller |
66
+ | protected-path | edits to `.claude/plugins\|logs\|cache`, `.git/` |
67
+ | APEX freshness | `explore-codebase` + `research-expert` not run within the window |
68
+ | APEX doc-consulted | Context7 **and** Exa not consulted this session |
69
+ | APEX solid-read | required SOLID refs (from `FUSE_HARNESS_REFS`) not read |
70
+ | brainstorm | creating a new file without brainstorming (when flagged) |
71
+ | MCP verbosity / cache | caps exa `numResults`; serves a fresh cached MCP/WebFetch result |
72
+
73
+ A trivial-edit fast path lets a few tiny (< 5-line, non-`replace_all`) edits
74
+ through per window without the full APEX gates.
75
+
76
+ ### Environment
77
+
78
+ | Var | Effect |
79
+ |---|---|
80
+ | `FUSE_SOLID_MAX_LINES` | SOLID file-size limit (default `100`). |
81
+ | `FUSE_HARNESS_REFS` | Directory of `.md` SOLID references → activates `solidReadGate`. |
82
+ | `FUSE_ENFORCE_TTL_SEC` | APEX freshness window in seconds. |
83
+ | `FUSE_LESSONS_THROTTLE_MIN` | Lessons-injection throttle (memory module). |
84
+
85
+ ## Library usage
50
86
 
51
87
  ```ts
52
- import { readClaudeInput, fileSizeGuard } from "@fusengine/harness/adapters/claude";
88
+ import { detectHarness } from "@fusengine/harness/detect";
89
+ import { evaluate } from "@fusengine/harness/policy";
90
+ import { gate } from "@fusengine/harness/runtime";
91
+
92
+ const { id, mode } = detectHarness(); // { id: "cursor", mode: "hook" }
53
93
 
54
- const deny = fileSizeGuard(await readClaudeInput());
55
- if (deny) { console.log(deny); process.exit(2); }
94
+ // stateless guards (file-size, git, security, …)
95
+ const verdict = evaluate({ tool: "Write", filePath: "src/big.ts", content });
96
+ if (verdict.decision !== "allow") console.error(verdict.prompt?.reason);
97
+
98
+ // full gate (stateless + stateful APEX, fed from the session track)
99
+ const prompt = await gate({ sessionId, framework: "react", tool: "Write",
100
+ filePath: "src/Button.tsx", content, now: Date.now(), trackFile });
56
101
  ```
57
102
 
58
- Harness without hooks (Aider/Windsurf/OpenHands) → `cli` mode: run the same
59
- `evaluate()` from a pre-commit step instead.
103
+ The `Prompt` it returns (`{ kind: "block" | "ask" | "inform", title, reason, actions? }`)
104
+ is portable; each adapter maps it to the harness's native shape.
105
+
106
+ ## Subpath exports
107
+
108
+ | Subpath | What |
109
+ |---------|------|
110
+ | `./detect` | `detectHarness()` / `detectMode()` — 13 harnesses, `hook` vs `cli`. |
111
+ | `./policy` | `evaluate(ctx)`, the 10 guards, `evaluateApex`, framework detection. |
112
+ | `./runtime` | `handleHook`, `gate`, `recordActivity`, `activityFor`, per-harness storage + MCP intercept. |
113
+ | `./tracking` | Session track: `recordAgent/Doc/RefRead`, `agentsFresh`, trivial-edit counter. |
114
+ | `./refs` | Frontmatter parse, `loadRefs(dir)`, SOLID ref scoring/routing. |
115
+ | `./prompt` | The portable `Prompt` type + `formatPrompt`. |
116
+ | `./cache` | MCP/WebFetch cache: key, lookup/store, compaction, response extraction. |
117
+ | `./memory` | Per-project "never reproduce" lessons. |
118
+ | `./config` `./util` `./state` `./statusline` `./freshness` `./init` `./cli` | env config, project-root, locks, statusline, doc-freshness, wiring templates, staged checks. |
119
+ | `./adapters/{claude,codex,cursor,cline,gemini}` | Thin per-harness adapters. |
120
+
121
+ See [`docs/`](./docs) for per-module guides, and run `bun run docs:api` for the
122
+ generated typedoc API reference.
60
123
 
61
124
  ## Develop
62
125
 
63
126
  ```sh
64
- bun test # test suite
65
- bunx tsc --noEmit # typecheck
127
+ bun test # 105 tests
128
+ bunx tsc --noEmit # typecheck (isolatedDeclarations)
129
+ bun run build # dist + .d.mts via tsdown (for Node/bundler consumers)
130
+ bun run docs:api # generate the typedoc API reference
66
131
  ```
67
132
 
68
- CI runs both on every PR. MIT licensed.
133
+ CI runs test + typecheck on every PR. MIT licensed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fusengine/harness",
3
- "version": "0.1.12",
3
+ "version": "0.1.13",
4
4
  "description": "Harness-agnostic toolkit for AI coding agents: runtime harness detection (Claude Code, Codex, Cursor, Cline, Gemini, Aider...), pure policy core (env config, project/framework detection, SOLID/file-size limits, APEX freshness, guard patterns, portable prompts), cache, project memory, ref routing, state/locks, statusline, per-harness adapters (Claude/Cursor/Cline/Gemini) and a cli-mode harness-check binary. Bun-native, with a built dist for Node + bundlers.",
5
5
  "type": "module",
6
6
  "module": "src/index.ts",
@@ -9,27 +9,111 @@
9
9
  "harness": "./dist/cli/bin.mjs"
10
10
  },
11
11
  "exports": {
12
- ".": { "bun": "./src/index.ts", "types": "./dist/index.d.mts", "import": "./dist/index.mjs" },
13
- "./config": { "bun": "./src/config/index.ts", "types": "./dist/config/index.d.mts", "import": "./dist/config/index.mjs" },
14
- "./util": { "bun": "./src/util/index.ts", "types": "./dist/util/index.d.mts", "import": "./dist/util/index.mjs" },
15
- "./detect": { "bun": "./src/detect/index.ts", "types": "./dist/detect/index.d.mts", "import": "./dist/detect/index.mjs" },
16
- "./policy": { "bun": "./src/policy/index.ts", "types": "./dist/policy/index.d.mts", "import": "./dist/policy/index.mjs" },
17
- "./prompt": { "bun": "./src/prompt/index.ts", "types": "./dist/prompt/index.d.mts", "import": "./dist/prompt/index.mjs" },
18
- "./memory": { "bun": "./src/memory/index.ts", "types": "./dist/memory/index.d.mts", "import": "./dist/memory/index.mjs" },
19
- "./cache": { "bun": "./src/cache/index.ts", "types": "./dist/cache/index.d.mts", "import": "./dist/cache/index.mjs" },
20
- "./freshness": { "bun": "./src/freshness/index.ts", "types": "./dist/freshness/index.d.mts", "import": "./dist/freshness/index.mjs" },
21
- "./refs": { "bun": "./src/refs/index.ts", "types": "./dist/refs/index.d.mts", "import": "./dist/refs/index.mjs" },
22
- "./state": { "bun": "./src/state/index.ts", "types": "./dist/state/index.d.mts", "import": "./dist/state/index.mjs" },
23
- "./statusline": { "bun": "./src/statusline/index.ts", "types": "./dist/statusline/index.d.mts", "import": "./dist/statusline/index.mjs" },
24
- "./cli": { "bun": "./src/cli/index.ts", "types": "./dist/cli/index.d.mts", "import": "./dist/cli/index.mjs" },
25
- "./init": { "bun": "./src/init/index.ts", "types": "./dist/init/index.d.mts", "import": "./dist/init/index.mjs" },
26
- "./tracking": { "bun": "./src/tracking/index.ts", "types": "./dist/tracking/index.d.mts", "import": "./dist/tracking/index.mjs" },
27
- "./runtime": { "bun": "./src/runtime/index.ts", "types": "./dist/runtime/index.d.mts", "import": "./dist/runtime/index.mjs" },
28
- "./adapters/claude": { "bun": "./src/adapters/claude/index.ts", "types": "./dist/adapters/claude/index.d.mts", "import": "./dist/adapters/claude/index.mjs" },
29
- "./adapters/codex": { "bun": "./src/adapters/codex/index.ts", "types": "./dist/adapters/codex/index.d.mts", "import": "./dist/adapters/codex/index.mjs" },
30
- "./adapters/cursor": { "bun": "./src/adapters/cursor/index.ts", "types": "./dist/adapters/cursor/index.d.mts", "import": "./dist/adapters/cursor/index.mjs" },
31
- "./adapters/cline": { "bun": "./src/adapters/cline/index.ts", "types": "./dist/adapters/cline/index.d.mts", "import": "./dist/adapters/cline/index.mjs" },
32
- "./adapters/gemini": { "bun": "./src/adapters/gemini/index.ts", "types": "./dist/adapters/gemini/index.d.mts", "import": "./dist/adapters/gemini/index.mjs" }
12
+ ".": {
13
+ "bun": "./src/index.ts",
14
+ "types": "./dist/index.d.mts",
15
+ "import": "./dist/index.mjs"
16
+ },
17
+ "./config": {
18
+ "bun": "./src/config/index.ts",
19
+ "types": "./dist/config/index.d.mts",
20
+ "import": "./dist/config/index.mjs"
21
+ },
22
+ "./util": {
23
+ "bun": "./src/util/index.ts",
24
+ "types": "./dist/util/index.d.mts",
25
+ "import": "./dist/util/index.mjs"
26
+ },
27
+ "./detect": {
28
+ "bun": "./src/detect/index.ts",
29
+ "types": "./dist/detect/index.d.mts",
30
+ "import": "./dist/detect/index.mjs"
31
+ },
32
+ "./policy": {
33
+ "bun": "./src/policy/index.ts",
34
+ "types": "./dist/policy/index.d.mts",
35
+ "import": "./dist/policy/index.mjs"
36
+ },
37
+ "./prompt": {
38
+ "bun": "./src/prompt/index.ts",
39
+ "types": "./dist/prompt/index.d.mts",
40
+ "import": "./dist/prompt/index.mjs"
41
+ },
42
+ "./memory": {
43
+ "bun": "./src/memory/index.ts",
44
+ "types": "./dist/memory/index.d.mts",
45
+ "import": "./dist/memory/index.mjs"
46
+ },
47
+ "./cache": {
48
+ "bun": "./src/cache/index.ts",
49
+ "types": "./dist/cache/index.d.mts",
50
+ "import": "./dist/cache/index.mjs"
51
+ },
52
+ "./freshness": {
53
+ "bun": "./src/freshness/index.ts",
54
+ "types": "./dist/freshness/index.d.mts",
55
+ "import": "./dist/freshness/index.mjs"
56
+ },
57
+ "./refs": {
58
+ "bun": "./src/refs/index.ts",
59
+ "types": "./dist/refs/index.d.mts",
60
+ "import": "./dist/refs/index.mjs"
61
+ },
62
+ "./state": {
63
+ "bun": "./src/state/index.ts",
64
+ "types": "./dist/state/index.d.mts",
65
+ "import": "./dist/state/index.mjs"
66
+ },
67
+ "./statusline": {
68
+ "bun": "./src/statusline/index.ts",
69
+ "types": "./dist/statusline/index.d.mts",
70
+ "import": "./dist/statusline/index.mjs"
71
+ },
72
+ "./cli": {
73
+ "bun": "./src/cli/index.ts",
74
+ "types": "./dist/cli/index.d.mts",
75
+ "import": "./dist/cli/index.mjs"
76
+ },
77
+ "./init": {
78
+ "bun": "./src/init/index.ts",
79
+ "types": "./dist/init/index.d.mts",
80
+ "import": "./dist/init/index.mjs"
81
+ },
82
+ "./tracking": {
83
+ "bun": "./src/tracking/index.ts",
84
+ "types": "./dist/tracking/index.d.mts",
85
+ "import": "./dist/tracking/index.mjs"
86
+ },
87
+ "./runtime": {
88
+ "bun": "./src/runtime/index.ts",
89
+ "types": "./dist/runtime/index.d.mts",
90
+ "import": "./dist/runtime/index.mjs"
91
+ },
92
+ "./adapters/claude": {
93
+ "bun": "./src/adapters/claude/index.ts",
94
+ "types": "./dist/adapters/claude/index.d.mts",
95
+ "import": "./dist/adapters/claude/index.mjs"
96
+ },
97
+ "./adapters/codex": {
98
+ "bun": "./src/adapters/codex/index.ts",
99
+ "types": "./dist/adapters/codex/index.d.mts",
100
+ "import": "./dist/adapters/codex/index.mjs"
101
+ },
102
+ "./adapters/cursor": {
103
+ "bun": "./src/adapters/cursor/index.ts",
104
+ "types": "./dist/adapters/cursor/index.d.mts",
105
+ "import": "./dist/adapters/cursor/index.mjs"
106
+ },
107
+ "./adapters/cline": {
108
+ "bun": "./src/adapters/cline/index.ts",
109
+ "types": "./dist/adapters/cline/index.d.mts",
110
+ "import": "./dist/adapters/cline/index.mjs"
111
+ },
112
+ "./adapters/gemini": {
113
+ "bun": "./src/adapters/gemini/index.ts",
114
+ "types": "./dist/adapters/gemini/index.d.mts",
115
+ "import": "./dist/adapters/gemini/index.mjs"
116
+ }
33
117
  },
34
118
  "files": ["dist", "README.md", "LICENSE"],
35
119
  "license": "MIT",
@@ -37,6 +121,7 @@
37
121
  "scripts": {
38
122
  "test": "bun test",
39
123
  "typecheck": "tsc --noEmit",
124
+ "docs:api": "typedoc",
40
125
  "build": "tsdown src/index.ts src/config/index.ts src/util/index.ts src/detect/index.ts src/policy/index.ts src/prompt/index.ts src/memory/index.ts src/cache/index.ts src/freshness/index.ts src/refs/index.ts src/state/index.ts src/statusline/index.ts src/cli/index.ts src/cli/bin.ts src/init/index.ts src/tracking/index.ts src/runtime/index.ts src/adapters/claude/index.ts src/adapters/codex/index.ts src/adapters/cursor/index.ts src/adapters/cline/index.ts src/adapters/gemini/index.ts --dts --format esm --clean --out-dir dist",
41
126
  "prepublishOnly": "bun test && tsc --noEmit && bun run build"
42
127
  },
@@ -47,11 +132,14 @@
47
132
  "@vercel/detect-agent": "*"
48
133
  },
49
134
  "peerDependenciesMeta": {
50
- "@vercel/detect-agent": { "optional": true }
135
+ "@vercel/detect-agent": {
136
+ "optional": true
137
+ }
51
138
  },
52
139
  "devDependencies": {
53
140
  "@types/bun": "latest",
54
141
  "tsdown": "^0.22.3",
142
+ "typedoc": "^0.28.19",
55
143
  "typescript": "^6.0.3"
56
144
  }
57
145
  }