@yancyyu/openhermit 1.6.29 → 1.6.30

package/src/main/services/extensions/skills/SkillScanner.ts

@@ -0,0 +1,117 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { SkillMetadataParser, type SkillRelatedFiles } from './SkillMetadataParser';
+
+import type { ResolvedSkillRoot } from './SkillRootsResolver';
+import type { SkillCatalogItem, SkillDirectoryFlags } from '@shared/types/extensions';
+
+const SKILL_FILE_CANDIDATES = ['SKILL.md', 'Skill.md', 'skill.md'] as const;
+
+export class SkillScanner {
+  constructor(private readonly parser = new SkillMetadataParser()) {}
+
+  async scanRoot(root: ResolvedSkillRoot): Promise<SkillCatalogItem[]> {
+    try {
+      const rootStat = await fs.stat(root.rootPath);
+      if (!rootStat.isDirectory()) return [];
+    } catch {
+      return [];
+    }
+
+    const dirEntries = await fs.readdir(root.rootPath, { withFileTypes: true });
+    const skillDirs = dirEntries.filter((entry) => entry.isDirectory());
+
+    const skills = await Promise.all(
+      skillDirs.map(async (entry) => {
+        const skillDir = path.join(root.rootPath, entry.name);
+        const skillFile = await this.detectSkillFile(skillDir);
+        if (!skillFile) return null;
+
+        const [rawContent, stat, flags] = await Promise.all([
+          fs.readFile(skillFile, 'utf8'),
+          fs.stat(skillFile),
+          this.readFlags(skillDir),
+        ]);
+
+        return this.parser.parseCatalogItem({
+          skillDir,
+          folderName: entry.name,
+          skillFile,
+          rawContent,
+          modifiedAt: stat.mtimeMs,
+          flags,
+          root,
+        });
+      })
+    );
+
+    return skills.filter((entry): entry is SkillCatalogItem => entry !== null);
+  }
+
+  async detectSkillFile(skillDir: string): Promise<string | null> {
+    for (const candidate of SKILL_FILE_CANDIDATES) {
+      const filePath = path.join(skillDir, candidate);
+      try {
+        const stat = await fs.stat(filePath);
+        if (stat.isFile()) return filePath;
+      } catch {
+        // ignore
+      }
+    }
+
+    return null;
+  }
+
+  async readFlags(skillDir: string): Promise<SkillDirectoryFlags> {
+    const [hasScripts, hasReferences, hasAssets] = await Promise.all([
+      this.directoryExists(path.join(skillDir, 'scripts')),
+      this.directoryExists(path.join(skillDir, 'references')),
+      this.directoryExists(path.join(skillDir, 'assets')),
+    ]);
+
+    return { hasScripts, hasReferences, hasAssets };
+  }
+
+  async readRelatedFiles(skillDir: string): Promise<SkillRelatedFiles> {
+    const [referencesFiles, scriptFiles, assetFiles] = await Promise.all([
+      this.listRelativeFiles(path.join(skillDir, 'references')),
+      this.listRelativeFiles(path.join(skillDir, 'scripts')),
+      this.listRelativeFiles(path.join(skillDir, 'assets')),
+    ]);
+
+    return { referencesFiles, scriptFiles, assetFiles };
+  }
+
+  private async listRelativeFiles(targetDir: string, prefix = ''): Promise<string[]> {
+    try {
+      const stat = await fs.stat(targetDir);
+      if (!stat.isDirectory()) return [];
+    } catch {
+      return [];
+    }
+
+    const dirEntries = await fs.readdir(targetDir, { withFileTypes: true });
+    const files = await Promise.all(
+      dirEntries.map(async (entry) => {
+        const relativePath = prefix ? path.join(prefix, entry.name) : entry.name;
+        const fullPath = path.join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+          return this.listRelativeFiles(fullPath, relativePath);
+        }
+        return [relativePath];
+      })
+    );
+
+    return files.flat().sort((a, b) => a.localeCompare(b));
+  }
+
+  private async directoryExists(targetDir: string): Promise<boolean> {
+    try {
+      const stat = await fs.stat(targetDir);
+      return stat.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+}

package/src/main/services/extensions/skills/SkillValidator.ts

@@ -0,0 +1,69 @@
+import { formatSkillRootKind, getSkillAudience } from '@shared/utils/skillRoots';
+
+import type { SkillCatalogItem } from '@shared/types/extensions';
+
+const ROOT_PRECEDENCE: Record<SkillCatalogItem['rootKind'], number> = {
+  hermit: 0,
+  claude: 1,
+  cursor: 2,
+  agents: 3,
+  codex: 4,
+};
+
+export class SkillValidator {
+  annotateCatalog(items: SkillCatalogItem[]): SkillCatalogItem[] {
+    const withDuplicates = this.annotateDuplicateNames(items);
+    return withDuplicates.sort((a, b) => {
+      if (a.isValid !== b.isValid) return a.isValid ? -1 : 1;
+      if (a.scope !== b.scope) return a.scope === 'project' ? -1 : 1;
+      if (a.rootKind !== b.rootKind)
+        return ROOT_PRECEDENCE[a.rootKind] - ROOT_PRECEDENCE[b.rootKind];
+      return a.name.localeCompare(b.name);
+    });
+  }
+
+  private annotateDuplicateNames(items: SkillCatalogItem[]): SkillCatalogItem[] {
+    const itemsByName = new Map<string, SkillCatalogItem[]>();
+    for (const item of items) {
+      const key = `${item.name.trim().toLowerCase()}::${getSkillAudience(item.rootKind)}`;
+      const bucket = itemsByName.get(key) ?? [];
+      bucket.push(item);
+      itemsByName.set(key, bucket);
+    }
+
+    return items.map((item) => {
+      const key = `${item.name.trim().toLowerCase()}::${getSkillAudience(item.rootKind)}`;
+      const duplicates = itemsByName.get(key) ?? [];
+      if (duplicates.length <= 1) {
+        return item;
+      }
+
+      if (item.issues.some((issue) => issue.code === 'duplicate-name')) {
+        return item;
+      }
+
+      const otherLocations = duplicates
+        .filter((candidate) => candidate.id !== item.id)
+        .map((candidate) => `${candidate.skillDir} (${this.formatRootLabel(candidate)})`)
+        .filter((value, index, values) => values.indexOf(value) === index)
+        .join('; ');
+
+      return {
+        ...item,
+        issues: [
+          ...item.issues,
+          {
+            code: 'duplicate-name',
+            message: `Another copy of "${item.name}" exists at: ${otherLocations}. Both entries are shown separately.`,
+            severity: 'warning',
+          },
+        ],
+      };
+    });
+  }
+
+  private formatRootLabel(item: SkillCatalogItem): string {
+    const rootLabel = formatSkillRootKind(item.rootKind);
+    return item.scope === 'project' ? `project ${rootLabel}` : rootLabel;
+  }
+}

package/src/main/services/extensions/skills/SkillsCatalogService.ts

@@ -0,0 +1,92 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { createLogger } from '@shared/utils/logger';
+
+import { SkillMetadataParser } from './SkillMetadataParser';
+import { type ResolvedSkillRoot, SkillRootsResolver } from './SkillRootsResolver';
+import { SkillScanner } from './SkillScanner';
+import { SkillValidator } from './SkillValidator';
+
+import type { SkillCatalogItem, SkillDetail } from '@shared/types/extensions';
+
+const logger = createLogger('Extensions:SkillsCatalog');
+
+export class SkillsCatalogService {
+  constructor(
+    private readonly rootsResolver = new SkillRootsResolver(),
+    private readonly parser = new SkillMetadataParser(),
+    private readonly scanner = new SkillScanner(parser),
+    private readonly validator = new SkillValidator()
+  ) {}
+
+  async list(projectPath?: string): Promise<SkillCatalogItem[]> {
+    const roots = this.rootsResolver.resolve(projectPath);
+    const scannedItems = (
+      await Promise.all(roots.map((root) => this.readSkillsFromRoot(root)))
+    ).flat();
+    return this.validator.annotateCatalog(scannedItems);
+  }
+
+  async getDetail(skillId: string, projectPath?: string): Promise<SkillDetail | null> {
+    const roots = this.rootsResolver.resolve(projectPath);
+    const allowedRoots = new Set(roots.map((root) => path.resolve(root.rootPath)));
+    const normalizedSkillDir = path.resolve(skillId);
+
+    const owningRoot = roots.find((root) => this.isWithinRoot(normalizedSkillDir, root.rootPath));
+    if (!owningRoot || !allowedRoots.has(path.resolve(owningRoot.rootPath))) {
+      return null;
+    }
+
+    const folderName = path.basename(normalizedSkillDir);
+    const skillFile = await this.scanner.detectSkillFile(normalizedSkillDir);
+    if (!skillFile) return null;
+
+    try {
+      const [rawContent, stat, flags, relatedFiles] = await Promise.all([
+        fs.readFile(skillFile, 'utf8'),
+        fs.stat(skillFile),
+        this.scanner.readFlags(normalizedSkillDir),
+        this.scanner.readRelatedFiles(normalizedSkillDir),
+      ]);
+
+      const item = this.parser.parseCatalogItem({
+        skillDir: normalizedSkillDir,
+        folderName,
+        skillFile,
+        rawContent,
+        modifiedAt: stat.mtimeMs,
+        flags,
+        root: owningRoot,
+      });
+
+      return this.parser.parseDetail(item, rawContent, relatedFiles);
+    } catch (error) {
+      logger.warn(`Failed to read skill detail for ${skillId}`, error);
+      return null;
+    }
+  }
+
+  private async readSkillsFromRoot(root: ResolvedSkillRoot): Promise<SkillCatalogItem[]> {
+    try {
+      return await this.scanner.scanRoot(root);
+    } catch (error) {
+      logger.warn(`Failed to scan skills root ${root.rootPath}`, error);
+      return [];
+    }
+  }
+
+  private isWithinRoot(targetPath: string, rootPath: string): boolean {
+    const normalizedTarget = this.normalizeForContainment(targetPath);
+    const normalizedRoot = this.normalizeForContainment(rootPath);
+    const relativePath = path.relative(normalizedRoot, normalizedTarget);
+    return (
+      relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath))
+    );
+  }
+
+  private normalizeForContainment(value: string): string {
+    const resolved = path.resolve(path.normalize(value));
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+  }
+}

package/src/main/services/extensions/skills/SkillsMutationService.ts

@@ -0,0 +1,146 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { isPathWithinRoot, validateFileName } from '@main/utils/pathValidation';
+
+import { SkillImportService } from './SkillImportService';
+import { SkillPlanService } from './SkillPlanService';
+import { SkillRootsResolver } from './SkillRootsResolver';
+import { SkillScaffoldService } from './SkillScaffoldService';
+import { SkillsCatalogService } from './SkillsCatalogService';
+
+import type {
+  SkillDeleteRequest,
+  SkillDetail,
+  SkillImportRequest,
+  SkillReviewPreview,
+  SkillUpsertRequest,
+} from '@shared/types/extensions';
+
+export class SkillsMutationService {
+  constructor(
+    private readonly rootsResolver = new SkillRootsResolver(),
+    private readonly catalogService = new SkillsCatalogService(),
+    private readonly scaffoldService = new SkillScaffoldService(rootsResolver),
+    private readonly importService = new SkillImportService(),
+    private readonly planService = new SkillPlanService()
+  ) {}
+
+  async previewUpsert(request: SkillUpsertRequest): Promise<SkillReviewPreview> {
+    const targetSkillDir = await this.scaffoldService.resolveUpsertTarget(
+      request.scope,
+      request.rootKind,
+      request.projectPath,
+      request.folderName,
+      request.existingSkillId
+    );
+    const files = this.scaffoldService.normalizeDraftFiles(request.files);
+    const plan = await this.planService.buildUpsertPlan(targetSkillDir, files);
+    return plan.preview;
+  }
+
+  async applyUpsert(request: SkillUpsertRequest): Promise<SkillDetail | null> {
+    if (!request.reviewPlanId) {
+      throw new Error('Review the skill changes before saving.');
+    }
+
+    const targetSkillDir = await this.scaffoldService.resolveUpsertTarget(
+      request.scope,
+      request.rootKind,
+      request.projectPath,
+      request.folderName,
+      request.existingSkillId
+    );
+    const files = this.scaffoldService.normalizeDraftFiles(request.files);
+    const plan = await this.planService.buildUpsertPlan(targetSkillDir, files);
+    this.assertReviewedPlanMatches(request.reviewPlanId, plan.preview.planId);
+    await this.planService.applyPlan(plan);
+
+    return this.catalogService.getDetail(targetSkillDir, request.projectPath);
+  }
+
+  async previewImport(request: SkillImportRequest): Promise<SkillReviewPreview> {
+    const { sourceDir, targetSkillDir } = await this.resolveImportTarget(request);
+    const inspection = await this.importService.inspectSourceDir(sourceDir);
+    const plan = await this.planService.buildImportPlan(targetSkillDir, inspection.files);
+    return {
+      ...plan.preview,
+      warnings: [...new Set([...inspection.warnings, ...plan.preview.warnings])],
+    };
+  }
+
+  async applyImport(request: SkillImportRequest): Promise<SkillDetail | null> {
+    if (!request.reviewPlanId) {
+      throw new Error('Review the import changes before saving.');
+    }
+
+    const { sourceDir, targetSkillDir } = await this.resolveImportTarget(request);
+    const inspection = await this.importService.inspectSourceDir(sourceDir);
+    const plan = await this.planService.buildImportPlan(targetSkillDir, inspection.files);
+    this.assertReviewedPlanMatches(request.reviewPlanId, plan.preview.planId);
+    await this.planService.applyPlan(plan);
+
+    return this.catalogService.getDetail(targetSkillDir, request.projectPath);
+  }
+
+  async deleteSkill(request: SkillDeleteRequest): Promise<void> {
+    const skillDir = this.resolveExistingSkill(request.skillId, request.projectPath);
+    await fs.rm(skillDir, { recursive: true, force: true });
+  }
+
+  private async resolveImportTarget(
+    request: SkillImportRequest
+  ): Promise<{ sourceDir: string; targetSkillDir: string }> {
+    const sourceDir = await this.importService.validateSourceDir(request.sourceDir);
+
+    const root = this.resolveWritableRoot(request.scope, request.rootKind, request.projectPath);
+    await fs.mkdir(root.rootPath, { recursive: true });
+
+    const folderName = request.folderName?.trim() || path.basename(sourceDir);
+    const folderValidation = validateFileName(folderName);
+    if (!folderValidation.valid) {
+      throw new Error(folderValidation.error ?? 'Invalid folder name');
+    }
+
+    const targetSkillDir = path.join(root.rootPath, folderName);
+    if (!isPathWithinRoot(targetSkillDir, root.rootPath)) {
+      throw new Error('Import destination is outside the allowed root');
+    }
+
+    return { sourceDir, targetSkillDir };
+  }
+
+  private resolveWritableRoot(
+    scope: SkillUpsertRequest['scope'],
+    rootKind: SkillUpsertRequest['rootKind'],
+    projectPath?: string
+  ) {
+    const roots = this.rootsResolver.resolve(projectPath);
+    const match = roots.find((root) => root.scope === scope && root.rootKind === rootKind);
+    if (!match) {
+      throw new Error('Requested skill root is unavailable');
+    }
+    if (scope === 'project' && !projectPath) {
+      throw new Error('projectPath is required for project-scoped skills');
+    }
+    return match;
+  }
+
+  private resolveExistingSkill(skillId: string, projectPath?: string): string {
+    const normalizedSkillDir = path.resolve(skillId);
+    const roots = this.rootsResolver.resolve(projectPath);
+    const owningRoot = roots.find((root) => isPathWithinRoot(normalizedSkillDir, root.rootPath));
+    if (!owningRoot) {
+      throw new Error('Skill is outside the allowed roots');
+    }
+    return normalizedSkillDir;
+  }
+
+  private assertReviewedPlanMatches(reviewPlanId: string, currentPlanId: string): void {
+    if (reviewPlanId !== currentPlanId) {
+      throw new Error(
+        'The skill files changed after review. Review the latest changes and try again.'
+      );
+    }
+  }
+}

package/src/main/services/extensions/skills/SkillsWatcherService.ts

@@ -0,0 +1,134 @@
+import { isPathWithinRoot } from '@main/utils/pathValidation';
+import { createLogger } from '@shared/utils/logger';
+import { watch } from 'chokidar';
+
+import { SkillRootsResolver } from './SkillRootsResolver';
+
+import type { SkillWatcherEvent } from '@shared/types/extensions';
+import type { FSWatcher } from 'chokidar';
+
+const logger = createLogger('Extensions:SkillsWatcher');
+const WATCHER_DEBOUNCE_MS = 250;
+
+export class SkillsWatcherService {
+  private watcher: FSWatcher | null = null;
+  private subscriptions = new Map<string, string | null>();
+  private pendingEvents = new Map<string, SkillWatcherEvent>();
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private emitChange: ((event: SkillWatcherEvent) => void) | null = null;
+  private nextWatchId = 0;
+
+  constructor(private readonly rootsResolver = new SkillRootsResolver()) {}
+
+  setEmitter(emitChange: (event: SkillWatcherEvent) => void): void {
+    this.emitChange = emitChange;
+  }
+
+  async start(projectPath?: string): Promise<string> {
+    const watchId = `skills-watch-${++this.nextWatchId}`;
+    this.subscriptions.set(watchId, projectPath ?? null);
+    await this.rebuildWatcher();
+    return watchId;
+  }
+
+  async stop(watchId: string): Promise<void> {
+    this.subscriptions.delete(watchId);
+    await this.rebuildWatcher();
+  }
+
+  private async rebuildWatcher(): Promise<void> {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    this.pendingEvents.clear();
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+
+    const roots = [
+      ...new Set(
+        [...this.subscriptions.values()].flatMap((projectPath) =>
+          this.rootsResolver.resolve(projectPath ?? undefined).map((root) => root.rootPath)
+        )
+      ),
+    ];
+
+    if (roots.length === 0) {
+      return;
+    }
+
+    this.watcher = watch(roots, {
+      ignoreInitial: true,
+      ignorePermissionErrors: true,
+      followSymlinks: false,
+      depth: 5,
+      awaitWriteFinish: {
+        stabilityThreshold: 200,
+        pollInterval: 100,
+      },
+    });
+
+    const queue = (type: SkillWatcherEvent['type'], filePath: string): void => {
+      this.enqueueEventsForPath(type, filePath);
+      if (this.flushTimer) return;
+      this.flushTimer = setTimeout(() => {
+        this.flushTimer = null;
+        if (this.emitChange) {
+          for (const event of this.pendingEvents.values()) {
+            this.emitChange(event);
+          }
+        }
+        this.pendingEvents.clear();
+      }, WATCHER_DEBOUNCE_MS);
+    };
+
+    this.watcher.on('add', (filePath) => queue('create', filePath));
+    this.watcher.on('addDir', (filePath) => queue('create', filePath));
+    this.watcher.on('change', (filePath) => queue('change', filePath));
+    this.watcher.on('unlink', (filePath) => queue('delete', filePath));
+    this.watcher.on('unlinkDir', (filePath) => queue('delete', filePath));
+    this.watcher.on('error', (error) => logger.warn('Skills watcher error', error));
+  }
+
+  async stopAll(): Promise<void> {
+    this.subscriptions.clear();
+    await this.rebuildWatcher();
+  }
+
+  private enqueueEventsForPath(type: SkillWatcherEvent['type'], filePath: string): void {
+    const matchedProjectPaths = new Set<string | null>();
+    let matchedUserRoot = false;
+
+    for (const projectPath of this.subscriptions.values()) {
+      const roots = this.rootsResolver.resolve(projectPath ?? undefined);
+      for (const root of roots) {
+        if (!isPathWithinRoot(filePath, root.rootPath)) continue;
+        if (root.scope === 'user') {
+          matchedUserRoot = true;
+        } else {
+          matchedProjectPaths.add(projectPath ?? null);
+        }
+      }
+    }
+
+    if (matchedUserRoot) {
+      this.pendingEvents.set(`user:${type}`, {
+        scope: 'user',
+        projectPath: null,
+        path: filePath,
+        type,
+      });
+    }
+
+    for (const projectPath of matchedProjectPaths) {
+      this.pendingEvents.set(`project:${projectPath ?? 'null'}:${type}`, {
+        scope: 'project',
+        projectPath,
+        path: filePath,
+        type,
+      });
+    }
+  }
+}

package/src/main/services/extensions/state/McpInstallationStateService.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolves installed MCP server state through the active runtime adapter.
+ *
+ * Direct Claude mode reads CLI-managed config files.
+ * Multimodel mode uses the structured `mcp list --json` runtime contract.
+ */
+
+import { createExtensionsRuntimeAdapter } from '../runtime/ExtensionsRuntimeAdapter';
+
+import type { ExtensionsRuntimeAdapter } from '../runtime/ExtensionsRuntimeAdapter';
+import type { InstalledMcpEntry } from '@shared/types/extensions';
+
+const CACHE_TTL_MS = 10_000; // 10 seconds
+
+interface TimedCache<T> {
+  data: T;
+  fetchedAt: number;
+}
+
+export class McpInstallationStateService {
+  private cache = new Map<string, TimedCache<InstalledMcpEntry[]>>();
+
+  constructor(
+    private readonly runtimeAdapter: ExtensionsRuntimeAdapter = createExtensionsRuntimeAdapter()
+  ) {}
+
+  async getInstalled(projectPath?: string): Promise<InstalledMcpEntry[]> {
+    const cacheKey = `${this.runtimeAdapter.flavor}:${projectPath ?? '__user__'}`;
+    const cached = this.cache.get(cacheKey);
+    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+      return cached.data;
+    }
+
+    const entries = await this.runtimeAdapter.getInstalledMcp(projectPath);
+    this.cache.set(cacheKey, { data: entries, fetchedAt: Date.now() });
+    return entries;
+  }
+
+  invalidateCache(): void {
+    this.cache.clear();
+  }
+}