motely-wasm 20.0.1 → 20.0.2

package/README.md

@@ -10,25 +10,12 @@ npm install motely-wasm
 
 ## Boot
 
-The WASM binary is **sideloaded** — a separate `dist/bin/motely-wasm.wasm`, **not** base64-embedded — so `boot()` **must** be told where to find it. A no-arg `boot()` will not load the runtime and every search silently does nothing.
-
-In Node, read the bytes and pass them directly (`fetch` can't read `file://` URLs):
+The WASM binary is **embedded** in the JS module — no extra files to serve.
 
 ```js
-import { readFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import bootsharp from "motely-wasm";
 
-const dist = resolve(dirname(fileURLToPath(import.meta.url)), "node_modules/motely-wasm/dist");
-const wasm = await readFile(resolve(dist, "bin", bootsharp.manifest.wasm));
-await bootsharp.boot({ wasm });
-```
-
-In the browser, pass the root URL your host serves `dist/` at:
-
-```js
-await bootsharp.boot("/motely-wasm/dist");
+await bootsharp.boot();
 ```
 
 Guard re-boots with `bootsharp.getStatus() === bootsharp.BootStatus.Standby`.
@@ -110,7 +97,7 @@ import * as fs from "@rewaffle/bootsharp-file-system";
 import { Bootsharp } from "motely-wasm/dist/generated/modules/bootsharp/file-system.g.mjs";
 
 fs.init(Bootsharp.FileSystem.FileMounter);
-await bootsharp.boot("/motely-wasm/dist");
+await bootsharp.boot();
 ```
 
 ## Jimmolate

package/RELEASE.md

@@ -0,0 +1,139 @@
+# Releasing motely-wasm to npm — the real pipeline
+
+This is the finished reasoning for "how do you update the README and the package
+without hand-editing anything," grounded in the Bootsharp docs and the actual
+state of this repo. It replaces the don't-touch comment in `Motely.Wasm.csproj`
+with an *understanding* of why that comment exists and what the correct fix is.
+
+## What ships, and from where
+
+`npm publish` runs from **`motely-wasm/`** (this directory). npm packs three
+things from here, regardless of any `files` field:
+
+| File | Owner today | Owner it should have |
+|------|-------------|----------------------|
+| `package.json` | hand-maintained | **npm** owns the version; structure hand-authored |
+| `README.md`    | hand-created (was *missing* for 20 weeks) | authored here, single source |
+| `dist/`        | Bootsharp build output (`BootsharpPublishDirectory`) | Bootsharp, regenerated on build |
+
+`dist/bin/motely-wasm.wasm` is the sideloaded runtime (`BootsharpBinariesDirectory`
+is set → separate `.wasm`, not base64-embedded → `boot()` MUST be told where it is;
+that is the whole reason for the boot section in `README.md`).
+
+## The root bug: two version sources, already drifted
+
+There are **two** places a version lives, and they are out of sync right now:
+
+- `Directory.Packages.props` → `<MotelyVersion>20.0.0</MotelyVersion>` — the **.NET
+  assembly version**, consumed solution-wide (`Motely.csproj`, `Motely.Wasm.csproj`
+  both do `<Version>$(MotelyVersion)</Version>`).
+- `motely-wasm/package.json` → `"version": "20.0.1"` — the **npm package version**,
+  the one users actually `npm install`.
+
+The published `20.0.1` is the `20.0.0` engine + a fixed README. That patch bump is
+*semantically correct* (docs-only fix), but it was done by **hand-typing `20.0.1`
+into package.json**, which is exactly the foot-gun: a human typing a version is a
+human introducing drift.
+
+These two versions are genuinely different concerns and **may** legitimately
+diverge (a README-only npm patch should not force an engine version bump). The fix
+is not "force them equal" — it's "make each one bumped by a tool, never by hand."
+
+## Why Bootsharp can't own package.json
+
+Bootsharp regenerates `package.json` on every build with a **bare** template — look
+at `Motely.Wasm/obj/package.json` (where it's currently parked):
+
+```json
+{ "name": "motely-wasm", "type": "module", "exports": {...}, "browser": {...} }
+```
+
+No `version`, no `main`, no `types`, no `author`, no `license`, no `description`.
+Publishing that fails (`npm publish` with no version → the `reading 'prerelease'`
+crash the csproj comment warns about). Per the Bootsharp docs, `BootsharpPackageDirectory`
+defaults to the project dir and Bootsharp **overwrites** the file there on every
+build. So pointing it at the real npm root clobbers the rich manifest every build.
+
+The current mitigation — redirect `BootsharpPackageDirectory` to `obj/` and
+hand-author `motely-wasm/package.json` — is **correct**. Don't undo it. The bare
+template genuinely lacks what npm needs, and Bootsharp offers no hook to enrich it.
+
+## The correct ownership split
+
+```
+Directory.Packages.props : MotelyVersion   — engine/assembly version, bump for ENGINE releases
+motely-wasm/package.json : "version"        — npm package version, bump with `npm version patch`
+motely-wasm/package.json : everything else  — stable, hand-authored, rarely changes
+motely-wasm/README.md                       — authored HERE (package root), single source
+motely-wasm/dist/                           — Bootsharp output, never hand-touched
+Motely.Wasm/obj/package.json                — Bootsharp's throwaway bare template, ignored
+```
+
+The "no hand-editing" rule applies to the **version field specifically**. You never
+type a version again — `npm version patch` does. The rest of package.json (exports
+map with types, browser shims, author) is a small stable file; authoring it once by
+hand is fine and *better* than a generator that drops the fields npm requires.
+
+## The release command (zero hand-edits)
+
+From `motely-wasm/`:
+
+```sh
+npm version patch    # 20.0.1 -> 20.0.2 in package.json AND creates the git tag v20.0.2
+npm publish          # packs package.json + README.md + dist/, pushes to npm
+```
+
+`npm version patch` is the tool that "knows" — it edits the version *and* tags git
+atomically. Never open package.json to change the version.
+
+### Make it bulletproof with npm lifecycle scripts (the real automation)
+
+Add to `motely-wasm/package.json` so a stale `dist/` can never ship:
+
+```json
+"scripts": {
+  "build": "dotnet publish ../Motely.Wasm/Motely.Wasm.csproj -c Release",
+  "prepublishOnly": "npm run build"
+}
+```
+
+`prepublishOnly` runs **after** `npm version patch` bumps the version and **before**
+the tarball is packed — so `npm publish` always ships a freshly built `dist/` that
+matches. (`dotnet publish` in Release is the Bootsharp path that emits `dist/` +
+the sideloaded wasm; see Bootsharp `getting-started.md` / `build-config.md`.)
+
+> Not yet wired — this is the one concrete edit the next session should make and
+> test with `npm publish --dry-run`. Left undone tonight on purpose (handoff, not
+> a 2am publish).
+
+## The README: one source, here
+
+`Motely.Wasm/README.md` (the C# project dir) is **stale v19** — it documents the
+removed `jimmolateProbe` / `MotelySingleSearchContext`. It is NOT what ships and
+should be deleted or treated as dead. The shipping README is **`motely-wasm/README.md`**
+(this dir), authored against the live v20 surface. Keep exactly one. Don't add a
+build "copy README" step that creates a second source to drift — author it where it
+ships.
+
+## What's drifted right now (reconcile when clear-headed)
+
+- `MotelyVersion` is `20.0.0`; npm is `20.0.1`. The published wasm reports `20.0.0`
+  internally. Cosmetic, not breaking. If you want them re-aligned, bump
+  `MotelyVersion` to match at the next engine touch and rebuild — don't republish
+  just for this.
+- The `Motely.Wasm.csproj` comment block says "DO NOT re-add a FinalizeNpmPackage
+  target." That advice is still right (Bootsharp's bare template can't be the
+  source), but the *reason* is now written down here instead of as a scar.
+
+## Docs citations
+
+- Bootsharp `build-config.md`: `BootsharpPackageDirectory` (default = project dir,
+  "Directory to publish package.json"), `BootsharpPublishDirectory`,
+  `BootsharpBinariesDirectory`.
+- Bootsharp `sideloading.md`: binaries dir **set** → separate `.wasm`, `boot()` takes
+  a root URL or `{ wasm }` bytes (the v20 boot contract — see `README.md`).
+- Bootsharp `getting-started.md`: `dotnet publish` (Release) produces the module +
+  `package.json`; Release auto-enables NativeAOT-LLVM + trimming.
+- npm: `package.json` / `README.md` / `LICENSE` always ship regardless of `files`;
+  `npm version <patch|minor|major>` bumps version + tags git; `npm publish --dry-run`
+  to verify the tarball before pushing.