create-flowdular 0.1.0

package/template/default/flowdular.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "./node_modules/@flowdular/contracts/schemas/project.schema.json",
+	"schemaVersion": 1,
+	"architectureVersion": "0.2.0",
+	"specs": {
+		"platformRoot": "specs",
+		"moduleDirectory": "spec"
+	},
+	"modules": {
+		"roots": ["modules"],
+		"enabled": ["system.core", "auth.core", "example.core"]
+	},
+	"locales": ["en", "pl"]
+}

package/template/default/modules/example/migrations/0001_example_core.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS example_notes;

package/template/default/modules/example/migrations/0001_example_core.up.sql

@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS example_notes (
+  tenant_id TEXT NOT NULL,
+  id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  body TEXT NOT NULL,
+  created_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, id)
+);
+CREATE INDEX IF NOT EXISTS example_notes_tenant_created_idx ON example_notes (tenant_id, created_at DESC);
+ALTER TABLE example_notes ENABLE ROW LEVEL SECURITY;
+ALTER TABLE example_notes FORCE ROW LEVEL SECURITY;
+CREATE POLICY example_notes_tenant_policy ON example_notes
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/template/default/modules/example/module.json

@@ -0,0 +1,22 @@
+{
+	"$schema": "../../node_modules/@flowdular/contracts/schemas/module.schema.json",
+	"schemaVersion": 1,
+	"id": "example.core",
+	"package": "@app/module-example",
+	"version": "0.1.0",
+	"profile": "full",
+	"capabilities": ["api", "database", "client", "translations"],
+	"platform": {
+		"server": true,
+		"client": true
+	},
+	"dependencies": [
+		{
+			"id": "auth.core",
+			"range": "0.10.0"
+		}
+	],
+	"tenancy": "required",
+	"locales": ["en", "pl"],
+	"stability": "experimental"
+}

package/template/default/modules/example/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@app/module-example",
+	"version": "0.1.0",
+	"private": true,
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client/index.ts",
+		"./server": "./src/server/index.ts",
+		"./platform": "./src/platform.ts"
+	},
+	"scripts": {
+		"typecheck": "tsrx-tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"octane": "0.1.51",
+		"segment-state": "0.2.0",
+		"@flowdular/sdk": "0.1.0"
+	},
+	"devDependencies": {
+		"@tsrx/typescript-plugin": "0.3.120",
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.10"
+	}
+}

package/template/default/modules/example/spec/module.yaml

@@ -0,0 +1,43 @@
+schemaVersion: 1
+id: example.core
+specVersion: 0.1.0
+status: approved
+name: Example Notes
+description: A minimal tenant-scoped record module to copy when you build your first real module.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+dependencies:
+  - id: auth.core
+    range: 0.10.0
+tenancy: required
+locales:
+  - en
+  - pl
+invariants:
+  - Persistence runs on the shared asynchronous database contract. The module receives a leased handle from platform composition, never a driver or a connection string, and provides explicit SQL for every dialect it declares.
+  - The PostgreSQL notes table enables and forces row-level security with USING and WITH CHECK policies bound to transaction-local coreloom.tenant_id, and the runtime role holds neither SUPERUSER nor BYPASSRLS. Migrations use a separate lease.
+  - Every note is owned by exactly one tenant and every query uses the trusted tenant identifier.
+permissions:
+  - id: example.notes.read
+    description: Read notes in the active tenant.
+  - id: example.notes.manage
+    description: Create notes in the active tenant.
+dataOwnership:
+  - example.core owns note identity, title, body, and creation time.
+acceptanceScenarios:
+  - id: EXAMPLE-LIST
+    given: Notes exist in more than one tenant.
+    when: An authorized principal lists notes.
+    then: Only notes owned by the active tenant are returned, newest first.
+  - id: EXAMPLE-CREATE
+    given: An authorized principal supplies a title and a body.
+    when: The note is created.
+    then: A tenant-owned note is persisted and returned with its creation time.
+  - id: EXAMPLE-DENY
+    given: A principal is unauthenticated or lacks the required example permission.
+    when: The principal reads or creates a note.
+    then: The server denies the operation before repository access.

package/template/default/modules/example/src/acl/permissions.ts

@@ -0,0 +1,6 @@
+export const EXAMPLE_PERMISSIONS = {
+	read: 'example.notes.read',
+	manage: 'example.notes.manage',
+} as const;
+
+export const permissions = Object.freeze(Object.values(EXAMPLE_PERMISSIONS));

package/template/default/modules/example/src/api/endpoints.ts

@@ -0,0 +1,81 @@
+import {
+	defineEndpoint,
+	jsonResponse,
+	problemResponse,
+	readJsonObject,
+	requiredString,
+} from '@flowdular/sdk/server';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import {
+	endpointIdentityFromContext,
+	principalFromContext,
+	sessionMutationDenial,
+} from '@flowdular/sdk/modules/auth/server';
+import { EXAMPLE_PERMISSIONS } from '../acl/permissions.ts';
+import { NoteServiceError } from '../services/note-service.ts';
+import type { ExampleRuntime } from '../server/runtime.ts';
+
+function failure(error: unknown): Response {
+	if (error instanceof NoteServiceError) {
+		return jsonResponse(
+			{ error: { code: error.code, message: error.message } },
+			error.status,
+		);
+	}
+	return problemResponse(error, 'The example operation failed.');
+}
+
+export function createExampleRoutes(
+	auth: AuthRuntime,
+	runtime: ExampleRuntime,
+) {
+	const list = defineEndpoint({
+		id: 'example.notes.list',
+		path: '/api/example/notes',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: EXAMPLE_PERMISSIONS.read },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				const principal = principalFromContext(octane)!;
+				const service = await runtime.service();
+				return jsonResponse({ notes: await service.list(principal.tenantId) });
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+	const create = defineEndpoint({
+		id: 'example.notes.create',
+		path: '/api/example/notes',
+		methods: ['POST'],
+		access: { kind: 'permission', permission: EXAMPLE_PERMISSIONS.manage },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			const denial = sessionMutationDenial(octane, auth);
+			if (denial) return denial;
+			try {
+				const value = await readJsonObject(octane.request);
+				const principal = principalFromContext(octane)!;
+				const service = await runtime.service();
+				return jsonResponse(
+					{
+						note: await service.create(principal.tenantId, {
+							title: requiredString(value, 'title', { min: 1, max: 120 }),
+							body: requiredString(value, 'body', { min: 1, max: 4_000 }),
+						}),
+					},
+					201,
+				);
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+	return [list.serverRoute, create.serverRoute] as const;
+}
+
+export const endpoints = [
+	'example.notes.list',
+	'example.notes.create',
+] as const;

package/template/default/modules/example/src/client/NotesView.tsrx

@@ -0,0 +1,236 @@
+import { useEffect, useMemo } from 'octane';
+import {
+	Alert,
+	Button,
+	Drawer,
+	FormField,
+	Icon,
+	PageHeader,
+	SearchField,
+	TableCard,
+	type TableColumn,
+} from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client';
+import { useValue } from 'segment-state';
+import type { Note } from '../domain/types.ts';
+import { createNote, loadNotes } from './api.ts';
+import { createExampleClientState } from './state.ts';
+
+export interface NotesViewProps {
+	readonly csrfToken: string;
+	readonly canManage: boolean;
+}
+
+function formValue(form: FormData, key: string): string {
+	const value = form.get(key);
+	return typeof value === 'string' ? value : '';
+}
+
+function columns(): readonly TableColumn<Note>[] {
+	return [
+		{
+			key: 'note',
+			header: t('example.table.column.note'),
+			width: '70%',
+			cell: (note) => <span class="ui-cell">
+				<b>{note.title}</b>
+				<span class="ui-cell__muted">{note.body}</span>
+			</span>,
+		},
+		{
+			key: 'created',
+			header: t('example.table.column.created'),
+			width: '30%',
+			cell: (note) => new Intl.DateTimeFormat(activeLocale(), {
+				dateStyle: 'medium',
+				timeStyle: 'short',
+			}).format(new Date(note.createdAt)),
+		},
+	];
+}
+
+export function NotesView(props: NotesViewProps) @{
+	const exampleState = useMemo(() => createExampleClientState(), []);
+	const [notes] = useValue(exampleState.state.notes);
+	const [status, setStatus] = useValue(exampleState.state.status);
+	const [error, setError] = useValue(exampleState.state.error);
+	const [query, setQuery] = useValue(exampleState.state.query);
+	const [formOpen, setFormOpen] = useValue(exampleState.state.formOpen);
+	const [formSession, setFormSession] = useValue(
+		exampleState.state.formSession,
+	);
+	const locale = activeLocale();
+	const term = query.trim().toLocaleLowerCase(locale);
+	const visible = notes.filter(
+		(note) =>
+			term === '' || note.title.toLocaleLowerCase(locale).includes(term),
+	);
+
+	const refresh = async () => {
+		setStatus('loading');
+		setError('');
+		try {
+			const records = await loadNotes();
+			exampleState.store.act(
+				(transaction) => transaction.set(exampleState.state.notes, records),
+				'example/loaded',
+			);
+		} catch (loadError) {
+			setError(
+				loadError instanceof Error
+					? loadError.message
+					: t('example.error.load'),
+			);
+		} finally {
+			setStatus('idle');
+		}
+	};
+
+	useEffect(() => {
+		void refresh();
+	}, []);
+
+	const openForm = () => {
+		setError('');
+		setFormSession((current) => current + 1);
+		setFormOpen(true);
+	};
+
+	const closeForm = () => {
+		setFormOpen(false);
+		setError('');
+	};
+
+	const submit = async (event: SubmitEvent) => {
+		event.preventDefault();
+		const form = new FormData(event.currentTarget as HTMLFormElement);
+		setStatus('submitting');
+		setError('');
+		try {
+			const note = await createNote(
+				{ title: formValue(form, 'title'), body: formValue(form, 'body') },
+				props.csrfToken,
+			);
+			exampleState.store.act(
+				(transaction) => transaction.set(exampleState.state.notes, [
+					note,
+					...notes,
+				]),
+				'example/created',
+			);
+			closeForm();
+		} catch (saveError) {
+			setError(
+				saveError instanceof Error
+					? saveError.message
+					: t('example.error.create'),
+			);
+		} finally {
+			setStatus('idle');
+		}
+	};
+
+	<div class="ui-view">
+		<PageHeader
+			eyebrow={t('example.page.eyebrow')}
+			title={t('example.page.title')}
+			description={t('example.page.description')}
+		>
+			<Button size="sm" onClick={() => void refresh()}>
+				<Icon name="refresh" size={14} />
+				{t('example.page.action.refresh')}
+			</Button>
+			@if (props.canManage) {
+				<Button size="sm" variant="primary" onClick={openForm}>
+					<Icon name="plus" size={14} />
+					{t('example.page.action.new')}
+				</Button>
+			}
+		</PageHeader>
+		@if (error && !formOpen) {
+			<Alert>{error}</Alert>
+		}
+		<TableCard
+			title={t('example.table.title')}
+			count={t(
+				notes.length === 1
+					? 'example.table.count.one'
+					: 'example.table.count.other',
+				{ count: notes.length },
+			)}
+			search={<SearchField
+				value={query}
+				placeholder={t('example.table.search.placeholder')}
+				label={t('example.table.search.label')}
+				onInput={setQuery}
+			/>}
+			caption={t('example.table.caption')}
+			columns={columns()}
+			rows={visible}
+			rowKey={(note) => note.id}
+			status={status === 'loading' && notes.length === 0 ? 'loading' : 'idle'}
+			loadingLabel={t('example.table.loading')}
+			filtered={term !== ''}
+			empty={{
+				icon: 'file-text',
+				title: t('example.table.empty.title'),
+				hint: t('example.table.empty.hint'),
+			}}
+			emptyFiltered={{
+				icon: 'file-text',
+				title: t('example.table.emptyFiltered.title'),
+				hint: t('example.table.emptyFiltered.hint'),
+			}}
+			note={t('example.table.note')}
+		/>
+		<Drawer
+			open={formOpen}
+			title={t('example.drawer.title')}
+			subtitle={t('example.drawer.subtitle')}
+			onClose={closeForm}
+		>
+			<form
+				class="ui-drawer__form"
+				key={'example-form-' + formSession}
+				onSubmit={submit}
+			>
+				<div class="ui-drawer__body">
+					@if (error) {
+						<Alert>{error}</Alert>
+					}
+					<FormField label={t('example.field.title')}>
+						<input
+							class="ui-input"
+							id="title"
+							name="title"
+							required
+							maxLength={120}
+						/>
+					</FormField>
+					<FormField
+						label={t('example.field.body')}
+						help={t('example.field.body.help')}
+					>
+						<textarea
+							class="ui-textarea"
+							id="body"
+							required
+							rows={6}
+							maxLength={4000}
+						></textarea>
+					</FormField>
+				</div>
+				<div class="ui-drawer__foot">
+					<Button type="button" onClick={closeForm}>{t(
+						'example.drawer.cancel',
+					)}</Button>
+					<Button
+						type="submit"
+						variant="primary"
+						disabled={status === 'submitting'}
+					>{t('example.drawer.save')}</Button>
+				</div>
+			</form>
+		</Drawer>
+	</div>
+}

package/template/default/modules/example/src/client/api.ts

@@ -0,0 +1,38 @@
+import { t } from '@flowdular/sdk/client/i18n';
+import type { CreateNoteInput, Note } from '../domain/types.ts';
+
+interface ErrorEnvelope {
+	readonly error?: { readonly message?: string };
+}
+
+async function payload<T>(response: Response): Promise<T> {
+	const value = (await response.json()) as T & ErrorEnvelope;
+	if (!response.ok) {
+		throw new Error(value.error?.message ?? t('example.error.request'));
+	}
+	return value;
+}
+
+export async function loadNotes(): Promise<readonly Note[]> {
+	const response = await fetch('/api/example/notes', {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	return (await payload<{ readonly notes: readonly Note[] }>(response)).notes;
+}
+
+export async function createNote(
+	input: CreateNoteInput,
+	csrfToken: string,
+): Promise<Note> {
+	const response = await fetch('/api/example/notes', {
+		method: 'POST',
+		headers: {
+			'content-type': 'application/json',
+			'x-csrf-token': csrfToken,
+		},
+		credentials: 'same-origin',
+		body: JSON.stringify(input),
+	});
+	return (await payload<{ readonly note: Note }>(response)).note;
+}

package/template/default/modules/example/src/client/contribution.tsrx

@@ -0,0 +1,52 @@
+import type { ModuleClientContribution } from '@flowdular/sdk/client';
+import { EXAMPLE_PERMISSIONS } from '../acl/permissions.ts';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import { NotesView } from './NotesView.tsrx';
+import {
+	exampleNavigationDescription,
+	exampleNavigationLabel,
+} from './navigation-copy.ts';
+
+export interface ExampleClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+}
+
+export function createExampleClientContribution(
+	options: ExampleClientContributionOptions,
+): ModuleClientContribution {
+	return {
+		moduleId: 'example.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: [
+			{
+				id: 'example.navigation',
+				viewId: 'example',
+				group: 'Operations',
+				/* The shell registers this contribution's bundles after the factory
+   returns. Getters resolve copy only when the shell reads navigation,
+   after registration, and again when the active locale changes. */
+				get label() {
+					return exampleNavigationLabel();
+				},
+				glyph: 'file-text',
+				get description() {
+					return exampleNavigationDescription();
+				},
+				scope: EXAMPLE_PERMISSIONS.read,
+				order: 20,
+			},
+		],
+		views: [
+			{
+				id: 'example',
+				render: () =>
+					<NotesView
+						csrfToken={options.csrfToken}
+						canManage={options.scopes.includes(EXAMPLE_PERMISSIONS.manage)}
+					/>,
+			},
+		],
+	};
+}

package/template/default/modules/example/src/client/index.ts

@@ -0,0 +1,18 @@
+export { createExampleClientContribution } from './contribution.tsrx';
+export type { ExampleClientContributionOptions } from './contribution.tsrx';
+export { NotesView } from './NotesView.tsrx';
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createExampleClientContribution as canonicalContribution } from './contribution.tsrx';
+
+/* Canonical entry used by the generated platform composition. */
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({
+		csrfToken: context.csrfToken,
+		scopes: context.scopes,
+	});
+}

package/template/default/modules/example/src/client/navigation-copy.ts

@@ -0,0 +1,9 @@
+import { t } from '@flowdular/sdk/client/i18n';
+
+export function exampleNavigationLabel(): string {
+	return t('example.nav.label');
+}
+
+export function exampleNavigationDescription(): string {
+	return t('example.nav.description');
+}

package/template/default/modules/example/src/client/state.ts

@@ -0,0 +1,14 @@
+import { cell, createStore } from 'segment-state';
+import type { Note } from '../domain/types.ts';
+
+export function createExampleClientState() {
+	const store = createStore({
+		notes: cell<readonly Note[]>([]),
+		query: '',
+		formOpen: false,
+		status: cell<'idle' | 'loading' | 'submitting'>('idle'),
+		error: '',
+		formSession: 0,
+	});
+	return { store, state: store.state };
+}

package/template/default/modules/example/src/domain/types.ts

@@ -0,0 +1,12 @@
+export interface Note {
+	readonly tenantId: string;
+	readonly id: string;
+	readonly title: string;
+	readonly body: string;
+	readonly createdAt: number;
+}
+
+export interface CreateNoteInput {
+	readonly title: string;
+	readonly body: string;
+}

package/template/default/modules/example/src/index.ts

@@ -0,0 +1,24 @@
+import type {
+	ModuleManifest,
+	RegisteredModule,
+} from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { EXAMPLE_PERMISSIONS } from './acl/permissions.ts';
+
+export const moduleDefinition = {
+	manifest: manifest as ModuleManifest,
+	navigation: [
+		{
+			id: 'example.navigation',
+			label: 'Notes',
+			href: '/example',
+			order: 20,
+			permission: EXAMPLE_PERMISSIONS.read,
+		},
+	],
+	permissions: Object.values(EXAMPLE_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export { EXAMPLE_PERMISSIONS } from './acl/permissions.ts';
+export { NoteService, NoteServiceError } from './services/note-service.ts';
+export type { CreateNoteInput, Note } from './domain/types.ts';

package/template/default/modules/example/src/platform.ts

@@ -0,0 +1,23 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import { createExampleRoutes, createExampleRuntime } from './server/index.ts';
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	const runtime = createExampleRuntime({
+		databases: context.databases,
+		purpose:
+			context.environment.NODE_ENV === 'test'
+				? 'test'
+				: context.environment.NODE_ENV === 'production'
+					? 'runtime'
+					: 'preview',
+	});
+	return {
+		routes: createExampleRoutes(context.auth, runtime),
+		dispose: () => runtime.dispose(),
+	};
+}

package/template/default/modules/example/src/server/index.ts

@@ -0,0 +1,3 @@
+export { createExampleRoutes } from '../api/endpoints.ts';
+export { createExampleRuntime } from './runtime.ts';
+export type { ExampleRuntime, ExampleRuntimeOptions } from './runtime.ts';