Packaging
One macaron-artifacts package, one CLI, and a prebuilt unified WebUI.
The repository root publishes exactly one package: macaron-artifacts. Its only CLI is bin/macaron-artifacts.mjs; choose Claude Code, Codex, OpenCode, pi, Hermes, or OpenClaw inside the running application.
Package contents
The package contains the launcher, the prebuilt artifacts/dist server and WebUI, the generated UI4A skill, and the current README. Starting the installed package does not invoke Vite or compile source files.
bunx macaron-artifactsThe launcher serves UI and API on http://127.0.0.1:43860 by default and accepts --port, --data-dir, --host, --password, --public-origin, and --pair. CLI options override their environment variables. Set MACARON_PASSWORD or pass --password for password protection; non-loopback listening or a non-loopback public origin requires it. See remote access for SSH forwarding and HTTPS reverse proxy configuration.
Runtime boundary
| Module | Responsibility |
|---|---|
artifacts/src/server/harnesses | Native lifecycle and event normalization for six harnesses |
artifacts/src/server/conversations.ts | Turn lifecycle, streaming, approvals, cancellation, and persistence |
artifacts/src/server/profiles.ts | Private Profile storage and per-turn resolution |
artifacts/src/server/pairing.ts | One-time hosted WebUI pairing grants |
artifacts/src/web/chat | Stable per-session Chat instances and reconnection |
artifacts/src/web/ui4a | Progressive inline and Canvas rendering |
artifacts/src/web/theme | Shiki workbench roles and semantic interface tokens |
A new harness implements HarnessAdapter and registers its capabilities. It does not add another package, launcher, SPA, sidebar, or Canvas path.
npm releases
.github/workflows/publish.yml publishes stable v* tags using npm Trusted Publishing. The tag must match the root package.json version and point to a commit already on main. The workflow runs type checks and tests, builds a tarball, installs and starts that tarball in isolation, then publishes the same file to npm's latest tag with provenance. Releases run serially without cancelling an active publish; prerelease versions are rejected.
Before the first automated release:
- Run
npm login --registry=https://registry.npmjs.organd complete browser authentication. - From the repository root, run the commands below to publish the tested tarball. This first manual release creates the npm package so its publisher can be configured.
- In the npm package settings, add a GitHub Actions trusted publisher with organization
mindverse-ltd, repositorymacaron-artifacts, workflow filenamepublish.yml, and allowed actionnpm publish. Leave the environment name empty; this workflow does not use a GitHub environment.
(
set -eu
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
release_dir="$(mktemp -d)"
npm pack --pack-destination "$release_dir"
release_version="$(node -p 'require("./package.json").version')"
MACARON_PACKAGE_SOURCE="$release_dir/macaron-artifacts-$release_version.tgz" pnpm test:package
npm publish "$release_dir/macaron-artifacts-$release_version.tgz"
)Subsequent releases need only a new root package version committed to main and the matching v<version> tag pushed to GitHub. Each version can be published once; do not rerun a successful publish for that version. No npm token secret is required. GitHub-hosted runners and npm 11.5.1 or newer are required for Trusted Publishing. The workflow has read-only Git permissions and publishes the tagged commit without creating another commit or tag during the run.
After the initial manual package publication, bump the root package to the next stable version on main before pushing its matching v<version> tag for the first automated release. Leave --tag unset so npm's default-tag check prevents an older version from replacing latest.
Release and updates
.github/workflows/pkg-pr-new.yml publishes the root package for each preview commit. Install a newer successful preview URL to update the application; conversation data remains in MACARON_DATA_DIR.
.github/workflows/pkg-pr-new.yml builds and publishes only the repository root:
pnpm exec pkg-pr-new publish --bin .After the first npm release exposes the package's repository metadata, pkg.pr.new can also use https://pkg.pr.new/macaron-artifacts@<sha>. It falls back to the full URL while that metadata is unavailable; full URLs remain valid afterward.