CodeNomad/scripts/test-opencode-location-native.mjs
Pascal André aa51cbb9ff
fix(opencode): support earlier and modern V2 runtime contracts (#695)
Closes #694

## Status

This PR contains the stable 2.0.4 client migration, authenticated V2
discovery fallback and shared cross-runtime compatibility
implementation. The validation results below are local execution
evidence; the newly added CI matrix must also run on the updated PR
head.

## Published changes

- Pin UI/server to official `@opencode/client@2.0.4` and the bundled
pruning plugin to `@opencode/plugin@2.0.4`, with the corresponding
lockfile migration.
- Probe authenticated `/api/status` first. Fall back to earlier V2
`/api/health` **only on HTTP 404**, retaining the endpoint, credentials,
64 KiB response bound and absolute deadline. Authentication, transport,
server and malformed-status failures do not trigger fallback.
- Migrate the canonical UI/server contract to stable Forms, permission
decisions, command names, interrupts, renaming, forks, message lookup
and inbox delivery.
- Update the guarded proxy for stable methods/paths, native
active-session envelopes, native `cursor.next`, global Form directory
headers and current resource/plugin events.
- Follow the renamed upstream platform binary `bin/opencode(.exe)` while
retaining public CLI aliases.

Discovery success alone does not establish compatibility with an earlier
runtime's conversation APIs.

## Shared cross-runtime compatibility

### Shared cross-runtime integration

- Introduce one connection-scoped adapter under
`packages/server/src/opencode/compatibility/`, used by both the guarded
UI proxy and direct server callers, including Yolo.
- Select the contract using authenticated daemon identity rather than
the CLI executable's version. Recognize unknown publications through
authenticated, bounded OpenAPI negotiation instead of an exact
runtime-version gate.
- Bind authorization, client, transport and profile to one connection
generation. Fence actual mutation dispatch after asynchronous body
preparation; prevent late old streams from publishing or invalidating
their replacement.
- Translate earlier V2 routes, methods and payloads before sending.
Never retry a mutation speculatively after 400, 404, authentication or
transport failures.
- Normalize legacy HTTP inbox timestamps, including compaction
admission, before the pinned Solid reducer. Preserve the distinct native
SSE inbox schema and durable event metadata.
- Restore legacy catalog/content invalidation and permission-event
convergence. Preserve meaningful method/path/status/profile diagnostics
and native 401 error envelopes.

### Location authority and pruning

- Preserve legacy workspace identity internally through request
serialization, catalog/cache keys, Forms, imports, cursors, events and
exact move rollback. Modern public APIs continue to reject obsolete
workspace selectors.
- Authorize complete locations before translating directories or
synthesizing upstream Form/location headers. Keep native cursor tokens
unchanged.
- Preserve session/path ownership, worktree mutation fences and the
restricted proxy allowlist. Generic RPC, plugin management and
destructive revert commit remain blocked.
- Carry verified legacy identity through pruning membership checks,
preview and the existing transactional storage/claim fence; do not relax
deletion checks.
- Treat native idle records as control records, retaining
identity/outcome without fabricated assistant text.
- Add a common multi-runtime CI matrix and the audit/evidence register
in `dev-docs/OPENCODE_V2_COMPATIBILITY.md`, including preserved
historical architecture findings.

## Local validation

All native tests use isolated synthetic daemons, configuration and
databases, never the shared daemon or user storage.

| Check | Result |
| --- | --- |
| Same native suite on beta-19271, 2.0.3, 2.0.4 and 2.0.5 with pinned
client/plugin 2.0.4 | Passed |
| Full native pruning suite with non-null legacy workspace identity on
beta-19271 and 2.0.3 | Passed |
| Rendered UI on modern 2.0.5 and beta-19271 with non-null identity |
Passed |
| Native 2.0.5 suite inside Ubuntu/WSL, using a temporary Linux
filesystem root | Passed |
| Server tests (after CI follow-up) | 500 passed, 2 skipped |
| UI store tests | 441 passed |
| Electron native tests | 194 passed, 4 skipped |
| UI/server/Electron typechecks | Passed |
| UI/server and Electron production builds | Passed |
| Windows Tauri release executable (`--no-bundle`) | Passed |
| Electron/Tauri packaged-resource smoke checks | Passed |
| Desktop packaging invariants | 4 passed |
| `git diff --check` | Passed |

The native matrix exercises the actual shared connection, generated
client, UI fetch adapter and guarded proxy: voice-off/on instructions,
prompts, commands, session Shell, background Shell output
cursors/removal, UI/Yolo permission acceptance and rejection, busy inbox
delivery/cancellation, interrupt/wait, staged revert clearing,
session/global/worktree Forms, native pagination, export/import,
same-directory legacy identities, scoped events, foreign authority
refusal and exact rollback.

Pruning coverage includes actual storage identity and execution claims,
busy refusal, idempotency, competing admission, next-model payload, fork
isolation, pre-compaction history, restart, backend presence
disposal/reopening and crash expiry. Rendered tests cover
individual/group/response/session cleanup, confirmation counts,
persistence and reload.

## Autonomous gatekeeper review

Review/fix/retest loops concluded with no remaining actionable findings
in the reviewed transport/lifecycle/proxy,
identity/UI/events/pruning/rollback, scripts/CI and rendered-fixture
scopes.

Corrections included dispatch-generation races, compaction admission
normalization, independent negotiation cancellation, first-request
profile resolution, preservation of streamed 401 envelopes and direct
Shell/PTY identity propagation. A final rendered failure was traced to
the fixture awaiting only the first RPC of a cross-message deletion; the
fixture and regression now await every affected message. Production
deletion guards were not relaxed.

This scoped approval does not close the separately preserved historical
architecture findings.

## Validation boundaries

### CI follow-up

The first run on `a0c1c943`
([35142559235](https://github.com/NeuralNomadsAI/CodeNomad/actions/runs/35142559235))
failed in five native jobs. The local bundle tests had missed the
standalone npm archive's missing sibling import, and Windows legacy jobs
exposed a short-path versus canonical-path project comparison. The
dependent artifact-comment job reported that same build failure.

The follow-up makes the plugin's identity primitives self-contained,
adds an isolated npm-file-list regression for all exported entrypoints,
and corrects project identity selection with alias and nested-repository
regressions. The packed-plugin failure was reproduced before correction;
the corrected installed package passes the native suite on Windows 2.0.4
and Linux/WSL 2.0.4/2.0.5. The corrected 2.0.4 shipped bundle also
passes rendered/native pruning. Fresh full beta-19271 and 2.0.3
`--legacy-pruning` suites pass under a reproducing Windows short-path
TEMP root after the final exact-directory fix. Independent final reviews
approve packaging/documentation and worktree identity with zero
actionable findings. Remote checks on the new head remain the CI
authority; these are local follow-up results.

- Full interaction with the installed desktop application through
Developer Mode was not verified because Developer Mode is inactive. The
release executable and packaged-resource checks above are build/smoke
evidence, not a fresh-install interactive certification.
- Remote run
[35146390688](https://github.com/NeuralNomadsAI/CodeNomad/actions/runs/35146390688)
at `486e856d` passes all runtime-contract jobs, Windows/Linux native
pruning, service compatibility, general tests and both Tauri checks.
macOS passes packed-plugin loading/pruning, then times out on late
bundle discovery. The fixture now canonicalizes its root before daemon
startup to align `/var` configuration paths with `/private/var` FSEvents
paths. Late installation remains mandatory and asserts the plugin was
initially absent; failures now upload isolated diagnostic
logs/inventory/captures. Actual macOS confirmation remains pending on
the new head.
- Interactive native TUI validation was not performed.
- The passing WSL result is Linux-native execution inside WSL, not a
complete Windows-host/WSL desktop traversal. With the fixture's
configuration directory under `/mnt/c`, conversation/proxy checks passed
but late plugin discovery timed out; the otherwise equivalent
Linux-filesystem run passed. Mounted-configuration late discovery
remains a documented environment limitation.
- Other audited publications are declaration-reviewed, not individually
native-certified. The four-runtime matrix does not imply universal V2
compatibility.
- Earlier PR artifacts do not contain the completed cross-runtime
implementation; use artifacts built from the updated head. Local passing
results do not imply that the updated remote CI has completed.
2026-09-16 23:48:08 +02:00

234 lines
15 KiB
JavaScript

// Native location authority fixture. Invoke with an absolute CLI path, or call
// testNativeLocationIdentity from an already-isolated native test. No discovery,
// shared daemon, user config or non-fixture database is ever used.
import assert from "node:assert/strict"
import { spawn, execFileSync } from "node:child_process"
import { randomUUID } from "node:crypto"
import { mkdtemp, mkdir, realpath, writeFile } from "node:fs/promises"
import os from "node:os"
import path from "node:path"
import { fileURLToPath } from "node:url"
import { setTimeout as delay } from "node:timers/promises"
import { OpenCode } from "@opencode/client"
import { tsImport } from "tsx/esm/api"
import Fastify from "fastify"
import replyFrom from "@fastify/reply-from"
import pino from "pino"
export async function testNativeLocationIdentity({ client, connection, root }) {
const { contractProfile, runtimeIdentity } = await tsImport("../packages/server/src/opencode/compatibility/runtime.ts", import.meta.url)
const { locationRequestOptions } = await tsImport("../packages/server/src/opencode/compatibility/location.ts", import.meta.url)
const profile = connection.profile ? await connection.profile() : contractProfile(runtimeIdentity(connection.endpoint))
const directory = path.join(root, `identity-project-${randomUUID()}`)
const worktree = path.join(root, `identity-worktree-${randomUUID()}`)
await mkdir(directory)
const git = (...args) => execFileSync("git", args, { cwd: directory, stdio: "pipe" })
git("init")
git("config", "user.name", "CodeNomad isolated fixture")
git("config", "user.email", "fixture@example.invalid")
await writeFile(path.join(directory, "fixture.txt"), "synthetic native identity fixture\n")
git("add", "fixture.txt")
git("commit", "-m", "Synthetic native identity fixture")
git("worktree", "add", "-b", "fixture-worktree", worktree)
const rootLocation = await client.location.get({ location: { directory } })
const worktreeLocation = await client.location.get({ location: { directory: worktree } })
assert.equal(rootLocation.project.id, worktreeLocation.project.id)
if (profile !== "legacy") {
await assert.rejects(client.location.get({ location: { directory } }, locationRequestOptions({ directory, workspaceID: "wrk_fixture_one" })))
console.log("PASS: native modern worktree location and obsolete-selector rejection")
return
}
const locations = ["wrk_fixture_one", "wrk_fixture_two"].map(workspaceID => ({ directory: rootLocation.directory, workspaceID }))
for (const location of locations) {
const resolved = await client.location.get({ location: { directory: location.directory } }, locationRequestOptions(location))
assert.equal(resolved.directory, location.directory)
assert.equal(resolved.workspaceID, location.workspaceID)
}
const { registerInstanceProxyRoutes } = await tsImport("../packages/server/src/server/http-server.ts", import.meta.url)
const { createInstanceFetch } = await tsImport("../packages/ui/src/lib/sdk-manager.ts", import.meta.url)
const { EventBus } = await tsImport("../packages/server/src/events/bus.ts", import.meta.url)
const { InstanceEventBridge } = await tsImport("../packages/server/src/workspaces/instance-events.ts", import.meta.url)
const { evacuateWorktreeSessions } = await tsImport("../packages/server/src/workspaces/worktree-session-evacuation.ts", import.meta.url)
const logger = pino({ level: "silent" })
const normal = value => process.platform === "win32" ? path.resolve(value).toLowerCase() : path.resolve(value)
const ownsDirectory = value => [directory, worktree].some(candidate => normal(candidate) === normal(value))
const records = locations.map((location, index) => ({ id: String(index), path: directory, location }))
// A deliberately narrow fixture policy: each logical owner may access only its
// native workspace identity, including its synthetic linked worktree. Native
// location resolution, sessions, Form state, cursors and SSE are never mocked.
const manager = {
list: () => records,
get: id => records.find(record => record.id === id),
getSharedServiceConnection: async () => connection,
getSharedServiceEndpoint: async () => connection.endpoint,
getSharedServiceClient: async () => client,
getInstanceAuthorizationHeader: () => `Basic ${Buffer.from(`${connection.endpoint.auth.username}:${connection.endpoint.auth.password}`).toString("base64")}`,
getServiceDirectory: () => rootLocation.directory,
getServiceDirectoryForPath: async (_id, candidate) => ownsDirectory(candidate) ? candidate : undefined,
getWorktreeIdentityForPath: async (_id, candidate) => ownsDirectory(candidate) ? normal(candidate) : undefined,
ownsDirectory: async (_id, candidate) => ownsDirectory(candidate),
ownsPath: async (_id, candidate) => ownsDirectory(candidate),
ownsLocation: async (id, location) => {
if (!ownsDirectory(location.directory)) return false
if (location.workspaceID === undefined) return true
if (records.find(record => record.id === id)?.location.workspaceID !== location.workspaceID) return false
const resolved = await client.location.get({ location: { directory: location.directory } }, locationRequestOptions(location))
return normal(resolved.directory) === normal(location.directory) && resolved.workspaceID === location.workspaceID
},
subscribeToSharedService: signal => client.event.subscribe({ signal }),
}
const app = Fastify()
await app.register(replyFrom)
registerInstanceProxyRoutes(app, { workspaceManager: manager, logger, worktreeDeletionFence: { enter: () => () => {} } })
await app.listen({ host: "127.0.0.1", port: 0 })
const proxyClients = records.map(record => {
const baseUrl = `http://127.0.0.1:${app.server.address().port}/workspaces/${record.id}/instance/`
return OpenCode.make({ baseUrl, fetch: createInstanceFetch(baseUrl) })
})
const bus = new EventBus()
const routedForms = []
let connected = false
bus.on("instance.eventStatus", event => { if (event.status === "connected") connected = true })
bus.on("instance.event", event => { if (event.event.type === "form.created") routedForms.push(event) })
const bridge = new InstanceEventBridge({ workspaceManager: manager, eventBus: bus, logger })
const until = async predicate => {
const deadline = Date.now() + 15_000
while (!await predicate()) {
if (Date.now() > deadline) throw new Error("Native identity fixture timed out")
await delay(20)
}
}
const created = []
const forms = []
const formOptions = location => ({ headers: {
"x-opencode-directory": encodeURIComponent(location.directory), ...locationRequestOptions(location)?.headers,
} })
try {
bus.publish({ type: "workspace.started", workspace: records[0] })
await until(() => connected)
for (const [index, location] of locations.entries()) {
const proxy = proxyClients[index]
const options = locationRequestOptions(location)
for (let n = 0; n < 2; n++) {
const session = await proxy.session.create({ location: { directory: location.directory } }, options)
assert.deepEqual(session.location, location)
created.push(session)
}
const page = await proxy.session.list({ directory: location.directory, limit: 1 }, options)
assert.equal(page.data.length, 1)
assert.equal(page.data[0].location.workspaceID, location.workspaceID)
assert.ok(page.cursor.next)
const continuation = await proxy.session.list({ cursor: page.cursor.next })
assert.ok(continuation.data.every(session => session.location.workspaceID === location.workspaceID))
await assert.rejects(proxyClients[1 - index].session.list({ cursor: page.cursor.next }))
await assert.rejects(proxyClients[1 - index].session.get({ sessionID: page.data[0].id }))
for (const directory of [location.directory, worktreeLocation.directory]) {
const scoped = { ...location, directory }
const session = await proxy.session.create({ location: { directory } }, locationRequestOptions(scoped))
created.push(session)
const form = await client.session.form.create({ sessionID: "global", title: "Synthetic identity Form", fields: [{ key: "answer", type: "string" }] }, formOptions(scoped))
forms.push({ ...form, location: scoped, owner: index })
}
}
await until(() => routedForms.length === forms.length)
for (const form of forms) {
const routes = routedForms.filter(event => event.event.data.form.id === form.id)
assert.deepEqual(routes.map(event => event.instanceId), [String(form.owner)])
assert.deepEqual(routes[0].event.location, form.location)
const proxy = proxyClients[form.owner]
const list = await proxy.form.list({ location: { directory: form.location.directory } }, locationRequestOptions(form.location))
assert.ok(list.data.some(item => item.id === form.id))
const foreign = { ...form.location, workspaceID: locations[1 - form.owner].workspaceID }
const otherList = await proxyClients[1 - form.owner].form.list({ location: { directory: foreign.directory } }, locationRequestOptions(foreign))
assert.ok(!otherList.data.some(item => item.id === form.id))
await assert.rejects(proxyClients[1 - form.owner].session.form.cancel({ sessionID: "global", formID: form.id }, formOptions(form.location)))
if (form.owner === 0) await proxy.session.form.reply({ sessionID: "global", formID: form.id, answer: { answer: "fixture" } }, formOptions(form.location))
else await proxy.session.form.cancel({ sessionID: "global", formID: form.id }, formOptions(form.location))
assert.ok(!(await proxy.form.list({ location: { directory: form.location.directory } }, locationRequestOptions(form.location))).data.some(item => item.id === form.id))
}
for (const form of forms) {
// These real native lists return their resolved location even when empty.
// Spawning inside an arbitrary workspace ID requires an actual remote
// workspace provider; this fixture deliberately does not provision one.
for (const resource of ["shell", "pty"]) {
const listed = await proxyClients[form.owner][resource].list({ location: { directory: form.location.directory } }, locationRequestOptions(form.location))
assert.equal(listed.location.directory, form.location.directory)
assert.equal(listed.location.workspaceID, form.location.workspaceID, `proxy ${resource} list must retain native identity`)
}
}
await assert.rejects(evacuateWorktreeSessions({
client, projectDirectory: rootLocation.directory, targetDirectory: worktreeLocation.directory, rootDirectory: rootLocation.directory,
// Like the production manager's resolver, compare filesystem identities:
// Windows TEMP can be an 8.3 path while Git reports its long canonical root.
resolveDirectoryIdentity: directory => realpath(directory).catch(() => undefined),
resolveExactDirectory: directory => realpath(directory).catch(() => undefined),
remove: async () => {
for (const original of created.filter(session => session.location.directory === worktreeLocation.directory)) {
assert.deepEqual((await client.session.get({ sessionID: original.id })).location, { directory: rootLocation.directory })
}
throw new Error("Synthetic Git removal refusal")
},
}), /Synthetic Git removal refusal/)
for (const original of created) assert.deepEqual((await client.session.get({ sessionID: original.id })).location, original.location)
console.log("PASS: native same-directory identities, worktree/global Forms, Shell/PTY list scope, scoped SSE, foreign session/cursor refusal and exact move rollback")
} finally {
bridge.shutdown()
await Promise.allSettled(forms.map(form => client.session.form.cancel({ sessionID: "global", formID: form.id }, formOptions(form.location))))
await Promise.allSettled(created.map(session => client.session.remove({ sessionID: session.id })))
await app.close()
}
}
async function runIsolated(cli) {
if (!cli || !path.isAbsolute(cli)) throw new Error("Pass an absolute isolated CLI executable path")
const temporaryRoot = path.join(os.tmpdir(), "opencode")
await mkdir(temporaryRoot, { recursive: true })
const root = await mkdtemp(path.join(temporaryRoot, "codenomad-location-native-"))
const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("OPENCODE_") && !key.startsWith("XDG_")))
for (const key of ["XDG_DATA_HOME", "XDG_CONFIG_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME"]) env[key] = path.join(root, key)
const password = randomUUID()
Object.assign(env, {
HOME: root, USERPROFILE: root, OPENCODE_TEST_HOME: root,
OPENCODE_DB: path.join(root, "fixture.db"), OPENCODE_CONFIG_DIR: path.join(root, "config"),
OPENCODE_SERVER_PASSWORD: password, OPENCODE_CONFIG_PROJECT_DISABLE: "1",
OPENCODE_DISABLE_MODELS_FETCH: "1", OPENCODE_DISABLE_FFF: "1", OPENCODE_CONFIG_CONTENT: "{}",
})
await mkdir(env.OPENCODE_CONFIG_DIR)
let output = ""
const child = spawn(cli, ["serve", "--hostname", "127.0.0.1", "--port", "0", "--log-level", "debug", "--print-logs"], {
cwd: root, env, windowsHide: true,
})
const stopped = new Promise(resolve => child.once("close", resolve))
child.stdout.on("data", data => { output += data })
child.stderr.on("data", data => { output += data })
console.log(`Isolated location fixture: ${root}`)
try {
const deadline = Date.now() + 30_000
while (!/http:\/\/127\.0\.0\.1:\d+/.test(output)) {
if (child.exitCode !== null || Date.now() > deadline) throw new Error(`Isolated daemon failed to start: ${output}`)
await delay(20)
}
const baseUrl = output.match(/http:\/\/127\.0\.0\.1:\d+/)[0]
const endpoint = { url: baseUrl, auth: { type: "basic", username: "opencode", password } }
const authorization = `Basic ${Buffer.from(`opencode:${password}`).toString("base64")}`
let discovery = "status"
let response = await fetch(`${baseUrl}/api/status`, { headers: { authorization } })
if (response.status === 404) { discovery = "health"; response = await fetch(`${baseUrl}/api/health`, { headers: { authorization } }) }
assert.equal(response.status, 200)
const identity = await response.json()
const { rememberRuntime } = await tsImport("../packages/server/src/opencode/compatibility/runtime.ts", import.meta.url)
const { createRuntimeTransport } = await tsImport("../packages/server/src/opencode/compatibility/transport.ts", import.meta.url)
rememberRuntime(endpoint, { version: identity.version, pid: identity.pid, discovery })
const transport = createRuntimeTransport(endpoint)
const client = OpenCode.make({ baseUrl, fetch: transport.fetch })
const connection = { endpoint, client, ...transport, assertCurrent() {}, invalidate() {} }
console.log(`Testing official runtime ${identity.version}`)
await testNativeLocationIdentity({ client, connection, root })
} finally {
child.kill()
await stopped
await writeFile(path.join(root, "daemon.log"), output)
}
}
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await runIsolated(process.argv[2])