attraverso 0.2.0 → 0.4.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
@@ -30,12 +30,27 @@ Add it to the `.mcp.json` at the root of your repo:
30
30
  ```
31
31
 
32
32
  The plan, `attraverso.yaml`, is created at the root of the repo on first run. Commit it: it is the source of
33
- truth, and its diffs are the history of the plan. Readings and attachments go in an `.attraverso/` folder
34
- beside it, committed too.
33
+ truth, and its diffs are the history of the plan. Readings, attachments and the graph's layout go in an
34
+ `.attraverso/` folder beside it, committed too.
35
35
 
36
36
  Then ask the agent to call `get_project`, or just to create a project and start planning. The tools describe
37
37
  themselves, and `get_project` returns the project's protocol - its operating manual - first.
38
38
 
39
+ ### Seeing it
40
+
41
+ Ask the agent to open the viewer (the `open_viewer` tool). It serves the plan as a dependency graph on a
42
+ `127.0.0.1` address, so it only opens on the machine running the server.
43
+
44
+ Or open it yourself from a terminal, in the project:
45
+
46
+ ```bash
47
+ npx attraverso viewer --open
48
+ ```
49
+
50
+ It finds the plan the way the server does (or takes `--store <path>`), prints the URL, and opens it with
51
+ `--open`. `--project <key>` picks which project it lands on. It can edit the plan as the agent's viewer can, and
52
+ is safe to run beside a connected server on the same file. Ctrl+C stops it.
53
+
39
54
  ### Where the plan lives
40
55
 
41
56
  In order of precedence:
@@ -59,16 +74,29 @@ Repeat `--store` to load a plan split across files; the first one named is where
59
74
  loaded, and always will be. To move one over, rename both: `git mv roadmap.apm.yaml attraverso.yaml` and
60
75
  `git mv .apm .attraverso`.
61
76
 
62
- ### Seeing it
63
-
64
- Ask the agent to open the viewer (the `open_viewer` tool). It serves the plan as a dependency graph on a
65
- `127.0.0.1` address, so it only opens on the machine running the server.
66
-
67
77
  ### Claude Desktop
68
78
 
69
79
  Claude Desktop starts servers without your shell's `PATH`, so a bare `npx` or `node` is often not found. See
70
80
  [docs/claude-desktop.md](docs/claude-desktop.md) for the setup and the three ways it silently breaks.
71
81
 
82
+ ### From a program
83
+
84
+ A program can open a plan in-process and call it with typed functions, without the MCP server. It runs in Node
85
+ and in a browser: the plan comes in as YAML text and goes out through a callback after every change, so where
86
+ it is kept (a file, IndexedDB, the origin-private file system) is up to you.
87
+
88
+ ```ts
89
+ import { openPlan } from "attraverso/library";
90
+
91
+ const plan = await openPlan({ yaml: savedText, save: (yaml) => store(yaml) });
92
+ const project = await plan.project("spanish");
93
+ const item = await project.createItem({ area: "VERB", title: "The subjunctive" });
94
+ await project.addComment(item.ref, "Mixed it up with the conditional again.");
95
+ ```
96
+
97
+ Keep one writer per plan: don't run the MCP server on the same file while a program has it open. In a Vite app,
98
+ add `optimizeDeps: { exclude: ["@electric-sql/pglite"] }` to the config so the dev server serves PGlite's WASM.
99
+
72
100
  ## Developing
73
101
 
74
102
  ```sh
@@ -76,6 +104,7 @@ yarn install
76
104
  yarn verify # typecheck, viewer build, unit tests
77
105
  yarn verify:all # plus the end-to-end suite (once: npx playwright install chromium)
78
106
  yarn viewer # the graph on http://localhost:5176
107
+ yarn build:standalone && yarn test:package # the packed package, used from Node, NodeNext types and a browser
79
108
  ```
80
109
 
81
110
  `yarn test:pg` runs the same suite against a server Postgres (`yarn pg:up` starts one in Docker).
@@ -84,8 +113,9 @@ To try a change against a real plan, run the server from source over any store:
84
113
  <path>`, or point a `.mcp.json` at `node_modules/.bin/vite-node src/mcp/server.ts`.
85
114
 
86
115
  Releasing is `yarn release` (`--dry-run` to rehearse), from an up-to-date checkout of this repo: it verifies,
87
- builds, checks the build starts with clean stdout, publishes to npm and tags the version. The published package
88
- is a single self-contained build that needs nothing installed but Node.
116
+ builds, checks the build starts with clean stdout and that the library works once installed, publishes to npm
117
+ and tags the version. The server in the published package is a single self-contained build that needs nothing
118
+ installed but Node; the library beside it declares its own dependencies.
89
119
 
90
120
  ## How this repo is maintained
91
121
 
@@ -0,0 +1,399 @@
1
+ import { a as R$1, c as h, l as u, n as I$1, o as T$1, t as Ce, u as x$2 } from "../server.js";
2
+ // node_modules/@electric-sql/pglite/dist/chunk-UCFNZJLR.js
3
+ u();
4
+ var K = 1024;
5
+ var A;
6
+ var F;
7
+ var g$1;
8
+ var m$1;
9
+ var y$1;
10
+ var E$1;
11
+ var v;
12
+ var n;
13
+ var J;
14
+ var H;
15
+ var j;
16
+ var z;
17
+ var B$1;
18
+ var U;
19
+ var x$1;
20
+ var D$1;
21
+ var q;
22
+ var I;
23
+ var L;
24
+ var C$1;
25
+ var w$1;
26
+ var T;
27
+ var $ = class extends Ce {
28
+ constructor(e, { debug: t = !1 } = {}) {
29
+ super();
30
+ R$1(this, n);
31
+ R$1(this, A);
32
+ R$1(this, F);
33
+ R$1(this, g$1, !0);
34
+ R$1(this, m$1, []);
35
+ R$1(this, y$1, /* @__PURE__ */ new Map());
36
+ R$1(this, E$1, Promise.resolve());
37
+ R$1(this, v, !1);
38
+ this.backend = e, this.debug = t;
39
+ }
40
+ async init(e, t) {
41
+ return this.pg = e, await this.backend.init(), { emscriptenOpts: {
42
+ ...t,
43
+ preRun: [...t.preRun || [], (s) => {
44
+ s.FS.mkdirTree(I$1), s.FS.mount(T$1(this, n, J).call(this, s), {}, I$1);
45
+ }]
46
+ } };
47
+ }
48
+ async initialSyncFs() {
49
+ let e = this.pg.Module.FS;
50
+ x$2(this, g$1, !1);
51
+ try {
52
+ for await (let t of this.backend.load()) {
53
+ let r = I$1 + t.path;
54
+ t.kind === "dir" ? e.mkdir(r, 448) : (e.writeFile(r, t.data, {
55
+ mode: 384,
56
+ canOwn: !0
57
+ }), t.mtime !== void 0 && e.utime(r, t.mtime, t.mtime));
58
+ }
59
+ } finally {
60
+ x$2(this, g$1, !0);
61
+ }
62
+ }
63
+ async syncToFs(e = !1) {
64
+ let t = h(this, E$1).then(() => T$1(this, n, q).call(this, e));
65
+ x$2(this, E$1, t.catch(() => {})), await t;
66
+ }
67
+ async closeFs() {
68
+ await this.syncToFs(), await this.backend.close(), this.pg.Module.FS.quit();
69
+ }
70
+ };
71
+ A = /* @__PURE__ */ new WeakMap(), F = /* @__PURE__ */ new WeakMap(), g$1 = /* @__PURE__ */ new WeakMap(), m$1 = /* @__PURE__ */ new WeakMap(), y$1 = /* @__PURE__ */ new WeakMap(), E$1 = /* @__PURE__ */ new WeakMap(), v = /* @__PURE__ */ new WeakMap(), n = /* @__PURE__ */ new WeakSet(), J = function(e) {
72
+ let t = e.MEMFS;
73
+ return {
74
+ mount: (r) => {
75
+ let s = t.mount(r);
76
+ return h(this, F) ?? x$2(this, F, T$1(this, n, H).call(this, e, t.ops_table)), T$1(this, n, j).call(this, e, s), x$2(this, A, s), s;
77
+ },
78
+ syncfs: (r, s, u) => {
79
+ u(null);
80
+ }
81
+ };
82
+ }, H = function(e, t) {
83
+ let r = e.FS, s = t.dir.node, u = t.file.node, l = t.file.stream, M = (i, h) => {
84
+ u.setattr(i, h), h.size !== void 0 && r.isFile(i.mode) && T$1(this, n, U).call(this, i);
85
+ };
86
+ return {
87
+ dir: {
88
+ node: {
89
+ ...s,
90
+ setattr: M,
91
+ mknod: (i, h, d, c) => {
92
+ let f = s.mknod(i, h, d, c);
93
+ return T$1(this, n, j).call(this, e, f), T$1(this, n, D$1).call(this, e, f), f;
94
+ },
95
+ rename: (i, h, d) => {
96
+ let c = T$1(this, n, w$1).call(this, e, i);
97
+ s.rename(i, h, d), T$1(this, n, x$1).call(this, c), T$1(this, n, D$1).call(this, e, i);
98
+ },
99
+ unlink: (i, h) => {
100
+ s.unlink(i, h), T$1(this, n, x$1).call(this, T$1(this, n, T).call(this, T$1(this, n, w$1).call(this, e, i), h));
101
+ },
102
+ rmdir: (i, h) => {
103
+ s.rmdir(i, h), T$1(this, n, x$1).call(this, T$1(this, n, T).call(this, T$1(this, n, w$1).call(this, e, i), h));
104
+ },
105
+ symlink: (i, h$1, d) => (h(this, g$1) && !h(this, v) && (x$2(this, v, !0), console.warn("MEMFS frontend: symlinks are not persisted")), s.symlink(i, h$1, d))
106
+ },
107
+ stream: t.dir.stream
108
+ },
109
+ file: {
110
+ node: {
111
+ ...u,
112
+ setattr: M
113
+ },
114
+ stream: {
115
+ ...l,
116
+ write: (i, h, d, c, f, k) => {
117
+ let _ = l.write(i, h, d, c, f, k);
118
+ return T$1(this, n, B$1).call(this, i.node, f, f + _), _;
119
+ },
120
+ msync: (i, h, d, c, f) => {
121
+ let k = l.msync(i, h, d, c, f);
122
+ return T$1(this, n, B$1).call(this, i.node, d, d + c), k;
123
+ },
124
+ allocate: (i, h, d) => {
125
+ l.allocate(i, h, d), T$1(this, n, U).call(this, i.node);
126
+ }
127
+ }
128
+ }
129
+ };
130
+ }, j = function(e, t) {
131
+ let r = e.FS;
132
+ r.isDir(t.mode) ? (t.node_ops = h(this, F).dir.node, t.stream_ops = h(this, F).dir.stream) : r.isFile(t.mode) && (t.node_ops = h(this, F).file.node, t.stream_ops = h(this, F).file.stream);
133
+ }, z = function(e) {
134
+ let t = h(this, y$1).get(e);
135
+ return t || (t = {
136
+ full: !1,
137
+ resized: !1,
138
+ ranges: []
139
+ }, h(this, y$1).set(e, t)), t;
140
+ }, B$1 = function(e, t, r) {
141
+ if (!h(this, g$1) || r <= t) return;
142
+ let s = T$1(this, n, z).call(this, e);
143
+ if (s.full) return;
144
+ let u = s.ranges, l = u[u.length - 1];
145
+ l && t <= l[1] && r >= l[0] ? (l[0] = Math.min(l[0], t), l[1] = Math.max(l[1], r)) : (u.push([t, r]), u.length > K && (s.ranges = R(u)));
146
+ }, U = function(e) {
147
+ h(this, g$1) && (T$1(this, n, z).call(this, e).resized = !0);
148
+ }, x$1 = function(e) {
149
+ h(this, g$1) && h(this, m$1).push({
150
+ op: "remove",
151
+ path: e
152
+ });
153
+ }, D$1 = function(e, t) {
154
+ if (!h(this, g$1)) return;
155
+ let r = e.FS;
156
+ if (r.isDir(t.mode)) {
157
+ h(this, m$1).push({
158
+ op: "mkdir",
159
+ node: t
160
+ });
161
+ for (let s of Object.values(t.contents)) T$1(this, n, D$1).call(this, e, s);
162
+ } else if (r.isFile(t.mode)) {
163
+ let s = T$1(this, n, z).call(this, t);
164
+ s.full = !0, s.ranges = [];
165
+ }
166
+ }, q = async function(e) {
167
+ if (h(this, m$1).length === 0 && h(this, y$1).size === 0) return;
168
+ let t = T$1(this, n, I).call(this);
169
+ try {
170
+ await this.backend.apply(t.changes, { relaxedDurability: e });
171
+ } catch (r) {
172
+ throw T$1(this, n, L).call(this, t), r;
173
+ }
174
+ if (this.debug) {
175
+ let { ops: r, files: s } = t.changes, u = s.wal.length + s.data.length + s.control.length;
176
+ console.log(`MEMFS frontend: flushed ${r.length} ops, ${u} files`);
177
+ }
178
+ }, I = function() {
179
+ let e = this.pg.Module, t = e.FS, r = [];
180
+ for (let l of h(this, m$1)) l.op === "remove" ? r.push(l) : t.isDir(l.node.mode) && T$1(this, n, C$1).call(this, l.node) && r.push({
181
+ op: "mkdir",
182
+ path: T$1(this, n, w$1).call(this, e, l.node)
183
+ });
184
+ let s = {
185
+ wal: [],
186
+ data: [],
187
+ control: []
188
+ };
189
+ for (let [l, M] of h(this, y$1)) {
190
+ if (!t.isFile(l.mode) || !T$1(this, n, C$1).call(this, l)) continue;
191
+ let i = l.usedBytes, h = M.full ? [[0, i]] : R(M.ranges), d = [];
192
+ for (let [k, _] of h) {
193
+ let W = Math.min(_, i);
194
+ k >= W || d.push({
195
+ at: k,
196
+ data: Q(l.contents, k, W)
197
+ });
198
+ }
199
+ let c = T$1(this, n, w$1).call(this, e, l);
200
+ (c.startsWith("/pg_wal/") ? s.wal : c === "/global/pg_control" ? s.control : s.data).push({
201
+ path: c,
202
+ size: i,
203
+ full: M.full,
204
+ truncate: M.full || M.resized,
205
+ chunks: d
206
+ });
207
+ }
208
+ let u = {
209
+ changes: {
210
+ ops: r,
211
+ files: s
212
+ },
213
+ journal: h(this, m$1),
214
+ dirty: h(this, y$1)
215
+ };
216
+ return x$2(this, m$1, []), x$2(this, y$1, /* @__PURE__ */ new Map()), u;
217
+ }, L = function(e) {
218
+ x$2(this, m$1, [...e.journal, ...h(this, m$1)]);
219
+ for (let [t, r] of e.dirty) {
220
+ let s = h(this, y$1).get(t);
221
+ s ? (s.full || (s.full = r.full), s.resized || (s.resized = r.resized), s.ranges = s.full ? [] : R([...r.ranges, ...s.ranges])) : h(this, y$1).set(t, r);
222
+ }
223
+ }, C$1 = function(e) {
224
+ for (; e.parent !== e;) {
225
+ if (e.parent.contents?.[e.name] !== e) return !1;
226
+ e = e.parent;
227
+ }
228
+ return e === h(this, A);
229
+ }, w$1 = function(e, t) {
230
+ return e.FS.getPath(t).slice(I$1.length);
231
+ }, T = function(e, t) {
232
+ return `${e}/${t}`;
233
+ };
234
+ function R(S) {
235
+ let N = [...S].sort((t, r) => t[0] - r[0]), e = [];
236
+ for (let [t, r] of N) {
237
+ let s = e[e.length - 1];
238
+ s && t <= s[1] ? s[1] = Math.max(s[1], r) : e.push([t, r]);
239
+ }
240
+ return e;
241
+ }
242
+ function Q(S, N, e) {
243
+ return S ? new Uint8Array(S.subarray ? S.subarray(N, e) : S.slice(N, e)) : new Uint8Array(e - N);
244
+ }
245
+ // node_modules/@electric-sql/pglite/dist/fs/memfs2opfs.js
246
+ u();
247
+ var B = 2;
248
+ var N = /^\/pg_wal\/[0-9A-F]{24}$/;
249
+ var m;
250
+ var y;
251
+ var d;
252
+ var P;
253
+ var w;
254
+ var x;
255
+ var p = class {
256
+ constructor(t, { maxConcurrentWrites: r = 16 } = {}) {
257
+ R$1(this, d);
258
+ R$1(this, m);
259
+ R$1(this, y, /* @__PURE__ */ new Map());
260
+ this.dataDir = t, this.maxConcurrentWrites = r;
261
+ }
262
+ async init() {
263
+ x$2(this, m, await T$1(this, d, x).call(this, this.dataDir, {
264
+ from: await navigator.storage.getDirectory(),
265
+ create: !0
266
+ }));
267
+ }
268
+ load() {
269
+ return E(h(this, m), "");
270
+ }
271
+ async apply(t, { relaxedDurability: r }) {
272
+ let e = /* @__PURE__ */ new Map(), s = (a) => {
273
+ let i = a.join("/"), c = e.get(i);
274
+ if (!c) {
275
+ let o = a.length ? s(a.slice(0, -1)).then((z) => z.getDirectoryHandle(a[a.length - 1], { create: !0 })) : Promise.resolve(h(this, m));
276
+ e.set(i, o), o.catch(() => e.delete(i)), c = o;
277
+ }
278
+ return c;
279
+ };
280
+ for (let a of t.ops) {
281
+ let i = g(a.path);
282
+ if (a.op === "mkdir") {
283
+ await s(i);
284
+ continue;
285
+ }
286
+ T$1(this, d, w).call(this, a.path);
287
+ let c = i.join("/");
288
+ for (let o of [...e.keys()]) (o === c || o.startsWith(c + "/")) && e.delete(o);
289
+ try {
290
+ await (await s(i.slice(0, -1))).removeEntry(i[i.length - 1], { recursive: !0 });
291
+ } catch (o) {
292
+ if (o?.name !== "NotFoundError") throw o;
293
+ }
294
+ }
295
+ let u = async (a) => {
296
+ let i = g(a);
297
+ return (await s(i.slice(0, -1))).getFileHandle(i[i.length - 1], { create: !0 });
298
+ }, S = async (a) => {
299
+ await b(await u(a.path), a, r);
300
+ }, v = async (a) => {
301
+ if (!N.test(a.path)) return S(a);
302
+ let i = h(this, y).get(a.path);
303
+ if (!i) {
304
+ let c = await u(a.path);
305
+ if (!("createSyncAccessHandle" in c)) return b(c, a, r);
306
+ i = await c.createSyncAccessHandle();
307
+ }
308
+ h(this, y).delete(a.path), h(this, y).set(a.path, i);
309
+ try {
310
+ C(i, a, r);
311
+ } catch (c) {
312
+ throw T$1(this, d, w).call(this, a.path), c;
313
+ }
314
+ }, { wal: M, data: O, control: _ } = t.files;
315
+ await k(M, this.maxConcurrentWrites, v), T$1(this, d, P).call(this);
316
+ for (let a of [O, _]) await k(a, this.maxConcurrentWrites, S);
317
+ }
318
+ async close() {
319
+ T$1(this, d, w).call(this);
320
+ }
321
+ };
322
+ m = /* @__PURE__ */ new WeakMap(), y = /* @__PURE__ */ new WeakMap(), d = /* @__PURE__ */ new WeakSet(), P = function() {
323
+ for (let [t, r] of h(this, y)) {
324
+ if (h(this, y).size <= B) break;
325
+ h(this, y).delete(t), W(r);
326
+ }
327
+ }, w = function(t) {
328
+ for (let [r, e] of h(this, y)) t && r !== t && !r.startsWith(t + "/") || (h(this, y).delete(r), W(e));
329
+ }, x = async function(t, r) {
330
+ let e = r.from;
331
+ for (let s of g(t)) e = await e.getDirectoryHandle(s, { create: r.create });
332
+ return e;
333
+ };
334
+ var D = class extends $ {
335
+ constructor(t, r = {}) {
336
+ super(new p(t, r), { debug: r.debug }), this.dataDir = t;
337
+ }
338
+ };
339
+ async function* E(n, t) {
340
+ for await (let [r, e] of n.entries()) {
341
+ let s = `${t}/${r}`;
342
+ if (e.kind === "directory") yield {
343
+ kind: "dir",
344
+ path: s
345
+ }, yield* E(e, s);
346
+ else {
347
+ let u = await e.getFile();
348
+ yield {
349
+ kind: "file",
350
+ path: s,
351
+ data: new Uint8Array(await u.arrayBuffer()),
352
+ mtime: u.lastModified
353
+ };
354
+ }
355
+ }
356
+ }
357
+ function g(n) {
358
+ return n.split("/").filter(Boolean);
359
+ }
360
+ async function b(n, t, r) {
361
+ if ("createSyncAccessHandle" in n) {
362
+ let e = await n.createSyncAccessHandle();
363
+ try {
364
+ C(e, t, r);
365
+ } finally {
366
+ e.close();
367
+ }
368
+ } else {
369
+ let e = await n.createWritable({ keepExistingData: !t.full });
370
+ try {
371
+ t.truncate && !t.full && await e.truncate(t.size);
372
+ for (let s of t.chunks) await e.write({
373
+ type: "write",
374
+ position: s.at,
375
+ data: s.data
376
+ });
377
+ await e.close();
378
+ } catch (s) {
379
+ throw await e.abort().catch(() => {}), s;
380
+ }
381
+ }
382
+ }
383
+ function C(n, t, r) {
384
+ t.truncate && n.truncate(t.size);
385
+ for (let e of t.chunks) n.write(e.data, { at: e.at });
386
+ r || n.flush();
387
+ }
388
+ function W(n) {
389
+ try {
390
+ n.close();
391
+ } catch {}
392
+ }
393
+ async function k(n, t, r) {
394
+ let e = 0, s = async () => {
395
+ for (; e < n.length;) await r(n[e++]);
396
+ };
397
+ await Promise.all(Array.from({ length: Math.min(t, n.length) }, s));
398
+ }
399
+ export { D as Memfs2OpfsFS, p as OpfsBackend };
@@ -0,0 +1,9 @@
1
+ CREATE TABLE "layout_positions" (
2
+ "project_id" text NOT NULL,
3
+ "node" text NOT NULL,
4
+ "x" integer NOT NULL,
5
+ "y" integer NOT NULL,
6
+ CONSTRAINT "layout_positions_project_id_node_pk" PRIMARY KEY("project_id","node")
7
+ );
8
+ --> statement-breakpoint
9
+ ALTER TABLE "layout_positions" ADD CONSTRAINT "layout_positions_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;