@carthooks/arcubase-cli 0.1.19 → 0.1.20

package/dist/runtime/help_examples.js

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

package/package.json

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

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

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

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

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

package/sdk-dist/docs/runtime-reference/help-examples/user/row/bulk-update.json

@@ -0,0 +1,23 @@
+{
+  "scope": "user",
+  "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"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/user/row/selection-action.json

@@ -0,0 +1,25 @@
+{
+  "scope": "user",
+  "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/sdk-dist/generated/help_examples.generated.ts

@@ -0,0 +1,289 @@
+// Generated by scripts/generate-help-examples.mjs. Do not edit by hand.
+
+export type GeneratedHelpExample = {
+  title: string
+  body?: unknown
+  notes?: readonly string[]
+}
+
+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"
+        ]
+      }
+    ]
+  }
+} as const satisfies Record<string, { command: readonly string[]; examples: readonly GeneratedHelpExample[] }>