@djordje-stojanovic/sigmaskills 0.2.0

package/src/destinations.js

@@ -0,0 +1,491 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { findPackageRoot } from './catalog.js';
+import { inspectManagedPath, pathExists } from './links.js';
+
+export const UNIVERSAL_PROJECT_DESTINATION = '.agents/skills';
+
+/**
+ * Load the bundled Agent Host registry snapshot.
+ *
+ * @param {string} [packageRoot]
+ * @returns {object}
+ */
+export function loadHostRegistry(packageRoot = findPackageRoot()) {
+  const snapshotPath = path.join(packageRoot, 'registry', 'agent-hosts.json');
+  if (!fs.existsSync(snapshotPath)) {
+    throw new Error(`missing Agent Host registry at ${snapshotPath}`);
+  }
+  let snapshot;
+  try {
+    snapshot = JSON.parse(fs.readFileSync(snapshotPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`failed to read Agent Host registry at ${snapshotPath}: ${err.message}`);
+  }
+  if (!snapshot || !Array.isArray(snapshot.hosts)) {
+    throw new Error('registry hosts must be an array');
+  }
+  return snapshot;
+}
+
+/**
+ * Normalize a project-relative destination root to posix form without a trailing slash.
+ *
+ * @param {string} relativeRoot
+ * @returns {string}
+ */
+export function normalizeRelativeRoot(relativeRoot) {
+  return String(relativeRoot || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+}
+
+/**
+ * Whether a host is labeled detected from environment metadata.
+ * Detection never selects destinations.
+ *
+ * @param {object} host
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function detectHost(host, env = process.env) {
+  const envVars = host?.detection?.envVars;
+  if (!Array.isArray(envVars) || envVars.length === 0) return false;
+  return envVars.some((name) => {
+    const value = env[name];
+    return value !== undefined && value !== '';
+  });
+}
+
+function expandProjectRelativeRoot(formula) {
+  if (!formula || formula.kind === 'none') return null;
+  if (formula.kind !== 'literal' || typeof formula.path !== 'string') return null;
+  const relativeRoot = normalizeRelativeRoot(formula.path);
+  if (!relativeRoot) return null;
+  return relativeRoot;
+}
+
+function compareIds(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function compareRoots(a, b) {
+  if (a === UNIVERSAL_PROJECT_DESTINATION && b !== UNIVERSAL_PROJECT_DESTINATION) return -1;
+  if (b === UNIVERSAL_PROJECT_DESTINATION && a !== UNIVERSAL_PROJECT_DESTINATION) return 1;
+  return compareIds(a, b);
+}
+
+/**
+ * Group every Agent Host by its Project Installation destination.
+ * Hosts without a project destination still appear under a non-selectable group.
+ *
+ * @param {object} params
+ * @param {object} params.registry
+ * @param {string} params.projectRoot
+ * @param {NodeJS.ProcessEnv} [params.env]
+ * @returns {object[]}
+ */
+export function listProjectDestinationGroups({ registry, projectRoot, env = process.env }) {
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  const grouped = new Map();
+
+  for (const host of registry.hosts || []) {
+    const relativeRoot = expandProjectRelativeRoot(host.destinations?.project);
+    const key = relativeRoot || `__none__:${host.id}`;
+    if (!grouped.has(key)) {
+      const universal = relativeRoot === UNIVERSAL_PROJECT_DESTINATION;
+      grouped.set(key, {
+        key,
+        relativeRoot: relativeRoot || '',
+        absoluteRoot: relativeRoot ? path.resolve(resolvedProjectRoot, ...relativeRoot.split('/')) : '',
+        universal,
+        selectedByDefault: universal,
+        selectable: Boolean(relativeRoot),
+        hosts: [],
+      });
+    }
+    grouped.get(key).hosts.push({
+      id: host.id,
+      name: host.name,
+      displayName: host.displayName,
+      aliases: [...(host.aliases || [])],
+      detected: detectHost(host, env),
+      relativeRoot: relativeRoot || '',
+    });
+  }
+
+  const groups = [...grouped.values()].sort((a, b) => compareRoots(a.relativeRoot || a.key, b.relativeRoot || b.key));
+  for (const group of groups) {
+    group.hosts.sort((a, b) => compareIds(a.id, b.id));
+  }
+  return groups;
+}
+
+/**
+ * Default selected destination roots: only the universal `.agents/skills` path.
+ *
+ * @param {object[]} groups
+ * @returns {string[]}
+ */
+export function defaultSelectedRoots(groups) {
+  return groups.filter((group) => group.selectedByDefault).map((group) => group.relativeRoot);
+}
+
+/**
+ * Search all hosts by id, display name, name, or alias. Detection does not hide hosts.
+ *
+ * @param {object[]} groups
+ * @param {string} query
+ * @returns {object[]}
+ */
+export function searchHosts(groups, query) {
+  const needle = String(query || '').trim().toLowerCase();
+  const hosts = groups.flatMap((group) => group.hosts.map((host) => ({ ...host, group })));
+  if (!needle) return hosts;
+  return hosts.filter((host) => {
+    const haystacks = [host.id, host.name, host.displayName, ...(host.aliases || [])];
+    return haystacks.some((value) => String(value || '').toLowerCase().includes(needle));
+  });
+}
+
+function isInsideProject(projectRoot, absolutePath) {
+  const relative = path.relative(path.resolve(projectRoot), path.resolve(absolutePath));
+  return relative === '' || (relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/**
+ * Resolve one skill folder under a project destination root.
+ *
+ * @param {string} projectRoot
+ * @param {string} relativeRoot
+ * @param {string} skillId
+ * @returns {{ destination: string, relativeDestination: string, relativeRoot: string }}
+ */
+export function resolveSkillPath(projectRoot, relativeRoot, skillId) {
+  const normalizedRoot = normalizeRelativeRoot(relativeRoot);
+  if (!normalizedRoot || normalizedRoot.split('/').some((segment) => segment === '..')) {
+    throw new Error(`invalid destination '${relativeRoot}'`);
+  }
+
+  const destination = path.resolve(projectRoot, ...normalizedRoot.split('/'), skillId);
+  if (!isInsideProject(projectRoot, destination)) {
+    throw new Error(`invalid destination '${relativeRoot}': resolved path escapes the project`);
+  }
+
+  const relativeDestination = path.relative(path.resolve(projectRoot), destination).replace(/\\/g, '/');
+  if (!relativeDestination || relativeDestination.startsWith('../')) {
+    throw new Error(`invalid destination '${relativeRoot}'`);
+  }
+
+  return {
+    destination,
+    relativeDestination,
+    relativeRoot: normalizedRoot,
+  };
+}
+
+const GLOBAL_BASES = Object.freeze({
+  home: (homeDir) => homeDir,
+  homeDir: (homeDir) => homeDir,
+  configHome: (homeDir, env) => env.XDG_CONFIG_HOME || path.join(homeDir, '.config'),
+  claudeHome: (homeDir, env) => env.CLAUDE_CONFIG_DIR || path.join(homeDir, '.claude'),
+  codexHome: (homeDir, env) => env.CODEX_HOME || path.join(homeDir, '.codex'),
+  grokHome: (homeDir, env) => env.GROK_HOME || path.join(homeDir, '.grok'),
+  hermesHome: (homeDir, env) => env.HERMES_HOME || path.join(homeDir, '.hermes'),
+  vibeHome: (homeDir, env) => env.VIBE_HOME || path.join(homeDir, '.vibe'),
+  autohandHome: (homeDir, env) => env.AUTOHAND_HOME || path.join(homeDir, '.autohand'),
+});
+
+/**
+ * Resolve the user home used for Global Installation. Env wins so tests can sandbox.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function resolveHomeDir(env = process.env) {
+  const fromEnv = env.HOME || env.USERPROFILE;
+  return path.resolve(fromEnv || os.homedir());
+}
+
+function posixPath(value) {
+  return String(value || '').replace(/\\/g, '/');
+}
+
+function isUncPath(value) {
+  return /^[/\\]{2}[^/\\]+/.test(String(value || ''));
+}
+
+function isFilesystemRoot(absolutePath) {
+  const resolved = path.resolve(absolutePath);
+  const parsed = path.parse(resolved);
+  return resolved === parsed.root || posixPath(resolved) === '/' || /^[A-Za-z]:[\\/]?$/.test(resolved);
+}
+
+function isInsideHome(homeDir, absolutePath) {
+  const relative = path.relative(path.resolve(homeDir), path.resolve(absolutePath));
+  return relative === '' || (relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function assertSafeUserPath(homeDir, absolutePath, label, { allowHome = false } = {}) {
+  const resolved = path.resolve(absolutePath);
+  if (isUncPath(resolved) || isUncPath(absolutePath)) {
+    throw new Error(`invalid destination '${label}': UNC path`);
+  }
+  if (isFilesystemRoot(resolved)) {
+    throw new Error(`invalid destination '${label}': filesystem root`);
+  }
+  if (!isInsideHome(homeDir, resolved)) {
+    throw new Error(`invalid destination '${label}': resolved path escapes the user home`);
+  }
+  if (!allowHome && path.resolve(resolved) === path.resolve(homeDir)) {
+    throw new Error(`invalid destination '${label}': user home root`);
+  }
+}
+
+function splitSafeSegments(segment, label) {
+  const posix = posixPath(segment);
+  if (isUncPath(posix) || path.isAbsolute(segment) || /^[A-Za-z]:/.test(segment)) {
+    throw new Error(`invalid destination '${label}'`);
+  }
+  const parts = posix.split('/').filter((part) => part && part !== '.');
+  if (parts.some((part) => part === '..')) {
+    throw new Error(`invalid destination '${label}': traversal`);
+  }
+  return parts;
+}
+
+function resolveKnownBase(baseName, homeDir, env, label) {
+  const resolver = GLOBAL_BASES[baseName];
+  if (!resolver) {
+    throw new Error(`unsupported global destination base '${baseName}'`);
+  }
+  const base = path.resolve(resolver(homeDir, env));
+  assertSafeUserPath(homeDir, base, label, { allowHome: true });
+  return base;
+}
+
+/**
+ * Expand a declarative global destination formula into an absolute path inside the user home.
+ *
+ * @param {object} formula
+ * @param {string} homeDir
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null}
+ */
+export function expandGlobalDestination(formula, homeDir, env = process.env) {
+  if (!formula || formula.kind === 'none') return null;
+  const label = formula.raw || formula.path || formula.kind;
+  if (formula.kind === 'literal') {
+    const relativeRoot = normalizeRelativeRoot(formula.path);
+    const destination = path.resolve(homeDir, ...splitSafeSegments(relativeRoot, label));
+    assertSafeUserPath(homeDir, destination, label);
+    return destination;
+  }
+  if (formula.kind === 'join') {
+    const base = resolveKnownBase(formula.base, homeDir, env, label);
+    const parts = (formula.segments || []).flatMap((segment) => splitSafeSegments(segment, label));
+    const destination = path.resolve(base, ...parts);
+    assertSafeUserPath(homeDir, destination, label);
+    return destination;
+  }
+  if (formula.kind === 'conditional') {
+    const base = resolveKnownBase(formula.base || 'homeDir', homeDir, env, label);
+    for (const option of formula.cases || []) {
+      if (option.probe == null) {
+        return expandGlobalDestination(option.formula, homeDir, env);
+      }
+      const probeParts = splitSafeSegments(option.probe, label);
+      const probePath = path.resolve(base, ...probeParts);
+      if (isInsideHome(homeDir, probePath) && fs.existsSync(probePath)) {
+        return expandGlobalDestination(option.formula, homeDir, env);
+      }
+    }
+    return null;
+  }
+  throw new Error(`invalid destination '${label}'`);
+}
+
+function expandGlobalRelativeRoot(formula, homeDir, env) {
+  try {
+    const absoluteRoot = expandGlobalDestination(formula, homeDir, env);
+    if (!absoluteRoot) return null;
+    const relativeRoot = path.relative(path.resolve(homeDir), absoluteRoot).replace(/\\/g, '/');
+    if (!relativeRoot || relativeRoot.startsWith('..') || path.isAbsolute(relativeRoot)) return null;
+    return { relativeRoot, absoluteRoot };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Group every Agent Host by its Global Installation destination.
+ *
+ * @param {object} params
+ * @returns {object[]}
+ */
+export function listGlobalDestinationGroups({ registry, homeDir, env = process.env }) {
+  const resolvedHome = path.resolve(homeDir);
+  const grouped = new Map();
+
+  for (const host of registry.hosts || []) {
+    const expanded = expandGlobalRelativeRoot(host.destinations?.global, resolvedHome, env);
+    const relativeRoot = expanded?.relativeRoot || '';
+    const key = relativeRoot || `__none__:${host.id}`;
+    if (!grouped.has(key)) {
+      const universal = relativeRoot === UNIVERSAL_PROJECT_DESTINATION;
+      grouped.set(key, {
+        key,
+        relativeRoot,
+        absoluteRoot: expanded?.absoluteRoot || '',
+        universal,
+        selectedByDefault: universal,
+        selectable: Boolean(relativeRoot),
+        hosts: [],
+      });
+    }
+    grouped.get(key).hosts.push({
+      id: host.id,
+      name: host.name,
+      displayName: host.displayName,
+      aliases: [...(host.aliases || [])],
+      detected: detectHost(host, env),
+      relativeRoot,
+    });
+  }
+
+  const groups = [...grouped.values()].sort((a, b) => compareRoots(a.relativeRoot || a.key, b.relativeRoot || b.key));
+  for (const group of groups) {
+    group.hosts.sort((a, b) => compareIds(a.id, b.id));
+  }
+  return groups;
+}
+
+/**
+ * Resolve one skill folder under a Global Installation destination root.
+ *
+ * @param {string} homeDir
+ * @param {string} relativeRoot
+ * @param {string} skillId
+ * @returns {{ destination: string, relativeDestination: string, relativeRoot: string }}
+ */
+export function resolveGlobalSkillPath(homeDir, relativeRoot, skillId) {
+  const resolvedHome = path.resolve(homeDir);
+  const normalizedRoot = normalizeRelativeRoot(relativeRoot);
+  if (!normalizedRoot) {
+    throw new Error(`invalid destination '${relativeRoot}': filesystem root`);
+  }
+  if (isUncPath(relativeRoot) || isUncPath(normalizedRoot)) {
+    throw new Error(`invalid destination '${relativeRoot}': UNC path`);
+  }
+  if (path.isAbsolute(relativeRoot) || path.isAbsolute(normalizedRoot) || /^[A-Za-z]:/.test(normalizedRoot)) {
+    throw new Error(`invalid destination '${relativeRoot}': filesystem root`);
+  }
+  const resolved = resolveSkillPath(resolvedHome, normalizedRoot, skillId);
+  assertSafeUserPath(resolvedHome, resolved.destination, relativeRoot);
+  return resolved;
+}
+
+function normalizeAbs(absolutePath) {
+  const resolved = path.resolve(absolutePath);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function classifyPathPair(a, b) {
+  const left = normalizeAbs(a);
+  const right = normalizeAbs(b);
+  if (left === right) return 'duplicate';
+  const sep = path.sep;
+  if (left.startsWith(right + sep) || right.startsWith(left + sep)) return 'overlap';
+  return null;
+}
+
+/**
+ * Fail-closed checks for selected Project Installation destinations.
+ * Returns human-readable error strings; an empty array means the set is safe.
+ *
+ * @param {object} params
+ * @returns {string[]}
+ */
+export function findDestinationConflicts({ projectRoot, skillIds, selectedRoots, isOwned, classify, resolvePath }) {
+  const errors = [];
+  const normalizedRoots = selectedRoots.map((root) => normalizeRelativeRoot(root));
+  const seenRoots = new Set();
+  const resolve = resolvePath || resolveSkillPath;
+
+  for (const root of normalizedRoots) {
+    if (seenRoots.has(root)) {
+      errors.push(`duplicate resolved destination '${root}'`);
+    }
+    seenRoots.add(root);
+  }
+
+  const resolved = [];
+  for (const root of [...seenRoots]) {
+    for (const skillId of skillIds) {
+      let skillPath;
+      try {
+        skillPath = resolve(projectRoot, root, skillId);
+      } catch (err) {
+        errors.push(err.message);
+        continue;
+      }
+      resolved.push({ root, skillId, ...skillPath });
+    }
+  }
+
+  for (let i = 0; i < resolved.length; i++) {
+    for (let j = i + 1; j < resolved.length; j++) {
+      const kind = classifyPathPair(resolved[i].destination, resolved[j].destination);
+      if (kind === 'duplicate') {
+        errors.push(
+          `duplicate resolved destination '${resolved[i].relativeDestination}'`,
+        );
+      } else if (kind === 'overlap') {
+        errors.push(
+          `overlapping destinations '${resolved[i].relativeDestination}' and '${resolved[j].relativeDestination}'`,
+        );
+      }
+    }
+  }
+
+  for (const item of resolved) {
+    if (process.platform === 'win32' && item.destination.length >= 260) {
+      errors.push(
+        `Destination '${item.destination}' exceeds the Windows path length limit. Installation aborted.`,
+      );
+      continue;
+    }
+    if (!pathExists(item.destination)) continue;
+    const expectedCanonical = resolveSkillPath(projectRoot, UNIVERSAL_PROJECT_DESTINATION, item.skillId);
+    const inspected = inspectManagedPath(item.destination, expectedCanonical.destination);
+    const owned = typeof isOwned === 'function'
+      ? isOwned(item.skillId, item.destination)
+      : false;
+    if (inspected.broken) {
+      errors.push(
+        `Destination '${item.destination}' is a broken link. Installation aborted.`,
+      );
+      continue;
+    }
+    const classified = typeof classify === 'function'
+      ? classify(item.skillId, item.destination)
+      : null;
+    if (classified?.adoptable) continue;
+    if (classified?.migratable) continue;
+    if (inspected.wrongTarget) {
+      errors.push(
+        `Destination '${item.destination}' is a wrong-target link. Installation aborted.`,
+      );
+      continue;
+    }
+    if (!owned) {
+      errors.push(
+        `Destination '${item.destination}' already exists and is not owned by SigmaSkills. Safe adoption is not enabled. Installation aborted.`,
+      );
+    }
+  }
+
+  return errors;
+}