create-we8 0.1.0

package/template/test/data-layer.test.ts

@@ -0,0 +1,312 @@
+import { describe, expect, it } from 'vitest';
+import { answerFor, selectBackend, selectRuntime } from '../src/lib/data.js';
+import { createFixtureBackend } from '../src/lib/fixture-backend.js';
+import { createWe8Backend } from '../src/lib/we8-backend.js';
+import type { Post, SiteBackend } from '../src/lib/types.js';
+
+const CONFIG = { key: 'pk_test', apiUrl: 'https://cms.example.com/api' };
+
+/**
+ * A stand-in for a live we8 API: enough of the `/v1` dialect for the backend
+ * to build its content graph, and nothing more.
+ */
+function fakeApi() {
+  const posts = [
+    {
+      slug: 'first-post',
+      type: 'blog',
+      title: 'How do I read an hour meter?',
+      excerpt: 'Once a week, on paper, next to the machine.',
+      content: '# Body\n\n## Why weekly?\n\nBecause a month is too coarse.\n',
+      coverImageUrl: null,
+      category: 'Practice',
+      tags: ['metering'],
+      authorIds: ['aut_1'],
+      wordCount: 440,
+      cta: null,
+      publishedAt: '2026-05-01T00:00:00.000Z',
+    },
+    {
+      slug: 'a-toolkit',
+      type: 'whitepaper',
+      title: 'The runtime log',
+      excerpt: 'A printable twelve month log.',
+      content: 'Body.',
+      coverImageUrl: null,
+      category: 'Toolkit',
+      tags: [],
+      authorIds: [],
+      wordCount: null,
+      cta: {
+        style: 'gated-download',
+        buttonLabel: 'Send it',
+        formKey: 'contact',
+        assetUrl: 'https://cms.example.com/log.pdf',
+      },
+      publishedAt: '2026-06-01T00:00:00.000Z',
+      // The flat AEO fields as the CMS ships them.
+      answerSummary: 'A weekly record of hour meters.',
+      questionHeading: 'What is a runtime log?',
+    },
+  ];
+
+  const author = {
+    id: 'aut_1',
+    slug: 'jane-okonjo',
+    name: 'Jane Okonjo',
+    type: 'team',
+    roleTitle: 'Founder',
+    links: [{ label: 'Email', url: 'mailto:jane@example.com' }],
+    createdAt: '2026-01-01',
+    updatedAt: '2026-01-01',
+  };
+
+  const site = {
+    name: 'Fake Co',
+    siteUrl: 'https://fake.example/',
+    seo: { defaultTitle: 'Fake Co', discourageSearchEngines: false },
+    publisher: { name: 'Fake Co' },
+    postsPathPrefix: '/insights',
+    contentPaths: { news: '/newsroom' },
+    gaMeasurementId: null,
+    brand: {},
+  };
+
+  const calls: string[] = [];
+  const fn: typeof fetch = (input) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    calls.push(url);
+    const path = new URL(url).pathname;
+    const body = ((): unknown => {
+      if (path === '/api/v1/site') return { ok: true, site };
+      if (path === '/api/v1/posts') {
+        const page = Number(new URL(url).searchParams.get('page') ?? '1');
+        return {
+          ok: true,
+          items: page === 1 ? posts : [],
+          page,
+          pageSize: 50,
+          total: posts.length,
+        };
+      }
+      const detail = posts.find((post) => path === `/api/v1/posts/${post.slug}`);
+      if (detail) {
+        return {
+          ok: true,
+          post: detail,
+          authors: detail.authorIds.length ? [author] : [],
+          jsonld: {},
+        };
+      }
+      if (path.startsWith('/api/v1/documents/')) {
+        return { ok: true, document: { kind: 'llms-txt', content: '# Fake Co', updatedAt: null } };
+      }
+      return { ok: false, error: 'no route', code: 'not_found' };
+    })();
+    return Promise.resolve(
+      new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+  };
+  return { fn, calls };
+}
+
+/**
+ * The point of the contract: run the SAME assertions against both
+ * implementations. Anything that passes here is safe for a page to rely on
+ * whichever backend a build selects.
+ */
+const backends: [string, () => SiteBackend][] = [
+  ['fixtures', () => createFixtureBackend()],
+  ['we8', () => createWe8Backend(CONFIG, fakeApi().fn)],
+];
+
+describe.each(backends)('SiteBackend contract: %s', (_name, make) => {
+  it('reports an identity with a trailing-slash-free site URL and every content path', async () => {
+    const identity = await make().identity();
+    expect(identity.name.length).toBeGreaterThan(0);
+    expect(identity.siteUrl).not.toMatch(/\/$/);
+    expect(identity.siteUrl).toMatch(/^https?:\/\//);
+    expect(typeof identity.seo.noindex).toBe('boolean');
+    expect(Object.keys(identity.contentPaths)).toHaveLength(6);
+  });
+
+  it('lists posts newest first', async () => {
+    const posts = await make().listAllPosts();
+    expect(posts.length).toBeGreaterThan(0);
+    const dates = posts.map((post) => post.publishedAt);
+    expect([...dates].sort().reverse()).toEqual(dates);
+  });
+
+  it('returns fully-formed posts: nulls, never undefined', async () => {
+    const posts = await make().listAllPosts();
+    for (const post of posts) {
+      expect(post.excerpt === null || typeof post.excerpt === 'string').toBe(true);
+      expect(post.coverImageUrl === null || typeof post.coverImageUrl === 'string').toBe(true);
+      expect(post.category === null || typeof post.category === 'string').toBe(true);
+      expect(Array.isArray(post.tags)).toBe(true);
+      expect(Array.isArray(post.authorSlugs)).toBe(true);
+      expect(post.cta === null || typeof post.cta.buttonLabel === 'string').toBe(true);
+      expect(post.readingMinutes === null || post.readingMinutes > 0).toBe(true);
+    }
+  });
+
+  it('pages and filters', async () => {
+    const backend = make();
+    const all = await backend.listAllPosts();
+    const first = await backend.listPosts({ page: 1, pageSize: 1 });
+    expect(first.items).toHaveLength(1);
+    expect(first.total).toBe(all.length);
+
+    const type = all[0]?.type;
+    const filtered = await backend.listPosts({ ...(type ? { type } : {}), pageSize: 50 });
+    expect(filtered.items.every((post) => post.type === type)).toBe(true);
+  });
+
+  it('resolves a post by slug and returns null for an unknown one', async () => {
+    const backend = make();
+    const all = await backend.listAllPosts();
+    const slug = all[0]?.slug ?? '';
+    expect((await backend.getPost(slug))?.slug).toBe(slug);
+    expect(await backend.getPost('no-such-post')).toBeNull();
+  });
+
+  it('resolves authors by the slugs its posts reference', async () => {
+    const backend = make();
+    const posts = await backend.listAllPosts();
+    const authors = await backend.listAuthors();
+    const known = new Set(authors.map((author) => author.slug));
+    for (const post of posts) {
+      for (const slug of post.authorSlugs) expect(known.has(slug)).toBe(true);
+    }
+    const first = authors[0];
+    if (first) expect((await backend.getAuthor(first.slug))?.name).toBe(first.name);
+    expect(await backend.getAuthor('nobody')).toBeNull();
+  });
+
+  it('serves a document body as a string, empty rather than throwing when absent', async () => {
+    expect(typeof (await make().getDocument('llms-txt'))).toBe('string');
+    expect(typeof (await make().getDocument('design-md'))).toBe('string');
+  });
+
+  it('merges no duplicate sitemap URLs for content it already renders', async () => {
+    const backend = make();
+    await backend.listAllPosts();
+    expect(await backend.extraSitemapUrls('https://site.example')).toEqual([]);
+  });
+});
+
+describe('the we8 backend and the /v1 dialect', () => {
+  it('resolves the byline through the detail route, not through author ids', async () => {
+    const backend = createWe8Backend(CONFIG, fakeApi().fn);
+    const post = await backend.getPost('first-post');
+    expect(post?.authorSlugs).toEqual(['jane-okonjo']);
+    const author = await backend.getAuthor('jane-okonjo');
+    expect(author?.roleTitle).toBe('Founder');
+    expect(author?.bio).toBeNull();
+  });
+
+  it('picks up answer fields the moment the API carries them, and tolerates their absence', async () => {
+    const backend = createWe8Backend(CONFIG, fakeApi().fn);
+    expect(await backend.getPost('a-toolkit').then((post) => post?.answer)).toEqual({
+      question: 'What is a runtime log?',
+      summary: 'A weekly record of hour meters.',
+      source: 'authored',
+    });
+    // The post without the fields is not an error; it just has no block.
+    expect(await backend.getPost('first-post').then((post) => post?.answer)).toBeNull();
+  });
+
+  it('fills every content path, falling back to the universal prefix', async () => {
+    const identity = await createWe8Backend(CONFIG, fakeApi().fn).identity();
+    expect(identity.contentPaths.news).toBe('/newsroom');
+    expect(identity.contentPaths.blog).toBe('/insights');
+  });
+
+  it('loads the content graph once, however many times pages ask', async () => {
+    const api = fakeApi();
+    const backend = createWe8Backend(CONFIG, api.fn);
+    await backend.listAllPosts();
+    await backend.listAuthors();
+    await backend.getPost('first-post');
+    const listCalls = api.calls.filter((url) => url.includes('/v1/posts?')).length;
+    expect(listCalls).toBe(1);
+  });
+
+  it('converts a CTA into the site vocabulary', async () => {
+    const post = await createWe8Backend(CONFIG, fakeApi().fn).getPost('a-toolkit');
+    expect(post?.cta).toEqual({
+      style: 'gated-download',
+      heading: null,
+      buttonLabel: 'Send it',
+      url: null,
+      formKey: 'contact',
+      assetUrl: 'https://cms.example.com/log.pdf',
+    });
+  });
+});
+
+describe('backend selection', () => {
+  const live = { WE8_API_URL: 'https://cms.example.com/api', WE8_PUBLISHABLE_KEY: 'pk_x' };
+
+  it('uses we8 when both variables are set', () => {
+    expect(selectBackend(live).name).toBe('we8');
+    expect(selectRuntime(live)).toEqual({
+      enabled: true,
+      key: 'pk_x',
+      apiUrl: 'https://cms.example.com/api',
+    });
+  });
+
+  it('falls back to fixtures rather than failing when configuration is incomplete', () => {
+    expect(selectBackend({}).name).toBe('fixtures');
+    expect(selectBackend({ WE8_API_URL: live.WE8_API_URL }).name).toBe('fixtures');
+    expect(selectBackend({ WE8_PUBLISHABLE_KEY: 'pk_x' }).name).toBe('fixtures');
+    expect(selectRuntime({}).enabled).toBe(false);
+  });
+
+  it('honors an explicit fixtures flag even with a live API configured', () => {
+    const forced = { ...live, WE8_DATA_SOURCE: 'fixtures' };
+    expect(selectBackend(forced).name).toBe('fixtures');
+    // And the browser half goes dark with it: no key is embedded in a build
+    // that is deliberately not talking to the backend.
+    expect(selectRuntime(forced)).toEqual({ enabled: false, key: null, apiUrl: null });
+  });
+});
+
+describe('answerFor', () => {
+  const base: Post = {
+    slug: 's',
+    type: 'blog',
+    title: 'How do I do the thing?',
+    excerpt: 'Like this.',
+    content: '',
+    coverImageUrl: null,
+    category: null,
+    tags: [],
+    authorSlugs: [],
+    publishedAt: '2026-01-01T00:00:00.000Z',
+    answer: null,
+    cta: null,
+    readingMinutes: null,
+  };
+
+  it('prefers an authored block', () => {
+    const authored = { question: 'Q', summary: 'A', source: 'authored' as const };
+    expect(answerFor({ ...base, answer: authored })).toBe(authored);
+  });
+
+  it('derives one from the title and excerpt, marked as derived', () => {
+    expect(answerFor(base)).toEqual({
+      question: 'How do I do the thing?',
+      summary: 'Like this.',
+      source: 'derived',
+    });
+  });
+
+  it('returns null when there is nothing honest to say', () => {
+    expect(answerFor({ ...base, excerpt: null })).toBeNull();
+  });
+});

package/template/test/seo.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest';
+import {
+  articleJsonLd,
+  faqJsonLd,
+  resolveSeo,
+  robotsTxt,
+  sitemapXml,
+} from '../src/lib/seo.js';
+import { outline, renderBody, slugifyHeading } from '../src/lib/markdown.js';
+import type { Post, SiteIdentity } from '../src/lib/types.js';
+
+function identity(overrides: Partial<SiteIdentity['seo']> = {}): SiteIdentity {
+  return {
+    name: 'Northgate Tools',
+    siteUrl: 'https://northgatetools.example',
+    seo: {
+      defaultTitle: null,
+      titleTemplate: null,
+      metaDescription: null,
+      ogImageUrl: null,
+      twitterHandle: null,
+      noindex: false,
+      ...overrides,
+    },
+    publisher: { name: 'Northgate Tools', logoUrl: null },
+    contentPaths: {
+      blog: '/blog',
+      article: '/blog',
+      news: '/blog',
+      research: '/resources',
+      whitepaper: '/resources',
+      'case-study': '/resources',
+    },
+  };
+}
+
+describe('resolveSeo (code-first: the page wins, the site fills)', () => {
+  it('applies the title template to a page title', () => {
+    expect(resolveSeo({ title: 'Blog' }, identity({ titleTemplate: '%s | Northgate' })).title).toBe(
+      'Blog | Northgate',
+    );
+  });
+
+  it('falls back to defaultTitle WITHOUT the template, then to the site name', () => {
+    expect(
+      resolveSeo({}, identity({ defaultTitle: 'Northgate: tools', titleTemplate: '%s | X' })).title,
+    ).toBe('Northgate: tools');
+    expect(resolveSeo({}, identity()).title).toBe('Northgate Tools');
+  });
+
+  it('lets a page description beat the site fallback', () => {
+    const resolved = resolveSeo(
+      { description: 'Page copy.' },
+      identity({ metaDescription: 'Site copy.' }),
+    );
+    expect(resolved.description).toBe('Page copy.');
+    expect(resolved.ogDescription).toBe('Page copy.');
+  });
+
+  it('builds an absolute canonical from the page path only', () => {
+    expect(resolveSeo({ path: '/blog' }, identity()).canonical).toBe(
+      'https://northgatetools.example/blog',
+    );
+    expect(resolveSeo({}, identity()).canonical).toBeNull();
+  });
+
+  it('carries the site noindex flag, and lets a page force it', () => {
+    expect(resolveSeo({}, identity()).noindex).toBe(false);
+    expect(resolveSeo({}, identity({ noindex: true })).noindex).toBe(true);
+    expect(resolveSeo({ noindex: true }, identity()).noindex).toBe(true);
+  });
+});
+
+describe('robotsTxt', () => {
+  it('disallows everything when the site asks to be left alone', () => {
+    expect(robotsTxt(identity({ noindex: true }))).toBe('User-agent: *\nDisallow: /\n');
+  });
+
+  it('advertises the sitemap and llms.txt when indexable', () => {
+    const txt = robotsTxt(identity());
+    expect(txt).toContain('Sitemap: https://northgatetools.example/sitemap.xml');
+    expect(txt).toContain('llms.txt');
+  });
+});
+
+describe('sitemapXml', () => {
+  it('escapes the ampersands a query string brings', () => {
+    const xml = sitemapXml(['https://x.example/a?b=1&c=2']);
+    expect(xml).toContain('<loc>https://x.example/a?b=1&amp;c=2</loc>');
+    expect(xml).not.toContain('&c=2');
+  });
+});
+
+const post: Post = {
+  slug: 'p',
+  type: 'blog',
+  title: 'How do I read an hour meter?',
+  excerpt: 'Weekly, on paper.',
+  content: '',
+  coverImageUrl: null,
+  category: null,
+  tags: ['metering'],
+  authorSlugs: ['jane'],
+  publishedAt: '2026-05-01T00:00:00.000Z',
+  answer: null,
+  cta: null,
+  readingMinutes: 3,
+};
+
+describe('faqJsonLd', () => {
+  it('publishes authored answers as an FAQPage', () => {
+    const json = faqJsonLd([{ question: 'Q?', summary: 'A.', source: 'authored' }]);
+    expect(json?.['@type']).toBe('FAQPage');
+    expect(json?.['mainEntity']).toEqual([
+      { '@type': 'Question', name: 'Q?', acceptedAnswer: { '@type': 'Answer', text: 'A.' } },
+    ]);
+  });
+
+  it('HONESTY: never publishes a derived block, and emits nothing at all when none qualify', () => {
+    expect(faqJsonLd([{ question: 'Q?', summary: 'A.', source: 'derived' }])).toBeNull();
+    expect(faqJsonLd([null])).toBeNull();
+    const mixed = faqJsonLd([
+      { question: 'Q1', summary: 'A1', source: 'derived' },
+      { question: 'Q2', summary: 'A2', source: 'authored' },
+    ]);
+    expect(mixed?.['mainEntity']).toHaveLength(1);
+  });
+});
+
+describe('articleJsonLd', () => {
+  it('maps the content type to a schema.org type and links the byline to its author page', () => {
+    const json = articleJsonLd(
+      post,
+      'https://northgatetools.example/blog/p',
+      [{ slug: 'jane', name: 'Jane', roleTitle: null, bio: null, avatarUrl: null, links: [] }],
+      identity(),
+    );
+    expect(json['@type']).toBe('BlogPosting');
+    expect(json['author']).toEqual([
+      {
+        '@type': 'Person',
+        name: 'Jane',
+        url: 'https://northgatetools.example/authors/jane',
+      },
+    ]);
+    expect(articleJsonLd({ ...post, type: 'news' }, 'u', [], identity())['@type']).toBe(
+      'NewsArticle',
+    );
+    expect(articleJsonLd({ ...post, type: 'whitepaper' }, 'u', [], identity())['@type']).toBe(
+      'Article',
+    );
+  });
+});
+
+describe('markdown outline', () => {
+  const body = '# Title\n\n## Why weekly?\n\ntext\n\n### A detail\n\n## What then?\n\ntext\n';
+
+  it('collects h2 and h3 headings, and never the h1', () => {
+    expect(outline(body)).toEqual([
+      { depth: 2, text: 'Why weekly?', id: 'why-weekly' },
+      { depth: 3, text: 'A detail', id: 'a-detail' },
+      { depth: 2, text: 'What then?', id: 'what-then' },
+    ]);
+  });
+
+  it('slugifies punctuation out of an anchor', () => {
+    expect(slugifyHeading('How often, really?')).toBe('how-often-really');
+  });
+
+  it('anchors every heading in the rendered HTML, in order', () => {
+    const { html, headings } = renderBody(body);
+    expect(headings).toHaveLength(3);
+    expect(html).toContain('<h2 id="why-weekly">Why weekly?</h2>');
+    expect(html).toContain('<h3 id="a-detail">A detail</h3>');
+    expect(html).toContain('<h2 id="what-then">What then?</h2>');
+  });
+});

package/template/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "customConditions": ["@we8/source"],
+    "strictNullChecks": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/template/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+
+// Resolve the workspace packages to their TypeScript source, mirroring the
+// tsconfig `customConditions: ["@we8/source"]`, so the data-layer tests run
+// without a prior build of the sibling packages.
+const root = new URL('../../packages/', import.meta.url).pathname;
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+  },
+  resolve: {
+    alias: {
+      '@we8/astro': `${root}astro/src/index.ts`,
+      '@we8/client': `${root}client/src/index.ts`,
+    },
+  },
+});