CLI binary requires network access even when @holistics/cli-core is already cached

[khoaanguyenn]

Description

The CLI binary always calls getLatestVersion() (which fetches from https://registry.npmjs.org/@holistics/cli-core) before checking the local cache. This means the binary cannot run offline, even if @holistics/cli-core is already downloaded and cached at ~/.cache/holistics/.

Problem

In src/downloader.ts:

export async function ensureModule(pkg: string, version?: string) {
  if (!version) version = await getLatestVersion(pkg); // ← always hits npm
  const modulePath = getModulePath(pkg, version);
  // ...
}

Since index.ts calls loadModule('@holistics/cli-core') without a version, getLatestVersion() is always invoked. If the network is unavailable, the binary crashes with ConnectionRefused — even though the package is already cached locally.

Impact

This makes it impossible to use the holistics CLI in network-restricted environments such as:

• Docker containers running with --network none
• Air-gapped CI/CD environments
• Pre-baked Docker images where @holistics/cli-core is downloaded at build time but unavailable at runtime
• Production environments where outbound connections to npm registry are not whitelisted

Suggested fix

Two changes to ensureModule in src/downloader.ts:

1. Support a HOLISTICS_CLI_CORE_VERSION env var — if set, skip the npm call entirely and use the specified version from cache
2. Offline fallback — if getLatestVersion() fails (network error), scan the cache directory for any previously downloaded version instead of crashing

This would allow:

# Pin version explicitly (no network call at all)
HOLISTICS_CLI_CORE_VERSION=0.6.13 holistics --version

# Or just work offline if cache exists
holistics --version  # falls back to cached version when npm is unreachable

Steps to reproduce

# 1. Run once to populate cache
holistics --version

# 2. Verify cache exists
ls ~/.cache/holistics/@holistics/cli-core@0.6.13/

# 3. Run without network — crashes
docker run --network none <image-with-holistics> holistics --version
# error: Unable to connect. Is the computer able to access the url?
#   path: "https://registry.npmjs.org/@holistics/cli-core"
#   code: "ConnectionRefused"

[khoaanguyenn]

Workaround: Build a self-contained binary that bundles @holistics/cli-core directly

As an alternative to the runtime download mechanism, we tried installing @holistics/cli-core directly as described in the README:

The CLI core can also be installed as a package from NPM registry with the name @holistics/cli-core. This is possible because we already compiled the code into a single commands.js file, and removed all the private dependencies (check bun_build.sh)

However, bin/holistics.js imports @commander-js/extra-typings which is not declared as a dependency in package.json ("dependencies": {}). A clean install fails:

mkdir test && cd test
npm install @holistics/cli-core
npx holistics --version
# Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@commander-js/extra-typings'

After adding the missing dependency manually, we can compile a fully self-contained binary:

mkdir holistics-build && cd holistics-build
echo '{}' > package.json
bun install @holistics/cli-core @commander-js/extra-typings
bun build node_modules/@holistics/cli-core/bin/holistics.js \
  --compile --outfile holistics --minify --target bun-linux-arm64

Verified: The resulting binary works fully offline:

docker run --network none <image> holistics --version
# 0.6.13

[khanhhuy]

Hi @khoaanguyenn,

Thanks for opening this issue, this is indeed a feature that we planned but not yet implemented for the CLI.

I think we would support pinning the version

HOLISTICS_CLI_CORE_VERSION=0.6.13 holistics

However, this still needs the 1st download to initialize the cache. I took a look at the downloader.ts and think we can create a similar bash script to download the package from NPM.

• At container build time: run the downloader bash script to download the @holistics/cli-core package
• At run time: HOLISTICS_CLI_CORE_VERSION=0.6.13 holistics

[khanhhuy]

Some background context on why the CLI needs to download the latest build:

• When using Holistics app at the browser, it always uses the latest build that includes the AML compiler. For some new features, we generates new AML codes that can only work with the latest version of the compiler
• The AML codes are synced to the customer's Github, then it might be picked up by the CLI for processing. If the CLI does not use the same latest build of the compiler, it wouldn't recognize the new codes and would crash

[khoaanguyenn]

If the CLI does not use the same latest build of the compiler, it wouldn't recognize the new codes and would crash

If we need the CLI always up-to-date AML codes, wouldn't that break if we explicitly pin down CLI core version through environment variable HOLISTICS_CLI_CORE_VERSION, especially when your team updates new AML code?

I took a look at the downloader.ts and think we can create a similar bash script to download the package from NPM.

Note that, due to our hardened security on production site, we can't reach NPM registry to download the latest version in runtime even though we're allowed to download packages during CI build. Would it be possible to download and cache the latest cli-core during CI build so that we don't need to open any connection at all? – if that's possible as of now, could you shed a light on the best practices?

Beside, even though we can make an exception to only allow downloading cli-core from NPM registry while denying all other packages, there remains a risk of supply chain attack if cli-core is unintentionally upgraded its version at runtime because of one of its third-party dependencies have security vulnerability.