@webstir-io/webstir-frontend 0.1.40

package/src/provider.ts

@@ -0,0 +1,249 @@
+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 type {
+    ModuleAsset,
+    ModuleArtifact,
+    ModuleBuildOptions,
+    ModuleBuildResult,
+    ModuleDiagnostic,
+    ModuleProvider,
+    ResolvedModuleWorkspace
+} from '@webstir-io/module-contract';
+
+import { runPipeline } from './pipeline.js';
+import type { PipelineMode } from './pipeline.js';
+import { prepareWorkspaceConfig } from './config/setup.js';
+import type { FrontendConfig } from './types.js';
+import { FOLDERS } from './core/constants.js';
+import { pathExists, readJson, remove } from './utils/fs.js';
+import { applySsgRouting, assertNoSsgRoutes, generateSsgViewData } from './modes/ssg/index.js';
+
+interface PackageJson {
+    readonly name: string;
+    readonly version: string;
+    readonly engines?: {
+        readonly node?: string;
+    };
+}
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json') as PackageJson;
+
+function resolveWorkspacePaths(workspaceRoot: string): ResolvedModuleWorkspace {
+    return {
+        sourceRoot: path.join(workspaceRoot, 'src', 'frontend'),
+        buildRoot: path.join(workspaceRoot, 'build', 'frontend'),
+        testsRoot: path.join(workspaceRoot, 'src', 'frontend', 'tests')
+    };
+}
+
+async function buildModule(options: ModuleBuildOptions): Promise<ModuleBuildResult> {
+    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: FrontendConfig): 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
+            }
+        }
+    };
+}
+
+async function removeLegacyPagesFolder(config: 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);
+}
+
+function normalizeMode(rawMode: unknown): PipelineMode {
+    if (typeof rawMode !== 'string') {
+        return 'build';
+    }
+
+    return rawMode.toLowerCase() === 'publish' ? 'publish' : 'build';
+}
+
+async function getScaffoldAssets(): Promise<readonly ModuleAsset[]> {
+    return [];
+}
+
+async function collectArtifacts(config: FrontendConfig): Promise<ModuleArtifact[]> {
+    const buildRoot = config.paths.build.frontend;
+    const matches = await glob('**/*', {
+        cwd: buildRoot,
+        nodir: true,
+        dot: false
+    });
+
+    return matches.map<ModuleArtifact>((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
+        };
+    });
+}
+
+interface WorkspaceEnableFlags {
+    readonly spa?: boolean;
+    readonly clientNav?: boolean;
+    readonly backend?: boolean;
+    readonly search?: boolean;
+}
+
+interface WorkspacePackageJson {
+    readonly webstir?: {
+        readonly mode?: string;
+        readonly enable?: WorkspaceEnableFlags;
+        readonly moduleManifest?: {
+            readonly views?: ReadonlyArray<{
+                readonly renderMode?: string;
+            }>;
+        };
+    };
+}
+
+function createManifest(
+    config: FrontendConfig,
+    assets: readonly ModuleArtifact[],
+    workspaceMode?: string,
+    isSsgWorkspace?: boolean
+) {
+    const entryPoints: string[] = [];
+    const staticAssets: string[] = [];
+    const diagnostics: ModuleDiagnostic[] = [];
+
+    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: string): Promise<{ mode?: string; isSsg: boolean; enable?: WorkspaceEnableFlags }> {
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    const pkg = await readJson<WorkspacePackageJson>(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: unknown): 'bundle' | 'ssg' | undefined {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+
+    const normalized = value.trim().toLowerCase();
+    return normalized === 'ssg'
+        ? 'ssg'
+        : normalized === 'bundle'
+            ? 'bundle'
+            : undefined;
+}
+
+export const frontendProvider: ModuleProvider = {
+    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/src/types.ts

@@ -0,0 +1,67 @@
+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/src/utils/changedFile.ts

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import type { BuilderContext } from '../builders/types.js';
+
+interface Rule {
+    readonly directory: string;
+    readonly extensions?: readonly string[];
+}
+
+export function shouldProcess(context: BuilderContext, rules: readonly Rule[]): boolean {
+    const changed = context.changedFile;
+    if (!changed) {
+        return true;
+    }
+
+    const normalizedChanged = path.resolve(changed);
+
+    for (const rule of rules) {
+        const normalizedDir = path.resolve(rule.directory);
+        if (!isPathInside(normalizedChanged, normalizedDir)) {
+            continue;
+        }
+
+        if (!rule.extensions || rule.extensions.length === 0) {
+            return true;
+        }
+
+        const extension = path.extname(normalizedChanged).toLowerCase();
+        if (rule.extensions.includes(extension)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+export function isPathInside(target: string, directory: string): boolean {
+    const relative = path.relative(directory, target);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}

package/src/utils/fs.ts

@@ -0,0 +1,48 @@
+import fs from 'fs-extra';
+
+export async function ensureDir(path: string): Promise<void> {
+    await fs.ensureDir(path);
+}
+
+export async function emptyDir(path: string): Promise<void> {
+    await fs.emptyDir(path);
+}
+
+export async function remove(path: string): Promise<void> {
+    await fs.remove(path);
+}
+
+export async function copy(source: string, destination: string): Promise<void> {
+    await fs.copy(source, destination, { overwrite: true, errorOnExist: false });
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+    return fs.pathExists(path);
+}
+
+export async function stat(path: string): Promise<fs.Stats> {
+    return fs.stat(path);
+}
+
+export async function readJson<T>(path: string): Promise<T | null> {
+    try {
+        return await fs.readJson(path);
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+
+export async function writeJson(path: string, data: unknown): Promise<void> {
+    await fs.writeJson(path, data, { spaces: 2 });
+}
+
+export async function readFile(path: string): Promise<string> {
+    return fs.readFile(path, 'utf8');
+}
+
+export async function writeFile(path: string, contents: string): Promise<void> {
+    await fs.outputFile(path, contents, 'utf8');
+}

package/src/utils/hash.ts

@@ -0,0 +1,6 @@
+import { createHash } from 'node:crypto';
+
+export function hashContent(content: string, length = 8): string {
+    const hash = createHash('sha256').update(content).digest('hex');
+    return hash.slice(0, length);
+}

package/src/utils/pagePaths.ts

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import { FOLDERS, FILES } from '../core/constants.js';
+
+export function resolvePagesUrlPrefix(frontendRoot: string, pagesRoot: string): string {
+    const relative = path.relative(frontendRoot, pagesRoot).replace(/\\/g, '/');
+    if (!relative || relative === '.' || relative.startsWith('..')) {
+        return '';
+    }
+    return `/${trimSlashes(relative)}`;
+}
+
+export function isRootPagesLayout(frontendRoot: string, pagesRoot: string): boolean {
+    return resolvePagesUrlPrefix(frontendRoot, pagesRoot) === '';
+}
+
+export function resolvePageAssetUrl(pagesUrlPrefix: string, pageName: string, fileName: string): string {
+    return joinUrl(pagesUrlPrefix, pageName, fileName);
+}
+
+export function resolvePageHtmlUrl(pagesUrlPrefix: string, pageName: string, useRootIndex: boolean): string {
+    if (useRootIndex && pageName === FOLDERS.home) {
+        return `/${FILES.indexHtml}`;
+    }
+    return joinUrl(pagesUrlPrefix, pageName, FILES.indexHtml);
+}
+
+export function resolvePageHtmlDir(pagesRoot: string, pageName: string, useRootIndex: boolean): string {
+    if (useRootIndex && pageName === FOLDERS.home) {
+        return pagesRoot;
+    }
+    return path.join(pagesRoot, pageName);
+}
+
+function joinUrl(...segments: string[]): string {
+    const cleaned = segments
+        .map(segment => trimSlashes(segment))
+        .filter(segment => segment.length > 0);
+    return `/${cleaned.join('/')}`;
+}
+
+function trimSlashes(value: string): string {
+    return value.replace(/^\/+|\/+$/g, '');
+}

package/src/utils/pathMatch.ts

@@ -0,0 +1,36 @@
+import path from 'node:path';
+
+export function isInsideDirectory(filePath: string, directory: string): boolean {
+    const resolvedFile = path.resolve(filePath);
+    const resolvedDirectory = path.resolve(directory);
+    const relative = path.relative(resolvedDirectory, resolvedFile);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+export function findPageFromChangedFile(changedFile: string | undefined, pagesRoot: string): string | null {
+    if (!changedFile) {
+        return null;
+    }
+
+    const resolvedChanged = path.resolve(changedFile);
+    const resolvedPagesRoot = path.resolve(pagesRoot);
+    if (!isInsideDirectory(resolvedChanged, resolvedPagesRoot)) {
+        return null;
+    }
+
+    const relative = path.relative(resolvedPagesRoot, resolvedChanged);
+    const segments = relative.split(path.sep);
+    return segments.length > 0 && segments[0] ? segments[0] : null;
+}
+
+export function relativePathWithin(filePath: string | undefined, directory: string): string | null {
+    if (!filePath) {
+        return null;
+    }
+
+    if (!isInsideDirectory(filePath, directory)) {
+        return null;
+    }
+
+    return path.relative(path.resolve(directory), path.resolve(filePath));
+}

package/src/watch/frontendFiles.ts

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import { ensureDir, pathExists, copy } from '../utils/fs.js';
+import { FILES, EXTENSIONS } from '../core/constants.js';
+import type { EnableFlags, FrontendConfig } from '../types.js';
+
+export async function resolveEntryPoint(pageDirectory: string): Promise<string | null> {
+    const candidates = [`${FILES.index}${EXTENSIONS.ts}`, `${FILES.index}.tsx`, `${FILES.index}${EXTENSIONS.js}`, `${FILES.index}.jsx`];
+
+    for (const candidate of candidates) {
+        const file = path.join(pageDirectory, candidate);
+        if (await pathExists(file)) {
+            return file;
+        }
+    }
+
+    return null;
+}
+
+export async function copyRefreshScript(config: FrontendConfig, enable?: EnableFlags): Promise<void> {
+    const runtimeScripts: string[] = [FILES.refreshJs, FILES.hmrJs];
+
+    for (const scriptName of runtimeScripts) {
+        const source = path.join(config.paths.src.app, scriptName);
+        if (!(await pathExists(source))) {
+            continue;
+        }
+
+        const destination = path.join(config.paths.build.frontend, scriptName);
+        await ensureDir(path.dirname(destination));
+        await copy(source, destination);
+    }
+}