fundus 0.1.0 → 0.2.0

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

@@ -22,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

@@ -1157,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.js

@@ -1,4 +1,4 @@
-import { mkdir, unlink, writeFile } from 'node:fs/promises';
+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';
@@ -48,6 +48,7 @@ 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 {
@@ -63,6 +64,20 @@ export async function runInitCommand(argumentList) {
         }
         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;

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/library-store.d.ts

@@ -36,6 +36,18 @@ 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

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

package/dist/server/operations.d.ts

@@ -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