@carthooks/arcubase-cli 0.1.19 → 0.1.20

package/dist/generated/help_examples.generated.d.ts

@@ -0,0 +1,205 @@
+export type GeneratedHelpExample = {
+    title: string;
+    body?: unknown;
+    notes?: readonly string[];
+};
+export declare const helpExamplesIndex: {
+    readonly "admin.access-rule.assign-users": {
+        readonly command: readonly ["access-rule", "assign-users"];
+        readonly examples: readonly [{
+            readonly title: "replace user_scope with user, department, and actor scopes";
+            readonly body: {
+                readonly update: readonly ["user_scope"];
+                readonly options: {
+                    readonly user_scope: readonly [{
+                        readonly type: "user";
+                        readonly id: 2188889901;
+                    }, {
+                        readonly type: "department";
+                        readonly id: 2188881201;
+                    }, {
+                        readonly type: "actor";
+                        readonly id: 2188883301;
+                    }];
+                };
+            };
+            readonly notes: readonly ["id must be numeric arcubaseUserId, department ID, or actor ID", "assign-users updates user_scope only and preserves the existing policy"];
+        }];
+    };
+    readonly "admin.access-rule.create": {
+        readonly command: readonly ["access-rule", "create"];
+        readonly examples: readonly [{
+            readonly title: "full access for a specific arcubaseUserId";
+            readonly body: {
+                readonly name: "Admin full access";
+                readonly enabled: true;
+                readonly type: "form";
+                readonly options: {
+                    readonly user_scope: readonly [{
+                        readonly type: "user";
+                        readonly id: 2188889977;
+                    }];
+                    readonly policy: {
+                        readonly key: "custom";
+                        readonly actions: readonly ["view", "add", "edit", "delete"];
+                        readonly all_fields_read: true;
+                        readonly all_fields_write: true;
+                    };
+                    readonly list_options: {};
+                };
+            };
+        }, {
+            readonly title: "department can view/add/edit only rows created by themselves";
+            readonly body: {
+                readonly name: "Sales own rows";
+                readonly enabled: true;
+                readonly type: "form";
+                readonly options: {
+                    readonly user_scope: readonly [{
+                        readonly type: "department";
+                        readonly id: 2188881201;
+                    }];
+                    readonly policy: {
+                        readonly key: "custom";
+                        readonly actions: readonly ["view", "add", "edit"];
+                        readonly all_fields_read: true;
+                        readonly all_fields_write: true;
+                        readonly condition: {
+                            readonly mode: "and";
+                            readonly conditions: readonly [{
+                                readonly column: "creator";
+                                readonly operator: "$eq";
+                                readonly value: "[[current_user]]";
+                                readonly value_from: 0;
+                                readonly value_relation: "";
+                            }];
+                        };
+                    };
+                    readonly list_options: {};
+                };
+            };
+            readonly notes: readonly ["department scope includes child departments", "row-owner isolation uses [[current_user]] on creator"];
+        }, {
+            readonly title: "role actor can view rows matching a complex AND/OR condition";
+            readonly body: {
+                readonly name: "Sales manager review queue";
+                readonly enabled: true;
+                readonly type: "form";
+                readonly options: {
+                    readonly user_scope: readonly [{
+                        readonly type: "actor";
+                        readonly id: 2188883301;
+                    }];
+                    readonly policy: {
+                        readonly key: "custom";
+                        readonly actions: readonly ["view", "edit"];
+                        readonly all_fields_read: true;
+                        readonly all_fields_write: true;
+                        readonly condition: {
+                            readonly mode: "and";
+                            readonly conditions: readonly [{
+                                readonly column: ":1004";
+                                readonly operator: "$eq";
+                                readonly value: "pending";
+                                readonly value_from: 0;
+                                readonly value_relation: "";
+                            }, {
+                                readonly column: "";
+                                readonly operator: "";
+                                readonly value: null;
+                                readonly value_from: 0;
+                                readonly value_relation: "";
+                                readonly subset: {
+                                    readonly mode: "or";
+                                    readonly conditions: readonly [{
+                                        readonly column: "creator";
+                                        readonly operator: "$eq";
+                                        readonly value: "[[current_user]]";
+                                        readonly value_from: 0;
+                                        readonly value_relation: "";
+                                    }, {
+                                        readonly column: ":1005";
+                                        readonly operator: "$eq";
+                                        readonly value: "high";
+                                        readonly value_from: 0;
+                                        readonly value_relation: "";
+                                    }];
+                                };
+                            }];
+                        };
+                    };
+                    readonly list_options: {};
+                };
+            };
+            readonly notes: readonly ["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"];
+        }];
+    };
+    readonly "user.row.bulk-update": {
+        readonly command: readonly ["row", "bulk-update"];
+        readonly examples: readonly [{
+            readonly title: "bulk update explicit row ids";
+            readonly body: {
+                readonly selection: {
+                    readonly type: "ids";
+                    readonly ids: readonly [2188890411, 2188890412];
+                    readonly length: 2;
+                };
+                readonly fields: readonly [{
+                    readonly id: 1003;
+                    readonly action: {
+                        readonly type: "set";
+                        readonly value: 2;
+                    };
+                }];
+            };
+        }, {
+            readonly title: "bulk update rows selected by a search condition";
+            readonly body: {
+                readonly selection: {
+                    readonly type: "condition";
+                    readonly condition: {
+                        readonly selectAll: true;
+                        readonly q: "SO-1001";
+                    };
+                    readonly length: 0;
+                };
+                readonly fields: readonly [{
+                    readonly id: 1003;
+                    readonly action: {
+                        readonly type: "set";
+                        readonly value: 2;
+                    };
+                }];
+            };
+            readonly notes: readonly ["condition selection uses row-query style keys such as q, tab, and filter_:1002"];
+        }];
+    };
+    readonly "user.row.selection-action": {
+        readonly command: readonly ["row", "selection-action"];
+        readonly examples: readonly [{
+            readonly title: "run a custom action against explicit row ids";
+            readonly body: {
+                readonly selection: {
+                    readonly type: "ids";
+                    readonly ids: readonly [2188890411];
+                    readonly length: 1;
+                };
+            };
+            readonly notes: readonly ["pass the backend action code with --action", "for query action, use ids or all selection instead of condition selection"];
+        }, {
+            readonly title: "run a custom action against a filtered selection";
+            readonly body: {
+                readonly selection: {
+                    readonly type: "condition";
+                    readonly condition: {
+                        readonly selectAll: true;
+                        readonly q: "SO-1001";
+                    };
+                    readonly length: 0;
+                };
+            };
+            readonly notes: readonly ["condition selection uses row-query style keys such as q, tab, and filter_:1002"];
+        }];
+    };
+};
+//# sourceMappingURL=help_examples.generated.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"help_examples.generated.d.ts","sourceRoot":"","sources":["../../src/generated/help_examples.generated.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwRgF,CAAA"}

package/dist/generated/help_examples.generated.js

@@ -0,0 +1,282 @@
+// Generated by scripts/generate-help-examples.mjs. Do not edit by hand.
+export const 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"
+                ]
+            }
+        ]
+    }
+};

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

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAyF,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAOhJ,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;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAc1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,MAAM,CAoB7G;AAOD,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAMlD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,MAAM,CA6HpI;AA8vDD,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,CA8MrI"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAyF,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAQhJ,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;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAc1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,MAAM,CAoB7G;AA8BD,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAUlD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,MAAM,CA8HpI;AA8xDD,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,CA+NrI"}

package/dist/runtime/execute.js

@@ -10,6 +10,7 @@ import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupp
 import { resolveArcubaseSDKPath } from './paths.js';
 import { compileCSVImportMapping, compileExcelImportMapping } from './entity_import_mapping.js';
 import { uploadLocalFileWithToken } from './local_upload.js';
+import { renderCommandHelpExamples } from './help_examples.js';
 export function renderRootHelp(scope) {
     const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase';
     const items = listModules(scope).map((item) => `  - ${item}`);
@@ -50,9 +51,29 @@ function buildUnknownCommandDetails(scope, moduleName, commandName) {
     const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName}${item.commandName ? ` ${item.commandName}` : ''}`);
     return suggestions.length > 0 ? { suggestions } : undefined;
 }
+function throwHelpExamplesRequiresCommand(scope, moduleName) {
+    const binary = binaryForScope(scope);
+    const suggestions = scope === 'admin'
+        ? [
+            `${binary} access-rule create --help-examples`,
+            `${binary} access-rule assign-users --help-examples`,
+        ]
+        : [
+            `${binary} row bulk-update --help-examples`,
+            `${binary} row selection-action --help-examples`,
+        ];
+    throw new CLIError('HELP_EXAMPLES_REQUIRES_COMMAND', '--help-examples must follow a final command', 2, {
+        operation: moduleName ? `${binary} ${moduleName} --help-examples` : `${binary} --help-examples`,
+        hint: `retry with a final command, for example: ${suggestions[0]}`,
+        suggestions,
+    });
+}
 function sdkPath(file, env = process.env) {
     return resolveArcubaseSDKPath(file, env);
 }
+function binaryForScope(scope) {
+    return scope === 'admin' ? 'arcubase-admin' : 'arcubase';
+}
 export function renderCommandHelp(scope, moduleName, commandName, env = process.env) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
@@ -75,6 +96,7 @@ export function renderCommandHelp(scope, moduleName, commandName, env = process.
         command.requestType ? `body: ${bodyTypeText} via --body-json <json-string> | --body-file <file>.json` : 'body: none',
         queryFlags.length ? `query flags: ${queryFlags.join(', ')}, --query-file` : 'query flags: --query-file',
         pathFlags.length ? `path flags: ${pathFlags.join(', ')}` : 'path flags: none',
+        `copyable examples: ${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${command.commandPath.join(' ')} --help-examples`,
         ...(isTableCreate
             ? [
                 'body-json example:',
@@ -229,7 +251,7 @@ function buildScalarQuery(command, flags) {
     return Object.keys(out).length > 0 ? out : undefined;
 }
 function validateKnownFlags(command, flags, env = process.env) {
-    const allowed = new Set(['help', 'body-file', 'body-json', 'query-file']);
+    const allowed = new Set(['help', 'help-examples', 'body-file', 'body-json', 'query-file']);
     for (const mapping of command.pathParams) {
         if (!getFixedValue(mapping)) {
             allowed.add(mapping.flag);
@@ -914,6 +936,32 @@ function validateAccessRuleUserScope(scope, command, requestType, userScope, env
         }
     }
 }
+function normalizeNumericAccessRuleUserScopeIDs(scope, command, body) {
+    if (!isAccessRuleCommand(scope, command) || !isRecord(body) || !isRecord(body.options) || !Array.isArray(body.options.user_scope)) {
+        return body;
+    }
+    let changed = false;
+    const userScope = body.options.user_scope.map((item) => {
+        if (!isRecord(item) || typeof item.id !== 'string' || !/^\d+$/.test(item.id)) {
+            return item;
+        }
+        const id = Number(item.id);
+        if (!Number.isFinite(id) || !Number.isInteger(id)) {
+            return item;
+        }
+        changed = true;
+        return { ...item, id };
+    });
+    if (!changed)
+        return body;
+    return {
+        ...body,
+        options: {
+            ...body.options,
+            user_scope: userScope,
+        },
+    };
+}
 function requireUpdateContains(scope, command, body, field, env) {
     if (!(field in body))
         return;
@@ -1639,16 +1687,32 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     const parsed = parseCLIArgs(argv);
     const envInput = env ?? process.env;
     if (parsed.commandTokens.length === 0) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope);
+        }
         return { kind: 'help', text: renderRootHelp(scope) };
     }
     const [moduleName, commandName] = parsed.commandTokens;
     if (!moduleName) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope);
+        }
         return { kind: 'help', text: renderRootHelp(scope) };
     }
     const singleTokenCommand = !commandName ? findCommand(scope, moduleName) : null;
     if (!commandName && !singleTokenCommand) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope, moduleName);
+        }
         return { kind: 'help', text: renderModuleHelp(scope, moduleName, envInput) };
     }
+    if (hasFlag(parsed.flags, 'help-examples')) {
+        const command = commandName ? findCommand(scope, moduleName, commandName) : singleTokenCommand;
+        if (!command) {
+            throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName}${commandName ? ` ${commandName}` : ''}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName ?? ''));
+        }
+        return { kind: 'help', text: renderCommandHelpExamples(scope, command) };
+    }
     if (hasFlag(parsed.flags, 'help')) {
         return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName, envInput) };
     }
@@ -1689,6 +1753,7 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
         if (body === undefined) {
             throw new CLIError('MISSING_BODY_FILE', `command requires --body-json or --body-file for ${command.requestType}; prefer --body-json to avoid file creation`, 2);
         }
+        body = normalizeNumericAccessRuleUserScopeIDs(scope, command, body);
         if (isTableCreateCommand(scope, command)) {
             requireTableCreateSchemaBody(scope, command, body, runtimeEnv);
             validateActionSpecificRawBody(scope, command, body, runtimeEnv);

package/dist/runtime/help_examples.d.ts

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

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

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