@carthooks/arcubase-cli 0.1.19 → 0.1.21

package/bundle/arcubase-admin.mjs

@@ -605,6 +605,27 @@ var adminCommands = [
     "queryParams": [],
     "responseType": "AppIngressUpdateRespVO"
   },
+  {
+    "scope": "admin",
+    "module": "access-rule",
+    "functionName": "bulkApplyEntityIngress",
+    "commandPath": [
+      "access-rule",
+      "bulk-apply"
+    ],
+    "method": "POST",
+    "endpoint": "/api/apps/:app_id/access-rules/bulk-apply",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "App.IngressBulkApply",
+    "requestType": "AppIngressBulkApplyReqVO",
+    "queryParams": [],
+    "responseType": "AppIngressBulkApplyRespVO"
+  },
   {
     "scope": "admin",
     "module": "workflow",
@@ -16092,6 +16113,8 @@ var PermitFieldPermitSchema = external_exports.lazy(() => external_exports.objec
 var PermitPolicySchema = external_exports.lazy(() => external_exports.object({ "actions": external_exports.array(external_exports.string()).optional(), "all_fields_read": external_exports.boolean().optional(), "all_fields_write": external_exports.boolean().optional(), "condition": PermitConditionSetSchema.optional(), "description": external_exports.string().optional(), "fields": external_exports.array(PermitFieldPermitSchema).optional(), "id": external_exports.string().optional(), "key": external_exports.string().optional(), "name": external_exports.string().optional() }).strict());
 var PermitUserScopeSchema = external_exports.lazy(() => external_exports.object({ "data": external_exports.object({ "name": external_exports.string().optional() }).strict().optional(), "id": external_exports.number().optional(), "type": external_exports.string().optional() }).strict());
 var EntityIngressOptionsSchema = external_exports.lazy(() => external_exports.object({ "i18n_name": I18NTextSchema.optional(), "list_options": PermitEntityListOptionsSchema.optional(), "policy": PermitPolicySchema.optional(), "user_scope": external_exports.array(PermitUserScopeSchema).optional() }).strict());
+var AppIngressBulkApplyItemVOSchema = external_exports.lazy(() => external_exports.object({ "enabled": external_exports.boolean().optional(), "name": external_exports.string().optional(), "options": EntityIngressOptionsSchema.optional(), "rule_id": external_exports.number().optional(), "table_id": external_exports.number().optional(), "type": external_exports.string().optional() }).strict());
+var AppIngressBulkApplyReqVOSchema = external_exports.lazy(() => external_exports.object({ "dry_run": external_exports.boolean().optional(), "items": external_exports.array(AppIngressBulkApplyItemVOSchema).optional(), "mode": external_exports.string().optional() }).strict());
 var AppIngressCreateReqVOSchema = external_exports.lazy(() => external_exports.object({ "enabled": external_exports.boolean().optional(), "entity_id": external_exports.number().optional(), "icon_name": external_exports.string().optional(), "name": external_exports.string().optional(), "options": EntityIngressOptionsSchema.optional(), "type": external_exports.string().optional(), "url": external_exports.string().optional() }).strict());
 var AppIngressUpdateReqVOSchema = external_exports.lazy(() => external_exports.object({ "enabled": external_exports.boolean().optional(), "name": external_exports.string().optional(), "options": EntityIngressOptionsSchema.optional(), "update": external_exports.array(external_exports.string()).optional() }).strict());
 var GormDeletedAtSchema = external_exports.lazy(() => external_exports.object({ "Time": external_exports.string().optional(), "Valid": external_exports.boolean().optional() }).strict());
@@ -16159,6 +16182,7 @@ var UserProfileUpdateReqVOSchema = external_exports.lazy(() => external_exports.
 var bodySchemas = {
   "AppCreateByTenantsReqVO": AppCreateByTenantsReqVOSchema,
   "AppCreateEntityReqVO": AppCreateEntityReqVOSchema,
+  "AppIngressBulkApplyReqVO": AppIngressBulkApplyReqVOSchema,
   "AppIngressCreateReqVO": AppIngressCreateReqVOSchema,
   "AppIngressUpdateReqVO": AppIngressUpdateReqVOSchema,
   "AppUpdateAppReqVO": AppUpdateAppReqVOSchema,
@@ -16193,6 +16217,10 @@ var typeIndex = {
     "file": "types/app.ts",
     "dependencies": []
   },
+  "AppIngressBulkApplyReqVO": {
+    "file": "types/ingress.ts",
+    "dependencies": []
+  },
   "AppIngressCreateReqVO": {
     "file": "types/ingress.ts",
     "dependencies": []
@@ -17053,6 +17081,10 @@ var 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" },
@@ -17166,6 +17198,10 @@ var 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" },
@@ -17416,6 +17452,489 @@ async function uploadLocalFileWithToken(filePath, token, fetchImpl = fetch) {
   return { objectKey };
 }
 
+// src/generated/help_examples.generated.ts
+var helpExamplesIndex = {
+  "admin.access-rule.assign-users": {
+    "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"
+        ]
+      }
+    ]
+  },
+  "admin.access-rule.bulk-apply": {
+    "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"
+        ]
+      }
+    ]
+  },
+  "admin.access-rule.create": {
+    "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"
+        ]
+      }
+    ]
+  },
+  "user.row.bulk-update": {
+    "command": [
+      "row",
+      "bulk-update"
+    ],
+    "examples": [
+      {
+        "title": "bulk update explicit row ids",
+        "body": {
+          "selection": {
+            "type": "ids",
+            "ids": [
+              2188890411,
+              2188890412
+            ],
+            "length": 2
+          },
+          "fields": [
+            {
+              "id": 1003,
+              "action": {
+                "type": "set",
+                "value": 2
+              }
+            }
+          ]
+        }
+      },
+      {
+        "title": "bulk update rows selected by a search condition",
+        "body": {
+          "selection": {
+            "type": "condition",
+            "condition": {
+              "selectAll": true,
+              "q": "SO-1001"
+            },
+            "length": 0
+          },
+          "fields": [
+            {
+              "id": 1003,
+              "action": {
+                "type": "set",
+                "value": 2
+              }
+            }
+          ]
+        },
+        "notes": [
+          "condition selection uses row-query style keys such as q, tab, and filter_:1002"
+        ]
+      }
+    ]
+  },
+  "user.row.selection-action": {
+    "command": [
+      "row",
+      "selection-action"
+    ],
+    "examples": [
+      {
+        "title": "run a custom action against explicit row ids",
+        "body": {
+          "selection": {
+            "type": "ids",
+            "ids": [
+              2188890411
+            ],
+            "length": 1
+          }
+        },
+        "notes": [
+          "pass the backend action code with --action",
+          "for query action, use ids or all selection instead of condition selection"
+        ]
+      },
+      {
+        "title": "run a custom action against a filtered selection",
+        "body": {
+          "selection": {
+            "type": "condition",
+            "condition": {
+              "selectAll": true,
+              "q": "SO-1001"
+            },
+            "length": 0
+          }
+        },
+        "notes": [
+          "condition selection uses row-query style keys such as q, tab, and filter_:1002"
+        ]
+      }
+    ]
+  }
+};
+
+// src/runtime/help_examples.ts
+function binaryForScope(scope) {
+  return scope === "admin" ? "arcubase-admin" : "arcubase";
+}
+function getFixedValue(value) {
+  if (!("fixedValue" in value)) {
+    return void 0;
+  }
+  const fixedValue = value.fixedValue;
+  return typeof fixedValue === "string" ? fixedValue : void 0;
+}
+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(".")}`;
+}
+function getCommandHelpExamples(scope, command) {
+  return helpExamplesIndex[helpExampleKey(scope, command)]?.examples ?? [];
+}
+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 === void 0 ? [] : [`  ${binary} ${command.commandPath.join(" ")} ${pathFlagPlaceholders(command)}--body-json '${JSON.stringify(example.body)}'`.replace(/\s+/g, " ").trim()],
+      ...(example.notes ?? []).map((note) => `  - ${note}`),
+      ""
+    ])
+  ].join("\n").trimEnd();
+}
+
 // src/runtime/execute.ts
 function renderRootHelp(scope) {
   const binary = scope === "admin" ? "arcubase-admin" : "arcubase";
@@ -17453,9 +17972,32 @@ 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 } : void 0;
 }
+function throwHelpExamplesRequiresCommand(scope, moduleName) {
+  const binary = binaryForScope2(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 sdkPath2(file2, env = process.env) {
   return resolveArcubaseSDKPath(file2, env);
 }
+function binaryForScope2(scope) {
+  return scope === "admin" ? "arcubase-admin" : "arcubase";
+}
 function renderCommandHelp(scope, moduleName, commandName, env = process.env) {
   const command = findCommand(scope, moduleName, commandName);
   if (!command) {
@@ -17466,7 +18008,7 @@ function renderCommandHelp(scope, moduleName, commandName, env = process.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 pathFlags = command.pathParams.filter((item) => !getFixedValue2(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;
@@ -17478,6 +18020,7 @@ function renderCommandHelp(scope, moduleName, commandName, env = process.env) {
     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:",
       `  - ${tableCreateExampleBody}`,
@@ -17576,7 +18119,7 @@ function coerceScalar(value, typeText) {
   }
   return value;
 }
-function getFixedValue(value) {
+function getFixedValue2(value) {
   if (!("fixedValue" in value)) {
     return void 0;
   }
@@ -17586,7 +18129,7 @@ function getFixedValue(value) {
 function resolveEndpoint(command, flags) {
   let resolved = command.endpoint;
   for (const mapping of command.pathParams) {
-    const value = getFixedValue(mapping) ?? flagValue(flags, mapping.flag);
+    const value = getFixedValue2(mapping) ?? flagValue(flags, mapping.flag);
     if (!value) {
       throw new CLIError("MISSING_PATH_FLAG", `missing required flag --${mapping.flag}`, 2);
     }
@@ -17600,21 +18143,21 @@ function buildScalarQuery(command, flags) {
   }
   const out = {};
   for (const scalar of effectiveQueryParams(command)) {
-    const value = getFixedValue(scalar) ?? flagValue(flags, scalar.flag);
+    const value = getFixedValue2(scalar) ?? flagValue(flags, scalar.flag);
     if (value === void 0) continue;
     out[scalar.key] = coerceScalar(value, scalar.type);
   }
   return Object.keys(out).length > 0 ? out : void 0;
 }
 function validateKnownFlags(command, flags, env = process.env) {
-  const allowed = /* @__PURE__ */ new Set(["help", "body-file", "body-json", "query-file"]);
+  const allowed = /* @__PURE__ */ new Set(["help", "help-examples", "body-file", "body-json", "query-file"]);
   for (const mapping of command.pathParams) {
-    if (!getFixedValue(mapping)) {
+    if (!getFixedValue2(mapping)) {
       allowed.add(mapping.flag);
     }
   }
   for (const query of visibleQueryParams(command)) {
-    if (!getFixedValue(query)) {
+    if (!getFixedValue2(query)) {
       allowed.add(query.flag);
     }
   }
@@ -17652,7 +18195,7 @@ function buildUnknownFlagDetails(command, flag, env = process.env) {
       `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()];
+    details.suggestions = [`retry with: ${command.commandPath.join(" ")} ${command.pathParams.filter((item) => !getFixedValue2(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)) {
     Object.assign(details, buildBodyGuidance("EntityQueryReqVO"));
@@ -17668,7 +18211,7 @@ function buildUnknownFlagDetails(command, flag, env = process.env) {
 }
 function visibleQueryParams(command) {
   if (!command) return [];
-  return effectiveQueryParams(command).filter((item) => !getFixedValue(item));
+  return effectiveQueryParams(command).filter((item) => !getFixedValue2(item));
 }
 function effectiveQueryParams(command) {
   if (!command) return [];
@@ -17917,6 +18460,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";
 }
@@ -18324,6 +18870,112 @@ function validateAccessRuleUserScope(scope, command, requestType, userScope, env
     }
   }
 }
+function normalizeNumericAccessRuleUserScopeIDs(scope, command, body) {
+  if (!isAccessRuleCommand(scope, command) || !isRecord3(body)) {
+    return body;
+  }
+  const normalizeUserScope = (userScope) => {
+    if (!Array.isArray(userScope)) return { value: userScope, changed: false };
+    let changed = false;
+    const value = userScope.map((item) => {
+      if (!isRecord3(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 (!isRecord3(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 (isRecord3(nextItem.options)) {
+        const normalizedUserScope2 = normalizeUserScope(nextItem.options.user_scope);
+        if (normalizedUserScope2.changed) {
+          nextItem = {
+            ...nextItem,
+            options: {
+              ...nextItem.options,
+              user_scope: normalizedUserScope2.value
+            }
+          };
+          changed = true;
+        }
+      }
+      return nextItem;
+    });
+    return changed ? { ...body, items } : body;
+  }
+  if (!isRecord3(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 = /* @__PURE__ */ new Set(["created", "updated", "creator"]);
+  for (const [index, field] of fields.entries()) {
+    if (!isRecord3(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;
   const update = stringArray(body.update);
@@ -18369,6 +19021,54 @@ 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 !== void 0 && 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 (!isRecord3(item)) {
+          throwBodyValidationFailure(
+            "access-rule bulk-apply body.items[] must be an object",
+            command.requestType,
+            `body.items.${index}`,
+            scope,
+            command,
+            env
+          );
+        }
+        const options2 = isRecord3(item.options) ? item.options : void 0;
+        if (!options2) {
+          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, options2.user_scope, env, `body.items.${index}.options.user_scope`);
+        validateAccessRulePolicyShape(scope, command, command.requestType, isRecord3(options2.policy) ? options2.policy : void 0, env, `body.items.${index}.options.policy`);
+      }
+      return;
+    }
     const update = stringArray(body.update);
     if (isAccessRuleUpdateCommand(scope, command) && update.some((item) => item.startsWith("options."))) {
       throwBodyValidationFailure(
@@ -18413,42 +19113,7 @@ function validateActionSpecificRawBody(scope, command, body, 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 = /* @__PURE__ */ new Set(["created", "updated", "creator"]);
-    for (const [index, field] of fields.entries()) {
-      if (!isRecord3(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) {
@@ -19124,16 +19789,32 @@ 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 command2 = commandName ? findCommand(scope, moduleName, commandName) : singleTokenCommand;
+    if (!command2) {
+      throw new CLIError("UNKNOWN_COMMAND", `unknown command: ${moduleName}${commandName ? ` ${commandName}` : ""}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName ?? ""));
+    }
+    return { kind: "help", text: renderCommandHelpExamples(scope, command2) };
+  }
   if (hasFlag(parsed.flags, "help")) {
     return { kind: "help", text: renderCommandHelp(scope, moduleName, commandName, envInput) };
   }
@@ -19178,6 +19859,7 @@ async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     if (body === void 0) {
       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);