@lythos/skill-deck 0.6.2 → 0.7.0

package/README.md

@@ -19,7 +19,7 @@ No installation required. `bunx` auto-downloads the package.
 max_cards = 10
 
 [tool]
-skills = ["github.com/lythos-labs/lythoskill/lythoskill-deck"]
+skills = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
 ```
 
 ### skill-deck.toml (full reference)
@@ -31,13 +31,16 @@ working_set = ".claude/skills"      # Where symlinks are created
 cold_pool = "~/.agents/skill-repos" # Where skills are downloaded
 
 [innate]                    # Always-loaded skills
-skills = ["github.com/lythos-labs/lythoskill/lythoskill-deck"]
+skills = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
 
 [tool]                      # Auto-triggered skills
-skills = ["skill-a", "skill-b"]
+skills = [
+  "github.com/mattpocock/skills/skills/engineering/tdd",
+  "github.com/garrytan/gstack",
+]
 
 [combo]                     # Multi-skill bundles
-skills = ["report-generation-combo"]
+skills = ["github.com/anthropics/skills/skills/pdf"]
 
 [transient]                 # Temporary skills with expiry
   [transient.handoff]
@@ -100,7 +103,7 @@ cat > skill-deck.toml << 'EOF'
 max_cards = 10
 
 [tool]
-skills = ["github.com/lythos-labs/lythoskill/lythoskill-deck"]
+skills = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/

package/package.json

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

package/src/add.ts

@@ -15,6 +15,8 @@ import { execSync } from 'node:child_process'
 import { parse as parseToml, stringify as stringifyToml } from '@iarna/toml'
 import { findDeckToml, expandHome } from './link.js'
 
+const CLAUDE_SKILLS_DIR = join(homedir(), '.claude', 'skills')
+
 interface ParsedLocator {
   host: string
   owner: string
@@ -114,29 +116,55 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
   const tmpRepo = join(tmpDir, 'repo')
 
   try {
+    let skillSourceDir: string
+
     if (backend === 'skills.sh' || backend === 'vercel') {
       const skillsShLocator = `${parsed.owner}/${parsed.repo}`
       console.log(`📦 Downloading via skills.sh: ${skillsShLocator}`)
+
+      // Snapshot existing directories in ~/.claude/skills/
+      const beforeDirs = existsSync(CLAUDE_SKILLS_DIR)
+        ? new Set(readdirSync(CLAUDE_SKILLS_DIR, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => e.name))
+        : new Set<string>()
+
       execSync(`npx skills add ${skillsShLocator} -g`, { cwd: tmpDir, stdio: 'inherit' })
+
+      // Detect the newly installed directory
+      const afterDirs = existsSync(CLAUDE_SKILLS_DIR)
+        ? readdirSync(CLAUDE_SKILLS_DIR, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .map(e => e.name)
+        : []
+      const newDirs = afterDirs.filter(d => !beforeDirs.has(d))
+
+      if (newDirs.length === 0) {
+        console.error(`❌ skills.sh installed nothing new to ~/.claude/skills/`)
+        console.error(`   The skill may already be installed, or the install failed.`)
+        process.exit(1)
+      }
+      if (newDirs.length > 1) {
+        console.warn(`⚠️  Multiple new directories detected in ~/.claude/skills/`)
+        console.warn(`   Using the first one: ${newDirs[0]}`)
+      }
+      const installedName = newDirs[0]
+      skillSourceDir = join(CLAUDE_SKILLS_DIR, installedName)
+      console.log(`   Detected install: ${installedName}`)
     } else {
       const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
       console.log(`📦 Cloning: ${gitUrl}`)
       execSync(`git clone --depth 1 ${gitUrl} ${tmpRepo}`, { stdio: 'inherit' })
+      skillSourceDir = tmpRepo
     }
 
-    if (!existsSync(tmpRepo)) {
-      if (backend === 'skills.sh' || backend === 'vercel') {
-        console.error(`❌ skills.sh backend installs globally, not to cold pool.`)
-        console.error(`   Please manually place the skill at: ${targetDir}`)
-        console.error(`   Or use: deck add ${locator} --via git`)
-        process.exit(1)
-      }
-      console.error(`❌ Download failed: expected output not found at ${tmpRepo}`)
+    if (!existsSync(skillSourceDir)) {
+      console.error(`❌ Download failed: expected output not found at ${skillSourceDir}`)
       process.exit(1)
     }
 
     mkdirSync(dirname(targetDir), { recursive: true })
-    renameSync(tmpRepo, targetDir)
+    renameSync(skillSourceDir, targetDir)
 
     const skillDir = findSkillDir(targetDir, parsed.skill)
     if (!skillDir) {

package/src/cli.ts

@@ -15,6 +15,7 @@ const HELP_CONFIG = {
   options: [
     { flag: '--deck <path>', description: 'Specify skill-deck.toml path (default: find upward from cwd)' },
     { flag: '--workdir <dir>', description: 'Specify working directory (default: cwd)' },
+    { flag: '--no-backup', description: 'Skip tar backup when removing non-symlink entries' },
     { flag: '--via <backend>', description: 'Download backend: git (default) | skills.sh' },
   ],
 }
@@ -29,6 +30,7 @@ const viaFlagIdx = args.indexOf('--via')
 const deckPath = deckFlagIdx >= 0 ? args[deckFlagIdx + 1] : undefined
 const workdir = workdirFlagIdx >= 0 ? args[workdirFlagIdx + 1] : undefined
 const via = viaFlagIdx >= 0 ? args[viaFlagIdx + 1] : undefined
+const noBackup = args.includes('--no-backup')
 
 switch (command) {
   case '--help':
@@ -36,7 +38,7 @@ switch (command) {
     console.log(formatHelp(HELP_CONFIG))
     process.exit(0)
   case 'link':
-    linkDeck(deckPath, workdir)
+    linkDeck(deckPath, workdir, noBackup)
     break
   case 'add': {
     const locator = args[1]

package/src/link.ts

@@ -9,13 +9,14 @@
 
 import { parse as parseToml } from "@iarna/toml";
 import YAML from "yaml";
-import { createHash } from "crypto";
+import { createHash } from "node:crypto";
 import {
   existsSync, mkdirSync, readFileSync, readdirSync,
-  symlinkSync, lstatSync, rmSync, writeFileSync,
-} from "fs";
-import { resolve, dirname, join, basename, relative } from "path";
-import { homedir } from "os";
+  symlinkSync, lstatSync, rmSync, statSync, writeFileSync,
+} from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve, dirname, join, basename, relative } from "node:path";
+import { homedir } from "node:os";
 import {
   SkillDeckLockSchema,
   type SkillDeckLock, type LinkedSkill, type ConstraintReport,
@@ -51,7 +52,12 @@ function parseSkillFrontmatter(skillMdPath: string): Record<string, any> {
 
 // ── 冷池查找 ────────────────────────────────────────────────
 
-export function findSource(name: string, coldPool: string, projectDir: string): string | null {
+export interface FindSourceResult {
+  path: string | null;
+  error?: string;
+}
+
+export function findSource(name: string, coldPool: string, projectDir: string): FindSourceResult {
   // 0. Fully-qualified path: host.tld/owner/repo/skill
   //    → cold_pool/host.tld/owner/repo/skills/skill
   //    Also handles host.tld/owner/repo (standalone skill without skills/ subdir)
@@ -65,31 +71,32 @@ export function findSource(name: string, coldPool: string, projectDir: string):
 
     if (skill) {
       const fqPath = join(coldPool, host, owner, repo, "skills", skill);
-      if (existsSync(join(fqPath, "SKILL.md"))) return fqPath;
+      if (existsSync(join(fqPath, "SKILL.md"))) return { path: fqPath };
     }
     // fallback: standalone skill at repo root
     const directPath = join(coldPool, host, owner, repo);
-    if (existsSync(join(directPath, "SKILL.md"))) return directPath;
+    if (existsSync(join(directPath, "SKILL.md"))) return { path: directPath };
   }
 
   // 1. 直接路径
   const direct = resolve(coldPool, name);
-  if (existsSync(join(direct, "SKILL.md"))) return direct;
+  if (existsSync(join(direct, "SKILL.md"))) return { path: direct };
 
   // 2. Monorepo: repo/skill → cold_pool/repo/skills/skill
   if (name.includes("/")) {
     const [repo, ...rest] = name.split("/");
     const mono = join(coldPool, repo, "skills", rest.join("/"));
-    if (existsSync(join(mono, "SKILL.md"))) return mono;
+    if (existsSync(join(mono, "SKILL.md"))) return { path: mono };
   }
 
   // 3. 项目本地: <project>/skills/<name>（build 输出目录，优先级高于扁平扫描）
   const local = resolve(projectDir, "skills", name);
-  if (existsSync(join(local, "SKILL.md"))) return local;
+  if (existsSync(join(local, "SKILL.md"))) return { path: local };
 
   // 4. 扁平扫描: cold_pool/<any-repo>/<name> 或 <any-repo>/skills/<name>
   //    跳过隐藏目录（agent working set、git、配置等）和 node_modules，
   //    避免把 .claude/skills/ 里的 symlink 误判为有效 cold-pool 源
+  const matches: string[] = [];
   try {
     for (const entry of readdirSync(coldPool, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
@@ -97,17 +104,54 @@ export function findSource(name: string, coldPool: string, projectDir: string):
       if (entry.name === 'node_modules') continue;
       const base = join(coldPool, entry.name);
       for (const sub of [join(base, name), join(base, "skills", name)]) {
-        if (existsSync(join(sub, "SKILL.md"))) return sub;
+        if (existsSync(join(sub, "SKILL.md"))) {
+          matches.push(sub);
+        }
       }
     }
   } catch {}
 
-  return null;
+  if (matches.length === 1) {
+    return { path: matches[0] };
+  }
+  if (matches.length > 1) {
+    const candidates = matches.map(m => relative(coldPool, m)).join(', ');
+    return {
+      path: null,
+      error: `Ambiguous skill name "${name}": found ${matches.length} matches (${candidates}). Use fully-qualified name (e.g., github.com/owner/repo/${name})`,
+    };
+  }
+
+  return { path: null };
 }
 
+// ── 备份工具 ────────────────────────────────────────────────
+
+function calculateDirSize(dir: string): number {
+  let total = 0;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        total += calculateDirSize(p);
+      } else if (entry.isFile()) {
+        total += statSync(p).size;
+      }
+    }
+  } catch {}
+  return total;
+}
+
+function formatBackupDate(d: Date): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+const BACKUP_SIZE_THRESHOLD = 100 * 1024 * 1024; // 100MB
+
 // ── 主流程 ──────────────────────────────────────────────────
 
-export function linkDeck(cliDeckPath?: string, cliWorkdir?: string): void {
+export function linkDeck(cliDeckPath?: string, cliWorkdir?: string, noBackup?: boolean): void {
 const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
 const DECK_PATH = cliDeck
   ? resolve(cliDeck)
@@ -150,12 +194,16 @@ const errors: string[] = [];
 for (const section of ["innate", "tool", "combo"] as const) {
   for (const name of (deck[section]?.skills || [])) {
     if (!name || typeof name !== "string") continue;
-    const src = findSource(name, COLD_POOL, PROJECT_DIR);
-    if (!src) {
+    const result = findSource(name, COLD_POOL, PROJECT_DIR);
+    if (result.error) {
+      errors.push(result.error);
+      continue;
+    }
+    if (!result.path) {
       errors.push(`Skill not found: ${name}`);
       continue;
     }
-    declared.push({ name, type: section, sourcePath: src });
+    declared.push({ name, type: section, sourcePath: result.path });
   }
 }
 
@@ -239,23 +287,74 @@ if (
 
 mkdirSync(WORKING_SET, { recursive: true });
 
-// 清理未声明的条目（只删 symlink，防呆）
+// Pre-flight: 备份并清理非 symlink 实体（真实目录/文件）
+const nonSymlinks: string[] = [];
+try {
+  for (const entry of readdirSync(WORKING_SET)) {
+    if (entry.startsWith("_") || entry.startsWith(".")) continue;
+    const entryPath = join(WORKING_SET, entry);
+    try {
+      const st = lstatSync(entryPath);
+      if (!st.isSymbolicLink()) {
+        nonSymlinks.push(entry);
+      }
+    } catch { continue; }
+  }
+} catch {}
+
+if (nonSymlinks.length > 0) {
+  // 计算总大小
+  let totalSize = 0;
+  for (const e of nonSymlinks) {
+    totalSize += calculateDirSize(join(WORKING_SET, e));
+  }
+
+  if (!noBackup && totalSize > BACKUP_SIZE_THRESHOLD) {
+    console.error(`❌ Found ${nonSymlinks.length} real directories in ${relative(PROJECT_DIR, WORKING_SET)} (> 100MB total).`);
+    console.error(`   Manual review required: ${nonSymlinks.join(", ")}`);
+    console.error(`   Use --no-backup to skip backup (removes without saving), or clean up manually.`);
+    process.exit(1);
+  }
+
+  if (!noBackup) {
+    const bakName = `skills.bak.${formatBackupDate(new Date())}.tar.gz`;
+    const bakPath = join(PROJECT_DIR, ".claude", bakName);
+    mkdirSync(join(PROJECT_DIR, ".claude"), { recursive: true });
+
+    const tarArgs = [
+      "czf", bakPath,
+      ...nonSymlinks.map(e => relative(PROJECT_DIR, join(WORKING_SET, e))),
+    ];
+    try {
+      execSync("tar " + tarArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" "), {
+        cwd: PROJECT_DIR,
+        stdio: "pipe",
+      });
+      console.log(`📦 Backed up ${nonSymlinks.length} entr${nonSymlinks.length === 1 ? "y" : "ies"} to .claude/${bakName}`);
+    } catch (err: any) {
+      console.error(`❌ Backup failed: ${err.message || err}`);
+      console.error(`   Use --no-backup to skip backup, or fix the issue and retry.`);
+      process.exit(1);
+    }
+  } else {
+    console.log(`⚠️  --no-backup: removing ${nonSymlinks.length} entr${nonSymlinks.length === 1 ? "y" : "ies"} without backup`);
+  }
+
+  for (const e of nonSymlinks) {
+    rmSync(join(WORKING_SET, e), { recursive: true, force: true });
+  }
+}
+
+// 清理未声明的 symlink
 const declaredNames = new Set(declared.map(d => d.name.split("/")[0]));
 try {
   for (const entry of readdirSync(WORKING_SET)) {
-    if (entry.startsWith("_")) continue;
+    if (entry.startsWith("_") || entry.startsWith(".")) continue;
     if (!declaredNames.has(entry)) {
       const entryPath = join(WORKING_SET, entry);
       try {
         const st = lstatSync(entryPath);
-        if (!st.isSymbolicLink()) {
-          console.warn(`⚠️  Skipping non-symlink entry: ${entry}`);
-          console.warn(`   → ${entry} is a real directory, not a symlink. Deck only manages symlinks.`);
-          const cpRel2 = relative(PROJECT_DIR, COLD_POOL);
-          const cpHint2 = cpRel2 === "" ? `skills/${entry}` : `${cpRel2}/${entry}`;
-          console.warn(`     Move it to your cold pool (${cpHint2}) and run link again.`);
-          continue;
-        }
+        if (!st.isSymbolicLink()) continue; // 已在上文处理
       } catch { continue; }
       rmSync(entryPath, { recursive: true, force: true });
       console.log(`  🗑️  Removed: ${entry}`);
@@ -399,7 +498,7 @@ writeFileSync(LOCK_PATH, JSON.stringify(parsed.data, null, 2) + "\n");
 // ── 报告 ────────────────────────────────────────────────────
 
 console.log("");
-console.log(`✅ Sync complete: ${linkedSkills.length}/${MAX_CARDS} skills`);
+console.log(`✅ Sync complete: ${linkedSkills.length} skill(s) linked (max_cards: ${MAX_CARDS})`);
 console.log(`   lock: ${LOCK_PATH}`);
 if (dirOverlaps.length > 0) {
   console.log(`   ⚠️  ${dirOverlaps.length} directory overlap(s) (see warnings above)`);

package/src/validate.ts

@@ -7,8 +7,8 @@
  */
 
 import { parse as parseToml } from "@iarna/toml";
-import { existsSync, readFileSync } from "fs";
-import { resolve } from "path";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { findDeckToml, expandHome, findSource } from "./link.js";
 
 export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
@@ -73,8 +73,10 @@ export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
       }
       declaredNames.add(name);
 
-      const src = findSource(name, COLD_POOL, PROJECT_DIR);
-      if (!src) {
+      const result = findSource(name, COLD_POOL, PROJECT_DIR);
+      if (result.error) {
+        errors.push(result.error);
+      } else if (!result.path) {
         errors.push(`Skill not found: ${name} (${section})`);
       }
     }