{"_id":"@atheory-ai/wasm-plugin-toolkit","_rev":"4-67f06193adfe44250d5145ff4b308262","name":"@atheory-ai/wasm-plugin-toolkit","dist-tags":{"latest":"0.0.4"},"versions":{"0.0.1":{"name":"@atheory-ai/wasm-plugin-toolkit","version":"0.0.1","license":"Apache-2.0","_id":"@atheory-ai/wasm-plugin-toolkit@0.0.1","maintainers":[{"name":"ladyhunterbear","email":"jeremy@atheory.ai"}],"homepage":"https://github.com/atheory-ai/wasm-plugin-toolkit#readme","bugs":{"url":"https://github.com/atheory-ai/wasm-plugin-toolkit/issues"},"bin":{"wasm-toolkit-validate":"bin/wasm-toolkit-validate.mjs"},"dist":{"shasum":"fa26e153a17f8a3581e7d42680a1376509dcb3c1","tarball":"https://registry.npmjs.org/@atheory-ai/wasm-plugin-toolkit/-/wasm-plugin-toolkit-0.0.1.tgz","fileCount":29,"integrity":"sha512-VUyXQWrMJsNiCZkddihW2iKxpVTSzzNKzruy7AJKNwJBhtPZj7cOPZWYL1TCSMLYqeJpqzocfWBRULQ/jcd8jw==","signatures":[{"sig":"MEQCIGeTS2jByrUCQ+Dfwfm+QJfyBa9uimUxzVY94tamVOTsAiAFiQQlJFxegAMr4CqpnJs/w6wlzLLSARhQVFb/Jaqniw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68796},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./build":{"types":"./dist/build/index.d.ts","import":"./dist/build/index.js"},"./sandbox":{"types":"./dist/sandbox/index.d.ts","import":"./dist/sandbox/index.js"},"./validate":{"types":"./dist/validate/index.d.ts","import":"./dist/validate/index.js"},"./test-preset":{"types":"./dist/test-preset/index.d.ts","import":"./dist/test-preset/index.js"}},"gitHead":"ffc4805e54e167f549dde418799b42a34252b338","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","test:watch":"vitest","postinstall":"node bin/install-javy.cjs","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"ladyhunterbear","email":"jeremy@atheory.ai"},"repository":{"url":"git+https://github.com/atheory-ai/wasm-plugin-toolkit.git","type":"git"},"_npmVersion":"11.13.0","description":"Shared TS->WASM build, sandbox, and validate pipeline for atheory-ai plugin SDKs (ce-plugin-sdk, argent-plugin-sdk).","directories":{},"_nodeVersion":"24.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","esbuild":"^0.25.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"peerDependencies":{"esbuild":">=0.20.0"},"peerDependenciesMeta":{"esbuild":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/wasm-plugin-toolkit_0.0.1_1782455128340_0.13975319291845412","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@atheory-ai/wasm-plugin-toolkit","version":"0.0.2","license":"Apache-2.0","_id":"@atheory-ai/wasm-plugin-toolkit@0.0.2","maintainers":[{"name":"ladyhunterbear","email":"jeremy@atheory.ai"}],"homepage":"https://github.com/atheory-ai/wasm-plugin-toolkit#readme","bugs":{"url":"https://github.com/atheory-ai/wasm-plugin-toolkit/issues"},"bin":{"wasm-toolkit-build":"bin/wasm-toolkit-build.mjs","wasm-toolkit-validate":"bin/wasm-toolkit-validate.mjs"},"dist":{"shasum":"e62f345e56abbfd57796422ce639c6e7e3920551","tarball":"https://registry.npmjs.org/@atheory-ai/wasm-plugin-toolkit/-/wasm-plugin-toolkit-0.0.2.tgz","fileCount":30,"integrity":"sha512-ZoQ4ZETkokKiPztrMI3jjWrABwKby6julax1hrgKxg8ia/TwhQviNNHfZfCpDyaMIMx1S4S3r2N2Yc0rhpoDUg==","signatures":[{"sig":"MEYCIQCzphD9RD3rwIhyAFqOnkr7UVSuxZqko5dH8r4Rn6URUQIhAIXhJkB3BguLzabEuRmMnkR0Vmh1oUgg4jNv4CYx8XQW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":71203},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./build":{"types":"./dist/build/index.d.ts","import":"./dist/build/index.js"},"./sandbox":{"types":"./dist/sandbox/index.d.ts","import":"./dist/sandbox/index.js"},"./validate":{"types":"./dist/validate/index.d.ts","import":"./dist/validate/index.js"},"./test-preset":{"types":"./dist/test-preset/index.d.ts","import":"./dist/test-preset/index.js"}},"gitHead":"a7c2421998527974bae017291befe4811efe3199","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","test:watch":"vitest","postinstall":"node bin/install-javy.cjs","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"ladyhunterbear","email":"jeremy@atheory.ai"},"repository":{"url":"git+https://github.com/atheory-ai/wasm-plugin-toolkit.git","type":"git"},"_npmVersion":"11.13.0","description":"Shared TS->WASM build, sandbox, and validate pipeline for atheory-ai plugin SDKs (ce-plugin-sdk, argent-plugin-sdk).","directories":{},"_nodeVersion":"24.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","esbuild":"^0.25.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"peerDependencies":{"esbuild":">=0.20.0"},"peerDependenciesMeta":{"esbuild":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/wasm-plugin-toolkit_0.0.2_1782456439524_0.21013753137589375","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@atheory-ai/wasm-plugin-toolkit","version":"0.0.3","license":"Apache-2.0","_id":"@atheory-ai/wasm-plugin-toolkit@0.0.3","maintainers":[{"name":"ladyhunterbear","email":"jeremy@atheory.ai"}],"homepage":"https://github.com/atheory-ai/wasm-plugin-toolkit#readme","bugs":{"url":"https://github.com/atheory-ai/wasm-plugin-toolkit/issues"},"bin":{"wasm-toolkit-build":"bin/wasm-toolkit-build.mjs","wasm-toolkit-validate":"bin/wasm-toolkit-validate.mjs"},"dist":{"shasum":"a5934823e733e55a990f6b3e7dedfc0cdb286148","tarball":"https://registry.npmjs.org/@atheory-ai/wasm-plugin-toolkit/-/wasm-plugin-toolkit-0.0.3.tgz","fileCount":30,"integrity":"sha512-eIKWpoRMdJgwIluMdATEf7qbC/jijmyoLiEzmDPkNyDHDKJfjkoXZcXwqaaUayn6+zdHxoQSTrpIi7u1UVNanQ==","signatures":[{"sig":"MEQCIHjEX4t3Y8AmuJlVnoCbSL5nz5sa9T7quXfjvkmRwf/7AiBewntH9qAZZdLBCK0ZdU5NcAV5MyqBIndzL6U9quDRCQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72513},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./build":{"types":"./dist/build/index.d.ts","import":"./dist/build/index.js"},"./sandbox":{"types":"./dist/sandbox/index.d.ts","import":"./dist/sandbox/index.js"},"./validate":{"types":"./dist/validate/index.d.ts","import":"./dist/validate/index.js"},"./test-preset":{"types":"./dist/test-preset/index.d.ts","import":"./dist/test-preset/index.js"}},"gitHead":"7050b93a04a2779a5305488c8d543cc4958d74ef","scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist","test:watch":"vitest","postinstall":"node bin/install-javy.cjs","prepublishOnly":"npm run clean && npm run build && npm test"},"_npmUser":{"name":"ladyhunterbear","email":"jeremy@atheory.ai"},"repository":{"url":"git+https://github.com/atheory-ai/wasm-plugin-toolkit.git","type":"git"},"_npmVersion":"11.13.0","description":"Shared TS->WASM build, sandbox, and validate pipeline for atheory-ai plugin SDKs (ce-plugin-sdk, argent-plugin-sdk).","directories":{},"_nodeVersion":"24.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.6.0","esbuild":"^0.25.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"peerDependencies":{"esbuild":">=0.20.0"},"peerDependenciesMeta":{"esbuild":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/wasm-plugin-toolkit_0.0.3_1782456755013_0.1502712196439262","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@atheory-ai/wasm-plugin-toolkit","version":"0.0.4","description":"Shared TS->WASM build, sandbox, and validate pipeline for atheory-ai plugin SDKs (ce-plugin-sdk, argent-plugin-sdk).","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./build":{"import":"./dist/build/index.js","types":"./dist/build/index.d.ts"},"./sandbox":{"import":"./dist/sandbox/index.js","types":"./dist/sandbox/index.d.ts"},"./validate":{"import":"./dist/validate/index.js","types":"./dist/validate/index.d.ts"},"./test-preset":{"import":"./dist/test-preset/index.js","types":"./dist/test-preset/index.d.ts"}},"bin":{"wasm-toolkit-build":"bin/wasm-toolkit-build.mjs","wasm-toolkit-validate":"bin/wasm-toolkit-validate.mjs"},"scripts":{"postinstall":"node bin/install-javy.cjs","build":"tsc -p tsconfig.json","prepublishOnly":"npm run clean && npm run build && npm test","test":"vitest run","test:watch":"vitest","lint":"eslint src --ext .ts","clean":"rm -rf dist"},"peerDependencies":{"esbuild":">=0.20.0"},"peerDependenciesMeta":{"esbuild":{"optional":false}},"devDependencies":{"@types/node":"^20.0.0","esbuild":"^0.25.0","typescript":"^5.4.0","vitest":"^1.6.0"},"engines":{"node":">=20"},"license":"Apache-2.0","homepage":"https://github.com/atheory-ai/wasm-plugin-toolkit#readme","bugs":{"url":"https://github.com/atheory-ai/wasm-plugin-toolkit/issues"},"repository":{"type":"git","url":"git+https://github.com/atheory-ai/wasm-plugin-toolkit.git"},"publishConfig":{"access":"public"},"gitHead":"5ff6fa7526cf5f293e188d502cf1b0c631d194a4","_id":"@atheory-ai/wasm-plugin-toolkit@0.0.4","_nodeVersion":"24.14.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-yC/DKf3LpqU0S+C+h1hbURLloNGZ1XVyFPuB4lLAaPWtswEwRYrKy45hO6UMKHvWUAVB2RsVjVeqWkE329peCQ==","shasum":"14e9c4ae87e23a776a7040809edd8aa6560afaf0","tarball":"https://registry.npmjs.org/@atheory-ai/wasm-plugin-toolkit/-/wasm-plugin-toolkit-0.0.4.tgz","fileCount":30,"unpackedSize":72551,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICAqi277wJYD1Cf6WeX5shgI7M77n68OhINjrrzBfcJ1AiAv6bcSiPIYQ1XlFTnj5DObpTqErvAxrfbntH1QW9d4Qg=="}]},"_npmUser":{"name":"ladyhunterbear","email":"jeremy@atheory.ai"},"directories":{},"maintainers":[{"name":"ladyhunterbear","email":"jeremy@atheory.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wasm-plugin-toolkit_0.0.4_1782458350160_0.7412763384368122"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-26T06:25:28.155Z","modified":"2026-06-26T07:19:10.415Z","0.0.1":"2026-06-26T06:25:28.480Z","0.0.2":"2026-06-26T06:47:19.647Z","0.0.3":"2026-06-26T06:52:35.167Z","0.0.4":"2026-06-26T07:19:10.288Z"},"bugs":{"url":"https://github.com/atheory-ai/wasm-plugin-toolkit/issues"},"license":"Apache-2.0","homepage":"https://github.com/atheory-ai/wasm-plugin-toolkit#readme","repository":{"type":"git","url":"git+https://github.com/atheory-ai/wasm-plugin-toolkit.git"},"description":"Shared TS->WASM build, sandbox, and validate pipeline for atheory-ai plugin SDKs (ce-plugin-sdk, argent-plugin-sdk).","maintainers":[{"name":"ladyhunterbear","email":"jeremy@atheory.ai"}],"readme":"# @atheory-ai/wasm-plugin-toolkit\n\nShared TypeScript-to-WebAssembly **build / sandbox / validate** pipeline for\nthe atheory-ai plugin SDK family.\n\nExtracted from [`ce-plugin-sdk`](https://github.com/atheory-ai/ce-plugin-sdk)\nduring Stage 4 of the\n[harmonization plan](https://github.com/atheory-ai/atheory-ai/blob/main/harmonization-plan.md),\nwhen a second consumer ([`argent-plugin-sdk`](https://github.com/atheory-ai/argent-plugin-sdk),\nplanned) appeared to validate the shape.\n\nThe toolkit is **product-neutral**. It knows how to:\n\n- compile a TS plugin to WASM via esbuild + javy,\n- run a built plugin against a fixture suite,\n- validate that a built plugin's WASM exports match a declared ABI and that\n  its manifest passes a declared schema.\n\nIt deliberately knows **nothing** about Context Engine plugins, argent\nplugins, or whichever product comes next. Consumers wire it to a particular\nproduct via three plug-in points described below.\n\n## The three plug-in points\n\nEach consumer supplies three small modules. They evolve independently — the\nABI is breaking and rare, the host-function module is additive and frequent,\nthe manifest schema lives on a per-registry release cadence.\n\n### 1. `AbiModule` — what the WASM must export\n\nDeclares the WIT world the build pipeline uses to bake exports into the\nbinary, the literal entry-wrapper TypeScript the build pipeline writes\nahead of esbuild, and the export names the validator will look for.\n\n```ts\nimport type { AbiModule } from \"@atheory-ai/wasm-plugin-toolkit\"\n\nexport const ceAbiV1: AbiModule = {\n  name: \"ce-plugin\",\n  abiVersion: 1,\n  wit: `package atheory:ce;\nworld plugin {\n  export ce-plugin-manifest: func();\n  export ce-language-match: func();\n  export ce-language-extract: func();\n  // ...\n}`,\n  entryWrapper: ({ userEntryRelative }) => `\nimport plugin from \"${userEntryRelative}\"\nimport { setPluginDefinition } from \"@atheory-ai/ce-plugin-sdk\"\nimport * as abi from \"@atheory-ai/ce-plugin-sdk/abi\"\nsetPluginDefinition(plugin)\nexport const {\n  cePluginManifest, ceLanguageMatch, ceLanguageExtract, ...\n} = abi\n`,\n  requiredExports: [\n    \"ce-plugin-manifest\",\n    \"ce-language-match\",\n    \"ce-language-extract\",\n    // ...\n  ],\n}\n```\n\n### 2. `HostFunctionModule` — what `__host_*` imports look like\n\nDeclares the import surface a built plugin will need at runtime, plus\nNode-side stubs so the sandbox can run the plugin out-of-engine for tests.\n\n```ts\nimport type { HostFunctionModule } from \"@atheory-ai/wasm-plugin-toolkit\"\n\nexport const ceHostFunctions: HostFunctionModule = {\n  name: \"ce-host\",\n  hostFunctions: [\n    {\n      name: \"__ce_log\",\n      signature: \"(level: string, message: string) => void\",\n      stub: () => undefined,\n    },\n    {\n      name: \"__ce_substrate_query\",\n      signature: \"(queryJSON: string) => string\",\n      stub: () => \"[]\",\n    },\n    // ...\n  ],\n}\n```\n\nToday the sandbox uses these only when the consumer's `PluginLoader` runs\nWASM in-process. For consumers that shell out to a product binary (CE's\ncurrent model: `ce plugin extract`) the engine wires its own host\nfunctions; the descriptor list is then purely informational, used by the\nvalidator to cross-check that manifest `permissions` enumerate every\nimport the WASM actually declares.\n\n### 3. `ManifestSchemaModule` — what the text manifest must contain\n\nDeclares the manifest's filename plus how to parse and validate it. The\ntoolkit doesn't pick a schema language — bring your own (JSON Schema +\najv, zod, hand-rolled, etc.) as long as it implements the small interface.\n\n```ts\nimport type { ManifestSchemaModule } from \"@atheory-ai/wasm-plugin-toolkit\"\n\nexport const cePluginManifest: ManifestSchemaModule = {\n  name: \"ce-plugin\",\n  filename: \"ce-plugin.json\",\n  parse: (raw) => JSON.parse(raw),\n  validate: (m) => {\n    const errors: string[] = []\n    if (!m.id) errors.push(\"id is required\")\n    if (!m.version) errors.push(\"version is required\")\n    // ...\n    return { ok: errors.length === 0, errors, warnings: [], parsed: m }\n  },\n}\n```\n\n## How `ce-plugin-sdk` will consume this\n\n```ts\n// packages/plugin-sdk/scripts/build-plugin.mjs\nimport { buildWasmPlugin } from \"@atheory-ai/wasm-plugin-toolkit/build\"\nimport { ceAbiV1 } from \"../abi/v1.js\"\n\nawait buildWasmPlugin({ pluginDir: process.argv[2], output: process.argv[3], abi: ceAbiV1 })\n```\n\n```ts\n// packages/plugin-sandbox/src/runner/loader.ts — wraps the toolkit's\n// PluginLoader with CE-binary-backed validate/extract calls.\n```\n\n## How `argent-plugin-sdk` will consume this (stub)\n\n```ts\nimport { buildWasmPlugin } from \"@atheory-ai/wasm-plugin-toolkit/build\"\nimport { argentAbiV1 } from \"./abi/v1.js\"  // exports argent.process.*, argent.route.*, …\n\nawait buildWasmPlugin({ pluginDir, output, abi: argentAbiV1 })\n```\n\nThe only difference from CE is the ABI module — same pipeline, different\nWIT world and entry wrapper. That equivalence is the whole reason the\ntoolkit was extracted.\n\n## Package layout\n\n```\nsrc/\n  build/         # esbuild -> javy WASM compilation\n  sandbox/       # fixture runner (consumer-injected loader)\n  validate/      # WASM well-formed + ABI + manifest schema\n  test-preset/   # vitest defineFixtureSuite preset\n  types.ts       # AbiModule, HostFunctionModule, ManifestSchemaModule\nbin/\n  install-javy.js          # postinstall: download javy v8.0.0 binary\n  wasm-toolkit-validate.mjs  # CLI for the validator core\ntests/\n  validate.test.ts  # end-to-end with hand-assembled WASM\n  build.test.ts     # smoke test, javy shimmed\n```\n\n## Install\n\n```bash\npnpm add @atheory-ai/wasm-plugin-toolkit esbuild\n```\n\nThe postinstall hook downloads javy v8.0.0 for your platform from\n[bytecodealliance/javy releases](https://github.com/bytecodealliance/javy/releases).\nSet `WASM_TOOLKIT_SKIP_JAVY=1` to skip (e.g., CI environments that\nprovision javy out of band).\n\n## Trust model\n\nThis package is the **authoring-time** half of the WASM-plugin story.\nSigning prevents substitution; sandboxing prevents misbehavior; the\nvalidator catches obvious shape errors before either matters. See the\nharmonization plan section on\n[\"signing prevents substitution, sandbox prevents misbehavior\"](../harmonization-plan.md#trust-model)\nfor the full framing.\n\n## License\n\nApache-2.0.\n","readmeFilename":"README.md"}