@duffcloudservices/cms 0.12.0 → 0.13.0

package/src/composables/useReleaseNotes.ts

@@ -28,6 +28,7 @@
  * ```
  */
 
+import { platformFetch } from '@duffcloudservices/cms-core'
 import { ref, onMounted } from 'vue'
 import type { ReleaseNote, ReleaseNotesReturn } from '../types/release-notes'
 
@@ -88,7 +89,12 @@ export function useReleaseNotes(
 
     try {
       const url = `${apiBaseUrl}/api/v1/release-notes/${version}`
-      const response = await fetch(url, {
+      // C-298 layer 2: an HTML body here means the call never reached the API (a host
+      // whose Front Door config has no /api/v1/* route answers with the SPA shell at
+      // HTTP 200). platformFetch names the URL + content-type instead of letting
+      // `response.json()` throw an opaque "Unexpected token '<'" into the catch below.
+      // A real 404 still lands in the `!response.ok` branch untouched.
+      const response = await platformFetch(url, {
         headers: {
           Accept: 'application/json',
         },

package/src/composables/useSEO.applyHead.test.ts

@@ -0,0 +1,150 @@
+/**
+ * ENFORCEMENT, IN ONE PLACE (C-356).
+ *
+ * The head-authority contract is enforced by the shared package, not by eleven
+ * site test suites: `applyHead` is typed `() => void`, and an argument that
+ * reaches it at runtime anyway is DROPPED with a loud message.
+ *
+ * Both halves are tested here because both are load-bearing:
+ *   - the TYPE stops a type-checked caller at build (`pnpm type-check`, wired as
+ *     the fleet's pre-deploy gate by C-303/C-316);
+ *   - the RUNTIME stops the caller who is not type-checked — a `.vue` SFC whose
+ *     script block never sees `vue-tsc`, an `as any`, or a plain-JS site
+ *     (just-posh is exactly that: `jsconfig.json`, `.js` sources, no type-check
+ *     script at all). That caller is not hypothetical; it is the fleet.
+ *
+ * The failure MODE is deliberately asymmetric — see the assertions at the end.
+ */
+import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest'
+
+const applied: unknown[] = []
+vi.mock('@unhead/vue', () => ({
+  useHead: (input: unknown) => {
+    applied.push(input)
+  },
+}))
+
+// The composable reads its config from the `__DCS_SEO__` build-time global.
+const SEO = {
+  global: {
+    siteName: 'Fixture Co',
+    siteUrl: 'https://fixture.example.com',
+    titleTemplate: '%s | Fixture Co',
+    defaultTitle: 'Fixture Co',
+    defaultDescription: 'The approved description.',
+  },
+  pages: {
+    home: { title: 'Approved Title', description: 'The approved description.' },
+  },
+}
+
+const { useSEO, HEAD_OVERRIDE_REFUSED_MESSAGE } = await import('./useSEO')
+const { buildHeadTags } = await import('../seo/headTags')
+
+type ApplyHeadWithOverride = (overrides: Record<string, unknown>) => void
+
+beforeEach(() => {
+  applied.length = 0
+  ;(globalThis as Record<string, unknown>).__DCS_SEO__ = SEO
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  delete (globalThis as Record<string, unknown>).__DCS_SEO__
+})
+
+describe('applyHead re-asserts the baked head', () => {
+  test('with no arguments it emits the seo.yaml-resolved head', () => {
+    const { applyHead } = useSEO('home', '/')
+    applyHead()
+    expect(applied).toHaveLength(1)
+    const head = applied[0] as { title: string; meta: Array<{ name?: string; content: string }> }
+    expect(head.title).toBe('Approved Title | Fixture Co')
+    expect(head.meta.find((m) => m.name === 'description')!.content).toBe('The approved description.')
+  })
+
+  test('the type says () => void — an override is a COMPILE error, not a runtime option', () => {
+    // NOTE: the compile-time assertion is NOT here. `packages/cms/tsconfig.json`
+    // excludes `**/*.test.ts`, so a `@ts-expect-error` in this file would never
+    // be evaluated by `pnpm type-check` — a comment dressed as a gate. The real
+    // pin is `APPLY_HEAD_TAKES_NO_ARGUMENTS` in `src/seo/headContract.ts`, which
+    // is a checked source file; kill-tested by re-adding the parameter (tsc then
+    // reports TS2322 on that line). This test covers the RUNTIME half only.
+    const { applyHead } = useSEO('home', '/')
+    expect(applyHead).toHaveLength(0)
+    applyHead()
+    expect(applied).toHaveLength(1)
+  })
+})
+
+describe('an override that reaches the runtime is REFUSED, not obeyed', () => {
+  test('the emitted head is byte-identical to the no-argument call', () => {
+    const errors: string[] = []
+    vi.spyOn(console, 'error').mockImplementation((m: unknown) => {
+      errors.push(String(m))
+    })
+
+    const a = useSEO('home', '/')
+    a.applyHead()
+    const clean = JSON.stringify(applied[0])
+
+    applied.length = 0
+    const b = useSEO('home', '/')
+    ;(b.applyHead as unknown as ApplyHeadWithOverride)({
+      title: 'Hand-written Title',
+      description: 'Hand-written description.',
+      keywords: 'hand, written',
+    })
+
+    expect(JSON.stringify(applied[0])).toBe(clean)
+    expect(JSON.stringify(applied[0])).not.toContain('Hand-written')
+    expect(errors.join('\n')).toContain('IGNORED')
+    expect(errors.join('\n')).toContain('.dcs/seo.yaml is the only writer')
+    expect(errors.join('\n')).toContain('title, description, keywords')
+  })
+
+  test('KILL-TEST: without the refusal the override WOULD have won', () => {
+    // The old behaviour, reproduced through the resolver the composable calls:
+    // `overrides?.title ?? resolved.title`. This is the exact line that shipped
+    // 93 divergences; it is asserted here so the fix cannot be quietly undone
+    // without this test going red.
+    const errors: string[] = []
+    vi.spyOn(console, 'error').mockImplementation((m: unknown) => errors.push(String(m)))
+    const overridden = buildHeadTags('home', '/', SEO as never, { title: 'Hand-written Title' })
+    expect(overridden.title).toBe('Hand-written Title')
+
+    const { applyHead } = useSEO('home', '/')
+    ;(applyHead as unknown as ApplyHeadWithOverride)({ title: 'Hand-written Title' })
+    expect((applied[0] as { title: string }).title).toBe('Approved Title | Fixture Co')
+  })
+
+  test('the refusal names the offending page slug and the ignored keys', () => {
+    const errors: string[] = []
+    vi.spyOn(console, 'error').mockImplementation((m: unknown) => errors.push(String(m)))
+    const { applyHead } = useSEO('home', '/')
+    ;(applyHead as unknown as ApplyHeadWithOverride)({ title: 'x', schemas: [] })
+    expect(errors[0]).toContain('page slug: home')
+    expect(errors[0]).toContain('ignored keys: title, schemas')
+    expect(errors[0]).toContain(HEAD_OVERRIDE_REFUSED_MESSAGE.slice(0, 60))
+  })
+
+  test('the failure mode is ASYMMETRIC on purpose: SEO stays correct, the build does not fall over', () => {
+    // A production throw would take a paying customer's page down over a
+    // metadata mistake. Dropping the override cannot: the worst case is that
+    // the page serves the OWNER-APPROVED value.
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { applyHead } = useSEO('home', '/')
+    expect(() => (applyHead as unknown as ApplyHeadWithOverride)({ title: 'x' })).not.toThrow()
+    expect((applied[0] as { title: string }).title).toBe('Approved Title | Fixture Co')
+  })
+
+  test('a null / undefined argument is not treated as a violation', () => {
+    const errors: string[] = []
+    vi.spyOn(console, 'error').mockImplementation((m: unknown) => errors.push(String(m)))
+    const { applyHead } = useSEO('home', '/')
+    ;(applyHead as unknown as (o?: unknown) => void)(undefined)
+    ;(applyHead as unknown as (o?: unknown) => void)(null)
+    expect(errors).toEqual([])
+    expect(applied).toHaveLength(2)
+  })
+})

package/src/composables/useSEO.ts

@@ -8,6 +8,12 @@
  * module so that the build-time static-HTML emitter (`dcsSeoPlugin`) produces
  * byte-identical output. This composable is a thin Vue/unhead wrapper over it.
  *
+ * THE HEAD-AUTHORITY CONTRACT (C-356). `.dcs/seo.yaml` is the ONLY writer of
+ * the managed head fields. `applyHead()` RE-ASSERTS the baked head at runtime;
+ * it never AUTHORS one, so it takes no arguments. Full text + reasoning:
+ * `.docs/plans/dynamic-site-resolution/README.md` § "The head-authority
+ * contract (C-356)".
+ *
  * @example
  * ```vue
  * <script setup lang="ts">
@@ -15,16 +21,15 @@
  *
  * const { applyHead, getSchema, config } = useSEO('home')
  *
- * // Apply all meta tags
+ * // Re-assert the baked head for this route. No arguments — ever.
  * applyHead()
- *
- * // Or customize before applying
- * applyHead({
- *   title: 'Custom Override Title',
- *   schemas: [...getSchema(), customSchema]
- * })
  * </script>
  * ```
+ *
+ * Need a different title? Change it in `.dcs/seo.yaml` (or in the portal SEO
+ * editor, which writes it). A value hardcoded here is a SECOND writer, and a
+ * second writer is a divergence by construction — whether or not today's two
+ * values happen to agree.
  */
 
 import { computed, type ComputedRef } from 'vue'
@@ -34,7 +39,6 @@ import type {
   GlobalSeoConfig,
   ResolvedPageSeo,
   UseSeoReturn,
-  HeadOverrides,
 } from '../types/seo'
 import { buildHeadTags, resolvePageSeo, generateJsonLd } from '../seo/headTags'
 
@@ -56,6 +60,35 @@ function getBuildTimeSeo(): SeoConfiguration | undefined {
   return undefined
 }
 
+/**
+ * The C-356 refusal. Exported so tests can assert the exact message and so a
+ * host app can spot it in a log.
+ *
+ * IT DOES NOT THROW, ANYWHERE. The build-time gates are the ones that must be
+ * unmissable — the `() => void` type (caught by every site's `type-check`, made
+ * pre-deploy-mandatory by C-303/C-316) and `assertHeadContract` in the source
+ * audit, which fails the build outright. By the time control reaches this
+ * function the page is already rendering for a real visitor, and throwing there
+ * would take a paying customer's page down over a metadata mistake. The
+ * asymmetry is the point: the worst outcome of a refused override is that the
+ * page serves the OWNER-APPROVED value with a console error next to it.
+ */
+export const HEAD_OVERRIDE_REFUSED_MESSAGE =
+  '[dcs-seo] applyHead() was called WITH AN ARGUMENT and the argument was IGNORED. ' +
+  '.dcs/seo.yaml is the only writer of title/description/keywords/canonical/OG/Twitter/' +
+  'JSON-LD (head-authority contract, C-356). A hardcoded value here overwrites the ' +
+  'owner-approved baked head for Google and every human while non-JS crawlers keep ' +
+  'receiving the approved one. Move the value into .dcs/seo.yaml and call applyHead() ' +
+  'with no arguments.'
+
+function reportHeadOverrideRefused(pageSlug: string, refused: unknown): void {
+  const keys =
+    refused && typeof refused === 'object' ? Object.keys(refused as object).join(', ') : String(refused)
+  console.error(
+    `${HEAD_OVERRIDE_REFUSED_MESSAGE}\n  page slug: ${pageSlug}\n  ignored keys: ${keys}`
+  )
+}
+
 /**
  * useSEO composable for DCS-managed SEO configuration.
  *
@@ -87,20 +120,30 @@ export function useSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
   }
 
   /**
-   * Apply all meta tags via useHead.
+   * RE-ASSERT the baked head for this route. Takes no arguments.
    *
    * Delegates to the shared `buildHeadTags` resolver so the emitted tags match
    * the build-time static-HTML emitter exactly. Keywords are intentionally not
    * emitted at runtime (historical behaviour), so `includeKeywords` is omitted.
+   *
+   * ENFORCEMENT (C-356). The parameter is gone from the signature, so TypeScript
+   * consumers fail `type-check`. But a `.vue` file compiled without type
+   * checking, an `as any`, or a JS site can still reach this function with an
+   * argument, and THAT is the shape that shipped 93 divergences on KEPT. So the
+   * override is also refused at runtime: it is dropped, `.dcs/seo.yaml` still
+   * wins, and the violation is reported. A violating site therefore degrades to
+   * CORRECT SEO plus a loud message — never to a silently destroyed head.
    */
-  function applyHead(overrides?: HeadOverrides): void {
-    const { title, meta, link, script } = buildHeadTags(pageSlug, pagePath, seoConfig, {
-      title: overrides?.title,
-      description: overrides?.description,
-      keywords: overrides?.keywords,
-      schemas: overrides?.schemas,
-      meta: overrides?.meta,
-    })
+  // Declared with a rest parameter so a runtime argument is CAPTURED, then
+  // exposed through `UseSeoReturn` as `() => void` so a compile-time argument is
+  // REJECTED. Both halves are needed: the type stops the honest caller, the
+  // runtime stops the one who is not type-checked.
+  function applyHeadImpl(...refused: unknown[]): void {
+    if (refused.length > 0 && refused[0] !== undefined && refused[0] !== null) {
+      reportHeadOverrideRefused(pageSlug, refused[0])
+    }
+
+    const { title, meta, link, script } = buildHeadTags(pageSlug, pagePath, seoConfig)
 
     // Apply via useHead. The shared resolver returns framework-agnostic tag
     // shapes (HeadMetaTag/HeadLinkTag/HeadScriptTag); unhead's input types are
@@ -114,6 +157,9 @@ export function useSEO(pageSlug: string, pagePath?: string): UseSeoReturn {
     } as unknown as Parameters<typeof useHead>[0])
   }
 
+  // The narrowing that makes the contract compile-checkable for consumers.
+  const applyHead: () => void = applyHeadImpl
+
   return {
     config,
     applyHead,

package/src/composables/useSiteVersion.ts

@@ -22,6 +22,7 @@
  * ```
  */
 
+import { platformFetch } from '@duffcloudservices/cms-core'
 import { ref, computed, onMounted } from 'vue'
 import type { SiteVersionReturn } from '../types/release-notes'
 
@@ -79,7 +80,9 @@ export function useSiteVersion(options: { fetchOnMount?: boolean } = {}): SiteVe
     try {
       // Fetch the latest release notes to get the version
       const url = `${apiBaseUrl}/api/v1/release-notes/latest`
-      const response = await fetch(url, {
+      // C-298 layer 2 — see useReleaseNotes: an HTML body is a misroute, not "no release
+      // notes yet", and this composable's catch would otherwise swallow it silently.
+      const response = await platformFetch(url, {
         headers: {
           Accept: 'application/json',
         },

package/src/composables/useSiteVisitorSession.test.ts

@@ -70,6 +70,62 @@ describe('fetchSiteVisitorSession — anonymous probe is silent', () => {
   })
 })
 
+describe('fetchSiteVisitorSession — a misroute is NOT an anonymous visit (C-298 layer 2)', () => {
+  /**
+   * The default base is the RELATIVE `/api/v1`. On a host whose Front Door config has no
+   * `/api/v1/*` route the catch-all answers with the SPA shell at HTTP 200 — which used to
+   * be indistinguishable from "signed out", the reason KEPT ran with all nine login routes
+   * dead for ~2 weeks (C-261) and the reason it is still live on www.nateduff.com.
+   */
+  const SPA_SHELL =
+    '<!DOCTYPE html><html><head><script type="module" src="/assets/index.js"></script></head><body><div id="app"></div></body></html>'
+
+  function htmlResponse() {
+    const headers = new Headers({ 'content-type': 'text/html; charset=utf-8' })
+    const build = (): Response =>
+      ({
+        ok: true,
+        status: 200,
+        headers,
+        clone: () => build(),
+        text: async () => SPA_SHELL,
+        json: async () => JSON.parse(SPA_SHELL),
+      }) as unknown as Response
+    return build()
+  }
+
+  it('200 text/html → signed out for the UI, apiUnreachable=true, and LOUD on the console', async () => {
+    const spies = installConsoleSpies()
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(htmlResponse()))
+
+    const result = await fetchSiteVisitorSession()
+
+    // The page still renders signed-out (a login button that cannot work is worse)…
+    expect(result.visitor).toBeNull()
+    expect(result.authenticated).toBe(false)
+    // …but the caller can tell the difference, and the console is not silent.
+    expect(result.apiUnreachable).toBe(true)
+    expect(spies.error).toHaveBeenCalledTimes(1)
+    const message = String(spies.error.mock.calls[0][0])
+    expect(message).toContain('/api/v1/site-auth/session')
+    expect(message).toContain('text/html')
+    expect(message).toContain('bodyClass=spa-html')
+  })
+
+  it('the ordinary anonymous paths never set apiUnreachable', async () => {
+    const spies = installConsoleSpies()
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({ ok: true, status: 200, json: async () => ({ visitor: null }) }),
+    )
+
+    const result = await fetchSiteVisitorSession()
+
+    expect(result.apiUnreachable).toBeFalsy()
+    expectSilent(spies)
+  })
+})
+
 describe('fetchSiteVisitorSession — authenticated shapes', () => {
   it('200 {visitor:{...}} → returns the visitor', async () => {
     vi.stubGlobal(

package/src/composables/useSiteVisitorSession.ts

@@ -13,7 +13,22 @@
  * `console.error`/`console.warn` on every signed-out page load is exactly the
  * console-noise this fixes. A genuine signed-in visitor is returned as a
  * normalized `SiteVisitor`; anything else resolves to `null`.
+ *
+ * ONE EXCEPTION, added by C-298 layer 2. "Signed out" and "this host does not route
+ * `/api/v1/*` to the platform API at all" used to be the SAME observation here: the
+ * default base is the RELATIVE `/api/v1`, so on a host whose Front Door config lacks the
+ * route, Front Door's catch-all answers with the SPA shell at HTTP 200, `response.json()`
+ * throws, and this client silently resolves to signed-out. That is precisely how KEPT — a
+ * paying customer — ran with all nine login routes dead for ~2 weeks with nothing
+ * detecting it (C-261), and it is still live today on `www.nateduff.com`.
+ *
+ * A non-JSON body is therefore NOT treated as an anonymous visit: it is reported loudly
+ * (once per probe, naming the URL and the received content-type) and the UI still degrades
+ * to signed-out, because a login button that cannot work is better than a broken page.
+ * The anonymous path — `200 {"visitor":null}`, a legacy `401`, a network error — stays
+ * exactly as silent as before.
  */
+import { platformFetch, isPlatformFetchError } from '@duffcloudservices/cms-core'
 import { ref, computed, onMounted, type Ref, type ComputedRef } from 'vue'
 
 /** A signed-in site visitor. */
@@ -30,6 +45,14 @@ export interface SiteVisitorSessionResult {
   visitor: SiteVisitor | null
   /** Convenience flag — `true` iff a visitor is present. */
   authenticated: boolean
+  /**
+   * `true` when the probe did not reach the platform API at all — the response carried a
+   * non-JSON body (C-298 layer 2), i.e. this host does not route `/api/v1/*` to the API.
+   * Distinct from an ordinary signed-out visit: a site can render "sign-in temporarily
+   * unavailable" instead of a login button that cannot possibly work. Absent/`false` on
+   * every normal path, so existing consumers are unaffected.
+   */
+  apiUnreachable?: boolean
 }
 
 export interface FetchSiteVisitorSessionOptions {
@@ -83,13 +106,19 @@ export async function fetchSiteVisitorSession(
 
   let response: Response
   try {
-    response = await fetch(`${base}/site-auth/session`, {
+    response = await platformFetch(`${base}/site-auth/session`, {
       method: 'GET',
       credentials: 'include',
       headers: { Accept: 'application/json' },
       signal: options.signal,
     })
-  } catch {
+  } catch (e) {
+    // A NON-JSON body is a misroute, not an anonymous visit: the request never reached
+    // the API. platformFetch has already written the diagnosable message to the console;
+    // flag it so the UI can say so, and still degrade to signed-out so the page renders.
+    if (isPlatformFetchError(e)) {
+      return { visitor: null, authenticated: false, apiUnreachable: true }
+    }
     // Network error / aborted / CORS — signed-out is the safe probe assumption.
     return SIGNED_OUT
   }
@@ -123,6 +152,11 @@ export interface UseSiteVisitorSessionReturn {
   isAuthenticated: ComputedRef<boolean>
   /** `true` while a probe is in flight. */
   isLoading: Ref<boolean>
+  /**
+   * `true` when the last probe did not reach the platform API (non-JSON body — C-298
+   * layer 2). Render "sign-in unavailable" rather than a login button that cannot work.
+   */
+  apiUnreachable: Ref<boolean>
   /** Re-run the probe. */
   refresh: () => Promise<void>
 }
@@ -138,6 +172,7 @@ export function useSiteVisitorSession(
 
   const visitor = ref<SiteVisitor | null>(null)
   const isLoading = ref(false)
+  const apiUnreachable = ref(false)
   const isAuthenticated = computed(() => visitor.value !== null)
 
   async function refresh(): Promise<void> {
@@ -145,6 +180,7 @@ export function useSiteVisitorSession(
     try {
       const result = await fetchSiteVisitorSession(fetchOptions)
       visitor.value = result.visitor
+      apiUnreachable.value = result.apiUnreachable === true
     } finally {
       isLoading.value = false
     }
@@ -156,5 +192,5 @@ export function useSiteVisitorSession(
     })
   }
 
-  return { visitor, isAuthenticated, isLoading, refresh }
+  return { visitor, isAuthenticated, isLoading, apiUnreachable, refresh }
 }

package/src/composables/useTextContent.ts

@@ -32,6 +32,7 @@
  * ```
  */
 
+import { platformFetch } from '@duffcloudservices/cms-core'
 import { ref, computed, readonly, onMounted, type Ref } from 'vue'
 import type { DcsContentFile, TextContentConfig, TextContentReturn } from '../types/content'
 
@@ -231,7 +232,14 @@ export function useTextContent(config: TextContentConfig): TextContentReturn {
       // Site is resolved server-side from the request Host or the dedicated
       // Container App's DCS_SITE_SLUG; the slug is no longer encoded in the path.
       const url = `${apiBaseUrl}/api/v1/pages/${pageSlug}/text`
-      const response = await fetch(url, {
+      // C-298 layer 2. `VITE_API_BASE_URL` defaults to '' here, so an unset base in
+      // `runtime` mode produces a RELATIVE call — the exact shape of C-261. The sweep also
+      // proved the configured base (api.duffcloudservices.com) is tenant-unresolvable for
+      // this host-resolved route (400 "Unable to resolve site from request"), which arrives
+      // as JSON and is therefore left to the `!response.ok` branch below, unchanged. What
+      // platformFetch adds is that an HTML shell can no longer be mistaken for "no
+      // overrides for this page".
+      const response = await platformFetch(url, {
         headers: {
           Accept: 'application/json',
         },

package/dist/chunk-DAYLLSEE.js

@@ -1,3 +0,0 @@
-
-//# sourceMappingURL=chunk-DAYLLSEE.js.map
-//# sourceMappingURL=chunk-DAYLLSEE.js.map

package/dist/chunk-DAYLLSEE.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-DAYLLSEE.js"}