@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/legacy/languages/runtime.ts

@@ -0,0 +1,216 @@
+import { resolveLocaleRequest } from './routing'
+import {
+  canonicalLocale,
+  localePrefix,
+  RESERVED_LOCALE_PREFIXES,
+  validateLanguageSettings,
+} from './settings'
+import type {
+  LanguageSettings,
+  LocalizableField,
+  TranslationDocument,
+  TranslationOwner,
+} from './types'
+import { isSemanticallyEmpty, resolveField, languageFieldCandidate } from './resolution'
+
+export type LanguageRuntimeOwner = TranslationOwner & {
+  /** Published owner logical/dashboard path, retained for collection route discovery. */
+  path?: string
+  source: Record<string, unknown>
+  fields: LocalizableField[]
+  translations: Record<string, TranslationDocument>
+}
+export type LanguageSnapshot = {
+  version: 1
+  /** Runtime fallback diagnostic; successful endpoint snapshots omit this. */
+  status?: 'unavailable'
+  draft?: true
+  settings: LanguageSettings | null
+  owners: LanguageRuntimeOwner[]
+}
+export const LANGUAGE_PREFERENCE_COOKIE = 'u90-language'
+export const LANGUAGE_VERSION = 1 as const
+
+/** Explicitly mount this adapter before passing it to createManifestRoute. No country is trusted by default. */
+export function createLanguageRuntime(options: {
+  load: (request?: Request) => Promise<LanguageSnapshot>
+  knownPaths:
+    readonly string[] | ((path: string, snapshot: LanguageSnapshot) => boolean | Promise<boolean>)
+  /** Configured dynamic route templates, for prefix collision validation (not route existence). */
+  routePatterns?: readonly string[]
+  getTrustedCountry?: (request: Request) => string | undefined
+  /** Optional durable, site-scoped published snapshot for serverless cold starts. Never supply draft data. */
+  lastPublished?: LanguageSnapshot
+  onPublished?: (snapshot: LanguageSnapshot) => void
+  reservedPrefixes?: readonly string[]
+}) {
+  const usable = (snapshot: LanguageSnapshot) =>
+    snapshot?.version === 1 &&
+    Array.isArray(snapshot.owners) &&
+    (snapshot.settings === null || validateLanguageSettings(snapshot.settings).ok)
+  let lastPublished =
+    options.lastPublished &&
+    !options.lastPublished.draft &&
+    !options.lastPublished.status &&
+    usable(options.lastPublished)
+      ? structuredClone(options.lastPublished)
+      : undefined
+  const load = async (request?: Request): Promise<LanguageSnapshot> => {
+    try {
+      const snapshot = await options.load(request)
+      if (!usable(snapshot)) throw new Error('Invalid Languages snapshot')
+      if (!snapshot.draft && !snapshot.status) {
+        lastPublished = structuredClone(snapshot)
+        options.onPublished?.(structuredClone(snapshot))
+      }
+      return snapshot
+    } catch {
+      // Only a successful published read establishes configuration. Cold-start legacy is not cached.
+      return lastPublished
+        ? { ...structuredClone(lastPublished), status: 'unavailable' }
+        : { version: 1, settings: null, owners: [], status: 'unavailable' }
+    }
+  }
+  const known = async (path: string, snapshot: LanguageSnapshot) =>
+    typeof options.knownPaths === 'function'
+      ? options.knownPaths(path, snapshot)
+      : options.knownPaths.some((p) => p.replace(/\/$/, '') === path.replace(/\/$/, ''))
+  return {
+    languageVersion: LANGUAGE_VERSION,
+    load,
+    async handleRequest(request: Request): Promise<Response | null> {
+      const url = new URL(request.url)
+      const first = url.pathname.split('/').filter(Boolean)[0]?.toLowerCase() ?? ''
+      if (
+        [...RESERVED_LOCALE_PREFIXES, ...(options.reservedPrefixes ?? [])].includes(first) ||
+        url.pathname.split('/').at(-1)?.includes('.')
+      )
+        return null
+      // A failed configuration read must never masquerade as disabled Languages.
+      const snapshot = await load(request)
+      const { settings } = snapshot
+      if (!settings?.enabled) return null
+      for (const language of settings.languages)
+        if (await known(`/${localePrefix(language.locale)}`, snapshot))
+          throw new Error('Language prefix collides with a public route')
+      const checked = validateLanguageSettings(settings, {
+        pagePaths: [
+          ...(Array.isArray(options.knownPaths) ? options.knownPaths : []),
+          ...(options.routePatterns ?? []),
+        ],
+        reservedPrefixes: options.reservedPrefixes,
+      })
+      if (!checked.ok) throw new Error(checked.problems.join(' '))
+      const configured = settings.languages.find((l) => localePrefix(l.locale) === first)
+      const logical = configured
+        ? '/' + url.pathname.split('/').filter(Boolean).slice(1).join('/')
+        : url.pathname
+      if (!(await known(logical, snapshot))) return new Response('Not found', { status: 404 })
+      // Draft authority comes only from the authenticated snapshot loader. Preparing an inactive
+      // language must keep its explicit preview URL; visitor query/cookie values cannot opt in.
+      if (snapshot.draft === true && configured) return null
+      let preferredLocale: string | undefined
+      const cookie = request.headers
+        .get('cookie')
+        ?.split(';')
+        .map((v) => v.trim())
+        .find((v) => v.startsWith(`${LANGUAGE_PREFERENCE_COOKIE}=`))
+      try {
+        preferredLocale = cookie
+          ? decodeURIComponent(cookie.slice(LANGUAGE_PREFERENCE_COOKIE.length + 1))
+          : undefined
+      } catch {
+        /* malformed preferences are ignored */
+      }
+      const result = resolveLocaleRequest(settings, {
+        path: url.pathname + url.search,
+        knownPaths: [logical],
+        preferredLocale,
+        country: configured ? undefined : options.getTrustedCountry?.(request),
+        reservedPrefixes: options.reservedPrefixes,
+      })
+      return result.kind === 'redirect'
+        ? new Response(null, {
+            status: result.status,
+            headers: {
+              Location: new URL(result.target, url.origin).href,
+              'Cache-Control': result.cacheControl,
+              Vary: 'Cookie',
+            },
+          })
+        : null
+    },
+  }
+}
+
+const assign = (source: Record<string, unknown>, path: string[], value: unknown) => {
+  let cursor: Record<string, unknown> = source
+  for (const segment of path.slice(0, -1)) {
+    if (['__proto__', 'prototype', 'constructor'].includes(segment))
+      throw new TypeError('Unsafe field path')
+    cursor[segment] ??= {}
+    cursor = cursor[segment] as Record<string, unknown>
+  }
+  const last = path.at(-1)!
+  if (['__proto__', 'prototype', 'constructor'].includes(last))
+    throw new TypeError('Unsafe field path')
+  cursor[last] = structuredClone(value)
+}
+
+/** Apply only schema-enumerated copy slots, to raw values before reference/media hydration. */
+export function overlayLanguageOwner({
+  owner,
+  settings,
+  locale,
+}: {
+  owner: LanguageRuntimeOwner
+  settings: LanguageSettings
+  locale: string
+}) {
+  const source = structuredClone(owner.source)
+  const resolvedLocales: Record<string, string> = {}
+  let translated = 0
+  for (const slot of owner.fields) {
+    const candidate = (language: string) => {
+      if (language === settings.originalLocale) return slot.value
+      const field = owner.translations[language]?.fields[slot.address]
+      return languageFieldCandidate(slot, field)
+    }
+    const requested = candidate(locale)
+    const target = owner.translations[locale]?.fields[slot.address]
+    const keepsOriginal =
+      locale !== settings.originalLocale &&
+      target?.keepOriginal &&
+      target.sourceHash === slot.sourceHash
+    // Keep original resolves useful copy, but does not establish a translated public variant.
+    if (!keepsOriginal && !isSemanticallyEmpty(requested, slot.field.type)) translated++
+    const value = resolveField({
+      requested,
+      fallback: candidate(settings.defaultLocale),
+      original: slot.value,
+      type: slot.field.type,
+    })
+    if (value === undefined) continue
+    const chosen =
+      [locale, settings.defaultLocale, settings.originalLocale].find(
+        (language) => !isSemanticallyEmpty(candidate(language), slot.field.type),
+      ) ?? settings.originalLocale
+    const chosenField = owner.translations[chosen]?.fields[slot.address]
+    resolvedLocales[slot.address] =
+      chosenField?.keepOriginal && chosenField.sourceHash === slot.sourceHash
+        ? settings.originalLocale
+        : chosen
+    let path = slot.positionalPath.split('.')
+    if (owner.kind === 'page' && !slot.address.startsWith('seo.')) path = ['content', ...path]
+    if (owner.kind === 'layout') path = ['data', 'entries', ...path]
+    if (owner.kind === 'entry') path = ['data', ...path.slice(1)]
+    assign(source, path, value)
+  }
+  return { source, whollyFallback: translated === 0, resolvedLocales }
+}
+
+export function languagePreferenceCookie(locale: string, secure = false): string {
+  const canonical = canonicalLocale(locale)
+  if (!canonical) throw new TypeError('A valid locale is required')
+  return `${LANGUAGE_PREFERENCE_COOKIE}=${encodeURIComponent(canonical)}; Path=/; Max-Age=31536000; SameSite=Lax${secure ? '; Secure' : ''}`
+}

package/src/legacy/languages/seo.ts

@@ -0,0 +1,95 @@
+import type { SeoMetadata } from '../seo'
+import { localePath } from './routing'
+import type { LanguageSettings } from './types'
+export function languageMetadataFor({
+  metadata,
+  settings,
+  locale,
+  logicalPath,
+  origin,
+  whollyFallback = false,
+  indexableLocales,
+}: {
+  metadata: SeoMetadata
+  settings: LanguageSettings | null
+  locale: string
+  logicalPath: string
+  origin: string
+  whollyFallback?: boolean
+  /** Equivalent locales with indexable copy; compute from each raw owner, not just the current one. */
+  indexableLocales?: readonly string[]
+}): SeoMetadata {
+  if (!settings?.enabled) return metadata
+  const languages = Object.fromEntries(
+    settings.languages
+      .filter(
+        (l) =>
+          l.active &&
+          metadata.robots?.index !== false &&
+          (!indexableLocales || indexableLocales.includes(l.locale)) &&
+          !(whollyFallback && l.locale === locale),
+      )
+      .map((l) => [l.locale, new URL(localePath(logicalPath, l.locale), origin).href]),
+  )
+  languages['x-default'] = new URL(logicalPath, origin).href
+  return {
+    ...metadata,
+    alternates: {
+      ...metadata.alternates,
+      canonical: new URL(localePath(logicalPath, locale), origin).href,
+      languages,
+    },
+    openGraph: { ...metadata.openGraph, locale },
+    ...(whollyFallback ? { robots: { follow: false, index: false } } : {}),
+  }
+}
+export function languageSitemapFrom({
+  entries,
+  settings,
+  origin,
+  allowIndexing,
+}: {
+  entries: readonly {
+    logicalPath: string
+    lastModified?: string
+    noindex?: boolean
+    whollyFallbackLocales?: readonly string[]
+  }[]
+  settings: LanguageSettings | null
+  origin: string
+  allowIndexing: boolean
+}) {
+  if (!allowIndexing) return []
+  return entries
+    .filter((e) => !e.noindex)
+    .flatMap((entry) =>
+      settings?.enabled
+        ? settings.languages
+            .filter((l) => l.active && !entry.whollyFallbackLocales?.includes(l.locale))
+            .map((l) => ({
+              url: new URL(localePath(entry.logicalPath, l.locale), origin).href,
+              ...(entry.lastModified ? { lastModified: entry.lastModified } : {}),
+              alternates: {
+                languages: languageMetadataFor({
+                  metadata: {},
+                  settings,
+                  origin,
+                  locale: l.locale,
+                  logicalPath: entry.logicalPath,
+                  indexableLocales: settings.languages
+                    .filter(
+                      (language) =>
+                        language.active && !entry.whollyFallbackLocales?.includes(language.locale),
+                    )
+                    .map((language) => language.locale),
+                }).alternates?.languages,
+              },
+            }))
+        : [
+            {
+              url: new URL(entry.logicalPath, origin).href,
+              ...(entry.lastModified ? { lastModified: entry.lastModified } : {}),
+            },
+          ],
+    )
+}

package/src/legacy/languages/settings.ts

@@ -0,0 +1,211 @@
+import type { LanguageDefinition, LanguageSettings } from './types'
+
+export const ISO_COUNTRY_CODES: readonly string[] = Object.freeze(
+  'AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW'.split(
+    ' ',
+  ),
+)
+const ISO_COUNTRIES = new Set(ISO_COUNTRY_CODES)
+
+export const RESERVED_LOCALE_PREFIXES = [
+  '_next',
+  'api',
+  'assets',
+  'callback',
+  'media',
+  'oauth',
+  'preview',
+  'robots.txt',
+  'sitemap.xml',
+  'u90',
+] as const
+
+export const canonicalLocale = (value: unknown): null | string => {
+  if (typeof value !== 'string' || value.trim() !== value || value.length === 0 || value.length > 80) {
+    return null
+  }
+  try {
+    return Intl.getCanonicalLocales(value)[0] ?? null
+  } catch {
+    return null
+  }
+}
+
+export const localePrefix = (locale: string): string => {
+  const canonical = canonicalLocale(locale)
+  if (!canonical) throw new TypeError(`Invalid BCP 47 locale: ${locale}`)
+  return canonical.toLowerCase()
+}
+
+const activeLanguage = (settings: LanguageSettings, locale: unknown): LanguageDefinition | undefined => {
+  if (typeof locale !== 'string') return undefined
+  const canonical = canonicalLocale(locale)
+  if (!canonical) return undefined
+  return settings.languages.find(
+    (language) => language.active && language.locale.toLowerCase() === canonical.toLowerCase(),
+  )
+}
+
+export const activeLocale = (settings: LanguageSettings, locale: unknown): null | string =>
+  activeLanguage(settings, locale)?.locale ?? null
+
+export const assignedCountryLocale = (settings: LanguageSettings, country: unknown): null | string => {
+  if (typeof country !== 'string') return null
+  const canonicalCountry = country.toUpperCase()
+  if (!ISO_COUNTRIES.has(canonicalCountry)) return null
+  return activeLocale(settings, settings.countries[canonicalCountry])
+}
+
+export type LanguageSettingsValidation =
+  | { ok: false; problems: string[] }
+  | { ok: true; settings: LanguageSettings }
+
+const topLevel = (path: string): string =>
+  path.split(/[?#]/, 1)[0]?.split('/').filter(Boolean)[0]?.toLowerCase() ?? ''
+
+export const validateLanguageSettings = (
+  value: unknown,
+  options: { pagePaths?: readonly string[]; reservedPrefixes?: readonly string[] } = {},
+): LanguageSettingsValidation => {
+  const problems: string[] = []
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { ok: false, problems: ['Language settings must be an object'] }
+  }
+  const candidate = value as Partial<LanguageSettings>
+  if (!Array.isArray(candidate.languages)) {
+    return { ok: false, problems: ['Language settings must contain a languages array'] }
+  }
+  const seen = new Set<string>()
+  const languages: LanguageDefinition[] = []
+  for (const [index, language] of candidate.languages.entries()) {
+    if (!language || typeof language !== 'object' || Array.isArray(language)) {
+      problems.push(`languages[${index}] must be an object`)
+      continue
+    }
+    const canonical = canonicalLocale(language.locale)
+    if (!canonical) {
+      problems.push(`languages[${index}].locale is not a valid BCP 47 locale`)
+      continue
+    }
+    const key = canonical.toLowerCase()
+    if (seen.has(key)) problems.push(`languages[${index}].locale duplicates ${canonical}`)
+    seen.add(key)
+    const label = typeof language.label === 'string' ? language.label.trim() : ''
+    if (label.length === 0) {
+      problems.push(`languages[${index}].label is required`)
+    }
+    if (typeof language.active !== 'boolean') problems.push(`languages[${index}].active must be boolean`)
+    languages.push({ active: language.active === true, label, locale: canonical })
+  }
+
+  const byLocale = new Map(languages.map((language) => [language.locale.toLowerCase(), language]))
+  const original = canonicalLocale(candidate.originalLocale)
+  const defaultLocale = canonicalLocale(candidate.defaultLocale)
+  if (!original || !byLocale.has(original.toLowerCase())) {
+    problems.push('originalLocale must name a configured language')
+  }
+  const defaultLanguage = defaultLocale ? byLocale.get(defaultLocale.toLowerCase()) : undefined
+  if (!defaultLanguage) problems.push('defaultLocale must name a configured language')
+  else if (!defaultLanguage.active) problems.push('defaultLocale must name an active language')
+  if (candidate.enabled && languages.every((language) => !language.active)) {
+    problems.push('Enabled language settings require at least one active language')
+  }
+
+  const reserved = new Set(
+    [...RESERVED_LOCALE_PREFIXES, ...(options.reservedPrefixes ?? [])].map((prefix) =>
+      prefix.replace(/^\/+/, '').toLowerCase(),
+    ),
+  )
+  const pagePrefixes = new Set((options.pagePaths ?? []).map(topLevel).filter(Boolean))
+  for (const language of languages) {
+    const prefix = localePrefix(language.locale)
+    if (reserved.has(prefix)) problems.push(`${language.locale} collides with a reserved route prefix`)
+    if (pagePrefixes.has(prefix)) problems.push(`${language.locale} collides with an existing page path`)
+  }
+
+  const countries: Record<string, string> = {}
+  if (!candidate.countries || typeof candidate.countries !== 'object' || Array.isArray(candidate.countries)) {
+    problems.push('countries must be an object')
+  } else {
+    for (const [country, locale] of Object.entries(candidate.countries)) {
+      if (!ISO_COUNTRIES.has(country)) {
+        problems.push(`${country} is not an ISO 3166-1 alpha-2 country code in uppercase`)
+        continue
+      }
+      const canonical = canonicalLocale(locale)
+      const language = canonical ? byLocale.get(canonical.toLowerCase()) : undefined
+      if (!language?.active) {
+        problems.push(`countries.${country} must name an active configured language`)
+        continue
+      }
+      countries[country] = language.locale
+    }
+  }
+  if (typeof candidate.enabled !== 'boolean') problems.push('enabled must be boolean')
+  if (problems.length > 0) return { ok: false, problems }
+  return {
+    ok: true,
+    settings: {
+      countries,
+      defaultLocale: defaultLanguage!.locale,
+      enabled: candidate.enabled!,
+      languages,
+      originalLocale: byLocale.get(original!.toLowerCase())!.locale,
+    },
+  }
+}
+
+export const fallbackLocales = (settings: LanguageSettings, requestedLocale: string): string[] => {
+  if (!settings.enabled) return []
+  const output: string[] = []
+  const seen = new Set<string>()
+  for (const candidate of [requestedLocale, settings.defaultLocale, settings.originalLocale]) {
+    const canonical = canonicalLocale(candidate)
+    if (!canonical || seen.has(canonical.toLowerCase())) continue
+    seen.add(canonical.toLowerCase())
+    output.push(
+      settings.languages.find((language) => language.locale.toLowerCase() === canonical.toLowerCase())
+        ?.locale ?? canonical,
+    )
+  }
+  return output
+}
+
+export type LanguageLifecycleResult =
+  | { ok: false; problem: string }
+  | { ok: true; settings: LanguageSettings }
+
+export const deactivateLanguage = (
+  settings: LanguageSettings,
+  locale: string,
+  options: { defaultLocale?: string } = {},
+): LanguageLifecycleResult => {
+  const canonical = canonicalLocale(locale)
+  const found = canonical
+    ? settings.languages.find((language) => language.locale.toLowerCase() === canonical.toLowerCase())
+    : undefined
+  if (!found) return { ok: false, problem: 'The language is not configured' }
+  const replacement = options.defaultLocale ?? settings.defaultLocale
+  if (found.locale.toLowerCase() === replacement.toLowerCase()) {
+    return { ok: false, problem: 'Choose another active default language before deactivating the default' }
+  }
+  const replacementLocale = activeLocale(settings, replacement)
+  if (!replacementLocale) return { ok: false, problem: 'The replacement default language must be active' }
+  return {
+    ok: true,
+    settings: {
+      ...settings,
+      countries: Object.fromEntries(
+        Object.entries(settings.countries).filter(
+          ([, assigned]) => assigned.toLowerCase() !== found.locale.toLowerCase(),
+        ),
+      ),
+      defaultLocale: replacementLocale,
+      languages: settings.languages.map((language) =>
+        language.locale.toLowerCase() === found.locale.toLowerCase()
+          ? { ...language, active: false }
+          : { ...language },
+      ),
+    },
+  }
+}

package/src/legacy/languages/types.ts

@@ -0,0 +1,85 @@
+import type { EditorField } from '../contract'
+
+export const STABLE_ID_KEY = '_u90id' as const
+
+export type LanguageDefinition = {
+  active: boolean
+  label: string
+  locale: string
+}
+
+export type LanguageSettings = {
+  countries: Record<string, string>
+  defaultLocale: string
+  enabled: boolean
+  languages: LanguageDefinition[]
+  originalLocale: string
+}
+
+export type TranslationOwner = {
+  id: string
+  kind: 'entry' | 'layout' | 'page' | 'seo' | 'single'
+}
+
+export type TranslationField = {
+  keepOriginal?: boolean
+  needsReview?: boolean
+  /** Monotonic per-address revision, so writes to different fields do not conflict. */
+  revision: number
+  sourceHash: string
+  value?: unknown
+}
+
+export type TranslationDocument = {
+  fields: Record<string, TranslationField>
+  /** Revision of the source structure used to map positional paths to stable addresses. */
+  structureRevision: number
+}
+
+export type LocalizableField = {
+  address: string
+  field: EditorField
+  positionalPath: string
+  sourceHash: string
+  value: unknown
+}
+
+export type LanguageFieldHealth = {
+  address: string
+  missingRequired: boolean
+  missingSource: boolean
+  missingTranslation: boolean
+  needsReview: boolean
+  sourceChanged: boolean
+}
+
+export type LanguageHealth = {
+  fields: LanguageFieldHealth[]
+  keptOriginal: number
+  missingOptional: number
+  missingRequired: number
+  missingSource: number
+  needsReview: number
+  ready: boolean
+  sourceChanged: number
+  total: number
+  translated: number
+}
+
+export type IdentityFactory = () => string
+export type ContentNode = Record<string, unknown> & { [STABLE_ID_KEY]?: string }
+
+export type IdentityResult =
+  | { changed: boolean; content: ContentNode[]; ok: true }
+  | { ok: false; problem: string }
+
+export type TranslationPatch = {
+  address: string
+  expectedFieldRevision: number
+  expectedStructureRevision: number
+  field: Omit<TranslationField, 'revision'>
+}
+
+export type TranslationPatchResult =
+  | { ok: false; problem: string }
+  | { ok: true; translation: TranslationDocument }

package/src/legacy/languages.ts

@@ -0,0 +1,8 @@
+export * from './languages/fields'
+export * from './languages/hash'
+export * from './languages/health'
+export * from './languages/identity'
+export * from './languages/resolution'
+export * from './languages/routing'
+export * from './languages/settings'
+export * from './languages/types'