@sveltesentio/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0](https://github.com/golusoris/sveltesentio/compare/core-v0.0.1...core-v0.1.0) (2026-06-14)
+
+
+### Features
+
+* land foundation packages and repair CI gate ([#41](https://github.com/golusoris/sveltesentio/issues/41)) ([7557620](https://github.com/golusoris/sveltesentio/commit/75576200e324cd4c55f48571a6532540c1f6eb16))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lusoris
+
+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,30 @@
+# @sveltesentio/core
+
+> Core utilities — rune helpers, type-safe fetch, CSP hooks, error boundaries
+
+Part of the [sveltesentio](https://github.com/golusoris/sveltesentio) composable SvelteKit framework.
+
+## Status
+
+✅ v0.1.0 — `./env`, `./problem` (RFC 9457), `./http`, `./id` (UUIDv7), `./csp`,
+`./vite`, and clock injection have shipped.
+
+## Requirements
+
+**Zod v4 only.** `@sveltesentio/core` schemas require `zod@^4`
+([ADR-0001](../../docs/adr/0001-zod-v4-floor.md)); **v3 is unsupported** — a v3 schema
+breaks `createEnv` error reporting (`z.treeifyError`) and the `@sveltesentio/forms`
+`zod4` adapter. Downstream apps on `zod@^3` must upgrade first; follow the
+[Zod v3 → v4 migration guide](../../docs/migrations/zod-v3-to-v4.md).
+
+## Installation
+
+```bash
+pnpm add @sveltesentio/core
+```
+
+See the [monorepo README](../../README.md) and [`docs/`](../../docs/) for design principles and usage.
+
+## License
+
+MIT © lusoris

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@sveltesentio/core",
+  "version": "0.1.0",
+  "description": "Vite plugin, env schema, error types, id/clock utils — sveltesentio core",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./clock": {
+      "import": "./src/clock.ts",
+      "types": "./src/clock.ts"
+    },
+    "./env": {
+      "import": "./src/env.ts",
+      "types": "./src/env.ts"
+    },
+    "./id": {
+      "import": "./src/id.ts",
+      "types": "./src/id.ts"
+    },
+    "./problem": {
+      "import": "./src/problem.ts",
+      "types": "./src/problem.ts"
+    },
+    "./http": {
+      "import": "./src/http.ts",
+      "types": "./src/http.ts"
+    },
+    "./csp": {
+      "import": "./src/csp.ts",
+      "types": "./src/csp.ts"
+    },
+    "./vite": {
+      "import": "./src/vite.ts",
+      "types": "./src/vite.ts"
+    }
+  },
+  "peerDependencies": {
+    "@sveltejs/kit": ">=2.0.0",
+    "esm-env": ">=1.0.0",
+    "openapi-fetch": ">=0.17.0",
+    "svelte": ">=5.0.0",
+    "uuid": ">=13.0.0",
+    "vite": ">=8.0.0",
+    "zod": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openapi-fetch": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@sveltejs/kit": "^2.0.0",
+    "@types/node": "^24.0.0",
+    "esm-env": "^1.2.2",
+    "openapi-fetch": "^0.17.0",
+    "svelte": "^5.55.4",
+    "typescript": "^6.0.3",
+    "uuid": "^13.0.0",
+    "vitest": "^4.1.4",
+    "zod": "^4.3.6"
+  },
+  "keywords": [
+    "sveltesentio",
+    "sveltekit",
+    "vite-plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/clock.ts

@@ -0,0 +1,64 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { getContext, hasContext, setContext } from 'svelte';
+import { BROWSER } from 'esm-env';
+import type { Handle } from '@sveltejs/kit';
+
+export interface Clock {
+	now(): Date;
+	monotonic(): number;
+}
+
+export const systemClock: Clock = {
+	now: () => new Date(),
+	monotonic: () =>
+		BROWSER ? performance.now() : Number(process.hrtime.bigint()) / 1e6,
+};
+
+const CLOCK_KEY = Symbol.for('sveltesentio.clock');
+
+const als: AsyncLocalStorage<Clock> | null = BROWSER
+	? null
+	: new AsyncLocalStorage<Clock>({ name: 'clock', defaultValue: systemClock });
+
+let clientClock: Clock = systemClock;
+
+export function setClock(clock: Clock): void {
+	setContext(CLOCK_KEY, clock);
+	if (BROWSER) clientClock = clock;
+}
+
+export function useClock(): Clock {
+	if (hasContext(CLOCK_KEY)) return getContext<Clock>(CLOCK_KEY);
+	if (BROWSER) return clientClock;
+	return als?.getStore() ?? systemClock;
+}
+
+export function getClock(): Clock {
+	if (BROWSER) return clientClock;
+	return als?.getStore() ?? systemClock;
+}
+
+export function withClock(clock: Clock): Handle {
+	return ({ event, resolve }) => {
+		(event.locals as { clock?: Clock }).clock = clock;
+		if (!als) return resolve(event);
+		return als.run(clock, () => resolve(event));
+	};
+}
+
+export function createHydrationClock(serverNow: Date): Clock {
+	const serverMs = serverNow.getTime();
+	const monotonicAtHydration = BROWSER ? performance.now() : 0;
+	let firstRead = true;
+	return {
+		now: () => {
+			if (firstRead) {
+				firstRead = false;
+				return new Date(serverMs);
+			}
+			const delta = BROWSER ? performance.now() - monotonicAtHydration : 0;
+			return new Date(serverMs + delta);
+		},
+		monotonic: () => (BROWSER ? performance.now() : 0),
+	};
+}

package/src/csp.ts

@@ -0,0 +1,93 @@
+import { newIdV4 } from './id.js';
+
+export type CspSource = string;
+
+export interface CspDirectives {
+	'default-src'?: readonly CspSource[];
+	'script-src'?: readonly CspSource[];
+	'script-src-elem'?: readonly CspSource[];
+	'style-src'?: readonly CspSource[];
+	'style-src-elem'?: readonly CspSource[];
+	'img-src'?: readonly CspSource[];
+	'font-src'?: readonly CspSource[];
+	'connect-src'?: readonly CspSource[];
+	'media-src'?: readonly CspSource[];
+	'frame-src'?: readonly CspSource[];
+	'worker-src'?: readonly CspSource[];
+	'manifest-src'?: readonly CspSource[];
+	'object-src'?: readonly CspSource[];
+	'base-uri'?: readonly CspSource[];
+	'form-action'?: readonly CspSource[];
+	'frame-ancestors'?: readonly CspSource[];
+	'report-uri'?: readonly string[];
+	'report-to'?: string;
+	'upgrade-insecure-requests'?: boolean;
+}
+
+export function createNonce(): string {
+	return newIdV4();
+}
+
+export function nonceSource(nonce: string): CspSource {
+	return `'nonce-${nonce}'`;
+}
+
+export function hashSource(algo: 'sha256' | 'sha384' | 'sha512', base64: string): CspSource {
+	return `'${algo}-${base64}'`;
+}
+
+export const STRICT_DYNAMIC: CspSource = "'strict-dynamic'";
+export const SELF: CspSource = "'self'";
+export const NONE: CspSource = "'none'";
+
+export interface StrictCspOptions {
+	nonce: string;
+	reportUri?: string;
+	connectSrc?: readonly CspSource[];
+	imgSrc?: readonly CspSource[];
+	fontSrc?: readonly CspSource[];
+	styleSrc?: readonly CspSource[];
+	mediaSrc?: readonly CspSource[];
+	extra?: CspDirectives;
+}
+
+export function strictCsp(options: StrictCspOptions): CspDirectives {
+	const { nonce, reportUri, connectSrc, imgSrc, fontSrc, styleSrc, mediaSrc, extra } = options;
+	return {
+		'default-src': [SELF],
+		'script-src': [STRICT_DYNAMIC, nonceSource(nonce)],
+		'style-src': styleSrc ?? [SELF, nonceSource(nonce)],
+		'img-src': imgSrc ?? [SELF, 'data:'],
+		'font-src': fontSrc ?? [SELF],
+		'connect-src': connectSrc ?? [SELF],
+		'media-src': mediaSrc ?? [SELF],
+		'object-src': [NONE],
+		'base-uri': [NONE],
+		'frame-ancestors': [NONE],
+		'form-action': [SELF],
+		'upgrade-insecure-requests': true,
+		...(reportUri ? { 'report-uri': [reportUri] } : {}),
+		...extra,
+	};
+}
+
+export function serialiseCsp(directives: CspDirectives): string {
+	const parts: string[] = [];
+	for (const [name, value] of Object.entries(directives) as Array<[
+		keyof CspDirectives,
+		CspDirectives[keyof CspDirectives],
+	]>) {
+		if (value === undefined || value === false) continue;
+		if (value === true) {
+			parts.push(name);
+			continue;
+		}
+		if (typeof value === 'string') {
+			parts.push(`${name} ${value}`);
+			continue;
+		}
+		if (value.length === 0) continue;
+		parts.push(`${name} ${value.join(' ')}`);
+	}
+	return parts.join('; ');
+}

package/src/env.ts

@@ -0,0 +1,69 @@
+import type { ZodObject, ZodRawShape, infer as ZodInfer } from 'zod';
+import { z } from 'zod';
+
+export class EnvValidationError extends Error {
+	readonly tree: unknown;
+	constructor(kind: 'server' | 'public', tree: unknown) {
+		super(`Invalid ${kind} environment. ${summarise(tree)}`);
+		this.name = 'EnvValidationError';
+		this.tree = tree;
+	}
+}
+
+export interface EnvOptions<
+	TServer extends ZodRawShape,
+	TPublic extends ZodRawShape,
+> {
+	server: ZodObject<TServer>;
+	publicEnv: ZodObject<TPublic>;
+	runtimeEnv: Record<string, string | undefined>;
+	skipValidation?: boolean;
+}
+
+export type Env<
+	TServer extends ZodRawShape,
+	TPublic extends ZodRawShape,
+> = Readonly<ZodInfer<ZodObject<TServer>> & ZodInfer<ZodObject<TPublic>>>;
+
+export function createEnv<
+	TServer extends ZodRawShape,
+	TPublic extends ZodRawShape,
+>(options: EnvOptions<TServer, TPublic>): Env<TServer, TPublic> {
+	const { server, publicEnv, runtimeEnv, skipValidation = false } = options;
+
+	if (skipValidation) {
+		return runtimeEnv as unknown as Env<TServer, TPublic>;
+	}
+
+	const serverResult = server.safeParse(runtimeEnv);
+	if (!serverResult.success) {
+		throw new EnvValidationError('server', z.treeifyError(serverResult.error));
+	}
+
+	const publicResult = publicEnv.safeParse(runtimeEnv);
+	if (!publicResult.success) {
+		throw new EnvValidationError('public', z.treeifyError(publicResult.error));
+	}
+
+	return Object.freeze({
+		...serverResult.data,
+		...publicResult.data,
+	});
+}
+
+export function requireEnv(name: string, value: string | undefined): string {
+	if (value === undefined || value === '') {
+		throw new EnvValidationError('server', {
+			errors: [`Required environment variable "${name}" is not set`],
+		});
+	}
+	return value;
+}
+
+function summarise(tree: unknown): string {
+	try {
+		return JSON.stringify(tree, null, 2);
+	} catch {
+		return '[unserialisable tree]';
+	}
+}

package/src/http.ts

@@ -0,0 +1,49 @@
+import type { Middleware } from 'openapi-fetch';
+import {
+	ProblemError,
+	isProblemResponse,
+	parseProblem,
+	problemFromDocument,
+} from './problem.js';
+
+export { ProblemError } from './problem.js';
+export type { ProblemDocument, ProblemErrorInit, InvalidParam } from './problem.js';
+
+export interface ProblemMiddlewareOptions {
+	onProblem?: (error: ProblemError) => void;
+}
+
+export function problemMiddleware(options: ProblemMiddlewareOptions = {}): Middleware {
+	return {
+		onResponse: async ({ response }) => {
+			if (response.ok) return undefined;
+			if (!isProblemResponse(response)) return undefined;
+
+			const clone = response.clone();
+			let body: unknown;
+			try {
+				body = await clone.json();
+			} catch (cause) {
+				throw new ProblemError({
+					type: 'about:blank',
+					title: response.statusText || 'Problem parse failure',
+					status: response.status,
+					cause,
+				});
+			}
+
+			const parsed = parseProblem(body);
+			const error = parsed
+				? problemFromDocument(parsed)
+				: new ProblemError({
+						type: 'about:blank',
+						title: response.statusText || 'Unknown problem',
+						status: response.status,
+						detail: typeof body === 'string' ? body : undefined,
+					});
+
+			options.onProblem?.(error);
+			throw error;
+		},
+	};
+}

package/src/id.ts

@@ -0,0 +1,30 @@
+import { v4 as uuidv4, v7 as uuidv7, validate, version } from 'uuid';
+
+export type Id<Brand extends string = string> = string & { readonly __brand: Brand };
+
+export function newId(): string {
+	return uuidv7();
+}
+
+export function newIdV4(): string {
+	return uuidv4();
+}
+
+export function isId(value: unknown): value is string {
+	return typeof value === 'string' && validate(value) && version(value) === 7;
+}
+
+export function isIdV4(value: unknown): value is string {
+	return typeof value === 'string' && validate(value) && version(value) === 4;
+}
+
+export function brandId<Brand extends string>(value: string): Id<Brand> {
+	if (!isId(value)) throw new TypeError(`Not a valid UUIDv7: ${value}`);
+	return value as Id<Brand>;
+}
+
+export function idToTimestamp(id: string): number {
+	if (!isId(id)) throw new TypeError(`Not a valid UUIDv7: ${id}`);
+	const hex = id.replace(/-/g, '').slice(0, 12);
+	return Number.parseInt(hex, 16);
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+export type { Clock } from './clock.js';
+export {
+	createHydrationClock,
+	getClock,
+	setClock,
+	systemClock,
+	useClock,
+	withClock,
+} from './clock.js';
+
+export type { Env, EnvOptions } from './env.js';
+export { EnvValidationError, createEnv, requireEnv } from './env.js';
+
+export type { Id } from './id.js';
+export { brandId, idToTimestamp, isId, isIdV4, newId, newIdV4 } from './id.js';
+
+export type {
+	InvalidParam,
+	ProblemDocument,
+	ProblemErrorInit,
+} from './problem.js';
+export {
+	ProblemError,
+	isProblemResponse,
+	parseProblem,
+	problemFromDocument,
+	problemFromResponse,
+} from './problem.js';
+
+export type { CspDirectives, CspSource, StrictCspOptions } from './csp.js';
+export {
+	NONE,
+	SELF,
+	STRICT_DYNAMIC,
+	createNonce,
+	hashSource,
+	nonceSource,
+	serialiseCsp,
+	strictCsp,
+} from './csp.js';
+
+export type { SentioPluginOptions } from './vite.js';
+export { sentioPlugin } from './vite.js';

package/src/problem.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+
+const invalidParamSchema = z.object({
+	name: z.string(),
+	reason: z.string(),
+});
+
+const problemSchema = z
+	.object({
+		type: z.string().default('about:blank'),
+		title: z.string().optional(),
+		status: z.number().int().optional(),
+		detail: z.string().optional(),
+		instance: z.string().optional(),
+		'invalid-params': z.array(invalidParamSchema).optional(),
+	})
+	.passthrough();
+
+export type InvalidParam = z.infer<typeof invalidParamSchema>;
+export type ProblemDocument = z.infer<typeof problemSchema>;
+
+export interface ProblemErrorInit {
+	type: string;
+	title?: string | undefined;
+	status?: number | undefined;
+	detail?: string | undefined;
+	instance?: string | undefined;
+	invalidParams?: readonly InvalidParam[] | undefined;
+	extensions?: Readonly<Record<string, unknown>> | undefined;
+	cause?: unknown;
+}
+
+export class ProblemError extends Error {
+	readonly type: string;
+	readonly title: string | undefined;
+	readonly status: number | undefined;
+	readonly detail: string | undefined;
+	readonly instance: string | undefined;
+	readonly invalidParams: readonly InvalidParam[] | undefined;
+	readonly extensions: Readonly<Record<string, unknown>>;
+
+	constructor(init: ProblemErrorInit) {
+		const message =
+			init.detail ?? init.title ?? `Problem: ${init.type} (${init.status ?? '?'})`;
+		super(message, init.cause === undefined ? undefined : { cause: init.cause });
+		this.name = 'ProblemError';
+		this.type = init.type;
+		this.title = init.title;
+		this.status = init.status;
+		this.detail = init.detail;
+		this.instance = init.instance;
+		this.invalidParams = init.invalidParams;
+		this.extensions = init.extensions ?? {};
+	}
+
+	toJSON(): ProblemDocument {
+		const base: Record<string, unknown> = {
+			type: this.type,
+			...this.extensions,
+		};
+		if (this.title !== undefined) base.title = this.title;
+		if (this.status !== undefined) base.status = this.status;
+		if (this.detail !== undefined) base.detail = this.detail;
+		if (this.instance !== undefined) base.instance = this.instance;
+		if (this.invalidParams !== undefined) base['invalid-params'] = this.invalidParams;
+		return base as ProblemDocument;
+	}
+}
+
+export function parseProblem(input: unknown): ProblemDocument | undefined {
+	const result = problemSchema.safeParse(input);
+	return result.success ? result.data : undefined;
+}
+
+export function problemFromDocument(doc: ProblemDocument, cause?: unknown): ProblemError {
+	const {
+		type,
+		title,
+		status,
+		detail,
+		instance,
+		['invalid-params']: invalidParams,
+		...rest
+	} = doc;
+	return new ProblemError({
+		type,
+		title,
+		status,
+		detail,
+		instance,
+		invalidParams,
+		extensions: rest,
+		cause,
+	});
+}
+
+export function problemFromResponse(
+	response: Response,
+	body: unknown,
+	cause?: unknown,
+): ProblemError {
+	const parsed = parseProblem(body);
+	if (parsed) return problemFromDocument(parsed, cause);
+	return new ProblemError({
+		type: 'about:blank',
+		title: response.statusText || 'HTTP error',
+		status: response.status,
+		detail: typeof body === 'string' ? body : undefined,
+		cause,
+	});
+}
+
+export function isProblemResponse(response: Response): boolean {
+	const ct = response.headers.get('content-type') ?? '';
+	return ct.toLowerCase().includes('application/problem+json');
+}

package/src/vite.ts

@@ -0,0 +1,56 @@
+import type { Plugin } from 'vite';
+
+export interface SentioPluginOptions {
+	requiredEnv?: readonly string[];
+	verbose?: boolean;
+	virtualModule?: Readonly<Record<string, unknown>>;
+}
+
+const VIRTUAL_ID = '$sentio';
+const RESOLVED_ID = '\0$sentio';
+
+export function sentioPlugin(options: SentioPluginOptions = {}): Plugin {
+	const { requiredEnv = [], verbose = false, virtualModule = {} } = options;
+
+	return {
+		name: 'vite-plugin-sentio',
+		enforce: 'pre',
+
+		resolveId(id) {
+			if (id === VIRTUAL_ID) return RESOLVED_ID;
+			return undefined;
+		},
+
+		load(id) {
+			if (id !== RESOLVED_ID) return undefined;
+			const entries = Object.entries(virtualModule);
+			const exports = entries
+				.map(([key, value]) => `export const ${key} = ${JSON.stringify(value)};`)
+				.join('\n');
+			return `${exports}\nexport default Object.freeze(${JSON.stringify(virtualModule)});\n`;
+		},
+
+		configResolved(config) {
+			if (verbose) {
+				console.warn('[sentio] Resolved Vite config:', {
+					mode: config.mode,
+					root: config.root,
+					build: { outDir: config.build.outDir, ssr: config.build.ssr },
+				});
+			}
+		},
+
+		buildStart() {
+			const missing = requiredEnv.filter(
+				(key) => !process.env[key] || process.env[key] === '',
+			);
+			if (missing.length > 0) {
+				throw new Error(
+					`[sentio] Missing required environment variables:\n${missing
+						.map((k) => `  - ${k}`)
+						.join('\n')}\nCheck your .env file or deployment environment.`,
+				);
+			}
+		},
+	};
+}