@carthooks/arcubase-cli 0.1.3 → 0.1.5

package/src/runtime/execute.ts

@@ -5,6 +5,7 @@ import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http
 import { listModules, listModuleCommands, findCommand, findCommandSuggestions, type CommandScope } from './command_registry.js'
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js'
 import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
+import { renderUploadHelp, uploadLocalFile } from './upload.js'
 
 export type CommandExecutionSummary = {
   scope: CommandScope
@@ -16,13 +17,136 @@ export type CommandExecutionSummary = {
   scalarFlags: readonly string[]
 }
 
+type CustomUploadSummary = {
+  kind: 'upload'
+  status: number
+  data: ReturnType<typeof summarizeUploadResult>
+}
+
+type AppInventoryItem = {
+  id: string
+  name: string
+  entities: Array<{ id: string; name: string }>
+}
+
+function summarizeUploadResult(value: Awaited<ReturnType<typeof uploadLocalFile>>) {
+  return value
+}
+
+function parseJSONResponse(raw: string): unknown {
+  if (!raw) return null
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return raw
+  }
+}
+
+function unwrapResponseData(payload: unknown): unknown {
+  return isRecord(payload) && 'data' in payload ? payload.data : payload
+}
+
+function formatUpstreamError(payload: unknown): string {
+  if (typeof payload === 'string') {
+    return payload
+  }
+  if (isRecord(payload) && isRecord(payload.error) && typeof payload.error.message === 'string') {
+    return payload.error.message
+  }
+  return JSON.stringify(payload)
+}
+
+function extractApps(payload: unknown): Array<{ id: string; name: string }> {
+  const data = unwrapResponseData(payload)
+  if (!Array.isArray(data)) return []
+  return data
+    .filter((item): item is Record<string, unknown> => isRecord(item))
+    .filter((item) => item.id !== undefined && typeof item.name === 'string')
+    .map((item) => ({
+      id: String(item.id),
+      name: item.name as string,
+    }))
+}
+
+function extractEntities(payload: unknown): Array<{ id: string; name: string }> {
+  const data = unwrapResponseData(payload)
+  if (!Array.isArray(data)) return []
+  return data
+    .filter((item): item is Record<string, unknown> => isRecord(item))
+    .filter((item) => item.id !== undefined && typeof item.name === 'string')
+    .map((item) => ({
+      id: String(item.id),
+      name: item.name as string,
+    }))
+}
+
+async function executeAppInventory(runtimeEnv: RuntimeEnv, fetchImpl: typeof fetch) {
+  const appsResponse = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, '/apps'), {
+    method: 'GET',
+    headers: buildRequestHeaders(runtimeEnv),
+  })
+  const appsRaw = await appsResponse.text()
+  const appsPayload = parseJSONResponse(appsRaw)
+  if (!appsResponse.ok) {
+    throw new CLIError('UPSTREAM_REQUEST_FAILED', formatUpstreamError(appsPayload), 1)
+  }
+  if (isRecord(appsPayload) && appsPayload.error) {
+    throw new CLIError('UPSTREAM_BODY_ERROR', formatUpstreamError(appsPayload), 1, {
+      endpoint: '/apps',
+      method: 'GET',
+      upstreamError: appsPayload.error,
+    })
+  }
+  const apps = extractApps(appsPayload)
+  const items: AppInventoryItem[] = []
+  for (const app of apps) {
+    const entitiesResponse = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, `/apps/${encodeURIComponent(app.id)}/entities`), {
+      method: 'POST',
+      headers: {
+        ...buildRequestHeaders(runtimeEnv),
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({}),
+    })
+    const entitiesRaw = await entitiesResponse.text()
+    const entitiesPayload = parseJSONResponse(entitiesRaw)
+    if (!entitiesResponse.ok) {
+      throw new CLIError('UPSTREAM_REQUEST_FAILED', formatUpstreamError(entitiesPayload), 1)
+    }
+    if (isRecord(entitiesPayload) && entitiesPayload.error) {
+      throw new CLIError('UPSTREAM_BODY_ERROR', formatUpstreamError(entitiesPayload), 1, {
+        endpoint: `/apps/${app.id}/entities`,
+        method: 'POST',
+        upstreamError: entitiesPayload.error,
+      })
+    }
+    items.push({
+      ...app,
+      entities: extractEntities(entitiesPayload),
+    })
+  }
+  return {
+    kind: 'result',
+    commandPath: ['app', 'inventory'] as const,
+    status: 200,
+    data: {
+      apps: items,
+    },
+  }
+}
+
 export function renderRootHelp(scope: CommandScope): string {
   const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase'
+  const items = listModules(scope).map((item) => `  - ${item}`)
   return [
     `${binary} <module> <command> [flags]`,
     '',
+    ...(scope === 'admin'
+      ? ['use arcubase-admin for app, entity shell, and schema management', '']
+      : ['use arcubase for rows, search, selection actions, and bulk actions', '']),
     'modules:',
-    ...listModules(scope).map((item) => `  - ${item}`),
+    ...items,
+    ...(scope === 'user' ? ['','special commands:','  - upload <local-file>'] : []),
   ].join('\n')
 }
 
@@ -35,16 +159,30 @@ export function renderModuleHelp(scope: CommandScope, moduleName: string): strin
   return [
     `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} <command> [flags]`,
     '',
+    ...(scope === 'admin'
+      ? ['use arcubase-admin for app, entity shell, and schema management', '']
+      : ['use arcubase for rows, search, selection actions, and bulk actions', '']),
     'commands:',
     ...items.map((item) => `  - ${item.commandPath[1]}`),
   ].join('\n')
 }
 
+function buildUnknownCommandDetails(scope: CommandScope, moduleName: string, commandName: string): { suggestions?: string[]; reason?: string; hint?: string } | undefined {
+  const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`)
+  if (scope === 'admin' && moduleName === 'workflow' && suggestions.some((item) => item.startsWith('arcubase rows '))) {
+    return {
+      suggestions,
+      reason: `${moduleName} ${commandName} is not a valid command group; use arcubase rows for row operations`,
+      hint: `use: arcubase rows ${commandName}`,
+    }
+  }
+  return suggestions.length > 0 ? { suggestions } : undefined
+}
+
 export function renderCommandHelp(scope: CommandScope, moduleName: string, commandName: string): string {
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
-    const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`)
-    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, suggestions.length > 0 ? { suggestions } : undefined)
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName))
   }
   const docHints = [
     ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`),
@@ -58,6 +196,21 @@ export function renderCommandHelp(scope: CommandScope, moduleName: string, comma
     'query flags: --query-file',
     command.endpointParams.length ? `path flags: ${command.endpointParams.map((item) => `--${item.replace(/_/g, '-')}`).join(', ')}` : 'path flags: none',
     command.scalarParams.length ? `scalar flags: ${command.scalarParams.map((item) => `--${item.name.replace(/([A-Z])/g, '-$1').toLowerCase()}`).join(', ')}` : 'scalar flags: none',
+    ...(scope === 'admin' && moduleName === 'entity' && commandName === 'admin-save-entity'
+      ? [
+          'next step:',
+          '  - switch to arcubase for row operations',
+          '  - row insert: arcubase rows insert-entity --app-id <app_id> --entity-id <entity_id> --body-file insert.json',
+          '  - row query: arcubase rows query-entity --app-id <app_id> --entity-id <entity_id> --body-file query.json',
+        ]
+      : []),
+    ...(scope === 'admin' && moduleName === 'app' && commandName === 'inventory'
+      ? [
+          'purpose:',
+          '  - list all accessible apps and each app entity list in one call sequence',
+          '  - use this before asking the user for app_id',
+        ]
+      : []),
     ...(docHints.length > 0
       ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
       : []),
@@ -112,6 +265,171 @@ function isRecord(value: unknown): value is Record<string, any> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
 
+type EntityFieldInfo = {
+  id: number
+  type: string
+  label?: string
+}
+
+function extractEntityFields(payload: unknown): EntityFieldInfo[] {
+  const candidate = isRecord(payload) && isRecord(payload.data) ? payload.data : payload
+  if (!isRecord(candidate) || !Array.isArray(candidate.fields)) {
+    return []
+  }
+  return candidate.fields
+    .filter((item): item is Record<string, unknown> => isRecord(item))
+    .filter((item) => typeof item.id === 'number' && typeof item.type === 'string')
+    .map((item) => ({
+      id: item.id as number,
+      type: item.type as string,
+      label: typeof item.label === 'string' ? item.label : undefined,
+    }))
+}
+
+async function fetchEntityFields(
+  runtimeEnv: RuntimeEnv,
+  appId: string,
+  entityId: string,
+  fetchImpl: typeof fetch,
+): Promise<Map<number, EntityFieldInfo>> {
+  const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, `/entity/${encodeURIComponent(appId)}/${encodeURIComponent(entityId)}`), {
+    method: 'GET',
+    headers: buildRequestHeaders(runtimeEnv),
+  })
+  const raw = await response.text()
+  let parsedResponse: unknown = raw
+  try {
+    parsedResponse = raw ? JSON.parse(raw) : null
+  } catch {
+    parsedResponse = raw
+  }
+  if (!response.ok) {
+    throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1)
+  }
+  if (isRecord(parsedResponse) && parsedResponse.error) {
+    const upstreamError = parsedResponse.error
+    const upstreamMessage =
+      isRecord(upstreamError) && typeof upstreamError.message === 'string'
+        ? upstreamError.message
+        : typeof upstreamError === 'string'
+          ? upstreamError
+          : JSON.stringify(upstreamError)
+    throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
+      endpoint: `/entity/${appId}/${entityId}`,
+      method: 'GET',
+      upstreamError,
+    })
+  }
+  const fields = extractEntityFields(parsedResponse)
+  return new Map(fields.map((field) => [field.id, field]))
+}
+
+function looksLikeLocalFilePath(value: string): boolean {
+  return (
+    value.startsWith('./') ||
+    value.startsWith('../') ||
+    value.startsWith('/') ||
+    value.startsWith('~/') ||
+    /\.(pdf|png|jpe?g|gif|webp|bmp|svg|heic|txt|csv|xlsx?|docx?|pptx?|zip)$/i.test(value)
+  )
+}
+
+function isValidUploadEntry(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false
+  }
+  const hasUploadId = typeof value.upload_id === 'number' || typeof value.upload_id === 'string'
+  const hasAssetsId = typeof value.assets_id === 'number' || typeof value.assets_id === 'string'
+  return (hasUploadId || hasAssetsId) && typeof value.file === 'string' && typeof value.file_name === 'string'
+}
+
+async function validateFileFieldPayloads(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  runtimeEnv: RuntimeEnv,
+  flags: Record<string, string | boolean>,
+  body: unknown,
+  fetchImpl: typeof fetch,
+) {
+  if (!isRecord(body)) {
+    return
+  }
+  const container = command.functionName === 'updateEntityRow' ? body.data : body.fields
+  if (!isRecord(container)) {
+    return
+  }
+  const appId = flagValue(flags, 'app-id')
+  const entityId = flagValue(flags, 'entity-id')
+  if (!appId || !entityId) {
+    return
+  }
+  const fieldsById = await fetchEntityFields(runtimeEnv, appId, entityId, fetchImpl)
+  for (const [fieldIdText, value] of Object.entries(container)) {
+    if (!/^\d+$/.test(fieldIdText)) {
+      continue
+    }
+    const fieldId = Number(fieldIdText)
+    const field = fieldsById.get(fieldId)
+    if (!field || (field.type !== 'file' && field.type !== 'image')) {
+      continue
+    }
+    const fieldPath = command.functionName === 'updateEntityRow' ? `body.data.${fieldId}` : `body.fields.${fieldId}`
+    const fieldName = field.label ? `${field.label} (${field.type})` : `${field.type} field ${fieldId}`
+    if (typeof value === 'string') {
+      const guidance = looksLikeLocalFilePath(value)
+        ? `do not put a local file path directly into ${fieldName}; run "arcubase upload ${value}" first and use the returned data array as the field value`
+        : `${fieldName} must be an array returned by "arcubase upload <local-file>", not a string`
+      throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
+        operation: `${scope}.${command.module}.${command.functionName}`,
+        requestType: command.requestType ?? undefined,
+        issues: [{ path: fieldPath, message: guidance }],
+        docHints: [
+          { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+          { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        ],
+      })
+    }
+    if (isRecord(value)) {
+      const guidance = `${fieldName} must be an array. Run "arcubase upload <local-file>" and use the returned data array directly as the field value`
+      throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
+        operation: `${scope}.${command.module}.${command.functionName}`,
+        requestType: command.requestType ?? undefined,
+        issues: [{ path: fieldPath, message: guidance }],
+        docHints: [
+          { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+          { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        ],
+      })
+    }
+    if (!Array.isArray(value)) {
+      const guidance = `${fieldName} must be an array returned by "arcubase upload <local-file>"`
+      throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
+        operation: `${scope}.${command.module}.${command.functionName}`,
+        requestType: command.requestType ?? undefined,
+        issues: [{ path: fieldPath, message: guidance }],
+        docHints: [
+          { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+          { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        ],
+      })
+    }
+    for (const [index, item] of value.entries()) {
+      if (!isValidUploadEntry(item)) {
+        const guidance = `${fieldName} entries must include upload_id or assets_id plus file and file_name. Use "arcubase upload <local-file>" and copy the returned array item as-is`
+        throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
+          operation: `${scope}.${command.module}.${command.functionName}`,
+          requestType: command.requestType ?? undefined,
+          issues: [{ path: `${fieldPath}.${index}`, message: guidance }],
+          docHints: [
+            { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+            { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+          ],
+        })
+      }
+    }
+  }
+}
+
 function throwBodyValidationFailure(message: string, requestType: string, path: string, scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>) {
   throw new CLIError('BODY_VALIDATION_FAILED', message, 2, {
     operation: `${scope}.${command.module}.${command.functionName}`,
@@ -137,7 +455,7 @@ function validateActionSpecificBody(
     return
   }
 
-  if (command.module === 'workflow' && command.functionName === 'queryEntitySelection') {
+  if (command.module === 'rows' && command.functionName === 'queryEntitySelection') {
     const action = flagValue(flags, 'action')
     const selection = body.selection
     if (!isRecord(selection) || typeof selection.type !== 'string') {
@@ -151,7 +469,7 @@ function validateActionSpecificBody(
     if (action === 'query') {
       if (type === 'condition') {
         throwBodyValidationFailure(
-          'selection.type=condition is not supported for action=query; use selection.type=ids or selection.type=all, or use workflow query-entity for search conditions',
+          'selection.type=condition is not supported for action=query; use selection.type=ids or selection.type=all, or use rows query-entity for search conditions',
           command.requestType,
           'body.selection.type',
           scope,
@@ -186,8 +504,7 @@ function validateActionSpecificBody(
 export function summarizeCommand(scope: CommandScope, moduleName: string, commandName: string): CommandExecutionSummary {
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
-    const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`)
-    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, suggestions.length > 0 ? { suggestions } : undefined)
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName))
   }
   return {
     scope,
@@ -202,6 +519,31 @@ export function summarizeCommand(scope: CommandScope, moduleName: string, comman
 
 export async function executeCLI(scope: CommandScope, argv: string[], env?: RuntimeEnv, fetchImpl: typeof fetch = fetch): Promise<any> {
   const parsed = parseCLIArgs(argv)
+  if (scope === 'user' && parsed.commandTokens[0] === 'upload') {
+    if (hasFlag(parsed.flags, 'help') || parsed.commandTokens.length === 1) {
+      return { kind: 'help', text: renderUploadHelp() }
+    }
+    const sourcePath = parsed.commandTokens[1]
+    if (!sourcePath) {
+      throw new CLIError('UPLOAD_SOURCE_REQUIRED', 'upload requires a local file path', 2)
+    }
+    const runtimeEnv = env ?? loadRuntimeEnv(scope)
+    const data = await uploadLocalFile(
+      runtimeEnv,
+      sourcePath,
+      {
+        filename: flagValue(parsed.flags, 'filename'),
+        global: hasFlag(parsed.flags, 'global'),
+      },
+      fetchImpl,
+    )
+    return {
+      kind: 'result',
+      commandPath: ['upload', sourcePath],
+      status: 200,
+      data,
+    }
+  }
   if (parsed.commandTokens.length === 0) {
     return { kind: 'help', text: renderRootHelp(scope) }
   }
@@ -220,7 +562,10 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
 
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
-    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName))
+  }
+  if (scope === 'admin' && moduleName === 'app' && commandName === 'inventory') {
+    return executeAppInventory(runtimeEnv, fetchImpl)
   }
 
   const endpoint = normalizeExternalEndpoint(resolveEndpoint(command.endpoint, parsed.flags))
@@ -270,6 +615,10 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
     }
   }
 
+  if (scope === 'user' && (command.functionName === 'insertEntity' || command.functionName === 'updateEntityRow')) {
+    await validateFileFieldPayloads(scope, command, runtimeEnv, parsed.flags, validatedBody, fetchImpl)
+  }
+
   const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
     method: command.method,
     headers: {
@@ -303,11 +652,22 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
         : typeof parsedResponse.request_id === 'string'
           ? parsedResponse.request_id
           : undefined
+    const uploadBindFailure = upstreamMessage.includes('failed to bind upload to assets')
     throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
       endpoint,
       method: command.method,
       traceId,
       upstreamError,
+      ...(uploadBindFailure
+        ? {
+            reason: 'the row payload used a file/image upload entry, but Arcubase could not bind that upload into an asset record',
+            hint: 'verify the upload storage host is reachable from the Arcubase server, then rerun arcubase upload and retry the row insert/update',
+            docHints: [
+              { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+              { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+            ],
+          }
+        : {}),
     })
   }
   return {

package/src/runtime/upload.ts

@@ -0,0 +1,196 @@
+import fs from 'fs'
+import path from 'path'
+import { CLIError } from './errors.js'
+import type { RuntimeEnv } from './env.js'
+import { buildRequestHeaders, buildURL } from './http.js'
+
+type UploadTokenResponse = {
+  data?: {
+    id?: number | string
+    mode?: string
+    token_data?: {
+      dir?: string
+      policy?: string
+      host?: string
+      accessid?: string
+      signature?: string
+      x_amz_algorithm?: string
+      x_amz_credential?: string
+      x_amz_date?: string
+      x_amz_signature?: string
+    }
+  }
+  error?: unknown
+  trace_id?: string
+}
+
+export type ArcubaseUploadResult = {
+  upload_id: number | string
+  file: string
+  file_name: string
+  meta: Record<string, never>
+}
+
+function readUploadSource(sourcePath: string): { absolutePath: string; bytes: Buffer } {
+  const absolutePath = path.resolve(sourcePath)
+  if (!fs.existsSync(absolutePath)) {
+    throw new CLIError('UPLOAD_SOURCE_NOT_FOUND', `upload source file does not exist: ${sourcePath}`, 2)
+  }
+  const stat = fs.statSync(absolutePath)
+  if (!stat.isFile()) {
+    throw new CLIError('UPLOAD_SOURCE_INVALID', `upload source path must be a file: ${sourcePath}`, 2)
+  }
+  return {
+    absolutePath,
+    bytes: fs.readFileSync(absolutePath),
+  }
+}
+
+function parseJSONResponse(raw: string): unknown {
+  try {
+    return raw ? JSON.parse(raw) : null
+  } catch {
+    return raw
+  }
+}
+
+function requireTokenPayload(payload: UploadTokenResponse): NonNullable<UploadTokenResponse['data']> {
+  if (payload && typeof payload === 'object' && payload.error) {
+    const upstreamError = payload.error
+    const message =
+      typeof upstreamError === 'object' && upstreamError && 'message' in upstreamError && typeof (upstreamError as any).message === 'string'
+        ? (upstreamError as any).message
+        : typeof upstreamError === 'string'
+          ? upstreamError
+          : JSON.stringify(upstreamError)
+    throw new CLIError('UPSTREAM_BODY_ERROR', message, 1, {
+      endpoint: '/upload/token',
+      method: 'POST',
+      traceId: typeof payload.trace_id === 'string' ? payload.trace_id : undefined,
+      upstreamError,
+    })
+  }
+  if (!payload?.data || typeof payload.data !== 'object') {
+    throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response did not include data', 1)
+  }
+  return payload.data
+}
+
+export function renderUploadHelp(): string {
+  return [
+    'arcubase upload <local-file> [flags]',
+    '',
+    'purpose:',
+    '  - upload one local file through Arcubase',
+    '  - return a field value that can be used directly in file or image row payloads',
+    '',
+    'flags:',
+    '  --filename <name>   override the uploaded filename stored in Arcubase',
+    '  --global            request a global upload token instead of a tenant-scoped token',
+    '',
+    'result shape:',
+    '  - data is a JSON array',
+    '  - use that array directly as the value of a file or image field in insert/update payloads',
+    '',
+    'example:',
+    '  arcubase upload ./contract.pdf',
+    '  arcubase upload ./photo.jpg --filename lead-photo.jpg',
+    '',
+    'docs:',
+    '  - Uploads: /opt/arcubase-sdk/docs/runtime-reference/uploads.md',
+    '  - Row CRUD: /opt/arcubase-sdk/docs/runtime-reference/row-crud.md',
+    '  - File field: /opt/arcubase-sdk/docs/runtime-reference/entity-schema/file.md',
+    '  - Image field: /opt/arcubase-sdk/docs/runtime-reference/entity-schema/image.md',
+  ].join('\n')
+}
+
+export async function uploadLocalFile(
+  env: RuntimeEnv,
+  sourcePath: string,
+  options: {
+    filename?: string
+    global?: boolean
+  },
+  fetchImpl: typeof fetch = fetch,
+): Promise<ArcubaseUploadResult[]> {
+  const { absolutePath, bytes } = readUploadSource(sourcePath)
+  const filename = (options.filename && options.filename.trim()) || path.basename(absolutePath)
+
+  const tokenResponse = await fetchImpl(buildURL(env.ARCUBASE_BASE_URL, '/upload/token'), {
+    method: 'POST',
+    headers: {
+      ...buildRequestHeaders(env),
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      global: Boolean(options.global),
+    }),
+  })
+
+  const tokenRaw = await tokenResponse.text()
+  const tokenParsed = parseJSONResponse(tokenRaw)
+  if (!tokenResponse.ok) {
+    throw new CLIError('UPLOAD_TOKEN_REQUEST_FAILED', typeof tokenParsed === 'string' ? tokenParsed : JSON.stringify(tokenParsed), 1, {
+      endpoint: '/upload/token',
+      method: 'POST',
+    })
+  }
+
+  const tokenData = requireTokenPayload(tokenParsed as UploadTokenResponse)
+  if (tokenData.mode !== 'aliyun-oss' && tokenData.mode !== 's3-post-policy') {
+    throw new CLIError('UPLOAD_MODE_UNSUPPORTED', `unsupported upload mode: ${String(tokenData.mode || '')}`, 1)
+  }
+  if (!tokenData.token_data?.dir || !tokenData.token_data.policy || !tokenData.token_data.host) {
+    throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response is missing required token_data fields', 1)
+  }
+  if (tokenData.id === undefined || tokenData.id === null || tokenData.id === '') {
+    throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response is missing id', 1)
+  }
+
+  const form = new FormData()
+  form.append('key', `${tokenData.token_data.dir}${filename}`)
+  form.append('policy', tokenData.token_data.policy)
+  if (tokenData.mode === 'aliyun-oss') {
+    if (!tokenData.token_data.accessid || !tokenData.token_data.signature) {
+      throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response is missing required token_data fields', 1)
+    }
+    form.append('OSSAccessKeyId', tokenData.token_data.accessid)
+    form.append('success_action_status', '200')
+    form.append('signature', tokenData.token_data.signature)
+  } else {
+    if (
+      !tokenData.token_data.x_amz_algorithm ||
+      !tokenData.token_data.x_amz_credential ||
+      !tokenData.token_data.x_amz_date ||
+      !tokenData.token_data.x_amz_signature
+    ) {
+      throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response is missing required s3 token_data fields', 1)
+    }
+    form.append('x-amz-algorithm', tokenData.token_data.x_amz_algorithm)
+    form.append('x-amz-credential', tokenData.token_data.x_amz_credential)
+    form.append('x-amz-date', tokenData.token_data.x_amz_date)
+    form.append('x-amz-signature', tokenData.token_data.x_amz_signature)
+  }
+  form.append('file', new Blob([new Uint8Array(bytes)]), filename)
+
+  const uploadResponse = await fetchImpl(tokenData.token_data.host, {
+    method: 'POST',
+    body: form,
+  })
+  const uploadRaw = await uploadResponse.text()
+  if (!uploadResponse.ok) {
+    throw new CLIError('UPLOAD_TRANSFER_FAILED', uploadRaw || `upload failed with status ${uploadResponse.status}`, 1, {
+      endpoint: tokenData.token_data.host,
+      method: 'POST',
+    })
+  }
+
+  return [
+    {
+      upload_id: tokenData.id,
+      file: filename,
+      file_name: filename,
+      meta: {},
+    },
+  ]
+}