@relu-interactives/spatial-ecs 0.2.2

package/README.md

@@ -0,0 +1,125 @@
+# @relu-interactives/spatial-ecs
+
+Reusable ECS core engine for Relu Spatial editor and runtime experiences.
+
+## Package
+
+- Name: `@relu-interactives/spatial-ecs`
+- Registry: GitHub Packages (`https://npm.pkg.github.com`)
+- Publish workflow: `.github/workflows/publish-package.yml`
+- Publish trigger: push tags matching `v*` (or manual workflow dispatch)
+- Publish access: public (`npm publish --access public`)
+
+## Prerequisites
+
+1. You have write access to this repository.
+2. GitHub Packages permissions are enabled for the repository.
+3. Your account/token has package read/write permissions.
+4. Node.js 20+ and npm are installed locally.
+
+## Local Development
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+Build package:
+
+```bash
+npm run build
+```
+
+Type check:
+
+```bash
+npm run typecheck
+```
+
+## Creating a Release Version
+
+Use one of the version scripts:
+
+```bash
+npm run release:patch
+# or
+npm run release:minor
+# or
+npm run release:major
+```
+
+This updates `package.json` version and creates a git tag.
+
+## Publishing via GitHub Actions (Recommended)
+
+1. Commit your changes (including the version bump).
+2. Push commit and tag.
+
+```bash
+git add .
+git commit -m "release: bump package version"
+git push && git push --tags
+git push --follow-tags
+```
+
+3. GitHub Action `Publish Spatial ECS Package` runs automatically.
+4. Verify publish in:
+   - Repository `Actions` tab
+   - Repository `Packages` section
+
+## Make Package Public (GitHub UI)
+
+For already-published package versions, you may need a one-time visibility change in GitHub:
+
+1. Open repository `Packages`.
+2. Open package `@relu-interactives/spatial-ecs`.
+3. Go to `Package settings`.
+4. Under `Danger Zone`, change visibility to `Public`.
+
+After this, new releases published by the workflow remain public.
+
+## Manual Publish (Optional)
+
+If needed, publish from your machine.
+
+Create/update your user `.npmrc` with GitHub Packages auth:
+
+```ini
+@relu-interactives:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+always-auth=true
+```
+
+Then run:
+
+```bash
+npm ci
+npm run build
+npm publish
+```
+
+## Consuming This Package
+
+In consumer projects, set scope registry:
+
+```ini
+@relu-interactives:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
+always-auth=true
+```
+
+Install:
+
+```bash
+npm install @relu-interactives/spatial-ecs
+```
+
+## Troubleshooting
+
+- `403 Forbidden` / `401 Unauthorized`:
+  - Check token permissions (`read:packages` for install, `write:packages` for publish).
+- `You cannot publish over the previously published versions`:
+  - Bump version before publishing.
+- Workflow succeeds build but fails publish:
+  - Confirm package name scope matches workflow scope (`@relu-interactives`).