@openchambery/web 2.0.0-beta.25 → 2.0.0-beta.29

package/server/lib/opencode/config-entities-layering.test.js

@@ -0,0 +1,72 @@
+import { beforeEach, afterEach, describe, it, expect, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readConfigFile } from './config-files.js';
+
+let root;
+let directory;
+let mcp;
+let agents;
+let providers;
+let plugins;
+beforeEach(async () => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-entity-layers-'));
+  directory = path.join(root, 'xdg', 'opencode');
+  fs.mkdirSync(directory, { recursive: true });
+  vi.stubEnv('XDG_CONFIG_HOME', path.dirname(directory));
+  vi.stubEnv('OPENCODE_CONFIG', '');
+  vi.stubEnv('OPENCODE_CONFIG_DIR', '');
+  vi.spyOn(os, 'homedir').mockReturnValue(root);
+  vi.resetModules();
+  [mcp, agents, providers, plugins] = await Promise.all([import('./mcp.js'), import('./agents.js'), import('./providers.js'), import('./plugins.js')]);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('Web/Electron entity physical provenance', () => {
+  it('MCP CRUD edits only the source document and preserves comments', () => {
+    const json = path.join(directory, 'opencode.json');
+    const jsonc = path.join(directory, 'opencode.jsonc');
+    fs.writeFileSync(json, '{"mcp":{"lower":{"type":"local","command":["lower"]}}}');
+    fs.writeFileSync(jsonc, '{ // retained\n"mcp":{"higher":{"type":"local","command":["higher"]}}}');
+    expect(mcp.listMcpConfigs().map((entry) => entry.name).sort()).toEqual(['higher', 'lower']);
+    mcp.updateMcpConfig('lower', { enabled: false });
+    expect(readConfigFile(json)).toMatchObject({ mcp: { lower: { enabled: false } } });
+    mcp.createMcpConfig('new', { type: 'local', command: ['new'] });
+    expect(readConfigFile(jsonc).mcp.lower).toBeUndefined();
+    mcp.deleteMcpConfig('higher');
+    expect(readConfigFile(jsonc).mcp.higher).toBeUndefined();
+    expect(fs.readFileSync(jsonc, 'utf8')).toContain('// retained');
+  });
+
+  it('agent and provider metadata point to physical layers, including scoped deletion', () => {
+    const json = path.join(directory, 'opencode.json');
+    const jsonc = path.join(directory, 'opencode.jsonc');
+    fs.writeFileSync(json, '{"agent":{"lower":{"description":"lower"}},"provider":{"lower":{}}}');
+    fs.writeFileSync(jsonc, '{ // retained\n"agent":{"higher":{"description":"higher"}},"provider":{"higher":{}}}');
+    expect(agents.getAgentSources('lower').json.path).toBe(json);
+    expect(agents.getAgentSources('higher').json.path).toBe(jsonc);
+    agents.deleteAgent('lower', undefined, 'user');
+    expect(readConfigFile(json).agent).toBeUndefined();
+    expect(readConfigFile(jsonc).agent.higher).toBeDefined();
+    expect(providers.getProviderSources('lower').sources.user.path).toBe(json);
+    providers.removeProviderConfig('lower');
+    expect(readConfigFile(json).provider).toBeUndefined();
+    expect(readConfigFile(jsonc).provider.higher).toBeDefined();
+  });
+
+  it('plugin edits locate the source containing the requested spec', () => {
+    const json = path.join(directory, 'opencode.json');
+    const jsonc = path.join(directory, 'opencode.jsonc');
+    fs.writeFileSync(json, '{"plugin":["lower-plugin"]}');
+    fs.writeFileSync(jsonc, '{ // retained\n"plugin":["higher-plugin"]}');
+    const entry = plugins.listPluginEntries().find((item) => item.spec === 'lower-plugin');
+    plugins.updatePluginEntry(entry.id, { spec: 'updated-plugin' });
+    expect(readConfigFile(json).plugin).toEqual(['updated-plugin']);
+    expect(readConfigFile(jsonc).plugin).toEqual(['higher-plugin']);
+  });
+});

package/server/lib/opencode/config-entity-routes.js

@@ -1,9 +1,9 @@
 import fs from 'node:fs/promises';
-import os from 'node:os';
 import path from 'node:path';
 import { parse as parseJsonc } from 'jsonc-parser';
 import { OpenCode } from '@opencode/client';
 import { projectProviderCatalog } from './provider-catalog.js';
+import { getGlobalConfigDirectory, writeConfigText } from './config-files.js';
 
 // Compose official v2 provider.list + model.list (+ optional default) into the
 // catalog shape consumed by projectProviderCatalog. Missing arrays are failure.
@@ -60,7 +60,7 @@ const createOpenCodeClient = ({ baseUrl, headers, fetch: fetchImpl }) =>
 
 const MAX_GLOBAL_CONFIG_SIZE = 2 * 1024 * 1024;
 const GLOBAL_CONFIG_FILES = {
-  opencode: ['opencode.json', 'opencode.jsonc'],
+  opencode: ['opencode.jsonc', 'opencode.json'],
   'oh-my-opencode-slim': ['oh-my-opencode-slim.json', 'oh-my-opencode-slim.jsonc'],
   'oh-my-openagent': ['oh-my-openagent.json', 'oh-my-openagent.jsonc'],
 };
@@ -84,6 +84,10 @@ function resolveGlobalConfigPath(target, configDirectory) {
   if (!fileNames) {
     return null;
   }
+  if (target === 'opencode' && process.env.OPENCODE_CONFIG) {
+    const filePath = path.resolve(process.env.OPENCODE_CONFIG);
+    return { target, fileNames: [path.basename(filePath)], fileName: path.basename(filePath), filePath };
+  }
   return {
     target,
     fileNames,
@@ -99,7 +103,7 @@ async function findGlobalConfigPath(target, configDirectory) {
   }
 
   for (const fileName of configPath.fileNames) {
-    const filePath = path.join(configDirectory, fileName);
+    const filePath = path.join(path.dirname(configPath.filePath), fileName);
     try {
       if ((await fs.stat(filePath)).isFile()) {
         return { ...configPath, fileName, filePath };
@@ -153,13 +157,7 @@ export const registerConfigEntityRoutes = (app, dependencies) => {
     createMcpConfig,
     updateMcpConfig,
     deleteMcpConfig,
-    listSnippets,
-    getSnippet,
-    createSnippet,
-    updateSnippet,
-    deleteSnippet,
-    expandSnippets,
-    configDirectory = path.join(os.homedir(), '.config', 'opencode'),
+    configDirectory = getGlobalConfigDirectory(),
   } = dependencies;
 
   app.get('/api/config/catalog/providers', async (req, res) => {
@@ -254,10 +252,7 @@ export const registerConfigEntityRoutes = (app, dependencies) => {
     }
 
     try {
-      await fs.mkdir(configDirectory, { recursive: true });
-      const temporaryPath = `${target.filePath}.${process.pid}.${Date.now()}.tmp`;
-      await fs.writeFile(temporaryPath, content, 'utf8');
-      await fs.rename(temporaryPath, target.filePath);
+      writeConfigText(content, target.filePath);
       return res.json({
         target: req.params.target,
         fileName: target.fileName,
@@ -679,112 +674,4 @@ export const registerConfigEntityRoutes = (app, dependencies) => {
     }
   });
 
-  app.get('/api/config/snippets', async (req, res) => {
-    try {
-      const { directory, error } = await resolveOptionalProjectDirectory(req);
-      if (error) {
-        return res.status(400).json({ error });
-      }
-      res.json(listSnippets(directory));
-    } catch (error) {
-      console.error('[API:GET /api/config/snippets] Failed:', error);
-      res.status(500).json({ error: error.message || 'Failed to list snippets' });
-    }
-  });
-
-  app.post('/api/config/snippets/expand', async (req, res) => {
-    try {
-      const { directory, error } = await resolveOptionalProjectDirectory(req);
-      if (error) {
-        return res.status(400).json({ error });
-      }
-      res.json({ text: expandSnippets(req.body?.text ?? '', directory) });
-    } catch (error) {
-      console.error('[API:POST /api/config/snippets/expand] Failed:', error);
-      res.status(500).json({ error: error.message || 'Failed to expand snippets' });
-    }
-  });
-
-  app.get('/api/config/snippets/:name', async (req, res) => {
-    try {
-      const name = req.params.name;
-      const { directory, error } = await resolveOptionalProjectDirectory(req);
-      if (error) {
-        return res.status(400).json({ error });
-      }
-      const snippet = getSnippet(name, directory);
-      if (!snippet) {
-        return res.status(404).json({ error: `Snippet "${name}" not found` });
-      }
-      res.json(snippet);
-    } catch (error) {
-      console.error('[API:GET /api/config/snippets/:name] Failed:', error);
-      if (error.message?.includes('Snippet name')) {
-        return res.status(400).json({ error: error.message });
-      }
-      res.status(500).json({ error: error.message || 'Failed to get snippet' });
-    }
-  });
-
-  app.post('/api/config/snippets/:name', async (req, res) => {
-    try {
-      const name = req.params.name;
-      const { directory, error } = await resolveOptionalProjectDirectory(req);
-      if (error) {
-        return res.status(400).json({ error });
-      }
-      const snippet = createSnippet(name, req.body || {}, directory, req.body?.scope || 'global');
-      res.json({ success: true, snippet });
-    } catch (error) {
-      console.error('[API:POST /api/config/snippets/:name] Failed:', error);
-      if (error.message?.includes('already exists')) {
-        return res.status(409).json({ error: error.message });
-      }
-      if (error.message?.includes('Snippet name') || error.message?.includes('Project directory')) {
-        return res.status(400).json({ error: error.message });
-      }
-      res.status(500).json({ error: error.message || 'Failed to create snippet' });
-    }
-  });
-
-  app.patch('/api/config/snippets/:name', async (req, res) => {
-    try {
-      const name = req.params.name;
-      const { directory, error } = await resolveOptionalProjectDirectory(req);
-      if (error) {
-        return res.status(400).json({ error });
-      }
-      res.json({ success: true, snippet: updateSnippet(name, req.body || {}, directory) });
-    } catch (error) {
-      console.error('[API:PATCH /api/config/snippets/:name] Failed:', error);
-      if (error.message?.includes('not found')) {
-        return res.status(404).json({ error: error.message });
-      }
-      if (error.message?.includes('Snippet name')) {
-        return res.status(400).json({ error: error.message });
-      }
-      res.status(500).json({ error: error.message || 'Failed to update snippet' });
-    }
-  });
-
-  app.delete('/api/config/snippets/:name', async (req, res) => {
-    try {
-      const name = req.params.name;
-      const { directory, error } = await resolveOptionalProjectDirectory(req);
-      if (error) {
-        return res.status(400).json({ error });
-      }
-      deleteSnippet(name, directory);
-      res.json({ success: true });
-    } catch (error) {
-      console.error('[API:DELETE /api/config/snippets/:name] Failed:', error);
-      if (error.message?.includes('not found')) {
-        return res.status(404).json({ error: error.message });
-      }
-      if (error.message?.includes('Snippet name')) {
-        return res.status(400).json({ error: error.message });
-      }
-      res.status(500).json({ error: error.message || 'Failed to delete snippet' });
-    }
-  });
 };

package/server/lib/opencode/config-entity-routes.test.js

@@ -38,12 +38,6 @@ const createDependencies = (getCommandSources, configDirectory, getAgentSources
   createMcpConfig: vi.fn(),
   updateMcpConfig: vi.fn(),
   deleteMcpConfig: vi.fn(),
-  listSnippets: vi.fn(),
-  getSnippet: vi.fn(),
-  createSnippet: vi.fn(),
-  updateSnippet: vi.fn(),
-  deleteSnippet: vi.fn(),
-  expandSnippets: vi.fn(),
   configDirectory,
   buildOpenCodeUrl: () => 'http://opencode-upstream:4096/',
   getOpenCodeAuthHeaders: () => ({ Authorization: 'Basic example' }),
@@ -459,6 +453,8 @@ describe('config entity agent metadata route', () => {
 });
 
 describe('global raw configuration routes', () => {
+  beforeEach(() => vi.stubEnv('OPENCODE_CONFIG', ''));
+  afterEach(() => vi.unstubAllEnvs());
   it('reads and validates the configured OpenCode and oh-my-opencode files', async () => {
     const app = express();
     app.use(express.json());
@@ -503,7 +499,7 @@ describe('global raw configuration routes', () => {
     await fs.rm(configDirectory, { recursive: true, force: true });
   });
 
-  it('discovers only existing configuration targets and prefers JSON files', async () => {
+  it('discovers only existing targets and edits the winning global JSONC document', async () => {
     const app = express();
     app.use(express.json());
     const configDirectory = await fs.mkdtemp(path.join(os.tmpdir(), 'openchamber-global-config-'));
@@ -516,20 +512,20 @@ describe('global raw configuration routes', () => {
     const available = await request(app).get('/api/config/global').expect(200);
     expect(available.body).toEqual({
       targets: [
-        { target: 'opencode', fileName: 'opencode.json' },
+        { target: 'opencode', fileName: 'opencode.jsonc' },
         { target: 'oh-my-openagent', fileName: 'oh-my-openagent.jsonc' },
       ],
     });
 
     const openCode = await request(app).get('/api/config/global/opencode').expect(200);
-    expect(openCode.body).toMatchObject({ fileName: 'opencode.json', content: '{ "model": "json-model" }' });
+    expect(openCode.body).toMatchObject({ fileName: 'opencode.jsonc', content: '{ "model": "jsonc-model" }' });
 
     await request(app)
       .put('/api/config/global/opencode')
       .send({ content: '{ "model": "updated-json-model" }' })
       .expect(200);
-    expect(await fs.readFile(path.join(configDirectory, 'opencode.json'), 'utf8')).toContain('updated-json-model');
-    expect(await fs.readFile(path.join(configDirectory, 'opencode.jsonc'), 'utf8')).toContain('jsonc-model');
+    expect(await fs.readFile(path.join(configDirectory, 'opencode.json'), 'utf8')).toContain('json-model');
+    expect(await fs.readFile(path.join(configDirectory, 'opencode.jsonc'), 'utf8')).toContain('updated-json-model');
 
     await fs.rm(configDirectory, { recursive: true, force: true });
   });

package/server/lib/opencode/config-files.d.ts

@@ -0,0 +1,17 @@
+export type ConfigObject = Record<string, unknown>;
+export type ConfigDocument = { path: string; scope: 'user' | 'project' | 'custom'; config: ConfigObject };
+export type ConfigLayers = {
+  userConfig: ConfigObject; projectConfig: ConfigObject; customConfig: ConfigObject; mergedConfig: ConfigObject;
+  userLayers: ConfigDocument[]; projectLayers: ConfigDocument[]; documents: ConfigDocument[];
+  paths: { userPath: string; projectPath: string | null; customPath: string | null };
+};
+export function getGlobalConfigDirectory(): string;
+export function isPlainObject(value: unknown): value is ConfigObject;
+export function readConfigFile(filePath?: string | null): ConfigObject;
+export function readConfigLayers(workingDirectory?: string): ConfigLayers;
+export function readConfig(workingDirectory?: string): ConfigObject;
+export function getConfigForPath(layers: ConfigLayers, targetPath?: string | null): ConfigObject;
+export function getJsonEntrySource(layers: ConfigLayers, sectionKey: string, entryName: string): { section: unknown; config: ConfigObject | null; path: string | null; exists: boolean };
+export function getJsonWriteTarget(layers: ConfigLayers, preferredScope: string): { config: ConfigObject; path: string };
+export function writeConfig(config: ConfigObject, filePath?: string): void;
+export function writeConfigText(content: string, filePath: string): void;

package/server/lib/opencode/config-files.js

@@ -0,0 +1,187 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { parse, parseTree, findNodeAtLocation, createScanner, SyntaxKind, modify, applyEdits } from 'jsonc-parser';
+
+export const getGlobalConfigDirectory = () => process.env.OPENCODE_CONFIG_DIR
+  ? path.resolve(process.env.OPENCODE_CONFIG_DIR)
+  : path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'opencode');
+export const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+function parseConfigObject(content, filePath) {
+  const errors = [];
+  const value = parse(content.replace(/^\uFEFF/, ''), errors, { allowTrailingComma: true, allowEmptyContent: true });
+  if (errors.length || (value !== undefined && !isPlainObject(value))) {
+    throw Object.assign(new Error(`Invalid JSONC configuration: ${filePath}`), { code: 'INVALID_JSONC' });
+  }
+  return value ?? {};
+}
+
+function readText(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function readConfigFile(filePath) {
+  if (!filePath) return {};
+  const text = readText(filePath);
+  return text === null ? {} : parseConfigObject(text, filePath);
+}
+
+function mergeConfigs(base, override) {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    Object.defineProperty(result, key, {
+      value: isPlainObject(result[key]) && isPlainObject(value) ? mergeConfigs(result[key], value) : value,
+      enumerable: true, configurable: true, writable: true,
+    });
+  }
+  return result;
+}
+
+const names = ['opencode.json', 'opencode.jsonc'];
+
+export function readConfigLayers(workingDirectory) {
+  const directory = getGlobalConfigDirectory();
+  const userPaths = names.map((name) => path.join(directory, name));
+  const customPath = process.env.OPENCODE_CONFIG ? path.resolve(process.env.OPENCODE_CONFIG) : null;
+  const ancestors = [];
+  if (workingDirectory && path.resolve(workingDirectory) !== path.resolve(directory)) {
+    let current = path.resolve(workingDirectory);
+    while (true) {
+      ancestors.unshift(current);
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  const projectPaths = [
+    ...ancestors.flatMap((dir) => names.map((name) => path.join(dir, name))),
+    ...ancestors.flatMap((dir) => names.map((name) => path.join(dir, '.opencode', name))),
+  ].filter((filePath) => !userPaths.includes(filePath));
+  const load = (paths, scope) => paths.flatMap((filePath) => {
+    const text = readText(filePath);
+    return text === null ? [] : [{ path: filePath, scope, config: parseConfigObject(text, filePath) }];
+  });
+  const userLayers = load(userPaths, 'user');
+  const projectLayers = load(projectPaths, 'project');
+  const customConfig = readConfigFile(customPath);
+  const documents = [...userLayers, ...(customPath ? [{ path: customPath, scope: 'custom', config: customConfig }] : []), ...projectLayers];
+  const merge = (layers) => layers.reduce((config, layer) => mergeConfigs(config, layer.config), {});
+  return {
+    userConfig: merge(userLayers), projectConfig: merge(projectLayers), customConfig,
+    mergedConfig: merge(documents), userLayers, projectLayers, documents,
+    paths: {
+      userPath: userLayers.at(-1)?.path ?? path.join(directory, 'opencode.jsonc'),
+      projectPath: projectLayers.at(-1)?.path ?? (workingDirectory ? path.join(workingDirectory, '.opencode', 'opencode.jsonc') : null),
+      customPath,
+    },
+  };
+}
+
+export const readConfig = (workingDirectory) => readConfigLayers(workingDirectory).mergedConfig;
+
+export function getConfigForPath(layers, targetPath) {
+  const filePath = targetPath || layers.paths.userPath;
+  return layers.documents.findLast((layer) => layer.path === filePath)?.config ?? readConfigFile(filePath);
+}
+
+export function getJsonEntrySource(layers, sectionKey, entryName) {
+  for (const layer of layers.documents.toReversed()) {
+    const section = layer.config?.[sectionKey]?.[entryName];
+    if (section !== undefined) return { section, config: layer.config, path: layer.path, exists: true };
+  }
+  return { section: null, config: null, path: null, exists: false };
+}
+
+export function getJsonWriteTarget(layers, preferredScope) {
+  const filePath = preferredScope === 'project' && layers.paths.projectPath
+    ? layers.paths.projectPath : layers.paths.customPath || layers.paths.userPath;
+  return { config: getConfigForPath(layers, filePath), path: filePath };
+}
+
+function removalEdits(text, propertyPath) {
+  const node = findNodeAtLocation(parseTree(text), propertyPath)?.parent;
+  const parent = node?.parent;
+  if (!node || parent?.type !== 'object') throw new Error('Cannot locate configuration property');
+  const siblings = parent.children;
+  const index = siblings.indexOf(node);
+  const end = node.offset + node.length;
+  const scanner = createScanner(text, true);
+  const comma = (start, stop) => {
+    scanner.setPosition(start);
+    return scanner.scan() === SyntaxKind.CommaToken && scanner.getTokenOffset() < stop ? scanner.getTokenOffset() : -1;
+  };
+  let separator = comma(end, siblings[index + 1]?.offset ?? parent.offset + parent.length - 1);
+  if (separator < 0) {
+    const previous = siblings[index - 1];
+    separator = comma(previous ? previous.offset + previous.length : parent.offset + 1, node.offset);
+  }
+  return [{ offset: node.offset, length: node.length, content: '' }, ...(separator < 0 ? [] : [{ offset: separator, length: 1, content: '' }])];
+}
+
+function editConfig(existing, desired, filePath) {
+  const current = parseConfigObject(existing, filePath);
+  const bom = existing.startsWith('\uFEFF') ? '\uFEFF' : '';
+  let text = existing.slice(bom.length);
+  if (!parseTree(text)) return `${existing}${existing && !existing.endsWith('\n') ? '\n' : ''}${JSON.stringify(desired, null, 2)}\n`;
+  const indentation = text.match(/\n([\t ]+)"/)?.[1] ?? '  ';
+  const formattingOptions = { insertSpaces: !indentation.includes('\t'), tabSize: indentation.length, eol: text.includes('\r\n') ? '\r\n' : '\n' };
+  const visit = (before, after, keys) => {
+    if (isDeepStrictEqual(before, after)) return;
+    if (isPlainObject(before) && isPlainObject(after)) {
+      for (const key of Object.keys(before)) {
+        if (!Object.hasOwn(after, key)) text = applyEdits(text, removalEdits(text, [...keys, key]));
+      }
+      for (const key of Object.keys(after)) visit(before[key], after[key], [...keys, key]);
+    } else {
+      text = applyEdits(text, modify(text, keys, after, { formattingOptions }));
+    }
+  };
+  visit(current, desired, []);
+  if (!isDeepStrictEqual(parseConfigObject(text, filePath), desired)) throw new Error('Configuration edit did not round-trip');
+  return bom + text;
+}
+
+// Shared by structured entity edits and the raw editor; failure never truncates the original.
+export function writeConfigText(content, filePath) {
+  parseConfigObject(content, filePath);
+  let exists = false;
+  try {
+    fs.lstatSync(filePath);
+    exists = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  // Resolve before staging: rename must replace the dotfile target, not its link.
+  // lstat distinguishes new files from dangling links, whose realpath must fail.
+  const targetPath = exists ? fs.realpathSync(filePath) : filePath;
+  const original = readText(targetPath);
+  if (original !== null) parseConfigObject(original, filePath);
+  if (content === original) return;
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  const temporaryPath = `${targetPath}.${randomUUID()}.tmp`;
+  try {
+    const mode = original === null ? 0o600 : fs.statSync(targetPath).mode & 0o777;
+    fs.writeFileSync(temporaryPath, content, { encoding: 'utf8', flag: 'wx', mode });
+    if (original !== null) {
+      fs.chmodSync(temporaryPath, mode);
+      fs.copyFileSync(targetPath, `${filePath}.openchamber.backup`);
+    }
+    fs.renameSync(temporaryPath, targetPath);
+  } finally {
+    fs.rmSync(temporaryPath, { force: true });
+  }
+}
+
+export function writeConfig(config, filePath = path.join(getGlobalConfigDirectory(), 'opencode.jsonc')) {
+  const desired = JSON.parse(JSON.stringify(config));
+  if (!isPlainObject(desired)) throw new Error('Configuration must be an object');
+  writeConfigText(editConfig(readText(filePath) ?? '', desired, filePath), filePath);
+}