chore(node-sdk): release 2.1.0

Claude-Session: https://claude.ai/code/session_01Agoc9bRVE9KL7mmWtey9Vq

.npmignore

@@ -1,5 +0,0 @@
-src/
-tsconfig.json
-.gitignore
-node_modules/
-*.tsbuildinfo

AGENTS.md

@@ -51,6 +51,16 @@ This repository owns the published `@elydora/sdk` package, its `elydora` CLI, lo
 - Read runtime config, private keys, status cache, chain state, and error logs through physical-file descriptors with identity checks. Write cache and validated chain state atomically, and append error logs through no-follow owner-only descriptors. Preserve rollback artifacts when recovery cannot safely restore an original file and include the recovery path in the surfaced error.
 - Resolve every agent runtime directory as one physical child of `~/.elydora`; reject separators, traversal segments, cross-platform reserved names, symbolic-link directories, and linked identity configs before writes or recursive removal. Validate stored directory identity before changing host CLI configuration, and require an explicit agent ID when discovery is ambiguous.
 
+## Shared Modules
+
+- `src/plugins/common.ts`: path and agent-id comparison, error helpers, size limits, `managedScriptReference`.
+- `src/plugins/shell-command.ts`: POSIX and PowerShell quoting, encoded Windows commands, command parsers, `isNodeExecutable`.
+- `src/plugins/managed-installation.ts` and `managed-transaction.ts`: preflight, prepare, and rollback-capable commit.
+- `src/plugins/managed-runtime-status.ts`: runtime config and key validation; `managedRuntimeFilesExist` and `managedRuntimePresent`.
+- `src/plugins/strict-json.ts` and `jsonc-edit.ts`: strict parsing and formatting-preserving JSONC edits.
+- `test-support/harness.mjs`: process runner, fake API server, fixture root, plugin runner; provider helper files wrap it.
+- Put logic used by two providers in a shared module; keep provider-specific rules in `<provider>-*.ts`.
+
 ## Verification
 
 Run the focused adapter test during development, then execute all release gates before commit:

README.md

@@ -124,7 +124,7 @@ const client = new ElydoraClient({
   baseUrl?: string,     // API base URL (default: https://api.elydora.com)
   ttlMs?: number,       // Operation TTL in ms (default: 30000)
   maxRetries?: number,  // Max retries on transient failures (default: 3)
-  kid?: string,         // Key ID (default: {agentId}-key-v1)
+  kid?: string,         // Key ID (default: {agentId}-key-1)
 });
 ```
 
@@ -143,8 +143,13 @@ client.setToken(auth.token);
 // Get current authenticated user profile
 const { user } = await client.getMe();
 
-// Issue a new API token (with optional TTL in seconds)
+// Issue an API token (optional TTL in seconds) and use it for later calls
 const { token, expires_at } = await client.issueApiToken(3600);
+client.setToken(token);
+
+// Rotate the API token the client currently holds
+const rotated = await client.rotateApiToken();
+client.setToken(rotated.token);
 ```
 
 ### Operations
@@ -183,6 +188,9 @@ const agent = await client.registerAgent({
 // Get agent details
 const details = await client.getAgent(agentId);
 
+// Change the integration type
+await client.updateAgent(agentId, 'cursor');
+
 // Freeze an agent
 await client.freezeAgent(agentId, 'security review');
 
@@ -245,7 +253,21 @@ const { keys } = await client.getJWKS();
 ```typescript
 // Check API health (no authentication required)
 const health = await client.health();
-// health.status, health.version, health.protocol_version, health.timestamp
+// health.status, health.version, health.protocol_version, health.capabilities, health.timestamp
+
+// Check dependency health (D1, auth storage, R2, KV)
+const deep = await client.deepHealth();
+```
+
+### Webhooks, Members, Admin Events
+
+```typescript
+const { webhooks } = await client.listWebhooks();
+const { webhook } = await client.registerWebhook(url, ['agent.status_changed'], secret);
+await client.deleteWebhook(webhook.webhook_id);
+
+const { members } = await client.listMembers();
+const { events } = await client.listAdminEvents(50);
 ```
 
 ### Client State

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elydora/sdk",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Node.js/TypeScript SDK for the Elydora tamper-evident audit platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,8 +8,7 @@
     "elydora": "dist/cli.js"
   },
   "files": [
-    "dist",
-    "scripts"
+    "dist"
   ],
   "scripts": {
     "build": "tsc && node scripts/postbuild.mjs",

src/plugins/common.ts

@@ -1,3 +1,4 @@
+import os from 'node:os';
 import path from 'node:path';
 
 export const MAX_SECRET_BYTES = 64 * 1024;
@@ -16,12 +17,13 @@ export function hasCode(error: unknown, code: string): boolean {
   return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
 }
 
+export function pathKey(filePath: string): string {
+  const resolved = path.resolve(filePath);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
 export function samePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
+  return pathKey(left) === pathKey(right);
 }
 
 export function sameAgentId(left: unknown, right: string): boolean {
@@ -29,3 +31,20 @@ export function sameAgentId(left: unknown, right: string): boolean {
     ? left.toLowerCase() === right.toLowerCase()
     : left === right);
 }
+
+export interface ManagedScriptReference {
+  readonly agentId: string;
+  readonly scriptPath: string;
+}
+
+// Accepts only ~/.elydora/<agentId>/<scriptName>.
+export function managedScriptReference(
+  scriptPath: string,
+  scriptName: string,
+): ManagedScriptReference | undefined {
+  if (!path.isAbsolute(scriptPath) || path.basename(scriptPath) !== scriptName) return undefined;
+  const agentDirectory = path.dirname(scriptPath);
+  if (!samePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) return undefined;
+  const agentId = path.basename(agentDirectory);
+  return agentId && agentId !== '.' && agentId !== '..' ? { agentId, scriptPath } : undefined;
+}

src/plugins/droid-config.ts

@@ -1,9 +1,5 @@
-import {
-  applyEdits,
-  modify,
-  type FormattingOptions,
-  type JSONPath,
-} from 'jsonc-parser';
+import type { JSONPath } from 'jsonc-parser';
+import { changeJsonc } from './jsonc-edit.js';
 import type { FileSnapshot } from './managed-files.js';
 import type { DroidPolicyState } from './droid-policy.js';
 import {
@@ -158,23 +154,6 @@ function eventPath(document: DroidDocument, event: string): JSONPath {
   return [...document.basePath, event];
 }
 
-function formatting(raw: string): FormattingOptions {
-  const indentation = /\r?\n([ \t]+)\S/.exec(raw)?.[1];
-  const insertSpaces = !indentation?.includes('\t');
-  return {
-    eol: raw.includes('\r\n') ? '\r\n' : '\n',
-    insertSpaces,
-    tabSize: insertSpaces ? Math.max(1, indentation?.length ?? 2) : 1,
-  };
-}
-
-function change(raw: string, path: JSONPath, value: unknown, isArrayInsertion = false): string {
-  return applyEdits(raw, modify(raw, path, value, {
-    formattingOptions: formatting(raw),
-    isArrayInsertion,
-  }));
-}
-
 function currentDocument(document: DroidDocument, raw: string): DroidDocument {
   return parseDocument({
     exists: document.exists,
@@ -194,17 +173,17 @@ function removeManagedEntries(document: DroidDocument, raw: string, agentId?: st
     for (const removal of eventRemovals) {
       const groupPath = [...eventPath(document, event), removal.groupIndex];
       if (removal.removeGroup) {
-        raw = change(raw, groupPath, undefined);
+        raw = changeJsonc(raw, groupPath, undefined);
         continue;
       }
       for (const handlerIndex of [...removal.handlerIndexes].sort((left, right) => right - left)) {
-        raw = change(raw, [...groupPath, 'hooks', handlerIndex], undefined);
+        raw = changeJsonc(raw, [...groupPath, 'hooks', handlerIndex], undefined);
       }
     }
     if (eventRemovals.length > 0) {
       const current = currentDocument(document, raw);
       if ((current.hooks[event] ?? []).length === 0) {
-        raw = change(raw, eventPath(document, event), undefined);
+        raw = changeJsonc(raw, eventPath(document, event), undefined);
       }
     }
   }
@@ -220,9 +199,9 @@ function appendGroup(
   const current = currentDocument(document, raw);
   if (Object.prototype.hasOwnProperty.call(current.hooks, event)) {
     const groups = current.hooks[event] ?? [];
-    return change(raw, [...eventPath(document, event), groups.length], group, true);
+    return changeJsonc(raw, [...eventPath(document, event), groups.length], group, true);
   }
-  return change(raw, eventPath(document, event), [group]);
+  return changeJsonc(raw, eventPath(document, event), [group]);
 }
 
 function hookFileIsEmpty(document: DroidDocument, raw: string): boolean {

src/plugins/gemini-config.ts

@@ -1,14 +1,4 @@
-import {
-  applyEdits,
-  modify,
-  parse,
-  parseTree,
-  printParseErrorCode,
-  type FormattingOptions,
-  type JSONPath,
-  type Node,
-  type ParseError,
-} from 'jsonc-parser';
+import type { JSONPath } from 'jsonc-parser';
 import {
   MANAGED_EVENTS,
   managedGeminiRemovals,
@@ -19,7 +9,8 @@ import {
   type GeminiHooks,
   type ManagedGeminiEvent,
 } from './gemini-contract.js';
-import { isObject, type JsonObject } from './strict-json.js';
+import { changeJsonc } from './jsonc-edit.js';
+import { parseCommentedJsonObject, type JsonObject } from './strict-json.js';
 
 export const GEMINI_OWNED_FILE_MARKER = '// Managed by Elydora';
 
@@ -46,53 +37,9 @@ interface DocumentOptions {
   readonly raw: string;
 }
 
-function rejectDuplicateKeys(
-  node: Node | undefined,
-  label: string,
-  location: string[] = [],
-): void {
-  if (!node) return;
-  if (node.type === 'object') {
-    const keys = new Set<string>();
-    for (const property of node.children ?? []) {
-      const key = String(property.children?.[0]?.value);
-      const childLocation = [...location, key];
-      if (keys.has(key)) {
-        throw new Error(`${label} contains duplicate field "${childLocation.join('.')}"`);
-      }
-      keys.add(key);
-      rejectDuplicateKeys(property.children?.[1], label, childLocation);
-    }
-    return;
-  }
-  if (node.type === 'array') {
-    for (const child of node.children ?? []) rejectDuplicateKeys(child, label, location);
-  }
-}
-
-function parseJsoncObject(raw: string, label: string): JsonObject {
-  const errors: ParseError[] = [];
-  const value: unknown = parse(raw, errors, {
-    allowTrailingComma: false,
-    disallowComments: false,
-  });
-  if (errors.length > 0) {
-    const details = errors
-      .map((error) => `${printParseErrorCode(error.error)} at offset ${error.offset}`)
-      .join(', ');
-    throw new Error(`Failed to parse ${label}: ${details}`);
-  }
-  if (!isObject(value)) throw new Error(`${label} must contain a JSON object`);
-  rejectDuplicateKeys(parseTree(raw, [], {
-    allowTrailingComma: false,
-    disallowComments: false,
-  }), label);
-  return value;
-}
-
 export function parseGeminiDocument(options: DocumentOptions): GeminiDocument {
   const label = `Gemini CLI user settings at ${options.filePath}`;
-  const root = parseJsoncObject(options.raw, label);
+  const root = parseCommentedJsonObject(options.raw, label);
   const hasHooksContainer = Object.hasOwn(root, 'hooks');
   return {
     ...options,
@@ -112,28 +59,6 @@ export function createGeminiDocument(filePath: string): GeminiDocument {
   });
 }
 
-function formatting(raw: string): FormattingOptions {
-  const indentation = /\r?\n([ \t]+)\S/.exec(raw)?.[1];
-  const insertSpaces = !indentation?.includes('\t');
-  return {
-    eol: raw.includes('\r\n') ? '\r\n' : '\n',
-    insertSpaces,
-    tabSize: insertSpaces ? Math.max(1, indentation?.length ?? 2) : 1,
-  };
-}
-
-function change(
-  raw: string,
-  jsonPath: JSONPath,
-  value: unknown,
-  isArrayInsertion = false,
-): string {
-  return applyEdits(raw, modify(raw, jsonPath, value, {
-    formattingOptions: formatting(raw),
-    isArrayInsertion,
-  }));
-}
-
 function currentDocument(document: GeminiDocument, raw: string): GeminiDocument {
   return parseGeminiDocument({
     exists: document.exists,
@@ -155,25 +80,25 @@ function removeManagedEntries(
     for (const removal of eventRemovals) {
       const groupPath: JSONPath = ['hooks', event, removal.groupIndex];
       if (removal.removeGroup) {
-        raw = change(raw, groupPath, undefined);
+        raw = changeJsonc(raw, groupPath, undefined);
         continue;
       }
       for (const handlerIndex of [...removal.handlerIndexes].sort(
         (left, right) => right - left,
       )) {
-        raw = change(raw, [...groupPath, 'hooks', handlerIndex], undefined);
+        raw = changeJsonc(raw, [...groupPath, 'hooks', handlerIndex], undefined);
       }
     }
     if (eventRemovals.length > 0) {
       const current = currentDocument(document, raw);
       if ((current.hooks[event] ?? []).length === 0) {
-        raw = change(raw, ['hooks', event], undefined);
+        raw = changeJsonc(raw, ['hooks', event], undefined);
       }
     }
   }
   const current = currentDocument(document, raw);
   if (current.hasHooksContainer && Object.keys(current.hooks).length === 0) {
-    raw = change(raw, ['hooks'], undefined);
+    raw = changeJsonc(raw, ['hooks'], undefined);
   }
   return raw;
 }
@@ -186,9 +111,9 @@ function appendGroup(
 ): string {
   const current = currentDocument(document, raw);
   if (current.hooks[event]) {
-    return change(raw, ['hooks', event, current.hooks[event].length], group, true);
+    return changeJsonc(raw, ['hooks', event, current.hooks[event].length], group, true);
   }
-  return change(raw, ['hooks', event], [group]);
+  return changeJsonc(raw, ['hooks', event], [group]);
 }
 
 export function renderGeminiDocument(

src/plugins/grok-command.ts

@@ -1,140 +1,21 @@
-import os from 'node:os';
 import path from 'node:path';
+import { managedScriptReference, type ManagedScriptReference } from './common.js';
+import {
+  encodedWindowsCommand,
+  isNodeExecutable,
+  parseEncodedWindowsCommand,
+  parseLegacyWindowsCommand,
+  parsePosixCommand,
+  posixSource,
+} from './shell-command.js';
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
-export interface GrokRuntimeReference {
-  readonly agentId: string;
-  readonly scriptPath: string;
-}
-
-export function sameGrokPath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameGrokAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
-function windowsPowerShellPath(): string {
-  const configuredRoot = process.platform === 'win32' ? process.env.SystemRoot : undefined;
-  const systemRoot = configuredRoot
-    && path.win32.isAbsolute(configuredRoot)
-    && !/["%\r\n]/.test(configuredRoot)
-    ? configuredRoot
-    : 'C:\\Windows';
-  return path.win32.join(
-    systemRoot,
-    'System32',
-    'WindowsPowerShell',
-    'v1.0',
-    'powershell.exe',
-  );
-}
-
-function windowsCommand(scriptPath: string): string {
-  const source = `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`;
-  const encoded = Buffer.from(source, 'utf16le').toString('base64');
-  return `"${windowsPowerShellPath()}" -NoLogo -NoProfile -NonInteractive -EncodedCommand ${encoded}`;
-}
+export type GrokRuntimeReference = ManagedScriptReference;
 
 export function buildGrokCommand(scriptPath: string): string {
   if (!path.isAbsolute(process.execPath) || !path.isAbsolute(scriptPath)) {
     throw new Error('Grok hook commands require absolute executable and script paths');
   }
-  return process.platform === 'win32'
-    ? windowsCommand(scriptPath)
-    : `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
-}
-
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parsePosixCommand(command: string): readonly [string, string] | undefined {
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length) return undefined;
-  return [executable.value, script.value];
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parsePowerShellSource(source: string): readonly [string, string] | undefined {
-  if (!source.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(source, 2);
-  if (!executable || source[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(source, executable.next + 1);
-  if (!script || source.slice(script.next) !== '; exit $LASTEXITCODE') return undefined;
-  return [executable.value, script.value];
-}
-
-function parseWindowsCommand(command: string): readonly [string, string] | undefined {
-  const match = /^"([^"\r\n]+)" -NoLogo -NoProfile -NonInteractive -EncodedCommand ([A-Za-z0-9+/]+={0,2})$/.exec(command);
-  if (!match
-    || !path.win32.isAbsolute(match[1])
-    || path.win32.basename(match[1]).toLowerCase() !== 'powershell.exe') return undefined;
-  const encoded = match[2];
-  const buffer = Buffer.from(encoded, 'base64');
-  if (buffer.length % 2 !== 0 || buffer.toString('base64') !== encoded) return undefined;
-  return parsePowerShellSource(buffer.toString('utf16le'));
-}
-
-function parseLegacyWindowsCommand(command: string): readonly [string, string] | undefined {
-  const match = /^"([^"\r\n]+)" "([^"\r\n]+)"$/.exec(command);
-  return match ? [match[1], match[2]] : undefined;
-}
-
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath).toLowerCase();
-  return basename === 'node' || basename === 'node.exe';
+  return process.platform === 'win32' ? encodedWindowsCommand(scriptPath) : posixSource(scriptPath);
 }
 
 export function grokRuntimeReference(
@@ -142,18 +23,8 @@ export function grokRuntimeReference(
   scriptName: string,
 ): GrokRuntimeReference | undefined {
   const parsed = parsePosixCommand(command)
-    ?? parseWindowsCommand(command)
+    ?? parseEncodedWindowsCommand(command)
     ?? parseLegacyWindowsCommand(command);
-  if (!parsed
-    || !path.isAbsolute(parsed[0])
-    || !path.isAbsolute(parsed[1])
-    || !isNodeExecutable(parsed[0])
-    || path.basename(parsed[1]) !== scriptName) return undefined;
-  const agentDirectory = path.dirname(parsed[1]);
-  if (!sameGrokPath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
-    return undefined;
-  }
-  const agentId = path.basename(agentDirectory);
-  if (!agentId || agentId === '.' || agentId === '..') return undefined;
-  return { agentId, scriptPath: parsed[1] };
+  if (!parsed || !path.isAbsolute(parsed[0]) || !isNodeExecutable(parsed[0])) return undefined;
+  return managedScriptReference(parsed[1], scriptName);
 }

src/plugins/grok-contract.ts

@@ -1,15 +1,19 @@
+import { sameAgentId } from './common.js';
 import {
   buildGrokCommand,
   grokRuntimeReference,
-  sameGrokAgentId,
   type GrokRuntimeReference,
 } from './grok-command.js';
+import type { GuardScriptOptions } from './guard-template.js';
+import type { HookScriptOptions } from './hook-template.js';
 import { isObject, parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'grok';
 export const GUARD_SCRIPT = 'guard.js';
 export const AUDIT_SCRIPT = 'hook.js';
 export const HOOK_TIMEOUT_SECONDS = 10;
+export const GUARD_OPTIONS: GuardScriptOptions = { denyProtocol: 'grok' };
+export const AUDIT_OPTIONS: HookScriptOptions = { nativePayload: true };
 
 const MATCHER_REJECTING_EVENTS = new Set([
   'SessionStart',
@@ -172,7 +176,7 @@ function removeFromGroups(
     const handlers = group.hooks.filter((handler) => {
       const reference = managedReference(handler, scriptName);
       return !reference
-        || (agentId !== undefined && !sameGrokAgentId(reference.agentId, agentId));
+        || (agentId !== undefined && !sameAgentId(reference.agentId, agentId));
     });
     if (handlers.length > 0) result.push({ hooks: handlers });
   }

src/plugins/grok-installation.ts

@@ -2,7 +2,9 @@ import path from 'node:path';
 import type { InstallConfig } from './base.js';
 import {
   AGENT_KEY,
+  AUDIT_OPTIONS,
   AUDIT_SCRIPT,
+  GUARD_OPTIONS,
   GUARD_SCRIPT,
   type RenderedGrokDocument,
 } from './grok-contract.js';
@@ -24,14 +26,10 @@ const DISPLAY_NAME = 'Grok Build';
 const HOOKS_DIRECTORY_LABEL = 'Grok hooks directory';
 const HOOKS_LABEL = 'Grok user hooks';
 
-export type GrokRuntimePaths = ManagedRuntimePaths;
-export type PreparedGrokInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
 export async function preflightGrokInstallation(
   config: InstallConfig,
   hooksPath: string,
-): Promise<GrokRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: [{ directoryLabel: HOOKS_DIRECTORY_LABEL, filePath: hooksPath }],
@@ -42,7 +40,7 @@ export async function preflightGrokInstallation(
 export async function prepareGrokInstallation(
   config: InstallConfig,
   rendered: RenderedGrokDocument,
-): Promise<PreparedGrokInstallation> {
+): Promise<PreparedManagedInstallation> {
   const hooksSource = rendered.next ?? rendered.document.raw;
   if (hooksSource === undefined) throw new Error('Grok hook configuration is missing');
   const prepared = await prepareManagedInstallation({
@@ -56,8 +54,8 @@ export async function prepareGrokInstallation(
       source: hooksSource,
     }],
     config,
-    guardOptions: { denyProtocol: 'grok' },
-    auditOptions: { nativePayload: true },
+    guardOptions: GUARD_OPTIONS,
+    auditOptions: AUDIT_OPTIONS,
   }, GUARD_SCRIPT, AUDIT_SCRIPT);
   const hooksDirectory = path.dirname(rendered.document.filePath);
   return {
@@ -73,7 +71,7 @@ export async function prepareGrokInstallation(
 }
 
 export async function commitGrokInstallation(
-  prepared: PreparedGrokInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/grok-io.ts

@@ -2,14 +2,15 @@ import os from 'node:os';
 import path from 'node:path';
 import {
   AGENT_KEY,
+  AUDIT_OPTIONS,
+  GUARD_OPTIONS,
   createGrokDocument,
   parseGrokDocument,
   type GrokDocument,
   type GrokRuntimeContract,
 } from './grok-contract.js';
-import { sameGrokAgentId, sameGrokPath } from './grok-command.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
-import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 
 const CONFIG_FILE = 'elydora-audit.json';
 
@@ -36,82 +37,15 @@ export async function readGrokDocument(): Promise<GrokDocument> {
     : createGrokDocument(filePath);
 }
 
-function requireNonEmptyString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function validateRuntimeConfig(
-  config: JsonObject,
-  contract: GrokRuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  requireNonEmptyString(config.org_id, 'org_id', configPath);
-  requireNonEmptyString(config.kid, 'kid', configPath);
-  const agentId = requireNonEmptyString(config.agent_id, 'agent_id', configPath);
-  if (!sameGrokAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Grok hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireNonEmptyString(config.token, 'token', configPath);
-  const rawBaseUrl = requireNonEmptyString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: error instanceof Error ? error : new Error(String(error)),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-async function runtimeContractExists(contract: GrokRuntimeContract): Promise<boolean> {
-  const runtimeRoot = path.join(os.homedir(), '.elydora');
-  const agentDirectory = path.dirname(contract.guardPath);
-  if (!sameGrokPath(path.dirname(agentDirectory), runtimeRoot)
-    || !sameGrokPath(contract.auditPath, path.join(agentDirectory, 'hook.js'))) return false;
-  if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) return false;
-  if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) return false;
-
-  const configPath = path.join(agentDirectory, 'config.json');
-  const keyPath = path.join(agentDirectory, 'private.key');
-  const [config, key, guard, audit] = await Promise.all([
-    readPhysicalFile(configPath, 'Elydora runtime config'),
-    readPhysicalFile(keyPath, 'Elydora private key'),
-    readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-    readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
-  ]);
-  if (!config || !key || !guard || !audit) return false;
-  const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
-  validateRuntimeConfig(parsed, contract, configPath);
-  validatePrivateKey(key.contents, keyPath);
-  return guard.contents.length > 0 && audit.contents.length > 0;
-}
-
 export async function grokRuntimeFilesExist(
   contracts: readonly GrokRuntimeContract[],
 ): Promise<boolean> {
   for (const contract of contracts) {
-    if (await runtimeContractExists(contract)) return true;
+    const exists = await managedRuntimeFilesExist(contract, AGENT_KEY, {
+      guardOptions: GUARD_OPTIONS,
+      auditOptions: AUDIT_OPTIONS,
+    });
+    if (exists) return true;
   }
   return false;
 }

src/plugins/jsonc-edit.ts

@@ -0,0 +1,23 @@
+import { applyEdits, modify, type FormattingOptions, type JSONPath } from 'jsonc-parser';
+
+function formatting(raw: string): FormattingOptions {
+  const indentation = /\r?\n([ \t]+)\S/.exec(raw)?.[1];
+  const insertSpaces = !indentation?.includes('\t');
+  return {
+    eol: raw.includes('\r\n') ? '\r\n' : '\n',
+    insertSpaces,
+    tabSize: insertSpaces ? Math.max(1, indentation?.length ?? 2) : 1,
+  };
+}
+
+export function changeJsonc(
+  raw: string,
+  jsonPath: JSONPath,
+  value: unknown,
+  isArrayInsertion = false,
+): string {
+  return applyEdits(raw, modify(raw, jsonPath, value, {
+    formattingOptions: formatting(raw),
+    isArrayInsertion,
+  }));
+}

src/plugins/kimi-command.ts

@@ -1,140 +1,21 @@
-import os from 'node:os';
 import path from 'node:path';
+import { managedScriptReference, type ManagedScriptReference } from './common.js';
+import {
+  encodedWindowsCommand,
+  isNodeExecutable,
+  parseEncodedWindowsCommand,
+  parseLegacyWindowsCommand,
+  parsePosixCommand,
+  posixSource,
+} from './shell-command.js';
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
-export interface KimiRuntimeReference {
-  readonly agentId: string;
-  readonly scriptPath: string;
-}
-
-export function sameKimiPath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameKimiAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
-function windowsPowerShellPath(): string {
-  const configuredRoot = process.platform === 'win32' ? process.env.SystemRoot : undefined;
-  const systemRoot = configuredRoot
-    && path.win32.isAbsolute(configuredRoot)
-    && !/["%\r\n]/.test(configuredRoot)
-    ? configuredRoot
-    : 'C:\\Windows';
-  return path.win32.join(
-    systemRoot,
-    'System32',
-    'WindowsPowerShell',
-    'v1.0',
-    'powershell.exe',
-  );
-}
-
-function windowsCommand(scriptPath: string): string {
-  const source = `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`;
-  const encoded = Buffer.from(source, 'utf16le').toString('base64');
-  return `"${windowsPowerShellPath()}" -NoLogo -NoProfile -NonInteractive -EncodedCommand ${encoded}`;
-}
+export type KimiRuntimeReference = ManagedScriptReference;
 
 export function buildKimiCommand(scriptPath: string): string {
   if (!path.isAbsolute(process.execPath) || !path.isAbsolute(scriptPath)) {
     throw new Error('Kimi hook commands require absolute executable and script paths');
   }
-  return process.platform === 'win32'
-    ? windowsCommand(scriptPath)
-    : `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
-}
-
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parsePosixCommand(command: string): readonly [string, string] | undefined {
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length) return undefined;
-  return [executable.value, script.value];
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parsePowerShellSource(source: string): readonly [string, string] | undefined {
-  if (!source.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(source, 2);
-  if (!executable || source[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(source, executable.next + 1);
-  if (!script || source.slice(script.next) !== '; exit $LASTEXITCODE') return undefined;
-  return [executable.value, script.value];
-}
-
-function parseWindowsCommand(command: string): readonly [string, string] | undefined {
-  const match = /^"([^"\r\n]+)" -NoLogo -NoProfile -NonInteractive -EncodedCommand ([A-Za-z0-9+/]+={0,2})$/.exec(command);
-  if (!match
-    || !path.win32.isAbsolute(match[1])
-    || path.win32.basename(match[1]).toLowerCase() !== 'powershell.exe') return undefined;
-  const encoded = match[2];
-  const buffer = Buffer.from(encoded, 'base64');
-  if (buffer.length % 2 !== 0 || buffer.toString('base64') !== encoded) return undefined;
-  return parsePowerShellSource(buffer.toString('utf16le'));
-}
-
-function parseLegacyWindowsCommand(command: string): readonly [string, string] | undefined {
-  const match = /^"([^"\r\n]+)" "([^"\r\n]+)"$/.exec(command);
-  return match ? [match[1], match[2]] : undefined;
-}
-
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath).toLowerCase();
-  return basename === 'node' || basename === 'node.exe';
+  return process.platform === 'win32' ? encodedWindowsCommand(scriptPath) : posixSource(scriptPath);
 }
 
 export function kimiRuntimeReference(
@@ -142,18 +23,8 @@ export function kimiRuntimeReference(
   scriptName: string,
 ): KimiRuntimeReference | undefined {
   const parsed = parsePosixCommand(command)
-    ?? parseWindowsCommand(command)
+    ?? parseEncodedWindowsCommand(command)
     ?? parseLegacyWindowsCommand(command);
-  if (!parsed
-    || !path.isAbsolute(parsed[0])
-    || !path.isAbsolute(parsed[1])
-    || !isNodeExecutable(parsed[0])
-    || path.basename(parsed[1]) !== scriptName) return undefined;
-  const agentDirectory = path.dirname(parsed[1]);
-  if (!sameKimiPath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
-    return undefined;
-  }
-  const agentId = path.basename(agentDirectory);
-  if (!agentId || agentId === '.' || agentId === '..') return undefined;
-  return { agentId, scriptPath: parsed[1] };
+  if (!parsed || !path.isAbsolute(parsed[0]) || !isNodeExecutable(parsed[0])) return undefined;
+  return managedScriptReference(parsed[1], scriptName);
 }

src/plugins/kimi-contract.ts

@@ -1,9 +1,10 @@
+import { sameAgentId } from './common.js';
 import {
   buildKimiCommand,
   kimiRuntimeReference,
-  sameKimiAgentId,
   type KimiRuntimeReference,
 } from './kimi-command.js';
+import { isObject, type JsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'kimi';
 export const GUARD_SCRIPT = 'guard.js';
@@ -34,7 +35,7 @@ export const STABLE_EVENTS = new Set<string>([
 ]);
 export const LEGACY_EVENTS = new Set<string>(SHARED_EVENTS);
 
-export type TomlObject = Record<string, unknown>;
+export type TomlObject = JsonObject;
 export type ManagedKimiEvent = 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure';
 
 export interface KimiHook extends TomlObject {
@@ -75,14 +76,6 @@ export interface KimiRuntimeContract {
   readonly configPath: string;
 }
 
-function isObject(value: unknown): value is TomlObject {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function hasOwn(value: TomlObject, key: string): boolean {
-  return Object.prototype.hasOwnProperty.call(value, key);
-}
-
 function exactManagedKeys(hook: KimiHook): boolean {
   return Object.keys(hook).sort().join('|') === 'command|event|timeout';
 }
@@ -194,7 +187,7 @@ async function renderHookSource(
   if (document.usesHookTables) return patchToml(document.raw ?? '', nextRoot);
 
   let base = document.raw ?? '';
-  if (hasOwn(document.root, 'hooks')) {
+  if (Object.hasOwn(document.root, 'hooks')) {
     const rootWithoutHooks = { ...document.root };
     delete rootWithoutHooks.hooks;
     base = patchToml(base, rootWithoutHooks);
@@ -248,7 +241,7 @@ export function removeManagedKimiHooks(
     if (!expected) return true;
     const managedId = managedAgentId(hook, expected[0], expected[1]);
     if (!managedId) return true;
-    return agentId !== undefined && !sameKimiAgentId(managedId, agentId);
+    return agentId !== undefined && !sameAgentId(managedId, agentId);
   });
 }
 

src/plugins/kimi-installation.ts

@@ -23,10 +23,6 @@ import {
 
 const DISPLAY_NAME = 'Kimi';
 
-export type KimiRuntimePaths = ManagedRuntimePaths;
-export type PreparedKimiInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
 function hookLocations(documents: readonly KimiConfigDocument[]) {
   return documents.map((document) => ({
     directoryLabel: document.contract.directoryLabel,
@@ -37,7 +33,7 @@ function hookLocations(documents: readonly KimiConfigDocument[]) {
 export async function preflightKimiInstallation(
   config: InstallConfig,
   documents: readonly KimiConfigDocument[],
-): Promise<KimiRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: hookLocations(documents),
@@ -56,7 +52,7 @@ function renderedSource(rendered: RenderedKimiDocument): string {
 export async function prepareKimiInstallation(
   config: InstallConfig,
   rendered: readonly RenderedKimiDocument[],
-): Promise<PreparedKimiInstallation> {
+): Promise<PreparedManagedInstallation> {
   return prepareManagedInstallation({
     agentKey: AGENT_KEY,
     displayName: DISPLAY_NAME,
@@ -73,7 +69,7 @@ export async function prepareKimiInstallation(
 }
 
 export async function commitKimiInstallation(
-  prepared: PreparedKimiInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/kimi-io.ts

@@ -1,6 +1,7 @@
 import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { asError, errorMessage, hasCode, samePath } from './common.js';
 import {
   AGENT_KEY,
   LEGACY_EVENTS,
@@ -10,23 +11,9 @@ import {
   type KimiConfigDocument,
   type KimiContract,
   type KimiRuntimeContract,
-  type TomlObject,
 } from './kimi-contract.js';
-import { sameKimiAgentId, sameKimiPath } from './kimi-command.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
-import { parseStrictJsonObject } from './strict-json.js';
-
-function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function hasCode(error: unknown, code: string): boolean {
-  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
-}
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 
 async function pathEntryExists(filePath: string, label: string): Promise<boolean> {
   try {
@@ -72,7 +59,7 @@ export async function resolveKimiContracts(): Promise<KimiContract[]> {
   const legacyHome = path.join(home, '.kimi');
   const stable = stableContract(path.join(stableHome, 'config.toml'));
   const legacy = legacyContract(path.join(legacyHome, 'config.toml'));
-  if (sameKimiPath(stable.configPath, legacy.configPath)) return [stable];
+  if (samePath(stable.configPath, legacy.configPath)) return [stable];
 
   const stableDetected = explicitHome !== undefined
     || await pathEntryExists(stableHome, 'Kimi Code home');
@@ -96,82 +83,11 @@ export async function readKimiDocuments(): Promise<KimiConfigDocument[]> {
   return documents;
 }
 
-function requireNonEmptyString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function validateRuntimeConfig(
-  config: TomlObject,
-  contract: KimiRuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  requireNonEmptyString(config.org_id, 'org_id', configPath);
-  requireNonEmptyString(config.kid, 'kid', configPath);
-  const agentId = requireNonEmptyString(config.agent_id, 'agent_id', configPath);
-  if (!sameKimiAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Kimi hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireNonEmptyString(config.token, 'token', configPath);
-  const rawBaseUrl = requireNonEmptyString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: asError(error),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-async function runtimeContractExists(contract: KimiRuntimeContract): Promise<boolean> {
-  const runtimeRoot = path.join(os.homedir(), '.elydora');
-  const agentDirectory = path.dirname(contract.guardPath);
-  if (!sameKimiPath(path.dirname(agentDirectory), runtimeRoot)
-    || !sameKimiPath(contract.auditPath, path.join(agentDirectory, 'hook.js'))) return false;
-  if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) return false;
-  if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) return false;
-
-  const configPath = path.join(agentDirectory, 'config.json');
-  const keyPath = path.join(agentDirectory, 'private.key');
-  const [config, key, guard, audit] = await Promise.all([
-    readPhysicalFile(configPath, 'Elydora runtime config'),
-    readPhysicalFile(keyPath, 'Elydora private key'),
-    readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-    readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
-  ]);
-  if (!config || !key || !guard || !audit) return false;
-  const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
-  validateRuntimeConfig(parsed, contract, configPath);
-  validatePrivateKey(key.contents, keyPath);
-  return guard.contents.length > 0 && audit.contents.length > 0;
-}
-
 export async function kimiRuntimeFilesExist(
   contracts: readonly KimiRuntimeContract[],
 ): Promise<boolean> {
   for (const contract of contracts) {
-    if (await runtimeContractExists(contract)) return true;
+    if (await managedRuntimeFilesExist(contract, AGENT_KEY)) return true;
   }
   return false;
 }

src/plugins/kirocli-contract.ts

@@ -1,14 +1,14 @@
 import os from 'node:os';
 import path from 'node:path';
+import { managedScriptReference, sameAgentId, samePath } from './common.js';
 import {
   buildKiroIdeCommand,
   kiroIdeRuntimeReference,
-  sameKiroIdeAgentId,
-  sameKiroIdePath,
   type KiroIdeRuntimeReference,
 } from './kiroide-command.js';
 import {
   buildKiroIdeHook,
+  exactKeys,
   kiroIdeRuntimeContracts,
   renderKiroIdeDocument,
   type KiroIdeDocument,
@@ -16,6 +16,7 @@ import {
   type RenderedKiroIdeDocument,
   type KiroIdeRuntimeContract,
 } from './kiroide-contract.js';
+import { isNodeExecutable, parseLegacyWindowsCommand } from './shell-command.js';
 import { isObject, parseStrictJsonObject, type JsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'kirocli';
@@ -162,27 +163,14 @@ function eventHooks(document: KiroCliV2Document, event: string): readonly KiroCl
   return (document.hooks[event] as readonly KiroCliV2Hook[] | undefined) ?? [];
 }
 
-function exactKeys(value: JsonObject, keys: readonly string[]): boolean {
-  return Object.keys(value).sort().join('|') === [...keys].sort().join('|');
-}
-
 function legacyWindowsReference(
   command: unknown,
   scriptName: string,
 ): KiroIdeRuntimeReference | undefined {
   if (typeof command !== 'string') return undefined;
-  const match = /^"([^"\r\n]+)" "([^"\r\n]+)"$/.exec(command);
-  if (!match
-    || !path.isAbsolute(match[1])
-    || !['node', 'node.exe'].includes(path.basename(match[1]).toLowerCase())
-    || !path.isAbsolute(match[2])
-    || path.basename(match[2]) !== scriptName) return undefined;
-  const agentDirectory = path.dirname(match[2]);
-  if (!sameKiroIdePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
-    return undefined;
-  }
-  const agentId = path.basename(agentDirectory);
-  return agentId ? { agentId, scriptPath: match[2] } : undefined;
+  const parsed = parseLegacyWindowsCommand(command);
+  if (!parsed || !path.isAbsolute(parsed[0]) || !isNodeExecutable(parsed[0])) return undefined;
+  return managedScriptReference(parsed[1], scriptName);
 }
 
 function ownedReference(command: unknown, scriptName: string): KiroIdeRuntimeReference | undefined {
@@ -219,7 +207,7 @@ function hasOwnedV2Hooks(document: KiroCliV2Document, agentId?: string): boolean
   return ['preToolUse', 'postToolUse'].some((event) => eventHooks(document, event).some((hook) => {
     const reference = v2OwnedReference(hook, event);
     return reference !== undefined
-      && (agentId === undefined || sameKiroIdeAgentId(reference.agentId, agentId));
+      && (agentId === undefined || sameAgentId(reference.agentId, agentId));
   }));
 }
 
@@ -237,7 +225,7 @@ export function withoutManagedKiroCliV2Hooks(
   for (const event of ['preToolUse', 'postToolUse']) {
     const remaining = eventHooks(document, event).filter((hook) => {
       const reference = v2OwnedReference(hook, event);
-      return !reference || (agentId !== undefined && !sameKiroIdeAgentId(reference.agentId, agentId));
+      return !reference || (agentId !== undefined && !sameAgentId(reference.agentId, agentId));
     });
     if (remaining.length > 0) next[event] = remaining;
     else delete next[event];
@@ -288,7 +276,7 @@ function entirelyManagedV2Document(document: KiroCliV2Document, agentId?: string
     const hooks = eventHooks(document, event);
     if (hooks.length !== 1) return false;
     const reference = v2OwnedReference(hooks[0], event);
-    if (!reference || (agentId !== undefined && !sameKiroIdeAgentId(reference.agentId, agentId))) {
+    if (!reference || (agentId !== undefined && !sameAgentId(reference.agentId, agentId))) {
       return false;
     }
   }
@@ -324,7 +312,7 @@ export function kiroCliV2RuntimeContracts(
     .map((hook) => v2ManagedReference(hook, 'postToolUse'))
     .filter((value): value is KiroIdeRuntimeReference => value !== undefined);
   if (guards.length !== 1 || audits.length !== 1
-    || !sameKiroIdeAgentId(guards[0].agentId, audits[0].agentId)) return [];
+    || !sameAgentId(guards[0].agentId, audits[0].agentId)) return [];
   return [{ agentId: guards[0].agentId, guardPath: guards[0].scriptPath, auditPath: audits[0].scriptPath }];
 }
 
@@ -355,7 +343,7 @@ export function withoutManagedKiroCliV3Hooks(
 ): KiroIdeHook[] {
   return hooks.filter((hook) => {
     const reference = v3OwnedReference(hook);
-    return !reference || (agentId !== undefined && !sameKiroIdeAgentId(reference.agentId, agentId));
+    return !reference || (agentId !== undefined && !sameAgentId(reference.agentId, agentId));
   });
 }
 
@@ -363,7 +351,7 @@ function hasOwnedV3Hooks(hooks: readonly KiroIdeHook[], agentId?: string): boole
   return hooks.some((hook) => {
     const reference = v3OwnedReference(hook);
     return reference !== undefined
-      && (agentId === undefined || sameKiroIdeAgentId(reference.agentId, agentId));
+      && (agentId === undefined || sameAgentId(reference.agentId, agentId));
   });
 }
 
@@ -374,7 +362,7 @@ function entirelyManagedV3Document(document: KiroIdeDocument, agentId?: string):
     && document.hooks.every((hook) => {
       const reference = v3OwnedReference(hook);
       return reference !== undefined
-        && (agentId === undefined || sameKiroIdeAgentId(reference.agentId, agentId));
+        && (agentId === undefined || sameAgentId(reference.agentId, agentId));
     });
 }
 
@@ -409,8 +397,8 @@ export function commonKiroCliRuntimeContract(
   const v2 = kiroCliV2RuntimeContracts(v2Document);
   const v3 = kiroIdeRuntimeContracts(v3Hooks);
   if (v2.length !== 1 || v3.length !== 1
-    || !sameKiroIdeAgentId(v2[0].agentId, v3[0].agentId)
-    || !sameKiroIdePath(v2[0].guardPath, v3[0].guardPath)
-    || !sameKiroIdePath(v2[0].auditPath, v3[0].auditPath)) return undefined;
+    || !sameAgentId(v2[0].agentId, v3[0].agentId)
+    || !samePath(v2[0].guardPath, v3[0].guardPath)
+    || !samePath(v2[0].auditPath, v3[0].auditPath)) return undefined;
   return v2[0];
 }

src/plugins/kirocli-installation.ts

@@ -27,10 +27,6 @@ const DISPLAY_NAME = 'Kiro CLI';
 const V2_DIRECTORY_LABEL = 'Kiro CLI agents directory';
 const V3_DIRECTORY_LABEL = 'Kiro CLI global hooks directory';
 
-export type KiroCliRuntimePaths = ManagedRuntimePaths;
-export type PreparedKiroCliInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
 function hookLocations(sources: KiroCliSources) {
   return [
     { directoryLabel: V2_DIRECTORY_LABEL, filePath: sources.paths.v2Path },
@@ -41,7 +37,7 @@ function hookLocations(sources: KiroCliSources) {
 export async function preflightKiroCliInstallation(
   config: InstallConfig,
   sources: KiroCliSources,
-): Promise<KiroCliRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: hookLocations(sources),
@@ -54,7 +50,7 @@ export async function prepareKiroCliInstallation(
   sources: KiroCliSources,
   v2: RenderedKiroCliV2Document,
   v3: RenderedKiroIdeDocument,
-): Promise<PreparedKiroCliInstallation> {
+): Promise<PreparedManagedInstallation> {
   if (v2.next === undefined || v3.next === undefined) {
     throw new Error('Kiro CLI installation requires both v2 and v3 hook documents');
   }
@@ -83,7 +79,7 @@ export async function prepareKiroCliInstallation(
 }
 
 export async function commitKiroCliInstallation(
-  prepared: PreparedKiroCliInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/kirocli-io.ts

@@ -12,11 +12,10 @@ import {
   type KiroIdeDocument,
   type KiroIdeRuntimeContract,
 } from './kiroide-contract.js';
+import { MAX_CONFIG_BYTES } from './common.js';
 import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
 import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 
-const MAX_HOOK_BYTES = 512 * 1024;
-
 export interface KiroCliSources {
   readonly paths: KiroCliPaths;
   readonly v2: KiroCliV2Document;
@@ -36,7 +35,7 @@ async function readV2Document(paths: KiroCliPaths): Promise<KiroCliV2Document> {
   const snapshot = await readPhysicalFile(
     paths.v2Path,
     'Kiro CLI v2 agent config',
-    MAX_HOOK_BYTES,
+    MAX_CONFIG_BYTES,
   );
   return snapshot
     ? parseKiroCliV2Document(paths.v2Path, snapshot.contents)
@@ -47,7 +46,7 @@ async function readV3Document(paths: KiroCliPaths): Promise<KiroIdeDocument> {
   const snapshot = await readPhysicalFile(
     paths.v3Path,
     'Kiro CLI v3 global hooks',
-    MAX_HOOK_BYTES,
+    MAX_CONFIG_BYTES,
   );
   return snapshot
     ? parseKiroIdeDocument(paths.v3Path, snapshot.contents, 'Kiro CLI v3 global hooks')

src/plugins/kiroide-command.ts

@@ -1,132 +1,20 @@
-import os from 'node:os';
 import path from 'node:path';
+import { managedScriptReference, type ManagedScriptReference } from './common.js';
+import {
+  encodedWindowsCommand,
+  isNodeExecutable,
+  parseEncodedWindowsCommand,
+  parsePosixCommand,
+  posixSource,
+} from './shell-command.js';
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
-export interface KiroIdeRuntimeReference {
-  readonly agentId: string;
-  readonly scriptPath: string;
-}
-
-export function sameKiroIdePath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameKiroIdeAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
-function windowsPowerShellPath(): string {
-  const configuredRoot = process.env.SystemRoot;
-  const systemRoot = configuredRoot
-    && path.win32.isAbsolute(configuredRoot)
-    && !/["%\r\n]/.test(configuredRoot)
-    ? configuredRoot
-    : 'C:\\Windows';
-  return path.win32.join(
-    systemRoot,
-    'System32',
-    'WindowsPowerShell',
-    'v1.0',
-    'powershell.exe',
-  );
-}
-
-function windowsCommand(scriptPath: string): string {
-  const source = `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`;
-  const encoded = Buffer.from(source, 'utf16le').toString('base64');
-  return `"${windowsPowerShellPath()}" -NoLogo -NoProfile -NonInteractive -EncodedCommand ${encoded}`;
-}
+export type KiroIdeRuntimeReference = ManagedScriptReference;
 
 export function buildKiroIdeCommand(scriptPath: string): string {
   if (!path.isAbsolute(process.execPath) || !path.isAbsolute(scriptPath)) {
     throw new Error('Kiro IDE hook commands require absolute executable and script paths');
   }
-  return process.platform === 'win32'
-    ? windowsCommand(scriptPath)
-    : `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
-}
-
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parsePosixCommand(command: string): readonly [string, string] | undefined {
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  return script && script.next === command.length ? [executable.value, script.value] : undefined;
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parsePowerShellSource(source: string): readonly [string, string] | undefined {
-  if (!source.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(source, 2);
-  if (!executable || source[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(source, executable.next + 1);
-  return script && source.slice(script.next) === '; exit $LASTEXITCODE'
-    ? [executable.value, script.value]
-    : undefined;
-}
-
-function parseWindowsCommand(command: string): readonly [string, string] | undefined {
-  const match = /^"([^"\r\n]+)" -NoLogo -NoProfile -NonInteractive -EncodedCommand ([A-Za-z0-9+/]+={0,2})$/.exec(command);
-  if (!match
-    || !path.win32.isAbsolute(match[1])
-    || path.win32.basename(match[1]).toLowerCase() !== 'powershell.exe') return undefined;
-  const buffer = Buffer.from(match[2], 'base64');
-  if (buffer.length % 2 !== 0 || buffer.toString('base64') !== match[2]) return undefined;
-  return parsePowerShellSource(buffer.toString('utf16le'));
-}
-
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath).toLowerCase();
-  return basename === 'node' || basename === 'node.exe';
+  return process.platform === 'win32' ? encodedWindowsCommand(scriptPath) : posixSource(scriptPath);
 }
 
 export function kiroIdeRuntimeReference(
@@ -134,19 +22,8 @@ export function kiroIdeRuntimeReference(
   scriptName: string,
 ): KiroIdeRuntimeReference | undefined {
   const parsed = process.platform === 'win32'
-    ? parseWindowsCommand(command)
+    ? parseEncodedWindowsCommand(command)
     : parsePosixCommand(command);
-  if (!parsed
-    || !path.isAbsolute(parsed[0])
-    || !isNodeExecutable(parsed[0])
-    || !path.isAbsolute(parsed[1])
-    || path.basename(parsed[1]) !== scriptName) return undefined;
-  const agentDirectory = path.dirname(parsed[1]);
-  if (!sameKiroIdePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
-    return undefined;
-  }
-  const agentId = path.basename(agentDirectory);
-  return agentId && agentId !== '.' && agentId !== '..'
-    ? { agentId, scriptPath: parsed[1] }
-    : undefined;
+  if (!parsed || !path.isAbsolute(parsed[0]) || !isNodeExecutable(parsed[0])) return undefined;
+  return managedScriptReference(parsed[1], scriptName);
 }

src/plugins/kiroide-contract.ts

@@ -1,10 +1,9 @@
 import os from 'node:os';
 import path from 'node:path';
+import { managedScriptReference, sameAgentId } from './common.js';
 import {
   buildKiroIdeCommand,
   kiroIdeRuntimeReference,
-  sameKiroIdeAgentId,
-  sameKiroIdePath,
   type KiroIdeRuntimeReference,
 } from './kiroide-command.js';
 import { isObject, parseStrictJsonObject, type JsonObject } from './strict-json.js';
@@ -154,7 +153,7 @@ export function createKiroIdeDocument(filePath: string): KiroIdeDocument {
   return { exists: false, filePath, root: {}, hooks: [] };
 }
 
-function exactKeys(value: JsonObject, keys: readonly string[]): boolean {
+export function exactKeys(value: JsonObject, keys: readonly string[]): boolean {
   return Object.keys(value).sort().join('|') === [...keys].sort().join('|');
 }
 
@@ -228,7 +227,7 @@ export function withoutManagedKiroIdeHooks(
 ): KiroIdeHook[] {
   return hooks.filter((hook) => {
     const reference = ownedReference(hook);
-    return !reference || (agentId !== undefined && !sameKiroIdeAgentId(reference.agentId, agentId));
+    return !reference || (agentId !== undefined && !sameAgentId(reference.agentId, agentId));
   });
 }
 
@@ -285,12 +284,7 @@ export function kiroIdeRuntimeContracts(
 function legacyReference(command: unknown, scriptName: string) {
   if (typeof command !== 'string') return undefined;
   const match = /^node "([^"\r\n]+)"$/.exec(command);
-  if (!match || !path.isAbsolute(match[1]) || path.basename(match[1]) !== scriptName) return undefined;
-  const agentDirectory = path.dirname(match[1]);
-  if (!sameKiroIdePath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
-    return undefined;
-  }
-  return { agentId: path.basename(agentDirectory), scriptPath: match[1] };
+  return match ? managedScriptReference(match[1], scriptName) : undefined;
 }
 
 export function legacyKiroIdeRuntimeContract(raw: string, filePath: string): KiroIdeRuntimeContract | undefined {
@@ -311,6 +305,6 @@ export function legacyKiroIdeRuntimeContract(raw: string, filePath: string): Kir
     || auditHook.timeout_ms !== 5000) return undefined;
   const guard = legacyReference(guardHook.command, GUARD_SCRIPT);
   const audit = legacyReference(auditHook.command, AUDIT_SCRIPT);
-  if (!guard || !audit || !sameKiroIdeAgentId(guard.agentId, audit.agentId)) return undefined;
+  if (!guard || !audit || !sameAgentId(guard.agentId, audit.agentId)) return undefined;
   return { agentId: guard.agentId, guardPath: guard.scriptPath, auditPath: audit.scriptPath };
 }

src/plugins/kiroide-installation.ts

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import type { InstallConfig } from './base.js';
-import { sameKiroIdeAgentId } from './kiroide-command.js';
+import { sameAgentId } from './common.js';
 import {
   AGENT_KEY,
   AUDIT_SCRIPT,
@@ -31,17 +31,13 @@ import {
 const DISPLAY_NAME = 'Kiro IDE';
 const DIRECTORY_LABEL = 'Kiro IDE hooks directory';
 
-export type KiroIdeRuntimePaths = ManagedRuntimePaths;
-export type PreparedKiroIdeInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
 function hookLocation(paths: KiroIdePaths) {
   return [{ directoryLabel: DIRECTORY_LABEL, filePath: paths.configPath }];
 }
 
 function removesLegacy(legacy: LegacyKiroIdeDocument, agentId?: string): boolean {
   return legacy.contract !== undefined
-    && (agentId === undefined || sameKiroIdeAgentId(legacy.contract.agentId, agentId));
+    && (agentId === undefined || sameAgentId(legacy.contract.agentId, agentId));
 }
 
 async function prepareLegacyRemoval(
@@ -64,7 +60,7 @@ async function prepareLegacyRemoval(
 export async function preflightKiroIdeInstallation(
   config: InstallConfig,
   paths: KiroIdePaths,
-): Promise<KiroIdeRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: hookLocation(paths),
@@ -76,7 +72,7 @@ export async function prepareKiroIdeInstallation(
   config: InstallConfig,
   sources: KiroIdeSources,
   rendered: RenderedKiroIdeDocument,
-): Promise<PreparedKiroIdeInstallation> {
+): Promise<PreparedManagedInstallation> {
   if (rendered.next === undefined) throw new Error('Kiro IDE installation requires a hook document');
   const prepared = await prepareManagedInstallation({
     agentKey: AGENT_KEY,
@@ -107,7 +103,7 @@ export async function prepareKiroIdeInstallation(
 }
 
 export async function commitKiroIdeInstallation(
-  prepared: PreparedKiroIdeInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/letta-command.ts

@@ -1,10 +1,12 @@
-import os from 'node:os';
 import path from 'node:path';
-
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
+import { managedScriptReference } from './common.js';
+import {
+  isNodeExecutable,
+  parsePosixCommand,
+  parsePowerShellSource,
+  posixSource,
+  powerShellSource,
+} from './shell-command.js';
 
 export interface LettaRuntimeReference {
   readonly agentId: string;
@@ -12,88 +14,11 @@ export interface LettaRuntimeReference {
   readonly scriptPath: string;
 }
 
-export function sameLettaPath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameLettaAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
 export function buildLettaCommand(scriptPath: string): string {
   if (!path.isAbsolute(process.execPath) || !path.isAbsolute(scriptPath)) {
     throw new Error('Letta Code hook commands require absolute executable and script paths');
   }
-  if (process.platform === 'win32') {
-    return `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`;
-  }
-  return `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
-}
-
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parsePosixCommand(command: string): readonly [string, string] | undefined {
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length) return undefined;
-  return [executable.value, script.value];
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parsePowerShellCommand(command: string): readonly [string, string] | undefined {
-  if (!command.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(command, 2);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(command, executable.next + 1);
-  if (!script || command.slice(script.next) !== '; exit $LASTEXITCODE') return undefined;
-  return [executable.value, script.value];
+  return process.platform === 'win32' ? powerShellSource(scriptPath) : posixSource(scriptPath);
 }
 
 function legacyScriptPath(command: string): string | undefined {
@@ -102,39 +27,16 @@ function legacyScriptPath(command: string): string | undefined {
   return scriptPath.includes('"') ? undefined : scriptPath;
 }
 
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath).toLowerCase();
-  return basename === 'node' || basename === 'node.exe';
-}
-
-function runtimeReference(
-  scriptPath: string,
-  scriptName: string,
-  executablePath?: string,
-): LettaRuntimeReference | undefined {
-  if (!path.isAbsolute(scriptPath) || path.basename(scriptPath) !== scriptName) return undefined;
-  const agentDirectory = path.dirname(scriptPath);
-  if (!sameLettaPath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
-    return undefined;
-  }
-  const agentId = path.basename(agentDirectory);
-  if (!agentId || agentId === '.' || agentId === '..') return undefined;
-  return { agentId, executablePath, scriptPath };
-}
-
 export function lettaRuntimeReference(
   command: string,
   scriptName: string,
 ): LettaRuntimeReference | undefined {
   const parsed = process.platform === 'win32'
-    ? parsePowerShellCommand(command)
+    ? parsePowerShellSource(command)
     : parsePosixCommand(command);
-  if (parsed
-    && path.isAbsolute(parsed[0])
-    && isNodeExecutable(parsed[0])) {
-    return runtimeReference(parsed[1], scriptName, parsed[0]);
-  }
-  return undefined;
+  if (!parsed || !path.isAbsolute(parsed[0]) || !isNodeExecutable(parsed[0])) return undefined;
+  const reference = managedScriptReference(parsed[1], scriptName);
+  return reference ? { ...reference, executablePath: parsed[0] } : undefined;
 }
 
 export function lettaLegacyRuntimeReference(
@@ -142,5 +44,5 @@ export function lettaLegacyRuntimeReference(
   scriptName: string,
 ): LettaRuntimeReference | undefined {
   const legacy = legacyScriptPath(command);
-  return legacy ? runtimeReference(legacy, scriptName) : undefined;
+  return legacy ? managedScriptReference(legacy, scriptName) : undefined;
 }

src/plugins/letta-config.ts

@@ -1,9 +1,5 @@
-import {
-  applyEdits,
-  modify,
-  type FormattingOptions,
-  type JSONPath,
-} from 'jsonc-parser';
+import type { JSONPath } from 'jsonc-parser';
+import { changeJsonc } from './jsonc-edit.js';
 import type { FileSnapshot } from './managed-files.js';
 import {
   MANAGED_EVENTS,
@@ -73,28 +69,6 @@ export function createLettaDocument(
   });
 }
 
-function formatting(raw: string): FormattingOptions {
-  const indentation = /\r?\n([ \t]+)\S/.exec(raw)?.[1];
-  const insertSpaces = !indentation?.includes('\t');
-  return {
-    eol: raw.includes('\r\n') ? '\r\n' : '\n',
-    insertSpaces,
-    tabSize: insertSpaces ? Math.max(1, indentation?.length ?? 2) : 1,
-  };
-}
-
-function change(
-  raw: string,
-  jsonPath: JSONPath,
-  value: unknown,
-  isArrayInsertion = false,
-): string {
-  return applyEdits(raw, modify(raw, jsonPath, value, {
-    formattingOptions: formatting(raw),
-    isArrayInsertion,
-  }));
-}
-
 function currentDocument(document: LettaDocument, raw: string): LettaDocument {
   return parseLettaDocument({
     kind: document.kind,
@@ -124,25 +98,25 @@ function removeManagedEntries(
     for (const removal of eventRemovals) {
       const groupPath: JSONPath = ['hooks', event, removal.groupIndex];
       if (removal.removeGroup) {
-        raw = change(raw, groupPath, undefined);
+        raw = changeJsonc(raw, groupPath, undefined);
         continue;
       }
       for (const handlerIndex of [...removal.handlerIndexes].sort(
         (left, right) => right - left,
       )) {
-        raw = change(raw, [...groupPath, 'hooks', handlerIndex], undefined);
+        raw = changeJsonc(raw, [...groupPath, 'hooks', handlerIndex], undefined);
       }
     }
     if (eventRemovals.length > 0) {
       const current = currentDocument(document, raw);
       if (groupsForEvent(current.hooks, event).length === 0) {
-        raw = change(raw, ['hooks', event], undefined);
+        raw = changeJsonc(raw, ['hooks', event], undefined);
       }
     }
   }
   const current = currentDocument(document, raw);
   if (current.hasHooksContainer && Object.keys(current.hooks).length === 0) {
-    raw = change(raw, ['hooks'], undefined);
+    raw = changeJsonc(raw, ['hooks'], undefined);
   }
   return raw;
 }
@@ -156,9 +130,9 @@ function appendGroup(
   const current = currentDocument(document, raw);
   const groups = groupsForEvent(current.hooks, event);
   if (groups.length > 0) {
-    return change(raw, ['hooks', event, groups.length], group, true);
+    return changeJsonc(raw, ['hooks', event, groups.length], group, true);
   }
-  return change(raw, ['hooks', event], [group]);
+  return changeJsonc(raw, ['hooks', event], [group]);
 }
 
 export function renderLettaDocument(

src/plugins/letta-contract.ts

@@ -1,9 +1,8 @@
+import { sameAgentId, samePath } from './common.js';
 import {
   buildLettaCommand,
   lettaLegacyRuntimeReference,
   lettaRuntimeReference,
-  sameLettaAgentId,
-  sameLettaPath,
   type LettaRuntimeReference,
 } from './letta-command.js';
 import { isObject, type JsonObject } from './strict-json.js';
@@ -220,7 +219,7 @@ export function managedLettaRemovals(
     eventGroups(hooks, event).forEach((group, groupIndex) => {
       const handlerIndexes = group.hooks.flatMap((handler, handlerIndex) => {
         const reference = managedReference(handler, scriptName);
-        return reference && (agentId === undefined || sameLettaAgentId(reference.agentId, agentId))
+        return reference && (agentId === undefined || sameAgentId(reference.agentId, agentId))
           ? [handlerIndex]
           : [];
       });
@@ -248,7 +247,7 @@ function referencesForEvent(
       const reference = exactCurrentReference(handler, scriptName);
       if (!reference
         || !reference.executablePath
-        || !sameLettaPath(reference.executablePath, process.execPath)) continue;
+        || !samePath(reference.executablePath, process.execPath)) continue;
       const key = process.platform === 'win32'
         ? reference.agentId.toLowerCase()
         : reference.agentId;
@@ -270,7 +269,7 @@ export function lettaRuntimeContracts(hooks: LettaHooks): LettaRuntimeContract[]
     const post = posts.get(key);
     const failure = failures.get(key);
     if (guard.length !== 1 || post?.length !== 1 || failure?.length !== 1) continue;
-    if (!sameLettaPath(post[0].scriptPath, failure[0].scriptPath)) continue;
+    if (!samePath(post[0].scriptPath, failure[0].scriptPath)) continue;
     contracts.push({
       agentId: guard[0].agentId,
       guardPath: guard[0].scriptPath,

src/plugins/letta-installation.ts

@@ -6,7 +6,7 @@ import {
   GUARD_SCRIPT,
   LETTA_AUDIT_OPTIONS,
 } from './letta-contract.js';
-import { sameLettaPath } from './letta-command.js';
+import { MAX_SOURCE_BYTES, samePath } from './common.js';
 import {
   lettaDocumentLabel,
   type RenderedLettaDocument,
@@ -31,16 +31,11 @@ import {
 
 const DISPLAY_NAME = 'Letta Code';
 const SETTINGS_DIRECTORY_LABEL = 'Letta Code global configuration directory';
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
-
-export type LettaRuntimePaths = ManagedRuntimePaths;
-export type PreparedLettaInstallation = PreparedManagedInstallation;
-export type { RenameFile };
 
 export async function preflightLettaInstallation(
   config: InstallConfig,
   sources: LettaSources,
-): Promise<LettaRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   requireLettaHooksEnabled(sources);
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
@@ -54,7 +49,7 @@ export async function preflightLettaInstallation(
 
 function readOnlyPreconditions(sources: LettaSources, changedPath?: string) {
   return sources.preconditions.filter((condition) => (
-    changedPath === undefined || !sameLettaPath(condition.filePath, changedPath)
+    changedPath === undefined || !samePath(condition.filePath, changedPath)
   ));
 }
 
@@ -62,7 +57,7 @@ export async function prepareLettaInstallation(
   config: InstallConfig,
   sources: LettaSources,
   rendered: RenderedLettaDocument,
-): Promise<PreparedLettaInstallation> {
+): Promise<PreparedManagedInstallation> {
   await preflightLettaInstallation(config, sources);
   const settingsSource = rendered.next ?? rendered.document.raw;
   const prepared = await prepareManagedInstallation({
@@ -89,7 +84,7 @@ export async function prepareLettaInstallation(
 }
 
 export async function commitLettaInstallation(
-  prepared: PreparedLettaInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/letta-sources.ts

@@ -9,14 +9,13 @@ import {
   type LettaDocument,
   type LettaDocumentKind,
 } from './letta-config.js';
+import { hasCode, MAX_SOURCE_BYTES, pathKey, samePath } from './common.js';
 import {
   inspectPhysicalDirectory,
   readPhysicalFile,
   type FileSnapshot,
 } from './managed-files.js';
 
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
-
 export interface LettaSourcePrecondition {
   readonly filePath: string;
   readonly label: string;
@@ -39,15 +38,6 @@ export interface LettaSources {
   readonly preconditions: readonly LettaSourcePrecondition[];
 }
 
-function comparisonPath(filePath: string): string {
-  const resolved = path.resolve(filePath);
-  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
-}
-
-function hasCode(error: unknown, code: string): boolean {
-  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
-}
-
 async function canonicalPath(filePath: string): Promise<string> {
   try {
     return await fsp.realpath(filePath);
@@ -93,7 +83,7 @@ function deduplicatePreconditions(
 ): LettaSourcePrecondition[] {
   const result = new Map<string, LettaSourcePrecondition>();
   for (const value of values) {
-    const key = comparisonPath(value.filePath);
+    const key = pathKey(value.filePath);
     if (!result.has(key)) result.set(key, value);
   }
   return [...result.values()];
@@ -123,7 +113,7 @@ export async function readLettaSources(): Promise<LettaSources> {
   const projectDirectory = path.join(workspace, '.letta');
   await inspectPhysicalDirectory(homeDirectory, 'Letta Code home directory');
   await inspectPhysicalDirectory(globalDirectory, 'Letta Code global configuration directory');
-  if (comparisonPath(projectDirectory) !== comparisonPath(globalDirectory)) {
+  if (!samePath(projectDirectory, globalDirectory)) {
     await inspectPhysicalDirectory(projectDirectory, 'Letta Code project configuration directory');
   }
   const globalPath = path.join(globalDirectory, 'settings.json');
@@ -133,7 +123,7 @@ export async function readLettaSources(): Promise<LettaSources> {
     canonicalPath(workspace),
     canonicalPath(homeDirectory),
   ]);
-  const projectActive = comparisonPath(canonicalWorkspace) !== comparisonPath(canonicalHome);
+  const projectActive = !samePath(canonicalWorkspace, canonicalHome);
   const global = await readDocument('global', globalPath);
   const project = projectActive
     ? await readDocument('project', projectPath)

src/plugins/opencode-contract.ts

@@ -1,7 +1,8 @@
 import os from 'node:os';
 import path from 'node:path';
 import type { HookScriptOptions } from './hook-template.js';
-import { samePath } from './common.js';
+import { errorMessage, samePath } from './common.js';
+import { isNodeExecutable } from './shell-command.js';
 import { parseStrictJsonObject } from './strict-json.js';
 
 export const AGENT_KEY = 'opencode';
@@ -51,10 +52,6 @@ interface OpenCodePluginMetadata {
   readonly auditPath: string;
 }
 
-export function sameOpenCodeAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
-}
-
 export function resolveOpenCodePaths(
   homeDirectory = os.homedir(),
   xdgConfigHome = process.env.XDG_CONFIG_HOME,
@@ -83,11 +80,6 @@ function validAgentSegment(agentId: string): boolean {
     && path.basename(agentId) === agentId;
 }
 
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath).toLowerCase();
-  return basename === 'node' || basename === 'node.exe';
-}
-
 function validateRuntimePaths(metadata: OpenCodePluginMetadata): void {
   if (!validAgentSegment(metadata.agentId)) {
     throw new Error('OpenCode plugin metadata contains an invalid agentId');
@@ -287,10 +279,6 @@ export const ElydoraAuditPlugin = async () => ({
 `);
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 export function parseOpenCodePlugin(
   filePath: string,
   source: string,

src/plugins/opencode-installation.ts

@@ -7,8 +7,8 @@ import {
   OPENCODE_AUDIT_OPTIONS,
   buildOpenCodeMetadata,
   buildOpenCodePlugin,
-  sameOpenCodeAgentId,
 } from './opencode-contract.js';
+import { sameAgentId } from './common.js';
 import type { OpenCodePluginFile, OpenCodeSources } from './opencode-io.js';
 import {
   commitManagedInstallation,
@@ -29,14 +29,10 @@ import {
 const DISPLAY_NAME = 'OpenCode';
 const DIRECTORY_LABEL = 'OpenCode plugins directory';
 
-export type OpenCodeRuntimePaths = ManagedRuntimePaths;
-export type PreparedOpenCodeInstallation = PreparedManagedInstallation;
-export type { RenameFile };
-
 export async function preflightOpenCodeInstallation(
   config: InstallConfig,
   sources: OpenCodeSources,
-): Promise<OpenCodeRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
     hookLocations: [{
@@ -50,7 +46,7 @@ export async function preflightOpenCodeInstallation(
 export async function prepareOpenCodeInstallation(
   config: InstallConfig,
   sources: OpenCodeSources,
-): Promise<PreparedOpenCodeInstallation> {
+): Promise<PreparedManagedInstallation> {
   const paths = await preflightOpenCodeInstallation(config, sources);
   const metadata = buildOpenCodeMetadata(
     config.agentId,
@@ -85,7 +81,7 @@ export async function prepareOpenCodeInstallation(
 }
 
 export async function commitOpenCodeInstallation(
-  prepared: PreparedOpenCodeInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);
@@ -96,7 +92,7 @@ function ownedByAgent<TContract extends { readonly agentId: string }>(
   agentId?: string,
 ): boolean {
   return file.contract !== undefined
-    && (agentId === undefined || sameOpenCodeAgentId(file.contract.agentId, agentId));
+    && (agentId === undefined || sameAgentId(file.contract.agentId, agentId));
 }
 
 export async function prepareOpenCodeUninstall(

src/plugins/opencode-io.ts

@@ -9,11 +9,10 @@ import {
   type OpenCodePaths,
   type OpenCodeRuntimeContract,
 } from './opencode-contract.js';
+import { errorMessage, hasCode, MAX_CONFIG_BYTES } from './common.js';
 import { inspectPhysicalDirectory, readPhysicalFile, type FileSnapshot } from './managed-files.js';
 import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 
-const MAX_PLUGIN_BYTES = 512 * 1024;
-
 export interface OpenCodePluginFile<TContract> {
   readonly exists: boolean;
   readonly filePath: string;
@@ -40,7 +39,7 @@ async function readPluginFile<TContract>(
   label: string,
   parse: (filePath: string, source: string) => TContract | undefined,
 ): Promise<OpenCodePluginFile<TContract>> {
-  const snapshot = await readPhysicalFile(filePath, label, MAX_PLUGIN_BYTES);
+  const snapshot = await readPhysicalFile(filePath, label, MAX_CONFIG_BYTES);
   if (!snapshot) return { exists: false, filePath };
   return {
     exists: true,
@@ -73,18 +72,14 @@ export function requireAvailableOpenCodePlugin(
   }
 }
 
-function hasCode(error: unknown, code: string): boolean {
-  return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
-}
-
 async function executableExists(filePath: string): Promise<boolean> {
   try {
     return (await fsp.stat(filePath)).isFile();
   } catch (error) {
     if (hasCode(error, 'ENOENT') || hasCode(error, 'ENOTDIR')) return false;
-    throw new Error(`Inspect OpenCode Node.js runtime at ${filePath}: ${
-      error instanceof Error ? error.message : String(error)
-    }`, { cause: error instanceof Error ? error : new Error(String(error)) });
+    throw new Error(`Inspect OpenCode Node.js runtime at ${filePath}: ${errorMessage(error)}`, {
+      cause: error instanceof Error ? error : new Error(String(error)),
+    });
   }
 }
 

src/plugins/qwen-command.ts

@@ -1,103 +1,20 @@
-import os from 'node:os';
 import path from 'node:path';
+import { managedScriptReference, type ManagedScriptReference } from './common.js';
+import {
+  isNodeExecutable,
+  parsePosixCommand,
+  parsePowerShellSource,
+  posixSource,
+  powerShellSource,
+} from './shell-command.js';
 
-interface ParsedArgument {
-  readonly value: string;
-  readonly next: number;
-}
-
-export interface QwenRuntimeReference {
-  readonly agentId: string;
-  readonly scriptPath: string;
-}
-
-export function sameQwenPath(left: string, right: string): boolean {
-  const normalizedLeft = path.resolve(left);
-  const normalizedRight = path.resolve(right);
-  return process.platform === 'win32'
-    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
-    : normalizedLeft === normalizedRight;
-}
-
-export function sameQwenAgentId(left: string, right: string): boolean {
-  return process.platform === 'win32'
-    ? left.toLowerCase() === right.toLowerCase()
-    : left === right;
-}
-
-function quotePosix(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
-function quotePowerShell(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
+export type QwenRuntimeReference = ManagedScriptReference;
 
 export function buildQwenCommand(scriptPath: string): string {
   if (!path.isAbsolute(process.execPath) || !path.isAbsolute(scriptPath)) {
     throw new Error('Qwen Code hook commands require absolute executable and script paths');
   }
-  if (process.platform === 'win32') {
-    return `& ${quotePowerShell(process.execPath)} ${quotePowerShell(scriptPath)}; exit $LASTEXITCODE`;
-  }
-  return `${quotePosix(process.execPath)} ${quotePosix(scriptPath)}`;
-}
-
-function readPosixArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  const apostrophe = `'"'"'`;
-  let value = '';
-  for (let index = start + 1; index < command.length;) {
-    if (command.startsWith(apostrophe, index)) {
-      value += "'";
-      index += apostrophe.length;
-      continue;
-    }
-    if (command[index] === "'") return { value, next: index + 1 };
-    value += command[index];
-    index += 1;
-  }
-  return undefined;
-}
-
-function parsePosixCommand(command: string): readonly [string, string] | undefined {
-  const executable = readPosixArgument(command, 0);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPosixArgument(command, executable.next + 1);
-  if (!script || script.next !== command.length) return undefined;
-  return [executable.value, script.value];
-}
-
-function readPowerShellArgument(command: string, start: number): ParsedArgument | undefined {
-  if (command[start] !== "'") return undefined;
-  let value = '';
-  for (let index = start + 1; index < command.length; index += 1) {
-    if (command[index] !== "'") {
-      value += command[index];
-      continue;
-    }
-    if (command[index + 1] === "'") {
-      value += "'";
-      index += 1;
-      continue;
-    }
-    return { value, next: index + 1 };
-  }
-  return undefined;
-}
-
-function parsePowerShellCommand(command: string): readonly [string, string] | undefined {
-  if (!command.startsWith('& ')) return undefined;
-  const executable = readPowerShellArgument(command, 2);
-  if (!executable || command[executable.next] !== ' ') return undefined;
-  const script = readPowerShellArgument(command, executable.next + 1);
-  if (!script || command.slice(script.next) !== '; exit $LASTEXITCODE') return undefined;
-  return [executable.value, script.value];
-}
-
-function isNodeExecutable(filePath: string): boolean {
-  const basename = path.basename(filePath).toLowerCase();
-  return basename === 'node' || basename === 'node.exe';
+  return process.platform === 'win32' ? powerShellSource(scriptPath) : posixSource(scriptPath);
 }
 
 export function qwenRuntimeReference(
@@ -105,18 +22,8 @@ export function qwenRuntimeReference(
   scriptName: string,
 ): QwenRuntimeReference | undefined {
   const parsed = process.platform === 'win32'
-    ? parsePowerShellCommand(command)
+    ? parsePowerShellSource(command)
     : parsePosixCommand(command);
-  if (!parsed
-    || !path.isAbsolute(parsed[0])
-    || !isNodeExecutable(parsed[0])
-    || !path.isAbsolute(parsed[1])
-    || path.basename(parsed[1]) !== scriptName) return undefined;
-  const agentDirectory = path.dirname(parsed[1]);
-  if (!sameQwenPath(path.dirname(agentDirectory), path.join(os.homedir(), '.elydora'))) {
-    return undefined;
-  }
-  const agentId = path.basename(agentDirectory);
-  if (!agentId || agentId === '.' || agentId === '..') return undefined;
-  return { agentId, scriptPath: parsed[1] };
+  if (!parsed || !path.isAbsolute(parsed[0]) || !isNodeExecutable(parsed[0])) return undefined;
+  return managedScriptReference(parsed[1], scriptName);
 }

src/plugins/qwen-config.ts

@@ -1,25 +1,15 @@
-import {
-  applyEdits,
-  modify,
-  parse,
-  parseTree,
-  printParseErrorCode,
-  type FormattingOptions,
-  type JSONPath,
-  type Node,
-  type ParseError,
-} from 'jsonc-parser';
+import type { JSONPath } from 'jsonc-parser';
 import type { FileSnapshot } from './managed-files.js';
+import { changeJsonc } from './jsonc-edit.js';
 import {
   MANAGED_EVENTS,
   managedQwenRemovals,
   readQwenHooks,
-  type JsonObject,
   type ManagedQwenEvent,
   type QwenGroup,
   type QwenHooks,
-  isObject,
 } from './qwen-contract.js';
+import { isObject, parseCommentedJsonObject, type JsonObject } from './strict-json.js';
 
 export const QWEN_OWNED_FILE_MARKER = '// Managed by Elydora';
 
@@ -53,50 +43,6 @@ interface DocumentOptions {
   readonly snapshot?: FileSnapshot;
 }
 
-function rejectDuplicateKeys(
-  node: Node | undefined,
-  label: string,
-  location: string[] = [],
-): void {
-  if (!node) return;
-  if (node.type === 'object') {
-    const keys = new Set<string>();
-    for (const property of node.children ?? []) {
-      const key = String(property.children?.[0]?.value);
-      const childLocation = [...location, key];
-      if (keys.has(key)) {
-        throw new Error(`${label} contains duplicate field "${childLocation.join('.')}"`);
-      }
-      keys.add(key);
-      rejectDuplicateKeys(property.children?.[1], label, childLocation);
-    }
-    return;
-  }
-  if (node.type === 'array') {
-    for (const child of node.children ?? []) rejectDuplicateKeys(child, label, location);
-  }
-}
-
-export function parseQwenJsoncObject(raw: string, label: string): JsonObject {
-  const errors: ParseError[] = [];
-  const value: unknown = parse(raw, errors, {
-    allowTrailingComma: false,
-    disallowComments: false,
-  });
-  if (errors.length > 0) {
-    const details = errors
-      .map((error) => `${printParseErrorCode(error.error)} at offset ${error.offset}`)
-      .join(', ');
-    throw new Error(`Failed to parse ${label}: ${details}`);
-  }
-  if (!isObject(value)) throw new Error(`${label} must contain a JSON object`);
-  rejectDuplicateKeys(parseTree(raw, [], {
-    allowTrailingComma: false,
-    disallowComments: false,
-  }), label);
-  return value;
-}
-
 export function qwenSourceLabel(kind: QwenDocumentKind): string {
   switch (kind) {
     case 'system-defaults': return 'Qwen Code system defaults';
@@ -122,7 +68,7 @@ function readFolderTrustEnabled(root: JsonObject, label: string): boolean | unde
 
 export function parseQwenDocument(options: DocumentOptions): QwenDocument {
   const label = `${qwenSourceLabel(options.kind)} at ${options.filePath}`;
-  const root = parseQwenJsoncObject(options.raw, label);
+  const root = parseCommentedJsonObject(options.raw, label);
   if (root.disableAllHooks !== undefined && typeof root.disableAllHooks !== 'boolean') {
     throw new Error(`${label} field "disableAllHooks" must be a boolean`);
   }
@@ -150,28 +96,6 @@ export function createQwenDocument(
   });
 }
 
-function formatting(raw: string): FormattingOptions {
-  const indentation = /\r?\n([ \t]+)\S/.exec(raw)?.[1];
-  const insertSpaces = !indentation?.includes('\t');
-  return {
-    eol: raw.includes('\r\n') ? '\r\n' : '\n',
-    insertSpaces,
-    tabSize: insertSpaces ? Math.max(1, indentation?.length ?? 2) : 1,
-  };
-}
-
-function change(
-  raw: string,
-  jsonPath: JSONPath,
-  value: unknown,
-  isArrayInsertion = false,
-): string {
-  return applyEdits(raw, modify(raw, jsonPath, value, {
-    formattingOptions: formatting(raw),
-    isArrayInsertion,
-  }));
-}
-
 function currentDocument(document: QwenDocument, raw: string): QwenDocument {
   return parseQwenDocument({
     kind: document.kind,
@@ -195,25 +119,25 @@ function removeManagedEntries(
     for (const removal of eventRemovals) {
       const groupPath: JSONPath = ['hooks', event, removal.groupIndex];
       if (removal.removeGroup) {
-        raw = change(raw, groupPath, undefined);
+        raw = changeJsonc(raw, groupPath, undefined);
         continue;
       }
       for (const handlerIndex of [...removal.handlerIndexes].sort(
         (left, right) => right - left,
       )) {
-        raw = change(raw, [...groupPath, 'hooks', handlerIndex], undefined);
+        raw = changeJsonc(raw, [...groupPath, 'hooks', handlerIndex], undefined);
       }
     }
     if (eventRemovals.length > 0) {
       const current = currentDocument(document, raw);
       if ((current.hooks[event] ?? []).length === 0) {
-        raw = change(raw, ['hooks', event], undefined);
+        raw = changeJsonc(raw, ['hooks', event], undefined);
       }
     }
   }
   const current = currentDocument(document, raw);
   if (current.hasHooksContainer && Object.keys(current.hooks).length === 0) {
-    raw = change(raw, ['hooks'], undefined);
+    raw = changeJsonc(raw, ['hooks'], undefined);
   }
   return raw;
 }
@@ -226,9 +150,9 @@ function appendGroup(
 ): string {
   const current = currentDocument(document, raw);
   if (current.hooks[event]) {
-    return change(raw, ['hooks', event, current.hooks[event].length], group, true);
+    return changeJsonc(raw, ['hooks', event, current.hooks[event].length], group, true);
   }
-  return change(raw, ['hooks', event], [group]);
+  return changeJsonc(raw, ['hooks', event], [group]);
 }
 
 export function renderQwenDocument(

src/plugins/qwen-contract.ts

@@ -1,8 +1,7 @@
+import { sameAgentId, samePath } from './common.js';
 import {
   buildQwenCommand,
   qwenRuntimeReference,
-  sameQwenAgentId,
-  sameQwenPath,
   type QwenRuntimeReference,
 } from './qwen-command.js';
 import { isObject, type JsonObject } from './strict-json.js';
@@ -283,7 +282,7 @@ export function managedQwenRemovals(
     (hooks[event] ?? []).forEach((group, groupIndex) => {
       const handlerIndexes = group.hooks.flatMap((handler, handlerIndex) => {
         const reference = managedReference(handler, scriptName, hookName, true);
-        return reference && (agentId === undefined || sameQwenAgentId(reference.agentId, agentId))
+        return reference && (agentId === undefined || sameAgentId(reference.agentId, agentId))
           ? [handlerIndex]
           : [];
       });
@@ -334,7 +333,7 @@ export function qwenRuntimeContracts(hooks: QwenHooks): QwenRuntimeContract[] {
     const post = posts.get(key);
     const failure = failures.get(key);
     if (guard.length !== 1 || post?.length !== 1 || failure?.length !== 1) continue;
-    if (!sameQwenPath(post[0].scriptPath, failure[0].scriptPath)) continue;
+    if (!samePath(post[0].scriptPath, failure[0].scriptPath)) continue;
     contracts.push({
       agentId: guard[0].agentId,
       guardPath: guard[0].scriptPath,
@@ -343,5 +342,3 @@ export function qwenRuntimeContracts(hooks: QwenHooks): QwenRuntimeContract[] {
   }
   return contracts;
 }
-
-export { isObject, type JsonObject };

src/plugins/qwen-installation.ts

@@ -5,7 +5,7 @@ import {
   AUDIT_SCRIPT,
   GUARD_SCRIPT,
 } from './qwen-contract.js';
-import { sameQwenPath } from './qwen-command.js';
+import { MAX_SOURCE_BYTES, samePath } from './common.js';
 import {
   qwenDocumentLabel,
   type RenderedQwenDocument,
@@ -30,16 +30,11 @@ import {
 
 const DISPLAY_NAME = 'Qwen Code';
 const SETTINGS_DIRECTORY_LABEL = 'Qwen Code user configuration directory';
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
-
-export type QwenRuntimePaths = ManagedRuntimePaths;
-export type PreparedQwenInstallation = PreparedManagedInstallation;
-export type { RenameFile };
 
 export async function preflightQwenInstallation(
   config: InstallConfig,
   sources: QwenSources,
-): Promise<QwenRuntimePaths> {
+): Promise<ManagedRuntimePaths> {
   requireQwenHooksEnabled(sources);
   return preflightManagedInstallation({
     agentKey: AGENT_KEY,
@@ -53,7 +48,7 @@ export async function preflightQwenInstallation(
 
 function readOnlyPreconditions(sources: QwenSources, changedPath?: string) {
   return sources.preconditions.filter((condition) => (
-    changedPath === undefined || !sameQwenPath(condition.filePath, changedPath)
+    changedPath === undefined || !samePath(condition.filePath, changedPath)
   ));
 }
 
@@ -61,7 +56,7 @@ export async function prepareQwenInstallation(
   config: InstallConfig,
   sources: QwenSources,
   rendered: RenderedQwenDocument,
-): Promise<PreparedQwenInstallation> {
+): Promise<PreparedManagedInstallation> {
   await preflightQwenInstallation(config, sources);
   const settingsSource = rendered.next ?? rendered.document.raw;
   const prepared = await prepareManagedInstallation({
@@ -88,7 +83,7 @@ export async function prepareQwenInstallation(
 }
 
 export async function commitQwenInstallation(
-  prepared: PreparedQwenInstallation,
+  prepared: PreparedManagedInstallation,
   renameFile?: RenameFile,
 ): Promise<void> {
   await commitManagedInstallation(prepared, renameFile);

src/plugins/qwen-io.ts

@@ -1,99 +1,11 @@
-import os from 'node:os';
-import path from 'node:path';
-import { generateGuardScript } from './guard-template.js';
-import { generateHookScript } from './hook-template.js';
-import {
-  AGENT_KEY,
-  type QwenRuntimeContract,
-} from './qwen-contract.js';
-import { sameQwenAgentId, sameQwenPath } from './qwen-command.js';
-import { inspectPhysicalDirectory, readPhysicalFile } from './managed-files.js';
-import { parseStrictJsonObject, type JsonObject } from './strict-json.js';
-
-function requireNonEmptyString(value: unknown, field: string, configPath: string): string {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`Elydora runtime config ${field} is invalid: ${configPath}`);
-  }
-  return value;
-}
-
-function validateRuntimeConfig(
-  config: JsonObject,
-  contract: QwenRuntimeContract,
-  configPath: string,
-): void {
-  const supported = new Set(['org_id', 'agent_id', 'kid', 'base_url', 'token', 'agent_name']);
-  const extra = Object.keys(config).find((key) => !supported.has(key));
-  if (extra) {
-    throw new Error(`Elydora runtime config has unsupported field "${extra}": ${configPath}`);
-  }
-  requireNonEmptyString(config.org_id, 'org_id', configPath);
-  requireNonEmptyString(config.kid, 'kid', configPath);
-  const agentId = requireNonEmptyString(config.agent_id, 'agent_id', configPath);
-  if (!sameQwenAgentId(agentId, contract.agentId) || config.agent_name !== AGENT_KEY) {
-    throw new Error(`Elydora runtime identity does not match Qwen Code hooks: ${configPath}`);
-  }
-  if (config.token !== undefined) requireNonEmptyString(config.token, 'token', configPath);
-  const rawBaseUrl = requireNonEmptyString(config.base_url, 'base_url', configPath);
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawBaseUrl);
-  } catch (error) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`, {
-      cause: error instanceof Error ? error : new Error(String(error)),
-    });
-  }
-  if (!['http:', 'https:'].includes(baseUrl.protocol)
-    || !baseUrl.hostname
-    || baseUrl.username
-    || baseUrl.password
-    || baseUrl.search
-    || baseUrl.hash) {
-    throw new Error(`Elydora runtime config base_url is invalid: ${configPath}`);
-  }
-}
-
-function validatePrivateKey(contents: string, keyPath: string): void {
-  const bytes = Buffer.from(contents, 'base64url');
-  if (bytes.length !== 32 || bytes.toString('base64url') !== contents) {
-    throw new Error(`Elydora private key is invalid: ${keyPath}`);
-  }
-}
-
-async function runtimeContractExists(contract: QwenRuntimeContract): Promise<boolean> {
-  const runtimeRoot = path.join(os.homedir(), '.elydora');
-  const agentDirectory = path.dirname(contract.guardPath);
-  if (!sameQwenPath(path.dirname(agentDirectory), runtimeRoot)
-    || !sameQwenPath(contract.auditPath, path.join(agentDirectory, 'hook.js'))) return false;
-  if (!await inspectPhysicalDirectory(runtimeRoot, 'Elydora runtime directory')) return false;
-  if (!await inspectPhysicalDirectory(agentDirectory, 'Elydora agent runtime directory')) {
-    return false;
-  }
-  const configPath = path.join(agentDirectory, 'config.json');
-  const keyPath = path.join(agentDirectory, 'private.key');
-  const [config, key, guard, audit] = await Promise.all([
-    readPhysicalFile(configPath, 'Elydora runtime config'),
-    readPhysicalFile(keyPath, 'Elydora private key'),
-    readPhysicalFile(contract.guardPath, 'Elydora guard runtime'),
-    readPhysicalFile(contract.auditPath, 'Elydora audit runtime'),
-  ]);
-  if (!config || !key || !guard || !audit) return false;
-  const parsed = parseStrictJsonObject(config.contents, `Elydora runtime config at ${configPath}`);
-  validateRuntimeConfig(parsed, contract, configPath);
-  validatePrivateKey(key.contents, keyPath);
-  return guard.contents === generateGuardScript(AGENT_KEY, contract.agentId)
-    && audit.contents === generateHookScript(
-      AGENT_KEY,
-      contract.agentId,
-      { nativePayload: true },
-    );
-}
+import { AGENT_KEY, type QwenRuntimeContract } from './qwen-contract.js';
+import { managedRuntimeFilesExist } from './managed-runtime-status.js';
 
 export async function qwenRuntimeFilesExist(
   contracts: readonly QwenRuntimeContract[],
 ): Promise<boolean> {
   for (const contract of contracts) {
-    if (await runtimeContractExists(contract)) return true;
+    if (await managedRuntimeFilesExist(contract, AGENT_KEY)) return true;
   }
   return false;
 }

src/plugins/qwen-sources.ts

@@ -2,18 +2,17 @@ import os from 'node:os';
 import path from 'node:path';
 import fsp from 'node:fs/promises';
 import { parse as parseDotenv } from 'dotenv';
+import { MAX_SOURCE_BYTES, pathKey, samePath } from './common.js';
 import {
   createQwenDocument,
   parseQwenDocument,
-  parseQwenJsoncObject,
   qwenDocumentLabel,
   qwenSourceLabel,
   type QwenDocument,
   type QwenDocumentKind,
 } from './qwen-config.js';
 import { readPhysicalFile, type FileSnapshot } from './managed-files.js';
-
-const MAX_SOURCE_BYTES = 2 * 1024 * 1024;
+import { parseCommentedJsonObject } from './strict-json.js';
 const HOME_ENV_KEYS = ['QWEN_HOME', 'QWEN_RUNTIME_DIR'] as const;
 
 export interface QwenSourcePrecondition {
@@ -94,7 +93,7 @@ async function resolveQwenRouting(): Promise<RoutingResult> {
 
   const readCandidate = async (filePath: string): Promise<void> => {
     const resolved = path.resolve(filePath);
-    const key = process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    const key = pathKey(resolved);
     if (visited.has(key)) return;
     visited.add(key);
     const snapshot = await readPhysicalFile(resolved, 'Qwen Code home environment');
@@ -172,13 +171,8 @@ async function canonicalPath(filePath: string): Promise<string> {
   }
 }
 
-function comparisonPath(filePath: string): string {
-  const resolved = path.resolve(filePath);
-  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
-}
-
 function isWithin(child: string, parent: string): boolean {
-  const relative = path.relative(comparisonPath(parent), comparisonPath(child));
+  const relative = path.relative(pathKey(parent), pathKey(child));
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
 
@@ -202,7 +196,7 @@ async function workspaceTrust(
     original: snapshot,
   };
   if (!snapshot) return { trusted: true, precondition };
-  const rules = parseQwenJsoncObject(snapshot.contents, `Qwen Code trusted folders at ${filePath}`);
+  const rules = parseCommentedJsonObject(snapshot.contents, `Qwen Code trusted folders at ${filePath}`);
   for (const [rulePath, level] of Object.entries(rules)) {
     if (!['TRUST_FOLDER', 'TRUST_PARENT', 'DO_NOT_TRUST'].includes(String(level))) {
       throw new Error(`Qwen Code trusted folders has invalid trust level for "${rulePath}"`);
@@ -217,7 +211,7 @@ async function workspaceTrust(
   }
   for (const [rulePath, level] of Object.entries(rules)) {
     if (level === 'DO_NOT_TRUST'
-      && comparisonPath(workspace) === comparisonPath(await canonicalPath(rulePath))) {
+      && samePath(workspace, await canonicalPath(rulePath))) {
       return { trusted: false, precondition };
     }
   }
@@ -256,7 +250,7 @@ function deduplicatePreconditions(
 ): QwenSourcePrecondition[] {
   const result = new Map<string, QwenSourcePrecondition>();
   for (const value of values) {
-    const key = comparisonPath(value.filePath);
+    const key = pathKey(value.filePath);
     if (!result.has(key)) result.set(key, value);
   }
   return [...result.values()];
@@ -276,7 +270,7 @@ export async function readQwenSources(): Promise<QwenSources> {
     canonicalPath(process.cwd()),
     canonicalPath(os.homedir()),
   ]);
-  const workspaceActive = comparisonPath(canonicalWorkspace) !== comparisonPath(canonicalHome);
+  const workspaceActive = !samePath(canonicalWorkspace, canonicalHome);
   const workspace = workspaceActive
     ? await readDocument('workspace', workspacePath)
     : createQwenDocument('workspace', workspacePath);

src/plugins/strict-json.ts

@@ -66,6 +66,13 @@ export function parseStrictJsonObject(raw: string, label: string): JsonObject {
   });
 }
 
+export function parseCommentedJsonObject(raw: string, label: string): JsonObject {
+  return parseJsonObject(raw, label, {
+    allowTrailingComma: false,
+    disallowComments: false,
+  });
+}
+
 export function parseStrictJsoncObject(raw: string, label: string): JsonObject {
   return parseJsonObject(raw, label, {
     allowTrailingComma: true,

test-support/augment-test-helpers.mjs

@@ -1,140 +1,60 @@
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+  runShell,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/augment.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/augment-io.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/augment-installation.js'),
-).href;
-export const managedInstallationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/managed-installation.js'),
-).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  managedInstallationModuleUrl,
+  readSettings,
+  registryModuleUrl,
+  runNode,
+  runProcess,
+  startApiServer,
+  writeJson,
+} from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/augment.js');
+export const ioModuleUrl = distUrl('plugins/augment-io.js');
+export const installationModuleUrl = distUrl('plugins/augment-installation.js');
 export const wrapperExtension = process.platform === 'win32' ? '.cmd' : '.sh';
 export const guardWrapperName = `augment-guard${wrapperExtension}`;
 export const auditWrapperName = `augment-hook${wrapperExtension}`;
-
-export function runProcess(command, args, env, cwd, input = '') {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      env: { ...process.env, ...env },
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export function runNode(args, env, cwd, input = '') {
-  return runProcess(process.execPath, args, env, cwd, input);
-}
+const PLUGIN = { exportName: 'augmentPlugin', moduleUrl: pluginModuleUrl };
 
 export function runHandler(handler, input, fixture) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(handler.command, {
-      cwd: fixture.projectDir,
-      env: { ...process.env, HOME: fixture.homeDir, USERPROFILE: fixture.homeDir },
-      shell: true,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export async function writeJson(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const contents = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, contents, { encoding: 'utf-8', mode: 0o600 });
+  return runShell(handler.command, homeEnvironment(fixture), fixture.projectDir, input);
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'augment',
-    orgId: 'org-1',
-    agentId: 'agent-1',
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('augment', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument) {
-  const source = `
-    import { augmentPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await augmentPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      HOME: fixture.homeDir,
-      USERPROFILE: fixture.homeDir,
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.projectDir,
-  );
+export function runPlugin(fixture, method, argument) {
+  return basePlugin(PLUGIN, fixture, method, argument);
 }
 
 export async function createFixture({ baseUrl = 'http://127.0.0.1:9', settings } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-augment-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %AUGGIE%");
-  const projectDir = path.join(rootDir, 'project with spaces');
-  const settingsPath = path.join(homeDir, '.augment', 'settings.json');
-  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
-  if (settings !== undefined) await writeJson(settingsPath, settings);
-  const fixture = {
-    agentDir,
-    auditWrapperPath: path.join(agentDir, auditWrapperName),
+  const base = await createFixtureRoot('elydora-augment-', "home with spaces and 'quote %AUGGIE%");
+  const settingsPath = path.join(base.homeDir, '.augment', 'settings.json');
+  await writeOptionalJson(settingsPath, settings);
+  return {
+    ...base,
+    auditWrapperPath: path.join(base.agentDir, auditWrapperName),
     baseUrl,
-    guardScriptPath,
-    guardWrapperPath: path.join(agentDir, guardWrapperName),
-    homeDir,
-    hookScriptPath,
-    projectDir,
-    rootDir,
+    guardWrapperPath: path.join(base.agentDir, guardWrapperName),
     settingsPath,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
-  return fixture;
-}
-
-export async function readSettings(filePath) {
-  const raw = await readFile(filePath, 'utf-8');
-  return { raw, settings: JSON.parse(raw) };
 }
 
 export function generatedCommand(wrapperPath) {
@@ -150,34 +70,3 @@ export function managedHandler(settings, event, wrapperPath) {
   }
   return undefined;
 }
-
-export async function startApiServer({ status = 'active', operationStatus = 201 } = {}) {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ headers: request.headers, method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus >= 200 && operationStatus < 300
-      ? JSON.stringify({ operation: { accepted: true } })
-      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/claudecode-test-helpers.mjs

@@ -1,38 +1,32 @@
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  optionalEnvironment,
+  runPlugin as basePlugin,
+  runProcess as baseProcess,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/claudecode.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/claudecode-io.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/claudecode-installation.js'),
-).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  readSettings,
+  registryModuleUrl,
+  startApiServer,
+  writeJson,
+} from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/claudecode.js');
+export const ioModuleUrl = distUrl('plugins/claudecode-io.js');
+export const installationModuleUrl = distUrl('plugins/claudecode-installation.js');
+const PLUGIN = { exportName: 'claudecodePlugin', moduleUrl: pluginModuleUrl };
 
 export function runProcess(command, args, env, cwd, input = '', unset = []) {
-  return new Promise((resolve, reject) => {
-    const childEnv = { ...process.env, ...env };
-    for (const key of unset) delete childEnv[key];
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnv,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
+  return baseProcess(command, args, env, cwd, input, { unset });
 }
 
 export function runNode(args, env, cwd, input = '', unset = []) {
@@ -44,8 +38,7 @@ export function runClaudeHook(handler, input, fixture, environment = {}) {
     handler.command,
     handler.args,
     {
-      HOME: fixture.homeDir,
-      USERPROFILE: fixture.homeDir,
+      ...homeEnvironment(fixture),
       CLAUDE_CONFIG_DIR: fixture.claudeConfigOverride ?? '',
       ...environment,
     },
@@ -54,51 +47,16 @@ export function runClaudeHook(handler, input, fixture, environment = {}) {
   );
 }
 
-export async function writeJson(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const contents = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, contents, { encoding: 'utf-8', mode: 0o600 });
-}
-
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'claudecode',
-    orgId: 'org-1',
-    agentId: 'agent-1',
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('claudecode', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument, environment = {}) {
-  const source = `
-    import { claudecodePlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await claudecodePlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  const env = {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
-    ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-    ELYDORA_TEST_METHOD: method,
-    ...environment,
-  };
-  const unset = [];
-  if (fixture.claudeConfigOverride === undefined) unset.push('CLAUDE_CONFIG_DIR');
-  else env.CLAUDE_CONFIG_DIR = fixture.claudeConfigOverride;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    env,
-    fixture.projectDir,
-    '',
-    unset,
-  );
+export function runPlugin(fixture, method, argument, environment = {}) {
+  const configDir = optionalEnvironment('CLAUDE_CONFIG_DIR', fixture.claudeConfigOverride);
+  return basePlugin(PLUGIN, fixture, method, argument, {
+    env: { ...environment, ...configDir.env },
+    unset: configDir.unset,
+  });
 }
 
 export async function createFixture({
@@ -106,42 +64,25 @@ export async function createFixture({
   settings,
   explicitClaudeConfig = true,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-claude-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %CLAUDE_HOOK_EVENT%");
-  const projectDir = path.join(rootDir, 'project with spaces');
+  const base = await createFixtureRoot(
+    'elydora-claude-',
+    "home with spaces and 'quote %CLAUDE_HOOK_EVENT%",
+  );
   const claudeConfigDir = explicitClaudeConfig
-    ? path.join(homeDir, 'custom claude')
-    : path.join(homeDir, '.claude');
+    ? path.join(base.homeDir, 'custom claude')
+    : path.join(base.homeDir, '.claude');
   const settingsPath = path.join(claudeConfigDir, 'settings.json');
-  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
-  if (settings !== undefined) await writeJson(settingsPath, settings);
-  const fixture = {
-    agentDir,
+  await writeOptionalJson(settingsPath, settings);
+  return {
+    ...base,
     baseUrl,
     claudeConfigDir,
     claudeConfigOverride: explicitClaudeConfig ? claudeConfigDir : undefined,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
-    projectDir,
-    rootDir,
     settingsPath,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
-  return fixture;
-}
-
-export async function readSettings(filePath) {
-  const raw = await readFile(filePath, 'utf-8');
-  return { raw, settings: JSON.parse(raw) };
 }
 
 export function managedHandler(settings, event) {
@@ -173,34 +114,3 @@ export function assertManagedHandler(handler, scriptPath, statusMessage) {
 export function legacyHandler(scriptPath) {
   return { type: 'command', command: `node "${scriptPath}"` };
 }
-
-export async function startApiServer({ status = 'active', operationStatus = 201 } = {}) {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ headers: request.headers, method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus >= 200 && operationStatus < 300
-      ? JSON.stringify({ operation: { accepted: true } })
-      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/cline-test-helpers.mjs

@@ -1,87 +1,39 @@
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
+import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32, 7).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/cline.js')).href;
-export const contractModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/cline-contract.js'),
-).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/cline-io.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/cline-installation.js'),
-).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  readJson,
+  registryModuleUrl,
+  runNode,
+  runProcess,
+  startApiServer,
+} from './harness.mjs';
 
-export function runProcess(command, args, env, cwd, input = '') {
-  return new Promise((resolve, reject) => {
-    const childEnvironment = { ...process.env, ...env };
-    for (const [name, value] of Object.entries(env)) {
-      if (value === undefined) delete childEnvironment[name];
-    }
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnvironment,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export function runNode(args, env, cwd, input = '') {
-  return runProcess(process.execPath, args, env, cwd, input);
-}
+export const pluginModuleUrl = distUrl('plugins/cline.js');
+export const contractModuleUrl = distUrl('plugins/cline-contract.js');
+export const ioModuleUrl = distUrl('plugins/cline-io.js');
+export const installationModuleUrl = distUrl('plugins/cline-installation.js');
+const PLUGIN = { exportName: 'clinePlugin', moduleUrl: pluginModuleUrl };
 
 export function environment(fixture, clineDir = fixture.clineDir) {
-  return {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
-    CLINE_DIR: clineDir === null ? undefined : clineDir,
-  };
+  return { ...homeEnvironment(fixture), CLINE_DIR: clineDir === null ? undefined : clineDir };
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'cline',
-    orgId: 'org-1',
-    agentId: fixture.agentId,
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('cline', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument, clineDir = fixture.clineDir) {
-  const source = `
-    import { clinePlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await clinePlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      ...environment(fixture, clineDir),
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.projectDir,
-  );
+export function runPlugin(fixture, method, argument, clineDir = fixture.clineDir) {
+  return basePlugin(PLUGIN, fixture, method, argument, { env: environment(fixture, clineDir) });
 }
 
 async function writeOptional(filePath, contents) {
@@ -96,66 +48,26 @@ export async function createFixture({
   existingAudit,
   existingGuard,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-cline-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %CLINE%");
-  const projectDir = path.join(rootDir, 'project with spaces');
-  const clineDir = path.join(rootDir, 'custom-cline-home');
+  const base = await createFixtureRoot(
+    'elydora-cline-',
+    "home with spaces and 'quote %CLINE%",
+    { agentId },
+  );
+  const clineDir = path.join(base.rootDir, 'custom-cline-home');
   const hooksDir = path.join(clineDir, 'hooks');
   const guardWrapperPath = path.join(hooksDir, 'PreToolUse.mjs');
   const auditWrapperPath = path.join(hooksDir, 'PostToolUse.mjs');
-  const agentDir = path.join(homeDir, '.elydora', agentId);
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
   await writeOptional(guardWrapperPath, existingGuard);
   await writeOptional(auditWrapperPath, existingAudit);
-  const fixture = {
-    agentDir,
-    agentId,
+  return {
+    ...base,
     auditWrapperPath,
     baseUrl,
     clineDir,
-    guardScriptPath,
     guardWrapperPath,
-    homeDir,
-    hookScriptPath,
     hooksDir,
-    projectDir,
-    rootDir,
     install(overrides = {}, clineDirOverride = this.clineDir) {
       return runPlugin(this, 'install', installConfig(this, overrides), clineDirOverride);
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
-  };
-  return fixture;
-}
-
-export async function readJson(filePath) {
-  return JSON.parse(await readFile(filePath, 'utf-8'));
-}
-
-export async function startApiServer() {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ method: request.method, url: request.url, raw });
-    response.writeHead(201, { 'Content-Type': 'application/json' });
-    response.end('{"operation":{"accepted":true}}');
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
   };
 }

test-support/codex-test-helpers.mjs

@@ -1,139 +1,58 @@
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runNode as baseNode,
+  runPlugin as basePlugin,
+  runProcess,
+  runShell,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/codex.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/codex-io.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/codex-installation.js'),
-).href;
+export { VALID_PRIVATE_KEY, registryModuleUrl, startApiServer, writeJson } from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/codex.js');
+export const ioModuleUrl = distUrl('plugins/codex-io.js');
+export const installationModuleUrl = distUrl('plugins/codex-installation.js');
+const PLUGIN = { exportName: 'codexPlugin', moduleUrl: pluginModuleUrl };
 
 export function runNode(args, env, cwd, input = '') {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, args, {
-      cwd,
-      env: { ...process.env, CODEX_HOME: '', ...env },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
+  return baseNode(args, { CODEX_HOME: '', ...env }, cwd, input);
 }
 
 export function runHook(handler, input, fixture, environment = {}) {
   const command = process.platform === 'win32' ? handler.commandWindows : handler.command;
-  return new Promise((resolve, reject) => {
-    const child = process.platform === 'win32'
-      ? spawn(command, {
-        shell: true,
-        cwd: fixture.projectDir,
-        env: {
-          ...process.env,
-          CODEX_HOME: '',
-          HOME: fixture.homeDir,
-          USERPROFILE: fixture.homeDir,
-          ...environment,
-        },
-        stdio: ['pipe', 'pipe', 'pipe'],
-      })
-      : spawn('/bin/sh', ['-c', command], {
-        cwd: fixture.projectDir,
-        env: {
-          ...process.env,
-          CODEX_HOME: '',
-          HOME: fixture.homeDir,
-          USERPROFILE: fixture.homeDir,
-          ...environment,
-        },
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export async function writeJson(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const contents = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, contents, { encoding: 'utf-8', mode: 0o600 });
+  const env = { CODEX_HOME: '', ...homeEnvironment(fixture), ...environment };
+  return process.platform === 'win32'
+    ? runShell(command, env, fixture.projectDir, input)
+    : runProcess('/bin/sh', ['-c', command], env, fixture.projectDir, input);
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'codex',
-    orgId: 'org-1',
-    agentId: 'agent-1',
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('codex', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument, environment = {}) {
-  const source = `
-    import { codexPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await codexPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      HOME: fixture.homeDir,
-      USERPROFILE: fixture.homeDir,
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-      ...environment,
-    },
-    fixture.projectDir,
-  );
+export function runPlugin(fixture, method, argument, environment = {}) {
+  return basePlugin(PLUGIN, fixture, method, argument, { env: { CODEX_HOME: '', ...environment } });
 }
 
 export async function createFixture({ existingConfig, baseUrl = 'http://127.0.0.1:9' } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-codex-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %ELYDORA_HOOK_PATH%");
-  const projectDir = path.join(rootDir, 'project with spaces');
-  const configPath = path.join(homeDir, '.codex', 'hooks.json');
-  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
-  if (existingConfig !== undefined) await writeJson(configPath, existingConfig);
+  const base = await createFixtureRoot(
+    'elydora-codex-',
+    "home with spaces and 'quote %ELYDORA_HOOK_PATH%",
+  );
+  const configPath = path.join(base.homeDir, '.codex', 'hooks.json');
+  await writeOptionalJson(configPath, existingConfig);
   return {
-    agentDir,
+    ...base,
     baseUrl,
     configPath,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
-    projectDir,
-    rootDir,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
 }
 
@@ -170,39 +89,3 @@ export function legacyHandler(scriptPath, statusMessage) {
     statusMessage,
   };
 }
-
-export async function startApiServer({ status = 'active', operationStatus = 201 } = {}) {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({
-      headers: request.headers,
-      method: request.method,
-      url: request.url,
-      raw,
-    });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus >= 200 && operationStatus < 300
-      ? JSON.stringify({ operation: { accepted: true } })
-      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/copilot-test-helpers.mjs

@@ -1,87 +1,44 @@
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+  runProcess,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32, 11).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/copilot.js')).href;
-export const contractModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/copilot-contract.js'),
-).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/copilot-installation.js'),
-).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/copilot-io.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  readJson,
+  registryModuleUrl,
+  runNode,
+  runProcess,
+  startApiServer,
+  writeJson,
+} from './harness.mjs';
 
-export function runProcess(command, args, env, cwd, input = '') {
-  return new Promise((resolve, reject) => {
-    const childEnvironment = { ...process.env, ...env };
-    for (const [name, value] of Object.entries(env)) {
-      if (value === undefined) delete childEnvironment[name];
-    }
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnvironment,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export function runNode(args, env, cwd, input = '') {
-  return runProcess(process.execPath, args, env, cwd, input);
-}
+export const pluginModuleUrl = distUrl('plugins/copilot.js');
+export const contractModuleUrl = distUrl('plugins/copilot-contract.js');
+export const installationModuleUrl = distUrl('plugins/copilot-installation.js');
+export const ioModuleUrl = distUrl('plugins/copilot-io.js');
+const PLUGIN = { exportName: 'copilotPlugin', moduleUrl: pluginModuleUrl };
 
 export function environment(fixture, copilotHome = fixture.copilotHome) {
   return {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
+    ...homeEnvironment(fixture),
     COPILOT_HOME: copilotHome === null ? undefined : copilotHome,
   };
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'copilot',
-    orgId: 'org-1',
-    agentId: fixture.agentId,
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('copilot', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument, copilotHome = fixture.copilotHome) {
-  const source = `
-    import { copilotPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await copilotPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      ...environment(fixture, copilotHome),
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.projectDir,
-  );
+export function runPlugin(fixture, method, argument, copilotHome = fixture.copilotHome) {
+  return basePlugin(PLUGIN, fixture, method, argument, { env: environment(fixture, copilotHome) });
 }
 
 export function runHook(handler, fixture, input) {
@@ -91,16 +48,6 @@ export function runHook(handler, fixture, input) {
   return runProcess(command[0], command[1], environment(fixture), fixture.projectDir, input);
 }
 
-export async function writeJson(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const source = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, source, { mode: 0o600 });
-}
-
-async function writeOptional(filePath, value) {
-  if (value !== undefined) await writeJson(filePath, value);
-}
-
 export async function createFixture({
   agentId = 'agent-1',
   baseUrl = 'http://127.0.0.1:9',
@@ -113,46 +60,36 @@ export async function createFixture({
   repositorySettings,
   localSettings,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-copilot-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %COPILOT%");
-  const projectDir = path.join(rootDir, 'project with spaces');
+  const base = await createFixtureRoot(
+    'elydora-copilot-',
+    "home with spaces and 'quote %COPILOT%",
+    { agentId },
+  );
+  const { projectDir, rootDir } = base;
   const copilotHome = path.join(rootDir, "custom Copilot 'home");
   const hooksDir = path.join(copilotHome, 'hooks');
   const configPath = path.join(hooksDir, 'elydora-audit.json');
   const legacyPath = path.join(projectDir, '.github', 'hooks', 'hooks.json');
-  const agentDir = path.join(homeDir, '.elydora', agentId);
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
   await Promise.all([
-    writeOptional(configPath, userConfig),
-    writeOptional(legacyPath, legacyConfig),
-    writeOptional(path.join(copilotHome, 'settings.json'), userSettings),
-    writeOptional(path.join(copilotHome, 'config.json'), legacyUserConfig),
-    writeOptional(path.join(projectDir, '.claude', 'settings.json'), claudeSettings),
-    writeOptional(path.join(projectDir, '.claude', 'settings.local.json'), claudeLocalSettings),
-    writeOptional(path.join(projectDir, '.github', 'copilot', 'settings.json'), repositorySettings),
-    writeOptional(path.join(projectDir, '.github', 'copilot', 'settings.local.json'), localSettings),
+    writeOptionalJson(configPath, userConfig),
+    writeOptionalJson(legacyPath, legacyConfig),
+    writeOptionalJson(path.join(copilotHome, 'settings.json'), userSettings),
+    writeOptionalJson(path.join(copilotHome, 'config.json'), legacyUserConfig),
+    writeOptionalJson(path.join(projectDir, '.claude', 'settings.json'), claudeSettings),
+    writeOptionalJson(path.join(projectDir, '.claude', 'settings.local.json'), claudeLocalSettings),
+    writeOptionalJson(path.join(projectDir, '.github', 'copilot', 'settings.json'), repositorySettings),
+    writeOptionalJson(path.join(projectDir, '.github', 'copilot', 'settings.local.json'), localSettings),
   ]);
   return {
-    agentDir,
-    agentId,
+    ...base,
     baseUrl,
     configPath,
     copilotHome,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
     hooksDir,
     legacyPath,
-    projectDir,
-    rootDir,
     install(overrides = {}, copilotHomeOverride = this.copilotHome) {
       return runPlugin(this, 'install', installConfig(this, overrides), copilotHomeOverride);
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
 }
 
@@ -193,35 +130,3 @@ export function legacyManagedConfig(fixture, extraHooks = {}) {
     },
   };
 }
-
-export async function readJson(filePath) {
-  return JSON.parse(await readFile(filePath, 'utf-8'));
-}
-
-export async function startApiServer() {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ method: request.method, url: request.url, raw });
-    response.writeHead(request.method === 'POST' ? 201 : 200, {
-      'Content-Type': 'application/json',
-    });
-    response.end(request.method === 'POST'
-      ? '{"operation":{"accepted":true}}'
-      : '{"agent":{"status":"active"}}');
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/cursor-test-helpers.mjs

@@ -1,127 +1,56 @@
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+  runProcess,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/cursor.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/cursor-io.js')).href;
-export const contractModuleUrl = pathToFileURL(path.resolve('dist/plugins/cursor-contract.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/cursor-installation.js'),
-).href;
+export {
+  VALID_PRIVATE_KEY,
+  registryModuleUrl,
+  runNode,
+  startApiServer,
+  writeJson,
+} from './harness.mjs';
 
-export function runNode(args, env, cwd, input = '') {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, args, {
-      cwd,
-      env: { ...process.env, ...env },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
+export const pluginModuleUrl = distUrl('plugins/cursor.js');
+export const ioModuleUrl = distUrl('plugins/cursor-io.js');
+export const contractModuleUrl = distUrl('plugins/cursor-contract.js');
+export const installationModuleUrl = distUrl('plugins/cursor-installation.js');
+const PLUGIN = { exportName: 'cursorPlugin', moduleUrl: pluginModuleUrl };
 
 export function runHook(handler, input, fixture, environment = {}) {
   const executable = process.platform === 'win32' ? 'powershell.exe' : '/bin/sh';
   const args = process.platform === 'win32'
     ? ['-NoProfile', '-NonInteractive', '-Command', handler.command]
     : ['-c', handler.command];
-  return new Promise((resolve, reject) => {
-    const child = spawn(executable, args, {
-      env: {
-        ...process.env,
-        HOME: fixture.homeDir,
-        USERPROFILE: fixture.homeDir,
-        ...environment,
-      },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export async function writeJson(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const contents = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, contents, { encoding: 'utf-8', mode: 0o600 });
+  return runProcess(executable, args, { ...homeEnvironment(fixture), ...environment }, undefined, input);
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'cursor',
-    orgId: 'org-1',
-    agentId: 'agent-1',
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('cursor', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument) {
-  const source = `
-    import { cursorPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await cursorPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      HOME: fixture.homeDir,
-      USERPROFILE: fixture.homeDir,
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.projectDir,
-  );
+export function runPlugin(fixture, method, argument) {
+  return basePlugin(PLUGIN, fixture, method, argument);
 }
 
 export async function createFixture({ existingConfig, baseUrl = 'http://127.0.0.1:9' } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-cursor-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote");
-  const projectDir = path.join(rootDir, 'project with spaces');
-  const configPath = path.join(homeDir, '.cursor', 'hooks.json');
-  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
-  if (existingConfig !== undefined) await writeJson(configPath, existingConfig);
+  const base = await createFixtureRoot('elydora-cursor-', "home with spaces and 'quote");
+  const configPath = path.join(base.homeDir, '.cursor', 'hooks.json');
+  await writeOptionalJson(configPath, existingConfig);
   return {
-    agentDir,
+    ...base,
     baseUrl,
     configPath,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
-    projectDir,
-    rootDir,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
 }
 
@@ -145,34 +74,3 @@ export function assertNativeHandler(handler) {
 export function legacyHandler(scriptPath) {
   return { command: `node "${scriptPath}"` };
 }
-
-export async function startApiServer({ status = 'active', operationStatus = 201 } = {}) {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus >= 200 && operationStatus < 300
-      ? JSON.stringify({ operation: { accepted: true } })
-      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/droid-test-helpers.mjs

@@ -1,104 +1,58 @@
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
+import { mkdir, readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { parse } from 'jsonc-parser';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+  runProcess as baseProcess,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32, 13).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/droid.js')).href;
-export const configModuleUrl = pathToFileURL(path.resolve('dist/plugins/droid-config.js')).href;
-export const contractModuleUrl = pathToFileURL(path.resolve('dist/plugins/droid-contract.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/droid-installation.js'),
-).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/droid-io.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  homeEnvironment as environment,
+  registryModuleUrl,
+  runNode,
+  startApiServer,
+  writeJson as writeConfig,
+} from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/droid.js');
+export const configModuleUrl = distUrl('plugins/droid-config.js');
+export const contractModuleUrl = distUrl('plugins/droid-contract.js');
+export const installationModuleUrl = distUrl('plugins/droid-installation.js');
+export const ioModuleUrl = distUrl('plugins/droid-io.js');
+const PLUGIN = { exportName: 'droidPlugin', moduleUrl: pluginModuleUrl };
 
 export function runProcess(command, args, env, cwd, input = '', shell = false) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-      cwd,
-      env: { ...process.env, ...env },
-      shell,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export function runNode(args, env, cwd, input = '') {
-  return runProcess(process.execPath, args, env, cwd, input);
-}
-
-export function environment(fixture) {
-  return { HOME: fixture.homeDir, USERPROFILE: fixture.homeDir };
+  return baseProcess(command, args, env, cwd, input, { shell });
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'droid',
-    orgId: 'org-1',
-    agentId: fixture.agentId,
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('droid', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument) {
-  const source = `
-    import { droidPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await droidPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      ...environment(fixture),
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.workspaceDir,
-  );
+export function runPlugin(fixture, method, argument) {
+  return basePlugin(PLUGIN, fixture, method, argument, { cwd: fixture.workspaceDir });
 }
 
 export function runHook(command, fixture, input) {
+  const env = homeEnvironment(fixture);
   if (process.platform === 'win32') {
     return runProcess(
       'powershell.exe',
       ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command],
-      environment(fixture),
+      env,
       fixture.workspaceDir,
       input,
     );
   }
-  return runProcess('/bin/sh', ['-c', command], environment(fixture), fixture.workspaceDir, input);
-}
-
-export async function writeConfig(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const source = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, source, { mode: 0o600 });
-}
-
-async function writeOptional(filePath, value) {
-  if (value !== undefined) await writeConfig(filePath, value);
+  return runProcess('/bin/sh', ['-c', command], env, fixture.workspaceDir, input);
 }
 
 export async function createFixture({
@@ -111,51 +65,44 @@ export async function createFixture({
   projectSettings,
   projectLocalSettings,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-droid-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %DROID%");
-  const workspaceDir = path.join(rootDir, 'workspace with spaces');
-  const factoryDir = path.join(homeDir, '.factory');
+  const base = await createFixtureRoot(
+    'elydora-droid-',
+    "home with spaces and 'quote %DROID%",
+    { agentId, projectName: 'workspace with spaces' },
+  );
+  const workspaceDir = base.projectDir;
+  const factoryDir = path.join(base.homeDir, '.factory');
   const rootPath = path.join(factoryDir, 'hooks.json');
   const legacyPath = path.join(factoryDir, 'hooks', 'hooks.json');
   const settingsPath = path.join(factoryDir, 'settings.json');
   const localSettingsPath = path.join(factoryDir, 'settings.local.json');
-  const agentDir = path.join(homeDir, '.elydora', agentId);
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
   const projectFactoryDir = path.join(workspaceDir, '.factory');
   const projectSettingsPath = path.join(projectFactoryDir, 'settings.json');
   const projectLocalSettingsPath = path.join(projectFactoryDir, 'settings.local.json');
   await mkdir(path.join(workspaceDir, '.git'), { recursive: true });
   await Promise.all([
-    writeOptional(rootPath, rootConfig),
-    writeOptional(legacyPath, legacyConfig),
-    writeOptional(settingsPath, settings),
-    writeOptional(localSettingsPath, localSettings),
-    writeOptional(projectSettingsPath, projectSettings),
-    writeOptional(projectLocalSettingsPath, projectLocalSettings),
+    writeOptionalJson(rootPath, rootConfig),
+    writeOptionalJson(legacyPath, legacyConfig),
+    writeOptionalJson(settingsPath, settings),
+    writeOptionalJson(localSettingsPath, localSettings),
+    writeOptionalJson(projectSettingsPath, projectSettings),
+    writeOptionalJson(projectLocalSettingsPath, projectLocalSettings),
   ]);
+  const { projectDir: _projectDir, ...fixture } = base;
   return {
-    agentDir,
-    agentId,
+    ...fixture,
     baseUrl,
     factoryDir,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
     legacyPath,
     localSettingsPath,
     projectLocalSettingsPath,
     projectSettingsPath,
-    rootDir,
     rootPath,
     settingsPath,
     workspaceDir,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
 }
 
@@ -208,31 +155,3 @@ export async function assertNoTransactionFiles(fixture) {
   const leaked = names.filter((name) => /\.(tmp|rollback)$/.test(name));
   if (leaked.length > 0) throw new Error(`Leaked transaction files: ${leaked.join(', ')}`);
 }
-
-export async function startApiServer() {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ method: request.method, url: request.url, raw });
-    response.writeHead(request.method === 'POST' ? 201 : 200, {
-      'Content-Type': 'application/json',
-    });
-    response.end(request.method === 'POST'
-      ? '{"operation":{"accepted":true}}'
-      : '{"agent":{"status":"active"}}');
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/gemini-test-helpers.mjs

@@ -1,65 +1,49 @@
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { parse } from 'jsonc-parser';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  optionalEnvironment,
+  runPlugin as basePlugin,
+  runProcess as baseProcess,
+  windowsPowerShellPath,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/gemini.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/gemini-io.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/gemini-installation.js'),
-).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  parseJsonc as parseSettings,
+  readJsoncSettings as readSettings,
+  registryModuleUrl,
+  startApiServer,
+  writeJson as writeSettings,
+} from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/gemini.js');
+export const ioModuleUrl = distUrl('plugins/gemini-io.js');
+export const installationModuleUrl = distUrl('plugins/gemini-installation.js');
+const PLUGIN = { exportName: 'geminiPlugin', moduleUrl: pluginModuleUrl };
 
 export function runProcess(command, args, env, cwd, input = '', unset = []) {
-  return new Promise((resolve, reject) => {
-    const childEnv = { ...process.env, ...env };
-    for (const key of unset) delete childEnv[key];
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnv,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
+  return baseProcess(command, args, env, cwd, input, { unset });
 }
 
 export function runNode(args, env, cwd, input = '', unset = []) {
   return runProcess(process.execPath, args, env, cwd, input, unset);
 }
 
-function windowsPowerShell() {
-  return path.win32.join(
-    process.env.SystemRoot || 'C:\\Windows',
-    'System32',
-    'WindowsPowerShell',
-    'v1.0',
-    'powershell.exe',
-  );
-}
-
 export function runGeminiHook(handler, input, fixture, environment = {}) {
   const env = {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
+    ...homeEnvironment(fixture),
     GEMINI_CLI_HOME: fixture.geminiCliHomeOverride ?? '',
     ...environment,
   };
   if (process.platform === 'win32') {
     return runProcess(
-      windowsPowerShell(),
+      windowsPowerShellPath(),
       [
         '-NoLogo',
         '-NoProfile',
@@ -75,66 +59,16 @@ export function runGeminiHook(handler, input, fixture, environment = {}) {
   return runProcess('/bin/bash', ['-c', handler.command], env, fixture.projectDir, input);
 }
 
-export async function writeSettings(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const contents = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, contents, { encoding: 'utf-8', mode: 0o600 });
-}
-
-export function parseSettings(raw) {
-  const errors = [];
-  const value = parse(raw, errors, {
-    allowTrailingComma: false,
-    disallowComments: false,
-  });
-  assert.deepEqual(errors, []);
-  return value;
-}
-
-export async function readSettings(filePath) {
-  const raw = await readFile(filePath, 'utf-8');
-  return { raw, settings: parseSettings(raw) };
-}
-
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'gemini',
-    orgId: 'org-1',
-    agentId: 'agent-1',
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('gemini', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument, environment = {}) {
-  const source = `
-    import { geminiPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await geminiPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  const env = {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
-    ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-    ELYDORA_TEST_METHOD: method,
-    ...environment,
-  };
-  const unset = [];
-  if (fixture.geminiCliHomeOverride === undefined) unset.push('GEMINI_CLI_HOME');
-  else env.GEMINI_CLI_HOME = fixture.geminiCliHomeOverride;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    env,
-    fixture.projectDir,
-    '',
-    unset,
-  );
+export function runPlugin(fixture, method, argument, environment = {}) {
+  const home = optionalEnvironment('GEMINI_CLI_HOME', fixture.geminiCliHomeOverride);
+  return basePlugin(PLUGIN, fixture, method, argument, {
+    env: { ...environment, ...home.env },
+    unset: home.unset,
+  });
 }
 
 export async function createFixture({
@@ -142,38 +76,23 @@ export async function createFixture({
   settings,
   explicitGeminiHome = true,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-gemini-'));
-  const homeDir = path.join(
-    rootDir,
+  const base = await createFixtureRoot(
+    'elydora-gemini-',
     "home with spaces and 'quote $GEMINI_CWD %GEMINI_CWD%",
   );
-  const projectDir = path.join(rootDir, 'project with spaces');
-  const geminiCliHome = homeDir;
+  const geminiCliHome = base.homeDir;
   const settingsPath = path.join(geminiCliHome, '.gemini', 'settings.json');
-  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
-  if (settings !== undefined) await writeSettings(settingsPath, settings);
-  const fixture = {
-    agentDir,
+  await writeOptionalJson(settingsPath, settings);
+  return {
+    ...base,
     baseUrl,
     geminiCliHome,
     geminiCliHomeOverride: explicitGeminiHome ? geminiCliHome : undefined,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
-    projectDir,
-    rootDir,
     settingsPath,
     install(overrides = {}, environment = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides), environment);
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
-  return fixture;
 }
 
 export function managedHandler(settings, event, name) {
@@ -202,34 +121,3 @@ export function assertManagedHandler(handler, name) {
 export function legacyHandler(scriptPath) {
   return { type: 'command', command: `node "${scriptPath}"` };
 }
-
-export async function startApiServer({ status = 'active', operationStatus = 201 } = {}) {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ headers: request.headers, method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus >= 200 && operationStatus < 300
-      ? JSON.stringify({ operation: { accepted: true } })
-      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/grok-test-helpers.mjs

@@ -1,39 +1,27 @@
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  optionalEnvironment,
+  runPlugin as basePlugin,
+  runProcess as baseProcess,
+  runShell,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/grok.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const contractModuleUrl = pathToFileURL(path.resolve('dist/plugins/grok-contract.js')).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/grok-io.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/grok-installation.js'),
-).href;
-export const cliPath = path.resolve('dist/cli.js');
+export { VALID_PRIVATE_KEY, cliPath, registryModuleUrl, startApiServer } from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/grok.js');
+export const contractModuleUrl = distUrl('plugins/grok-contract.js');
+export const ioModuleUrl = distUrl('plugins/grok-io.js');
+export const installationModuleUrl = distUrl('plugins/grok-installation.js');
+const PLUGIN = { exportName: 'grokPlugin', moduleUrl: pluginModuleUrl };
 
 export function runProcess(command, args, env, cwd, input = '', unset = []) {
-  return new Promise((resolve, reject) => {
-    const childEnv = { ...process.env, ...env };
-    for (const key of unset) delete childEnv[key];
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnv,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
+  return baseProcess(command, args, env, cwd, input, { unset });
 }
 
 export function runNode(args, env, cwd, input = '', unset = []) {
@@ -41,68 +29,23 @@ export function runNode(args, env, cwd, input = '', unset = []) {
 }
 
 export function runGrokHook(command, input, fixture, environment = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, {
-      shell: true,
-      cwd: fixture.projectDir,
-      env: {
-        ...process.env,
-        HOME: fixture.homeDir,
-        USERPROFILE: fixture.homeDir,
-        GROK_HOME: fixture.grokHomeOverride ?? '',
-        ...environment,
-      },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
+  return runShell(command, {
+    ...homeEnvironment(fixture),
+    GROK_HOME: fixture.grokHomeOverride ?? '',
+    ...environment,
+  }, fixture.projectDir, input);
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'grok',
-    orgId: 'org-1',
-    agentId: 'agent-1',
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('grok', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument, environment = {}) {
-  const source = `
-    import { grokPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await grokPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  const env = {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
-    ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-    ELYDORA_TEST_METHOD: method,
-    ...environment,
-  };
-  const unset = [];
-  if (fixture.grokHomeOverride === undefined) unset.push('GROK_HOME');
-  else env.GROK_HOME = fixture.grokHomeOverride;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    env,
-    fixture.projectDir,
-    '',
-    unset,
-  );
+export function runPlugin(fixture, method, argument, environment = {}) {
+  const home = optionalEnvironment('GROK_HOME', fixture.grokHomeOverride);
+  return basePlugin(PLUGIN, fixture, method, argument, {
+    env: { ...environment, ...home.env },
+    unset: home.unset,
+  });
 }
 
 async function writeOptional(filePath, contents) {
@@ -116,37 +59,25 @@ export async function createFixture({
   config,
   explicitGrokHome = true,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-grok-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %GROK_HOOK_EVENT%");
-  const projectDir = path.join(rootDir, 'project with spaces');
+  const base = await createFixtureRoot(
+    'elydora-grok-',
+    "home with spaces and 'quote %GROK_HOOK_EVENT%",
+  );
   const grokHome = explicitGrokHome
-    ? path.join(homeDir, 'custom grok')
-    : path.join(homeDir, '.grok');
+    ? path.join(base.homeDir, 'custom grok')
+    : path.join(base.homeDir, '.grok');
   const configPath = path.join(grokHome, 'hooks', 'elydora-audit.json');
-  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
   await writeOptional(configPath, config);
-  const fixture = {
-    agentDir,
+  return {
+    ...base,
     baseUrl,
     configPath,
     grokHome,
     grokHomeOverride: explicitGrokHome ? grokHome : undefined,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
-    projectDir,
-    rootDir,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
-  return fixture;
 }
 
 export async function readGrokConfig(filePath) {
@@ -184,34 +115,3 @@ export function legacyCommand(scriptPath) {
   const quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
   return `${quote(process.execPath)} ${quote(scriptPath)}`;
 }
-
-export async function startApiServer({ status = 'active', operationStatus = 201 } = {}) {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ headers: request.headers, method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus >= 200 && operationStatus < 300
-      ? JSON.stringify({ operation: { accepted: true } })
-      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/harness.mjs

@@ -0,0 +1,202 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse } from 'jsonc-parser';
+
+export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
+export const cliPath = path.resolve('dist/cli.js');
+
+export function distUrl(relativePath) {
+  return pathToFileURL(path.resolve('dist', relativePath)).href;
+}
+
+export const registryModuleUrl = distUrl('plugins/registry.js');
+export const managedInstallationModuleUrl = distUrl('plugins/managed-installation.js');
+
+export function runProcess(command, args, env, cwd, input = '', { unset = [], shell = false } = {}) {
+  return new Promise((resolve, reject) => {
+    const childEnvironment = { ...process.env, ...env };
+    for (const [name, value] of Object.entries(env)) {
+      if (value === undefined) delete childEnvironment[name];
+    }
+    for (const name of unset) delete childEnvironment[name];
+    const child = spawn(command, args, {
+      cwd,
+      env: childEnvironment,
+      shell,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('close', (code) => resolve({ code, stdout, stderr }));
+    child.stdin.end(input);
+  });
+}
+
+export function runNode(args, env, cwd, input = '', options = {}) {
+  return runProcess(process.execPath, args, env, cwd, input, options);
+}
+
+export function runShell(command, env, cwd, input = '') {
+  return runProcess(command, [], env, cwd, input, { shell: true });
+}
+
+export function windowsPowerShellPath() {
+  return path.win32.join(
+    process.env.SystemRoot || 'C:\\Windows',
+    'System32',
+    'WindowsPowerShell',
+    'v1.0',
+    'powershell.exe',
+  );
+}
+
+export function homeEnvironment(fixture) {
+  return { HOME: fixture.homeDir, USERPROFILE: fixture.homeDir };
+}
+
+// Sets NAME when a value is configured, otherwise removes it from the child environment.
+export function optionalEnvironment(name, value) {
+  return value === undefined ? { env: {}, unset: [name] } : { env: { [name]: value }, unset: [] };
+}
+
+export function installConfig(agentName, fixture, overrides = {}) {
+  return {
+    agentName,
+    orgId: 'org-1',
+    agentId: fixture.agentId,
+    privateKey: VALID_PRIVATE_KEY,
+    kid: 'kid-1',
+    token: 'token-1',
+    baseUrl: fixture.baseUrl,
+    guardScriptPath: fixture.guardScriptPath,
+    hookScriptPath: fixture.hookScriptPath,
+    ...overrides,
+  };
+}
+
+export function runPlugin(
+  plugin,
+  fixture,
+  method,
+  argument,
+  { env = {}, unset = [], cwd = fixture.projectDir } = {},
+) {
+  const source = `
+    import { ${plugin.exportName} } from ${JSON.stringify(plugin.moduleUrl)};
+    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
+    const result = await ${plugin.exportName}[process.env.ELYDORA_TEST_METHOD](argument);
+    if (result !== undefined) console.log(JSON.stringify(result));
+  `;
+  return runNode(
+    ['--input-type=module', '--eval', source],
+    {
+      ...homeEnvironment(fixture),
+      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
+      ELYDORA_TEST_METHOD: method,
+      ...env,
+    },
+    cwd,
+    '',
+    { unset },
+  );
+}
+
+export async function createFixtureRoot(
+  prefix,
+  homeName,
+  { agentId = 'agent-1', projectName = 'project with spaces', createHome = false } = {},
+) {
+  const rootDir = await mkdtemp(path.join(os.tmpdir(), prefix));
+  const homeDir = path.join(rootDir, homeName);
+  const projectDir = path.join(rootDir, projectName);
+  const agentDir = path.join(homeDir, '.elydora', agentId);
+  if (createHome) await mkdir(homeDir, { recursive: true });
+  await mkdir(projectDir, { recursive: true });
+  return {
+    agentDir,
+    agentId,
+    guardScriptPath: path.join(agentDir, 'guard.js'),
+    homeDir,
+    hookScriptPath: path.join(agentDir, 'hook.js'),
+    projectDir,
+    rootDir,
+    async close() {
+      await rm(rootDir, { recursive: true, force: true });
+    },
+  };
+}
+
+export async function writeJson(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const contents = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
+  await writeFile(filePath, contents, { encoding: 'utf-8', mode: 0o600 });
+}
+
+export async function writeOptionalJson(filePath, value) {
+  if (value !== undefined) await writeJson(filePath, value);
+}
+
+export async function readJson(filePath) {
+  return JSON.parse(await readFile(filePath, 'utf-8'));
+}
+
+export async function readSettings(filePath) {
+  const raw = await readFile(filePath, 'utf-8');
+  return { raw, settings: JSON.parse(raw) };
+}
+
+export function parseJsonc(raw) {
+  const errors = [];
+  const value = parse(raw, errors, { allowTrailingComma: false, disallowComments: false });
+  assert.deepEqual(errors, []);
+  return value;
+}
+
+export async function readJsoncSettings(filePath) {
+  const raw = await readFile(filePath, 'utf-8');
+  return { raw, settings: parseJsonc(raw) };
+}
+
+export async function startApiServer({ status: initialStatus = 'active', operationStatus: initialOperationStatus = 201 } = {}) {
+  const requests = [];
+  let status = initialStatus;
+  let operationStatus = initialOperationStatus;
+  const server = http.createServer(async (request, response) => {
+    const chunks = [];
+    for await (const chunk of request) chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf-8');
+    requests.push({ headers: request.headers, method: request.method, url: request.url, raw });
+    if (request.method === 'GET') {
+      response.writeHead(200, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ agent: { status } }));
+      return;
+    }
+    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
+    response.end(operationStatus >= 200 && operationStatus < 300
+      ? JSON.stringify({ operation: { accepted: true } })
+      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const address = server.address();
+  return {
+    baseUrl: `http://127.0.0.1:${address.port}`,
+    requests,
+    setStatus(value) { status = value; },
+    setOperationStatus(value) { operationStatus = value; },
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => error ? reject(error) : resolve());
+    }),
+  };
+}

test-support/kimi-test-helpers.mjs

@@ -1,104 +1,48 @@
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { parse as parseToml } from '@decimalturn/toml-patch';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  optionalEnvironment,
+  runNode as baseNode,
+  runPlugin as basePlugin,
+  runShell,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/kimi.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const contractModuleUrl = pathToFileURL(path.resolve('dist/plugins/kimi-contract.js')).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/kimi-io.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/kimi-installation.js'),
-).href;
-export const cliPath = path.resolve('dist/cli.js');
+export { VALID_PRIVATE_KEY, cliPath, registryModuleUrl, startApiServer } from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/kimi.js');
+export const contractModuleUrl = distUrl('plugins/kimi-contract.js');
+export const ioModuleUrl = distUrl('plugins/kimi-io.js');
+export const installationModuleUrl = distUrl('plugins/kimi-installation.js');
+const PLUGIN = { exportName: 'kimiPlugin', moduleUrl: pluginModuleUrl };
 
 export function runNode(args, env, cwd, input = '', unset = []) {
-  return new Promise((resolve, reject) => {
-    const childEnv = { ...process.env, ...env };
-    for (const key of unset) delete childEnv[key];
-    const child = spawn(process.execPath, args, {
-      cwd,
-      env: childEnv,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
+  return baseNode(args, env, cwd, input, { unset });
 }
 
 export function runKimiHook(command, input, fixture, environment = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, {
-      shell: true,
-      cwd: fixture.projectDir,
-      env: {
-        ...process.env,
-        HOME: fixture.homeDir,
-        USERPROFILE: fixture.homeDir,
-        KIMI_CODE_HOME: fixture.kimiHomeOverride ?? '',
-        ...environment,
-      },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
+  return runShell(command, {
+    ...homeEnvironment(fixture),
+    KIMI_CODE_HOME: fixture.kimiHomeOverride ?? '',
+    ...environment,
+  }, fixture.projectDir, input);
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'kimi',
-    orgId: 'org-1',
-    agentId: 'agent-1',
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('kimi', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument, environment = {}) {
-  const source = `
-    import { kimiPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await kimiPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  const env = {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
-    ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-    ELYDORA_TEST_METHOD: method,
-    ...environment,
-  };
-  const unset = [];
-  if (fixture.kimiHomeOverride === undefined) unset.push('KIMI_CODE_HOME');
-  else env.KIMI_CODE_HOME = fixture.kimiHomeOverride;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    env,
-    fixture.projectDir,
-    '',
-    unset,
-  );
+export function runPlugin(fixture, method, argument, environment = {}) {
+  const home = optionalEnvironment('KIMI_CODE_HOME', fixture.kimiHomeOverride);
+  return basePlugin(PLUGIN, fixture, method, argument, {
+    env: { ...environment, ...home.env },
+    unset: home.unset,
+  });
 }
 
 async function writeOptional(filePath, contents) {
@@ -115,50 +59,37 @@ export async function createFixture({
   legacyDetected = true,
   explicitKimiHome = true,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-kimi-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %ELYDORA_HOOK_PATH%");
-  const projectDir = path.join(rootDir, 'project with spaces');
+  const base = await createFixtureRoot(
+    'elydora-kimi-',
+    "home with spaces and 'quote %ELYDORA_HOOK_PATH%",
+  );
   const kimiHome = explicitKimiHome
-    ? path.join(homeDir, 'custom kimi-code')
-    : path.join(homeDir, '.kimi-code');
+    ? path.join(base.homeDir, 'custom kimi-code')
+    : path.join(base.homeDir, '.kimi-code');
   const stablePath = path.join(kimiHome, 'config.toml');
-  const legacyHome = path.join(homeDir, '.kimi');
+  const legacyHome = path.join(base.homeDir, '.kimi');
   const legacyPath = path.join(legacyHome, 'config.toml');
-  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
   if (stableDetected && !explicitKimiHome) await mkdir(kimiHome, { recursive: true });
   if (legacyDetected) await mkdir(legacyHome, { recursive: true });
   await writeOptional(stablePath, stableConfig);
   await writeOptional(legacyPath, legacyConfig);
-  const fixture = {
-    agentDir,
+  return {
+    ...base,
     baseUrl,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
     kimiHome,
     kimiHomeOverride: explicitKimiHome ? kimiHome : undefined,
     legacyHome,
     legacyPath,
-    projectDir,
-    rootDir,
     stablePath,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
-  return fixture;
 }
 
-export function readKimiConfig(filePath) {
-  return import('node:fs/promises')
-    .then(({ readFile }) => readFile(filePath, 'utf-8'))
-    .then((raw) => ({ raw, config: parseToml(raw) }));
+export async function readKimiConfig(filePath) {
+  const raw = await readFile(filePath, 'utf-8');
+  return { raw, config: parseToml(raw) };
 }
 
 export function managedHook(config, event) {
@@ -182,39 +113,3 @@ export function legacyCommand(scriptPath) {
   const quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
   return `${quote(process.execPath)} ${quote(scriptPath)}`;
 }
-
-export async function startApiServer({ status = 'active', operationStatus = 201 } = {}) {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({
-      headers: request.headers,
-      method: request.method,
-      url: request.url,
-      raw,
-    });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus >= 200 && operationStatus < 300
-      ? JSON.stringify({ operation: { accepted: true } })
-      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/kirocli-test-helpers.mjs

@@ -1,98 +1,41 @@
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+  runProcess as baseProcess,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32, 17).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/kirocli.js')).href;
-export const contractModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/kirocli-contract.js'),
-).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/kirocli-installation.js'),
-).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/kirocli-io.js')).href;
-export const kiroV1ModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/kiroide-contract.js'),
-).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  homeEnvironment as environment,
+  readJson,
+  registryModuleUrl,
+  runNode,
+  runShell,
+  startApiServer,
+} from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/kirocli.js');
+export const contractModuleUrl = distUrl('plugins/kirocli-contract.js');
+export const installationModuleUrl = distUrl('plugins/kirocli-installation.js');
+export const ioModuleUrl = distUrl('plugins/kirocli-io.js');
+export const kiroV1ModuleUrl = distUrl('plugins/kiroide-contract.js');
+const PLUGIN = { exportName: 'kirocliPlugin', moduleUrl: pluginModuleUrl };
 
 export function runProcess(command, args, env, cwd, input = '', shell = false) {
-  return new Promise((resolve, reject) => {
-    const childEnvironment = { ...process.env, ...env };
-    for (const [name, value] of Object.entries(env)) {
-      if (value === undefined) delete childEnvironment[name];
-    }
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnvironment,
-      shell,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export function runNode(args, env, cwd, input = '') {
-  return runProcess(process.execPath, args, env, cwd, input);
-}
-
-export function runShell(command, env, cwd, input = '') {
-  return runProcess(command, [], env, cwd, input, true);
-}
-
-export function environment(fixture) {
-  return { HOME: fixture.homeDir, USERPROFILE: fixture.homeDir };
+  return baseProcess(command, args, env, cwd, input, { shell });
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'kirocli',
-    orgId: 'org-1',
-    agentId: fixture.agentId,
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('kirocli', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument) {
-  const source = `
-    import { kirocliPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await kirocliPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      ...environment(fixture),
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.projectDir,
-  );
-}
-
-async function writeOptional(filePath, value) {
-  if (value === undefined) return;
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const source = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, source, { mode: 0o600 });
+export function runPlugin(fixture, method, argument) {
+  return basePlugin(PLUGIN, fixture, method, argument);
 }
 
 export function managedV2Document(overrides = {}) {
@@ -112,71 +55,26 @@ export async function createFixture({
   existingV2,
   existingV3,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-kirocli-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %KIRO%");
-  const projectDir = path.join(rootDir, 'workspace with spaces');
-  const v2Path = path.join(homeDir, '.kiro', 'agents', 'elydora-audit.json');
-  const v3Path = path.join(homeDir, '.kiro', 'hooks', 'elydora-audit.json');
-  const agentDir = path.join(homeDir, '.elydora', agentId);
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(homeDir, { recursive: true });
-  await mkdir(projectDir, { recursive: true });
-  await writeOptional(v2Path, existingV2);
-  await writeOptional(v3Path, existingV3);
+  const base = await createFixtureRoot(
+    'elydora-kirocli-',
+    "home with spaces and 'quote %KIRO%",
+    { agentId, projectName: 'workspace with spaces', createHome: true },
+  );
+  const v2Path = path.join(base.homeDir, '.kiro', 'agents', 'elydora-audit.json');
+  const v3Path = path.join(base.homeDir, '.kiro', 'hooks', 'elydora-audit.json');
+  await writeOptionalJson(v2Path, existingV2);
+  await writeOptionalJson(v3Path, existingV3);
   return {
-    agentDir,
-    agentId,
+    ...base,
     baseUrl,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
-    projectDir,
-    rootDir,
     v2Path,
     v3Path,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
 }
 
-export async function readJson(filePath) {
-  return JSON.parse(await readFile(filePath, 'utf-8'));
-}
-
 export function findV3Hook(document, name) {
   return document.hooks.find((hook) => hook.name === name);
 }
-
-export async function startApiServer() {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end('{"agent":{"status":"active"}}');
-      return;
-    }
-    response.writeHead(201, { 'Content-Type': 'application/json' });
-    response.end('{"operation":{"accepted":true}}');
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/kiroide-test-helpers.mjs

@@ -1,95 +1,40 @@
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+  runProcess as baseProcess,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32, 11).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/kiroide.js')).href;
-export const contractModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/kiroide-contract.js'),
-).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/kiroide-installation.js'),
-).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/kiroide-io.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  homeEnvironment as environment,
+  readJson,
+  registryModuleUrl,
+  runNode,
+  runShell,
+  startApiServer,
+} from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/kiroide.js');
+export const contractModuleUrl = distUrl('plugins/kiroide-contract.js');
+export const installationModuleUrl = distUrl('plugins/kiroide-installation.js');
+export const ioModuleUrl = distUrl('plugins/kiroide-io.js');
+const PLUGIN = { exportName: 'kiroidePlugin', moduleUrl: pluginModuleUrl };
 
 export function runProcess(command, args, env, cwd, input = '', shell = false) {
-  return new Promise((resolve, reject) => {
-    const childEnvironment = { ...process.env, ...env };
-    for (const [name, value] of Object.entries(env)) {
-      if (value === undefined) delete childEnvironment[name];
-    }
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnvironment,
-      shell,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export function runNode(args, env, cwd, input = '') {
-  return runProcess(process.execPath, args, env, cwd, input);
-}
-
-export function runShell(command, env, cwd, input = '') {
-  return runProcess(command, [], env, cwd, input, true);
-}
-
-export function environment(fixture) {
-  return { HOME: fixture.homeDir, USERPROFILE: fixture.homeDir };
+  return baseProcess(command, args, env, cwd, input, { shell });
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'kiroide',
-    orgId: 'org-1',
-    agentId: fixture.agentId,
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('kiroide', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument) {
-  const source = `
-    import { kiroidePlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await kiroidePlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      ...environment(fixture),
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.projectDir,
-  );
-}
-
-async function writeOptional(filePath, value) {
-  if (value === undefined) return;
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const source = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, source, { mode: 0o600 });
+export function runPlugin(fixture, method, argument) {
+  return basePlugin(PLUGIN, fixture, method, argument);
 }
 
 export async function createFixture({
@@ -98,73 +43,28 @@ export async function createFixture({
   existingConfig,
   existingLegacy,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-kiroide-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %KIRO%");
-  const projectDir = path.join(rootDir, 'workspace with spaces');
-  const hooksDir = path.join(projectDir, '.kiro', 'hooks');
+  const base = await createFixtureRoot(
+    'elydora-kiroide-',
+    "home with spaces and 'quote %KIRO%",
+    { agentId, projectName: 'workspace with spaces' },
+  );
+  const hooksDir = path.join(base.projectDir, '.kiro', 'hooks');
   const configPath = path.join(hooksDir, 'elydora-audit.json');
-  const legacyConfigPath = path.join(homeDir, '.kiro', 'hooks', 'elydora-audit.kiro.hook');
-  const agentDir = path.join(homeDir, '.elydora', agentId);
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(projectDir, { recursive: true });
-  await writeOptional(configPath, existingConfig);
-  await writeOptional(legacyConfigPath, existingLegacy);
-  const fixture = {
-    agentDir,
-    agentId,
+  const legacyConfigPath = path.join(base.homeDir, '.kiro', 'hooks', 'elydora-audit.kiro.hook');
+  await writeOptionalJson(configPath, existingConfig);
+  await writeOptionalJson(legacyConfigPath, existingLegacy);
+  return {
+    ...base,
     baseUrl,
     configPath,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
     hooksDir,
     legacyConfigPath,
-    projectDir,
-    rootDir,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
-  return fixture;
-}
-
-export async function readJson(filePath) {
-  return JSON.parse(await readFile(filePath, 'utf-8'));
 }
 
 export function findHook(document, name) {
   return document.hooks.find((hook) => hook.name === name);
 }
-
-export async function startApiServer() {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end('{"agent":{"status":"active"}}');
-      return;
-    }
-    response.writeHead(201, { 'Content-Type': 'application/json' });
-    response.end('{"operation":{"accepted":true}}');
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test-support/letta.mjs

@@ -1,92 +1,38 @@
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+  runProcess,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32, 23).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/letta.js')).href;
-export const configModuleUrl = pathToFileURL(path.resolve('dist/plugins/letta-config.js')).href;
-export const contractModuleUrl = pathToFileURL(path.resolve('dist/plugins/letta-contract.js')).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/letta-installation.js'),
-).href;
-export const sourcesModuleUrl = pathToFileURL(path.resolve('dist/plugins/letta-sources.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  homeEnvironment as environment,
+  readJson as readSettings,
+  registryModuleUrl,
+  runNode,
+  runProcess,
+  startApiServer,
+} from './harness.mjs';
 
-export function runProcess(command, args, env, cwd, input = '') {
-  return new Promise((resolve, reject) => {
-    const childEnvironment = { ...process.env, ...env };
-    for (const [name, value] of Object.entries(env)) {
-      if (value === undefined) delete childEnvironment[name];
-    }
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnvironment,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export function runNode(args, env, cwd, input = '') {
-  return runProcess(process.execPath, args, env, cwd, input);
-}
-
-export function environment(fixture) {
-  return {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
-  };
-}
+export const pluginModuleUrl = distUrl('plugins/letta.js');
+export const configModuleUrl = distUrl('plugins/letta-config.js');
+export const contractModuleUrl = distUrl('plugins/letta-contract.js');
+export const installationModuleUrl = distUrl('plugins/letta-installation.js');
+export const sourcesModuleUrl = distUrl('plugins/letta-sources.js');
+const PLUGIN = { exportName: 'lettaPlugin', moduleUrl: pluginModuleUrl };
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'letta',
-    orgId: 'org-1',
-    agentId: fixture.agentId,
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('letta', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument) {
-  const source = `
-    import { lettaPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await lettaPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      ...environment(fixture),
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.projectDir,
-  );
-}
-
-async function writeOptional(filePath, value) {
-  if (value === undefined) return;
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const source = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, source, { mode: 0o600 });
+export function runPlugin(fixture, method, argument) {
+  return basePlugin(PLUGIN, fixture, method, argument);
 }
 
 export async function createFixture({
@@ -96,45 +42,29 @@ export async function createFixture({
   projectSettings,
   localSettings,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-letta-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %HOME%");
-  const projectDir = path.join(rootDir, 'workspace with spaces');
-  const globalPath = path.join(homeDir, '.letta', 'settings.json');
-  const projectPath = path.join(projectDir, '.letta', 'settings.json');
-  const localPath = path.join(projectDir, '.letta', 'settings.local.json');
-  const agentDir = path.join(homeDir, '.elydora', agentId);
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(homeDir, { recursive: true });
-  await mkdir(projectDir, { recursive: true });
-  await writeOptional(globalPath, globalSettings);
-  await writeOptional(projectPath, projectSettings);
-  await writeOptional(localPath, localSettings);
+  const base = await createFixtureRoot(
+    'elydora-letta-',
+    "home with spaces and 'quote %HOME%",
+    { agentId, projectName: 'workspace with spaces', createHome: true },
+  );
+  const globalPath = path.join(base.homeDir, '.letta', 'settings.json');
+  const projectPath = path.join(base.projectDir, '.letta', 'settings.json');
+  const localPath = path.join(base.projectDir, '.letta', 'settings.local.json');
+  await writeOptionalJson(globalPath, globalSettings);
+  await writeOptionalJson(projectPath, projectSettings);
+  await writeOptionalJson(localPath, localSettings);
   return {
-    agentDir,
-    agentId,
+    ...base,
     baseUrl,
     globalPath,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
     localPath,
-    projectDir,
     projectPath,
-    rootDir,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
 }
 
-export async function readSettings(filePath) {
-  return JSON.parse(await readFile(filePath, 'utf-8'));
-}
-
 export function managedHandler(settings, event) {
   return settings.hooks[event].find((group) => (
     group.matcher === '*'
@@ -148,40 +78,5 @@ export function runLettaHook(handler, input, fixture) {
   const args = process.platform === 'win32'
     ? ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', handler.command]
     : ['-c', handler.command];
-  return runProcess(shell, args, environment(fixture), fixture.projectDir, input);
-}
-
-export async function startApiServer(initialStatus = 'active') {
-  const requests = [];
-  let status = initialStatus;
-  let operationStatus = 201;
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus < 400
-      ? '{"operation":{"accepted":true}}'
-      : '{"error":{"code":"AUDIT_UNAVAILABLE"}}');
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    setStatus(value) { status = value; },
-    setOperationStatus(value) { operationStatus = value; },
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
+  return runProcess(shell, args, homeEnvironment(fixture), fixture.projectDir, input);
 }

test-support/opencode-test-helpers.mjs

@@ -1,87 +1,40 @@
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
+import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32, 19).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/opencode.js')).href;
-export const contractModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/opencode-contract.js'),
-).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/opencode-installation.js'),
-).href;
-export const ioModuleUrl = pathToFileURL(path.resolve('dist/plugins/opencode-io.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  readJson,
+  registryModuleUrl,
+  runNode,
+  runProcess,
+  startApiServer,
+} from './harness.mjs';
 
-export function runProcess(command, args, env, cwd, input = '') {
-  return new Promise((resolve, reject) => {
-    const childEnvironment = { ...process.env, ...env };
-    for (const [name, value] of Object.entries(env)) {
-      if (value === undefined) delete childEnvironment[name];
-    }
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnvironment,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
-}
-
-export function runNode(args, env, cwd, input = '') {
-  return runProcess(process.execPath, args, env, cwd, input);
-}
+export const pluginModuleUrl = distUrl('plugins/opencode.js');
+export const contractModuleUrl = distUrl('plugins/opencode-contract.js');
+export const installationModuleUrl = distUrl('plugins/opencode-installation.js');
+export const ioModuleUrl = distUrl('plugins/opencode-io.js');
+const PLUGIN = { exportName: 'opencodePlugin', moduleUrl: pluginModuleUrl };
 
 export function environment(fixture) {
-  return {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
-    XDG_CONFIG_HOME: fixture.configRoot,
-  };
+  return { ...homeEnvironment(fixture), XDG_CONFIG_HOME: fixture.configRoot };
 }
 
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'opencode',
-    orgId: 'org-1',
-    agentId: fixture.agentId,
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('opencode', fixture, overrides);
 }
 
-export async function runPlugin(fixture, method, argument) {
-  const source = `
-    import { opencodePlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await opencodePlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    {
-      ...environment(fixture),
-      ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-      ELYDORA_TEST_METHOD: method,
-    },
-    fixture.projectDir,
-  );
+export function runPlugin(fixture, method, argument) {
+  return basePlugin(PLUGIN, fixture, method, argument, { env: environment(fixture) });
 }
 
 async function writeOptional(filePath, value) {
@@ -96,33 +49,24 @@ export async function createFixture({
   existingPlugin,
   existingLegacy,
 } = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-opencode-'));
-  const homeDir = path.join(rootDir, "home with spaces and 'quote %OPEN%");
-  const configRoot = path.join(rootDir, 'xdg config');
-  const projectDir = path.join(rootDir, 'workspace with spaces');
+  const base = await createFixtureRoot(
+    'elydora-opencode-',
+    "home with spaces and 'quote %OPEN%",
+    { agentId, projectName: 'workspace with spaces', createHome: true },
+  );
+  const configRoot = path.join(base.rootDir, 'xdg config');
   const pluginsDir = path.join(configRoot, 'opencode', 'plugins');
   const pluginPath = path.join(pluginsDir, 'elydora-audit.js');
   const legacyPluginPath = path.join(pluginsDir, 'elydora-audit.mjs');
-  const agentDir = path.join(homeDir, '.elydora', agentId);
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(homeDir, { recursive: true });
-  await mkdir(projectDir, { recursive: true });
   await writeOptional(pluginPath, existingPlugin);
   await writeOptional(legacyPluginPath, existingLegacy);
   return {
-    agentDir,
-    agentId,
+    ...base,
     baseUrl,
     configRoot,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
     legacyPluginPath,
     pluginPath,
     pluginsDir,
-    projectDir,
-    rootDir,
     install(overrides = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides));
     },
@@ -130,51 +74,5 @@ export async function createFixture({
       const module = await import(`${pathToFileURL(this.pluginPath).href}?test=${Date.now()}`);
       return module.ElydoraAuditPlugin({});
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
-  };
-}
-
-export async function readJson(filePath) {
-  return JSON.parse(await readFile(filePath, 'utf-8'));
-}
-
-export async function startApiServer(initialStatus = 'active') {
-  const requests = [];
-  let status = initialStatus;
-  let operationStatus = 201;
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus < 400
-      ? '{"operation":{"accepted":true}}'
-      : '{"error":{"code":"AUDIT_UNAVAILABLE"}}');
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    setStatus(value) {
-      status = value;
-    },
-    setOperationStatus(value) {
-      operationStatus = value;
-    },
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
   };
 }

test-support/qwen.mjs

@@ -1,28 +1,32 @@
 import assert from 'node:assert/strict';
-import { spawn } from 'node:child_process';
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import http from 'node:http';
-import os from 'node:os';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { parse } from 'jsonc-parser';
+import {
+  createFixtureRoot,
+  distUrl,
+  homeEnvironment,
+  installConfig as baseInstallConfig,
+  runPlugin as basePlugin,
+  runProcess as baseProcess,
+  windowsPowerShellPath,
+  writeOptionalJson,
+} from './harness.mjs';
 
-export const VALID_PRIVATE_KEY = Buffer.alloc(32).toString('base64url');
-export const pluginModuleUrl = pathToFileURL(path.resolve('dist/plugins/qwen.js')).href;
-export const registryModuleUrl = pathToFileURL(path.resolve('dist/plugins/registry.js')).href;
-export const sourcesModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/qwen-sources.js'),
-).href;
-export const installationModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/qwen-installation.js'),
-).href;
-export const configModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/qwen-config.js'),
-).href;
-export const contractModuleUrl = pathToFileURL(
-  path.resolve('dist/plugins/qwen-contract.js'),
-).href;
-export const cliPath = path.resolve('dist/cli.js');
+export {
+  VALID_PRIVATE_KEY,
+  cliPath,
+  parseJsonc as parseSettings,
+  readJsoncSettings as readSettings,
+  registryModuleUrl,
+  startApiServer,
+  writeJson as writeSettings,
+} from './harness.mjs';
+
+export const pluginModuleUrl = distUrl('plugins/qwen.js');
+export const sourcesModuleUrl = distUrl('plugins/qwen-sources.js');
+export const installationModuleUrl = distUrl('plugins/qwen-installation.js');
+export const configModuleUrl = distUrl('plugins/qwen-config.js');
+export const contractModuleUrl = distUrl('plugins/qwen-contract.js');
+const PLUGIN = { exportName: 'qwenPlugin', moduleUrl: pluginModuleUrl };
 
 const QWEN_ENV_KEYS = [
   'QWEN_HOME',
@@ -33,48 +37,18 @@ const QWEN_ENV_KEYS = [
 ];
 
 export function runProcess(command, args, env, cwd, input = '', unset = []) {
-  return new Promise((resolve, reject) => {
-    const childEnv = { ...process.env, ...env };
-    for (const key of unset) delete childEnv[key];
-    const child = spawn(command, args, {
-      cwd,
-      env: childEnv,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.once('error', reject);
-    child.once('close', (code) => resolve({ code, stdout, stderr }));
-    child.stdin.end(input);
-  });
+  return baseProcess(command, args, env, cwd, input, { unset });
 }
 
 export function runNode(args, env, cwd, input = '', unset = []) {
   return runProcess(process.execPath, args, env, cwd, input, unset);
 }
 
-function windowsPowerShell() {
-  return path.win32.join(
-    process.env.SystemRoot || 'C:\\Windows',
-    'System32',
-    'WindowsPowerShell',
-    'v1.0',
-    'powershell.exe',
-  );
-}
-
 export function runQwenHook(handler, input, fixture, environment = {}) {
-  const env = {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
-    ...environment,
-  };
+  const env = { ...homeEnvironment(fixture), ...environment };
   if (process.platform === 'win32') {
     return runProcess(
-      windowsPowerShell(),
+      windowsPowerShellPath(),
       ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', handler.command],
       env,
       fixture.projectDir,
@@ -84,109 +58,36 @@ export function runQwenHook(handler, input, fixture, environment = {}) {
   return runProcess('/bin/bash', ['-c', handler.command], env, fixture.projectDir, input);
 }
 
-export async function writeSettings(filePath, value) {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  const contents = typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`;
-  await writeFile(filePath, contents, { encoding: 'utf-8', mode: 0o600 });
-}
-
-export function parseSettings(raw) {
-  const errors = [];
-  const value = parse(raw, errors, {
-    allowTrailingComma: false,
-    disallowComments: false,
-  });
-  assert.deepEqual(errors, []);
-  return value;
-}
-
-export async function readSettings(filePath) {
-  const raw = await readFile(filePath, 'utf-8');
-  return { raw, settings: parseSettings(raw) };
-}
-
 export function installConfig(fixture, overrides = {}) {
-  return {
-    agentName: 'qwen',
-    orgId: 'org-1',
-    agentId: 'agent-1',
-    privateKey: VALID_PRIVATE_KEY,
-    kid: 'kid-1',
-    token: 'token-1',
-    baseUrl: fixture.baseUrl,
-    guardScriptPath: fixture.guardScriptPath,
-    hookScriptPath: fixture.hookScriptPath,
-    ...overrides,
-  };
+  return baseInstallConfig('qwen', fixture, overrides);
 }
 
-function qwenEnvironment(fixture, environment) {
+export function runPlugin(fixture, method, argument, environment = {}) {
   const env = {
-    HOME: fixture.homeDir,
-    USERPROFILE: fixture.homeDir,
     QWEN_CODE_SYSTEM_DEFAULTS_PATH: path.join(fixture.rootDir, 'system-defaults.json'),
     QWEN_CODE_SYSTEM_SETTINGS_PATH: path.join(fixture.rootDir, 'system-settings.json'),
     ...environment,
   };
   const unset = QWEN_ENV_KEYS.filter((key) => !Object.hasOwn(env, key));
-  return { env, unset };
+  return basePlugin(PLUGIN, fixture, method, argument, { env, unset });
 }
 
-export async function runPlugin(fixture, method, argument, environment = {}) {
-  const source = `
-    import { qwenPlugin } from ${JSON.stringify(pluginModuleUrl)};
-    const argument = JSON.parse(process.env.ELYDORA_TEST_ARGUMENT);
-    const result = await qwenPlugin[process.env.ELYDORA_TEST_METHOD](argument);
-    if (result !== undefined) console.log(JSON.stringify(result));
-  `;
-  const configured = qwenEnvironment(fixture, {
-    ELYDORA_TEST_ARGUMENT: JSON.stringify(argument),
-    ELYDORA_TEST_METHOD: method,
-    ...environment,
-  });
-  return runNode(
-    ['--input-type=module', '--eval', source],
-    configured.env,
-    fixture.projectDir,
-    '',
-    configured.unset,
-  );
-}
-
-export async function createFixture({
-  baseUrl = 'http://127.0.0.1:9',
-  settings,
-} = {}) {
-  const rootDir = await mkdtemp(path.join(os.tmpdir(), 'elydora-qwen-'));
-  const homeDir = path.join(
-    rootDir,
+export async function createFixture({ baseUrl = 'http://127.0.0.1:9', settings } = {}) {
+  const base = await createFixtureRoot(
+    'elydora-qwen-',
     "home with spaces and 'quote $QWEN_PROJECT_DIR %QWEN_PROJECT_DIR%",
+    { createHome: true },
   );
-  const projectDir = path.join(rootDir, 'project with spaces');
-  const settingsPath = path.join(homeDir, '.qwen', 'settings.json');
-  const agentDir = path.join(homeDir, '.elydora', 'agent-1');
-  const guardScriptPath = path.join(agentDir, 'guard.js');
-  const hookScriptPath = path.join(agentDir, 'hook.js');
-  await mkdir(homeDir, { recursive: true });
-  await mkdir(projectDir, { recursive: true });
-  if (settings !== undefined) await writeSettings(settingsPath, settings);
-  const fixture = {
-    agentDir,
+  const settingsPath = path.join(base.homeDir, '.qwen', 'settings.json');
+  await writeOptionalJson(settingsPath, settings);
+  return {
+    ...base,
     baseUrl,
-    guardScriptPath,
-    homeDir,
-    hookScriptPath,
-    projectDir,
-    rootDir,
     settingsPath,
     install(overrides = {}, environment = {}) {
       return runPlugin(this, 'install', installConfig(this, overrides), environment);
     },
-    async close() {
-      await rm(rootDir, { recursive: true, force: true });
-    },
   };
-  return fixture;
 }
 
 export function managedHandler(settings, event, name) {
@@ -243,34 +144,3 @@ export function legacyGroup(scriptPath) {
     }],
   };
 }
-
-export async function startApiServer({ status = 'active', operationStatus = 201 } = {}) {
-  const requests = [];
-  const server = http.createServer(async (request, response) => {
-    const chunks = [];
-    for await (const chunk of request) chunks.push(chunk);
-    const raw = Buffer.concat(chunks).toString('utf-8');
-    requests.push({ headers: request.headers, method: request.method, url: request.url, raw });
-    if (request.method === 'GET') {
-      response.writeHead(200, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ agent: { status } }));
-      return;
-    }
-    response.writeHead(operationStatus, { 'Content-Type': 'application/json' });
-    response.end(operationStatus >= 200 && operationStatus < 300
-      ? JSON.stringify({ operation: { accepted: true } })
-      : JSON.stringify({ error: { code: 'UPSTREAM_FAILURE', message: 'failed' } }));
-  });
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  const address = server.address();
-  return {
-    baseUrl: `http://127.0.0.1:${address.port}`,
-    requests,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => error ? reject(error) : resolve());
-    }),
-  };
-}

test/cli-security.test.mjs

@@ -18,6 +18,7 @@ async function runCli(args, homeDir) {
         ...process.env,
         HOME: homeDir,
         USERPROFILE: homeDir,
+        XDG_CONFIG_HOME: path.join(homeDir, '.config'),
       },
       stdio: ['ignore', 'pipe', 'pipe'],
     });

test/guard-template.test.mjs

@@ -26,6 +26,7 @@ async function createFixture(status) {
   await writeFile(
     path.join(agentDir, 'config.json'),
     JSON.stringify({ agent_id: AGENT_ID, base_url: `http://127.0.0.1:${address.port}` }),
+    { mode: 0o600 },
   );
 
   const scriptPath = path.join(homeDir, 'guard.cjs');
@@ -91,6 +92,7 @@ test('cached frozen status keeps the blocking exit code', async () => {
     await writeFile(
       path.join(fixture.homeDir, '.elydora', AGENT_ID, 'status-cache.json'),
       JSON.stringify({ status: 'frozen', cached_at: Date.now() }),
+      { mode: 0o600 },
     );
 
     const result = await runGuard(fixture.scriptPath, fixture.homeDir);

test/letta-runtime.test.mjs

@@ -60,7 +60,7 @@ async function installedHandlers(fixture) {
 }
 
 test('Letta guard accepts active agents with native exit semantics', async () => {
-  const api = await startApiServer('active');
+  const api = await startApiServer({ status: 'active' });
   const fixture = await createFixture({ baseUrl: api.baseUrl });
   try {
     assert.equal((await fixture.install()).code, 0);
@@ -82,7 +82,7 @@ test('Letta guard accepts active agents with native exit semantics', async () =>
 test('Letta guard propagates frozen and revoked states through exit code 2', async (t) => {
   for (const status of ['frozen', 'revoked']) {
     await t.test(status, async () => {
-      const api = await startApiServer(status);
+      const api = await startApiServer({ status });
       const fixture = await createFixture({ baseUrl: api.baseUrl });
       try {
         assert.equal((await fixture.install()).code, 0);