@openchamber/web 1.11.5 → 1.11.6

package/server/lib/opencode/plugins.js

@@ -0,0 +1,393 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+  AGENT_SCOPE,
+  readConfigFile,
+  writeConfig,
+} from './shared.js';
+import { isPathSpec } from './plugin-spec.js';
+
+const PLUGIN_FILE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_.]*\.(js|ts|mjs|cjs)$/;
+
+/**
+ * @typedef {'user' | 'project'} PluginScope
+ * @typedef {'npm' | 'path'} PluginParsedKind
+ * @typedef {Object} PluginEntry
+ * @property {string} id base64url encoded "config:scope:spec"
+ * @property {string} spec
+ * @property {Record<string, unknown>} [options]
+ * @property {PluginScope} scope
+ * @property {'config'} kind
+ * @property {PluginParsedKind} parsedKind
+ * @property {string} sourcePath absolute path to the config file
+ * @typedef {Object} PluginFile
+ * @property {string} id base64url encoded "file:scope:fileName"
+ * @property {string} fileName
+ * @property {PluginScope} scope
+ * @property {'file'} kind
+ * @property {string} absolutePath
+ */
+
+function codedError(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function validateScope(scope) {
+  if (scope !== AGENT_SCOPE.USER && scope !== AGENT_SCOPE.PROJECT) {
+    throw codedError('Plugin scope must be user or project', 'INVALID_SCOPE');
+  }
+}
+
+function validatePluginSpec(spec) {
+  if (typeof spec !== 'string' || !spec.trim()) {
+    throw codedError('Plugin spec must be a non-empty string', 'INVALID_SPEC');
+  }
+  if (spec.includes('\0')) {
+    throw codedError('Plugin spec cannot contain null bytes', 'INVALID_SPEC');
+  }
+  return spec.trim();
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasOptions(options) {
+  return isRecord(options) && Object.keys(options).length > 0;
+}
+
+function parsedKindForSpec(spec) {
+  // Path indicators must include Windows paths; scoped npm packages also contain '/'.
+  // Do NOT use `includes(path.sep)` — scoped npm packages legitimately contain '/' (e.g. `@gitlab/opencode-gitlab-auth`).
+  return isPathSpec(spec) ? 'path' : 'npm';
+}
+
+function getActiveOpencodeConfigDir() {
+  const customConfigPath = process.env.OPENCODE_CONFIG;
+  if (customConfigPath) {
+    return path.dirname(path.resolve(customConfigPath));
+  }
+  return path.join(os.homedir(), '.config', 'opencode');
+}
+
+function getActiveUserConfigPaths() {
+  const configDir = getActiveOpencodeConfigDir();
+  return [
+    path.join(configDir, 'config.json'),
+    path.join(configDir, 'opencode.json'),
+    path.join(configDir, 'opencode.jsonc'),
+  ];
+}
+
+function getActiveCustomConfigPath() {
+  return process.env.OPENCODE_CONFIG ? path.resolve(process.env.OPENCODE_CONFIG) : null;
+}
+
+function getPrimaryUserConfigPath() {
+  const [defaultPath, ...fallbackPaths] = getActiveUserConfigPaths();
+  for (const userPath of [defaultPath, ...fallbackPaths]) {
+    if (fs.existsSync(userPath)) {
+      return userPath;
+    }
+  }
+  return defaultPath;
+}
+
+function getProjectConfigPath(workingDirectory) {
+  if (!workingDirectory) return null;
+  const candidates = [
+    path.join(workingDirectory, 'opencode.json'),
+    path.join(workingDirectory, 'opencode.jsonc'),
+    path.join(workingDirectory, '.opencode', 'opencode.json'),
+    path.join(workingDirectory, '.opencode', 'opencode.jsonc'),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
+}
+
+function readPluginConfigLayers(workingDirectory) {
+  const customPath = getActiveCustomConfigPath();
+  const userPath = getPrimaryUserConfigPath();
+  const projectPath = getProjectConfigPath(workingDirectory);
+  return {
+    userConfig: readConfigFile(userPath),
+    projectConfig: readConfigFile(projectPath),
+    customConfig: readConfigFile(customPath),
+    paths: {
+      userPath,
+      projectPath,
+      customPath,
+    },
+  };
+}
+
+function validateFileName(fileName) {
+  if (typeof fileName !== 'string' || !fileName) {
+    throw codedError('Plugin file name is required', 'INVALID_FILENAME');
+  }
+  if (fileName.includes('/') || fileName.includes('\\') || fileName.includes('..') || !PLUGIN_FILE_NAME_PATTERN.test(fileName)) {
+    throw codedError('Plugin file name must match /^[a-z0-9][a-z0-9-_.]*\\.(js|ts|mjs|cjs)$/ and cannot contain path traversal', 'INVALID_FILENAME');
+  }
+  return fileName;
+}
+
+function ensureProjectConfigPath(workingDirectory) {
+  if (!workingDirectory) {
+    throw codedError('Project scope requires working directory', 'INVALID_SCOPE');
+  }
+  const configDir = path.join(workingDirectory, '.opencode');
+  fs.mkdirSync(configDir, { recursive: true });
+  return path.join(configDir, 'opencode.json');
+}
+
+function configSources(layers) {
+  const sources = [];
+  if (layers.paths.customPath) {
+    sources.push({ config: layers.customConfig, filePath: layers.paths.customPath, scope: AGENT_SCOPE.USER });
+  } else {
+    sources.push({ config: layers.userConfig, filePath: layers.paths.userPath, scope: AGENT_SCOPE.USER });
+  }
+  if (layers.paths.projectPath) {
+    sources.push({ config: layers.projectConfig, filePath: layers.paths.projectPath, scope: AGENT_SCOPE.PROJECT });
+  }
+  return sources;
+}
+
+function splitScopedValue(value) {
+  const separator = value.indexOf(':');
+  if (separator === -1) {
+    throw codedError('Plugin id value must include scope', 'INVALID_SPEC');
+  }
+  return {
+    scope: value.slice(0, separator),
+    value: value.slice(separator + 1),
+  };
+}
+
+function getPluginTarget(id, workingDirectory) {
+  const decoded = decodePluginId(id);
+  if (decoded.prefix !== 'config') {
+    throw codedError('Plugin entry id must use config prefix', 'INVALID_SPEC');
+  }
+  const { scope, value: spec } = splitScopedValue(decoded.value);
+  validateScope(scope);
+  const layers = readPluginConfigLayers(workingDirectory);
+  const source = configSources(layers).find((candidate) => candidate.scope === scope);
+  const plugin = Array.isArray(source?.config?.plugin) ? source.config.plugin : [];
+  const index = plugin.findIndex((raw) => parsePluginRaw(raw).spec === spec);
+  if (!source || index === -1) {
+    return null;
+  }
+  return { source, plugin, index };
+}
+
+function pluginDirForScope(scope, workingDirectory) {
+  validateScope(scope);
+  if (scope === AGENT_SCOPE.PROJECT) {
+    if (!workingDirectory) {
+      throw codedError('Project scope requires working directory', 'INVALID_SCOPE');
+    }
+    return path.join(workingDirectory, '.opencode', 'plugins');
+  }
+  return path.join(getActiveOpencodeConfigDir(), 'plugins');
+}
+
+function fileTargetFromId(id, workingDirectory) {
+  const decoded = decodePluginId(id);
+  if (decoded.prefix !== 'file') {
+    throw codedError('Plugin file id must use file prefix', 'INVALID_FILENAME');
+  }
+  const { scope, value: fileName } = splitScopedValue(decoded.value);
+  validateScope(scope);
+  validateFileName(fileName);
+  return {
+    fileName,
+    scope,
+    absolutePath: path.join(pluginDirForScope(scope, workingDirectory), fileName),
+  };
+}
+
+function encodePluginId(prefix, value) {
+  return Buffer.from(`${prefix}:${value}`).toString('base64url');
+}
+
+function decodePluginId(id) {
+  const decoded = Buffer.from(id, 'base64url').toString('utf8');
+  const separator = decoded.indexOf(':');
+  if (separator === -1) {
+    throw codedError('Invalid plugin id', 'INVALID_SPEC');
+  }
+  return { prefix: decoded.slice(0, separator), value: decoded.slice(separator + 1) };
+}
+
+function parsePluginRaw(raw) {
+  if (typeof raw === 'string') {
+    return { spec: validatePluginSpec(raw) };
+  }
+  if (Array.isArray(raw) && raw.length === 2 && isRecord(raw[1])) {
+    return { spec: validatePluginSpec(raw[0]), options: { ...raw[1] } };
+  }
+  throw codedError('Plugin spec must be a string or [string, object]', 'INVALID_SPEC');
+}
+
+function serializePluginEntry(entry) {
+  const spec = validatePluginSpec(entry?.spec);
+  if (hasOptions(entry?.options)) {
+    return [spec, { ...entry.options }];
+  }
+  return spec;
+}
+
+function listPluginEntries(workingDirectory) {
+  const layers = readPluginConfigLayers(workingDirectory);
+  return configSources(layers).flatMap((source) => {
+    if (!Array.isArray(source.config?.plugin)) {
+      return [];
+    }
+    return source.config.plugin.map((raw) => {
+      const parsed = parsePluginRaw(raw);
+      return {
+        id: encodePluginId('config', `${source.scope}:${parsed.spec}`),
+        spec: parsed.spec,
+        ...(parsed.options !== undefined ? { options: parsed.options } : {}),
+        scope: source.scope,
+        kind: 'config',
+        parsedKind: parsedKindForSpec(parsed.spec),
+        sourcePath: source.filePath,
+      };
+    });
+  });
+}
+
+function getPluginEntry(id, workingDirectory) {
+  return listPluginEntries(workingDirectory).find((entry) => entry.id === id) || null;
+}
+
+function createPluginEntry(entry, workingDirectory) {
+  const spec = validatePluginSpec(entry?.spec);
+  const scope = entry?.scope || AGENT_SCOPE.USER;
+  validateScope(scope);
+
+  const layers = readPluginConfigLayers(workingDirectory);
+  const existing = configSources(layers).find((source) => (
+    source.scope === scope
+    && Array.isArray(source.config?.plugin)
+    && source.config.plugin.some((raw) => parsePluginRaw(raw).spec === spec)
+  ));
+  if (existing) {
+    throw codedError(`Plugin "${spec}" already exists`, 'ENTRY_EXISTS');
+  }
+
+  let targetPath = getPrimaryUserConfigPath();
+  let config = {};
+  if (scope === AGENT_SCOPE.PROJECT) {
+    targetPath = ensureProjectConfigPath(workingDirectory);
+    config = fs.existsSync(targetPath) ? readConfigFile(targetPath) : {};
+  } else {
+    targetPath = layers.paths.customPath || layers.paths.userPath;
+    config = layers.paths.customPath ? layers.customConfig : layers.userConfig;
+  }
+
+  if (!Array.isArray(config.plugin)) {
+    config.plugin = [];
+  }
+  config.plugin.push(serializePluginEntry({ spec, options: entry.options }));
+  writeConfig(config, targetPath);
+}
+
+function updatePluginEntry(id, updates, workingDirectory) {
+  const target = getPluginTarget(id, workingDirectory);
+  if (!target) {
+    throw codedError('Plugin entry not found', 'NOT_FOUND');
+  }
+  const existing = parsePluginRaw(target.plugin[target.index]);
+  const nextSpec = updates?.spec === undefined ? existing.spec : validatePluginSpec(updates.spec);
+  const nextOptions = updates?.options === undefined ? existing.options : updates.options;
+  target.plugin[target.index] = serializePluginEntry({ spec: nextSpec, options: nextOptions });
+  writeConfig(target.source.config, target.source.filePath);
+}
+
+function deletePluginEntry(id, workingDirectory) {
+  const target = getPluginTarget(id, workingDirectory);
+  if (!target) {
+    throw codedError('Plugin entry not found', 'NOT_FOUND');
+  }
+  target.plugin.splice(target.index, 1);
+  if (target.plugin.length === 0) {
+    delete target.source.config.plugin;
+  }
+  writeConfig(target.source.config, target.source.filePath);
+}
+
+function listPluginDirFiles(workingDirectory) {
+  const scopes = [AGENT_SCOPE.USER];
+  if (workingDirectory) {
+    scopes.push(AGENT_SCOPE.PROJECT);
+  }
+  return scopes.flatMap((scope) => {
+    const dir = pluginDirForScope(scope, workingDirectory);
+    if (!fs.existsSync(dir)) {
+      return [];
+    }
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && PLUGIN_FILE_NAME_PATTERN.test(entry.name) && !entry.name.includes('..'))
+      .map((entry) => ({
+        id: encodePluginId('file', `${scope}:${entry.name}`),
+        fileName: entry.name,
+        scope,
+        kind: 'file',
+        absolutePath: path.join(dir, entry.name),
+      }));
+  });
+}
+
+function readPluginDirFile(id, workingDirectory) {
+  const target = fileTargetFromId(id, workingDirectory);
+  if (!fs.existsSync(target.absolutePath)) {
+    return null;
+  }
+  return {
+    fileName: target.fileName,
+    scope: target.scope,
+    content: fs.readFileSync(target.absolutePath, 'utf8'),
+  };
+}
+
+function writePluginDirFile(file, workingDirectory, opts = {}) {
+  const fileName = validateFileName(file?.fileName);
+  const scope = file?.scope || AGENT_SCOPE.USER;
+  validateScope(scope);
+  const dir = pluginDirForScope(scope, workingDirectory);
+  const absolutePath = path.join(dir, fileName);
+  if (!opts.overwrite && fs.existsSync(absolutePath)) {
+    throw codedError(`Plugin file "${fileName}" already exists`, 'FILE_EXISTS');
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(absolutePath, file?.content ?? '', 'utf8');
+}
+
+function deletePluginDirFile(id, workingDirectory) {
+  const target = fileTargetFromId(id, workingDirectory);
+  if (!fs.existsSync(target.absolutePath)) {
+    throw codedError(`Plugin file "${target.fileName}" not found`, 'NOT_FOUND');
+  }
+  fs.unlinkSync(target.absolutePath);
+}
+
+export {
+  listPluginEntries,
+  getPluginEntry,
+  createPluginEntry,
+  updatePluginEntry,
+  deletePluginEntry,
+  listPluginDirFiles,
+  readPluginDirFile,
+  writePluginDirFile,
+  deletePluginDirFile,
+  encodePluginId,
+  decodePluginId,
+  parsePluginRaw,
+  serializePluginEntry,
+};

package/server/lib/opencode/plugins.test.js

@@ -0,0 +1,176 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+let rootDir;
+let projectDir;
+let userConfigPath;
+let plugins;
+
+function thrownBy(fn) {
+  try {
+    fn();
+  } catch (error) {
+    return error;
+  }
+  throw new Error('Expected function to throw');
+}
+
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+describe('opencode plugins data layer', () => {
+  beforeAll(async () => {
+    rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-plugins-'));
+    userConfigPath = path.join(rootDir, 'user-opencode.json');
+    process.env.OPENCODE_CONFIG = userConfigPath;
+    plugins = await import('./plugins.js');
+  });
+
+  beforeEach(() => {
+    process.env.OPENCODE_CONFIG = userConfigPath;
+    projectDir = fs.mkdtempSync(path.join(rootDir, 'project-'));
+    fs.rmSync(userConfigPath, { force: true });
+  });
+
+  afterAll(() => {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+    delete process.env.OPENCODE_CONFIG;
+  });
+
+  test('parses raw plugin entries', () => {
+    expect(plugins.parsePluginRaw('foo')).toEqual({ spec: 'foo' });
+    expect(plugins.parsePluginRaw('foo@1.0.0')).toEqual({ spec: 'foo@1.0.0' });
+    expect(plugins.parsePluginRaw(['foo', { a: 1 }])).toEqual({ spec: 'foo', options: { a: 1 } });
+    expect(plugins.parsePluginRaw(['foo', {}])).toEqual({ spec: 'foo', options: {} });
+    expect(() => plugins.parsePluginRaw(123)).toThrow('Plugin spec');
+  });
+
+  test('serializes plugin entries', () => {
+    expect(plugins.serializePluginEntry({ spec: 'foo' })).toBe('foo');
+    expect(plugins.serializePluginEntry({ spec: 'foo', options: undefined })).toBe('foo');
+    expect(plugins.serializePluginEntry({ spec: 'foo', options: {} })).toBe('foo');
+    expect(plugins.serializePluginEntry({ spec: 'foo', options: { a: 1 } })).toEqual(['foo', { a: 1 }]);
+  });
+
+  test('rejects invalid specs and file names', () => {
+    expect(() => plugins.createPluginEntry({ spec: 123, scope: 'user' }, projectDir)).toThrow('Plugin spec');
+    expect(() => plugins.writePluginDirFile({ fileName: '', content: '', scope: 'project' }, projectDir)).toThrow('Plugin file name');
+    expect(() => plugins.writePluginDirFile({ fileName: '../bad.js', content: '', scope: 'project' }, projectDir)).toThrow('Plugin file name');
+    expect(() => plugins.writePluginDirFile({ fileName: 'a/b.js', content: '', scope: 'project' }, projectDir)).toThrow('Plugin file name');
+    expect(() => plugins.writePluginDirFile({ fileName: 'A.js', content: '', scope: 'project' }, projectDir)).toThrow('Plugin file name');
+    expect(() => plugins.writePluginDirFile({ fileName: 'foo.txt', content: '', scope: 'project' }, projectDir)).toThrow('Plugin file name');
+  });
+
+  test('creates string and tuple entries with duplicate rejection', () => {
+    plugins.createPluginEntry({ spec: 'plain-plugin', scope: 'user' }, projectDir);
+    plugins.createPluginEntry({ spec: 'tuple-plugin', options: { apiKey: 'x' }, scope: 'user' }, projectDir);
+
+    expect(readJson(userConfigPath).plugin).toEqual(['plain-plugin', ['tuple-plugin', { apiKey: 'x' }]]);
+    expect(() => plugins.createPluginEntry({ spec: 'plain-plugin', scope: 'user' }, projectDir)).toThrow('already exists');
+    expect(thrownBy(() => plugins.createPluginEntry({ spec: 'plain-plugin', scope: 'user' }, projectDir))).toHaveProperty('code', 'ENTRY_EXISTS');
+  });
+
+  test('routes project entries to project config and user entries to custom user config', () => {
+    plugins.createPluginEntry({ spec: 'user-plugin', scope: 'user' }, projectDir);
+    plugins.createPluginEntry({ spec: 'project-plugin', scope: 'project' }, projectDir);
+
+    expect(readJson(userConfigPath).plugin).toEqual(['user-plugin']);
+    expect(readJson(path.join(projectDir, '.opencode', 'opencode.json')).plugin).toEqual(['project-plugin']);
+  });
+
+  test('re-resolves custom config env between calls', () => {
+    const firstConfigPath = path.join(rootDir, 'first', 'opencode.json');
+    const secondConfigPath = path.join(rootDir, 'second', 'opencode.json');
+
+    process.env.OPENCODE_CONFIG = firstConfigPath;
+    plugins.createPluginEntry({ spec: 'first-plugin', scope: 'user' }, projectDir);
+    plugins.writePluginDirFile({ fileName: 'first.js', content: 'one', scope: 'user' }, projectDir);
+
+    process.env.OPENCODE_CONFIG = secondConfigPath;
+    plugins.createPluginEntry({ spec: 'second-plugin', scope: 'user' }, projectDir);
+    plugins.writePluginDirFile({ fileName: 'second.js', content: 'two', scope: 'user' }, projectDir);
+
+    expect(readJson(firstConfigPath).plugin).toEqual(['first-plugin']);
+    expect(readJson(secondConfigPath).plugin).toEqual(['second-plugin']);
+    expect(fs.existsSync(path.join(path.dirname(firstConfigPath), 'plugins', 'first.js'))).toBe(true);
+    expect(fs.existsSync(path.join(path.dirname(secondConfigPath), 'plugins', 'second.js'))).toBe(true);
+  });
+
+  test('updates entries in place and transitions between string and tuple', () => {
+    writeJson(userConfigPath, { plugin: ['first', ['second', { a: 1 }], 'third'] });
+
+    plugins.updatePluginEntry(plugins.encodePluginId('config', 'user:second'), { spec: 'second-new', options: {} }, projectDir);
+    expect(readJson(userConfigPath).plugin).toEqual(['first', 'second-new', 'third']);
+
+    plugins.updatePluginEntry(plugins.encodePluginId('config', 'user:first'), { spec: 'first-new', options: { b: 2 } }, projectDir);
+    expect(readJson(userConfigPath).plugin).toEqual([['first-new', { b: 2 }], 'second-new', 'third']);
+  });
+
+  test('deletes entries and prunes empty plugin key', () => {
+    writeJson(userConfigPath, { plugin: ['only'] });
+
+    plugins.deletePluginEntry(plugins.encodePluginId('config', 'user:only'), projectDir);
+    expect(readJson(userConfigPath)).toEqual({});
+  });
+
+  test('lists entries from user and project layers with scopes and parsed kinds', () => {
+    writeJson(userConfigPath, { plugin: ['npm-plugin', '/abs/plugin.js', '@scope/pkg@1.0.0'] });
+    writeJson(path.join(projectDir, '.opencode', 'opencode.json'), { plugin: ['./local-plugin.js'] });
+
+    const entries = plugins.listPluginEntries(projectDir);
+    expect(entries).toEqual([
+      expect.objectContaining({ spec: 'npm-plugin', scope: 'user', kind: 'config', parsedKind: 'npm', sourcePath: userConfigPath }),
+      expect.objectContaining({ spec: '/abs/plugin.js', scope: 'user', kind: 'config', parsedKind: 'path', sourcePath: userConfigPath }),
+      expect.objectContaining({ spec: '@scope/pkg@1.0.0', scope: 'user', kind: 'config', parsedKind: 'npm', sourcePath: userConfigPath }),
+      expect.objectContaining({ spec: './local-plugin.js', scope: 'project', kind: 'config', parsedKind: 'path', sourcePath: path.join(projectDir, '.opencode', 'opencode.json') }),
+    ]);
+    fs.rmSync(userConfigPath, { force: true });
+    expect(plugins.listPluginEntries(projectDir)).toEqual([
+      expect.objectContaining({ spec: './local-plugin.js', scope: 'project' }),
+    ]);
+  });
+
+  test('encodes and decodes ids', () => {
+    const id = plugins.encodePluginId('config', 'user:oh-my-openagent@4.3.0');
+    expect(plugins.decodePluginId(id)).toEqual({ prefix: 'config', value: 'user:oh-my-openagent@4.3.0' });
+  });
+
+  test('round-trips plugin dir files', () => {
+    plugins.writePluginDirFile({ fileName: 'my-plugin.ts', content: 'export default {}', scope: 'project' }, projectDir);
+    const file = plugins.listPluginDirFiles(projectDir).find((candidate) => candidate.fileName === 'my-plugin.ts');
+
+    expect(file).toEqual(expect.objectContaining({ fileName: 'my-plugin.ts', scope: 'project', kind: 'file' }));
+    expect(plugins.readPluginDirFile(file.id, projectDir)).toEqual({ fileName: 'my-plugin.ts', scope: 'project', content: 'export default {}' });
+    plugins.deletePluginDirFile(file.id, projectDir);
+    expect(plugins.listPluginDirFiles(projectDir).filter((candidate) => candidate.scope === 'project')).toEqual([]);
+    expect(() => plugins.deletePluginDirFile(file.id, projectDir)).toThrow('not found');
+  });
+
+  test('rejects duplicate plugin dir files unless overwrite is true', () => {
+    plugins.writePluginDirFile({ fileName: 'dup.js', content: 'one', scope: 'project' }, projectDir);
+    expect(() => plugins.writePluginDirFile({ fileName: 'dup.js', content: 'two', scope: 'project' }, projectDir)).toThrow('already exists');
+    expect(thrownBy(() => plugins.writePluginDirFile({ fileName: 'dup.js', content: 'two', scope: 'project' }, projectDir))).toHaveProperty('code', 'FILE_EXISTS');
+
+    plugins.writePluginDirFile({ fileName: 'dup.js', content: 'two', scope: 'project' }, projectDir, { overwrite: true });
+    expect(fs.readFileSync(path.join(projectDir, '.opencode', 'plugins', 'dup.js'), 'utf8')).toBe('two');
+  });
+
+  test('lists only valid plugin dir files', () => {
+    const dir = path.join(projectDir, '.opencode', 'plugins');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'valid.mjs'), '', 'utf8');
+    fs.writeFileSync(path.join(dir, 'README.md'), '', 'utf8');
+
+    expect(plugins.listPluginDirFiles(projectDir).filter((file) => file.scope === 'project')).toEqual([
+      expect.objectContaining({ fileName: 'valid.mjs', scope: 'project' }),
+    ]);
+  });
+});

package/server/lib/opencode/settings-helpers.js

@@ -115,6 +115,9 @@ export const createSettingsHelpers = (dependencies) => {
     if (typeof candidate.desktopLanAccessEnabled === 'boolean') {
       result.desktopLanAccessEnabled = candidate.desktopLanAccessEnabled;
     }
+    if (typeof candidate.desktopUiPassword === 'string') {
+      result.desktopUiPassword = candidate.desktopUiPassword.trim();
+    }
     if (Array.isArray(candidate.projects)) {
       const projects = sanitizeProjects(candidate.projects);
       if (projects) {

package/server/lib/opencode/settings-helpers.test.js

@@ -52,6 +52,17 @@ describe('settings helpers', () => {
     });
   });
 
+  it('accepts desktopUiPassword as a persisted shared setting', () => {
+    const helpers = createTestHelpers();
+
+    expect(helpers.sanitizeSettingsUpdate({ desktopUiPassword: ' secret ' })).toEqual({
+      desktopUiPassword: 'secret',
+    });
+    expect(helpers.sanitizeSettingsUpdate({ desktopUiPassword: '' })).toEqual({
+      desktopUiPassword: '',
+    });
+  });
+
   it('accepts mobileKeyboardMode as a persisted shared setting', () => {
     const helpers = createTestHelpers();
 

package/server/lib/tunnels/DOCUMENTATION.md

@@ -10,6 +10,7 @@ This module contains tunnel provider orchestration for OpenChamber, including pr
 - `packages/web/server/lib/tunnels/routes.js`: tunnel API route registration and request orchestration runtime.
 - `packages/web/server/lib/tunnels/types.js`: tunnel constants, normalization, and shared type helpers.
 - `packages/web/server/lib/tunnels/providers/cloudflare.js`: Cloudflare tunnel provider implementation.
+- `packages/web/server/lib/tunnels/providers/ngrok.js`: Ngrok quick tunnel provider implementation.
 
 ## Public exports (routes.js)
 - `createTunnelRoutesRuntime(dependencies)`: creates tunnel routes runtime and helpers.