@soleri/core 9.13.0 → 9.14.4

package/src/skills/__tests__/sync-skills.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { mkdirSync, writeFileSync, rmSync, existsSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -9,6 +9,7 @@ import { tmpdir } from 'node:os';
 
 let sourceDir: string;
 let fakeHome: string;
+let fakeProject: string;
 
 function setup(): void {
   const base = join(tmpdir(), `soleri-sync-test-${Date.now()}`);
@@ -19,6 +20,9 @@ function setup(): void {
 
   fakeHome = join(base, 'fake-home');
   mkdirSync(join(fakeHome, '.claude', 'skills'), { recursive: true });
+
+  fakeProject = join(base, 'fake-project');
+  mkdirSync(join(fakeProject, '.claude', 'skills'), { recursive: true });
 }
 
 function teardown(): void {
@@ -40,29 +44,36 @@ function createSourceSkill(name: string, content?: string): string {
 }
 
 /** Create a directory in the fake ~/.claude/skills/ target */
-function createTargetSkillDir(name: string): string {
+function createGlobalSkillDir(name: string): string {
   const dir = join(fakeHome, '.claude', 'skills', name);
   mkdirSync(dir, { recursive: true });
   writeFileSync(join(dir, 'SKILL.md'), `---\nname: ${name}\n---\n\nStale skill.\n`);
   return dir;
 }
 
-function targetSkillsDir(): string {
+function globalSkillsDir(): string {
   return join(fakeHome, '.claude', 'skills');
 }
 
-function targetDirExists(name: string): boolean {
-  return existsSync(join(targetSkillsDir(), name));
+function globalDirExists(name: string): boolean {
+  return existsSync(join(globalSkillsDir(), name));
+}
+
+function projectSkillsDir(): string {
+  return join(fakeProject, '.claude', 'skills');
+}
+
+function projectDirExists(name: string): boolean {
+  return existsSync(join(projectSkillsDir(), name));
 }
 
 // =============================================================================
-// TESTS
+// TESTS — Global install (orphan cleanup)
 // =============================================================================
 
-describe('syncSkillsToClaudeCode — orphan cleanup', () => {
+describe('syncSkillsToClaudeCode — global orphan cleanup', () => {
   beforeEach(() => {
     setup();
-    // Mock homedir() so syncSkillsToClaudeCode writes to our temp directory
     vi.mock('node:os', async (importOriginal) => {
       const original = await importOriginal<typeof import('node:os')>();
       return {
@@ -77,56 +88,118 @@ describe('syncSkillsToClaudeCode — orphan cleanup', () => {
     teardown();
   });
 
-  it('removes orphan directories that match the agent prefix', async () => {
-    // Source has "my-skill", target has stale "test-agent-old-skill"
+  it('removes orphan directories that match the agent prefix (global)', async () => {
     createSourceSkill('my-skill');
-    createTargetSkillDir('test-agent-old-skill');
+    createGlobalSkillDir('test-agent-old-skill');
 
     const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
-    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent', { global: true });
 
-    // The orphan should be reported as removed
     expect(result.removed).toContain('test-agent-old-skill');
-    // The orphan directory should be gone
-    expect(targetDirExists('test-agent-old-skill')).toBe(false);
+    expect(globalDirExists('test-agent-old-skill')).toBe(false);
   });
 
-  it('does NOT remove directories that do not match the agent prefix', async () => {
+  it('does NOT remove directories that do not match the agent prefix (global)', async () => {
     createSourceSkill('my-skill');
-    // "other-agent-skill" does NOT start with "test-agent-"
-    createTargetSkillDir('other-agent-skill');
+    createGlobalSkillDir('other-agent-skill');
 
     const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
-    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent', { global: true });
 
-    // Should still exist — not our prefix
-    expect(targetDirExists('other-agent-skill')).toBe(true);
+    expect(globalDirExists('other-agent-skill')).toBe(true);
     expect(result.removed).not.toContain('other-agent-skill');
   });
 
-  it('does NOT remove a skill directory that was just synced', async () => {
+  it('does NOT remove a skill directory that was just synced (global)', async () => {
     createSourceSkill('active-skill');
-    // This directory matches the prefix AND is a current skill
-    createTargetSkillDir('test-agent-active-skill');
+    createGlobalSkillDir('test-agent-active-skill');
 
     const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
-    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent', { global: true });
 
-    // "active-skill" should be synced (installed/updated/skipped), not removed
     const synced = [...result.installed, ...result.updated, ...result.skipped];
     expect(synced).toContain('active-skill');
     expect(result.removed).not.toContain('test-agent-active-skill');
-    expect(targetDirExists('test-agent-active-skill')).toBe(true);
+    expect(globalDirExists('test-agent-active-skill')).toBe(true);
   });
 
-  it('returns an empty removed array when there are no orphans', async () => {
+  it('returns an empty removed array when there are no orphans (global)', async () => {
     createSourceSkill('only-skill');
 
     const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
-    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent', { global: true });
 
     expect(result.removed).toBeDefined();
     expect(Array.isArray(result.removed)).toBe(true);
     expect(result.removed).toHaveLength(0);
   });
 });
+
+// =============================================================================
+// TESTS — Project-local install (symlinks + canonical names)
+// =============================================================================
+
+describe('syncSkillsToClaudeCode — project-local install', () => {
+  beforeEach(() => {
+    setup();
+    vi.mock('node:os', async (importOriginal) => {
+      const original = await importOriginal<typeof import('node:os')>();
+      return {
+        ...original,
+        homedir: () => fakeHome,
+      };
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    teardown();
+  });
+
+  it('creates symlinks with canonical (unprefixed) names', async () => {
+    createSourceSkill('soleri-vault-capture');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Ernesto', {
+      projectRoot: fakeProject,
+    });
+
+    // Should use canonical name, not "ernesto-soleri-vault-capture"
+    expect(result.installed).toContain('soleri-vault-capture');
+    expect(projectDirExists('soleri-vault-capture')).toBe(true);
+
+    // Should be a symlink
+    const stat = lstatSync(join(projectSkillsDir(), 'soleri-vault-capture'));
+    expect(stat.isSymbolicLink()).toBe(true);
+  });
+
+  it('cleans stale global entries with agent-soleri- prefix', async () => {
+    createSourceSkill('soleri-vault-capture');
+    // Simulate old global duplicates
+    createGlobalSkillDir('ernesto-soleri-vault-capture');
+    createGlobalSkillDir('ernesto-soleri-vault-navigator');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Ernesto', {
+      projectRoot: fakeProject,
+    });
+
+    expect(result.cleanedGlobal).toContain('ernesto-soleri-vault-capture');
+    expect(result.cleanedGlobal).toContain('ernesto-soleri-vault-navigator');
+    expect(globalDirExists('ernesto-soleri-vault-capture')).toBe(false);
+    expect(globalDirExists('ernesto-soleri-vault-navigator')).toBe(false);
+  });
+
+  it('does not clean global entries that do not match agent-soleri- prefix', async () => {
+    createSourceSkill('soleri-vault-capture');
+    createGlobalSkillDir('other-agent-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Ernesto', {
+      projectRoot: fakeProject,
+    });
+
+    expect(result.cleanedGlobal).not.toContain('other-agent-skill');
+    expect(globalDirExists('other-agent-skill')).toBe(true);
+  });
+});

package/src/skills/__tests__/validate-skill-docs.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Unit tests for the SKILL.md validator.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { validateSkillDocs } from '../validate-skill-docs.js';
+
+// Resolve monorepo root from this file's location (packages/core/src/skills/__tests__)
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname2 = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = resolve(__dirname2, '../../../../..');
+
+describe('validateSkillDocs', () => {
+  it('builds a non-empty schema registry', () => {
+    const result = validateSkillDocs(ROOT_DIR);
+    expect(result.registrySize).toBeGreaterThan(100);
+  });
+
+  it('discovers SKILL.md files', () => {
+    const result = validateSkillDocs(ROOT_DIR);
+    expect(result.totalFiles).toBeGreaterThan(10);
+  });
+
+  it('extracts op examples from SKILL.md files', () => {
+    const result = validateSkillDocs(ROOT_DIR);
+    expect(result.totalExamples).toBeGreaterThan(20);
+  });
+
+  it('returns structured error objects with file, line, opName, message', () => {
+    const result = validateSkillDocs(ROOT_DIR);
+    // We expect some errors in the current state of docs
+    if (result.errors.length > 0) {
+      const err = result.errors[0];
+      expect(err).toHaveProperty('file');
+      expect(err).toHaveProperty('line');
+      expect(err).toHaveProperty('opName');
+      expect(err).toHaveProperty('message');
+      expect(typeof err.line).toBe('number');
+      expect(err.line).toBeGreaterThan(0);
+    }
+  });
+
+  it('detects the create_plan scope mismatch', () => {
+    const result = validateSkillDocs(ROOT_DIR);
+    const scopeError = result.errors.find(
+      (e) => e.opName === 'create_plan' && e.message.includes('scope'),
+    );
+    expect(scopeError).toBeDefined();
+    expect(scopeError!.message).toContain('Expected string');
+  });
+
+  it('detects unknown ops', () => {
+    const result = validateSkillDocs(ROOT_DIR);
+    const unknownOps = result.errors.filter((e) => e.message.includes('unknown op'));
+    expect(unknownOps.length).toBeGreaterThan(0);
+  });
+});

package/src/skills/sync-skills.ts

@@ -1,22 +1,29 @@
 /**
  * Skill sync — discovers SKILL.md files in agent skills directories
- * and copies them to ~/.claude/skills/ for Claude Code discovery.
+ * and installs them for Claude Code discovery.
+ *
+ * Default: project-local `.claude/skills/` with canonical (unprefixed) names
+ * and symlinks so source edits propagate automatically.
+ *
+ * Optional `global: true` installs to `~/.claude/skills/` with agent-prefixed
+ * names and file copies (symlinks to project paths don't work globally).
  *
- * Injects agent branding so users know which agent owns the skill.
  * Called automatically at engine startup and by admin_setup_global.
  */
 
 import {
   cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
   rmSync,
   statSync,
+  symlinkSync,
   writeFileSync,
 } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, relative } from 'node:path';
 import { homedir } from 'node:os';
 import type { SkillMetadata, SourceType } from '../packs/types.js';
 import { classifyTrust } from './trust-classifier.js';
@@ -35,6 +42,15 @@ export interface SyncResult {
   skipped: string[];
   failed: string[];
   removed: string[];
+  /** Stale global entries cleaned up during project-local install */
+  cleanedGlobal: string[];
+}
+
+export interface SyncOptions {
+  /** Install globally to ~/.claude/skills/ with agent-prefixed names (default: false) */
+  global?: boolean;
+  /** Project root for project-local installs (default: process.cwd()) */
+  projectRoot?: string;
 }
 
 /** Error thrown when a skill requires approval due to scripts trust level */
@@ -96,42 +112,97 @@ function brandSkillContent(content: string, agentName: string, prefixedName?: st
 }
 
 /**
- * Sync skills from agent directory to ~/.claude/skills/.
- * - New skills are installed with agent branding
- * - Changed skills are overwritten (compared by mtime)
- * - Missing source skills leave target untouched (other agents may own them)
+ * Sync skills to Claude Code's skills directory.
+ *
+ * Default (project-local): installs to `<projectRoot>/.claude/skills/` using
+ * canonical (unprefixed) names and symlinks for automatic propagation.
+ *
+ * Global (`options.global: true`): installs to `~/.claude/skills/` using
+ * agent-prefixed names and file copies (symlinks to project paths won't work).
+ *
+ * Project-local installs also clean up stale `{agent}-soleri-*` entries from
+ * the global `~/.claude/skills/` directory to eliminate duplication.
  */
-export function syncSkillsToClaudeCode(skillsDirs: string[], agentName?: string): SyncResult {
-  const skillsDir = join(homedir(), '.claude', 'skills');
+export function syncSkillsToClaudeCode(
+  skillsDirs: string[],
+  agentName?: string,
+  options: SyncOptions = {},
+): SyncResult {
+  const isGlobal = options.global === true;
+  const projectRoot = options.projectRoot ?? process.cwd();
+
+  const skillsDir = isGlobal
+    ? join(homedir(), '.claude', 'skills')
+    : join(projectRoot, '.claude', 'skills');
+
   const skills = discoverSkills(skillsDirs);
-  const result: SyncResult = { installed: [], updated: [], skipped: [], failed: [], removed: [] };
+  const result: SyncResult = {
+    installed: [],
+    updated: [],
+    skipped: [],
+    failed: [],
+    removed: [],
+    cleanedGlobal: [],
+  };
 
   if (skills.length === 0) return result;
 
   for (const skill of skills) {
-    const prefix = agentName ? `${agentName.toLowerCase().replace(/\s+/g, '-')}-` : '';
-    const skillName = `${prefix}${skill.name}`;
+    // Global installs use agent-prefixed names; local uses canonical names
+    const skillName =
+      isGlobal && agentName
+        ? `${agentName.toLowerCase().replace(/\s+/g, '-')}-${skill.name}`
+        : skill.name;
     const targetDir = join(skillsDir, skillName);
     const targetPath = join(targetDir, 'SKILL.md');
+
     try {
-      const sourceContent = readFileSync(skill.sourcePath, 'utf-8');
-      const branded = agentName
-        ? brandSkillContent(sourceContent, agentName, skillName)
-        : sourceContent;
-
-      if (!existsSync(targetPath)) {
-        mkdirSync(targetDir, { recursive: true });
-        writeFileSync(targetPath, branded);
-        result.installed.push(skill.name);
-      } else {
-        const sourceMtime = statSync(skill.sourcePath).mtimeMs;
-        const targetMtime = statSync(targetPath).mtimeMs;
-        if (sourceMtime > targetMtime) {
+      if (isGlobal) {
+        // Global: copy with branding (original behavior)
+        const sourceContent = readFileSync(skill.sourcePath, 'utf-8');
+        const branded = agentName
+          ? brandSkillContent(sourceContent, agentName, skillName)
+          : sourceContent;
+
+        if (!existsSync(targetPath)) {
+          mkdirSync(targetDir, { recursive: true });
           writeFileSync(targetPath, branded);
-          result.updated.push(skill.name);
+          result.installed.push(skill.name);
         } else {
-          result.skipped.push(skill.name);
+          const sourceMtime = statSync(skill.sourcePath).mtimeMs;
+          const targetMtime = statSync(targetPath).mtimeMs;
+          if (sourceMtime > targetMtime) {
+            writeFileSync(targetPath, branded);
+            result.updated.push(skill.name);
+          } else {
+            result.skipped.push(skill.name);
+          }
         }
+      } else {
+        // Project-local: symlink the skill directory
+        const sourceSkillDir = dirname(skill.sourcePath);
+
+        if (existsSync(targetDir)) {
+          // Check if it's already a symlink pointing to the right place
+          try {
+            const stat = lstatSync(targetDir);
+            if (stat.isSymbolicLink()) {
+              // Already a symlink — skip
+              result.skipped.push(skill.name);
+              continue;
+            }
+          } catch {
+            // lstat failed — remove and recreate
+          }
+          // Not a symlink — remove the copy and replace with symlink
+          rmSync(targetDir, { recursive: true, force: true });
+        }
+
+        mkdirSync(skillsDir, { recursive: true });
+        // Use relative symlink so the project stays portable
+        const relPath = relative(skillsDir, sourceSkillDir);
+        symlinkSync(relPath, targetDir);
+        result.installed.push(skill.name);
       }
     } catch {
       result.failed.push(skill.name);
@@ -142,16 +213,18 @@ export function syncSkillsToClaudeCode(skillsDirs: string[], agentName?: string)
   if (agentName) {
     const prefix = `${agentName.toLowerCase().replace(/\s+/g, '-')}-`;
     const syncedNames = new Set<string>(
-      [...result.installed, ...result.updated, ...result.skipped, ...result.failed].map(
-        (name) => `${prefix}${name}`,
+      [...result.installed, ...result.updated, ...result.skipped, ...result.failed].map((name) =>
+        isGlobal ? `${prefix}${name}` : name,
       ),
     );
 
     try {
       const entries = readdirSync(skillsDir, { withFileTypes: true });
       for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        if (!entry.name.startsWith(prefix)) continue;
+        if (!entry.isDirectory() && !lstatSync(join(skillsDir, entry.name)).isSymbolicLink())
+          continue;
+        const matchPrefix = isGlobal ? entry.name.startsWith(prefix) : true;
+        if (!matchPrefix) continue;
         if (syncedNames.has(entry.name)) continue;
 
         // Orphan detected — stage backup then remove
@@ -160,7 +233,10 @@ export function syncSkillsToClaudeCode(skillsDirs: string[], agentName?: string)
           const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
           const stagingDir = join(homedir(), '.soleri', 'staging', timestamp);
           mkdirSync(stagingDir, { recursive: true });
-          cpSync(orphanPath, join(stagingDir, entry.name), { recursive: true });
+          const orphanStat = lstatSync(orphanPath);
+          if (!orphanStat.isSymbolicLink()) {
+            cpSync(orphanPath, join(stagingDir, entry.name), { recursive: true });
+          }
           rmSync(orphanPath, { recursive: true, force: true });
           result.removed.push(entry.name);
         } catch {
@@ -172,9 +248,53 @@ export function syncSkillsToClaudeCode(skillsDirs: string[], agentName?: string)
     }
   }
 
+  // Task 3: Clean up stale global entries when doing a project-local install
+  if (!isGlobal && agentName) {
+    cleanStaleGlobalSkills(agentName, result);
+  }
+
   return result;
 }
 
+/**
+ * Remove ALL `{agent}-soleri-*` entries from ~/.claude/skills/
+ * to clean up duplicates left by the old global-install behavior.
+ *
+ * Cleans entries from ALL agents, not just the current one — any
+ * `*-soleri-*` entry in the global dir is a stale copy from a previous
+ * global install. Canonical skills now live in project-local .claude/skills/.
+ */
+function cleanStaleGlobalSkills(agentName: string, result: SyncResult): void {
+  const globalSkillsDir = join(homedir(), '.claude', 'skills');
+  if (!existsSync(globalSkillsDir)) return;
+
+  // Match any agent-prefixed soleri skill: <anything>-soleri-<skillname>
+  // Canonical project-local names look like "soleri-*" (no agent prefix).
+  const stalePattern = /^.+-soleri-.+$/;
+
+  try {
+    const entries = readdirSync(globalSkillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (!stalePattern.test(entry.name)) continue;
+
+      const staleDir = join(globalSkillsDir, entry.name);
+      try {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const stagingDir = join(homedir(), '.soleri', 'staging', timestamp);
+        mkdirSync(stagingDir, { recursive: true });
+        cpSync(staleDir, join(stagingDir, entry.name), { recursive: true });
+        rmSync(staleDir, { recursive: true, force: true });
+        result.cleanedGlobal.push(entry.name);
+      } catch {
+        // Best-effort cleanup — don't fail the sync
+      }
+    }
+  } catch {
+    // Global skills dir unreadable — nothing to clean
+  }
+}
+
 // =============================================================================
 // TRUST CLASSIFICATION & SOURCE TRACKING
 // =============================================================================