@viyv/agent-ui-schema 0.1.0

package/src/expression.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+// Expression types
+export type ExpressionRef =
+	| { type: 'hook'; hookId: string; path: string[] }
+	| { type: 'state'; key: string }
+	| { type: 'bindState'; key: string }
+	| { type: 'action'; actionId: string }
+	| { type: 'item'; path: string[] }
+	| { type: 'param'; name: string }
+	| { type: 'expr'; code: string };
+
+// Pattern matchers — identifiers allow word chars plus hyphens (e.g. "my-hook")
+const ID = '[\\w-]+';
+const HOOK_PATTERN = new RegExp(`^\\$hook\\.(${ID})(\\.(.+))?$`);
+const STATE_PATTERN = new RegExp(`^\\$state\\.(${ID})$`);
+const BIND_STATE_PATTERN = new RegExp(`^\\$bindState\\.(${ID})$`);
+const ACTION_PATTERN = new RegExp(`^\\$action\\.(${ID})$`);
+const ITEM_PATTERN = /^\$item(\.(.+))?$/;
+const PARAM_PATTERN = new RegExp(`^\\$param\\.(${ID})$`);
+const EXPR_PATTERN = /^\$expr\((.+)\)$/s;
+
+export function isExpression(value: unknown): value is string {
+	return typeof value === 'string' && value.startsWith('$');
+}
+
+export function parseExpression(value: string): ExpressionRef | null {
+	let match: RegExpMatchArray | null;
+
+	match = value.match(HOOK_PATTERN);
+	if (match) {
+		const hookId = match[1];
+		const rest = match[3];
+		const path = rest ? rest.split('.') : [];
+		return { type: 'hook', hookId, path };
+	}
+
+	match = value.match(STATE_PATTERN);
+	if (match) {
+		return { type: 'state', key: match[1] };
+	}
+
+	match = value.match(BIND_STATE_PATTERN);
+	if (match) {
+		return { type: 'bindState', key: match[1] };
+	}
+
+	match = value.match(ACTION_PATTERN);
+	if (match) {
+		return { type: 'action', actionId: match[1] };
+	}
+
+	match = value.match(ITEM_PATTERN);
+	if (match) {
+		const rest = match[2];
+		const path = rest ? rest.split('.') : [];
+		return { type: 'item', path };
+	}
+
+	match = value.match(PARAM_PATTERN);
+	if (match) {
+		return { type: 'param', name: match[1] };
+	}
+
+	match = value.match(EXPR_PATTERN);
+	if (match) {
+		return { type: 'expr', code: match[1] };
+	}
+
+	return null;
+}
+
+export const ExpressionStringSchema = z
+	.string()
+	.refine((val) => !val.startsWith('$') || parseExpression(val) !== null, {
+		message: 'Invalid expression syntax',
+	});

package/src/hook-def.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+
+export const UseStateHookSchema = z.object({
+	use: z.literal('useState'),
+	params: z.object({
+		initial: z.unknown(),
+	}),
+});
+
+export const UseDerivedHookSchema = z.object({
+	use: z.literal('useDerived'),
+	from: z.string().min(1),
+	params: z.object({
+		sort: z
+			.object({
+				key: z.string(),
+				order: z.enum(['asc', 'desc']).default('asc'),
+			})
+			.optional(),
+		filter: z
+			.object({
+				key: z.string(),
+				match: z.unknown(),
+			})
+			.optional(),
+		limit: z.number().int().positive().optional(),
+		groupBy: z.string().optional(),
+		aggregate: z
+			.object({
+				fn: z.enum(['sum', 'avg', 'count', 'min', 'max']),
+				key: z.string(),
+			})
+			.optional(),
+	}),
+});
+
+export const UseFetchHookSchema = z.object({
+	use: z.literal('useFetch'),
+	params: z.object({
+		url: z.string().url(),
+		method: z.enum(['GET', 'POST']).default('GET'),
+		headers: z.record(z.string()).optional(),
+		body: z.unknown().optional(),
+		refreshInterval: z.number().int().positive().optional(),
+	}),
+});
+
+export const UseSqlQueryHookSchema = z.object({
+	use: z.literal('useSqlQuery'),
+	params: z.object({
+		connection: z.string().min(1),
+		query: z.string().min(1),
+		refreshInterval: z.number().int().positive().optional(),
+	}),
+});
+
+export const UseAgentQueryHookSchema = z.object({
+	use: z.literal('useAgentQuery'),
+	params: z.object({
+		endpoint: z.string().min(1),
+		query: z.record(z.unknown()).optional(),
+		refreshInterval: z.number().int().positive().optional(),
+	}),
+});
+
+export const HookDefSchema = z.discriminatedUnion('use', [
+	UseStateHookSchema,
+	UseDerivedHookSchema,
+	UseFetchHookSchema,
+	UseSqlQueryHookSchema,
+	UseAgentQueryHookSchema,
+]);
+
+export type HookDef = z.infer<typeof HookDefSchema>;
+export type UseStateHook = z.infer<typeof UseStateHookSchema>;
+export type UseDerivedHook = z.infer<typeof UseDerivedHookSchema>;
+export type UseFetchHook = z.infer<typeof UseFetchHookSchema>;
+export type UseSqlQueryHook = z.infer<typeof UseSqlQueryHookSchema>;
+export type UseAgentQueryHook = z.infer<typeof UseAgentQueryHookSchema>;

package/src/index.ts

@@ -0,0 +1,72 @@
+// Expression
+export { parseExpression, isExpression, ExpressionStringSchema } from './expression.js';
+export type { ExpressionRef } from './expression.js';
+
+// Hook definitions
+export {
+	HookDefSchema,
+	UseStateHookSchema,
+	UseDerivedHookSchema,
+	UseFetchHookSchema,
+	UseSqlQueryHookSchema,
+	UseAgentQueryHookSchema,
+} from './hook-def.js';
+export type {
+	HookDef,
+	UseStateHook,
+	UseDerivedHook,
+	UseFetchHook,
+	UseSqlQueryHook,
+	UseAgentQueryHook,
+} from './hook-def.js';
+
+// Element definitions
+export { ElementDefSchema, VisibilityConditionSchema } from './element-def.js';
+export type { ElementDef, VisibilityCondition } from './element-def.js';
+
+// Action definitions
+export {
+	ActionDefSchema,
+	SetStateActionSchema,
+	RefreshHookActionSchema,
+	NavigateActionSchema,
+	SubmitFormActionSchema,
+	AddItemActionSchema,
+	RemoveItemActionSchema,
+	UpdateItemActionSchema,
+} from './action-def.js';
+export type { ActionDef } from './action-def.js';
+
+// Page spec
+export { PageSpecSchema, ParamDefSchema, ThemeSchema, PageMetaSchema } from './page-spec.js';
+export type { PageSpec, ParamDef, Theme, PageMeta } from './page-spec.js';
+
+// Catalog
+export { defineCatalog } from './catalog.js';
+export type { ComponentMeta, ComponentCatalog } from './catalog.js';
+
+// Page store
+export type { PageStore, PageStorePage } from './page-store.js';
+
+// Data source
+export {
+	DataSourceMetaSchema,
+	TableMetaSchema,
+	ColumnMetaSchema,
+	EndpointMetaSchema,
+} from './data-source.js';
+export type {
+	DataSourceMeta,
+	TableMeta,
+	ColumnMeta,
+	EndpointMeta,
+	DataConnector,
+} from './data-source.js';
+
+// JSON Patch
+export { JsonPatchSchema, JsonPatchOpSchema } from './patch.js';
+export type { JsonPatch, JsonPatchOp } from './patch.js';
+
+// Validator
+export { validatePageSpec } from './validator.js';
+export type { ValidationResult, ValidationError } from './validator.js';

package/src/page-spec.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { ActionDefSchema } from './action-def.js';
+import { ElementDefSchema } from './element-def.js';
+import { HookDefSchema } from './hook-def.js';
+
+export const ParamDefSchema = z.object({
+	type: z.enum(['string', 'number']).default('string'),
+	default: z.unknown().optional(),
+	description: z.string().optional(),
+});
+
+export const ThemeSchema = z.object({
+	colorScheme: z.enum(['light', 'dark', 'auto']).default('auto'),
+	accentColor: z.string().optional(),
+	spacing: z.enum(['compact', 'default', 'relaxed']).default('default'),
+});
+
+export const PageMetaSchema = z.object({
+	createdAt: z.string().datetime().optional(),
+	updatedAt: z.string().datetime().optional(),
+	createdBy: z.string().optional(),
+	tags: z.array(z.string()).optional(),
+});
+
+export const PageSpecSchema = z.object({
+	id: z.string().min(1),
+	title: z.string().min(1),
+	description: z.string().optional(),
+	hooks: z.record(HookDefSchema).default({}),
+	root: z.string().min(1),
+	elements: z.record(ElementDefSchema),
+	state: z.record(z.unknown()).default({}),
+	actions: z.record(ActionDefSchema).default({}),
+	params: z.record(ParamDefSchema).optional(),
+	theme: ThemeSchema.optional(),
+	meta: PageMetaSchema.optional(),
+});
+
+export type PageSpec = z.infer<typeof PageSpecSchema>;
+export type ParamDef = z.infer<typeof ParamDefSchema>;
+export type Theme = z.infer<typeof ThemeSchema>;
+export type PageMeta = z.infer<typeof PageMetaSchema>;

package/src/page-store.ts

@@ -0,0 +1,18 @@
+import type { PageSpec } from './page-spec.js';
+
+export interface PageStorePage {
+	id: string;
+	spec: PageSpec;
+	createdAt: Date;
+	updatedAt: Date;
+}
+
+export interface PageStore {
+	list(): Promise<PageStorePage[]>;
+	get(id: string): Promise<PageStorePage | null>;
+	save(spec: PageSpec): Promise<PageStorePage>;
+	update(id: string, spec: PageSpec): Promise<PageStorePage>;
+	delete(id: string): Promise<void>;
+	savePreview(spec: PageSpec): Promise<{ previewId: string; expiresAt: Date }>;
+	getPreview(previewId: string): Promise<PageSpec | null>;
+}

package/src/patch.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+/** JSON Pointer string (RFC 6901): must be empty or start with "/" */
+const JsonPointerSchema = z.string().refine((s) => s === '' || s.startsWith('/'), {
+	message: 'JSON Pointer must be empty or start with "/"',
+});
+
+export const JsonPatchOpSchema = z.discriminatedUnion('op', [
+	z.object({ op: z.literal('add'), path: JsonPointerSchema, value: z.unknown() }),
+	z.object({ op: z.literal('remove'), path: JsonPointerSchema }),
+	z.object({ op: z.literal('replace'), path: JsonPointerSchema, value: z.unknown() }),
+	z.object({
+		op: z.literal('move'),
+		from: JsonPointerSchema,
+		path: JsonPointerSchema,
+	}),
+	z.object({
+		op: z.literal('copy'),
+		from: JsonPointerSchema,
+		path: JsonPointerSchema,
+	}),
+	z.object({ op: z.literal('test'), path: JsonPointerSchema, value: z.unknown() }),
+]);
+
+export const JsonPatchSchema = z.array(JsonPatchOpSchema);
+
+export type JsonPatchOp = z.infer<typeof JsonPatchOpSchema>;
+export type JsonPatch = z.infer<typeof JsonPatchSchema>;

package/src/validator.ts

@@ -0,0 +1,347 @@
+import type { ComponentCatalog } from './catalog.js';
+import { isExpression, parseExpression } from './expression.js';
+import type { HookDef } from './hook-def.js';
+import type { PageSpec } from './page-spec.js';
+import { PageSpecSchema } from './page-spec.js';
+
+export interface ValidationError {
+	path: string;
+	message: string;
+	severity: 'error' | 'warning';
+}
+
+export interface ValidationResult {
+	valid: boolean;
+	errors: ValidationError[];
+	warnings: ValidationError[];
+}
+
+export function validatePageSpec(input: unknown, catalog?: ComponentCatalog): ValidationResult {
+	const errors: ValidationError[] = [];
+	const warnings: ValidationError[] = [];
+
+	// 1. Zod schema validation
+	const parsed = PageSpecSchema.safeParse(input);
+	if (!parsed.success) {
+		for (const issue of parsed.error.issues) {
+			errors.push({
+				path: issue.path.join('.'),
+				message: issue.message,
+				severity: 'error',
+			});
+		}
+		return { valid: false, errors, warnings };
+	}
+
+	const spec = parsed.data;
+
+	// 2. Root element exists
+	if (!spec.elements[spec.root]) {
+		errors.push({
+			path: 'root',
+			message: `Root element "${spec.root}" not found in elements`,
+			severity: 'error',
+		});
+	}
+
+	// 3. Children reference integrity
+	for (const [id, element] of Object.entries(spec.elements)) {
+		if (element.children) {
+			for (const childId of element.children) {
+				if (!spec.elements[childId]) {
+					errors.push({
+						path: `elements.${id}.children`,
+						message: `Child element "${childId}" not found`,
+						severity: 'error',
+					});
+				}
+			}
+		}
+	}
+
+	// 4. Expression reference validity
+	validateExpressions(spec, errors, warnings);
+
+	// 5. Hook dependency validation (dangling references + cycles)
+	validateHookDependencies(spec.hooks, errors);
+	validateHookCycles(spec.hooks, errors);
+
+	// 6. SQL safety check
+	validateSqlSafety(spec.hooks, errors, warnings);
+
+	// 7. CRUD action hookId validation
+	validateActions(spec, errors);
+
+	// 8. Component props validation against catalog
+	if (catalog) {
+		validateComponentProps(spec, catalog, warnings);
+	}
+
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings,
+	};
+}
+
+function validateExpressionRef(
+	ref: ReturnType<typeof parseExpression>,
+	spec: PageSpec,
+	path: string,
+	errors: ValidationError[],
+): void {
+	if (!ref) return;
+	if (ref.type === 'hook' && !spec.hooks[ref.hookId]) {
+		errors.push({
+			path,
+			message: `Hook "${ref.hookId}" not defined`,
+			severity: 'error',
+		});
+	}
+	if (ref.type === 'state' && !(ref.key in spec.state)) {
+		errors.push({
+			path,
+			message: `State key "${ref.key}" not defined`,
+			severity: 'error',
+		});
+	}
+	if (ref.type === 'bindState' && !(ref.key in spec.state)) {
+		errors.push({
+			path,
+			message: `State key "${ref.key}" not defined for binding`,
+			severity: 'error',
+		});
+	}
+	if (ref.type === 'action' && !spec.actions[ref.actionId]) {
+		errors.push({
+			path,
+			message: `Action "${ref.actionId}" not defined`,
+			severity: 'error',
+		});
+	}
+	if (ref.type === 'param' && spec.params && !(ref.name in spec.params)) {
+		errors.push({
+			path,
+			message: `Param "${ref.name}" not defined in params`,
+			severity: 'error',
+		});
+	}
+	// $item is validated for Repeater ancestry in validateExpressions
+}
+
+function buildParentMap(elements: Record<string, { children?: string[] }>): Record<string, string> {
+	const parentMap: Record<string, string> = {};
+	for (const [id, element] of Object.entries(elements)) {
+		if (element.children) {
+			for (const childId of element.children) {
+				parentMap[childId] = id;
+			}
+		}
+	}
+	return parentMap;
+}
+
+function hasRepeaterAncestor(
+	elemId: string,
+	elements: Record<string, { type: string; children?: string[] }>,
+	parentMap: Record<string, string>,
+): boolean {
+	let current = parentMap[elemId];
+	while (current) {
+		if (elements[current]?.type === 'Repeater') return true;
+		current = parentMap[current];
+	}
+	return false;
+}
+
+function validateExpressions(
+	spec: PageSpec,
+	errors: ValidationError[],
+	warnings: ValidationError[],
+): void {
+	const parentMap = buildParentMap(spec.elements);
+
+	for (const [elemId, element] of Object.entries(spec.elements)) {
+		// Validate prop expressions
+		for (const [propKey, propValue] of Object.entries(element.props)) {
+			if (isExpression(propValue)) {
+				const ref = parseExpression(propValue);
+				if (!ref) {
+					errors.push({
+						path: `elements.${elemId}.props.${propKey}`,
+						message: `Invalid expression: ${propValue}`,
+						severity: 'error',
+					});
+					continue;
+				}
+				validateExpressionRef(ref, spec, `elements.${elemId}.props.${propKey}`, errors);
+
+				if (ref.type === 'item' && !hasRepeaterAncestor(elemId, spec.elements, parentMap)) {
+					warnings.push({
+						path: `elements.${elemId}.props.${propKey}`,
+						message: '$item expression used outside Repeater context',
+						severity: 'warning',
+					});
+				}
+			}
+		}
+
+		// Validate visibility expression
+		if (element.visible) {
+			const expr = element.visible.expr;
+			if (isExpression(expr)) {
+				const ref = parseExpression(expr);
+				if (!ref) {
+					errors.push({
+						path: `elements.${elemId}.visible.expr`,
+						message: `Invalid visibility expression: ${expr}`,
+						severity: 'error',
+					});
+				} else {
+					validateExpressionRef(ref, spec, `elements.${elemId}.visible.expr`, errors);
+				}
+			}
+		}
+	}
+}
+
+function validateHookDependencies(hooks: Record<string, HookDef>, errors: ValidationError[]): void {
+	for (const [hookId, hook] of Object.entries(hooks)) {
+		if (hook.use === 'useDerived' && !hooks[hook.from]) {
+			errors.push({
+				path: `hooks.${hookId}.from`,
+				message: `Derived hook "${hookId}" references undefined source hook "${hook.from}"`,
+				severity: 'error',
+			});
+		}
+	}
+}
+
+function validateHookCycles(hooks: Record<string, HookDef>, errors: ValidationError[]): void {
+	const visited = new Set<string>();
+	const inStack = new Set<string>();
+
+	function dfs(hookId: string): boolean {
+		if (inStack.has(hookId)) return true;
+		if (visited.has(hookId)) return false;
+
+		visited.add(hookId);
+		inStack.add(hookId);
+
+		const hook = hooks[hookId];
+		if (hook && hook.use === 'useDerived') {
+			if (dfs(hook.from)) {
+				errors.push({
+					path: `hooks.${hookId}`,
+					message: `Circular dependency detected involving hook "${hookId}"`,
+					severity: 'error',
+				});
+				return true;
+			}
+		}
+
+		inStack.delete(hookId);
+		return false;
+	}
+
+	for (const hookId of Object.keys(hooks)) {
+		dfs(hookId);
+	}
+}
+
+function validateActions(spec: PageSpec, errors: ValidationError[]): void {
+	for (const [actionId, action] of Object.entries(spec.actions)) {
+		if ('hookId' in action && action.type !== 'refreshHook') {
+			const hook = spec.hooks[action.hookId];
+			if (!hook) {
+				errors.push({
+					path: `actions.${actionId}.hookId`,
+					message: `Hook "${action.hookId}" not defined`,
+					severity: 'error',
+				});
+			} else if (hook.use !== 'useState') {
+				errors.push({
+					path: `actions.${actionId}.hookId`,
+					message: `Hook "${action.hookId}" is not useState (cannot mutate ${hook.use} hooks)`,
+					severity: 'error',
+				});
+			}
+		}
+	}
+}
+
+function validateComponentProps(
+	spec: PageSpec,
+	catalog: ComponentCatalog,
+	warnings: ValidationError[],
+): void {
+	for (const [elemId, element] of Object.entries(spec.elements)) {
+		const meta = catalog.components[element.type];
+		if (!meta) {
+			warnings.push({
+				path: `elements.${elemId}.type`,
+				message: `Unknown component type "${element.type}"`,
+				severity: 'warning',
+			});
+			continue;
+		}
+
+		// Build a props object with only static (non-expression) values
+		const staticProps: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(element.props)) {
+			if (isExpression(value)) continue;
+			staticProps[key] = value;
+		}
+
+		// Skip validation if all props are expressions
+		if (Object.keys(staticProps).length === 0) continue;
+
+		const result = meta.propsSchema.safeParse(staticProps);
+		if (!result.success) {
+			for (const issue of result.error.issues) {
+				warnings.push({
+					path: `elements.${elemId}.props.${issue.path.join('.')}`,
+					message: issue.message,
+					severity: 'warning',
+				});
+			}
+		}
+	}
+}
+
+const SQL_DANGEROUS_PATTERNS = [
+	/\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|EXEC|EXECUTE)\b/i,
+	/;\s*\w/, // multiple statements
+	/--/, // SQL comments (potential injection)
+	/\/\*/, // block comments
+];
+
+function validateSqlSafety(
+	hooks: Record<string, HookDef>,
+	errors: ValidationError[],
+	_warnings: ValidationError[],
+): void {
+	for (const [hookId, hook] of Object.entries(hooks)) {
+		if (hook.use !== 'useSqlQuery') continue;
+
+		const query = hook.params.query;
+
+		for (const pattern of SQL_DANGEROUS_PATTERNS) {
+			if (pattern.test(query)) {
+				errors.push({
+					path: `hooks.${hookId}.params.query`,
+					message: `Potentially unsafe SQL detected: ${pattern.source}`,
+					severity: 'error',
+				});
+			}
+		}
+
+		if (!query.trim().toUpperCase().startsWith('SELECT')) {
+			errors.push({
+				path: `hooks.${hookId}.params.query`,
+				message: 'SQL query must start with SELECT',
+				severity: 'error',
+			});
+		}
+	}
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src"]
+}