everything-dev 1.35.3 → 1.35.5

package/skills/dev-workflow/SKILL.md

@@ -2,7 +2,7 @@
 name: dev-workflow
 description: Development workflow for everything-dev projects using bos dev, bos start, and the Module Federation runtime. Use when starting dev servers, debugging hot reload, or understanding the service-descriptor architecture.
 metadata:
-  sources: "src/service-descriptor.ts,src/orchestrator.ts,src/dev-logs.ts,src/host.ts"
+  sources: "packages/everything-dev/src/service-descriptor.ts,packages/everything-dev/src/orchestrator.ts,packages/everything-dev/src/dev-logs.ts,packages/everything-dev/src/dev-session.ts"
 ---
 
 # everything-dev Development Workflow
@@ -28,7 +28,7 @@ bos dev                  # Full local (rarely needed)
 | auth | 3002 | http://localhost:3002 |
 | ui | 3003 | http://localhost:3003 |
 | ui-ssr | 3004 | http://localhost:3004 |
-| plugins | 3010+ | http://localhost:3010+ |
+| plugins | 3010+ | http://localhost:3010+ (incremental — one per plugin in config order) |
 
 ## Service-Descriptor Architecture
 
@@ -49,6 +49,8 @@ The orchestrator:
 
 - **UI changes**: Rsbuild HMR — instant at :3003, no rebuild
 - **API changes**: Rspack HMR — instant at :3001, no rebuild
+- **Auth / Plugin changes**: No HMR — require full restart (`bos kill && bos dev`)
+- **SSR (ui-ssr)**: No HMR — restart required after UI changes
 - **Config changes**: Require host restart (`bos kill && bos dev`)
 
 ## Contract Sync & Type Generation
@@ -79,6 +81,8 @@ bos types gen   # Regenerate ui/src/lib/api-types.gen.ts and api/src/lib/plugins
 
 The host reads `BOS_RUNTIME_CONFIG` at startup (resolved from `bos.config.json` by the CLI). `ConfigService` is an immutable Effect Layer — every service is built from that one snapshot.
 
+**Override for testing**: Set `BOS_RUNTIME_CONFIG` env var to a JSON string or file path to bypass config loading from disk. Useful for testing with different configs without modifying `bos.config.json`.
+
 On page refresh:
 1. Browser re-fetches HTML shell from host
 2. Host injects current config into `window.__RUNTIME_CONFIG__`
@@ -99,21 +103,45 @@ Build configs (rsbuild/rspack) read from `.bos/bos.resolved-config.json` first,
 ```bash
 bos ps                    # List running processes + ports
 bos status                # Check remote health
+bos info                  # Show current configuration
 ls .bos/logs/             # Available log files
 cat .bos/logs/api.log     # API process logs
 ```
 
-API not responding:
+### Port Conflicts
+
+If a port is already in use, the local service fails to start. Check what's on the port:
+
+```bash
+lsof -i :3003             # Check what is using port 3003
+```
+
+Kill the conflicting process and retry, or stop the existing `bos dev` session first.
+
+### Stale PID file
+
+If `bos kill` doesn't run cleanly (e.g., terminal was closed), stale PIDs in `.bos/pids.json` can block restart:
+
+```bash
+rm .bos/pids.json         # Clear stale PID tracking
+bos dev                   # Start fresh
+```
+
+### API not responding
+
 1. `bos ps` — is API running?
 2. `.bos/logs/api.log` — startup errors?
 3. `curl http://localhost:3001/remoteEntry.js` — is the entry accessible?
 
-UI not loading:
+### UI not loading
+
 1. Check browser console for Module Federation errors
 2. `bos.config.json` — is `app.ui.development` correct?
-3. Clear browser cache and hard reload
+3. Clear browser cache and hard reload (Cmd+Shift+R)
+4. Verify UI SSR restart if using SSR
+
+### Module Federation errors
 
-Module Federation errors:
 - Verify shared dependency versions match across package.json files
 - Clear browser cache (Cmd+Shift+R)
 - Check `bos.config.json` URLs are accessible

package/skills/extends-config/SKILL.md

@@ -2,7 +2,7 @@
 name: extends-config
 description: How bos.config.json extends chains work, deep merge semantics, resolved config lifecycle, env-specific extends, and canonical field ordering. Use when debugging extends inheritance, configuring per-environment parents, understanding what dev writes vs publish writes, or reasoning about config merging.
 metadata:
-  sources: "src/merge.ts,src/config.ts,src/shared-deps.ts,src/types.ts"
+  sources: "packages/everything-dev/src/merge.ts,packages/everything-dev/src/config.ts,packages/everything-dev/src/shared-deps.ts,packages/everything-dev/src/types.ts"
 ---
 
 # extends & Config Merging
@@ -151,6 +151,16 @@ The `_resolved` metadata is stripped before use.
 
 When host is remote, `syncResolvedSharedDeps()` reads versions from `bos.config.json` and writes them into `package.json` catalog. No resolved config is written — the remote host reads `bos.config.json` directly.
 
+### `_resolved.resolvedAt`
+
+The `resolvedAt` timestamp in `.bos/bos.resolved-config.json` is metadata for debugging only. It is not used for staleness detection — the CLI always re-resolves on `bos dev` / `bos build`.
+
+## Circular Extends Detection
+
+If the extends chain contains a cycle (e.g., A→B→A), the resolver detects it during config loading and throws an error listing the cycle path. This prevents infinite recursion during merge.
+
+Detection occurs in `resolveExtendsRef()` → `mergeBosConfigWithExtends()`. The extends chain is tracked as a set of visited BOS refs; a duplicate visit triggers the error.
+
 ## Canonical Field Ordering
 
 `BOS_CONFIG_ORDER` enforces consistent key order:
@@ -158,24 +168,26 @@ When host is remote, `syncResolvedSharedDeps()` reads versions from `bos.config.
 1. `extends` — always first
 2. `account`
 3. `domain`
-4. `testnet`
-5. `staging`
-6. `repository`
-7. `app`
-8. `plugins`
-9. `shared`
+4. `title`
+5. `description`
+6. `testnet`
+7. `staging`
+8. `repository`
+9. `ci`
+10. `app`
+11. `plugins`
 
 Unknown keys go after known keys. `rebuildOrderedConfig()` is applied before every write.
 
 ## API
 
-From `src/config.ts`:
+From `packages/everything-dev/src/config.ts`:
 - `writeResolvedConfig(configDir, config, env, extendsChain?)` — writes `.bos/bos.resolved-config.json`
 - `loadResolvedConfig(configDir)` — reads resolved config, returns `BosConfig | null`
 - `resolveBosConfigPath(configDir)` — returns resolved config path if exists, else `bos.config.json`
 - `readBosConfigForBuild(configDir)` — reads resolved config stripping `_resolved`, falls back to `bos.config.json`
 
-From `src/merge.ts`:
+From `packages/everything-dev/src/merge.ts`:
 - `mergeBosConfigWithExtends(parent, child)` — deep merge for extends chain
 - `mergeBosConfigWithTemplate(local, template)` — merge for sync (local wins)
 - `resolveExtendsRef(extendsField, env)` — resolve string|object extends for a given env

package/skills/init-upgrade/SKILL.md

@@ -2,7 +2,7 @@
 name: init-upgrade
 description: bos init, bos sync, and bos upgrade workflows — template download, snapshot-based conflict detection, package version bumps, and how init/sync select and own files. Use when scaffolding new projects, syncing upstream changes, or upgrading framework packages.
 metadata:
-  sources: "src/cli/init.ts,src/cli/sync.ts,src/cli/upgrade.ts,src/cli/snapshot.ts"
+  sources: "packages/everything-dev/src/cli/init.ts,packages/everything-dev/src/cli/sync.ts,packages/everything-dev/src/cli/upgrade.ts,packages/everything-dev/src/cli/snapshot.ts,packages/everything-dev/src/merge.ts"
 ---
 
 # bos init, sync, upgrade
@@ -23,8 +23,8 @@ bos init --overrides ui,api,host                          # Include host locally
 3. Build the file list with `buildInitPatterns(overrides, plugins)`
 4. Filter plugins: only included plugins + their routes are copied
 5. `personalizeConfig()` — sets `extends`, `account`, `domain`, removes production URLs
-6. `resolveWorkspaceRefs()` — normalizes package manifests, sets catalog refs
-7. Write initial snapshot (`.bos/sync-snapshot.json`)
+6. `resolveWorkspaceRefs()` — normalizes each workspace `package.json`: rewrites `file:`/`workspace:*` refs to `catalog:`, ensures all workspace packages are listed in root `workspaces.catalog`, pins framework versions (`everything-dev`, `every-plugin`)
+7. Write initial snapshot (`.bos/sync-snapshot.json`) — records file path → content hash for all template-origin files, used later by `bos sync` for conflict detection
 8. `bun install` + `bos types gen`
 
 ## Shared Host + Custom Child App
@@ -188,22 +188,18 @@ Workspace packages use `catalog:` refs so a single version bump in root catalog
 
 ## bos publish
 
+See `everything-dev#publish-sync` for the full publish workflow. A quick reference:
+
 ```bash
 bos publish                  # Publish config to FastKV
 bos publish --deploy         # Build, deploy to CDN, then publish
 ```
 
-On `--deploy`:
-1. Build all workspace targets
-2. Deploy to Zephyr CDN → auto-updates `bos.config.json` with production URLs + integrity
-3. Re-read config to pick up deploy updates
-4. Publish full config to FastKV registry
-
-**This is the only time `bos dev`-style writes touch `bos.config.json`** — it's the snapshot moment.
+`bos publish --deploy` builds, deploys to Zephyr, auto-updates `bos.config.json` with production URLs + integrity hashes, then publishes the config to FastKV.
 
 ## Canonical Ordering
 
 All writes to `bos.config.json` enforce `BOS_CONFIG_ORDER`:
-`extends` → `account` → `domain` → `testnet` → `staging` → `repository` → `app` → `plugins`
+`extends` → `account` → `domain` → `title` → `description` → `testnet` → `staging` → `repository` → `ci` → `app` → `plugins`
 
-Unknown keys go after known keys.
+Unknown keys go after known keys. See `everything-dev#extends-config` for full ordering details.

package/skills/publish-sync/SKILL.md

@@ -2,7 +2,7 @@
 name: publish-sync
 description: Publish bos.config.json to the FastKV registry, sync from upstream, and upgrade workspace packages. Use when deploying, syncing, or managing runtime configuration across projects.
 metadata:
-  sources: "src/plugin.ts,src/cli/sync.ts,src/cli/upgrade.ts,src/fastkv.ts,src/integrity.ts"
+  sources: "packages/everything-dev/src/plugin.ts,packages/everything-dev/src/cli/sync.ts,packages/everything-dev/src/cli/upgrade.ts,packages/everything-dev/src/fastkv.ts,packages/everything-dev/src/integrity.ts,packages/everything-dev/src/config.ts"
 ---
 
 # everything-dev Publish & Sync
@@ -33,6 +33,19 @@ After `bos publish --deploy`:
 2. `bos.config.json` is auto-updated with production URLs + integrity hashes
 3. Config is published to the FastKV registry at `{account}/bos/gateways/{gateway}/bos.config.json`
 
+The `--network` flag controls the NEAR network (mainnet by default). With `--network testnet`, publishes go to the NEAR testnet chain under the testnet account specified in config.
+
+### Rollback
+
+To revert a publish, restore the previous `bos.config.json` from git and re-publish:
+
+```bash
+git checkout HEAD~1 -- bos.config.json
+bos publish
+```
+
+Or cherry-pick a specific version of `bos.config.json` and publish that snapshot.
+
 Lineage model:
 - `extends` is the canonical parent edge between published runtimes
 - `account` is the tenant namespace root for that runtime
@@ -140,13 +153,7 @@ For remix-host browsing with the apps plugin:
 
 ### What bos dev writes vs bos publish writes
 
-| Mode | Writes to | File |
-|------|-----------|------|
-| `bos dev` | `.bos/bos.resolved-config.json` | Full merged config (gitignored) |
-| `bos build` | `.bos/bos.resolved-config.json` | Full merged config |
-| `bos publish --deploy` | `bos.config.json` | Snapshot with pinned production URLs |
-| `bos plugin publish` | `bos.config.json` | Records production URL + integrity |
-| `bos sync` | `bos.config.json` | Merges template updates |
+See `everything-dev#extends-config` for the full table. In short: `bos dev` and `bos build` write to `.bos/bos.resolved-config.json` (gitignored); `bos publish --deploy`, `bos plugin publish`, and `bos sync` write to `bos.config.json`.
 
 ## Troubleshooting
 
@@ -155,7 +162,25 @@ bos info              # Show current configuration
 bos status            # Check remote health
 ```
 
-Process issues:
+### FastKV publish failures
+
+- **NEAR RPC error**: Verify the configured NEAR account has sufficient gas and the FastKV contract is deployed at `{account}/bos/gateways/{gateway}/bos.config.json`
+- **Account mismatch**: The `bos.config.json` `account` field must match the on-chain account that owns the FastKV path
+- **Network mismatch**: Ensure `--network` matches where the account is deployed (mainnet vs testnet)
+- **Dry-run first**: Use `bos publish --dry-run` to preview before sending
+
+### Integrity verification
+
+During `bos publish --deploy`, integrity SRI hashes are auto-generated for each remote entry and stored in `bos.config.json`. At runtime, the host:
+- Verifies integrity on first load using bounded streaming (not full-response buffering)
+- Uses stale-while-revalidate for asset requests to avoid latency spikes
+- Blocks HTML and SSR requests on integrity mismatch
+- Identifies SSR modules by both URL and `ssrIntegrity` hash in the cache
+
+If a remote entry fails integrity check, the host rejects it and falls back to client-rendered output without that remote.
+
+### Process issues
+
 ```bash
 bos kill               # Kill all tracked processes
 bun install            # Reinstall deps

package/skills/super-app/SKILL.md

@@ -98,7 +98,7 @@ ALLOW_UNTRUSTED_SSR=false
 ```
 
 Meaning:
-- `ALLOW_OVERRIDE` controls which tenant config sections can affect request-scoped composition
+- `ALLOW_OVERRIDE` controls which tenant config sections can affect request-scoped composition. Format: comma-separated list (e.g., `ui,plugins.*`) where `plugins.*` is a glob matching all plugin overrides
 - `TENANT_WHITELIST` controls which tenants may use SSR
 - `ALLOW_UNTRUSTED_SSR=true` allows SSR for any valid tenant with SSR config
 
@@ -128,6 +128,28 @@ The tenant config must:
 - Asset requests use stale-while-revalidate verification to avoid latency spikes.
 - HTML and SSR requests use blocking verification.
 - SSR module cache identity includes `ssrIntegrity`, not just the SSR URL.
+- **On integrity failure**: the host rejects the remote entry. HTML and SSR requests block immediately; asset requests fall back. The page renders client-side without the failed remote.
+
+## Tenant Config Caching
+
+The host caches resolved tenant configs in memory. Cache TTL is managed by the tenant runtime service (`host/src/services/tenant-runtime.ts`). After publishing tenant config changes, a host restart is typically required to pick up fresh config unless the cache TTL has expired.
+
+## Debugging Tenant Resolution
+
+If tenant overrides are not applying as expected:
+
+1. **Verify the tenant config exists in FastKV**: The config must be published to `{tenantAccount}/bos/gateways/{gateway}/bos.config.json`
+2. **Check extends chain**: The tenant config must extend the base runtime via its `extends` field
+3. **Check host logs**: Run `cat .bos/logs/host.log` and look for tenant resolution messages — the host logs which runtime config it resolved for each request
+4. **Check env vars**: `ALLOW_OVERRIDE` must include the sections you're overriding (e.g., `ui` or `plugins.*`)
+5. **Verify integrity**: If tenant remote URLs have integrity hashes, the host validates them — mismatches cause rejection
+6. **Missing tenant config**: If the tenant config is not found in FastKV, the host silently serves the base runtime config without tenant overrides — no error is surfaced to the browser
+
+### Diagnostics
+
+- `bos info` shows the active runtime configuration loaded by the CLI
+- The host logs the resolved tenant account per request at startup
+- Compare the tenant's published config against the base runtime using `bos info` in the tenant project directory
 
 ## Recommended Workflow