@webstir-io/webstir-frontend 0.1.40 → 0.1.41

package/src/html/htmlSecurity.ts

@@ -1,86 +1,127 @@
-import { createHash } from 'node:crypto';
 import type { CheerioAPI } from 'cheerio';
 
 const HTTP_TIMEOUT_MS = 5000;
 
+export interface SubresourceIntegrityOptions {
+  readonly allowExternalFetch?: boolean;
+  readonly fetcher?: typeof fetch;
+}
+
 export interface SubresourceIntegrityResult {
-    readonly failures: string[];
+  readonly failures: string[];
+  readonly skippedExternalResources: string[];
 }
 
-export async function addSubresourceIntegrity(document: CheerioAPI): Promise<SubresourceIntegrityResult> {
-    const failures: string[] = [];
-    await Promise.all([
-        processScripts(document, failures),
-        processStylesheets(document, failures)
-    ]);
-    return { failures };
+export async function addSubresourceIntegrity(
+  document: CheerioAPI,
+  options: SubresourceIntegrityOptions = {},
+): Promise<SubresourceIntegrityResult> {
+  const failures: string[] = [];
+  const skippedExternalResources: string[] = [];
+  await Promise.all([
+    processScripts(document, failures, skippedExternalResources, options),
+    processStylesheets(document, failures, skippedExternalResources, options),
+  ]);
+  return { failures, skippedExternalResources };
 }
 
-async function processScripts(document: CheerioAPI, failures: string[]): Promise<void> {
-    const scripts = document('script[src]').toArray();
-    await Promise.all(scripts.map(async (element) => {
-        const script = document(element);
-        const src = script.attr('src');
-        if (!src || !isExternal(src) || script.attr('integrity')) {
-            return;
-        }
-
-        const sri = await fetchIntegrity(src);
-        if (!sri) {
-            failures.push(src);
-            return;
-        }
-
-        script.attr('integrity', sri);
-        if (!script.attr('crossorigin')) {
-            script.attr('crossorigin', 'anonymous');
-        }
-    }));
+async function processScripts(
+  document: CheerioAPI,
+  failures: string[],
+  skippedExternalResources: string[],
+  options: SubresourceIntegrityOptions,
+): Promise<void> {
+  const scripts = document('script[src]').toArray();
+  await Promise.all(
+    scripts.map(async (element) => {
+      const script = document(element);
+      const src = script.attr('src');
+      if (!src || script.attr('integrity')) {
+        return;
+      }
+
+      if (!isExternal(src)) {
+        return;
+      }
+
+      if (!options.allowExternalFetch) {
+        skippedExternalResources.push(src);
+        return;
+      }
+
+      const sri = await fetchIntegrity(src, options.fetcher ?? fetch);
+      if (!sri) {
+        failures.push(src);
+        return;
+      }
+
+      script.attr('integrity', sri);
+      if (!script.attr('crossorigin')) {
+        script.attr('crossorigin', 'anonymous');
+      }
+    }),
+  );
 }
 
-async function processStylesheets(document: CheerioAPI, failures: string[]): Promise<void> {
-    const links = document('link[rel="stylesheet"][href]').toArray();
-    await Promise.all(links.map(async (element) => {
-        const link = document(element);
-        const href = link.attr('href');
-        if (!href || !isExternal(href) || link.attr('integrity')) {
-            return;
-        }
-
-        const sri = await fetchIntegrity(href);
-        if (!sri) {
-            failures.push(href);
-            return;
-        }
-
-        link.attr('integrity', sri);
-        if (!link.attr('crossorigin')) {
-            link.attr('crossorigin', 'anonymous');
-        }
-    }));
+async function processStylesheets(
+  document: CheerioAPI,
+  failures: string[],
+  skippedExternalResources: string[],
+  options: SubresourceIntegrityOptions,
+): Promise<void> {
+  const links = document('link[rel="stylesheet"][href]').toArray();
+  await Promise.all(
+    links.map(async (element) => {
+      const link = document(element);
+      const href = link.attr('href');
+      if (!href || link.attr('integrity')) {
+        return;
+      }
+
+      if (!isExternal(href)) {
+        return;
+      }
+
+      if (!options.allowExternalFetch) {
+        skippedExternalResources.push(href);
+        return;
+      }
+
+      const sri = await fetchIntegrity(href, options.fetcher ?? fetch);
+      if (!sri) {
+        failures.push(href);
+        return;
+      }
+
+      link.attr('integrity', sri);
+      if (!link.attr('crossorigin')) {
+        link.attr('crossorigin', 'anonymous');
+      }
+    }),
+  );
 }
 
 function isExternal(url: string): boolean {
-    return url.startsWith('http://') || url.startsWith('https://') || url.startsWith('//');
+  return url.startsWith('http://') || url.startsWith('https://') || url.startsWith('//');
 }
 
-async function fetchIntegrity(url: string): Promise<string | null> {
+async function fetchIntegrity(url: string, fetcher: typeof fetch): Promise<string | null> {
+  try {
+    const normalizedUrl = url.startsWith('//') ? `https:${url}` : url;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
     try {
-        const normalizedUrl = url.startsWith('//') ? `https:${url}` : url;
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
-        try {
-            const response = await fetch(normalizedUrl, { signal: controller.signal });
-            if (!response.ok) {
-                return null;
-            }
-            const arrayBuffer = await response.arrayBuffer();
-            const hash = createHash('sha384').update(Buffer.from(arrayBuffer)).digest('base64');
-            return `sha384-${hash}`;
-        } finally {
-            clearTimeout(timeout);
-        }
-    } catch {
+      const response = await fetcher(normalizedUrl, { signal: controller.signal });
+      if (!response.ok) {
         return null;
+      }
+      const arrayBuffer = await response.arrayBuffer();
+      const hash = new Bun.CryptoHasher('sha384').update(Buffer.from(arrayBuffer)).digest('base64');
+      return `sha384-${hash}`;
+    } finally {
+      clearTimeout(timeout);
     }
+  } catch {
+    return null;
+  }
 }

package/src/html/lazyLoad.ts

@@ -1,30 +1,33 @@
 import type { CheerioAPI } from 'cheerio';
 
 interface LazyOptions {
-    readonly skip: number;
+  readonly skip: number;
 }
 
 const DEFAULT_OPTIONS: LazyOptions = {
-    skip: 1
+  skip: 1,
 };
 
-export function applyLazyLoading(document: CheerioAPI, options: LazyOptions = DEFAULT_OPTIONS): void {
-    const { skip } = options;
-    let index = 0;
-    document('img').each((_i, element) => {
-        const img = document(element);
-        if (img.attr('loading')) {
-            return;
-        }
+export function applyLazyLoading(
+  document: CheerioAPI,
+  options: LazyOptions = DEFAULT_OPTIONS,
+): void {
+  const { skip } = options;
+  let index = 0;
+  document('img').each((_i, element) => {
+    const img = document(element);
+    if (img.attr('loading')) {
+      return;
+    }
 
-        index += 1;
-        if (index <= skip) {
-            return;
-        }
+    index += 1;
+    if (index <= skip) {
+      return;
+    }
 
-        img.attr('loading', 'lazy');
-        if (!img.attr('fetchpriority')) {
-            img.attr('fetchpriority', 'low');
-        }
-    });
+    img.attr('loading', 'lazy');
+    if (!img.attr('fetchpriority')) {
+      img.attr('fetchpriority', 'low');
+    }
+  });
 }

package/src/html/pageScaffold.ts

@@ -1,44 +1,53 @@
 import path from 'node:path';
-import { FOLDERS, FILES, EXTENSIONS } from '../core/constants.js';
+import { FILES, EXTENSIONS } from '../core/constants.js';
 import { ensureDir, pathExists, writeFile } from '../utils/fs.js';
 
 export interface PageScaffoldOptions {
-    readonly workspaceRoot: string;
-    readonly pageName: string;
-    readonly mode?: 'standard' | 'ssg';
-    readonly paths: {
-        readonly pages: string;
-        readonly app: string;
-    };
+  readonly workspaceRoot: string;
+  readonly pageName: string;
+  readonly mode?: 'standard' | 'ssg';
+  readonly paths: {
+    readonly pages: string;
+    readonly app: string;
+  };
 }
 
 export async function createPageScaffold(options: PageScaffoldOptions): Promise<void> {
-    const pageDir = path.join(options.paths.pages, options.pageName);
-    if (await pathExists(pageDir)) {
-        throw new Error(`Page '${options.pageName}' already exists.`);
-    }
+  const pageDir = path.join(options.paths.pages, options.pageName);
+  if (await pathExists(pageDir)) {
+    throw new Error(`Page '${options.pageName}' already exists.`);
+  }
 
-    await ensureDir(pageDir);
+  await ensureDir(pageDir);
 
-    const mode = options.mode ?? 'standard';
-    const writes: Promise<void>[] = [
-        writeFile(path.join(pageDir, `${FILES.index}${EXTENSIONS.html}`), buildHtmlTemplate(options.pageName, mode)),
-        writeFile(path.join(pageDir, `${FILES.index}${EXTENSIONS.css}`), buildCssTemplate(options.pageName))
-    ];
+  const mode = options.mode ?? 'standard';
+  const writes: Promise<void>[] = [
+    writeFile(
+      path.join(pageDir, `${FILES.index}${EXTENSIONS.html}`),
+      buildHtmlTemplate(options.pageName, mode),
+    ),
+    writeFile(
+      path.join(pageDir, `${FILES.index}${EXTENSIONS.css}`),
+      buildCssTemplate(options.pageName),
+    ),
+  ];
 
-    if (mode === 'standard') {
-        writes.push(writeFile(path.join(pageDir, `${FILES.index}${EXTENSIONS.ts}`), buildScriptTemplate()));
-    }
+  if (mode === 'standard') {
+    writes.push(
+      writeFile(path.join(pageDir, `${FILES.index}${EXTENSIONS.ts}`), buildScriptTemplate()),
+    );
+  }
 
-    await Promise.all(writes);
+  await Promise.all(writes);
 }
 
 function buildHtmlTemplate(pageName: string, mode: 'standard' | 'ssg'): string {
-    const script = mode === 'standard'
-        ? `    <script type="module" src="${FILES.index}${EXTENSIONS.js}" async></script>`
-        : `    <!-- Add ${FILES.index}${EXTENSIONS.ts} to enable JS on this page. -->`;
+  const script =
+    mode === 'standard'
+      ? `    <script type="module" src="${FILES.index}${EXTENSIONS.js}" async></script>`
+      : `    <!-- Add ${FILES.index}${EXTENSIONS.ts} to enable JS on this page. -->`;
 
-    return `<head>
+  return `<head>
     <meta charset="utf-8">
     <title>${pageName}</title>
     <link rel="stylesheet" href="${FILES.index}${EXTENSIONS.css}">
@@ -54,7 +63,7 @@ ${script}
 }
 
 function buildCssTemplate(pageName: string): string {
-    return `/* ${pageName} Page Styles */
+  return `/* ${pageName} Page Styles */
 @import "@app/app.css";
 
 /* Add your page-specific styles here */
@@ -62,7 +71,7 @@ function buildCssTemplate(pageName: string): string {
 }
 
 function buildScriptTemplate(): string {
-    return `// Page entry point
+  return `// Page entry point
 import '../../app/app';
 
 // Add page-specific logic here

package/src/html/resourceHints.ts

@@ -2,90 +2,99 @@ import type { CheerioAPI } from 'cheerio';
 import { resolvePageHtmlUrl } from '../utils/pagePaths.js';
 
 export interface ResourceHintResult {
-    readonly added: number;
-    readonly candidates: string[];
-    readonly missingHead: boolean;
+  readonly added: number;
+  readonly candidates: string[];
+  readonly missingHead: boolean;
 }
 
 export function injectResourceHints(
-    document: CheerioAPI,
-    currentPage: string,
-    pagesUrlPrefix: string,
-    useRootIndex: boolean
+  document: CheerioAPI,
+  currentPage: string,
+  pagesUrlPrefix: string,
+  useRootIndex: boolean,
 ): ResourceHintResult {
-    const head = document('head').first();
-    const pages = [...collectInternalPages(document, currentPage, pagesUrlPrefix)];
-
-    if (head.length === 0) {
-        return {
-            added: 0,
-            candidates: pages,
-            missingHead: pages.length > 0
-        };
-    }
-
-    if (pages.length === 0) {
-        return { added: 0, candidates: [], missingHead: false };
-    }
-
-    for (const page of pages) {
-        const href = resolvePageHtmlUrl(pagesUrlPrefix, page, useRootIndex);
-        head.append(`\n<link rel="prefetch" href="${href}" as="document">`);
-    }
-
-    return { added: pages.length, candidates: pages, missingHead: false };
+  const head = document('head').first();
+  const pages = [...collectInternalPages(document, currentPage, pagesUrlPrefix)];
+
+  if (head.length === 0) {
+    return {
+      added: 0,
+      candidates: pages,
+      missingHead: pages.length > 0,
+    };
+  }
+
+  if (pages.length === 0) {
+    return { added: 0, candidates: [], missingHead: false };
+  }
+
+  for (const page of pages) {
+    const href = resolvePageHtmlUrl(pagesUrlPrefix, page, useRootIndex);
+    head.append(`\n<link rel="prefetch" href="${href}" as="document">`);
+  }
+
+  return { added: pages.length, candidates: pages, missingHead: false };
 }
 
-function collectInternalPages(document: CheerioAPI, currentPage: string, pagesUrlPrefix: string): Set<string> {
-    const pages = new Set<string>();
-    document('a[href]').each((_index, element) => {
-        const href = document(element).attr('href');
-        const pageName = normalizePageName(href, pagesUrlPrefix);
-        if (!pageName || pageName === currentPage) {
-            return;
-        }
-        pages.add(pageName);
-    });
-    return pages;
+function collectInternalPages(
+  document: CheerioAPI,
+  currentPage: string,
+  pagesUrlPrefix: string,
+): Set<string> {
+  const pages = new Set<string>();
+  document('a[href]').each((_index, element) => {
+    const href = document(element).attr('href');
+    const pageName = normalizePageName(href, pagesUrlPrefix);
+    if (!pageName || pageName === currentPage) {
+      return;
+    }
+    pages.add(pageName);
+  });
+  return pages;
 }
 
 function normalizePageName(href: string | undefined, pagesUrlPrefix: string): string | null {
-    if (!href || href.length === 0) {
-        return null;
-    }
-
-    const lower = href.toLowerCase();
-    if (lower.startsWith('http://') || lower.startsWith('https://') || lower.startsWith('mailto:') || lower.startsWith('#')) {
-        return null;
-    }
-
-    let path = href.split('#')[0]?.split('?')[0] ?? '';
-    if (path.length === 0) {
-        return null;
-    }
-
-    if (path.startsWith('/')) {
-        path = path.slice(1);
-    }
-
-    const prefix = trimSlashes(pagesUrlPrefix);
-    if (prefix && path.startsWith(`${prefix}/`)) {
-        path = path.slice(prefix.length + 1);
-    }
-
-    if (path.endsWith('/')) {
-        path = path.slice(0, -1);
-    }
-
-    const segments = path.split('/');
-    const candidate = segments[0];
-    if (!candidate) {
-        return null;
-    }
-
-    return candidate;
+  if (!href || href.length === 0) {
+    return null;
+  }
+
+  const lower = href.toLowerCase();
+  if (
+    lower.startsWith('http://') ||
+    lower.startsWith('https://') ||
+    lower.startsWith('mailto:') ||
+    lower.startsWith('#')
+  ) {
+    return null;
+  }
+
+  let path = href.split('#')[0]?.split('?')[0] ?? '';
+  if (path.length === 0) {
+    return null;
+  }
+
+  if (path.startsWith('/')) {
+    path = path.slice(1);
+  }
+
+  const prefix = trimSlashes(pagesUrlPrefix);
+  if (prefix && path.startsWith(`${prefix}/`)) {
+    path = path.slice(prefix.length + 1);
+  }
+
+  if (path.endsWith('/')) {
+    path = path.slice(0, -1);
+  }
+
+  const segments = path.split('/');
+  const candidate = segments[0];
+  if (!candidate) {
+    return null;
+  }
+
+  return candidate;
 }
 
 function trimSlashes(value: string): string {
-    return value.replace(/^\/+|\/+$/g, '');
+  return value.replace(/^\/+|\/+$/g, '');
 }

package/src/index.ts

@@ -1,5 +1,7 @@
 export * from './operations.js';
+export * from './inspect.js';
 export * from './config/manifest.js';
 export * from './config/schema.js';
+export * from './runtime/index.js';
 export * from './types.js';
 export { frontendProvider } from './provider.js';