@carthooks/arcubase-cli 0.1.10 → 0.1.13

package/dist/tests/execute_validation.test.js

@@ -8,6 +8,7 @@ import { CLIError } from '../runtime/errors.js';
 const env = {
     ARCUBASE_BASE_URL: 'https://arcubase.example.com',
     ARCUBASE_ACCESS_TOKEN: 'tok',
+    ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
     ARCUBASE_TRACE_ID: '',
     ARCUBASE_SUBJECT_TYPE: '',
     ARCUBASE_SUBJECT_ID: '',
@@ -19,6 +20,22 @@ function tempJSONFile(payload) {
     fs.writeFileSync(filePath, JSON.stringify(payload, null, 2));
     return filePath;
 }
+function withRowPolicyResolver(tableId = 'table_1', actions = ['view', 'add', 'edit', 'delete', 'bulk_update', 'archive'], policyOverridesOrFinal = {}, final) {
+    const policyOverrides = typeof policyOverridesOrFinal === 'function' ? {} : policyOverridesOrFinal;
+    const finalFetch = typeof policyOverridesOrFinal === 'function'
+        ? policyOverridesOrFinal
+        : final ?? (async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    return async (url, init) => {
+        const text = String(url);
+        if (/\/api\/apps\/[^/?]+$/.test(text) && init?.method === 'GET') {
+            return new Response(JSON.stringify({ data: { ingress: { groups: [{ items: [{ id: 'policy_hash_1' }] }] } } }), { status: 200 });
+        }
+        if (/\/api\/ingress\/[^/]+\/policy_hash_1$/.test(text) && init?.method === 'GET') {
+            return new Response(JSON.stringify({ data: { id: tableId, policy: { actions, ...policyOverrides } } }), { status: 200 });
+        }
+        return finalFetch(url, init);
+    };
+}
 function assertAssignUsersGuidance(error, messagePattern) {
     assert.ok(error instanceof CLIError);
     assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -29,7 +46,7 @@ function assertAssignUsersGuidance(error, messagePattern) {
     assert.deepEqual(error.details?.shapeHint, {
         update: ['user_scope'],
         options: {
-            user_scope: [{ type: 'member', id: 123 }],
+            user_scope: [{ type: 'user', id: 2188889901 }],
         },
     });
     assert.deepEqual(error.details?.commonMistakes, [
@@ -38,9 +55,9 @@ function assertAssignUsersGuidance(error, messagePattern) {
         'do not use hash tenant user id as id',
         'id must be numeric TenantUser.ID',
     ]);
-    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'AppIngressUpdateReqVO' && item.file === '/opt/arcubase-sdk/types/ingress.ts'));
-    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'EntityIngressOptions' && item.file === '/opt/arcubase-sdk/types/ingress.ts'));
-    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'PermitUserScope' && item.file === '/opt/arcubase-sdk/types/common.ts'));
+    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'AppIngressUpdateReqVO' && item.file === '/runtime/arcubase-sdk/types/ingress.ts'));
+    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'EntityIngressOptions' && item.file === '/runtime/arcubase-sdk/types/ingress.ts'));
+    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'PermitUserScope' && item.file === '/runtime/arcubase-sdk/types/common.ts'));
     return true;
 }
 function validEntitySavePayload(overrides = {}) {
@@ -104,6 +121,15 @@ test('table update-schema rejects invalid body file', async () => {
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
         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.symbol === 'EntitySaveReqVO' && item.file === '/runtime/arcubase-sdk/types/entity.ts'));
+        assert.ok(error.details?.docHints?.some((item) => item.file === '/runtime/arcubase-sdk/docs/runtime-reference/entity-schema.md'));
+        assert.equal(error.details?.shapeHint?.field_id_seq, 1004);
+        assert.equal(error.details?.shapeHint?.fields?.[0]?.type, 'text');
+        assert.equal(error.details?.shapeHint?.fields?.[1]?.type, 'textarea');
+        assert.equal(error.details?.shapeHint?.fields?.[2]?.type, 'select');
+        assert.ok((error.details?.commonMistakes ?? []).some((item) => item.includes('fields must be an array')));
+        assert.ok((error.details?.commonMistakes ?? []).some((item) => item.includes('get table shell first')));
+        assert.ok((error.details?.commonMistakes ?? []).some((item) => item.includes('not "string"')));
         return true;
     });
 });
@@ -118,28 +144,56 @@ test('app create rejects name longer than 20 chars', async () => {
         return true;
     });
 });
-test('table create executes with valid body file', async () => {
-    const bodyFile = tempJSONFile({ name: '订单', parent: 0 });
-    const out = await executeCLI('admin', ['table', 'create', '--app-id', 'app_1', '--body-file', bodyFile], env, async (url, init) => new Response(JSON.stringify({
-        url,
-        method: init?.method,
-        hasTenantHeader: Object.prototype.hasOwnProperty.call(init?.headers ?? {}, 'X-Tenant-Id'),
-        hasHostHeader: Object.prototype.hasOwnProperty.call(init?.headers ?? {}, 'X-Host'),
-    }), { status: 200 }));
+test('table create rejects empty schema body before request', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['table', 'create', '--app-id', '2188889844', '--body-json', '{"name":"订单","parent":0}'], env, async () => new Response('{}'));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /fields/);
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('arcubase-admin table create --app-id <app_id> --body-json')));
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('"field_id_seq":1003')));
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('"投票描述"')));
+        return true;
+    });
+});
+test('table create executes create and schema save with valid body file', async () => {
+    const bodyFile = tempJSONFile({ ...validEntitySavePayload({ id: undefined, app_id: undefined }), name: '订单', parent: 0 });
+    const calls = [];
+    const out = await executeCLI('admin', ['table', 'create', '--app-id', '2188889844', '--body-file', bodyFile], env, async (url, init) => {
+        calls.push({ url: String(url), method: init?.method, body: init?.body ? JSON.parse(String(init.body)) : null });
+        if (init?.method === 'POST') {
+            return new Response(JSON.stringify({ data: { id: 2188889845 } }), { status: 200 });
+        }
+        return new Response(JSON.stringify({ data: { id: 2188889845, fields: calls[1]?.body?.fields ?? [] } }), { status: 200 });
+    });
     assert.equal(out.kind, 'result');
-    assert.equal(out.data.url, 'https://arcubase.example.com/api/apps/app_1/entities');
-    assert.equal(out.data.hasTenantHeader, false);
-    assert.equal(out.data.hasHostHeader, false);
+    assert.equal(out.data.id, 2188889845);
+    assert.equal(calls.length, 2);
+    assert.equal(calls[0].url, 'https://arcubase.example.com/api/apps/2188889844/entities');
+    assert.equal(calls[0].method, 'POST');
+    assert.deepEqual(calls[0].body, { name: '订单', parent: 0 });
+    assert.equal(calls[1].url, 'https://arcubase.example.com/api/apps/2188889844/entity/2188889845');
+    assert.equal(calls[1].method, 'PUT');
+    assert.equal(calls[1].body.id, 2188889845);
+    assert.equal(calls[1].body.app_id, 2188889844);
+    assert.equal(calls[1].body.fields.length, 1);
 });
 test('table create executes with valid body json', async () => {
-    const out = await executeCLI('admin', ['table', 'create', '--app-id', 'app_1', '--body-json', '{"name":"订单","parent":0}'], env, async (url, init) => new Response(JSON.stringify({
-        url,
-        method: init?.method,
-        body: init?.body ? JSON.parse(String(init.body)) : null,
-    }), { status: 200 }));
+    const calls = [];
+    const payload = JSON.stringify({ ...validEntitySavePayload({ id: undefined, app_id: undefined }), name: '订单', parent: 0 });
+    const out = await executeCLI('admin', ['table', 'create', '--app-id', '2188889844', '--body-json', payload], env, async (url, init) => {
+        calls.push({ url: String(url), method: init?.method, body: init?.body ? JSON.parse(String(init.body)) : null });
+        if (init?.method === 'POST') {
+            return new Response(JSON.stringify({ data: { id: 2188889845 } }), { status: 200 });
+        }
+        return new Response(JSON.stringify({ data: { id: 2188889845, fields: calls[1]?.body?.fields ?? [] } }), { status: 200 });
+    });
     assert.equal(out.kind, 'result');
-    assert.equal(out.data.url, 'https://arcubase.example.com/api/apps/app_1/entities');
-    assert.deepEqual(out.data.body, { name: '订单', parent: 0 });
+    assert.equal(out.data.id, 2188889845);
+    assert.equal(calls.length, 2);
+    assert.deepEqual(calls[0].body, { name: '订单', parent: 0 });
+    assert.equal(calls[1].body.id, 2188889845);
 });
 test('body json conflicts with body file', async () => {
     const bodyFile = tempJSONFile({ name: '订单', parent: 0 });
@@ -160,6 +214,21 @@ test('body json is rejected for commands without request type', async () => {
         return true;
     });
 });
+test('entry rejects retired include-app-tables flag before fetch', async () => {
+    let called = false;
+    await assert.rejects(async () => {
+        await executeCLI('user', ['entry', '--include-app-tables'], env, async () => {
+            called = true;
+            return new Response('{}', { status: 200 });
+        });
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UNKNOWN_FLAG');
+        assert.match(error.message, /--include-app-tables/);
+        return true;
+    });
+    assert.equal(called, false);
+});
 test('body json parse errors fail fast', async () => {
     await assert.rejects(async () => {
         await executeCLI('admin', ['table', 'create', '--app-id', 'app_1', '--body-json', '{"name":'], env, async () => new Response('{}', { status: 200 }));
@@ -169,6 +238,49 @@ test('body json parse errors fail fast', async () => {
         return true;
     });
 });
+test('body json parse errors include command docs and type hints', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'update', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["options"]}]}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'INVALID_BODY_JSON');
+        assert.equal(error.details?.requestType, 'AppIngressUpdateReqVO');
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file === '/runtime/arcubase-sdk/docs/runtime-reference/access-rule.md'));
+        assert.ok((error.details?.commonMistakes ?? []).some((item) => item.includes('access-rule update policy changes')));
+        return true;
+    });
+});
+test('access-rule invalid json returns copyable create retry examples', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-json', '{"name":"Admin full access","enabled":true,"type":"form","options":{"user_scope":[{"type":"user","id":2188889977}],"policy":{"key":"custom","actions":["view","add","edit","delete"],"all_fields_read":true,"all_fields_write":true},"list_options":{}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'INVALID_BODY_JSON');
+        assert.equal(error.details?.requestType, 'AppIngressCreateReqVO');
+        assert.match(error.message, /retryToolCalls/);
+        const toolCall = (error.details?.retryToolCalls ?? [])[0];
+        assert.ok(toolCall);
+        assert.equal(toolCall.command, 'access-rule create');
+        assert.deepEqual(toolCall.args.slice(0, 5), ['--app-id', '<app_id>', '--table-id', '<table_id>', '--body-json']);
+        const body = JSON.parse(toolCall.args[5]);
+        assert.deepEqual(body, {
+            name: 'Admin full access',
+            enabled: true,
+            type: 'form',
+            options: {
+                user_scope: [{ type: 'user', id: 2188889977 }],
+                policy: {
+                    key: 'custom',
+                    actions: ['view', 'add', 'edit', 'delete'],
+                    all_fields_read: true,
+                    all_fields_write: true,
+                },
+                list_options: {},
+            },
+        });
+        return true;
+    });
+});
 test('access-rule list executes against external root path', async () => {
     const out = await executeCLI('admin', ['access-rule', 'list', '--app-id', 'app_1', '--table-id', 'table_1'], env, async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }));
     assert.equal(out.kind, 'result');
@@ -215,6 +327,30 @@ test('table update-schema normalizes shell null placeholders before validation',
     assert.deepEqual(requestBody.options.TitleFormat.Parts, []);
     assert.deepEqual(requestBody.options.misc, {});
 });
+test('table update-schema rejects per-user permission patches', async () => {
+    const body = JSON.stringify({
+        id: 2188893443,
+        app_id: 2188893436,
+        name: '投票项目',
+        schema_version: 1,
+        field_id_seq: 1003,
+        layout: [[1001], [1002]],
+        fields: [
+            { id: 1001, label: 'Title', 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: 'title', code_index: false, options: { type: 'text', placeholder: '', lengthLimit: false, lengthMin: 0, lengthMax: 255 }, transfers: null, children: null },
+            { id: 1002, label: 'Description', type: 'textarea', required: false, unique: false, editable: true, visible: true, show_label: true, scannable: false, default_value_mode: 0, description: '', value: null, number_decimal: 0, depends: [], key: 'description', code_index: false, options: { placeholder: '', html: false, size: 'default', lengthLimit: false, lengthMin: 0, lengthMax: 2000 }, transfers: null, children: null, permission: { user: { read: false } } },
+        ],
+        options: { Buttons: [], CustomActions: [], FrontendEvents: [], TitleFormat: { Fields: [], Parts: [], Body: '' }, misc: {} },
+        workflow_enabled: false,
+    });
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['table', 'update-schema', '--app-id', 'app_1', '--table-id', 'table_1', '--body-json', body], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /access-rule/);
+        return true;
+    });
+});
 test('row delete rejects selection type outside ids', async () => {
     const bodyFile = tempJSONFile({ selection: { type: 'selection', ids: [4000000003], length: 1 } });
     await assert.rejects(async () => {
@@ -231,7 +367,7 @@ test('row bulk-update accepts ids selection with number_add action', async () =>
         selection: { type: 'ids', ids: [4000000003], length: 1 },
         fields: [{ id: 1002, action: { type: 'number_add', number_add: 10 } }],
     });
-    const out = await executeCLI('user', ['row', 'bulk-update', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    const out = await executeCLI('user', ['row', 'bulk-update', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile], env, withRowPolicyResolver());
     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');
@@ -245,7 +381,7 @@ test('row selection-action accepts condition selection with selectAll', async ()
             sorts: [{ column: ':1002', order: 'desc' }],
         },
     });
-    const out = await executeCLI('user', ['row', 'selection-action', '--app-id', 'app_1', '--table-id', 'table_1', '--action', 'archive', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    const out = await executeCLI('user', ['row', 'selection-action', '--app-id', 'app_1', '--table-id', 'table_1', '--action', 'archive', '--body-file', bodyFile], env, withRowPolicyResolver());
     assert.equal(out.kind, 'result');
     assert.equal(out.data.selection.type, 'condition');
     assert.equal(out.data.selection.condition.selectAll, true);
@@ -261,7 +397,124 @@ test('row selection-action rejects condition selection for query action', async
         return true;
     });
 });
-test('row create rejects local file path for file field and points to arcubase upload', async () => {
+test('row create resolves internal policy_id from accessible ingress', async () => {
+    const bodyFile = tempJSONFile({ fields: { 1001: '今天吃什么' } });
+    const calls = [];
+    const out = await executeCLI('user', ['row', 'create', '--app-id', '2188900691', '--table-id', '2188900694', '--body-file', bodyFile], env, withRowPolicyResolver('2188900694', ['view', 'add'], async (url, init) => {
+        calls.push({
+            url: String(url),
+            method: init?.method,
+            body: init?.body ? JSON.parse(String(init.body)) : null,
+        });
+        return new Response(String(init?.body ?? '{}'), { status: 200 });
+    }));
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(calls, [
+        { url: 'https://arcubase.example.com/api/entity/2188900691/2188900694', method: 'GET', body: null },
+        {
+            url: 'https://arcubase.example.com/api/entity/2188900691/2188900694/insert',
+            method: 'POST',
+            body: { fields: { 1001: '今天吃什么' }, policy_id: 'policy_hash_1' },
+        },
+    ]);
+});
+test('row get resolves internal policy_id as query parameter', async () => {
+    const calls = [];
+    const out = await executeCLI('user', ['row', 'get', '--app-id', '2188900691', '--table-id', '2188900694', '--row-id', '4000000046'], env, withRowPolicyResolver('2188900694', ['view'], async (url) => {
+        calls.push(String(url));
+        return new Response(JSON.stringify({ data: { id: 4000000046 } }), { status: 200 });
+    }));
+    assert.equal(out.kind, 'result');
+    assert.equal(calls[0], 'https://arcubase.example.com/api/entity/2188900691/2188900694/row/4000000046?policy_id=policy_hash_1');
+});
+test('row get returns machine-readable row value evidence', async () => {
+    const out = await executeCLI('user', ['row', 'get', '--app-id', '2188900691', '--table-id', '2188900694', '--row-id', '4000000046'], env, withRowPolicyResolver('2188900694', ['view'], async () => new Response(JSON.stringify({
+        data: {
+            record: {
+                id: 4000000046,
+                fields: { 1001: '复测投票' },
+            },
+            fieldPermits: {
+                all_fields_read: false,
+                fields: [
+                    { key: ':1001', read: true, write: true, report: false },
+                    { key: ':1002', read: false, write: false, report: false },
+                    { key: ':1003', read: true, write: true, report: false },
+                ],
+            },
+        },
+    }), { status: 200 })));
+    assert.deepEqual(out.rowValueEvidence, {
+        source: 'row get record.fields',
+        returnedFieldIds: ['1001'],
+        notReturnedFieldIds: ['1002', '1003'],
+        deniedReadFieldIds: ['1002'],
+        absentFieldMeaning: 'not returned to current user; no row-value evidence',
+        rules: [
+            'current row values come only from row query fields or row get record.fields',
+            'table schema fields[].value and default_value_mode are schema defaults, not returned row values',
+            'a field id absent from returned row fields has no row-value evidence',
+            'read visibility status is fieldPermits read:false; FIELD_PERMISSION_REQUIRED is only a write preflight error',
+        ],
+    });
+});
+test('row command rejects user-provided policy_id', async () => {
+    const bodyFile = tempJSONFile({ fields: { 1001: '今天吃什么' }, policy_id: 'manual_policy' });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['row', 'create', '--app-id', '2188900691', '--table-id', '2188900694', '--body-file', bodyFile], env, withRowPolicyResolver('2188900694', ['add']));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'INTERNAL_POLICY_ID_NOT_ALLOWED');
+        assert.match(error.message, /internal Arcubase ingress parameter/);
+        return true;
+    });
+});
+test('row command fastfails when no accessible ingress matches action', async () => {
+    const bodyFile = tempJSONFile({ fields: { 1001: '今天吃什么' } });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['row', 'create', '--app-id', '2188900691', '--table-id', '2188900694', '--body-file', bodyFile], env, withRowPolicyResolver('2188900694', ['view']));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'POLICY_ID_RESOLUTION_FAILED');
+        assert.match(error.message, /action add/);
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('access-rule')));
+        return true;
+    });
+});
+test('row create fastfails before request when payload writes non-writable field', async () => {
+    const bodyFile = tempJSONFile({ fields: { 1001: '标题', 1002: '隐藏描述' } });
+    const calls = [];
+    await assert.rejects(async () => {
+        await executeCLI('user', ['row', 'create', '--app-id', '2188900691', '--table-id', '2188900694', '--body-file', bodyFile], env, withRowPolicyResolver('2188900694', ['view', 'add'], { all_fields_write: true, fields: [{ key: ':1002', read: false, write: false, report: false }] }, async (url, init) => {
+            calls.push({ url: String(url), method: init?.method });
+            return new Response(String(init?.body ?? '{}'), { status: 200 });
+        }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'FIELD_PERMISSION_REQUIRED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.fields.1002'));
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('remove non-writable field ids')));
+        return true;
+    });
+    assert.equal(calls.some((call) => call.method !== 'GET'), false);
+});
+test('row update fastfails before request when payload writes non-writable field', async () => {
+    const bodyFile = tempJSONFile({ data: { 1002: '隐藏描述' }, changed_fields: [1002] });
+    const calls = [];
+    await assert.rejects(async () => {
+        await executeCLI('user', ['row', 'update', '--app-id', '2188900691', '--table-id', '2188900694', '--row-id', '2188901452', '--body-file', bodyFile], env, withRowPolicyResolver('2188900694', ['view', 'edit'], { all_fields_write: false, fields: [{ key: ':1001', read: true, write: true, report: false }, { key: ':1002', read: false, write: false, report: false }] }, async (url, init) => {
+            calls.push({ url: String(url), method: init?.method });
+            return new Response(String(init?.body ?? '{}'), { status: 200 });
+        }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'FIELD_PERMISSION_REQUIRED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.data.1002'));
+        return true;
+    });
+    assert.equal(calls.some((call) => call.method !== 'GET'), false);
+});
+test('row create rejects local file path for file field and points to upload token flow', async () => {
     const bodyFile = tempJSONFile({ fields: { 1001: 'Lead A', 1007: './contract.pdf' } });
     const calls = [];
     await assert.rejects(async () => {
@@ -276,11 +529,24 @@ test('row create rejects local file path for file field and points to arcubase u
         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.match(error.message, /upload token flow/);
         return true;
     });
     assert.deepEqual(calls, [{ url: 'https://arcubase.example.com/api/entity/app_1/table_1', method: 'GET' }]);
 });
+test('row create non-numeric field key gives table get retry path', async () => {
+    const bodyFile = tempJSONFile({ fields: { 标题: '今天吃什么' } });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['row', 'create', '--app-id', '2188900691', '--table-id', '2188900694', '--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?.commonMistakes?.some((item) => item.includes('do not use field labels')));
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('arcubase table get')));
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('arcubase row create')));
+        return true;
+    });
+});
 test('row update 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 () => {
@@ -294,20 +560,20 @@ test('row update rejects object value for image field and requires upload array'
         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, /upload value array/);
         return true;
     });
 });
 test('row create 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', ['row', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile], env, async (url, init) => {
+    const out = await executeCLI('user', ['row', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile], env, withRowPolicyResolver('table_1', ['add'], async (url, init) => {
         calls.push({ url: String(url), method: init?.method });
         if (String(url) === 'https://arcubase.example.com/api/entity/app_1/table_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/api/entity/app_1/table_1', method: 'GET' },
@@ -318,7 +584,7 @@ test('row create accepts upload array for file field after schema preflight', as
 test('row create 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', ['row', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile], env, async (url, init) => {
+        await executeCLI('user', ['row', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile], env, withRowPolicyResolver('table_1', ['add'], async (url, init) => {
             if (String(url) === 'https://arcubase.example.com/api/entity/app_1/table_1' && init?.method === 'GET') {
                 return new Response(JSON.stringify({ data: { fields: [{ id: 1007, type: 'file', label: 'Contract File' }] } }), { status: 200 });
             }
@@ -330,13 +596,13 @@ test('row create decorates upload bind failures with actionable guidance', async
                 },
                 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.match(error.details?.hint ?? '', /upload token flow/);
         return true;
     });
 });
@@ -351,6 +617,28 @@ test('row query rejects camelCase viewMode and points to row crud doc', async ()
         return true;
     });
 });
+test('row query unknown limit flag gives body-json retry path', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('user', ['row', 'query', '--app-id', '2188900691', '--table-id', '2188900694', '--limit', '1', '--offset', '0'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UNKNOWN_FLAG');
+        assert.equal(error.details?.requestType, 'EntityQueryReqVO');
+        assert.deepEqual(error.details?.shapeHint, { limit: 20, offset: 0, search: { text_search: 'SO-1001' } });
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('--body-json')));
+        return true;
+    });
+});
+test('table dataset unknown app flag points to table get', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('user', ['table', 'dataset', '--app-id', '2188900691', '--table-id', '2188900694'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UNKNOWN_FLAG');
+        assert.ok(error.details?.suggestions?.some((item) => item.includes('table get --app-id')));
+        return true;
+    });
+});
 test('row update rejects fields key', async () => {
     const bodyFile = tempJSONFile({ fields: { 1002: 99 }, data: { '1002': 99 }, changed_fields: [1002] });
     await assert.rejects(async () => {
@@ -374,11 +662,11 @@ test('row update rejects changed_fields that are missing from data', async () =>
     });
 });
 test('workflow approve maps to fixed action path', async () => {
-    const bodyFile = tempJSONFile({ task_id: 1001, fields: {}, changed: [] });
+    const bodyFile = tempJSONFile({ task_id: 2188890521, fields: {}, changed: [] });
     const out = await executeCLI('user', ['workflow', 'approve', '--app-id', 'app_1', '--table-id', 'table_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async (url, init) => new Response(JSON.stringify({ url, method: init?.method, body: init?.body ? JSON.parse(String(init.body)) : null }), { status: 200 }));
     assert.equal(out.kind, 'result');
     assert.equal(out.data.url, 'https://arcubase.example.com/api/entity/app_1/table_1/row/row_1/action/2');
-    assert.equal(out.data.body.task_id, 1001);
+    assert.equal(out.data.body.task_id, 2188890521);
 });
 test('workflow query-approve-users requires request body', async () => {
     await assert.rejects(async () => {
@@ -389,11 +677,42 @@ test('workflow query-approve-users requires request body', async () => {
         return true;
     });
 });
-test('entry passes include_app_tables query flag', async () => {
-    const out = await executeCLI('user', ['entry', '--include-app-tables', 'true'], env, async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }));
+test('entry always includes app tables without exposing a query flag', async () => {
+    const out = await executeCLI('user', ['entry'], env, async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.url, 'https://arcubase.example.com/api/entry?include_app_tables=true');
+});
+test('entry fixed app tables query cannot be disabled by query file', async () => {
+    const queryFile = tempJSONFile({ include_app_tables: false });
+    const out = await executeCLI('user', ['entry', '--query-file', queryFile], env, async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }));
     assert.equal(out.kind, 'result');
     assert.equal(out.data.url, 'https://arcubase.example.com/api/entry?include_app_tables=true');
 });
+test('upstream http failures include endpoint status and body details', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('user', ['entry'], env, async () => new Response('', { status: 500 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UPSTREAM_REQUEST_FAILED');
+        assert.equal(error.details?.endpoint, '/api/entry');
+        assert.equal(error.details?.method, 'GET');
+        assert.equal(error.details?.status, 500);
+        return true;
+    });
+});
+test('upstream network failures are separated from http failures', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('user', ['entry'], env, async () => {
+            throw new Error('dns failed');
+        });
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UPSTREAM_NETWORK_ERROR');
+        assert.equal(error.details?.endpoint, '/api/entry');
+        assert.match(error.message, /dns failed/);
+        return true;
+    });
+});
 test('access-rule update rejects enabled without update whitelist', async () => {
     await assert.rejects(async () => {
         await executeCLI('admin', ['access-rule', 'update', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"enabled":true}'], env, async () => new Response('{}', { status: 200 }));
@@ -402,7 +721,7 @@ test('access-rule update rejects enabled without update whitelist', async () =>
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
         assert.match(error.message, /update.*enabled/);
         assert.equal(error.details?.requestType, 'AppIngressUpdateReqVO');
-        assert.ok((error.details?.tsHints ?? []).some((item) => item.file === '/opt/arcubase-sdk/types/ingress.ts'));
+        assert.ok((error.details?.tsHints ?? []).some((item) => item.file === '/runtime/arcubase-sdk/types/ingress.ts'));
         return true;
     });
 });
@@ -411,6 +730,86 @@ test('access-rule update accepts enabled with update whitelist', async () => {
     assert.equal(out.kind, 'result');
     assert.deepEqual(out.data, { update: ['enabled'], enabled: true });
 });
+test('access-rule update rejects nested options patch with canonical policy example', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'update', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["options.policy"],"options":{"policy":{"key":"custom","actions":["view","add"],"fields":[{"key":"1002","read":false}]}}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /update.*options/);
+        assert.match(error.message, /:1002/);
+        assert.ok((error.details?.commonMistakes ?? []).some((item) => item.includes('options.policy')));
+        return true;
+    });
+});
+test('access-rule update accepts canonical policy body with hidden field', async () => {
+    const body = '{"update":["options"],"options":{"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":true,"all_fields_write":true,"fields":[{"key":":1002","read":false,"write":false,"report":false}]},"list_options":{}}}';
+    const out = await executeCLI('admin', ['access-rule', 'update', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', body], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(out.data.update, ['options']);
+    assert.deepEqual(out.data.options.policy.fields, [{ key: ':1002', read: false, write: false, report: false }]);
+});
+test('access-rule update rejects partial options user scope overwrite', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'update', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["options"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /options.*policy/);
+        assert.match(error.message, /assign-users/);
+        return true;
+    });
+});
+test('access-rule update rejects FieldVO key names in policy fields', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'update', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["options"],"options":{"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":false,"all_fields_write":false,"fields":[{"key":"vote_description","read":false,"write":false,"report":false}]},"list_options":{}}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /:1002/);
+        assert.match(error.message, /vote_name|FieldVO\.key/);
+        return true;
+    });
+});
+test('access-rule create rejects guessed permission aliases', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-json', '{"name":"rule","enabled":true,"permissions":["read","write"],"field_visibility":[{"field_id":1002,"visible":false}]}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /options\.policy/);
+        assert.equal(error.details?.requestType, 'AppIngressCreateReqVO');
+        assert.ok((error.details?.commonMistakes ?? []).some((item) => item.includes('field_visibility')));
+        return true;
+    });
+});
+test('access-rule create rejects read write action aliases', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-json', '{"name":"rule","enabled":true,"type":"form","options":{"policy":{"key":"custom","actions":["read","write"]},"list_options":{}}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /view.*add.*edit/);
+        return true;
+    });
+});
+test('access-rule create rejects FieldVO member type in user scope', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-json', '{"name":"rule","enabled":true,"type":"form","options":{"user_scope":[{"type":"member","id":2188889901}],"policy":{"key":"custom","actions":["view"],"all_fields_read":true,"all_fields_write":false},"list_options":{}}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /user.*department.*actor|FieldVO type "member"/);
+        return true;
+    });
+});
+test('access-rule create accepts custom policy with hidden field', async () => {
+    const body = '{"name":"rule","enabled":true,"type":"form","options":{"user_scope":[{"type":"user","id":2188889901}],"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":true,"all_fields_write":true,"fields":[{"key":":1002","read":false,"write":false,"report":false}]},"list_options":{}}}';
+    const out = await executeCLI('admin', ['access-rule', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-json', body], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(out.data.options.policy.actions, ['view', 'add', 'edit']);
+    assert.deepEqual(out.data.options.policy.fields, [{ key: ':1002', read: false, write: false, report: false }]);
+});
 test('access-rule assign-users rejects users shortcut', async () => {
     await assert.rejects(async () => {
         await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"users":["tu_1"]}'], env, async () => new Response('{}', { status: 200 }));
@@ -428,22 +827,22 @@ test('access-rule assign-users rejects allowedUsers shortcut', async () => {
 });
 test('access-rule assign-users rejects top-level user_scope', async () => {
     await assert.rejects(async () => {
-        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"user_scope":[{"type":"member","id":123}]}'], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"user_scope":[{"type":"user","id":2188889901}]}'], env, async () => new Response('{}', { status: 200 }));
     }, (error) => assertAssignUsersGuidance(error, /options.user_scope/));
 });
-test('access-rule assign-users rejects non-member scope type', async () => {
+test('access-rule assign-users rejects non-user member scope type', async () => {
     await assert.rejects(async () => {
-        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}'], env, async () => new Response('{}', { status: 200 }));
-    }, (error) => assertAssignUsersGuidance(error, /type.*member/));
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":2188889901}]}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => assertAssignUsersGuidance(error, /type.*user/));
 });
 test('access-rule assign-users rejects hash tenant user id', async () => {
     await assert.rejects(async () => {
-        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":"zW96OnE0kyJa3B2"}]}}'], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":"zW96OnE0kyJa3B2"}]}}'], env, async () => new Response('{}', { status: 200 }));
     }, (error) => assertAssignUsersGuidance(error, /numeric TenantUser.ID/));
 });
 test('access-rule assign-users accepts canonical user_scope body', async () => {
-    const out = await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":123}]}}'], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    const out = await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}'], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
     assert.equal(out.kind, 'result');
     assert.deepEqual(out.data.update, ['user_scope']);
-    assert.deepEqual(out.data.options.user_scope, [{ type: 'member', id: 123 }]);
+    assert.deepEqual(out.data.options.user_scope, [{ type: 'user', id: 2188889901 }]);
 });