fix(core): discover system configuration directory at lowest precedence (#54921)

Co-authored-by: Renato Duarte <renato.duarte@datacamp.com>
This commit is contained in:
Aiden Cline
2026-10-12 23:02:06 -05:00
committed by GitHub
Unverified
parent b4a57f6849
commit ba82b370c1
8 changed files with 276 additions and 24 deletions
+38 -5
View File
@@ -18,6 +18,8 @@ import { ConfigNormalize } from "./config/normalize.js"
import { ConfigDiscovery } from "./config/discovery.js"
import { ConfigWatch } from "./config/watch.js"
import { WellKnown } from "./wellknown.js"
import { AppProcess } from "@opencode/util/process"
import { ChildProcess } from "effect/process"
export function latest<K extends keyof Info>(entries: readonly Entry[], key: K): Info[K] | undefined {
return entries.findLast((entry): entry is Document => entry.type === "document" && entry.info[key] !== undefined)
@@ -44,9 +46,10 @@ export interface Interface {
export const Options = Schema.Struct({
project: Schema.optional(Schema.Boolean),
// false skips the global config dir, ~/.claude, and ~/.agents; wellknown,
// file, and content entries still load.
// false skips the system and global config dirs, ~/.claude, and ~/.agents;
// wellknown, file, and content entries still load.
global: Schema.optional(Schema.Boolean),
system: Schema.optional(Schema.Union([Schema.Boolean, Schema.String])),
file: Schema.optional(Schema.String),
content: Schema.optional(Schema.String),
})
@@ -97,6 +100,7 @@ export const layer = (options?: Options) =>
const credentials = yield* Credential.Service
const globalService = yield* Global.Service
const wellknown = yield* WellKnown.Service
const processes = yield* AppProcess.Service
const reloadLock = Semaphore.makeUnsafe(1)
const updateLock = Semaphore.makeUnsafe(1)
const decodeOptions = { errors: "all", onExcessProperty: "ignore" } as const
@@ -182,6 +186,26 @@ export const layer = (options?: Options) =>
return yield* Effect.forEach(entries, loadWellknownEntry).pipe(Effect.map((documents) => documents.flat()))
})
const loadPreferences = Effect.fn("Config.loadPreferences")(function* (plist: AbsolutePath) {
const result = yield* processes
.run(ChildProcess.make("plutil", ["-convert", "json", "-o", "-", plist], { stdin: "ignore" }), {
timeout: "10 seconds",
})
.pipe(Effect.flatMap(AppProcess.requireSuccess), Effect.option)
if (Option.isNone(result)) {
yield* Effect.logWarning("failed to convert managed preferences", { source: plist })
return []
}
const text = yield* ConfigVariable.substitute({
type: "virtual",
source: plist,
dir: path.dirname(plist),
text: ConfigDiscovery.stripPreferenceMetadata(result.value.stdout.toString()),
})
const info = yield* parseInfo(text, plist)
return info ? [new Document({ type: "document", path: plist, info })] : []
})
const loadDirectory = Effect.fnUntraced(function* (directory: AbsolutePath) {
return [
...(yield* Effect.forEach(ConfigDiscovery.names, (file) => loadFile(path.join(directory, file))).pipe(
@@ -217,8 +241,16 @@ export const layer = (options?: Options) =>
)
: []
// Global entries sit below explicit and direct files; project
// directories rank above them.
// System entries sit at lowest priority so users and projects can
// override ordinary defaults while reversed policy evaluation gives
// system policies highest file-based authority. Global entries sit
// below explicit and direct files; project directories rank above them.
// MDM preferences rank below the system directory so their policies
// carry the most file-based authority, matching V1 where they won.
const systemSupplementary = [
...(sources.preferences ? yield* loadPreferences(sources.preferences).pipe(Effect.orDie) : []),
...(sources.system?.present ? yield* loadDirectory(sources.system.path).pipe(Effect.orDie) : []),
]
const globalSupplementary = sources.global ? yield* loadDirectory(sources.global).pipe(Effect.orDie) : []
const projectSupplementary = yield* Effect.forEach(
sources.project.filter((root) => root.present),
@@ -228,6 +260,7 @@ export const layer = (options?: Options) =>
Effect.map((entries) => entries.flat()),
)
return [
...systemSupplementary,
...(yield* loadWellknown().pipe(Effect.orDie)),
...globalSupplementary,
...explicit,
@@ -368,7 +401,7 @@ export function configured(options?: Options) {
return makeLocationNode({
service: Service,
layer: layer(options),
deps: [Watcher.node, Bus.node, FSUtil.node, Global.node, Location.node, Credential.node, WellKnown.node],
deps: [Watcher.node, Bus.node, FSUtil.node, Global.node, Location.node, Credential.node, WellKnown.node, AppProcess.node],
})
}
+62 -4
View File
@@ -1,5 +1,6 @@
export * as ConfigDiscovery from "./discovery.js"
import os from "os"
import path from "path"
import { Effect } from "effect"
import { FSUtil } from "@opencode/util/fs-util"
@@ -12,6 +13,9 @@ export const names = ["opencode.json", "opencode.jsonc"]
/** Eligible sources in priority order, including paths that may appear later. */
export interface Sources {
readonly system?: { readonly path: AbsolutePath; readonly present: boolean }
/** macOS MDM managed preferences plist (`ai.opencode.managed`), when one is deployed. */
readonly preferences?: AbsolutePath
readonly global?: AbsolutePath
readonly explicit?: AbsolutePath
readonly direct: readonly AbsolutePath[]
@@ -20,18 +24,58 @@ export interface Sources {
readonly agents: readonly AbsolutePath[]
}
/** Platform system configuration directory (`/Library/Application Support/opencode`, `/etc/opencode`, `%ProgramData%\opencode`). */
export function systemDirectory(platform: NodeJS.Platform = process.platform, env: NodeJS.ProcessEnv = process.env) {
if (platform === "darwin") return AbsolutePath.make("/Library/Application Support/opencode")
if (platform === "win32") return AbsolutePath.make(path.join(env.ProgramData || "C:\\ProgramData", "opencode"))
return AbsolutePath.make("/etc/opencode")
}
/** macOS MDM managed preferences plists, most specific first; the first one present wins. */
export function preferencePaths(user: string) {
return [
AbsolutePath.make(path.join("/Library/Managed Preferences", user, "ai.opencode.managed.plist")),
AbsolutePath.make("/Library/Managed Preferences/ai.opencode.managed.plist"),
]
}
// Keys macOS and MDM profiles inject into managed preferences that are not OpenCode config.
const preferenceMetadata = new Set([
"PayloadDisplayName",
"PayloadIdentifier",
"PayloadType",
"PayloadUUID",
"PayloadVersion",
"_manualProfile",
])
/** Removes MDM payload metadata from `plutil -convert json` output. */
export function stripPreferenceMetadata(json: string) {
const parsed: unknown = JSON.parse(json)
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return json
return JSON.stringify(Object.fromEntries(Object.entries(parsed).filter(([key]) => !preferenceMetadata.has(key))))
}
export const discover = Effect.fn("ConfigDiscovery.discover")(function* (options?: Options) {
const fs = yield* FSUtil.Service
const global = yield* Global.Service
const location = yield* Location.Service
const system = (() => {
if (options?.system === false) return
if (typeof options?.system === "string") return AbsolutePath.make(path.resolve(options.system))
return systemDirectory()
})()
const globalDirectory = AbsolutePath.make(global.config)
const globalAgentsDirectory = AbsolutePath.make(path.join(global.home, ".agents"))
const globalClaudeDirectory = AbsolutePath.make(path.join(global.home, ".claude"))
const globalRoots = yield* Effect.forEach([globalDirectory, globalClaudeDirectory, globalAgentsDirectory], (item) =>
fs.resolve(item),
const configDirectories = [...(system ? [system] : []), globalDirectory]
const globalRoots = yield* Effect.forEach(
[...configDirectories, globalClaudeDirectory, globalAgentsDirectory],
(item) => fs.resolve(item),
)
const current = yield* fs.resolve(location.directory)
const directories =
(yield* fs.resolve(location.directory)) === globalRoots[0] || options?.project === false
globalRoots.slice(0, configDirectories.length).includes(current) || options?.project === false
? []
: yield* fs.up({ targets: ["."], start: location.directory }).pipe(Effect.orDie)
const discovered = yield* Effect.forEach(directories, (directory) =>
@@ -50,7 +94,10 @@ export const discover = Effect.fn("ConfigDiscovery.discover")(function* (options
)
const globalEnabled = options?.global !== false
const globalFiles = yield* Effect.forEach(names, (name) => fs.resolve(path.join(globalDirectory, name)))
const globalFiles = yield* Effect.forEach(
configDirectories.flatMap((directory) => names.map((name) => path.join(directory, name))),
(file) => fs.resolve(file),
)
// Global sources must not re-enter through the project walk.
const visible = discovered
.filter(({ resolved }) =>
@@ -60,7 +107,18 @@ export const discover = Effect.fn("ConfigDiscovery.discover")(function* (options
)
.map(({ item }) => item)
// A custom system directory replaces platform discovery, so it also skips host MDM preferences.
const preferences =
globalEnabled && (options?.system ?? true) === true && process.platform === "darwin"
? (yield* Effect.filter(
preferencePaths(yield* Effect.try(() => os.userInfo().username).pipe(Effect.orElseSucceed(() => "user"))),
fs.isFile,
)).at(0)
: undefined
return {
system: globalEnabled && system ? { path: system, present: yield* fs.isDir(system) } : undefined,
preferences,
global: globalEnabled ? globalDirectory : undefined,
explicit: options?.file ? AbsolutePath.make(path.resolve(options.file)) : undefined,
direct: visible.filter((item) => ![".agents", ".claude", ".opencode"].includes(path.basename(item))).toReversed(),
+2
View File
@@ -7,10 +7,12 @@ import type { ConfigDiscovery } from "./discovery.js"
export function plan(sources: ConfigDiscovery.Sources) {
const directories = [
...(sources.system?.present ? [sources.system.path] : []),
...(sources.global ? [sources.global] : []),
...sources.project.filter((root) => root.present).map((root) => root.path),
]
const files = [
...(sources.system ? [sources.system.path] : []),
...sources.direct,
...sources.project.map((root) => root.path),
...sources.claude,
+100 -1
View File
@@ -3,6 +3,7 @@ import fs from "fs/promises"
import { describe, expect, test } from "bun:test"
import { Arbitrary, Effect, Fiber, Layer, Logger, Schema, Stream } from "effect"
import { Config } from "@opencode/core/config"
import { ConfigDiscovery } from "@opencode/core/config/discovery"
import { Directory, Document, type Entry, Event, Info } from "@opencode/schema/config"
import { ConfigModel } from "@opencode/schema/config/model"
import { ConfigProvider } from "@opencode/schema/config/provider"
@@ -64,7 +65,7 @@ function testLayer(
),
)
const built = AppNodeBuilder.build(LayerNode.group([Config.node, Bus.node]), [
Config.node.replace(Config.configured(options)),
Config.node.replace(Config.configured({ system: false, ...options })),
Location.node.replace(locationLayer),
Global.node.replace(Global.layerWith({ config: globalDirectory, home: path.join(globalDirectory, "home") })),
Credential.node.replace(credentialNode),
@@ -201,6 +202,102 @@ describe("Config", () => {
),
)
it.live("loads system configuration at lowest priority", () =>
Effect.acquireDisposable(Effect.promise(() => tmpdir())).pipe(
Effect.flatMap((tmp) => {
const system = path.join(tmp.path, "system")
const global = path.join(tmp.path, "global")
const project = path.join(tmp.path, "project")
return Effect.promise(async () => {
await fs.mkdir(system, { recursive: true })
await fs.mkdir(global, { recursive: true })
await fs.mkdir(project, { recursive: true })
await fs.writeFile(
path.join(system, "opencode.json"),
JSON.stringify({ shell: "system", username: "system-user" }),
)
await fs.writeFile(path.join(global, "opencode.json"), JSON.stringify({ shell: "global" }))
await fs.writeFile(path.join(project, "opencode.json"), JSON.stringify({ shell: "project" }))
}).pipe(
Effect.andThen(
Effect.gen(function* () {
const config = yield* Config.Service
const entries = yield* config.entries()
expect(
entries.flatMap((entry) => (entry.type === "document" && entry.info.shell ? [entry.info.shell] : [])),
).toEqual(["system", "global", "project"])
expect(entries.flatMap((entry) => (entry.type === "directory" ? [entry.path] : []))).toEqual([
AbsolutePath.make(system),
AbsolutePath.make(global),
])
expect(Config.latest(entries, "shell")).toBe("project")
expect(Config.latest(entries, "username")).toBe("system-user")
}).pipe(
Effect.provide(
testLayer(project, global, project, undefined, undefined, emptyCredentialNode, emptyWellknownNode, {
system,
}),
),
),
),
Effect.andThen(
Effect.gen(function* () {
const config = yield* Config.Service
const entries = yield* config.entries()
expect(
entries.flatMap((entry) => (entry.type === "document" && entry.info.shell ? [entry.info.shell] : [])),
).toEqual(["global", "project"])
}).pipe(
Effect.provide(
testLayer(project, global, project, undefined, undefined, emptyCredentialNode, emptyWellknownNode, {
system: false,
}),
),
),
),
)
}),
),
)
test("resolves the system configuration directory per platform", () => {
expect(ConfigDiscovery.systemDirectory("darwin", {})).toBe(
AbsolutePath.make("/Library/Application Support/opencode"),
)
expect(ConfigDiscovery.systemDirectory("linux", {})).toBe(AbsolutePath.make("/etc/opencode"))
expect(ConfigDiscovery.systemDirectory("win32", { ProgramData: "D:\\ProgramData" })).toBe(
AbsolutePath.make(path.join("D:\\ProgramData", "opencode")),
)
expect(ConfigDiscovery.systemDirectory("win32", {})).toBe(
AbsolutePath.make(path.join("C:\\ProgramData", "opencode")),
)
})
test("resolves macOS managed preferences with user-specific profiles first", () => {
expect(ConfigDiscovery.preferencePaths("alice")).toEqual([
AbsolutePath.make(path.join("/Library/Managed Preferences", "alice", "ai.opencode.managed.plist")),
AbsolutePath.make("/Library/Managed Preferences/ai.opencode.managed.plist"),
])
})
test("strips MDM payload metadata from managed preferences", () => {
expect(
JSON.parse(
ConfigDiscovery.stripPreferenceMetadata(
JSON.stringify({
PayloadDisplayName: "OpenCode",
PayloadIdentifier: "ai.opencode.managed",
PayloadType: "ai.opencode.managed",
PayloadUUID: "00000000-0000-0000-0000-000000000000",
PayloadVersion: 1,
_manualProfile: true,
share: "disabled",
}),
),
),
).toEqual({ share: "disabled" })
})
it.live("loads explicit file and content overrides in priority order", () =>
Effect.acquireDisposable(Effect.promise(() => tmpdir())).pipe(
Effect.flatMap((tmp) => {
@@ -395,6 +492,7 @@ describe("Config", () => {
}).pipe(
Effect.provide(
AppNodeBuilder.build(LayerNode.group([Config.node, Bus.node]), [
Config.node.replace(Config.configured({ system: false })),
Location.node.replace(
Layer.succeed(
Location.Service,
@@ -618,6 +716,7 @@ describe("Config", () => {
// Each build is a fresh process sharing one persisted KV store.
const instance = () =>
AppNodeBuilder.build(LayerNode.group([Config.node, Bus.node, WellKnown.node]), [
Config.node.replace(Config.configured({ system: false })),
Location.node.replace(
Layer.succeed(
Location.Service,
+12 -2
View File
@@ -19,10 +19,20 @@ describe("ConfigWatch.plan", () => {
expect(Array.from(missing.values())).toEqual([
{ path: project, type: "entries", names: [".agents", ".claude", ".opencode", "opencode.json", "opencode.jsonc"] },
])
const present = ConfigWatch.plan({ ...sources, project: [{ path: root, present: true }] })
const system = AbsolutePath.make(path.join(project, "system-opencode"))
const present = ConfigWatch.plan({
...sources,
system: { path: system, present: true },
project: [{ path: root, present: true }],
})
expect(Array.from(present.values())).toEqual([
{ path: system, type: "directory", ignore: ["node_modules", ".git", "**/{node_modules,.git}/**"] },
{ path: root, type: "directory", ignore: ["node_modules", ".git", "**/{node_modules,.git}/**"] },
...missing.values(),
{
path: project,
type: "entries",
names: [".agents", ".claude", ".opencode", "opencode.json", "opencode.jsonc", "system-opencode"],
},
])
})
+42 -5
View File
@@ -27,7 +27,40 @@ OpenCode supports JSON and JSONC. Use JSONC when you want comments or trailing c
## Locations
Put settings for every project in the global configuration:
Put machine-wide defaults in the system configuration directory:
| Platform | Directory |
| -------- | --------------------------------------- |
| macOS | `/Library/Application Support/opencode` |
| Linux | `/etc/opencode` |
| Windows | `%ProgramData%\opencode` |
The system directory works like the global directory. Besides
`opencode.json(c)`, it loads `agents/`, `commands/`, `skills/`, and `plugins/`
for every user on the machine:
```text
/etc/opencode/
├── opencode.json
├── agents/review.md
├── commands/release.md
└── skills/deploy/SKILL.md
```
On macOS, OpenCode also reads managed preferences that MDM tools deploy for the
`ai.opencode.managed` domain. A user-specific profile replaces the
machine-wide one:
```text
/Library/Managed Preferences/<user>/ai.opencode.managed.plist
/Library/Managed Preferences/ai.opencode.managed.plist
```
Managed preferences load just below the system directory, so their
[policies](/policies#precedence) have the most authority of any file. OpenCode
reads them at startup and whenever another config change triggers a reload.
Put user settings for every project in the global configuration:
```text
~/.config/opencode/opencode.json(c)
@@ -49,6 +82,7 @@ Use one form throughout a directory tree unless you need that behavior.
For example, start OpenCode from `/home/user/projects/acme/packages/web`:
```text
/etc/opencode/opencode.json
~/.config/opencode/opencode.json
/home/user/projects/acme/
@@ -61,12 +95,15 @@ For example, start OpenCode from `/home/user/projects/acme/packages/web`:
OpenCode applies these files from lowest to highest precedence:
1. `~/.config/opencode/opencode.json`
2. `/home/user/projects/acme/opencode.json`
3. `/home/user/projects/acme/packages/web/opencode.json`
1. `/etc/opencode/opencode.json`
2. `~/.config/opencode/opencode.json`
3. `/home/user/projects/acme/opencode.json`
4. `/home/user/projects/acme/packages/web/opencode.json`
The package config overrides matching settings from the repository config,
which overrides the global config. Settings that do not conflict are preserved.
which overrides the global and system configs. Settings that do not conflict
are preserved, and [policies](/policies#precedence) evaluate in the reverse
order so system policies outrank global and project policies.
## Schema
+12 -1
View File
@@ -48,9 +48,14 @@ This section covers both JSON/JSONC configuration and file-based definitions und
### Use your existing configuration
V2 reads existing global and project configuration from the same locations as V1:
V2 reads existing system, global, and project configuration from the same locations as V1:
```text
/Library/Application Support/opencode/opencode.json(c)
/etc/opencode/opencode.json(c)
%ProgramData%\opencode\opencode.json(c)
/Library/Managed Preferences/<user>/ai.opencode.managed.plist
/Library/Managed Preferences/ai.opencode.managed.plist
~/.config/opencode/opencode.json(c)
<project>/opencode.json(c)
<project>/.opencode/opencode.json(c)
@@ -60,6 +65,12 @@ V2 reads these same locations. It normalizes supported V1 and native V2 fields i
file. Existing supported V1 configuration is intended to keep working, so you do not need to convert it to try or adopt
V2.
In V2, the system configuration directory loads at the lowest precedence for ordinary settings so it provides
machine-wide defaults, while [policies](/policies#precedence) evaluate in the reverse order so system
`experimental.policies` (including migrated `enabled_providers` and `disabled_providers`) cannot be overridden by global
or project files. Express admin-enforced restrictions as `experimental.policies` rather than ordinary settings such as
`permissions`.
### Ask OpenCode to migrate
The V1 config format remains supported. The native V2 format is optional and makes several settings more explicit and
+8 -6
View File
@@ -157,12 +157,14 @@ broader `deny`, after which the agent's own rules decide.
Ordinary settings let the nearest configuration win. Policies reverse that: statements
from broader configuration are evaluated later, so they override narrower ones.
| Authority | Source |
| ----------- | --------------------------------------------------------------- |
| 1 (highest) | Connected OpenCode Console workspace |
| 2 | Global `~/.config/opencode/opencode.json(c)` |
| 3 | Direct `opencode.json(c)`; outer directories beat inner ones |
| 4 (lowest) | `.opencode/opencode.json(c)`; outer directories beat inner ones |
| Authority | Source |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| 1 (highest) | Connected OpenCode Console workspace |
| 2 | macOS managed preferences (`/Library/Managed Preferences/ai.opencode.managed.plist`) |
| 3 | System `opencode.json(c)` (`/Library/Application Support/opencode`, `/etc/opencode`, `%ProgramData%\opencode`) |
| 4 | Global `~/.config/opencode/opencode.json(c)` |
| 5 | Direct `opencode.json(c)`; outer directories beat inner ones |
| 6 (lowest) | `.opencode/opencode.json(c)`; outer directories beat inner ones |
A repository cannot re-enable a provider you deny globally: