@pmndre/pine 0.22.1 → 0.33.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 (99) hide show
  1. package/README.md +2 -1
  2. package/changes.json +264 -0
  3. package/docs/SKILL.md +31 -7
  4. package/docs/references/agents.md +245 -21
  5. package/docs/references/coding.md +1 -1
  6. package/docs/references/computer.md +1 -1
  7. package/docs/references/configuration.md +14 -5
  8. package/docs/references/mcp.md +9 -0
  9. package/docs/references/operations.md +21 -10
  10. package/docs/references/overview.md +3 -1
  11. package/docs/references/security.md +83 -24
  12. package/docs/references/setup.md +55 -9
  13. package/docs/references/source-types.md +1418 -0
  14. package/docs/references/sources.md +333 -19
  15. package/docs/references/stack.md +1 -0
  16. package/docs/references/tui.md +86 -12
  17. package/examples/home/AGENTS.md +4 -0
  18. package/examples/home/TOOLS.md +5 -0
  19. package/examples/home/agents/main/workspace/AGENTS.md +1 -1
  20. package/examples/home/agents/main/workspace/TOOLS.md +5 -0
  21. package/mcp/browser.d.ts +6 -0
  22. package/mcp/browser.js +19 -0
  23. package/mcp/render.d.ts +1 -0
  24. package/mcp/render.js +237 -0
  25. package/package.json +6 -4
  26. package/src/actions.d.ts +6 -1
  27. package/src/actions.js +17 -4
  28. package/src/admin.d.ts +4 -0
  29. package/src/admin.js +25 -6
  30. package/src/agents.d.ts +167 -2
  31. package/src/agents.js +912 -45
  32. package/src/catalogue.d.ts +60 -0
  33. package/src/catalogue.js +791 -0
  34. package/src/cli.js +10 -7
  35. package/src/config.d.ts +53 -4
  36. package/src/config.js +30 -5
  37. package/src/goals.d.ts +1 -1
  38. package/src/goals.js +14 -1
  39. package/src/manual.js +24 -2
  40. package/src/mime.d.ts +78 -0
  41. package/src/mime.js +342 -0
  42. package/src/net.d.ts +11 -0
  43. package/src/net.js +29 -2
  44. package/src/pine.js +10 -1
  45. package/src/router.js +3 -3
  46. package/src/sandbox-linux.d.ts +3 -1
  47. package/src/sandbox-linux.js +5 -0
  48. package/src/security.d.ts +22 -6
  49. package/src/security.js +44 -13
  50. package/src/slots.d.ts +106 -0
  51. package/src/slots.js +250 -0
  52. package/src/source-types.d.ts +20 -0
  53. package/src/sources/calendar.d.ts +24 -0
  54. package/src/sources/calendar.js +265 -0
  55. package/src/sources/command.js +109 -4
  56. package/src/sources/discord.d.ts +4 -0
  57. package/src/sources/discord.js +298 -0
  58. package/src/sources/feed.d.ts +19 -0
  59. package/src/sources/feed.js +257 -0
  60. package/src/sources/http.js +154 -103
  61. package/src/sources/mail.d.ts +51 -0
  62. package/src/sources/mail.js +1013 -0
  63. package/src/sources/matrix.d.ts +4 -0
  64. package/src/sources/matrix.js +232 -0
  65. package/src/sources/modbus.d.ts +15 -0
  66. package/src/sources/modbus.js +240 -0
  67. package/src/sources/onvif.d.ts +35 -0
  68. package/src/sources/onvif.js +326 -0
  69. package/src/sources/presence.d.ts +80 -0
  70. package/src/sources/presence.js +480 -0
  71. package/src/sources/serial.d.ts +21 -0
  72. package/src/sources/serial.js +220 -0
  73. package/src/sources/slack.d.ts +16 -0
  74. package/src/sources/slack.js +1062 -0
  75. package/src/sources/smtp.d.ts +4 -0
  76. package/src/sources/smtp.js +360 -0
  77. package/src/sources/stream.d.ts +68 -0
  78. package/src/sources/stream.js +534 -0
  79. package/src/sources/syslog.d.ts +32 -0
  80. package/src/sources/syslog.js +243 -0
  81. package/src/sources/system.d.ts +14 -0
  82. package/src/sources/system.js +236 -0
  83. package/src/sources/system.swift +102 -0
  84. package/src/sources/telegram.js +34 -1
  85. package/src/sources.d.ts +41 -1
  86. package/src/sources.js +147 -24
  87. package/src/tools.d.ts +1 -1
  88. package/src/tools.js +304 -23
  89. package/src/tui/app.d.ts +35 -2
  90. package/src/tui/app.js +306 -43
  91. package/src/tui/levels.d.ts +68 -0
  92. package/src/tui/levels.js +273 -0
  93. package/src/tui/picture.d.ts +17 -1
  94. package/src/tui/picture.js +72 -5
  95. package/src/types.d.ts +3 -0
  96. package/src/update.d.ts +9 -1
  97. package/src/update.js +75 -3
  98. package/src/watching.d.ts +156 -0
  99. package/src/watching.js +609 -4
@@ -0,0 +1,220 @@
1
+ import { execFile, spawn } from "node:child_process";
2
+ import fs from "node:fs";
3
+ import path from "node:path";
4
+ import { StringDecoder } from "node:string_decoder";
5
+ import { Type } from "typebox";
6
+ import { capped, clip, found, pattern, shown } from "../watching.js";
7
+ /**
8
+ * A serial port: reports the lines a device prints on it. For a microcontroller that prints its
9
+ * readings (Arduino, ESP32), a smart meter's P1 port, a GPS receiver, a weather station, a UPS.
10
+ *
11
+ * options: { port, baud?, match?, changed?, perMinute? }
12
+ * port the device, /dev/cu.usbserial-1420 on a Mac, /dev/ttyUSB0 or /dev/ttyACM0 on Linux
13
+ * baud its speed (9600 by default)
14
+ * match only lines this regular expression finds; its first group is the value
15
+ * changed true: only a line (or value) that differs from the one before
16
+ * perMinute at most this many reports a minute (30 by default)
17
+ *
18
+ * event "line": { port, line, value?, previous?, dropped? }
19
+ *
20
+ * It listens and nothing else: nothing is ever written to the port.
21
+ */
22
+ const BAUDS = [300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600];
23
+ const LONGEST = 4096;
24
+ const first = (...files) => files.find((f) => fs.existsSync(f));
25
+ /** How long to wait before looking for a device again, at the start and at most. A test shortens them. */
26
+ export const timing = { retryMs: 1000, retryMaxMs: 60_000 };
27
+ /**
28
+ * Whether a name under /dev is a serial port by how it is called. A terminal somebody types into
29
+ * is a device of the same kind, and reading from it would take their keystrokes: those are
30
+ * called otherwise (ttys003, pts/4, tty1, console) and are never opened.
31
+ */
32
+ const serialName = (file) => /^\/dev\/(cu|tty)\.[A-Za-z0-9_.-]+$/.test(file) || /^\/dev\/(tty[A-Z][A-Za-z]*[0-9]+|rfcomm[0-9]+)$/.test(file);
33
+ /** The device a `port` option means: resolved, under /dev, there, and a serial port. Throws a sentence otherwise. */
34
+ export function portOf(raw) {
35
+ const given = String(raw ?? "").trim();
36
+ if (!path.isAbsolute(given))
37
+ throw new Error('"port" is the device\'s path: /dev/cu.usbserial-1420 on a Mac, /dev/ttyUSB0 or /dev/ttyACM0 on Linux');
38
+ let file;
39
+ try {
40
+ // A name under /dev/serial/by-id leads to the device itself.
41
+ file = fs.realpathSync(given);
42
+ }
43
+ catch {
44
+ throw new Error(`${given} is not there. Is the device plugged in? On a Mac the ports are listed by "ls /dev/cu.*", on Linux by "ls /dev/ttyUSB* /dev/ttyACM*"`);
45
+ }
46
+ if (!file.startsWith("/dev/"))
47
+ throw new Error(`${given} is not a device: a serial port lies under /dev`);
48
+ if (!fs.statSync(file).isCharacterDevice())
49
+ throw new Error(`${given} is not a serial port`);
50
+ if (!serialName(file))
51
+ throw new Error(`${given} is not a serial port by its name. One is called /dev/cu.<something> on a Mac, /dev/ttyUSB0, /dev/ttyACM0 or /dev/ttyS0 on Linux. A terminal is never read`);
52
+ // On a Mac the tty. name waits for a modem that is never there; the cu. name of the same port does not.
53
+ const twin = file.replace(/^\/dev\/tty\./, "/dev/cu.");
54
+ return twin !== file && fs.existsSync(twin) ? twin : file;
55
+ }
56
+ export const type = {
57
+ summary: "a serial port: reports the lines a device prints on it. For an Arduino or ESP32 that prints readings, a smart meter's P1 port, a GPS receiver. It only listens",
58
+ options: Type.Object({
59
+ port: Type.String({ description: "the device: /dev/cu.usbserial-1420 on a Mac, /dev/ttyUSB0 or /dev/ttyACM0 on Linux" }),
60
+ baud: Type.Optional(Type.Number({ description: "the speed the device sends at, e.g. 9600 or 115200. Default 9600" })),
61
+ match: Type.Optional(Type.String({ description: 'report only lines this regular expression finds; its first group becomes "value", e.g. "temp=([0-9.]+)"' })),
62
+ changed: Type.Optional(Type.Boolean({ description: "true to report a line (or its value) only when it differs from the one before. For a device that prints the same reading every second" })),
63
+ perMinute: Type.Optional(Type.Number({ description: "at most this many reports a minute; the rest are dropped and counted. Default 30" })),
64
+ }, { additionalProperties: false }),
65
+ plan(o) {
66
+ const port = portOf(o.port);
67
+ const baud = o.baud ?? 9600;
68
+ if (!BAUDS.includes(baud))
69
+ throw new Error(`"baud" is one of ${BAUDS.join(", ")}`);
70
+ if (o.match)
71
+ pattern(o.match);
72
+ if (o.perMinute !== undefined && !(Number.isInteger(o.perMinute) && o.perMinute >= 1 && o.perMinute <= 600))
73
+ throw new Error('"perMinute" is a whole number from 1 to 600');
74
+ return {
75
+ options: { ...o, port },
76
+ does: [`read the serial port ${port} at ${baud} baud and report ${o.match ? `the lines /${o.match}/ finds` : "the lines that arrive"}${o.changed ? ", when they differ from the one before" : ""}, at most ${o.perMinute ?? 30} a minute`, "it only listens: nothing is written to the port"],
77
+ opens: true,
78
+ tell: "It reports from the next line on. The sources tool shows whether the device is there.",
79
+ };
80
+ },
81
+ };
82
+ /** Lines out of bytes as they arrive: split at any line end, without control characters, none longer than a line can be. */
83
+ export function lines(onLine) {
84
+ const decoder = new StringDecoder("utf8");
85
+ let rest = "";
86
+ return (chunk) => {
87
+ rest += decoder.write(chunk);
88
+ for (;;) {
89
+ const at = rest.search(/[\r\n]/);
90
+ if (at < 0 && rest.length < LONGEST)
91
+ return;
92
+ const raw = at < 0 ? rest.slice(0, LONGEST) : rest.slice(0, at);
93
+ rest = at < 0 ? rest.slice(LONGEST) : rest.slice(at + 1);
94
+ const line = raw.replace(/\t/g, " ").replace(/[\u0000-\u001f\u007f-\u009f�]/g, "").trim();
95
+ if (line)
96
+ onLine(line);
97
+ }
98
+ };
99
+ }
100
+ /**
101
+ * Listen to a serial device until `stop` is called. The device is held open by a reader that
102
+ * does nothing else (`cat`, started by its path with the device as its one argument), and its
103
+ * speed is set while it is open, since a Mac forgets the setting when the last holder lets go.
104
+ * `state` says how it stands: "listening", "waiting" (the device is not there), "unset" (the
105
+ * speed could not be set).
106
+ */
107
+ export function listen(file, baud, onLine, state) {
108
+ const cat = first("/bin/cat", "/usr/bin/cat");
109
+ const stty = first("/bin/stty", "/usr/bin/stty");
110
+ if (!cat || !stty)
111
+ throw new Error("this system has no cat or stty to read a serial port with");
112
+ let stopped = false;
113
+ let child;
114
+ let timer;
115
+ let wait = timing.retryMs;
116
+ const again = (now) => {
117
+ if (stopped)
118
+ return;
119
+ state(now);
120
+ timer = setTimeout(start, wait);
121
+ timer.unref?.();
122
+ wait = Math.min(wait * 2, timing.retryMaxMs);
123
+ };
124
+ const start = () => {
125
+ if (stopped)
126
+ return;
127
+ let there = false;
128
+ try {
129
+ there = fs.statSync(file).isCharacterDevice();
130
+ }
131
+ catch {
132
+ // unplugged
133
+ }
134
+ if (!there)
135
+ return again("waiting");
136
+ const reader = spawn(cat, [file], { stdio: ["ignore", "pipe", "ignore"] });
137
+ child = reader;
138
+ let ready = false;
139
+ let failed = false;
140
+ const feed = lines(onLine);
141
+ // What arrived before the speed was set was read at the wrong one.
142
+ reader.stdout.on("data", (d) => ready && feed(d));
143
+ reader.on("error", () => { });
144
+ reader.on("close", () => {
145
+ if (child === reader)
146
+ child = undefined;
147
+ again(failed ? "unset" : "waiting");
148
+ });
149
+ execFile(stty, [process.platform === "linux" ? "-F" : "-f", file, String(baud), "raw", "-echo", "cs8", "-parenb", "-cstopb", "clocal", "cread"], { timeout: 5000 }, (err) => {
150
+ if (stopped || child !== reader)
151
+ return;
152
+ if (err) {
153
+ failed = true;
154
+ return void reader.kill("SIGKILL");
155
+ }
156
+ ready = true;
157
+ wait = timing.retryMs;
158
+ state("listening");
159
+ });
160
+ };
161
+ start();
162
+ return () => {
163
+ stopped = true;
164
+ clearTimeout(timer);
165
+ child?.kill("SIGKILL");
166
+ };
167
+ }
168
+ export default function serial(source) {
169
+ const o = source.options;
170
+ let file;
171
+ try {
172
+ file = portOf(o.port);
173
+ }
174
+ catch (e) {
175
+ // Unplugged right now: it is waited for under the name it was set up with, if that is a serial port's.
176
+ const given = String(o.port ?? "");
177
+ if (!serialName(given) || fs.existsSync(given))
178
+ throw e;
179
+ file = given;
180
+ }
181
+ const baud = Number(o.baud ?? 9600);
182
+ if (!BAUDS.includes(baud))
183
+ throw new Error(`"baud" is one of ${BAUDS.join(", ")}`);
184
+ const re = o.match ? pattern(String(o.match)) : undefined;
185
+ const cap = capped(Number(o.perMinute ?? 30));
186
+ const name = path.basename(file);
187
+ let count = 0;
188
+ const onLine = (line) => {
189
+ let value;
190
+ if (re) {
191
+ const hit = found(re, line);
192
+ if (hit === null)
193
+ return;
194
+ value = /^-?\d+(\.\d+)?$/.test(hit) ? Number(hit) : hit;
195
+ }
196
+ else {
197
+ try {
198
+ value = JSON.parse(line);
199
+ }
200
+ catch {
201
+ // a line of text
202
+ }
203
+ }
204
+ let previous;
205
+ if (o.changed === true) {
206
+ const was = source.changed(value ?? line);
207
+ if (!was)
208
+ return;
209
+ previous = was.previous;
210
+ }
211
+ if (!cap.ok())
212
+ return;
213
+ const dropped = cap.dropped();
214
+ count++;
215
+ source.status(`listening on ${name} at ${baud} baud, ${count} line${count === 1 ? "" : "s"} reported`);
216
+ source.emit("line", { port: file, line: clip(line, 1000), ...(value !== undefined ? { value: shown(value) } : {}), ...(previous !== undefined ? { previous: shown(previous) } : {}), ...(dropped ? { dropped } : {}) });
217
+ };
218
+ const stop = listen(file, baud, onLine, (now) => source.status(now === "listening" ? `listening on ${name} at ${baud} baud${count ? `, ${count} line${count === 1 ? "" : "s"} reported` : ""}` : now === "waiting" ? `waiting for ${name}: it is not there (unplugged?)` : `${name} does not take ${baud} baud; trying again`));
219
+ source.onStop(stop);
220
+ }
@@ -0,0 +1,16 @@
1
+ import type { SourceType } from "../source-types.ts";
2
+ import type { SourceApi } from "../sources.ts";
3
+ /**
4
+ * Times the tests set: what a second of "wait this long" from Slack lasts, how long a new
5
+ * connection may take to be greeted, within what time Slack has to answer a ping (the SDK pings
6
+ * three times in that time, and takes a connection without an answer for dead), and how long a
7
+ * goodbye is waited for before the socket is cut.
8
+ */
9
+ export declare const pace: {
10
+ second: number;
11
+ hello: number;
12
+ ping: number;
13
+ bye: number;
14
+ };
15
+ export declare const type: SourceType;
16
+ export default function slack(source: SourceApi): Promise<void>;