@carthooks/arcubase-cli 0.1.12 → 0.1.15

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
@@ -121,8 +125,9 @@ export function renderCommandHelp(scope: CommandScope, moduleName: string, comma
       : []),
     ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'create'
       ? [
-          'body-json example:',
-          '  - {"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}]},"list_options":{}}}',
+          'body-json examples:',
+          `  - full access: ${JSON.stringify(buildFullAccessRuleBody())}`,
+          `  - hide field: ${JSON.stringify(buildHiddenFieldAccessRuleBody())}`,
           'success requires:',
           '  - result.enabled must be true',
           '  - options.user_scope[].type is "user" for tenant users',
@@ -141,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 optionally overrides the imported app name',
+          '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 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}`)]
       : []),
@@ -231,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)
@@ -242,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'
@@ -536,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,
       },
@@ -554,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')
 }
@@ -567,6 +629,28 @@ function isAccessRuleUpdateCommand(scope: CommandScope, command: NonNullable<Ret
 }
 
 function buildAccessRuleShapeHint(userId = 2188889901) {
+  return buildHiddenFieldAccessRuleBody(userId)
+}
+
+function buildFullAccessRuleBody(userId = 2188889977) {
+  return {
+    name: 'Admin full access',
+    enabled: true,
+    type: 'form',
+    options: {
+      user_scope: [{ type: 'user', id: userId }],
+      policy: {
+        key: 'custom',
+        actions: ['view', 'add', 'edit', 'delete'],
+        all_fields_read: true,
+        all_fields_write: true,
+      },
+      list_options: {},
+    },
+  }
+}
+
+function buildHiddenFieldAccessRuleBody(userId = 2188889901) {
   return {
     name: 'Sales read write',
     enabled: true,
@@ -585,6 +669,13 @@ function buildAccessRuleShapeHint(userId = 2188889901) {
   }
 }
 
+function buildAccessRuleCreateToolCall(body: unknown) {
+  return {
+    command: 'access-rule create',
+    args: ['--app-id', '<app_id>', '--table-id', '<table_id>', '--body-json', JSON.stringify(body)],
+  }
+}
+
 function buildAssignUsersValidationDetails(
   scope: CommandScope,
   command: NonNullable<ReturnType<typeof findCommand>>,
@@ -618,7 +709,7 @@ function buildAssignUsersValidationDetails(
   }
 }
 
-function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'shapeHint' | 'commonMistakes' | 'suggestions'> {
+function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'retryToolCalls' | 'shapeHint' | 'commonMistakes' | 'suggestions'> {
   if (requestType === 'EntitySaveReqVO' || requestType === 'AppCreateEntityReqVO') {
     return {
       shapeHint: {
@@ -667,7 +758,7 @@ function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'shapeHin
             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,
           },
@@ -730,7 +821,15 @@ function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'shapeHin
     }
   }
   if (requestType === 'AppIngressCreateReqVO' || requestType === 'AppIngressUpdateReqVO') {
+    const retryToolCalls = [
+      buildAccessRuleCreateToolCall(buildFullAccessRuleBody()),
+      buildAccessRuleCreateToolCall(buildHiddenFieldAccessRuleBody()),
+    ]
     return {
+      retryToolCalls,
+      suggestions: [
+        'next arcubase-admin-cli input: retryToolCalls[0] for full access or retryToolCalls[1] for hidden-field access',
+      ],
       shapeHint: buildAccessRuleShapeHint(),
       commonMistakes: [
         'use options.policy, not top-level permissions',
@@ -769,15 +868,21 @@ function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'shapeHin
       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"}}\'',
       ],
     }
   }
@@ -1233,6 +1338,72 @@ function unwrapData(value: unknown): unknown {
   return current
 }
 
+function numericFieldKeys(fields: unknown): string[] {
+  if (!isRecord(fields)) return []
+  return Object.keys(fields).filter((key) => /^\d+$/.test(key)).sort((left, right) => Number(left) - Number(right))
+}
+
+function permitFieldId(permit: unknown): string | undefined {
+  if (!isRecord(permit) || typeof permit.key !== 'string') return undefined
+  const match = /^:(\d+)$/.exec(permit.key)
+  return match?.[1]
+}
+
+function rowFieldPermits(value: unknown): Array<Record<string, unknown>> {
+  const data = unwrapData(value)
+  const fieldPermits = isRecord(data) && isRecord(data.fieldPermits) ? data.fieldPermits : undefined
+  return fieldPermits && Array.isArray(fieldPermits.fields)
+    ? fieldPermits.fields.filter((item): item is Record<string, unknown> => isRecord(item))
+    : []
+}
+
+function buildRowValueEvidence(command: NonNullable<ReturnType<typeof findCommand>>, responseBody: unknown): Record<string, unknown> | undefined {
+  if (command.scope !== 'user' || command.commandPath[0] !== 'row') return undefined
+  const action = command.commandPath[1]
+  const data = unwrapData(responseBody)
+  const rules = [
+    'current row values come only from row query fields or row get record.fields',
+    'table schema fields[].value and default_value_mode are schema defaults, not returned row values',
+    'a field id absent from returned row fields has no row-value evidence',
+    'read visibility status is fieldPermits read:false; FIELD_PERMISSION_REQUIRED is only a write preflight error',
+  ]
+  if (action === 'get') {
+    const record = isRecord(data) && isRecord(data.record) ? data.record : undefined
+    const returnedFieldIds = numericFieldKeys(record?.fields)
+    const permits = rowFieldPermits(responseBody)
+    const permitFieldIds = permits.map(permitFieldId).filter((id): id is string => Boolean(id))
+    const deniedReadFieldIds = permits
+      .filter((permit) => permit.read === false)
+      .map(permitFieldId)
+      .filter((id): id is string => Boolean(id))
+      .sort((left, right) => Number(left) - Number(right))
+    const notReturnedFieldIds = permitFieldIds
+      .filter((id) => !returnedFieldIds.includes(id))
+      .sort((left, right) => Number(left) - Number(right))
+    return {
+      source: 'row get record.fields',
+      returnedFieldIds,
+      notReturnedFieldIds,
+      deniedReadFieldIds,
+      absentFieldMeaning: 'not returned to current user; no row-value evidence',
+      rules,
+    }
+  }
+  if (action === 'query') {
+    const items = isRecord(data) && Array.isArray(data.items) ? data.items : []
+    return {
+      source: 'row query items[].fields',
+      rows: items.filter((item): item is Record<string, unknown> => isRecord(item)).map((item) => ({
+        rowId: item.id,
+        returnedFieldIds: numericFieldKeys(item.fields),
+      })),
+      absentFieldMeaning: 'not returned to current user; no row-value evidence',
+      rules,
+    }
+  }
+  return undefined
+}
+
 function requiredRowAction(command: NonNullable<ReturnType<typeof findCommand>>, flags: Record<string, string | boolean>): string | undefined {
   if (command.commandPath[0] !== 'row') return undefined
   switch (command.commandPath[1]) {
@@ -1484,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,
@@ -1621,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)
@@ -1632,7 +2054,7 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
     if (error instanceof CLIError && error.code === 'INVALID_BODY_JSON' && command.requestType) {
       throw new CLIError(
         'INVALID_BODY_JSON',
-        `body json is invalid for ${scope}.${command.commandPath.join(' ')}; fix JSON syntax, then use the canonical ${command.requestType} shape from docs/types`,
+        `body json is invalid for ${scope}.${command.commandPath.join(' ')}; retry with retryToolCalls[0] or retryToolCalls[1] when present`,
         2,
         buildBodyValidationDetails(scope, command, command.requestType, [{ path: 'body', message: 'invalid JSON syntax' }], runtimeEnv),
       )
@@ -1782,10 +2204,12 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
         : {}),
     })
   }
+  const rowValueEvidence = buildRowValueEvidence(command, parsedResponse)
   return {
     kind: 'result',
     commandPath: command.commandPath,
     status: response.status,
     data: parsedResponse,
+    ...(rowValueEvidence ? { rowValueEvidence } : {}),
   }
 }

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 }
+}