@flowdular/sdk 0.2.3 → 0.3.0

package/packages/contracts/schemas/module-spec.schema.json

@@ -18,7 +18,7 @@
 	],
 	"properties": {
 		"$schema": { "type": "string" },
-		"schemaVersion": { "const": 1 },
+		"schemaVersion": { "enum": [1, 2] },
 		"id": {
 			"type": "string",
 			"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
@@ -59,6 +59,29 @@
 				}
 			}
 		},
+		"provides": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+			},
+			"uniqueItems": true
+		},
+		"requires": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["id"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+					},
+					"optional": { "type": "boolean" }
+				}
+			}
+		},
 		"tenancy": { "enum": ["required", "optional", "none"] },
 		"locales": {
 			"type": "array",
@@ -106,6 +129,269 @@
 				}
 			},
 			"uniqueItems": true
+		},
+		"entities": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/entity" },
+			"uniqueItems": true
+		},
+		"screens": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/screen" },
+			"uniqueItems": true
+		},
+		"actions": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/action" },
+			"uniqueItems": true
+		},
+		"widgets": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/widget" },
+			"uniqueItems": true
+		},
+		"settings": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/setting" },
+			"uniqueItems": true
+		},
+		"agentTools": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/agentTool" },
+			"uniqueItems": true
+		},
+		"outOfScope": {
+			"type": "array",
+			"items": { "type": "string", "minLength": 1 },
+			"uniqueItems": true
+		},
+		"decisions": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/decision" },
+			"uniqueItems": true
+		}
+	},
+	"allOf": [
+		{
+			"if": {
+				"required": ["schemaVersion"],
+				"properties": { "schemaVersion": { "const": 1 } }
+			},
+			"then": {
+				"properties": {
+					"entities": false,
+					"screens": false,
+					"actions": false,
+					"widgets": false,
+					"settings": false,
+					"agentTools": false,
+					"outOfScope": false,
+					"decisions": false
+				}
+			}
+		}
+	],
+	"$defs": {
+		"entityId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+		"fieldId": { "type": "string", "pattern": "^[a-z][a-zA-Z0-9]*$" },
+		"enumValue": { "type": "string", "pattern": "^[a-z][a-z0-9_-]*$" },
+		"entity": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "name", "fields"],
+			"properties": {
+				"id": { "$ref": "#/$defs/entityId" },
+				"name": { "type": "string", "minLength": 1 },
+				"description": { "type": "string", "minLength": 1 },
+				"fields": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/field" },
+					"uniqueItems": true
+				},
+				"states": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["field", "values"],
+					"properties": {
+						"field": { "$ref": "#/$defs/fieldId" },
+						"values": {
+							"type": "array",
+							"minItems": 1,
+							"items": { "$ref": "#/$defs/enumValue" },
+							"uniqueItems": true
+						},
+						"transitions": {
+							"type": "array",
+							"items": {
+								"type": "object",
+								"additionalProperties": false,
+								"required": ["from", "to"],
+								"properties": {
+									"from": { "type": "string", "minLength": 1 },
+									"to": { "type": "string", "minLength": 1 },
+									"permission": { "type": "string", "minLength": 1 }
+								}
+							},
+							"uniqueItems": true
+						}
+					}
+				}
+			}
+		},
+		"field": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "type"],
+			"properties": {
+				"id": { "$ref": "#/$defs/fieldId" },
+				"type": {
+					"enum": [
+						"string",
+						"text",
+						"integer",
+						"decimal",
+						"boolean",
+						"date",
+						"datetime",
+						"enum",
+						"reference",
+						"json"
+					]
+				},
+				"required": { "type": "boolean" },
+				"unique": { "enum": ["tenant", "none"] },
+				"maxLength": { "type": "integer", "minimum": 1 },
+				"values": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "$ref": "#/$defs/enumValue" },
+					"uniqueItems": true
+				},
+				"reference": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$"
+				},
+				"description": { "type": "string", "minLength": 1 }
+			}
+		},
+		"screen": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "kind"],
+			"properties": {
+				"id": { "$ref": "#/$defs/entityId" },
+				"kind": { "enum": ["list", "record", "form", "dashboard"] },
+				"entity": { "$ref": "#/$defs/entityId" },
+				"title": { "type": "string", "minLength": 1 },
+				"columns": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/fieldId" },
+					"uniqueItems": true
+				},
+				"filters": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/fieldId" },
+					"uniqueItems": true
+				},
+				"navigationGroup": { "type": "string", "minLength": 1 }
+			}
+		},
+		"action": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"id",
+				"permission",
+				"kind",
+				"risk",
+				"idempotent",
+				"description"
+			],
+			"properties": {
+				"id": { "$ref": "#/$defs/entityId" },
+				"entity": { "$ref": "#/$defs/entityId" },
+				"permission": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+				},
+				"kind": { "enum": ["create", "update", "delete", "custom"] },
+				"risk": {
+					"enum": ["read", "workspace-write", "external", "destructive"]
+				},
+				"idempotent": { "type": "boolean" },
+				"description": { "type": "string", "minLength": 1 }
+			}
+		},
+		"widget": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "slot", "description"],
+			"properties": {
+				"id": { "$ref": "#/$defs/entityId" },
+				"slot": {
+					"enum": [
+						"dashboard.metrics",
+						"dashboard.main",
+						"dashboard.aside",
+						"topbar.actions"
+					]
+				},
+				"entity": { "$ref": "#/$defs/entityId" },
+				"description": { "type": "string", "minLength": 1 }
+			}
+		},
+		"setting": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["key", "type", "scope", "description"],
+			"properties": {
+				"key": { "$ref": "#/$defs/fieldId" },
+				"type": { "enum": ["string", "integer", "boolean", "enum"] },
+				"scope": { "enum": ["tenant", "platform"] },
+				"default": {
+					"oneOf": [
+						{ "type": "string" },
+						{ "type": "integer" },
+						{ "type": "boolean" }
+					]
+				},
+				"values": {
+					"type": "array",
+					"minItems": 1,
+					"items": { "type": "string", "minLength": 1 },
+					"uniqueItems": true
+				},
+				"description": { "type": "string", "minLength": 1 }
+			}
+		},
+		"agentTool": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "permission", "description", "risk"],
+			"properties": {
+				"id": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+				},
+				"permission": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+				},
+				"description": { "type": "string", "minLength": 1 },
+				"risk": { "enum": ["read", "workspace-write"] }
+			}
+		},
+		"decision": {
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["id", "question", "answer", "decidedBy"],
+			"properties": {
+				"id": { "type": "string", "pattern": "^[A-Z][A-Z0-9-]+$" },
+				"question": { "type": "string", "minLength": 1 },
+				"answer": { "type": "string", "minLength": 1 },
+				"decidedBy": { "enum": ["user", "default"] }
+			}
 		}
 	}
 }

package/packages/contracts/schemas/module.schema.json

@@ -69,6 +69,31 @@
 				}
 			}
 		},
+		"provides": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+			},
+			"uniqueItems": true
+		},
+		"requires": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["id"],
+				"properties": {
+					"id": {
+						"type": "string",
+						"pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+					},
+					"optional": {
+						"type": "boolean"
+					}
+				}
+			}
+		},
 		"tenancy": {
 			"enum": ["required", "optional", "none"]
 		},

package/packages/contracts/src/index.ts

@@ -1,3 +1,20 @@
+/* Version of the public platform contract, independent of application
+   versions. While it stays below 1.0.0 a patch bump means an additive change
+   that `^0.1.0` consumers still accept, and a minor bump means a member was
+   removed or changed. The surface is pinned by
+   packages/kernel/platform-api.snapshot.d.ts; `pnpm platform-api:check` fails
+   when the surface changes without a bump here. */
+export const PLATFORM_API_VERSION = '0.1.6';
+
+/* The workspace time zone: one tenant setting, declared by the module named
+   here and read by any module that shows or schedules a local time. The id, the
+   key and the fallback live here so a reader never restates them. */
+export const TENANT_TIME_ZONE_SETTING = {
+	moduleId: 'system.core',
+	key: 'timeZone',
+	defaultValue: 'UTC',
+} as const;
+
 export type ModuleCapability =
 	| 'api'
 	| 'database'
@@ -15,6 +32,16 @@ export interface ModuleDependency {
 	readonly range: string;
 }
 
+/* A public capability id another module registers through
+   `context.capabilities`, such as `notifications.publish.v1`. The version is
+   part of the id, so compatibility is asserted by name, not by module version. */
+export interface ModuleCapabilityRequirement {
+	readonly id: string;
+	/* An optional requirement is resolved with `get` returning null when no
+	   enabled module provides it; a required one fails composition. */
+	readonly optional?: boolean;
+}
+
 export interface ModuleManifest {
 	readonly platformApi?: string;
 	readonly $schema?: string;
@@ -25,6 +52,10 @@ export interface ModuleManifest {
 	readonly profile: ModuleProfile;
 	readonly capabilities: readonly ModuleCapability[];
 	readonly dependencies: readonly ModuleDependency[];
+	/** Capability ids this module registers at composition. */
+	readonly provides?: readonly string[];
+	/** Capability ids this module resolves from other modules. */
+	readonly requires?: readonly ModuleCapabilityRequirement[];
 	readonly tenancy: 'required' | 'optional' | 'none';
 	readonly locales: readonly string[];
 	readonly stability: ModuleStability;
@@ -54,8 +85,105 @@ export interface BlueprintManifest {
 	readonly status: 'draft' | 'approved' | 'deprecated';
 }
 
+export type ModuleSpecFieldType =
+	| 'string'
+	| 'text'
+	| 'integer'
+	| 'decimal'
+	| 'boolean'
+	| 'date'
+	| 'datetime'
+	| 'enum'
+	| 'reference'
+	| 'json';
+
+export interface ModuleSpecField {
+	readonly id: string;
+	readonly type: ModuleSpecFieldType;
+	readonly required?: boolean;
+	readonly unique?: 'tenant' | 'none';
+	readonly maxLength?: number;
+	/* Enum members; required when type is enum. */
+	readonly values?: readonly string[];
+	/* "<entityId>" in this spec, or "<moduleId>.<entityId>" in a dependency. */
+	readonly reference?: string;
+	readonly description?: string;
+}
+
+export interface ModuleSpecStates {
+	readonly field: string;
+	readonly values: readonly string[];
+	readonly transitions?: readonly {
+		readonly from: string;
+		readonly to: string;
+		readonly permission?: string;
+	}[];
+}
+
+export interface ModuleSpecEntity {
+	readonly id: string;
+	readonly name: string;
+	readonly description?: string;
+	readonly fields: readonly ModuleSpecField[];
+	readonly states?: ModuleSpecStates;
+}
+
+export interface ModuleSpecScreen {
+	readonly id: string;
+	readonly kind: 'list' | 'record' | 'form' | 'dashboard';
+	readonly entity?: string;
+	readonly title?: string;
+	readonly columns?: readonly string[];
+	readonly filters?: readonly string[];
+	readonly navigationGroup?: string;
+}
+
+export interface ModuleSpecAction {
+	readonly id: string;
+	readonly entity?: string;
+	readonly permission: string;
+	readonly kind: 'create' | 'update' | 'delete' | 'custom';
+	readonly risk: 'read' | 'workspace-write' | 'external' | 'destructive';
+	readonly idempotent: boolean;
+	readonly description: string;
+}
+
+export interface ModuleSpecWidget {
+	readonly id: string;
+	readonly slot:
+		| 'dashboard.metrics'
+		| 'dashboard.main'
+		| 'dashboard.aside'
+		| 'topbar.actions';
+	readonly entity?: string;
+	readonly description: string;
+}
+
+export interface ModuleSpecSetting {
+	readonly key: string;
+	readonly type: 'string' | 'integer' | 'boolean' | 'enum';
+	readonly scope: 'tenant' | 'platform';
+	readonly default?: string | number | boolean;
+	readonly values?: readonly string[];
+	readonly description: string;
+}
+
+export interface ModuleSpecAgentTool {
+	readonly id: string;
+	readonly permission: string;
+	readonly description: string;
+	readonly risk: 'read' | 'workspace-write';
+}
+
+export interface ModuleSpecDecision {
+	readonly id: string;
+	readonly question: string;
+	readonly answer: string;
+	readonly decidedBy: 'user' | 'default';
+}
+
 export interface ModuleSpec {
-	readonly schemaVersion: 1;
+	readonly schemaVersion: 1 | 2;
 	readonly id: string;
 	readonly specVersion: string;
 	readonly status:
@@ -69,6 +197,8 @@ export interface ModuleSpec {
 	readonly profile: ModuleProfile;
 	readonly capabilities: readonly ModuleCapability[];
 	readonly dependencies: readonly ModuleDependency[];
+	readonly provides?: readonly string[];
+	readonly requires?: readonly ModuleCapabilityRequirement[];
 	readonly tenancy: 'required' | 'optional' | 'none';
 	readonly locales: readonly string[];
 	readonly invariants?: readonly string[];
@@ -83,8 +213,21 @@ export interface ModuleSpec {
 		readonly when: string;
 		readonly then: string;
 	}[];
+	/* Domain model, accepted only with schemaVersion 2. Every member stays
+	   optional so a specification can adopt version 2 section by section. */
+	readonly entities?: readonly ModuleSpecEntity[];
+	readonly screens?: readonly ModuleSpecScreen[];
+	readonly actions?: readonly ModuleSpecAction[];
+	readonly widgets?: readonly ModuleSpecWidget[];
+	readonly settings?: readonly ModuleSpecSetting[];
+	readonly agentTools?: readonly ModuleSpecAgentTool[];
+	readonly outOfScope?: readonly string[];
+	readonly decisions?: readonly ModuleSpecDecision[];
 }
 
+/** A specification that carries the version 2 domain model. */
+export type ModuleSpecV2 = ModuleSpec & { readonly schemaVersion: 2 };
+
 export interface ValidationIssue {
 	readonly code: string;
 	readonly message: string;

package/packages/database/src/backup.ts

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { DatabaseError } from './contracts.ts';
+import type { ConfiguredDatabaseAdapter } from './provider.ts';
+
+export const BACKUP_MANIFEST_FILE = 'backup.json';
+export const BACKUP_MANIFEST_VERSION = 1;
+
+/**
+ * The encryption keys that protect data stored inside the database. A dump
+ * alone restores unreadable credentials and workflow payloads, so every backup
+ * records which keys it was taken under. Only a SHA-256 fingerprint of the key
+ * material is recorded; the material itself never enters a backup.
+ */
+export const BACKUP_KEY_VARIABLES = Object.freeze([
+	'FD_AGENT_CREDENTIAL_KEY',
+	'FD_AGENT_RUN_GRANT_KEY',
+	'FD_WORKFLOWS_PAYLOAD_KEY',
+	'FD_WORKFLOWS_CURSOR_KEY',
+	'FD_AUTH_MFA_KEY',
+	'FD_AUTOMATIONS_CREDENTIAL_KEY',
+	'FD_NOTIFICATIONS_SECRET_KEY',
+	'FD_STORAGE_ENCRYPTION_KEY',
+	'FD_CONNECTORS_SECRET_KEY',
+	'FD_AUDIT_ANCHOR_KEY',
+] as const);
+
+export interface BackupKeyFingerprint {
+	readonly variable: string;
+	/** `sha256:<hex>` of the key material, or null when the key was not set. */
+	readonly fingerprint: string | null;
+}
+
+export interface BackupManifest {
+	readonly schemaVersion: number;
+	readonly createdAt: string;
+	readonly adapter: ConfiguredDatabaseAdapter;
+	readonly platformVersion: string;
+	readonly modules: readonly string[];
+	readonly keys: readonly BackupKeyFingerprint[];
+}
+
+export type BackupKeyStatus =
+	| 'match'
+	| 'different'
+	| 'missing-in-environment'
+	| 'missing-in-backup';
+
+export interface BackupKeyComparison {
+	readonly variable: string;
+	readonly status: BackupKeyStatus;
+}
+
+/* One 32 byte key is written as hex, base64 or base64url depending on the
+   module that reads it, so the fingerprint covers the decoded bytes and not the
+   spelling. A value that decodes to anything else is fingerprinted verbatim. */
+function keyMaterial(value: string): Buffer {
+	if (/^[0-9a-f]{64}$/i.test(value)) return Buffer.from(value, 'hex');
+	const decoded = Buffer.from(value, 'base64');
+	return decoded.byteLength === 32 ? decoded : Buffer.from(value, 'utf8');
+}
+
+export function backupKeyFingerprint(value: string | undefined): string | null {
+	const trimmed = value?.trim();
+	if (!trimmed) return null;
+	const material = keyMaterial(trimmed);
+	const digest = createHash('sha256').update(material).digest('hex');
+	material.fill(0);
+	return `sha256:${digest}`;
+}
+
+export function backupKeyFingerprints(
+	environment: NodeJS.ProcessEnv,
+): readonly BackupKeyFingerprint[] {
+	return BACKUP_KEY_VARIABLES.map((variable) => ({
+		variable,
+		fingerprint: backupKeyFingerprint(environment[variable]),
+	}));
+}
+
+/**
+ * Every key the backup or this platform knows about, so a restore can warn
+ * before the data it is about to write becomes unreadable.
+ */
+export function compareBackupKeys(
+	manifest: BackupManifest,
+	environment: NodeJS.ProcessEnv,
+): readonly BackupKeyComparison[] {
+	const recorded = new Map(
+		manifest.keys.map((key) => [key.variable, key.fingerprint]),
+	);
+	const variables = [
+		...new Set([...recorded.keys(), ...BACKUP_KEY_VARIABLES]),
+	].sort((left, right) => left.localeCompare(right));
+	return variables.map((variable) => {
+		const backup = recorded.get(variable) ?? null;
+		const current = backupKeyFingerprint(environment[variable]);
+		if (backup === current) return { variable, status: 'match' as const };
+		if (!current)
+			return { variable, status: 'missing-in-environment' as const };
+		if (!backup) return { variable, status: 'missing-in-backup' as const };
+		return { variable, status: 'different' as const };
+	});
+}
+
+export function createBackupManifest(input: {
+	readonly adapter: ConfiguredDatabaseAdapter;
+	readonly platformVersion: string;
+	readonly modules: readonly string[];
+	readonly environment: NodeJS.ProcessEnv;
+	readonly createdAt?: Date;
+}): BackupManifest {
+	return {
+		schemaVersion: BACKUP_MANIFEST_VERSION,
+		createdAt: (input.createdAt ?? new Date()).toISOString(),
+		adapter: input.adapter,
+		platformVersion: input.platformVersion,
+		modules: [...input.modules],
+		keys: backupKeyFingerprints(input.environment),
+	};
+}
+
+function invalid(reason: string): never {
+	throw new DatabaseError(
+		'INVALID_ARGUMENT',
+		`The backup manifest is invalid: ${reason}`,
+	);
+}
+
+function boundedString(value: unknown, field: string): string {
+	if (typeof value !== 'string' || value.length < 1 || value.length > 256) {
+		invalid(`${field} must be a string of 1 to 256 characters.`);
+	}
+	return value;
+}
+
+/** Parses a manifest read from disk. Bounded so a hostile file cannot grow the process. */
+export function parseBackupManifest(value: unknown): BackupManifest {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+		invalid('it is not an object.');
+	}
+	const record = value as Record<string, unknown>;
+	if (record.schemaVersion !== BACKUP_MANIFEST_VERSION) {
+		invalid(`schemaVersion must be ${BACKUP_MANIFEST_VERSION}.`);
+	}
+	const adapter = record.adapter;
+	if (adapter !== 'pglite' && adapter !== 'postgresql') {
+		invalid('adapter must be "pglite" or "postgresql".');
+	}
+	if (!Array.isArray(record.modules) || record.modules.length > 512) {
+		invalid('modules must be a list of at most 512 module ids.');
+	}
+	if (!Array.isArray(record.keys) || record.keys.length > 64) {
+		invalid('keys must be a list of at most 64 fingerprints.');
+	}
+	return {
+		schemaVersion: BACKUP_MANIFEST_VERSION,
+		createdAt: boundedString(record.createdAt, 'createdAt'),
+		adapter,
+		platformVersion: boundedString(record.platformVersion, 'platformVersion'),
+		modules: record.modules.map((entry) => boundedString(entry, 'modules[]')),
+		keys: record.keys.map((entry) => {
+			if (typeof entry !== 'object' || entry === null) {
+				invalid('keys[] must be an object.');
+			}
+			const key = entry as Record<string, unknown>;
+			const fingerprint = key.fingerprint;
+			if (fingerprint !== null && typeof fingerprint !== 'string') {
+				invalid('keys[].fingerprint must be a string or null.');
+			}
+			return {
+				variable: boundedString(key.variable, 'keys[].variable'),
+				fingerprint:
+					fingerprint === null
+						? null
+						: boundedString(fingerprint, 'keys[].fingerprint'),
+			};
+		}),
+	};
+}