@carthooks/arcubase-cli 0.1.10 → 0.1.13

package/dist/tests/help.test.js

@@ -1,9 +1,12 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { executeCLI } from '../runtime/execute.js';
+import { listCommands } from '../runtime/command_registry.js';
+import { getTypeHints } from '../runtime/zod_registry.js';
 const env = {
     ARCUBASE_BASE_URL: 'https://arcubase.example.com',
     ARCUBASE_ACCESS_TOKEN: 'tok',
+    ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
     ARCUBASE_TRACE_ID: '',
     ARCUBASE_SUBJECT_TYPE: '',
     ARCUBASE_SUBJECT_ID: '',
@@ -43,33 +46,69 @@ test('admin module help lists reset app commands', async () => {
     assert.doesNotMatch(out.text, /create-entity/);
 });
 test('user row help replaces workflow row commands', async () => {
-    const out = await executeCLI('user', ['row', 'query', '--help'], undefined, async () => new Response('{}'));
+    const out = await executeCLI('user', ['row', 'query', '--help'], env, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
-    assert.match(out.text, /body: .*--body-file or --body-json/);
+    assert.match(out.text, /body: .*--body-json <json-string> \| --body-file <file>\.json/);
     assert.match(out.text, /query flags: --query-file/);
     assert.doesNotMatch(out.text, /workflow query-entity/);
     assert.doesNotMatch(out.text, /--entity-id/);
 });
+test('user row help does not expose internal policy id input', async () => {
+    const out = await executeCLI('user', ['row', 'get', '--help'], env, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.doesNotMatch(out.text, /--policy-id/);
+    assert.doesNotMatch(out.text, /policy_id/);
+});
 test('admin table update-schema help uses table nouns and body-json', async () => {
-    const out = await executeCLI('admin', ['table', 'update-schema', '--help'], undefined, async () => new Response('{}'));
+    const out = await executeCLI('admin', ['table', 'update-schema', '--help'], env, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
-    assert.match(out.text, /body: .*--body-file or --body-json/);
+    assert.match(out.text, /body: .*--body-json <json-string> \| --body-file <file>\.json/);
+    assert.match(out.text, /prefer --body-json/);
     assert.match(out.text, /path flags: --app-id, --table-id/);
     assert.doesNotMatch(out.text, /--entity-id/);
     assert.doesNotMatch(out.text, /admin-save-entity/);
 });
+test('admin table create help gives one-call body-json example', async () => {
+    const out = await executeCLI('admin', ['table', 'create', '--help'], env, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /body-json example:/);
+    assert.match(out.text, /"field_id_seq":1003/);
+    assert.match(out.text, /"label":"投票描述"/);
+    assert.match(out.text, /"type":"textarea"/);
+});
 test('admin access-rule help gives update whitelist and assign-users body-json examples', async () => {
-    const update = await executeCLI('admin', ['access-rule', 'update', '--help'], undefined, async () => new Response('{}'));
+    const create = await executeCLI('admin', ['access-rule', 'create', '--help'], env, async () => new Response('{}'));
+    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('{}'));
     assert.equal(update.kind, 'help');
     assert.match(update.text, /--app-id/);
     assert.match(update.text, /--table-id/);
     assert.match(update.text, /--rule-id/);
     assert.match(update.text, /"update":\["enabled"\]/);
-    const assign = await executeCLI('admin', ['access-rule', 'assign-users', '--help'], undefined, async () => new Response('{}'));
+    assert.match(update.text, /"actions":\["view","add","edit"\]/);
+    const assign = await executeCLI('admin', ['access-rule', 'assign-users', '--help'], env, async () => new Response('{}'));
     assert.equal(assign.kind, 'help');
     assert.match(assign.text, /"update":\["user_scope"\]/);
-    assert.match(assign.text, /\{"update":\["user_scope"\],"options":\{"user_scope":\[\{"type":"member","id":123\}\]\}\}/);
-    assert.doesNotMatch(assign.text, /"type":"user"/);
+    assert.match(assign.text, /\{"update":\["user_scope"\],"options":\{"user_scope":\[\{"type":"user","id":2188889901\}\]\}\}/);
+    assert.doesNotMatch(assign.text, /"type":"member"/);
     assert.doesNotMatch(assign.text, /"users"/);
     assert.doesNotMatch(assign.text, /"allowedUsers"/);
 });
+test('every body command help exposes readable TypeScript type paths', async () => {
+    for (const scope of ['admin', 'user']) {
+        for (const command of listCommands(scope).filter((item) => item.requestType)) {
+            const out = await executeCLI(scope, [...command.commandPath, '--help'], env, async () => new Response('{}'));
+            assert.equal(out.kind, 'help');
+            assert.match(out.text, /^types:$/m, `${scope} ${command.commandPath.join(' ')} must expose types section`);
+            for (const hint of getTypeHints(command.requestType ?? '', env)) {
+                assert.match(out.text, new RegExp(`${hint.symbol}: ${hint.file}`.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+            }
+        }
+    }
+});

package/dist/tests/upload.test.js

@@ -1,106 +1,59 @@
 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';
+import { CLIError } from '../runtime/errors.js';
 const env = {
     ARCUBASE_BASE_URL: 'https://arcubase.example.com',
     ARCUBASE_ACCESS_TOKEN: 'tok',
+    ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
     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('{}'));
+test('upload module help exposes reset upload commands with injected SDK root', async () => {
+    const out = await executeCLI('user', ['upload', '--help'], env, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
-    assert.match(out.text, /arcubase upload <local-file>/);
-    assert.match(out.text, /uploads\.md/);
+    assert.match(out.text, /commands:/);
+    assert.match(out.text, /token/);
+    assert.match(out.text, /preview/);
+    assert.match(out.text, /mobile/);
+    assert.match(out.text, /check-mobile/);
+    assert.doesNotMatch(out.text, /<local-file>/);
 });
-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');
+test('upload rejects local file shortcut', async () => {
+    await assert.rejects(async () => {
+        await executeCLI('user', ['upload', './contract.pdf'], env, async () => new Response('{}'));
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UNKNOWN_COMMAND');
+        assert.match(error.message, /unknown command: upload \.\/contract\.pdf/);
+        return true;
+    });
+});
+test('upload token executes the explicit API command', async () => {
     const calls = [];
-    const result = await executeCLI('user', ['upload', sourceFile], env, async (input, init) => {
+    const result = await executeCLI('user', ['upload', 'token', '--body-json', '{"global":false}'], env, async (input, init) => {
         const url = String(input);
-        calls.push({ url, method: init?.method });
+        calls.push({ url, method: init?.method, body: typeof init?.body === 'string' ? init.body : undefined });
         if (url === 'https://arcubase.example.com/api/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',
-                    },
+                    token_data: { 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/api/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: {},
+    assert.deepEqual(calls, [{ url: 'https://arcubase.example.com/api/upload/token', method: 'POST', body: '{"global":false}' }]);
+    assert.deepEqual(result.data, {
+        data: {
+            id: 123456,
+            mode: 'aliyun-oss',
+            token_data: { host: 'https://uploads.example.com' },
         },
-    ]);
-});
-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/api/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/api/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.10",
+  "version": "0.1.13",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",

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

@@ -11,13 +11,14 @@ Read it as a command cheatsheet:
 - what result shape to expect
 
 Do not start from raw HTTP methods or paths. Start from the CLI command.
+Prefer `--body-json <json-string>` for normal payloads, including table schema, to avoid an extra agent file operation. Use `--body-file <file>.json` only when the JSON is too large for one tool call.
 
 ## Paths
 
 - Development source:
   - `misc/packages/@carthooks/arcubase-cli/docs/runtime-reference/`
 - Runtime location:
-  - `/opt/arcubase-sdk/docs/runtime-reference/`
+  - `$ARCUBASE_SDK_ROOT/docs/runtime-reference/`
 - Published path:
   - `sdk-dist/docs/runtime-reference/`
 
@@ -26,18 +27,18 @@ Do not start from raw HTTP methods or paths. Start from the CLI command.
 Use `arcubase-admin` for:
 
 - app creation
-- entity shell creation
-- entity schema save
-- entity tag admin actions
+- table shell creation
+- table schema save
+- access-rule and workflow setup
 
 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> --table-id <table_id>
-arcubase-admin entity admin-save-entity --app-id <app_id> --table-id <table_id> --body-file save-entity.json
-arcubase-admin entity-tags get-selection-tags --appId <app_id> --entityId <table_id> --body-file get-tags.json
+arcubase-admin app create --body-file create-app.json | --body-json <json-string>
+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
 ```
 
 Use `arcubase` for:
@@ -49,31 +50,31 @@ Use `arcubase` for:
 - search
 - selection actions
 - bulk update
-- batch operator
 
 Common commands:
 
 ```bash
-arcubase row create --app-id <app_id> --table-id <table_id> --body-file insert.json
-arcubase row query --app-id <app_id> --table-id <table_id> --body-file query.json
-arcubase row update --app-id <app_id> --table-id <table_id> --row-id <row_id> --body-file update.json
-arcubase row delete --app-id <app_id> --table-id <table_id> --body-file delete.json
-arcubase row selection-action --app-id <app_id> --table-id <table_id> --action archive --body-file selection.json
-arcubase row bulk-update --app-id <app_id> --table-id <table_id> --body-file bulk-update.json
+arcubase row create --app-id <app_id> --table-id <table_id> --body-file insert.json | --body-json <json-string>
+arcubase row query --app-id <app_id> --table-id <table_id> --body-file query.json | --body-json <json-string>
+arcubase row update --app-id <app_id> --table-id <table_id> --row-id <row_id> --body-file update.json | --body-json <json-string>
+arcubase row delete --app-id <app_id> --table-id <table_id> --body-file delete.json | --body-json <json-string>
+arcubase row update --app-id <app_id> --table-id <table_id> --body-file restore.json | --body-json <json-string>
+arcubase row selection-action --app-id <app_id> --table-id <table_id> --action archive --body-file selection.json | --body-json <json-string>
+arcubase row bulk-update --app-id <app_id> --table-id <table_id> --body-file bulk-update.json | --body-json <json-string>
 ```
 
 Hard rule:
 
+- `table create` must include non-empty `fields`; empty table shell creation is not allowed
 - `arcubase-admin` stops at schema save
 - all row operations must switch to `arcubase`
-- do not use `arcubase-admin row create`
 - do not use `arcubase-admin row query`
 
 ## Required file inputs
 
 Most write commands use:
 
-- `--body-file <file>.json`
+- `--body-file <file>.json` or `--body-json <json-string>`
 
 Some query commands also use:
 
@@ -88,7 +89,7 @@ arcubase row query \
   --app-id <app_id> \
   --table-id <table_id> \
   --query-file archived-query.json \
-  --body-file archived-body.json
+  --body-file archived-body.json | --body-json <json-string>
 ```
 
 ## Runtime env
@@ -97,6 +98,8 @@ The CLIs accept either generic env keys:
 
 - `ARCUBASE_BASE_URL`
 - `ARCUBASE_ACCESS_TOKEN`
+- `ARCUBASE_SDK_ROOT`
+- optional: `ARCUBASE_TRACE_ID`
 
 or scoped env keys:
 
@@ -107,6 +110,9 @@ or scoped env keys:
   - `ARCUBASE_USER_BASE_URL`
   - `ARCUBASE_USER_ACCESS_TOKEN`
 
+Tenant identity comes from the JWT access token. Do not pass tenant ids through CLI env.
+  - `ARCUBASE_USER_HOST`
+
 Help should work without runtime env:
 
 ```bash
@@ -118,7 +124,7 @@ arcubase <module> --help
 arcubase <module> <command> --help
 ```
 
-Command help is also the discovery entrypoint for this doc set.
+Command help is also the index entrypoint for this doc set.
 
 When a command is tied to a common task, `--help` should print:
 
@@ -149,10 +155,17 @@ If you need a business-shaped template:
 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:
+If you need search, selection, or bulk update:
 
 1. read `search-and-bulk-actions.md`
-2. use `row-crud.md` only for row result shapes
+2. read `selection.md`
+3. read `condition.md`
+4. use `row-crud.md` only for row result shapes
+
+If you need workflow actions:
+
+1. read `workflow/README.md`
+2. use the exact `task_id`, node, record, and user ids returned by Arcubase
 
 ## Covered now
 
@@ -167,13 +180,14 @@ If you need search, selection, tags, bulk update, or batch operator:
 - `row-crud.md`
   - insert, query, update, delete, restore
 - `uploads.md`
-  - upload one local file and reuse the returned field value in row payloads
+  - upload token, preview, mobile upload, and mobile upload check API payloads
 - `search-and-bulk-actions.md`
-  - search, selection, tags, bulk update, batch operator
+  - search, selection, bulk update
+- `selection.md`
+  - `EntitySelectionVO`, ids/all/condition selection, command action matrix
+- `condition.md`
+  - selection condition, `FilterCond`, and `ConditionSet` differences
+- `workflow/README.md`
+  - process map, approve, rollback, countersign, forward, retract, resolve, approver query, node query
 - `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/access-rule.md

@@ -0,0 +1,128 @@
+# Access Rule
+
+Use `arcubase-admin access-rule` for app/table access.
+
+## One Path
+
+1. Get the numeric `TenantUser.ID`.
+2. Create an enabled rule with `options.policy`.
+3. Assign users with `options.user_scope`.
+4. Verify with `access-rule get`.
+
+## User Mapping
+
+```bash
+arcubase-admin get-digiemployee-users
+```
+
+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
+arcubase-admin access-rule create \
+  --app-id 2188893436 \
+  --table-id 2188893443 \
+  --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"]`
+- write permission = add `add` and `edit`
+- field key is `":<field_id>"`, not a number
+- field key is not the FieldVO `key`; do not use values like `vote_description`
+- hidden field = `{"key":":1002","read":false,"write":false,"report":false}`
+- when `all_fields_read=false` or `all_fields_write=false`, list each visible field with `read/write=true`
+- do not use `permissions`
+- do not use `field_visibility`
+- do not use `actions:["read","insert"]`
+
+## Enable Rule
+
+```bash
+arcubase-admin access-rule update \
+  --app-id 2188893436 \
+  --table-id 2188893443 \
+  --rule-id 2188893557 \
+  --body-json '{"update":["enabled"],"enabled":true}'
+```
+
+## Update Policy With Hidden Field
+
+Use this when the rule already exists and the field visibility or actions must change.
+
+```bash
+arcubase-admin access-rule update \
+  --app-id 2188893436 \
+  --table-id 2188893443 \
+  --rule-id 2188893557 \
+  --body-json '{"update":["options"],"options":{"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":{}}}'
+```
+
+Rules:
+
+- use `update:["options"]`
+- do not use `update:["options.policy"]`
+- field key is `":<field_id>"`, not a number
+- field key is not the FieldVO `key`; do not use values like `vote_description`
+- preserve `list_options:{}` unless the existing rule has a known replacement
+
+## Assign Users Only
+
+Use this only when the rule already has the correct `policy`.
+
+```bash
+arcubase-admin access-rule assign-users \
+  --app-id 2188893436 \
+  --table-id 2188893443 \
+  --rule-id 2188893557 \
+  --body-json '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}'
+```
+
+Rules:
+
+- `assign-users` preserves the existing policy.
+- body must use `update:["user_scope"]`.
+- body must use `options.user_scope`.
+- `user_scope[].type` is `user` for tenant users.
+- `user_scope[].id` is numeric `TenantUser.ID`.
+
+## Verify
+
+```bash
+arcubase-admin access-rule get \
+  --app-id 2188893436 \
+  --table-id 2188893443 \
+  --rule-id 2188893557
+```
+
+Success:
+
+- `enabled=true`
+- `options.user_scope` contains the numeric user id
+- `options.policy.actions` contains `view`, `add`, `edit`
+- `options.policy.fields` contains hidden fields as `{"key":":1002","read":false,"write":false,"report":false}`
+- visible fields are explicitly present with `read/write=true` when `all_fields_read/write=false`