wasm-platform-kit-build 0.0.0-stage → 0.2.0

package/tools/component.mjs

@@ -0,0 +1,269 @@
+// Host-owned build pipeline: accepts Wasm and WIT, never plugin JavaScript.
+// ref:DEC-host-sdk-direct-haskell
+import {execFileSync} from 'node:child_process';
+import {format} from 'prettier';
+import {declarations} from './facade.mjs';
+import {registerLocalNative} from './native.mjs';
+import braceStyle from 'prettier-plugin-brace-style';
+import {
+  readFile,
+  writeFile,
+  mkdir,
+  readdir,
+  copyFile,
+  rm,
+  cp,
+} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {generatorPath, runtimeRoot, jcoRoot, toolchainRoot} from './paths.mjs';
+/** Identifies exact artifact bytes so the runtime can reject changed components. */
+export const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const run = (tool, args) =>
+  execFileSync(tool, args, {stdio: 'pipe', maxBuffer: 32 * 1024 * 1024});
+const toolroot = toolchainRoot;
+const wasmTools = path.join(toolroot, 'wasmtime/bin/wasm-tools');
+
+/** Builds and registers executable glue from Wasm; callers never provide JavaScript. */
+export async function packageComponent({
+  core,
+  wit,
+  world,
+  directory,
+  generated,
+  interfaceName,
+  component,
+  requirements = [],
+})
+{
+  if (
+    !Array.isArray(requirements) ||
+    requirements.some(
+      requirement =>
+        !requirement ||
+        typeof requirement.provider !== 'string' ||
+        !requirement.provider ||
+        ![
+          'files',
+          'network',
+          'storage',
+          'environment',
+          'ui',
+          'native',
+        ].includes(requirement.kind),
+    )
+  )
+    throw new Error('invalid informational capability requirements');
+  await rm(directory, {recursive: true, force: true});
+  await mkdir(directory, {recursive: true});
+  const target = path.join(directory, 'component.wasm');
+  if (component) await copyFile(component, target);
+  else
+  {
+    run(generatorPath(), [
+      'remap',
+      core,
+      path.join(directory, 'remapped.wasm'),
+      path.join(generated, 'symbols.json'),
+    ]);
+    run(path.join(toolroot, 'binaryen/bin/wasm-merge'), [
+      path.join(directory, 'remapped.wasm'),
+      'guest',
+      path.join(generated, 'initialize.wat'),
+      'init',
+      '--all-features',
+      '--disable-compact-imports',
+      '-o',
+      path.join(directory, 'initialized.wasm'),
+    ]);
+    run(wasmTools, [
+      'component',
+      'embed',
+      wit,
+      path.join(directory, 'initialized.wasm'),
+      '-w',
+      world,
+      '-o',
+      path.join(directory, 'embedded.wasm'),
+    ]);
+    run(wasmTools, [
+      'component',
+      'new',
+      path.join(directory, 'embedded.wasm'),
+      '--adapt',
+      `wasi_snapshot_preview1=${path.join(jcoRoot(), 'lib/wasi_snapshot_preview1.reactor.wasm')}`,
+      '-o',
+      target,
+    ]);
+    for (const name of ['remapped.wasm', 'initialized.wasm', 'embedded.wasm'])
+      await rm(path.join(directory, name));
+  }
+  run(wasmTools, ['validate', target]);
+  const actualWit = run(wasmTools, ['component', 'wit', target]).toString();
+  const schemaPath = path.join(directory, 'interface.wit');
+  await writeFile(schemaPath, actualWit);
+  const contract = JSON.parse(
+    run(generatorPath(), ['schema', schemaPath, 'root']),
+  );
+  await rm(schemaPath);
+  if (!contract.interfaces[interfaceName])
+    throw new Error('unknown application interface');
+  const asyncExports = Object.keys(contract.interfaces[interfaceName]).map(
+    name => `${interfaceName}#${name}`,
+  );
+  run(process.execPath, [
+    path.join(jcoRoot(), 'dist/jco.js'),
+    'transpile',
+    target,
+    '-o',
+    directory,
+    '--name',
+    'guest',
+    '--instantiation',
+    'async',
+    '--no-wasi-shim',
+    '--base64-cutoff',
+    '0',
+    '--strict',
+    '--async-mode',
+    'jspi',
+    '--async-imports',
+    'host:sdk/host@0.2.0#perform',
+    '--async-exports',
+    ...asyncExports,
+  ]);
+  const mapping = path.join(directory, 'bounds.json');
+  await writeFile(
+    mapping,
+    JSON.stringify({memoryBytes: 256 * 1024 * 1024, imports: {}, exports: {}}),
+  );
+  const assets = {};
+  let memoryBudget = 0;
+  for (const name of await readdir(directory))
+  {
+    if (name.endsWith('.wasm') && name !== 'component.wasm')
+    {
+      const budget = JSON.parse(
+        run(generatorPath(), [
+          'remap',
+          path.join(directory, name),
+          path.join(directory, name + '.bounded'),
+          mapping,
+        ]),
+      );
+      memoryBudget += budget.memory;
+      await copyFile(
+        path.join(directory, name + '.bounded'),
+        path.join(directory, name),
+      );
+      await rm(path.join(directory, name + '.bounded'));
+    }
+    if (name.endsWith('.js') || name.endsWith('.wasm'))
+      assets[name] = digest(await readFile(path.join(directory, name)));
+  }
+  await rm(mapping);
+  const manifest = {
+    version: 1,
+    sdk: '0.2.0',
+    component: 'component.wasm',
+    sha256: assets['component.wasm'],
+    interface: interfaceName,
+    contract,
+    assets,
+    browser: {jspi: true, memory: memoryBudget},
+    generators: {
+      witParser: '0.263.0',
+      jco: '1.41.0',
+      bindings: 'wit-haskell-0.2.0',
+    },
+    requirements: structuredClone(requirements),
+    providers: digest(
+      Buffer.concat(
+        await Promise.all(
+          [
+            'policy.mjs',
+            'node.mjs',
+            'browser.mjs',
+            'worker.mjs',
+            'client.mjs',
+          ].map(name => readFile(path.join(runtimeRoot(), name))),
+        ),
+      ),
+    ),
+  };
+  await writeFile(
+    path.join(directory, 'manifest.json'),
+    JSON.stringify(manifest, null, 2) + '\n',
+  );
+  await registerLocalNative({directory, component: target});
+  const registration = digest(JSON.stringify(manifest));
+  const runtime = path.join(directory, 'runtime');
+  await mkdir(runtime, {recursive: true});
+  for (const name of ['browser.mjs', 'worker.mjs', 'policy.mjs', 'client.mjs'])
+    await copyFile(path.join(runtimeRoot(), name), path.join(runtime, name));
+  await cp(
+    path.join(runtimeRoot(), 'assets/wasi'),
+    path.join(runtime, 'assets/wasi'),
+    {recursive: true},
+  );
+  await writeFile(
+    path.join(directory, 'worker.mjs'),
+    `// Host-generated allowlist. Plugin manifests cannot modify it.\nimport {startWorker} from './runtime/worker.mjs';\nstartWorker(${JSON.stringify([registration])});\n`,
+  );
+  await writeFile(
+    path.join(directory, 'browser.mjs'),
+    `// Generated embedding entrypoint.\nimport {createHost} from './runtime/browser.mjs';\nimport {createClient} from './runtime/client.mjs';\nconst contract = ${JSON.stringify(contract)};\nexport const createApplication = async (options = {}) => createClient(await createHost({...options, manifest: new URL('./manifest.json', import.meta.url), registration: {manifests: ${JSON.stringify([registration])}, workerURL: new URL('./worker.mjs', import.meta.url)}}), contract, ${JSON.stringify(interfaceName)});\n`,
+  );
+  await writeFile(
+    path.join(directory, 'node.mjs'),
+    `// Generated Node entrypoint.\nimport {createHost} from 'wasm-platform-kit';\nimport {nativeArtifacts} from './node-registration.mjs';\nimport {createClient} from './runtime/client.mjs';\nconst contract = ${JSON.stringify(contract)};\nexport const createApplication = async (options = {}) => createClient(await createHost({...options, nativeArtifacts, manifest: new URL('./manifest.json', import.meta.url)}), contract, ${JSON.stringify(interfaceName)});\n`,
+  );
+  const types = declarations(contract, interfaceName);
+  for (const file of ['node.d.mts', 'browser.d.mts'])
+    await writeFile(path.join(directory, file), types);
+  for (const file of [
+    'worker.mjs',
+    'browser.mjs',
+    'node.mjs',
+    'node-registration.mjs',
+    'install.mjs',
+    'node.d.mts',
+    'browser.d.mts',
+  ])
+  {
+    const target = path.join(directory, file);
+    await writeFile(
+      target,
+      await format(await readFile(target, 'utf8'), {
+        filepath: target,
+        printWidth: 80,
+        tabWidth: 2,
+        singleQuote: true,
+        bracketSpacing: false,
+        trailingComma: 'all',
+        arrowParens: 'avoid',
+        plugins: [braceStyle],
+        braceStyle: 'allman',
+      }),
+    );
+  }
+  await writeFile(
+    path.join(directory, 'deployment.json'),
+    JSON.stringify(
+      {
+        standard: {
+          'Content-Security-Policy':
+            "default-src 'self'; script-src 'self' blob: 'wasm-unsafe-eval'; worker-src 'self'; connect-src 'self'",
+        },
+        isolated: {
+          'Cross-Origin-Opener-Policy': 'same-origin',
+          'Cross-Origin-Embedder-Policy': 'require-corp',
+        },
+      },
+      null,
+      2,
+    ),
+  );
+  return manifest;
+}

package/tools/facade.mjs

@@ -0,0 +1,133 @@
+// Generated public declarations come from the same resolved WIT as the runtime.
+// ref:DEC-host-sdk-typed-application-boundary
+const camel = name =>
+  name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+const pascal = name =>
+{
+  const value = camel(name);
+  return value[0].toUpperCase() + value.slice(1);
+};
+/** Emits an asynchronous application API with opaque resource types. */
+export function declarations(contract, interfaceName)
+{
+  const resultType = type =>
+  {
+    if (typeof type !== 'number') return undefined;
+    const kind = contract.types[type].kind;
+    return kind.type !== undefined ? resultType(kind.type) : kind.result;
+  };
+  const functions = Object.values(contract.interfaces[interfaceName]);
+  const visited = new Set();
+  const names = new Map();
+  function typeName(id)
+  {
+    const name = contract.types[id].name;
+    const label = name ? pascal(name) : `Type${id}`;
+    if (names.has(label) && names.get(label) !== id)
+      throw new Error('unsupported: colliding façade type names');
+    names.set(label, id);
+    return label;
+  }
+  function type(ty)
+  {
+    if (ty == null) return 'void';
+    if (typeof ty === 'string')
+    {
+      const value = {
+        string: 'string',
+        bool: 'boolean',
+        u8: 'number',
+        s8: 'number',
+        u16: 'number',
+        s16: 'number',
+        u32: 'number',
+        s32: 'number',
+        u64: 'bigint',
+        s64: 'bigint',
+      }[ty];
+      if (!value) throw new Error('unsupported façade scalar ' + ty);
+      return value;
+    }
+    if (contract.types[ty].kind.type !== undefined)
+      return type(contract.types[ty].kind.type);
+    if (visited.has(ty)) return typeName(ty);
+    visited.add(ty);
+    const {kind} = contract.types[ty];
+    if (kind === 'resource') return typeName(ty);
+    // Traverse every referenced type now, including error types exposed by WIT.
+    expression(kind);
+    return typeName(ty);
+  }
+  function expression(kind)
+  {
+    if (kind.type !== undefined) return type(kind.type);
+    if (kind.handle) return type(kind.handle.own ?? kind.handle.borrow);
+    if (kind.list !== undefined)
+      return kind.list === 'u8' ? 'Uint8Array' : `Array<${type(kind.list)}>`;
+    if (kind.option !== undefined) return `(${type(kind.option)} | null)`;
+    if (kind.result)
+      return `{tag: 'ok'; val: ${type(kind.result.ok)}} | {tag: 'err'; val: ${type(kind.result.err)}}`;
+    if (kind.record)
+      return `{${kind.record.fields.map(field => `${JSON.stringify(camel(field.name))}: ${type(field.type)}`).join('; ')}}`;
+    if (kind.variant)
+      return kind.variant.cases
+        .map(
+          item =>
+            `{tag: ${JSON.stringify(item.name)}${item.type == null ? '' : `; val: ${type(item.type)}`}}`,
+        )
+        .join(' | ');
+    if (kind.enum)
+      return kind.enum.cases.map(item => JSON.stringify(item.name)).join(' | ');
+    throw new Error('unsupported façade type');
+  }
+  function signature(fn, method = false)
+  {
+    if (method) type(fn.params[0].type);
+    const params = fn.params
+      .slice(method ? 1 : 0)
+      .map(param => `${camel(param.name)}: ${type(param.type)}`);
+    params.push('controls?: {signal?: AbortSignal}');
+    const result = resultType(fn.result);
+    // Record the error schema too, while Promise rejection carries the failure.
+    type(fn.result);
+    return `(${params.join(', ')}): Promise<${type(result ? result.ok : fn.result)}>`;
+  }
+  const operations = functions
+    .filter(fn => fn.kind?.method === undefined)
+    .map(fn =>
+    {
+      const name = fn.name.startsWith('[constructor]')
+        ? 'new' + pascal(fn.name.slice(13))
+        : camel(fn.name.replace(/^\[static\]/, '').replace('.', '-'));
+      if (
+        ['identity', 'invoke', 'drop', 'close', 'revoke', 'then'].includes(name)
+      )
+        throw new Error('unsupported: export conflicts with client lifecycle');
+      return `${JSON.stringify(name)}${signature(fn)};`;
+    });
+  for (const fn of functions) signature(fn, fn.kind?.method !== undefined);
+  const types = [];
+  for (const id of visited)
+  {
+    const {kind} = contract.types[id];
+    if (kind === 'resource')
+    {
+      const methods = functions
+        .filter(fn => fn.kind?.method === id)
+        .map(fn =>
+        {
+          const name = camel(fn.name.split('.')[1]);
+          if (name === 'dispose' || name === 'then')
+            throw new Error(
+              'unsupported: resource method conflicts with disposal',
+            );
+          return `${JSON.stringify(name)}${signature(fn, true)};`;
+        });
+      types.push(
+        `export interface ${typeName(id)} {readonly [resourceBrand]: ${JSON.stringify(typeName(id))}; dispose(controls?: {signal?: AbortSignal}): Promise<void>; ${methods.join('\n')}}`,
+      );
+    }
+    else types.push(`export type ${typeName(id)} = ${expression(kind)};`);
+  }
+  return `// Generated from resolved WIT. Do not edit.\nimport type {HostInstance, HostOptions} from 'wasm-platform-kit';\ndeclare const resourceBrand: unique symbol;\n${types.join('\n')}\nexport interface Application extends HostInstance {${operations.join('\n')}}\nexport function createApplication(options?: Omit<HostOptions, 'manifest' | 'nativeArtifacts'>): Promise<Application>;\n`;
+}