feat(cli): activate installed Packages with apply

.lyracore-cli-rev

@@ -1 +1 @@
-950a03ff593722109482ab6dd496e94148ecf709
+65158741481236ab435de54693dd530a4075ad90

CONTEXT.md

@@ -980,6 +980,7 @@ _Avoid_: config file, setting (unqualified), package setting
 
 **Package Inventory**:
 The two directories that hold installed Packages. `packages/` holds the enabled ones, which the build compiles. `.lyracore/packages-disabled/` holds the disabled ones, which it cannot see. A Package's location IS its enabled state; no file records it, so nothing can disagree with the disk about what the next build compiles. `lyracore packages enable` and `lyracore packages disable` move one folder between the two.
+`lyracore packages apply` applies the enabled set to the chosen Shards. See [Applying packages](packages/README.md#applying-packages) for artifact preparation and Module publishing.
 _Avoid_: registry, package list, enabled flag, state file
 
 **Package Teardown**:

README.md

@@ -55,9 +55,11 @@ in TypeScript or Lua, data changes, client addons, Rust code, or any mix of thes
 ```bash
 lyracore packages new my-package    # start your own
 lyracore packages add playerbots    # install an official one
+lyracore packages apply             # build and activate enabled Packages
 ```
 
 The official Packages live in [LyraCoreProject/packages](https://github.com/LyraCoreProject/packages).
+[Applying packages](./packages/README.md#applying-packages) explains what the command changes.
 [`docs/package-api.md`](./docs/package-api.md) lists what a Package's Rust code may call.
 
 ## Architecture

docs/danger-zones.md

@@ -116,7 +116,10 @@ any line in §1 needs a human review before it ships, whoever or whatever wrote
   and [HTTP body](https://github.com/clockworklabs/SpacetimeDB/blob/v2.7.1/crates/cli/src/api.rs#L69-L76).
 - **`game_package_import` is private and has no gateway binding.** Read it with `spacetime sql`
   only, and with an EQUALITY filter on `family` (a range filter on one column can wrongly return 0
-  rows). `lyracore packages replay` is the supported way to change it; never write it by hand.
+  rows). `lyracore packages apply` is the supported way to change it; never write it by hand.
+  `apply` can publish the Module. See [Applying packages](../packages/README.md#applying-packages)
+  for the publish conditions. Its confirmation covers the Realm changes; `--check` prepares locally
+  without Realm writes.
   An empty Package Delta payload is not "unknown" — it means "no Package claims this family" and
   CLEARS the Package spell range.
 - **`auto_inc` sequences sit BEHIND explicitly-numbered imported rows.** A content import writes
@@ -420,6 +423,7 @@ cargo build
 # `--features=debug_reducers` (a bare `spacetime publish` omits it, drops the feature-gated debug
 # tables, and then false-aborts on a bogus "Removed table: game_debug_readout"), passes `--yes`, and
 # REFUSES `-c` and any other flag-shaped argument. Plain publish = safe auto-migrate. NEVER -c.
+# `packages apply` can also publish the Module. See packages/README.md for its publish conditions.
 ./lyracore publish
 # ⚠ With no names, that publishes the FIXTURE topology recorded in this checkout's own
 # `.lyracore/state.json` — normally absent on a production host, which falls back to the default
@@ -475,8 +479,9 @@ sleep 4
 # RUST_LOG=info deliberately, not info,gateway::world=debug: since the raw-bytes relay, every packet
 # logs a line, which floods at scale.
 
-# ⚠ Now call `debug_repair_after_publish` BY HAND, on EVERY shard you just published. Nothing runs
-# it for you. It re-arms the motion, creature-tick, aura, ground-area, weather, gateway-lease and
+# After `lyracore publish`, call `debug_repair_after_publish` on every published Shard.
+# `packages apply` already calls it on each Shard it publishes.
+# It re-arms the motion, creature-tick, aura, ground-area, weather, gateway-lease and
 # instance-reaper schedules and re-seeds every fixture family `init` seeds but an auto-migrating
 # republish does not re-run. Skipping it presents as a mid-session hang, not an error.
 # Folding it into `lyracore publish` is issue 41 in the lyracore-cli repository.

importer/src/package_delta.rs

@@ -198,7 +198,7 @@ fn read_enabled(root: &Path) -> Result<Vec<Artifact>> {
             // One Package ships every artifact kind it has into this one directory, so the glob
             // above finds a Script Artifact next to a Package Delta. Skipping it is not leniency:
             // this stage is the CLAIM half of an apply, and the script family has no base import to
-            // run behind. `lyracore packages replay` applies that family separately. Anything this
+            // run behind. `lyracore packages apply` applies that family separately. Anything this
             // router cannot read at all still goes to the parser, which names what is wrong with it.
             if matches!(
                 artifact_kind(&json),

packages/README.md

@@ -31,11 +31,38 @@ Official Package Source at the compatible tag, but does not replace a scaffold.
 A folder or Git URL passed to `packages add` keeps its own source rules. Review a Package as you
 would a Core patch. Its Rust is trusted Module code.
 
+## Applying packages
+
+After creating, installing or changing a Package, apply the enabled Packages to your Shards:
+
+```bash
+./lyracore packages apply
+```
+
+With no Shard names, the command uses the recorded development topology. Pass Shard names to
+choose other Shards. It builds missing or stale artifacts from enabled sources, then applies
+spell Package Deltas and Script Artifacts. Current Script Artifacts need neither Bun nor client data.
+A Datascript build needs Bun and a Base Snapshot. If the snapshot is missing, `apply` extracts one
+from your own client data. Applying spell Package Deltas also reads client data. Use
+`--client-data PATH` to select the client's Data directory.
+
+If an enabled or disabled Package contains `src/mod.rs`, or a Shard records pending Package
+Teardown, `apply` publishes the Module built from the enabled Packages. Including disabled Rust
+Packages in this decision ensures the publish removes their code. After each publish it calls
+`debug_repair_after_publish` to restore Module schedules and fixtures. Each Shard completes its
+publish, repair and artifact application before the next Shard starts.
+
+The command asks once before changing the Realm. Use `--check` to prepare local artifacts and
+validate the plan without Realm writes. Client content uses `lyracore client sync` separately.
+For flags and retry behavior, see the
+[CLI commands](https://github.com/LyraCoreProject/lyracore-cli/blob/main/docs/commands.md).
+
 ## Building source
 
-`lyracore packages build` runs Package-local `datascripts/*.ts` as well as Core's legacy
-`datascripts/src/<package>/*.ts`. Datascripts use the Authoring Library and a Base Snapshot from
-your own client data. Their Package Deltas and Build Identities stay local under `data/.generated/`.
+Use `lyracore packages build` to build artifacts without applying them. It runs Package-local
+`datascripts/*.ts` as well as Core's legacy `datascripts/src/<package>/*.ts`. Datascripts use the
+Authoring Library and a Base Snapshot from your own client data. Their Package Deltas and Build
+Identities stay local under `data/.generated/`.
 Never commit a Package Delta to the collection.
 
 Runtime Scripts use `scripts/*.ts` or `scripts/*.lua`. The build compiles them into a Script
@@ -50,7 +77,7 @@ Each source starts with an event and a durable Script ID:
 Optional `@priority` defaults to `0`, and `@enabled` defaults to `true`. TypeScript declares
 `function script(): number | void`. A numeric Script Answer is what a Package reads through
 `ask()`. Choose distinct IDs before installing multiple copies of a rung. After scaffolding,
-run `packages build` to produce artifacts for the renamed source.
+run `packages apply` to build and activate the renamed source.
 
 ## Client content
 
@@ -66,7 +93,8 @@ Rust Packages seed Package Config with `ensure_package_config_default` and read
 topology, `lyracore packages config NAME KEY VALUE` changes it without a republish.
 
 `packages disable` runs Package Teardown and moves the folder to `.lyracore/packages-disabled/`.
-`packages enable` moves it back. Folder location is the enabled state.
+`packages enable` moves it back. Folder location is the enabled state. Run `packages apply` after
+either command to apply the enabled set.
 
 See the [CLI commands](https://github.com/LyraCoreProject/lyracore-cli/blob/main/docs/commands.md)
-for build, replay, client installation and Package management.
+for build, apply, client installation and Package management.