gazetta 0.7.0 → 0.8.0

package/dist/manifest-save.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Save pipeline — orchestrator for Page and Fragment Manifest writes.
+ *
+ * Today's `admin-api/routes/pages.ts` PUT handler and the matching
+ * fragments.ts handler each inline the same 13-step orchestration:
+ * etag check → validate → beforeSave hooks → history → write → sidecars
+ * → cache → audit → afterSave hooks → scanner. Two route files, one deep
+ * concept duplicated.
+ *
+ * `saveManifestCore` is the seam that hides the orchestration. Routes
+ * become protocol translators (parse Hono request → call → project
+ * SaveResult to HTTP). The CLI, plugin-contributed routes, and any
+ * future Save-shaped consumer call the same function.
+ *
+ * Per-kind entry points (`savePage`, `saveFragment` in pages/save.ts +
+ * fragments/save.ts — Cuts 3+4) wrap this with kind-specific concerns:
+ * locale resolution from `site.pages` vs `site.fragments`, the `route`
+ * field preservation Page Manifests need, and per-kind cache prefixes
+ * (Fragment Saves invalidate `pages:` too because Fragment References
+ * compose into Page summaries).
+ *
+ * Pipeline order is locked semantics, not configuration. Per
+ * `design-hooks.md` "Save flow with hooks": validators run first
+ * (validators are pure functions over a manifest), then beforeSave
+ * hooks see validated payload, then storage write, then afterSave
+ * hooks observe the result. Reordering breaks invariants — audit
+ * before write would lie about success.
+ *
+ * Reserved slots in the sequence (no-ops today; wired by future cuts):
+ *   - Review-state precheck (Review-Workflow Cut 5: pending-review
+ *     state → 409 EDIT_LOCKED)
+ *   - Cascades (Soft-Delete Q6: auto-cancel scheduled actions on
+ *     archive transition; Review Cut 5: invalidateOnSave policy
+ *     transitions approved → draft)
+ *
+ * Throws are reserved for infrastructure failures (storage write
+ * fail, audit infra fail per locked fail-open). Expected outcomes
+ * — STALE / VALIDATION_FAILED / HOOK_CANCELLED — are typed
+ * `SaveResult` variants. Callers `switch` exhaustively; TS narrows.
+ */
+import type { Principal } from './auth/types.js';
+import type { ContentRoot } from './content-root.js';
+import type { HistoryProvider } from './history.js';
+import { type HookRegistry } from './hooks/index.js';
+import type { Site } from './site-loader.js';
+import type { StorageProvider } from './types.js';
+import type { ValidatorRegistry } from './validation/registry.js';
+import type { RescanCause, ValidationScanner } from './validation/scanner.js';
+import type { Issue } from './validation/types.js';
+/**
+ * Discriminator for the kind of manifest being saved. The pipeline
+ * spine is the same for every kind; per-kind wrappers in
+ * `pages/save.ts` and `fragments/save.ts` carry the kind through to
+ * audit + sidecar + cache invalidation calls.
+ */
+export type SaveManifestKind = 'page' | 'fragment';
+/**
+ * Successful save outcome. `etag` is the recomputed save-etag for
+ * the new on-disk content; clients update their baseline without a
+ * separate GET so offline replay chains work (per
+ * `design-offline.md` Q3 — chained If-Match projections).
+ */
+export interface SaveOk {
+    readonly ok: true;
+    readonly etag: string;
+}
+/**
+ * Save-etag mismatch (per `design-offline.md` Q3). Server returned
+ * the current manifest body so the client can render a diff. The
+ * `currentEtag` lets the client retry-without-conflict if it accepts
+ * the server's version verbatim.
+ */
+export interface SaveStale {
+    readonly ok: false;
+    readonly code: 'STALE';
+    readonly current: Record<string, unknown>;
+    readonly currentEtag: string;
+}
+/**
+ * Save-delta validation produced blocking issues (per
+ * `design-validation.md` four-phase model). Only issues introduced
+ * by THIS edit are surfaced — pre-existing site debt is the
+ * background scanner's surface, not the save handler's.
+ */
+export interface SaveValidationFailed {
+    readonly ok: false;
+    readonly code: 'VALIDATION_FAILED';
+    readonly issues: readonly Issue[];
+}
+/**
+ * A `beforeSave` hook threw `HookCancellation` or `HookTimeout`
+ * (per `design-hooks.md` "Composition" — `before*` hooks chain;
+ * one throw stops the chain and cancels the operation). The hook's
+ * name is surfaced so clients can discriminate which hook
+ * cancelled.
+ */
+export interface SaveHookCancelled {
+    readonly ok: false;
+    readonly code: 'HOOK_CANCELLED';
+    readonly hook: string;
+    readonly reason: string;
+}
+/**
+ * Typed union of expected save outcomes. Routes project each
+ * variant to HTTP (200 / 409). Callers (CLI, plugin-routes, future
+ * save-via-hook) `switch` exhaustively. Adding a new variant is a
+ * compile error at every call site — intentional, per the locked
+ * decision in Q1.
+ */
+export type SaveResult = SaveOk | SaveStale | SaveValidationFailed | SaveHookCancelled;
+/**
+ * Audit recorder shape the pipeline calls. Matches the existing
+ * `c.var.audit.record` surface from admin-api/middleware/audit.ts
+ * — the pipeline doesn't construct events differently from routes.
+ *
+ * Returns `unknown` (not `RecordResult`) so the pipeline doesn't
+ * couple to the audit module's return shape. Strict-mode operators
+ * branch on `result.failed > 0`; the pipeline doesn't.
+ */
+export interface SaveAuditRecorder {
+    record(event: {
+        action: 'save';
+        /**
+         * Closed-enum subset of AuditOutcome the save pipeline emits.
+         * 'hook-cancelled' fires when a beforeSave hook throws or times
+         * out (per design-hooks.md Q3); 'validation-failed' fires when
+         * save-delta validators flag blocking issues. Pre-fix shape
+         * conflated the two paths under 'validation-failed' — fixed
+         * 2026-05 alongside cross-foundation gap #1 coverage.
+         */
+        outcome: 'success' | 'validation-failed' | 'forbidden' | 'hook-cancelled';
+        scope: {
+            kind: SaveManifestKind;
+            name: string;
+        };
+        metadata?: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/**
+ * Principal shape the pipeline needs. Re-exports `auth/types.ts:Principal`
+ * so callers (`c.var.principal`) pass the real type without conversion.
+ * The pipeline doesn't construct principals — only forwards them to
+ * `buildHookContext`.
+ */
+export type SavePrincipal = Principal;
+/**
+ * Source wiring the pipeline needs. Mirrors the relevant subset of
+ * `admin-api/source-context.ts:SourceContext` without importing the
+ * admin-api type — the pipeline is a domain primitive, not bound to
+ * the admin-api boundary. Wrappers (`savePage`, `saveFragment`) pass
+ * `source` straight through; the structural compatibility with
+ * `SourceContext` lets that work without conversion.
+ */
+export interface SaveSourceWiring {
+    readonly storage: StorageProvider;
+    readonly contentRoot: ContentRoot;
+    readonly cache: {
+        invalidatePrefix(prefix: string): Promise<number>;
+    };
+    readonly history?: HistoryProvider;
+    readonly targetName?: string;
+    readonly manifest?: {
+        name?: string;
+    };
+}
+/**
+ * Inputs to `saveManifestCore`. Carries everything the pipeline
+ * needs without reaching into route or HTTP concerns.
+ *
+ * Per Q2 lock: target wiring (cache, history, storage, contentRoot)
+ * comes from `SourceContext` upstream; orchestration deps
+ * (validators, hooks, scanner, audit) are injected per request.
+ * The wrapper functions (`savePage`, `saveFragment`) destructure
+ * `source` and assemble this shape.
+ */
+export interface SaveManifestInput {
+    /** Discriminator for downstream audit + sidecar calls. */
+    readonly kind: SaveManifestKind;
+    /** Item name (folder name under `pages/` or `fragments/`). */
+    readonly name: string;
+    /** BCP-47 locale when saving a Locale Variant; undefined for default. */
+    readonly locale?: string;
+    /** New manifest body (post-component-id, pre-validation). */
+    readonly manifest: Record<string, unknown>;
+    /** Pre-save manifest from the loaded `Site`; null when creating. */
+    readonly before: Record<string, unknown> | null;
+    /** Absolute path the new manifest serializes to. */
+    readonly manifestPath: string;
+    /** Optional save-etag for concurrency check (per design-offline.md Q3). */
+    readonly ifMatch?: string;
+    /**
+     * Loaded `Site` (the same instance that resolved `before`). Save-delta
+     * validation needs it to walk template + fragment + asset refs.
+     */
+    readonly site: Site;
+    /**
+     * Cache prefixes to invalidate after the write. Page Saves pass
+     * `['pages:']`; Fragment Saves pass `['fragments:', 'pages:']`
+     * because Fragment References compose into Page summaries.
+     */
+    readonly cacheInvalidatePrefixes: readonly string[];
+    /**
+     * Optional fields to include in the recomputed save-etag.
+     * Page Saves include `route` (folder-derived; not stored in the
+     * file but part of the etag projection chain). Fragment Saves
+     * pass an empty object.
+     */
+    readonly etagExtras: Record<string, unknown>;
+    /** Source wiring; opaque to the pipeline beyond the typed fields below. */
+    readonly source: SaveSourceWiring;
+    /** Audit recorder bound to the request (typically `c.var.audit`). */
+    readonly audit: SaveAuditRecorder;
+    /** Authenticated principal driving this save (for hook context). */
+    readonly principal: SavePrincipal;
+    /** Audit-firing emitter used by hook dispatch (forwarded to buildHookContext). */
+    readonly hookAuditEmit?: import('./hooks/index.js').HookFiringEmitter;
+    /** Validator registry (built once at admin boot per design-validation.md Cut 1). */
+    readonly validators: ValidatorRegistry;
+    /** Hook registry; absent when the site has no hooks contributed. */
+    readonly hooks?: HookRegistry;
+    /** Background scanner; absent when scanner not enabled for this admin. */
+    readonly scanner?: ValidationScanner;
+    /**
+     * Scanner rescan cause. Per-kind because the scanner's `RescanCause`
+     * union differs by kind (Page Saves use `{ kind: 'manifest', item }`
+     * to invalidate just the page; Fragment Saves use
+     * `{ kind: 'fragment', name }` to walk transitive dependents via
+     * `findDependentsFromSidecars`). Wrappers build the right shape.
+     */
+    readonly scannerCause?: RescanCause;
+    /** Per-request correlation id; fresh UUID when absent. */
+    readonly requestId?: string;
+}
+/**
+ * Save pipeline orchestrator — Cut 2.
+ *
+ * Ports the 13-step spine from `admin-api/routes/pages.ts:290-510`.
+ * Pipeline sequence (locked per Q5):
+ *
+ *   1. etag precheck                 → STALE
+ *   2. review-state precheck         (reserved slot — no-op today)
+ *   3. validators                    → VALIDATION_FAILED
+ *   4. beforeSave hooks              → HOOK_CANCELLED
+ *   5. history record (pre-write)
+ *   6. storage write
+ *   7. sidecars (asset/fragment/alias) in parallel
+ *   8. cache invalidate (per per-kind prefixes)
+ *   9. compute new etag
+ *  10. audit success
+ *  11. afterSave hooks               (fail-open observers)
+ *  12. cascades                      (reserved slot — no-op today)
+ *  13. scanner.rescan                (fire-and-forget)
+ */
+export declare function saveManifestCore(input: SaveManifestInput): Promise<SaveResult>;
+//# sourceMappingURL=manifest-save.d.ts.map

package/dist/manifest-save.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-save.d.ts","sourceRoot":"","sources":["../src/manifest-save.ts"],"names":[],"mappings":"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"}

package/dist/manifest-save.js

@@ -0,0 +1,260 @@
+/**
+ * Save pipeline — orchestrator for Page and Fragment Manifest writes.
+ *
+ * Today's `admin-api/routes/pages.ts` PUT handler and the matching
+ * fragments.ts handler each inline the same 13-step orchestration:
+ * etag check → validate → beforeSave hooks → history → write → sidecars
+ * → cache → audit → afterSave hooks → scanner. Two route files, one deep
+ * concept duplicated.
+ *
+ * `saveManifestCore` is the seam that hides the orchestration. Routes
+ * become protocol translators (parse Hono request → call → project
+ * SaveResult to HTTP). The CLI, plugin-contributed routes, and any
+ * future Save-shaped consumer call the same function.
+ *
+ * Per-kind entry points (`savePage`, `saveFragment` in pages/save.ts +
+ * fragments/save.ts — Cuts 3+4) wrap this with kind-specific concerns:
+ * locale resolution from `site.pages` vs `site.fragments`, the `route`
+ * field preservation Page Manifests need, and per-kind cache prefixes
+ * (Fragment Saves invalidate `pages:` too because Fragment References
+ * compose into Page summaries).
+ *
+ * Pipeline order is locked semantics, not configuration. Per
+ * `design-hooks.md` "Save flow with hooks": validators run first
+ * (validators are pure functions over a manifest), then beforeSave
+ * hooks see validated payload, then storage write, then afterSave
+ * hooks observe the result. Reordering breaks invariants — audit
+ * before write would lie about success.
+ *
+ * Reserved slots in the sequence (no-ops today; wired by future cuts):
+ *   - Review-state precheck (Review-Workflow Cut 5: pending-review
+ *     state → 409 EDIT_LOCKED)
+ *   - Cascades (Soft-Delete Q6: auto-cancel scheduled actions on
+ *     archive transition; Review Cut 5: invalidateOnSave policy
+ *     transitions approved → draft)
+ *
+ * Throws are reserved for infrastructure failures (storage write
+ * fail, audit infra fail per locked fail-open). Expected outcomes
+ * — STALE / VALIDATION_FAILED / HOOK_CANCELLED — are typed
+ * `SaveResult` variants. Callers `switch` exhaustively; TS narrows.
+ */
+import { recordWrite } from './history-recorder.js';
+import { buildHookContext, dispatchAfterSave, dispatchBeforeSave, HookCancellation, HookTimeout, } from './hooks/index.js';
+import { rebuildAssetRefs } from './assets/asset-deps.js';
+import { rebuildFragmentDeps } from './fragment-deps.js';
+import { rebuildArchiveAliases } from './archive-aliases.js';
+import { computeSaveEtag } from './save-etag.js';
+import { hasBlockingIssues, runSaveDelta } from './validation/save-delta.js';
+/**
+ * Save pipeline orchestrator — Cut 2.
+ *
+ * Ports the 13-step spine from `admin-api/routes/pages.ts:290-510`.
+ * Pipeline sequence (locked per Q5):
+ *
+ *   1. etag precheck                 → STALE
+ *   2. review-state precheck         (reserved slot — no-op today)
+ *   3. validators                    → VALIDATION_FAILED
+ *   4. beforeSave hooks              → HOOK_CANCELLED
+ *   5. history record (pre-write)
+ *   6. storage write
+ *   7. sidecars (asset/fragment/alias) in parallel
+ *   8. cache invalidate (per per-kind prefixes)
+ *   9. compute new etag
+ *  10. audit success
+ *  11. afterSave hooks               (fail-open observers)
+ *  12. cascades                      (reserved slot — no-op today)
+ *  13. scanner.rescan                (fire-and-forget)
+ */
+export async function saveManifestCore(input) {
+    // Step 1 — etag precheck. Mirrors pages.ts:312-339. The current
+    // on-disk etag is computed from the in-memory `before` manifest
+    // plus the per-kind extras (Page passes route; Fragment passes
+    // empty). Absent ifMatch = no concurrency check (last-write-wins).
+    if (input.ifMatch && input.before) {
+        const currentEtag = await computeSaveEtag({
+            ...input.before,
+            ...input.etagExtras,
+        });
+        if (currentEtag !== input.ifMatch) {
+            return {
+                ok: false,
+                code: 'STALE',
+                current: { ...input.before, ...input.etagExtras },
+                currentEtag,
+            };
+        }
+    }
+    // Step 2 — review-state precheck. Reserved slot for Review-Workflow
+    // Cut 5 (pending-review state → 409 EDIT_LOCKED). No-op today.
+    // Step 3 — save-delta validation. Same shape as pages.ts:370-394.
+    // Validators are pure functions; orchestrator catches infra errors
+    // and surfaces them as synthetic issues so the save flow stays
+    // predictable. Audit failure with `outcome: 'validation-failed'`
+    // before returning the typed result.
+    const issues = await runSaveDelta({
+        item: {
+            kind: input.kind,
+            name: input.name,
+            itemPath: input.source.contentRoot.relative(input.manifestPath),
+        },
+        // Cast preserves the validator's structural expectation; the
+        // pipeline treats manifests as opaque bags of fields here.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        before: input.before,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        after: { ...input.manifest, ...input.etagExtras },
+        site: input.site,
+        contentRoot: input.source.contentRoot,
+        storage: input.source.storage,
+    }, input.validators);
+    if (hasBlockingIssues(issues)) {
+        await input.audit.record({
+            action: 'save',
+            outcome: 'validation-failed',
+            scope: { kind: input.kind, name: input.name },
+            metadata: input.locale ? { locale: input.locale } : undefined,
+        });
+        return { ok: false, code: 'VALIDATION_FAILED', issues };
+    }
+    // Step 4 — beforeSave hooks. Build the HookContext ONCE per
+    // request — design-hooks.md "HookContext shape" locks `now` +
+    // `requestId` as deterministic across all hooks in a request.
+    // Reused for the afterSave dispatch in step 11.
+    const hooks = input.hooks;
+    const hookCtx = hooks
+        ? buildHookContext({
+            principal: input.principal,
+            storage: input.source.storage,
+            target: input.source.targetName,
+            requestId: input.requestId ?? crypto.randomUUID(),
+            site: { name: input.source.manifest?.name },
+            auditEmit: input.hookAuditEmit,
+        })
+        : null;
+    const hookScope = {
+        kind: input.kind,
+        name: input.name,
+        locale: input.locale ?? undefined,
+    };
+    let finalManifest = input.manifest;
+    if (hooks && hookCtx) {
+        try {
+            finalManifest = (await dispatchBeforeSave(hooks, hookScope, input.manifest, hookCtx));
+        }
+        catch (err) {
+            if (err instanceof HookCancellation || err instanceof HookTimeout) {
+                // Per design-hooks.md Q3 audit lock: cancelled saves record
+                // outcome 'hook-cancelled' (closed-enum extension to
+                // AuditOutcome already in audit/types.ts). Earlier behavior
+                // emitted 'validation-failed' which conflated hook policy
+                // with validator semantics — forensic queries filtering on
+                // outcome would mistakenly include hook cancellations.
+                // metadata.hookCancelled vs metadata.hookTimeout still
+                // distinguishes the two cancellation paths for forensics.
+                await input.audit.record({
+                    action: 'save',
+                    outcome: 'hook-cancelled',
+                    scope: { kind: input.kind, name: input.name },
+                    metadata: {
+                        ...(input.locale ? { locale: input.locale } : {}),
+                        hookCancelled: err instanceof HookCancellation ? err.hookName : undefined,
+                        hookTimeout: err instanceof HookTimeout ? err.hookName : undefined,
+                    },
+                });
+                return {
+                    ok: false,
+                    code: 'HOOK_CANCELLED',
+                    hook: err.hookName,
+                    reason: err.message,
+                };
+            }
+            throw err;
+        }
+    }
+    // Re-serialize the (potentially mutated) manifest. When no hooks
+    // ran, finalManifest === input.manifest so the same serialization
+    // is recomputed once — cost is negligible vs the conditional.
+    const serialized = JSON.stringify(finalManifest, null, 2) + '\n';
+    // Step 5 — history. Record BEFORE the disk write per the
+    // recordWrite first-call invariant (pages.ts:442-456). Baseline
+    // scan reads current disk state (pre-save); recordWrite overlays
+    // the incoming delta to build the snapshot.
+    if (input.source.history) {
+        await recordWrite({
+            history: input.source.history,
+            contentRoot: input.source.contentRoot,
+            operation: 'save',
+            items: [
+                {
+                    path: input.source.contentRoot.relative(input.manifestPath),
+                    content: serialized,
+                },
+            ],
+        });
+    }
+    // Step 6 — storage write.
+    await input.source.storage.writeFile(input.manifestPath, serialized);
+    // Step 7 — sidecars in parallel. Three Usage Sidecar relations
+    // (per `sidecars.md`): asset-refs, fragment-deps, archive-aliases.
+    // Future asset-soft-delete adds a fourth here in one place.
+    const item = input.locale
+        ? {
+            source: input.kind === 'page' ? 'page' : 'fragment',
+            name: input.name,
+            locale: input.locale,
+        }
+        : { source: input.kind === 'page' ? 'page' : 'fragment', name: input.name };
+    await Promise.all([
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        rebuildAssetRefs(input.source.contentRoot, item, input.before, finalManifest),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        rebuildFragmentDeps(input.source.contentRoot, item, input.before, finalManifest),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        rebuildArchiveAliases(input.source.contentRoot, item, input.before, finalManifest),
+    ]);
+    // Step 8 — cache invalidate. Per-kind prefixes from caller. Page
+    // Saves pass ['pages:']; Fragment Saves pass ['fragments:',
+    // 'pages:'] because Fragment References compose into Page
+    // summaries.
+    await Promise.all(input.cacheInvalidatePrefixes.map(p => input.source.cache.invalidatePrefix(p)));
+    // Step 9 — recompute save-etag for the new on-disk content. Echo
+    // shape MUST match what the next GET produces — extras (route)
+    // are folded in here so offline replay projection chains work
+    // (design-offline.md Q3).
+    const echoShape = { ...finalManifest, ...input.etagExtras };
+    const newEtag = await computeSaveEtag(echoShape);
+    // Step 10 — audit success. Records actor + scope + locale (when
+    // locale variant). Strict-mode operators check the result.failed
+    // count; fail-open default ignores. Recorder never throws.
+    await input.audit.record({
+        action: 'save',
+        outcome: 'success',
+        scope: { kind: input.kind, name: input.name },
+        metadata: input.locale ? { locale: input.locale } : undefined,
+    });
+    // Step 11 — afterSave hooks. Observational; failures logged but
+    // never propagated. Runs AFTER the audit record so the forensic
+    // record is durably committed before observational hooks fire.
+    // Per-hook timeout applies; one slow hook bounded by its
+    // timeout, not the total.
+    if (hooks && hookCtx) {
+        await dispatchAfterSave(hooks, hookScope, { payload: finalManifest, etag: newEtag }, hookCtx);
+    }
+    // Step 12 — cascades. Reserved slot for Soft-Delete Q6
+    // (auto-cancel scheduled actions on archive transition) and
+    // Review Cut 5 (invalidateOnSave policy → approved → draft).
+    // No-op today.
+    // Step 13 — background validation scanner. Fire-and-forget — the
+    // save response shouldn't block on scanner work; the scanner
+    // emits its own SSE event when the pass completes and the admin
+    // UI store re-fetches `/api/validation/issues` on the event.
+    if (input.scanner) {
+        const cause = input.scannerCause ?? {
+            kind: 'manifest',
+            item: { kind: input.kind, name: input.name, itemPath: input.manifestPath },
+        };
+        void input.scanner.rescan(cause);
+    }
+    return { ok: true, etag: newEtag };
+}
+//# sourceMappingURL=manifest-save.js.map

package/dist/manifest-save.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-save.js","sourceRoot":"","sources":["../src/manifest-save.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,GAEZ,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,gBAAgB,EAAgB,MAAM,wBAAwB,CAAA;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAGhD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AA8M5E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAwB;IAC7D,gEAAgE;IAChE,gEAAgE;IAChE,+DAA+D;IAC/D,mEAAmE;IACnE,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAClC,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC;YACxC,GAAG,KAAK,CAAC,MAAM;YACf,GAAG,KAAK,CAAC,UAAU;SACpB,CAAC,CAAA;QACF,IAAI,WAAW,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE;gBACjD,WAAW;aACZ,CAAA;QACH,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,+DAA+D;IAE/D,kEAAkE;IAClE,mEAAmE;IACnE,+DAA+D;IAC/D,iEAAiE;IACjE,qCAAqC;IACrC,MAAM,MAAM,GAAG,MAAM,YAAY,CAC/B;QACE,IAAI,EAAE;YACJ,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;SAChE;QACD,6DAA6D;QAC7D,2DAA2D;QAC3D,8DAA8D;QAC9D,MAAM,EAAE,KAAK,CAAC,MAAa;QAC3B,8DAA8D;QAC9D,KAAK,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,UAAU,EAAS;QACxD,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,WAAW;QACrC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO;KAC9B,EACD,KAAK,CAAC,UAAU,CACjB,CAAA;IACD,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;YACvB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,mBAAmB;YAC5B,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;YAC7C,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS;SAC9D,CAAC,CAAA;QACF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,CAAA;IACzD,CAAC;IAED,4DAA4D;IAC5D,8DAA8D;IAC9D,8DAA8D;IAC9D,gDAAgD;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;IACzB,MAAM,OAAO,GAAG,KAAK;QACnB,CAAC,CAAC,gBAAgB,CAAC;YACf,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO;YAC7B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,UAAU;YAC/B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE;YACjD,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE;YAC3C,SAAS,EAAE,KAAK,CAAC,aAAa;SAC/B,CAAC;QACJ,CAAC,CAAC,IAAI,CAAA;IACR,MAAM,SAAS,GAAG;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,SAAS;KAClC,CAAA;IACD,IAAI,aAAa,GAA4B,KAAK,CAAC,QAAQ,CAAA;IAC3D,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,aAAa,GAAG,CAAC,MAAM,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAA4B,CAAA;QAClH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,gBAAgB,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;gBAClE,4DAA4D;gBAC5D,qDAAqD;gBACrD,4DAA4D;gBAC5D,0DAA0D;gBAC1D,2DAA2D;gBAC3D,uDAAuD;gBACvD,uDAAuD;gBACvD,0DAA0D;gBAC1D,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;oBACvB,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE,gBAAgB;oBACzB,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;oBAC7C,QAAQ,EAAE;wBACR,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBACjD,aAAa,EAAE,GAAG,YAAY,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;wBACzE,WAAW,EAAE,GAAG,YAAY,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;qBACnE;iBACF,CAAC,CAAA;gBACF,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,IAAI,EAAE,gBAAgB;oBACtB,IAAI,EAAE,GAAG,CAAC,QAAQ;oBAClB,MAAM,EAAE,GAAG,CAAC,OAAO;iBACpB,CAAA;YACH,CAAC;YACD,MAAM,GAAG,CAAA;QACX,CAAC;IACH,CAAC;IACD,iEAAiE;IACjE,kEAAkE;IAClE,8DAA8D;IAC9D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAA;IAEhE,yDAAyD;IACzD,gEAAgE;IAChE,iEAAiE;IACjE,4CAA4C;IAC5C,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,WAAW,CAAC;YAChB,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO;YAC7B,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,WAAW;YACrC,SAAS,EAAE,MAAM;YACjB,KAAK,EAAE;gBACL;oBACE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;oBAC3D,OAAO,EAAE,UAAU;iBACpB;aACF;SACF,CAAC,CAAA;IACJ,CAAC;IAED,0BAA0B;IAC1B,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY,EAAE,UAAU,CAAC,CAAA;IAEpE,+DAA+D;IAC/D,mEAAmE;IACnE,4DAA4D;IAC5D,MAAM,IAAI,GAAY,KAAK,CAAC,MAAM;QAChC,CAAC,CAAC;YACE,MAAM,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU;YACnD,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB;QACH,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;IAC7E,MAAM,OAAO,CAAC,GAAG,CAAC;QAChB,8DAA8D;QAC9D,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,MAAa,EAAE,aAAa,CAAC;QACpF,8DAA8D;QAC9D,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,MAAa,EAAE,aAAa,CAAC;QACvF,8DAA8D;QAC9D,qBAAqB,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,MAAa,EAAE,aAAa,CAAC;KAC1F,CAAC,CAAA;IAEF,iEAAiE;IACjE,4DAA4D;IAC5D,0DAA0D;IAC1D,aAAa;IACb,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEjG,iEAAiE;IACjE,+DAA+D;IAC/D,8DAA8D;IAC9D,0BAA0B;IAC1B,MAAM,SAAS,GAA4B,EAAE,GAAG,aAAa,EAAE,GAAG,KAAK,CAAC,UAAU,EAAE,CAAA;IACpF,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAA;IAEhD,gEAAgE;IAChE,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;QACvB,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,SAAS;QAClB,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;QAC7C,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS;KAC9D,CAAC,CAAA;IAEF,gEAAgE;IAChE,gEAAgE;IAChE,+DAA+D;IAC/D,yDAAyD;IACzD,0BAA0B;IAC1B,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;QACrB,MAAM,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,CAAA;IAC/F,CAAC;IAED,uDAAuD;IACvD,4DAA4D;IAC5D,6DAA6D;IAC7D,eAAe;IAEf,iEAAiE;IACjE,6DAA6D;IAC7D,gEAAgE;IAChE,6DAA6D;IAC7D,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,MAAM,KAAK,GAAgB,KAAK,CAAC,YAAY,IAAI;YAC/C,IAAI,EAAE,UAAU;YAChB,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,YAAY,EAAE;SAC3E,CAAA;QACD,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAClC,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;AACpC,CAAC"}

package/dist/manifest.d.ts

@@ -1,5 +1,4 @@
-import type { FragmentManifest, PageManifest, SiteManifest, StorageProvider } from './types.js';
-export declare function parseSiteManifest(storage: StorageProvider, filePath: string): Promise<SiteManifest>;
+import type { FragmentManifest, PageManifest, StorageProvider } from './types.js';
 export declare function parsePageManifest(storage: StorageProvider, filePath: string): Promise<PageManifest>;
 export declare function parseFragmentManifest(storage: StorageProvider, filePath: string): Promise<FragmentManifest>;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,gBAAgB,EAEhB,YAAY,EACZ,YAAY,EACZ,eAAe,EAChB,MAAM,YAAY,CAAA;AAiDnB,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAazG;AAcD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAazG;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAUjH"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiC,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoEhH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAezG;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAYjH"}