@openchambery/web 2.1.8-beta.3 → 2.1.8-beta.5

package/server/lib/opencode/DOCUMENTATION.md

@@ -19,6 +19,7 @@ This module provides OpenCode server integration utilities for the web server ru
   from the authenticated client context (null for owner UI sessions), allowing
   connection shortcuts to exclude themselves without changing management lists.
 - `plugins.js`: config entries and plugin-directory files are inventory, not compatibility checks. They do not synthesize `compatibility` or `compatible` fields; Settings uses the OpenCode runtime inventory for actual load status and errors.
+  - Reads native V2 `plugins` (strings or `{ package, options }`) with legacy `plugin`/tuple fallback. A native array, including an empty one, wins within each document. Entry mutations write only `plugins`, convert retained legacy tuples, and remove the shadowed legacy key in the touched source file. Options, ordering, unrelated configuration and JSONC comments are preserved through the shared atomic config writer; malformed entries or write failures do not replace the original file. Web, Electron and mobile use this host implementation; VS Code mirrors the same persistence contract.
 - `session-directory-runtime.js`: Host-side physical directory identity for session index/list/detail/live projection. Uses a runtime-scoped, bounded 256-entry cache (60s success / 5s failed resolution), cleared when the upstream URL changes. Local directory lists use the upstream project identity and physical-directory filtering to include legacy symlink sessions without mixing worktrees. One request reads one page and preserves opaque cursors; consumers must follow continuations even after filtered-empty pages. Non-loopback upstreams keep their own path namespace.
 - `packages/web/server/lib/opencode/index.js`: public entrypoint (currently baseline placeholder).
 - `packages/web/server/lib/opencode/auth.js`: host-only authoritative provider credential API reads and deletion.
@@ -27,6 +28,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/cli-entry-runtime.js`: CLI entrypoint runtime that detects direct execution, forces `OPENCHAMBER_RUNTIME=web` unless already `ssh-remote` (so `dev:server` cannot inherit a leftover desktop env and host a relay, while SSH-managed remotes may), parses CLI options, and starts server bootstrap.
 - `packages/web/server/lib/opencode/routes.js`: OpenCode/provider settings and auth-related route registration.
 - `packages/web/server/lib/opencode/lifecycle.js`: OpenCode process lifecycle runtime (startup, restart, readiness, health monitoring). Managed child env inherits the user shell environment unchanged; experimental flags such as `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` follow the user's own environment and are never injected by OpenChamber.
+  - Before shared-service/private startup, config-sync's Magpie adapter repairs the discoverable command entry for an existing OpenChamber-managed Magpie CLI. No download occurs at startup. Errors remain explicit rather than starting OpenCode with an undiscoverable managed dependency. External services are not modified.
 - `packages/web/server/lib/opencode/v1-migration-gate.js`: pure V1→v2 migration admission gate (`GET /api/experimental/migration/v1` → whether transcript may be fetched).
 - `packages/web/server/lib/opencode/managed-capabilities-runtime.js`: managed-child scheduled-task resources, config injection, rotating bridge identity, and bridge authorization.
 - `packages/web/server/lib/opencode/env-runtime.js`: OpenCode CLI/binary resolution and shell environment runtime.

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

@@ -66,7 +66,8 @@ describe('Web/Electron entity physical provenance', () => {
     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(json).plugins).toEqual(['updated-plugin']);
+    expect(readConfigFile(json).plugin).toBeUndefined();
     expect(readConfigFile(jsonc).plugin).toEqual(['higher-plugin']);
   });
 });

package/server/lib/opencode/lifecycle.js

@@ -6,6 +6,7 @@ import { readOpenCode2BinaryVersion } from './ensure-cli.js';
 import { createRevokedRuntimeContract, evaluateRuntimeContract } from './runtime-contract.js';
 import { OPENCODE_V1_MIGRATION_PATH, fetchV1MigrationGate } from './v1-migration-gate.js';
 import { isProcessAlive } from './shared-service.js';
+import { createMagpieSync } from '../config-sync/magpie.js';
 
 const parsePositiveInt = (value, fallback) => {
   const parsed = Number.parseInt(String(value ?? ''), 10);
@@ -71,6 +72,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     buildAugmentedPath,
     buildManagedOpenCodePath,
     getManagedOpenCodeShellEnvSnapshot,
+    prepareMagpieInstallation = () => createMagpieSync().repairInstallation(),
     managedCapabilitiesRuntime = null,
     getActiveSessionCount = () => 0,
     // Official background service (shared-service.js). null keeps the private
@@ -691,6 +693,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
    * or the registration is missing/malformed; the caller decides rollback.
    */
   const connectSharedOpenCodeService = async ({ binaryPath } = {}) => {
+    await prepareMagpieInstallation();
     if (!binaryPath) {
       await applyOpencodeBinaryFromSettings({ strict: true });
       if (typeof ensurePinnedOpenCode2CliEnv === 'function') {
@@ -793,6 +796,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
   const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
   const startOpenCodeOnce = async () => {
+    await prepareMagpieInstallation();
     // New managed instance — drop any prior permit before spawn/probes.
     const generationAtStart = revokeRuntimeExecutionPermit('managed-start');
     const requestedPort = env.ENV_CONFIGURED_OPENCODE_PORT;

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

@@ -101,6 +101,7 @@ const createRuntime = (overrides = {}, stateRef = null) => {
     normalizeApiPrefix: vi.fn(() => ''),
     applyOpencodeBinaryFromSettings: vi.fn(async () => null),
     ensureOpencodeCliEnv: vi.fn(),
+    prepareMagpieInstallation: vi.fn(async () => {}),
     ensureLocalOpenCodeServerPassword: vi.fn(async () => 'password'),
     resolveManagedOpenCodeLaunchSpec: vi.fn((binary) => ({ binary, args: [], wrapperType: null })),
     setOpenCodePort: vi.fn((port) => {
@@ -195,14 +196,16 @@ describe('OpenCode lifecycle', () => {
   it('launches managed OpenCode with the managed PATH', async () => {
     delete process.env.OPENCODE_BINARY;
     const child = createMockChild();
+    const prepareMagpieInstallation = vi.fn(async () => {});
     spawnMock.mockImplementationOnce(() => {
+      expect(prepareMagpieInstallation).toHaveBeenCalledTimes(1);
       queueMicrotask(() => {
         child.stdout.emit('data', 'opencode server listening on http://127.0.0.1:45678\n');
       });
       return child;
     });
 
-    const runtime = createRuntime();
+    const runtime = createRuntime({ prepareMagpieInstallation });
     const server = await runtime.startOpenCode();
     const [binary, args, options] = spawnMock.mock.calls[0];
 
@@ -1100,13 +1103,15 @@ describe('shared official OpenCode service', () => {
     const sharedService = createSharedService();
     const adoptOpenCodeServerPassword = vi.fn();
     const stateRef = {};
-    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, adoptOpenCodeServerPassword }, stateRef);
+    const prepareMagpieInstallation = vi.fn(async () => {});
+    const runtime = createRuntime({ env: UNCONFIGURED_ENV, sharedService, adoptOpenCodeServerPassword, prepareMagpieInstallation }, stateRef);
     const fetchMock = stubSharedFetch();
 
     await runtime.bootstrapOpenCodeAtStartup();
 
     expect(spawnMock).not.toHaveBeenCalled();
     expect(sharedService.start).toHaveBeenCalledTimes(1);
+    expect(prepareMagpieInstallation.mock.invocationCallOrder[0]).toBeLessThan(sharedService.start.mock.invocationCallOrder[0]);
     const startInput = sharedService.start.mock.calls[0][0];
     expect(startInput.binary).toBe('/mock/opencode');
     expect(startInput.env.OPENCODE_SERVER_PASSWORD).toBeUndefined();

package/server/lib/opencode/plugin-routes.test.js

@@ -316,7 +316,7 @@ describe('opencode plugin routes', () => {
 
     const after = await request(app).get('/api/config/plugins').expect(200);
     expect(after.body.entries).toEqual([]);
-    expect(readJson(userConfigPath).plugin).toBeUndefined();
+    expect(readJson(userConfigPath).plugins).toBeUndefined();
     expect(refreshOpenCodeAfterConfigChange).not.toHaveBeenCalled();
   });
 

package/server/lib/opencode/plugins.js

@@ -79,6 +79,25 @@ function readPluginConfigLayers(workingDirectory) {
   return readConfigLayers(workingDirectory);
 }
 
+function readPluginArray(config) {
+  if (Array.isArray(config.plugins)) return config.plugins;
+  return Array.isArray(config.plugin) ? config.plugin : [];
+}
+
+function writePluginArray(config, plugin, filePath) {
+  const next = { ...config };
+  delete next.plugin;
+  if (plugin.length > 0) {
+    next.plugins = plugin.map((raw) => {
+      const parsed = parsePluginRaw(raw);
+      return Array.isArray(raw) ? serializePluginEntry(parsed) : raw;
+    });
+  } else {
+    delete next.plugins;
+  }
+  writeConfig(next, filePath);
+}
+
 function validateFileName(fileName) {
   if (typeof fileName !== 'string' || !fileName) {
     throw codedError('Plugin file name is required', 'INVALID_FILENAME');
@@ -125,9 +144,8 @@ function getPluginTarget(id, workingDirectory) {
   validateScope(scope);
   const layers = readPluginConfigLayers(workingDirectory);
   const source = configSources(layers).find((candidate) => candidate.scope === scope
-    && Array.isArray(candidate.config?.plugin)
-    && candidate.config.plugin.some((raw) => parsePluginRaw(raw).spec === spec));
-  const plugin = Array.isArray(source?.config?.plugin) ? source.config.plugin : [];
+    && readPluginArray(candidate.config).some((raw) => parsePluginRaw(raw).spec === spec));
+  const plugin = source ? [...readPluginArray(source.config)] : [];
   const index = plugin.findIndex((raw) => parsePluginRaw(raw).spec === spec);
   if (!source || index === -1) {
     return null;
@@ -181,13 +199,16 @@ function parsePluginRaw(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');
+  if (isRecord(raw) && (raw.options === undefined || isRecord(raw.options))) {
+    return { spec: validatePluginSpec(raw.package), ...(raw.options === undefined ? {} : { options: { ...raw.options } }) };
+  }
+  throw codedError('Plugin spec must be a string or { package, options } object', 'INVALID_SPEC');
 }
 
 function serializePluginEntry(entry) {
   const spec = validatePluginSpec(entry?.spec);
   if (hasOptions(entry?.options)) {
-    return [spec, { ...entry.options }];
+    return { package: spec, options: { ...entry.options } };
   }
   return spec;
 }
@@ -195,10 +216,7 @@ function serializePluginEntry(entry) {
 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) => {
+    return readPluginArray(source.config).map((raw) => {
       const parsed = parsePluginRaw(raw);
       return {
         id: encodePluginId('config', `${source.scope}:${parsed.spec}`),
@@ -225,8 +243,7 @@ function createPluginEntry(entry, workingDirectory) {
   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)
+    && readPluginArray(source.config).some((raw) => parsePluginRaw(raw).spec === spec)
   ));
   if (existing) {
     throw codedError(`Plugin "${spec}" already exists`, 'ENTRY_EXISTS');
@@ -242,11 +259,7 @@ function createPluginEntry(entry, workingDirectory) {
     config = getConfigForPath(layers, targetPath);
   }
 
-  if (!Array.isArray(config.plugin)) {
-    config.plugin = [];
-  }
-  config.plugin.push(serializePluginEntry({ spec, options: entry.options }));
-  writeConfig(config, targetPath);
+  writePluginArray(config, [...readPluginArray(config), serializePluginEntry({ spec, options: entry.options })], targetPath);
 }
 
 function updatePluginEntry(id, updates, workingDirectory) {
@@ -258,7 +271,7 @@ function updatePluginEntry(id, updates, workingDirectory) {
   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);
+  writePluginArray(target.source.config, target.plugin, target.source.filePath);
 }
 
 function deletePluginEntry(id, workingDirectory) {
@@ -267,10 +280,7 @@ function deletePluginEntry(id, workingDirectory) {
     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);
+  writePluginArray(target.source.config, target.plugin, target.source.filePath);
 }
 
 function listPluginDirFiles(workingDirectory) {

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

@@ -52,6 +52,9 @@ describe('opencode plugins data layer', () => {
     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({ package: 'foo', options: { a: 1 } })).toEqual({ spec: 'foo', options: { a: 1 } });
+    expect(plugins.parsePluginRaw({ package: 'foo' })).toEqual({ spec: 'foo' });
+    expect(() => plugins.parsePluginRaw({ package: 'foo', options: [] })).toThrow('Plugin spec');
     expect(() => plugins.parsePluginRaw(123)).toThrow('Plugin spec');
   });
 
@@ -59,7 +62,7 @@ describe('opencode plugins data layer', () => {
     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 }]);
+    expect(plugins.serializePluginEntry({ spec: 'foo', options: { a: 1 } })).toEqual({ package: 'foo', options: { a: 1 } });
   });
 
   test('rejects invalid specs and file names', () => {
@@ -71,11 +74,11 @@ describe('opencode plugins data layer', () => {
     expect(() => plugins.writePluginDirFile({ fileName: 'foo.txt', content: '', scope: 'project' }, projectDir)).toThrow('Plugin file name');
   });
 
-  test('creates string and tuple entries with duplicate rejection', () => {
+  test('creates V2 string and object 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(readJson(userConfigPath).plugins).toEqual(['plain-plugin', { package: 'tuple-plugin', options: { 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');
   });
@@ -84,8 +87,8 @@ describe('opencode plugins data layer', () => {
     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']);
+    expect(readJson(userConfigPath).plugins).toEqual(['user-plugin']);
+    expect(readJson(path.join(projectDir, '.opencode', 'opencode.json')).plugins).toEqual(['project-plugin']);
   });
 
   test('re-resolves custom config env between calls', () => {
@@ -100,20 +103,62 @@ describe('opencode plugins data layer', () => {
     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(readJson(firstConfigPath).plugins).toEqual(['first-plugin']);
+    expect(readJson(secondConfigPath).plugins).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', () => {
+  test('migrates legacy entries in place and transitions between string and object', () => {
     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']);
+    expect(readJson(userConfigPath)).toEqual({ plugins: ['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']);
+    expect(readJson(userConfigPath).plugins).toEqual([{ package: 'first-new', options: { b: 2 } }, 'second-new', 'third']);
+  });
+
+  test('converts untouched legacy options on save and preserves unrelated JSONC', () => {
+    fs.writeFileSync(userConfigPath, '// retained comment\n' + JSON.stringify({ model: 'example/model', plugin: [['old', { nested: { enabled: false } }]] }));
+    plugins.createPluginEntry({ spec: 'new', scope: 'user' }, projectDir);
+    const text = fs.readFileSync(userConfigPath, 'utf8');
+    expect(text).toContain('// retained comment');
+    expect(plugins.listPluginEntries(projectDir).map(({ spec, options }) => ({ spec, options }))).toEqual([
+      { spec: 'old', options: { nested: { enabled: false } } }, { spec: 'new', options: undefined },
+    ]);
+    expect(text).toContain('"plugins"');
+    expect(text).not.toContain('"plugin"');
+    expect(text).toContain('example/model');
+  });
+
+  test('prefers native plugins over legacy entries including an empty native array', () => {
+    writeJson(userConfigPath, { plugin: ['shadowed'], plugins: [{ package: 'native', options: { enabled: false } }] });
+    expect(plugins.listPluginEntries(projectDir).map((entry) => entry.spec)).toEqual(['native']);
+    expect(() => plugins.createPluginEntry({ spec: 'native' }, projectDir)).toThrow('already exists');
+    plugins.deletePluginEntry(plugins.encodePluginId('config', 'user:native'), projectDir);
+    expect(readJson(userConfigPath)).toEqual({});
+    writeJson(userConfigPath, { plugin: ['shadowed'], plugins: [] });
+    expect(plugins.listPluginEntries(projectDir)).toEqual([]);
+    plugins.createPluginEntry({ spec: 'new' }, projectDir);
+    expect(readJson(userConfigPath)).toEqual({ plugins: ['new'] });
+  });
+
+  test('malformed legacy data and failed atomic writes leave original config intact', () => {
+    writeJson(userConfigPath, { plugin: [['bad', null]], model: 'example/model' });
+    const malformed = fs.readFileSync(userConfigPath, 'utf8');
+    expect(() => plugins.createPluginEntry({ spec: 'new' }, projectDir)).toThrow('Plugin spec');
+    expect(fs.readFileSync(userConfigPath, 'utf8')).toBe(malformed);
+
+    writeJson(userConfigPath, { plugin: [['old', { enabled: false }]] });
+    const original = fs.readFileSync(userConfigPath, 'utf8');
+    const rename = vi.spyOn(fs, 'renameSync').mockImplementation(() => { throw new Error('write failed'); });
+    try {
+      expect(() => plugins.createPluginEntry({ spec: 'new' }, projectDir)).toThrow('write failed');
+      expect(fs.readFileSync(userConfigPath, 'utf8')).toBe(original);
+    } finally {
+      rename.mockRestore();
+    }
   });
 
   test('deletes entries and prunes empty plugin key', () => {