Matrix Package Lifecycle

Appearance

Refresh without copying ​

When iterating on a package that runs inside a long-lived Host, you don't always want to stop the Host. The repo provides two paths for "rebuild and reload one package":

  1. matrix up <abs-path> against a folder-backed runtime — restart only that runtime.
  2. hivecast operator refresh-host-package — install the rebuilt source into the Host's package store and restart its runtime.

Path 1 — folder-backed matrix up reload ​

If the runtime started from a folder path, you can stop and restart just that one runtime:

bash
# Source already running
hivecast status --home /tmp/matrix-home

# Rebuild
cd projects/matrix-3/packages/<my-pkg>
pnpm build

# Stop just this one runtime
matrix down <runtime-id> --home /tmp/matrix-home

# Bring it back up — same folder, freshly imported dist/
matrix up /abs/path/to/projects/matrix-3/packages/<my-pkg> \
  --env hivecast --home /tmp/matrix-home

Source: host-service/src/cli.ts:145-265. The runtime record captures the directory; restart re-imports runtime.entry from disk.

This path doesn't change anything in <host-home>/packages/. It's appropriate when:

  • You want to test against the live Host (gateway, NATS, neighbors).
  • The change is your own package's source.
  • You're not validating install lifecycle hooks.

Path 2 — hivecast operator refresh-host-package ​

This script (packages/hivecast/scripts/refresh-host-package.js, registered in packages/hivecast/bin/hivecast.mjs:73-76) rebuilds a package, copies it into a Host's package store, and optionally restarts the runtime supervising it.

bash
hivecast operator refresh-host-package \
  --package @open-matrix/<my-pkg> \
  --home /tmp/matrix-home \
  --restart

Common flags:

FlagPurpose
--package <name> or positional <package-dir>Which package to refresh
--home <path>Host home; defaults to ~/.matrix
--store <name>system or global; defaults to whichever store currently holds the package
--runtime-id <id>Restart this specific runtime; defaults to whatever is registered for the package
--restartStop+start the runtime after the copy
--matrix-bin <path>Path to the mx-cli binary; default uses the wrapper-bundled one

This is the closest to "production refresh". The runtime sees an installed copy, so it exercises the same code path as a registry install. Use this when:

  • You're checking that the install hooks (validate, migrate, seed, verify) work end-to-end.
  • You want to verify behavior of the runtime against the real Host package store (e.g. for screenshots in a bug report).
  • You need the runtime restart but don't want to bounce the Host.

What does NOT refresh on its own ​

  • Host configuration. host.json is read at Host startup. Hand edits require hivecast stop and hivecast start.
  • Browser tabs. A reload of dist/browser/ triggers a refresh of the asset endpoint, but a tab that already loaded old JS keeps it in memory until you reload the page.
  • NATS credentials. Refresh credentials with mx refresh-credentials --home <home> if a HiveCast pairing changed; do not edit credential files by hand.
  • Default runtime list. Adding a new package to the hostDefaultRuntimeTargets array (packages/hivecast/bin/hivecast.mjs:28-39) requires a fresh hivecast install to seed the new entry.

Don't hand-copy into <host-home>/packages/ ​

CLAUDE.md "ONE DEPLOY PATH" and "NEVER hand-edit container daemon.json": always go through the documented commands. Manual copies into <host-home>/packages/.../node_modules/ skip the install hooks, leave the Host's view of system.runtimes inconsistent, and have caused crash loops in the past.

If you must work outside the documented commands, file a one-off script under the owning package and document it (CLAUDE.md "Package, publish, installer, and deploy operations must be discoverable through documented CLI commands").

See also ​

Source:projects/matrix-3/packages/hivecast/scripts/refresh-host-package.js is the canonical refresh script; packages/hivecast/bin/hivecast.mjs:73-76 registers it as hivecast operator refresh-host-package.