@narumitw/pi-herdr 0.2.0 → 0.3.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/README.md +8 -0
- package/package.json +51 -52
- package/skills/herdr/SKILL.md +12 -0
- package/src/herdr-agent-state.ts +404 -411
- package/src/herdr-client.ts +236 -238
- package/src/herdr-menu.ts +49 -50
- package/src/herdr-metadata.ts +46 -52
- package/src/herdr-observer.ts +334 -372
- package/src/herdr-protocol.ts +185 -187
- package/src/herdr-settings-controller.ts +118 -124
- package/src/herdr-widget.ts +204 -217
- package/src/settings.ts +131 -135
package/src/settings.ts
CHANGED
|
@@ -8,17 +8,17 @@ export const HERDR_SETTINGS_FILE = "pi-herdr.json";
|
|
|
8
8
|
const MAX_SETTINGS_BYTES = 64 * 1024;
|
|
9
9
|
|
|
10
10
|
export interface HerdrSettings {
|
|
11
|
-
|
|
11
|
+
widget: boolean;
|
|
12
12
|
}
|
|
13
13
|
|
|
14
14
|
export type HerdrSettingsLoadResult =
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
15
|
+
| { kind: "missing"; settings: HerdrSettings }
|
|
16
|
+
| { kind: "invalid"; reason: string; settings: HerdrSettings }
|
|
17
|
+
| { kind: "loaded"; settings: HerdrSettings };
|
|
18
18
|
|
|
19
19
|
export interface UpdateHerdrSettingsOptions {
|
|
20
|
-
|
|
21
|
-
|
|
20
|
+
settingsPath?: string;
|
|
21
|
+
beforeRename?: (temporaryPath: string, settingsPath: string) => Promise<void>;
|
|
22
22
|
}
|
|
23
23
|
|
|
24
24
|
type SettingsDocument = Record<string, unknown>;
|
|
@@ -26,167 +26,163 @@ const DEFAULT_SETTINGS: HerdrSettings = { widget: true };
|
|
|
26
26
|
const queues = new Map<string, Promise<void>>();
|
|
27
27
|
|
|
28
28
|
export function herdrSettingsPath(): string {
|
|
29
|
-
|
|
29
|
+
return join(getAgentDir(), HERDR_SETTINGS_FILE);
|
|
30
30
|
}
|
|
31
31
|
|
|
32
32
|
export function normalizeHerdrSettings(value: unknown): HerdrSettings | undefined {
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
33
|
+
if (!isRecord(value)) return undefined;
|
|
34
|
+
if (Object.hasOwn(value, "widget") && typeof value.widget !== "boolean") {
|
|
35
|
+
return undefined;
|
|
36
|
+
}
|
|
37
|
+
return {
|
|
38
|
+
widget: typeof value.widget === "boolean" ? value.widget : DEFAULT_SETTINGS.widget,
|
|
39
|
+
};
|
|
40
40
|
}
|
|
41
41
|
|
|
42
|
-
export function readHerdrSettings(
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
};
|
|
67
|
-
});
|
|
42
|
+
export function readHerdrSettings(settingsPath = herdrSettingsPath()): Promise<HerdrSettingsLoadResult> {
|
|
43
|
+
return enqueue(settingsPath, async () => {
|
|
44
|
+
let document: SettingsDocument;
|
|
45
|
+
try {
|
|
46
|
+
document = await readSettingsDocument(settingsPath);
|
|
47
|
+
} catch (error) {
|
|
48
|
+
if (isNodeError(error) && error.code === "ENOENT") {
|
|
49
|
+
return { kind: "missing", settings: { ...DEFAULT_SETTINGS } };
|
|
50
|
+
}
|
|
51
|
+
return {
|
|
52
|
+
kind: "invalid",
|
|
53
|
+
reason: `${settingsPath}: ${safeError(error)}`,
|
|
54
|
+
settings: { ...DEFAULT_SETTINGS },
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
const settings = normalizeHerdrSettings(document);
|
|
58
|
+
return settings
|
|
59
|
+
? { kind: "loaded", settings }
|
|
60
|
+
: {
|
|
61
|
+
kind: "invalid",
|
|
62
|
+
reason: `${settingsPath}: invalid settings shape`,
|
|
63
|
+
settings: { ...DEFAULT_SETTINGS },
|
|
64
|
+
};
|
|
65
|
+
});
|
|
68
66
|
}
|
|
69
67
|
|
|
70
68
|
export function updateHerdrSettings(
|
|
71
|
-
|
|
72
|
-
|
|
69
|
+
patch: Partial<HerdrSettings>,
|
|
70
|
+
options: UpdateHerdrSettingsOptions = {},
|
|
73
71
|
): Promise<HerdrSettings> {
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
72
|
+
const settingsPath = options.settingsPath ?? herdrSettingsPath();
|
|
73
|
+
return enqueue(settingsPath, async () => {
|
|
74
|
+
const current = await readDocumentForUpdate(settingsPath);
|
|
75
|
+
const updated = { ...current, ...patch };
|
|
76
|
+
const settings = normalizeHerdrSettings(updated);
|
|
77
|
+
if (!settings) throw new Error(`Pi Herdr settings at ${settingsPath} have an invalid shape.`);
|
|
78
|
+
await publishSettings(settingsPath, updated, options);
|
|
79
|
+
return settings;
|
|
80
|
+
});
|
|
83
81
|
}
|
|
84
82
|
|
|
85
83
|
export async function awaitHerdrSettingsWrites(settingsPath = herdrSettingsPath()): Promise<void> {
|
|
86
|
-
|
|
84
|
+
await queues.get(settingsPath);
|
|
87
85
|
}
|
|
88
86
|
|
|
89
87
|
function enqueue<T>(path: string, operation: () => Promise<T>): Promise<T> {
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
88
|
+
const previous = queues.get(path) ?? Promise.resolve();
|
|
89
|
+
const result = previous.then(operation, operation);
|
|
90
|
+
const settled = result.then(
|
|
91
|
+
() => undefined,
|
|
92
|
+
() => undefined,
|
|
93
|
+
);
|
|
94
|
+
queues.set(path, settled);
|
|
95
|
+
void settled.finally(() => {
|
|
96
|
+
if (queues.get(path) === settled) queues.delete(path);
|
|
97
|
+
});
|
|
98
|
+
return result;
|
|
101
99
|
}
|
|
102
100
|
|
|
103
101
|
async function readDocumentForUpdate(path: string): Promise<SettingsDocument> {
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
102
|
+
try {
|
|
103
|
+
const document = await readSettingsDocument(path);
|
|
104
|
+
if (!normalizeHerdrSettings(document)) throw new Error("invalid settings shape");
|
|
105
|
+
return document;
|
|
106
|
+
} catch (error) {
|
|
107
|
+
if (isNodeError(error) && error.code === "ENOENT") return {};
|
|
108
|
+
throw new Error(`Pi Herdr settings at ${path} are invalid: ${safeError(error)}`);
|
|
109
|
+
}
|
|
112
110
|
}
|
|
113
111
|
|
|
114
112
|
async function readSettingsDocument(path: string): Promise<SettingsDocument> {
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
await handle.close();
|
|
157
|
-
}
|
|
113
|
+
const pathStats = await lstat(path);
|
|
114
|
+
if (pathStats.isSymbolicLink() || !pathStats.isFile()) {
|
|
115
|
+
throw new Error("settings path is not a regular file");
|
|
116
|
+
}
|
|
117
|
+
if (pathStats.size > MAX_SETTINGS_BYTES) {
|
|
118
|
+
throw new Error(`settings file exceeds ${MAX_SETTINGS_BYTES} bytes`);
|
|
119
|
+
}
|
|
120
|
+
const noFollow = constants.O_NOFOLLOW ?? 0;
|
|
121
|
+
const handle = await open(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | noFollow);
|
|
122
|
+
try {
|
|
123
|
+
const stats = await handle.stat();
|
|
124
|
+
if (!stats.isFile() || stats.dev !== pathStats.dev || stats.ino !== pathStats.ino) {
|
|
125
|
+
throw new Error("settings path changed while opening");
|
|
126
|
+
}
|
|
127
|
+
const buffer = Buffer.alloc(MAX_SETTINGS_BYTES + 1);
|
|
128
|
+
let offset = 0;
|
|
129
|
+
while (offset < buffer.length) {
|
|
130
|
+
const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
|
|
131
|
+
if (bytesRead === 0) break;
|
|
132
|
+
offset += bytesRead;
|
|
133
|
+
}
|
|
134
|
+
if (offset > MAX_SETTINGS_BYTES) {
|
|
135
|
+
throw new Error(`settings file exceeds ${MAX_SETTINGS_BYTES} bytes`);
|
|
136
|
+
}
|
|
137
|
+
let contents: string;
|
|
138
|
+
try {
|
|
139
|
+
contents = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, offset));
|
|
140
|
+
} catch {
|
|
141
|
+
throw new Error("settings file is not valid UTF-8");
|
|
142
|
+
}
|
|
143
|
+
let parsed: unknown;
|
|
144
|
+
try {
|
|
145
|
+
parsed = JSON.parse(contents) as unknown;
|
|
146
|
+
} catch {
|
|
147
|
+
throw new Error("invalid JSON");
|
|
148
|
+
}
|
|
149
|
+
if (!isRecord(parsed)) throw new Error("settings document must be a JSON object");
|
|
150
|
+
return parsed;
|
|
151
|
+
} finally {
|
|
152
|
+
await handle.close();
|
|
153
|
+
}
|
|
158
154
|
}
|
|
159
155
|
|
|
160
156
|
async function publishSettings(
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
157
|
+
path: string,
|
|
158
|
+
document: SettingsDocument,
|
|
159
|
+
options: UpdateHerdrSettingsOptions,
|
|
164
160
|
): Promise<void> {
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
161
|
+
const contents = `${JSON.stringify(document, null, 2)}\n`;
|
|
162
|
+
if (Buffer.byteLength(contents) > MAX_SETTINGS_BYTES) {
|
|
163
|
+
throw new Error(`Pi Herdr settings document exceeds ${MAX_SETTINGS_BYTES} bytes.`);
|
|
164
|
+
}
|
|
165
|
+
const directory = dirname(path);
|
|
166
|
+
await mkdir(directory, { recursive: true });
|
|
167
|
+
const temporaryPath = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
|
|
168
|
+
try {
|
|
169
|
+
await writeFile(temporaryPath, contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
|
|
170
|
+
await options.beforeRename?.(temporaryPath, path);
|
|
171
|
+
await rename(temporaryPath, path);
|
|
172
|
+
} catch (error) {
|
|
173
|
+
await rm(temporaryPath, { force: true }).catch(() => undefined);
|
|
174
|
+
throw error;
|
|
175
|
+
}
|
|
180
176
|
}
|
|
181
177
|
|
|
182
178
|
function isRecord(value: unknown): value is SettingsDocument {
|
|
183
|
-
|
|
179
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
184
180
|
}
|
|
185
181
|
|
|
186
182
|
function isNodeError(error: unknown): error is NodeJS.ErrnoException {
|
|
187
|
-
|
|
183
|
+
return error instanceof Error && "code" in error;
|
|
188
184
|
}
|
|
189
185
|
|
|
190
186
|
function safeError(error: unknown): string {
|
|
191
|
-
|
|
187
|
+
return error instanceof Error ? error.message : String(error);
|
|
192
188
|
}
|