@webstir-io/webstir-frontend 0.1.40 → 0.1.41

package/src/inspect.ts

@@ -0,0 +1,158 @@
+import path from 'node:path';
+
+import { FILES, FILE_NAMES } from './core/constants.js';
+import { getPageDirectories } from './core/pages.js';
+import { buildConfig } from './config/workspace.js';
+import type {
+  FrontendWorkspaceAppShellInspect,
+  FrontendWorkspaceContentInspect,
+  FrontendWorkspaceInspectResult,
+  FrontendWorkspaceKnownEnableFlags,
+  FrontendWorkspacePackageInspect,
+  FrontendWorkspacePageInspect,
+} from './types.js';
+import { pathExists, readJson } from './utils/fs.js';
+
+interface WorkspacePackageJson {
+  readonly webstir?: {
+    readonly mode?: string;
+    readonly enable?: Record<string, unknown>;
+  };
+}
+
+const PAGE_SCRIPT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'] as const;
+
+export async function inspectFrontendWorkspace(
+  workspaceRoot: string,
+): Promise<FrontendWorkspaceInspectResult> {
+  const config = buildConfig(workspaceRoot);
+  const packageJson = await readWorkspacePackageInspect(workspaceRoot);
+  const appShell = await inspectAppShell(config.paths.src.app);
+  const pages = await inspectPages(config.paths.src.pages);
+  const content = await inspectContent(config.paths.src.content);
+
+  return {
+    workspaceRoot,
+    config,
+    packageJson,
+    appShell,
+    pages,
+    content,
+  };
+}
+
+async function readWorkspacePackageInspect(
+  workspaceRoot: string,
+): Promise<FrontendWorkspacePackageInspect> {
+  const packagePath = path.join(workspaceRoot, FILES.packageJson);
+  const pkg = await readJson<WorkspacePackageJson>(packagePath);
+  const enable = pkg?.webstir?.enable;
+
+  return {
+    path: packagePath,
+    exists: pkg !== null,
+    mode: pkg?.webstir?.mode,
+    enable: {
+      raw: enable,
+      known: normalizeKnownEnableFlags(enable),
+    },
+  };
+}
+
+async function inspectAppShell(appRoot: string): Promise<FrontendWorkspaceAppShellInspect> {
+  const templatePath = path.join(appRoot, FILE_NAMES.htmlAppTemplate);
+  const stylesheetPath = path.join(appRoot, 'app.css');
+  const scriptPath = await resolveFirstExistingPath(appRoot, 'app', PAGE_SCRIPT_EXTENSIONS);
+
+  const [exists, templateExists, stylesheetExists, scriptExists] = await Promise.all([
+    pathExists(appRoot),
+    pathExists(templatePath),
+    pathExists(stylesheetPath),
+    pathExists(scriptPath),
+  ]);
+
+  return {
+    root: appRoot,
+    exists,
+    templatePath,
+    templateExists,
+    stylesheetPath,
+    stylesheetExists,
+    scriptPath,
+    scriptExists,
+  };
+}
+
+async function inspectPages(pagesRoot: string): Promise<readonly FrontendWorkspacePageInspect[]> {
+  const pages = await getPageDirectories(pagesRoot);
+  return await Promise.all(
+    pages.map(async (page) => {
+      const htmlPath = path.join(page.directory, FILES.indexHtml);
+      const stylesheetPath = path.join(page.directory, `${FILES.index}.css`);
+      const scriptPath = await resolveFirstExistingPath(
+        page.directory,
+        FILES.index,
+        PAGE_SCRIPT_EXTENSIONS,
+      );
+
+      const [htmlExists, stylesheetExists, scriptExists] = await Promise.all([
+        pathExists(htmlPath),
+        pathExists(stylesheetPath),
+        pathExists(scriptPath),
+      ]);
+
+      return {
+        name: page.name,
+        directory: page.directory,
+        htmlPath,
+        htmlExists,
+        stylesheetPath,
+        stylesheetExists,
+        scriptPath,
+        scriptExists,
+      };
+    }),
+  );
+}
+
+async function inspectContent(contentRoot: string): Promise<FrontendWorkspaceContentInspect> {
+  const sidebarOverridePath = path.join(contentRoot, '_sidebar.json');
+  const [exists, sidebarOverrideExists] = await Promise.all([
+    pathExists(contentRoot),
+    pathExists(sidebarOverridePath),
+  ]);
+
+  return {
+    root: contentRoot,
+    exists,
+    sidebarOverridePath,
+    sidebarOverrideExists,
+  };
+}
+
+async function resolveFirstExistingPath(
+  root: string,
+  baseName: string,
+  extensions: readonly string[],
+): Promise<string> {
+  for (const extension of extensions) {
+    const candidate = path.join(root, `${baseName}${extension}`);
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+
+  return path.join(root, `${baseName}${extensions[0] ?? ''}`);
+}
+
+function normalizeKnownEnableFlags(
+  value: Record<string, unknown> | undefined,
+): FrontendWorkspaceKnownEnableFlags {
+  return {
+    spa: value?.spa === true,
+    clientNav: value?.clientNav === true,
+    backend: value?.backend === true,
+    search: value?.search === true,
+    contentNav: value?.contentNav === true,
+  };
+}

package/src/modes/ssg/metadata.ts

@@ -3,61 +3,63 @@ import { readJson, writeJson } from '../../utils/fs.js';
 import type { WorkspaceModuleView, WorkspacePackageJson } from '../../config/workspaceManifest.js';
 
 export interface SsgViewMetadataOptions {
-    readonly workspaceRoot: string;
-    readonly pageName: string;
+  readonly workspaceRoot: string;
+  readonly pageName: string;
 }
 
 export async function ensureSsgViewMetadataForPage(options: SsgViewMetadataOptions): Promise<void> {
-    const pkgPath = path.join(options.workspaceRoot, 'package.json');
-    const pkg = (await readJson<WorkspacePackageJson>(pkgPath)) ?? {};
-    const workspaceMode = pkg.webstir?.mode;
-    const isSsgWorkspace = typeof workspaceMode === 'string' && workspaceMode.toLowerCase() === 'ssg';
-    if (isSsgWorkspace) {
-        return;
-    }
-
-    const webstir = pkg.webstir ?? {};
-    const moduleConfig = webstir.moduleManifest ?? {};
-    const existingViews = Array.isArray(moduleConfig.views) ? [...moduleConfig.views] : [];
-
-    const pageName = options.pageName;
-    const isHome = pageName === 'home';
-    const viewName = `${capitalize(pageName)}View`;
-    const viewPath = isHome ? '/' : `/${pageName}`;
-
-    const existingIndex = existingViews.findIndex((view) => view?.name === viewName || view?.path === viewPath);
-    const existing = existingIndex >= 0 ? (existingViews[existingIndex] ?? {}) : {};
-    const nextView: WorkspaceModuleView = {
-        ...existing,
-        name: viewName,
-        path: viewPath,
-        renderMode: 'ssg',
-        staticPaths: [viewPath]
-    };
-
-    if (existingIndex >= 0) {
-        existingViews[existingIndex] = nextView;
-    } else {
-        existingViews.push(nextView);
-    }
-
-    const nextPkg: WorkspacePackageJson = {
-        ...pkg,
-        webstir: {
-            ...webstir,
-            moduleManifest: {
-                ...moduleConfig,
-                views: existingViews
-            }
-        }
-    };
-
-    await writeJson(pkgPath, nextPkg);
+  const pkgPath = path.join(options.workspaceRoot, 'package.json');
+  const pkg = (await readJson<WorkspacePackageJson>(pkgPath)) ?? {};
+  const workspaceMode = pkg.webstir?.mode;
+  const isSsgWorkspace = typeof workspaceMode === 'string' && workspaceMode.toLowerCase() === 'ssg';
+  if (isSsgWorkspace) {
+    return;
+  }
+
+  const webstir = pkg.webstir ?? {};
+  const moduleConfig = webstir.moduleManifest ?? {};
+  const existingViews = Array.isArray(moduleConfig.views) ? [...moduleConfig.views] : [];
+
+  const pageName = options.pageName;
+  const isHome = pageName === 'home';
+  const viewName = `${capitalize(pageName)}View`;
+  const viewPath = isHome ? '/' : `/${pageName}`;
+
+  const existingIndex = existingViews.findIndex(
+    (view) => view?.name === viewName || view?.path === viewPath,
+  );
+  const existing = existingIndex >= 0 ? (existingViews[existingIndex] ?? {}) : {};
+  const nextView: WorkspaceModuleView = {
+    ...existing,
+    name: viewName,
+    path: viewPath,
+    renderMode: 'ssg',
+    staticPaths: [viewPath],
+  };
+
+  if (existingIndex >= 0) {
+    existingViews[existingIndex] = nextView;
+  } else {
+    existingViews.push(nextView);
+  }
+
+  const nextPkg: WorkspacePackageJson = {
+    ...pkg,
+    webstir: {
+      ...webstir,
+      moduleManifest: {
+        ...moduleConfig,
+        views: existingViews,
+      },
+    },
+  };
+
+  await writeJson(pkgPath, nextPkg);
 }
 
 function capitalize(value: string): string {
-    if (!value) {
-        return value;
-    }
-    return value.charAt(0).toUpperCase() + value.slice(1);
+  if (!value) {
+    return value;
+  }
+  return value.charAt(0).toUpperCase() + value.slice(1);
 }

package/src/modes/ssg/routing.ts

@@ -1,230 +1,230 @@
 import path from 'node:path';
-import { glob } from 'glob';
 import { FOLDERS, FILES } from '../../core/constants.js';
 import type { FrontendConfig } from '../../types.js';
 import { copy, ensureDir, pathExists, readJson } from '../../utils/fs.js';
+import { scanGlob } from '../../utils/glob.js';
 import { getPageDirectories } from '../../core/pages.js';
 import { assertNoSsgRoutesInModuleConfig } from './validation.js';
 import type { WorkspaceModuleView, WorkspacePackageJson } from '../../config/workspaceManifest.js';
 import { runSsgSeo } from './seo.js';
 
 export async function applySsgRouting(config: FrontendConfig): Promise<void> {
-    const distRoot = config.paths.dist.frontend;
-    const distPagesRoot = config.paths.dist.pages;
-    const isRootLayout = path.resolve(distRoot) === path.resolve(distPagesRoot);
+  const distRoot = config.paths.dist.frontend;
+  const distPagesRoot = config.paths.dist.pages;
+  const isRootLayout = path.resolve(distRoot) === path.resolve(distPagesRoot);
 
-    const pages = await getPageDirectories(distPagesRoot);
-    const pageIndexMap = new Map<string, string>();
-    const rootIndexPath = path.join(distRoot, FILES.indexHtml);
+  const pages = await getPageDirectories(distPagesRoot);
+  const pageIndexMap = new Map<string, string>();
+  const rootIndexPath = path.join(distRoot, FILES.indexHtml);
 
-    for (const page of pages) {
-        const sourceIndex = path.join(page.directory, FILES.indexHtml);
-        if (!(await pathExists(sourceIndex))) {
-            continue;
-        }
-
-        pageIndexMap.set(page.name, sourceIndex);
+  for (const page of pages) {
+    const sourceIndex = path.join(page.directory, FILES.indexHtml);
+    if (!(await pathExists(sourceIndex))) {
+      continue;
+    }
 
-        if (isRootLayout) {
-            continue;
-        }
+    pageIndexMap.set(page.name, sourceIndex);
 
-        // For each page, create a /<page>/index.html alias to its main HTML file when available.
-        const targetDir = path.join(distRoot, page.name);
-        await ensureDir(targetDir);
-        const targetIndex = path.join(targetDir, FILES.indexHtml);
-        await copy(sourceIndex, targetIndex);
+    if (isRootLayout) {
+      continue;
     }
 
-    if (isRootLayout) {
-        if (await pathExists(rootIndexPath)) {
-            pageIndexMap.set(FOLDERS.home, rootIndexPath);
-        }
-    } else {
-        // Ensure a root index.html that aliases the home page when present.
-        const homeIndexPath = path.join(distPagesRoot, FOLDERS.home, FILES.indexHtml);
-        if (await pathExists(homeIndexPath)) {
-            await ensureDir(path.dirname(rootIndexPath));
-            await copy(homeIndexPath, rootIndexPath);
-        }
+    // For each page, create a /<page>/index.html alias to its main HTML file when available.
+    const targetDir = path.join(distRoot, page.name);
+    await ensureDir(targetDir);
+    const targetIndex = path.join(targetDir, FILES.indexHtml);
+    await copy(sourceIndex, targetIndex);
+  }
 
-        await applyDocsContentAliases(distRoot, distPagesRoot);
+  if (isRootLayout) {
+    if (await pathExists(rootIndexPath)) {
+      pageIndexMap.set(FOLDERS.home, rootIndexPath);
+    }
+  } else {
+    // Ensure a root index.html that aliases the home page when present.
+    const homeIndexPath = path.join(distPagesRoot, FOLDERS.home, FILES.indexHtml);
+    if (await pathExists(homeIndexPath)) {
+      await ensureDir(path.dirname(rootIndexPath));
+      await copy(homeIndexPath, rootIndexPath);
     }
 
-    await applyStaticPathAliases(config, distRoot, distPagesRoot, pageIndexMap);
+    await applyDocsContentAliases(distRoot, distPagesRoot);
+  }
 
-    const siteUrl = await resolveWorkspaceSiteUrl(config.paths.workspace);
-    await runSsgSeo(distRoot, { siteUrl });
+  await applyStaticPathAliases(config, distRoot, distPagesRoot, pageIndexMap);
+
+  const siteUrl = await resolveWorkspaceSiteUrl(config.paths.workspace);
+  await runSsgSeo(distRoot, { siteUrl });
 }
 
 async function applyDocsContentAliases(distRoot: string, distPagesRoot: string): Promise<void> {
-    if (path.resolve(distRoot) === path.resolve(distPagesRoot)) {
-        return;
-    }
+  if (path.resolve(distRoot) === path.resolve(distPagesRoot)) {
+    return;
+  }
 
-    const docsRoot = path.join(distPagesRoot, 'docs');
-    if (!(await pathExists(docsRoot))) {
-        return;
-    }
+  const docsRoot = path.join(distPagesRoot, 'docs');
+  if (!(await pathExists(docsRoot))) {
+    return;
+  }
 
-    const indexes = await glob('docs/**/index.html', {
-        cwd: distPagesRoot,
-        nodir: true
-    });
-
-    for (const relativeIndex of indexes) {
-        const sourceIndex = path.join(distPagesRoot, relativeIndex);
-        if (!(await pathExists(sourceIndex))) {
-            continue;
-        }
+  const indexes = await scanGlob('docs/**/index.html', { cwd: distPagesRoot });
 
-        const targetIndex = path.join(distRoot, relativeIndex);
-        await ensureDir(path.dirname(targetIndex));
-        await copy(sourceIndex, targetIndex);
+  for (const relativeIndex of indexes) {
+    const sourceIndex = path.join(distPagesRoot, relativeIndex);
+    if (!(await pathExists(sourceIndex))) {
+      continue;
     }
+
+    const targetIndex = path.join(distRoot, relativeIndex);
+    await ensureDir(path.dirname(targetIndex));
+    await copy(sourceIndex, targetIndex);
+  }
 }
 
 async function resolveWorkspaceSiteUrl(workspaceRoot: string): Promise<string | undefined> {
-    const fromEnv = process.env.WEBSTIR_SITE_URL?.trim();
-    if (fromEnv) {
-        return fromEnv;
-    }
-
-    const pkgPath = path.join(workspaceRoot, 'package.json');
-    const pkg = await readJson<Record<string, unknown>>(pkgPath);
-    const webstir = pkg?.webstir;
-    if (!webstir || typeof webstir !== 'object') {
-        return undefined;
-    }
-
-    const candidate = (webstir as Record<string, unknown>).siteUrl;
-    return typeof candidate === 'string' && candidate.trim() ? candidate.trim() : undefined;
+  const fromEnv = process.env.WEBSTIR_SITE_URL?.trim();
+  if (fromEnv) {
+    return fromEnv;
+  }
+
+  const pkgPath = path.join(workspaceRoot, 'package.json');
+  const pkg = await readJson<Record<string, unknown>>(pkgPath);
+  const webstir = pkg?.webstir;
+  if (!webstir || typeof webstir !== 'object') {
+    return undefined;
+  }
+
+  const candidate = (webstir as Record<string, unknown>).siteUrl;
+  return typeof candidate === 'string' && candidate.trim() ? candidate.trim() : undefined;
 }
 
 async function applyStaticPathAliases(
-    config: FrontendConfig,
-    distRoot: string,
-    distPagesRoot: string,
-    pageIndexMap: Map<string, string>
+  config: FrontendConfig,
+  distRoot: string,
+  distPagesRoot: string,
+  pageIndexMap: Map<string, string>,
 ): Promise<void> {
-    if (pageIndexMap.size === 0) {
-        return;
-    }
-
-    const workspaceRoot = config.paths.workspace;
-    const pkgPath = path.join(workspaceRoot, 'package.json');
-    const pkg = await readJson<WorkspacePackageJson>(pkgPath);
-    const workspaceMode = pkg?.webstir?.mode;
-    const isSsgWorkspace = typeof workspaceMode === 'string' && workspaceMode.toLowerCase() === 'ssg';
-    const moduleConfig = pkg?.webstir?.moduleManifest;
-    assertNoSsgRoutesInModuleConfig(moduleConfig);
-
-    const views = moduleConfig?.views ?? [];
-    if (views.length === 0) {
-        return;
-    }
-
-    for (const view of views) {
-        const renderMode = view.renderMode ?? (isSsgWorkspace ? 'ssg' : undefined);
-        if (renderMode !== 'ssg') {
+  if (pageIndexMap.size === 0) {
+    return;
+  }
+
+  const workspaceRoot = config.paths.workspace;
+  const pkgPath = path.join(workspaceRoot, 'package.json');
+  const pkg = await readJson<WorkspacePackageJson>(pkgPath);
+  const workspaceMode = pkg?.webstir?.mode;
+  const isSsgWorkspace = typeof workspaceMode === 'string' && workspaceMode.toLowerCase() === 'ssg';
+  const moduleConfig = pkg?.webstir?.moduleManifest;
+  assertNoSsgRoutesInModuleConfig(moduleConfig);
+
+  const views = moduleConfig?.views ?? [];
+  if (views.length === 0) {
+    return;
+  }
+
+  for (const view of views) {
+    const renderMode = view.renderMode ?? (isSsgWorkspace ? 'ssg' : undefined);
+    if (renderMode !== 'ssg') {
+      continue;
+    }
+
+    const paths = getEffectiveStaticPaths(view, isSsgWorkspace);
+    for (const raw of paths) {
+      if (typeof raw !== 'string' || raw.length === 0) {
+        continue;
+      }
+
+      const normalized = normalizeStaticPath(raw);
+      let sourceIndex: string | undefined;
+
+      if (normalized === '/') {
+        sourceIndex = pageIndexMap.get(FOLDERS.home);
+      } else {
+        const relativePath = normalized.replace(/^\/+/, '');
+        const candidate = path.join(distPagesRoot, relativePath, FILES.indexHtml);
+        if (await pathExists(candidate)) {
+          sourceIndex = candidate;
+        } else {
+          const pageName = firstPathSegment(normalized);
+          if (!pageName) {
             continue;
+          }
+          sourceIndex = pageIndexMap.get(pageName);
         }
+      }
 
-        const paths = getEffectiveStaticPaths(view, isSsgWorkspace);
-        for (const raw of paths) {
-            if (typeof raw !== 'string' || raw.length === 0) {
-                continue;
-            }
-
-            const normalized = normalizeStaticPath(raw);
-            let sourceIndex: string | undefined;
-
-            if (normalized === '/') {
-                sourceIndex = pageIndexMap.get(FOLDERS.home);
-            } else {
-                const relativePath = normalized.replace(/^\/+/, '');
-                const candidate = path.join(distPagesRoot, relativePath, FILES.indexHtml);
-                if (await pathExists(candidate)) {
-                    sourceIndex = candidate;
-                } else {
-                    const pageName = firstPathSegment(normalized);
-                    if (!pageName) {
-                        continue;
-                    }
-                    sourceIndex = pageIndexMap.get(pageName);
-                }
-            }
-
-            if (!sourceIndex) {
-                continue;
-            }
-
-            const targetIndex =
-                normalized === '/'
-                    ? path.join(distRoot, FILES.indexHtml)
-                    : path.join(distRoot, normalized.replace(/^\/+/, ''), FILES.indexHtml);
-
-            if (path.resolve(sourceIndex) === path.resolve(targetIndex)) {
-                continue;
-            }
-
-            await ensureDir(path.dirname(targetIndex));
-            await copy(sourceIndex, targetIndex);
-        }
+      if (!sourceIndex) {
+        continue;
+      }
+
+      const targetIndex =
+        normalized === '/'
+          ? path.join(distRoot, FILES.indexHtml)
+          : path.join(distRoot, normalized.replace(/^\/+/, ''), FILES.indexHtml);
+
+      if (path.resolve(sourceIndex) === path.resolve(targetIndex)) {
+        continue;
+      }
+
+      await ensureDir(path.dirname(targetIndex));
+      await copy(sourceIndex, targetIndex);
     }
+  }
 }
 
 function normalizeStaticPath(value: string): string {
-    let s = value.trim();
-    if (!s.startsWith('/')) {
-        s = `/${s}`;
-    }
-    if (s.length > 1 && s.endsWith('/')) {
-        s = s.slice(0, -1);
-    }
-    return s;
+  let s = value.trim();
+  if (!s.startsWith('/')) {
+    s = `/${s}`;
+  }
+  if (s.length > 1 && s.endsWith('/')) {
+    s = s.slice(0, -1);
+  }
+  return s;
 }
 
 function firstPathSegment(pathname: string): string | undefined {
-    const [, segment] = pathname.split('/');
-    if (!segment) {
-        return undefined;
-    }
-    return segment;
+  const [, segment] = pathname.split('/');
+  if (!segment) {
+    return undefined;
+  }
+  return segment;
 }
 
-function getEffectiveStaticPaths(view: WorkspaceModuleView, isSsgWorkspace: boolean): readonly string[] {
-    const explicitPaths = view.staticPaths ?? [];
-    if (explicitPaths.length > 0) {
-        return explicitPaths;
-    }
-
-    if (!isSsgWorkspace) {
-        return [];
-    }
-
-    const candidate = view.path ?? '';
-    if (!isDefaultStaticPathCandidate(candidate)) {
-        return [];
-    }
-
-    return [candidate];
+function getEffectiveStaticPaths(
+  view: WorkspaceModuleView,
+  isSsgWorkspace: boolean,
+): readonly string[] {
+  const explicitPaths = view.staticPaths ?? [];
+  if (explicitPaths.length > 0) {
+    return explicitPaths;
+  }
+
+  if (!isSsgWorkspace) {
+    return [];
+  }
+
+  const candidate = view.path ?? '';
+  if (!isDefaultStaticPathCandidate(candidate)) {
+    return [];
+  }
+
+  return [candidate];
 }
 
 function isDefaultStaticPathCandidate(template: string): boolean {
-    if (typeof template !== 'string') {
-        return false;
-    }
+  if (typeof template !== 'string') {
+    return false;
+  }
 
-    const trimmed = template.trim();
-    if (!trimmed.startsWith('/')) {
-        return false;
-    }
+  const trimmed = template.trim();
+  if (!trimmed.startsWith('/')) {
+    return false;
+  }
 
-    // Avoid treating parameterized or wildcard templates as a single concrete path.
-    if (trimmed.includes(':') || trimmed.includes('*')) {
-        return false;
-    }
+  // Avoid treating parameterized or wildcard templates as a single concrete path.
+  if (trimmed.includes(':') || trimmed.includes('*')) {
+    return false;
+  }
 
-    return true;
+  return true;
 }