@vyriy/static 0.5.2

package/AGENTS.md

@@ -0,0 +1,102 @@
+# Project Agent Guide
+
+This repository follows a calm engineering style: changes should be explicit, reusable, typed, documented, tested, and easy to reason about.
+
+Use this guide as the default behavior for AI agents and contributors working in this repository. Prefer local package conventions when they are more specific than this document.
+
+## Core Principles
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package and project boundaries explicit.
+- Avoid project-specific coupling in reusable code.
+- Extract only proven reusable behavior.
+- Keep public APIs small, typed, documented, and stable.
+- Prefer SSR-friendly and SSG-friendly code paths when working with frontend or shared code.
+- Keep integrations replaceable and avoid hard coupling to a CMS, framework, vendor, or runtime host.
+- Prefer infrastructure assumptions that are easy to deploy, observe, and replace.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.
+
+## File Shape
+
+- Prefer one exported runtime method, component, helper, or class per production file when it stays readable.
+- Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
+- Use focused folders when behavior naturally splits into several related files.
+- Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Use relative import and export specifiers that match the package module style.
+- Use `.js` relative specifiers in TypeScript source for ESM/NodeNext packages.
+- Add `types.ts` when public shared types are part of the package contract.
+- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+
+## Public Surface
+
+- Every new public export must be re-exported from the package or module public entry point.
+- Add or update public-surface tests when exports change.
+- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
+- Avoid exporting internal helpers only to make tests easier.
+- Do not hand-maintain package `exports` maps unless the project has a real custom publishing need.
+
+## Tests
+
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- Keep tests deterministic.
+- Avoid real network, filesystem, timers, browser, or cloud dependencies unless the behavior specifically requires them.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing behavior.
+
+Example validation commands:
+
+```bash
+yarn test
+```
+
+For workspaces, prefer the project convention, for example:
+
+```bash
+yarn workspace <package-name> test
+```
+
+For Jest-based packages, focused validation may look like:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# <package>`.
+- Document real public exports, supported options, and examples that actually work.
+- Update docs when public behavior changes.
+- Keep generated docs wrappers, such as `doc.mdx`, aligned with the README when the project uses them.
+- For component packages, include visual documentation or stories for supported states and common usage.
+
+## Components
+
+- Prefer lightweight React components with TypeScript when working in React packages.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and predictable ergonomics.
+- Put each public component in its own file with a matching test.
+- Add stories or examples when a component has visual states, variants, or interaction states.
+- Keep styling explicit and reusable. Avoid hidden theme assumptions unless they are part of the package contract.
+
+## Change Discipline
+
+- Keep changes scoped to the requested behavior.
+- Avoid unrelated refactors and metadata churn.
+- Sync implementation, tests, docs, examples, and public re-exports together.
+- Do not introduce new dependencies unless they clearly reduce complexity or are already part of the project direction.
+- Prefer small, reviewable changes over broad rewrites.
+- Preserve existing conventions unless there is a clear reason to change them.
+
+## Before Finishing
+
+Check that the change is complete:
+
+- Public exports are updated.
+- Public-surface tests are updated when exports change.
+- Matching unit tests exist for new behavior.
+- README examples still match the real API.
+- Visual docs, stories, or examples are updated for visible component behavior.
+- TypeScript imports follow the package module style.
+- No unrelated files, formatting churn, or generated artifacts were changed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vyriy contributors
+
+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

@@ -0,0 +1,49 @@
+# @vyriy/static
+
+Static file and SPA serving CLI with reusable Lambda-style handlers and router helpers.
+
+## CLI
+
+Install globally:
+
+```bash
+npm install --global @vyriy/static
+```
+
+Serve a static directory:
+
+```bash
+vyriy-static
+vyriy-static dist
+vyriy-static build
+vyriy-static public
+```
+
+When no directory is provided, the server tries `dist`, `build`, `public`, `out`, and then the current directory.
+
+## API
+
+Install as a project dependency:
+
+```bash
+npm install @vyriy/static
+```
+
+Use handlers and router helpers from code:
+
+```ts
+import { staticServer, useSpa, useStatic, withSpa, withStatic } from '@vyriy/static';
+import { createRouter } from '@vyriy/router';
+
+export const assets = useStatic();
+export const app = useSpa({ directory: 'dist', index: 'index.html' });
+
+export const router = withStatic(createRouter(), { directory: 'dist' }).static('/');
+export const spaRouter = withSpa(createRouter(), 'dist');
+
+const code = await staticServer({ directory: 'dist' });
+```
+
+`useStatic({ directory, index, error })` serves files from a directory. `useSpa(options)` serves static files and falls back to the configured index file for missing `GET` and `HEAD` paths. `withStatic(router, options).static(path)` adds prefix-based static mounts. `withSpa(router, directoryOrOptions)` adds static-first SPA fallback behavior.
+
+Defaults are `directory: 'dist'`, `index: 'index.html'`, and `error: '404.html'`.

package/bin/vyriy-static.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { staticServer } from '../index.js';
+const directory = process.argv.find((arg, index) => index > 1 && !arg.startsWith('-')) ?? '.';
+void staticServer({ directory }).then((code) => {
+    process.exitCode = code;
+});

package/index.d.ts

@@ -0,0 +1,6 @@
+export * from './server.js';
+export * from './use-static.js';
+export * from './use-spa.js';
+export * from './with-static.js';
+export * from './with-spa.js';
+export type * from './types.js';

package/index.js

@@ -0,0 +1,5 @@
+export * from './server.js';
+export * from './use-static.js';
+export * from './use-spa.js';
+export * from './with-static.js';
+export * from './with-spa.js';

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@vyriy/static",
+  "version": "0.5.2",
+  "description": "Static file and SPA serving helpers for Vyriy servers.",
+  "type": "module",
+  "bin": "./bin/vyriy-static.js",
+  "dependencies": {
+    "@vyriy/handler": "0.5.2",
+    "@vyriy/router": "0.5.2",
+    "@vyriy/server": "0.5.2"
+  },
+  "agents": "./AGENTS.md",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evheniy/vyriy",
+    "directory": "packages/static"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./index": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./index.js": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "import": "./server.js",
+      "default": "./server.js"
+    },
+    "./server.js": {
+      "types": "./server.d.ts",
+      "import": "./server.js",
+      "default": "./server.js"
+    },
+    "./use-spa": {
+      "types": "./use-spa.d.ts",
+      "import": "./use-spa.js",
+      "default": "./use-spa.js"
+    },
+    "./use-spa.js": {
+      "types": "./use-spa.d.ts",
+      "import": "./use-spa.js",
+      "default": "./use-spa.js"
+    },
+    "./use-static": {
+      "types": "./use-static.d.ts",
+      "import": "./use-static.js",
+      "default": "./use-static.js"
+    },
+    "./use-static.js": {
+      "types": "./use-static.d.ts",
+      "import": "./use-static.js",
+      "default": "./use-static.js"
+    },
+    "./with-spa": {
+      "types": "./with-spa.d.ts",
+      "import": "./with-spa.js",
+      "default": "./with-spa.js"
+    },
+    "./with-spa.js": {
+      "types": "./with-spa.d.ts",
+      "import": "./with-spa.js",
+      "default": "./with-spa.js"
+    },
+    "./with-static": {
+      "types": "./with-static.d.ts",
+      "import": "./with-static.js",
+      "default": "./with-static.js"
+    },
+    "./with-static.js": {
+      "types": "./with-static.d.ts",
+      "import": "./with-static.js",
+      "default": "./with-static.js"
+    }
+  }
+}

package/server.d.ts

@@ -0,0 +1,2 @@
+import type { StaticServer } from './types.js';
+export declare const staticServer: StaticServer;

package/server.js

@@ -0,0 +1,15 @@
+import { existsSync } from 'node:fs';
+import { server } from '@vyriy/server';
+import { useStatic } from './use-static.js';
+const DIRECTORIES = [
+    'dist',
+    'build',
+    'public',
+    'out',
+];
+const resolveDirectory = (directory) => directory ?? DIRECTORIES.find((candidate) => existsSync(candidate)) ?? '.';
+const createStaticHandler = useStatic;
+export const staticServer = async (options = {}) => {
+    await Promise.resolve(server(createStaticHandler({ ...options, directory: resolveDirectory(options.directory) })));
+    return 0;
+};

package/types.d.ts

@@ -0,0 +1,15 @@
+import type { ApiEvent, ApiResult, Handler } from '@vyriy/handler';
+import type { RouterApi } from '@vyriy/router';
+export type StaticServerOptions = StaticOptions;
+export type StaticOptions = {
+    readonly directory?: string;
+    readonly index?: string;
+    readonly error?: string;
+};
+export type StaticHandler = Handler<ApiEvent, ApiResult>;
+export type StaticServer = (options?: StaticServerOptions) => Promise<number>;
+export type StaticRouterApi = Omit<RouterApi, 'delete' | 'fallback' | 'get' | 'patch' | 'post' | 'put'> & {
+    static(path: string): StaticRouterApi;
+} & {
+    [Method in Extract<keyof RouterApi, 'delete' | 'fallback' | 'get' | 'patch' | 'post' | 'put'>]: (...args: Parameters<RouterApi[Method]>) => StaticRouterApi;
+};

package/use-spa.d.ts

@@ -0,0 +1,2 @@
+import type { StaticHandler, StaticOptions } from './types.js';
+export declare const useSpa: (options?: StaticOptions) => StaticHandler;

package/use-spa.js

@@ -0,0 +1,17 @@
+import { useStatic } from './use-static.js';
+const createStaticHandler = useStatic;
+const isSpaFallbackMethod = (method) => method === 'GET' || method === 'HEAD';
+export const useSpa = (options = {}) => {
+    const handler = createStaticHandler(options);
+    const index = options.index ?? 'index.html';
+    return async (event, context) => {
+        const result = await handler(event, context);
+        if (result.statusCode !== 404 || !isSpaFallbackMethod(event.httpMethod)) {
+            return result;
+        }
+        return handler({
+            ...event,
+            path: `/${index}`,
+        }, context);
+    };
+};

package/use-static.d.ts

@@ -0,0 +1,2 @@
+import type { StaticHandler, StaticOptions } from './types.js';
+export declare const useStatic: (options?: StaticOptions) => StaticHandler;

package/use-static.js

@@ -0,0 +1,170 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+const DEFAULT_DIRECTORY = 'dist';
+const DEFAULT_INDEX = 'index.html';
+const DEFAULT_ERROR = '404.html';
+const NOT_FOUND_BODY = JSON.stringify({ message: 'Not Found' });
+const METHOD_NOT_ALLOWED_BODY = JSON.stringify({ message: 'Method Not Allowed' });
+const CONTENT_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.csv': 'text/csv; charset=utf-8',
+    '.gif': 'image/gif',
+    '.html': 'text/html; charset=utf-8',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.xml': 'application/xml; charset=utf-8',
+};
+const TEXT_TYPES = new Set([
+    '.css',
+    '.csv',
+    '.html',
+    '.js',
+    '.json',
+    '.map',
+    '.mjs',
+    '.svg',
+    '.txt',
+    '.xml',
+]);
+const getContentType = (extension) => CONTENT_TYPES[extension.toLowerCase()] ?? 'application/octet-stream';
+const isTextExtension = (extension) => TEXT_TYPES.has(extension.toLowerCase());
+const notFound = (body = NOT_FOUND_BODY, headers) => ({
+    statusCode: 404,
+    body,
+    headers: headers ?? {
+        'content-type': 'application/json; charset=utf-8',
+    },
+});
+const methodNotAllowed = () => ({
+    statusCode: 405,
+    body: METHOD_NOT_ALLOWED_BODY,
+    headers: {
+        allow: 'GET, HEAD',
+        'content-type': 'application/json; charset=utf-8',
+    },
+});
+const isStaticMethod = (method) => method === 'GET' || method === 'HEAD';
+const isInsideDirectory = (directory, candidate) => {
+    const relative = path.relative(directory, candidate);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+const normalizeOptions = ({ directory = DEFAULT_DIRECTORY, error = DEFAULT_ERROR, index = DEFAULT_INDEX, }) => ({
+    directory,
+    error,
+    index,
+});
+const createFileResult = async (realFilePath, fileSize, method) => {
+    const extension = path.extname(realFilePath);
+    const isText = isTextExtension(extension);
+    if (method === 'HEAD') {
+        return {
+            statusCode: 200,
+            body: '',
+            headers: {
+                'content-length': String(fileSize),
+                'content-type': getContentType(extension),
+            },
+            isBase64Encoded: false,
+        };
+    }
+    const content = await readFile(realFilePath);
+    return {
+        statusCode: 200,
+        body: content.toString(isText ? 'utf8' : 'base64'),
+        headers: {
+            'content-length': String(fileSize),
+            'content-type': getContentType(extension),
+        },
+        isBase64Encoded: !isText,
+    };
+};
+const readStaticFile = async (root, filePath, method) => {
+    if (!isInsideDirectory(root, filePath)) {
+        return undefined;
+    }
+    const realFilePath = await realpath(filePath);
+    if (!isInsideDirectory(root, realFilePath)) {
+        return undefined;
+    }
+    const fileStat = await stat(realFilePath);
+    if (!fileStat.isFile()) {
+        return undefined;
+    }
+    return createFileResult(realFilePath, fileStat.size, method);
+};
+const readErrorFile = async (root, error, method) => {
+    try {
+        const result = await readStaticFile(root, path.resolve(root, error), method);
+        if (!result) {
+            return notFound();
+        }
+        return {
+            ...result,
+            statusCode: 404,
+        };
+    }
+    catch {
+        return notFound();
+    }
+};
+export const useStatic = (options = {}) => {
+    const { directory, error, index } = normalizeOptions(options);
+    let root;
+    const getRoot = () => (root ??= realpath(directory));
+    return async (event) => {
+        if (!isStaticMethod(event.httpMethod)) {
+            return methodNotAllowed();
+        }
+        let decodedPath;
+        try {
+            decodedPath = decodeURIComponent(event.path);
+        }
+        catch {
+            return notFound();
+        }
+        let staticRoot;
+        try {
+            staticRoot = await getRoot();
+        }
+        catch {
+            return notFound();
+        }
+        const requestedPath = decodedPath.replace(/^\/+/, '') || index;
+        const candidate = path.resolve(staticRoot, requestedPath);
+        if (!isInsideDirectory(staticRoot, candidate)) {
+            return readErrorFile(staticRoot, error, event.httpMethod);
+        }
+        let filePath = candidate;
+        try {
+            const fileStat = await stat(filePath);
+            if (fileStat.isDirectory()) {
+                filePath = path.join(filePath, index);
+            }
+        }
+        catch {
+            return readErrorFile(staticRoot, error, event.httpMethod);
+        }
+        if (!isInsideDirectory(staticRoot, filePath)) {
+            return readErrorFile(staticRoot, error, event.httpMethod);
+        }
+        try {
+            const result = await readStaticFile(staticRoot, filePath, event.httpMethod);
+            return result ?? readErrorFile(staticRoot, error, event.httpMethod);
+        }
+        catch {
+            return readErrorFile(staticRoot, error, event.httpMethod);
+        }
+    };
+};

package/with-spa.d.ts

@@ -0,0 +1,3 @@
+import type { StaticOptions } from './types.js';
+import type { RouterApi } from '@vyriy/router';
+export declare const withSpa: (router: RouterApi, directoryOrOptions?: StaticOptions | string) => RouterApi;

package/with-spa.js

@@ -0,0 +1,41 @@
+import { useSpa } from './use-spa.js';
+const createSpaHandler = useSpa;
+const isStaticMethod = (method) => method === 'GET' || method === 'HEAD';
+export const withSpa = (router, directoryOrOptions = {}) => {
+    const options = typeof directoryOrOptions === 'string' ? { directory: directoryOrOptions } : directoryOrOptions;
+    const spaHandler = createSpaHandler(options);
+    const api = {
+        delete(path, handler) {
+            router.delete(path, handler);
+            return api;
+        },
+        fallback(handler) {
+            router.fallback(handler);
+            return api;
+        },
+        get(path, handler) {
+            router.get(path, handler);
+            return api;
+        },
+        patch(path, handler) {
+            router.patch(path, handler);
+            return api;
+        },
+        post(path, handler) {
+            router.post(path, handler);
+            return api;
+        },
+        put(path, handler) {
+            router.put(path, handler);
+            return api;
+        },
+        route: async (event) => {
+            const result = await router.route(event);
+            if (result.statusCode !== 404 || !isStaticMethod(event.httpMethod)) {
+                return result;
+            }
+            return spaHandler(event, {});
+        },
+    };
+    return api;
+};

package/with-static.d.ts

@@ -0,0 +1,3 @@
+import type { StaticOptions, StaticRouterApi } from './types.js';
+import type { RouterApi } from '@vyriy/router';
+export declare const withStatic: (router: RouterApi, options?: StaticOptions) => StaticRouterApi;

package/with-static.js

@@ -0,0 +1,72 @@
+import { useStatic } from './use-static.js';
+const normalizeMount = (path) => {
+    const mount = path.startsWith('/') ? path : `/${path}`;
+    return mount === '/' ? mount : mount.replace(/\/+$/, '');
+};
+const toStaticPath = (mount, requestPath) => {
+    if (mount === '/') {
+        return requestPath;
+    }
+    if (requestPath === mount) {
+        return '/';
+    }
+    if (requestPath.startsWith(`${mount}/`)) {
+        return requestPath.slice(mount.length);
+    }
+    return undefined;
+};
+const isStaticMethod = (method) => method === 'GET' || method === 'HEAD';
+export const withStatic = (router, options = {}) => {
+    const mounts = [];
+    const createStaticHandler = useStatic;
+    const staticHandler = createStaticHandler(options);
+    const api = {
+        delete(path, handler) {
+            router.delete(path, handler);
+            return api;
+        },
+        fallback(handler) {
+            router.fallback(handler);
+            return api;
+        },
+        get(path, handler) {
+            router.get(path, handler);
+            return api;
+        },
+        patch(path, handler) {
+            router.patch(path, handler);
+            return api;
+        },
+        post(path, handler) {
+            router.post(path, handler);
+            return api;
+        },
+        put(path, handler) {
+            router.put(path, handler);
+            return api;
+        },
+        route: async (event) => {
+            const result = await router.route(event);
+            if (result.statusCode !== 404 || !isStaticMethod(event.httpMethod)) {
+                return result;
+            }
+            for (const mount of mounts) {
+                const staticPath = toStaticPath(mount, event.path);
+                if (staticPath === undefined) {
+                    continue;
+                }
+                const staticResult = await staticHandler({
+                    ...event,
+                    path: staticPath,
+                }, {});
+                return staticResult;
+            }
+            return result;
+        },
+        static(path) {
+            mounts.push(normalizeMount(path));
+            return api;
+        },
+    };
+    return api;
+};