selftune 0.2.30 → 0.2.32

package/cli/selftune/orchestrate/finalize.ts

@@ -16,6 +16,8 @@ interface OrchestrateFinalTotals {
   watched: number;
   skipped: number;
   autoGraded: number;
+  packageSearched: number;
+  packageImproved: number;
   freshlyWatchedSkills: string[];
 }
 
@@ -27,6 +29,8 @@ export interface FinalizeOrchestrateRunInput {
   dryRun: boolean;
   approvalMode: "auto" | "review";
   autoGradedCount: number;
+  packageSearched: number;
+  packageImproved: number;
   freshlyWatchedSkills: string[];
   pendingSignals: ImprovementSignalRecord[];
   elapsedMs: number;
@@ -36,6 +40,8 @@ function buildFinalTotals(
   skills: SkillStatus[],
   candidates: SkillAction[],
   autoGradedCount: number,
+  packageSearched: number,
+  packageImproved: number,
   freshlyWatchedSkills: string[],
 ): OrchestrateFinalTotals {
   return {
@@ -50,6 +56,8 @@ function buildFinalTotals(
       freshlyWatchedSkills.length,
     skipped: candidates.filter((candidate) => candidate.action === "skip").length,
     autoGraded: autoGradedCount,
+    packageSearched,
+    packageImproved,
     freshlyWatchedSkills,
   };
 }
@@ -63,6 +71,8 @@ export function finalizeOrchestrateRun(input: FinalizeOrchestrateRunInput): Orch
     dryRun,
     approvalMode,
     autoGradedCount,
+    packageSearched,
+    packageImproved,
     freshlyWatchedSkills,
     pendingSignals,
     elapsedMs,
@@ -72,6 +82,8 @@ export function finalizeOrchestrateRun(input: FinalizeOrchestrateRunInput): Orch
     statusResult.skills,
     candidates,
     autoGradedCount,
+    packageSearched,
+    packageImproved,
     freshlyWatchedSkills,
   );
 
@@ -106,6 +118,8 @@ export function finalizeOrchestrateRun(input: FinalizeOrchestrateRunInput): Orch
     watched: finalTotals.watched,
     skipped: finalTotals.skipped,
     auto_graded: finalTotals.autoGraded,
+    package_searched: finalTotals.packageSearched,
+    package_improved: finalTotals.packageImproved,
     skill_actions: candidates.map(
       (candidate): OrchestrateRunSkillAction => ({
         skill: candidate.skill,

package/cli/selftune/orchestrate/plan.ts

@@ -2,6 +2,22 @@ import type { CandidateContext, SkillAction } from "../orchestrate.js";
 import type { SkillStatus } from "../status.js";
 import type { EvolutionAuditEntry } from "../types.js";
 
+/**
+ * Determines whether a skill should use package search instead of standard
+ * evolution. Returns true when the skill has package-level evidence:
+ * a frontier candidate exists or a canonical evaluation record is present.
+ *
+ * This gates the package-search path so only skills with sufficient
+ * package-level signal enter the bounded search flow.
+ */
+export function shouldSelectPackageSearch(skill: SkillStatus, context: CandidateContext): boolean {
+  // Package search requires that the candidate context carries a
+  // packageFrontierSkills set (populated from package-candidate-state).
+  // When present and the skill is listed, we route through package search.
+  if (!context.packageFrontierSkills) return false;
+  return context.packageFrontierSkills.has(skill.name);
+}
+
 /** Candidate selection criteria. */
 const CANDIDATE_STATUSES = new Set(["CRITICAL", "WARNING", "UNGRADED"]);
 
@@ -109,18 +125,19 @@ export function selectCandidates(skills: SkillStatus[], options: CandidateContex
       continue;
     }
 
+    const action = shouldSelectPackageSearch(skill, options) ? "package-search" : "evolve";
     actions.push({
       skill: skill.name,
-      action: "evolve",
+      action,
       reason: `status=${skill.status}, passRate=${skill.passRate !== null ? `${(skill.passRate * 100).toFixed(0)}%` : "—"}, missed=${skill.missedQueries}, trend=${skill.trend}`,
     });
   }
 
-  let evolveCount = 0;
+  let activeCount = 0;
   for (const action of actions) {
-    if (action.action === "evolve") {
-      evolveCount++;
-      if (evolveCount > options.maxSkills) {
+    if (action.action === "evolve" || action.action === "package-search") {
+      activeCount++;
+      if (activeCount > options.maxSkills) {
         action.action = "skip";
         action.reason = `capped by --max-skills ${options.maxSkills}`;
       }

package/cli/selftune/orchestrate/prepare.ts

@@ -1,5 +1,5 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import {
   buildDefaultGradingOutputPath,
@@ -7,8 +7,11 @@ import {
   gradeSession,
   resolveLatestSessionForSkill,
 } from "../grading/grade-session.js";
+import { selectAcceptedPackageFrontierCandidate } from "../create/package-candidate-state.js";
 import { writeGradingResultToDb } from "../localdb/direct-write.js";
 import { createDefaultSyncOptions } from "../sync.js";
+import { getDb } from "../localdb/db.js";
+import { readCanonicalPackageEvaluationArtifact } from "../testing-readiness.js";
 import type {
   ImprovementSignalRecord,
   QueryLogRecord,
@@ -17,7 +20,7 @@ import type {
 } from "../types.js";
 import { readExcerpt } from "../utils/transcript.js";
 import type { OrchestrateOptions, SkillAction } from "../orchestrate.js";
-import { selectCandidates } from "./plan.js";
+import { MIN_CANDIDATE_EVIDENCE, selectCandidates } from "./plan.js";
 import { groupSignalsBySkill, readPendingSignals } from "./signals.js";
 import type { ResolvedOrchestrateRuntime } from "./runtime.js";
 
@@ -33,6 +36,50 @@ export interface PreparedOrchestrateRun {
   autoGradedCount: number;
 }
 
+export function collectPackageSearchEligibleSkills(
+  skillNames: string[],
+  options?: {
+    db?: import("bun:sqlite").Database;
+    resolveSkillPath?: (skillName: string) => string | undefined;
+  },
+): Set<string> {
+  const eligible = new Set<string>();
+
+  for (const skillName of skillNames) {
+    if (
+      selectAcceptedPackageFrontierCandidate(skillName) != null ||
+      readCanonicalPackageEvaluationArtifact(skillName) != null
+    ) {
+      eligible.add(skillName);
+      continue;
+    }
+
+    // Second tier: skills with a draft package and sufficient grading evidence
+    if (!options?.db || !options?.resolveSkillPath) continue;
+
+    const skillPath = options.resolveSkillPath(skillName);
+    if (!skillPath) continue;
+
+    const hasDraft = existsSync(join(dirname(skillPath), "selftune.create.json"));
+    if (!hasDraft) continue;
+
+    try {
+      const row = options.db
+        .query<{ count: number }, [string]>(
+          "SELECT COUNT(*) as count FROM grading_results WHERE skill_name = ?",
+        )
+        .get(skillName);
+      if (row && row.count >= MIN_CANDIDATE_EVIDENCE) {
+        eligible.add(skillName);
+      }
+    } catch {
+      // Fail-open: table may not exist yet
+    }
+  }
+
+  return eligible;
+}
+
 /**
  * Detects significant overlap between the positive eval sets of evolution
  * candidates. When two skills share >30% of their positive queries, it
@@ -270,6 +317,10 @@ export async function prepareOrchestrateRun(
 
   const pendingSignals = readPendingSignals(runtime.readSignals);
   const signaledSkills = groupSignalsBySkill(pendingSignals);
+  const packageFrontierSkills = collectPackageSearchEligibleSkills(
+    statusResult.skills.map((skill) => skill.name),
+    { db: getDb(), resolveSkillPath: runtime.resolveSkillPath },
+  );
   if (signaledSkills.size > 0) {
     console.error(
       `[orchestrate] Improvement signals: ${pendingSignals.length} pending for ${signaledSkills.size} skill(s)`,
@@ -281,12 +332,16 @@ export async function prepareOrchestrateRun(
     maxSkills: options.maxSkills,
     auditEntries,
     signaledSkills,
+    packageFrontierSkills,
   });
 
   const evolveCandidates = candidates.filter((candidate) => candidate.action === "evolve");
+  const packageSearchCount = candidates.filter(
+    (candidate) => candidate.action === "package-search",
+  ).length;
   const skipCount = candidates.filter((candidate) => candidate.action === "skip").length;
   console.error(
-    `[orchestrate] Candidates: ${evolveCandidates.length} to evolve, ${skipCount} skipped`,
+    `[orchestrate] Candidates: ${evolveCandidates.length} to evolve, ${packageSearchCount} to package-search, ${skipCount} skipped`,
   );
   for (const candidate of candidates) {
     console.error(

package/cli/selftune/orchestrate/report.ts

@@ -123,7 +123,7 @@ export function formatOrchestrateReport(result: OrchestrateResult): string {
   const lines: string[] = [];
 
   lines.push(separator);
-  lines.push("selftune orchestrate — decision report");
+  lines.push("selftune run — decision report");
   lines.push(separator);
   lines.push("");
 

package/cli/selftune/orchestrate.ts

@@ -24,8 +24,11 @@ import {
   autoGradeFreshDeploys,
   buildReplayValidationOptions,
   runEvolutionPhase,
+  runPackageSearchPhase,
   watchRecentDeploys,
 } from "./orchestrate/execute.js";
+export { runPackageSearchPhase } from "./orchestrate/execute.js";
+export type { RunPackageSearchPhaseInput } from "./orchestrate/execute.js";
 import { finalizeOrchestrateRun } from "./orchestrate/finalize.js";
 import { acquireLock, releaseLock } from "./orchestrate/locks.js";
 import { runPostOrchestrateSideEffects } from "./orchestrate/post-run.js";
@@ -67,6 +70,7 @@ export {
   DEFAULT_COOLDOWN_HOURS,
   MIN_CANDIDATE_EVIDENCE,
   selectCandidates,
+  shouldSelectPackageSearch,
 } from "./orchestrate/plan.js";
 export { autoGradeTopUngraded, detectCrossSkillOverlap } from "./orchestrate/prepare.js";
 export { formatOrchestrateReport } from "./orchestrate/report.js";
@@ -93,12 +97,20 @@ export interface OrchestrateOptions {
   maxAutoGrade: number;
 }
 
+export interface PackageSearchResult {
+  searched: boolean;
+  winnerApplied: boolean;
+  candidateCount: number;
+  winnerCandidateId?: string;
+}
+
 export interface SkillAction {
   skill: string;
-  action: "evolve" | "watch" | "skip";
+  action: "evolve" | "package-search" | "watch" | "skip";
   reason: string;
   evolveResult?: EvolveResult;
   watchResult?: WatchResult;
+  packageSearchResult?: PackageSearchResult;
 }
 
 /** Context for candidate selection beyond simple status checks. */
@@ -110,6 +122,8 @@ export interface CandidateContext {
   cooldownHours?: number;
   /** Skill name (lowercase) to improvement signal count. */
   signaledSkills?: Map<string, number>;
+  /** Skills with an accepted package frontier candidate (eligible for package search). */
+  packageFrontierSkills?: Set<string>;
 }
 
 export interface OrchestrateResult {
@@ -127,6 +141,8 @@ export interface OrchestrateResult {
     watched: number;
     skipped: number;
     autoGraded: number;
+    packageSearched: number;
+    packageImproved: number;
     freshlyWatchedSkills: string[];
     dryRun: boolean;
     approvalMode: "auto" | "review";
@@ -240,6 +256,8 @@ export async function orchestrate(
         watched: 0,
         skipped: 0,
         autoGraded: 0,
+        packageSearched: 0,
+        packageImproved: 0,
         freshlyWatchedSkills: [],
         dryRun: options.dryRun,
         approvalMode: options.approvalMode,
@@ -288,6 +306,19 @@ export async function orchestrate(
       readSkillRecords: runtime.readSkillRecords,
     });
 
+    // -------------------------------------------------------------------------
+    // Step 5c: Package search for candidates tagged with action "package-search"
+    // -------------------------------------------------------------------------
+    const packageSearchCandidates = candidates.filter(
+      (candidate) => candidate.action === "package-search",
+    );
+    const packageSearchImproved = await runPackageSearchPhase({
+      packageSearchCandidates,
+      dryRun: options.dryRun,
+      agent,
+      resolveSkillPath: runtime.resolveSkillPath,
+    });
+
     // -------------------------------------------------------------------------
     // Step 6: Watch recently evolved skills (including freshly deployed in this run)
     // -------------------------------------------------------------------------
@@ -336,6 +367,8 @@ export async function orchestrate(
       dryRun: options.dryRun,
       approvalMode: options.approvalMode,
       autoGradedCount,
+      packageSearched: packageSearchCandidates.length,
+      packageImproved: packageSearchImproved.length,
       freshlyWatchedSkills,
       pendingSignals,
       elapsedMs: Date.now() - startTime,

package/cli/selftune/publish.ts

@@ -0,0 +1,35 @@
+import { PUBLIC_COMMAND_SURFACES, renderCommandHelp } from "./command-surface.js";
+import { cliMain as createPublishCliMain } from "./create/publish.js";
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
+
+export async function cliMain(): Promise<void> {
+  const rawArgs = process.argv.slice(2);
+
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    console.log(renderCommandHelp(PUBLIC_COMMAND_SURFACES.publish));
+    process.exit(0);
+  }
+
+  const hasWatch = rawArgs.includes("--watch") || rawArgs.some((arg) => arg.startsWith("--watch="));
+  const hasNoWatch = rawArgs.includes("--no-watch");
+
+  if (hasWatch && hasNoWatch) {
+    throw new CLIError(
+      "Use either --watch or --no-watch, not both.",
+      "INVALID_FLAG",
+      "selftune publish --skill-path <path> [--no-watch]",
+    );
+  }
+
+  const delegatedArgs = rawArgs.filter((arg) => arg !== "--no-watch");
+  if (!hasWatch && !hasNoWatch) {
+    delegatedArgs.push("--watch");
+  }
+
+  process.argv = [process.argv[0], process.argv[1], ...delegatedArgs];
+  await createPublishCliMain();
+}
+
+if (import.meta.main) {
+  cliMain().catch(handleCLIError);
+}

package/cli/selftune/registry/github-install.ts

@@ -0,0 +1,256 @@
+import { execFile } from "node:child_process";
+import { cp, mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { parseFrontmatter } from "../utils/frontmatter.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface GithubRegistryInstallTarget {
+  owner: string;
+  repo: string;
+  repoFullName: string;
+  ref: string | null;
+  skillPath: string | null;
+}
+
+function normalizeGithubSkillPath(skillPath: string): string {
+  const trimmed = skillPath.trim().replace(/\\/g, "/");
+  if (!trimmed || trimmed === ".") {
+    return ".";
+  }
+
+  const segments = trimmed.split("/").filter(Boolean);
+  if (segments.includes("..")) {
+    throw new Error("GitHub skill path must stay within the repository");
+  }
+
+  const normalized = path.posix.normalize(trimmed).replace(/^\/+|\/+$/g, "");
+  return normalized || ".";
+}
+
+export function parseGithubRegistryInstallTarget(
+  rawTarget: string,
+): GithubRegistryInstallTarget | null {
+  if (!rawTarget.startsWith("github:")) {
+    return null;
+  }
+
+  const spec = rawTarget.slice("github:".length).trim();
+  if (!spec) {
+    throw new Error("GitHub install target must be github:owner/repo[@ref][//path]");
+  }
+
+  const pathSeparatorIndex = spec.indexOf("//");
+  const repoWithMaybeRef = pathSeparatorIndex === -1 ? spec : spec.slice(0, pathSeparatorIndex);
+  const pathWithMaybeRef = pathSeparatorIndex === -1 ? null : spec.slice(pathSeparatorIndex + 2);
+
+  let ref: string | null = null;
+  let repoSpec = repoWithMaybeRef;
+
+  const repoRefIndex = repoWithMaybeRef.lastIndexOf("@");
+  if (repoRefIndex !== -1) {
+    repoSpec = repoWithMaybeRef.slice(0, repoRefIndex);
+    ref = repoWithMaybeRef.slice(repoRefIndex + 1) || null;
+  }
+
+  let skillPath: string | null = null;
+  if (pathWithMaybeRef != null) {
+    const pathRefIndex = pathWithMaybeRef.lastIndexOf("@");
+    if (pathRefIndex !== -1) {
+      skillPath = pathWithMaybeRef.slice(0, pathRefIndex) || ".";
+      ref = pathWithMaybeRef.slice(pathRefIndex + 1) || ref;
+    } else {
+      skillPath = pathWithMaybeRef || ".";
+    }
+  }
+
+  const match = repoSpec.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/);
+  if (!match) {
+    throw new Error("GitHub install target must look like github:owner/repo[@ref][//path]");
+  }
+
+  return {
+    owner: match[1],
+    repo: match[2],
+    repoFullName: `${match[1]}/${match[2]}`,
+    ref,
+    skillPath: skillPath ? normalizeGithubSkillPath(skillPath) : null,
+  };
+}
+
+function isExcludedEntry(name: string): boolean {
+  return name === ".git" || name === "node_modules" || name === ".env" || name.startsWith(".env.");
+}
+
+export async function discoverLocalSkillPaths(rootDir: string): Promise<string[]> {
+  async function walk(currentDir: string, basePath: string): Promise<string[]> {
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    const discovered: string[] = [];
+
+    for (const entry of entries) {
+      if (isExcludedEntry(entry.name)) {
+        continue;
+      }
+
+      const fullPath = path.join(currentDir, entry.name);
+      const relativePath = basePath ? path.join(basePath, entry.name) : entry.name;
+
+      if (entry.isDirectory()) {
+        discovered.push(...(await walk(fullPath, relativePath)));
+        continue;
+      }
+
+      if (entry.isFile() && entry.name === "SKILL.md") {
+        discovered.push(basePath ? basePath.split(path.sep).join("/") : ".");
+      }
+    }
+
+    return discovered;
+  }
+
+  const discovered = await walk(rootDir, "");
+  return [...new Set(discovered)].sort((a, b) => a.localeCompare(b));
+}
+
+export async function resolveGithubSkillPath(
+  repoDir: string,
+  requestedSkillPath: string | null,
+): Promise<{ skillPath: string; availablePaths: string[] }> {
+  const availablePaths = await discoverLocalSkillPaths(repoDir);
+
+  if (requestedSkillPath) {
+    const normalized = normalizeGithubSkillPath(requestedSkillPath);
+    const skillMdPath =
+      normalized === "."
+        ? path.join(repoDir, "SKILL.md")
+        : path.join(repoDir, ...normalized.split("/"), "SKILL.md");
+    await stat(skillMdPath);
+    return { skillPath: normalized, availablePaths };
+  }
+
+  if (availablePaths.length === 1) {
+    return { skillPath: availablePaths[0] ?? ".", availablePaths };
+  }
+
+  if (availablePaths.length === 0) {
+    throw new Error("No SKILL.md found in the GitHub repository");
+  }
+
+  throw new Error(
+    `Multiple skills found in the GitHub repository. Choose one with github:owner/repo//path (available: ${availablePaths.join(", ")})`,
+  );
+}
+
+export function deriveGithubInstallSkillName(
+  frontmatterName: string,
+  skillPath: string,
+  skillDir: string,
+  repoName: string,
+): string {
+  const trimmedName = frontmatterName.trim();
+  if (trimmedName) {
+    return trimmedName;
+  }
+
+  return skillPath === "." ? repoName : path.basename(skillDir);
+}
+
+async function cloneGithubRepository(
+  target: GithubRegistryInstallTarget,
+  cloneDir: string,
+): Promise<void> {
+  const repoUrl = `https://github.com/${target.repoFullName}.git`;
+  const args = ["clone", "--depth=1"];
+
+  if (target.ref) {
+    args.push("--branch", target.ref);
+  }
+
+  args.push(repoUrl, cloneDir);
+
+  await execFileAsync("git", args);
+}
+
+async function copySkillDirectory(sourceDir: string, targetDir: string): Promise<void> {
+  await rm(targetDir, { recursive: true, force: true });
+  await mkdir(path.dirname(targetDir), { recursive: true });
+
+  await cp(sourceDir, targetDir, {
+    recursive: true,
+    filter: (entryPath) => {
+      const basename = path.basename(entryPath);
+      return !isExcludedEntry(basename);
+    },
+  });
+}
+
+export async function installFromGithubTarget(
+  rawTarget: string,
+  globalFlag: boolean,
+): Promise<void> {
+  const target = parseGithubRegistryInstallTarget(rawTarget);
+  if (!target) {
+    throw new Error("GitHub install target must start with github:");
+  }
+
+  const tempRoot = await mkdtemp(path.join(tmpdir(), "selftune-github-install-"));
+
+  try {
+    const cloneDir = path.join(tempRoot, "repo");
+    await cloneGithubRepository(target, cloneDir);
+
+    const { skillPath, availablePaths } = await resolveGithubSkillPath(cloneDir, target.skillPath);
+    const skillDir = skillPath === "." ? cloneDir : path.join(cloneDir, ...skillPath.split("/"));
+    const skillContent = await readFile(path.join(skillDir, "SKILL.md"), "utf-8");
+    const frontmatter = parseFrontmatter(skillContent);
+    const skillName = deriveGithubInstallSkillName(
+      frontmatter.name,
+      skillPath,
+      skillDir,
+      target.repo,
+    );
+    const resolvedCommit = (
+      await execFileAsync("git", ["-C", cloneDir, "rev-parse", "HEAD"])
+    ).stdout.trim();
+
+    const targetBase = globalFlag
+      ? path.join(process.env.HOME || "~", ".claude", "skills")
+      : path.join(process.cwd(), ".claude", "skills");
+    const targetDir = path.join(targetBase, skillName);
+
+    await copySkillDirectory(skillDir, targetDir);
+    await writeFile(
+      path.join(targetDir, ".selftune-source.json"),
+      JSON.stringify(
+        {
+          source: "github-direct",
+          repo: target.repoFullName,
+          ref: target.ref ?? "HEAD",
+          commit: resolvedCommit,
+          skill_path: skillPath,
+          available_paths: availablePaths,
+        },
+        null,
+        2,
+      ),
+    );
+
+    console.log(
+      JSON.stringify({
+        success: true,
+        source: "github-direct",
+        name: skillName,
+        repo: target.repoFullName,
+        ref: target.ref ?? "HEAD",
+        commit: resolvedCommit,
+        skill_path: skillPath,
+        path: targetDir,
+        global: globalFlag,
+      }),
+    );
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}

package/cli/selftune/registry/index.ts

@@ -24,7 +24,7 @@ Usage:
 
 Subcommands:
   push [name]          Push current skill folder as a new version
-  install <name>       Download and install a skill from the registry
+  install <name>       Download from the registry or install github:owner/repo[@ref][//path]
   sync                 Check for updates and pull latest versions
   status               Show installed entries and version drift
   rollback <name>      Rollback to a previous version