@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, 06:00 UTC

main
ts 386 lines 13.4 KB
Raw
1 import { writeSync } from "node:fs";
2 import * as Cause from "effect/Cause";
3 import * as Context from "effect/Context";
4 import * as Effect from "effect/Effect";
5 import * as Layer from "effect/Layer";
6 import * as Logger from "effect/Logger";
7 import * as LogLevel from "effect/LogLevel";
8 import * as Option from "effect/Option";
9 import { CurrentLogAnnotations, MinimumLogLevel } from "effect/References";
10 import * as Schema from "effect/Schema";
11 import { Event, isKnownEventType } from "../Events.ts";
12 import { LogAnnotation } from "./LogAnnotation.ts";
13 import { processTrace, type TraceParent, withTraceParent } from "./TraceParent.ts";
14
15 /** Record levels, spelled like `--log-level`. */
16 export type Level = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
17
18 /**
19 * What a record is, and the first thing a sink filters on:
20 * - `log`: a line alchemy logged;
21 * - `event`: a typed event (see `emit`);
22 * - `output`: a line a child process wrote (dev servers, workerd, the user's code);
23 * - `run`: the first line of a run log, describing the run.
24 */
25 export type Kind = "log" | "event" | "output" | "run";
26
27 /**
28 * The envelope every record shares. Every key is always present (`null`
29 * when it doesn't apply), so a reader filters on fields without guessing
30 * which ones a record carries; `data` has the shape its `kind` names.
31 */
32 interface Envelope<K extends Kind, Data> {
33 /** Unix time in milliseconds. */
34 readonly time: number;
35 readonly level: Level;
36 readonly kind: K;
37 /** The alchemy process that produced it: `cli`, `exec` or `sidecar`. */
38 readonly process: string;
39 /** Which run log it belongs to: account-level work is `global`. */
40 readonly scope: "project" | "global";
41 /**
42 * The trace and span it was logged in, for joining with telemetry; outside
43 * any span, the process's trace (see `processTrace`).
44 */
45 readonly trace: TraceParent;
46 /** Annotations on the record, beyond the envelope's own fields. */
47 readonly attributes: Readonly<Record<string, unknown>>;
48 readonly data: Data;
49 }
50
51 /**
52 * One record as data. Every alchemy process logs these; only the process
53 * that owns the terminal renders them (pretty or JSON), so structure
54 * survives process boundaries instead of being baked into rendered text.
55 */
56 export type LogRecord =
57 | Envelope<"log", { readonly message: string; readonly cause: string | null }>
58 | Envelope<"event", Event>
59 | Envelope<
60 "output",
61 {
62 readonly stream: "stdout" | "stderr";
63 /** The line as the child wrote it, ANSI styling included. */
64 readonly text: string;
65 }
66 >
67 | Envelope<
68 "run",
69 {
70 readonly version: string;
71 readonly pid: number;
72 readonly cwd: string;
73 readonly argv: ReadonlyArray<string>;
74 }
75 >;
76
77 const reserved: ReadonlySet<string> = new Set(
78 Object.values(LogAnnotation).filter((key) => key !== LogAnnotation.fqn),
79 );
80
81 /** The name this process stamps on its records: `cli`, `exec` or `sidecar`. */
82 export const LogProcess = Context.Reference<string>("alchemy/LogProcess", {
83 defaultValue: () => "cli",
84 });
85
86 /** The Effect log level of each record {@link Level}. */
87 export const severities: Record<Level, LogLevel.Severity> = {
88 trace: "Trace",
89 debug: "Debug",
90 info: "Info",
91 warn: "Warn",
92 error: "Error",
93 fatal: "Fatal",
94 };
95
96 const levelOf = (logLevel: LogLevel.LogLevel): Level =>
97 logLevel === "All" || logLevel === "None" ? "info" : (logLevel.toLowerCase() as Level);
98
99 /**
100 * `JSON.stringify` that never throws: cycles become `"[Circular]"` and
101 * bigints their decimal string. Logging must not fail the work it reports.
102 */
103 export const safeStringify = (value: unknown): string => {
104 const seen = new WeakSet<object>();
105 try {
106 return (
107 JSON.stringify(value, (_key, v: unknown) => {
108 if (typeof v === "bigint") return v.toString();
109 if (typeof v === "object" && v !== null) {
110 if (seen.has(v)) return "[Circular]";
111 seen.add(v);
112 }
113 return v;
114 }) ?? String(value)
115 );
116 } catch {
117 return String(value);
118 }
119 };
120
121 const messageText = (message: unknown): string => {
122 const parts = Array.isArray(message) ? message : [message];
123 return parts
124 .map((part) =>
125 typeof part === "string"
126 ? part
127 : part instanceof Error
128 ? (part.stack ?? part.message)
129 : safeStringify(part),
130 )
131 .join(" ");
132 };
133
134 /** A record's {@link Kind}, read from its annotations alone. */
135 export const kindOf = (options: Logger.Options<unknown>): Exclude<Kind, "run"> => {
136 const annotations = options.fiber.getRef(CurrentLogAnnotations);
137 return annotations[LogAnnotation.event] === true
138 ? "event"
139 : annotations[LogAnnotation.stream] !== undefined
140 ? "output"
141 : "log";
142 };
143
144 const isTrace = (value: unknown): value is TraceParent =>
145 typeof value === "object" &&
146 value !== null &&
147 typeof (value as { traceId?: unknown }).traceId === "string" &&
148 typeof (value as { spanId?: unknown }).spanId === "string";
149
150 /** The record a logger call describes. */
151 export const recordOf = (options: Logger.Options<unknown>): LogRecord => {
152 const all = options.fiber.getRef(CurrentLogAnnotations);
153 const string = (key: string) => (typeof all[key] === "string" ? all[key] : undefined);
154 const time = all[LogAnnotation.time];
155 const replayedTrace = all[LogAnnotation.trace];
156 const span = options.fiber.cache.span;
157 const head = {
158 time: typeof time === "number" ? time : options.date.getTime(),
159 level: levelOf(options.logLevel),
160 };
161 const envelope = {
162 process: string(LogAnnotation.process) ?? options.fiber.getRef(LogProcess),
163 scope: all[LogAnnotation.scope] === "global" ? ("global" as const) : ("project" as const),
164 trace: isTrace(replayedTrace)
165 ? replayedTrace
166 : span === undefined
167 ? processTrace
168 : { traceId: span.traceId, spanId: span.spanId },
169 attributes: Object.fromEntries(Object.entries(all).filter(([key]) => !reserved.has(key))),
170 };
171 const first = Array.isArray(options.message) ? options.message[0] : options.message;
172 switch (kindOf(options)) {
173 case "event":
174 // SAFETY: only `emit` (or a replayed event) sets the event annotation,
175 // and it logs one Event.
176 return { ...head, kind: "event", ...envelope, data: first as Event };
177 case "output":
178 return {
179 ...head,
180 kind: "output",
181 ...envelope,
182 data: {
183 stream: all[LogAnnotation.stream] === "stderr" ? "stderr" : "stdout",
184 text: messageText(options.message),
185 },
186 };
187 case "log":
188 return {
189 ...head,
190 kind: "log",
191 ...envelope,
192 data: {
193 message: messageText(options.message),
194 cause:
195 string(LogAnnotation.cause) ??
196 (options.cause.reasons.length > 0 ? Cause.pretty(options.cause) : null),
197 },
198 };
199 }
200 };
201
202 /**
203 * Mark the logs of `effect` as account-level: the CLI files them in the
204 * global run log (`~/.alchemy/logs`) instead of the project's. For work that
205 * isn't about one project — the state store, auth and credentials, profiles.
206 */
207 export const globalLogs = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
208 Effect.annotateLogs(effect, LogAnnotation.scope, "global");
209
210 /**
211 * Set to `json` on alchemy child processes (sidecars) so they log
212 * {@link LogRecord} lines instead of rendering, and on the CLI to print
213 * records as JSON.
214 */
215 export const LOG_FORMAT_ENV = "ALCHEMY_LOG_FORMAT";
216
217 /** The console's `--log-level`, for child processes that render the run's logs. */
218 export const LOG_LEVEL_ENV = "ALCHEMY_LOG_LEVEL";
219
220 /** Formats each record as one line of JSON (for `Logger.toFile`). */
221 export const formatJsonRecord = Logger.make<unknown, string>((options) =>
222 safeStringify(recordOf(options)),
223 );
224
225 /** A logger that writes each record as one line of JSON. */
226 export const jsonLogger = (write: (line: string) => void) => Logger.map(formatJsonRecord, write);
227
228 /**
229 * The only logger of an alchemy child process: every record as a JSON line
230 * on stdout, down to Debug, for the parent to filter and render.
231 */
232 export const childJsonLogLayer = Layer.mergeAll(
233 Logger.layer([jsonLogger((line) => process.stdout.write(`${line}\n`))]),
234 Layer.succeed(MinimumLogLevel, "Debug"),
235 );
236
237 /**
238 * Set on a child process that renders its own terminal output (the
239 * `alchemy dev` exec child) to the file descriptor its parent reads log
240 * records from. The parent writes the run log; the child keeps none.
241 */
242 export const LOG_FD_ENV = "ALCHEMY_LOG_FD";
243
244 /**
245 * Forward every record, down to Debug, to the parent as JSON lines on the
246 * descriptor in {@link LOG_FD_ENV}, alongside the installed loggers. Empty
247 * when the variable is unset.
248 */
249 export const parentLogLayer = (): Layer.Layer<never> => {
250 const fd = Number(process.env[LOG_FD_ENV]);
251 if (!Number.isInteger(fd) || fd < 3) return Layer.empty;
252 const write = (line: string) => {
253 try {
254 writeSync(fd, `${line}\n`);
255 } catch {
256 // The parent is gone or stopped reading: logging must not fail the work.
257 }
258 };
259 return Logger.layer([jsonLogger(write)], {
260 mergeWithExisting: true,
261 });
262 };
263
264 /** An event of a `type` this version doesn't know: decoded, never validated. */
265 const UnknownEvent = Schema.StructWithRest(
266 Schema.Struct({
267 type: Schema.String.check(
268 Schema.makeFilter(
269 (type: string) => !isKnownEventType(type) || "A known event type must decode in full.",
270 ),
271 ),
272 }),
273 [Schema.Record(Schema.String, Schema.Unknown)],
274 );
275
276 const envelopeFields = {
277 time: Schema.Number,
278 level: Schema.Literals(["trace", "debug", "info", "warn", "error", "fatal"]),
279 process: Schema.String,
280 scope: Schema.Literals(["project", "global"]),
281 trace: Schema.Struct({ traceId: Schema.String, spanId: Schema.String }),
282 attributes: Schema.Record(Schema.String, Schema.Unknown),
283 };
284
285 /**
286 * The wire form of a {@link LogRecord}: what a child process sends and the
287 * run log stores. An event is decoded with the {@link Event} union; one whose
288 * `type` this version doesn't know is kept as-is rather than rejected, so a
289 * newer process's records still pass through.
290 */
291 export const LogRecordSchema = Schema.Union([
292 Schema.Struct({
293 ...envelopeFields,
294 kind: Schema.Literal("log"),
295 data: Schema.Struct({ message: Schema.String, cause: Schema.NullOr(Schema.String) }),
296 }),
297 Schema.Struct({
298 ...envelopeFields,
299 kind: Schema.Literal("event"),
300 data: Schema.Union([Event, UnknownEvent]),
301 }),
302 Schema.Struct({
303 ...envelopeFields,
304 kind: Schema.Literal("output"),
305 data: Schema.Struct({ stream: Schema.Literals(["stdout", "stderr"]), text: Schema.String }),
306 }),
307 Schema.Struct({
308 ...envelopeFields,
309 kind: Schema.Literal("run"),
310 data: Schema.Struct({
311 version: Schema.String,
312 pid: Schema.Number,
313 cwd: Schema.String,
314 argv: Schema.Array(Schema.String),
315 }),
316 }),
317 ]);
318
319 const decodeRecordLine = Schema.decodeUnknownOption(Schema.fromJsonString(LogRecordSchema));
320
321 /** Decode one JSON log line, or `undefined` when it isn't a log record. */
322 export const parseRecord = (line: string): typeof LogRecordSchema.Type | undefined =>
323 Option.getOrUndefined(decodeRecordLine(line));
324
325 /**
326 * Log a record from another process through this process's loggers,
327 * keeping its envelope: the sinks here see the record the child produced.
328 */
329 export const replayRecord = (record: typeof LogRecordSchema.Type): Effect.Effect<void> =>
330 record.kind === "run"
331 ? Effect.void
332 : Effect.logWithLevel(severities[record.level])(
333 record.kind === "log"
334 ? record.data.message
335 : record.kind === "output"
336 ? record.data.text
337 : record.data,
338 ).pipe(
339 Effect.annotateLogs({
340 ...record.attributes,
341 [LogAnnotation.time]: record.time,
342 [LogAnnotation.process]: record.process,
343 [LogAnnotation.trace]: record.trace,
344 [LogAnnotation.scope]: record.scope,
345 ...(record.kind === "event" ? { [LogAnnotation.event]: true } : {}),
346 ...(record.kind === "output" ? { [LogAnnotation.stream]: record.data.stream } : {}),
347 ...(record.kind === "log" && record.data.cause !== null
348 ? { [LogAnnotation.cause]: record.data.cause }
349 : {}),
350 }),
351 // A record the child already let through keeps reaching the sinks,
352 // whatever this process's minimum level.
353 Effect.provideService(MinimumLogLevel, "Trace"),
354 // Loggers that read the fiber's span (OTLP) see the child's too.
355 withTraceParent(record.trace),
356 );
357
358 /**
359 * Log one line a child process wrote. A JSON {@link LogRecord} (an alchemy
360 * child) is replayed as-is; anything else becomes an Info `output` record,
361 * from `source.process` or, when that's unset, this process.
362 */
363 export const logChildLine = (
364 line: string,
365 source: {
366 readonly stream: "stdout" | "stderr";
367 readonly resource?: string;
368 readonly process?: string;
369 },
370 ): Effect.Effect<void> => {
371 const record = parseRecord(line);
372 if (record !== undefined) {
373 return replayRecord(
374 source.resource !== undefined && record.attributes[LogAnnotation.fqn] === undefined
375 ? { ...record, attributes: { ...record.attributes, [LogAnnotation.fqn]: source.resource } }
376 : record,
377 );
378 }
379 return Effect.logInfo(line).pipe(
380 Effect.annotateLogs({
381 [LogAnnotation.stream]: source.stream,
382 ...(source.resource === undefined ? {} : { [LogAnnotation.fqn]: source.resource }),
383 ...(source.process === undefined ? {} : { [LogAnnotation.process]: source.process }),
384 }),
385 );
386 };