@lythos/skill-deck 0.7.0 → 0.7.2

package/README.md

@@ -55,6 +55,7 @@ skills = ["github.com/anthropics/skills/skills/pdf"]
 | Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck link` |
 | Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck validate` |
 | Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck update` |
 | Use a custom deck file or working dir | `bunx @lythos/skill-deck link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
@@ -64,6 +65,7 @@ skills = ["github.com/anthropics/skills/skills/pdf"]
 | `link` | `[--deck <path>] [--workdir <dir>]` | Sync working set. Removes undeclared skills (deny-by-default). |
 | `validate` | `[deck.toml] [--workdir <dir>]` | Validate deck config without modifying files. |
 | `add` | `<locator> [--via <backend>] [--deck <path>]` | Download skill to cold pool and append to skill-deck.toml. |
+| `update` | `[--deck <path>]` | Pull latest versions of declared skills from upstream git repos. |
 
 ### Options
 
@@ -138,6 +140,7 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 |---------|-------|-----|
 | `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck add github.com/owner/repo/skill` or clone manually into cold pool |
 | `link` skips entries with warnings | Real files/directories exist in working set (not symlinks) | Delete the real directories in `working_set` and re-run `link`. Never create directories manually there |
+| `update` reports "Not a git repository" | Skill was copied (not cloned) into cold pool | Re-clone with `git clone` or use `deck add` which clones by default |
 | `link` refuses with "budget exceeded" | Declared skills > `max_cards` | Increase `max_cards` in `skill-deck.toml` or remove unused skills |
 | `link` refuses with "unsafe working_set" | `working_set` resolves to `~` or `/` | Check `skill-deck.toml` has correct relative path (e.g. `.claude/skills/`) |
 | Agent doesn't see skills after `link` | `working_set` path doesn't match agent's scan location | Claude Code: `.claude/skills/`; Cursor: `.cursor/skills/`; Kimi: check your platform docs. Set `working_set` correctly |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.7.0",
-  "description": "Declarative skill deck governance \u2014 cold pool, working set, deny-by-default",
+  "version": "0.7.2",
+  "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",
     "skill",

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { linkDeck } from './link.js'
 import { validateDeck } from './validate.js'
 import { addSkill } from './add.js'
+import { updateDeck } from './update.js'
 import { formatHelp } from './help.js'
 
 const HELP_CONFIG = {
@@ -10,6 +11,7 @@ const HELP_CONFIG = {
   commands: [
     { name: 'link', description: 'Sync working set with skill-deck.toml' },
     { name: 'add', description: 'Download skill to cold pool and add to deck', args: '<locator>' },
+    { name: 'update', description: 'Pull latest versions of declared skills from upstream' },
     { name: 'validate', description: 'Validate deck configuration', args: '[deck.toml]' },
   ],
   options: [
@@ -49,6 +51,9 @@ switch (command) {
     await addSkill(locator, { via, deck: deckPath, workdir })
     break
   }
+  case 'update':
+    updateDeck(deckPath, workdir)
+    break
   case 'validate':
     validateDeck(deckPath, workdir)
     break

package/src/link.ts

@@ -175,8 +175,10 @@ const deckRaw = readFileSync(DECK_PATH, "utf-8");
 const deckHash = hashContent(deckRaw);
 const deck = parseToml(deckRaw) as any;
 
-const WORKING_SET = expandHome(deck.deck?.working_set || ".claude/skills", PROJECT_DIR);
-const COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
+const WORKING_SET_RAW = deck.deck?.working_set || ".claude/skills";
+const COLD_POOL_RAW = deck.deck?.cold_pool || "~/.agents/skill-repos";
+const WORKING_SET = expandHome(WORKING_SET_RAW, PROJECT_DIR);
+const COLD_POOL = expandHome(COLD_POOL_RAW, PROJECT_DIR);
 const MAX_CARDS = Number(deck.deck?.max_cards || 10);
 
 // ── 收集声明 ────────────────────────────────────────────────
@@ -396,12 +398,17 @@ for (const item of declared) {
     contentHash = hashContent(readFileSync(skillMdPath, "utf-8"));
   } catch {}
 
+  // source: relative to cold_pool (non-transient) or project dir (transient)
+  const sourceRel = item.type === "transient"
+    ? relative(PROJECT_DIR, item.sourcePath)
+    : relative(COLD_POOL, item.sourcePath);
+
   linkedSkills.push({
     name: item.name,
     deck_niche: niche,
     type: item.type,
-    source: item.sourcePath,
-    dest,
+    source: sourceRel,
+    dest: relative(PROJECT_DIR, dest),
     content_hash: contentHash,
     linked_at: new Date().toISOString(),
     ...(item.expires ? { expires: item.expires } : {}),
@@ -479,9 +486,9 @@ const constraints: ConstraintReport = {
 const lock: SkillDeckLock = {
   version: "1.0.0",
   generated_at: new Date().toISOString(),
-  deck_source: { path: DECK_PATH, content_hash: deckHash },
-  working_set: WORKING_SET,
-  cold_pool: COLD_POOL,
+  deck_source: { path: relative(PROJECT_DIR, DECK_PATH), content_hash: deckHash },
+  working_set: WORKING_SET_RAW,
+  cold_pool: COLD_POOL_RAW,
   skills: linkedSkills,
   constraints,
 };

package/src/update.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env bun
+/**
+ * deck-update.ts — Update declared skills from their upstream sources
+ *
+ * 读取 skill-deck.toml → 遍历声明的 skill → 对 git 来源执行 pull。
+ * 职责：让冷池跟上上游版本。
+ * 不做：下载新 skill（那是 add 的职责）、修改 deck.toml、同步 working set。
+ */
+
+import { parse as parseToml } from "@iarna/toml";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve, dirname, join, relative } from "node:path";
+import { findDeckToml, expandHome, findSource } from "./link.js";
+
+interface UpdateResult {
+  name: string;
+  path: string;
+  status: "updated" | "up-to-date" | "skipped" | "failed" | "not-git";
+  message?: string;
+}
+
+function isGitRepo(dir: string): boolean {
+  return existsSync(join(dir, ".git"));
+}
+
+function gitPull(dir: string): { status: "updated" | "up-to-date" | "failed"; message: string } {
+  try {
+    const output = execSync("git pull", {
+      cwd: dir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 30000,
+    }).trim();
+
+    if (output.includes("Already up to date") || output.includes("Already up-to-date")) {
+      return { status: "up-to-date", message: output };
+    }
+    return { status: "updated", message: output };
+  } catch (err: any) {
+    const stderr = err.stderr?.toString() || err.message || "";
+    return { status: "failed", message: stderr.trim() };
+  }
+}
+
+export function updateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
+  const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
+  const DECK_PATH = cliDeck
+    ? resolve(cliDeck)
+    : findDeckToml(process.cwd()) || resolve("skill-deck.toml");
+
+  if (!existsSync(DECK_PATH)) {
+    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`);
+    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
+    process.exit(1);
+  }
+
+  const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
+  const deckRaw = readFileSync(DECK_PATH, "utf-8");
+  const deck = parseToml(deckRaw) as any;
+
+  const COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
+
+  // ── 收集声明 ────────────────────────────────────────────────
+
+  const declared: { name: string; type: string }[] = [];
+
+  for (const section of ["innate", "tool", "combo"] as const) {
+    for (const name of (deck[section]?.skills || [])) {
+      if (!name || typeof name !== "string") continue;
+      declared.push({ name, type: section });
+    }
+  }
+
+  if (declared.length === 0) {
+    console.log("📭 No skills declared in deck. Nothing to update.");
+    process.exit(0);
+  }
+
+  // ── 执行更新 ────────────────────────────────────────────────
+
+  const results: UpdateResult[] = [];
+  let updated = 0;
+  let upToDate = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const { name, type } of declared) {
+    const result = findSource(name, COLD_POOL, PROJECT_DIR);
+
+    if (result.error || !result.path) {
+      results.push({ name, path: "", status: "failed", message: result.error || "Skill not found" });
+      failed++;
+      continue;
+    }
+
+    const path = result.path;
+
+    // localhost skills are user-managed; skip
+    const relativePath = relative(COLD_POOL, path);
+    if (relativePath.startsWith("localhost")) {
+      results.push({ name, path: relativePath, status: "skipped", message: "localhost skill — user-managed" });
+      skipped++;
+      continue;
+    }
+
+    if (!isGitRepo(path)) {
+      results.push({ name, path: relativePath, status: "not-git", message: "Not a git repository" });
+      skipped++;
+      continue;
+    }
+
+    const pullResult = gitPull(path);
+    results.push({ name, path: relativePath, status: pullResult.status, message: pullResult.message });
+
+    if (pullResult.status === "updated") updated++;
+    else if (pullResult.status === "up-to-date") upToDate++;
+    else failed++;
+  }
+
+  // ── 报告 ────────────────────────────────────────────────────
+
+  console.log(`\n📦 Skill Update Report — ${declared.length} skill(s) checked`);
+  console.log(`   Updated: ${updated} | Up-to-date: ${upToDate} | Skipped: ${skipped} | Failed: ${failed}`);
+  console.log();
+
+  for (const r of results) {
+    const icon =
+      r.status === "updated" ? "🔄" :
+      r.status === "up-to-date" ? "✅" :
+      r.status === "skipped" ? "⏭️" :
+      r.status === "not-git" ? "📁" :
+      "❌";
+    console.log(`${icon} ${r.name}`);
+    if (r.message && r.status !== "up-to-date") {
+      const lines = r.message.split("\n").filter(l => l.trim());
+      for (const line of lines.slice(0, 3)) {
+        console.log(`   ${line.trim()}`);
+      }
+      if (lines.length > 3) {
+        console.log(`   ... (${lines.length - 3} more lines)`);
+      }
+    }
+  }
+
+  if (updated > 0) {
+    console.log(`\n💡 Run 'bunx @lythos/skill-deck link' to sync updated skills to working set.`);
+  }
+
+  if (failed > 0) {
+    process.exit(1);
+  }
+}
+