@bitakit/core 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/AGENTS.md +58 -2
  2. package/README.md +61 -18
  3. package/dist/actions/execution.js +4 -0
  4. package/dist/contributions/action.d.ts +0 -5
  5. package/dist/contributions/action.js +21 -1
  6. package/dist/contributions/host.d.ts +3 -0
  7. package/dist/core.d.ts +4 -0
  8. package/dist/core.js +1 -0
  9. package/dist/definitions.d.ts +10 -0
  10. package/dist/events/service.d.ts +14 -0
  11. package/dist/events/service.js +109 -39
  12. package/dist/events/types.d.ts +5 -1
  13. package/dist/inspection/inventory.d.ts +1 -1
  14. package/dist/operation-error.d.ts +75 -0
  15. package/dist/operation-error.js +123 -0
  16. package/dist/remote.d.ts +60 -0
  17. package/dist/remote.js +156 -0
  18. package/dist/request-context.d.ts +62 -0
  19. package/dist/request-context.js +2 -0
  20. package/dist/runtime-mode.d.ts +35 -0
  21. package/dist/runtime-mode.js +6 -0
  22. package/dist/runtime.d.ts +17 -1
  23. package/dist/runtime.js +118 -50
  24. package/dist/server/access.d.ts +31 -0
  25. package/dist/server/access.js +109 -0
  26. package/dist/server/compile.d.ts +59 -0
  27. package/dist/server/compile.js +211 -0
  28. package/dist/server/contributions.d.ts +13 -0
  29. package/dist/server/contributions.js +17 -0
  30. package/dist/server/create-server.d.ts +15 -0
  31. package/dist/server/create-server.js +132 -0
  32. package/dist/server/define.d.ts +40 -0
  33. package/dist/server/define.js +15 -0
  34. package/dist/server/fetch-handler.d.ts +17 -0
  35. package/dist/server/fetch-handler.js +139 -0
  36. package/dist/server/index.d.ts +22 -0
  37. package/dist/server/index.js +21 -0
  38. package/dist/server/kernel.d.ts +44 -0
  39. package/dist/server/kernel.js +278 -0
  40. package/dist/server/types.d.ts +208 -0
  41. package/dist/server/types.js +1 -0
  42. package/dist/server/validate.d.ts +31 -0
  43. package/dist/server/validate.js +60 -0
  44. package/dist/services.d.ts +5 -1
  45. package/dist/services.js +5 -1
  46. package/dist/settings/access.d.ts +5 -2
  47. package/dist/settings/access.js +7 -4
  48. package/dist/settings/server.d.ts +28 -0
  49. package/dist/settings/server.js +94 -0
  50. package/package.json +7 -3
  51. package/testing/index.d.ts +104 -0
  52. package/testing/index.mjs +349 -14
package/AGENTS.md CHANGED
@@ -10,6 +10,8 @@ rarely call the runtime directly: files in `src/plugins/<id>/` are discovered, a
10
10
 
11
11
  ## The define helpers (import from `@bitakit/core`)
12
12
 
13
+ Files under `server/` import the same helpers from `@bitakit/core/server` (see below).
14
+
13
15
  | File (in a plugin) | Helper | ID |
14
16
  | ------------------------ | -------------------------------------------------------------- | ------------------ |
15
17
  | `services/<name>.ts` | `defineService(({ store, events, settings, onStart }) => ...)` | `<plugin>.<name>` |
@@ -24,6 +26,47 @@ rarely call the runtime directly: files in `src/plugins/<id>/` are discovered, a
24
26
 
25
27
  The app declares its base roles once in `src/roles.ts` with `defineRoles({ ... }, { customRoles })`.
26
28
 
29
+ ## The server half (`@bitakit/core/server`)
30
+
31
+ A plugin's `server/` folder runs only on the server and is never bundled for the browser.
32
+
33
+ | File (in a plugin) | Helper (from `@bitakit/core/server`) | ID |
34
+ | ------------------------------- | -------------------------------------------------------------- | ------------------------------------- |
35
+ | `server/actions/<name>.ts` | `defineAction({ access, expose?, input?, output?, execute })` | `<plugin>.<name>`, `server:` in tools |
36
+ | `server/services/<name>.ts` | `defineService(() => ...)`: one instance for the whole process | `<plugin>.<name>` (server services) |
37
+ | `server/interceptors/<name>.ts` | `defineInterceptor({ action: '<plugin>.*', before, after })` | — |
38
+ | `server/contributions/<dir>/…` | Files of a contribution kind declared with `runtime: 'server'` | — |
39
+
40
+ - `access` is required: `'public'`, `'user'`, `'organization'` or
41
+ `{ permission: { resource: ['operation'] } }`. `expose: true` publishes the operation over
42
+ HTTP and in the client's typed `remote` (`remote.<plugin>.<name>(input)` in client Actions
43
+ and services); without it the operation is callable only in-process (`server.as(request)`).
44
+ - `execute({ id, input, ctx, services, config, events, settings, signal })`: `ctx` is the frozen,
45
+ verified identity (`requestId`, `signal`, plus `user`, `organization`, `member`, `can()` by
46
+ access). Filter every query by `ctx.user.id` or `ctx.organization.id`; server services take
47
+ `ctx` or the owner ID as a method argument and never hold per-user state.
48
+ - Identity comes from one app service with `provides: requestContext` (`resolve(request)` →
49
+ `{ user, organization?, member?, reason?, can? }`). It returns an organization only for a
50
+ verified, active membership; `can` grants only by answering exactly `true`. Without a provider
51
+ the server refuses to start while a non-public operation exists.
52
+ - Throw `OperationError(code, safeMessage, { issues?, reason? })` for expected failures (codes
53
+ `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `TOO_MANY_REQUESTS`, ...);
54
+ anything else answers 500 with a `requestId` and is logged. `remote` rejects with the same
55
+ `OperationError` (also exported from `@bitakit/core`, with `isOperationError`), and an Action's
56
+ default failure message shows its `safeMessage`.
57
+ - On the server, settings load per request: `await settings.<plugin>.<name>.load()` (in an
58
+ operation; `load(ctx)` elsewhere) through a `settings.storage` provider; `get()` throws.
59
+ `store()` is process-wide. Events reach in-process listeners with `{ signal, ctx }` and never
60
+ the browser. Interceptor `before` sees validated input; returning `false` rejects the call
61
+ (`FORBIDDEN`, reason `INTERCEPTED`). Client interceptors never match server Actions.
62
+ - The route: `export const POST = fetchHandler(server)` with `server` from the generated
63
+ `src/bitakit.gen.server.ts` (Next.js: `src/app/api/rpc/[...path]/route.ts`). It accepts only
64
+ `POST <endpoint>/<operation id>` with JSON from the app's origin (`trustedOrigins` for exact
65
+ others), up to 1 MiB; `server.endpoint` (default `/api/rpc`) comes from `bitakit.config.ts`
66
+ `server.endpoint`.
67
+ - Reserved name segments (`then`, `catch`, `finally`, `subscribe`, `toJSON`, `valueOf`,
68
+ `toString`, `constructor`, `prototype`) cannot name a server Action.
69
+
27
70
  ## Roles and permissions
28
71
 
29
72
  - Core holds only the vocabulary: `definePermissions`, `defineRoles`, the composed catalog and
@@ -57,13 +100,25 @@ The app declares its base roles once in `src/roles.ts` with `defineRoles({ ... }
57
100
  one plugin under Node (no browser); `plugin.execute(id, input)` resolves to the outcome
58
101
  (`completed` or `skipped`) and rejects on failure; `plugin.events.recorded` lists emitted events.
59
102
 
103
+ `mountServer(folder, { plugins?, services?, configOverrides?, kinds?, app? })` boots a folder's
104
+ server half (shared files plus `server/`, loaded with the app's tsconfig `paths`);
105
+ `mounted.as(identity({ user, organization, member, permissions, reason }))` calls every
106
+ operation, also private ones, with the same checks as over HTTP. A test `requestContext`
107
+ provider answers it and replaces the folder's own. Test each exposed operation as a member, a
108
+ member of another organization and signed out (`user: null`). `mountPlugin(folder, { remote })`
109
+ connects a client half to `mounted.as(...)` or a stub. `mountServer` needs
110
+ `@bitakit/discovery` 0.3.1 or later.
111
+
60
112
  ## Rules
61
113
 
62
114
  - One `defineAction` shape; state belongs in a service `store()`, replaced with `state.set`.
63
115
  - Reading a missing service throws; list other plugins' services in `requires`, or check
64
116
  `app.has(name)` for optional ones.
65
117
  - Only the declaring plugin emits its events; others listen.
66
- - `enabled`, `visible` and interceptors are client rules; authorize on the server.
118
+ - `enabled`, `visible` and interceptors are client rules; authorize in the server operation's
119
+ `access` and filter its data by `ctx`.
120
+ - Browser code never imports `server/` files, `@bitakit/core/server` or
121
+ `src/bitakit.gen.server.ts`; server code never imports React or `ui/` (`bitakit doctor` checks).
67
122
 
68
123
  ## Identifier compatibility and integration contexts
69
124
 
@@ -106,7 +161,8 @@ Origin records may carry `metadataLocation` for diagnostics. Rebinding a definit
106
161
  existing `metadataWarnings`. The runtime's application module has local origin; unknown
107
162
  replacement plugins remain unknown. Static inventory may include `selected` and
108
163
  `diagnostics.identityConflicts`; physical record keys are not portable package identities.
109
- The optional `@bitakit/core/testing` entry requires Discovery 0.2.5 or later.
164
+ The optional `@bitakit/core/testing` entry requires Discovery 0.2.5 or later; `mountServer`
165
+ needs 0.3.1 or later.
110
166
 
111
167
  ### Complete cohort replacement
112
168
 
package/README.md CHANGED
@@ -5,8 +5,9 @@
5
5
  # BitaKit Core
6
6
 
7
7
  Framework-independent plugins, services, Actions, events, settings and lifecycle management.
8
- Core works in Node.js and the browser without React or a router. React bindings, discovery,
9
- visual plugins and provider integrations are separate packages.
8
+ Core works in Node.js and the browser without React or a router. Its `@bitakit/core/server`
9
+ entry runs plugins' server halves. React bindings, discovery, visual plugins and provider
10
+ integrations are separate packages.
10
11
 
11
12
  ## Install
12
13
 
@@ -15,7 +16,7 @@ npm install @bitakit/core
15
16
  ```
16
17
 
17
18
  For a new application, `npx @bitakit/create-app my-app` connects the packages for you
18
- (Node.js 24 or newer). The handbook describes the 0.2 API in this checkout; use matching
19
+ (Node.js 24 or newer). The handbook describes the 0.3 API in this checkout; use matching
19
20
  package versions or the [local package workflow](../../apps/docs/content/docs/local-development.mdx)
20
21
  when trying unpublished changes.
21
22
 
@@ -37,6 +38,31 @@ Discovery names it `counter.value`. Continue with the
37
38
  to add an Action and a page. Installing Core alone does not scan folders or render UI.
38
39
  For a headless program, follow [manual composition](../../apps/docs/content/docs/concepts/manual-composition.mdx).
39
40
 
41
+ ## The server half
42
+
43
+ A plugin's `server/` folder holds code that runs only on the server. An operation is a server
44
+ Action, written with the same `defineAction` imported from `@bitakit/core/server`:
45
+
46
+ ```ts
47
+ // src/plugins/counter/server/actions/save.ts
48
+ import { defineAction } from '@bitakit/core/server';
49
+ import { z } from 'zod';
50
+
51
+ export default defineAction({
52
+ access: 'user', // required: 'public', 'user', 'organization' or { permission }
53
+ expose: true, // callable from the browser as remote.counter.save(input)
54
+ input: z.object({ count: z.number().int() }),
55
+ execute: ({ input, ctx }) => ({ userId: ctx.user.id, count: input.count }),
56
+ });
57
+ ```
58
+
59
+ Discovery writes `src/bitakit.gen.server.ts`; one route serves every exposed operation
60
+ (`export const POST = fetchHandler(server)`), and client Actions and services call them through
61
+ the typed `remote`. Identity comes from one app service with `provides: requestContext`.
62
+ `@bitakit/core/testing` boots a server half with `mountServer` and calls it as different people
63
+ with `identity(...)`. See [The server half](../../apps/docs/content/docs/concepts/server.mdx)
64
+ and the [Server reference](../../apps/docs/content/docs/reference/server.mdx).
65
+
40
66
  ## Developer handbook
41
67
 
42
68
  The handbook is maintained once in the documentation website's source. The links below
@@ -44,23 +70,40 @@ resolve within a repository checkout and follow the branch viewed on GitHub. Run
44
70
  `npm run dev:docs` from the repository root to read the rendered handbook at
45
71
  `http://localhost:3002/docs`. A public documentation address is not configured yet.
46
72
 
47
- | Topic | Guide |
48
- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
49
- | Services and cleanup | [Service reference](../../apps/docs/content/docs/reference/services.mdx) |
50
- | Actions and React bindings | [Action reference](../../apps/docs/content/docs/reference/actions.mdx) |
51
- | Events and interception | [Events](../../apps/docs/content/docs/concepts/events.mdx), [Interceptors](../../apps/docs/content/docs/concepts/interceptors.mdx) |
52
- | Files and developer configuration | [Discovery](../../apps/docs/content/docs/concepts/discovery.mdx), [Configuration](../../apps/docs/content/docs/concepts/configuration.mdx) |
53
- | Extension points and preferences | [Slots](../../apps/docs/content/docs/reference/slots.mdx), [Settings](../../apps/docs/content/docs/reference/settings.mdx) |
54
- | Runtime updates and diagnostics | [Runtime management](../../apps/docs/content/docs/concepts/runtime-management.mdx) |
55
- | Enable, disable, add and remove plugins | [Plugin manager](../../apps/docs/content/docs/plugin-management.mdx) |
56
- | Activate a trusted package catalog | [Package manager](../../apps/docs/content/docs/package-management.mdx) |
57
- | Authentication contract | [Client authentication](../../apps/docs/content/docs/reference/authentication.mdx) |
58
- | Test a plugin folder | [Testing](../../apps/docs/content/docs/reference/testing.mdx) |
59
- | Standalone example | [To-do walkthrough](../../apps/docs/content/docs/concepts/tutorial.mdx); runnable JavaScript files in `examples/` |
73
+ | Topic | Guide |
74
+ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
75
+ | Services and cleanup | [Service reference](../../apps/docs/content/docs/reference/services.mdx) |
76
+ | Actions and React bindings | [Action reference](../../apps/docs/content/docs/reference/actions.mdx) |
77
+ | Events and interception | [Events](../../apps/docs/content/docs/concepts/events.mdx), [Interceptors](../../apps/docs/content/docs/concepts/interceptors.mdx) |
78
+ | Files and developer configuration | [Discovery](../../apps/docs/content/docs/concepts/discovery.mdx), [Configuration](../../apps/docs/content/docs/concepts/configuration.mdx) |
79
+ | Extension points and preferences | [Slots](../../apps/docs/content/docs/reference/slots.mdx), [Settings](../../apps/docs/content/docs/reference/settings.mdx) |
80
+ | Runtime updates and diagnostics | [Runtime management](../../apps/docs/content/docs/concepts/runtime-management.mdx) |
81
+ | Enable, disable, add and remove plugins | [Plugin manager](../../apps/docs/content/docs/plugin-management.mdx) |
82
+ | Activate a trusted package catalog | [Package manager](../../apps/docs/content/docs/package-management.mdx) |
83
+ | Authentication contract | [Client authentication](../../apps/docs/content/docs/reference/authentication.mdx) |
84
+ | Server operations and the request context | [The server half](../../apps/docs/content/docs/concepts/server.mdx), [Server reference](../../apps/docs/content/docs/reference/server.mdx) |
85
+ | Test a plugin folder or its server half | [Testing](../../apps/docs/content/docs/reference/testing.mdx) |
86
+ | Standalone example | [To-do walkthrough](../../apps/docs/content/docs/concepts/tutorial.mdx); runnable JavaScript files in `examples/` |
60
87
 
61
88
  Plugins are trusted application code. Core is not a sandbox, package installer or remote
62
- marketplace. Services own state and resources; the host owns routing, persistence providers
63
- and server authorization.
89
+ marketplace. Services own state and resources; the host owns routing, persistence providers and
90
+ its authentication. Server operations declare who may call them (`access`); the app's
91
+ `requestContext` provider verifies the caller, and Core never decides roles itself.
92
+
93
+ ## Source responsibilities: the server half
94
+
95
+ - `src/server/index.ts`: the `@bitakit/core/server` entry; `define.ts` gives the root helpers
96
+ their server types.
97
+ - `src/server/create-server.ts`: the lazy `Server` handle and the process-wide live-kernel
98
+ registry (`instance`, `stamp`); `kernel.ts`: one call (lookup, access, validation,
99
+ interceptors, execute, output, errors); `compile.ts`: the frozen operation table built at boot;
100
+ `access.ts`: identity normalization and access rules; `validate.ts`: schema checks.
101
+ - `src/server/fetch-handler.ts`: the built-in JSON transport; `contributions.ts`: `contributionsOf`.
102
+ - `src/remote.ts`: the client's `remote`, `ServerActionMap`/`ServerServiceMap` and the reserved
103
+ name segments; `src/operation-error.ts`: the request-error model; `src/request-context.ts`: the
104
+ `requestContext` contract and `ctx` types; `src/runtime-mode.ts` and `src/settings/server.ts`:
105
+ the runtime's server mode and per-request settings.
106
+ - `testing/index.mjs`: `mountPlugin`, `mountServer`, `identity`, `assertAuthContract`.
64
107
 
65
108
  ## Metadata and provenance
66
109
 
@@ -93,6 +93,10 @@ export function createExecutor(setPending, owners, environment, get, resolve, up
93
93
  return result;
94
94
  }
95
95
  catch (error) {
96
+ // A run whose signal was aborted (a newer `latest` run took over, or its registration went
97
+ // away) usually rejects with that abort. It was stopped on purpose: not a failure to report.
98
+ if (controller.signal.aborted)
99
+ return skip('cancelled');
96
100
  status = ActionStatus.Failed;
97
101
  failure = error;
98
102
  lifecycle.emit({ id, context, phase: 'failed', error });
@@ -18,9 +18,4 @@ export type Adapted = {
18
18
  };
19
19
  /** Configuration caps: false wins over any reactive result; true never bypasses guards. */
20
20
  export declare function cap(presentation: ActionPresentation, override: Override): ActionPresentation;
21
- /**
22
- * The one adapter: static fields register as-is, function-valued fields are evaluated per
23
- * input in `resolve`, `href` executes as navigation, `dialog` opens the host dialog and
24
- * `execute` runs with validation, feedback and the shared execution guards.
25
- */
26
21
  export declare function adaptAction(resolved: ResolvedContribution, host: ContributionHost, config: ConfigContext, events: Events, available?: () => boolean): Adapted;
@@ -1,6 +1,7 @@
1
1
  import { CANCEL, navigate } from '@bitakit/core/actions';
2
2
  import { ActionFailure } from '../actions/feedback.js';
3
3
  import { isThenable, validate, validateSync } from '../schema.js';
4
+ import { contributionPath } from '../contribution-origin.js';
4
5
  const dynamicKeys = [
5
6
  'title',
6
7
  'description',
@@ -28,7 +29,17 @@ export function cap(presentation, override) {
28
29
  * input in `resolve`, `href` executes as navigation, `dialog` opens the host dialog and
29
30
  * `execute` runs with validation, feedback and the shared execution guards.
30
31
  */
32
+ /** Fields only a server Action has; in a client Action they would silently not apply. */
33
+ const serverFields = ['access', 'expose', 'output'];
34
+ function rejectServerFields(resolved) {
35
+ const field = serverFields.find((name) => resolved[name] !== undefined);
36
+ if (!field)
37
+ return;
38
+ const path = (contributionPath(resolved) ?? resolved.id.split('.')).join('/');
39
+ throw new Error(`\`${field}\` is a server field. This file is the button; put the operation, with \`expose: true\`, in server/actions/${path}.ts and call it with remote.${resolved.id}().`);
40
+ }
31
41
  export function adaptAction(resolved, host, config, events, available = () => true) {
42
+ rejectServerFields(resolved);
32
43
  const override = host.override(resolved.id);
33
44
  // Only `false` caps apply to the definition; `true` never bypasses the action's own guards.
34
45
  const definition = override
@@ -101,6 +112,7 @@ export function adaptAction(resolved, host, config, events, available = () => tr
101
112
  settings: host.app.settings,
102
113
  app: host.app,
103
114
  events,
115
+ remote: host.remote,
104
116
  };
105
117
  let result;
106
118
  try {
@@ -158,7 +170,15 @@ export function adaptAction(resolved, host, config, events, available = () => tr
158
170
  const request = evaluate(definition.confirm, context.input);
159
171
  if (!request)
160
172
  return undefined;
161
- const accepted = await host.confirm(typeof request === 'string' ? { title: request, description: '' } : request);
173
+ const { title, description, ...rest } = typeof request === 'string' ? { title: request, description: '' } : request;
174
+ // Like an Action's title: the text itself as a catalog key, then `<id>.confirm.title`
175
+ // and `.description`, then the literal.
176
+ const text = (value, part) => host.text(value, host.text(`${definition.id}.confirm.${part}`, value));
177
+ const accepted = await host.confirm({
178
+ ...rest,
179
+ title: text(title, 'title'),
180
+ description: description ? text(description, 'description') : description,
181
+ });
162
182
  return accepted ? undefined : CANCEL;
163
183
  }
164
184
  : undefined;
@@ -3,6 +3,7 @@ import type { Feedback, MessageValues } from '../actions/feedback.js';
3
3
  import type { ResolvedContribution, Services, Translator } from '../definitions.js';
4
4
  import type { BitaKitApp } from '../app/types.js';
5
5
  import type { Confirmation } from '../confirmation.js';
6
+ import type { Remote } from '../remote.js';
6
7
  export type FeedbackOutcome = {
7
8
  message: string | false;
8
9
  closeDialog: boolean;
@@ -25,6 +26,8 @@ export interface ContributionHost {
25
26
  readonly app: BitaKitApp;
26
27
  readonly actions: ActionList;
27
28
  readonly services: Services;
29
+ /** The exposed server operations, passed to `execute` as `remote`. */
30
+ readonly remote: Remote;
28
31
  translator(): Translator;
29
32
  title(definition: ResolvedContribution): string;
30
33
  description(definition: ResolvedContribution): string | undefined;
package/dist/core.d.ts CHANGED
@@ -23,6 +23,10 @@ export { BitaKitServiceError } from './app/service-error.js';
23
23
  export { resolveBitaKitConfig, type BitaKitOverrides } from './configuration.js';
24
24
  export { BitaKitRuntime, createRuntime, type DialogState, type NormalizedPlugin, } from './runtime.js';
25
25
  export { BitaKitStartupError, isBitaKitStartupError } from './startup-error.js';
26
+ export { OperationError, isOperationError, type OperationErrorCode, type OperationErrorReason, type OperationErrorJSON, type OperationIssue, } from './operation-error.js';
27
+ export type { ServerActionMap, ServerServiceMap, Remote, RemoteConfig, RemoteCallOptions, OperationFunction, } from './remote.js';
28
+ export type { RuntimeMode, RuntimeOptions } from './runtime-mode.js';
29
+ export type { Access, PermissionRequest, RequestContext, PublicContext, UserContext, OrganizationContext, } from './request-context.js';
26
30
  export type { Cleanup } from './lifecycle/cleanup.js';
27
31
  export type { LifecyclePhase, LifecycleFailure, LifecycleEntry, LifecycleSnapshot, LifecycleState, } from './lifecycle/state.js';
28
32
  export { RuntimeController, createRuntimeController, describeStartupFailure, failedPluginClosure, pluginExposesService, } from './lifecycle/controller.js';
package/dist/core.js CHANGED
@@ -15,6 +15,7 @@ export { BitaKitServiceError } from './app/service-error.js';
15
15
  export { resolveBitaKitConfig } from './configuration.js';
16
16
  export { BitaKitRuntime, createRuntime, } from './runtime.js';
17
17
  export { BitaKitStartupError, isBitaKitStartupError } from './startup-error.js';
18
+ export { OperationError, isOperationError, } from './operation-error.js';
18
19
  export { RuntimeController, createRuntimeController, describeStartupFailure, failedPluginClosure, pluginExposesService, } from './lifecycle/controller.js';
19
20
  export { PluginScope, scopeModule, scopePlugins, scopeModules, scopeTranslation, scopeLifecycle, } from './scope.js';
20
21
  export { mergePluginMessages } from './messages.js';
@@ -14,6 +14,7 @@ import type { InterceptorSpec } from './interceptors/define.js';
14
14
  import type { Confirmation } from './confirmation.js';
15
15
  import type { Cleanup } from './lifecycle/cleanup.js';
16
16
  import type { SlotDefinition, SlotDefinitions } from './slots/define.js';
17
+ import type { Remote, RemoteConfig } from './remote.js';
17
18
  /** Service IDs and aliases with their instance types. Generated from discovery; augmentable by hand. */
18
19
  export interface ServiceMap {
19
20
  }
@@ -26,6 +27,8 @@ export type ServiceContext = {
26
27
  services: Services;
27
28
  config: ConfigContext;
28
29
  events: Events;
30
+ /** The exposed server operations: `await remote.todos.add(input)` (see `Remote`). */
31
+ remote: Remote;
29
32
  /** Typed setting handles: `settings.todos.pageSize.get()`. */
30
33
  settings: SettingsAccess;
31
34
  /** Observable state; actions and `useServiceState` follow it automatically. */
@@ -84,6 +87,8 @@ export type ExecuteContext<Input = unknown> = ActionContext<Input> & {
84
87
  settings: SettingsAccess;
85
88
  app: BitaKitApp;
86
89
  events: Events;
90
+ /** The exposed server operations: `await remote.todos.add(input)` (see `Remote`). */
91
+ remote: Remote;
87
92
  /** Aborts when the registration is disposed, or when a newer `latest` run supersedes this one. */
88
93
  signal: AbortSignal;
89
94
  };
@@ -354,6 +359,11 @@ export type BitaKitRuntimeConfig = Omit<Plugin, 'id' | 'dependencies' | 'parent'
354
359
  bundle?: string;
355
360
  /** Host-known bundle labels. A plugin's membership claim does not add entries here. */
356
361
  knownBundles?: readonly import('./inspection/plugin-origin.js').PluginBundle[];
362
+ /**
363
+ * The exposed server operations and their endpoint, generated into the client config. Without
364
+ * it every `remote` call rejects with SERVICE_UNAVAILABLE.
365
+ */
366
+ remote?: RemoteConfig;
357
367
  };
358
368
  /** A literal string wins; a widened `string` or a missing value falls back. */
359
369
  type LiteralOr<Value, Fallback> = [NonNullable<Value>] extends [string] ? string extends NonNullable<Value> ? Fallback : NonNullable<Value> : Fallback;
@@ -1,5 +1,6 @@
1
1
  import type { Events, EventErrorHandler, BitaKitEvent } from './types.js';
2
2
  import type { EventsDefinition } from './define.js';
3
+ import type { RequestContext } from '../request-context.js';
3
4
  /**
4
5
  * One bus per runtime. Delivery is synchronous and ordered; async handlers are awaited only
5
6
  * for error reporting, or fully for cancelable events. Declared namespaces belong to the
@@ -14,11 +15,15 @@ export declare class EventService implements Events {
14
15
  private declared;
15
16
  private reserved;
16
17
  private reservedEvents;
18
+ private lookupCache?;
17
19
  constructor(onError?: EventErrorHandler);
18
20
  /** Registers a plugin's `events.ts`; its names live under `<plugin>.`. */
19
21
  declare(plugin: string, definition: EventsDefinition): void;
20
22
  /** Release a stopped owner’s declaration without removing other owners’ listeners. */
21
23
  undeclare(plugin: string): void;
24
+ private get lookup();
25
+ /** The declared or reserved namespace a (case-folded) namespace reference names. */
26
+ private namespace;
22
27
  /** The plugin that declared the namespace of an event name, if any. */
23
28
  ownerOf(name: string): string | undefined;
24
29
  resolve(name: string): string;
@@ -26,9 +31,16 @@ export declare class EventService implements Events {
26
31
  /** Reserves a runtime-owned namespace and returns its private publishing capability. */
27
32
  reserve(namespace: string): (name: string, data: unknown) => void;
28
33
  emit: Events["emit"];
34
+ /**
35
+ * Emits on behalf of a server call: listeners receive `ctx` as `{ signal, ctx }`. It is never
36
+ * part of the event object. `undefined` behaves exactly like `emit`.
37
+ */
38
+ emitWithContext(ctx: RequestContext | undefined, name: string, data?: unknown): void | Promise<boolean>;
29
39
  private dispatch;
30
40
  private emitCancelable;
41
+ /** Exact listeners (in subscription order), then prefix listeners; each listener once. */
31
42
  private listenersFor;
43
+ private indexExact;
32
44
  private report;
33
45
  on: Events["on"];
34
46
  /** Diagnostics only: receives every event after delivery. It cannot change or stop delivery. */
@@ -43,5 +55,7 @@ export declare class EventService implements Events {
43
55
  */
44
56
  export declare function createEventScope(events: EventService, owner?: string): {
45
57
  events: Events;
58
+ /** The same view whose `emit` hands a server call's `ctx` to listeners. */
59
+ withContext: (ctx: RequestContext) => Events;
46
60
  dispose(): void;
47
61
  };