lazybiz 1.0.0

package/README.md

@@ -0,0 +1,90 @@
+# lazybiz
+
+Install Lazy Biz vault skills into your own machine with one command.
+
+A skill is a folder your coding agent reads: instructions, reference notes and
+sometimes scripts. This CLI downloads the ones you have access to, puts them
+where your agent looks for them, and keeps them current.
+
+Requires **Node 18 or newer**. Nothing else — no install, no account, no
+dependencies.
+
+## Install a skill
+
+Open the skill in Whop and copy the command. It already carries your personal
+install key:
+
+```bash
+npx lazybiz add brand-kit --key YOUR_KEY
+```
+
+That puts the skill in `~/.agents/skills/brand-kit/` and, if you have a
+`~/.claude` directory, links it into `~/.claude/skills/` so Claude Code picks it
+up. Then tell your agent: *"use the brand-kit skill"*.
+
+`npx github:lazybizai/vault-cli add …` also works — it is the same code from
+the public mirror, and the older command in your notes keeps running.
+
+## Keep them current
+
+```bash
+npx lazybiz update --key YOUR_KEY
+```
+
+Compares every installed skill against the vault and reinstalls only the ones
+whose version moved. Add a skill id to update just that one.
+
+## See what is available
+
+```bash
+npx lazybiz list
+```
+
+Shows the whole catalog with each skill's state: installed, update available,
+or coming soon. The catalog needs no key.
+
+## Options
+
+| Option | What it does |
+|---|---|
+| `--key <KEY>` | Your install key. Also read from `$VAULT_KEY`. |
+| `--base-url <URL>` | Which vault to talk to. Default `https://lazybiz-skills.whop.site`, also read from `$VAULT_BASE_URL`. |
+| `--global` | Install into `~/.agents/skills`. This is the default. |
+| `--dir <PATH>` | Install somewhere else instead. Also read from `$VAULT_SKILLS_DIR`. |
+| `--force` | Overwrite a skill directory this CLI did not install. |
+
+## Where files land
+
+```
+~/.agents/skills/<skill-id>/            the skill, plus a .vault-version marker
+~/.claude/skills/<skill-id>             a symlink to it (when ~/.claude exists)
+```
+
+One copy on disk, read by every agent that looks for skills. The
+`.vault-version` marker is how `update` knows which version you have — deleting
+it does not break the skill, but `update` will stop tracking it.
+
+**A directory the CLI did not install is never overwritten.** If you already
+have a hand-written `~/.agents/skills/writing/`, `add writing` stops and says so
+rather than replacing it. `--force` overrides that, and deletes what was there.
+
+## Your install key is a secret
+
+Anyone holding the key can download the vault from any terminal. Treat it like a
+password: do not paste it into a shared channel or commit it. If it leaks, ask
+for a new one — the old one stops working.
+
+## Troubleshooting
+
+**"the vault rejected your install key"** — the key is wrong, or it was
+replaced. Open the skill in Whop and copy the command again.
+
+**"returned JSON instead of a zip"** — you are pointed at a host that redirects
+away from Whop's proxy. Use the `.whop.site` address, not `.whop.app`.
+
+**"already exists and was not installed by this CLI"** — you have your own
+folder by that name. Move it aside, or use `--force` if you want the vault's
+version to win.
+
+**An old version keeps running** — npx caches what it downloaded. Ask for the
+newest one with `npx lazybiz@latest add …`.

package/bin/vault.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * lazybiz — install and update Lazy Biz vault skills.
+ *
+ *   npx lazybiz add <skill-id> --key <KEY>
+ *   npx lazybiz update --key <KEY>
+ *   npx lazybiz list
+ *
+ * Published on npm as `lazybiz`; `npx github:lazybizai/vault-cli` still works
+ * for anyone who copied the old command.
+ *
+ * No dependencies on purpose: npx installs the package before our first line
+ * runs, so every dependency is time the member waits and code we did not
+ * write. Node 18 ships everything this needs.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  DEFAULT_BASE_URL,
+  VaultError,
+  downloadZip,
+  fetchCatalog,
+  resolveBaseUrl,
+  resolveKey,
+} from '../src/api.mjs'
+import { installSkill, InstallError } from '../src/install.mjs'
+import { MARKER, aliasRoot, linkAlias, listInstalled, readMarker, skillsRoot } from '../src/paths.mjs'
+
+const pkg = JSON.parse(
+  fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'),
+)
+
+const HELP = `lazybiz ${pkg.version} — install Lazy Biz vault skills
+
+Usage
+  npx lazybiz add <skill-id> --key <KEY>     install or reinstall one skill
+  npx lazybiz update [skill-id] --key <KEY>  reinstall every installed skill whose version changed
+  npx lazybiz list [--key <KEY>]             show what is installed and what is available
+  npx lazybiz --help                         this text
+  npx lazybiz --version                      print the CLI version
+
+Options
+  --key <KEY>        your personal install key. Copy the whole command from the
+                     skill's page in Whop and it is already filled in.
+                     Falls back to $VAULT_KEY.
+  --base-url <URL>   the vault to talk to. Default ${DEFAULT_BASE_URL}
+                     (or $VAULT_BASE_URL).
+  --global           install into ~/.agents/skills. This is the default.
+  --dir <PATH>       install into <PATH> instead of ~/.agents/skills.
+                     Falls back to $VAULT_SKILLS_DIR.
+  --force            overwrite a skill directory this CLI did not install.
+
+Where things land
+  ~/.agents/skills/<skill-id>/            the skill itself, plus a ${MARKER} marker
+  ~/.claude/skills/<skill-id>             a symlink to it, when ~/.claude exists
+
+Your key is a secret. Anyone holding it can download the vault.
+`
+
+/** Parse argv into {command, positionals, flags}. Unknown flags are an error. */
+function parseArgs(argv) {
+  const known = {
+    '--key': 'key',
+    '--base-url': 'baseUrl',
+    '--dir': 'dir',
+  }
+  const booleans = { '--global': 'global', '--force': 'force', '--help': 'help', '-h': 'help', '--version': 'version', '-v': 'version' }
+  const flags = {}
+  const positionals = []
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg in booleans) {
+      flags[booleans[arg]] = true
+      continue
+    }
+    const eq = arg.indexOf('=')
+    const name = eq > 0 ? arg.slice(0, eq) : arg
+    if (name in known) {
+      const value = eq > 0 ? arg.slice(eq + 1) : argv[++i]
+      if (value === undefined) throw new VaultError(`${name} needs a value`)
+      flags[known[name]] = value
+      continue
+    }
+    if (arg.startsWith('-')) throw new VaultError(`unknown option ${arg} (try --help)`)
+    positionals.push(arg)
+  }
+  return { command: positionals[0], positionals: positionals.slice(1), flags }
+}
+
+function requireKey(flags) {
+  const key = resolveKey(flags.key)
+  if (!key) {
+    throw new VaultError(
+      'no install key.\n' +
+        '  Open the skill in Whop and copy the command — it carries your key.\n' +
+        '  Or pass --key <KEY>, or set $VAULT_KEY.',
+    )
+  }
+  return key
+}
+
+function findInCatalog(catalog, id) {
+  const hit = catalog.find((s) => s.id === id)
+  if (!hit) {
+    const names = catalog.map((s) => s.id)
+    const near = names.filter((n) => n.includes(id) || id.includes(n)).slice(0, 3)
+    throw new VaultError(
+      `the vault has no skill called "${id}".` +
+        (near.length ? `\n  Did you mean: ${near.join(', ')}?` : '') +
+        `\n  Run "vault list" to see all ${names.length}.`,
+    )
+  }
+  return hit
+}
+
+/** Download, unpack and alias one skill. Returns a printable summary. */
+async function installOne({ entry, key, baseUrl, root, alias, force }) {
+  const zip = await downloadZip(baseUrl, entry.id, key)
+  const { files, replaced } = installSkill({
+    root,
+    id: entry.id,
+    zip,
+    version: entry.version,
+    baseUrl,
+    force,
+  })
+  const linked = linkAlias(alias, root, entry.id)
+  return { files, replaced, linked }
+}
+
+async function cmdAdd(positionals, flags) {
+  const id = positionals[0]
+  if (!id) throw new VaultError('which skill? Usage: npx lazybiz add <skill-id> --key <KEY>')
+
+  const baseUrl = resolveBaseUrl(flags.baseUrl)
+  const key = requireKey(flags)
+  const root = skillsRoot(flags)
+  const alias = aliasRoot(flags)
+
+  const entry = findInCatalog(await fetchCatalog(baseUrl), id)
+  if (!entry.available) {
+    throw new VaultError(`"${id}" is announced but has no file yet. Nothing to install.`)
+  }
+
+  const summary = await installOne({ entry, key, baseUrl, root, alias, force: flags.force })
+  console.log(
+    `${summary.replaced ? 'Reinstalled' : 'Installed'} ${entry.id} v${entry.version} ` +
+      `(${summary.files} files) in ${path.join(root, entry.id)}`,
+  )
+  if (summary.linked === 'linked') {
+    console.log(`Linked ${path.join(alias, entry.id)} -> the install above`)
+  } else if (summary.linked === 'skipped' && alias) {
+    console.log(`Left ${path.join(alias, entry.id)} alone (something real is already there)`)
+  }
+  console.log(`\nTell your agent to use it: "use the ${entry.id} skill".`)
+}
+
+async function cmdUpdate(positionals, flags) {
+  const baseUrl = resolveBaseUrl(flags.baseUrl)
+  const key = requireKey(flags)
+  const root = skillsRoot(flags)
+  const alias = aliasRoot(flags)
+
+  const only = positionals[0]
+  const installed = listInstalled(root).filter((s) => !only || s.id === only)
+
+  if (installed.length === 0) {
+    if (only) {
+      throw new VaultError(
+        `"${only}" is not installed in ${root} (no ${MARKER}).\n` +
+          `  Install it first: vault add ${only} --key <KEY>`,
+      )
+    }
+    console.log(`Nothing installed in ${root} yet. Start with: vault add <skill-id> --key <KEY>`)
+    return
+  }
+
+  const catalog = await fetchCatalog(baseUrl)
+  const stale = []
+  const gone = []
+  for (const local of installed) {
+    const remote = catalog.find((s) => s.id === local.id)
+    if (!remote) {
+      gone.push(local)
+    } else if (remote.available && remote.version !== local.version) {
+      stale.push({ local, remote })
+    }
+  }
+
+  if (stale.length === 0) {
+    console.log(`Up to date — ${installed.length} skill(s) match the vault.`)
+  }
+  for (const { local, remote } of stale) {
+    const summary = await installOne({ entry: remote, key, baseUrl, root, alias, force: true })
+    console.log(`Updated ${remote.id} ${local.version} -> ${remote.version} (${summary.files} files)`)
+  }
+  for (const local of gone) {
+    console.log(`Note: ${local.id} is installed but no longer in the vault. Left untouched.`)
+  }
+}
+
+async function cmdList(_positionals, flags) {
+  const baseUrl = resolveBaseUrl(flags.baseUrl)
+  const root = skillsRoot(flags)
+  const installed = new Map(listInstalled(root).map((s) => [s.id, s]))
+
+  // The catalog route needs no key — a version comparison should not have to
+  // pass the download gate. --key is accepted so one habit fits every command.
+  const catalog = await fetchCatalog(baseUrl)
+
+  console.log(`${baseUrl}  ->  ${root}\n`)
+  const ids = [...catalog.map((s) => s.id), ...installed.keys()]
+  const width = Math.max(4, ...ids.map((id) => id.length))
+  for (const s of catalog) {
+    const local = installed.get(s.id)
+    let state
+    if (!s.available) state = 'coming soon'
+    else if (!local) state = 'available'
+    else if (local.version === s.version) state = `installed v${local.version}`
+    else state = `update: v${local.version} -> v${s.version}`
+    console.log(`  ${s.id.padEnd(width)}  ${state.padEnd(24)} ${s.oneLiner ?? ''}`)
+    installed.delete(s.id)
+  }
+  for (const [id, local] of installed) {
+    console.log(`  ${id.padEnd(width)}  ${`v${local.version}, not in vault`.padEnd(24)}`)
+  }
+  console.log(`\n${catalog.length} skill(s) in the vault.`)
+}
+
+async function main() {
+  let parsed
+  try {
+    parsed = parseArgs(process.argv.slice(2))
+  } catch (e) {
+    console.error(`lazybiz: ${e.message}`)
+    process.exit(2)
+  }
+  const { command, positionals, flags } = parsed
+
+  if (flags.version) {
+    console.log(pkg.version)
+    return
+  }
+  if (flags.help || !command || command === 'help') {
+    console.log(HELP)
+    return
+  }
+
+  const commands = { add: cmdAdd, update: cmdUpdate, list: cmdList }
+  const run = commands[command]
+  if (!run) {
+    console.error(`lazybiz: unknown command "${command}". Try: add, update, list, --help`)
+    process.exit(2)
+  }
+
+  try {
+    await run(positionals, flags)
+  } catch (e) {
+    if (e instanceof VaultError || e instanceof InstallError) {
+      console.error(`lazybiz: ${e.message}`)
+      process.exit(1)
+    }
+    throw e
+  }
+}
+
+main().catch((e) => {
+  console.error(`lazybiz: unexpected failure — ${e?.stack ?? e}`)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "lazybiz",
+  "version": "1.0.0",
+  "description": "Install and update Lazy Biz vault skills into your agent's skills folder.",
+  "type": "module",
+  "bin": {
+    "lazybiz": "bin/vault.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "UNLICENSED",
+  "private": false
+}

package/src/api.mjs

@@ -0,0 +1,106 @@
+/**
+ * The vault's HTTP surface. Two routes, and the base URL is a parameter so the
+ * same CLI serves a future vault without a code change.
+ *
+ * DEFAULT HOST IS `.whop.site`, NEVER `.whop.app`. whop.app answers 307 and the
+ * client follows that redirect OUTSIDE Whop's proxy, which drops the auth header
+ * — a download then returns a 401 JSON body that looks exactly like a zip until
+ * you open it. Every request this CLI makes rides on this one value.
+ */
+export const DEFAULT_BASE_URL = 'https://lazybiz-skills.whop.site'
+
+export class VaultError extends Error {}
+
+export function resolveBaseUrl(flag) {
+  const raw = flag || process.env.VAULT_BASE_URL || DEFAULT_BASE_URL
+  const url = raw.replace(/\/+$/, '')
+  if (!/^https?:\/\//.test(url)) {
+    throw new VaultError(`base URL must start with http:// or https:// — got "${raw}"`)
+  }
+  return url
+}
+
+export function resolveKey(flag) {
+  const key = (flag || process.env.VAULT_KEY || '').trim()
+  return key || null
+}
+
+async function getJson(url, what) {
+  let res
+  try {
+    res = await fetch(url, { headers: { accept: 'application/json' } })
+  } catch (e) {
+    throw new VaultError(`could not reach ${new URL(url).origin} — ${e.message}`)
+  }
+  if (!res.ok) {
+    throw new VaultError(`${what} failed: HTTP ${res.status} from ${url}`)
+  }
+  let body
+  try {
+    body = await res.json()
+  } catch {
+    throw new VaultError(`${what} returned something that is not JSON — is the base URL right?`)
+  }
+  if (body?.ok === false) {
+    throw new VaultError(`${what} failed: ${body.error ?? 'unknown error'}`)
+  }
+  return body
+}
+
+/**
+ * The catalog. Ungated on purpose — it carries ids, names and versions only, so
+ * a version comparison never needs the key. The bytes still do.
+ */
+export async function fetchCatalog(baseUrl) {
+  const body = await getJson(`${baseUrl}/api/skills`, 'catalog lookup')
+  if (!Array.isArray(body?.skills)) {
+    throw new VaultError(`catalog lookup returned no skills list — is ${baseUrl} the vault?`)
+  }
+  return body.skills
+}
+
+/**
+ * Download one skill's zip. The key is a bearer secret and goes in the query
+ * string because that is what the route accepts; it is never logged.
+ */
+export async function downloadZip(baseUrl, id, key) {
+  const url = `${baseUrl}/api/install/${encodeURIComponent(id)}?key=${encodeURIComponent(key)}`
+  let res
+  try {
+    res = await fetch(url)
+  } catch (e) {
+    throw new VaultError(`could not reach ${baseUrl} — ${e.message}`)
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    throw new VaultError(
+      'the vault rejected your install key.\n' +
+        '  Open the skill in Whop and copy the command again — it carries a fresh key.\n' +
+        '  Nothing was installed.',
+    )
+  }
+  if (res.status === 404) {
+    throw new VaultError(
+      `the vault has no downloadable file for "${id}" yet (it may be marked as coming soon).`,
+    )
+  }
+  if (!res.ok) {
+    throw new VaultError(`download failed: HTTP ${res.status} for ${id}`)
+  }
+
+  // A JSON body here means an error page slipped through with a 200, which is
+  // what a redirect off the proxy looks like. Treat it as a failure, not a zip.
+  const type = res.headers.get('content-type') ?? ''
+  if (type.includes('application/json')) {
+    throw new VaultError(
+      `the vault returned JSON instead of a zip for "${id}".\n` +
+        `  Check that the base URL is the .whop.site host, not .whop.app.`,
+    )
+  }
+
+  const buf = Buffer.from(await res.arrayBuffer())
+  if (buf.length < 22 || buf.readUInt16LE(0) !== 0x4b50) {
+    throw new VaultError(`the download for "${id}" is not a zip file (${buf.length} bytes).`)
+  }
+  return buf
+}

package/src/install.mjs

@@ -0,0 +1,101 @@
+/**
+ * Unpack one skill zip into the skills root.
+ *
+ * Two rules do the real work here:
+ *
+ * 1. **A directory without our marker is never overwritten.** The skills root
+ *    is where hand-written skills live too, and on a maintainer's machine it is
+ *    a symlink into the repository those skills come FROM. An `add` that
+ *    silently replaced `writing/` there would delete the source, not a copy.
+ *    Refuse, name the file, and let --force be a decision the member makes.
+ * 2. **Extract to a temporary directory first, then swap.** A download that
+ *    fails halfway must leave the previous install intact.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { listEntries, readEntry } from './unzip.mjs'
+import { MARKER, readMarker } from './paths.mjs'
+
+export class InstallError extends Error {}
+
+/** Reject anything that would write outside the target directory. */
+function safeName(name) {
+  if (name.startsWith('/') || /^[a-zA-Z]:/.test(name) || name.includes('\\')) return null
+  const parts = name.split('/').filter((p) => p !== '' && p !== '.')
+  if (parts.some((p) => p === '..')) return null
+  return parts.join('/')
+}
+
+/**
+ * Extract the zip into `dest`.
+ *
+ * The pipeline's packages are `<id>/…` PLUS a loose `VAULT-INFO.md` at the zip
+ * root — the wrapper is not the only thing up there. So the rule is per entry,
+ * not per archive: strip the `<id>/` prefix where it appears, keep root-level
+ * files as they are. The member ends up with the skill's own files at the top of
+ * `<id>/` and the provenance note beside them, which is the layout the skill
+ * pages describe. A flat zip with no wrapper lands as-is under the same rule.
+ *
+ * (Found the hard way: assuming every entry carried the prefix produced
+ * `<id>/<id>/SKILL.md`, and an agent looking for `<id>/SKILL.md` found nothing.)
+ */
+function extractInto(zip, dest, id) {
+  const entries = listEntries(zip)
+  const files = entries.filter((e) => !e.isDir)
+  if (files.length === 0) throw new InstallError('the package is empty')
+
+  const prefix = `${id}/`
+
+  let written = 0
+  for (const entry of files) {
+    const stripped = entry.name.startsWith(prefix) ? entry.name.slice(prefix.length) : entry.name
+    const rel = safeName(stripped)
+    if (!rel) throw new InstallError(`the package contains an unsafe path: ${entry.name}`)
+
+    const target = path.join(dest, rel)
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    fs.writeFileSync(target, readEntry(zip, entry))
+    // Keep the executable bit; skills ship scripts that are meant to run.
+    if (entry.mode & 0o111) fs.chmodSync(target, 0o755)
+    written++
+  }
+  return written
+}
+
+/**
+ * Install `id` from `zip` under `root`.
+ * @returns {{files: number, replaced: boolean}}
+ */
+export function installSkill({ root, id, zip, version, baseUrl, force = false }) {
+  const finalDir = path.join(root, id)
+  // lstat, not existsSync: a dangling symlink is in the way too.
+  const existing = fs.lstatSync(finalDir, { throwIfNoEntry: false }) != null
+
+  if (existing && !readMarker(root, id) && !force) {
+    throw new InstallError(
+      `${finalDir} already exists and was not installed by this CLI (no ${MARKER}).\n` +
+        `  Refusing to overwrite it. Move it aside, or rerun with --force.`,
+    )
+  }
+
+  fs.mkdirSync(root, { recursive: true })
+  const staging = path.join(root, `.${id}.vault-tmp`)
+  fs.rmSync(staging, { recursive: true, force: true })
+  fs.mkdirSync(staging, { recursive: true })
+
+  let files
+  try {
+    files = extractInto(zip, staging, id)
+    fs.writeFileSync(
+      path.join(staging, MARKER),
+      `${JSON.stringify({ id, version, source: baseUrl, installedAt: new Date().toISOString() }, null, 2)}\n`,
+    )
+    // Swap last: until this point the previous install is still the live one.
+    fs.rmSync(finalDir, { recursive: true, force: true })
+    fs.renameSync(staging, finalDir)
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true })
+  }
+
+  return { files, replaced: existing }
+}

package/src/paths.mjs

@@ -0,0 +1,87 @@
+/**
+ * Where a skill lands, and how it becomes visible to the agents.
+ *
+ * `<root>/.agents/skills/<id>/` is the real directory; `~/.claude/skills/<id>`
+ * is a symlink pointing at it. That split is the workspace's own layout, not an
+ * invention here: one copy on disk, read by every agent that looks for skills.
+ *
+ * The symlink target is RELATIVE. An absolute $HOME path written on one machine
+ * is a dead link on another, and these directories get synced between machines.
+ */
+import { homedir } from 'node:os'
+import path from 'node:path'
+import fs from 'node:fs'
+
+export const MARKER = '.vault-version'
+
+/** The directory skills are installed into. */
+export function skillsRoot({ dir } = {}) {
+  if (dir) return path.resolve(dir)
+  if (process.env.VAULT_SKILLS_DIR) return path.resolve(process.env.VAULT_SKILLS_DIR)
+  return path.join(homedir(), '.agents', 'skills')
+}
+
+/**
+ * The Claude-side alias directory, or null when this machine has no ~/.claude.
+ * Only the default (global) root is aliased: a skill installed into an explicit
+ * --dir belongs to that tree and linking it into the home directory would make
+ * a throwaway install look permanent.
+ */
+export function aliasRoot({ dir } = {}) {
+  if (dir || process.env.VAULT_SKILLS_DIR) return null
+  const claude = path.join(homedir(), '.claude')
+  if (!fs.existsSync(claude)) return null
+  return path.join(claude, 'skills')
+}
+
+/** Read the install marker, or null when the skill is not a vault install. */
+export function readMarker(root, id) {
+  try {
+    const raw = fs.readFileSync(path.join(root, id, MARKER), 'utf8')
+    const parsed = JSON.parse(raw)
+    return typeof parsed?.version === 'string' ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** Every vault-installed skill under `root`, as {id, version, …}. */
+export function listInstalled(root) {
+  let names = []
+  try {
+    names = fs.readdirSync(root, { withFileTypes: true })
+      .filter((e) => e.isDirectory() || e.isSymbolicLink())
+      .map((e) => e.name)
+  } catch {
+    return []
+  }
+  const out = []
+  for (const id of names.sort()) {
+    const marker = readMarker(root, id)
+    if (marker) out.push({ id, ...marker })
+  }
+  return out
+}
+
+/**
+ * Point `<aliasRoot>/<id>` at the installed skill.
+ * Returns 'linked' | 'kept' | 'skipped'. An existing real directory is never
+ * touched: it holds content this CLI did not write.
+ */
+export function linkAlias(alias, root, id) {
+  if (!alias) return 'skipped'
+  fs.mkdirSync(alias, { recursive: true })
+  const link = path.join(alias, id)
+  const target = path.relative(alias, path.join(root, id))
+
+  let current = null
+  try {
+    current = fs.readlinkSync(link)
+  } catch {
+    if (fs.existsSync(link)) return 'skipped'
+  }
+  if (current === target) return 'kept'
+  if (current !== null) fs.rmSync(link)
+  fs.symlinkSync(target, link)
+  return 'linked'
+}

package/src/unzip.mjs

@@ -0,0 +1,95 @@
+/**
+ * Minimal ZIP reader — stored + deflate, nothing else.
+ *
+ * The CLI runs through `npx github:…`, which installs whatever `dependencies`
+ * says before the first line of our code runs. Every dependency is therefore a
+ * download the member waits through and a supply chain we do not control, for a
+ * job Node's own `zlib` already does. Shelling out to `unzip` was the other
+ * candidate and was dropped: it is absent on a plain Windows box, and the point
+ * of the npx route is that it works on the machine the member already has.
+ *
+ * The vault's zips come from Python's `zipfile` with ZIP_DEFLATED, so store and
+ * deflate cover them. Zip64 is detected and refused rather than mis-parsed; a
+ * skill package that large is a pipeline bug, not something to guess around.
+ */
+import { inflateRawSync } from 'node:zlib'
+
+const EOCD_SIG = 0x06054b50
+const CD_SIG = 0x02014b50
+const LFH_SIG = 0x04034b50
+const ZIP64_LOCATOR_SIG = 0x07064b50
+
+export class ZipError extends Error {}
+
+/** Scan backwards for the end-of-central-directory record. */
+function findEocd(buf) {
+  const min = Math.max(0, buf.length - 66_000)
+  for (let i = buf.length - 22; i >= min; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) return i
+  }
+  throw new ZipError('not a zip file (no end-of-central-directory record)')
+}
+
+/**
+ * List the entries in a zip.
+ * @returns {{name: string, isDir: boolean, mode: number, method: number,
+ *            compressedSize: number, size: number, offset: number}[]}
+ */
+export function listEntries(buf) {
+  const eocd = findEocd(buf)
+
+  if (eocd >= 20 && buf.readUInt32LE(eocd - 20) === ZIP64_LOCATOR_SIG) {
+    throw new ZipError('zip64 archives are not supported')
+  }
+
+  const count = buf.readUInt16LE(eocd + 10)
+  let p = buf.readUInt32LE(eocd + 16)
+  if (count === 0xffff || p === 0xffffffff) {
+    throw new ZipError('zip64 archives are not supported')
+  }
+
+  const entries = []
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(p) !== CD_SIG) {
+      throw new ZipError(`corrupt central directory at entry ${i + 1}`)
+    }
+    const method = buf.readUInt16LE(p + 10)
+    const compressedSize = buf.readUInt32LE(p + 20)
+    const size = buf.readUInt32LE(p + 24)
+    const nameLen = buf.readUInt16LE(p + 28)
+    const extraLen = buf.readUInt16LE(p + 30)
+    const commentLen = buf.readUInt16LE(p + 32)
+    const externalAttrs = buf.readUInt32LE(p + 38)
+    const offset = buf.readUInt32LE(p + 42)
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen)
+
+    entries.push({
+      name,
+      isDir: name.endsWith('/'),
+      // Unix permissions live in the high 16 bits. 0 means the zip was written
+      // by a tool that did not record them; the caller falls back to a default.
+      mode: (externalAttrs >>> 16) & 0o7777,
+      method,
+      compressedSize,
+      size,
+      offset,
+    })
+    p += 46 + nameLen + extraLen + commentLen
+  }
+  return entries
+}
+
+/** Inflate one entry's bytes. */
+export function readEntry(buf, entry) {
+  if (buf.readUInt32LE(entry.offset) !== LFH_SIG) {
+    throw new ZipError(`corrupt local header for ${entry.name}`)
+  }
+  const nameLen = buf.readUInt16LE(entry.offset + 26)
+  const extraLen = buf.readUInt16LE(entry.offset + 28)
+  const start = entry.offset + 30 + nameLen + extraLen
+  const raw = buf.subarray(start, start + entry.compressedSize)
+
+  if (entry.method === 0) return Buffer.from(raw)
+  if (entry.method === 8) return inflateRawSync(raw)
+  throw new ZipError(`unsupported compression method ${entry.method} for ${entry.name}`)
+}