stagent 0.5.0 → 0.6.0

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

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+vi.mock("@/lib/db", () => {
+  const rows: Array<Record<string, unknown>> = [];
+  return {
+    db: {
+      select: vi.fn(() => ({
+        from: vi.fn(() => ({
+          where: vi.fn(() => ({
+            all: vi.fn(() => rows),
+          })),
+        })),
+      })),
+      update: vi.fn(() => ({
+        set: vi.fn(() => ({
+          where: vi.fn(() => ({
+            run: vi.fn(),
+          })),
+        })),
+      })),
+      __rows: rows,
+    },
+  };
+});
+
+vi.mock("@/lib/db/schema", () => ({
+  environmentArtifacts: {
+    scanId: "scan_id",
+    category: "category",
+    id: "id",
+    linkedProfileId: "linked_profile_id",
+  },
+}));
+
+vi.mock("@/lib/agents/profiles/registry", () => ({
+  listAllProfiles: vi.fn(() => []),
+}));
+
+import { linkArtifactsToProfiles } from "../profile-linker";
+import { listAllProfiles } from "@/lib/agents/profiles/registry";
+import { db } from "@/lib/db";
+
+const mockListAllProfiles = listAllProfiles as ReturnType<typeof vi.fn>;
+
+function makeArtifact(id: string, name: string, absPath: string) {
+  return {
+    id,
+    scanId: "scan-1",
+    tool: "claude-code",
+    category: "skill",
+    scope: "user",
+    name,
+    relPath: `skills/${name}/SKILL.md`,
+    absPath,
+    contentHash: "abc123",
+    preview: null,
+    metadata: null,
+    sizeBytes: 100,
+    modifiedAt: Date.now(),
+    linkedProfileId: null,
+    createdAt: new Date(),
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("linkArtifactsToProfiles", () => {
+  it("returns zeros when no skill artifacts exist", () => {
+    // Mock select to return empty array for skill artifacts
+    const mockAll = vi.fn(() => []);
+    (db.select as ReturnType<typeof vi.fn>).mockReturnValue({
+      from: vi.fn(() => ({
+        where: vi.fn(() => ({
+          all: mockAll,
+        })),
+      })),
+    });
+
+    const result = linkArtifactsToProfiles("scan-1");
+    expect(result.linked).toBe(0);
+    expect(result.unlinked).toBe(0);
+    expect(result.unlinkedArtifactIds).toEqual([]);
+  });
+
+  it("links artifacts to matching profiles by directory basename", () => {
+    const artifacts = [
+      makeArtifact("a1", "code-reviewer", "/home/.claude/skills/code-reviewer/SKILL.md"),
+      makeArtifact("a2", "researcher", "/home/.claude/skills/researcher/SKILL.md"),
+    ];
+
+    const mockAll = vi.fn(() => artifacts);
+    const mockRun = vi.fn();
+    (db.select as ReturnType<typeof vi.fn>).mockReturnValue({
+      from: vi.fn(() => ({
+        where: vi.fn(() => ({
+          all: mockAll,
+        })),
+      })),
+    });
+    (db.update as ReturnType<typeof vi.fn>).mockReturnValue({
+      set: vi.fn(() => ({
+        where: vi.fn(() => ({
+          run: mockRun,
+        })),
+      })),
+    });
+
+    mockListAllProfiles.mockReturnValue([
+      { id: "code-reviewer", name: "Code Reviewer" },
+      { id: "researcher", name: "Researcher" },
+    ]);
+
+    const result = linkArtifactsToProfiles("scan-1");
+    expect(result.linked).toBe(2);
+    expect(result.unlinked).toBe(0);
+    expect(db.update).toHaveBeenCalledTimes(2);
+  });
+
+  it("marks unmatched artifacts as unlinked", () => {
+    const artifacts = [
+      makeArtifact("a1", "code-reviewer", "/home/.claude/skills/code-reviewer/SKILL.md"),
+      makeArtifact("a2", "unknown-skill", "/home/.claude/skills/unknown-skill/SKILL.md"),
+    ];
+
+    const mockAll = vi.fn(() => artifacts);
+    const mockRun = vi.fn();
+    (db.select as ReturnType<typeof vi.fn>).mockReturnValue({
+      from: vi.fn(() => ({
+        where: vi.fn(() => ({
+          all: mockAll,
+        })),
+      })),
+    });
+    (db.update as ReturnType<typeof vi.fn>).mockReturnValue({
+      set: vi.fn(() => ({
+        where: vi.fn(() => ({
+          run: mockRun,
+        })),
+      })),
+    });
+
+    mockListAllProfiles.mockReturnValue([
+      { id: "code-reviewer", name: "Code Reviewer" },
+    ]);
+
+    const result = linkArtifactsToProfiles("scan-1");
+    expect(result.linked).toBe(1);
+    expect(result.unlinked).toBe(1);
+    expect(result.unlinkedArtifactIds).toContain("a2");
+  });
+
+  it("handles directory-style absPath (no file extension)", () => {
+    // The scanner sometimes stores the directory, not the file
+    const artifacts = [
+      makeArtifact("a1", "code-reviewer", "/home/.claude/skills/code-reviewer"),
+      makeArtifact("a2", "general", "/home/.claude/skills/general"),
+    ];
+
+    const mockAll = vi.fn(() => artifacts);
+    const mockRun = vi.fn();
+    (db.select as ReturnType<typeof vi.fn>).mockReturnValue({
+      from: vi.fn(() => ({
+        where: vi.fn(() => ({
+          all: mockAll,
+        })),
+      })),
+    });
+    (db.update as ReturnType<typeof vi.fn>).mockReturnValue({
+      set: vi.fn(() => ({
+        where: vi.fn(() => ({
+          run: mockRun,
+        })),
+      })),
+    });
+
+    mockListAllProfiles.mockReturnValue([
+      { id: "code-reviewer", name: "Code Reviewer" },
+      { id: "general", name: "General" },
+    ]);
+
+    const result = linkArtifactsToProfiles("scan-1");
+    expect(result.linked).toBe(2);
+    expect(result.unlinked).toBe(0);
+  });
+});

package/src/lib/environment/auto-scan.ts

@@ -0,0 +1,48 @@
+/**
+ * Auto-scan module.
+ * Triggers environment scans when the last scan is stale (>5 min) or missing.
+ * All functions are synchronous — scanEnvironment() and the DB layer are sync.
+ */
+
+import { getLatestScan, createScan } from "./data";
+import { scanEnvironment } from "./scanner";
+import type { ScanResult } from "./types";
+
+/** Staleness threshold in milliseconds (5 minutes). */
+const STALENESS_MS = 5 * 60 * 1000;
+
+/** Returns true if no scan exists or the latest scan is older than STALENESS_MS. */
+export function shouldRescan(projectId?: string): boolean {
+  const latest = getLatestScan(projectId);
+  if (!latest) return true;
+
+  const scannedAt =
+    latest.scannedAt instanceof Date
+      ? latest.scannedAt.getTime()
+      : new Date(latest.scannedAt).getTime();
+
+  return Date.now() - scannedAt > STALENESS_MS;
+}
+
+/**
+ * Ensures a fresh environment scan exists for the given project directory.
+ * Runs a new scan if the latest one is stale or missing.
+ * Returns the scan result if a new scan was performed, or null if already fresh.
+ *
+ * Errors are caught and logged — auto-scan must never block the caller.
+ */
+export function ensureFreshScan(
+  projectDir: string,
+  projectId?: string
+): ScanResult | null {
+  try {
+    if (!shouldRescan(projectId)) return null;
+
+    const result = scanEnvironment({ projectDir });
+    createScan(result, projectDir, projectId);
+    return result;
+  } catch (error) {
+    console.warn("Auto-scan failed (non-blocking):", error);
+    return null;
+  }
+}

package/src/lib/environment/data.ts

@@ -16,6 +16,7 @@ import {
 } from "@/lib/db/schema";
 import { eq, desc, and, like, sql } from "drizzle-orm";
 import type { ScanResult, ArtifactCategory, ToolPersona, ArtifactScope } from "./types";
+import { linkArtifactsToProfiles } from "./profile-linker";
 
 /** Persist a scan result (scan + all artifacts) in a single transaction. */
 export function createScan(
@@ -70,6 +71,13 @@ export function createScan(
     }
   });
 
+  // Link skill artifacts to their corresponding profiles
+  try {
+    linkArtifactsToProfiles(scanId);
+  } catch (err) {
+    console.warn("[environment] Profile linking failed (non-blocking):", err);
+  }
+
   return db
     .select()
     .from(environmentScans)
@@ -77,6 +85,23 @@ export function createScan(
     .get()!;
 }
 
+/**
+ * Invalidate the latest scan by marking it as stale.
+ * Called after profile mutations to ensure the next ensureFreshScan() re-scans.
+ */
+export function invalidateLatestScan(projectId?: string): void {
+  const latest = getLatestScan(projectId);
+  if (!latest) return;
+
+  // Set scannedAt far enough in the past that shouldRescan() returns true.
+  // The auto-scan staleness window is 5 minutes, so subtracting 10 minutes is safe.
+  const staleTime = new Date(Date.now() - 10 * 60 * 1000);
+  db.update(environmentScans)
+    .set({ scannedAt: staleTime })
+    .where(eq(environmentScans.id, latest.id))
+    .run();
+}
+
 /** Get the most recent completed scan. */
 export function getLatestScan(projectId?: string): EnvironmentScanRow | undefined {
   const conditions = [eq(environmentScans.scanStatus, "completed")];

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));
+}