@svadmin/surface 0.6.2 → 0.7.0

package/README.md

@@ -78,6 +78,25 @@ import {
 
 When rendered inside `AdminApp`, the renderer resolves the configured provider for each resource. A trusted host may instead pass `dataProvider`, which is still narrowed to `getList` and `getOne`.
 
+## AI proposals
+
+The DOM-free root entry also exposes an opt-in Agent protocol. `buildSurfaceAgentPrompt()` constrains a model to return a proposal envelope and includes the host's widget/resource/field allowlists. `parseSurfaceAgentProposal()` parses and validates the complete `SurfaceSpec` against the same catalog and policy without querying a provider:
+
+```ts
+import {
+  buildSurfaceAgentPrompt,
+  parseSurfaceAgentProposal,
+} from '@svadmin/surface';
+
+const prompt = buildSurfaceAgentPrompt('Generate an inventory dashboard', catalog, policy);
+const proposal = parseSurfaceAgentProposal(modelText, catalog, policy);
+if (proposal.ok) {
+  // Preview proposal.value.spec, then require explicit user approval before rendering.
+}
+```
+
+The adapter is deliberately proposal-only. Persistence, revision history, audit records, and the final apply decision belong to the host application. It never executes generated code or mutation actions.
+
 ## Built-in catalog
 
 | Type | Binding | Purpose |

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "surface": "0.6.x",
+  "surface": "0.7.x",
   "minimumSupported": {
     "@svadmin/core": "0.34.2",
     "@svadmin/ui": "0.40.6",

package/dist/agent.d.ts

@@ -0,0 +1,23 @@
+import type { SurfaceCatalog, SurfacePolicy, SurfaceSpec, SurfaceValidationIssue } from './types.js';
+/** Wire version for model-produced, human-reviewable Surface proposals. */
+export declare const SURFACE_AGENT_SCHEMA_VERSION: "surface-agent/v1";
+export interface SurfaceAgentProposal {
+    readonly schemaVersion: typeof SURFACE_AGENT_SCHEMA_VERSION;
+    readonly action: 'propose';
+    readonly summary?: string;
+    readonly spec: SurfaceSpec;
+}
+export type SurfaceAgentValidationResult = {
+    readonly ok: true;
+    readonly value: SurfaceAgentProposal;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SurfaceValidationIssue[];
+};
+/**
+ * Parse and fully validate an AI-generated proposal before a host previews it.
+ * This function has no side effects and never queries a provider.
+ */
+export declare function parseSurfaceAgentProposal(input: unknown, catalog: SurfaceCatalog, policy: SurfacePolicy): SurfaceAgentValidationResult;
+/** Build a model instruction that keeps generation inside the Surface contract. */
+export declare function buildSurfaceAgentPrompt(request: string, catalog: SurfaceCatalog, policy: SurfacePolicy): string;

package/dist/agent.js

@@ -0,0 +1,78 @@
+import { Type } from '@sinclair/typebox';
+import { TypeCompiler } from '@sinclair/typebox/compiler';
+import { jsonPointer } from './json.js';
+import { validateSurfaceSpec } from './validation.js';
+/** Wire version for model-produced, human-reviewable Surface proposals. */
+export const SURFACE_AGENT_SCHEMA_VERSION = 'surface-agent/v1';
+const proposalSchema = Type.Object({
+    schemaVersion: Type.Literal(SURFACE_AGENT_SCHEMA_VERSION),
+    action: Type.Literal('propose'),
+    summary: Type.Optional(Type.String({ minLength: 1, maxLength: 240 })),
+    spec: Type.Unknown(),
+}, { additionalProperties: false });
+const compiledProposalSchema = TypeCompiler.Compile(proposalSchema);
+function parseCandidate(value) {
+    if (typeof value !== 'string')
+        return value;
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(value);
+    const source = fenced?.[1] ?? value.trim();
+    return JSON.parse(source);
+}
+function proposalIssue(message) {
+    return {
+        code: 'invalid_json',
+        path: '/',
+        message,
+    };
+}
+function proposalSchemaIssues(errors) {
+    return [...errors].map((issue) => ({
+        code: 'invalid_json',
+        path: issue.path || jsonPointer([]),
+        message: issue.message,
+    }));
+}
+/**
+ * Parse and fully validate an AI-generated proposal before a host previews it.
+ * This function has no side effects and never queries a provider.
+ */
+export function parseSurfaceAgentProposal(input, catalog, policy) {
+    let candidate;
+    try {
+        candidate = parseCandidate(input);
+    }
+    catch {
+        return { ok: false, issues: [proposalIssue('Agent proposal must be valid JSON')] };
+    }
+    if (!compiledProposalSchema.Check(candidate)) {
+        return { ok: false, issues: proposalSchemaIssues(compiledProposalSchema.Errors(candidate)) };
+    }
+    const parsed = candidate;
+    const surface = validateSurfaceSpec(parsed.spec, catalog, policy);
+    if (!surface.ok)
+        return surface;
+    return {
+        ok: true,
+        value: {
+            schemaVersion: SURFACE_AGENT_SCHEMA_VERSION,
+            action: 'propose',
+            ...(parsed.summary === undefined ? {} : { summary: parsed.summary }),
+            spec: surface.value,
+        },
+    };
+}
+/** Build a model instruction that keeps generation inside the Surface contract. */
+export function buildSurfaceAgentPrompt(request, catalog, policy) {
+    const widgetTypes = catalog.widgets.map((widget) => widget.type).join(', ') || '(none)';
+    const resources = Object.entries(policy.resources).map(([resource, resourcePolicy]) => {
+        const permissions = [
+            `read=${resourcePolicy.readFields.join(',') || '(none)'}`,
+            `filter=${resourcePolicy.filterFields?.join(',') || '(none)'}`,
+            `sort=${resourcePolicy.sortFields?.join(',') || '(none)'}`,
+            `getOne=${resourcePolicy.allowGetOne === true}`,
+            `maxPageSize=${resourcePolicy.maxPageSize ?? 'default'}`,
+        ];
+        return `${resource}(${permissions.join(';')})`;
+    }).join(' | ') || '(none)';
+    return `${request}\n\n[svadmin surface agent protocol]\nReturn only a human-reviewable fenced JSON proposal. Never generate or execute Svelte, HTML, CSS, JavaScript, SQL, URLs, event handlers, or mutations. The envelope must be {"schemaVersion":"${SURFACE_AGENT_SCHEMA_VERSION}","action":"propose","summary":"...","spec":{...}}. The spec must use schemaVersion "surface/v1" and catalogVersion "${catalog.version}". Allowed widget types: ${widgetTypes}. Resource policy: ${resources}. Use only catalog widgets and policy-authorized resources and fields. If the request cannot be represented safely, explain the limitation without inventing fields or capabilities.`;
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export type { JsonObject, JsonPrimitive, JsonValue, ResourceListDataSource, ResourceListSource, ResourceOneDataSource, ResourceOneSource, SurfaceBinding, SurfaceCatalog, SurfaceCatalogDataKind, SurfaceDataError, SurfaceDataProvider, SurfaceDataSource, SurfaceFilter, SurfaceGridLayout, SurfaceGridSpan, SurfacePolicy, SurfaceResourcePolicy, SurfaceSort, SurfaceSpec, SurfaceValidationCode, SurfaceValidationIssue, SurfaceValidationResult, SurfaceWidget, SurfaceWidgetDataState, SurfaceWidgetDefinition, } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
+export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, parseSurfaceAgentProposal, } from './agent.js';
+export type { SurfaceAgentProposal, SurfaceAgentValidationResult, } from './agent.js';

package/dist/index.js

@@ -1,2 +1,3 @@
 export { SURFACE_LIMITS, SURFACE_SCHEMA_VERSION } from './types.js';
 export { validateSurfaceSpec } from './validation.js';
+export { SURFACE_AGENT_SCHEMA_VERSION, buildSurfaceAgentPrompt, parseSurfaceAgentProposal, } from './agent.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/surface",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Validated declarative surfaces for svadmin dashboards",
   "type": "module",
   "sideEffects": false,