From 4b71ae6a0d1a6b8af1b727b352d6df4a5fa88d5b Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Tue, 25 Aug 2026 22:02:49 -0400 Subject: [PATCH] feat(core): support git plugin packages (#45110) --- packages/cli/src/commands/commands.ts | 2 +- .../cli/src/commands/handlers/plugin/add.ts | 6 +- packages/core/test/npm.test.ts | 105 ++++++++++++++++++ packages/util/src/npm.ts | 67 +++++++++-- packages/www/src/docs/content/plugins.mdx | 11 +- 5 files changed, 172 insertions(+), 19 deletions(-) diff --git a/packages/cli/src/commands/commands.ts b/packages/cli/src/commands/commands.ts index ef069516eb3..30304d04617 100644 --- a/packages/cli/src/commands/commands.ts +++ b/packages/cli/src/commands/commands.ts @@ -181,7 +181,7 @@ const Root = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCODE_CLI_NAME Spec.make("add", { description: "Install a plugin and add it to the global configuration", params: { - package: Argument.string("package").pipe(Argument.withDescription("npm registry package specifier")), + package: Argument.string("package").pipe(Argument.withDescription("npm registry or Git package specifier")), }, }), Spec.make("remove", { diff --git a/packages/cli/src/commands/handlers/plugin/add.ts b/packages/cli/src/commands/handlers/plugin/add.ts index c33049c2163..8ca3ed53d00 100644 --- a/packages/cli/src/commands/handlers/plugin/add.ts +++ b/packages/cli/src/commands/handlers/plugin/add.ts @@ -13,10 +13,8 @@ import { Config } from "../../../config" export default Runtime.handler( Commands.commands.plugin.commands.add, Effect.fn("cli.plugin.add")(function* (input) { - if (!(yield* Effect.promise(() => Npm.isRegistryPackage(input.package)))) - return yield* Effect.fail( - new Error("Plugin target must be an npm registry package name, version, tag, or semver range"), - ) + if (!(yield* Effect.promise(() => Npm.isInstallablePackage(input.package)))) + return yield* Effect.fail(new Error("Plugin target must be an npm registry package or Git package specifier")) const npm = yield* Npm.Service const installed = yield* npm.add(input.package, { subpaths: ["server", ""] }) const tui = yield* npm.resolve(input.package, { subpaths: ["tui"] }) diff --git a/packages/core/test/npm.test.ts b/packages/core/test/npm.test.ts index bf41b99be73..fefa36eca3c 100644 --- a/packages/core/test/npm.test.ts +++ b/packages/core/test/npm.test.ts @@ -21,6 +21,39 @@ const writePackage = (dir: string, pkg: Record) => const npmLayer = (cache: string) => AppNodeBuilder.build(Npm.node, [[Global.node, Global.layerWith({ cache, state: path.join(cache, "state") })]]) +async function createGitFixture(directory: string) { + const repository = path.join(directory, "repository") + await fs.mkdir(path.join(repository, "dependency"), { recursive: true }) + await writePackage(repository, { + name: "fixture-git-plugin", + exports: "./index.js", + dependencies: { "fixture-dependency": "file:./dependency" }, + }) + await writePackage(path.join(repository, "dependency"), { name: "fixture-dependency", exports: "./index.js" }) + await Bun.write(path.join(repository, "index.js"), "export default { root: true }\n") + await Bun.write(path.join(repository, "dependency", "index.js"), "export const dependency = true\n") + + const subdirectory = path.join(repository, "packages", "subdirectory-plugin") + await fs.mkdir(path.join(subdirectory, "dependency"), { recursive: true }) + await writePackage(subdirectory, { + name: "fixture-subdirectory-plugin", + exports: "./index.js", + dependencies: { "fixture-subdirectory-dependency": "file:./dependency" }, + }) + await writePackage(path.join(subdirectory, "dependency"), { + name: "fixture-subdirectory-dependency", + exports: "./index.js", + }) + await Bun.write(path.join(subdirectory, "index.js"), "export default { subdirectory: true }\n") + await Bun.write(path.join(subdirectory, "dependency", "index.js"), "export const dependency = true\n") + + await Bun.$`git init -q -b fixture-branch ${repository}` + await Bun.$`git -C ${repository} add .` + await Bun.$`git -C ${repository} -c user.name=fixture -c user.email=fixture@example.com commit -qm fixture` + const commit = await Bun.$`git -C ${repository} rev-parse HEAD`.text().then((value) => value.trim()) + return { repository, commit } +} + describe("Npm.sanitize", () => { test("keeps normal scoped package specs unchanged", () => { expect(Npm.sanitize("@opencode/acme")).toBe("@opencode/acme") @@ -46,6 +79,33 @@ describe("Npm.isRegistryPackage", () => { }) }) +describe("Npm.isInstallablePackage", () => { + test("accepts registry and npm-compatible Git specs", async () => { + expect(await Npm.isInstallablePackage("plugin@^1.2.0")).toBe(true) + expect(await Npm.isInstallablePackage("github:acme/plugin#main")).toBe(true) + expect(await Npm.isInstallablePackage("git+ssh://git@github.com/acme/plugin.git#main")).toBe(true) + expect(await Npm.isInstallablePackage("git@github.com:acme/plugin.git")).toBe(true) + expect( + await Npm.isInstallablePackage( + "git+https://github.com/acme/plugins.git#0123456789abcdef0123456789abcdef01234567::path:packages/plugin", + ), + ).toBe(true) + expect(await Npm.isInstallablePackage("./plugin")).toBe(false) + expect(await Npm.isInstallablePackage("https://example.com/plugin.tgz")).toBe(false) + expect(await Npm.isInstallablePackage("alias@npm:plugin@1.0.0")).toBe(false) + }) +}) + +describe("Npm.cacheKey", () => { + test("preserves registry keys and hashes Git specs", async () => { + expect(await Npm.cacheKey("@opencode/acme@1.0.0")).toBe(Npm.sanitize("@opencode/acme@1.0.0")) + const spec = "git+ssh://git@github.com/acme/plugin.git#main" + expect(await Npm.cacheKey(spec)).toMatch(/^git-[a-f0-9]{64}$/) + expect(await Npm.cacheKey(spec)).toBe(await Npm.cacheKey(spec)) + expect(await Npm.cacheKey(`${spec}-other`)).not.toBe(await Npm.cacheKey(spec)) + }) +}) + describe("Npm.add", () => { test("resolves cached scoped package specs without reifying", async () => { await using tmp = await tmpdir() @@ -116,6 +176,51 @@ describe("Npm.add", () => { expect(entries.tui.entrypoint).toEndWith("/tui.js") expect(entries.fallback.entrypoint).toEndWith("/index.js") }) + + test("installs and resolves named and unnamed Git packages with dependencies", async () => { + await using tmp = await tmpdir() + const fixture = await createGitFixture(tmp.path) + const cache = path.join(tmp.path, "cache") + const specs = [ + `git+file://${fixture.repository}#${fixture.commit}`, + `fixture-named-plugin@git+file://${fixture.repository}#fixture-branch`, + ] + + for (const spec of specs) { + const entries = await Effect.gen(function* () { + const npm = yield* Npm.Service + return { + added: yield* npm.add(spec), + cached: yield* npm.add(spec), + resolved: yield* npm.resolve(spec), + } + }).pipe(Effect.scoped, Effect.provide(npmLayer(cache)), Effect.runPromise) + + expect(entries.added.entrypoint).toEndWith("/index.js") + expect(entries.cached).toEqual(entries.added) + expect(entries.resolved).toEqual(entries.added) + expect( + await fs.stat(path.join(path.dirname(entries.added.directory), "fixture-dependency", "package.json")), + ).toBeTruthy() + expect(entries.added.directory).toContain(path.join("packages", await Npm.cacheKey(spec), "node_modules")) + } + }) + + test("installs a Git package from an npm ::path: subdirectory", async () => { + await using tmp = await tmpdir() + const fixture = await createGitFixture(tmp.path) + const spec = `git+file://${fixture.repository}#${fixture.commit}::path:packages/subdirectory-plugin` + const entry = await Effect.gen(function* () { + const npm = yield* Npm.Service + return yield* npm.add(spec) + }).pipe(Effect.scoped, Effect.provide(npmLayer(path.join(tmp.path, "cache"))), Effect.runPromise) + + expect(entry.directory).toEndWith(path.join("node_modules", "fixture-subdirectory-plugin")) + expect(entry.entrypoint).toEndWith("/index.js") + expect( + await fs.stat(path.join(path.dirname(entry.directory), "fixture-subdirectory-dependency", "package.json")), + ).toBeTruthy() + }) }) describe("Npm.resolve", () => { diff --git a/packages/util/src/npm.ts b/packages/util/src/npm.ts index 8cf027be6da..2cffa1ba8ff 100644 --- a/packages/util/src/npm.ts +++ b/packages/util/src/npm.ts @@ -1,8 +1,8 @@ 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 * as NodeFileSystem from "@effect/platform-node/NodeFileSystem" import { FSUtil } from "./fs-util.js" import { Global } from "./global.js" import { EffectFlock } from "./effect-flock.js" @@ -52,6 +52,26 @@ export async function isRegistryPackage(pkg: string) { } } +export async function isInstallablePackage(pkg: string) { + 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 + } +} + +export async function cacheKey(pkg: string) { + const { default: npa } = await import("npm-package-arg") + try { + if (npa(pkg).type === "git") return `git-${createHash("sha256").update(pkg).digest("hex")}` + } catch { + // Preserve the existing fallback for invalid and non-registry package strings. + } + return sanitize(pkg) +} + const resolveEntryPoint = (name: string, dir: string, subpaths: readonly string[] = [""]): EntryPoint => { const entrypoint = subpaths .map((subpath) => { @@ -77,6 +97,10 @@ interface ArboristTree { edgesOut: Map } +const PackageJson = Schema.Struct({ + dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)), +}) + const layer = Layer.effect( Service, Effect.gen(function* () { @@ -84,7 +108,22 @@ const layer = Layer.effect( const global = yield* Global.Service const fs = yield* FileSystem.FileSystem const flock = yield* EffectFlock.Service - const directory = (pkg: string) => path.join(global.cache, "packages", sanitize(pkg)) + const directory = (pkg: string) => + Effect.map( + Effect.promise(() => cacheKey(pkg)), + (key) => path.join(global.cache, "packages", key), + ) + const installedName = Effect.fnUntraced(function* (pkg: string, dir: string, parsedName?: string) { + if (parsedName) return parsedName + 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 reify = (input: { dir: string; add?: string[] }) => Effect.gen(function* () { yield* flock.acquire(`npm-install:${input.dir}`) @@ -122,14 +161,15 @@ const layer = Layer.effect( const add = Effect.fn("Npm.add")(function* (pkg: string, options?: { readonly subpaths?: readonly string[] }) { const { default: npa } = yield* Effect.promise(() => import("npm-package-arg")) - const dir = directory(pkg) - const name = (() => { + const parsedName = (() => { try { - return npa(pkg).name ?? pkg + return npa(pkg).name ?? undefined } catch { - return pkg + return undefined } })() + const dir = yield* directory(pkg) + const name = yield* installedName(pkg, dir, parsedName) if (yield* afs.existsSafe(path.join(dir, "node_modules", name))) { return resolveEntryPoint(name, path.join(dir, "node_modules", name), options?.subpaths) @@ -138,7 +178,8 @@ const layer = Layer.effect( const tree = yield* reify({ dir, add: [pkg] }) const first = tree.edgesOut.values().next().value?.to if (!first) { - const result = resolveEntryPoint(name, path.join(dir, "node_modules", name), options?.subpaths) + 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 }) } @@ -150,20 +191,22 @@ const layer = Layer.effect( options?: { readonly subpaths?: readonly string[] }, ) { const { default: npa } = yield* Effect.promise(() => import("npm-package-arg")) - const name = (() => { + const parsedName = (() => { try { - return npa(pkg).name ?? pkg + return npa(pkg).name ?? undefined } catch { - return pkg + return undefined } })() - const dir = path.join(directory(pkg), "node_modules", name) + const root = yield* directory(pkg) + const name = yield* installedName(pkg, root, parsedName) + const dir = path.join(root, "node_modules", name) if (!(yield* afs.existsSafe(dir))) return { directory: dir } return resolveEntryPoint(name, dir, options?.subpaths) }) const which = Effect.fn("Npm.which")(function* (pkg: string, bin?: string) { - const dir = directory(pkg) + const dir = yield* directory(pkg) const binDir = path.join(dir, "node_modules", ".bin") const pick = Effect.fnUntraced(function* () { diff --git a/packages/www/src/docs/content/plugins.mdx b/packages/www/src/docs/content/plugins.mdx index f4ebd723cde..d3c83a26f51 100644 --- a/packages/www/src/docs/content/plugins.mdx +++ b/packages/www/src/docs/content/plugins.mdx @@ -79,13 +79,20 @@ opencode2 plugin list --builtin opencode2 plugin remove opencode-acme-plugin@1.2.0 ``` -Package installation accepts npm names with versions, tags, or ranges. Configure local paths directly instead of using -Git, tarball, or npm alias targets with `plugin add`. +Package installation accepts npm names with versions, tags, or ranges, plus npm-compatible Git package specifications. +Git repositories can use hosted shortcuts, HTTPS, or SSH, including private repositories available through your existing +Git credentials. ```sh opencode2 plugin add @acme/opencode-plugin@beta +opencode2 plugin add github:acme/opencode-plugin +opencode2 plugin add git+ssh://git@github.com/acme/opencode-plugin.git#main +opencode2 plugin add 'github:acme/plugins#main::path:packages/opencode-plugin' ``` +Branches, tags, complete commit hashes, and npm's `::path:` repository-subdirectory selectors are supported. Configure +local paths directly; tarball and npm alias targets are not accepted by `plugin add`. + Changes under watched config directories reload automatically. Restart OpenCode after changing an installed package version or an unwatched dependency.