@webstir-io/webstir-frontend 0.1.40

package/src/watch/watchDaemon.ts

@@ -0,0 +1,144 @@
+import process from 'node:process';
+import { createInterface, Interface as ReadLineInterface } from 'node:readline';
+import { emitDiagnostic } from '../core/diagnostics.js';
+import { WatchCoordinator } from './watchCoordinator.js';
+import type { WatchDaemonCommand, WatchDaemonOptions } from './types.js';
+
+export class WatchDaemon {
+    private readonly coordinator: WatchCoordinator;
+    private readonly options: WatchDaemonOptions;
+    private readonly shutdownPromise: Promise<void>;
+    private resolveShutdown: (() => void) | null = null;
+    private commandQueue: Promise<void> = Promise.resolve();
+    private isShuttingDown = false;
+    private rl?: ReadLineInterface;
+
+    public constructor(options: WatchDaemonOptions) {
+        this.options = options;
+        this.coordinator = new WatchCoordinator({
+            workspaceRoot: options.workspaceRoot,
+            verbose: options.verbose ?? false,
+            hmrVerbose: options.hmrVerbose ?? false
+        });
+        this.shutdownPromise = new Promise((resolve) => {
+            this.resolveShutdown = resolve;
+        });
+    }
+
+    public async run(): Promise<void> {
+        if (this.options.autoStart !== false) {
+            await this.coordinator.start();
+        }
+
+        this.setupSignalHandlers();
+        this.setupCommandLoop();
+
+        await this.shutdownPromise;
+    }
+
+    private setupCommandLoop(): void {
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+        }
+        process.stdin.setEncoding('utf8');
+
+        this.rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+        this.rl.on('line', (line) => this.processLine(line));
+        this.rl.on('close', () => {
+            void this.shutdown();
+        });
+    }
+
+    private setupSignalHandlers(): void {
+        const shutdown = () => {
+            void this.shutdown();
+        };
+
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+
+    private processLine(rawLine: string): void {
+        const line = rawLine.trim();
+        if (line.length === 0) {
+            return;
+        }
+
+        let command: WatchDaemonCommand | null = null;
+        try {
+            command = JSON.parse(line) as WatchDaemonCommand;
+        } catch (error) {
+            emitDiagnostic({
+                code: 'frontend.watch.command.invalid',
+                kind: 'watch-daemon',
+                stage: 'command',
+                severity: 'warning',
+                message: `Discarding invalid command payload: ${String(error)}`
+            });
+            return;
+        }
+
+        this.commandQueue = this.commandQueue.then(() => this.handleCommand(command!)).catch((error) => {
+            emitDiagnostic({
+                code: 'frontend.watch.command.failure',
+                kind: 'watch-daemon',
+                stage: 'command',
+                severity: 'error',
+                message: `Command handling failed: ${error instanceof Error ? error.message : String(error)}`
+            });
+        });
+    }
+
+    private async handleCommand(command: WatchDaemonCommand): Promise<void> {
+        switch (command.type) {
+            case 'start':
+                await this.coordinator.start();
+                return;
+            case 'reload':
+                await this.coordinator.reload();
+                return;
+            case 'change':
+                await this.coordinator.handleChange({ path: command.path });
+                return;
+            case 'shutdown':
+                await this.shutdown();
+                return;
+            case 'ping':
+                emitDiagnostic({
+                    code: 'frontend.watch.pong',
+                    kind: 'watch-daemon',
+                    stage: 'command',
+                    severity: 'info',
+                    message: 'Watch daemon heartbeat acknowledged.',
+                    data: command.id ? { id: command.id } : undefined
+                });
+                return;
+            default:
+                emitDiagnostic({
+                    code: 'frontend.watch.command.unknown',
+                    kind: 'watch-daemon',
+                    stage: 'command',
+                    severity: 'warning',
+                    message: `Unknown watch daemon command: ${(command as { type?: unknown }).type}`
+                });
+                return;
+        }
+    }
+
+    private async shutdown(): Promise<void> {
+        if (this.isShuttingDown) {
+            return;
+        }
+
+        this.isShuttingDown = true;
+
+        if (this.rl) {
+            this.rl.close();
+            this.rl = undefined;
+        }
+
+        await this.coordinator.stop();
+        this.resolveShutdown?.();
+        this.resolveShutdown = null;
+    }
+}

package/src/watch/watchReporter.ts

@@ -0,0 +1,98 @@
+import type { BuildResult, Message } from 'esbuild';
+import { emitDiagnostic } from '../core/diagnostics.js';
+import type { DiagnosticEvent } from '../core/diagnostics.js';
+
+export interface WatchReporterOptions {
+    readonly verbose: boolean;
+}
+
+export interface SerializedMessage {
+    readonly text: string;
+    readonly location?: {
+        readonly file?: string;
+        readonly line?: number;
+        readonly column?: number;
+    };
+}
+
+export class WatchReporter {
+    private readonly verbose: boolean;
+
+    public constructor(options: WatchReporterOptions) {
+        this.verbose = options.verbose;
+    }
+
+    public emit(event: DiagnosticEvent): void {
+        emitDiagnostic(event);
+    }
+
+    public emitVerbose(event: DiagnosticEvent): void {
+        if (!this.verbose) {
+            return;
+        }
+
+        emitDiagnostic(event);
+    }
+
+    public emitJavaScriptStats(pageName: string, result: BuildResult, durationMs: number): void {
+        if (!this.verbose) {
+            return;
+        }
+
+        const stats = extractMetafileStats(result);
+        const data: Record<string, unknown> = {
+            page: pageName,
+            durationMs: Number(durationMs.toFixed(1))
+        };
+
+        if (stats) {
+            data.inputs = stats.inputs;
+            data.outputs = stats.outputs;
+            data.bytes = stats.bytes;
+        }
+
+        emitDiagnostic({
+            code: 'frontend.watch.javascript.build.stats',
+            kind: 'watch-daemon',
+            stage: 'javascript',
+            severity: 'info',
+            message: `JavaScript rebuild stats for '${pageName}' (${durationMs.toFixed(1)}ms).`,
+            data
+        });
+    }
+}
+
+export function serializeMessages(messages: readonly Message[]): SerializedMessage[] {
+    return messages.map((message) => ({
+        text: message.text,
+        location: message.location
+            ? {
+                  file: message.location.file,
+                  line: message.location.line,
+                  column: message.location.column
+              }
+            : undefined
+    }));
+}
+
+function extractMetafileStats(result: BuildResult): MetafileStats | null {
+    if (!result.metafile) {
+        return null;
+    }
+
+    const inputs = Object.keys(result.metafile.inputs ?? {}).length;
+    const outputsEntries = Object.entries(result.metafile.outputs ?? {});
+    const bytes = outputsEntries.reduce((sum, [, output]) => sum + (output.bytes ?? 0), 0);
+
+    return {
+        inputs,
+        outputs: outputsEntries.length,
+        bytes
+    };
+}
+
+interface MetafileStats {
+    readonly inputs: number;
+    readonly outputs: number;
+    readonly bytes: number;
+}

package/tests/add-page-defaults.test.js

@@ -0,0 +1,64 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { runAddPage } from '../dist/index.js';
+
+async function createWorkspace(pkg) {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'webstir-frontend-add-page-'));
+    await fs.writeFile(path.join(root, 'package.json'), JSON.stringify(pkg, null, 2), 'utf8');
+    return root;
+}
+
+test('add-page defaults to ssg scaffold when webstir.mode=ssg', async () => {
+    const workspace = await createWorkspace({
+        name: 'webstir-project',
+        version: '1.0.0',
+        webstir: { mode: 'ssg' }
+    });
+
+    try {
+        await runAddPage({ workspaceRoot: workspace, pageName: 'about' });
+
+        const pageDir = path.join(workspace, 'src', 'frontend', 'pages', 'about');
+        const htmlPath = path.join(pageDir, 'index.html');
+        const cssPath = path.join(pageDir, 'index.css');
+        const tsPath = path.join(pageDir, 'index.ts');
+
+        assert.equal(fssync.existsSync(htmlPath), true);
+        assert.equal(fssync.existsSync(cssPath), true);
+        assert.equal(fssync.existsSync(tsPath), false);
+
+        const html = await fs.readFile(htmlPath, 'utf8');
+        assert.ok(!html.includes('<script type="module"'), 'ssg scaffold should not include module script tag');
+    } finally {
+        await fs.rm(workspace, { recursive: true, force: true });
+    }
+});
+
+test('add-page defaults to standard scaffold when webstir.mode is not ssg', async () => {
+    const workspace = await createWorkspace({
+        name: 'webstir-project',
+        version: '1.0.0'
+    });
+
+    try {
+        await runAddPage({ workspaceRoot: workspace, pageName: 'about' });
+
+        const pageDir = path.join(workspace, 'src', 'frontend', 'pages', 'about');
+        const htmlPath = path.join(pageDir, 'index.html');
+        const tsPath = path.join(pageDir, 'index.ts');
+
+        assert.equal(fssync.existsSync(htmlPath), true);
+        assert.equal(fssync.existsSync(tsPath), true);
+
+        const html = await fs.readFile(htmlPath, 'utf8');
+        assert.ok(html.includes('<script type="module"'), 'standard scaffold should include module script tag');
+    } finally {
+        await fs.rm(workspace, { recursive: true, force: true });
+    }
+});
+

package/tests/content-pages.test.js

@@ -0,0 +1,81 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+async function loadProviderOrSkip(t) {
+  try {
+    const mod = await import('../dist/index.js');
+    return mod.frontendProvider;
+  } catch (err) {
+    console.warn('[frontend-tests] Skipping provider integration: optional dependency unavailable:', err?.message ?? err);
+    t?.diagnostic?.('skip: missing optional dependency');
+    return null;
+  }
+}
+
+async function createWorkspaceWithContent() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'webstir-frontend-content-'));
+  const appDir = path.join(root, 'src', 'frontend', 'app');
+  const pageDir = path.join(root, 'src', 'frontend', 'pages', 'home');
+  const contentDir = path.join(root, 'src', 'frontend', 'content');
+  await fs.mkdir(appDir, { recursive: true });
+  await fs.mkdir(pageDir, { recursive: true });
+  await fs.mkdir(contentDir, { recursive: true });
+
+  await fs.writeFile(
+    path.join(appDir, 'app.html'),
+    '<!DOCTYPE html><html><head><title>My Site</title></head><body><main></main></body></html>',
+    'utf8'
+  );
+  await fs.writeFile(path.join(appDir, 'app.css'), 'body{font-family:sans-serif;}', 'utf8');
+  await fs.writeFile(path.join(pageDir, 'index.html'), '<head></head><main><section>Home</section></main>', 'utf8');
+
+  await fs.writeFile(
+    path.join(contentDir, 'readme.md'),
+    [
+      '---',
+      'title: Content pipeline',
+      'description: How it works',
+      'order: 1',
+      '---',
+      '',
+      '# Content pipeline',
+      '',
+      'Hello from markdown.'
+    ].join('\n'),
+    'utf8'
+  );
+
+  return root;
+}
+
+test('content builder strips frontmatter and injects app styles', async (t) => {
+  const frontendProvider = await loadProviderOrSkip(t);
+  if (!frontendProvider) return;
+  const workspace = await createWorkspaceWithContent();
+
+  try {
+    await frontendProvider.build({ workspaceRoot: workspace, env: { WEBSTIR_MODULE_MODE: 'build' }, incremental: false });
+
+    const htmlPath = path.join(workspace, 'build', 'frontend', 'pages', 'docs', 'readme', 'index.html');
+    assert.equal(fssync.existsSync(htmlPath), true, `expected ${htmlPath}`);
+
+    const html = await fs.readFile(htmlPath, 'utf8');
+    assert.ok(!html.includes('title: Content pipeline'), 'frontmatter should not be rendered');
+    assert.ok(/<article\b/i.test(html), 'expected markdown wrapped in <article>');
+    assert.ok(html.includes('href="/app/app.css"'), 'expected app.css link injected');
+    assert.ok(html.includes('href="/pages/docs/index.css"'), 'expected docs css link injected');
+
+    const navPath = path.join(workspace, 'build', 'frontend', 'docs-nav.json');
+    assert.equal(fssync.existsSync(navPath), true, `expected ${navPath}`);
+
+    const nav = JSON.parse(await fs.readFile(navPath, 'utf8'));
+    assert.ok(Array.isArray(nav) && nav.length > 0, 'expected docs-nav.json to contain entries');
+    assert.ok(nav.some((entry) => entry.path === '/docs/readme/'), 'expected docs-nav.json to include /docs/readme/');
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});

package/tests/css-app-imports.test.js

@@ -0,0 +1,64 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+async function loadProviderOrSkip(t) {
+  try {
+    const mod = await import('../dist/index.js');
+    return mod.frontendProvider;
+  } catch (err) {
+    console.warn('[frontend-tests] Skipping provider integration: optional dependency unavailable:', err?.message ?? err);
+    t?.diagnostic?.('skip: missing optional dependency');
+    return null;
+  }
+}
+
+async function createWorkspace() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'webstir-frontend-css-'));
+  const appDir = path.join(root, 'src', 'frontend', 'app');
+  const stylesDir = path.join(appDir, 'styles');
+  const pageDir = path.join(root, 'src', 'frontend', 'pages', 'home');
+  await fs.mkdir(stylesDir, { recursive: true });
+  await fs.mkdir(pageDir, { recursive: true });
+
+  await fs.writeFile(
+    path.join(appDir, 'app.html'),
+    '<!DOCTYPE html><html><head><title>App</title></head><body><main></main></body></html>',
+    'utf8'
+  );
+  await fs.writeFile(
+    path.join(appDir, 'app.css'),
+    [
+      '@layer reset, base;',
+      '@import "./styles/base.css";'
+    ].join('\n'),
+    'utf8'
+  );
+  await fs.writeFile(path.join(stylesDir, 'base.css'), '@layer base { body { background: blue; } }', 'utf8');
+  await fs.writeFile(path.join(pageDir, 'index.html'), '<head></head><main><section>Home</section></main>', 'utf8');
+  await fs.writeFile(path.join(pageDir, 'index.css'), '@import "@app/app.css";', 'utf8');
+
+  return root;
+}
+
+test('development app.css import URLs include a cache-busting version', async (t) => {
+  const frontendProvider = await loadProviderOrSkip(t);
+  if (!frontendProvider) return;
+  const workspace = await createWorkspace();
+
+  try {
+    await frontendProvider.build({ workspaceRoot: workspace, env: { WEBSTIR_MODULE_MODE: 'build' }, incremental: false });
+
+    const appCssPath = path.join(workspace, 'build', 'frontend', 'app', 'app.css');
+    assert.equal(fssync.existsSync(appCssPath), true, `expected ${appCssPath}`);
+
+    const appCss = await fs.readFile(appCssPath, 'utf8');
+    assert.match(appCss, /@import\s+["']\.\/styles\/base\.css\?v=[a-f0-9]+["'];/i);
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});
+

package/tests/css-page-imports.test.js

@@ -0,0 +1,100 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import fssync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+async function loadProviderOrSkip(t) {
+  try {
+    const mod = await import('../dist/index.js');
+    return mod.frontendProvider;
+  } catch (err) {
+    console.warn('[frontend-tests] Skipping provider integration: optional dependency unavailable:', err?.message ?? err);
+    t?.diagnostic?.('skip: missing optional dependency');
+    return null;
+  }
+}
+
+async function createWorkspace() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'webstir-frontend-page-css-'));
+  const appDir = path.join(root, 'src', 'frontend', 'app');
+  const pageDir = path.join(root, 'src', 'frontend', 'pages', 'home');
+  const partialsDir = path.join(pageDir, 'partials');
+  await fs.mkdir(appDir, { recursive: true });
+  await fs.mkdir(partialsDir, { recursive: true });
+
+  await fs.writeFile(
+    path.join(appDir, 'app.html'),
+    '<!DOCTYPE html><html><head><title>App</title></head><body><main></main></body></html>',
+    'utf8'
+  );
+  await fs.writeFile(path.join(appDir, 'app.css'), '', 'utf8');
+  await fs.writeFile(path.join(pageDir, 'index.html'), '<head></head><main><section>Home</section></main>', 'utf8');
+
+  await fs.writeFile(
+    path.join(pageDir, 'index.css'),
+    [
+      '@layer overrides { .home { color: red; } }',
+      '@import "./layout.css";',
+      '@import url("./partials/colors.css");'
+    ].join('\n'),
+    'utf8'
+  );
+
+  await fs.writeFile(
+    path.join(pageDir, 'layout.css'),
+    [
+      '@layer overrides { .layout { display: grid; } }',
+      '@import "./partials/typography.css";'
+    ].join('\n'),
+    'utf8'
+  );
+
+  await fs.writeFile(
+    path.join(partialsDir, 'colors.css'),
+    '@layer overrides { .colors { color: blue; } }',
+    'utf8'
+  );
+
+  await fs.writeFile(
+    path.join(partialsDir, 'typography.css'),
+    '@layer overrides { .type { font-weight: 700; } }',
+    'utf8'
+  );
+
+  return root;
+}
+
+test('build inlines page-local CSS @import files', async (t) => {
+  const frontendProvider = await loadProviderOrSkip(t);
+  if (!frontendProvider) return;
+  const workspace = await createWorkspace();
+
+  try {
+    await frontendProvider.build({ workspaceRoot: workspace, env: { WEBSTIR_MODULE_MODE: 'build' }, incremental: false });
+
+    const cssPath = path.join(workspace, 'build', 'frontend', 'pages', 'home', 'index.css');
+    assert.equal(fssync.existsSync(cssPath), true, `expected ${cssPath}`);
+
+    assert.equal(
+      fssync.existsSync(path.join(workspace, 'build', 'frontend', 'pages', 'home', 'layout.css')),
+      true,
+      'expected imported layout.css copied for dev server'
+    );
+    assert.equal(
+      fssync.existsSync(path.join(workspace, 'build', 'frontend', 'pages', 'home', 'partials', 'colors.css')),
+      true,
+      'expected imported nested css copied for dev server'
+    );
+
+    const css = await fs.readFile(cssPath, 'utf8');
+    assert.ok(css.includes('.home'), 'expected entry css content');
+    assert.ok(css.includes('.layout'), 'expected imported css content');
+    assert.ok(css.includes('.colors'), 'expected imported css content');
+    assert.ok(css.includes('.type'), 'expected nested imported css content');
+    assert.equal(css.includes('@import "./layout.css"'), false, 'expected imports to be inlined');
+  } finally {
+    await fs.rm(workspace, { recursive: true, force: true });
+  }
+});

package/tests/diagnostics.test.js

@@ -0,0 +1,48 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { emitDiagnostic, STRUCTURED_DIAGNOSTIC_PREFIX } from '../dist/core/index.js';
+
+test('emitDiagnostic emits human-readable and structured output', () => {
+    const originalLog = console.log;
+    const originalWarn = console.warn;
+    const logs = [];
+    const warnings = [];
+
+    console.log = (message) => {
+        logs.push(message);
+    };
+    console.warn = (message) => {
+        warnings.push(message);
+    };
+
+    try {
+        emitDiagnostic({
+            code: 'frontend.test.warning',
+            kind: 'test',
+            stage: 'unit',
+            severity: 'warning',
+            message: 'Sample diagnostic for testing.',
+            data: { flag: true }
+        });
+    } finally {
+        console.log = originalLog;
+        console.warn = originalWarn;
+    }
+
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0], /\[webstir-frontend]\[frontend\.test\.warning\] Sample diagnostic for testing\./);
+
+    assert.equal(logs.length, 1);
+    const structuredLine = logs[0];
+    assert.ok(structuredLine.startsWith(STRUCTURED_DIAGNOSTIC_PREFIX));
+
+    const payload = JSON.parse(structuredLine.slice(STRUCTURED_DIAGNOSTIC_PREFIX.length));
+    assert.equal(payload.type, 'diagnostic');
+    assert.equal(payload.code, 'frontend.test.warning');
+    assert.equal(payload.kind, 'test');
+    assert.equal(payload.stage, 'unit');
+    assert.equal(payload.severity, 'warning');
+    assert.equal(payload.message, 'Sample diagnostic for testing.');
+    assert.deepEqual(payload.data, { flag: true });
+});

package/tests/features.test.js

@@ -0,0 +1,63 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import { buildConfig } from '../dist/config/workspace.js';
+
+async function createWorkspace(frontendConfig) {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'webstir-frontend-'));
+    const workspaceRoot = path.join(tempRoot, 'workspace');
+    const frontendRoot = path.join(workspaceRoot, 'src', 'frontend');
+    await fs.mkdir(frontendRoot, { recursive: true });
+
+    if (frontendConfig !== undefined) {
+        const configPath = path.join(frontendRoot, 'frontend.config.json');
+        await fs.writeFile(configPath, JSON.stringify(frontendConfig, null, 2), 'utf8');
+    }
+
+    return {
+        workspaceRoot,
+        cleanup: () => fs.rm(tempRoot, { recursive: true, force: true })
+    };
+}
+
+test('buildConfig returns defaults when frontend.config.json is absent', async (t) => {
+    const workspace = await createWorkspace();
+    t.after(workspace.cleanup);
+
+    const config = buildConfig(workspace.workspaceRoot);
+    assert.equal(config.features.htmlSecurity, true);
+    assert.equal(config.features.imageOptimization, true);
+    assert.equal(config.features.precompression, true);
+});
+
+test('buildConfig applies overrides from nested features key', async (t) => {
+    const workspace = await createWorkspace({
+        features: {
+            htmlSecurity: false,
+            precompression: false
+        }
+    });
+    t.after(workspace.cleanup);
+
+    const config = buildConfig(workspace.workspaceRoot);
+    assert.equal(config.features.htmlSecurity, false);
+    assert.equal(config.features.precompression, false);
+    assert.equal(config.features.imageOptimization, true);
+});
+
+test('buildConfig accepts top-level feature flags', async (t) => {
+    const workspace = await createWorkspace({
+        htmlSecurity: false,
+        imageOptimization: false,
+        precompression: true
+    });
+    t.after(workspace.cleanup);
+
+    const config = buildConfig(workspace.workspaceRoot);
+    assert.equal(config.features.htmlSecurity, false);
+    assert.equal(config.features.imageOptimization, false);
+    assert.equal(config.features.precompression, true);
+});