shelfware 0.1.0 → 0.1.1

package/.output/nitro.json

@@ -1,5 +1,5 @@
 {
-  "date": "2026-09-06T10:58:50.215Z",
+  "date": "2026-09-06T14:46:30.939Z",
   "preset": "node-server",
   "framework": {
     "name": "nuxt",

package/.output/public/_nuxt/builds/latest.json

@@ -1 +1 @@
-{"id":"4c307968-4837-497b-a570-d6ee336accc4","timestamp":1788692326920}
+{"id":"e0d2b6a3-3a30-44b7-8c79-a56f66400005","timestamp":1788705987913}

package/.output/public/_nuxt/builds/meta/e0d2b6a3-3a30-44b7-8c79-a56f66400005.json

@@ -0,0 +1 @@
+{"id":"e0d2b6a3-3a30-44b7-8c79-a56f66400005","timestamp":1788705987913,"prerendered":[]}

package/.output/server/chunks/nitro/nitro.mjs

@@ -4056,7 +4056,7 @@ function _expandFromEnv(value) {
 const _inlineRuntimeConfig = {
   "app": {
     "baseURL": "/",
-    "buildId": "4c307968-4837-497b-a570-d6ee336accc4",
+    "buildId": "e0d2b6a3-3a30-44b7-8c79-a56f66400005",
     "buildAssetsDir": "/_nuxt/",
     "cdnURL": ""
   },
@@ -4574,107 +4574,107 @@ const assets = {
   "/_nuxt/6IstVYrV.js": {
     "type": "text/javascript; charset=utf-8",
     "etag": "\"e90-QSo0QKAvkvHEus5Dhcj+CyKCqD4\"",
-    "mtime": "2026-09-06T10:58:49.045Z",
+    "mtime": "2026-09-06T14:46:29.734Z",
     "size": 3728,
     "path": "../public/_nuxt/6IstVYrV.js"
   },
   "/_nuxt/BDNMzG2s.js": {
     "type": "text/javascript; charset=utf-8",
     "etag": "\"54-MasMfSk/A98C3Gn9uIOxtFxkWNw\"",
-    "mtime": "2026-09-06T10:58:49.045Z",
+    "mtime": "2026-09-06T14:46:29.734Z",
     "size": 84,
     "path": "../public/_nuxt/BDNMzG2s.js"
   },
-  "/_nuxt/BXXtFil5.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": "\"1bd2-NDdun38lYj0OD2wayMdetDX3ehc\"",
-    "mtime": "2026-09-06T10:58:49.045Z",
-    "size": 7122,
-    "path": "../public/_nuxt/BXXtFil5.js"
-  },
-  "/_nuxt/BZuUK3cr.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": "\"d4e-rtWL1k144ZrYuBUrIE7FN7q4gDI\"",
-    "mtime": "2026-09-06T10:58:49.045Z",
-    "size": 3406,
-    "path": "../public/_nuxt/BZuUK3cr.js"
-  },
   "/_nuxt/BW3xJdEx.js": {
     "type": "text/javascript; charset=utf-8",
     "etag": "\"2da-zDmvCG/tLW/peRiDRHBkm+3Edw4\"",
-    "mtime": "2026-09-06T10:58:49.045Z",
+    "mtime": "2026-09-06T14:46:29.735Z",
     "size": 730,
     "path": "../public/_nuxt/BW3xJdEx.js"
   },
+  "/_nuxt/BXXtFil5.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": "\"1bd2-NDdun38lYj0OD2wayMdetDX3ehc\"",
+    "mtime": "2026-09-06T14:46:29.735Z",
+    "size": 7122,
+    "path": "../public/_nuxt/BXXtFil5.js"
+  },
   "/_nuxt/BeLyMmd4.js": {
     "type": "text/javascript; charset=utf-8",
     "etag": "\"1c1-HX03BAMzK3TbabTUt+zazZac6jY\"",
-    "mtime": "2026-09-06T10:58:49.045Z",
+    "mtime": "2026-09-06T14:46:29.735Z",
     "size": 449,
     "path": "../public/_nuxt/BeLyMmd4.js"
   },
-  "/_nuxt/9C5WUlLE.js": {
+  "/_nuxt/BZuUK3cr.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": "\"76057-x5s6sLzHAii+nwAfxpSA3vSHenw\"",
-    "mtime": "2026-09-06T10:58:49.046Z",
-    "size": 483415,
-    "path": "../public/_nuxt/9C5WUlLE.js"
+    "etag": "\"d4e-rtWL1k144ZrYuBUrIE7FN7q4gDI\"",
+    "mtime": "2026-09-06T14:46:29.735Z",
+    "size": 3406,
+    "path": "../public/_nuxt/BZuUK3cr.js"
   },
   "/_nuxt/C_VgD9ZI.js": {
     "type": "text/javascript; charset=utf-8",
     "etag": "\"16e9b-CaBNJIMBZbSuSxfSRmsiBioAcZc\"",
-    "mtime": "2026-09-06T10:58:49.045Z",
+    "mtime": "2026-09-06T14:46:29.735Z",
     "size": 93851,
     "path": "../public/_nuxt/C_VgD9ZI.js"
   },
+  "/_nuxt/DB5Vxbte.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": "\"9f1f-lZvm375DqcFM+vOcKc2rvEVowVM\"",
+    "mtime": "2026-09-06T14:46:29.735Z",
+    "size": 40735,
+    "path": "../public/_nuxt/DB5Vxbte.js"
+  },
   "/_nuxt/error-404.CHsn7XF-.css": {
     "type": "text/css; charset=utf-8",
     "etag": "\"97d-2Jv1I5SVRWWiHcs7d0fjdFylhP4\"",
-    "mtime": "2026-09-06T10:58:49.046Z",
+    "mtime": "2026-09-06T14:46:29.735Z",
     "size": 2429,
     "path": "../public/_nuxt/error-404.CHsn7XF-.css"
   },
   "/_nuxt/error-500.Bawx2bLr.css": {
     "type": "text/css; charset=utf-8",
     "etag": "\"772-1WbEnJKsOodm+94L4M1TNGEMGdA\"",
-    "mtime": "2026-09-06T10:58:49.046Z",
+    "mtime": "2026-09-06T14:46:29.735Z",
     "size": 1906,
     "path": "../public/_nuxt/error-500.Bawx2bLr.css"
   },
+  "/_nuxt/9C5WUlLE.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": "\"76057-x5s6sLzHAii+nwAfxpSA3vSHenw\"",
+    "mtime": "2026-09-06T14:46:29.735Z",
+    "size": 483415,
+    "path": "../public/_nuxt/9C5WUlLE.js"
+  },
   "/_nuxt/builds/latest.json": {
     "type": "application/json",
-    "etag": "\"47-A62hsqMqrttpShO9U5Ab+nBZHXY\"",
-    "mtime": "2026-09-06T10:58:49.041Z",
+    "etag": "\"47-gnWfjO3atXpuKHcTeevtRdg7IRg\"",
+    "mtime": "2026-09-06T14:46:29.732Z",
     "size": 71,
     "path": "../public/_nuxt/builds/latest.json"
   },
   "/_nuxt/entry.b3_DJTEt.css": {
     "type": "text/css; charset=utf-8",
     "etag": "\"2fd30-a1fPhKsI3m5s3WkUz/aQvIKj6Ow\"",
-    "mtime": "2026-09-06T10:58:49.046Z",
+    "mtime": "2026-09-06T14:46:29.735Z",
     "size": 195888,
     "path": "../public/_nuxt/entry.b3_DJTEt.css"
   },
+  "/_nuxt/builds/meta/e0d2b6a3-3a30-44b7-8c79-a56f66400005.json": {
+    "type": "application/json",
+    "etag": "\"58-/O8b6cy7JVz90KrikBRsiFQaWdI\"",
+    "mtime": "2026-09-06T14:46:29.731Z",
+    "size": 88,
+    "path": "../public/_nuxt/builds/meta/e0d2b6a3-3a30-44b7-8c79-a56f66400005.json"
+  },
   "/_nuxt/DMg0j7gv.js": {
     "type": "text/javascript; charset=utf-8",
     "etag": "\"25529-MrmjBHZKW5MJ6UC+MAR50nTTq7U\"",
-    "mtime": "2026-09-06T10:58:49.046Z",
+    "mtime": "2026-09-06T14:46:29.735Z",
     "size": 152873,
     "path": "../public/_nuxt/DMg0j7gv.js"
-  },
-  "/_nuxt/DB5Vxbte.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": "\"9f1f-lZvm375DqcFM+vOcKc2rvEVowVM\"",
-    "mtime": "2026-09-06T10:58:49.045Z",
-    "size": 40735,
-    "path": "../public/_nuxt/DB5Vxbte.js"
-  },
-  "/_nuxt/builds/meta/4c307968-4837-497b-a570-d6ee336accc4.json": {
-    "type": "application/json",
-    "etag": "\"58-vdwrkuxkvo48U14qzidl95rF2gw\"",
-    "mtime": "2026-09-06T10:58:49.040Z",
-    "size": 88,
-    "path": "../public/_nuxt/builds/meta/4c307968-4837-497b-a570-d6ee336accc4.json"
   }
 };
 

package/.output/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shelfware-prod",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "private": true,
   "dependencies": {

package/README.md

@@ -24,7 +24,7 @@ Skills outside your home directory (project-level `.claude/skills` inside a repo
 
 - **`npx shelfware` prints "coming soon".** Your npx cache still holds the `0.0.1` placeholder. Run `npx shelfware@latest` once; npx then caches the real release.
 - **The browser did not open.** Copy the URL from the `shelfware at http://127.0.0.1:<port>` line, or start with `--no-open` and open it yourself.
-- **Port in use.** Pass `--port <n>`; without it shelfware tries 3781 through 3800.
+- **Port in use.** An explicit `--port <n>` that is taken is refused at once with a one-line message; without either the flag or PORT shelfware tries 3781 through 3800. A typo in a flag prints the message and the help text instead of a stack trace.
 - **The catalog is empty.** Check that your skills live under `$HOME/.<tool>/skills`; other locations are not scanned yet.
 
 ## What you get

package/bin/launch.mjs

@@ -13,7 +13,7 @@ export const HOST = '127.0.0.1'
 
 export const HELP = `shelfware — a local catalog of the AI-agent skills on this machine
 
-Usage: shelfware [--port <n>] [--no-open]
+Usage: shelfware [--port <n>] [--no-open] [--help]
 
   --port <n>   bind 127.0.0.1:<n> instead of the first free port from ${DEFAULT_PORT}
   --no-open    do not open the browser (also SHELFWARE_NO_OPEN=1)
@@ -26,6 +26,18 @@ export function makeToken() {
   return `sw_${crypto.randomBytes(32).toString('hex')}`
 }
 
+/**
+ * The raw text stays in the message so `--port abc` reads back as "abc", not NaN.
+ * Digits only: `Number()` would otherwise accept `0x10`, `1e3` and `' 4000 '`,
+ * none of which the help text (`--port <n>`) promises.
+ */
+function parsePort(raw) {
+  if (!/^\d+$/.test(raw)) throw new Error(`Invalid port: ${JSON.stringify(raw)}`)
+  const port = Number(raw)
+  if (port < 1 || port > 65535) throw new Error(`Invalid port: ${JSON.stringify(raw)}`)
+  return port
+}
+
 export function parseArgs(argv = [], env = {}) {
   let port = null
   let open = env.SHELFWARE_NO_OPEN !== '1'
@@ -34,18 +46,18 @@ export function parseArgs(argv = [], env = {}) {
     if (arg === '--no-open') {
       open = false
     } else if (arg === '--port') {
-      port = Number(argv[i + 1])
+      if (i + 1 >= argv.length) throw new Error('--port needs a value')
+      port = parsePort(argv[i + 1])
       i += 1
     } else if (arg.startsWith('--port=')) {
-      port = Number(arg.slice('--port='.length))
+      port = parsePort(arg.slice('--port='.length))
     } else if (arg === '--help' || arg === '-h') {
       return { help: true, port: null, open }
+    } else {
+      throw new Error(`Unknown option: ${arg}`)
     }
   }
-  if (port === null && env.PORT) port = Number(env.PORT)
-  if (port !== null && (!Number.isInteger(port) || port < 1 || port > 65535)) {
-    throw new Error(`Invalid port: ${port}`)
-  }
+  if (port === null && env.PORT) port = parsePort(env.PORT)
   return { help: false, port, open }
 }
 
@@ -87,24 +99,46 @@ export function probeHealth(port, host = HOST) {
   })
 }
 
-export async function waitForHealth(port, { timeoutMs = 10_000, intervalMs = 100, host = HOST, probe = probeHealth } = {}) {
+export async function waitForHealth(port, { timeoutMs = 10_000, intervalMs = 100, host = HOST, probe = probeHealth, signal } = {}) {
   const deadline = Date.now() + timeoutMs
-  while (Date.now() < deadline) {
+  while (Date.now() < deadline && !signal?.aborted) {
     if (await probe(port, host)) return true
-    await new Promise(resolve => setTimeout(resolve, intervalMs))
+    await sleep(intervalMs, signal)
   }
   return false
 }
 
-export function openBrowser(url, { platform = process.platform, spawn = spawnProcess } = {}) {
+/** Resolves after `ms`, or as soon as `signal` aborts — and then leaves no timer behind. */
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve()
+      return
+    }
+    const onAbort = () => {
+      clearTimeout(timer)
+      resolve()
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+export function openBrowser(url, { platform = process.platform, spawn = spawnProcess, env = process.env } = {}) {
   const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open'
   const args = platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  // The opener execs the browser; strip the session token so it never sits in the
+  // browser's environment (the served page is the only place it belongs).
+  const { NUXT_PUBLIC_SHELFWARE_TOKEN: _token, ...childEnv } = env
   // A missing browser opener (e.g. no xdg-open on a headless box) must never take
   // the running server down with it: spawn can throw synchronously (rare) or emit
   // an async 'error' (the common ENOENT case), and an unhandled 'error' on an
   // EventEmitter is fatal. Swallow both.
   try {
-    const child = spawn(cmd, args, { stdio: 'ignore', detached: true })
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true, env: childEnv })
     child.on?.('error', () => {})
     child.unref?.()
   } catch {
@@ -130,7 +164,15 @@ export async function launch({
   entry = serverEntry(),
   spawn = spawnProcess,
 } = {}) {
-  const args = parseArgs(argv, env)
+  let args
+  try {
+    args = parseArgs(argv, env)
+  } catch (err) {
+    log(`shelfware: ${err.message}`)
+    log(HELP)
+    exit(1)
+    return null
+  }
   if (args.help) {
     log(HELP)
     return null
@@ -140,12 +182,28 @@ export async function launch({
     exit(1)
     return null
   }
-  const port = args.port ?? await pickPort(DEFAULT_PORT)
-  env.NUXT_PUBLIC_SHELFWARE_TOKEN = makeToken()
-  env.NITRO_HOST = HOST
-  env.NITRO_PORT = String(port)
-  env.NODE_ENV = 'production'
-  await importServer()
+  if (args.port !== null && !(await isPortFree(args.port))) {
+    log(`shelfware: port ${args.port} is already in use on ${HOST}; pick another with --port`)
+    exit(1)
+    return null
+  }
+  // Both of these can fail for reasons the user can act on — every port in the
+  // range is taken, or the server throws at import (a Nitro crash, or an
+  // EADDRINUSE from losing the race for the auto-picked port). One line, exit 1,
+  // never a stack trace.
+  let port
+  try {
+    port = args.port ?? await pickPort(DEFAULT_PORT)
+    env.NUXT_PUBLIC_SHELFWARE_TOKEN = makeToken()
+    env.NITRO_HOST = HOST
+    env.NITRO_PORT = String(port)
+    env.NODE_ENV = 'production'
+    await importServer()
+  } catch (err) {
+    log(`shelfware: ${err.message}`)
+    exit(1)
+    return null
+  }
   if (!(await waitForHealth(port))) {
     log(`shelfware: the server did not answer on http://${HOST}:${port} within 10 s`)
     exit(1)
@@ -153,6 +211,6 @@ export async function launch({
   }
   const url = `http://${HOST}:${port}`
   log(`shelfware at ${url}`)
-  if (args.open) openBrowser(url, { spawn })
+  if (args.open) openBrowser(url, { spawn, env })
   return { port, url }
 }

package/bin/shelfware.mjs

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 import { launch } from './launch.mjs'
 
-await launch({
-  importServer: () => import('../.output/server/index.mjs'),
-})
+// launch() reports every failure it can foresee as one line and exits 1; this is
+// the last resort, so an unforeseen throw still never reaches the user as a stack.
+try {
+  await launch({ importServer: () => import('../.output/server/index.mjs') })
+} catch (err) {
+  console.error(`shelfware: ${err instanceof Error ? err.message : String(err)}`)
+  process.exit(1)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shelfware",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "shelfware finds the shelfware in your skill drawers.",
   "keywords": [
     "skills",

package/.output/public/_nuxt/builds/meta/4c307968-4837-497b-a570-d6ee336accc4.json

@@ -1 +0,0 @@
-{"id":"4c307968-4837-497b-a570-d6ee336accc4","timestamp":1788692326920,"prerendered":[]}