coding-tool-x 3.8.3 → 3.8.5

package/src/shared/driver-factories/projects.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const { ok, unsupported, failed } = require('../driver-result');
+
+function createProjectsDriver({
+  platform,
+  servicePath,
+  localServicePath,
+  requireImpl,
+  availabilityMethod = null,
+  availabilityCheck = null,
+  createProject,
+  onSuccess,
+  ...context
+} = {}) {
+  let service;
+
+  const loadService = () => {
+    if (service) return service;
+    service = requireImpl ? requireImpl(servicePath) : require(localServicePath);
+    service.configure?.({ ...context, platform, capability: 'projects' });
+    return service;
+  };
+
+  const configFor = options => platform === 'claude'
+    ? options?.config || {}
+    : options || {};
+
+  const invoke = (operation, methodName, args) => {
+    try {
+      const target = loadService();
+      if (typeof target?.[methodName] !== 'function') {
+        return unsupported(platform, 'projects', operation);
+      }
+      const value = target[methodName](...args);
+      const wrap = result => {
+        if (typeof onSuccess === 'function') onSuccess(operation, result);
+        return ok(platform, 'projects', operation, result);
+      };
+      return value && typeof value.then === 'function'
+        ? value.then(wrap).catch(error => failed(platform, 'projects', operation, error))
+        : wrap(value);
+    } catch (error) {
+      return failed(platform, 'projects', operation, error);
+    }
+  };
+
+  const invokeCustom = (operation, callback, args) => {
+    try {
+      const value = callback(...args);
+      const wrap = result => {
+        if (typeof onSuccess === 'function') onSuccess(operation, result);
+        return ok(platform, 'projects', operation, result);
+      };
+      return value && typeof value.then === 'function'
+        ? value.then(wrap).catch(error => failed(platform, 'projects', operation, error))
+        : wrap(value);
+    } catch (error) {
+      return failed(platform, 'projects', operation, error);
+    }
+  };
+
+  const driver = {
+    platform,
+    capability: 'projects',
+    ...context,
+    listProjects(options = {}) {
+      const normalizedOptions = options || {};
+      if (platform === 'claude') {
+        const target = loadService();
+        if (typeof target?.getProjectsWithStats === 'function') {
+          return invoke('listProjects', 'getProjectsWithStats', [configFor(normalizedOptions), normalizedOptions]);
+        }
+      }
+      return invoke('listProjects', 'getProjects', [configFor(normalizedOptions)]);
+    },
+    getProjectOrder(options = {}) {
+      return invoke('getProjectOrder', 'getProjectOrder', [configFor(options)]);
+    },
+    getProjectAndSessionCounts(options = {}) {
+      const args = platform === 'claude' ? [configFor(options), options] : [options];
+      return invoke('getProjectAndSessionCounts', 'getProjectAndSessionCounts', args);
+    },
+    counts(options = {}) {
+      return this.getProjectAndSessionCounts(options);
+    },
+    saveProjectOrder(order, options = {}) {
+      const args = platform === 'claude' ? [configFor(options), order] : [order];
+      return invoke('saveProjectOrder', 'saveProjectOrder', args);
+    },
+    deleteProject(projectId, options = {}) {
+      const args = platform === 'claude' ? [configFor(options), projectId] : [projectId];
+      return invoke('deleteProject', 'deleteProject', args);
+    }
+  };
+  if (availabilityMethod) {
+    driver.isAvailable = (options = {}) => invoke(
+      'isAvailable',
+      availabilityMethod,
+      platform === 'claude' ? [configFor(options)] : [options]
+    );
+  } else if (typeof availabilityCheck === 'function') {
+    driver.isAvailable = (options = {}) => invokeCustom(
+      'isAvailable',
+      availabilityCheck,
+      [options]
+    );
+  }
+
+  if (typeof createProject === 'function') {
+    driver.createProject = (input = {}, options = {}) => invokeCustom(
+      'createProject',
+      createProject,
+      [input, options]
+    );
+  }
+
+  return driver;
+}
+
+module.exports = { createProjectsDriver };

package/src/shared/driver-factories/prompts.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { ok, failed } = require('../driver-result');
+
+function createPromptDriver({ platform, ...context } = {}) {
+  const { NATIVE_PATHS } = require('../../config/paths');
+  const { resolvePreferredHomeDir } = require('../../utils/home-dir');
+  const pathContext = context.pathContext || {};
+  const home = pathContext.home || resolvePreferredHomeDir(process.platform, process.env, os.homedir());
+  const configuredNative = pathContext.native || {};
+  const native = configuredNative[platform]
+    ? configuredNative[platform]
+    : configuredNative;
+  const legacyNative = NATIVE_PATHS || {};
+  const claudeDir = native.dir || legacyNative.claude?.dir || path.dirname(legacyNative.claude?.settings || '') || path.join(home, '.claude');
+  const paths = {
+    claude: native.prompt || legacyNative.claude?.prompt || path.join(claudeDir, 'CLAUDE.md'),
+    codex: native.prompt || legacyNative.codex?.prompt || path.join(native.dir || legacyNative.codex?.dir || path.join(home, '.codex'), 'AGENTS.md'),
+    gemini: native.prompt || legacyNative.gemini?.prompt || path.join(native.dir || legacyNative.gemini?.dir || path.join(home, '.gemini'), 'GEMINI.md'),
+    opencode: native.prompt || legacyNative.opencode?.prompt || path.join(native.config || legacyNative.opencode?.config || path.join(home, '.config', 'opencode'), 'AGENTS.md'),
+    omp: native.prompt || legacyNative.omp?.prompt || path.join(native.dir || legacyNative.omp?.dir || path.join(home, '.omp', 'agent'), 'AGENTS.md')
+  };
+  const promptPath = paths[platform] || native.prompt;
+  if (!promptPath) throw new Error(`Prompt path is not configured for ${platform}`);
+  const read = () => fs.existsSync(promptPath) ? fs.readFileSync(promptPath, 'utf8') : '';
+  const write = content => {
+    if (typeof content !== 'string') throw new Error('提示词内容必须是字符串');
+    fs.mkdirSync(path.dirname(promptPath), { recursive: true });
+    fs.writeFileSync(promptPath, content, 'utf8');
+    return content;
+  };
+  const remove = () => {
+    if (!fs.existsSync(promptPath)) return true;
+    fs.unlinkSync(promptPath);
+    return true;
+  };
+  const invoke = (operation, args) => {
+    try {
+      const value = { read, write, remove }[operation](...args);
+      return ok(platform, 'prompts', operation, value);
+    } catch (error) {
+      return failed(platform, 'prompts', operation, error);
+    }
+  };
+  return {
+    platform,
+    capability: 'prompts',
+    path: promptPath,
+    read: (...args) => invoke('read', args),
+    write: (...args) => invoke('write', args),
+    remove: (...args) => invoke('remove', args)
+  };
+}
+
+module.exports = { createPromptDriver };

package/src/shared/driver-factories/resource-sync.js

@@ -0,0 +1,375 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const toml = require('@iarna/toml');
+const tomlStringify = require('@iarna/toml').stringify;
+const { ok, failed } = require('../driver-result');
+const { assertNoSymlinkComponents } = require('../project-config');
+
+const CONFIG_TYPES = {
+  skills: {
+    isDirectory: true,
+    markerFile: 'SKILL.md',
+    claudeTarget: 'skills',
+    codexTarget: 'skills',
+    codexSupported: true,
+    geminiTarget: 'skills',
+    geminiSupported: true,
+    opencodeTarget: 'skills',
+    opencodeLegacyTarget: 'skill',
+    opencodeSupported: true,
+    ompTarget: 'skills',
+    ompSupported: true
+  },
+  commands: {
+    isDirectory: false,
+    extension: '.md',
+    claudeTarget: 'commands',
+    codexTarget: 'prompts',
+    codexSupported: true,
+    geminiTarget: 'commands',
+    geminiExtension: '.toml',
+    geminiSupported: true,
+    opencodeTarget: 'commands',
+    opencodeLegacyTarget: 'command',
+    opencodeSupported: true,
+    ompTarget: 'commands',
+    ompSupported: true
+  },
+  agents: {
+    isDirectory: false,
+    extension: '.md',
+    claudeTarget: 'agents',
+    codexSupported: true,
+    geminiTarget: 'agents',
+    geminiSupported: true,
+    opencodeTarget: 'agents',
+    opencodeLegacyTarget: 'agent',
+    opencodeSupported: true,
+    ompSupported: false
+  },
+  plugins: {
+    isDirectory: true,
+    claudeTarget: 'plugins',
+    codexSupported: false,
+    geminiSupported: false,
+    opencodeTarget: 'plugins',
+    opencodeLegacyTarget: 'plugin',
+    opencodeSupported: true,
+    ompTarget: 'extensions',
+    ompSupported: true
+  }
+};
+
+function normalizeSafeRelativeName(name) {
+  const raw = String(name || '').replace(/\\/g, '/').trim();
+  if (!raw || raw.includes('\0') || path.isAbsolute(raw) || raw.startsWith('/')) return null;
+  const normalized = path.posix.normalize(raw).replace(/^(\.\/)+/, '');
+  return normalized && normalized !== '.' && normalized !== '..' && !normalized.startsWith('../') ? normalized : null;
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyDirRecursive(src, dest) {
+  ensureDir(dest);
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const source = path.join(src, entry.name);
+    const target = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(source, target);
+    else fs.copyFileSync(source, target);
+  }
+}
+
+function copyDirWithConversion(src, dest, transform) {
+  ensureDir(dest);
+  const textExtensions = new Set(['.md', '.txt', '.json', '.js', '.ts', '.py', '.sh', '.yaml', '.yml']);
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const source = path.join(src, entry.name);
+    const target = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirWithConversion(source, target, transform);
+      continue;
+    }
+    if (!textExtensions.has(path.extname(entry.name).toLowerCase())) {
+      fs.copyFileSync(source, target);
+      continue;
+    }
+    fs.writeFileSync(target, transform(source, fs.readFileSync(source, 'utf8')), 'utf8');
+  }
+}
+
+function removeRecursive(target) {
+  if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+}
+
+function cleanupEmptyParents(dir, baseDir) {
+  const normalizedDir = path.resolve(dir);
+  const normalizedBase = path.resolve(baseDir);
+  if (!normalizedDir.startsWith(`${normalizedBase}${path.sep}`)) return;
+  try {
+    if (fs.readdirSync(dir).length === 0) {
+      fs.rmdirSync(dir);
+      cleanupEmptyParents(path.dirname(dir), baseDir);
+    }
+  } catch (_) {
+    // The target may have disappeared concurrently.
+  }
+}
+
+function parseFrontmatter(content) {
+  const result = { frontmatter: {}, body: content };
+  const normalized = content.trim().replace(/^\uFEFF/, '');
+  const match = normalized.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  if (!match) return result;
+  result.body = match[2].trim();
+  for (const line of match[1].split('\n')) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+    const key = line.slice(0, colonIndex).trim();
+    let value = line.slice(colonIndex + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    result.frontmatter[key] = value;
+  }
+  return result;
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function createResourceSyncDriver({ platform, configTypes = CONFIG_TYPES, resourcePaths = {}, ...context } = {}) {
+  const { PATHS, NATIVE_PATHS, HOME_DIR } = require('../../config/paths');
+  const pathContext = context.pathContext || {};
+  const home = pathContext.home || HOME_DIR || os.homedir();
+  const configuredNative = pathContext.native || {};
+  const native = configuredNative[platform]
+    ? configuredNative
+    : { ...(NATIVE_PATHS || {}), [platform]: configuredNative };
+  const claudeNative = native.claude || {};
+  const codexNative = native.codex || {};
+  const geminiNative = native.gemini || {};
+  const opencodeNative = native.opencode || {};
+  const ompNative = native.omp || {};
+  const claudeDir = claudeNative.dir || path.dirname(claudeNative.settings || '') || path.join(home, '.claude');
+  const codexDir = codexNative.dir || path.dirname(codexNative.config || '') || path.join(home, '.codex');
+  const geminiDir = geminiNative.dir || path.dirname(geminiNative.settings || '') || path.join(home, '.gemini');
+  const opencodeDir = opencodeNative.config || path.join(home, '.config', 'opencode');
+  const ompDir = ompNative.dir || path.join(home, '.omp', 'agent');
+  const codexConfigPath = codexNative.config || path.join(codexDir, 'config.toml');
+  const config = {
+    home,
+    configs: PATHS.configs,
+    skillArtifacts: PATHS.skillArtifacts,
+    claudeDir,
+    codexDir,
+    geminiDir,
+    opencodeDir,
+    ompDir,
+    codexConfigPath,
+    ...resourcePaths
+  };
+
+  const getType = type => configTypes[type];
+  const isSupported = typeConfig => typeConfig && typeConfig[`${platform}Supported`] !== false;
+  const resolveSourcePath = (type, safeName, sourcePathOverride) => {
+    const sourcePath = sourcePathOverride ? path.resolve(sourcePathOverride) : path.join(config.configs, type, safeName);
+    const allowedRoots = [path.join(config.configs, type), config.skillArtifacts]
+      .filter(Boolean)
+      .map(root => path.resolve(root));
+    const allowedRoot = allowedRoots.find(root => sourcePath === root || sourcePath.startsWith(`${root}${path.sep}`));
+    if (!allowedRoot) throw new Error('Controlled source path escapes allowed storage');
+    assertNoSymlinkComponents(allowedRoot, sourcePath, fs);
+    if (sourcePathOverride && !fs.existsSync(sourcePath)) throw new Error('Controlled source path not found');
+    return sourcePath;
+  };
+  const readCodexConfig = () => fs.existsSync(config.codexConfigPath) ? toml.parse(fs.readFileSync(config.codexConfigPath, 'utf8')) : {};
+  const writeCodexConfig = value => {
+    ensureDir(path.dirname(config.codexConfigPath));
+    const tempPath = `${config.codexConfigPath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tempPath, tomlStringify(value), 'utf8');
+    fs.renameSync(tempPath, config.codexConfigPath);
+  };
+  const resolveCodexPath = value => {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    if (!normalized) return '';
+    if (normalized.startsWith('~/')) return path.join(config.home, normalized.slice(2));
+    return path.isAbsolute(normalized) ? normalized : path.resolve(path.dirname(config.codexConfigPath), normalized);
+  };
+  const managedCodexDir = () => path.join(config.codexDir, 'agents');
+  const managedCodexPath = name => path.join(managedCodexDir(), `${name}.toml`);
+  const isManagedCodexPath = value => {
+    const resolved = resolveCodexPath(value);
+    if (!resolved) return false;
+    const root = path.resolve(managedCodexDir());
+    return resolved === root || resolved.startsWith(`${root}${path.sep}`);
+  };
+  const readCodexAgentConfig = value => {
+    const resolved = resolveCodexPath(value);
+    if (!resolved || !fs.existsSync(resolved)) return null;
+    const content = fs.readFileSync(resolved, 'utf8');
+    try { return { content, data: toml.parse(content) }; } catch (_) { return { content, data: null }; }
+  };
+  const writeCodexAgentConfig = (value, data) => {
+    const resolved = resolveCodexPath(value);
+    ensureDir(path.dirname(resolved));
+    const tempPath = `${resolved}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tempPath, tomlStringify(data), 'utf8');
+    fs.renameSync(tempPath, resolved);
+  };
+  const converter = () => require('../../server/services/format-converter');
+  const escapeRegExp = value => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  function targetBasePath(type, typeConfig) {
+    if (platform === 'claude') return path.join(config.claudeDir, typeConfig.claudeTarget);
+    if (platform === 'codex') return path.join(config.codexDir, typeConfig.codexTarget);
+    if (platform === 'gemini') return path.join(config.geminiDir, typeConfig.geminiTarget);
+    if (platform === 'opencode') {
+      const modern = path.join(config.opencodeDir, typeConfig.opencodeTarget);
+      if (type === 'skills' || !typeConfig.opencodeLegacyTarget) return modern;
+      const legacy = path.join(config.opencodeDir, typeConfig.opencodeLegacyTarget);
+      return fs.existsSync(legacy) && !fs.existsSync(modern) ? legacy : modern;
+    }
+    return path.join(config.ompDir, typeConfig.ompTarget);
+  }
+
+  function targetPath(type, safeName) {
+    const typeConfig = getType(type);
+    if (platform === 'gemini' && typeConfig.geminiExtension) {
+      const extension = path.extname(safeName);
+      const targetName = safeName.replace(new RegExp(`${escapeRegExp(extension)}$`, 'i'), typeConfig.geminiExtension);
+      return path.join(targetBasePath(type, typeConfig), targetName);
+    }
+    return path.join(targetBasePath(type, typeConfig), safeName);
+  }
+
+  function syncCodex(type, safeName, sourcePath) {
+    const warnings = [];
+    if (type === 'agents') {
+      const { frontmatter } = parseFrontmatter(fs.readFileSync(sourcePath, 'utf8'));
+      const fileName = path.basename(safeName, path.extname(safeName));
+      const codexConfig = readCodexConfig();
+      codexConfig.features = isPlainObject(codexConfig.features) ? codexConfig.features : {};
+      codexConfig.features.multi_agent = true;
+      codexConfig.agents = isPlainObject(codexConfig.agents) ? codexConfig.agents : {};
+      const existing = codexConfig.agents[fileName];
+      if (Object.prototype.hasOwnProperty.call(codexConfig.agents, fileName) && !isPlainObject(existing)) {
+        return { success: false, error: `Agent name "${fileName}" conflicts with global [agents] key` };
+      }
+      const entry = isPlainObject(existing) ? { ...existing } : {};
+      entry.description = (frontmatter.description || fileName).trim();
+      const model = typeof frontmatter.model === 'string' ? frontmatter.model.trim() : '';
+      const existingConfigFile = typeof entry.config_file === 'string' ? entry.config_file.trim() : '';
+      if (model) {
+        const managedPath = isManagedCodexPath(existingConfigFile) ? existingConfigFile : managedCodexPath(fileName);
+        const parsed = readCodexAgentConfig(managedPath);
+        const data = isPlainObject(parsed?.data) ? parsed.data : {};
+        data.model = model;
+        writeCodexAgentConfig(managedPath, data);
+        entry.config_file = managedPath;
+      } else if (isManagedCodexPath(existingConfigFile)) {
+        const resolved = resolveCodexPath(existingConfigFile);
+        if (resolved && fs.existsSync(resolved)) fs.unlinkSync(resolved);
+        delete entry.config_file;
+      }
+      codexConfig.agents[fileName] = entry;
+      writeCodexConfig(codexConfig);
+      return { success: true, target: config.codexConfigPath, warnings };
+    }
+    if (type === 'skills') {
+      const target = targetPath(type, safeName);
+      copyDirWithConversion(sourcePath, target, (filePath, content) => {
+        if (path.basename(filePath) !== 'SKILL.md') return content;
+        const result = converter().convertSkillToCodex(content);
+        warnings.push(...(result.warnings || []));
+        return result.content;
+      });
+      return { success: true, target, warnings };
+    }
+    if (type === 'commands') {
+      const result = converter().convertCommandToCodex(fs.readFileSync(sourcePath, 'utf8'));
+      warnings.push(...(result.warnings || []));
+      const target = targetPath(type, safeName);
+      ensureDir(path.dirname(target));
+      fs.writeFileSync(target, result.content, 'utf8');
+      return { success: true, target, warnings };
+    }
+    return { success: false, error: 'Unexpected type' };
+  }
+
+  function sync(type, name, sourcePathOverride = null) {
+    const typeConfig = getType(type);
+    if (!typeConfig) return { success: false, error: `Unknown config type: ${type}` };
+    if (!isSupported(typeConfig)) {
+      const reason = platform === 'omp' ? 'Not supported natively by OMP' : `Not supported by ${platform}`;
+      return { success: true, skipped: true, reason };
+    }
+    const safeName = normalizeSafeRelativeName(name);
+    if (!safeName) return { success: false, error: 'Invalid config item name' };
+    const sourcePath = resolveSourcePath(type, safeName, sourcePathOverride);
+    if (!fs.existsSync(sourcePath)) return { success: false, error: 'Source not found' };
+    if (platform === 'codex') return syncCodex(type, safeName, sourcePath);
+    const target = targetPath(type, safeName);
+    ensureDir(path.dirname(target));
+    if (typeConfig.isDirectory) copyDirRecursive(sourcePath, target);
+    else if (platform === 'gemini' && type === 'commands') {
+      const result = converter().convertCommandToGemini(fs.readFileSync(sourcePath, 'utf8'));
+      fs.writeFileSync(target, result.content, 'utf8');
+      return { success: true, target, warnings: result.warnings || [] };
+    } else fs.copyFileSync(sourcePath, target);
+    return { success: true, target };
+  }
+
+  function remove(type, name) {
+    const typeConfig = getType(type);
+    if (!typeConfig) return { success: false, error: `Unknown config type: ${type}` };
+    if (!isSupported(typeConfig)) {
+      const reason = platform === 'omp' ? 'Not supported natively by OMP' : `Not supported by ${platform}`;
+      return { success: true, skipped: true, reason };
+    }
+    const safeName = normalizeSafeRelativeName(name);
+    if (!safeName) return { success: false, error: 'Invalid config item name' };
+    if (platform === 'codex' && type === 'agents') {
+      const codexConfig = readCodexConfig();
+      const agents = isPlainObject(codexConfig.agents) ? codexConfig.agents : {};
+      const fileName = path.basename(safeName, path.extname(safeName));
+      const existing = agents[fileName];
+      if (!isPlainObject(existing)) return { success: true, message: 'Already removed' };
+      if (existing.config_file && isManagedCodexPath(existing.config_file)) {
+        const resolved = resolveCodexPath(existing.config_file);
+        if (resolved && fs.existsSync(resolved)) fs.unlinkSync(resolved);
+      }
+      delete agents[fileName];
+      codexConfig.agents = agents;
+      writeCodexConfig(codexConfig);
+      return { success: true };
+    }
+    const target = targetPath(type, safeName);
+    if (!fs.existsSync(target)) return { success: true, message: 'Already removed' };
+    if (typeConfig.isDirectory) removeRecursive(target);
+    else {
+      fs.unlinkSync(target);
+      cleanupEmptyParents(path.dirname(target), targetBasePath(type, typeConfig));
+    }
+    return { success: true };
+  }
+
+  const invoke = (operation, args) => {
+    try {
+      const value = operation === 'sync' ? sync(...args) : remove(...args);
+      const wrap = data => ok(platform, 'resourceSync', operation, data);
+      return value && typeof value.then === 'function' ? value.then(wrap).catch(error => failed(platform, 'resourceSync', operation, error)) : wrap(value);
+    } catch (error) {
+      return failed(platform, 'resourceSync', operation, error);
+    }
+  };
+
+  return { platform, capability: 'resourceSync', ...context, sync: (...args) => invoke('sync', args), remove: (...args) => invoke('remove', args) };
+}
+
+module.exports = { CONFIG_TYPES, createResourceSyncDriver, normalizeSafeRelativeName };

package/src/shared/driver-result.js

@@ -0,0 +1,78 @@
+'use strict';
+
+function createDriverResult({ platform, capability, operation, status = 'ok', data, error, cause } = {}) {
+  const result = { status, platform, capability, operation };
+  if (status === 'ok' && data !== undefined) result.data = data;
+  if (error) result.error = error instanceof Error ? error.message : String(error);
+  if (cause) Object.defineProperty(result, 'cause', { value: cause, enumerable: false });
+  return result;
+}
+
+function normalizeDriverResult(value, context = {}) {
+  if (value && typeof value === 'object' && typeof value.status === 'string') {
+    const result = {
+      ...value,
+      platform: value.platform || context.platform,
+      capability: value.capability || context.capability,
+      operation: value.operation || context.operation
+    };
+    if (value.cause) Object.defineProperty(result, 'cause', { value: value.cause, enumerable: false });
+    return result;
+  }
+  return createDriverResult({ ...context, status: 'ok', data: value });
+}
+
+function driverError(result, fallback = 'Driver operation failed') {
+  if (!result || typeof result !== 'object' || !result.status || result.status === 'ok') return null;
+  if (result.cause instanceof Error) return result.cause;
+  const error = new Error(result.error || fallback);
+  error.status = result.status;
+  error.platform = result.platform;
+  error.capability = result.capability;
+  error.operation = result.operation;
+  return error;
+}
+
+function unwrapDriverResult(result, context = {}) {
+  const normalized = normalizeDriverResult(result, context);
+  const error = driverError(normalized, `Driver operation ${normalized.operation || 'unknown'} failed`);
+  if (error) throw error;
+  return normalized.status === 'ok' ? normalized.data : normalized;
+}
+
+async function invokeDriverOperation(driver, operation, args = [], context = {}) {
+  if (!driver || typeof driver[operation] !== 'function') {
+    return createDriverResult({ ...context, operation, status: 'unsupported' });
+  }
+  try {
+    const value = await driver[operation](...args);
+    return normalizeDriverResult(value, { ...context, operation });
+  } catch (error) {
+    return createDriverResult({ ...context, operation, status: 'failed', error, cause: error });
+  }
+}
+
+const ok = (platform, capability, operation, data) => createDriverResult({
+  platform, capability, operation, status: 'ok', data
+});
+const unsupported = (platform, capability, operation) => createDriverResult({
+  platform, capability, operation, status: 'unsupported'
+});
+const invalid = (platform, capability, operation, error) => createDriverResult({
+  platform, capability, operation, status: 'invalid', error, cause: error
+});
+const failed = (platform, capability, operation, error) => createDriverResult({
+  platform, capability, operation, status: 'failed', error, cause: error
+});
+
+module.exports = {
+  createDriverResult,
+  normalizeDriverResult,
+  driverError,
+  unwrapDriverResult,
+  invokeDriverOperation,
+  ok,
+  unsupported,
+  invalid,
+  failed
+};