@lythos/skill-deck 0.9.16 → 0.9.18

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.16 <command> [options]
+bunx @lythos/skill-deck@0.9.18 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -53,14 +53,14 @@ expires = "2026-05-01"    # ISO date; warns at ≤14 days
 
 | Situation | Command |
 |-----------|---------|
-| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.16 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.16 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.16 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.16 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.16 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.16 remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.16 prune` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.16 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.18 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.18 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.18 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.18 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.18 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.18 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.18 prune` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.18 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -117,7 +117,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.16 link
+bunx @lythos/skill-deck@0.9.18 link
 ```
 
 ### Key Concepts
@@ -146,7 +146,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.16 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.18 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 |
@@ -255,3 +255,22 @@ Coverage is honest — no gate, no inflation. Agent BDD scenarios run locally on
 ## License
 
 MIT
+
+<!-- test-stats -->
+![pass](https://img.shields.io/badge/71_pass-0_fail-brightgreen) ![coverage](https://img.shields.io/badge/coverage-82%25-yellow)
+
+```
+File | % Funcs | % Lines | Uncovered Line #s
+| --- | --- | --- |
+All files | 74.76 | 81.66 |
+ src/add.ts | 83.33 | 71.17 | 43,45-49,54-58,61-70,86-88,103-105,123-124,132-134,166,170,181-187,195-200
+ src/link.ts | 43.75 | 61.40 | 112-120,125,128-132,140-151,155-156,171-180,189,215-216,219-220,227-234,246-248,253-254,256-270,274-277,280-287,294-296,307-309,316-319,335,343-346,348-353,355-358,360-373,375-376,379-381,416-417,463-470,488-489,497-499,501-507,533-534,546
+ src/parse-deck.ts | 100.00 | 92.45 | 47-50
+ src/prune-plan.ts | 75.00 | 97.27 | 179-181
+ src/prune.ts | 50.00 | 36.21 | 24-26,29-40,44-73,77-90,94-100,111-113,125-126,144,149-150
+ src/refresh-plan.ts | 75.00 | 97.66 | 170-172
+ src/refresh.ts | 85.71 | 87.30 | 43-44,56-58,73,77-78
+ src/remove.ts | 60.00 | 91.53 | 22-24,44
+ src/schema.ts | 100.00 | 100.00 | 
+```
+<!-- /test-stats -->

package/package.json

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

package/src/add.ts

@@ -75,7 +75,8 @@ function resolvePath(p: string): string {
   return resolve(p)
 }
 
-export async function addSkill(locator: string, options: { deck?: string; workdir?: string; alias?: string; type?: string }) {
+export async function addSkill(locator: string, options: { deck?: string; workdir?: string; alias?: string; type?: string; dryRun?: boolean }) {
+  const dryRun = options.dryRun || false
   const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
   const deckPath = options.deck
     ? resolvePath(options.deck)
@@ -99,6 +100,37 @@ export async function addSkill(locator: string, options: { deck?: string; workdi
 
   const targetDir = join(coldPool, parsed.host, parsed.owner, parsed.repo)
 
+  if (dryRun) {
+    const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
+    const alias = options.alias || skillName
+    const skillType = (options.type || 'tool').toLowerCase()
+    const fqPath = parsed.skill
+      ? `${parsed.host}/${parsed.owner}/${parsed.repo}/${parsed.skill}`
+      : `${parsed.host}/${parsed.owner}/${parsed.repo}`
+
+    console.log(`🔎 Dry-run: deck add ${locator}`)
+    console.log(`   Cold pool:  ${coldPool}`)
+    console.log(`   Deck:       ${deckPath}`)
+    console.log()
+    console.log(`📂 Repo status: ${existsSync(join(targetDir, '.git')) ? 'already cloned' : existsSync(targetDir) ? 'dir exists (partial clone?)' : 'not in cold pool'}`)
+    if (!existsSync(join(targetDir, '.git'))) {
+      console.log(`📦 Would clone: https://${parsed.host}/${parsed.owner}/${parsed.repo}.git --depth 1`)
+    }
+    if (parsed.skill) {
+      const skillMd = join(targetDir, parsed.skill, 'SKILL.md')
+      if (existsSync(targetDir) && existsSync(skillMd)) {
+        console.log(`📄 Skill path:  valid — ${skillMd}`)
+      } else if (existsSync(targetDir)) {
+        console.log(`⚠️  Skill path:  NOT FOUND — check repo layout`)
+      }
+    }
+    console.log(`\n📝 Would add to skill-deck.toml:`)
+    console.log(`   [${skillType}.skills.${alias}]`)
+    console.log(`   path = "${fqPath}"`)
+    console.log(`\n💡 Remove --dry-run to execute.`)
+    return
+  }
+
   if (existsSync(targetDir)) {
     console.error(`❌ Already exists in cold pool: ${targetDir}`)
     console.error(`   To update: rm -rf ${targetDir} and re-run`)

package/src/cli.ts

@@ -23,6 +23,7 @@ const alias = aliasFlagIdx >= 0 ? args[aliasFlagIdx + 1] : undefined
 const type = typeFlagIdx >= 0 ? args[typeFlagIdx + 1] : undefined
 const noBackup = args.includes('--no-backup')
 const yes = args.includes('--yes')
+const dryRun = args.includes('--dry-run')
 
 const HELP_CONFIG = {
   binName: 'lythoskill-deck',
@@ -43,6 +44,7 @@ const HELP_CONFIG = {
 
     { flag: '--alias <name>', description: 'Explicit alias for the skill (default: basename of path)' },
     { flag: '--type <type>', description: 'Target section: innate | tool | combo (default: tool)' },
+    { flag: '--dry-run', description: 'Show plan without executing (add, prune)' },
     { flag: '--yes', description: 'Skip interactive confirmation (for prune)' },
   ],
 }
@@ -61,7 +63,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 })
+    await addSkill(locator, { deck: deckPath, workdir, alias, type, dryRun })
     break
   }
   case 'refresh': {

package/src/link.ts

@@ -79,13 +79,14 @@ export function findSource(name: string, coldPool: string, projectDir: string):
     if (existsSync(join(directPath, "SKILL.md"))) return { path: directPath };
   }
 
-  // 0.5 localhost skills: localhost/skill → cold_pool/skill
+  // 0.5 localhost skills: localhost/skill → cold_pool/<skill>
   if (name.startsWith('localhost/')) {
     const skill = name.slice('localhost/'.length);
     if (skill) {
       const localPath = join(coldPool, skill);
       if (existsSync(join(localPath, "SKILL.md"))) return { path: localPath };
     }
+    return { path: null };
   }
 
   // 1. 直接路径
@@ -216,8 +217,32 @@ for (const entry of parsedEntries) {
     continue;
   }
   if (!result.path) {
-    errors.push(`Skill not found: ${entry.path}`);
-    continue;
+    // For localhost skills, create a placeholder so the user can fill it in
+    if (entry.path.startsWith('localhost/')) {
+      const skill = entry.path.slice('localhost/'.length)
+      const localPath = join(COLD_POOL, skill)
+      if (!existsSync(join(localPath, 'SKILL.md'))) {
+        const now = new Date().toISOString().slice(0, 10)
+        const placeholder = [
+          '---', `name: ${skill}`, 'description: TODO — add description', 'type: standard', '---',
+          '', `# ${skill}`,
+          '', '> ⚠️ Placeholder — declared in skill-deck.toml but not yet implemented.',
+          '', '## TODO',
+          '- [ ] Define what this skill does',
+          '- [ ] Add usage instructions',
+          '- [ ] Run `deck link` to activate',
+          '', `Created: ${now}`, '',
+        ].join('\n')
+        mkdirSync(localPath, { recursive: true })
+        writeFileSync(join(localPath, 'SKILL.md'), placeholder)
+        console.log(`📝 Created placeholder: localhost/${skill} → ${localPath}/SKILL.md`)
+        result.path = localPath
+      }
+    }
+    if (!result.path) {
+      errors.push(`Skill not found: ${entry.path}`)
+      continue
+    }
   }
   declared.push({ name: entry.path, alias: entry.alias, type: entry.type, sourcePath: result.path });
 }