# Emscripten Env Audit

> Static analysis of Emscripten build flags targeting AudioWorkletGlobalScope. Parses a Makefile or build script, extracts emcc flags, and cross-references against a known list of APIs unavailable in the worklet environment. Flags configuration patterns that will cause runtime failures in the browser.

- **Type:** Skill
- **Install:** `agentstack add skill-gertsylvest-meta-team-emscripten-env-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gertsylvest](https://agentstack.voostack.com/s/gertsylvest)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gertsylvest](https://github.com/gertsylvest)
- **Source:** https://github.com/gertsylvest/meta-team/tree/main/library/skills/emscripten-env-audit

## Install

```sh
agentstack add skill-gertsylvest-meta-team-emscripten-env-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Emscripten Environment Audit

Parse Emscripten build flags and flag configuration patterns that cause runtime failures in `AudioWorkletGlobalScope`. Designed to catch the class of errors that require a full browser session to surface otherwise — `self is not defined`, `fetch is not a function`, `registerProcessor` not called — before any code is written or rebuilt.

This skill encodes the compatibility research that took ~3–4 hours of iterative debugging in Sprint 5 of faust-poc1. A 30-minute research session reading the Emscripten GitHub issues and MDN AudioWorkletGlobalScope docs would have identified all five failure modes before the first `make synth-wasm`.

## Requirements

- Python 3.8+ (for the audit script)
- The Makefile or shell script containing the `emcc` invocation

## Instructions

Arguments are in `$ARGUMENTS`. Pass them directly to the audit script:

```bash
python3 "$(dirname "$0")/audit.py" $ARGUMENTS
```

## Checks performed

| Check | Severity | Pattern detected |
|-------|----------|-----------------|
| `MODULARIZE=1` | **ERROR** | Wraps `--post-js` content inside the factory function body. `registerProcessor()` never executes at top level. |
| `ENVIRONMENT=web` or `ENVIRONMENT=node` | **ERROR** | Wrong environment for a worklet target. Emscripten will emit DOM access code or Node.js-specific code. |
| No `--pre-js` with `self` polyfill | **WARN** | `ENVIRONMENT=worker` assumes `self` is defined. `AudioWorkletGlobalScope` does not expose it. |
| No `--pre-js` with `self.location` polyfill | **WARN** | Emscripten reads `self.location.href` for WASM path resolution. Absent in worklet scope. |
| No `instantiateWasm` hook pattern | **WARN** | Emscripten's default WASM loading calls `fetch()`. `fetch` is unavailable in `AudioWorkletGlobalScope`. |
| `ALLOW_MEMORY_GROWTH=1` without buffer re-read note | **INFO** | `HEAPF32.buffer` is invalidated on memory growth. Safe if `HEAPF32.buffer` is re-read on each `process()` call. |
| `EXPORT_NAME` without `MODULARIZE` | **INFO** | `EXPORT_NAME` is only meaningful with `MODULARIZE=1`. Has no effect without it. |
| Missing `--pre-js` or `--post-js` for worklet target | **WARN** | Both are typically needed: `--pre-js` for polyfills, `--post-js` to bundle the `AudioWorkletProcessor` class. |

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `--var NAME` | auto-detect | Makefile variable name holding the emcc flags (e.g. `WASM_FLAGS`). Auto-detected by scanning for `emcc` invocations if omitted. |
| `--env TYPE` | `audioworklet` | Target environment (`audioworklet`, `worker`, `web`, `node`). Determines which checks apply. Use `audioworklet` for Emscripten + AudioWorklet targets. |

## Exit codes

- `0` — no errors (warnings and infos do not fail)
- `1` — one or more ERROR-level findings

## Examples

```bash
# Audit a Makefile with default auto-detection
python3 audit.py Makefile

# Specify the variable name explicitly
python3 audit.py Makefile --var WASM_FLAGS

# Audit a shell build script
python3 audit.py build_wasm.sh
```

## Known limitations

- **Static analysis only**: The audit reads flag strings. It cannot evaluate Make variables that are computed dynamically (e.g. `$(shell ...)`), variables defined in included files, or flags set by environment variables at build time.
- **`--pre-js` content not inspected**: The audit detects the presence of `--pre-js` but does not parse its content to verify the polyfills are correct. After the audit, verify the `pre.js` file includes `self`, `self.location`, and a `Module.instantiateWasm` hook.
- **No cross-file analysis**: If `emcc` is invoked in a script that sources another file for flags, only the top-level file is inspected.

## AudioWorkletGlobalScope quick reference

APIs that differ from a standard Worker (the closest `ENVIRONMENT` option):

| API | Worker | AudioWorkletGlobalScope | Emscripten impact |
|-----|--------|------------------------|-------------------|
| `self` | Yes | **No** | Runtime crash; polyfill in `--pre-js` |
| `self.location.href` | Yes | **No** | Path resolution crash; polyfill in `--pre-js` |
| `fetch()` | Yes | **No** | WASM loading fails; use main-thread compile + `processorOptions` |
| `XMLHttpRequest` | Yes | **No** | WASM loading fallback fails; same fix as `fetch` |
| `setTimeout` / `setInterval` | Yes | **No** | Cannot use for timing in worklet |
| `registerProcessor()` | No | Yes | Must run at top-level scope; `MODULARIZE=1` prevents this |
| `WebAssembly.instantiate(module, imports)` | Yes | Yes | Works; requires pre-compiled module (no fetch for bytes) |
| `console.log` / `console.error` | Yes | Yes | Works normally |
| `performance.now()` | Yes | **No** | Emscripten may reference; not confirmed as a failure in testing |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gertsylvest](https://github.com/gertsylvest)
- **Source:** [gertsylvest/meta-team](https://github.com/gertsylvest/meta-team)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gertsylvest-meta-team-emscripten-env-audit
- Seller: https://agentstack.voostack.com/s/gertsylvest
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.