Add swappable storage, settings UI, and tests

Introduce a swappable storage proxy and settings-driven live configuration: adds SwappableStorageService (proxy that can swap inner adapter), wiring in StorageServicePlugin to bind to the `storage` Settings namespace and rebuild the adapter on changes (with a logged warning that files are not migrated). Adds a storage.manifest (with a fallback storage/test action handler exported from service-settings) and translations (en, ja-JP, zh-CN), plus manifest/unit tests. Storage plugin now registers a live storage/test probe action that uploads → downloads → deletes a probe blob to validate configs; exposes bindToSettings option to disable live binding for tests. Also updated exports, README docs (apps/objectos, cli, service-storage) to document UI-driven configuration and migration caveats. Includes unit/integration tests for the plugin and swappable proxy and various implementation fixes when building adapters from settings.

Author: hotlong

apps/objectos/README.md

@@ -441,16 +441,26 @@ plugins (in this order) via `mountDefaultProjectPlugins()`:
    tenants are fully isolated
 5. `EmailServicePlugin` — each tenant configures its own provider /
    api_key via Settings; api_key is stored encrypted in `sys_secret`
-6. `StorageServicePlugin` — see below
+6. `StorageServicePlugin` — see below. Adapter + credentials are
+   live-configurable per tenant via the `storage` Settings namespace;
+   the plugin swaps the inner adapter on every change.
 
 ### Storage adapter selection
 
 - `OS_STORAGE_ADAPTER=s3` + `OS_S3_*` env → shared S3 bucket with
   `pathStylePrefix: projects/<projectId>` so tenant prefixes never
-  collide
+  collide. Per-project Settings can still override the bucket /
+  credentials at runtime.
 - otherwise → local driver under
   `<dataRoot>/projects/<projectId>/uploads/`; a single boot warning
-  fires in non-dev mode
+  fires in non-dev mode.
+
+Tenant admins can switch adapter from the Settings hub
+(`namespace=storage`) — the `SwappableStorageService` proxy rebuilds
+the inner adapter without restarting the kernel. ⚠ Existing files are
+**not** migrated; a warning is logged on every swap. The
+`storage/test` action uploads → reads → deletes a probe blob to
+validate the new configuration before users start uploading.
 
 ### Ops overrides
 

packages/cli/README.md

@@ -265,7 +265,7 @@ service plugins for every preset **except** `--preset minimal`:
 | `queue`     | `QueueServicePlugin`         | Background retries (mail, audit batching) need a queue.      |
 | `job`       | `JobServicePlugin`           | Scheduled jobs (cleanup, reports, cron).                     |
 | `cache`     | `CacheServicePlugin`         | In-memory adapter; performance baseline.                     |
-| `settings`  | `SettingsServicePlugin`      | Mail/branding/feature-flag UI + persistence.                 |
+| `settings`  | `SettingsServicePlugin`      | Mail / storage / branding / feature-flag UI + persistence.   |
 | `email`     | `EmailServicePlugin`         | Auth callbacks (verify, reset, magic-link) hard-depend.      |
 | `storage`   | `StorageServicePlugin`       | Avatars, attachments, exports. Local fallback in dev.        |
 
@@ -274,10 +274,17 @@ Apps no longer need to list these in `requires: [...]`.
 **Opt-out:** run `objectstack serve --preset minimal` to skip the slate
 and only load core + your explicit `requires`.
 
+**Built-in Settings manifests:** `mail`, `storage`, `branding`,
+`feature_flags` are pre-registered. Both `mail` and `storage` expose a
+"Test connection" action that exercises the live transport / adapter
+end-to-end. Switching the storage adapter does **not** migrate
+previously uploaded files — the plugin logs a warning on every swap.
+
 **Storage warning:** when no `storage:` block is configured the plugin
 falls back to the local driver under `.objectstack/data/uploads/`. In
 non-dev mode a single `console.warn` fires at boot — switch to S3/GCS/
-Azure for production by setting `config.storage` or `OS_STORAGE_*` env.
+Azure for production by setting `config.storage`, `OS_STORAGE_*` env,
+or via the Settings hub (`namespace=storage`).
 
 ## License
 

packages/services/service-settings/README.md

@@ -52,5 +52,11 @@ per-project kernel on hosted objectos. Apps no longer need to declare
 no runtime cost (the registry is empty, no routes fire).
 
 The Settings hub in `apps/console` therefore appears in every app, and
-the **Mail Settings** card is the first manifest registered (by
-`EmailServicePlugin`, also always-on).
+the following built-in manifests are pre-registered out of the box:
+
+| Namespace      | Owner plugin                | Highlights                                  |
+|----------------|-----------------------------|---------------------------------------------|
+| `mail`         | `EmailServicePlugin`        | SMTP / Resend / Postmark + `mail/test`      |
+| `storage`      | `StorageServicePlugin`      | Local FS / S3 + encrypted secret + `storage/test` |
+| `branding`     | (built-in fallback)         | Workspace name, logo, accent colour         |
+| `feature_flags`| (built-in fallback)         | Opt-in experimental features                |

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

@@ -46,6 +46,8 @@ export {
   featureFlagsSettingsManifest,
   mailSettingsManifest,
   mailTestActionHandler,
+  storageSettingsManifest,
+  storageTestActionHandler,
 } from './manifests/index.js';
 
 // Re-export the spec types for convenience so plugin authors only need

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

@@ -4,14 +4,17 @@
 export { mailSettingsManifest, mailTestActionHandler } from './mail.manifest.js';
 export { brandingSettingsManifest } from './branding.manifest.js';
 export { featureFlagsSettingsManifest } from './feature-flags.manifest.js';
+export { storageSettingsManifest, storageTestActionHandler } from './storage.manifest.js';
 
 import { mailSettingsManifest } from './mail.manifest.js';
 import { brandingSettingsManifest } from './branding.manifest.js';
 import { featureFlagsSettingsManifest } from './feature-flags.manifest.js';
+import { storageSettingsManifest } from './storage.manifest.js';
 
 /** Convenience aggregate — pass to `SettingsServicePlugin({ manifests })`. */
 export const builtinSettingsManifests = [
   brandingSettingsManifest,
   mailSettingsManifest,
+  storageSettingsManifest,
   featureFlagsSettingsManifest,
 ];

packages/services/service-settings/src/manifests/storage.manifest.test.ts

@@ -0,0 +1,90 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { SettingsManifestSchema } from '@objectstack/spec/system';
+import { storageSettingsManifest, storageTestActionHandler } from './storage.manifest';
+
+describe('storageSettingsManifest', () => {
+  it('parses against SettingsManifestSchema', () => {
+    expect(() => SettingsManifestSchema.parse(storageSettingsManifest)).not.toThrow();
+  });
+
+  it('declares namespace=storage, scope=global, version=1', () => {
+    const parsed = SettingsManifestSchema.parse(storageSettingsManifest);
+    expect(parsed.namespace).toBe('storage');
+    expect(parsed.scope).toBe('global');
+    expect(parsed.version).toBe(1);
+  });
+
+  it('marks s3_secret_access_key as encrypted', () => {
+    const sk = (storageSettingsManifest.specifiers as any[]).find(
+      (s) => s.key === 's3_secret_access_key',
+    );
+    expect(sk).toBeDefined();
+    expect(sk.encrypted).toBe(true);
+    expect(sk.type).toBe('password');
+  });
+
+  it('exposes a test action that POSTs to /api/settings/storage/test', () => {
+    const test = (storageSettingsManifest.specifiers as any[]).find(
+      (s) => s.type === 'action_button' && s.id === 'test',
+    );
+    expect(test).toBeDefined();
+    expect(test.handler).toMatchObject({
+      kind: 'http',
+      method: 'POST',
+      url: '/api/settings/storage/test',
+    });
+  });
+
+  it('hides S3 fields when adapter=local and vice-versa via visible expressions', () => {
+    const specs = storageSettingsManifest.specifiers as any[];
+    const s3Fields = ['s3_bucket', 's3_region', 's3_access_key_id', 's3_secret_access_key'];
+    for (const key of s3Fields) {
+      const spec = specs.find((s) => s.key === key);
+      expect(spec).toBeDefined();
+      expect(spec.visible).toBe("${data.adapter === 's3'}");
+    }
+    const localRoot = specs.find((s) => s.key === 'local_root');
+    expect(localRoot.visible).toBe("${data.adapter === 'local'}");
+  });
+});
+
+describe('storageTestActionHandler (fallback)', () => {
+  it('rejects local adapter without local_root', async () => {
+    const r = await storageTestActionHandler({ values: { adapter: 'local' }, ctx: {} as any });
+    expect(r.ok).toBe(false);
+    expect(r.severity).toBe('error');
+  });
+
+  it('accepts local adapter when local_root is set', async () => {
+    const r = await storageTestActionHandler({
+      values: { adapter: 'local', local_root: './uploads' },
+      ctx: {} as any,
+    });
+    expect(r.ok).toBe(true);
+  });
+
+  it('rejects s3 adapter when credentials are missing', async () => {
+    const r = await storageTestActionHandler({
+      values: { adapter: 's3', s3_bucket: 'x' },
+      ctx: {} as any,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.message).toMatch(/s3_region|s3_access_key_id|s3_secret_access_key/);
+  });
+
+  it('accepts a fully-specified s3 config', async () => {
+    const r = await storageTestActionHandler({
+      values: {
+        adapter: 's3',
+        s3_bucket: 'b',
+        s3_region: 'us-east-1',
+        s3_access_key_id: 'A',
+        s3_secret_access_key: 'S',
+      },
+      ctx: {} as any,
+    });
+    expect(r.ok).toBe(true);
+  });
+});

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

@@ -0,0 +1,118 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SettingsManifest } from '@objectstack/spec/system';
+import type { SettingsActionHandler } from '../settings-service.types.js';
+
+// Mirrors the shape of `mail.manifest.ts`. The actual adapter rebuild
+// + `storage/test` probe live in `@objectstack/service-storage`; this
+// manifest only declares the form + acts as a safe fallback when the
+// storage plugin is not present.
+const manifest = {
+  namespace: 'storage',
+  version: 1,
+  label: 'File Storage',
+  icon: 'HardDrive',
+  description:
+    'Backend used for attachments, exports, and user uploads. ' +
+    '⚠ Switching adapter does not migrate existing files — files ' +
+    'uploaded under the previous adapter become unreachable through ' +
+    'the new one.',
+  scope: 'global',
+  readPermission: 'setup.access',
+  writePermission: 'setup.write',
+  category: 'Infrastructure',
+  order: 20,
+  specifiers: [
+    { type: 'group', id: 'adapter', label: 'Backend', required: false,
+      description: 'Choose where uploaded files are stored.' },
+    { type: 'select', key: 'adapter', label: 'Adapter', required: true, default: 'local',
+      options: [
+        { value: 'local', label: 'Local filesystem' },
+        { value: 's3', label: 'S3 / S3-compatible' },
+      ],
+    },
+
+    { type: 'group', id: 'local', label: 'Local', required: false,
+      visible: "${data.adapter === 'local'}" },
+    { type: 'text', key: 'local_root', label: 'Root directory', required: false,
+      default: './.objectstack/data/uploads',
+      description: 'Filesystem path under which files are stored. Relative paths resolve from the server CWD.',
+      visible: "${data.adapter === 'local'}" },
+
+    { type: 'group', id: 's3', label: 'S3', required: false,
+      visible: "${data.adapter === 's3'}" },
+    { type: 'text', key: 's3_bucket', label: 'Bucket', required: true,
+      description: 'Shared host bucket. Per-project files are namespaced via the projects/<projectId>/ prefix.',
+      visible: "${data.adapter === 's3'}" },
+    { type: 'text', key: 's3_region', label: 'Region', required: true,
+      description: 'Example: us-east-1',
+      visible: "${data.adapter === 's3'}" },
+    { type: 'text', key: 's3_endpoint', label: 'Endpoint', required: false,
+      description: 'Custom endpoint for S3-compatible providers (R2, MinIO, Wasabi). Leave blank for AWS S3.',
+      visible: "${data.adapter === 's3'}" },
+    { type: 'text', key: 's3_access_key_id', label: 'Access key ID', required: true,
+      visible: "${data.adapter === 's3'}" },
+    { type: 'password', key: 's3_secret_access_key', label: 'Secret access key',
+      required: true, encrypted: true,
+      visible: "${data.adapter === 's3'}" },
+    { type: 'toggle', key: 's3_force_path_style', label: 'Force path-style URLs',
+      required: false, default: false,
+      description: 'Enable for MinIO and most S3-compatible providers; disable for AWS S3.',
+      visible: "${data.adapter === 's3'}" },
+
+    { type: 'group', id: 'limits', label: 'Limits', required: false },
+    { type: 'number', key: 'presigned_ttl', label: 'Presigned URL TTL (seconds)',
+      required: false, default: 3600, min: 60, max: 604800 },
+    { type: 'number', key: 'session_ttl', label: 'Upload session TTL (seconds)',
+      required: false, default: 86400, min: 300, max: 604800,
+      description: 'How long a chunked-upload session stays resumable.' },
+    { type: 'number', key: 'max_upload_mb', label: 'Max upload size (MB)',
+      required: false, default: 100, min: 1, max: 10240 },
+
+    { type: 'action_button', id: 'test', label: 'Test connection',
+      required: false, icon: 'Plug',
+      handler: { kind: 'http', method: 'POST', url: '/api/settings/storage/test' } },
+  ],
+};
+
+/** File Storage — local FS / S3-compatible backend configuration. */
+export const storageSettingsManifest = manifest as unknown as SettingsManifest;
+
+/**
+ * Built-in fallback action handler for `storage/test`. The real
+ * implementation lives in `@objectstack/service-storage` and is
+ * registered by `StorageServicePlugin` on `kernel:ready` (it overrides
+ * this stub via `registerAction`). This fallback only validates the
+ * form so the button is still useful when the storage plugin is
+ * absent (e.g. in a unit-test kernel that mounts settings only).
+ */
+export const storageTestActionHandler: SettingsActionHandler = async ({ values }) => {
+  const adapter = String(values.adapter ?? 'local');
+  if (adapter === 'local') {
+    const root = values.local_root as string | undefined;
+    if (!root) {
+      return { ok: false, severity: 'error', message: 'Configure a root directory before testing.' };
+    }
+    return {
+      ok: true,
+      severity: 'info',
+      message: `Local adapter configured (root=${root}). Mount @objectstack/service-storage to exercise live I/O.`,
+    };
+  }
+  if (adapter === 's3') {
+    const missing: string[] = [];
+    if (!values.s3_bucket) missing.push('s3_bucket');
+    if (!values.s3_region) missing.push('s3_region');
+    if (!values.s3_access_key_id) missing.push('s3_access_key_id');
+    if (!values.s3_secret_access_key) missing.push('s3_secret_access_key');
+    if (missing.length) {
+      return { ok: false, severity: 'error', message: `Missing required field${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}` };
+    }
+    return {
+      ok: true,
+      severity: 'info',
+      message: `S3 adapter configured (bucket=${values.s3_bucket}, region=${values.s3_region}). Mount @objectstack/service-storage to exercise live I/O.`,
+    };
+  }
+  return { ok: false, severity: 'error', message: `Unknown adapter: ${adapter}` };
+};

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

@@ -18,6 +18,7 @@ import {
 import {
   builtinSettingsManifests,
   mailTestActionHandler,
+  storageTestActionHandler,
 } from './manifests/index.js';
 import { settingsBuiltinTranslations } from './translations/index.js';
 
@@ -78,6 +79,7 @@ export class SettingsServicePlugin implements Plugin {
       manifests: opts.manifests ?? builtinSettingsManifests,
       actionHandlers: opts.actionHandlers ?? {
         mail: { test: mailTestActionHandler },
+        storage: { test: storageTestActionHandler },
       },
     };
   }

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

@@ -5,7 +5,7 @@ import type { TranslationData } from '@objectstack/spec/system';
 /**
  * English (en) — built-in settings manifest translations.
  *
- * Mirrors literals in `manifests/{mail,branding,feature-flags}.manifest.ts`.
+ * Mirrors literals in `manifests/{mail,branding,feature-flags,storage}.manifest.ts`.
  * Keeping them explicit here lets the resolver chain (locale → fallback → literal)
  * always have at least an English entry to fall back to.
  */
@@ -89,5 +89,44 @@ export const en: TranslationData = {
         inline_comments: { label: 'Inline comments' },
       },
     },
+
+    storage: {
+      title: 'File Storage',
+      description:
+        'Backend used for attachments, exports, and user uploads. ' +
+        '⚠ Switching adapter does not migrate existing files — files ' +
+        'uploaded under the previous adapter become unreachable through ' +
+        'the new one.',
+      groups: {
+        adapter: { title: 'Backend', description: 'Choose where uploaded files are stored.' },
+        local: { title: 'Local' },
+        s3: { title: 'S3' },
+        limits: { title: 'Limits' },
+      },
+      keys: {
+        adapter: {
+          label: 'Adapter',
+          options: { local: 'Local filesystem', s3: 'S3 / S3-compatible' },
+        },
+        local_root: { label: 'Root directory',
+          help: 'Filesystem path under which files are stored. Relative paths resolve from the server CWD.' },
+        s3_bucket: { label: 'Bucket',
+          help: 'Shared host bucket. Per-project files are namespaced via the projects/<projectId>/ prefix.' },
+        s3_region: { label: 'Region', help: 'Example: us-east-1' },
+        s3_endpoint: { label: 'Endpoint',
+          help: 'Custom endpoint for S3-compatible providers (R2, MinIO, Wasabi). Leave blank for AWS S3.' },
+        s3_access_key_id: { label: 'Access key ID' },
+        s3_secret_access_key: { label: 'Secret access key' },
+        s3_force_path_style: { label: 'Force path-style URLs',
+          help: 'Enable for MinIO and most S3-compatible providers; disable for AWS S3.' },
+        presigned_ttl: { label: 'Presigned URL TTL (seconds)' },
+        session_ttl: { label: 'Upload session TTL (seconds)',
+          help: 'How long a chunked-upload session stays resumable.' },
+        max_upload_mb: { label: 'Max upload size (MB)' },
+      },
+      actions: {
+        test: { label: 'Test connection' },
+      },
+    },
   },
 };