ignotum 0.0.13 → 0.0.15

package/src/cli/build/managed-client.ts

@@ -0,0 +1,411 @@
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { Effect, FileSystem, Option, Path, Predicate, Schema } from "effect";
+import tailwindcss from "@tailwindcss/vite";
+import { defaultClientConditions, normalizePath, type Plugin } from "vite";
+import {
+  AppArtifact,
+  AppArtifactPath,
+  AppDefinition,
+  AppModuleId,
+  ModuleImport,
+  type AppModule,
+} from "@ignotum/contracts/app-definition";
+import { artifactReference, sha256, utf8Bytes, validateAppModuleBytes } from "@ignotum/versions";
+import { InvalidClientFile } from "../client-config.js";
+import { clientStylesSource } from "../client-styles.js";
+import { createImageAssetsPlugin } from "../image-assets.js";
+import { managedClientBoundariesPlugin } from "../managed-client-boundaries.js";
+import { managedPreactPeerPlugin } from "../managed-exports.js";
+import { moduleBoundariesPlugin } from "../module-boundaries.js";
+import { generateClientRoutes } from "../route-codegen.js";
+import { InvalidBuildOutput, runViteBuild, sourceMapPathTransform } from "./artifact.js";
+
+export interface ManagedClientBuildResult {
+  readonly appName: string;
+  readonly client: AppDefinition["client"];
+  readonly artifacts: ReadonlyArray<AppArtifact>;
+  readonly bytes: ReadonlyMap<string, Uint8Array>;
+}
+
+interface ClientChunk {
+  readonly fileName: string;
+  readonly imports: ReadonlyArray<string>;
+  readonly dynamicImports: ReadonlyArray<string>;
+  readonly styles: ReadonlyArray<string>;
+  readonly isEntry: boolean;
+}
+
+const literal = Schema.encodeSync(Schema.fromJsonString(Schema.String));
+const globalStylesId = "virtual:ignotum/managed-global.css";
+
+const stylesheetFileName = (source: string | Uint8Array): string => {
+  // Vite removes its internal hash-update marker before writing CSS assets.
+  const finalSource = Predicate.isString(source)
+    ? source.replace(/\/\*\$vite\$:\d+\*\//, "")
+    : source;
+  return `assets/${createHash("sha256").update(finalSource).digest("hex")}/style.css`;
+};
+
+/** Compile route definitions and app dependencies without embedding browser runtime code. */
+export const buildManagedClient = Effect.fn("Deploy.buildManagedClient")(function* (
+  appDirectory: string,
+  outputDirectory: string,
+  options: { readonly applicationName: string },
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const appName = yield* Schema.decodeUnknownEffect(AppDefinition.fields.appName)(
+    options.applicationName,
+  );
+  for (const publicPath of [
+    path.join(appDirectory, "public"),
+    path.join(appDirectory, "client/public"),
+  ]) {
+    if (
+      (yield* fs.exists(publicPath)) ||
+      Option.isSome(yield* Effect.option(fs.readLink(publicPath)))
+    )
+      return yield* InvalidClientFile.make({
+        path: publicPath,
+        message:
+          "App public directories are not supported. Import supported images from client/_assets instead.",
+      });
+  }
+  const discovery = yield* generateClientRoutes(appDirectory);
+  const stage = yield* fs.makeTempDirectoryScoped({ prefix: "ignotum-managed-client-" });
+  const images = yield* createImageAssetsPlugin(appDirectory);
+  const boundaries = yield* moduleBoundariesPlugin("Client", appDirectory);
+  const platform = yield* managedClientBoundariesPlugin(appDirectory);
+  const peers = yield* managedPreactPeerPlugin({ resolvePeer: (specifier) => specifier });
+  const entrySources = new Map<string, string>();
+  const input: Record<string, string> = {};
+  input.global = globalStylesId;
+  const sourceEntries = new Map<AppModuleId, string>();
+  for (const [index, module] of discovery.modules.entries()) {
+    const name = `${module.kind}-${index}`;
+    const id = `virtual:ignotum/managed-client/${name}`;
+    input[name] = id;
+    sourceEntries.set(module.id, `${name}.mjs`);
+    entrySources.set(
+      `\0${id}`,
+      `export { default } from ${literal(normalizePath(module.path))};\n`,
+    );
+  }
+  const chunkMetadata = new Map<string, ClientChunk>();
+  const maps = new Map<string, Uint8Array>();
+  const privateMaps: Plugin = {
+    name: "ignotum:private-client-source-maps",
+    enforce: "pre",
+    generateBundle: {
+      order: "pre",
+      handler(_options, bundle) {
+        for (const item of Object.values(bundle)) {
+          if (item.type !== "asset" || !item.fileName.endsWith(".mjs.map")) continue;
+          const owner = bundle[item.fileName.slice(0, -4)];
+          if (owner?.type !== "chunk" || owner.map === null) continue;
+          // Remove only compiler-produced chunk maps before the image plugin checks browser assets.
+          // The final writer records them privately with their app module owner.
+          delete bundle[item.fileName];
+        }
+      },
+    },
+  };
+  const collect: Plugin = {
+    name: "ignotum:managed-client-entries",
+    enforce: "post",
+    resolveId(id) {
+      if (id === globalStylesId || entrySources.has(`\0${id}`)) return `\0${id}`;
+    },
+    load(id) {
+      if (id === `\0${globalStylesId}`) return clientStylesSource;
+      return entrySources.get(id);
+    },
+    generateBundle(_options, bundle) {
+      for (const item of Object.values(bundle)) {
+        if (item.type !== "chunk") continue;
+        const metadata = Schema.decodeUnknownSync(
+          Schema.Struct({
+            viteMetadata: Schema.optional(
+              Schema.Struct({ importedCss: Schema.ReadonlySet(Schema.String) }),
+            ),
+          }),
+        )(item);
+        chunkMetadata.set(item.fileName, {
+          fileName: item.fileName,
+          imports: item.imports,
+          dynamicImports: item.dynamicImports,
+          styles: [...(metadata.viteMetadata?.importedCss ?? [])].sort(),
+          isEntry: item.isEntry,
+        });
+        if (item.map === null) {
+          if (Object.values(item.modules).some((module) => module.renderedLength > 0))
+            this.error(`Missing source map for app implementation '${item.fileName}'.`);
+          continue;
+        }
+        const encodedDirectory = JSON.stringify(normalizePath(appDirectory)).slice(1, -1);
+        maps.set(
+          `${item.fileName}.map`,
+          utf8Bytes(item.map.toString().replaceAll(encodedDirectory, "ignotum://app")),
+        );
+      }
+    },
+  };
+  const output = yield* runViteBuild("managed client graph", {
+    root: path.join(appDirectory, "client"),
+    configFile: false,
+    publicDir: false,
+    envDir: false,
+    logLevel: "warn",
+    mode: "production",
+    define: {
+      "process.env.NODE_ENV": JSON.stringify("production"),
+      "import.meta.env.DEV": "false",
+      "import.meta.env.PROD": "true",
+    },
+    base: "/_ignotum/",
+    oxc: { jsx: { importSource: "ignotum/client", runtime: "automatic", development: false } },
+    resolve: {
+      alias: [
+        {
+          find: /^tailwindcss$/,
+          replacement: normalizePath(fileURLToPath(import.meta.resolve("tailwindcss/index.css"))),
+        },
+      ],
+      conditions: defaultClientConditions.map((condition) =>
+        condition === "development|production" ? "production" : condition,
+      ),
+      tsconfigPaths: true,
+    },
+    plugins: [privateMaps, images.plugin, boundaries, platform, peers, collect, tailwindcss()],
+    build: {
+      emptyOutDir: false,
+      outDir: stage,
+      modulePreload: false,
+      sourcemap: "hidden",
+      target: "es2022",
+      rolldownOptions: {
+        input,
+        preserveEntrySignatures: "strict",
+        output: {
+          entryFileNames: "[name].mjs",
+          chunkFileNames: "shared-[hash].mjs",
+          assetFileNames: (asset) =>
+            asset.names.some((name) => name.endsWith(".css"))
+              ? stylesheetFileName(asset.source)
+              : "assets/[name]-[hash][extname]",
+          sourcemapPathTransform: yield* sourceMapPathTransform(appDirectory),
+        },
+      },
+    },
+  });
+  const chunks = output.flatMap((item) =>
+    item.type === "chunk"
+      ? [
+          {
+            fileName: item.fileName,
+            imports: item.imports,
+            dynamicImports: item.dynamicImports,
+            isEntry: item.isEntry,
+            styles: chunkMetadata.get(item.fileName)?.styles ?? [],
+          },
+        ]
+      : [],
+  );
+  const files = new Map<string, Uint8Array>();
+  for (const item of output) {
+    if (
+      item.type === "asset" &&
+      !item.fileName.endsWith(".css") &&
+      !images.assets.has(item.fileName)
+    )
+      return yield* InvalidBuildOutput.make({
+        message: `Unsupported client artifact '${item.fileName}'.`,
+      });
+    files.set(item.fileName, yield* fs.readFile(path.join(stage, item.fileName)));
+  }
+  for (const [name, bytes] of maps) files.set(name, bytes);
+  const knownChunks = new Map(chunks.map((chunk) => [chunk.fileName, chunk]));
+  const stylesFor = (fileName: string, visited = new Set<string>()): ReadonlyArray<string> => {
+    if (visited.has(fileName)) return [];
+    visited.add(fileName);
+    const chunk = knownChunks.get(fileName);
+    if (chunk === undefined) return [];
+    return [
+      ...new Set([
+        ...chunk.styles,
+        ...chunk.imports.flatMap((dependency) => stylesFor(dependency, visited)),
+      ]),
+    ].sort();
+  };
+  const globalCss = new Set(chunkMetadata.get("global.mjs")?.styles ?? []);
+  const routeStyles = new Set(
+    chunks.filter((chunk) => chunk.fileName !== "global.mjs").flatMap((chunk) => chunk.styles),
+  );
+  const styles = [...files.keys()]
+    .filter((name) => name.endsWith(".css") && (globalCss.has(name) || !routeStyles.has(name)))
+    .sort();
+  const registration = `import { mountClient } from "ignotum/internal/bootstrap";
+const registration = {
+  applicationName: ${literal(appName)},
+  routes: ${JSON.stringify(discovery.routes)},
+  layouts: ${JSON.stringify(discovery.layouts)},
+  styles: ${JSON.stringify(styles.map((name) => `/_ignotum/${name}`))},
+  modules: new Map([
+${discovery.modules
+  .map((module) => {
+    const name = sourceEntries.get(module.id)!;
+    return `    [${literal(module.id)}, { load: () => import(${literal(`./${name}`)}), styles: ${JSON.stringify(stylesFor(name).map((style) => `/_ignotum/${style}`))} }]`;
+  })
+  .join(",\n")}
+  ])
+};
+export default function mount(selection) { return mountClient(registration, selection); }
+`;
+  files.set("registration.mjs", utf8Bytes(registration));
+  chunks.push({
+    fileName: "registration.mjs",
+    imports: ["ignotum/internal/bootstrap"],
+    dynamicImports: [...sourceEntries.values()],
+    styles,
+    isEntry: true,
+  });
+  chunks.sort((a, b) => a.fileName.localeCompare(b.fileName));
+  let icon: AppArtifactPath | undefined;
+  const iconPath = path.join(appDirectory, "client/icon.svg");
+  if (yield* fs.exists(iconPath)) {
+    if ((yield* fs.stat(iconPath)).type !== "File")
+      return yield* InvalidClientFile.make({
+        path: iconPath,
+        message: "The client icon must be a regular file.",
+      });
+    const bytes = yield* fs.readFile(iconPath);
+    icon = AppArtifactPath.make(`assets/${yield* sha256(bytes)}/icon.svg`);
+    files.set(icon, bytes);
+  }
+  // App module identities include the completed inventory digest. Its source retains relative
+  // imports and content-named asset URLs, so cycles and registration never hash their own identity.
+  const inventory = yield* Effect.forEach(
+    [...files].sort(([a], [b]) => a.localeCompare(b)),
+    ([name, bytes]) => sha256(bytes).pipe(Effect.map((digest) => ({ name, digest }))),
+  );
+  const graphDigest = yield* sha256(utf8Bytes(JSON.stringify(inventory)));
+  const moduleId = (name: string) => AppModuleId.make(`app/client/${graphDigest}/${name}`);
+  const modulePath = (name: string) => AppArtifactPath.make(`client/${graphDigest}/${name}`);
+  const artifacts: AppArtifact[] = [];
+  const bytes = new Map<string, Uint8Array>();
+  const modules: AppModule[] = [];
+  const imagePaths = [...images.assets.keys()];
+  for (const chunk of chunks) {
+    const source = files.get(chunk.fileName)!;
+    const id = moduleId(chunk.fileName);
+    const artifact = {
+      ...(yield* artifactReference(modulePath(chunk.fileName), source)),
+      kind: "ClientModule" as const,
+      visibility: "public" as const,
+      contentType: "text/javascript",
+    };
+    const imports: ModuleImport[] = [];
+    for (const imported of new Set([...chunk.imports, ...chunk.dynamicImports])) {
+      if (knownChunks.has(imported)) {
+        const relative = normalizePath(path.relative(path.dirname(chunk.fileName), imported));
+        imports.push({
+          kind: "App",
+          specifier: relative.startsWith(".") ? relative : `./${relative}`,
+          module: moduleId(imported),
+        });
+      } else {
+        const kind = imported.startsWith("ignotum/internal/")
+          ? "Compiler"
+          : imported.startsWith("ignotum/client")
+            ? "Runtime"
+            : "RenderingPeer";
+        imports.push(
+          yield* Schema.decodeUnknownEffect(ModuleImport)({ kind, specifier: imported }),
+        );
+      }
+    }
+    const map = maps.get(`${chunk.fileName}.map`);
+    const mapPath = modulePath(`${chunk.fileName}.map`);
+    const moduleStyles = chunk.fileName === "registration.mjs" ? styles : stylesFor(chunk.fileName);
+    const assetSources = [
+      new TextDecoder().decode(source),
+      ...moduleStyles.map((style) => new TextDecoder().decode(files.get(style))),
+    ];
+    const baseModule: AppModule = {
+      id,
+      artifact: artifact.path,
+      imports,
+      styles: moduleStyles.map((name) => AppArtifactPath.make(name)),
+      assets: imagePaths
+        .filter((name) => assetSources.some((contents) => contents.includes(`/_ignotum/${name}`)))
+        .map((name) => AppArtifactPath.make(name)),
+    };
+    const module = map === undefined ? baseModule : { ...baseModule, sourceMap: mapPath };
+    yield* validateAppModuleBytes(module, artifact, source, chunk.isEntry ? ["default"] : []);
+    modules.push(module);
+    artifacts.push(artifact);
+    bytes.set(artifact.path, source);
+    if (map !== undefined) {
+      artifacts.push({
+        ...(yield* artifactReference(mapPath, map)),
+        kind: "SourceMap",
+        visibility: "private",
+        contentType: "application/json",
+        owner: id,
+      });
+      bytes.set(mapPath, map);
+    }
+  }
+  for (const [name, contents] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    if (knownChunks.has(name) || name === "registration.mjs" || name.endsWith(".map")) continue;
+    const kind = name === icon ? "Icon" : name.endsWith(".css") ? "Style" : "Image";
+    const contentType =
+      kind === "Icon"
+        ? "image/svg+xml"
+        : kind === "Style"
+          ? "text/css"
+          : images.assets.get(name)?.contentType;
+    if (contentType === undefined)
+      return yield* InvalidBuildOutput.make({ message: `Unknown client asset '${name}'.` });
+    const reference = yield* artifactReference(name, contents);
+    if (kind === "Style" && name !== `assets/${reference.sha256}/style.css`)
+      return yield* InvalidBuildOutput.make({
+        message: "The bundler changed stylesheet bytes after their content identity was assigned.",
+      });
+    const artifact = yield* Schema.decodeUnknownEffect(AppArtifact)({
+      ...reference,
+      kind,
+      visibility: "public",
+      contentType,
+    });
+    artifacts.push(artifact);
+    bytes.set(artifact.path, contents);
+  }
+  const reference = (id: AppModuleId) => ({
+    module: moduleId(sourceEntries.get(id)!),
+    exportName: "default",
+  });
+  const baseClient = {
+    registration: { module: moduleId("registration.mjs"), exportName: "default" },
+    graph: {
+      entries: chunks.filter((chunk) => chunk.isEntry).map((chunk) => moduleId(chunk.fileName)),
+      modules,
+    },
+    routes: discovery.routes.map((route) => ({ ...route, page: reference(route.page.module) })),
+    layouts: discovery.layouts.map((layout) => ({
+      ...layout,
+      module: reference(layout.module.module),
+    })),
+    styles: styles.map((name) => AppArtifactPath.make(name)),
+  };
+  const client = yield* Schema.decodeUnknownEffect(AppDefinition.fields.client)(
+    icon === undefined ? baseClient : { ...baseClient, icon },
+  );
+  for (const [name, content] of bytes) {
+    const target = path.join(outputDirectory, name);
+    yield* fs.makeDirectory(path.dirname(target), { recursive: true });
+    yield* fs.writeFile(target, content);
+  }
+  return { appName, client, artifacts, bytes } satisfies ManagedClientBuildResult;
+});