advisers 0.2.0-preview.71 → 0.2.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/LICENSE +130 -201
- package/NOTICE +29 -4
- package/README-zh.md +32 -6
- package/README.md +36 -7
- package/THIRD-PARTY-NOTICES.md +277 -0
- package/bin/advisers.js +1634 -290
- package/index.js +1 -1
- package/lib/attachments.js +153 -27
- package/lib/capture.js +82 -2
- package/lib/evidence.js +1180 -26
- package/lib/ical.js +542 -0
- package/lib/imap.js +82 -24
- package/lib/mcp-server.js +869 -0
- package/lib/model.js +151 -2
- package/lib/notify.js +129 -3
- package/lib/pdf.js +44 -6
- package/lib/pet-brief.js +78 -15
- package/lib/receipt-verify.js +624 -0
- package/lib/remind.js +261 -11
- package/lib/research.js +142 -18
- package/lib/safety/classifier.js +392 -0
- package/lib/safety/explain.js +157 -0
- package/lib/safety/index.js +333 -0
- package/lib/safety/redact.js +212 -0
- package/lib/safety/rules.js +824 -0
- package/lib/scheduler.js +399 -0
- package/lib/source.js +294 -0
- package/lib/sqlite.js +361 -37
- package/lib/sync.js +58 -13
- package/lib/tos/index.js +332 -0
- package/lib/tos/manifest.json +32 -0
- package/lib/tos/privacy.zh-CN.md +136 -0
- package/lib/tos/safety.zh-CN.md +101 -0
- package/lib/tos/summary.zh-CN.md +12 -0
- package/lib/tos/terms.zh-CN.md +439 -0
- package/package.json +7 -6
package/lib/scheduler.js
ADDED
|
@@ -0,0 +1,399 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* E1-T4: user-level scheduler planning (opt-in).
|
|
3
|
+
*
|
|
4
|
+
* This module never executes a system command. It produces a *plan* — the new
|
|
5
|
+
* crontab text, or the argv for `schtasks` — and the CLI layer decides whether
|
|
6
|
+
* to apply it. A dry-run is therefore the default everywhere in this module.
|
|
7
|
+
*
|
|
8
|
+
* The only side effect is the local state file
|
|
9
|
+
* `~/.advisers/scheduler/status.json` (written atomically, 0600) which records
|
|
10
|
+
* `lastRun` so `remind status` can show whether the schedule actually fires.
|
|
11
|
+
* Tests and callers always pass an explicit `homeDir`; this module never writes
|
|
12
|
+
* outside it.
|
|
13
|
+
*/
|
|
14
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
|
|
15
|
+
import { homedir } from 'node:os'
|
|
16
|
+
import { join } from 'node:path'
|
|
17
|
+
|
|
18
|
+
export const SCHEDULER_DIR = 'scheduler'
|
|
19
|
+
export const SCHEDULER_STATUS_FILE = 'status.json'
|
|
20
|
+
export const SCHEDULER_STATUS_VERSION = 1
|
|
21
|
+
export const CRON_MARKER = 'advisers-remind'
|
|
22
|
+
export const DEFAULT_CRON_SCHEDULE = '0 9 * * *'
|
|
23
|
+
export const DEFAULT_TASK_NAME = 'Advisers Remind'
|
|
24
|
+
export const DEFAULT_TASK_TIME = '09:00'
|
|
25
|
+
export const DEFAULT_REMIND_ARGS = Object.freeze(['remind', '--deliver', '--notify'])
|
|
26
|
+
/** Platforms where `crontab(1)` is the user-level scheduler. */
|
|
27
|
+
export const CRON_PLATFORMS = Object.freeze(['linux', 'darwin', 'freebsd', 'openbsd', 'sunos'])
|
|
28
|
+
|
|
29
|
+
const MARKER_PATTERN = /^[A-Za-z0-9._-]{1,64}$/
|
|
30
|
+
const CRON_FIELD = /^[0-9A-Za-z*,/-]+$/
|
|
31
|
+
const TASK_TIME = /^([01][0-9]|2[0-3]):[0-5][0-9]$/
|
|
32
|
+
|
|
33
|
+
/** Quote one argv element for a POSIX shell (cron runs commands via /bin/sh). */
|
|
34
|
+
export function quoteShellArgument(value) {
|
|
35
|
+
const text = String(value ?? '')
|
|
36
|
+
if (text === '') return "''"
|
|
37
|
+
if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(text)) return text
|
|
38
|
+
return "'" + text.replace(/'/g, "'\\''") + "'"
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Build the cron command for `advisers remind --deliver --notify`. Crontab
|
|
43
|
+
* treats `%` as a line separator even inside arguments, so it is escaped.
|
|
44
|
+
*/
|
|
45
|
+
export function buildCronCommand({ nodeBin = 'node', cliPath = 'advisers', args = DEFAULT_REMIND_ARGS } = {}) {
|
|
46
|
+
if (!Array.isArray(args)) throw new TypeError('cron args must be an array')
|
|
47
|
+
const argv = [nodeBin, cliPath, ...args].map((entry) => {
|
|
48
|
+
if (typeof entry !== 'string') throw new TypeError('cron command arguments must be strings')
|
|
49
|
+
if (/[\r\n\0]/.test(entry)) throw new TypeError('cron command arguments must be single-line')
|
|
50
|
+
return entry
|
|
51
|
+
})
|
|
52
|
+
return argv.map(quoteShellArgument).join(' ').replace(/%/g, '\\%')
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function validateMarker(marker) {
|
|
56
|
+
const text = String(marker ?? '').trim()
|
|
57
|
+
if (!MARKER_PATTERN.test(text)) throw new TypeError(`invalid scheduler marker: ${String(marker)}`)
|
|
58
|
+
return text
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Validate a five-field cron expression and return it normalised. */
|
|
62
|
+
export function validateCronSchedule(schedule) {
|
|
63
|
+
if (typeof schedule !== 'string') throw new TypeError('cron schedule must be a string')
|
|
64
|
+
const text = schedule.trim()
|
|
65
|
+
if (/[\r\n\0]/.test(text)) throw new TypeError('cron schedule must be single-line')
|
|
66
|
+
const fields = text.split(/\s+/)
|
|
67
|
+
if (fields.length !== 5 || fields.some((field) => !CRON_FIELD.test(field))) {
|
|
68
|
+
throw new TypeError(`invalid cron schedule: ${String(schedule)}`)
|
|
69
|
+
}
|
|
70
|
+
return fields.join(' ')
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function validateCronCommand(command) {
|
|
74
|
+
const text = String(command ?? '').trim()
|
|
75
|
+
if (!text) throw new TypeError('cron command must not be empty')
|
|
76
|
+
if (/[\r\n\0]/.test(text)) throw new TypeError('cron command must be single-line')
|
|
77
|
+
return text
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function markerTokens(marker) {
|
|
81
|
+
return { start: `# >>> ${marker} >>>`, end: `# <<< ${marker} <<<` }
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function splitLines(text) {
|
|
85
|
+
return String(text ?? '').replace(/\r\n/g, '\n').split('\n')
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function findCronBlock(lines, marker) {
|
|
89
|
+
const { start: startToken, end: endToken } = markerTokens(marker)
|
|
90
|
+
const start = lines.findIndex((line) => line.trim() === startToken)
|
|
91
|
+
if (start === -1) return null
|
|
92
|
+
const end = lines.findIndex((line, index) => index > start && line.trim() === endToken)
|
|
93
|
+
return { start, end: end === -1 ? lines.length - 1 : end, malformed: end === -1 }
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** The managed crontab block, including the two marker comments. */
|
|
97
|
+
export function buildCronBlock({ command, schedule = DEFAULT_CRON_SCHEDULE, marker = CRON_MARKER } = {}) {
|
|
98
|
+
const safeMarker = validateMarker(marker)
|
|
99
|
+
const safeSchedule = validateCronSchedule(schedule)
|
|
100
|
+
const safeCommand = validateCronCommand(command)
|
|
101
|
+
const { start, end } = markerTokens(safeMarker)
|
|
102
|
+
return [start, `${safeSchedule} ${safeCommand}`, end].join('\n')
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Inspect a crontab text for the managed block.
|
|
107
|
+
*
|
|
108
|
+
* @returns {{ installed: boolean, marker: string, schedule: string|null,
|
|
109
|
+
* command: string|null, malformed: boolean }}
|
|
110
|
+
*/
|
|
111
|
+
export function getCronEntry(text, { marker = CRON_MARKER } = {}) {
|
|
112
|
+
const safeMarker = validateMarker(marker)
|
|
113
|
+
const lines = splitLines(text)
|
|
114
|
+
const block = findCronBlock(lines, safeMarker)
|
|
115
|
+
if (!block) {
|
|
116
|
+
return { installed: false, marker: safeMarker, schedule: null, command: null, malformed: false }
|
|
117
|
+
}
|
|
118
|
+
const job = lines.slice(block.start + 1, block.end).find((line) => line.trim() && !line.trim().startsWith('#'))
|
|
119
|
+
const match = job ? /^\s*\S+\s+\S+\s+\S+\s+\S+\s+\S+\s+(.*)$/.exec(job) : null
|
|
120
|
+
return {
|
|
121
|
+
installed: true,
|
|
122
|
+
marker: safeMarker,
|
|
123
|
+
schedule: match ? job.trim().split(/\s+/).slice(0, 5).join(' ') : null,
|
|
124
|
+
command: match ? match[1].trim() : null,
|
|
125
|
+
malformed: block.malformed,
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Append or replace the managed crontab block. Pure: the caller writes the
|
|
131
|
+
* returned text (e.g. pipes it to `crontab -`).
|
|
132
|
+
*
|
|
133
|
+
* @returns {{ text: string, changed: boolean, added: boolean,
|
|
134
|
+
* alreadyInstalled: boolean, updated: boolean }}
|
|
135
|
+
*/
|
|
136
|
+
export function addCronEntry(text, { command, schedule = DEFAULT_CRON_SCHEDULE, marker = CRON_MARKER } = {}) {
|
|
137
|
+
const original = String(text ?? '')
|
|
138
|
+
const safeMarker = validateMarker(marker)
|
|
139
|
+
const safeSchedule = validateCronSchedule(schedule)
|
|
140
|
+
const safeCommand = validateCronCommand(command)
|
|
141
|
+
const block = buildCronBlock({ command: safeCommand, schedule: safeSchedule, marker: safeMarker })
|
|
142
|
+
const lines = splitLines(original)
|
|
143
|
+
const found = findCronBlock(lines, safeMarker)
|
|
144
|
+
if (found) {
|
|
145
|
+
const current = getCronEntry(original, { marker: safeMarker })
|
|
146
|
+
if (!found.malformed && current.schedule === safeSchedule && current.command === safeCommand) {
|
|
147
|
+
return { text: original, changed: false, added: false, alreadyInstalled: true, updated: false }
|
|
148
|
+
}
|
|
149
|
+
lines.splice(found.start, found.end - found.start + 1, ...block.split('\n'))
|
|
150
|
+
return { text: lines.join('\n'), changed: true, added: false, alreadyInstalled: false, updated: true }
|
|
151
|
+
}
|
|
152
|
+
const base = original === '' || original.endsWith('\n') ? original : `${original}\n`
|
|
153
|
+
return { text: `${base}${block}\n`, changed: true, added: true, alreadyInstalled: false, updated: false }
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* Remove the managed crontab block and leave every other line untouched.
|
|
158
|
+
*
|
|
159
|
+
* @returns {{ text: string, changed: boolean, removed: boolean }}
|
|
160
|
+
*/
|
|
161
|
+
export function removeCronEntry(text, { marker = CRON_MARKER } = {}) {
|
|
162
|
+
const original = String(text ?? '')
|
|
163
|
+
const safeMarker = validateMarker(marker)
|
|
164
|
+
const lines = splitLines(original)
|
|
165
|
+
const found = findCronBlock(lines, safeMarker)
|
|
166
|
+
if (!found) return { text: original, changed: false, removed: false }
|
|
167
|
+
lines.splice(found.start, found.end - found.start + 1)
|
|
168
|
+
// Drop the artifact newline left behind when the block was the whole file.
|
|
169
|
+
const remaining = lines.join('\n')
|
|
170
|
+
return { text: remaining, changed: true, removed: true }
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
export function crontabReadCommand() {
|
|
174
|
+
return { command: 'crontab', args: ['-l'] }
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
export function crontabWriteCommand(text) {
|
|
178
|
+
return { command: 'crontab', args: ['-'], stdin: String(text ?? '') }
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** Validate a Windows Task Scheduler task name. */
|
|
182
|
+
export function validateTaskName(name) {
|
|
183
|
+
const text = String(name ?? '').trim()
|
|
184
|
+
if (!text) throw new TypeError('task name must not be empty')
|
|
185
|
+
if (/[\r\n\0]/.test(text)) throw new TypeError('task name must be single-line')
|
|
186
|
+
if (text.length > 200) throw new RangeError('task name is too long')
|
|
187
|
+
return text
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Validate a daily run time as `HH:MM` (24h). */
|
|
191
|
+
export function validateTaskTime(time) {
|
|
192
|
+
const text = String(time ?? '').trim()
|
|
193
|
+
if (!TASK_TIME.test(text)) throw new TypeError(`invalid task time: ${String(time)} (expected HH:MM)`)
|
|
194
|
+
return text
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Generate the schtasks argv for create/delete/query. Nothing is executed.
|
|
199
|
+
*
|
|
200
|
+
* @returns {{ command: 'schtasks', args: string[] }}
|
|
201
|
+
*/
|
|
202
|
+
export function buildSchtasksCommand({ action = 'create', taskName = DEFAULT_TASK_NAME, command, time = DEFAULT_TASK_TIME } = {}) {
|
|
203
|
+
const safeTask = validateTaskName(taskName)
|
|
204
|
+
if (action === 'create') {
|
|
205
|
+
const safeCommand = validateCronCommand(command)
|
|
206
|
+
const safeTime = validateTaskTime(time)
|
|
207
|
+
return { command: 'schtasks', args: ['/Create', '/TN', safeTask, '/TR', safeCommand, '/SC', 'DAILY', '/ST', safeTime, '/F'] }
|
|
208
|
+
}
|
|
209
|
+
if (action === 'delete') return { command: 'schtasks', args: ['/Delete', '/TN', safeTask, '/F'] }
|
|
210
|
+
if (action === 'query') return { command: 'schtasks', args: ['/Query', '/TN', safeTask] }
|
|
211
|
+
throw new TypeError(`unknown schtasks action: ${String(action)}`)
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/** Dry-run plan for a cron-style install. */
|
|
215
|
+
export function planCronInstall({ existingText = '', command, schedule = DEFAULT_CRON_SCHEDULE, marker = CRON_MARKER, dryRun = true } = {}) {
|
|
216
|
+
const change = addCronEntry(existingText, { command, schedule, marker })
|
|
217
|
+
return {
|
|
218
|
+
platform: 'cron',
|
|
219
|
+
action: 'install',
|
|
220
|
+
dryRun: dryRun !== false,
|
|
221
|
+
changed: change.changed,
|
|
222
|
+
alreadyInstalled: change.alreadyInstalled,
|
|
223
|
+
installed: true,
|
|
224
|
+
marker: validateMarker(marker),
|
|
225
|
+
schedule: validateCronSchedule(schedule),
|
|
226
|
+
command: validateCronCommand(command),
|
|
227
|
+
text: change.text,
|
|
228
|
+
commands: change.changed ? [crontabWriteCommand(change.text)] : [],
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** Dry-run plan for a cron-style uninstall. */
|
|
233
|
+
export function planCronUninstall({ existingText = '', marker = CRON_MARKER, dryRun = true } = {}) {
|
|
234
|
+
const change = removeCronEntry(existingText, { marker })
|
|
235
|
+
return {
|
|
236
|
+
platform: 'cron',
|
|
237
|
+
action: 'uninstall',
|
|
238
|
+
dryRun: dryRun !== false,
|
|
239
|
+
changed: change.changed,
|
|
240
|
+
installed: false,
|
|
241
|
+
marker: validateMarker(marker),
|
|
242
|
+
text: change.text,
|
|
243
|
+
commands: change.changed ? [crontabWriteCommand(change.text)] : [],
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** Read-only cron status query; the CLI must execute the returned read command. */
|
|
248
|
+
export function planCronStatus({ existingText = '', marker = CRON_MARKER } = {}) {
|
|
249
|
+
return {
|
|
250
|
+
platform: 'cron',
|
|
251
|
+
action: 'status',
|
|
252
|
+
dryRun: true,
|
|
253
|
+
...getCronEntry(existingText, { marker }),
|
|
254
|
+
commands: [crontabReadCommand()],
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/** Dry-run plan for a Windows Task Scheduler install (argv only, not executed). */
|
|
259
|
+
export function planWindowsInstall({ command, taskName = DEFAULT_TASK_NAME, time = DEFAULT_TASK_TIME, dryRun = true } = {}) {
|
|
260
|
+
return {
|
|
261
|
+
platform: 'win32',
|
|
262
|
+
action: 'install',
|
|
263
|
+
dryRun: dryRun !== false,
|
|
264
|
+
changed: true,
|
|
265
|
+
installed: null,
|
|
266
|
+
taskName: validateTaskName(taskName),
|
|
267
|
+
time: validateTaskTime(time),
|
|
268
|
+
commands: [buildSchtasksCommand({ action: 'create', taskName, command, time })],
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
export function planWindowsUninstall({ taskName = DEFAULT_TASK_NAME, dryRun = true } = {}) {
|
|
273
|
+
return {
|
|
274
|
+
platform: 'win32',
|
|
275
|
+
action: 'uninstall',
|
|
276
|
+
dryRun: dryRun !== false,
|
|
277
|
+
changed: true,
|
|
278
|
+
installed: false,
|
|
279
|
+
taskName: validateTaskName(taskName),
|
|
280
|
+
commands: [buildSchtasksCommand({ action: 'delete', taskName })],
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
/** Windows cannot be queried without running schtasks, so the plan carries the query argv. */
|
|
285
|
+
export function planWindowsStatus({ taskName = DEFAULT_TASK_NAME } = {}) {
|
|
286
|
+
return {
|
|
287
|
+
platform: 'win32',
|
|
288
|
+
action: 'status',
|
|
289
|
+
dryRun: true,
|
|
290
|
+
installed: null,
|
|
291
|
+
taskName: validateTaskName(taskName),
|
|
292
|
+
commands: [buildSchtasksCommand({ action: 'query', taskName })],
|
|
293
|
+
note: 'The CLI must run the query command; exit code 0 means scheduled.',
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/** Platform dispatcher used by the CLI: returns a plan, never executes it. */
|
|
298
|
+
export function planScheduler(options = {}) {
|
|
299
|
+
const opts = options ?? {}
|
|
300
|
+
const platform = opts.platform ?? process.platform
|
|
301
|
+
const action = opts.action ?? 'install'
|
|
302
|
+
if (platform === 'win32') {
|
|
303
|
+
if (action === 'install') return planWindowsInstall(opts)
|
|
304
|
+
if (action === 'uninstall') return planWindowsUninstall(opts)
|
|
305
|
+
if (action === 'status') return planWindowsStatus(opts)
|
|
306
|
+
} else if (CRON_PLATFORMS.includes(platform)) {
|
|
307
|
+
if (action === 'install') return planCronInstall(opts)
|
|
308
|
+
if (action === 'uninstall') return planCronUninstall(opts)
|
|
309
|
+
if (action === 'status') return planCronStatus(opts)
|
|
310
|
+
}
|
|
311
|
+
throw new TypeError(`unsupported scheduler platform/action: ${String(platform)}/${String(action)}`)
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
/** Resolve `~/.advisers/scheduler/` without assuming a real HOME. */
|
|
315
|
+
export function schedulerPaths({ homeDir } = {}) {
|
|
316
|
+
const home = String(homeDir ?? process.env.ADVISERS_HOME ?? join(homedir(), '.advisers'))
|
|
317
|
+
const dir = join(home, SCHEDULER_DIR)
|
|
318
|
+
return { home, dir, statusFile: join(dir, SCHEDULER_STATUS_FILE) }
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
export function defaultSchedulerStatus() {
|
|
322
|
+
return {
|
|
323
|
+
version: SCHEDULER_STATUS_VERSION,
|
|
324
|
+
lastRun: null,
|
|
325
|
+
lastResult: null,
|
|
326
|
+
lastCount: null,
|
|
327
|
+
lastChannel: null,
|
|
328
|
+
updatedAt: null,
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* Read `lastRun` state. Missing or corrupt files degrade to defaults instead of
|
|
334
|
+
* throwing, so a damaged status file can never block reminder delivery.
|
|
335
|
+
*
|
|
336
|
+
* @returns {{ version: number, lastRun: string|null, lastResult: string|null,
|
|
337
|
+
* lastCount: number|null, lastChannel: string|null, updatedAt: string|null,
|
|
338
|
+
* exists: boolean, corrupt: boolean }}
|
|
339
|
+
*/
|
|
340
|
+
export function readSchedulerStatus(options = {}) {
|
|
341
|
+
const { statusFile } = schedulerPaths(options ?? {})
|
|
342
|
+
let raw
|
|
343
|
+
try {
|
|
344
|
+
raw = readFileSync(statusFile, 'utf8')
|
|
345
|
+
} catch (error) {
|
|
346
|
+
return { ...defaultSchedulerStatus(), exists: false, corrupt: false, error: error?.code === 'ENOENT' ? null : 'read-error' }
|
|
347
|
+
}
|
|
348
|
+
let parsed
|
|
349
|
+
try {
|
|
350
|
+
parsed = JSON.parse(raw)
|
|
351
|
+
} catch {
|
|
352
|
+
return { ...defaultSchedulerStatus(), exists: true, corrupt: true }
|
|
353
|
+
}
|
|
354
|
+
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
|
|
355
|
+
return { ...defaultSchedulerStatus(), exists: true, corrupt: true }
|
|
356
|
+
}
|
|
357
|
+
const status = defaultSchedulerStatus()
|
|
358
|
+
if (typeof parsed.lastRun === 'string' && !Number.isNaN(Date.parse(parsed.lastRun))) status.lastRun = new Date(parsed.lastRun).toISOString()
|
|
359
|
+
if (typeof parsed.lastResult === 'string' && parsed.lastResult) status.lastResult = parsed.lastResult
|
|
360
|
+
if (Number.isFinite(parsed.lastCount)) status.lastCount = Number(parsed.lastCount)
|
|
361
|
+
if (typeof parsed.lastChannel === 'string' && parsed.lastChannel) status.lastChannel = parsed.lastChannel
|
|
362
|
+
if (typeof parsed.updatedAt === 'string' && !Number.isNaN(Date.parse(parsed.updatedAt))) status.updatedAt = new Date(parsed.updatedAt).toISOString()
|
|
363
|
+
return { ...status, exists: true, corrupt: false }
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
/**
|
|
367
|
+
* Record one scheduler run in `status.json`. Defaults to dry-run: pass
|
|
368
|
+
* `dryRun: false` (the CLI does this after a real delivery) to write the file.
|
|
369
|
+
*
|
|
370
|
+
* @returns {{ status: object, path: string, written: boolean }}
|
|
371
|
+
*/
|
|
372
|
+
export function recordSchedulerRun({ homeDir, at = new Date(), result = 'ok', count = null, channel = null, dryRun = true } = {}) {
|
|
373
|
+
const paths = schedulerPaths({ homeDir })
|
|
374
|
+
const when = at instanceof Date ? at : new Date(at)
|
|
375
|
+
if (Number.isNaN(when.getTime())) throw new RangeError('invalid scheduler run time')
|
|
376
|
+
const status = {
|
|
377
|
+
version: SCHEDULER_STATUS_VERSION,
|
|
378
|
+
lastRun: when.toISOString(),
|
|
379
|
+
lastResult: typeof result === 'string' && result ? result : 'ok',
|
|
380
|
+
lastCount: Number.isFinite(count) ? Number(count) : null,
|
|
381
|
+
lastChannel: typeof channel === 'string' && channel ? channel : null,
|
|
382
|
+
updatedAt: when.toISOString(),
|
|
383
|
+
}
|
|
384
|
+
if (dryRun !== false) return { status, path: paths.statusFile, written: false }
|
|
385
|
+
mkdirSync(paths.dir, { recursive: true, mode: 0o700 })
|
|
386
|
+
const temp = `${paths.statusFile}.${process.pid}.tmp`
|
|
387
|
+
try {
|
|
388
|
+
writeFileSync(temp, JSON.stringify(status, null, 2) + '\n', { mode: 0o600 })
|
|
389
|
+
renameSync(temp, paths.statusFile)
|
|
390
|
+
} catch (error) {
|
|
391
|
+
try {
|
|
392
|
+
if (existsSync(temp)) unlinkSync(temp)
|
|
393
|
+
} catch {
|
|
394
|
+
// Best-effort cleanup only; the original error is the one that matters.
|
|
395
|
+
}
|
|
396
|
+
throw error
|
|
397
|
+
}
|
|
398
|
+
return { status, path: paths.statusFile, written: true }
|
|
399
|
+
}
|
package/lib/source.js
ADDED
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Source provenance schema v2 (E2).
|
|
3
|
+
*
|
|
4
|
+
* Every candidate accepted into a commitment/fact/preference keeps a pointer to
|
|
5
|
+
* the local input it came from (docs/SOURCE-SCHEMA.md). v1 stored whatever the
|
|
6
|
+
* capture/import path happened to have, and evidence rows kept sessionId/turnId
|
|
7
|
+
* next to it. The two consequences were:
|
|
8
|
+
*
|
|
9
|
+
* - mail / calendar / transcript provenance had different ad-hoc field names
|
|
10
|
+
* in every entry point (uid vs messageId, speakers vs speaker, ...);
|
|
11
|
+
* - there was no version marker, so a reader could not tell v1 from a future
|
|
12
|
+
* schema.
|
|
13
|
+
*
|
|
14
|
+
* v2 is the canonical shape below, with an explicit sourceVersion marker:
|
|
15
|
+
*
|
|
16
|
+
* { sourceVersion: 2, type, quote, ref, messageId, subject, file, mime,
|
|
17
|
+
* speaker, tStart, tEnd, capturedAt }
|
|
18
|
+
*
|
|
19
|
+
* normalizeSource() maps legacy rows into this shape (and preserves unknown
|
|
20
|
+
* fields as extensions so old consumers keep working); validateSource() reports
|
|
21
|
+
* schema problems; toLegacySource() produces the lossy v1 view for consumers
|
|
22
|
+
* that have not migrated yet. Everything here is pure: no database, no
|
|
23
|
+
* filesystem, no network.
|
|
24
|
+
*
|
|
25
|
+
* @module source
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
/** Current source schema version. */
|
|
29
|
+
export const SOURCE_VERSION = 2
|
|
30
|
+
|
|
31
|
+
/** Canonical source types; any other stored type is preserved with a warning. */
|
|
32
|
+
export const SOURCE_TYPES = Object.freeze(['conversation', 'mail', 'calendar', 'transcript'])
|
|
33
|
+
|
|
34
|
+
/** Legacy type spellings that map onto a canonical type. */
|
|
35
|
+
export const SOURCE_TYPE_ALIASES = Object.freeze({ email: 'mail' })
|
|
36
|
+
|
|
37
|
+
const VERSION_KEYS = ['sourceVersion', 'source_v', 'source_version']
|
|
38
|
+
const FIELDS = Object.freeze([
|
|
39
|
+
'type',
|
|
40
|
+
'quote',
|
|
41
|
+
'ref',
|
|
42
|
+
'messageId',
|
|
43
|
+
'subject',
|
|
44
|
+
'file',
|
|
45
|
+
'mime',
|
|
46
|
+
'speaker',
|
|
47
|
+
'tStart',
|
|
48
|
+
'tEnd',
|
|
49
|
+
'capturedAt',
|
|
50
|
+
])
|
|
51
|
+
const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/
|
|
52
|
+
const MIME_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*(?:\s*;\s*[^;]+)*$/i
|
|
53
|
+
|
|
54
|
+
function isPlainObject(value) {
|
|
55
|
+
return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function trimmedString(value) {
|
|
59
|
+
return typeof value === 'string' ? value.trim() : ''
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function basename(value) {
|
|
63
|
+
const text = trimmedString(value)
|
|
64
|
+
if (!text) return ''
|
|
65
|
+
const parts = text.split(/[\\/]/)
|
|
66
|
+
return parts[parts.length - 1] ?? ''
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function hasPathSeparator(value) {
|
|
70
|
+
return typeof value === 'string' && /[\\/]/.test(value)
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function readVersion(raw) {
|
|
74
|
+
for (const key of VERSION_KEYS) {
|
|
75
|
+
if (raw[key] === undefined || raw[key] === null) continue
|
|
76
|
+
const numeric = Number(raw[key])
|
|
77
|
+
return Number.isFinite(numeric) ? numeric : Number.NaN
|
|
78
|
+
}
|
|
79
|
+
return undefined
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function canonicalType(value) {
|
|
83
|
+
const text = trimmedString(value).toLowerCase()
|
|
84
|
+
if (!text) return ''
|
|
85
|
+
return SOURCE_TYPE_ALIASES[text] ?? text
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function isCanonicalField(key) {
|
|
89
|
+
return FIELDS.includes(key) || VERSION_KEYS.includes(key)
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function isTimestamp(value) {
|
|
93
|
+
return typeof value === 'string' && ISO_DATE_TIME.test(value) && Number.isFinite(Date.parse(value))
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Normalise a v1 or v2 source row into the canonical v2 shape.
|
|
98
|
+
*
|
|
99
|
+
* Legacy mapping (documented in docs/SOURCE-SCHEMA.md):
|
|
100
|
+
* - email -> mail;
|
|
101
|
+
* - sessionId (+ turnId) -> ref 'sessionId#turnId'; turnId alone -> 'legacy#turnId';
|
|
102
|
+
* - calendar uid -> ref when no ref is present;
|
|
103
|
+
* - speakers[] -> speaker (first non-empty);
|
|
104
|
+
* - file is reduced to its basename (the schema never stores directories).
|
|
105
|
+
*
|
|
106
|
+
* Unknown fields (e.g. the imap channel / mail from) are preserved as
|
|
107
|
+
* extensions so older readers and later migrations do not lose information.
|
|
108
|
+
* The function never throws: non-object input returns null.
|
|
109
|
+
*
|
|
110
|
+
* @param {object|null|undefined} raw stored or freshly built source object
|
|
111
|
+
* @returns {object|null} canonical v2 source, or null when input is not an object
|
|
112
|
+
*/
|
|
113
|
+
export function normalizeSource(raw) {
|
|
114
|
+
if (!isPlainObject(raw)) return null
|
|
115
|
+
const out = { sourceVersion: SOURCE_VERSION }
|
|
116
|
+
|
|
117
|
+
const consumed = new Set()
|
|
118
|
+
const type = canonicalType(raw.type)
|
|
119
|
+
out.type = type || 'conversation'
|
|
120
|
+
|
|
121
|
+
const quote = typeof raw.quote === 'string' ? raw.quote : ''
|
|
122
|
+
if (quote) out.quote = quote
|
|
123
|
+
|
|
124
|
+
let ref = trimmedString(raw.ref)
|
|
125
|
+
if (!ref) {
|
|
126
|
+
const sessionId = trimmedString(raw.sessionId)
|
|
127
|
+
const turnId = trimmedString(raw.turnId)
|
|
128
|
+
if (sessionId) {
|
|
129
|
+
ref = turnId ? sessionId + '#' + turnId : sessionId
|
|
130
|
+
consumed.add('sessionId').add('turnId')
|
|
131
|
+
} else if (turnId) {
|
|
132
|
+
ref = 'legacy#' + turnId
|
|
133
|
+
consumed.add('turnId')
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
if (!ref && out.type === 'calendar') {
|
|
137
|
+
ref = trimmedString(raw.uid)
|
|
138
|
+
if (ref) consumed.add('uid')
|
|
139
|
+
}
|
|
140
|
+
if (ref) out.ref = ref
|
|
141
|
+
|
|
142
|
+
for (const field of ['messageId', 'subject']) {
|
|
143
|
+
const value = trimmedString(raw[field])
|
|
144
|
+
if (value) out[field] = value
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
const file = basename(raw.file)
|
|
148
|
+
if (file) out.file = file
|
|
149
|
+
|
|
150
|
+
const mime = trimmedString(raw.mime).toLowerCase()
|
|
151
|
+
if (mime) out.mime = mime
|
|
152
|
+
|
|
153
|
+
let speaker = trimmedString(raw.speaker)
|
|
154
|
+
if (!speaker && Array.isArray(raw.speakers)) {
|
|
155
|
+
speaker = raw.speakers.map((item) => trimmedString(item)).find(Boolean) ?? ''
|
|
156
|
+
if (speaker) consumed.add('speakers')
|
|
157
|
+
}
|
|
158
|
+
if (speaker) out.speaker = speaker
|
|
159
|
+
|
|
160
|
+
for (const field of ['tStart', 'tEnd', 'capturedAt']) {
|
|
161
|
+
const value = trimmedString(raw[field])
|
|
162
|
+
if (value) out[field] = value
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
// Forward/backward compatibility: keep fields this version does not know so
|
|
166
|
+
// that rendering older rows never silently drops provenance.
|
|
167
|
+
for (const key of Object.keys(raw)) {
|
|
168
|
+
if (isCanonicalField(key) || consumed.has(key)) continue
|
|
169
|
+
if (raw[key] === undefined) continue
|
|
170
|
+
out[key] = raw[key]
|
|
171
|
+
}
|
|
172
|
+
return out
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Validate a stored or freshly built source object against schema v2.
|
|
177
|
+
*
|
|
178
|
+
* Errors mean the row must not be written as a v2 source; warnings mean a
|
|
179
|
+
* legacy/unknown value was tolerated. Returns the normalised object so callers
|
|
180
|
+
* can validate and normalise in one pass.
|
|
181
|
+
*
|
|
182
|
+
* @param {unknown} raw source object (v1 or v2 shape)
|
|
183
|
+
* @returns {{ ok: boolean, errors: string[], warnings: string[], source: object|null }}
|
|
184
|
+
*/
|
|
185
|
+
export function validateSource(raw) {
|
|
186
|
+
const errors = []
|
|
187
|
+
const warnings = []
|
|
188
|
+
if (!isPlainObject(raw)) {
|
|
189
|
+
return { ok: false, errors: ['source must be an object'], warnings, source: null }
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
const version = readVersion(raw)
|
|
193
|
+
if (version !== undefined) {
|
|
194
|
+
if (Number.isNaN(version)) {
|
|
195
|
+
errors.push('sourceVersion must be numeric')
|
|
196
|
+
} else if (version !== 1 && version !== SOURCE_VERSION) {
|
|
197
|
+
warnings.push('unknown sourceVersion ' + version + '; normalised as v2')
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
const legacyMarkers = ['sessionId', 'turnId', 'uid', 'speakers'].filter((key) => raw[key] !== undefined && raw[key] !== null && raw[key] !== '')
|
|
202
|
+
if (version === 1 || (version === undefined && legacyMarkers.length > 0)) {
|
|
203
|
+
warnings.push('legacy v1 source mapped to v2')
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
for (const field of FIELDS) {
|
|
207
|
+
if (field === 'type') continue // handled below (aliases allowed)
|
|
208
|
+
if (raw[field] === undefined || raw[field] === null) continue
|
|
209
|
+
if (typeof raw[field] !== 'string') errors.push(field + ' must be a string')
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
const normalized = normalizeSource(raw)
|
|
213
|
+
if (!normalized) {
|
|
214
|
+
return { ok: false, errors: ['source must be an object'], warnings, source: null }
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
if (raw.type !== undefined && raw.type !== null) {
|
|
218
|
+
if (typeof raw.type !== 'string') {
|
|
219
|
+
errors.push('type must be a string')
|
|
220
|
+
} else if (!canonicalType(raw.type)) {
|
|
221
|
+
errors.push('type must not be empty')
|
|
222
|
+
} else if (!SOURCE_TYPES.includes(canonicalType(raw.type))) {
|
|
223
|
+
warnings.push('unknown source type "' + canonicalType(raw.type) + '" kept as-is')
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
if (raw.type === undefined || raw.type === null) {
|
|
227
|
+
warnings.push('missing source type; defaulted to conversation')
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
if (raw.file !== undefined && typeof raw.file === 'string' && hasPathSeparator(raw.file)) {
|
|
231
|
+
errors.push('file must be a basename, not a path')
|
|
232
|
+
}
|
|
233
|
+
if (raw.mime !== undefined && typeof raw.mime === 'string' && raw.mime.trim() && !MIME_TYPE.test(raw.mime.trim())) {
|
|
234
|
+
errors.push('mime must look like type/subtype')
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
for (const field of ['tStart', 'tEnd', 'capturedAt']) {
|
|
238
|
+
if (raw[field] === undefined || raw[field] === null) continue
|
|
239
|
+
if (typeof raw[field] !== 'string') continue // already reported above
|
|
240
|
+
if (!isTimestamp(raw[field])) {
|
|
241
|
+
errors.push(field + ' must be an ISO 8601 date or datetime')
|
|
242
|
+
continue
|
|
243
|
+
}
|
|
244
|
+
if (field === 'capturedAt' && Date.parse(raw[field]) > Date.now() + 24 * 60 * 60 * 1000) {
|
|
245
|
+
warnings.push('capturedAt is in the future')
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
if (isTimestamp(raw.tStart) && isTimestamp(raw.tEnd)) {
|
|
249
|
+
if (Date.parse(raw.tStart) > Date.parse(raw.tEnd)) errors.push('tStart must not be after tEnd')
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
const hasPointer = Boolean(normalized.ref || normalized.messageId || normalized.file)
|
|
253
|
+
const hasQuote = typeof normalized.quote === 'string' && normalized.quote.length > 0
|
|
254
|
+
if (!hasPointer && !hasQuote) {
|
|
255
|
+
errors.push('source has neither a pointer (ref/messageId/file) nor a quote')
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
return { ok: errors.length === 0, errors, warnings, source: normalized }
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** True when a row already carries the v2 version marker. */
|
|
262
|
+
export function isSourceV2(raw) {
|
|
263
|
+
if (!isPlainObject(raw)) return false
|
|
264
|
+
return readVersion(raw) === SOURCE_VERSION
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* Lossy v1 view for consumers that have not migrated yet.
|
|
269
|
+
*
|
|
270
|
+
* v1 never had mime/speaker/tStart/tEnd or the version marker, so those are
|
|
271
|
+
* dropped; a calendar ref becomes the legacy uid and a transcript speaker
|
|
272
|
+
* becomes the legacy speakers[] array. Use this only at a compatibility
|
|
273
|
+
* boundary; writing new rows should use normalizeSource().
|
|
274
|
+
*
|
|
275
|
+
* @param {object|null|undefined} source v1 or v2 source object
|
|
276
|
+
* @returns {object|null} v1-shaped source, or null for non-object input
|
|
277
|
+
*/
|
|
278
|
+
export function toLegacySource(source) {
|
|
279
|
+
const normalized = normalizeSource(source)
|
|
280
|
+
if (!normalized) return null
|
|
281
|
+
const legacy = { type: normalized.type }
|
|
282
|
+
for (const field of ['quote', 'ref', 'messageId', 'subject', 'file', 'capturedAt']) {
|
|
283
|
+
if (normalized[field] !== undefined) legacy[field] = normalized[field]
|
|
284
|
+
}
|
|
285
|
+
if (normalized.type === 'calendar' && normalized.ref) legacy.uid = normalized.ref
|
|
286
|
+
if (normalized.speaker) legacy.speakers = [normalized.speaker]
|
|
287
|
+
for (const key of Object.keys(normalized)) {
|
|
288
|
+
if (['sourceVersion'].includes(key)) continue
|
|
289
|
+
if (['type', 'quote', 'ref', 'messageId', 'subject', 'file', 'capturedAt', 'mime', 'speaker', 'tStart', 'tEnd'].includes(key)) continue
|
|
290
|
+
if (key === 'uid' || key === 'speakers') continue
|
|
291
|
+
legacy[key] = normalized[key]
|
|
292
|
+
}
|
|
293
|
+
return legacy
|
|
294
|
+
}
|