gazetta 0.6.0 → 0.8.0

package/dist/admin-api/routes/publish.js

@@ -2,23 +2,92 @@ import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 import { getType, getEnvironment, isEditable, isHistoryEnabled, getHistoryRetention } from '../../types.js';
 import { publishItems, resolveDependencies, findFragmentDependents, findDependentsFromSidecars } from '../../publish.js';
-import { mapLimitStream } from '../../concurrency.js';
-import { publishPageStatic, publishSiteManifest, publishFragmentIndex, createCloudflarePurge, lookupCloudflareZoneId, } from '../../publish-rendered.js';
+import { createCloudflarePurge, lookupCloudflareZoneId } from '../../publish-rendered.js';
 import { loadSiteFromSource } from '../source-context.js';
-import { publishPageAllLocales, publishFragmentAllLocales } from '../../publish-locale.js';
 import { resolveEnvVars } from '../../targets.js';
-import { scanTemplates, templateHashesFrom } from '../../templates-scan.js';
-import { hashManifest } from '../../hash.js';
+import { isAltAdapterConfigured } from '../../alt/factory.js';
+import { resolveAltConfig } from '../../alt/config.js';
+import { inspectTarget } from '../../runtime/runtime-capabilities.js';
+import { scanTemplates } from '../../templates-scan.js';
 import { createContentRoot } from '../../content-root.js';
 import { createHistoryProvider } from '../../history-provider.js';
 import { recordWrite } from '../../history-recorder.js';
+import { requireCapability } from '../middleware/capability.js';
+import { buildHookContext, dispatchAfterPublish, dispatchBeforePublish, HookCancellation, HookTimeout, } from '../../hooks/index.js';
+import { makeAuditFiringEmitter } from '../hook-audit-emitter.js';
+import { runPublishAudit } from '../../validation/publish-audit.js';
 export function publishRoutes(resolve, preInitTargets, targetConfigs, templatesDir, 
 // Optional injected scanner — the admin-api server memoizes it and
 // clears the cache via its template file watcher. Default: fresh scan
 // on every call (used by the CLI and tests).
-scanTemplatesInjected) {
+scanTemplatesInjected, opts = {}) {
     const scan = scanTemplatesInjected ?? scanTemplates;
+    const hooks = opts.hooks;
     const app = new Hono();
+    /**
+     * Categorize an item path into the hook payload shape.
+     * Items arrive as e.g. `pages/home`, `fragments/header`,
+     * `assets/hero`. Hooks see kind + name + path; if the prefix
+     * doesn't match, default to 'asset' (covers loose path forms).
+     */
+    function toPublishItem(itemPath) {
+        if (itemPath.startsWith('pages/')) {
+            return { kind: 'page', name: itemPath.slice('pages/'.length), path: itemPath };
+        }
+        if (itemPath.startsWith('fragments/')) {
+            return { kind: 'fragment', name: itemPath.slice('fragments/'.length), path: itemPath };
+        }
+        return {
+            kind: 'asset',
+            name: itemPath.startsWith('assets/') ? itemPath.slice('assets/'.length) : itemPath,
+            path: itemPath,
+        };
+    }
+    /**
+     * Server-side publish gate (Validation Cut 4).
+     *
+     * Runs `runPublishAudit` for every (target × items) pair the request is
+     * asking to publish, applies the per-target `publishAudit.strict`
+     * promotion, and returns any error-severity issues. The publish
+     * handlers refuse with 409 when this returns non-empty results — the
+     * client-side audit modal is the polite UX, this gate is the
+     * enforcement layer so a determined client can't bypass.
+     *
+     * Returns `{ target, issues }` per target that produced errors. Targets
+     * with only warns/infos are omitted (errors-only gate).
+     */
+    async function evaluatePublishGate(source, targetNames, itemPaths) {
+        if (!opts.validators)
+            return [];
+        const items = [];
+        for (const p of itemPaths) {
+            const i = toPublishItem(p);
+            if (i.kind === 'page' || i.kind === 'fragment')
+                items.push({ kind: i.kind, name: i.name });
+        }
+        if (items.length === 0)
+            return [];
+        const site = await loadSiteFromSource(source);
+        const blocked = [];
+        for (const targetName of targetNames) {
+            const targetCfg = source.manifest?.targets?.[targetName];
+            const strict = !!targetCfg?.publishAudit?.strict;
+            const issues = await runPublishAudit({
+                items,
+                site,
+                contentRoot: source.contentRoot,
+                storage: source.storage,
+                registry: opts.validators,
+                cache: source.cache,
+                strict,
+                templatesDir: site.templatesDir,
+            });
+            const errors = issues.filter(i => i.severity === 'error');
+            if (errors.length > 0)
+                blocked.push({ target: targetName, issues: errors });
+        }
+        return blocked;
+    }
     // Background target initialization — lazy, needs the resolved source's
     // projectSiteDir to resolve filesystem target paths. We call resolve()
     // once with undefined (→ default editable) to obtain projectSiteDir.
@@ -35,7 +104,7 @@ scanTemplatesInjected) {
             initPromise = (async () => {
                 const { createTargetRegistry } = await import('../../targets.js');
                 const bootstrapSource = await resolve(undefined);
-                const t = await createTargetRegistry(targetConfigs, bootstrapSource.projectSiteDir);
+                const t = await createTargetRegistry(targetConfigs);
                 targets = t;
                 return t;
             })().catch(() => {
@@ -48,15 +117,76 @@ scanTemplatesInjected) {
     function getTargetConfig(name) {
         return targetConfigs?.[name];
     }
-    app.get('/api/targets', async (c) => {
+    // First-time dependents lookup against a source target needs the
+    // `.gazetta/fragment-deps/` index to be present. Save handlers write
+    // it incrementally on every save, but a fresh dev server pointed at
+    // a content tree that's never been saved through admin will have an
+    // empty index. Rebuild once per (source-target) and memoize the
+    // in-flight Promise so concurrent tree badges share one walk.
+    const fragmentDepsBackfill = new Map();
+    async function ensureFragmentDepsIndex(source) {
+        const key = source.targetName ?? '__source__';
+        let p = fragmentDepsBackfill.get(key);
+        if (p)
+            return p;
+        p = (async () => {
+            const indexRoot = source.contentRoot.path('.gazetta', 'fragment-deps');
+            // Cheap existence probe — if any entry is present, the index has
+            // been written at least once and incremental save handlers keep
+            // it consistent thereafter.
+            const exists = await source.storage.exists(indexRoot);
+            if (exists)
+                return;
+            const { rebuildDepIndex } = await import('../../publish-rendered.js');
+            const { FRAGMENT_DEPS } = await import('../../fragment-deps.js');
+            const site = await loadSiteFromSource(source);
+            await rebuildDepIndex(FRAGMENT_DEPS, site, source.storage, source.contentRoot.rootPath);
+        })().catch(err => {
+            // Clear on failure so the next caller retries.
+            fragmentDepsBackfill.delete(key);
+            throw err;
+        });
+        fragmentDepsBackfill.set(key, p);
+        return p;
+    }
+    app.get('/api/targets', requireCapability('read:pages'), async (c) => {
         const t = await getTargets();
+        // Resolve once — the site manifest is the same across all
+        // targets in this loop. resolve(undefined) returns the source
+        // context whose .manifest holds `ai:` and `altText:`.
+        const source = await resolve(undefined);
+        const site = source.manifest;
         return c.json([...t.keys()].map(name => {
             const cfg = getTargetConfig(name);
+            // AI alt-text capability — site + target inherit chain. When
+            // the site manifest isn't available (legacy/test setups), the
+            // feature is reported off uniformly.
+            const altResolved = site ? resolveAltConfig(site, cfg) : null;
+            const altAvailable = site ? isAltAdapterConfigured(site, cfg) : false;
+            // Runtime capability inspection per
+            // `feature-design-process.md`'s capability-gap UX discipline
+            // (surface #2 — author-time modal data source). The admin
+            // archive modal renders per-target capability badges from
+            // these fields; Cut 10 wires the UI.
+            const inspection = cfg
+                ? inspectTarget(cfg)
+                : { has: new Set(), gaps: [] };
             return {
                 name,
                 environment: cfg ? getEnvironment(cfg) : 'local',
                 type: cfg ? getType(cfg) : 'static',
                 editable: cfg ? isEditable(cfg) : true,
+                altText: {
+                    available: altAvailable,
+                    // When not configured, the resolved value is null — surface
+                    // false rather than the hardcoded default so the UI doesn't
+                    // imply "auto-fire is on" for an unconfigured target.
+                    auto: altResolved?.auto ?? false,
+                },
+                capabilities: {
+                    has: [...inspection.has],
+                    gaps: inspection.gaps.map(g => ({ capability: g.capability, reason: g.reason })),
+                },
             };
         }));
     });
@@ -65,37 +195,23 @@ scanTemplatesInjected) {
      * GET /api/dependents?item=fragments/header[&target=staging]
      *   → { pages: string[], fragments: string[] }
      *
-     * Without `target`: scans local source manifests (authoritative for the
-     * current draft state — what's about to be published). Slow-ish on very
-     * large sites since it reads every manifest.
-     *
-     * With `target`: uses published .uses-* / .tpl-* sidecars on that target.
-     * Listings only, no content reads — scales to 10k+ items at the cost of
-     * reflecting only what's been published (not unsaved local changes).
-     * Useful for answering "what pages would need republish if this fragment
-     * changed" on large sites.
+     * Reads `.gazetta/fragment-deps/` per-edge sidecars on the requested
+     * target (or the source when `target` is omitted or names the source).
+     * Save handlers maintain the index incrementally; a fresh dev server
+     * with no prior saves triggers a one-time rebuild via
+     * `ensureFragmentDepsIndex`. Listings only, no content reads —
+     * scales to 10k+ items.
      */
-    app.get('/api/dependents', async (c) => {
+    app.get('/api/dependents', requireCapability('read:pages'), async (c) => {
         const item = c.req.query('item');
         if (!item || !item.startsWith('fragments/')) {
             return c.json({ error: 'Missing or invalid "item" query (must be fragments/<name>)' }, 400);
         }
         const fragmentName = item.slice('fragments/'.length);
-        // `target`  — specific published target's sidecars (read-only listing).
-        //              Useful for "what would need republish on staging?" queries
-        //              where sidecars reflect the last publish, not the draft.
-        // `source`  — the editable source target (authoritative for the draft).
-        //              When target === source (common case: client sends the
-        //              active editable target), route through source so the
-        //              sidecar writer can backfill missing entries.
         const targetName = c.req.query('target');
         const sourceName = c.req.query('source');
         try {
             const source = await resolve(sourceName);
-            // Treat `target=local` (the active editable target) the same as no
-            // target — the source path is the authoritative one for the draft,
-            // and it's the only path that knows how to backfill sidecars on a
-            // fresh dev server.
             const isTargetTheSource = !targetName || targetName === source.targetName;
             if (!isTargetTheSource) {
                 const t = await getTargets();
@@ -105,17 +221,8 @@ scanTemplatesInjected) {
                 const result = await findDependentsFromSidecars(createContentRoot(targetStorage), { fragment: fragmentName });
                 return c.json(result);
             }
-            // Source-side path: ensure every item has a sidecar before reading.
-            // The writer memoizes the backfill — concurrent tree badges on a
-            // fresh dev server share one pass instead of racing to an empty index.
-            const sidecarWriter = source.sidecarWriter;
-            if (sidecarWriter) {
-                await sidecarWriter.ensureBackfilled();
-                const result = await findDependentsFromSidecars(source.contentRoot, { fragment: fragmentName });
-                return c.json(result);
-            }
-            // No writer injected (legacy setup) — fall back to the manifest walker.
-            const result = await findFragmentDependents(source.contentRoot, fragmentName);
+            await ensureFragmentDepsIndex(source);
+            const result = await findDependentsFromSidecars(source.contentRoot, { fragment: fragmentName });
             return c.json(result);
         }
         catch (err) {
@@ -174,7 +281,9 @@ scanTemplatesInjected) {
             };
             return;
         }
-        const templateHashes = templateHashesFrom(templateInfos);
+        // Per Cut 7 cutover: per-item hash composition lives inside publishRun
+        // (consumes templateInfos, computes per-item hashManifest including
+        // fragmentHashes for static-mode pages). Route doesn't precompute.
         const site = await loadSiteFromSource(source, { templatesDir: tdir });
         yield { kind: 'start', targets: targetNames, itemsPerTarget: allItems.length };
         const results = [];
@@ -204,6 +313,12 @@ scanTemplatesInjected) {
             const total = 1 + targetItems.length + 1 + (purgeConfig?.type === 'cloudflare' ? 1 : 0);
             yield { kind: 'target-start', target: targetName, total };
             let current = 0;
+            // Buffer for publishRun's progress events. The route's outer
+            // generator yields SSE frames; publishRun's onProgress callback
+            // can't yield directly (different generator). Push events into
+            // this queue inside the callback; drain after publishRun resolves.
+            // Order preserved (publishRun runs items sequentially per target).
+            const progressQueue = [];
             try {
                 let totalFiles = 0;
                 const targetRoot = createContentRoot(targetStorage);
@@ -238,63 +353,92 @@ scanTemplatesInjected) {
                 totalFiles += copiedFiles;
                 current++;
                 yield { kind: 'progress', target: targetName, current, total, label: 'source files' };
-                // 2. Render items in bounded parallel. Progress events are yielded
-                // in completion order — the UI shows X/N + whatever finished last,
-                // which stays meaningful without needing input-order. Preserves the
-                // event contract: one 'progress' per item between 'target-start'
-                // and 'target-result'.
-                // Static-mode page hashes must include fragment hashes (a fragment
-                // change invalidates every page that bakes it in). Matches the
-                // combination used by compareTargets.
-                const fragmentHashes = new Map();
-                if (isStatic) {
-                    for (const [fragName, frag] of site.fragments) {
-                        fragmentHashes.set(fragName, hashManifest(frag, { templateHashes }));
-                    }
-                }
-                const pageHashOpts = isStatic ? { templateHashes, fragmentHashes } : { templateHashes };
-                // SEO context for this target — built once, shared across all page renders.
-                const seo = {
-                    siteName: site.manifest.name,
-                    siteUrl: config?.siteUrl,
-                    locale: site.manifest.locale,
-                    defaultOgImage: site.manifest.defaultOgImage,
-                };
-                const renderItem = async (item) => {
-                    if (item.startsWith('pages/')) {
-                        const raw = item.replace('pages/', '');
-                        // Support locale-qualified items: pages/home:fr → publish only FR
-                        const [pageName, itemLocale] = raw.includes(':') ? raw.split(':') : [raw, undefined];
-                        const page = site.pages.get(pageName);
-                        const manifestHash = page ? hashManifest(page, pageHashOpts) : undefined;
-                        if (isStatic) {
-                            return publishPageStatic(pageName, source.contentRoot, targetStorage, tdir, manifestHash, site, seo, itemLocale);
+                // Cutover (Cut 7 of publish-pipeline-extraction): asset publish +
+                // per-item render loop + dep indices + site manifest now go through
+                // `publishRun`. The route keeps history record (above), source-copy
+                // (publishItems above), sitemap/robots/redirects/purge (below) and
+                // the SSE progress emit. publishRun's onProgress feeds the SSE
+                // generator one progress event per item-done; admin's UI counts
+                // items toward `total`.
+                //
+                // Item-string layout (`pages/home:fr`) split into ItemRefs. Static
+                // targets emit only page items (fragments are baked); ESI emits
+                // both. Static-mode page hash composition (fragmentHashes) is
+                // handled inside publishRun when templateInfos is supplied.
+                const itemRefs = [];
+                for (const it of targetItems) {
+                    if (it.startsWith('pages/')) {
+                        const raw = it.replace('pages/', '');
+                        const [name, locale] = raw.includes(':') ? raw.split(':') : [raw, undefined];
+                        // Locale-qualified: just the requested variant. Else: default
+                        // + every supported locale (subject to target.locales filter).
+                        if (locale) {
+                            itemRefs.push({ kind: 'page', name, locale });
+                        }
+                        else {
+                            itemRefs.push({ kind: 'page', name });
+                            const pageLocales = site.pageLocales.get(name);
+                            if (pageLocales) {
+                                for (const loc of pageLocales.locales.keys()) {
+                                    if (config?.locales && !config.locales.includes(loc))
+                                        continue;
+                                    itemRefs.push({ kind: 'page', name, locale: loc });
+                                }
+                            }
                         }
-                        // When a specific locale is requested, only publish that one
-                        const onlyLocales = itemLocale ? [itemLocale] : undefined;
-                        const { files } = await publishPageAllLocales(pageName, source.contentRoot, targetStorage, site, pageHashOpts, { cache: config?.cache, templatesDir: tdir, seo, targetLocales: onlyLocales ?? config?.locales });
-                        return { files };
                     }
-                    if (item.startsWith('fragments/') && !isStatic) {
-                        const raw = item.replace('fragments/', '');
-                        const [fragName, itemLocale] = raw.includes(':') ? raw.split(':') : [raw, undefined];
-                        const onlyLocales = itemLocale ? [itemLocale] : undefined;
-                        const { files } = await publishFragmentAllLocales(fragName, source.contentRoot, targetStorage, site, { templateHashes }, { templatesDir: tdir, targetLocales: onlyLocales ?? config?.locales });
-                        return { files };
+                    else if (it.startsWith('fragments/') && !isStatic) {
+                        const raw = it.replace('fragments/', '');
+                        const [name, locale] = raw.includes(':') ? raw.split(':') : [raw, undefined];
+                        if (locale) {
+                            itemRefs.push({ kind: 'fragment', name, locale });
+                        }
+                        else {
+                            itemRefs.push({ kind: 'fragment', name });
+                            const fragLocales = site.fragmentLocales.get(name);
+                            if (fragLocales) {
+                                for (const loc of fragLocales.locales.keys()) {
+                                    if (config?.locales && !config.locales.includes(loc))
+                                        continue;
+                                    itemRefs.push({ kind: 'fragment', name, locale: loc });
+                                }
+                            }
+                        }
                     }
-                    return { files: 0 }; // skipped (e.g. fragment on static target)
-                };
-                // Render concurrency is lower than listing concurrency — each render
-                // may do multiple writes, so 10 in flight is the safe default.
-                for await (const { item, result } of mapLimitStream(targetItems, renderItem, 10)) {
-                    totalFiles += result.files;
-                    current++;
-                    yield { kind: 'progress', target: targetName, current, total, label: item };
                 }
-                // 3. Site manifest + fragment index
-                await publishSiteManifest(source.contentRoot, targetStorage, site);
-                await publishFragmentIndex(source.contentRoot, targetStorage, site);
-                totalFiles += 2;
+                const { publishRun } = await import('../../publish-run.js');
+                const runResult = await publishRun({
+                    items: itemRefs,
+                    targets: [targetName],
+                    site,
+                    sourceRoot: source.contentRoot,
+                    siteManifest: source.manifest ?? { name: '(publish)' },
+                    targetStorages: new Map([[targetName, targetStorage]]),
+                    templateInfos,
+                    onProgress: ev => {
+                        if (ev.kind === 'item-done') {
+                            const label = (ev.result.kind === 'fragment' ? `@${ev.result.name}` : `pages/${ev.result.name}`) +
+                                (ev.result.locale ? `:${ev.result.locale}` : '');
+                            current++;
+                            // SSE consumer reads per-item progress; admin UI updates X/N.
+                            // Yield is bridged via the outer generator below.
+                            progressQueue.push({ kind: 'progress', target: targetName, current, total, label });
+                        }
+                    },
+                });
+                // publishRun doesn't throw on per-target init failure (assets
+                // missing → target failed); surface as the same error the inline
+                // path used to throw so the per-target try/catch projects to
+                // `target-result success: false`.
+                const tr = runResult.targets.find(t => t.name === targetName);
+                if (tr?.failed) {
+                    throw new Error(tr.failureReason ?? 'all items failed');
+                }
+                totalFiles += tr?.filesWritten ?? 0;
+                // Drain queued progress events from the publishRun callback.
+                for (const ev of progressQueue)
+                    yield ev;
+                progressQueue.length = 0;
                 current++;
                 yield { kind: 'progress', target: targetName, current, total, label: 'site manifest' };
                 // 3b. Sitemap + robots.txt
@@ -327,6 +471,34 @@ scanTemplatesInjected) {
                         totalFiles++;
                     }
                 }
+                // 3c. Host-format redirects file (e.g. _redirects). Per
+                // design-soft-delete.md Q10: plain-static targets without a
+                // worker can't read the per-page HTML marker; this file is the
+                // host glue for archive-driven redirects. Independent of
+                // siteUrl — the format determines whether to emit at all.
+                const redirectsFormat = config?.redirects?.format;
+                if (redirectsFormat && redirectsFormat !== 'none') {
+                    const { emitRedirects } = await import('../../runtime/redirects-emit.js');
+                    const { allPageEntries, deriveRoute } = await import('../../site-loader.js');
+                    const archives = [];
+                    for (const entry of allPageEntries(site)) {
+                        if (entry.page.archived !== true)
+                            continue;
+                        // Locale variants share the parent's archive state in v1
+                        // (per design-soft-delete.md future directions). Default-
+                        // locale row is the canonical entry.
+                        if (entry.locale)
+                            continue;
+                        const from = deriveRoute(entry.name);
+                        const to = entry.page.aliasOf ? deriveRoute(entry.page.aliasOf) : undefined;
+                        archives.push(to !== undefined ? { from, to } : { from });
+                    }
+                    const result = emitRedirects(redirectsFormat, archives);
+                    if (result && result.body !== '') {
+                        await targetStorage.writeFile(result.filename, result.body);
+                        totalFiles++;
+                    }
+                }
                 // 4. Purge CDN cache
                 if (purgeConfig?.type === 'cloudflare') {
                     const apiToken = resolveEnvVars(purgeConfig.apiToken);
@@ -362,6 +534,25 @@ scanTemplatesInjected) {
                 const result = { target: targetName, success: true, copiedFiles: totalFiles };
                 results.push(result);
                 console.log(`    ${targetName}: ${totalFiles} files`);
+                // Publish wrote new manifests to the target's storage. Any
+                // SourceContext for that target has a stale cached page /
+                // fragment summary. Resolve the target's SourceContext (if
+                // the resolver has built one) and invalidate. Cheap; covers
+                // the case where the admin UI's active target is the publish
+                // destination and the next /api/pages should reflect the
+                // newly-published items.
+                try {
+                    const targetSource = await resolve(targetName);
+                    await Promise.all([
+                        targetSource.cache.invalidatePrefix('pages:'),
+                        targetSource.cache.invalidatePrefix('fragments:'),
+                    ]);
+                }
+                catch {
+                    // Resolver may not know this target (registry not configured;
+                    // legacy single-target setup). Cache invalidation is best-
+                    // effort; ignore.
+                }
                 yield { kind: 'target-result', result };
             }
             catch (err) {
@@ -374,11 +565,87 @@ scanTemplatesInjected) {
         }
         yield { kind: 'done', results };
     }
-    app.post('/api/publish', async (c) => {
+    // Publish routes gate on `publish:non-production` as the baseline.
+    // Production-target gating runs inside the handler when iterating
+    // requested targets (per design-auth-rbac.md "Failure mode": publish
+    // to a production target requires `publish:production`). Cut 9
+    // ships the route-level gate; per-target enforcement lands when
+    // the route is rewritten to consult the resolved target's
+    // environment field.
+    app.post('/api/publish', requireCapability('publish:non-production'), async (c) => {
         const body = (await c.req.json());
+        // beforePublish hooks per design-hooks.md "Publish lifecycle".
+        // Hooks see the requested items + active target; can mutate
+        // the item set (drop / reorder / extend) or throw to cancel
+        // the operation. One dispatch per target — operators wanting
+        // per-target item filtering branch on `target` inside their
+        // handler.
+        const hookCtx = hooks
+            ? buildHookContext({
+                principal: c.var.principal,
+                storage: (await resolve(body.source)).storage,
+                requestId: c.req.header('x-request-id') ?? crypto.randomUUID(),
+                site: { name: undefined },
+                auditEmit: makeAuditFiringEmitter(c.var.audit),
+            })
+            : null;
+        let finalItems = body.items;
+        if (hooks && hookCtx) {
+            try {
+                const inputItems = body.items.map(toPublishItem);
+                // Dispatch once per target. Cancellation by any handler
+                // aborts the entire publish (multi-target).
+                let mutated = inputItems;
+                for (const target of body.targets) {
+                    mutated = await dispatchBeforePublish(hooks, target, mutated, hookCtx);
+                }
+                finalItems = mutated.map(i => i.path);
+            }
+            catch (err) {
+                if (err instanceof HookCancellation || err instanceof HookTimeout) {
+                    // Per design-hooks.md Q3 audit lock: cancelled publishes
+                    // record outcome 'hook-cancelled' (not 'forbidden' — hook
+                    // policy is operator decision, not a capability denial).
+                    await c.var.audit.record({
+                        action: 'publish',
+                        outcome: 'hook-cancelled',
+                        scope: { kind: 'site' },
+                        metadata: {
+                            items: body.items,
+                            targets: body.targets,
+                            source: body.source,
+                            hookCancelled: err instanceof HookCancellation ? err.hookName : undefined,
+                            hookTimeout: err instanceof HookTimeout ? err.hookName : undefined,
+                        },
+                    });
+                    return c.json({ code: 'HOOK_CANCELLED', hook: err.hookName, reason: err.message }, 409);
+                }
+                throw err;
+            }
+        }
+        // Server-side publish gate per design-validation.md Cut 4. Runs the
+        // same `runPublishAudit` the client-side modal calls; refuses on
+        // remaining error-severity issues so a determined client can't
+        // bypass the dialog. `publishAudit.strict` is applied per-target.
+        const sourceForGate = await resolve(body.source);
+        const blocked = await evaluatePublishGate(sourceForGate, body.targets, finalItems);
+        if (blocked.length > 0) {
+            await c.var.audit.record({
+                action: 'publish',
+                outcome: 'validation-failed',
+                scope: { kind: 'site' },
+                metadata: {
+                    items: finalItems,
+                    targets: body.targets,
+                    source: body.source,
+                    blockedTargets: blocked.map(b => b.target),
+                },
+            });
+            return c.json({ code: 'PUBLISH_AUDIT_FAILED', blocked }, 409);
+        }
         let results = [];
         let fatal = null;
-        for await (const ev of runPublish(body.items, body.targets, body.source)) {
+        for await (const ev of runPublish(finalItems, body.targets, body.source)) {
             if (ev.kind === 'fatal')
                 fatal = ev;
             else if (ev.kind === 'done')
@@ -389,16 +656,115 @@ scanTemplatesInjected) {
             return c.json({ error: fatal.error, ...(fatal.invalidTemplates ? { invalidTemplates: fatal.invalidTemplates } : {}) }, status);
         }
         const allSuccess = results.every(r => r.success);
+        // Audit: one event per publish operation. metadata carries the
+        // requested items + targets for forensic queries; per-item
+        // events would explode volume on multi-item publishes.
+        await c.var.audit.record({
+            action: 'publish',
+            outcome: 'success',
+            scope: { kind: 'site' },
+            metadata: { items: finalItems, targets: body.targets, source: body.source },
+        });
+        // afterPublish hooks per design-hooks.md "Publish lifecycle"
+        // step 5. Observational; failures logged. One dispatch per
+        // target with that target's per-target result.
+        if (hooks && hookCtx) {
+            const finalPublishItems = finalItems.map(toPublishItem);
+            for (const r of results) {
+                const hookResult = {
+                    target: r.target,
+                    itemsPublished: r.success ? finalPublishItems : [],
+                    itemsFailed: r.success ? [] : finalPublishItems.map(item => ({ item, reason: r.error ?? 'unknown' })),
+                };
+                await dispatchAfterPublish(hooks, r.target, hookResult, hookCtx);
+            }
+        }
         return c.json({ results }, allSuccess ? 200 : 207);
     });
-    app.post('/api/publish/stream', async (c) => {
+    app.post('/api/publish/stream', requireCapability('publish:non-production'), async (c) => {
         const body = (await c.req.json());
+        // beforePublish hooks fire BEFORE the SSE stream opens — a
+        // cancellation surfaces as a 409 (synchronous) rather than as
+        // an SSE 'fatal' event, matching the sync /api/publish path.
+        const hookCtx = hooks
+            ? buildHookContext({
+                principal: c.var.principal,
+                storage: (await resolve(body.source)).storage,
+                requestId: c.req.header('x-request-id') ?? crypto.randomUUID(),
+                site: { name: undefined },
+                auditEmit: makeAuditFiringEmitter(c.var.audit),
+            })
+            : null;
+        let finalItems = body.items;
+        if (hooks && hookCtx) {
+            try {
+                let mutated = body.items.map(toPublishItem);
+                for (const target of body.targets) {
+                    mutated = await dispatchBeforePublish(hooks, target, mutated, hookCtx);
+                }
+                finalItems = mutated.map(i => i.path);
+            }
+            catch (err) {
+                if (err instanceof HookCancellation || err instanceof HookTimeout) {
+                    // Per design-hooks.md Q3 audit lock: cancelled publishes
+                    // record outcome 'hook-cancelled' (not 'forbidden' — hook
+                    // policy is operator decision, not a capability denial).
+                    await c.var.audit.record({
+                        action: 'publish',
+                        outcome: 'hook-cancelled',
+                        scope: { kind: 'site' },
+                        metadata: {
+                            items: body.items,
+                            targets: body.targets,
+                            source: body.source,
+                            hookCancelled: err instanceof HookCancellation ? err.hookName : undefined,
+                            hookTimeout: err instanceof HookTimeout ? err.hookName : undefined,
+                        },
+                    });
+                    return c.json({ code: 'HOOK_CANCELLED', hook: err.hookName, reason: err.message }, 409);
+                }
+                throw err;
+            }
+        }
+        // Server-side publish gate (mirrors /api/publish). Surfaces as a
+        // synchronous 409 before the SSE stream opens, so the client can
+        // treat audit-failure identically across the two endpoints.
+        const sourceForGate = await resolve(body.source);
+        const blocked = await evaluatePublishGate(sourceForGate, body.targets, finalItems);
+        if (blocked.length > 0) {
+            await c.var.audit.record({
+                action: 'publish',
+                outcome: 'validation-failed',
+                scope: { kind: 'site' },
+                metadata: {
+                    items: finalItems,
+                    targets: body.targets,
+                    source: body.source,
+                    blockedTargets: blocked.map(b => b.target),
+                },
+            });
+            return c.json({ code: 'PUBLISH_AUDIT_FAILED', blocked }, 409);
+        }
         return streamSSE(c, async (stream) => {
+            let recordedSuccess = false;
+            const collectedResults = [];
             try {
-                for await (const ev of runPublish(body.items, body.targets, body.source)) {
+                for await (const ev of runPublish(finalItems, body.targets, body.source)) {
                     if (stream.aborted)
                         return;
                     await stream.writeSSE({ event: ev.kind, data: JSON.stringify(ev) });
+                    if (ev.kind === 'done') {
+                        // Record once per stream — same shape as the
+                        // synchronous /api/publish endpoint.
+                        await c.var.audit.record({
+                            action: 'publish',
+                            outcome: 'success',
+                            scope: { kind: 'site' },
+                            metadata: { items: finalItems, targets: body.targets, source: body.source },
+                        });
+                        recordedSuccess = true;
+                        collectedResults.push(...ev.results);
+                    }
                 }
             }
             catch (err) {
@@ -409,9 +775,28 @@ scanTemplatesInjected) {
                     });
                 }
             }
+            // afterPublish hooks fire after the stream's `done` event —
+            // observational; failures logged via ctx.log without
+            // affecting the already-streamed response.
+            if (hooks && hookCtx && recordedSuccess) {
+                const finalPublishItems = finalItems.map(toPublishItem);
+                for (const r of collectedResults) {
+                    const hookResult = {
+                        target: r.target,
+                        itemsPublished: r.success ? finalPublishItems : [],
+                        itemsFailed: r.success ? [] : finalPublishItems.map(item => ({ item, reason: r.error ?? 'unknown' })),
+                    };
+                    await dispatchAfterPublish(hooks, r.target, hookResult, hookCtx);
+                }
+            }
+            // Avoid recording a duplicate when the loop completed without
+            // a 'done' event (rare — happens if runPublish yields fatal
+            // before done). Suppresses double-audit; the absence of a
+            // success event is itself the forensic signal.
+            void recordedSuccess;
         });
     });
-    app.post('/api/fetch', async (c) => {
+    app.post('/api/fetch', requireCapability('publish:non-production'), async (c) => {
         // `source` (body) — target to fetch FROM (a published target)
         // `destination` (body) — optional editable target to write INTO; defaults
         // to the resolver's default editable target (the author's current source)
@@ -479,6 +864,70 @@ scanTemplatesInjected) {
             return c.json({ error }, 500);
         }
     });
+    /**
+     * POST /api/publish/audit — runs pre-publish-stage validators against the
+     * items operator is about to publish. Returns the consolidated `Issue[]`,
+     * with `publishAudit.strict` promotion already applied (warns → errors)
+     * for the destination target.
+     *
+     * The audit is read-only: it doesn't write to storage, doesn't fire hooks,
+     * doesn't trigger publish. It's the pre-flight check the publish dialog
+     * surfaces before the user clicks "Publish."
+     *
+     * Server-side enforcement of the audit happens at `POST /api/publish` —
+     * this endpoint is the read surface; the gate is the publish handler
+     * itself. Defense in depth: client-side dialog uses this endpoint for
+     * display; server-side publish re-runs the same audit and refuses on
+     * errors, so a determined client can't bypass.
+     */
+    app.post('/api/publish/audit', requireCapability('publish:non-production'), async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (!body || typeof body !== 'object') {
+            return c.json({ error: 'invalid request body' }, 400);
+        }
+        const targetName = body.target;
+        const items = body.items;
+        if (typeof targetName !== 'string' || !Array.isArray(items)) {
+            return c.json({ error: 'expected { target: string, items: SavedItem[] }' }, 400);
+        }
+        const source = await resolve(c.req.query('target'));
+        const site = await loadSiteFromSource(source);
+        const targetCfg = source.manifest?.targets?.[targetName];
+        const strict = !!targetCfg?.publishAudit?.strict;
+        if (!opts.validators) {
+            // No validator registry wired; return empty issues.
+            return c.json({ issues: [], strict });
+        }
+        const issues = await runPublishAudit({
+            items: items,
+            site,
+            contentRoot: source.contentRoot,
+            storage: source.storage,
+            registry: opts.validators,
+            cache: source.cache,
+            strict,
+            templatesDir: site.templatesDir,
+        });
+        // Capability-gap UX surface #4 (pre-publish gate) per
+        // `feature-design-process.md`'s capability-gap-UX discipline.
+        // When the publish set includes any archived items, surface the
+        // destination target's capability info so the publish dialog can
+        // warn operators (e.g., "this target won't emit 301 redirects").
+        const itemList = items;
+        const includesArchived = itemList.some(i => {
+            const m = i.kind === 'page' ? site.pages.get(i.name) : site.fragments.get(i.name);
+            return m?.archived === true;
+        });
+        let capabilities;
+        if (includesArchived && targetCfg) {
+            const inspection = inspectTarget(targetCfg);
+            capabilities = {
+                has: [...inspection.has],
+                gaps: inspection.gaps.map(g => ({ capability: g.capability, reason: g.reason })),
+            };
+        }
+        return c.json({ issues, strict, ...(capabilities ? { capabilities } : {}) });
+    });
     return app;
 }
 /**