Add global scope + reactive settings client

Introduce a platform-wide "global" settings scope and a Phase‑1 reactive settings client/events system. Changes:

- Add 'global' to specifier schema and update cascade order (env > global > tenant > user > default). Update sys-setting object to show Global option.
- Change mail manifest scope to 'global' and update tests to expect source='global'.
- Implement SettingsService change bus: subscribe/emitChange, createClient/snapshotOf reactive client, and fire settings:changed events on mutations. Adjust load/save to handle global rows and bypass tenant-audit where appropriate.
- Extend SettingsEngine types with bypassTenantAudit and updated insert/update/find signatures.
- Add settings-client Zod spec for the reactive client and change event contract.
- Add i18n support for source labels and resolveSettingsSourceLabel helper in i18n resolver; add translations for en / ja-JP / zh-CN.
- Wire EmailServicePlugin to bind to the 'mail' namespace, subscribe to changes, register a mail/test action, and apply live settings; add EmailService.setTransport and setDefaultFrom to support hot-swapping.
- Update and add tests covering global scope, change events, createClient behaviour and subscriber safety.

These changes enable platform-wide settings and allow services (e.g. email) to pick up admin UI updates without restart.

Author: hotlong

packages/platform-objects/src/system/sys-setting.object.ts

@@ -14,9 +14,10 @@ import { ObjectSchema, Field } from '@objectstack/spec/data';
  *
  * Resolution order (handled by `SettingsService.get`):
  *   1. process.env override                    (source='env',     locked=true)
- *   2. sys_setting WHERE scope='tenant'        (source='tenant')
- *   3. sys_setting WHERE scope='user'          (source='user')
- *   4. manifest specifier.default              (source='default')
+ *   2. sys_setting WHERE scope='global'        (source='global')
+ *   3. sys_setting WHERE scope='tenant'        (source='tenant')
+ *   4. sys_setting WHERE scope='user'          (source='user')
+ *   5. manifest specifier.default              (source='default')
  *
  * Encryption: rows with `encrypted=true` store ciphertext in `value_enc`
  * and leave `value` null. The plain value is never written to audit log
@@ -119,6 +120,7 @@ export const SysSetting = ObjectSchema.create({
 
     scope: Field.select(
       [
+        { label: 'Global', value: 'global' },
         { label: 'Tenant', value: 'tenant' },
         { label: 'User',   value: 'user' },
         { label: 'Runtime',value: 'runtime' },

packages/plugins/plugin-email/src/email-plugin.ts

@@ -125,6 +125,72 @@ export class EmailServicePlugin implements Plugin {
       catch { try { engine = ctx.getService<IDataEngine>('data'); } catch { /* ignore */ } }
       if (!engine || !this.service) return;
 
+      // ── Bind to the `mail` settings namespace (Phase 1) ──────────────
+      // Allows the admin UI to live-update SMTP/provider/from-address
+      // without restarting the process. Env-locked fields still win at
+      // the resolver level, so config-via-env keeps its precedence.
+      try {
+        const settings = ctx.getService<any>('settings');
+        if (settings && typeof settings.createClient === 'function') {
+          const applySettings = async () => {
+            try {
+              const payload = await settings.getNamespace('mail');
+              const values: Record<string, unknown> = {};
+              for (const [k, v] of Object.entries(payload.values as Record<string, any>)) {
+                values[k] = v?.value;
+              }
+              this.applyMailSettings(values, ctx);
+            } catch (err: any) {
+              ctx.logger.warn('EmailServicePlugin: failed to apply mail settings: ' + (err?.message ?? err));
+            }
+          };
+          await applySettings();
+          // Subscribe to namespace changes; rebuild on every update.
+          if (typeof settings.subscribe === 'function') {
+            settings.subscribe('mail', () => {
+              void applySettings();
+            });
+            ctx.logger.info('EmailServicePlugin: bound to settings:changed for namespace=mail');
+          }
+
+          // Register the `mail/test` action handler so saving + sending
+          // a test email actually exercises the live transport.
+          if (typeof settings.registerAction === 'function') {
+            const svc = this.service;
+            settings.registerAction('mail', 'test', async ({ values, ctx: actionCtx }: any) => {
+              const to = (actionCtx?.body?.to as string | undefined)
+                ?? (values.from_email as string | undefined);
+              if (!to) {
+                return { ok: false, severity: 'error', message: 'Provide a "to" address (or set from_email).' };
+              }
+              try {
+                const result = await svc.send({
+                  to,
+                  from: values.from_email ? {
+                    address: String(values.from_email),
+                    name: values.from_name ? String(values.from_name) : undefined,
+                  } : undefined,
+                  subject: 'ObjectStack mail test',
+                  text: 'This is a test email from the ObjectStack settings page.',
+                });
+                if (result.status === 'failed') {
+                  return { ok: false, severity: 'error', message: result.error ?? 'Send failed.' };
+                }
+                return {
+                  ok: true,
+                  severity: 'info',
+                  message: `Sent test email to ${to} (id=${result.id}).`,
+                };
+              } catch (err: any) {
+                return { ok: false, severity: 'error', message: err?.message ?? String(err) };
+              }
+            });
+          }
+        }
+      } catch {
+        // settings service not registered — env/constructor opts remain authoritative.
+      }
+
       const persistence: EmailPersistence | undefined = this.options.persist === false
         ? undefined
         : {
@@ -198,6 +264,62 @@ export class EmailServicePlugin implements Plugin {
     });
   }
 
+  /**
+   * Translate the `mail` settings namespace snapshot into a transport
+   * and `defaultFrom`, then hot-swap them on the running EmailService.
+   *
+   * Behaviour:
+   *  - `provider = 'log' | 'smtp'` keeps the LogTransport (real SMTP
+   *    delivery requires `@objectstack/plugin-mail-smtp`, which is not
+   *    a dependency of this package). The from-address is still applied.
+   *  - `provider = 'resend' | 'postmark'` rebuilds the transport using
+   *    `api_key` from settings. If `api_key` is missing the swap is
+   *    skipped and a warning is logged — the previous transport stays.
+   *
+   * Env-locked fields (handled in SettingsService.get) still resolve
+   * before this method ever sees them, so an env override transparently
+   * wins.
+   */
+  private applyMailSettings(values: Record<string, unknown>, ctx: PluginContext): void {
+    if (!this.service) return;
+
+    const fromEmail = typeof values.from_email === 'string' ? values.from_email : undefined;
+    const fromName = typeof values.from_name === 'string' ? values.from_name : undefined;
+    if (fromEmail) this.service.setDefaultFrom({ address: fromEmail, name: fromName });
+
+    const provider = String(values.provider ?? 'smtp');
+    if (provider === 'smtp' || provider === 'log') {
+      // No SMTP transport ships in core; settings-only edits become
+      // a no-op for transport but still apply `defaultFrom`. Users
+      // wanting real SMTP install `@objectstack/plugin-mail-smtp`
+      // and configure it via constructor opts.
+      ctx.logger.info(
+        `EmailServicePlugin: mail settings applied (provider=${provider}, from=${fromEmail ?? '∅'}); transport unchanged.`,
+      );
+      return;
+    }
+
+    const apiKey = typeof values.api_key === 'string' ? values.api_key : undefined;
+    if (!apiKey) {
+      ctx.logger.warn(
+        `EmailServicePlugin: provider='${provider}' selected but api_key is empty — transport NOT rebuilt.`,
+      );
+      return;
+    }
+
+    try {
+      const transport = makeTransport({
+        provider: provider as 'resend' | 'postmark',
+        apiKey,
+        logger: ctx.logger,
+      });
+      this.service.setTransport(transport);
+      ctx.logger.info(`EmailServicePlugin: transport rebuilt from settings (provider=${provider}).`);
+    } catch (err: any) {
+      ctx.logger.warn('EmailServicePlugin: failed to rebuild transport: ' + (err?.message ?? err));
+    }
+  }
+
   private async upsertTemplate(engine: IDataEngine, tpl: EmailTemplate): Promise<void> {
     const row = {
       name: tpl.name,

packages/plugins/plugin-email/src/email-service.ts

@@ -200,6 +200,21 @@ export class EmailService implements IEmailService {
     this.options.persistence = persistence;
   }
 
+  /**
+   * Hot-swap the underlying transport. Used by EmailServicePlugin when
+   * the `mail` settings namespace changes (e.g. SMTP host updated in
+   * the admin UI) so subsequent `send()` calls go through the new
+   * transport without restarting the process.
+   */
+  setTransport(transport: IEmailTransport): void {
+    this.options.transport = transport;
+  }
+
+  /** Replace the default `from` address used when callers omit `input.from`. */
+  setDefaultFrom(from: EmailAddress | undefined): void {
+    this.options.defaultFrom = from;
+  }
+
   async send(input: SendEmailInput): Promise<SendEmailResult> {
     let normalized: NormalizedEmailMessage;
     try {

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

@@ -14,7 +14,7 @@ const manifest = {
   label: 'Mail Delivery',
   icon: 'Mail',
   description: 'SMTP and transactional email provider configuration.',
-  scope: 'tenant',
+  scope: 'global',
   readPermission: 'setup.access',
   writePermission: 'setup.write',
   category: 'Communication',

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

@@ -90,7 +90,42 @@ describe('SettingsService — encryption round-trip', () => {
     await svc.setMany('mail', { provider: 'sendgrid', api_key: 'sg-secret-123', from_email: 'a@b.com' });
     const ns = await svc.getNamespace('mail');
     expect(ns.values.api_key.value).toBe('sg-secret-123');
-    expect(ns.values.api_key.source).toBe('tenant');
+    expect(ns.values.api_key.source).toBe('global');
+  });
+});
+
+describe('SettingsService — global scope', () => {
+  it('mail manifest defaults to global scope', () => {
+    expect(mailSettingsManifest.scope).toBe('global');
+  });
+
+  it('returns source="global" for platform-wide values', async () => {
+    const svc = new SettingsService({ env: {} });
+    svc.registerManifest(mailSettingsManifest);
+    await svc.setMany('mail', { provider: 'smtp', from_email: 'ops@example.com' });
+    const r = await svc.get('mail', 'from_email');
+    expect(r.source).toBe('global');
+    expect(r.value).toBe('ops@example.com');
+    expect(r.locked).toBe(false);
+  });
+
+  it('global value is visible from any user context (no per-user isolation)', async () => {
+    const svc = new SettingsService({ env: {} });
+    svc.registerManifest(mailSettingsManifest);
+    await svc.setMany('mail', { provider: 'smtp', from_email: 'ops@example.com' }, { userId: 'u1' });
+    const fromU2 = await svc.get('mail', 'from_email', { userId: 'u2' });
+    expect(fromU2.source).toBe('global');
+    expect(fromU2.value).toBe('ops@example.com');
+  });
+
+  it('env still wins over global', async () => {
+    const svc = new SettingsService({ env: { MAIL_FROM_EMAIL: 'env@example.com' } });
+    svc.registerManifest(mailSettingsManifest);
+    await svc.set('mail', 'from_email', 'global@example.com').catch(() => {});
+    const r = await svc.get('mail', 'from_email');
+    expect(r.source).toBe('env');
+    expect(r.value).toBe('env@example.com');
+    expect(r.locked).toBe(true);
   });
 });
 
@@ -178,3 +213,81 @@ describe('SettingsService — user-scoped values', () => {
     expect((await svc.get('prefs', 'nick', { userId: 'u3' })).value).toBe('anon');
   });
 });
+
+describe('SettingsService — Phase 1 change events + client', () => {
+  it('fires settings:changed on set with namespace, key, scope, action', async () => {
+    const svc = new SettingsService({ env: {} });
+    svc.registerManifest(mailSettingsManifest);
+    const events: any[] = [];
+    const off = svc.subscribe('mail', (e) => events.push(e));
+
+    await svc.set('mail', 'from_email', 'a@b.c');
+    await svc.set('mail', 'from_email', null);
+
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({ namespace: 'mail', key: 'from_email', scope: 'global', action: 'set' });
+    expect(events[1]).toMatchObject({ namespace: 'mail', key: 'from_email', scope: 'global', action: 'reset' });
+    expect(typeof events[0].at).toBe('string');
+
+    off();
+    await svc.set('mail', 'from_email', 'x@y.z');
+    expect(events).toHaveLength(2);
+  });
+
+  it('filters subscribers by namespace', async () => {
+    const svc = new SettingsService({ env: {} });
+    svc.registerManifest(mailSettingsManifest);
+    svc.registerManifest(brandingSettingsManifest);
+    const mailEvents: any[] = [];
+    const allEvents: any[] = [];
+    svc.subscribe('mail', (e) => mailEvents.push(e));
+    svc.subscribe(undefined, (e) => allEvents.push(e));
+
+    await svc.set('mail', 'from_email', 'a@b.c');
+    await svc.set('branding', 'workspace_name', 'X');
+
+    expect(mailEvents).toHaveLength(1);
+    expect(allEvents).toHaveLength(2);
+  });
+
+  it('createClient exposes reactive snapshot that refreshes after set', async () => {
+    const svc = new SettingsService({ env: {} });
+    svc.registerManifest(mailSettingsManifest);
+    await svc.set('mail', 'from_email', 'initial@x.y');
+
+    const client = await svc.createClient<{ from_email?: string; provider?: string }>('mail');
+    expect(client.current.from_email).toBe('initial@x.y');
+    expect(client.get('provider')).toBe('smtp');
+
+    await svc.set('mail', 'from_email', 'updated@x.y');
+    // Allow microtask drain so the subscriber callback completes.
+    await new Promise((r) => setImmediate(r));
+    expect(client.current.from_email).toBe('updated@x.y');
+
+    client.dispose();
+  });
+
+  it('createClient honours an explicit parser', async () => {
+    const svc = new SettingsService({ env: {} });
+    svc.registerManifest(mailSettingsManifest);
+    await svc.set('mail', 'smtp_port', 2525);
+
+    const client = await svc.createClient<{ smtp_port: number; provider: string }>('mail', {
+      parse: (raw) => ({
+        smtp_port: Number(raw.smtp_port ?? 0),
+        provider: String(raw.provider ?? 'smtp'),
+      }),
+    });
+    expect(client.current).toEqual({ smtp_port: 2525, provider: 'smtp' });
+  });
+
+  it('handler exceptions do not break the writer', async () => {
+    const svc = new SettingsService({ env: {} });
+    svc.registerManifest(mailSettingsManifest);
+    svc.subscribe('mail', () => {
+      throw new Error('listener boom');
+    });
+    // Must not throw despite the bad listener.
+    await expect(svc.set('mail', 'from_email', 'ok@x.y')).resolves.toBeDefined();
+  });
+});