@lythos/skill-deck 0.9.28 → 0.9.29

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.28 <command> [options]
+bunx @lythos/skill-deck@0.9.29 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -55,14 +55,14 @@ prompt = "Search for latest info, then generate professional document with diagr
 
 | Situation | Command |
 |-----------|---------|
-| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.28 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.28 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.28 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.28 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.28 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.28 remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.28 prune` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.28 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.29 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.29 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.29 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.29 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.29 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.29 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.29 prune` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.29 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -119,7 +119,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.28 link
+bunx @lythos/skill-deck@0.9.29 link
 ```
 
 ### Key Concepts
@@ -148,7 +148,7 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.9.28 add github.com/owner/repo/skill` or clone manually into cold pool |
+| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.9.29 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 |
 | `refresh` 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 |
 | `deck update` prints deprecation warning | `update` was renamed to `refresh` in v0.8+ | Use `deck refresh` instead |

package/package.json

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

package/src/add.ts

@@ -91,7 +91,7 @@ function exitInvalidLocator(locator: string): never {
 
 export async function addSkill(
   locator: string,
-  options: { deck?: string; workdir?: string; alias?: string; type?: string; dryRun?: boolean },
+  options: { deck?: string; workdir?: string; alias?: string; type?: string; dryRun?: boolean; mode?: 'symlink' | 'snapshot' },
 ) {
   const dryRun = options.dryRun || false
   const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
@@ -245,15 +245,32 @@ export async function addSkill(
     writeFileSync(deckPath, stringifyToml(deck))
     console.log(`📝 Added "${alias}" to [${skillType}.skills] in ${deckPath}`)
   } else {
-    const minimal: Record<string, any> = { deck: { max_cards: 10 } }
+    const header = [
+      '# Skill Deck — generated by lythoskill-deck',
+      '# Edit working_set for your agent platform (uncomment one):',
+      '#   working_set = ".claude/skills"   # Claude Code (also read by Cursor, Copilot)',
+      '#   working_set = ".agents/skills"   # Codex CLI, OpenClaw',
+      '#   working_set = ".cursor/skills"   # Cursor-native',
+      '#   working_set = ".github/skills"   # GitHub Copilot',
+      '#   working_set = ".windsurf/skills" # Windsurf',
+      '# After editing, run:  bunx @lythos/skill-deck@latest link',
+      '',
+    ].join('\n')
+    const minimal: Record<string, any> = {
+      deck: {
+        max_cards: 10,
+        cold_pool: '~/.agents/skill-repos',
+        working_set: '.claude/skills',
+      },
+    }
     minimal[skillType] = { skills: { [alias]: { path: fqPath } } }
-    writeFileSync(deckPath, stringifyToml(minimal))
+    writeFileSync(deckPath, header + stringifyToml(minimal))
     console.log(`📝 Created ${deckPath} with "${alias}"`)
   }
 
   console.log('🔗 Running deck link...')
   const { linkDeck } = await import('./link.js')
-  linkDeck(deckPath, workdir)
+  linkDeck(deckPath, workdir, { mode: options.mode })
 
   // ── Metadata recording (content-level only; deck refs reconciled by link) ─
 

package/src/cli.ts

@@ -29,6 +29,7 @@ const noBackup = args.includes('--no-backup')
 const yes = args.includes('--yes')
 const dryRun = args.includes('--dry-run')
 const remote = args.includes('--remote')
+const mode = flagValue('--mode') as 'symlink' | 'snapshot' | undefined
 
 const HELP_CONFIG = {
   binName: 'lythoskill-deck',
@@ -45,6 +46,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: '--mode <symlink|snapshot>', description: 'Link mode: symlink (default) or snapshot (cp)' },
     { flag: '--no-backup', description: 'Skip tar backup when removing non-symlink entries' },
 
     { flag: '--alias <name>', description: 'Explicit alias for the skill (default: basename of path)' },
@@ -62,7 +64,7 @@ switch (command) {
     console.log(formatHelp(HELP_CONFIG))
     process.exit(0)
   case 'link':
-    linkDeck(deckPath, workdir, noBackup)
+    linkDeck(deckPath, workdir, { noBackup, mode })
     break
   case 'add': {
     const locator = args[1]
@@ -70,7 +72,7 @@ switch (command) {
       console.error('❌ Missing locator. Usage: deck add <github.com/owner/repo[/skill]>')
       process.exit(1)
     }
-    await addSkill(locator, { deck: deckPath, workdir, alias, type, dryRun })
+    await addSkill(locator, { deck: deckPath, workdir, alias, type, dryRun, mode })
     break
   }
   case 'refresh': {

package/src/link.test.ts

@@ -129,7 +129,7 @@ describe('linkDeck reconciler', () => {
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 
-    linkDeck(deckPath, projectDir, true)
+    linkDeck(deckPath, projectDir, { noBackup: true })
 
     const workingSet = join(projectDir, '.claude', 'skills')
     expect(existsSync(workingSet)).toBe(true)
@@ -167,7 +167,7 @@ describe('linkDeck reconciler', () => {
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 
-    linkDeck(deckPath, projectDir, true)
+    linkDeck(deckPath, projectDir, { noBackup: true })
 
     const workingSet = join(projectDir, '.claude', 'skills')
     const symlinkPath = join(workingSet, 'my-alias')
@@ -204,7 +204,7 @@ describe('linkDeck reconciler', () => {
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 
-    linkDeck(deckPath, projectDir, true)
+    linkDeck(deckPath, projectDir, { noBackup: true })
 
     const lock1 = JSON.parse(readFileSync(join(projectDir, 'skill-deck.lock'), 'utf-8'))
     const symlinkPath = join(projectDir, '.claude', 'skills', 'my-alias')
@@ -212,7 +212,7 @@ describe('linkDeck reconciler', () => {
 
     await new Promise(r => setTimeout(r, 50))
 
-    linkDeck(deckPath, projectDir, true)
+    linkDeck(deckPath, projectDir, { noBackup: true })
 
     const lock2 = JSON.parse(readFileSync(join(projectDir, 'skill-deck.lock'), 'utf-8'))
     const target2 = readlinkSync(symlinkPath)
@@ -249,7 +249,7 @@ describe('linkDeck reconciler', () => {
     symlinkSync(skillADir, join(workingSet, 'skill-a'))
     symlinkSync(skillBDir, join(workingSet, 'skill-b'))
 
-    linkDeck(deckPath, projectDir, true)
+    linkDeck(deckPath, projectDir, { noBackup: true })
 
     // skill-a should remain
     expect(existsSync(join(workingSet, 'skill-a'))).toBe(true)
@@ -263,4 +263,26 @@ describe('linkDeck reconciler', () => {
     expect(lock.skills[0].alias).toBe('skill-a')
   })
 
+  it('snapshot mode: cp instead of symlink', () => {
+    const projectDir = makeTmp()
+    const coldPoolRel = 'cold-pool'
+    const coldPool = join(projectDir, coldPoolRel)
+
+    placeSkill(coldPool, 'github.com/owner/repo-a')
+
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.my-alias]\npath = "github.com/owner/repo-a"\n`
+    const deckPath = join(projectDir, 'skill-deck.toml')
+    writeFileSync(deckPath, deckContent)
+
+    linkDeck(deckPath, projectDir, { noBackup: true, mode: 'snapshot' })
+
+    const dest = join(projectDir, '.claude', 'skills', 'my-alias')
+    expect(existsSync(dest)).toBe(true)
+    // Snapshot: real directory, not a symlink
+    expect(lstatSync(dest).isDirectory()).toBe(true)
+    expect(lstatSync(dest).isSymbolicLink()).toBe(false)
+    // Verify content was copied
+    expect(existsSync(join(dest, 'SKILL.md'))).toBe(true)
+  })
+
 })

package/src/link.ts

@@ -12,7 +12,7 @@ import YAML from "yaml";
 import { createHash } from "node:crypto";
 import {
   existsSync, mkdirSync, readFileSync, readdirSync,
-  symlinkSync, lstatSync, rmSync, statSync, writeFileSync,
+  symlinkSync, cpSync, lstatSync, rmSync, statSync, writeFileSync,
 } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { resolve, dirname, join, basename, relative } from "node:path";
@@ -125,7 +125,8 @@ const BACKUP_SIZE_THRESHOLD = 100 * 1024 * 1024; // 100MB
 
 // ── 主流程 ──────────────────────────────────────────────────
 
-export function linkDeck(cliDeckPath?: string, cliWorkdir?: string, noBackup?: boolean): void {
+export function linkDeck(cliDeckPath?: string, cliWorkdir?: string, opts?: { noBackup?: boolean; mode?: 'symlink' | 'snapshot' }): void {
+const MODE = opts?.mode ?? 'symlink'
 const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
 const DECK_PATH = cliDeck
   ? resolve(cliDeck)
@@ -144,7 +145,14 @@ if (!existsSync(DECK_PATH)) {
   process.exit(1);
 }
 
-const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
+// --workdir always wins. --deck (explicit) defaults to cwd: user expects
+// "work here" when pointing to a deck outside the current directory.
+// Default (no flags): deck file's directory (99% of cases = project root).
+const PROJECT_DIR = cliWorkdir
+  ? resolve(cliWorkdir)
+  : cliDeck
+    ? process.cwd()
+    : dirname(DECK_PATH);
 const deckRaw = readFileSync(DECK_PATH, "utf-8");
 const deckHash = hashContent(deckRaw);
 
@@ -333,14 +341,14 @@ if (nonSymlinks.length > 0) {
     totalSize += calculateDirSize(join(WORKING_SET, e));
   }
 
-  if (!noBackup && totalSize > BACKUP_SIZE_THRESHOLD) {
+  if (!opts?.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) {
+  if (!opts?.noBackup) {
     const bakName = `skills.bak.${formatBackupDate(new Date())}.tar.gz`;
     const bakPath = join(PROJECT_DIR, ".claude", bakName);
     mkdirSync(join(PROJECT_DIR, ".claude"), { recursive: true });
@@ -400,7 +408,11 @@ for (const item of declared) {
 
   try {
     mkdirSync(dirname(dest), { recursive: true });
-    symlinkSync(item.sourcePath, dest);
+    if (MODE === 'snapshot') {
+      cpSync(item.sourcePath, dest, { recursive: true });
+    } else {
+      symlinkSync(item.sourcePath, dest);
+    }
   } catch (err: any) {
     console.error(`❌ Link failed: ${item.alias}: ${err.message}`);
     continue;
@@ -540,6 +552,12 @@ try {
 // ── 报告 ────────────────────────────────────────────────────
 
 console.log("");
+console.log(`📋 deck:      ${DECK_PATH}`);
+console.log(`📁 working_set: ${resolvedWorkingSet}`);
+console.log(`🗄️  cold_pool:   ${COLD_POOL}`);
+if (!cliWorkdir && cliDeck && dirname(DECK_PATH) !== process.cwd()) {
+  console.log(`💡 working_set 相对于当前目录。若期望跟随 deck 文件位置，使用 --workdir <dir>`);
+}
 console.log(`✅ Sync complete: ${linkedSkills.length} skill(s) linked (max_cards: ${MAX_CARDS})`);
 console.log(`   lock: ${LOCK_PATH}`);
 if (dirOverlaps.length > 0) {