@jskit-ai/agent-docs 0.1.58 → 0.1.60

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/package.json

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

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

@@ -36,6 +36,7 @@ Local functions
 Exports
 - `safeRequestCookies(request)`
 - `cookieOptions(isProduction, maxAge)`
+- `cookieClearOptions(isProduction)`
 
 ### `src/server/lib/authenticatedProfile.js`
 Exports

package/reference/autogen/packages/kernel.md

@@ -678,7 +678,7 @@ Exports
 Exports
 - `normalizeDescriptorUiRoutes(value)`
 - `normalizeDescriptorClientProviders(value)`
-- `normalizeDescriptorClientOptimizeIncludeSpecifiers(value)`
+- `normalizeDescriptorClientOptimizeSpecifiers(value)`
 - `normalizeClientDescriptorSections(descriptorValue)`
 
 ### `client/index.js`
@@ -782,7 +782,7 @@ Exports
 - `CLIENT_BOOTSTRAP_VIRTUAL_ID`
 - `CLIENT_BOOTSTRAP_RESOLVED_ID`
 - `createVirtualModuleSource(clientModules = [])`
-- `resolveClientOptimizeIncludeSpecifiers(clientModules = [])`
+- `resolveClientOptimizeIncludeSpecifiers(clientModules = [], excludeSpecifiers = [])`
 - `resolveClientOptimizeExcludeSpecifiers(clientModules = [])`
 - `resolveLocalScopeOptimizeExcludeSpecifiers(localScopePackageIds = [])`
 - `resolveInstalledClientPackageIds(options)`
@@ -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

package/reference/autogen/packages/users-core.md

@@ -198,6 +198,26 @@ Local functions
 Exports
 - `resolveActionUser(context, input)`
 
+### `src/server/previewUserProvisioning.js`
+Exports
+- `DEFAULT_AUTH_PROVIDER`
+- `DEFAULT_DISPLAY_NAME`
+- `DEFAULT_EMAIL`
+- `ensurePreviewUser(db, profileInput = {})`
+- `normalizePreviewUserProfile(profile = {})`
+- `profileFromUserRow(user = {}, fallback = {})`
+Local functions
+- `normalizeText(value = "")`
+- `normalizeLowerText(value = "")`
+- `normalizeUsername(value = "")`
+- `usernameBaseFromEmail(email = "")`
+- `buildUsernameCandidate(baseUsername = "", suffix = 0)`
+- `isDuplicateError(error)`
+- `resolveUniqueUsername(db, baseUsername = "", { excludeUserId = "" } = {})`
+- `findPreviewUser(db, profile = {})`
+- `ensurePreviewUserRow(db, profile = {})`
+- `ensureUserSettings(db, user = {})`
+
 ### `src/server/profileSyncLifecycleContributorRegistry.js`
 Exports
 - `PROFILE_SYNC_LIFECYCLE_CONTRIBUTOR_TAG`

package/reference/autogen/packages/workspaces-core.md

@@ -114,6 +114,25 @@ Exports
 - `routeParamsValidator`
 - `workspaceSlugParamsValidator`
 
+### `src/server/previewWorkspaceProvisioning.js`
+Exports
+- `buildWorkspaceBaseSlug(profile = {})`
+- `buildWorkspaceName(profile = {})`
+- `ensurePreviewWorkspace(db, user = {}, profile = {}, { appConfig = {}, tenancyMode = "" } = {})`
+- `normalizeWorkspaceResult(workspace = null)`
+Local functions
+- `normalizeText(value = "")`
+- `normalizeLowerText(value = "")`
+- `workspaceSlugPart(value = "")`
+- `usernameBaseFromEmail(email = "")`
+- `buildWorkspaceSlugCandidate(baseSlug = "", suffix = 0)`
+- `isDuplicateError(error)`
+- `resolveUniqueWorkspaceSlug(db, baseSlug = "", { excludeWorkspaceId = "" } = {})`
+- `hasWorkspaceTables(db)`
+- `findPreviewWorkspace(db, user = {}, { isPersonal = true } = {})`
+- `ensureWorkspaceSettings(db, workspace = {})`
+- `ensureOwnerMembership(db, workspace = {}, user = {})`
+
 ### `src/server/registerWorkspaceBootstrap.js`
 Exports
 - `registerWorkspaceBootstrap(app)`

package/reference/autogen/tooling/jskit-cli.md

@@ -400,6 +400,23 @@ Local functions
 - `replaceWithSymlink(targetPath = "", sourceDir = "", { packageName = "" } = {})`
 - `maybeLinkCompanionPackages({ appRoot = "", repoRoot = "", stdout, createCliError })`
 
+### `src/server/commandHandlers/appCommands/preparePreviewUser.js`
+Exports
+- `runAppPreparePreviewUserCommand(_ctx = {}, { appRoot = "", options = {}, stdout = process.stdout })`
+Local functions
+- `normalizeText(value = "")`
+- `normalizeLowerText(value = "")`
+- `profileFromOptions(options = {})`
+- `fileExists(filePath = "")`
+- `createAppRequire(appRoot = "")`
+- `importFreshModule(filePath = "")`
+- `loadKnexConfig(appRoot = "")`
+- `importAppPackageExport(appRoot = "", specifier = "", { required = true } = {})`
+- `writeProfile(profileFile = "", authProfile = {})`
+- `isTrueOption(value)`
+- `normalizeTenancyMode(value = "")`
+- `hasWorkspaceTables(db)`
+
 ### `src/server/commandHandlers/appCommands/release.js`
 Exports
 - `runAppReleaseCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`