create-flowdular 0.1.0

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

@@ -0,0 +1,84 @@
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+	DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+} from '@flowdular/sdk/database';
+import {
+	DatabaseNoteRepository,
+	migrateExampleDatabase,
+} from '../services/database-repository.ts';
+import { NoteService } from '../services/note-service.ts';
+
+export interface ExampleRuntimeOptions {
+	readonly databases: DatabaseProvider;
+	readonly purpose: Exclude<DatabaseProviderRequest['purpose'], 'migration'>;
+}
+
+export interface ExampleRuntime {
+	service(): Promise<NoteService>;
+	dispose(): Promise<void>;
+}
+
+export function createExampleRuntime(
+	options: ExampleRuntimeOptions,
+): ExampleRuntime {
+	let disposed = false;
+	let runtimeLeasePromise: Promise<DatabaseAdapterLease> | undefined;
+	let servicePromise: Promise<NoteService> | undefined;
+
+	const initialize = async (): Promise<NoteService> => {
+		const migrationLease = await options.databases.acquire({
+			namespace: 'example.core',
+			purpose: 'migration',
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+					DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+					DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+				],
+			},
+		});
+		try {
+			await migrateExampleDatabase(migrationLease.database);
+		} finally {
+			await migrationLease.release();
+		}
+		runtimeLeasePromise = options.databases.acquire({
+			namespace: 'example.core',
+			purpose: options.purpose,
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [DATABASE_CAPABILITY_IDS.TRANSACTIONS],
+			},
+		});
+		const lease = await runtimeLeasePromise;
+		return new NoteService(new DatabaseNoteRepository(lease.database));
+	};
+
+	return {
+		service: () => {
+			if (disposed) {
+				return Promise.reject(new Error('Example runtime is disposed.'));
+			}
+			servicePromise ??= initialize();
+			return servicePromise;
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (!runtimeLeasePromise) {
+				await servicePromise?.catch(() => undefined);
+			}
+			if (!runtimeLeasePromise) return;
+			const lease = await runtimeLeasePromise;
+			await lease.release();
+			runtimeLeasePromise = undefined;
+			servicePromise = undefined;
+		},
+	};
+}

package/template/default/modules/example/src/services/database-repository.ts

@@ -0,0 +1,82 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import { runDatabaseMigrations } from '@flowdular/sdk/database';
+import type { Note } from '../domain/types.ts';
+import { databaseMigrations } from './migration.ts';
+import type { NoteRepository } from './repository.ts';
+
+interface NoteRow {
+	tenant_id: string;
+	id: string;
+	title: string;
+	body: string;
+	created_at: number | bigint | string;
+}
+
+/* Queries stay explicit. Note data never passes through a SQL rewriter, and
+   values always use the adapter's parameter channel. */
+const LIST = `SELECT tenant_id, id, title, body, created_at
+			 FROM example_notes
+			 WHERE tenant_id = $1
+			 ORDER BY created_at DESC, id ASC`;
+
+const CREATE = `INSERT INTO example_notes
+			 (tenant_id, id, title, body, created_at)
+			 VALUES ($1, $2, $3, $4, $5)`;
+
+/* PostgreSQL returns BIGINT as a string, so every numeric read is normalized
+   before it reaches the domain. */
+function integer(value: NoteRow['created_at']): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized) || normalized < 0) {
+		throw new Error('The example database returned an invalid timestamp.');
+	}
+	return normalized;
+}
+
+function fromRow(row: NoteRow): Note {
+	return {
+		tenantId: row.tenant_id,
+		id: row.id,
+		title: row.title,
+		body: row.body,
+		createdAt: integer(row.created_at),
+	};
+}
+
+/** A repository over a platform-owned PostgreSQL handle. */
+export class DatabaseNoteRepository implements NoteRepository {
+	constructor(private readonly database: DatabaseHandle) {}
+
+	async list(tenantId: string): Promise<readonly Note[]> {
+		const result = await this.database.transaction(
+			(transaction) =>
+				transaction.query<NoteRow>({ text: LIST, parameters: [tenantId] }),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(fromRow);
+	}
+
+	async create(note: Note): Promise<Note> {
+		await this.database.transaction(
+			(transaction) =>
+				transaction.execute({
+					text: CREATE,
+					parameters: [
+						note.tenantId,
+						note.id,
+						note.title,
+						note.body,
+						note.createdAt,
+					],
+				}),
+			{ access: 'write', tenantId: note.tenantId },
+		);
+		return note;
+	}
+}
+
+export async function migrateExampleDatabase(
+	database: DatabaseHandle,
+): Promise<void> {
+	await runDatabaseMigrations(database, 'example.core', databaseMigrations);
+}

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

@@ -0,0 +1,6 @@
+export { NoteService, NoteServiceError } from './note-service.ts';
+export type { NoteRepository } from './repository.ts';
+export {
+	DatabaseNoteRepository,
+	migrateExampleDatabase,
+} from './database-repository.ts';

package/template/default/modules/example/src/services/migration.ts

@@ -0,0 +1,35 @@
+import type { DatabaseMigration } from '@flowdular/sdk/database';
+import { postgresTenantTableState } from '@flowdular/sdk/database';
+
+/* Every constant mirrors its migrations/<id>.up.sql file byte for byte;
+   tests/migrations.test.ts fails on drift. */
+
+export const EXAMPLE_MIGRATION_001 = `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));
+`;
+
+export const databaseMigrations: readonly DatabaseMigration[] = [
+	{
+		id: '0001_example_core',
+		sql: { postgresql: EXAMPLE_MIGRATION_001 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'example_notes',
+				'example_notes_tenant_policy',
+				[() => database.schema.hasIndex('example_notes_tenant_created_idx')],
+			),
+	},
+];

package/template/default/modules/example/src/services/note-service.ts

@@ -0,0 +1,54 @@
+import { randomUUID } from 'node:crypto';
+import type { CreateNoteInput, Note } from '../domain/types.ts';
+import type { NoteRepository } from './repository.ts';
+
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f-\u009f]/u;
+
+export class NoteServiceError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'NoteServiceError';
+	}
+}
+
+function text(value: string, field: string, max: number): string {
+	if (typeof value !== 'string' || CONTROL_CHARACTER_PATTERN.test(value)) {
+		throw new NoteServiceError(
+			'INVALID_INPUT',
+			`${field} must not contain control characters.`,
+		);
+	}
+	const normalized = value.trim();
+	if (normalized.length < 1 || normalized.length > max) {
+		throw new NoteServiceError(
+			'INVALID_INPUT',
+			`${field} must contain between 1 and ${String(max)} characters.`,
+		);
+	}
+	return normalized;
+}
+
+export class NoteService {
+	constructor(
+		private readonly repository: NoteRepository,
+		private readonly now: () => number = () => Date.now(),
+	) {}
+
+	list(tenantId: string): Promise<readonly Note[]> {
+		return this.repository.list(tenantId);
+	}
+
+	create(tenantId: string, input: CreateNoteInput): Promise<Note> {
+		return this.repository.create({
+			tenantId,
+			id: randomUUID(),
+			title: text(input.title, 'title', 120),
+			body: text(input.body, 'body', 4_000),
+			createdAt: this.now(),
+		});
+	}
+}

package/template/default/modules/example/src/services/repository.ts

@@ -0,0 +1,7 @@
+import type { Note } from '../domain/types.ts';
+
+/** The database-agnostic business port. No driver type crosses it. */
+export interface NoteRepository {
+	list(tenantId: string): Promise<readonly Note[]>;
+	create(note: Note): Promise<Note>;
+}

package/template/default/modules/example/tests/module.test.ts

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import manifest from '../module.json' with { type: 'json' };
+import translationsEn from '../translations/en.json' with { type: 'json' };
+import translationsPl from '../translations/pl.json' with { type: 'json' };
+import { EXAMPLE_PERMISSIONS, permissions } from '../src/acl/permissions.ts';
+import { endpoints } from '../src/api/endpoints.ts';
+import { databaseMigrations } from '../src/services/migration.ts';
+
+const migrationDirectory = new URL('../migrations/', import.meta.url);
+
+describe('example.core manifest', () => {
+	it('declares the identifier the platform composes', () => {
+		expect(manifest.id).toBe('example.core');
+		expect(manifest.package).toBe('@app/module-example');
+		expect(manifest.tenancy).toBe('required');
+	});
+
+	it('declares one permission per action the API enforces', () => {
+		expect([...permissions]).toEqual([
+			'example.notes.read',
+			'example.notes.manage',
+		]);
+		expect(EXAMPLE_PERMISSIONS.read).toBe('example.notes.read');
+		expect(endpoints).toEqual(['example.notes.list', 'example.notes.create']);
+	});
+});
+
+describe('example.core translations', () => {
+	it('ships the same key set in every declared locale', () => {
+		expect(Object.keys(translationsPl).sort()).toEqual(
+			Object.keys(translationsEn).sort(),
+		);
+		expect(manifest.locales).toEqual(['en', 'pl']);
+	});
+
+	it('never ships an empty string', () => {
+		for (const bundle of [translationsEn, translationsPl]) {
+			for (const [key, value] of Object.entries(bundle)) {
+				expect(value.trim(), key).not.toBe('');
+			}
+		}
+	});
+});
+
+describe('example.core migrations', () => {
+	it('mirrors every PostgreSQL up file byte for byte', () => {
+		for (const migration of databaseMigrations) {
+			expect(migration.sql.postgresql).toBe(
+				readFileSync(
+					new URL(`${migration.id}.up.sql`, migrationDirectory),
+					'utf8',
+				),
+			);
+		}
+	});
+
+	it('declares forced row security for every tenant table', () => {
+		for (const migration of databaseMigrations) {
+			const sql = migration.sql.postgresql ?? '';
+			expect(sql).toContain('ENABLE ROW LEVEL SECURITY');
+			expect(sql).toContain('FORCE ROW LEVEL SECURITY');
+			expect(sql).toContain("current_setting('coreloom.tenant_id', true)");
+			expect(sql).toContain('WITH CHECK');
+		}
+	});
+});

package/template/default/modules/example/tests/notes.test.ts

@@ -0,0 +1,83 @@
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
+import { NoteService, NoteServiceError } from '../src/services/note-service.ts';
+import {
+	closeExampleTestDatabases,
+	createExampleTestDatabase,
+	type ExampleTestDatabase,
+} from './support/database.ts';
+
+const databases = new Set<ExampleTestDatabase>();
+
+afterEach(async () => {
+	await Promise.all([...databases].map((database) => database.dispose()));
+	databases.clear();
+});
+
+afterAll(closeExampleTestDatabases);
+
+async function fixture(): Promise<ExampleTestDatabase> {
+	const database = await createExampleTestDatabase();
+	databases.add(database);
+	return database;
+}
+
+describe('example notes', () => {
+	it('lists only the notes the active tenant owns', async () => {
+		const service = new NoteService((await fixture()).repository);
+		await service.create('tenant-a', { title: 'A', body: 'Owned by A' });
+		await service.create('tenant-b', { title: 'B', body: 'Owned by B' });
+
+		expect((await service.list('tenant-a')).map((note) => note.title)).toEqual([
+			'A',
+		]);
+		expect((await service.list('tenant-b')).map((note) => note.title)).toEqual([
+			'B',
+		]);
+	});
+
+	it('normalizes the BIGINT timestamp PostgreSQL returns as a string', async () => {
+		const service = new NoteService((await fixture()).repository);
+		const created = await service.create('tenant-a', {
+			title: 'Timestamps',
+			body: 'One note',
+		});
+
+		const [read] = await service.list('tenant-a');
+		expect(read?.createdAt).toBe(created.createdAt);
+		expect(typeof read?.createdAt).toBe('number');
+	});
+
+	it('returns the newest note first', async () => {
+		let clock = 1_000;
+		const service = new NoteService(
+			(await fixture()).repository,
+			() => (clock += 1_000),
+		);
+		await service.create('tenant-a', { title: 'First', body: 'x' });
+		await service.create('tenant-a', { title: 'Second', body: 'y' });
+
+		expect((await service.list('tenant-a')).map((note) => note.title)).toEqual([
+			'Second',
+			'First',
+		]);
+	});
+
+	it('refuses a query that carries no tenant context', async () => {
+		const database = await fixture();
+
+		await expect(
+			database.runtime.query({ text: 'SELECT 1 FROM example_notes' }),
+		).rejects.toMatchObject({ code: 'TENANT_CONTEXT_REQUIRED' });
+	});
+
+	it('rejects an empty title and a title longer than the column allows', async () => {
+		const service = new NoteService((await fixture()).repository);
+
+		await expect(async () =>
+			service.create('tenant-a', { title: '   ', body: 'x' }),
+		).rejects.toBeInstanceOf(NoteServiceError);
+		await expect(async () =>
+			service.create('tenant-a', { title: 'x'.repeat(121), body: 'x' }),
+		).rejects.toBeInstanceOf(NoteServiceError);
+	});
+});

package/template/default/modules/example/tests/support/database.ts

@@ -0,0 +1,69 @@
+import type { DatabaseHandle, DatabaseProvider } from '@flowdular/sdk/database';
+import { createPgliteTestProvider } from '@flowdular/sdk/database-testing';
+import {
+	DatabaseNoteRepository,
+	migrateExampleDatabase,
+} from '../../src/services/database-repository.ts';
+
+export interface ExampleTestDatabase {
+	readonly provider: DatabaseProvider;
+	readonly runtime: DatabaseHandle;
+	readonly repository: DatabaseNoteRepository;
+	dispose(): Promise<void>;
+}
+
+/* Booting an embedded PostgreSQL costs about two seconds, so a test file shares
+   one migrated cluster and every fixture starts from truncated tables instead.
+   Call closeExampleTestDatabases() from the file's afterAll. */
+let shared: Promise<DatabaseProvider> | undefined;
+
+/** The file's migrated provider, with every example table emptied. */
+export async function exampleTestProvider(): Promise<DatabaseProvider> {
+	shared ??= (async () => {
+		const provider = createPgliteTestProvider();
+		const lease = await provider.acquire({
+			namespace: 'example.core',
+			purpose: 'migration',
+		});
+		try {
+			await migrateExampleDatabase(lease.database);
+		} finally {
+			await lease.release();
+		}
+		return provider;
+	})();
+	const provider = await shared;
+	const migration = await provider.acquire({
+		namespace: 'example.core',
+		purpose: 'migration',
+	});
+	try {
+		await migration.database.execute({
+			text: 'TRUNCATE example_notes RESTART IDENTITY CASCADE',
+		});
+	} finally {
+		await migration.release();
+	}
+	return provider;
+}
+
+/** An empty example database with a tenant-scoped runtime handle. */
+export async function createExampleTestDatabase(): Promise<ExampleTestDatabase> {
+	const provider = await exampleTestProvider();
+	const lease = await provider.acquire({
+		namespace: 'example.core',
+		purpose: 'test',
+	});
+	return {
+		provider,
+		runtime: lease.database,
+		repository: new DatabaseNoteRepository(lease.database),
+		dispose: () => lease.release(),
+	};
+}
+
+export async function closeExampleTestDatabases(): Promise<void> {
+	const provider = shared;
+	shared = undefined;
+	if (provider) await (await provider).dispose();
+}

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

@@ -0,0 +1,34 @@
+{
+	"module.name": "Example Notes",
+	"nav.label": "Notes",
+	"nav.description": "Tenant-scoped notes",
+	"page.eyebrow": "Example",
+	"page.title": "Notes",
+	"page.description": "A tenant-scoped record screen to copy when you build your first module.",
+	"page.action.refresh": "Refresh",
+	"page.action.new": "New note",
+	"table.title": "Notes",
+	"table.count.one": "{count} note",
+	"table.count.other": "{count} notes",
+	"table.column.note": "Note",
+	"table.column.created": "Created",
+	"table.search.placeholder": "Search notes",
+	"table.search.label": "Search notes",
+	"table.caption": "Notes owned by the active workspace",
+	"table.loading": "Loading notes",
+	"table.empty.title": "No notes yet",
+	"table.empty.hint": "Create the first note to see the screen with data.",
+	"table.emptyFiltered.title": "No note matches",
+	"table.emptyFiltered.hint": "Clear the search to see every note.",
+	"table.note": "Notes belong to the active workspace and are never visible to another one.",
+	"drawer.title": "New note",
+	"drawer.subtitle": "Stored in the active workspace",
+	"drawer.cancel": "Cancel",
+	"drawer.save": "Create note",
+	"field.title": "Title",
+	"field.body": "Body",
+	"field.body.help": "Up to 4000 characters.",
+	"error.load": "Could not load notes.",
+	"error.create": "Could not create the note.",
+	"error.request": "The example operation failed."
+}

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

@@ -0,0 +1,34 @@
+{
+	"module.name": "Przykładowe notatki",
+	"nav.label": "Notatki",
+	"nav.description": "Notatki w ramach przestrzeni",
+	"page.eyebrow": "Przykład",
+	"page.title": "Notatki",
+	"page.description": "Ekran rekordów w ramach przestrzeni, od którego zaczniesz swój pierwszy moduł.",
+	"page.action.refresh": "Odśwież",
+	"page.action.new": "Nowa notatka",
+	"table.title": "Notatki",
+	"table.count.one": "{count} notatka",
+	"table.count.other": "{count} notatek",
+	"table.column.note": "Notatka",
+	"table.column.created": "Utworzono",
+	"table.search.placeholder": "Szukaj notatek",
+	"table.search.label": "Szukaj notatek",
+	"table.caption": "Notatki należące do aktywnej przestrzeni",
+	"table.loading": "Wczytywanie notatek",
+	"table.empty.title": "Nie ma jeszcze notatek",
+	"table.empty.hint": "Utwórz pierwszą notatkę, aby zobaczyć ekran z danymi.",
+	"table.emptyFiltered.title": "Brak pasujących notatek",
+	"table.emptyFiltered.hint": "Wyczyść wyszukiwanie, aby zobaczyć wszystkie notatki.",
+	"table.note": "Notatki należą do aktywnej przestrzeni i nigdy nie są widoczne w innej.",
+	"drawer.title": "Nowa notatka",
+	"drawer.subtitle": "Zapisywana w aktywnej przestrzeni",
+	"drawer.cancel": "Anuluj",
+	"drawer.save": "Utwórz notatkę",
+	"field.title": "Tytuł",
+	"field.body": "Treść",
+	"field.body.help": "Do 4000 znaków.",
+	"error.load": "Nie udało się wczytać notatek.",
+	"error.create": "Nie udało się utworzyć notatki.",
+	"error.request": "Operacja przykładowego modułu nie powiodła się."
+}

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

@@ -0,0 +1,14 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"allowImportingTsExtensions": true,
+		"isolatedModules": true,
+		"jsx": "react-jsx",
+		"jsxImportSource": "octane",
+		"plugins": [{ "name": "@tsrx/typescript-plugin" }]
+	},
+	"include": ["src/**/*", "tests/**/*.ts"]
+}

package/template/default/modules/example/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+/* Booting the embedded PostgreSQL a suite runs against takes seconds under
+   parallel load, well past the 5s vitest default. */
+export default defineConfig({
+	test: {
+		testTimeout: 30_000,
+		hookTimeout: 30_000,
+	},
+});

package/template/default/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "flowdular-app",
+	"version": "0.1.0",
+	"private": true,
+	"type": "module",
+	"packageManager": "pnpm@11.17.0",
+	"engines": {
+		"node": ">=22.22.2"
+	},
+	"scripts": {
+		"dev": "node --env-file-if-exists=.env platform/scripts/dev.mjs",
+		"typecheck": "pnpm -r --if-present typecheck",
+		"test": "pnpm -r --if-present test",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"flowdular": "flowdular",
+		"cl": "flowdular",
+		"doctor": "flowdular doctor",
+		"verify": "pnpm typecheck && pnpm test && flowdular module validate && pnpm format:check"
+	},
+	"devDependencies": {
+		"@tsrx/prettier-plugin": "0.3.120",
+		"prettier": "3.6.2",
+		"flowdular": "0.1.0"
+	}
+}

package/template/default/platform/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<meta name="theme-color" content="#141B2E" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<!--ssr-head-->
+	</head>
+	<body>
+		<div id="root"><!--ssr-body--></div>
+	</body>
+</html>