@webstir-io/webstir-frontend 0.1.40

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Electric Coding LLC and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @webstir-io/webstir-frontend
+
+Frontend build and publish toolkit for Webstir workspaces. The package bundles the HTML/CSS/JS pipeline, scaffolding helpers, and module provider used by the Webstir CLI and installers.
+
+## Status
+
+- Experimental provider for the Webstir ecosystem — pipeline details and configuration surfaces may change between releases.
+- Best suited for exploration and demos today; do not rely on it as a hardened production frontend pipeline yet.
+
+## Quick Start
+
+1. **Install the package**
+   ```bash
+   npm install @webstir-io/webstir-frontend
+   ```
+2. **Run a build**
+   ```bash
+   npx webstir-frontend build --workspace /absolute/path/to/workspace
+   ```
+
+Requires Node.js **20.18.x** or newer.
+
+## Workspace Layout
+
+The provider assumes the standard Webstir workspace shape:
+
+```
+workspace/
+  src/frontend/
+    app/
+    pages/
+    images/
+    fonts/
+    media/
+    frontend.config.json   # optional feature flag overrides
+    webstir.config.mjs     # optional hook definitions
+  build/frontend/...       # generated build artifacts
+  dist/frontend/...        # publish-ready assets
+  .webstir/manifest.json   # pipeline manifest emitted on each run
+```
+
+## CLI Commands
+
+Binary name: `webstir-frontend`. All commands require `--workspace` pointing to the absolute workspace root.
+
+| Command | Description | Useful options |
+|---------|-------------|----------------|
+| `build` | Runs the development pipeline (incremental safe). | `--changed-file <path>` to scope rebuilds. |
+| `publish` | Produces optimized assets under `dist/frontend`. | `--mode <bundle\|ssg>` (SSG preview). |
+| `rebuild` | Incremental rebuild triggered by a file change. | `--changed-file <path>` to pass the changed file. |
+| `add-page <name>` | Scaffolds a page (HTML/CSS/TS) inside `src/frontend/pages`. | — |
+| `watch-daemon` | Persistent watcher + HMR coordinator. | `--no-auto-start`, `--verbose`, `--hmr-verbose`. |
+
+### Feature Flags
+
+`frontend.config.json` enables or disables pipeline features:
+
+```jsonc
+{
+  "features": {
+    "htmlSecurity": true,
+    "imageOptimization": true,
+    "precompression": false
+  }
+}
+```
+
+### Lifecycle Hooks
+
+Hooks live in `webstir.config.mjs` (or `.js`/`.cjs`) at the workspace root:
+
+```js
+export const hooks = {
+  pipeline: {
+    beforeAll({ mode }) {
+      console.info(`[webstir] starting ${mode} pipeline`);
+    }
+  },
+  builders: {
+    assets: {
+      after({ config }) {
+        // custom post-processing
+      }
+    }
+  }
+};
+```
+
+## API Usage
+
+The package exports a `ModuleProvider` compatible with `@webstir-io/module-contract`:
+
+```ts
+import { frontendProvider } from '@webstir-io/webstir-frontend';
+
+const result = await frontendProvider.build({
+  workspaceRoot: '/absolute/path/to/workspace',
+  env: { WEBSTIR_MODULE_MODE: 'publish' }
+});
+
+   console.log(result.manifest.entryPoints);
+   ```
+
+- `frontendProvider.metadata` surfaces id/version compatibility.
+- `frontendProvider.resolveWorkspace` returns canonical source/build/test paths.
+- `frontendProvider.build` executes the pipeline and returns artifacts + manifest.
+
+## SSG Preview
+
+When invoked as:
+
+```bash
+npx webstir-frontend publish --workspace /absolute/path/to/workspace --mode ssg
+```
+
+the provider:
+
+- Runs the normal publish pipeline to populate `dist/frontend/**`.
+- Creates static-friendly `index.html` aliases (root and per-page).
+- When `package.json` includes `webstir.moduleManifest.views` with `renderMode: 'ssg'` and `staticPaths`, uses those paths to add additional `index.html` aliases under `dist/frontend/**`.
+
+## Maintainer Workflow
+
+```bash
+npm install
+npm run clean          # remove dist artifacts
+npm run build          # TypeScript → dist/
+npm run test           # Node --test against compiled output
+npm run smoke          # scaffolds a temp workspace and runs build/publish
+# Release helper (bumps version, pushes tags to trigger release workflow)
+npm run release -- patch
+```
+
+GitHub Actions should run `npm ci`, `npm run clean`, `npm run build`, `npm run test`, and `npm run smoke` before publishing. The release workflow publishes to npm with trusted publishing (`id-token: write` + provenance).
+
+CI notes
+- Package CI runs clean + build + tests + smoke on PRs and main.
+
+## Troubleshooting
+
+- **“404 Not Found” when installing `@webstir-io/module-contract`** — verify the dependency has been published to npm and re-generate `package-lock.json` against npmjs.
+- **“No frontend test files found”** — the `test` script expects files under `tests/**/*.test.js` after build.
+- **Missing entry points in manifest** — confirm `build/frontend` contains at least one `.js`/`.mjs` bundle; the provider falls back to `build/app/index.js` and emits a warning if empty.
+
+## Community & Support
+
+- Code of Conduct: https://github.com/webstir-io/.github/blob/main/CODE_OF_CONDUCT.md
+- Contributing guidelines: https://github.com/webstir-io/.github/blob/main/CONTRIBUTING.md
+- Security policy and disclosure process: https://github.com/webstir-io/.github/blob/main/SECURITY.md
+- Support expectations and contact channels: https://github.com/webstir-io/.github/blob/main/SUPPORT.md
+
+## Third-Party Notices
+
+Webstir Frontend depends on third-party libraries and data sets (including `sharp`/libvips and `caniuse-lite`) under their respective licenses. See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for a summary of notable licenses and attribution.
+
+## License
+
+MIT © Webstir

package/dist/assets/assetManifest.d.ts

@@ -0,0 +1,16 @@
+export interface PageAssetManifest {
+    js?: string;
+    css?: string;
+}
+export interface AssetManifest {
+    pages: Record<string, PageAssetManifest>;
+    shared?: SharedAssets;
+}
+export interface SharedAssets {
+    css?: string;
+    js?: string;
+}
+export declare function updatePageManifest(directory: string, pageName: string, updater: (value: PageAssetManifest) => void): Promise<void>;
+export declare function readPageManifest(directory: string, pageName: string): Promise<PageAssetManifest>;
+export declare function updateSharedAssets(directory: string, updater: (value: SharedAssets) => void): Promise<void>;
+export declare function readSharedAssets(directory: string): Promise<SharedAssets | null>;

package/dist/assets/assetManifest.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { readJson, writeJson, ensureDir } from '../utils/fs.js';
+const MANIFEST_FILENAME = 'manifest.json';
+export async function updatePageManifest(directory, pageName, updater) {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    await ensureDir(directory);
+    const manifest = (await readJson(manifestPath)) ?? { pages: {} };
+    const pageManifest = manifest.pages[pageName] ?? {};
+    updater(pageManifest);
+    manifest.pages[pageName] = pageManifest;
+    await writeJson(manifestPath, manifest);
+}
+export async function readPageManifest(directory, pageName) {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    const manifest = (await readJson(manifestPath)) ?? { pages: {} };
+    return manifest.pages[pageName] ?? {};
+}
+export async function updateSharedAssets(directory, updater) {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    await ensureDir(directory);
+    const manifest = (await readJson(manifestPath)) ?? { pages: {} };
+    const shared = manifest.shared ?? {};
+    updater(shared);
+    manifest.shared = shared;
+    await writeJson(manifestPath, manifest);
+}
+export async function readSharedAssets(directory) {
+    const manifestPath = path.join(directory, MANIFEST_FILENAME);
+    const manifest = await readJson(manifestPath);
+    return manifest?.shared ?? null;
+}

package/dist/assets/imageOptimizer.d.ts

@@ -0,0 +1,6 @@
+export interface ImageDimensions {
+    width: number;
+    height: number;
+}
+export declare function optimizeImages(sourceDir: string, destinationDir: string, files?: string[]): Promise<void>;
+export declare function getImageDimensions(filePath: string): Promise<ImageDimensions | null>;

package/dist/assets/imageOptimizer.js

@@ -0,0 +1,93 @@
+import path from 'node:path';
+import sharp from 'sharp';
+import { glob } from 'glob';
+import { copy, ensureDir, emptyDir, pathExists, remove } from '../utils/fs.js';
+import { EXTENSIONS } from '../core/constants.js';
+const TRANSCODABLE_EXTENSIONS = new Set([
+    EXTENSIONS.png,
+    EXTENSIONS.jpg,
+    EXTENSIONS.jpeg
+]);
+export async function optimizeImages(sourceDir, destinationDir, files) {
+    if (!(await pathExists(sourceDir))) {
+        await emptyDir(destinationDir);
+        return;
+    }
+    if (!files || files.length === 0) {
+        await emptyDir(destinationDir);
+        const allFiles = await glob('**/*', { cwd: sourceDir, nodir: true });
+        await Promise.all(allFiles.map(async (relative) => processImage(sourceDir, destinationDir, relative)));
+        return;
+    }
+    await ensureDir(destinationDir);
+    await Promise.all(files.map(async (relative) => processImage(sourceDir, destinationDir, relative, true)));
+}
+export async function getImageDimensions(filePath) {
+    try {
+        const metadata = await sharp(filePath).metadata();
+        if (typeof metadata.width === 'number' && typeof metadata.height === 'number') {
+            return { width: metadata.width, height: metadata.height };
+        }
+    }
+    catch {
+        // Ignore errors – the caller can continue without dimensions.
+    }
+    return null;
+}
+function replaceExtension(filePath, extension) {
+    const parsed = path.parse(filePath);
+    return path.join(parsed.dir, `${parsed.name}${extension}`);
+}
+async function createWebpVariant(sourcePath, destinationPath) {
+    try {
+        await sharp(sourcePath)
+            .webp({ quality: 75 })
+            .toFile(destinationPath);
+    }
+    catch {
+        // Ignore failures; fall back to original image only.
+    }
+}
+async function createAvifVariant(sourcePath, destinationPath) {
+    try {
+        await sharp(sourcePath)
+            .avif({ quality: 45 })
+            .toFile(destinationPath);
+    }
+    catch {
+        // Ignore failures; fall back to original image only.
+    }
+}
+async function processImage(sourceDir, destinationDir, relative, incremental = false) {
+    const sourcePath = path.join(sourceDir, relative);
+    const destinationPath = path.join(destinationDir, relative);
+    if (!(await pathExists(sourcePath))) {
+        await removeVariants(destinationPath, true);
+        return;
+    }
+    await ensureDir(path.dirname(destinationPath));
+    await copy(sourcePath, destinationPath);
+    const extension = path.extname(sourcePath).toLowerCase();
+    if (!TRANSCODABLE_EXTENSIONS.has(extension)) {
+        if (incremental) {
+            await removeVariants(destinationPath, false);
+        }
+        return;
+    }
+    if (incremental) {
+        await removeVariants(destinationPath, false);
+    }
+    await Promise.all([
+        createWebpVariant(sourcePath, replaceExtension(destinationPath, EXTENSIONS.webp)),
+        createAvifVariant(sourcePath, replaceExtension(destinationPath, EXTENSIONS.avif))
+    ]);
+}
+async function removeVariants(destinationPath, includeBase) {
+    const targets = [replaceExtension(destinationPath, EXTENSIONS.webp), replaceExtension(destinationPath, EXTENSIONS.avif)];
+    if (includeBase) {
+        targets.push(destinationPath);
+    }
+    await Promise.all(targets.map(async (target) => {
+        await remove(target).catch(() => undefined);
+    }));
+}

package/dist/assets/precompression.d.ts

@@ -0,0 +1 @@
+export declare function createCompressedVariants(filePath: string): Promise<void>;

package/dist/assets/precompression.js

@@ -0,0 +1,21 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { constants as zlibConstants, createBrotliCompress, createGzip } from 'node:zlib';
+export async function createCompressedVariants(filePath) {
+    await Promise.all([
+        compress(filePath, '.br', () => createBrotliCompress({ params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 11 } })),
+        compress(filePath, '.gz', () => createGzip({ level: zlibConstants.Z_BEST_COMPRESSION }))
+    ]);
+}
+async function compress(source, extension, factory) {
+    return new Promise((resolve, reject) => {
+        const destination = `${source}${extension}`;
+        const readStream = createReadStream(source);
+        const writeStream = createWriteStream(destination);
+        const compressor = factory();
+        readStream.on('error', reject);
+        writeStream.on('error', reject);
+        compressor.on('error', reject);
+        writeStream.on('close', resolve);
+        readStream.pipe(compressor).pipe(writeStream);
+    });
+}

package/dist/builders/contentBuilder.d.ts

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