@swifttui/build 0.0.6

package/AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+Guidance for agentic assistants working in **`@swifttui/build`**. Keep this
+concise; [`README.md`](README.md) is the full reference.
+
+## What this package is
+
+The **build/packaging tooling** for SwiftTUI browser apps — the sibling of
+[`@swifttui/web`](../web) (which owns the runtime). It captures the Swift app's
+scene manifest and packages its WASI/wasm artifact for the browser. Exposes the
+`swifttui-web` CLI (see `bin` in `package.json`) and a programmatic `index.ts`.
+
+Keep the split clean: **packaging/build steps live here; browser-safe runtime
+APIs live in `@swifttui/web`.** This package depends on `@swifttui/web`.
+
+## Toolchains
+
+- **Bun** for the CLI, bundling, and tests.
+- **`swiftly`** Swift 6.3.1 for the wasm build it invokes
+  (`swiftly run swift ...`), not bare `swift`.
+
+## Commands
+
+```bash
+bun test                         # package tests
+bun run build:manifest -- --app <Exe>   # capture TUIGUI_MODE=manifest output
+bun run build:wasm     -- --app <Exe>   # copy + validate the app's wasm
+bun run build          -- --app <Exe>   # manifest + wasm
+```
+
+`build:wasm`/`build` default to `--configuration release`; pass
+`--configuration debug` for local debug wasm.
+
+## Gotcha
+
+WASI release builds need specific flags (`-Osize` plus
+`-disable-llvm-merge-functions-pass`) to stay under the browser WebAssembly
+API's 1000-parameter limit. The canonical command lives in this package's build
+code — don't hand-roll the swift invocation. See
+[`WebExample`](../../../swift-tui-examples/WebExample) for the full rationale.
+
+## Conventions
+
+`AGENTS.md` is the real file; `CLAUDE.md` is a symlink to it. Edit `AGENTS.md`.

package/README.md

@@ -0,0 +1,46 @@
+# `@swifttui/build`
+
+Build-time package for SwiftTUI browser deployment.
+
+This package owns manifest generation, Swift WASI builds, browser
+`WebAssembly.compile` validation, and wasm packaging. It intentionally sits
+outside `@swifttui/web` so browser runtime imports do not pull in Swift process
+spawning, Node filesystem APIs, or wasm packaging helpers.
+
+Publication status: the package name is reserved for the first public web
+release. Until it is published to npm or attached as a public release tarball,
+use the source checkout and the `swift-tui-examples/WebExample` template.
+
+## API
+
+```ts
+import { buildSwiftTUIWebApp } from "@swifttui/build";
+
+await buildSwiftTUIWebApp({
+  packagePath: ".",
+  product: "MyApp",
+  outputDirectory: "dist",
+});
+```
+
+Toolchain defaults match the repo:
+
+- Swift command: `swiftly run swift` when `swiftly` is on `PATH`, otherwise
+  `swift`
+- SDK: `swift-6.3.1-RELEASE_wasm`
+- Release Swift flags:
+  `-Xswiftc -Osize -Xswiftc -Xfrontend -Xswiftc -disable-llvm-merge-functions-pass`
+- Initial memory: `536870912`
+- Max memory: `4294967296`
+- Stack size: `1048576`
+
+Callers can override `swiftCommand`, `swiftSDK`, `configuration`,
+`initialMemory`, `maxMemory`, `stackSize`, `extraSwiftcFlags`,
+`extraLinkerFlags`, and `extraSwiftBuildArgs`.
+
+## Scripts
+
+- `bun test`
+- `bun run build:manifest -- --app <AppExecutable>`
+- `bun run build:wasm -- --app <AppExecutable>`
+- `bun run build -- --app <AppExecutable>`

package/cli.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env bun
+
+import { resolve } from "node:path";
+import {
+  buildAppWasm,
+  buildSwiftTUIWebApp,
+  generateSceneManifest,
+  type WasmBuildConfiguration,
+} from "./index.ts";
+
+void runCli(process.argv.slice(2));
+
+async function runCli(argv: string[]): Promise<void> {
+  const command = argv[0] ?? "build";
+  const flags = parseFlags(argv.slice(1));
+  const packagePath = resolve(flags["package-path"] ?? "../../");
+  const distPath = resolve(flags["dist"] ?? "./dist");
+  const appExecutable = flags.app ?? flags.product ?? flags["app-product"] ?? "";
+  const configuration = parseWasmBuildConfiguration(flags.configuration ?? "release");
+
+  switch (command) {
+    case "build:manifest":
+      assertAppExecutable(appExecutable);
+      await generateSceneManifest({
+        packagePath,
+        outputPath: resolve(distPath, "scene-manifest.json"),
+        appExecutable,
+      });
+      return;
+    case "build:wasm":
+      assertAppExecutable(appExecutable);
+      await buildAppWasm({
+        configuration,
+        packagePath,
+        outputDirectory: distPath,
+        product: appExecutable,
+      });
+      return;
+    case "build":
+      assertAppExecutable(appExecutable);
+      await buildSwiftTUIWebApp({
+        configuration,
+        packagePath,
+        outputDirectory: distPath,
+        product: appExecutable,
+      });
+      return;
+    default:
+      throw new Error(`unknown command: ${command}`);
+  }
+}
+
+function parseFlags(
+  argv: string[]
+): Record<string, string> {
+  const flags: Record<string, string> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      continue;
+    }
+    const equalsIndex = value.indexOf("=");
+    if (equalsIndex !== -1) {
+      flags[value.slice(2, equalsIndex)] = value.slice(equalsIndex + 1);
+      continue;
+    }
+    const name = value.slice(2);
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      flags[name] = next;
+      index += 1;
+    } else {
+      flags[name] = "true";
+    }
+  }
+  return flags;
+}
+
+function parseWasmBuildConfiguration(
+  value: string
+): WasmBuildConfiguration {
+  switch (value) {
+    case "debug":
+      return "debug";
+    case "release":
+      return "release";
+    default:
+      throw new Error(`unsupported wasm build configuration: ${value}`);
+  }
+}
+
+function assertAppExecutable(
+  value: string
+): asserts value is string {
+  if (!value) {
+    throw new Error("missing --app or --product flag");
+  }
+}

package/index.ts

@@ -0,0 +1,4 @@
+export * from "./src/build/buildAppWasm.ts";
+export * from "./src/build/buildSwiftTUIWebApp.ts";
+export * from "./src/build/generateSceneManifest.ts";
+export * from "./src/build/resolveSwiftArtifacts.ts";

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@swifttui/build",
+  "version": "0.0.6",
+  "license": "MIT",
+  "module": "index.ts",
+  "bin": {
+    "swifttui-web": "./cli.ts"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "type": "module",
+  "scripts": {
+    "build:manifest": "bun run cli.ts build:manifest",
+    "build:wasm": "bun run cli.ts build:wasm",
+    "build": "bun run cli.ts build",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@swifttui/web": "0.0.6"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.13"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/build/buildAppWasm.test.ts

@@ -0,0 +1,178 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { packageBrowserValidatedWasm } from "./buildAppWasm.ts";
+
+const minimalWasmBytes = new Uint8Array([
+  0x00, 0x61, 0x73, 0x6d,
+  0x01, 0x00, 0x00, 0x00,
+]);
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("falls back to the original wasm when strip tooling throws", async () => {
+  const fixture = await createFixture();
+  const warnings: string[] = [];
+
+  await packageBrowserValidatedWasm({
+    optimize: async () => {},
+    sourceWasmPath: fixture.sourceWasmPath,
+    outputWasmPath: fixture.outputWasmPath,
+    strip: async () => {
+      throw new Error("missing llvm-objcopy");
+    },
+    onWarning: (warning) => warnings.push(warning),
+  });
+
+  expect(await Bun.file(fixture.outputWasmPath).bytes())
+    .toEqual(minimalWasmBytes);
+  expect(warnings).toHaveLength(1);
+  expect(warnings[0]).toContain("keeping unstripped wasm");
+  expect(warnings[0]).toContain("missing llvm-objcopy");
+  await WebAssembly.compile(await Bun.file(fixture.outputWasmPath).arrayBuffer());
+});
+
+test("falls back to the original wasm when stripping corrupts the artifact", async () => {
+  const fixture = await createFixture();
+  const warnings: string[] = [];
+
+  await packageBrowserValidatedWasm({
+    optimize: async () => {},
+    sourceWasmPath: fixture.sourceWasmPath,
+    outputWasmPath: fixture.outputWasmPath,
+    strip: async (wasmPath) => {
+      await Bun.write(wasmPath, new Uint8Array([0x00, 0x61, 0x73, 0x6d]));
+    },
+    onWarning: (warning) => warnings.push(warning),
+  });
+
+  expect(await Bun.file(fixture.outputWasmPath).bytes())
+    .toEqual(minimalWasmBytes);
+  expect(warnings).toHaveLength(1);
+  expect(warnings[0])
+    .toContain("stripped wasm does not parse in browser WebAssembly");
+  await WebAssembly.compile(await Bun.file(fixture.outputWasmPath).arrayBuffer());
+});
+
+test("fails when the source wasm itself is not browser-parseable", async () => {
+  const fixture = await createFixture(buildHugeFunctionTypeWasm(1001));
+
+  await expect(
+    packageBrowserValidatedWasm({
+      optimize: async () => {},
+      sourceWasmPath: fixture.sourceWasmPath,
+      outputWasmPath: fixture.outputWasmPath,
+      strip: async () => {},
+    })
+  ).rejects.toThrow("generated wasm does not parse in browser WebAssembly");
+  await expect(
+    packageBrowserValidatedWasm({
+      optimize: async () => {},
+      sourceWasmPath: fixture.sourceWasmPath,
+      outputWasmPath: fixture.outputWasmPath,
+      strip: async () => {},
+    })
+  ).rejects.toThrow("maxTypeParameterCount=1001");
+  await expect(
+    packageBrowserValidatedWasm({
+      optimize: async () => {},
+      sourceWasmPath: fixture.sourceWasmPath,
+      outputWasmPath: fixture.outputWasmPath,
+      strip: async () => {},
+    })
+  ).rejects.toThrow("overBrowserLimitTypes=0");
+});
+
+test("uses optimized wasm when the raw compiler output is not browser-parseable", async () => {
+  const fixture = await createFixture(buildHugeFunctionTypeWasm(1001));
+
+  await packageBrowserValidatedWasm({
+    optimize: async (wasmPath) => {
+      await Bun.write(wasmPath, minimalWasmBytes);
+    },
+    sourceWasmPath: fixture.sourceWasmPath,
+    outputWasmPath: fixture.outputWasmPath,
+    strip: async () => {},
+  });
+
+  expect(await Bun.file(fixture.outputWasmPath).bytes())
+    .toEqual(minimalWasmBytes);
+});
+
+test("reports the optimization failure when the raw wasm is still invalid", async () => {
+  const fixture = await createFixture(buildHugeFunctionTypeWasm(1001));
+
+  await expect(
+    packageBrowserValidatedWasm({
+      optimize: async () => {
+        throw new Error("missing wasm-opt");
+      },
+      sourceWasmPath: fixture.sourceWasmPath,
+      outputWasmPath: fixture.outputWasmPath,
+      strip: async () => {},
+    })
+  ).rejects.toThrow("wasm optimization step failed: missing wasm-opt");
+});
+
+async function createFixture(
+  sourceBytes: Uint8Array = minimalWasmBytes
+): Promise<{ sourceWasmPath: string; outputWasmPath: string }> {
+  const directory = await mkdtemp(join(tmpdir(), "webhost-wasm-"));
+  temporaryDirectories.push(directory);
+
+  const sourceWasmPath = join(directory, "source.wasm");
+  const outputWasmPath = join(directory, "output.wasm");
+  await Bun.write(sourceWasmPath, sourceBytes);
+
+  return {
+    sourceWasmPath,
+    outputWasmPath,
+  };
+}
+
+function buildHugeFunctionTypeWasm(
+  parameterCount: number
+): Uint8Array {
+  const payload = [
+    ...encodeUnsignedLEB128(1),
+    0x60,
+    ...encodeUnsignedLEB128(parameterCount),
+    ...new Array<number>(parameterCount).fill(0x7f),
+    0x00,
+  ];
+
+  return new Uint8Array([
+    ...minimalWasmBytes,
+    0x01,
+    ...encodeUnsignedLEB128(payload.length),
+    ...payload,
+  ]);
+}
+
+function encodeUnsignedLEB128(
+  value: number
+): number[] {
+  if (value < 0) {
+    throw new Error("LEB128 values must be non-negative");
+  }
+
+  const bytes: number[] = [];
+  let remaining = value;
+  do {
+    let byte = remaining & 0x7f;
+    remaining >>>= 7;
+    if (remaining !== 0) {
+      byte |= 0x80;
+    }
+    bytes.push(byte);
+  } while (remaining !== 0);
+
+  return bytes;
+}

package/src/build/buildAppWasm.ts

@@ -0,0 +1,107 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { optimizePackagedWasm } from "./optimizePackagedWasm.ts";
+import {
+  resolveSwiftArtifacts,
+  type ResolveSwiftArtifactsOptions,
+  type SwiftArtifactPaths,
+  type WasmBuildConfiguration,
+} from "./resolveSwiftArtifacts.ts";
+import { stripPackagedWasm } from "./stripPackagedWasm.ts";
+import { formatWasmTypeDiagnostics } from "./wasmTypeDiagnostics.ts";
+
+export interface BuildAppWasmOptions extends ResolveSwiftArtifactsOptions {
+  configuration?: WasmBuildConfiguration;
+  packagePath: string;
+  outputDirectory: string;
+  product: string;
+}
+
+export async function buildAppWasm(
+  options: BuildAppWasmOptions
+): Promise<SwiftArtifactPaths> {
+  const artifacts = await resolveSwiftArtifacts(options);
+
+  const packagedWasmPath = join(options.outputDirectory, "assets", "app.wasm");
+  await mkdir(join(options.outputDirectory, "assets"), { recursive: true });
+  await rm(packagedWasmPath, { force: true });
+  await packageBrowserValidatedWasm({
+    sourceWasmPath: artifacts.wasmPath,
+    outputWasmPath: packagedWasmPath,
+  });
+  return artifacts;
+}
+
+interface PackageBrowserValidatedWasmOptions {
+  optimize?: (wasmPath: string) => Promise<void>;
+  sourceWasmPath: string;
+  outputWasmPath: string;
+  strip?: (wasmPath: string) => Promise<void>;
+  onWarning?: (message: string) => void;
+}
+
+export async function packageBrowserValidatedWasm(
+  options: PackageBrowserValidatedWasmOptions
+): Promise<void> {
+  const sourceBytes = await readFile(options.sourceWasmPath);
+  await writeFile(options.outputWasmPath, sourceBytes);
+
+  const optimize = options.optimize ?? optimizePackagedWasm;
+  try {
+    await optimize(options.outputWasmPath);
+    await validateBrowserWasm(options.outputWasmPath, "optimized wasm");
+  } catch (error) {
+    await writeFile(options.outputWasmPath, sourceBytes);
+    const message = error instanceof Error ? error.message : String(error);
+
+    try {
+      await validateBrowserWasm(options.outputWasmPath, "generated wasm");
+    } catch (rawError) {
+      const rawMessage = rawError instanceof Error ? rawError.message : String(rawError);
+      throw new Error([
+        rawMessage,
+        `wasm optimization step failed: ${message}`,
+      ].join("\n"));
+    }
+
+    const warning = [
+      `warning: keeping unoptimized wasm at ${options.outputWasmPath}`,
+      `wasm optimization step failed or did not produce browser-parseable output: ${message}`,
+    ].join("\n");
+    (options.onWarning ?? console.warn)(warning);
+  }
+
+  const strip = options.strip ?? stripPackagedWasm;
+
+  try {
+    await strip(options.outputWasmPath);
+    await validateBrowserWasm(options.outputWasmPath, "stripped wasm");
+  } catch (error) {
+    // Stripping is a size optimization only. Keep the known-good raw wasm
+    // whenever toolchain-specific objcopy output fails browser validation.
+    await writeFile(options.outputWasmPath, sourceBytes);
+    const message = error instanceof Error ? error.message : String(error);
+    const warning = [
+      `warning: keeping unstripped wasm at ${options.outputWasmPath}`,
+      `strip step failed browser validation or tooling requirements: ${message}`,
+    ].join("\n");
+    (options.onWarning ?? console.warn)(warning);
+  }
+}
+
+async function validateBrowserWasm(
+  wasmPath: string,
+  description: string
+): Promise<void> {
+  const bytes = await readFile(wasmPath);
+  try {
+    // Validate against the same JS API the browser uses before we publish it.
+    await WebAssembly.compile(bytes);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error([
+      `${description} does not parse in browser WebAssembly (${wasmPath}): ${message}`,
+      formatWasmTypeDiagnostics(bytes),
+    ].join("\n"));
+  }
+}

package/src/build/buildSwiftTUIWebApp.ts

@@ -0,0 +1,22 @@
+import { mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { buildAppWasm, type BuildAppWasmOptions } from "./buildAppWasm.ts";
+import { generateSceneManifest } from "./generateSceneManifest.ts";
+
+export interface BuildSwiftTUIWebAppOptions extends BuildAppWasmOptions {
+  appExecutable?: string;
+}
+
+export async function buildSwiftTUIWebApp(
+  options: BuildSwiftTUIWebAppOptions
+): Promise<void> {
+  await rm(options.outputDirectory, { recursive: true, force: true });
+  await mkdir(options.outputDirectory, { recursive: true });
+  await generateSceneManifest({
+    packagePath: options.packagePath,
+    outputPath: join(options.outputDirectory, "scene-manifest.json"),
+    appExecutable: options.appExecutable ?? options.product,
+    swiftCommand: options.swiftCommand,
+  });
+  await buildAppWasm(options);
+}

package/src/build/generateSceneManifest.ts

@@ -0,0 +1,46 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  loadWebHostSceneManifest,
+  webTUISceneManifestToJSON,
+  type WebHostSceneManifest,
+} from "@swifttui/web/manifest";
+import { runCommand } from "./runCommand.ts";
+import { swiftCommandPrefix } from "./swiftCommandPrefix.ts";
+
+export interface GenerateSceneManifestOptions {
+  packagePath: string;
+  outputPath: string;
+  appExecutable: string;
+  swiftCommand?: readonly string[];
+}
+
+export async function generateSceneManifest(
+  options: GenerateSceneManifestOptions
+): Promise<WebHostSceneManifest> {
+  const output = await runManifestCommand(options);
+  const manifest = await loadWebHostSceneManifest(output.trim());
+  await mkdir(dirname(options.outputPath), { recursive: true });
+  await writeFile(options.outputPath, webTUISceneManifestToJSON(manifest));
+  return manifest;
+}
+
+async function runManifestCommand(
+  options: GenerateSceneManifestOptions
+): Promise<string> {
+  return await runCommand(
+    [
+      ...(options.swiftCommand ?? swiftCommandPrefix()),
+      "run",
+      "--package-path",
+      options.packagePath,
+      options.appExecutable,
+    ],
+    {
+      env: {
+        ...process.env,
+        TUIGUI_MODE: "manifest",
+      },
+    }
+  );
+}

package/src/build/optimizePackagedWasm.ts

@@ -0,0 +1,20 @@
+import { findExecutable, runCommand } from "./runCommand.ts";
+
+export async function optimizePackagedWasm(
+  wasmPath: string
+): Promise<void> {
+  const wasmOptPath = findExecutable("wasm-opt");
+  if (!wasmOptPath) {
+    throw new Error(
+      "missing wasm-opt in PATH; install Binaryen so wasm packaging is deterministic across environments"
+    );
+  }
+
+  await runCommand([
+    wasmOptPath,
+    "-Os",
+    wasmPath,
+    "-o",
+    wasmPath,
+  ]);
+}

package/src/build/resolveSwiftArtifacts.test.ts

@@ -0,0 +1,90 @@
+import { expect, test } from "bun:test";
+import {
+  formatCommandForLogs,
+  hasRequiredWasmFlags,
+  requiredWasmSwiftFlags,
+  wasmBuildConfigurationLogLines,
+} from "./resolveSwiftArtifacts.ts";
+
+test("detects the required wasm Swift flag sequence", () => {
+  expect(
+    hasRequiredWasmFlags([
+      "build",
+      "--swift-sdk",
+      "swift-6.3.1-RELEASE_wasm",
+      "-c",
+      "release",
+      ...requiredWasmSwiftFlags,
+      "-Xlinker",
+      "--initial-memory=1",
+    ])
+  ).toBe(true);
+
+  expect(
+    hasRequiredWasmFlags([
+      "build",
+      "--swift-sdk",
+      "swift-6.3.1-RELEASE_wasm",
+      "-c",
+      "release",
+      "-Xswiftc",
+      "-Osize",
+      "-Xswiftc",
+      "-disable-llvm-merge-functions-pass",
+    ])
+  ).toBe(false);
+});
+
+test("formats commands for readable CI logs", () => {
+  expect(
+    formatCommandForLogs([
+      "swiftly",
+      "run",
+      "swift",
+      "build",
+      "--package-path",
+      "/tmp/My Project",
+      "-Xlinker",
+      "stack-size=1048576",
+    ])
+  ).toBe(
+    "swiftly run swift build --package-path '/tmp/My Project' -Xlinker stack-size=1048576"
+  );
+});
+
+test("emits explicit CI log lines for flag confirmation and commands", () => {
+  const lines = wasmBuildConfigurationLogLines({
+    configuration: "release",
+    packagePath: "/tmp/pkg",
+    product: "WebExampleApp",
+    swiftlyWorkingDirectory: "/tmp",
+    buildCommand: ["swiftly", "run", "swift", "build", "--product", "WebExampleApp"],
+    showBinPathCommand: ["swiftly", "run", "swift", "build", "--show-bin-path"],
+  });
+
+  expect(lines).toContain("WASM_REQUIRED_FLAGS_CONFIRMED=true");
+  expect(lines).toContain("WASM_BUILD_CONFIGURATION_NAME=release");
+  expect(lines).toContain(
+    "WASM_REQUIRED_FLAGS=-Xswiftc -Osize -Xswiftc -Xfrontend -Xswiftc -disable-llvm-merge-functions-pass"
+  );
+  expect(lines).toContain(
+    'WASM_BUILD_COMMAND_ARGS_JSON=["swiftly","run","swift","build","--product","WebExampleApp"]'
+  );
+  expect(lines).toContain(
+    'WASM_SHOW_BIN_PATH_COMMAND_ARGS_JSON=["swiftly","run","swift","build","--show-bin-path"]'
+  );
+});
+
+test("marks required release flags as skipped for debug wasm builds", () => {
+  const lines = wasmBuildConfigurationLogLines({
+    configuration: "debug",
+    packagePath: "/tmp/pkg",
+    product: "WebExampleApp",
+    swiftlyWorkingDirectory: "/tmp",
+    buildCommand: ["swiftly", "run", "swift", "build", "-c", "debug"],
+    showBinPathCommand: ["swiftly", "run", "swift", "build", "-c", "debug", "--show-bin-path"],
+  });
+
+  expect(lines).toContain("WASM_BUILD_CONFIGURATION_NAME=debug");
+  expect(lines).toContain("WASM_REQUIRED_FLAGS_CONFIRMED=skipped");
+});