@carthooks/arcubase-cli 0.1.19 → 0.1.21

package/dist/runtime/execute.js

@@ -10,6 +10,7 @@ import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupp
 import { resolveArcubaseSDKPath } from './paths.js';
 import { compileCSVImportMapping, compileExcelImportMapping } from './entity_import_mapping.js';
 import { uploadLocalFileWithToken } from './local_upload.js';
+import { renderCommandHelpExamples } from './help_examples.js';
 export function renderRootHelp(scope) {
     const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase';
     const items = listModules(scope).map((item) => `  - ${item}`);
@@ -50,9 +51,29 @@ 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;
 }
+function throwHelpExamplesRequiresCommand(scope, moduleName) {
+    const binary = binaryForScope(scope);
+    const suggestions = scope === 'admin'
+        ? [
+            `${binary} access-rule create --help-examples`,
+            `${binary} access-rule assign-users --help-examples`,
+        ]
+        : [
+            `${binary} row bulk-update --help-examples`,
+            `${binary} row selection-action --help-examples`,
+        ];
+    throw new CLIError('HELP_EXAMPLES_REQUIRES_COMMAND', '--help-examples must follow a final command', 2, {
+        operation: moduleName ? `${binary} ${moduleName} --help-examples` : `${binary} --help-examples`,
+        hint: `retry with a final command, for example: ${suggestions[0]}`,
+        suggestions,
+    });
+}
 function sdkPath(file, env = process.env) {
     return resolveArcubaseSDKPath(file, env);
 }
+function binaryForScope(scope) {
+    return scope === 'admin' ? 'arcubase-admin' : 'arcubase';
+}
 export function renderCommandHelp(scope, moduleName, commandName, env = process.env) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
@@ -75,6 +96,7 @@ export function renderCommandHelp(scope, moduleName, commandName, env = process.
         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',
+        `copyable examples: ${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${command.commandPath.join(' ')} --help-examples`,
         ...(isTableCreate
             ? [
                 'body-json example:',
@@ -229,7 +251,7 @@ 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']);
+    const allowed = new Set(['help', 'help-examples', 'body-file', 'body-json', 'query-file']);
     for (const mapping of command.pathParams) {
         if (!getFixedValue(mapping)) {
             allowed.add(mapping.flag);
@@ -555,6 +577,9 @@ function buildTableCreateExampleBody() {
 function isAssignUsersCommand(scope, command) {
     return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users';
 }
+function isAccessRuleBulkApplyCommand(scope, command) {
+    return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'bulk-apply';
+}
 function isTableCreateCommand(scope, command) {
     return scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'create';
 }
@@ -914,6 +939,97 @@ function validateAccessRuleUserScope(scope, command, requestType, userScope, env
         }
     }
 }
+function normalizeNumericAccessRuleUserScopeIDs(scope, command, body) {
+    if (!isAccessRuleCommand(scope, command) || !isRecord(body)) {
+        return body;
+    }
+    const normalizeUserScope = (userScope) => {
+        if (!Array.isArray(userScope))
+            return { value: userScope, changed: false };
+        let changed = false;
+        const value = userScope.map((item) => {
+            if (!isRecord(item) || typeof item.id !== 'string' || !/^\d+$/.test(item.id)) {
+                return item;
+            }
+            const id = Number(item.id);
+            if (!Number.isFinite(id) || !Number.isInteger(id)) {
+                return item;
+            }
+            changed = true;
+            return { ...item, id };
+        });
+        return { value, changed };
+    };
+    const normalizeNumericID = (value) => {
+        if (typeof value !== 'string' || !/^\d+$/.test(value))
+            return { value, changed: false };
+        const id = Number(value);
+        if (!Number.isFinite(id) || !Number.isInteger(id))
+            return { value, changed: false };
+        return { value: id, changed: true };
+    };
+    if (isAccessRuleBulkApplyCommand(scope, command) && Array.isArray(body.items)) {
+        let changed = false;
+        const items = body.items.map((item) => {
+            if (!isRecord(item))
+                return item;
+            let nextItem = item;
+            for (const key of ['table_id', 'rule_id']) {
+                const normalized = normalizeNumericID(nextItem[key]);
+                if (normalized.changed) {
+                    nextItem = { ...nextItem, [key]: normalized.value };
+                    changed = true;
+                }
+            }
+            if (isRecord(nextItem.options)) {
+                const normalizedUserScope = normalizeUserScope(nextItem.options.user_scope);
+                if (normalizedUserScope.changed) {
+                    nextItem = {
+                        ...nextItem,
+                        options: {
+                            ...nextItem.options,
+                            user_scope: normalizedUserScope.value,
+                        },
+                    };
+                    changed = true;
+                }
+            }
+            return nextItem;
+        });
+        return changed ? { ...body, items } : body;
+    }
+    if (!isRecord(body.options)) {
+        return body;
+    }
+    const normalizedUserScope = normalizeUserScope(body.options.user_scope);
+    if (!normalizedUserScope.changed)
+        return body;
+    return {
+        ...body,
+        options: {
+            ...body.options,
+            user_scope: normalizedUserScope.value,
+        },
+    };
+}
+function validateAccessRulePolicyShape(scope, command, requestType, policy, env, pathPrefix) {
+    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"', requestType, `${pathPrefix}.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', requestType, `${pathPrefix}.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"', requestType, `${pathPrefix}.fields.${index}.key`, scope, command, env);
+        }
+    }
+}
 function requireUpdateContains(scope, command, body, field, env) {
     if (!(field in body))
         return;
@@ -939,6 +1055,26 @@ function validateActionSpecificRawBody(scope, command, body, env) {
         }
     }
     if (isAccessRuleCommand(scope, command)) {
+        if (isAccessRuleBulkApplyCommand(scope, command)) {
+            if (!Array.isArray(body.items) || body.items.length === 0) {
+                throwBodyValidationFailure('access-rule bulk-apply requires non-empty body.items; put every table/rule assignment in body.items', command.requestType, 'body.items', scope, command, env);
+            }
+            if (body.mode !== undefined && body.mode !== 'update_existing' && body.mode !== 'upsert_by_name') {
+                throwBodyValidationFailure('access-rule bulk-apply body.mode must be "update_existing" or "upsert_by_name"', command.requestType, 'body.mode', scope, command, env);
+            }
+            for (const [index, item] of body.items.entries()) {
+                if (!isRecord(item)) {
+                    throwBodyValidationFailure('access-rule bulk-apply body.items[] must be an object', command.requestType, `body.items.${index}`, scope, command, env);
+                }
+                const options = isRecord(item.options) ? item.options : undefined;
+                if (!options) {
+                    throwBodyValidationFailure('access-rule bulk-apply body.items[].options is required and must include the full canonical options object', command.requestType, `body.items.${index}.options`, scope, command, env);
+                }
+                validateAccessRuleUserScope(scope, command, command.requestType, options.user_scope, env, `body.items.${index}.options.user_scope`);
+                validateAccessRulePolicyShape(scope, command, command.requestType, isRecord(options.policy) ? options.policy : undefined, env, `body.items.${index}.options.policy`);
+            }
+            return;
+        }
         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);
@@ -955,22 +1091,7 @@ function validateActionSpecificRawBody(scope, command, body, env) {
             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);
-            }
-        }
+        validateAccessRulePolicyShape(scope, command, command.requestType, policy, env, 'body.options.policy');
     }
 }
 function validateActionSpecificBody(scope, command, flags, body, env) {
@@ -1639,16 +1760,32 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     const parsed = parseCLIArgs(argv);
     const envInput = env ?? process.env;
     if (parsed.commandTokens.length === 0) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope);
+        }
         return { kind: 'help', text: renderRootHelp(scope) };
     }
     const [moduleName, commandName] = parsed.commandTokens;
     if (!moduleName) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope);
+        }
         return { kind: 'help', text: renderRootHelp(scope) };
     }
     const singleTokenCommand = !commandName ? findCommand(scope, moduleName) : null;
     if (!commandName && !singleTokenCommand) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope, moduleName);
+        }
         return { kind: 'help', text: renderModuleHelp(scope, moduleName, envInput) };
     }
+    if (hasFlag(parsed.flags, 'help-examples')) {
+        const command = commandName ? findCommand(scope, moduleName, commandName) : singleTokenCommand;
+        if (!command) {
+            throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName}${commandName ? ` ${commandName}` : ''}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName ?? ''));
+        }
+        return { kind: 'help', text: renderCommandHelpExamples(scope, command) };
+    }
     if (hasFlag(parsed.flags, 'help')) {
         return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName, envInput) };
     }
@@ -1689,6 +1826,7 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
         if (body === undefined) {
             throw new CLIError('MISSING_BODY_FILE', `command requires --body-json or --body-file for ${command.requestType}; prefer --body-json to avoid file creation`, 2);
         }
+        body = normalizeNumericAccessRuleUserScopeIDs(scope, command, body);
         if (isTableCreateCommand(scope, command)) {
             requireTableCreateSchemaBody(scope, command, body, runtimeEnv);
             validateActionSpecificRawBody(scope, command, body, runtimeEnv);

package/dist/runtime/help_examples.d.ts

@@ -0,0 +1,10 @@
+import type { CommandDef, CommandScope } from './command_registry.js';
+type HelpExample = {
+    title: string;
+    body?: unknown;
+    notes?: readonly string[];
+};
+export declare function getCommandHelpExamples(scope: CommandScope, command: CommandDef): readonly HelpExample[];
+export declare function renderCommandHelpExamples(scope: CommandScope, command: CommandDef): string;
+export {};
+//# sourceMappingURL=help_examples.d.ts.map

package/dist/runtime/help_examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help_examples.d.ts","sourceRoot":"","sources":["../../src/runtime/help_examples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAErE,KAAK,WAAW,GAAG;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B,CAAA;AAyBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,WAAW,EAAE,CAEvG;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,CAwB1F"}

package/dist/runtime/help_examples.js

@@ -0,0 +1,48 @@
+import { helpExamplesIndex } from '../generated/help_examples.generated.js';
+function binaryForScope(scope) {
+    return scope === 'admin' ? 'arcubase-admin' : 'arcubase';
+}
+function getFixedValue(value) {
+    if (!('fixedValue' in value)) {
+        return undefined;
+    }
+    const fixedValue = value.fixedValue;
+    return typeof fixedValue === 'string' ? fixedValue : undefined;
+}
+function pathFlagPlaceholders(command) {
+    const parts = command.pathParams
+        .filter((item) => !getFixedValue(item))
+        .map((item) => `--${item.flag} <${item.flag.replace(/-/g, '_')}>`);
+    return parts.length > 0 ? `${parts.join(' ')} ` : '';
+}
+function helpExampleKey(scope, command) {
+    return `${scope}.${command.commandPath.join('.')}`;
+}
+export function getCommandHelpExamples(scope, command) {
+    return helpExamplesIndex[helpExampleKey(scope, command)]?.examples ?? [];
+}
+export function renderCommandHelpExamples(scope, command) {
+    const binary = binaryForScope(scope);
+    const examples = getCommandHelpExamples(scope, command);
+    const header = `${binary} ${command.commandPath.join(' ')} --help-examples`;
+    if (examples.length === 0) {
+        return [
+            header,
+            '',
+            'No dedicated examples for this final command yet.',
+            `Use ${binary} ${command.commandPath.join(' ')} --help for flags, docs, and type paths.`,
+        ].join('\n');
+    }
+    return [
+        header,
+        '',
+        ...examples.flatMap((example) => [
+            `${example.title}:`,
+            ...(example.body === undefined
+                ? []
+                : [`  ${binary} ${command.commandPath.join(' ')} ${pathFlagPlaceholders(command)}--body-json '${JSON.stringify(example.body)}'`.replace(/\s+/g, ' ').trim()]),
+            ...(example.notes ?? []).map((note) => `  - ${note}`),
+            '',
+        ]),
+    ].join('\n').trimEnd();
+}

package/dist/runtime/zod_registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zod_registry.d.ts","sourceRoot":"","sources":["../../src/runtime/zod_registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AA8BrC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAOjE;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQ9D;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAyGlD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,eAAe,EAAE,CAqB7F;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,cAAc,EAAE,CAI3F;AAwED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,cAAc,EAAE,CAInG"}
+{"version":3,"file":"zod_registry.d.ts","sourceRoot":"","sources":["../../src/runtime/zod_registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AA8BrC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAOjE;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQ9D;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AA6GlD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,eAAe,EAAE,CAqB7F;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,cAAc,EAAE,CAI3F;AA4ED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,cAAc,EAAE,CAInG"}

package/dist/runtime/zod_registry.js

@@ -79,6 +79,10 @@ const docHintIndex = {
         { title: 'Access rule', file: 'docs/runtime-reference/access-rule.md' },
         examplesIndexDocHint,
     ],
+    AppIngressBulkApplyReqVO: [
+        { title: 'Access rule', file: 'docs/runtime-reference/access-rule.md' },
+        examplesIndexDocHint,
+    ],
     EntitySaveReqVO: [
         { title: 'Table schema cheatsheet', file: 'docs/runtime-reference/entity-schema.md' },
         { title: 'Field type index', file: 'docs/runtime-reference/entity-schema/README.md' },
@@ -197,6 +201,10 @@ const commandDocHintIndex = {
         { title: 'Access rule', file: 'docs/runtime-reference/access-rule.md' },
         examplesIndexDocHint,
     ],
+    'admin.access-rule.bulkApplyEntityIngress': [
+        { title: 'Access rule', file: 'docs/runtime-reference/access-rule.md' },
+        examplesIndexDocHint,
+    ],
     'user.row.insertEntity': [
         { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
         { title: 'Uploads', file: 'docs/runtime-reference/uploads.md' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carthooks/arcubase-cli",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,9 +22,10 @@
     "codegen:commands": "node scripts/generate-command-registry.mjs",
     "codegen:zod": "node scripts/generate-zod-registry.mjs",
     "codegen:type-index": "node scripts/generate-type-index.mjs",
-    "bundle": "npm run codegen:commands && npm run codegen:zod && npm run codegen:type-index && tsc && node scripts/bundle-cli.mjs",
+    "codegen:help-examples": "node scripts/generate-help-examples.mjs",
+    "bundle": "npm run codegen:commands && npm run codegen:zod && npm run codegen:type-index && npm run codegen:help-examples && tsc && node scripts/bundle-cli.mjs",
     "build": "npm run bundle && npm run docs:llms",
-    "test": "npm run codegen:commands && npm run codegen:zod && npm run codegen:type-index && tsx --test src/tests/*.test.ts",
+    "test": "npm run codegen:commands && npm run codegen:zod && npm run codegen:type-index && npm run codegen:help-examples && tsx --test src/tests/*.test.ts",
     "watch": "tsc --watch",
     "type-check": "tsc --noEmit",
     "docs:llms": "node -e \"\""

package/sdk-dist/api/admin/ingress.ts

@@ -7,6 +7,8 @@ import type {
   AppIngressGetBlocksRespVO,
   AppIngressGetByHashIDRespVO,
   AppIngressListRespVO,
+  AppIngressBulkApplyReqVO,
+  AppIngressBulkApplyRespVO,
   AppIngressUpdateReqVO,
   AppIngressUpdateRespVO,
   AppIngressUpdateBlocksReqVO,
@@ -83,6 +85,15 @@ export async function getEntityIngressList(
   return getDefaultClient().get(`/apps/${appId}/entity/${entityId}/ingress`)
 }
 
+// @endpoint POST /apps/:app_id/access-rules/bulk-apply
+// @controller App.IngressBulkApply
+export async function bulkApplyEntityIngress(
+  appId: string,
+  data: AppIngressBulkApplyReqVO
+): Promise<AppIngressBulkApplyRespVO> {
+  return getDefaultClient().post(`/apps/${appId}/access-rules/bulk-apply`, data)
+}
+
 // @endpoint PUT /apps/:app_id/entity/:entity_id/ingress/:id
 // @controller App.IngressUpdate
 export async function updateEntityIngress(

package/sdk-dist/docs/runtime-reference/access-rule.md

@@ -112,6 +112,25 @@ Rules:
 - Multiple scope items are OR: any matching user, department membership, or actor membership can use the ingress.
 - Department scope includes child departments because Arcubase matches the user's department path.
 
+## Bulk Apply Across Tables
+
+Use this when assigning or updating many access rules for one app. This is the single path for matrix-style permission setup. Do not loop `access-rule list` and `access-rule update` for every table/rule.
+
+```bash
+arcubase-admin access-rule bulk-apply \
+  --app-id 2188893436 \
+  --body-json '{"mode":"upsert_by_name","items":[{"table_id":2188893443,"name":"Sales read write","enabled":true,"type":"form","options":{"user_scope":[{"type":"department","id":2188881201}],"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":true,"all_fields_write":true,"condition":{"mode":"and","conditions":[{"column":"creator","operator":"$eq","value":"[[current_user]]","value_from":0,"value_relation":""}]}},"list_options":{}}},{"table_id":2188893444,"name":"Sales readonly","enabled":true,"type":"form","options":{"user_scope":[{"type":"actor","id":2188883301}],"policy":{"key":"custom","actions":["view"],"all_fields_read":true,"all_fields_write":false},"list_options":{}}}]}'
+```
+
+Rules:
+
+- `bulk-apply` runs in one backend transaction.
+- `mode:"update_existing"` requires every item to include `rule_id`.
+- `mode:"upsert_by_name"` requires every item to include `name` and must not include `rule_id`.
+- Each item must include `table_id` and the full canonical `options` object.
+- Numeric IDs passed as strings are normalized by the CLI for `table_id`, `rule_id`, and `options.user_scope[].id`.
+- Use `dry_run:true` to preview the exact operations without writing.
+
 ## Verify
 
 ```bash

package/sdk-dist/docs/runtime-reference/help-examples/admin/access-rule/assign-users.json

@@ -0,0 +1,23 @@
+{
+  "scope": "admin",
+  "command": ["access-rule", "assign-users"],
+  "examples": [
+    {
+      "title": "replace user_scope with user, department, and actor scopes",
+      "body": {
+        "update": ["user_scope"],
+        "options": {
+          "user_scope": [
+            {"type": "user", "id": 2188889901},
+            {"type": "department", "id": 2188881201},
+            {"type": "actor", "id": 2188883301}
+          ]
+        }
+      },
+      "notes": [
+        "id must be numeric arcubaseUserId, department ID, or actor ID",
+        "assign-users updates user_scope only and preserves the existing policy"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/admin/access-rule/bulk-apply.json

@@ -0,0 +1,105 @@
+{
+  "scope": "admin",
+  "command": ["access-rule", "bulk-apply"],
+  "examples": [
+    {
+      "title": "upsert permission matrix by rule name in one transaction",
+      "body": {
+        "mode": "upsert_by_name",
+        "items": [
+          {
+            "table_id": 2188893443,
+            "name": "Customer archive - sales owns rows",
+            "enabled": true,
+            "type": "form",
+            "options": {
+              "user_scope": [{"type": "department", "id": 2188881201}],
+              "policy": {
+                "key": "custom",
+                "actions": ["view", "add", "edit"],
+                "all_fields_read": true,
+                "all_fields_write": true,
+                "condition": {
+                  "mode": "and",
+                  "conditions": [
+                    {"column": "creator", "operator": "$eq", "value": "[[current_user]]", "value_from": 0, "value_relation": ""}
+                  ]
+                }
+              },
+              "list_options": {}
+            }
+          },
+          {
+            "table_id": 2188893444,
+            "name": "Lead review - manager queue",
+            "enabled": true,
+            "type": "form",
+            "options": {
+              "user_scope": [{"type": "actor", "id": 2188883301}],
+              "policy": {
+                "key": "custom",
+                "actions": ["view", "edit"],
+                "all_fields_read": true,
+                "all_fields_write": true,
+                "condition": {
+                  "mode": "and",
+                  "conditions": [
+                    {"column": ":1004", "operator": "$eq", "value": "pending", "value_from": 0, "value_relation": ""},
+                    {
+                      "column": "",
+                      "operator": "",
+                      "value": null,
+                      "value_from": 0,
+                      "value_relation": "",
+                      "subset": {
+                        "mode": "or",
+                        "conditions": [
+                          {"column": "creator", "operator": "$eq", "value": "[[current_user]]", "value_from": 0, "value_relation": ""},
+                          {"column": ":1005", "operator": "$eq", "value": "high", "value_from": 0, "value_relation": ""}
+                        ]
+                      }
+                    }
+                  ]
+                }
+              },
+              "list_options": {}
+            }
+          }
+        ]
+      },
+      "notes": [
+        "mode upsert_by_name is for idempotent setup; rule names must be unique within each table",
+        "department, actor, and specific user scopes all use options.user_scope",
+        "row-owner isolation uses [[current_user]] in policy.condition"
+      ]
+    },
+    {
+      "title": "preview updates for existing rule ids",
+      "body": {
+        "mode": "update_existing",
+        "dry_run": true,
+        "items": [
+          {
+            "table_id": 2188893443,
+            "rule_id": 2188893557,
+            "enabled": true,
+            "options": {
+              "user_scope": [{"type": "user", "id": 2188889901}],
+              "policy": {
+                "key": "custom",
+                "actions": ["view"],
+                "all_fields_read": true,
+                "all_fields_write": false
+              },
+              "list_options": {}
+            }
+          }
+        ]
+      },
+      "notes": [
+        "dry_run true returns the planned operations without writing",
+        "update_existing requires rule_id on every item"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/admin/access-rule/create.json

@@ -0,0 +1,95 @@
+{
+  "scope": "admin",
+  "command": ["access-rule", "create"],
+  "examples": [
+    {
+      "title": "full access for a specific arcubaseUserId",
+      "body": {
+        "name": "Admin full access",
+        "enabled": true,
+        "type": "form",
+        "options": {
+          "user_scope": [{"type": "user", "id": 2188889977}],
+          "policy": {
+            "key": "custom",
+            "actions": ["view", "add", "edit", "delete"],
+            "all_fields_read": true,
+            "all_fields_write": true
+          },
+          "list_options": {}
+        }
+      }
+    },
+    {
+      "title": "department can view/add/edit only rows created by themselves",
+      "body": {
+        "name": "Sales own rows",
+        "enabled": true,
+        "type": "form",
+        "options": {
+          "user_scope": [{"type": "department", "id": 2188881201}],
+          "policy": {
+            "key": "custom",
+            "actions": ["view", "add", "edit"],
+            "all_fields_read": true,
+            "all_fields_write": true,
+            "condition": {
+              "mode": "and",
+              "conditions": [
+                {"column": "creator", "operator": "$eq", "value": "[[current_user]]", "value_from": 0, "value_relation": ""}
+              ]
+            }
+          },
+          "list_options": {}
+        }
+      },
+      "notes": [
+        "department scope includes child departments",
+        "row-owner isolation uses [[current_user]] on creator"
+      ]
+    },
+    {
+      "title": "role actor can view rows matching a complex AND/OR condition",
+      "body": {
+        "name": "Sales manager review queue",
+        "enabled": true,
+        "type": "form",
+        "options": {
+          "user_scope": [{"type": "actor", "id": 2188883301}],
+          "policy": {
+            "key": "custom",
+            "actions": ["view", "edit"],
+            "all_fields_read": true,
+            "all_fields_write": true,
+            "condition": {
+              "mode": "and",
+              "conditions": [
+                {"column": ":1004", "operator": "$eq", "value": "pending", "value_from": 0, "value_relation": ""},
+                {
+                  "column": "",
+                  "operator": "",
+                  "value": null,
+                  "value_from": 0,
+                  "value_relation": "",
+                  "subset": {
+                    "mode": "or",
+                    "conditions": [
+                      {"column": "creator", "operator": "$eq", "value": "[[current_user]]", "value_from": 0, "value_relation": ""},
+                      {"column": ":1005", "operator": "$eq", "value": "high", "value_from": 0, "value_relation": ""}
+                    ]
+                  }
+                }
+              ]
+            }
+          },
+          "list_options": {}
+        }
+      },
+      "notes": [
+        "actor means Arcubase role id",
+        "condition mode \"and\" and \"or\" are canonical; legacy \"all\" also reads as AND",
+        "nested OR uses subset and leaves the wrapper column/operator empty"
+      ]
+    }
+  ]
+}