create-flowdular 0.3.1 → 0.4.0

package/agent-template/docs/sandbox.md

@@ -65,6 +65,79 @@ so a workspace can change them.
 When the work is done, eject it into `modules/` and enable it, or open a pull
 request with the gate evidence attached.
 
+## Sample data and recorded adapters
+
+A session can carry a sample of the data the module will really see: attach a
+CSV, JSON or plain text file (`.csv`, `.json`, `.txt`) to the brief or the
+composer, within the attachment limits (5 MB per file, 10 per session). The file
+stays in the session directory, is never sent to the connected application, and
+is deleted with the session.
+
+Every turn reads the sample through the read-only sandbox tool `sample-data`.
+Without input it lists each sample file with its columns, row count and a
+parsed preview of the first 20 rows; `{ "name": "customers.csv" }` previews one
+file. CSV is parsed with quoted fields and a detected `,`, `;` or tab delimiter,
+JSON from a top-level array or the first array inside an object, text as lines.
+A value is cut at 200 characters and a row at 40 columns; one preview stays
+under 32 KB and the listing under 64 KB, listing a file that does not fit
+without its rows. The BYOK driver offers the tool to the model. The local
+`claude` and `codex` drivers have no tool channel, so the same listing is
+written to `reference/sample-data.json` for the turn.
+
+The backend engineer derives the module's fixtures from the sample:
+`tests/fixtures/*.json` for the tests and `preview/seed.json` for the preview. It
+keeps the shape and replaces real names, contacts and identifiers with invented
+values, because fixtures ship with the module. The role may write `preview/**`,
+`src/preview.ts`, `research-fixtures.json` and `adapters/**`.
+
+### Seeding the preview
+
+When a draft module has both `preview/seed.json` (at most 1 MB) and
+`src/preview.ts` exporting `seed`, the preview calls it once the generation has
+started:
+
+```ts
+export async function seed(context: {
+	readonly tenantId: string; // the preview workspace
+	readonly accountId: string; // the preview account
+	readonly data: unknown; // parsed preview/seed.json
+	readonly databases: DatabaseProvider; // the preview's own provider
+}): Promise<void>;
+```
+
+`seed()` writes through the module's own repository, as the server composition
+does. The sandbox keeps a hash of both files in the session data directory and
+calls `seed()` again only when one of them changes, so it must be idempotent
+(upsert by the natural key). A failure is reported as the preview error of that
+module and never stops the preview. The preview does not seed through an
+`import.ports.v1` port: only `import.core` can read its port registry (the
+public capability registers ports), a port write needs a full principal and a
+job, and most drafts do not compose `import.core`.
+
+### Recorded adapters
+
+A draft spec with a `research` section previews through `research.core`. The
+preview composes it from the platform modules ahead of the drafts and holds
+`research.core.adapter` at `recorded`, the adapter chain at the recorded adapter
+alone (`searchOrder` at `recorded` with `recordedEnabled` on, `fetchOrder` at
+`direct`) and `research.core.recordedFixturesPath` at the absolute path of the
+module's `research-fixtures.json` for every workspace. A chain holding the
+recorded adapter reads pages from the same file before it looks at the fetch
+order, so nothing reaches the network. Changing any of them answers
+`409 SANDBOX_LIVE_ADAPTER_REFUSED`. When several drafts declare research, the
+first one in session order supplies the path. An entry of the spec's `adapters`
+section reads the fixture its `recorded` field names, by convention
+`adapters/<id>.recorded.json`.
+
+A session declares only recorded adapters; an owner connects a live search or
+connector instance after delivery. When a draft spec sets `research.adapter` to
+`model-native`, `searxng`, `firecrawl` or `connector`, or lists an adapter
+without `recorded`, the `spec-schema` gate fails with
+`SANDBOX_LIVE_ADAPTER_REFUSED` and names the file and field, so the turn goes
+back to its specialist and delivery stops. The preview refuses to compose such a
+session with the same code before a worker starts. A `research` section without
+`adapter` is previewed on the recorded fixtures.
+
 ## Deliver as a pull request
 
 The eject route (`POST /sandbox/api/sessions/:id/eject`) takes `target:
@@ -81,7 +154,9 @@ request time (`delivery/configuration.ts`): `targets`, `default`,
 `maxChangedFiles` and `git` with `remote`
 (`origin`), `repository` (`owner/name`, derived from the remote when null),
 `baseBranch` (`main`), `branchPrefix` (`sandbox`), `provider` (`github` or
-`none`), `mode` (`auto`, `direct` or `fork`), `forkOwner` and `reviewers`.
+`none`), `mode` (`auto`, `direct` or `fork`), `forkOwner`, `reviewers` and
+`labels` (added to the pull request after creation, default
+`sandbox-delivery`; a label the repository lacks never fails a delivery).
 
 Operator settings live in the sandbox configuration
 (`.flowdular/sandbox/config.json`, `GitHubDeliveryConfiguration` in

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-flowdular",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"type": "module",
 	"description": "Scaffold a Flowdular application: the platform, one example module and the secrets a fresh install needs.",
 	"license": "MIT",

package/template/default/flowdular.json

@@ -12,6 +12,7 @@
 			"system.core",
 			"auth.core",
 			"access.core",
+			"adapters.core",
 			"reports.core",
 			"metering.core",
 			"agents.core",
@@ -26,6 +27,7 @@
 			"import.core",
 			"notifications.core",
 			"profile.core",
+			"research.core",
 			"sandbox.core",
 			"search.core",
 			"users.core",

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

@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.1",
-		"@flowdular/sdk": "0.3.1"
+		"@flowdular/sdk": "0.4.0"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

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

@@ -2,6 +2,9 @@ import { useEffect, useMemo } from 'octane';
 import {
 	Alert,
 	Button,
+	CellStack,
+	CellText,
+	CellTime,
 	Drawer,
 	FormField,
 	Icon,
@@ -31,20 +34,18 @@ function columns(): readonly TableColumn<Note>[] {
 		{
 			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>,
+			width: 'auto',
+			cell: (note) =>
+				<CellStack
+					primary={note.title}
+					secondary={<CellText value={note.body} muted />}
+				/>,
 		},
 		{
 			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)),
+			width: '170px',
+			cell: (note) => <CellTime value={note.createdAt} />,
 		},
 	];
 }
@@ -152,12 +153,7 @@ export function NotesView(props: NotesViewProps) @{
 		}
 		<TableCard
 			title={t('example.table.title')}
-			count={t(
-				notes.length === 1
-					? 'example.table.count.one'
-					: 'example.table.count.other',
-				{ count: notes.length },
-			)}
+			count={t('example.table.count', { count: notes.length })}
 			search={<SearchField
 				value={query}
 				placeholder={t('example.table.search.placeholder')}

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

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
+import { translationKeys } from '@flowdular/sdk/contracts';
 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' };
@@ -28,8 +29,8 @@ describe('example.core manifest', () => {
 
 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(translationKeys(translationsPl)).toEqual(
+			translationKeys(translationsEn),
 		);
 		expect(manifest.locales).toEqual(['en', 'pl']);
 	});

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

@@ -9,7 +9,9 @@
 	"page.action.new": "Nowa notatka",
 	"table.title": "Notatki",
 	"table.count.one": "{count} notatka",
-	"table.count.other": "{count} notatek",
+	"table.count.few": "{count} notatki",
+	"table.count.many": "{count} notatek",
+	"table.count.other": "{count} notatki",
 	"table.column.note": "Notatka",
 	"table.column.created": "Utworzono",
 	"table.search.placeholder": "Szukaj notatek",

package/template/default/package.json

@@ -25,7 +25,7 @@
 	"devDependencies": {
 		"@tsrx/prettier-plugin": "0.3.120",
 		"prettier": "3.6.2",
-		"flowdular": "0.3.1",
+		"flowdular": "0.4.0",
 		"rulesync": "16.21.0"
 	}
 }

package/template/default/platform/package.json

@@ -15,7 +15,7 @@
 		"@octanejs/vite-plugin": "0.1.51",
 		"octane": "0.1.51",
 		"pg": "8.23.0",
-		"@flowdular/sdk": "0.3.1"
+		"@flowdular/sdk": "0.4.0"
 	},
 	"devDependencies": {
 		"@octanejs/app-core": "0.0.47",

package/template/default/platform/src/generated/modules.client.ts

@@ -8,6 +8,7 @@ import type {
 import { createClientContribution as system_core } from '@flowdular/sdk/modules/system/client';
 import { createClientContribution as auth_core } from '@flowdular/sdk/modules/auth/client';
 import { createClientContribution as access_core } from '@flowdular/sdk/modules/access/client';
+import { createClientContribution as adapters_core } from '@flowdular/sdk/modules/adapters/client';
 import { createClientContribution as reports_core } from '@flowdular/sdk/modules/reports/client';
 import { createClientContribution as metering_core } from '@flowdular/sdk/modules/metering/client';
 import { createClientContribution as agents_core } from '@flowdular/sdk/modules/agents/client';
@@ -23,6 +24,7 @@ import { createClientContribution as exports_core } from '@flowdular/sdk/modules
 import { createClientContribution as import_core } from '@flowdular/sdk/modules/import/client';
 import { createClientContribution as notifications_core } from '@flowdular/sdk/modules/notifications/client';
 import { createClientContribution as profile_core } from '@flowdular/sdk/modules/profile/client';
+import { createClientContribution as research_core } from '@flowdular/sdk/modules/research/client';
 import { createClientContribution as sandbox_core } from '@flowdular/sdk/modules/sandbox/client';
 import { createClientContribution as search_core } from '@flowdular/sdk/modules/search/client';
 import { createClientContribution as users_core } from '@flowdular/sdk/modules/users/client';
@@ -34,6 +36,7 @@ export function createModuleClientContributions(
 		system_core(context),
 		auth_core(context),
 		access_core(context),
+		adapters_core(context),
 		reports_core(context),
 		metering_core(context),
 		agents_core(context),
@@ -49,6 +52,7 @@ export function createModuleClientContributions(
 		import_core(context),
 		notifications_core(context),
 		profile_core(context),
+		research_core(context),
 		sandbox_core(context),
 		search_core(context),
 		users_core(context),

package/template/default/platform/src/generated/modules.server.ts

@@ -5,9 +5,13 @@ import type {
 	PlatformServerContext,
 } from '@flowdular/sdk/modules/auth/server';
 import type { WebMount } from '@flowdular/sdk/server';
-import { createModuleMetrics } from '@flowdular/sdk/server';
+import {
+	bindModuleCompositions,
+	createModuleMetrics,
+} from '@flowdular/sdk/server';
 import { createServerComposition as system_core } from '@flowdular/sdk/modules/system/platform';
 import { createServerComposition as access_core } from '@flowdular/sdk/modules/access/platform';
+import { createServerComposition as adapters_core } from '@flowdular/sdk/modules/adapters/platform';
 import { createServerComposition as reports_core } from '@flowdular/sdk/modules/reports/platform';
 import { createServerComposition as metering_core } from '@flowdular/sdk/modules/metering/platform';
 import { createServerComposition as agents_core } from '@flowdular/sdk/modules/agents/platform';
@@ -23,6 +27,7 @@ import { createServerComposition as exports_core } from '@flowdular/sdk/modules/
 import { createServerComposition as import_core } from '@flowdular/sdk/modules/import/platform';
 import { createServerComposition as notifications_core } from '@flowdular/sdk/modules/notifications/platform';
 import { createServerComposition as profile_core } from '@flowdular/sdk/modules/profile/platform';
+import { createServerComposition as research_core } from '@flowdular/sdk/modules/research/platform';
 import { createServerComposition as sandbox_core } from '@flowdular/sdk/modules/sandbox/platform';
 import { createServerComposition as search_core } from '@flowdular/sdk/modules/search/platform';
 import { createServerComposition as users_core } from '@flowdular/sdk/modules/users/platform';
@@ -30,14 +35,14 @@ import { createServerComposition as users_core } from '@flowdular/sdk/modules/us
 export function composeModuleServer(
 	context: PlatformServerContext,
 ): readonly PlatformServerComposition[] {
-	return [
+	return bindModuleCompositions([
 		{
 			...system_core({
 				...context,
 				agentDefinitions: context.agentDefinitions.forModule('system.core'),
 				dataClasses: context.dataClasses.forModule('system.core'),
 				capabilities: context.capabilities.forModule('system.core', {
-					provides: [],
+					provides: ['system.modules.v1'],
 					requires: [],
 				}),
 				metrics: createModuleMetrics('system.core'),
@@ -57,6 +62,26 @@ export function composeModuleServer(
 			}),
 			moduleId: 'access.core',
 		},
+		{
+			...adapters_core({
+				...context,
+				agentDefinitions: context.agentDefinitions.forModule('adapters.core'),
+				dataClasses: context.dataClasses.forModule('adapters.core'),
+				capabilities: context.capabilities.forModule('adapters.core', {
+					provides: ['adapters.sources.v1', 'adapters.sinks.v1'],
+					requires: [
+						{ id: 'connectors.calls.v1', optional: true },
+						{ id: 'connectors.instances.v1', optional: true },
+						{ id: 'import.ports.v1', optional: true },
+						{ id: 'import.write.v1', optional: true },
+						{ id: 'exports.lists.v1', optional: true },
+						{ id: 'metering.meters.v1', optional: true },
+					],
+				}),
+				metrics: createModuleMetrics('adapters.core'),
+			}),
+			moduleId: 'adapters.core',
+		},
 		{
 			...reports_core({
 				...context,
@@ -174,7 +199,12 @@ export function composeModuleServer(
 				agentDefinitions: context.agentDefinitions.forModule('connectors.core'),
 				dataClasses: context.dataClasses.forModule('connectors.core'),
 				capabilities: context.capabilities.forModule('connectors.core', {
-					provides: ['connectors.definitions.v1', 'connectors.calls.v1'],
+					provides: [
+						'connectors.definitions.v1',
+						'connectors.calls.v1',
+						'connectors.egress.v1',
+						'connectors.instances.v1',
+					],
 					requires: [],
 				}),
 				metrics: createModuleMetrics('connectors.core'),
@@ -200,8 +230,12 @@ export function composeModuleServer(
 				agentDefinitions: context.agentDefinitions.forModule('documents.core'),
 				dataClasses: context.dataClasses.forModule('documents.core'),
 				capabilities: context.capabilities.forModule('documents.core', {
-					provides: ['documents.attachments.v1'],
-					requires: [],
+					provides: [
+						'documents.attachments.v1',
+						'documents.text.v1',
+						'documents.templates.v1',
+					],
+					requires: [{ id: 'connectors.egress.v1', optional: true }],
 				}),
 				metrics: createModuleMetrics('documents.core'),
 			}),
@@ -239,7 +273,7 @@ export function composeModuleServer(
 				agentDefinitions: context.agentDefinitions.forModule('import.core'),
 				dataClasses: context.dataClasses.forModule('import.core'),
 				capabilities: context.capabilities.forModule('import.core', {
-					provides: ['import.ports.v1'],
+					provides: ['import.ports.v1', 'import.write.v1'],
 					requires: [{ id: 'documents.attachments.v1' }],
 				}),
 				metrics: createModuleMetrics('import.core'),
@@ -273,6 +307,32 @@ export function composeModuleServer(
 			}),
 			moduleId: 'profile.core',
 		},
+		{
+			...research_core({
+				...context,
+				agentDefinitions: context.agentDefinitions.forModule('research.core'),
+				dataClasses: context.dataClasses.forModule('research.core'),
+				capabilities: context.capabilities.forModule('research.core', {
+					provides: [
+						'research.search.v1',
+						'research.fetch.v1',
+						'research.evidence.v1',
+					],
+					requires: [
+						{ id: 'connectors.calls.v1', optional: true },
+						{ id: 'connectors.definitions.v1', optional: true },
+						{ id: 'connectors.instances.v1', optional: true },
+						{ id: 'connectors.egress.v1', optional: true },
+						{ id: 'metering.meters.v1', optional: true },
+						{ id: 'documents.attachments.v1', optional: true },
+						{ id: 'documents.text.v1', optional: true },
+						{ id: 'exports.lists.v1', optional: true },
+					],
+				}),
+				metrics: createModuleMetrics('research.core'),
+			}),
+			moduleId: 'research.core',
+		},
 		{
 			...sandbox_core({
 				...context,
@@ -316,7 +376,7 @@ export function composeModuleServer(
 			}),
 			moduleId: 'users.core',
 		},
-	];
+	]);
 }
 
 export const moduleWebMounts: readonly WebMount[] = [] as const;