Auto-mount default per-project plugins and add publish API

Introduce a default capability slate (queue, job, cache, settings, email, storage) that the CLI auto-injects for non-minimal presets and that hosted per-project kernels mount via a new mountDefaultProjectPlugins helper. Wire the helper into ArtifactKernelFactory and DefaultProjectKernelFactory (with an ops override hook basePluginsExtra), add local-storage fallback + prod warning behavior, and export types from service-cloud. Add cloud package publish endpoints (POST /cloud/packages and POST /cloud/packages/:id/versions) to register packages and publish versions (including optional auto-install), plus snapshot/checksum helpers. Update docs and examples to document the always-on slate and storage behavior, add unit tests for the CLI ALWAYS_ON_CAPABILITIES and the default-project plugin mounting, and bump service-cloud package deps / pnpm lockfile accordingly.

Author: hotlong

apps/objectos/README.md

@@ -422,3 +422,54 @@ Required runtime env vars (set as Cloudflare secrets, not in `wrangler.toml`):
 | `OS_DATABASE_AUTH_TOKEN` | Turso auth token. |
 | `AUTH_SECRET` | Cookie/session signing secret. |
 | `OS_CLOUD_URL` *(optional)* | Point at an `apps/cloud` deployment for multi-project mode. Omit for single-project local mode. |
+
+## Default per-project plugin slate
+
+ObjectOS keeps the **host kernel intentionally bare** (stateless
+routing shell). All tenant-data plugins live on **per-project kernels**,
+mounted on first-hit and cached by `ArtifactKernelFactory` /
+`DefaultProjectKernelFactory`.
+
+Every per-project kernel automatically gets the following default
+plugins (in this order) via `mountDefaultProjectPlugins()`:
+
+1. `QueueServicePlugin` (in-memory)
+2. `JobServicePlugin`
+3. `CacheServicePlugin` (in-memory)
+4. `SettingsServicePlugin` — `sys_setting` / `sys_secret` /
+   `sys_setting_audit` rows live in the **project's own driver**, so
+   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
+
+### Storage adapter selection
+
+- `OS_STORAGE_ADAPTER=s3` + `OS_S3_*` env → shared S3 bucket with
+  `pathStylePrefix: projects/<projectId>` so tenant prefixes never
+  collide
+- otherwise → local driver under
+  `<dataRoot>/projects/<projectId>/uploads/`; a single boot warning
+  fires in non-dev mode
+
+### Ops overrides
+
+The factory accepts `basePluginsExtra({ projectId, kernel })` which can
+return `{ caps?: {…: false}, extraPlugins?: [...] }` to:
+
+- inject a **shared Redis-backed queue** so retries survive kernel
+  eviction (set `caps.queue=false` and push your custom plugin in
+  `extraPlugins`)
+- skip storage when the host worker mounts a shared S3 instance
+  out-of-band
+- mount tenant-specific audit/automation/analytics plugins
+
+### Caveats
+
+- **In-memory queue eviction** — when a per-project kernel is LRU-
+  evicted, queued retries are dropped. Use the `basePluginsExtra`
+  hook above to inject a Redis-backed queue for SLA-bound workloads.
+- **InMemoryCryptoProvider is per-process** — the default AES key is
+  regenerated on every restart, so encrypted `sys_secret` rows cannot
+  be decrypted after a redeploy. Ship `KmsCryptoProvider` (AWS KMS
+  envelope) before enabling encrypted settings on hosted objectos.

examples/app-crm/objectstack.config.ts

@@ -48,7 +48,12 @@ 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', 'settings'],
+  // Note: the foundational slate (queue, job, cache, settings, email,
+  // storage) is auto-injected by the CLI for every non-`minimal`
+  // preset — see `ALWAYS_CAPS` in packages/cli/src/commands/serve.ts.
+  // Listed below only the *opt-in* capabilities this stack actually
+  // wants on top of that slate.
+  requires: ['ai', 'automation', 'analytics', 'auth', 'ui', 'approvals', 'sharing'],
 
   objects: Object.values(objects),
   actions: Object.values(actions),

packages/cli/README.md

@@ -254,6 +254,31 @@ os projects bind <id> --artifact dist/objectstack.json  # 8. Bind to a Cloud Pro
 └── package.json                # oclif config under "oclif" key
 ```
 
+
+## Default capability slate (always-on)
+
+`objectstack serve` (and `os dev`) auto-mount a baseline slate of
+service plugins for every preset **except** `--preset minimal`:
+
+| Capability  | Plugin                       | Why default                                                  |
+|-------------|------------------------------|--------------------------------------------------------------|
+| `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.                 |
+| `email`     | `EmailServicePlugin`         | Auth callbacks (verify, reset, magic-link) hard-depend.      |
+| `storage`   | `StorageServicePlugin`       | Avatars, attachments, exports. Local fallback in dev.        |
+
+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`.
+
+**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.
+
 ## License
 
 Apache-2.0

packages/cli/src/commands/serve.ts

@@ -86,6 +86,22 @@ export default class Serve extends Command {
     }),
   };
 
+  /**
+   * Capabilities auto-added to every app's `requires` for every preset
+   * EXCEPT `minimal`. These form the foundation that every server-side
+   * runtime expects to exist (background work, settings persistence,
+   * transactional mail, file uploads). Apps may still list these in
+   * `requires:` explicitly — duplicates are de-duped.
+   *
+   * Opt out: `objectstack serve --preset minimal`.
+   *
+   * Mirrored on hosted objectos per-project kernels by
+   * `mountDefaultProjectPlugins()` in `@objectstack/service-cloud`.
+   */
+  static readonly ALWAYS_ON_CAPABILITIES: readonly string[] = Object.freeze([
+    'queue', 'job', 'cache', 'settings', 'email', 'storage',
+  ]);
+
   /**
    * Auto-registered plugin tiers. Plugins explicitly listed in
    * `config.plugins` are always loaded — tiers only gate the optional
@@ -306,7 +322,7 @@ export default class Serve extends Command {
       // storage). Opt out with `objectstack serve --preset minimal`.
       // Keeping `auth → email` above as a defensive rule for users who
       // explicitly opt into `minimal` but still enable auth.
-      const ALWAYS_CAPS = ['queue', 'job', 'cache', 'settings', 'email', 'storage'];
+      const ALWAYS_CAPS = Serve.ALWAYS_ON_CAPABILITIES;
       if (presetName !== 'minimal') {
         for (const cap of ALWAYS_CAPS) {
           if (!requires.includes(cap)) requires.push(cap);
@@ -1077,6 +1093,26 @@ export default class Serve extends Command {
               ));
               arg.provider = 'log';
             }
+          } else if (cap === 'storage') {
+            // Storage is now in the default capability slate. If the host
+            // hasn't configured a backend explicitly we fall back to the
+            // local-disk driver under `.objectstack/data/uploads/` so
+            // avatars / attachments / report files work out of the box.
+            // In production mode we emit a single loud warning so the
+            // operator knows to point storage at S3 / GCS / Azure before
+            // shipping (data on a single pod is volatile / non-replicated).
+            const cfgStorage = (config as any).storage;
+            if (cfgStorage && (cfgStorage.driver || cfgStorage.adapter)) {
+              arg = cfgStorage;
+            } else {
+              const root = process.env.OS_STORAGE_ROOT || '.objectstack/data/uploads';
+              arg = { driver: 'local', root };
+              if (!isDev) {
+                console.warn(chalk.yellow(
+                  `  ⚠ StorageServicePlugin using local driver (${root}) — switch to S3/GCS/Azure for production (set config.storage or OS_STORAGE_*).`,
+                ));
+              }
+            }
           }
           await kernel.use(arg !== undefined ? new Ctor(arg) : new Ctor());
           trackPlugin(spec.export);

packages/cli/test/serve-defaults.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import Serve from '../src/commands/serve.js';
+
+describe('serve: ALWAYS_ON_CAPABILITIES default slate', () => {
+  it('exposes the six foundational capabilities in stable order', () => {
+    expect(Serve.ALWAYS_ON_CAPABILITIES).toEqual([
+      'queue', 'job', 'cache', 'settings', 'email', 'storage',
+    ]);
+  });
+
+  it('is frozen so accidental mutation throws', () => {
+    expect(Object.isFrozen(Serve.ALWAYS_ON_CAPABILITIES)).toBe(true);
+  });
+
+  it('minimal preset has none of the always-on caps in its tier list', () => {
+    const minimal = Serve.TIER_PRESETS.minimal;
+    for (const cap of Serve.ALWAYS_ON_CAPABILITIES) {
+      expect(minimal).not.toContain(cap);
+    }
+    expect(minimal).toEqual(['core']);
+  });
+
+  it('default preset does not pre-include the always-on caps (they merge into `requires`, not tier)', () => {
+    // ALWAYS_CAPS get injected into per-app `requires` at runtime; the
+    // tier preset is the orthogonal "feature tier" axis.
+    const def = Serve.TIER_PRESETS.default;
+    for (const cap of Serve.ALWAYS_ON_CAPABILITIES) {
+      expect(def).not.toContain(cap);
+    }
+  });
+});

packages/services/service-cloud/package.json

@@ -32,10 +32,15 @@
     "@objectstack/objectql": "workspace:^",
     "@objectstack/plugin-audit": "workspace:^",
     "@objectstack/plugin-auth": "workspace:^",
+    "@objectstack/plugin-email": "workspace:^",
     "@objectstack/plugin-security": "workspace:^",
     "@objectstack/runtime": "workspace:^",
+    "@objectstack/service-cache": "workspace:^",
     "@objectstack/service-i18n": "workspace:^",
+    "@objectstack/service-job": "workspace:^",
     "@objectstack/service-package": "workspace:^",
+    "@objectstack/service-queue": "workspace:^",
+    "@objectstack/service-settings": "workspace:^",
     "@objectstack/service-storage": "workspace:*",
     "@objectstack/service-tenant": "workspace:^",
     "@objectstack/spec": "workspace:^",

packages/services/service-cloud/src/artifact-kernel-factory.ts

@@ -33,6 +33,7 @@ import { DriverPlugin, AppPlugin } from '@objectstack/runtime';
 import type { ProjectKernelFactory } from './kernel-manager.js';
 import type { EnvironmentDriverRegistry } from './environment-registry.js';
 import type { ArtifactApiClient } from './artifact-api-client.js';
+import { mountDefaultProjectPlugins } from './default-project-plugins.js';
 
 type IDataDriver = Contracts.IDataDriver;
 
@@ -183,6 +184,16 @@ export class ArtifactKernelFactory implements ProjectKernelFactory {
             });
         }
 
+        // Mount the default per-project plugin slate (queue, job, cache,
+        // settings, email, storage). Mirrors `ALWAYS_CAPS` in
+        // `packages/cli/src/commands/serve.ts` so hosted tenants get the
+        // same foundational services a single-tenant `objectstack dev`
+        // stack gets.
+        await mountDefaultProjectPlugins(kernel, {
+            projectId,
+            logger: this.logger,
+        });
+
         const projectName = project.hostname ?? projectId;
         const bundle = artifact.metadata as any;
         const sys = bundle?.manifest ?? bundle;

packages/services/service-cloud/src/cloud-artifact-api-plugin.ts

@@ -16,6 +16,8 @@
  *   GET  /cloud/projects/:id/revisions
  *   POST /cloud/projects/:id/revisions/:commit/activate
  *   POST /cloud/projects/:id/revisions/prune
+ *   POST /cloud/packages                      — register/upsert a package (ADR-0006 v4 Phase B)
+ *   POST /cloud/packages/:id/versions         — publish a new package version (ADR-0006 v4 Phase B)
  *   GET  /pub/v1/projects/:id/manifest.json
  *   GET  /pub/v1/projects/:id/artifact[?commit=&redirect=]
  *   GET  /pub/v1/projects/:id/revisions
@@ -28,6 +30,7 @@ import { registerPublicRoutes } from './routes/public.js';
 import { registerBranchRoutes } from './routes/branches.js';
 import { registerProjectLifecycleRoutes } from './routes/project-lifecycle.js';
 import { registerPackageInstallRoutes } from './routes/package-install.js';
+import { registerPackagePublishRoutes } from './routes/package-publish.js';
 import type { ProjectTemplate } from './multi-project-plugin.js';
 import type { RouteDeps } from './routes/types.js';
 
@@ -118,6 +121,7 @@ export function createCloudArtifactApiPlugin(options: CloudArtifactApiPluginOpti
             registerBranchRoutes(server, deps);
             registerProjectLifecycleRoutes(server, { ...deps, templates: options.templates });
             registerPackageInstallRoutes(server, { ...deps, templates: options.templates });
+            registerPackagePublishRoutes(server, { ...deps, templates: options.templates });
         },
         stop: async (_ctx: AnyContext) => {},
     };