@webstir-io/webstir-frontend 0.1.40

package/dist/html/resourceHints.js

@@ -0,0 +1,64 @@
+import { resolvePageHtmlUrl } from '../utils/pagePaths.js';
+export function injectResourceHints(document, currentPage, pagesUrlPrefix, useRootIndex) {
+    const head = document('head').first();
+    const pages = [...collectInternalPages(document, currentPage, pagesUrlPrefix)];
+    if (head.length === 0) {
+        return {
+            added: 0,
+            candidates: pages,
+            missingHead: pages.length > 0
+        };
+    }
+    if (pages.length === 0) {
+        return { added: 0, candidates: [], missingHead: false };
+    }
+    for (const page of pages) {
+        const href = resolvePageHtmlUrl(pagesUrlPrefix, page, useRootIndex);
+        head.append(`\n<link rel="prefetch" href="${href}" as="document">`);
+    }
+    return { added: pages.length, candidates: pages, missingHead: false };
+}
+function collectInternalPages(document, currentPage, pagesUrlPrefix) {
+    const pages = new Set();
+    document('a[href]').each((_index, element) => {
+        const href = document(element).attr('href');
+        const pageName = normalizePageName(href, pagesUrlPrefix);
+        if (!pageName || pageName === currentPage) {
+            return;
+        }
+        pages.add(pageName);
+    });
+    return pages;
+}
+function normalizePageName(href, pagesUrlPrefix) {
+    if (!href || href.length === 0) {
+        return null;
+    }
+    const lower = href.toLowerCase();
+    if (lower.startsWith('http://') || lower.startsWith('https://') || lower.startsWith('mailto:') || lower.startsWith('#')) {
+        return null;
+    }
+    let path = href.split('#')[0]?.split('?')[0] ?? '';
+    if (path.length === 0) {
+        return null;
+    }
+    if (path.startsWith('/')) {
+        path = path.slice(1);
+    }
+    const prefix = trimSlashes(pagesUrlPrefix);
+    if (prefix && path.startsWith(`${prefix}/`)) {
+        path = path.slice(prefix.length + 1);
+    }
+    if (path.endsWith('/')) {
+        path = path.slice(0, -1);
+    }
+    const segments = path.split('/');
+    const candidate = segments[0];
+    if (!candidate) {
+        return null;
+    }
+    return candidate;
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, '');
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './operations.js';
+export * from './config/manifest.js';
+export * from './config/schema.js';
+export * from './types.js';
+export { frontendProvider } from './provider.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './operations.js';
+export * from './config/manifest.js';
+export * from './config/schema.js';
+export * from './types.js';
+export { frontendProvider } from './provider.js';

package/dist/modes/ssg/index.d.ts

@@ -0,0 +1,4 @@
+export { applySsgRouting } from './routing.js';
+export { ensureSsgViewMetadataForPage } from './metadata.js';
+export { assertNoSsgRoutes } from './validation.js';
+export { generateSsgViewData } from './views.js';

package/dist/modes/ssg/index.js

@@ -0,0 +1,4 @@
+export { applySsgRouting } from './routing.js';
+export { ensureSsgViewMetadataForPage } from './metadata.js';
+export { assertNoSsgRoutes } from './validation.js';
+export { generateSsgViewData } from './views.js';

package/dist/modes/ssg/metadata.d.ts

@@ -0,0 +1,5 @@
+export interface SsgViewMetadataOptions {
+    readonly workspaceRoot: string;
+    readonly pageName: string;
+}
+export declare function ensureSsgViewMetadataForPage(options: SsgViewMetadataOptions): Promise<void>;

package/dist/modes/ssg/metadata.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { readJson, writeJson } from '../../utils/fs.js';
+export async function ensureSsgViewMetadataForPage(options) {
+    const pkgPath = path.join(options.workspaceRoot, 'package.json');
+    const pkg = (await readJson(pkgPath)) ?? {};
+    const workspaceMode = pkg.webstir?.mode;
+    const isSsgWorkspace = typeof workspaceMode === 'string' && workspaceMode.toLowerCase() === 'ssg';
+    if (isSsgWorkspace) {
+        return;
+    }
+    const webstir = pkg.webstir ?? {};
+    const moduleConfig = webstir.moduleManifest ?? {};
+    const existingViews = Array.isArray(moduleConfig.views) ? [...moduleConfig.views] : [];
+    const pageName = options.pageName;
+    const isHome = pageName === 'home';
+    const viewName = `${capitalize(pageName)}View`;
+    const viewPath = isHome ? '/' : `/${pageName}`;
+    const existingIndex = existingViews.findIndex((view) => view?.name === viewName || view?.path === viewPath);
+    const existing = existingIndex >= 0 ? (existingViews[existingIndex] ?? {}) : {};
+    const nextView = {
+        ...existing,
+        name: viewName,
+        path: viewPath,
+        renderMode: 'ssg',
+        staticPaths: [viewPath]
+    };
+    if (existingIndex >= 0) {
+        existingViews[existingIndex] = nextView;
+    }
+    else {
+        existingViews.push(nextView);
+    }
+    const nextPkg = {
+        ...pkg,
+        webstir: {
+            ...webstir,
+            moduleManifest: {
+                ...moduleConfig,
+                views: existingViews
+            }
+        }
+    };
+    await writeJson(pkgPath, nextPkg);
+}
+function capitalize(value) {
+    if (!value) {
+        return value;
+    }
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/dist/modes/ssg/routing.d.ts

@@ -0,0 +1,2 @@
+import type { FrontendConfig } from '../../types.js';
+export declare function applySsgRouting(config: FrontendConfig): Promise<void>;

package/dist/modes/ssg/routing.js

@@ -0,0 +1,186 @@
+import path from 'node:path';
+import { glob } from 'glob';
+import { FOLDERS, FILES } from '../../core/constants.js';
+import { copy, ensureDir, pathExists, readJson } from '../../utils/fs.js';
+import { getPageDirectories } from '../../core/pages.js';
+import { assertNoSsgRoutesInModuleConfig } from './validation.js';
+import { runSsgSeo } from './seo.js';
+export async function applySsgRouting(config) {
+    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();
+    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, distPagesRoot) {
+    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) {
+    const fromEnv = process.env.WEBSTIR_SITE_URL?.trim();
+    if (fromEnv) {
+        return fromEnv;
+    }
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson(pkgPath);
+    const webstir = pkg?.webstir;
+    if (!webstir || typeof webstir !== 'object') {
+        return undefined;
+    }
+    const candidate = webstir.siteUrl;
+    return typeof candidate === 'string' && candidate.trim() ? candidate.trim() : undefined;
+}
+async function applyStaticPathAliases(config, distRoot, distPagesRoot, pageIndexMap) {
+    if (pageIndexMap.size === 0) {
+        return;
+    }
+    const workspaceRoot = config.paths.workspace;
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson(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;
+            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) {
+    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) {
+    const [, segment] = pathname.split('/');
+    if (!segment) {
+        return undefined;
+    }
+    return segment;
+}
+function getEffectiveStaticPaths(view, isSsgWorkspace) {
+    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) {
+    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/dist/modes/ssg/seo.d.ts

@@ -0,0 +1,4 @@
+export interface SsgSeoOptions {
+    readonly siteUrl?: string;
+}
+export declare function runSsgSeo(distRoot: string, options?: SsgSeoOptions): Promise<void>;

package/dist/modes/ssg/seo.js

@@ -0,0 +1,208 @@
+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';
+export async function runSsgSeo(distRoot, options = {}) {
+    const pages = await discoverHtmlPages(distRoot);
+    await validateInternalLinks(pages, distRoot);
+    await writeSitemap(distRoot, pages, options.siteUrl);
+    await writeRobots(distRoot, options.siteUrl);
+}
+async function discoverHtmlPages(distRoot) {
+    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) {
+    if (relativeIndex === FILES.indexHtml) {
+        return '/';
+    }
+    if (relativeIndex.endsWith(`/${FILES.indexHtml}`)) {
+        return `/${relativeIndex.slice(0, -FILES.indexHtml.length)}`;
+    }
+    return '';
+}
+async function validateInternalLinks(pages, distRoot) {
+    if (pages.length === 0) {
+        return;
+    }
+    const knownPages = new Set(pages.map((page) => page.urlPath));
+    const idsByPath = await collectIdsByPath(pages);
+    const errors = [];
+    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();
+            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) {
+    const idsByPath = new Map();
+    for (const page of pages) {
+        const html = await readFile(page.filePath);
+        const doc = load(html);
+        const ids = new Set();
+        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) {
+    if (href.startsWith('//')) {
+        return true;
+    }
+    return /^[a-z][a-z0-9+.-]*:/i.test(href);
+}
+function resolveHref(basePath, href) {
+    try {
+        const base = basePath.endsWith('/') ? basePath : `${basePath}/`;
+        return new URL(href, `http://webstir.local${base}`);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizePagePath(pathname, knownPages) {
+    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, pathname) {
+    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, pages, siteUrl) {
+    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, siteUrl) {
+    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) {
+    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) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}

package/dist/modes/ssg/validation.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceModuleConfig } from '../../config/workspaceManifest.js';
+export declare function assertNoSsgRoutesInModuleConfig(moduleConfig: WorkspaceModuleConfig | undefined): void;
+export declare function assertNoSsgRoutes(workspaceRoot: string): Promise<void>;

package/dist/modes/ssg/validation.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { readJson } from '../../utils/fs.js';
+export function assertNoSsgRoutesInModuleConfig(moduleConfig) {
+    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) {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson(pkgPath);
+    const moduleConfig = pkg?.webstir?.moduleManifest;
+    assertNoSsgRoutesInModuleConfig(moduleConfig);
+}

package/dist/modes/ssg/views.d.ts

@@ -0,0 +1,2 @@
+import type { FrontendConfig } from '../../types.js';
+export declare function generateSsgViewData(config: FrontendConfig): Promise<void>;