selftune 0.2.30 → 0.2.31

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

package/cli/selftune/registry/install.ts

@@ -8,6 +8,7 @@ import { hostname } from "node:os";
 import { join } from "node:path";
 
 import { registryRequest } from "./client.js";
+import { installFromGithubTarget, parseGithubRegistryInstallTarget } from "./github-install.js";
 
 export async function cliMain() {
   const args = process.argv.slice(2);
@@ -17,13 +18,45 @@ export async function cliMain() {
   if (!name) {
     console.error(
       JSON.stringify({
-        error: "Usage: selftune registry install <name>",
+        error: "Usage: selftune registry install <name|github:owner/repo[@ref][//path]>",
         guidance: { next_command: "selftune registry list" },
       }),
     );
     process.exit(1);
   }
 
+  let githubTarget = null;
+  try {
+    githubTarget = parseGithubRegistryInstallTarget(name);
+  } catch (error) {
+    console.error(
+      JSON.stringify({
+        error: error instanceof Error ? error.message : "Invalid GitHub install target",
+        guidance: {
+          next_command: "selftune registry install github:owner/repo//path",
+        },
+      }),
+    );
+    process.exit(1);
+  }
+
+  if (githubTarget) {
+    try {
+      await installFromGithubTarget(name, globalFlag);
+      return;
+    } catch (error) {
+      console.error(
+        JSON.stringify({
+          error: error instanceof Error ? error.message : "GitHub install failed",
+          guidance: {
+            next_command: "selftune registry install github:owner/repo//path",
+          },
+        }),
+      );
+      process.exit(1);
+    }
+  }
+
   // Find entry by name
   const listResult = await registryRequest<{
     entries: Array<{
@@ -49,7 +82,12 @@ export async function cliMain() {
   // Get detail with versions
   const detailResult = await registryRequest<{
     entry: { id: string; name: string };
-    versions: Array<{ id: string; version: string; content_hash: string; is_current: boolean }>;
+    versions: Array<{
+      id: string;
+      version: string;
+      content_hash: string;
+      is_current: boolean;
+    }>;
   }>("GET", `/${entryId}`);
 
   if (!detailResult.success) {
@@ -71,7 +109,9 @@ export async function cliMain() {
       latest_content_hash: string;
     }>;
   }>("POST", "/sync", {
-    body: { installations: [{ entry_id: entryId, current_version_hash: "none" }] },
+    body: {
+      installations: [{ entry_id: entryId, current_version_hash: "none" }],
+    },
   });
 
   const downloadUrl = syncResult.data?.entries?.[0]?.download_url;
@@ -82,7 +122,9 @@ export async function cliMain() {
 
   // Download archive
   console.log(`Installing ${name} v${currentVersion.version}...`);
-  const response = await fetch(downloadUrl, { signal: AbortSignal.timeout(60_000) });
+  const response = await fetch(downloadUrl, {
+    signal: AbortSignal.timeout(60_000),
+  });
   if (!response.ok) {
     console.error(JSON.stringify({ error: `Download failed: HTTP ${response.status}` }));
     process.exit(1);
@@ -119,13 +161,22 @@ export async function cliMain() {
 
   // Update local state
   const statePath = join(process.env.HOME || "~", ".selftune", "registry-state.json");
-  let state: Array<{ entryId: string; name: string; versionHash: string; installPath: string }> =
-    [];
+  let state: Array<{
+    entryId: string;
+    name: string;
+    versionHash: string;
+    installPath: string;
+  }> = [];
   try {
     state = JSON.parse(readFileSync(statePath, "utf-8"));
   } catch {}
   state = state.filter((s) => s.entryId !== entryId);
-  state.push({ entryId, name, versionHash: currentVersion.content_hash, installPath: targetDir });
+  state.push({
+    entryId,
+    name,
+    versionHash: currentVersion.content_hash,
+    installPath: targetDir,
+  });
   await mkdir(join(process.env.HOME || "~", ".selftune"), { recursive: true });
   await writeFile(statePath, JSON.stringify(state, null, 2));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selftune",
-  "version": "0.2.30",
+  "version": "0.2.31",
   "description": "Skill-level observability and self-improvement for AI agents — monitors skill routing, detects missed triggers, and evolves descriptions automatically",
   "keywords": [
     "agent",

package/packages/dashboard-core/src/routes/manifest.ts

@@ -217,7 +217,7 @@ export const DASHBOARD_ROUTE_MANIFEST: readonly DashboardRouteManifestEntry[] =
     icon: PackageIcon,
     feature: "registry",
     discoverableFeature: "registry",
-    lockedTitle: "Cloud Registry lives in Selftune Cloud",
+    lockedTitle: "Cloud Registry lives in selftune Cloud",
     lockedBody:
       "Publish versioned skills, watch installations across projects, and roll back bad versions from a single cloud workspace.",
     lockedHighlights: [
@@ -255,7 +255,7 @@ export const DASHBOARD_ROUTE_MANIFEST: readonly DashboardRouteManifestEntry[] =
     icon: UsersIcon,
     feature: "signals",
     discoverableFeature: "signals",
-    lockedTitle: "Contributor signals run through Selftune Cloud",
+    lockedTitle: "Contributor signals run through selftune Cloud",
     lockedBody:
       "See anonymized contributor signals, compare bundle submissions, and turn real-world usage into proposals without leaving the shared dashboard.",
     lockedHighlights: [

package/packages/ui/src/components/SkillReportPanels.tsx

@@ -379,7 +379,7 @@ function narrativeObservedText({
     promptLinkRate != null
       ? ` It could link ${formatRate(promptLinkRate)} of those checks back to prompts.`
       : "";
-  return `Selftune watched ${checks} skill checks across ${sessions} sessions.${promptClause}`;
+  return `selftune watched ${checks} skill checks across ${sessions} sessions.${promptClause}`;
 }
 
 function narrativeDiagnosisText({
@@ -411,17 +411,17 @@ function narrativeDecisionText({
 }) {
   switch (trustState) {
     case "validated":
-      return `Selftune found a candidate that looks promising, but it has not been deployed yet. ${nextActionText}`;
+      return `selftune found a candidate that looks promising, but it has not been deployed yet. ${nextActionText}`;
     case "deployed":
-      return `A change has already been deployed for this skill. Selftune is now watching for regressions in real use.`;
+      return `A change has already been deployed for this skill. selftune is now watching for regressions in real use.`;
     case "rolled_back":
       return `A previous change was rolled back, so the live skill is back on the safer version while selftune keeps observing.`;
     case "watch":
-      return `Selftune sees enough signal to keep a close eye on this skill, but not enough to blindly change it. ${nextActionText}`;
+      return `selftune sees enough signal to keep a close eye on this skill, but not enough to blindly change it. ${nextActionText}`;
     case "observed":
-      return `Selftune is still learning how people use this skill before making stronger recommendations.`;
+      return `selftune is still learning how people use this skill before making stronger recommendations.`;
     case "low_sample":
-      return `There is not enough evidence yet to trust a big change here. Selftune is still collecting examples.`;
+      return `There is not enough evidence yet to trust a big change here. selftune is still collecting examples.`;
     default:
       return latestAction
         ? `The latest automated decision for this skill was ${latestAction}. ${nextActionText}`
@@ -552,7 +552,7 @@ export function SkillTrustNarrativePanel({
           />
         </div>
         <div className="rounded-xl border border-border/10 bg-muted/15 px-4 py-3 text-sm text-muted-foreground">
-          If a proposal is rejected or still pending, your live skill has not changed yet. Selftune
+          If a proposal is rejected or still pending, your live skill has not changed yet. selftune
           only earns trust by testing changes before deployment.
         </div>
       </CardContent>

package/packages/ui/src/primitives/button.tsx

@@ -18,6 +18,10 @@ const buttonVariants = cva(
         destructive:
           "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
         link: "text-primary underline-offset-4 hover:underline",
+        "glass-primary":
+          "border-cyan-300 bg-background/75 text-foreground shadow-[0_10px_28px_rgba(34,211,238,0.14),inset_0_1px_0_rgba(255,255,255,0.09)] hover:border-cyan-200 hover:bg-background/85 hover:shadow-[0_14px_34px_rgba(34,211,238,0.18),inset_0_1px_0_rgba(255,255,255,0.12)]",
+        "glass-secondary":
+          "border-border/70 bg-background/60 text-foreground shadow-[inset_0_1px_0_rgba(255,255,255,0.06)] hover:border-cyan-400/20 hover:bg-background/75 hover:shadow-[0_10px_24px_rgba(34,211,238,0.08),inset_0_1px_0_rgba(255,255,255,0.1)]",
       },
       size: {
         default:
@@ -31,6 +35,7 @@ const buttonVariants = cva(
         "icon-sm":
           "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
         "icon-lg": "size-9",
+        glass: "gap-2 px-4 py-2 backdrop-blur-sm",
       },
     },
     defaultVariants: {

package/skill/SKILL.md

@@ -13,7 +13,7 @@ description: >
   even if they don't say "selftune" explicitly.
 metadata:
   author: selftune-dev
-  version: 0.2.30
+  version: 0.2.31
   category: developer-tools
 ---
 

package/skill/workflows/Registry.md

@@ -4,20 +4,21 @@ Manage versioned skill distribution across your team. Push skill folders to the
 
 ## Commands
 
-| Command | Flags | What It Does |
-|---------|-------|-------------|
-| `selftune registry push [name]` | `--version=<semver>` `--summary=<text>` | Archive current skill folder and push as a new version |
-| `selftune registry install <name>` | `--global` | Download and extract a skill from the registry |
-| `selftune registry sync` | | Check all installed entries for updates, pull latest |
-| `selftune registry status` | | Show installed entries with version drift |
-| `selftune registry rollback <name>` | `--to=<version>` `--reason=<text>` | Rollback a skill to a previous version |
-| `selftune registry history <name>` | | Show version timeline with quality data |
-| `selftune registry list` | | Show all published entries in the org |
+| Command                                                             | Flags                                   | What It Does                                                     |
+| ------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- |
+| `selftune registry push [name]`                                     | `--version=<semver>` `--summary=<text>` | Archive current skill folder and push as a new version           |
+| `selftune registry install <name\|github:owner/repo[@ref][//path]>` | `--global`                              | Download from the registry or clone/install directly from GitHub |
+| `selftune registry sync`                                            |                                         | Check all installed entries for updates, pull latest             |
+| `selftune registry status`                                          |                                         | Show installed entries with version drift                        |
+| `selftune registry rollback <name>`                                 | `--to=<version>` `--reason=<text>`      | Rollback a skill to a previous version                           |
+| `selftune registry history <name>`                                  |                                         | Show version timeline with quality data                          |
+| `selftune registry list`                                            |                                         | Show all published entries in the org                            |
 
 ## When to Use
 
 - User says "push this skill to the team" → `selftune registry push`
 - User says "install the deploy skill" → `selftune registry install deploy`
+- User says "install this GitHub skill repo" → `selftune registry install github:owner/repo`
 - User says "update my skills" or "sync registry" → `selftune registry sync`
 - User says "check for updates" → `selftune registry status`
 - User says "rollback the deploy skill" → `selftune registry rollback deploy`
@@ -34,10 +35,13 @@ Manage versioned skill distribution across your team. Push skill folders to the
 
 ## Install Workflow
 
-1. Run `selftune registry install <name>` to pull from the registry
+1. Run `selftune registry install <name>` to pull from the registry, or
+   `selftune registry install github:owner/repo[@ref][//path]` to clone and
+   install directly from GitHub using local git credentials
 2. By default, installs to `.claude/skills/<name>/` in the current project
 3. Use `--global` to install to `~/.claude/skills/<name>/` (available everywhere)
-4. Installation is tracked — `selftune registry status` shows what's installed
+4. Registry installs are tracked by `selftune registry status`; direct GitHub
+   installs are local-only and do not participate in `registry sync`
 
 ## Sync Workflow
 
@@ -82,8 +86,10 @@ All commands output JSON for agent consumption:
 
 **User wants to install a shared skill**
 
-> Run `selftune registry install <name>`. Use `--global` if they want it
-> available across all projects.
+> Run `selftune registry install <name>` for a cloud-published skill, or
+> `selftune registry install github:owner/repo[@ref][//path]` if they want to
+> install directly from GitHub. Use `--global` if they want it available across
+> all projects.
 
 **User wants to check what's outdated**