@open-artifact/server-sdk 0.0.0-stage → 0.1.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.
@@ -0,0 +1,573 @@
1
+ /**
2
+ * The db capability's local backend: documents are JSON files at
3
+ * `<root>/db/<collection>/<doc>.json`, a subcollection is a folder beside its
4
+ * document (`db/a/b.json` and `db/a/b/c/`). Paths follow the capability's
5
+ * grammar; queries (where / one orderBy / limit) run over one collection's
6
+ * files. Leases (`acquire`) live in memory.
7
+ *
8
+ * `readDb` / `writeDb` are the agent's view (`open-artifact.db.read` / `open-artifact.db.write`),
9
+ * in the shapes the CLI libraries answer.
10
+ */
11
+ import { createHash, randomBytes } from 'node:crypto';
12
+ import { EventEmitter } from 'node:events';
13
+ import { existsSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
14
+ import { isAbsolute, join } from 'node:path';
15
+ import { FrameError, writeAtomic } from "./files.js";
16
+ export const DB_DIR = 'db';
17
+ export const DOC_MAX_BYTES = 256 * 1024;
18
+ const DEPTH_MAX = 32;
19
+ const SEGMENT = /^[A-Za-z0-9_\-.~:@+]+$/;
20
+ const OPS = new Set(['==', '!=', '<', '<=', '>', '>=', 'in', 'not-in', 'array-contains']);
21
+ const SHA = /^[0-9a-f]{64}$/;
22
+ /** Largest page of an agent's read. */
23
+ export const READ_MAX = 1000;
24
+ export const dbError = (code, message, extra = {}) => new FrameError(code, message, code === 'invalid_argument' ? 400 : 409, extra);
25
+ /**
26
+ * A document's hash for `if_match`: the sha256 (lowercase hex) of its data as
27
+ * compact JSON, so reformatting a file by hand does not change it.
28
+ */
29
+ export function docSha256(data) {
30
+ return createHash('sha256').update(JSON.stringify(data)).digest('hex');
31
+ }
32
+ /** The fix for a `set` / `delete` over an existing document without `if_match`. */
33
+ export const IF_MATCH_FIX = 'Read the document with ArtifactData {action: "get"} and pass its sha256 as if_match, or pass "*" to replace it anyway.';
34
+ /** Splits and checks a db path. `kind`: 'doc', 'collection' or 'any' ('' is the root, allowed for 'any' only). */
35
+ export function splitPath(p, kind = 'any') {
36
+ if (typeof p !== 'string')
37
+ throw dbError('invalid_argument', 'A db path is a string.');
38
+ const trimmed = p.replace(/^\/+|\/+$/g, '');
39
+ if (trimmed === '') {
40
+ if (kind === 'any')
41
+ return [];
42
+ throw dbError('invalid_argument', 'An empty db path names no document or collection.');
43
+ }
44
+ if (Buffer.byteLength(trimmed) > 1000)
45
+ throw dbError('invalid_argument', 'A db path is at most 1000 bytes.');
46
+ const segs = trimmed.split('/');
47
+ if (segs.length > 16)
48
+ throw dbError('invalid_argument', 'A db path has at most 16 segments.');
49
+ for (const s of segs) {
50
+ if (!SEGMENT.test(s) || s === '.' || s === '..' || Buffer.byteLength(s) > 200)
51
+ throw dbError('invalid_argument', `Bad db path segment ${JSON.stringify(s)}.`);
52
+ }
53
+ if (kind === 'doc' && segs.length % 2 !== 0)
54
+ throw dbError('invalid_argument', `${trimmed} names a collection, not a document.`);
55
+ if (kind === 'collection' && segs.length % 2 !== 1)
56
+ throw dbError('invalid_argument', `${trimmed} names a document, not a collection.`);
57
+ return segs;
58
+ }
59
+ function isPlain(v) {
60
+ return typeof v === 'object' && v !== null && !Array.isArray(v);
61
+ }
62
+ /** RFC 7386-style merge for `update`: objects merge, arrays and scalars replace, `{__delete__: true}` removes a key. */
63
+ export function mergePatch(target, patch) {
64
+ const out = isPlain(target) ? { ...target } : {};
65
+ for (const [k, v] of Object.entries(patch)) {
66
+ if (isPlain(v) && v.__delete__ === true && Object.keys(v).length === 1)
67
+ delete out[k];
68
+ else if (isPlain(v))
69
+ out[k] = mergePatch(out[k], v);
70
+ else
71
+ out[k] = v;
72
+ }
73
+ return out;
74
+ }
75
+ function hasDeleteMarker(v) {
76
+ if (Array.isArray(v))
77
+ return v.some(hasDeleteMarker);
78
+ if (!isPlain(v))
79
+ return false;
80
+ if (v.__delete__ === true)
81
+ return true;
82
+ return Object.values(v).some(hasDeleteMarker);
83
+ }
84
+ function depthOf(v, d = 0) {
85
+ if (d > DEPTH_MAX)
86
+ return d;
87
+ if (Array.isArray(v))
88
+ return Math.max(d, ...v.map((x) => depthOf(x, d + 1)));
89
+ if (isPlain(v))
90
+ return Math.max(d, ...Object.values(v).map((x) => depthOf(x, d + 1)));
91
+ return d;
92
+ }
93
+ function checkData(data) {
94
+ if (!isPlain(data))
95
+ throw dbError('invalid_argument', 'Document data is a JSON object.');
96
+ const text = JSON.stringify(data);
97
+ if (Buffer.byteLength(text) > DOC_MAX_BYTES)
98
+ throw dbError('too_large', `A document is at most ${DOC_MAX_BYTES} bytes.`);
99
+ if (depthOf(data) > DEPTH_MAX)
100
+ throw dbError('invalid_argument', `A document nests at most ${DEPTH_MAX} levels.`);
101
+ return text;
102
+ }
103
+ function fieldOf(data, field) {
104
+ if (field === '__name__' || field === 'id')
105
+ return undefined;
106
+ let v = data;
107
+ for (const k of String(field).split('.')) {
108
+ if (!isPlain(v))
109
+ return undefined;
110
+ v = v[k];
111
+ }
112
+ return v;
113
+ }
114
+ const typeRank = (v) => v === null ? 0 : typeof v === 'boolean' ? 1 : typeof v === 'number' ? 2 : typeof v === 'string' ? 3 : Array.isArray(v) ? 4 : 5;
115
+ function compare(a, b) {
116
+ const ra = typeRank(a);
117
+ const rb = typeRank(b);
118
+ if (ra !== rb)
119
+ return ra - rb;
120
+ if (ra === 2)
121
+ return a - b;
122
+ if (ra === 3)
123
+ return a < b ? -1 : a > b ? 1 : 0;
124
+ if (ra === 1)
125
+ return Number(a) - Number(b);
126
+ const sa = JSON.stringify(a);
127
+ const sb = JSON.stringify(b);
128
+ return sa < sb ? -1 : sa > sb ? 1 : 0;
129
+ }
130
+ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
131
+ function matches(doc, w) {
132
+ const v = w.field === '__name__' || w.field === 'id' ? doc.id : fieldOf(doc.data, w.field);
133
+ switch (w.op) {
134
+ case '==':
135
+ return v !== undefined && same(v, w.value);
136
+ case '!=':
137
+ return v !== undefined && !same(v, w.value);
138
+ case '<':
139
+ case '<=':
140
+ case '>':
141
+ case '>=': {
142
+ if (v === undefined || typeRank(v) !== typeRank(w.value))
143
+ return false;
144
+ const c = compare(v, w.value);
145
+ return w.op === '<' ? c < 0 : w.op === '<=' ? c <= 0 : w.op === '>' ? c > 0 : c >= 0;
146
+ }
147
+ case 'in':
148
+ return v !== undefined && Array.isArray(w.value) && w.value.some((x) => same(x, v));
149
+ case 'not-in':
150
+ return v !== undefined && Array.isArray(w.value) && !w.value.some((x) => same(x, v));
151
+ case 'array-contains':
152
+ return Array.isArray(v) && v.some((x) => same(x, w.value));
153
+ default:
154
+ return false;
155
+ }
156
+ }
157
+ /** Checks a query spec from a page: `{where?: [{field, op, value}], orderBy?: {field, dir}, limit?}`. */
158
+ export function checkSpec(raw = {}) {
159
+ const spec = isPlain(raw) ? raw : {};
160
+ const where = (Array.isArray(spec.where) ? spec.where : []);
161
+ for (const w of where) {
162
+ if (typeof w?.field !== 'string' || !w.field)
163
+ throw dbError('invalid_argument', 'where() needs a field.');
164
+ if (!OPS.has(w.op))
165
+ throw dbError('invalid_argument', `where() does not know the operator ${w.op}.`);
166
+ if ((w.op === 'in' || w.op === 'not-in') && (!Array.isArray(w.value) || w.value.length > 30))
167
+ throw dbError('invalid_argument', `${w.op} takes an array of at most 30 values.`);
168
+ }
169
+ let orderBy = null;
170
+ if (spec.orderBy) {
171
+ const o = spec.orderBy;
172
+ if (typeof o.field !== 'string' || !o.field)
173
+ throw dbError('invalid_argument', 'orderBy() needs a field.');
174
+ orderBy = { field: o.field, dir: o.dir === 'desc' ? 'desc' : 'asc' };
175
+ }
176
+ let limit = null;
177
+ if (spec.limit !== undefined && spec.limit !== null) {
178
+ if (!Number.isInteger(spec.limit) || spec.limit < 1 || spec.limit > 1000)
179
+ throw dbError('invalid_argument', 'limit() takes 1 to 1000.');
180
+ limit = spec.limit;
181
+ }
182
+ return { where, orderBy, limit };
183
+ }
184
+ function pageOf(opts) {
185
+ let limit = null;
186
+ if (opts.limit !== undefined && opts.limit !== null) {
187
+ if (!Number.isInteger(opts.limit) || opts.limit < 1 || opts.limit > READ_MAX)
188
+ throw dbError('invalid_argument', `limit is 1 to ${READ_MAX}.`);
189
+ limit = opts.limit;
190
+ }
191
+ let offset = 0;
192
+ if (opts.cursor !== undefined && opts.cursor !== null && opts.cursor !== '') {
193
+ const n = typeof opts.cursor === 'string' && /^\d{1,9}$/.test(opts.cursor) ? Number(opts.cursor) : NaN;
194
+ if (!Number.isInteger(n))
195
+ throw dbError('invalid_argument', 'cursor is the next_cursor of an earlier read.');
196
+ offset = n;
197
+ }
198
+ return { limit, offset };
199
+ }
200
+ function paged(items, opts) {
201
+ const { limit, offset } = pageOf(opts);
202
+ const end = limit === null ? items.length : Math.min(items.length, offset + limit);
203
+ return { items: items.slice(offset, end), total: items.length, ...(end < items.length ? { next_cursor: String(end) } : {}) };
204
+ }
205
+ /** Sets a dot-path field of a copy of `data`. */
206
+ function withField(data, field, value) {
207
+ const keys = field.split('.');
208
+ const out = { ...data };
209
+ let at = out;
210
+ for (const k of keys.slice(0, -1)) {
211
+ const next = at[k];
212
+ if (!isPlain(next))
213
+ throw dbError('invalid_argument', `str_replace: ${field} is not a text field.`);
214
+ at[k] = { ...next };
215
+ at = at[k];
216
+ }
217
+ at[keys.at(-1)] = value;
218
+ return out;
219
+ }
220
+ function occurrences(text, part) {
221
+ let n = 0;
222
+ for (let i = text.indexOf(part); i !== -1; i = text.indexOf(part, i + part.length))
223
+ n++;
224
+ return n;
225
+ }
226
+ /** A store of one artifact's documents. Emits `change` with the doc paths a write touched. */
227
+ export class DbStore extends EventEmitter {
228
+ root;
229
+ dir;
230
+ leases = new Map();
231
+ constructor(root) {
232
+ super();
233
+ this.root = root;
234
+ this.dir = join(root, DB_DIR);
235
+ }
236
+ fileOf(segs) {
237
+ return join(this.dir, ...segs.slice(0, -1), `${segs.at(-1)}.json`);
238
+ }
239
+ readDoc(p) {
240
+ const segs = splitPath(p, 'doc');
241
+ try {
242
+ const data = JSON.parse(readFileSync(this.fileOf(segs), 'utf8'));
243
+ return isPlain(data) ? data : null;
244
+ }
245
+ catch {
246
+ return null;
247
+ }
248
+ }
249
+ /** Documents of one collection, sorted by id. */
250
+ listCollection(p) {
251
+ const segs = splitPath(p, 'collection');
252
+ const dir = join(this.dir, ...segs);
253
+ let names;
254
+ try {
255
+ names = readdirSync(dir, { withFileTypes: true });
256
+ }
257
+ catch {
258
+ return [];
259
+ }
260
+ const docs = [];
261
+ for (const e of names) {
262
+ if (!e.isFile() || e.name.startsWith('.') || !e.name.endsWith('.json'))
263
+ continue;
264
+ const id = e.name.slice(0, -5);
265
+ if (!SEGMENT.test(id))
266
+ continue;
267
+ try {
268
+ const data = JSON.parse(readFileSync(join(dir, e.name), 'utf8'));
269
+ if (isPlain(data))
270
+ docs.push({ id, data: data });
271
+ }
272
+ catch {
273
+ // half-written by hand: skipped until it parses
274
+ }
275
+ }
276
+ docs.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
277
+ return docs;
278
+ }
279
+ query(p, rawSpec) {
280
+ const spec = checkSpec(rawSpec);
281
+ let docs = this.listCollection(p).filter((d) => spec.where.every((w) => matches(d, w)));
282
+ if (spec.orderBy) {
283
+ const { field, dir } = spec.orderBy;
284
+ const key = (d) => (field === '__name__' || field === 'id' ? d.id : fieldOf(d.data, field));
285
+ docs = docs
286
+ .map((d, i) => ({ d, i, k: key(d) }))
287
+ .sort((a, b) => {
288
+ // Documents without the field sort last, either way.
289
+ if (a.k === undefined && b.k === undefined)
290
+ return a.i - b.i;
291
+ if (a.k === undefined)
292
+ return 1;
293
+ if (b.k === undefined)
294
+ return -1;
295
+ const c = compare(a.k, b.k) * (dir === 'desc' ? -1 : 1);
296
+ return c || a.i - b.i;
297
+ })
298
+ .map((x) => x.d);
299
+ }
300
+ if (spec.limit)
301
+ docs = docs.slice(0, spec.limit);
302
+ return docs;
303
+ }
304
+ set(p, data) {
305
+ const segs = splitPath(p, 'doc');
306
+ if (hasDeleteMarker(data))
307
+ throw dbError('invalid_argument', '{__delete__: true} is for update only.');
308
+ const text = checkData(data);
309
+ const file = this.fileOf(segs);
310
+ const created = !existsSync(file);
311
+ writeAtomic(file, `${text}\n`);
312
+ this.changed([segs.join('/')]);
313
+ return { bytes: Buffer.byteLength(text), created };
314
+ }
315
+ update(p, patch) {
316
+ const segs = splitPath(p, 'doc');
317
+ if (!isPlain(patch))
318
+ throw dbError('invalid_argument', 'update() takes an object.');
319
+ const have = this.readDoc(p);
320
+ if (!have)
321
+ throw dbError('invalid_argument', `update(): ${segs.join('/')} does not exist.`);
322
+ const text = checkData(mergePatch(have, patch));
323
+ writeAtomic(this.fileOf(segs), `${text}\n`);
324
+ this.changed([segs.join('/')]);
325
+ return { bytes: Buffer.byteLength(text) };
326
+ }
327
+ delete(p) {
328
+ const segs = splitPath(p, 'doc');
329
+ let existed = true;
330
+ try {
331
+ rmSync(this.fileOf(segs));
332
+ }
333
+ catch {
334
+ existed = false;
335
+ }
336
+ this.leases.delete(segs.join('/'));
337
+ if (existed)
338
+ this.changed([segs.join('/')]);
339
+ return { existed };
340
+ }
341
+ add(collection, data) {
342
+ const segs = splitPath(collection, 'collection');
343
+ const id = randomBytes(10).toString('base64url').replace(/[^A-Za-z0-9]/g, 'x');
344
+ const docPath = [...segs, id].join('/');
345
+ this.set(docPath, data);
346
+ return { id, path: docPath };
347
+ }
348
+ /** A lease on a document. */
349
+ acquire(p, opts = {}) {
350
+ const key = splitPath(p, 'doc').join('/');
351
+ const { holder, ttlMs = 30_000, data } = opts;
352
+ if (typeof holder !== 'string' || !holder || holder.length > 128)
353
+ throw dbError('invalid_argument', 'acquire() needs a holder.');
354
+ if (typeof ttlMs !== 'number' || !Number.isInteger(ttlMs) || ttlMs < 1000 || ttlMs > 600_000)
355
+ throw dbError('invalid_argument', 'acquire(): ttlMs is 1000 to 600000.');
356
+ const now = Date.now();
357
+ const have = this.leases.get(key);
358
+ if (have && have.expiresAt > now && have.holder !== holder)
359
+ return { acquired: false, holder: have.holder, expiresAt: have.expiresAt };
360
+ const lease = { holder, expiresAt: now + ttlMs, version: (have?.version ?? 0) + 1 };
361
+ this.leases.set(key, lease);
362
+ if (data !== undefined) {
363
+ if (this.readDoc(key))
364
+ this.update(key, data);
365
+ else
366
+ this.set(key, data);
367
+ }
368
+ return { acquired: true, version: lease.version, expiresAt: lease.expiresAt, holder };
369
+ }
370
+ release(p, holder) {
371
+ const key = splitPath(p, 'doc').join('/');
372
+ const have = this.leases.get(key);
373
+ const released = !!have && have.holder === holder;
374
+ if (released)
375
+ this.leases.delete(key);
376
+ return { released };
377
+ }
378
+ changed(paths) {
379
+ this.emit('change', paths);
380
+ }
381
+ // ---- the agent's view ---------------------------------------------------------------------------------------------
382
+ /** Every document file. */
383
+ listAll() {
384
+ const out = [];
385
+ const walk = (dir, segs) => {
386
+ let entries;
387
+ try {
388
+ entries = readdirSync(dir, { withFileTypes: true });
389
+ }
390
+ catch {
391
+ return;
392
+ }
393
+ for (const e of entries) {
394
+ if (e.name.startsWith('.'))
395
+ continue;
396
+ if (e.isDirectory() && SEGMENT.test(e.name))
397
+ walk(join(dir, e.name), [...segs, e.name]);
398
+ else if (e.isFile() && e.name.endsWith('.json')) {
399
+ const id = e.name.slice(0, -5);
400
+ const docSegs = [...segs, id];
401
+ if (docSegs.length % 2 !== 0 || !SEGMENT.test(id))
402
+ continue;
403
+ out.push({ path: docSegs.join('/'), bytes: statSync(join(dir, e.name)).size });
404
+ }
405
+ }
406
+ };
407
+ walk(this.dir, []);
408
+ return out.sort((a, b) => (a.path < b.path ? -1 : 1));
409
+ }
410
+ /**
411
+ * The agent's read (`open-artifact.db.read`): the root lists every document path, a
412
+ * collection its documents (filtered by `query`), a document its data.
413
+ * Documents carry `sha256` for `if_match`; a page that stops early carries
414
+ * `next_cursor`.
415
+ */
416
+ readDb(p, opts = {}) {
417
+ const segs = splitPath(p ?? '', 'any');
418
+ if (segs.length === 0) {
419
+ const page = paged(this.listAll(), opts);
420
+ return { root: DB_DIR, documents: page.items, total: page.total, ...(page.next_cursor ? { next_cursor: page.next_cursor } : {}) };
421
+ }
422
+ const joined = segs.join('/');
423
+ if (segs.length % 2 === 1) {
424
+ const query = opts.query !== undefined && opts.query !== null;
425
+ const docs = query ? this.query(joined, opts.query) : this.listCollection(joined);
426
+ const page = paged(docs, opts);
427
+ return {
428
+ collection: joined,
429
+ ...(query ? { query: true } : {}),
430
+ docs: page.items.map((d) => ({ id: d.id, path: `${joined}/${d.id}`, sha256: docSha256(d.data), data: d.data })),
431
+ total: page.total,
432
+ ...(page.next_cursor ? { next_cursor: page.next_cursor } : {}),
433
+ };
434
+ }
435
+ if (opts.query !== undefined && opts.query !== null)
436
+ throw dbError('invalid_argument', `${joined} names a document; a query reads a collection.`);
437
+ const data = this.readDoc(joined);
438
+ return data ? { path: joined, exists: true, sha256: docSha256(data), data } : { path: joined, exists: false, sha256: null };
439
+ }
440
+ /**
441
+ * The agent's batch (`open-artifact.db.write`): every write is checked before any is
442
+ * made. A write with `if_match` that no longer holds fails the whole batch
443
+ * with `conflict`, its `current` holding what each such document is now.
444
+ */
445
+ writeDb(writes, opts = {}) {
446
+ if (!Array.isArray(writes) || writes.length === 0)
447
+ throw dbError('invalid_argument', 'writes is a non-empty array.');
448
+ if (writes.length > 500)
449
+ throw dbError('invalid_argument', 'At most 500 writes at once.');
450
+ const seen = new Set();
451
+ const conflicts = {};
452
+ const unguarded = [];
453
+ const plan = writes.map((w) => {
454
+ const op = w?.op;
455
+ if (op !== 'set' && op !== 'update' && op !== 'delete' && op !== 'str_replace')
456
+ throw dbError('invalid_argument', `Unknown op ${String(op)}.`);
457
+ // A write names its document by `path`, or by `collection` + `doc_id` (the ArtifactData batch shape).
458
+ const named = w.path ?? (w.collection != null && w.doc_id != null ? `${w.collection}/${w.doc_id}` : '');
459
+ const p = splitPath(String(named), 'doc').join('/');
460
+ if (seen.has(p))
461
+ throw dbError('invalid_argument', `${p} appears twice in one batch.`);
462
+ seen.add(p);
463
+ const ifMatch = w.if_match;
464
+ if (ifMatch !== undefined && ifMatch !== null && ifMatch !== '*' && !(typeof ifMatch === 'string' && SHA.test(ifMatch))) {
465
+ throw dbError('invalid_argument', `${op} ${p}: if_match is a sha256 you read, null or "*".`);
466
+ }
467
+ const have = this.readDoc(p);
468
+ const haveSha = have ? docSha256(have) : null;
469
+ if (ifMatch !== undefined && ifMatch !== '*' && ifMatch !== haveSha) {
470
+ conflicts[p] = have ? { path: p, exists: true, sha256: haveSha, data: have } : { path: p, exists: false, sha256: null };
471
+ }
472
+ if (opts.requireIfMatch && (op === 'set' || op === 'delete') && have && ifMatch === undefined)
473
+ unguarded.push(`${op} ${p}`);
474
+ if (op === 'delete')
475
+ return { op, path: p, data: undefined };
476
+ if (op === 'str_replace') {
477
+ if (typeof w.field !== 'string' || !w.field)
478
+ throw dbError('invalid_argument', `str_replace ${p}: field (a dot path) is required.`);
479
+ if (typeof w.old !== 'string' || !w.old)
480
+ throw dbError('invalid_argument', `str_replace ${p}: old is a non-empty string.`);
481
+ if (typeof w.new !== 'string')
482
+ throw dbError('invalid_argument', `str_replace ${p}: new is a string.`);
483
+ if (!have)
484
+ throw dbError('invalid_argument', `str_replace: ${p} does not exist.`);
485
+ const text = fieldOf(have, w.field);
486
+ if (typeof text !== 'string')
487
+ throw dbError('invalid_argument', `str_replace ${p}: ${w.field} is not a text field.`);
488
+ const n = occurrences(text, w.old);
489
+ if (n === 0)
490
+ throw dbError('invalid_argument', `str_replace ${p}: old does not occur in ${w.field}.`, { fix: 'Read the document again and copy old exactly from it.' });
491
+ if (n > 1)
492
+ throw dbError('invalid_argument', `str_replace ${p}: old occurs ${n} times in ${w.field}.`, { fix: 'Make old longer so it occurs exactly once.' });
493
+ const data = withField(have, w.field, text.replace(w.old, () => w.new));
494
+ checkData(data);
495
+ return { op, path: p, data: data };
496
+ }
497
+ const hasData = w.data !== undefined;
498
+ const hasFile = typeof w.file_path === 'string' && w.file_path !== '';
499
+ if (hasData === hasFile)
500
+ throw dbError('invalid_argument', `${op} ${p}: give exactly one of data or file_path.`);
501
+ let data = w.data;
502
+ if (hasFile) {
503
+ if (!isAbsolute(w.file_path))
504
+ throw dbError('invalid_argument', 'file_path is an absolute path.');
505
+ try {
506
+ data = JSON.parse(readFileSync(w.file_path, 'utf8'));
507
+ }
508
+ catch (error) {
509
+ throw dbError('invalid_argument', `${w.file_path}: ${error?.message ?? error}`);
510
+ }
511
+ }
512
+ if (!isPlain(data))
513
+ throw dbError('invalid_argument', `${op} ${p}: the data is a JSON object.`);
514
+ if (op === 'set' && hasDeleteMarker(data))
515
+ throw dbError('invalid_argument', `set ${p}: {__delete__: true} is for update only.`);
516
+ checkData(op === 'update' ? mergePatch(have ?? {}, data) : data);
517
+ return { op, path: p, data };
518
+ });
519
+ const conflicted = Object.keys(conflicts);
520
+ if (conflicted.length) {
521
+ throw dbError('conflict', `${conflicted.length === 1 ? `${conflicted[0]} changed` : `${conflicted.length} documents changed`} since you read it: nothing was written.`, {
522
+ fix: 'Merge your change into the document in current, then write again with its sha256 as if_match.',
523
+ current: conflicts,
524
+ });
525
+ }
526
+ if (unguarded.length) {
527
+ throw dbError('invalid_argument', `${unguarded.join(', ')}: the document exists, so the write needs if_match. Nothing was written.`, {
528
+ fix: IF_MATCH_FIX,
529
+ need_if_match: unguarded.map((u) => u.slice(u.indexOf(' ') + 1)),
530
+ });
531
+ }
532
+ const out = [];
533
+ const shaOf = (path) => {
534
+ const data = this.readDoc(path);
535
+ return data ? docSha256(data) : null;
536
+ };
537
+ for (const w of plan) {
538
+ if (w.op === 'delete') {
539
+ const { existed } = this.delete(w.path);
540
+ out.push({ op: 'delete', path: w.path, sha256: null, ...(existed ? {} : { note: 'did not exist' }) });
541
+ }
542
+ else if (w.op === 'update' && this.readDoc(w.path)) {
543
+ const r = this.update(w.path, w.data);
544
+ out.push({ op: 'update', path: w.path, bytes: r.bytes, sha256: shaOf(w.path) });
545
+ }
546
+ else if (w.op === 'update') {
547
+ const r = this.set(w.path, mergePatch({}, w.data));
548
+ out.push({ op: 'update', path: w.path, bytes: r.bytes, sha256: shaOf(w.path), created: true, note: 'did not exist; created' });
549
+ }
550
+ else {
551
+ const r = this.set(w.path, w.data);
552
+ out.push({ op: w.op, path: w.path, bytes: r.bytes, sha256: shaOf(w.path), ...(r.created ? { created: true } : {}) });
553
+ }
554
+ }
555
+ return out;
556
+ }
557
+ }
558
+ /** Doc paths of the db files a watcher saw change (paths relative to the artifact folder). */
559
+ export function docPathsOf(relPaths) {
560
+ const out = [];
561
+ for (const rel of relPaths) {
562
+ const segs = rel.split(/[\\/]/);
563
+ if (segs[0] !== DB_DIR || segs.length < 2)
564
+ continue;
565
+ const last = segs.at(-1);
566
+ if (last.startsWith('.') || !last.endsWith('.json'))
567
+ continue;
568
+ const doc = [...segs.slice(1, -1), last.slice(0, -5)];
569
+ if (doc.length % 2 === 0)
570
+ out.push(doc.join('/'));
571
+ }
572
+ return out;
573
+ }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * The inline declaration of an original artifact type: a type's index.html
3
+ * carries, near the top of its first script, a block that starts with the
4
+ * line comment `// artifact.json` and declares
5
+ * `var key = "<type key>"; var capabilities = {...}; var monitoring = {...};`
6
+ * in some order (a type may leave capabilities out). Only that block is read:
7
+ * it ends at the next line comment. The literals are evaluated in an empty V8
8
+ * context with a short timeout, never in this process's realm.
9
+ */
10
+ /** A capability's declared config: `true`, or an object of options. */
11
+ export type CapabilityDecl = boolean | Record<string, unknown>;
12
+ export interface Declaration {
13
+ /** The type key, when the block names one. */
14
+ key: string | null;
15
+ /** cap → declared config. */
16
+ capabilities: Record<string, CapabilityDecl>;
17
+ monitoring: Record<string, unknown>;
18
+ }
19
+ /** Whether `html` carries an inline declaration at all (a line of its own). */
20
+ export declare const DECLARATION_LINE: RegExp;
21
+ /** The declaration in a type's index.html, or null when the page carries none. Throws when the block does not evaluate. */
22
+ export declare function parseDeclaration(html: string): Declaration | null;
23
+ /** The declaration of the type folder `dir` (its index.html), or null. */
24
+ export declare function readDeclaration(dir: string): Declaration | null;
@@ -0,0 +1,65 @@
1
+ /**
2
+ * The inline declaration of an original artifact type: a type's index.html
3
+ * carries, near the top of its first script, a block that starts with the
4
+ * line comment `// artifact.json` and declares
5
+ * `var key = "<type key>"; var capabilities = {...}; var monitoring = {...};`
6
+ * in some order (a type may leave capabilities out). Only that block is read:
7
+ * it ends at the next line comment. The literals are evaluated in an empty V8
8
+ * context with a short timeout, never in this process's realm.
9
+ */
10
+ import { readFileSync } from 'node:fs';
11
+ import { join } from 'node:path';
12
+ import vm from 'node:vm';
13
+ const MARKER = '// artifact.json';
14
+ const NAMES = ['key', 'capabilities', 'monitoring'];
15
+ /** Whether `html` carries an inline declaration at all (a line of its own). */
16
+ export const DECLARATION_LINE = /(^|\n)[ \t]*\/\/ artifact\.json[ \t]*\r?\n/;
17
+ /** The declaration in a type's index.html, or null when the page carries none. Throws when the block does not evaluate. */
18
+ export function parseDeclaration(html) {
19
+ const at = html.indexOf(MARKER);
20
+ if (at < 0)
21
+ return null;
22
+ const from = at + MARKER.length;
23
+ const next = /\n[ \t]*\/\/ /g;
24
+ next.lastIndex = from;
25
+ const stop = next.exec(html);
26
+ const block = html.slice(from, stop ? stop.index : Math.min(html.length, from + 64 * 1024));
27
+ const sandbox = Object.create(null);
28
+ try {
29
+ vm.runInNewContext(block, sandbox, { timeout: 250, displayErrors: false, contextCodeGeneration: { strings: false, wasm: false } });
30
+ }
31
+ catch (error) {
32
+ throw new Error(`The artifact.json block of index.html does not evaluate: ${error?.message ?? error}`);
33
+ }
34
+ const out = {};
35
+ for (const name of NAMES) {
36
+ let value = sandbox[name];
37
+ // Plain data only, in this realm.
38
+ try {
39
+ value = value === undefined ? undefined : JSON.parse(JSON.stringify(value));
40
+ }
41
+ catch {
42
+ value = undefined;
43
+ }
44
+ out[name] = value;
45
+ }
46
+ return {
47
+ key: typeof out.key === 'string' ? out.key : null,
48
+ capabilities: isObject(out.capabilities) ? out.capabilities : {},
49
+ monitoring: isObject(out.monitoring) ? out.monitoring : {},
50
+ };
51
+ }
52
+ /** The declaration of the type folder `dir` (its index.html), or null. */
53
+ export function readDeclaration(dir) {
54
+ let html;
55
+ try {
56
+ html = readFileSync(join(dir, 'index.html'), 'utf8');
57
+ }
58
+ catch {
59
+ return null;
60
+ }
61
+ return parseDeclaration(html);
62
+ }
63
+ function isObject(v) {
64
+ return typeof v === 'object' && v !== null && !Array.isArray(v);
65
+ }