@opencode-ai/util 0.0.0-dev-18789 → 0.0.0-dev-18793

package/dist/npm.d.ts

@@ -12,15 +12,20 @@ export declare class InstallFailedError extends InstallFailedError_base {
 export interface EntryPoint {
     readonly directory: string;
     readonly entrypoint?: string;
+    readonly version?: string;
+    readonly revision?: string;
 }
 export interface Interface {
     readonly add: (pkg: string, options?: {
         readonly subpaths?: readonly string[];
-        readonly refresh?: boolean;
     }) => Effect.Effect<EntryPoint, InstallFailedError | EffectFlock.LockError>;
     readonly resolve: (pkg: string, options?: {
         readonly subpaths?: readonly string[];
     }) => Effect.Effect<EntryPoint>;
+    readonly check: (pkg: string) => Effect.Effect<boolean, InstallFailedError>;
+    readonly update: (pkg: string, options?: {
+        readonly subpaths?: readonly string[];
+    }) => Effect.Effect<EntryPoint, InstallFailedError | EffectFlock.LockError>;
     readonly which: (pkg: string, bin?: string) => Effect.Effect<string | undefined>;
 }
 declare const Service_base: Context.ServiceClass<Service, "@opencode/Npm", Interface>;
@@ -33,4 +38,6 @@ 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<EntryPoint>;
 export declare function resolve(...args: Parameters<Interface["resolve"]>): Promise<EntryPoint>;
+export declare function check(...args: Parameters<Interface["check"]>): Promise<boolean>;
+export declare function update(...args: Parameters<Interface["update"]>): Promise<EntryPoint>;
 export declare function which(...args: Parameters<Interface["which"]>): Promise<string | undefined>;

package/dist/npm.js

@@ -1,7 +1,7 @@
 export * as Npm from "./npm.js";
 import path from "path";
-import { createHash } from "node:crypto";
-import { Effect, Schema, Context, Layer, Option, FileSystem } from "effect";
+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";
@@ -26,36 +26,62 @@ export function sanitize(pkg) {
     return Array.from(pkg, (char) => (illegal.has(char) || char.charCodeAt(0) < 32 ? "_" : char)).join("");
 }
 export async function isRegistryPackage(pkg) {
-    const { default: npa } = await import("npm-package-arg");
-    try {
-        const result = npa(pkg);
-        return result.name !== undefined && ["version", "range", "tag"].includes(result.type);
-    }
-    catch {
-        return false;
-    }
+    return (await parse(pkg))?.type === "registry";
 }
 export async function isInstallablePackage(pkg) {
-    const { default: npa } = await import("npm-package-arg");
-    try {
-        const result = npa(pkg);
-        return result.type === "git" || (result.name !== undefined && ["version", "range", "tag"].includes(result.type));
-    }
-    catch {
-        return false;
-    }
+    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 {
-        if (npa(pkg).type === "git")
-            return `git-${createHash("sha256").update(pkg).digest("hex")}`;
+        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 {
-        // Preserve the existing fallback for invalid and non-registry package strings.
+        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 resolveEntryPoint = (name, dir, subpaths = [""]) => {
     const entrypoint = subpaths
         .map((subpath) => {
@@ -74,16 +100,34 @@ const resolveEntryPoint = (name, dir, subpaths = [""]) => {
 };
 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) => Effect.map(Effect.promise(() => cacheKey(pkg)), (key) => path.join(global.cache, "packages", key));
-    const installedName = Effect.fnUntraced(function* (pkg, dir, parsedName) {
-        if (parsedName)
-            return parsedName;
+    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);
@@ -94,12 +138,40 @@ const layer = Layer.effect(Service, Effect.gen(function* () {
         }
         return pkg;
     });
-    const refreshed = new Set();
+    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 entry = Effect.fnUntraced(function* (root, name, dir, target, subpaths) {
+        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 {
+            ...resolveEntryPoint(name, dir, subpaths),
+            ...(version ? { version } : {}),
+            ...(revision ? { revision } : {}),
+        };
+    });
     const reify = (input) => Effect.gen(function* () {
-        yield* flock.acquire(`npm-install:${input.dir}`);
         const { Arborist } = yield* Effect.promise(() => import("@npmcli/arborist"));
         const add = input.add ?? [];
-        const npmOptions = yield* NpmConfig.load(input.dir);
+        const npmOptions = yield* NpmConfig.load(input.config ?? input.dir);
         const options = input.update ? { ...npmOptions, preferOnline: true, noGitRevCache: true } : npmOptions;
         const arborist = new Arborist({
             ...options,
@@ -126,104 +198,154 @@ const layer = Layer.effect(Service, Effect.gen(function* () {
     }).pipe(Effect.withSpan("Npm.reify", {
         attributes: input,
     }));
-    const add = Effect.fn("Npm.add")(function* (pkg, options) {
-        const { default: npa } = yield* Effect.promise(() => import("npm-package-arg"));
-        const parsed = (() => {
-            try {
-                return npa(pkg);
-            }
-            catch {
-                return undefined;
-            }
-        })();
-        const parsedName = parsed?.name ?? undefined;
-        const dir = yield* directory(pkg);
-        const name = yield* installedName(pkg, dir, parsedName);
-        const cached = yield* afs.existsSafe(path.join(dir, "node_modules", name));
-        const refresh = options?.refresh && isMutable(parsed) && !refreshed.has(pkg);
-        if (refresh) {
-            refreshed.add(pkg);
-            if (cached)
-                yield* reify({ dir, add: [pkg], update: true }).pipe(Effect.catchCause(() => Effect.logWarning("failed to refresh cached package; using installed version")));
+    const install = Effect.fnUntraced(function* (pkg, target, dir, subpaths, 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* entry(active, name, path.join(active, "node_modules", name), target, subpaths);
         }
-        if (cached) {
-            return resolveEntryPoint(name, path.join(dir, "node_modules", name), options?.subpaths);
-        }
-        const tree = yield* reify({ dir, add: [pkg] });
-        if (isMutable(parsed))
-            refreshed.add(pkg);
-        const first = tree.edgesOut.values().next().value?.to;
-        if (!first) {
-            const installed = yield* installedName(pkg, dir, parsedName);
-            const result = resolveEntryPoint(installed, path.join(dir, "node_modules", installed), options?.subpaths);
-            if (result.entrypoint)
-                return result;
-            return yield* new InstallFailedError({ add: [pkg], dir });
+        yield* mkdir(dir);
+        const startedAt = yield* Clock.currentTimeMillis;
+        const staging = path.join(dir, `.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* entry(staging, installedNameValue, installed?.path ?? path.join(staging, "node_modules", installedNameValue), target, subpaths);
+            if (!installed && !result.entrypoint)
+                return yield* new InstallFailedError({ add: [pkg], dir: staging });
+            return { name: installedNameValue, result };
+        }).pipe(Effect.onError(() => remove(staging, dir).pipe(Effect.ignore)));
+        if (active) {
+            const activeEntry = yield* entry(active, name, path.join(active, "node_modules", name), target, subpaths);
+            if (activeEntry.revision && activeEntry.revision === staged.result.revision) {
+                yield* remove(staging, dir);
+                return activeEntry;
+            }
         }
-        return resolveEntryPoint(first.name, first.path, options?.subpaths);
+        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)));
+        yield* rename(staging, generation, dir);
+        return yield* entry(generation, staged.name, path.join(generation, "node_modules", staged.name), target, subpaths);
+    });
+    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, options) {
+        const target = yield* Effect.promise(() => parse(pkg));
+        const dir = directory(pkg, target);
+        return yield* install(pkg, target, dir, options?.subpaths, false);
     }, Effect.scoped);
     const resolve = Effect.fn("Npm.resolve")(function* (pkg, options) {
-        const { default: npa } = yield* Effect.promise(() => import("npm-package-arg"));
-        const parsedName = (() => {
-            try {
-                return npa(pkg).name ?? undefined;
-            }
-            catch {
-                return undefined;
-            }
-        })();
-        const root = yield* directory(pkg);
-        const name = yield* installedName(pkg, root, parsedName);
-        const dir = path.join(root, "node_modules", name);
+        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 };
-        return resolveEntryPoint(name, dir, options?.subpaths);
+        return yield* entry(generation ?? root, name, dir, target, options?.subpaths);
+    });
+    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, options) {
+        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, options);
+        const installed = yield* install(pkg, target, dir, options?.subpaths, true);
+        yield* collect(dir);
+        return installed;
+    }, Effect.scoped);
     const which = Effect.fn("Npm.which")(function* (pkg, bin) {
-        const dir = yield* directory(pkg);
-        const binDir = path.join(dir, "node_modules", ".bin");
-        const pick = Effect.fnUntraced(function* () {
+        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(bin) : Option.none();
+                return files.includes(bin) ? Option.some(path.join(binDir, bin)) : Option.none();
             if (files.length === 1)
-                return Option.some(files[0]);
-            const pkgJson = yield* afs.readJson(path.join(dir, "node_modules", pkg, "package.json")).pipe(Effect.option);
+                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 = pkg.startsWith("@") ? pkg.split("/")[1] : pkg;
+                    const unscoped = packageName.startsWith("@") ? packageName.split("/")[1] : packageName;
                     const parsedBin = parsed.bin;
                     if (typeof parsedBin === "string")
-                        return Option.some(unscoped);
+                        return Option.some(path.join(binDir, unscoped));
                     const keys = Object.keys(parsedBin);
-                    if (keys.length === 1)
-                        return Option.some(keys[0]);
-                    return parsedBin[unscoped] ? Option.some(unscoped) : Option.some(keys[0]);
+                    const selected = parsedBin[unscoped] ? unscoped : keys[0];
+                    return selected ? Option.some(path.join(binDir, selected)) : Option.none();
                 }
             }
-            return Option.some(files[0]);
+            return Option.some(path.join(binDir, files[0]));
         });
         return Option.getOrUndefined(yield* Effect.gen(function* () {
-            const bin = yield* pick();
-            if (Option.isSome(bin)) {
-                return Option.some(path.join(binDir, bin.value));
-            }
-            yield* fs.remove(path.join(dir, "package-lock.json")).pipe(Effect.orElseSucceed(() => { }));
+            const generation = yield* current(root);
+            const selected = generation ? yield* pick(generation) : Option.none();
+            if (Option.isSome(selected))
+                return selected;
             yield* add(pkg);
-            const resolved = yield* pick();
-            if (Option.isNone(resolved))
+            const installed = yield* current(root);
+            if (!installed)
                 return Option.none();
-            return Option.some(path.join(binDir, resolved.value));
+            return yield* pick(installed);
         }).pipe(Effect.scoped, Effect.orElseSucceed(() => Option.none())));
     });
     return Service.of({
         add,
         resolve,
+        check,
+        update,
         which,
     });
 }));
@@ -239,15 +361,18 @@ export async function 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 isMutable(parsed) {
-    if (!parsed)
-        return false;
-    if (["tag", "range"].includes(parsed.type))
-        return true;
-    if (parsed.type !== "git")
-        return false;
-    return !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(parsed.gitCommittish ?? "");
+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/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode-ai/util",
-  "version": "0.0.0-dev-18789",
+  "version": "0.0.0-dev-18793",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -60,6 +60,7 @@
     "mime-types": "3.0.2",
     "minimatch": "10.2.5",
     "npm-package-arg": "13.0.2",
+    "pacote": "21.5.1",
     "resolve.exports": "2.0.3"
   },
   "devDependencies": {
@@ -69,6 +70,7 @@
     "@types/node": "24.12.2",
     "@types/npm-package-arg": "6.1.4",
     "@types/npmcli__arborist": "6.3.3",
+    "@types/pacote": "11.1.8",
     "@typescript/native-preview": "7.0.0-dev.20251207.1"
   }
 }