@carthooks/arcubase-cli 0.1.19 → 0.1.20

package/bundle/arcubase-admin.mjs

@@ -17416,6 +17416,334 @@ 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.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 +17781,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 +17817,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 +17829,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 +17928,7 @@ function coerceScalar(value, typeText) {
   }
   return value;
 }
-function getFixedValue(value) {
+function getFixedValue2(value) {
   if (!("fixedValue" in value)) {
     return void 0;
   }
@@ -17586,7 +17938,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 +17952,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 +18004,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 +18020,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 [];
@@ -18324,6 +18676,31 @@ function validateAccessRuleUserScope(scope, command, requestType, userScope, env
     }
   }
 }
+function normalizeNumericAccessRuleUserScopeIDs(scope, command, body) {
+  if (!isAccessRuleCommand(scope, command) || !isRecord3(body) || !isRecord3(body.options) || !Array.isArray(body.options.user_scope)) {
+    return body;
+  }
+  let changed = false;
+  const userScope = body.options.user_scope.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 };
+  });
+  if (!changed) return body;
+  return {
+    ...body,
+    options: {
+      ...body.options,
+      user_scope: userScope
+    }
+  };
+}
 function requireUpdateContains(scope, command, body, field, env) {
   if (!(field in body)) return;
   const update = stringArray(body.update);
@@ -19124,16 +19501,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 +19571,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);