@carthooks/arcubase-cli 0.1.3 → 0.1.5

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.5",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",

package/sdk-dist/api/admin/app.ts

@@ -13,7 +13,8 @@ import type {
   AppUpdateAppRespVO,
   AppUpdateI18nReqVO,
   AppUpdateI18nRespVO,
-  AppGetEntitiesRespVO
+  AppGetEntitiesRespVO,
+  AppListRespVO
 } from '../../types/app'
 import type {
   AppDeleteWidgetsRespVO,
@@ -46,6 +47,12 @@ export async function createAppByTenants(
   return getDefaultClient().post('/apps', data)
 }
 
+// @endpoint GET /apps
+// @controller App.ListApps
+export async function listApps(): Promise<AppListRespVO> {
+  return getDefaultClient().get('/apps')
+}
+
 // @endpoint POST /apps/:id/entities
 // @controller App.CreateEntity
 export async function createEntity(

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

@@ -25,6 +25,7 @@ Do not start from raw HTTP methods or paths. Start from the CLI command.
 
 Use `arcubase-admin` for:
 
+- app discovery
 - app creation
 - entity shell creation
 - entity schema save
@@ -33,6 +34,7 @@ Use `arcubase-admin` for:
 Common commands:
 
 ```bash
+arcubase-admin app inventory
 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>
@@ -54,16 +56,24 @@ Use `arcubase` for:
 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 rows insert-entity --app-id <app_id> --entity-id <entity_id> --body-file insert.json
+arcubase rows query-entity --app-id <app_id> --entity-id <entity_id> --body-file query.json
+arcubase rows update-entity-row --app-id <app_id> --entity-id <entity_id> --row-id <row_id> --body-file update.json
+arcubase rows delete-entity-row --app-id <app_id> --entity-id <entity_id> --body-file delete.json
+arcubase rows restore-entity-row --app-id <app_id> --entity-id <entity_id> --body-file restore.json
+arcubase rows 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:
+
+- all Arcubase work starts by identifying the target app
+- `arcubase-admin` stops at schema save
+- all row operations must switch to `arcubase`
+- do not use `arcubase-admin` for row insertion or row queries
+- do not ask the user for `entity_id` when creating a new table
+
 ## Required file inputs
 
 Most write commands use:
@@ -79,7 +89,7 @@ Use `--query-file` when the command needs query-string parameters that do not be
 Current important example:
 
 ```bash
-arcubase workflow query-entity \
+arcubase rows query-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --query-file archived-query.json \
@@ -133,15 +143,22 @@ When a command is tied to a common task, `--help` should print:
 
 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
+1. read `app-discovery.md`
+2. read `table-lifecycle.md`
+3. read `entity-schema.md`
+4. read `entity-schema/README.md`
+5. open the exact field-type page you need
+
+If you need to find an existing app or choose the right app:
+
+1. read `app-discovery.md`
+2. run `arcubase-admin app inventory`
 
 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:
 
@@ -156,6 +173,8 @@ If you need search, selection, tags, bulk update, or batch operator:
 
 ## Covered now
 
+- `app-discovery.md`
+  - resolve the target app before asking the user for ids
 - `table-lifecycle.md`
   - app shell, entity shell, schema save, readiness probe
 - `entity-schema.md`
@@ -166,12 +185,11 @@ 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/`
   - business-shaped schema and payload templates
 
 ## Reserved expansion
-
-- `workflow/README.md`
-  - reserved for future workflow-specific CLI docs

package/sdk-dist/docs/runtime-reference/app-discovery.md

@@ -0,0 +1,68 @@
+# App Discovery
+
+Arcubase is a headless app platform.
+
+Core concepts:
+
+- app: the top-level business container
+- entity: a table inside an app
+- row: a record inside an entity
+
+Hard rule:
+
+- every operation happens inside one app
+- find the target app before schema work or row work
+
+Do not ask the user for `app_id` unless:
+
+- there is no matching app
+- there are multiple matching apps and you cannot resolve the ambiguity
+
+Do not ask the user for `entity_id` when creating a new table.
+Entity ids are assigned by Arcubase.
+
+## First command
+
+Use the inventory command first:
+
+```bash
+arcubase-admin app inventory
+```
+
+It returns:
+
+- every accessible app
+- each app id and app name
+- each app entity list
+
+Use it to resolve:
+
+- which existing app matches the user's business name
+- whether the table already exists
+- whether the user is talking about the wrong app
+
+## Resolution order
+
+1. if the user gives an app name, run `arcubase-admin app inventory`
+2. match the app by name yourself
+3. if the match is unique, continue without asking for `app_id`
+4. if there is no match, ask which app to use
+5. if there are multiple matches, ask the user to choose by app name
+
+## Existing app flow
+
+If the app already exists:
+
+1. run `arcubase-admin app inventory`
+2. find the app id
+3. inspect the existing entity list
+4. decide whether to create a new entity or write rows into an existing entity
+
+## New app flow
+
+If the user clearly wants a brand-new app:
+
+1. create the app with `arcubase-admin app create-app-by-tenants`
+2. create the entity shell
+3. save the schema
+4. switch to `arcubase rows ...` for row operations

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

@@ -54,8 +54,8 @@ If you need row payloads, read:
 Current important row rules:
 
 - row delete / restore uses:
-  - `arcubase workflow delete-entity-row`
-  - `arcubase workflow restore-entity-row`
+  - `arcubase rows delete-entity-row`
+  - `arcubase rows restore-entity-row`
   - `selection.type = "ids"`
 - `subform` row values use:
   - `[{ "id": 0, "fields": { ... } }]`

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/entity-schema/subform.md

@@ -43,8 +43,8 @@ Subform field.
 
 For row commands such as:
 
-- `arcubase workflow insert-entity`
-- `arcubase workflow update-entity-row`
+- `arcubase rows insert-entity`
+- `arcubase rows update-entity-row`
 
 the current writable row shape is:
 

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

@@ -30,7 +30,7 @@ The current direct-write path is:
 1. create the entity shell
 2. fetch the current shell
 3. save the full schema
-4. probe rows with `arcubase workflow query-entity`
+4. probe rows with `arcubase rows query-entity`
 
 Do not treat shell creation as “table created”.
 
@@ -180,7 +180,7 @@ Also:
 Do not call schema creation successful until:
 
 1. `arcubase-admin entity admin-save-entity ...` succeeds without top-level `error`
-2. `arcubase workflow query-entity ...` succeeds against the saved table
+2. `arcubase rows query-entity ...` succeeds against the saved table
 
 If row probing still fails, the table is not ready.
 

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

@@ -16,7 +16,7 @@ These examples are not raw tenant exports.
 
 - Keep table names and field names in English.
 - Remove company-specific words.
-- Remove region-specific words when they are not essential to the workflow.
+- Remove region-specific words when they are not essential to the business process.
 - Prefer neutral names such as `sku_code`, `sales_order`, `goods_receipt`, and `stock_issue`.
 - When a save payload needs shell values, replace placeholder tokens such as `__APP_ID__`, `__ENTITY_ID__`, and `__SCHEMA_VERSION__` from the current shell returned by:
 

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

@@ -1,6 +1,6 @@
 # OMS Example 01
 
-This example set models a compact order-management workflow.
+This example set models a compact order-management example.
 
 It is intentionally generic:
 
@@ -70,7 +70,7 @@ This example rewrites them into generic names such as:
 - `sales-order.selection.condition.json`
 - `sales-order.bulk-update.json`
 
-## Save workflow
+## Save sequence
 
 For every `*.schema.json` file:
 
@@ -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:
@@ -124,13 +143,13 @@ arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id
 Insert one row:
 
 ```bash
-arcubase workflow insert-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.row.insert.json
+arcubase rows insert-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.row.insert.json
 ```
 
 Query rows:
 
 ```bash
-arcubase workflow query-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.query.json
+arcubase rows query-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.query.json
 ```
 
 ## Placeholder rules

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

@@ -76,4 +76,4 @@ Purpose:
 - country-specific code naming
 - tenant-specific internal labels
 - region-specific channel names
-- company-specific workflow terms
+- company-specific process terms

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

@@ -7,7 +7,7 @@ Use this page for direct row operations with `arcubase`.
 Command:
 
 ```bash
-arcubase workflow insert-entity \
+arcubase rows insert-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file insert.json
@@ -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:
 
@@ -45,7 +46,7 @@ The returned value is the new `row_id`.
 Command:
 
 ```bash
-arcubase workflow query-entity \
+arcubase rows query-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file query.json
@@ -84,7 +85,7 @@ Typical row shape:
 Command:
 
 ```bash
-arcubase workflow get-entity-row \
+arcubase rows get-entity-row \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --row-id <row_id>
@@ -97,7 +98,7 @@ Use this when you already know the row id and want the full record payload.
 Command:
 
 ```bash
-arcubase workflow update-entity-row \
+arcubase rows update-entity-row \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --row-id <row_id> \
@@ -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:
 
@@ -137,7 +139,7 @@ The update command returns `true`, not the updated row body.
 Command:
 
 ```bash
-arcubase workflow delete-entity-row \
+arcubase rows delete-entity-row \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file delete.json
@@ -165,7 +167,7 @@ Rules:
 Command:
 
 ```bash
-arcubase workflow restore-entity-row \
+arcubase rows restore-entity-row \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file restore.json

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

@@ -14,7 +14,7 @@ Use this page for:
 Use:
 
 ```bash
-arcubase workflow query-entity \
+arcubase rows query-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file query.json
@@ -83,7 +83,7 @@ Archived view requires both:
 Command:
 
 ```bash
-arcubase workflow query-entity \
+arcubase rows query-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --query-file archived-query.json \
@@ -195,7 +195,7 @@ Rules:
 Command:
 
 ```bash
-arcubase workflow query-entity-selection \
+arcubase rows query-entity-selection \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --action query \
@@ -235,7 +235,7 @@ Rules:
 Command:
 
 ```bash
-arcubase workflow query-entity-selection \
+arcubase rows query-entity-selection \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --action archive \
@@ -253,7 +253,7 @@ Rules:
 Command:
 
 ```bash
-arcubase workflow query-entity-selection \
+arcubase rows query-entity-selection \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --action batch_print \

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

@@ -2,6 +2,7 @@
 
 Use this page when the goal is:
 
+- find the target app
 - create an app
 - create a table
 - save the schema
@@ -9,14 +10,36 @@ Use this page when the goal is:
 
 The successful path is command-first:
 
-1. create the app
-2. create the entity shell
-3. fetch the current shell
-4. save the full schema
-5. probe rows with `query-entity`
+1. identify the target app
+2. create the app
+3. create the entity shell
+4. fetch the current shell
+5. save the full schema
+6. probe rows with `query-entity`
 
 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 0: identify the target app
+
+Command:
+
+```bash
+arcubase-admin app inventory
+```
+
+Rules:
+
+- always resolve the app first when the user refers to an existing app by name
+- do not ask for `app_id` unless there is no match or more than one match
+- do not ask for `entity_id` when creating a new table
+
 ## Step 1: create the app
 
 Command:
@@ -97,12 +120,17 @@ 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 rows insert-entity` for row insertion
+- use `arcubase rows query-entity` for readiness and row reads
+
 ## Step 5: probe readiness
 
 Command:
 
 ```bash
-arcubase workflow query-entity \
+arcubase rows query-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file query.json