@carthooks/arcubase-cli 0.1.12 → 0.1.15

package/dist/tests/entity_save_schema.test.js

@@ -61,6 +61,44 @@ test('EntitySaveReqVO normalizes mechanical FieldVO defaults', () => {
     assert.equal(parsed.data.fields[0].transfers, null);
     assert.deepEqual(parsed.data.fields[0].depends, []);
 });
+test('EntitySaveReqVO rejects textarea size as string', () => {
+    assert.ok(schema);
+    const parsed = schema.safeParse({
+        name: '订单',
+        field_id_seq: 1003,
+        layout: [[1001], [1002]],
+        fields: [
+            buildMinimalField(1001),
+            {
+                ...buildMinimalField(1002),
+                label: '描述',
+                type: 'textarea',
+                key: 'description',
+                options: { placeholder: '', html: false, size: 'default', lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
+            },
+        ],
+    });
+    assert.equal(parsed.success, false);
+});
+test('EntitySaveReqVO accepts textarea size as number', () => {
+    assert.ok(schema);
+    const parsed = schema.safeParse({
+        name: '订单',
+        field_id_seq: 1003,
+        layout: [[1001], [1002]],
+        fields: [
+            buildMinimalField(1001),
+            {
+                ...buildMinimalField(1002),
+                label: '描述',
+                type: 'textarea',
+                key: 'description',
+                options: { placeholder: '', html: false, size: 6, lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
+            },
+        ],
+    });
+    assert.equal(parsed.success, true);
+});
 test('EntitySaveReqVO rejects fields as object', () => {
     assert.ok(schema);
     const parsed = schema.safeParse({

package/dist/tests/execute_validation.test.js

@@ -250,6 +250,37 @@ test('body json parse errors include command docs and type hints', async () => {
         return true;
     });
 });
+test('access-rule invalid json returns copyable create retry examples', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('admin', ['access-rule', 'create', '--app-id', 'app_1', '--table-id', 'table_1', '--body-json', '{"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":{}}'], env, async () => new Response('{}', { status: 200 }));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'INVALID_BODY_JSON');
+        assert.equal(error.details?.requestType, 'AppIngressCreateReqVO');
+        assert.match(error.message, /retryToolCalls/);
+        const toolCall = (error.details?.retryToolCalls ?? [])[0];
+        assert.ok(toolCall);
+        assert.equal(toolCall.command, 'access-rule create');
+        assert.deepEqual(toolCall.args.slice(0, 5), ['--app-id', '<app_id>', '--table-id', '<table_id>', '--body-json']);
+        const body = JSON.parse(toolCall.args[5]);
+        assert.deepEqual(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: {},
+            },
+        });
+        return true;
+    });
+});
 test('access-rule list executes against external root path', async () => {
     const out = await executeCLI('admin', ['access-rule', 'list', '--app-id', 'app_1', '--table-id', 'table_1'], env, async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }));
     assert.equal(out.kind, 'result');
@@ -306,7 +337,7 @@ test('table update-schema rejects per-user permission patches', async () => {
         layout: [[1001], [1002]],
         fields: [
             { id: 1001, label: 'Title', type: 'text', required: true, unique: false, editable: true, visible: true, show_label: true, scannable: false, default_value_mode: 0, description: '', value: null, number_decimal: 0, depends: [], key: 'title', code_index: false, options: { type: 'text', placeholder: '', lengthLimit: false, lengthMin: 0, lengthMax: 255 }, transfers: null, children: null },
-            { id: 1002, label: 'Description', type: 'textarea', required: false, unique: false, editable: true, visible: true, show_label: true, scannable: false, default_value_mode: 0, description: '', value: null, number_decimal: 0, depends: [], key: 'description', code_index: false, options: { placeholder: '', html: false, size: 'default', lengthLimit: false, lengthMin: 0, lengthMax: 2000 }, transfers: null, children: null, permission: { user: { read: false } } },
+            { id: 1002, label: 'Description', type: 'textarea', required: false, unique: false, editable: true, visible: true, show_label: true, scannable: false, default_value_mode: 0, description: '', value: null, number_decimal: 0, depends: [], key: 'description', code_index: false, options: { placeholder: '', html: false, size: 6, lengthLimit: false, lengthMin: 0, lengthMax: 2000 }, transfers: null, children: null, permission: { user: { read: false } } },
         ],
         options: { Buttons: [], CustomActions: [], FrontendEvents: [], TitleFormat: { Fields: [], Parts: [], Body: '' }, misc: {} },
         workflow_enabled: false,
@@ -396,6 +427,37 @@ test('row get resolves internal policy_id as query parameter', async () => {
     assert.equal(out.kind, 'result');
     assert.equal(calls[0], 'https://arcubase.example.com/api/entity/2188900691/2188900694/row/4000000046?policy_id=policy_hash_1');
 });
+test('row get returns machine-readable row value evidence', async () => {
+    const out = await executeCLI('user', ['row', 'get', '--app-id', '2188900691', '--table-id', '2188900694', '--row-id', '4000000046'], env, withRowPolicyResolver('2188900694', ['view'], async () => new Response(JSON.stringify({
+        data: {
+            record: {
+                id: 4000000046,
+                fields: { 1001: '复测投票' },
+            },
+            fieldPermits: {
+                all_fields_read: false,
+                fields: [
+                    { key: ':1001', read: true, write: true, report: false },
+                    { key: ':1002', read: false, write: false, report: false },
+                    { key: ':1003', read: true, write: true, report: false },
+                ],
+            },
+        },
+    }), { status: 200 })));
+    assert.deepEqual(out.rowValueEvidence, {
+        source: 'row get record.fields',
+        returnedFieldIds: ['1001'],
+        notReturnedFieldIds: ['1002', '1003'],
+        deniedReadFieldIds: ['1002'],
+        absentFieldMeaning: 'not returned to current user; no row-value evidence',
+        rules: [
+            'current row values come only from row query fields or row get record.fields',
+            'table schema fields[].value and default_value_mode are schema defaults, not returned row values',
+            'a field id absent from returned row fields has no row-value evidence',
+            'read visibility status is fieldPermits read:false; FIELD_PERMISSION_REQUIRED is only a write preflight error',
+        ],
+    });
+});
 test('row command rejects user-provided policy_id', async () => {
     const bodyFile = tempJSONFile({ fields: { 1001: '今天吃什么' }, policy_id: 'manual_policy' });
     await assert.rejects(async () => {
@@ -562,7 +624,7 @@ test('row query unknown limit flag gives body-json retry path', async () => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'UNKNOWN_FLAG');
         assert.equal(error.details?.requestType, 'EntityQueryReqVO');
-        assert.deepEqual(error.details?.shapeHint, { limit: 20, offset: 0, search: { text_search: 'SO-1001' } });
+        assert.deepEqual(error.details?.shapeHint, { limit: 20, offset: 0, search: { q: 'SO-1001' }, sorts: [{ column: ':1001', order: 'asc' }] });
         assert.ok(error.details?.suggestions?.some((item) => item.includes('--body-json')));
         return true;
     });

package/dist/tests/help.test.js

@@ -81,6 +81,8 @@ test('admin access-rule help gives update whitelist and assign-users body-json e
     assert.equal(create.kind, 'help');
     assert.match(create.text, /Access rule/);
     assert.match(create.text, /access-rule\.md/);
+    assert.match(create.text, /full access/);
+    assert.match(create.text, /"actions":\["view","add","edit","delete"\]/);
     assert.match(create.text, /"user_scope":\[\{"type":"user","id":2188889901\}\]/);
     assert.doesNotMatch(create.text, /"user_scope":\[\{"type":"member"/);
     const update = await executeCLI('admin', ['access-rule', 'update', '--help'], env, async () => new Response('{}'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carthooks/arcubase-cli",
-  "version": "0.1.12",
+  "version": "0.1.15",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,13 +31,13 @@
   },
   "dependencies": {
     "@carthooks/client-ts": "0.8.0",
-    "zod": "^3.25.76"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^20.19.0",
-    "esbuild": "^0.25.11",
-    "ts-morph": "^25.0.1",
-    "tsx": "^4.20.6",
-    "typescript": "^5.3.3"
+    "@types/node": "^25.9.2",
+    "esbuild": "^0.28.0",
+    "ts-morph": "^28.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
   }
 }

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

@@ -35,12 +35,16 @@ Common commands:
 
 ```bash
 arcubase-admin app create --body-file create-app.json | --body-json <json-string>
+arcubase-admin app create-from-bundle-url --url <bundle_url> [--name <app_name>]
+arcubase-admin app watch-import-task --task-id <task_id> --ttl-seconds 300
 arcubase-admin table create --app-id <app_id> --body-json <json-string> | --body-file table-create.json
 arcubase-admin table get --app-id <app_id> --table-id <table_id>
 arcubase-admin table update-schema --app-id <app_id> --table-id <table_id> --body-json <json-string> | --body-file table-schema.json
 arcubase-admin access-rule assign-users --app-id <app_id> --table-id <table_id> --rule-id <rule_id> --body-json <json-string> | --body-file assign-users.json
 ```
 
+`--ttl-seconds` is a local wait limit. It does not cancel the backend import task.
+
 Use `arcubase` for:
 
 - row insert

package/sdk-dist/docs/runtime-reference/access-rule.md

@@ -20,6 +20,14 @@ Use the numeric `tenantUserId` / `TenantUser.ID`.
 Do not use hash ids such as `arcubaseTenantUserId`.
 Use `user_scope[].type:"user"` for a tenant user. Do not use FieldVO field type `member` in access rules.
 
+## Body Input
+
+```bash
+--body-json '<json-string>' | --body-file access-rule.json
+```
+
+Prefer `--body-json` for short payloads. `--body-file` is available for large or fragile JSON payloads.
+
 ## Create Read/Write Rule With Hidden Field
 
 ```bash
@@ -29,6 +37,17 @@ arcubase-admin access-rule create \
   --body-json '{"name":"Sales read write","enabled":true,"type":"form","options":{"user_scope":[{"type":"user","id":2188889901}],"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":false,"all_fields_write":false,"fields":[{"key":":1001","read":true,"write":true,"report":false},{"key":":1002","read":false,"write":false,"report":false},{"key":":1003","read":true,"write":true,"report":false}]},"list_options":{}}}'
 ```
 
+## Create Admin Full Access Rule
+
+Use this for the operator's own admin entry before creating seed rows.
+
+```bash
+arcubase-admin access-rule create \
+  --app-id 2188893436 \
+  --table-id 2188893443 \
+  --body-json '{"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":{}}}'
+```
+
 Rules:
 
 - read permission = `actions:["view"]`

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

@@ -23,7 +23,7 @@ Multi-line text field.
   "options": {
     "placeholder": "",
     "html": false,
-    "size": "default",
+    "size": 6,
     "lengthLimit": false,
     "lengthMin": 0,
     "lengthMax": 2000
@@ -44,4 +44,4 @@ Multi-line text field.
 
 - `placeholder` matters only when `html=false`
 - when `lengthLimit=true`, it is recommended to provide both `lengthMin` and `lengthMax`
-- keep `size` within the values returned by the current editor; do not invent extra enum values
+- `size` is numeric and maps to editor rows; use `6` for the default two-row textarea

package/sdk-dist/docs/runtime-reference/examples/crm-01/lead.query.json

@@ -1 +1 @@
-{"limit":20,"offset":0,"search":{"text_search":"lead"},"sorts":[{"column":":1001","order":"asc"}]}
+{"limit":20,"offset":0,"search":{"q":"lead"},"sorts":[{"column":":1001","order":"asc"}]}

package/sdk-dist/docs/runtime-reference/examples/oms-01/sales-order.query.json

@@ -2,7 +2,7 @@
   "limit": 20,
   "offset": 0,
   "search": {
-    "text_search": "SO-1001"
+    "q": "SO-1001"
   },
   "sorts": [
     { "column": ":1003", "order": "desc" }

package/sdk-dist/docs/runtime-reference/examples/wms-01/inventory-snapshot.query.json

@@ -1 +1 @@
-{"limit":20,"offset":0,"search":{"text_search":"SKU-1001"},"sorts":[{"column":":1001","order":"desc"}]}
+{"limit":20,"offset":0,"search":{"q":"SKU-1001"},"sorts":[{"column":":1001","order":"desc"}]}

package/sdk-dist/docs/runtime-reference/row-crud.md

@@ -83,6 +83,12 @@ Typical row shape:
 }
 ```
 
+Returned values:
+
+- current row values are only in `fields`
+- fields absent from `fields` are not returned to the current user and have no row-value evidence
+- table schema `fields[].value` and `default_value_mode` describe schema defaults, not current row values
+
 ## Read one row
 
 Command:
@@ -96,6 +102,13 @@ arcubase row get \
 
 Use this when you already know the row id and want the full record payload.
 
+Returned values:
+
+- current row values are in `record.fields`
+- fields absent from `record.fields` are not returned to the current user and have no row-value evidence
+- use `fieldPermits` only to explain access, not as current row values
+- read visibility status is `fieldPermits read:false`; `FIELD_PERMISSION_REQUIRED` is a write preflight error from row create/update
+
 ## Update a row
 
 Command:
@@ -139,6 +152,61 @@ Success result:
 
 The update command returns `true`, not the updated row body.
 
+## Import Records
+
+Excel:
+
+```bash
+arcubase row import-excel \
+  --app-id <app_id> \
+  --table-id <table_id> \
+  --file records.xlsx \
+  --mapping-file mapping.excel.json \
+  --ttl-seconds 300
+```
+
+CSV:
+
+```bash
+arcubase row import-csv \
+  --app-id <app_id> \
+  --table-id <table_id> \
+  --file records.csv \
+  --mapping-file mapping.csv.json \
+  --ttl-seconds 300
+```
+
+Both commands accept local file paths only. CSV mapping uses headers. Excel mapping uses column letters. The mapping file is validated locally before the import task is started.
+
+Excel `mapping.excel.json`:
+
+```json
+{
+  "sheet": "Sheet1",
+  "mode": "addonly",
+  "headerRow": 1,
+  "dataStartRow": 2,
+  "fields": [
+    { "fieldId": 1001, "column": "A" }
+  ]
+}
+```
+
+CSV `mapping.csv.json`:
+
+```json
+{
+  "mode": "addonly",
+  "header": true,
+  "dataStartRow": 2,
+  "fields": [
+    { "fieldId": 1001, "header": "客户名称" }
+  ]
+}
+```
+
+For `updateonly` and `addorupdate`, include `recordId` in the mapping. Use `arcubase-admin table get --app-id <app_id> --table-id <table_id>` to inspect numeric field ids.
+
 ## Delete rows
 
 Command:

package/sdk-dist/docs/runtime-reference/search-and-bulk-actions.md

@@ -38,13 +38,38 @@ For extra query-string parameters, also use:
   "limit": 20,
   "offset": 0,
   "search": {
-    "text_search": "ORD-3001"
+    "q": "ORD-3001"
   }
 }
 ```
 
 This is the current success path for free-text search.
 
+Rules:
+
+- `search` is route-query state, not `ConditionSet`
+- every `search` value must be a string
+- use `q` for free-text search
+- use `tab` for a list tab id
+- use `filter_:<field_id_or_prop>` for field filters
+- do not use `search.conditions`, `search.condition`, `search.field_filters`, `filter`, `filters`, `where`, `order`, or `orderBy`
+
+## Field filter
+
+`query.json`:
+
+```json
+{
+  "limit": 20,
+  "offset": 0,
+  "search": {
+    "filter_:1002": "%7B%22is%22%3A%22member_1%22%7D"
+  }
+}
+```
+
+`filter_:...` values are URL-encoded `FilterCond` JSON strings. For example, `%7B%22is%22%3A%22member_1%22%7D` decodes to `{"is":"member_1"}`.
+
 ## Sorts
 
 `query.json`:

package/sdk-dist/docs/runtime-reference/table-lifecycle.md

@@ -102,7 +102,7 @@ Minimal `table-create.json`:
       "depends": [],
       "key": "description",
       "code_index": false,
-      "options": {"placeholder": "", "html": false, "size": "default", "lengthLimit": false, "lengthMin": 0, "lengthMax": 2000},
+      "options": {"placeholder": "", "html": false, "size": 6, "lengthLimit": false, "lengthMin": 0, "lengthMax": 2000},
       "transfers": null,
       "children": null
     },

package/sdk-dist/generated/command_registry.generated.ts

@@ -68,6 +68,63 @@ export const adminCommands = [
     "queryParams": [],
     "responseType": "AppCreateByTenantsRespVO"
   },
+  {
+    "scope": "admin",
+    "module": "app",
+    "functionName": "createAppFromBundleURL",
+    "commandPath": [
+      "app",
+      "create-from-bundle-url"
+    ],
+    "method": "POST",
+    "endpoint": "/api/apps/import-task",
+    "pathParams": [],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "url",
+        "flag": "url",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "name",
+        "flag": "name",
+        "type": "string",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "AppBundleImportTaskCreateRespVO"
+  },
+  {
+    "scope": "admin",
+    "module": "app",
+    "functionName": "watchAppBundleImportTask",
+    "commandPath": [
+      "app",
+      "watch-import-task"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/import-task/:task_id",
+    "pathParams": [
+      {
+        "param": "task_id",
+        "flag": "task-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": false
+      }
+    ],
+    "responseType": "AppBundleImportTaskStatusRespVO"
+  },
   {
     "scope": "admin",
     "module": "app",
@@ -791,6 +848,94 @@ export const userCommands = [
     "queryParams": [],
     "responseType": "EntityBulkUpdateRespVO"
   },
+  {
+    "scope": "user",
+    "module": "row",
+    "functionName": "importEntityRecordsFromExcel",
+    "commandPath": [
+      "row",
+      "import-excel"
+    ],
+    "method": "POST",
+    "endpoint": "/api/entity/:app_id/:entity_id/import",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "entity_id",
+        "flag": "table-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "file",
+        "flag": "file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "mapping_file",
+        "flag": "mapping-file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "ImporterGetStateRespVO"
+  },
+  {
+    "scope": "user",
+    "module": "row",
+    "functionName": "importEntityRecordsFromCSV",
+    "commandPath": [
+      "row",
+      "import-csv"
+    ],
+    "method": "POST",
+    "endpoint": "/api/entity/:app_id/:entity_id/import",
+    "pathParams": [
+      {
+        "param": "app_id",
+        "flag": "app-id"
+      },
+      {
+        "param": "entity_id",
+        "flag": "table-id"
+      }
+    ],
+    "controller": "manual",
+    "requestType": null,
+    "queryParams": [
+      {
+        "key": "file",
+        "flag": "file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "mapping_file",
+        "flag": "mapping-file",
+        "type": "string",
+        "hasDefault": false
+      },
+      {
+        "key": "ttl_seconds",
+        "flag": "ttl-seconds",
+        "type": "number",
+        "hasDefault": true
+      }
+    ],
+    "responseType": "ImporterGetStateRespVO"
+  },
   {
     "scope": "user",
     "module": "row",

package/sdk-dist/types/common.ts

@@ -293,6 +293,7 @@ export interface KioskConfig {
   interactiveMode?: string;
   lookupFields?: number[];
   options?: Record<string, any>;
+  printers?: Record<string, any>[];
   screens?: KioskScreen[];
   theme?: string;
 }