@mumbrane/arrakis 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,16 @@
1
1
  # arrakis
2
2
 
3
- A coding agent for your terminal, built by Mumbrane. It reads your code, edits files and runs commands, asking before anything that changes your machine.
3
+ A coding agent for your terminal, built by Mumbrane. It reads your code, edits files and runs commands, asking before anything that changes your machine. It works with Claude, GPT, Gemini, Grok, DeepSeek, Mistral, local models and more.
4
+
5
+ - **Sub-agents:** hands big jobs to parallel agents with their own fresh context
6
+ - **Plan mode:** investigates and proposes a plan before touching anything
7
+ - **Task lists:** tracks multi-step work as it goes
8
+ - **Undo:** every file change is checkpointed; `/undo` puts things back
9
+ - **MCP:** plug in GitHub, databases, Slack and any other MCP server
10
+ - **Images:** attach screenshots and mockups
11
+ - **Background jobs:** hand off a task and close the terminal
12
+ - **Hooks:** run your own scripts before or after the agent's actions
13
+ - **Crash-safe sessions:** every step is logged; pick up exactly where you left off
4
14
 
5
15
  ## Install
6
16
 
@@ -42,7 +52,14 @@ In a session:
42
52
 
43
53
  | Command | What it does |
44
54
  |---|---|
45
- | `/help` | List commands |
55
+ | `/help` | List commands (including your own) |
56
+ | `/plan` | Plan mode: investigate and propose, change nothing; `/plan` again to approve |
57
+ | `/init` | Write `ARRAKIS.md` project notes for this folder |
58
+ | `/todos` | Show the current task list |
59
+ | `/undo [n]` | Revert arrakis's file changes from the last turn (or pick a turn) |
60
+ | `/paste` | Attach the image on your clipboard (macOS) |
61
+ | `/mcp` | Show connected MCP servers and their tools |
62
+ | `/bg <task>` / `/jobs` | Start a background job / check on jobs |
46
63
  | `/status` | Session, model, context usage, permissions |
47
64
  | `/compact` | Summarize history to free up context |
48
65
  | `/model [name]` | Pick a model from your provider |
@@ -51,17 +68,68 @@ In a session:
51
68
  | `/yolo` | Toggle running tool calls without asking |
52
69
  | `/exit` | Quit (or Ctrl-D) |
53
70
 
54
- Ctrl-C interrupts the model mid-response. End a line with `\` to keep typing on the next line.
71
+ Type `@path/to/file` to attach a file (or folder listing) to your message; images (`@screenshot.png`, or drag one into the terminal) are sent to the model too. Tab completes commands and `@` paths, and ↑ recalls earlier messages, even from past sessions. Esc or Ctrl-C interrupts the model mid-response. End a line with `\` to keep typing on the next line.
72
+
73
+ ### Custom commands
74
+
75
+ Put a Markdown file in `.arrakis/commands/` (per project) or `~/.arrakis/commands/` (everywhere) and it becomes a slash command. `.arrakis/commands/review.md` becomes `/review`; `$ARGUMENTS` in the file is replaced with whatever you type after the command.
55
76
 
56
77
  ## Tools
57
78
 
58
79
  | Tool | Asks first |
59
80
  |---|---|
60
81
  | `read_file`, `grep`, `list_files` | No |
61
- | `write_file`, `edit_file`, `bash` | Yes: answer `y`, `a` (always, for this session) or `n` |
82
+ | `todo_write` (task list), `task` (sub-agents) | No |
83
+ | `write_file`, `edit_file`, `bash`, `web_fetch` | Yes: answer `y`, `a` (always, for this session) or `n` |
84
+
85
+ Sub-agents of type `explore` (the default) can only read and search. `general` sub-agents can also edit and run commands, and they ask permission the same way.
62
86
 
63
87
  `-p` mode denies tools that need permission unless you pass `--yolo` or `--allow edit_file,write_file,bash`.
64
88
 
89
+ ## Undo
90
+
91
+ Before arrakis writes or edits a file, it saves the original. `/undo` reverts the last turn's changes; with several turns it lets you pick how far back to go. Checkpoints are stored with the session, so undo still works after `arrakis -c`. Changes made by shell commands (`bash`) aren't tracked, so use git for those.
92
+
93
+ ## MCP servers
94
+
95
+ Connect any [Model Context Protocol](https://modelcontextprotocol.io) server, local or remote:
96
+
97
+ ```bash
98
+ arrakis mcp add github -- npx -y @modelcontextprotocol/server-github
99
+ arrakis mcp add docs --url https://example.com/mcp
100
+ arrakis mcp # check they connect and list their tools
101
+ ```
102
+
103
+ Servers live in `~/.arrakis/mcp.json` using the standard `mcpServers` format, so configs from other tools work as-is. Add API keys under `"env"` (local servers) or `"headers"` (remote ones); `${VAR}` reads from your environment. A project can ship servers in `.mcp.json` or `.arrakis/mcp.json`; arrakis asks before trusting a folder's servers the first time. MCP tools ask permission before running unless the server marks them read-only.
104
+
105
+ ## Background jobs
106
+
107
+ ```bash
108
+ arrakis bg "audit the dependencies for known vulnerabilities and write a report to AUDIT.md" --allow write_file
109
+ arrakis jobs # list jobs
110
+ arrakis jobs log job-3fa2c1 -f # follow one
111
+ arrakis jobs stop job-3fa2c1
112
+ ```
113
+
114
+ Jobs keep running after you close the terminal. With no flags they can read and search but not change anything; `--allow` lets specific tools through and `--yolo` allows everything. Each job has a session, so `arrakis -r <session>` continues the conversation afterwards. Inside a session, `/bg <task>` starts one with the same permissions you've granted so far.
115
+
116
+ ## Hooks
117
+
118
+ Run your own commands at points in the agent's work, in `~/.arrakis/config.json` (or `.arrakis/settings.json` in a project, which asks before first use):
119
+
120
+ ```json
121
+ {
122
+ "hooks": {
123
+ "PreToolUse": [{ "matcher": "bash", "command": "./scripts/check-command.sh" }],
124
+ "PostToolUse": [{ "matcher": "edit_file|write_file", "command": "npx prettier --write \"$ARRAKIS_FILE\"" }],
125
+ "UserPromptSubmit": [{ "command": "git status --short" }],
126
+ "Stop": [{ "command": "say done" }]
127
+ }
128
+ }
129
+ ```
130
+
131
+ Each hook gets the event as JSON on stdin and `ARRAKIS_EVENT`, `ARRAKIS_TOOL` and `ARRAKIS_FILE` in its environment. A `PreToolUse` hook that exits with code 2 blocks the tool, and its stderr is shown to the model as the reason. `UserPromptSubmit` output is added to your message as context.
132
+
65
133
  ## Project instructions
66
134
 
67
135
  Put an `ARRAKIS.md` (or `AGENTS.md`) in your repo to tell the agent how your project works: build commands, conventions, things to avoid. Arrakis reads these files from the current directory and its parents, plus `~/.arrakis/ARRAKIS.md` for global instructions.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mumbrane/arrakis",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Arrakis: a coding agent for your terminal, built by Mumbrane",
5
5
  "type": "module",
6
6
  "main": "./index.js",
package/src/agent.js CHANGED
@@ -1,27 +1,60 @@
1
1
  import { streamChat, completeText } from './client.js';
2
- import { toolSchemas, executeToolCall, truncate } from './tools.js';
2
+ import { toolSchemas, executeToolCall, truncate, READ_ONLY_TOOLS, PARALLEL_SAFE } from './tools.js';
3
3
  import { buildSystemPrompt } from './prompt.js';
4
+ import { Session } from './session.js';
4
5
 
5
- const MAX_STEPS = 200;
6
+ const MAX_STEPS = 400;
7
+ const MAX_SUB_STEPS = 150;
6
8
  const COMPACT_AT = 0.8;
7
9
  const KEEP_RECENT = 6;
8
10
 
9
- export const estimateTokens = (messages) => Math.ceil(JSON.stringify(messages).length / 4);
11
+ // Rough token count: ~4 characters per token, ~1600 tokens per image.
12
+ export function estimateTokens(messages) {
13
+ let chars = 0;
14
+ for (const m of messages) {
15
+ if (Array.isArray(m.content)) for (const p of m.content) chars += p.type === 'image_url' ? 6400 : String(p.text ?? '').length;
16
+ else chars += String(m.content ?? '').length;
17
+ if (m.tool_calls) chars += JSON.stringify(m.tool_calls).length;
18
+ chars += 16;
19
+ }
20
+ return Math.ceil(chars / 4);
21
+ }
22
+
23
+ const textOf = (content) => (Array.isArray(content) ? content.map((p) => (p.type === 'text' ? p.text : '[image]')).join('\n') : String(content ?? ''));
10
24
 
11
25
  export class Agent {
12
- constructor({ config, session, ui, permissions, cwd }) {
26
+ // depth 0 is the agent the user talks to; sub-agents have depth >= 1.
27
+ constructor({ config, session, ui, permissions, cwd, depth = 0, label = '', toolFilter = null, checkpoints = null, hooks = null }) {
13
28
  this.config = config;
14
29
  this.session = session;
15
30
  this.ui = ui;
16
31
  this.permissions = permissions;
17
32
  this.cwd = cwd;
33
+ this.depth = depth;
34
+ this.label = label;
35
+ this.toolFilter = toolFilter;
36
+ this.checkpoints = checkpoints;
37
+ this.hooks = hooks;
38
+ this.notes = []; // things to tell the model with the next message (e.g. an undo)
18
39
  this.abort = null;
40
+ this.todos = [];
41
+ this.toolCount = 0;
42
+ this.lastError = null;
19
43
  }
20
44
 
21
45
  get busy() {
22
46
  return this.abort !== null;
23
47
  }
24
48
 
49
+ get silent() {
50
+ return this.depth > 0;
51
+ }
52
+
53
+ allowsTool(name) {
54
+ if (this.depth > 0 && (name === 'task' || name === 'todo_write')) return false;
55
+ return this.toolFilter ? this.toolFilter(name) : true;
56
+ }
57
+
25
58
  interrupt() {
26
59
  if (!this.abort) return;
27
60
  this.abort.abort();
@@ -29,52 +62,143 @@ export class Agent {
29
62
  }
30
63
 
31
64
  // Run one user turn to completion. Returns true on success.
32
- async send(text) {
33
- this.session.add({ role: 'user', content: text });
65
+ async send(input, { parentSignal } = {}) {
66
+ let content = input;
67
+ if (this.depth === 0 && this.hooks) {
68
+ const text = typeof input === 'string' ? input : input.find((p) => p.type === 'text')?.text ?? '';
69
+ const hook = await this.hooks.run('UserPromptSubmit', { prompt: text, sessionId: this.session.id });
70
+ if (hook.blocked) {
71
+ this.ui.error(`Message blocked by a hook: ${hook.reason}`);
72
+ return false;
73
+ }
74
+ if (hook.output) this.notes.push(`<hook-context>\n${hook.output}\n</hook-context>`);
75
+ }
76
+ if (this.notes.length) {
77
+ const note = this.notes.splice(0).join('\n');
78
+ content = typeof input === 'string' ? `${input}\n\n${note}` : [...input, { type: 'text', text: note }];
79
+ }
80
+ this.session.add({ role: 'user', content });
81
+ if (this.depth === 0) this.checkpoints?.beginTurn(typeof input === 'string' ? input : input.find((p) => p.type === 'text')?.text ?? '(message)');
34
82
  this.abort = new AbortController();
35
83
  const signal = this.abort.signal;
84
+ const onParentAbort = () => this.abort?.abort();
85
+ parentSignal?.addEventListener('abort', onParentAbort, { once: true });
86
+ if (!this.silent) this.ui.setBusy(true);
36
87
  try {
37
- for (let step = 0; step < MAX_STEPS; step++) {
88
+ const limit = this.depth > 0 ? MAX_SUB_STEPS : MAX_STEPS;
89
+ for (let step = 0; step < limit; step++) {
38
90
  await this.maybeCompact(signal);
39
91
  const msg = await this.callModel(signal);
40
- if (!msg.tool_calls?.length) return true;
41
- for (const call of msg.tool_calls) {
42
- const content = signal.aborted
43
- ? 'Interrupted by the user before this tool ran.'
44
- : await executeToolCall(call, { cwd: this.cwd, signal, ui: this.ui, permissions: this.permissions });
45
- this.session.add({ role: 'tool', tool_call_id: call.id, content });
92
+ if (!msg.tool_calls?.length) {
93
+ if (this.depth === 0 && this.hooks) await this.hooks.run('Stop', { sessionId: this.session.id });
94
+ return true;
46
95
  }
96
+ await this.runTools(msg.tool_calls, signal);
47
97
  if (signal.aborted) throw new DOMException('Interrupted', 'AbortError');
48
98
  }
49
- this.ui.error(`Stopped after ${MAX_STEPS} steps.`);
99
+ this.lastError = `Stopped after ${limit} steps.`;
100
+ if (!this.silent) this.ui.error(this.lastError);
50
101
  return false;
51
102
  } catch (err) {
52
- if (err.name === 'AbortError') this.ui.info('Interrupted.');
53
- else if (err.status === 401 || err.status === 403) this.ui.error(`${err.message}\nYour API key was rejected. Run /provider (or: arrakis setup) to update it.`);
103
+ this.lastError = err.name === 'AbortError' ? 'Interrupted.' : err.message;
104
+ if (this.silent) return false;
105
+ if (err.name === 'AbortError') this.ui.info('Interrupted. Tell arrakis what to do differently, or keep going.');
106
+ else if (err.status === 401 || err.status === 403) this.ui.error(`${err.message}\nYour API key was rejected. Run /provider to update it.`);
54
107
  else if (err.status === 404) this.ui.error(`${err.message}\nThe model may not exist for this provider. Pick another with /model.`);
55
108
  else this.ui.error(err.message);
56
109
  return false;
57
110
  } finally {
58
- this.ui.endText();
111
+ parentSignal?.removeEventListener('abort', onParentAbort);
112
+ if (this.depth === 0) this.checkpoints?.endTurn();
113
+ if (!this.silent) {
114
+ this.ui.stopSpinner();
115
+ this.ui.endText();
116
+ this.ui.setBusy(false);
117
+ }
59
118
  this.abort = null;
60
119
  this.session.repair();
61
120
  }
62
121
  }
63
122
 
123
+ async runTools(calls, signal) {
124
+ const ctx = {
125
+ cwd: this.cwd,
126
+ signal,
127
+ ui: this.ui,
128
+ permissions: this.permissions,
129
+ agent: this,
130
+ depth: this.depth,
131
+ label: this.label,
132
+ allowed: (name) => this.allowsTool(name),
133
+ checkpoints: this.checkpoints,
134
+ hooks: this.hooks,
135
+ sessionId: this.session.id,
136
+ };
137
+ this.toolCount += calls.length;
138
+ const parallel = calls.length > 1 && calls.every((c) => PARALLEL_SAFE.has(c.function?.name));
139
+ let results;
140
+ if (parallel) {
141
+ results = await Promise.all(calls.map((call) => executeToolCall(call, ctx)));
142
+ } else {
143
+ results = [];
144
+ for (const call of calls) {
145
+ results.push(signal.aborted ? 'Interrupted by the user before this tool ran.' : await executeToolCall(call, ctx));
146
+ }
147
+ }
148
+ if (!this.silent) this.ui.stopSpinner();
149
+ calls.forEach((call, i) => this.session.add({ role: 'tool', tool_call_id: call.id, content: results[i] }));
150
+ }
151
+
152
+ async runSubagent({ description = 'sub-task', prompt, agent_type = 'explore' }, signal) {
153
+ if (!prompt) throw new Error('prompt is required');
154
+ const readOnly = agent_type !== 'general';
155
+ const sub = new Agent({
156
+ config: this.config,
157
+ session: Session.memory(),
158
+ ui: this.ui,
159
+ permissions: this.permissions,
160
+ cwd: this.cwd,
161
+ depth: this.depth + 1,
162
+ label: description,
163
+ toolFilter: readOnly ? (name) => READ_ONLY_TOOLS.has(name) : null,
164
+ checkpoints: this.checkpoints,
165
+ hooks: this.hooks,
166
+ });
167
+ sub.subagentType = readOnly ? 'explore' : 'general';
168
+ const started = Date.now();
169
+ const ok = await sub.send(prompt, { parentSignal: signal });
170
+ const secs = Math.round((Date.now() - started) / 1000);
171
+ const report = [...sub.session.messages].reverse().find((m) => m.role === 'assistant' && m.content)?.content ?? '';
172
+ const stats = `${sub.toolCount} tool use${sub.toolCount === 1 ? '' : 's'} · ${secs}s`;
173
+ if (!ok) {
174
+ return { content: `Sub-agent "${description}" did not finish: ${sub.lastError}\n\nPartial report:\n${report || '(none)'}`, display: `${description}: stopped, ${sub.lastError} (${stats})` };
175
+ }
176
+ return { content: report || '(The sub-agent returned no report.)', display: `${description}: done (${stats})` };
177
+ }
178
+
64
179
  async callModel(signal) {
65
- const messages = [{ role: 'system', content: buildSystemPrompt({ cwd: this.cwd, model: this.config.model }) }, ...this.session.messages];
180
+ const system = buildSystemPrompt({
181
+ cwd: this.cwd,
182
+ model: this.config.model,
183
+ planMode: this.permissions.planMode,
184
+ subagent: this.depth > 0 ? { type: this.subagentType } : null,
185
+ });
186
+ const messages = [{ role: 'system', content: system }, ...this.session.messages];
66
187
  let content = '';
67
188
  const calls = [];
68
- this.ui.startResponse();
189
+ if (!this.silent) {
190
+ this.ui.startResponse();
191
+ this.ui.startSpinner();
192
+ }
69
193
  try {
70
- for await (const event of streamChat({ config: this.config, messages, tools: toolSchemas(), signal })) {
194
+ for await (const event of streamChat({ config: this.config, messages, tools: toolSchemas((n) => this.allowsTool(n)), signal })) {
71
195
  const delta = event.choices?.[0]?.delta;
72
196
  if (!delta) continue;
73
197
  const reasoning = delta.reasoning_content ?? delta.reasoning;
74
- if (reasoning) this.ui.thinking(reasoning);
198
+ if (reasoning && !this.silent) this.ui.thinking(reasoning);
75
199
  if (delta.content) {
76
200
  content += delta.content;
77
- this.ui.text(delta.content);
201
+ if (!this.silent) this.ui.text(delta.content);
78
202
  }
79
203
  for (const tc of delta.tool_calls ?? []) {
80
204
  const idx = tc.index ?? (tc.id ? calls.length : Math.max(0, calls.length - 1));
@@ -85,7 +209,7 @@ export class Agent {
85
209
  }
86
210
  }
87
211
  } finally {
88
- this.ui.endText();
212
+ if (!this.silent) this.ui.endText();
89
213
  }
90
214
  const toolCalls = calls.filter(Boolean).map((c, i) => ({ ...c, id: c.id || `call_${Date.now()}_${i}` }));
91
215
  const msg = { role: 'assistant', content: content || (toolCalls.length ? null : '') };
@@ -98,7 +222,6 @@ export class Agent {
98
222
  const messages = this.session.messages;
99
223
  if (!force && estimateTokens(messages) < this.config.contextWindow * COMPACT_AT) return false;
100
224
  // Cut at a user message so tool calls stay paired with their results.
101
- // A manual /compact keeps only the last exchange; automatic keeps a bit more.
102
225
  const keep = force ? 2 : KEEP_RECENT;
103
226
  let cut = -1;
104
227
  for (let i = messages.length - 1; i > 0; i--) {
@@ -110,8 +233,8 @@ export class Agent {
110
233
  if (cut <= 0) {
111
234
  for (let i = messages.length - 1; i > 0; i--) if (messages[i].role === 'user') { cut = i; break; }
112
235
  }
113
- if (cut <= 0) return false;
114
- this.ui.info('Compacting conversation history…');
236
+ if (cut <= 0) return this.trimToolResults();
237
+ if (!this.silent) this.ui.info('Compacting conversation history to free up context…');
115
238
  const transcript = messages.slice(0, cut).map(renderForSummary).join('\n\n');
116
239
  const summary = await completeText({
117
240
  config: this.config,
@@ -120,18 +243,38 @@ export class Agent {
120
243
  { role: 'system', content: 'You summarize coding-agent conversations so the work can continue with less context.' },
121
244
  {
122
245
  role: 'user',
123
- content: `Summarize this conversation between a user and a coding agent. Keep: the user's goals and instructions, decisions made, files read or changed (with paths), commands run and their important results, errors hit, and what is left to do. Be specific and concise.\n\n<conversation>\n${truncate(transcript, 400000)}\n</conversation>`,
246
+ content: `Summarize this conversation between a user and a coding agent. Keep: the user's goals and instructions, decisions made, files read or changed (with paths), commands run and their important results, errors hit, the current task list, and what is left to do. Be specific and concise.\n\n<conversation>\n${truncate(transcript, 400000)}\n</conversation>`,
124
247
  },
125
248
  ],
126
249
  });
127
250
  this.session.compact(summary.trim() || '(no summary produced)', cut);
251
+ if (estimateTokens(this.session.messages) >= this.config.contextWindow * COMPACT_AT) this.trimToolResults();
128
252
  return true;
129
253
  }
254
+
255
+ // One long turn with no user message to cut at: shorten old tool results.
256
+ trimToolResults() {
257
+ const messages = this.session.messages;
258
+ const recent = Math.max(0, messages.length - 8);
259
+ let changed = false;
260
+ const next = messages.map((m, i) => {
261
+ if (i < recent && m.role === 'tool' && typeof m.content === 'string' && m.content.length > 600) {
262
+ changed = true;
263
+ return { ...m, content: `${m.content.slice(0, 500)}\n… [older tool output trimmed to save context; re-run the tool if you need it]` };
264
+ }
265
+ return m;
266
+ });
267
+ if (changed) {
268
+ this.session.replace(next);
269
+ if (!this.silent) this.ui.info('Trimmed old tool output to free up context.');
270
+ }
271
+ return changed;
272
+ }
130
273
  }
131
274
 
132
275
  function renderForSummary(m) {
133
276
  if (m.role === 'tool') return `[tool result]\n${truncate(String(m.content ?? ''), 2000)}`;
134
- let s = `[${m.role}]\n${m.content ?? ''}`;
277
+ let s = `[${m.role}]\n${textOf(m.content)}`;
135
278
  for (const c of m.tool_calls ?? []) s += `\n(called ${c.function.name} ${truncate(c.function.arguments, 1000)})`;
136
279
  return s;
137
280
  }
@@ -0,0 +1,83 @@
1
+ // File checkpoints: before arrakis writes or edits a file, the original is
2
+ // saved. /undo puts files back the way they were before a turn. Stored next to
3
+ // the session log (<session>.checkpoints/), so undo works after a restart.
4
+ import fs from 'node:fs';
5
+ import path from 'node:path';
6
+
7
+ export class Checkpoints {
8
+ constructor(sessionFile) {
9
+ this.dir = sessionFile ? sessionFile.replace(/\.jsonl$/, '.checkpoints') : null;
10
+ this.turns = [];
11
+ this.current = null;
12
+ this.blobs = 0;
13
+ if (this.dir) {
14
+ try {
15
+ const index = JSON.parse(fs.readFileSync(path.join(this.dir, 'index.json'), 'utf8'));
16
+ this.turns = index.turns ?? [];
17
+ this.blobs = index.blobs ?? 0;
18
+ } catch {}
19
+ }
20
+ }
21
+
22
+ beginTurn(label) {
23
+ this.current = { id: (this.turns.at(-1)?.id ?? 0) + 1, label: String(label).replace(/\s+/g, ' ').slice(0, 80), time: Date.now(), files: {} };
24
+ }
25
+
26
+ // Save a file's current state the first time a turn touches it.
27
+ record(file) {
28
+ if (!this.current) this.beginTurn('(changes)');
29
+ const abs = path.resolve(file);
30
+ if (abs in this.current.files) return;
31
+ let blob = null;
32
+ if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
33
+ blob = `${++this.blobs}.bin`;
34
+ if (this.dir) {
35
+ fs.mkdirSync(this.dir, { recursive: true });
36
+ fs.copyFileSync(abs, path.join(this.dir, blob));
37
+ } else {
38
+ (this.memory ??= new Map()).set(blob, fs.readFileSync(abs));
39
+ }
40
+ }
41
+ this.current.files[abs] = blob; // null means the file didn't exist
42
+ if (!this.turns.includes(this.current)) this.turns.push(this.current);
43
+ this.save();
44
+ }
45
+
46
+ endTurn() {
47
+ this.current = null;
48
+ }
49
+
50
+ list() {
51
+ return this.turns.map((t) => ({ id: t.id, label: t.label, time: t.time, files: Object.keys(t.files) }));
52
+ }
53
+
54
+ // Undo the most recent turn with changes (or every turn back to `toId`).
55
+ undo(toId) {
56
+ const target = toId ?? this.turns.at(-1)?.id;
57
+ if (target === undefined) return [];
58
+ const restored = new Map();
59
+ while (this.turns.length && this.turns.at(-1).id >= target) {
60
+ const turn = this.turns.pop();
61
+ for (const [file, blob] of Object.entries(turn.files)) {
62
+ if (blob === null) {
63
+ fs.rmSync(file, { force: true });
64
+ restored.set(file, 'removed');
65
+ } else {
66
+ fs.mkdirSync(path.dirname(file), { recursive: true });
67
+ const data = this.dir ? fs.readFileSync(path.join(this.dir, blob)) : this.memory.get(blob);
68
+ fs.writeFileSync(file, data);
69
+ restored.set(file, 'restored');
70
+ }
71
+ }
72
+ }
73
+ this.current = null;
74
+ this.save();
75
+ return [...restored].map(([file, action]) => ({ file, action }));
76
+ }
77
+
78
+ save() {
79
+ if (!this.dir) return;
80
+ fs.mkdirSync(this.dir, { recursive: true });
81
+ fs.writeFileSync(path.join(this.dir, 'index.json'), JSON.stringify({ turns: this.turns, blobs: this.blobs }));
82
+ }
83
+ }