feat(core): support git plugin packages (#45110)

This commit is contained in:
Kit Langton
2026-08-25 22:02:49 -04:00
committed by GitHub
Unverified
parent e211b6f30e
commit 4b71ae6a0d
5 changed files with 172 additions and 19 deletions
+1 -1
View File
@@ -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", {
@@ -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"] })
+105
View File
@@ -21,6 +21,39 @@ const writePackage = (dir: string, pkg: Record<string, unknown>) =>
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", () => {
+55 -12
View File
@@ -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<string, { to?: ArboristNode }>
}
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* () {
+9 -2
View File
@@ -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.