fundus 0.0.4 → 0.2.0

package/dist/server/check.d.ts

@@ -1,8 +1,10 @@
+import { type Library, type ValidationIssueDto } from '../core/index.js';
+import { type RawClassification } from './raw-reconciliation.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 /** One machine-readable check finding (the `--json` failure-list shape, M9). */
 export 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';
+    kind: 'validation' | 'proxy-missing' | 'proxy-unresolvable' | 'proxy-orphaned' | 'module-missing' | 'module-out-of-sync' | 'module-stray' | 'module-regeneration-failed' | 'unreachable-asset' | 'raw-hash-drift' | 'raw-type-incompatible' | 'raw-scan-incomplete' | 'raw-unmanaged';
     message: string;
     /** The asset the finding concerns, where applicable. */
     assetId?: string;
@@ -22,3 +24,5 @@ export interface CheckReport {
     manifestCount: number;
 }
 export declare function runCheck(projectRoot: string, registry?: ServerPluginRegistry): Promise<CheckReport>;
+/** Pure expansion of a raw classification into canonical hard check findings. */
+export declare function rawCheckFindings(library: Library, raw: RawClassification, registry: ServerPluginRegistry, validationIssues: ValidationIssueDto[]): CheckFinding[];

package/dist/server/check.js

@@ -2,16 +2,17 @@
  * `fundus check` — the verify-only CI gate: no writes, ever. It
  * fails when the library does not validate, when a committed proxy is stale,
  * missing, or orphaned, or when a generated manifest module differs from an
- * in-memory regeneration. Warnings (unreachable asset, raw-hash drift) are
+ * in-memory regeneration. Warnings (unreachable assets) are
  * treated as errors unless `--allow-warnings` downgrades them — errors are
  * never downgradable.
  */
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { collectAllReferences, compareCodeUnits, computeLibraryMembership, rawFileNameOfPath } from '../core/index.js';
+import { collectAllReferences, compareCodeUnits, computeLibraryMembership, rawFileNameOfPath, typesForFileName } from '../core/index.js';
 import { loadConfig } from './config-loader.js';
-import { LibraryStore, sha256Hex } from './library-store.js';
+import { LibraryStore } from './library-store.js';
+import { classifyRawDirectory } from './raw-reconciliation.js';
 import { buildManifestEntries, manifestModuleFileName, renderManifestModule, strayGeneratedModuleNames } from './codegen.js';
 import { descriptorsByType, serverPluginsByType } from './plugins.js';
 import { deliveredAssetIds, expectedProxyRelativePath, isProxyFileName, readCurrentProxy } from './processing/processor.js';
@@ -32,13 +33,21 @@ export async function runCheck(projectRoot, registry = serverPluginsByType) {
     };
     // 1. Library validation (structure, parameters, raw pointers, references).
     const issues = await store.validate(library);
+    const validationKeys = new Set();
     for (const issue of issues) {
+        const key = `${issue.assetId ?? ''}|${issue.message}`;
+        if (validationKeys.has(key))
+            continue;
+        validationKeys.add(key);
         report.errors.push({
             kind: 'validation',
             message: issue.message,
             ...(issue.assetId !== undefined ? { assetId: issue.assetId } : {})
         });
     }
+    const descriptors = Object.values(registry).map((plugin) => plugin.descriptor);
+    const raw = await classifyRawDirectory(config.rawDir, library, (path) => typesForFileName(path, descriptors).length > 0);
+    report.errors.push(...rawCheckFindings(library, raw, registry, issues));
     // 2. Proxies: every delivered asset's expected proxy exists (staleness is a
     // name check), and the proxy directory holds no orphans.
     const delivered = deliveredAssetIds(library, registry);
@@ -93,15 +102,80 @@ export async function runCheck(projectRoot, registry = serverPluginsByType) {
     // 3. Generated manifest modules must be byte-identical to an in-memory
     // regeneration. Only meaningful when validation passed and every proxy
     // exists — otherwise regeneration is impossible and already reported.
-    if (issues.length === 0 && proxiesComplete) {
+    if (report.errors.length === 0 && proxiesComplete) {
         await checkGeneratedModules(report, library, config, proxies, registry);
         await checkStrayModules(report, library, config);
     }
-    // 4. Warnings: unreachable assets, raw-hash drift.
+    // 4. Warnings: unreachable assets only. Raw drift is always a hard CI failure.
     collectUnreachableAssets(report, library, delivered);
-    await collectRawHashDrift(report, library, config);
+    report.errors.sort((left, right) => compareCodeUnits(`${left.fileName ?? ''}|${left.assetId ?? ''}|${left.kind}|${left.message}`, `${right.fileName ?? ''}|${right.assetId ?? ''}|${right.kind}|${right.message}`));
+    report.warnings.sort((left, right) => compareCodeUnits(`${left.assetId ?? ''}|${left.kind}|${left.message}`, `${right.assetId ?? ''}|${right.kind}|${right.message}`));
     return report;
 }
+/** Pure expansion of a raw classification into canonical hard check findings. */
+export function rawCheckFindings(library, raw, registry, validationIssues) {
+    const findings = [];
+    const descriptors = Object.values(registry).map((plugin) => plugin.descriptor);
+    const compatibleTypes = (path) => typesForFileName(path, descriptors);
+    for (const diagnostic of raw.diagnostics) {
+        findings.push({
+            kind: 'raw-scan-incomplete',
+            message: diagnostic.reason,
+            ...(diagnostic.path ? { fileName: diagnostic.path } : {})
+        });
+    }
+    const edited = new Map(raw.edited.map((entry) => [entry.assetId, entry]));
+    for (const assetId of raw.unchangedAssetIds) {
+        const record = library.assets[assetId];
+        if (!compatibleTypes(record.raw).includes(record.type)) {
+            findings.push({
+                kind: 'raw-type-incompatible',
+                message: `Raw file "${record.raw}" is not compatible with its current ${record.type} type — ` +
+                    'open or refocus the editor and choose a compatible type.',
+                assetId,
+                fileName: record.raw
+            });
+        }
+    }
+    for (const entry of edited.values()) {
+        findings.push({
+            kind: 'raw-hash-drift',
+            message: `Raw file "${entry.path}" changed outside Fundus — open or refocus the editor ` +
+                'to process or dismiss the edited ingestion item.',
+            assetId: entry.assetId,
+            fileName: entry.path
+        });
+    }
+    const missingAssetIds = new Set(validationIssues
+        .filter((issue) => issue.message.includes('is missing from the raw directory'))
+        .map((issue) => issue.assetId));
+    for (const move of raw.moves) {
+        if (!missingAssetIds.has(move.assetId)) {
+            findings.push({
+                kind: 'validation',
+                message: `Raw file "${move.from}" is missing from the raw directory.`,
+                assetId: move.assetId
+            });
+        }
+    }
+    for (const file of [...raw.unmanaged, ...raw.moves]) {
+        findings.push({
+            kind: 'raw-unmanaged',
+            message: `Raw file "${file.path}" is not managed by Fundus — open or refocus the editor and ` +
+                'resolve its ingestion queue item.',
+            fileName: file.path
+        });
+    }
+    for (const blocker of raw.blockers) {
+        findings.push({
+            kind: 'raw-unmanaged',
+            message: `Unsupported raw entry "${blocker.path}": ${blocker.reason} Rename or remove it externally.`,
+            fileName: blocker.path,
+            ...(blocker.assetId ? { assetId: blocker.assetId } : {})
+        });
+    }
+    return findings;
+}
 async function checkGeneratedModules(report, library, config, proxies, registry) {
     const referencesByAsset = collectAllReferences(library, descriptorsByType(registry));
     const membershipByManifest = computeLibraryMembership(library, referencesByAsset);
@@ -175,25 +249,3 @@ function collectUnreachableAssets(report, library, delivered) {
         }
     }
 }
-/**
- * Raw-hash drift: a raw file replaced on disk while the library still pins the
- * old content hash. The proxy name derives from the *recorded* hash, so the
- * name check alone would keep passing while the delivered pixels are outdated.
- */
-async function collectRawHashDrift(report, library, config) {
-    for (const [assetId, record] of Object.entries(library.assets)) {
-        const rawPath = join(config.rawDir, record.raw);
-        if (!existsSync(rawPath))
-            continue; // A missing raw file is a validation error already.
-        const currentHash = sha256Hex(new Uint8Array(await readFile(rawPath)));
-        if (currentHash !== record.rawHash) {
-            report.warnings.push({
-                kind: 'raw-hash-drift',
-                message: `Raw file "${record.raw}" changed since it was ingested (hash drift) — ` +
-                    `re-ingest or update it through the editor, then run \`fundus build\`.`,
-                assetId,
-                fileName: record.raw
-            });
-        }
-    }
-}

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

@@ -1,9 +1,10 @@
 export declare const STATE_HELP = "fundus state \u2014 the full project state in one document\n\nUsage: fundus state [--json]\n\nThe agent's one-stop overview: every asset (type, raw file, parameters,\nexplicit + passive manifest memberships, proxy status, reference edges,\nwarnings), every manifest (members, delivered bytes), library-level\nvalidation issues, and the available preset names per asset type.\n\nFlags:\n  --json   print {\"ok\": true, \"state\": <FundusStateDto>} on stdout\n  --help   this help\n\nRead-only: nothing is processed or written.\n\nExample:\n  fundus state --json | jq '.state.assets[].id'\n";
 export declare function runStateCommand(argumentList: string[]): Promise<void>;
-export declare const ASSET_HELP = "fundus asset \u2014 inspect and mutate assets\n\nUsage: fundus asset <subcommand> \u2026\n\nEvery mutation runs the full editor autosave chain: write library \u2192\nprocess affected assets \u2192 regenerate manifest modules. There is no\nseparate apply/sync step. All subcommands accept --json (a single JSON\ndocument on stdout) and --help.\n\nSubcommands:\n  list      list assets (--manifest, --type, --warnings-only)\n  show      one asset in detail\n  ingest    copy a file into the raw dir as a typed asset\n  set       merge parameters and/or replace manifest membership\n  rename    rename an asset id\n  move      move an asset to a folder or root\n  delete    delete an asset (record, raw file, proxies)\n\nRun `fundus asset <subcommand> --help` for the focused page (flags,\nsemantics, an example) \u2014 e.g. `fundus asset set --help` documents the\n--parameters merge rules.\n";
+export declare const ASSET_HELP = "fundus asset \u2014 inspect and mutate assets\n\nUsage: fundus asset <subcommand> \u2026\n\nEvery mutation runs the full editor autosave chain: write library \u2192\nprocess affected assets \u2192 regenerate manifest modules. There is no\nseparate apply/sync step. All subcommands accept --json (a single JSON\ndocument on stdout) and --help.\n\nSubcommands:\n  list      list assets (--manifest, --type, --warnings-only)\n  show      one asset in detail\n  ingest    copy a file into the raw dir as a typed asset\n  replace   replace an asset's raw file while preserving its metadata\n  set       merge parameters and/or replace manifest membership\n  rename    rename an asset id\n  move      move an asset to a folder or root\n  delete    delete an asset (record, raw file, proxies)\n\nRun `fundus asset <subcommand> --help` for the focused page (flags,\nsemantics, an example) \u2014 e.g. `fundus asset set --help` documents the\n--parameters merge rules.\n";
 export declare const ASSET_LIST_HELP: string;
 export declare const ASSET_SHOW_HELP = "fundus asset show \u2014 one asset in detail\n\nUsage: fundus asset show <id> [--json]\n\nPrints the asset's raw file, content hash, parameters, explicit +\npassive manifest memberships, proxy status, reference edges (outgoing\nand incoming), and warnings.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>}\n  --help   this help\n\nRead-only: nothing is processed or written.\n\nExample:\n  fundus asset show navigationPanel --json\n";
 export declare const ASSET_INGEST_HELP: string;
+export declare const ASSET_REPLACE_HELP = "fundus asset replace \u2014 replace an asset's raw file\n\nUsage: fundus asset replace <id> <file> [--json]\n\nReplaces the stored raw file and content hash while preserving the asset's\nid, type, folder, parameters, references, and manifest memberships. The new\nfile must have an extension accepted by the existing asset type. Runs the full\nautosave chain, so delivered assets are reprocessed and manifests regenerated.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset replace navigationPanel ./exports/navigation_panel_v2.png --json\n";
 export declare const ASSET_SET_HELP = "fundus asset set \u2014 update an asset's parameters and/or memberships\n\nUsage: fundus asset set <id> [--parameters <json>] [--manifests <a,b>] [--json]\n\nAt least one of --parameters/--manifests is required. Runs the full\nautosave chain (write library \u2192 process \u2192 regenerate manifest modules).\n\nFlags:\n  --parameters <json>  SHALLOW MERGE at the top level onto the current\n                       parameters, then plugin validation:\n                         {\"preset\": \"webp-hq\"}        sets one field,\n                                                      keeps the others\n                         {\"chromaKey\": {\u2026}}           replaces the whole\n                                                      chromaKey object\n                         {\"mask\": null}               clears an optional\n                                                      field\n                         {\"mask\": {\"$asset\": \"someImage\"}}\n                                                      sets an asset\n                                                      reference\n  --manifests <a,b>    REPLACES the explicit membership set (declarative,\n                       idempotent); --manifests \"\" clears it\n  --json               print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help               this help\n\nThe mutation is validated first and rejected (exit 1, nothing written)\nif it would leave the library invalid \u2014 e.g. a reference to a missing\nasset, a reference cycle, or an unknown manifest name. Ingest reference\ntargets before pointing at them.\n\nExample:\n  fundus asset set characterIdle \\\n    --parameters '{\"mask\": {\"$asset\": \"characterIdleMask\"}}' --json\n";
 export declare const ASSET_RENAME_HELP = "fundus asset rename \u2014 rename an asset id\n\nUsage: fundus asset rename <id> <newId> [--json]\n\nRenames the asset's id (the raw file keeps its name \u2014 ids are the\nstable key) and re-hashes its proxy under the new id via the autosave\nchain. Fails if another asset references <id> \u2014 update the referrers\nfirst \u2014 or if <newId> is taken or invalid.\n\nFlags:\n  --json   print {\"ok\": true, \"asset\": <AssetStateDto>, \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset rename sidebarPanel navigationPanel --json\n";
 export declare const ASSET_DELETE_HELP = "fundus asset delete \u2014 delete an asset\n\nUsage: fundus asset delete <id> [--json]\n\nDeletes the library record, its raw file, and its proxies, then\nregenerates the affected manifest modules. Fails if another asset\nreferences it \u2014 remove the references first.\n\nFlags:\n  --json   print {\"ok\": true, \"deletedAssetId\": \"<id>\", \"issues\": [\u2026]}\n  --help   this help\n\nExample:\n  fundus asset delete obsoleteBanner --json\n";
@@ -21,5 +22,5 @@ export declare const MANIFEST_PALETTE_HELP = "fundus manifest palette \u2014 lis
 export declare function runManifestCommand(argumentList: string[]): Promise<void>;
 export declare const BUILD_HELP = "fundus build \u2014 run the headless pipeline\n\nUsage: fundus build [--json]\n\nValidates the library, processes every stale or missing proxy, prunes\norphaned proxies, and regenerates all manifest modules. Deterministic\nand idempotent: a second run on an unchanged project processes nothing\nand rewrites byte-identical modules. Run it in CI, postinstall, or\nbefore the host build; commit the result.\n\nFlags:\n  --json   print {\"ok\": true, \"processed\": [\u2026], \"upToDate\": [\u2026],\n           \"prunedProxies\": [\u2026], \"modulesWritten\": [\u2026],\n           \"modulesRemoved\": [\u2026]} \u2014 asset ids for processing,\n           file names for pruning/codegen\n  --help   this help\n\nA validation failure processes nothing and exits 1 (with --json:\n{\"error\": {\"message\": \u2026}}).\n\nExample:\n  fundus build --json | jq '.processed'\n";
 export declare function runBuildCommand(argumentList: string[]): Promise<void>;
-export declare const CHECK_HELP = "fundus check \u2014 verify the committed state (the CI gate)\n\nUsage: fundus check [--allow-warnings] [--json]\n\nVerify-only, no writes: the library must validate, every delivered\nasset's committed proxy must exist under its expected name (staleness\nis a name check), the proxy directory must hold no orphans, and every\ngenerated manifest module must be byte-identical to an in-memory\nregeneration. Warnings (unreachable asset, raw-hash drift) fail the\ncheck too unless --allow-warnings downgrades them; errors never\ndowngrade.\n\nFlags:\n  --allow-warnings   exit 0 despite warnings (errors still fail)\n  --json             print one report document:\n                     {\"ok\": <pass/fail>, \"assetCount\": \u2026, \"manifestCount\": \u2026,\n                      \"errors\": [<finding>, \u2026], \"warnings\": [<finding>, \u2026]}\n                     where a finding is {\"kind\", \"message\"} plus\n                     \"assetId\" / \"manifest\" / \"fileName\" where applicable\n  --help             this help\n\nExit codes: 0 = clean (or warnings allowed), 1 = failed. A failure to\neven run the check (e.g. no fundus.config.ts) exits 1 with the usual\n{\"error\": {\"message\": \u2026}} envelope under --json.\n\nExample:\n  fundus check --json | jq '.errors[].kind'\n";
+export declare const CHECK_HELP = "fundus check \u2014 verify the committed state (the CI gate)\n\nUsage: fundus check [--allow-warnings] [--json]\n\nVerify-only, no writes: the library must validate, every delivered\nasset's committed proxy must exist under its expected name (staleness\nis a name check), the proxy directory must hold no orphans, and every\ngenerated manifest module must be byte-identical to an in-memory\nregeneration. Warnings (such as unreachable assets) fail the check\nunless --allow-warnings downgrades them. New, missing, edited, or\ninvalid entries in the raw directory are hard errors:\nopen or refocus the Fundus editor and resolve its ingestion queue.\nRaw-file errors never downgrade.\n\nFlags:\n  --allow-warnings   exit 0 despite warnings (errors still fail)\n  --json             print one report document:\n                     {\"ok\": <pass/fail>, \"assetCount\": \u2026, \"manifestCount\": \u2026,\n                      \"errors\": [<finding>, \u2026], \"warnings\": [<finding>, \u2026]}\n                     where a finding is {\"kind\", \"message\"} plus\n                     \"assetId\" / \"manifest\" / \"fileName\" where applicable\n  --help             this help\n\nExit codes: 0 = clean (or warnings allowed), 1 = failed. A failure to\neven run the check (e.g. no fundus.config.ts) exits 1 with the usual\n{\"error\": {\"message\": \u2026}} envelope under --json.\n\nExample:\n  fundus check --json | jq '.errors[].kind'\n";
 export declare function runCheckCommand(argumentList: string[]): Promise<void>;

package/dist/server/cli-commands.js

@@ -202,6 +202,7 @@ Subcommands:
   list      list assets (--manifest, --type, --warnings-only)
   show      one asset in detail
   ingest    copy a file into the raw dir as a typed asset
+  replace   replace an asset's raw file while preserving its metadata
   set       merge parameters and/or replace manifest membership
   rename    rename an asset id
   move      move an asset to a folder or root
@@ -285,6 +286,22 @@ Example:
   fundus asset ingest ./exports/navigation_panel@2x.png --type slice \\
     --manifests mainCatalog --json
 `;
+export const ASSET_REPLACE_HELP = `fundus asset replace — replace an asset's raw file
+
+Usage: fundus asset replace <id> <file> [--json]
+
+Replaces the stored raw file and content hash while preserving the asset's
+id, type, folder, parameters, references, and manifest memberships. The new
+file must have an extension accepted by the existing asset type. Runs the full
+autosave chain, so delivered assets are reprocessed and manifests regenerated.
+
+Flags:
+  --json   print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help   this help
+
+Example:
+  fundus asset replace navigationPanel ./exports/navigation_panel_v2.png --json
+`;
 export const ASSET_SET_HELP = `fundus asset set — update an asset's parameters and/or memberships
 
 Usage: fundus asset set <id> [--parameters <json>] [--manifests <a,b>] [--json]
@@ -368,6 +385,7 @@ const ASSET_SUBCOMMAND_HELP = {
     list: ASSET_LIST_HELP,
     show: ASSET_SHOW_HELP,
     ingest: ASSET_INGEST_HELP,
+    replace: ASSET_REPLACE_HELP,
     set: ASSET_SET_HELP,
     rename: ASSET_RENAME_HELP,
     move: ASSET_MOVE_HELP,
@@ -490,6 +508,27 @@ async function runAssetIngest(argumentList) {
     }
     printMutationResult(`Ingested "${fileName}" as ${type} asset "${id}".`, asset, state);
 }
+async function runAssetReplace(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus asset replace');
+    const [id, filePath] = requirePositionals(parsed, ['<id>', '<file>'], 'fundus asset replace');
+    const absolutePath = resolve(process.cwd(), filePath);
+    let bytes;
+    try {
+        bytes = new Uint8Array(await readFile(absolutePath));
+    }
+    catch {
+        throw new Error(`Cannot read file "${filePath}".`);
+    }
+    const fileName = basename(absolutePath);
+    const operations = await createOperations();
+    const state = await operations.replaceRawFile(id, { fileName, bytes });
+    const asset = assetById(state, id);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, asset, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Replaced raw file for asset "${id}" with "${fileName}".`, asset, state);
+}
 async function runAssetSet(argumentList) {
     const parsed = parseArguments(argumentList, { ...COMMON_FLAGS, parameters: { takesValue: true }, manifests: { takesValue: true } }, 'fundus asset set');
     const [id] = requirePositionals(parsed, ['<id>'], 'fundus asset set');
@@ -554,7 +593,7 @@ export async function runAssetCommand(argumentList) {
     if (subcommand === undefined || subcommand === '--help') {
         console.log(ASSET_HELP);
         if (subcommand === undefined) {
-            throw new CliUsageError('`fundus asset` needs a subcommand: list, show, ingest, set, rename, move, delete.');
+            throw new CliUsageError('`fundus asset` needs a subcommand: list, show, ingest, replace, set, rename, move, delete.');
         }
         return;
     }
@@ -570,6 +609,8 @@ export async function runAssetCommand(argumentList) {
             return runAssetShow(rest);
         case 'ingest':
             return runAssetIngest(rest);
+        case 'replace':
+            return runAssetReplace(rest);
         case 'set':
             return runAssetSet(rest);
         case 'rename':
@@ -1116,9 +1157,11 @@ Verify-only, no writes: the library must validate, every delivered
 asset's committed proxy must exist under its expected name (staleness
 is a name check), the proxy directory must hold no orphans, and every
 generated manifest module must be byte-identical to an in-memory
-regeneration. Warnings (unreachable asset, raw-hash drift) fail the
-check too unless --allow-warnings downgrades them; errors never
-downgrade.
+regeneration. Warnings (such as unreachable assets) fail the check
+unless --allow-warnings downgrades them. New, missing, edited, or
+invalid entries in the raw directory are hard errors:
+open or refocus the Fundus editor and resolve its ingestion queue.
+Raw-file errors never downgrade.
 
 Flags:
   --allow-warnings   exit 0 despite warnings (errors still fail)

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

@@ -1,3 +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 const INIT_HELP = "fundus init \u2014 create a Fundus configuration file\n\nUsage: fundus init [--json]\n\nCreates a template fundus.config.ts and a library with a default \"main\"\nmanifest in the current directory. The command refuses to initialize a project\nthat already has a Fundus 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

@@ -1,5 +1,6 @@
-import { writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { lstat, mkdir, unlink, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { createEmptyLibrary, serializeLibrary } from '../core/index.js';
 import { parseArguments, printJsonDocument, requirePositionals } from './cli-io.js';
 export const FUNDUS_CONFIG_TEMPLATE = `import { defineConfig } from 'fundus/config';
 
@@ -15,8 +16,9 @@ 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.
+Creates a template fundus.config.ts and a library with a default "main"
+manifest in the current directory. The command refuses to initialize a project
+that already has a Fundus configuration file.
 
 Flags:
   --json   print {"ok": true, "path": "fundus.config.ts"} on stdout
@@ -45,9 +47,40 @@ export async function runInitCommand(argumentList) {
         }
         throw new Error(`Cannot create fundus.config.ts: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
+    const libraryPath = resolve(process.cwd(), 'assets/fundus.library.json');
+    const rawPath = resolve(process.cwd(), 'assets/raw');
+    const library = createEmptyLibrary();
+    library.manifests.main = {};
+    try {
+        await mkdir(dirname(libraryPath), { recursive: true });
+        await writeFile(libraryPath, serializeLibrary(library), { encoding: 'utf8', flag: 'wx' });
+    }
+    catch (cause) {
+        // The config was created by this invocation. Remove it so a failed
+        // library scaffold does not make the project look initialized.
+        await unlink(configPath).catch(() => { });
+        if (cause.code === 'EEXIST') {
+            throw new Error(`assets/fundus.library.json already exists in ${process.cwd()}.`);
+        }
+        throw new Error(`Cannot create assets/fundus.library.json: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    try {
+        await mkdir(rawPath, { recursive: true });
+        const rawStat = await lstat(rawPath);
+        if (!rawStat.isDirectory() || rawStat.isSymbolicLink()) {
+            throw new Error('the path exists but is not a regular directory');
+        }
+    }
+    catch (cause) {
+        // Only the two files written exclusively by this invocation are rolled
+        // back. Existing paths and directories are never removed recursively.
+        await unlink(libraryPath).catch(() => { });
+        await unlink(configPath).catch(() => { });
+        throw new Error(`Cannot create assets/raw directory: ${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.');
+    console.log('Created fundus.config.ts and default "main" manifest.');
 }

package/dist/server/http.js

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { lstat, readFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
 import { assertSafeRelativeFilePath } from './library-store.js';
 const CONTENT_TYPES = {
@@ -71,6 +71,10 @@ export async function serveFundusFile(config, kind, fileName, request) {
     if (!existsSync(filePath)) {
         return errorResponse(new Error(`File "${fileName}" not found.`), 404);
     }
+    const fileStat = await lstat(filePath);
+    if (!fileStat.isFile() || fileStat.isSymbolicLink()) {
+        return errorResponse(new Error(`File "${fileName}" is not a regular file.`), 400);
+    }
     const bytes = new Uint8Array(await readFile(filePath));
     const size = bytes.byteLength;
     const headers = {

package/dist/server/index.d.ts

@@ -1,7 +1,7 @@
 export type { ResolvedFundusConfig, ResolvedPresetPluginConfig, ResolvedVideoPluginConfig, ResolvedAudioPluginConfig } from './config-loader.js';
 export { loadConfig, resolveConfig } from './config-loader.js';
 export { LibraryStore } from './library-store.js';
-export type { IngestOptions } from './library-store.js';
+export type { IngestOptions, ReplaceRawFileOptions } from './library-store.js';
 export type { AssetProxyInfo, ProxyOutputInfo, ProcessingReport } from './processing/processor.js';
 export { processAssets, expectedProxyFileName, expectedProxyRelativePath, deliveredAssetIds, isProxyFileName, readProxyOutputInfo } from './processing/processor.js';
 export { ffmpegBinaryPath, runToolchainBinary } from './processing/ffmpeg.js';

package/dist/server/library-store.d.ts

@@ -23,6 +23,11 @@ export interface IngestOptions {
     /** Registered destination folder; empty string means the implicit root. */
     folder?: string;
 }
+export interface ReplaceRawFileOptions {
+    /** Original file name of the replacement (sanitized before storing). */
+    fileName: string;
+    bytes: Uint8Array;
+}
 export declare class LibraryStore {
     #private;
     constructor(config: ResolvedFundusConfig, registry?: ServerPluginRegistry);
@@ -31,12 +36,30 @@ export declare class LibraryStore {
     read(): Promise<Library>;
     /** Deterministically serialize + write the library file. */
     write(library: Library): Promise<void>;
+    /**
+     * Candidate-first source transaction used for externally-owned raw files.
+     * The callback runs after entering the store queue and may scan the raw tree;
+     * Fundus writes only the library candidate and never touches external bytes.
+     */
+    transactCandidate<T>(change: (candidate: Library, current: Library) => Promise<T>): Promise<{
+        library: Library;
+        value: T;
+        changed: boolean;
+    }>;
+    /** Remove derived proxies after a source record was externally deleted/moved. */
+    deleteProxiesOf(assetId: string): 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 one asset's raw file while preserving its identity and authored
+     * metadata. The replacement stays in the current folder, receives a safe
+     * non-colliding name, and must be accepted by the asset's existing type.
+     */
+    replaceRawFile(id: string, options: ReplaceRawFileOptions): 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). */

package/dist/server/library-store.js

@@ -8,7 +8,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises';
 import { dirname, extname, join } from 'node:path';
 import { createHash } from 'node:crypto';
-import { assetIdError, collectAllReferences, createEmptyLibrary, folderNameError, folderNameOf, folderOfRawPath, folderPathError, isFolderOrDescendant, joinFolderPath, manifestColorError, manifestEmojiError, parseLibrary, referenceErrors, normalizeFolderPath, parentFolderPath, portableFolderPathKey, rawFileNameOfPath, replaceFolderPrefix, manifestNameError, serializeLibrary } from '../core/index.js';
+import { assetIdError, collectAllReferences, createEmptyLibrary, folderNameError, folderNameOf, folderOfRawPath, folderPathError, isFolderOrDescendant, joinFolderPath, manifestColorError, manifestEmojiError, parseLibrary, referenceErrors, normalizeFolderPath, parentFolderPath, portableFolderPathKey, rawFilePathError, rawFileNameOfPath, replaceFolderPrefix, manifestNameError, serializeLibrary } from '../core/index.js';
 import { manifestModuleFileName } from './codegen.js';
 import { descriptorsByType, serverPluginForType, serverPluginsByType } from './plugins.js';
 import { isProxyFileNameFor } from './processing/processor.js';
@@ -22,19 +22,9 @@ export function assertSafeFileName(fileName) {
 }
 /** Validate a persisted/served file path without allowing traversal outside its root. */
 export function assertSafeRelativeFilePath(filePath) {
-    if (filePath.startsWith('/') || filePath.endsWith('/') || filePath.includes('\\')) {
-        throw new Error(`Unsafe file path "${filePath}".`);
-    }
-    const segments = filePath.split('/');
-    if (segments.length === 0)
-        throw new Error(`Unsafe file path "${filePath}".`);
-    assertSafeFileName(segments.at(-1) ?? '');
-    const folder = segments.slice(0, -1).join('/');
-    if (folder !== '') {
-        const problem = folderPathError(folder);
-        if (problem)
-            throw new Error(problem);
-    }
+    const problem = rawFilePathError(filePath);
+    if (problem)
+        throw new Error(problem);
 }
 /**
  * Turn an arbitrary uploaded file name (spaces, umlauts, parentheses, nested
@@ -97,6 +87,27 @@ export class LibraryStore {
         await writeFile(temporaryPath, serializeLibrary(library));
         await rename(temporaryPath, this.#config.library);
     }
+    /**
+     * Candidate-first source transaction used for externally-owned raw files.
+     * The callback runs after entering the store queue and may scan the raw tree;
+     * Fundus writes only the library candidate and never touches external bytes.
+     */
+    async transactCandidate(change) {
+        return this.#enqueue(async () => {
+            const current = await this.read();
+            const before = serializeLibrary(current);
+            const candidate = structuredClone(current);
+            const value = await change(candidate, current);
+            const changed = serializeLibrary(candidate) !== before;
+            if (changed)
+                await this.write(candidate);
+            return { library: candidate, value, changed };
+        });
+    }
+    /** Remove derived proxies after a source record was externally deleted/moved. */
+    async deleteProxiesOf(assetId) {
+        await this.#deleteProxiesOf(assetId);
+    }
     /**
      * 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
@@ -136,6 +147,63 @@ export class LibraryStore {
         await this.write(library);
         return library;
     }
+    /**
+     * Replace one asset's raw file while preserving its identity and authored
+     * metadata. The replacement stays in the current folder, receives a safe
+     * non-colliding name, and must be accepted by the asset's existing type.
+     */
+    async replaceRawFile(id, options) {
+        return this.#enqueue(() => this.#replaceRawFile(id, options));
+    }
+    async #replaceRawFile(id, options) {
+        const library = await this.read();
+        const record = this.#requireAsset(library, id);
+        const sanitizedName = sanitizeFileName(options.fileName);
+        const extension = extname(sanitizedName).slice(1).toLowerCase();
+        const plugin = serverPluginForType(record.type, this.#registry);
+        if (!plugin.descriptor.accepts.includes(extension)) {
+            throw new Error(`The ${record.type} type does not accept ".${extension}" files (accepts: ${plugin.descriptor.accepts.join(', ')}).`);
+        }
+        const previousRaw = record.raw;
+        const previousHash = record.rawHash;
+        const folder = folderOfRawPath(previousRaw);
+        const previousName = rawFileNameOfPath(previousRaw);
+        const storedName = sanitizedName === previousName ? previousName : this.#uniqueRawName(sanitizedName, folder);
+        const nextRaw = folder === '' ? storedName : `${folder}/${storedName}`;
+        const previousPath = join(this.#config.rawDir, previousRaw);
+        const nextPath = join(this.#config.rawDir, nextRaw);
+        const token = crypto.randomUUID();
+        const temporaryPath = join(this.#config.rawDir, folder, `.fundus-replace-${token}.tmp`);
+        const backupPath = `${previousPath}.fundus-replace-${token}`;
+        let previousStaged = false;
+        let replacementInstalled = false;
+        await mkdir(dirname(temporaryPath), { recursive: true });
+        try {
+            await writeFile(temporaryPath, options.bytes);
+            if (existsSync(previousPath)) {
+                await rename(previousPath, backupPath);
+                previousStaged = true;
+            }
+            await rename(temporaryPath, nextPath);
+            replacementInstalled = true;
+            record.raw = nextRaw;
+            record.rawHash = sha256Hex(options.bytes);
+            await this.write(library);
+        }
+        catch (cause) {
+            record.raw = previousRaw;
+            record.rawHash = previousHash;
+            if (replacementInstalled)
+                await unlink(nextPath).catch(() => { });
+            if (previousStaged)
+                await rename(backupPath, previousPath);
+            await unlink(temporaryPath).catch(() => { });
+            throw cause;
+        }
+        if (previousStaged)
+            await unlink(backupPath).catch(() => { });
+        return library;
+    }
     /** Replace an asset's parameters (validated by the owning plugin). */
     async updateParameters(id, parameters) {
         return this.#enqueue(() => this.#updateParameters(id, parameters));

package/dist/server/operations.d.ts

@@ -1,6 +1,6 @@
 import { type FundusStateDto, type PatchAssetRequestDto, type PatchManifestRequestDto } from '../core/index.js';
 import type { ResolvedFundusConfig } from './config-loader.js';
-import { LibraryStore, type IngestOptions } from './library-store.js';
+import { LibraryStore, type IngestOptions, type ReplaceRawFileOptions } from './library-store.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 /**
  * The CLI's `--parameters` merge semantics (M7): a SHALLOW merge at the top
@@ -22,8 +22,16 @@ export declare class FundusOperations {
     constructor(config: ResolvedFundusConfig, registry?: ServerPluginRegistry);
     get config(): ResolvedFundusConfig;
     get store(): LibraryStore;
-    /** Read-only state snapshot (no processing). */
+    /** Read-only state snapshot, serialized with mutations but never processing or writing. */
     state(): Promise<FundusStateDto>;
+    /** Reconcile only changes that are safe without a user decision: unique moves and deletions. */
+    reconcileRawState(): Promise<FundusStateDto>;
+    /** Adopt an already-existing raw file without copying, renaming, or deleting it. */
+    adoptRawFile(token: string, id: string, type: string, manifests?: readonly string[]): Promise<FundusStateDto>;
+    /** Reset/reseed edited bytes, optionally changing to another compatible type. */
+    acceptEditedRawFile(token: string, type: string): Promise<FundusStateDto>;
+    /** Accept edited bytes while preserving type, parameters, path and memberships. */
+    dismissEditedRawFile(token: string): Promise<FundusStateDto>;
     /**
      * Ingest an upload: store the raw file + record, then let the owning
      * plugin's optional `seedIngestParameters` derive better starting
@@ -37,6 +45,8 @@ export declare class FundusOperations {
     /** 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>;
+    /** Replace the raw bytes/name and run the normal processing + codegen tail. */
+    replaceRawFile(id: string, options: ReplaceRawFileOptions): 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>;