fundus 0.0.2 → 0.0.3

package/dist/server/cli-init.d.ts

@@ -0,0 +1,3 @@
+export declare const FUNDUS_CONFIG_TEMPLATE = "import { defineConfig } from 'fundus/config';\n\nexport default defineConfig({\n\trawDir: './assets/raw',\n\tproxyDir: './static/fundus',\n\tproxyBasePath: '/fundus/',\n\tlibrary: './assets/fundus.library.json',\n\tmanifestsDir: './src/lib/fundus'\n});\n";
+export declare const INIT_HELP = "fundus init \u2014 create a Fundus configuration file\n\nUsage: fundus init [--json]\n\nCreates a template fundus.config.ts in the current directory. The command\nrefuses to overwrite an existing configuration file.\n\nFlags:\n  --json   print {\"ok\": true, \"path\": \"fundus.config.ts\"} on stdout\n  --help   this help\n\nExample:\n  cd my-host-app && npx fundus init\n";
+export declare function runInitCommand(argumentList: string[]): Promise<void>;

package/dist/server/cli-init.js

@@ -0,0 +1,53 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArguments, printJsonDocument, requirePositionals } from './cli-io.js';
+export const FUNDUS_CONFIG_TEMPLATE = `import { defineConfig } from 'fundus/config';
+
+export default defineConfig({
+	rawDir: './assets/raw',
+	proxyDir: './static/fundus',
+	proxyBasePath: '/fundus/',
+	library: './assets/fundus.library.json',
+	manifestsDir: './src/lib/fundus'
+});
+`;
+export const INIT_HELP = `fundus init — create a Fundus configuration file
+
+Usage: fundus init [--json]
+
+Creates a template fundus.config.ts in the current directory. The command
+refuses to overwrite an existing configuration file.
+
+Flags:
+  --json   print {"ok": true, "path": "fundus.config.ts"} on stdout
+  --help   this help
+
+Example:
+  cd my-host-app && npx fundus init
+`;
+export async function runInitCommand(argumentList) {
+    if (argumentList.includes('--help')) {
+        console.log(INIT_HELP);
+        return;
+    }
+    const parsed = parseArguments(argumentList, {
+        json: { takesValue: false },
+        help: { takesValue: false }
+    }, 'fundus init');
+    requirePositionals(parsed, [], 'fundus init');
+    const configPath = resolve(process.cwd(), 'fundus.config.ts');
+    try {
+        await writeFile(configPath, FUNDUS_CONFIG_TEMPLATE, { encoding: 'utf8', flag: 'wx' });
+    }
+    catch (cause) {
+        if (cause.code === 'EEXIST') {
+            throw new Error(`fundus.config.ts already exists in ${process.cwd()}.`);
+        }
+        throw new Error(`Cannot create fundus.config.ts: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, path: 'fundus.config.ts' });
+        return;
+    }
+    console.log('Created fundus.config.ts.');
+}

package/dist/server/cli-io.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Terminal I/O for the fundus CLI (M7): hand-rolled flag parsing, the JSON
+ * output envelope, and the expected-error type — no CLI framework. The output
+ * contract agents rely on: with `--json`, stdout carries exactly one JSON
+ * document ({"ok": true, ...} on success, {"error": {"message": ...}} on an
+ * expected failure); without it, errors go to stderr. Exit codes: 0 success,
+ * 1 expected error, 2 unexpected crash (see cli.ts).
+ */
+/**
+ * A wrong invocation (unknown flag/subcommand, missing positional, malformed
+ * flag value): an expected error whose message points at the right `--help`.
+ */
+export declare class CliUsageError extends Error {
+}
+export interface FlagDefinition {
+    /** `--name value` / `--name=value` when true; a presence flag when false. */
+    takesValue: boolean;
+}
+export interface ParsedArguments {
+    positionals: string[];
+    flags: Record<string, string | true>;
+}
+/**
+ * Parse a command's argument list against its flag definitions. Supports
+ * `--flag value` and `--flag=value`; anything not starting with `--` is a
+ * positional. Unknown flags and missing values throw a `CliUsageError` that
+ * names the command's `--help`.
+ */
+export declare function parseArguments(argumentList: string[], flagDefinitions: Record<string, FlagDefinition>, commandPath: string): ParsedArguments;
+/**
+ * Enforce a command's exact positional shape. `names` are the placeholders
+ * from the synopsis (e.g. ["<id>", "<newId>"]); the mismatch message repeats
+ * the expected usage.
+ */
+export declare function requirePositionals(parsed: ParsedArguments, names: string[], commandPath: string): string[];
+/** The single JSON document a `--json` invocation writes to stdout. */
+export declare function printJsonDocument(document: unknown): void;
+/** Parse a JSON-valued flag (`--parameters`), mapping bad JSON to a usage error. */
+export declare function parseJsonFlag(name: string, value: string): unknown;
+/**
+ * Parse a `--manifests a,b` list: comma-separated names, whitespace-tolerant.
+ * The empty string is the explicit "no manifests" — it clears the membership.
+ */
+export declare function parseManifestList(value: string): string[];
+/** Human-readable byte count for terminal output (1024-based, one decimal). */
+export declare function formatBytes(bytes: number): string;

package/dist/server/cli-io.js

@@ -0,0 +1,105 @@
+/**
+ * Terminal I/O for the fundus CLI (M7): hand-rolled flag parsing, the JSON
+ * output envelope, and the expected-error type — no CLI framework. The output
+ * contract agents rely on: with `--json`, stdout carries exactly one JSON
+ * document ({"ok": true, ...} on success, {"error": {"message": ...}} on an
+ * expected failure); without it, errors go to stderr. Exit codes: 0 success,
+ * 1 expected error, 2 unexpected crash (see cli.ts).
+ */
+/**
+ * A wrong invocation (unknown flag/subcommand, missing positional, malformed
+ * flag value): an expected error whose message points at the right `--help`.
+ */
+export class CliUsageError extends Error {
+}
+/**
+ * Parse a command's argument list against its flag definitions. Supports
+ * `--flag value` and `--flag=value`; anything not starting with `--` is a
+ * positional. Unknown flags and missing values throw a `CliUsageError` that
+ * names the command's `--help`.
+ */
+export function parseArguments(argumentList, flagDefinitions, commandPath) {
+    const positionals = [];
+    const flags = {};
+    for (let index = 0; index < argumentList.length; index++) {
+        const argument = argumentList[index];
+        if (!argument.startsWith('--')) {
+            positionals.push(argument);
+            continue;
+        }
+        const equalsIndex = argument.indexOf('=');
+        const name = equalsIndex === -1 ? argument.slice(2) : argument.slice(2, equalsIndex);
+        const definition = flagDefinitions[name];
+        if (!definition) {
+            throw new CliUsageError(`Unknown flag "--${name}" for \`${commandPath}\` — run \`${commandPath} --help\`.`);
+        }
+        if (!definition.takesValue) {
+            if (equalsIndex !== -1) {
+                throw new CliUsageError(`Flag "--${name}" takes no value.`);
+            }
+            flags[name] = true;
+            continue;
+        }
+        if (equalsIndex !== -1) {
+            flags[name] = argument.slice(equalsIndex + 1);
+            continue;
+        }
+        const value = argumentList[index + 1];
+        if (value === undefined) {
+            throw new CliUsageError(`Flag "--${name}" needs a value — run \`${commandPath} --help\`.`);
+        }
+        flags[name] = value;
+        index++;
+    }
+    return { positionals, flags };
+}
+/**
+ * Enforce a command's exact positional shape. `names` are the placeholders
+ * from the synopsis (e.g. ["<id>", "<newId>"]); the mismatch message repeats
+ * the expected usage.
+ */
+export function requirePositionals(parsed, names, commandPath) {
+    if (parsed.positionals.length !== names.length) {
+        const usage = names.length === 0 ? commandPath : `${commandPath} ${names.join(' ')}`;
+        throw new CliUsageError(`\`${commandPath}\` expects ${names.length} argument(s) (usage: ${usage}) — ` +
+            `got ${parsed.positionals.length}. Run \`${commandPath} --help\`.`);
+    }
+    return parsed.positionals;
+}
+/** The single JSON document a `--json` invocation writes to stdout. */
+export function printJsonDocument(document) {
+    console.log(JSON.stringify(document, null, '\t'));
+}
+/** Parse a JSON-valued flag (`--parameters`), mapping bad JSON to a usage error. */
+export function parseJsonFlag(name, value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (cause) {
+        throw new CliUsageError(`Flag "--${name}" is not valid JSON (${cause instanceof Error ? cause.message : String(cause)}). ` +
+            `Pass a single JSON value, e.g. --${name} '{"preset": "default"}'.`);
+    }
+}
+/**
+ * Parse a `--manifests a,b` list: comma-separated names, whitespace-tolerant.
+ * The empty string is the explicit "no manifests" — it clears the membership.
+ */
+export function parseManifestList(value) {
+    return value
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+}
+/** Human-readable byte count for terminal output (1024-based, one decimal). */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KiB', 'MiB', 'GiB'];
+    let value = bytes;
+    let unitIndex = -1;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex++;
+    }
+    return `${value.toFixed(1)} ${units[unitIndex]}`;
+}

package/dist/server/codegen.d.ts

@@ -0,0 +1,58 @@
+import { type AssetRecord, type Library, type ManifestEntry, type ManifestEntryData, type ManifestMembership, type ReferencesByAsset } from '../core/index.js';
+import type { ResolvedFundusConfig } from './config-loader.js';
+import type { ServerPluginRegistry } from './plugins/contract.js';
+import type { AssetProxyInfo } from './processing/processor.js';
+export declare const GENERATED_HEADER = "// generated by fundus \u2014 do not edit\n";
+/** `mainCatalog` → `main-catalog`. */
+export declare function kebabCaseFromCamel(name: string): string;
+/** Generated module file name for a manifest. */
+export declare function manifestModuleFileName(manifestName: string): string;
+/**
+ * Build the entry data codegen emits for one asset — delegated to
+ * the owning server plugin's `buildManifestEntry`. Reference fields
+ * (chroma-key-video's mask/fallback) stay `{ $asset }` markers here — the
+ * generic `inlineAssetReferences` walk resolves them.
+ */
+export declare function manifestEntryForAsset(record: AssetRecord, proxy: AssetProxyInfo, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): ManifestEntryData;
+/** Builds one asset's raw entry data; references may remain as `{ $asset }` markers. */
+export type ManifestEntryBuilder = (assetId: string, record: AssetRecord, proxy: AssetProxyInfo, config: ResolvedFundusConfig) => ManifestEntryData;
+/**
+ * Replace every `{ $asset }` marker in a built entry with the referenced
+ * asset's own (already inlined) entry data. Codegen inlines the
+ * resolved reference, so the runtime never resolves ids. Generic deep walk;
+ * plugin entry builders stay reference-unaware.
+ */
+export declare function inlineAssetReferences(value: ManifestEntryData, resolveEntry: (assetId: string) => ManifestEntry): ManifestEntry;
+/**
+ * Build the entries for one manifest from its membership picture: the whole
+ * delivery set (explicit ∪ passive members — the shared membership
+ * computation) in dependency order (the closure is a DAG — a
+ * cycle throws), each entry's markers inlined from the already-built entries.
+ * Only the explicit members appear top-level — they are the manifest's API
+ * surface; passive members exist solely inlined.
+ */
+export declare function buildManifestEntries(options: {
+    membership: ManifestMembership;
+    library: Library;
+    proxies: Record<string, AssetProxyInfo>;
+    config: ResolvedFundusConfig;
+    referencesByAsset: ReferencesByAsset;
+    entryBuilder?: ManifestEntryBuilder;
+    registry?: ServerPluginRegistry;
+}): Record<string, ManifestEntry>;
+/** Render one generated manifest module. */
+export declare function renderManifestModule(manifestName: string, entries: Record<string, ManifestEntry | ManifestEntryData>): string;
+export interface CodegenReport {
+    /** Written module file names. */
+    written: string[];
+    /** Removed module file names (their manifest no longer exists). */
+    removed: string[];
+}
+/** Fundus-owned generated modules not present in the expected file-name set. */
+export declare function strayGeneratedModuleNames(manifestsDir: string, expectedFileNames: ReadonlySet<string>): Promise<string[]>;
+/**
+ * Write one module per manifest and remove generated modules whose manifest is
+ * gone. Only files starting with the fundus header are ever removed, so other
+ * generated files co-located in the directory stay untouched.
+ */
+export declare function generateManifestModules(config: ResolvedFundusConfig, library: Library, proxies: Record<string, AssetProxyInfo>, registry?: ServerPluginRegistry): Promise<CodegenReport>;

package/dist/server/codegen.js

@@ -0,0 +1,185 @@
+/**
+ * Manifest module codegen: one `<manifest-name-kebab>.generated.ts`
+ * per manifest in the configured manifests directory, containing data only —
+ * entries constructed through the runtime's `createManifest`. Deterministic:
+ * sorted asset ids, fixed property order, tab indentation. Generated modules
+ * for deleted manifests are removed (only files carrying the fundus header).
+ */
+import { mkdir, readdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { collectAllReferences, compareCodeUnits, computeLibraryMembership, isAssetReference, topologicalReferenceOrder } from '../core/index.js';
+import { descriptorsByType, serverPluginForType, serverPluginsByType } from './plugins.js';
+export const GENERATED_HEADER = '// generated by fundus — do not edit\n';
+/** `mainCatalog` → `main-catalog`. */
+export function kebabCaseFromCamel(name) {
+    return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+/** Generated module file name for a manifest. */
+export function manifestModuleFileName(manifestName) {
+    return `${kebabCaseFromCamel(manifestName)}.generated.ts`;
+}
+/**
+ * Build the entry data codegen emits for one asset — delegated to
+ * the owning server plugin's `buildManifestEntry`. Reference fields
+ * (chroma-key-video's mask/fallback) stay `{ $asset }` markers here — the
+ * generic `inlineAssetReferences` walk resolves them.
+ */
+export function manifestEntryForAsset(record, proxy, config, registry = serverPluginsByType) {
+    const plugin = serverPluginForType(record.type, registry);
+    return plugin.buildManifestEntry({
+        assetId: proxy.assetId,
+        parameters: plugin.descriptor.validateParameters(record.parameters),
+        src: `${config.proxyBasePath}${proxy.relativePath
+            .split('/')
+            .map(encodeURIComponent)
+            .join('/')}`,
+        proxy
+    });
+}
+/**
+ * Replace every `{ $asset }` marker in a built entry with the referenced
+ * asset's own (already inlined) entry data. Codegen inlines the
+ * resolved reference, so the runtime never resolves ids. Generic deep walk;
+ * plugin entry builders stay reference-unaware.
+ */
+export function inlineAssetReferences(value, resolveEntry) {
+    return inlineValue(value, resolveEntry);
+}
+function inlineValue(value, resolveEntry) {
+    if (isAssetReference(value)) {
+        return resolveEntry(value.$asset);
+    }
+    if (Array.isArray(value)) {
+        return value.map((element) => inlineValue(element, resolveEntry));
+    }
+    if (typeof value === 'object' && value !== null) {
+        const inlined = {};
+        for (const [key, nested] of Object.entries(value)) {
+            inlined[key] = inlineValue(nested, resolveEntry);
+        }
+        return inlined;
+    }
+    return value;
+}
+/**
+ * Build the entries for one manifest from its membership picture: the whole
+ * delivery set (explicit ∪ passive members — the shared membership
+ * computation) in dependency order (the closure is a DAG — a
+ * cycle throws), each entry's markers inlined from the already-built entries.
+ * Only the explicit members appear top-level — they are the manifest's API
+ * surface; passive members exist solely inlined.
+ */
+export function buildManifestEntries(options) {
+    const buildEntry = options.entryBuilder ??
+        ((assetId, record, proxy, config) => manifestEntryForAsset(record, proxy, config, options.registry));
+    const buildOrder = topologicalReferenceOrder(options.membership.deliveredAssetIds, options.referencesByAsset);
+    const builtEntries = {};
+    const resolveEntry = (assetId) => {
+        if (!Object.hasOwn(builtEntries, assetId)) {
+            throw new Error(`Cannot inline reference to "${assetId}" — no entry was built for it.`);
+        }
+        return builtEntries[assetId];
+    };
+    for (const assetId of buildOrder) {
+        if (!Object.hasOwn(options.library.assets, assetId)) {
+            throw new Error(`Cannot build an entry for unknown asset "${assetId}".`);
+        }
+        const proxy = options.proxies[assetId];
+        if (!proxy) {
+            throw new Error(`No proxy info for asset "${assetId}". Run processing before codegen.`);
+        }
+        const rawEntry = buildEntry(assetId, options.library.assets[assetId], proxy, options.config);
+        builtEntries[assetId] = inlineAssetReferences(rawEntry, resolveEntry);
+    }
+    const memberEntries = {};
+    for (const assetId of options.membership.explicitMemberIds) {
+        memberEntries[assetId] = builtEntries[assetId];
+    }
+    return memberEntries;
+}
+/** Render one generated manifest module. */
+export function renderManifestModule(manifestName, entries) {
+    const assetIds = Object.keys(entries).sort(compareCodeUnits);
+    const body = assetIds.length === 0
+        ? `export const ${manifestName} = createManifest({});`
+        : `export const ${manifestName} = createManifest({\n` +
+            assetIds
+                .map((assetId) => {
+                const json = JSON.stringify(entries[assetId], null, '\t').replace(/\n/g, '\n\t');
+                return `\t${assetId}: ${json}`;
+            })
+                .join(',\n') +
+            `\n});`;
+    return `${GENERATED_HEADER}import { createManifest } from 'fundus';\n\n${body}\n`;
+}
+/** Fundus-owned generated modules not present in the expected file-name set. */
+export async function strayGeneratedModuleNames(manifestsDir, expectedFileNames) {
+    let fileNames;
+    try {
+        fileNames = await readdir(manifestsDir);
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return [];
+        throw cause;
+    }
+    const strayNames = [];
+    for (const fileName of fileNames) {
+        if (!fileName.endsWith('.generated.ts') || expectedFileNames.has(fileName))
+            continue;
+        const content = await readFile(join(manifestsDir, fileName), 'utf8');
+        if (content.startsWith(GENERATED_HEADER))
+            strayNames.push(fileName);
+    }
+    return strayNames.sort(compareCodeUnits);
+}
+/**
+ * Write one module per manifest and remove generated modules whose manifest is
+ * gone. Only files starting with the fundus header are ever removed, so other
+ * generated files co-located in the directory stay untouched.
+ */
+export async function generateManifestModules(config, library, proxies, registry = serverPluginsByType) {
+    await mkdir(config.manifestsDir, { recursive: true });
+    const report = { written: [], removed: [] };
+    const expectedFileNames = new Set();
+    // Two distinct manifest names can share a kebab form (`mainCatalog` / `mainCATALOG`
+    // both map to `main-catalog`) — that would make one module silently overwrite
+    // the other. The store rejects such names at creation; this guard is defense
+    // in depth for hand-edited libraries.
+    const namesByFileName = new Map();
+    for (const manifestName of Object.keys(library.manifests)) {
+        const fileName = manifestModuleFileName(manifestName);
+        namesByFileName.set(fileName, [...(namesByFileName.get(fileName) ?? []), manifestName]);
+    }
+    for (const [fileName, manifestNames] of namesByFileName) {
+        if (manifestNames.length > 1) {
+            throw new Error(`Manifests ${manifestNames.map((name) => `"${name}"`).join(' and ')} would both generate ` +
+                `"${fileName}" — rename one so the kebab-case module names stay distinct.`);
+        }
+    }
+    const referencesByAsset = collectAllReferences(library, descriptorsByType(registry));
+    const membershipByManifest = computeLibraryMembership(library, referencesByAsset);
+    const renderedModules = [];
+    for (const manifestName of Object.keys(library.manifests).sort(compareCodeUnits)) {
+        const entries = buildManifestEntries({
+            membership: membershipByManifest[manifestName],
+            library,
+            proxies,
+            config,
+            referencesByAsset,
+            registry
+        });
+        const fileName = manifestModuleFileName(manifestName);
+        expectedFileNames.add(fileName);
+        renderedModules.push({ fileName, content: renderManifestModule(manifestName, entries) });
+    }
+    for (const { fileName, content } of renderedModules) {
+        await writeFile(join(config.manifestsDir, fileName), content);
+        report.written.push(fileName);
+    }
+    for (const fileName of await strayGeneratedModuleNames(config.manifestsDir, expectedFileNames)) {
+        await unlink(join(config.manifestsDir, fileName));
+        report.removed.push(fileName);
+    }
+    return report;
+}

package/dist/server/config-loader.d.ts

@@ -0,0 +1,34 @@
+import { type AudioPreset, type ImagePreset, type VideoPreset } from '../core/index.js';
+export interface ResolvedPresetPluginConfig {
+    presets: Record<string, ImagePreset>;
+}
+export interface ResolvedVideoPluginConfig {
+    presets: Record<string, VideoPreset>;
+    /** Absolute path of the ffmpeg binary to use; null = the bundled `ffmpeg-static`. */
+    ffmpegPath: string | null;
+    /** Absolute path of the ffprobe binary to use; null = the bundled `ffprobe-static`. */
+    ffprobePath: string | null;
+}
+export interface ResolvedAudioPluginConfig {
+    presets: Record<string, AudioPreset>;
+}
+export interface ResolvedFundusConfig {
+    /** All paths absolute. */
+    rawDir: string;
+    proxyDir: string;
+    library: string;
+    manifestsDir: string;
+    /** URL prefix baked into generated proxy `src` values; always ends with '/'. */
+    proxyBasePath: string;
+    plugins: {
+        image: ResolvedPresetPluginConfig;
+        slice: ResolvedPresetPluginConfig;
+        /** Shared by video and chroma-key-video through one preset namespace. */
+        video: ResolvedVideoPluginConfig;
+        audio: ResolvedAudioPluginConfig;
+    };
+}
+/** Pure resolution step (testable without a config file on disk). */
+export declare function resolveConfig(projectRoot: string, value: unknown): ResolvedFundusConfig;
+/** Load `fundus.config.ts` from the host project root. */
+export declare function loadConfig(projectRoot: string): Promise<ResolvedFundusConfig>;

package/dist/server/config-loader.js

@@ -0,0 +1,103 @@
+/**
+ * Loads and resolves the host's `fundus.config.ts` through jiti, validates
+ * the shape, resolves all paths to
+ * absolute, and merges the built-in plugin preset defaults under the host's.
+ */
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { createJiti } from 'jiti';
+import { AUDIO_BUILT_IN_PRESETS, IMAGE_BUILT_IN_PRESETS, SLICE_BUILT_IN_PRESETS, VIDEO_BUILT_IN_PRESETS, validateAudioPreset, validateImagePreset, validateVideoPreset } from '../core/index.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requiredString(config, key) {
+    const value = config[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`fundus.config: "${key}" must be a non-empty string.`);
+    }
+    return value;
+}
+function resolvePath(projectRoot, value) {
+    return isAbsolute(value) ? value : resolve(projectRoot, value);
+}
+function mergePresets(label, builtIn, pluginConfig, validatePreset) {
+    const merged = { ...builtIn };
+    if (pluginConfig === undefined)
+        return merged;
+    if (!isRecord(pluginConfig)) {
+        throw new Error(`fundus.config: "plugins.${label}" must be an object.`);
+    }
+    if (pluginConfig.presets === undefined)
+        return merged;
+    if (!isRecord(pluginConfig.presets)) {
+        throw new Error(`fundus.config: "plugins.${label}.presets" must be an object.`);
+    }
+    for (const [name, preset] of Object.entries(pluginConfig.presets)) {
+        merged[name] = validatePreset(name, preset);
+    }
+    return merged;
+}
+/** `plugins.video.ffmpegPath` / `ffprobePath`: optional system-binary overrides. */
+function binaryPathOverride(projectRoot, pluginConfig, key) {
+    if (!isRecord(pluginConfig) || pluginConfig[key] === undefined)
+        return null;
+    const value = pluginConfig[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`fundus.config: "plugins.video.${key}" must be a non-empty string.`);
+    }
+    return resolvePath(projectRoot, value);
+}
+/** Pure resolution step (testable without a config file on disk). */
+export function resolveConfig(projectRoot, value) {
+    if (!isRecord(value)) {
+        throw new Error('fundus.config must default-export a configuration object.');
+    }
+    const proxyBasePath = requiredString(value, 'proxyBasePath');
+    if (!proxyBasePath.endsWith('/')) {
+        throw new Error('fundus.config: "proxyBasePath" must end with "/".');
+    }
+    const plugins = value.plugins === undefined ? {} : value.plugins;
+    if (!isRecord(plugins)) {
+        throw new Error('fundus.config: "plugins" must be an object.');
+    }
+    return {
+        rawDir: resolvePath(projectRoot, requiredString(value, 'rawDir')),
+        proxyDir: resolvePath(projectRoot, requiredString(value, 'proxyDir')),
+        library: resolvePath(projectRoot, requiredString(value, 'library')),
+        manifestsDir: resolvePath(projectRoot, requiredString(value, 'manifestsDir')),
+        proxyBasePath,
+        plugins: {
+            image: {
+                presets: mergePresets('image', IMAGE_BUILT_IN_PRESETS, plugins.image, validateImagePreset)
+            },
+            slice: {
+                presets: mergePresets('slice', SLICE_BUILT_IN_PRESETS, plugins.slice, validateImagePreset)
+            },
+            video: {
+                presets: mergePresets('video', VIDEO_BUILT_IN_PRESETS, plugins.video, validateVideoPreset),
+                ffmpegPath: binaryPathOverride(projectRoot, plugins.video, 'ffmpegPath'),
+                ffprobePath: binaryPathOverride(projectRoot, plugins.video, 'ffprobePath')
+            },
+            audio: {
+                presets: mergePresets('audio', AUDIO_BUILT_IN_PRESETS, plugins.audio, validateAudioPreset)
+            }
+        }
+    };
+}
+/** Load `fundus.config.ts` from the host project root. */
+export async function loadConfig(projectRoot) {
+    const root = resolve(projectRoot);
+    const configPath = resolve(root, 'fundus.config.ts');
+    if (!existsSync(configPath)) {
+        throw new Error(`No fundus.config.ts found in ${root}.`);
+    }
+    let module;
+    try {
+        const jiti = createJiti(import.meta.url, { interopDefault: false });
+        module = await jiti.import(configPath);
+    }
+    catch (cause) {
+        throw new Error(`Cannot load fundus.config.ts: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    return resolveConfig(root, isRecord(module) && 'default' in module ? module.default : module);
+}

package/dist/server/context.d.ts

@@ -0,0 +1,8 @@
+import { type ResolvedFundusConfig } from './config-loader.js';
+import { FundusOperations } from './operations.js';
+export interface FundusContext {
+    config: ResolvedFundusConfig;
+    operations: FundusOperations;
+}
+export declare function initializeFundusContext(): Promise<FundusContext>;
+export declare function getFundusContext(): Promise<FundusContext>;

package/dist/server/context.js

@@ -0,0 +1,19 @@
+import { isAbsolute } from 'node:path';
+import { loadConfig } from './config-loader.js';
+import { FundusOperations } from './operations.js';
+let context;
+export function initializeFundusContext() {
+    context ??= createFundusContext();
+    return context;
+}
+export function getFundusContext() {
+    return initializeFundusContext();
+}
+async function createFundusContext() {
+    const projectRoot = process.env.FUNDUS_PROJECT_ROOT;
+    if (!projectRoot || !isAbsolute(projectRoot)) {
+        throw new Error('FUNDUS_PROJECT_ROOT must be set to an absolute host project directory.');
+    }
+    const config = await loadConfig(projectRoot);
+    return { config, operations: new FundusOperations(config) };
+}

package/dist/server/folder-filesystem.d.ts

@@ -0,0 +1,7 @@
+import { type Library } from '../core/index.js';
+import type { ResolvedFundusConfig } from './config-loader.js';
+export declare function ensureManagedFolder(root: string, folder: string): Promise<void>;
+export declare function syncManagedFolders(config: ResolvedFundusConfig, library: Library): Promise<void>;
+/** Recursively list files as POSIX-style paths relative to `root`. */
+export declare function listRelativeFiles(root: string, folder?: string): Promise<string[]>;
+export declare function encodeRelativePathForUrl(path: string): string;

package/dist/server/folder-filesystem.js

@@ -0,0 +1,39 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FOLDER_SENTINEL } from '../core/index.js';
+export async function ensureManagedFolder(root, folder) {
+    const directory = join(root, folder);
+    await mkdir(directory, { recursive: true });
+    if (folder === '')
+        return;
+    const sentinel = join(directory, FOLDER_SENTINEL);
+    if (!existsSync(sentinel))
+        await writeFile(sentinel, '');
+}
+export async function syncManagedFolders(config, library) {
+    await Promise.all(library.folders.flatMap((folder) => [
+        ensureManagedFolder(config.rawDir, folder),
+        ensureManagedFolder(config.proxyDir, folder)
+    ]));
+}
+/** Recursively list files as POSIX-style paths relative to `root`. */
+export async function listRelativeFiles(root, folder = '') {
+    const directory = join(root, folder);
+    if (!existsSync(directory))
+        return [];
+    const result = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const relativePath = folder === '' ? entry.name : `${folder}/${entry.name}`;
+        if (entry.isDirectory()) {
+            result.push(...(await listRelativeFiles(root, relativePath)));
+        }
+        else if (entry.isFile()) {
+            result.push(relativePath);
+        }
+    }
+    return result;
+}
+export function encodeRelativePathForUrl(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}