@opencode/util 0.0.0-reserved → 2.0.0

package/dist/observability/logging.js

@@ -0,0 +1,151 @@
+import { Effect, FileSystem, Formatter, Logger, Option, Schedule, Stream } from "effect";
+import path from "path";
+import { Global } from "../global.js";
+import { runID } from "./shared.js";
+// One log file is shared by every opencode process on the machine and only ever appended to, so it
+// is bounded by compacting in place instead of rotating: once it passes LOG_MAX_BYTES the head is
+// dropped so roughly LOG_KEEP_BYTES remain, rounded forward to the next line boundary.
+export const LOG_MAX_BYTES = 50 * 1024 * 1024;
+export const LOG_KEEP_BYTES = 25 * 1024 * 1024;
+export const LOG_TRIM_INTERVAL = "1 hour";
+// A trim of a 1 GB log takes well under a second, so a lock older than this belongs to a dead process.
+export const LOG_TRIM_LOCK_STALE_MS = 5 * 60 * 1000;
+const LOG_TRIM_CHUNK = 64 * 1024;
+function formatter(id = runID()) {
+    return Logger.map(Logger.formatStructured, (output) => {
+        const messages = Array.isArray(output.message) ? output.message : [output.message];
+        return [
+            ["timestamp", output.timestamp],
+            ["level", output.level],
+            ["run", id],
+            ...messages.flatMap((value) => (plain(value) ? flatten(value) : [["message", value]])),
+            ...(output.cause === undefined ? [] : [["cause", output.cause]]),
+            ...flatten(output.spans),
+            ...flatten(output.annotations),
+        ]
+            .map(([key, value]) => `${key}=${format(value)}`)
+            .join(" ");
+    });
+}
+function flatten(input, prefix = "", seen = new WeakSet()) {
+    if (seen.has(input))
+        return [[prefix, "[Circular]"]];
+    seen.add(input);
+    const entries = Object.entries(input);
+    if (entries.length === 0 && prefix)
+        return [[prefix, input]];
+    return entries.flatMap(([key, value]) => {
+        const path = prefix ? `${prefix}.${key}` : key;
+        return plain(value) ? flatten(value, path, seen) : [[path, value]];
+    });
+}
+function plain(input) {
+    if (input === null || typeof input !== "object" || Array.isArray(input))
+        return false;
+    const prototype = Object.getPrototypeOf(input);
+    return prototype === Object.prototype || prototype === null;
+}
+function format(input) {
+    const value = typeof input === "string" ? input : Formatter.format(input);
+    return /^[^\s="\\]+$/.test(value) ? value : JSON.stringify(value);
+}
+export function file(local = true, channel = "local") {
+    if (!local)
+        return path.join(Global.Path.log, "opencode.log");
+    return path.join(Global.Path.log, `opencode-${channel.replace(/[^a-zA-Z0-9._-]/g, "-")}.log`);
+}
+export function fileLogger(target = file(), id = runID()) {
+    // Do not set batchWindow to 0; it causes high idle CPU usage.
+    return Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        yield* fs.makeDirectory(path.dirname(target), { recursive: true });
+        const logger = yield* Logger.toFile(formatter(id), target, { flag: "a" });
+        yield* trim(target).pipe(Effect.ignore, Effect.repeat(Schedule.spaced(LOG_TRIM_INTERVAL)), Effect.forkScoped({ startImmediately: true }));
+        return logger;
+    });
+}
+// Compacts in place rather than writing a temp file and renaming over the log. Other processes hold
+// the same file open with O_APPEND, so they keep appending to the compacted file, whereas a rename
+// would strand them on the unlinked inode and lose their output.
+//
+// Appenders are not coordinated with the final truncate, so a batch flushed by another process
+// between the last read and the truncate is lost. That window is a few milliseconds once per trim,
+// which is an accepted trade for not wrapping every log write in a cross-process lock.
+export const trim = Effect.fn("Logging.trim")(function* (target, options = {}) {
+    const max = options.max ?? LOG_MAX_BYTES;
+    const keep = options.keep ?? LOG_KEEP_BYTES;
+    const fs = yield* FileSystem.FileSystem;
+    // Every opencode process on the machine runs this against the same file. Two trimmers racing
+    // would have one compute its cut from a size the other already shrank, so only one may proceed
+    // and the rest skip until the next interval. mkdir is the atomic primitive on every platform.
+    // acquireRelease keeps the mkdir uninterruptible, so a scope closing mid-call cannot leave a lock
+    // on disk with no finalizer registered to remove it.
+    const lock = `${target}.trim`;
+    const acquired = yield* Effect.acquireRelease(fs.makeDirectory(lock).pipe(Effect.as(true), Effect.catchIf((error) => error.reason._tag === "AlreadyExists", () => breakStaleLock(fs, lock))), (acquired) => (acquired ? fs.remove(lock, { recursive: true }).pipe(Effect.ignore) : Effect.void));
+    if (!acquired)
+        return;
+    const size = Number((yield* fs.stat(target)).size);
+    if (size <= max)
+        return;
+    const handle = yield* fs.open(target, { flag: "r+" });
+    const start = yield* lineStart(handle, size - keep);
+    yield* handle.seek(0, "start");
+    // Reads run to the current EOF so lines appended since the stat survive; the write cursor always
+    // trails the read cursor so the forward copy never overwrites unread bytes.
+    const written = yield* fs.stream(target, { offset: start, chunkSize: LOG_TRIM_CHUNK }).pipe(Stream.runFoldEffect(() => 0, (total, chunk) => handle.writeAll(chunk).pipe(Effect.as(total + chunk.length))));
+    yield* handle.truncate(written);
+}, Effect.scoped);
+// Removes a lock left by a process that died mid-trim. Still yields this round: the next interval
+// acquires cleanly, and a process that is legitimately trimming right now keeps its lock.
+//
+// Two processes that both observe the same stale lock can race here: one removes it, a third
+// acquires fresh, and the other removes that fresh lock. That needs a crash inside a sub-second trim
+// followed by three processes ticking within the same few milliseconds, and the consequence is the
+// same bounded tail loss documented on `trim`. Not worth a breaker protocol; see EffectFlock if it is.
+function breakStaleLock(fs, lock) {
+    return Effect.gen(function* () {
+        const info = yield* fs.stat(lock).pipe(Effect.option);
+        const modified = Option.flatMap(info, (value) => value.mtime);
+        if (Option.isNone(modified))
+            return false;
+        if (Date.now() - modified.value.getTime() < LOG_TRIM_LOCK_STALE_MS)
+            return false;
+        yield* fs.remove(lock, { recursive: true }).pipe(Effect.ignore);
+        return false;
+    });
+}
+// First byte after the first newline at or beyond `from`, or EOF when the tail has no newline.
+function lineStart(handle, from) {
+    return Effect.gen(function* () {
+        let cursor = from;
+        while (true) {
+            yield* handle.seek(cursor, "start");
+            const chunk = yield* handle.readAlloc(LOG_TRIM_CHUNK);
+            if (Option.isNone(chunk))
+                return cursor;
+            const newline = chunk.value.indexOf(10);
+            if (newline !== -1)
+                return cursor + newline + 1;
+            cursor += chunk.value.length;
+        }
+    });
+}
+const stderrLogger = Logger.make((options) => {
+    if (process.env.OPENCODE_PRINT_LOGS !== "1")
+        return;
+    process.stderr.write(formatter().log(options) + "\n");
+});
+export function minimumLogLevel() {
+    const value = process.env.OPENCODE_LOG_LEVEL?.toUpperCase();
+    const levels = {
+        DEBUG: "Debug",
+        INFO: "Info",
+        WARN: "Warn",
+        ERROR: "Error",
+    };
+    return value && value in levels ? levels[value] : levels.INFO;
+}
+export function loggers(local = true, channel = "local") {
+    return [fileLogger(file(local, channel)), stderrLogger];
+}
+export * as Logging from "./logging.js";

package/dist/observability/otlp.d.ts

@@ -0,0 +1,18 @@
+import { Effect, Layer, Scope } from "effect";
+export interface Options {
+    readonly endpoint?: string;
+    readonly headers?: string;
+}
+export interface App {
+    readonly client: string;
+    readonly version: string;
+    readonly channel: string;
+}
+export declare function resource(app?: App): {
+    serviceName: string;
+    serviceVersion: string;
+    attributes: Record<string, string>;
+};
+export declare function loggers(options: Options | undefined, app: App): Effect.Effect<import("effect/Logger").Logger<unknown, void>, never, Scope.Scope | import("effect/unstable/http/HttpClient").HttpClient | import("effect/unstable/observability/OtlpExporter").Flusher | import("effect/unstable/observability/OtlpSerialization").OtlpSerialization>[];
+export declare const tracingLayer: (options: Options | undefined, app: App) => Effect.Effect<Layer.Layer<never, never, never>, never, never>;
+export * as Otlp from "./otlp.js";

package/dist/observability/otlp.js

@@ -0,0 +1,76 @@
+import { Effect, Layer, Scope } from "effect";
+import { OtlpLogger } from "effect/unstable/observability";
+import { runID } from "./shared.js";
+function parseHeaders(value) {
+    return value
+        ? value.split(",").reduce((acc, entry) => {
+            const [key, ...value] = entry.split("=");
+            acc[key] = value.join("=");
+            return acc;
+        }, {})
+        : undefined;
+}
+function resourceAttributes() {
+    const value = process.env.OTEL_RESOURCE_ATTRIBUTES;
+    if (!value)
+        return {};
+    try {
+        return Object.fromEntries(value.split(",").map((entry) => {
+            const index = entry.indexOf("=");
+            if (index < 1)
+                throw new Error("Invalid OTEL_RESOURCE_ATTRIBUTES entry");
+            return [decodeURIComponent(entry.slice(0, index)), decodeURIComponent(entry.slice(index + 1))];
+        }));
+    }
+    catch {
+        return {};
+    }
+}
+export function resource(app = { client: "opencode", version: "unknown", channel: "local" }) {
+    return {
+        serviceName: "opencode",
+        serviceVersion: app.version,
+        attributes: {
+            ...resourceAttributes(),
+            "deployment.environment.name": app.channel,
+            "opencode.client": app.client,
+            "opencode.run": runID(),
+            "service.instance.id": runID(),
+        },
+    };
+}
+export function loggers(options, app) {
+    if (!options?.endpoint)
+        return [];
+    return [
+        OtlpLogger.make({
+            url: `${options.endpoint}/v1/logs`,
+            resource: resource(app),
+            headers: parseHeaders(options.headers),
+        }),
+    ];
+}
+export const tracingLayer = Effect.fnUntraced(function* (options, app) {
+    if (!options?.endpoint)
+        return Layer.empty;
+    const [{ layer }, { OTLPTraceExporter }, { BatchSpanProcessor }, { AsyncLocalStorageContextManager }, { context }] = yield* Effect.all([
+        Effect.promise(() => import("@effect/opentelemetry/NodeSdk")),
+        Effect.promise(() => import("@opentelemetry/exporter-trace-otlp-http")),
+        Effect.promise(() => import("@opentelemetry/sdk-trace-base")),
+        Effect.promise(() => import("@opentelemetry/context-async-hooks")),
+        Effect.promise(() => import("@opentelemetry/api")),
+    ], { concurrency: "unbounded" });
+    // The Effect Node SDK does not register a global context manager, but the AI SDK uses it to parent spans.
+    const manager = new AsyncLocalStorageContextManager();
+    manager.enable();
+    context.setGlobalContextManager(manager);
+    const tracing = layer(() => ({
+        resource: resource(app),
+        spanProcessor: new BatchSpanProcessor(new OTLPTraceExporter({
+            url: `${options.endpoint}/v1/traces`,
+            headers: parseHeaders(options.headers),
+        })),
+    }));
+    return Layer.effectContext(Effect.acquireRelease(Scope.make(), (scope, exit) => Scope.close(scope, exit).pipe(Effect.ignoreCause)).pipe(Effect.flatMap((scope) => Layer.buildWithScope(tracing, scope))));
+});
+export * as Otlp from "./otlp.js";

package/dist/observability/shared.d.ts

@@ -0,0 +1 @@
+export declare function runID(): string;

package/dist/observability/shared.js

@@ -0,0 +1,7 @@
+// Lazy: workerd forbids generating random values in global scope, so the id
+// materializes on first call (inside a handler) and stays stable afterwards.
+let generated;
+export function runID() {
+    generated ??= crypto.randomUUID().slice(0, 8);
+    return generated;
+}

package/dist/observability.d.ts

@@ -0,0 +1,13 @@
+export * as Observability from "./observability.js";
+import { LayerNode } from "./effect/layer-node.js";
+import { Layer, Schema } from "effect";
+export declare const Options: Schema.Struct<{
+    readonly endpoint: Schema.optional<Schema.String>;
+    readonly headers: Schema.optional<Schema.String>;
+    readonly client: Schema.optional<Schema.String>;
+    readonly version: Schema.optional<Schema.String>;
+    readonly channel: Schema.optional<Schema.String>;
+}>;
+export type Options = typeof Options.Type;
+export declare function layer(options?: Options): Layer.Layer<never, never, never>;
+export declare const node: LayerNode.Provider<never, never, undefined>;

package/dist/observability.js

@@ -0,0 +1,37 @@
+export * as Observability from "./observability.js";
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem";
+import { LayerNode } from "./effect/layer-node.js";
+import { Effect, Layer, Logger, References, Schema } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+import { OtlpExporter, OtlpSerialization } from "effect/unstable/observability";
+import { Logging } from "./observability/logging.js";
+import { Otlp } from "./observability/otlp.js";
+export const Options = Schema.Struct({
+    endpoint: Schema.optional(Schema.String),
+    headers: Schema.optional(Schema.String),
+    client: Schema.optional(Schema.String),
+    version: Schema.optional(Schema.String),
+    channel: Schema.optional(Schema.String),
+});
+export function layer(options = {
+    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+    headers: process.env.OTEL_EXPORTER_OTLP_HEADERS,
+}) {
+    const app = {
+        client: options.client ?? "opencode",
+        version: options.version ?? "unknown",
+        channel: options.channel ?? "local",
+    };
+    const local = Logger.layer(Logging.loggers(app.channel === "local", app.channel), { mergeWithExisting: false }).pipe(Layer.provide(NodeFileSystem.layer), Layer.orDie, Layer.merge(Layer.succeed(References.MinimumLogLevel, Logging.minimumLogLevel())));
+    return Layer.unwrap(Effect.gen(function* () {
+        const logs = Logger.layer([...Logging.loggers(app.channel === "local", app.channel), ...Otlp.loggers(options, app)], { mergeWithExisting: false }).pipe(Layer.provide(NodeFileSystem.layer), Layer.provide(OtlpSerialization.layerJson), Layer.provide(FetchHttpClient.layer), Layer.provide(OtlpExporter.layerFlusher), Layer.orDie, Layer.merge(Layer.succeed(References.MinimumLogLevel, Logging.minimumLogLevel())));
+        return Layer.merge(logs, yield* Otlp.tracingLayer(options, app));
+    })).pipe(Layer.catchCause(() => local));
+}
+// Layer.suspend: constructing the loggers eagerly at module scope performs
+// I/O (file logger, run id) that workerd forbids in global scope.
+export const node = LayerNode.make({
+    name: "observability",
+    layer: Layer.suspend(() => layer()),
+    deps: [],
+});

package/dist/patch.d.ts

@@ -0,0 +1,43 @@
+export * as Patch from "./patch.js";
+import { Result, Schema } from "effect";
+declare const BoundaryError_base: Schema.Class<BoundaryError, Schema.TaggedStruct<"Patch.BoundaryError", {
+    readonly boundary: Schema.Literals<readonly ["first", "last"]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class BoundaryError extends BoundaryError_base {
+    get message(): string;
+}
+declare const InvalidHunkError_base: Schema.Class<InvalidHunkError, Schema.TaggedStruct<"Patch.InvalidHunkError", {
+    readonly line: Schema.String;
+    readonly lineNumber: Schema.Number;
+    readonly reason: Schema.optional<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidHunkError extends InvalidHunkError_base {
+    get message(): string;
+}
+export type ParseError = BoundaryError | InvalidHunkError;
+export type Hunk = {
+    readonly type: "add";
+    readonly path: string;
+    readonly contents: string;
+} | {
+    readonly type: "delete";
+    readonly path: string;
+} | {
+    readonly type: "update";
+    readonly path: string;
+    readonly movePath?: string;
+    readonly chunks: ReadonlyArray<UpdateFileChunk>;
+};
+export interface UpdateFileChunk {
+    readonly oldLines: ReadonlyArray<string>;
+    readonly newLines: ReadonlyArray<string>;
+    readonly changeContext?: string;
+    readonly endOfFile?: boolean;
+}
+export interface FileUpdate {
+    readonly content: string;
+    readonly bom: boolean;
+}
+export declare function parse(patchText: string): Result.Result<ReadonlyArray<Hunk>, ParseError>;
+export declare function derive(path: string, chunks: ReadonlyArray<UpdateFileChunk>, original: string): FileUpdate;
+export declare function joinBom(text: string, bom: boolean): string;