@openchambery/web 1.19.22-beta.1 → 2.0.0-beta.10

package/server/lib/opencode/upgrade-screen.js

@@ -0,0 +1,299 @@
+/**
+ * Startup upgrade screen for OpenCode below 2.0.15.
+ *
+ * This module does not own process lifecycle. It classifies the version the
+ * existing startup path already detected, and installs through the owned-cache
+ * installer (`installPinnedOpenCode2Cli`) plus the caller's restart hook.
+ * Success is a verified running version, never a download that has not started.
+ */
+
+import {
+  PINNED_OPENCODE2_VERSION,
+  isAcceptableOpenCode2HealthVersion,
+  isOpenCode1xVersion,
+  isOpenCode2VersionAtLeast,
+  npmPackageForOpenCode2,
+} from './opencode2-pin.js';
+
+/** Oldest OpenCode this OpenChamber build will enter a session against. */
+export const REQUIRED_OPENCODE_VERSION = '2.0.15';
+
+const normalizeVersion = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim().replace(/^v/i, '');
+  return trimmed || null;
+};
+
+/**
+ * Install target is the pin when the pin already satisfies the screen, otherwise
+ * the screen minimum. A pin still at 2.0.12 must not be what this screen installs.
+ * @param {string} [pin]
+ */
+export function resolveUpgradeScreenTarget(pin = PINNED_OPENCODE2_VERSION) {
+  if (isOpenCode2VersionAtLeast(pin, REQUIRED_OPENCODE_VERSION)) return pin;
+  return REQUIRED_OPENCODE_VERSION;
+}
+
+/** 2.x at or above the screen minimum. A future major is not this contract. */
+function isUpgradeScreenSatisfied(version) {
+  const normalized = normalizeVersion(version);
+  if (!normalized || !isAcceptableOpenCode2HealthVersion(normalized)) return false;
+  return isOpenCode2VersionAtLeast(normalized, REQUIRED_OPENCODE_VERSION);
+}
+
+function isOlderThanUpgradeScreenMinimum(version) {
+  const normalized = normalizeVersion(version);
+  if (!normalized) return false;
+  if (isOpenCode1xVersion(normalized)) return true;
+  if (!isAcceptableOpenCode2HealthVersion(normalized)) return false;
+  return !isOpenCode2VersionAtLeast(normalized, REQUIRED_OPENCODE_VERSION);
+}
+
+/**
+ * @param {string | null | undefined} ownership
+ * @returns {'managed' | 'external' | 'bundled'}
+ */
+function classifyUpgradeScreenInstallation(ownership) {
+  if (ownership === 'external-serve') return 'external';
+  if (ownership === 'bundled') return 'bundled';
+  return 'managed';
+}
+
+export function platformSupportsUpgradeScreenInstall(platform = process.platform, arch = process.arch) {
+  try {
+    npmPackageForOpenCode2(platform, arch);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const pickDetectedVersion = (serveVersion, cliVersion) => {
+  const serve = normalizeVersion(serveVersion);
+  const cli = normalizeVersion(cliVersion);
+  if (serve && !isUpgradeScreenSatisfied(serve)) return serve;
+  if (serve) return serve;
+  return cli;
+};
+
+/**
+ * @param {{
+ *   version?: string | null,
+ *   installation?: 'managed' | 'external' | 'bundled',
+ *   platformCanInstall?: boolean,
+ *   guidance?: string | null,
+ *   pin?: string,
+ * }} input
+ */
+export function describeUpgradeScreen(input = {}) {
+  const version = normalizeVersion(input.version);
+  const installation = input.installation === 'external' || input.installation === 'bundled'
+    ? input.installation
+    : 'managed';
+  const state = version == null
+    ? 'unavailable'
+    : isUpgradeScreenSatisfied(version)
+      ? 'compatible'
+      : 'incompatible';
+  const older = version != null && isOlderThanUpgradeScreenMinimum(version);
+  // External processes are not replaced. Bundled and managed locals can receive
+  // an owned-cache install; that does not overwrite the user's other binaries.
+  const canInstall = state === 'incompatible'
+    && older
+    && installation !== 'external'
+    && input.platformCanInstall === true;
+  const guidance = canInstall
+    ? null
+    : (typeof input.guidance === 'string' && input.guidance.trim() ? input.guidance.trim() : null);
+  return {
+    state,
+    version,
+    installation,
+    minimumVersion: REQUIRED_OPENCODE_VERSION,
+    targetVersion: resolveUpgradeScreenTarget(input.pin),
+    canInstall,
+    guidance,
+  };
+}
+
+/**
+ * A running serve below the minimum, or a missing version, is not an upgrade.
+ * @param {{ targetVersion?: string | null, serveVersion?: string | null }} input
+ */
+export function evaluateUpgradeScreenInstallResult(input = {}) {
+  const targetVersion = resolveUpgradeScreenTarget(input.targetVersion || REQUIRED_OPENCODE_VERSION);
+  const version = normalizeVersion(input.serveVersion);
+  if (!version || !isUpgradeScreenSatisfied(version) || !isOpenCode2VersionAtLeast(version, targetVersion)) {
+    const found = version || 'unknown';
+    return {
+      ok: false,
+      upgraded: false,
+      version,
+      targetVersion,
+      errorCode: 'UPGRADE_SCREEN_NOT_VERIFIED',
+      error: `OpenCode is still ${found}. OpenChamber requires ${REQUIRED_OPENCODE_VERSION} or newer.`,
+    };
+  }
+  return {
+    ok: true,
+    upgraded: true,
+    version,
+    targetVersion,
+    error: null,
+    errorCode: null,
+  };
+}
+
+async function readUpgradeScreenStatus(deps) {
+  const ownership = typeof deps.resolveOwnership === 'function'
+    ? await deps.resolveOwnership()
+    : { ownership: 'unknown', guidance: null };
+  const installation = classifyUpgradeScreenInstallation(ownership?.ownership);
+  const serveVersion = typeof deps.readServeVersion === 'function'
+    ? await Promise.resolve(deps.readServeVersion()).catch(() => null)
+    : null;
+  const cliVersion = typeof deps.readCliVersion === 'function'
+    ? await Promise.resolve(deps.readCliVersion()).catch(() => null)
+    : null;
+  return describeUpgradeScreen({
+    version: pickDetectedVersion(serveVersion, cliVersion),
+    installation,
+    platformCanInstall: typeof deps.platformCanInstall === 'boolean'
+      ? deps.platformCanInstall
+      : platformSupportsUpgradeScreenInstall(deps.platform, deps.arch),
+    guidance: ownership?.guidance ?? null,
+    pin: deps.pin,
+  });
+}
+
+const failure = (message, code, status = 500) => {
+  const error = new Error(message);
+  error.code = code;
+  error.status = status;
+  return error;
+};
+
+/**
+ * Install the screen target into the owned cache and restart through the
+ * caller's existing lifecycle hooks. Restores the previous binary selection
+ * when verification fails. Never returns upgraded:true for a failed install.
+ * @param {object} deps
+ */
+export async function installRequiredOpenCode(deps) {
+  const status = await readUpgradeScreenStatus(deps);
+  if (status.state !== 'incompatible' || status.canInstall !== true) {
+    throw failure(
+      status.guidance || 'Automatic OpenCode installation is unavailable for this runtime.',
+      'UPGRADE_SCREEN_UNAVAILABLE',
+      409,
+    );
+  }
+  const target = status.targetVersion;
+  const previousBinary = typeof deps.getResolvedBinary === 'function' ? deps.getResolvedBinary() : null;
+  const previousSource = typeof deps.getResolvedBinarySource === 'function' ? deps.getResolvedBinarySource() : null;
+  const previousSetting = typeof deps.readConfiguredBinary === 'function'
+    ? await deps.readConfiguredBinary()
+    : undefined;
+  let persisted = false;
+  try {
+    if (typeof deps.install !== 'function') {
+      throw failure('OpenCode install is not configured.', 'UPGRADE_SCREEN_INSTALL_UNAVAILABLE', 500);
+    }
+    const installedPath = await deps.install({ version: target });
+    const diskVersion = typeof deps.readBinaryVersion === 'function'
+      ? await Promise.resolve(deps.readBinaryVersion(installedPath))
+      : null;
+    if (diskVersion !== target) {
+      throw failure(
+        `Installed OpenCode version mismatch: expected ${target}, got ${diskVersion || 'unknown'}`,
+        'UPGRADE_SCREEN_BINARY_MISMATCH',
+        500,
+      );
+    }
+    if (typeof deps.persistBinary === 'function') {
+      await deps.persistBinary(installedPath);
+      persisted = true;
+    }
+    if (typeof deps.forceBinary === 'function') {
+      deps.forceBinary(installedPath, 'installed');
+    }
+    if (typeof deps.restart === 'function') {
+      const shared = typeof deps.isSharedService === 'function' && deps.isSharedService() === true;
+      await deps.restart(shared ? { binaryPath: installedPath } : undefined);
+    }
+    if (typeof deps.waitReady === 'function') {
+      await deps.waitReady();
+    }
+    const serveVersion = typeof deps.readServeVersion === 'function'
+      ? await deps.readServeVersion()
+      : null;
+    const verification = evaluateUpgradeScreenInstallResult({ targetVersion: target, serveVersion });
+    if (!verification.ok) {
+      throw failure(verification.error, verification.errorCode, 500);
+    }
+    return verification;
+  } catch (error) {
+    if (persisted && typeof deps.persistBinary === 'function') {
+      try {
+        await deps.persistBinary(typeof previousSetting === 'string' ? previousSetting : '');
+      } catch {
+        // Keep the install error. A failed restore must not become success.
+      }
+    }
+    if (previousBinary && typeof deps.forceBinary === 'function') {
+      try {
+        deps.forceBinary(previousBinary, previousSource || 'discovered');
+      } catch {
+        // Same: report the install failure, not a restored-success.
+      }
+    }
+    throw error;
+  }
+}
+
+export function registerUpgradeScreenRoutes(app, deps) {
+  app.get('/api/opencode/compatibility', async (_req, res) => {
+    try {
+      res.json(await readUpgradeScreenStatus(deps));
+    } catch (error) {
+      res.status(503).json({
+        error: error instanceof Error ? error.message : 'Could not check OpenCode compatibility',
+      });
+    }
+  });
+
+  let inFlight = null;
+  app.post('/api/opencode/install-required', async (_req, res) => {
+    try {
+      if (!inFlight) {
+        inFlight = installRequiredOpenCode(deps).finally(() => {
+          inFlight = null;
+        });
+      }
+      const result = await inFlight;
+      if (!result || result.ok !== true || result.upgraded !== true || !result.version) {
+        return res.status(500).json({
+          success: false,
+          upgraded: false,
+          error: result?.error || 'OpenCode installation did not verify a new version',
+          errorCode: result?.errorCode || 'UPGRADE_SCREEN_NOT_VERIFIED',
+          version: result?.version ?? null,
+        });
+      }
+      return res.json({
+        success: true,
+        upgraded: true,
+        version: result.version,
+        targetVersion: result.targetVersion,
+      });
+    } catch (error) {
+      const status = Number.isInteger(error?.status) ? error.status : 500;
+      return res.status(status).json({
+        success: false,
+        upgraded: false,
+        error: error instanceof Error ? error.message : 'OpenCode installation failed',
+        errorCode: error?.code || 'UPGRADE_SCREEN_FAILED',
+      });
+    }
+  });
+}

package/server/lib/opencode/upgrade-screen.test.js

@@ -0,0 +1,196 @@
+import express from 'express';
+import request from 'supertest';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  REQUIRED_OPENCODE_VERSION,
+  describeUpgradeScreen,
+  evaluateUpgradeScreenInstallResult,
+  installRequiredOpenCode,
+  registerUpgradeScreenRoutes,
+  resolveUpgradeScreenTarget,
+} from './upgrade-screen.js';
+
+describe('upgrade screen version gate', () => {
+  it('uses 2.0.15 even when the runtime pin is older', () => {
+    expect(REQUIRED_OPENCODE_VERSION).toBe('2.0.15');
+    expect(resolveUpgradeScreenTarget('2.0.12')).toBe('2.0.15');
+    expect(resolveUpgradeScreenTarget('2.0.16')).toBe('2.0.16');
+  });
+
+  it('does not open the gate at or above 2.0.15', () => {
+    expect(describeUpgradeScreen({
+      version: '2.0.15',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'compatible', canInstall: false, minimumVersion: '2.0.15' });
+    expect(describeUpgradeScreen({
+      version: 'v2.0.16',
+      installation: 'managed',
+      platformCanInstall: true,
+    }).state).toBe('compatible');
+  });
+
+  it('opens the gate below 2.0.15 and offers install only when this runtime can switch', () => {
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true, version: '2.0.14' });
+    expect(describeUpgradeScreen({
+      version: '1.18.30',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true });
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'external',
+      platformCanInstall: true,
+    }).canInstall).toBe(false);
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'bundled',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true, installation: 'bundled' });
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'managed',
+      platformCanInstall: false,
+    }).canInstall).toBe(false);
+  });
+
+  it('does not treat a missing version as an old install', () => {
+    expect(describeUpgradeScreen({
+      version: null,
+      installation: 'managed',
+      platformCanInstall: true,
+    }).state).toBe('unavailable');
+  });
+
+  it('does not report an unverified install as upgraded', () => {
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: '2.0.14',
+    })).toMatchObject({ ok: false, upgraded: false, version: '2.0.14' });
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: null,
+    }).upgraded).toBe(false);
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: '2.0.15',
+    })).toMatchObject({ ok: true, upgraded: true, version: '2.0.15' });
+  });
+});
+
+describe('installRequiredOpenCode', () => {
+  const createDeps = (overrides = {}) => {
+    const calls = [];
+    const deps = {
+      resolveOwnership: async () => ({ ownership: 'global-cli', guidance: null }),
+      readServeVersion: async () => '2.0.14',
+      readCliVersion: () => '2.0.14',
+      platformCanInstall: true,
+      install: vi.fn(async () => {
+        calls.push('install');
+        return '/cache/opencode';
+      }),
+      readBinaryVersion: vi.fn(() => '2.0.15'),
+      persistBinary: vi.fn(async () => {
+        calls.push('persist');
+      }),
+      forceBinary: vi.fn(() => {
+        calls.push('force');
+      }),
+      restart: vi.fn(async () => {
+        calls.push('restart');
+      }),
+      waitReady: vi.fn(async () => {
+        calls.push('ready');
+      }),
+      readConfiguredBinary: async () => null,
+      isSharedService: () => false,
+      ...overrides,
+    };
+    return { deps, calls };
+  };
+
+  it('installs 2.0.15 and only succeeds after the running serve is verified', async () => {
+    const { deps, calls } = createDeps({
+      readServeVersion: vi.fn()
+        .mockResolvedValueOnce('2.0.14')
+        .mockResolvedValueOnce('2.0.15'),
+    });
+
+    await expect(installRequiredOpenCode(deps)).resolves.toMatchObject({
+      ok: true,
+      upgraded: true,
+      version: '2.0.15',
+      targetVersion: '2.0.15',
+    });
+    expect(deps.install).toHaveBeenCalledWith({ version: '2.0.15' });
+    expect(calls).toEqual(['install', 'persist', 'force', 'restart', 'ready']);
+  });
+
+  it('returns the failure reason and does not claim an upgrade when verification fails', async () => {
+    const { deps } = createDeps({
+      readServeVersion: vi.fn()
+        .mockResolvedValueOnce('1.18.30')
+        .mockResolvedValueOnce('1.18.30'),
+      readCliVersion: () => '1.18.30',
+      readBinaryVersion: () => '2.0.15',
+    });
+
+    await expect(installRequiredOpenCode(deps)).rejects.toThrow(/still 1\.18\.30/);
+    expect(deps.persistBinary).toHaveBeenCalledWith('');
+  });
+
+  it('does not install when the runtime cannot switch', async () => {
+    const { deps } = createDeps({
+      resolveOwnership: async () => ({
+        ownership: 'external-serve',
+        guidance: 'Restart that server yourself.',
+      }),
+    });
+
+    await expect(installRequiredOpenCode(deps)).rejects.toMatchObject({
+      status: 409,
+      message: 'Restart that server yourself.',
+    });
+    expect(deps.install).not.toHaveBeenCalled();
+  });
+});
+
+describe('upgrade screen routes', () => {
+  it('hides the gate for 2.0.15 and reports install failure without upgraded:true', async () => {
+    const app = express();
+    app.use(express.json());
+    const readServeVersion = vi.fn()
+      .mockResolvedValueOnce('2.0.15')
+      .mockResolvedValueOnce('2.0.12')
+      .mockResolvedValueOnce('2.0.12');
+    registerUpgradeScreenRoutes(app, {
+      resolveOwnership: async () => ({ ownership: 'owned-cache', guidance: null }),
+      readServeVersion,
+      readCliVersion: () => '2.0.12',
+      platformCanInstall: true,
+      install: vi.fn(async () => {
+        throw new Error('registry unreachable');
+      }),
+      readBinaryVersion: () => '2.0.15',
+      persistBinary: vi.fn(),
+      forceBinary: vi.fn(),
+      restart: vi.fn(),
+    });
+
+    const compatible = await request(app).get('/api/opencode/compatibility').expect(200);
+    expect(compatible.body).toMatchObject({ state: 'compatible', version: '2.0.15', minimumVersion: '2.0.15' });
+
+    const failed = await request(app).post('/api/opencode/install-required').expect(500);
+    expect(failed.body).toMatchObject({
+      success: false,
+      upgraded: false,
+      error: 'registry unreachable',
+    });
+    expect(failed.body.upgraded).not.toBe(true);
+  });
+});

package/server/lib/opencode/v1-migration-gate.js

@@ -0,0 +1,157 @@
+export const OPENCODE_V1_MIGRATION_PATH = '/api/experimental/migration/v1';
+
+// Backfill notes must stay readable by UI and docs. Do not drop them when the
+// gate blocks or later admits a migrated library.
+export const V1_MIGRATION_USER_NOTICE = [
+  'V1 history is backfilled in the opencode2 process.',
+  'Message ids are reused.',
+  'In-progress tools become interrupted.',
+  'V1 subtasks do not appear in v2.',
+].join(' ');
+
+const MIGRATION_PHASES = new Set(['required', 'running', 'completed', 'error']);
+
+const stringifyError = (error) => {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  if (typeof error === 'string' && error.trim()) {
+    return error;
+  }
+  return 'V1 migration status request failed';
+};
+
+const blocked = (phase, extra = {}) => ({
+  admitTranscript: false,
+  phase,
+  userNotice: V1_MIGRATION_USER_NOTICE,
+  ...extra,
+});
+
+const admitted = (phase, extra = {}) => ({
+  admitTranscript: true,
+  phase,
+  ...extra,
+});
+
+const normalizeProgress = (progress) => {
+  if (!progress || typeof progress !== 'object' || Array.isArray(progress)) {
+    return undefined;
+  }
+  const result = {
+    label: typeof progress.label === 'string' ? progress.label : '',
+  };
+  if (Number.isFinite(progress.numerator) && progress.numerator >= 0) {
+    result.numerator = progress.numerator;
+  }
+  if (Number.isFinite(progress.denominator) && progress.denominator >= 0) {
+    result.denominator = progress.denominator;
+  }
+  return result;
+};
+
+const resolveHttpStatus = (input) => {
+  if (typeof input.httpStatus === 'number') {
+    return input.httpStatus;
+  }
+  if (typeof input.status === 'number') {
+    return input.status;
+  }
+  return undefined;
+};
+
+const resolveBody = (input) => {
+  if (input.body !== undefined) {
+    return input.body;
+  }
+  if (typeof input.status === 'string') {
+    return input;
+  }
+  return null;
+};
+
+const resolveTransportError = (input) => {
+  if (input instanceof Error || typeof input === 'string') {
+    return input;
+  }
+  if (input?.error instanceof Error || typeof input?.error === 'string') {
+    if (input.body === undefined && typeof input.status !== 'string') {
+      return input.error;
+    }
+  }
+  return null;
+};
+
+// Pure admission decision for GET /api/experimental/migration/v1.
+// required/running/error never become an empty-list success.
+export const evaluateV1MigrationGate = (input = {}) => {
+  if (input == null) {
+    return blocked('error', { error: 'V1 migration status is missing or invalid' });
+  }
+
+  const transportError = resolveTransportError(input);
+  if (transportError) {
+    return blocked('error', { error: stringifyError(transportError) });
+  }
+
+  const httpStatus = resolveHttpStatus(input);
+  if (httpStatus === 404) {
+    return admitted('absent');
+  }
+  if (Number.isInteger(httpStatus) && httpStatus >= 400) {
+    return blocked('error', { error: `V1 migration status HTTP ${httpStatus}` });
+  }
+
+  const body = resolveBody(input);
+  const phase = body && typeof body === 'object' ? body.status : undefined;
+
+  if (phase === 'required') {
+    return blocked('required');
+  }
+  if (phase === 'running') {
+    return blocked('running', { progress: normalizeProgress(body.progress) });
+  }
+  if (phase === 'completed') {
+    return admitted('completed', { userNotice: V1_MIGRATION_USER_NOTICE });
+  }
+  if (phase === 'error') {
+    return blocked('error', {
+      error: typeof body.error === 'string' && body.error.trim()
+        ? body.error
+        : 'V1 migration failed',
+    });
+  }
+
+  if (MIGRATION_PHASES.has(phase) === false) {
+    return blocked('error', { error: 'V1 migration status is missing or invalid' });
+  }
+
+  return blocked('error', { error: 'V1 migration status is missing or invalid' });
+};
+
+// Official protocol only publishes GET status. Backfill is owned by opencode2;
+// clients poll this helper and do not POST unless a later API requires it.
+export const fetchV1MigrationGate = async ({
+  url,
+  headers = {},
+  signal,
+  fetchImpl = globalThis.fetch,
+} = {}) => {
+  try {
+    const response = await fetchImpl(url, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        ...headers,
+      },
+      signal,
+    });
+    const body = await response.json().catch(() => null);
+    return evaluateV1MigrationGate({
+      httpStatus: response.status,
+      body,
+    });
+  } catch (error) {
+    return evaluateV1MigrationGate({ error });
+  }
+};