@foldkit/node 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Devin Jameson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @foldkit/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@foldkit/node` starts a built Foldkit server-rendered application on Node.
+It reads `foldkit.build.json` to find the client output and Fetch handler.
+
+## Install
+
+```bash
+npm install @foldkit/node @effect/platform-node
+```
+
+## Serve a build
+
+Build the application with `vite build`, then run a Node entry point such as:
+
+```ts
+import { Config, Option, String } from 'effect'
+
+import { NodeRuntime } from '@effect/platform-node'
+import * as Node from '@foldkit/node'
+
+const port = Config.withDefault(Config.Port('PORT'), 3000)
+const origin = Config.option(Config.String('ORIGIN')).pipe(
+  Config.map(Option.filter(String.isNonEmpty)),
+)
+
+NodeRuntime.runMain(Node.serve({ port, origin }))
+```
+
+`origin` is the public URL of the deployment. When it is `None`, the adapter
+uses `http://localhost:<port>`. Set it behind a proxy or TLS terminator so the
+server entry receives the public `Request.url`.
+
+The adapter serves matching client files only for `GET` and `HEAD`. It sends
+the Vite-base `index.html` path, such as `/app/index.html` for `/app/`, and
+every request that does not match a static file to the Fetch handler. It does
+not choose a `Cache-Control` policy or replace application 404 responses.
+
+Pass `manifestPath` to `serve` when the manifest is not at
+`dist/server/foldkit.build.json` relative to the process working directory.
+When the server output is outside the Vite root, also pass `rootDirectory` so
+the adapter can locate the client output recorded by the manifest.
+
+For a Vite application built with a root-relative `base` such as `/app/`, pass
+the same value as `basePath`. The adapter serves client files only under that
+path and preserves it in URLs passed to the Fetch handler.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { serve } from './node.js';
+export type { ServeOptions } from './node.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AAEjC,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { serve } from './node.js';

package/dist/node.d.ts

@@ -0,0 +1,37 @@
+import { Config, Effect, Option, PlatformError, Schema } from 'effect';
+import { HttpServerError } from 'effect/http';
+/** Configuration for a Node server that hosts a built Foldkit application. */
+export type ServeOptions = Readonly<{
+    /** The port Config that selects the listening port. */
+    port: Config.Config<number>;
+    /**
+     * The origin Config for requests that reach the Fetch handler. Use `None`
+     * to derive `http://localhost:<port>` from the resolved port.
+     */
+    origin: Config.Config<Option.Option<string>>;
+    /**
+     * The build manifest to read. Relative paths resolve from the process
+     * working directory. It defaults to `dist/server/foldkit.build.json`.
+     */
+    manifestPath?: string;
+    /**
+     * The deployed directory that corresponds to the Vite root. Provide it when
+     * the manifest's server directory is outside that root. Relative paths
+     * resolve from the process working directory.
+     */
+    rootDirectory?: string;
+    /**
+     * The root-relative Vite base path for client assets. It defaults to `/` and
+     * must end with `/`, such as `/app/`.
+     */
+    basePath?: string;
+}>;
+/**
+ * Starts a Node HTTP server for a built Foldkit application.
+ *
+ * The server reads `foldkit.build.json`, serves its client directory for GET
+ * and HEAD requests, and sends every other application request to the emitted
+ * Web Fetch handler. Interrupting the returned Effect closes the HTTP server.
+ */
+export declare const serve: (options: ServeOptions) => Effect.Effect<never, Config.ConfigError | Error | PlatformError.PlatformError | Schema.SchemaError | HttpServerError.ServeError, never>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,MAAM,EAIN,MAAM,EACN,aAAa,EAEb,MAAM,EACP,MAAM,QAAQ,CAAA;AACf,OAAO,EAGL,eAAe,EAIhB,MAAM,aAAa,CAAA;AAqCpB,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC3B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IAC5C;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAC,CAAA;AAmTF;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,YAAa,YAAY,4IACP,CAAA"}

package/dist/node.js

@@ -0,0 +1,204 @@
+import { Effect, FileSystem, Layer, Match, Option, PlatformError, Predicate, Schema, } from 'effect';
+import { HttpPlatform, HttpServer, HttpServerRequest, HttpServerResponse, HttpStaticServer, } from 'effect/http';
+import { Server } from 'foldkit/experimental';
+import { readFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { dirname, isAbsolute, posix, relative, resolve, sep } from 'node:path';
+import { Readable } from 'node:stream';
+import { ReadableStream } from 'node:stream/web';
+import { pathToFileURL } from 'node:url';
+import { NodeHttpPlatform, NodeHttpServer, NodeHttpServerRequest, NodeServices, } from '@effect/platform-node';
+const DEFAULT_MANIFEST_PATH = 'dist/server/foldkit.build.json';
+const FoldkitBuildManifest = Schema.Struct({
+    schemaVersion: Schema.Literals([1]),
+    client: Schema.String,
+    server: Schema.String,
+    serverEntry: Schema.String,
+    prerendered: Schema.Array(Schema.String),
+});
+const isFetchHandler = (value) => Predicate.hasProperty(value, 'fetch') && Predicate.isFunction(value.fetch);
+const isFetchModule = (value) => Predicate.hasProperty(value, 'default') && isFetchHandler(value.default);
+const isRouteNotFound = (error) => error.reason._tag === 'RouteNotFound';
+const hostSettledResponse = () => HttpServerResponse.setHeader(HttpServerResponse.empty({
+    status: Server.HOST_METHOD_ANSWERS.refusedStatus,
+}), 'allow', Server.HOST_METHOD_ANSWERS.allow);
+const basePathFrom = (basePath) => {
+    const resolvedBasePath = basePath ?? '/';
+    let url;
+    try {
+        url = new URL(resolvedBasePath, 'http://localhost');
+    }
+    catch {
+        throw new Error('basePath must be a root-relative path ending with `/`');
+    }
+    if (!resolvedBasePath.startsWith('/') ||
+        resolvedBasePath.startsWith('//') ||
+        resolvedBasePath.includes('\\') ||
+        !resolvedBasePath.endsWith('/') ||
+        url.origin !== 'http://localhost' ||
+        url.search !== '' ||
+        url.hash !== '') {
+        throw new Error('basePath must be a root-relative path ending with `/`');
+    }
+    return url.pathname;
+};
+const staticPathFor = (pathname, basePath) => {
+    if (basePath === '/') {
+        return pathname;
+    }
+    if (!pathname.startsWith(basePath)) {
+        return undefined;
+    }
+    return `/${pathname.slice(basePath.length)}`;
+};
+const decodeManifest = (content) => Effect.try({
+    try: () => JSON.parse(content),
+    catch: cause => new Error('foldkit.build.json is not valid JSON', { cause }),
+}).pipe(Effect.flatMap(Schema.decodeUnknownEffect(FoldkitBuildManifest)));
+const buildPaths = (manifestPath, manifest, rootDirectory) => {
+    const serverDirectory = dirname(manifestPath);
+    const normalizedServerDirectory = posix.normalize(manifest.server);
+    if (rootDirectory === undefined &&
+        (normalizedServerDirectory === '..' ||
+            normalizedServerDirectory.startsWith('../'))) {
+        throw new Error('foldkit.build.json describes a server directory outside the Vite root. Pass rootDirectory so @foldkit/node can locate the client output.');
+    }
+    const resolvedRootDirectory = rootDirectory === undefined
+        ? resolve(serverDirectory, relative(manifest.server, '.'))
+        : resolve(process.cwd(), rootDirectory);
+    const expectedServerDirectory = resolve(resolvedRootDirectory, manifest.server);
+    if (expectedServerDirectory !== serverDirectory) {
+        throw new Error(`rootDirectory resolves ${manifest.server} to ${expectedServerDirectory}, but the manifest is at ${serverDirectory}`);
+    }
+    return {
+        clientDirectory: resolve(resolvedRootDirectory, manifest.client),
+        fetchHandlerPath: resolve(serverDirectory, manifest.serverEntry),
+    };
+};
+const readBuildPaths = (manifestPath, rootDirectory) => Effect.tryPromise({
+    try: () => readFile(manifestPath, 'utf8'),
+    catch: cause => new Error(`could not read Foldkit build manifest at ${manifestPath}`, {
+        cause,
+    }),
+}).pipe(Effect.flatMap(decodeManifest), Effect.map(manifest => buildPaths(manifestPath, manifest, rootDirectory)));
+const loadFetchHandler = (fetchHandlerPath) => Effect.tryPromise({
+    try: () => import(pathToFileURL(fetchHandlerPath).href),
+    catch: cause => new Error(`could not load the Foldkit fetch handler at ${fetchHandlerPath}. Run \`vite build\` first.`, { cause }),
+}).pipe(Effect.flatMap(loaded => isFetchModule(loaded)
+    ? Effect.succeed(loaded.default)
+    : Effect.fail(new Error(`${fetchHandlerPath} must default-export a Web fetch handler`))));
+const fetchResponse = (app, request, requestUrl) => Effect.gen(function* () {
+    const signal = yield* Effect.abortSignal;
+    const webRequest = yield* HttpServerRequest.toWeb(request, { signal });
+    const response = yield* Effect.promise(() => app.fetch(new Request(requestUrl, webRequest)));
+    const headers = new Headers(response.headers);
+    const setCookieHeaders = headers.getSetCookie();
+    headers.delete('set-cookie');
+    if (setCookieHeaders.length > 0) {
+        NodeHttpServerRequest.toServerResponse(request).setHeader('set-cookie', setCookieHeaders);
+    }
+    const responseOptions = {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    };
+    if (response.body === null) {
+        return HttpServerResponse.empty(responseOptions);
+    }
+    const webReader = response.body.getReader();
+    const nodeBody = Readable.fromWeb(new ReadableStream({
+        async pull(controller) {
+            const chunk = await webReader.read();
+            if (chunk.done) {
+                controller.close();
+            }
+            else {
+                controller.enqueue(chunk.value);
+            }
+        },
+        cancel: reason => webReader.cancel(reason),
+    }));
+    const nodeResponse = NodeHttpServerRequest.toServerResponse(request);
+    const destroyBody = () => nodeBody.destroy();
+    nodeResponse.once('close', destroyBody);
+    nodeBody.once('close', () => nodeResponse.off('close', destroyBody));
+    if (signal.aborted) {
+        nodeBody.destroy();
+    }
+    return HttpServerResponse.raw(nodeBody, responseOptions);
+});
+const confinedStaticFiles = (clientDirectory) => Effect.gen(function* () {
+    const fileSystem = yield* FileSystem.FileSystem;
+    const httpPlatform = yield* HttpPlatform.HttpPlatform;
+    const root = yield* fileSystem.realPath(clientDirectory);
+    const confinedRealPath = (path) => Effect.flatMap(fileSystem.realPath(path), canonicalPath => {
+        const fromRoot = relative(root, canonicalPath);
+        const isContained = fromRoot === '' ||
+            (fromRoot !== '..' &&
+                !fromRoot.startsWith(`..${sep}`) &&
+                !isAbsolute(fromRoot));
+        if (isContained) {
+            return Effect.succeed(canonicalPath);
+        }
+        return Effect.fail(PlatformError.systemError({
+            _tag: 'NotFound',
+            module: 'FileSystem',
+            method: 'realPath',
+            pathOrDescriptor: path,
+        }));
+    });
+    const confinedFileSystem = FileSystem.FileSystem.of({
+        ...fileSystem,
+        stat: path => Effect.flatMap(confinedRealPath(path), fileSystem.stat),
+    });
+    const confinedPlatform = HttpPlatform.HttpPlatform.of({
+        ...httpPlatform,
+        fileResponse: (path, options) => Effect.flatMap(confinedRealPath(path), canonicalPath => httpPlatform.fileResponse(canonicalPath, options)),
+    });
+    return yield* HttpStaticServer.make({ root, index: undefined }).pipe(Effect.provideService(FileSystem.FileSystem, confinedFileSystem), Effect.provideService(HttpPlatform.HttpPlatform, confinedPlatform));
+});
+const makeHandler = (options) => Effect.gen(function* () {
+    const port = yield* options.port;
+    const origin = Option.getOrElse(yield* options.origin, () => `http://localhost:${globalThis.String(port)}`);
+    const manifestPath = resolve(process.cwd(), options.manifestPath ?? DEFAULT_MANIFEST_PATH);
+    const paths = yield* readBuildPaths(manifestPath, options.rootDirectory);
+    const app = yield* loadFetchHandler(paths.fetchHandlerPath);
+    const basePath = basePathFrom(options.basePath);
+    const staticFiles = yield* confinedStaticFiles(paths.clientDirectory);
+    return HttpServerRequest.HttpServerRequest.use(request => {
+        const requestUrl = Server.resolveRequestUrl(request.url, origin);
+        if (requestUrl === undefined) {
+            return Effect.succeed(HttpServerResponse.empty({ status: 400 }));
+        }
+        const resolved = new URL(requestUrl);
+        const fetchRequest = request.modify({
+            url: `${resolved.pathname}${resolved.search}`,
+        });
+        const staticPath = staticPathFor(resolved.pathname, basePath);
+        const staticRequest = staticPath === undefined
+            ? undefined
+            : request.modify({ url: `${staticPath}${resolved.search}` });
+        const response = Match.value(fetchRequest.method).pipe(Match.whenOr('GET', 'HEAD', () => {
+            if (staticRequest === undefined ||
+                Server.resolvesToIndexHtml(staticRequest.url)) {
+                return fetchResponse(app, fetchRequest, requestUrl);
+            }
+            return staticFiles.pipe(Effect.catchIf(isRouteNotFound, () => fetchResponse(app, fetchRequest, requestUrl)));
+        }), Match.orElse(() => {
+            if (Server.isHostSettledMethod(fetchRequest.method)) {
+                return Effect.succeed(hostSettledResponse());
+            }
+            return fetchResponse(app, fetchRequest, requestUrl);
+        }));
+        return Effect.provideService(response, HttpServerRequest.HttpServerRequest, staticRequest ?? fetchRequest);
+    }).pipe(Effect.interruptible);
+});
+const serverLayer = (options) => Layer.unwrap(Effect.map(makeHandler(options), handler => HttpServer.serve(handler))).pipe(HttpServer.withLogAddress, Layer.provide(NodeHttpServer.layerConfig(createServer, { port: options.port })), Layer.provide(NodeHttpPlatform.layer), Layer.provide(NodeServices.layer));
+/**
+ * Starts a Node HTTP server for a built Foldkit application.
+ *
+ * The server reads `foldkit.build.json`, serves its client directory for GET
+ * and HEAD requests, and sends every other application request to the emitted
+ * Web Fetch handler. Interrupting the returned Effect closes the HTTP server.
+ */
+export const serve = (options) => Layer.launch(serverLayer(options));

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@foldkit/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Node.js host adapter for Foldkit server-rendered applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@effect/platform-node": "4.0.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0",
+    "foldkit": ">=0.165.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.4.0",
+    "effect": "4.0.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "foldkit": "0.166.0"
+  },
+  "keywords": [
+    "foldkit",
+    "node",
+    "server-rendering",
+    "ssr"
+  ],
+  "author": "Devin Jameson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/foldkit/foldkit.git",
+    "directory": "packages/node"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist *.tsbuildinfo",
+    "build": "pnpm run clean && tsc -b tsconfig.build.json",
+    "watch": "tsc -b tsconfig.build.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }