create-flowdular 0.2.4 → 0.2.6

package/agent-template/.ai/references/catalog/src/domain/types.ts

@@ -0,0 +1,32 @@
+export type CatalogItemKind = 'product' | 'service';
+
+export interface CatalogItem {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly sku: string;
+	readonly name: string;
+	readonly kind: CatalogItemKind;
+	readonly unit: string;
+	readonly basePriceMinor: number;
+	readonly currency: string;
+	readonly status: 'active' | 'archived';
+	readonly createdAt: number;
+}
+
+export interface CreateCatalogItemInput {
+	readonly sku: string;
+	readonly name: string;
+	readonly kind: CatalogItemKind;
+	readonly unit: string;
+	readonly basePriceMinor: number;
+	readonly currency: string;
+}
+
+export interface UpdateCatalogItemInput {
+	readonly id: string;
+	readonly name: string;
+	readonly kind: CatalogItemKind;
+	readonly unit: string;
+	readonly basePriceMinor: number;
+	readonly currency: string;
+}

package/agent-template/.ai/references/catalog/src/domain/variables.ts

@@ -0,0 +1,111 @@
+import type { VariableSource } from '@flowdular/sdk/contracts';
+import type {
+	AgentTool,
+	AgentToolContext,
+} from '@flowdular/sdk/harness/runtime';
+import {
+	VariableResolutionError,
+	type PlatformVariableRegistry,
+	type VariableSourceResolutionContext,
+} from '@flowdular/sdk/kernel';
+import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
+import type { CatalogItem } from './types.ts';
+
+export const CATALOG_VARIABLE_SOURCE: VariableSource = {
+	id: 'catalog.items',
+	variables: [
+		{
+			key: 'catalogItem.name',
+			label: 'Catalog item name',
+			kind: 'text',
+			scope: CATALOG_PERMISSIONS.read,
+		},
+		{
+			key: 'catalogItem.sku',
+			label: 'Catalog item SKU',
+			kind: 'identifier',
+			scope: CATALOG_PERMISSIONS.read,
+		},
+		{
+			key: 'catalogItem.priceMinor',
+			label: 'Catalog item price in minor units',
+			kind: 'money',
+			scope: CATALOG_PERMISSIONS.read,
+		},
+		{
+			key: 'catalogItem.currency',
+			label: 'Catalog item currency',
+			kind: 'identifier',
+			scope: CATALOG_PERMISSIONS.read,
+		},
+	],
+};
+
+function toolContext(
+	context: VariableSourceResolutionContext,
+): AgentToolContext {
+	return {
+		runId:
+			context.actor.kind === 'agent'
+				? context.actor.runId!
+				: `variable:${context.actor.kind}:${context.actor.id}`,
+		tenantId: context.tenantId,
+		requestedBy: context.actor.id,
+		permissions: new Set(context.permissionSnapshot),
+		signal: context.signal,
+	};
+}
+
+/* catalog.item.list is the module-owned public read tool. Its exact-id query
+   is bounded before paging, so the resolver never scans or opens catalog.db. */
+export function registerCatalogVariableSource(
+	registry: PlatformVariableRegistry,
+	tools: readonly AgentTool[],
+): void {
+	const list = tools.find((tool) => tool.id === 'catalog.item.list');
+	if (!list || !list.requiredPermissions.includes(CATALOG_PERMISSIONS.read)) {
+		throw new Error(
+			'catalog.item.list must require catalog.items.read before variables can be registered.',
+		);
+	}
+	const requiredBindings = Object.fromEntries(
+		CATALOG_VARIABLE_SOURCE.variables.map((variable) => [
+			variable.key,
+			['catalogItemId'] as const,
+		]),
+	);
+	registry.register(CATALOG_VARIABLE_SOURCE, {
+		requiredBindings,
+		resolve: async (context) => {
+			if (
+				!list.requiredPermissions.every((permission) =>
+					context.permissionSnapshot.includes(permission),
+				)
+			) {
+				throw new VariableResolutionError(
+					'FORBIDDEN_TEMPLATE_VARIABLE',
+					'The variable source is unavailable to this actor.',
+				);
+			}
+			const rows = (await list.execute(
+				{ query: context.bindings.catalogItemId },
+				toolContext(context),
+			)) as readonly CatalogItem[];
+			const item = rows.find(
+				(candidate) => candidate.id === context.bindings.catalogItemId,
+			);
+			if (!item) {
+				throw new VariableResolutionError(
+					'VARIABLE_VALUE_UNAVAILABLE',
+					'A variable value is unavailable.',
+				);
+			}
+			return {
+				'catalogItem.name': item.name,
+				'catalogItem.sku': item.sku,
+				'catalogItem.priceMinor': String(item.basePriceMinor),
+				'catalogItem.currency': item.currency,
+			};
+		},
+	});
+}

package/agent-template/.ai/references/catalog/src/index.ts

@@ -0,0 +1,31 @@
+import type {
+	ModuleManifest,
+	RegisteredModule,
+} from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { CATALOG_PERMISSIONS } from './acl/permissions.ts';
+
+export const moduleDefinition = {
+	manifest: manifest as ModuleManifest,
+	navigation: [
+		{
+			id: 'catalog.navigation',
+			label: 'Catalog',
+			href: '/catalog',
+			order: 20,
+			permission: CATALOG_PERMISSIONS.read,
+		},
+	],
+	permissions: Object.values(CATALOG_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export { CATALOG_PERMISSIONS } from './acl/permissions.ts';
+export {
+	CatalogService,
+	CatalogServiceError,
+} from './services/catalog-service.ts';
+export type {
+	CatalogItem,
+	CatalogItemKind,
+	CreateCatalogItemInput,
+} from './domain/types.ts';

package/agent-template/.ai/references/catalog/src/platform.ts

@@ -0,0 +1,35 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import { platformVariableRegistry } from '@flowdular/sdk/kernel';
+import { registerCatalogVariableSource } from './domain/variables.ts';
+import {
+	catalogAgentTools,
+	createCatalogRoutes,
+	createCatalogRuntime,
+} from './server/index.ts';
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	const runtime = createCatalogRuntime({
+		databases: context.databases,
+		purpose:
+			context.environment.NODE_ENV === 'test'
+				? 'test'
+				: context.environment.NODE_ENV === 'production'
+					? 'runtime'
+					: 'preview',
+	});
+	const tools = catalogAgentTools(runtime);
+	context.agentTools.register(tools);
+	registerCatalogVariableSource(
+		platformVariableRegistry(context.capabilities),
+		tools,
+	);
+	return {
+		routes: createCatalogRoutes(context.auth, runtime),
+		dispose: () => runtime.dispose(),
+	};
+}

package/agent-template/.ai/references/catalog/src/server/index.ts

@@ -0,0 +1,4 @@
+export { catalogAgentTools } from '../agent/tools.ts';
+export { createCatalogRoutes } from '../api/endpoints.ts';
+export { createCatalogRuntime } from './runtime.ts';
+export type { CatalogRuntime, CatalogRuntimeOptions } from './runtime.ts';

package/agent-template/.ai/references/catalog/src/server/runtime.ts

@@ -0,0 +1,86 @@
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+	DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+} from '@flowdular/sdk/database';
+import { CatalogService } from '../services/catalog-service.ts';
+import {
+	DatabaseCatalogRepository,
+	migrateCatalogDatabase,
+} from '../services/database-repository.ts';
+
+export interface CatalogRuntimeOptions {
+	readonly databases: DatabaseProvider;
+	readonly purpose: Exclude<DatabaseProviderRequest['purpose'], 'migration'>;
+}
+
+export interface CatalogRuntime {
+	service(): Promise<CatalogService>;
+	dispose(): Promise<void>;
+}
+
+export function createCatalogRuntime(
+	options: CatalogRuntimeOptions,
+): CatalogRuntime {
+	let disposed = false;
+	let runtimeLeasePromise: Promise<DatabaseAdapterLease> | undefined;
+	let servicePromise: Promise<CatalogService> | undefined;
+
+	const initialize = async (): Promise<CatalogService> => {
+		/* Migrations take their own short lease: the runtime role is tenant
+		   scoped and may not run schema operations. */
+		const migrationLease = await options.databases.acquire({
+			namespace: 'catalog.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 migrateCatalogDatabase(migrationLease.database);
+		} finally {
+			await migrationLease.release();
+		}
+		runtimeLeasePromise = options.databases.acquire({
+			namespace: 'catalog.core',
+			purpose: options.purpose,
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [DATABASE_CAPABILITY_IDS.TRANSACTIONS],
+			},
+		});
+		const lease = await runtimeLeasePromise;
+		return new CatalogService(new DatabaseCatalogRepository(lease.database));
+	};
+
+	return {
+		service: () => {
+			if (disposed) {
+				return Promise.reject(new Error('Catalog 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/agent-template/.ai/references/catalog/src/services/catalog-service.ts

@@ -0,0 +1,306 @@
+import { randomUUID } from 'node:crypto';
+import {
+	normalizeActor,
+	type Actor,
+	type HistoryPage,
+	type HistoryRequest,
+} from '@flowdular/sdk/kernel';
+import type {
+	CatalogItem,
+	CatalogItemKind,
+	CreateCatalogItemInput,
+	UpdateCatalogItemInput,
+} from '../domain/types.ts';
+import { DuplicateSkuError, type CatalogRepository } from './repository.ts';
+import {
+	canonicalDigest,
+	TargetIdempotencyConflictError,
+} from './target-idempotency.ts';
+
+export interface CatalogIdempotencyRequest {
+	readonly key: string;
+	readonly operationId: string;
+}
+
+export class CatalogServiceError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'CatalogServiceError';
+	}
+}
+
+function bounded(
+	value: string,
+	field: string,
+	min: number,
+	max: number,
+): string {
+	const normalized = value.trim();
+	if (normalized.length < min || normalized.length > max) {
+		throw new CatalogServiceError(
+			'INVALID_INPUT',
+			`${field} must contain between ${min} and ${max} characters.`,
+		);
+	}
+	return normalized;
+}
+
+function itemKind(value: CatalogItemKind): CatalogItemKind {
+	if (value !== 'product' && value !== 'service') {
+		throw new CatalogServiceError(
+			'INVALID_ITEM_KIND',
+			'kind must be product or service.',
+		);
+	}
+	return value;
+}
+
+function trustedActor(actor: Actor): Actor {
+	const normalized = normalizeActor(actor);
+	if (!normalized) {
+		throw new CatalogServiceError(
+			'INVALID_ACTOR',
+			'actor must carry a kind, an id, and a label.',
+		);
+	}
+	return normalized;
+}
+
+export class CatalogService {
+	constructor(private readonly repository: CatalogRepository) {}
+
+	async list(tenantId: string): Promise<readonly CatalogItem[]> {
+		return await this.repository.list(bounded(tenantId, 'tenantId', 1, 128));
+	}
+
+	async get(tenantId: string, id: string): Promise<CatalogItem | null> {
+		return await this.repository.find(
+			bounded(tenantId, 'tenantId', 1, 128),
+			bounded(id, 'id', 1, 128),
+		);
+	}
+
+	async create(
+		tenantId: string,
+		input: CreateCatalogItemInput,
+		actor: Actor,
+	): Promise<CatalogItem> {
+		const item = this.newItem(tenantId, input);
+		return await this.persistCreate(item, trustedActor(actor));
+	}
+
+	async createIdempotent(
+		tenantId: string,
+		input: CreateCatalogItemInput,
+		actor: Actor,
+		idempotency: CatalogIdempotencyRequest,
+	): Promise<CatalogItem> {
+		const item = this.newItem(tenantId, input);
+		const trusted = trustedActor(actor);
+		try {
+			return await this.repository.createIdempotent(
+				item,
+				item.sku.toLocaleLowerCase('en-US'),
+				trusted,
+				{
+					key: bounded(idempotency.key, 'idempotencyKey', 8, 128),
+					operationId: bounded(idempotency.operationId, 'operationId', 3, 160),
+					inputDigest: canonicalDigest({
+						sku: item.sku,
+						name: item.name,
+						kind: item.kind,
+						unit: item.unit,
+						basePriceMinor: item.basePriceMinor,
+						currency: item.currency,
+					}),
+				},
+			);
+		} catch (error) {
+			if (error instanceof TargetIdempotencyConflictError) {
+				throw new CatalogServiceError(error.code, error.message, 409);
+			}
+			if (error instanceof DuplicateSkuError) {
+				throw new CatalogServiceError('DUPLICATE_SKU', error.message, 409);
+			}
+			throw error;
+		}
+	}
+
+	private newItem(
+		tenantId: string,
+		input: CreateCatalogItemInput,
+	): CatalogItem {
+		if (
+			!Number.isSafeInteger(input.basePriceMinor) ||
+			input.basePriceMinor < 0
+		) {
+			throw new CatalogServiceError(
+				'INVALID_PRICE',
+				'basePriceMinor must be a non-negative integer.',
+			);
+		}
+		const sku = bounded(input.sku, 'sku', 1, 64).toUpperCase();
+		const currency = bounded(input.currency, 'currency', 3, 3).toUpperCase();
+		if (!/^[A-Z]{3}$/.test(currency)) {
+			throw new CatalogServiceError(
+				'INVALID_CURRENCY',
+				'currency must be a three-letter ISO code.',
+			);
+		}
+		return {
+			id: randomUUID(),
+			tenantId: bounded(tenantId, 'tenantId', 1, 128),
+			sku,
+			name: bounded(input.name, 'name', 2, 160),
+			kind: itemKind(input.kind),
+			unit: bounded(input.unit, 'unit', 1, 24),
+			basePriceMinor: input.basePriceMinor,
+			currency,
+			status: 'active',
+			createdAt: Date.now(),
+		};
+	}
+
+	private async persistCreate(
+		item: CatalogItem,
+		actor: Actor,
+	): Promise<CatalogItem> {
+		try {
+			return await this.repository.create(
+				item,
+				item.sku.toLocaleLowerCase('en-US'),
+				actor,
+			);
+		} catch (error) {
+			if (error instanceof DuplicateSkuError) {
+				throw new CatalogServiceError('DUPLICATE_SKU', error.message, 409);
+			}
+			throw error;
+		}
+	}
+
+	async update(
+		tenantId: string,
+		input: UpdateCatalogItemInput,
+		actor: Actor,
+	): Promise<CatalogItem> {
+		const trustedTenantId = bounded(tenantId, 'tenantId', 1, 128);
+		const current = await this.item(trustedTenantId, input.id);
+		if (
+			!Number.isSafeInteger(input.basePriceMinor) ||
+			input.basePriceMinor < 0
+		) {
+			throw new CatalogServiceError(
+				'INVALID_PRICE',
+				'basePriceMinor must be a non-negative integer.',
+			);
+		}
+		const currency = bounded(input.currency, 'currency', 3, 3).toUpperCase();
+		if (!/^[A-Z]{3}$/.test(currency)) {
+			throw new CatalogServiceError(
+				'INVALID_CURRENCY',
+				'currency must be a three-letter ISO code.',
+			);
+		}
+		const updated = await this.repository.update(
+			{
+				...current,
+				name: bounded(input.name, 'name', 2, 160),
+				kind: itemKind(input.kind),
+				unit: bounded(input.unit, 'unit', 1, 24),
+				basePriceMinor: input.basePriceMinor,
+				currency,
+			},
+			trustedActor(actor),
+		);
+		if (!updated) throw this.notFound();
+		return updated;
+	}
+
+	async archive(
+		tenantId: string,
+		id: string,
+		actor: Actor,
+	): Promise<CatalogItem> {
+		return await this.changeStatus(tenantId, id, 'archived', actor);
+	}
+
+	async restore(
+		tenantId: string,
+		id: string,
+		actor: Actor,
+	): Promise<CatalogItem> {
+		return await this.changeStatus(tenantId, id, 'active', actor);
+	}
+
+	async delete(tenantId: string, id: string, actor: Actor): Promise<void> {
+		const trustedTenantId = bounded(tenantId, 'tenantId', 1, 128);
+		const trustedId = bounded(id, 'id', 1, 128);
+		const current = await this.item(trustedTenantId, trustedId);
+		if (current.status !== 'archived') {
+			throw new CatalogServiceError(
+				'CATALOG_ITEM_NOT_ARCHIVED',
+				'Archive the catalog item before deleting it permanently.',
+				409,
+			);
+		}
+		if (
+			!(await this.repository.delete(
+				trustedTenantId,
+				trustedId,
+				trustedActor(actor),
+			))
+		) {
+			throw this.notFound();
+		}
+	}
+
+	async history(
+		tenantId: string,
+		request: HistoryRequest,
+	): Promise<HistoryPage> {
+		return await this.repository.history({
+			tenantId: bounded(tenantId, 'tenantId', 1, 128),
+			recordId: bounded(request.recordId, 'recordId', 1, 128),
+			limit: request.limit,
+			cursor: request.cursor,
+		});
+	}
+
+	private async item(tenantId: string, id: string): Promise<CatalogItem> {
+		const item = await this.repository.find(
+			tenantId,
+			bounded(id, 'id', 1, 128),
+		);
+		if (!item) throw this.notFound();
+		return item;
+	}
+
+	private notFound(): CatalogServiceError {
+		return new CatalogServiceError(
+			'CATALOG_ITEM_NOT_FOUND',
+			'The catalog item was not found in the active tenant.',
+			404,
+		);
+	}
+
+	private async changeStatus(
+		tenantId: string,
+		id: string,
+		status: CatalogItem['status'],
+		actor: Actor,
+	): Promise<CatalogItem> {
+		const item = await this.repository.setStatus(
+			bounded(tenantId, 'tenantId', 1, 128),
+			bounded(id, 'id', 1, 128),
+			status,
+			trustedActor(actor),
+		);
+		if (!item) throw this.notFound();
+		return item;
+	}
+}