@descent-vtt/spec-harness 0.0.0 → 0.1.1

package/dist/workspace.js

@@ -0,0 +1,138 @@
+/**
+ * What every command shares: exit codes, options, the repository a command
+ * runs in, and which brief the round is working on.
+ */
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { findActive } from './briefs.js';
+import { briefIdFromBranch } from './branch.js';
+import { loadConfig } from './fs.js';
+import { commonDirectory, currentBranch, workTreeRoot } from './git.js';
+import { createSiblings } from './siblings.js';
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_ERROR = 2;
+/** The version of the JSON documents this tool prints. Bumped when a field changes meaning. */
+export const JSON_SCHEMA_VERSION = 1;
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+export function version() {
+    const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return manifest.version;
+}
+export function parseOptions(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...argv],
+            allowPositionals: true,
+            strict: true,
+            options: {
+                brief: { type: 'string' },
+                base: { type: 'string' },
+                root: { type: 'string' },
+                format: { type: 'string' },
+                strict: { type: 'boolean' },
+                write: { type: 'boolean' },
+                'git-hook': { type: 'boolean' },
+                path: { type: 'string', multiple: true },
+                reason: { type: 'string' },
+                option: { type: 'string', multiple: true },
+                recommend: { type: 'string' },
+                list: { type: 'boolean' },
+                show: { type: 'string' },
+                allow: { type: 'boolean' },
+                deny: { type: 'boolean' },
+                note: { type: 'string' },
+                id: { type: 'string' },
+                at: { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+            },
+        });
+    }
+    catch (error) {
+        throw new UsageError(error.message);
+    }
+    const { values, positionals } = parsed;
+    const format = values.format ?? 'pretty';
+    if (format !== 'pretty' && format !== 'json')
+        throw new UsageError(`--format must be pretty or json, not "${format}"`);
+    const at = values.at;
+    if (at !== undefined && at !== 'base' && at !== 'head' && at !== 'both')
+        throw new UsageError(`--at must be base, head or both, not "${at}"`);
+    return {
+        command: positionals[0],
+        positionals: positionals.slice(1),
+        brief: values.brief,
+        base: values.base,
+        root: values.root,
+        format,
+        strict: values.strict === true,
+        help: values.help === true,
+        version: values.version === true,
+        write: values.write === true,
+        gitHook: values['git-hook'] === true,
+        paths: values.path ?? [],
+        reason: values.reason,
+        options: values.option ?? [],
+        recommend: values.recommend,
+        list: values.list === true,
+        show: values.show,
+        allow: values.allow === true,
+        deny: values.deny === true,
+        note: values.note,
+        id: values.id,
+        at,
+    };
+}
+export async function openWorkspace(options, io) {
+    const cwd = options.root ?? io.cwd;
+    const root = await workTreeRoot(cwd);
+    if (root === null)
+        throw new UsageError(`${cwd} is not inside a git work tree; spec-harness measures rounds by their commits`);
+    const commonDir = (await commonDirectory(root)) ?? `${root}/.git`;
+    const { config } = await loadConfig(root);
+    return { root, commonDir, config, siblings: createSiblings(root, config), branch: await currentBranch(root), cwd: io.cwd };
+}
+/** The id the flag, the environment or the branch names, without asking spec-brief anything. */
+export function namedId(workspace, options, env) {
+    if (options.brief !== undefined && options.brief.trim() !== '')
+        return options.brief.trim();
+    const environment = env['SPEC_BRIEF'];
+    if (environment !== undefined && environment.trim() !== '')
+        return environment.trim();
+    return workspace.branch === null ? null : briefIdFromBranch(workspace.config.branches, workspace.branch);
+}
+export async function activeBrief(workspace, options, env) {
+    if (namedId(workspace, options, env) === null) {
+        return findActive([], {});
+    }
+    const briefs = await workspace.siblings.briefs();
+    const fromBranch = workspace.branch === null ? null : briefIdFromBranch(workspace.config.branches, workspace.branch);
+    return findActive(briefs, { flag: options.brief, environment: env['SPEC_BRIEF'], branch: fromBranch });
+}
+export function describeActive(active) {
+    switch (active.kind) {
+        case 'found':
+            return { brief: active.brief, note: undefined, problem: null };
+        case 'none':
+            return { brief: null, note: active.reason, problem: null };
+        case 'unknown':
+            return { brief: null, note: undefined, problem: `the ${active.source} names brief ${active.id}, and spec-brief knows no such brief` };
+        case 'archived':
+            return {
+                brief: null,
+                note: undefined,
+                problem: `the ${active.source} names brief ${active.brief.id}, which is archived; a closed round writes nothing`,
+            };
+    }
+}
+export function json(command, body) {
+    return `${JSON.stringify({ tool: 'spec-harness', version: version(), schemaVersion: JSON_SCHEMA_VERSION, command, ...body }, null, 2)}\n`;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What every command shares: exit codes, options, the repository a command\n * runs in, and which brief the round is working on.\n */\n\nimport { readFileSync } from 'node:fs';\nimport { parseArgs } from 'node:util';\n\nimport { findActive, type ActiveBrief } from './briefs.js';\nimport { briefIdFromBranch } from './branch.js';\nimport type { HarnessConfig } from './config.js';\nimport { loadConfig } from './fs.js';\nimport { commonDirectory, currentBranch, workTreeRoot } from './git.js';\nimport { createSiblings, type Siblings } from './siblings.js';\nimport type { BriefRow } from './types.js';\n\nexport const EXIT_OK = 0;\nexport const EXIT_FAILED = 1;\nexport const EXIT_ERROR = 2;\n\n/** The version of the JSON documents this tool prints. Bumped when a field changes meaning. */\nexport const JSON_SCHEMA_VERSION = 1;\n\nexport class UsageError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'UsageError';\n  }\n}\n\nexport interface CliIO {\n  readonly stdout: { write(text: string): unknown };\n  readonly stderr: { write(text: string): unknown };\n  readonly stdin?: () => Promise<string>;\n  readonly cwd: string;\n  readonly env: Readonly<Record<string, string | undefined>>;\n}\n\nexport function version(): string {\n  const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string };\n  return manifest.version;\n}\n\nexport interface Options {\n  readonly command: string | undefined;\n  readonly positionals: readonly string[];\n  readonly brief: string | undefined;\n  readonly base: string | undefined;\n  readonly root: string | undefined;\n  readonly format: 'pretty' | 'json';\n  readonly strict: boolean;\n  readonly help: boolean;\n  readonly version: boolean;\n  /** init: apply the plan instead of printing it. */\n  readonly write: boolean;\n  /** init: also install git's pre-commit hook. */\n  readonly gitHook: boolean;\n  /** escalate: the files the round needs, the reason, the options and the recommendation. */\n  readonly paths: readonly string[];\n  readonly reason: string | undefined;\n  readonly options: readonly string[];\n  readonly recommend: string | undefined;\n  readonly list: boolean;\n  readonly show: string | undefined;\n  /** rule: the decision and what it allows. */\n  readonly allow: boolean;\n  readonly deny: boolean;\n  readonly note: string | undefined;\n  /** probe: which probe, and at which commit. */\n  readonly id: string | undefined;\n  readonly at: 'base' | 'head' | 'both' | undefined;\n}\n\nexport function parseOptions(argv: readonly string[]): Options {\n  let parsed;\n  try {\n    parsed = parseArgs({\n      args: [...argv],\n      allowPositionals: true,\n      strict: true,\n      options: {\n        brief: { type: 'string' },\n        base: { type: 'string' },\n        root: { type: 'string' },\n        format: { type: 'string' },\n        strict: { type: 'boolean' },\n        write: { type: 'boolean' },\n        'git-hook': { type: 'boolean' },\n        path: { type: 'string', multiple: true },\n        reason: { type: 'string' },\n        option: { type: 'string', multiple: true },\n        recommend: { type: 'string' },\n        list: { type: 'boolean' },\n        show: { type: 'string' },\n        allow: { type: 'boolean' },\n        deny: { type: 'boolean' },\n        note: { type: 'string' },\n        id: { type: 'string' },\n        at: { type: 'string' },\n        help: { type: 'boolean', short: 'h' },\n        version: { type: 'boolean', short: 'v' },\n      },\n    });\n  } catch (error) {\n    throw new UsageError((error as Error).message);\n  }\n  const { values, positionals } = parsed;\n  const format = values.format ?? 'pretty';\n  if (format !== 'pretty' && format !== 'json') throw new UsageError(`--format must be pretty or json, not \"${format}\"`);\n  const at = values.at;\n  if (at !== undefined && at !== 'base' && at !== 'head' && at !== 'both') throw new UsageError(`--at must be base, head or both, not \"${at}\"`);\n  return {\n    command: positionals[0],\n    positionals: positionals.slice(1),\n    brief: values.brief,\n    base: values.base,\n    root: values.root,\n    format,\n    strict: values.strict === true,\n    help: values.help === true,\n    version: values.version === true,\n    write: values.write === true,\n    gitHook: values['git-hook'] === true,\n    paths: values.path ?? [],\n    reason: values.reason,\n    options: values.option ?? [],\n    recommend: values.recommend,\n    list: values.list === true,\n    show: values.show,\n    allow: values.allow === true,\n    deny: values.deny === true,\n    note: values.note,\n    id: values.id,\n    at,\n  };\n}\n\n/** Everything a command needs about the repository it runs in. */\nexport interface Workspace {\n  readonly root: string;\n  readonly commonDir: string;\n  readonly config: HarnessConfig;\n  readonly siblings: Siblings;\n  readonly branch: string | null;\n  readonly cwd: string;\n}\n\nexport async function openWorkspace(options: Options, io: CliIO): Promise<Workspace> {\n  const cwd = options.root ?? io.cwd;\n  const root = await workTreeRoot(cwd);\n  if (root === null) throw new UsageError(`${cwd} is not inside a git work tree; spec-harness measures rounds by their commits`);\n  const commonDir = (await commonDirectory(root)) ?? `${root}/.git`;\n  const { config } = await loadConfig(root);\n  return { root, commonDir, config, siblings: createSiblings(root, config), branch: await currentBranch(root), cwd: io.cwd };\n}\n\n/** The id the flag, the environment or the branch names, without asking spec-brief anything. */\nexport function namedId(workspace: Workspace, options: Options, env: CliIO['env']): string | null {\n  if (options.brief !== undefined && options.brief.trim() !== '') return options.brief.trim();\n  const environment = env['SPEC_BRIEF'];\n  if (environment !== undefined && environment.trim() !== '') return environment.trim();\n  return workspace.branch === null ? null : briefIdFromBranch(workspace.config.branches, workspace.branch);\n}\n\nexport async function activeBrief(workspace: Workspace, options: Options, env: CliIO['env']): Promise<ActiveBrief> {\n  if (namedId(workspace, options, env) === null) {\n    return findActive([], {});\n  }\n  const briefs = await workspace.siblings.briefs();\n  const fromBranch = workspace.branch === null ? null : briefIdFromBranch(workspace.config.branches, workspace.branch);\n  return findActive(briefs, { flag: options.brief, environment: env['SPEC_BRIEF'], branch: fromBranch });\n}\n\nexport function describeActive(active: ActiveBrief): { brief: BriefRow | null; note: string | undefined; problem: string | null } {\n  switch (active.kind) {\n    case 'found':\n      return { brief: active.brief, note: undefined, problem: null };\n    case 'none':\n      return { brief: null, note: active.reason, problem: null };\n    case 'unknown':\n      return { brief: null, note: undefined, problem: `the ${active.source} names brief ${active.id}, and spec-brief knows no such brief` };\n    case 'archived':\n      return {\n        brief: null,\n        note: undefined,\n        problem: `the ${active.source} names brief ${active.brief.id}, which is archived; a closed round writes nothing`,\n      };\n  }\n}\n\nexport function json(command: string, body: Record<string, unknown>): string {\n  return `${JSON.stringify({ tool: 'spec-harness', version: version(), schemaVersion: JSON_SCHEMA_VERSION, command, ...body }, null, 2)}\\n`;\n}\n\n"]}

package/hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --no-install spec-harness hook claude",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --no-install spec-harness hook claude",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,14 +1,93 @@
 {
   "name": "@descent-vtt/spec-harness",
-  "version": "0.0.0",
-  "description": "Placeholder that holds the name until 0.1.0, which CI publishes with provenance. It contains no code.",
+  "version": "0.1.1",
+  "description": "The agent-facing member of the spec-* tools: context for a round, a guard on every write, an audit when it ends, probes that prove a defect before it is filed, and rulings a person signs.",
+  "keywords": [
+    "agents",
+    "brief",
+    "claude-code",
+    "guardrails",
+    "harness",
+    "hooks",
+    "mcp",
+    "spec"
+  ],
   "license": "MIT",
-  "homepage": "https://github.com/DescentVTT/spec-harness",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "spec-harness": "bin/spec-harness.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./spec-brief-plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "bin",
+    "dist",
+    "skills",
+    "hooks",
+    ".claude-plugin",
+    ".mcp.json",
+    "src/vendor/spec-core/LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run stryker.core.config.mjs",
+    "test:mutation:full": "stryker run",
+    "prepublishOnly": "node -e \"if (process.env.GITHUB_ACTIONS !== 'true') { console.error('npm publish is refused outside GitHub Actions: a release is a v* tag, staged by CI with provenance.'); process.exit(1) }\" && npm run clean && npm run build"
+  },
+  "peerDependencies": {
+    "@descent-vtt/spec-brief": ">=0.2.0",
+    "@descent-vtt/spec-graph": ">=0.9.0",
+    "@descent-vtt/spec-guard": ">=0.12.0"
+  },
+  "peerDependenciesMeta": {
+    "@descent-vtt/spec-graph": {
+      "optional": true
+    },
+    "@descent-vtt/spec-guard": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@descent-vtt/spec-brief": "^0.2.0",
+    "@descent-vtt/spec-guard": "^0.12.0",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
+    "@types/node": "^22.20.4",
+    "@vitest/coverage-v8": "^4.1.11",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DescentVTT/spec-harness.git"
   },
-  "publishConfig": {
-    "access": "public"
-  }
+  "bugs": {
+    "url": "https://github.com/DescentVTT/spec-harness/issues"
+  },
+  "homepage": "https://github.com/DescentVTT/spec-harness#readme"
 }

package/skills/close-round/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: close-round
+description: Check that a round is really done - scope kept, protections held, goals met, the defect's probe green, no unexplained dependency - and hand the archive decision to a person. Use when a brief's work looks finished, before opening or merging its pull request.
+---
+
+# Close a round
+
+## 1. Audit
+
+```bash
+npx spec-harness audit --format json
+```
+
+It reports, as one list: what spec-brief's archive would refuse or warn
+about (open boxes, protected files changed, files outside the scope, work not
+committed), the brief's own assertions (a goal that fails; a premise that
+still holds), rulings whose signatures do not verify, and every dependency the
+round added. Fix what it reports, then run it again. `unmeasured` means it
+could not see the round's commits: pass `--base <branch>`.
+
+## 2. For a defect, show it is gone
+
+```bash
+npx spec-harness probe <id> --at head
+```
+
+`fixed` is the only verdict that closes a defect. Add the evidence table to
+the brief next to the one that measured it.
+
+## 3. Hand over
+
+```bash
+npx spec-brief archive <id> --dry-run --base <branch>
+```
+
+Show the person the audit, the dry run and a short summary of what the round
+did and did not do. Archiving is theirs: they run `spec-brief archive <id>`
+and commit the result. Do not archive a brief yourself.

package/skills/draft-brief/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: draft-brief
+description: Draft the brief for one round of work - the contract an agent works under - from a request, with its scope, its protections and, for a defect, a probe that proves the defect exists. Use when asked to plan, specify or write up a change before implementing it, or when a request is too loose to start on.
+---
+
+# Draft a brief
+
+A brief is the contract for one round: what done looks like, what the round
+must not do, which files it may write and which it may not touch. You write
+it; `spec-brief` checks it; a person approves it before anyone starts. Never
+start implementing from a brief the person has not approved.
+
+## 1. Scaffold from the repository's own rules
+
+```bash
+npx spec-brief new "<short title>" --type <feature|defect|refactor|chore> --wave <n>
+```
+
+The scaffold holds every section this repository requires, each with a hint
+in a comment saying what it must answer. Those hints are your interview:
+ask the person what you cannot find out yourself, one section at a time.
+Press hardest on the two that keep a round from wandering:
+
+- **What the round does not do.** Name the tempting adjacent work and rule it
+  out.
+- **What it is not empowered to change.** Public interfaces, schemas, other
+  teams' code, the rules files themselves.
+
+## 2. Measure the scope, do not guess it
+
+- Find the files the change touches: search the code, read `git log` for
+  files that change together, and ask spec-guard which rules govern them:
+  `npx spec-guard query <path> --json`.
+- Write `affectedFiles` as narrow globs (`src/auth/**`, not `src/**`). A scope
+  too wide makes rounds that could run in parallel wait for each other; one
+  too narrow stops you mid-round. A new directory ends with `/`.
+- Write `protectedFiles` for what lies inside or beside the scope and must not
+  change.
+
+## 3. A defect is measured before it is filed
+
+For a `defect` brief, write a probe: a test that fails now, for the reason
+the brief states, declared in the brief as a `probe` block (with the test in
+a `probe-file` block if it is new). Give it a `signature` - text the failure
+must contain - or a JUnit `test` name, so a compile error is never taken for
+the defect. Then:
+
+```bash
+npx spec-harness probe <id> --at base
+```
+
+`measured` means the defect is real; paste the evidence table into the
+brief. `vacuous` means it is not there: say so to the person and stop.
+`invalid` or `flaky` means the probe proves nothing yet: fix the probe.
+
+## 4. Check, then hand over
+
+```bash
+npx spec-brief lint <id> --format json    # until it reports nothing
+npx spec-brief matrix                     # no collision with its wave
+```
+
+Show the person the brief, the scope and the protections, and wait for their
+approval. The approval is theirs to give; a clean lint is not one.

package/skills/run-round/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: run-round
+description: Carry out one approved brief as a contract - load its context, stay inside its scope, escalate instead of working around a protection, and keep its checklist honest. Use when asked to implement, execute or work on a brief, or when on a branch named like brief/<id>-<topic>.
+---
+
+# Run a round
+
+## 1. Start from the contract
+
+Work on a branch named after the brief, `brief/<id>-<topic>`, or pass
+`--brief <id>`. Then:
+
+```bash
+npx spec-harness context <id>
+```
+
+It gives you the brief in full, the scope as the guard reads it, the rulings
+already signed, the briefs this one waited on, the rules spec-guard holds the
+scope's code to, and the documents the brief cites. Read it before the code.
+
+## 2. Stay inside the lines
+
+- Write the files in `affectedFiles`. If the hook is installed, every edit is
+  checked; otherwise ask first: `npx spec-harness guard <path>`.
+- A protected file is not yours to change. If the round cannot be finished
+  without it, stop and escalate - do not work around it, do not edit through
+  a shell to avoid the hook:
+
+  ```bash
+  npx spec-harness escalate --path <file> --reason "<why the round needs it>" \
+    --option "<option>: <what it costs>" --option "<other option>: <cost>" \
+    --recommend "<which, and why>"
+  ```
+
+  Then wait. A person rules, and signs the ruling; only a signed ruling lets
+  the guard pass the file.
+- A file outside the scope that the round genuinely needs: say so in the
+  brief and tell the person. The archive reports every such file.
+- Adding a dependency is a decision: name it in the brief and say why.
+
+## 3. Keep the checklist true
+
+Tick a box when its work is done and verified, not before. A box you will
+not do gets a note under it that starts with a disposition the repository
+accepts - `**Delegated`, `**Accepted debt`, `**Rejected` by default - and
+says why. Commit as you go; the audit measures commits.

package/skills/split-goal/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: split-goal
+description: Split a goal too large for one round into briefs - each a small, separately reviewable round - ordered by dependency and grouped into waves that provably cannot write the same file. Use when asked to plan a multi-step feature, an epic, or work for several agents in parallel.
+---
+
+# Split a goal into rounds
+
+You decide what the pieces are; the tools decide whether the plan holds.
+
+## 1. Cut along files and decisions
+
+- One brief, one outcome a reviewer can judge on its own. Prefer rounds that
+  touch few files; a round whose scope is `src/**` collides with everything.
+- What must exist before something else can start is a `dependsOn`.
+- Split off what can wait - scaling, polish, the second backend - as its own
+  brief, and give each deferral an **observable trigger** in its text ("when
+  the second tenant signs", "when p95 exceeds 200 ms"), never a date.
+- Write each piece as a draft with the `draft-brief` steps. Drafts need not be
+  complete to be scheduled; their scopes must be.
+
+## 2. Let the tools place the waves
+
+```bash
+npx spec-brief schedule --format json     # if this version has it
+npx spec-brief matrix --all-waves         # otherwise: which pairs collide
+```
+
+A wave may run in parallel only if no two of its briefs can name the same
+file. `schedule` computes waves from `dependsOn` and from collisions; `matrix`
+names a file both briefs would write when two collide. Resolve a collision by
+narrowing a scope, by adding a `dependsOn`, or by moving a brief to a later
+wave - never by leaving it for merge time.
+
+```bash
+npx spec-brief lint --format json         # no cycles, waves in dependency order
+```
+
+## 3. Present the plan
+
+Give the person the list: each brief's title, wave, dependencies and scope,
+and the deferrals with their triggers. The person approves the plan and each
+brief before its round starts.

package/src/vendor/spec-core/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spec-core contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/vendor/spec-core/README.md

@@ -0,0 +1,8 @@
+# Vendored from spec-core
+
+These files are copies of modules from
+[spec-core](https://github.com/DescentVTT/spec-core), byte for byte. Do not edit them here: change
+spec-core, then run `node scripts/vendor.mjs --into <this tool>` there.
+`VENDOR.json` records the commit and the SHA-256 of every file, and this
+tool's tests fail when a file no longer matches its hash. `LICENSE` is
+spec-core's, and ships in this tool's package with the compiled copies.