@webstir-io/webstir-frontend 0.1.40

package/dist/modes/ssg/views.js

@@ -0,0 +1,236 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ensureDir, pathExists, readJson, writeJson } from '../../utils/fs.js';
+import { FOLDERS } from '../../core/constants.js';
+export async function generateSsgViewData(config) {
+    const workspaceRoot = config.paths.workspace;
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson(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();
+    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;
+            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, name, templatePath) {
+    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) {
+    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));
+            const candidate = extractModuleDefinition(imported);
+            if (candidate) {
+                return candidate;
+            }
+        }
+        catch {
+            // Best-effort only.
+        }
+    }
+    return undefined;
+}
+function extractModuleDefinition(exports) {
+    const keys = ['module', 'moduleDefinition', 'default', 'backendModule'];
+    for (const key of keys) {
+        if (key in exports) {
+            const value = exports[key];
+            if (value && typeof value === 'object') {
+                return value;
+            }
+        }
+    }
+    return undefined;
+}
+function normalizePath(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 deriveRouteParams(template, actual) {
+    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 = {};
+    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, params) {
+    const url = new URL(`http://localhost${pathname}`);
+    const envAccessor = {
+        get(name) {
+            return process.env[name];
+        },
+        require(name) {
+            const value = process.env[name];
+            if (value === undefined) {
+                throw new Error(`Missing required env variable ${name} for SSG view rendering.`);
+            }
+            return value;
+        },
+        entries() {
+            return process.env;
+        }
+    };
+    const logger = {
+        level: 'info',
+        log(_level, _message, _metadata) {
+            // no-op for SSG
+        },
+        debug(_message, _metadata) {
+            // no-op for SSG
+        },
+        info(_message, _metadata) {
+            // no-op for SSG
+        },
+        warn(_message, _metadata) {
+            // no-op for SSG
+        },
+        error(_message, _metadata) {
+            // no-op for SSG
+        },
+        with(_bindings) {
+            return this;
+        }
+    };
+    return {
+        url,
+        params,
+        cookies: {},
+        headers: {},
+        auth: undefined,
+        session: null,
+        env: envAccessor,
+        logger,
+        now: () => new Date()
+    };
+}
+function getEffectiveStaticPaths(meta, definition, isSsgWorkspace) {
+    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) {
+    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/dist/operations.d.ts

@@ -0,0 +1,5 @@
+import type { AddPageCommandOptions, FrontendCommandOptions } from './types.js';
+export declare function runBuild(options: FrontendCommandOptions): Promise<void>;
+export declare function runPublish(options: FrontendCommandOptions): Promise<void>;
+export declare function runRebuild(options: FrontendCommandOptions): Promise<void>;
+export declare function runAddPage(options: AddPageCommandOptions): Promise<void>;

package/dist/operations.js

@@ -0,0 +1,102 @@
+import { readdir } from 'node:fs/promises';
+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) {
+    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) {
+    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) {
+    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) {
+    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.');
+}
+async function detectSsgWorkspace(workspaceRoot) {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson(pkgPath);
+    const mode = pkg?.webstir?.mode;
+    return typeof mode === 'string' && mode.toLowerCase() === 'ssg';
+}
+function applySsgPublishLayout(config) {
+    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
+            }
+        }
+    };
+}
+async function readWorkspaceEnableFlags(workspaceRoot) {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson(pkgPath);
+    return pkg?.webstir?.enable;
+}
+async function removeLegacyPagesFolder(config) {
+    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/dist/pipeline.d.ts

@@ -0,0 +1,7 @@
+import type { EnableFlags, FrontendConfig } from './types.js';
+export interface PipelineOptions {
+    readonly changedFile?: string;
+    readonly enable?: EnableFlags;
+}
+export type PipelineMode = 'build' | 'publish';
+export declare function runPipeline(config: FrontendConfig, mode: PipelineMode, options?: PipelineOptions): Promise<void>;

package/dist/pipeline.js

@@ -0,0 +1,71 @@
+import { performance } from 'node:perf_hooks';
+import { createBuilders } from './builders/index.js';
+import { createHookContext, executeHooks, loadHooks } from './hooks.js';
+export async function runPipeline(config, mode, options = {}) {
+    const context = { config, changedFile: options.changedFile, enable: options.enable };
+    const builders = 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;
+    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;
+            let afterHookError;
+            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;
+            }
+            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, mode, error) {
+    if (error instanceof Error) {
+        error.message = `[${mode}:${name}] ${error.message}`;
+        return error;
+    }
+    return new Error(`[${mode}:${name}] ${String(error)}`);
+}

package/dist/provider.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleProvider } from '@webstir-io/module-contract';
+export declare const frontendProvider: ModuleProvider;

package/dist/provider.js

@@ -0,0 +1,176 @@
+import path from 'node:path';
+import { readdir } from 'node:fs/promises';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { glob } from 'glob';
+import { runPipeline } from './pipeline.js';
+import { prepareWorkspaceConfig } from './config/setup.js';
+import { FOLDERS } from './core/constants.js';
+import { pathExists, readJson, remove } from './utils/fs.js';
+import { applySsgRouting, assertNoSsgRoutes, generateSsgViewData } from './modes/ssg/index.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+function resolveWorkspacePaths(workspaceRoot) {
+    return {
+        sourceRoot: path.join(workspaceRoot, 'src', 'frontend'),
+        buildRoot: path.join(workspaceRoot, 'build', 'frontend'),
+        testsRoot: path.join(workspaceRoot, 'src', 'frontend', 'tests')
+    };
+}
+async function buildModule(options) {
+    const config = await prepareWorkspaceConfig(options.workspaceRoot);
+    const mode = normalizeMode(options.env?.WEBSTIR_MODULE_MODE);
+    const workspaceMode = await readWorkspaceMode(options.workspaceRoot);
+    const frontendMode = normalizeFrontendMode(options.env?.WEBSTIR_FRONTEND_MODE);
+    const shouldRunSsgPublish = mode === 'publish' && (frontendMode === 'ssg' || (frontendMode === undefined && workspaceMode.mode === 'ssg'));
+    const publishConfig = shouldRunSsgPublish ? applySsgPublishLayout(config) : config;
+    if (shouldRunSsgPublish) {
+        await assertNoSsgRoutes(config.paths.workspace);
+    }
+    await runPipeline(publishConfig, mode, { changedFile: undefined, enable: workspaceMode.enable });
+    if (shouldRunSsgPublish) {
+        await generateSsgViewData(publishConfig);
+        await applySsgRouting(publishConfig);
+        await removeLegacyPagesFolder(publishConfig);
+    }
+    const artifacts = await collectArtifacts(config);
+    const manifest = createManifest(config, artifacts, workspaceMode.mode, workspaceMode.isSsg);
+    return {
+        artifacts,
+        manifest
+    };
+}
+function applySsgPublishLayout(config) {
+    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
+            }
+        }
+    };
+}
+async function removeLegacyPagesFolder(config) {
+    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);
+}
+function normalizeMode(rawMode) {
+    if (typeof rawMode !== 'string') {
+        return 'build';
+    }
+    return rawMode.toLowerCase() === 'publish' ? 'publish' : 'build';
+}
+async function getScaffoldAssets() {
+    return [];
+}
+async function collectArtifacts(config) {
+    const buildRoot = config.paths.build.frontend;
+    const matches = await glob('**/*', {
+        cwd: buildRoot,
+        nodir: true,
+        dot: false
+    });
+    return matches.map((relative) => {
+        const absolutePath = path.join(buildRoot, relative);
+        const ext = path.extname(relative).toLowerCase();
+        const artifactType = ext === '.js' || ext === '.mjs' ? 'bundle' : 'asset';
+        return {
+            path: absolutePath,
+            type: artifactType
+        };
+    });
+}
+function createManifest(config, assets, workspaceMode, isSsgWorkspace) {
+    const entryPoints = [];
+    const staticAssets = [];
+    const diagnostics = [];
+    const normalizedMode = workspaceMode?.toLowerCase();
+    const isSsg = isSsgWorkspace || normalizedMode === 'ssg';
+    for (const asset of assets) {
+        const relativePath = path.relative(config.paths.build.frontend, asset.path);
+        const ext = path.extname(relativePath).toLowerCase();
+        if (ext === '.js' || ext === '.mjs') {
+            entryPoints.push(relativePath);
+        }
+        else if (ext) {
+            staticAssets.push(relativePath);
+        }
+    }
+    if (entryPoints.length === 0) {
+        const fallback = path.join(config.paths.build.app, 'index.js');
+        if (fs.existsSync(fallback)) {
+            entryPoints.push(path.relative(config.paths.build.frontend, fallback));
+        }
+        else if (!isSsg) {
+            diagnostics.push({
+                severity: 'warn',
+                message: 'No JavaScript entry points found under build/frontend.'
+            });
+        }
+    }
+    return {
+        entryPoints,
+        staticAssets,
+        diagnostics
+    };
+}
+async function readWorkspaceMode(workspaceRoot) {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson(pkgPath);
+    const mode = pkg?.webstir?.mode;
+    const normalizedMode = typeof mode === 'string' ? mode.toLowerCase() : undefined;
+    const views = pkg?.webstir?.moduleManifest?.views;
+    const hasSsgView = Array.isArray(views) && views.some(view => view.renderMode?.toLowerCase() === 'ssg');
+    return {
+        mode,
+        isSsg: normalizedMode === 'ssg' || hasSsgView,
+        enable: pkg?.webstir?.enable
+    };
+}
+function normalizeFrontendMode(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === 'ssg'
+        ? 'ssg'
+        : normalized === 'bundle'
+            ? 'bundle'
+            : undefined;
+}
+export const frontendProvider = {
+    metadata: {
+        id: pkg.name ?? '@webstir-io/webstir-frontend',
+        kind: 'frontend',
+        version: pkg.version ?? '0.0.0',
+        compatibility: {
+            minCliVersion: '0.1.0',
+            nodeRange: pkg.engines?.node ?? '>=20.18.1'
+        }
+    },
+    resolveWorkspace(options) {
+        return resolveWorkspacePaths(options.workspaceRoot);
+    },
+    async build(options) {
+        return await buildModule(options);
+    },
+    async getScaffoldAssets() {
+        return await getScaffoldAssets();
+    }
+};

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export type FrontendPublishMode = 'bundle' | 'ssg';
+export interface FrontendCommandOptions {
+    readonly workspaceRoot: string;
+    readonly changedFile?: string;
+    readonly watch?: boolean;
+    readonly publishMode?: FrontendPublishMode;
+}
+export interface FrontendConfig {
+    readonly version: 1;
+    readonly paths: FrontendPathConfig;
+    readonly features: FrontendFeatureFlags;
+}
+export interface EnableFlags {
+    readonly spa?: boolean;
+    readonly clientNav?: boolean;
+    readonly backend?: boolean;
+    readonly search?: boolean;
+    readonly contentNav?: boolean;
+}
+export interface FrontendPathConfig {
+    readonly workspace: string;
+    readonly src: {
+        readonly root: string;
+        readonly frontend: string;
+        readonly app: string;
+        readonly pages: string;
+        readonly content: string;
+        readonly images: string;
+        readonly fonts: string;
+        readonly media: string;
+    };
+    readonly build: {
+        readonly root: string;
+        readonly frontend: string;
+        readonly app: string;
+        readonly pages: string;
+        readonly content: string;
+        readonly images: string;
+        readonly fonts: string;
+        readonly media: string;
+    };
+    readonly dist: {
+        readonly root: string;
+        readonly frontend: string;
+        readonly app: string;
+        readonly pages: string;
+        readonly content: string;
+        readonly images: string;
+        readonly fonts: string;
+        readonly media: string;
+    };
+}
+export interface FrontendFeatureFlags {
+    readonly htmlSecurity: boolean;
+    readonly imageOptimization: boolean;
+    readonly precompression: boolean;
+}
+export interface AddPageCommandOptions extends FrontendCommandOptions {
+    readonly pageName: string;
+    readonly ssg?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/changedFile.d.ts

@@ -0,0 +1,8 @@
+import type { BuilderContext } from '../builders/types.js';
+interface Rule {
+    readonly directory: string;
+    readonly extensions?: readonly string[];
+}
+export declare function shouldProcess(context: BuilderContext, rules: readonly Rule[]): boolean;
+export declare function isPathInside(target: string, directory: string): boolean;
+export {};