b51cbf96cf
* feat(#1943): extensionEvents vocabulary — separate from hookEvents (extension-system surface) * fix(#1943): re-export VALID_EXTENSION_EVENTS from gen-capability-registry (test import path) * fix(#1943): regenerate capability-registry.cjs + add changeset fragment * fix(#1943): import VALID_EXTENSION_EVENTS from validator, not gen-capability-registry (golden parity)
391 lines
17 KiB
JavaScript
391 lines
17 KiB
JavaScript
'use strict';
|
|
|
|
/**
|
|
* opencode-plugin-adapter.test.cjs — unit + integration coverage for the
|
|
* OpenCode native plugin adapter (.opencode/plugins/gsd-core.js, issue #1914).
|
|
*
|
|
* The adapter bridges OpenCode's plugin event bus onto GSD's existing hook
|
|
* scripts by spawning them as subprocesses. These tests exercise it WITHOUT a
|
|
* live OpenCode runtime by:
|
|
* 1. Unit-testing the pure translation helpers exposed on `_internals`.
|
|
* 2. Building a temp "install" layout (hooks/ with deterministic STUB hooks +
|
|
* gsd-core/ + plugins/gsd-core.js) and driving the plugin's returned
|
|
* handlers directly, asserting the real spawn bridge maps block/advisory/
|
|
* allow correctly and that REPO_ROOT resolves to the payload dir.
|
|
*
|
|
* Cross-platform note: filesystem-failure paths are not exercised here; the
|
|
* adapter's own error handling swallows spawn failures by design (a broken hook
|
|
* must never break a tool call), which the "missing hook" case covers.
|
|
*/
|
|
|
|
const { test } = require('node:test');
|
|
const assert = require('node:assert/strict');
|
|
const fs = require('node:fs');
|
|
const path = require('node:path');
|
|
const os = require('os');
|
|
const { cleanup } = require('./helpers.cjs');
|
|
|
|
const ADAPTER_SRC = path.join(__dirname, '..', '.opencode', 'plugins', 'gsd-core.js');
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Pure-helper unit tests (no filesystem / no spawn)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// Test-only helpers hang off the exported `server` function (see adapter export
|
|
// note) so they never appear as top-level exports the OpenCode loader iterates.
|
|
const _internals = require(ADAPTER_SRC).server._internals;
|
|
|
|
// Faithful emulation of OpenCode's loader: `getServerPlugin` accepts a bare
|
|
// function OR an object with a `.server` function, else the loader THROWS.
|
|
function getServerPlugin(entry) {
|
|
if (typeof entry === 'function') return entry;
|
|
if (entry && typeof entry === 'object' && typeof entry.server === 'function') return entry.server;
|
|
return null;
|
|
}
|
|
// Emulate the loader loop: `for (const entry of Object.values(mod)) { … throw if null }`.
|
|
function loaderExtract(mod) {
|
|
const servers = [];
|
|
for (const entry of Object.values(mod)) {
|
|
const s = getServerPlugin(entry);
|
|
if (!s) throw new TypeError('Plugin export is not a function');
|
|
servers.push(s);
|
|
}
|
|
return servers;
|
|
}
|
|
|
|
test('export survives the loader loop as raw CommonJS (require)', () => {
|
|
const mod = require(ADAPTER_SRC);
|
|
// `id` must be readable for identity/dedup...
|
|
assert.equal(mod.id, 'gsd-core');
|
|
// ...but NON-ENUMERABLE so it never lands in Object.values (would throw).
|
|
assert.ok(!Object.keys(mod).includes('id'), 'id must be non-enumerable');
|
|
const servers = loaderExtract(mod); // must not throw
|
|
assert.equal(servers.length, 1);
|
|
assert.equal(typeof servers[0], 'function');
|
|
// Internals hang off the server fn, never as a sibling top-level export.
|
|
assert.equal(mod._internals, undefined);
|
|
assert.equal(typeof mod.server._internals, 'object');
|
|
});
|
|
|
|
test('export survives the loader loop as an ESM/Bun namespace (default + synthesized)', () => {
|
|
const raw = require(ADAPTER_SRC);
|
|
// Worst-case ESM interop: default plus any lexer-synthesized named exports.
|
|
// Because module.exports is assigned from a variable, only `default` is
|
|
// realistically synthesized — but assert robustness even if `server` leaks.
|
|
for (const ns of [{ default: raw }, { default: raw, server: raw.server }]) {
|
|
assert.doesNotThrow(() => loaderExtract(ns), `loader threw on namespace ${Object.keys(ns)}`);
|
|
}
|
|
});
|
|
|
|
test('mapToolName maps OpenCode tool names to Claude names', () => {
|
|
assert.equal(_internals.mapToolName('read'), 'Read');
|
|
assert.equal(_internals.mapToolName('write'), 'Write');
|
|
assert.equal(_internals.mapToolName('edit'), 'Edit');
|
|
assert.equal(_internals.mapToolName('bash'), 'Bash');
|
|
assert.equal(_internals.mapToolName('apply_patch'), 'MultiEdit');
|
|
assert.equal(_internals.mapToolName('webfetch'), 'WebFetch');
|
|
// Unknown tools pass through unchanged; empty is empty.
|
|
assert.equal(_internals.mapToolName('mystery'), 'mystery');
|
|
assert.equal(_internals.mapToolName(''), '');
|
|
});
|
|
|
|
test('mapToolInput normalizes camelCase + snake_case arg keys', () => {
|
|
const out = _internals.mapToolInput({
|
|
filePath: '/a/b.txt',
|
|
oldString: 'x',
|
|
newString: 'y',
|
|
command: 'ls',
|
|
url: 'http://e',
|
|
});
|
|
assert.deepEqual(out, {
|
|
file_path: '/a/b.txt',
|
|
old_string: 'x',
|
|
new_string: 'y',
|
|
command: 'ls',
|
|
url: 'http://e',
|
|
});
|
|
// path/file_path aliases also resolve to file_path.
|
|
assert.equal(_internals.mapToolInput({ path: '/p' }).file_path, '/p');
|
|
assert.deepEqual(_internals.mapToolInput(null), {});
|
|
});
|
|
|
|
test('parseFrontmatter splits frontmatter and body', () => {
|
|
const { frontmatter, body } = _internals.parseFrontmatter(
|
|
'---\ndescription: A command\nmode: primary\n---\nHello body\n',
|
|
);
|
|
assert.equal(frontmatter.description, 'A command');
|
|
assert.equal(frontmatter.mode, 'primary');
|
|
assert.equal(body, 'Hello body\n');
|
|
// No frontmatter → whole content is body.
|
|
const plain = _internals.parseFrontmatter('just text');
|
|
assert.deepEqual(plain.frontmatter, {});
|
|
assert.equal(plain.body, 'just text');
|
|
});
|
|
|
|
test('handleHookResult: block decision throws with the hook reason', () => {
|
|
assert.throws(
|
|
() => _internals.handleHookResult(
|
|
{ stdout: JSON.stringify({ decision: 'block', reason: 'blocked!' }), exitCode: 0 },
|
|
),
|
|
/blocked!/,
|
|
);
|
|
});
|
|
|
|
test('handleHookResult: exit code 2 is a hard block even without JSON', () => {
|
|
assert.throws(
|
|
() => _internals.handleHookResult({ stdout: '', exitCode: 2 }),
|
|
/Blocked by GSD hook/,
|
|
);
|
|
});
|
|
|
|
test('handleHookResult: advisory sets metadata + does not throw', () => {
|
|
const output = {};
|
|
assert.doesNotThrow(() =>
|
|
_internals.handleHookResult(
|
|
{ stdout: JSON.stringify({ hookSpecificOutput: { additionalContext: 'heads up' } }), exitCode: 0 },
|
|
output,
|
|
),
|
|
);
|
|
assert.deepEqual(output.metadata._gsdAdvisory, ['heads up']);
|
|
});
|
|
|
|
test('handleHookResult: multiple advisories accumulate (no clobber)', () => {
|
|
// A single tool call runs several advisory hooks in sequence; each must be
|
|
// preserved, not overwritten by the next.
|
|
const output = {};
|
|
const advise = (ctx) =>
|
|
_internals.handleHookResult(
|
|
{ stdout: JSON.stringify({ hookSpecificOutput: { additionalContext: ctx } }), exitCode: 0 },
|
|
output,
|
|
);
|
|
advise('prompt-guard note');
|
|
advise('read-guard note');
|
|
advise('workflow-guard note');
|
|
assert.deepEqual(output.metadata._gsdAdvisory, [
|
|
'prompt-guard note',
|
|
'read-guard note',
|
|
'workflow-guard note',
|
|
]);
|
|
});
|
|
|
|
test('handleHookResult: silent allow is a no-op', () => {
|
|
const output = {};
|
|
assert.doesNotThrow(() => _internals.handleHookResult({ stdout: '', exitCode: 0 }, output));
|
|
assert.deepEqual(output, {});
|
|
});
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Integration: drive the plugin against a temp install layout with STUB hooks
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// Build a self-contained payload dir: <root>/hooks/<stub>.js, <root>/gsd-core/,
|
|
// and <root>/plugins/gsd-core.js (a copy of the adapter). Returns the loaded
|
|
// plugin module for that layout. Each stub hook echoes a fixed JSON verdict.
|
|
function buildInstalledLayout(t, stubHooks) {
|
|
// realpath so `root` matches Node's realpath-resolved __dirname inside the
|
|
// copied plugin (macOS /var → /private/var symlink would otherwise diverge).
|
|
const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-oc-plugin-')));
|
|
t.after(() => cleanup(root));
|
|
|
|
fs.mkdirSync(path.join(root, 'hooks'), { recursive: true });
|
|
fs.mkdirSync(path.join(root, 'gsd-core', 'workflows'), { recursive: true });
|
|
fs.mkdirSync(path.join(root, 'plugins'), { recursive: true });
|
|
|
|
for (const [name, jsBody] of Object.entries(stubHooks)) {
|
|
fs.writeFileSync(path.join(root, 'hooks', name), jsBody);
|
|
}
|
|
|
|
// Copy the real adapter into the payload's plugins/ dir so REPO_ROOT resolves
|
|
// to `root` via the walk-up probe (root has both hooks/ and gsd-core/).
|
|
const dest = path.join(root, 'plugins', 'gsd-core.js');
|
|
fs.copyFileSync(ADAPTER_SRC, dest);
|
|
// Fresh module instance (bypass require cache — each layout is distinct).
|
|
delete require.cache[require.resolve(dest)];
|
|
const mod = require(dest);
|
|
return { root, mod };
|
|
}
|
|
|
|
// A stub hook that reads stdin (ignored) and prints the given verdict JSON.
|
|
function stubHook(verdictJson, exitCode = 0) {
|
|
return `
|
|
let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{
|
|
process.stdout.write(${JSON.stringify(verdictJson)});
|
|
process.exit(${exitCode});
|
|
});
|
|
process.stdin.on('error',()=>process.exit(${exitCode}));
|
|
if(process.stdin.isTTY){process.stdout.write(${JSON.stringify(verdictJson)});process.exit(${exitCode});}
|
|
`;
|
|
}
|
|
|
|
test('REPO_ROOT resolves to the payload dir in an installed layout', (t) => {
|
|
const { root, mod } = buildInstalledLayout(t, {});
|
|
assert.equal(mod.server._internals.REPO_ROOT, fs.realpathSync(root));
|
|
// No source commands/gsd/ present → treated as installed (not package) tree.
|
|
assert.equal(mod.server._internals.IS_PACKAGE_TREE, false);
|
|
});
|
|
|
|
test('tool.execute.before: a blocking hook aborts the tool call (throws)', async (t) => {
|
|
const { mod } = buildInstalledLayout(t, {
|
|
'gsd-prompt-guard.js': stubHook(JSON.stringify({ decision: 'block', reason: 'injection detected' })),
|
|
});
|
|
const handlers = await mod.server({ directory: process.cwd() });
|
|
await assert.rejects(
|
|
() => handlers['tool.execute.before'](
|
|
{ tool: 'write' },
|
|
{ args: { filePath: '/proj/.planning/x.md', content: 'evil' } },
|
|
),
|
|
/injection detected/,
|
|
);
|
|
});
|
|
|
|
test('tool.execute.before: a silent hook allows the tool call (no throw)', async (t) => {
|
|
const { mod } = buildInstalledLayout(t, {
|
|
'gsd-prompt-guard.js': stubHook(''),
|
|
'gsd-read-guard.js': stubHook(''),
|
|
'gsd-worktree-path-guard.js': stubHook(''),
|
|
'gsd-workflow-guard.js': stubHook(''),
|
|
});
|
|
const handlers = await mod.server({ directory: process.cwd() });
|
|
await assert.doesNotReject(() =>
|
|
handlers['tool.execute.before'](
|
|
{ tool: 'write' },
|
|
{ args: { filePath: '/proj/notes.md', content: 'ok' } },
|
|
),
|
|
);
|
|
});
|
|
|
|
test('tool.execute.after: Read content rewriting maps ~/.claude/gsd-core paths', async (t) => {
|
|
const { root, mod } = buildInstalledLayout(t, {
|
|
'gsd-read-injection-scanner.js': stubHook(''),
|
|
});
|
|
const handlers = await mod.server({ directory: process.cwd() });
|
|
// A file under the payload's gsd-core/workflows is a GSD-managed file, so its
|
|
// Read output is rewritten (canonical ~/.claude/gsd-core/ → real payload path).
|
|
const managed = path.join(root, 'gsd-core', 'workflows', 'x.md');
|
|
const output = { output: 'see ~/.claude/gsd-core/references/foo.md for details' };
|
|
await handlers['tool.execute.after']({ tool: 'read', args: { filePath: managed } }, output);
|
|
// The adapter rewrites `~/.claude/gsd-core/` → `${GSD_CORE}/`, where GSD_CORE
|
|
// is `path.join(root, 'gsd-core')` (OS-native separators). Assert with a plain
|
|
// string include, NOT a RegExp built from a path — on Windows the backslashes
|
|
// in the path would be interpreted as regex escapes and never match.
|
|
const expected = path.join(root, 'gsd-core') + '/references/foo.md';
|
|
assert.ok(
|
|
output.output.includes(expected),
|
|
`expected rewritten path "${expected}" in output: ${output.output}`,
|
|
);
|
|
assert.ok(
|
|
!output.output.includes('~/.claude/gsd-core/'),
|
|
'canonical ~/.claude/gsd-core/ prefix must be rewritten away',
|
|
);
|
|
});
|
|
|
|
test('missing hook script is a silent allow (never breaks the tool call)', async (t) => {
|
|
// No hook stubs written at all → every runHook finds no file → silent allow.
|
|
const { mod } = buildInstalledLayout(t, {});
|
|
const handlers = await mod.server({ directory: process.cwd() });
|
|
await assert.doesNotReject(() =>
|
|
handlers['tool.execute.before'](
|
|
{ tool: 'edit' },
|
|
{ args: { filePath: '/proj/a.md', old_string: 'a', new_string: 'b' } },
|
|
),
|
|
);
|
|
});
|
|
|
|
test('config hook is a no-op in installed (non-package) layout', async (t) => {
|
|
const { mod } = buildInstalledLayout(t, {});
|
|
const handlers = await mod.server({ directory: process.cwd() });
|
|
const config = {};
|
|
await handlers.config(config);
|
|
// No commands/agents/skills registered — native file copy owns that surface.
|
|
assert.deepEqual(config, {});
|
|
});
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Session lifecycle + opencode-subset surface parity (#1682 Slice 1b/c)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
test('session.idle event is handled (no-op sentinel) without throwing', async (t) => {
|
|
const { mod } = buildInstalledLayout(t, {});
|
|
const handlers = await mod.server({ directory: process.cwd() });
|
|
// session.idle ↔ Claude Stop lifecycle point; recognized no-op today.
|
|
await assert.doesNotReject(() => handlers.event({ event: { type: 'session.idle' } }));
|
|
});
|
|
|
|
test('experimental.session.compacting injects the GSD state breadcrumb', async (t) => {
|
|
const { mod } = buildInstalledLayout(t, { 'gsd-context-monitor.js': stubHook('') });
|
|
const handlers = await mod.server({ directory: process.cwd() });
|
|
// Compaction fires only with an active session; session.created sets it.
|
|
await handlers.event({
|
|
event: { type: 'session.created', properties: { info: { id: 's1', directory: process.cwd() } } },
|
|
});
|
|
const output = {};
|
|
await handlers['experimental.session.compacting']({}, output);
|
|
assert.ok(Array.isArray(output.context) && output.context.length > 0, 'compaction injects a GSD breadcrumb');
|
|
assert.ok(output.context.some((c) => /GSD/.test(c)), 'breadcrumb is GSD-tagged');
|
|
});
|
|
|
|
test('plugin implements the full declared opencode extension-event surface (Claude parity — #1943)', async (t) => {
|
|
const { extensionEventSurfaceFor } = require('../gsd-core/bin/lib/host-integration.cjs');
|
|
const surface = extensionEventSurfaceFor('opencode');
|
|
assert.ok(surface, 'opencode is a consumed extensionEvents dialect (non-null surface)');
|
|
// The engine — not the host bus — owns workflow-phase sequencing on this host.
|
|
assert.ok(!surface.some((e) => /plan:|verify:|ship:/.test(e)),
|
|
'opencode extension events include no workflow-phase events');
|
|
|
|
const { mod } = buildInstalledLayout(t, {});
|
|
const handlers = await mod.server({ directory: process.cwd() });
|
|
// Tool + compaction events are top-level handler keys.
|
|
for (const ev of ['tool.execute.before', 'tool.execute.after', 'experimental.session.compacting']) {
|
|
assert.equal(typeof handlers[ev], 'function', `plugin exposes a handler for ${ev}`);
|
|
}
|
|
// Session/file events dispatch through the `event` handler.
|
|
assert.equal(typeof handlers.event, 'function', 'plugin exposes an event dispatcher');
|
|
// Every declared surface event resolves to a plugin handler.
|
|
for (const ev of surface) {
|
|
const covered = typeof handlers[ev] === 'function'
|
|
|| ev === 'session.created' || ev === 'session.idle' || ev === 'file.edited';
|
|
assert.ok(covered, `plugin covers opencode extension event: ${ev}`);
|
|
}
|
|
});
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Installer integration: copy → manifest → uninstall (real bin/install.js)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
test('installer copies plugin as .js, records it in the manifest, and removes it on uninstall', (t) => {
|
|
const { spawnSync } = require('node:child_process');
|
|
const installer = path.join(__dirname, '..', 'bin', 'install.js');
|
|
const cfg = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-oc-install-')));
|
|
t.after(() => cleanup(cfg));
|
|
|
|
const run = (args) =>
|
|
spawnSync(process.execPath, [installer, '--opencode', '--global', '--config-dir', cfg, ...args], {
|
|
encoding: 'utf8',
|
|
});
|
|
|
|
// Install
|
|
const install = run([]);
|
|
assert.equal(install.status, 0, `install failed: ${install.stderr}`);
|
|
|
|
const pluginPath = path.join(cfg, 'plugins', 'gsd-core.js');
|
|
assert.ok(fs.existsSync(pluginPath), 'plugin must land at plugins/gsd-core.js (matches OpenCode {plugin,plugins}/*.{ts,js} glob)');
|
|
assert.ok(!fs.existsSync(path.join(cfg, 'plugins', 'gsd-core.cjs')), 'must NOT ship a .cjs (never auto-discovered)');
|
|
|
|
// Manifest records the plugin for drift/uninstall accounting.
|
|
const manifest = JSON.parse(fs.readFileSync(path.join(cfg, 'gsd-file-manifest.json'), 'utf8'));
|
|
assert.ok(manifest.files['plugins/gsd-core.js'], 'manifest must track plugins/gsd-core.js');
|
|
|
|
// The installed plugin loads and resolves REPO_ROOT to the config dir.
|
|
delete require.cache[require.resolve(pluginPath)];
|
|
const installed = require(pluginPath);
|
|
assert.equal(installed.id, 'gsd-core');
|
|
assert.equal(installed.server._internals.REPO_ROOT, cfg);
|
|
assert.equal(installed.server._internals.IS_PACKAGE_TREE, false);
|
|
|
|
// Uninstall removes the plugin and prunes the (now empty) plugins/ dir.
|
|
const uninstall = run(['--uninstall']);
|
|
assert.equal(uninstall.status, 0, `uninstall failed: ${uninstall.stderr}`);
|
|
assert.ok(!fs.existsSync(pluginPath), 'plugin must be removed on uninstall');
|
|
assert.ok(!fs.existsSync(path.join(cfg, 'plugins')), 'empty plugins/ dir must be pruned');
|
|
});
|