The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }; |