@webstir-io/webstir-frontend 0.1.40

package/dist/builders/jsBuilder.js

@@ -0,0 +1,300 @@
+import path from 'node:path';
+import { build as esbuild } from 'esbuild';
+import { glob } from 'glob';
+import { FOLDERS, FILES, EXTENSIONS } from '../core/constants.js';
+import { getPages } from '../core/pages.js';
+import { ensureDir, pathExists, copy, remove, stat } from '../utils/fs.js';
+import { updatePageManifest, updateSharedAssets, readSharedAssets } from '../assets/assetManifest.js';
+import { createCompressedVariants } from '../assets/precompression.js';
+import { shouldProcess } from '../utils/changedFile.js';
+import { findPageFromChangedFile } from '../utils/pathMatch.js';
+const ENTRY_EXTENSIONS = ['.ts', '.tsx', '.js'];
+const APP_ENTRY_BASENAME = 'app';
+export function createJavaScriptBuilder(context) {
+    return {
+        name: 'javascript',
+        async build() {
+            await bundleJavaScript(context, false);
+        },
+        async publish() {
+            await bundleJavaScript(context, true);
+        }
+    };
+}
+async function bundleJavaScript(context, isProduction) {
+    const { config } = context;
+    if (!shouldProcess(context, [
+        {
+            directory: config.paths.src.frontend,
+            extensions: [EXTENSIONS.ts, EXTENSIONS.js, '.tsx', '.jsx']
+        }
+    ])) {
+        return;
+    }
+    const targetPage = findPageFromChangedFile(context.changedFile, config.paths.src.pages);
+    const pages = await getPages(config.paths.src.pages);
+    let builtAny = false;
+    await assertFeatureModulesPresent(config, context.enable);
+    await compileAppTypeScript(config, isProduction);
+    for (const page of pages) {
+        if (targetPage && page.name !== targetPage) {
+            continue;
+        }
+        const entryPoint = await resolveEntryPoint(page.directory);
+        if (!entryPoint) {
+            continue;
+        }
+        builtAny = true;
+        if (isProduction) {
+            await buildForProduction(config, page.name, entryPoint);
+        }
+        else {
+            await buildForDevelopment(config, page.name, entryPoint);
+        }
+    }
+    // Always copy dev runtime scripts in dev builds to support HMR/refresh even when no page JS exists.
+    if (!isProduction || context.enable?.clientNav || context.enable?.search) {
+        await copyRuntimeScripts(config, context.enable, isProduction);
+    }
+}
+async function compileAppTypeScript(config, isProduction) {
+    const appRoot = config.paths.src.app;
+    if (!(await pathExists(appRoot))) {
+        return;
+    }
+    if (isProduction) {
+        const entryPoint = await resolveAppEntry(appRoot);
+        if (!entryPoint) {
+            return;
+        }
+        const outputDir = path.join(config.paths.dist.frontend, FOLDERS.app);
+        await ensureDir(outputDir);
+        const result = await esbuild({
+            entryPoints: [entryPoint],
+            outdir: outputDir,
+            format: 'esm',
+            target: 'es2020',
+            platform: 'browser',
+            minify: true,
+            sourcemap: false,
+            bundle: true,
+            entryNames: 'app-[hash]',
+            assetNames: 'assets/[name]-[hash]',
+            metafile: true,
+            logLevel: 'silent'
+        });
+        const fileName = await resolveAppBundleName(outputDir, entryPoint, result.metafile);
+        if (!fileName) {
+            throw new Error(`esbuild did not produce an app bundle for ${entryPoint}.`);
+        }
+        const absolutePath = path.join(outputDir, fileName);
+        if (config.features.precompression) {
+            await createCompressedVariants(absolutePath);
+        }
+        else {
+            await Promise.all([
+                remove(`${absolutePath}${EXTENSIONS.br}`).catch(() => undefined),
+                remove(`${absolutePath}${EXTENSIONS.gz}`).catch(() => undefined)
+            ]);
+        }
+        const existing = await readSharedAssets(config.paths.dist.frontend);
+        const previousFile = existing?.js;
+        if (previousFile && previousFile !== fileName) {
+            const previousPath = path.join(outputDir, previousFile);
+            await remove(previousPath).catch(() => undefined);
+            await remove(`${previousPath}${EXTENSIONS.br}`).catch(() => undefined);
+            await remove(`${previousPath}${EXTENSIONS.gz}`).catch(() => undefined);
+        }
+        await updateSharedAssets(config.paths.dist.frontend, shared => {
+            shared.js = fileName;
+        });
+        return;
+    }
+    const entryPoints = (await glob('**/*.{ts,tsx}', { cwd: appRoot, nodir: true }))
+        .filter((relativePath) => !relativePath.endsWith('.d.ts'))
+        .map((relativePath) => path.join(appRoot, relativePath));
+    if (entryPoints.length === 0) {
+        return;
+    }
+    const outdir = isProduction
+        ? path.join(config.paths.dist.frontend, FOLDERS.app)
+        : path.join(config.paths.build.frontend, FOLDERS.app);
+    await ensureDir(outdir);
+    await esbuild({
+        entryPoints,
+        outdir,
+        format: 'esm',
+        target: 'es2020',
+        platform: 'browser',
+        sourcemap: !isProduction,
+        minify: isProduction,
+        bundle: false,
+        outbase: appRoot,
+        logLevel: 'silent'
+    });
+}
+async function buildForDevelopment(config, pageName, entryPoint) {
+    const outputDir = path.join(config.paths.build.pages, pageName);
+    await ensureDir(outputDir);
+    const outfile = path.join(outputDir, `${FILES.index}${EXTENSIONS.js}`);
+    await esbuild({
+        entryPoints: [entryPoint],
+        bundle: true,
+        format: 'esm',
+        target: 'es2020',
+        platform: 'browser',
+        sourcemap: true,
+        outfile,
+        logLevel: 'silent'
+    });
+}
+async function buildForProduction(config, pageName, entryPoint) {
+    const outputDir = path.join(config.paths.dist.pages, pageName);
+    await ensureDir(outputDir);
+    const result = await esbuild({
+        entryPoints: [entryPoint],
+        bundle: true,
+        format: 'esm',
+        target: 'es2020',
+        platform: 'browser',
+        minify: true,
+        sourcemap: false,
+        outdir: outputDir,
+        entryNames: `${FILES.index}-[hash]`,
+        assetNames: 'assets/[name]-[hash]',
+        metafile: true,
+        logLevel: 'silent'
+    });
+    const outputs = result.metafile?.outputs ?? {};
+    const scriptPath = Object.keys(outputs).find((file) => file.endsWith('.js'));
+    if (!scriptPath) {
+        throw new Error(`esbuild did not produce a JavaScript bundle for page '${pageName}'.`);
+    }
+    const fileName = path.basename(scriptPath);
+    const absolutePath = path.join(outputDir, fileName);
+    if (config.features.precompression) {
+        await createCompressedVariants(absolutePath);
+    }
+    else {
+        await Promise.all([
+            remove(`${absolutePath}${EXTENSIONS.br}`).catch(() => undefined),
+            remove(`${absolutePath}${EXTENSIONS.gz}`).catch(() => undefined)
+        ]);
+    }
+    await updatePageManifest(outputDir, pageName, (manifest) => {
+        manifest.js = fileName;
+    });
+}
+async function copyRuntimeScripts(config, enable, isProduction) {
+    const scripts = [
+        // Always copy dev runtime in dev builds to support live reload, even if no page JS exists.
+        { name: FILES.refreshJs, copyToDist: false, required: !isProduction },
+        { name: FILES.hmrJs, copyToDist: false, required: !isProduction }
+    ];
+    for (const script of scripts) {
+        if (!script.required) {
+            continue;
+        }
+        const source = path.join(config.paths.src.app, script.name);
+        if (!(await pathExists(source))) {
+            continue;
+        }
+        const buildDestination = path.join(config.paths.build.frontend, script.name);
+        await ensureDir(path.dirname(buildDestination));
+        await copy(source, buildDestination);
+        if (isProduction && script.copyToDist) {
+            const distDestination = path.join(config.paths.dist.frontend, script.name);
+            await ensureDir(path.dirname(distDestination));
+            await copy(source, distDestination);
+        }
+    }
+}
+async function resolveEntryPoint(pageDirectory) {
+    for (const extension of ENTRY_EXTENSIONS) {
+        const candidate = path.join(pageDirectory, `${FILES.index}${extension}`);
+        if (await pathExists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+async function assertFeatureModulesPresent(config, enable) {
+    if (!enable) {
+        return;
+    }
+    const missing = [];
+    if (enable.clientNav === true) {
+        const hasClientNav = await hasFeatureModule(config, 'client-nav');
+        if (!hasClientNav) {
+            missing.push('client-nav');
+        }
+    }
+    if (enable.search === true) {
+        const hasSearch = await hasFeatureModule(config, 'search');
+        if (!hasSearch) {
+            missing.push('search');
+        }
+    }
+    if (enable.contentNav === true) {
+        const hasContentNav = await hasFeatureModule(config, 'content-nav');
+        if (!hasContentNav) {
+            missing.push('content-nav');
+        }
+    }
+    if (missing.length === 0) {
+        return;
+    }
+    const expected = missing
+        .map((name) => `src/frontend/app/scripts/features/${name}.ts`)
+        .join(', ');
+    throw new Error(`Enabled feature module(s) missing: ${missing.join(', ')}. Run 'webstir enable <feature>' to scaffold them (expected: ${expected}).`);
+}
+async function hasFeatureModule(config, name) {
+    const root = path.join(config.paths.src.app, 'scripts', 'features');
+    return await pathExists(path.join(root, `${name}${EXTENSIONS.ts}`))
+        || await pathExists(path.join(root, `${name}${EXTENSIONS.js}`));
+}
+async function resolveAppBundleName(outputDir, entryPoint, metafile) {
+    const outputs = metafile?.outputs ?? {};
+    const outputEntries = Object.entries(outputs);
+    const entryOutput = outputEntries.find(([, meta]) => {
+        if (!meta.entryPoint) {
+            return false;
+        }
+        return path.resolve(meta.entryPoint) === path.resolve(entryPoint);
+    });
+    if (entryOutput) {
+        return path.basename(entryOutput[0]);
+    }
+    const matches = await glob('app-*.js', { cwd: outputDir, nodir: true });
+    if (matches.length === 0) {
+        return null;
+    }
+    if (matches.length === 1) {
+        return matches[0] ?? null;
+    }
+    let latest = null;
+    for (const name of matches) {
+        const info = await stat(path.join(outputDir, name));
+        const time = info.mtimeMs;
+        if (!latest || time > latest.time) {
+            latest = { name, time };
+        }
+    }
+    return latest?.name ?? matches[0] ?? null;
+}
+async function resolveAppEntry(appRoot) {
+    const candidates = [
+        `${APP_ENTRY_BASENAME}${EXTENSIONS.ts}`,
+        `${APP_ENTRY_BASENAME}.tsx`,
+        `${APP_ENTRY_BASENAME}${EXTENSIONS.js}`,
+        `${APP_ENTRY_BASENAME}.jsx`
+    ];
+    for (const candidate of candidates) {
+        const fullPath = path.join(appRoot, candidate);
+        if (await pathExists(fullPath)) {
+            return fullPath;
+        }
+    }
+    return null;
+}

package/dist/builders/staticAssetsBuilder.d.ts

@@ -0,0 +1,2 @@
+import type { Builder, BuilderContext } from './types.js';
+export declare function createStaticAssetsBuilder(context: BuilderContext): Builder;

package/dist/builders/staticAssetsBuilder.js

@@ -0,0 +1,158 @@
+import path from 'node:path';
+import { FOLDERS, EXTENSIONS, FILES } from '../core/constants.js';
+import { copy, pathExists, emptyDir, ensureDir, remove, writeFile } from '../utils/fs.js';
+import { shouldProcess } from '../utils/changedFile.js';
+import { optimizeImages } from '../assets/imageOptimizer.js';
+import { relativePathWithin } from '../utils/pathMatch.js';
+const IMAGE_EXTENSIONS = [
+    EXTENSIONS.png,
+    EXTENSIONS.jpg,
+    EXTENSIONS.jpeg,
+    EXTENSIONS.gif,
+    EXTENSIONS.svg,
+    EXTENSIONS.webp,
+    EXTENSIONS.ico
+];
+const FONT_EXTENSIONS = [
+    EXTENSIONS.woff,
+    EXTENSIONS.woff2,
+    EXTENSIONS.ttf,
+    EXTENSIONS.otf,
+    EXTENSIONS.eot
+];
+const MEDIA_EXTENSIONS = [
+    EXTENSIONS.mp3,
+    EXTENSIONS.m4a,
+    EXTENSIONS.wav,
+    EXTENSIONS.ogg,
+    EXTENSIONS.mp4,
+    EXTENSIONS.webm,
+    EXTENSIONS.mov
+];
+const ALLOW_ALL_ROBOTS = 'User-agent: *\nAllow: /\n';
+export function createStaticAssetsBuilder(context) {
+    return {
+        name: 'static-assets',
+        async build() {
+            await copyStaticAssets(context, false);
+        },
+        async publish() {
+            await copyStaticAssets(context, true);
+        }
+    };
+}
+async function copyStaticAssets(context, isProduction) {
+    const { config } = context;
+    if (!shouldProcess(context, [
+        { directory: config.paths.src.images, extensions: IMAGE_EXTENSIONS },
+        { directory: config.paths.src.fonts, extensions: FONT_EXTENSIONS },
+        { directory: config.paths.src.media, extensions: MEDIA_EXTENSIONS }
+    ])) {
+        return;
+    }
+    const targets = [
+        { source: config.paths.src.images, build: config.paths.build.frontend, dist: config.paths.dist.frontend, folder: FOLDERS.images, extensions: IMAGE_EXTENSIONS },
+        { source: config.paths.src.fonts, build: config.paths.build.frontend, dist: config.paths.dist.frontend, folder: FOLDERS.fonts, extensions: FONT_EXTENSIONS },
+        { source: config.paths.src.media, build: config.paths.build.frontend, dist: config.paths.dist.frontend, folder: FOLDERS.media, extensions: MEDIA_EXTENSIONS }
+    ];
+    for (const target of targets) {
+        if (!(await pathExists(target.source))) {
+            continue;
+        }
+        const changedRelative = relativePathWithin(context.changedFile, target.source);
+        const buildDestination = path.join(target.build, target.folder);
+        if (!context.changedFile || !changedRelative) {
+            await emptyDir(buildDestination);
+            await copy(target.source, buildDestination);
+            if (isProduction) {
+                const distDestination = path.join(target.dist, target.folder);
+                if (target.folder === FOLDERS.images) {
+                    if (config.features.imageOptimization) {
+                        await optimizeImages(buildDestination, distDestination);
+                    }
+                    else {
+                        await emptyDir(distDestination);
+                        await copy(buildDestination, distDestination);
+                    }
+                }
+                else {
+                    await emptyDir(distDestination);
+                    await copy(buildDestination, distDestination);
+                }
+            }
+            continue;
+        }
+        await copySingleAsset(target.source, buildDestination, changedRelative);
+        if (isProduction) {
+            const distDestination = path.join(target.dist, target.folder);
+            if (target.folder === FOLDERS.images) {
+                if (config.features.imageOptimization) {
+                    await optimizeImages(buildDestination, distDestination, [changedRelative]);
+                }
+                else {
+                    await syncImageWithoutOptimization(buildDestination, distDestination, changedRelative);
+                }
+            }
+            else {
+                const sourcePath = path.join(target.source, changedRelative);
+                const destPath = path.join(distDestination, changedRelative);
+                if (await pathExists(sourcePath)) {
+                    await ensureDir(path.dirname(destPath));
+                    await copy(sourcePath, destPath);
+                }
+                else {
+                    await remove(destPath).catch(() => undefined);
+                }
+            }
+        }
+    }
+    await syncRobotsTxt(config, isProduction);
+}
+async function copySingleAsset(sourceRoot, buildRoot, relativePath) {
+    const sourcePath = path.join(sourceRoot, relativePath);
+    const destinationPath = path.join(buildRoot, relativePath);
+    if (await pathExists(sourcePath)) {
+        await ensureDir(path.dirname(destinationPath));
+        await copy(sourcePath, destinationPath);
+    }
+    else {
+        await remove(destinationPath).catch(() => undefined);
+    }
+}
+async function syncImageWithoutOptimization(buildRoot, distRoot, relativePath) {
+    const sourcePath = path.join(buildRoot, relativePath);
+    const destinationPath = path.join(distRoot, relativePath);
+    if (await pathExists(sourcePath)) {
+        await ensureDir(path.dirname(destinationPath));
+        await copy(sourcePath, destinationPath);
+    }
+    else {
+        await remove(destinationPath).catch(() => undefined);
+    }
+    await Promise.all([
+        remove(`${destinationPath}${EXTENSIONS.webp}`).catch(() => undefined),
+        remove(`${destinationPath}${EXTENSIONS.avif}`).catch(() => undefined)
+    ]);
+}
+async function syncRobotsTxt(config, isProduction) {
+    const sourcePath = path.join(config.paths.src.frontend, FILES.robotsTxt);
+    const buildPath = path.join(config.paths.build.frontend, FILES.robotsTxt);
+    if (await pathExists(sourcePath)) {
+        await ensureDir(path.dirname(buildPath));
+        await copy(sourcePath, buildPath);
+        if (isProduction) {
+            const distPath = path.join(config.paths.dist.frontend, FILES.robotsTxt);
+            await ensureDir(path.dirname(distPath));
+            await copy(sourcePath, distPath);
+        }
+    }
+    else {
+        await ensureDir(path.dirname(buildPath));
+        await writeFile(buildPath, ALLOW_ALL_ROBOTS);
+        if (isProduction) {
+            const distPath = path.join(config.paths.dist.frontend, FILES.robotsTxt);
+            await ensureDir(path.dirname(distPath));
+            await writeFile(distPath, ALLOW_ALL_ROBOTS);
+        }
+    }
+}

package/dist/builders/types.d.ts

@@ -0,0 +1,12 @@
+import type { EnableFlags, FrontendConfig } from '../types.js';
+export interface BuilderContext {
+    readonly config: FrontendConfig;
+    readonly changedFile?: string;
+    readonly enable?: EnableFlags;
+}
+export interface Builder {
+    readonly name: string;
+    build(context: BuilderContext): Promise<void>;
+    publish(context: BuilderContext): Promise<void>;
+}
+export type BuilderFactory = (context: BuilderContext) => Builder;

package/dist/builders/types.js

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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { runAddPage, runBuild, runPublish, runRebuild } from './operations.js';
+import { WatchDaemon } from './watch/watchDaemon.js';
+const program = new Command();
+program
+    .name('webstir-frontend')
+    .description('Webstir frontend build orchestrator');
+program
+    .command('build')
+    .description('Build frontend assets for development workflows')
+    .requiredOption('-w, --workspace <path>', 'Absolute path to the workspace root')
+    .option('-c, --changed-file <path>', 'Optional path filter for incremental builds')
+    .action(async (cmd) => {
+    try {
+        await runBuild({
+            workspaceRoot: cmd.workspace,
+            changedFile: cmd.changedFile ?? undefined
+        });
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
+program
+    .command('publish')
+    .description('Build production assets into the dist directory')
+    .requiredOption('-w, --workspace <path>', 'Absolute path to the workspace root')
+    .option('-m, --mode <mode>', 'Publish mode: bundle or ssg', 'bundle')
+    .action(async (cmd) => {
+    try {
+        await runPublish({
+            workspaceRoot: cmd.workspace,
+            publishMode: cmd.mode === 'ssg' ? 'ssg' : 'bundle'
+        });
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
+program
+    .command('rebuild')
+    .description('Rebuild frontend assets in response to file changes')
+    .requiredOption('-w, --workspace <path>', 'Absolute path to the workspace root')
+    .requiredOption('-c, --changed-file <path>', 'Path to the changed file triggering the rebuild')
+    .action(async (cmd) => {
+    try {
+        await runRebuild({
+            workspaceRoot: cmd.workspace,
+            changedFile: cmd.changedFile ?? undefined
+        });
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
+program
+    .command('add-page <name>')
+    .description('Scaffold a new frontend page (HTML/CSS/TS)')
+    .requiredOption('-w, --workspace <path>', 'Absolute path to the workspace root')
+    .option('-m, --mode <mode>', 'Page mode: standard or ssg (defaults to ssg when webstir.mode=ssg)')
+    .action(async (name, cmd) => {
+    try {
+        const rawMode = typeof cmd.mode === 'string' ? cmd.mode.toLowerCase() : undefined;
+        await runAddPage({
+            workspaceRoot: cmd.workspace,
+            pageName: name,
+            ssg: rawMode === 'ssg' ? true : rawMode === 'standard' ? false : undefined
+        });
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
+program
+    .command('watch-daemon')
+    .description('Run the persistent frontend watch daemon')
+    .requiredOption('-w, --workspace <path>', 'Absolute path to the workspace root')
+    .option('--no-auto-start', 'Defer startup until a start command is received')
+    .option('-v, --verbose', 'Enable verbose watch diagnostics')
+    .option('--hmr-verbose', 'Log detailed hot-update diagnostics')
+    .action(async (cmd) => {
+    try {
+        const daemon = new WatchDaemon({
+            workspaceRoot: cmd.workspace,
+            autoStart: cmd.autoStart,
+            verbose: cmd.verbose === true,
+            hmrVerbose: cmd.hmrVerbose === true
+        });
+        await daemon.run();
+    }
+    catch (error) {
+        handleError(error);
+    }
+});
+program.parseAsync(process.argv).catch(handleError);
+function handleError(error) {
+    if (error instanceof Error) {
+        console.error(error.message);
+    }
+    else {
+        console.error('Unknown error', error);
+    }
+    process.exitCode = 1;
+}

package/dist/config/manifest.d.ts

@@ -0,0 +1,7 @@
+import { type FrontendConfigInput } from './schema.js';
+export interface WriteManifestOptions {
+    readonly outputPath: string;
+    readonly data: FrontendConfigInput;
+}
+export declare function writeConfigManifest(options: WriteManifestOptions): Promise<void>;
+export declare function readConfigManifest(manifestPath: string): Promise<FrontendConfigInput>;

package/dist/config/manifest.js

@@ -0,0 +1,17 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { frontendConfigSchema } from './schema.js';
+export async function writeConfigManifest(options) {
+    const parsed = frontendConfigSchema.parse(options.data);
+    const directory = path.dirname(options.outputPath);
+    await fs.mkdir(directory, { recursive: true });
+    const serialized = JSON.stringify(parsed, undefined, 2);
+    const tempPath = path.join(directory, `.webstir-frontend-${process.pid}-${Date.now()}.tmp`);
+    await fs.writeFile(tempPath, serialized, 'utf8');
+    await fs.rename(tempPath, options.outputPath);
+}
+export async function readConfigManifest(manifestPath) {
+    const json = await fs.readFile(manifestPath, 'utf8');
+    const parsed = JSON.parse(json);
+    return frontendConfigSchema.parse(parsed);
+}

package/dist/config/paths.d.ts

@@ -0,0 +1,3 @@
+export declare const FRONTEND_MANIFEST_FILENAME = "frontend-manifest.json";
+export declare function resolveManifestPath(workspaceRoot: string): string;
+export declare function ensureWebstirDirectory(workspaceRoot: string): Promise<void>;

package/dist/config/paths.js

@@ -0,0 +1,11 @@
+import path from 'path';
+import { promises as fs } from 'fs';
+import { FOLDERS } from '../core/constants.js';
+export const FRONTEND_MANIFEST_FILENAME = 'frontend-manifest.json';
+export function resolveManifestPath(workspaceRoot) {
+    return path.join(workspaceRoot, FOLDERS.webstir, FRONTEND_MANIFEST_FILENAME);
+}
+export async function ensureWebstirDirectory(workspaceRoot) {
+    const webstirPath = path.join(workspaceRoot, FOLDERS.webstir);
+    await fs.mkdir(webstirPath, { recursive: true });
+}