net-snmp 3.27.0 → 3.28.1

package/README.md

@@ -1556,7 +1556,11 @@ an object, possibly empty, and can contain the following fields:
 
 The `callback` parameter is a callback function of the form
 `function (error, notification)`.  On an error condition, the `notification`
-parameter is set to `null`.  On successful reception of a notification, the error
+parameter is set to `null`.  Where the error was produced while processing a
+received packet - such as an authorization failure for a community or user
+not in the receiver's local authorization lists - the error will include an
+`rinfo` attribute containing the sender socket details of the offending packet.
+On successful reception of a notification, the error
 parameter is set to `null`, and the `notification` parameter is set as an object
 with the notification PDU details in the `pdu` field and the sender socket details
 in the `rinfo` field.  For example:
@@ -1678,6 +1682,11 @@ an object, possibly empty, and can contain the following fields:
  * `mibOptions` - a MIB options object that is passed to the `Mib` instance - see the MIB section
  for further details on this - defaults to the empty object.
 
+As for the receiver, errors that the agent produces while processing a received
+packet - such as an authorization failure, or a request the agent cannot serve -
+include an `rinfo` attribute containing the sender socket details of the offending
+packet.
+
 The `mib` parameter is optional, and sets the agent's singleton `Mib` instance.
 If not supplied, the agent creates itself a new empty `Mib` singleton.  If supplied,
 the `Mib` instance needs to be created and populated as per the [Mib Module](#mib-module)
@@ -1724,7 +1733,9 @@ receiver's community authorization list, the receiver will not accept the notifi
 instead returning a error of class `RequestFailedError` to the supplied callback
 function.  Similarly, if a v3 notification is received with a user whose name is
 not in the receiver's user authorization list, the receiver will return a
-`RequestFailedError`.  If the `disableAuthorization` option is supplied for the
+`RequestFailedError`.  These errors include an `rinfo` attribute containing the
+sender socket details of the unauthorized packet, so that its origin can be
+identified.  If the `disableAuthorization` option is supplied for the
 receiver on start-up, then these local authorization list checks are disabled for
 community notifications and noAuthNoPriv user notifications.  Note that even with
 this setting, the user list is *still checked* for authNoPriv and authPriv notifications,
@@ -3762,6 +3773,18 @@ Example programs are included under the module's `example` directory.
 
  * Discard SNMPv3 responses that fall outside the USM time window, reported as the new `ResponseInvalidCode.ENotInTimeWindow`
 
+# Version 3.28.0 - 11/09/2026
+
+ * Add an `rinfo` attribute to errors that a receiver or agent produces while processing a received packet - covering unknown community and unknown user authorization failures, authentication and privacy level mismatches, digest and decryption failures, and unsupported PDU type rejections - so the sender of an offending packet can be identified
+
+ * Replace `.npmignore` with a `files` allowlist in `package.json`, so the published package ships only the module, its libraries, examples and reference files
+
+# Version 3.28.1 - 12/09/2026
+
+ * Reject table instance OIDs whose row index encoding is malformed, instead of silently decoding them to a different row - a SetRequest naming a non-implied `OctetString` or OID index that claimed a different length than it supplied, or that carried unexpected trailing components, would create a row at the decoded index while answering `NoSuchInstance` for the OID that was requested
+
+ * Decode index parts declared with a fixed `length` without consuming a leading length component, matching the way they are encoded - an index value of `AB` in such a column previously read back as `B`
+
 # License
 
 Copyright (c) 2020 Mark Abrahams <mark@abrahams.co.nz>

package/index.js

@@ -3258,6 +3258,17 @@ Listener.formatCallbackData = function (pdu, rinfo) {
 	};
 };
 
+// Returns a callback that annotates errors with the origin of the packet being
+// processed, so consumers can identify the source of unauthorized or invalid messages
+Listener.rinfoErrorCallback = function (target, rinfo) {
+	return function (error, data) {
+		if ( error && rinfo && ! error.rinfo ) {
+			error.rinfo = rinfo;
+		}
+		target.callback (error, data);
+	};
+};
+
 Listener.processIncoming = function (buffer, authorizer, callback) {
 	var message = Message.createFromBuffer (buffer);
 	var community;
@@ -3564,12 +3575,13 @@ Receiver.prototype.getAuthorizer = function () {
 
 Receiver.prototype.onMsg = function (socket, buffer, rinfo) {
 
+	const callback = Listener.rinfoErrorCallback (this, rinfo);
 	let message;
 
 	try {
-		message = Listener.processIncoming (buffer, this.authorizer, this.callback);
+		message = Listener.processIncoming (buffer, this.authorizer, callback);
 	} catch (error) {
-		this.callback (new ProcessingError ("Failure to process incoming message", error, rinfo, buffer));
+		callback (new ProcessingError ("Failure to process incoming message", error, rinfo, buffer));
 		return;
 	}
 
@@ -3586,13 +3598,13 @@ Receiver.prototype.onMsg = function (socket, buffer, rinfo) {
 	// The only GetRequest PDUs supported are those used for SNMPv3 discovery
 	if ( message.pdu.type == PduType.GetRequest ) {
 		if ( message.version != Version3 ) {
-			this.callback (new RequestInvalidError ("Only SNMPv3 discovery GetRequests are supported"));
+			callback (new RequestInvalidError ("Only SNMPv3 discovery GetRequests are supported"));
 			return;
 		} else if ( message.hasAuthentication() ) {
-			this.callback (new RequestInvalidError ("Only discovery (noAuthNoPriv) GetRequests are supported but this message has authentication"));
+			callback (new RequestInvalidError ("Only discovery (noAuthNoPriv) GetRequests are supported but this message has authentication"));
 			return;
 		} else if ( ! message.isReportable () ) {
-			this.callback (new RequestInvalidError ("Only discovery GetRequests are supported and this message does not have the reportable flag set"));
+			callback (new RequestInvalidError ("Only discovery GetRequests are supported and this message does not have the reportable flag set"));
 			return;
 		}
 		let reportMessage = message.createReportResponseMessage (this.engine, this.context, UsmErrorType.UNKNOWN_ENGINE_ID);
@@ -3603,16 +3615,16 @@ Receiver.prototype.onMsg = function (socket, buffer, rinfo) {
 	// Inform/trap processing
 	// debug (JSON.stringify (message.pdu, null, 2));
 	if ( message.pdu.type == PduType.Trap || message.pdu.type == PduType.TrapV2 ) {
-		this.callback (null, this.formatCallbackData (message, rinfo) );
+		callback (null, this.formatCallbackData (message, rinfo) );
 	} else if ( message.pdu.type == PduType.InformRequest ) {
 		message.pdu.type = PduType.GetResponse;
 		message.buffer = null;
 		message.setReportable (false);
 		this.listener.send (message, rinfo, socket);
 		message.pdu.type = PduType.InformRequest;
-		this.callback (null, this.formatCallbackData (message, rinfo) );
+		callback (null, this.formatCallbackData (message, rinfo) );
 	} else {
-		this.callback (new RequestInvalidError ("Unexpected PDU type " + message.pdu.type + " (" + PduType[message.pdu.type] + ")"));
+		callback (new RequestInvalidError ("Unexpected PDU type " + message.pdu.type + " (" + PduType[message.pdu.type] + ")"));
 	}
 };
 
@@ -4695,41 +4707,73 @@ Mib.prototype.getTableRowInstanceFromRow = function (provider, row) {
 	return rowIndex;
 };
 
+// Splices exactly `length` components off the front of an index address,
+// rejecting encodings that claim more components than they supply.
+Mib.spliceIndexValue = function (addressRemaining, length, oid) {
+	var value = addressRemaining.splice (0, length);
+	if ( value.length !== length ) {
+		throw new RangeError ("Index encoding in \"" + oid + "\" claims " + length +
+			" components but supplies " + value.length);
+	}
+	return value;
+};
+
+// Determines how many OID components an index part occupies, consuming a
+// leading length component for variable-length parts that are neither
+// implied nor of a fixed length.
+Mib.getIndexPartLength = function (indexPart, addressRemaining, oid) {
+	var length;
+	if ( indexPart.implied ) {
+		return addressRemaining.length;
+	}
+	if ( indexPart.length ) {
+		return indexPart.length;
+	}
+	length = Number (addressRemaining.shift ());
+	if ( ! Number.isInteger (length) || length < 0 ) {
+		throw new RangeError ("Index encoding in \"" + oid + "\" has a missing or invalid length component");
+	}
+	return length;
+};
+
 Mib.getRowIndexFromOid = function (oid, index) {
-	var addressRemaining = oid.split (".");
+	var addressRemaining = oid === "" ? [] : oid.split (".");
 	var length = 0;
 	var values = [];
 	var value;
 	for ( var indexPart of index ) {
 		switch ( indexPart.type ) {
 			case ObjectType.OID:
-				if ( indexPart.implied ) {
-					length = addressRemaining.length;
-				} else {
-					length = addressRemaining.shift ();
-				}
-				value = addressRemaining.splice (0, length);
+				length = Mib.getIndexPartLength (indexPart, addressRemaining, oid);
+				value = Mib.spliceIndexValue (addressRemaining, length, oid);
 				values.push (value.join ("."));
 				break;
 			case ObjectType.IpAddress:
 				length = 4;
-				value = addressRemaining.splice (0, length);
+				value = Mib.spliceIndexValue (addressRemaining, length, oid);
 				values.push (value.join ("."));
 				break;
 			case ObjectType.OctetString:
-				if ( indexPart.implied ) {
-					length = addressRemaining.length;
-				} else {
-					length = addressRemaining.shift ();
-				}
-				value = addressRemaining.splice (0, length);
+				length = Mib.getIndexPartLength (indexPart, addressRemaining, oid);
+				value = Mib.spliceIndexValue (addressRemaining, length, oid);
 				value = value.map (c => String.fromCharCode(c)).join ("");
 				values.push (value);
 				break;
 			default:
-				values.push (parseInt (addressRemaining.shift ()) );
+				if ( addressRemaining.length === 0 ) {
+					throw new RangeError ("Index encoding in \"" + oid + "\" is missing a component");
+				}
+				value = parseInt (addressRemaining.shift ());
+				if ( Number.isNaN (value) ) {
+					throw new RangeError ("Index encoding in \"" + oid + "\" has a non-numeric component");
+				}
+				values.push (value);
 		}
 	}
+	if ( addressRemaining.length > 0 ) {
+		throw new RangeError ("Index encoding in \"" + oid + "\" has " + addressRemaining.length +
+			" unexpected trailing component(s)");
+	}
 	return values;
 };
 
@@ -5160,12 +5204,13 @@ Agent.prototype.tableRowStatusHandlerInternal = function (createRequest) {
 
 Agent.prototype.onMsg = function (socket, buffer, rinfo) {
 
+	const callback = Listener.rinfoErrorCallback (this, rinfo);
 	let message;
 
 	try {
-		message = Listener.processIncoming (buffer, this.authorizer, this.callback);
+		message = Listener.processIncoming (buffer, this.authorizer, callback);
 	} catch (error) {
-		this.callback (new ProcessingError ("Failure to process incoming message", error, rinfo, buffer));
+		callback (new ProcessingError ("Failure to process incoming message", error, rinfo, buffer));
 		return;
 	}
 
@@ -5200,7 +5245,7 @@ Agent.prototype.onMsg = function (socket, buffer, rinfo) {
 	} else if ( message.pdu.type == PduType.GetBulkRequest ) {
 		this.getBulkRequest (socket, message, rinfo);
 	} else {
-		this.callback (new RequestInvalidError ("Unexpected PDU type " +
+		callback (new RequestInvalidError ("Unexpected PDU type " +
 			message.pdu.type + " (" + PduType[message.pdu.type] + ")"));
 	}
 };
@@ -5284,7 +5329,15 @@ Agent.prototype.tryCreateInstance = function (varbind, requestType) {
 			subOid = Mib.getSubOidFromBaseOid (oid, provider.oid);
 			subAddr = subOid.split(".");
 			column = parseInt(subAddr.shift(), 10);
-			row = Mib.getRowIndexFromOid(subAddr.join("."), provider.tableIndex);
+			try {
+				row = Mib.getRowIndexFromOid(subAddr.join("."), provider.tableIndex);
+			} catch (error) {
+				// The OID is not a valid index encoding for this table, so it names no
+				// row and there is nothing to create. Leave the varbind to be answered
+				// as NoSuchInstance.
+				debug (error);
+				return undefined;
+			}
 			rowStatusColumn = provider.tableColumns.reduce( (acc, current) => current.rowStatus ? current.number : acc, null );
 
 			if ( requestType === PduType.SetRequest &&

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "net-snmp",
-  "version": "3.27.0",
+  "version": "3.28.1",
   "description": "JavaScript implementation of the Simple Network Management Protocol (SNMP)",
   "author": "Mark Abrahams <mark@abrahams.co.nz>",
   "license": "MIT",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "lib/",
+    "example/",
+    "ref/",
+    "CONTRIBUTING.md",
+    "README.cn.md",
+    "!example/test.js"
+  ],
   "directories": {
     "example": "example"
   },

package/.claude/skills/git-commit/SKILL.md

@@ -1,54 +0,0 @@
----
-name: git-commit
-description: Creates a git commit summarizing all current working tree changes (staged and unstaged). Use when the user asks to commit, save progress, or invoke /git-commit.
----
-
-# Git Commit
-
-## When to use
-
-- When the user asks to commit current changes.
-- When invoked via `/git-commit`.
-
-## Arguments
-
-- `dry-run` — perform steps 1–3 only (gather context, identify files, draft commit message) and then **ask the user** whether to proceed with the actual commit or cancel. Do **not** stage or commit until the user confirms.
-
-## Workflow
-
-1. **Gather context** — run these commands in parallel:
-   - `git status` — to see all tracked modifications and untracked files.
-   - `git diff` and `git diff --cached` — to see unstaged and staged changes.
-   - `git log --oneline -10` — to match the repository's commit message style.
-
-2. **Stage all relevant changes** — add all modified and untracked files that are part of the current work. Use specific file paths rather than `git add -A`. Do **not** stage files that likely contain secrets (`.env`, credentials, etc.) — warn the user if any are present.
-
-3. **Draft the commit message** — analyse the diff and write a concise commit message:
-   - One summary line (imperative mood, under 72 characters) describing the *why* / *what* of the change.
-   - If the change is non-trivial, add a blank line followed by bullet points elaborating key changes.
-   - **Don't pad small commits**: if the summary line already captures the change, omit the body entirely. Most single-purpose commits need only the summary line.
-   - **Stay high-level**: never reference code-level details like variable names, function names, method calls, or file paths in the commit message. Describe *what changed for the user or system*, not *which functions were modified*.
-   - Match the style and conventions visible in the recent git log.
-
-4. **Commit** — create the commit using a heredoc for the message:
-   ```bash
-   git commit -m "$(cat <<'EOF'
-   <summary line>
-
-   <optional body>
-   EOF
-   )"
-   ```
-
-5. **Verify** — run `git status` after the commit to confirm it succeeded and the working tree is clean (or shows only intentionally unstaged files).
-
-6. **Show the commit** — run `git log -1` and display the **entire** commit message (summary line and body) to the user so they can review it. Do not truncate or abbreviate — if the message has bullet points or a multi-line body, include all of it in your response.
-
-## Rules
-
-- Never amend an existing commit unless the user explicitly asks.
-- Never push to the remote unless the user explicitly asks.
-- Never use `--no-verify` or skip pre-commit hooks.
-- If a pre-commit hook fails, fix the issue, re-stage, and create a **new** commit (do not amend).
-- Never stage `.env`, credential files, or other secrets.
-- Never add `Co-Authored-By`, `Authored-By`, `Made-with` or any other attribution trailer to commit messages.

package/.claude/skills/prepare-release/SKILL.md

@@ -1,97 +0,0 @@
----
-name: prepare-release
-description: Prepare a release by running lint + tests, bumping the package.json version, and appending a version summary to README.md. Use when the user asks to "prepare a release", "cut a release", or invokes /prepare-release. Stops immediately on lint/test failure so the user can fix issues before continuing.
----
-
-# Prepare Release
-
-## When to use
-
-- User asks to prepare / cut a release.
-- User invokes `/prepare-release`.
-- Immediately before the release commit — this skill stages no files and creates no commit; hand off to `/git-commit` afterwards.
-
-## Release model
-
-The release content is the union of **(a)** commits since the last tag and **(b)** uncommitted user-facing changes in the working tree. Both are valid sources; the typical flow is that the fix being released sits uncommitted alongside the version bump and README update, and the user then commits them all together in a single release commit.
-
-Consequences:
-- Do **not** object to uncommitted changes in the working tree — they are expected and are part of what is being released. Treat them as release content, not as a blocker.
-- Do **not** require at least one committed change since the last tag. The release may consist entirely of working-tree changes that have not yet been committed.
-- When drafting the README bullets in step 5, summarise the user-facing changes visible across **both** sources (committed commits since the last tag **and** the diff of the working tree before this skill began modifying it).
-- The only changes this skill itself creates are in `package.json`, `package-lock.json`, and `README.md`. Everything else in the working tree was already the user's in-progress release content.
-
-## Arguments
-
-- `patch` (default) — bumps the patch component, e.g. `3.26.1` → `3.26.2`.
-- `minor` — bumps the minor component and resets patch, e.g. `3.26.1` → `3.27.0`.
-- `major` — bumps the major component and resets minor/patch, e.g. `3.26.1` → `4.0.0`.
-
-If the user supplies anything else, stop and ask for clarification.
-
-## Workflow
-
-Run steps in order. **If any step fails, stop immediately, report the failure, and do not proceed.** Do not modify `package.json`, `package-lock.json`, or `README.md` until lint and tests pass.
-
-### 1. Pre-flight checks (parallel)
-
-- `git status --short` — capture the working tree state. Per the release model above, treat uncommitted changes as part of the release content, not as a blocker. Still surface the list to the user so they can spot anything that looks unintended (e.g. a modified file they don't remember touching) before the eventual release commit.
-- `git rev-parse --abbrev-ref HEAD` — confirm the current branch. If it is not `master`, warn the user and ask whether to continue.
-- `git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || git log --format=%H | tail -1)..HEAD` — collect commits since the last tag (or since the beginning if no tags exist). These feed the README summary in step 5 alongside the working-tree diff.
-- `git diff` and `git diff --cached` — capture the uncommitted user-facing changes. These also feed the README summary in step 5.
-- Read current version from `package.json`.
-
-Only stop at pre-flight if **both** the commit list and the uncommitted diff are empty — in that case there is genuinely nothing to release.
-
-### 2. Lint
-
-Run `npm run lint`. **Stop on non-zero exit.** Report the linter output verbatim and do not continue.
-
-### 3. Tests
-
-Run `npm test`. **Stop on non-zero exit.**
-
-Exception: the `Subagent` tests in `test/subagent.test.js` require a locally-running AgentX master (`snmpd`) and will fail with `ECONNREFUSED` if one is not present. If the only failures are Subagent `ECONNREFUSED` failures, report them and ask the user whether to proceed (they may have intentionally skipped running snmpd). All other failures are hard stops.
-
-### 4. Bump version
-
-Run `npm version <patch|minor|major> --no-git-tag-version`. This updates both `package.json` and `package-lock.json` atomically without creating a commit or tag. Capture the new version string for the README entry.
-
-If the argument was omitted, default to `patch`.
-
-### 5. Append README version summary
-
-- Read `README.md`.
-- Locate the `# License` heading near the end.
-- Insert a new version section **immediately before** `# License`, separated by a blank line above and below, in exactly this format:
-
-```
-# Version X.Y.Z - DD/MM/YYYY
-
- * <concise user-facing summary of change 1>
-
- * <concise user-facing summary of change 2>
-```
-
-Notes:
-- Date is **today's date** in `DD/MM/YYYY` (day/month/year) — use the date from the environment, not a hardcoded value.
-- Each bullet begins with a single space, then `*`, then a space. There is a blank line between bullets (match the style of the existing entries).
-- Bullets describe **user-visible changes** — not refactors, lint fixes, test additions, or internal tidy-ups. Write them like release notes, not commit subjects. Draw from **both** the commit list gathered in step 1 and the uncommitted working-tree diff; merge/reword where helpful so each line stands on its own.
-- If there is only one user-visible change, include just one bullet.
-- Do not touch any other part of `README.md`.
-
-### 6. Summary
-
-Report to the user, concisely:
-- New version number.
-- Bullets added to `README.md`.
-- The full list of uncommitted files now staged for the release commit — both the pre-existing working-tree changes and the three files this skill modified (`package.json`, `package-lock.json`, `README.md`). Flag anything that looks unexpected.
-
-Do **not** run `git add`, `git commit`, `git tag`, or `npm publish` — those are the user's decision. The next step is typically `/git-commit`.
-
-## Things to watch for
-
-- If `npm version` fails because the working tree is dirty, it has not been run with `--no-git-tag-version` correctly — re-check the command.
-- If the README insertion point (`# License`) cannot be found, stop and ask the user — do not guess.
-- If the lint or test commands are missing from `package.json`, stop and report.
-- Never bypass a failing check with `--no-verify`, `SKIP=`, or similar; the user must fix the underlying issue.

package/.claude/skills/propose-action/SKILL.md

@@ -1,111 +0,0 @@
----
-name: propose-action
-description: Review a GitHub issue or PR by number and propose a concrete action plan — either a reasoned recommendation not to action it, or the code and test changes required to action it. Use when the user asks to "propose an action" for an issue/PR, "look at issue/PR #N", or invokes /propose-action with an issue or PR number. Ends by asking whether to proceed, proceed with modifications, or abandon.
----
-
-# Propose Action
-
-## When to use
-
-- The user asks to review a GitHub issue or PR and recommend what to do about it.
-- The user invokes `/propose-action <number>`.
-
-This skill **plans only** for steps 1–5 — it does not edit code, run tests, commit, push, or comment on the issue/PR during the proposal phase. Implementation happens after the user approves the plan in step 5's closing question. Once the user has approved and you have carried out the agreed actions, step 6 produces a ready-to-paste reply to the issue/PR aligned with what was actually done — but never posts it.
-
-## Arguments
-
-- `<number>` (required) — the GitHub issue or PR number. Bare integer, or `#N`, or a full GitHub URL are all acceptable forms.
-
-If the number is missing, ambiguous, or does not resolve to an issue/PR in the current repository, stop and ask the user to clarify.
-
-## Workflow
-
-### 1. Identify the target
-
-- Determine the current repository: `gh repo view --json nameWithOwner -q .nameWithOwner`.
-- Resolve the number to either an issue or a PR. GitHub numbers them in the same namespace, so try PR first, then issue:
-  - `gh pr view <number> --json number,title,state,author,body,headRefName,baseRefName,isDraft,mergeable,additions,deletions,changedFiles,labels,comments,reviews`
-  - If that fails, `gh issue view <number> --json number,title,state,author,body,labels,comments,assignees`
-- Record whether the target is an **issue** or a **PR** — the two branches below differ.
-
-### 2a. If the target is an issue
-
-Gather context in parallel:
-- The issue body and all comments (from the `gh issue view` JSON above).
-- `gh issue view <number> --json linkedPullRequests` — check for linked PRs that may already address it.
-- Identify the files or subsystems the issue points at. Search the repo (`Grep`, `Glob`, `Read`) for the relevant code. Do not guess — read the actual files the issue describes.
-- If the issue references specific OIDs, error messages, function names, or SNMP behaviours, locate them in the source.
-
-### 2b. If the target is a PR
-
-Gather context in parallel:
-- PR body, comments, and reviews (from the `gh pr view` JSON above).
-- `gh pr diff <number>` — the full diff.
-- `gh pr view <number> --json files -q '.files[].path'` — changed files.
-- Read the **current** version of each changed file on the base branch so you understand what the PR is replacing, not just what it adds.
-- If the PR closes or references an issue (via `Fixes #N`, `Closes #N`, etc.), also fetch that issue for context.
-- Check CI status if available: `gh pr checks <number>`.
-
-### 3. Form a judgement
-
-Decide which of these recommendations fits, and be willing to recommend **against** actioning:
-
-- **Do not action** — the issue is invalid, already fixed, out of scope, based on a misunderstanding, a duplicate, or the PR is the wrong approach / would regress behaviour / conflicts with project direction. Explain *why* clearly, citing the code or prior commits that support the conclusion.
-- **Action as-is** — the issue is valid and the fix is clear, or the PR is correct and should be merged as submitted.
-- **Action with modifications** — the issue is valid but the obvious fix is wrong; or the PR has the right idea but needs specific changes before it can be merged.
-- **Needs more information** — the report is plausible but underspecified. List the exact questions to ask the reporter / author before any code change is possible.
-
-Base the judgement on what the code actually does today, not on what the issue/PR claims. If the two disagree, surface the disagreement.
-
-### 4. Draft the proposal
-
-Structure the written proposal in this order. Keep it concrete — name files, line numbers, function names, and the specific behaviours being changed.
-
-1. **Target** — `Issue #N: <title>` or `PR #N: <title>`, plus one sentence on its state (open/closed/draft/merged, CI status for PRs).
-2. **Summary of the report** — one short paragraph in your own words describing what the reporter is asking for or proposing. Do not just quote the body.
-3. **Findings** — what the code currently does, whether the report is accurate, and any related context (linked issues/PRs, prior commits, existing tests covering this area). Cite `file:line` locations.
-4. **Recommendation** — one of the four options from step 3, stated plainly in a sentence or two.
-5. **Proposed changes** (omit if the recommendation is *do not action* or *needs more information*):
-   - **Code** — for each file to change, list the edit as a bullet: `path/to/file.js:<line-range> — <what changes and why>`. For non-trivial edits, include a short before/after sketch (a few lines, not a full diff).
-   - **Tests** — list tests to **add**, **modify**, or **delete**, each with the file and a one-line description of what the test asserts. If no test changes are needed, say so explicitly and justify (e.g. "covered by existing test at `test/x.test.js:42`").
-   - **Docs / README** — note any README or inline-doc updates required. Release-note bullets are handled by `/prepare-release`; do not pre-empt them here.
-6. **Risks and unknowns** — anything that could make the plan wrong: behaviours you could not verify, edge cases the tests would not catch, compatibility concerns, or assumptions about the reporter's environment.
-7. **Out of scope** — closely-related issues you noticed while investigating but are **not** proposing to fix in this action. Keeps the scope honest.
-
-### 5. Closing question
-
-End the response with exactly one question, offering three choices:
-
-> Proceed with this plan as-is, proceed with modifications (tell me what to change), or abandon it?
-
-Do not start implementing until the user answers. If the user says "proceed", begin implementing the plan in the next turn. If the user asks for modifications, revise the proposal and ask the same question again. If the user says to abandon, stop and skip step 6.
-
-### 6. Ready-to-paste issue/PR reply
-
-After the agreed actions have been carried out (code edits, tests, docs, or a reasoned decision not to action), produce a single ready-to-paste reply for the issue/PR. This is the **last** thing you output, rendered in a fenced block or delimited by `---` so the user can copy it cleanly.
-
-The reply must be aligned with **what actually happened**, not with the original plan — if the user asked for modifications during implementation, reflect the modified outcome. If a step was skipped or failed, say so honestly; do not describe work that was not done.
-
-Tailor the content to the recommendation from step 3:
-
-- **Action as-is / with modifications** — acknowledge the report, give the user a short, concrete summary of the fix (with the key code change or snippet inline if it helps them adopt it), point at the files/sections that changed (e.g. "updated in `README.md` under *Scalar providers*"), and note when it will ship (e.g. "will land in the next release" — do not invent a version number unless `package.json` has already been bumped). If there's a workaround the reporter can apply before the release, include it.
-- **Do not action** — explain the reasoning in the reporter's terms, citing the code or prior history that supports the decision. Be respectful: the reporter put effort into the report. Offer an alternative path if one exists (a different API, a related issue, a config change). If the issue should be closed, say so; do not close it yourself.
-- **Needs more information** — list the specific questions you need answered, each as its own bullet. Explain briefly *why* each is needed so the reporter can see what would unblock progress.
-
-Style:
-
-- Match the tone of prior replies in this repository if they are visible in the issue/PR thread — don't suddenly adopt a different register.
-- Write as the maintainer would: first person, conversational, no corporate voice, no marketing copy, no emoji unless the repo's existing replies use them.
-- Do not include a signature, do not add attribution trailers (no "generated by", no `Co-Authored-By`), do not tag the reporter more than once.
-- Keep it focused — one screen of text is almost always enough. If the reply needs code blocks, prefer short, complete snippets over long diffs.
-
-Hand the reply to the user with one sentence above it saying where to paste it (e.g. "Ready-to-paste reply for issue #297:"). Do **not** run `gh issue comment` / `gh pr comment` / `gh issue close` / `gh pr merge` — the user posts it.
-
-## Rules
-
-- **Never** edit files, run tests, or modify git state during steps 1–5. Planning only.
-- **Never** post a comment on the issue/PR, add labels, request reviews, merge, or close — not in step 6, not ever within this skill. Those are the user's decision.
-- **Never** fabricate line numbers or function names — if you cite `file:line`, you must have read it.
-- If `gh` is not authenticated or the number does not exist, stop and report the error verbatim.
-- If the issue/PR is in a different repository than the current working directory, stop and confirm with the user before proceeding — the plan would target the wrong codebase.
-- Keep the proposal focused. A plan that touches ten files for a one-line bug is a signal to re-read the issue, not to write a bigger plan.

package/.claude/skills/publish-release/SKILL.md

@@ -1,68 +0,0 @@
----
-name: publish-release
-description: Publish the currently-committed release by pushing master to origin, publishing to npm, tagging the commit with the package.json version, and pushing the tag. Use when the user asks to "publish the release", "push and publish", or invokes /publish-release. Stops immediately on any failure.
----
-
-# Publish Release
-
-## When to use
-
-- After `/prepare-release` and the release commit have both been completed — this skill assumes the release commit (version bump + README entry + fix) is already `HEAD` on `master`.
-- User asks to publish / ship / release to npm.
-- User invokes `/publish-release`.
-
-Run after `/prepare-release` + `/git-commit`, never in place of them. This skill does not run lint, tests, or modify any files.
-
-## Workflow
-
-Run steps in order. **If any step fails, stop immediately, report the failure, and do not proceed.** There is no rollback — each step is externally observable (a push, a publish, a tag on origin), so a mid-flight failure leaves the release in a partial state the user will need to reason about. Be explicit about which steps succeeded and which did not.
-
-### 1. Pre-flight checks (parallel)
-
-- `git rev-parse --abbrev-ref HEAD` — confirm the current branch is `master`. If not, stop and ask the user.
-- `git status --short` — confirm the working tree is clean. If not, stop — the release commit must already exist as `HEAD`, with nothing else pending.
-- Read the current version from `package.json` (this becomes the tag name).
-- `git tag --list <version>` — confirm the tag does not already exist locally. If it does, stop.
-- `git ls-remote --tags origin refs/tags/<version>` — confirm the tag does not already exist on the remote. If it does, stop.
-- `git log -1 --format=%s` — capture the subject of the HEAD commit for the summary.
-
-### 2. Push master to origin
-
-Run `git push origin master`. **Stop on non-zero exit.** Report the output.
-
-### 3. Publish to npm
-
-Run `npm publish`. **Stop on non-zero exit.**
-
-Notes:
-- If the registry prompts for a one-time password (2FA OTP), relay the prompt to the user and wait for their input. Do not attempt to bypass 2FA.
-- If the registry rejects with `403` or `You do not have permission`, stop and surface the full error — the user may need to `npm login` or check their credentials.
-- If the registry rejects with `You cannot publish over the previously published versions`, stop — the version was not bumped correctly upstream of this skill.
-
-### 4. Tag the release
-
-Tags in this repo are bare version numbers (no `v` prefix) — verified against the existing tag list.
-
-Run `git tag <version>` where `<version>` is the exact value read from `package.json` in step 1 (e.g., `3.26.2`, not `v3.26.2`).
-
-**Stop on non-zero exit.**
-
-### 5. Push the tag
-
-Run `git push origin <version>`. **Stop on non-zero exit.**
-
-### 6. Summary
-
-Report to the user, concisely:
-- The version that was published.
-- Confirmation of: master pushed, npm publish succeeded, tag created, tag pushed.
-- The release commit subject (from pre-flight).
-- The npm package URL, if it can be derived from `package.json` name (`https://www.npmjs.com/package/<name>`).
-
-## Things to watch for
-
-- If step 2 (push master) succeeds but step 3 (npm publish) fails, the commit is on GitHub but not on npm. Do not tag — the user must either resolve the npm issue and re-run publish, or roll back the push.
-- If step 3 (npm publish) succeeds but step 4 (tag) or step 5 (tag push) fails, the package is on npm but not tagged. Surface this clearly — the user needs to manually create / push the tag, and an un-tagged published release is a fix-it-now situation, not something to leave for later.
-- Never use `--force`, `--no-verify`, or any flag that bypasses checks, even to recover from a mid-flight failure. Always ask the user.
-- Never create or push tags for versions other than the one in `package.json`.
-- Never run this skill on a branch other than `master` without explicit user confirmation.

package/.github/FUNDING.yml

@@ -1 +0,0 @@
-github: [markabrahams]

package/.travis.yml

@@ -1,13 +0,0 @@
-language: node_js
-node_js:
-  - lts/*
-  - 20
-  - 18
-  - 16
-  - 14
-  - 12
-  - 10
-  - 8
-
-script:
-  - npm run lint