@webstir-io/webstir-frontend 0.1.40

package/src/config/schema.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+export const frontendPathSchema = z.object({
+    workspace: z.string(),
+    src: z.object({
+        root: z.string(),
+        frontend: z.string(),
+        app: z.string(),
+        pages: z.string(),
+        content: z.string(),
+        images: z.string(),
+        fonts: z.string(),
+        media: z.string()
+    }),
+    build: z.object({
+        root: z.string(),
+        frontend: z.string(),
+        app: z.string(),
+        pages: z.string(),
+        content: z.string(),
+        images: z.string(),
+        fonts: z.string(),
+        media: z.string()
+    }),
+    dist: z.object({
+        root: z.string(),
+        frontend: z.string(),
+        app: z.string(),
+        pages: z.string(),
+        content: z.string(),
+        images: z.string(),
+        fonts: z.string(),
+        media: z.string()
+    })
+});
+
+export const frontendFeatureFlagsSchema = z.object({
+    htmlSecurity: z.boolean().default(true),
+    imageOptimization: z.boolean().default(true),
+    precompression: z.boolean().default(true)
+});
+
+export const frontendConfigSchema = z.object({
+    version: z.literal(1),
+    paths: frontendPathSchema,
+    features: frontendFeatureFlagsSchema
+});
+
+export type FrontendConfigInput = z.infer<typeof frontendConfigSchema>;

package/src/config/setup.ts

@@ -0,0 +1,14 @@
+import { writeConfigManifest } from './manifest.js';
+import { buildConfig } from './workspace.js';
+import { ensureWebstirDirectory, resolveManifestPath } from './paths.js';
+import type { FrontendConfig } from '../types.js';
+
+export async function prepareWorkspaceConfig(workspaceRoot: string): Promise<FrontendConfig> {
+    const config = buildConfig(workspaceRoot);
+    await ensureWebstirDirectory(workspaceRoot);
+    await writeConfigManifest({
+        outputPath: resolveManifestPath(workspaceRoot),
+        data: config
+    });
+    return config;
+}

package/src/config/workspace.ts

@@ -0,0 +1,150 @@
+import fs from 'node:fs';
+import path from 'path';
+import type { FrontendConfig, FrontendFeatureFlags } from '../types.js';
+import { FOLDERS } from '../core/constants.js';
+import { frontendFeatureFlagsSchema } from './schema.js';
+
+const DEFAULT_FEATURE_FLAGS: FrontendFeatureFlags = {
+    htmlSecurity: true,
+    imageOptimization: true,
+    precompression: true
+};
+
+export function buildConfig(workspaceRoot: string): FrontendConfig {
+    const srcRoot = path.join(workspaceRoot, FOLDERS.src);
+    const frontendRoot = path.join(srcRoot, FOLDERS.frontend);
+    const buildRoot = path.join(workspaceRoot, FOLDERS.build);
+    const distRoot = path.join(workspaceRoot, FOLDERS.dist);
+
+    const buildFrontend = path.join(buildRoot, FOLDERS.frontend);
+    const distFrontend = path.join(distRoot, FOLDERS.frontend);
+    const srcContentRoot = resolveContentRoot(workspaceRoot, frontendRoot);
+
+    return {
+        version: 1,
+        paths: {
+            workspace: workspaceRoot,
+            src: {
+                root: srcRoot,
+                frontend: frontendRoot,
+                app: path.join(frontendRoot, FOLDERS.app),
+                pages: path.join(frontendRoot, FOLDERS.pages),
+                content: srcContentRoot,
+                images: path.join(frontendRoot, FOLDERS.images),
+                fonts: path.join(frontendRoot, FOLDERS.fonts),
+                media: path.join(frontendRoot, FOLDERS.media)
+            },
+            build: {
+                root: buildRoot,
+                frontend: buildFrontend,
+                app: path.join(buildFrontend, FOLDERS.app),
+                pages: path.join(buildFrontend, FOLDERS.pages),
+                content: path.join(buildFrontend, FOLDERS.pages, 'docs'),
+                images: path.join(buildFrontend, FOLDERS.images),
+                fonts: path.join(buildFrontend, FOLDERS.fonts),
+                media: path.join(buildFrontend, FOLDERS.media)
+            },
+            dist: {
+                root: distRoot,
+                frontend: distFrontend,
+                app: path.join(distFrontend, FOLDERS.app),
+                pages: path.join(distFrontend, FOLDERS.pages),
+                content: path.join(distFrontend, FOLDERS.pages, 'docs'),
+                images: path.join(distFrontend, FOLDERS.images),
+                fonts: path.join(distFrontend, FOLDERS.fonts),
+                media: path.join(distFrontend, FOLDERS.media)
+            }
+        },
+        features: loadFeatureFlags(frontendRoot)
+    };
+}
+
+function resolveContentRoot(workspaceRoot: string, frontendRoot: string): string {
+    const defaultContentRoot = path.join(frontendRoot, 'content');
+    const configPath = path.join(frontendRoot, 'frontend.config.json');
+    if (!fs.existsSync(configPath)) {
+        return defaultContentRoot;
+    }
+
+    try {
+        const raw = fs.readFileSync(configPath, 'utf8');
+        const parsed = JSON.parse(raw) as unknown;
+        const override = extractContentRoot(parsed);
+
+        if (override === undefined) {
+            return defaultContentRoot;
+        }
+
+        if (typeof override !== 'string') {
+            throw new Error('Expected contentRoot to be a string when specified.');
+        }
+
+        const trimmed = override.trim();
+        if (!trimmed) {
+            return defaultContentRoot;
+        }
+
+        if (path.isAbsolute(trimmed)) {
+            return trimmed;
+        }
+
+        return path.join(workspaceRoot, trimmed);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read frontend content root from ${configPath}: ${message}`);
+    }
+}
+
+function extractContentRoot(value: unknown): unknown {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+
+    const container = value as Record<string, unknown>;
+
+    if ('paths' in container && container.paths && typeof container.paths === 'object') {
+        const pathsContainer = container.paths as Record<string, unknown>;
+        if ('contentRoot' in pathsContainer) {
+            return pathsContainer.contentRoot;
+        }
+    }
+
+    if ('contentRoot' in container) {
+        return container.contentRoot;
+    }
+
+    return undefined;
+}
+
+function loadFeatureFlags(frontendRoot: string): FrontendFeatureFlags {
+    const configPath = path.join(frontendRoot, 'frontend.config.json');
+    if (!fs.existsSync(configPath)) {
+        return DEFAULT_FEATURE_FLAGS;
+    }
+
+    try {
+        const raw = fs.readFileSync(configPath, 'utf8');
+        const parsed = JSON.parse(raw) as unknown;
+        const overridesSource = extractOverrideSource(parsed);
+        const overrides = frontendFeatureFlagsSchema.parse(overridesSource);
+        return {
+            htmlSecurity: overrides.htmlSecurity,
+            imageOptimization: overrides.imageOptimization,
+            precompression: overrides.precompression
+        };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read frontend feature flags from ${configPath}: ${message}`);
+    }
+}
+
+function extractOverrideSource(value: unknown): Record<string, unknown> {
+    if (value && typeof value === 'object' && 'features' in (value as Record<string, unknown>)) {
+        const container = (value as Record<string, unknown>).features;
+        if (container && typeof container === 'object') {
+            return container as Record<string, unknown>;
+        }
+    }
+
+    return (value && typeof value === 'object') ? value as Record<string, unknown> : {};
+}

package/src/config/workspaceManifest.ts

@@ -0,0 +1,27 @@
+export type RenderMode = 'ssg' | 'ssr' | 'spa';
+
+export interface WorkspaceModuleView {
+    readonly name?: string;
+    readonly path?: string;
+    readonly renderMode?: RenderMode;
+    readonly staticPaths?: readonly string[];
+}
+
+export interface WorkspaceModuleRouteGuard {
+    readonly renderMode?: unknown;
+    readonly staticPaths?: unknown;
+    readonly ssg?: unknown;
+}
+
+export interface WorkspaceModuleConfig {
+    readonly views?: readonly WorkspaceModuleView[];
+    readonly routes?: readonly WorkspaceModuleRouteGuard[];
+}
+
+export interface WorkspacePackageJson {
+    readonly name?: string;
+    readonly webstir?: {
+        readonly mode?: string;
+        readonly moduleManifest?: WorkspaceModuleConfig;
+    };
+}

package/src/core/constants.ts

@@ -0,0 +1,73 @@
+export const FOLDERS = {
+    src: 'src',
+    build: 'build',
+    dist: 'dist',
+    webstir: '.webstir',
+    tests: 'tests',
+    frontend: 'frontend',
+    backend: 'backend',
+    shared: 'shared',
+    types: 'types',
+    app: 'app',
+    pages: 'pages',
+    styles: 'styles',
+    scripts: 'scripts',
+    images: 'images',
+    fonts: 'fonts',
+    media: 'media',
+    chunks: 'chunks',
+    home: 'home',
+    nodeModules: 'node_modules',
+    seed: 'seed',
+    demo: 'demo',
+    temp: 'temp'
+} as const;
+
+export const FILES = {
+    packageJson: 'package.json',
+    packageLockJson: 'package-lock.json',
+    tsBuildInfo: '.tsbuildinfo',
+    baseTsConfigJson: 'base.tsconfig.json',
+    manifestJson: 'manifest.json',
+    test: '.test',
+    index: 'index',
+    indexHtml: 'index.html',
+    refreshJs: 'refresh.js',
+    hmrJs: 'hmr.js',
+    robotsTxt: 'robots.txt'
+} as const;
+
+export const EXTENSIONS = {
+    html: '.html',
+    css: '.css',
+    br: '.br',
+    gz: '.gz',
+    dts: '.d.ts',
+    ts: '.ts',
+    js: '.js',
+    map: '.map',
+    png: '.png',
+    jpg: '.jpg',
+    jpeg: '.jpeg',
+    gif: '.gif',
+    svg: '.svg',
+    webp: '.webp',
+    avif: '.avif',
+    ico: '.ico',
+    woff: '.woff',
+    woff2: '.woff2',
+    ttf: '.ttf',
+    otf: '.otf',
+    eot: '.eot',
+    mp3: '.mp3',
+    m4a: '.m4a',
+    wav: '.wav',
+    ogg: '.ogg',
+    mp4: '.mp4',
+    webm: '.webm',
+    mov: '.mov'
+} as const;
+
+export const FILE_NAMES = {
+    htmlAppTemplate: 'app.html'
+} as const;

package/src/core/diagnostics.ts

@@ -0,0 +1,40 @@
+export type DiagnosticSeverity = 'info' | 'warning' | 'error';
+
+export interface DiagnosticEvent {
+    readonly code: string;
+    readonly kind: string;
+    readonly stage: string;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly data?: Record<string, unknown>;
+    readonly suggestion?: string;
+}
+
+export interface DiagnosticPayload extends DiagnosticEvent {
+    readonly type: 'diagnostic';
+}
+
+export const STRUCTURED_DIAGNOSTIC_PREFIX = 'WEBSTIR_DIAGNOSTIC ';
+
+export function emitDiagnostic(event: DiagnosticEvent): void {
+    const payload: DiagnosticPayload = {
+        type: 'diagnostic',
+        ...event
+    };
+
+    const logMessage = `[webstir-frontend][${event.code}] ${event.message}`;
+    switch (event.severity) {
+        case 'error':
+            console.error(logMessage);
+            break;
+        case 'warning':
+            console.warn(logMessage);
+            break;
+        default:
+            console.info(logMessage);
+            break;
+    }
+
+    const serialized = JSON.stringify(payload);
+    console.log(`${STRUCTURED_DIAGNOSTIC_PREFIX}${serialized}`);
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export * from './constants.js';
+export * from './diagnostics.js';
+export * from './pages.js';

package/src/core/pages.ts

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { glob } from 'glob';
+import { pathExists } from '../utils/fs.js';
+
+export interface PageInfo {
+    readonly name: string;
+    readonly directory: string;
+}
+
+export async function getPages(root: string): Promise<PageInfo[]> {
+    const directories = await getPageDirectories(root);
+    return directories.map((entry) => ({
+        name: entry.name,
+        directory: entry.directory
+    }));
+}
+
+export async function getPageDirectories(root: string): Promise<PageInfo[]> {
+    if (!(await pathExists(root))) {
+        return [];
+    }
+
+    const entries = await glob('*/', { cwd: root, absolute: false, withFileTypes: false });
+    return entries.map((entry) => {
+        const name = entry.endsWith('/') ? entry.slice(0, -1) : entry;
+        return {
+            name,
+            directory: path.join(root, name)
+        };
+    });
+}

package/src/hooks.ts

@@ -0,0 +1,175 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { FrontendConfig } from './types.js';
+import type { PipelineMode } from './pipeline.js';
+
+const CONFIG_CANDIDATES = ['webstir.config.mjs', 'webstir.config.js', 'webstir.config.cjs'];
+
+export interface HookContext {
+    readonly config: FrontendConfig;
+    readonly mode: PipelineMode;
+    readonly workspaceRoot: string;
+    readonly builderName?: string;
+    readonly changedFile?: string;
+}
+
+export type HookHandler = (context: HookContext) => unknown | Promise<unknown>;
+
+export interface ResolvedHooks {
+    readonly pipelineBefore: HookHandler[];
+    readonly pipelineAfter: HookHandler[];
+    readonly builderBefore: Map<string, HookHandler[]>;
+    readonly builderAfter: Map<string, HookHandler[]>;
+}
+
+interface RawHooks {
+    readonly pipeline?: RawPipelineHooks;
+    readonly builders?: Record<string, RawBuilderHooks | HookHandler | HookHandler[]>;
+}
+
+interface RawPipelineHooks {
+    readonly beforeAll?: HookHandler | HookHandler[];
+    readonly afterAll?: HookHandler | HookHandler[];
+}
+
+interface RawBuilderHooks {
+    readonly before?: HookHandler | HookHandler[];
+    readonly after?: HookHandler | HookHandler[];
+}
+
+const EMPTY_HOOKS: ResolvedHooks = {
+    pipelineBefore: [],
+    pipelineAfter: [],
+    builderBefore: new Map(),
+    builderAfter: new Map()
+};
+
+export async function loadHooks(workspaceRoot: string, cacheBust: boolean): Promise<ResolvedHooks> {
+    const configPath = findConfigPath(workspaceRoot);
+    if (!configPath) {
+        return EMPTY_HOOKS;
+    }
+
+    let moduleConfig: unknown;
+    try {
+        const fileUrl = pathToFileURL(configPath).href;
+        const url = cacheBust ? `${fileUrl}?update=${Date.now()}` : fileUrl;
+        moduleConfig = await import(url);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load hooks from ${configPath}: ${message}`);
+    }
+
+    const exported = (moduleConfig as Record<string, unknown>)?.default ?? moduleConfig;
+    if (!exported || typeof exported !== 'object') {
+        return EMPTY_HOOKS;
+    }
+
+    const rawHooks = (exported as Record<string, unknown>).hooks ?? exported;
+    if (!rawHooks || typeof rawHooks !== 'object') {
+        return EMPTY_HOOKS;
+    }
+
+    return normalizeHooks(rawHooks as RawHooks, configPath);
+}
+
+export function createHookContext(
+    config: FrontendConfig,
+    mode: PipelineMode,
+    changedFile: string | undefined,
+    builderName?: string
+): HookContext {
+    return {
+        config,
+        mode,
+        workspaceRoot: config.paths.workspace,
+        builderName,
+        changedFile
+    };
+}
+
+export async function executeHooks(label: string, handlers: HookHandler[], context: HookContext): Promise<void> {
+    for (const handler of handlers) {
+        try {
+            await handler(context);
+        } catch (error) {
+            throw wrapHookError(label, error);
+        }
+    }
+}
+
+function wrapHookError(label: string, error: unknown): Error {
+    if (error instanceof Error) {
+        error.message = `[hook:${label}] ${error.message}`;
+        return error;
+    }
+
+    return new Error(`[hook:${label}] ${String(error)}`);
+}
+
+function normalizeHooks(raw: RawHooks, configPath: string): ResolvedHooks {
+    const pipeline = raw.pipeline ?? {};
+    const pipelineBefore = normalizeHandlerSet(pipeline.beforeAll, `${configPath} pipeline.beforeAll`);
+    const pipelineAfter = normalizeHandlerSet(pipeline.afterAll, `${configPath} pipeline.afterAll`);
+
+    const builderBefore = new Map<string, HookHandler[]>();
+    const builderAfter = new Map<string, HookHandler[]>();
+
+    const builders = raw.builders ?? {};
+    for (const [name, value] of Object.entries(builders)) {
+        if (typeof value === 'function' || Array.isArray(value)) {
+            builderBefore.set(name, normalizeHandlerSet(value, `${configPath} builders.${name}`));
+            continue;
+        }
+
+        if (!value || typeof value !== 'object') {
+            continue;
+        }
+
+        const before = normalizeHandlerSet(value.before, `${configPath} builders.${name}.before`);
+        const after = normalizeHandlerSet(value.after, `${configPath} builders.${name}.after`);
+        if (before.length > 0) {
+            builderBefore.set(name, before);
+        }
+        if (after.length > 0) {
+            builderAfter.set(name, after);
+        }
+    }
+
+    return {
+        pipelineBefore,
+        pipelineAfter,
+        builderBefore,
+        builderAfter
+    };
+}
+
+function normalizeHandlerSet(value: HookHandler | HookHandler[] | undefined, label: string): HookHandler[] {
+    if (value === undefined) {
+        return [];
+    }
+
+    const handlers = Array.isArray(value) ? value : [value];
+    const normalized: HookHandler[] = [];
+
+    for (const handler of handlers) {
+        if (typeof handler !== 'function') {
+            throw new Error(`Invalid hook handler in ${label}; expected function`);
+        }
+        normalized.push(handler);
+    }
+
+    return normalized;
+}
+
+function findConfigPath(workspaceRoot: string): string | undefined {
+    for (const candidate of CONFIG_CANDIDATES) {
+        const fullPath = path.join(workspaceRoot, candidate);
+        if (fs.existsSync(fullPath)) {
+            return fullPath;
+        }
+    }
+
+    return undefined;
+}