brainclaw 0.19.7 → 0.19.11
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 +225 -126
- package/dist/cli.js +9 -3
- package/dist/commands/bootstrap.js +88 -3
- package/dist/commands/init.js +21 -0
- package/dist/commands/mcp.js +76 -3
- package/dist/core/bootstrap.js +945 -6
- package/dist/core/migration.js +6 -2
- package/dist/core/schema.js +97 -0
- package/docs/cli.md +26 -1
- package/docs/integrations/agents.md +42 -29
- package/docs/integrations/claude-code.md +4 -4
- package/docs/integrations/codex.md +5 -5
- package/docs/integrations/copilot.md +3 -2
- package/docs/integrations/cursor.md +4 -4
- package/docs/integrations/mcp.md +70 -24
- package/docs/integrations/overview.md +53 -40
- package/docs/mcp-schema-changelog.md +9 -0
- package/docs/product/positioning.md +17 -18
- package/docs/quickstart.md +102 -52
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -1,25 +1,34 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<img src="https://brainclaw.dev/logo.png" alt="brainclaw" width="140" />
|
|
3
|
-
</p>
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://brainclaw.dev/logo.png" alt="brainclaw" width="140" />
|
|
3
|
+
</p>
|
|
4
4
|
|
|
5
5
|
<h1 align="center">brainclaw</h1>
|
|
6
6
|
|
|
7
|
-
<p align="center"><strong>Local-first coordination for
|
|
7
|
+
<p align="center"><strong>Local-first coordination for coding agents, with human-readable local control.</strong></p>
|
|
8
8
|
|
|
9
|
-
---
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
brainclaw gives a workspace a shared coordination layer for coding agents: project memory, explicit plans, file claims, handoffs, layered instructions, and prompt-ready context, all stored locally, versioned in Git, and readable in plain text.
|
|
12
|
+
|
|
13
|
+
For capable agents, the nominal path is:
|
|
10
14
|
|
|
11
|
-
|
|
15
|
+
1. read dynamic state through MCP
|
|
16
|
+
2. use native agent files such as `AGENTS.md`, `CLAUDE.md`, or Cursor rules as local guidance
|
|
17
|
+
3. leave the CLI to operators, scripts, setup, release, and fallback workflows
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
The best setup is usually not "open a terminal and run Brainclaw yourself".
|
|
20
|
+
The best setup is to tell your agent, in natural language, to install and initialize Brainclaw in the repo so it can bootstrap its own working context correctly.
|
|
21
|
+
|
|
22
|
+
It sits alongside Copilot, Claude Code, Cursor, Codex, Windsurf, OpenCode, Antigravity/Gemini CLI and other coding agents. It does not replace them. It gives them a shared state layer they can resume from reliably across sessions.
|
|
14
23
|
|
|
15
24
|
---
|
|
16
25
|
|
|
17
26
|
## Why brainclaw exists
|
|
18
27
|
|
|
19
28
|
Coding agents are getting better at local code generation, but they still struggle with shared project state.
|
|
20
|
-
Across real projects, agents often miss active constraints, forget known traps, duplicate work, step on the same files, and lose context between sessions.
|
|
29
|
+
Across real projects, agents often miss active constraints, forget known traps, duplicate work, step on the same files, and lose context between sessions or tool surfaces.
|
|
21
30
|
|
|
22
|
-
brainclaw solves this by
|
|
31
|
+
brainclaw solves this by making the repo itself agent-readable and agent-writeable through MCP, local memory files, and explicit coordination primitives.
|
|
23
32
|
|
|
24
33
|
---
|
|
25
34
|
|
|
@@ -27,74 +36,152 @@ brainclaw solves this by giving the workspace a shared coordination layer that b
|
|
|
27
36
|
|
|
28
37
|
| | |
|
|
29
38
|
|---|---|
|
|
30
|
-
| **Project memory** | constraints, decisions, traps, handoffs, layered instructions |
|
|
31
|
-
| **Coordination state** | shared plans, file claims,
|
|
32
|
-
| **Agent-ready context** | compact, prompt-sized context
|
|
33
|
-
| **Native agent files** | auto-writes `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`,
|
|
34
|
-
| **Local-first storage** | plain text + JSON, Git-friendly, no cloud, no telemetry |
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
##
|
|
39
|
-
|
|
40
|
-
brainclaw
|
|
41
|
-
|
|
42
|
-
|
|
|
43
|
-
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
|
64
|
-
|
|
65
|
-
| [](https://github.com/anthropics/claude-code) | **[Claude Code](https://github.com/anthropics/claude-code)** | Best fit | full agent workflow with MCP, instructions, commands, and session hooks |
|
|
68
|
+
| [](https://openai.com/codex/) | **[Codex](https://openai.com/codex/)** | Strong fit | agent-first repo coordination with explicit plans, claims, and handoffs |
|
|
69
|
+
| [](https://cursor.com/en-US) | **[Cursor](https://cursor.com/en-US)** | Strong fit | repo-native agent workflows with rules plus MCP |
|
|
70
|
+
| [](https://github.com/opencode-ai/opencode) | **[OpenCode](https://github.com/opencode-ai/opencode)** | Strong fit | simple agent bootstrap with `AGENTS.md` plus workspace MCP |
|
|
71
|
+
| [](https://windsurf.com/) | **[Windsurf](https://windsurf.com/)** | Good fit | guided agent workflows with instructions, hooks, and MCP |
|
|
72
|
+
| [](https://github.com/RooCodeInc/Roo-Code) | **[Roo](https://github.com/RooCodeInc/Roo-Code)** | Good fit | workspace agent coordination with rules plus MCP |
|
|
73
|
+
| [](https://github.com/continuedev/continue) | **[Continue](https://github.com/continuedev/continue)** | Good fit | editor-based agent workflows with MCP context access |
|
|
74
|
+
| [](https://github.com/google-gemini/gemini-cli) | **[Antigravity / Gemini CLI](https://github.com/google-gemini/gemini-cli)** | Promising fit | local agent workflows with `GEMINI.md` plus MCP |
|
|
75
|
+
| [](https://github.com/cline/cline) | **[Cline](https://github.com/cline/cline)** | Functional fit | lightweight agent use through rules plus MCP |
|
|
76
|
+
| [](https://github.com/features/copilot) | **[GitHub Copilot](https://github.com/features/copilot)** | Supported fit | project awareness and shared local instructions with lighter workflow control |
|
|
77
|
+
|
|
78
|
+
brainclaw is most effective today when one agent works at a time in a given checkout and the next agent resumes from shared context, claims, and handoffs.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Platform Support
|
|
83
|
+
|
|
84
|
+
brainclaw targets Node.js 20+ across major developer operating systems, but real-world support is not perfectly even yet.
|
|
85
|
+
|
|
86
|
+
| Logo | Platform | Status today | Notes |
|
|
87
|
+
|---|---|---|---|
|
|
88
|
+
| [](https://www.kernel.org/) | **[Linux](https://www.kernel.org/)** | Recommended | best-supported environment today; GitHub CI runs on Ubuntu with Node 20 and 22 |
|
|
89
|
+
| [](https://www.apple.com/macos/) | **[macOS](https://www.apple.com/macos/)** | Likely supported | Unix-like path and shell model should map well, but it is less exercised than Linux |
|
|
90
|
+
| [](https://www.microsoft.com/windows/) | **[Windows](https://www.microsoft.com/windows/)** | Supported with caveats | native support exists, but PATH, npm, SSH, and PowerShell quoting still create more friction than on Unix systems |
|
|
91
|
+
| [](https://learn.microsoft.com/windows/wsl/) | **[Windows + WSL2](https://learn.microsoft.com/windows/wsl/)** | Important, still maturing | Brainclaw detects this setup explicitly, but setup/install/store parity across Windows and WSL is not fully seamless yet |
|
|
92
|
+
|
|
93
|
+
If you want the least surprising setup today, use Linux first. If you are on Windows, prefer a disciplined single-environment workflow and expect a few extra machine-specific fixes.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Best Setup
|
|
98
|
+
|
|
99
|
+
If you want the cleanest Brainclaw onboarding, ask your agent to do it.
|
|
100
|
+
|
|
101
|
+
Example:
|
|
102
|
+
|
|
103
|
+
```text
|
|
104
|
+
Install Brainclaw in this repo, initialize it, configure the agent integration if needed,
|
|
105
|
+
and then use Brainclaw for shared context, plans, claims, and handoffs while you work.
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
That is the product's intended entry path.
|
|
109
|
+
The human expresses the intent in plain language. The agent installs Brainclaw, bootstraps the repo, and then keeps using it through MCP and local agent files.
|
|
110
|
+
|
|
111
|
+
If the agent supports MCP well, this produces a better bootstrap than a human manually running setup commands first, because the agent can immediately:
|
|
112
|
+
|
|
113
|
+
- set up the workspace in the right environment
|
|
114
|
+
- write the local agent-facing files it will actually use
|
|
115
|
+
- configure MCP where supported
|
|
116
|
+
- start from shared context instead of ad hoc instructions
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Quick Example
|
|
75
121
|
|
|
76
122
|
```bash
|
|
123
|
+
# behind the scenes, the agent will typically bootstrap Brainclaw in the repo
|
|
77
124
|
npx brainclaw setup --yes
|
|
78
125
|
npx brainclaw init
|
|
126
|
+
```
|
|
79
127
|
|
|
80
|
-
|
|
81
|
-
npx brainclaw memory create constraint "Payments module frozen until 2026-04-01" --tag payments
|
|
82
|
-
npx brainclaw memory create trap "Checkout E2E tests are flaky on Windows" --severity high
|
|
83
|
-
npx brainclaw plan create "Coordinate auth rollout" --priority high
|
|
84
|
-
npx brainclaw memory create handoff "Validate refund endpoint" --from backend --to qa
|
|
128
|
+
After that, the agent should stay on Brainclaw's MCP path for live state:
|
|
85
129
|
|
|
86
|
-
|
|
87
|
-
|
|
130
|
+
```text
|
|
131
|
+
bclaw_session_start -> open session + return board/context
|
|
132
|
+
bclaw_get_context -> fetch fresh prompt-ready context for a path
|
|
133
|
+
bclaw_list_plans -> inspect shared work
|
|
134
|
+
bclaw_claim -> claim scope before editing
|
|
135
|
+
bclaw_write_note -> record runtime observations
|
|
136
|
+
bclaw_session_end -> close session and hand work off cleanly
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Humans can still use the CLI directly for inspection, scripting, and fallback workflows:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
brainclaw plan create "Coordinate auth rollout" --priority high
|
|
143
|
+
brainclaw claim create "Take auth rollout" --scope src/auth/
|
|
144
|
+
brainclaw context --for src/auth/routes.ts --digest
|
|
145
|
+
brainclaw status
|
|
88
146
|
```
|
|
89
147
|
|
|
90
148
|
---
|
|
91
149
|
|
|
92
150
|
## Installation
|
|
93
151
|
|
|
152
|
+
The intended path is agent-driven bootstrap inside the target repo, not a human doing a manual install flow first.
|
|
153
|
+
|
|
154
|
+
In practice, that means:
|
|
155
|
+
|
|
156
|
+
1. tell the agent to install and initialize Brainclaw in the repo
|
|
157
|
+
2. let the agent bootstrap MCP and native agent files
|
|
158
|
+
3. let the agent keep using Brainclaw for shared context and coordination while it works
|
|
159
|
+
|
|
160
|
+
If you need the underlying commands, the agent will usually do something close to:
|
|
161
|
+
|
|
94
162
|
```bash
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
163
|
+
npx brainclaw setup --yes
|
|
164
|
+
npx brainclaw init
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
That gives the agent a better bootstrap path because Brainclaw can immediately:
|
|
168
|
+
|
|
169
|
+
- detect the workspace
|
|
170
|
+
- write native agent files
|
|
171
|
+
- configure MCP where supported
|
|
172
|
+
- seed local project memory and coordination state
|
|
173
|
+
|
|
174
|
+
If you want a machine-level CLI for operator workflows, debugging, or repeated local use, a global install is still available, but it is not the primary onboarding path:
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
npm install -g brainclaw
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
If you are working from source while developing Brainclaw itself:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
npm install
|
|
184
|
+
npm run build
|
|
98
185
|
```
|
|
99
186
|
|
|
100
187
|
Also available as `bclaw`:
|
|
@@ -106,80 +193,87 @@ bclaw status
|
|
|
106
193
|
|
|
107
194
|
---
|
|
108
195
|
|
|
109
|
-
## Quickstart
|
|
196
|
+
## Quickstart
|
|
110
197
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
brainclaw context --json
|
|
119
|
-
```
|
|
198
|
+
Start here conceptually:
|
|
199
|
+
|
|
200
|
+
1. ask the agent to install and initialize Brainclaw in the repo
|
|
201
|
+
2. let the agent use MCP for dynamic state
|
|
202
|
+
3. use the CLI yourself only when you need operator-level inspection or fallback access
|
|
203
|
+
|
|
204
|
+
Then choose the entry path that matches your surface:
|
|
120
205
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
206
|
+
- agent-first runtime: start with `docs/integrations/overview.md` and `docs/integrations/mcp.md`
|
|
207
|
+
- operator CLI: use `docs/quickstart.md` and `docs/cli.md`
|
|
208
|
+
- brownfield onboarding: use `brainclaw bootstrap` and the onboarding guides in `docs/`
|
|
209
|
+
|
|
210
|
+
If you are evaluating Brainclaw as a product, start with the agent-first runtime path, not the CLI reference.
|
|
211
|
+
|
|
212
|
+
Detailed Markdown guides are bundled in the npm package under `docs/`.
|
|
213
|
+
|
|
214
|
+
---
|
|
215
|
+
|
|
216
|
+
## Current Limitation
|
|
217
|
+
|
|
218
|
+
For now, avoid having multiple coding agents edit the same project in parallel in the same checkout.
|
|
219
|
+
|
|
220
|
+
brainclaw already helps one agent resume or review another agent's work with better shared context, plans, claims, and handoffs. But until dedicated Git worktrees per agent or session are implemented, concurrent edits in the same checkout can still create conflicts, overwritten local state, or confusing Git transitions.
|
|
221
|
+
|
|
222
|
+
Recommended use today:
|
|
223
|
+
|
|
224
|
+
1. let one agent work at a time in a given checkout
|
|
225
|
+
2. use handoffs when switching from one agent to another
|
|
226
|
+
3. use shared plans, claims, and context to preserve continuity
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
## How it fits into agent workflows
|
|
140
231
|
|
|
141
232
|
brainclaw sits *alongside* Copilot, Claude Code, Cursor, Codex, Windsurf, Cline, Roo, Continue, OpenCode, and Antigravity/Gemini CLI.
|
|
142
233
|
|
|
143
|
-
Typical flow:
|
|
234
|
+
Typical agent-first flow:
|
|
144
235
|
|
|
145
|
-
1.
|
|
146
|
-
2.
|
|
147
|
-
3.
|
|
148
|
-
4.
|
|
149
|
-
5. use
|
|
150
|
-
6.
|
|
151
|
-
7. keep shared state visible across sessions
|
|
236
|
+
1. a human asks the agent to install and initialize Brainclaw in the repo
|
|
237
|
+
2. the agent bootstraps Brainclaw in the right environment for that workspace
|
|
238
|
+
3. the agent connects through MCP for fresh context, board views, plans, claims, and runtime writes
|
|
239
|
+
4. native agent files provide local guidance and workflow reminders in the surface the agent already uses
|
|
240
|
+
5. humans use the CLI for inspection, scripting, release, and fallback operations
|
|
241
|
+
6. shared plans, claims, handoffs, and runtime notes keep the next agent resumeable
|
|
152
242
|
|
|
153
|
-
brainclaw
|
|
243
|
+
brainclaw exposes collaboration views through MCP-readable tools, including context, board views, and structured lists for plans, claims, agents, instructions, and candidates. Readable local files still matter, but MCP is the stronger path for dynamic state and write operations.
|
|
154
244
|
|
|
155
245
|
---
|
|
156
246
|
|
|
157
|
-
## Documentation
|
|
158
|
-
|
|
159
|
-
The npm package includes the Markdown docs below under `docs/`. Public web docs on `brainclaw.dev` are still being rolled out, so the npm README does not depend on private GitHub links.
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
|
164
|
-
|
|
165
|
-
| `docs/
|
|
166
|
-
| `docs/
|
|
167
|
-
| `docs/
|
|
168
|
-
| `docs/
|
|
169
|
-
| `docs/
|
|
170
|
-
| `docs/
|
|
171
|
-
| `docs/
|
|
172
|
-
| `docs/integrations/
|
|
173
|
-
| `docs/integrations/
|
|
174
|
-
| `docs/
|
|
175
|
-
| `docs/
|
|
176
|
-
| `docs/
|
|
177
|
-
| `docs/
|
|
247
|
+
## Documentation
|
|
248
|
+
|
|
249
|
+
The npm package includes the Markdown docs below under `docs/`. Public web docs on `brainclaw.dev` are still being rolled out, so the npm README does not depend on private GitHub links.
|
|
250
|
+
|
|
251
|
+
If you are integrating Brainclaw into an agent workflow, start with the agent-facing docs first:
|
|
252
|
+
|
|
253
|
+
| | |
|
|
254
|
+
|---|---|
|
|
255
|
+
| `docs/integrations/overview.md` | Start here for agent integrations |
|
|
256
|
+
| `docs/integrations/mcp.md` | MCP runtime path for capable agents |
|
|
257
|
+
| `docs/quickstart.md` | Setup paths, including operator and brownfield flows |
|
|
258
|
+
| `docs/cli.md` | CLI reference for operators, scripts, and fallback use |
|
|
259
|
+
| `docs/concepts/memory.md` | What "memory" means in brainclaw |
|
|
260
|
+
| `docs/concepts/plans-and-claims.md` | Coordination layer |
|
|
261
|
+
| `docs/concepts/runtime-notes.md` | Ephemeral observations |
|
|
262
|
+
| `docs/integrations/cursor.md` | Cursor |
|
|
263
|
+
| `docs/integrations/claude-code.md` | Claude Code |
|
|
264
|
+
| `docs/integrations/copilot.md` | GitHub Copilot |
|
|
265
|
+
| `docs/integrations/codex.md` | Codex |
|
|
266
|
+
| `docs/storage.md` | Storage model |
|
|
267
|
+
| `docs/security.md` | Security model |
|
|
268
|
+
| `docs/review.md` | Reflective review |
|
|
269
|
+
| `docs/reputation.md` | Reputation signals |
|
|
178
270
|
|
|
179
271
|
---
|
|
180
272
|
|
|
181
273
|
## Running tests
|
|
182
274
|
|
|
275
|
+
Contributor note: the commands below are for developing Brainclaw itself, not for normal agent usage inside a target repo.
|
|
276
|
+
|
|
183
277
|
```bash
|
|
184
278
|
npm test # unit + smoke (fast path)
|
|
185
279
|
npm run test:e2e # full suite
|
|
@@ -217,8 +311,13 @@ npm run test:coverage # with coverage report
|
|
|
217
311
|
|
|
218
312
|
## License
|
|
219
313
|
|
|
220
|
-
[Business Source License 1.1](LICENSE) — © 2024-2026 Juan Berdah
|
|
314
|
+
Current releases of brainclaw are published under the [Business Source License 1.1](LICENSE) — © 2024-2026 Juan Berdah.
|
|
315
|
+
|
|
316
|
+
The long-term direction is simpler than the current wording might suggest:
|
|
317
|
+
|
|
318
|
+
- the local-first brainclaw core is intended to move to MIT after the closed beta
|
|
319
|
+
- cloud shared-memory, remote collaboration services, advanced dashboards, and related hosted add-ons will live in separate commercial products
|
|
221
320
|
|
|
222
|
-
|
|
321
|
+
The intended MIT core covers what makes brainclaw useful inside a repo today: local project memory, local MCP and CLI coordination, onboarding and bootstrap, plans, claims, handoffs, runtime notes, and local agent integrations.
|
|
223
322
|
|
|
224
|
-
|
|
323
|
+
The goal is not to close brainclaw down. The goal is to keep the local-first core open and genuinely useful on its own, while keeping hosted collaboration features separate.
|
package/dist/cli.js
CHANGED
|
@@ -509,12 +509,18 @@ program
|
|
|
509
509
|
// --- bootstrap ---
|
|
510
510
|
program
|
|
511
511
|
.command('bootstrap')
|
|
512
|
-
.description('Derive brownfield bootstrap signals
|
|
512
|
+
.description('Derive brownfield bootstrap signals and optionally import them into canonical memory')
|
|
513
513
|
.option('--for <target>', 'Target path or scope to tailor the bootstrap')
|
|
514
514
|
.option('--json', 'Output as JSON')
|
|
515
515
|
.option('--refresh', 'Force a fresh bootstrap scan instead of reusing the current profile')
|
|
516
|
-
.
|
|
517
|
-
|
|
516
|
+
.option('--interview', 'Render the adaptive interview prompts instead of the bootstrap summary')
|
|
517
|
+
.option('--audience <audience>', 'Target interview prompts for cli, ide_chat, or any')
|
|
518
|
+
.option('--answers-file <path>', 'Load structured bootstrap interview answers from a JSON file')
|
|
519
|
+
.option('--apply', 'Import the current bootstrap proposal into canonical memory')
|
|
520
|
+
.option('--uninstall', 'Deactivate the last bootstrap import managed by this workspace')
|
|
521
|
+
.option('-y, --yes', 'Skip confirmation prompts for apply/uninstall')
|
|
522
|
+
.action(async (options) => {
|
|
523
|
+
await runBootstrap(options);
|
|
518
524
|
});
|
|
519
525
|
// --- env ---
|
|
520
526
|
program
|
|
@@ -1,15 +1,50 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import readline from 'node:readline/promises';
|
|
3
|
+
import { stdin as input, stdout as output } from 'node:process';
|
|
1
4
|
import { memoryExists } from '../core/io.js';
|
|
2
|
-
import { renderBootstrapSummary, runBootstrapProfile } from '../core/bootstrap.js';
|
|
3
|
-
|
|
5
|
+
import { applyBootstrapImport, renderBootstrapInterview, renderBootstrapSummary, runBootstrapProfile, uninstallBootstrapImport, } from '../core/bootstrap.js';
|
|
6
|
+
import { BootstrapInterviewAnswerSchema } from '../core/schema.js';
|
|
7
|
+
export async function runBootstrap(options = {}) {
|
|
4
8
|
const cwd = options.cwd ?? process.cwd();
|
|
5
9
|
if (!memoryExists(cwd)) {
|
|
6
10
|
console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
|
|
7
11
|
process.exit(1);
|
|
8
12
|
}
|
|
9
13
|
try {
|
|
14
|
+
if (options.apply && options.uninstall) {
|
|
15
|
+
console.error('Error: --apply and --uninstall are mutually exclusive.');
|
|
16
|
+
process.exit(1);
|
|
17
|
+
}
|
|
18
|
+
const audience = resolveBootstrapInterviewAudience(options.audience);
|
|
19
|
+
const interviewAnswers = loadBootstrapInterviewAnswers(options.answersFile);
|
|
20
|
+
if (options.uninstall) {
|
|
21
|
+
await confirmBootstrapAction('Remove the last bootstrap import?', options.yes);
|
|
22
|
+
const result = uninstallBootstrapImport(cwd);
|
|
23
|
+
if (!result.receipt) {
|
|
24
|
+
console.log('No bootstrap import receipt found.');
|
|
25
|
+
return;
|
|
26
|
+
}
|
|
27
|
+
console.log(`✔ Bootstrap uninstall completed: ${result.deactivatedCount} instruction(s) deactivated, ${result.deletedCount} artifact(s) deleted, ${result.skippedCount} artifact(s) skipped.`);
|
|
28
|
+
return;
|
|
29
|
+
}
|
|
30
|
+
if (options.apply) {
|
|
31
|
+
await confirmBootstrapAction('Apply the current bootstrap import proposal to canonical memory?', options.yes);
|
|
32
|
+
const result = applyBootstrapImport({
|
|
33
|
+
target: options.for,
|
|
34
|
+
refresh: options.refresh,
|
|
35
|
+
interviewAnswers,
|
|
36
|
+
cwd,
|
|
37
|
+
});
|
|
38
|
+
console.log(`✔ Bootstrap import applied: ${result.createdCount} item(s) created, ${result.skippedCount} suggestion(s) skipped.`);
|
|
39
|
+
if (result.receipt) {
|
|
40
|
+
console.log(`✔ Receipt saved: ${result.receipt.managed_artifacts.length} managed artifact(s) can be reverted with \`brainclaw bootstrap --uninstall\`.`);
|
|
41
|
+
}
|
|
42
|
+
return;
|
|
43
|
+
}
|
|
10
44
|
const result = runBootstrapProfile({
|
|
11
45
|
target: options.for,
|
|
12
46
|
refresh: options.refresh,
|
|
47
|
+
interviewAnswers,
|
|
13
48
|
cwd,
|
|
14
49
|
});
|
|
15
50
|
if (options.json) {
|
|
@@ -18,17 +53,67 @@ export function runBootstrap(options = {}) {
|
|
|
18
53
|
target: result.profile.target,
|
|
19
54
|
repo_fingerprint: result.profile.repo_fingerprint,
|
|
20
55
|
sources_scanned: result.profile.sources_scanned,
|
|
56
|
+
workspace_kind: result.profile.workspace_kind,
|
|
57
|
+
confidence: result.profile.confidence,
|
|
58
|
+
native_instruction_files: result.profile.native_instruction_files,
|
|
59
|
+
gaps: result.profile.gaps,
|
|
21
60
|
seed_count: result.profile.seed_count,
|
|
22
61
|
seeds: result.seeds,
|
|
62
|
+
import_plan: result.importPlan,
|
|
63
|
+
last_application: result.lastApplication,
|
|
23
64
|
reused_profile: result.reusedProfile,
|
|
24
65
|
}, null, 2));
|
|
25
66
|
return;
|
|
26
67
|
}
|
|
27
|
-
console.log(renderBootstrapSummary(result));
|
|
68
|
+
console.log(options.interview ? renderBootstrapInterview(result, audience) : renderBootstrapSummary(result));
|
|
28
69
|
}
|
|
29
70
|
catch (error) {
|
|
30
71
|
console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
|
|
31
72
|
process.exit(1);
|
|
32
73
|
}
|
|
33
74
|
}
|
|
75
|
+
function resolveBootstrapInterviewAudience(value) {
|
|
76
|
+
if (!value) {
|
|
77
|
+
return 'any';
|
|
78
|
+
}
|
|
79
|
+
if (value === 'cli' || value === 'ide_chat' || value === 'any') {
|
|
80
|
+
return value;
|
|
81
|
+
}
|
|
82
|
+
throw new Error(`Unsupported bootstrap interview audience '${value}'. Use cli, ide_chat, or any.`);
|
|
83
|
+
}
|
|
84
|
+
function loadBootstrapInterviewAnswers(filepath) {
|
|
85
|
+
if (!filepath) {
|
|
86
|
+
return [];
|
|
87
|
+
}
|
|
88
|
+
const raw = fs.readFileSync(filepath, 'utf-8');
|
|
89
|
+
const parsed = JSON.parse(raw);
|
|
90
|
+
if (!Array.isArray(parsed)) {
|
|
91
|
+
throw new Error(`Bootstrap interview answers file must contain a JSON array: ${filepath}`);
|
|
92
|
+
}
|
|
93
|
+
return parsed.map((entry) => BootstrapInterviewAnswerSchema.parse(entry));
|
|
94
|
+
}
|
|
95
|
+
async function confirmBootstrapAction(question, yes) {
|
|
96
|
+
if (yes) {
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
if (!process.stdin.isTTY || !process.stdout.isTTY) {
|
|
100
|
+
console.error(`Error: ${question} Re-run with --yes in non-interactive mode.`);
|
|
101
|
+
process.exit(1);
|
|
102
|
+
}
|
|
103
|
+
const rl = readline.createInterface({ input, output });
|
|
104
|
+
try {
|
|
105
|
+
const answer = await rl.question(`${question} [y/N] `);
|
|
106
|
+
if (answer.trim().toLowerCase() !== 'y') {
|
|
107
|
+
console.error('Cancelled.');
|
|
108
|
+
process.exit(1);
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
catch (error) {
|
|
112
|
+
console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
|
|
113
|
+
process.exit(1);
|
|
114
|
+
}
|
|
115
|
+
finally {
|
|
116
|
+
rl.close();
|
|
117
|
+
}
|
|
118
|
+
}
|
|
34
119
|
//# sourceMappingURL=bootstrap.js.map
|
package/dist/commands/init.js
CHANGED
|
@@ -10,6 +10,7 @@ import { initMemoryRepo } from '../core/memory-git.js';
|
|
|
10
10
|
import { buildProjectIdentity, resolveExistingProjectIdentity, saveProjectIdentity } from '../core/project-registry.js';
|
|
11
11
|
import { scanProject, upsertProject } from '../core/global-registry.js';
|
|
12
12
|
import { analyzeRepository, scanWorkspaceBoundaries } from '../core/repo-analysis.js';
|
|
13
|
+
import { renderBootstrapSummary, runBootstrapProfile } from '../core/bootstrap.js';
|
|
13
14
|
import { isAgentIntegrationName, upsertAgentIntegrationDeclaration } from '../core/agent-integrations.js';
|
|
14
15
|
import { describeAutoConfigWrite, ensureAgentFiles, ensureGitignoreEntries, writeDetectedAgentAutoConfig } from '../core/agent-files.js';
|
|
15
16
|
import { detectAiAgent, detectWslEnvironment } from '../core/ai-agent-detection.js';
|
|
@@ -228,6 +229,26 @@ export async function runInit(options = {}) {
|
|
|
228
229
|
if (initMemoryRepo(cwd)) {
|
|
229
230
|
console.log('✔ Initialized memory git repo for versioning');
|
|
230
231
|
}
|
|
232
|
+
const onboardingPreflight = runBootstrapProfile({ cwd, refresh: true });
|
|
233
|
+
console.log('');
|
|
234
|
+
console.log('Onboarding preflight:');
|
|
235
|
+
for (const line of renderBootstrapSummary(onboardingPreflight).split('\n')) {
|
|
236
|
+
console.log(` ${line}`);
|
|
237
|
+
}
|
|
238
|
+
if (onboardingPreflight.importPlan.suggestion_count > 0) {
|
|
239
|
+
console.log('');
|
|
240
|
+
console.log(`Next step: run 'brainclaw bootstrap --apply' to import ${onboardingPreflight.importPlan.suggestion_count} suggested item(s) into canonical memory.`);
|
|
241
|
+
console.log(`Rollback: run 'brainclaw bootstrap --uninstall' to deactivate the last bootstrap-managed import.`);
|
|
242
|
+
}
|
|
243
|
+
if ((onboardingPreflight.importPlan.interview?.question_count ?? 0) > 0) {
|
|
244
|
+
console.log('');
|
|
245
|
+
console.log(`Interview: run 'brainclaw bootstrap --interview --audience cli' for terminal agents or '--audience ide_chat' for IDE chat agents.`);
|
|
246
|
+
console.log(`Apply confirmed answers: write a JSON answers file and run 'brainclaw bootstrap --answers-file <path> --apply'.`);
|
|
247
|
+
}
|
|
248
|
+
else if ((onboardingPreflight.profile.gaps?.length ?? 0) > 0) {
|
|
249
|
+
console.log('');
|
|
250
|
+
console.log(`Next step: review the onboarding gaps, then use 'brainclaw bootstrap --json' as the basis for an interview/import flow.`);
|
|
251
|
+
}
|
|
231
252
|
console.log('');
|
|
232
253
|
console.log(`Tip: run 'brainclaw context --json' to load the shared memory into your agent session.`);
|
|
233
254
|
}
|