@carthooks/arcubase-cli 0.1.2 → 0.1.3

package/sdk-dist/docs/runtime-reference/README.md

@@ -0,0 +1,177 @@
+# Arcubase CLI Runtime Reference
+
+This documentation set is for using `arcubase-admin` and `arcubase` directly.
+
+Read it as a command cheatsheet:
+
+- which binary to use
+- which subcommand to run
+- which flags are required
+- what the body file should look like
+- what result shape to expect
+
+Do not start from raw HTTP methods or paths. Start from the CLI command.
+
+## Paths
+
+- Development source:
+  - `misc/packages/@carthooks/arcubase-cli/docs/runtime-reference/`
+- Runtime location:
+  - `/opt/arcubase-sdk/docs/runtime-reference/`
+- Published path:
+  - `sdk-dist/docs/runtime-reference/`
+
+## Which binary to use
+
+Use `arcubase-admin` for:
+
+- app creation
+- entity shell creation
+- entity schema save
+- entity tag admin actions
+
+Common commands:
+
+```bash
+arcubase-admin app create-app-by-tenants --body-file create-app.json
+arcubase-admin app create-entity --id <app_id> --body-file create-entity.json
+arcubase-admin entity admin-get-entity-info --app-id <app_id> --entity-id <entity_id>
+arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id> --body-file save-entity.json
+arcubase-admin entity-tags get-selection-tags --appId <app_id> --entityId <entity_id> --body-file get-tags.json
+```
+
+Use `arcubase` for:
+
+- row insert
+- row query
+- row update
+- row delete / restore
+- search
+- selection actions
+- bulk update
+- batch operator
+
+Common commands:
+
+```bash
+arcubase workflow insert-entity --app-id <app_id> --entity-id <entity_id> --body-file insert.json
+arcubase workflow query-entity --app-id <app_id> --entity-id <entity_id> --body-file query.json
+arcubase workflow update-entity-row --app-id <app_id> --entity-id <entity_id> --row-id <row_id> --body-file update.json
+arcubase workflow delete-entity-row --app-id <app_id> --entity-id <entity_id> --body-file delete.json
+arcubase workflow restore-entity-row --app-id <app_id> --entity-id <entity_id> --body-file restore.json
+arcubase workflow query-entity-selection --app-id <app_id> --entity-id <entity_id> --action archive --body-file selection.json
+arcubase entity update-entity-bulk --app-id <app_id> --entity-id <entity_id> --body-file bulk-update.json
+arcubase entity invoke-entity-batch-operator --app-id <app_id> --entity-id <entity_id> --body-file invoke-batch-operator.json
+```
+
+## Required file inputs
+
+Most write commands use:
+
+- `--body-file <file>.json`
+
+Some query commands also use:
+
+- `--query-file <file>.json`
+
+Use `--query-file` when the command needs query-string parameters that do not belong in the JSON body.
+
+Current important example:
+
+```bash
+arcubase workflow query-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --query-file archived-query.json \
+  --body-file archived-body.json
+```
+
+## Runtime env
+
+The CLIs accept either generic env keys:
+
+- `ARCUBASE_BASE_URL`
+- `ARCUBASE_TENANT_ID`
+- `ARCUBASE_ACCESS_TOKEN`
+- `ARCUBASE_HOST`
+
+or scoped env keys:
+
+- admin:
+  - `ARCUBASE_ADMIN_BASE_URL`
+  - `ARCUBASE_ADMIN_TENANT_ID`
+  - `ARCUBASE_ADMIN_ACCESS_TOKEN`
+  - `ARCUBASE_ADMIN_HOST`
+- user:
+  - `ARCUBASE_USER_BASE_URL`
+  - `ARCUBASE_USER_TENANT_ID`
+  - `ARCUBASE_USER_ACCESS_TOKEN`
+  - `ARCUBASE_USER_HOST`
+
+Help should work without runtime env:
+
+```bash
+arcubase-admin --help
+arcubase-admin <module> --help
+arcubase-admin <module> <command> --help
+arcubase --help
+arcubase <module> --help
+arcubase <module> <command> --help
+```
+
+Command help is also the discovery entrypoint for this doc set.
+
+When a command is tied to a common task, `--help` should print:
+
+- the normalized external endpoint
+- required path and scalar flags
+- whether `--query-file` is supported
+- direct links to the most relevant runtime reference pages
+- direct links to business-shaped examples when available
+
+## Reading order by task
+
+If you need to create a table:
+
+1. read `table-lifecycle.md`
+2. read `entity-schema.md`
+3. read `entity-schema/README.md`
+4. open the exact field-type page you need
+
+If you need row CRUD:
+
+1. read `row-crud.md`
+2. if a field is complex, open the exact field-type page
+
+If you need a business-shaped template:
+
+1. read `examples/README.md`
+2. pick the closest domain directory
+3. copy and adapt the example schema and payload files
+
+If you need search, selection, tags, bulk update, or batch operator:
+
+1. read `search-and-bulk-actions.md`
+2. use `row-crud.md` only for row result shapes
+
+## Covered now
+
+- `table-lifecycle.md`
+  - app shell, entity shell, schema save, readiness probe
+- `entity-schema.md`
+  - full save-ready schema rules
+- `entity-schema/README.md`
+  - field index and how to use field docs
+- `entity-schema/*.md`
+  - one field cheatsheet per file
+- `row-crud.md`
+  - insert, query, update, delete, restore
+- `search-and-bulk-actions.md`
+  - search, selection, tags, bulk update, batch operator
+- `examples/`
+  - business-shaped schema and payload templates
+
+## Reserved expansion
+
+- `workflow/README.md`
+  - reserved for future workflow-specific CLI docs

package/sdk-dist/docs/runtime-reference/entity-schema/README.md

@@ -0,0 +1,120 @@
+# Entity Schema Field Reference
+
+Use this directory while building `save-entity.json` for:
+
+```bash
+arcubase-admin entity admin-save-entity \
+  --app-id <app_id> \
+  --entity-id <entity_id> \
+  --body-file save-entity.json
+```
+
+## How to use these field pages
+
+1. fetch the current shell with:
+
+```bash
+arcubase-admin entity admin-get-entity-info \
+  --app-id <app_id> \
+  --entity-id <entity_id>
+```
+
+2. build the top-level save payload with:
+
+- `entity-schema.md`
+
+3. open the exact field page you need
+
+4. copy the field-specific `options` shape into the full base `FieldVO`
+
+These field pages do **not** replace the full base field shape. They only explain the field-specific part.
+
+## Global save rules
+
+- `fields` must be `FieldVO[]`
+- field ids should start from `1001`
+- field ids must be non-zero
+- `field_id_seq > max(field.id)`
+- top-level `layout` may only reference top-level field ids
+- non-`subform` fields should use `children: null`
+- saved `subform` payload keeps `children` only
+- `lookup/rollup.local_linkto_field_id` must point to a `linkto` field
+- formula references must point to existing field ids
+- `schema_version` should come from the current shell
+- if the response contains a top-level `error`, the save failed even when HTTP is `200`
+
+## Row CRUD reminder
+
+These field pages are for schema save.
+
+If you need row payloads, read:
+
+- `../row-crud.md`
+
+Current important row rules:
+
+- row delete / restore uses:
+  - `arcubase workflow delete-entity-row`
+  - `arcubase workflow restore-entity-row`
+  - `selection.type = "ids"`
+- `subform` row values use:
+  - `[{ "id": 0, "fields": { ... } }]`
+
+## Field index
+
+### Basic types
+
+- [`text`](./text.md)
+- [`textarea`](./textarea.md)
+- [`number`](./number.md)
+- [`datetime`](./datetime.md)
+- [`boolean`](./boolean.md)
+
+### Enum and status
+
+- [`radio`](./radio.md)
+- [`checkbox`](./checkbox.md)
+- [`select`](./select.md)
+- [`selects`](./selects.md)
+- [`status`](./status.md)
+
+### Structure and display
+
+- [`divider`](./divider.md)
+- [`subform`](./subform.md)
+- [`button`](./button.md)
+
+### File and media
+
+- [`image`](./image.md)
+- [`file`](./file.md)
+- [`signature`](./signature.md)
+
+### Geography and external data
+
+- [`address`](./address.md)
+- [`datasets`](./datasets.md)
+- [`location`](./location.md)
+
+### People and organization
+
+- [`member`](./member.md)
+- [`members`](./members.md)
+- [`department`](./department.md)
+- [`departments`](./departments.md)
+
+### Relations and computation
+
+- [`linkto`](./linkto.md)
+- [`relation`](./relation.md)
+- [`relationfield`](./relationfield.md)
+- [`query`](./query.md)
+- [`lookup`](./lookup.md)
+- [`rollup`](./rollup.md)
+- [`formula`](./formula.md)
+
+### Other advanced types
+
+- [`serialnumber`](./serialnumber.md)
+- [`workflow_status`](./workflow_status.md)
+- [`tags`](./tags.md)

package/sdk-dist/docs/runtime-reference/entity-schema/address.md

@@ -0,0 +1,34 @@
+# address
+
+## Purpose
+
+Hierarchical address selection field.
+
+## Frontend capability flags
+
+- `group: advanced`
+- `useFormula: true`
+- `useRelation: true`
+
+## Minimal shape
+
+```json
+{
+  "type": "address",
+  "options": {
+    "dataset_id": 1,
+    "maxDepth": 3
+  }
+}
+```
+
+## Common options
+
+- `dataset_id`
+- `maxDepth`
+
+## Constraints
+
+- `dataset_id` is required
+- common `maxDepth` values are `1` to `4`
+- if `maxDepth` is omitted, prefer `3`

package/sdk-dist/docs/runtime-reference/entity-schema/boolean.md

@@ -0,0 +1,37 @@
+# boolean
+
+## Purpose
+
+Boolean field.
+
+
+
+## Frontend capability flags
+
+- `group: normal`
+- `switchgroup: enum`
+- `useFormula: true`
+- `useRelation: true`
+- `inlineEdtiable: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "boolean",
+  "options": {}
+}
+```
+
+## Available options
+
+- There is currently no stable complex `options` contract
+
+## Constraints
+
+- In the current direct-write pathprefer empty `options`
+- only use generic field flags for:
+  - `required`
+  - `visible`
+  - `editable`

package/sdk-dist/docs/runtime-reference/entity-schema/button.md

@@ -0,0 +1,47 @@
+# button
+
+## Purpose
+
+Button field.
+
+## Frontend capability flags
+
+- `group: advanced`
+- `custom_permissions: true`
+- `notImportAble: true`
+- `notExportAble: true`
+- `events: ['click']`
+
+## Minimal shape
+
+```json
+{
+  "type": "button",
+  "options": {
+    "label": "Button",
+    "hideInList": false,
+    "perm": {
+      "create": true,
+      "edit": true,
+      "list": true,
+      "view": true
+    }
+  }
+}
+```
+
+## Common options
+
+- `label`
+- `hideInList`
+- `perm.create`
+- `perm.edit`
+- `perm.list`
+- `perm.view`
+
+## Constraints
+
+- `label` is required
+- `perm` should explicitly include all four boolean flags
+- `hideInList` should stay consistent with `perm.list`
+- Button behavior is bound through top-level `options.FrontendEvents`, not written directly in the field body

package/sdk-dist/docs/runtime-reference/entity-schema/checkbox.md

@@ -0,0 +1,61 @@
+# checkbox
+
+## Purpose
+
+Multi-select enum field.
+
+## Frontend capability flags
+
+- `group: normal`
+- `useFormula: true`
+- `useRelation: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "checkbox",
+  "options": {
+    "horizontal": false,
+    "options": {
+      "mode": "custom",
+      "colorful": false,
+      "items": [
+        { "key": 1, "value": "Option 1" }
+      ]
+    }
+  }
+}
+```
+
+## Common options
+
+- `horizontal`
+- `hideInList`
+- `options.items`
+- `options.mode`
+- `options.colorful`
+- `options.has_other`
+- `options.other_label`
+
+## Constraints
+
+- `options.items` at least one item
+- when `options.has_other = true`, also provide `options.other_label`
+- row values should be an array of selected option values
+
+## Save-ready reminder
+
+For `arcubase-admin entity admin-save-entity`, keep the full base `FieldVO`.
+
+The saved field still needs:
+
+- `id`
+- `label`
+- `required`
+- `editable`
+- `visible`
+- `number_decimal`
+- `key`
+- `children: null`

package/sdk-dist/docs/runtime-reference/entity-schema/datasets.md

@@ -0,0 +1,35 @@
+# datasets
+
+## Purpose
+
+Dataset picker field.
+
+## Frontend capability flags
+
+- `group: advanced`
+- `useFormula: true`
+- `useRelation: true`
+- `inlineEdtiable: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "datasets",
+  "options": {
+    "dataset_id": 0,
+    "maxDepth": 0
+  }
+}
+```
+
+## Common options
+
+- `dataset_id`
+- `maxDepth`
+
+## Constraints
+
+- `dataset_id` is required
+- if `maxDepth` is omitted, prefer `3`

package/sdk-dist/docs/runtime-reference/entity-schema/datetime.md

@@ -0,0 +1,40 @@
+# datetime
+
+## Purpose
+
+Date-time field.
+
+
+
+## Frontend capability flags
+
+- `group: normal`
+- `useFormula: true`
+- `useRelation: true`
+- `inlineEdtiable: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "datetime",
+  "options": {
+    "placeholder": "",
+    "type": "datetime"
+  }
+}
+```
+
+## Available options
+
+- `placeholder`
+- `type`
+
+## Constraints
+
+- in the current direct-write path, valid `type` values are:
+  - `date`
+  - `datetime`
+- if omitted, prefer `date`
+- if a default is written into `value`, it should match a value accepted by the frontend date picker

package/sdk-dist/docs/runtime-reference/entity-schema/department.md

@@ -0,0 +1,33 @@
+# department
+
+## Purpose
+
+Single-department field.
+
+## Frontend capability flags
+
+- `group: normal`
+- `useFormula: true`
+- `useRelation: true`
+- `operator: department`
+- `notImportAble: true`
+- `notExportAble: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "department",
+  "options": {}
+}
+```
+
+## Common options
+
+- `placeholder`
+
+## Constraints
+
+- `department` is a single-value field
+- in the current direct-write path, `options` may contain only `placeholder`

package/sdk-dist/docs/runtime-reference/entity-schema/departments.md

@@ -0,0 +1,34 @@
+# departments
+
+## Purpose
+
+Multi-department field.
+
+## Frontend capability flags
+
+- `group: normal`
+- `useFormula: true`
+- `useRelation: true`
+- `notImportAble: true`
+- `notExportAble: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "departments",
+  "options": {
+    "placeholder": ""
+  }
+}
+```
+
+## Common options
+
+- `placeholder`
+
+## Constraints
+
+- `departments` is a multi-value field
+- in the current direct-write path, `options` may contain only `placeholder`

package/sdk-dist/docs/runtime-reference/entity-schema/divider.md

@@ -0,0 +1,39 @@
+# divider
+
+## Purpose
+
+Divider / visual grouping field.
+
+
+
+## Frontend capability flags
+
+- `group: normal`
+- `withoutFieldContainer: true`
+- `custom_permissions: true`
+- `hideInList: true`
+- `readonly: true`
+- `notImportAble: true`
+- `notExportAble: true`
+
+## Minimal shape
+
+```json
+{
+  "type": "divider",
+  "options": {
+    "color": "",
+    "style_id": ""
+  }
+}
+```
+
+## Available options
+
+- `color`
+- `style_id`
+
+## Constraints
+
+- In the current direct-write path, `options.style_id` and `options.color` should both be explicit
+- `divider` is a display-only field and does not carry business values

package/sdk-dist/docs/runtime-reference/entity-schema/file.md

@@ -0,0 +1,44 @@
+# file
+
+## Purpose
+
+File upload field.
+
+## Frontend capability flags
+
+- `group: advanced`
+- `switchgroup: file`
+- `notImportAble: true`
+- `notExportAble: true`
+- `events: ['change']`
+
+## Minimal shape
+
+```json
+{
+  "type": "file",
+  "options": {
+    "placeholder": "",
+    "count_range": false,
+    "count_min": 0,
+    "count_max": 9
+  }
+}
+```
+
+## Common options
+
+- `placeholder`
+- `count_range`
+- `count_min`
+- `count_max`
+- `hideInList`
+
+## Constraints
+
+- when `count_range=true`, it is recommended to provide both `count_min` and `count_max`
+- `required` is controlled by generic field flags, not inside `options`
+- when count limits are disabled in the current direct-write path, use:
+  - `count_range: false`
+  - `count_min: 0`
+  - `count_max: 9`