@soleri/core 9.14.4 → 9.16.7

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

@@ -173,25 +173,11 @@ describe('syncSkillsToClaudeCode — project-local install', () => {
     expect(stat.isSymbolicLink()).toBe(true);
   });
 
-  it('cleans stale global entries with agent-soleri- prefix', async () => {
+  it('does NOT touch ~/.claude/skills/ during project-local install', async () => {
     createSourceSkill('soleri-vault-capture');
-    // Simulate old global duplicates
+    // Global dir has ernesto-soleri-* entries — project-local sync must leave them alone
     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');
@@ -199,7 +185,10 @@ describe('syncSkillsToClaudeCode — project-local install', () => {
       projectRoot: fakeProject,
     });
 
-    expect(result.cleanedGlobal).not.toContain('other-agent-skill');
+    // cleanedGlobal must be empty — project-local sync must not remove global entries
+    expect(result.cleanedGlobal).toHaveLength(0);
+    expect(globalDirExists('ernesto-soleri-vault-capture')).toBe(true);
+    expect(globalDirExists('ernesto-soleri-vault-navigator')).toBe(true);
     expect(globalDirExists('other-agent-skill')).toBe(true);
   });
 });

package/src/skills/global-claude-md.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Unit tests for global ~/.claude/CLAUDE.md scaffolding functions.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { scaffoldGlobalClaudeMd, removeAgentFromGlobalClaudeMd } from './sync-skills.js';
+
+// ---------------------------------------------------------------------------
+// Test harness — redirect homedir() to a temp dir via env override
+// ---------------------------------------------------------------------------
+
+let tmpHome: string;
+let claudeDir: string;
+let claudeMdPath: string;
+
+// We patch the module by temporarily pointing HOME (and USERPROFILE on Windows) at a temp dir
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `soleri-claude-md-test-${Date.now()}`);
+  claudeDir = join(tmpHome, '.claude');
+  claudeMdPath = join(claudeDir, 'CLAUDE.md');
+  mkdirSync(claudeDir, { recursive: true });
+  process.env['HOME'] = tmpHome;
+  process.env['USERPROFILE'] = tmpHome; // Windows: homedir() reads USERPROFILE, not HOME
+});
+
+afterEach(() => {
+  rmSync(tmpHome, { recursive: true, force: true });
+  delete process.env['HOME'];
+  delete process.env['USERPROFILE'];
+});
+
+describe('scaffoldGlobalClaudeMd', () => {
+  it('creates CLAUDE.md with header and agent section when file does not exist', () => {
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto');
+
+    expect(existsSync(claudeMdPath)).toBe(true);
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    expect(content).toContain('# Soleri Engine');
+    expect(content).toContain('<!-- soleri:agent:ernesto start -->');
+    expect(content).toContain('<!-- soleri:agent:ernesto end -->');
+    expect(content).toContain('## Ernesto');
+    expect(content).toContain('ernesto_*');
+  });
+
+  it('replaces existing agent section on second call (idempotent)', () => {
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto');
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto');
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    const startCount = (content.match(/<!-- soleri:agent:ernesto start -->/g) ?? []).length;
+    expect(startCount).toBe(1);
+  });
+
+  it('appends a second agent section without disturbing the first', () => {
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto');
+    scaffoldGlobalClaudeMd('salvador', 'Salvador');
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    expect(content).toContain('<!-- soleri:agent:ernesto start -->');
+    expect(content).toContain('<!-- soleri:agent:ernesto end -->');
+    expect(content).toContain('<!-- soleri:agent:salvador start -->');
+    expect(content).toContain('<!-- soleri:agent:salvador end -->');
+  });
+
+  it('updating one agent does not affect another agent section', () => {
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto');
+    scaffoldGlobalClaudeMd('salvador', 'Salvador');
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto Updated');
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    expect(content).toContain('Ernesto Updated');
+    expect(content).toContain('<!-- soleri:agent:salvador start -->');
+    // Only one ernesto section
+    const count = (content.match(/<!-- soleri:agent:ernesto start -->/g) ?? []).length;
+    expect(count).toBe(1);
+  });
+});
+
+describe('removeAgentFromGlobalClaudeMd', () => {
+  it('is a no-op when CLAUDE.md does not exist', () => {
+    expect(() => removeAgentFromGlobalClaudeMd('ernesto')).not.toThrow();
+  });
+
+  it('removes the agent section', () => {
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto');
+    removeAgentFromGlobalClaudeMd('ernesto');
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    expect(content).not.toContain('<!-- soleri:agent:ernesto start -->');
+    expect(content).not.toContain('<!-- soleri:agent:ernesto end -->');
+  });
+
+  it('only removes the target agent, leaving others intact', () => {
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto');
+    scaffoldGlobalClaudeMd('salvador', 'Salvador');
+    removeAgentFromGlobalClaudeMd('ernesto');
+
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    expect(content).not.toContain('<!-- soleri:agent:ernesto start -->');
+    expect(content).toContain('<!-- soleri:agent:salvador start -->');
+  });
+
+  it('is a no-op when the agent section is not in the file', () => {
+    scaffoldGlobalClaudeMd('ernesto', 'Ernesto');
+    const before = readFileSync(claudeMdPath, 'utf-8');
+    removeAgentFromGlobalClaudeMd('nonexistent');
+    const after = readFileSync(claudeMdPath, 'utf-8');
+    expect(after).toBe(before);
+  });
+});

package/src/skills/sync-skills.ts

@@ -82,7 +82,18 @@ export function discoverSkills(skillsDirs: string[]): SkillEntry[] {
     if (!existsSync(dir)) continue;
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
+      // Follow symlinks — project-local installs use symlinks to source skills
+      const isDir =
+        entry.isDirectory() ||
+        (entry.isSymbolicLink() &&
+          (() => {
+            try {
+              return statSync(join(dir, entry.name)).isDirectory();
+            } catch {
+              return false;
+            }
+          })());
+      if (!isDir) continue;
       const skillPath = join(dir, entry.name, 'SKILL.md');
       if (existsSync(skillPath)) {
         skills.push({ name: entry.name, sourcePath: skillPath });
@@ -248,51 +259,148 @@ export function syncSkillsToClaudeCode(
     }
   }
 
-  // Task 3: Clean up stale global entries when doing a project-local install
-  if (!isGlobal && agentName) {
-    cleanStaleGlobalSkills(agentName, result);
+  // Task 3: (removed — cleanStaleGlobalSkills was wiping valid ernesto-soleri-* entries
+  // that the global sync installed. Task 2 orphan removal handles stale entries during
+  // global sync; project-local sync must not touch ~/.claude/skills/.)
+
+  // Task 4: Scaffold global ~/.claude/CLAUDE.md when doing a global install
+  if (isGlobal && agentName && result.installed.length + result.updated.length > 0) {
+    try {
+      const agentId = agentName.toLowerCase().replace(/\s+/g, '-');
+      const displayName = agentName.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+      scaffoldGlobalClaudeMd(agentId, displayName);
+    } catch {
+      // Best-effort — don't fail the sync
+    }
   }
 
   return result;
 }
 
+// =============================================================================
+// GLOBAL CLAUDE.MD SCAFFOLDING
+// =============================================================================
+
 /**
- * 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/.
+ * Sentinel markers that bracket an agent's section in ~/.claude/CLAUDE.md.
+ * Using HTML comments so they don't render in markdown viewers.
  */
-function cleanStaleGlobalSkills(agentName: string, result: SyncResult): void {
-  const globalSkillsDir = join(homedir(), '.claude', 'skills');
-  if (!existsSync(globalSkillsDir)) return;
+function agentSectionStart(agentId: string): string {
+  return `<!-- soleri:agent:${agentId} start -->`;
+}
+function agentSectionEnd(agentId: string): string {
+  return `<!-- soleri:agent:${agentId} end -->`;
+}
 
-  // Match any agent-prefixed soleri skill: <anything>-soleri-<skillname>
-  // Canonical project-local names look like "soleri-*" (no agent prefix).
-  const stalePattern = /^.+-soleri-.+$/;
+/**
+ * Build the minimal routing section for one agent in the global CLAUDE.md.
+ */
+function buildAgentSection(agentId: string, displayName: string): string {
+  return [
+    agentSectionStart(agentId),
+    `## ${displayName}`,
+    '',
+    `Skills for **${displayName}** are installed globally. Agent-specific instructions`,
+    `are in each project's \`CLAUDE.md\`.`,
+    '',
+    `**Routing:** When you see \`${agentId}_*\` MCP tools, follow the project's \`CLAUDE.md\`.`,
+    agentSectionEnd(agentId),
+  ].join('\n');
+}
 
-  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
-      }
+/**
+ * Create or update ~/.claude/CLAUDE.md to include a routing section for the
+ * given agent. Idempotent — replaces the agent's existing section if present,
+ * appends otherwise. Does not touch other agents' sections.
+ */
+export function scaffoldGlobalClaudeMd(agentId: string, displayName: string): void {
+  const claudeMdPath = join(homedir(), '.claude', 'CLAUDE.md');
+
+  const header = [
+    '# Soleri Engine',
+    '',
+    'Active Soleri agents are installed on this system. Agent-specific instructions',
+    "are in each project's `CLAUDE.md`.",
+    '',
+    '## Routing',
+    '',
+    "- When working in a Soleri agent project, follow that project's `CLAUDE.md`",
+    '- Agent sections below are managed automatically — do not edit manually',
+    '',
+  ].join('\n');
+
+  const newSection = buildAgentSection(agentId, displayName);
+  const start = agentSectionStart(agentId);
+  const end = agentSectionEnd(agentId);
+
+  mkdirSync(join(homedir(), '.claude'), { recursive: true });
+
+  let existing = '';
+  if (existsSync(claudeMdPath)) {
+    existing = readFileSync(claudeMdPath, 'utf-8');
+  }
+
+  let startIdx = existing.indexOf(start);
+  let endIdx = existing.indexOf(end);
+
+  // Migrate legacy sentinel format: <!-- agent:{id}:mode --> / <!-- /agent:{id}:mode -->
+  if (startIdx === -1) {
+    const legacyStart = `<!-- agent:${agentId}:mode -->`;
+    const legacyEnd = `<!-- /agent:${agentId}:mode -->`;
+    const ls = existing.indexOf(legacyStart);
+    const le = existing.indexOf(legacyEnd);
+    if (ls !== -1 && le !== -1) {
+      startIdx = ls;
+      endIdx = le;
+      // Point past the legacy end sentinel so we replace the whole block
+      existing =
+        existing.slice(0, ls) +
+        start +
+        existing.slice(ls + legacyStart.length, le) +
+        end +
+        existing.slice(le + legacyEnd.length);
+      startIdx = existing.indexOf(start);
+      endIdx = existing.indexOf(end);
     }
-  } catch {
-    // Global skills dir unreadable — nothing to clean
   }
+
+  let updated: string;
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace the existing section
+    updated = existing.slice(0, startIdx) + newSection + existing.slice(endIdx + end.length);
+  } else if (existing.length === 0) {
+    // New file — write header + section
+    updated = header + newSection + '\n';
+  } else {
+    // Append to existing file
+    updated = existing.trimEnd() + '\n\n' + newSection + '\n';
+  }
+
+  writeFileSync(claudeMdPath, updated);
+}
+
+/**
+ * Remove an agent's section from ~/.claude/CLAUDE.md.
+ * No-op if the file or section doesn't exist.
+ */
+export function removeAgentFromGlobalClaudeMd(agentId: string): void {
+  const claudeMdPath = join(homedir(), '.claude', 'CLAUDE.md');
+  if (!existsSync(claudeMdPath)) return;
+
+  const content = readFileSync(claudeMdPath, 'utf-8');
+  const start = agentSectionStart(agentId);
+  const end = agentSectionEnd(agentId);
+
+  const startIdx = content.indexOf(start);
+  const endIdx = content.indexOf(end);
+  if (startIdx === -1 || endIdx === -1) return;
+
+  // Remove the section and any leading blank line before it
+  const before = content.slice(0, startIdx).trimEnd();
+  const after = content.slice(endIdx + end.length);
+
+  const updated = (before.length > 0 ? before + '\n' : '') + after.replace(/^\n+/, '\n');
+  writeFileSync(claudeMdPath, updated.trimEnd() + '\n');
 }
 
 // =============================================================================

package/src/skills/validate-skills.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Unit tests for validate-skills — the user-installed SKILL.md validator.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { validateSkillDocs } from './validate-skills.js';
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function createSkillsDir(): string {
+  return mkdtempSync(join(tmpdir(), 'soleri-validate-skills-test-'));
+}
+
+function addSkill(skillsDir: string, skillName: string, content: string): void {
+  const skillDir = join(skillsDir, skillName);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────
+
+describe('validateSkillDocs', () => {
+  let skillsDir: string;
+
+  beforeEach(() => {
+    skillsDir = createSkillsDir();
+  });
+
+  afterEach(() => {
+    rmSync(skillsDir, { recursive: true, force: true });
+  });
+
+  it('returns valid=true and no errors when the skills directory is empty', () => {
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+    expect(result.totalFiles).toBe(0);
+    expect(result.totalExamples).toBe(0);
+  });
+
+  it('returns valid=true for a SKILL.md with no op-call examples', () => {
+    addSkill(
+      skillsDir,
+      'my-skill',
+      `# My Skill
+
+This skill does something useful.
+
+## Usage
+
+Just invoke it.
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+    expect(result.totalFiles).toBe(1);
+    expect(result.totalExamples).toBe(0);
+  });
+
+  it('returns valid=true when op-call params match the schema', () => {
+    addSkill(
+      skillsDir,
+      'capture-skill',
+      `# Capture Skill
+
+Captures knowledge to the vault.
+
+\`\`\`
+YOUR_AGENT_core op:capture_knowledge params: { projectPath: ".", entries: [{ type: "pattern", domain: "testing", title: "Use vitest", description: "Prefer vitest for unit tests", severity: "info" }] }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('reports an error when severity has an invalid enum value', () => {
+    // "suggestion" is not in the capture_knowledge severity enum (valid: critical, warning, info)
+    addSkill(
+      skillsDir,
+      'bad-severity-skill',
+      `# Bad Skill
+
+Example with wrong severity enum:
+
+\`\`\`
+YOUR_AGENT_core op:capture_knowledge params: { entries: [{ type: "pattern", domain: "testing", title: "Test", description: "A test", severity: "suggestion" }] }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+
+    const severityError = result.errors.find(
+      (e) => e.op === 'capture_knowledge' && e.message.toLowerCase().includes('invalid'),
+    );
+    expect(severityError).toBeDefined();
+    expect(severityError!.file).toContain('bad-severity-skill');
+  });
+
+  it('reports an error when scope receives an object instead of a string', () => {
+    // create_plan scope expects z.string() but we pass an object
+    addSkill(
+      skillsDir,
+      'bad-scope-skill',
+      `# Bad Scope Skill
+
+Example with wrong scope type:
+
+\`\`\`
+YOUR_AGENT_core op:create_plan params: { title: "My Plan", objective: "Do something", scope: { included: [] } }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+
+    const scopeError = result.errors.find(
+      (e) => e.op === 'create_plan' && e.message.includes('scope'),
+    );
+    expect(scopeError).toBeDefined();
+    expect(scopeError!.message).toContain('Expected string');
+  });
+
+  it('returns structured error objects with required fields', () => {
+    addSkill(
+      skillsDir,
+      'structured-error-skill',
+      `# Structured Error Skill
+
+\`\`\`
+YOUR_AGENT_core op:capture_knowledge params: { entries: [{ type: "pattern", domain: "testing", title: "Test", description: "A test", severity: "suggestion" }] }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+
+    // "suggestion" is not a valid severity — expect at least one error
+    expect(result.errors.length).toBeGreaterThan(0);
+    const err = result.errors[0];
+    expect(err).toHaveProperty('file');
+    expect(err).toHaveProperty('op');
+    expect(err).toHaveProperty('message');
+    expect(typeof err.file).toBe('string');
+    expect(typeof err.op).toBe('string');
+    expect(typeof err.message).toBe('string');
+  });
+
+  it('includes the file path and op name in each error', () => {
+    addSkill(
+      skillsDir,
+      'named-skill',
+      `# Named Skill
+
+\`\`\`
+YOUR_AGENT_core op:capture_knowledge params: { entries: [{ type: "pattern", domain: "testing", title: "Test", description: "A test", severity: "suggestion" }] }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.errors.length).toBeGreaterThan(0);
+
+    const err = result.errors[0];
+    expect(err.file).toContain('named-skill');
+    expect(err.op).toBe('capture_knowledge');
+  });
+
+  it('builds a schema registry covering core ops', () => {
+    const result = validateSkillDocs(skillsDir);
+    // Registry must cover: capture_knowledge, capture_quick, create_plan, approve_plan, etc.
+    expect(result.registrySize).toBeGreaterThanOrEqual(60);
+  });
+
+  it('handles a skills directory that does not exist', () => {
+    const nonExistentDir = join(skillsDir, 'does-not-exist');
+    const result = validateSkillDocs(nonExistentDir);
+    expect(result.valid).toBe(true);
+    expect(result.totalFiles).toBe(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('counts multiple skill files correctly', () => {
+    addSkill(
+      skillsDir,
+      'skill-one',
+      `# Skill One\n\n\`\`\`\nYOUR_AGENT_core op:capture_quick params: { title: "Test", content: "Content" }\n\`\`\`\n`,
+    );
+    addSkill(skillsDir, 'skill-two', `# Skill Two\n\nNo examples here.\n`);
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.totalFiles).toBe(2);
+  });
+});