@crombolo/server 0.0.0-stage → 0.9.1

package/src/models-builder.ts

@@ -0,0 +1,106 @@
+/**
+ * Umbraco's ModelsBuilder over `crombolo generate`: the models are the
+ * TypeScript in `schema/content-types.d.ts`, written from the TOML schema.
+ *
+ * Umbraco reports staleness from a flag file written when a content type
+ * changes. There is nothing to flag here — the schema files are the truth — so
+ * "out of date" is answered by generating the types and comparing them with
+ * what is on disk, which cannot drift from the question being asked.
+ */
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import type {
+  ModelsBuilderInfo,
+  ModelsBuilderPort,
+  OutOfDateStatus,
+} from '@crombolo/api-management'
+import { generateTypes, loadSchemaDirectory, validateSchemaSet } from '@crombolo/schema'
+import type { CromboloConfig } from './config.ts'
+import { VERSION } from './config.ts'
+import { logger } from './logging.ts'
+
+/** The file `crombolo generate` writes, inside the schema directory. */
+export const GENERATED_FILE = 'content-types.d.ts'
+
+export type Intended = { types: string } | { problems: string[] }
+
+/** What `crombolo generate` would write now, or the problems stopping it. */
+export function intendedTypes(schemaDir: string): Intended {
+  if (!existsSync(schemaDir)) return { problems: [`No schema directory at ${schemaDir}`] }
+  const loaded = loadSchemaDirectory(schemaDir)
+  const problems = [...loaded.problems, ...validateSchemaSet(loaded.set)]
+  if (problems.length > 0)
+    return {
+      problems: problems.map((p) => `${p.file}${p.path ? ` (${p.path})` : ''}: ${p.message}`),
+    }
+  return { types: generateTypes(loaded.set) }
+}
+
+/** Undefined when the schema does not generate, so staleness is unknowable. */
+export async function compareModels(
+  schemaDir: string,
+): Promise<{ outOfDate: boolean } | undefined> {
+  const intended = intendedTypes(schemaDir)
+  if ('problems' in intended) return undefined
+  const target = join(schemaDir, GENERATED_FILE)
+  if (!existsSync(target)) return { outOfDate: true }
+  const current = await readFile(target, 'utf8').catch(() => undefined)
+  return { outOfDate: current !== intended.types }
+}
+
+export function createModelsBuilderPort(
+  config: Pick<CromboloConfig, 'schemaDir'>,
+): ModelsBuilderPort {
+  // Umbraco keeps the last generation error in memory and shows it on the
+  // dashboard; a build that succeeds clears it.
+  let lastError: string | null = null
+  const log = logger('models-builder')
+
+  const describe = async (): Promise<ModelsBuilderInfo> => {
+    const compared = await compareModels(config.schemaDir)
+    return {
+      // The models are TypeScript source, written on request: Umbraco's mode for
+      // exactly that. The client only explains its own four mode strings.
+      mode: 'SourceCodeManual',
+      canGenerate: true,
+      outOfDateModels: compared?.outOfDate ?? false,
+      trackingOutOfDateModels: true,
+      lastError,
+      version: VERSION,
+      // Shown to a person, so the path the CLI would print rather than an
+      // absolute one from inside a container.
+      modelsNamespace: relative(process.cwd(), join(config.schemaDir, GENERATED_FILE)),
+    }
+  }
+
+  return {
+    info: describe,
+
+    async status(): Promise<OutOfDateStatus> {
+      const compared = await compareModels(config.schemaDir)
+      if (!compared) return 'Unknown'
+      return compared.outOfDate ? 'OutOfDate' : 'Current'
+    },
+
+    async build() {
+      const intended = intendedTypes(config.schemaDir)
+      if ('problems' in intended) {
+        lastError = intended.problems.join('\n')
+        log.warn('Models were not generated: {problems}', { problems: intended.problems.length })
+        return { ok: false, error: lastError }
+      }
+      const target = join(config.schemaDir, GENERATED_FILE)
+      try {
+        await writeFile(target, intended.types)
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error)
+        log.error('Models could not be written to {target}', { target })
+        return { ok: false, error: lastError }
+      }
+      lastError = null
+      log.info('Models written to {target}', { target })
+      return { ok: true }
+    },
+  }
+}

package/src/no-nodes.ts

@@ -0,0 +1,64 @@
+/**
+ * The holding page for a site with nothing published — Umbraco's "no nodes"
+ * screen, which `docs/06-features.md` asks for.
+ *
+ * It answers 404, not 200: a brand-new site is not a working one, and anything
+ * watching the URL should keep saying so until a page is published. It is only
+ * reached when the published tree is empty, so a missing path on a live site is
+ * the bare 404 it always was.
+ */
+export function noNodesPage(options: { siteName: string; backOfficePath: string }): string {
+  const site = escapeHtml(options.siteName)
+  const backoffice = escapeHtml(options.backOfficePath)
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${site} — nothing published yet</title>
+<style>
+  :root { color-scheme: light dark; }
+  body {
+    margin: 0; min-height: 100vh; display: grid; place-items: center;
+    font: 16px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+    background: #f6f5f3; color: #1b1b1b;
+  }
+  main { max-width: 34rem; padding: 2.5rem 1.5rem; }
+  h1 { font-size: 1.6rem; margin: 0 0 .75rem; }
+  p { margin: 0 0 1rem; }
+  ol { margin: 0 0 1.5rem; padding-left: 1.25rem; }
+  li { margin-bottom: .35rem; }
+  code { font-size: .9em; background: #e9e7e2; padding: .1em .35em; border-radius: 3px; }
+  a.cta { display: inline-block; padding: .55rem 1rem; border-radius: 4px; background: #1b1b1b; color: #fff; text-decoration: none; }
+  .fine { font-size: .85rem; color: #6b6b63; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #16171a; color: #e8e6e3; }
+    code { background: #26282c; }
+    a.cta { background: #e8e6e3; color: #16171a; }
+    .fine { color: #9a9a93; }
+  }
+</style>
+</head>
+<body>
+<main>
+  <h1>Nothing is published yet</h1>
+  <p>${site} is running. There is no published page for visitors to see, so this is what the site serves.</p>
+  <ol>
+    <li>Sign in to the backoffice.</li>
+    <li>Create a page from one of the content types in <code>schema/</code> — if there are none, add one there first.</li>
+    <li>Publish it. This page goes away.</li>
+  </ol>
+  <p><a class="cta" href="${backoffice}">Open the backoffice</a></p>
+  <p class="fine">Served with a 404: nothing is published, and a crawler should be told that plainly.</p>
+</main>
+</body>
+</html>
+`
+}
+
+const escapeHtml = (value: string): string =>
+  value.replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string,
+  )

package/src/not-implemented.ts

@@ -0,0 +1,44 @@
+/**
+ * Development aid: a line on the console the first time the backoffice calls an
+ * operation that answers 501, and a running list, so one walk through a
+ * section shows everything it still needs.
+ */
+import type { OperationInfo } from '@crombolo/contracts'
+
+export interface NotImplementedEntry {
+  operationId: string
+  method: string
+  path: string
+  /** How many times it was asked for. */
+  count: number
+}
+
+export class NotImplementedLog {
+  readonly #entries = new Map<string, NotImplementedEntry>()
+  readonly #write: (line: string, entry: NotImplementedEntry) => void
+
+  constructor(
+    write: (line: string, entry: NotImplementedEntry) => void = (line) => console.warn(line),
+  ) {
+    this.#write = write
+  }
+
+  record(operation: OperationInfo, request: Request): void {
+    const existing = this.#entries.get(operation.operationId)
+    if (existing) {
+      existing.count += 1
+      return
+    }
+    const path = new URL(request.url).pathname
+    const entry = { operationId: operation.operationId, method: request.method, path, count: 1 }
+    this.#entries.set(operation.operationId, entry)
+    this.#write(
+      `501 ${operation.operationId.padEnd(40)} ${request.method} ${path}   (${this.#entries.size} missing so far)`,
+      entry,
+    )
+  }
+
+  entries(): NotImplementedEntry[] {
+    return [...this.#entries.values()]
+  }
+}

package/src/oembed.ts

@@ -0,0 +1,144 @@
+/**
+ * The rich text editor's "embed" dialog asks the server for a URL's embed
+ * markup (Umbraco's `OEmbedService`). These are Umbraco's providers, each asked
+ * for JSON; a photo becomes an `<img>`, anything else is the provider's HTML.
+ */
+
+interface Provider {
+  name: string
+  endpoint: string
+  patterns: RegExp[]
+}
+
+export const OEMBED_PROVIDERS: readonly Provider[] = [
+  {
+    name: 'YouTube',
+    endpoint: 'https://www.youtube.com/oembed',
+    patterns: [
+      /^https?:\/\/(www\.)?youtu\.be\//,
+      /^https?:\/\/(www\.)?youtube\.com\/watch/,
+      /^https?:\/\/(www\.)?youtube\.com\/shorts\//,
+      /^https?:\/\/(www\.)?youtube\.com\/live\//,
+    ],
+  },
+  {
+    name: 'Vimeo',
+    endpoint: 'https://vimeo.com/api/oembed.json',
+    patterns: [/^https?:\/\/(www\.)?vimeo\.com\//],
+  },
+  {
+    name: 'X',
+    endpoint: 'https://publish.x.com/oembed',
+    patterns: [/^https?:\/\/(www\.)?(twitter|x)\.com\/[^/]+\/status\//],
+  },
+  {
+    name: 'DailyMotion',
+    endpoint: 'https://www.dailymotion.com/services/oembed',
+    patterns: [/^https?:\/\/(www\.)?dailymotion\.com\/video\//],
+  },
+  {
+    name: 'Flickr',
+    endpoint: 'https://www.flickr.com/services/oembed/',
+    patterns: [/^https?:\/\/(www\.)?flickr\.com\/photos\//, /^https?:\/\/flic\.kr\/p\//],
+  },
+  {
+    name: 'GettyImages',
+    endpoint: 'https://embed.gettyimages.com/oembed',
+    patterns: [/^https?:\/\/(www\.)?gty\.im\//, /^https?:\/\/(www\.)?gettyimages\.com\/detail\//],
+  },
+  {
+    name: 'Giphy',
+    endpoint: 'https://giphy.com/services/oembed',
+    patterns: [/^https?:\/\/(www\.)?giphy\.com\//, /^https?:\/\/(www\.)?gph\.is\//],
+  },
+  {
+    name: 'Hulu',
+    endpoint: 'https://www.hulu.com/api/oembed.json',
+    patterns: [/^https?:\/\/(www\.)?hulu\.com\/watch\//],
+  },
+  {
+    name: 'Issuu',
+    endpoint: 'https://issuu.com/oembed',
+    patterns: [/^https?:\/\/(www\.)?issuu\.com\/[^/]+\/docs\//],
+  },
+  {
+    name: 'Kickstarter',
+    endpoint: 'https://www.kickstarter.com/services/oembed',
+    patterns: [/^https?:\/\/(www\.)?kickstarter\.com\/projects\//],
+  },
+  {
+    name: 'LottieFiles',
+    endpoint: 'https://embed.lottiefiles.com/oembed',
+    patterns: [/^https?:\/\/(www\.)?lottiefiles\.com\//],
+  },
+  {
+    name: 'Slideshare',
+    endpoint: 'https://www.slideshare.net/api/oembed/2',
+    patterns: [/^https?:\/\/(www\.)?slideshare\.net\//],
+  },
+  {
+    name: 'SoundCloud',
+    endpoint: 'https://soundcloud.com/oembed',
+    patterns: [/^https?:\/\/(www\.)?soundcloud\.com\//],
+  },
+  {
+    name: 'Ted',
+    endpoint: 'https://www.ted.com/services/v1/oembed.json',
+    patterns: [/^https?:\/\/(www\.)?ted\.com\/talks\//],
+  },
+]
+
+export type OEmbedResult =
+  | { ok: true; markup: string }
+  | { ok: false; status: 'unsupported' | 'failed'; reason: string }
+
+const escapeAttribute = (value: string) =>
+  value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+
+export function createOEmbedService(fetcher: typeof fetch = fetch) {
+  return {
+    async markup(url: string, maxWidth?: number, maxHeight?: number): Promise<OEmbedResult> {
+      const provider = OEMBED_PROVIDERS.find((p) => p.patterns.some((pattern) => pattern.test(url)))
+      if (!provider)
+        return {
+          ok: false,
+          status: 'unsupported',
+          reason: 'No oEmbed provider was found for the specified url.',
+        }
+      const request = new URL(provider.endpoint)
+      request.searchParams.set('url', url)
+      request.searchParams.set('format', 'json')
+      if (maxWidth) request.searchParams.set('maxwidth', String(maxWidth))
+      if (maxHeight) request.searchParams.set('maxheight', String(maxHeight))
+      let body: Record<string, unknown>
+      try {
+        const response = await fetcher(request, { headers: { accept: 'application/json' } })
+        if (!response.ok) throw new Error(`${provider.name} answered ${response.status}`)
+        body = (await response.json()) as Record<string, unknown>
+      } catch (error) {
+        return {
+          ok: false,
+          status: 'failed',
+          reason: error instanceof Error ? error.message : String(error),
+        }
+      }
+      if (body.type === 'photo' && typeof body.url === 'string')
+        return {
+          ok: true,
+          markup: `<img src="${escapeAttribute(body.url)}" width="${escapeAttribute(String(body.width ?? ''))}" height="${escapeAttribute(String(body.height ?? ''))}" alt="${escapeAttribute(String(body.title ?? ''))}" />`,
+        }
+      if (typeof body.html === 'string') return { ok: true, markup: body.html }
+      return {
+        ok: false,
+        status: 'failed',
+        reason: `${provider.name} returned no embeddable markup.`,
+      }
+    },
+  }
+}
+
+export type OEmbedService = ReturnType<typeof createOEmbedService>