@bitakit/core 0.2.6 → 0.2.8

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.
package/AGENTS.md CHANGED
@@ -17,7 +17,7 @@ rarely call the runtime directly: files in `src/plugins/<id>/` are discovered, a
17
17
  | `events.ts` | `defineEvents({ changed: event<T>() })` | `<plugin>.changed` |
18
18
  | `settings.ts` | `defineSettings({ name: setting({ default }) }, page)` | `<plugin>.<name>` |
19
19
  | `slots/<name>.ts` | `defineSlot({ accepts, policy?, payload? })` | `<plugin>.<name>` |
20
- | `interceptors/<name>.ts` | `defineInterceptor({ action, before, after })` | — |
20
+ | `interceptors/<name>.ts` | `defineInterceptor({ action or service, before, after })` | — |
21
21
  | `configs/<name>.ts` | `defineConfig({ defaults, schema? })` | `<plugin>.<name>` |
22
22
  | `setup.ts` | `Setup` function (`scope.slots.attach`, cleanup) | — |
23
23
 
@@ -44,3 +44,36 @@ one plugin under Node (no browser); `plugin.execute(id, input)` resolves to the
44
44
  `app.has(name)` for optional ones.
45
45
  - Only the declaring plugin emits its events; others listen.
46
46
  - `enabled`, `visible` and interceptors are client rules; authorize on the server.
47
+
48
+ ## Plugin identity and inspection
49
+
50
+ Discovery records provenance on definitions. `withPluginOrigin(plugin, record)` is the trusted
51
+ host API; `getPluginOrigin` reads it. Replacing a definition without a record leaves it unknown.
52
+ `pluginMembership` and `groupPlugins` are pure grouping projections; membership never changes
53
+ execution or access. `inspectRuntime` adds origin, package, parent and membership to its existing
54
+ version-1 inventory. Package/bundle names compare lowercase with scopes preserved; runtime IDs
55
+ stay unchanged. `projectPluginMetadata` shares canonical-first package metadata and legacy
56
+ fallback; `projectPluginMetadataSources([{ value, location }, ...])` uses the same projection
57
+ with ordered sources and diagnostic labels. `packageMetadataSources` extracts public package
58
+ fields without I/O. Included folder bindings preserve existing plugin metadata before package
59
+ fallbacks. `metadata.name` remains supported; package identity is recorded independently.
60
+ `pluginDisplayTitle(metadata, fallback?)` shares title-before-name selection; consumers apply
61
+ translations and explicit settings section labels first. `projectPluginMetadataSources` accepts
62
+ `{ packageName }` to distinguish the generated identity fallback from an authored display name.
63
+ Origin records may carry `metadataLocation` for diagnostics. Rebinding a definition retains
64
+ existing `metadataWarnings`. The runtime's application module has local origin; unknown
65
+ replacement plugins remain unknown. Static inventory may include `selected` and
66
+ `diagnostics.identityConflicts`; physical record keys are not portable package identities.
67
+ The optional `@bitakit/core/testing` entry requires Discovery 0.2.5 or later.
68
+
69
+ ### Complete cohort replacement
70
+
71
+ Host-only `runtime.plugins.replace(ids, nextPlugins, { expectedRevision?, preserve? })` validates
72
+ an entire proposed composition before stopping any old owner. `plugins.preview({ operation:
73
+ 'replace', ids, plugins, ...options })` uses the same planner. Supply every owned descendant;
74
+ external dependents and outside ID collisions are refused. Empty old/new sets support addition
75
+ or removal. Providers, foundational services and other composition restrictions still return
76
+ `restart-required`. Cleanup is awaited; failed cleanup blocks reuse. A startup failure can leave
77
+ candidate definitions installed with failed lifecycle state; this API does not silently roll
78
+ back. Optional `@bitakit/packages` coordinates artifact recovery. Core never downloads or
79
+ persists code, and `reconcilePlugins` retains its existing narrower compatibility contract.
package/README.md CHANGED
@@ -62,7 +62,29 @@ Plugins are trusted application code. Core is not a sandbox, package installer o
62
62
  marketplace. Services own state and resources; the host owns routing, persistence providers
63
63
  and server authorization.
64
64
 
65
+ ## Metadata and provenance
66
+
67
+ `src/metadata.ts` owns the pure public-field projection shared by build tools and runtime.
68
+ `projectPluginMetadataSources` accepts ordered `{ value, location }` sources so tools can name
69
+ actual diagnostic sources without changing the field validators. Included folder provenance
70
+ bindings preserve existing plugin metadata before package fallbacks.
71
+ `src/inspection/plugin-origin.ts` binds host evidence to definitions and projects membership
72
+ and groups; `src/inspection/inventory.ts` supplies serializable static/live inspection.
73
+ See the [identity and metadata reference](../../apps/docs/content/docs/reference/plugin-metadata.mdx).
74
+
65
75
  ## License
66
76
 
67
77
  [MIT](https://github.com/mvavesal/bitakit/blob/main/LICENSE). Third-party dependencies retain
68
78
  their own licenses.
79
+
80
+ ### Complete cohort replacement
81
+
82
+ Host-only `runtime.plugins.replace(ids, nextPlugins, { expectedRevision?, preserve? })` validates
83
+ an entire proposed composition before stopping any old owner. `plugins.preview({ operation:
84
+ 'replace', ids, plugins, ...options })` uses the same planner. Supply every owned descendant;
85
+ external dependents and outside ID collisions are refused. Empty old/new sets support addition
86
+ or removal. Providers, foundational services and other composition restrictions still return
87
+ `restart-required`. Cleanup is awaited; failed cleanup blocks reuse. A startup failure can leave
88
+ candidate definitions installed with failed lifecycle state; this API does not silently roll
89
+ back. Optional `@bitakit/packages` coordinates artifact recovery. Core never downloads or
90
+ persists code, and `reconcilePlugins` retains its existing narrower compatibility contract.
@@ -1,3 +1,4 @@
1
+ import { preservePluginOrigin } from './inspection/plugin-origin.js';
1
2
  const providersOf = (plugin) => plugin.ui?.providers ?? [];
2
3
  /** Undefined inherits. An explicit list replaces that domain, including an empty list. */
3
4
  export function resolveBitaKitConfig(discovered, overrides = {}) {
@@ -6,7 +7,7 @@ export function resolveBitaKitConfig(discovered, overrides = {}) {
6
7
  ...discovered,
7
8
  plugins: overrides.actions === undefined && overrides.interceptors === undefined
8
9
  ? selectedPlugins
9
- : selectedPlugins.map((plugin) => ({
10
+ : selectedPlugins.map((plugin) => preservePluginOrigin(plugin, {
10
11
  ...plugin,
11
12
  ...(overrides.actions === undefined ? {} : { actions: [] }),
12
13
  ...(overrides.interceptors === undefined ? {} : { interceptors: [] }),
package/dist/core.d.ts CHANGED
@@ -34,7 +34,9 @@ export { resolveText, createTranslationPlugin } from './translation.js';
34
34
  export { findPluginPage, validatePluginPages, pluginPage, pluginSlot, pluginProvider, pluginSettingsPage, pluginLayout, layoutSlots, layoutFamilies, type LayoutSlot, } from './pages.js';
35
35
  export { destinationMetadata, type Destination, type DestinationKind } from './destinations.js';
36
36
  export * from './actions/core.js';
37
- export { pluginMetadata } from './metadata.js';
37
+ export { pluginMetadata, pluginDisplayTitle, projectPluginMetadata, projectPluginMetadataSources, packageMetadataSources, type PluginMetadataSources, } from './metadata.js';
38
+ export { withPluginOrigin, pluginOrigin as getPluginOrigin, pluginMembership, groupPlugins, } from './inspection/plugin-origin.js';
39
+ export type { PluginOrigin, PluginOriginRecord, PackageIdentity, PluginBundle, PluginMembership, PluginGroup, } from './inspection/plugin-origin.js';
38
40
  export * from './discovered.js';
39
41
  export type { PresentationTypes, PresentationType, SlotMap, LegacySlotMap, SlotName, } from './presentation.js';
40
42
  export { defineSlot, isSlotDefinition } from './slots/define.js';
@@ -44,6 +46,6 @@ export type { ActionSlotPlacement } from './slots/action-placement.js';
44
46
  export { SlotError } from './slots/runtime.js';
45
47
  export { selectSingle, candidateNames, type SingleSelection } from './slots/select.js';
46
48
  export { configureAuthPaths, resolveAuthReturnTo, authSignInHref, type AuthPaths, type AuthSignInOptions, } from './auth-navigation.js';
47
- export type { PluginUpdateResult, PluginChangeResult, PluginDependentOptions, PluginChangeOptions, PluginToggleRequest, PluginChangePreview, PluginChangeReason, } from './lifecycle/reconcile.js';
49
+ export type { PluginUpdateResult, PluginChangeResult, PluginDependentOptions, PluginChangeOptions, PluginToggleRequest, PluginReplacementRequest, PluginChangePreview, PluginChangeReason, } from './lifecycle/reconcile.js';
48
50
  export { createInventory, inspectRuntime, observeRuntimeInventory, inventoryMetadata, } from './inspection/inventory.js';
49
51
  export type { RuntimeInventory, InventoryPlugin, InventoryDeclaration, InventoryMetadata, InventoryKind, InventoryLive, } from './inspection/inventory.js';
package/dist/core.js CHANGED
@@ -24,7 +24,8 @@ export { resolveText, createTranslationPlugin } from './translation.js';
24
24
  export { findPluginPage, validatePluginPages, pluginPage, pluginSlot, pluginProvider, pluginSettingsPage, pluginLayout, layoutSlots, layoutFamilies, } from './pages.js';
25
25
  export { destinationMetadata } from './destinations.js';
26
26
  export * from './actions/core.js';
27
- export { pluginMetadata } from './metadata.js';
27
+ export { pluginMetadata, pluginDisplayTitle, projectPluginMetadata, projectPluginMetadataSources, packageMetadataSources, } from './metadata.js';
28
+ export { withPluginOrigin, pluginOrigin as getPluginOrigin, pluginMembership, groupPlugins, } from './inspection/plugin-origin.js';
28
29
  export * from './discovered.js';
29
30
  export { defineSlot, isSlotDefinition } from './slots/define.js';
30
31
  export { SlotError } from './slots/runtime.js';
@@ -250,6 +250,14 @@ export type PluginUI = {
250
250
  };
251
251
  /** Public display information only; package authors remain the source of truth. */
252
252
  export type PluginMetadata = {
253
+ /** Canonical display title, distinct from package identity and the legacy name field. */
254
+ title?: string;
255
+ keywords?: readonly string[];
256
+ repository?: string | {
257
+ type?: string;
258
+ url: string;
259
+ directory?: string;
260
+ };
253
261
  coverImage?: string;
254
262
  /** Catalog labels; presentation only, never permissions or dependencies. */
255
263
  tags?: readonly string[];
@@ -332,6 +340,10 @@ export type BitaKitRuntimeConfig = Omit<Plugin, 'id' | 'dependencies' | 'parent'
332
340
  */
333
341
  choose?: Readonly<Record<string, string>>;
334
342
  plugins?: readonly Plugin[];
343
+ /** Application grouping identity; independent of appId and all execution namespaces. */
344
+ bundle?: string;
345
+ /** Host-known bundle labels. A plugin's membership claim does not add entries here. */
346
+ knownBundles?: readonly import('./inspection/plugin-origin.js').PluginBundle[];
335
347
  };
336
348
  /** A literal string wins; a widened `string` or a missing value falls back. */
337
349
  type LiteralOr<Value, Fallback> = [NonNullable<Value>] extends [string] ? string extends NonNullable<Value> ? Fallback : NonNullable<Value> : Fallback;
@@ -1,6 +1,7 @@
1
1
  import type { PluginMetadata } from '../definitions.js';
2
2
  import type { LifecyclePhase, LifecycleSnapshot } from '../lifecycle/state.js';
3
3
  import type { BitaKitRuntime } from '../runtime.js';
4
+ import { type PluginOrigin, type PackageIdentity, type PluginMembership } from './plugin-origin.js';
4
5
  export type InventoryKind = 'service' | 'action' | 'event' | 'page' | 'setting' | 'slot' | 'widget' | 'provider' | 'config' | 'interceptor';
5
6
  export type InventoryDeclaration = Readonly<{
6
7
  kind: InventoryKind;
@@ -8,15 +9,17 @@ export type InventoryDeclaration = Readonly<{
8
9
  source: string | null;
9
10
  resolution: 'resolved' | 'file';
10
11
  }>;
11
- export type InventoryMetadata = Readonly<Pick<PluginMetadata, 'name' | 'description' | 'version' | 'license' | 'homepage' | 'tags' | 'coverImage'> & {
12
+ export type InventoryMetadata = Readonly<Pick<PluginMetadata, 'name' | 'title' | 'description' | 'version' | 'license' | 'homepage' | 'tags' | 'keywords' | 'repository' | 'coverImage'> & {
12
13
  author?: string;
13
14
  support?: string;
14
15
  }>;
15
16
  export type InventoryPlugin = Readonly<{
16
- /** Stable inventory key; an unresolved package uses its export specifier. */
17
+ /** Inventory key within this installation; physical package keys may change with hoisting. */
17
18
  id: string;
18
19
  pluginId: string | null;
19
20
  enabled: boolean | null;
21
+ /** Static activation selection, separate from runtime enablement; null means not applicable. */
22
+ selected?: boolean | null;
20
23
  source: Readonly<{
21
24
  kind: 'runtime' | 'file' | 'package';
22
25
  path: string | null;
@@ -24,6 +27,14 @@ export type InventoryPlugin = Readonly<{
24
27
  metadata: InventoryMetadata;
25
28
  dependencies: readonly string[] | null;
26
29
  declarations: readonly InventoryDeclaration[] | null;
30
+ /** Additive host evidence; older inventory producers may omit these fields. */
31
+ origin?: PluginOrigin;
32
+ application?: boolean;
33
+ parent?: string | null;
34
+ package?: PackageIdentity | null;
35
+ declaredMembership?: readonly string[] | null;
36
+ membership?: PluginMembership;
37
+ metadataWarnings?: readonly string[];
27
38
  }>;
28
39
  export type InventoryLive = Readonly<{
29
40
  revision: number;
@@ -64,6 +75,10 @@ export type RuntimeInventory = Readonly<{
64
75
  static: Readonly<{
65
76
  plugins: readonly InventoryPlugin[];
66
77
  }>;
78
+ /** Optional passive-tooling diagnostics, without executing package code. */
79
+ diagnostics?: Readonly<{
80
+ identityConflicts: readonly string[];
81
+ }>;
67
82
  /** Null means there is no running process to inspect, never an empty/healthy runtime. */
68
83
  live: InventoryLive | null;
69
84
  }>;
@@ -79,6 +94,10 @@ export declare function observeRuntimeInventory(runtime: BitaKitRuntime): {
79
94
  static: Readonly<{
80
95
  plugins: readonly InventoryPlugin[];
81
96
  }>;
97
+ /** Optional passive-tooling diagnostics, without executing package code. */
98
+ diagnostics?: Readonly<{
99
+ identityConflicts: readonly string[];
100
+ }>;
82
101
  /** Null means there is no running process to inspect, never an empty/healthy runtime. */
83
102
  live: InventoryLive | null;
84
103
  }>;
@@ -1,9 +1,13 @@
1
+ import { projectPluginMetadata } from '../metadata.js';
1
2
  import { contributionSource } from '../contribution-origin.js';
3
+ import { pluginOrigin, pluginMembership, } from './plugin-origin.js';
2
4
  /** Public declaration metadata only; no icons, functions, defaults, credentials or arbitrary fields. */
3
5
  export function inventoryMetadata(metadata = {}) {
6
+ metadata = projectPluginMetadata(metadata).metadata;
4
7
  const result = {};
5
8
  for (const key of [
6
9
  'name',
10
+ 'title',
7
11
  'description',
8
12
  'version',
9
13
  'license',
@@ -20,6 +24,13 @@ export function inventoryMetadata(metadata = {}) {
20
24
  result.support = support;
21
25
  if (metadata.tags)
22
26
  result.tags = Object.freeze([...metadata.tags]);
27
+ if (metadata.keywords)
28
+ result.keywords = Object.freeze([...metadata.keywords]);
29
+ if (metadata.repository)
30
+ result.repository =
31
+ typeof metadata.repository === 'string'
32
+ ? metadata.repository
33
+ : Object.freeze({ ...metadata.repository });
23
34
  return Object.freeze(result);
24
35
  }
25
36
  /** Both static tooling and runtime readers produce this versioned, serializable envelope. */
@@ -38,10 +49,28 @@ export function inspectRuntime(runtime) {
38
49
  resolution: 'resolved',
39
50
  });
40
51
  const lifecycle = runtime.lifecycle.get();
52
+ const provenance = (id, parent) => {
53
+ const application = id === (runtime.config.appId ?? 'app');
54
+ const source = pluginOrigin(runtime.config.plugins?.find((plugin) => plugin.id === id));
55
+ return {
56
+ application,
57
+ origin: source?.kind ?? (application ? 'local' : 'unknown'),
58
+ ...(source?.metadataWarnings?.length ? { metadataWarnings: source.metadataWarnings } : {}),
59
+ parent: parent ?? null,
60
+ package: source?.package ?? null,
61
+ declaredMembership: source?.memberOf ?? null,
62
+ membership: pluginMembership(source, {
63
+ application,
64
+ bundle: runtime.config.bundle,
65
+ knownBundles: runtime.config.knownBundles,
66
+ }),
67
+ };
68
+ };
41
69
  return createInventory([
42
70
  ...runtime.modules.map((module) => Object.freeze({
43
71
  id: module.id,
44
72
  pluginId: module.id,
73
+ ...provenance(module.id, module.parent),
45
74
  enabled: true,
46
75
  source: Object.freeze({ kind: 'runtime', path: null }),
47
76
  metadata: inventoryMetadata(module.metadata),
@@ -66,6 +95,7 @@ export function inspectRuntime(runtime) {
66
95
  .map((plugin) => Object.freeze({
67
96
  id: plugin.id,
68
97
  pluginId: plugin.id,
98
+ ...provenance(plugin.id, plugin.parent),
69
99
  enabled: false,
70
100
  source: Object.freeze({ kind: 'runtime', path: null }),
71
101
  metadata: inventoryMetadata(plugin.metadata),
@@ -0,0 +1,60 @@
1
+ import { type PluginMetadataSources } from '../metadata.js';
2
+ import type { Plugin } from '../definitions.js';
3
+ export type PluginOrigin = 'local' | 'included' | 'package' | 'unknown';
4
+ export type PackageIdentity = Readonly<{
5
+ /** Complete lowercase name, including its npm scope. Never a runtime plugin ID. */
6
+ name: string;
7
+ version: string | null;
8
+ }>;
9
+ export type PluginOriginRecord = Readonly<{
10
+ kind: Exclude<PluginOrigin, 'unknown'>;
11
+ package?: PackageIdentity | null;
12
+ /** Authored membership; discovery validates it. ['*'] explicitly means general purpose. */
13
+ memberOf?: readonly string[] | null;
14
+ /** Authoritative ID of this single definition, never a prediction from its npm name. */
15
+ pluginId?: string | null;
16
+ /** Sanitized, statically available package sources; never executable UI metadata. */
17
+ metadata?: PluginMetadataSources;
18
+ /** Manifest path used by the host's static diagnostics, when known. */
19
+ metadataLocation?: string;
20
+ metadataWarnings?: readonly string[];
21
+ }>;
22
+ export type PluginBundle = Readonly<{
23
+ id: string;
24
+ label?: string;
25
+ }>;
26
+ export type PluginMembership = Readonly<{
27
+ state: 'derived' | 'declared' | 'general' | 'unspecified';
28
+ bundles: readonly Readonly<{
29
+ id: string;
30
+ resolved: boolean;
31
+ label?: string;
32
+ }>[];
33
+ }>;
34
+ /**
35
+ * Binds host-recorded provenance to a fresh definition without changing execution behavior.
36
+ * This is an attribution API for trusted hosts, not a sandbox or an authorization boundary.
37
+ */
38
+ export declare function withPluginOrigin<T extends Plugin>(plugin: T, record: PluginOriginRecord): T;
39
+ /** Reads host evidence for this definition only; never guesses from an ID or metadata. */
40
+ export declare function pluginOrigin(plugin: Plugin | undefined): PluginOriginRecord | undefined;
41
+ /** Internal composition transforms retain the host's evidence; replacement plugins do not. */
42
+ export declare function preservePluginOrigin<T extends Plugin>(from: Plugin, to: T): T;
43
+ /** Pure grouping projection. Membership never changes dependencies, ownership or enablement. */
44
+ export declare function pluginMembership(origin: PluginOriginRecord | undefined, context?: {
45
+ application?: boolean;
46
+ bundle?: string;
47
+ knownBundles?: readonly PluginBundle[];
48
+ }): PluginMembership;
49
+ export type PluginGroup<T> = Readonly<{
50
+ key: string;
51
+ kind: 'application' | 'bundle' | 'unresolved' | 'general' | 'unspecified';
52
+ label?: string;
53
+ bundleId?: string;
54
+ entries: readonly T[];
55
+ }>;
56
+ /** Groups distinct records; callers keep one shared instance/toggle for repeated appearances. */
57
+ export declare function groupPlugins<T extends {
58
+ id: string;
59
+ membership: PluginMembership;
60
+ }>(plugins: readonly T[], bundle?: string): readonly PluginGroup<T>[];
@@ -0,0 +1,128 @@
1
+ import { projectPluginMetadata, projectPluginMetadataSources, } from '../metadata.js';
2
+ // Host evidence follows the actual definition, never its ID or an array position. Definitions
3
+ // supplied later without a binding remain unknown, even if they replace the same runtime ID.
4
+ const origins = new WeakMap();
5
+ /**
6
+ * Binds host-recorded provenance to a fresh definition without changing execution behavior.
7
+ * This is an attribution API for trusted hosts, not a sandbox or an authorization boundary.
8
+ */
9
+ export function withPluginOrigin(plugin, record) {
10
+ if (record.pluginId != null && record.pluginId !== plugin.id)
11
+ throw new Error(`Package "${record.package?.name ?? 'unknown'}" declares plugin ID "${record.pluginId}" but loaded "${plugin.id}".`);
12
+ const packageLocation = record.metadataLocation ?? `package "${record.package?.name ?? 'unknown'}" manifest`;
13
+ const declared = { value: plugin.metadata, location: `plugin "${plugin.id}" metadata` };
14
+ const canonical = { value: record.metadata?.canonical, location: packageLocation };
15
+ const projected = record.metadata
16
+ ? projectPluginMetadataSources([
17
+ ...(record.kind === 'included' ? [declared, canonical] : [canonical, declared]),
18
+ { value: record.metadata.legacy, location: `${packageLocation} legacy fields` },
19
+ ], { packageName: record.package?.name })
20
+ : undefined;
21
+ const warnings = [
22
+ ...new Set([
23
+ ...(origins.get(plugin)?.metadataWarnings ?? []),
24
+ ...(record.metadataWarnings ?? []),
25
+ ...(projected?.warnings ?? []),
26
+ ]),
27
+ ];
28
+ const definition = {
29
+ ...plugin,
30
+ ...(projected ? { metadata: { ...plugin.metadata, ...projected.metadata } } : {}),
31
+ };
32
+ origins.set(definition, Object.freeze({
33
+ kind: record.kind,
34
+ ...(record.metadata
35
+ ? {
36
+ metadata: Object.freeze({
37
+ canonical: Object.freeze(projectPluginMetadata(record.metadata.canonical).metadata),
38
+ legacy: Object.freeze(projectPluginMetadata(record.metadata.legacy).metadata),
39
+ }),
40
+ }
41
+ : {}),
42
+ ...(record.metadataLocation ? { metadataLocation: record.metadataLocation } : {}),
43
+ ...(warnings.length ? { metadataWarnings: Object.freeze(warnings) } : {}),
44
+ ...(record.pluginId == null ? {} : { pluginId: record.pluginId }),
45
+ package: record.package
46
+ ? Object.freeze({
47
+ name: record.package.name.toLowerCase(),
48
+ version: record.package.version,
49
+ })
50
+ : null,
51
+ memberOf: record.memberOf ? Object.freeze([...record.memberOf]) : null,
52
+ }));
53
+ return definition;
54
+ }
55
+ /** Reads host evidence for this definition only; never guesses from an ID or metadata. */
56
+ export function pluginOrigin(plugin) {
57
+ return plugin && origins.get(plugin);
58
+ }
59
+ /** Internal composition transforms retain the host's evidence; replacement plugins do not. */
60
+ export function preservePluginOrigin(from, to) {
61
+ const record = origins.get(from);
62
+ if (record)
63
+ origins.set(to, record);
64
+ return to;
65
+ }
66
+ /** Pure grouping projection. Membership never changes dependencies, ownership or enablement. */
67
+ export function pluginMembership(origin, context = {}) {
68
+ const current = context.bundle?.toLowerCase();
69
+ const known = new Map((context.knownBundles ?? []).map((item) => [item.id.toLowerCase(), item]));
70
+ if (current && !known.has(current))
71
+ known.set(current, { id: current });
72
+ const project = (state, ids) => Object.freeze({
73
+ state,
74
+ bundles: Object.freeze([...new Set(ids.map((id) => id.toLowerCase()))].sort().map((id) => Object.freeze({
75
+ id,
76
+ resolved: known.has(id),
77
+ ...(known.get(id)?.label ? { label: known.get(id).label } : {}),
78
+ }))),
79
+ });
80
+ if (context.application || origin?.kind === 'local')
81
+ return project('derived', current ? [current] : []);
82
+ if (!origin)
83
+ return project('unspecified', []);
84
+ const declaration = origin.memberOf;
85
+ if (!Array.isArray(declaration) ||
86
+ !declaration.length ||
87
+ declaration.some((id) => typeof id !== 'string' || !id))
88
+ return project('unspecified', []);
89
+ if (declaration.includes('*'))
90
+ return project(declaration.length === 1 ? 'general' : 'unspecified', []);
91
+ return project('declared', declaration);
92
+ }
93
+ /** Groups distinct records; callers keep one shared instance/toggle for repeated appearances. */
94
+ export function groupPlugins(plugins, bundle) {
95
+ const current = bundle?.toLowerCase();
96
+ const groups = new Map();
97
+ const add = (key, kind, plugin, details = {}) => {
98
+ if (!groups.has(key))
99
+ groups.set(key, { key, kind, ...details, entries: [] });
100
+ const group = groups.get(key);
101
+ if (!group.entries.some((entry) => entry.id === plugin.id))
102
+ group.entries.push(plugin);
103
+ };
104
+ for (const plugin of plugins) {
105
+ const membership = plugin.membership;
106
+ if (membership.state === 'derived')
107
+ add('application', 'application', plugin);
108
+ else if (membership.state === 'general' || membership.state === 'unspecified')
109
+ add(membership.state, membership.state, plugin);
110
+ else
111
+ for (const entry of membership.bundles) {
112
+ if (entry.id === current)
113
+ add('application', 'application', plugin);
114
+ else
115
+ add(`bundle:${entry.id}`, entry.resolved ? 'bundle' : 'unresolved', plugin, {
116
+ bundleId: entry.id,
117
+ label: entry.label,
118
+ });
119
+ }
120
+ }
121
+ const rank = { application: 0, bundle: 1, unresolved: 2, general: 3, unspecified: 4 };
122
+ const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
123
+ return Object.freeze([...groups.values()]
124
+ .sort((a, b) => rank[a.kind] - rank[b.kind] ||
125
+ compare(a.label ?? a.bundleId ?? a.key, b.label ?? b.bundleId ?? b.key) ||
126
+ compare(a.key, b.key))
127
+ .map((group) => Object.freeze({ ...group, entries: Object.freeze(group.entries) })));
128
+ }
@@ -35,10 +35,19 @@ type Methods<S> = {
35
35
  type ServiceOf<Name extends string> = Name extends keyof ServiceMap ? NonNullable<ServiceMap[Name]> : Record<string, (...args: any[]) => unknown>;
36
36
  type MethodOf<Name extends string, Key extends string> = Key extends keyof ServiceOf<Name> ? Extract<ServiceOf<Name>[Key], (...args: any[]) => any> : (...args: any[]) => unknown;
37
37
  export type ServiceCall<Name extends string = string, Key extends string = string> = {
38
- readonly service: Name;
38
+ /** The called service's ID; a glob or alias target still reports the actual ID. */
39
+ readonly service: string;
39
40
  readonly method: Key;
40
41
  readonly args: Readonly<Parameters<MethodOf<Name, Key>>>;
41
42
  };
43
+ /**
44
+ * What a service hook receives besides the call: the services, as Action interceptors get them,
45
+ * so an observer can record into its own service. Calls to the observer's own service are
46
+ * observed too; skip them to avoid recursion.
47
+ */
48
+ export type ServiceHookContext = {
49
+ readonly services: Services;
50
+ };
42
51
  /** Observes one method or every public method of a service. Hooks never change the outcome. */
43
52
  export type ServiceInterceptorSpec<Name extends string = string, Key extends string = string> = {
44
53
  readonly kind?: 'interceptor';
@@ -48,11 +57,11 @@ export type ServiceInterceptorSpec<Name extends string = string, Key extends str
48
57
  scope?: never;
49
58
  requires?: never;
50
59
  order?: number;
51
- before?(call: ServiceCall<Name, Key>): void;
52
- after?(call: ServiceCall<Name, Key> & {
60
+ before?(call: ServiceCall<Name, Key> & ServiceHookContext): void;
61
+ after?(call: ServiceCall<Name, Key> & ServiceHookContext & {
53
62
  readonly result: Awaited<ReturnType<MethodOf<Name, Key>>>;
54
63
  }): void;
55
- onError?(call: ServiceCall<Name, Key> & {
64
+ onError?(call: ServiceCall<Name, Key> & ServiceHookContext & {
56
65
  readonly error: unknown;
57
66
  }): void;
58
67
  };
@@ -1,6 +1,7 @@
1
1
  import { type InterceptorSpec } from './define.js';
2
2
  /**
3
3
  * Wraps service instances whose ID or alias matches an interceptor's `service` target. All
4
- * container consumers receive the same wrapper; frozen instances are supported.
4
+ * container consumers receive the same wrapper; frozen instances are supported. `services`
5
+ * is read when a call happens, because the service tree exists only after the container does.
5
6
  */
6
- export declare function serviceObserver(interceptors: readonly InterceptorSpec[], namesOf: (id: string) => readonly string[]): (id: string, instance: any, active: () => boolean) => any;
7
+ export declare function serviceObserver(interceptors: readonly InterceptorSpec[], namesOf: (id: string) => readonly string[], services: () => unknown): (id: string, instance: any, active: () => boolean) => any;
@@ -12,9 +12,10 @@ function notify(callback, event) {
12
12
  }
13
13
  /**
14
14
  * Wraps service instances whose ID or alias matches an interceptor's `service` target. All
15
- * container consumers receive the same wrapper; frozen instances are supported.
15
+ * container consumers receive the same wrapper; frozen instances are supported. `services`
16
+ * is read when a call happens, because the service tree exists only after the container does.
16
17
  */
17
- export function serviceObserver(interceptors, namesOf) {
18
+ export function serviceObserver(interceptors, namesOf, services) {
18
19
  const entries = interceptors
19
20
  .filter(isServiceInterceptor)
20
21
  .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
@@ -47,7 +48,9 @@ export function serviceObserver(interceptors, namesOf) {
47
48
  const observers = typeof key === 'string'
48
49
  ? selected.filter((entry) => entry.method === undefined || entry.method === key)
49
50
  : [];
50
- const wrapped = (...args) => {
51
+ // A function Proxy keeps the method's own properties (for example `translate.has`);
52
+ // only the call itself is observed.
53
+ const call = (...args) => {
51
54
  const emit = (phase, extra = {}) => {
52
55
  if (!active())
53
56
  return;
@@ -56,6 +59,7 @@ export function serviceObserver(interceptors, namesOf) {
56
59
  service: id,
57
60
  method: key,
58
61
  args: Object.freeze([...args]),
62
+ services: services(),
59
63
  ...extra,
60
64
  });
61
65
  };
@@ -75,6 +79,9 @@ export function serviceObserver(interceptors, namesOf) {
75
79
  emit('after', { result });
76
80
  return result;
77
81
  };
82
+ const wrapped = new Proxy(value, {
83
+ apply: (_method, _this, args) => call(...args),
84
+ });
78
85
  cache.set(key, { original: value, wrapped });
79
86
  return wrapped;
80
87
  },
@@ -25,6 +25,12 @@ export type PluginToggleRequest = PluginChangeOptions & (Readonly<{
25
25
  id: string;
26
26
  dependents: 'stop' | 'refuse';
27
27
  }>);
28
+ /** Complete owned cohort replacement. External dependents must be updated separately. */
29
+ export type PluginReplacementRequest = PluginChangeOptions & Readonly<{
30
+ operation: 'replace';
31
+ ids: readonly string[];
32
+ plugins: readonly Plugin[];
33
+ }>;
28
34
  export type PluginChangeReason = 'busy' | 'cleanup-failed' | 'stale' | 'protected' | 'dependents' | 'owner-disabled' | 'composition' | 'invalid' | 'pending-settings';
29
35
  /** Read-only planning result. It grants no authority to execute a stale operation. */
30
36
  export type PluginChangePreview = Readonly<{
@@ -1,3 +1,28 @@
1
1
  import type { PluginMetadata } from './definitions.js';
2
- /** Copy public package fields only; never bundle scripts, config or arbitrary manifest data. */
2
+ export type PluginMetadataSources = Readonly<{
3
+ canonical?: PluginMetadata;
4
+ legacy?: PluginMetadata;
5
+ }>;
6
+ /** Shared display fallback; callers apply translations and explicit section labels first. */
7
+ export declare function pluginDisplayTitle(metadata: Pick<PluginMetadata, 'title' | 'name'> | undefined, fallback: string): string;
8
+ export declare function pluginDisplayTitle(metadata: Pick<PluginMetadata, 'title' | 'name'> | undefined): string | undefined;
9
+ /** One pure projection for build, discovery and runtime. Invalid optional values fall back per
10
+ * field; executable icons and arbitrary package fields never enter the serializable result. */
11
+ export declare function projectPluginMetadata(canonical?: unknown, ...legacy: unknown[]): {
12
+ metadata: PluginMetadata;
13
+ warnings: string[];
14
+ };
15
+ /** Projects ordered sources with truthful diagnostic labels. The first valid field wins. */
16
+ export declare function projectPluginMetadataSources(sources: readonly {
17
+ value: unknown;
18
+ location: string;
19
+ }[], { packageName }?: {
20
+ packageName?: string;
21
+ }): {
22
+ metadata: PluginMetadata;
23
+ warnings: string[];
24
+ };
25
+ /** Standard npm data plus the existing bitakit block; npm name stays package identity. */
26
+ export declare function packageMetadataSources(source: Record<string, unknown>): PluginMetadataSources;
27
+ /** Compatibility helper: copies supported public fields, without arbitrary manifest data. */
3
28
  export declare function pluginMetadata(source: PluginMetadata): PluginMetadata;
package/dist/metadata.js CHANGED
@@ -1,13 +1,95 @@
1
- /** Copy public package fields only; never bundle scripts, config or arbitrary manifest data. */
2
- export function pluginMetadata(source) {
3
- const { name, version, description, author, homepage, bugs, license } = source;
1
+ import { z } from 'zod';
2
+ // Optional descriptive shapes only. Loading policy, npm identity, URLs, licensing and
3
+ // compatibility have their own owners; metadata does not invent additional admission rules.
4
+ const fields = {
5
+ name: z.string(),
6
+ title: z.string(),
7
+ version: z.string(),
8
+ description: z.string(),
9
+ author: z.union([
10
+ z.string(),
11
+ z.object({ name: z.string(), email: z.string().optional(), url: z.string().optional() }),
12
+ ]),
13
+ homepage: z.string(),
14
+ bugs: z.union([
15
+ z.string(),
16
+ z.object({ url: z.string().optional(), email: z.string().optional() }),
17
+ ]),
18
+ license: z.string(),
19
+ coverImage: z.string(),
20
+ tags: z.array(z.string()),
21
+ keywords: z.array(z.string()),
22
+ repository: z.union([
23
+ z.string(),
24
+ z.object({ type: z.string().optional(), url: z.string(), directory: z.string().optional() }),
25
+ ]),
26
+ };
27
+ export function pluginDisplayTitle(metadata, fallback) {
28
+ return metadata?.title ?? metadata?.name ?? fallback;
29
+ }
30
+ /** One pure projection for build, discovery and runtime. Invalid optional values fall back per
31
+ * field; executable icons and arbitrary package fields never enter the serializable result. */
32
+ export function projectPluginMetadata(canonical = {}, ...legacy) {
33
+ return projectPluginMetadataSources([
34
+ { value: canonical, location: 'canonical metadata' },
35
+ ...legacy.map((value) => ({ value, location: 'legacy metadata' })),
36
+ ]);
37
+ }
38
+ /** Projects ordered sources with truthful diagnostic labels. The first valid field wins. */
39
+ export function projectPluginMetadataSources(sources, { packageName } = {}) {
40
+ const metadata = {};
41
+ const warnings = [];
42
+ const owners = new Map();
43
+ for (const key of Object.keys(fields)) {
44
+ for (const [index, { value: source, location }] of sources.entries()) {
45
+ if (!source || typeof source !== 'object')
46
+ continue;
47
+ const value = source[key];
48
+ if (value === undefined)
49
+ continue;
50
+ const parsed = fields[key].safeParse(value);
51
+ if (!parsed.success) {
52
+ warnings.push(`Invalid optional metadata.${key} in ${location}; using the next available source.`);
53
+ continue;
54
+ }
55
+ const owner = owners.get(key);
56
+ if (owner === undefined) {
57
+ Object.assign(metadata, { [key]: parsed.data });
58
+ owners.set(key, index);
59
+ }
60
+ else if (JSON.stringify(metadata[key]) !== JSON.stringify(parsed.data)) {
61
+ warnings.push(`Conflicting metadata.${key}: ${sources[owner].location} takes precedence over ${location}.`);
62
+ }
63
+ }
64
+ }
65
+ const titleOwner = owners.get('title');
66
+ const nameOwner = owners.get('name');
67
+ if (titleOwner !== undefined &&
68
+ nameOwner !== undefined &&
69
+ titleOwner !== nameOwner &&
70
+ !(packageName && metadata.name?.toLowerCase() === packageName.toLowerCase()) &&
71
+ metadata.title !== metadata.name)
72
+ warnings.push(`Conflicting display title: metadata.title in ${sources[titleOwner].location} takes precedence over metadata.name in ${sources[nameOwner].location}.`);
73
+ return { metadata, warnings: [...new Set(warnings)] };
74
+ }
75
+ /** Standard npm data plus the existing bitakit block; npm name stays package identity. */
76
+ export function packageMetadataSources(source) {
77
+ const block = source.bitakit ?? source.foundation;
78
+ const bitakit = block && typeof block === 'object' ? block : {};
79
+ const canonical = {};
80
+ for (const key of Object.keys(fields)) {
81
+ if (key === 'name')
82
+ continue;
83
+ const value = ['title', 'tags', 'coverImage'].includes(key) ? bitakit[key] : source[key];
84
+ if (value !== undefined)
85
+ canonical[key] = value;
86
+ }
4
87
  return {
5
- ...(name === undefined ? {} : { name }),
6
- ...(version === undefined ? {} : { version }),
7
- ...(description === undefined ? {} : { description }),
8
- ...(author === undefined ? {} : { author }),
9
- ...(homepage === undefined ? {} : { homepage }),
10
- ...(bugs === undefined ? {} : { bugs }),
11
- ...(license === undefined ? {} : { license }),
88
+ canonical,
89
+ legacy: { tags: source.tags, coverImage: source.coverImage },
12
90
  };
13
91
  }
92
+ /** Compatibility helper: copies supported public fields, without arbitrary manifest data. */
93
+ export function pluginMetadata(source) {
94
+ return projectPluginMetadata(source).metadata;
95
+ }
package/dist/runtime.d.ts CHANGED
@@ -12,7 +12,7 @@ import { type Feedback, type MessageValues } from './actions/feedback.js';
12
12
  import { type ContributionHost, type DialogState, type FeedbackOutcome, type OpenableDefinition, type Override } from './contributions/index.js';
13
13
  import type { Confirmation } from './confirmation.js';
14
14
  import { type LifecycleState } from './lifecycle/state.js';
15
- import { type PluginUpdateResult, type PluginDependentOptions, type PluginChangeOptions, type PluginToggleRequest, type PluginChangePreview } from './lifecycle/reconcile.js';
15
+ import { type PluginUpdateResult, type PluginDependentOptions, type PluginChangeOptions, type PluginToggleRequest, type PluginReplacementRequest, type PluginChangePreview } from './lifecycle/reconcile.js';
16
16
  export type { DialogState } from './contributions/index.js';
17
17
  /** A plugin after normalization: records resolved to arrays with IDs, `ui` merged with the legacy fields. */
18
18
  export type NormalizedPlugin = Omit<Plugin, 'services' | 'actions' | 'slots'> & {
@@ -85,6 +85,14 @@ export declare class BitaKitRuntime implements ContributionHost {
85
85
  affected: readonly string[];
86
86
  reasons: readonly string[];
87
87
  }>>;
88
+ /** Replace a complete cohort after candidate validation; refuses external dependents. */
89
+ replace: (ids: readonly string[], plugins: readonly Plugin[], options?: PluginChangeOptions) => Promise<Readonly<{
90
+ status: "applied" | "blocked" | "failed" | "restart-required";
91
+ revision: number;
92
+ changed: readonly string[];
93
+ affected: readonly string[];
94
+ reasons: readonly string[];
95
+ }>>;
88
96
  enable: (id: string, options?: PluginChangeOptions) => Promise<Readonly<{
89
97
  status: "applied" | "blocked" | "failed" | "restart-required";
90
98
  revision: number;
@@ -100,7 +108,7 @@ export declare class BitaKitRuntime implements ContributionHost {
100
108
  reasons: readonly string[];
101
109
  }>>;
102
110
  /** Preview uses the execution planner without stopping owners or changing retained intent. */
103
- preview: (request: PluginToggleRequest) => PluginChangePreview;
111
+ preview: (request: PluginToggleRequest | PluginReplacementRequest) => PluginChangePreview;
104
112
  }>;
105
113
  private revision;
106
114
  getRevision: () => number;
package/dist/runtime.js CHANGED
@@ -199,10 +199,14 @@ export class BitaKitRuntime {
199
199
  plugins = Object.freeze({
200
200
  add: (plugins) => this.changePlugins('add', [...plugins]),
201
201
  remove: (ids, options) => this.changePlugins('remove', [...ids], options),
202
+ /** Replace a complete cohort after candidate validation; refuses external dependents. */
203
+ replace: (ids, plugins, options) => this.changePlugins('replace', [...ids], options, [...plugins]),
202
204
  enable: (id, options) => this.changePlugins('enable', [id], options),
203
205
  disable: (id, options) => this.changePlugins('disable', [id], options),
204
206
  /** Preview uses the execution planner without stopping owners or changing retained intent. */
205
- preview: (request) => this.planPluginChange(request.operation, [request.id], request).preview,
207
+ preview: (request) => request.operation === 'replace'
208
+ ? this.planPluginChange('replace', request.ids, request, request.plugins).preview
209
+ : this.planPluginChange(request.operation, [request.id], request).preview,
206
210
  });
207
211
  revision = 0;
208
212
  getRevision = () => this.revision;
@@ -686,7 +690,7 @@ export class BitaKitRuntime {
686
690
  const interceptors = plugins.flatMap((plugin) => plugin.interceptors ?? []);
687
691
  this.container = createServices(plugins.flatMap((plugin) => plugin.services), this.providedServices, (definition) => this.configuration.context(owners.get(definition) ??
688
692
  this.modules.find((module) => module.services.includes(definition))?.id ??
689
- this.appId), serviceObserver(interceptors, (id) => this.aliasesOf(id)), this.events, {
693
+ this.appId), serviceObserver(interceptors, (id) => this.aliasesOf(id), () => this.view), this.events, {
690
694
  names: this.names,
691
695
  appId: this.appId,
692
696
  moduleOf: (definition) => owners.get(definition) ??
@@ -1091,8 +1095,8 @@ export class BitaKitRuntime {
1091
1095
  this.actions.refresh();
1092
1096
  }
1093
1097
  /** Execute the same plan used by preview; there is no await between validation and exclusion. */
1094
- changePlugins(operation, values, options) {
1095
- const plan = this.planPluginChange(operation, values, options);
1098
+ changePlugins(operation, values, options, replacement = []) {
1099
+ const plan = this.planPluginChange(operation, values, options, replacement);
1096
1100
  if (plan.apply)
1097
1101
  return plan.apply();
1098
1102
  const { status, revision, changed, affected, reasons } = plan.preview;
@@ -1105,7 +1109,7 @@ export class BitaKitRuntime {
1105
1109
  });
1106
1110
  }
1107
1111
  /** Validate without starting services, invoking hooks or mutating retained lifecycle intent. */
1108
- planPluginChange(operation, values, options) {
1112
+ planPluginChange(operation, values, options, replacement = []) {
1109
1113
  let changed = [];
1110
1114
  let affected = [];
1111
1115
  let dependents = [];
@@ -1155,6 +1159,19 @@ export class BitaKitRuntime {
1155
1159
  }
1156
1160
  // Ownership: a parent's descendants follow it, whatever the dependents policy says.
1157
1161
  const owned = descendantsOf(installed, ids);
1162
+ if (operation === 'replace') {
1163
+ const incoming = replacement.map((plugin) => plugin.id);
1164
+ if (new Set(incoming).size !== incoming.length || incoming.includes(this.appId))
1165
+ return result('blocked', ['Replacement plugin IDs must be unique and exclude the app.']);
1166
+ if (owned.some((id) => !ids.includes(id)))
1167
+ return result('blocked', ['Replacement must include every owned descendant.']);
1168
+ for (const id of incoming)
1169
+ if (!ids.includes(id) && installed.some((plugin) => plugin.id === id))
1170
+ return result('blocked', [`Plugin "${id}" is owned outside the replacement cohort.`]);
1171
+ dependents = updateClosure(modules, ids).filter((id) => !ids.includes(id));
1172
+ if (dependents.length)
1173
+ return result('blocked', [`Enabled dependents: ${dependents.join(', ')}.`], 'dependents', dependents);
1174
+ }
1158
1175
  const cascaded = new Map(this.disabledWithParent);
1159
1176
  if (operation === 'remove')
1160
1177
  ids.push(...owned);
@@ -1195,19 +1212,31 @@ export class BitaKitRuntime {
1195
1212
  for (const id of ids)
1196
1213
  disabled.delete(id);
1197
1214
  }
1215
+ else if (operation === 'replace') {
1216
+ changed = [...new Set([...ids, ...replacement.map((plugin) => plugin.id)])];
1217
+ for (const id of ids) {
1218
+ disabled.delete(id);
1219
+ cascaded.delete(id);
1220
+ }
1221
+ }
1198
1222
  else
1199
1223
  installed.push(...values);
1200
1224
  if (operation === 'remove')
1201
1225
  for (const id of ids)
1202
1226
  cascaded.delete(id);
1203
- const nextInstalled = operation === 'remove' ? installed.filter((plugin) => !ids.includes(plugin.id)) : installed;
1227
+ const nextInstalled = operation === 'replace'
1228
+ ? [...installed.filter((plugin) => !ids.includes(plugin.id)), ...replacement]
1229
+ : operation === 'remove'
1230
+ ? installed.filter((plugin) => !ids.includes(plugin.id))
1231
+ : installed;
1204
1232
  for (const id of ids)
1205
1233
  if (operation === 'remove')
1206
1234
  disabled.delete(id);
1207
1235
  if (operation === 'disable')
1208
1236
  changed = changed.filter((id) => !this.disabledPlugins.has(id));
1209
1237
  const protectedOwners = changed.filter((id) => options?.preserve?.includes(id));
1210
- if ((operation === 'disable' || operation === 'remove') && protectedOwners.length)
1238
+ if ((operation === 'disable' || operation === 'remove' || operation === 'replace') &&
1239
+ protectedOwners.length)
1211
1240
  return result('blocked', ['The host requires these plugins to remain enabled.'], 'protected', protectedOwners);
1212
1241
  if (!changed.length) {
1213
1242
  const plan = result('ready', []);
@@ -3,13 +3,19 @@ import type { PresentationType } from '../presentation.js';
3
3
  import type { GeneratedName } from '../names.js';
4
4
  /** Who a value belongs to: the signed-in user, the active organization, or this browser. */
5
5
  export type SettingScope = 'user' | 'organization' | 'device';
6
- export type SettingControl = 'switch' | 'select' | 'radio' | 'cards' | 'text' | 'textarea' | 'number';
6
+ /**
7
+ * How a generated settings page edits a value. `list` edits a list of short texts (add and
8
+ * remove); `checkboxes` chooses several of the options (a list default).
9
+ */
10
+ export type SettingControl = 'switch' | 'select' | 'radio' | 'cards' | 'text' | 'textarea' | 'number' | 'list' | 'checkboxes';
7
11
  export type SettingOption<T = unknown> = {
8
12
  readonly value: T;
9
13
  readonly label?: string;
10
14
  readonly description?: string;
11
15
  readonly icon?: PresentationType<'icon'>;
12
16
  };
17
+ /** The value of one option: the setting's value, or one item of a list setting. */
18
+ type OptionValue<T> = T extends readonly (infer Item)[] ? Item : T;
13
19
  declare const settingType: unique symbol;
14
20
  /** One declared setting. Values are read and written through `settings.<plugin>.<name>`. */
15
21
  export type SettingSpec<T = unknown> = {
@@ -22,7 +28,7 @@ export type SettingSpec<T = unknown> = {
22
28
  readonly description?: string;
23
29
  /** Presentation hint for generated settings pages; inferred from the value when omitted. */
24
30
  readonly control?: SettingControl;
25
- readonly options?: readonly SettingOption<T>[];
31
+ readonly options?: readonly SettingOption<OptionValue<T>>[];
26
32
  readonly order?: number;
27
33
  readonly group?: string;
28
34
  /** Readable and writable, but left out of generated settings pages. */
@@ -36,7 +42,7 @@ type SettingInput<T> = {
36
42
  label?: string;
37
43
  description?: string;
38
44
  control?: SettingControl;
39
- options?: readonly SettingOption<T>[];
45
+ options?: readonly SettingOption<OptionValue<T>>[];
40
46
  order?: number;
41
47
  group?: string;
42
48
  hidden?: boolean;
@@ -45,6 +51,15 @@ type SettingInput<T> = {
45
51
  export declare function setting<S extends InputSchema<any>>(spec: Omit<SettingInput<SchemaOutput<S>>, 'schema'> & {
46
52
  schema: S;
47
53
  }): SettingSpec<SchemaOutput<S>>;
54
+ /**
55
+ * `setting({ default: ['email'], options: [{ value: 'email' }, { value: 'sms' }] })`: several of
56
+ * the options, a list of the option union (shown as checkboxes).
57
+ */
58
+ export declare function setting<const O extends readonly SettingOption<any>[]>(spec: Omit<SettingInput<O[number]['value'][]>, 'schema' | 'options' | 'default'> & {
59
+ schema?: undefined;
60
+ default: readonly O[number]['value'][];
61
+ options: O;
62
+ }): SettingSpec<O[number]['value'][]>;
48
63
  /** `setting({ default: 'system', options: [{ value: 'light' }, ...] })`: the type is the option union. */
49
64
  export declare function setting<const O extends readonly SettingOption<any>[]>(spec: Omit<SettingInput<O[number]['value']>, 'schema' | 'options'> & {
50
65
  schema?: undefined;
@@ -8,6 +8,8 @@ const controls = [
8
8
  'text',
9
9
  'textarea',
10
10
  'number',
11
+ 'list',
12
+ 'checkboxes',
11
13
  ];
12
14
  export function setting(spec) {
13
15
  if (!spec || typeof spec !== 'object' || !('default' in spec))
@@ -70,10 +72,15 @@ export function parseSetting(spec, value, key = 'setting') {
70
72
  return checked.value;
71
73
  }
72
74
  if (spec.options) {
73
- if (!spec.options.some((option) => Object.is(option.value, value)))
74
- throw new Error(`Setting "${key}" accepts ${spec.options.map((option) => show(option.value)).join(', ')}; got ${show(value)}.`);
75
+ const accepts = (item) => spec.options.some((option) => Object.is(option.value, item));
76
+ // A list default chooses several of the options.
77
+ const several = Array.isArray(spec.default);
78
+ if (several ? !Array.isArray(value) || !value.every(accepts) : !accepts(value))
79
+ throw new Error(`Setting "${key}" accepts ${several ? 'a list of ' : ''}${spec.options.map((option) => show(option.value)).join(', ')}; got ${show(value)}.`);
75
80
  return value;
76
81
  }
82
+ if (Array.isArray(spec.default) && !Array.isArray(value))
83
+ throw new Error(`Setting "${key}" expects a list; got ${show(value)}.`);
77
84
  const expected = typeof spec.default;
78
85
  if (spec.default !== null && spec.default !== undefined && typeof value !== expected)
79
86
  throw new Error(`Setting "${key}" expects a ${expected}; got ${value === null ? 'null' : typeof value}.`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bitakit/core",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "files": [
@@ -38,10 +38,11 @@
38
38
  "dev": "tsc -p tsconfig.json --watch"
39
39
  },
40
40
  "dependencies": {
41
+ "zod": "^4.6.7",
41
42
  "zustand": "^5.0.0"
42
43
  },
43
44
  "peerDependencies": {
44
- "@bitakit/discovery": "^0.2.2",
45
+ "@bitakit/discovery": "^0.2.5",
45
46
  "jiti": "^2.7.0"
46
47
  },
47
48
  "peerDependenciesMeta": {
@@ -53,7 +54,7 @@
53
54
  }
54
55
  },
55
56
  "devDependencies": {
56
- "@bitakit/discovery": "^0.2.4",
57
+ "@bitakit/discovery": "^0.2.5",
57
58
  "jiti": "^2.7.0",
58
59
  "typescript": "^5.9.3"
59
60
  },
package/testing/index.mjs CHANGED
@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
2
2
  import path from 'node:path';
3
3
  import { pathToFileURL } from 'node:url';
4
4
  import { createJiti } from 'jiti';
5
- import { describeModule } from '@bitakit/discovery';
5
+ import { describeModule, packagePluginId } from '@bitakit/discovery';
6
6
  import {
7
7
  createRuntime,
8
8
  discoverActions,
@@ -23,14 +23,7 @@ async function packageId(directory) {
23
23
  .then(JSON.parse)
24
24
  .catch(() => undefined);
25
25
  if (manifest)
26
- return (
27
- manifest.bitakit?.id ??
28
- manifest.foundation?.id ??
29
- (manifest.name ?? '')
30
- .replace(/^@[^/]+\//, '')
31
- .replace(/^bitakit-(plugin-)?/, '')
32
- .replace(/-plugin$/, '')
33
- );
26
+ return (manifest.bitakit ?? manifest.foundation)?.id ?? packagePluginId(manifest.name);
34
27
  if (path.dirname(folder) === folder) return undefined;
35
28
  }
36
29
  }