@duffcloudservices/cms 0.13.13 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
- import { H as SeoConfiguration, x as BreadcrumbCrumb, z as ReviewSource, F as FaqSource, y as BlogMeta, T as ResolvedPageSeo, N as SeoSchemaConfig, G as GlobalSeoConfig, L as SeoOpenGraphConfig, M as SeoTwitterConfig } from './vitepressTransform-CZ_IB3dq.js';
1
+ import { d as BreadcrumbCrumb, k as ReviewSource, i as FaqSource, B as BlogMeta, j as ResolvedPageSeo, p as SeoConfiguration, u as SeoSchemaConfig, G as GlobalSeoConfig, r as SeoOpenGraphConfig, w as SeoTwitterConfig } from './vitepressTransform-CQXBpYEC.js';
2
2
 
3
3
  /**
4
4
  * Framework-agnostic SEO head-tag resolution.
@@ -675,4 +675,4 @@ declare function buildSeoHeadRouteMap(routes: readonly SeoHeadPageRoute[]): Map<
675
675
  */
676
676
  declare function installSeoHead(router: SeoHeadRouterLike, options: InstallSeoHeadOptions): unknown;
677
677
 
678
- export { formatDuplicateNormalizedPaths as A, SEO_HEAD_ROUTE_HAS_NO_META as B, type SeoHeadRouteHasNoMeta as C, type HeadMetaTag as H, type InstallSeoHeadOptions as I, type ResolvedHeadTags as R, type SeoHeadRouterLike as S, generateOpenGraphMeta as a, buildHeadTags as b, generateTwitterMeta as c, renderHeadTags as d, stripManagedHeadTags as e, escapeJsonLd as f, generateJsonLd as g, isManagedLinkRel as h, isManagedMetaTag as i, installSeoHead as j, buildSeoHeadRouteMap as k, type HeadLinkTag as l, type HeadScriptTag as m, normalizeSeoHeadPath as n, type HeadTagOverrides as o, type SeoHeadRouteLike as p, type SeoHeadClientLike as q, resolvePageSeo as r, spliceHeadHtml as s, type SeoHeadEntryLike as t, type SeoHeadInput as u, type SeoHeadPageRoute as v, type SeoHeadPagesManifest as w, type SeoHeadResolution as x, type SeoHeadResolutionReason as y, findDuplicateNormalizedPaths as z };
678
+ export { type SeoHeadRouteHasNoMeta as A, findDuplicateNormalizedPaths as B, formatDuplicateNormalizedPaths as C, type HeadLinkTag as H, type InstallSeoHeadOptions as I, type ResolvedHeadTags as R, type SeoHeadClientLike as S, type HeadMetaTag as a, type HeadScriptTag as b, type HeadTagOverrides as c, type SeoHeadEntryLike as d, type SeoHeadInput as e, type SeoHeadPageRoute as f, type SeoHeadPagesManifest as g, type SeoHeadResolution as h, type SeoHeadResolutionReason as i, type SeoHeadRouteLike as j, type SeoHeadRouterLike as k, buildHeadTags as l, buildSeoHeadRouteMap as m, escapeJsonLd as n, generateJsonLd as o, generateOpenGraphMeta as p, generateTwitterMeta as q, installSeoHead as r, isManagedLinkRel as s, isManagedMetaTag as t, normalizeSeoHeadPath as u, renderHeadTags as v, resolvePageSeo as w, spliceHeadHtml as x, stripManagedHeadTags as y, SEO_HEAD_ROUTE_HAS_NO_META as z };
@@ -1,7 +1,7 @@
1
1
  import { Plugin, HtmlTagDescriptor } from 'vite';
2
- import { D as DcsRobotsOptions, Y as SeoHonestyBlock, Z as PageRouteEntry, H as SeoConfiguration, E as ContentConfig } from '../vitepressTransform-CZ_IB3dq.js';
3
- export { C as CreateSeoTransformPageDataOptions, R as ResolvedPageOverrides, S as SeoPageContext, r as SeoPageTypeRule, t as VitePressHeadConfig, V as VitePressPageData, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute } from '../vitepressTransform-CZ_IB3dq.js';
4
- import { H as HonestyMode } from '../headHonesty-OzxvLuwd.js';
2
+ import { a7 as PageRouteEntry, D as DcsRobotsOptions, a8 as SeoHonestyBlock, p as SeoConfiguration, C as ContentConfig } from '../vitepressTransform-CQXBpYEC.js';
3
+ export { h as CreateSeoTransformPageDataOptions, R as ResolvedPageOverrides, s as SeoPageContext, t as SeoPageTypeRule, V as VitePressHeadConfig, z as VitePressPageData, Y as buildVitePressSeoHead, Z as createSeoTransformPageData, $ as defaultRelativePathToRoute } from '../vitepressTransform-CQXBpYEC.js';
4
+ import { H as HonestyMode } from '../headHonesty-k1IhGblP.js';
5
5
  import { Component, Plugin as Plugin$1 } from 'vue';
6
6
  import MarkdownIt from 'markdown-it';
7
7
 
@@ -53,6 +53,126 @@ interface DcsContentPluginOptions {
53
53
  */
54
54
  declare function dcsContentPlugin(options?: DcsContentPluginOptions): Plugin;
55
55
 
56
+ /**
57
+ * Per-route sitemap `<lastmod>` derived from git (RFQ-002427 L1a, cms 0.14.0).
58
+ *
59
+ * OPT-IN AND BEST-EFFORT. The factory never infers a lastmod by default: a URL
60
+ * carries its per-route `.dcs/pages.yaml` date or no `<lastmod>`. This walk
61
+ * runs only for a site that sets `.dcs/seo.yaml` `sitemap.lastmodFromGit:
62
+ * true` (or the `gitLastmod` option). Known gaps the opt-in accepts:
63
+ * composables/stores/lib/utils are excluded, not inspected (content a page
64
+ * reads through them is not dated unless re-included via `lastmodExclude`
65
+ * `!glob`); markdown includes (`<!--@include:-->`) are not traced; a VitePress
66
+ * page with a custom frontmatter `layout:` is omitted, not traced; runtime
67
+ * data (API fetches, live artifacts) is never dated.
68
+ *
69
+ * The sitemap rule: a `<lastmod>` is accurate for its URL, or it is omitted.
70
+ * Never a build-time stamp, and never one site-wide date on every URL (the
71
+ * kineticenergypt F4 defect: all 52 URLs carried seo.yaml `lastUpdated`, stale
72
+ * on 100 % of them).
73
+ *
74
+ * INVARIANT: a route gets a git-derived lastmod only when EVERY material
75
+ * content source of that route is tracked and dated; otherwise that route's
76
+ * lastmod is omitted.
77
+ *
78
+ * Precedence, applied by `buildSitemapXml`:
79
+ * 1. a per-route `lastmod` / `lastUpdated` / `dateModified` on the
80
+ * `.dcs/pages.yaml` entry (validated);
81
+ * 2. the git-derived date from here = the NEWEST of
82
+ * (a) the route's view or markdown file,
83
+ * (b) every local module reachable from it through other content modules
84
+ * (transitive, shared or not), never counting or walking into the
85
+ * non-content exclusions ({@link DEFAULT_LASTMOD_EXCLUDE} plus
86
+ * `.dcs/seo.yaml` `sitemap.lastmodExclude`),
87
+ * (c) the route's own content in `.dcs/content.yaml`: the newest commit
88
+ * that changed `pages.<slug>` or a `global` key the route's sources
89
+ * reference by name (parsed-subtree diff, commit by commit, capped at
90
+ * {@link CONTENT_WALK_LIMIT} commits);
91
+ * 3. nothing: `<lastmod>` is omitted.
92
+ *
93
+ * A route is omitted (no git date) when any material source cannot be
94
+ * accounted for: no resolvable view, an import that resolves to no file and is
95
+ * not an installed package (virtual modules, unknown aliases), a VitePress
96
+ * markdown component tag with no theme registration, a VitePress data loader
97
+ * whose inputs are not literal globs, an untracked or locally modified source,
98
+ * or a content.yaml walk that hit the cap without finding the change.
99
+ *
100
+ * Git-derived dates are withheld for ALL routes when git is unavailable, the
101
+ * clone is shallow (`git rev-parse --is-shallow-repository`), or 3+ dated
102
+ * routes ALL share one single date (the uniform-stamp signature). A partial
103
+ * overlap from a real bulk commit is accurate and kept.
104
+ *
105
+ * Modelled on lane L3's web/scripts/generate-sitemap.mjs (169eb73f8,
106
+ * acebc7a75: transitive content-module walk, NON_CONTENT_SOURCES, one
107
+ * `git log --name-only --cc` prime walk so merge resolutions count).
108
+ */
109
+
110
+ /** Runs `git <args>` in `cwd` and returns stdout; throws on any failure. */
111
+ type GitRunner = (args: string[], cwd: string) => string;
112
+ /** Why git-derived dates were withheld for the whole site (undefined = used). */
113
+ type RouteLastmodWithheld = 'git-unavailable' | 'shallow' | 'identical-dates';
114
+ /** Why ONE route got no git-derived date. */
115
+ type RouteLastmodOmitted = 'no-source' | 'unresolved-import' | 'unresolved-component' | 'untracked-source' | 'data-loader' | 'undated-source' | 'content-walk-cap' | 'content-untracked' | 'custom-layout';
116
+ /** With this many or more dated routes all on ONE date, every git date is withheld. */
117
+ declare const IDENTICAL_LASTMOD_ROUTE_LIMIT = 3;
118
+ /** content.yaml commits walked per site before an unanswered route is omitted. */
119
+ declare const CONTENT_WALK_LIMIT = 300;
120
+ /**
121
+ * Local modules that never count toward a page's lastmod and are not walked
122
+ * into: app shell and chrome, non-content code, styles, tests, and the `.dcs`
123
+ * metadata files (content.yaml is dated per route by (c) instead). Globs are
124
+ * matched against the path relative to `projectRoot`; a glob without `/`
125
+ * matches the basename. A site extends this with `.dcs/seo.yaml`
126
+ * `sitemap.lastmodExclude`, where a `!glob` entry re-includes.
127
+ */
128
+ declare const DEFAULT_LASTMOD_EXCLUDE: readonly string[];
129
+ interface DeriveRouteLastmodsOptions {
130
+ routes: PageRouteEntry[];
131
+ /** Directory the source paths resolve against. */
132
+ projectRoot: string;
133
+ /**
134
+ * Site override for a route's ENTRY files (absolute, or relative to
135
+ * `projectRoot`); the content-module walk still runs from them. Return
136
+ * `undefined` for the default mapping, `[]` to give the route no git date.
137
+ */
138
+ sourcesForRoute?: (route: PageRouteEntry) => string[] | undefined;
139
+ /** `.dcs/content.yaml` path (absolute or projectRoot-relative). Default: searched. */
140
+ contentPath?: string;
141
+ /** Extra exclusion globs (`.dcs/seo.yaml` `sitemap.lastmodExclude`); `!glob` re-includes. */
142
+ exclude?: string[];
143
+ /** content.yaml commits to walk (default {@link CONTENT_WALK_LIMIT}). */
144
+ contentWalkLimit?: number;
145
+ /** Injectable git runner (tests). Defaults to a real `git` subprocess. */
146
+ git?: GitRunner;
147
+ debug?: boolean;
148
+ }
149
+ interface DeriveRouteLastmodsResult {
150
+ /** route.path → ISO-8601 committer date of the newest change to its material sources. */
151
+ lastmods: Map<string, string>;
152
+ /** Set when every git-derived date was withheld, with the reason. */
153
+ withheld?: RouteLastmodWithheld;
154
+ /** route.path → why that route got no date (only routes the walk reached). */
155
+ omitted: Map<string, RouteLastmodOmitted>;
156
+ /** route.path → the material source files that were dated (absolute). */
157
+ sources: Map<string, string[]>;
158
+ }
159
+ /**
160
+ * The conventional entry files for a route, relative to `projectRoot`, in
161
+ * priority order. Covers the SPA layout (`src/views/<Name>View.vue`,
162
+ * `src/pages/<Name>.vue`) and the VitePress layout (`<path>.md`,
163
+ * `<path>/index.md`, under the root or `docs/`). The FIRST that exists is the
164
+ * route's entry.
165
+ */
166
+ declare function defaultRouteSourceCandidates(route: PageRouteEntry): string[];
167
+ /** Minimal glob → RegExp: `**`, `*`, `?`, `{a,b}` (alternatives literal or wildcard). */
168
+ declare function lastmodGlobToRegExp(glob: string): RegExp;
169
+ /**
170
+ * Derive per-route `<lastmod>` values from git. Never throws: any git failure
171
+ * withholds the git-derived dates (the sitemap then omits `<lastmod>` for
172
+ * routes without a pages.yaml date).
173
+ */
174
+ declare function deriveRouteLastmods(options: DeriveRouteLastmodsOptions): DeriveRouteLastmodsResult;
175
+
56
176
  /**
57
177
  * DCS SEO Plugin for Vite
58
178
  *
@@ -186,6 +306,21 @@ interface DcsSeoPluginOptions {
186
306
  preview?: boolean;
187
307
  /** Emit `dist/llms.txt` (default `true`; always off in preview mode). */
188
308
  llms?: boolean;
309
+ /**
310
+ * Opt in to git-derived sitemap `<lastmod>` (BEST-EFFORT; default OFF).
311
+ * Without it the factory never infers a date: a URL carries its per-route
312
+ * `.dcs/pages.yaml` `lastmod`, or no `<lastmod>`. The site-level switch is
313
+ * `.dcs/seo.yaml` `sitemap.lastmodFromGit: true`; this option, when set,
314
+ * overrides it for one build. See `deriveRouteLastmods` for what the walk
315
+ * does and does not see.
316
+ */
317
+ gitLastmod?: boolean;
318
+ /**
319
+ * Override a route's source files (absolute or project-root relative) for
320
+ * the git-derived `<lastmod>`. Return `undefined` for the default mapping
321
+ * (`src/views/<Name>View.vue`, `src/pages/<Name>.vue`, `<path>.md`, ...).
322
+ */
323
+ lastmodSources?: (route: PageRouteEntry) => string[] | undefined;
189
324
  /**
190
325
  * P1 — assert that each route's BAKED `<title>`/description equals what the
191
326
  * app leaves in the `<head>` after it mounts. Rides the prerender browser, so
@@ -213,6 +348,19 @@ interface DcsSeoPluginOptions {
213
348
  * Env override: `DCS_SEO_CHARSET_BUDGET=error|warn|off`.
214
349
  */
215
350
  charsetBudget?: boolean | HonestyMode | SeoHonestyBlock;
351
+ /**
352
+ * C-1965: on a VitePress `cleanUrls` BUILD, write a byte-identical
353
+ * `<page>/index.html` twin of every flat `<page>.html` (index pages and the
354
+ * root `404.md` excluded) after the site's own `buildEnd`, so `/page/`
355
+ * answers 200 on an Azure Static Web App instead of 301-ing to the
356
+ * `*.azurestaticapps.net` default host. Default `true`; non-VitePress builds
357
+ * and `vitepress dev` are never touched. An existing `<page>/index.html` with
358
+ * different bytes FAILS the build. See `dcsDirIndex.ts`. On by default
359
+ * because every DCS cleanUrls consumer is an Azure SWA; on another host the
360
+ * twins change what `/page/` serves (README, "Directory-index twins"), and
361
+ * `false` keeps the pre-0.13.14 output.
362
+ */
363
+ dirIndex?: boolean;
216
364
  }
217
365
  /**
218
366
  * Every key a `noindex` entry can legitimately match.
@@ -254,7 +402,10 @@ declare class NoindexOrphanError extends Error {
254
402
  * - `llms.txt` (skipped in preview, or when nothing indexable)
255
403
  *
256
404
  * Returns the list of relative filenames written. Pure aside from `fs` writes —
257
- * deterministic + idempotent. Never throws (the caller also wraps in try/catch).
405
+ * deterministic + idempotent. Throws only {@link RobotsAiTrainingConflictError}
406
+ * (a hand-authored robots.txt that contradicts `robots.aiTraining: false`),
407
+ * which the plugin's emit catch re-throws so the build fails; nothing else is
408
+ * thrown.
258
409
  */
259
410
  declare function emitSiteFiles(params: {
260
411
  outDir: string;
@@ -268,6 +419,24 @@ declare function emitSiteFiles(params: {
268
419
  preview?: boolean;
269
420
  robots?: DcsRobotsOptions;
270
421
  llms?: boolean;
422
+ /**
423
+ * Opt in to git-derived sitemap `<lastmod>` (BEST-EFFORT; default OFF).
424
+ * Without it the factory never infers a date: a URL carries its per-route
425
+ * `.dcs/pages.yaml` `lastmod`, or no `<lastmod>`. The site-level switch is
426
+ * `.dcs/seo.yaml` `sitemap.lastmodFromGit: true`; this option, when set,
427
+ * overrides it for one build. See `deriveRouteLastmods` for what the walk
428
+ * does and does not see.
429
+ */
430
+ gitLastmod?: boolean;
431
+ /** Override a route's ENTRY files for the git-derived `<lastmod>` (the content walk still runs). */
432
+ lastmodSources?: (route: PageRouteEntry) => string[] | undefined;
433
+ /**
434
+ * `.dcs/content.yaml` path (projectRoot-relative or absolute), used to date
435
+ * each route's own content subtree. Default: searched like pages.yaml.
436
+ */
437
+ contentPath?: string;
438
+ /** Injectable git runner (tests only). */
439
+ git?: GitRunner;
271
440
  debug?: boolean;
272
441
  }): string[];
273
442
  /**
@@ -549,6 +718,187 @@ declare function dcsCdnBuildEnd(options?: DcsCdnBuildEndOptions): (siteConfig: {
549
718
 
550
719
  declare function responsiveImagePlugin(md: MarkdownIt): void;
551
720
 
721
+ /**
722
+ * DCS directory-index twins for VitePress `cleanUrls` builds (C-1965).
723
+ *
724
+ * THE DEFECT. A VitePress site built with `cleanUrls: true` emits every
725
+ * non-index page flat: `contact.md` -> `dist/contact.html`. On an Azure Static
726
+ * Web App with no `trailingSlash` rule, `/contact` answers 200 but `/contact/`
727
+ * answers `301 Location: https://<swa-default-host>/contact` - an ABSOLUTE
728
+ * redirect to the `*.azurestaticapps.net` host, because Front Door sends that
729
+ * host as the origin Host and a Free SWA ignores `X-Forwarded-Host`. Measured
730
+ * live on kimduffhomes.com, nateduff.com, bryanduffhomes.com and bryanduff.com
731
+ * (.workboard/records/2026-10-27-lead-C1965-swa-fixture.md section 1).
732
+ *
733
+ * THE FIX, PROVEN ON A DISPOSABLE FREE SWA (same record, section 3f): when both
734
+ * `x.html` and `x/index.html` exist, SWA serves `x.html` for `/x` and
735
+ * `x/index.html` for `/x/`, both 200, no `Location`, in either direction. So for
736
+ * every flat page this writes `<page>/index.html` as a BYTE-IDENTICAL twin of
737
+ * `<page>.html`.
738
+ *
739
+ * WHY STRICT. The two URLs are served by two different files, so a twin that
740
+ * differs from its flat page shows visitors and crawlers two different
741
+ * documents on `/x` and `/x/`. An existing `<page>/index.html` with different
742
+ * bytes is therefore a BUILD FAILURE, never a skip. A page VitePress says it
743
+ * rendered whose `.html` is missing is also fatal: the emitter's model of the
744
+ * build would be wrong.
745
+ *
746
+ * NO CANONICAL OF ITS OWN. The flat page already carries the cms factory's
747
+ * absolute, slash-less canonical (`vitepressTransform.ts`), and a byte copy
748
+ * carries it too, so `/contact/` consolidates onto `/contact`. A self-canonical
749
+ * `/contact/` would split the signal.
750
+ *
751
+ * ORDER. The twin must copy the FINAL bytes. VitePress applies `transformHtml`
752
+ * before it writes each page, and the site's own `buildEnd` (CDN rewrite,
753
+ * site files, pre-launch stamps) runs next; the emitter is chained AFTER that
754
+ * hook. The canonical deploy workflow then injects GA into every `*.html` and
755
+ * re-checks the pairs (site-deploy.yml, "Assert directory-index twin parity").
756
+ *
757
+ * THE MANIFEST (C-1965 roll-blocker N2). When `DCS_DIR_INDEX_MANIFEST` names a
758
+ * file, every emitter run writes there the list of twins it validated (twin
759
+ * path, source path, sha256 of the bytes it copied), so the deploy workflow
760
+ * checks the pairs the cms OWNS instead of inferring pairs from the dist. The
761
+ * canonical workflow points it at a run-unique file under `$RUNNER_TEMP`:
762
+ * outside the SWA upload directory (nothing new is served) and outside the
763
+ * site repo (nothing new to ignore or commit). Unset (a local build), nothing
764
+ * is written.
765
+ *
766
+ * TWO ENTRY POINTS, ONE GUARD. `dcsSeoPlugin` installs the emitter
767
+ * automatically on a VitePress build (`dirIndex: false` opts out). A site that
768
+ * wants explicit composition can chain `dcsDirIndexBuildEnd()` into its own
769
+ * `buildEnd`. Both go through the registry symbol
770
+ * `Symbol.for('dcs.cms.dirIndex.installed')` on VitePress's `siteConfig`, which
771
+ * is the same object for the client and the SSR config resolution, so the
772
+ * emitter runs exactly once however many times it is registered.
773
+ *
774
+ * @example Explicit composition (optional - dcsSeoPlugin already installs it)
775
+ * ```ts
776
+ * // .vitepress/config.ts
777
+ * import { chainBuildEnd, dcsCdnBuildEnd, dcsDirIndexBuildEnd } from '@duffcloudservices/cms/plugins'
778
+ *
779
+ * export default defineConfig({
780
+ * cleanUrls: true,
781
+ * buildEnd: chainBuildEnd(dcsCdnBuildEnd(), dcsDirIndexBuildEnd()),
782
+ * })
783
+ * ```
784
+ */
785
+ /**
786
+ * The idempotency guard. A REGISTRY symbol (`Symbol.for`), not `Symbol()`: it
787
+ * must be the same key across module instances (the plugin barrel and a
788
+ * site-local import can be two copies) and across the client and SSR config
789
+ * resolutions.
790
+ */
791
+ declare const DIR_INDEX_INSTALLED: unique symbol;
792
+ /**
793
+ * The environment variable that names the twin manifest file. Read at emit
794
+ * time; an empty or unset value writes no manifest.
795
+ */
796
+ declare const DIR_INDEX_MANIFEST_ENV = "DCS_DIR_INDEX_MANIFEST";
797
+ /** The manifest's `schema` value; the workflow step refuses any other. */
798
+ declare const DIR_INDEX_MANIFEST_SCHEMA = "dcs.cms.dir-index-manifest/v1";
799
+ /** One twin the emitter validated (written, or already present and identical). */
800
+ interface DirIndexManifestEntry {
801
+ /** `<page>/index.html`, relative to `outDir`, forward slashes. */
802
+ twin: string;
803
+ /** `<page>.html`, relative to `outDir`, forward slashes. */
804
+ source: string;
805
+ /** sha256 (hex) of the bytes copied, i.e. the source as the emitter read it. */
806
+ sha256: string;
807
+ }
808
+ /** The file `DCS_DIR_INDEX_MANIFEST` names, written on every emitter run. */
809
+ interface DirIndexManifest {
810
+ schema: typeof DIR_INDEX_MANIFEST_SCHEMA;
811
+ /** Absolute build output directory the twins live in. */
812
+ outDir: string;
813
+ /** Whether the build had `cleanUrls` on (off: `twins` is empty). */
814
+ cleanUrls: boolean;
815
+ /** Sorted by `twin`. */
816
+ twins: DirIndexManifestEntry[];
817
+ }
818
+ interface EmitDirectoryIndexesOptions {
819
+ /**
820
+ * Where to write the twin manifest. Defaults to
821
+ * `process.env.DCS_DIR_INDEX_MANIFEST`; when neither is set, nothing is
822
+ * written. Relative paths resolve against `process.cwd()`.
823
+ */
824
+ manifestPath?: string;
825
+ }
826
+ /** The subset of VitePress's resolved `SiteConfig` the emitter reads. */
827
+ interface DirIndexSiteConfig {
828
+ /** Absolute build output directory. */
829
+ outDir: string;
830
+ /** Source pages relative to `srcDir`, e.g. `contact.md`, `blogs/post.md`. */
831
+ pages: string[];
832
+ /** VitePress rewrites; a page renders at `rewrites.map[page] ?? page`. */
833
+ rewrites?: {
834
+ map?: Record<string, string | undefined>;
835
+ };
836
+ /** Twins are emitted only when `cleanUrls` is on. */
837
+ cleanUrls?: boolean;
838
+ /** VitePress's single `buildEnd` hook. */
839
+ buildEnd?: (siteConfig: never) => unknown;
840
+ }
841
+ interface DirIndexResult {
842
+ /** Twins written by this run. */
843
+ written: number;
844
+ /** Twins already present with identical bytes (left untouched). */
845
+ identical: number;
846
+ /** The twin paths (relative to `outDir`, forward slashes) written or found identical. */
847
+ twins: string[];
848
+ /** Absolute path of the manifest written by this run, when one was requested. */
849
+ manifestPath?: string;
850
+ }
851
+ /** Thrown for a missing source page or an unequal `<page>/index.html` collision. */
852
+ declare class DirIndexError extends Error {
853
+ constructor(message: string);
854
+ }
855
+ /**
856
+ * The flat pages that get a twin: every mapped page except index pages
857
+ * (`(^|/)index\.md$`) and the root `404.md`. Returned as mapped `.md` paths.
858
+ */
859
+ declare function dirIndexCandidates(siteConfig: Pick<DirIndexSiteConfig, 'pages' | 'rewrites'>): string[];
860
+ /**
861
+ * Remove a manifest left at `DCS_DIR_INDEX_MANIFEST` by an earlier build, for a
862
+ * build whose emitter is DISABLED (`dirIndex: false`). Removal, not an empty
863
+ * manifest: a disabled emitter owns nothing and validated nothing, and "no
864
+ * manifest" is exactly how the deploy step reads that (no pairs passes, any
865
+ * pair is un-owned and fails), so a stale list from another build can never
866
+ * vouch for this dist. A regular file or a symlink (unlinked, never followed)
867
+ * is removed; a directory is not. Returns the path removed.
868
+ */
869
+ declare function clearDirIndexManifest(manifestPath?: string | undefined): string | undefined;
870
+ /**
871
+ * Write a byte-identical `<page>/index.html` for every flat page of a
872
+ * `cleanUrls` VitePress build. Validates every pair BEFORE writing anything,
873
+ * so a failing build leaves `outDir` exactly as VitePress produced it.
874
+ *
875
+ * When a manifest path is set (option or `DCS_DIR_INDEX_MANIFEST`), any file
876
+ * already there is removed first and a fresh manifest is written on success,
877
+ * including the `cleanUrls: false` no-op (an empty list). A refused build
878
+ * leaves no manifest. A manifest path inside `outDir` is refused: it would
879
+ * ship with the site.
880
+ */
881
+ declare function emitDirectoryIndexes(siteConfig: DirIndexSiteConfig, options?: EmitDirectoryIndexesOptions): DirIndexResult;
882
+ /**
883
+ * The AUTOMATIC entry point (called by `dcsSeoPlugin` on a VitePress build).
884
+ * Wraps `siteConfig.buildEnd` so the site's own hook runs FIRST and the
885
+ * emitter copies its final output. Returns `false` when already installed
886
+ * (the client and SSR builds both resolve config; a second plugin instance
887
+ * may also call this).
888
+ */
889
+ declare function installDirIndex(siteConfig: DirIndexSiteConfig): boolean;
890
+ /**
891
+ * The MANUAL entry point: a VitePress `buildEnd` hook for sites that compose
892
+ * their hooks explicitly. It shares the automatic guard:
893
+ *
894
+ * - If `dcsSeoPlugin` already installed the emitter, this DEFERS to it (the
895
+ * automatic wrapper runs after the site's whole `buildEnd`, so it copies the
896
+ * final bytes) and does nothing itself.
897
+ * - Otherwise it claims the guard and emits, once, however many times it is
898
+ * chained.
899
+ */
900
+ declare function dcsDirIndexBuildEnd(): (siteConfig: DirIndexSiteConfig) => Promise<void>;
901
+
552
902
  /**
553
903
  * Build-time responsive-variant lint for DCS customer sites.
554
904
  *
@@ -770,4 +1120,4 @@ interface DcsAgentWidgetTagOptions {
770
1120
  */
771
1121
  declare function dcsAgentWidgetLoaderTag(options: DcsAgentWidgetTagOptions): HtmlTagDescriptor | null;
772
1122
 
773
- export { AGENT_CONFIG_ORIGINS, type AgentConfigOrigin, DCS_MOTION_TOKENS_CSS, DEFAULT_AGENT_API_BASE_URL, DEFAULT_AGENT_WIDGET_SCRIPT_URL, type DcsAgentWidgetLoaderOptions, type DcsAgentWidgetTagOptions, type DcsCdnBuildEndOptions, type DcsCdnImagePluginOptions, type DcsContentPluginOptions, type DcsEditorPluginOptions, type DcsPreviewPluginOptions, type DcsResponsiveImageLintOptions, type DcsSeoPluginOptions, NoindexOrphanError, type ResponsiveImageLintReport, type ResponsiveImageViolation, buildAgentWidgetLoaderScript, chainBuildEnd, collectNoindexMatchKeys, dcsAgentWidgetLoaderTag, dcsCdnBuildEnd, dcsCdnImagePlugin, dcsContentPlugin, dcsEditorPlugin, dcsMotionTokensStyleTag, dcsPreviewPlugin, dcsResponsiveImageLint, dcsSeoPlugin, emitSiteFiles, emitStaticSeoHtml, findFullSizeCdnImages, findOrphanNoindexEntries, isFullSizeCdnUrl, readAgentConfigOrigin, readSiteSlug, responsiveImagePlugin };
1123
+ export { AGENT_CONFIG_ORIGINS, type AgentConfigOrigin, CONTENT_WALK_LIMIT, DCS_MOTION_TOKENS_CSS, DEFAULT_AGENT_API_BASE_URL, DEFAULT_AGENT_WIDGET_SCRIPT_URL, DEFAULT_LASTMOD_EXCLUDE, DIR_INDEX_INSTALLED, DIR_INDEX_MANIFEST_ENV, DIR_INDEX_MANIFEST_SCHEMA, type DcsAgentWidgetLoaderOptions, type DcsAgentWidgetTagOptions, type DcsCdnBuildEndOptions, type DcsCdnImagePluginOptions, type DcsContentPluginOptions, type DcsEditorPluginOptions, type DcsPreviewPluginOptions, type DcsResponsiveImageLintOptions, type DcsSeoPluginOptions, type DeriveRouteLastmodsOptions, type DeriveRouteLastmodsResult, DirIndexError, type DirIndexManifest, type DirIndexManifestEntry, type DirIndexResult, type DirIndexSiteConfig, type EmitDirectoryIndexesOptions, type GitRunner, IDENTICAL_LASTMOD_ROUTE_LIMIT, NoindexOrphanError, type ResponsiveImageLintReport, type ResponsiveImageViolation, type RouteLastmodOmitted, type RouteLastmodWithheld, buildAgentWidgetLoaderScript, chainBuildEnd, clearDirIndexManifest, collectNoindexMatchKeys, dcsAgentWidgetLoaderTag, dcsCdnBuildEnd, dcsCdnImagePlugin, dcsContentPlugin, dcsDirIndexBuildEnd, dcsEditorPlugin, dcsMotionTokensStyleTag, dcsPreviewPlugin, dcsResponsiveImageLint, dcsSeoPlugin, defaultRouteSourceCandidates, deriveRouteLastmods, dirIndexCandidates, emitDirectoryIndexes, emitSiteFiles, emitStaticSeoHtml, findFullSizeCdnImages, findOrphanNoindexEntries, installDirIndex, isFullSizeCdnUrl, lastmodGlobToRegExp, readAgentConfigOrigin, readSiteSlug, responsiveImagePlugin };