@carthooks/arcubase-cli 0.1.2 → 0.1.4

package/dist/tests/upload.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=upload.test.d.ts.map

package/dist/tests/upload.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.test.d.ts","sourceRoot":"","sources":["../../src/tests/upload.test.ts"],"names":[],"mappings":""}

package/dist/tests/upload.test.js

@@ -0,0 +1,107 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { executeCLI } from '../runtime/execute.js';
+const env = {
+    ARCUBASE_BASE_URL: 'https://arcubase.example.com',
+    ARCUBASE_TENANT_ID: 'tenant_1',
+    ARCUBASE_ACCESS_TOKEN: 'tok',
+    ARCUBASE_TRACE_ID: '',
+    ARCUBASE_SUBJECT_TYPE: '',
+    ARCUBASE_SUBJECT_ID: '',
+    ARCUBASE_TOKEN_EXPIRES_AT: '',
+};
+test('upload help works without runtime env', async () => {
+    const out = await executeCLI('user', ['upload', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /arcubase upload <local-file>/);
+    assert.match(out.text, /uploads\.md/);
+});
+test('upload returns file field value array for row payloads', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'arcubase-upload-'));
+    const sourceFile = path.join(tempDir, 'contract.pdf');
+    fs.writeFileSync(sourceFile, 'fake pdf bytes');
+    const calls = [];
+    const result = await executeCLI('user', ['upload', sourceFile], env, async (input, init) => {
+        const url = String(input);
+        calls.push({ url, method: init?.method });
+        if (url === 'https://arcubase.example.com/upload/token') {
+            return new Response(JSON.stringify({
+                data: {
+                    id: 123456,
+                    mode: 'aliyun-oss',
+                    token_data: {
+                        dir: 'upload/123456/',
+                        policy: 'policy',
+                        accessid: 'accessid',
+                        signature: 'signature',
+                        host: 'https://uploads.example.com',
+                    },
+                },
+            }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+        }
+        if (url === 'https://uploads.example.com') {
+            return new Response('', { status: 200 });
+        }
+        throw new Error(`unexpected fetch url: ${url}`);
+    });
+    assert.equal(result.kind, 'result');
+    assert.deepEqual(calls, [
+        { url: 'https://arcubase.example.com/upload/token', method: 'POST' },
+        { url: 'https://uploads.example.com', method: 'POST' },
+    ]);
+    assert.deepEqual(result.data, [
+        {
+            upload_id: 123456,
+            file: 'contract.pdf',
+            file_name: 'contract.pdf',
+            meta: {},
+        },
+    ]);
+});
+test('upload supports s3-post-policy tokens', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'arcubase-upload-s3-'));
+    const sourceFile = path.join(tempDir, 'contract.pdf');
+    fs.writeFileSync(sourceFile, 'fake pdf bytes');
+    const calls = [];
+    const result = await executeCLI('user', ['upload', sourceFile], env, async (input, init) => {
+        const url = String(input);
+        calls.push({ url, method: init?.method });
+        if (url === 'https://arcubase.example.com/upload/token') {
+            return new Response(JSON.stringify({
+                data: {
+                    id: 654321,
+                    mode: 's3-post-policy',
+                    token_data: {
+                        dir: 'upload/654321/',
+                        policy: 'policy',
+                        host: 'https://uploads.example.com/private-bucket',
+                        x_amz_algorithm: 'AWS4-HMAC-SHA256',
+                        x_amz_credential: 'test/20260504/us-east-1/s3/aws4_request',
+                        x_amz_date: '20260504T010203Z',
+                        x_amz_signature: 'abc123',
+                    },
+                },
+            }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+        }
+        if (url === 'https://uploads.example.com/private-bucket') {
+            return new Response('', { status: 200 });
+        }
+        throw new Error(`unexpected fetch url: ${url}`);
+    });
+    assert.equal(result.kind, 'result');
+    assert.deepEqual(calls, [
+        { url: 'https://arcubase.example.com/upload/token', method: 'POST' },
+        { url: 'https://uploads.example.com/private-bucket', method: 'POST' },
+    ]);
+    assert.deepEqual(result.data, [
+        {
+            upload_id: 654321,
+            file: 'contract.pdf',
+            file_name: 'contract.pdf',
+            meta: {},
+        },
+    ]);
+});

package/package.json

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

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

@@ -0,0 +1,187 @@
+# 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
+```
+
+Hard rule:
+
+- `arcubase-admin` stops at schema save
+- all row operations must switch to `arcubase`
+- do not use `arcubase-admin workflow insert-entity`
+- do not use `arcubase-admin workflow query-entity`
+
+## 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 the row contains a file or image field, read `uploads.md`
+3. 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
+- `uploads.md`
+  - upload one local file and reuse the returned field value in row payloads
+- `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