@jskit-ai/agent-docs 0.1.59 → 0.1.61

package/guide/agent/app-extras/realtime.md

@@ -124,6 +124,79 @@ So the mental model is:
 - `realtime` gives the app a live transport
 - your own app code, or later packages, decide which events should travel across it
 
+## Publishing server events
+
+Server code should publish realtime lifecycle events through JSKIT's entity-change helpers instead of hand-rolling `domainEvents.publish()` payloads.
+
+Keep `operation` limited to resource invalidation semantics:
+
+- `created`
+- `updated`
+- `deleted`
+
+Use `action` for the domain lifecycle transition, and `reason` only when you need to explain why that transition happened.
+
+For direct publishers, use `createRealtimeEntityChangePublisher()` from `@jskit-ai/kernel/server/runtime/entityChangeEvents`:
+
+```js
+import { createRealtimeEntityChangePublisher } from "@jskit-ai/kernel/server/runtime/entityChangeEvents";
+
+const publishProjectRuntimeChanged = createRealtimeEntityChangePublisher({
+  domainEvents,
+  source: "vibe64",
+  entity: "project",
+  event: "vibe64.project.changed",
+  serviceToken: "vibe64.terminals.service",
+  methodName: "projectRuntime"
+});
+
+await publishProjectRuntimeChanged("updated", projectSlug, {
+  action: "runtime-closed",
+  payload: {
+    message: "Project is closed.",
+    runtime: {
+      open: false
+    }
+  }
+});
+```
+
+The helper emits a normal `entity.changed` domain event with service metadata and `meta.realtime.event`. The realtime bridge uses that service metadata to find the registered socket dispatcher, then emits the socket event with canonical fields such as `source`, `entity`, `operation`, `entityId`, `scope`, and the lifecycle `action`.
+
+For services registered through `app.service()`, declare the same semantics in service metadata:
+
+```js
+app.service(
+  "vibe64.terminals.service",
+  (scope) => createTerminalsService({
+    repository: scope.make("vibe64.repository.terminals")
+  }),
+  {
+    events: {
+      projectRuntime: [
+        {
+          type: "entity.changed",
+          source: "vibe64",
+          entity: "project",
+          operation: "updated",
+          entityId: ({ args }) => args?.[0]?.projectSlug,
+          action: "runtime-closed",
+          realtime: {
+            event: "vibe64.project.changed",
+            payload: ({ result }) => ({
+              message: result?.message || "",
+              runtime: result?.runtime || null
+            })
+          }
+        }
+      ]
+    }
+  }
+);
+```
+
+`action`, `reason`, and `realtime.payload` may be functions when the value depends on the service result or arguments. Do not encode lifecycle names by widening `operation`; keep `operation` truthful for CRUD/resource contracts and put domain-specific lifecycle meaning in metadata.
+
 ## What `realtime` adds to the app
 
 This chapter is small enough that it is worth looking directly at the app-owned files it changes.

package/guide/agent/app-setup/authentication.md

@@ -184,11 +184,11 @@ The screen is also ready to show OAuth provider buttons, but only if providers a
 For this chapter, `config.server.js` keeps this empty:
 
 ```js
-config.auth = {
-  oauth: {
-    providers: [],
-    defaultProvider: ""
-  }
+config.auth ||= {};
+config.auth.profileMode = "standalone";
+config.auth.oauth = {
+  providers: [],
+  defaultProvider: ""
 };
 ```
 
@@ -208,11 +208,10 @@ First, configure Google and Supabase:
 Then tell JSKIT to expose the provider in the login UI:
 
 ```js
-config.auth = {
-  oauth: {
-    providers: ["google"],
-    defaultProvider: "google"
-  }
+config.auth ||= {};
+config.auth.oauth = {
+  providers: ["google"],
+  defaultProvider: "google"
 };
 ```
 
@@ -575,15 +574,15 @@ That `requiresAuth: false` line is important. The auth surface must stay public,
 `config/server.js` also gets an auth stub:
 
 ```js
-config.auth = {
-  oauth: {
-    providers: [],
-    defaultProvider: ""
-  }
+config.auth ||= {};
+config.auth.profileMode = "standalone";
+config.auth.oauth = {
+  providers: [],
+  defaultProvider: ""
 };
 ```
 
-That small block explains a lot of the default login screen. The stock UI is ready for OAuth providers such as Google, but this chapter keeps the provider list empty, so the page only shows the email/password and one-time-code flows. Later, if you enable a provider in Supabase and list it here, the same login screen can expose that button too.
+That small block explains a lot of the default login screen and auth profile behavior. `profileMode: "standalone"` keeps this auth-only chapter on the temporary app-side profile mirror. The stock UI is ready for OAuth providers such as Google, but this chapter keeps the provider list empty, so the page only shows the email/password and one-time-code flows. Later, if you enable a provider in Supabase and list it here, the same login screen can expose that button too.
 
 The auth routes themselves are app-owned wrappers around the module-supplied default views. `src/pages/auth/login.vue` looks like this:
 

package/guide/agent/app-setup/database-layer.md

@@ -710,16 +710,16 @@ So the app has gained a new capability, but no visible part of the UI depends on
 
 This is the most important code path to read in this chapter.
 
-Inside `AuthSupabaseServiceProvider`, auth still resolves its profile mode from the environment:
+Inside `AuthSupabaseServiceProvider`, auth resolves its profile mode from server app config:
 
 ```js
-const authProfileMode = resolveAuthProfileMode(env);
+const authProfileMode = resolveAuthProfileMode(appConfig);
 let userProfileSyncService = fallbackStandaloneProfileSyncService;
 
-if (authProfileMode === AUTH_PROFILE_MODE_USERS) {
+if (authProfileMode === PROFILE_MODE_USERS) {
   if (!scope.has("users.profile.sync.service")) {
     throw new Error(
-      "AuthSupabaseServiceProvider requires users.profile.sync.service when AUTH_PROFILE_MODE=users."
+      "AuthSupabaseServiceProvider requires users.profile.sync.service when config.auth.profileMode is \"users\"."
     );
   }
   userProfileSyncService = scope.make("users.profile.sync.service");
@@ -728,9 +728,10 @@ if (authProfileMode === AUTH_PROFILE_MODE_USERS) {
 
 That snippet explains the whole consequence of this chapter.
 
-- The default mode is still `standalone`.
+- The auth provider's server config still sets `config.auth.profileMode = "standalone"`.
+- If `profileMode` is missing entirely, the runtime assumes `users`, but it is not missing in the auth-only scaffold.
 - The fallback service is still the in-memory profile sync service from the previous chapter.
-- Nothing in `database-runtime-mysql` changes `AUTH_PROFILE_MODE`.
+- Nothing in `database-runtime-mysql` changes `config.auth.profileMode`.
 - Nothing in `database-runtime-mysql` provides `users.profile.sync.service`.
 
 So the auth layer keeps behaving the same way it did before:

package/guide/agent/app-setup/users.md

@@ -39,7 +39,7 @@ This is the first chapter where the migration step is not just "nice to have."
 
 `users-core` writes:
 
-- `AUTH_PROFILE_MODE=users` into `.env`
+- `config.auth.profileMode = "users"` into `config/server.js`
 - real users/account schema migrations into `migrations/`
 
 That means the app is expected to use the persistent users-backed profile sync service. If you skip `npm run db:migrate`, the code and routes are installed, but the required tables are still missing.
@@ -119,12 +119,13 @@ This is the first chapter where the app starts to feel like it has a real user m
 
 The most interesting files are spread across config, migrations, routing, and the app-owned account UI.
 
-### `.env` flips auth into users mode
+### `config/server.js` flips auth into users mode
 
-The most important new line in `.env` is:
+The most important new server-only config line is:
 
-```dotenv
-AUTH_PROFILE_MODE=users
+```js
+config.auth ||= {};
+config.auth.profileMode = "users";
 ```
 
 That one line explains the deepest change in the chapter.
@@ -252,16 +253,16 @@ That is worth noticing because this is a higher level of scaffolding:
 
 ### Why auth uses the users layer
 
-In the previous chapter, auth still defaulted to the standalone profile sync fallback. The core logic in `AuthSupabaseServiceProvider` looks like this:
+In the previous chapter, auth was explicitly configured for the standalone profile sync fallback. The core logic in `AuthSupabaseServiceProvider` looks like this:
 
 ```js
-const authProfileMode = resolveAuthProfileMode(env);
+const authProfileMode = resolveAuthProfileMode(appConfig);
 let userProfileSyncService = fallbackStandaloneProfileSyncService;
 
-if (authProfileMode === AUTH_PROFILE_MODE_USERS) {
+if (authProfileMode === PROFILE_MODE_USERS) {
   if (!scope.has("users.profile.sync.service")) {
     throw new Error(
-      "AuthSupabaseServiceProvider requires users.profile.sync.service when AUTH_PROFILE_MODE=users."
+      "AuthSupabaseServiceProvider requires users.profile.sync.service when config.auth.profileMode is \"users\"."
     );
   }
   userProfileSyncService = scope.make("users.profile.sync.service");
@@ -272,7 +273,7 @@ The important part is concrete.
 
 After `users-web`:
 
-- `.env` sets `AUTH_PROFILE_MODE=users`
+- `config/server.js` sets `config.auth.profileMode = "users"`
 - `users-core` supplies the users-backed sync service
 - the migrations supply the required tables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/reference/autogen/packages/auth-provider-supabase-core.md

@@ -244,7 +244,7 @@ Local functions
 - `resolveOAuthConfigFromAppConfig(appConfig)`
 - `resolveAllowedReturnToOrigins({ appConfig = {}, appPublicUrl = "" } = {})`
 - `resolveAuthProviderConfig(env, appConfig = {})`
-- `resolveAuthProfileMode(env)`
+- `resolveAuthProfileMode(appConfig = {})`
 - `isDevAuthBypassEnabledForRegistration(env)`
 - `isDevAuthBypassRequested(env)`
 - `createInMemoryUserSettingsRepository()`

package/reference/autogen/packages/kernel.md

@@ -1163,6 +1163,7 @@ Local functions
 - `normalizeServiceEventType(value, { context = "service event" } = {})`
 - `normalizeServiceEventOperation(value, { context = "service event" } = {})`
 - `normalizeServiceEventEntityId(value)`
+- `normalizeServiceEventMetaField(value, { context = "service event meta field" } = {})`
 - `normalizeRealtimeDispatch(value, { context = "service event.realtime" } = {})`
 - `normalizeRealtimeAudience(value, { context = "service event.realtime.audience" } = {})`
 - `normalizeServiceEventSpec(entry, { context = "service event" } = {})`
@@ -1171,6 +1172,7 @@ Local functions
 - `resolveMethodOptions(args = [])`
 - `resolveEventOperation(spec, state)`
 - `resolveEventEntityId(spec, state)`
+- `resolveEventMetaField(value, state)`
 - `resolveEventMeta(spec, state)`
 - `createServiceMethodEventPublisher(scope, serviceToken, methodName, specs = [])`
 
@@ -1217,12 +1219,17 @@ Exports
 Exports
 - `resolveDefaultScope(visibilityContext = {}, runtime = {})`
 - `createEntityChangePublisher({ domainEvents, source, entity, scopeResolver = resolveDefaultScope } = {})`
+- `createRealtimeEntityChangePublisher({ domainEvents, source, entity, event, serviceToken, methodName, scopeResolver = resolveDefaultScope } = {})`
 - `createNoopEntityChangePublisher()`
 Local functions
 - `resolveContextScope(context = {})`
 - `resolveVisibilityScope(visibilityContext = {}, runtimeContext = {})`
 - `resolveCommandId(requestMeta = {})`
 - `resolveSourceClientId(requestMeta = {})`
+- `normalizeMetaTextField(source = {}, fieldName = "", { context = "realtime entity change" } = {})`
+- `normalizeRealtimePayload(value, { context = "realtime entity change.payload" } = {})`
+- `createRealtimeEntityChangeMeta({ serviceToken, methodName, event, change = {} } = {})`
+- `resolveRealtimeEntityChangeOptions(change = {}, options = {})`
 
 ### `server/runtime/errors.js`
 Exports