@dreamforgestudiollc/emet 0.2.6 → 0.3.1

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.
Files changed (57) hide show
  1. package/.env.example +10 -0
  2. package/CHANGELOG.md +26 -1
  3. package/README.md +34 -8
  4. package/areas/emet.md +18 -0
  5. package/areas/garden.md +18 -0
  6. package/areas/health.md +18 -0
  7. package/areas/home.md +18 -0
  8. package/areas/learning.md +18 -0
  9. package/areas/state.md +18 -0
  10. package/docs/DEPLOY.md +32 -1
  11. package/docs/DEVELOPMENT-PRACTICES.md +26 -0
  12. package/docs/ERROR-CODES-SPEC.md +43 -0
  13. package/docs/ERROR-CODES.md +332 -0
  14. package/docs/GUIDED-SETUP.md +16 -0
  15. package/docs/PERMISSIONS.md +8 -5
  16. package/docs/ROADMAP.md +10 -10
  17. package/docs/SETUP.md +115 -12
  18. package/package.json +4 -2
  19. package/server.json +7 -3
  20. package/src/aleph.js +16 -10
  21. package/src/annotations.js +8 -3
  22. package/src/atlas-role.js +8 -3
  23. package/src/attribution.js +12 -12
  24. package/src/conformance.js +6 -4
  25. package/src/database.js +28 -12
  26. package/src/dispatch.js +33 -16
  27. package/src/error-codes.js +394 -0
  28. package/src/error-log.js +273 -0
  29. package/src/error-report.js +245 -0
  30. package/src/floor.js +6 -4
  31. package/src/gaps.js +2 -2
  32. package/src/gem-check.js +27 -26
  33. package/src/http-remote.js +2 -1
  34. package/src/index.js +1 -0
  35. package/src/invites.js +6 -5
  36. package/src/layers.js +8 -7
  37. package/src/mongo-connect.js +5 -0
  38. package/src/oauth-provider.js +28 -27
  39. package/src/pages.js +806 -0
  40. package/src/persons.js +2 -1
  41. package/src/provenance.js +10 -10
  42. package/src/rune-dispatch.js +10 -10
  43. package/src/session-graph.js +16 -15
  44. package/src/session.js +1 -1
  45. package/src/setup.js +21 -17
  46. package/src/startup-pages.js +3 -2
  47. package/src/startup-payload.js +3 -2
  48. package/src/subkey-store.js +3 -2
  49. package/src/tools.js +254 -177
  50. package/src/validation.js +61 -52
  51. package/src/version.js +1 -1
  52. package/templates/AREA.md +35 -0
  53. package/templates/INDEX.md +7 -6
  54. package/templates/PROCEDURE.md +1 -1
  55. package/templates/SEED.md +2 -2
  56. package/templates/STAGING.md +1 -1
  57. package/templates/THREAD.md +1 -1
@@ -0,0 +1,273 @@
1
+ /**
2
+ * Operational error log. Not a controlled document and not a memory.
3
+ * Entries are capped and rotated. Nothing here stores message text,
4
+ * arguments, document ids, names, or secrets.
5
+ */
6
+
7
+ import { readySharedClient } from './mongo-connect.js';
8
+ import { MONGODB_URI, MONGODB_DB, ErrorCodes } from './database.js';
9
+ import { redactText } from './redact.js';
10
+ import { currentActor, getPerson } from './persons.js';
11
+ import { registeredSourceTags } from './setup.js';
12
+ import { EMET_VERSION } from './version.js';
13
+ import { CodedError, EMET_CODE_RE, EMET_INT_001, lookupEmetCode, newCorrelationId } from './error-codes.js';
14
+
15
+ export const ERROR_LOG_COLLECTION = 'error_log';
16
+ export const ERROR_LOG_SUMMARY_COLLECTION = 'error_log_summary';
17
+ export const ERROR_LOG_MAX = 10000;
18
+ export const ERROR_LOG_DAYS = 90;
19
+
20
+ const ENTRY_KEYS = Object.freeze([
21
+ '_id', 't', 'emet_code', 'class_code', 'tool', 'version', 'transport', 'caller', 'role', 'correlation_id', 'count'
22
+ ]);
23
+ const SUMMARY_KEYS = Object.freeze(['day', 'emet_code', 'tool', 'version', 'count']);
24
+ const CLASS_CODES = new Set(Object.values(ErrorCodes));
25
+
26
+ let backend = null;
27
+ let indexed = false;
28
+ let chain = Promise.resolve();
29
+
30
+ /** Test seam. Pass null to use Mongo again. */
31
+ export function setErrorLogBackend(store) {
32
+ backend = store;
33
+ }
34
+
35
+ export function useMemoryErrorLog() {
36
+ const store = { entries: [], summaries: [], fail: false };
37
+ backend = store;
38
+ return store;
39
+ }
40
+
41
+ export function flushErrorLog() {
42
+ return chain;
43
+ }
44
+
45
+ function scrub(value) {
46
+ return redactText(String(value ?? ''));
47
+ }
48
+
49
+ function safeCode(code) {
50
+ return typeof code === 'string' && EMET_CODE_RE.test(code) && lookupEmetCode(code) ? code : EMET_INT_001;
51
+ }
52
+
53
+ function safeClass(code) {
54
+ return CLASS_CODES.has(code) ? code : ErrorCodes.INTERNAL_ERROR;
55
+ }
56
+
57
+ function safeTool(name) {
58
+ return typeof name === 'string' && /^[a-z0-9_]{1,80}$/.test(name) ? name : 'unknown';
59
+ }
60
+
61
+ function safeCorrelation(id) {
62
+ return typeof id === 'string' && /^[0-9a-f]{16}$/.test(id) ? id : newCorrelationId();
63
+ }
64
+
65
+ function callerTag() {
66
+ let raw = null;
67
+ try {
68
+ const actor = currentActor();
69
+ if (actor && typeof actor.sourceTag === 'string' && actor.sourceTag) raw = actor.sourceTag;
70
+ } catch { raw = null; }
71
+ const tags = registeredSourceTags();
72
+ if (typeof raw !== 'string' || !tags.includes(raw)) return 'unregistered';
73
+ const clean = scrub(raw);
74
+ if (clean !== raw) return 'unregistered';
75
+ return raw;
76
+ }
77
+
78
+ async function roleOf(db) {
79
+ try {
80
+ const actor = currentActor();
81
+ if (actor.transport === 'stdio') return 'owner';
82
+ if (actor.transport !== 'http' || !actor.personId || !db) return 'guest';
83
+ const person = await getPerson(db, actor.personId);
84
+ return person && person.role === 'owner' ? 'owner' : 'guest';
85
+ } catch {
86
+ return 'guest';
87
+ }
88
+ }
89
+
90
+ function buildEntry(fields) {
91
+ const doc = {
92
+ _id: fields._id || newCorrelationId(),
93
+ t: typeof fields.t === 'string' && fields.t ? fields.t : new Date().toISOString(),
94
+ emet_code: safeCode(fields.emet_code),
95
+ class_code: safeClass(fields.class_code),
96
+ tool: safeTool(fields.tool),
97
+ version: EMET_VERSION,
98
+ transport: fields.transport === 'http' ? 'http' : 'stdio',
99
+ caller: fields.caller === 'unregistered' || typeof fields.caller !== 'string' ? 'unregistered' : (scrub(fields.caller) === fields.caller ? fields.caller : 'unregistered'),
100
+ role: fields.role === 'owner' ? 'owner' : 'guest',
101
+ correlation_id: safeCorrelation(fields.correlation_id),
102
+ count: 1
103
+ };
104
+ const out = {};
105
+ for (const key of ENTRY_KEYS) out[key] = doc[key];
106
+ return out;
107
+ }
108
+
109
+ function dbHandle() {
110
+ if (!MONGODB_URI) return null;
111
+ const client = readySharedClient();
112
+ if (!client) return null;
113
+ return client.db(MONGODB_DB);
114
+ }
115
+
116
+ async function logCollection() {
117
+ const db = await dbHandle();
118
+ if (!db) return null;
119
+ const col = db.collection(ERROR_LOG_COLLECTION);
120
+ if (!indexed) {
121
+ indexed = true;
122
+ await col.createIndex({ t: -1 });
123
+ await col.createIndex({ emet_code: 1, t: -1 });
124
+ await col.createIndex({ correlation_id: 1 }, { unique: true });
125
+ await db.collection(ERROR_LOG_SUMMARY_COLLECTION).createIndex(
126
+ { day: 1, emet_code: 1, tool: 1, version: 1 },
127
+ { unique: true }
128
+ );
129
+ }
130
+ return col;
131
+ }
132
+
133
+ export async function insertErrorLog(fields) {
134
+ const doc = buildEntry(fields);
135
+ if (backend) {
136
+ if (backend.fail) throw new CodedError('error log down', { code: 'EMET-INT-001' });
137
+ backend.entries.push(doc);
138
+ return doc;
139
+ }
140
+ const col = await logCollection();
141
+ if (!col) return doc;
142
+ await col.insertOne(doc);
143
+ return doc;
144
+ }
145
+
146
+ export async function upsertErrorSummary(row) {
147
+ const summary = {
148
+ day: String(row.day || '').slice(0, 10),
149
+ emet_code: safeCode(row.emet_code),
150
+ tool: safeTool(row.tool),
151
+ version: typeof row.version === 'string' ? row.version : EMET_VERSION,
152
+ count: Number(row.count) || 0
153
+ };
154
+ const stored = {};
155
+ for (const key of SUMMARY_KEYS) stored[key] = summary[key];
156
+ if (backend) {
157
+ if (backend.fail) throw new CodedError('error log down', { code: 'EMET-INT-001' });
158
+ const found = backend.summaries.find((s) => s.day === stored.day && s.emet_code === stored.emet_code && s.tool === stored.tool && s.version === stored.version);
159
+ if (found) found.count += stored.count;
160
+ else backend.summaries.push({ ...stored });
161
+ return stored;
162
+ }
163
+ const db = await dbHandle();
164
+ if (!db) return stored;
165
+ await db.collection(ERROR_LOG_SUMMARY_COLLECTION).updateOne(
166
+ { day: stored.day, emet_code: stored.emet_code, tool: stored.tool, version: stored.version },
167
+ { $inc: { count: stored.count } },
168
+ { upsert: true }
169
+ );
170
+ return stored;
171
+ }
172
+
173
+ async function loadRows() {
174
+ if (backend) return backend.entries.map((row) => ({ ...row }));
175
+ const col = await logCollection();
176
+ if (!col) return [];
177
+ return col.find({}, { projection: { t: 1, emet_code: 1, tool: 1, version: 1, count: 1 } }).toArray();
178
+ }
179
+
180
+ export async function rotateErrorLog(options = {}) {
181
+ const max = options.maxEntries ?? ERROR_LOG_MAX;
182
+ const days = options.maxAgeDays ?? ERROR_LOG_DAYS;
183
+ const now = options.now instanceof Date ? options.now : new Date();
184
+ const ageCutoff = new Date(now.getTime() - days * 86400000).toISOString();
185
+ const rows = await loadRows();
186
+ const sorted = [...rows].sort((a, b) => (a.t < b.t ? 1 : a.t > b.t ? -1 : String(a._id) < String(b._id) ? 1 : -1));
187
+ const keep = new Set(sorted.slice(0, max).map((row) => row._id));
188
+ const removed = sorted.filter((row) => row.t < ageCutoff || !keep.has(row._id));
189
+ if (!removed.length) return { removed: 0 };
190
+ let day = ageCutoff.slice(0, 10);
191
+ if (removed.some((row) => row.t >= ageCutoff)) {
192
+ const kept = sorted.filter((row) => !removed.includes(row));
193
+ const oldest = kept[kept.length - 1];
194
+ if (oldest) day = String(oldest.t).slice(0, 10);
195
+ }
196
+ const groups = new Map();
197
+ for (const row of removed) {
198
+ const key = `${String(row.t).slice(0, 10)}\0${row.emet_code}\0${row.tool}\0${row.version}`;
199
+ const group = groups.get(key) || {
200
+ day: String(row.t).slice(0, 10),
201
+ emet_code: row.emet_code,
202
+ tool: row.tool,
203
+ version: row.version,
204
+ count: 0
205
+ };
206
+ group.count += Number(row.count) || 1;
207
+ groups.set(key, group);
208
+ }
209
+ for (const group of groups.values()) await upsertErrorSummary(group);
210
+ const ids = removed.map((row) => row._id);
211
+ if (backend) {
212
+ const drop = new Set(ids);
213
+ backend.entries = backend.entries.filter((row) => !drop.has(row._id));
214
+ } else {
215
+ const col = await logCollection();
216
+ if (col) await col.deleteMany({ _id: { $in: ids } });
217
+ }
218
+ console.error(`rotated ${removed.length} entries older than ${day}`);
219
+ return { removed: removed.length, day };
220
+ }
221
+
222
+ export async function queryErrorLog({ since, correlation_id, codes } = {}) {
223
+ let rows;
224
+ if (backend) rows = backend.entries.map((row) => ({ ...row }));
225
+ else {
226
+ const col = await logCollection();
227
+ rows = col ? await col.find({}).toArray() : [];
228
+ }
229
+ if (correlation_id) rows = rows.filter((row) => row.correlation_id === correlation_id);
230
+ else {
231
+ if (since) rows = rows.filter((row) => row.t >= since);
232
+ if (Array.isArray(codes) && codes.length) {
233
+ const wanted = new Set(codes);
234
+ rows = rows.filter((row) => wanted.has(row.emet_code));
235
+ }
236
+ }
237
+ rows.sort((a, b) => (a.t < b.t ? 1 : a.t > b.t ? -1 : 0));
238
+ return rows;
239
+ }
240
+
241
+ export async function recordError(input = {}) {
242
+ const job = (async () => {
243
+ try {
244
+ const db = backend ? null : await dbHandle();
245
+ const actor = currentActor();
246
+ await insertErrorLog({
247
+ t: new Date().toISOString(),
248
+ emet_code: input.emet_code,
249
+ class_code: input.class_code,
250
+ tool: input.tool,
251
+ correlation_id: input.correlation_id,
252
+ transport: actor.transport === 'http' ? 'http' : 'stdio',
253
+ caller: callerTag(),
254
+ role: await roleOf(db)
255
+ });
256
+ } catch {
257
+ console.error('error log write failed');
258
+ }
259
+ })();
260
+ chain = chain.then(() => job, () => job);
261
+ return job;
262
+ }
263
+
264
+ export function startErrorLogRotation() {
265
+ const run = () => {
266
+ rotateErrorLog().catch(() => { console.error('error log write failed'); });
267
+ };
268
+ const kick = setTimeout(run, 1000);
269
+ if (kick.unref) kick.unref();
270
+ const timer = setInterval(run, 24 * 60 * 60 * 1000);
271
+ if (timer.unref) timer.unref();
272
+ return timer;
273
+ }
@@ -0,0 +1,245 @@
1
+ /**
2
+ * Owner-only error report. This module does not send mail and does not
3
+ * open a network connection. A calling assistant may pass the structured
4
+ * email to its own mail tool only after the user has seen the report and agreed.
5
+ */
6
+
7
+ import crypto from 'node:crypto';
8
+ import { ValidationError } from './validation.js';
9
+ import { currentActor, getPerson } from './persons.js';
10
+ import { EMET_VERSION } from './version.js';
11
+ import { ERROR_CODES, EMET_CODE_RE } from './error-codes.js';
12
+ import { redactText } from './redact.js';
13
+ import { queryErrorLog } from './error-log.js';
14
+
15
+ export const SEND_INSTRUCTION = 'The calling assistant may send this report only after showing the report to its user and getting their OK.';
16
+ export const DEFAULT_REPORT_EMAIL = 'dreamforgestudio@mail.grokbot.com';
17
+ export const MAILTO_MAX = 1800;
18
+
19
+ /**
20
+ * One plain address: exactly one @. The local part is letters, digits, and
21
+ * . _ + - , and it does not start or end with a dot or contain "..".
22
+ * The domain is two or more labels separated by dots. A label is letters,
23
+ * digits, and -, and it does not start or end with -.
24
+ */
25
+ export function plainReportAddress(value) {
26
+ if (typeof value !== 'string' || value.length === 0) return false;
27
+ const at = value.indexOf('@');
28
+ if (at < 1 || at !== value.lastIndexOf('@') || at === value.length - 1) return false;
29
+ const local = value.slice(0, at);
30
+ const domain = value.slice(at + 1);
31
+ if (!/^[A-Za-z0-9._+-]+$/.test(local)) return false;
32
+ if (local.startsWith('.') || local.endsWith('.') || local.includes('..')) return false;
33
+ const labels = domain.split('.');
34
+ if (labels.length < 2) return false;
35
+ const labelOk = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
36
+ if (labels.some((label) => !labelOk.test(label))) return false;
37
+ return true;
38
+ }
39
+
40
+ export function reportEmailAddress() {
41
+ if (!plainReportAddress(DEFAULT_REPORT_EMAIL)) return '';
42
+ if (process.env.EMET_REPORT_EMAIL == null) return DEFAULT_REPORT_EMAIL;
43
+ const raw = process.env.EMET_REPORT_EMAIL;
44
+ if (raw === '' || !plainReportAddress(raw)) return '';
45
+ return raw;
46
+ }
47
+
48
+ export async function assertReportOwner(db) {
49
+ const actor = currentActor();
50
+ if (actor.transport === 'stdio') return;
51
+ const person = actor.transport === 'http' && actor.personId && db ? await getPerson(db, actor.personId) : null;
52
+ if (!person || person.role !== 'owner') {
53
+ throw new ValidationError('The error report is owner-only.', { code: 'EMET-AUTH-038' });
54
+ }
55
+ }
56
+
57
+ export function validateReportArgs(args = {}, now = new Date()) {
58
+ const out = { since: null, codes: null, correlation_id: null, limit: 50, now };
59
+ if (args.correlation_id != null && args.correlation_id !== '') {
60
+ if (typeof args.correlation_id !== 'string' || !/^[0-9a-f]{16}$/.test(args.correlation_id)) {
61
+ throw new ValidationError('correlation_id must be 16 hex characters.', { code: 'EMET-TOOL-013' });
62
+ }
63
+ out.correlation_id = args.correlation_id;
64
+ }
65
+ if (args.limit != null) {
66
+ if (typeof args.limit !== 'number' || !Number.isInteger(args.limit) || args.limit < 1 || args.limit > 200) {
67
+ throw new ValidationError('limit must be a whole number from 1 to 200.', { code: 'EMET-TOOL-012' });
68
+ }
69
+ out.limit = args.limit;
70
+ }
71
+ if (args.codes != null) {
72
+ if (!Array.isArray(args.codes) || args.codes.some((code) => typeof code !== 'string' || !EMET_CODE_RE.test(code))) {
73
+ throw new ValidationError('codes must be a list of EMET codes.', { code: 'EMET-TOOL-011' });
74
+ }
75
+ out.codes = args.codes;
76
+ }
77
+ if (!out.correlation_id) {
78
+ let since;
79
+ if (args.since == null || args.since === '') {
80
+ since = new Date(now.getTime() - 7 * 86400000);
81
+ } else if (typeof args.since !== 'string' || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)?$/.test(args.since)) {
82
+ throw new ValidationError('since must be an ISO date.', { code: 'EMET-TOOL-009' });
83
+ } else {
84
+ since = new Date(args.since.length === 10 ? `${args.since}T00:00:00.000Z` : args.since);
85
+ if (Number.isNaN(since.getTime())) throw new ValidationError('since must be an ISO date.', { code: 'EMET-TOOL-009' });
86
+ }
87
+ const oldest = now.getTime() - 90 * 86400000;
88
+ if (since.getTime() < oldest - 1000) {
89
+ throw new ValidationError('since is older than 90 days.', { code: 'EMET-TOOL-010' });
90
+ }
91
+ out.since = since.toISOString();
92
+ }
93
+ return out;
94
+ }
95
+
96
+ function shown(entry) {
97
+ return {
98
+ t: redactText(String(entry.t || '')),
99
+ emet_code: redactText(String(entry.emet_code || '')),
100
+ tool: redactText(String(entry.tool || '')),
101
+ transport: entry.transport === 'http' ? 'http' : 'stdio',
102
+ caller: redactText(String(entry.caller || 'unregistered')),
103
+ role: entry.role === 'owner' ? 'owner' : 'guest',
104
+ correlation_id: redactText(String(entry.correlation_id || ''))
105
+ };
106
+ }
107
+
108
+ function totalsOf(rows) {
109
+ const map = new Map();
110
+ for (const row of rows) {
111
+ const code = row.emet_code;
112
+ const cur = map.get(code) || { emet_code: code, count: 0, tools: new Map() };
113
+ cur.count += 1;
114
+ cur.tools.set(row.tool, (cur.tools.get(row.tool) || 0) + 1);
115
+ map.set(code, cur);
116
+ }
117
+ return [...map.values()]
118
+ .sort((a, b) => b.count - a.count || (a.emet_code < b.emet_code ? -1 : 1))
119
+ .map((row) => {
120
+ let tool = 'unknown';
121
+ let best = -1;
122
+ for (const [name, count] of row.tools) {
123
+ if (count > best) { tool = name; best = count; }
124
+ }
125
+ const known = ERROR_CODES[row.emet_code];
126
+ return { emet_code: row.emet_code, summary: known ? known.summary : row.emet_code, count: row.count, tool };
127
+ });
128
+ }
129
+
130
+ function assemble({ version, shortId, generated, windowStart, windowEnd, nodeVersion, totals, recent, notes }) {
131
+ const lines = [];
132
+ lines.push(`EMET error report ${version} ${shortId}`);
133
+ lines.push(`Generated: ${generated} EMET ${version} Node ${nodeVersion}`);
134
+ lines.push(`Window: ${windowStart} to ${windowEnd} (UTC)`);
135
+ lines.push('');
136
+ lines.push('Totals');
137
+ if (!totals.length) lines.push(' (none)');
138
+ for (const row of totals) lines.push(` ${row.emet_code} ${row.summary} ${row.count} ${row.tool}`);
139
+ for (const note of notes) lines.push(note);
140
+ lines.push('');
141
+ lines.push('Most recent');
142
+ if (!recent.length) lines.push(' (none)');
143
+ for (const entry of recent) {
144
+ lines.push(` ${entry.t} ${entry.emet_code} ${entry.tool} ${entry.transport} ${entry.caller} ${entry.role} ${entry.correlation_id}`);
145
+ }
146
+ lines.push('');
147
+ lines.push('Contains: codes, times, tool names, versions, caller tags, ids.');
148
+ lines.push('Does not contain: memory, documents, arguments, names, tokens.');
149
+ lines.push('You are sending this yourself. EMET has not sent it anywhere.');
150
+ return lines.join('\n');
151
+ }
152
+
153
+ function mailtoLink(to, subject, body) {
154
+ const text = String(body).replace(/\r?\n/g, '\r\n');
155
+ return `mailto:${to}?subject=${encodeURIComponent(subject)}&body=${encodeURIComponent(text)}`;
156
+ }
157
+
158
+ export function fitReportEmail({ to, subject, base }) {
159
+ const full = assemble({ ...base, notes: [] });
160
+ const fullLink = mailtoLink(to, subject, full);
161
+ if (fullLink.length <= MAILTO_MAX) {
162
+ return { body: full, mailto: fullLink, truncated: false, entries_in_link: base.recent.length, report: full };
163
+ }
164
+ const listed = base.recent.length;
165
+ for (let count = listed - 1; count >= 1; count--) {
166
+ const notes = [`Truncated: showing the ${count} most recent of ${listed} entries. The full report is in the tool output above.`];
167
+ const body = assemble({ ...base, recent: base.recent.slice(0, count), notes });
168
+ const link = mailtoLink(to, subject, body);
169
+ if (link.length <= MAILTO_MAX) return { body, mailto: link, truncated: true, entries_in_link: count, report: full };
170
+ }
171
+ for (let keep = base.totals.length; keep >= 0; keep--) {
172
+ const omitted = base.totals.length - keep;
173
+ const notes = [];
174
+ if (listed) notes.push(`Truncated: showing none of the ${listed} most recent entries. The full report is in the tool output above.`);
175
+ if (omitted) notes.push(`Truncated: totals omit ${omitted} codes. The full report is in the tool output above.`);
176
+ const body = assemble({ ...base, totals: base.totals.slice(0, keep), recent: [], notes });
177
+ const link = mailtoLink(to, subject, body);
178
+ if (link.length <= MAILTO_MAX) return { body, mailto: link, truncated: true, entries_in_link: 0, report: full };
179
+ }
180
+ const body = assemble({ ...base, totals: [], recent: [], notes: ['Truncated: the full report is in the tool output above.'] });
181
+ const link = mailtoLink(to, subject, body);
182
+ if (link.length <= MAILTO_MAX) {
183
+ return { body, mailto: link, truncated: true, entries_in_link: 0, report: full };
184
+ }
185
+ return {
186
+ body,
187
+ mailto: null,
188
+ reason: 'The mailto link would exceed 1800 characters.',
189
+ truncated: true,
190
+ entries_in_link: 0,
191
+ report: full
192
+ };
193
+ }
194
+
195
+ function windowLabel(rows, since, now) {
196
+ if (rows.length) {
197
+ const oldest = rows[rows.length - 1].t.slice(0, 10);
198
+ const newest = rows[0].t.slice(0, 10);
199
+ return [oldest, newest];
200
+ }
201
+ const end = now.toISOString().slice(0, 10);
202
+ const start = since ? since.slice(0, 10) : end;
203
+ return [start, end];
204
+ }
205
+
206
+ export function composeErrorReport(rows, { since, now, shortId, limit = rows.length, nodeVersion = process.versions.node } = {}) {
207
+ const version = EMET_VERSION;
208
+ const generated = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
209
+ const [windowStart, windowEnd] = windowLabel(rows, since, now);
210
+ const shownRows = rows.map(shown);
211
+ const recent = shownRows.slice(0, limit);
212
+ const totals = totalsOf(shownRows);
213
+ const base = { version, shortId, generated, windowStart, windowEnd, nodeVersion, totals, recent };
214
+ const report = assemble({ ...base, notes: [] });
215
+ const to = reportEmailAddress();
216
+ const subject = `EMET error report ${version} ${shortId}`;
217
+ if (to === '') {
218
+ return { report, email: null, instruction: SEND_INSTRUCTION };
219
+ }
220
+ const fitted = fitReportEmail({ to, subject, base });
221
+ const email = {
222
+ to,
223
+ subject,
224
+ body_text: fitted.report,
225
+ short_id: shortId,
226
+ version,
227
+ body: fitted.body,
228
+ mailto: fitted.mailto,
229
+ truncated: fitted.truncated,
230
+ entries_in_link: fitted.entries_in_link,
231
+ entries_total: shownRows.length
232
+ };
233
+ if (fitted.mailto == null) email.reason = fitted.reason;
234
+ return { report: fitted.report, email, instruction: SEND_INSTRUCTION };
235
+ }
236
+
237
+ export async function runErrorReport(args = {}, dbManager = null) {
238
+ const db = dbManager && dbManager.db ? dbManager.db : (dbManager && dbManager.collection ? dbManager : null);
239
+ await assertReportOwner(db);
240
+ const now = args.now instanceof Date ? args.now : new Date();
241
+ const query = validateReportArgs(args, now);
242
+ const rows = await queryErrorLog(query);
243
+ const shortId = crypto.randomBytes(3).toString('hex');
244
+ return composeErrorReport(rows, { since: query.since, now, shortId, limit: query.limit });
245
+ }
package/src/floor.js CHANGED
@@ -152,6 +152,7 @@ export async function readFloor(options = {}) {
152
152
  return {
153
153
  form: 'section',
154
154
  error: `Unknown section '${section}'.`,
155
+ emet_code: 'EMET-GEM-009',
155
156
  sections: FLOOR_SECTIONS
156
157
  };
157
158
  }
@@ -174,7 +175,7 @@ export async function readFloor(options = {}) {
174
175
  /** A loadable installed GEM's floor. Off is still readable. A refusal is not served. */
175
176
  async function readGemFloor(gem, { compact, section }) {
176
177
  if (!GEM_ID.test(gem)) {
177
- return { form: 'gem', gem, error: `Unknown GEM '${gem}'.` };
178
+ return { form: 'gem', gem, error: `Unknown GEM '${gem}'.`, emet_code: 'EMET-GEM-010' };
178
179
  }
179
180
  const { seatGems } = await import('./socket.js');
180
181
  const seated = await seatGems({
@@ -187,14 +188,15 @@ async function readGemFloor(gem, { compact, section }) {
187
188
  form: 'gem',
188
189
  gem,
189
190
  error: `Unknown GEM '${gem}'.`,
191
+ emet_code: 'EMET-GEM-010',
190
192
  installed: (seated.gems_available || []).map((g) => g.id)
191
193
  };
192
194
  }
193
195
  if (row.loadable !== true) {
194
- return { form: 'gem', gem, loadable: false, reason: row.reason, error: `GEM '${gem}' is not loadable.` };
196
+ return { form: 'gem', gem, loadable: false, reason: row.reason, error: `GEM '${gem}' is not loadable.`, emet_code: 'EMET-GEM-011' };
195
197
  }
196
198
  const body = seated.floors && Object.prototype.hasOwnProperty.call(seated.floors, gem) ? seated.floors[gem] : null;
197
- if (!body) return { form: 'gem', gem, error: `GEM '${gem}' has no floor.` };
199
+ if (!body) return { form: 'gem', gem, error: `GEM '${gem}' has no floor.`, emet_code: 'EMET-GEM-012' };
198
200
  const active = row.active === true;
199
201
  if (compact) {
200
202
  return {
@@ -211,7 +213,7 @@ async function readGemFloor(gem, { compact, section }) {
211
213
  if (section) {
212
214
  const sections = body.sections || {};
213
215
  if (!Object.prototype.hasOwnProperty.call(sections, section)) {
214
- return { form: 'section', gem, error: `Unknown section '${section}'.`, sections: Object.keys(sections) };
216
+ return { form: 'section', gem, error: `Unknown section '${section}'.`, emet_code: 'EMET-GEM-009', sections: Object.keys(sections) };
215
217
  }
216
218
  return { form: 'section', gem, active, section, precedence: PRECEDENCE, floor: sections[section] };
217
219
  }
package/src/gaps.js CHANGED
@@ -213,7 +213,7 @@ export function tagFamilies(rows, { minShared = 3, minFamily = 3, maxFamily = 8
213
213
  }
214
214
 
215
215
  async function connect() {
216
- if (!MONGODB_URI) throw new DatabaseError('MONGODB_URI is not set; cannot assess gaps.', 'emet_gaps');
216
+ if (!MONGODB_URI) throw new DatabaseError('MONGODB_URI is not set; cannot assess gaps.', 'emet_gaps', { code: 'EMET-DB-001' });
217
217
  const client = await connectMongo(MONGODB_URI, { serverSelectionTimeoutMS: 15000 });
218
218
  return { client, db: client.db(MONGODB_DB) };
219
219
  }
@@ -253,7 +253,7 @@ export async function checkCorrectionLinks(corrected, corrections, findRow) {
253
253
 
254
254
  export async function findGaps({ layer = null, since = null, limit = 50 } = {}) {
255
255
  const layers = layer ? [layer] : [...LAYERS];
256
- if (layer && !LAYERS.includes(layer)) throw new DatabaseError(`Unknown layer '${layer}'`, 'emet_gaps');
256
+ if (layer && !LAYERS.includes(layer)) throw new DatabaseError(`Unknown layer '${layer}'`, 'emet_gaps', { code: 'EMET-DB-010' });
257
257
  const cap = Math.max(1, Math.min(500, Number(limit) || 50));
258
258
  const nowSec = Date.now() / 1000;
259
259
  const registry = registeredTags();