@lythos/skill-deck 0.1.8 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.1.8",
+  "version": "0.3.0",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "license": "MIT",
   "type": "module",

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

@@ -17,19 +17,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);
 }
@@ -83,7 +82,7 @@ function extractArrayField(fm: string, field: string): string[] {
 
 // ── 冷池查找 ────────────────────────────────────────────────
 
-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 +160,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 +186,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 +199,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 +220,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 +235,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,9 +244,10 @@ 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;
   }
 
@@ -302,7 +273,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}`);
+}