gazetta 0.6.0 → 0.7.0

package/dist/assets/hash.js

@@ -0,0 +1,43 @@
+/**
+ * Content-addressing hash for asset bytes.
+ *
+ * Uses **SHA-256**, 8-character hex prefix — the canonical asset-URL hash for
+ * this codebase. Distinct from:
+ * - `src/hash.ts` (MD5-based) used by publish-rendered sidecars
+ * - Full SHA-256 used by history blob storage
+ *
+ * See design-media-reference.md "Codebase alignment verified → Two hash
+ * algorithms coexist" for why asset work standardises on SHA-256 and doesn't
+ * extend the legacy MD5 sidecar pattern.
+ *
+ * The streaming helper (`hashStream`) consumes the passed stream. Callers
+ * that need both the hash AND the original bytes must tee the stream first.
+ */
+import { createHash } from 'node:crypto';
+/** Length of the hex prefix embedded in asset URLs. Matches the doc's `{hash8}`. */
+export const ASSET_HASH_LENGTH = 8;
+/** Hash a complete byte buffer — convenience wrapper for tests and small payloads. */
+export function hashBytes(bytes) {
+    const full = createHash('sha256').update(bytes).digest('hex');
+    return full.slice(0, ASSET_HASH_LENGTH);
+}
+/**
+ * Hash a byte stream as it flows through. Consumes the stream. Returns the
+ * 8-char hex prefix once the stream ends.
+ *
+ * For upload pipelines that need to both hash and persist bytes, tee the
+ * source stream and pass one branch here, the other to storage.
+ */
+export async function hashStream(stream) {
+    const digest = createHash('sha256');
+    const reader = stream.getReader();
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        if (value)
+            digest.update(value);
+    }
+    return digest.digest('hex').slice(0, ASSET_HASH_LENGTH);
+}
+//# sourceMappingURL=hash.js.map

package/dist/assets/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/assets/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,oFAAoF;AACpF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAA;AAElC,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,KAAiB;IACzC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAA;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAkC;IACjE,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAA;IACjC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QAC3C,IAAI,IAAI;YAAE,MAAK;QACf,IAAI,KAAK;YAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACjC,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAA;AACzD,CAAC"}

package/dist/assets/image-metadata.d.ts

@@ -0,0 +1,11 @@
+export interface ImageDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Extract dimensions from an image buffer. Returns `null` when sharp
+ * can't parse the bytes (unsupported format, corrupt, or non-image MIME
+ * that slipped past sniffing).
+ */
+export declare function extractImageDimensions(bytes: Uint8Array): Promise<ImageDimensions | null>;
+//# sourceMappingURL=image-metadata.d.ts.map

package/dist/assets/image-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-metadata.d.ts","sourceRoot":"","sources":["../../src/assets/image-metadata.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAQ/F"}

package/dist/assets/image-metadata.js

@@ -0,0 +1,31 @@
+/**
+ * Image metadata extraction — wraps sharp's `.metadata()` to get width +
+ * height from bytes without decoding the full image. Read-only, no transform,
+ * no resize.
+ *
+ * Step 4 will add a sibling transform module (variants via sharp's
+ * `.resize()` + `.toFormat()`) that shares the sharp dependency. This file
+ * stays focused on "describe the image" — a reason to change independent of
+ * variant generation.
+ *
+ * sharp is an Apache-2.0 Node binding over libvips. See
+ * design-media-reference.md → Library and tooling specifics.
+ */
+import sharp from 'sharp';
+/**
+ * Extract dimensions from an image buffer. Returns `null` when sharp
+ * can't parse the bytes (unsupported format, corrupt, or non-image MIME
+ * that slipped past sniffing).
+ */
+export async function extractImageDimensions(bytes) {
+    try {
+        const meta = await sharp(bytes).metadata();
+        if (typeof meta.width !== 'number' || typeof meta.height !== 'number')
+            return null;
+        return { width: meta.width, height: meta.height };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=image-metadata.js.map

package/dist/assets/image-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-metadata.js","sourceRoot":"","sources":["../../src/assets/image-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAOzB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAAiB;IAC5D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAA;QAC1C,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QAClF,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAA;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/assets/ingest-locale.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Locale-bytes override ingest — write per-locale (or per-theme) bytes
+ * for an existing asset.
+ *
+ * Author-facing semantics (design-media.md → locale-specific bytes):
+ *   "When the active locale is not the default and the author is
+ *    uploading a file that matches an existing asset's name, the dialog
+ *    asks: Replace default bytes / Add {locale} bytes override / Cancel."
+ *
+ * The "Add override" branch lands here. Result on disk:
+ *   - `{name}.asset.{selector}.json` — locale-bytes manifest with own hash
+ *   - `{name}-{hash}.{selector}.{ext}` — primary bytes for this locale
+ *   - `{name}-{hash}.{selector}-{w}w.{ext}` — variant ladder for this locale
+ *
+ * The default manifest at `{name}.asset.json` is unchanged.
+ *
+ * Single responsibility: validate the override candidate, hash + extract
+ * dimensions + generate variants, write the locale manifest + bytes.
+ * Does NOT own:
+ *   - the route adapter (HTTP layer)
+ *   - the "default vs override" decision UX (the route knows whether the
+ *     active locale is non-default)
+ *   - per-reference content rewrites (locale-bytes don't affect refs)
+ *
+ * Compatibility rules per design-media.md:
+ *   - Same kind as default (image override of image, etc.)
+ *   - `animated` flag must match (out of v1 scope: animated detection
+ *     deferred — today both default and override are static images)
+ *   - MIME may differ within the kind category (jpeg default + webp
+ *     override is allowed; image → video is not)
+ *   - Dimensions may differ (warning at upload time is a UX concern)
+ *
+ * History recording mirrors `ingest.ts`: one revision per upload,
+ * recorded BEFORE any writes so the recorder's first-time baseline
+ * captures pre-op state.
+ */
+import type { ContentRoot } from '../content-root.js';
+import type { HistoryProvider } from '../history.js';
+import type { LocaleBytesOverrideManifest } from '../schema/types.js';
+import type { Selector } from '../schema/dimensions.js';
+import type { StorageProvider } from '../types.js';
+import { type UploadPreprocessor } from './preprocess.js';
+import { type UploadPolicy } from './validate.js';
+export interface IngestLocaleBytesInput {
+    /** Storage provider. */
+    storage: StorageProvider;
+    /** Path prefix for assets (typically `"assets"`). */
+    assetsRoot: string;
+    /** Existing asset's name. The default manifest must already exist. */
+    assetName: string;
+    /**
+     * Selector for the override (locale + optional theme). Must be
+     * non-null — caller decides which dimension(s) to write. The default
+     * asset's bytes correspond to selector === null and are untouched.
+     */
+    selector: Selector;
+    /** The incoming byte stream for the override bytes. */
+    bytes: ReadableStream<Uint8Array>;
+    /** Per-target upload policy (size cap). */
+    policy?: UploadPolicy;
+    /** Optional history. When set, one revision is recorded for this upload. */
+    history?: HistoryProvider;
+    /** Required when `history` is set. */
+    contentRoot?: ContentRoot;
+    /** Author identifier. */
+    author?: string;
+    /** Format-specific preprocessors. Defaults to `defaultPreprocessors`. */
+    preprocessors?: readonly UploadPreprocessor[];
+}
+export interface IngestLocaleBytesResult {
+    /** The new locale-bytes manifest as written. */
+    manifest: LocaleBytesOverrideManifest;
+    /** Path to the override's primary bytes (for caller logging). */
+    bytesPath: string;
+}
+/**
+ * Ingest a locale-bytes override for an existing asset. Throws:
+ *   - `AssetManifestNotFoundError` — default manifest doesn't exist
+ *   - `AssetValidationError` (subclass) — name/size/MIME failed policy
+ *   - `AssetKindMismatchError` — MIME category differs from default
+ *     (image override of pdf is rejected, jpeg override of png is fine)
+ *   - `AssetVariantGenerationError` — sharp couldn't process the bytes
+ *   - `AssetStorageError` — underlying storage failed
+ */
+export declare function ingestLocaleBytes(input: IngestLocaleBytesInput): Promise<IngestLocaleBytesResult>;
+//# sourceMappingURL=ingest-locale.d.ts.map

package/dist/assets/ingest-locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-locale.d.ts","sourceRoot":"","sources":["../../src/assets/ingest-locale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,OAAO,KAAK,EAA+B,2BAA2B,EAAE,MAAM,oBAAoB,CAAA;AAClG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAalD,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAE3E,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,eAAe,CAAA;AASjE,MAAM,WAAW,sBAAsB;IACrC,wBAAwB;IACxB,OAAO,EAAE,eAAe,CAAA;IACxB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,QAAQ,EAAE,QAAQ,CAAA;IAClB,uDAAuD;IACvD,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAA;IACjC,2CAA2C;IAC3C,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,sCAAsC;IACtC,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yEAAyE;IACzE,aAAa,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;CAC9C;AAED,MAAM,WAAW,uBAAuB;IACtC,gDAAgD;IAChD,QAAQ,EAAE,2BAA2B,CAAA;IACrC,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAuJvG"}

package/dist/assets/ingest-locale.js

@@ -0,0 +1,209 @@
+import { recordWrite } from '../history-recorder.js';
+import { selectorSuffix } from '../schema/dimensions.js';
+import { rmIgnoreMissing } from '../providers/_rm-ignore-missing.js';
+import { AssetKindMismatchError, AssetMimeMismatchError, AssetStorageError, AssetVariantGenerationError, } from './errors.js';
+import { ASSET_HASH_LENGTH, hashBytes } from './hash.js';
+import { extractImageDimensions } from './image-metadata.js';
+import { mimeCategory } from './kind-compat.js';
+import { assetBytesPath, assetVariantBytesPath, readManifest, writeLocaleManifest } from './manifest.js';
+import { runAnalyzers } from './analyze.js';
+import { runPreprocessors } from './preprocess.js';
+import { sniffMimeFromStream } from './mime-sniff.js';
+import { validateUpload } from './validate.js';
+import { generateVariants } from './variants.js';
+/** Ext-from-MIME for the v1 allowlist (JPEG, PNG). */
+const EXT_BY_MIME = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+};
+/**
+ * Ingest a locale-bytes override for an existing asset. Throws:
+ *   - `AssetManifestNotFoundError` — default manifest doesn't exist
+ *   - `AssetValidationError` (subclass) — name/size/MIME failed policy
+ *   - `AssetKindMismatchError` — MIME category differs from default
+ *     (image override of pdf is rejected, jpeg override of png is fine)
+ *   - `AssetVariantGenerationError` — sharp couldn't process the bytes
+ *   - `AssetStorageError` — underlying storage failed
+ */
+export async function ingestLocaleBytes(input) {
+    // Step 1 — read the default manifest. Throws AssetManifestNotFoundError
+    // when the asset doesn't exist; you can't override bytes for an asset
+    // that isn't there.
+    const defaultManifest = await readManifest(input.storage, input.assetsRoot, input.assetName);
+    // Step 2 — collect bytes once.
+    const initialBuffer = await collectBytes(input.bytes);
+    // Step 3 — sniff MIME and validate.
+    const { mime, ext } = await sniffMimeFromStream(byteStreamFrom(initialBuffer));
+    validateUpload({ name: input.assetName, claimedSize: initialBuffer.byteLength, sniffedMime: mime }, input.policy);
+    const bytesExt = ext ?? EXT_BY_MIME[mime ?? ''] ?? '';
+    if (!bytesExt) {
+        throw new AssetMimeMismatchError(mime, []);
+    }
+    // Step 4 — kind/MIME-category compatibility with default. Per design,
+    // jpeg → webp is allowed (same `image` category); image → pdf is not.
+    // We don't compare `kind` directly because the override doesn't carry
+    // its own kind — it inherits from the default.
+    const overrideMime = mime ?? 'application/octet-stream';
+    const defaultCategory = mimeCategory(defaultManifest.mime);
+    const overrideCategory = mimeCategory(overrideMime);
+    if (defaultCategory !== overrideCategory) {
+        throw new AssetKindMismatchError(defaultManifest.kind, defaultCategory, defaultManifest.kind, overrideCategory);
+    }
+    // Step 5 — format-specific preprocessing (SVG sanitization, future
+    // EXIF/HEIC/etc.). Same interface as default-asset ingest; failures
+    // throw AssetPreprocessError (HTTP 400).
+    const { bytes: buffer } = await runPreprocessors(initialBuffer, mime, input.preprocessors);
+    const size = buffer.byteLength;
+    const hash = hashBytes(buffer);
+    if (hash.length !== ASSET_HASH_LENGTH) {
+        throw new AssetStorageError('write', input.assetName, new Error('unexpected hash length'));
+    }
+    // Step 6 — image dimensions (per-locale: override may differ from default).
+    const dims = overrideMime.startsWith('image/') ? await extractImageDimensions(buffer) : null;
+    // Step 7 — generate variants in memory. Skip for vector formats
+    // (SVG) and animated images (multi-frame can't ladder-resize
+    // correctly). Animated detection uses the analyzer for parity
+    // with the default-ingest path; locale manifests don't carry
+    // animated fields today, but the variant skip still matters.
+    const generatedVariants = [];
+    if (overrideMime.startsWith('image/') && overrideMime !== 'image/svg+xml') {
+        let isAnimated = false;
+        try {
+            const analysis = await runAnalyzers({
+                bytes: buffer,
+                assetName: input.assetName,
+                hash,
+                ext: bytesExt,
+                mime: overrideMime,
+            });
+            isAnimated = analysis.manifestPatch?.animated === true;
+        }
+        catch {
+            // Analyzer failure is non-fatal at this layer — fall back to
+            // assuming static + variants. Static analyzer would be the one
+            // failing; variant generation will surface its own error if
+            // sharp can't process the image.
+        }
+        if (!isAnimated) {
+            try {
+                const generated = await generateVariants(buffer);
+                generatedVariants.push(...generated);
+            }
+            catch (err) {
+                throw new AssetVariantGenerationError(input.assetName, err);
+            }
+        }
+    }
+    // Step 8 — compose paths + manifest in memory.
+    const variantManifestEntries = generatedVariants.map(v => ({
+        width: v.width,
+        path: assetVariantBytesPath(input.assetName, hash, bytesExt, v.width, input.selector),
+        size: v.bytes.byteLength,
+    }));
+    const bytesRel = assetBytesPath(input.assetName, hash, bytesExt, input.selector);
+    const bytesAbs = `${input.assetsRoot}/${bytesRel}`;
+    const localeManifest = {
+        version: 1,
+        name: input.assetName,
+        hash,
+        size,
+        mime: overrideMime,
+        width: dims?.width ?? null,
+        height: dims?.height ?? null,
+        variants: variantManifestEntries,
+    };
+    const localeManifestPath = `${input.assetsRoot}/${input.assetName}.asset${selectorSuffix(input.selector)}.json`;
+    // Step 8 — record history BEFORE any writes. Mirrors ingest.ts /
+    // replace.ts pattern.
+    if (input.history) {
+        if (!input.contentRoot) {
+            throw new Error('ingestLocaleBytes: history requires contentRoot');
+        }
+        const items = [
+            { path: localeManifestPath, content: `${JSON.stringify(localeManifest, null, 2)}\n` },
+            { path: bytesAbs, content: buffer },
+            ...generatedVariants.map(v => ({
+                path: `${input.assetsRoot}/${assetVariantBytesPath(input.assetName, hash, bytesExt, v.width, input.selector)}`,
+                content: v.bytes,
+            })),
+        ];
+        await recordWrite({
+            history: input.history,
+            contentRoot: input.contentRoot,
+            operation: 'save',
+            author: input.author,
+            items,
+            message: `Upload ${input.assetName} override (${selectorSuffix(input.selector).slice(1)})`,
+        });
+    }
+    // Step 9 — write primary bytes.
+    try {
+        await input.storage.writeStream(bytesAbs, byteStreamFrom(buffer));
+    }
+    catch (err) {
+        throw new AssetStorageError('write', bytesAbs, err);
+    }
+    // Step 10 — write variants with rollback on failure.
+    const writtenVariantPaths = [];
+    for (const v of generatedVariants) {
+        const variantAbs = `${input.assetsRoot}/${assetVariantBytesPath(input.assetName, hash, bytesExt, v.width, input.selector)}`;
+        try {
+            await input.storage.writeStream(variantAbs, byteStreamFrom(v.bytes));
+        }
+        catch (err) {
+            await rollback(input.storage, [bytesAbs, ...writtenVariantPaths]);
+            throw new AssetStorageError('write', variantAbs, err);
+        }
+        writtenVariantPaths.push(variantAbs);
+    }
+    // Step 11 — write the locale manifest last (the visible "this
+    // override exists" record).
+    try {
+        await writeLocaleManifest(input.storage, input.assetsRoot, input.assetName, input.selector, localeManifest);
+    }
+    catch (err) {
+        await rollback(input.storage, [bytesAbs, ...writtenVariantPaths]);
+        throw err;
+    }
+    return { manifest: localeManifest, bytesPath: bytesAbs };
+}
+async function rollback(storage, paths) {
+    for (const path of paths) {
+        try {
+            await rmIgnoreMissing(storage, path);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+async function collectBytes(stream) {
+    const reader = stream.getReader();
+    const parts = [];
+    let total = 0;
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            parts.push(value);
+            total += value.byteLength;
+        }
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const p of parts) {
+        out.set(p, offset);
+        offset += p.byteLength;
+    }
+    return out;
+}
+function byteStreamFrom(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+//# sourceMappingURL=ingest-locale.js.map

package/dist/assets/ingest-locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-locale.js","sourceRoot":"","sources":["../../src/assets/ingest-locale.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAE,WAAW,EAAoB,MAAM,wBAAwB,CAAA;AAGtE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AACpE,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACxG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAA2B,MAAM,iBAAiB,CAAA;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EAAqB,cAAc,EAAE,MAAM,eAAe,CAAA;AACjE,OAAO,EAAE,gBAAgB,EAAyB,MAAM,eAAe,CAAA;AAEvE,sDAAsD;AACtD,MAAM,WAAW,GAA2B;IAC1C,YAAY,EAAE,KAAK;IACnB,WAAW,EAAE,KAAK;CACnB,CAAA;AAoCD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAA6B;IACnE,wEAAwE;IACxE,sEAAsE;IACtE,oBAAoB;IACpB,MAAM,eAAe,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IAE5F,+BAA+B;IAC/B,MAAM,aAAa,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAErD,oCAAoC;IACpC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,mBAAmB,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAA;IAC9E,cAAc,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,aAAa,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAEjH,MAAM,QAAQ,GAAG,GAAG,IAAI,WAAW,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,EAAE,CAAA;IACrD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,sBAAsB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAC5C,CAAC;IAED,sEAAsE;IACtE,sEAAsE;IACtE,sEAAsE;IACtE,+CAA+C;IAC/C,MAAM,YAAY,GAAG,IAAI,IAAI,0BAA0B,CAAA;IACvD,MAAM,eAAe,GAAG,YAAY,CAAC,eAAe,CAAC,IAAI,CAAC,CAAA;IAC1D,MAAM,gBAAgB,GAAG,YAAY,CAAC,YAAY,CAAC,CAAA;IACnD,IAAI,eAAe,KAAK,gBAAgB,EAAE,CAAC;QACzC,MAAM,IAAI,sBAAsB,CAAC,eAAe,CAAC,IAAI,EAAE,eAAe,EAAE,eAAe,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAA;IACjH,CAAC;IAED,mEAAmE;IACnE,oEAAoE;IACpE,yCAAyC;IACzC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,gBAAgB,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC,CAAA;IAC1F,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAA;IAE9B,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;IAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,iBAAiB,EAAE,CAAC;QACtC,MAAM,IAAI,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAAA;IAC5F,CAAC;IAED,4EAA4E;IAC5E,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAE5F,gEAAgE;IAChE,6DAA6D;IAC7D,8DAA8D;IAC9D,6DAA6D;IAC7D,6DAA6D;IAC7D,MAAM,iBAAiB,GAAuB,EAAE,CAAA;IAChD,IAAI,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,YAAY,KAAK,eAAe,EAAE,CAAC;QAC1E,IAAI,UAAU,GAAG,KAAK,CAAA;QACtB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC;gBAClC,KAAK,EAAE,MAAM;gBACb,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,IAAI;gBACJ,GAAG,EAAE,QAAQ;gBACb,IAAI,EAAE,YAAY;aACnB,CAAC,CAAA;YACF,UAAU,GAAG,QAAQ,CAAC,aAAa,EAAE,QAAQ,KAAK,IAAI,CAAA;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;YAC7D,+DAA+D;YAC/D,4DAA4D;YAC5D,iCAAiC;QACnC,CAAC;QAED,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAA;gBAChD,iBAAiB,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAA;YACtC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,2BAA2B,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;YAC7D,CAAC;QACH,CAAC;IACH,CAAC;IAED,+CAA+C;IAC/C,MAAM,sBAAsB,GAAmB,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACzE,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,qBAAqB,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;QACrF,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU;KACzB,CAAC,CAAC,CAAA;IACH,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;IAChF,MAAM,QAAQ,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,QAAQ,EAAE,CAAA;IAClD,MAAM,cAAc,GAAgC;QAClD,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,KAAK,CAAC,SAAS;QACrB,IAAI;QACJ,IAAI;QACJ,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,IAAI,EAAE,KAAK,IAAI,IAAI;QAC1B,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,IAAI;QAC5B,QAAQ,EAAE,sBAAsB;KACjC,CAAA;IACD,MAAM,kBAAkB,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,SAAS,SAAS,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAA;IAE/G,iEAAiE;IACjE,sBAAsB;IACtB,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;QACpE,CAAC;QACD,MAAM,KAAK,GAAkB;YAC3B,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;YACrF,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;YACnC,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAC7B,IAAI,EAAE,GAAG,KAAK,CAAC,UAAU,IAAI,qBAAqB,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE;gBAC9G,OAAO,EAAE,CAAC,CAAC,KAAK;aACjB,CAAC,CAAC;SACJ,CAAA;QACD,MAAM,WAAW,CAAC;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,SAAS,EAAE,MAAM;YACjB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,KAAK;YACL,OAAO,EAAE,UAAU,KAAK,CAAC,SAAS,cAAc,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG;SAC3F,CAAC,CAAA;IACJ,CAAC;IAED,gCAAgC;IAChC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAA;IACnE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAA;IACrD,CAAC;IAED,qDAAqD;IACrD,MAAM,mBAAmB,GAAa,EAAE,CAAA;IACxC,KAAK,MAAM,CAAC,IAAI,iBAAiB,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,qBAAqB,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAA;QAC3H,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QACtE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,mBAAmB,CAAC,CAAC,CAAA;YACjE,MAAM,IAAI,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,CAAC,CAAA;QACvD,CAAC;QACD,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACtC,CAAC;IAED,8DAA8D;IAC9D,4BAA4B;IAC5B,IAAI,CAAC;QACH,MAAM,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAA;IAC7G,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,mBAAmB,CAAC,CAAC,CAAA;QACjE,MAAM,GAAG,CAAA;IACX,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;AAC1D,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,OAAwB,EAAE,KAAwB;IACxE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,MAAkC;IAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAA;IACjC,MAAM,KAAK,GAAiB,EAAE,CAAA;IAC9B,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;QAC3C,IAAI,IAAI;YAAE,MAAK;QACf,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACjB,KAAK,IAAI,KAAK,CAAC,UAAU,CAAA;QAC3B,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAA;IACjC,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;QAClB,MAAM,IAAI,CAAC,CAAC,UAAU,CAAA;IACxB,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,cAAc,CAAC,KAAiB;IACvC,OAAO,IAAI,cAAc,CAAC;QACxB,KAAK,CAAC,UAAU;YACd,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YACzB,UAAU,CAAC,KAAK,EAAE,CAAA;QACpB,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/assets/ingest.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Asset ingest pipeline — the single entry point for "bytes in → persisted
+ * asset out." Composes validation, hashing, MIME sniffing, dimension
+ * extraction, byte persistence, and manifest writing.
+ *
+ * Callers (HTTP upload route, future CLI import, future paste-URL handler):
+ *   const result = await ingestAsset({ storage, assetsRoot, bytes, requestedName, ... })
+ *
+ * Inside, the stream is collected into a buffer first — for the v1 slice's
+ * 50 MB limit this is the pragmatic choice (validation wants to see all the
+ * bytes; hashing + sniffing + dimensions all need to touch them). A future
+ * large-video path would need true streaming; calling sites that need that
+ * can compose the lower-level primitives (sniffMimeFromStream, hashStream,
+ * atomicWriteStream) directly.
+ *
+ * History atomicity:
+ *   When `history` is provided, ingest records ONE revision covering the
+ *   manifest + primary bytes + every variant. Recording happens BEFORE any
+ *   writes so the recorder's first-time baseline scan captures pre-op
+ *   state — same pattern as `replace.ts`. If recording succeeds but a
+ *   subsequent write fails, the revision references blobs we never
+ *   persisted; that's recoverable (history-restorer degrades gracefully
+ *   on missing blobs) and rare (writes after a successful record fail
+ *   only on transient storage errors), and far better than the inverse
+ *   (writes succeed, recorder captures post-op state, undo is a no-op).
+ */
+import type { ContentRoot } from '../content-root.js';
+import type { HistoryProvider } from '../history.js';
+import type { AssetManifest } from '../schema/types.js';
+import type { StorageProvider } from '../types.js';
+import { type UploadAnalyzer } from './analyze.js';
+import { type UploadPolicy } from './validate.js';
+import { type UploadPreprocessor } from './preprocess.js';
+export interface IngestInput {
+    /** The target's storage provider. */
+    storage: StorageProvider;
+    /** The assets directory prefix (e.g., `"assets"`) relative to storage root. */
+    assetsRoot: string;
+    /** The incoming byte stream (multipart file body). */
+    bytes: ReadableStream<Uint8Array>;
+    /** Author-chosen asset name (pre-validation; policy may reject). */
+    requestedName: string;
+    /** Optional author-supplied alt text. Null means "not set" (warns in the library). */
+    alt: string | null;
+    /** Author identifier, if available. Empty string when RBAC isn't configured. */
+    uploadedBy: string;
+    /**
+     * Per-target upload policy. When omitted, the default size cap
+     * (`DEFAULT_ASSET_MAX_BYTES` from validate.ts) applies. The HTTP
+     * route should pass `target.assets` through here so per-target
+     * limits are honored.
+     */
+    policy?: UploadPolicy;
+    /**
+     * Optional history provider. When set, ingest records ONE revision
+     * covering manifest + primary bytes + variants. Caller must also pass
+     * `contentRoot` so the recorder can scan the pre-op baseline on its
+     * first call.
+     */
+    history?: HistoryProvider;
+    /** Required when `history` is set — content root for the baseline scan. */
+    contentRoot?: ContentRoot;
+    /** Author identifier passed through to the history revision. */
+    author?: string;
+    /**
+     * Format-specific preprocessors to run on the byte buffer before
+     * hashing. Defaults to `defaultPreprocessors` (today: SVG
+     * sanitization). Tests pass an empty array to bypass; future
+     * deployments can register custom preprocessors (HEIC transcode,
+     * etc.) without editing this module.
+     */
+    preprocessors?: readonly UploadPreprocessor[];
+    /**
+     * Format-specific analyzers to run on the post-preprocess bytes.
+     * Defaults to `defaultAnalyzers` (today: width/height + animated
+     * detection + poster extraction for images). Empty array bypasses
+     * analysis; custom registries plug in audio metadata, EXIF,
+     * PDF page count, etc. without editing this module.
+     */
+    analyzers?: readonly UploadAnalyzer[];
+}
+export interface IngestResult {
+    manifest: AssetManifest;
+    bytesPath: string;
+}
+/**
+ * Ingest an asset. On success, bytes are persisted at
+ * `{assetsRoot}/{name}-{hash}.{ext}` and the manifest at
+ * `{assetsRoot}/{name}.asset.json`.
+ *
+ * Throws:
+ * - `AssetValidationError` — name, size, or MIME failed policy
+ * - `AssetStorageError` — storage write failed
+ */
+export declare function ingestAsset(input: IngestInput): Promise<IngestResult>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/assets/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/assets/ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,oBAAoB,CAAA;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAA;AAMhE,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,eAAe,CAAA;AACjE,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AA2B3E,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,OAAO,EAAE,eAAe,CAAA;IACxB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAA;IAClB,sDAAsD;IACtD,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAA;IACjC,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAA;IACrB,sFAAsF;IACtF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC7C;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAmM3E"}