@webstir-io/webstir-frontend 0.1.40

package/dist/watch/watchDaemon.js

@@ -0,0 +1,127 @@
+import process from 'node:process';
+import { createInterface } from 'node:readline';
+import { emitDiagnostic } from '../core/diagnostics.js';
+import { WatchCoordinator } from './watchCoordinator.js';
+export class WatchDaemon {
+    coordinator;
+    options;
+    shutdownPromise;
+    resolveShutdown = null;
+    commandQueue = Promise.resolve();
+    isShuttingDown = false;
+    rl;
+    constructor(options) {
+        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;
+        });
+    }
+    async run() {
+        if (this.options.autoStart !== false) {
+            await this.coordinator.start();
+        }
+        this.setupSignalHandlers();
+        this.setupCommandLoop();
+        await this.shutdownPromise;
+    }
+    setupCommandLoop() {
+        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();
+        });
+    }
+    setupSignalHandlers() {
+        const shutdown = () => {
+            void this.shutdown();
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    }
+    processLine(rawLine) {
+        const line = rawLine.trim();
+        if (line.length === 0) {
+            return;
+        }
+        let command = null;
+        try {
+            command = JSON.parse(line);
+        }
+        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)}`
+            });
+        });
+    }
+    async handleCommand(command) {
+        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.type}`
+                });
+                return;
+        }
+    }
+    async shutdown() {
+        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/dist/watch/watchReporter.d.ts

@@ -0,0 +1,21 @@
+import type { BuildResult, Message } from 'esbuild';
+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 declare class WatchReporter {
+    private readonly verbose;
+    constructor(options: WatchReporterOptions);
+    emit(event: DiagnosticEvent): void;
+    emitVerbose(event: DiagnosticEvent): void;
+    emitJavaScriptStats(pageName: string, result: BuildResult, durationMs: number): void;
+}
+export declare function serializeMessages(messages: readonly Message[]): SerializedMessage[];

package/dist/watch/watchReporter.js

@@ -0,0 +1,64 @@
+import { emitDiagnostic } from '../core/diagnostics.js';
+export class WatchReporter {
+    verbose;
+    constructor(options) {
+        this.verbose = options.verbose;
+    }
+    emit(event) {
+        emitDiagnostic(event);
+    }
+    emitVerbose(event) {
+        if (!this.verbose) {
+            return;
+        }
+        emitDiagnostic(event);
+    }
+    emitJavaScriptStats(pageName, result, durationMs) {
+        if (!this.verbose) {
+            return;
+        }
+        const stats = extractMetafileStats(result);
+        const data = {
+            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) {
+    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) {
+    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
+    };
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@webstir-io/webstir-frontend",
+  "version": "0.1.40",
+  "description": "Frontend build and publish tooling for Webstir workspaces.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    },
+    "./builders": {
+      "types": "./dist/builders/index.d.ts",
+      "import": "./dist/builders/index.js",
+      "default": "./dist/builders/index.js"
+    },
+    "./cli": {
+      "import": "./dist/cli.js",
+      "default": "./dist/cli.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "webstir-frontend": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "node -e \"const { spawnSync } = require('node:child_process'); const glob = require('glob'); const files = glob.sync('tests/**/*.test.js'); if (!files.length) { console.error('No frontend test files found'); process.exit(1); } const env = { ...process.env, BASELINE_BROWSER_MAPPING_IGNORE_OLD_DATA: 'true', BROWSERSLIST_IGNORE_OLD_DATA: 'true' }; const result = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit', env }); process.exit(result.status ?? 1);\"",
+    "prepare": "npm run build",
+    "smoke": "npm run build && node scripts/smoke.mjs",
+    "release": "bash scripts/publish.sh"
+  },
+  "files": [
+    "dist",
+    "src",
+    "scripts",
+    "tests",
+    "tsconfig.json",
+    "package-lock.json"
+  ],
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webstir-io/webstir-frontend"
+  },
+  "keywords": [
+    "webstir",
+    "frontend",
+    "cli"
+  ],
+  "author": "Webstir",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "@webstir-io/module-contract": "^0.1.13",
+    "autoprefixer": "^10.4.18",
+    "cheerio": "^1.0.0-rc.12",
+    "commander": "^12.1.0",
+    "csso": "^5.0.5",
+    "esbuild": "^0.25.10",
+    "fs-extra": "^11.2.0",
+    "glob": "^10.4.1",
+    "highlight.js": "^11.11.1",
+    "html-minifier-terser": "^7.2.0",
+    "marked": "^12.0.2",
+    "postcss": "^8.4.47",
+    "postcss-custom-media": "^11.0.6",
+    "sharp": "^0.33.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/csso": "^5.0.4",
+    "@types/fs-extra": "^11.0.4",
+    "@types/glob": "^8.1.0",
+    "@types/html-minifier-terser": "^7.0.2",
+    "@types/node": "^20.11.25",
+    "typescript": "^5.7.2"
+  }
+}

package/scripts/publish.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/publish.sh <patch|minor|major|x.y.z> [--no-push]
+
+Examples:
+  scripts/publish.sh patch
+  scripts/publish.sh 0.1.0
+
+The script requires a clean git worktree and npm publish access to
+@webstir-io. Publishing is handled by GitHub Actions via npm trusted
+publishing (OIDC) after the version tag is pushed.
+
+By default, the script pushes the version bump commit and tag. To skip pushing,
+pass --no-push or set PUBLISH_NO_PUSH=1.
+EOF
+  exit 1
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+main() {
+  if [[ $# -lt 1 ]]; then
+    echo "error: version bump argument missing" >&2
+    usage
+  fi
+
+  local bump="$1"; shift || true
+  local no_push="false"
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --no-push)
+        no_push="true"
+        ;;
+      *)
+        echo "error: unknown option '$1'" >&2
+        usage
+        ;;
+    esac
+    shift || true
+  done
+
+  if [[ ! $bump =~ ^(patch|minor|major)$ && ! $bump =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "error: invalid bump '$bump'" >&2
+    usage
+  fi
+
+  ensure_clean_git
+
+  cd "$ROOT_DIR"
+
+  echo "› npm version $bump"
+  npm version "$bump" -m "v%s"
+
+  echo "› npm install --package-lock-only"
+  npm install --package-lock-only
+
+  echo "› npm run clean"
+  npm run clean
+
+  echo "› npm run build"
+  npm run build
+
+  echo "› npm test"
+  npm test
+
+  echo "› npm run smoke"
+  npm run smoke
+
+  echo "› Skipping direct npm publish; pushing commit+tag will trigger the release workflow."
+
+  if [[ "$no_push" == "true" || "${PUBLISH_NO_PUSH:-}" =~ ^([Yy][Ee][Ss]|[Yy]|1|true)$ ]]; then
+    echo "› Skipping git push (no-push)."
+    echo "  To publish upstream later, run: git push && git push --tags"
+    return 0
+  fi
+
+  echo "› git push"
+  git push
+  echo "› git push --tags"
+  git push --tags
+}
+
+ensure_clean_git() {
+  cd "$ROOT_DIR"
+  if ! git diff --quiet --ignore-submodules HEAD; then
+    echo "error: git worktree has uncommitted changes" >&2
+    exit 1
+  fi
+  if ! git diff --quiet --cached --ignore-submodules; then
+    echo "error: git index has staged changes" >&2
+    exit 1
+  fi
+}
+
+main "$@"

package/scripts/smoke.mjs

@@ -0,0 +1,35 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { frontendProvider } from '../dist/index.js';
+
+async function createWorkspace() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'webstir-frontend-smoke-'));
+  const appDir = path.join(root, 'src', 'frontend', 'app');
+  const pageDir = path.join(root, 'src', 'frontend', 'pages', 'home');
+  await fs.mkdir(appDir, { 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(pageDir, 'index.html'), '<head></head><main><section>Home</section></main>', 'utf8');
+  await fs.writeFile(path.join(pageDir, 'index.ts'), 'console.log("home")', 'utf8');
+  return root;
+}
+
+async function main() {
+  const workspace = await createWorkspace();
+  console.info('[smoke:frontend] build mode');
+  const build = await frontendProvider.build({ workspaceRoot: workspace, env: { WEBSTIR_MODULE_MODE: 'build' }, incremental: false });
+  console.info('[smoke:frontend] build entries:', build.manifest.entryPoints);
+  console.info('[smoke:frontend] build diagnostics:', build.manifest.diagnostics.map(d => d.message));
+
+  console.info('[smoke:frontend] publish mode');
+  const publish = await frontendProvider.build({ workspaceRoot: workspace, env: { WEBSTIR_MODULE_MODE: 'publish' }, incremental: false });
+  console.info('[smoke:frontend] publish entries:', publish.manifest.entryPoints);
+  console.info('[smoke:frontend] publish diagnostics:', publish.manifest.diagnostics.map(d => d.message));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+

package/scripts/update-contract.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/update-contract.sh [x.y.z|--latest] [--exact] [--fast]
+
+Updates @webstir-io/module-contract (defaults to latest when no version is provided),
+installs deps, then builds and tests the frontend package. Does NOT publish. If
+everything passes, run scripts/publish.sh <bump> separately.
+
+Examples:
+  scripts/update-contract.sh                # use latest
+  scripts/update-contract.sh --latest       # explicit latest
+  scripts/update-contract.sh 0.1.9          # specific version (caret range)
+  scripts/update-contract.sh 0.1.9 --exact  # set exact version instead of ^range
+  scripts/update-contract.sh 0.1.9 --fast   # lockfile-only update; skip build/test
+EOF
+  exit 1
+}
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+has_script() {
+  local script_name="$1"
+  node -e "const fs=require('fs'); const pkg=JSON.parse(fs.readFileSync('package.json','utf8')); const has=!!(pkg.scripts && Object.prototype.hasOwnProperty.call(pkg.scripts, '${script_name}')); process.exit(has ? 0 : 1);"
+}
+
+main() {
+  local ver=""
+  local exact="false"
+  local fast="false"
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --latest)
+        ver="__resolve_latest__"
+        ;;
+      --exact)
+        exact="true"
+        ;;
+      --fast)
+        fast="true"
+        ;;
+      -h|--help)
+        usage ;;
+      *)
+        if [[ -n "$ver" && "$ver" != "__resolve_latest__" ]]; then
+          echo "error: duplicate version argument '$1'" >&2
+          usage
+        fi
+        ver="$1"
+        ;;
+    esac
+    shift || true
+  done
+
+  if [[ -z "$ver" || "$ver" == "__resolve_latest__" ]]; then
+    echo "› Resolving latest @webstir-io/module-contract version"
+    ver="$(npm view @webstir-io/module-contract version 2>/dev/null || true)"
+    if [[ -z "$ver" ]]; then
+      echo "error: unable to resolve latest @webstir-io/module-contract version" >&2
+      exit 1
+    fi
+  fi
+
+  if [[ ! $ver =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "error: invalid version '$ver' (expected x.y.z)" >&2
+    usage
+  fi
+
+  cd "$ROOT_DIR"
+
+  local spec
+  if [[ "$exact" == "true" ]]; then
+    spec="$ver"
+  else
+    spec="^$ver"
+  fi
+
+  echo "› Setting @webstir-io/module-contract to $spec"
+  npm pkg set "dependencies.@webstir-io/module-contract=$spec"
+
+  echo "› npm install (refresh lockfile)"
+  if [[ "$fast" == "true" ]]; then
+    npm install --package-lock-only --no-audit --no-fund --ignore-scripts
+  else
+    npm install --no-audit --no-fund
+  fi
+
+  local frontend_ver
+  frontend_ver="$(node -p "require('./package.json').version" 2>/dev/null || echo 'unknown')"
+  local installed_contract
+  installed_contract="$(npm ls @webstir-io/module-contract --json 2>/dev/null | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{const j=JSON.parse(d);const v=(j.dependencies&&j.dependencies['@webstir-io/module-contract']&&j.dependencies['@webstir-io/module-contract'].version)||'';console.log(v||'unknown')}catch{console.log('unknown')}})")"
+  echo "› Frontend package: @webstir-io/webstir-frontend@${frontend_ver}"
+  echo "› Contract installed: @webstir-io/module-contract@${installed_contract}"
+
+  if [[ "$fast" != "true" ]]; then
+    if has_script build; then
+      echo "› npm run build"
+      npm run build
+    fi
+
+    if has_script test; then
+      echo "› npm test"
+      npm test
+    fi
+
+    if has_script smoke; then
+      echo "› npm run smoke"
+      npm run smoke
+    fi
+  fi
+
+  echo
+  echo "Contract update complete: @webstir-io/module-contract@$spec"
+}
+
+main "$@"

package/src/assets/assetManifest.ts

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { readJson, writeJson, ensureDir } from '../utils/fs.js';
+
+export interface PageAssetManifest {
+    js?: string;
+    css?: string;
+}
+
+export interface AssetManifest {
+    pages: Record<string, PageAssetManifest>;
+    shared?: SharedAssets;
+}
+
+export interface SharedAssets {
+    css?: string;
+    js?: string;
+}
+
+const MANIFEST_FILENAME = 'manifest.json';
+
+export async function updatePageManifest(directory: string, pageName: string, updater: (value: PageAssetManifest) => void): Promise<void> {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    await ensureDir(directory);
+    const manifest = (await readJson<AssetManifest>(manifestPath)) ?? { pages: {} };
+    const pageManifest: PageAssetManifest = manifest.pages[pageName] ?? {};
+    updater(pageManifest);
+    manifest.pages[pageName] = pageManifest;
+    await writeJson(manifestPath, manifest);
+}
+
+export async function readPageManifest(directory: string, pageName: string): Promise<PageAssetManifest> {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    const manifest = (await readJson<AssetManifest>(manifestPath)) ?? { pages: {} };
+    return manifest.pages[pageName] ?? {};
+}
+
+export async function updateSharedAssets(directory: string, updater: (value: SharedAssets) => void): Promise<void> {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    await ensureDir(directory);
+    const manifest = (await readJson<AssetManifest>(manifestPath)) ?? { pages: {} };
+    const shared: SharedAssets = manifest.shared ?? {};
+    updater(shared);
+    manifest.shared = shared;
+    await writeJson(manifestPath, manifest);
+}
+
+export async function readSharedAssets(directory: string): Promise<SharedAssets | null> {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    const manifest = await readJson<AssetManifest>(manifestPath);
+    return manifest?.shared ?? null;
+}