diff --git a/.lyracore-cli-rev b/.lyracore-cli-rev index 094bc10d..e3f5f409 100644 --- a/.lyracore-cli-rev +++ b/.lyracore-cli-rev @@ -1 +1 @@ -950a03ff593722109482ab6dd496e94148ecf709 +65158741481236ab435de54693dd530a4075ad90 diff --git a/CONTEXT.md b/CONTEXT.md index a69bad89..98382f94 100644 --- a/CONTEXT.md +++ b/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**: diff --git a/README.md b/README.md index 36501b2b..7789d805 100644 --- a/README.md +++ b/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 diff --git a/docs/danger-zones.md b/docs/danger-zones.md index 59bb4bd9..b2b59410 100644 --- a/docs/danger-zones.md +++ b/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. diff --git a/importer/src/package_delta.rs b/importer/src/package_delta.rs index 25489edc..7db67766 100644 --- a/importer/src/package_delta.rs +++ b/importer/src/package_delta.rs @@ -198,7 +198,7 @@ fn read_enabled(root: &Path) -> Result> { // 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), diff --git a/packages/README.md b/packages/README.md index b164d935..e918e278 100644 --- a/packages/README.md +++ b/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//*.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//*.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.