clavarium-docket 0.1.0-next.1 → 0.1.0-next.2
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/docs/protocol.md +6 -3
- package/host/docket-host.mjs +10 -1
- package/package.json +1 -1
- package/server/docket.mjs +3 -3
- package/server/time.mjs +12 -2
package/docs/protocol.md
CHANGED
|
@@ -12,8 +12,9 @@ a library for the application that posts events.
|
|
|
12
12
|
| `acks.jsonl` | the worker | what it did of each event: done, or failed and why |
|
|
13
13
|
| `plans.jsonl` | the worker | the reminders it set itself, and those it took back |
|
|
14
14
|
| `plans-off.jsonl` | the application | the reminders the person took back |
|
|
15
|
+
| `zone` | the application | the person's time zone, one IANA name (optional) |
|
|
15
16
|
|
|
16
|
-
Every file only grows: nothing is edited, nothing is deleted. Each has one
|
|
17
|
+
Every `.jsonl` file only grows: nothing is edited, nothing is deleted. Each has one
|
|
17
18
|
writer. There is no address, no port and no key: whoever can read and write
|
|
18
19
|
the folder is a side.
|
|
19
20
|
|
|
@@ -60,8 +61,9 @@ command: 0 done, 1 refused, 2 no folder, 64 not understood.
|
|
|
60
61
|
|
|
61
62
|
## Time
|
|
62
63
|
|
|
63
|
-
A folder's time zone is `$DOCKET_TZ` (an IANA name, `Europe/Paris`), else
|
|
64
|
-
|
|
64
|
+
A folder's time zone is `$DOCKET_TZ` (an IANA name, `Europe/Paris`), else
|
|
65
|
+
the one the application wrote in its `zone` file (`zone(tz)`: the person's,
|
|
66
|
+
since a machine often runs in UTC), else the machine's. It is written into each plan, so that a cron line keeps meaning
|
|
65
67
|
what it meant where it was set.
|
|
66
68
|
|
|
67
69
|
## Reminders become events
|
|
@@ -81,6 +83,7 @@ was due.
|
|
|
81
83
|
| `read()` | `events` (each with `state`: `waiting`, `done` or `failed`, and its `ack`), `plans` (each with `next`, or `off`), `waiting` (how many) |
|
|
82
84
|
| `tick(now?)` | the events it posted |
|
|
83
85
|
| `cancel(plan)` | the plan taken back, by the person |
|
|
86
|
+
| `zone(tz)` | the folder's time zone written |
|
|
84
87
|
| `listen({every})` | events of its own: `acked` (`{event, ack}`), `planned` (`{plan}`), `cancelled` (`{plan}`) |
|
|
85
88
|
|
|
86
89
|
`WAKE` is one line the application may type to a worker that waits at a
|
package/host/docket-host.mjs
CHANGED
|
@@ -14,10 +14,11 @@
|
|
|
14
14
|
* WHAT IS READ HERE WAS WRITTEN BY A WORKER: its notes and its reminders are
|
|
15
15
|
* text chosen by a program, bounded and cleaned, handed over as text.
|
|
16
16
|
*/
|
|
17
|
-
import { appendFileSync, mkdirSync, statSync, lstatSync } from 'node:fs';
|
|
17
|
+
import { appendFileSync, mkdirSync, statSync, lstatSync, writeFileSync, renameSync } from 'node:fs';
|
|
18
18
|
import { join } from 'node:path';
|
|
19
19
|
import { randomUUID } from 'node:crypto';
|
|
20
20
|
import { state, tick, oneLine, TEXT_MAX, DATA_MAX, WAKE, VERSION, FOLDER } from '../server/docket.mjs';
|
|
21
|
+
import { isZone } from '../server/time.mjs';
|
|
21
22
|
|
|
22
23
|
export { WAKE, VERSION, FOLDER };
|
|
23
24
|
|
|
@@ -46,6 +47,14 @@ export class Docket {
|
|
|
46
47
|
/* The reminders that came due, posted as events: once each time each is due. */
|
|
47
48
|
tick(now = this.#now()) { return tick(this.#dir, { now }); }
|
|
48
49
|
|
|
50
|
+
/* The person's time zone (an IANA name), written for the worker: the times it gives are read in it. */
|
|
51
|
+
zone(tz) {
|
|
52
|
+
if (!isZone(tz)) throw new RangeError('Not a time zone.');
|
|
53
|
+
mkdirSync(this.#dir, { recursive: true });
|
|
54
|
+
writeFileSync(join(this.#dir, 'zone.new'), `${tz}\n`);
|
|
55
|
+
renameSync(join(this.#dir, 'zone.new'), join(this.#dir, 'zone'));
|
|
56
|
+
}
|
|
57
|
+
|
|
49
58
|
/* The person takes a reminder back. */
|
|
50
59
|
cancel(plan) {
|
|
51
60
|
const found = this.read().plans.find((p) => p.id === plan);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "clavarium-docket",
|
|
3
|
-
"version": "0.1.0-next.
|
|
3
|
+
"version": "0.1.0-next.2",
|
|
4
4
|
"description": "Clavarium Docket: events an AI agent or a script sees and acknowledges, and reminders it sets itself (a command and an MCP server, and a library for the application). No dependency.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/clavarium/clavarium-docket#readme",
|
package/server/docket.mjs
CHANGED
|
@@ -25,7 +25,7 @@ import { randomUUID, createHash } from 'node:crypto';
|
|
|
25
25
|
import { createInterface } from 'node:readline';
|
|
26
26
|
import { zoneOf, isZone, parseWhen, parseIn, parseCron, nextCron, lastCron, wall } from './time.mjs';
|
|
27
27
|
|
|
28
|
-
export const VERSION = '0.1.0-next.
|
|
28
|
+
export const VERSION = '0.1.0-next.2';
|
|
29
29
|
export const FOLDER = '.docket';
|
|
30
30
|
export const TEXT_MAX = 500;
|
|
31
31
|
export const NOTE_MAX = 1000;
|
|
@@ -115,7 +115,7 @@ export function verbs(dir, { env = process.env, now = () => Date.now() } = {}) {
|
|
|
115
115
|
if (waiting.length === 0) said.push('Nothing waits.');
|
|
116
116
|
else {
|
|
117
117
|
said.push(`Waiting (${waiting.length}), oldest first; say what you did of each: docket done ID, or docket failed ID "why".`);
|
|
118
|
-
const tz = zoneOf(env);
|
|
118
|
+
const tz = zoneOf(env, dir);
|
|
119
119
|
const when = (e) => (Number.isFinite(Date.parse(e.at)) ? stamp(Date.parse(e.at), tz).replace(/ \(.*\)$/, '') : '?');
|
|
120
120
|
for (const e of waiting.slice(0, LISTED_MAX)) said.push(` [${e.id.slice(0, ID_SHOWN)}] ${when(e)} ${e.from}/${e.kind}${e.late ? ' (late)' : ''}: ${e.text}${e.data ? `\n data: ${JSON.stringify(e.data).slice(0, 500)}` : ''}`);
|
|
121
121
|
if (waiting.length > LISTED_MAX) said.push(` ... and ${waiting.length - LISTED_MAX} more`);
|
|
@@ -140,7 +140,7 @@ export function verbs(dir, { env = process.env, now = () => Date.now() } = {}) {
|
|
|
140
140
|
if (given !== 1) throw new Error('give one of: --at "2026-10-23 09:00", --in 2h, --cron "0 9 * * 1"');
|
|
141
141
|
const s = state(dir, { now: now() });
|
|
142
142
|
if (s.plans.filter((p) => !p.off && p.next !== null).length >= PLANS_MAX) throw new Error(`${PLANS_MAX} reminders at most: take one back first`);
|
|
143
|
-
const tz = zoneOf(env);
|
|
143
|
+
const tz = zoneOf(env, dir);
|
|
144
144
|
if (cron) {
|
|
145
145
|
const c = parseCron(cron);
|
|
146
146
|
if (!c) throw new Error('a cron line is five fields: minute hour day month weekday ("0 9 * * 1": Mondays at 9:00)');
|
package/server/time.mjs
CHANGED
|
@@ -1,11 +1,21 @@
|
|
|
1
|
+
import { lstatSync, readFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
|
|
1
4
|
/* TIME, for reminders: a wall-clock time in a time zone, a cron line, and when
|
|
2
5
|
* it is next due. No dependency: the time zones are the platform's (Intl).
|
|
3
6
|
*/
|
|
4
7
|
|
|
5
|
-
/* The time zone a folder works in: $DOCKET_TZ, else the
|
|
6
|
-
|
|
8
|
+
/* The time zone a folder works in: $DOCKET_TZ, else what the application wrote in its `zone` file
|
|
9
|
+
(the person's: a machine often runs in UTC), else the machine's. */
|
|
10
|
+
export function zoneOf(env = process.env, dir) {
|
|
7
11
|
const given = String(env.DOCKET_TZ ?? '').trim();
|
|
8
12
|
if (given && isZone(given)) return given;
|
|
13
|
+
if (dir) {
|
|
14
|
+
try {
|
|
15
|
+
const file = join(dir, 'zone');
|
|
16
|
+
if (lstatSync(file).isFile() && lstatSync(file).size <= 64) { const written = readFileSync(file, 'utf8').trim(); if (isZone(written)) return written; }
|
|
17
|
+
} catch { /* none written */ }
|
|
18
|
+
}
|
|
9
19
|
try { return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'; } catch { return 'UTC'; }
|
|
10
20
|
}
|
|
11
21
|
export function isZone(tz) { try { new Intl.DateTimeFormat('en-US', { timeZone: tz }); return /^[A-Za-z0-9_+\-/]{1,64}$/.test(tz); } catch { return false; } }
|