@webstir-io/webstir-frontend 0.1.40

package/src/modes/ssg/routing.ts

@@ -0,0 +1,230 @@
+import path from 'node:path';
+import { glob } from 'glob';
+import { FOLDERS, FILES } from '../../core/constants.js';
+import type { FrontendConfig } from '../../types.js';
+import { copy, ensureDir, pathExists, readJson } from '../../utils/fs.js';
+import { getPageDirectories } from '../../core/pages.js';
+import { assertNoSsgRoutesInModuleConfig } from './validation.js';
+import type { WorkspaceModuleView, WorkspacePackageJson } from '../../config/workspaceManifest.js';
+import { runSsgSeo } from './seo.js';
+
+export async function applySsgRouting(config: FrontendConfig): Promise<void> {
+    const distRoot = config.paths.dist.frontend;
+    const distPagesRoot = config.paths.dist.pages;
+    const isRootLayout = path.resolve(distRoot) === path.resolve(distPagesRoot);
+
+    const pages = await getPageDirectories(distPagesRoot);
+    const pageIndexMap = new Map<string, string>();
+    const rootIndexPath = path.join(distRoot, FILES.indexHtml);
+
+    for (const page of pages) {
+        const sourceIndex = path.join(page.directory, FILES.indexHtml);
+        if (!(await pathExists(sourceIndex))) {
+            continue;
+        }
+
+        pageIndexMap.set(page.name, sourceIndex);
+
+        if (isRootLayout) {
+            continue;
+        }
+
+        // For each page, create a /<page>/index.html alias to its main HTML file when available.
+        const targetDir = path.join(distRoot, page.name);
+        await ensureDir(targetDir);
+        const targetIndex = path.join(targetDir, FILES.indexHtml);
+        await copy(sourceIndex, targetIndex);
+    }
+
+    if (isRootLayout) {
+        if (await pathExists(rootIndexPath)) {
+            pageIndexMap.set(FOLDERS.home, rootIndexPath);
+        }
+    } else {
+        // Ensure a root index.html that aliases the home page when present.
+        const homeIndexPath = path.join(distPagesRoot, FOLDERS.home, FILES.indexHtml);
+        if (await pathExists(homeIndexPath)) {
+            await ensureDir(path.dirname(rootIndexPath));
+            await copy(homeIndexPath, rootIndexPath);
+        }
+
+        await applyDocsContentAliases(distRoot, distPagesRoot);
+    }
+
+    await applyStaticPathAliases(config, distRoot, distPagesRoot, pageIndexMap);
+
+    const siteUrl = await resolveWorkspaceSiteUrl(config.paths.workspace);
+    await runSsgSeo(distRoot, { siteUrl });
+}
+
+async function applyDocsContentAliases(distRoot: string, distPagesRoot: string): Promise<void> {
+    if (path.resolve(distRoot) === path.resolve(distPagesRoot)) {
+        return;
+    }
+
+    const docsRoot = path.join(distPagesRoot, 'docs');
+    if (!(await pathExists(docsRoot))) {
+        return;
+    }
+
+    const indexes = await glob('docs/**/index.html', {
+        cwd: distPagesRoot,
+        nodir: true
+    });
+
+    for (const relativeIndex of indexes) {
+        const sourceIndex = path.join(distPagesRoot, relativeIndex);
+        if (!(await pathExists(sourceIndex))) {
+            continue;
+        }
+
+        const targetIndex = path.join(distRoot, relativeIndex);
+        await ensureDir(path.dirname(targetIndex));
+        await copy(sourceIndex, targetIndex);
+    }
+}
+
+async function resolveWorkspaceSiteUrl(workspaceRoot: string): Promise<string | undefined> {
+    const fromEnv = process.env.WEBSTIR_SITE_URL?.trim();
+    if (fromEnv) {
+        return fromEnv;
+    }
+
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson<Record<string, unknown>>(pkgPath);
+    const webstir = pkg?.webstir;
+    if (!webstir || typeof webstir !== 'object') {
+        return undefined;
+    }
+
+    const candidate = (webstir as Record<string, unknown>).siteUrl;
+    return typeof candidate === 'string' && candidate.trim() ? candidate.trim() : undefined;
+}
+
+async function applyStaticPathAliases(
+    config: FrontendConfig,
+    distRoot: string,
+    distPagesRoot: string,
+    pageIndexMap: Map<string, string>
+): Promise<void> {
+    if (pageIndexMap.size === 0) {
+        return;
+    }
+
+    const workspaceRoot = config.paths.workspace;
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson<WorkspacePackageJson>(pkgPath);
+    const workspaceMode = pkg?.webstir?.mode;
+    const isSsgWorkspace = typeof workspaceMode === 'string' && workspaceMode.toLowerCase() === 'ssg';
+    const moduleConfig = pkg?.webstir?.moduleManifest;
+    assertNoSsgRoutesInModuleConfig(moduleConfig);
+
+    const views = moduleConfig?.views ?? [];
+    if (views.length === 0) {
+        return;
+    }
+
+    for (const view of views) {
+        const renderMode = view.renderMode ?? (isSsgWorkspace ? 'ssg' : undefined);
+        if (renderMode !== 'ssg') {
+            continue;
+        }
+
+        const paths = getEffectiveStaticPaths(view, isSsgWorkspace);
+        for (const raw of paths) {
+            if (typeof raw !== 'string' || raw.length === 0) {
+                continue;
+            }
+
+            const normalized = normalizeStaticPath(raw);
+            let sourceIndex: string | undefined;
+
+            if (normalized === '/') {
+                sourceIndex = pageIndexMap.get(FOLDERS.home);
+            } else {
+                const relativePath = normalized.replace(/^\/+/, '');
+                const candidate = path.join(distPagesRoot, relativePath, FILES.indexHtml);
+                if (await pathExists(candidate)) {
+                    sourceIndex = candidate;
+                } else {
+                    const pageName = firstPathSegment(normalized);
+                    if (!pageName) {
+                        continue;
+                    }
+                    sourceIndex = pageIndexMap.get(pageName);
+                }
+            }
+
+            if (!sourceIndex) {
+                continue;
+            }
+
+            const targetIndex =
+                normalized === '/'
+                    ? path.join(distRoot, FILES.indexHtml)
+                    : path.join(distRoot, normalized.replace(/^\/+/, ''), FILES.indexHtml);
+
+            if (path.resolve(sourceIndex) === path.resolve(targetIndex)) {
+                continue;
+            }
+
+            await ensureDir(path.dirname(targetIndex));
+            await copy(sourceIndex, targetIndex);
+        }
+    }
+}
+
+function normalizeStaticPath(value: string): string {
+    let s = value.trim();
+    if (!s.startsWith('/')) {
+        s = `/${s}`;
+    }
+    if (s.length > 1 && s.endsWith('/')) {
+        s = s.slice(0, -1);
+    }
+    return s;
+}
+
+function firstPathSegment(pathname: string): string | undefined {
+    const [, segment] = pathname.split('/');
+    if (!segment) {
+        return undefined;
+    }
+    return segment;
+}
+
+function getEffectiveStaticPaths(view: WorkspaceModuleView, isSsgWorkspace: boolean): readonly string[] {
+    const explicitPaths = view.staticPaths ?? [];
+    if (explicitPaths.length > 0) {
+        return explicitPaths;
+    }
+
+    if (!isSsgWorkspace) {
+        return [];
+    }
+
+    const candidate = view.path ?? '';
+    if (!isDefaultStaticPathCandidate(candidate)) {
+        return [];
+    }
+
+    return [candidate];
+}
+
+function isDefaultStaticPathCandidate(template: string): boolean {
+    if (typeof template !== 'string') {
+        return false;
+    }
+
+    const trimmed = template.trim();
+    if (!trimmed.startsWith('/')) {
+        return false;
+    }
+
+    // Avoid treating parameterized or wildcard templates as a single concrete path.
+    if (trimmed.includes(':') || trimmed.includes('*')) {
+        return false;
+    }
+
+    return true;
+}

package/src/modes/ssg/seo.ts

@@ -0,0 +1,261 @@
+import path from 'node:path';
+import { glob } from 'glob';
+import { load } from 'cheerio';
+import { ensureDir, pathExists, readFile, writeFile } from '../../utils/fs.js';
+import { FILES } from '../../core/constants.js';
+
+interface HtmlPage {
+    readonly filePath: string;
+    readonly urlPath: string;
+}
+
+export interface SsgSeoOptions {
+    readonly siteUrl?: string;
+}
+
+export async function runSsgSeo(distRoot: string, options: SsgSeoOptions = {}): Promise<void> {
+    const pages = await discoverHtmlPages(distRoot);
+    await validateInternalLinks(pages, distRoot);
+    await writeSitemap(distRoot, pages, options.siteUrl);
+    await writeRobots(distRoot, options.siteUrl);
+}
+
+async function discoverHtmlPages(distRoot: string): Promise<HtmlPage[]> {
+    if (!(await pathExists(distRoot))) {
+        return [];
+    }
+
+    const files = await glob('**/index.html', { cwd: distRoot, nodir: true, ignore: ['pages/**'] });
+    const pages = files
+        .map((relative) => {
+            const normalized = relative.split(path.sep).join('/');
+            const urlPath = toUrlPath(normalized);
+            return {
+                filePath: path.join(distRoot, relative),
+                urlPath
+            };
+        })
+        .filter((page) => Boolean(page.urlPath));
+
+    pages.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+    return pages;
+}
+
+function toUrlPath(relativeIndex: string): string {
+    if (relativeIndex === FILES.indexHtml) {
+        return '/';
+    }
+
+    if (relativeIndex.endsWith(`/${FILES.indexHtml}`)) {
+        return `/${relativeIndex.slice(0, -FILES.indexHtml.length)}`;
+    }
+
+    return '';
+}
+
+async function validateInternalLinks(pages: readonly HtmlPage[], distRoot: string): Promise<void> {
+    if (pages.length === 0) {
+        return;
+    }
+
+    const knownPages = new Set<string>(pages.map((page) => page.urlPath));
+    const idsByPath = await collectIdsByPath(pages);
+    const errors: string[] = [];
+
+    for (const page of pages) {
+        const html = await readFile(page.filePath);
+        const doc = load(html);
+        const anchors = doc('a[href]').toArray();
+
+        for (const element of anchors) {
+            const rawHref = doc(element).attr('href')?.trim() ?? '';
+            if (!rawHref) {
+                continue;
+            }
+
+            if (isExternalHref(rawHref)) {
+                continue;
+            }
+
+            const resolved = resolveHref(page.urlPath, rawHref);
+            if (!resolved) {
+                continue;
+            }
+
+            const normalizedPath = normalizePagePath(resolved.pathname, knownPages);
+            if (!normalizedPath) {
+                // Still allow links to known static assets (best-effort).
+                if (await targetExistsInDist(distRoot, resolved.pathname)) {
+                    continue;
+                }
+
+                errors.push(`${page.filePath}: broken link '${rawHref}'`);
+                continue;
+            }
+
+            const hash = resolved.hash.startsWith('#') ? resolved.hash.slice(1) : resolved.hash;
+            if (!hash) {
+                continue;
+            }
+
+            const ids = idsByPath.get(normalizedPath) ?? new Set<string>();
+            if (!ids.has(hash)) {
+                errors.push(`${page.filePath}: broken anchor '${rawHref}' (missing '#${hash}' on ${normalizedPath})`);
+            }
+        }
+    }
+
+    if (errors.length === 0) {
+        return;
+    }
+
+    const preview = errors.slice(0, 16).join('\n');
+    const suffix = errors.length > 16 ? `\n… and ${errors.length - 16} more.` : '';
+    throw new Error(`Broken links found in publish output:\n${preview}${suffix}`);
+}
+
+async function collectIdsByPath(pages: readonly HtmlPage[]): Promise<Map<string, Set<string>>> {
+    const idsByPath = new Map<string, Set<string>>();
+
+    for (const page of pages) {
+        const html = await readFile(page.filePath);
+        const doc = load(html);
+        const ids = new Set<string>();
+
+        doc('[id]').each((_, element) => {
+            const raw = doc(element).attr('id');
+            const value = typeof raw === 'string' ? raw.trim() : '';
+            if (value) {
+                ids.add(value);
+            }
+        });
+
+        idsByPath.set(page.urlPath, ids);
+    }
+
+    return idsByPath;
+}
+
+function isExternalHref(href: string): boolean {
+    if (href.startsWith('//')) {
+        return true;
+    }
+    return /^[a-z][a-z0-9+.-]*:/i.test(href);
+}
+
+function resolveHref(basePath: string, href: string): URL | null {
+    try {
+        const base = basePath.endsWith('/') ? basePath : `${basePath}/`;
+        return new URL(href, `http://webstir.local${base}`);
+    } catch {
+        return null;
+    }
+}
+
+function normalizePagePath(pathname: string, knownPages: ReadonlySet<string>): string | null {
+    if (pathname === '/' || pathname === '') {
+        return '/';
+    }
+
+    if (pathname.endsWith('/index.html')) {
+        const asDir = pathname.slice(0, -'index.html'.length);
+        return knownPages.has(asDir) ? asDir : null;
+    }
+
+    if (pathname.endsWith('.html')) {
+        return knownPages.has(pathname) ? pathname : null;
+    }
+
+    if (pathname.endsWith('/')) {
+        return knownPages.has(pathname) ? pathname : null;
+    }
+
+    const withSlash = `${pathname}/`;
+    if (knownPages.has(withSlash)) {
+        return withSlash;
+    }
+
+    return knownPages.has(pathname) ? pathname : null;
+}
+
+async function targetExistsInDist(distRoot: string, pathname: string): Promise<boolean> {
+    if (!pathname.startsWith('/')) {
+        return false;
+    }
+
+    const relative = pathname.replace(/^\/+/, '');
+    if (!relative) {
+        return true;
+    }
+
+    const full = path.join(distRoot, relative);
+    if (await pathExists(full)) {
+        return true;
+    }
+
+    const asIndex = path.join(distRoot, relative, FILES.indexHtml);
+    return pathExists(asIndex);
+}
+
+async function writeSitemap(distRoot: string, pages: readonly HtmlPage[], siteUrl?: string): Promise<void> {
+    const urls = pages.map((page) => page.urlPath).filter((url) => url.startsWith('/'));
+    const unique = Array.from(new Set(urls)).sort((a, b) => a.localeCompare(b));
+
+    const baseUrl = normalizeSiteUrl(siteUrl);
+    const comment = baseUrl ? '' : '<!-- Set WEBSTIR_SITE_URL to emit absolute <loc> entries. -->\n';
+
+    const entries = unique
+        .map((pathname) => {
+            const loc = baseUrl ? new URL(pathname, baseUrl).href : pathname;
+            return `  <url><loc>${escapeXml(loc)}</loc></url>`;
+        })
+        .join('\n');
+
+    const xml = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        comment + '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+        entries,
+        '</urlset>',
+        ''
+    ].join('\n');
+
+    const outputPath = path.join(distRoot, 'sitemap.xml');
+    await ensureDir(path.dirname(outputPath));
+    await writeFile(outputPath, xml);
+}
+
+async function writeRobots(distRoot: string, siteUrl?: string): Promise<void> {
+    const baseUrl = normalizeSiteUrl(siteUrl);
+    const sitemapLine = baseUrl ? `\nSitemap: ${new URL('/sitemap.xml', baseUrl).href}` : '';
+    const content = `User-agent: *\nAllow: /${sitemapLine}\n`;
+
+    const outputPath = path.join(distRoot, FILES.robotsTxt);
+    await ensureDir(path.dirname(outputPath));
+    await writeFile(outputPath, content);
+}
+
+function normalizeSiteUrl(value: string | undefined): string | undefined {
+    const trimmed = (value ?? '').trim();
+    if (!trimmed) {
+        return undefined;
+    }
+
+    try {
+        const url = new URL(trimmed);
+        url.pathname = url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`;
+        url.hash = '';
+        url.search = '';
+        return url.toString();
+    } catch {
+        return undefined;
+    }
+}
+
+function escapeXml(value: string): string {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}

package/src/modes/ssg/validation.ts

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { readJson } from '../../utils/fs.js';
+import type { WorkspaceModuleConfig, WorkspacePackageJson } from '../../config/workspaceManifest.js';
+
+export function assertNoSsgRoutesInModuleConfig(moduleConfig: WorkspaceModuleConfig | undefined): void {
+    const routes = moduleConfig?.routes ?? [];
+    if (!Array.isArray(routes) || routes.length === 0) {
+        return;
+    }
+
+    const hasSsgRoute = routes.some((route) => {
+        if (!route || typeof route !== 'object') {
+            return false;
+        }
+
+        const renderMode = typeof route.renderMode === 'string' ? route.renderMode.toLowerCase() : undefined;
+        const hasStaticPaths = Array.isArray(route.staticPaths) && route.staticPaths.length > 0;
+        const hasSsgBlock = route.ssg !== undefined;
+
+        return renderMode === 'ssg' || hasStaticPaths || hasSsgBlock;
+    });
+
+    if (!hasSsgRoute) {
+        return;
+    }
+
+    throw new Error(
+        "SSG publish expects SSG metadata under `webstir.moduleManifest.views`, not `webstir.moduleManifest.routes`. Move `renderMode: 'ssg'`, `staticPaths`, and/or `ssg` onto the corresponding view definition."
+    );
+}
+
+export async function assertNoSsgRoutes(workspaceRoot: string): Promise<void> {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson<WorkspacePackageJson>(pkgPath);
+    const moduleConfig = pkg?.webstir?.moduleManifest;
+    assertNoSsgRoutesInModuleConfig(moduleConfig);
+}