@lythos/skill-deck 0.11.2 → 0.13.0

package/README.md

@@ -8,16 +8,16 @@
 
 ```bash
 # Add a skill from skills.sh (owner/repo syntax — no conversion needed)
-bunx @lythos/skill-deck@0.11.2 add vercel-labs/agent-skills
+bunx @lythos/skill-deck@0.13.0 add vercel-labs/agent-skills
 
 # Or with @skill filter (same as npx skills add):
-bunx @lythos/skill-deck@0.11.2 add mattpocock/skills@tdd
+bunx @lythos/skill-deck@0.13.0 add mattpocock/skills@tdd
 
 # Or FQ locator:
-bunx @lythos/skill-deck@0.11.2 add github.com/anthropics/skills/skills/frontend-design
+bunx @lythos/skill-deck@0.13.0 add github.com/anthropics/skills/skills/frontend-design
 
 # Sync working set (deny-by-default):
-bunx @lythos/skill-deck@0.11.2 link
+bunx @lythos/skill-deck@0.13.0 link
 ```
 
 ## For AI Agents
@@ -25,7 +25,7 @@ bunx @lythos/skill-deck@0.11.2 link
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.11.2 <command> [options]
+bunx @lythos/skill-deck@0.13.0 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -73,15 +73,15 @@ 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.11.2 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.11.2 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.11.2 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.11.2 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.11.2 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.11.2 remove tdd` |
-| Switch skill to symlink mode (live) | `bunx @lythos/skill-deck@0.11.2 to-symlink tdd` |
-| Switch skill to snapshot mode (pinned) | `bunx @lythos/skill-deck@0.11.2 to-snapshot tdd` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.11.2 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.13.0 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.13.0 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.13.0 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.13.0 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.13.0 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.13.0 remove tdd` |
+| Switch skill to symlink mode (live) | `bunx @lythos/skill-deck@0.13.0 to-symlink tdd` |
+| Switch skill to snapshot mode (pinned) | `bunx @lythos/skill-deck@0.13.0 to-snapshot tdd` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.13.0 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -90,7 +90,7 @@ prompt = "Search for latest info, then generate professional document with diagr
 | `link` | `[--deck <path>] [--workdir <dir>]` | Sync working set. Removes undeclared skills (deny-by-default). |
 | `validate` | `[deck.toml] [--workdir <dir>]` | Validate deck config without modifying files. |
 | `add` | `<locator> [--alias <alias>] [--type <type>] [--deck <path>]` | Add skill to cold pool + deck.toml. Accepts skills.sh syntax (owner/repo, owner/repo@skill, github:owner/repo) and FQ locators. |
-| `refresh` | `[<fq\|alias>] [--deck <path>]` | Pull latest versions of declared skills from upstream git repos. Pass a name to refresh one skill. |
+| `refresh` | `[<fq\|alias>] [--deck <path>] [--exec]` | Scan declared skills for upstream updates (plan-only by default). Add `--exec` to actually pull. Agent-driven apply preferred. |
 | `remove` | `<fq\|alias> [--deck <path>]` | Remove skill from deck.toml and working set. Cold pool untouched. |
 | `to-symlink` | `<alias> [--deck <path>] [--workdir <dir>]` | Switch a skill to symlink mode (live link, follows cold pool) |
 | `to-snapshot` | `<alias> [--deck <path>] [--workdir <dir>]` | Switch a skill to snapshot mode (pinned cp of current HEAD) |
@@ -143,7 +143,7 @@ source = "https://github.com/lythos-labs/lythoskill/blob/HEAD/skills/lythoskill-
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.11.2 link
+bunx @lythos/skill-deck@0.13.0 link
 ```
 
 ### Key Concepts
@@ -229,7 +229,7 @@ Caution: deck's deny-by-default will remove any skills not declared in your deck
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.11.2 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.13.0 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.11.2",
+  "version": "0.13.0",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",
@@ -31,8 +31,8 @@
   ],
   "dependencies": {
     "@iarna/toml": "^2.2.5",
-    "@lythos/cold-pool": "^0.11.2",
-    "@lythos/infra": "^0.11.2",
+    "@lythos/cold-pool": "^0.13.0",
+    "@lythos/infra": "^0.13.0",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },

package/src/add.ts

@@ -28,6 +28,7 @@ import {
   hashSkillMd,
   type Locator,
 } from '@lythos/cold-pool'
+import { probeConnectivity } from '@lythos/cold-pool/src/mirror.js'
 import { findDeckToml, expandHome } from './link.js'
 import { validateAlias } from './path-guard.js'
 
@@ -263,6 +264,24 @@ export async function addSkill(
   // git clone needs the parent of the target dir (e.g. host/owner/) to exist
   mkdirSync(dirname(fetchPlan.targetDir), { recursive: true })
 
+  // ── Plan→Apply boundary: probe network before any git operation ────────
+  if (fetchPlan.cloneUrl) {
+    const probe = await probeConnectivity(fetchPlan.cloneUrl, 5000)
+    if (!probe) {
+      console.error(`❌ Cannot reach ${fetchPlan.cloneUrl}`)
+      console.error(`   Network probe failed — the host may be unreachable or blocked.`)
+      console.error(``)
+      console.error(`   To fix:`)
+      console.error(`     export LYTHOSKILL_GH_MIRROR="https://your-mirror.com"`)
+      console.error(`     # Or set LYTHOS_SOCKS_PROXY for SOCKS5 routing`)
+      console.error(`     # See: AGENTS.md → Network Restrictions`)
+      process.exit(1)
+    }
+    if (probe.path === 'mirror') {
+      console.log(`🪞 Using mirror: ${probe.url} (${probe.latencyMs}ms)`)
+    }
+  }
+
   // Note: if cold pool already has the repo (fetchPlan.alreadyExists),
   // executeFetchPlan returns status: 'already-present' and skips clone.
   // We still want to write deck.toml + link this skill — critical for

package/src/cli.ts

@@ -49,6 +49,7 @@ const format = flagValue('--format')
 const noBackup = args.includes('--no-backup')
 const dryRun = args.includes('--dry-run')
 const remote = args.includes('--remote')
+const execFlag = args.includes('--exec')
 const mode = flagValue('--mode') as 'symlink' | 'snapshot' | undefined
 
 const HELP_CONFIG = {
@@ -76,9 +77,16 @@ const HELP_CONFIG = {
     { flag: '--yes', description: 'Skip interactive confirmation' },
     { flag: '--remote', description: 'For validate: probe each FQ locator against api.github.com' },
     { flag: '--format <text|json>', description: 'For validate: output format (default: text)' },
+    { flag: '--exec', description: 'For refresh: execute git pull instead of printing plan-only' },
   ],
 }
 
+// --help / -h anywhere in the arg list triggers help (not treated as a positional arg or ignored)
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(formatHelp(HELP_CONFIG))
+  process.exit(0)
+}
+
 switch (command) {
   case '--help':
   case '-h':
@@ -98,7 +106,7 @@ switch (command) {
   }
   case 'refresh': {
     const refreshTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
-    refreshDeck(deckPath, workdir, refreshTarget)
+    await refreshDeck(deckPath, workdir, refreshTarget, execFlag)
     break
   }
   case 'update': {

package/src/refresh.ts

@@ -2,14 +2,17 @@
 /**
  * deck-refresh.ts — Refresh declared skills from their upstream sources
  *
- * Reads skill-deck.toml → traverses declared skills → git pull.
- * Supports single-skill (by FQ path or alias) or all skills.
- * Never modifies deck.toml.
+ * Default: discover-only — outputs a structured plan, never executes git pull.
+ * With `exec: true` — executes the plan (git pull + linkDeck).
+ *
+ * Agent-driven apply: the agent reads the plan, decides what to pull,
+ * and can probe / retry / fix per target. Not a dead heredoc script.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { gitPull } from "@lythos/cold-pool";
+import { probeConnectivity } from "@lythos/cold-pool/src/mirror.js";
 import { findDeckToml, linkDeck } from "./link.js";
 import { parseDeck } from "./parse-deck.js";
 import { buildRefreshPlan, detectGitRoot, executeRefreshPlan } from "./refresh-plan.js";
@@ -20,7 +23,26 @@ export function findGitRoot(dir: string, coldPool: string): string | null {
   return result.gitRoot ?? null
 }
 
-export function refreshDeck(cliDeckPath?: string, cliWorkdir?: string, target?: string): void {
+/** Quick behind-count probe for a single git root. Pure, no mutation. */
+async function probeBehindCount(gitRoot: string): Promise<number | undefined> {
+  try {
+    const { execSync } = await import("node:child_process");
+    execSync("git fetch --depth=1 origin", { cwd: gitRoot, timeout: 5000, stdio: "pipe" });
+    const count = execSync("git rev-list HEAD...@{upstream} --count", {
+      cwd: gitRoot, timeout: 3000, encoding: "utf-8", stdio: "pipe",
+    }).trim();
+    return parseInt(count, 10);
+  } catch {
+    return undefined;
+  }
+}
+
+export async function refreshDeck(
+  cliDeckPath?: string,
+  cliWorkdir?: string,
+  target?: string,
+  exec = false,
+): Promise<void> {
   const deckPath = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
   const workdir = cliWorkdir
 
@@ -59,7 +81,59 @@ export function refreshDeck(cliDeckPath?: string, cliWorkdir?: string, target?:
     process.exit(1)
   }
 
-  // ── Execute with real IO ────────────────────────────────────
+  // ── Discover: enrich plan with behind counts ─────────────────────
+  const enriched = await Promise.all(
+    plan.targets.map(async (t) => {
+      if (t.type !== 'git' || !t.gitRoot) return { ...t, behind: undefined };
+      const behind = await probeBehindCount(t.gitRoot);
+      return { ...t, behind };
+    })
+  );
+
+  // ── Default path: print plan, do NOT pull ──────────────────────
+  if (!exec) {
+    console.log(`📋 Refresh Plan — ${enriched.length} skill(s)`)
+    console.log(``)
+    for (const t of enriched) {
+      const behindStr = t.behind === undefined ? '?' : t.behind > 0 ? `${t.behind} behind` : 'up to date';
+      switch (t.type) {
+        case 'git':
+          console.log(`🔄 ${t.alias}  ${t.path}  (${behindStr})`)
+          break
+        case 'localhost':
+          console.log(`📁 ${t.alias}  ${t.path}  (localhost — user-managed)`)
+          break
+        case 'missing':
+          console.log(`❌ ${t.alias}  ${t.path}  (missing from cold pool)`)
+          break
+        case 'not-git':
+          console.log(`📁 ${t.alias}  ${t.path}  (not a git repo)`)
+          break
+      }
+    }
+    console.log(``)
+    console.log(`💡 To apply this plan: deck refresh --exec`)
+    console.log(`   Or let an agent read this plan and execute per target with probe + retry.`)
+    return
+  }
+
+  // ── Exec path: agent/human has explicitly opted in ─────────────
+  // ── Plan→Apply boundary: probe network before any git pull ─────
+  const gitTargets = plan.targets.filter(t => t.type === 'git')
+  if (gitTargets.length > 0) {
+    const firstTarget = gitTargets[0]!
+    const probeUrl = `https://${firstTarget.path}`
+    const probe = await probeConnectivity(probeUrl, 5000)
+    if (!probe) {
+      console.error(`⚠️  Network probe failed for ${probeUrl}`)
+      console.error(`   Refresh may fail for git targets. To fix:`)
+      console.error(`     export LYTHOSKILL_GH_MIRROR="https://your-mirror.com"`)
+      console.error(`     # Or set LYTHOS_SOCKS_PROXY for SOCKS5 routing`)
+      console.error(`   Continuing anyway — per-target errors will be reported below.`)
+      console.error()
+    }
+  }
+
   const results = executeRefreshPlan(plan, {
     gitPull,
     log: console.log,

package/src/resolve-deck.ts

@@ -82,7 +82,7 @@ export async function fetchDeckUrl(url: string, io?: FetchDeckIO): Promise<strin
   }
 
   if (!res?.ok) {
-    throw new Error(`Failed to fetch deck: ${normalized}\n   All mirrors exhausted. Set LYTHOSKILL_GH_MIRROR to use a custom mirror, or LYTHOS_SOCKS_PROXY for SOCKS5.`)
+    throw new Error(`Failed to fetch deck: ${normalized}\n   Set LYTHOSKILL_GH_MIRROR to use a custom mirror, or LYTHOS_SOCKS_PROXY for SOCKS5.`)
   }
 
   writeFn(dest, await res.text())