@webstir-io/webstir 0.1.0

package/src/test.ts

@@ -0,0 +1,215 @@
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+
+import type { ModuleManifest } from '@webstir-io/module-contract';
+import type { TestModule, RunnerSummary, TestRunResult, RuntimeFilter } from '@webstir-io/webstir-testing';
+import type { BuildTargetKind, WorkspaceDescriptor } from './types.ts';
+
+import { compileTestModules } from './compile-tests.ts';
+import { loadProvider } from './providers.ts';
+import { createWorkspaceRuntimeEnv } from './runtime.ts';
+import { readWorkspaceDescriptor } from './workspace.ts';
+import {
+  applyRuntimeFilter,
+  describeRuntimeFilter,
+  normalizeRuntimeFilter,
+  createDefaultProviderRegistry,
+  discoverTestManifest,
+} from '@webstir-io/webstir-testing';
+
+export interface RunTestOptions {
+  readonly workspaceRoot: string;
+  readonly rawArgs: readonly string[];
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface TestCommandResult {
+  readonly workspace: WorkspaceDescriptor;
+  readonly runtime: 'all' | 'frontend' | 'backend';
+  readonly builtTargets: readonly BuildTargetKind[];
+  readonly summary: RunnerSummary;
+  readonly filterMessage?: string;
+  readonly hadFailures: boolean;
+}
+
+export async function runTest(options: RunTestOptions): Promise<TestCommandResult> {
+  const runtime = parseRuntimeFlag(options.rawArgs, options.env);
+  const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
+  const builtTargets = selectBuildTargets(workspace.mode, runtime);
+
+  for (const target of builtTargets) {
+    const provider = await loadProvider(target);
+    const result = await provider.build({
+      workspaceRoot: workspace.root,
+      env: createWorkspaceRuntimeEnv(workspace.root, target === 'backend' ? 'test' : 'build', options.env),
+      incremental: false,
+    });
+
+    if (target === 'backend' && result.manifest.module) {
+      await persistBackendManifest(workspace.root, result.manifest.module);
+    }
+  }
+
+  const manifest = await discoverTestManifest(workspace.root);
+  const filteredManifest = applyRuntimeFilter(manifest, runtime);
+  const filterMessage = describeRuntimeFilter(runtime, manifest.modules.length, filteredManifest.modules.length) ?? undefined;
+  await compileTestModules(workspace.root, filteredManifest.modules);
+  const summary = await executeTestRun(filteredManifest.modules, workspace.root);
+
+  return {
+    workspace,
+    runtime: runtime ?? 'all',
+    builtTargets,
+    summary,
+    filterMessage,
+    hadFailures: summary.failed > 0,
+  };
+}
+
+export function formatFailedTests(results: readonly TestRunResult[]): string[] {
+  return results
+    .filter((result) => !result.passed)
+    .map((result) => `${result.file}: ${result.name}${result.message ? ` — ${firstLine(result.message)}` : ''}`);
+}
+
+async function executeTestRun(modules: readonly TestModule[], workspaceRoot: string): Promise<RunnerSummary> {
+  const registry = createDefaultProviderRegistry();
+  const grouped = new Map<TestModule['runtime'], TestModule[]>();
+
+  for (const module of modules) {
+    const list = grouped.get(module.runtime);
+    if (list) {
+      list.push(module);
+    } else {
+      grouped.set(module.runtime, [module]);
+    }
+  }
+
+  let summary = createEmptySummary();
+
+  for (const [runtime, runtimeModules] of grouped) {
+    const provider = registry.get(runtime);
+    if (!provider) {
+      continue;
+    }
+
+    const files = runtimeModules
+      .map((module) => module.compiledPath)
+      .filter((compiledPath): compiledPath is string => typeof compiledPath === 'string');
+    const runtimeSummary = await withRuntimeEnv(runtime, workspaceRoot, async () => await provider.runTests(files));
+    summary = {
+      passed: summary.passed + runtimeSummary.passed,
+      failed: summary.failed + runtimeSummary.failed,
+      total: summary.total + runtimeSummary.total,
+      durationMs: summary.durationMs + runtimeSummary.durationMs,
+      results: [...summary.results, ...runtimeSummary.results],
+    };
+  }
+
+  return summary;
+}
+
+async function withRuntimeEnv<T>(
+  runtime: TestModule['runtime'],
+  workspaceRoot: string,
+  callback: () => Promise<T>
+): Promise<T> {
+  if (runtime !== 'backend') {
+    return await callback();
+  }
+
+  const previous = new Map<string, string | undefined>();
+  const overrides: Record<string, string> = {
+    WEBSTIR_WORKSPACE_ROOT: workspaceRoot,
+    WEBSTIR_BACKEND_BUILD_ROOT: path.join(workspaceRoot, 'build', 'backend'),
+    WEBSTIR_BACKEND_TEST_ENTRY: path.join(workspaceRoot, 'build', 'backend', 'index.js'),
+    WEBSTIR_BACKEND_TEST_MANIFEST: path.join(workspaceRoot, '.webstir', 'backend-manifest.json'),
+  };
+
+  for (const [key, value] of Object.entries(overrides)) {
+    previous.set(key, process.env[key]);
+    process.env[key] = value;
+  }
+
+  try {
+    return await callback();
+  } finally {
+    for (const [key, value] of previous) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  }
+}
+
+function createEmptySummary(): RunnerSummary {
+  return {
+    passed: 0,
+    failed: 0,
+    total: 0,
+    durationMs: 0,
+    results: [],
+  };
+}
+
+function selectBuildTargets(mode: WorkspaceDescriptor['mode'], runtime: RuntimeFilter): BuildTargetKind[] {
+  if (runtime === 'frontend') {
+    if (mode === 'spa' || mode === 'ssg' || mode === 'full') {
+      return ['frontend'];
+    }
+
+    return [];
+  }
+
+  if (runtime === 'backend') {
+    if (mode === 'api' || mode === 'full') {
+      return ['backend'];
+    }
+
+    return [];
+  }
+
+  if (mode === 'spa' || mode === 'ssg') {
+    return ['frontend'];
+  }
+
+  if (mode === 'api') {
+    return ['backend'];
+  }
+
+  return ['frontend', 'backend'];
+}
+
+function parseRuntimeFlag(
+  rawArgs: readonly string[],
+  env: Record<string, string | undefined> = process.env
+): RuntimeFilter {
+  for (let index = 0; index < rawArgs.length; index += 1) {
+    const arg = rawArgs[index];
+    if (arg === '--runtime' || arg === '-r') {
+      return normalizeRuntimeFilter(rawArgs[index + 1] ?? null);
+    }
+
+    if (arg.startsWith('--runtime=')) {
+      return normalizeRuntimeFilter(arg.slice('--runtime='.length));
+    }
+  }
+
+  return normalizeRuntimeFilter(env.WEBSTIR_TEST_RUNTIME);
+}
+
+async function persistBackendManifest(workspaceRoot: string, manifest: ModuleManifest): Promise<void> {
+  const webstirDir = path.join(workspaceRoot, '.webstir');
+  await mkdir(webstirDir, { recursive: true });
+  await writeFile(
+    path.join(webstirDir, 'backend-manifest.json'),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    'utf8'
+  );
+}
+
+function firstLine(message: string): string {
+  return message.split(/\r?\n/, 1)[0] ?? message;
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import type {
+  ModuleBuildResult,
+  ModuleProvider,
+} from '@webstir-io/module-contract';
+
+export const SUPPORTED_WORKSPACE_MODES = ['spa', 'ssg', 'api', 'full'] as const;
+
+export type WorkspaceMode = (typeof SUPPORTED_WORKSPACE_MODES)[number];
+export type CommandMode = 'build' | 'publish';
+export type BuildTargetKind = 'frontend' | 'backend';
+export type BuildProvider = Pick<ModuleProvider, 'build' | 'resolveWorkspace'>;
+
+export interface WorkspaceDescriptor {
+  readonly root: string;
+  readonly name: string;
+  readonly mode: WorkspaceMode;
+}
+
+export interface CommandTargetResult {
+  readonly kind: BuildTargetKind;
+  readonly outputRoot: string;
+  readonly result: ModuleBuildResult;
+}
+
+export interface CommandExecutionResult {
+  readonly mode: CommandMode;
+  readonly workspace: WorkspaceDescriptor;
+  readonly targets: readonly CommandTargetResult[];
+}

package/src/watch-daemon-client.ts

@@ -0,0 +1,171 @@
+import path from 'node:path';
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { createInterface, type Interface as ReadLineInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+
+import { createWorkspaceRuntimeEnv, resolveRuntimeCommand } from './runtime.ts';
+import { parseStructuredDiagnosticLine, type StructuredDiagnosticPayload } from './watch-events.ts';
+import { ensureLocalPackageArtifacts } from './providers.ts';
+
+type WatchDaemonCommand =
+  | { readonly type: 'start' }
+  | { readonly type: 'change'; readonly path: string }
+  | { readonly type: 'reload' }
+  | { readonly type: 'shutdown' };
+
+export interface FrontendWatchDaemonClientOptions {
+  readonly workspaceRoot: string;
+  readonly verbose?: boolean;
+  readonly hmrVerbose?: boolean;
+  readonly env?: Record<string, string | undefined>;
+  readonly onLine?: (line: string) => void;
+  readonly onErrorLine?: (line: string) => void;
+  readonly onDiagnostic?: (payload: StructuredDiagnosticPayload) => void;
+}
+
+export class FrontendWatchDaemonClient {
+  private readonly workspaceRoot: string;
+  private readonly verbose: boolean;
+  private readonly hmrVerbose: boolean;
+  private readonly env?: Record<string, string | undefined>;
+  private readonly onLine?: (line: string) => void;
+  private readonly onErrorLine?: (line: string) => void;
+  private readonly onDiagnostic?: (payload: StructuredDiagnosticPayload) => void;
+  private child?: ChildProcessWithoutNullStreams;
+  private stdoutReader?: ReadLineInterface;
+  private stderrReader?: ReadLineInterface;
+  private exitPromise?: Promise<number | null>;
+  private isStopping = false;
+
+  public constructor(options: FrontendWatchDaemonClientOptions) {
+    this.workspaceRoot = path.resolve(options.workspaceRoot);
+    this.verbose = options.verbose ?? false;
+    this.hmrVerbose = options.hmrVerbose ?? false;
+    this.env = options.env;
+    this.onLine = options.onLine;
+    this.onErrorLine = options.onErrorLine;
+    this.onDiagnostic = options.onDiagnostic;
+  }
+
+  public async start(): Promise<void> {
+    if (this.child) {
+      return;
+    }
+
+    await ensureLocalPackageArtifacts();
+    const frontendCliPath = fileURLToPath(import.meta.resolve('@webstir-io/webstir-frontend/cli'));
+    const args = [
+      frontendCliPath,
+      'watch-daemon',
+      '--workspace',
+      this.workspaceRoot,
+      '--no-auto-start',
+    ];
+
+    if (this.verbose) {
+      args.push('--verbose');
+    }
+
+    if (this.hmrVerbose) {
+      args.push('--hmr-verbose');
+    }
+
+    const child = spawn(resolveRuntimeCommand(), args, {
+      cwd: this.workspaceRoot,
+      env: createWorkspaceRuntimeEnv(this.workspaceRoot, 'build', this.env),
+      stdio: 'pipe',
+    });
+
+    this.child = child;
+    this.exitPromise = new Promise<number | null>((resolve, reject) => {
+      child.once('error', reject);
+      child.once('close', (code) => resolve(code));
+    });
+
+    this.stdoutReader = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    this.stdoutReader.on('line', (line) => {
+      const diagnostic = parseStructuredDiagnosticLine(line);
+      if (diagnostic) {
+        this.onDiagnostic?.(diagnostic);
+        return;
+      }
+
+      this.onLine?.(line);
+    });
+
+    this.stderrReader = createInterface({ input: child.stderr, crlfDelay: Infinity });
+    this.stderrReader.on('line', (line) => {
+      this.onErrorLine?.(line);
+    });
+  }
+
+  public async sendStart(): Promise<void> {
+    await this.send({ type: 'start' });
+  }
+
+  public async sendChange(filePath: string): Promise<void> {
+    await this.send({ type: 'change', path: filePath });
+  }
+
+  public async sendReload(): Promise<void> {
+    await this.send({ type: 'reload' });
+  }
+
+  public async stop(): Promise<number | null> {
+    if (!this.child || !this.exitPromise) {
+      return 0;
+    }
+
+    if (!this.isStopping) {
+      this.isStopping = true;
+      try {
+        await this.send({ type: 'shutdown' });
+      } catch {
+        // Fall through to best-effort teardown.
+      }
+
+      this.child.stdin.end();
+    }
+
+    const code = await this.exitPromise;
+    this.cleanup();
+    return code;
+  }
+
+  public async waitForExit(): Promise<number | null> {
+    if (!this.exitPromise) {
+      throw new Error('Frontend watch daemon has not started.');
+    }
+
+    const code = await this.exitPromise;
+    this.cleanup();
+    return code;
+  }
+
+  private async send(command: WatchDaemonCommand): Promise<void> {
+    if (!this.child || !this.child.stdin.writable) {
+      throw new Error('Frontend watch daemon is not running.');
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      this.child!.stdin.write(`${JSON.stringify(command)}\n`, (error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        resolve();
+      });
+    });
+  }
+
+  private cleanup(): void {
+    this.stdoutReader?.close();
+    this.stderrReader?.close();
+    this.stdoutReader = undefined;
+    this.stderrReader = undefined;
+    this.child = undefined;
+    this.exitPromise = undefined;
+    this.isStopping = false;
+  }
+}

package/src/watch-events.ts

@@ -0,0 +1,195 @@
+export const STRUCTURED_DIAGNOSTIC_PREFIX = 'WEBSTIR_DIAGNOSTIC ';
+
+export type WatchStatus = 'building' | 'success' | 'error' | 'hmr-fallback';
+
+export interface StructuredDiagnosticPayload {
+  readonly type: 'diagnostic';
+  readonly code: string;
+  readonly kind: string;
+  readonly stage: string;
+  readonly severity: 'info' | 'warning' | 'error';
+  readonly message: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface HotUpdateAsset {
+  readonly type: 'js' | 'css';
+  readonly path: string;
+  readonly relativePath: string;
+  readonly url: string;
+}
+
+export interface HotUpdatePayload {
+  readonly requiresReload: boolean;
+  readonly modules: readonly HotUpdateAsset[];
+  readonly styles: readonly HotUpdateAsset[];
+  readonly changedFile?: string;
+  readonly fallbackReasons?: readonly string[];
+  readonly stats?: {
+    readonly hotUpdates: number;
+    readonly reloadFallbacks: number;
+  };
+}
+
+export type WatchAction =
+  | { readonly type: 'status'; readonly status: WatchStatus }
+  | { readonly type: 'hmr'; readonly payload: HotUpdatePayload }
+  | { readonly type: 'reload' };
+
+export function parseStructuredDiagnosticLine(line: string): StructuredDiagnosticPayload | null {
+  if (!line.startsWith(STRUCTURED_DIAGNOSTIC_PREFIX)) {
+    return null;
+  }
+
+  const rawPayload = line.slice(STRUCTURED_DIAGNOSTIC_PREFIX.length);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawPayload);
+  } catch {
+    return null;
+  }
+
+  if (!isStructuredDiagnosticPayload(parsed)) {
+    return null;
+  }
+
+  return parsed;
+}
+
+export function collectWatchActions(payload: StructuredDiagnosticPayload): readonly WatchAction[] {
+  if (isBuildStartDiagnostic(payload.code)) {
+    return [{ type: 'status', status: 'building' }];
+  }
+
+  if (isBuildFailureDiagnostic(payload.code)) {
+    return [{ type: 'status', status: 'error' }];
+  }
+
+  if (payload.code === 'frontend.watch.pipeline.hmrfallback') {
+    return [{ type: 'status', status: 'hmr-fallback' }];
+  }
+
+  if (payload.code !== 'frontend.watch.pipeline.success') {
+    return [];
+  }
+
+  const hotUpdate = readHotUpdatePayload(payload.data);
+  const changedFile = typeof hotUpdate?.changedFile === 'string' ? hotUpdate.changedFile : undefined;
+  if (!hotUpdate || !changedFile) {
+    return [{ type: 'status', status: 'success' }];
+  }
+
+  if (hotUpdate.requiresReload) {
+    return [
+      { type: 'status', status: 'hmr-fallback' },
+      { type: 'reload' },
+    ];
+  }
+
+  if (hotUpdate.modules.length === 0 && hotUpdate.styles.length === 0) {
+    return [{ type: 'status', status: 'success' }];
+  }
+
+  return [
+    { type: 'hmr', payload: hotUpdate },
+    { type: 'status', status: 'success' },
+  ];
+}
+
+function isBuildStartDiagnostic(code: string): boolean {
+  return code === 'frontend.watch.starting' ||
+    code === 'frontend.watch.reload' ||
+    code.endsWith('.build.start');
+}
+
+function isBuildFailureDiagnostic(code: string): boolean {
+  return code === 'frontend.watch.unexpected' ||
+    code === 'frontend.watch.command.failure' ||
+    code.endsWith('.build.failure');
+}
+
+function readHotUpdatePayload(data: Record<string, unknown> | undefined): HotUpdatePayload | null {
+  if (!data) {
+    return null;
+  }
+
+  const candidate = data.hotUpdate;
+  if (typeof candidate !== 'object' || candidate === null) {
+    return null;
+  }
+
+  const payload = candidate as Record<string, unknown>;
+  if (typeof payload.requiresReload !== 'boolean') {
+    return null;
+  }
+
+  return {
+    requiresReload: payload.requiresReload,
+    modules: readAssets(payload.modules),
+    styles: readAssets(payload.styles),
+    changedFile: typeof payload.changedFile === 'string' ? payload.changedFile : undefined,
+    fallbackReasons: Array.isArray(payload.fallbackReasons)
+      ? payload.fallbackReasons.filter((value): value is string => typeof value === 'string')
+      : undefined,
+    stats: readStats(payload.stats),
+  };
+}
+
+function readAssets(value: unknown): readonly HotUpdateAsset[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.flatMap((candidate) => {
+    if (typeof candidate !== 'object' || candidate === null) {
+      return [];
+    }
+
+    const asset = candidate as Record<string, unknown>;
+    if (
+      (asset.type !== 'js' && asset.type !== 'css') ||
+      typeof asset.path !== 'string' ||
+      typeof asset.relativePath !== 'string' ||
+      typeof asset.url !== 'string'
+    ) {
+      return [];
+    }
+
+    return [{
+      type: asset.type,
+      path: asset.path,
+      relativePath: asset.relativePath,
+      url: asset.url,
+    }];
+  });
+}
+
+function readStats(value: unknown): HotUpdatePayload['stats'] | undefined {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+
+  const stats = value as Record<string, unknown>;
+  if (typeof stats.hotUpdates !== 'number' || typeof stats.reloadFallbacks !== 'number') {
+    return undefined;
+  }
+
+  return {
+    hotUpdates: stats.hotUpdates,
+    reloadFallbacks: stats.reloadFallbacks,
+  };
+}
+
+function isStructuredDiagnosticPayload(value: unknown): value is StructuredDiagnosticPayload {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const payload = value as Record<string, unknown>;
+  return payload.type === 'diagnostic' &&
+    typeof payload.code === 'string' &&
+    typeof payload.kind === 'string' &&
+    typeof payload.stage === 'string' &&
+    typeof payload.severity === 'string' &&
+    typeof payload.message === 'string';
+}

package/src/watch.ts

@@ -0,0 +1,66 @@
+import { runApiWatch } from './api-watch.ts';
+import { runFrontendWatch } from './frontend-watch.ts';
+import { runFullWatch } from './full-watch.ts';
+import type { WorkspaceDescriptor } from './types.ts';
+import { readWorkspaceDescriptor } from './workspace.ts';
+
+interface WatchStream {
+  write(message: string): void;
+}
+
+export interface WatchIo {
+  readonly stdout: WatchStream;
+  readonly stderr: WatchStream;
+}
+
+export interface WatchOptions {
+  readonly host?: string;
+  readonly port?: number;
+  readonly verbose?: boolean;
+  readonly hmrVerbose?: boolean;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface RunWatchOptions extends WatchOptions {
+  readonly workspaceRoot: string;
+  readonly io?: WatchIo;
+}
+
+const defaultIo: WatchIo = {
+  stdout: {
+    write(message) {
+      process.stdout.write(message);
+    },
+  },
+  stderr: {
+    write(message) {
+      process.stderr.write(message);
+    },
+  },
+};
+
+export async function runWatch(options: RunWatchOptions): Promise<void> {
+  const io = options.io ?? defaultIo;
+  const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
+
+  switch (workspace.mode) {
+    case 'spa':
+    case 'ssg':
+      await runFrontendWatch(workspace, options, io);
+      return;
+    case 'api':
+      await runApiWatch(workspace, options, io);
+      return;
+    case 'full':
+      await runFullWatch(workspace, options, io);
+      return;
+    default:
+      throwUnsupportedWatchMode(workspace);
+  }
+}
+
+function throwUnsupportedWatchMode(workspace: WorkspaceDescriptor): never {
+  throw new Error(
+    `Watch currently supports spa, ssg, api, and full workspaces only. "${workspace.name}" is ${workspace.mode}.`
+  );
+}