@carthooks/arcubase-cli 0.1.2 → 0.1.4

package/src/runtime/errors.ts

@@ -8,12 +8,24 @@ export type CLITSTypeHint = {
   file: string
 }
 
+export type CLIDocHint = {
+  title: string
+  file: string
+}
+
 export type CLIErrorDetails = {
   operation?: string
   requestType?: string
   issues?: CLIValidationIssue[]
   tsHints?: CLITSTypeHint[]
+  docHints?: CLIDocHint[]
   reason?: string
+  hint?: string
+  endpoint?: string
+  method?: string
+  traceId?: string
+  upstreamError?: unknown
+  suggestions?: string[]
 }
 
 export class CLIError extends Error {

package/src/runtime/execute.ts

@@ -2,9 +2,10 @@ import { parseCLIArgs, hasFlag, flagValue } from './argv.js'
 import { loadRuntimeEnv, type RuntimeEnv } from './env.js'
 import { CLIError } from './errors.js'
 import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js'
-import { listModules, listModuleCommands, findCommand, type CommandScope } from './command_registry.js'
+import { listModules, listModuleCommands, findCommand, findCommandSuggestions, type CommandScope } from './command_registry.js'
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js'
-import { getBodySchema, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
+import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
+import { renderUploadHelp, uploadLocalFile } from './upload.js'
 
 export type CommandExecutionSummary = {
   scope: CommandScope
@@ -16,41 +17,88 @@ export type CommandExecutionSummary = {
   scalarFlags: readonly string[]
 }
 
+type CustomUploadSummary = {
+  kind: 'upload'
+  status: number
+  data: ReturnType<typeof summarizeUploadResult>
+}
+
+function summarizeUploadResult(value: Awaited<ReturnType<typeof uploadLocalFile>>) {
+  return value
+}
+
 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 row CRUD, search, selection actions, and bulk actions', '']),
     'modules:',
-    ...listModules(scope).map((item) => `  - ${item}`),
+    ...items,
+    ...(scope === 'user' ? ['','special commands:','  - upload <local-file>'] : []),
   ].join('\n')
 }
 
 export function renderModuleHelp(scope: CommandScope, moduleName: string): string {
   const items = listModuleCommands(scope, moduleName)
   if (items.length === 0) {
-    throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2)
+    const suggestions = findCommandSuggestions(moduleName, '').map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`)
+    throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2, suggestions.length > 0 ? { suggestions } : undefined)
   }
   return [
     `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} <command> [flags]`,
     '',
+    ...(scope === 'admin'
+      ? ['use arcubase-admin for app, entity shell, and schema management', '']
+      : ['use arcubase for row CRUD, 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 workflow '))) {
+    return {
+      suggestions,
+      reason: `${moduleName} ${commandName} is a row operation, not an arcubase-admin command`,
+      hint: `use: arcubase ${moduleName} ${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) {
-    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName))
   }
+  const docHints = [
+    ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`),
+    ...(command.requestType ? getDocHints(command.requestType) : []),
+  ].filter((item, index, list) => list.findIndex((candidate) => candidate.file === item.file) === index)
   return [
     `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} ${commandName}`,
     `method: ${command.method}`,
     `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
     command.requestType ? `body: ${command.requestType} via --body-file` : 'body: none',
+    '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 workflow insert-entity --app-id <app_id> --entity-id <entity_id> --body-file insert.json',
+          '  - row query: arcubase workflow query-entity --app-id <app_id> --entity-id <entity_id> --body-file query.json',
+        ]
+      : []),
+    ...(docHints.length > 0
+      ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
+      : []),
   ].join('\n')
 }
 
@@ -98,10 +146,250 @@ function buildScalarQuery(command: ReturnType<typeof findCommand>, flags: Record
   return Object.keys(out).length > 0 ? out : undefined
 }
 
+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}`,
+    requestType,
+    issues: [
+      {
+        path,
+        message,
+      },
+    ],
+    tsHints: getTypeHints(requestType),
+    docHints: getDocHints(requestType),
+  })
+}
+
+function validateActionSpecificBody(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  flags: Record<string, string | boolean>,
+  body: unknown,
+) {
+  if (!isRecord(body) || !command.requestType) {
+    return
+  }
+
+  if (command.module === 'workflow' && command.functionName === 'queryEntitySelection') {
+    const action = flagValue(flags, 'action')
+    const selection = body.selection
+    if (!isRecord(selection) || typeof selection.type !== 'string') {
+      return
+    }
+
+    const type = selection.type
+    const condition = isRecord(selection.condition) ? selection.condition : undefined
+    const conditionKeys = condition ? Object.keys(condition).filter((key) => key !== 'selectAll') : []
+
+    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',
+          command.requestType,
+          'body.selection.type',
+          scope,
+          command,
+        )
+      }
+      return
+    }
+
+    if ((action === 'archive' || action === 'delete' || action === 'batch_print') && type === 'all') {
+      throwBodyValidationFailure(
+        `selection.type=all is not supported for action=${action}; use ids or condition`,
+        command.requestType,
+        'body.selection.type',
+        scope,
+        command,
+      )
+    }
+
+    if ((action === 'archive' || action === 'delete') && type === 'condition' && conditionKeys.length === 0) {
+      throwBodyValidationFailure(
+        `selection.condition for action=${action} requires at least one q, tab, or filter_* key in addition to selectAll`,
+        command.requestType,
+        'body.selection.condition',
+        scope,
+        command,
+      )
+    }
+  }
+}
+
 export function summarizeCommand(scope: CommandScope, moduleName: string, commandName: string): CommandExecutionSummary {
   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))
   }
   return {
     scope,
@@ -114,8 +402,33 @@ export function summarizeCommand(scope: CommandScope, moduleName: string, comman
   }
 }
 
-export async function executeCLI(scope: CommandScope, argv: string[], env: RuntimeEnv = loadRuntimeEnv(scope), fetchImpl: typeof fetch = fetch): Promise<any> {
+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) }
   }
@@ -130,9 +443,11 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
     return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName) }
   }
 
+  const runtimeEnv = env ?? loadRuntimeEnv(scope)
+
   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))
   }
 
   const endpoint = normalizeExternalEndpoint(resolveEndpoint(command.endpoint, parsed.flags))
@@ -140,6 +455,7 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
   const fileQuery = loadQueryFromFlags(parsed.flags)
   const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) }
   const body = loadBodyFromFlags(parsed.flags)
+  let validatedBody = body
 
   if (command.requestType) {
     if (body === undefined) {
@@ -161,9 +477,12 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
               message: issue.message,
             })),
             tsHints: getTypeHints(command.requestType),
+            docHints: getDocHints(command.requestType),
           }
         )
       }
+      validatedBody = parsedBody.data
+      validateActionSpecificBody(scope, command, parsed.flags, validatedBody)
     } else {
       const unsupportedReason = getUnsupportedBodySchemaReason(command.requestType)
       if (unsupportedReason) {
@@ -172,19 +491,23 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
           requestType: command.requestType,
           reason: unsupportedReason,
           tsHints: getTypeHints(command.requestType),
+          docHints: getDocHints(command.requestType),
         })
       }
     }
   }
 
-  const headers = buildRequestHeaders(env)
-  const response = await fetchImpl(buildURL(env.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
+  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: {
-      ...headers,
+      ...buildRequestHeaders(runtimeEnv),
       'Content-Type': 'application/json',
     },
-    body: body === undefined || command.method === 'GET' ? undefined : JSON.stringify(body),
+    body: validatedBody === undefined || command.method === 'GET' ? undefined : JSON.stringify(validatedBody),
   })
 
   const raw = await response.text()
@@ -197,6 +520,38 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
   if (!response.ok) {
     throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1)
   }
+  if (parsedResponse && typeof parsedResponse === 'object' && 'error' in parsedResponse && parsedResponse.error) {
+    const upstreamError = parsedResponse.error
+    const upstreamMessage =
+      typeof upstreamError === 'object' && upstreamError && 'message' in upstreamError && typeof upstreamError.message === 'string'
+        ? upstreamError.message
+        : typeof upstreamError === 'string'
+          ? upstreamError
+          : JSON.stringify(upstreamError)
+    const traceId =
+      typeof parsedResponse.trace_id === 'string'
+        ? parsedResponse.trace_id
+        : 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 {
     kind: 'result',
     commandPath: command.commandPath,