chore(index): add virtualhere 0.1.0 #3

2026-07-30T21:11:27Z

enricobuehler commented

2026-07-30 21:11:27 +00:00

What changed

Package: @punktfunk/plugin-virtualhere
Version: (none) -> 0.1.0
Type: new plugin

Hands a physical USB device on the couch machine to the host for the length of a session and gives it back after, by driving a VirtualHere USB client the operator installs and licences themselves. Nothing from VirtualHere is bundled, vendored, or downloaded by the plugin.

Diff reviewed

Tarball compared: no previous version — this is a new plugin, so there is nothing to diff against.

curl -sL -o pkg.tgz "https://git.unom.io/api/packages/unom/npm/%40punktfunk%2Fplugin-virtualhere/-/0.1.0/plugin-virtualhere-0.1.0.tgz"
openssl dgst -sha512 -binary pkg.tgz | base64

Published artifact — 12 files, 300 KB:

package.json
dist/index.js        the plugin entry (bundled)
dist/cli.js          the ops CLI (bundled)
dist/ui/…            the console SPA (index.html + 3 asset files + 5 Geist woff2)

Evidence gathered (machine-checkable parts)

These are facts I verified against the published tarball, offered as material for the human review — not as a substitute for it.

Integrity matches, verified independently of CI. Downloaded the tarball from the registry and computed the digest locally; it equals the pinned value byte for byte. bun run validate (live cross-check) also passes for all three entries.
No install lifecycle scripts. The published package.json has no preinstall / install / postinstall / prepare / prepublish. It does carry prepublishOnly, which runs only at publish time on CI, never on a user's machine.
No network endpoints in the shipped backend. Grepping dist/index.js and dist/cli.js for http(s):// returns nothing. Consistent with the design: it talks to the host over loopback via @punktfunk/host (an unbundled dependency) and to the local VirtualHere client over a named pipe (Windows) or the vendor CLI (Linux/macOS).
Dependencies: @punktfunk/host ^0.1.2, @punktfunk/plugin-kit ^0.2.0, effect ^4.0.0-beta.102. No additions beyond what the other kit-built plugins already use.
Version is exact semver, platforms is ["linux","windows"] (macOS is client-only for punktfunk, so there is no macOS host), minHost is 0.15.0 — the same floor as rom-manager, which is the version that introduced the plugin-UI surface this plugin also uses.

End-to-end verification on real hardware

Updated 2026-07-31 — this section replaces the "the bind path has never run against a real device" caveat that was in the first version of this PR. It has now run.

Topology: VirtualHere server on a Linux box sharing a real USB device, client on the Windows host, joined with MANUAL HUB ADD. The plugin's actual service graph (config → journal → pipe transport → binder) was bundled and run against it.

Bind. Our parser read the live listing as [{"address":"home-private.31","name":"QEMU USB Tablet","server":"Desktop Hub"}]; bind returned {"ok":true,"detail":"bound home-private.31"} and wrote the journal. The device really moved: the Windows host gained a VirtualHere USB 3 eXtensible Host Controller, and the client's own LIST reported the device as (In-use by you).
Crash. The process exited without releasing, deliberately — the failure mode the whole journal design exists for.
Recover. A fresh process: binder: 1 binding(s) survived the last run — handing them back → reconciled home-private.31 back to the couch → journal after reconcile: []. An independent LIST confirmed the device was no longer in use.

So the never-strand guarantee is now demonstrated, not merely unit-tested. Both machines were returned to their prior state afterwards.

The transport was separately verified against VirtualHere client v6.0.2: HELP came back byte-identical through the shipped pipe backend and through an independent PowerShell probe.

Review checklist

Deliberately left unticked. This checklist is explicitly the part only a person can do, and ticking it is an attestation about your review, not mine. The evidence above should make the mechanical boxes quick; the reading of the code is yours.

One box needs a judgement call rather than a check: "no obfuscated or minified code where source is expected". The tarball ships a bun build bundle, not source — same as rom-manager and playnite. It is traceable to v0.1.0 in the plugin repo and was built by that repo's CI from the tagged commit, but if you want to satisfy that box strictly, diff the bundle against a local bun run build:all at the tag.

Dependencies added or changed

None beyond the three listed above, all already trusted in this index via the other plugins.

Anything that gave you pause

This plugin depends on a commercial third-party product. VirtualHere is sold separately by VirtualHere Pty. Ltd.; the free tier shares one device, and running their client as a service requires a purchased server licence. The plugin drives its published IPC and bundles nothing of theirs. The console page and README both say "sold separately" and disclaim affiliation. Worth confirming you are comfortable with a catalogued plugin whose usefulness is gated on a paid product.
The package was published before the end-to-end verification above was run — the tag went out first, then the hardware became available. It passed, so nothing is wrong with the artifact, but the ordering was luck rather than judgement, and the right sequence for the next release is verify-then-tag.
Otherwise nothing. The one thing I would have flagged — an unexercised bind path — is what §"End-to-end verification" now covers.

## What changed - **Package:** `@punktfunk/plugin-virtualhere` - **Version:** *(none)* -> `0.1.0` - **Type:** new plugin Hands a physical USB device on the couch machine to the host for the length of a session and gives it back after, by driving a **VirtualHere** USB client the operator installs and licences themselves. Nothing from VirtualHere is bundled, vendored, or downloaded by the plugin. ## Diff reviewed **Tarball compared:** no previous version — this is a new plugin, so there is nothing to diff against. ``` curl -sL -o pkg.tgz "https://git.unom.io/api/packages/unom/npm/%40punktfunk%2Fplugin-virtualhere/-/0.1.0/plugin-virtualhere-0.1.0.tgz" openssl dgst -sha512 -binary pkg.tgz | base64 ``` Published artifact — 12 files, 300 KB: ``` package.json dist/index.js the plugin entry (bundled) dist/cli.js the ops CLI (bundled) dist/ui/… the console SPA (index.html + 3 asset files + 5 Geist woff2) ``` ## Evidence gathered (machine-checkable parts) These are facts I verified against the **published tarball**, offered as material for the human review — not as a substitute for it. - **Integrity matches, verified independently of CI.** Downloaded the tarball from the registry and computed the digest locally; it equals the pinned value byte for byte. `bun run validate` (live cross-check) also passes for all three entries. - **No install lifecycle scripts.** The published `package.json` has no `preinstall` / `install` / `postinstall` / `prepare` / `prepublish`. It does carry `prepublishOnly`, which runs only at publish time on CI, never on a user's machine. - **No network endpoints in the shipped backend.** Grepping `dist/index.js` and `dist/cli.js` for `http(s)://` returns nothing. Consistent with the design: it talks to the host over loopback via `@punktfunk/host` (an unbundled dependency) and to the local VirtualHere client over a named pipe (Windows) or the vendor CLI (Linux/macOS). - **Dependencies:** `@punktfunk/host ^0.1.2`, `@punktfunk/plugin-kit ^0.2.0`, `effect ^4.0.0-beta.102`. No additions beyond what the other kit-built plugins already use. - **Version is exact semver**, `platforms` is `["linux","windows"]` (macOS is client-only for punktfunk, so there is no macOS host), `minHost` is `0.15.0` — the same floor as rom-manager, which is the version that introduced the plugin-UI surface this plugin also uses. ## End-to-end verification on real hardware **Updated 2026-07-31** — this section replaces the "the bind path has never run against a real device" caveat that was in the first version of this PR. It has now run. Topology: VirtualHere **server** on a Linux box sharing a real USB device, **client** on the Windows host, joined with `MANUAL HUB ADD`. The plugin's actual service graph (config → journal → pipe transport → binder) was bundled and run against it. 1. **Bind.** Our parser read the live listing as `[{"address":"home-private.31","name":"QEMU USB Tablet","server":"Desktop Hub"}]`; `bind` returned `{"ok":true,"detail":"bound home-private.31"}` and wrote the journal. The device really moved: the Windows host gained a *VirtualHere USB 3 eXtensible Host Controller*, and the client's own `LIST` reported the device as `(In-use by you)`. 2. **Crash.** The process exited **without releasing**, deliberately — the failure mode the whole journal design exists for. 3. **Recover.** A fresh process: `binder: 1 binding(s) survived the last run — handing them back` → `reconciled home-private.31 back to the couch` → `journal after reconcile: []`. An independent `LIST` confirmed the device was no longer in use. So the never-strand guarantee is now demonstrated, not merely unit-tested. Both machines were returned to their prior state afterwards. The transport was separately verified against VirtualHere client v6.0.2: `HELP` came back byte-identical through the shipped pipe backend and through an independent PowerShell probe. ## Review checklist Deliberately left unticked. This checklist is explicitly the part only a person can do, and ticking it is an attestation about *your* review, not mine. The evidence above should make the mechanical boxes quick; the reading of the code is yours. One box needs a judgement call rather than a check: **"no obfuscated or minified code where source is expected"**. The tarball ships a `bun build` bundle, not source — same as `rom-manager` and `playnite`. It is traceable to `v0.1.0` in the plugin repo and was built by that repo's CI from the tagged commit, but if you want to satisfy that box strictly, diff the bundle against a local `bun run build:all` at the tag. ### Dependencies added or changed None beyond the three listed above, all already trusted in this index via the other plugins. ### Anything that gave you pause 1. **This plugin depends on a commercial third-party product.** VirtualHere is sold separately by VirtualHere Pty. Ltd.; the free tier shares one device, and running their client as a service requires a purchased server licence. The plugin drives its published IPC and bundles nothing of theirs. The console page and README both say "sold separately" and disclaim affiliation. Worth confirming you are comfortable with a catalogued plugin whose usefulness is gated on a paid product. 2. **The package was published before the end-to-end verification above was run** — the tag went out first, then the hardware became available. It passed, so nothing is wrong with the artifact, but the ordering was luck rather than judgement, and the right sequence for the next release is verify-then-tag. 3. Otherwise nothing. The one thing I would have flagged — an unexercised bind path — is what §"End-to-end verification" now covers.

enricobuehler added 1 commit 2026-07-30 21:11:28 +00:00

chore(index): add virtualhere 0.1.0

validate / validate (pull_request) Successful in 5s

Details

2785fa1999

New plugin: hands a physical USB device on the couch to the host for the length of a session
and gives it back after, by driving a separately-licensed VirtualHere client. Nothing from
VirtualHere is bundled or downloaded.

Pinned integrity verified independently against the registry tarball, not only via CI.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

enricobuehler merged commit caa7f40397 into main

2026-07-30 22:23:05 +00:00

enricobuehler deleted branch chore/add-virtualhere-0.1.0

2026-07-30 22:23:06 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: unom/punktfunk-plugin-index#3