@skillsgate/tui 0.1.15 → 0.2.4

package/bin/postinstall.cjs

@@ -16,7 +16,7 @@ const pkg = platformMap[os.platform()]?.[os.arch()];
 if (!pkg) process.exit(0);
 
 // Check if already available as a sibling (optionalDeps worked)
-const siblingPath = path.join(__dirname, "..", "..", "..", `@skillsgate/${pkg}`);
+const siblingPath = path.join(__dirname, "..", "..", `@skillsgate/${pkg}`);
 if (fs.existsSync(siblingPath)) process.exit(0);
 
 // Also check nested node_modules
@@ -27,11 +27,20 @@ try {
 
 // Not found — install it explicitly
 const version = require("../package.json").version;
+const fullPkg = `@skillsgate/${pkg}@${version}`;
 try {
-  execSync(`npm install -g @skillsgate/${pkg}@${version} --no-save`, {
+  execSync(`npm install -g ${fullPkg} --no-save`, {
     stdio: "inherit",
     timeout: 30000,
   });
 } catch {
-  console.warn(`Warning: could not install @skillsgate/${pkg}. Run manually: npm install -g @skillsgate/${pkg}`);
+  console.warn(`Could not install ${fullPkg}, falling back to @latest (versions may differ)`);
+  try {
+    execSync(`npm install -g @skillsgate/${pkg}@latest --no-save`, {
+      stdio: "inherit",
+      timeout: 30000,
+    });
+  } catch {
+    console.warn(`Warning: could not install @skillsgate/${pkg}. Run manually: npm install -g @skillsgate/${pkg}`);
+  }
 }

package/bin/skillsgate-tui

@@ -25,14 +25,34 @@ const binName = platform === "win32" ? "skillsgate-tui.exe" : "skillsgate-tui";
 const require = createRequire(import.meta.url);
 const thisDir = path.dirname(fileURLToPath(import.meta.url));
 
-function findBinary() {
+function getNpmGlobalRoot() {
+  try {
+    return execFileSync("npm", ["root", "-g"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 10000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function findBinary({ includeGlobal = false } = {}) {
   const candidates = [
     // Nested node_modules (local installs)
     () => require.resolve(`@skillsgate/${pkg}/${binName}`),
     // Sibling in global node_modules (npm install -g)
-    () => path.join(thisDir, "..", "..", "..", `@skillsgate/${pkg}`, binName),
+    () => path.join(thisDir, "..", "..", `@skillsgate/${pkg}`, binName),
   ];
 
+  if (includeGlobal) {
+    candidates.push(() => {
+      const globalRoot = getNpmGlobalRoot();
+      if (!globalRoot) throw new Error("npm global root not found");
+      return path.join(globalRoot, `@skillsgate/${pkg}`, binName);
+    });
+  }
+
   for (const resolve of candidates) {
     try {
       const p = resolve();
@@ -54,9 +74,16 @@ if (!binPath) {
   console.error(`Installing platform binary (${fullPkg})...`);
   try {
     execSync(`npm install -g ${fullPkg}`, { stdio: "inherit", timeout: 30000 });
-    binPath = findBinary();
+    binPath = findBinary({ includeGlobal: true });
   } catch {
-    // fall through to error below
+    // Fallback to latest if exact version is not published for this platform
+    console.warn(`Could not install ${fullPkg}, falling back to @latest (versions may differ)`);
+    try {
+      execSync(`npm install -g @skillsgate/${pkg}@latest`, { stdio: "inherit", timeout: 30000 });
+      binPath = findBinary({ includeGlobal: true });
+    } catch {
+      binPath = findBinary({ includeGlobal: true });
+    }
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillsgate/tui",
-  "version": "0.1.15",
+  "version": "0.2.4",
   "type": "module",
   "bin": {
     "skillsgate-tui": "bin/skillsgate-tui"

package/src/components/agent-filter.tsx

@@ -15,6 +15,12 @@ export function AgentFilter() {
   const { servers } = useDb()
 
   const allCount = state.installedSkills.length
+  // Count favorites that are currently installed.
+  const favSet = new Set(state.favorites)
+  const favoritesCount = state.installedSkills.reduce(
+    (n, s) => (favSet.has(s.name) ? n + 1 : n),
+    0,
+  )
 
   // Remote servers with skill counts
   const serverList = servers.list()
@@ -38,7 +44,7 @@ export function AgentFilter() {
     if (state.focusedPane !== "agents") return
     if (state.showHelp) return
 
-    const allOptions = ["all", ...agentOptions.map((o) => o.value)]
+    const allOptions = ["all", "favorites", ...agentOptions.map((o) => o.value)]
     const currentIdx = allOptions.indexOf(state.selectedAgentFilter)
 
     if (key.name === "up" || (key.name === "k" && !key.ctrl)) {
@@ -84,6 +90,21 @@ export function AgentFilter() {
         <text fg={colors.textDim}> ({allCount})</text>
       </box>
 
+      {/* Favorites */}
+      <box
+        style={{
+          paddingLeft: 1,
+          paddingRight: 1,
+          height: 1,
+          backgroundColor: state.selectedAgentFilter === "favorites" ? colors.bgAlt : "transparent",
+        }}
+      >
+        <text fg={state.selectedAgentFilter === "favorites" ? colors.primary : colors.text}>
+          {"★ "}Favorites
+        </text>
+        <text fg={colors.textDim}> ({favoritesCount})</text>
+      </box>
+
       {/* Spacer */}
       <box style={{ height: 1 }}>
         <text>{" "}</text>

package/src/components/help-overlay.tsx

@@ -10,6 +10,7 @@ const SHORTCUTS_LEFT: ShortcutEntry[] = [
   { key: "g", description: "Jump to first item" },
   { key: "G", description: "Jump to last item" },
   { key: "v", description: "View skill detail" },
+  { key: "f", description: "Toggle favorite on selected skill" },
   { key: "n", description: "Create local skill (home)" },
   { key: "c", description: "Manage collections (home)" },
   { key: "/", description: "Focus search input" },
@@ -29,6 +30,7 @@ const SHORTCUTS_RIGHT: ShortcutEntry[] = [
   { key: "", description: "" },
   { key: "-- Servers View --", description: "" },
   { key: "S", description: "Sync selected server" },
+  { key: "P", description: "push local skills to selected server" },
   { key: "a", description: "Add new server" },
   { key: "e", description: "Edit server" },
   { key: "t", description: "Test connection" },

package/src/components/layout.tsx

@@ -4,6 +4,7 @@ import { useStore, useDispatch } from "../store/context.js"
 import { useDb } from "../db/context.js"
 import { useDetectedAgents } from "../data/use-agents.js"
 import { useInstalledSkills } from "../data/use-installed-skills.js"
+import { useFavorites } from "../data/use-favorites.js"
 import { StatusBar } from "./status-bar.js"
 import { HelpOverlay } from "./help-overlay.js"
 import { HomeView } from "../views/home.js"
@@ -38,6 +39,7 @@ export function Layout() {
   // Load agent + skill data on mount
   useDetectedAgents()
   useInstalledSkills()
+  useFavorites()
 
   // Global keyboard shortcuts
   useKeyboard((key) => {

package/src/components/skill-list-item.tsx

@@ -4,13 +4,14 @@ import { colors, agentBadges as badgeMap } from "../utils/colors.js"
 interface SkillListItemProps {
   skill: EnrichedSkill
   selected?: boolean
+  favorited?: boolean
 }
 
 /**
  * Compact skill list item for the middle panel.
  * Shows just the name and small agent dot indicators.
  */
-export function SkillListItem({ skill, selected }: SkillListItemProps) {
+export function SkillListItem({ skill, selected, favorited }: SkillListItemProps) {
   // Build compact agent dots (single-char badges)
   const agentDots = skill.agents.slice(0, 3).map((a) => {
     const badge = badgeMap[a]
@@ -27,6 +28,11 @@ export function SkillListItem({ skill, selected }: SkillListItemProps) {
         backgroundColor: selected ? colors.bgAlt : "transparent",
       }}
     >
+      {/* Star indicator (favorited skills only) */}
+      <text fg={favorited ? colors.warning : colors.textDim}>
+        {favorited ? "★ " : "  "}
+      </text>
+
       {/* Skill name */}
       <text fg={selected ? colors.primary : colors.text} style={{ flexGrow: 1 }}>
         {skill.name}

package/src/components/skill-list.tsx

@@ -1,7 +1,8 @@
-import { useState, useEffect } from "react"
+import { useState, useEffect, useMemo } from "react"
 import { useKeyboard } from "@opentui/react"
 import { useStore, useDispatch } from "../store/context.js"
 import { useSkillActions } from "../data/use-skill-actions.js"
+import { useFavorites } from "../data/use-favorites.js"
 import { SkillListItem } from "./skill-list-item.js"
 import { ConfirmDialog } from "./confirm-dialog.js"
 import { colors, agentBadges as badgeMap } from "../utils/colors.js"
@@ -30,6 +31,8 @@ export function SkillList({ skills }: SkillListProps) {
   const dispatch = useDispatch()
   const state = useStore()
   const { removeSkill, removeSkillFromOneAgent, updateSkill } = useSkillActions()
+  const { favorites, toggleFavorite } = useFavorites()
+  const favoritesSet = useMemo(() => new Set(favorites), [favorites])
   const [selectedIndex, setSelectedIndex] = useState(0)
   const [pendingAction, setPendingAction] = useState<PendingAction>(null)
   const [removeMode, setRemoveMode] = useState<RemoveMode>(null)
@@ -114,6 +117,21 @@ export function SkillList({ skills }: SkillListProps) {
     if (key.name === "u" && skills[selectedIndex]) {
       setPendingAction({ type: "update", skill: skills[selectedIndex] })
     }
+
+    // f to toggle favorite for selected skill
+    if (key.name === "f" && skills[selectedIndex]) {
+      const skill = skills[selectedIndex]
+      const isFavoritedAfter = toggleFavorite(skill.name)
+      dispatch({
+        type: "SHOW_NOTIFICATION",
+        notification: {
+          type: "info",
+          message: isFavoritedAfter
+            ? `Added "${skill.name}" to favorites`
+            : `Removed "${skill.name}" from favorites`,
+        },
+      })
+    }
   })
 
   // Handle confirm/cancel for pending actions
@@ -201,7 +219,9 @@ export function SkillList({ skills }: SkillListProps) {
         <text fg={colors.textDim}>
           {state.installedLoading
             ? "Scanning for installed skills..."
-            : "No skills found. Install skills with: skillsgate install <source>"}
+            : state.selectedAgentFilter === "favorites"
+              ? "No favorites yet. Press f on any skill to save it here."
+              : "No skills found. Install skills with: skillsgate install <source>"}
         </text>
       </box>
     )
@@ -237,6 +257,7 @@ export function SkillList({ skills }: SkillListProps) {
             key={skill.name}
             skill={skill}
             selected={i === selectedIndex}
+            favorited={favoritesSet.has(skill.name)}
           />
         ))}
       </scrollbox>

package/src/data/use-favorites.ts

@@ -0,0 +1,31 @@
+import { useCallback, useEffect } from "react"
+import { useDispatch, useStore } from "../store/context.js"
+import { useDb } from "../db/context.js"
+
+/**
+ * Hydrates the favorites list from the local DB on mount and exposes a
+ * `toggleFavorite` callback that updates both DB and store state.
+ */
+export function useFavorites() {
+  const dispatch = useDispatch()
+  const state = useStore()
+  const { favorites } = useDb()
+
+  useEffect(() => {
+    dispatch({ type: "SET_FAVORITES", favorites: favorites.list() })
+  }, [])
+
+  const toggleFavorite = useCallback(
+    (name: string): boolean => {
+      const next = favorites.toggle(name)
+      dispatch({ type: "SET_FAVORITES", favorites: favorites.list() })
+      return next
+    },
+    [favorites, dispatch],
+  )
+
+  return {
+    favorites: state.favorites,
+    toggleFavorite,
+  }
+}

package/src/db/context.tsx

@@ -3,12 +3,14 @@ import type { Database } from "bun:sqlite"
 import { SettingsStore } from "./settings.js"
 import { RemoteServerStore } from "./servers.js"
 import { RemoteSkillStore } from "./skills.js"
+import { FavoritesStore } from "./favorites.js"
 
 export interface DbContext {
   db: Database
   settings: SettingsStore
   servers: RemoteServerStore
   skills: RemoteSkillStore
+  favorites: FavoritesStore
 }
 
 const DbCtx = createContext<DbContext | null>(null)
@@ -24,6 +26,7 @@ export function DbProvider({ db, children }: DbProviderProps) {
     settings: new SettingsStore(db),
     servers: new RemoteServerStore(db),
     skills: new RemoteSkillStore(db),
+    favorites: new FavoritesStore(db),
   }
 
   return <DbCtx.Provider value={ctx}>{children}</DbCtx.Provider>

package/src/db/favorites.ts

@@ -0,0 +1,39 @@
+import type { Database } from "bun:sqlite"
+
+export class FavoritesStore {
+  private db: Database
+
+  constructor(db: Database) {
+    this.db = db
+  }
+
+  list(): string[] {
+    const rows = this.db
+      .query("SELECT skill_name FROM favorites ORDER BY created_at DESC")
+      .all() as Array<{ skill_name: string }>
+    return rows.map((r) => r.skill_name)
+  }
+
+  has(name: string): boolean {
+    const row = this.db
+      .query("SELECT 1 FROM favorites WHERE skill_name = ?")
+      .get(name)
+    return row !== null
+  }
+
+  toggle(name: string): boolean {
+    if (this.has(name)) {
+      this.db.query("DELETE FROM favorites WHERE skill_name = ?").run(name)
+      return false
+    }
+    this.db.query("INSERT INTO favorites (skill_name) VALUES (?)").run(name)
+    return true
+  }
+
+  count(): number {
+    const row = this.db
+      .query("SELECT COUNT(*) as c FROM favorites")
+      .get() as { c: number }
+    return row.c
+  }
+}

package/src/db/local-skills.ts

@@ -0,0 +1,64 @@
+// packages/tui/src/db/local-skills.ts
+/**
+ * Pure async scanner for local canonical skills under ~/.agents/skills.
+ * Returns the minimal shape needed by the push orchestrator.
+ * Does NOT depend on React, the store, or the DB layer.
+ */
+import fs from "node:fs/promises"
+import path from "node:path"
+import os from "node:os"
+
+const home = os.homedir()
+export const CANONICAL_SKILLS_DIR = path.join(home, ".agents", "skills")
+
+export interface LocalCanonicalSkill {
+  folderName: string
+  canonicalPath: string
+  name: string
+}
+
+/**
+ * List all skill directories under ~/.agents/skills that contain a SKILL.md.
+ * Uses the folder name as both folderName and name (SKILL.md name field is
+ * parsed by the push orchestrator's hash step, which reads the file again).
+ */
+export async function listLocalCanonicalSkills(): Promise<LocalCanonicalSkill[]> {
+  const results: LocalCanonicalSkill[] = []
+  let names: string[]
+  try {
+    names = await fs.readdir(CANONICAL_SKILLS_DIR)
+  } catch {
+    return []
+  }
+
+  for (const name of names) {
+    const skillDir = path.join(CANONICAL_SKILLS_DIR, name)
+    let stat: Awaited<ReturnType<typeof fs.stat>>
+    try {
+      stat = await fs.stat(skillDir)
+    } catch {
+      continue // broken symlink or unreadable
+    }
+    if (!stat.isDirectory()) continue
+
+    let canonicalPath: string
+    try {
+      canonicalPath = await fs.realpath(skillDir)
+    } catch {
+      continue
+    }
+
+    const skillMdPath = path.join(canonicalPath, "SKILL.md")
+    try {
+      await fs.access(skillMdPath)
+    } catch {
+      continue // no SKILL.md
+    }
+    results.push({
+      folderName: name,
+      canonicalPath,
+      name,
+    })
+  }
+  return results
+}

package/src/db/migrations.ts

@@ -70,6 +70,17 @@ const MIGRATIONS: Migration[] = [
       INSERT OR IGNORE INTO schema_version VALUES (2);
     `,
   },
+  {
+    version: 3,
+    up: `
+      CREATE TABLE IF NOT EXISTS favorites (
+        skill_name TEXT PRIMARY KEY,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      INSERT OR IGNORE INTO schema_version VALUES (3);
+    `,
+  },
 ]
 
 function getCurrentVersion(db: Database): number {

package/src/db/push.ts

@@ -0,0 +1,220 @@
+// packages/tui/src/db/push.ts
+import crypto from "node:crypto"
+import path from "node:path"
+import { promises as fs } from "node:fs"
+
+import type { RemoteServer } from "./servers.js"
+import {
+  scanRemoteSkills,
+  uploadSkillDir,
+  deleteRemoteSkillDir,
+} from "./ssh.js"
+import { listLocalCanonicalSkills, CANONICAL_SKILLS_DIR } from "./local-skills.js"
+
+export interface PushPlanEntry {
+  folderName: string
+  name: string
+  localPath: string
+  remotePath: string
+  remoteDir: string
+  reason: "added" | "updated" | "deleted" | "unchanged"
+  localHash?: string
+  remoteHash?: string
+}
+
+export interface PushPreview {
+  toAdd: PushPlanEntry[]
+  toUpdate: PushPlanEntry[]
+  toDelete: PushPlanEntry[]
+  unchanged: PushPlanEntry[]
+  mirror: boolean
+}
+
+export interface PushResult {
+  added: number
+  updated: number
+  deleted: number
+  unchanged: number
+  errors: { folderName: string; message: string }[]
+}
+
+export interface PushOptions {
+  mirror: boolean
+}
+
+function sha256(s: string): string {
+  return crypto.createHash("sha256").update(s, "utf-8").digest("hex")
+}
+
+/**
+ * Resolve the remote skills base path to an absolute path relative to the server,
+ * dropping a trailing slash. We don't expand "~/" here -- that happens server-side
+ * via $HOME inside shellQuotePath.
+ */
+function normalizeRemoteBase(p: string): string {
+  return p.replace(/\/+$/, "")
+}
+
+/**
+ * Diff local canonical skills against the remote scan. Returns the plan.
+ * Does NOT execute anything.
+ */
+export async function planPush(
+  server: RemoteServer,
+  options: PushOptions,
+): Promise<PushPreview> {
+  // 1. List local canonical skills under ~/.agents/skills
+  const localCanonical = await listLocalCanonicalSkills()
+
+  // 2. Hash each local SKILL.md
+  const localByFolder = new Map<
+    string,
+    { folderName: string; name: string; localPath: string; hash: string }
+  >()
+  for (const s of localCanonical) {
+    const skillMdPath = path.join(s.canonicalPath, "SKILL.md")
+    let content: string
+    try {
+      content = await fs.readFile(skillMdPath, "utf-8")
+    } catch {
+      continue // skill dir without SKILL.md -- skip
+    }
+    localByFolder.set(s.folderName, {
+      folderName: s.folderName,
+      name: s.name,
+      localPath: s.canonicalPath,
+      hash: sha256(content),
+    })
+  }
+
+  // 3. Scan remote
+  const remote = await scanRemoteSkills(server)
+  const remoteBase = normalizeRemoteBase(server.skillsBasePath)
+
+  // Match remote skills to local folder names by remotePath suffix.
+  // remotePath looks like "<skillsBasePath>/<folderName>/SKILL.md".
+  // We strip the basePath prefix and the "/SKILL.md" suffix to recover folderName.
+  const remoteByFolder = new Map<string, { remotePath: string; hash: string }>()
+  for (const r of remote) {
+    const rp = r.remotePath
+    if (!rp.endsWith("/SKILL.md")) continue
+    // Remove the trailing "/SKILL.md"
+    const skillDir = rp.slice(0, -"/SKILL.md".length)
+    // Try to match by basename so we tolerate "~/.agents/skills" vs "$HOME/..." differences
+    const folderName = path.posix.basename(skillDir)
+    if (!folderName) continue
+    remoteByFolder.set(folderName, { remotePath: rp, hash: r.contentHash })
+  }
+
+  const toAdd: PushPlanEntry[] = []
+  const toUpdate: PushPlanEntry[] = []
+  const unchanged: PushPlanEntry[] = []
+  const toDelete: PushPlanEntry[] = []
+
+  for (const [folderName, local] of localByFolder) {
+    const remoteEntry = remoteByFolder.get(folderName)
+    const remoteDir = `${remoteBase}/${folderName}`
+    const remotePath = `${remoteDir}/SKILL.md`
+    if (!remoteEntry) {
+      toAdd.push({
+        folderName,
+        name: local.name,
+        localPath: local.localPath,
+        remotePath,
+        remoteDir,
+        reason: "added",
+        localHash: local.hash,
+      })
+    } else if (remoteEntry.hash !== local.hash) {
+      toUpdate.push({
+        folderName,
+        name: local.name,
+        localPath: local.localPath,
+        remotePath,
+        remoteDir,
+        reason: "updated",
+        localHash: local.hash,
+        remoteHash: remoteEntry.hash,
+      })
+    } else {
+      unchanged.push({
+        folderName,
+        name: local.name,
+        localPath: local.localPath,
+        remotePath,
+        remoteDir,
+        reason: "unchanged",
+        localHash: local.hash,
+        remoteHash: remoteEntry.hash,
+      })
+    }
+  }
+
+  if (options.mirror) {
+    for (const [folderName, remoteEntry] of remoteByFolder) {
+      if (localByFolder.has(folderName)) continue
+      const remoteDir = `${remoteBase}/${folderName}`
+      toDelete.push({
+        folderName,
+        name: folderName,
+        localPath: "",
+        remotePath: remoteEntry.remotePath,
+        remoteDir,
+        reason: "deleted",
+        remoteHash: remoteEntry.hash,
+      })
+    }
+  }
+
+  return { toAdd, toUpdate, toDelete, unchanged, mirror: options.mirror }
+}
+
+/**
+ * Apply a previously-computed plan. Errors per skill are collected, not thrown,
+ * so a single failure doesn't abort the entire push.
+ */
+export async function applyPush(
+  server: RemoteServer,
+  preview: PushPreview,
+): Promise<PushResult> {
+  const errors: { folderName: string; message: string }[] = []
+  const remoteBase = normalizeRemoteBase(server.skillsBasePath)
+
+  // Uploads (added + updated). Use uploadSkillDir which handles tar pipeline.
+  for (const entry of [...preview.toAdd, ...preview.toUpdate]) {
+    try {
+      await uploadSkillDir(server, CANONICAL_SKILLS_DIR, entry.folderName, remoteBase)
+    } catch (err) {
+      errors.push({
+        folderName: entry.folderName,
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  // Deletions (mirror only)
+  if (preview.mirror) {
+    for (const entry of preview.toDelete) {
+      try {
+        await deleteRemoteSkillDir(server, entry.remoteDir)
+      } catch (err) {
+        errors.push({
+          folderName: entry.folderName,
+          message: err instanceof Error ? err.message : String(err),
+        })
+      }
+    }
+  }
+
+  // Compute counts: subtract failures
+  const failedFolders = new Set(errors.map((e) => e.folderName))
+  return {
+    added: preview.toAdd.filter((e) => !failedFolders.has(e.folderName)).length,
+    updated: preview.toUpdate.filter((e) => !failedFolders.has(e.folderName)).length,
+    deleted: preview.mirror
+      ? preview.toDelete.filter((e) => !failedFolders.has(e.folderName)).length
+      : 0,
+    unchanged: preview.unchanged.length,
+    errors,
+  }
+}

package/src/db/ssh.ts

@@ -299,6 +299,89 @@ function parseDelimitedOutput(output: string): ScannedRemoteSkill[] {
   return skills
 }
 
+/**
+ * Upload an entire local skill directory to the remote server.
+ * Streams `tar -cf - -C <parentLocalDir> <folderName>` into
+ * `tar -xf - -C <remoteBaseDir>` over SSH.
+ *
+ * Both directories must already exist on the remote (caller ensures via mkdir -p).
+ */
+export async function uploadSkillDir(
+  server: RemoteServer,
+  parentLocalDir: string,
+  folderName: string,
+  remoteBaseDir: string,
+): Promise<void> {
+  // Ensure remote base dir exists first
+  const baseQuoted = shellQuotePath(remoteBaseDir)
+  const mkdirResult = await sshExec(server, `mkdir -p ${baseQuoted}`)
+  if (mkdirResult.exitCode !== 0) {
+    throw new Error(
+      mkdirResult.stderr.trim() || `mkdir -p failed for ${remoteBaseDir}`,
+    )
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const tarLocal = spawn("tar", ["-cf", "-", "-C", parentLocalDir, folderName], {
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+
+    const sshArgs = [...buildSshArgs(server), `tar -xf - -C ${baseQuoted}`]
+    const tarRemote = spawn("ssh", sshArgs, {
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 120_000,
+    })
+
+    let localStderr = ""
+    let remoteStderr = ""
+    tarLocal.stderr.on("data", (c: Buffer) => (localStderr += c.toString("utf-8")))
+    tarRemote.stderr.on("data", (c: Buffer) => (remoteStderr += c.toString("utf-8")))
+
+    tarLocal.stdout.pipe(tarRemote.stdin)
+
+    tarLocal.on("error", (err) => reject(err))
+    tarRemote.on("error", (err) => reject(err))
+
+    tarRemote.on("close", (code) => {
+      if ((code ?? 1) === 0) {
+        resolve()
+      } else {
+        reject(
+          new Error(
+            remoteStderr.trim() ||
+              localStderr.trim() ||
+              `tar pipeline exited with code ${code ?? 1}`,
+          ),
+        )
+      }
+    })
+  })
+}
+
+/**
+ * Delete a single skill directory on the remote.
+ * Used only by Mirror mode. Caller is responsible for confirming with the user.
+ */
+export async function deleteRemoteSkillDir(
+  server: RemoteServer,
+  remoteSkillDir: string,
+): Promise<void> {
+  const quoted = shellQuotePath(remoteSkillDir)
+  // Refuse to delete the entire skills base path or anything ending in '/'
+  if (
+    !remoteSkillDir ||
+    remoteSkillDir === "/" ||
+    remoteSkillDir === server.skillsBasePath ||
+    remoteSkillDir === server.skillsBasePath.replace(/\/+$/, "")
+  ) {
+    throw new Error(`Refusing to delete suspicious remote path: ${remoteSkillDir}`)
+  }
+  const result = await sshExec(server, `rm -rf ${quoted}`)
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || `rm -rf failed for ${remoteSkillDir}`)
+  }
+}
+
 // ---------- Sync Orchestrator ----------
 
 export interface SyncResult {

package/src/store/reducers.ts

@@ -10,6 +10,7 @@ export const initialState: AppState = {
   installedSkills: [],
   installedLoading: true,
   installedFilter: "",
+  favorites: [],
   searchQuery: "",
   searchResults: [],
   searchLoading: false,
@@ -61,6 +62,9 @@ export function appReducer(state: AppState, action: Action): AppState {
     case "SET_INSTALLED_FILTER":
       return { ...state, installedFilter: action.filter }
 
+    case "SET_FAVORITES":
+      return { ...state, favorites: action.favorites }
+
     case "SET_SEARCH_QUERY":
       return { ...state, searchQuery: action.query }
 

package/src/store/types.ts

@@ -63,11 +63,14 @@ export interface AppState {
   detectedAgents: DetectedAgent[]
 
   // Installed skills (home view)
-  selectedAgentFilter: string // agent name or "all"
+  selectedAgentFilter: string // agent name, "all", or "favorites"
   installedSkills: EnrichedSkill[]
   installedLoading: boolean
   installedFilter: string
 
+  // Favorites (skill names)
+  favorites: string[]
+
   // Search / discover
   searchQuery: string
   searchResults: unknown[]
@@ -98,6 +101,7 @@ export type Action =
   | { type: "SET_INSTALLED_SKILLS"; skills: EnrichedSkill[] }
   | { type: "SET_INSTALLED_LOADING"; loading: boolean }
   | { type: "SET_INSTALLED_FILTER"; filter: string }
+  | { type: "SET_FAVORITES"; favorites: string[] }
   | { type: "SET_SEARCH_QUERY"; query: string }
   | { type: "SET_SEARCH_RESULTS"; results: unknown[] }
   | { type: "SET_SEARCH_LOADING"; loading: boolean }

package/src/views/home.tsx

@@ -73,8 +73,11 @@ export function HomeView() {
       skills = skills.filter((skill) => ids.has(skill.canonicalPath))
     }
 
-    // Agent filter
-    if (state.selectedAgentFilter !== "all") {
+    // Agent filter (or favorites)
+    if (state.selectedAgentFilter === "favorites") {
+      const favSet = new Set(state.favorites)
+      skills = skills.filter((s) => favSet.has(s.name))
+    } else if (state.selectedAgentFilter !== "all") {
       skills = skills.filter((s) =>
         s.agents.includes(state.selectedAgentFilter as any)
       )
@@ -96,7 +99,7 @@ export function HomeView() {
     }
 
     return skills
-  }, [state.installedSkills, state.selectedAgentFilter, state.installedFilter, selectedCollection, collections, collectionsVersion])
+  }, [state.installedSkills, state.selectedAgentFilter, state.installedFilter, state.favorites, selectedCollection, collections, collectionsVersion])
 
   useKeyboard((key) => {
     if (state.activeView !== "home") return
@@ -383,7 +386,7 @@ function DetailPanel({ skill, collections, selectedCollection }: DetailPanelProp
         <text>{" "}</text>
 
         {/* Shortcut hints */}
-        <text fg={colors.textDim}>v=view detail  d=remove  u=update  n=create skill  c=collections  Tab=switch pane</text>
+        <text fg={colors.textDim}>v=view detail  d=remove  u=update  f=favorite  n=create skill  c=collections  Tab=switch pane</text>
         <text fg={colors.border}>---</text>
 
         {/* SKILL.md content */}

package/src/views/push-dialog.tsx

@@ -0,0 +1,251 @@
+// packages/tui/src/views/push-dialog.tsx
+import { useState } from "react"
+import { useKeyboard } from "@opentui/react"
+import { colors } from "../utils/colors.js"
+import type { RemoteServer } from "../db/servers.js"
+import { planPush, applyPush } from "../db/push.js"
+import type { PushPreview, PushResult } from "../db/push.js"
+
+interface PushDialogProps {
+  server: RemoteServer
+  onClose: (result?: PushResult) => void
+}
+
+type Stage = "choose" | "previewing" | "review" | "applying" | "done" | "error"
+
+/**
+ * TUI push dialog. State machine: choose -> previewing -> review -> applying -> done | error.
+ * Keybindings:
+ *   m      toggle Mirror mode (in choose)
+ *   Enter  advance (choose->preview, review->apply if changes exist)
+ *   Esc    cancel / go back
+ */
+export function PushDialog({ server, onClose }: PushDialogProps) {
+  const [mirror, setMirror] = useState(false)
+  const [stage, setStage] = useState<Stage>("choose")
+  const [preview, setPreview] = useState<PushPreview | null>(null)
+  const [result, setResult] = useState<PushResult | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  const totalChanges =
+    (preview?.toAdd.length ?? 0) +
+    (preview?.toUpdate.length ?? 0) +
+    (preview?.toDelete.length ?? 0)
+
+  useKeyboard((key) => {
+    if (stage === "previewing" || stage === "applying") return // no input while running
+
+    if (key.name === "escape") {
+      if (stage === "review") {
+        // Go back to choose
+        setStage("choose")
+        setPreview(null)
+        return
+      }
+      onClose()
+      return
+    }
+
+    if (stage === "choose") {
+      if (key.name === "m") {
+        setMirror((v) => !v)
+        return
+      }
+      if (key.name === "return") {
+        runPreview()
+        return
+      }
+    }
+
+    if (stage === "review") {
+      if (key.name === "return" && totalChanges > 0) {
+        runApply()
+        return
+      }
+    }
+
+    if (stage === "done" || stage === "error") {
+      if (key.name === "return" || key.name === "escape") {
+        onClose(result ?? undefined)
+        return
+      }
+    }
+  })
+
+  async function runPreview() {
+    setStage("previewing")
+    setError(null)
+    try {
+      const p = await planPush(server, { mirror })
+      setPreview(p)
+      setStage("review")
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+      setStage("error")
+    }
+  }
+
+  async function runApply() {
+    if (!preview) return
+    setStage("applying")
+    setError(null)
+    try {
+      const r = await applyPush(server, preview)
+      setResult(r)
+      setStage("done")
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+      setStage("error")
+    }
+  }
+
+  return (
+    <box
+      style={{
+        width: "100%",
+        height: "100%",
+        justifyContent: "center",
+        alignItems: "center",
+        backgroundColor: colors.bg,
+      }}
+    >
+      <box
+        style={{
+          width: 72,
+          border: true,
+          borderColor: colors.primary,
+          backgroundColor: "#1a1a2e",
+          paddingLeft: 2,
+          paddingRight: 2,
+          paddingTop: 1,
+          paddingBottom: 1,
+          flexDirection: "column",
+        }}
+        title={`Push to ${server.label}`}
+      >
+        {stage === "choose" && (
+          <>
+            <text fg={colors.primary}>
+              <strong>Push to {server.label}</strong>
+            </text>
+            <text>{" "}</text>
+            <text fg={mirror ? colors.textDim : colors.success}>
+              {mirror ? "  " : "> "}[Push] additive — adds/updates only, never deletes
+            </text>
+            <text fg={mirror ? colors.warning : colors.textDim}>
+              {mirror ? "> " : "  "}[Mirror] one-to-one — also deletes remote-only skills
+            </text>
+            <text>{" "}</text>
+            <text fg={colors.textDim}>
+              m=toggle mode  Enter=preview  Esc=cancel
+            </text>
+          </>
+        )}
+
+        {stage === "previewing" && (
+          <>
+            <text fg={colors.textDim}>Computing diff...</text>
+          </>
+        )}
+
+        {stage === "review" && preview && (
+          <>
+            <text fg={colors.primary}>
+              <strong>Preview</strong>
+              {preview.mirror ? (
+                <span fg={colors.warning}> (Mirror mode)</span>
+              ) : null}
+            </text>
+            <text>{" "}</text>
+            <text fg={colors.text}>
+              <span fg={colors.success}>{preview.toAdd.length} to add</span>
+              {"  "}
+              <span fg={colors.warning}>{preview.toUpdate.length} to update</span>
+              {preview.mirror ? (
+                <>
+                  {"  "}
+                  <span fg={colors.error}>{preview.toDelete.length} to delete</span>
+                </>
+              ) : null}
+              {"  "}
+              <span fg={colors.textDim}>{preview.unchanged.length} unchanged</span>
+            </text>
+            <text>{" "}</text>
+            {totalChanges === 0 ? (
+              <text fg={colors.textDim}>Nothing to push — remote already matches local.</text>
+            ) : (
+              <>
+                {preview.toAdd.map((e, i) => (
+                  <text key={`add-${i}`} fg={colors.success}>+ {e.folderName}</text>
+                ))}
+                {preview.toUpdate.map((e, i) => (
+                  <text key={`upd-${i}`} fg={colors.warning}>~ {e.folderName}</text>
+                ))}
+                {preview.toDelete.map((e, i) => (
+                  <text key={`del-${i}`} fg={colors.error}>- {e.folderName}</text>
+                ))}
+              </>
+            )}
+            {preview.mirror && preview.toDelete.length > 0 && (
+              <>
+                <text>{" "}</text>
+                <text fg={colors.error}>
+                  Mirror will delete {preview.toDelete.length} skill{preview.toDelete.length === 1 ? "" : "s"} from remote.
+                </text>
+              </>
+            )}
+            <text>{" "}</text>
+            <text fg={colors.textDim}>
+              {totalChanges > 0
+                ? preview.mirror && preview.toDelete.length > 0
+                  ? "Enter=confirm mirror (destructive)  Esc=back"
+                  : "Enter=apply  Esc=back"
+                : "Esc=close"}
+            </text>
+          </>
+        )}
+
+        {stage === "applying" && (
+          <text fg={colors.textDim}>Pushing to remote...</text>
+        )}
+
+        {stage === "done" && result && (
+          <>
+            <text fg={colors.success}><strong>Push complete</strong></text>
+            <text>{" "}</text>
+            <text fg={colors.text}>
+              <span fg={colors.success}>{result.added} added</span>
+              {"  "}
+              <span fg={colors.warning}>{result.updated} updated</span>
+              {"  "}
+              <span fg={result.deleted > 0 ? colors.error : colors.textDim}>{result.deleted} deleted</span>
+              {"  "}
+              <span fg={colors.textDim}>{result.unchanged} unchanged</span>
+            </text>
+            {result.errors.length > 0 && (
+              <>
+                <text>{" "}</text>
+                <text fg={colors.error}>Errors ({result.errors.length}):</text>
+                {result.errors.map((e, i) => (
+                  <text key={i} fg={colors.error}>  {e.folderName}: {e.message}</text>
+                ))}
+              </>
+            )}
+            <text>{" "}</text>
+            <text fg={colors.textDim}>Enter or Esc to close</text>
+          </>
+        )}
+
+        {stage === "error" && (
+          <>
+            <text fg={colors.error}><strong>Push failed</strong></text>
+            <text>{" "}</text>
+            <text fg={colors.error}>{error || "Unknown error"}</text>
+            <text>{" "}</text>
+            <text fg={colors.textDim}>Enter or Esc to close</text>
+          </>
+        )}
+      </box>
+    </box>
+  )
+}

package/src/views/servers.tsx

@@ -6,6 +6,7 @@ import { ConfirmDialog } from "../components/confirm-dialog.js"
 import { testConnection, syncRemoteServer } from "../db/ssh.js"
 import { colors } from "../utils/colors.js"
 import type { RemoteServer } from "../db/servers.js"
+import { PushDialog } from "./push-dialog.js"
 
 interface ServersViewProps {
   onServerCountChange: (count: number) => void
@@ -40,6 +41,7 @@ export function ServersView({ onServerCountChange }: ServersViewProps) {
   const [serverList, setServerList] = useState<RemoteServer[]>(() => servers.list())
   const [selectedIndex, setSelectedIndex] = useState(0)
   const [pendingAction, setPendingAction] = useState<PendingAction>(null)
+  const [pushTarget, setPushTarget] = useState<RemoteServer | null>(null)
   const [syncing, setSyncing] = useState(false)
   const [syncLog, setSyncLog] = useState<string[] | null>(null)
   const [testing, setTesting] = useState(false)
@@ -67,6 +69,7 @@ export function ServersView({ onServerCountChange }: ServersViewProps) {
     if (state.activeView !== "servers") return
     if (state.showHelp) return
     if (pendingAction) return
+    if (pushTarget) return
     if (syncing || testing) return
 
     // j/k or arrow keys
@@ -116,6 +119,12 @@ export function ServersView({ onServerCountChange }: ServersViewProps) {
       return
     }
 
+    // P = push to selected server
+    if (key.name === "P" && selectedServer) {
+      setPushTarget(selectedServer)
+      return
+    }
+
     // Enter = browse server's skills
     if (key.name === "return" && selectedServer) {
       const count = skillCounts.get(selectedServer.id) ?? 0
@@ -193,6 +202,19 @@ export function ServersView({ onServerCountChange }: ServersViewProps) {
     }
   }, [servers, skills, dispatch, refreshList])
 
+  // Push dialog
+  if (pushTarget) {
+    return (
+      <PushDialog
+        server={pushTarget}
+        onClose={() => {
+          setPushTarget(null)
+          refreshList()
+        }}
+      />
+    )
+  }
+
   // Confirm dialog for delete
   if (pendingAction?.type === "delete") {
     return (
@@ -327,7 +349,7 @@ export function ServersView({ onServerCountChange }: ServersViewProps) {
           {/* Bottom shortcut hints */}
           <box style={{ height: 1, paddingLeft: 1, backgroundColor: colors.bgAlt }}>
             <text fg={colors.textDim}>
-              S=sync  Enter=browse  a=add  e=edit  d=delete  t=test
+              S=sync  P=push  Enter=browse  a=add  e=edit  d=delete  t=test
             </text>
           </box>
         </box>
@@ -400,7 +422,7 @@ function ServerDetailPanel({ server, skillCount }: ServerDetailPanelProps) {
       ) : null}
 
       <text fg={colors.border}>---</text>
-      <text fg={colors.textDim}>S=sync  t=test  e=edit  d=delete  Enter=browse skills</text>
+      <text fg={colors.textDim}>S=sync  P=push  t=test  e=edit  d=delete  Enter=browse skills</text>
     </box>
   )
 }