overmux 0.0.1 → 0.0.2

package/src/internal/server/check-overmux.ts

@@ -0,0 +1,364 @@
+import { loadOvermuxConfig } from "@overmux/shared/node";
+import { dirname, isAbsolute, resolve } from "node:path";
+import ts from "typescript";
+import { ZodError } from "zod";
+
+import { createRuntime } from "./runtime/create-runtime";
+
+export type CheckDiagnostic = {
+  code?: number | string;
+  column?: number;
+  file?: string;
+  line?: number;
+  message: string;
+  path?: string;
+  phase: "config" | "imports" | "runtime" | "types" | "ui";
+};
+
+export type CheckResult = {
+  operations?: number;
+  config: string;
+  diagnostics: CheckDiagnostic[];
+  files: number;
+  ok: boolean;
+};
+
+export type CheckOvermuxOptions = {
+  aliases?: Record<string, string>;
+  configPath: string;
+  typeAliases?: Record<string, string>;
+  typesOnly?: boolean;
+};
+
+const loadCompilerOptions = (configPath: string) => {
+  const tsconfig = ts.findConfigFile(dirname(configPath), ts.sys.fileExists);
+  if (!tsconfig) {
+    return {
+      allowImportingTsExtensions: true,
+      allowJs: false,
+      esModuleInterop: true,
+      jsx: ts.JsxEmit.ReactJSX,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      noEmit: true,
+      skipLibCheck: true,
+      strict: true,
+      target: ts.ScriptTarget.ES2022,
+    } satisfies ts.CompilerOptions;
+  }
+  const loaded = ts.readConfigFile(tsconfig, ts.sys.readFile);
+  if (loaded.error) {
+    throw new Error(
+      ts.flattenDiagnosticMessageText(loaded.error.messageText, "\n"),
+    );
+  }
+  const parsed = ts.parseJsonConfigFileContent(
+    loaded.config,
+    ts.sys,
+    dirname(tsconfig),
+  );
+  return {
+    ...parsed.options,
+    allowImportingTsExtensions: true,
+    noEmit: true,
+  };
+};
+
+const diagnosticOf = (diagnostic: ts.Diagnostic): CheckDiagnostic => {
+  const position =
+    diagnostic.file && diagnostic.start !== undefined
+      ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start)
+      : undefined;
+  return {
+    code: diagnostic.code,
+    column: position ? position.character + 1 : undefined,
+    file: diagnostic.file?.fileName,
+    line: position ? position.line + 1 : undefined,
+    message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+    phase: "types",
+  };
+};
+
+const kindOf = (fileName: string, configPath: string) => {
+  if (
+    resolve(fileName) === resolve(configPath) ||
+    fileName.match(/\.server\.[cm]?[jt]sx?$/)
+  ) {
+    return "server";
+  }
+  if (fileName.match(/\.ui\.[cm]?[jt]sx?$/)) {
+    return "client";
+  }
+  if (fileName.match(/\.shared\.[cm]?[jt]sx?$/)) {
+    return "shared";
+  }
+  return undefined;
+};
+
+type ModuleKind = "client" | "server" | "shared";
+
+type ResolvedImport = {
+  kind?: ModuleKind;
+  node: ts.ImportDeclaration | ts.ExportDeclaration;
+  source?: ts.SourceFile;
+};
+
+const kindOfSpecifier = (specifier: string): ModuleKind | undefined => {
+  if (specifier === "overmux/client" || specifier.endsWith("/react")) {
+    return "client";
+  }
+  if (
+    specifier === "overmux/server" ||
+    specifier.endsWith("/server") ||
+    specifier.startsWith("node:")
+  ) {
+    return "server";
+  }
+  if (specifier === "overmux" || specifier.endsWith("/shared")) {
+    return "shared";
+  }
+  return undefined;
+};
+
+const isTypeOnlyReference = (
+  node: ts.ImportDeclaration | ts.ExportDeclaration,
+) => {
+  if (ts.isExportDeclaration(node)) {
+    return Boolean(
+      node.isTypeOnly ||
+      (node.exportClause &&
+        ts.isNamedExports(node.exportClause) &&
+        node.exportClause.elements.every((element) => element.isTypeOnly)),
+    );
+  }
+  const clause = node.importClause;
+  if (!clause || clause.name) {
+    return Boolean(clause?.isTypeOnly);
+  }
+  return Boolean(
+    clause.isTypeOnly ||
+    (clause.namedBindings &&
+      ts.isNamedImports(clause.namedBindings) &&
+      clause.namedBindings.elements.every((element) => element.isTypeOnly)),
+  );
+};
+
+const resolvedImports = (program: ts.Program, source: ts.SourceFile) => {
+  const imports: ResolvedImport[] = [];
+  source.forEachChild((node) => {
+    if (
+      (!ts.isImportDeclaration(node) && !ts.isExportDeclaration(node)) ||
+      !node.moduleSpecifier ||
+      !ts.isStringLiteral(node.moduleSpecifier) ||
+      isTypeOnlyReference(node)
+    ) {
+      return;
+    }
+    const specifier = node.moduleSpecifier.text;
+    const resolved = ts.resolveModuleName(
+      specifier,
+      source.fileName,
+      program.getCompilerOptions(),
+      ts.sys,
+    ).resolvedModule?.resolvedFileName;
+    const target = resolved ? program.getSourceFile(resolved) : undefined;
+    const kind = kindOfSpecifier(specifier);
+    if (kind || (target && !target.isDeclarationFile)) {
+      imports.push({
+        kind,
+        node,
+        source: target?.isDeclarationFile ? undefined : target,
+      });
+    }
+  });
+  return imports;
+};
+
+const invalidImport = (source: ModuleKind, target: ModuleKind | undefined) =>
+  (source === "server" && target === "client") ||
+  (source === "client" && target === "server") ||
+  (source === "shared" && target !== undefined && target !== "shared");
+
+const visitImportGraph = ({
+  configPath,
+  diagnostics,
+  kind,
+  program,
+  seen,
+  source,
+}: {
+  configPath: string;
+  diagnostics: CheckDiagnostic[];
+  kind: ModuleKind;
+  program: ts.Program;
+  seen: Set<string>;
+  source: ts.SourceFile;
+}) => {
+  const visitKey = `${kind}:${source.fileName}`;
+  if (seen.has(visitKey)) {
+    return;
+  }
+  seen.add(visitKey);
+  resolvedImports(program, source).forEach(
+    ({ kind: importKind, node, source: target }) => {
+      const declaredKind =
+        importKind ??
+        (target ? kindOf(target.fileName, configPath) : undefined);
+      if (invalidImport(kind, declaredKind)) {
+        const position = source.getLineAndCharacterOfPosition(node.getStart());
+        diagnostics.push({
+          code: "OVERMUX_IMPORT_BOUNDARY",
+          column: position.character + 1,
+          file: source.fileName,
+          line: position.line + 1,
+          message: `${kind} modules may not import ${declaredKind} modules`,
+          phase: "imports",
+        });
+        return;
+      }
+      if (target) {
+        visitImportGraph({
+          configPath,
+          diagnostics,
+          kind: declaredKind === "shared" ? "shared" : kind,
+          program,
+          seen,
+          source: target,
+        });
+      }
+    },
+  );
+};
+
+const importBoundaryDiagnostics = (
+  program: ts.Program,
+  configPath: string,
+): CheckDiagnostic[] => {
+  const diagnostics: CheckDiagnostic[] = [];
+  const seen = new Set<string>();
+  program.getSourceFiles().forEach((source) => {
+    const kind = kindOf(source.fileName, configPath);
+    if (kind && !source.isDeclarationFile) {
+      visitImportGraph({
+        configPath,
+        diagnostics,
+        kind,
+        program,
+        seen,
+        source,
+      });
+    }
+  });
+  return diagnostics;
+};
+
+const runtimeDiagnostics = (cause: unknown): CheckDiagnostic[] => {
+  if (cause instanceof ZodError) {
+    return cause.issues.map((issue) => ({
+      message: issue.message,
+      path: issue.path.length ? issue.path.join(".") : undefined,
+      phase: "runtime" as const,
+    }));
+  }
+  return [
+    {
+      message: cause instanceof Error ? cause.message : String(cause),
+      phase: "runtime",
+    },
+  ];
+};
+
+const typecheck = async ({
+  aliases = {},
+  configPath,
+  typeAliases,
+}: CheckOvermuxOptions) => {
+  const options = loadCompilerOptions(configPath);
+  const aliasesForTypes =
+    typeAliases ??
+    Object.fromEntries(
+      Object.entries(aliases).filter(
+        ([key]) => key === "overmux" || key.startsWith("overmux/"),
+      ),
+    );
+  const absoluteAliases = Object.fromEntries(
+    Object.entries(aliasesForTypes).map(([key, value]) => [
+      key,
+      [isAbsolute(value) ? value : resolve(value)],
+    ]),
+  );
+  const program = ts.createProgram({
+    options: {
+      ...options,
+      baseUrl: options.baseUrl ?? "/",
+      paths: { ...options.paths, ...absoluteAliases },
+    },
+    rootNames: [configPath],
+  });
+  const diagnostics = [
+    ...ts.getPreEmitDiagnostics(program).map(diagnosticOf),
+    ...importBoundaryDiagnostics(program, configPath),
+  ];
+  const files = program
+    .getSourceFiles()
+    .filter(
+      (file) =>
+        !file.isDeclarationFile && !file.fileName.includes("node_modules"),
+    ).length;
+  return { diagnostics, files };
+};
+
+export const checkOvermux = async (
+  options: CheckOvermuxOptions,
+): Promise<CheckResult> => {
+  const configPath = resolve(options.configPath);
+  let checked;
+  try {
+    checked = await typecheck({ ...options, configPath });
+  } catch (cause) {
+    return {
+      config: configPath,
+      diagnostics: [
+        {
+          message: cause instanceof Error ? cause.message : String(cause),
+          phase: "config",
+        },
+      ],
+      files: 0,
+      ok: false,
+    };
+  }
+  if (checked.diagnostics.length || options.typesOnly) {
+    return {
+      config: configPath,
+      diagnostics: checked.diagnostics,
+      files: checked.files,
+      ok: checked.diagnostics.length === 0,
+    };
+  }
+
+  let runtime: Awaited<ReturnType<typeof createRuntime>> | undefined;
+  try {
+    const { config } = await loadOvermuxConfig({
+      aliases: options.aliases,
+      configPath,
+    });
+    runtime = await createRuntime({ config });
+    return {
+      operations: runtime.manifest.operations.length,
+      config: configPath,
+      diagnostics: [],
+      files: checked.files,
+      ok: true,
+    };
+  } catch (cause) {
+    return {
+      config: configPath,
+      diagnostics: runtimeDiagnostics(cause),
+      files: checked.files,
+      ok: false,
+    };
+  } finally {
+    await runtime?.dispose();
+  }
+};

package/src/internal/server/coordinator/ipc-protocol.ts

@@ -0,0 +1,44 @@
+// Defines the complete validated IPC boundary between coordinator and child.
+// Application traffic never crosses this process boundary.
+
+import { z } from "zod";
+
+const childOptionsSchema = z.object({
+  configAliases: z.record(z.string(), z.string()).optional(),
+  configPath: z.string(),
+  debug: z.boolean().optional(),
+  developmentWebTarget: z.url().optional(),
+  host: z.string().optional(),
+  logFile: z.string().optional(),
+  port: z.number().int().min(0).max(65_535).optional(),
+  productionWebAssetsDir: z.string().optional(),
+  watch: z.boolean().optional(),
+});
+
+const parentMessageSchema = z.discriminatedUnion("type", [
+  z.object({ options: childOptionsSchema, type: z.literal("start") }),
+  z.object({ type: z.literal("update-available") }),
+  z.object({ type: z.literal("stop") }),
+]);
+
+const childMessageSchema = z.discriminatedUnion("type", [
+  z.object({
+    host: z.string(),
+    port: z.number().int().min(1).max(65_535),
+    type: z.literal("ready"),
+    url: z.string(),
+    watch: z.boolean(),
+  }),
+  z.object({ type: z.literal("restart-requested") }),
+  z.object({ message: z.string(), type: z.literal("startup-failed") }),
+]);
+
+export type ChildServerOptions = z.infer<typeof childOptionsSchema>;
+export type ParentToChildMessage = z.infer<typeof parentMessageSchema>;
+export type ChildToParentMessage = z.infer<typeof childMessageSchema>;
+
+export const parseParentMessage = (value: unknown): ParentToChildMessage =>
+  parentMessageSchema.parse(value);
+
+export const parseChildMessage = (value: unknown): ChildToParentMessage =>
+  childMessageSchema.parse(value);

package/src/internal/server/coordinator/server-child.ts

@@ -0,0 +1,108 @@
+// Executable entry for one fresh application-server child process.
+// It translates lifecycle IPC only and never retains state across restarts.
+
+import { startApplicationServer } from "../start-application-server";
+import { errorMessage } from "../server-logger";
+import { parseParentMessage, type ChildToParentMessage } from "./ipc-protocol";
+
+const send = (message: ChildToParentMessage) => {
+  if (!process.connected) {
+    return;
+  }
+  try {
+    process.send?.(message, () => undefined);
+  } catch {}
+};
+
+const disconnect = () => {
+  if (!process.connected) {
+    return;
+  }
+  try {
+    process.disconnect();
+  } catch {}
+};
+
+const runServerChild = () => {
+  let serverPromise: ReturnType<typeof startApplicationServer> | undefined;
+  let closing: Promise<void> | undefined;
+
+  const close = () => {
+    if (closing) {
+      return closing;
+    }
+    closing =
+      serverPromise?.then(
+        (server) => server.close(),
+        () => undefined,
+      ) ?? Promise.resolve();
+    return closing;
+  };
+
+  process.on("message", (raw) => {
+    let message;
+    try {
+      message = parseParentMessage(raw);
+    } catch (cause) {
+      send({ message: errorMessage(cause), type: "startup-failed" });
+      return;
+    }
+    if (message.type === "update-available") {
+      if (!closing) {
+        void serverPromise?.then(
+          (server) => server.announceUpdateAvailable(),
+          () => undefined,
+        );
+      }
+      return;
+    }
+    if (message.type === "stop") {
+      void close()
+        .catch((cause: unknown) => {
+          process.stderr.write(
+            `[overmux] child shutdown failed: ${errorMessage(cause)}\n`,
+          );
+        })
+        .finally(disconnect);
+      return;
+    }
+    if (serverPromise || closing) {
+      send({
+        message: "Server child received more than one start request",
+        type: "startup-failed",
+      });
+      return;
+    }
+    serverPromise = startApplicationServer({
+      onRestartRequested: () => send({ type: "restart-requested" }),
+      options: message.options,
+    });
+    void serverPromise
+      .then((server) => {
+        if (closing) {
+          return;
+        }
+        send({
+          host: server.host,
+          port: server.port,
+          type: "ready",
+          url: server.url,
+          watch: server.watch,
+        });
+      })
+      .catch((cause: unknown) => {
+        send({ message: errorMessage(cause), type: "startup-failed" });
+        disconnect();
+      });
+  });
+
+  process.once("disconnect", () => {
+    void close().catch((cause: unknown) => {
+      process.stderr.write(
+        `[overmux] disconnected child shutdown failed: ${errorMessage(cause)}\n`,
+      );
+    });
+  });
+};
+
+runServerChild();