@opencode/util 0.0.0-reserved → 2.0.1

package/dist/glob.js

@@ -0,0 +1,26 @@
+import { glob, globSync } from "glob";
+import { minimatch } from "minimatch";
+export var Glob;
+(function (Glob) {
+    function toGlobOptions(options) {
+        return {
+            cwd: options.cwd,
+            absolute: options.absolute,
+            dot: options.dot,
+            follow: options.symlink ?? false,
+            nodir: options.include !== "all",
+        };
+    }
+    async function scan(pattern, options = {}) {
+        return glob(pattern, toGlobOptions(options));
+    }
+    Glob.scan = scan;
+    function scanSync(pattern, options = {}) {
+        return globSync(pattern, toGlobOptions(options));
+    }
+    Glob.scanSync = scanSync;
+    function match(pattern, filepath) {
+        return minimatch(filepath, pattern, { dot: true });
+    }
+    Glob.match = match;
+})(Glob || (Glob = {}));

package/dist/global-roots.d.ts

@@ -0,0 +1,8 @@
+/** The XDG base directories that root opencode's global paths. */
+export declare function roots(app: string): {
+    data: string;
+    cache: string;
+    config: string;
+    state: string;
+    tmp: string;
+};

package/dist/global-roots.js

@@ -0,0 +1,17 @@
+import os from "os";
+import path from "path";
+const home = os.homedir();
+const data = process.env.XDG_DATA_HOME || (home ? path.join(home, ".local", "share") : undefined);
+const cache = process.env.XDG_CACHE_HOME || (home ? path.join(home, ".cache") : undefined);
+const config = process.env.XDG_CONFIG_HOME || (home ? path.join(home, ".config") : undefined);
+const state = process.env.XDG_STATE_HOME || (home ? path.join(home, ".local", "state") : undefined);
+/** The XDG base directories that root opencode's global paths. */
+export function roots(app) {
+    return {
+        data: path.join(data, app),
+        cache: path.join(cache, app),
+        config: path.join(config, app),
+        state: path.join(state, app),
+        tmp: path.join(os.tmpdir(), app),
+    };
+}

package/dist/global-roots.workerd.d.ts

@@ -0,0 +1,7 @@
+export declare function roots(app: string): {
+    data: string;
+    cache: string;
+    config: string;
+    state: string;
+    tmp: string;
+};

package/dist/global-roots.workerd.js

@@ -0,0 +1,15 @@
+import os from "os";
+import path from "path";
+// workerd has no home directory or XDG base dirs and only tmp is writable, so
+// every global path roots under one directory there. Nothing durable lives in
+// these: on workerd the database is on Durable Object storage.
+export function roots(app) {
+    const root = path.join(os.tmpdir(), app);
+    return {
+        data: path.join(root, "data"),
+        cache: path.join(root, "cache"),
+        config: path.join(root, "config"),
+        state: path.join(root, "state"),
+        tmp: path.join(root, "tmp"),
+    };
+}

package/dist/global.d.ts

@@ -0,0 +1,30 @@
+import { Context, Layer } from "effect";
+export declare const Path: {
+    readonly home: string;
+    data: string;
+    bin: string;
+    log: string;
+    repos: string;
+    cache: string;
+    config: string;
+    state: string;
+    tmp: string;
+};
+declare const Service_base: Context.ServiceClass<Service, "@opencode/Global", Interface>;
+export declare class Service extends Service_base {
+}
+export interface Interface {
+    readonly home: string;
+    readonly data: string;
+    readonly cache: string;
+    readonly config: string;
+    readonly state: string;
+    readonly tmp: string;
+    readonly bin: string;
+    readonly log: string;
+    readonly repos: string;
+}
+export declare function make(input?: Partial<Interface>): Interface;
+export declare const node: import("./effect/layer-node.js").Provider<Service, never, import("./effect/layer-node.js").Tag<"global">>;
+export declare const layerWith: (input: Partial<Interface>) => Layer.Layer<Service, never, never>;
+export * as Global from "./global.js";

package/dist/global.js

@@ -0,0 +1,54 @@
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { Context, Effect, Layer } from "effect";
+// XDG on runtimes with a home directory; one tmp-rooted directory on workerd.
+// The variants resolve through the `workerd` bundle condition, like the
+// native-module stubs, so no runtime sniffing happens here.
+import { roots } from "#global-roots";
+import { Flock } from "./flock.js";
+import { makeGlobalNode } from "./effect/app-node.js";
+const app = "opencode";
+const { data, cache, config, state, tmp } = roots(app);
+const paths = {
+    get home() {
+        return process.env.OPENCODE_TEST_HOME ?? os.homedir();
+    },
+    data,
+    bin: path.join(cache, "bin"),
+    log: path.join(data, "log"),
+    repos: path.join(data, "repos"),
+    cache,
+    config,
+    state,
+    tmp,
+};
+export const Path = paths;
+Flock.setGlobal({ state });
+export class Service extends Context.Service()("@opencode/Global") {
+}
+export function make(input = {}) {
+    // The acquired service canonicalizes default tmp; use it instead of Path.tmp for path comparisons.
+    return {
+        home: Path.home,
+        data: Path.data,
+        cache: Path.cache,
+        config: Path.config,
+        state: Path.state,
+        tmp: input.tmp ?? Path.tmp,
+        bin: Path.bin,
+        log: Path.log,
+        repos: Path.repos,
+        ...input,
+    };
+}
+const acquire = (input) => Effect.gen(function* () {
+    const service = Service.of(make(input));
+    yield* Effect.promise(() => Promise.all([service.data, service.config, service.state, service.log, service.bin, service.repos, service.tmp].map((directory) => fs.promises.mkdir(directory, { recursive: true }))));
+    const canonicalTmp = yield* Effect.promise(() => fs.promises.realpath(service.tmp));
+    return Service.of({ ...service, tmp: input.tmp ?? canonicalTmp });
+});
+const layer = Layer.effect(Service, Effect.suspend(() => acquire({ config: process.env.OPENCODE_CONFIG_DIR ?? Path.config })));
+export const node = makeGlobalNode({ service: Service, layer: layer, deps: [] });
+export const layerWith = (input) => Layer.effect(Service, acquire(input));
+export * as Global from "./global.js";

package/dist/hash.d.ts

@@ -0,0 +1,4 @@
+export declare namespace Hash {
+    function fast(input: string | Buffer): string;
+    function sha256(input: string | Buffer): string;
+}

package/dist/hash.js

@@ -0,0 +1,12 @@
+import { createHash } from "crypto";
+export var Hash;
+(function (Hash) {
+    function fast(input) {
+        return createHash("sha1").update(input).digest("hex");
+    }
+    Hash.fast = fast;
+    function sha256(input) {
+        return createHash("sha256").update(input).digest("hex");
+    }
+    Hash.sha256 = sha256;
+})(Hash || (Hash = {}));

package/dist/npm-config.d.ts

@@ -0,0 +1,4 @@
+export * as NpmConfig from "./npm-config.js";
+import { Effect } from "effect";
+export declare const load: (dir: string) => Effect.Effect<Record<string, unknown>, never, never>;
+export declare const registry: (dir: string) => Effect.Effect<string, never, never>;

package/dist/npm-config.js

@@ -0,0 +1,34 @@
+export * as NpmConfig from "./npm-config.js";
+import { fileURLToPath } from "url";
+import { Effect } from "effect";
+export const load = (dir) => Effect.tryPromise({
+    try: async () => {
+        // @ts-expect-error npm does not publish types for this internal config API.
+        const { default: Config } = await import("@npmcli/config");
+        // @ts-expect-error npm does not publish types for this internal config API.
+        const { default: npmDefinitions } = await import("@npmcli/config/lib/definitions/index.js");
+        const { definitions, flatten, nerfDarts, shorthands } = npmDefinitions;
+        const config = new Config({
+            // Resolved per call: on workerd import.meta.url is undefined and building
+            // this URL at module scope fails startup validation; npm config never runs there.
+            npmPath: fileURLToPath(new URL("..", import.meta.url)),
+            cwd: dir,
+            env: { ...process.env },
+            argv: [process.execPath, process.execPath, "--prefix", dir],
+            execPath: process.execPath,
+            platform: process.platform,
+            definitions,
+            flatten,
+            nerfDarts,
+            shorthands,
+            warn: false,
+        });
+        await config.load();
+        return config.flat;
+    },
+    catch: (cause) => cause,
+}).pipe(Effect.orElseSucceed(() => ({})));
+export const registry = (dir) => load(dir).pipe(Effect.map((config) => {
+    const registry = typeof config.registry === "string" ? config.registry : "https://registry.npmjs.org";
+    return registry.endsWith("/") ? registry.slice(0, -1) : registry;
+}));

package/dist/npm.d.ts

@@ -0,0 +1,37 @@
+export * as Npm from "./npm.js";
+import { Effect, Schema, Context } from "effect";
+import { EffectFlock } from "./effect-flock.js";
+import { LayerNode } from "./effect/layer-node.js";
+declare const InstallFailedError_base: Schema.Class<InstallFailedError, Schema.TaggedStruct<"NpmInstallFailedError", {
+    readonly add: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly dir: Schema.String;
+    readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class InstallFailedError extends InstallFailedError_base {
+}
+export interface Package {
+    readonly directory: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly revision?: string;
+}
+export interface Interface {
+    readonly add: (pkg: string) => Effect.Effect<Package, InstallFailedError | EffectFlock.LockError>;
+    readonly resolve: (pkg: string) => Effect.Effect<Package>;
+    readonly check: (pkg: string) => Effect.Effect<boolean, InstallFailedError>;
+    readonly update: (pkg: string) => Effect.Effect<Package, InstallFailedError | EffectFlock.LockError>;
+    readonly which: (pkg: string, bin?: string) => Effect.Effect<string | undefined>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@opencode/Npm", Interface>;
+export declare class Service extends Service_base {
+}
+export declare function sanitize(pkg: string): string;
+export declare function isRegistryPackage(pkg: string): Promise<boolean>;
+export declare function isInstallablePackage(pkg: string): Promise<boolean>;
+export declare function cacheKey(pkg: string): Promise<string>;
+export declare const node: LayerNode.Provider<Service, never, LayerNode.Tag<"global">>;
+export declare function add(...args: Parameters<Interface["add"]>): Promise<Package>;
+export declare function resolve(...args: Parameters<Interface["resolve"]>): Promise<Package>;
+export declare function check(...args: Parameters<Interface["check"]>): Promise<boolean>;
+export declare function update(...args: Parameters<Interface["update"]>): Promise<Package>;
+export declare function which(...args: Parameters<Interface["which"]>): Promise<string | undefined>;

package/dist/npm.js

@@ -0,0 +1,386 @@
+export * as Npm from "./npm.js";
+import path from "path";
+import { createHash, randomUUID } from "node:crypto";
+import { Clock, Effect, Schema, Context, Layer, Option, FileSystem } from "effect";
+import { FSUtil } from "./fs-util.js";
+import { Global } from "./global.js";
+import { EffectFlock } from "./effect-flock.js";
+import { makeGlobalNode } from "./effect/app-node.js";
+import { filesystem } from "./effect/app-node-platform.js";
+import { LayerNode } from "./effect/layer-node.js";
+import { makeRuntime } from "./effect/runtime.js";
+import { NpmConfig } from "./npm-config.js";
+export class InstallFailedError extends Schema.TaggedError()("NpmInstallFailedError", {
+    add: Schema.Array(Schema.String).pipe(Schema.optional),
+    dir: Schema.String,
+    cause: Schema.optional(Schema.Defect()),
+}) {
+}
+export class Service extends Context.Service()("@opencode/Npm") {
+}
+const illegal = process.platform === "win32" ? new Set(["<", ">", ":", '"', "|", "?", "*"]) : undefined;
+export function sanitize(pkg) {
+    if (!illegal)
+        return pkg;
+    return Array.from(pkg, (char) => (illegal.has(char) || char.charCodeAt(0) < 32 ? "_" : char)).join("");
+}
+export async function isRegistryPackage(pkg) {
+    return (await parse(pkg))?.type === "registry";
+}
+export async function isInstallablePackage(pkg) {
+    return (await parse(pkg)) !== undefined;
+}
+export async function cacheKey(pkg) {
+    return key(pkg, await parse(pkg));
+}
+async function parse(pkg) {
+    const { default: npa } = await import("npm-package-arg");
+    try {
+        const result = npa(pkg);
+        if (result.type === "git") {
+            return {
+                type: "git",
+                ...(result.name ? { name: result.name } : {}),
+                slug: gitSlug(pkg),
+                mutable: !isCommit(result.gitCommittish),
+            };
+        }
+        if (!result.name || !["version", "range", "tag"].includes(result.type))
+            return;
+        return {
+            type: "registry",
+            name: result.name,
+            spec: result.raw === result.name ? "latest" : result.rawSpec,
+            mutable: result.type !== "version",
+        };
+    }
+    catch {
+        return;
+    }
+}
+function key(pkg, target) {
+    if (target?.type === "git")
+        return `git-${target.slug}-${createHash("sha256").update(pkg).digest("hex").slice(0, 12)}`;
+    if (target?.type === "registry")
+        return sanitize(`${target.name}@${target.spec}`);
+    return sanitize(pkg);
+}
+function gitSlug(pkg) {
+    const target = (() => {
+        try {
+            return decodeURIComponent(pkg.split("#")[0]);
+        }
+        catch {
+            return pkg.split("#")[0];
+        }
+    })();
+    return (target
+        .replace(/\.git$/i, "")
+        .split(/[/:\\]/)
+        .at(-1)
+        ?.replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "repository");
+}
+const PackageJson = Schema.Struct({
+    dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    version: Schema.optional(Schema.String),
+});
+const PackageLock = Schema.Struct({
+    packages: Schema.optional(Schema.Record(Schema.String, Schema.Struct({ resolved: Schema.optional(Schema.String) }))),
+});
+const retention = 7 * 24 * 60 * 60 * 1_000;
+const stagingRetention = 60 * 60 * 1_000;
+const layer = Layer.effect(Service, Effect.gen(function* () {
+    const afs = yield* FSUtil.Service;
+    const global = yield* Global.Service;
+    const fs = yield* FileSystem.FileSystem;
+    const flock = yield* EffectFlock.Service;
+    const directory = (pkg, target) => path.join(global.cache, "npm", key(pkg, target));
+    const generations = Effect.fnUntraced(function* (dir) {
+        return yield* fs.readDirectory(dir).pipe(Effect.orElseSucceed(() => []), Effect.map((entries) => entries
+            .filter((entry) => /^\d+$/.test(entry))
+            .toSorted((a, b) => Number(a) - Number(b))));
+    });
+    const current = Effect.fnUntraced(function* (dir) {
+        const latest = (yield* generations(dir)).at(-1);
+        return latest ? path.join(dir, latest) : undefined;
+    });
+    const mkdir = (dir) => fs.makeDirectory(dir, { recursive: true }).pipe(Effect.mapError((cause) => new InstallFailedError({ dir, cause })));
+    const remove = (target, dir) => fs.remove(target, { recursive: true, force: true }).pipe(Effect.mapError((cause) => new InstallFailedError({ dir, cause })));
+    const rename = (from, to, dir) => fs.rename(from, to).pipe(Effect.mapError((cause) => new InstallFailedError({ dir, cause })));
+    const installedName = Effect.fnUntraced(function* (pkg, dir, target) {
+        if (target?.name)
+            return target.name;
+        const manifest = yield* afs
+            .readJson(path.join(dir, "package.json"))
+            .pipe(Effect.flatMap(Schema.decodeUnknownEffect(PackageJson)), Effect.option);
+        if (Option.isSome(manifest)) {
+            const name = Object.keys(manifest.value.dependencies ?? {})[0];
+            if (name)
+                return name;
+        }
+        return pkg;
+    });
+    const installedRevision = Effect.fnUntraced(function* (root, name, target) {
+        const dir = path.join(root, "node_modules", name);
+        if (target.type === "registry") {
+            const manifest = yield* afs
+                .readJson(path.join(dir, "package.json"))
+                .pipe(Effect.flatMap(Schema.decodeUnknownEffect(PackageJson)), Effect.option);
+            return Option.isSome(manifest) ? manifest.value.version : undefined;
+        }
+        for (const file of [path.join(root, "package-lock.json"), path.join(root, "node_modules", ".package-lock.json")]) {
+            const lock = yield* afs
+                .readJson(file)
+                .pipe(Effect.flatMap(Schema.decodeUnknownEffect(PackageLock)), Effect.option);
+            const revision = gitRevision(Option.isSome(lock) ? lock.value.packages?.[`node_modules/${name}`]?.resolved : undefined);
+            if (revision)
+                return revision;
+        }
+    });
+    const metadata = Effect.fnUntraced(function* (root, name, dir, target) {
+        const manifest = yield* afs
+            .readJson(path.join(dir, "package.json"))
+            .pipe(Effect.flatMap(Schema.decodeUnknownEffect(PackageJson)), Effect.option);
+        const manifestVersion = Option.isSome(manifest) ? manifest.value.version : undefined;
+        const revision = target ? (yield* installedRevision(root, name, target)) ?? manifestVersion : undefined;
+        const version = target?.type === "git" ? revision : manifestVersion;
+        return {
+            directory: dir,
+            name,
+            ...(version ? { version } : {}),
+            ...(revision ? { revision } : {}),
+        };
+    });
+    const reify = (input) => Effect.gen(function* () {
+        const { Arborist } = yield* Effect.promise(() => import("@npmcli/arborist"));
+        const add = input.add ?? [];
+        const options = {
+            ...(yield* NpmConfig.load(input.config ?? input.dir)),
+            ...(input.update ? { preferOnline: true, noGitRevCache: true } : {}),
+            // Audit reports are unused here, but Arborist waits for them before completing an install.
+            audit: false,
+        };
+        const arborist = new Arborist({
+            ...options,
+            path: input.dir,
+            binLinks: true,
+            progress: false,
+            savePrefix: "",
+            ignoreScripts: true,
+        });
+        return yield* Effect.tryPromise({
+            try: () => arborist.reify({
+                ...options,
+                add,
+                update: input.update,
+                save: true,
+                saveType: "prod",
+            }),
+            catch: (cause) => new InstallFailedError({
+                cause,
+                add,
+                dir: input.dir,
+            }),
+        });
+    }).pipe(Effect.withSpan("Npm.reify", {
+        attributes: input,
+    }));
+    const install = Effect.fnUntraced(function* (pkg, target, dir, update) {
+        yield* flock.acquire(`npm-install:${dir}`);
+        const active = yield* current(dir);
+        const name = yield* installedName(pkg, active ?? dir, target);
+        if (active && !update && (yield* afs.existsSafe(path.join(active, "node_modules", name)))) {
+            return yield* metadata(active, name, path.join(active, "node_modules", name), target);
+        }
+        yield* mkdir(dir);
+        const startedAt = yield* Clock.currentTimeMillis;
+        // Arborist keys lockfile entries relative to the root's real path. When the cache
+        // directory is reached through a symlink (macOS `/var` → `/private/var`, a linked
+        // XDG cache), the keys become `../../…` paths that installedRevision never finds,
+        // so Git checks report "not installed" and updates go undetected. Stage under the
+        // resolved directory so the root path and real path agree.
+        const root = yield* fs.realPath(dir).pipe(Effect.mapError((cause) => new InstallFailedError({ dir, cause })));
+        const staging = path.join(root, `.staging-${startedAt}-${randomUUID()}`);
+        const staged = yield* Effect.gen(function* () {
+            const tree = yield* reify({ dir: staging, config: dir, add: [pkg], update });
+            const installed = tree.edgesOut.values().next().value?.to;
+            const installedNameValue = installed?.name ?? (yield* installedName(pkg, staging, target));
+            const result = yield* metadata(staging, installedNameValue, installed?.path ?? path.join(staging, "node_modules", installedNameValue), target);
+            if (!installed && !(yield* afs.isDir(result.directory)))
+                return yield* new InstallFailedError({ add: [pkg], dir: staging });
+            const links = process.platform === "win32"
+                ? Array.from(tree.inventory.values()).filter((node) => node.isLink && FSUtil.contains(staging, node.path) && FSUtil.contains(staging, node.realpath))
+                : [];
+            return { result, links };
+        }).pipe(Effect.onError(() => remove(staging, dir).pipe(Effect.ignore)));
+        if (active) {
+            const activeEntry = yield* metadata(active, name, path.join(active, "node_modules", name), target);
+            if (activeEntry.revision && activeEntry.revision === staged.result.revision) {
+                yield* remove(staging, dir);
+                return activeEntry;
+            }
+        }
+        const completedAt = yield* Clock.currentTimeMillis;
+        const newest = Number((yield* generations(dir)).at(-1) ?? 0);
+        const generation = path.join(dir, String(Math.max(completedAt, newest + 1)));
+        // Windows junctions use absolute targets, so rebase internal links before publishing the generation.
+        if (staged.links.length > 0) {
+            const { unlink, symlink } = yield* Effect.promise(() => import("node:fs/promises"));
+            yield* Effect.forEach(staged.links, (link) => Effect.tryPromise({
+                try: async () => {
+                    await unlink(link.path);
+                    await symlink(path.join(generation, path.relative(staging, link.realpath)), link.path, "junction");
+                },
+                catch: (cause) => new InstallFailedError({ dir, cause }),
+            }), { discard: true }).pipe(Effect.onError(() => remove(staging, dir).pipe(Effect.ignore)));
+        }
+        yield* rename(staging, generation, dir);
+        return { ...staged.result, directory: path.join(generation, "node_modules", staged.result.name) };
+    });
+    const collect = Effect.fnUntraced(function* (dir) {
+        const now = yield* Clock.currentTimeMillis;
+        const completed = yield* generations(dir);
+        const keep = new Set(completed.slice(-2));
+        const entries = yield* fs.readDirectory(dir).pipe(Effect.orElseSucceed(() => []));
+        yield* Effect.forEach(entries, (name) => {
+            const timestamp = /^\d+$/.test(name)
+                ? Number(name)
+                : Number(name.match(/^\.staging-(\d+)-/)?.[1] ?? Number.NaN);
+            const maximumAge = name.startsWith(".staging-") ? stagingRetention : retention;
+            if (!Number.isFinite(timestamp) || keep.has(name) || now - timestamp <= maximumAge)
+                return Effect.void;
+            return remove(path.join(dir, name), dir).pipe(Effect.catchCause((cause) => Effect.logWarning("failed to remove stale npm generation", { dir, name, cause })));
+        }, { concurrency: "unbounded", discard: true });
+    });
+    const add = Effect.fn("Npm.add")(function* (pkg) {
+        const target = yield* Effect.promise(() => parse(pkg));
+        const dir = directory(pkg, target);
+        return yield* install(pkg, target, dir, false);
+    }, Effect.scoped);
+    const resolve = Effect.fn("Npm.resolve")(function* (pkg) {
+        const target = yield* Effect.promise(() => parse(pkg));
+        const root = directory(pkg, target);
+        const generation = yield* current(root);
+        const name = yield* installedName(pkg, generation ?? root, target);
+        const dir = path.join(generation ?? root, "node_modules", name);
+        if (!(yield* afs.existsSafe(dir)))
+            return { directory: dir, name };
+        return yield* metadata(generation ?? root, name, dir, target);
+    });
+    const check = Effect.fn("Npm.check")(function* (pkg) {
+        const target = yield* Effect.promise(() => parse(pkg));
+        const root = directory(pkg, target);
+        if (!target)
+            return yield* new InstallFailedError({
+                dir: root,
+                cause: new Error("Package checks only support registry and Git package specs"),
+            });
+        if (!target.mutable)
+            return false;
+        const generation = yield* current(root);
+        const name = yield* installedName(pkg, generation ?? root, target);
+        const installed = generation ? yield* installedRevision(generation, name, target) : undefined;
+        if (!installed)
+            return yield* new InstallFailedError({ dir: root, cause: new Error(`Package is not installed: ${pkg}`) });
+        const { manifest, resolve } = yield* Effect.promise(() => import("pacote"));
+        const options = { ...(yield* NpmConfig.load(root)), preferOnline: true, noGitRevCache: true, ignoreScripts: true };
+        const available = yield* Effect.tryPromise({
+            try: async () => target.type === "git" ? gitRevision(await resolve(pkg, options)) : (await manifest(pkg, options)).version,
+            catch: (cause) => new InstallFailedError({ dir: root, cause }),
+        });
+        if (!available)
+            return yield* new InstallFailedError({ dir: root, cause: new Error(`Package revision not found: ${pkg}`) });
+        return installed !== available;
+    });
+    const update = Effect.fn("Npm.update")(function* (pkg) {
+        const target = yield* Effect.promise(() => parse(pkg));
+        const dir = directory(pkg, target);
+        if (!target)
+            return yield* new InstallFailedError({
+                dir,
+                cause: new Error("Package updates only support registry and Git package specs"),
+            });
+        if (!target.mutable)
+            return yield* add(pkg);
+        const installed = yield* install(pkg, target, dir, true);
+        yield* collect(dir);
+        return installed;
+    }, Effect.scoped);
+    const which = Effect.fn("Npm.which")(function* (pkg, bin) {
+        const target = yield* Effect.promise(() => parse(pkg));
+        const root = directory(pkg, target);
+        const pick = Effect.fnUntraced(function* (dir) {
+            const binDir = path.join(dir, "node_modules", ".bin");
+            const files = yield* fs.readDirectory(binDir).pipe(Effect.orElseSucceed(() => []));
+            if (files.length === 0)
+                return Option.none();
+            // Caller picked a specific bin (e.g. pyright exposes both `pyright` and
+            // `pyright-langserver`); trust the hint if the package provides it.
+            if (bin)
+                return files.includes(bin) ? Option.some(path.join(binDir, bin)) : Option.none();
+            if (files.length === 1)
+                return Option.some(path.join(binDir, files[0]));
+            const packageName = target?.name ?? pkg;
+            const pkgJson = yield* afs.readJson(path.join(dir, "node_modules", packageName, "package.json")).pipe(Effect.option);
+            if (Option.isSome(pkgJson)) {
+                const parsed = pkgJson.value;
+                if (parsed?.bin) {
+                    const unscoped = packageName.startsWith("@") ? packageName.split("/")[1] : packageName;
+                    const parsedBin = parsed.bin;
+                    if (typeof parsedBin === "string")
+                        return Option.some(path.join(binDir, unscoped));
+                    const keys = Object.keys(parsedBin);
+                    const selected = parsedBin[unscoped] ? unscoped : keys[0];
+                    return selected ? Option.some(path.join(binDir, selected)) : Option.none();
+                }
+            }
+            return Option.some(path.join(binDir, files[0]));
+        });
+        return Option.getOrUndefined(yield* Effect.gen(function* () {
+            const generation = yield* current(root);
+            const selected = generation ? yield* pick(generation) : Option.none();
+            if (Option.isSome(selected))
+                return selected;
+            yield* add(pkg);
+            const installed = yield* current(root);
+            if (!installed)
+                return Option.none();
+            return yield* pick(installed);
+        }).pipe(Effect.scoped, Effect.orElseSucceed(() => Option.none())));
+    });
+    return Service.of({
+        add,
+        resolve,
+        check,
+        update,
+        which,
+    });
+}));
+export const node = makeGlobalNode({
+    service: Service,
+    layer: layer,
+    deps: [FSUtil.node, Global.node, filesystem, EffectFlock.node],
+});
+const { runPromise } = makeRuntime(Service, LayerNode.compile(node));
+export async function add(...args) {
+    return runPromise((svc) => svc.add(...args));
+}
+export async function resolve(...args) {
+    return runPromise((svc) => svc.resolve(...args));
+}
+export async function check(...args) {
+    return runPromise((svc) => svc.check(...args));
+}
+export async function update(...args) {
+    return runPromise((svc) => svc.update(...args));
+}
+export async function which(...args) {
+    return runPromise((svc) => svc.which(...args));
+}
+function gitRevision(resolved) {
+    return resolved?.match(/#([a-f0-9]{40}|[a-f0-9]{64})(?=::|$)/i)?.[1];
+}
+function isCommit(value) {
+    return /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(value ?? "");
+}

package/dist/observability/logging.d.ts

@@ -0,0 +1,14 @@
+import { Effect, FileSystem, Logger } from "effect";
+export declare const LOG_MAX_BYTES: number;
+export declare const LOG_KEEP_BYTES: number;
+export declare const LOG_TRIM_INTERVAL = "1 hour";
+export declare const LOG_TRIM_LOCK_STALE_MS: number;
+export declare function file(local?: boolean, channel?: string): string;
+export declare function fileLogger(target?: string, id?: string): Effect.Effect<Logger.Logger<unknown, void>, import("effect/PlatformError").PlatformError, import("effect/Scope").Scope | FileSystem.FileSystem>;
+export declare const trim: (target: string, options?: {
+    max?: number;
+    keep?: number;
+} | undefined) => Effect.Effect<void, import("effect/PlatformError").PlatformError, FileSystem.FileSystem>;
+export declare function minimumLogLevel(): "Error" | "Warn" | "Info" | "Debug";
+export declare function loggers(local?: boolean, channel?: string): (Logger.Logger<unknown, void> | Effect.Effect<Logger.Logger<unknown, void>, import("effect/PlatformError").PlatformError, import("effect/Scope").Scope | FileSystem.FileSystem>)[];
+export * as Logging from "./logging.js";