stagent 0.4.0 → 0.6.0

package/src/lib/environment/profile-generator.ts

@@ -3,31 +3,57 @@
  */
 
 import { getArtifacts } from "./data";
-import { evaluateRules, type ProfileSuggestion } from "./profile-rules";
+import { evaluateRules, generateTier2Suggestions, type ProfileSuggestion } from "./profile-rules";
 import { listProfiles, createProfile } from "@/lib/agents/profiles/registry";
 import type { ProfileConfig } from "@/lib/validators/profile";
 
-const MIN_CONFIDENCE = 0.6;
+const MIN_CURATED_CONFIDENCE = 0.6;
+
+export interface TieredSuggestions {
+  curated: ProfileSuggestion[];
+  discovered: ProfileSuggestion[];
+}
 
 /**
  * Suggest profiles based on artifacts from a scan.
+ * Returns both curated (Tier 1) and discovered (Tier 2) suggestions.
  * Filters out suggestions that match existing profiles.
  */
-export function suggestProfiles(scanId: string): ProfileSuggestion[] {
+export function suggestProfilesTiered(scanId: string): TieredSuggestions {
   const artifacts = getArtifacts({ scanId });
-  const suggestions = evaluateRules(artifacts);
-
-  // Filter by minimum confidence
-  const confident = suggestions.filter((s) => s.confidence >= MIN_CONFIDENCE);
 
-  // Filter out profiles that already exist (by ID match)
+  // Tier 1: Curated rules
+  const curatedRaw = evaluateRules(artifacts);
   const existing = listProfiles();
   const existingIds = new Set(existing.map((p) => p.id));
   const existingNames = new Set(existing.map((p) => p.name.toLowerCase()));
 
-  return confident.filter(
-    (s) => !existingIds.has(s.ruleId) && !existingNames.has(s.name.toLowerCase())
+  const curated = curatedRaw
+    .filter((s) => s.confidence >= MIN_CURATED_CONFIDENCE)
+    .filter(
+      (s) => !existingIds.has(s.ruleId) && !existingNames.has(s.name.toLowerCase())
+    );
+
+  // Tier 2: Unlinked skill artifacts (those without linkedProfileId)
+  const unlinkedSkills = artifacts.filter(
+    (a) => a.category === "skill" && !a.linkedProfileId
+  );
+  const discovered = generateTier2Suggestions(unlinkedSkills).filter(
+    (s) =>
+      !existingIds.has(s.ruleId) &&
+      !existingIds.has(`env-${s.ruleId}`) &&
+      !existingNames.has(s.name.toLowerCase())
   );
+
+  return { curated, discovered };
+}
+
+/**
+ * Suggest profiles based on artifacts from a scan (legacy flat API).
+ * Returns only curated (Tier 1) suggestions for backward compatibility.
+ */
+export function suggestProfiles(scanId: string): ProfileSuggestion[] {
+  return suggestProfilesTiered(scanId).curated;
 }
 
 /**
@@ -98,4 +124,8 @@ export function createProfileFromSuggestion(
   }
 
   createProfile(config, skillMd);
+
+  // Note: the created profile will have author "stagent-env" which,
+  // combined with the env- prefix on the ID, identifies it as environment-originated.
+  // The profile registry can infer origin from the author field.
 }

package/src/lib/environment/profile-linker.ts

@@ -0,0 +1,143 @@
+/**
+ * Profile-Artifact Linker
+ *
+ * Reconciles environment skill artifacts with profile registry entries.
+ * Runs after each scan to populate linkedProfileId on skill artifacts,
+ * enabling the UI to show which skills are already profiles and which
+ * are candidates for promotion.
+ *
+ * Matching strategy: directory basename under ~/.claude/skills/ is the
+ * shared key between both systems.
+ */
+
+import { db } from "@/lib/db";
+import { environmentArtifacts } from "@/lib/db/schema";
+import { eq, and, isNull } from "drizzle-orm";
+import { listAllProfiles } from "@/lib/agents/profiles/registry";
+import path from "node:path";
+
+export interface LinkResult {
+  linked: number;
+  unlinked: number;
+  unlinkedArtifactIds: string[];
+}
+
+/**
+ * Link skill artifacts from a scan to their corresponding profiles.
+ *
+ * For each skill artifact, extracts the directory basename from its absPath
+ * (e.g., ~/.claude/skills/code-reviewer/SKILL.md → "code-reviewer") and
+ * matches it against profile IDs in the registry.
+ */
+export function linkArtifactsToProfiles(
+  scanId: string,
+  projectDir?: string
+): LinkResult {
+  // Get all skill artifacts from this scan
+  const skillArtifacts = db
+    .select()
+    .from(environmentArtifacts)
+    .where(
+      and(
+        eq(environmentArtifacts.scanId, scanId),
+        eq(environmentArtifacts.category, "skill")
+      )
+    )
+    .all();
+
+  if (skillArtifacts.length === 0) {
+    return { linked: 0, unlinked: 0, unlinkedArtifactIds: [] };
+  }
+
+  // Build a set of known profile IDs
+  const profiles = listAllProfiles(projectDir);
+  const profileIds = new Set(profiles.map((p) => p.id));
+
+  let linked = 0;
+  const unlinkedArtifactIds: string[] = [];
+
+  // Match each skill artifact to a profile by directory basename
+  for (const artifact of skillArtifacts) {
+    const dirBasename = extractProfileId(artifact.absPath);
+    if (!dirBasename) {
+      unlinkedArtifactIds.push(artifact.id);
+      continue;
+    }
+
+    if (profileIds.has(dirBasename)) {
+      // Link this artifact to the profile
+      db.update(environmentArtifacts)
+        .set({ linkedProfileId: dirBasename })
+        .where(eq(environmentArtifacts.id, artifact.id))
+        .run();
+      linked++;
+    } else {
+      unlinkedArtifactIds.push(artifact.id);
+    }
+  }
+
+  return {
+    linked,
+    unlinked: unlinkedArtifactIds.length,
+    unlinkedArtifactIds,
+  };
+}
+
+/**
+ * Extract the profile ID from a skill artifact's absolute path.
+ *
+ * The scanner stores absPath as either:
+ *   - The directory: ~/.claude/skills/code-reviewer
+ *   - Or the file:   ~/.claude/skills/code-reviewer/SKILL.md
+ *
+ * The profile ID is the skill directory basename ("code-reviewer").
+ */
+function extractProfileId(absPath: string): string | null {
+  // The absPath may point to the skill directory itself or a file within it.
+  // Use the basename of the path first — if it looks like a directory name
+  // (no extension), use it directly. Otherwise, use the parent directory.
+  const basename = path.basename(absPath);
+
+  // If basename has a file extension (e.g., "SKILL.md"), go up one level
+  if (basename.includes(".")) {
+    const parentBasename = path.basename(path.dirname(absPath));
+    if (parentBasename === "skills" || parentBasename === ".claude") {
+      return null;
+    }
+    return parentBasename;
+  }
+
+  // basename is a directory name — skip if it's the skills root
+  if (basename === "skills" || basename === ".claude") {
+    return null;
+  }
+
+  return basename;
+}
+
+/**
+ * Get all unlinked skill artifact IDs for a scan.
+ * Useful for the suggestion engine to generate Tier 2 suggestions.
+ */
+export function getUnlinkedSkillArtifacts(
+  scanId: string
+): Array<{ id: string; name: string; absPath: string; contentHash: string; preview: string | null; metadata: string | null }> {
+  return db
+    .select({
+      id: environmentArtifacts.id,
+      name: environmentArtifacts.name,
+      absPath: environmentArtifacts.absPath,
+      contentHash: environmentArtifacts.contentHash,
+      preview: environmentArtifacts.preview,
+      metadata: environmentArtifacts.metadata,
+    })
+    .from(environmentArtifacts)
+    .where(
+      and(
+        eq(environmentArtifacts.scanId, scanId),
+        eq(environmentArtifacts.category, "skill"),
+        isNull(environmentArtifacts.linkedProfileId)
+      )
+    )
+    .all();
+}

package/src/lib/environment/profile-rules.ts

@@ -1,6 +1,11 @@
 /**
  * Profile suggestion rules engine.
  * Maps artifact clusters to agent profile suggestions.
+ *
+ * Two-tier system:
+ * - Tier 1 (Curated): 6 hardcoded rules with high confidence (0.65-1.0)
+ * - Tier 2 (Discovered): Any unlinked skill artifact with valid SKILL.md
+ *   frontmatter becomes a generic suggestion at confidence 0.5
  */
 
 import type { EnvironmentArtifactRow } from "@/lib/db/schema";
@@ -22,11 +27,14 @@ export interface ProfileRule {
   tags: string[];
 }
 
+export type SuggestionTier = "curated" | "discovered";
+
 export interface ProfileSuggestion {
   ruleId: string;
   name: string;
   description: string;
   confidence: number;
+  tier: SuggestionTier;
   matchedArtifacts: Array<{ id: string; name: string; category: string }>;
   suggestedTools: string[];
   systemPrompt: string;
@@ -190,6 +198,7 @@ export function evaluateRules(
       name: rule.name,
       description: rule.description,
       confidence,
+      tier: "curated",
       matchedArtifacts: matched,
       suggestedTools: rule.suggestedTools,
       systemPrompt: rule.systemPromptTemplate,
@@ -199,3 +208,90 @@ export function evaluateRules(
 
   return suggestions.sort((a, b) => b.confidence - a.confidence);
 }
+
+// ---------------------------------------------------------------------------
+// Tier 2: Auto-discovered suggestions from unlinked skill artifacts
+// ---------------------------------------------------------------------------
+
+const TIER2_CONFIDENCE = 0.5;
+
+/** Parse YAML frontmatter from SKILL.md preview content. */
+function parseFrontmatter(preview: string | null): { name?: string; description?: string } {
+  if (!preview) return {};
+  const match = preview.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const result: { name?: string; description?: string } = {};
+  const lines = match[1].split("\n");
+  for (const line of lines) {
+    const nameMatch = line.match(/^name:\s*(.+)/);
+    if (nameMatch) result.name = nameMatch[1].trim();
+    const descMatch = line.match(/^description:\s*(.+)/);
+    if (descMatch) result.description = descMatch[1].trim();
+  }
+  return result;
+}
+
+/**
+ * Generate Tier 2 (discovered) suggestions from unlinked skill artifacts.
+ *
+ * Any skill artifact that:
+ * 1. Has no linked profile (linkedProfileId is null)
+ * 2. Has parseable SKILL.md frontmatter with at least a name
+ *
+ * becomes a suggestion with confidence 0.5 (below the Tier 1 minimum of 0.6).
+ */
+export function generateTier2Suggestions(
+  unlinkedArtifacts: EnvironmentArtifactRow[]
+): ProfileSuggestion[] {
+  const suggestions: ProfileSuggestion[] = [];
+
+  for (const artifact of unlinkedArtifacts) {
+    if (artifact.category !== "skill") continue;
+
+    // Try to extract metadata from the artifact's preview or metadata field
+    let name: string | undefined;
+    let description: string | undefined;
+
+    // Parse from metadata (JSON) if available
+    if (artifact.metadata) {
+      try {
+        const meta = JSON.parse(artifact.metadata);
+        name = meta.name;
+        description = meta.description;
+      } catch {
+        // Fall through to preview parsing
+      }
+    }
+
+    // Fall back to preview (first 200 chars of SKILL.md) frontmatter parsing
+    if (!name) {
+      const fm = parseFrontmatter(artifact.preview);
+      name = fm.name;
+      description = fm.description;
+    }
+
+    // If we still don't have a name, use the artifact name (directory basename)
+    if (!name) {
+      name = artifact.name
+        .replace(/-/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+    }
+
+    suggestions.push({
+      ruleId: `discovered-${artifact.name}`,
+      name,
+      description: description ?? `Discovered skill: ${artifact.name}`,
+      confidence: TIER2_CONFIDENCE,
+      tier: "discovered",
+      matchedArtifacts: [
+        { id: artifact.id, name: artifact.name, category: artifact.category },
+      ],
+      suggestedTools: ["Read", "Grep", "Glob", "Bash"],
+      systemPrompt: description ?? `You are a ${name} specialist.`,
+      tags: artifact.name.split("-").filter((t) => t.length > 2),
+    });
+  }
+
+  return suggestions.sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/lib/import/dedup.ts

@@ -0,0 +1,149 @@
+/**
+ * Deduplication engine for profile import.
+ * Three-tier matching: exact ID, name match, content similarity.
+ */
+
+import type { ProfileConfig } from "@/lib/validators/profile";
+import type { AgentProfile } from "@/lib/agents/profiles/types";
+
+export interface DedupResult {
+  candidate: ProfileConfig;
+  candidateSkillMd: string;
+  status: "new" | "exact-match" | "near-match";
+  matchedProfile?: AgentProfile;
+  matchReason?: string;
+  similarity?: number;
+}
+
+/** Common stop words to exclude from keyword extraction. */
+const STOP_WORDS = new Set([
+  "the", "and", "for", "are", "but", "not", "you", "all", "can", "had",
+  "her", "was", "one", "our", "out", "has", "have", "that", "this", "with",
+  "from", "they", "been", "will", "each", "make", "like", "into", "them",
+  "some", "when", "what", "your", "should", "would", "could", "about",
+  "which", "their", "other", "than", "then", "more", "also", "been",
+  "only", "must", "does", "here", "just", "over", "such", "after",
+  "before", "between", "through", "where", "these", "those", "being",
+  "using", "ensure", "every", "following", "include",
+]);
+
+/** Extract meaningful keywords from text. */
+function extractKeywords(text: string, limit = 20): Set<string> {
+  const words = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 3 && w.length < 30 && !STOP_WORDS.has(w));
+
+  // Count frequency
+  const freq = new Map<string, number>();
+  for (const word of words) {
+    freq.set(word, (freq.get(word) ?? 0) + 1);
+  }
+
+  // Sort by frequency, take top N
+  const sorted = Array.from(freq.entries())
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([word]) => word);
+
+  return new Set(sorted);
+}
+
+/** Jaccard similarity between two sets. */
+function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersection = 0;
+  for (const item of a) {
+    if (b.has(item)) intersection++;
+  }
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/** Tag overlap ratio (how many of candidate's tags match existing). */
+function tagOverlap(candidateTags: string[], existingTags: string[]): number {
+  if (candidateTags.length === 0) return 0;
+  const existingSet = new Set(existingTags.map((t) => t.toLowerCase()));
+  const matches = candidateTags.filter((t) => existingSet.has(t.toLowerCase()));
+  return matches.length / candidateTags.length;
+}
+
+/**
+ * Check a batch of candidate profiles against all existing profiles for duplicates.
+ */
+export function checkDuplicates(
+  candidates: Array<{ config: ProfileConfig; skillMd: string }>,
+  existingProfiles: AgentProfile[]
+): DedupResult[] {
+  return candidates.map(({ config, skillMd }) => {
+    // Tier 1: Exact ID match
+    const idMatch = existingProfiles.find(
+      (p) => p.id === config.id
+    );
+    if (idMatch) {
+      return {
+        candidate: config,
+        candidateSkillMd: skillMd,
+        status: "exact-match" as const,
+        matchedProfile: idMatch,
+        matchReason: `Same ID: "${config.id}"`,
+        similarity: 1.0,
+      };
+    }
+
+    // Tier 2: Name match (case-insensitive)
+    const nameMatch = existingProfiles.find(
+      (p) => p.name.toLowerCase() === config.name.toLowerCase()
+    );
+    if (nameMatch) {
+      return {
+        candidate: config,
+        candidateSkillMd: skillMd,
+        status: "exact-match" as const,
+        matchedProfile: nameMatch,
+        matchReason: `Same name: "${config.name}"`,
+        similarity: 1.0,
+      };
+    }
+
+    // Tier 3: Content similarity via keyword Jaccard + tag overlap
+    const candidateKeywords = extractKeywords(skillMd);
+    let bestSimilarity = 0;
+    let bestMatch: AgentProfile | undefined;
+
+    for (const existing of existingProfiles) {
+      const existingKeywords = extractKeywords(existing.skillMd);
+      let similarity = jaccard(candidateKeywords, existingKeywords);
+
+      // Boost by tag overlap
+      const overlap = tagOverlap(config.tags, existing.tags);
+      if (overlap > 0.5) {
+        similarity = Math.min(1.0, similarity + 0.1);
+      }
+
+      if (similarity > bestSimilarity) {
+        bestSimilarity = similarity;
+        bestMatch = existing;
+      }
+    }
+
+    if (bestSimilarity > 0.6 && bestMatch) {
+      return {
+        candidate: config,
+        candidateSkillMd: skillMd,
+        status: "near-match" as const,
+        matchedProfile: bestMatch,
+        matchReason: `Similar content to "${bestMatch.name}" (${Math.round(bestSimilarity * 100)}%)`,
+        similarity: bestSimilarity,
+      };
+    }
+
+    // No match found
+    return {
+      candidate: config,
+      candidateSkillMd: skillMd,
+      status: "new" as const,
+    };
+  });
+}