@carthooks/arcubase-cli 0.1.10 → 0.1.12

package/dist/runtime/execute.js

@@ -5,10 +5,7 @@ import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http
 import { listModules, listModuleCommands, findCommand, findCommandSuggestions } from './command_registry.js';
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js';
 import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js';
-import { renderUploadHelp, uploadLocalFile } from './upload.js';
-function summarizeUploadResult(value) {
-    return value;
-}
+import { resolveArcubaseSDKPath } from './paths.js';
 export function renderRootHelp(scope) {
     const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase';
     const items = listModules(scope).map((item) => `  - ${item}`);
@@ -18,19 +15,20 @@ export function renderRootHelp(scope) {
         ...(scope === 'admin'
             ? ['use arcubase-admin for app, table, access-rule, and workflow management', '']
             : ['use arcubase for entry, table, row, upload, profile, and workflow actions', '']),
+        'prefer --body-json <json-string> for normal payloads, including table schema; use --body-file only when JSON is too large for one tool call',
+        '',
         'modules:',
         ...items,
-        ...(scope === 'user' ? ['', 'special commands:', '  - upload <local-file>'] : []),
     ].join('\n');
 }
-export function renderModuleHelp(scope, moduleName) {
+export function renderModuleHelp(scope, moduleName, env = process.env) {
     const items = listModuleCommands(scope, moduleName);
     if (items.length === 0) {
         const suggestions = findCommandSuggestions(moduleName, '').map((item) => `${item.binary} ${item.moduleName}${item.commandName ? ` ${item.commandName}` : ''}`);
         throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2, suggestions.length > 0 ? { suggestions } : undefined);
     }
     if (items.length === 1 && items[0].commandPath.length === 1) {
-        return renderCommandHelp(scope, moduleName);
+        return renderCommandHelp(scope, moduleName, undefined, env);
     }
     return [
         `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} <command> [flags]`,
@@ -38,6 +36,8 @@ export function renderModuleHelp(scope, moduleName) {
         ...(scope === 'admin'
             ? ['use arcubase-admin for app, table, access-rule, and workflow management', '']
             : ['use arcubase for entry, table, row, upload, profile, and workflow actions', '']),
+        'prefer --body-json <json-string> for normal payloads, including table schema; use --body-file only when JSON is too large for one tool call',
+        '',
         'commands:',
         ...items.filter((item) => item.commandPath.length > 1).map((item) => `  - ${item.commandPath[1]}`),
     ].join('\n');
@@ -46,30 +46,52 @@ function buildUnknownCommandDetails(scope, moduleName, commandName) {
     const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName}${item.commandName ? ` ${item.commandName}` : ''}`);
     return suggestions.length > 0 ? { suggestions } : undefined;
 }
-export function renderCommandHelp(scope, moduleName, commandName) {
+function sdkPath(file, env = process.env) {
+    return resolveArcubaseSDKPath(file, env);
+}
+export function renderCommandHelp(scope, moduleName, commandName, env = process.env) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
         throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName}${commandName ? ` ${commandName}` : ''}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName ?? ''));
     }
     const docHints = [
-        ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`),
-        ...(command.requestType ? getDocHints(command.requestType) : []),
+        ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`, env),
+        ...(command.requestType ? getDocHints(command.requestType, env) : []),
     ].filter((item, index, list) => list.findIndex((candidate) => candidate.file === item.file) === index);
+    const typeHints = command.requestType ? getTypeHints(command.requestType, env) : [];
     const pathFlags = command.pathParams.filter((item) => !getFixedValue(item)).map((item) => `--${item.flag}`);
-    const queryFlags = command.queryParams.filter((item) => !getFixedValue(item)).map((item) => `--${item.flag}`);
+    const queryFlags = visibleQueryParams(command).map((item) => `--${item.flag}`);
+    const isTableCreate = scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'create';
+    const bodyTypeText = isTableCreate ? 'TableCreateWithSchema' : command.requestType;
+    const tableCreateExampleBody = JSON.stringify(buildTableCreateExampleBody());
     return [
         `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${command.commandPath.join(' ')}`,
         `method: ${command.method}`,
         `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
-        command.requestType ? `body: ${command.requestType} via --body-file or --body-json` : 'body: none',
+        command.requestType ? `body: ${bodyTypeText} via --body-json <json-string> | --body-file <file>.json` : 'body: none',
         queryFlags.length ? `query flags: ${queryFlags.join(', ')}, --query-file` : 'query flags: --query-file',
         pathFlags.length ? `path flags: ${pathFlags.join(', ')}` : 'path flags: none',
+        ...(isTableCreate
+            ? [
+                'body-json example:',
+                `  - ${tableCreateExampleBody}`,
+                'body rules:',
+                '  - fields must be non-empty; empty table shell creation is not allowed',
+                '  - field_id_seq must be greater than every field.id',
+                '  - use text, not string; use member, not user',
+                '  - for select/radio/checkbox/status, use options.options.items',
+                'schema refs:',
+                `  - Table schema cheatsheet: ${sdkPath('docs/runtime-reference/entity-schema.md', env)}`,
+                `  - Field type index: ${sdkPath('docs/runtime-reference/entity-schema/README.md', env)}`,
+            ]
+            : []),
         ...(scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'update-schema'
             ? [
                 'next step:',
+                '  - prefer --body-json for schema save to avoid file creation and JSON file corruption',
                 '  - switch to arcubase for row operations',
-                '  - row create: arcubase row create --app-id <app_id> --table-id <table_id> --body-file insert.json',
-                '  - row query: arcubase row query --app-id <app_id> --table-id <table_id> --body-file query.json',
+                '  - row create: arcubase row create --app-id <app_id> --table-id <table_id> --body-json <json-string> | --body-file insert.json',
+                '  - row query: arcubase row query --app-id <app_id> --table-id <table_id> --body-json <json-string> | --body-file query.json',
             ]
             : []),
         ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update'
@@ -77,13 +99,23 @@ export function renderCommandHelp(scope, moduleName, commandName) {
                 'body-json examples:',
                 '  - enable: {"update":["enabled"],"enabled":true}',
                 '  - rename: {"update":["name"],"name":"Sales read only"}',
-                '  - update options: {"update":["options"],"options":{"user_scope":[{"type":"member","id":123}]}}',
+                '  - update policy: {"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":{}}}',
+            ]
+            : []),
+        ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'create'
+            ? [
+                'body-json example:',
+                '  - {"name":"Sales read write","enabled":true,"type":"form","options":{"user_scope":[{"type":"user","id":2188889901}],"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":false,"all_fields_write":false,"fields":[{"key":":1001","read":true,"write":true,"report":false},{"key":":1002","read":false,"write":false,"report":false}]},"list_options":{}}}',
+                'success requires:',
+                '  - result.enabled must be true',
+                '  - options.user_scope[].type is "user" for tenant users',
+                '  - hidden fields use colon field keys such as ":1002"',
             ]
             : []),
         ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users'
             ? [
                 'body-json example:',
-                '  - {"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":123}]}}',
+                '  - {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}',
                 'success requires:',
                 '  - result.enabled must be true',
                 '  - result.options.user_scope must contain the assigned numeric TenantUser.ID values',
@@ -95,6 +127,9 @@ export function renderCommandHelp(scope, moduleName, commandName) {
         ...(docHints.length > 0
             ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
             : []),
+        ...(typeHints.length > 0
+            ? ['types:', ...typeHints.map((item) => `  - ${item.symbol}: ${item.file}`)]
+            : []),
     ].join('\n');
 }
 function coerceScalar(value, typeText) {
@@ -138,7 +173,7 @@ function buildScalarQuery(command, flags) {
         return undefined;
     }
     const out = {};
-    for (const scalar of command.queryParams) {
+    for (const scalar of effectiveQueryParams(command)) {
         const value = getFixedValue(scalar) ?? flagValue(flags, scalar.flag);
         if (value === undefined)
             continue;
@@ -146,9 +181,125 @@ function buildScalarQuery(command, flags) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
+function validateKnownFlags(command, flags, env = process.env) {
+    const allowed = new Set(['help', 'body-file', 'body-json', 'query-file']);
+    for (const mapping of command.pathParams) {
+        if (!getFixedValue(mapping)) {
+            allowed.add(mapping.flag);
+        }
+    }
+    for (const query of visibleQueryParams(command)) {
+        if (!getFixedValue(query)) {
+            allowed.add(query.flag);
+        }
+    }
+    for (const flag of Object.keys(flags)) {
+        if (!allowed.has(flag)) {
+            throw new CLIError('UNKNOWN_FLAG', `unknown flag --${flag} for ${command.commandPath.join(' ')}`, 2, {
+                ...buildUnknownFlagDetails(command, flag, env),
+            });
+        }
+    }
+}
+function buildUnknownFlagDetails(command, flag, env = process.env) {
+    const operation = command.commandPath.join(' ');
+    const details = {
+        operation,
+        hint: `run ${operation} --help for the supported flags`,
+    };
+    if (command.requestType) {
+        details.requestType = command.requestType;
+        details.tsHints = getTypeHints(command.requestType, env);
+        details.docHints = getDocHints(command.requestType, env);
+        details.commonMistakes = [
+            `do not pass request body fields as --${flag}`,
+            'put request body fields inside --body-json <json-string>',
+        ];
+        details.suggestions = [`retry with: ${command.commandPath.join(' ')} ${command.pathParams.filter((item) => !getFixedValue(item)).map((item) => `--${item.flag} <${item.flag.replace(/-/g, '_')}>`).join(' ')} --body-json '<json>'`.replace(/\s+/g, ' ').trim()];
+    }
+    if (command.commandPath[0] === 'row' && command.commandPath[1] === 'query' && ['limit', 'offset', 'search', 'sorts', 'view-mode'].includes(flag)) {
+        details.shapeHint = { limit: 20, offset: 0, search: { text_search: 'SO-1001' } };
+        details.suggestions = ['retry with: row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0}\''];
+    }
+    if (command.commandPath[0] === 'table' && command.commandPath[1] === 'dataset' && ['app-id', 'table-id'].includes(flag)) {
+        details.hint = 'table dataset uses --dataset-id and --node-id; use table get for app/table metadata';
+        details.suggestions = [
+            'retry metadata read with: table get --app-id <app_id> --table-id <table_id>',
+            'retry dataset read with: table dataset --dataset-id <dataset_id> --node-id <node_id>',
+        ];
+    }
+    return details;
+}
+function visibleQueryParams(command) {
+    if (!command)
+        return [];
+    return effectiveQueryParams(command).filter((item) => !getFixedValue(item));
+}
+function effectiveQueryParams(command) {
+    if (!command)
+        return [];
+    return command.queryParams.filter((item) => {
+        if (rowCommandNeedsPolicy(command) && item.key === 'policy_id') {
+            return false;
+        }
+        return true;
+    });
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+function stringifyUpstreamBody(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value == null)
+        return '';
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function extractTraceID(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value.trace_id === 'string')
+        return value.trace_id;
+    if (typeof value.request_id === 'string')
+        return value.request_id;
+    return undefined;
+}
+function upstreamErrorMessage(value) {
+    if (isRecord(value) && typeof value.message === 'string')
+        return value.message;
+    if (typeof value === 'string')
+        return value;
+    return stringifyUpstreamBody(value);
+}
+function throwUpstreamHTTPError(endpoint, method, response, parsedResponse) {
+    const upstreamError = isRecord(parsedResponse) && parsedResponse.error ? parsedResponse.error : undefined;
+    const body = stringifyUpstreamBody(parsedResponse);
+    throw new CLIError('UPSTREAM_REQUEST_FAILED', upstreamError ? upstreamErrorMessage(upstreamError) : body || `HTTP ${response.status}`, 1, {
+        endpoint,
+        method,
+        status: response.status,
+        traceId: extractTraceID(parsedResponse),
+        responseBody: body,
+        ...(upstreamError ? { upstreamError } : {}),
+    });
+}
+async function fetchUpstream(url, init, endpoint, method, fetchImpl) {
+    try {
+        return await fetchImpl(url, init);
+    }
+    catch (error) {
+        throw new CLIError('UPSTREAM_NETWORK_ERROR', error instanceof Error ? error.message : String(error), 1, {
+            endpoint,
+            method,
+            reason: 'network or DNS failure before Arcubase returned an HTTP response',
+        });
+    }
+}
 function extractEntityFields(payload) {
     const candidate = isRecord(payload) && isRecord(payload.data) ? payload.data : payload;
     if (!isRecord(candidate) || !Array.isArray(candidate.fields)) {
@@ -164,10 +315,12 @@ function extractEntityFields(payload) {
     }));
 }
 async function fetchEntityFields(runtimeEnv, appId, entityId, fetchImpl) {
-    const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, `/api/entity/${encodeURIComponent(appId)}/${encodeURIComponent(entityId)}`), {
+    const endpoint = `/api/entity/${appId}/${entityId}`;
+    const encodedEndpoint = `/api/entity/${encodeURIComponent(appId)}/${encodeURIComponent(entityId)}`;
+    const response = await fetchUpstream(buildURL(runtimeEnv.ARCUBASE_BASE_URL, encodedEndpoint), {
         method: 'GET',
         headers: buildRequestHeaders(runtimeEnv),
-    });
+    }, endpoint, 'GET', fetchImpl);
     const raw = await response.text();
     let parsedResponse = raw;
     try {
@@ -177,18 +330,15 @@ async function fetchEntityFields(runtimeEnv, appId, entityId, fetchImpl) {
         parsedResponse = raw;
     }
     if (!response.ok) {
-        throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1);
+        throwUpstreamHTTPError(endpoint, 'GET', response, parsedResponse);
     }
     if (isRecord(parsedResponse) && parsedResponse.error) {
         const upstreamError = parsedResponse.error;
-        const upstreamMessage = isRecord(upstreamError) && typeof upstreamError.message === 'string'
-            ? upstreamError.message
-            : typeof upstreamError === 'string'
-                ? upstreamError
-                : JSON.stringify(upstreamError);
+        const upstreamMessage = upstreamErrorMessage(upstreamError);
         throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
-            endpoint: `/api/entity/${appId}/${entityId}`,
+            endpoint,
             method: 'GET',
+            traceId: extractTraceID(parsedResponse),
             upstreamError,
         });
     }
@@ -237,76 +387,161 @@ async function validateFileFieldPayloads(scope, command, runtimeEnv, flags, body
         const fieldName = field.label ? `${field.label} (${field.type})` : `${field.type} field ${fieldId}`;
         if (typeof value === 'string') {
             const guidance = looksLikeLocalFilePath(value)
-                ? `do not put a local file path directly into ${fieldName}; run "arcubase upload ${value}" first and use the returned data array as the field value`
-                : `${fieldName} must be an array returned by "arcubase upload <local-file>", not a string`;
+                ? `do not put a local file path directly into ${fieldName}; use arcubase upload token flow and pass the returned upload value array`
+                : `${fieldName} must be an upload value array, not a string`;
             throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
                 operation: `${scope}.${command.module}.${command.functionName}`,
                 requestType: command.requestType ?? undefined,
                 issues: [{ path: fieldPath, message: guidance }],
                 docHints: [
-                    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-                    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                    { title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md', runtimeEnv) },
+                    { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
                 ],
             });
         }
         if (isRecord(value)) {
-            const guidance = `${fieldName} must be an array. Run "arcubase upload <local-file>" and use the returned data array directly as the field value`;
+            const guidance = `${fieldName} must be an upload value array. Use the upload token flow and pass the returned array directly`;
             throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
                 operation: `${scope}.${command.module}.${command.functionName}`,
                 requestType: command.requestType ?? undefined,
                 issues: [{ path: fieldPath, message: guidance }],
                 docHints: [
-                    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-                    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                    { title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md', runtimeEnv) },
+                    { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
                 ],
             });
         }
         if (!Array.isArray(value)) {
-            const guidance = `${fieldName} must be an array returned by "arcubase upload <local-file>"`;
+            const guidance = `${fieldName} must be an upload value array`;
             throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
                 operation: `${scope}.${command.module}.${command.functionName}`,
                 requestType: command.requestType ?? undefined,
                 issues: [{ path: fieldPath, message: guidance }],
                 docHints: [
-                    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-                    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                    { title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md', runtimeEnv) },
+                    { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
                 ],
             });
         }
         for (const [index, item] of value.entries()) {
             if (!isValidUploadEntry(item)) {
-                const guidance = `${fieldName} entries must include upload_id or assets_id plus file and file_name. Use "arcubase upload <local-file>" and copy the returned array item as-is`;
+                const guidance = `${fieldName} entries must include upload_id or assets_id plus file and file_name. Use the upload token flow and copy the returned array item as-is`;
                 throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
                     operation: `${scope}.${command.module}.${command.functionName}`,
                     requestType: command.requestType ?? undefined,
                     issues: [{ path: `${fieldPath}.${index}`, message: guidance }],
                     docHints: [
-                        { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-                        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                        { title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md', runtimeEnv) },
+                        { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
                     ],
                 });
             }
         }
     }
 }
+function buildTableCreateExampleBody() {
+    return {
+        name: '投票项目',
+        parent: 0,
+        schema_version: 0,
+        field_id_seq: 1003,
+        layout: [[1001], [1002]],
+        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: 'vote_name',
+                code_index: false,
+                options: { type: 'text', placeholder: '', lengthLimit: false, lengthMin: 0, lengthMax: 255 },
+                transfers: null,
+                children: null,
+            },
+            {
+                id: 1002,
+                label: '投票描述',
+                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: 'vote_description',
+                code_index: false,
+                options: { placeholder: '', html: false, size: 'default', lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
+                transfers: null,
+                children: null,
+            },
+        ],
+        options: { Buttons: [], CustomActions: [], FrontendEvents: [], TitleFormat: { Fields: [], Parts: [], Body: '' }, misc: {} },
+        workflow_enabled: false,
+    };
+}
 function isAssignUsersCommand(scope, command) {
     return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users';
 }
-function buildAssignUsersValidationDetails(scope, command, requestType, path, message) {
+function isTableCreateCommand(scope, command) {
+    return scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'create';
+}
+function isTableSchemaCommand(scope, command) {
+    return scope === 'admin' && command.commandPath[0] === 'table' && (command.commandPath[1] === 'create' || command.commandPath[1] === 'update-schema');
+}
+function isAccessRuleCommand(scope, command) {
+    return scope === 'admin' && command.commandPath[0] === 'access-rule';
+}
+function isAccessRuleUpdateCommand(scope, command) {
+    return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update';
+}
+function buildAccessRuleShapeHint(userId = 2188889901) {
+    return {
+        name: 'Sales read write',
+        enabled: true,
+        type: 'form',
+        options: {
+            user_scope: [{ type: 'user', id: userId }],
+            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: {},
+        },
+    };
+}
+function buildAssignUsersValidationDetails(scope, command, requestType, path, message, env = process.env) {
     return {
         operation: `${scope}.${command.module}.${command.functionName}`,
         requestType,
         issues: [{ path, message }],
         tsHints: [
-            { symbol: 'AppIngressUpdateReqVO', file: '/opt/arcubase-sdk/types/ingress.ts' },
-            { symbol: 'EntityIngressOptions', file: '/opt/arcubase-sdk/types/ingress.ts' },
-            { symbol: 'PermitUserScope', file: '/opt/arcubase-sdk/types/common.ts' },
+            { symbol: 'AppIngressUpdateReqVO', file: sdkPath('types/ingress.ts', env) },
+            { symbol: 'EntityIngressOptions', file: sdkPath('types/ingress.ts', env) },
+            { symbol: 'PermitUserScope', file: sdkPath('types/common.ts', env) },
         ],
-        docHints: getDocHints(requestType),
+        docHints: getDocHints(requestType, env),
         shapeHint: {
             update: ['user_scope'],
             options: {
-                user_scope: [{ type: 'member', id: 123 }],
+                user_scope: [{ type: 'user', id: 2188889901 }],
             },
         },
         commonMistakes: [
@@ -317,76 +552,355 @@ function buildAssignUsersValidationDetails(scope, command, requestType, path, me
         ],
     };
 }
-function throwBodyValidationFailure(message, requestType, path, scope, command) {
-    if (isAssignUsersCommand(scope, command)) {
-        throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildAssignUsersValidationDetails(scope, command, requestType, path, message));
+function buildBodyGuidance(requestType) {
+    if (requestType === 'EntitySaveReqVO' || requestType === 'AppCreateEntityReqVO') {
+        return {
+            shapeHint: {
+                id: 2188889845,
+                app_id: 2188889844,
+                name: '订单',
+                schema_version: 0,
+                field_id_seq: 1004,
+                layout: [[1001], [1002], [1003]],
+                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_no',
+                        code_index: false,
+                        options: { type: 'text', placeholder: '', lengthLimit: false, lengthMin: 0, lengthMax: 255 },
+                        transfers: null,
+                        children: null,
+                    },
+                    {
+                        id: 1002,
+                        label: '描述',
+                        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,
+                    },
+                    {
+                        id: 1003,
+                        label: '状态',
+                        type: 'select',
+                        required: true,
+                        unique: false,
+                        editable: true,
+                        visible: true,
+                        show_label: true,
+                        scannable: false,
+                        default_value_mode: 1,
+                        description: '',
+                        value: 'draft',
+                        number_decimal: 0,
+                        depends: [],
+                        key: 'status',
+                        code_index: false,
+                        options: {
+                            horizontal: false,
+                            numberMax: '',
+                            numberMin: '',
+                            numberRange: false,
+                            repeatRemind: 'This value already exists and duplicate submission is not allowed',
+                            options: {
+                                mode: 'custom',
+                                colorful: false,
+                                items: [
+                                    { key: 1, value: 'draft' },
+                                    { key: 2, value: 'active' },
+                                ],
+                            },
+                        },
+                        transfers: null,
+                        children: null,
+                    },
+                ],
+                options: { Buttons: [], CustomActions: [], FrontendEvents: [], TitleFormat: { Fields: [], Parts: [], Body: '' }, misc: {} },
+                workflow_enabled: false,
+            },
+            commonMistakes: [
+                'table create must include fields and field_id_seq; do not create an empty table shell',
+                'prefer --body-json for table create/update-schema; do not create a body file unless JSON is too large for one tool call',
+                'fields must be an array of full FieldVO objects, not an object map',
+                'get table shell first: arcubase-admin table get --app-id <app_id> --table-id <table_id>',
+                'save the full returned schema after editing; do not submit only changed fields',
+                'field_id_seq must be greater than every field.id',
+                'layout must reference existing field ids',
+                'use type "text", not "string"',
+                'use type "member", not "user"',
+                'for select/radio/checkbox/status, options must contain options.items',
+                'for linkto/relation/query, options must contain relation.app_id, relation.entity_id, relation.type',
+                'do not put per-user permissions in FieldVO; use access-rule for read/write and hidden fields',
+            ],
+            suggestions: [
+                `retry with: arcubase-admin table create --app-id <app_id> --body-json '${JSON.stringify(buildTableCreateExampleBody())}'`,
+            ],
+        };
+    }
+    if (requestType === 'AppIngressCreateReqVO' || requestType === 'AppIngressUpdateReqVO') {
+        return {
+            shapeHint: buildAccessRuleShapeHint(),
+            commonMistakes: [
+                'use options.policy, not top-level permissions',
+                'use options.policy.fields, not field_visibility',
+                'actions must use Arcubase action codes: view, add, edit; do not use read, write, or insert',
+                'field permission keys must be strings prefixed with colon, for example ":1002"; do not use FieldVO.key values such as "vote_name"',
+                'for access-rule update policy changes, use {"update":["options"],"options":{"policy":...,"list_options":{}}}; do not use update:["options.policy"]',
+                'use options.user_scope with type user/department/actor and numeric id; do not use FieldVO type "member" here',
+                'use assign-users only for updating user_scope later',
+                'assign-users preserves existing policy when body.update=["user_scope"]',
+            ],
+        };
+    }
+    if (requestType === 'InsertReqVO') {
+        return {
+            shapeHint: {
+                fields: {
+                    '1001': 'SO-1001',
+                    '1002': 199,
+                },
+            },
+            commonMistakes: [
+                'row fields must use numeric field ids as JSON object keys',
+                'do not use field labels such as "标题" or "投票标题" as keys',
+                'run table get first when field ids are unclear',
+                'do not add access policy fields; the CLI resolves access policy internally',
+            ],
+            suggestions: [
+                'run: arcubase table get --app-id <app_id> --table-id <table_id>',
+                'retry with: arcubase row create --app-id <app_id> --table-id <table_id> --body-json \'{"fields":{"1001":"今天吃什么"}}\'',
+            ],
+        };
+    }
+    if (requestType === 'EntityQueryReqVO') {
+        return {
+            shapeHint: {
+                limit: 20,
+                offset: 0,
+                search: { text_search: 'SO-1001' },
+            },
+            commonMistakes: [
+                'limit, offset, search, sorts, and view_mode belong inside --body-json',
+                'do not pass --limit or --offset flags',
+                'do not add access policy fields; the CLI resolves access policy internally',
+            ],
+            suggestions: [
+                'retry with: arcubase row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0}\'',
+            ],
+        };
+    }
+    if (requestType === 'EntityUpdateReqVO') {
+        return {
+            shapeHint: {
+                data: { '1002': 299 },
+                changed_fields: [1002],
+            },
+            commonMistakes: [
+                'use data, not fields',
+                'changed_fields is required and must match data keys',
+                'do not add access policy fields; the CLI resolves access policy internally',
+            ],
+        };
+    }
+    if (requestType === 'EntityBulkUpdateReqVO') {
+        return {
+            shapeHint: {
+                selection: {
+                    type: 'ids',
+                    ids: [2188890411, 2188890412],
+                    length: 2,
+                },
+                fields: [
+                    {
+                        id: 1003,
+                        action: {
+                            type: 'set',
+                            value: 2,
+                        },
+                    },
+                ],
+            },
+            commonMistakes: [
+                'bulk update fields[].action must be an object with type',
+                'use {"type":"set","value":2} to assign a scalar value',
+                'do not use value_set, setValue, or a top-level value field',
+                'use {"type":"number_add","number_add":10} only for numeric increments',
+                'selection.type=ids requires ids and length',
+            ],
+            suggestions: [
+                'retry with: arcubase row bulk-update --app-id <app_id> --table-id <table_id> --body-json \'{"selection":{"type":"ids","ids":[2188890411],"length":1},"fields":[{"id":1003,"action":{"type":"set","value":2}}]}\'',
+            ],
+        };
     }
-    throw new CLIError('BODY_VALIDATION_FAILED', message, 2, {
+    return {};
+}
+function buildBodyValidationDetails(scope, command, requestType, issues, env = process.env) {
+    return {
         operation: `${scope}.${command.module}.${command.functionName}`,
         requestType,
-        issues: [
-            {
-                path,
-                message,
-            },
-        ],
-        tsHints: getTypeHints(requestType),
-        docHints: getDocHints(requestType),
-    });
+        issues,
+        tsHints: getTypeHints(requestType, env),
+        docHints: getDocHints(requestType, env),
+        ...buildBodyGuidance(requestType),
+    };
+}
+function throwBodyValidationFailure(message, requestType, path, scope, command, env = process.env) {
+    if (isAssignUsersCommand(scope, command)) {
+        throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildAssignUsersValidationDetails(scope, command, requestType, path, message, env));
+    }
+    throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildBodyValidationDetails(scope, command, requestType, [{ path, message }], env));
+}
+function requireTableCreateSchemaBody(scope, command, body, env) {
+    if (!isRecord(body)) {
+        throwBodyValidationFailure('table create requires a JSON object with name, fields, field_id_seq, layout, options, and workflow_enabled', 'AppCreateEntityReqVO', 'body', scope, command, env);
+    }
+    if (!Array.isArray(body.fields) || body.fields.length === 0) {
+        throwBodyValidationFailure('table create must include non-empty body.fields; empty table shell creation is not allowed', 'AppCreateEntityReqVO', 'body.fields', scope, command, env);
+    }
+    if (typeof body.field_id_seq !== 'number') {
+        throwBodyValidationFailure('table create must include body.field_id_seq greater than every field.id', 'AppCreateEntityReqVO', 'body.field_id_seq', scope, command, env);
+    }
 }
 function stringArray(value) {
     return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
 }
-function requireUpdateContains(scope, command, body, field) {
+function validateAccessRuleUserScope(scope, command, requestType, userScope, env, pathPrefix = 'body.options.user_scope') {
+    if (userScope === undefined)
+        return;
+    if (!Array.isArray(userScope)) {
+        throwBodyValidationFailure('access-rule user_scope must be an array of {"type":"user","id":2188889901}', requestType, pathPrefix, scope, command, env);
+    }
+    const allowedTypes = new Set(['user', 'department', 'actor']);
+    for (const [index, item] of userScope.entries()) {
+        if (!isRecord(item)) {
+            throwBodyValidationFailure('access-rule user_scope item must be an object', requestType, `${pathPrefix}.${index}`, scope, command, env);
+        }
+        if (typeof item.type !== 'string' || !allowedTypes.has(item.type)) {
+            throwBodyValidationFailure('access-rule user_scope[].type must be "user", "department", or "actor"; do not use FieldVO type "member" here', requestType, `${pathPrefix}.${index}.type`, scope, command, env);
+        }
+        if (typeof item.id !== 'number' || !Number.isInteger(item.id) || item.id <= 0) {
+            throwBodyValidationFailure('access-rule user_scope[].id must be numeric TenantUser.ID, department ID, or actor ID', requestType, `${pathPrefix}.${index}.id`, scope, command, env);
+        }
+    }
+}
+function requireUpdateContains(scope, command, body, field, env) {
     if (!(field in body))
         return;
     const update = stringArray(body.update);
     if (!update.includes(field)) {
-        throwBodyValidationFailure(`body.update must include "${field}" when body.${field} is present. Example: {"update":["${field}"],"${field}":${field === 'enabled' ? 'true' : '"value"'}}`, command.requestType ?? 'AppIngressUpdateReqVO', 'body.update', scope, command);
+        throwBodyValidationFailure(`body.update must include "${field}" when body.${field} is present. Example: {"update":["${field}"],"${field}":${field === 'enabled' ? 'true' : '"value"'}}`, command.requestType ?? 'AppIngressUpdateReqVO', 'body.update', scope, command, env);
     }
 }
-function validateActionSpecificRawBody(scope, command, body) {
+function validateActionSpecificRawBody(scope, command, body, env) {
     if (!isRecord(body) || !command.requestType) {
         return;
     }
     if (isAssignUsersCommand(scope, command)) {
         if ('users' in body || 'allowedUsers' in body || 'user_scope' in body) {
-            throwBodyValidationFailure('access-rule assign-users only accepts body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":123}]}}', command.requestType, 'body.options.user_scope', scope, command);
+            throwBodyValidationFailure('access-rule assign-users only accepts body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}', command.requestType, 'body.options.user_scope', scope, command, env);
+        }
+    }
+    if (isTableSchemaCommand(scope, command)) {
+        const fields = Array.isArray(body.fields) ? body.fields : [];
+        const hasPermissionPatch = fields.some((field) => isRecord(field) && ('permission' in field || 'permissions' in field || 'field_visibility' in field));
+        if (hasPermissionPatch) {
+            throwBodyValidationFailure('table schema cannot configure per-user permissions. Use access-rule create/update with options.policy.fields for hidden fields', command.requestType, 'body.fields', scope, command, env);
+        }
+    }
+    if (isAccessRuleCommand(scope, command)) {
+        const update = stringArray(body.update);
+        if (isAccessRuleUpdateCommand(scope, command) && update.some((item) => item.startsWith('options.'))) {
+            throwBodyValidationFailure('access-rule update cannot patch nested options paths. Use {"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":{}}}', command.requestType, 'body.update', scope, command, env);
+        }
+        if ('permissions' in body || 'field_visibility' in body || 'description' in body) {
+            throwBodyValidationFailure('access-rule body only supports name, enabled, type, and options; use options.policy.actions and options.policy.fields', command.requestType, 'body', scope, command, env);
+        }
+        const options = isRecord(body.options) ? body.options : undefined;
+        if (options && ('permissions' in options || 'field_visibility' in options)) {
+            throwBodyValidationFailure('access-rule options only supports user_scope, policy, list_options, i18n_name; use options.policy.actions and options.policy.fields', command.requestType, 'body.options', scope, command, env);
+        }
+        const policy = options && isRecord(options.policy) ? options.policy : undefined;
+        if (isAccessRuleUpdateCommand(scope, command) && update.includes('options') && options?.user_scope !== undefined && !policy) {
+            throwBodyValidationFailure('access-rule update with update:["options"] cannot change only options.user_scope because it overwrites policy. Use access-rule assign-users for user assignment, or include the full options.policy and options.list_options.', command.requestType, 'body.options.policy', scope, command, env);
+        }
+        validateAccessRuleUserScope(scope, command, command.requestType, options?.user_scope, env);
+        const actions = policy && Array.isArray(policy.actions) ? policy.actions : [];
+        if (actions.includes('read') || actions.includes('write')) {
+            throwBodyValidationFailure('access-rule policy.actions must use Arcubase action codes: use "view" for read and "add","edit" for write; do not use "read", "write", or "insert"', command.requestType, 'body.options.policy.actions', scope, command, env);
+        }
+        const fields = policy && Array.isArray(policy.fields) ? policy.fields : [];
+        const allowedSystemFieldKeys = new Set(['created', 'updated', 'creator']);
+        for (const [index, field] of fields.entries()) {
+            if (!isRecord(field))
+                continue;
+            if (typeof field.key === 'number' || (typeof field.key === 'string' && /^\d+$/.test(field.key))) {
+                throwBodyValidationFailure('access-rule policy.fields[].key must be a string prefixed with colon, for example ":1002"; do not use raw numbers', command.requestType, `body.options.policy.fields.${index}.key`, scope, command, env);
+            }
+            if (typeof field.key === 'string' && !field.key.startsWith(':') && !allowedSystemFieldKeys.has(field.key)) {
+                throwBodyValidationFailure('access-rule policy.fields[].key must use Arcubase permission keys such as ":1002"; do not use FieldVO.key values such as "vote_name"', command.requestType, `body.options.policy.fields.${index}.key`, scope, command, env);
+            }
         }
     }
 }
-function validateActionSpecificBody(scope, command, flags, body) {
+function validateActionSpecificBody(scope, command, flags, body, env) {
     if (!isRecord(body) || !command.requestType) {
         return;
     }
     if (scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update') {
-        requireUpdateContains(scope, command, body, 'enabled');
-        requireUpdateContains(scope, command, body, 'name');
-        requireUpdateContains(scope, command, body, 'options');
+        requireUpdateContains(scope, command, body, 'enabled', env);
+        requireUpdateContains(scope, command, body, 'name', env);
+        requireUpdateContains(scope, command, body, 'options', env);
     }
     if (isAssignUsersCommand(scope, command)) {
         const update = stringArray(body.update);
         const options = isRecord(body.options) ? body.options : undefined;
         const userScope = options && Array.isArray(options.user_scope) ? options.user_scope : undefined;
         if ('users' in body || 'allowedUsers' in body) {
-            throwBodyValidationFailure('access-rule assign-users only accepts body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":123}]}}', command.requestType, 'body.options.user_scope', scope, command);
+            throwBodyValidationFailure('access-rule assign-users only accepts body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}', command.requestType, 'body.options.user_scope', scope, command, env);
         }
         if (!update.includes('user_scope')) {
-            throwBodyValidationFailure('access-rule assign-users requires body.update to include "user_scope"', command.requestType, 'body.update', scope, command);
+            throwBodyValidationFailure('access-rule assign-users requires body.update to include "user_scope"', command.requestType, 'body.update', scope, command, env);
         }
         if (!userScope || userScope.length === 0) {
-            throwBodyValidationFailure('access-rule assign-users requires non-empty body.options.user_scope', command.requestType, 'body.options.user_scope', scope, command);
+            throwBodyValidationFailure('access-rule assign-users requires non-empty body.options.user_scope', command.requestType, 'body.options.user_scope', scope, command, env);
         }
+        validateAccessRuleUserScope(scope, command, command.requestType, userScope, env);
         const assignedUserScope = userScope;
         for (const [index, item] of assignedUserScope.entries()) {
             if (!isRecord(item)) {
-                throwBodyValidationFailure('access-rule assign-users requires each body.options.user_scope item to be an object', command.requestType, `body.options.user_scope.${index}`, scope, command);
+                throwBodyValidationFailure('access-rule assign-users requires each body.options.user_scope item to be an object', command.requestType, `body.options.user_scope.${index}`, scope, command, env);
             }
-            if (item.type !== 'member') {
-                throwBodyValidationFailure('access-rule assign-users requires body.options.user_scope[].type to be "member"', command.requestType, `body.options.user_scope.${index}.type`, scope, command);
+            if (item.type !== 'user') {
+                throwBodyValidationFailure('access-rule assign-users requires body.options.user_scope[].type to be "user"', command.requestType, `body.options.user_scope.${index}.type`, scope, command, env);
             }
             if (typeof item.id !== 'number' || !Number.isInteger(item.id) || item.id <= 0) {
-                throwBodyValidationFailure('access-rule assign-users requires body.options.user_scope[].id to be numeric TenantUser.ID', command.requestType, `body.options.user_scope.${index}.id`, scope, command);
+                throwBodyValidationFailure('access-rule assign-users requires body.options.user_scope[].id to be numeric TenantUser.ID', command.requestType, `body.options.user_scope.${index}.id`, scope, command, env);
             }
         }
     }
@@ -401,17 +915,314 @@ function validateActionSpecificBody(scope, command, flags, body) {
         const conditionKeys = condition ? Object.keys(condition).filter((key) => key !== 'selectAll') : [];
         if (action === 'query') {
             if (type === 'condition') {
-                throwBodyValidationFailure('selection.type=condition is not supported for action=query; use selection.type=ids or selection.type=all, or use row query for search conditions', command.requestType, 'body.selection.type', scope, command);
+                throwBodyValidationFailure('selection.type=condition is not supported for action=query; use selection.type=ids or selection.type=all, or use row query for search conditions', command.requestType, 'body.selection.type', scope, command, env);
             }
             return;
         }
         if ((action === 'archive' || action === 'delete' || action === 'batch_print') && type === 'all') {
-            throwBodyValidationFailure(`selection.type=all is not supported for action=${action}; use ids or condition`, command.requestType, 'body.selection.type', scope, command);
+            throwBodyValidationFailure(`selection.type=all is not supported for action=${action}; use ids or condition`, command.requestType, 'body.selection.type', scope, command, env);
         }
         if ((action === 'archive' || action === 'delete') && type === 'condition' && conditionKeys.length === 0) {
-            throwBodyValidationFailure(`selection.condition for action=${action} requires at least one q, tab, or filter_* key in addition to selectAll`, command.requestType, 'body.selection.condition', scope, command);
+            throwBodyValidationFailure(`selection.condition for action=${action} requires at least one q, tab, or filter_* key in addition to selectAll`, command.requestType, 'body.selection.condition', scope, command, env);
+        }
+    }
+}
+function unwrapData(value) {
+    let current = value;
+    for (let i = 0; i < 3; i += 1) {
+        if (isRecord(current) && isRecord(current.data)) {
+            current = current.data;
+            continue;
+        }
+        break;
+    }
+    return current;
+}
+function requiredRowAction(command, flags) {
+    if (command.commandPath[0] !== 'row')
+        return undefined;
+    switch (command.commandPath[1]) {
+        case 'query':
+        case 'get':
+            return 'view';
+        case 'create':
+            return 'add';
+        case 'update':
+            return 'edit';
+        case 'delete':
+            return 'delete';
+        case 'bulk-update':
+            return 'bulk_update';
+        case 'selection-action':
+            return flagValue(flags, 'action') || undefined;
+        default:
+            return undefined;
+    }
+}
+function rowCommandNeedsPolicy(command) {
+    return command.scope === 'user' && command.commandPath[0] === 'row';
+}
+function extractIngressItems(appDetail) {
+    const appData = unwrapData(appDetail);
+    const ingress = isRecord(appData) ? appData.ingress : undefined;
+    const groups = isRecord(ingress) && Array.isArray(ingress.groups) ? ingress.groups : [];
+    const items = [];
+    for (const group of groups) {
+        const groupItems = isRecord(group) && Array.isArray(group.items) ? group.items : [];
+        for (const item of groupItems) {
+            if (!isRecord(item))
+                continue;
+            const id = typeof item.id === 'string' ? item.id : typeof item.ID === 'string' ? item.ID : '';
+            if (id) {
+                items.push({ id });
+            }
+        }
+    }
+    return items;
+}
+function ingressMatchesTableAndAction(ingressDetail, tableId, action) {
+    const ingressData = unwrapData(ingressDetail);
+    if (!isRecord(ingressData))
+        return undefined;
+    const id = typeof ingressData.id === 'number' || typeof ingressData.id === 'string'
+        ? ingressData.id
+        : typeof ingressData.ID === 'number' || typeof ingressData.ID === 'string'
+            ? ingressData.ID
+            : undefined;
+    if (String(id ?? '') !== tableId)
+        return undefined;
+    const policyID = typeof ingressData.hash_id === 'string'
+        ? ingressData.hash_id
+        : typeof ingressData.hashId === 'string'
+            ? ingressData.hashId
+            : undefined;
+    const policy = isRecord(ingressData.policy) ? ingressData.policy : undefined;
+    if (!action)
+        return { policyID: policyID || '', policy };
+    const actions = policy && Array.isArray(policy.actions) ? policy.actions.filter((item) => typeof item === 'string') : [];
+    if (!actions.includes(action))
+        return undefined;
+    return { policyID: policyID || '', policy };
+}
+function writtenRowFieldIds(command, body) {
+    if (!isRecord(body))
+        return [];
+    const source = command.commandPath[1] === 'create'
+        ? body.fields
+        : command.commandPath[1] === 'update'
+            ? body.data
+            : undefined;
+    if (!isRecord(source))
+        return [];
+    return Object.keys(source)
+        .filter((key) => /^\d+$/.test(key))
+        .map((key) => Number(key));
+}
+function fieldWriteAllowedByPolicy(policy, fieldId) {
+    if (!policy)
+        return true;
+    const fields = Array.isArray(policy.fields) ? policy.fields : [];
+    const explicit = fields.find((item) => isRecord(item) && item.key === `:${fieldId}`);
+    if (isRecord(explicit) && explicit.write === false)
+        return false;
+    if (isRecord(explicit) && explicit.write === true)
+        return true;
+    if (policy.all_fields_write === false)
+        return false;
+    return true;
+}
+function assertWritableFieldsForRowCommand(command, runtimeEnv, body, policy) {
+    if (command.commandPath[1] !== 'create' && command.commandPath[1] !== 'update') {
+        return;
+    }
+    const denied = writtenRowFieldIds(command, body).filter((fieldId) => !fieldWriteAllowedByPolicy(policy, fieldId));
+    if (denied.length === 0) {
+        return;
+    }
+    const payloadKey = command.commandPath[1] === 'create' ? 'fields' : 'data';
+    throw new CLIError('FIELD_PERMISSION_REQUIRED', `row ${command.commandPath[1]} includes field ids without write permission: ${denied.join(', ')}`, 2, {
+        operation: `user.${command.module}.${command.functionName}`,
+        requestType: command.requestType ?? undefined,
+        issues: denied.map((fieldId) => ({
+            path: `body.${payloadKey}.${fieldId}`,
+            message: 'field is not writable for the resolved Arcubase access rule',
+        })),
+        docHints: [
+            { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
+            { title: 'Runtime reference', file: sdkPath('docs/runtime-reference/README.md', runtimeEnv) },
+        ],
+        suggestions: [
+            'remove non-writable field ids from the row body and retry',
+            'run arcubase table get to map visible business fields to numeric field ids',
+            'ask an admin to update the access-rule if this field should be writable',
+        ],
+    });
+}
+async function resolvePolicyIDForRowCommand(command, runtimeEnv, flags, fetchImpl) {
+    const appId = flagValue(flags, 'app-id');
+    const tableId = flagValue(flags, 'table-id');
+    const action = requiredRowAction(command, flags);
+    if (!appId || !tableId) {
+        throw new CLIError('POLICY_ID_RESOLUTION_FAILED', 'row command requires --app-id and --table-id to resolve Arcubase policy_id', 2, {
+            operation: `user.${command.module}.${command.functionName}`,
+            docHints: getDocHints(command.requestType ?? '', runtimeEnv),
+        });
+    }
+    const appDetail = await requestJSON(runtimeEnv, 'GET', `/api/apps/${encodeURIComponent(appId)}`, undefined, fetchImpl);
+    const ingressItems = extractIngressItems(appDetail.data);
+    for (const item of ingressItems) {
+        const ingressDetail = await requestJSON(runtimeEnv, 'GET', `/api/ingress/${encodeURIComponent(appId)}/${encodeURIComponent(item.id)}`, undefined, fetchImpl);
+        const match = ingressMatchesTableAndAction(ingressDetail.data, tableId, action);
+        if (match) {
+            return { ...match, policyID: match.policyID || item.id };
+        }
+    }
+    throw new CLIError('POLICY_ID_RESOLUTION_FAILED', `no accessible ingress policy found for app ${appId}, table ${tableId}${action ? `, action ${action}` : ''}`, 2, {
+        operation: `user.${command.module}.${command.functionName}`,
+        requestType: command.requestType ?? undefined,
+        issues: [{ path: 'policy_id', message: 'CLI could not resolve policy_id from accessible ingress' }],
+        docHints: [
+            { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
+            { title: 'Runtime reference', file: sdkPath('docs/runtime-reference/README.md', runtimeEnv) },
+        ],
+        suggestions: [
+            'run arcubase entry and confirm the app/table is visible',
+            'ask an admin to create an enabled access-rule with the required action for this table',
+        ],
+    });
+}
+async function injectResolvedPolicyID(command, runtimeEnv, flags, query, body, fetchImpl) {
+    if (!rowCommandNeedsPolicy(command)) {
+        return { query, body };
+    }
+    if (typeof query.policy_id === 'string' && query.policy_id) {
+        return { query, body };
+    }
+    if (isRecord(body) && typeof body.policy_id === 'string' && body.policy_id) {
+        return { query, body };
+    }
+    const resolvedPolicy = await resolvePolicyIDForRowCommand(command, runtimeEnv, flags, fetchImpl);
+    const policyID = resolvedPolicy.policyID;
+    assertWritableFieldsForRowCommand(command, runtimeEnv, body, resolvedPolicy.policy);
+    if (command.commandPath[1] === 'get') {
+        return { query: { ...query, policy_id: policyID }, body };
+    }
+    if (isRecord(body)) {
+        return { query, body: { ...body, policy_id: policyID } };
+    }
+    return { query, body };
+}
+function assertNoUserPolicyIDInput(command, runtimeEnv, query, body) {
+    if (!rowCommandNeedsPolicy(command)) {
+        return;
+    }
+    if ('policy_id' in query || (isRecord(body) && 'policy_id' in body)) {
+        throw new CLIError('INTERNAL_POLICY_ID_NOT_ALLOWED', 'policy_id is an internal Arcubase ingress parameter; use app/table/row ids only', 2, {
+            operation: `user.${command.module}.${command.functionName}`,
+            issues: [{ path: 'policy_id', message: 'do not provide policy_id in flags, query file, or body JSON' }],
+            docHints: [
+                { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
+                { title: 'Runtime reference', file: sdkPath('docs/runtime-reference/README.md', runtimeEnv) },
+            ],
+            suggestions: ['run arcubase entry to find the app/table ids, then retry without policy_id'],
+        });
+    }
+}
+async function requestJSON(runtimeEnv, method, endpoint, body, fetchImpl) {
+    const response = await fetchUpstream(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint), {
+        method,
+        headers: {
+            ...buildRequestHeaders(runtimeEnv),
+            'Content-Type': 'application/json',
+        },
+        body: body === undefined || method === 'GET' ? undefined : JSON.stringify(body),
+    }, endpoint, method, fetchImpl);
+    const raw = await response.text();
+    let parsedResponse = raw;
+    try {
+        parsedResponse = raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        // keep raw text
+    }
+    if (!response.ok) {
+        throwUpstreamHTTPError(endpoint, method, response, parsedResponse);
+    }
+    if (parsedResponse && typeof parsedResponse === 'object' && 'error' in parsedResponse && parsedResponse.error) {
+        const upstreamError = parsedResponse.error;
+        const upstreamMessage = upstreamErrorMessage(upstreamError);
+        throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, { upstreamError });
+    }
+    return { status: response.status, data: parsedResponse };
+}
+function extractCreatedTableID(value) {
+    const candidates = [
+        value,
+        isRecord(value) ? value.data : undefined,
+        isRecord(value) && isRecord(value.data) ? value.data.data : undefined,
+    ];
+    for (const candidate of candidates) {
+        if (isRecord(candidate) && typeof candidate.id === 'number') {
+            return candidate.id;
         }
     }
+    throw new CLIError('UPSTREAM_RESPONSE_INVALID', 'table create response did not include numeric table id', 1);
+}
+function normalizeTableCreateSchemaBody(body, appId, tableId) {
+    const { parent: _parent, ...schemaBody } = body;
+    return {
+        ...schemaBody,
+        id: tableId,
+        app_id: Number.isFinite(Number(appId)) ? Number(appId) : body.app_id,
+        schema_version: typeof body.schema_version === 'number' ? body.schema_version : 0,
+        layout: Array.isArray(body.layout) ? body.layout : [],
+        options: isRecord(body.options)
+            ? body.options
+            : { Buttons: [], CustomActions: [], FrontendEvents: [], TitleFormat: { Fields: [], Parts: [], Body: '' }, misc: {} },
+        workflow_enabled: typeof body.workflow_enabled === 'boolean' ? body.workflow_enabled : false,
+    };
+}
+async function executeTableCreateWithSchema(command, runtimeEnv, flags, body, fetchImpl) {
+    const appId = flagValue(flags, 'app-id');
+    if (!appId) {
+        throw new CLIError('MISSING_PATH_FLAG', 'missing required flag --app-id', 2);
+    }
+    if (!isRecord(body)) {
+        throw new CLIError('BODY_VALIDATION_FAILED', 'table create body must be an object', 2);
+    }
+    const createBody = {
+        name: typeof body.name === 'string' ? body.name : undefined,
+        parent: typeof body.parent === 'number' ? body.parent : 0,
+    };
+    if (!createBody.name) {
+        throw new CLIError('BODY_VALIDATION_FAILED', 'table create requires body.name', 2);
+    }
+    const createResult = await requestJSON(runtimeEnv, command.method, resolveEndpoint(command, flags), createBody, fetchImpl);
+    const tableId = extractCreatedTableID(createResult.data);
+    const saveBody = normalizeTableCreateSchemaBody(body, appId, tableId);
+    const saveSchema = getBodySchema('EntitySaveReqVO');
+    if (!saveSchema) {
+        throw new CLIError('BODY_VALIDATION_FAILED', 'EntitySaveReqVO schema is not available', 2);
+    }
+    const parsedSaveBody = saveSchema.safeParse(saveBody);
+    if (!parsedSaveBody.success) {
+        const message = parsedSaveBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildBodyValidationDetails('admin', command, 'EntitySaveReqVO', parsedSaveBody.error.issues.map((issue) => ({
+            path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',
+            message: issue.message,
+        })), runtimeEnv));
+    }
+    const saveResult = await requestJSON(runtimeEnv, 'PUT', `/api/apps/${encodeURIComponent(appId)}/entity/${encodeURIComponent(String(tableId))}`, parsedSaveBody.data, fetchImpl);
+    return {
+        kind: 'result',
+        commandPath: command.commandPath,
+        status: saveResult.status,
+        data: {
+            id: tableId,
+            created: createResult.data,
+            schema: saveResult.data,
+        },
+    };
 }
 export function summarizeCommand(scope, moduleName, commandName) {
     const command = findCommand(scope, moduleName, commandName);
@@ -425,31 +1236,12 @@ export function summarizeCommand(scope, moduleName, commandName) {
         endpoint: command.endpoint,
         requestType: command.requestType,
         pathFlags: command.pathParams.filter((item) => !getFixedValue(item)).map((item) => item.flag),
-        queryFlags: command.queryParams.filter((item) => !getFixedValue(item)).map((item) => item.flag),
+        queryFlags: visibleQueryParams(command).map((item) => item.flag),
     };
 }
 export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     const parsed = parseCLIArgs(argv);
-    if (scope === 'user' && parsed.commandTokens[0] === 'upload') {
-        if (hasFlag(parsed.flags, 'help') || parsed.commandTokens.length === 1) {
-            return { kind: 'help', text: renderUploadHelp() };
-        }
-        const sourcePath = parsed.commandTokens[1];
-        if (!sourcePath) {
-            throw new CLIError('UPLOAD_SOURCE_REQUIRED', 'upload requires a local file path', 2);
-        }
-        const runtimeEnv = env ?? loadRuntimeEnv(scope);
-        const data = await uploadLocalFile(runtimeEnv, sourcePath, {
-            filename: flagValue(parsed.flags, 'filename'),
-            global: hasFlag(parsed.flags, 'global'),
-        }, fetchImpl);
-        return {
-            kind: 'result',
-            commandPath: ['upload', sourcePath],
-            status: 200,
-            data,
-        };
-    }
+    const envInput = env ?? process.env;
     if (parsed.commandTokens.length === 0) {
         return { kind: 'help', text: renderRootHelp(scope) };
     }
@@ -459,30 +1251,58 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     }
     const singleTokenCommand = !commandName ? findCommand(scope, moduleName) : null;
     if (!commandName && !singleTokenCommand) {
-        return { kind: 'help', text: renderModuleHelp(scope, moduleName) };
+        return { kind: 'help', text: renderModuleHelp(scope, moduleName, envInput) };
     }
     if (hasFlag(parsed.flags, 'help')) {
-        return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName) };
+        return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName, envInput) };
     }
-    const runtimeEnv = env ?? loadRuntimeEnv(scope);
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
         throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName}${commandName ? ` ${commandName}` : ''}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName ?? ''));
     }
+    validateKnownFlags(command, parsed.flags, envInput);
+    const runtimeEnv = env ?? loadRuntimeEnv(scope);
     const endpoint = resolveEndpoint(command, parsed.flags);
     const scalarQuery = buildScalarQuery(command, parsed.flags);
     const fileQuery = loadQueryFromFlags(parsed.flags);
-    const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) };
-    const body = loadBodyFromFlags(parsed.flags);
+    let query = { ...(fileQuery ?? {}), ...(scalarQuery ?? {}) };
+    let body;
+    try {
+        body = loadBodyFromFlags(parsed.flags);
+    }
+    catch (error) {
+        if (error instanceof CLIError && error.code === 'INVALID_BODY_JSON' && command.requestType) {
+            throw new CLIError('INVALID_BODY_JSON', `body json is invalid for ${scope}.${command.commandPath.join(' ')}; fix JSON syntax, then use the canonical ${command.requestType} shape from docs/types`, 2, buildBodyValidationDetails(scope, command, command.requestType, [{ path: 'body', message: 'invalid JSON syntax' }], runtimeEnv));
+        }
+        throw error;
+    }
     let validatedBody = body;
     if (!command.requestType && body !== undefined) {
         throw new CLIError('BODY_JSON_NOT_SUPPORTED', `command does not accept a request body: ${moduleName} ${commandName}`, 2);
     }
     if (command.requestType) {
         if (body === undefined) {
-            throw new CLIError('MISSING_BODY_FILE', `command requires --body-file or --body-json for ${command.requestType}`, 2);
+            throw new CLIError('MISSING_BODY_FILE', `command requires --body-json or --body-file for ${command.requestType}; prefer --body-json to avoid file creation`, 2);
         }
-        validateActionSpecificRawBody(scope, command, body);
+        if (isTableCreateCommand(scope, command)) {
+            requireTableCreateSchemaBody(scope, command, body, runtimeEnv);
+            validateActionSpecificRawBody(scope, command, body, runtimeEnv);
+            const { parent: _parent, ...schemaBody } = isRecord(body) ? body : {};
+            const parsedBody = getBodySchema('EntitySaveReqVO')?.safeParse(schemaBody);
+            if (!parsedBody?.success) {
+                const message = parsedBody
+                    ? parsedBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')
+                    : 'EntitySaveReqVO schema is not available';
+                throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildBodyValidationDetails(scope, command, 'EntitySaveReqVO', parsedBody && !parsedBody.success
+                    ? parsedBody.error.issues.map((issue) => ({
+                        path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',
+                        message: issue.message,
+                    }))
+                    : [{ path: 'body', message }], runtimeEnv));
+            }
+            return executeTableCreateWithSchema(command, runtimeEnv, parsed.flags, parsedBody.data, fetchImpl);
+        }
+        validateActionSpecificRawBody(scope, command, body, runtimeEnv);
         const schema = getBodySchema(command.requestType);
         if (schema) {
             const parsedBody = schema.safeParse(body);
@@ -490,21 +1310,15 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
                 const message = parsedBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
                 if (isAssignUsersCommand(scope, command)) {
                     const hasUserScopeIDIssue = parsedBody.error.issues.some((issue) => issue.path.join('.') === 'options.user_scope.0.id' || issue.path.join('.').startsWith('options.user_scope.'));
-                    throw new CLIError('BODY_VALIDATION_FAILED', hasUserScopeIDIssue ? 'access-rule assign-users requires body.options.user_scope[].id to be numeric TenantUser.ID' : message, 2, buildAssignUsersValidationDetails(scope, command, command.requestType, hasUserScopeIDIssue ? 'body.options.user_scope' : 'body', hasUserScopeIDIssue ? 'access-rule assign-users requires body.options.user_scope[].id to be numeric TenantUser.ID' : message));
+                    throw new CLIError('BODY_VALIDATION_FAILED', hasUserScopeIDIssue ? 'access-rule assign-users requires body.options.user_scope[].id to be numeric TenantUser.ID' : message, 2, buildAssignUsersValidationDetails(scope, command, command.requestType, hasUserScopeIDIssue ? 'body.options.user_scope' : 'body', hasUserScopeIDIssue ? 'access-rule assign-users requires body.options.user_scope[].id to be numeric TenantUser.ID' : message, runtimeEnv));
                 }
-                throw new CLIError('BODY_VALIDATION_FAILED', message, 2, {
-                    operation: `${scope}.${command.module}.${command.functionName}`,
-                    requestType: command.requestType,
-                    issues: parsedBody.error.issues.map((issue) => ({
-                        path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',
-                        message: issue.message,
-                    })),
-                    tsHints: getTypeHints(command.requestType),
-                    docHints: getDocHints(command.requestType),
-                });
+                throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildBodyValidationDetails(scope, command, command.requestType, parsedBody.error.issues.map((issue) => ({
+                    path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',
+                    message: issue.message,
+                })), runtimeEnv));
             }
             validatedBody = parsedBody.data;
-            validateActionSpecificBody(scope, command, parsed.flags, validatedBody);
+            validateActionSpecificBody(scope, command, parsed.flags, validatedBody, runtimeEnv);
         }
         else {
             const unsupportedReason = getUnsupportedBodySchemaReason(command.requestType);
@@ -513,23 +1327,27 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
                     operation: `${scope}.${command.module}.${command.functionName}`,
                     requestType: command.requestType,
                     reason: unsupportedReason,
-                    tsHints: getTypeHints(command.requestType),
-                    docHints: getDocHints(command.requestType),
+                    tsHints: getTypeHints(command.requestType, runtimeEnv),
+                    docHints: getDocHints(command.requestType, runtimeEnv),
                 });
             }
         }
     }
+    assertNoUserPolicyIDInput(command, runtimeEnv, query, validatedBody);
     if (scope === 'user' && (command.functionName === 'insertEntity' || command.functionName === 'updateEntityRow')) {
         await validateFileFieldPayloads(scope, command, runtimeEnv, parsed.flags, validatedBody, fetchImpl);
     }
-    const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
+    const policyInjected = await injectResolvedPolicyID(command, runtimeEnv, parsed.flags, query, validatedBody, fetchImpl);
+    query = policyInjected.query;
+    validatedBody = policyInjected.body;
+    const response = await fetchUpstream(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
         method: command.method,
         headers: {
             ...buildRequestHeaders(runtimeEnv),
             'Content-Type': 'application/json',
         },
         body: validatedBody === undefined || command.method === 'GET' ? undefined : JSON.stringify(validatedBody),
-    });
+    }, endpoint, command.method, fetchImpl);
     const raw = await response.text();
     let parsedResponse = raw;
     try {
@@ -539,20 +1357,12 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
         // keep raw text
     }
     if (!response.ok) {
-        throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1);
+        throwUpstreamHTTPError(endpoint, command.method, response, parsedResponse);
     }
     if (parsedResponse && typeof parsedResponse === 'object' && 'error' in parsedResponse && parsedResponse.error) {
         const upstreamError = parsedResponse.error;
-        const upstreamMessage = typeof upstreamError === 'object' && upstreamError && 'message' in upstreamError && typeof upstreamError.message === 'string'
-            ? upstreamError.message
-            : typeof upstreamError === 'string'
-                ? upstreamError
-                : JSON.stringify(upstreamError);
-        const traceId = typeof parsedResponse.trace_id === 'string'
-            ? parsedResponse.trace_id
-            : typeof parsedResponse.request_id === 'string'
-                ? parsedResponse.request_id
-                : undefined;
+        const upstreamMessage = upstreamErrorMessage(upstreamError);
+        const traceId = extractTraceID(parsedResponse);
         const uploadBindFailure = upstreamMessage.includes('failed to bind upload to assets');
         throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
             endpoint,
@@ -562,10 +1372,10 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
             ...(uploadBindFailure
                 ? {
                     reason: 'the row payload used a file/image upload entry, but Arcubase could not bind that upload into an asset record',
-                    hint: 'verify the upload storage host is reachable from the Arcubase server, then rerun arcubase upload and retry the row insert/update',
+                    hint: 'verify the upload storage host is reachable from the Arcubase server, then use the upload token flow again and retry the row insert/update',
                     docHints: [
-                        { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-                        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                        { title: 'Uploads', file: 'docs/runtime-reference/uploads.md' },
+                        { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
                     ],
                 }
                 : {}),