@lythos/skill-deck 0.9.32 → 0.9.36

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.32 <command> [options]
+bunx @lythos/skill-deck@0.9.36 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -55,17 +55,17 @@ 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.32 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.32 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.32 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.32 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.32 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.32 remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.32 prune` |
-| Switch skill from snapshot to sync mode | `bunx @lythos/skill-deck@0.9.32 sync tdd` |
-| Switch skill from sync to snapshot mode | `bunx @lythos/skill-deck@0.9.32 freeze tdd` |
-| Check cold pool for drift vs lock file | `bunx @lythos/skill-deck@0.9.32 reconcile` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.32 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.36 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.36 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.36 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.36 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.36 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.36 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.36 prune` |
+| Switch skill from snapshot to sync mode | `bunx @lythos/skill-deck@0.9.36 sync tdd` |
+| Switch skill from sync to snapshot mode | `bunx @lythos/skill-deck@0.9.36 freeze tdd` |
+| Check cold pool for drift vs lock file | `bunx @lythos/skill-deck@0.9.36 reconcile` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.36 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -94,7 +94,7 @@ prompt = "Search for latest info, then generate professional document with diagr
 
 ### Safety guards
 
-`link` refuses to operate if `working_set` resolves to your home directory or root (`/`). It also only removes **symlinks** from the working set — real files or directories are skipped with a warning.
+`link` refuses to operate if `working_set` resolves to your home directory or root (`/`).
 
 **Snapshot mode** (`--mode snapshot` or `link --mode snapshot`): copies the source directory into the working set instead of symlinking. This is needed for agents that don't support symlinks (e.g. Codex #11314). Snapshots are pinned to the cold pool version at link time. Use `deck sync <alias>` to switch back to live symlink mode, or `deck freeze <alias>` to pin a symlink as a snapshot.
 
@@ -128,7 +128,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.32 link
+bunx @lythos/skill-deck@0.9.36 link
 ```
 
 ### Key Concepts
@@ -138,7 +138,7 @@ bunx @lythos/skill-deck@0.9.32 link
 | **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 the working set match the declaration. |
-| **Working Set** | Symlinks only. Default: `.claude/skills/` — where agents scan for skills. |
+| **Working Set** | Per-skill mode: symlink (live) or snapshot (pinned copy). Default: `.claude/skills/`. |
 | **deny-by-default** | Undeclared skills are physically absent from the working set. |
 
 ### Agent skill scan locations
@@ -157,7 +157,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.32 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.36 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 |
@@ -222,7 +222,7 @@ If you already have skills installed (in working set, globally, or mixed), deck
 3. BACKUP  Always. `link` creates tar backups for non-symlink entries before removal.
            Use `--no-backup` only if you're certain.
 
-4. EXECUTE deck link — creates symlinks, removes undeclared, leaves real files untouched.
+4. EXECUTE deck link — creates symlinks (default) or snapshots (--mode snapshot), removes undeclared entries.
 
 5. VERIFY  Agent checks: all declared skills resolve? Working set clean?
            If unhappy: tar xf backup → rollback to pre-migration state.

package/package.json

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

package/src/cli.ts

@@ -9,6 +9,7 @@ import { removeSkill } from './remove.js'
 import { pruneDeck } from './prune.js'
 import { syncSkill, freezeSkill } from './sync-freeze.js'
 import { reconcileDeck } from './reconcile.js'
+import { resolveDeckPathSync, fetchDeckUrl, isUrl } from './resolve-deck.js'
 import { formatHelp } from './help.js'
 
 const args = process.argv.slice(2)
@@ -22,7 +23,22 @@ function flagValue(name: string): string | undefined {
   return idx >= 0 ? args[idx + 1] : undefined
 }
 
-const deckPath = flagValue('--deck')
+const cliDeck = flagValue('--deck')
+// URL deck: fetch first at the CLI dispatch layer, then pass local path to commands.
+// Commands stay sync; URL I/O is handled once here.
+let deckPath: string | undefined
+if (cliDeck && isUrl(cliDeck)) {
+  try {
+    deckPath = await fetchDeckUrl(cliDeck)
+  } catch (e: any) {
+    console.error(`❌ ${e.message}`)
+    process.exit(1)
+  }
+} else if (cliDeck) {
+  deckPath = resolveDeckPathSync(cliDeck).path
+} else {
+  deckPath = undefined
+}
 const workdir = flagValue('--workdir')
 const alias = flagValue('--alias')
 const type = flagValue('--type')

package/src/link.ts

@@ -23,6 +23,7 @@ import {
   type SkillDeckLock, type LinkedSkill, type ConstraintReport,
 } from "./schema.js";
 import { parseDeck } from "./parse-deck.js";
+import { resolveDeckPathSync, fetchDeckUrl, isUrl } from "./resolve-deck.js";
 
 // ── 路径工具 ────────────────────────────────────────────────
 
@@ -129,33 +130,19 @@ export async function linkDeck(cliDeckPath?: string, cliWorkdir?: string, opts?:
 const MODE = opts?.mode ?? 'symlink'
 const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
 
-// If --deck is a URL, fetch it first (discovered via quick-agent.sh dogfooding)
-let DECK_PATH: string
-if (cliDeck && (cliDeck.startsWith('http://') || cliDeck.startsWith('https://'))) {
-  let url = cliDeck
-  if (url.includes('github.com/') && url.includes('/blob/')) {
-    url = url.replace('github.com/', 'raw.githubusercontent.com/').replace('/blob/', '/')
-  }
-  const dest = resolve(process.cwd(), 'skill-deck.toml')
-  console.log(`📥 Fetching deck: ${url}`)
-  try {
-    const res = await fetch(url, { signal: AbortSignal.timeout(30_000) })
-    if (!res.ok) {
-      console.error(`❌ Failed to fetch deck (HTTP ${res.status}): ${url}`)
+  // URL deck: fetch first, then proceed as local
+  let DECK_PATH: string
+  if (cliDeck && isUrl(cliDeck)) {
+    try {
+      DECK_PATH = await fetchDeckUrl(cliDeck)
+    } catch (e: any) {
+      console.error(`❌ ${e.message}`)
       process.exit(1)
     }
-    writeFileSync(dest, await res.text())
-    console.log(`   → saved to ${dest}`)
-    DECK_PATH = dest
-  } catch (e: any) {
-    console.error(`❌ Failed to fetch deck: ${e.message || e}`)
-    process.exit(1)
+  } else {
+    DECK_PATH = resolveDeckPathSync(cliDeck).path
   }
-} else {
-  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()}`);

package/src/resolve-deck.ts

@@ -0,0 +1,55 @@
+/**
+ * resolveDeckPath — shared deck URL/path resolution.
+ *
+ * Per ADR-20260508075301691: --deck accepts http/https URL.
+ * Extracted from link.ts so all commands (validate, add, refresh, etc.)
+ * inherit URL support without duplicating fetch logic.
+ *
+ * T1 of EPIC-20260508082810062 (Everything-from-URL).
+ */
+
+import { existsSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { findDeckToml } from './link.js'
+
+export interface ResolvedDeck {
+  path: string
+  source: 'url' | 'local' | 'default'
+}
+
+export function isUrl(s: string): boolean {
+  return s.startsWith('http://') || s.startsWith('https://')
+}
+
+function normalizeUrl(url: string): string {
+  try {
+    const u = new URL(url)
+    if (u.hostname === 'github.com' && u.pathname.includes('/blob/')) {
+      return `https://raw.githubusercontent.com${u.pathname.replace('/blob/', '/')}`
+    }
+  } catch {}
+  return url
+}
+
+/** Sync: resolve local path or default. URL case handled separately. */
+export function resolveDeckPathSync(cliArg?: string): ResolvedDeck {
+  if (cliArg) {
+    return { path: resolve(cliArg), source: 'local' }
+  }
+  const found = findDeckToml(process.cwd()) || resolve('skill-deck.toml')
+  return { path: found, source: 'default' }
+}
+
+/** Async: fetch URL deck, save to cwd, return local path. */
+export async function fetchDeckUrl(url: string): Promise<string> {
+  const normalized = normalizeUrl(url)
+  const dest = resolve(process.cwd(), 'skill-deck.toml')
+  console.log(`📥 Fetching deck: ${normalized}`)
+  const res = await fetch(normalized, { signal: AbortSignal.timeout(30_000) })
+  if (!res.ok) {
+    throw new Error(`Failed to fetch deck (HTTP ${res.status}): ${normalized}`)
+  }
+  writeFileSync(dest, await res.text())
+  console.log(`   → saved to ${dest}`)
+  return dest
+}

package/src/validate.ts

@@ -13,6 +13,7 @@
 import { parse as parseToml } from "@iarna/toml";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { resolveDeckPathSync, fetchDeckUrl, isUrl } from "./resolve-deck.js";
 import {
   buildValidationPlan,
   executeValidationPlan,
@@ -55,9 +56,17 @@ export async function buildDeckValidation(
   options: ValidateOptions = {},
 ): Promise<DeckValidationReport> {
   const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : process.cwd();
-  const DECK_PATH = cliDeckPath
-    ? resolve(cliDeckPath)
-    : findDeckToml(PROJECT_DIR) || resolve(PROJECT_DIR, "skill-deck.toml");
+  let DECK_PATH: string
+  if (cliDeckPath && isUrl(cliDeckPath)) {
+    try {
+      DECK_PATH = await fetchDeckUrl(cliDeckPath)
+    } catch (e: any) {
+      return { status: 'invalid', deckPath: cliDeckPath, errors: [`Failed to fetch deck: ${e.message}`], warnings: [], entries: [], skills: [], max_cards: 0, constraints: { total_cards: 0, within_budget: true, transient_warnings: [], dir_overlaps: [] } }
+    }
+  } else {
+    const resolved = resolveDeckPathSync(cliDeckPath)
+    DECK_PATH = resolved.path
+  }
 
   if (!existsSync(DECK_PATH)) {
     return {