create-flowdular 0.2.4 → 0.2.5

package/agent-template/.ai/references/catalog/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flowdular contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agent-template/.ai/references/catalog/migrations/0001_catalog_core.down.sql

@@ -0,0 +1,2 @@
+DROP POLICY IF EXISTS catalog_items_tenant_policy ON catalog_items;
+DROP TABLE IF EXISTS catalog_items;

package/agent-template/.ai/references/catalog/migrations/0001_catalog_core.up.sql

@@ -0,0 +1,21 @@
+CREATE TABLE IF NOT EXISTS catalog_items (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  sku TEXT NOT NULL,
+  sku_normalized TEXT NOT NULL,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('product', 'service')),
+  unit TEXT NOT NULL,
+  base_price_minor BIGINT NOT NULL CHECK (base_price_minor >= 0),
+  currency TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active', 'archived')),
+  created_at BIGINT NOT NULL,
+  UNIQUE (tenant_id, sku_normalized)
+);
+CREATE INDEX IF NOT EXISTS catalog_items_tenant_sku_idx
+  ON catalog_items (tenant_id, sku_normalized, id);
+ALTER TABLE catalog_items ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_items_tenant_policy ON catalog_items
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/agent-template/.ai/references/catalog/migrations/0002_catalog_history.down.sql

@@ -0,0 +1,3 @@
+DROP POLICY IF EXISTS catalog_items_history_tenant_policy ON catalog_items_history;
+DROP INDEX IF EXISTS catalog_items_history_tenant_record_version_idx;
+DROP TABLE IF EXISTS catalog_items_history;

package/agent-template/.ai/references/catalog/migrations/0002_catalog_history.up.sql

@@ -0,0 +1,20 @@
+CREATE TABLE IF NOT EXISTS catalog_items_history (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  record_id TEXT NOT NULL,
+  version BIGINT NOT NULL CHECK (version >= 1),
+  action TEXT NOT NULL CHECK (length(action) BETWEEN 1 AND 32),
+  actor_kind TEXT NOT NULL CHECK (actor_kind IN ('user', 'agent')),
+  actor_id TEXT NOT NULL CHECK (length(actor_id) BETWEEN 1 AND 128),
+  actor_label TEXT NOT NULL CHECK (length(actor_label) BETWEEN 1 AND 160),
+  run_id TEXT CHECK (run_id IS NULL OR length(run_id) BETWEEN 1 AND 128),
+  changes_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS catalog_items_history_tenant_record_version_idx
+  ON catalog_items_history (tenant_id, record_id, version DESC);
+ALTER TABLE catalog_items_history ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items_history FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_items_history_tenant_policy ON catalog_items_history
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/agent-template/.ai/references/catalog/migrations/0003_catalog_history_service_actors.down.sql

@@ -0,0 +1,3 @@
+DROP POLICY IF EXISTS catalog_items_history_v2_tenant_policy ON catalog_items_history_v2;
+DROP INDEX IF EXISTS catalog_items_history_v2_tenant_record_version_idx;
+DROP TABLE IF EXISTS catalog_items_history_v2;

package/agent-template/.ai/references/catalog/migrations/0003_catalog_history_service_actors.up.sql

@@ -0,0 +1,36 @@
+CREATE TABLE IF NOT EXISTS catalog_items_history_v2 (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  record_id TEXT NOT NULL,
+  version BIGINT NOT NULL CHECK (version >= 1),
+  action TEXT NOT NULL CHECK (length(action) BETWEEN 1 AND 32),
+  actor_kind TEXT NOT NULL CHECK (actor_kind IN ('user', 'agent', 'service')),
+  actor_id TEXT NOT NULL CHECK (length(actor_id) BETWEEN 1 AND 128),
+  actor_label TEXT NOT NULL CHECK (length(actor_label) BETWEEN 1 AND 160),
+  run_id TEXT CHECK (run_id IS NULL OR length(run_id) BETWEEN 1 AND 128),
+  configured_by_json TEXT CHECK (configured_by_json IS NULL OR configured_by_json::jsonb IS NOT NULL),
+  changes_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL,
+  CHECK (
+    (actor_kind = 'agent' AND run_id IS NOT NULL)
+    OR (actor_kind IN ('user', 'service') AND run_id IS NULL)
+  ),
+  CHECK (
+    (actor_kind = 'service' AND configured_by_json IS NOT NULL)
+    OR (actor_kind IN ('user', 'agent') AND configured_by_json IS NULL)
+  )
+);
+CREATE UNIQUE INDEX IF NOT EXISTS catalog_items_history_v2_tenant_record_version_idx
+  ON catalog_items_history_v2 (tenant_id, record_id, version DESC);
+INSERT INTO catalog_items_history_v2
+  (id, tenant_id, record_id, version, action, actor_kind, actor_id,
+   actor_label, run_id, configured_by_json, changes_json, occurred_at)
+SELECT id, tenant_id, record_id, version, action, actor_kind, actor_id,
+       actor_label, run_id, NULL, changes_json, occurred_at
+FROM catalog_items_history
+ON CONFLICT DO NOTHING;
+ALTER TABLE catalog_items_history_v2 ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_items_history_v2 FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_items_history_v2_tenant_policy ON catalog_items_history_v2
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/agent-template/.ai/references/catalog/migrations/0004_catalog_idempotency_ledger.down.sql

@@ -0,0 +1,3 @@
+DROP POLICY IF EXISTS catalog_idempotency_ledger_tenant_policy ON catalog_idempotency_ledger;
+DROP INDEX IF EXISTS catalog_idempotency_ledger_tenant_operation_idx;
+DROP TABLE IF EXISTS catalog_idempotency_ledger;

package/agent-template/.ai/references/catalog/migrations/0004_catalog_idempotency_ledger.up.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS catalog_idempotency_ledger (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  idempotency_key TEXT NOT NULL CHECK (length(idempotency_key) BETWEEN 8 AND 128),
+  operation_id TEXT NOT NULL CHECK (length(operation_id) BETWEEN 3 AND 160),
+  input_digest TEXT NOT NULL CHECK (length(input_digest) = 71),
+  outcome TEXT NOT NULL CHECK (outcome = 'succeeded'),
+  result_json TEXT NOT NULL CHECK (result_json::jsonb IS NOT NULL),
+  result_digest TEXT NOT NULL CHECK (length(result_digest) = 71),
+  created_at BIGINT NOT NULL,
+  UNIQUE (tenant_id, idempotency_key)
+);
+CREATE INDEX IF NOT EXISTS catalog_idempotency_ledger_tenant_operation_idx
+  ON catalog_idempotency_ledger (tenant_id, operation_id, created_at, id);
+ALTER TABLE catalog_idempotency_ledger ENABLE ROW LEVEL SECURITY;
+ALTER TABLE catalog_idempotency_ledger FORCE ROW LEVEL SECURITY;
+CREATE POLICY catalog_idempotency_ledger_tenant_policy ON catalog_idempotency_ledger
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/agent-template/.ai/references/catalog/migrations/README.md

@@ -0,0 +1,3 @@
+# Migrations
+
+Migrations in this directory are append-only after release.

package/agent-template/.ai/references/catalog/module.json

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

package/agent-template/.ai/references/catalog/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@flowdular/module-catalog",
+	"version": "0.6.1",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./client": "./src/client/index.ts",
+		"./server": "./src/server/index.ts",
+		"./platform": "./src/platform.ts",
+		"./module.json": "./module.json"
+	},
+	"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"
+	},
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/official-modules.git",
+		"directory": "modules/catalog"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	]
+}

package/agent-template/.ai/references/catalog/spec/module.yaml

@@ -0,0 +1,86 @@
+schemaVersion: 1
+id: catalog.core
+specVersion: 0.6.1
+status: approved
+name: Product Catalog Core
+description: Provides tenant-scoped products and services with stable SKUs, units, prices, currencies, and lifecycle state.
+profile: full
+capabilities:
+  - api
+  - database
+  - client
+  - translations
+dependencies:
+  - id: system.core
+    range: 0.5.0
+  - 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 PostgreSQL handle from platform composition, never a driver or a connection string, and declares explicit PostgreSQL SQL for every statement and migration.
+  - PostgreSQL item, history, and idempotency ledger tables enable and force 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 catalog item is owned by exactly one tenant and every query uses the trusted tenant identifier.
+  - SKU is unique inside a tenant and is never used as tenancy authority.
+  - Monetary values are stored as integer minor units with an explicit ISO currency code.
+  - Item kind is product or service and status is active or archived.
+  - Background workflow actions preserve their service actor and the configuring user in record history.
+  - One tenant-scoped durable target ledger is shared by mutating agent tools and workflow actions; each entry binds an idempotency key to the exact tool identifier or versioned workflow action identifier, canonical input digest, and first persisted result in the same transaction as the catalog mutation.
+  - Replaying the same idempotency key for the same operation and canonical input returns the original result without another catalog item or history row, while reuse for another operation or input fails with a stable conflict.
+  - Idempotency ledger entries remain after a catalog item is deleted, and audit metadata records identifiers, input digests, and outcomes without raw tool input, credentials, secrets, or result payloads.
+permissions:
+  - id: catalog.items.read
+    description: Read products and services in the active tenant.
+  - id: catalog.items.manage
+    description: Create and update products and services in the active tenant.
+dataOwnership:
+  - catalog.core owns SKU, item identity, kind, unit, base price, currency, and lifecycle status.
+  - catalog.core owns the idempotency ledger for its mutating agent tools and workflow actions; callers supply the key but do not maintain a second target ledger.
+  - Sales and purchasing modules reference catalog item identifiers and snapshot commercial terms when required by their specs.
+acceptanceScenarios:
+  - id: CATALOG-LIST
+    given: Tenant-scoped products and services exist.
+    when: An authorized principal lists catalog items.
+    then: Only items owned by the active tenant are returned in deterministic SKU order.
+  - id: CATALOG-CREATE
+    given: An authorized principal supplies a unique SKU and valid product or service data.
+    when: The catalog item is created.
+    then: A tenant-owned active item is persisted with integer minor-unit pricing.
+  - id: CATALOG-DUPLICATE
+    given: An item already uses a SKU in the active tenant.
+    when: Another item is created with the same normalized SKU.
+    then: The server returns a stable conflict error and leaves existing data unchanged.
+  - id: CATALOG-DENY
+    given: A principal is unauthenticated or lacks the required catalog permission.
+    when: The principal reads or mutates catalog data.
+    then: The server denies the operation before repository access.
+  - id: CATALOG-AGENT-TOOL
+    given: An agent run holds catalog.items.manage in its permission snapshot and the tool catalog.item.create in its grants.
+    when: The agent invokes the tool with a valid item, and a run without the manage scope invokes the same tool.
+    then: The scoped run creates a tenant-owned catalog item from the run tenant and the harness denies the unscoped run before any write.
+  - id: CATALOG-LIFECYCLE-HISTORY
+    given: A catalog item is active in the current tenant.
+    when: An authorized principal edits it, archives it, restores it, or deletes it after archiving.
+    then: Each accepted transition has an append-only tenant-scoped revision with the user or agent actor, and the item history endpoint returns only that tenant's revisions.
+  - id: CATALOG-WORKFLOW-ACTIONS
+    given: A workflow revision selects a versioned catalog read or create action and carries the matching permission snapshot.
+    when: The action capability validates and executes the node with an idempotency key and service actor.
+    then: The action exposes exact input and output schemas, refuses a missing permission before work, cooperates with cancellation, and attributes a created item to the service and its configuring user.
+  - id: CATALOG-IDEMPOTENCY-REPLAY
+    given: A mutating catalog tool or workflow action has committed a catalog mutation and its target-ledger result for an idempotency key.
+    when: The caller repeats the exact operation with the same canonical input and key, including after losing the first response.
+    then: The module returns the original persisted result and creates no second catalog item or history row.
+  - id: CATALOG-IDEMPOTENCY-CONFLICT
+    given: A tenant-scoped idempotency key is already bound to an exact catalog tool identifier or versioned workflow action identifier and canonical input digest.
+    when: A caller reuses the key for a different operation or canonical input.
+    then: The module returns a stable conflict before any catalog item, history, or ledger write.
+  - id: CATALOG-POSTGRESQL-TENANT-BOUNDARY
+    given: catalog.core runs on PostgreSQL and two tenants own catalog data.
+    when: A runtime transaction bound to one tenant reads or writes items, history, or ledger rows.
+    then: Only that tenant's rows are visible or mutable, a transaction without a tenant is refused, and the forced row-level security policy rejects a row carrying another tenant identifier.
+  - id: CATALOG-IDEMPOTENCY-RECOVERY
+    given: A catalog item has been committed atomically with its idempotency result, or the item is later deleted through its lifecycle operation.
+    when: Recovery replays the mutating tool or workflow action with the same key.
+    then: The retained ledger returns the original result without another mutation, and audit evidence contains no raw input, credentials, secrets, or result payload.

package/agent-template/.ai/references/catalog/src/acl/permissions.ts

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

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

@@ -0,0 +1,164 @@
+import { defineApiAgentTool } from '@flowdular/sdk/harness/tool-adapters';
+import {
+	AgentHarnessError,
+	type AgentTool,
+	type AgentToolContext,
+} from '@flowdular/sdk/harness/runtime';
+import { agentActor, type Actor } from '@flowdular/sdk/kernel';
+import { CATALOG_PERMISSIONS } from '../acl/permissions.ts';
+import type { CatalogItemKind } from '../domain/types.ts';
+import type { CatalogRuntime } from '../server/runtime.ts';
+import { CatalogServiceError } from '../services/catalog-service.ts';
+
+const MAX_TOOL_ROWS = 200;
+const CREATE_OPERATION = 'catalog.item.create@1';
+
+const CATALOG_ITEM_OUTPUT_SCHEMA = {
+	type: 'object',
+	additionalProperties: false,
+	required: [
+		'id',
+		'tenantId',
+		'sku',
+		'name',
+		'kind',
+		'unit',
+		'basePriceMinor',
+		'currency',
+		'status',
+		'createdAt',
+	],
+	properties: {
+		id: { type: 'string' },
+		tenantId: { type: 'string' },
+		sku: { type: 'string' },
+		name: { type: 'string' },
+		kind: { type: 'string', enum: ['product', 'service'] },
+		unit: { type: 'string' },
+		basePriceMinor: { type: 'integer' },
+		currency: { type: 'string' },
+		status: { type: 'string', enum: ['active', 'archived'] },
+		createdAt: { type: 'integer' },
+	},
+} as const;
+
+function actionActor(context: AgentToolContext): Actor {
+	return context.actor ?? agentActor(context);
+}
+
+function normalized(value: unknown): string {
+	return typeof value === 'string'
+		? value.trim().toLocaleLowerCase('en-US')
+		: '';
+}
+
+function idempotencyKey(context: AgentToolContext): string {
+	if (!context.idempotencyKey) {
+		throw new AgentHarnessError(
+			'TOOL_IDEMPOTENCY_KEY_REQUIRED',
+			'The catalog create tool requires a durable idempotency key.',
+		);
+	}
+	return context.idempotencyKey;
+}
+
+/* Tools call the catalog service and take the tenant and the actor from the
+   run context, never from input; the service revalidates so a tool cannot
+   bypass the endpoint's rules, every write is attributed to the run that made
+   it, and list output is capped so one call cannot flood the run window. */
+export function catalogAgentTools(
+	runtime: CatalogRuntime,
+): readonly AgentTool[] {
+	return [
+		defineApiAgentTool({
+			id: 'catalog.item.list',
+			endpointId: 'catalog.items.list',
+			contractVersion: 1,
+			description:
+				'List products and services of the active tenant, optionally filtered by a free-text query.',
+			requiredPermissions: [CATALOG_PERMISSIONS.read],
+			risk: 'read',
+			idempotency: 'required',
+			cancellation: 'cooperative',
+			inputSchema: {
+				type: 'object',
+				additionalProperties: false,
+				properties: { query: { type: 'string', maxLength: 120 } },
+			},
+			outputSchema: { type: 'array', items: CATALOG_ITEM_OUTPUT_SCHEMA },
+			execute: async (input, context) => {
+				context.signal.throwIfAborted();
+				const query = normalized(
+					(input as Record<string, unknown> | null)?.query,
+				);
+				return (await (await runtime.service()).list(context.tenantId))
+					.filter(
+						(item) =>
+							query === '' ||
+							item.id.toLocaleLowerCase('en-US') === query ||
+							item.sku.toLocaleLowerCase('en-US').includes(query) ||
+							item.name.toLocaleLowerCase('en-US').includes(query),
+					)
+					.slice(0, MAX_TOOL_ROWS);
+			},
+		}),
+		defineApiAgentTool({
+			id: 'catalog.item.create',
+			endpointId: 'catalog.items.create',
+			contractVersion: 1,
+			description: 'Create a product or service owned by the active tenant.',
+			requiredPermissions: [CATALOG_PERMISSIONS.manage],
+			risk: 'workspace-write',
+			idempotency: 'required',
+			idempotencyProtection: 'target-ledger',
+			cancellation: 'cooperative',
+			inputSchema: {
+				type: 'object',
+				additionalProperties: false,
+				required: ['sku', 'name', 'kind', 'unit', 'basePriceMinor', 'currency'],
+				properties: {
+					sku: { type: 'string', maxLength: 64 },
+					name: { type: 'string', maxLength: 160 },
+					kind: { type: 'string', enum: ['product', 'service'] },
+					unit: { type: 'string', maxLength: 24 },
+					basePriceMinor: { type: 'integer' },
+					currency: { type: 'string', maxLength: 3 },
+				},
+			},
+			outputSchema: CATALOG_ITEM_OUTPUT_SCHEMA,
+			execute: async (input, context) => {
+				context.signal.throwIfAborted();
+				const value = (input ?? {}) as Record<string, unknown>;
+				try {
+					return (await runtime.service()).createIdempotent(
+						context.tenantId,
+						{
+							sku: String(value.sku ?? ''),
+							name: String(value.name ?? ''),
+							kind: value.kind as CatalogItemKind,
+							unit: String(value.unit ?? ''),
+							basePriceMinor:
+								typeof value.basePriceMinor === 'number'
+									? value.basePriceMinor
+									: Number.NaN,
+							currency: String(value.currency ?? ''),
+						},
+						actionActor(context),
+						{
+							key: idempotencyKey(context),
+							operationId: CREATE_OPERATION,
+						},
+					);
+				} catch (error) {
+					if (
+						error instanceof CatalogServiceError &&
+						error.code === 'CATALOG_IDEMPOTENCY_CONFLICT'
+					) {
+						throw new AgentHarnessError(error.code, error.message);
+					}
+					throw error;
+				}
+			},
+		}),
+	];
+}