fundus 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,370 @@
+import { AssetId, AssetRecord, AssetTypePluginDescriptor, AudioPreset, FundusStateDto, ImagePreset, Library, ManifestEntryData, PatchAssetRequestDto, PatchManifestRequestDto, ValidationIssueDto, VideoPreset } from "#fundus/core";
+
+//#region src/config-loader.d.ts
+interface ResolvedPresetPluginConfig {
+  presets: Record<string, ImagePreset>;
+}
+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;
+}
+interface ResolvedAudioPluginConfig {
+  presets: Record<string, AudioPreset>;
+}
+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). */
+declare function resolveConfig(projectRoot: string, value: unknown): ResolvedFundusConfig;
+/** Load `fundus.config.ts` from the host project root. */
+declare function loadConfig(projectRoot: string): Promise<ResolvedFundusConfig>;
+//#endregion
+//#region src/plugins/contract.d.ts
+/** Output metadata of one processed proxy file (absent fields don't apply). */
+interface ProxyOutputInfo {
+  /** Intrinsic pixel dimensions; absent for audio proxies. */
+  width?: number;
+  height?: number;
+  /** Media duration; present for video and audio proxies. */
+  durationMs?: number;
+}
+/** One delivered asset's current proxy: file identity plus output metadata. */
+interface AssetProxyInfo extends ProxyOutputInfo {
+  assetId: string;
+  /** Basename, stable across folder moves. */
+  fileName: string;
+  /** Path relative to proxyDir, mirroring the raw asset's folder. */
+  relativePath: string;
+  fileSize: number;
+}
+/** The inputs of one processing run: raw file → proxy file. */
+interface ServerProcessingJob<TParameters, TPreset> {
+  /** Absolute path of the raw source file. */
+  sourcePath: string;
+  /** Absolute path the proxy file must be written to. */
+  targetPath: string;
+  /** The asset's validated parameters. */
+  parameters: TParameters;
+  /** The resolved preset the parameters name. */
+  preset: TPreset;
+  config: ResolvedFundusConfig;
+}
+/** The inputs of one manifest-entry build. */
+interface ManifestEntryInput<TParameters> {
+  assetId: string;
+  /** The asset's validated parameters. */
+  parameters: TParameters;
+  /** The delivered proxy URL (`proxyBasePath` + proxy relative path). */
+  src: string;
+  proxy: AssetProxyInfo;
+}
+interface ServerAssetTypePlugin<TParameters = unknown, TPreset = unknown> {
+  /** The environment-free half of the plugin (type key, ingestion, validation). */
+  descriptor: AssetTypePluginDescriptor<TParameters, unknown>;
+  /**
+   * The plugin's `plugins.<namespace>` config slice — handed to the
+   * descriptor's `defaultParameters` on ingest. Types may share a namespace
+   * (chroma-key-video uses the video slice).
+   */
+  pluginConfig(config: ResolvedFundusConfig): unknown;
+  /** The merged (built-in + host) named presets available to this type. */
+  presets(config: ResolvedFundusConfig): Record<string, TPreset>;
+  /**
+   * The resolved settings of the preset the validated parameters name —
+   * these feed the job hash (a preset edit under an unchanged name
+   * must rename the proxy). Throws (listing the known names) on a miss.
+   */
+  resolvePreset(parameters: TParameters, config: ResolvedFundusConfig): TPreset;
+  /** The proxy file extension a resolved preset's output carries. */
+  proxyExtension(preset: TPreset): string;
+  /**
+   * Optional ingest seeding, run right after the raw file is stored: derive
+   * better starting parameters than the schema defaults from the actual raw
+   * file — the slice plugin seeds insets from the image dimensions and a
+   * pixel ratio from a `@2x`-style file-name suffix. Returns the replacement
+   * parameters, or undefined to keep the defaults. Omitted = defaults stand.
+   */
+  seedIngestParameters?(context: {
+    /** Absolute path of the stored raw file. */rawPath: string; /** The stored raw file name (sanitized, unique). */
+    rawFileName: string; /** The validated default parameters the record starts with. */
+    parameters: TParameters;
+    config: ResolvedFundusConfig;
+  }): Promise<TParameters | undefined>;
+  /** Run the processing job (sharp/ffmpeg): write the proxy, report its metadata. */
+  process(job: ServerProcessingJob<TParameters, TPreset>): Promise<ProxyOutputInfo>;
+  /** Probe an existing proxy file's output metadata (the up-to-date path). */
+  readProxyInfo(proxyPath: string, config: ResolvedFundusConfig): Promise<ProxyOutputInfo>;
+  /**
+   * Build the generated manifest entry. Reference fields stay
+   * `{ $asset }` markers — codegen's generic inline walk resolves them.
+   */
+  buildManifestEntry(input: ManifestEntryInput<TParameters>): ManifestEntryData;
+}
+/** The one server-side touch point for a new asset type: type key → plugin. */
+type ServerPluginRegistry = Record<string, ServerAssetTypePlugin>;
+//#endregion
+//#region src/library-store.d.ts
+interface IngestOptions {
+  /** Original file name of the upload (sanitized before storing). */
+  fileName: string;
+  bytes: Uint8Array;
+  /** Asset type (must be a known plugin type). */
+  type: string;
+  /** The chosen asset id (validated; must be unique). */
+  id: string;
+  /** Registered destination folder; empty string means the implicit root. */
+  folder?: string;
+}
+declare class LibraryStore {
+  #private;
+  constructor(config: ResolvedFundusConfig, registry?: ServerPluginRegistry);
+  get config(): ResolvedFundusConfig;
+  /** Read + parse the library file; a missing file is an empty library. */
+  read(): Promise<Library>;
+  /** Deterministically serialize + write the library file. */
+  write(library: Library): Promise<void>;
+  /**
+   * Ingest a new asset: write the raw file into `rawDir` (under a sanitized,
+   * non-colliding name), hash its content, and create the library record with
+   * the owning plugin's default parameters. Returns the updated library.
+   */
+  ingest(options: IngestOptions): Promise<Library>;
+  /** Replace an asset's parameters (validated by the owning plugin). */
+  updateParameters(id: string, parameters: unknown): Promise<Library>;
+  /** Replace an asset's manifest membership (every name must exist). */
+  setManifests(id: string, manifests: string[]): Promise<Library>;
+  /** Rename an asset id (the raw file keeps its name — ids are the stable key). */
+  renameAsset(id: string, newId: string): Promise<Library>;
+  /** Move an asset's raw file and current proxies without changing its stable id. */
+  moveAsset(id: string, folder: string): Promise<Library>;
+  createFolder(path: string): Promise<Library>;
+  renameFolder(path: string, newName: string): Promise<Library>;
+  /** Move a complete folder subtree below another folder (or the implicit root). */
+  moveFolder(path: string, parent: string): Promise<Library>;
+  /** Recursively delete a folder and every asset stored below it. */
+  deleteFolder(path: string): Promise<{
+    library: Library;
+    deletedAssetIds: string[];
+  }>;
+  /** Delete an asset: remove the record, its raw file, and its proxies. */
+  deleteAsset(id: string): Promise<Library>;
+  /** Delete several assets as one library/file transaction. */
+  deleteAssets(ids: string[]): Promise<Library>;
+  createManifest(name: string): Promise<Library>;
+  /**
+   * Set (or clear) a manifest's editor appearance — its color and/or emoji.
+   * An `undefined` field is left unchanged; a `null` field clears it. Values
+   * are validated against the fixed palettes.
+   */
+  setManifestAppearance(name: string, appearance: {
+    color?: string | null;
+    emoji?: string | null;
+  }): Promise<Library>;
+  /** Rename a manifest and rewrite every asset's membership to the new name. */
+  renameManifest(name: string, newName: string): Promise<Library>;
+  /** Delete a manifest and strip it from every asset's membership. */
+  deleteManifest(name: string): Promise<Library>;
+  /**
+   * Structural + referential validation, listed per asset: invalid id, unknown
+   * type, dangling raw pointer, invalid parameters, unknown manifest names,
+   * and reference errors (dangling target, type mismatch, cycles).
+   */
+  validate(library: Library): Promise<ValidationIssueDto[]>;
+  syncFolders(library: Library): Promise<void>;
+}
+//#endregion
+//#region src/processing/processor.d.ts
+/** Whether a file name in the proxy directory is (shaped like) a fundus proxy. */
+declare function isProxyFileName(fileName: string): boolean;
+interface ProcessingReport {
+  /** Asset ids whose proxy was (re)generated in this run. */
+  processed: string[];
+  /** Asset ids whose proxy was already current (name check hit). */
+  reused: string[];
+  /** Orphaned proxy file names removed from the proxy directory. */
+  pruned: string[];
+  /** Per delivered asset: the current proxy and its output metadata. */
+  proxies: Record<string, AssetProxyInfo>;
+}
+/**
+ * The proxy file name an asset's current raw content + parameters demand.
+ * Throws when the parameters are invalid or reference an unknown preset.
+ *
+ * The hash input is the *effective* processing input: the asset's
+ * processing-relevant parameters (the plugin-declared subset — entry-only data
+ * like chroma-key tuning and references must not rename the proxy)
+ * plus the preset's **resolved settings** — parameters only carry the preset
+ * *name*, so hashing them alone would keep serving stale proxy bytes after a
+ * preset's quality/format is edited in the host config.
+ */
+declare function expectedProxyFileName(assetId: string, record: AssetRecord, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): string;
+/** Expected proxy path relative to proxyDir, mirroring the raw asset folder. */
+declare function expectedProxyRelativePath(assetId: string, record: AssetRecord, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): string;
+/**
+ * Output metadata of an existing proxy file, probed per the owning plugin's
+ * strategy: image-backed proxies via sharp, media proxies via ffprobe.
+ */
+declare function readProxyOutputInfo(type: string, proxyPath: string, config: ResolvedFundusConfig, registry?: ServerPluginRegistry): Promise<ProxyOutputInfo>;
+/**
+ * The delivered set: every explicit or passive member of ≥ 1 manifest —
+ * derived by the shared membership computation. Assets outside
+ * it are inert.
+ */
+declare function deliveredAssetIds(library: Library, registry?: ServerPluginRegistry): Set<AssetId>;
+/**
+ * Ensure every delivered asset's proxy exists (processing stale/missing ones)
+ * and prune orphans. Assets outside the delivered set are skipped entirely.
+ */
+declare function processAssets(config: ResolvedFundusConfig, library: Library, registry?: ServerPluginRegistry): Promise<ProcessingReport>;
+//#endregion
+//#region src/processing/ffmpeg.d.ts
+declare function ffmpegBinaryPath(config: ResolvedFundusConfig): string;
+/**
+ * Run a toolchain binary with an argument array (never a shell string) and
+ * return its stdout. A non-zero exit throws with the stderr tail — ffmpeg
+ * writes its diagnostics there.
+ */
+declare function runToolchainBinary(binaryPath: string, commandArguments: string[]): Promise<string>;
+//#endregion
+//#region src/codegen.d.ts
+interface CodegenReport {
+  /** Written module file names. */
+  written: string[];
+  /** Removed module file names (their manifest no longer exists). */
+  removed: 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.
+ */
+declare function generateManifestModules(config: ResolvedFundusConfig, library: Library, proxies: Record<string, AssetProxyInfo>, registry?: ServerPluginRegistry): Promise<CodegenReport>;
+//#endregion
+//#region src/build.d.ts
+interface BuildReport {
+  processing: ProcessingReport;
+  codegen: CodegenReport;
+}
+declare function runBuild(projectRoot: string, registry?: ServerPluginRegistry): Promise<BuildReport>;
+//#endregion
+//#region src/check.d.ts
+/** One machine-readable check finding (the `--json` failure-list shape, M9). */
+interface CheckFinding {
+  /** The failure category. */
+  kind: 'validation' | 'proxy-missing' | 'proxy-unresolvable' | 'proxy-orphaned' | 'module-missing' | 'module-out-of-sync' | 'module-stray' | 'module-regeneration-failed' | 'unreachable-asset' | 'raw-hash-drift';
+  message: string;
+  /** The asset the finding concerns, where applicable. */
+  assetId?: string;
+  /** The manifest whose generated module the finding concerns, where applicable. */
+  manifest?: string;
+  /** The concrete file (proxy or generated module), where applicable. */
+  fileName?: string;
+}
+/** The human rendering of a finding — `[assetId] message`, as `fundus check` prints it. */
+declare function formatCheckFinding(finding: CheckFinding): string;
+interface CheckReport {
+  /** Hard failures — always fatal. */
+  errors: CheckFinding[];
+  /** Advisory findings — fatal unless the caller allows warnings. */
+  warnings: CheckFinding[];
+  assetCount: number;
+  manifestCount: number;
+}
+declare function runCheck(projectRoot: string, registry?: ServerPluginRegistry): Promise<CheckReport>;
+//#endregion
+//#region src/operations.d.ts
+/** A CLI-facing asset change: parameter patch and/or explicit membership set. */
+interface AssetChangeOptions {
+  /** Shallow top-level parameter patch (see mergeParameterPatch). */
+  parametersPatch?: unknown;
+  /** Replacement for the explicit manifest membership set (declarative). */
+  manifests?: string[];
+}
+declare class FundusOperations {
+  #private;
+  constructor(config: ResolvedFundusConfig, registry?: ServerPluginRegistry);
+  get config(): ResolvedFundusConfig;
+  get store(): LibraryStore;
+  /** Read-only state snapshot (no processing). */
+  state(): Promise<FundusStateDto>;
+  /**
+   * Ingest an upload: store the raw file + record, then let the owning
+   * plugin's optional `seedIngestParameters` derive better starting
+   * parameters from the stored raw file (slices: insets from the image
+   * dimensions, pixel ratio from the file name — the schema default can't
+   * know either). The CLI additionally applies a parameter patch and/or an
+   * explicit membership set in the same operation; a failing application
+   * rolls the whole ingest back, so a failed ingest leaves nothing behind.
+   */
+  ingest(options: IngestOptions & AssetChangeOptions): Promise<FundusStateDto>;
+  /** Apply a PATCH body: parameters and/or manifests and/or a rename — in that order. */
+  patchAsset(id: string, body: PatchAssetRequestDto): Promise<FundusStateDto>;
+  moveAsset(id: string, folder: string): Promise<FundusStateDto>;
+  /** Move a selected asset set as one editor action and roll back on any failure. */
+  moveAssets(assetIds: string[], folder: string): Promise<FundusStateDto>;
+  createFolder(path: string): Promise<FundusStateDto>;
+  renameFolder(path: string, newName: string): Promise<FundusStateDto>;
+  moveFolder(path: string, parent: string): Promise<FundusStateDto>;
+  deleteFolder(path: string): Promise<FundusStateDto>;
+  /**
+   * CLI-facing asset update (M7): shallow-merge a parameter patch and/or
+   * replace the explicit manifest membership — validating the *result* before
+   * anything is persisted, so a change that would leave the library invalid
+   * (dangling or cyclic reference, unknown manifest, invalid parameters) is
+   * rejected with nothing written. The REST `patchAsset` keeps the editor's
+   * lenient replace semantics.
+   */
+  setAsset(id: string, changes: AssetChangeOptions): Promise<FundusStateDto>;
+  /**
+   * CLI-facing rename (M7): rejects a rename that would break references —
+   * a referrer keeps pointing at the old id, so renaming a referenced asset
+   * introduces dangling-reference errors. Update the referrers first.
+   */
+  renameAsset(id: string, newId: string): Promise<FundusStateDto>;
+  /**
+   * Delete an asset: the record, its raw file, and its proxies. With
+   * `failOnIntroducedIssues` (the CLI), a delete that would break references
+   * (the asset is a reference target) is rejected before anything —
+   * including the raw file — is removed; the REST route stays lenient.
+   */
+  deleteAsset(id: string, options?: {
+    failOnIntroducedIssues?: boolean;
+  }): Promise<FundusStateDto>;
+  /** Delete a selected asset set as one lenient editor mutation. */
+  deleteAssets(assetIds: string[]): Promise<FundusStateDto>;
+  createManifest(name: string): Promise<FundusStateDto>;
+  setManifestAppearance(name: string, appearance: {
+    color?: string | null;
+    emoji?: string | null;
+  }): Promise<FundusStateDto>;
+  /** Apply a PATCH body: appearance fields and/or a rename — in that order. */
+  patchManifest(name: string, body: PatchManifestRequestDto): Promise<FundusStateDto>;
+  /**
+   * Rename a manifest: rewrites every asset's membership and replaces the
+   * generated module (the old one is pruned as a stray). Host code importing
+   * the module must be updated by hand — both the file name and the exported
+   * const change with the manifest name.
+   */
+  renameManifest(name: string, newName: string): Promise<FundusStateDto>;
+  deleteManifest(name: string): Promise<FundusStateDto>;
+}
+//#endregion
+//#region src/start.d.ts
+declare function runStart(projectRoot: string): Promise<void>;
+//#endregion
+export { type AssetChangeOptions, type AssetProxyInfo, type BuildReport, type CheckFinding, type CheckReport, type CodegenReport, FundusOperations, type IngestOptions, LibraryStore, type ProcessingReport, type ProxyOutputInfo, type ResolvedAudioPluginConfig, type ResolvedFundusConfig, type ResolvedPresetPluginConfig, type ResolvedVideoPluginConfig, deliveredAssetIds, expectedProxyFileName, expectedProxyRelativePath, ffmpegBinaryPath, formatCheckFinding, generateManifestModules, isProxyFileName, loadConfig, processAssets, readProxyOutputInfo, resolveConfig, runBuild, runCheck, runStart, runToolchainBinary };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { C as runToolchainBinary, S as ffmpegBinaryPath, T as resolveConfig, a as deliveredAssetIds, c as isProxyFileName, d as readProxyOutputInfo, l as processAssets, m as generateManifestModules, n as LibraryStore, o as expectedProxyFileName, s as expectedProxyRelativePath, t as FundusOperations, w as loadConfig } from "./operations-DYM-5KVl.js";
+import { n as formatCheckFinding, r as runCheck, t as runBuild } from "./build-CZYFLLvl.js";
+import { t as runStart } from "./start-Bhnqt9Dc.js";
+export { FundusOperations, LibraryStore, deliveredAssetIds, expectedProxyFileName, expectedProxyRelativePath, ffmpegBinaryPath, formatCheckFinding, generateManifestModules, isProxyFileName, loadConfig, processAssets, readProxyOutputInfo, resolveConfig, runBuild, runCheck, runStart, runToolchainBinary };