@lythos/skill-deck 0.1.9 → 0.4.0

package/README.md

@@ -1,40 +1,78 @@
 # @lythos/skill-deck
 
-> Declarative skill deck governance. Reconcile declared skills against your cold pool via symlinks.
+> Declarative skill deck governance for AI agents. Reconcile declared skills against your cold pool via symlinks — deny-by-default, max-cards budgeting, transient expiry.
 
-Part of the [lythoskill](https://github.com/lythos-labs/lythoskill) meta-skill ecosystem.
+## Why
 
-## What it does
+When an AI agent has access to 50+ skills, context window pollution and silent conflicts become real problems. Two skills claiming the same niche, redundant descriptions, incompatible assumptions — all invisible until the agent hallucinates.
 
-Manages your agent's working set of skills. You declare which skills you want in `skill-deck.toml`; `deck link` creates symlinks from the cold pool to `.claude/skills/`. Supports deny-by-default isolation, max_cards budgeting, transient expiry, and managed directory overlap detection.
+`skill-deck.toml` solves this by declaring *exactly* which skills the agent should see. `deck link` creates symlinks from the cold pool to `.claude/skills/` and **removes everything else**. Deny-by-default means undeclared skills physically do not exist in the agent's view.
 
 ## Install
 
 ```bash
 bun add -d @lythos/skill-deck
-# or
+# or use directly
 bunx @lythos/skill-deck <command>
 ```
 
-## Commands
+## Quick Start
 
 ```bash
-# Link declared skills to working set
+# 1. Create a skill-deck.toml
+cat > skill-deck.toml << 'EOF'
+[deck]
+max_cards = 10
+
+[tool]
+skills = ["lythoskill-deck"]
+EOF
+
+# 2. Link — creates symlinks in .claude/skills/
 bunx @lythos/skill-deck link
+```
+
+## Commands
+
+```
+lythoskill-deck — Declarative skill deck governance — cold pool, working set, deny-by-default
 
-# Link with custom deck file
-bunx @lythos/skill-deck link --deck ./my-deck.toml
+Usage: lythoskill-deck link | lythoskill-deck validate [deck.toml]
 
-# Show current deck status
-bunx @lythos/skill-deck status
+Commands:
+  link                  Sync working set with skill-deck.toml
+  validate [deck.toml]  Validate deck configuration
 
-# Migrate from old deck format
-bunx @lythos/skill-deck migrate
+Options:
+  --deck <path>    Specify skill-deck.toml path
+  --workdir <dir>  Specify working directory
 ```
 
+## Key Concepts
+
+| Concept | One-liner |
+|---------|-----------|
+| **Cold Pool** | All downloaded skills (`~/.agents/skill-repos/`). Agent cannot see here. |
+| **skill-deck.toml** | Declares desired state: "this project uses these skills." |
+| **`deck link`** | Reconciler. Makes `.claude/skills/` match the declaration. |
+| **Working Set** | `.claude/skills/` — symlinks only. What the agent actually scans. |
+| **deny-by-default** | Undeclared skills are physically absent from the working set. |
+
+## Skill Documentation
+
+This package is the **Starter** layer (CLI implementation).  
+The agent-visible **Skill** layer documentation is here:  
+[packages/lythoskill-deck/skill/SKILL.md](../../packages/lythoskill-deck/skill/SKILL.md)
+
 ## Architecture
 
-This is the **Starter** layer of the thin-skill pattern. The agent-visible **Skill** layer lives in `packages/lythoskill-deck/skill/` and is built to `skills/lythoskill-deck/`.
+Part of the [lythoskill](https://github.com/lythos-labs/lythoskill) ecosystem — the thin-skill pattern separates heavy logic (this npm package) from lightweight agent instructions (SKILL.md).
+
+```
+Starter (this package) → npm publish → bunx @lythos/skill-deck ...
+Skill   (packages/<name>/skill/)     → build → SKILL.md + thin scripts
+Output  (skills/<name>/)             → git commit → agent-visible skill
+```
 
 ## License
 

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.1.9",
+  "version": "0.4.0",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
+  "keywords": [
+    "ai-agent",
+    "skill",
+    "claude-code",
+    "agent-skills",
+    "llm-tooling",
+    "lythoskill"
+  ],
+  "author": "lythos-labs",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -14,6 +23,16 @@
   ],
   "dependencies": {
     "@iarna/toml": "^2.2.5",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lythos-labs/lythoskill.git",
+    "directory": "packages/lythoskill-deck"
+  },
+  "bugs": {
+    "url": "https://github.com/lythos-labs/lythoskill/issues"
+  },
+  "homepage": "https://github.com/lythos-labs/lythoskill/tree/main/packages/lythoskill-deck#readme"
 }

package/src/cli.ts

@@ -1,5 +1,20 @@
 #!/usr/bin/env bun
 import { linkDeck } from './link.js'
+import { validateDeck } from './validate.js'
+import { formatHelp } from './help.js'
+
+const HELP_CONFIG = {
+  binName: 'lythoskill-deck',
+  description: 'Declarative skill deck governance — cold pool, working set, deny-by-default',
+  commands: [
+    { name: 'link', description: 'Sync working set with skill-deck.toml' },
+    { name: 'validate', description: 'Validate deck configuration', args: '[deck.toml]' },
+  ],
+  options: [
+    { flag: '--deck <path>', description: 'Specify skill-deck.toml path' },
+    { flag: '--workdir <dir>', description: 'Specify working directory' },
+  ],
+}
 
 const command = process.argv[2]
 const deckFlagIdx = process.argv.indexOf('--deck')
@@ -8,10 +23,17 @@ const deckPath = deckFlagIdx >= 0 ? process.argv[deckFlagIdx + 1] : undefined
 const workdir = workdirFlagIdx >= 0 ? process.argv[workdirFlagIdx + 1] : undefined
 
 switch (command) {
+  case '--help':
+  case '-h':
+    console.log(formatHelp(HELP_CONFIG))
+    process.exit(0)
   case 'link':
     linkDeck(deckPath, workdir)
     break
+  case 'validate':
+    validateDeck(deckPath, workdir)
+    break
   default:
-    console.error('Usage: lythoskill-deck link [--deck <path>] [--workdir <dir>]')
+    console.error(formatHelp(HELP_CONFIG))
     process.exit(1)
 }

package/src/help.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+/**
+ * help.ts — Declarative help text formatter
+ *
+ * Commands and options are defined as data (HelpConfig).
+ * formatHelp() produces aligned usage output.
+ * This is the SSOT: build pipeline captures `bun cli.ts --help`
+ * and writes it to skill/references/COMMANDS.md.
+ */
+
+export interface CommandDef {
+  name: string
+  description: string
+  args?: string
+}
+
+export interface OptionDef {
+  flag: string
+  description: string
+}
+
+export interface HelpConfig {
+  binName: string
+  description?: string
+  commands: CommandDef[]
+  options?: OptionDef[]
+}
+
+export function formatHelp(config: HelpConfig): string {
+  const lines: string[] = []
+
+  if (config.description) {
+    lines.push(`${config.binName} -- ${config.description}`)
+    lines.push('')
+  }
+
+  // Usage line
+  const usages = config.commands.map(
+    (c) => `${config.binName} ${c.name}${c.args ? ' ' + c.args : ''}`
+  )
+  lines.push(`Usage: ${usages.join(' | ')}`)
+  lines.push('')
+
+  // Commands
+  lines.push('Commands:')
+  const cmdWidth = Math.max(
+    ...config.commands.map((c) => c.name.length + (c.args ? c.args.length + 1 : 0))
+  )
+  for (const cmd of config.commands) {
+    const left = `  ${cmd.name}${cmd.args ? ' ' + cmd.args : ''}`
+    const pad = ' '.repeat(Math.max(cmdWidth - left.length + 4, 2))
+    lines.push(`${left}${pad}${cmd.description}`)
+  }
+
+  // Options
+  if (config.options && config.options.length > 0) {
+    lines.push('')
+    lines.push('Options:')
+    const optWidth = Math.max(...config.options.map((o) => o.flag.length))
+    for (const opt of config.options) {
+      const left = `  ${opt.flag}`
+      const pad = ' '.repeat(Math.max(optWidth - left.length + 4, 2))
+      lines.push(`${left}${pad}${opt.description}`)
+    }
+  }
+
+  return lines.join('\n')
+}

package/src/link.ts

@@ -8,6 +8,7 @@
  */
 
 import { parse as parseToml } from "@iarna/toml";
+import YAML from "yaml";
 import { createHash } from "crypto";
 import {
   existsSync, mkdirSync, readFileSync, readdirSync,
@@ -17,19 +18,18 @@ import { resolve, dirname, join } from "path";
 import { homedir } from "os";
 import {
   SkillDeckLockSchema,
-  SkillDeckTomlSchema,
   type SkillDeckLock, type LinkedSkill, type ConstraintReport,
 } from "./schema.js";
 
 // ── 路径工具 ────────────────────────────────────────────────
 
-function findDeckToml(from: string): string | null {
+export function findDeckToml(from: string): string | null {
   const p = join(from, "skill-deck.toml");
   if (existsSync(p)) return p;
   return null;
 }
 
-function expandHome(p: string, base: string): string {
+export function expandHome(p: string, base: string): string {
   if (p.startsWith("~/")) return join(homedir(), p.slice(2));
   return resolve(base, p);
 }
@@ -37,53 +37,21 @@ function expandHome(p: string, base: string): string {
 function hashContent(content: string): string {
   return createHash("sha256").update(content).digest("hex");
 }
-
 // ── Front matter 提取 ───────────────────────────────────────
 
-function getFrontMatter(skillMdPath: string): string {
+function parseSkillFrontmatter(skillMdPath: string): Record<string, any> {
   try {
     const c = readFileSync(skillMdPath, "utf-8");
-    if (!c.startsWith("---")) return "";
-    const parts = c.split("---");
-    return parts.length >= 3 ? parts[1] : "";
-  } catch { return ""; }
+    const match = c.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+    if (!match) return {};
+    return YAML.parse(match[1]) || {};
+  } catch { return {}; }
 }
 
-function extractField(fm: string, field: string): string {
-  const m = fm.match(new RegExp(`^${field}:\\s*(.+)$`, "m"));
-  return m ? m[1].trim() : "";
-}
-
-function extractArrayField(fm: string, field: string): string[] {
-  const lines = fm.split("\n");
-  const results: string[] = [];
-  let collecting = false;
-  for (const line of lines) {
-    if (line.match(new RegExp(`^${field}:\\s*$`))) {
-      collecting = true;
-      continue;
-    }
-    if (line.match(new RegExp(`^${field}:\\s*\\[`))) {
-      const inline = line.match(/\[(.+)\]/);
-      if (inline) return inline[1].split(",").map(s => s.trim().replace(/^["']|["']$/g, ""));
-      collecting = true;
-      continue;
-    }
-    if (collecting) {
-      const item = line.match(/^\s+-\s+(.+)/);
-      if (item) {
-        results.push(item[1].trim().replace(/^["']|["']$/g, ""));
-      } else if (line.trim() !== "" && !line.match(/^\s*#/)) {
-        break;
-      }
-    }
-  }
-  return results;
-}
 
 // ── 冷池查找 ────────────────────────────────────────────────
 
-function findSource(name: string, coldPool: string, projectDir: string): string | null {
+export function findSource(name: string, coldPool: string, projectDir: string): string | null {
   // 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)
@@ -161,44 +129,16 @@ if (!existsSync(DECK_PATH)) {
 const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
 const deckRaw = readFileSync(DECK_PATH, "utf-8");
 const deckHash = hashContent(deckRaw);
-const parsedToml = parseToml(deckRaw) as any;
-
-// 预处理：TOML 解析器可能在空表上生成 Symbol 键，先清理
-function stripSymbols(obj: any): any {
-  if (obj == null) return obj;
-  if (Array.isArray(obj)) return obj.map(stripSymbols);
-  if (typeof obj === 'object') {
-    const clean: Record<string, any> = {};
-    for (const key of Object.keys(obj)) {
-      clean[key] = stripSymbols(obj[key]);
-    }
-    return clean;
-  }
-  return obj;
-}
-const cleanToml = stripSymbols(parsedToml);
-
-// Schema 校验：防止模板与运行时解析漂移
-const schemaResult = SkillDeckTomlSchema.safeParse(cleanToml);
-if (!schemaResult.success) {
-  console.error("❌ skill-deck.toml 格式错误:");
-  for (const issue of schemaResult.error.issues) {
-    const path = issue.path.map(String).filter(p => p !== "undefined").join(".") || "<root>";
-    console.error(`   ${path}: ${issue.message}`);
-  }
-  process.exit(1);
-}
-const deck = schemaResult.data;
+const deck = parseToml(deckRaw) as any;
 
-const WORKING_SET = expandHome(deck.deck.working_set, PROJECT_DIR);
-const COLD_POOL = expandHome(deck.deck.cold_pool, PROJECT_DIR);
-const MAX_CARDS = deck.deck.max_cards;
+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 MAX_CARDS = Number(deck.deck?.max_cards || 10);
 
 // ── 收集声明 ────────────────────────────────────────────────
 
 interface DeclaredSkill {
-  name: string;          // 完整声明名（如 github.com/.../lythoskill-deck）
-  baseName: string;      // working set 中的目录名（如 lythoskill-deck）
+  name: string;
   type: "innate" | "tool" | "combo" | "transient";
   sourcePath: string;
   expires?: string;
@@ -215,8 +155,7 @@ for (const section of ["innate", "tool", "combo"] as const) {
       errors.push(`skill 未找到: ${name}`);
       continue;
     }
-    const baseName = name.split("/").pop() || name;
-    declared.push({ name, baseName, type: section, sourcePath: src });
+    declared.push({ name, type: section, sourcePath: src });
   }
 }
 
@@ -229,7 +168,7 @@ for (const [key, value] of Object.entries(deck.transient || {})) {
     errors.push(`transient 路径不存在: ${key} → ${src}`);
     continue;
   }
-  declared.push({ name: key, baseName: key, type: "transient", sourcePath: src, expires: t.expires });
+  declared.push({ name: key, type: "transient", sourcePath: src, expires: t.expires });
 }
 
 if (errors.length > 0) {
@@ -250,11 +189,11 @@ if (declared.length > MAX_CARDS) {
 mkdirSync(WORKING_SET, { recursive: true });
 
 // 清理未声明的条目
-const declaredBaseNames = new Set(declared.map(d => d.baseName));
+const declaredNames = new Set(declared.map(d => d.name.split("/")[0]));
 try {
   for (const entry of readdirSync(WORKING_SET)) {
     if (entry.startsWith("_")) continue;
-    if (!declaredBaseNames.has(entry)) {
+    if (!declaredNames.has(entry)) {
       rmSync(join(WORKING_SET, entry), { recursive: true, force: true });
       console.log(`  🗑️  移除: ${entry}`);
     }
@@ -265,7 +204,7 @@ try {
 const linkedSkills: LinkedSkill[] = [];
 
 for (const item of declared) {
-  const dest = join(WORKING_SET, item.baseName);
+  const dest = join(WORKING_SET, item.name);
 
   // 幂等：已存在则删除重建（lstat 不跟随 symlink，能处理断链/自引用 symlink）
   try {
@@ -274,17 +213,22 @@ for (const item of declared) {
   } catch {}
 
   try {
+    mkdirSync(dirname(dest), { recursive: true });
     symlinkSync(item.sourcePath, dest);
   } catch (err: any) {
-    console.error(`❌ 链接失败: ${item.baseName}: ${err.message}`);
+    console.error(`❌ 链接失败: ${item.name}: ${err.message}`);
     continue;
   }
 
   // 提取元数据
   const skillMdPath = join(item.sourcePath, "SKILL.md");
-  const fm = getFrontMatter(skillMdPath);
-  const niche = extractField(fm, "deck_niche");
-  const managedDirs = extractArrayField(fm, "deck_managed_dirs");
+  const fm = parseSkillFrontmatter(skillMdPath);
+  const niche = String(fm["deck_niche"] || "");
+  const managedDirs = Array.isArray(fm["deck_managed_dirs"])
+    ? fm["deck_managed_dirs"].map(String)
+    : fm["deck_managed_dirs"]
+      ? [String(fm["deck_managed_dirs"])]
+      : [];
   let contentHash: string | undefined;
   try {
     contentHash = hashContent(readFileSync(skillMdPath, "utf-8"));
@@ -302,7 +246,7 @@ for (const item of declared) {
     deck_managed_dirs: managedDirs,
   });
 
-  console.log(`  🔗 ${item.baseName}`);
+  console.log(`  🔗 ${item.name}`);
 }
 
 // ── Transient 过期检查 ──────────────────────────────────────

package/src/schema.ts

@@ -1,30 +1,5 @@
 import { z } from "zod";
 
-// ── skill-deck.toml 声明文件 Schema ─────────────────────────
-// 防止模板与运行时解析漂移（template drift）
-
-export const SkillDeckTomlSchema = z.object({
-  deck: z.object({
-    working_set: z.string().default(".claude/skills"),
-    cold_pool: z.string().default("~/.agents/skill-repos"),
-    max_cards: z.number().int().min(1).default(10),
-  }),
-  innate: z.object({
-    skills: z.array(z.string()).default([]),
-  }).optional(),
-  tool: z.object({
-    skills: z.array(z.string()).default([]),
-  }).optional(),
-  combo: z.object({
-    skills: z.array(z.string()).default([]),
-  }).optional(),
-  // transient: 动态子表，key 是 skill 名，value 是任意配置
-  // 用 z.any() 避免空 [transient] 导致 record key 验证失败
-  transient: z.record(z.string(), z.any()).optional(),
-});
-
-export type SkillDeckToml = z.infer<typeof SkillDeckTomlSchema>;
-
 // ── 单个已链接 Skill ────────────────────────────────────────
 export const LinkedSkillSchema = z.object({
   name: z.string(),

package/src/validate.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env bun
+/**
+ * deck-validate.ts — Skill Deck configuration validator
+ *
+ * 读取 skill-deck.toml → 校验 schema、引用有效性、约束合规性。
+ * 不做：创建 symlink、修改文件系统。
+ */
+
+import { parse as parseToml } from "@iarna/toml";
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { findDeckToml, expandHome, findSource } from "./link.js";
+
+export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
+  const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : process.cwd();
+  const DECK_PATH = cliDeckPath
+    ? resolve(cliDeckPath)
+    : findDeckToml(PROJECT_DIR) || resolve(PROJECT_DIR, "skill-deck.toml");
+
+  if (!existsSync(DECK_PATH)) {
+    console.error(`❌ skill-deck.toml not found: ${DECK_PATH}`);
+    process.exit(1);
+  }
+
+  const deckRaw = readFileSync(DECK_PATH, "utf-8");
+  let deck: any;
+  try {
+    deck = parseToml(deckRaw);
+  } catch (err: any) {
+    console.error(`❌ TOML parse error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // ── Validate deck section ──────────────────────────────────
+
+  if (!deck.deck || typeof deck.deck !== "object") {
+    errors.push("[deck] section is required");
+  } else {
+    const maxCards = deck.deck.max_cards;
+    if (maxCards === undefined) {
+      errors.push("deck.max_cards is required");
+    } else if (!Number.isInteger(maxCards) || maxCards < 1) {
+      errors.push(`deck.max_cards must be a positive integer, got ${maxCards}`);
+    }
+  }
+
+  const COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
+  const MAX_CARDS = Number(deck.deck?.max_cards || 10);
+
+  // ── Validate skill declarations ────────────────────────────
+
+  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 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);
+
+      const src = findSource(name, COLD_POOL, PROJECT_DIR);
+      if (!src) {
+        errors.push(`Skill not found: ${name} (${section})`);
+      }
+    }
+  }
+
+  // ── Validate transient section ─────────────────────────────
+
+  const transientCount = Object.keys(deck.transient || {}).length;
+  if (deck.transient) {
+    for (const [key, value] of Object.entries(deck.transient)) {
+      const t = value as any;
+      if (!t || typeof t !== "object") {
+        errors.push(`transient.${key} must be a table`);
+        continue;
+      }
+      if (!t.path) {
+        errors.push(`transient.${key} missing required field: path`);
+        continue;
+      }
+      const src = resolve(PROJECT_DIR, t.path);
+      if (!existsSync(src)) {
+        errors.push(`transient path does not exist: ${key} → ${src}`);
+      }
+      if (t.expires) {
+        const d = new Date(t.expires);
+        if (isNaN(d.getTime())) {
+          errors.push(`transient.${key} has invalid expires format: ${t.expires}`);
+        }
+      }
+    }
+  }
+
+  // ── Budget check ───────────────────────────────────────────
+
+  const total = declaredCount + transientCount;
+  if (total > MAX_CARDS) {
+    errors.push(`Budget exceeded: declared ${total} skill(s), max_cards = ${MAX_CARDS}`);
+  }
+
+  // ── Report ─────────────────────────────────────────────────
+
+  if (warnings.length > 0) {
+    for (const w of warnings) console.warn(`⚠️  ${w}`);
+  }
+
+  if (errors.length > 0) {
+    for (const e of errors) console.error(`❌ ${e}`);
+    console.error(`\n❌ Validation failed: ${errors.length} error(s)`);
+    process.exit(1);
+  }
+
+  console.log(`✅ Validation passed: ${total} skill(s), max_cards = ${MAX_CARDS}`);
+}