ignotum 0.0.13 → 0.0.15

package/src/cli/image-assets.ts

@@ -0,0 +1,499 @@
+import { Crypto, Effect, FileSystem, Path, Predicate, Schema } from "effect";
+import { versionArtifactLimits } from "@ignotum/contracts/version";
+import type { ArtifactReference } from "@ignotum/contracts/version";
+import { artifactReference, sha256 } from "@ignotum/versions";
+import type { Plugin as PostcssPlugin } from "postcss";
+import valueParser from "postcss-value-parser";
+import { normalizePath } from "vite";
+import type { Plugin, ResolvedConfig, ViteDevServer } from "vite";
+
+const imageModulePrefix = "\0ignotum:image:";
+const assetUrlPrefix = "/_ignotum/";
+const imageModuleId = (sourcePath: string): string =>
+  `${imageModulePrefix}${encodeURIComponent(normalizePath(sourcePath))}.js`;
+
+const imageFormats = {
+  avif: { canonicalExtension: "avif", contentType: "image/avif" },
+  gif: { canonicalExtension: "gif", contentType: "image/gif" },
+  ico: { canonicalExtension: "ico", contentType: "image/x-icon" },
+  jpeg: { canonicalExtension: "jpg", contentType: "image/jpeg" },
+  jpg: { canonicalExtension: "jpg", contentType: "image/jpeg" },
+  png: { canonicalExtension: "png", contentType: "image/png" },
+  webp: { canonicalExtension: "webp", contentType: "image/webp" },
+} as const;
+
+const ImageExtension = Schema.Literals(["avif", "gif", "ico", "jpeg", "jpg", "png", "webp"]);
+type ImageExtension = typeof ImageExtension.Type;
+const isImageExtension = Schema.is(ImageExtension);
+
+const sourceExtensions = new Set([
+  "cjs",
+  "css",
+  "cts",
+  "html",
+  "js",
+  "json",
+  "jsx",
+  "mjs",
+  "mts",
+  "ts",
+  "tsx",
+]);
+
+export interface ImageAsset {
+  readonly bytes: Uint8Array;
+  readonly contentType: string;
+  readonly path: string;
+  readonly reference: ArtifactReference;
+}
+
+export interface ImageAssetsPlugin {
+  readonly assets: ReadonlyMap<string, ImageAsset>;
+  readonly plugin: Plugin;
+}
+
+export class InvalidImageAsset extends Schema.TaggedError<InvalidImageAsset>()(
+  "InvalidImageAsset",
+  {
+    importer: Schema.optional(Schema.String),
+    message: Schema.String,
+    path: Schema.String,
+  },
+) {}
+
+const extensionOf = (specifier: string): string | undefined => {
+  const clean = specifier.split(/[?#]/, 1)[0] ?? specifier;
+  const slash = clean.lastIndexOf("/");
+  const dot = clean.lastIndexOf(".");
+  return dot > slash ? clean.slice(dot + 1).toLowerCase() : undefined;
+};
+
+const imageExtension = (specifier: string): ImageExtension | undefined => {
+  const extension = extensionOf(specifier);
+  return isImageExtension(extension) ? extension : undefined;
+};
+
+const hasImageSignature = (extension: ImageExtension, bytes: Uint8Array): boolean => {
+  const ascii = (start: number, length: number): string =>
+    String.fromCharCode(...bytes.subarray(start, start + length));
+
+  switch (extension) {
+    case "avif": {
+      if (bytes.length < 12 || ascii(4, 4) !== "ftyp") return false;
+      for (let offset = 8; offset + 4 <= Math.min(bytes.length, 40); offset += 4) {
+        const brand = ascii(offset, 4);
+        if (brand === "avif" || brand === "avis") return true;
+      }
+      return false;
+    }
+    case "gif":
+      return ascii(0, 6) === "GIF87a" || ascii(0, 6) === "GIF89a";
+    case "ico":
+      return (
+        bytes.length >= 6 &&
+        bytes[0] === 0 &&
+        bytes[1] === 0 &&
+        bytes[2] === 1 &&
+        bytes[3] === 0 &&
+        (bytes[4] ?? 0) + ((bytes[5] ?? 0) << 8) > 0
+      );
+    case "jpeg":
+    case "jpg":
+      return bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff;
+    case "png":
+      return (
+        bytes.length >= 8 &&
+        bytes[0] === 0x89 &&
+        ascii(1, 3) === "PNG" &&
+        bytes[4] === 0x0d &&
+        bytes[5] === 0x0a &&
+        bytes[6] === 0x1a &&
+        bytes[7] === 0x0a
+      );
+    case "webp":
+      return bytes.length >= 12 && ascii(0, 4) === "RIFF" && ascii(8, 4) === "WEBP";
+  }
+};
+
+const isExternalBrowserUrl = (url: string): boolean =>
+  url.startsWith("#") || url.startsWith("//") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(url);
+
+const decodeCssEscapes = (value: string): string =>
+  value.replace(/\\([0-9A-Fa-f]{1,6})\s?|\\([^\r\n])/g, (_match, hex: string, escaped: string) =>
+    hex === undefined ? escaped : String.fromCodePoint(Number.parseInt(hex, 16)),
+  );
+
+const cssImageNodes = (parsed: ReturnType<typeof valueParser>): ReadonlyArray<valueParser.Node> => {
+  const nodes: valueParser.Node[] = [];
+  parsed.walk((node) => {
+    if (node.type === "function" && node.value.toLowerCase() === "url") {
+      const valueNode = node.nodes.find(
+        (child) => child.type === "string" || child.type === "word",
+      );
+      if (valueNode !== undefined) nodes.push(valueNode);
+      return false;
+    }
+    if (
+      node.type === "function" &&
+      ["image-set", "-webkit-image-set"].includes(node.value.toLowerCase())
+    ) {
+      for (const child of node.nodes) {
+        if (child.type === "string") nodes.push(child);
+      }
+    }
+  });
+  return nodes;
+};
+
+export const createImageAssetsPlugin = Effect.fn("Deploy.createImageAssetsPlugin")(function* (
+  appDirectory: string,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const runPromise = Effect.runPromiseWith(yield* Effect.context<Crypto.Crypto>());
+  const assets = new Map<string, ImageAsset>();
+  const sources = new Map<string, ImageAsset>();
+  const emitted = new Set<string>();
+  let emitAsset: ((asset: ImageAsset) => void) | undefined;
+  let resolvedConfig: ResolvedConfig | undefined;
+  let devServer: ViteDevServer | undefined;
+
+  const fail = (assetPath: string, message: string, importer?: string): InvalidImageAsset =>
+    InvalidImageAsset.make({ importer, message, path: assetPath });
+
+  const validateNoSymlinks = Effect.fn("Deploy.validateImageAssetSymlinks")(function* (
+    absolutePath: string,
+    importer?: string,
+  ) {
+    let current = absolutePath;
+    for (;;) {
+      const info = yield* fileSystem
+        .stat(current)
+        .pipe(
+          Effect.mapError((cause) =>
+            fail(
+              absolutePath,
+              `Could not inspect imported image ${absolutePath}: ${cause.message}`,
+              importer,
+            ),
+          ),
+        );
+      if (info.type === "SymbolicLink") {
+        return yield* fail(
+          absolutePath,
+          `Imported image paths cannot contain symbolic links (${current})`,
+          importer,
+        );
+      }
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+    const realPath = yield* fileSystem
+      .realPath(absolutePath)
+      .pipe(
+        Effect.mapError((cause) =>
+          fail(
+            absolutePath,
+            `Could not resolve imported image ${absolutePath}: ${cause.message}`,
+            importer,
+          ),
+        ),
+      );
+    if (normalizePath(realPath) !== normalizePath(absolutePath)) {
+      return yield* fail(
+        absolutePath,
+        "Imported image paths cannot contain symbolic links",
+        importer,
+      );
+    }
+  });
+
+  const validateImage = Effect.fn("Deploy.validateImageAsset")(function* (
+    sourcePath: string,
+    importer?: string,
+  ) {
+    const absolutePath = path.resolve(sourcePath);
+    const cached = sources.get(absolutePath);
+    if (cached !== undefined) return cached;
+
+    const extension = imageExtension(absolutePath);
+    if (extension === undefined) {
+      return yield* fail(
+        absolutePath,
+        "Imported assets must be AVIF, GIF, ICO, JPEG, PNG, or WebP images",
+        importer,
+      );
+    }
+    yield* validateNoSymlinks(absolutePath, importer);
+    const info = yield* fileSystem
+      .stat(absolutePath)
+      .pipe(
+        Effect.mapError((cause) =>
+          fail(
+            absolutePath,
+            `Could not inspect imported image ${absolutePath}: ${cause.message}`,
+            importer,
+          ),
+        ),
+      );
+    if (info.type !== "File") {
+      return yield* fail(absolutePath, "Imported images must be regular files", importer);
+    }
+    if (info.size > BigInt(versionArtifactLimits.fileBytes)) {
+      return yield* fail(absolutePath, "Imported images cannot be larger than 16 MiB", importer);
+    }
+    const bytes = yield* fileSystem
+      .readFile(absolutePath)
+      .pipe(
+        Effect.mapError((cause) =>
+          fail(
+            absolutePath,
+            `Could not read imported image ${absolutePath}: ${cause.message}`,
+            importer,
+          ),
+        ),
+      );
+    if (bytes.byteLength > versionArtifactLimits.fileBytes) {
+      return yield* fail(absolutePath, "Imported images cannot be larger than 16 MiB", importer);
+    }
+    if (!hasImageSignature(extension, bytes)) {
+      return yield* fail(
+        absolutePath,
+        `The file contents do not match the .${extension} image extension`,
+        importer,
+      );
+    }
+
+    const digest = yield* sha256(bytes);
+    const format = imageFormats[extension];
+    const artifactPath = `assets/${digest}/image.${format.canonicalExtension}`;
+    let asset = assets.get(artifactPath);
+    if (asset === undefined) {
+      asset = {
+        bytes,
+        contentType: format.contentType,
+        path: artifactPath,
+        reference: yield* artifactReference(artifactPath, bytes),
+      };
+      assets.set(artifactPath, asset);
+    }
+    sources.set(absolutePath, asset);
+    return asset;
+  });
+
+  const emit = (asset: ImageAsset): void => {
+    if (resolvedConfig?.command !== "build" || emitted.has(asset.path)) return;
+    emitAsset?.(asset);
+    emitted.add(asset.path);
+  };
+
+  const cssPlugin: PostcssPlugin = {
+    postcssPlugin: "ignotum-image-assets",
+    Once: async (root, { result }) => {
+      const declarations: Array<{
+        file: string;
+        get: () => string;
+        set: (value: string) => void;
+      }> = [];
+      root.walkDecls((declaration) => {
+        const file = declaration.source?.input.file;
+        if (file === undefined || file.startsWith("<")) return;
+        declarations.push({
+          file,
+          get: () => declaration.value,
+          set: (value) => {
+            declaration.value = value;
+          },
+        });
+      });
+
+      for (const owner of declarations) {
+        const parsed = valueParser(owner.get());
+        const nodes = cssImageNodes(parsed);
+        for (const node of nodes) {
+          const url = decodeCssEscapes(node.value.trim());
+          if (url.length === 0 || isExternalBrowserUrl(url)) continue;
+          if (url.startsWith(assetUrlPrefix) && assets.has(url.slice(assetUrlPrefix.length)))
+            continue;
+          if (url.includes("?") || url.includes("#")) {
+            throw fail(url, "Image import queries and fragments are not supported", owner.file);
+          }
+          const extension = extensionOf(url);
+          if (!isImageExtension(extension)) {
+            throw fail(
+              url,
+              "CSS can only import local AVIF, GIF, ICO, JPEG, PNG, or WebP images",
+              owner.file,
+            );
+          }
+          const sourcePath = url.startsWith("/")
+            ? path.resolve(resolvedConfig?.root ?? path.join(appDirectory, "client"), url.slice(1))
+            : path.resolve(path.dirname(owner.file), url);
+          const asset = await runPromise(validateImage(sourcePath, owner.file));
+          result.messages.push({
+            type: "dependency",
+            plugin: "ignotum-image-assets",
+            file: sourcePath,
+            parent: owner.file,
+          });
+          emit(asset);
+          node.value = `${assetUrlPrefix}${asset.path}`;
+        }
+        owner.set(valueParser.stringify(parsed.nodes));
+      }
+    },
+  };
+
+  const plugin: Plugin = {
+    name: "ignotum-image-assets",
+    enforce: "pre",
+    config: (config) => {
+      const external = config.build?.rolldownOptions?.external;
+      const postcss = config.css?.postcss;
+      const postcssOptions = Predicate.isString(postcss) ? undefined : postcss;
+      return {
+        build: {
+          assetsInlineLimit: 0,
+          rolldownOptions: {
+            external: (id, importer, isResolved) => {
+              if (id.startsWith(assetUrlPrefix) && assets.has(id.slice(assetUrlPrefix.length)))
+                return true;
+              if (Predicate.isFunction(external)) return external(id, importer, isResolved);
+              if (external === undefined) return false;
+              const patterns = Array.isArray(external) ? external : [external];
+              return patterns.some((pattern) =>
+                Predicate.isString(pattern) ? pattern === id : pattern.test(id),
+              );
+            },
+          },
+        },
+        css: {
+          postcss: {
+            ...postcssOptions,
+            plugins: [...(postcssOptions?.plugins ?? []), cssPlugin],
+          },
+        },
+      };
+    },
+    configResolved: (config) => {
+      resolvedConfig = config;
+    },
+    buildStart() {
+      emitAsset = (asset) => {
+        this.emitFile({ type: "asset", fileName: asset.path, source: asset.bytes });
+      };
+      assets.clear();
+      sources.clear();
+      emitted.clear();
+    },
+    resolveId: async function (source, importer) {
+      if (source.startsWith("/@id/__x00__")) {
+        return `\0${source.slice("/@id/__x00__".length)}`;
+      }
+      if (
+        source.startsWith("\0") ||
+        source.startsWith("virtual:") ||
+        source.startsWith("//") ||
+        /^[A-Za-z][A-Za-z0-9+.-]*:/.test(source)
+      )
+        return;
+      const extension = extensionOf(source);
+      const hasQuery = source.includes("?") || source.includes("#");
+      if (imageExtension(source) !== undefined) {
+        if (hasQuery) {
+          throw fail(source, "Image import queries and fragments are not supported", importer);
+        }
+        if (source.startsWith(".") && importer !== undefined && !importer.startsWith("\0")) {
+          await runPromise(validateImage(path.resolve(path.dirname(importer), source), importer));
+        } else if (source.startsWith("/")) {
+          const sourcePath = (await runPromise(fileSystem.exists(source)))
+            ? source
+            : path.resolve(
+                resolvedConfig?.root ?? path.join(appDirectory, "client"),
+                source.slice(1),
+              );
+          await runPromise(validateImage(sourcePath, importer));
+        }
+        const resolution = await this.resolve(source, importer, { skipSelf: true });
+        if (
+          resolution === null ||
+          (resolution.external !== undefined && resolution.external !== false)
+        ) {
+          throw fail(source, "Imported image could not be resolved", importer);
+        }
+        return imageModuleId(resolution.id);
+      }
+      if (hasQuery || (extension !== undefined && !sourceExtensions.has(extension))) {
+        throw fail(
+          source,
+          "Client imports only support source modules, stylesheets, and validated image assets",
+          importer,
+        );
+      }
+    },
+    load: async function (id) {
+      if (!id.startsWith(imageModulePrefix)) {
+        if (!id.startsWith("\0") && !id.startsWith("virtual:")) {
+          const extension = extensionOf(id);
+          if (extension !== undefined && !sourceExtensions.has(extension)) {
+            throw fail(
+              id,
+              "Client imports only support source modules, stylesheets, and validated image assets",
+            );
+          }
+        }
+        return;
+      }
+      const sourcePath = decodeURIComponent(id.slice(imageModulePrefix.length, -3));
+      if (resolvedConfig?.command === "build") this.addWatchFile(sourcePath);
+      else devServer?.watcher.add(sourcePath);
+      const asset = await runPromise(validateImage(sourcePath));
+      emit(asset);
+      return [
+        'import { createImageSource } from "ignotum/internal/client";',
+        `export default createImageSource(${JSON.stringify(`${assetUrlPrefix}${asset.path}`)});`,
+      ].join("\n");
+    },
+    configureServer(server: ViteDevServer) {
+      devServer = server;
+      server.middlewares.use((request, response, next) => {
+        if (request.method !== "GET" && request.method !== "HEAD") return next();
+        const pathname = request.url?.split(/[?#]/, 1)[0];
+        if (pathname === undefined || !pathname.startsWith(`${assetUrlPrefix}assets/`))
+          return next();
+        const asset = assets.get(pathname.slice(assetUrlPrefix.length));
+        if (asset === undefined) return next();
+        response.statusCode = 200;
+        response.setHeader("Content-Type", asset.contentType);
+        response.setHeader("Content-Length", String(asset.bytes.byteLength));
+        response.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+        response.end(request.method === "HEAD" ? undefined : asset.bytes);
+      });
+    },
+    watchChange(id) {
+      sources.delete(path.resolve(id));
+      const graph = devServer?.environments.client.moduleGraph;
+      const module = graph?.getModuleById(imageModuleId(path.resolve(id)));
+      if (module !== undefined) graph?.invalidateModule(module);
+    },
+    hotUpdate(context) {
+      const module = this.environment.moduleGraph.getModuleById(
+        imageModuleId(path.resolve(context.file)),
+      );
+      if (module !== undefined) return [...new Set([...context.modules, module])];
+    },
+    generateBundle(_options, bundle) {
+      for (const output of Object.values(bundle)) {
+        if (output.type !== "asset") continue;
+        if (output.fileName.endsWith(".css") || assets.has(output.fileName)) continue;
+        throw fail(
+          output.fileName,
+          "The client build emitted an unsupported asset; import supported images through Ignotum",
+        );
+      }
+    },
+  };
+
+  return { assets, plugin } satisfies ImageAssetsPlugin;
+});

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

@@ -0,0 +1,103 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { normalizePath, type Plugin } from "vite";
+import { managedBrowserExports } from "./managed-exports.js";
+import { InvalidBuildOutput } from "./build/artifact.js";
+
+const PackageMetadata = Schema.Struct({ name: Schema.optional(Schema.String) });
+const externals = new Set<string>(
+  managedBrowserExports
+    .filter((entry) => entry.specifier.startsWith("ignotum/"))
+    .map((entry) => entry.specifier),
+);
+
+/** Resolve before workspace conditions or package aliases can embed SDK implementation. */
+export const managedClientBoundariesPlugin = Effect.fn("Deploy.managedClientBoundariesPlugin")(
+  function* (appDirectory: string) {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const runPromise = Effect.runPromiseWith(yield* Effect.context<never>());
+    const generatedDirectory = normalizePath(
+      path.join(yield* fs.realPath(appDirectory), "_generated"),
+    );
+    const compilerImportAllowed = (specifier: string, importer: string | undefined): boolean => {
+      if (importer === undefined) return false;
+      const source = normalizePath(importer.split("?", 1)[0]!);
+      switch (specifier) {
+        case "ignotum/internal/api":
+          return source === `${generatedDirectory}/api.ts`;
+        case "ignotum/internal/client":
+          return (
+            source === `${generatedDirectory}/client.ts` ||
+            source === `${generatedDirectory}/routes.ts` ||
+            source.startsWith("\0ignotum:image:")
+          );
+        case "ignotum/internal/routes":
+          return source === `${generatedDirectory}/routes.ts`;
+        default:
+          return false;
+      }
+    };
+    const owners = new Map<string, string | undefined>();
+    const ownerOf = Effect.fn("Deploy.managedClientOwner")(function* (id: string) {
+      let directory = path.dirname(id);
+      const start = directory;
+      if (owners.has(start)) return owners.get(start);
+      while (path.dirname(directory) !== directory) {
+        const manifest = path.join(directory, "package.json");
+        if (yield* fs.exists(manifest)) {
+          const metadata = yield* Schema.decodeUnknownEffect(
+            Schema.fromJsonString(PackageMetadata),
+          )(yield* fs.readFileString(manifest));
+          if (metadata.name !== undefined) {
+            owners.set(start, metadata.name);
+            return metadata.name;
+          }
+        }
+        directory = path.dirname(directory);
+      }
+      owners.set(start, undefined);
+      return undefined;
+    });
+    return {
+      name: "ignotum:managed-client-platform-boundary",
+      enforce: "pre",
+      resolveId(specifier, importer) {
+        if (
+          specifier.startsWith("ignotum/internal/") &&
+          !compilerImportAllowed(specifier, importer)
+        ) {
+          throw InvalidBuildOutput.make({
+            message: `Managed client module '${importer ?? "<entry>"}' imports unsupported platform entry '${specifier}'. Compiler-owned entries must come from generated bindings.`,
+          });
+        }
+        if (externals.has(specifier)) return { id: specifier, external: true };
+        if (
+          specifier === "ignotum" ||
+          specifier.startsWith("ignotum/") ||
+          specifier.startsWith("@ignotum/")
+        ) {
+          throw InvalidBuildOutput.make({
+            message: `Managed client module '${importer ?? "<entry>"}' imports unsupported platform entry '${specifier}'. Use ignotum/client or generated client bindings.`,
+          });
+        }
+      },
+      async transform(_code, id) {
+        const clean = id.split("?", 1)[0]!;
+        if (!path.isAbsolute(clean)) return;
+        const relative = normalizePath(path.relative(appDirectory, clean));
+        if (
+          !relative.startsWith("../") &&
+          !path.isAbsolute(relative) &&
+          !relative.split("/").includes("node_modules")
+        )
+          return;
+        const owner = await runPromise(ownerOf(clean));
+        if (owner === "ignotum" || owner?.startsWith("@ignotum/")) {
+          throw InvalidBuildOutput.make({
+            message: `App client graph embeds private platform implementation '${id}'. Import supported ignotum/client entries instead.`,
+          });
+        }
+      },
+    } satisfies Plugin;
+  },
+);