@webstir-io/webstir 0.1.0

package/src/repair.ts

@@ -0,0 +1,414 @@
+import path from 'node:path';
+import { chmod, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+import { getBackendScaffoldAssets } from '@webstir-io/webstir-backend';
+import { getModeScaffoldAssets, getRootScaffoldAssets } from './init-assets.ts';
+import {
+  getClientNavAssets,
+  getContentNavAssets,
+  getSearchAssets,
+  getSpaAssets,
+  renderGithubPagesDeployScript,
+  type StaticFeatureAsset,
+} from './enable-assets.ts';
+import { readWorkspaceDescriptor } from './workspace.ts';
+
+interface RepairEnableFlags {
+  spa?: boolean;
+  clientNav?: boolean;
+  search?: boolean;
+  contentNav?: boolean;
+  backend?: boolean;
+  githubPages?: boolean;
+}
+
+interface RepairPackageJson {
+  scripts?: Record<string, unknown>;
+  webstir?: {
+    mode?: string;
+    enable?: RepairEnableFlags;
+  };
+}
+
+export interface RunRepairOptions {
+  readonly workspaceRoot: string;
+  readonly rawArgs: readonly string[];
+}
+
+export interface RepairResult {
+  readonly workspaceRoot: string;
+  readonly mode: string;
+  readonly dryRun: boolean;
+  readonly changes: readonly string[];
+}
+
+export async function runRepair(options: RunRepairOptions): Promise<RepairResult> {
+  const dryRun = options.rawArgs.includes('--dry-run');
+  const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
+  const packageJsonPath = path.join(workspace.root, 'package.json');
+  const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8')) as RepairPackageJson;
+  const enable = packageJson.webstir?.enable ?? {};
+  const changes: string[] = [];
+
+  await restoreScaffoldAssets(workspace.root, getRootScaffoldAssets(), changes, dryRun);
+  await restoreScaffoldAssets(workspace.root, await getModeScaffoldAssets(workspace.mode), changes, dryRun);
+
+  if (enable.spa) {
+    await restoreFeatureAssets(workspace.root, getSpaAssets(), changes, dryRun);
+  }
+  if (enable.clientNav) {
+    await restoreFeatureAssets(workspace.root, getClientNavAssets(), changes, dryRun);
+    await ensureAppImport(workspace.root, './scripts/features/client-nav.js', changes, dryRun);
+  }
+  if (enable.search) {
+    await restoreFeatureAssets(workspace.root, getSearchAssets(), changes, dryRun);
+    await ensureCssLayerIncludes(workspace.root, 'features', changes, dryRun);
+    await ensureAppCssImport(workspace.root, './styles/features/search.css', './styles/components/buttons.css', changes, dryRun);
+    await ensureAppImport(workspace.root, './scripts/features/search.js', changes, dryRun);
+    await ensureHtmlSearchMode(workspace.root, changes, dryRun);
+  }
+  if (enable.contentNav) {
+    await restoreFeatureAssets(workspace.root, getContentNavAssets(), changes, dryRun);
+    await ensureCssLayerIncludes(workspace.root, 'features', changes, dryRun);
+    await ensureAppCssImport(
+      workspace.root,
+      './styles/features/content-nav.css',
+      './styles/components/buttons.css',
+      changes,
+      dryRun
+    );
+    await ensureAppImport(workspace.root, './scripts/features/content-nav.js', changes, dryRun);
+  }
+  if (enable.backend || workspace.mode === 'api' || workspace.mode === 'full') {
+    await restoreBackendAssets(workspace.root, changes, dryRun);
+    await ensureBackendTsReference(workspace.root, changes, dryRun);
+  }
+  if (enable.githubPages) {
+    await ensureGithubPagesDeployScript(workspace.root, changes, dryRun);
+    await ensureDeployScriptEntry(packageJsonPath, changes, dryRun);
+    await ensureFrontendConfigBasePath(workspace.root, changes, dryRun);
+  }
+
+  return {
+    workspaceRoot: workspace.root,
+    mode: workspace.mode,
+    dryRun,
+    changes: uniqueSorted(changes),
+  };
+}
+
+async function restoreScaffoldAssets(
+  workspaceRoot: string,
+  assets: readonly { sourcePath: string; targetPath: string }[],
+  changes: string[],
+  dryRun: boolean
+): Promise<void> {
+  for (const asset of assets) {
+    const targetPath = path.join(workspaceRoot, asset.targetPath);
+    if (existsSync(targetPath)) {
+      continue;
+    }
+
+    if (!dryRun) {
+      await mkdir(path.dirname(targetPath), { recursive: true });
+      await copyFile(asset.sourcePath, targetPath);
+    }
+
+    changes.push(relativeWorkspacePath(workspaceRoot, targetPath));
+  }
+}
+
+async function restoreFeatureAssets(
+  workspaceRoot: string,
+  assets: readonly StaticFeatureAsset[],
+  changes: string[],
+  dryRun: boolean
+): Promise<void> {
+  for (const asset of assets) {
+    const targetPath = path.join(workspaceRoot, asset.targetPath);
+    if (existsSync(targetPath)) {
+      continue;
+    }
+
+    if (!dryRun) {
+      await mkdir(path.dirname(targetPath), { recursive: true });
+      await copyFile(asset.sourcePath, targetPath);
+      if (asset.executable) {
+        await chmod(targetPath, 0o755);
+      }
+    }
+
+    changes.push(relativeWorkspacePath(workspaceRoot, targetPath));
+  }
+}
+
+async function restoreBackendAssets(workspaceRoot: string, changes: string[], dryRun: boolean): Promise<void> {
+  const assets = await getBackendScaffoldAssets();
+  for (const asset of assets) {
+    const targetPath = path.join(workspaceRoot, asset.targetPath);
+    if (existsSync(targetPath)) {
+      continue;
+    }
+
+    if (!dryRun) {
+      await mkdir(path.dirname(targetPath), { recursive: true });
+      await copyFile(asset.sourcePath, targetPath);
+    }
+
+    changes.push(relativeWorkspacePath(workspaceRoot, targetPath));
+  }
+}
+
+async function ensureAppImport(
+  workspaceRoot: string,
+  importPath: string,
+  changes: string[],
+  dryRun: boolean
+): Promise<void> {
+  const appTsPath = path.join(workspaceRoot, 'src', 'frontend', 'app', 'app.ts');
+  if (!existsSync(appTsPath)) {
+    return;
+  }
+
+  const source = await readFile(appTsPath, 'utf8');
+  const updated = ensureSideEffectImport(source, importPath);
+  if (updated === source) {
+    return;
+  }
+
+  if (!dryRun) {
+    await writeFile(appTsPath, updated, 'utf8');
+  }
+  changes.push(relativeWorkspacePath(workspaceRoot, appTsPath));
+}
+
+async function ensureCssLayerIncludes(
+  workspaceRoot: string,
+  layerName: string,
+  changes: string[],
+  dryRun: boolean
+): Promise<void> {
+  const appCssPath = path.join(workspaceRoot, 'src', 'frontend', 'app', 'app.css');
+  if (!existsSync(appCssPath)) {
+    return;
+  }
+
+  const source = await readFile(appCssPath, 'utf8');
+  const updated = ensureLayerIncludes(source, layerName);
+  if (updated === source) {
+    return;
+  }
+
+  if (!dryRun) {
+    await writeFile(appCssPath, updated, 'utf8');
+  }
+  changes.push(relativeWorkspacePath(workspaceRoot, appCssPath));
+}
+
+async function ensureAppCssImport(
+  workspaceRoot: string,
+  importPath: string,
+  insertAfterImportPath: string,
+  changes: string[],
+  dryRun: boolean
+): Promise<void> {
+  const appCssPath = path.join(workspaceRoot, 'src', 'frontend', 'app', 'app.css');
+  if (!existsSync(appCssPath)) {
+    return;
+  }
+
+  const source = await readFile(appCssPath, 'utf8');
+  const updated = ensureImportIncludes(source, importPath, insertAfterImportPath);
+  if (updated === source) {
+    return;
+  }
+
+  if (!dryRun) {
+    await writeFile(appCssPath, updated, 'utf8');
+  }
+  changes.push(relativeWorkspacePath(workspaceRoot, appCssPath));
+}
+
+async function ensureHtmlSearchMode(workspaceRoot: string, changes: string[], dryRun: boolean): Promise<void> {
+  const appHtmlPath = path.join(workspaceRoot, 'src', 'frontend', 'app', 'app.html');
+  if (!existsSync(appHtmlPath)) {
+    return;
+  }
+
+  const source = await readFile(appHtmlPath, 'utf8');
+  if (source.includes('data-webstir-search-styles=')) {
+    return;
+  }
+
+  const updated = source.replace(
+    /<html\b(?![^>]*\bdata-webstir-search-styles=)/i,
+    '<html data-webstir-search-styles="css"'
+  );
+  if (updated === source) {
+    return;
+  }
+
+  if (!dryRun) {
+    await writeFile(appHtmlPath, updated, 'utf8');
+  }
+  changes.push(relativeWorkspacePath(workspaceRoot, appHtmlPath));
+}
+
+async function ensureBackendTsReference(workspaceRoot: string, changes: string[], dryRun: boolean): Promise<void> {
+  const tsconfigPath = path.join(workspaceRoot, 'base.tsconfig.json');
+  if (!existsSync(tsconfigPath)) {
+    return;
+  }
+
+  const source = await readFile(tsconfigPath, 'utf8');
+  const root = JSON.parse(source) as Record<string, unknown>;
+  const references = Array.isArray(root.references) ? [...root.references] : [];
+  const exists = references.some((entry) =>
+    typeof entry === 'object'
+    && entry !== null
+    && (entry as Record<string, unknown>).path === 'src/backend'
+  );
+  if (exists) {
+    return;
+  }
+
+  references.push({ path: 'src/backend' });
+  root.references = references;
+  const updated = `${JSON.stringify(root, null, 2)}\n`;
+
+  if (!dryRun) {
+    await writeFile(tsconfigPath, updated, 'utf8');
+  }
+  changes.push(relativeWorkspacePath(workspaceRoot, tsconfigPath));
+}
+
+async function ensureGithubPagesDeployScript(workspaceRoot: string, changes: string[], dryRun: boolean): Promise<void> {
+  const deployScriptPath = path.join(workspaceRoot, 'utils', 'deploy-gh-pages.sh');
+  if (existsSync(deployScriptPath)) {
+    return;
+  }
+
+  if (!dryRun) {
+    await mkdir(path.dirname(deployScriptPath), { recursive: true });
+    await writeFile(deployScriptPath, renderGithubPagesDeployScript(), 'utf8');
+    await chmod(deployScriptPath, 0o755);
+  }
+  changes.push(relativeWorkspacePath(workspaceRoot, deployScriptPath));
+}
+
+async function ensureDeployScriptEntry(packageJsonPath: string, changes: string[], dryRun: boolean): Promise<void> {
+  const source = await readFile(packageJsonPath, 'utf8');
+  const root = JSON.parse(source) as RepairPackageJson & Record<string, unknown>;
+  const scripts = root.scripts && typeof root.scripts === 'object' ? { ...root.scripts } : {};
+  if (typeof scripts.deploy === 'string') {
+    return;
+  }
+
+  scripts.deploy = 'bash ./utils/deploy-gh-pages.sh';
+  root.scripts = scripts;
+  const updated = `${JSON.stringify(root, null, 2)}\n`;
+
+  if (!dryRun) {
+    await writeFile(packageJsonPath, updated, 'utf8');
+  }
+  changes.push(path.basename(packageJsonPath));
+}
+
+async function ensureFrontendConfigBasePath(workspaceRoot: string, changes: string[], dryRun: boolean): Promise<void> {
+  const configPath = path.join(workspaceRoot, 'src', 'frontend', 'frontend.config.json');
+  let root: Record<string, unknown> = {};
+
+  if (existsSync(configPath)) {
+    try {
+      root = JSON.parse(await readFile(configPath, 'utf8')) as Record<string, unknown>;
+    } catch {
+      root = {};
+    }
+  }
+
+  const publish = asRecord(root.publish);
+  if (typeof publish.basePath === 'string' && publish.basePath.length > 0) {
+    return;
+  }
+
+  publish.basePath = `/${path.basename(workspaceRoot)}`;
+  root.publish = publish;
+  const updated = `${JSON.stringify(root, null, 2)}\n`;
+
+  if (!dryRun) {
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, updated, 'utf8');
+  }
+  changes.push(relativeWorkspacePath(workspaceRoot, configPath));
+}
+
+function ensureSideEffectImport(source: string, importPath: string): string {
+  const escaped = escapeRegExp(importPath);
+  const pattern = new RegExp(`^\\s*import\\s+(['"])${escaped}\\1\\s*;?\\s*$`, 'm');
+  if (pattern.test(source)) {
+    return source;
+  }
+
+  const suffix = source.endsWith('\n') ? '' : '\n';
+  return `${source}${suffix}import "${importPath}";\n`;
+}
+
+function ensureLayerIncludes(css: string, layerName: string): string {
+  const match = css.match(/@layer\s+([^;]+);/);
+  if (!match || match.index === undefined) {
+    return css;
+  }
+
+  const layers = match[1].split(',').map((layer) => layer.trim()).filter(Boolean);
+  if (layers.includes(layerName)) {
+    return css;
+  }
+
+  const updated = [...layers];
+  const utilitiesIndex = updated.indexOf('utilities');
+  const overridesIndex = updated.indexOf('overrides');
+  const insertIndex = utilitiesIndex >= 0 ? utilitiesIndex : overridesIndex >= 0 ? overridesIndex : updated.length;
+  updated.splice(insertIndex, 0, layerName);
+  const replacement = `@layer ${updated.join(', ')};`;
+  return `${css.slice(0, match.index)}${replacement}${css.slice(match.index + match[0].length)}`;
+}
+
+function ensureImportIncludes(css: string, importPath: string, insertAfterImportPath: string): string {
+  if (css.includes(`@import "${importPath}"`) || css.includes(`@import '${importPath}'`)) {
+    return css;
+  }
+
+  const doubleNeedle = `@import "${insertAfterImportPath}"`;
+  const singleNeedle = `@import '${insertAfterImportPath}'`;
+  let insertAfterIndex = css.indexOf(doubleNeedle);
+  if (insertAfterIndex < 0) {
+    insertAfterIndex = css.indexOf(singleNeedle);
+  }
+
+  if (insertAfterIndex >= 0) {
+    const lineEnd = css.indexOf('\n', insertAfterIndex);
+    const insertAt = lineEnd >= 0 ? lineEnd + 1 : css.length;
+    return `${css.slice(0, insertAt)}@import "${importPath}";\n${css.slice(insertAt)}`;
+  }
+
+  return `${css}\n@import "${importPath}";\n`;
+}
+
+function relativeWorkspacePath(workspaceRoot: string, absolutePath: string): string {
+  return path.relative(workspaceRoot, absolutePath).replaceAll(path.sep, '/');
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? { ...(value as Record<string, unknown>) }
+    : {};
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function uniqueSorted(values: readonly string[]): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}

package/src/runtime.ts

@@ -0,0 +1,48 @@
+import path from 'node:path';
+
+import { packageRoot } from './paths.ts';
+
+export type ModuleRuntimeMode = 'build' | 'publish' | 'test';
+
+export function createWorkspaceRuntimeEnv(
+  workspaceRoot: string,
+  mode: ModuleRuntimeMode,
+  env: Record<string, string | undefined> = process.env
+): Record<string, string | undefined> {
+  const binPaths = [
+    ...collectNodeModuleBins(workspaceRoot),
+    ...collectNodeModuleBins(packageRoot),
+    env.PATH,
+  ].filter(Boolean);
+
+  return {
+    ...env,
+    PATH: binPaths.join(path.delimiter),
+    WEBSTIR_MODULE_MODE: mode,
+  };
+}
+
+export function resolveRuntimeCommand(): string {
+  if (typeof process.versions.bun === 'string') {
+    return process.execPath;
+  }
+
+  return 'bun';
+}
+
+function collectNodeModuleBins(startPath: string): string[] {
+  const paths: string[] = [];
+  let current = path.resolve(startPath);
+
+  while (true) {
+    paths.push(path.join(current, 'node_modules', '.bin'));
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+
+    current = parent;
+  }
+
+  return paths;
+}

package/src/smoke.ts

@@ -0,0 +1,161 @@
+import os from 'node:os';
+import path from 'node:path';
+import { cp, mkdtemp, rm } from 'node:fs/promises';
+
+import type { WorkspaceDescriptor } from './types.ts';
+
+import { runBackendInspect, type BackendInspectResult } from './backend-inspect.ts';
+import { monorepoRoot } from './paths.ts';
+import { runBuild, type RunBuildOptions } from './build.ts';
+import { scaffoldWorkspace } from './init.ts';
+import { runPublish } from './publish.ts';
+import { runTest, type TestCommandResult } from './test.ts';
+import { readWorkspaceDescriptor } from './workspace.ts';
+
+export interface RunSmokeOptions {
+  readonly workspaceRoot?: string;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface SmokePhaseResult {
+  readonly name: 'build' | 'test' | 'publish' | 'backend-inspect';
+  readonly detail: string;
+}
+
+export interface SmokeResult {
+  readonly workspace: WorkspaceDescriptor;
+  readonly phases: readonly SmokePhaseResult[];
+  readonly usedTempWorkspace: boolean;
+  readonly source?: string;
+}
+
+export async function runSmoke(options: RunSmokeOptions = {}): Promise<SmokeResult> {
+  const prepared = await prepareWorkspace(options.workspaceRoot);
+
+  try {
+    const workspace = await readWorkspaceDescriptor(prepared.workspaceRoot);
+    const env = createSmokeEnv(workspace.root, options.env);
+    const phases: SmokePhaseResult[] = [];
+
+    const buildResult = await runBuild({
+      workspaceRoot: workspace.root,
+      env,
+    } satisfies RunBuildOptions);
+    phases.push({
+      name: 'build',
+      detail: formatBuildDetail(buildResult),
+    });
+
+    const testResult = await runTest({
+      workspaceRoot: workspace.root,
+      rawArgs: [],
+      env,
+    });
+    if (testResult.hadFailures) {
+      throw new Error('Smoke test phase reported failures.');
+    }
+    phases.push({
+      name: 'test',
+      detail: formatTestDetail(testResult),
+    });
+
+    const publishResult = await runPublish({
+      workspaceRoot: workspace.root,
+      env,
+    });
+    phases.push({
+      name: 'publish',
+      detail: formatBuildDetail(publishResult),
+    });
+
+    if (workspace.mode === 'api' || workspace.mode === 'full') {
+      const backendInspect = await runBackendInspect({
+        workspaceRoot: workspace.root,
+        env,
+      });
+      phases.push({
+        name: 'backend-inspect',
+        detail: formatBackendInspectDetail(backendInspect),
+      });
+    }
+
+    return {
+      workspace,
+      phases,
+      usedTempWorkspace: prepared.usedTempWorkspace,
+      source: prepared.source,
+    };
+  } finally {
+    if (prepared.cleanupRoot) {
+      await rm(prepared.cleanupRoot, { recursive: true, force: true });
+    }
+  }
+}
+
+function createSmokeEnv(
+  workspaceRoot: string,
+  env: Record<string, string | undefined> = process.env
+): Record<string, string | undefined> {
+  if (env.WEBSTIR_BACKEND_TYPECHECK) {
+    return env;
+  }
+
+  const relativeToRepo = monorepoRoot ? path.relative(monorepoRoot, workspaceRoot) : '../external';
+  const isExternalWorkspace = !monorepoRoot || relativeToRepo.startsWith('..') || path.isAbsolute(relativeToRepo);
+  if (!isExternalWorkspace) {
+    return env;
+  }
+
+  return {
+    ...env,
+    WEBSTIR_BACKEND_TYPECHECK: 'skip',
+  };
+}
+
+async function prepareWorkspace(workspaceRoot?: string): Promise<{
+  readonly workspaceRoot: string;
+  readonly cleanupRoot?: string;
+  readonly usedTempWorkspace: boolean;
+  readonly source?: string;
+}> {
+  if (workspaceRoot) {
+    return {
+      workspaceRoot: path.resolve(workspaceRoot),
+      usedTempWorkspace: false,
+    };
+  }
+
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'webstir-smoke-'));
+  const tempWorkspace = path.join(tempRoot, 'full');
+  let source: string | undefined;
+
+  if (monorepoRoot) {
+    const sourceRoot = path.join(monorepoRoot, 'examples', 'demos', 'full');
+    await cp(sourceRoot, tempWorkspace, { recursive: true });
+    source = sourceRoot;
+  } else {
+    await scaffoldWorkspace('full', tempWorkspace, { force: true });
+    source = 'built-in full template';
+  }
+
+  return {
+    workspaceRoot: tempWorkspace,
+    cleanupRoot: tempRoot,
+    usedTempWorkspace: true,
+    source,
+  };
+}
+
+function formatBuildDetail(result: Awaited<ReturnType<typeof runBuild>>): string {
+  return result.targets
+    .map((target) => `${target.kind}:${target.result.artifacts.length} artifacts`)
+    .join(', ');
+}
+
+function formatTestDetail(result: TestCommandResult): string {
+  return `${result.summary.passed} passed, ${result.summary.failed} failed`;
+}
+
+function formatBackendInspectDetail(result: BackendInspectResult): string {
+  return `${result.manifest.routes?.length ?? 0} routes, ${result.manifest.jobs?.length ?? 0} jobs`;
+}

package/src/stop-signal.ts

@@ -0,0 +1,26 @@
+export interface StopSignal {
+  readonly promise: Promise<void>;
+  dispose(): void;
+}
+
+export function createStopSignal(): StopSignal {
+  let resolvePromise: (() => void) | undefined;
+  const promise = new Promise<void>((resolve) => {
+    resolvePromise = resolve;
+  });
+
+  const handleSignal = () => {
+    resolvePromise?.();
+  };
+
+  process.on('SIGINT', handleSignal);
+  process.on('SIGTERM', handleSignal);
+
+  return {
+    promise,
+    dispose() {
+      process.off('SIGINT', handleSignal);
+      process.off('SIGTERM', handleSignal);
+    },
+  };
+}