Skip to content

Beautiful Open-Source Form Builder

21.4 KB
Raw Blame
<?php

use App\Mcp\Servers\OpnFormServer;
use App\Mcp\Tools\CreateFormDraftTool;
use App\Mcp\Tools\GetFormDraftTool;
use App\Mcp\Tools\OpenFormDraftInEditorTool;
use App\Mcp\Tools\PatchFormDraftTool;
use App\Mcp\Tools\PreviewFormDraftTool;
use App\Models\Forms\AgentFormDraft;
use App\Service\Forms\AgentFormDraftRateLimiter;
use App\Service\Forms\AgentFormDraftService;
use Illuminate\Validation\ValidationException;

function guestDraftDefinition(array $overrides = []): array
{
    return array_replace([
        'title' => 'Customer intake',
        'properties' => [
            ['id' => 'name-field', 'name' => 'Name', 'type' => 'text'],
            ['id' => 'email-field', 'name' => 'Email', 'type' => 'email'],
        ],
    ], $overrides);
}

beforeEach(function () {
    config()->set('app.self_hosted', false);
});

it('publishes a neutral draft handle contract and accurate preview annotations', function () {
    $create = app(CreateFormDraftTool::class)->toArray();
    $preview = app(PreviewFormDraftTool::class)->toArray();
    $open = app(OpenFormDraftInEditorTool::class)->toArray();

    expect($create['outputSchema']['properties'])->toHaveKey('draft_handle')
        ->and($create['outputSchema']['properties'])->not->toHaveKey('preview_url')
        ->and($create['outputSchema']['properties'])->not->toHaveKey('draft_token')
        ->and($create['_meta'])->not->toHaveKey('ui')
        ->and(app(PatchFormDraftTool::class)->toArray()['_meta'])->not->toHaveKey('ui')
        ->and($preview['_meta']['ui']['resourceUri'])->toBe('ui://opnform/form-draft-preview.html')
        ->and($preview['_meta']['openai/outputTemplate'])->toBe('ui://opnform/form-draft-preview.html')
        ->and($preview['inputSchema']['properties'])->toHaveKey('draft_handle')
        ->and($preview['description'])
        ->toContain('modify the draft again or save it', 'Do not request OAuth unless the user chooses save')
        ->and($preview['outputSchema']['properties'])->toHaveKey('next_step')
        ->and($preview['outputSchema']['properties'])->not->toHaveKeys([
            'preview_url',
            'editor_url',
            'editor_link_expires_at',
        ])
        ->and($preview['annotations']['readOnlyHint'])->toBeTrue()
        ->and($open['_meta']['ui']['visibility'])->toBe(['model', 'app'])
        ->and($open['outputSchema']['properties'])->toHaveKey('editor_handoff_ready')
        ->and($open['outputSchema']['properties'])->not->toHaveKey('editor_url')
        ->and($open['outputSchema']['properties'])->not->toHaveKey('handoff_token');
});

it('creates a seven-day server-side guest draft and returns an opaque handle', function () {
    $before = now();

    OpnFormServer::tool(CreateFormDraftTool::class, [
        'definition' => guestDraftDefinition(['visibility' => 'public']),
    ])->assertOk()
        ->assertSee('draft_handle')
        ->assertDontSee('preview_url')
        ->assertDontSee('capability secret')
        ->assertSee('Customer intake');

    $draft = AgentFormDraft::query()->sole();

    expect($draft->token_hash)->toMatch('/^[a-f0-9]{64}$/')
        ->and($draft->definition['visibility'])->toBe('draft')
        ->and($draft->version)->toBe(1)
        ->and($draft->schema_version)->toBe(1)
        ->and($draft->status)->toBe(AgentFormDraft::STATUS_ACTIVE)
        ->and($draft->expires_at->betweenIncluded($before->copy()->addDays(7)->subSecond(), now()->addDays(7)->addSecond()))->toBeTrue();

    $this->assertDatabaseCount('forms', 0);
});

it('fetches a draft with its opaque handle without exposing stored hashes', function () {
    $created = app(AgentFormDraftService::class)->create(guestDraftDefinition());

    OpnFormServer::tool(GetFormDraftTool::class, [
        'draft_handle' => $created['token'],
    ])->assertOk()
        ->assertSee('Customer intake')
        ->assertDontSee($created['draft']->token_hash)
        ->assertDontSee('token_hash');
});

it('patches form values and blocks with optimistic versioning', function () {
    $drafts = app(AgentFormDraftService::class);
    $created = $drafts->create(guestDraftDefinition());

    $response = OpnFormServer::tool(PatchFormDraftTool::class, [
        'draft_handle' => $created['token'],
        'expected_version' => 1,
        'operations' => [
            [
                'op' => 'set_form_values',
                'values' => ['title' => 'Qualified lead', 'visibility' => 'public'],
            ],
            [
                'op' => 'update_block',
                'block_id' => 'name-field',
                'patch' => ['name' => 'Full legal name', 'required' => true],
            ],
            [
                'op' => 'add_block',
                'index' => 1,
                'block' => ['name' => 'Company', 'type' => 'text'],
            ],
            [
                'op' => 'move_block',
                'block_id' => 'email-field',
                'to_index' => 0,
            ],
        ],
    ]);

    $response->assertOk()
        ->assertSee('Qualified lead')
        ->assertSee('Full legal name')
        ->assertDontSee('preview_url')
        ->assertSee('version');

    $updated = $created['draft']->refresh();

    expect($updated->version)->toBe(2)
        ->and($updated->definition['visibility'])->toBe('draft')
        ->and($updated->definition['properties'][0]['id'])->toBe('email-field')
        ->and($updated->definition['properties'][1]['name'])->toBe('Full legal name')
        ->and($updated->definition['properties'][1]['required'])->toBeTrue()
        ->and($updated->definition['properties'][2]['name'])->toBe('Company')
        ->and($updated->definition['properties'][2]['id'])->toBeString()->not->toBeEmpty();
});

it('describes strict style values in the patch schema and field catalog', function () {
    $tool = OpnFormServer::tool(PatchFormDraftTool::class, [
        'draft_handle' => str_repeat('x', 43),
        'expected_version' => 1,
        'operations' => [[
            'op' => 'set_form_values',
            'values' => ['border_radius' => 'large'],
        ]],
    ]);

    $tool->assertHasErrors(['Draft not found, expired, or already claimed']);

    $schema = app(PatchFormDraftTool::class)->schema(new \Illuminate\JsonSchema\JsonSchemaTypeFactory());

    $styleProperties = $schema['operations']->toArray()['items']['properties']['values']['properties'];

    expect($styleProperties['presentation_style']['enum'])->toBe(['classic', 'focused'])
        ->and($styleProperties['width']['enum'])->toBe(['centered', 'full'])
        ->and($styleProperties['size']['enum'])->toBe(['sm', 'md', 'lg'])
        ->and($styleProperties['theme']['enum'])->toBe(['default', 'simple', 'notion', 'minimal', 'transparent'])
        ->and($styleProperties['border_radius']['enum'])->toBe(['none', 'small', 'full'])
        ->and(\App\Service\Forms\AgentFormFieldCatalog::reference()['form_style']['border_radius'])
        ->toBe(['none', 'small', 'full']);
});

it('publishes and applies computed variable and display logic draft patches', function () {
    $schema = app(PatchFormDraftTool::class)->schema(new \Illuminate\JsonSchema\JsonSchemaTypeFactory());
    $operationProperties = $schema['operations']->toArray()['items']['properties'];

    expect($operationProperties['values']['properties']['computed_variables']['items']['properties'])
        ->toHaveKeys(['id', 'name', 'formula', 'result_type'])
        ->and($operationProperties['block']['properties'])
        ->toHaveKeys(['hidden', 'logic'])
        ->and($operationProperties['patch']['properties'])
        ->toHaveKeys(['hidden', 'logic'])
        ->and($operationProperties['patch']['properties']['logic']['type'])
        ->toBe(['object', 'null'])
        ->and($operationProperties['patch']['properties']['logic']['properties']['conditions']['properties']['value']['properties']['value']['type'])
        ->toBe(['string', 'number', 'boolean', 'object', 'array', 'null'])
        ->and($operationProperties['patch']['properties']['logic']['properties']['actions']['items']['enum'])
        ->toContain('show-block', 'hide-block', 'require-answer');

    $drafts = app(AgentFormDraftService::class);
    $created = $drafts->create(guestDraftDefinition([
        'properties' => [
            ['id' => 'budget', 'name' => 'Budget', 'type' => 'number'],
            ['id' => 'details', 'name' => 'Details', 'type' => 'text'],
        ],
    ]));

    OpnFormServer::tool(PatchFormDraftTool::class, [
        'draft_handle' => $created['token'],
        'expected_version' => 1,
        'operations' => [
            [
                'op' => 'set_form_values',
                'values' => [
                    'computed_variables' => [[
                        'id' => 'cv_priority_score',
                        'name' => 'Priority score',
                        'formula' => '{budget} * 1.5',
                        'result_type' => 'number',
                    ]],
                ],
            ],
            [
                'op' => 'update_block',
                'block_id' => 'details',
                'patch' => [
                    'hidden' => true,
                    'logic' => [
                        'conditions' => [
                            'operatorIdentifier' => 'and',
                            'children' => [[
                                'identifier' => 'cv_priority_score',
                                'value' => [
                                    'operator' => 'greater_than',
                                    'property_meta' => ['id' => 'cv_priority_score', 'type' => 'computed'],
                                    'value' => 15000,
                                ],
                            ]],
                        ],
                        'actions' => ['show-block'],
                    ],
                ],
            ],
        ],
    ])->assertOk();

    $definition = $created['draft']->refresh()->definition;
    expect($created['draft']->version)->toBe(2)
        ->and($definition['computed_variables'][0]['formula'])->toBe('{budget} * 1.5')
        ->and($definition['properties'][1]['hidden'])->toBeTrue()
        ->and($definition['properties'][1]['logic']['conditions']['children'][0]['value']['value'])
        ->toBe(15000);
});

it('returns actionable validation errors for invalid style values', function () {
    $drafts = app(AgentFormDraftService::class);
    $created = $drafts->create(guestDraftDefinition());

    OpnFormServer::tool(PatchFormDraftTool::class, [
        'draft_handle' => $created['token'],
        'expected_version' => 1,
        'operations' => [[
            'op' => 'set_form_values',
            'values' => ['border_radius' => 'large'],
        ]],
    ])->assertHasErrors(['border_radius must be one of: none, small, full.']);
});

it('rejects stale patches without changing the draft', function () {
    $drafts = app(AgentFormDraftService::class);
    $created = $drafts->create(guestDraftDefinition());

    $drafts->patch($created['token'], 1, [[
        'op' => 'set_form_values',
        'values' => ['title' => 'First update'],
    ]]);

    OpnFormServer::tool(PatchFormDraftTool::class, [
        'draft_handle' => $created['token'],
        'expected_version' => 1,
        'operations' => [[
            'op' => 'set_form_values',
            'values' => ['title' => 'Stale overwrite'],
        ]],
    ])->assertHasErrors(['Current version is 2']);

    expect($created['draft']->refresh()->definition['title'])->toBe('First update')
        ->and($created['draft']->version)->toBe(2);
});

it('rolls back invalid patch operations and preserves the previous version', function () {
    $drafts = app(AgentFormDraftService::class);
    $created = $drafts->create(guestDraftDefinition([
        'properties' => [
            ['id' => 'only-field', 'name' => 'Name', 'type' => 'text'],
        ],
    ]));

    OpnFormServer::tool(PatchFormDraftTool::class, [
        'draft_handle' => $created['token'],
        'expected_version' => 1,
        'operations' => [[
            'op' => 'remove_block',
            'block_id' => 'only-field',
        ]],
    ])->assertHasErrors();

    expect($created['draft']->refresh()->version)->toBe(1)
        ->and($created['draft']->definition['properties'])->toHaveCount(1);
});

it('cleans dependent variables and logic after removing an MCP draft block', function () {
    $drafts = app(AgentFormDraftService::class);
    $created = $drafts->create(guestDraftDefinition([
        'properties' => [
            ['id' => 'amount', 'name' => 'Amount', 'type' => 'number'],
            [
                'id' => 'details',
                'name' => 'Details',
                'type' => 'text',
                'hidden' => true,
                'logic' => [
                    'conditions' => [
                        'identifier' => 'cv_double',
                        'value' => [
                            'operator' => 'greater_than',
                            'property_meta' => ['id' => 'cv_double', 'type' => 'computed'],
                            'value' => 10,
                        ],
                    ],
                    'actions' => ['show-block'],
                ],
            ],
        ],
        'computed_variables' => [
            ['id' => 'cv_base', 'name' => 'Base', 'formula' => '{amount}', 'result_type' => 'number'],
            ['id' => 'cv_double', 'name' => 'Double', 'formula' => '{cv_base} * 2', 'result_type' => 'number'],
        ],
    ]));

    OpnFormServer::tool(PatchFormDraftTool::class, [
        'draft_handle' => $created['token'],
        'expected_version' => 1,
        'operations' => [[
            'op' => 'remove_block',
            'block_id' => 'amount',
        ]],
    ])->assertOk();

    $definition = $created['draft']->refresh()->definition;
    expect($definition['computed_variables'])->toBeEmpty()
        ->and($definition['properties'][0]['id'])->toBe('details')
        ->and($definition['properties'][0])->not->toHaveKey('logic');
});

it('rejects malformed, expired, and claimed draft capabilities with one generic error', function () {
    $drafts = app(AgentFormDraftService::class);
    $created = $drafts->create(guestDraftDefinition());

    OpnFormServer::tool(GetFormDraftTool::class, [
        'draft_handle' => str_repeat('x', 43),
    ])->assertHasErrors(['Draft not found, expired, or already claimed']);

    $created['draft']->forceFill(['expires_at' => now()->subSecond()])->save();

    OpnFormServer::tool(GetFormDraftTool::class, [
        'draft_handle' => $created['token'],
    ])->assertHasErrors(['Draft not found, expired, or already claimed']);

    $claimed = $drafts->create(guestDraftDefinition());
    $claimed['draft']->forceFill(['status' => AgentFormDraft::STATUS_CLAIMED])->save();

    OpnFormServer::tool(GetFormDraftTool::class, [
        'draft_handle' => $claimed['token'],
    ])->assertHasErrors(['Draft not found, expired, or already claimed']);
});

it('rejects duplicate block ids', function () {
    OpnFormServer::tool(CreateFormDraftTool::class, [
        'definition' => guestDraftDefinition([
            'properties' => [
                ['id' => 'duplicate', 'name' => 'One', 'type' => 'text'],
                ['id' => 'duplicate', 'name' => 'Two', 'type' => 'email'],
            ],
        ]),
    ])->assertHasErrors([
        'properties.1.id',
        'The field ID [duplicate] is already used by field 1.',
    ]);
});

it('accepts computed variables as display logic sources', function () {
    OpnFormServer::tool(CreateFormDraftTool::class, [
        'definition' => guestDraftDefinition([
            'properties' => [
                ['id' => 'amount', 'name' => 'Amount', 'type' => 'number'],
                [
                    'id' => 'details',
                    'name' => 'Details',
                    'type' => 'text',
                    'hidden' => true,
                    'logic' => [
                        'conditions' => [
                            'operatorIdentifier' => 'and',
                            'children' => [[
                                'identifier' => 'cv_total',
                                'value' => [
                                    'operator' => 'greater_than',
                                    'property_meta' => ['id' => 'cv_total', 'type' => 'computed'],
                                    'value' => 100,
                                ],
                            ]],
                        ],
                        'actions' => ['show-block'],
                    ],
                ],
            ],
            'computed_variables' => [[
                'id' => 'cv_total',
                'name' => 'Total',
                'formula' => '{amount} * 2',
                'result_type' => 'number',
            ]],
        ]),
    ])->assertOk();

    $this->assertDatabaseCount('agent_form_drafts', 1);
    $condition = AgentFormDraft::query()->firstOrFail()
        ->definition['properties'][1]['logic']['conditions']['children'][0];
    expect($condition['identifier'])->toBe('cv_total')
        ->and($condition['value']['property_meta'])->toBe(['id' => 'cv_total', 'type' => 'computed']);
});

it('removes display logic with missing MCP references before persisting', function () {
    OpnFormServer::tool(CreateFormDraftTool::class, [
        'definition' => guestDraftDefinition([
            'properties' => [[
                'id' => 'details',
                'name' => 'Details',
                'type' => 'text',
                'logic' => [
                    'conditions' => [
                        'operatorIdentifier' => 'and',
                        'children' => [[
                            'identifier' => 'removed',
                            'value' => [
                                'operator' => 'equals',
                                'property_meta' => ['id' => 'removed', 'type' => 'text'],
                                'value' => 'yes',
                            ],
                        ]],
                    ],
                    'actions' => ['show-block'],
                ],
            ]],
        ]),
    ])->assertOk();

    $this->assertDatabaseCount('agent_form_drafts', 1);
    expect(AgentFormDraft::query()->firstOrFail()->definition['properties'][0])->not->toHaveKey('logic');
});

it('rejects machine-like labels before persisting a guest draft', function () {
    OpnFormServer::tool(CreateFormDraftTool::class, [
        'definition' => guestDraftDefinition([
            'properties' => [
                ['id' => 'full-name', 'name' => 'full_name', 'type' => 'text'],
                ['id' => 'contact-email', 'name' => 'contact_email', 'type' => 'email'],
            ],
        ]),
    ])->assertHasErrors([
        'properties.0.name: Replace the raw label [full_name] with clear respondent-facing copy in sentence case.',
        'properties.1.name: Replace the raw label [contact_email] with clear respondent-facing copy in sentence case.',
    ]);

    $this->assertDatabaseCount('agent_form_drafts', 0);
});

it('rejects markdown text blocks before persisting a guest draft', function () {
    OpnFormServer::tool(CreateFormDraftTool::class, [
        'definition' => guestDraftDefinition([
            'properties' => [[
                'id' => 'introduction',
                'name' => 'Introduction',
                'type' => 'nf-text',
                'content' => '# Contact us\n\n**Tell us how we can help.**',
            ]],
        ]),
    ])->assertHasErrors([
        'properties.0.content: Replace Markdown with sanitized HTML',
    ]);

    $this->assertDatabaseCount('agent_form_drafts', 0);
});

it('rejects oversized draft definitions before persistence', function () {
    OpnFormServer::tool(CreateFormDraftTool::class, [
        'definition' => guestDraftDefinition([
            'custom_code' => str_repeat('x', 1_000_001),
        ]),
    ])->assertHasErrors(['must not exceed 1 MB']);

    $this->assertDatabaseCount('agent_form_drafts', 0);
});

it('sanitizes rich text html before an agent draft can be rendered', function () {
    $created = app(AgentFormDraftService::class)->create(guestDraftDefinition([
        'properties' => [[
            'id' => 'rich-text',
            'name' => 'Introduction',
            'type' => 'nf-text',
            'content' => '<p>Hello</p><img src=x onerror="alert(1)"><script>alert(2)</script>',
        ]],
    ]));

    $content = $created['draft']->definition['properties'][0]['content'];
    expect($content)->toContain('<p>Hello</p>')
        ->not->toContain('onerror')
        ->not->toContain('<script');
});

it('rate limits only excessive draft creation bursts', function () {
    config()->set('opnform.mcp.rate_limit.draft_creates_per_minute', 2);
    config()->set('opnform.mcp.rate_limit.draft_creates_per_hour', 10);
    $limiter = app(AgentFormDraftRateLimiter::class);

    $limiter->hit('ip:192.0.2.1');
    $limiter->hit('ip:192.0.2.1');

    expect(fn () => $limiter->hit('ip:192.0.2.1'))
        ->toThrow(ValidationException::class, 'Too many drafts');

    expect(fn () => $limiter->hit('ip:192.0.2.2'))->not->toThrow(ValidationException::class);
});

it('purges only expired agent drafts with the scheduled command', function () {
    $drafts = app(AgentFormDraftService::class);
    $active = $drafts->create(guestDraftDefinition())['draft'];
    $expired = $drafts->create(guestDraftDefinition())['draft'];
    $expired->forceFill(['expires_at' => now()->subMinute()])->save();

    $this->artisan('agent-drafts:purge-expired')
        ->expectsOutput('Purged 1 expired agent form draft(s).')
        ->assertSuccessful();

    $this->assertDatabaseHas('agent_form_drafts', ['id' => $active->id]);
    $this->assertDatabaseMissing('agent_form_drafts', ['id' => $expired->id]);
});