@carthooks/arcubase-cli 0.1.3 → 0.1.4

package/dist/tests/execute_validation.test.js

@@ -328,6 +328,159 @@ test('selection action rejects selectAll-only condition for archive action', asy
         return true;
     });
 });
+test('insert entity rejects local file path for file field and points to arcubase upload', async () => {
+    const bodyFile = tempJSONFile({
+        fields: {
+            1001: 'Lead A',
+            1007: './contract.pdf',
+        },
+    });
+    const calls = [];
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+            calls.push({ url: String(url), method: init?.method });
+            if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+                return new Response(JSON.stringify({
+                    data: {
+                        id: 1,
+                        app_id: 1,
+                        fields: [
+                            { id: 1001, type: 'text', label: 'Lead Name' },
+                            { id: 1007, type: 'file', label: 'Contract File' },
+                        ],
+                    },
+                }), { status: 200 });
+            }
+            return new Response('{}', { status: 200 });
+        });
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.fields.1007'));
+        assert.match(error.message, /arcubase upload \.\/contract\.pdf/);
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/uploads.md')));
+        return true;
+    });
+    assert.deepEqual(calls, [
+        { url: 'https://arcubase.example.com/entity/app_1/entity_1', method: 'GET' },
+    ]);
+});
+test('update row rejects object value for image field and requires upload array', async () => {
+    const bodyFile = tempJSONFile({
+        changed_fields: [1008],
+        data: {
+            1008: {
+                upload_id: 123456,
+                file: 'lead-photo.jpg',
+                file_name: 'lead-photo.jpg',
+                meta: {},
+            },
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async (url, init) => {
+            if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+                return new Response(JSON.stringify({
+                    data: {
+                        id: 1,
+                        app_id: 1,
+                        fields: [
+                            { id: 1008, type: 'image', label: 'Lead Photo' },
+                        ],
+                    },
+                }), { status: 200 });
+            }
+            return new Response('{}', { status: 200 });
+        });
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'BODY_VALIDATION_FAILED');
+        assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.data.1008'));
+        assert.match(error.message, /must be an array/);
+        assert.match(error.message, /arcubase upload <local-file>/);
+        return true;
+    });
+});
+test('insert entity accepts upload array for file field after schema preflight', async () => {
+    const bodyFile = tempJSONFile({
+        fields: {
+            1001: 'Lead A',
+            1007: [
+                {
+                    upload_id: 123456,
+                    file: 'contract.pdf',
+                    file_name: 'contract.pdf',
+                    meta: {},
+                },
+            ],
+        },
+    });
+    const calls = [];
+    const out = await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+        calls.push({ url: String(url), method: init?.method });
+        if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+            return new Response(JSON.stringify({
+                data: {
+                    id: 1,
+                    app_id: 1,
+                    fields: [
+                        { id: 1001, type: 'text', label: 'Lead Name' },
+                        { id: 1007, type: 'file', label: 'Contract File' },
+                    ],
+                },
+            }), { status: 200 });
+        }
+        return new Response(String(init?.body ?? '{}'), { status: 200 });
+    });
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(calls, [
+        { url: 'https://arcubase.example.com/entity/app_1/entity_1', method: 'GET' },
+        { url: 'https://arcubase.example.com/entity/app_1/entity_1/insert', method: 'POST' },
+    ]);
+    assert.equal(out.data.fields['1007'][0].upload_id, 123456);
+});
+test('insert entity decorates upload bind failures with actionable guidance', async () => {
+    const bodyFile = tempJSONFile({
+        fields: {
+            1001: 'Lead A',
+            1007: [
+                {
+                    upload_id: 123456,
+                    file: 'contract.pdf',
+                    file_name: 'contract.pdf',
+                    meta: {},
+                },
+            ],
+        },
+    });
+    await assert.rejects(async () => {
+        await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+            if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+                return new Response(JSON.stringify({
+                    data: {
+                        fields: [{ id: 1007, type: 'file', label: 'Contract File' }],
+                    },
+                }), { status: 200 });
+            }
+            return new Response(JSON.stringify({
+                error: {
+                    message: 'failed to bind upload to assets: Head \"http://test-bucket.test.aliyuncs.com/upload/123456/contract.pdf\": dial tcp: lookup test-bucket.test.aliyuncs.com: no such host',
+                    type: 'system',
+                    key: 'error.system',
+                },
+                trace_id: 'req_upload_bind',
+            }), { status: 200 });
+        });
+    }, (error) => {
+        assert.ok(error instanceof CLIError);
+        assert.equal(error.code, 'UPSTREAM_BODY_ERROR');
+        assert.equal(error.details?.traceId, 'req_upload_bind');
+        assert.equal(error.details?.reason, 'the row payload used a file/image upload entry, but Arcubase could not bind that upload into an asset record');
+        assert.match(error.details?.hint ?? '', /rerun arcubase upload/);
+        assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/uploads.md')));
+        return true;
+    });
+});
 test('selection action rejects condition selection without selectAll', async () => {
     const bodyFile = tempJSONFile({
         selection: {

package/dist/tests/help.test.js

@@ -46,7 +46,7 @@ test('command help prints runtime doc hints for request body commands', async ()
     assert.equal(out.kind, 'help');
     assert.match(out.text, /docs:/);
     assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/row-crud\.md/);
-    assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/oms-01\/README\.md/);
+    assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/README\.md/);
 });
 test('command help prints query-file support', async () => {
     const out = await executeCLI('user', ['workflow', 'query-entity', '--help'], undefined, async () => new Response('{}'));
@@ -57,5 +57,21 @@ test('command help without request body can still point to lifecycle and example
     const out = await executeCLI('admin', ['entity', 'admin-get-entity-info', '--help'], undefined, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/table-lifecycle\.md/);
-    assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/oms-01\/README\.md/);
+    assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/README\.md/);
+});
+test('admin-save-entity help prints row-operation next step', async () => {
+    const out = await executeCLI('admin', ['entity', 'admin-save-entity', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /switch to arcubase for row operations/);
+    assert.match(out.text, /arcubase workflow insert-entity/);
+    assert.match(out.text, /arcubase workflow query-entity/);
+});
+test('wrong admin workflow command points to arcubase row command', async () => {
+    await assert.rejects(() => executeCLI('admin', ['workflow', 'insert-entity'], env, async () => new Response('{}')), (error) => {
+        assert.equal(error.code, 'UNKNOWN_COMMAND');
+        assert.equal(error.details?.reason, 'workflow insert-entity is a row operation, not an arcubase-admin command');
+        assert.equal(error.details?.hint, 'use: arcubase workflow insert-entity');
+        assert.ok((error.details?.suggestions ?? []).includes('arcubase workflow insert-entity'));
+        return true;
+    });
 });

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.3",
+  "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

@@ -64,6 +64,13 @@ arcubase entity update-entity-bulk --app-id <app_id> --entity-id <entity_id> --b
 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:
@@ -141,7 +148,8 @@ If you need to create a table:
 If you need row CRUD:
 
 1. read `row-crud.md`
-2. if a field is complex, open the exact field-type page
+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:
 
@@ -166,6 +174,8 @@ If you need search, selection, tags, bulk update, or batch operator:
   - 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/`

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

@@ -42,3 +42,12 @@ File upload field.
   - `count_range: false`
   - `count_min: 0`
   - `count_max: 9`
+
+## Row write rule
+
+When inserting or updating row data for a `file` field:
+
+- do not construct upload payload objects by hand
+- run `arcubase upload <local-file>` first
+- use the returned `data` array directly as the row field value
+- read `../uploads.md`

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

@@ -41,3 +41,12 @@ Image upload field.
   - `count_range: false`
   - `count_min: 0`
   - `count_max: 9`
+
+## Row write rule
+
+When inserting or updating row data for an `image` field:
+
+- do not construct upload payload objects by hand
+- run `arcubase upload <local-file>` first
+- use the returned `data` array directly as the row field value
+- read `../uploads.md`

package/sdk-dist/docs/runtime-reference/examples/oms-01/README.md

@@ -85,6 +85,25 @@ For every `*.schema.json` file:
 
 These schema files are templates, not live shell exports.
 
+## CLI phases
+
+Phase 1 uses `arcubase-admin`:
+
+- create the app
+- create entity shells
+- fetch shells
+- save schemas
+
+Phase 2 uses `arcubase`:
+
+- insert rows
+- query rows
+- update rows
+- delete or restore rows
+- search, selection, and bulk actions
+
+Do not use `arcubase-admin` for row operations.
+
 ## Minimal command path
 
 Create the app:

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

@@ -29,6 +29,7 @@ Rules:
 
 - use numeric field ids as JSON object keys
 - values must match the saved schema
+- if a field is `file` or `image`, run `arcubase upload <local-file>` first and use the returned `data` array as the field value
 
 Success result:
 
@@ -121,6 +122,7 @@ Rules:
 - `changed_fields` is required
 - every id in `changed_fields` must also appear in `data`
 - use numeric field ids as JSON object keys
+- if a field is `file` or `image`, run `arcubase upload <local-file>` first and use the returned `data` array as the field value
 
 Success result:
 

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

@@ -17,6 +17,13 @@ The successful path is command-first:
 
 Do not stop at shell creation.
 
+CLI phase split:
+
+- schema phase uses `arcubase-admin`
+- row phase uses `arcubase`
+- the switch happens immediately after `admin-save-entity`
+- do not use `arcubase-admin` for row insert or row query
+
 ## Step 1: create the app
 
 Command:
@@ -97,6 +104,11 @@ Read before writing `save-entity.json`:
 2. `entity-schema/README.md`
 3. the exact field-type pages you need
 
+After `admin-save-entity`, switch binaries:
+
+- use `arcubase workflow insert-entity` for row insertion
+- use `arcubase workflow query-entity` for readiness and row reads
+
 ## Step 5: probe readiness
 
 Command:

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

@@ -0,0 +1,106 @@
+# Uploads
+
+Use this page when a row contains a `file` or `image` field.
+
+The successful path is:
+
+1. run `arcubase upload <local-file>`
+2. use the returned JSON array directly as the field value
+3. insert or update the row with `arcubase workflow insert-entity` or `arcubase workflow update-entity-row`
+
+Do not construct `upload_id`, `assets_id`, or OSS form fields by hand.
+
+## Upload one local file
+
+Command:
+
+```bash
+arcubase upload ./contract.pdf
+```
+
+Optional flags:
+
+- `--filename <name>`
+- `--global`
+
+Example:
+
+```bash
+arcubase upload ./lead-photo.jpg --filename lead-photo.jpg
+```
+
+## Upload result shape
+
+The command returns a JSON array.
+
+Example:
+
+```json
+{
+  "data": [
+    {
+      "upload_id": 123456,
+      "file": "contract.pdf",
+      "file_name": "contract.pdf",
+      "meta": {}
+    }
+  ]
+}
+```
+
+Use the `data` array directly as the field value for a `file` or `image` field.
+
+## Insert a row with a file field
+
+```json
+{
+  "fields": {
+    "1001": "Lead A",
+    "1007": [
+      {
+        "upload_id": 123456,
+        "file": "contract.pdf",
+        "file_name": "contract.pdf",
+        "meta": {}
+      }
+    ]
+  }
+}
+```
+
+## Update a row with an image field
+
+```json
+{
+  "data": {
+    "1008": [
+      {
+        "upload_id": 123457,
+        "file": "lead-photo.jpg",
+        "file_name": "lead-photo.jpg",
+        "meta": {}
+      }
+    ]
+  },
+  "changed_fields": [1008]
+}
+```
+
+## Preview an uploaded file
+
+Command:
+
+```bash
+arcubase common upload-preview --body-file preview.json
+```
+
+Example `preview.json`:
+
+```json
+{
+  "upload_id": 123456,
+  "fname": "contract.pdf"
+}
+```
+
+This returns a preview URL for the upload token entry. It does not insert or update a row.

package/src/runtime/errors.ts

@@ -20,6 +20,7 @@ export type CLIErrorDetails = {
   tsHints?: CLITSTypeHint[]
   docHints?: CLIDocHint[]
   reason?: string
+  hint?: string
   endpoint?: string
   method?: string
   traceId?: string