@carthooks/arcubase-cli 0.1.3 → 0.1.4

package/bundle/arcubase.mjs

@@ -5276,8 +5276,8 @@ function getErrorMap() {
 
 // node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path, errorMaps, issueData } = params;
-  const fullPath = [...path, ...issueData.path || []];
+  const { data, path: path2, errorMaps, issueData } = params;
+  const fullPath = [...path2, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -5393,11 +5393,11 @@ var errorUtil;
 
 // node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path, key) {
+  constructor(parent, value, path2, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path;
+    this._path = path2;
     this._key = key;
   }
   get path() {
@@ -10372,54 +10372,53 @@ var examplesIndexDocHint = {
   title: "Examples index",
   file: "/opt/arcubase-sdk/docs/runtime-reference/examples/README.md"
 };
-var omsExampleDocHint = {
-  title: "OMS example 01",
-  file: "/opt/arcubase-sdk/docs/runtime-reference/examples/oms-01/README.md"
-};
 var docHintIndex = {
   AppCreateByTenantsReqVO: [
     { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
-    examplesIndexDocHint,
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   AppCreateEntityReqVO: [
     { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
-    examplesIndexDocHint,
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   EntitySaveReqVO: [
     { title: "Entity schema", file: "/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   EntityQueryReqVO: [
     { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
     { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   EntityUpdateReqVO: [
     { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
-    omsExampleDocHint
+    { title: "Uploads", file: "/opt/arcubase-sdk/docs/runtime-reference/uploads.md" },
+    examplesIndexDocHint
   ],
   EntitySelectionActionReqVO: [
     { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   InsertReqVO: [
     { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
-    omsExampleDocHint
+    { title: "Uploads", file: "/opt/arcubase-sdk/docs/runtime-reference/uploads.md" },
+    examplesIndexDocHint
   ],
   EntityBulkUpdateReqVO: [
     { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   "EntityInvokeBatchOperatorReqVO & InvokeRequestVO": [
-    { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" }
+    { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
+    examplesIndexDocHint
   ],
   "{ policy_id: string selection: any }": [
-    { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" }
+    { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
+    examplesIndexDocHint
   ],
   "{ policy_id: string selection: any tag_names: string[] }": [
-    { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" }
+    { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
+    examplesIndexDocHint
   ]
 };
 function getTypeHints(typeName) {
@@ -10452,52 +10451,56 @@ function getDocHints(typeName) {
 var commandDocHintIndex = {
   "admin.app.createAppByTenants": [
     { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
-    examplesIndexDocHint,
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   "admin.app.createEntity": [
     { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   "admin.entity.adminGetEntityInfo": [
     { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   "admin.entity.adminSaveEntity": [
     { title: "Entity schema", file: "/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md" },
-    omsExampleDocHint
+    { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
+    { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
+    examplesIndexDocHint
   ],
   "user.workflow.insertEntity": [
     { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
-    omsExampleDocHint
+    { title: "Uploads", file: "/opt/arcubase-sdk/docs/runtime-reference/uploads.md" },
+    examplesIndexDocHint
   ],
   "user.workflow.queryEntity": [
     { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
-    omsExampleDocHint
+    { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
+    examplesIndexDocHint
   ],
   "user.workflow.getEntityRow": [
     { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   "user.workflow.updateEntityRow": [
     { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
-    omsExampleDocHint
+    { title: "Uploads", file: "/opt/arcubase-sdk/docs/runtime-reference/uploads.md" },
+    examplesIndexDocHint
   ],
   "user.workflow.queryEntitySelection": [
     { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   "user.workflow.deleteEntityRow": [
     { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   "user.workflow.restoreEntityRow": [
     { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ],
   "user.entity.updateEntityBulk": [
     { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
-    omsExampleDocHint
+    examplesIndexDocHint
   ]
 };
 function getCommandDocHints(operation) {
@@ -10506,14 +10509,156 @@ function getCommandDocHints(operation) {
   return commandDocHintIndex[key] ?? [];
 }
 
+// src/runtime/upload.ts
+import fs2 from "fs";
+import path from "path";
+function readUploadSource(sourcePath) {
+  const absolutePath = path.resolve(sourcePath);
+  if (!fs2.existsSync(absolutePath)) {
+    throw new CLIError("UPLOAD_SOURCE_NOT_FOUND", `upload source file does not exist: ${sourcePath}`, 2);
+  }
+  const stat = fs2.statSync(absolutePath);
+  if (!stat.isFile()) {
+    throw new CLIError("UPLOAD_SOURCE_INVALID", `upload source path must be a file: ${sourcePath}`, 2);
+  }
+  return {
+    absolutePath,
+    bytes: fs2.readFileSync(absolutePath)
+  };
+}
+function parseJSONResponse(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return raw;
+  }
+}
+function requireTokenPayload(payload) {
+  if (payload && typeof payload === "object" && payload.error) {
+    const upstreamError = payload.error;
+    const message = typeof upstreamError === "object" && upstreamError && "message" in upstreamError && typeof upstreamError.message === "string" ? upstreamError.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 : void 0,
+      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;
+}
+function renderUploadHelp() {
+  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");
+}
+async function uploadLocalFile(env, sourcePath, options, fetchImpl = fetch) {
+  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);
+  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 === void 0 || 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: {}
+    }
+  ];
+}
+
 // src/runtime/execute.ts
 function renderRootHelp(scope) {
   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");
 }
 function renderModuleHelp(scope, moduleName) {
@@ -10525,15 +10670,26 @@ function renderModuleHelp(scope, moduleName) {
   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, moduleName, commandName) {
+  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 } : void 0;
+}
 function renderCommandHelp(scope, moduleName, commandName) {
   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 } : void 0);
+    throw new CLIError("UNKNOWN_COMMAND", `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName));
   }
   const docHints = [
     ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`),
@@ -10547,6 +10703,12 @@ function renderCommandHelp(scope, moduleName, commandName) {
     "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");
 }
@@ -10594,13 +10756,139 @@ function buildScalarQuery(command, flags) {
 function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function throwBodyValidationFailure(message, requestType, path, scope, command) {
+function extractEntityFields(payload) {
+  const candidate = isRecord2(payload) && isRecord2(payload.data) ? payload.data : payload;
+  if (!isRecord2(candidate) || !Array.isArray(candidate.fields)) {
+    return [];
+  }
+  return candidate.fields.filter((item) => isRecord2(item)).filter((item) => typeof item.id === "number" && typeof item.type === "string").map((item) => ({
+    id: item.id,
+    type: item.type,
+    label: typeof item.label === "string" ? item.label : void 0
+  }));
+}
+async function fetchEntityFields(runtimeEnv, appId, entityId, fetchImpl) {
+  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 = 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 (isRecord2(parsedResponse) && parsedResponse.error) {
+    const upstreamError = parsedResponse.error;
+    const upstreamMessage = isRecord2(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) {
+  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) {
+  if (!isRecord2(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, command, runtimeEnv, flags, body, fetchImpl) {
+  if (!isRecord2(body)) {
+    return;
+  }
+  const container = command.functionName === "updateEntityRow" ? body.data : body.fields;
+  if (!isRecord2(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 ?? void 0,
+        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 (isRecord2(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 ?? void 0,
+        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 ?? void 0,
+        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 ?? void 0,
+          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, requestType, path2, scope, command) {
   throw new CLIError("BODY_VALIDATION_FAILED", message, 2, {
     operation: `${scope}.${command.module}.${command.functionName}`,
     requestType,
     issues: [
       {
-        path,
+        path: path2,
         message
       }
     ],
@@ -10655,6 +10943,31 @@ function validateActionSpecificBody(scope, command, flags, body) {
 }
 async function executeCLI(scope, argv, env, fetchImpl = fetch) {
   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 runtimeEnv2 = env ?? loadRuntimeEnv(scope);
+    const data = await uploadLocalFile(
+      runtimeEnv2,
+      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) };
   }
@@ -10671,7 +10984,7 @@ async function executeCLI(scope, argv, env, fetchImpl = fetch) {
   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));
   const scalarQuery = buildScalarQuery(command, parsed.flags);
@@ -10718,6 +11031,9 @@ async function executeCLI(scope, argv, env, fetchImpl = fetch) {
       }
     }
   }
+  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 : void 0), {
     method: command.method,
     headers: {
@@ -10739,11 +11055,20 @@ async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     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 : void 0;
+    const uploadBindFailure = upstreamMessage.includes("failed to bind upload to assets");
     throw new CLIError("UPSTREAM_BODY_ERROR", upstreamMessage, 1, {
       endpoint,
       method: command.method,
       traceId,
-      upstreamError
+      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/dist/runtime/errors.d.ts

@@ -17,6 +17,7 @@ export type CLIErrorDetails = {
     tsHints?: CLITSTypeHint[];
     docHints?: CLIDocHint[];
     reason?: string;
+    hint?: string;
     endpoint?: string;
     method?: string;
     traceId?: string;

package/dist/runtime/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAC7B,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;IACzB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAA;gBAEtB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,EAAE,OAAO,CAAC,EAAE,eAAe;IAQlF,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAC7B,OAAO,CAAC,EAAE,aAAa,EAAE,CAAA;IACzB,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAA;gBAEtB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAI,EAAE,OAAO,CAAC,EAAE,eAAe;IAQlF,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC"}

package/dist/runtime/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAwE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAI/H,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CAC/B,CAAA;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQ1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAYhF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAsBtG;AAyHD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,uBAAuB,CAetH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAoHrI"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAwE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAK/H,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CAC/B,CAAA;AAYD,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAa1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAehF;AAcD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CA6BtG;AA8RD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,uBAAuB,CActH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CA4JrI"}