create-flowdular 0.3.2 → 0.4.0

package/agent-template/docs/modules.md

@@ -39,6 +39,18 @@ spec instead of scanning the repository. Every section is optional and a
   `agentTools[]`: `id`, `permission`, `description`, `risk`.
 - `outOfScope[]` records what is deliberately not built; `decisions[]` records
   each interview question, its answer and whether a user or a default decided.
+- `research`: `adapter` (`model-native`, `searxng`, `firecrawl`, `connector`
+  or `recorded`),
+  `allowDomains`, `denyDomains`, `monthlyQueryBudget`, and `evidenceOwner`, the
+  entity whose records evidence attaches to through `research.core`.
+- `adapters[]`: `id` (prefixed with the module id), `direction` (`source` or
+  `sink`), `connector` and `operation` (a `connectors.core` definition and
+  operation key), `port` (an import port id for a source, a list export id for a
+  sink), `schedule` (a five-field cron or `null`), `mapping[]` (`from`, `to`,
+  `transform` of `rename`, `constant`, `format` or `lookup`, `value`) and
+  `recorded` (`adapters/<name>.recorded.json`).
+- `templates[]`: `id`, `title`, `inputEntity`, `format` (`pdf` or `docx`) and
+  `body` (`templates/<name>.md`).
 
 Validation is more than the schema: an action permission must exist in
 `permissions`, every `entity` must name an entity, screen `columns` and
@@ -53,6 +65,19 @@ at least one entity (`SPEC_ACTION_PERMISSION_UNKNOWN`, `SPEC_ENTITY_UNKNOWN`,
 `SPEC_DUPLICATE_ID`). A client without a list screen, or a stored entity with no
 tenant-unique field, is a warning.
 
+The three optional sections have checks of their own. `research.evidenceOwner`
+and `templates[].inputEntity` must name an entity (`SPEC_ENTITY_UNKNOWN`). An
+adapter id must start with the module id (`SPEC_ADAPTER_ID_NAMESPACE`); a source
+adapter's `port` must belong to this module or a declared dependency
+(`SPEC_ADAPTER_PORT_UNKNOWN`); `schedule` must be a cron `automations.core`
+accepts: minute, hour, day of month, month and day of week, each `*`, a number,
+a three letter month or weekday name, a list, a range or a step
+(`SPEC_ADAPTER_SCHEDULE_INVALID`); and a mapping needs `from` unless it is a
+`constant` and `value` unless it is a `rename` (`SPEC_ADAPTER_MAPPING_INVALID`).
+`recorded` stays optional here; a sandbox session refuses a live adapter in its
+own `spec-schema` gate (`SANDBOX_LIVE_ADAPTER_REFUSED`, see
+[sandbox.md](sandbox.md)).
+
 ### 2. Scaffold
 
 ```bash
@@ -82,6 +107,15 @@ lifecycle field is set by the service), and the columns of the first `list`
 screen become the table view. Further entities are the implementing agent's
 work.
 
+The optional sections scaffold declarations and fixtures, nothing that runs:
+`src/research.ts` and `research-fixtures.json` (one example query and page in
+the shape the recorded research adapter reads) for `research`; per adapter one
+`src/adapters/<name>.ts` (the id without the module id, dots turned into
+hyphens) and one recorded fixture stub at the declared `recorded` path, else
+`adapters/<name>.recorded.json`; and one `templates/<name>.md` per template
+body, with `templates` added to the package `files`. Implementing them follows the `module-new` and `integration-adapter`
+skills.
+
 Files are written through the workspace Prettier, so the format gate passes
 without a rewrite. A directory that already holds `spec/module.yaml` or
 `translations/**` is extended, not rejected, and a failed run leaves nothing
@@ -119,7 +153,10 @@ pnpm --filter @flowdular/module-<dir> test
 `module validate` checks more than the schema: `platform.server` requires
 `src/platform.ts` and a `./platform` export, `platform.client` requires
 `src/client/index.ts` and a `./client` export, and every declared locale needs a
-`translations/<locale>.json` with the same key set as the others (an error).
+`translations/<locale>.json` with the same key set as the others (an error). A
+plural family such as `count.one`/`count.other` in `en` and
+`count.one`/`count.few`/`count.many`/`count.other` in `pl` counts as one key,
+and each locale must carry the categories its plural rules select.
 `module.json` version drift against `specVersion`, or a locale missing from
 `flowdular.json`, is reported as a warning.
 

package/agent-template/docs/operations.md

@@ -356,6 +356,8 @@ variable falls back to the default and logs one warning about it.
 ## Production checklist
 
 - `pnpm verify` and `pnpm build` pass on the commit being shipped.
+  The container image only builds; it does not run the tests again, so a tag
+  must point at a commit whose CI verify passed.
 - `FD_ENV=production`, `FD_DATABASE_ADAPTER=postgresql`, separate
   `FD_DATABASE_URL` and `FD_DATABASE_MIGRATOR_URL` roles, neither `SUPERUSER`
   nor `BYPASSRLS` on the runtime role.

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.2",
+	"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.2"
+		"@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.2",
+		"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.2"
+		"@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

@@ -11,6 +11,7 @@ import {
 } 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';
@@ -26,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';
@@ -60,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,
@@ -177,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'),
@@ -203,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'),
 			}),
@@ -242,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'),
@@ -276,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,