@carthooks/arcubase-cli 0.1.2 → 0.1.4

package/dist/tests/execute_validation.test.js

@@ -31,6 +31,19 @@ test('admin save entity rejects invalid body file', async () => {
         assert.equal(error.details?.requestType, 'EntitySaveReqVO');
         assert.ok((error.details?.issues ?? []).some((item) => item.path.startsWith('body.layout')));
         assert.ok((error.details?.tsHints ?? []).some((item) => item.file.startsWith('/opt/arcubase-sdk/')));
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/entity-schema.md')));
+        return true;
+    });
+});
+test('admin create app by tenants rejects name longer than 20 chars', async () => {
+    const bodyFile = tempJSONFile({ name: 'CLI Verify Happy Path' });
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['app', 'create-app-by-tenants', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.name'));
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/table-lifecycle.md')));
         return true;
     });
 });
@@ -47,3 +60,593 @@ test('admin api-prefixed command executes against external root path', async ()
     assert.equal(out.kind, 'result');
     assert.equal(out.data.url, 'https://arcubase.example.com/apps/app_1/entity-shares');
 });
+test('admin save entity treats top-level error body as failure even on http 200', async () => {
+    const bodyFile = tempJSONFile({
+        id: 2188889845,
+        app_id: 2188889844,
+        name: '订单',
+        schema_version: 1,
+        field_id_seq: 1002,
+        layout: [[1001]],
+        fields: [
+            {
+                id: 1001,
+                label: '订单号',
+                type: 'text',
+                required: true,
+                unique: false,
+                editable: true,
+                visible: true,
+                show_label: true,
+                scannable: false,
+                default_value_mode: 0,
+                description: '',
+                value: null,
+                number_decimal: 0,
+                depends: [],
+                key: 'order_id',
+                code_index: false,
+                options: {},
+                transfers: null,
+                children: null,
+            },
+        ],
+        workflow_enabled: false,
+    });
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['entity', 'admin-save-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async () => new Response(JSON.stringify({
+            error: {
+                message: 'json: cannot unmarshal object into Go struct field .EntityVO.fields of type []models.Field',
+                type: 'system',
+                key: 'error.system',
+            },
+            trace_id: 'req_xxx',
+        }), { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UPSTREAM_BODY_ERROR');
+        assert.equal(error.details?.endpoint, '/apps/app_1/entity/entity_1');
+        assert.equal(error.details?.method, 'PUT');
+        assert.equal(error.details?.traceId, 'req_xxx');
+        return true;
+    });
+});
+test('admin save entity normalizes shell null placeholders before validation', async () => {
+    const bodyFile = tempJSONFile({
+        id: 2188889845,
+        app_id: 2188889844,
+        name: '订单',
+        schema_version: 0,
+        field_id_seq: 1002,
+        layout: null,
+        current_serial: null,
+        fields: [
+            {
+                id: 1001,
+                label: '订单号',
+                type: 'text',
+                required: true,
+                unique: false,
+                editable: true,
+                visible: true,
+                show_label: true,
+                scannable: false,
+                default_value_mode: 0,
+                description: '',
+                value: null,
+                number_decimal: 0,
+                depends: [],
+                key: 'order_id',
+                code_index: false,
+                options: {
+                    placeholder: '',
+                    type: 'text',
+                    lengthLimit: false,
+                    lengthMin: 0,
+                    lengthMax: 255,
+                },
+                transfers: null,
+                children: null,
+            },
+        ],
+        options: {
+            Buttons: null,
+            CustomActions: null,
+            FrontendEvents: null,
+            TitleFormat: {
+                Fields: null,
+                Parts: null,
+                Body: '',
+            },
+            misc: null,
+        },
+        workflow_enabled: false,
+    });
+    const out = await executeCLI('admin', ['entity', 'admin-save-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    const requestBody = out.data;
+    assert.deepEqual(requestBody.layout, []);
+    assert.equal('current_serial' in requestBody, false);
+    assert.deepEqual(requestBody.options.Buttons, []);
+    assert.deepEqual(requestBody.options.CustomActions, []);
+    assert.deepEqual(requestBody.options.FrontendEvents, []);
+    assert.deepEqual(requestBody.options.TitleFormat.Fields, []);
+    assert.deepEqual(requestBody.options.TitleFormat.Parts, []);
+    assert.deepEqual(requestBody.options.misc, {});
+});
+test('delete entity row rejects selection type outside ids', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'selection',
+            ids: [4000000003],
+            length: 1,
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'delete-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.selection'));
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/search-and-bulk-actions.md')));
+        return true;
+    });
+});
+test('bulk update accepts ids selection with number_add action', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'ids',
+            ids: [4000000003],
+            length: 1,
+        },
+        fields: [
+            {
+                id: 1002,
+                action: {
+                    type: 'number_add',
+                    number_add: 10,
+                },
+            },
+        ],
+    });
+    const out = await executeCLI('user', ['entity', 'update-entity-bulk', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(out.data.selection, { type: 'ids', ids: [4000000003], length: 1 });
+    assert.equal(out.data.fields[0].action.type, 'number_add');
+});
+test('selection action accepts condition selection with selectAll', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                q: 'A-100',
+                selectAll: true,
+            },
+            sorts: [
+                { column: ':1002', order: 'desc' },
+            ],
+        },
+    });
+    const out = await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.selection.type, 'condition');
+    assert.equal(out.data.selection.condition.selectAll, true);
+});
+test('selection action accepts condition selection with filter_* keys', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                'filter_:1001': '%7B%22is%22%3A%22A-100%22%7D',
+                selectAll: true,
+            },
+        },
+    });
+    const out = await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.selection.type, 'condition');
+    assert.equal(out.data.selection.condition.selectAll, true);
+});
+test('selection action accepts condition selection with selectAll only for batch_print', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                selectAll: true,
+            },
+        },
+    });
+    const out = await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'batch_print', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.selection.type, 'condition');
+    assert.equal(out.data.selection.condition.selectAll, true);
+});
+test('selection action accepts all selection for query-style actions', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'all',
+        },
+    });
+    const out = await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.selection.type, 'all');
+});
+test('selection action rejects condition selection for query action', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                q: 'A-100',
+                selectAll: true,
+            },
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.selection.type'));
+        return true;
+    });
+});
+test('selection action rejects all selection for archive action', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'all',
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.selection.type'));
+        return true;
+    });
+});
+test('selection action rejects selectAll-only condition for archive action', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                selectAll: true,
+            },
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.selection.condition'));
+        return true;
+    });
+});
+test('insert entity rejects local file path for file field and points to arcubase upload', async () => {
+    const bodyFile = tempJSONFile({
+        fields: {
+            1001: 'Lead A',
+            1007: './contract.pdf',
+        },
+    });
+    const calls = [];
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+            calls.push({ url: String(url), method: init?.method });
+            if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+                return new Response(JSON.stringify({
+                    data: {
+                        id: 1,
+                        app_id: 1,
+                        fields: [
+                            { id: 1001, type: 'text', label: 'Lead Name' },
+                            { id: 1007, type: 'file', label: 'Contract File' },
+                        ],
+                    },
+                }), { status: 200 });
+            }
+            return new Response('{}', { status: 200 });
+        });
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.fields.1007'));
+        assert.match(error.message, /arcubase upload \.\/contract\.pdf/);
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/uploads.md')));
+        return true;
+    });
+    assert.deepEqual(calls, [
+        { url: 'https://arcubase.example.com/entity/app_1/entity_1', method: 'GET' },
+    ]);
+});
+test('update row rejects object value for image field and requires upload array', async () => {
+    const bodyFile = tempJSONFile({
+        changed_fields: [1008],
+        data: {
+            1008: {
+                upload_id: 123456,
+                file: 'lead-photo.jpg',
+                file_name: 'lead-photo.jpg',
+                meta: {},
+            },
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async (url, init) => {
+            if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+                return new Response(JSON.stringify({
+                    data: {
+                        id: 1,
+                        app_id: 1,
+                        fields: [
+                            { id: 1008, type: 'image', label: 'Lead Photo' },
+                        ],
+                    },
+                }), { status: 200 });
+            }
+            return new Response('{}', { status: 200 });
+        });
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.data.1008'));
+        assert.match(error.message, /must be an array/);
+        assert.match(error.message, /arcubase upload <local-file>/);
+        return true;
+    });
+});
+test('insert entity accepts upload array for file field after schema preflight', async () => {
+    const bodyFile = tempJSONFile({
+        fields: {
+            1001: 'Lead A',
+            1007: [
+                {
+                    upload_id: 123456,
+                    file: 'contract.pdf',
+                    file_name: 'contract.pdf',
+                    meta: {},
+                },
+            ],
+        },
+    });
+    const calls = [];
+    const out = await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+        calls.push({ url: String(url), method: init?.method });
+        if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+            return new Response(JSON.stringify({
+                data: {
+                    id: 1,
+                    app_id: 1,
+                    fields: [
+                        { id: 1001, type: 'text', label: 'Lead Name' },
+                        { id: 1007, type: 'file', label: 'Contract File' },
+                    ],
+                },
+            }), { status: 200 });
+        }
+        return new Response(String(init?.body ?? '{}'), { status: 200 });
+    });
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(calls, [
+        { url: 'https://arcubase.example.com/entity/app_1/entity_1', method: 'GET' },
+        { url: 'https://arcubase.example.com/entity/app_1/entity_1/insert', method: 'POST' },
+    ]);
+    assert.equal(out.data.fields['1007'][0].upload_id, 123456);
+});
+test('insert entity decorates upload bind failures with actionable guidance', async () => {
+    const bodyFile = tempJSONFile({
+        fields: {
+            1001: 'Lead A',
+            1007: [
+                {
+                    upload_id: 123456,
+                    file: 'contract.pdf',
+                    file_name: 'contract.pdf',
+                    meta: {},
+                },
+            ],
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+            if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+                return new Response(JSON.stringify({
+                    data: {
+                        fields: [{ id: 1007, type: 'file', label: 'Contract File' }],
+                    },
+                }), { status: 200 });
+            }
+            return new Response(JSON.stringify({
+                error: {
+                    message: 'failed to bind upload to assets: Head \"http://test-bucket.test.aliyuncs.com/upload/123456/contract.pdf\": dial tcp: lookup test-bucket.test.aliyuncs.com: no such host',
+                    type: 'system',
+                    key: 'error.system',
+                },
+                trace_id: 'req_upload_bind',
+            }), { status: 200 });
+        });
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UPSTREAM_BODY_ERROR');
+        assert.equal(error.details?.traceId, 'req_upload_bind');
+        assert.equal(error.details?.reason, 'the row payload used a file/image upload entry, but Arcubase could not bind that upload into an asset record');
+        assert.match(error.details?.hint ?? '', /rerun arcubase upload/);
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/uploads.md')));
+        return true;
+    });
+});
+test('selection action rejects condition selection without selectAll', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                q: 'A-100',
+            },
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.selection.condition.selectAll'));
+        return true;
+    });
+});
+test('selection action rejects condition selection that uses text_search instead of q/filter keys', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                text_search: 'A-100',
+                selectAll: true,
+            },
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.selection.condition'));
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/search-and-bulk-actions.md')));
+        return true;
+    });
+});
+test('bulk update accepts condition selection with q', async () => {
+    const bodyFile = tempJSONFile({
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                q: 'A-100',
+                selectAll: true,
+            },
+            sorts: [
+                { column: ':1002', order: 'desc' },
+            ],
+        },
+        fields: [
+            {
+                id: 1002,
+                action: {
+                    type: 'number_add',
+                    number_add: 2,
+                },
+            },
+        ],
+    });
+    const out = await executeCLI('user', ['entity', 'update-entity-bulk', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.selection.type, 'condition');
+    assert.equal(out.data.fields[0].action.type, 'number_add');
+});
+test('entity tags get-selection-tags accepts ids selection', async () => {
+    const bodyFile = tempJSONFile({
+        policy_id: '',
+        selection: {
+            type: 'ids',
+            ids: [4000000003],
+            length: 1,
+        },
+    });
+    const out = await executeCLI('admin', ['entity-tags', 'get-selection-tags', '--appId', 'app_1', '--entityId', 'entity_1', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.selection.type, 'ids');
+});
+test('entity tags batch-add accepts tag_names and condition selection', async () => {
+    const bodyFile = tempJSONFile({
+        policy_id: '',
+        selection: {
+            type: 'condition',
+            length: 1,
+            condition: {
+                q: 'A-100',
+                selectAll: true,
+            },
+        },
+        tag_names: ['tag-a'],
+    });
+    const out = await executeCLI('admin', ['entity-tags', 'batch-add-entity-tags', '--appId', 'app_1', '--entityId', 'entity_1', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.tag_names[0], 'tag-a');
+});
+test('invoke batch operator accepts backend request shape', async () => {
+    const bodyFile = tempJSONFile({
+        id: 'event_1',
+        data: {
+            action_id: 'action_1',
+            policy_id: '',
+            selection: {
+                type: 'all',
+            },
+        },
+        params: {},
+    });
+    const out = await executeCLI('user', ['entity', 'invoke-entity-batch-operator', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.id, 'event_1');
+    assert.equal(out.data.data.action_id, 'action_1');
+    assert.equal(out.data.data.selection.type, 'all');
+});
+test('query entity rejects camelCase viewMode and points to row crud doc', async () => {
+    const bodyFile = tempJSONFile({
+        limit: 20,
+        offset: 0,
+        viewMode: 'grid',
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'query-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.viewMode'));
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/row-crud.md')));
+        return true;
+    });
+});
+test('update entity row rejects fields key', async () => {
+    const bodyFile = tempJSONFile({
+        fields: {
+            1002: 99,
+        },
+        data: {
+            '1002': 99,
+        },
+        changed_fields: [1002],
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.fields'));
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/row-crud.md')));
+        return true;
+    });
+});
+test('update entity row rejects changed_fields that are missing from data', async () => {
+    const bodyFile = tempJSONFile({
+        data: {
+            '1002': 99,
+        },
+        changed_fields: [1003],
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.changed_fields.0'));
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/row-crud.md')));
+        return true;
+    });
+});

package/dist/tests/help.test.js

@@ -15,14 +15,63 @@ test('root help prints modules', async () => {
     assert.equal(out.kind, 'help');
     assert.match(out.text, /app/);
 });
+test('root help does not require runtime env', async () => {
+    const out = await executeCLI('admin', ['--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /modules:/);
+});
 test('module help prints create-entity command', async () => {
     const out = await executeCLI('admin', ['app', '--help'], env, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /create-entity/);
 });
+test('module help does not require runtime env', async () => {
+    const out = await executeCLI('user', ['workflow', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /delete-entity-row/);
+});
 test('command help prints normalized external endpoint', async () => {
     const out = await executeCLI('admin', ['app-entity-share', 'get-app-entity-shares', '--help'], env, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /endpoint: \/apps\/:app_id\/entity-shares/);
     assert.doesNotMatch(out.text, /endpoint: \/api\//);
 });
+test('command help does not require runtime env', async () => {
+    const out = await executeCLI('user', ['workflow', 'delete-entity-row', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /endpoint: \/entity\/:app_id\/:entity_id\/delete-item/);
+});
+test('command help prints runtime doc hints for request body commands', async () => {
+    const out = await executeCLI('user', ['workflow', 'update-entity-row', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /docs:/);
+    assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/row-crud\.md/);
+    assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/README\.md/);
+});
+test('command help prints query-file support', async () => {
+    const out = await executeCLI('user', ['workflow', 'query-entity', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /query flags: --query-file/);
+});
+test('command help without request body can still point to lifecycle and examples docs', async () => {
+    const out = await executeCLI('admin', ['entity', 'admin-get-entity-info', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/table-lifecycle\.md/);
+    assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/README\.md/);
+});
+test('admin-save-entity help prints row-operation next step', async () => {
+    const out = await executeCLI('admin', ['entity', 'admin-save-entity', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /switch to arcubase for row operations/);
+    assert.match(out.text, /arcubase workflow insert-entity/);
+    assert.match(out.text, /arcubase workflow query-entity/);
+});
+test('wrong admin workflow command points to arcubase row command', async () => {
+    await assert.rejects(() => executeCLI('admin', ['workflow', 'insert-entity'], env, async () => new Response('{}')), (error) => {
+        assert.equal(error.code, 'UNKNOWN_COMMAND');
+        assert.equal(error.details?.reason, 'workflow insert-entity is a row operation, not an arcubase-admin command');
+        assert.equal(error.details?.hint, 'use: arcubase workflow insert-entity');
+        assert.ok((error.details?.suggestions ?? []).includes('arcubase workflow insert-entity'));
+        return true;
+    });
+});