@givolt/i3-composer-agent 3.0.0 → 3.1.0

package/skills/i3-ui-demo/scripts/design-provider.cjs

@@ -0,0 +1,57 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const { discoverProviderCandidates } = require('./provider-discovery.cjs');
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const json = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+function ensure(condition, message) { if (!condition) throw new Error(message); }
+function providerVersion(root) {
+  const receipt = path.join(root, 'UPSTREAM-ORIGIN.json');
+  if (fs.existsSync(receipt)) {
+    try { const source = json(receipt); if (source.packageName === 'ui-ux-pro-max-cli' && typeof source.version === 'string') return source.version; } catch {}
+  }
+  for (let folder = root, i = 0; i < 5; i++, folder = path.dirname(folder)) {
+    for (const name of ['skill.json', '.claude-plugin/plugin.json', '.codebuddy-plugin/plugin.json', 'package.json']) {
+      const file = path.join(folder, name);
+      if (fs.existsSync(file)) {
+        try {
+          const metadata = json(file);
+          if (name === 'package.json' && !['ui-ux-pro-max', 'ui-ux-pro-max-cli'].includes(metadata.name)) continue;
+          if (metadata.version) return metadata.version;
+        } catch {}
+      }
+    }
+  }
+  return 'unversioned';
+}
+function queryProvider(root, query, options = {}) {
+  const mode = options.stack ? ['--stack', options.stack] : options.designSystem ? ['--design-system'] : ['--domain', options.domain || 'ux'];
+  const run = spawnSync(options.python || (process.platform === 'win32' ? 'python' : 'python3'), ['-B', path.join(root, 'scripts/search.py'), query, ...mode, '--json'], { encoding: 'utf8', timeout: 15000, maxBuffer: 5 * 1024 * 1024 });
+  ensure(run.status === 0, `UI/UX Pro Max query unavailable: ${run.error?.code || (run.stderr || '').trim().slice(0, 400)}`);
+  return JSON.parse(run.stdout);
+}
+function checkDesignProvider(options = {}) {
+  const discovery = discoverProviderCandidates(options);
+  const attempts = [];
+  const roots = discovery.candidates.map(candidate => path.resolve(candidate.root));
+  const diagnostics = discovery.diagnostics;
+  if (discovery.contextRequired) return { availability: 'needs-context', searched: roots, attempts, diagnostics, reason: '请指定当前宿主 --host，或传入宿主实际提供的 --provider 技能路径；尚不能判断是否已安装' };
+  for (const candidate of discovery.candidates) {
+    const root = path.resolve(candidate.root);
+    if (!fs.existsSync(root)) { attempts.push({ root, source: candidate.source, availability: 'missing', reason: '技能路径不存在' }); continue; }
+    const required = ['SKILL.md', 'scripts/search.py', 'scripts/core.py', 'scripts/design_system.py', ...['ux-guidelines', 'styles', 'colors', 'typography', 'products', 'landing', 'ui-reasoning'].map(name => `data/${name}.csv`)];
+    const missing = required.filter(file => !fs.existsSync(path.join(root, file)));
+    if (missing.length) { attempts.push({ root, source: candidate.source, availability: 'unusable', missing, reason: '技能资源不完整' }); continue; }
+    try {
+      const probe = queryProvider(root, 'error summary validation', { python: options.python, domain: 'ux' });
+      ensure(probe.domain === 'ux' && probe.results?.length, 'No verified UX probe result');
+      attempts.push({ root, source: candidate.source, availability: 'available' });
+      return { availability: 'available', root, source: candidate.source, version: providerVersion(root), digest: hash(required.map(file => hash(fs.readFileSync(path.join(root, file)))).join('\n')), searched: roots, attempts, diagnostics };
+    } catch (error) { attempts.push({ root, source: candidate.source, availability: 'unusable', reason: error.message }); }
+  }
+  const failure = attempts.find(attempt => attempt.availability === 'unusable') || ['ambiguous', 'disabled', 'discovery-error'].map(status => diagnostics.find(item => item.availability === status)).find(Boolean);
+  return { ...(failure || {}), availability: failure?.availability || 'missing', searched: roots, attempts, diagnostics, reason: failure?.reason || (options.provider ? '指定的 UI/UX Pro Max 技能路径不存在，请核对 --provider' : '当前宿主未发现 UI/UX Pro Max；可安装，或传入宿主实际提供的 --provider 技能路径') };
+}
+module.exports = { checkDesignProvider, queryProvider, providerVersion };

package/skills/i3-ui-demo/scripts/locations.cjs

@@ -0,0 +1,52 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+// Reviewed mirror of i3's installer target table; maintenance tests require byte equality.
+const registry = require('../assets/host-targets.json');
+const aliases = { claude: 'claude-code', gemini: 'gemini-cli', copilot: 'github-copilot' };
+function globalSkillsDir(agent, home, env) {
+  const config = agent.globalSkillsDir;
+  if (!config) return null;
+  let base = home;
+  if (config.base === 'config') base = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
+  if (config.base === 'env') base = env[config.env]?.trim() || path.join(home, config.fallback);
+  if (['CODEBUDDY_CONFIG_DIR','WORKBUDDY_CONFIG_DIR'].includes(config.env) && (!path.isAbsolute(base) || /[\x00\r\n]/.test(base))) throw new Error(`${config.env} must be an absolute safe directory`);
+  if (config.alternatives && !fs.existsSync(path.join(home, path.dirname(config.path)))) {
+    const alternative = config.alternatives.find(relative => fs.existsSync(path.join(home, path.dirname(relative))));
+    if (alternative) return path.join(home, alternative);
+  }
+  return path.resolve(base, config.path);
+}
+function installedContext() {
+  const file = path.resolve(__dirname, '../../../.i3-composer-agent.json');
+  if (!fs.existsSync(file)) return {};
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (data.name !== 'i3-composer-agent' || !Array.isArray(data.agents)) throw new Error('Invalid i3 installation context');
+  return { hosts: data.agents, scope: data.scope };
+}
+function resolveLocations(options = {}) {
+  const installed = installedContext();
+  if (!options.host && installed.hosts?.length > 1) throw new Error('Multiple installed hosts; specify --host');
+  const selected = options.host || installed.hosts?.[0] || 'codebuddy';
+  const host = aliases[selected] || selected, scope = options.scope || 'project';
+  const agent = registry.agents.find(item => item.id === host);
+  if (!agent) throw new Error(`Unknown host: ${host}`);
+  if (!['project', 'global'].includes(scope)) throw new Error('Use scope project or global');
+  const project = fs.realpathSync(path.resolve(options.project || '.'));
+  if (!fs.statSync(project).isDirectory()) throw new Error('Project must be a directory');
+  const home = path.resolve(options.home || os.homedir()), env = options.env || process.env;
+  const projectSkills = path.resolve(project, agent.projectSkillsDir), globalSkills = globalSkillsDir(agent, home, env);
+  if (scope === 'global' && !globalSkills) throw new Error(`${agent.label}: project installation only`);
+  const skillsDirectory = scope === 'project' ? projectSkills : globalSkills, base = path.dirname(skillsDirectory);
+  const projectBase = path.dirname(projectSkills), globalBase = globalSkills ? path.dirname(globalSkills) : null;
+  // Some hosts put skills directly in the workspace; tools still get a host directory.
+  const projectToolsBase = projectBase === project ? path.join(project, `.${host}`) : projectBase;
+  const projectKey = `${path.basename(project).replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 32) || 'project'}-${crypto.createHash('sha256').update(project).digest('hex').slice(0, 16)}`;
+  const cacheBase = path.join(scope === 'global' ? globalBase : projectToolsBase, 'cache/i3-ui-demo');
+  return { host, scope, project, home, skillsDirectory, base, projectSkills, globalSkills,
+    projectBase, globalBase, projectToolsBase, projectKey, cacheDirectory: scope === 'global' ? path.join(cacheBase, projectKey) : cacheBase,
+    toolsDirectory: path.join(scope === 'global' ? globalBase : projectToolsBase, 'tools/i3-ui-demo') };
+}
+module.exports = { registry, resolveLocations };

package/skills/i3-ui-demo/scripts/mcp.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { browser } = require('../assets/versions.json');
+const desired = { command: 'npx', args: ['-y', `${browser.package}@${browser.version}`, '--isolated', '--no-usage-statistics'] };
+const attachedBrowser = /(?:--(?:auto-?connect|browser-?url|ws-?endpoint|user-?data-?dir)|(?:^|[\s"'])-[uw])(?:[=\s"']|$)/i;
+const hash = data => crypto.createHash('sha256').update(data).digest('hex');
+function safe(file) {
+  if (!path.isAbsolute(file) || /[\0\r\n]/.test(file)) throw new Error('Configuration path must be absolute');
+  let current = path.parse(file).root;
+  for (const part of path.relative(current, file).split(path.sep)) {
+    current = path.join(current, part);
+    try { if (fs.lstatSync(current).isSymbolicLink()) throw new Error(`Configuration symlink preserved: ${current}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return file;
+}
+function configFile(options) {
+  const project = fs.realpathSync(path.resolve(options.project || '.'));
+  const home = path.resolve(options.home || os.homedir()), scope = options.scope || 'project';
+  if (!['project', 'global'].includes(scope)) throw new Error('Use scope project or global');
+  if (options.config) {
+    const file = path.resolve(options.config), base = scope === 'project' ? project : home;
+    if (path.relative(base, file).startsWith('..') || path.isAbsolute(path.relative(base, file))) throw new Error('Explicit config escapes the selected scope');
+    return safe(file);
+  }
+  const env = options.env || process.env;
+  const codebuddy = env.CODEBUDDY_CONFIG_DIR || path.join(home, '.codebuddy');
+  const codex = env.CODEX_HOME || path.join(home, '.codex');
+  const candidates = {
+    codebuddy: scope === 'project' ? [path.join(project, '.mcp.json'), path.join(project, 'mcp.json')]
+      : [path.join(codebuddy, '.mcp.json'), path.join(codebuddy, 'mcp.json'), path.join(home, '.codebuddy.json')],
+    'claude-code': [scope === 'project' ? path.join(project, '.mcp.json') : path.join(home, '.claude.json')],
+    codex: [scope === 'project' ? path.join(project, '.codex/config.toml') : path.join(codex, 'config.toml')],
+    cursor: [path.join(scope === 'project' ? project : home, '.cursor/mcp.json')],
+    'gemini-cli': [path.join(scope === 'project' ? project : home, '.gemini/settings.json')],
+  }[options.host];
+  if (!candidates) throw new Error('Unsupported host; supply the host-confirmed --config path rather than guessing');
+  for (const file of candidates) safe(file);
+  return candidates.find(file => fs.existsSync(file)) || candidates[0];
+}
+function compatible(server) {
+  return server && typeof server.command === 'string' && Array.isArray(server.args)
+    && server.args.some(arg => typeof arg === 'string' && /chrome-devtools-mcp(?:@|$)/.test(arg))
+    && !attachedBrowser.test(server.args.join(' '))
+    && server.disabled !== true && server.enabled !== false;
+}
+function plan(options = {}) {
+  const file = configFile(options), original = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+  const digest = hash(file + '\0' + (original === null ? '<missing>' : original));
+  const server = { ...desired, args: [...desired.args, '--workspace', fs.realpathSync(path.resolve(options.project || '.'))] };
+  const result = { file, digest, host: options.host, scope: options.scope || 'project', connectionVerified: false, server };
+  const base = original || '';
+  if (file.endsWith('.toml')) {
+    const header = /^\s*\[\s*mcp_servers\.(?:chrome-devtools|"chrome-devtools"|'chrome-devtools')\s*\]\s*(?:#.*)?$/m;
+    const match = header.exec(base);
+    if (match) {
+      const block = base.slice(match.index + match[0].length).split(/^\s*\[/m)[0];
+      const recognized = /chrome-devtools-mcp/.test(block) && !attachedBrowser.test(block) && !/enabled\s*=\s*false/.test(block);
+      return { ...result, status: recognized ? 'configured-unverified' : 'conflict', reason: recognized ? 'Connect the current host and call a browser tool' : 'Existing server preserved; review the configuration' };
+    }
+    if (/^\s*mcp_servers\s*[.=]|^\s*\[\[?\s*['"]mcp_servers/m.test(base)) return { ...result, status: 'conflict', reason: 'Non-table MCP configuration preserved; use the host editor' };
+    const addition = '\n[mcp_servers.chrome-devtools]\ncommand = ' + JSON.stringify(server.command) + '\nargs = ' + JSON.stringify(server.args) + '\n';
+    return { ...result, status: 'needs-configuration', nextContent: base + addition };
+  }
+  let data;
+  try { data = base.trim() ? JSON.parse(base) : {}; }
+  catch { return { ...result, status: 'conflict', reason: 'JSONC or invalid JSON preserved; use the host editor for a precise edit' }; }
+  if (!data || Array.isArray(data) || typeof data !== 'object' || (data.mcpServers !== undefined && (!data.mcpServers || Array.isArray(data.mcpServers) || typeof data.mcpServers !== 'object'))) {
+    return { ...result, status: 'conflict', reason: 'Existing MCP configuration shape preserved' };
+  }
+  const existing = data.mcpServers?.['chrome-devtools'];
+  if (existing !== undefined) return { ...result, status: compatible(existing) ? 'configured-unverified' : 'conflict', reason: 'Existing server preserved; connectivity must be checked in the current host' };
+  data.mcpServers = { ...data.mcpServers, 'chrome-devtools': server };
+  return { ...result, status: 'needs-configuration', nextContent: JSON.stringify(data, null, 2) + '\n' };
+}
+function apply(options = {}) {
+  if (options.write !== true) throw new Error('Explicit write authorization (--write) is required');
+  if (typeof options.expected !== 'string') throw new Error('Supply the expected configuration digest from the read-only plan');
+  const before = plan(options);
+  if (before.digest !== options.expected) throw new Error('Configuration changed since the plan; re-read before writing');
+  if (before.status === 'conflict') throw new Error(`Configuration conflict: ${before.reason}`);
+  if (before.status === 'configured-unverified') return before;
+  const parent = path.dirname(before.file); safe(parent); fs.mkdirSync(parent, { recursive: true });
+  const temporary = path.join(parent, '.ui-demo-mcp-' + crypto.randomBytes(8).toString('hex'));
+  try {
+    fs.writeFileSync(temporary, before.nextContent, { flag: 'wx', mode: fs.existsSync(before.file) ? fs.statSync(before.file).mode & 0o777 : 0o600 });
+    if (plan(options).digest !== before.digest) throw new Error('Configuration changed during preparation; user edit preserved');
+    safe(before.file); fs.renameSync(temporary, before.file);
+  } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+  const { nextContent, ...result } = plan(options);
+  return { ...result, note: 'Configuration only. Enable/reload the host if needed and actually call Chrome DevTools MCP before reporting verification.' };
+}
+function parse(argv) {
+  const operation = argv.shift() || 'plan', options = {};
+  if (!['plan', 'apply'].includes(operation)) throw new Error('Use plan or apply');
+  while (argv.length) {
+    const flag = argv.shift();
+    if (flag === '--write') { options.write = true; continue; }
+    if (!['--project', '--host', '--scope', '--home', '--config', '--expected'].includes(flag) || !argv.length) throw new Error(`Invalid option: ${flag}`);
+    options[flag.slice(2)] = argv.shift();
+  }
+  return { operation, options };
+}
+module.exports = { plan, apply, configFile, desired, safe };
+if (require.main === module) {
+  try { const { operation, options } = parse(process.argv.slice(2)); process.stdout.write(JSON.stringify(operation === 'apply' ? apply(options) : plan(options), null, 2) + '\n'); }
+  catch (error) { process.stderr.write(JSON.stringify({ status: 'failed', errors: [error.message] }) + '\n'); process.exitCode = 1; }
+}

package/skills/i3-ui-demo/scripts/provider-discovery.cjs

@@ -0,0 +1,131 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { spawnSync } = require('node:child_process');
+
+const PROVIDER = 'ui-ux-pro-max';
+const MARKETPLACE = 'ui-ux-pro-max-skill';
+const json = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const safeSegment = value => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._+-]*$/.test(value) && !value.includes('..');
+function ensure(condition, message) { if (!condition) throw new Error(message); }
+function canonical(file) { return fs.existsSync(file) ? fs.realpathSync(file) : path.resolve(file); }
+
+function pluginRoot(installation, manifests, fallback) {
+  ensure(typeof installation.installPath === 'string' && path.isAbsolute(installation.installPath), 'Plugin installPath must be absolute');
+  ensure(safeSegment(installation.version), 'Installed plugin version is invalid');
+  const root = installation.installPath;
+  const manifestFile = manifests.map(name => path.join(root, name)).find(file => fs.existsSync(file));
+  ensure(manifestFile, 'Installed plugin manifest is missing');
+  const manifest = json(manifestFile);
+  ensure(manifest.name === PROVIDER && manifest.version === installation.version, 'Installed plugin manifest name or version does not match its registration');
+  const declared = manifest.skills === undefined ? fallback : manifest.skills;
+  ensure(typeof declared === 'string' && declared && !path.isAbsolute(declared) && !declared.includes('\\'), 'Plugin skills declaration is missing or invalid');
+  const folder = path.resolve(root, declared), relative = path.relative(path.resolve(root), folder);
+  ensure(relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative), 'Plugin skills declaration escapes its root');
+  if (fs.existsSync(folder)) {
+    const realRelative = path.relative(canonical(root), canonical(folder));
+    ensure(realRelative !== '..' && !realRelative.startsWith(`..${path.sep}`) && !path.isAbsolute(realRelative), 'Plugin skills path escapes its root');
+  }
+  const skill = path.join(folder, PROVIDER);
+  ensure(fs.existsSync(path.join(skill, 'SKILL.md')), 'Installed plugin skill entrypoint is missing');
+  const skillRelative = path.relative(canonical(root), canonical(skill));
+  ensure(skillRelative !== '..' && !skillRelative.startsWith(`..${path.sep}`) && !path.isAbsolute(skillRelative), 'Plugin skill path escapes its root');
+  return skill;
+}
+
+function codexCandidates(config, project, env, add, report, python) {
+  const source = 'codex-plugin';
+  try {
+    const file = path.join(config, 'config.toml');
+    if (!fs.existsSync(file)) { report(source, 'missing', 'Codex plugin registration is absent'); return; }
+    // `codex plugin list` may create config/cache files even for inspection.
+    // Read the existing registration instead; never launch the host CLI here.
+    const script = 'import json,sys,tomllib; f=open(sys.argv[1],"rb"); print(json.dumps(tomllib.load(f).get("plugins",{}).get(sys.argv[2])))';
+    const run = spawnSync(python || (process.platform === 'win32' ? 'python' : 'python3'), ['-B', '-c', script, file, `${PROVIDER}@${MARKETPLACE}`], { env: { ...process.env, ...env }, encoding: 'utf8', timeout: 10000, maxBuffer: 1024 * 1024, shell: false });
+    ensure(!run.error && run.status === 0, 'Read-only Codex plugin detection needs Python 3.11+ with tomllib, or an explicit --provider path');
+    const registration = JSON.parse(run.stdout);
+    if (registration === null) { report(source, 'missing', 'Current Codex host has no registered UI/UX Pro Max plugin'); return; }
+    ensure(object(registration) && typeof registration.enabled === 'boolean', 'Codex plugin registration is invalid');
+    if (!registration.enabled) { report(source, 'disabled', 'UI/UX Pro Max is disabled in the current Codex host'); return; }
+    const cache = path.join(config, 'plugins/cache', MARKETPLACE, PROVIDER);
+    const versions = fs.existsSync(cache) ? fs.readdirSync(cache, { withFileTypes: true }).filter(entry => entry.isDirectory() && safeSegment(entry.name)).map(entry => entry.name) : [];
+    if (!versions.length) { report(source, 'missing', 'Registered Codex plugin payload is missing'); return; }
+    if (versions.length !== 1) { report(source, 'ambiguous', 'Multiple cached Codex plugin versions require an explicit --provider path'); return; }
+    const version = versions[0];
+    add(pluginRoot({ installPath: path.join(cache, version), version }, ['.codex-plugin/plugin.json', '.claude-plugin/plugin.json']), source);
+  } catch (error) { report(source, 'discovery-error', error.message); }
+}
+
+function registeredCandidates(host, config, project, add, report) {
+  const source = `${host}-plugin`, registryFile = path.join(config, 'plugins/installed_plugins.json'), settingsFile = path.join(config, 'settings.json');
+  try {
+    if (!fs.existsSync(registryFile)) { report(source, 'missing', 'Optional host plugin installation registry is absent'); return; }
+    const registry = json(registryFile);
+    ensure(registry.version === 2 && object(registry.plugins), 'Host plugin installation registry has an unsupported or invalid schema');
+    const entries = Object.entries(registry.plugins).filter(([id]) => id.startsWith(`${PROVIDER}@`));
+    if (!entries.length) { report(source, 'missing', 'Current host has no registered UI/UX Pro Max plugin'); return; }
+    ensure(fs.existsSync(settingsFile), 'Registered plugin enablement metadata is missing');
+    const settings = json(settingsFile);
+    ensure(object(settings) && object(settings.enabledPlugins), 'Host plugin enablement metadata is invalid');
+    const active = [];
+    let disabled = false;
+    for (const [id, records] of entries) {
+      ensure(Array.isArray(records), 'Host plugin registration must contain an installation array');
+      if (settings.enabledPlugins[id] !== true) { disabled = true; continue; }
+      for (const record of records) {
+        ensure(object(record), 'Host plugin installation entry is invalid');
+        if (record.scope === 'user') active.push(record);
+        else if (record.scope === 'project') {
+          ensure(typeof record.projectPath === 'string' && path.isAbsolute(record.projectPath), 'Project-scoped plugin requires an absolute projectPath');
+          if (canonical(record.projectPath) === canonical(project)) active.push(record);
+        } else throw new Error('Host plugin installation scope is unsupported');
+      }
+    }
+    if (!active.length) { report(source, disabled ? 'disabled' : 'missing', 'No enabled UI/UX Pro Max installation applies to the current project'); return; }
+    if (active.length !== 1) { report(source, 'ambiguous', 'Multiple applicable plugin installations require an explicit provider path'); return; }
+    const fallback = host === 'workbuddy' || host === 'codebuddy' ? './skills/' : undefined;
+    const manifests = host === 'claude' ? ['.claude-plugin/plugin.json'] : ['.codebuddy-plugin/plugin.json', '.claude-plugin/plugin.json'];
+    add(pluginRoot(active[0], manifests, fallback), source);
+  } catch (error) { report(source, 'discovery-error', error.message); }
+}
+
+function discoverProviderCandidates(options = {}) {
+  const result = { candidates: [], diagnostics: [] }, seen = new Set();
+  const report = (source, availability, reason) => result.diagnostics.push({ source, availability, reason });
+  const add = (root, source) => {
+    ensure(typeof root === 'string' && root, 'Provider root must be a nonempty path');
+    root = path.resolve(root);
+    if (!seen.has(root)) { seen.add(root); result.candidates.push({ root, source }); }
+  };
+  if (options.provider !== undefined) {
+    try { add(options.provider, 'explicit'); } catch (error) { report('explicit', 'discovery-error', error.message); }
+    return result;
+  }
+  if (options.providerRoots !== undefined) {
+    try {
+      ensure(Array.isArray(options.providerRoots), 'Host-exposed providerRoots must be an array');
+      for (const root of options.providerRoots) add(root, 'host-exposed');
+    } catch (error) { report('host-exposed', 'discovery-error', error.message); }
+    return result;
+  }
+  if (options.discover === false) return { ...result, contextRequired: true };
+  const host = options.host === 'claude-code' ? 'claude' : options.host;
+  if (!['codex', 'claude', 'workbuddy', 'codebuddy', 'gemini', 'cursor'].includes(host)) return { ...result, contextRequired: true };
+  const home = options.home || os.homedir(), env = options.env === undefined ? process.env : options.env, project = path.resolve(options.project || '.');
+  const configName = host === 'claude' ? 'CLAUDE_CONFIG_DIR' : `${host.toUpperCase()}_${host === 'codex' ? 'HOME' : 'CONFIG_DIR'}`;
+  const config = path.resolve(env[configName] || path.join(home, `.${host}`));
+  const projectFolder = host === 'codex' ? '.agents' : host === 'workbuddy' ? '.codebuddy' : `.${host}`;
+  const locations = [
+    [path.join(project, projectFolder, 'skills', PROVIDER), 'project-skill'],
+    ...(host === 'codex' ? [[path.join(home, '.agents/skills', PROVIDER), 'global-skill']] : []),
+    [path.join(config, 'skills', PROVIDER), 'global-skill'],
+  ];
+  for (const [root, source] of locations) if (fs.existsSync(path.join(root, 'SKILL.md'))) add(root, source);
+  if (host === 'codex' && !result.candidates.length) codexCandidates(config, project, env, add, report, options.python);
+  else if (['claude', 'workbuddy', 'codebuddy'].includes(host)) registeredCandidates(host, config, project, add, report);
+  return result;
+}
+
+module.exports = { discoverProviderCandidates };