create-flowdular 0.2.6 → 0.3.0

package/agent-template/docs/module-web-surfaces.md

@@ -0,0 +1,221 @@
+# Module-owned web surfaces
+
+A module can provide workspace administration, HTTP APIs and independently laid
+out web pages in the same installation. Web pages are optional server composition
+contributions. They do not render `ApplicationShell` or `AuthenticationCore`.
+Access and presentation are independent: a standalone portal may still require
+authentication or a permission.
+
+## Module declaration
+
+Use the normal approved module specification and `platform.server: true` entry.
+Declare the public interface and its visibility rules in that specification.
+No new manifest capability or separate business module is required.
+
+```ts
+import { defineWebSurface } from '@flowdular/sdk/server';
+import type { ModuleServerComposition } from '@flowdular/sdk/server';
+
+export function createServerComposition(): ModuleServerComposition {
+	return {
+		routes: [], // Existing protected administration APIs can remain here.
+		web: [
+			defineWebSurface({
+				id: 'public',
+				pages: [
+					{
+						id: 'record',
+						path: '/records/:slug',
+						entry: ['RecordPage', '@example/module/web'],
+						layout: '@example/module/web-layout',
+						access: { kind: 'public' },
+						async load({ site, params, signal }) {
+							// Call your module's service with site.tenantId.
+							// Read inside a tenant-scoped, read-only transaction.
+							// Return 404 if the record is missing or is not public.
+							return { title: 'Public record', slug: params.slug ?? '' };
+						},
+					},
+				],
+			}),
+		],
+	};
+}
+```
+
+Add browser-safe package exports for the page and optional layout:
+
+```json
+{
+	"exports": {
+		"./platform": "./src/platform.ts",
+		"./web": "./src/web/RecordPage.tsrx",
+		"./web-layout": "./src/web/Layout.tsrx"
+	}
+}
+```
+
+Use package subpaths, not workspace absolute paths. These entries go through
+Octane's normal development and production SSR/hydration compilation. Keep
+database, credentials and server imports out of both page and layout. Declare
+all imported dependencies in the package manifest. Reuse the shared translation
+runtime and the module's existing bundles when localization is needed.
+
+## Operator configuration
+
+Add the optional `web` section in the installation's `flowdular.json`:
+
+```json
+{
+	"web": {
+		"mounts": [
+			{
+				"id": "acme-public",
+				"moduleId": "example.core",
+				"surfaceId": "public",
+				"path": "/blog",
+				"tenantId": "the-existing-acme-tenant-id",
+				"enabled": true
+			}
+		]
+	}
+}
+```
+
+Run `pnpm flowdular module sync --apply`, then rebuild/redeploy production or
+restart development. Configuration is generated into the server composition;
+changing it requires regeneration. It is not read from a process-local settings
+cache or an anonymous query parameter. Verify the tenant ID before publishing.
+The same module surface can be mounted for multiple tenants under different
+paths. `/records/:slug` above becomes `/blog/records/:slug`.
+
+The root `/` can host a public storefront, alongside more specific mounts such as
+`/blog`. Reserved platform prefixes such as `/app`, `/auth`, `/api`, `/setup` and
+the configured backoffice path cannot be claimed by modules. Other overlapping
+mounts and equivalent route patterns are rejected. Custom paths such as `/blog`, `/portal` and `/forms/contact` work without a
+tenant ID in the URL. `/sites/` is an optional convention for multiple sites;
+unknown sites under that prefix return 404. A disabled binding
+or an uninstalled/disabled module leaves its configured address returning 404.
+Keep that disabled binding when retiring an address so it cannot fall through
+to legacy workspace routing. Remove the binding only when releasing the address.
+
+A mount owns the addresses its pages declare. A mount under a custom path also
+answers 404 below its own base, so do not put a `platform/public` file there.
+A root mount claims nothing beyond its pages: the host serves built assets,
+`platform/public` files and, in development, Vite's module and transform
+requests from addresses the router leaves unmatched, and answers 404 for the
+rest. An unknown public URL under a root mount therefore still returns 404, and
+a root mount never shadows `/assets/...`, `/favicon.svg` or `/@vite/client`.
+A deployment that wraps the exported handler itself must serve `dist/client`
+in front of it, as the bundled Node server does.
+
+### Backoffice address
+
+The first-run setup includes **Backoffice address**, defaulting to `/app` (or the
+installation's configured default). Choose `/backoffice` to leave `/` available
+for a storefront. Setup validates the address, includes it in the review, and
+writes `FD_APPLICATION_PATH=/backoffice` alongside the database settings. Restart
+after setup; no client rebuild is needed for this environment setting. On a
+read-only deployment setup provides the environment block to paste into the
+hosting service. If `FD_APPLICATION_PATH` already exists in the environment, it
+is authoritative; setup cannot silently replace it.
+
+For configuration managed in source control, add:
+
+```json
+{
+	"application": { "path": "/backoffice" },
+	"web": {
+		"mounts": [
+			{
+				"id": "store",
+				"moduleId": "example.core",
+				"surfaceId": "public",
+				"path": "/",
+				"tenantId": "the-existing-tenant-id"
+			}
+		]
+	}
+}
+```
+
+Run module sync and rebuild after changing `flowdular.json`. At startup,
+`FD_APPLICATION_PATH` overrides `application.path`; `/app` is the fallback.
+The value is installation-wide, one lowercase path segment of at most 64
+characters. Navigation, authentication redirects and dashboard deep links use
+it. When changed from `/app`, old `/app/...` bookmarks redirect permanently to
+the configured address, preserving the suffix and query. Authentication pages
+remain under `/auth/...`. A root mount removes the legacy slug-first dashboard
+aliases; unknown public URLs return 404 instead of displaying the dashboard.
+
+This release supports path mounts. Custom hostname binding, DNS ownership and
+TLS provisioning are a separate deployment feature. It does not download or
+activate executable modules at request time.
+
+## Page and hydration
+
+```tsx
+import { Head, Seo } from '@octanejs/seo';
+import { webPageData } from '@flowdular/sdk/client/web';
+import type { RenderRouteProps } from '@octanejs/vite-plugin';
+
+export function RecordPage(props: RenderRouteProps) @{
+	const record = webPageData<{ title: string; slug: string }>(props);
+	<Head>
+		<Seo title={record.title} description="A public record" />
+		<main><h1>{record.title}</h1><p>{record.slug}</p></main>
+	</Head>
+}
+```
+
+`load` runs before rendering, so it can return an actual 404 or redirect before
+streaming starts. Its JSON result is the only data serialized into the page;
+the authentication state, database handles and the rest of `Context.state` are
+never serialized. `webPageData` reads that exact DTO on the server and during
+hydration, with no second fetch. A layout receives the usual Octane page props
+and `children`. Pages own their metadata, styling and UI states.
+
+For an explicit refresh or client navigation, use
+`loadWebPage<T>(url, abortSignal)` from the same client subpath. It requests the
+same URL with `Accept: application/vnd.flowdular.page+json`, which runs the same
+tenant, access and loader checks. Native links and deep-link refresh also work.
+The page loader and data representation accept only GET/HEAD, never mutations.
+Existing module endpoints remain the mechanism for writes; they must retain
+their permission, CSRF and input-validation rules.
+
+## Access and safety
+
+- `public`: the loader's identity is always null, even if the visitor has a
+  dashboard session for another tenant. Data ownership comes from `site.tenantId`.
+- `authenticated`: requires an authenticated principal whose active tenant
+  matches the configured site tenant. Otherwise returns 401 or 403.
+- `permission`: additionally requires the declared permission, for example
+  `{ kind: 'permission', permission: 'example.records.read' }`.
+
+The module must enforce record visibility inside its own service. Tenant RLS
+alone does not hide private records from a public visitor to that same tenant.
+Never reuse an unrestricted administration query as a public loader. Return
+`new Response('Not found', { status: 404 })` for inaccessible content. Use the
+request signal to cancel database or external work and bound query inputs.
+
+All responses use `Cache-Control: no-store`; the HTML and JSON representations
+vary on `Accept`. Shared/CDN caching is deliberately disabled until an explicit
+tenant-aware invalidation policy is configured in a future extension. Page JSON
+is bounded to 1 MiB. Unexpected failures return safe errors without raw secrets.
+The host lifecycle drains response streams on completion, cancellation, errors
+and request abort before releasing module resources.
+
+Installed modules remain trusted code in the host process. Module composition
+types now live in the shared server API; auth exports compatibility aliases for
+existing modules. This extension is not a runtime security sandbox.
+
+## Validation
+
+Run module typechecks and tests, `pnpm verify`, and `pnpm build`. Cover public
+and denied access, two tenants using the same slug, draft/private records,
+redirects, 404s, deep links, cancellation and DTO contents. The shared production
+integration test is `node scripts/smoke-web.mjs`; it creates an isolated fixture,
+runs the real CLI composition generator, compiles the page and layout, and
+checks production HTTP behavior. `FD_WEB_SMOKE_KEEP=true` retains its temporary
+server for manual hydration and keyboard checks. No operator module is enabled
+and no real tenant data is used by that test.

package/agent-template/docs/modules.md

@@ -22,6 +22,37 @@ spec is the contract: `permissions[].id` equal the constants in
 pnpm flowdular spec validate --all
 ```
 
+`schemaVersion: 2` adds the domain model, so an implementing agent reads the
+spec instead of scanning the repository. Every section is optional and a
+`schemaVersion: 1` spec stays valid unchanged; version 1 rejects these keys.
+
+- `entities[]`: `id`, `name`, `fields[]` (`id`, `type` of `string`, `text`,
+  `integer`, `decimal`, `boolean`, `date`, `datetime`, `enum`, `reference` or
+  `json`, plus `required`, `unique: tenant|none`, `maxLength`, `values` for an
+  enum, `reference` as `<entityId>` or `<moduleId>.<entityId>`), and optional
+  `states` (`field`, `values`, `transitions`).
+- `screens[]`: `id`, `kind` of `list`, `record`, `form` or `dashboard`,
+  `entity`, `title`, `columns`, `filters`, `navigationGroup`.
+- `actions[]`: `id`, `entity`, `permission`, `kind`, `risk`, `idempotent`,
+  `description`. `widgets[]`: `id`, `slot`, `entity`, `description`.
+- `settings[]`: `key`, `type`, `scope`, `default`, `values`, `description`.
+  `agentTools[]`: `id`, `permission`, `description`, `risk`.
+- `outOfScope[]` records what is deliberately not built; `decisions[]` records
+  each interview question, its answer and whether a user or a default decided.
+
+Validation is more than the schema: an action permission must exist in
+`permissions`, every `entity` must name an entity, screen `columns` and
+`filters` must be fields of that entity, a `reference` must resolve in this spec
+or a declared dependency, an enum field or setting needs `values`, `states.field`
+must be the enum that declares exactly `states.values`, a field may not be called
+`id`, `tenantId`, `createdAt` or a PostgreSQL reserved word such as `order` or
+`user` (generated SQL quotes no identifier), and the `database` capability needs
+at least one entity (`SPEC_ACTION_PERMISSION_UNKNOWN`, `SPEC_ENTITY_UNKNOWN`,
+`SPEC_FIELD_UNKNOWN`, `SPEC_FIELD_RESERVED`, `SPEC_STATE_FIELD_INVALID`,
+`SPEC_REFERENCE_UNKNOWN`, `SPEC_ENUM_VALUES_REQUIRED`, `SPEC_ENTITY_REQUIRED`,
+`SPEC_DUPLICATE_ID`). A client without a list screen, or a stored entity with no
+tenant-unique field, is a warning.
+
 ### 2. Scaffold
 
 ```bash
@@ -42,6 +73,15 @@ and `migrations/0001_*.up.sql` and `.down.sql` with the tenant table and its
 forced row-level security block. The contract is in
 [Database adapters](database-adapters.md) and the `database-adapter` skill.
 
+From a `schemaVersion: 2` spec one entity replaces the demo record: the one
+whose id matches the permission entity segment, else the first declared. Its
+fields become `src/domain/types.ts`, the `0001` migration columns (with
+`UNIQUE (tenant_id, …)` for a `unique: tenant` field), the repository row
+mapping, the create endpoint's input validation (required fields only; the
+lifecycle field is set by the service), and the columns of the first `list`
+screen become the table view. Further entities are the implementing agent's
+work.
+
 Files are written through the workspace Prettier, so the format gate passes
 without a rewrite. A directory that already holds `spec/module.yaml` or
 `translations/**` is extended, not rejected, and a failed run leaves nothing
@@ -107,6 +147,38 @@ A running `pnpm dev` picks the change up live: the octane plugin reloads server
 routes when the generated composition changes and the client hot-reloads, so no
 rebuild is needed. `pnpm dev` and `pnpm build` run the sync automatically.
 
+## Versions, ranges and capabilities
+
+A module carries one version in three places: `module.json` `version`,
+`package.json` `version` and `spec/module.yaml` `specVersion`. Bump them with
+one command; it also rewrites every dependent range that stops accepting the
+new version and keeps the operator (`^0.11.0` becomes `^0.12.0`):
+
+```sh
+pnpm flowdular module version auth.core
+pnpm flowdular module version bump auth.core minor --apply
+```
+
+Dependency ranges use caret (`^0.11.0`). Below 1.0.0 a caret range accepts
+patch releases only, so a minor bump of a core module still moves its
+dependents, which the bump command does. `module validate` reports
+`SPEC_DEPENDENCY_DRIFT` when the spec and manifest ranges differ and
+`PLATFORM_API_MISSING` when a manifest lacks `platformApi`.
+
+`platformApi` is the range of the platform contract the module compiles against
+(`^0.1.0`). The contract surface is pinned in
+`packages/kernel/platform-api.snapshot.d.ts`; a change to it without a
+`PLATFORM_API_VERSION` bump fails `pnpm verify`. `module search --compatible`
+lists only releases whose range accepts the running platform.
+
+Cross-module services are declared by capability id, not by module version:
+`provides` lists the ids a module registers, `requires` lists the ids it
+resolves (`optional: true` when it handles absence). The kernel orders required
+providers before consumers, refuses a missing provider or two providers of one
+id, and the composition hands each module a registry view that accepts only its
+declared ids. The installer resolves a required capability to the newest
+compatible release that provides it.
+
 ## Files the CLI owns
 
 Never edit these by hand:
@@ -128,6 +200,150 @@ returned as `settings` from the composition, read live with
 module's drawer under Administration, Modules. Administration, Settings holds
 only workspace and organization settings.
 
+## Record policies
+
+A permission says who may act on a kind of record. A policy says whether this
+record allows it: an amount above an approver's limit, a claim the submitter
+owns, a contract outside the reviewer's region. Policies are declared with
+`definePolicy` from `@flowdular/sdk/kernel` and evaluated through a registry the
+module fills while it composes:
+
+```ts
+const amountLimit = definePolicy<Claim>({
+	id: 'expenses.claims.amount-limit',
+	permission: 'expenses.claims.approve',
+	evaluate: ({ record }) =>
+		record.amountMinor <= 100_000
+			? { allowed: true }
+			: {
+					allowed: false,
+					reason: 'The claim exceeds the approver limit.',
+					requiresApproval: {
+						requirement: { roleKey: 'finance-lead', decisions: 2 },
+					},
+				},
+});
+
+const policies = createPolicyRegistry();
+policies.register(amountLimit);
+policies.seal();
+
+/* In the endpoint, once the record is loaded and before it is written. */
+const decision = authorizeRecord(
+	policies,
+	principal,
+	'expenses.claims.approve',
+	claim,
+	'approve',
+);
+if (!decision.allowed) {
+	throw new HttpProblem('POLICY_DENIED', decision.reason, 403);
+}
+```
+
+`authorizeRecord` checks the permission scope first and evaluates policies only
+after it holds, so a policy never sees a principal that lacks the permission. It
+answers the first denial in registration order; a permission with no policy is
+allowed by the scope alone. A policy that throws denies rather than escaping
+into the endpoint. Register once per id, at most 256 policies, and seal the
+registry before serving requests: a policy registered at request time would
+change a decision under the requests already in flight.
+
+`requiresApproval.requirement` carries `roleKey`, `scope`, `decisions` and
+`expiresInDays`, and nothing else. Resolving a role to people, collecting their
+decisions and keeping the receipt belong to the module that owns approvals; the
+kernel owns the shape so a denial can name what would lift it. The platform does
+not compose a shared registry yet, so a module that wants record conditions today
+owns its registry inside its own composition.
+
+## List pagination
+
+New list endpoints page with the helpers in `@flowdular/sdk/server`
+(`packages/server/src/pagination.ts`). The endpoints written before them keep
+their own paging until the owning module retrofits it in its own change, so do
+not migrate another module's list while touching yours.
+
+```ts
+const page = readPageQuery(new URL(octane.request.url), { maxLimit: 100 });
+const after = page.cursor ? decodeCursor(page.cursor, cursorSecret) : null;
+const keyset = after
+	? keysetWhere(
+			['created_at', 'id'],
+			[Number(after['createdAt']), String(after['id'])],
+			{ parameterOffset: 1 },
+		)
+	: null;
+
+/* One row more than the page is what says whether another page exists. */
+const rows = await repository.pageClaims(tenantId, keyset, page.limit + 1);
+const items = rows.slice(0, page.limit);
+const last = items[items.length - 1];
+return pageResponse({
+	items,
+	limit: page.limit,
+	nextCursor:
+		rows.length > page.limit && last
+			? encodeCursor({ createdAt: last.createdAt, id: last.id }, cursorSecret)
+			: null,
+});
+```
+
+`readPageQuery` answers `{ limit, cursor }`, defaults to 50 rows, and refuses
+bad input the way the rest of the input boundary does: 400 `INVALID_INPUT` for a
+limit outside 1 to the endpoint's `maxLimit`, 400 `CURSOR_INVALID` for a cursor
+that is too long or not cursor-shaped. The platform ceiling is 200 rows; an
+endpoint narrows it with `maxLimit` and picks its own `defaultLimit`.
+
+A cursor is the keyset of the last row of the page, HMAC signed with a 32 byte
+secret the module owns and bounded to 1 KB, so a caller cannot move the page
+boundary onto a row the query excludes. `decodeCursor` answers the same
+`CURSOR_INVALID` for a forged, edited or retired cursor, which a client treats
+as "start from the first page". Put nothing in a cursor but the ordering keys:
+it is a position, not saved state.
+
+The response body is `{ items, page: { nextCursor, limit, total? } }`.
+`nextCursor` is null on the last page, and `total` belongs in the body only
+where the count is cheap, which a count over a tenant's rows usually is not.
+`keysetWhere(columns, cursorValues, { direction, parameterOffset })` builds
+`(created_at < $2 OR (created_at = $2 AND id < $3))` with the values bound and
+the column names checked as plain identifiers; the statement's `ORDER BY` must
+match the columns and direction, ending in a unique column, and the table needs
+an index on them. Offset paging is not a platform capability: `OFFSET` over a
+tenant's rows gets slower with every page and drops rows that move.
+Record history keeps its own narrower request contract, `parseHistoryRequest`
+from `@flowdular/sdk/kernel`.
+
+## Search providers
+
+A module that owns searchable records registers a provider with `search.core`
+instead of feeding a central index. Declare `search.core` under `dependencies`
+so it composes first, add `{ id: "search.providers.v1", optional: true }` under
+`requires`, and register in `createServerComposition`:
+
+```ts
+context.capabilities
+	.get<SearchProviderRegistry>(SEARCH_PROVIDERS_CAPABILITY)
+	?.register('users.core', [createMemberSearchProvider(context.auth)]);
+```
+
+A provider is `{ key, label, permission, search(input) }`. `search` receives
+`{ tenantId, principal, query, limit, cursor?, signal? }` and answers
+`{ hits, nextCursor }`, where a hit carries only `ref`, `title`, `snippet`,
+`viewId`, `route` and `score`: search.core never opens the provider's tables and
+never fetches the record. The `route` is workspace-relative and starts with `/`;
+`score` orders hits inside one provider and is never compared across providers.
+The query is normalized and bounded to 200 characters before a provider sees it,
+and a query under two characters reaches nobody.
+
+`search.core` runs every provider whose `permission` the principal holds in
+parallel under `providerTimeoutMs`, merges provider-major, and pages the merged
+stream with the platform cursor helpers. A provider that fails, times out, or
+answers something unreadable contributes nothing and is named in the response's
+`unavailable`; it never turns the member's search into an error. The registry is
+sealed when search.core starts, so registration happens at composition and never
+at request time. The capability stays optional: resolve it with `get`, register
+behind `?.`, and the module still composes where search.core is not enabled.
+
 ## Adding a CLI command
 
 Module commands live in `src/cli/commands.json` and `src/cli/index.ts`,