Skip to content

Commit 28dca30

Browse files
melvincarvalhomelvincarvalho
committed
NEXT.md: lift the core-freeze note; add the Stage-3 seam-consumption plan
The freeze is lifted (serverInfo merged as core #605). Update the stale hard-rule #2, and add a Stage-3 section: how to consume a merged seam — the two blockers (unpublished + the ^0.0.x caret-locks-to-exact-patch trap), why the retrofit isn't a find-replace (call serverInfo() lazily, not at activate), and the recommended first move (retrofit nip05 + webfinger against a locally-linked core, prove the loop, then flip the pin).
1 parent 6b1baef commit 28dca30

1 file changed

Lines changed: 67 additions & 7 deletions

File tree

‎NEXT.md‎

Lines changed: 67 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -34,13 +34,71 @@ plugin), `NOTES.md` (the findings/seams — the real deliverable), and
3434
(`@noble/curves`, `ws`), and `javascript-solid-server/auth.js`. **Never
3535
`javascript-solid-server/src/...`.** A wall you can't cross without an
3636
internal *is a finding* — document it, approximate honestly, move on.
37-
2. **Do NOT modify the JavaScriptSolidServer core repo** (no commits,
38-
branches, or PRs there). Everything goes in *this* repo. (The maintainer
39-
set this explicitly. Two core PRs — #590 `api.mountApp`, #591
40-
`/idp/refresh` — are already open and awaiting their call; leave them.)
37+
2. **The core-freeze is LIFTED (2026-07-11).** Core changes are now on the
38+
table — the four seams from REPORT.md are filed (core #601–#604) and
39+
#601 `api.serverInfo` is **merged** (core #605). Still: one seam per PR,
40+
each independently evidenced, following core's convention (feature
41+
branch → squash PR to `gh-pages` → version bump). Don't bundle; the
42+
value of this experiment is that every seam is separately proven.
43+
(Earlier waves ran under a strict no-core rule — that's why the plugins
44+
are honest approximations; keep them that way until a seam actually
45+
lands and is *published*.)
4146
3. Core is at `~/remote/github.com/JavaScriptSolidServer/JavaScriptSolidServer`,
42-
pinned to 0.0.215 on `gh-pages`. You may **read** it for reference; keep
43-
it clean.
47+
at 0.0.217 on `gh-pages` (serverInfo merged on top, unversioned as of
48+
writing). This repo still consumes the **published npm** JSS, pinned
49+
`^0.0.215` — see the Stage-3 plan below for why that pin blocks
50+
consuming merged-but-unpublished seams.
51+
52+
## Stage 3: consuming the merged seams (the upstream loop)
53+
54+
The point of filing the seams was never the issues — it's closing the
55+
loop: **seam lands in core → plugins get simpler/faithful, proven**.
56+
`api.serverInfo` (#601) is merged (#605); this is how to consume it. The
57+
same shape applies to each seam as it lands.
58+
59+
### What `serverInfo` gives you
60+
61+
`api.serverInfo() → { baseUrl, protocol, host, port, listening }`. A
62+
**function**, called lazily (per-request or in an `onListen` hook via
63+
`api.fastify`) — *not* cached at activate, because with an ephemeral port
64+
the real port only exists after listen. `idpIssuer` wins as the canonical
65+
public `baseUrl`. One call collapses **both** config values most plugins
66+
carry: `.baseUrl` replaces the public-origin config, and
67+
`http://${host}:${port}` replaces `loopbackUrl` (the callable bind).
68+
69+
### Two blockers before a retrofit can go green
70+
71+
1. **Not published.** #605 merged but didn't bump the version — core is
72+
still 0.0.217 and npm has 0.0.215. serverInfo exists only on the branch.
73+
Core must bump → `npm publish` (say 0.0.218) first.
74+
2. **The pin is a trap.** This repo pins `^0.0.215`, and **caret on a
75+
`0.0.x` version locks to the exact patch** (`^0.0.215` = `>=0.0.215
76+
<0.0.216`, i.e. *only* 0.0.215 — which is why we're still on 215 despite
77+
216/217 shipping). Publishing 0.0.218 is **not** enough; the dependency
78+
string itself must change to `^0.0.218`/`0.0.218`, then `npm install`.
79+
Miss this and it looks like "the seam isn't there" when it's the range.
80+
81+
To validate *before* a publish: `npm link` (or a `file:` dep) against the
82+
local core tree on a throwaway branch, then flip to the real version once
83+
it's out.
84+
85+
### The retrofit is NOT a find-replace
86+
87+
Plugins that capture `baseUrl`/`loopbackUrl` at activate and `throw` if
88+
missing (the fail-loud pattern) must **move the `serverInfo()` call to
89+
request time** — at activate the port may be unresolved. Keep
90+
`config.baseUrl` as an *optional override* where a plugin genuinely needs
91+
a public origin different from the server's (reverse-proxy edge cases),
92+
rather than deleting it everywhere.
93+
94+
### Recommended first move
95+
96+
Don't retrofit all ~16 at once. Do **`nip05/` + `webfinger/`** first — the
97+
two where a wrong origin fails *silently* (nip05 serves an empty identity
98+
map), so the before/after story is strongest. One plugins-repo PR against
99+
a locally-linked core, proving the loop closes; once core publishes, flip
100+
the pin and merge. The rest follow the same shape. Then the next seam:
101+
`reservePath` (#602) → `events` (#603) → `authorize` (#604).
44102

45103
## Wave 7 status
46104

@@ -109,7 +167,9 @@ each. Current top four (keep this current as you add consumers):
109167
prefix and can't self-exempt; didweb needs a *parameterized* form.
110168
(micropub/ is the counter-witness: client-discovered endpoints need no
111169
reservation — the seam is about protocol-fixed paths.)
112-
4. **`api.serverInfo`** — broadest (~12 plugins hand-roll their origin).
170+
4. **`api.serverInfo`** — broadest (~16 plugins hand-roll their origin).
171+
**FILED #601, MERGED as core #605** — see the Stage-3 plan above for
172+
consuming it. reservePath #602, events #603, authorize #604 still open.
113173

114174
Plus: the unconsumed-body-**stream** primitive (#583), `api.mcp.registerTool`
115175
(blocks the MCP-tool issues #495/#496/#500/#501), can't-set-server-options,

0 commit comments

Comments
 (0)