@lythos/skill-deck 0.7.2 → 0.9.1

package/src/remove.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+/**
+ * deck-remove.ts — Remove a skill from the declaration layer
+ *
+ * Deletes the entry from skill-deck.toml and removes the working-set symlink.
+ * Does NOT touch the cold pool (use `deck prune` for material-layer GC).
+ */
+
+import { parse as parseToml, stringify as stringifyToml } from "@iarna/toml";
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { findDeckToml, expandHome } from "./link.js";
+import { parseDeck } from "./parse-deck.js";
+
+export function removeSkill(target: string, 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 WORKING_SET = expandHome(deck.deck?.working_set || ".claude/skills", PROJECT_DIR);
+
+  // ── 定位目标 ────────────────────────────────────────────────
+
+  const { entries: parsedEntries } = parseDeck(deckRaw);
+
+  // Match by alias first, then by path
+  const match = parsedEntries.find(e => e.alias === target || e.path === target);
+
+  if (!match) {
+    console.error(`❌ Skill not found in deck: ${target}`);
+    const aliases = parsedEntries.map(e => e.alias);
+    if (aliases.length > 0) {
+      console.error(`   Declared aliases: ${aliases.join(", ")}`);
+    }
+    process.exit(1);
+  }
+
+  // ── 删 deck.toml 条目 ───────────────────────────────────────
+
+  const section = match.type;
+  const alias = match.alias;
+
+  if (deck[section]?.skills) {
+    if (Array.isArray(deck[section].skills)) {
+      // Legacy string-array format
+      deck[section].skills = deck[section].skills.filter((name: string) => {
+        const a = name.split("/").pop() || name;
+        return a !== alias;
+      });
+      if (deck[section].skills.length === 0) {
+        delete deck[section].skills;
+      }
+    } else if (typeof deck[section].skills === "object") {
+      // Dict format
+      delete deck[section].skills[alias];
+      if (Object.keys(deck[section].skills).length === 0) {
+        delete deck[section].skills;
+      }
+    }
+    // Clean up empty section
+    if (Object.keys(deck[section] || {}).length === 0) {
+      delete deck[section];
+    }
+  }
+
+  writeFileSync(DECK_PATH, stringifyToml(deck));
+  console.log(`📝 Removed "${alias}" from [${section}.skills] in ${DECK_PATH}`);
+
+  // ── 删 working set symlink ──────────────────────────────────
+
+  const symlinkPath = join(WORKING_SET, alias);
+  if (existsSync(symlinkPath)) {
+    rmSync(symlinkPath, { recursive: true, force: true });
+    console.log(`  🗑️  Removed symlink: ${symlinkPath}`);
+  } else {
+    console.log(`  ⚠️  Symlink not found: ${symlinkPath}`);
+  }
+
+  console.log(`\n💡 Cold pool untouched. Run 'bunx @lythos/skill-deck prune' to GC unreferenced repos.`);
+}

package/src/schema.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 // ── 单个已链接 Skill ────────────────────────────────────────
 export const LinkedSkillSchema = z.object({
   name: z.string(),
+  alias: z.string(),
   deck_niche: z.string(),
   type: z.enum(["innate", "tool", "combo", "transient"]),
   source: z.string(),
@@ -49,6 +50,15 @@ export const SkillDeckLockSchema = z.object({
   constraints: ConstraintReportSchema,
 });
 
+// ── Skill entry (alias-as-key dict body) ──────────────────────
+export const SkillEntrySchema = z.object({
+  path: z.string().min(1),
+  role: z.string().optional(),
+  why_in_deck: z.string().optional(),
+}).passthrough();
+
+export type SkillEntry = z.infer<typeof SkillEntrySchema>;
+
 export type LinkedSkill = z.infer<typeof LinkedSkillSchema>;
 export type ConstraintReport = z.infer<typeof ConstraintReportSchema>;
 export type SkillDeckLock = z.infer<typeof SkillDeckLockSchema>;

package/src/update.ts

@@ -1,154 +1,13 @@
 #!/usr/bin/env bun
 /**
- * deck-update.ts — Update declared skills from their upstream sources
+ * deck-update.ts — Deprecated alias for refresh
  *
- * 读取 skill-deck.toml → 遍历声明的 skill → 对 git 来源执行 pull。
- * 职责：让冷池跟上上游版本。
- * 不做：下载新 skill（那是 add 的职责）、修改 deck.toml、同步 working set。
+ * Kept for backward compatibility. Will be removed in v1.0.0.
  */
 
-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";
+import { refreshDeck } from "./refresh.js";
 
-interface UpdateResult {
-  name: string;
-  path: string;
-  status: "updated" | "up-to-date" | "skipped" | "failed" | "not-git";
-  message?: string;
+export function updateDeck(cliDeckPath?: string, cliWorkdir?: string, target?: string): void {
+  console.warn("⚠️  `deck update` is deprecated. Use `deck refresh` instead. (Removed in v1.0.0)");
+  refreshDeck(cliDeckPath, cliWorkdir, target);
 }
-
-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);
-  }
-}
-

package/src/validate.test.ts

@@ -0,0 +1,160 @@
+#!/usr/bin/env bun
+/**
+ * validate.test.ts — unit tests for validate.ts
+ *
+ * Run: bun test packages/lythoskill-deck/src/validate.test.ts
+ */
+
+import { describe, it, expect, afterEach } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { spawnSync } from 'node:child_process'
+
+let cleanup: string[] = []
+
+afterEach(() => {
+  for (const dir of cleanup) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+  cleanup = []
+})
+
+function makeTmp(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'deck-validate-'))
+  cleanup.push(dir)
+  return dir
+}
+
+function placeSkill(coldPool: string, relPath: string): string {
+  const skillDir = join(coldPool, relPath)
+  mkdirSync(skillDir, { recursive: true })
+  writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: fixture\n---\n')
+  return skillDir
+}
+
+function runValidate(deckPath: string, workdir: string) {
+  return spawnSync('bun', [join(import.meta.dir, 'cli.ts'), 'validate', '--deck', deckPath, '--workdir', workdir], {
+    cwd: workdir,
+    encoding: 'utf-8',
+  })
+}
+
+describe('validateDeck', () => {
+  it('C1: valid deck passes validation', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+
+    placeSkill(coldPool, 'github.com/owner/repo/skill')
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.my-alias]\npath = "github.com/owner/repo/skill"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = runValidate(deckPath, projectDir)
+
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('Validation passed')
+  })
+
+  it('C2: missing [deck] section errors', () => {
+    const projectDir = makeTmp()
+    const deckContent = `[tool.skills.foo]\npath = "github.com/owner/repo/skill"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = runValidate(deckPath, projectDir)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('[deck] section is required')
+  })
+
+  it('C3: invalid max_cards errors', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    placeSkill(coldPool, 'github.com/owner/repo/skill')
+
+    const deckContent = `[deck]\nmax_cards = -1\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.foo]\npath = "github.com/owner/repo/skill"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = runValidate(deckPath, projectDir)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('deck.max_cards must be a positive integer')
+  })
+
+  it('C4: skill not found in cold pool errors', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    mkdirSync(coldPool, { recursive: true })
+    // do NOT place the skill
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.foo]\npath = "github.com/owner/repo/nonexistent"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = runValidate(deckPath, projectDir)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('Skill not found')
+  })
+
+  it('C5: budget exceeded errors', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    placeSkill(coldPool, 'github.com/owner/repo/skill-a')
+    placeSkill(coldPool, 'github.com/owner/repo/skill-b')
+
+    const deckContent = `[deck]\nmax_cards = 1\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo/skill-a"\n\n[tool.skills.skill-b]\npath = "github.com/owner/repo/skill-b"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = runValidate(deckPath, projectDir)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('Budget exceeded')
+  })
+
+  it('C6: toml parse error exits', () => {
+    const projectDir = makeTmp()
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, '[invalid toml\n')
+
+    const result = runValidate(deckPath, projectDir)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('TOML parse error')
+  })
+
+  it('C7: deprecated string-array format warns', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+    placeSkill(coldPool, 'github.com/owner/repo/skill')
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool]\nskills = ["github.com/owner/repo/skill"]\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    const result = runValidate(deckPath, projectDir)
+
+    expect(result.status).toBe(0)
+    expect(result.stderr).toContain('deprecated')
+  })
+
+  it('C8: invalid transient expires errors', () => {
+    const projectDir = makeTmp()
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, `[deck]\nmax_cards = 10\n\n[transient.foo]\npath = "./nonexistent"\nexpires = "not-a-date"\n`)
+
+    const result = runValidate(deckPath, projectDir)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('invalid expires')
+  })
+})

package/src/validate.ts

@@ -10,6 +10,7 @@ import { parse as parseToml } from "@iarna/toml";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { findDeckToml, expandHome, findSource } from "./link.js";
+import { parseDeck } from "./parse-deck.js";
 
 export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
   const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : process.cwd();
@@ -52,33 +53,27 @@ export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
 
   // ── Validate skill declarations ────────────────────────────
 
+  const { entries: parsedEntries, deprecated: isDeprecated, errors: parseErrors } = parseDeck(deckRaw);
+  if (isDeprecated) {
+    warnings.push("string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.");
+  }
+  errors.push(...parseErrors);
+
   const declaredNames = new Set<string>();
   let declaredCount = 0;
 
-  for (const section of ["innate", "tool", "combo"] as const) {
-    const skills = deck[section]?.skills;
-    if (skills === undefined) continue;
-    if (!Array.isArray(skills)) {
-      errors.push(`[${section}].skills must be an array`);
-      continue;
+  for (const entry of parsedEntries) {
+    declaredCount++;
+    if (declaredNames.has(entry.path)) {
+      warnings.push(`Skill "${entry.path}" is declared in multiple sections`);
     }
-    for (const name of skills) {
-      if (!name || typeof name !== "string") {
-        errors.push(`[${section}] contains invalid skill name`);
-        continue;
-      }
-      declaredCount++;
-      if (declaredNames.has(name)) {
-        warnings.push(`Skill "${name}" is declared in multiple sections`);
-      }
-      declaredNames.add(name);
+    declaredNames.add(entry.path);
 
-      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})`);
-      }
+    const result = findSource(entry.path, COLD_POOL, PROJECT_DIR);
+    if (result.error) {
+      errors.push(result.error);
+    } else if (!result.path) {
+      errors.push(`Skill not found: ${entry.path} (${entry.type})`);
     }
   }