framein 0.0.5 → 0.0.6

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,285 +1,286 @@
1
- <p align="center">
2
- <img src="docs/assets/framein-readme-header.svg" alt="Framein" width="760">
3
- </p>
4
-
5
- <p align="center">
6
- <strong>One local work frame beneath the coding agents you already use.</strong>
7
- </p>
8
-
9
- <p align="center">
1
+ <p>
2
+ <img src="docs/assets/framein-bi.png" alt="Framein" width="150" align="left">
3
+ <strong>One local work frame beneath the coding agents you already use.</strong><br>
10
4
  Start with one agent. Challenge with another. Switch when needed. Ship with evidence.
11
5
  </p>
12
-
13
- <p align="center">
14
- <a href="https://www.npmjs.com/package/framein"><img src="https://img.shields.io/npm/v/framein" alt="npm version"></a>
15
- <img src="https://img.shields.io/badge/tests-249%20passing-brightgreen" alt="249 tests passing">
16
- <img src="https://img.shields.io/badge/runtime-zero%20deps-blue" alt="zero runtime dependencies">
17
- <img src="https://img.shields.io/badge/node-%3E%3D22.5-339933" alt="Node 22.5+">
18
- <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT license">
19
- </p>
20
-
21
- <p align="center">
22
- <a href="https://www.framein.dev">Website</a> |
23
- <a href="https://www.framein.dev/why">Developer note</a> |
24
- <a href="docs/MANUAL.md">Manual</a> |
25
- <a href="docs/INSTALL.md">Install guide</a> |
26
- <a href="docs/FAQ.md">FAQ</a> |
27
- <a href="SECURITY.md">Security</a>
28
- </p>
29
-
30
- Framein is a local work-state layer beneath the coding agents and harnesses you already use. Keep
31
- using Claude Code, Codex, Gemini, Pi, OpenCode, slash-command frameworks, skill packs, role-based
32
- workflows, or your own setup. Framein keeps the work underneath them stable: a task contract,
33
- decision trail, risk state, validation results, and a compact capsule the next model can read.
34
-
35
- ```text
36
- start in Claude -> challenge with Codex -> switch when needed -> validate before ship
37
- ```
38
-
39
- Status: **public pre-release** (`v0.0.5`). Runtime dependencies: **zero**. Required Node:
40
- **22.5.0+**.
41
-
6
+ <br clear="left">
7
+
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/framein"><img src="https://img.shields.io/npm/v/framein" alt="npm version"></a>
10
+ <img src="https://img.shields.io/badge/tests-249%20passing-brightgreen" alt="249 tests passing">
11
+ <img src="https://img.shields.io/badge/runtime-zero%20deps-blue" alt="zero runtime dependencies">
12
+ <img src="https://img.shields.io/badge/node-%3E%3D22.5-339933" alt="Node 22.5+">
13
+ <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT license">
14
+ </p>
15
+
16
+ <p align="center">
17
+ <a href="https://www.framein.dev">Website</a> |
18
+ <a href="https://www.framein.dev/why">Developer note</a> |
19
+ <a href="docs/MANUAL.md">Manual</a> |
20
+ <a href="docs/INSTALL.md">Install guide</a> |
21
+ <a href="docs/FAQ.md">FAQ</a> |
22
+ <a href="SECURITY.md">Security</a>
23
+ </p>
24
+
25
+ Framein is a local work-state layer beneath the coding agents and harnesses you already use. Keep
26
+ using Claude Code, Codex, Gemini, Pi, OpenCode, slash-command frameworks, skill packs, role-based
27
+ workflows, or your own setup. Framein keeps the work underneath them stable: a task contract,
28
+ decision trail, risk state, validation results, and a compact capsule the next model can read.
29
+
30
+ ```text
31
+ start in Claude -> challenge with Codex -> switch when needed -> validate before ship
32
+ ```
33
+
34
+ Status: **public pre-release** (`v0.0.6`). Runtime dependencies: **zero**. Required Node:
35
+ **22.5.0+**.
36
+
42
37
  Links:
43
- - English: [Website](https://www.framein.dev) · [Developer note](https://www.framein.dev/why) · [Manual](docs/MANUAL.md) · [Install guide](docs/INSTALL.md) · [FAQ](docs/FAQ.md) · [Security](SECURITY.md)
44
- - Korean: [웹사이트](https://www.framein.dev/ko) · [개발자 노트](https://www.framein.dev/ko/why) · [매뉴얼](docs/MANUAL.ko.md) · [설치 가이드](docs/INSTALL.ko.md)
45
-
46
- ## Why Framein?
47
-
48
- Good PRDs, plans, ADRs, and skill packs help any model do better work. That is useful, and Framein is
49
- designed to coexist with it.
50
-
51
- The pain Framein targets starts when the work has to survive beyond one model or one clean session:
52
-
53
- - Your lead model gets stuck and repeats the same approach.
54
- - You want a different model to challenge the plan, diff, or risk.
55
- - You need to switch lead model because of quota, model fit, or a dead end.
56
- - The agent says the task is done before build and tests ran.
57
- - The next session gets a chat summary instead of the actual contract, validation state, failed attempts, and decisions.
58
-
59
- Framein does not replace the coding agent or pretend to be a full multi-agent cockpit. It keeps one
60
- local work frame under the agents you already use.
61
-
62
- ## Quick Start
63
-
64
- npm is the supported cross-platform install path today:
65
-
66
- ```bash
67
- npm install -g framein
68
- framein --version
69
- ```
70
-
71
- Standalone executables are planned as an additional convenience path, mainly for users who do not
72
- want to install Node/npm or who want to avoid Windows npm shim and PowerShell execution-policy
73
- friction. They are not required to use Framein today. See
74
- [Install notes](docs/INSTALL.md#6-standalone-executables).
75
-
76
- If you want to test a local checkout instead:
77
-
78
- ```bash
79
- git clone https://github.com/framein-dev/framein.git
80
- cd framein
81
- npm install
82
- npm run build
83
- npm install -g .
84
- ```
85
-
86
- Initialize a project:
87
-
88
- ```bash
89
- cd your-project
90
- framein init
91
- framein integrations install all --write
92
- ```
93
-
94
- Run the work loop:
95
-
96
- ```bash
97
- framein start "add Google OAuth, keep email login"
98
- framein verify
99
-
100
- # When another model should review or continue:
101
- framein challenge "review the OAuth callback plan" --run
102
- framein capsule codex
103
-
104
- framein ship
105
- ```
106
-
107
- Use `challenge` when another model should review a claim or plan. In a live run, the reviewer returns
108
- a structured verdict, the lead gets one bounded response, and Framein prints a decision brief for the
109
- user to accept or reject. Use `capsule <agent>` when a different model should continue from the same
110
- local facts. After the current CLI exits, Framein launches the next agent with a short handoff prompt;
111
- the new agent still pulls facts with `framein capsule`. `verify` is a rehearsal; `ship` is the
112
- enforced gate and exits non-zero when hard validation fails.
113
-
114
- ## What You See
115
-
116
- ```text
117
- $ framein start "add Google OAuth, keep email login"
118
- task contract
119
- goal add Google OAuth, keep email login
120
- preserve existing email login
121
-
122
- $ framein challenge "OAuth callback stores state in session" --run
123
- reviewer codex
124
- verdict challenge
125
- required add nonce/state validation
126
- lead accepts required change
127
- next framein decide accept "add nonce/state validation"
38
+ - Korean: [웹사이트](https://www.framein.dev/ko) | [개발자 노트](https://www.framein.dev/ko/why) | [매뉴얼](docs/MANUAL.ko.md) | [설치 가이드](docs/INSTALL.ko.md)
128
39
 
129
- $ framein capsule gemini
130
- next lead prepared from facts:
131
- contract · diff · tests · decisions
132
- exit the current agent; gemini opens and pulls the capsule first
40
+ ## Demo
133
41
 
134
- $ framein ship
135
- build ok · tests passed
136
- risk high: auth/ touched
137
- status ready with human gate
138
- ```
42
+ [![Framein demo: challenge and handoff across AI coding agents](docs/assets/framein-demo-storyboard.gif)](https://www.framein.dev/#demo)
139
43
 
140
- The important part is not the text UI. It is that every command writes to the same local work frame,
141
- so terminal commands, native agent wrappers, MCP tools, and the next model all read the same facts.
44
+ Challenge a plan with another model, then hand off the task without losing the local facts.
45
+ [Watch the full 30-second demo](https://www.framein.dev/#demo).
142
46
 
143
- ## Core Commands
144
-
145
- | Need | Command | What it does |
146
- |---|---|---|
147
- | Define done | `framein start "<goal>"` | Creates a Task Contract: goal, acceptance, protected areas, non-goals |
148
- | Edit the contract | `framein task show` / `framein task amend ...` | Reviews or updates the definition of done |
149
- | Get second opinion | `framein challenge "<proposal>" --run` | Asks a different reviewer role for a structured verdict, one lead response, and a decision brief |
150
- | Switch model/session | `framein capsule [agent]` | Prepares the next lead from contract, diff, validation, ADRs, and ledger |
151
- | Run validation | `framein verify` | Runs configured build/test checks and records the result |
152
- | Check risk | `framein risk` | Flags sensitive blast radius from changed files |
153
- | Decide ship readiness | `framein ship` | Enforced validation and risk gate for commit/deploy readiness |
154
- | Recover from loops | `framein rescue` | Detects repeated failures or thrash and offers options |
155
- | Save a green point | `framein checkpoint <label>` | Records the current commit as last known good |
156
-
157
- Full reference: [`docs/MANUAL.md`](docs/MANUAL.md).
158
-
159
- ## Native Agent Surface
160
-
161
- Framein installs logic-less wrappers into the tools agents already understand:
162
-
163
- | Host | Surface | Example |
164
- |---|---|---|
165
- | Claude / Gemini | slash commands | `/fr:verify`, `/fr:ship`, `/fr:risk` |
166
- | Codex | project skills | `$fr-verify`, `$fr-ship`, `$fr-capsule` |
167
- | Terminal / CI | CLI + JSON | `framein ship --json` |
168
- | MCP-capable clients | local stdio MCP server | `framein mcp serve` |
169
-
170
- The generated agent commands expose the same agent-facing verbs across hosts:
171
-
172
- | Intent | Claude / Gemini | Codex skill |
173
- |---|---|---|
174
- | Start or reset the task contract | `/fr:start` | `$fr-start` |
175
- | Run build/test validation | `/fr:verify` | `$fr-verify` |
176
- | Check commit/deploy readiness | `/fr:ship` | `$fr-ship` |
177
- | Detect a repair loop | `/fr:rescue` | `$fr-rescue` |
178
- | Read current Framein state | `/fr:status` | `$fr-status` |
179
- | Ask an independent model to review | `/fr:challenge` | `$fr-challenge` |
180
- | Check changed-file risk | `/fr:risk` | `$fr-risk` |
181
- | Show or amend the task contract | `/fr:task` | `$fr-task` |
182
- | Prepare a model switch | `/fr:capsule` | `$fr-capsule` |
183
- | Resolve a reviewer debate | `/fr:decide` | `$fr-decide` |
184
-
185
- The wrappers do not contain product logic. They call the same local `framein` engine, so a command
186
- invoked from an agent, a terminal, or CI reads and writes the same contract, validation results, risk, and ledger.
187
- Agent-native `challenge` wrappers add `--run --by <host>` internally, so users call `/fr:challenge`
188
- or `$fr-challenge` without manually typing those flags. Codex repo skills are generated under
189
- `.agents/skills/fr-<verb>/SKILL.md`.
190
-
191
- Windows note: generated wrappers use `framein.cmd` to avoid PowerShell execution-policy failures from
192
- the npm `.ps1` shim inside agent shells.
193
-
194
- ## How It Works
195
-
196
- ```text
197
- framein.store.json (git-friendly snapshot) <-> .frame/store.db (local cache)
198
- |
199
- v
200
- Task Contract · ADRs · memory · write locks · ledger · validation results
201
- |
202
- v
203
- managed block projection
204
- |
205
- +--> CLAUDE.md
206
- +--> AGENTS.md
207
- +--> GEMINI.md
208
- ```
209
-
210
- Important behavior:
211
-
212
- - `framein init` creates `.frame/store.db`, projects managed blocks, and ensures `.frame/` is ignored.
213
- - `framein export` writes `framein.store.json` when you want a git-canonical text snapshot.
214
- - Managed blocks are byte-identical across native context files.
215
- - User-authored text outside managed markers is preserved.
216
- - ADRs are append-only; corrections use superseding records.
217
- - Write locks are atomic conditional upserts with TTL.
218
- - Runtime dependencies stay at zero.
219
-
220
- ## Trust Boundary
221
-
222
- Framein is local-first:
223
-
224
- - No provider credentials are collected.
225
- - No remote credential relay or subscription pooling.
226
- - Claude, Codex, and Gemini keep their official CLI authentication.
227
- - Existing MCP servers and skills are detected/recommended, not proxied or cross-executed.
228
- - No terminal I/O (TTY) screen-scraping.
229
- - `framein trust` previews permission-bypass flags; it does not silently enable them.
230
- - Destructive recovery uses explicit flags, for example `framein rewind --force`.
231
- - Deployment remains a human gate.
232
-
233
- ## Current Status
234
-
235
- Solid in the current pre-release:
236
-
237
- - Store, import/export, managed-block projection
238
- - Task Contract, Verification Gate, Risk Gate, Rescue, Capsule, Challenge/Decide
239
- - Logic-less `/fr:*` and `$fr-*` wrappers
240
- - MCP stdio server and registration helpers
241
- - Headless delegation to real CLIs where available
242
- - Windows author environment live-verified
243
- - `249` automated tests passing as of 2026-06-28
244
-
245
- Still being validated:
246
-
247
- - signed standalone executable release hardening for Windows and macOS
248
- - multi-developer workflows
249
- - interactive lobby paths such as `/lead`, `/go`, and inline command palette
250
-
251
- ## Development
252
-
253
- ```bash
254
- npm install
255
- npm run build
256
- npm test
257
- ```
258
-
259
- Tests compile first and run from `dist/` through Node's built-in test runner.
260
-
261
- Useful focused commands:
262
-
263
- ```bash
264
- node --no-warnings --test dist/store.test.js
265
- node --no-warnings --test --test-name-pattern="supersede" dist/**/*.test.js
266
- node --no-warnings dist/cli.js <cmd>
267
- ```
268
-
269
- Node **22.5.0+** is required because Framein uses built-in `node:sqlite`.
270
-
271
- ## Documentation
272
-
273
- - Manual: [`docs/MANUAL.md`](docs/MANUAL.md)
274
- - FAQ: [`docs/FAQ.md`](docs/FAQ.md)
275
- - Korean manual backup: [`docs/MANUAL.ko.md`](docs/MANUAL.ko.md)
276
- - Install troubleshooting: [`docs/INSTALL.md`](docs/INSTALL.md) / [`docs/INSTALL.ko.md`](docs/INSTALL.ko.md)
277
- - Website: [framein.dev](https://www.framein.dev)
278
-
279
- ## License
280
-
281
- MIT. Framein by [Frameout](https://frameout.co.kr).
282
-
283
- Please keep the copyright and license notice when redistributing substantial
284
- portions of Framein. See [`NOTICE`](NOTICE) for suggested attribution and brand
285
- usage notes.
47
+ ## Why Framein?
48
+
49
+ Good PRDs, plans, ADRs, and skill packs help any model do better work. That is useful, and Framein is
50
+ designed to coexist with it.
51
+
52
+ The pain Framein targets starts when the work has to survive beyond one model or one clean session:
53
+
54
+ - Your lead model gets stuck and repeats the same approach.
55
+ - You want a different model to challenge the plan, diff, or risk.
56
+ - You need to switch lead model because of quota, model fit, or a dead end.
57
+ - The agent says the task is done before build and tests ran.
58
+ - The next session gets a chat summary instead of the actual contract, validation state, failed attempts, and decisions.
59
+
60
+ Framein does not replace the coding agent or pretend to be a full multi-agent cockpit. It keeps one
61
+ local work frame under the agents you already use.
62
+
63
+ ## Quick Start
64
+
65
+ npm is the supported cross-platform install path today:
66
+
67
+ ```bash
68
+ npm install -g framein
69
+ framein --version
70
+ ```
71
+
72
+ Standalone executables are planned as an additional convenience path, mainly for users who do not
73
+ want to install Node/npm or who want to avoid Windows npm shim and PowerShell execution-policy
74
+ friction. They are not required to use Framein today. See
75
+ [Install notes](docs/INSTALL.md#6-standalone-executables).
76
+
77
+ If you want to test a local checkout instead:
78
+
79
+ ```bash
80
+ git clone https://github.com/framein-dev/framein.git
81
+ cd framein
82
+ npm install
83
+ npm run build
84
+ npm install -g .
85
+ ```
86
+
87
+ Initialize a project:
88
+
89
+ ```bash
90
+ cd your-project
91
+ framein init
92
+ framein integrations install all --write
93
+ ```
94
+
95
+ Run the work loop:
96
+
97
+ ```bash
98
+ framein start "add Google OAuth, keep email login"
99
+ framein verify
100
+
101
+ # When another model should review or continue:
102
+ framein challenge "review the OAuth callback plan" --run
103
+ framein capsule codex
104
+
105
+ framein ship
106
+ ```
107
+
108
+ Use `challenge` when another model should review a claim or plan. In a live run, the reviewer returns
109
+ a structured verdict, the lead gets one bounded response, and Framein prints a decision brief for the
110
+ user to accept or reject. Use `capsule <agent>` when a different model should continue from the same
111
+ local facts. After the current CLI exits, Framein launches the next agent with a short handoff prompt;
112
+ the new agent still pulls facts with `framein capsule`. `verify` is a rehearsal; `ship` is the
113
+ enforced gate and exits non-zero when hard validation fails.
114
+
115
+ ## What You See
116
+
117
+ ```text
118
+ $ framein start "add Google OAuth, keep email login"
119
+ task contract
120
+ goal add Google OAuth, keep email login
121
+ preserve existing email login
122
+
123
+ $ framein challenge "OAuth callback stores state in session" --run
124
+ reviewer codex
125
+ verdict challenge
126
+ required add nonce/state validation
127
+ lead accepts required change
128
+ next framein decide accept "add nonce/state validation"
129
+
130
+ $ framein capsule gemini
131
+ next lead prepared from facts:
132
+ contract · diff · tests · decisions
133
+ exit the current agent; gemini opens and pulls the capsule first
134
+
135
+ $ framein ship
136
+ build ok · tests passed
137
+ risk high: auth/ touched
138
+ status ready with human gate
139
+ ```
140
+
141
+ The important part is not the text UI. It is that every command writes to the same local work frame,
142
+ so terminal commands, native agent wrappers, MCP tools, and the next model all read the same facts.
143
+
144
+ ## Core Commands
145
+
146
+ | Need | Command | What it does |
147
+ |---|---|---|
148
+ | Define done | `framein start "<goal>"` | Creates a Task Contract: goal, acceptance, protected areas, non-goals |
149
+ | Edit the contract | `framein task show` / `framein task amend ...` | Reviews or updates the definition of done |
150
+ | Get second opinion | `framein challenge "<proposal>" --run` | Asks a different reviewer role for a structured verdict, one lead response, and a decision brief |
151
+ | Switch model/session | `framein capsule [agent]` | Prepares the next lead from contract, diff, validation, ADRs, and ledger |
152
+ | Run validation | `framein verify` | Runs configured build/test checks and records the result |
153
+ | Check risk | `framein risk` | Flags sensitive blast radius from changed files |
154
+ | Decide ship readiness | `framein ship` | Enforced validation and risk gate for commit/deploy readiness |
155
+ | Recover from loops | `framein rescue` | Detects repeated failures or thrash and offers options |
156
+ | Save a green point | `framein checkpoint <label>` | Records the current commit as last known good |
157
+
158
+ Full reference: [`docs/MANUAL.md`](docs/MANUAL.md).
159
+
160
+ ## Native Agent Surface
161
+
162
+ Framein installs logic-less wrappers into the tools agents already understand:
163
+
164
+ | Host | Surface | Example |
165
+ |---|---|---|
166
+ | Claude / Gemini | slash commands | `/fr:verify`, `/fr:ship`, `/fr:risk` |
167
+ | Codex | project skills | `$fr-verify`, `$fr-ship`, `$fr-capsule` |
168
+ | Terminal / CI | CLI + JSON | `framein ship --json` |
169
+ | MCP-capable clients | local stdio MCP server | `framein mcp serve` |
170
+
171
+ The generated agent commands expose the same agent-facing verbs across hosts:
172
+
173
+ | Intent | Claude / Gemini | Codex skill |
174
+ |---|---|---|
175
+ | Start or reset the task contract | `/fr:start` | `$fr-start` |
176
+ | Run build/test validation | `/fr:verify` | `$fr-verify` |
177
+ | Check commit/deploy readiness | `/fr:ship` | `$fr-ship` |
178
+ | Detect a repair loop | `/fr:rescue` | `$fr-rescue` |
179
+ | Read current Framein state | `/fr:status` | `$fr-status` |
180
+ | Ask an independent model to review | `/fr:challenge` | `$fr-challenge` |
181
+ | Check changed-file risk | `/fr:risk` | `$fr-risk` |
182
+ | Show or amend the task contract | `/fr:task` | `$fr-task` |
183
+ | Prepare a model switch | `/fr:capsule` | `$fr-capsule` |
184
+ | Resolve a reviewer debate | `/fr:decide` | `$fr-decide` |
185
+
186
+ The wrappers do not contain product logic. They call the same local `framein` engine, so a command
187
+ invoked from an agent, a terminal, or CI reads and writes the same contract, validation results, risk, and ledger.
188
+ Agent-native `challenge` wrappers add `--run --by <host>` internally, so users call `/fr:challenge`
189
+ or `$fr-challenge` without manually typing those flags. Codex repo skills are generated under
190
+ `.agents/skills/fr-<verb>/SKILL.md`.
191
+
192
+ Windows note: generated wrappers use `framein.cmd` to avoid PowerShell execution-policy failures from
193
+ the npm `.ps1` shim inside agent shells.
194
+
195
+ ## How It Works
196
+
197
+ ```text
198
+ framein.store.json (git-friendly snapshot) <-> .frame/store.db (local cache)
199
+ |
200
+ v
201
+ Task Contract · ADRs · memory · write locks · ledger · validation results
202
+ |
203
+ v
204
+ managed block projection
205
+ |
206
+ +--> CLAUDE.md
207
+ +--> AGENTS.md
208
+ +--> GEMINI.md
209
+ ```
210
+
211
+ Important behavior:
212
+
213
+ - `framein init` creates `.frame/store.db`, projects managed blocks, and ensures `.frame/` is ignored.
214
+ - `framein export` writes `framein.store.json` when you want a git-canonical text snapshot.
215
+ - Managed blocks are byte-identical across native context files.
216
+ - User-authored text outside managed markers is preserved.
217
+ - ADRs are append-only; corrections use superseding records.
218
+ - Write locks are atomic conditional upserts with TTL.
219
+ - Runtime dependencies stay at zero.
220
+
221
+ ## Trust Boundary
222
+
223
+ Framein is local-first:
224
+
225
+ - No provider credentials are collected.
226
+ - No remote credential relay or subscription pooling.
227
+ - Claude, Codex, and Gemini keep their official CLI authentication.
228
+ - Existing MCP servers and skills are detected/recommended, not proxied or cross-executed.
229
+ - No terminal I/O (TTY) screen-scraping.
230
+ - `framein trust` previews permission-bypass flags; it does not silently enable them.
231
+ - Destructive recovery uses explicit flags, for example `framein rewind --force`.
232
+ - Deployment remains a human gate.
233
+
234
+ ## Current Status
235
+
236
+ Solid in the current pre-release:
237
+
238
+ - Store, import/export, managed-block projection
239
+ - Task Contract, Verification Gate, Risk Gate, Rescue, Capsule, Challenge/Decide
240
+ - Logic-less `/fr:*` and `$fr-*` wrappers
241
+ - MCP stdio server and registration helpers
242
+ - Headless delegation to real CLIs where available
243
+ - Windows author environment live-verified
244
+ - `249` automated tests passing as of 2026-06-28
245
+
246
+ Still being validated:
247
+
248
+ - signed standalone executable release hardening for Windows and macOS
249
+ - multi-developer workflows
250
+ - interactive lobby paths such as `/lead`, `/go`, and inline command palette
251
+
252
+ ## Development
253
+
254
+ ```bash
255
+ npm install
256
+ npm run build
257
+ npm test
258
+ ```
259
+
260
+ Tests compile first and run from `dist/` through Node's built-in test runner.
261
+
262
+ Useful focused commands:
263
+
264
+ ```bash
265
+ node --no-warnings --test dist/store.test.js
266
+ node --no-warnings --test --test-name-pattern="supersede" dist/**/*.test.js
267
+ node --no-warnings dist/cli.js <cmd>
268
+ ```
269
+
270
+ Node **22.5.0+** is required because Framein uses built-in `node:sqlite`.
271
+
272
+ ## Documentation
273
+
274
+ - Manual: [`docs/MANUAL.md`](docs/MANUAL.md)
275
+ - FAQ: [`docs/FAQ.md`](docs/FAQ.md)
276
+ - Korean manual backup: [`docs/MANUAL.ko.md`](docs/MANUAL.ko.md)
277
+ - Install troubleshooting: [`docs/INSTALL.md`](docs/INSTALL.md) / [`docs/INSTALL.ko.md`](docs/INSTALL.ko.md)
278
+ - Website: [framein.dev](https://www.framein.dev)
279
+
280
+ ## License
281
+
282
+ MIT. Framein by [Frameout](https://frameout.co.kr).
283
+
284
+ Please keep the copyright and license notice when redistributing substantial
285
+ portions of Framein. See [`NOTICE`](NOTICE) for suggested attribution and brand
286
+ usage notes.
package/dist/adr.js CHANGED
@@ -1,17 +1,17 @@
1
- // ADR digest: a compact index embedded into the projected native files.
2
- // Full ADRs live in the store (queried live via MCP); files carry only a digest.
3
- export function buildAdrDigest(adrs, opts = {}) {
4
- if (adrs.length === 0)
5
- return '_No decisions recorded yet._';
6
- const max = opts.max ?? 10;
7
- // Derived (append-only): an ADR is superseded only if a LATER one references it.
8
- const supersededIds = new Set(adrs.filter((a) => a.supersedes != null && a.id > a.supersedes).map((a) => a.supersedes));
9
- const recent = [...adrs].sort((a, b) => b.id - a.id).slice(0, max);
10
- const lines = recent.map((a) => {
11
- const status = supersededIds.has(a.id) ? 'superseded' : a.status;
12
- return `- [ADR-${a.id}] ${a.title} (${status})`;
13
- });
14
- const overflow = adrs.length > recent.length
15
- ? `\n- …and ${adrs.length - recent.length} earlier decision(s)` : '';
16
- return `${adrs.length} decision(s) recorded. Latest:\n${lines.join('\n')}${overflow}`;
17
- }
1
+ // ADR digest: a compact index embedded into the projected native files.
2
+ // Full ADRs live in the store (queried live via MCP); files carry only a digest.
3
+ export function buildAdrDigest(adrs, opts = {}) {
4
+ if (adrs.length === 0)
5
+ return '_No decisions recorded yet._';
6
+ const max = opts.max ?? 10;
7
+ // Derived (append-only): an ADR is superseded only if a LATER one references it.
8
+ const supersededIds = new Set(adrs.filter((a) => a.supersedes != null && a.id > a.supersedes).map((a) => a.supersedes));
9
+ const recent = [...adrs].sort((a, b) => b.id - a.id).slice(0, max);
10
+ const lines = recent.map((a) => {
11
+ const status = supersededIds.has(a.id) ? 'superseded' : a.status;
12
+ return `- [ADR-${a.id}] ${a.title} (${status})`;
13
+ });
14
+ const overflow = adrs.length > recent.length
15
+ ? `\n- …and ${adrs.length - recent.length} earlier decision(s)` : '';
16
+ return `${adrs.length} decision(s) recorded. Latest:\n${lines.join('\n')}${overflow}`;
17
+ }