@mutmutco/installer-launcher 0.1.12 → 0.1.13

package/README.md

@@ -186,3 +186,55 @@ supported, so there is no `darwin-x64` leg): `npm ci`, install
 `--run test/fixtures/run-hello.mjs a b`, write the `.sha256`,
 and upload `launcher-<product>-<platform>-<arch>`. It is callable (`workflow_call`) and dispatchable,
 and it is the only supported path to a real SEA binary — nothing is faked in this lane.
+
+## Signed fresh acquisition
+
+A signed `payload.json` can declare `acquisition` instead of implementing installation:
+
+```json
+{
+  "acquisition": {
+    "schema": 1,
+    "package": "@scope/product",
+    "archive": "product-1.2.3.tgz",
+    "platforms": ["win32-x64", "win32-arm64", "darwin-arm64"],
+    "convergeEntry": "dist/index.js",
+    "convergeArgs": ["install", "--from-shared-prefix", "$prefix", "--version", "$version"],
+    "rollbackEntry": "dist/index.js",
+    "rollbackArgs": ["install", "--rollback-shared-prefix", "$prefix", "--version", "$version"],
+    "runEntry": "dist/launcher-entry.js",
+    "repairArgs": ["--install-converge"]
+  },
+  "entry": ["$self", "--run", "acquisition-required.mjs"],
+  "verbs": ["start", "doctor"]
+}
+```
+
+The archive and metadata must both be covered by the release signature. Entry paths are
+package-relative; placeholders replace entire argv elements only. The launcher owns a pinned,
+checksum-verified user-local Node 24.20.0/npm 12.0.2, local-archive project-prefix installation
+with lifecycle scripts disabled, credential-free public npm resolution, and stable candidate
+paths. Existing system Node/npm installations are unchanged. Updates acquire the selected
+archive even when a previous product root exists. An unchanged update reuses its candidate and
+runs `runEntry` with `repairArgs` for idempotent selected-product convergence; it never repeats
+acquisition activation or reports ready from directory existence alone. Products own validation of their complete
+release and their activation/host convergence through the declared commands.
+
+Convergence runs the candidate entry directly with real Node, never SEA re-entry. Forwarding
+also uses real Node so product grandchildren can use `process.execPath`. The consumer rollback
+command must durably record prior/candidate selection before activation, compare-and-restore
+under its own lock, restore absence for a fresh failed install, and succeed harmlessly if no
+activation occurred. It must refuse to overwrite a newer concurrent product selection.
+
+A flushed shared pending receipt precedes convergence. The launcher commits its selection
+atomically only after convergence succeeds. On failure or interrupted startup it invokes the
+consumer rollback before allowing another install or forwarding. Failed rollback stays pending.
+A crash after shared commit completes the receipt instead of reverting the committed product.
+Host registration is not atomic: failures can leave host references to retained candidates.
+Candidates are deliberately retained until product-owned reference evidence can permit cleanup.
+An orphan lock-recovery guard fails closed and needs operator diagnosis.
+
+For already-shipped old launchers, copy the exact file exported by
+`@mutmutco/installer-launcher/acquisition-required` into the signed payload as
+`acquisition-required.mjs`, and declare the legacy entry above. Old launchers truthfully refuse
+and instruct the user to rerun the public installer. New launchers use acquisition instead.

package/dist/acquisition-required.mjs

@@ -0,0 +1,3 @@
+// Acquisition declarations require a launcher that owns fresh package/runtime provisioning.
+process.stderr.write('This installer launcher is too old. Run the public installer again to update it.\n');
+process.exitCode = 1;