@coasys/ad4m-test: multiple compatibility issues preventing language development

[HexaField]

Summary

@coasys/ad4m-test (all published versions 0.8.0–0.11.1) has multiple issues that prevent it from working out of the box for developing and testing AD4M languages. These were discovered while building nextgraph-adam-language and are addressed in PR #670.

Issues

1. No compiled output shipped (all versions)

The npm package ships TypeScript source only — no build/ directory. The bin field points to build/cli.js which does not exist. Users must manually compile with npx tsc --noImplicitAny false.

Fix: Add build/ to the files field and ensure prepublishOnly runs tsc.

2. CLI flag names don't match executor (since v0.10.1)

The test runner passes --dataPath, --languageLanguageOnly etc. but the executor expects kebab-case: --data-path, --language-language-only. The serve subcommand was also renamed to run.

3. GitHub API URL uses wrong org

Binary download URL references perspect3vism/ad4m but releases are at coasys/ad4m. Also no error handling on the API response (crashes on 403/rate-limit).

4. Binary download URL pattern mismatch

Code constructs URL with -linux- separator but the actual release asset uses _linux_ (ad4m-cli-executor-linux_0.11.1_amd64). Binary download silently fails.

5. Init detection only checks stdout

The executor logs "AD4M init complete" via Rust log::info! to stderr, but the test runner only watches stdout. This causes a 10-minute hang until timeout.

6. System language bundles are CJS

The executor uses a Deno JS runtime that requires ESM modules. All downloaded system language bundles (Language Language, agent-expression-store, etc.) are CJS and crash with ReferenceError: exports is not defined.

7. Language Language bundle references removed IPFS

context.IPFS.add() is called during languagePublish but IPFS has been completely removed from the executor. This crashes language publishing.

8. Missing bootstrapSeed.json

The executor requires a bootstrap seed with the Language Language bundle, but the test runner doesn't create one, resulting in "No Language Language installed!" errors.

9. SSH-only git dependencies in lockfile

appdata-path dependency uses SSH URLs (git@github.com:perspect3vism/...) which fail in CI environments without SSH keys configured.

10. Node builtin imports need node: prefix

Language bundles that use Node builtins (e.g. require("path"), require("fs")) crash in the Deno runtime. They need node:path, node:fs etc.

Current Workaround

A comprehensive patch script handles all of these: see the patch script and the CI workflow.

Related

• PR fix(test-runner): update ad4m-test for v0.10.1+ compatibility #670 — fixes issues 1–5, 8–9 in the test-runner source
• Issues 6, 7, 10 require bundle post-processing (CJS→ESM conversion, IPFS removal, node: prefix) which is done in the patch script

/cc @lucksus @data-coasys

[HexaField]

PR #670 has been merged 🎉 — this addresses issues 1–5, 8–9 from the list above.

Remaining items (6, 7, 10) require bundle post-processing that can't be fixed in the test-runner itself:

• 6. CJS → ESM conversion — system language bundles ship as CJS but the Deno runtime needs ESM
• 7. IPFS references in Language Language — context.IPFS.add() calls crash since IPFS was removed from the executor
• 10. Node builtin imports — bundles use require('path') etc. which need node: prefix for Deno

These are currently handled by a patch script run in CI. The proper fix would be either:

1. Republishing the system language bundles as ESM with IPFS removed, or
2. Adding a post-download transform step to @coasys/ad4m-test itself (so users don't need their own patch script)

Option 2 could be done as a follow-up PR — the transform logic already exists and is proven in CI. Happy to put that together if that's the preferred path. ⬡

[HexaField]

PR #670 has been merged 🎉 — this addresses issues 1–5, 8–9 from the list above.

Remaining items (6, 7, 10) require bundle post-processing that can't be fixed in the test-runner itself:

• 6. CJS → ESM conversion — system language bundles ship as CJS but the Deno runtime needs ESM
• 7. IPFS references in Language Language — context.IPFS.add() calls crash since IPFS was removed from the executor
• 10. Node builtin imports — bundles use require('path') etc. which need node: prefix for Deno

These are currently handled by a patch script run in CI. The proper fix would be either:

1. Republishing the system language bundles as ESM with IPFS removed, or
2. Adding a post-download transform step to @coasys/ad4m-test itself (so users don't need their own patch script)

Option 2 could be done as a follow-up PR — the transform logic already exists and is proven in CI. Happy to put that together if that's the preferred path. ⬡