@webstir-io/webstir-frontend 0.1.40

package/src/modes/ssg/views.ts

@@ -0,0 +1,309 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { FrontendConfig } from '../../types.js';
+import { ensureDir, pathExists, readJson, writeJson } from '../../utils/fs.js';
+import { FOLDERS } from '../../core/constants.js';
+import type { WorkspaceModuleView, WorkspacePackageJson } from '../../config/workspaceManifest.js';
+
+interface ViewDefinitionLike {
+    readonly name?: string;
+    readonly path?: string;
+    readonly renderMode?: 'ssg' | 'ssr' | 'spa';
+    readonly staticPaths?: readonly string[];
+}
+
+interface ViewSpecLike {
+    readonly definition?: ViewDefinitionLike;
+    readonly load?: (context: any) => unknown | Promise<unknown>;
+}
+
+interface ModuleDefinitionLike {
+    readonly views?: readonly ViewSpecLike[];
+}
+
+interface ViewDataEntry {
+    readonly viewName: string;
+    readonly path: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    readonly data: any;
+}
+
+export async function generateSsgViewData(config: FrontendConfig): Promise<void> {
+    const workspaceRoot = config.paths.workspace;
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson<WorkspacePackageJson>(pkgPath);
+    const moduleConfig = pkg?.webstir?.moduleManifest;
+    const viewMetadata = moduleConfig?.views ?? [];
+    const workspaceMode = pkg?.webstir?.mode;
+    const isSsgWorkspace = typeof workspaceMode === 'string' && workspaceMode.toLowerCase() === 'ssg';
+
+    const moduleDefinition = await loadBackendModuleDefinition(workspaceRoot);
+    if (!moduleDefinition?.views || moduleDefinition.views.length === 0) {
+        return;
+    }
+
+    const perPageData = new Map<string, ViewDataEntry[]>();
+
+    for (const spec of moduleDefinition.views) {
+        const definition = spec.definition ?? {};
+        const viewName = definition.name ?? '';
+        const viewPathTemplate = definition.path ?? '';
+        const meta = findViewMetadata(viewMetadata, viewName, viewPathTemplate);
+        const renderMode = meta?.renderMode ?? definition.renderMode ?? (isSsgWorkspace ? 'ssg' : undefined);
+        if (renderMode !== 'ssg') {
+            continue;
+        }
+
+        const staticPaths = getEffectiveStaticPaths(meta, definition, isSsgWorkspace);
+        if (!spec.load || !Array.isArray(staticPaths) || staticPaths.length === 0) {
+            continue;
+        }
+
+        for (const rawPath of staticPaths) {
+            if (typeof rawPath !== 'string' || rawPath.length === 0) {
+                continue;
+            }
+
+            const normalizedPath = normalizePath(rawPath);
+            const params = deriveRouteParams(viewPathTemplate, normalizedPath);
+            if (!params) {
+                continue;
+            }
+
+            const ssrContext = createMinimalSsrContext(normalizedPath, params);
+
+            let data: unknown;
+            try {
+                data = await spec.load(ssrContext);
+            } catch {
+                // Best-effort only; skip paths that fail to load.
+                continue;
+            }
+
+            const pageName = normalizedPath === '/' ? FOLDERS.home : firstPathSegment(normalizedPath) ?? FOLDERS.home;
+            const entries = perPageData.get(pageName) ?? [];
+            entries.push({
+                viewName: viewName || viewPathTemplate || normalizedPath,
+                path: normalizedPath,
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                data
+            });
+            perPageData.set(pageName, entries);
+        }
+    }
+
+    if (perPageData.size === 0) {
+        return;
+    }
+
+    const pagesRoot = config.paths.dist.pages;
+
+    for (const [pageName, entries] of perPageData.entries()) {
+        const pageDir = path.join(pagesRoot, pageName);
+        if (!(await pathExists(pageDir))) {
+            continue;
+        }
+
+        const dataPath = path.join(pageDir, 'view-data.json');
+        await ensureDir(pageDir);
+        await writeJson(dataPath, entries);
+    }
+}
+
+function findViewMetadata(
+    views: readonly WorkspaceModuleView[],
+    name: string,
+    templatePath: string
+): WorkspaceModuleView | undefined {
+    return (
+        views.find((view) => (view.name && view.name === name) || (view.path && view.path === templatePath)) ??
+        views.find((view) => view.path === templatePath) ??
+        views.find((view) => view.name === name)
+    );
+}
+
+async function loadBackendModuleDefinition(workspaceRoot: string): Promise<ModuleDefinitionLike | undefined> {
+    const buildRoot = path.join(workspaceRoot, 'build', 'backend');
+    const candidates = [
+        path.join(buildRoot, 'module.js'),
+        path.join(buildRoot, 'module.mjs'),
+        path.join(buildRoot, 'module', 'index.js'),
+        path.join(buildRoot, 'module', 'index.mjs')
+    ];
+
+    for (const fullPath of candidates) {
+        if (!(await pathExists(fullPath))) {
+            continue;
+        }
+
+        try {
+            const url = `${pathToFileURL(fullPath).href}?t=${Date.now()}`;
+            const imported = (await import(url)) as Record<string, unknown>;
+            const candidate = extractModuleDefinition(imported);
+            if (candidate) {
+                return candidate;
+            }
+        } catch {
+            // Best-effort only.
+        }
+    }
+
+    return undefined;
+}
+
+function extractModuleDefinition(exports: Record<string, unknown>): ModuleDefinitionLike | undefined {
+    const keys = ['module', 'moduleDefinition', 'default', 'backendModule'];
+    for (const key of keys) {
+        if (key in exports) {
+            const value = exports[key as keyof typeof exports];
+            if (value && typeof value === 'object') {
+                return value as ModuleDefinitionLike;
+            }
+        }
+    }
+    return undefined;
+}
+
+function normalizePath(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 deriveRouteParams(template: string, actual: string): Record<string, string> | null {
+    if (!template || !actual) {
+        return {};
+    }
+
+    const templateSegments = template.split('/').filter(Boolean);
+    const actualSegments = actual.split('/').filter(Boolean);
+
+    if (templateSegments.length !== actualSegments.length) {
+        return null;
+    }
+
+    const params: Record<string, string> = {};
+
+    for (let i = 0; i < templateSegments.length; i++) {
+        const templateSegment = templateSegments[i];
+        const actualSegment = actualSegments[i];
+
+        if (templateSegment.startsWith(':')) {
+            const key = templateSegment.slice(1);
+            if (!key) {
+                return null;
+            }
+            params[key] = decodeURIComponent(actualSegment);
+        } else if (templateSegment !== actualSegment) {
+            return null;
+        }
+    }
+
+    return params;
+}
+
+function createMinimalSsrContext(pathname: string, params: Record<string, string>): unknown {
+    const url = new URL(`http://localhost${pathname}`);
+
+    const envAccessor = {
+        get(name: string): string | undefined {
+            return process.env[name];
+        },
+        require(name: string): string {
+            const value = process.env[name];
+            if (value === undefined) {
+                throw new Error(`Missing required env variable ${name} for SSG view rendering.`);
+            }
+            return value;
+        },
+        entries(): Record<string, string | undefined> {
+            return process.env as Record<string, string | undefined>;
+        }
+    };
+
+    const logger = {
+        level: 'info',
+        log(_level: string, _message: string, _metadata?: Record<string, unknown>): void {
+            // no-op for SSG
+        },
+        debug(_message: string, _metadata?: Record<string, unknown>): void {
+            // no-op for SSG
+        },
+        info(_message: string, _metadata?: Record<string, unknown>): void {
+            // no-op for SSG
+        },
+        warn(_message: string, _metadata?: Record<string, unknown>): void {
+            // no-op for SSG
+        },
+        error(_message: string, _metadata?: Record<string, unknown>): void {
+            // no-op for SSG
+        },
+        with(_bindings: Record<string, unknown>) {
+            return this;
+        }
+    };
+
+    return {
+        url,
+        params,
+        cookies: {},
+        headers: {},
+        auth: undefined,
+        session: null,
+        env: envAccessor,
+        logger,
+        now: () => new Date()
+    };
+}
+
+function getEffectiveStaticPaths(
+    meta: WorkspaceModuleView | undefined,
+    definition: ViewDefinitionLike,
+    isSsgWorkspace: boolean
+): readonly string[] {
+    const explicit = meta?.staticPaths ?? definition.staticPaths ?? [];
+    if (Array.isArray(explicit) && explicit.length > 0) {
+        return explicit;
+    }
+
+    if (!isSsgWorkspace) {
+        return [];
+    }
+
+    const candidate = meta?.path ?? definition.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;
+    }
+
+    if (trimmed.includes(':') || trimmed.includes('*')) {
+        return false;
+    }
+
+    return true;
+}

package/src/operations.ts

@@ -0,0 +1,138 @@
+import { readdir } from 'node:fs/promises';
+import type { AddPageCommandOptions, EnableFlags, FrontendCommandOptions } from './types.js';
+import { runPipeline } from './pipeline.js';
+import { createPageScaffold } from './html/pageScaffold.js';
+import { prepareWorkspaceConfig } from './config/setup.js';
+import {
+    applySsgRouting,
+    assertNoSsgRoutes,
+    ensureSsgViewMetadataForPage,
+    generateSsgViewData
+} from './modes/ssg/index.js';
+import path from 'node:path';
+import { FOLDERS } from './core/constants.js';
+import { pathExists, readJson, remove } from './utils/fs.js';
+
+export async function runBuild(options: FrontendCommandOptions): Promise<void> {
+    const config = await prepareWorkspaceConfig(options.workspaceRoot);
+    const enable = await readWorkspaceEnableFlags(options.workspaceRoot);
+
+    console.info('[webstir-frontend] Running build pipeline...');
+    await runPipeline(config, 'build', { changedFile: options.changedFile, enable });
+    console.info('[webstir-frontend] Build pipeline completed.');
+}
+
+export async function runPublish(options: FrontendCommandOptions): Promise<void> {
+    const config = await prepareWorkspaceConfig(options.workspaceRoot);
+    const enable = await readWorkspaceEnableFlags(options.workspaceRoot);
+    const publishConfig = options.publishMode === 'ssg' ? applySsgPublishLayout(config) : config;
+
+    const modeLabel = options.publishMode === 'ssg' ? 'SSG publish' : 'publish';
+    console.info(`[webstir-frontend] Running ${modeLabel} pipeline...`);
+
+    if (options.publishMode === 'ssg') {
+        await assertNoSsgRoutes(config.paths.workspace);
+    }
+
+    await runPipeline(publishConfig, 'publish', { enable });
+    if (options.publishMode === 'ssg') {
+        await generateSsgViewData(publishConfig);
+        await applySsgRouting(publishConfig);
+        await removeLegacyPagesFolder(publishConfig);
+    }
+    console.info(`[webstir-frontend] ${modeLabel} pipeline completed.`);
+}
+
+export async function runRebuild(options: FrontendCommandOptions): Promise<void> {
+    const config = await prepareWorkspaceConfig(options.workspaceRoot);
+    const enable = await readWorkspaceEnableFlags(options.workspaceRoot);
+
+    console.info('[webstir-frontend] Running rebuild pipeline...');
+    await runPipeline(config, 'build', { changedFile: options.changedFile, enable });
+    console.info('[webstir-frontend] Rebuild pipeline completed.');
+}
+
+export async function runAddPage(options: AddPageCommandOptions): Promise<void> {
+    const config = await prepareWorkspaceConfig(options.workspaceRoot);
+    console.info('[webstir-frontend] Creating page scaffold...');
+
+    const isSsgWorkspace = await detectSsgWorkspace(options.workspaceRoot);
+    const effectiveSsg = options.ssg ?? isSsgWorkspace;
+    await createPageScaffold({
+        workspaceRoot: options.workspaceRoot,
+        pageName: options.pageName,
+        mode: effectiveSsg ? 'ssg' : 'standard',
+        paths: {
+            pages: config.paths.src.pages,
+            app: config.paths.src.app
+        }
+    });
+    if (effectiveSsg) {
+        await ensureSsgViewMetadataForPage({
+            workspaceRoot: options.workspaceRoot,
+            pageName: options.pageName
+        });
+    }
+    console.info('[webstir-frontend] Page scaffold created.');
+}
+
+interface WorkspacePackageJsonMode {
+    readonly webstir?: {
+        readonly mode?: string;
+    };
+}
+
+async function detectSsgWorkspace(workspaceRoot: string): Promise<boolean> {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson<WorkspacePackageJsonMode>(pkgPath);
+    const mode = pkg?.webstir?.mode;
+    return typeof mode === 'string' && mode.toLowerCase() === 'ssg';
+}
+
+function applySsgPublishLayout(config: import('./types.js').FrontendConfig): import('./types.js').FrontendConfig {
+    const distFrontend = config.paths.dist.frontend;
+    const distPages = distFrontend;
+    const distContent = path.join(distFrontend, 'docs');
+
+    return {
+        ...config,
+        paths: {
+            ...config.paths,
+            dist: {
+                ...config.paths.dist,
+                pages: distPages,
+                content: distContent
+            }
+        }
+    };
+}
+
+interface WorkspacePackageJsonEnable {
+    readonly webstir?: {
+        readonly enable?: EnableFlags;
+    };
+}
+
+async function readWorkspaceEnableFlags(workspaceRoot: string): Promise<EnableFlags | undefined> {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson<WorkspacePackageJsonEnable>(pkgPath);
+    return pkg?.webstir?.enable;
+}
+
+async function removeLegacyPagesFolder(config: import('./types.js').FrontendConfig): Promise<void> {
+    const legacyPagesRoot = path.join(config.paths.dist.frontend, FOLDERS.pages);
+    if (legacyPagesRoot === config.paths.dist.pages) {
+        return;
+    }
+
+    if (!(await pathExists(legacyPagesRoot))) {
+        return;
+    }
+
+    const entries = await readdir(legacyPagesRoot);
+    if (entries.length > 0) {
+        return;
+    }
+
+    await remove(legacyPagesRoot);
+}

package/src/pipeline.ts

@@ -0,0 +1,88 @@
+import { performance } from 'node:perf_hooks';
+import type { EnableFlags, FrontendConfig } from './types.js';
+import { createBuilders } from './builders/index.js';
+import type { Builder, BuilderContext } from './builders/types.js';
+import { createHookContext, executeHooks, loadHooks } from './hooks.js';
+
+export interface PipelineOptions {
+    readonly changedFile?: string;
+    readonly enable?: EnableFlags;
+}
+
+export type PipelineMode = 'build' | 'publish';
+
+export async function runPipeline(config: FrontendConfig, mode: PipelineMode, options: PipelineOptions = {}): Promise<void> {
+    const context: BuilderContext = { config, changedFile: options.changedFile, enable: options.enable };
+    const builders: Builder[] = createBuilders(context);
+    const hooks = await loadHooks(config.paths.workspace, mode === 'build');
+    const pipelineContext = createHookContext(config, mode, options.changedFile);
+
+    await executeHooks('pipeline.beforeAll', hooks.pipelineBefore, pipelineContext);
+
+    let pipelineError: unknown;
+
+    try {
+        for (const builder of builders) {
+            const builderContext = createHookContext(config, mode, options.changedFile, builder.name);
+            const beforeHooks = hooks.builderBefore.get(builder.name) ?? [];
+            const afterHooks = hooks.builderAfter.get(builder.name) ?? [];
+
+            await executeHooks(`builder.${builder.name}.before`, beforeHooks, builderContext);
+
+            const start = performance.now();
+            let builderError: Error | undefined;
+            let afterHookError: Error | undefined;
+
+            try {
+                if (mode === 'build') {
+                    await builder.build(context);
+                } else {
+                    await builder.publish(context);
+                }
+            } catch (error) {
+                builderError = wrapPipelineError(builder.name, mode, error);
+            }
+
+            try {
+                await executeHooks(`builder.${builder.name}.after`, afterHooks, builderContext);
+            } catch (error) {
+                afterHookError = error as Error;
+            }
+
+            const end = performance.now();
+            const duration = end - start;
+            console.info(`[webstir-frontend] ${mode}:${builder.name} completed in ${duration.toFixed(1)}ms`);
+
+            if (builderError) {
+                throw builderError;
+            }
+
+            if (afterHookError) {
+                throw afterHookError;
+            }
+        }
+    } catch (error) {
+        pipelineError = error;
+    } finally {
+        try {
+            await executeHooks('pipeline.afterAll', hooks.pipelineAfter, pipelineContext);
+        } catch (hookError) {
+            if (!pipelineError) {
+                pipelineError = hookError;
+            }
+        }
+    }
+
+    if (pipelineError) {
+        throw pipelineError;
+    }
+}
+
+function wrapPipelineError(name: string, mode: PipelineMode, error: unknown): Error {
+    if (error instanceof Error) {
+        error.message = `[${mode}:${name}] ${error.message}`;
+        return error;
+    }
+
+    return new Error(`[${mode}:${name}] ${String(error)}`);
+}