Catalyst Bundle Studio

CLI and web UI for generating websdk bundles of selected @zcatalyst/* packages.

Install

# Global
npm install -g @zcatalyst/websdk-bundler

# Or use without installing
npx @zcatalyst/websdk-bundler

Usage

# Start the server on the default port (3001)
websdk-bundler

# Custom port
websdk-bundler --port 8080

Open http://localhost:<port> in a browser, pick packages and versions, generate, download.

CLI options

| Option | Description | |---|---| | --port <number> | Port to run the server on (default: 3001) | | --help, -h | Show help |

Environment variables

| Variable | Default | Description | |---|---|---| | PORT | 3001 | Server port (also settable via --port) | | HOST | 127.0.0.1 | Interface the server binds to; override only for containerized/hosted deployments | | PACKAGES_CONFIG_URL | built-in default | URL of the remote packages-config JSON allow-list, fetched and cached at startup | | PACKAGES_CONFIG_CHECKSUM_URL | ${PACKAGES_CONFIG_URL}.sha256 | Checksum sidecar for the packages config, verified before trusting it | | NPM_REGISTRY | https://registry.npmjs.org/ | Registry used for npm install during bundle build. Trust boundary — packages resolvable here are implicitly trusted | | API_TOKEN | required | Bearer token required on all /api/* requests; 32–256 chars, 8+ unique chars. Generate with node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" | | REQUIRE_SIGNED_PACKAGES | true | Fails the build if npm audit signatures can't verify installed packages; set false for private registries without signatures | | IDLE_TIMEOUT_MINUTES | 15 | Minutes of API inactivity before the server auto-shuts down | | TRUST_PROXY | false | Set true only behind a reverse proxy, to trust X-Forwarded-For for rate limiting |

Development

Requires Node.js 20.19+ (or 22.12+) and npm 9+.

npm install

# Build frontend (Vite) + server + CLI to build/
npm run build

# Run the compiled server
npm run start

# Run unit tests
npm test

# Watch mode
npm run test:watch

Bundle contents

Each ZIP contains:

• catalyst-bundle.js — minified Rollup output
• manifest.json — per-package version + dependency info, bundle size, file list

License

Apache-2.0 — see LICENSE.