@zeyue0329/xiaoma-cli 1.0.49 → 1.0.66

package/tools/cli/installers/lib/ide/shared/path-utils.js

@@ -0,0 +1,364 @@
+/**
+ * Path transformation utilities for IDE installer standardization
+ *
+ * Provides utilities to convert hierarchical paths to flat naming conventions.
+ *
+ * DASH-BASED NAMING (new standard):
+ * - Agents: xiaoma-agent-module-name.md (with xiaoma-agent- prefix)
+ * - Workflows/Tasks/Tools: xiaoma-module-name.md
+ *
+ * Example outputs:
+ * - cis/agents/storymaster.md → xiaoma-agent-cis-storymaster.md
+ * - xmc/workflows/plan-project.md → xiaoma-xmc-plan-project.md
+ * - xmc/tasks/create-story.md → xiaoma-xmc-create-story.md
+ * - core/agents/brainstorming.md → xiaoma-agent-brainstorming.md (core agents skip module name)
+ * - standalone/agents/fred.md → xiaoma-agent-standalone-fred.md
+ */
+
+// Type segments - agents are included in naming, others are filtered out
+const TYPE_SEGMENTS = ['workflows', 'tasks', 'tools'];
+const AGENT_SEGMENT = 'agents';
+
+// XiaoMa installation folder name - centralized constant for all installers
+const XiaoMa_FOLDER_NAME = '_xiaoma';
+
+/**
+ * Convert hierarchical path to flat dash-separated name (NEW STANDARD)
+ * Converts: 'xmc', 'agents', 'pm' → 'xiaoma-agent-xmc-pm.md'
+ * Converts: 'xmc', 'workflows', 'correct-course' → 'xiaoma-xmc-correct-course.md'
+ * Converts: 'core', 'agents', 'brainstorming' → 'xiaoma-agent-brainstorming.md' (core agents skip module name)
+ * Converts: 'standalone', 'agents', 'fred' → 'xiaoma-agent-standalone-fred.md'
+ *
+ * @param {string} module - Module name (e.g., 'xmc', 'core', 'standalone')
+ * @param {string} type - Artifact type ('agents', 'workflows', 'tasks', 'tools')
+ * @param {string} name - Artifact name (e.g., 'pm', 'brainstorming')
+ * @returns {string} Flat filename like 'xiaoma-agent-xmc-pm.md' or 'xiaoma-xmc-correct-course.md'
+ */
+function toDashName(module, type, name) {
+  const isAgent = type === AGENT_SEGMENT;
+
+  // For core module, skip the module name: use 'xiaoma-agent-name.md' instead of 'xiaoma-agent-core-name.md'
+  if (module === 'core') {
+    return isAgent ? `xiaoma-agent-${name}.md` : `xiaoma-${name}.md`;
+  }
+  // For standalone module, include 'standalone' in the name
+  if (module === 'standalone') {
+    return isAgent ? `xiaoma-agent-standalone-${name}.md` : `xiaoma-standalone-${name}.md`;
+  }
+
+  // Module artifacts: xiaoma-module-name.md or xiaoma-agent-module-name.md
+  // eslint-disable-next-line unicorn/prefer-string-replace-all -- regex replace is intentional here
+  const dashName = name.replace(/\//g, '-'); // Flatten nested paths
+  return isAgent ? `xiaoma-agent-${module}-${dashName}.md` : `xiaoma-${module}-${dashName}.md`;
+}
+
+/**
+ * Convert relative path to flat dash-separated name
+ * Converts: 'xmc/agents/pm.md' → 'xiaoma-agent-xmc-pm.md'
+ * Converts: 'xmc/agents/tech-writer/tech-writer.md' → 'xiaoma-agent-xmc-tech-writer.md' (uses folder name)
+ * Converts: 'xmc/workflows/correct-course.md' → 'xiaoma-xmc-correct-course.md'
+ * Converts: 'core/agents/brainstorming.md' → 'xiaoma-agent-brainstorming.md' (core agents skip module name)
+ *
+ * @param {string} relativePath - Path like 'xmc/agents/pm.md'
+ * @returns {string} Flat filename like 'xiaoma-agent-xmc-pm.md' or 'xiaoma-brainstorming.md'
+ */
+function toDashPath(relativePath) {
+  if (!relativePath || typeof relativePath !== 'string') {
+    // Return a safe default for invalid input
+    return 'xiaoma-unknown.md';
+  }
+
+  // Strip common file extensions to avoid double extensions in generated filenames
+  // e.g., 'create-story.xml' → 'create-story', 'workflow.md' → 'workflow'
+  const withoutExt = relativePath.replace(/\.(md|yaml|yml|json|xml|toml)$/i, '');
+  const parts = withoutExt.split(/[/\\]/);
+
+  const module = parts[0];
+  const type = parts[1];
+  let name;
+
+  // For agents, if nested in a folder (more than 3 parts), use the folder name only
+  // e.g., 'xmc/agents/tech-writer/tech-writer' → 'tech-writer' (not 'tech-writer-tech-writer')
+  if (type === 'agents' && parts.length > 3) {
+    // Use the folder name (parts[2]) as the name, ignore the file name
+    name = parts[2];
+  } else {
+    // For non-nested or non-agents, join all parts after type
+    name = parts.slice(2).join('-');
+  }
+
+  return toDashName(module, type, name);
+}
+
+/**
+ * Create custom agent dash name
+ * Creates: 'xiaoma-custom-agent-fred-commit-poet.md'
+ *
+ * @param {string} agentName - Custom agent name
+ * @returns {string} Flat filename like 'xiaoma-custom-agent-fred-commit-poet.md'
+ */
+function customAgentDashName(agentName) {
+  return `xiaoma-custom-agent-${agentName}.md`;
+}
+
+/**
+ * Check if a filename uses dash format
+ * @param {string} filename - Filename to check
+ * @returns {boolean} True if filename uses dash format
+ */
+function isDashFormat(filename) {
+  return filename.startsWith('xiaoma-') && filename.includes('-');
+}
+
+/**
+ * Extract parts from a dash-formatted filename
+ * Parses: 'xiaoma-agent-xmc-pm.md' → { prefix: 'xiaoma', module: 'xmc', type: 'agents', name: 'pm' }
+ * Parses: 'xiaoma-xmc-correct-course.md' → { prefix: 'xiaoma', module: 'xmc', type: 'workflows', name: 'correct-course' }
+ * Parses: 'xiaoma-agent-brainstorming.md' → { prefix: 'xiaoma', module: 'core', type: 'agents', name: 'brainstorming' } (core agents)
+ * Parses: 'xiaoma-brainstorming.md' → { prefix: 'xiaoma', module: 'core', type: 'workflows', name: 'brainstorming' } (core workflows)
+ * Parses: 'xiaoma-agent-standalone-fred.md' → { prefix: 'xiaoma', module: 'standalone', type: 'agents', name: 'fred' }
+ * Parses: 'xiaoma-standalone-foo.md' → { prefix: 'xiaoma', module: 'standalone', type: 'workflows', name: 'foo' }
+ *
+ * @param {string} filename - Dash-formatted filename
+ * @returns {Object|null} Parsed parts or null if invalid format
+ */
+function parseDashName(filename) {
+  const withoutExt = filename.replace('.md', '');
+  const parts = withoutExt.split('-');
+
+  if (parts.length < 2 || parts[0] !== 'xiaoma') {
+    return null;
+  }
+
+  // Check if this is an agent file (has 'agent' as second part)
+  const isAgent = parts[1] === 'agent';
+
+  if (isAgent) {
+    // This is an agent file
+    // Format: xiaoma-agent-name (core) or xiaoma-agent-standalone-name or xiaoma-agent-module-name
+    if (parts.length >= 4 && parts[2] === 'standalone') {
+      // Standalone agent: xiaoma-agent-standalone-name
+      return {
+        prefix: parts[0],
+        module: 'standalone',
+        type: 'agents',
+        name: parts.slice(3).join('-'),
+      };
+    }
+    if (parts.length === 3) {
+      // Core agent: xiaoma-agent-name
+      return {
+        prefix: parts[0],
+        module: 'core',
+        type: 'agents',
+        name: parts[2],
+      };
+    } else {
+      // Module agent: xiaoma-agent-module-name
+      return {
+        prefix: parts[0],
+        module: parts[2],
+        type: 'agents',
+        name: parts.slice(3).join('-'),
+      };
+    }
+  }
+
+  // Not an agent file - must be a workflow/tool/task
+  // If only 2 parts (xiaoma-name), it's a core workflow/tool/task
+  if (parts.length === 2) {
+    return {
+      prefix: parts[0],
+      module: 'core',
+      type: 'workflows', // Default to workflows for non-agent core items
+      name: parts[1],
+    };
+  }
+
+  // Check for standalone non-agent: xiaoma-standalone-name
+  if (parts[1] === 'standalone') {
+    return {
+      prefix: parts[0],
+      module: 'standalone',
+      type: 'workflows', // Default to workflows for non-agent standalone items
+      name: parts.slice(2).join('-'),
+    };
+  }
+
+  // Otherwise, it's a module workflow/tool/task (xiaoma-module-name)
+  return {
+    prefix: parts[0],
+    module: parts[1],
+    type: 'workflows', // Default to workflows for non-agent module items
+    name: parts.slice(2).join('-'),
+  };
+}
+
+// ============================================================================
+// LEGACY FUNCTIONS (underscore format) - kept for backward compatibility
+// ============================================================================
+
+/**
+ * Convert hierarchical path to flat underscore-separated name (LEGACY)
+ * @deprecated Use toDashName instead
+ */
+function toUnderscoreName(module, type, name) {
+  const isAgent = type === AGENT_SEGMENT;
+  if (module === 'core') {
+    return isAgent ? `xiaoma_agent_${name}.md` : `xiaoma_${name}.md`;
+  }
+  if (module === 'standalone') {
+    return isAgent ? `xiaoma_agent_standalone_${name}.md` : `xiaoma_standalone_${name}.md`;
+  }
+  return isAgent ? `xiaoma_${module}_agent_${name}.md` : `xiaoma_${module}_${name}.md`;
+}
+
+/**
+ * Convert relative path to flat underscore-separated name (LEGACY)
+ * @deprecated Use toDashPath instead
+ */
+function toUnderscorePath(relativePath) {
+  // Strip common file extensions (same as toDashPath for consistency)
+  const withoutExt = relativePath.replace(/\.(md|yaml|yml|json|xml|toml)$/i, '');
+  const parts = withoutExt.split(/[/\\]/);
+
+  const module = parts[0];
+  const type = parts[1];
+  const name = parts.slice(2).join('_');
+
+  return toUnderscoreName(module, type, name);
+}
+
+/**
+ * Create custom agent underscore name (LEGACY)
+ * @deprecated Use customAgentDashName instead
+ */
+function customAgentUnderscoreName(agentName) {
+  return `xiaoma_custom_${agentName}.md`;
+}
+
+/**
+ * Check if a filename uses underscore format (LEGACY)
+ * @deprecated Use isDashFormat instead
+ */
+function isUnderscoreFormat(filename) {
+  return filename.startsWith('xiaoma_') && filename.includes('_');
+}
+
+/**
+ * Extract parts from an underscore-formatted filename (LEGACY)
+ * @deprecated Use parseDashName instead
+ */
+function parseUnderscoreName(filename) {
+  const withoutExt = filename.replace('.md', '');
+  const parts = withoutExt.split('_');
+
+  if (parts.length < 2 || parts[0] !== 'xiaoma') {
+    return null;
+  }
+
+  const agentIndex = parts.indexOf('agent');
+
+  if (agentIndex !== -1) {
+    if (agentIndex === 1) {
+      // xiaoma_agent_... - check for standalone
+      if (parts.length >= 4 && parts[2] === 'standalone') {
+        return {
+          prefix: parts[0],
+          module: 'standalone',
+          type: 'agents',
+          name: parts.slice(3).join('_'),
+        };
+      }
+      return {
+        prefix: parts[0],
+        module: 'core',
+        type: 'agents',
+        name: parts.slice(agentIndex + 1).join('_'),
+      };
+    } else {
+      return {
+        prefix: parts[0],
+        module: parts[1],
+        type: 'agents',
+        name: parts.slice(agentIndex + 1).join('_'),
+      };
+    }
+  }
+
+  if (parts.length === 2) {
+    return {
+      prefix: parts[0],
+      module: 'core',
+      type: 'workflows',
+      name: parts[1],
+    };
+  }
+
+  // Check for standalone non-agent: xiaoma_standalone_name
+  if (parts[1] === 'standalone') {
+    return {
+      prefix: parts[0],
+      module: 'standalone',
+      type: 'workflows',
+      name: parts.slice(2).join('_'),
+    };
+  }
+
+  return {
+    prefix: parts[0],
+    module: parts[1],
+    type: 'workflows',
+    name: parts.slice(2).join('_'),
+  };
+}
+
+/**
+ * Resolve the skill name for an artifact.
+ * Prefers canonicalId from a xiaoma-skill-manifest.yaml sidecar when available,
+ * falling back to the path-derived name from toDashPath().
+ *
+ * @param {Object} artifact - Artifact object (must have relativePath; may have canonicalId)
+ * @returns {string} Filename like 'xiaoma-create-prd.md' or 'xiaoma-agent-xmc-pm.md'
+ */
+function resolveSkillName(artifact) {
+  if (artifact.canonicalId) {
+    return `${artifact.canonicalId}.md`;
+  }
+  return toDashPath(artifact.relativePath);
+}
+
+// Backward compatibility aliases (colon format was same as underscore)
+const toColonName = toUnderscoreName;
+const toColonPath = toUnderscorePath;
+const customAgentColonName = customAgentUnderscoreName;
+const isColonFormat = isUnderscoreFormat;
+const parseColonName = parseUnderscoreName;
+
+module.exports = {
+  // New standard (dash-based)
+  toDashName,
+  toDashPath,
+  resolveSkillName,
+  customAgentDashName,
+  isDashFormat,
+  parseDashName,
+
+  // Legacy (underscore-based) - kept for backward compatibility
+  toUnderscoreName,
+  toUnderscorePath,
+  customAgentUnderscoreName,
+  isUnderscoreFormat,
+  parseUnderscoreName,
+
+  // Backward compatibility aliases
+  toColonName,
+  toColonPath,
+  customAgentColonName,
+  isColonFormat,
+  parseColonName,
+
+  TYPE_SEGMENTS,
+  AGENT_SEGMENT,
+  XiaoMa_FOLDER_NAME,
+};

package/tools/cli/installers/lib/ide/shared/skill-manifest.js

@@ -0,0 +1,90 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const yaml = require('yaml');
+
+/**
+ * Load xiaoma-skill-manifest.yaml from a directory.
+ * Single-entry manifests (canonicalId at top level) apply to all files in the directory.
+ * Multi-entry manifests are keyed by source filename.
+ * @param {string} dirPath - Directory to check for xiaoma-skill-manifest.yaml
+ * @returns {Object|null} Parsed manifest or null
+ */
+async function loadSkillManifest(dirPath) {
+  const manifestPath = path.join(dirPath, 'xiaoma-skill-manifest.yaml');
+  try {
+    if (!(await fs.pathExists(manifestPath))) return null;
+    const content = await fs.readFile(manifestPath, 'utf8');
+    const parsed = yaml.parse(content);
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (parsed.canonicalId || parsed.type) return { __single: parsed };
+    return parsed;
+  } catch (error) {
+    console.warn(`Warning: Failed to parse xiaoma-skill-manifest.yaml in ${dirPath}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Get the canonicalId for a specific file from a loaded skill manifest.
+ * @param {Object|null} manifest - Loaded manifest (from loadSkillManifest)
+ * @param {string} filename - Source filename to look up (e.g., 'pm.md', 'help.md', 'pm.agent.yaml')
+ * @returns {string} canonicalId or empty string
+ */
+function getCanonicalId(manifest, filename) {
+  if (!manifest) return '';
+  // Single-entry manifest applies to all files in the directory
+  if (manifest.__single) return manifest.__single.canonicalId || '';
+  // Multi-entry: look up by filename directly
+  if (manifest[filename]) return manifest[filename].canonicalId || '';
+  // Fallback: try alternate extensions for compiled files
+  const baseName = filename.replace(/\.(md|xml)$/i, '');
+  const agentKey = `${baseName}.agent.yaml`;
+  if (manifest[agentKey]) return manifest[agentKey].canonicalId || '';
+  const xmlKey = `${baseName}.xml`;
+  if (manifest[xmlKey]) return manifest[xmlKey].canonicalId || '';
+  return '';
+}
+
+/**
+ * Get the artifact type for a specific file from a loaded skill manifest.
+ * @param {Object|null} manifest - Loaded manifest (from loadSkillManifest)
+ * @param {string} filename - Source filename to look up
+ * @returns {string|null} type or null
+ */
+function getArtifactType(manifest, filename) {
+  if (!manifest) return null;
+  // Single-entry manifest applies to all files in the directory
+  if (manifest.__single) return manifest.__single.type || null;
+  // Multi-entry: look up by filename directly
+  if (manifest[filename]) return manifest[filename].type || null;
+  // Fallback: try alternate extensions for compiled files
+  const baseName = filename.replace(/\.(md|xml)$/i, '');
+  const agentKey = `${baseName}.agent.yaml`;
+  if (manifest[agentKey]) return manifest[agentKey].type || null;
+  const xmlKey = `${baseName}.xml`;
+  if (manifest[xmlKey]) return manifest[xmlKey].type || null;
+  return null;
+}
+
+/**
+ * Get the install_to_xiaoma flag for a specific file from a loaded skill manifest.
+ * @param {Object|null} manifest - Loaded manifest (from loadSkillManifest)
+ * @param {string} filename - Source filename to look up
+ * @returns {boolean} install_to_xiaoma value (defaults to true)
+ */
+function getInstallToXiaoma(manifest, filename) {
+  if (!manifest) return true;
+  // Single-entry manifest applies to all files in the directory
+  if (manifest.__single) return manifest.__single.install_to_xiaoma !== false;
+  // Multi-entry: look up by filename directly
+  if (manifest[filename]) return manifest[filename].install_to_xiaoma !== false;
+  // Fallback: try alternate extensions for compiled files
+  const baseName = filename.replace(/\.(md|xml)$/i, '');
+  const agentKey = `${baseName}.agent.yaml`;
+  if (manifest[agentKey]) return manifest[agentKey].install_to_xiaoma !== false;
+  const xmlKey = `${baseName}.xml`;
+  if (manifest[xmlKey]) return manifest[xmlKey].install_to_xiaoma !== false;
+  return true;
+}
+
+module.exports = { loadSkillManifest, getCanonicalId, getArtifactType, getInstallToXiaoma };