@soleri/core 9.6.0 → 9.7.1

package/src/skills/trust-classifier.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { classifyTrust } from './trust-classifier.js';
+import { classifySkills, checkSkillCompatibility, ApprovalRequiredError } from './sync-skills.js';
+import type { SkillEntry } from './sync-skills.js';
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+let testDir: string;
+
+function setup(): string {
+  testDir = join(tmpdir(), `soleri-trust-test-${Date.now()}`);
+  mkdirSync(testDir, { recursive: true });
+  return testDir;
+}
+
+function createSkillDir(parentDir: string, name: string, files: Record<string, string>): string {
+  const dir = join(parentDir, name);
+  mkdirSync(dir, { recursive: true });
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = join(dir, filePath);
+    mkdirSync(join(fullPath, '..'), { recursive: true });
+    writeFileSync(fullPath, content);
+  }
+  return dir;
+}
+
+// =============================================================================
+// TrustClassifier
+// =============================================================================
+
+describe('TrustClassifier', () => {
+  beforeEach(() => setup());
+  afterEach(() => {
+    if (testDir) rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('classifies markdown-only directory', () => {
+    const dir = createSkillDir(testDir, 'md-skill', {
+      'SKILL.md': '---\nname: test\n---\n# Test Skill',
+      'reference.md': '# Reference doc',
+    });
+
+    const result = classifyTrust(dir);
+
+    expect(result.trust).toBe('markdown_only');
+    expect(result.inventory).toHaveLength(2);
+    expect(result.inventory.find((i) => i.path === 'SKILL.md')?.kind).toBe('skill');
+    expect(result.inventory.find((i) => i.path === 'reference.md')?.kind).toBe('reference');
+  });
+
+  it('classifies directory with assets', () => {
+    const dir = createSkillDir(testDir, 'asset-skill', {
+      'SKILL.md': '# Skill',
+      'logo.png': 'fake-png-data',
+      'config.json': '{}',
+    });
+
+    const result = classifyTrust(dir);
+
+    expect(result.trust).toBe('assets');
+    expect(result.inventory.find((i) => i.path === 'logo.png')?.kind).toBe('asset');
+    expect(result.inventory.find((i) => i.path === 'config.json')?.kind).toBe('asset');
+  });
+
+  it('classifies directory with scripts', () => {
+    const dir = createSkillDir(testDir, 'script-skill', {
+      'SKILL.md': '# Skill',
+      'setup.sh': '#!/bin/bash\necho hi',
+      'helper.ts': 'export const x = 1;',
+    });
+
+    const result = classifyTrust(dir);
+
+    expect(result.trust).toBe('scripts');
+    expect(result.inventory.filter((i) => i.kind === 'script')).toHaveLength(2);
+  });
+
+  it('treats .d.ts files as reference, not scripts', () => {
+    const dir = createSkillDir(testDir, 'decl-skill', {
+      'SKILL.md': '# Skill',
+      'types.d.ts': 'export type Foo = string;',
+    });
+
+    const result = classifyTrust(dir);
+
+    expect(result.trust).toBe('markdown_only');
+    expect(result.inventory.find((i) => i.path === 'types.d.ts')?.kind).toBe('reference');
+  });
+
+  it('returns markdown_only for empty directory', () => {
+    const dir = join(testDir, 'empty-skill');
+    mkdirSync(dir, { recursive: true });
+
+    const result = classifyTrust(dir);
+
+    expect(result.trust).toBe('markdown_only');
+    expect(result.inventory).toHaveLength(0);
+  });
+
+  it('returns markdown_only for non-existent directory', () => {
+    const result = classifyTrust(join(testDir, 'nonexistent'));
+
+    expect(result.trust).toBe('markdown_only');
+    expect(result.inventory).toHaveLength(0);
+  });
+
+  it('handles nested directories', () => {
+    const dir = createSkillDir(testDir, 'nested-skill', {
+      'SKILL.md': '# Skill',
+      'sub/helper.js': 'module.exports = {};',
+      'sub/deep/readme.md': '# Deep',
+    });
+
+    const result = classifyTrust(dir);
+
+    expect(result.trust).toBe('scripts');
+    expect(result.inventory).toHaveLength(3);
+    expect(result.inventory.find((i) => i.path === 'sub/helper.js')?.kind).toBe('script');
+  });
+
+  it('skips hidden directories', () => {
+    const dir = createSkillDir(testDir, 'hidden-skill', {
+      'SKILL.md': '# Skill',
+      '.git/config': 'gitconfig',
+    });
+
+    const result = classifyTrust(dir);
+
+    expect(result.inventory.some((i) => i.path.includes('.git'))).toBe(false);
+  });
+});
+
+// =============================================================================
+// checkSkillCompatibility
+// =============================================================================
+
+describe('checkSkillCompatibility', () => {
+  it('returns unknown when no engine version specified', () => {
+    expect(checkSkillCompatibility(undefined, '9.6.0')).toBe('unknown');
+  });
+
+  it('returns unknown when no current version available', () => {
+    expect(checkSkillCompatibility('>=9.0.0', undefined)).toBe('unknown');
+  });
+
+  it('returns compatible for matching version', () => {
+    expect(checkSkillCompatibility('>=9.0.0', '9.6.0')).toBe('compatible');
+  });
+
+  it('returns invalid for incompatible version', () => {
+    expect(checkSkillCompatibility('>=10.0.0', '9.6.0')).toBe('invalid');
+  });
+
+  it('returns compatible for caret range', () => {
+    expect(checkSkillCompatibility('^9.0.0', '9.6.0')).toBe('compatible');
+  });
+
+  it('returns invalid for caret range with major mismatch', () => {
+    expect(checkSkillCompatibility('^10.0.0', '9.6.0')).toBe('invalid');
+  });
+});
+
+// =============================================================================
+// classifySkills (integration with approval gate)
+// =============================================================================
+
+describe('classifySkills', () => {
+  beforeEach(() => setup());
+  afterEach(() => {
+    if (testDir) rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('classifies markdown-only skills without error', () => {
+    createSkillDir(testDir, 'safe-skill', {
+      'SKILL.md': '---\nname: safe\n---\n# Safe Skill',
+    });
+
+    const skills: SkillEntry[] = [
+      { name: 'safe-skill', sourcePath: join(testDir, 'safe-skill', 'SKILL.md') },
+    ];
+
+    const result = classifySkills(skills);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].metadata?.trust).toBe('markdown_only');
+    expect(result[0].metadata?.compatibility).toBe('unknown');
+    expect(result[0].metadata?.source.type).toBe('local');
+  });
+
+  it('throws ApprovalRequiredError for scripts without approval', () => {
+    createSkillDir(testDir, 'risky-skill', {
+      'SKILL.md': '# Risky',
+      'run.sh': '#!/bin/bash\nrm -rf /',
+    });
+
+    const skills: SkillEntry[] = [
+      { name: 'risky-skill', sourcePath: join(testDir, 'risky-skill', 'SKILL.md') },
+    ];
+
+    expect(() => classifySkills(skills)).toThrow(ApprovalRequiredError);
+  });
+
+  it('allows scripts when explicitly approved', () => {
+    createSkillDir(testDir, 'approved-skill', {
+      'SKILL.md': '# Approved',
+      'setup.sh': '#!/bin/bash\necho ok',
+    });
+
+    const skills: SkillEntry[] = [
+      { name: 'approved-skill', sourcePath: join(testDir, 'approved-skill', 'SKILL.md') },
+    ];
+
+    const result = classifySkills(skills, {
+      approvedScripts: new Set(['approved-skill']),
+    });
+
+    expect(result).toHaveLength(1);
+    expect(result[0].metadata?.trust).toBe('scripts');
+  });
+
+  it('reads engine version from SKILL.md frontmatter', () => {
+    createSkillDir(testDir, 'versioned-skill', {
+      'SKILL.md': '---\nname: versioned\nengineVersion: ">=9.0.0"\n---\n# Versioned',
+    });
+
+    const skills: SkillEntry[] = [
+      { name: 'versioned-skill', sourcePath: join(testDir, 'versioned-skill', 'SKILL.md') },
+    ];
+
+    const result = classifySkills(skills, { currentEngineVersion: '9.6.0' });
+
+    expect(result[0].metadata?.engineVersion).toBe('>=9.0.0');
+    expect(result[0].metadata?.compatibility).toBe('compatible');
+  });
+
+  it('detects npm source type from node_modules path', () => {
+    const npmDir = join(testDir, 'node_modules', '@soleri', 'pack-test');
+    mkdirSync(npmDir, { recursive: true });
+    writeFileSync(join(npmDir, 'SKILL.md'), '---\nname: npm-skill\n---\n# NPM Skill');
+
+    const skills: SkillEntry[] = [{ name: 'npm-skill', sourcePath: join(npmDir, 'SKILL.md') }];
+
+    const result = classifySkills(skills);
+
+    expect(result[0].metadata?.source.type).toBe('npm');
+  });
+});

package/src/skills/trust-classifier.ts

@@ -0,0 +1,127 @@
+/**
+ * Trust Classifier — scans a skill directory and determines its trust level.
+ *
+ * Classification rules:
+ * - `.sh`, `.ts`, `.js` files (non-declaration) -> `scripts`
+ * - Non-`.md` files (images, JSON, etc.) -> `assets`
+ * - `.md` files only -> `markdown_only`
+ *
+ * Also builds a full inventory of all files with their classified kind.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, extname, relative } from 'node:path';
+import type { TrustLevel, SkillInventoryItem } from '../packs/types.js';
+
+/** File extensions that indicate executable scripts */
+const SCRIPT_EXTENSIONS = new Set(['.sh', '.ts', '.js', '.mjs', '.cjs', '.py', '.rb', '.bash']);
+
+/** File extensions considered markdown/documentation */
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
+
+/** File extensions for TypeScript declaration files (not executable) */
+const DECLARATION_PATTERN = /\.d\.[mc]?ts$/;
+
+/**
+ * Classify a skill directory and return its trust level and inventory.
+ *
+ * @param dirPath - Absolute path to the skill directory
+ * @returns Trust level and full file inventory
+ */
+export function classifyTrust(dirPath: string): {
+  trust: TrustLevel;
+  inventory: SkillInventoryItem[];
+} {
+  if (!existsSync(dirPath)) {
+    return { trust: 'markdown_only', inventory: [] };
+  }
+
+  const inventory: SkillInventoryItem[] = [];
+  walkDir(dirPath, dirPath, inventory);
+
+  // Determine trust level from inventory
+  const hasScripts = inventory.some((item) => item.kind === 'script');
+  const hasAssets = inventory.some((item) => item.kind === 'asset');
+
+  let trust: TrustLevel;
+  if (hasScripts) {
+    trust = 'scripts';
+  } else if (hasAssets) {
+    trust = 'assets';
+  } else {
+    trust = 'markdown_only';
+  }
+
+  return { trust, inventory };
+}
+
+/**
+ * Namespace object for backward compatibility and namespaced access.
+ * Delegates to standalone `classifyTrust` function.
+ */
+export const TrustClassifier = {
+  classify(dirPath: string): Promise<{ trust: TrustLevel; inventory: SkillInventoryItem[] }> {
+    return Promise.resolve(classifyTrust(dirPath));
+  },
+};
+
+/** Recursively walk a directory and classify all files */
+function walkDir(rootDir: string, currentDir: string, inventory: SkillInventoryItem[]): void {
+  let names: string[];
+  try {
+    names = readdirSync(currentDir);
+  } catch {
+    return;
+  }
+
+  for (const name of names) {
+    const fullPath = join(currentDir, name);
+    let stat;
+    try {
+      stat = statSync(fullPath);
+    } catch {
+      continue;
+    }
+
+    if (stat.isDirectory()) {
+      // Skip hidden directories and node_modules
+      if (name.startsWith('.') || name === 'node_modules') continue;
+      walkDir(rootDir, fullPath, inventory);
+      continue;
+    }
+
+    if (!stat.isFile()) continue;
+
+    const relPath = relative(rootDir, fullPath);
+    const ext = extname(name).toLowerCase();
+    const kind = classifyFile(name, ext);
+
+    inventory.push({ path: relPath, kind });
+  }
+}
+
+/** Classify a single file by its extension and name */
+function classifyFile(fileName: string, ext: string): SkillInventoryItem['kind'] {
+  // SKILL.md is the primary skill definition
+  if (fileName === 'SKILL.md' || fileName === 'skill.md') {
+    return 'skill';
+  }
+
+  // Declaration files are not executable
+  if (DECLARATION_PATTERN.test(fileName)) {
+    return 'reference';
+  }
+
+  // Script files
+  if (SCRIPT_EXTENSIONS.has(ext)) {
+    return 'script';
+  }
+
+  // Markdown files are references
+  if (MARKDOWN_EXTENSIONS.has(ext)) {
+    return 'reference';
+  }
+
+  // Everything else is an asset
+  return 'asset';
+}

package/src/subagent/dispatcher.ts

@@ -19,6 +19,8 @@ import { WorkspaceResolver } from './workspace-resolver.js';
 import { ConcurrencyManager } from './concurrency-manager.js';
 import { OrphanReaper } from './orphan-reaper.js';
 import { aggregate } from './result-aggregator.js';
+import type { GoalRepository } from '../planning/goal-ancestry.js';
+import { GoalAncestry } from '../planning/goal-ancestry.js';
 
 const DEFAULT_TIMEOUT = 300_000; // 5 minutes
 const DEFAULT_MAX_CONCURRENT = 3;
@@ -28,6 +30,8 @@ export interface SubagentDispatcherConfig {
   adapterRegistry: RuntimeAdapterRegistry;
   /** Base directory for git worktree isolation */
   baseDir?: string;
+  /** Optional goal repository for injecting goal ancestry context */
+  goalRepository?: GoalRepository;
 }
 
 export class SubagentDispatcher {
@@ -36,9 +40,13 @@ export class SubagentDispatcher {
   private readonly concurrency = new ConcurrencyManager();
   private readonly reaper: OrphanReaper;
   private readonly adapterRegistry: RuntimeAdapterRegistry;
+  private readonly goalAncestry?: GoalAncestry;
 
   constructor(config: SubagentDispatcherConfig) {
     this.adapterRegistry = config.adapterRegistry;
+    if (config.goalRepository) {
+      this.goalAncestry = new GoalAncestry(config.goalRepository);
+    }
     this.workspace = new WorkspaceResolver(config.baseDir ?? process.cwd());
     this.reaper = new OrphanReaper((taskId) => {
       // On orphan: release the task claim and clean up workspace
@@ -245,13 +253,21 @@ export class SubagentDispatcher {
       };
     }
 
-    // 4. Execute with timeout
+    // 4. Inject goal ancestry context if available
+    let enrichedConfig: Record<string, unknown> = { ...task.config, timeout };
+    const goalId = task.config?.goalId as string | undefined;
+    if (goalId && this.goalAncestry) {
+      enrichedConfig =
+        this.goalAncestry.inject({ config: enrichedConfig }, goalId).config ?? enrichedConfig;
+    }
+
+    // 5. Execute with timeout
     try {
       const resultPromise = adapter.execute({
         runId: `subagent-${task.taskId}-${Date.now()}`,
         prompt: task.prompt,
         workspace,
-        config: { ...task.config, timeout },
+        config: enrichedConfig,
       });
 
       const timeoutPromise = new Promise<never>((_, reject) => {

package/src/update-check.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { buildChangelogUrl, detectBreakingChanges } from './update-check.js';
+
+describe('buildChangelogUrl', () => {
+  it('generates correct URL for a standard version', () => {
+    expect(buildChangelogUrl('1.2.3')).toBe(
+      'https://github.com/adrozdenko/soleri/releases/tag/v1.2.3',
+    );
+  });
+
+  it('generates correct URL for a major version', () => {
+    expect(buildChangelogUrl('2.0.0')).toBe(
+      'https://github.com/adrozdenko/soleri/releases/tag/v2.0.0',
+    );
+  });
+
+  it('generates correct URL for a patch-only bump', () => {
+    expect(buildChangelogUrl('0.1.15')).toBe(
+      'https://github.com/adrozdenko/soleri/releases/tag/v0.1.15',
+    );
+  });
+
+  it('handles single-digit versions', () => {
+    expect(buildChangelogUrl('0.0.1')).toBe(
+      'https://github.com/adrozdenko/soleri/releases/tag/v0.0.1',
+    );
+  });
+});
+
+describe('detectBreakingChanges', () => {
+  it('returns no warnings when versions share the same major and minor delta < 2', () => {
+    const result = detectBreakingChanges('1.2.0', '1.3.0');
+    expect(result.hasBreakingChanges).toBe(false);
+    expect(result.hasMultipleReleases).toBe(false);
+  });
+
+  it('detects breaking changes when major version differs (upgrade)', () => {
+    const result = detectBreakingChanges('1.5.0', '2.0.0');
+    expect(result.hasBreakingChanges).toBe(true);
+    expect(result.hasMultipleReleases).toBe(false);
+  });
+
+  it('detects breaking changes when major version differs (large jump)', () => {
+    const result = detectBreakingChanges('1.0.0', '3.0.0');
+    expect(result.hasBreakingChanges).toBe(true);
+    expect(result.hasMultipleReleases).toBe(false);
+  });
+
+  it('does not flag hasMultipleReleases when major differs', () => {
+    // Even though minor jumped by 2+, breaking change takes priority
+    const result = detectBreakingChanges('1.0.0', '2.5.0');
+    expect(result.hasBreakingChanges).toBe(true);
+    expect(result.hasMultipleReleases).toBe(false);
+  });
+
+  it('detects multiple releases when minor jumps by 2+', () => {
+    const result = detectBreakingChanges('1.0.0', '1.2.0');
+    expect(result.hasBreakingChanges).toBe(false);
+    expect(result.hasMultipleReleases).toBe(true);
+  });
+
+  it('detects multiple releases when minor jumps by 5', () => {
+    const result = detectBreakingChanges('1.1.0', '1.6.0');
+    expect(result.hasBreakingChanges).toBe(false);
+    expect(result.hasMultipleReleases).toBe(true);
+  });
+
+  it('returns no warnings for identical versions', () => {
+    const result = detectBreakingChanges('1.2.3', '1.2.3');
+    expect(result.hasBreakingChanges).toBe(false);
+    expect(result.hasMultipleReleases).toBe(false);
+  });
+
+  it('returns no warnings for patch-only bumps', () => {
+    const result = detectBreakingChanges('1.2.0', '1.2.5');
+    expect(result.hasBreakingChanges).toBe(false);
+    expect(result.hasMultipleReleases).toBe(false);
+  });
+
+  it('handles 0.x versions correctly', () => {
+    const result = detectBreakingChanges('0.1.0', '0.3.0');
+    expect(result.hasBreakingChanges).toBe(false);
+    expect(result.hasMultipleReleases).toBe(true);
+  });
+
+  it('detects breaking change from 0.x to 1.x', () => {
+    const result = detectBreakingChanges('0.9.0', '1.0.0');
+    expect(result.hasBreakingChanges).toBe(true);
+    expect(result.hasMultipleReleases).toBe(false);
+  });
+});

package/src/update-check.ts

@@ -21,6 +21,58 @@ interface CacheEntry {
   latestVersion: string | null;
 }
 
+export interface UpdateInfo {
+  hasUpdate: boolean;
+  currentVersion: string;
+  latestVersion: string | null;
+  changelogUrl: string | null;
+  hasBreakingChanges: boolean;
+  hasMultipleReleases: boolean;
+}
+
+const CHANGELOG_BASE_URL = 'https://github.com/adrozdenko/soleri/releases/tag';
+
+/**
+ * Build a changelog URL for a given version.
+ */
+export function buildChangelogUrl(version: string): string {
+  return `${CHANGELOG_BASE_URL}/v${version}`;
+}
+
+/**
+ * Parse the major version from a semver string (x.y.z).
+ */
+function parseMajor(version: string): number {
+  return Number(version.split('.')[0]) || 0;
+}
+
+/**
+ * Parse the minor version from a semver string (x.y.z).
+ */
+function parseMinor(version: string): number {
+  return Number(version.split('.')[1]) || 0;
+}
+
+/**
+ * Detect breaking changes (major version bump) and multi-release jumps (minor +2).
+ */
+export function detectBreakingChanges(
+  currentVersion: string,
+  latestVersion: string,
+): { hasBreakingChanges: boolean; hasMultipleReleases: boolean } {
+  const currentMajor = parseMajor(currentVersion);
+  const latestMajor = parseMajor(latestVersion);
+  const hasBreakingChanges = latestMajor !== currentMajor;
+
+  const currentMinor = parseMinor(currentVersion);
+  const latestMinor = parseMinor(latestVersion);
+  // Multiple releases: same major but minor jumped by 2+
+  const hasMultipleReleases =
+    !hasBreakingChanges && latestMajor === currentMajor && latestMinor - currentMinor >= 2;
+
+  return { hasBreakingChanges, hasMultipleReleases };
+}
+
 function readCache(): CacheEntry | null {
   try {
     if (!existsSync(CACHE_FILE)) return null;
@@ -75,10 +127,7 @@ export async function checkForUpdate(agentId: string, currentVersion: string): P
   if (cache && Date.now() - cache.checkedAt < CHECK_INTERVAL_MS) {
     // Use cached result
     if (cache.latestVersion && isNewer(currentVersion, cache.latestVersion)) {
-      console.error(
-        `${tag} Update available: @soleri/core ${currentVersion} → ${cache.latestVersion}`,
-      );
-      console.error(`${tag} Run: soleri agent update`);
+      emitUpdateNotifications(tag, currentVersion, cache.latestVersion);
     }
     return;
   }
@@ -101,11 +150,32 @@ export async function checkForUpdate(agentId: string, currentVersion: string): P
     writeCache({ checkedAt: Date.now(), latestVersion });
 
     if (latestVersion && isNewer(currentVersion, latestVersion)) {
-      console.error(`${tag} Update available: @soleri/core ${currentVersion} → ${latestVersion}`);
-      console.error(`${tag} Run: soleri agent update`);
+      emitUpdateNotifications(tag, currentVersion, latestVersion);
     }
   } catch {
     // Network error, timeout, etc. — fail silently
     writeCache({ checkedAt: Date.now(), latestVersion: null });
   }
 }
+
+/**
+ * Emit update notification messages to stderr, including changelog URL
+ * and breaking change / multi-release warnings.
+ */
+function emitUpdateNotifications(tag: string, currentVersion: string, latestVersion: string): void {
+  console.error(`${tag} Update available: @soleri/core ${currentVersion} → ${latestVersion}`);
+  console.error(`${tag} Run: soleri agent update`);
+  console.error(`${tag} Changelog: ${buildChangelogUrl(latestVersion)}`);
+
+  const { hasBreakingChanges, hasMultipleReleases } = detectBreakingChanges(
+    currentVersion,
+    latestVersion,
+  );
+
+  if (hasBreakingChanges) {
+    const latestMajor = latestVersion.split('.')[0];
+    console.error(`${tag} ⚠ Breaking changes in v${latestMajor}.0.0 — see migration guide`);
+  } else if (hasMultipleReleases) {
+    console.error(`${tag} Multiple releases since your version — review changelog`);
+  }
+}