@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
ts 514 lines 19.8 KB
Raw
1 // @effect-diagnostics nodeBuiltinImport:off - the guarded file read needs open
2 // flags (O_NOFOLLOW, O_NONBLOCK) the FileSystem service does not expose.
3 import * as NodeFS from "node:fs";
4 import * as NodePath from "node:path";
5
6 import {
7 type DefaultAppearancePreference,
8 EnvironmentTheme,
9 type ServerSettingsError,
10 EnvironmentThemeFile,
11 EnvironmentThemeId,
12 environmentThemeFileHasColors,
13 THEME_CSS_MAX_LENGTH,
14 } from "@t3tools/contracts";
15 import { fromJsonStringPretty } from "@t3tools/shared/schemaJson";
16 import { themeCssLoadsRemoteFiles } from "@t3tools/shared/themeCss";
17 import {
18 MOBILE_DEFAULT_THEME_ID,
19 MOBILE_THEME_IDS,
20 UNPUBLISHABLE_THEME_IDS,
21 } from "@t3tools/shared/themePalettes";
22 import * as Cause from "effect/Cause";
23 import * as Context from "effect/Context";
24 import * as DateTime from "effect/DateTime";
25 import * as Deferred from "effect/Deferred";
26 import * as Duration from "effect/Duration";
27 import * as Effect from "effect/Effect";
28 import * as Equal from "effect/Equal";
29 import * as Exit from "effect/Exit";
30 import * as FileSystem from "effect/FileSystem";
31 import * as Layer from "effect/Layer";
32 import * as Option from "effect/Option";
33 import * as PubSub from "effect/PubSub";
34 import * as Ref from "effect/Ref";
35 import * as Schema from "effect/Schema";
36 import * as Semaphore from "effect/Semaphore";
37 import * as Scope from "effect/Scope";
38 import * as Stream from "effect/Stream";
39
40 import * as ServerConfig from "./config.ts";
41 import * as ServerSettings from "./serverSettings.ts";
42 import { watchDirectoryPath } from "./watchDirectoryReplacements.ts";
43
44 const decodeEnvironmentThemeFileJsonExit = Schema.decodeUnknownExit(
45 Schema.fromJsonString(EnvironmentThemeFile),
46 );
47 const encodeEnvironmentThemeFileJson = Schema.encodeEffect(
48 fromJsonStringPretty(EnvironmentThemeFile),
49 );
50 const isEnvironmentThemeId = Schema.is(EnvironmentThemeId);
51
52 const THEME_FILE_SUFFIX = ".json";
53
54 const MAX_THEME_FILES = 32;
55 /**
56 * Shared with publishing so it cannot accept files the watcher skips. Fits the longest CSS in any
57 * JSON encoding, at up to 6 bytes per character for a `\uXXXX` escape, plus the colors.
58 */
59 export const MAX_THEME_FILE_BYTES = 6 * THEME_CSS_MAX_LENGTH + 16 * 1024;
60 // Clients cache every published theme in localStorage, which holds about 5 MB per origin.
61 const MAX_THEME_TOTAL_BYTES = 2 * 1024 * 1024;
62
63 /** A theme's background is `<id>.<extension>` beside `<id>.json`; earlier extensions win. */
64 const THEME_BACKGROUND_EXTENSIONS = ["webp", "png", "jpg", "jpeg"] as const;
65 const MAX_THEME_BACKGROUND_BYTES = 16 * 1024 * 1024;
66
67 interface PublishedThemes {
68 readonly seq: number;
69 readonly themes: ReadonlyArray<EnvironmentTheme>;
70 }
71
72 const INVALID_ID =
73 "is not a valid theme id. Use lowercase letters, digits, and hyphens, and not a built-in name.";
74 const NOT_PUBLISHED = "could not be published. The themes directory may be full or not writable.";
75
76 /** A theme the service will not publish or select. `problem` ends the sentence naming it. */
77 export class EnvironmentThemeRefusedError extends Schema.TaggedError<EnvironmentThemeRefusedError>()(
78 "EnvironmentThemeRefusedError",
79 {
80 themeId: Schema.String,
81 problem: Schema.String,
82 known: Schema.optional(Schema.Array(Schema.String)),
83 cause: Schema.optional(Schema.Defect()),
84 },
85 ) {
86 override get message(): string {
87 const known = this.known ? ` Available: ${this.known.join(", ")}.` : "";
88 return `Theme "${this.themeId}" ${this.problem}${known}`;
89 }
90 }
91
92 /** The settings write that makes a theme or mode the default failed. */
93 export class EnvironmentThemeNotSelectedError extends Schema.TaggedError<EnvironmentThemeNotSelectedError>()(
94 "EnvironmentThemeNotSelectedError",
95 {
96 /** Absent when only the appearance was set. */
97 themeId: Schema.optional(Schema.String),
98 cause: Schema.Defect(),
99 },
100 ) {
101 override get message(): string {
102 const subject = this.themeId === undefined ? "The appearance" : `Theme "${this.themeId}"`;
103 return `${subject} was not applied, because the settings could not be saved.`;
104 }
105 }
106
107 export class EnvironmentThemeService extends Context.Service<
108 EnvironmentThemeService,
109 {
110 readonly current: Effect.Effect<ReadonlyArray<EnvironmentTheme>>;
111
112 /** The default theme id and the published themes, plus the one named `themeId`. */
113 readonly read: (themeId?: string) => Effect.Effect<
114 {
115 readonly current: string;
116 /** Where theme files and their background images live. */
117 readonly themesDir: string;
118 readonly themes: ReadonlyArray<EnvironmentTheme>;
119 readonly theme?: EnvironmentTheme;
120 },
121 EnvironmentThemeRefusedError | ServerSettingsError
122 >;
123
124 /**
125 * Makes `themeId` the environment theme and `appearance` its mode, so connected clients
126 * switch to them. With `theme`, first publishes that file under the id, replacing one already
127 * there.
128 */
129 readonly apply: (
130 input:
131 | {
132 readonly themeId: string;
133 readonly theme?: EnvironmentThemeFile | undefined;
134 readonly appearance?: Exclude<DefaultAppearancePreference, ""> | undefined;
135 }
136 | { readonly appearance: Exclude<DefaultAppearancePreference, ""> },
137 ) => Effect.Effect<void, EnvironmentThemeRefusedError | EnvironmentThemeNotSelectedError>;
138
139 /** Subscribes before reading to retain changes during connection. */
140 readonly streamChanges: Stream.Stream<ReadonlyArray<EnvironmentTheme>>;
141 }
142 >()("t3/environmentTheme/EnvironmentThemeService") {}
143
144 /** True when anything, a dangling symlink included, is at the path. */
145 const pathIsTaken = (filePath: string): boolean => {
146 try {
147 NodeFS.lstatSync(filePath);
148 return true;
149 } catch {
150 return false;
151 }
152 };
153
154 /** Validates and reads one handle; rejects symlinked files, allows symlinked directories.
155 * Uses non-blocking opens against FIFOs; Windows lacks these flags and checks symlinks with lstat. */
156 export const readThemeFileGuarded = (filePath: string, maxBytes: number): string | null => {
157 let fd: number;
158 try {
159 if (NodeFS.constants.O_NOFOLLOW === undefined && NodeFS.lstatSync(filePath).isSymbolicLink()) {
160 return null;
161 }
162 fd = NodeFS.openSync(
163 filePath,
164 NodeFS.constants.O_RDONLY |
165 (NodeFS.constants.O_NOFOLLOW ?? 0) |
166 (NodeFS.constants.O_NONBLOCK ?? 0),
167 );
168 } catch {
169 return null;
170 }
171 try {
172 const info = NodeFS.fstatSync(fd);
173 if (!info.isFile() || info.size > maxBytes) return null;
174 const contents = Buffer.alloc(info.size);
175 let offset = 0;
176 while (offset < contents.length) {
177 const read = NodeFS.readSync(fd, contents, offset, contents.length - offset, offset);
178 if (read <= 0) break;
179 offset += read;
180 }
181 // Unlike Buffer#toString, TextDecoder drops a UTF-8 BOM, which JSON.parse rejects.
182 return new TextDecoder().decode(contents.subarray(0, offset));
183 } catch {
184 return null;
185 } finally {
186 NodeFS.closeSync(fd);
187 }
188 };
189
190 /**
191 * The background image published beside `themeId`, if any. Symlinks and oversized files are
192 * skipped. `entries` lets a directory scan skip lookups for names it did not list.
193 */
194 export function findThemeBackground(
195 themesDir: string,
196 themeId: string,
197 entries?: ReadonlySet<string>,
198 ): { readonly path: string; readonly revision: string } | null {
199 for (const extension of THEME_BACKGROUND_EXTENSIONS) {
200 const name = `${themeId}.${extension}`;
201 if (entries !== undefined && !entries.has(name)) continue;
202 // Native separators: the asset route refuses a path that differs from its canonical form.
203 const filePath = NodePath.join(themesDir, name);
204 let info: NodeFS.BigIntStats;
205 try {
206 info = NodeFS.lstatSync(filePath, { bigint: true });
207 } catch {
208 continue;
209 }
210 if (!info.isFile() || info.size > MAX_THEME_BACKGROUND_BYTES) continue;
211 return {
212 path: filePath,
213 revision: [info.ino, info.size, info.mtimeNs].map((part) => part.toString(36)).join("-"),
214 };
215 }
216 return null;
217 }
218
219 export const readPublishedThemes = Effect.fn(function* (themesDir: string) {
220 const fs = yield* FileSystem.FileSystem;
221 const entries = yield* fs
222 .readDirectory(themesDir)
223 .pipe(Effect.orElseSucceed((): Array<string> => []));
224
225 const themes: Array<EnvironmentTheme> = [];
226 const entryNames = new Set(entries);
227 let examined = 0;
228 let totalBytes = 0;
229 for (const entry of entries.toSorted()) {
230 if (!entry.endsWith(THEME_FILE_SUFFIX)) continue;
231 const id = entry.slice(0, -THEME_FILE_SUFFIX.length);
232 // Reserved ids shadow built-ins or capture clients that never chose them.
233 if (!isEnvironmentThemeId(id) || UNPUBLISHABLE_THEME_IDS.has(id)) continue;
234
235 // Cap examined files, not accepted themes, to bound work on malformed directories.
236 examined += 1;
237 if (examined > MAX_THEME_FILES) {
238 yield* Effect.logWarning("ignoring environment theme files past the limit", {
239 path: themesDir,
240 limit: MAX_THEME_FILES,
241 });
242 break;
243 }
244
245 const filePath = `${themesDir}/${entry}`;
246 const raw = readThemeFileGuarded(filePath, MAX_THEME_FILE_BYTES);
247 if (raw === null) {
248 yield* Effect.logWarning("ignoring unusable environment theme file", {
249 path: filePath,
250 limit: MAX_THEME_FILE_BYTES,
251 });
252 continue;
253 }
254 if (raw.trim().length === 0) continue;
255
256 const decoded = decodeEnvironmentThemeFileJsonExit(raw);
257 if (decoded._tag === "Failure") {
258 yield* Effect.logWarning("ignoring invalid environment theme", {
259 path: filePath,
260 detail: Cause.pretty(decoded.cause),
261 });
262 continue;
263 }
264 const file = decoded.value;
265 if (!environmentThemeFileHasColors(file)) {
266 yield* Effect.logWarning("ignoring environment theme without colors", { path: filePath });
267 continue;
268 }
269
270 totalBytes += Buffer.byteLength(raw);
271 if (totalBytes > MAX_THEME_TOTAL_BYTES) {
272 yield* Effect.logWarning("ignoring environment themes past the total size limit", {
273 path: themesDir,
274 limit: MAX_THEME_TOTAL_BYTES,
275 });
276 break;
277 }
278
279 const background = findThemeBackground(themesDir, id, entryNames);
280 themes.push({ id, ...file, ...(background ? { background: background.revision } : {}) });
281 }
282 return themes;
283 });
284
285 const make = Effect.gen(function* () {
286 const { environmentThemesDir } = yield* ServerConfig.ServerConfig;
287 const fs = yield* FileSystem.FileSystem;
288 const settings = yield* ServerSettings.ServerSettingsService;
289 // Sequence numbers let subscribers drop queued events older than their initial snapshot.
290 const changes = yield* PubSub.sliding<PublishedThemes>(1);
291 const published = yield* Ref.make<PublishedThemes>({ seq: 0, themes: [] });
292 // Serialize read/compare/publish so slow older reads cannot publish with newer sequence numbers.
293 const refreshSemaphore = yield* Semaphore.make(1);
294 const watcherScope = yield* Scope.make("sequential");
295 yield* Effect.addFinalizer(() => Scope.close(watcherScope, Exit.void));
296
297 const refresh = refreshSemaphore.withPermits(1)(
298 Effect.gen(function* () {
299 const themes = yield* readPublishedThemes(environmentThemesDir).pipe(
300 Effect.provideService(FileSystem.FileSystem, fs),
301 );
302 // Compare the whole value so new fields cannot silently miss republishes.
303 const [changed, next] = yield* Ref.modify(
304 published,
305 (previous): readonly [readonly [boolean, PublishedThemes], PublishedThemes] => {
306 if (Equal.equals(previous.themes, themes)) return [[false, previous], previous];
307 const updated: PublishedThemes = { seq: previous.seq + 1, themes };
308 return [[true, updated], updated];
309 },
310 );
311 if (changed) yield* PubSub.publish(changes, next).pipe(Effect.asVoid);
312 return next;
313 }),
314 );
315
316 yield* fs
317 .makeDirectory(environmentThemesDir, { recursive: true })
318 .pipe(Effect.ignoreCause({ log: true }));
319
320 const watchDirectory = (directory: string) =>
321 Stream.unwrap(
322 Effect.gen(function* () {
323 const ready = yield* Deferred.make<void>();
324 const markReady = () => Deferred.doneUnsafe(ready, Exit.void);
325 const events = fs.watch(directory, { onReady: markReady }).pipe(
326 Stream.as(undefined),
327 Stream.catchIf(
328 (error) => error.reason._tag === "NotFound",
329 () => Stream.empty,
330 ),
331 Stream.ignoreCause({ log: true }),
332 Stream.ensuring(Effect.sync(markReady)),
333 );
334 return Stream.merge(events, Stream.fromEffect(Deferred.await(ready)));
335 }),
336 );
337
338 const watchEvents = watchDirectoryPath(
339 environmentThemesDir,
340 watchDirectory(environmentThemesDir),
341 ).pipe(
342 // A save emits several events, and fs.watch can fire before content is flushed.
343 Stream.debounce(Duration.millis(100)),
344 );
345
346 yield* refresh;
347 yield* Stream.runForEach(watchEvents, () => refresh.pipe(Effect.ignoreCause({ log: true }))).pipe(
348 Effect.ignoreCause({ log: true }),
349 Effect.forkIn(watcherScope),
350 Effect.asVoid,
351 );
352
353 // One publish at a time: they share a staging path, and each one checks what is served after it.
354 const publishSemaphore = yield* Semaphore.make(1);
355
356 /** Callers hold `publishSemaphore`. Succeeds with the effect that undoes this publish. */
357
358 const publish = Effect.fnUntraced(function* (themeId: string, file: EnvironmentThemeFile) {
359 if (UNPUBLISHABLE_THEME_IDS.has(themeId)) {
360 return yield* new EnvironmentThemeRefusedError({ themeId, problem: INVALID_ID });
361 }
362 if (!environmentThemeFileHasColors(file)) {
363 return yield* new EnvironmentThemeRefusedError({
364 themeId,
365 problem: "has no colors. Give canvas and accent, or at least one color role.",
366 });
367 }
368 if (file.css !== undefined && themeCssLoadsRemoteFiles(file.css)) {
369 return yield* new EnvironmentThemeRefusedError({
370 themeId,
371 problem:
372 "has CSS that loads files. Remove @import, image-set(), and url() that is not data: or #id.",
373 });
374 }
375 const contents = yield* encodeEnvironmentThemeFileJson(file).pipe(
376 Effect.mapError(
377 (cause) => new EnvironmentThemeRefusedError({ themeId, problem: NOT_PUBLISHED, cause }),
378 ),
379 );
380 if (Buffer.byteLength(contents) > MAX_THEME_FILE_BYTES) {
381 return yield* new EnvironmentThemeRefusedError({
382 themeId,
383 problem: `is larger than ${MAX_THEME_FILE_BYTES} bytes.`,
384 });
385 }
386
387 const destination = `${environmentThemesDir}/${themeId}${THEME_FILE_SUFFIX}`;
388 // The watcher reads only .json names, so it never sees a half-written file.
389 const staging = `${destination}.staging-${process.pid}`;
390 // Exclusive create: a link left at the staging path is removed, never written through.
391 const replace = (next: string) =>
392 fs.remove(staging, { force: true }).pipe(
393 Effect.andThen(fs.writeFileString(staging, next, { flag: "wx" })),
394 Effect.andThen(fs.rename(staging, destination)),
395 Effect.tapError(() => fs.remove(staging, { force: true }).pipe(Effect.ignore)),
396 );
397
398 // The guarded reader does not block on a FIFO and does not follow a symlink.
399 const previous = Option.fromNullOr(readThemeFileGuarded(destination, MAX_THEME_FILE_BYTES));
400 // A file it cannot read back, such as one over the size limit, could not be restored.
401 if (Option.isNone(previous) && pathIsTaken(destination)) {
402 return yield* new EnvironmentThemeRefusedError({
403 themeId,
404 problem: "would replace a file that could not be backed up. Use another theme id.",
405 });
406 }
407 const servedBefore = (yield* refresh).themes.map((theme) => theme.id);
408 // Puts back what was there, so a failed apply does not take a working theme away.
409 const revert = Option.match(previous, {
410 onNone: () => fs.remove(destination, { force: true }),
411 onSome: replace,
412 }).pipe(Effect.ignore, Effect.andThen(refresh), Effect.asVoid);
413
414 yield* fs.makeDirectory(environmentThemesDir, { recursive: true }).pipe(
415 Effect.andThen(replace(contents)),
416 Effect.mapError(
417 (cause) => new EnvironmentThemeRefusedError({ themeId, problem: NOT_PUBLISHED, cause }),
418 ),
419 );
420 // The reader stops at its count and size limits, so this file can go unserved, or it can
421 // push another theme out. Both count as a failed publish.
422 const served = new Set((yield* refresh).themes.map((theme) => theme.id));
423 if (served.has(themeId) && servedBefore.every((id) => served.has(id))) return revert;
424 yield* revert;
425 return yield* new EnvironmentThemeRefusedError({ themeId, problem: NOT_PUBLISHED });
426 });
427
428 const apply: EnvironmentThemeService["Service"]["apply"] = Effect.fn(
429 "EnvironmentThemeService.apply",
430 )(function* (input) {
431 const themeId = "themeId" in input ? input.themeId : undefined;
432 const theme = "theme" in input ? input.theme : undefined;
433 const { appearance } = input;
434 if (themeId !== undefined && !isEnvironmentThemeId(themeId)) {
435 return yield* new EnvironmentThemeRefusedError({ themeId, problem: INVALID_ID });
436 }
437 // Timestamps make clients apply a set again when its value did not change. Theme and
438 // appearance have one each, so setting one does not undo a later local choice of the other.
439 // The stock theme is an empty default with a set time, which clients adopt as stock.
440 const defaultTheme = themeId === MOBILE_DEFAULT_THEME_ID ? "" : themeId;
441 const select = Effect.gen(function* () {
442 const setAt = DateTime.formatIso(yield* DateTime.now);
443 yield* settings
444 .updateSettings({
445 ...(defaultTheme === undefined ? {} : { defaultTheme, defaultThemeSetAt: setAt }),
446 ...(appearance === undefined
447 ? {}
448 : { defaultAppearance: appearance, defaultAppearanceSetAt: setAt }),
449 })
450 .pipe(Effect.mapError((cause) => new EnvironmentThemeNotSelectedError({ themeId, cause })));
451 });
452 // One at a time, so a selection never sees a file that a failed publish then takes back.
453 // If the theme cannot be selected, the file it replaced comes back.
454 yield* publishSemaphore.withPermits(1)(
455 Effect.gen(function* () {
456 if (themeId === undefined) return yield* select;
457 if (theme === undefined) {
458 const known = [...MOBILE_THEME_IDS, ...(yield* refresh).themes.map(({ id }) => id)];
459 if (!known.includes(themeId)) {
460 return yield* new EnvironmentThemeRefusedError({
461 themeId,
462 problem: "is not a built-in or published theme.",
463 known,
464 });
465 }
466 return yield* select;
467 }
468 const revert = yield* publish(themeId, theme);
469 yield* select.pipe(Effect.tapError(() => revert));
470 }),
471 );
472 });
473
474 const read: EnvironmentThemeService["Service"]["read"] = Effect.fn(
475 "EnvironmentThemeService.read",
476 )(function* (themeId) {
477 const { themes } = yield* refresh;
478 const { defaultTheme } = yield* settings.getSettings;
479 const themesDir = environmentThemesDir;
480 if (themeId === undefined) return { current: defaultTheme, themesDir, themes };
481 const theme = themes.find((candidate) => candidate.id === themeId);
482 if (theme === undefined) {
483 return yield* new EnvironmentThemeRefusedError({
484 themeId,
485 problem: "is not a published theme.",
486 known: themes.map(({ id }) => id),
487 });
488 }
489 return { current: defaultTheme, themesDir, themes, theme };
490 });
491
492 return {
493 current: Effect.map(refresh, (state) => state.themes),
494 read,
495 apply,
496 get streamChanges() {
497 return Stream.unwrap(
498 Effect.gen(function* () {
499 const subscription = yield* PubSub.subscribe(changes);
500 const snapshot = yield* refresh;
501 return Stream.concat(
502 Stream.make(snapshot.themes),
503 Stream.fromSubscription(subscription).pipe(
504 Stream.filter((update) => update.seq > snapshot.seq),
505 Stream.map((update) => update.themes),
506 ),
507 );
508 }),
509 );
510 },
511 } satisfies EnvironmentThemeService["Service"];
512 });
513
514 export const layer = Layer.effect(EnvironmentThemeService, make);