@_linked/server 2.24.1 → 2.24.3

package/lib/esm/utils/nativeImport.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Node's own `import()`, out of reach of any bundler or SSR transform.
+ *
+ * Under an app's dev SSR runner this package is itself evaluated by Vite, and
+ * Vite's SSR transform rewrites every `import()` it can see into its own
+ * module loader — `@vite-ignore` only silences the warning, it does not stop
+ * the rewrite. An installed package's backend loaded that way becomes a second,
+ * Vite-evaluated instance alongside the one Node already loaded for the app's
+ * own imports, and both register their shapes (whichever registers last wins).
+ *
+ * Building the call with the Function constructor keeps it out of the source
+ * any transform parses, so it always resolves through Node's ESM loader and
+ * its cache: one instance per resolved file.
+ *
+ * The source carries a per-evaluation nonce. V8 reuses compiled
+ * Function-constructor code by source text across vm contexts, and a dynamic
+ * import in reused code resolves against the context that compiled it first —
+ * under a test runner that runs several files in one worker, that is an
+ * earlier, torn-down file. A unique source gives each evaluation of this
+ * module its own compilation.
+ */
+export declare const nativeImport: (specifier: string) => Promise<any>;

package/lib/esm/utils/nativeImport.js

@@ -0,0 +1,23 @@
+/**
+ * Node's own `import()`, out of reach of any bundler or SSR transform.
+ *
+ * Under an app's dev SSR runner this package is itself evaluated by Vite, and
+ * Vite's SSR transform rewrites every `import()` it can see into its own
+ * module loader — `@vite-ignore` only silences the warning, it does not stop
+ * the rewrite. An installed package's backend loaded that way becomes a second,
+ * Vite-evaluated instance alongside the one Node already loaded for the app's
+ * own imports, and both register their shapes (whichever registers last wins).
+ *
+ * Building the call with the Function constructor keeps it out of the source
+ * any transform parses, so it always resolves through Node's ESM loader and
+ * its cache: one instance per resolved file.
+ *
+ * The source carries a per-evaluation nonce. V8 reuses compiled
+ * Function-constructor code by source text across vm contexts, and a dynamic
+ * import in reused code resolves against the context that compiled it first —
+ * under a test runner that runs several files in one worker, that is an
+ * earlier, torn-down file. A unique source gives each evaluation of this
+ * module its own compilation.
+ */
+export const nativeImport = new Function('specifier', `return import(specifier); // ${Date.now()}-${Math.random()}`);
+//# sourceMappingURL=nativeImport.js.map

package/lib/esm/utils/nativeImport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeImport.js","sourceRoot":"","sources":["../../../src/utils/nativeImport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,QAAQ,CACtC,WAAW,EACX,gCAAgC,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CACvB,CAAC","sourcesContent":["/**\n * Node's own `import()`, out of reach of any bundler or SSR transform.\n *\n * Under an app's dev SSR runner this package is itself evaluated by Vite, and\n * Vite's SSR transform rewrites every `import()` it can see into its own\n * module loader — `@vite-ignore` only silences the warning, it does not stop\n * the rewrite. An installed package's backend loaded that way becomes a second,\n * Vite-evaluated instance alongside the one Node already loaded for the app's\n * own imports, and both register their shapes (whichever registers last wins).\n *\n * Building the call with the Function constructor keeps it out of the source\n * any transform parses, so it always resolves through Node's ESM loader and\n * its cache: one instance per resolved file.\n *\n * The source carries a per-evaluation nonce. V8 reuses compiled\n * Function-constructor code by source text across vm contexts, and a dynamic\n * import in reused code resolves against the context that compiled it first —\n * under a test runner that runs several files in one worker, that is an\n * earlier, torn-down file. A unique source gives each evaluation of this\n * module its own compilation.\n */\nexport const nativeImport = new Function(\n  'specifier',\n  `return import(specifier); // ${Date.now()}-${Math.random()}`\n) as (specifier: string) => Promise<any>;\n"]}

package/package.json

@@ -10,13 +10,18 @@
     "type": "git",
     "url": "git+https://github.com/linked-fw/server.git"
   },
-  "version": "2.24.1",
+  "version": "2.24.3",
   "packageManager": "npm@11.21.0",
   "linkedPackage": true,
   "type": "module",
   "main": "lib/esm/index.js",
   "types": "index.d.ts",
   "license": "ISC",
+  "files": [
+    "lib",
+    "styles",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "start": "npm exec linked dev",
     "test": "NODE_OPTIONS=--experimental-vm-modules npx jest --config jest.config.cjs",

package/.changeset/README.md

@@ -1,20 +0,0 @@
-# Changesets
-
-This package uses [changesets](https://github.com/changesets/changesets) for version management and publishing.
-
-## Adding a changeset
-
-When making a change that should trigger a new release, run:
-
-```bash
-npx changeset
-```
-
-This generates a markdown file in `.changeset/` describing the change. Commit it with your PR.
-
-On merge to `main`, the publish workflow either:
-
-1. Creates (or updates) a **Release PR** that bumps the version + updates `CHANGELOG.md`, or
-2. If the Release PR is already merged, publishes the new version to npm.
-
-Changes that don't need a release (docs, CI config, tooling) can skip the changeset — the check is a warning, not a block.

package/.changeset/config.json

@@ -1,14 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
-  "changelog": [
-    "@changesets/changelog-github",
-    { "repo": "linked-fw/server" }
-  ],
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.gitattributes

@@ -1 +0,0 @@
-package-lock.json linguist-generated=true -diff merge=ours

package/.github/workflows/pr.yml

@@ -1,18 +0,0 @@
-name: PR
-
-on:
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  checks:
-    uses: linked-fw/.github/.github/workflows/pr.yml@v1
-    # The changeset reminder posts a PR comment. A reusable workflow only holds what its
-    # caller granted, and the org default is read-only.
-    permissions:
-      contents: read
-      pull-requests: write
-    with:
-      require-tests: true
-      run-e2e: false

package/.github/workflows/publish.yml

@@ -1,30 +0,0 @@
-# Calls the shared workflow in linked-fw/.github.
-#
-# This FILENAME is what npm's trusted-publisher check validates — not the shared workflow's.
-# Renaming this file invalidates this package's trusted publisher, and the only symptom is
-# that releases quietly start needing manual approval again.
-name: Publish
-
-on:
-  push:
-    branches:
-      - main
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  release:
-    uses: linked-fw/.github/.github/workflows/publish.yml@v1
-    permissions:
-      contents: write
-      pull-requests: write
-      # Needed HERE as well as in the shared workflow: a reusable workflow cannot widen the
-      # permissions its caller was granted, and without this npm never gets an id-token and
-      # every release silently falls back to the approval queue.
-      id-token: write
-    # Named rather than `inherit`: `inherit` forwards everything this repo can see, which is
-    # how a community repo would end up forwarding a first-party token.
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
-      RELEASE_APP_ID: ${{ secrets.RELEASE_APP_ID }}
-      RELEASE_APP_PRIVATE_KEY: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}

package/docs/architecture/01-server-only-surface.md

@@ -1,58 +0,0 @@
----
-summary: Why this package declares its own server-only surface rather than being named by
-  consumers, what the declaration means, and the one part of this package that is not server-only
-  and should not live here.
----
-
-# This package's server-only surface
-
-This package is a **replaceable module**. An application may swap it for another implementation,
-and anything that depends on knowing it by name breaks the moment someone does.
-
-That matters for one specific rule: **a frontend bundle must not contain this package.** Almost
-everything here touches a filesystem, a process or a socket, and a `ShapeProvider` extends
-`BackendProvider`, which imports node's `path`. Pull any of it into a client graph and the bundler
-resolves `path` to the abandoned npm shim of the same name, the shim references `process`, and the
-application hydrates into an empty shell with `ReferenceError: process is not defined` — an error
-naming nothing that would lead you back to the import.
-
-## The declaration
-
-```jsonc
-"linked": {
-  "serverOnly": [".", "./shapes/*", "./server/*", "./utils/*"]
-}
-```
-
-A consuming application's client/server boundary check reads this, rather than hardcoding
-`@_linked/server`. The difference is not stylistic: a check that names this package protects one
-arrangement of the framework, and a replacement inherits none of it. A check that reads
-declarations protects whatever is installed.
-
-It is purely declarative. No code, no exports, and no resolution behaviour depends on it.
-
-## The convention it complements
-
-A consumer also treats anything under `<pkg>/backend/**` as server-only, in **any** package, with
-no declaration needed. Between the two, no application has to know a package by name.
-
-A package whose server-only code all lives under `backend/` therefore needs no `linked.serverOnly`
-at all. This package declares one because its server-only surface predates that convention and is
-spread across several subpaths.
-
-## What is not server-only, and should move
-
-Three exports are client-safe and are published from here anyway:
-
-| Export | Who uses it |
-|---|---|
-| `BackendAPIStore` | the store a **browser** uses to talk to the backend; constructed by an app's frontend storage config |
-| `getAccessUrlLocalFileStore` | the same frontend config |
-| `LincdWebApp` | constructed in a React hook |
-
-They belong in `@_linked/server-utils`, which exists for exactly the isomorphic half of the
-framework. Until they move, every consuming application must carry a standing exception in its
-boundary check — and a boundary with permanent exceptions stops being one.
-
-Tracked as follow-up work; noted here so the next person to wonder why an app imports
-`@_linked/server` from its frontend finds the answer.

package/docs/backlog/001-resize-by-store-key.md

@@ -1,104 +0,0 @@
----
-summary: >
-  DONE. /resized/* no longer fetches anything: both branches read and write
-  through LinkedFileStorage. The `?src=` parameter still accepts a full URL, so
-  nothing broke -- the URL is resolved to a store key and the bytes are read
-  directly, which turned out not to need the major release this item assumed.
-  Kept as the record of why the route looks the way it does.
----
-
-# 001 — Resize by store key instead of fetching a URL
-
-> **Done.** Delivered without the breaking change this item expected: see *Resolution* at the end.
-
-## Where this came from
-
-`?src=` used to be handed straight to `fetch`, which made every deployment an
-open proxy into its own network — and because the fetched bytes were written
-into the *public* file store and the caller redirected to them, a reachable
-internal resource was persisted rather than merely leaked.
-
-That was fixed by restricting `src` to the configured file store: parsed-origin
-comparison against `LinkedFileStorage.accessURL`, a `fileExists` check on the
-derived key, a fetch of a URL rebuilt from that key, and `redirect: 'error'`
-plus a timeout and a size cap. See `src/utils/resizeSource.ts`.
-
-That fix was deliberately the conservative one, because it is backward
-compatible. This item is the version that is actually correct.
-
-## The problem with what is there now
-
-Once `src` is guaranteed to name an image in the store, the URL is a store key
-with extra steps:
-
-- **The fetch is pointless.** `resizeImage` calls
-  `LinkedFileStorage.fileExists(key)` and then performs an HTTP request to
-  retrieve bytes that `LinkedFileStorage.getFile(key)` would return directly.
-  For a local store that is a loopback request to read a file already on disk.
-- **It keeps a fetch that has to stay correct.** Origin comparison, redirect
-  refusal, credential rejection, the size cap and the timeout all exist to make
-  an outbound request safe. None of that code needs to exist if there is no
-  outbound request.
-- **The API lies about what it accepts.** Callers pass a full URL, but only one
-  origin's URLs are valid. A key says what is meant.
-
-## What the change looks like
-
-Replace the `src`-fetch branch with a key lookup:
-
-```ts
-const bytes = await LinkedFileStorage.getFile(key);
-```
-
-`resolveResizeSource` still has a job during a deprecation window — turning a
-legacy full URL into a key — but `fetchStoredImage`, and with it the timeout,
-the size cap and the redirect handling, can go.
-
-## Why it is not done yet
-
-It is a breaking change to the route's contract. Anything passing
-`?src=<full URL>` keeps working only if the URL-to-key translation is retained,
-and anything passing a third-party URL — which no longer works anyway after the
-SSRF fix — breaks visibly rather than silently.
-
-## First open questions
-
-1. Is `?src=` as a full URL used by real consumers, or is the local branch
-   (`/resized/<path>`) the only one anyone uses? That decides whether this needs
-   a deprecation window at all.
-2. Should the key form be a new parameter (`?key=`) so both can coexist for a
-   release, or should `src` simply start accepting a key as well as a URL?
-3. ~~The other branch of the same route reads from `<cwd>/data/uploads`
-   directly~~ — **done.** Both branches now read and write through
-   `LinkedFileStorage`, the derivative cache has its own purpose
-   (`resizedImagesPurpose`), and the hand-rolled directory creation is gone
-   because `LocalFileStore` makes its own parents. That was the larger half of
-   "the route reads and writes through the store"; what is left here is only
-   the remote branch's needless HTTP hop.
-
-## Related
-
-- `src/utils/resizeSource.ts` — the guard this would let go.
-- `src/tests/resized-images.test.ts` — the behaviour that must keep passing.
-
-## Resolution
-
-Done, and the "why it is not done yet" above turned out to be wrong.
-
-The assumption was that dropping the fetch meant dropping `?src=<full URL>`,
-which would break callers and need a major. It does not. The URL form still
-works: `resolveResizeSource` turns it into a store key, and the bytes are then
-read with `LinkedFileStorage.getFile(key)` instead of being fetched over HTTP.
-The request contract is unchanged, so this shipped as a minor.
-
-What went with the fetch: `fetchStoredImage`, the 10s timeout, the 25MB
-streaming cap and `redirect: 'error'`. All of that existed to make an outbound
-request safe, and there is no outbound request any more — the route cannot be
-pointed at anything, rather than being guarded against it.
-
-The local branch had already moved to the store, so both halves now read and
-write the same way.
-
-Open question 2 — whether to add a `?key=` parameter — was not needed and is
-dropped. Question 1, whether anyone passes a full URL, no longer matters either
-way, since both forms cost the same now.

package/docs/reports/001-vite-release-serving.md

@@ -1,100 +0,0 @@
----
-summary: Two fixes that stood between a Vite-built application and a release it could actually
-  serve — the entry tag was rendered as a classic script, and LocalFileStore rewrote the object
-  keys a release is addressed by. Records what was wrong, why neither surfaced earlier, and the
-  contracts they establish.
----
-
-# Serving a Vite-built release
-
-Two independent defects, both on the path from "a release exists" to "a browser runs it". Neither
-could be seen from inside this package: the first needs a real Vite bundle, the second needs a
-release actually published to a local store.
-
-## 1. The entry tag was a classic script
-
-**`LinkedServer.tsx` — [#51](https://github.com/linked-fw/server/pull/51)**
-
-The SSR render passed the client entry to React as `bootstrapScripts`, which emits
-
-```html
-<script src="…/assets/index-abc123.js" async></script>
-```
-
-Vite always emits the client entry as an **ES module**. A browser handed module syntax in a
-classic script refuses the file outright:
-
-```
-Uncaught SyntaxError: Cannot use import statement outside a module
-```
-
-So **no Vite production build could hydrate at all** — the server rendered correct HTML, every
-asset returned 200, and the page stayed inert.
-
-The dev branch immediately above this code already used `bootstrapModules`, for exactly this
-reason. Only the production branch was wrong.
-
-### What it does now
-
-`start()` records whether `assets['main.js']` was resolved from a Vite manifest
-(`mainEntryIsModule`), and the SSR render passes `bootstrapModules` when it was.
-
-This is deliberately **not** unconditional. A legacy webpack bundle is a classic script and a
-module tag would break it, so the decision follows the manifest the entry actually came from
-rather than a global setting.
-
-### Why it survived
-
-Dev never takes this path — `config.server.vite` routes to `bootstrapScriptContent` with the
-React-refresh preamble. And no consuming application had completed a production build, because
-the release pipeline itself was still being finished. The first app to get that far hit this
-immediately.
-
-## 2. `LocalFileStore` rewrote release object keys
-
-**`shapes/filestores/LocalFileStore.ts` — [#52](https://github.com/linked-fw/server/pull/52)**
-
-`resolveTarget`'s preserved character class was `[A-Za-z0-9._/]` — no `-` — so a run of dashes
-collapsed to one:
-
-```
-asked for:  shapeCodeGenerator--2JmNvrO.js
-stored as:  shapeCodeGenerator-2JmNvrO.js
-```
-
-Rollup's default base64 hash alphabet includes `-`, so an entry whose hash begins with one meets
-the separator as `--`. The stored key is then neither what the caller asked for nor what the
-bundle's own URLs point at.
-
-`publish-app` requires a release store to keep keys verbatim and caught it — but only after 125 of
-158 objects had uploaded, leaving an incomplete release.
-
-### What it does now
-
-`-` joins the preserved set. The method's own doc comment already stated the intent — not to
-corrupt "a key a program chose on purpose, such as a Vite content hash: `main-hwqwrAvA.css`" — so
-this makes the character class match what it says. Everything else is unchanged: `My File (2).TXT`
-still becomes `My-File-2-.TXT`.
-
-A regression test in `src/tests/local-file-store.test.ts` covers the doubled dash specifically, and
-was confirmed to fail without the change.
-
-## The contract both establish
-
-**A release object must be addressable by exactly the key it was given.** The bundle's own chunk
-URLs are baked in at build time and nothing rewrites them at request time, so a store that alters a
-key — or a server that renders the entry in a form the browser rejects — breaks the release with no
-useful error.
-
-Anything implementing `IFileStore` for release assets inherits that requirement.
-
-## Known limitation, not fixed here
-
-`LocalFileStore.accessURL` is bare `SITE_ROOT`, while the store writes to `data/uploads/<key>` and
-`LinkedServer` serves that tree at `/uploads` — the `/uploads` segment is appended inside
-`publicURL` instead. `build-app` bakes the bundle's base URL from `accessURL`, so publishing to the
-default store produces chunk URLs missing that segment, and every chunk 404s.
-
-An application can work around it by registering a dedicated `appAssets` store whose `accessURL`
-carries the segment. Moving it into `accessURL` here would be the real fix, but it changes that
-field for every existing consumer and warrants its own assessment.

package/jest.config.cjs

@@ -1,23 +0,0 @@
-/** @type {import('ts-jest/dist/types').JestConfigWithTsJest} */
-module.exports = {
-  preset: 'ts-jest/presets/default-esm',
-  testEnvironment: 'node',
-  rootDir: '.',
-  roots: ['<rootDir>/src/tests'],
-  testMatch: ['<rootDir>/src/tests/*.test.ts'],
-  extensionsToTreatAsEsm: ['.ts', '.tsx'],
-  transform: {
-    '^.+\\.(ts|tsx)$': [
-      'ts-jest',
-      {
-        useESM: true,
-        tsconfig: '<rootDir>/tsconfig-tests.json',
-      },
-    ],
-  },
-  // Strip the `.js` extension from relative ESM imports so ts-jest resolves the
-  // `.ts` source (NodeNext-style specifiers carry `.js`; jest maps back to src).
-  moduleNameMapper: {
-    '^(\\.{1,2}/.*)\\.js$': '$1',
-  },
-};

package/renovate.json

@@ -1,4 +0,0 @@
-{
-  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
-  "extends": ["local>linked-fw/renovate-config"]
-}

package/tsconfig-cjs.json

@@ -1,8 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "module": "commonjs",
-    "target": "es6",
-    "outDir": "lib/cjs"
-  }
-}

package/tsconfig-esm.json

@@ -1,9 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "module": "esnext",
-    "target": "es2018",
-    "outDir": "lib/esm",
-    "moduleResolution": "bundler"
-  }
-}

package/tsconfig-tests.json

@@ -1,11 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "target": "es2020",
-    "noEmit": true
-  },
-  "files": [],
-  "include": ["./src/**/*.ts", "./src/**/*.tsx"]
-}