create-we8 0.1.0

package/template/src/lib/types.ts

@@ -0,0 +1,180 @@
+/**
+ * The data-layer contract.
+ *
+ * These types are the site's OWN vocabulary. Nothing here imports we8, and
+ * nothing here is shaped by any particular API: that is the whole point. A
+ * page renders a `Post`, not a we8 post, so replacing the backend is a matter
+ * of writing one more `SiteBackend` and pointing `data.ts` at it.
+ *
+ * See the README section "The data-layer contract" for the rules.
+ */
+
+/**
+ * The kinds of content this site publishes. Blog and article are editorial;
+ * research, whitepaper, and case study are the long-form material the
+ * resources page lays out. The list matches the we8 CMS vocabulary so the
+ * default backend needs no translation table, but it belongs to the site: a
+ * different backend maps its own types onto these.
+ */
+export const CONTENT_TYPES = [
+  'blog',
+  'article',
+  'news',
+  'research',
+  'whitepaper',
+  'case-study',
+] as const;
+
+export type ContentType = (typeof CONTENT_TYPES)[number];
+
+/** The content types the resources page collects. */
+export const RESOURCE_TYPES: readonly ContentType[] = ['research', 'whitepaper', 'case-study'];
+
+export interface AuthorLink {
+  label: string;
+  url: string;
+}
+
+export interface Author {
+  slug: string;
+  name: string;
+  roleTitle: string | null;
+  bio: string | null;
+  avatarUrl: string | null;
+  links: AuthorLink[];
+}
+
+/**
+ * An inline call to action attached to a post. `link` is a plain button.
+ * `gated-download` asks for an email through `formKey` and then reveals
+ * `assetUrl`.
+ */
+export interface CallToAction {
+  style: 'link' | 'gated-download';
+  heading: string | null;
+  buttonLabel: string;
+  url: string | null;
+  formKey: string | null;
+  assetUrl: string | null;
+}
+
+/**
+ * The answer-first block that makes a page quotable by an answer engine: the
+ * question a person actually types, and a short self-contained answer that
+ * stands on its own when lifted out of the page.
+ *
+ * `source` records where it came from, because the honest fallback matters:
+ * `authored` means an editor wrote the question and the answer, `derived`
+ * means the site built one from the title and the excerpt because the backend
+ * has no answer fields yet. Only `authored` blocks become `FAQPage` JSON-LD;
+ * claiming a derived summary is a curated answer would be a lie to the crawler.
+ */
+export interface AnswerBlock {
+  question: string;
+  summary: string;
+  source: 'authored' | 'derived';
+}
+
+export interface Post {
+  slug: string;
+  type: ContentType;
+  title: string;
+  excerpt: string | null;
+  /** Markdown. Rendered by `lib/markdown.ts`, never by a page. */
+  content: string;
+  coverImageUrl: string | null;
+  category: string | null;
+  tags: string[];
+  /** Slugs of the bylined authors, in order. */
+  authorSlugs: string[];
+  /** ISO 8601. */
+  publishedAt: string;
+  answer: AnswerBlock | null;
+  cta: CallToAction | null;
+  /** Rounded reading time in minutes, or null when the backend does not count words. */
+  readingMinutes: number | null;
+}
+
+export interface PostPage {
+  items: Post[];
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+export interface PostQuery {
+  type?: ContentType;
+  tag?: string;
+  category?: string;
+  page?: number;
+  pageSize?: number;
+}
+
+/** Site-level SEO fallbacks. A page's own values always win over these. */
+export interface SiteSeo {
+  defaultTitle: string | null;
+  /** `%s` is the page-title placeholder, for example `%s | Northgate Tools`. */
+  titleTemplate: string | null;
+  metaDescription: string | null;
+  ogImageUrl: string | null;
+  twitterHandle: string | null;
+  /** True when the site asks search engines to stay away. */
+  noindex: boolean;
+}
+
+export interface SiteIdentity {
+  name: string;
+  /** The site's canonical origin, no trailing slash. */
+  siteUrl: string;
+  seo: SiteSeo;
+  publisher: { name: string; logoUrl: string | null } | null;
+  /**
+   * The path prefix the BACKEND believes each content type is served under.
+   * Advisory: this template routes by its own `SECTIONS` map in `data.ts`, so
+   * a backend whose paths disagree cannot produce links to pages that do not
+   * exist. Useful for reconciling the two.
+   */
+  contentPaths: Record<ContentType, string>;
+}
+
+/** The site documents a backend can serve at the site root. */
+export type DocumentKind = 'llms-txt' | 'design-md';
+
+/**
+ * Everything a page can ask for. Implement this once per backend; that is the
+ * entire porting surface.
+ *
+ * Every method is build-time and read-only. Writes (form submissions, visit
+ * beacons, consent) do not appear here on purpose: they happen in the browser
+ * against a live API, so they are a property of the runtime configuration
+ * (`runtime` in `data.ts`), not of the content source.
+ */
+export interface SiteBackend {
+  /** A short name for the build log and the footer, for example `we8` or `fixtures`. */
+  readonly name: string;
+  identity(): Promise<SiteIdentity>;
+  listPosts(query?: PostQuery): Promise<PostPage>;
+  /** Every published post, newest first. Used by listings, the sitemap, and static paths. */
+  listAllPosts(): Promise<Post[]>;
+  getPost(slug: string): Promise<Post | null>;
+  listAuthors(): Promise<Author[]>;
+  getAuthor(slug: string): Promise<Author | null>;
+  /** A site document's body. `''` when the backend has none, which is not an error. */
+  getDocument(kind: DocumentKind): Promise<string>;
+  /**
+   * Absolute URLs of content the backend knows about but this site does not
+   * statically render. Merged into the site's own sitemap. Usually empty.
+   */
+  extraSitemapUrls(siteUrl: string): Promise<string[]>;
+}
+
+/**
+ * How the browser should talk to a live backend. `enabled: false` means this
+ * build has no API behind it, so the form, the consent banner, and the visit
+ * beacon are not rendered at all rather than rendered dead.
+ */
+export interface RuntimeConfig {
+  enabled: boolean;
+  key: string | null;
+  apiUrl: string | null;
+}

package/template/src/lib/we8-backend.ts

@@ -0,0 +1,254 @@
+/**
+ * The we8 backend: the data-layer contract implemented over the we8 `/v1` API.
+ *
+ * This is the ONLY module in the template that imports `@we8/astro` or
+ * `@we8/client`. Everything else, `data.ts` included, speaks the site's own
+ * vocabulary from `types.ts`. Deleting this file and its entry in `data.ts` is
+ * the entire cost of moving to a different backend.
+ *
+ * One build-time pass loads the whole content graph and memoizes it: the list
+ * endpoint gives slugs and content, and each post's detail endpoint resolves
+ * its byline (a post carries author ids, which no public consumer can turn
+ * into names). A starter-sized site does this once per build; if your site
+ * outgrows it, page `listPosts` directly and drop `listAllPosts`.
+ */
+import {
+  createBuildClient,
+  mergeSitemap,
+  tryResolveConfig,
+  type EnvLike,
+  type We8AstroConfig,
+  type We8Author,
+  type We8Post,
+} from '@we8/astro';
+import type {
+  Author,
+  CallToAction,
+  ContentType,
+  DocumentKind,
+  Post,
+  PostPage,
+  PostQuery,
+  RuntimeConfig,
+  SiteBackend,
+  SiteIdentity,
+} from './types.js';
+import { CONTENT_TYPES } from './types.js';
+
+/** Average adult reading speed, words per minute. Only used when the API counted words. */
+const WORDS_PER_MINUTE = 220;
+
+/**
+ * Read the answer-first fields off a post.
+ *
+ * The `/v1` dialect carries them flat: `answerSummary` (editor-authored, the
+ * only kind that becomes FAQPage markup) and `questionHeading` (falls back to
+ * the title). Both are optional on older backends, so the read stays
+ * defensive and the template degrades to a derived block without them.
+ */
+function readAnswer(post: We8Post): Post['answer'] {
+  const summary = typeof post.answerSummary === 'string' ? post.answerSummary.trim() : '';
+  if (!summary) return null;
+  const question = typeof post.questionHeading === 'string' ? post.questionHeading.trim() : '';
+  return { question: question || post.title, summary, source: 'authored' };
+}
+
+function toContentType(value: string): ContentType {
+  return (CONTENT_TYPES as readonly string[]).includes(value)
+    ? (value as ContentType)
+    : 'blog';
+}
+
+function toCta(post: We8Post): CallToAction | null {
+  const cta = post.cta;
+  if (!cta) return null;
+  return {
+    style: cta.style,
+    heading: cta.heading ?? null,
+    buttonLabel: cta.buttonLabel,
+    url: cta.url ?? null,
+    formKey: cta.formKey ?? null,
+    assetUrl: cta.assetUrl ?? null,
+  };
+}
+
+function toAuthor(author: We8Author): Author {
+  return {
+    slug: author.slug,
+    name: author.name,
+    roleTitle: author.roleTitle ?? null,
+    bio: author.bio ?? null,
+    avatarUrl: author.avatarUrl ?? null,
+    links: author.links.map((link) => ({ label: link.label, url: link.url })),
+  };
+}
+
+function toPost(post: We8Post, authorSlugs: string[]): Post {
+  return {
+    slug: post.slug,
+    type: toContentType(post.type),
+    title: post.title,
+    excerpt: post.excerpt,
+    content: post.content,
+    coverImageUrl: post.coverImageUrl,
+    category: post.category,
+    tags: post.tags,
+    authorSlugs,
+    publishedAt: post.publishedAt,
+    answer: readAnswer(post),
+    cta: toCta(post),
+    readingMinutes:
+      post.wordCount === null ? null : Math.max(1, Math.round(post.wordCount / WORDS_PER_MINUTE)),
+  };
+}
+
+interface Graph {
+  posts: Post[];
+  authors: Author[];
+}
+
+export function createWe8Backend(config: We8AstroConfig, fetchImpl?: typeof fetch): SiteBackend {
+  const client = createBuildClient(config, fetchImpl);
+  let graph: Promise<Graph> | null = null;
+
+  async function loadGraph(): Promise<Graph> {
+    // 50 is the largest page the API accepts; a larger request is a 400.
+    const pageSize = 50;
+    const raw: We8Post[] = [];
+    for (let page = 1; page <= 100; page++) {
+      const { items, total } = await client.posts.list({ page, pageSize });
+      raw.push(...items);
+      if (items.length === 0 || raw.length >= total) break;
+    }
+
+    const authorsBySlug = new Map<string, Author>();
+    const posts: Post[] = [];
+    for (const summary of raw) {
+      // The detail route is what resolves the byline; the list route carries
+      // author ids only.
+      const detail = await client.posts.get(summary.slug);
+      const slugs: string[] = [];
+      for (const author of detail.authors) {
+        if (!authorsBySlug.has(author.slug)) authorsBySlug.set(author.slug, toAuthor(author));
+        slugs.push(author.slug);
+      }
+      posts.push(toPost(detail.post, slugs));
+    }
+
+    posts.sort((a, b) => b.publishedAt.localeCompare(a.publishedAt));
+    return { posts, authors: [...authorsBySlug.values()] };
+  }
+
+  function load(): Promise<Graph> {
+    graph ??= loadGraph();
+    return graph;
+  }
+
+  function matches(post: Post, query: PostQuery): boolean {
+    if (query.type && post.type !== query.type) return false;
+    if (query.tag && !post.tags.includes(query.tag)) return false;
+    if (query.category && post.category !== query.category) return false;
+    return true;
+  }
+
+  return {
+    name: 'we8',
+
+    async identity(): Promise<SiteIdentity> {
+      const site = await client.site.config();
+      const contentPaths = Object.fromEntries(
+        CONTENT_TYPES.map((type) => [type, site.contentPaths[type] ?? site.postsPathPrefix]),
+      ) as Record<ContentType, string>;
+      return {
+        name: site.name ?? site.publisher?.name ?? '',
+        siteUrl: site.siteUrl.replace(/\/+$/, ''),
+        seo: {
+          defaultTitle: site.seo.defaultTitle ?? null,
+          titleTemplate: site.seo.titleTemplate ?? null,
+          metaDescription: site.seo.metaDescription ?? null,
+          ogImageUrl: site.seo.ogImageUrl ?? null,
+          twitterHandle: site.seo.twitterHandle ?? null,
+          noindex: site.seo.discourageSearchEngines,
+        },
+        publisher: site.publisher
+          ? { name: site.publisher.name, logoUrl: site.publisher.logoUrl ?? null }
+          : null,
+        contentPaths,
+      };
+    },
+
+    async listPosts(query: PostQuery = {}): Promise<PostPage> {
+      const { posts } = await load();
+      const filtered = posts.filter((post) => matches(post, query));
+      const page = Math.max(1, query.page ?? 1);
+      const pageSize = Math.max(1, query.pageSize ?? 10);
+      const start = (page - 1) * pageSize;
+      return {
+        items: filtered.slice(start, start + pageSize),
+        page,
+        pageSize,
+        total: filtered.length,
+      };
+    },
+
+    async listAllPosts(): Promise<Post[]> {
+      return (await load()).posts;
+    },
+
+    async getPost(slug: string): Promise<Post | null> {
+      return (await load()).posts.find((post) => post.slug === slug) ?? null;
+    },
+
+    async listAuthors(): Promise<Author[]> {
+      return (await load()).authors;
+    },
+
+    async getAuthor(slug: string): Promise<Author | null> {
+      return (await load()).authors.find((author) => author.slug === slug) ?? null;
+    },
+
+    async getDocument(kind: DocumentKind): Promise<string> {
+      const document = await client.documents.get(kind);
+      return document.content;
+    },
+
+    async extraSitemapUrls(siteUrl: string): Promise<string[]> {
+      // Ask the API for every slug it publishes and subtract the ones this
+      // build rendered. Normally empty; it stops content from vanishing from
+      // the sitemap when the site routes only part of what the CMS holds.
+      const { posts } = await load();
+      const rendered = new Set(posts.map((post) => post.slug));
+      const base = siteUrl.replace(/\/+$/, '');
+      const identity = await this.identity();
+      const all = await mergeSitemap({
+        config,
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+        map: (slug) => slug,
+      });
+      return all
+        .filter((slug) => !rendered.has(slug))
+        .map((slug) => `${base}${identity.contentPaths.blog}/${slug}`);
+    },
+  };
+}
+
+/**
+ * Build a we8 backend from the environment, or `null` when we8 is not
+ * configured. This is the whole detection rule: both `WE8_API_URL` and
+ * `WE8_PUBLISHABLE_KEY` present means live, anything else means fall back.
+ */
+export function resolveWe8Backend(env: EnvLike, fetchImpl?: typeof fetch): SiteBackend | null {
+  const config = tryResolveConfig(env);
+  return config ? createWe8Backend(config, fetchImpl) : null;
+}
+
+/**
+ * The browser-side half of the we8 configuration: the publishable key and the
+ * API base, or nulls when we8 is not configured. Kept here so `data.ts` stays
+ * free of we8 imports.
+ */
+export function resolveWe8Runtime(env: EnvLike): RuntimeConfig {
+  const config = tryResolveConfig(env);
+  if (!config?.apiUrl) return { enabled: false, key: null, apiUrl: null };
+  return { enabled: true, key: config.key, apiUrl: config.apiUrl };
+}

package/template/src/pages/about.astro

@@ -0,0 +1,96 @@
+---
+/**
+ * About.
+ *
+ * A content page with question-phrased headings, which is the whole AEO habit
+ * in one file: every `##` is something a person would type, and the paragraph
+ * under it answers that question without needing the rest of the page.
+ *
+ * The team list comes from the data layer's author roster, so it stays true as
+ * the CMS changes rather than drifting into a hand-maintained list.
+ */
+import AnswerBlock from '../components/AnswerBlock.astro';
+import JsonLd from '../components/JsonLd.astro';
+import BaseLayout from '../layouts/BaseLayout.astro';
+import { authorPath, getAuthors, getIdentity } from '../lib/data.js';
+import { breadcrumbJsonLd, faqJsonLd } from '../lib/seo.js';
+
+const identity = await getIdentity();
+const authors = await getAuthors();
+
+const answer = {
+  question: `Who is ${identity.name}?`,
+  summary: `${identity.name} is a small team building maintenance planning software for workshops under fifty machines. We started on a maintenance desk, not in a boardroom, and the product still reflects that.`,
+  source: 'authored' as const,
+};
+---
+
+<BaseLayout
+  identity={identity}
+  seo={{
+    title: 'About',
+    description: answer.summary,
+  }}
+>
+  <Fragment slot="jsonLd">
+    <JsonLd data={faqJsonLd([answer])} />
+    <JsonLd
+      data={breadcrumbJsonLd(
+        [
+          { name: 'Home', path: '/' },
+          { name: 'About', path: '/about' },
+        ],
+        identity,
+      )}
+    />
+  </Fragment>
+
+  <div class="stack prose">
+    <h1>About {identity.name}</h1>
+    <AnswerBlock answer={answer} showQuestion={false} />
+
+    <h2>Why does this exist?</h2>
+    <p>
+      Maintenance software is built for plants and sold to workshops. The result is a system whose
+      setup costs more attention than the maintenance it manages, abandoned within a year and
+      quietly replaced by a spreadsheet. We built the spreadsheet's replacement instead: runtime
+      scheduling, a six field work order, and downtime measured from two timestamps.
+    </p>
+
+    <h2>What will you not sell us?</h2>
+    <p>
+      Sensors, in year one. Condition monitoring is an answer to a question you should be able to
+      state out loud, and most shops cannot state it yet because they are not counting runtime.
+      Counting runtime is free. We would rather you did that first and bought nothing.
+    </p>
+
+    <h2>How do you handle our data?</h2>
+    <p>
+      Your maintenance records are yours. Everything exports as CSV, including after you stop
+      paying us, and we do not sell or share anything. This site counts page views only, after you
+      agree to it, and it works exactly the same if you decline.
+    </p>
+
+    <h2>Who works here?</h2>
+    {
+      authors.length > 0 ? (
+        <ul>
+          {authors.map((author) => (
+            <li>
+              <a href={authorPath(author)}>{author.name}</a>
+              {author.roleTitle && <span class="meta">, {author.roleTitle}</span>}
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <p>The team roster appears here once authors are published in the CMS.</p>
+      )
+    }
+
+    <h2>How do we get in touch?</h2>
+    <p>
+      The <a href="/contact">contact page</a> reaches us directly. We answer within two working
+      days, and there is no sales sequence behind it.
+    </p>
+  </div>
+</BaseLayout>

package/template/src/pages/authors/[slug].astro

@@ -0,0 +1,113 @@
+---
+/**
+ * An author page: who wrote this, and everything they wrote.
+ *
+ * Author pages matter more than they look. They are what turns a byline into a
+ * source an answer engine can attribute, and schema.org `Person` with a real
+ * bio and a real list of work is the cheapest credibility signal a small site
+ * can emit.
+ */
+import type { GetStaticPaths } from 'astro';
+import JsonLd from '../../components/JsonLd.astro';
+import PostCard from '../../components/PostCard.astro';
+import BaseLayout from '../../layouts/BaseLayout.astro';
+import {
+  authorPath,
+  getAuthors,
+  getIdentity,
+  getPostsByAuthor,
+  postUrl,
+} from '../../lib/data.js';
+import { breadcrumbJsonLd } from '../../lib/seo.js';
+
+export const getStaticPaths = (async () => {
+  const authors = await getAuthors();
+  const identity = await getIdentity();
+  const entries = [];
+  for (const author of authors) {
+    entries.push({
+      params: { slug: author.slug },
+      props: { author, posts: await getPostsByAuthor(author.slug), identity },
+    });
+  }
+  return entries;
+}) satisfies GetStaticPaths;
+
+const { author, posts, identity } = Astro.props;
+
+const personJsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'Person',
+  name: author.name,
+  url: `${identity.siteUrl}${authorPath(author)}`,
+  ...(author.roleTitle ? { jobTitle: author.roleTitle } : {}),
+  ...(author.bio ? { description: author.bio } : {}),
+  ...(author.avatarUrl ? { image: author.avatarUrl } : {}),
+  worksFor: { '@type': 'Organization', name: identity.publisher?.name ?? identity.name },
+  ...(posts.length
+    ? {
+        subjectOf: posts.map((post) => ({
+          '@type': 'Article',
+          headline: post.title,
+          url: postUrl(post, identity),
+        })),
+      }
+    : {}),
+};
+---
+
+<BaseLayout
+  identity={identity}
+  seo={{
+    title: author.name,
+    description:
+      author.bio ??
+      `${author.name} writes for ${identity.name} about maintenance planning for small workshops.`,
+  }}
+>
+  <Fragment slot="jsonLd">
+    <JsonLd data={personJsonLd} />
+    <JsonLd
+      data={breadcrumbJsonLd(
+        [
+          { name: 'Home', path: '/' },
+          { name: author.name, path: authorPath(author) },
+        ],
+        identity,
+      )}
+    />
+  </Fragment>
+
+  <div class="stack">
+    <header class="prose">
+      <h1>{author.name}</h1>
+      {author.roleTitle && <p class="lede">{author.roleTitle}</p>}
+      {author.bio && <p>{author.bio}</p>}
+      {
+        author.links.length > 0 && (
+          <p class="meta">
+            {author.links.map((link, index) => (
+              <>
+                {index > 0 && ' · '}
+                <a href={link.url}>{link.label}</a>
+              </>
+            ))}
+          </p>
+        )
+      }
+    </header>
+
+    {
+      posts.length > 0 && (
+        <section aria-labelledby="by-author">
+          <h2 id="by-author">Written by {author.name}</h2>
+          <ul class="grid">
+            {posts.map((post) => (
+              <PostCard post={post} />
+            ))}
+          </ul>
+        </section>
+      )
+    }
+  </div>
+</BaseLayout>

package/template/src/pages/blog/[slug].astro

@@ -0,0 +1,28 @@
+---
+/**
+ * One blog post. The page itself is four lines of data fetching: the rendering
+ * lives in PostLayout, shared with the resources section.
+ */
+import type { GetStaticPaths } from 'astro';
+import PostLayout from '../../layouts/PostLayout.astro';
+import { bylineFor, getArticles, getAuthors, getIdentity } from '../../lib/data.js';
+
+export const getStaticPaths = (async () => {
+  const posts = await getArticles();
+  const authors = await getAuthors();
+  const identity = await getIdentity();
+  return posts.map((post) => ({
+    params: { slug: post.slug },
+    props: { post, byline: bylineFor(post, authors), identity },
+  }));
+}) satisfies GetStaticPaths;
+
+const { post, byline, identity } = Astro.props;
+---
+
+<PostLayout
+  post={post}
+  byline={byline}
+  identity={identity}
+  section={{ name: 'Blog', path: '/blog' }}
+/>