@webstir-io/webstir 0.1.0

package/src/format.ts

@@ -0,0 +1,254 @@
+import type { EnableResult } from './enable.ts';
+import type { InitResult } from './init.ts';
+import type { RefreshResult } from './refresh.ts';
+import type { RepairResult } from './repair.ts';
+import type { BackendInspectResult } from './backend-inspect.ts';
+import type { SmokeResult } from './smoke.ts';
+import type { TestCommandResult } from './test.ts';
+import { formatFailedTests } from './test.ts';
+import type { CommandExecutionResult } from './types.ts';
+
+export function formatBuildSummary(result: CommandExecutionResult): string {
+  return formatExecutionSummary(result);
+}
+
+export function formatPublishSummary(result: CommandExecutionResult): string {
+  return formatExecutionSummary(result);
+}
+
+export function formatEnableSummary(result: EnableResult): string {
+  const lines = [
+    '[webstir] enable complete',
+    `feature: ${result.feature}`,
+    `root: ${result.workspaceRoot}`,
+  ];
+
+  if (result.changes.length === 0) {
+    lines.push('changes: none');
+    return lines.join('\n');
+  }
+
+  lines.push(`changes: ${result.changes.length}`);
+  for (const change of result.changes) {
+    lines.push(`  - ${change}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatInitSummary(result: InitResult): string {
+  return formatWorkspaceMutationSummary('[webstir] init complete', result.mode, result.workspaceRoot, result.changes);
+}
+
+export function formatRefreshSummary(result: RefreshResult): string {
+  return formatWorkspaceMutationSummary('[webstir] refresh complete', result.mode, result.workspaceRoot, result.changes);
+}
+
+export function formatRepairSummary(result: RepairResult): string {
+  const lines = [
+    '[webstir] repair complete',
+    `mode: ${result.mode}`,
+    `root: ${result.workspaceRoot}`,
+    `dry-run: ${result.dryRun ? 'true' : 'false'}`,
+  ];
+
+  if (result.changes.length === 0) {
+    lines.push('changes: none');
+    return lines.join('\n');
+  }
+
+  lines.push(`changes: ${result.changes.length}`);
+  for (const change of result.changes) {
+    lines.push(`  - ${change}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatBackendInspectSummary(result: BackendInspectResult): string {
+  const lines = [
+    '[webstir] backend-inspect complete',
+    `workspace: ${result.workspace.name}`,
+    `mode: ${result.workspace.mode}`,
+    `root: ${result.workspace.root}`,
+    `build: ${result.buildRoot}`,
+    `module: ${result.manifest.name}@${result.manifest.version}`,
+    `capabilities: ${result.manifest.capabilities && result.manifest.capabilities.length > 0 ? result.manifest.capabilities.join(', ') : 'none'}`,
+  ];
+
+  const routes = result.manifest.routes ?? [];
+  lines.push(`routes: ${routes.length}`);
+  for (const route of routes) {
+    lines.push(`  - ${route.method} ${route.path}${route.name ? ` (${route.name})` : ''}`);
+  }
+
+  const jobs = result.manifest.jobs ?? [];
+  lines.push(`jobs: ${jobs.length}`);
+  for (const job of jobs) {
+    const details = [
+      job.schedule ? `schedule: ${job.schedule}` : undefined,
+      'description' in job && typeof (job as { description?: unknown }).description === 'string'
+        ? `description: ${(job as { description?: string }).description}`
+        : undefined,
+      job.priority !== undefined ? `priority: ${String(job.priority)}` : undefined,
+    ].filter(Boolean);
+    lines.push(`  - ${job.name}${details.length > 0 ? ` (${details.join(', ')})` : ''}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatTestSummary(result: TestCommandResult): string {
+  const lines = [
+    '[webstir] test complete',
+    `workspace: ${result.workspace.name}`,
+    `mode: ${result.workspace.mode}`,
+    `root: ${result.workspace.root}`,
+    `runtime: ${result.runtime}`,
+    `build-targets: ${result.builtTargets.length > 0 ? result.builtTargets.join(', ') : 'none'}`,
+  ];
+
+  if (result.filterMessage) {
+    lines.push(`filter: ${result.filterMessage}`);
+  }
+
+  lines.push(`tests: ${result.summary.total}`);
+  lines.push(`passed: ${result.summary.passed}`);
+  lines.push(`failed: ${result.summary.failed}`);
+  lines.push(`durationMs: ${result.summary.durationMs}`);
+
+  const failures = formatFailedTests(result.summary.results);
+  if (failures.length > 0) {
+    lines.push(`failures: ${failures.length}`);
+    for (const failure of failures) {
+      lines.push(`  - ${failure}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function formatSmokeSummary(result: SmokeResult): string {
+  const lines = [
+    '[webstir] smoke complete',
+    `workspace: ${result.workspace.name}`,
+    `mode: ${result.workspace.mode}`,
+    `root: ${result.workspace.root}`,
+    `workspace-source: ${result.usedTempWorkspace ? 'temporary copy' : 'explicit workspace'}`,
+  ];
+
+  if (result.source) {
+    lines.push(`source: ${result.source}`);
+  }
+
+  lines.push(`phases: ${result.phases.length}`);
+  for (const phase of result.phases) {
+    lines.push(`  - ${phase.name}: ${phase.detail}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatAddSummary(
+  header: string,
+  target: string,
+  workspaceRoot: string,
+  changes: readonly string[],
+  note?: string
+): string {
+  const lines = [
+    header,
+    `target: ${target}`,
+    `root: ${workspaceRoot}`,
+  ];
+
+  if (changes.length === 0) {
+    lines.push('changes: none');
+    if (note) {
+      lines.push(`note: ${note}`);
+    }
+    return lines.join('\n');
+  }
+
+  lines.push(`changes: ${changes.length}`);
+  for (const change of changes) {
+    lines.push(`  - ${change}`);
+  }
+
+  if (note) {
+    lines.push(`note: ${note}`);
+  }
+
+  return lines.join('\n');
+}
+
+function formatExecutionSummary(result: CommandExecutionResult): string {
+  const lines = [
+    `[webstir] ${result.mode} complete`,
+    `workspace: ${result.workspace.name}`,
+    `mode: ${result.workspace.mode}`,
+    `root: ${result.workspace.root}`,
+  ];
+
+  for (const target of result.targets) {
+    const diagnostics = summarizeDiagnostics(target.result);
+    lines.push(
+      `${target.kind}: ${target.result.artifacts.length} artifacts, ` +
+        `${target.result.manifest.entryPoints.length} entries, ` +
+        `${target.result.manifest.staticAssets.length} static assets -> ${target.outputRoot}`
+    );
+
+    if (diagnostics.errors > 0 || diagnostics.warnings > 0) {
+      lines.push(
+        `${target.kind}: ${diagnostics.errors} error(s), ${diagnostics.warnings} warning(s), ${diagnostics.info} info`
+      );
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function formatWorkspaceMutationSummary(
+  header: string,
+  mode: string,
+  workspaceRoot: string,
+  changes: readonly string[]
+): string {
+  const lines = [
+    header,
+    `mode: ${mode}`,
+    `root: ${workspaceRoot}`,
+  ];
+
+  if (changes.length === 0) {
+    lines.push('changes: none');
+    return lines.join('\n');
+  }
+
+  lines.push(`changes: ${changes.length}`);
+  for (const change of changes) {
+    lines.push(`  - ${change}`);
+  }
+
+  return lines.join('\n');
+}
+
+function summarizeDiagnostics(result: CommandExecutionResult['targets'][number]['result']) {
+  const counts = {
+    errors: 0,
+    warnings: 0,
+    info: 0,
+  };
+
+  for (const diagnostic of result.manifest.diagnostics) {
+    if (diagnostic.severity === 'error') {
+      counts.errors += 1;
+    } else if (diagnostic.severity === 'warn') {
+      counts.warnings += 1;
+    } else {
+      counts.info += 1;
+    }
+  }
+
+  return counts;
+}

package/src/frontend-watch.ts

@@ -0,0 +1,145 @@
+import path from 'node:path';
+
+import { DevServer, type DevServerAddress } from './dev-server.ts';
+import { createStopSignal } from './stop-signal.ts';
+import { FrontendWatchDaemonClient } from './watch-daemon-client.ts';
+import { collectWatchActions, type StructuredDiagnosticPayload } from './watch-events.ts';
+import type { WorkspaceDescriptor } from './types.ts';
+import type { WatchIo, WatchOptions } from './watch.ts';
+import { WorkspaceWatcher, type WorkspaceWatchEvent } from './workspace-watcher.ts';
+
+export interface FrontendWatchSession {
+  readonly address: DevServerAddress;
+  waitForExit(): Promise<number | null>;
+  stop(): Promise<void>;
+}
+
+interface FrontendWatchSessionOptions extends WatchOptions {
+  readonly server?: DevServer;
+}
+
+export async function runFrontendWatch(
+  workspace: WorkspaceDescriptor,
+  options: WatchOptions,
+  io: WatchIo
+): Promise<void> {
+  const session = await startFrontendWatchSession(workspace, options, io);
+
+  io.stdout.write(
+    `[webstir] watch starting\nworkspace: ${workspace.name}\nmode: ${workspace.mode}\nurl: ${session.address.origin}\n`
+  );
+
+  const stopSignal = createStopSignal();
+
+  try {
+    const daemonExitCode = await Promise.race([
+      session.waitForExit(),
+      stopSignal.promise.then(() => null),
+    ]);
+
+    if (typeof daemonExitCode === 'number' && daemonExitCode !== 0) {
+      throw new Error(`Frontend watch daemon exited with code ${daemonExitCode}.`);
+    }
+  } finally {
+    stopSignal.dispose();
+    await session.stop();
+  }
+}
+
+export async function startFrontendWatchSession(
+  workspace: WorkspaceDescriptor,
+  options: FrontendWatchSessionOptions,
+  io: WatchIo
+): Promise<FrontendWatchSession> {
+  const server = options.server ?? new DevServer({
+    buildRoot: path.join(workspace.root, 'build', 'frontend'),
+    host: options.host,
+    port: options.port,
+  });
+  const ownsServer = options.server === undefined;
+  const address = await server.start();
+
+  let initialBuildReady = false;
+  const daemon = new FrontendWatchDaemonClient({
+    workspaceRoot: workspace.root,
+    verbose: options.verbose,
+    hmrVerbose: options.hmrVerbose,
+    env: options.env,
+    onLine(line) {
+      io.stdout.write(`${line}\n`);
+    },
+    onErrorLine(line) {
+      io.stderr.write(`${line}\n`);
+    },
+    onDiagnostic(payload) {
+      if (!initialBuildReady && payload.code === 'frontend.watch.pipeline.success') {
+        initialBuildReady = true;
+        io.stdout.write(`[webstir] frontend ready at ${address.origin}\n`);
+      }
+
+      void applyDiagnostic(payload, server);
+    },
+  });
+
+  const watcher = new WorkspaceWatcher({
+    workspaceRoot: workspace.root,
+    onEvent(event) {
+      void dispatchWorkspaceEvent(event, daemon);
+    },
+  });
+
+  await daemon.start();
+  await watcher.start();
+  await daemon.sendStart();
+
+  let stopPromise: Promise<void> | null = null;
+
+  return {
+    address,
+    async waitForExit() {
+      return await daemon.waitForExit();
+    },
+    async stop() {
+      stopPromise ??= (async () => {
+        await watcher.stop();
+        await daemon.stop();
+        if (ownsServer) {
+          await server.stop();
+        }
+      })();
+
+      await stopPromise;
+    },
+  };
+}
+
+async function applyDiagnostic(payload: StructuredDiagnosticPayload, server: DevServer): Promise<void> {
+  const actions = collectWatchActions(payload);
+  for (const action of actions) {
+    switch (action.type) {
+      case 'status':
+        await server.publishStatus(action.status);
+        break;
+      case 'hmr':
+        await server.publishHotUpdate(action.payload);
+        break;
+      case 'reload':
+        await server.publishReload();
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+async function dispatchWorkspaceEvent(
+  event: WorkspaceWatchEvent,
+  daemon: FrontendWatchDaemonClient
+): Promise<void> {
+  if (event.type === 'reload') {
+    await daemon.sendReload();
+    return;
+  }
+
+  await daemon.sendChange(event.path);
+}

package/src/full-watch.ts

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { createServer } from 'node:net';
+
+import { startApiWatchSession } from './api-watch.ts';
+import { DevServer } from './dev-server.ts';
+import { startFrontendWatchSession } from './frontend-watch.ts';
+import { createStopSignal } from './stop-signal.ts';
+import type { WorkspaceDescriptor } from './types.ts';
+import type { WatchIo, WatchOptions } from './watch.ts';
+
+export async function runFullWatch(
+  workspace: WorkspaceDescriptor,
+  options: WatchOptions,
+  io: WatchIo
+): Promise<void> {
+  const backendPort = await allocateBackendPort();
+  const apiSession = await startApiWatchSession(workspace, { ...options, port: backendPort }, io);
+  const server = new DevServer({
+    buildRoot: path.join(workspace.root, 'build', 'frontend'),
+    host: options.host,
+    port: options.port,
+    apiProxyOrigin: apiSession.origin,
+  });
+
+  let frontendSession: Awaited<ReturnType<typeof startFrontendWatchSession>> | undefined;
+
+  try {
+    frontendSession = await startFrontendWatchSession(workspace, { ...options, server }, io);
+    io.stdout.write(
+      `[webstir] watch starting\nworkspace: ${workspace.name}\nmode: ${workspace.mode}\nurl: ${frontendSession.address.origin}\napi: ${apiSession.origin}\n`
+    );
+
+    const stopSignal = createStopSignal();
+    try {
+      const daemonExitCode = await Promise.race([
+        frontendSession.waitForExit(),
+        stopSignal.promise.then(() => null),
+      ]);
+
+      if (typeof daemonExitCode === 'number' && daemonExitCode !== 0) {
+        throw new Error(`Frontend watch daemon exited with code ${daemonExitCode}.`);
+      }
+    } finally {
+      stopSignal.dispose();
+    }
+  } finally {
+    if (frontendSession) {
+      await frontendSession.stop();
+    }
+    await server.stop();
+    await apiSession.stop();
+  }
+}
+
+async function allocateBackendPort(): Promise<number> {
+  const server = createServer();
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve());
+  });
+
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Failed to allocate a backend runtime port.');
+  }
+
+  const port = address.port;
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      resolve();
+    });
+  });
+
+  return port;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export * from './add.ts';
+export * from './add-backend.ts';
+export * from './backend-inspect.ts';
+export * from './build-plan.ts';
+export * from './build.ts';
+export * from './dev-server.ts';
+export * from './enable.ts';
+export * from './execute.ts';
+export * from './format.ts';
+export * from './init.ts';
+export * from './publish.ts';
+export * from './repair.ts';
+export * from './refresh.ts';
+export * from './runtime.ts';
+export * from './smoke.ts';
+export * from './test.ts';
+export * from './types.ts';
+export * from './watch-events.ts';
+export * from './watch.ts';
+export * from './workspace.ts';

package/src/init-assets.ts

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { readdir } from 'node:fs/promises';
+
+import { assetsRoot } from './paths.ts';
+import type { WorkspaceMode } from './types.ts';
+
+export interface ScaffoldAsset {
+  readonly sourcePath: string;
+  readonly targetPath: string;
+}
+
+const templatesRoot = path.join(assetsRoot, 'templates');
+const sharedTemplateRoot = path.join(templatesRoot, 'shared');
+const ssgTemplateRoot = path.join(templatesRoot, 'ssg');
+const spaTemplateRoot = path.join(templatesRoot, 'spa');
+const apiTemplateRoot = path.join(templatesRoot, 'api');
+const fullTemplateRoot = path.join(templatesRoot, 'full');
+
+export function getRootScaffoldAssets(): readonly ScaffoldAsset[] {
+  return [
+    createAsset(sharedTemplateRoot, 'Errors.404.html', 'Errors.404.html'),
+    createAsset(sharedTemplateRoot, 'Errors.500.html', 'Errors.500.html'),
+    createAsset(sharedTemplateRoot, 'Errors.default.html', 'Errors.default.html'),
+    createAsset(sharedTemplateRoot, 'types.global.d.ts', 'types.global.d.ts'),
+    createAsset(sharedTemplateRoot, path.join('types', 'global.d.ts'), path.join('types', 'global.d.ts')),
+  ];
+}
+
+export async function getModeScaffoldAssets(mode: WorkspaceMode): Promise<readonly ScaffoldAsset[]> {
+  switch (mode) {
+    case 'ssg':
+      return collectModeAssets([
+        { sourceRoot: path.join(ssgTemplateRoot, 'src', 'frontend'), targetRoot: path.join('src', 'frontend') },
+      ]);
+    case 'spa':
+      return collectModeAssets([
+        { sourceRoot: path.join(spaTemplateRoot, 'src', 'frontend'), targetRoot: path.join('src', 'frontend') },
+        { sourceRoot: path.join(spaTemplateRoot, 'src', 'shared'), targetRoot: path.join('src', 'shared') },
+      ]);
+    case 'api':
+      return collectModeAssets([
+        { sourceRoot: path.join(apiTemplateRoot, 'src', 'backend'), targetRoot: path.join('src', 'backend') },
+        { sourceRoot: path.join(apiTemplateRoot, 'src', 'shared'), targetRoot: path.join('src', 'shared') },
+      ]);
+    case 'full':
+      return collectModeAssets([
+        { sourceRoot: path.join(fullTemplateRoot, 'src', 'frontend'), targetRoot: path.join('src', 'frontend') },
+        { sourceRoot: path.join(fullTemplateRoot, 'src', 'backend'), targetRoot: path.join('src', 'backend') },
+        { sourceRoot: path.join(fullTemplateRoot, 'src', 'shared'), targetRoot: path.join('src', 'shared') },
+      ]);
+  }
+}
+
+async function collectModeAssets(
+  roots: readonly { sourceRoot: string; targetRoot: string }[]
+): Promise<readonly ScaffoldAsset[]> {
+  const assets: ScaffoldAsset[] = [];
+  for (const root of roots) {
+    const relativePaths = await listFiles(root.sourceRoot);
+    for (const relativePath of relativePaths) {
+      assets.push({
+        sourcePath: path.join(root.sourceRoot, relativePath),
+        targetPath: path.join(root.targetRoot, relativePath),
+      });
+    }
+  }
+
+  return assets.sort((left, right) => left.targetPath.localeCompare(right.targetPath));
+}
+
+async function listFiles(root: string, prefix = ''): Promise<string[]> {
+  const entries = await readdir(root, { withFileTypes: true });
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    const nextRelative = prefix ? path.join(prefix, entry.name) : entry.name;
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listFiles(fullPath, nextRelative)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(nextRelative);
+    }
+  }
+
+  return files;
+}
+
+function createAsset(root: string, sourceRelativePath: string, targetPath: string): ScaffoldAsset {
+  return {
+    sourcePath: path.join(root, sourceRelativePath),
+    targetPath,
+  };
+}