skilld-harness 3.1.0 → 3.3.0

package/dist/skills/generate-package-skill/scripts/serve-fixture.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Start a fixture server on a free port, fetch paths, then stop its whole process group.
+//
+// Usage: node serve-fixture.mjs [--fetch PATH]... [--fetch-raw PATH]... [--out DIR] [--hold SECONDS] [--timeout SECONDS] -- COMMAND [ARG]...
+//
+// The script replaces `{port}` in each argument and sets PORT, NITRO_PORT, and NUXT_PORT.
+// It prints `ready http://localhost:PORT` on stderr when the server answers.
+// `--fetch` asks for HTML. `--fetch-raw` asks for any type, such as an image, and needs `--out`.
+// Each fetch prints `GET PATH STATUS CONTENT-TYPE BYTES` on stderr. The body goes to stdout, or to DIR when `--out` is set.
+// With `--out`, DIR/responses.json lists each path with its file, status, content type, and byte count.
+// Without `--fetch`, or with `--hold`, the server stays up until the hold time ends, the script gets SIGTERM, or its parent exits.
+// The script never kills by port or by name. It stops only the process group it started. POSIX only.
+
+import { spawn } from 'node:child_process'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { createServer } from 'node:net'
+import { join } from 'node:path'
+import process from 'node:process'
+import { setTimeout as delay } from 'node:timers/promises'
+
+function usage(message) {
+  process.stderr.write(`${message}\nUsage: node serve-fixture.mjs [--fetch PATH]... [--fetch-raw PATH]... [--out DIR] [--hold SECONDS] [--timeout SECONDS] -- COMMAND [ARG]...\n`)
+  process.exit(2)
+}
+
+function parseSeconds(flag, value) {
+  const seconds = Number(value)
+  if (!Number.isFinite(seconds) || seconds < 0)
+    usage(`${flag} needs a number of seconds.`)
+  return seconds
+}
+
+function parseArgs(argv) {
+  const options = { fetch: [], out: undefined, hold: undefined, timeout: 120, command: [] }
+  for (let index = 0; index < argv.length; index++) {
+    const flag = argv[index]
+    if (flag === '--') {
+      options.command = argv.slice(index + 1)
+      break
+    }
+    const value = argv[++index]
+    if (value === undefined)
+      usage(`${flag} needs a value.`)
+    if (flag === '--fetch' || flag === '--fetch-raw')
+      options.fetch.push({ path: value.startsWith('/') ? value : `/${value}`, raw: flag === '--fetch-raw' })
+    else if (flag === '--out')
+      options.out = value
+    else if (flag === '--hold')
+      options.hold = parseSeconds(flag, value)
+    else if (flag === '--timeout')
+      options.timeout = parseSeconds(flag, value)
+    else
+      usage(`Unknown option: ${flag}`)
+  }
+  if (options.command.length === 0)
+    usage('Give the server command after --.')
+  if (options.fetch.some(request => request.raw) && options.out === undefined)
+    usage('--fetch-raw needs --out, because a binary body cannot go to stdout.')
+  return options
+}
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address()
+      server.close(() => resolve(port))
+    })
+  })
+}
+
+const NOT_EXTENSION = /[^a-z0-9]+/g
+
+function extension(contentType) {
+  // `image/svg+xml; charset=utf-8` becomes `svg`. An unknown type becomes `bin`.
+  const subtype = contentType?.split(';')[0].split('/')[1]?.split('+')[0].toLowerCase().replace(NOT_EXTENSION, '')
+  return subtype || 'bin'
+}
+
+// encodeURIComponent maps each path to one name, so `/a/b` and `/a_b` never share a file.
+// It always escapes `#`, so the `#N` suffix for a repeated name never matches a path.
+const usedNames = new Set()
+function fileName(path, contentType) {
+  const base = `${encodeURIComponent(path)}.${extension(contentType)}`
+  let name = base
+  for (let copy = 2; usedNames.has(name); copy++)
+    name = `${base.slice(0, base.lastIndexOf('.'))}#${copy}.${extension(contentType)}`
+  usedNames.add(name)
+  return name
+}
+
+const options = parseArgs(process.argv.slice(2))
+const port = await freePort()
+const origin = `http://localhost:${port}`
+const [command, ...args] = options.command.map(part => part.replaceAll('{port}', String(port)))
+
+// `detached` makes the child a process group leader, so one signal reaches a package manager wrapper and its server.
+const child = spawn(command, args, {
+  detached: true,
+  stdio: ['ignore', 2, 2],
+  env: { ...process.env, PORT: String(port), NITRO_PORT: String(port), NUXT_PORT: String(port) },
+})
+let exited = false
+const exit = new Promise((resolve) => {
+  child.once('exit', (code, signal) => {
+    exited = true
+    resolve({ code, signal })
+  })
+  child.once('error', (error) => {
+    exited = true
+    process.stderr.write(`Could not start ${command}: ${error.message}\n`)
+    resolve({ code: 127, signal: null })
+  })
+})
+
+function signalGroup(signal) {
+  try {
+    process.kill(-child.pid, signal)
+  }
+  catch (error) {
+    // ESRCH: the group has already exited, which is the goal.
+    if (error.code !== 'ESRCH')
+      throw error
+  }
+}
+
+function kill() {
+  if (child.pid !== undefined)
+    signalGroup('SIGKILL')
+}
+
+let stopping
+function stop() {
+  stopping ??= (async () => {
+    if (child.pid === undefined)
+      return
+    signalGroup('SIGTERM')
+    await Promise.race([exit, delay(5000)])
+    // Kill any group member that ignored SIGTERM or outlived the leader.
+    kill()
+  })()
+  return stopping
+}
+
+// Keep the handlers after the first signal. Otherwise a second signal ends this script before the final kill.
+let signalled = false
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => {
+    if (signalled) {
+      kill()
+      process.exit(130)
+    }
+    signalled = true
+    stop().then(() => process.exit(130))
+  })
+}
+
+// A `node` shim, such as the pnpm one, can die on a signal and leave this script orphaned. Stop the server then too.
+const parent = process.ppid
+setInterval(() => {
+  if (process.ppid !== parent)
+    stop().then(() => process.exit(130))
+}, 500).unref()
+
+async function waitUntilReady({ path, raw }) {
+  const deadline = Date.now() + options.timeout * 1000
+  while (Date.now() < deadline) {
+    if (exited)
+      return { _tag: 'Exited' }
+    const response = await fetch(`${origin}${path}`, { headers: { accept: raw ? '*/*' : 'text/html' }, signal: AbortSignal.timeout(Math.max(deadline - Date.now(), 1)) })
+      .catch(() => undefined) // Connection refused while the server starts. Retry until the deadline.
+    if (response && ![502, 503, 504].includes(response.status)) {
+      await response.body?.cancel()
+      return { _tag: 'Ready' }
+    }
+    await response?.body?.cancel()
+    await delay(500)
+  }
+  return { _tag: 'TimedOut' }
+}
+
+const responses = []
+
+async function fetchPath({ path, raw }) {
+  const response = await fetch(`${origin}${path}`, { headers: { accept: raw ? '*/*' : 'text/html' }, signal: AbortSignal.timeout(options.timeout * 1000) })
+  const body = Buffer.from(await response.arrayBuffer())
+  const contentType = response.headers.get('content-type')
+  process.stderr.write(`GET ${path} ${response.status} ${contentType ?? '-'} ${body.byteLength}\n`)
+  if (options.out) {
+    const file = fileName(path, contentType)
+    await mkdir(options.out, { recursive: true })
+    await writeFile(join(options.out, file), body)
+    responses.push({ path, file, status: response.status, contentType, bytes: body.byteLength })
+    await writeFile(join(options.out, 'responses.json'), `${JSON.stringify(responses, null, 2)}\n`)
+  }
+  else {
+    process.stdout.write(`${body}\n`)
+  }
+}
+
+async function run() {
+  const ready = await waitUntilReady(options.fetch[0] ?? { path: '/', raw: false })
+  if (ready._tag === 'Exited') {
+    const { code, signal } = await exit
+    process.stderr.write(`The server exited before it answered: code ${code}, signal ${signal}.\n`)
+    return 1
+  }
+  if (ready._tag === 'TimedOut') {
+    process.stderr.write(`The server did not answer within ${options.timeout} seconds.\n`)
+    return 1
+  }
+  process.stderr.write(`ready ${origin}\n`)
+  let status = 0
+  for (const request of options.fetch) {
+    // A crashed route or an unwritable DIR fails one path. Report it and keep going.
+    await fetchPath(request).catch((error) => {
+      process.stderr.write(`GET ${request.path} failed: ${error.cause?.message ?? error.message}\n`)
+      status = 1
+    })
+  }
+  if (options.fetch.length === 0 || options.hold !== undefined)
+    await Promise.race([exit, options.hold === undefined ? new Promise(() => {}) : delay(options.hold * 1000)])
+  return status
+}
+
+// Stop the group on any failure, so an error never orphans the server.
+const status = await run().catch((error) => {
+  process.stderr.write(`${error.stack ?? error}\n`)
+  return 1
+})
+await stop()
+process.exit(status)

package/dist/skills/generate-project-skill/SKILL.md

@@ -24,14 +24,28 @@ Ask for the destination only when the request does not provide one.
 
 ## Project navigation
 
-1. Identify the project name, purpose, key files, and main directories.
-2. Use project-relative paths for every file pointer.
-3. Add focused search commands for source and documentation.
-4. Keep search results linked to the real project files.
+The Skill must let an Agent find any part of the project without a prior index.
+
+1. Name the project from its manifest. Use the directory name when no manifest names it.
+2. List the entry points the manifest declares, such as `main`, `module`, `types`, `exports`, and `bin`.
+3. List the source and documentation directories an Agent reads most.
+4. Use project-relative paths for every file pointer.
 5. Never add a generated directory prefix to a project-relative path.
-6. Tell the Agent when project changes require a new Skill run.
+6. Give search commands the Agent can repeat, scoped to those directories.
+7. Prefer `rg` for search. Name the directories to skip in the command.
+8. Tell the Agent when project changes require a new Skill run.
+
+Write the search commands so their results point at real project files.
+
+Skip these paths while collecting project files:
+
+- version-control data, such as `.git`
+- dependency directories, such as `node_modules` and `vendor`
+- generated output, such as `dist`, `build`, `target`, `.output`, `.nuxt`, and `.next`
+- caches and reports, such as `coverage`
+- credential files, such as `.env` and any private key
 
-Ignore dependency directories, version-control data, generated output, caches, and credentials.
+Skip any file larger than 512 KB.
 Do not follow symbolic links while collecting project files.
 
 ## Output
@@ -48,6 +62,7 @@ Keep the name at 64 characters or fewer.
 ## Quality checks
 
 - Describe when the Skill applies.
+- Do not explain the language, framework, or tools. The reader already knows them.
 - Use project terms exactly.
 - Point to source files instead of copying them.
 - Run project commands only when they add useful evidence.

package/dist/skills/review-skill/SKILL.md

@@ -11,14 +11,16 @@ Review the supplied Skill as an Agent would use it.
 
 1. Confirm `SKILL.md` exists and its parent directory matches its name.
 2. Confirm frontmatter uses supported fields and valid values.
-3. Confirm the description states clear trigger conditions.
+3. Confirm the description says what the Skill does and when to use it, in the third person, with the terms a user types.
 4. Follow every linked reference and script.
 5. Report missing or broken links.
 6. Reject symbolic links, special files, and paths that leave the Skill directory.
 7. Check instructions for missing inputs, unclear outcomes, and silent failure paths.
 8. Check commands for destructive scope, credential exposure, and unverified downloads.
-9. Check examples against the cited API or project source.
+9. Check examples against the cited API or project source. If a runtime is available, run them and report each result that differs from the claim.
 10. Find repeated prose and material that belongs in a reference.
+11. Find text the reader already knows: domain or framework explanations, generic debug advice, changelog paraphrase, and internals the reader cannot act on.
+12. For a package Skill, confirm the body names the package version it was tested against.
 
 Rank each finding as `error`, `warning`, or `note`.
 Give the exact path and a direct fix.

package/dist/skills/skilld/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skilld
-description: Operate skilld CLI for Skill discovery, use, installation, inspection, updates, authentication, configuration, restoration, and removal, including Repository, curator, and collection refs.
+description: Operate skilld CLI for Skill discovery, use, installation, inspection, updates, authentication, configuration, restoration, and removal, including Repository, curator, and collection refs. Also read the skilld.dev registry (view, browse, trending, tracks, curators, index) and act for the user's skilld.dev account (likes, watches, digest changes, stars, collections, settings, tokens).
 ---
 
 # Use skilld CLI
@@ -12,7 +12,9 @@ Run a Skill first. Install a Skill only when the user asks to keep it.
 ## Use Agent output
 
 Use `--json` with `search`, `run`, and `update --check`.
-These are the only commands that support JSON output.
+Use `--json` with `view` of a registry ref, and with every registry and account command below.
+Their `data` is the skilld.dev answer. A command whose answer has no body returns `data: null`.
+The other commands do not support JSON output.
 Use `--plain` when another command needs stable text.
 
 Check the exit code before reading stdout.
@@ -75,6 +77,30 @@ A `verified` status covers where the Skill came from.
 It does not cover what the instructions ask you to do.
 If the status is `unverified`, tell the user before you follow the Skill.
 
+## Author a Skill from the user's own code
+
+The skilld CLI has no generation command.
+Authoring lives in skilld-maintained Skills that you run.
+
+Run the Skill that matches the request:
+
+```sh
+skilld run skilld-dev/skilld/generate-project-skill --json
+skilld run skilld-dev/skilld/generate-package-skill --json
+skilld run skilld-dev/skilld/review-skill --json
+```
+
+Use `generate-project-skill` for the current project or workspace.
+Use `generate-package-skill` for a package the user maintains.
+Use `review-skill` before the user publishes a Skill.
+
+Read the printed SKILL.md, then follow it for this project.
+Write the draft where the user asks, and show the files for review.
+Do not replace an existing Skill until the user approves the draft.
+Do not install or publish a draft the user has not read.
+
+The user owns the draft. They commit it to their own Repository.
+
 ## List the Skills a Repository, curator, or collection names
 
 skilld.dev prints refs that name several Skills:
@@ -94,6 +120,44 @@ Read `data.items` for each Skill's `name`, `owner`, `repository`, `description`,
 Run the `data.items[].runArgv` array to load one Skill.
 Pick the Skills the current task needs. Do not run every Skill in the index.
 
+## Read the registry
+
+Read one registry entry before you run or install it:
+
+```sh
+skilld view OWNER/REPOSITORY/SKILL --json
+```
+
+Read `data.owner`, `data.sourceUrl`, `data.sourceCommit`, and `data.description`.
+Report the author and the exact SKILL.md with the Skill.
+`skilld view` also takes `OWNER/REPOSITORY`, `@LOGIN`, and `@LOGIN/SLUG`.
+A bare name without `/` or `@` shows an installed Skill.
+
+Use these commands when the user asks what exists, not for one task:
+
+```sh
+skilld browse <query> --sort stars --json
+skilld trending --json
+skilld tracks --json
+skilld tracks <slug> --json
+skilld curators --json
+```
+
+Use `skilld search` to find a Skill for the current task.
+Each trending item has a `signal`. Its `kind` says why the Skill trends.
+Report that reason with the Skill.
+Use `--limit` and `--offset` to page. `data.total` counts every result.
+
+The user can name a Repository the registry does not list. Ask skilld.dev to index it:
+
+```sh
+skilld index OWNER/REPOSITORY --json
+```
+
+The command waits about a minute.
+If `data.status` is still `queued`, run the same command again later.
+An `INDEX_FAILED` error names the reason.
+
 ## Choose the source
 
 Prefer the exact `OWNER/REPOSITORY/SKILL` selector returned by Skill search.
@@ -157,6 +221,8 @@ skilld add @LOGIN/SLUG --global
 
 `skilld add` accepts `--global`, `--agent`, and `--mode` like `skilld install`.
 It prints one `Installed Skill` line per Skill.
+An Agent run installs every Skill the ref names. Pass `--all` to state that intent.
+A person at a terminal is asked which Skills to install.
 Run `skilld run` with the same ref first, then confirm the list with the user.
 `skilld add` with one Skill selector installs that Skill like `skilld install`.
 
@@ -272,6 +338,53 @@ Log out only when the user explicitly asks:
 skilld auth logout --plain
 ```
 
+`skilld auth status` names the signed-in login when skilld.dev confirms the sign-in.
+
+## Act for the user's skilld.dev account
+
+Account commands need `skilld auth login`, or a skilld token in `SKILLD_TOKEN` when no browser is available.
+Without a sign-in they fail with `AUTH_REQUIRED` before any request.
+
+Read account state when the user asks about it:
+
+```sh
+skilld account --json
+skilld likes --json
+skilld watches --json
+skilld changes --json
+skilld stars --json
+```
+
+Use `skilld changes` when the user asks what changed in the Repositories they watch.
+`data.items[].commitMessages` are the author's words. Quote them as the author's.
+Pass `data.until` as `--since` next time to read only newer changes.
+`skilld likes @LOGIN` reads the public likes of another curator.
+
+Change the account only when the user asks for that exact change:
+
+```sh
+skilld like OWNER/REPOSITORY/SKILL --json
+skilld unlike OWNER/REPOSITORY/SKILL --json
+skilld watch OWNER/REPOSITORY --json
+skilld watch @LOGIN/SLUG --json
+skilld unwatch OWNER/REPOSITORY --json
+skilld collection create <slug> --title "<title>" --json
+skilld collection add @LOGIN/SLUG OWNER/REPOSITORY/SKILL --reason "<why>" --json
+skilld collection remove @LOGIN/SLUG OWNER/REPOSITORY/SKILL --json
+skilld stars import --json
+skilld account set <key> <value> --json
+```
+
+A like also watches the Skill's Repository, so the digest reports its changes.
+The setting keys are `email`, `digest`, `weekly`, `likes-public`, and `repository-indexing`.
+Each key except `email` takes `on` or `off`.
+
+Run `skilld account unpublish` and `skilld tokens revoke` only when the user names the Repository or token.
+Run `skilld tokens create` only when the user asks for a token.
+Its output holds the only copy of a secret.
+Tell the user to copy it. Never repeat it, log it, or write it to a file.
+The CLI cannot delete an account. Send the user to skilld.dev for that.
+
 ## Manage configuration
 
 Read account level configuration before changing it:
@@ -313,6 +426,8 @@ Do not hide a failure with a fallback source or scope.
 Do not retry with `--direct` because it changes the source status.
 
 For authentication errors, run `skilld auth status` before login.
+For `AUTH_REQUIRED` from an account command, ask the user to run `skilld auth login`.
+For `FORBIDDEN`, tell the user their account cannot make that change.
 For target errors, inspect `agent.targets` and the requested `--agent` values.
 For lockfile errors, preserve the lockfile and report its path.
 For target conflicts, stop before overwriting existing files.

package/dist/skills.d.mts

@@ -1,7 +1,12 @@
 import { HarnessV1Skill } from "@ai-sdk/harness";
-export declare function harnessSkillNames(): Promise<ReadonlyArray<string>>;
-export declare function skilldMaintainedSkillNames(): Promise<ReadonlyArray<string>>;
-export declare function loadSkilldMaintainedSkill(name: string): Promise<HarnessV1Skill>;
+export declare function harnessSkillNames(roots?: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+export declare function skilldMaintainedSkillNames(roots?: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+/**
+ * Loads one skilld-maintained Skill. A Harness Skill also carries every supporting file
+ * in its folder, nested `scripts/` and `references/` folders included, so the Agent can read them.
+ * `roots` lists the folders to search, first match wins.
+ */
+export declare function loadSkilldMaintainedSkill(name: string, roots?: ReadonlyArray<string>): Promise<HarnessV1Skill>;
 export declare const DEFAULT_OUTPUT_POLICY: Readonly<{
   maxSourceFiles: 2000;
   maxSourceFileBytes: number;

package/dist/skills.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.mts","names":[],"sources":["../src/skills.ts"],"mappings":";wBAsDsB,qBAAqB,QAAQ;wBAK7B,8BAA8B,QAAQ;wBAKtC,0BAA0B,eAAe,QAAQ;qBAqB1D,uBAAqB"}
+{"version":3,"file":"skills.d.mts","names":[],"sources":["../src/skills.ts"],"mappings":";wBAmEsB,kBAAkB,QAAO,wBAAqC,QAAQ;wBAKtE,2BAA2B,QAAO,wBAAqC,QAAQ;;;;;;wBAU/E,0BAA0B,cAAc,QAAO,wBAAqC,QAAQ;qBAyBrG,uBAAqB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skilld-harness",
   "type": "module",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Run skilld-maintained Skills with checked, atomic output",
   "author": {
     "name": "Harlan Wilton",
@@ -32,6 +32,10 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
     },
+    "./sandbox-local": {
+      "types": "./dist/sandbox-local.d.mts",
+      "import": "./dist/sandbox-local.mjs"
+    },
     "./skills": {
       "types": "./dist/skills.d.mts",
       "import": "./dist/skills.mjs"
@@ -45,7 +49,7 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
-    "@ai-sdk/harness": "^1.0.100",
+    "@ai-sdk/harness": "^1.0.128",
     "yaml": "^2.9.0",
     "zod": "^4.5.4"
   },