@marianmeres/ownsuite 1.0.3 → 2.1.0

package/AGENTS.md

@@ -6,7 +6,7 @@ Machine-readable documentation for AI coding assistants.
 
 ```yaml
 name: "@marianmeres/ownsuite"
-version: "1.0.0"
+version: "2.0.0"
 type: "library"
 language: "typescript"
 runtime: "deno"
@@ -19,25 +19,51 @@ entry: "./src/mod.ts"
 
 Client-side helper library for **owner-scoped** UIs. Generic domain managers for CRUD over collections where every row is implicitly filtered to the authenticated subject by the server. Mirrors the shape of `@marianmeres/ecsuite` but applies to arbitrary owner-scoped collections instead of hard-coded e-commerce domains.
 
+**Also (opt-in)** provides the blessed account-lifecycle surface for apps built on `@marianmeres/stack-account`: `suite.auth` (register / login / logout / OAuth init / password reset / delete account), `suite.profile` (`/me` CRUD + OAuth link list), `suite.session` (reactive JWT + subject, pluggable storage). Pass an `AuthAdapter` to `createOwnsuite({ adapters: { auth } })` to attach them.
+
 Pairs with:
 - **`@marianmeres/collection`** — `ownerIdScope` route hook (read-side owner enforcement).
 - **`@marianmeres/stack-common`** — `ownsuiteOptions()` server helper for mounting `/me/*` routes.
+- **`@marianmeres/stack-account`** — default adapters (`createStackAccountAuthAdapter`, `createStackAccountProfileAdapter`) target its REST surface.
 
 ## Architecture
 
 ```
 Ownsuite (orchestrator)
-├── #pubsub           (shared event bus)
+├── #pubsub           (shared event bus, cleared on destroy)
 ├── #context          (propagated to all domains on setContext)
 └── domains: Map<string, OwnedCollectionManager>
-      ├── store       (Svelte-compatible DomainStateWrapper<OwnedCollectionState<TRow>>)
-      ├── adapter     (OwnedCollectionAdapter)
-      ├── state machine: initializing → ready ↔ syncing → error
-      └── optimistic update + rollback on create/update/delete
+      ├── store           (Svelte-compatible DomainStateWrapper<OwnedCollectionState<TRow>>)
+      ├── adapter         (OwnedCollectionAdapter)
+      ├── state machine:  initializing → ready ↔ syncing → error
+      ├── optimistic update + per-row rollback on update/delete
+      ├── mutation chain  (serial create/update/delete)
+      ├── abort-supersede (initialize/refresh — newer call aborts older)
+      └── destroy()       (aborts in-flight ops, drops adapter)
 ```
 
 Each domain holds one list of rows. List operations replace the list wholesale; single-row ops mutate it in place so subscribers see stable references.
 
+### Concurrency model
+
+- **Mutations serialize** per manager via an internal promise chain. A
+  `create/update/delete` that starts while another is in-flight queues
+  behind it; callers still receive their own result through the returned
+  promise. Rejections on the chain are swallowed so they do not block
+  later mutations.
+- **Reads abort-supersede**: a new `initialize()` or `refresh()` aborts
+  any in-flight read on the same manager. The aborted call resolves
+  without writing to the store.
+- **onSuccess uses live data, not a captured snapshot**, so interleaving
+  reads and mutations never resurrect deleted rows or clobber writes.
+- **Rollback is per-row**: a failed `update` reverts just the updated
+  row; a failed `delete` re-inserts the deleted row at its original
+  position. An interleaved refresh that brought new rows is preserved.
+- **AbortSignal plumbing**: every adapter call receives
+  `ctx.signal: AbortSignal`. `reset()` and `destroy()` abort all active
+  signals. Adapters should forward the signal to `fetch()` — ignoring
+  it is safe but leaves abandoned requests running.
+
 ## Directory Structure
 
 ```
@@ -47,17 +73,28 @@ src/
 ├── types/
 │   ├── mod.ts
 │   ├── state.ts                # DomainState/Wrapper/Error, OwnsuiteContext, OwnedCollectionState
-│   ├── events.ts               # OwnsuiteEventType, OwnsuiteEvent union, per-event interfaces
-│   └── adapter.ts              # OwnedCollectionAdapter, OwnedListResult, OwnedRowResult
+│   ├── events.ts               # OwnsuiteEventType, OwnsuiteEvent union (incl. auth:* / profile:* / oauth:*)
+│   ├── adapter.ts              # OwnedCollectionAdapter, OwnedListResult, OwnedRowResult
+│   └── auth.ts                 # AuthAdapter, ProfileAdapter, SessionState/Subject/Status, OAuth*
 ├── domains/
 │   ├── mod.ts
 │   ├── base.ts                 # BaseDomainManager abstract class (mirrors ecsuite)
-│   └── owned-collection.ts     # OwnedCollectionManager<TRow, TCreate, TUpdate>
+│   ├── owned-collection.ts     # OwnedCollectionManager<TRow, TCreate, TUpdate>
+│   ├── session.ts              # SessionManager + pluggable SessionStorage resolver
+│   ├── auth.ts                 # AuthManager (register/login/logout/OAuth/verify/delete)
+│   └── profile.ts              # ProfileManager (/me singleton)
+├── oauth/
+│   └── popup.ts                # openOAuthPopup + injectable PopupWindowHost for tests
 └── adapters/
     ├── mod.ts
-    └── mock.ts                 # createMockOwnedCollectionAdapter for tests
+    ├── mock.ts                 # createMockOwnedCollectionAdapter
+    ├── mock-auth.ts            # createMockAuthAdapter / createMockProfileAdapter / createMockAuthStore
+    └── stack-account.ts        # createStackAccountAuthAdapter / createStackAccountProfileAdapter
 tests/
-└── ownsuite.test.ts
+├── ownsuite.test.ts            # core suite + OwnedCollectionManager
+├── concurrency.test.ts         # critical-invariant coverage (abort-supersede, rollback, etc.)
+├── auth.test.ts                # AuthManager / ProfileManager / SessionManager
+└── oauth-popup.test.ts         # openOAuthPopup message / timeout / close / origin semantics
 ```
 
 ## Key Exports
@@ -65,7 +102,9 @@ tests/
 ```typescript
 // Main
 export { Ownsuite, createOwnsuite } from "./ownsuite.ts";
-export type { OwnsuiteConfig, OwnsuiteDomainConfig } from "./ownsuite.ts";
+export type {
+	OwnsuiteConfig, OwnsuiteDomainConfig, SetContextOptions,
+} from "./ownsuite.ts";
 
 // Domain managers
 export { BaseDomainManager, OwnedCollectionManager } from "./domains/mod.ts";
@@ -85,8 +124,65 @@ export type {
 // Mock adapter (for tests)
 export { createMockOwnedCollectionAdapter } from "./adapters/mod.ts";
 export type { MockAdapterOptions } from "./adapters/mod.ts";
+
+// Account lifecycle (optional — attached when adapters.auth is supplied)
+export { SessionManager, AuthManager, ProfileManager } from "./domains/mod.ts";
+export type {
+	AuthAdapter, ProfileAdapter, AuthTokenResult, ProfileResult,
+	SessionState, SessionSubject, SessionStatus,
+	SessionStorage, SessionStorageType,
+	OAuthConnection, OAuthProvider, OAuthInitOptions, OAuthAction,
+} from "./types/mod.ts";
+
+// OAuth popup helper
+export { openOAuthPopup } from "./oauth/popup.ts";
+export type {
+	OAuthPopupMessage, OAuthPopupLoginMessage, OAuthPopupLinkMessage,
+	OpenOAuthPopupOptions, PopupWindowHost, PopupWindowHandle,
+} from "./oauth/popup.ts";
+
+// Default stack-account adapters
+export {
+	createStackAccountAuthAdapter,
+	createStackAccountProfileAdapter,
+} from "./adapters/mod.ts";
+export type { StackAccountAdapterOptions } from "./adapters/mod.ts";
+
+// Mock auth adapter (for tests)
+export {
+	createMockAuthAdapter, createMockProfileAdapter,
+	createMockAuthStore, verifyMockAccount,
+} from "./adapters/mod.ts";
+export type { MockAuthStore } from "./adapters/mod.ts";
 ```
 
+## Account lifecycle (optional)
+
+When `adapters.auth` is supplied, `createOwnsuite` instantiates three extra managers and attaches them as readonly suite properties:
+
+- **`suite.session: SessionManager`** — reactive `{ status, subject, jwt, expiresAt }` persisted via pluggable `SessionStorage` (`"local"` / `"session"` / `"memory"` / custom object). Hydrates on construction; discards expired sessions. Exposes `subscribe` (Svelte-compatible), `get()`, and state-mutation methods (`setAuthenticated`, `setUnverified`, `clear`, `patchSubject`). Writes are driven by `AuthManager`, not consumers directly.
+
+- **`suite.auth: AuthManager`** — verbs only, no state. `register` / `login` / `logout` / `resendVerification` / `requestPasswordReset` / `changePassword` / `deleteAccount` / `initiateOAuth` (`mode: "popup" | "redirect"`) / `handleOAuthCallback` (redirect mode). Each call pipes the result into the session and fires an `onIdentityChanged` hook that resets + re-initializes every owner-scoped domain with the fresh context.
+
+- **`suite.profile: ProfileManager`** — singleton (one-row) `/me` CRUD. `fetch` / `update` / `listOAuth` / `unlinkOAuth`. Every successful fetch/update patches the session subject in place so consumers reading `suite.session` see email / roles / verification / connections without a second fetch. Update emits `profile:updated`.
+
+The session subscribes to its own store and propagates `ctx.jwt` + `ctx.subjectId` into every registered owner-scoped domain automatically — authentication changes propagate without any manual wiring from consumers.
+
+### Auth events (emitted on the shared pubsub)
+
+- `auth:register` — `{ email, requiresVerification }`
+- `auth:login` — `{ email }`
+- `auth:logout` — `{ subjectId? }`
+- `auth:session:changed` — `{ session: SessionState }`
+- `auth:verification:required` — `{ email }` (fired when `status` transitions to `"unverified"`)
+- `profile:updated` — `{ email }`
+- `oauth:linked` — `{ connection }`
+- `oauth:unlinked` — `{ provider }`
+
+### OAuth popup protocol
+
+`suite.auth.initiateOAuth(provider, opts)` with `mode: "popup"` opens a popup at the server's `/oauth/{provider}/init` URL and awaits a `postMessage` from the server's callback page (`{ type: "oauth_login_success" | "oauth_link_success" | "oauth_error", ... }`). For `mode: "redirect"` the top window navigates and the app's callback page calls `suite.auth.handleOAuthCallback()` on mount.
+
 ## State Machine
 
 ```
@@ -102,15 +198,23 @@ Triggered by `initialize()`, `refresh()`, `create()`, `update()`, `delete()` on
 
 1. **Client NEVER sets `owner_id`.** The server stamps it from the authenticated JWT via `@marianmeres/collection`'s `ownerIdExtractor`. Including `owner_id` in a create/update payload will be rejected (belt-and-braces) or silently ignored (immutability guarantee on update).
 
-2. **Ownership mismatches return 404, not 403.** When the server's `ownerIdScope` rejects access to a foreign row, it responds 404 to avoid leaking row existence. Adapter implementations must not treat 404 as a soft miss — they must throw so the manager transitions to `error` state for unexpected 404s on previously-visible rows.
+2. **Ownership mismatches return 404, not 403.** When the server's `ownerIdScope` rejects access to a foreign row, it responds 404 to avoid leaking row existence. For `list`/`refresh`, adapters must throw — the manager transitions to `error`. For `getOne`, a throw lands only in a returned `null` (see invariant 7).
+
+3. **Row ids default to `model_id`, fallback `id`.** Override via `getRowId` in `OwnsuiteDomainConfig` or `OwnedCollectionManagerOptions` when rows have a different key shape. Empty string is rejected.
 
-3. **Row ids default to `model_id`, fallback `id`.** Override via `getRowId` in `OwnsuiteDomainConfig` or `OwnedCollectionManagerOptions` when rows have a different key shape.
+4. **`initialize()` never rejects.** Per-domain errors land in that domain's `error` state; the top-level promise resolves. Use `suite.hasErrors()` / `suite.errors()` to detect failed boots, or subscribe to `domain:error`.
 
-4. **`initialize()` never rejects.** Per-domain errors land in that domain's `error` state; the top-level promise resolves. Callers that need failure detection should subscribe to `domain:error` events or inspect `manager.get().state`.
+5. **Optimistic updates roll back per-row on failure.** `update` mutates the single target row; on error that row reverts to its pre-call value. `delete` removes the target row; on error it is re-inserted at its original position (unless another op has since re-added it). `create` does NOT optimistically insert. Rollback reads the *live* store so an interleaved `refresh()` that brought new rows is preserved.
 
-5. **Optimistic updates roll back on failure.** `update` and `delete` mutate the list before the server call; on error the list is restored to its pre-call snapshot and the manager transitions to `error`. `create` does NOT optimistically insert (no client-assigned id) — it only inserts after the server returns.
+6. **`OwnsuiteContext.subjectId` is a hint, not authorization.** The server is authoritative. Setting it client-side has no security effect. When subject changes, call `suite.setContext(ctx, { replace: true, refresh: true })` to clear stale per-subject caches.
 
-6. **`OwnsuiteContext.subjectId` is a hint, not authorization.** The server is authoritative. Setting it client-side has no security effect.
+7. **`getOne()` does NOT transition the domain to `error`.** A failing single-row read (commonly a 404 for an un-owned row) returns `null` and emits nothing. The list state is preserved.
+
+8. **`update(id)` for a row absent from the cached list does NOT insert.** A missing index means the row was filtered out or never loaded — the successful server response is acknowledged (`own:row:updated` is emitted) but the list remains untouched. Call `refresh()` to surface the row.
+
+9. **Mutations serialize; reads abort-supersede.** Within a single manager, `create/update/delete` run one-at-a-time in call order. A newer `initialize/refresh` aborts an older one (the older call becomes a no-op).
+
+10. **`ctx.signal` is present on every adapter call.** Adapters should forward it to `fetch()`. Signals abort on `reset()`, `destroy()`, and read-supersede.
 
 ## Common Patterns
 
@@ -152,6 +256,29 @@ suite.on("domain:error",     (e) => {/* e.error */});
 suite.onAny(({ event, data }) => {/* wildcard envelope */});
 ```
 
+### Detecting boot failures
+
+```typescript
+await suite.initialize();
+if (suite.hasErrors()) {
+	const errs = suite.errors(); // { [domainName]: DomainError }
+	// route to error UI, log, retry, ...
+}
+```
+
+### Switching subject mid-session
+
+```typescript
+// Clears the previous subject's context keys and re-fetches every domain.
+suite.setContext({ subjectId: newId }, { replace: true, refresh: true });
+```
+
+### Cleanup
+
+```typescript
+suite.destroy(); // aborts in-flight requests, unsubscribes pubsub, drops adapters
+```
+
 ### Implementing a real adapter
 
 ```typescript
@@ -159,14 +286,14 @@ import type { OwnedCollectionAdapter } from "@marianmeres/ownsuite";
 import { HTTP_ERROR } from "@marianmeres/http-utils";
 
 const adapter: OwnedCollectionAdapter = {
-	async list(_ctx, query) {
+	async list(ctx, query) {
 		const url = new URL(`/api/shop/me/col/order/mod`, location.origin);
 		if (query) for (const [k, v] of Object.entries(query)) url.searchParams.set(k, String(v));
-		const res = await fetch(url);
+		const res = await fetch(url, { signal: ctx.signal }); // forward abort
 		if (!res.ok) throw new HTTP_ERROR.BadRequest(await res.text());
 		return await res.json(); // { data, meta }
 	},
-	// getOne, create, update, delete similarly
+	// getOne, create, update, delete similarly — always forward ctx.signal
 };
 ```
 
@@ -234,10 +361,16 @@ dev:
 ## Testing
 
 ```bash
-deno task test       # run all tests (10 tests)
+deno task test       # run all tests (44 tests across 4 files)
 deno task test:watch # watch mode
 ```
 
+Coverage by file:
+- `tests/ownsuite.test.ts` — core suite + `OwnedCollectionManager` CRUD, events, rollback.
+- `tests/concurrency.test.ts` — critical invariants: concurrent mutations, abort-supersede, `getOne` not setting error, phantom-row prevention, destroy semantics, `errors()`/`hasErrors()` helpers.
+- `tests/auth.test.ts` — `AuthManager` / `ProfileManager` / `SessionManager`: register / login / logout / unverified gate / OAuth login (popup + redirect) / OAuth unlink / profile update patching session / deleteAccount / identity-change hook propagation.
+- `tests/oauth-popup.test.ts` — `openOAuthPopup` message / timeout / popup-closed / origin-mismatch semantics via injectable `PopupWindowHost`.
+
 ## Build & Publish
 
 ```bash
@@ -277,6 +410,58 @@ Joy ships:
 
 See the full-stack-app-template repo for the end-to-end example.
 
+## Breaking changes in 2.0.0
+
+The 1.x line has one open set of correctness bugs and a permissive API
+that leaked state into domain errors on non-list operations. 2.0.0 fixes
+those; the behaviors changed are:
+
+1. **`getOne()` no longer transitions the domain to `error`.** Previously
+   any adapter throw from `getOne` set `state: "error"` on the whole
+   domain, invalidating a healthy list view. Now it returns `null` and
+   logs at debug level. Callers relying on the error-state transition
+   must subscribe differently (wrap `getOne` or inspect adapter errors
+   directly).
+
+2. **`update(id, ...)` for an id absent from the cached list no longer
+   prepends a phantom row** on successful server response. The server
+   update is still applied (and `own:row:updated` emitted), but the list
+   stays as-is. Call `refresh()` to surface the row. Previously the row
+   was inserted at the top of the list.
+
+3. **`OwnsuiteContext.signal` is now populated by the manager on every
+   adapter call.** Adapters that declared `ctx: OwnsuiteContext` see no
+   compile break (the field was already allowed via the index
+   signature); adapters that want cancellation should now forward
+   `ctx.signal` to `fetch()`. Adapters that ignore it continue to work.
+
+4. **`createMockOwnedCollectionAdapter` rejects `create` payloads
+   containing `model_id`** by default. Tests that were relying on
+   passing a `model_id` at create time must either drop the field or
+   opt out via `rejectClientId: false` in the options. Rows with an
+   empty-string `model_id` in `seed` are also rejected.
+
+5. **Rollback is now per-row, not whole-list.** Behavioral semantics
+   are stricter: a failed `update` reverts only the updated row; a
+   failed `delete` re-inserts only the deleted row. If your app relied
+   on the whole-list-restore side effect (e.g., to drop rows added by
+   a concurrent refresh that raced with a failing mutation), note this
+   subtle shift.
+
+6. **`reset()` now emits `domain:state:changed`** for each domain that
+   transitions out of a non-initializing state. Subscribers that count
+   events may see more of them.
+
+Non-breaking additions: `suite.destroy()`, `suite.errors()`,
+`suite.hasErrors()`, `suite.setContext(ctx, { replace, refresh })`,
+`manager.isDestroyed`, `manager.replaceContext(ctx)`.
+
+**Account lifecycle managers (opt-in addition).** `suite.auth` /
+`suite.session` / `suite.profile` attach automatically when
+`adapters.auth` is passed to `createOwnsuite`. Existing owner-scoped
+CRUD consumers see no change unless they opt in. Full surface is
+described in the "Account lifecycle (optional)" section above.
+
 ## Differences from `@marianmeres/ecsuite`
 
 | Aspect | ecsuite | ownsuite |