Integrate settings service and plugin wiring

Add the Settings service as a capability and wire it into the CLI and runtime: include @objectstack/service-settings in package.json, add the settings capability to CAPABILITY_PROVIDERS, and register the plugin in the serve command. Update the example app config and built artifact to require the settings capability. Enhance the service-settings package: export builtin manifests, register built-in action handlers (mail.test) by default, allow passing custom manifests and action handlers, and add bindEngine to late-bind the real data engine and audit sink instead of re-instantiating the service at start. Also tidy mail manifest typing/shape and propagate action handler registration on init. Update pnpm lockfile to reflect the new workspace dependency and resolved package changes.

Author: hotlong

examples/app-crm/dist/objectstack.json

@@ -25942,6 +25942,7 @@
     "ui",
     "storage",
     "approvals",
-    "sharing"
+    "sharing",
+    "settings"
   ]
 }

examples/app-crm/objectstack.config.ts

@@ -48,7 +48,7 @@ export default defineStack({
   // `ui`   serves the Studio shell and CRM apps under /_studio/.
   // Both are required for a clickable login flow when running `objectstack start`
   // off the compiled artifact.
-  requires: ['ai', 'automation', 'analytics', 'auth', 'ui', 'storage', 'approvals', 'sharing'],
+  requires: ['ai', 'automation', 'analytics', 'auth', 'ui', 'storage', 'approvals', 'sharing', 'settings'],
 
   objects: Object.values(objects),
   actions: Object.values(actions),

packages/cli/package.json

@@ -68,6 +68,7 @@
     "@objectstack/service-package": "workspace:*",
     "@objectstack/service-queue": "workspace:*",
     "@objectstack/service-realtime": "workspace:*",
+    "@objectstack/service-settings": "workspace:*",
     "@objectstack/service-storage": "workspace:*",
     "@objectstack/spec": "workspace:*",
     "@oclif/core": "^4.11.3",

packages/cli/src/commands/serve.ts

@@ -987,6 +987,11 @@ export default class Serve extends Command {
           export: 'ApprovalsServicePlugin',
           nameMatch: ['plugin-approvals', 'ApprovalsServicePlugin'],
         },
+        settings: {
+          pkg: '@objectstack/service-settings',
+          export: 'SettingsServicePlugin',
+          nameMatch: ['service-settings', 'SettingsServicePlugin'],
+        },
       };
 
       const hasPluginMatching = (fragments: string[]) =>

packages/runtime/src/cloud/capability-loader.ts

@@ -93,6 +93,10 @@ export const CAPABILITY_PROVIDERS: Record<string, CapabilitySpec> = {
         pkg: '@objectstack/service-feed',
         export: 'FeedServicePlugin',
     },
+    settings: {
+        pkg: '@objectstack/service-settings',
+        export: 'SettingsServicePlugin',
+    },
 };
 
 type Logger = { info?: (...a: any[]) => void; warn?: (...a: any[]) => void; error?: (...a: any[]) => void };

packages/services/service-settings/src/index.ts

@@ -37,6 +37,17 @@ export {
   SETTINGS_PLUGIN_VERSION,
 } from './manifest.js';
 
+// Reference manifests (mail / branding / feature flags) and the
+// convenience aggregate. Hosts can pass `builtinSettingsManifests`
+// directly to `new SettingsServicePlugin({ manifests })`.
+export {
+  builtinSettingsManifests,
+  brandingSettingsManifest,
+  featureFlagsSettingsManifest,
+  mailSettingsManifest,
+  mailTestActionHandler,
+} from './manifests/index.js';
+
 // Re-export the spec types for convenience so plugin authors only need
 // one import.
 export type {

packages/services/service-settings/src/manifests/mail.manifest.ts

@@ -1,9 +1,14 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { SettingsManifest, SettingsActionHandler } from '@objectstack/spec/system';
+import type { SettingsManifest } from '@objectstack/spec/system';
+import type { SettingsActionHandler } from '../settings-service.types.js';
 
-/** Mail Delivery — SMTP / API provider configuration. */
-export const mailSettingsManifest: SettingsManifest = {
+// Visibility expressions are written as inline strings here for
+// readability. The spec's ExpressionInputSchema accepts a bare string
+// and normalises it at parse time, but the inferred TypeScript output
+// type expects `{ dialect, source }` objects. Build the manifest as
+// `unknown` first, then cast — keeps the manifest source compact.
+const manifest = {
   namespace: 'mail',
   version: 1,
   label: 'Mail Delivery',
@@ -53,6 +58,9 @@ export const mailSettingsManifest: SettingsManifest = {
   ],
 };
 
+/** Mail Delivery — SMTP / API provider configuration. */
+export const mailSettingsManifest = manifest as unknown as SettingsManifest;
+
 /** Built-in action handler stub for `mail/test`. */
 export const mailTestActionHandler: SettingsActionHandler = async ({ values }) => {
   const provider = String(values.provider ?? 'smtp');

packages/services/service-settings/src/settings-service-plugin.ts

@@ -13,10 +13,19 @@ import {
   SETTINGS_PLUGIN_ID,
   SETTINGS_PLUGIN_VERSION,
 } from './manifest.js';
+import {
+  builtinSettingsManifests,
+  mailTestActionHandler,
+} from './manifests/index.js';
 
 /** Configuration options for the SettingsServicePlugin. */
 export interface SettingsServicePluginOptions {
-  /** Pre-register these manifests at boot. */
+  /**
+   * Pre-register these manifests at boot. When omitted, the bundled
+   * builtin manifests (mail / branding / feature_flags) are loaded so
+   * a host gets a working Settings hub out of the box. Pass an empty
+   * array to opt out entirely.
+   */
   manifests?: SettingsManifest[];
   /** Override the default crypto adapter. */
   crypto?: CryptoAdapter;
@@ -26,6 +35,12 @@ export interface SettingsServicePluginOptions {
   registerRoutes?: boolean;
   /** Override the env source. Defaults to `process.env`. */
   env?: Record<string, string | undefined>;
+  /**
+   * Action handlers to register at boot, keyed by namespace and action
+   * id. The bundled `mail.test` handler is registered automatically
+   * unless this object is provided.
+   */
+  actionHandlers?: Record<string, Record<string, import('./settings-service.types.js').SettingsActionHandler>>;
 }
 
 /**
@@ -46,7 +61,13 @@ export class SettingsServicePlugin implements Plugin {
   private service: SettingsService | null = null;
 
   constructor(opts: SettingsServicePluginOptions = {}) {
-    this.opts = opts;
+    this.opts = {
+      ...opts,
+      manifests: opts.manifests ?? builtinSettingsManifests,
+      actionHandlers: opts.actionHandlers ?? {
+        mail: { test: mailTestActionHandler },
+      },
+    };
   }
 
   async init(ctx: PluginContext): Promise<void> {
@@ -55,6 +76,11 @@ export class SettingsServicePlugin implements Plugin {
       env: this.opts.env,
     });
     for (const m of this.opts.manifests ?? []) this.service.registerManifest(m);
+    for (const [ns, handlers] of Object.entries(this.opts.actionHandlers ?? {})) {
+      for (const [id, fn] of Object.entries(handlers)) {
+        this.service.registerAction(ns, id, fn);
+      }
+    }
 
     ctx.registerService('settings', this.service);
     ctx.logger?.info?.(
@@ -84,21 +110,14 @@ export class SettingsServicePlugin implements Plugin {
         // ok — fall back to in-memory.
       }
       if (engine) {
-        // Stash the engine on the service via a thin re-init. The
-        // SettingsService keeps the engine ref private, so we
-        // construct a fresh instance preserving registered manifests +
-        // crypto + env.
-        const fresh = new SettingsService({
-          engine: engine as unknown as SettingsEngine,
-          crypto: this.opts.crypto,
-          env: this.opts.env,
-          audit: this.buildAuditSink(ctx, engine),
-        });
-        for (const m of this.opts.manifests ?? []) fresh.registerManifest(m);
-        // Re-register any manifests that were added between init and start.
-        for (const m of this.service!.listManifests()) fresh.registerManifest(m);
-        this.service = fresh;
-        ctx.registerService('settings', fresh);
+        // Late-bind the engine + audit sink on the existing service
+        // instance. We avoid re-registering the service because the
+        // kernel disallows `registerService` for an already-registered
+        // name.
+        this.service!.bindEngine(
+          engine as unknown as SettingsEngine,
+          this.buildAuditSink(ctx, engine),
+        );
       }
 
       if (this.opts.registerRoutes === false) return;

packages/services/service-settings/src/settings-service.ts

@@ -56,9 +56,9 @@ interface RegisteredManifest {
  * the supporting types and `README.md` for the high-level contract.
  */
 export class SettingsService {
-  private readonly engine?: SettingsEngine;
+  private engine?: SettingsEngine;
   private readonly crypto: CryptoAdapter;
-  private readonly audit?: SettingsAuditSink;
+  private audit?: SettingsAuditSink;
   private readonly env: Record<string, string | undefined>;
   private readonly objectName: string;
   private readonly registry = new Map<string, RegisteredManifest>();
@@ -73,6 +73,17 @@ export class SettingsService {
     this.objectName = opts.objectName ?? DEFAULT_OBJECT;
   }
 
+  /**
+   * Late-bind a data engine and (optionally) an audit sink. Plugins
+   * call this from `kernel:ready` once `objectql` is wired so the
+   * SettingsService swaps from its in-memory fallback to the real
+   * `sys_setting` table without re-registering the service.
+   */
+  bindEngine(engine: SettingsEngine, audit?: SettingsAuditSink): void {
+    this.engine = engine;
+    if (audit) this.audit = audit;
+  }
+
   // ---------------------------------------------------------------------
   // Manifest registry
   // ---------------------------------------------------------------------