@carthooks/arcubase-cli 0.1.9 → 0.1.10

package/bundle/arcubase-admin.mjs

@@ -6658,6 +6658,22 @@ function renderCommandHelp(scope, moduleName, commandName) {
       "  - 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"
     ] : [],
+    ...scope === "admin" && command.commandPath[0] === "access-rule" && command.commandPath[1] === "update" ? [
+      "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}]}}'
+    ] : [],
+    ...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}]}}',
+      "success requires:",
+      "  - result.enabled must be true",
+      "  - result.options.user_scope must contain the assigned numeric TenantUser.ID values",
+      "  - PermitUserScope.id must be numeric TenantUser.ID",
+      "  - Do not copy hash arcubaseTenantUserId into PermitUserScope.id",
+      "  - If result.enabled is false, enable the rule first and retry assign-users"
+    ] : [],
     ...docHints.length > 0 ? ["docs:", ...docHints.map((item) => `  - ${item.title}: ${item.file}`)] : []
   ].join("\n");
 }
@@ -6836,7 +6852,38 @@ async function validateFileFieldPayloads(scope, command, runtimeEnv, flags, body
     }
   }
 }
+function isAssignUsersCommand(scope, command) {
+  return scope === "admin" && command.commandPath[0] === "access-rule" && command.commandPath[1] === "assign-users";
+}
+function buildAssignUsersValidationDetails(scope, command, requestType, path2, message) {
+  return {
+    operation: `${scope}.${command.module}.${command.functionName}`,
+    requestType,
+    issues: [{ path: path2, 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" }
+    ],
+    docHints: getDocHints(requestType),
+    shapeHint: {
+      update: ["user_scope"],
+      options: {
+        user_scope: [{ type: "member", id: 123 }]
+      }
+    },
+    commonMistakes: [
+      "do not use user_scope at top level",
+      "do not use users or allowedUsers",
+      "do not use hash tenant user id as id",
+      "id must be numeric TenantUser.ID"
+    ]
+  };
+}
 function throwBodyValidationFailure(message, requestType, path2, scope, command) {
+  if (isAssignUsersCommand(scope, command)) {
+    throw new CLIError("BODY_VALIDATION_FAILED", message, 2, buildAssignUsersValidationDetails(scope, command, requestType, path2, message));
+  }
   throw new CLIError("BODY_VALIDATION_FAILED", message, 2, {
     operation: `${scope}.${command.module}.${command.functionName}`,
     requestType,
@@ -6850,10 +6897,109 @@ function throwBodyValidationFailure(message, requestType, path2, scope, command)
     docHints: getDocHints(requestType)
   });
 }
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function requireUpdateContains(scope, command, body, field) {
+  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
+    );
+  }
+}
+function validateActionSpecificRawBody(scope, command, body) {
+  if (!isRecord2(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
+      );
+    }
+  }
+}
 function validateActionSpecificBody(scope, command, flags, body) {
   if (!isRecord2(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");
+  }
+  if (isAssignUsersCommand(scope, command)) {
+    const update = stringArray(body.update);
+    const options = isRecord2(body.options) ? body.options : void 0;
+    const userScope = options && Array.isArray(options.user_scope) ? options.user_scope : void 0;
+    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
+      );
+    }
+    if (!update.includes("user_scope")) {
+      throwBodyValidationFailure(
+        'access-rule assign-users requires body.update to include "user_scope"',
+        command.requestType,
+        "body.update",
+        scope,
+        command
+      );
+    }
+    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
+      );
+    }
+    const assignedUserScope = userScope;
+    for (const [index, item] of assignedUserScope.entries()) {
+      if (!isRecord2(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
+        );
+      }
+      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 (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
+        );
+      }
+    }
+  }
   if (command.commandPath[0] === "row" && command.commandPath[1] === "selection-action") {
     const action = flagValue(flags, "action");
     const selection = body.selection;
@@ -6954,13 +7100,30 @@ async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     if (body === void 0) {
       throw new CLIError("MISSING_BODY_FILE", `command requires --body-file or --body-json for ${command.requestType}`, 2);
     }
+    validateActionSpecificRawBody(scope, command, body);
     const schema = getBodySchema(command.requestType);
     if (schema) {
       const parsedBody = schema.safeParse(body);
       if (!parsedBody.success) {
+        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",
-          parsedBody.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "),
+          message,
           2,
           {
             operation: `${scope}.${command.module}.${command.functionName}`,

package/bundle/arcubase.mjs

@@ -6658,6 +6658,22 @@ function renderCommandHelp(scope, moduleName, commandName) {
       "  - 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"
     ] : [],
+    ...scope === "admin" && command.commandPath[0] === "access-rule" && command.commandPath[1] === "update" ? [
+      "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}]}}'
+    ] : [],
+    ...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}]}}',
+      "success requires:",
+      "  - result.enabled must be true",
+      "  - result.options.user_scope must contain the assigned numeric TenantUser.ID values",
+      "  - PermitUserScope.id must be numeric TenantUser.ID",
+      "  - Do not copy hash arcubaseTenantUserId into PermitUserScope.id",
+      "  - If result.enabled is false, enable the rule first and retry assign-users"
+    ] : [],
     ...docHints.length > 0 ? ["docs:", ...docHints.map((item) => `  - ${item.title}: ${item.file}`)] : []
   ].join("\n");
 }
@@ -6836,7 +6852,38 @@ async function validateFileFieldPayloads(scope, command, runtimeEnv, flags, body
     }
   }
 }
+function isAssignUsersCommand(scope, command) {
+  return scope === "admin" && command.commandPath[0] === "access-rule" && command.commandPath[1] === "assign-users";
+}
+function buildAssignUsersValidationDetails(scope, command, requestType, path2, message) {
+  return {
+    operation: `${scope}.${command.module}.${command.functionName}`,
+    requestType,
+    issues: [{ path: path2, 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" }
+    ],
+    docHints: getDocHints(requestType),
+    shapeHint: {
+      update: ["user_scope"],
+      options: {
+        user_scope: [{ type: "member", id: 123 }]
+      }
+    },
+    commonMistakes: [
+      "do not use user_scope at top level",
+      "do not use users or allowedUsers",
+      "do not use hash tenant user id as id",
+      "id must be numeric TenantUser.ID"
+    ]
+  };
+}
 function throwBodyValidationFailure(message, requestType, path2, scope, command) {
+  if (isAssignUsersCommand(scope, command)) {
+    throw new CLIError("BODY_VALIDATION_FAILED", message, 2, buildAssignUsersValidationDetails(scope, command, requestType, path2, message));
+  }
   throw new CLIError("BODY_VALIDATION_FAILED", message, 2, {
     operation: `${scope}.${command.module}.${command.functionName}`,
     requestType,
@@ -6850,10 +6897,109 @@ function throwBodyValidationFailure(message, requestType, path2, scope, command)
     docHints: getDocHints(requestType)
   });
 }
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function requireUpdateContains(scope, command, body, field) {
+  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
+    );
+  }
+}
+function validateActionSpecificRawBody(scope, command, body) {
+  if (!isRecord2(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
+      );
+    }
+  }
+}
 function validateActionSpecificBody(scope, command, flags, body) {
   if (!isRecord2(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");
+  }
+  if (isAssignUsersCommand(scope, command)) {
+    const update = stringArray(body.update);
+    const options = isRecord2(body.options) ? body.options : void 0;
+    const userScope = options && Array.isArray(options.user_scope) ? options.user_scope : void 0;
+    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
+      );
+    }
+    if (!update.includes("user_scope")) {
+      throwBodyValidationFailure(
+        'access-rule assign-users requires body.update to include "user_scope"',
+        command.requestType,
+        "body.update",
+        scope,
+        command
+      );
+    }
+    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
+      );
+    }
+    const assignedUserScope = userScope;
+    for (const [index, item] of assignedUserScope.entries()) {
+      if (!isRecord2(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
+        );
+      }
+      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 (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
+        );
+      }
+    }
+  }
   if (command.commandPath[0] === "row" && command.commandPath[1] === "selection-action") {
     const action = flagValue(flags, "action");
     const selection = body.selection;
@@ -6954,13 +7100,30 @@ async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     if (body === void 0) {
       throw new CLIError("MISSING_BODY_FILE", `command requires --body-file or --body-json for ${command.requestType}`, 2);
     }
+    validateActionSpecificRawBody(scope, command, body);
     const schema = getBodySchema(command.requestType);
     if (schema) {
       const parsedBody = schema.safeParse(body);
       if (!parsedBody.success) {
+        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",
-          parsedBody.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; "),
+          message,
           2,
           {
             operation: `${scope}.${command.module}.${command.functionName}`,

package/dist/runtime/errors.d.ts

@@ -16,6 +16,8 @@ export type CLIErrorDetails = {
     issues?: CLIValidationIssue[];
     tsHints?: CLITSTypeHint[];
     docHints?: CLIDocHint[];
+    shapeHint?: unknown;
+    commonMistakes?: string[];
     reason?: string;
     hint?: string;
     endpoint?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAC7B,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;IACzB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAA;gBAEtB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,EAAE,OAAO,CAAC,EAAE,eAAe;IAQlF,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAC7B,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;IACzB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAA;IACvB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAA;gBAEtB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,EAAE,OAAO,CAAC,EAAE,eAAe;IAQlF,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC"}

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

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAwE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAK/H,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B,CAAA;AAYD,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAa1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAkBhF;AAOD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CA8BvG;AAoSD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,uBAAuB,CActH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAiKrI"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAwE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAK/H,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B,CAAA;AAYD,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAa1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAkBhF;AAOD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAkDvG;AA6bD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,uBAAuB,CActH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAkLrI"}

package/dist/runtime/execute.js

@@ -72,6 +72,26 @@ export function renderCommandHelp(scope, moduleName, commandName) {
                 '  - row query: arcubase row query --app-id <app_id> --table-id <table_id> --body-file query.json',
             ]
             : []),
+        ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update'
+            ? [
+                '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}]}}',
+            ]
+            : []),
+        ...(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}]}}',
+                'success requires:',
+                '  - result.enabled must be true',
+                '  - result.options.user_scope must contain the assigned numeric TenantUser.ID values',
+                '  - PermitUserScope.id must be numeric TenantUser.ID',
+                '  - Do not copy hash arcubaseTenantUserId into PermitUserScope.id',
+                '  - If result.enabled is false, enable the rule first and retry assign-users',
+            ]
+            : []),
         ...(docHints.length > 0
             ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
             : []),
@@ -269,7 +289,38 @@ async function validateFileFieldPayloads(scope, command, runtimeEnv, flags, body
         }
     }
 }
+function isAssignUsersCommand(scope, command) {
+    return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users';
+}
+function buildAssignUsersValidationDetails(scope, command, requestType, path, message) {
+    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' },
+        ],
+        docHints: getDocHints(requestType),
+        shapeHint: {
+            update: ['user_scope'],
+            options: {
+                user_scope: [{ type: 'member', id: 123 }],
+            },
+        },
+        commonMistakes: [
+            'do not use user_scope at top level',
+            'do not use users or allowedUsers',
+            'do not use hash tenant user id as id',
+            'id must be numeric TenantUser.ID',
+        ],
+    };
+}
 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));
+    }
     throw new CLIError('BODY_VALIDATION_FAILED', message, 2, {
         operation: `${scope}.${command.module}.${command.functionName}`,
         requestType,
@@ -283,10 +334,62 @@ function throwBodyValidationFailure(message, requestType, path, scope, command)
         docHints: getDocHints(requestType),
     });
 }
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function requireUpdateContains(scope, command, body, field) {
+    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);
+    }
+}
+function validateActionSpecificRawBody(scope, command, body) {
+    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);
+        }
+    }
+}
 function validateActionSpecificBody(scope, command, flags, body) {
     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');
+    }
+    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);
+        }
+        if (!update.includes('user_scope')) {
+            throwBodyValidationFailure('access-rule assign-users requires body.update to include "user_scope"', command.requestType, 'body.update', scope, command);
+        }
+        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);
+        }
+        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);
+            }
+            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 (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);
+            }
+        }
+    }
     if (command.commandPath[0] === 'row' && command.commandPath[1] === 'selection-action') {
         const action = flagValue(flags, 'action');
         const selection = body.selection;
@@ -379,11 +482,17 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
         if (body === undefined) {
             throw new CLIError('MISSING_BODY_FILE', `command requires --body-file or --body-json for ${command.requestType}`, 2);
         }
+        validateActionSpecificRawBody(scope, command, body);
         const schema = getBodySchema(command.requestType);
         if (schema) {
             const parsedBody = schema.safeParse(body);
             if (!parsedBody.success) {
-                throw new CLIError('BODY_VALIDATION_FAILED', parsedBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '), 2, {
+                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', message, 2, {
                     operation: `${scope}.${command.module}.${command.functionName}`,
                     requestType: command.requestType,
                     issues: parsedBody.error.issues.map((issue) => ({

package/dist/tests/execute_validation.test.js

@@ -19,6 +19,30 @@ function tempJSONFile(payload) {
     fs.writeFileSync(filePath, JSON.stringify(payload, null, 2));
     return filePath;
 }
+function assertAssignUsersGuidance(error, messagePattern) {
+    assert.ok(error instanceof CLIError);
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+    if (messagePattern) {
+        assert.match(error.message, messagePattern);
+    }
+    assert.equal(error.details?.requestType, 'AppIngressUpdateReqVO');
+    assert.deepEqual(error.details?.shapeHint, {
+        update: ['user_scope'],
+        options: {
+            user_scope: [{ type: 'member', id: 123 }],
+        },
+    });
+    assert.deepEqual(error.details?.commonMistakes, [
+        'do not use user_scope at top level',
+        'do not use users or allowedUsers',
+        'do not use hash tenant user id as id',
+        'id must be numeric TenantUser.ID',
+    ]);
+    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'AppIngressUpdateReqVO' && item.file === '/opt/arcubase-sdk/types/ingress.ts'));
+    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'EntityIngressOptions' && item.file === '/opt/arcubase-sdk/types/ingress.ts'));
+    assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'PermitUserScope' && item.file === '/opt/arcubase-sdk/types/common.ts'));
+    return true;
+}
 function validEntitySavePayload(overrides = {}) {
     return {
         id: 2188889845,
@@ -370,3 +394,56 @@ test('entry passes include_app_tables query flag', async () => {
     assert.equal(out.kind, 'result');
     assert.equal(out.data.url, 'https://arcubase.example.com/api/entry?include_app_tables=true');
 });
+test('access-rule update rejects enabled without update whitelist', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'update', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"enabled":true}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.match(error.message, /update.*enabled/);
+        assert.equal(error.details?.requestType, 'AppIngressUpdateReqVO');
+        assert.ok((error.details?.tsHints ?? []).some((item) => item.file === '/opt/arcubase-sdk/types/ingress.ts'));
+        return true;
+    });
+});
+test('access-rule update accepts enabled with update whitelist', async () => {
+    const out = await executeCLI('admin', ['access-rule', 'update', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["enabled"],"enabled":true}'], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(out.data, { update: ['enabled'], enabled: true });
+});
+test('access-rule assign-users rejects users shortcut', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"users":["tu_1"]}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => assertAssignUsersGuidance(error, /options.user_scope/));
+});
+test('access-rule assign-users requires update user_scope and non-empty user_scope', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[]}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => assertAssignUsersGuidance(error, /non-empty/));
+});
+test('access-rule assign-users rejects allowedUsers shortcut', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"allowedUsers":["tu_1"]}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => assertAssignUsersGuidance(error, /options.user_scope/));
+});
+test('access-rule assign-users rejects top-level user_scope', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"user_scope":[{"type":"member","id":123}]}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => assertAssignUsersGuidance(error, /options.user_scope/));
+});
+test('access-rule assign-users rejects non-member scope type', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => assertAssignUsersGuidance(error, /type.*member/));
+});
+test('access-rule assign-users rejects hash tenant user id', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":"zW96OnE0kyJa3B2"}]}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => assertAssignUsersGuidance(error, /numeric TenantUser.ID/));
+});
+test('access-rule assign-users accepts canonical user_scope body', async () => {
+    const out = await executeCLI('admin', ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":123}]}}'], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(out.data.update, ['user_scope']);
+    assert.deepEqual(out.data.options.user_scope, [{ type: 'member', id: 123 }]);
+});

package/dist/tests/help.test.js

@@ -58,3 +58,18 @@ test('admin table update-schema help uses table nouns and body-json', async () =
     assert.doesNotMatch(out.text, /--entity-id/);
     assert.doesNotMatch(out.text, /admin-save-entity/);
 });
+test('admin access-rule help gives update whitelist and assign-users body-json examples', async () => {
+    const update = await executeCLI('admin', ['access-rule', 'update', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(update.kind, 'help');
+    assert.match(update.text, /--app-id/);
+    assert.match(update.text, /--table-id/);
+    assert.match(update.text, /--rule-id/);
+    assert.match(update.text, /"update":\["enabled"\]/);
+    const assign = await executeCLI('admin', ['access-rule', 'assign-users', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(assign.kind, 'help');
+    assert.match(assign.text, /"update":\["user_scope"\]/);
+    assert.match(assign.text, /\{"update":\["user_scope"\],"options":\{"user_scope":\[\{"type":"member","id":123\}\]\}\}/);
+    assert.doesNotMatch(assign.text, /"type":"user"/);
+    assert.doesNotMatch(assign.text, /"users"/);
+    assert.doesNotMatch(assign.text, /"allowedUsers"/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carthooks/arcubase-cli",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",

package/src/runtime/errors.ts

@@ -19,6 +19,8 @@ export type CLIErrorDetails = {
   issues?: CLIValidationIssue[]
   tsHints?: CLITSTypeHint[]
   docHints?: CLIDocHint[]
+  shapeHint?: unknown
+  commonMistakes?: string[]
   reason?: string
   hint?: string
   endpoint?: string

package/src/runtime/execute.ts

@@ -1,6 +1,6 @@
 import { parseCLIArgs, hasFlag, flagValue } from './argv.js'
 import { loadRuntimeEnv, type RuntimeEnv } from './env.js'
-import { CLIError } from './errors.js'
+import { CLIError, type CLIErrorDetails } from './errors.js'
 import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js'
 import { listModules, listModuleCommands, findCommand, findCommandSuggestions, type CommandScope } from './command_registry.js'
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js'
@@ -98,16 +98,19 @@ export function renderCommandHelp(scope: CommandScope, moduleName: string, comma
           'body-json examples:',
           '  - enable: {"update":["enabled"],"enabled":true}',
           '  - rename: {"update":["name"],"name":"Sales read only"}',
-          '  - update options: {"update":["options"],"options":{"user_scope":[{"type":"user","id":123}]}}',
+          '  - update options: {"update":["options"],"options":{"user_scope":[{"type":"member","id":123}]}}',
         ]
       : []),
     ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users'
       ? [
           'body-json example:',
-          '  - {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}',
+          '  - {"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":123}]}}',
           'success requires:',
           '  - result.enabled must be true',
-          '  - result.options.user_scope must contain the assigned user ids',
+          '  - result.options.user_scope must contain the assigned numeric TenantUser.ID values',
+          '  - PermitUserScope.id must be numeric TenantUser.ID',
+          '  - Do not copy hash arcubaseTenantUserId into PermitUserScope.id',
+          '  - If result.enabled is false, enable the rule first and retry assign-users',
         ]
       : []),
     ...(docHints.length > 0
@@ -335,7 +338,46 @@ async function validateFileFieldPayloads(
   }
 }
 
-function throwBodyValidationFailure(message: string, requestType: string, path: string, scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>) {
+function isAssignUsersCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users'
+}
+
+function buildAssignUsersValidationDetails(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  requestType: string,
+  path: string,
+  message: string,
+): CLIErrorDetails {
+  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' },
+    ],
+    docHints: getDocHints(requestType),
+    shapeHint: {
+      update: ['user_scope'],
+      options: {
+        user_scope: [{ type: 'member', id: 123 }],
+      },
+    },
+    commonMistakes: [
+      'do not use user_scope at top level',
+      'do not use users or allowedUsers',
+      'do not use hash tenant user id as id',
+      'id must be numeric TenantUser.ID',
+    ],
+  }
+}
+
+function throwBodyValidationFailure(message: string, requestType: string, path: string, scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): never {
+  if (isAssignUsersCommand(scope, command)) {
+    throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildAssignUsersValidationDetails(scope, command, requestType, path, message))
+  }
   throw new CLIError('BODY_VALIDATION_FAILED', message, 2, {
     operation: `${scope}.${command.module}.${command.functionName}`,
     requestType,
@@ -382,10 +424,10 @@ function validateActionSpecificRawBody(
     return
   }
 
-  if (scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users') {
-    if ('users' in body || 'allowedUsers' in body) {
+  if (isAssignUsersCommand(scope, command)) {
+    if ('users' in body || 'allowedUsers' in body || 'user_scope' in body) {
       throwBodyValidationFailure(
-        'access-rule assign-users does not accept users or allowedUsers; use body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}',
+        '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,
@@ -411,13 +453,13 @@ function validateActionSpecificBody(
     requireUpdateContains(scope, command, body, 'options')
   }
 
-  if (scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users') {
+  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 does not accept users or allowedUsers; use body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}',
+        '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,
@@ -442,6 +484,36 @@ function validateActionSpecificBody(
         command,
       )
     }
+    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,
+        )
+      }
+      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 (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,
+        )
+      }
+    }
   }
 
   if (command.commandPath[0] === 'row' && command.commandPath[1] === 'selection-action') {
@@ -575,9 +647,25 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
     if (schema) {
       const parsedBody = schema.safeParse(body)
       if (!parsedBody.success) {
+        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',
-          parsedBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '),
+          message,
           2,
           {
             operation: `${scope}.${command.module}.${command.functionName}`,

package/src/tests/execute_validation.test.ts

@@ -22,6 +22,31 @@ function tempJSONFile(payload: unknown): string {
   return filePath
 }
 
+function assertAssignUsersGuidance(error: unknown, messagePattern?: RegExp): boolean {
+  assert.ok(error instanceof CLIError)
+  assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+  if (messagePattern) {
+    assert.match(error.message, messagePattern)
+  }
+  assert.equal(error.details?.requestType, 'AppIngressUpdateReqVO')
+  assert.deepEqual(error.details?.shapeHint, {
+    update: ['user_scope'],
+    options: {
+      user_scope: [{ type: 'member', id: 123 }],
+    },
+  })
+  assert.deepEqual(error.details?.commonMistakes, [
+    'do not use user_scope at top level',
+    'do not use users or allowedUsers',
+    'do not use hash tenant user id as id',
+    'id must be numeric TenantUser.ID',
+  ])
+  assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'AppIngressUpdateReqVO' && item.file === '/opt/arcubase-sdk/types/ingress.ts'))
+  assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'EntityIngressOptions' && item.file === '/opt/arcubase-sdk/types/ingress.ts'))
+  assert.ok(error.details?.tsHints?.some((item) => item.symbol === 'PermitUserScope' && item.file === '/opt/arcubase-sdk/types/common.ts'))
+  return true
+}
+
 function validEntitySavePayload(overrides: Record<string, unknown> = {}) {
   return {
     id: 2188889845,
@@ -501,13 +526,7 @@ test('access-rule assign-users rejects users shortcut', async () => {
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
-  }, (error: unknown) => {
-    assert.ok(error instanceof CLIError)
-    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
-    assert.match(error.message, /options.user_scope/)
-    assert.equal(error.details?.requestType, 'AppIngressUpdateReqVO')
-    return true
-  })
+  }, (error: unknown) => assertAssignUsersGuidance(error, /options.user_scope/))
 })
 
 test('access-rule assign-users requires update user_scope and non-empty user_scope', async () => {
@@ -518,22 +537,61 @@ test('access-rule assign-users requires update user_scope and non-empty user_sco
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
-  }, (error: unknown) => {
-    assert.ok(error instanceof CLIError)
-    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
-    assert.match(error.message, /non-empty/)
-    return true
-  })
+  }, (error: unknown) => assertAssignUsersGuidance(error, /non-empty/))
+})
+
+test('access-rule assign-users rejects allowedUsers shortcut', async () => {
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"allowedUsers":["tu_1"]}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => assertAssignUsersGuidance(error, /options.user_scope/))
+})
+
+test('access-rule assign-users rejects top-level user_scope', async () => {
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"user_scope":[{"type":"member","id":123}]}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => assertAssignUsersGuidance(error, /options.user_scope/))
+})
+
+test('access-rule assign-users rejects non-member scope type', async () => {
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => assertAssignUsersGuidance(error, /type.*member/))
+})
+
+test('access-rule assign-users rejects hash tenant user id', async () => {
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":"zW96OnE0kyJa3B2"}]}}'],
+      env as any,
+      async () => new Response('{}', { status: 200 }),
+    )
+  }, (error: unknown) => assertAssignUsersGuidance(error, /numeric TenantUser.ID/))
 })
 
 test('access-rule assign-users accepts canonical user_scope body', async () => {
   const out = await executeCLI(
     'admin',
-    ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}'],
+    ['access-rule', 'assign-users', '--app-id', 'app_1', '--table-id', 'table_1', '--rule-id', 'rule_1', '--body-json', '{"update":["user_scope"],"options":{"user_scope":[{"type":"member","id":123}]}}'],
     env as any,
     async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }),
   )
   assert.equal(out.kind, 'result')
   assert.deepEqual(out.data.update, ['user_scope'])
-  assert.deepEqual(out.data.options.user_scope, [{ type: 'user', id: 123 }])
+  assert.deepEqual(out.data.options.user_scope, [{ type: 'member', id: 123 }])
 })

package/src/tests/help.test.ts

@@ -76,5 +76,8 @@ test('admin access-rule help gives update whitelist and assign-users body-json e
   const assign = await executeCLI('admin', ['access-rule', 'assign-users', '--help'], undefined, async () => new Response('{}'))
   assert.equal(assign.kind, 'help')
   assert.match(assign.text, /"update":\["user_scope"\]/)
-  assert.match(assign.text, /"options":\{"user_scope":\[/)
+  assert.match(assign.text, /\{"update":\["user_scope"\],"options":\{"user_scope":\[\{"type":"member","id":123\}\]\}\}/)
+  assert.doesNotMatch(assign.text, /"type":"user"/)
+  assert.doesNotMatch(assign.text, /"users"/)
+  assert.doesNotMatch(assign.text, /"allowedUsers"/)
 })