@openfairygui/backend 0.2.0-alpha.0

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@openfairygui/backend",
+	"version": "0.2.0-alpha.0",
+	"description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
+	"author": "OpenFairyGUI Contributors",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/OpenFairyGUI/OpenFairyGUI.git",
+		"directory": "packages/backend"
+	},
+	"homepage": "https://github.com/OpenFairyGUI/OpenFairyGUI#readme",
+	"bugs": {
+		"url": "https://github.com/OpenFairyGUI/OpenFairYGUI/issues"
+	},
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		"require": {
+			"types": "./dist/index.d.cts",
+			"default": "./dist/index.cjs"
+		},
+		"default": {
+			"types": "./dist/index.d.mts",
+			"default": "./dist/index.mjs"
+		}
+	},
+	"scripts": {
+		"build": "tsdown --format esm,cjs --platform node --external node:fs --external node:fs/promises --external node:path --env.PACKAGE_VERSION=$npm_package_version",
+		"build:watch": "tsdown --watch --format esm,cjs --platform node --env.PACKAGE_VERSION=$npm_package_version"
+	},
+	"files": [
+		"dist/",
+		"src/"
+	],
+	"keywords": [
+		"fairygui",
+		"backend",
+		"session",
+		"authoring",
+		"runtime"
+	],
+	"dependencies": {
+		"@openfairygui/core": "workspace:*",
+		"@openfairygui/functions": "workspace:*"
+	},
+	"devDependencies": {
+		"ava": "^7.0.0",
+		"tsx": "^4.0.0"
+	}
+}

package/src/contracts.ts

@@ -0,0 +1,32 @@
+export const BACKEND_CONTRACT_VERSION = '1.1.0-p2' as const;
+export const BACKEND_CAPABILITY_SCHEMA_VERSION = 2 as const;
+export const BACKEND_COMPATIBILITY_POLICY = {
+	incompatibleChange: 'requires contractVersion bump',
+	capabilitySchemaChange: 'requires capabilitySchemaVersion bump',
+	additiveChange: 'allowed without breaking existing consumers',
+} as const;
+
+export type BackendStage = 'read' | 'authoring' | 'runtime';
+
+export interface BackendMessage {
+	code: string;
+	message: string;
+}
+
+export interface BackendDiagnostic {
+	code: string;
+	message: string;
+	severity: 'info' | 'warning' | 'error';
+}
+
+export interface BackendResponseMeta {
+	requestId: string;
+	sessionId?: string;
+	revision?: number;
+	durationMs: number;
+	warnings: BackendMessage[];
+	diagnostics: BackendDiagnostic[];
+	stage: BackendStage;
+	contractVersion: typeof BACKEND_CONTRACT_VERSION;
+	capabilitySchemaVersion: typeof BACKEND_CAPABILITY_SCHEMA_VERSION;
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+export {
+	BackendRuntime,
+	createNodeBackendFileSystem,
+	type AdvisoryLockConflictError,
+	type ApplySessionTransactionInput,
+	type BackendCacheEntry,
+	type BackendCacheSnapshot,
+	type BackendCapabilities,
+	type BackendError,
+	type BackendEvent,
+	type BackendEventKind,
+	type BackendFailure,
+	type BackendFileHandle,
+	type BackendFileSystem,
+	type BackendJobKind,
+	type BackendJobListSnapshot,
+	type BackendJobListStatusFilter,
+	type BackendJobNotCancellableError,
+	type BackendJobNotFoundError,
+	type BackendJobProgress,
+	type BackendJobSnapshot,
+	type BackendJobStatus,
+	type BackendJobErrors,
+	type BackendResult,
+	type BackendSessionSnapshot,
+	type BackendSuccess,
+	type BackendRuntimeOptions,
+	type CacheRefreshFailedError,
+	type CancelJobInput,
+	type EventCursorInvalidError,
+	type GetCacheSnapshotInput,
+	type GetEventsInput,
+	type GetEventsSnapshot,
+	type GetJobInput,
+	type InProcessLockConflictError,
+	type ListJobsInput,
+	type RefreshCacheInput,
+	type SavePartialFailureError,
+	type SessionNotFoundError,
+	type SessionStaleWriteError,
+} from './runtime.js';
+export {
+	type BackendDiagnostic,
+	type BackendMessage,
+	type BackendResponseMeta,
+	type BackendStage,
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_COMPATIBILITY_POLICY,
+	BACKEND_CONTRACT_VERSION,
+} from './contracts.js';

package/src/path-policy.ts

@@ -0,0 +1,105 @@
+import type { BackendCapabilities, BackendFileSystem } from './runtime.js';
+
+export function normalizeComparablePath(value: string): string {
+	const normalized = value.replace(/[/\\]+$/, '').replace(/\\/g, '/');
+	const driveMatch = normalized.match(/^([a-z]:)(?:\/(.*))?$/i);
+	const drivePrefix = driveMatch?.[1].toLowerCase() ?? '';
+	const remainder = driveMatch ? (driveMatch[2] ?? '') : normalized;
+	const hasRoot = driveMatch ? true : remainder.startsWith('/');
+	const rawSegments = remainder.split('/').filter((segment) => segment.length > 0);
+	const segments: string[] = [];
+
+	for (const segment of rawSegments) {
+		if (segment === '.') continue;
+		if (segment === '..') {
+			if (segments.length > 0 && segments[segments.length - 1] !== '..') {
+				segments.pop();
+			} else if (!hasRoot) {
+				segments.push('..');
+			}
+			continue;
+		}
+		segments.push(segment);
+	}
+
+	const joined = segments.join('/');
+	const comparable = drivePrefix
+		? `${drivePrefix}/${joined}`.replace(/\/$/, '')
+		: hasRoot
+			? `/${joined}`.replace(/\/$/, '')
+			: joined || '.';
+	return comparable.toLowerCase();
+}
+
+export function createRuntimePathPolicy(): BackendCapabilities['runtime']['pathPolicy'] {
+	return {
+		canonicalization: 'realpath+normalized-casefold',
+		sessionIdentity: 'project-root',
+		saveTarget: 'opened-project-only',
+		outputTargets: 'deferred',
+		workspaceBoundary: 'project-root-only',
+	};
+}
+
+export async function resolveFairyPath(fileSystem: BackendFileSystem, input: string): Promise<string> {
+	const resolvedInput = fileSystem.resolve(input);
+	const stat = await fileSystem.stat(resolvedInput);
+
+	if (stat.isFile() && resolvedInput.endsWith('.fairy')) {
+		return await fileSystem.resolvePath(resolvedInput);
+	}
+
+	if (stat.isDirectory()) {
+		const entries = await fileSystem.readdir(resolvedInput);
+		const fairyFiles = entries.filter((entry) => entry.endsWith('.fairy'));
+		if (fairyFiles.length === 1) {
+			return await fileSystem.resolvePath(fileSystem.join(resolvedInput, fairyFiles[0]!));
+		}
+		if (fairyFiles.length > 1) {
+			throw new Error(`Multiple .fairy files found in ${resolvedInput}: ${fairyFiles.join(', ')}`);
+		}
+		throw new Error(`No .fairy file found in ${resolvedInput}`);
+	}
+
+	throw new Error(`Input is not a .fairy file or directory: ${resolvedInput}`);
+}
+
+export async function resolveCanonicalProjectRoot(fileSystem: BackendFileSystem, input: string): Promise<{
+	fairyPath: string;
+	canonicalProjectPath: string;
+	canonicalPathKey: string;
+}> {
+	const fairyPath = await resolveFairyPath(fileSystem, input);
+	const canonicalProjectPath = await fileSystem.resolvePath(fileSystem.dirname(fairyPath));
+	return {
+		fairyPath,
+		canonicalProjectPath,
+		canonicalPathKey: normalizeComparablePath(canonicalProjectPath),
+	};
+}
+
+export interface PathPolicyViolationError {
+	code: 'path_policy_violation';
+	message: string;
+	policy: 'save_target';
+	attemptedPath: string;
+	allowedPath: string;
+}
+
+export async function validateSaveTarget(
+	fileSystem: BackendFileSystem,
+	openedFairyPath: string,
+	targetPath: string | undefined,
+): Promise<PathPolicyViolationError | null> {
+	if (!targetPath) return null;
+	const attemptedPath = await fileSystem.resolvePath(fileSystem.resolve(targetPath));
+	const allowedPath = await fileSystem.resolvePath(openedFairyPath);
+	if (normalizeComparablePath(attemptedPath) === normalizeComparablePath(allowedPath)) return null;
+	return {
+		code: 'path_policy_violation',
+		message: `Save target is restricted to the originally opened project file: ${allowedPath}`,
+		policy: 'save_target',
+		attemptedPath,
+		allowedPath,
+	};
+}