@carthooks/arcubase-cli 0.1.9 → 0.1.12

package/src/tests/execute_validation.test.ts

@@ -9,6 +9,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: '',
@@ -22,6 +23,53 @@ function tempJSONFile(payload: unknown): string {
   return filePath
 }
 
+function withRowPolicyResolver(
+  tableId = 'table_1',
+  actions = ['view', 'add', 'edit', 'delete', 'bulk_update', 'archive'],
+  policyOverridesOrFinal: Record<string, unknown> | typeof fetch = {},
+  final?: typeof fetch,
+): typeof fetch {
+  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: unknown, messagePattern?: RegExp): boolean {
+  assert.ok(error instanceof CLIError)
+  assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+  if (messagePattern) {
+    assert.match(error.message, messagePattern)
+  }
+  assert.equal(error.details?.requestType, 'AppIngressUpdateReqVO')
+  assert.deepEqual(error.details?.shapeHint, {
+    update: ['user_scope'],
+    options: {
+      user_scope: [{ type: 'user', id: 2188889901 }],
+    },
+  })
+  assert.deepEqual(error.details?.commonMistakes, [
+    'do not use user_scope at top level',
+    'do not use users or allowedUsers',
+    '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 === '/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: Record<string, unknown> = {}) {
   return {
     id: 2188889845,
@@ -84,6 +132,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 as any)?.field_id_seq, 1004)
+    assert.equal((error.details?.shapeHint as any)?.fields?.[0]?.type, 'text')
+    assert.equal((error.details?.shapeHint as any)?.fields?.[1]?.type, 'textarea')
+    assert.equal((error.details?.shapeHint as any)?.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
   })
 })
@@ -100,40 +157,68 @@ test('app create rejects name longer than 20 chars', async () => {
   })
 })
 
-test('table create executes with valid body file', async () => {
-  const bodyFile = tempJSONFile({ name: '订单', parent: 0 })
+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 as any, async () => new Response('{}'))
+  }, (error: unknown) => {
+    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: Array<{ url: string; method?: string; body: any }> = []
   const out = await executeCLI(
     'admin',
-    ['table', 'create', '--app-id', 'app_1', '--body-file', bodyFile],
+    ['table', 'create', '--app-id', '2188889844', '--body-file', bodyFile],
     env as any,
-    async (url, init) =>
-      new Response(JSON.stringify({
-        url,
-        method: init?.method,
-        hasTenantHeader: Object.prototype.hasOwnProperty.call((init?.headers as Record<string, string>) ?? {}, 'X-Tenant-Id'),
-        hasHostHeader: Object.prototype.hasOwnProperty.call((init?.headers as Record<string, string>) ?? {}, 'X-Host'),
-      }), { status: 200 }),
+    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 calls: Array<{ url: string; method?: string; body: any }> = []
+  const payload = JSON.stringify({ ...validEntitySavePayload({ id: undefined, app_id: undefined }), name: '订单', parent: 0 })
   const out = await executeCLI(
     'admin',
-    ['table', 'create', '--app-id', 'app_1', '--body-json', '{"name":"订单","parent":0}'],
+    ['table', 'create', '--app-id', '2188889844', '--body-json', payload],
     env as any,
-    async (url, init) => new Response(JSON.stringify({
-      url,
-      method: init?.method,
-      body: init?.body ? JSON.parse(String(init.body)) : null,
-    }), { status: 200 }),
+    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 () => {
@@ -157,6 +242,22 @@ test('body json is rejected for commands without request type', async () => {
   })
 })
 
+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 as any, async () => {
+      called = true
+      return new Response('{}', { status: 200 })
+    })
+  }, (error: unknown) => {
+    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 as any, async () => new Response('{}', { status: 200 }))
@@ -167,6 +268,19 @@ test('body json parse errors fail fast', async () => {
   })
 })
 
+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 as any, async () => new Response('{}', { status: 200 }))
+  }, (error: unknown) => {
+    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 list executes against external root path', async () => {
   const out = await executeCLI(
     'admin',
@@ -231,6 +345,36 @@ test('table update-schema normalizes shell null placeholders before validation',
   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 as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => {
+    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 () => {
@@ -252,7 +396,7 @@ test('row bulk-update accepts ids selection with number_add action', async () =>
     'user',
     ['row', 'bulk-update', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile],
     env as any,
-    async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }),
+    withRowPolicyResolver(),
   )
   assert.equal(out.kind, 'result')
   assert.deepEqual(out.data.selection, { type: 'ids', ids: [4000000003], length: 1 })
@@ -272,7 +416,7 @@ test('row selection-action accepts condition selection with selectAll', async ()
     'user',
     ['row', 'selection-action', '--app-id', 'app_1', '--table-id', 'table_1', '--action', 'archive', '--body-file', bodyFile],
     env as any,
-    async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }),
+    withRowPolicyResolver(),
   )
   assert.equal(out.kind, 'result')
   assert.equal(out.data.selection.type, 'condition')
@@ -291,7 +435,139 @@ test('row selection-action rejects condition selection for query action', async
   })
 })
 
-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: Array<{ url: string; method?: string; body: any }> = []
+  const out = await executeCLI(
+    'user',
+    ['row', 'create', '--app-id', '2188900691', '--table-id', '2188900694', '--body-file', bodyFile],
+    env as any,
+    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: string[] = []
+  const out = await executeCLI(
+    'user',
+    ['row', 'get', '--app-id', '2188900691', '--table-id', '2188900694', '--row-id', '4000000046'],
+    env as any,
+    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 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 as any,
+      withRowPolicyResolver('2188900694', ['add']),
+    )
+  }, (error: unknown) => {
+    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 as any,
+      withRowPolicyResolver('2188900694', ['view']),
+    )
+  }, (error: unknown) => {
+    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: Array<{ url: string; method?: string }> = []
+  await assert.rejects(async () => {
+    await executeCLI(
+      'user',
+      ['row', 'create', '--app-id', '2188900691', '--table-id', '2188900694', '--body-file', bodyFile],
+      env as any,
+      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: unknown) => {
+    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: Array<{ url: string; method?: string }> = []
+  await assert.rejects(async () => {
+    await executeCLI(
+      'user',
+      ['row', 'update', '--app-id', '2188900691', '--table-id', '2188900694', '--row-id', '2188901452', '--body-file', bodyFile],
+      env as any,
+      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: unknown) => {
+    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: Array<{ url: string; method?: string }> = []
   await assert.rejects(async () => {
@@ -311,12 +587,31 @@ 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 as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => {
+    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 () => {
@@ -335,7 +630,7 @@ 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
   })
 })
@@ -347,13 +642,13 @@ test('row create accepts upload array for file field after schema preflight', as
     'user',
     ['row', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile],
     env as any,
-    async (url, init) => {
+    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, [
@@ -370,7 +665,7 @@ test('row create decorates upload bind failures with actionable guidance', async
       'user',
       ['row', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-file', bodyFile],
       env as any,
-      async (url, init) => {
+      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 })
         }
@@ -382,14 +677,14 @@ test('row create decorates upload bind failures with actionable guidance', async
           },
           trace_id: 'req_upload_bind',
         }), { status: 200 })
-      },
+      }),
     )
   }, (error: unknown) => {
     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
   })
 })
@@ -406,6 +701,30 @@ test('row query rejects camelCase viewMode and points to row crud doc', async ()
   })
 })
 
+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 as any, async () => new Response('{}', { status: 200 }))
+  }, (error: unknown) => {
+    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 as any, async () => new Response('{}', { status: 200 }))
+  }, (error: unknown) => {
+    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 () => {
@@ -431,7 +750,7 @@ 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],
@@ -440,7 +759,7 @@ test('workflow approve maps to fixed action path', async () => {
   )
   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 () => {
@@ -453,10 +772,22 @@ test('workflow query-approve-users requires request body', async () => {
   })
 })
 
-test('entry passes include_app_tables query flag', async () => {
+test('entry always includes app tables without exposing a query flag', async () => {
+  const out = await executeCLI(
+    'user',
+    ['entry'],
+    env as any,
+    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', '--include-app-tables', 'true'],
+    ['entry', '--query-file', queryFile],
     env as any,
     async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }),
   )
@@ -464,6 +795,33 @@ test('entry passes include_app_tables query flag', async () => {
   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 as any, async () => new Response('', { status: 500 }))
+  }, (error: unknown) => {
+    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 as any, async () => {
+      throw new Error('dns failed')
+    })
+  }, (error: unknown) => {
+    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(
@@ -477,7 +835,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
   })
 })
@@ -493,47 +851,208 @@ test('access-rule update accepts enabled with update whitelist', async () => {
   assert.deepEqual(out.data, { update: ['enabled'], enabled: true })
 })
 
-test('access-rule assign-users rejects users shortcut', async () => {
+test('access-rule update rejects nested options patch with canonical policy example', 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"]}'],
+      ['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 as any,
       async () => new Response('{}', { status: 200 }),
     )
   }, (error: unknown) => {
     assert.ok(error instanceof CLIError)
     assert.equal(error.code, 'BODY_VALIDATION_FAILED')
-    assert.match(error.message, /options.user_scope/)
-    assert.equal(error.details?.requestType, 'AppIngressUpdateReqVO')
+    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 assign-users requires update user_scope and non-empty user_scope', async () => {
+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 as any,
+    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', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[]}}'],
+      ['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 as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => {
+    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 as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => {
+    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 as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => {
+    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 as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => {
+    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 as any,
       async () => new Response('{}', { status: 200 }),
     )
   }, (error: unknown) => {
     assert.ok(error instanceof CLIError)
     assert.equal(error.code, 'BODY_VALIDATION_FAILED')
-    assert.match(error.message, /non-empty/)
+    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 as any,
+    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 as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => assertAssignUsersGuidance(error, /options.user_scope/))
+})
+
+test('access-rule assign-users requires update user_scope and non-empty 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', '{"update":["user_scope"],"options":{"user_scope":[]}}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => assertAssignUsersGuidance(error, /non-empty/))
+})
+
+test('access-rule assign-users rejects allowedUsers 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', '{"allowedUsers":["tu_1"]}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => assertAssignUsersGuidance(error, /options.user_scope/))
+})
+
+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":"user","id":2188889901}]}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => assertAssignUsersGuidance(error, /options.user_scope/))
+})
+
+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":"member","id":2188889901}]}}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => 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":"user","id":"zW96OnE0kyJa3B2"}]}}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => 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":"user","id":123}]}}'],
+    ['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 as any,
     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: 'user', id: 123 }])
+  assert.deepEqual(out.data.options.user_scope, [{ type: 'user', id: 2188889901 }])
 })