@carthooks/arcubase-cli 0.1.13 → 0.1.16

package/src/runtime/execute.ts

@@ -1,11 +1,15 @@
+import fs from 'fs'
+import path from 'path'
 import { parseCLIArgs, hasFlag, flagValue } from './argv.js'
 import { loadRuntimeEnv, type RuntimeEnv } from './env.js'
 import { CLIError, type CLIErrorDetails } from './errors.js'
 import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js'
-import { listModules, listModuleCommands, findCommand, findCommandSuggestions, type CommandScope } from './command_registry.js'
+import { listModules, listModuleCommands, findCommand, findCommandSuggestions, type CommandDef, type CommandScope } from './command_registry.js'
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js'
 import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
 import { resolveArcubaseSDKPath } from './paths.js'
+import { compileCSVImportMapping, compileExcelImportMapping, type CompiledEntityImportConfig } from './entity_import_mapping.js'
+import { uploadLocalFileWithToken } from './local_upload.js'
 
 export type CommandExecutionSummary = {
   scope: CommandScope
@@ -142,6 +146,48 @@ export function renderCommandHelp(scope: CommandScope, moduleName: string, comma
           '  - If result.enabled is false, enable the rule first and retry assign-users',
         ]
       : []),
+    ...(scope === 'admin' && command.commandPath[0] === 'app' && command.commandPath[1] === 'create-from-bundle-url'
+      ? [
+          'flags:',
+          '  - --url must be a public http/https app bundle zip URL',
+          '  - --name is accepted for compatibility; imported app name comes from the bundle source app',
+          'success:',
+          '  - returns task_id; use app watch-import-task to wait for completion',
+        ]
+      : []),
+    ...(scope === 'admin' && command.commandPath[0] === 'app' && command.commandPath[1] === 'watch-import-task'
+      ? [
+          'flags:',
+          '  - --task-id is returned by app create-from-bundle-url',
+          '  - --ttl-seconds is a local wait limit and does not cancel the backend task',
+          'success:',
+          '  - returns finished task status with app_id, name, and warnings',
+        ]
+      : []),
+    ...(scope === 'user' && command.commandPath[0] === 'row' && command.commandPath[1] === 'import-excel'
+      ? [
+          'mapping-file example:',
+          '  - {"sheet":"Sheet1","mode":"addonly","headerRow":1,"dataStartRow":2,"fields":[{"fieldId":1001,"column":"A"}]}',
+          'rules:',
+          '  - import supports local file paths only',
+          '  - --file must be a local Excel file path',
+          '  - Excel columns use letters such as A, B, AA',
+          '  - row numbers are 1-based',
+          '  - fieldId must be numeric; use arcubase-admin table get --app-id <app_id> --table-id <table_id>',
+        ]
+      : []),
+    ...(scope === 'user' && command.commandPath[0] === 'row' && command.commandPath[1] === 'import-csv'
+      ? [
+          'mapping-file example:',
+          '  - {"mode":"addonly","header":true,"dataStartRow":2,"fields":[{"fieldId":1001,"header":"客户名称"}]}',
+          'rules:',
+          '  - import supports local file paths only',
+          '  - --file must be a local CSV file path',
+          '  - CSV mapping uses headers, not column indexes',
+          '  - CSV import does not support embedded images',
+          '  - fieldId must be numeric; use arcubase-admin table get --app-id <app_id> --table-id <table_id>',
+        ]
+      : []),
     ...(docHints.length > 0
       ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
       : []),
@@ -232,6 +278,18 @@ function buildUnknownFlagDetails(
     operation,
     hint: `run ${operation} --help for the supported flags`,
   }
+  if (command.commandPath[0] === 'app' && command.commandPath[1] === 'create' && flag === 'url') {
+    details.hint = 'app bundle URLs must use app create-from-bundle-url; do not retry app create'
+    details.commonMistakes = [
+      'do not use app create for app bundle URLs',
+      'do not put url inside app create --body-json',
+    ]
+    details.suggestions = [
+      'retry with: app create-from-bundle-url --url <public_http_zip_url> --name <app_name>',
+      'then watch with: app watch-import-task --task-id <task_id> --ttl-seconds 300',
+    ]
+    return details
+  }
   if (command.requestType) {
     details.requestType = command.requestType
     details.tsHints = getTypeHints(command.requestType, env)
@@ -243,8 +301,7 @@ function buildUnknownFlagDetails(
     details.suggestions = [`retry with: ${command.commandPath.join(' ')} ${command.pathParams.filter((item) => !getFixedValue(item)).map((item) => `--${item.flag} <${item.flag.replace(/-/g, '_')}>`).join(' ')} --body-json '<json>'`.replace(/\s+/g, ' ').trim()]
   }
   if (command.commandPath[0] === 'row' && command.commandPath[1] === 'query' && ['limit', 'offset', 'search', 'sorts', 'view-mode'].includes(flag)) {
-    details.shapeHint = { limit: 20, offset: 0, search: { text_search: 'SO-1001' } }
-    details.suggestions = ['retry with: row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0}\'']
+    Object.assign(details, buildBodyGuidance('EntityQueryReqVO'))
   }
   if (command.commandPath[0] === 'table' && command.commandPath[1] === 'dataset' && ['app-id', 'table-id'].includes(flag)) {
     details.hint = 'table dataset uses --dataset-id and --node-id; use table get for app/table metadata'
@@ -537,7 +594,7 @@ function buildTableCreateExampleBody() {
         depends: [],
         key: 'vote_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,
       },
@@ -555,6 +612,10 @@ function isTableCreateCommand(scope: CommandScope, command: NonNullable<ReturnTy
   return scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'create'
 }
 
+function isEntityRecordImportCommand(scope: CommandScope, command: CommandDef): boolean {
+  return scope === 'user' && command.commandPath[0] === 'row' && (command.commandPath[1] === 'import-excel' || command.commandPath[1] === 'import-csv')
+}
+
 function isTableSchemaCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
   return scope === 'admin' && command.commandPath[0] === 'table' && (command.commandPath[1] === 'create' || command.commandPath[1] === 'update-schema')
 }
@@ -697,7 +758,7 @@ function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'retryToo
             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,
           },
@@ -807,15 +868,21 @@ function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'retryToo
       shapeHint: {
         limit: 20,
         offset: 0,
-        search: { text_search: 'SO-1001' },
+        search: { q: 'SO-1001' },
+        sorts: [{ column: ':1001', order: 'asc' }],
       },
       commonMistakes: [
         'limit, offset, search, sorts, and view_mode belong inside --body-json',
         'do not pass --limit or --offset flags',
+        'do not use search.conditions, search.condition, search.field_filters, filter, filters, where, or order',
+        'search only accepts string route-query keys such as q, tab, and filter_:1002',
+        'sorts belongs at top level and uses column values like ":1001"; do not use order/orderBy',
         'do not add access policy fields; the CLI resolves access policy internally',
       ],
       suggestions: [
         'retry with: arcubase row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0}\'',
+        'retry text search with: arcubase row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0,"search":{"q":"SO-1001"}}\'',
+        'retry field filter with: arcubase row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0,"search":{"filter_:1002":"%7B%22is%22%3A%22member_1%22%7D"}}\'',
       ],
     }
   }
@@ -1588,6 +1655,247 @@ async function requestJSON(
   return { status: response.status, data: parsedResponse }
 }
 
+function requiredStringFlag(flags: Record<string, string | boolean>, flag: string): string {
+  const value = flagValue(flags, flag)
+  if (!value) {
+    throw new CLIError('MISSING_PATH_FLAG', `missing required flag --${flag}`, 2)
+  }
+  return value
+}
+
+function validateAppBundleImportURL(rawURL: string): string {
+  const value = rawURL.trim()
+  let parsed: URL
+  try {
+    parsed = new URL(value)
+  } catch {
+    throw new CLIError('INVALID_IMPORT_URL', '--url must be a public http/https app bundle zip URL', 2, {
+      hint: 'retry with --url https://.../app-bundles/...zip',
+    })
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new CLIError('INVALID_IMPORT_URL', '--url must be a public http/https app bundle zip URL', 2, {
+      hint: 'local files and upload ids are not supported; provide a public app bundle URL',
+    })
+  }
+  return value
+}
+
+function watchIntervalMs(env: EnvInput): number {
+  const raw = env.ARCUBASE_IMPORT_TASK_WATCH_INTERVAL_MS
+  const parsed = raw ? Number(raw) : 2000
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 2000
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function executeCreateAppFromBundleURL(runtimeEnv: RuntimeEnv, flags: Record<string, string | boolean>, fetchImpl: typeof fetch) {
+  const url = validateAppBundleImportURL(requiredStringFlag(flags, 'url'))
+  const name = flagValue(flags, 'name')
+  const result = await requestJSON(runtimeEnv, 'POST', '/api/apps/import-task', {
+    url,
+    ...(name ? { name } : {}),
+  }, fetchImpl)
+  const taskID = extractImportTaskID(result.data)
+  return {
+    kind: 'result',
+    commandPath: ['app', 'create-from-bundle-url'],
+    status: result.status,
+    data: result.data,
+    nextAction: {
+      command: 'app watch-import-task',
+      args: ['--task-id', taskID, '--ttl-seconds', '300'],
+      hint: 'run this command until the task returns status=finished and app_id > 0; task_id alone is not success',
+    },
+  }
+}
+
+async function executeWatchAppBundleImportTask(runtimeEnv: RuntimeEnv, flags: Record<string, string | boolean>, fetchImpl: typeof fetch) {
+  const taskID = requiredStringFlag(flags, 'task-id')
+  const ttlRaw = requiredStringFlag(flags, 'ttl-seconds')
+  const ttlSeconds = Number(ttlRaw)
+  if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+    throw new CLIError('INVALID_FLAG_VALUE', `expected positive ttl seconds, got ${ttlRaw}`, 2)
+  }
+  const deadline = Date.now() + ttlSeconds * 1000
+  const endpoint = `/api/apps/import-task/${encodeURIComponent(taskID)}`
+  let latest: any = null
+  while (Date.now() <= deadline) {
+    const result = await requestJSON(runtimeEnv, 'GET', endpoint, undefined, fetchImpl)
+    latest = result.data
+    const payload = isRecord(latest) && isRecord(latest.data) ? latest.data : latest
+    const status = isRecord(payload) ? payload.status : undefined
+    if (status === 'finished') {
+      const appID = isRecord(payload) ? Number(payload.app_id) : 0
+      if (!Number.isFinite(appID) || appID <= 0) {
+        throw new CLIError('IMPORT_TASK_APP_ID_MISSING', 'app bundle import task finished without app_id', 1, {
+          endpoint,
+          responseBody: stringifyUpstreamBody(latest),
+          hint: 'treat this as an import failure; do not claim the app was imported',
+        })
+      }
+      return {
+        kind: 'result',
+        commandPath: ['app', 'watch-import-task'],
+        status: result.status,
+        data: latest,
+      }
+    }
+    if (status === 'failed') {
+      throw new CLIError('IMPORT_TASK_FAILED', isRecord(payload) && typeof payload.error === 'string' ? payload.error : 'app bundle import task failed', 1, {
+        endpoint,
+        responseBody: stringifyUpstreamBody(latest),
+      })
+    }
+    await sleep(Math.min(watchIntervalMs(runtimeEnv), Math.max(0, deadline - Date.now())))
+  }
+  throw new CLIError('IMPORT_TASK_WATCH_TIMEOUT', `import task did not finish within ${ttlSeconds} seconds`, 1, {
+    endpoint,
+    responseBody: stringifyUpstreamBody(latest),
+  })
+}
+
+function readJSONFile(filePath: string, label: string): unknown {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+  } catch {
+    throw new CLIError('INVALID_JSON_FILE', `${label} file is invalid: ${filePath}`, 2)
+  }
+}
+
+function assertLocalImportFile(filePath: string, format: 'excel' | 'csv') {
+  let stat
+  try {
+    stat = fs.statSync(filePath)
+  } catch {
+    throw new CLIError('LOCAL_FILE_NOT_FOUND', `local file not found: ${filePath}`, 2)
+  }
+  if (!stat.isFile()) {
+    throw new CLIError('LOCAL_FILE_INVALID', `path is not a regular file: ${filePath}`, 2)
+  }
+  const ext = path.extname(filePath).toLowerCase()
+  if (format === 'csv' && ext !== '.csv') {
+    throw new CLIError('LOCAL_FILE_INVALID', 'row import-csv requires a .csv file', 2)
+  }
+  if (format === 'excel' && !['.xlsx', '.xlsm', '.xls'].includes(ext)) {
+    throw new CLIError('LOCAL_FILE_INVALID', 'row import-excel requires an Excel file', 2)
+  }
+}
+
+function csvHeadersFromLocalFile(filePath: string, delimiter = ','): string[] {
+  const firstLine = fs.readFileSync(filePath, 'utf8').split(/\r?\n/, 1)[0] ?? ''
+  const headers: string[] = []
+  let current = ''
+  let quoted = false
+  for (let i = 0; i < firstLine.length; i += 1) {
+    const char = firstLine[i]
+    if (char === '"') {
+      if (quoted && firstLine[i + 1] === '"') {
+        current += '"'
+        i += 1
+      } else {
+        quoted = !quoted
+      }
+    } else if (char === delimiter && !quoted) {
+      headers.push(current)
+      current = ''
+    } else {
+      current += char
+    }
+  }
+  headers.push(current)
+  return headers
+}
+
+async function postEntityImportAction(runtimeEnv: RuntimeEnv, appId: string, entityId: string, body: unknown, fetchImpl: typeof fetch): Promise<any> {
+  const endpoint = `/api/entity/${encodeURIComponent(appId)}/${encodeURIComponent(entityId)}/import`
+  const response = await requestJSON(runtimeEnv, 'POST', endpoint, body, fetchImpl)
+  return response.data
+}
+
+function extractImportTaskID(value: unknown): string {
+  const candidates = [
+    value,
+    isRecord(value) ? value.data : undefined,
+  ]
+  for (const candidate of candidates) {
+    if (isRecord(candidate) && typeof candidate.taskId === 'string') return candidate.taskId
+    if (isRecord(candidate) && typeof candidate.task_id === 'string') return candidate.task_id
+    if (typeof candidate === 'string') return candidate
+  }
+  throw new CLIError('UPSTREAM_RESPONSE_INVALID', 'import response did not include taskId', 1)
+}
+
+function extractUploadToken(value: unknown): unknown {
+  const payload = isRecord(value) && isRecord(value.data) ? value.data : value
+  if (isRecord(payload) && isRecord(payload.token)) return payload.token
+  throw new CLIError('UPSTREAM_RESPONSE_INVALID', 'import init-token response did not include upload token', 1)
+}
+
+function compileEntityImportConfig(format: 'excel' | 'csv', mapping: unknown, filePath: string): CompiledEntityImportConfig {
+  if (format === 'excel') {
+    return compileExcelImportMapping(mapping)
+  }
+  const delimiter = isRecord(mapping) && typeof mapping.delimiter === 'string' ? mapping.delimiter : ','
+  return compileCSVImportMapping(mapping, csvHeadersFromLocalFile(filePath, delimiter))
+}
+
+async function executeEntityRecordImport(
+  command: CommandDef,
+  runtimeEnv: RuntimeEnv,
+  flags: Record<string, string | boolean>,
+  fetchImpl: typeof fetch,
+) {
+  const appId = requiredStringFlag(flags, 'app-id')
+  const entityId = requiredStringFlag(flags, 'table-id')
+  const filePath = requiredStringFlag(flags, 'file')
+  const mappingPath = requiredStringFlag(flags, 'mapping-file')
+  const ttlRaw = flagValue(flags, 'ttl-seconds') ?? '300'
+  const ttlSeconds = Number(ttlRaw)
+  if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+    throw new CLIError('INVALID_FLAG_VALUE', `expected positive ttl seconds, got ${ttlRaw}`, 2)
+  }
+
+  const format: 'excel' | 'csv' = command.commandPath[1] === 'import-csv' ? 'csv' : 'excel'
+  assertLocalImportFile(filePath, format)
+  const mapping = readJSONFile(mappingPath, 'mapping')
+  const config = compileEntityImportConfig(format, mapping, filePath)
+
+  const init = await postEntityImportAction(runtimeEnv, appId, entityId, { _import_action: 'init-token' }, fetchImpl)
+  const taskId = extractImportTaskID(init)
+  const token = extractUploadToken(init)
+  await uploadLocalFileWithToken(filePath, token as any, fetchImpl)
+  await postEntityImportAction(runtimeEnv, appId, entityId, { _import_action: 'uploaded', task_id: taskId }, fetchImpl)
+  await postEntityImportAction(runtimeEnv, appId, entityId, { _import_action: 'do-process', task_id: taskId, config }, fetchImpl)
+
+  const deadline = Date.now() + ttlSeconds * 1000
+  let latest: any = null
+  while (Date.now() <= deadline) {
+    latest = await postEntityImportAction(runtimeEnv, appId, entityId, { _import_action: 'get-state', task_id: taskId }, fetchImpl)
+    const payload = isRecord(latest) && isRecord(latest.data) ? latest.data : latest
+    const status = isRecord(payload) ? payload.status : undefined
+    if (status === 'finished') {
+      return {
+        kind: 'result',
+        commandPath: command.commandPath,
+        status: 200,
+        data: latest,
+      }
+    }
+    if (status === 'failed') {
+      throw new CLIError('IMPORT_TASK_FAILED', 'entity record import task failed', 1, {
+        responseBody: stringifyUpstreamBody(latest),
+      })
+    }
+    await sleep(Math.min(watchIntervalMs(runtimeEnv), Math.max(0, deadline - Date.now())))
+  }
+  throw new CLIError('IMPORT_TASK_WATCH_TIMEOUT', `import task did not finish within ${ttlSeconds} seconds`, 1, {
+    responseBody: stringifyUpstreamBody(latest),
+  })
+}
+
 function extractCreatedTableID(value: unknown): number {
   const candidates = [
     value,
@@ -1725,6 +2033,16 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
 
   const runtimeEnv = env ?? loadRuntimeEnv(scope)
 
+  if (scope === 'admin' && command.commandPath[0] === 'app' && command.commandPath[1] === 'create-from-bundle-url') {
+    return executeCreateAppFromBundleURL(runtimeEnv, parsed.flags, fetchImpl)
+  }
+  if (scope === 'admin' && command.commandPath[0] === 'app' && command.commandPath[1] === 'watch-import-task') {
+    return executeWatchAppBundleImportTask(runtimeEnv, parsed.flags, fetchImpl)
+  }
+  if (isEntityRecordImportCommand(scope, command)) {
+    return executeEntityRecordImport(command, runtimeEnv, parsed.flags, fetchImpl)
+  }
+
   const endpoint = resolveEndpoint(command, parsed.flags)
   const scalarQuery = buildScalarQuery(command, parsed.flags)
   const fileQuery = loadQueryFromFlags(parsed.flags)

package/src/runtime/local_upload.ts

@@ -0,0 +1,84 @@
+import fs from 'fs/promises'
+import path from 'path'
+import { CLIError } from './errors.js'
+
+type UploadTokenPayload = {
+  mode?: string
+  token_data?: unknown
+  tokenData?: unknown
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+async function ensureLocalFile(filePath: string) {
+  let stat
+  try {
+    stat = await fs.stat(filePath)
+  } catch {
+    throw new CLIError('LOCAL_FILE_NOT_FOUND', `local file not found: ${filePath}`, 2)
+  }
+  if (!stat.isFile()) {
+    throw new CLIError('LOCAL_FILE_INVALID', `path is not a regular file: ${filePath}`, 2)
+  }
+}
+
+function tokenData(token: UploadTokenPayload): Record<string, any> {
+  const data = token.token_data ?? token.tokenData
+  if (!isRecord(data)) {
+    throw new CLIError('UPLOAD_TOKEN_UNSUPPORTED', 'upload token data is not an object', 1)
+  }
+  return data
+}
+
+function appendAliyunCompatFields(form: FormData, data: Record<string, any>, objectKey: string) {
+  form.set('key', objectKey)
+  form.set('policy', String(data.policy))
+  form.set('OSSAccessKeyId', String(data.accessid))
+  form.set('Signature', String(data.signature))
+  form.set('success_action_status', '200')
+  if (typeof data.callback === 'string' && data.callback !== '') {
+    form.set('callback', data.callback)
+  }
+}
+
+function appendS3PostPolicyFields(form: FormData, data: Record<string, any>, objectKey: string) {
+  form.set('key', objectKey)
+  form.set('Policy', String(data.policy))
+  form.set('X-Amz-Algorithm', String(data.x_amz_algorithm))
+  form.set('X-Amz-Credential', String(data.x_amz_credential))
+  form.set('X-Amz-Date', String(data.x_amz_date))
+  form.set('X-Amz-Signature', String(data.x_amz_signature))
+}
+
+export async function uploadLocalFileWithToken(filePath: string, token: UploadTokenPayload, fetchImpl: typeof fetch = fetch): Promise<{ objectKey: string }> {
+  await ensureLocalFile(filePath)
+  const data = tokenData(token)
+  if (typeof data.host !== 'string' || data.host === '' || typeof data.dir !== 'string') {
+    throw new CLIError('UPLOAD_TOKEN_UNSUPPORTED', `unsupported upload token mode: ${token.mode ?? 'unknown'}`, 1)
+  }
+
+  const fileName = path.basename(filePath)
+  const objectKey = `${data.dir}${fileName}`
+  const form = new FormData()
+  if (typeof data.x_amz_signature === 'string') {
+    appendS3PostPolicyFields(form, data, objectKey)
+  } else if (typeof data.accessid === 'string' && typeof data.signature === 'string') {
+    appendAliyunCompatFields(form, data, objectKey)
+  } else {
+    throw new CLIError('UPLOAD_TOKEN_UNSUPPORTED', `unsupported upload token mode: ${token.mode ?? 'unknown'}`, 1)
+  }
+
+  const raw = await fs.readFile(filePath)
+  form.set('file', new Blob([raw]), fileName)
+  const response = await fetchImpl(data.host, { method: 'POST', body: form })
+  if (!response.ok) {
+    const body = await response.text().catch(() => '')
+    throw new CLIError('LOCAL_UPLOAD_FAILED', body || `upload failed with HTTP ${response.status}`, 1, {
+      status: response.status,
+      responseBody: body,
+    })
+  }
+  return { objectKey }
+}

package/src/tests/command_registry.test.ts

@@ -11,10 +11,12 @@ test('admin surface is restricted to reset white list', () => {
   const actual = commandPaths(adminCommands)
   const expected = [
     'app create',
+    'app create-from-bundle-url',
     'app delete',
     'app get',
     'app list',
     'app update',
+    'app watch-import-task',
     'table create',
     'table delete',
     'table get',
@@ -45,6 +47,8 @@ test('user surface is restricted to reset white list', () => {
     'row create',
     'row delete',
     'row get',
+    'row import-csv',
+    'row import-excel',
     'row query',
     'row selection-action',
     'row update',

package/src/tests/entity_import_mapping.test.ts

@@ -0,0 +1,87 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { compileCSVImportMapping, compileExcelImportMapping } from '../runtime/entity_import_mapping.js'
+import { CLIError } from '../runtime/errors.js'
+
+test('excel mapping compiles column letters to backend mapper', () => {
+  const result = compileExcelImportMapping({
+    sheet: 'Sheet1',
+    mode: 'addorupdate',
+    headerRow: 1,
+    dataStartRow: 2,
+    recordId: { column: 'A' },
+    fields: [
+      { fieldId: 1001, column: 'B' },
+      { fieldId: 1002, column: 'AA' },
+    ],
+  })
+  assert.deepEqual(result, {
+    fileFormat: 'excel',
+    importMode: 'addorupdate',
+    workingSheet: 'Sheet1',
+    titleRowIndex: 0,
+    mapper: {
+      '$id': 0,
+      '1001': 1,
+      '1002': 26,
+    },
+  })
+})
+
+test('excel mapping rejects string field id', () => {
+  assert.throws(() => {
+    compileExcelImportMapping({
+      sheet: 'Sheet1',
+      mode: 'addonly',
+      dataStartRow: 2,
+      fields: [{ fieldId: '1001', column: 'A' }],
+    } as any)
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'INVALID_IMPORT_MAPPING')
+    assert.match(error.message, /fieldId must be a number/)
+    return true
+  })
+})
+
+test('csv mapping resolves headers to backend mapper', () => {
+  const result = compileCSVImportMapping({
+    mode: 'updateonly',
+    header: true,
+    dataStartRow: 2,
+    delimiter: ',',
+    recordId: { header: 'ID' },
+    fields: [
+      { fieldId: 1001, header: '客户名称' },
+      { fieldId: 1002, header: '手机号' },
+    ],
+  }, ['ID', '客户名称', '手机号'])
+  assert.deepEqual(result, {
+    fileFormat: 'csv',
+    importMode: 'updateonly',
+    titleRowIndex: 0,
+    csvDelimiter: ',',
+    mapper: {
+      '$id': 0,
+      '1001': 1,
+      '1002': 2,
+    },
+  })
+})
+
+test('csv mapping missing header lists available headers', () => {
+  assert.throws(() => {
+    compileCSVImportMapping({
+      mode: 'addonly',
+      header: true,
+      dataStartRow: 2,
+      fields: [{ fieldId: 1001, header: 'missing' }],
+    }, ['客户名称', '手机号'])
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'INVALID_IMPORT_MAPPING')
+    assert.match(error.message, /missing/)
+    assert.ok(error.details?.suggestions?.some((item) => item.includes('客户名称')))
+    return true
+  })
+})

package/src/tests/entity_save_schema.test.ts

@@ -65,6 +65,46 @@ test('EntitySaveReqVO normalizes mechanical FieldVO defaults', () => {
   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({