diff --git a/.changeset/v11-remove-driverinterface-alias.md b/.changeset/v11-remove-driverinterface-alias.md index 6a68b0701b..52d0ebc982 100644 --- a/.changeset/v11-remove-driverinterface-alias.md +++ b/.changeset/v11-remove-driverinterface-alias.md @@ -1,7 +1,7 @@ --- -"@objectstack/spec": major -"@objectstack/core": major -"@objectstack/objectql": major +"@objectstack/spec": minor +"@objectstack/core": minor +"@objectstack/objectql": minor --- Remove the deprecated `DriverInterface` type alias — use `IDataDriver` (11.0). diff --git a/.changeset/v11-remove-env-aliases.md b/.changeset/v11-remove-env-aliases.md index 1a0a298323..27b06d719a 100644 --- a/.changeset/v11-remove-env-aliases.md +++ b/.changeset/v11-remove-env-aliases.md @@ -1,7 +1,7 @@ --- -"@objectstack/types": major -"@objectstack/objectql": major -"@objectstack/cli": major +"@objectstack/types": minor +"@objectstack/objectql": minor +"@objectstack/cli": minor --- Remove ObjectStack's own legacy env-var aliases (11.0); ecosystem-standard names stay. diff --git a/.changeset/v11-remove-policyschema.md b/.changeset/v11-remove-policyschema.md index 79b7b1b784..f07385e043 100644 --- a/.changeset/v11-remove-policyschema.md +++ b/.changeset/v11-remove-policyschema.md @@ -1,5 +1,5 @@ --- -"@objectstack/spec": major +"@objectstack/spec": minor --- Remove the dead `PolicySchema` / `definePolicy` and the stack `policies` collection (#1882, ADR-0049). diff --git a/.changeset/v11-remove-unused-adapters.md b/.changeset/v11-remove-unused-adapters.md index 4bdb4e745f..907caee2ba 100644 --- a/.changeset/v11-remove-unused-adapters.md +++ b/.changeset/v11-remove-unused-adapters.md @@ -1,5 +1,5 @@ --- -"@objectstack/client": major +"@objectstack/client": minor "@objectstack/runtime": patch --- diff --git a/README.md b/README.md index dd39ebb761..57415dd86a 100644 --- a/README.md +++ b/README.md @@ -246,7 +246,6 @@ For the browser, the typed client SDK and React hooks (`useQuery` / `useMutation | [`@objectstack/plugin-webhooks`](packages/plugins/plugin-webhooks) | Outbound webhook delivery — fan-out `data.record.*` events | | [`@objectstack/plugin-reports`](packages/plugins/plugin-reports) | Saved reports + scheduled email digests | | [`@objectstack/plugin-dev`](packages/plugins/plugin-dev) | Developer mode — in-memory stubs for all services | -| [`@objectstack/plugin-msw`](packages/plugins/plugin-msw) | Mock Service Worker plugin for browser testing | ### Services @@ -268,13 +267,7 @@ For the browser, the typed client SDK and React hooks (`useQuery` / `useMutation | Package | Description | | :--- | :--- | -| [`@objectstack/express`](packages/adapters/express) | Express adapter | -| [`@objectstack/fastify`](packages/adapters/fastify) | Fastify adapter | -| [`@objectstack/hono`](packages/adapters/hono) | Hono adapter (Node.js, Bun, Deno, Cloudflare Workers) | -| [`@objectstack/nestjs`](packages/adapters/nestjs) | NestJS module integration | -| [`@objectstack/nextjs`](packages/adapters/nextjs) | Next.js App Router adapter | -| [`@objectstack/nuxt`](packages/adapters/nuxt) | Nuxt adapter (h3-based) | -| [`@objectstack/sveltekit`](packages/adapters/sveltekit) | SvelteKit adapter | +| [`@objectstack/hono`](packages/adapters/hono) | Hono adapter (Node.js, Bun, Deno, Cloudflare Workers) — the supported HTTP adapter | ### Tools & Apps @@ -324,6 +317,8 @@ Key standards: Full documentation: **[https://docs.objectstack.ai](https://docs.objectstack.ai)** +**Upgrading from 10.x?** See [Upgrading to ObjectStack 11](./docs/upgrading-to-11.md). + Run locally: `pnpm docs:dev` ## Community diff --git a/docs/upgrading-to-11.md b/docs/upgrading-to-11.md new file mode 100644 index 0000000000..42359d7c9b --- /dev/null +++ b/docs/upgrading-to-11.md @@ -0,0 +1,154 @@ +# Upgrading to ObjectStack 11 + +ObjectStack 11 is a focused breaking release: it sharpens the **open edition** down +to what is actually shipped and dogfooded, and removes a batch of long-deprecated +APIs. This guide lists every breaking change from **10.x → 11.x** with a concrete +migration for each. + +> The breaking changes are spread across the 11 line (11.0.0 + 11.1.0). There is +> one migration target: **the latest 11.x**. Pin `@objectstack/*` to `^11`. + +## Quick checklist + +- [ ] AI authoring service is no longer bundled in the open edition → see [MCP-only](#open-edition-is-mcp-only). +- [ ] Using a non-Hono HTTP adapter (Express/Fastify/Next/Nest/Nuxt/SvelteKit) or `@objectstack/plugin-msw`? → [Adapters](#http-adapters-hono-only). +- [ ] Flow nodes typed `http_request` / `http_call` / `webhook` → rename to `http`. +- [ ] `@objectstack/client-react` `useQuery` using `select`/`filters`/`sort`/`top`/`skip` → canonical names. +- [ ] Code referencing `IUIService` → `IMetadataService`. +- [ ] Driver code typed `DriverInterface` (the alias) → `IDataDriver`. +- [ ] `.env` using `OS_MULTI_TENANT` / `OBJECTSTACK_METADATA_WRITABLE` / `AUTH_BASE_URL` → rename. +- [ ] Stack `policies` / `definePolicy` → removed (was never enforced). + +--- + +## Open edition is MCP-only + +The bundled AI authoring service (`@objectstack/service-ai`) is **no longer part of +the open distribution** (ADR-0025). AI integrates through MCP (`@objectstack/mcp`) +plus the documented opt-in seam. + +**Migration** +- If you don't use AI authoring: nothing to do. +- If you do: declare `@objectstack/service-ai` / `@objectstack/service-ai-studio` + as an app dependency (the CLI auto-registers the service only when the host app + declares it), or run on the commercial distribution. MCP tooling is unaffected. + +## HTTP adapters: Hono only + +The open edition now ships **only the Hono adapter** (`@objectstack/hono`). These +packages were removed (zero internal consumers, not dogfooded): +`@objectstack/express`, `@objectstack/fastify`, `@objectstack/nextjs`, +`@objectstack/nestjs`, `@objectstack/nuxt`, `@objectstack/sveltekit`, and +`@objectstack/plugin-msw`. + +**Migration** +- **On Hono already** → no change. +- **On another framework** → either move to Hono (`createHonoApp` / `objectStackMiddleware`, + runs on Node/Bun/Deno/Workers), or build a thin adapter on the public + `HttpDispatcher` API / `createDispatcherPlugin` (the removed adapters were ~50-line + wrappers; you can vendor one out-of-tree). +- **Used `@objectstack/plugin-msw`** for test mocking → use `msw` directly, or + drive the kernel via `@objectstack/hono` in tests. + +```ts +// before: import { objectStackPlugin } from '@objectstack/fastify'; +import { createHonoApp } from '@objectstack/hono'; +const app = createHonoApp({ kernel, prefix: '/api/v1' }); +``` + +## Flow node type: `http` + +The deprecated flow-node aliases `http_request` / `http_call` / `webhook` are +removed; the canonical type is **`http`** (same behavior — durable outbox when +`config.durable`, inline fetch otherwise). Authoring a removed type now fails fast +at parse instead of silently resolving. + +```ts +// before: { id: 'call', type: 'http_request', config: { url, method } } +{ id: 'call', type: 'http', config: { url, method } } +``` + +> The trigger `eventType: 'webhook'` and the `webhook` resume event are unchanged — +> only the HTTP **node** aliases were removed. + +## `@objectstack/client-react`: canonical query fields + +`useQuery` / `useInfiniteQuery` no longer accept the legacy aliases: + +| removed | use | +|---|---| +| `select` | `fields` | +| `filters` | `where` | +| `sort` | `orderBy` | +| `top` | `limit` | +| `skip` | `offset` | + +```ts +// before: useQuery('account', { select: ['name'], filters, sort, top: 20, skip: 40 }) +useQuery('account', { fields: ['name'], where, orderBy, limit: 20, offset: 40 }); +``` + +## `IUIService` → `IMetadataService` + +The deprecated `IUIService` contract is removed. Views and dashboards are metadata: + +```ts +// before: ui.getView(name) / ui.registerView(name, def) +metadata.get('view', name); +metadata.register('view', name, def); +``` + +## `DriverInterface` (alias) → `IDataDriver` + +The deprecated `DriverInterface` type alias (`= IDataDriver`) is removed. Use +`IDataDriver` — the shape is identical. + +```ts +// before: import { DriverInterface } from '@objectstack/runtime'; +import type { IDataDriver } from '@objectstack/spec/contracts'; +``` + +> Unrelated and unchanged: the live `IDataEngine` (engine-layer contract) and the +> zod-derived `DriverInterface` / `DriverInterfaceSchema` in `@objectstack/spec/data`. + +## Environment variables: ObjectStack's own renames removed + +The framework's **own** legacy env names are removed — rename them: + +| removed | use | +|---|---| +| `OS_MULTI_TENANT` | `OS_MULTI_ORG_ENABLED` | +| `OBJECTSTACK_METADATA_WRITABLE` | `OS_METADATA_WRITABLE` | +| `OS_AUTH_BASE_URL`, `AUTH_BASE_URL` | `OS_AUTH_URL` | + +**Ecosystem-standard names still work** (and no longer warn): `DATABASE_URL`, +`AUTH_SECRET`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, `PORT`, `CORS_*`, +`LOG_LEVEL`, `ROOT_DOMAIN`, `MCP_SERVER_*`. + +## `PolicySchema` / `definePolicy` removed + +The "org security policy" schema (`PolicySchema`, `definePolicy`, and the stack +`policies` collection) is removed — it was parsed but **never enforced** at runtime +(ADR-0049). `better-auth` governs session/password behavior; there is no functional +loss. + +**Migration**: delete `policies: [...]` from `defineStack(...)` and any +`definePolicy(...)` definitions. For real password/session policy, configure +`@objectstack/plugin-auth`. `SharingRule` / `PermissionSet` / RLS are unaffected. + +--- + +## Behavioral changes to be aware of (not API-breaking) + +11 also hardens authentication (ADR-0069). These don't change your code but can +change runtime behavior for end users: + +- Breached passwords are rejected (HIBP). +- Account lockout + login rate-limiting. +- Optional password expiry, history/no-reuse, complexity, and enforced MFA + (per-org). Review your `@objectstack/plugin-auth` configuration before rollout. + +## Getting help + +If a removed adapter or API blocks you, open an issue — thin adapters and the +`HttpDispatcher` API are public, so out-of-tree maintenance is straightforward.