@carthooks/arcubase-cli 0.1.2 → 0.1.4

package/bundle/arcubase.mjs

@@ -4738,6 +4738,41 @@ function listModules(scope) {
 function listModuleCommands(scope, moduleName) {
   return listCommands(scope).filter((item) => item.commandPath[0] === moduleName);
 }
+function levenshtein(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i += 1) dp[i][0] = i;
+  for (let j = 0; j <= b.length; j += 1) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i += 1) {
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dp[a.length][b.length];
+}
+function findCommandSuggestions(moduleName, commandName, limit = 3) {
+  const suggestions = [];
+  for (const scope of ["admin", "user"]) {
+    for (const command of listCommands(scope)) {
+      const [candidateModule, candidateCommand] = command.commandPath;
+      const moduleScore = candidateModule === moduleName ? 0 : levenshtein(candidateModule, moduleName || "");
+      const commandScore = candidateCommand === commandName ? 0 : levenshtein(candidateCommand, commandName || "");
+      const score = commandScore * 3 + moduleScore;
+      suggestions.push({
+        scope,
+        moduleName: candidateModule,
+        commandName: candidateCommand,
+        binary: scope === "admin" ? "arcubase-admin" : "arcubase",
+        score
+      });
+    }
+  }
+  return suggestions.sort((a, b) => a.score - b.score || a.binary.localeCompare(b.binary) || a.moduleName.localeCompare(b.moduleName) || a.commandName.localeCompare(b.commandName)).slice(0, limit);
+}
 
 // src/runtime/body_loader.ts
 import fs from "fs";
@@ -5241,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
@@ -5358,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() {
@@ -9661,10 +9696,671 @@ var typeIndex = {
   }
 };
 
+// src/runtime/entity_save_schema.ts
+var simpleFieldTypes = [
+  "text",
+  "textarea",
+  "number",
+  "datetime",
+  "boolean",
+  "button",
+  "address",
+  "datasets",
+  "department",
+  "departments",
+  "divider",
+  "file",
+  "image",
+  "location",
+  "member",
+  "members",
+  "signature",
+  "tags",
+  "workflow_status",
+  "mobile"
+];
+var enumFieldTypes = ["select", "selects", "radio", "checkbox", "status"];
+var relationFieldTypes = ["linkto", "relation", "query"];
+var strictFieldTypes = /* @__PURE__ */ new Set([
+  ...simpleFieldTypes,
+  ...enumFieldTypes,
+  ...relationFieldTypes,
+  "formula",
+  "lookup",
+  "relationfield",
+  "rollup",
+  "serialnumber",
+  "subform"
+]);
+var relationTypeSchema = external_exports.union([external_exports.literal("entity"), external_exports.literal("aggregation")]);
+var linkModeSchema = external_exports.union([external_exports.literal("manual"), external_exports.literal("auto")]);
+var linkStructureSchema = external_exports.union([external_exports.literal("single"), external_exports.literal("multiple")]);
+var enumItemSchema = external_exports.object({
+  key: external_exports.union([external_exports.number(), external_exports.string()]).optional(),
+  value: external_exports.string().min(1)
+}).passthrough();
+var statusItemSchema = external_exports.object({
+  key: external_exports.union([external_exports.number(), external_exports.string()]).optional(),
+  code: external_exports.union([external_exports.number(), external_exports.string()]),
+  value: external_exports.string().min(1)
+}).passthrough();
+var sortConfigSchema = external_exports.object({
+  column: external_exports.string().min(1),
+  order: external_exports.union([external_exports.literal("asc"), external_exports.literal("desc")])
+}).strict();
+var relationOptionsSchema = external_exports.object({
+  entity_id: external_exports.number().int().positive(),
+  app_id: external_exports.number().int().positive(),
+  type: relationTypeSchema,
+  show_fields: external_exports.array(external_exports.number().int().positive()).optional(),
+  condition: external_exports.record(external_exports.string(), external_exports.any()).optional(),
+  sorts: external_exports.array(sortConfigSchema).optional(),
+  queryFields: external_exports.array(external_exports.number().int().positive()).optional(),
+  subform_id: external_exports.number().int().positive().optional()
+}).strict();
+var lookupRelationSchema = external_exports.object({
+  local_linkto_field_id: external_exports.number().int().min(1001),
+  target_field_id: external_exports.number().int().min(1001),
+  target_field_type: external_exports.string().min(1)
+}).strict();
+var relationFieldRelationSchema = external_exports.object({
+  app_id: external_exports.number().int().positive(),
+  entity_id: external_exports.number().int().positive(),
+  type: relationTypeSchema.optional(),
+  show_fields: external_exports.array(external_exports.number().int().positive()).optional(),
+  condition: external_exports.record(external_exports.string(), external_exports.any()).optional(),
+  sorts: external_exports.array(sortConfigSchema).optional(),
+  queryFields: external_exports.array(external_exports.number().int().positive()).optional(),
+  subform_id: external_exports.number().int().positive().optional()
+}).strict();
+var formulaSchema = external_exports.object({
+  code: external_exports.string().min(1),
+  jsonlogic: external_exports.record(external_exports.string(), external_exports.any())
+}).strict();
+var serialPartBuildinStringSchema = external_exports.object({
+  mode: external_exports.literal("buildin"),
+  type: external_exports.literal("string"),
+  options: external_exports.object({
+    value: external_exports.string()
+  }).strict()
+}).strict();
+var serialPartBuildinDateSchema = external_exports.object({
+  mode: external_exports.literal("buildin"),
+  type: external_exports.literal("date"),
+  options: external_exports.object({
+    format: external_exports.string().optional(),
+    perdefined: external_exports.boolean().optional(),
+    perdefinedFormat: external_exports.string().optional()
+  }).strict().refine((value) => Boolean(value.format || value.perdefinedFormat), {
+    message: "date serial part requires format or perdefinedFormat"
+  })
+}).strict();
+var serialPartBuildinSerialSchema = external_exports.object({
+  mode: external_exports.literal("buildin"),
+  type: external_exports.literal("serial"),
+  options: external_exports.object({
+    length: external_exports.number().int().min(1),
+    lenfixed: external_exports.boolean().optional(),
+    random: external_exports.boolean().optional(),
+    reset: external_exports.string().optional()
+  }).strict()
+}).strict();
+var serialPartFieldSchema = external_exports.object({
+  mode: external_exports.literal("field"),
+  field_id: external_exports.number().int().min(1001)
+}).passthrough();
+var serialPartSchema = external_exports.union([
+  serialPartBuildinStringSchema,
+  serialPartBuildinDateSchema,
+  serialPartBuildinSerialSchema,
+  serialPartFieldSchema
+]);
+var fieldCommonShape = {
+  id: external_exports.number().int().min(1001),
+  label: external_exports.string().min(1),
+  required: external_exports.boolean(),
+  unique: external_exports.boolean(),
+  editable: external_exports.boolean(),
+  visible: external_exports.boolean(),
+  show_label: external_exports.boolean(),
+  scannable: external_exports.boolean(),
+  default_value_mode: external_exports.number(),
+  description: external_exports.string(),
+  value: external_exports.any(),
+  number_decimal: external_exports.number().int().min(0),
+  depends: external_exports.array(external_exports.number().int().min(1001)),
+  key: external_exports.string(),
+  code_index: external_exports.boolean(),
+  transfers: external_exports.array(external_exports.any()).nullable()
+};
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function cloneJSON(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function makeSimpleFieldSchema(type) {
+  return external_exports.object({
+    ...fieldCommonShape,
+    type: external_exports.literal(type),
+    options: external_exports.record(external_exports.string(), external_exports.any()).nullable(),
+    children: external_exports.null()
+  }).strict();
+}
+function makeEnumFieldSchema(type) {
+  const itemSchema = type === "status" ? statusItemSchema : enumItemSchema;
+  return external_exports.object({
+    ...fieldCommonShape,
+    type: external_exports.literal(type),
+    options: external_exports.object({
+      options: external_exports.object({
+        items: external_exports.array(itemSchema).min(1)
+      }).passthrough()
+    }).passthrough(),
+    children: external_exports.null()
+  }).strict();
+}
+var simpleFieldSchemas = simpleFieldTypes.map((type) => makeSimpleFieldSchema(type));
+var enumFieldSchemas = enumFieldTypes.map((type) => makeEnumFieldSchema(type));
+var formulaFieldSchema = external_exports.object({
+  ...fieldCommonShape,
+  type: external_exports.literal("formula"),
+  options: external_exports.object({
+    formula: formulaSchema
+  }).passthrough(),
+  children: external_exports.null()
+}).strict();
+var relationFieldSchemas = relationFieldTypes.map(
+  (type) => external_exports.object({
+    ...fieldCommonShape,
+    type: external_exports.literal(type),
+    options: external_exports.object({
+      relation: relationOptionsSchema,
+      mode: linkModeSchema.optional(),
+      structure: linkStructureSchema.optional(),
+      multiple: external_exports.boolean().optional(),
+      backfill: external_exports.array(external_exports.object({
+        id: external_exports.number().int().min(1001),
+        local_id: external_exports.number().int().min(1001)
+      }).strict()).optional(),
+      addValue: external_exports.boolean().optional(),
+      placeholder: external_exports.string().optional()
+    }).passthrough(),
+    children: external_exports.null()
+  }).strict()
+);
+var lookupFieldSchema = external_exports.object({
+  ...fieldCommonShape,
+  type: external_exports.literal("lookup"),
+  options: external_exports.object({
+    relation: lookupRelationSchema
+  }).passthrough(),
+  children: external_exports.null()
+}).strict();
+var relationFieldFieldSchema = external_exports.object({
+  ...fieldCommonShape,
+  type: external_exports.literal("relationfield"),
+  options: external_exports.object({
+    relation: relationFieldRelationSchema
+  }).passthrough(),
+  children: external_exports.null()
+}).strict();
+var rollupFieldSchema = external_exports.object({
+  ...fieldCommonShape,
+  type: external_exports.literal("rollup"),
+  options: external_exports.object({
+    relation: lookupRelationSchema,
+    aggregation_formula: formulaSchema
+  }).passthrough(),
+  children: external_exports.null()
+}).strict();
+var serialNumberFieldSchema = external_exports.object({
+  ...fieldCommonShape,
+  type: external_exports.literal("serialnumber"),
+  options: external_exports.object({
+    parts: external_exports.array(serialPartSchema).min(1)
+  }).passthrough(),
+  children: external_exports.null()
+}).strict();
+var genericFieldSchema = external_exports.object({
+  ...fieldCommonShape,
+  type: external_exports.string().min(1).refine((value) => !strictFieldTypes.has(value), {
+    message: "known field type must use dedicated schema"
+  }),
+  options: external_exports.record(external_exports.string(), external_exports.any()).nullable(),
+  children: external_exports.null()
+}).strict();
+var baseFieldSchemaVariants = [
+  ...simpleFieldSchemas,
+  ...enumFieldSchemas,
+  ...relationFieldSchemas,
+  formulaFieldSchema,
+  lookupFieldSchema,
+  relationFieldFieldSchema,
+  rollupFieldSchema,
+  serialNumberFieldSchema,
+  genericFieldSchema
+];
+var BaseFieldSchema = external_exports.union(baseFieldSchemaVariants);
+var SubformFieldSchema = external_exports.lazy(
+  () => external_exports.object({
+    ...fieldCommonShape,
+    type: external_exports.literal("subform"),
+    options: external_exports.record(external_exports.string(), external_exports.any()).nullable(),
+    children: external_exports.array(BaseFieldSchema),
+    layout: external_exports.array(external_exports.array(external_exports.number().int().min(1001))).optional()
+  }).strict()
+);
+var FieldVOSchema = external_exports.lazy(
+  () => external_exports.union([
+    SubformFieldSchema,
+    BaseFieldSchema
+  ])
+);
+function normalizeEntitySaveInput(value) {
+  if (!isRecord(value)) {
+    return value;
+  }
+  const entity = cloneJSON(value);
+  if (entity.layout === null) {
+    entity.layout = [];
+  }
+  if (entity.current_serial === null) {
+    delete entity.current_serial;
+  }
+  if (isRecord(entity.options)) {
+    if (entity.options.Buttons === null) {
+      entity.options.Buttons = [];
+    }
+    if (entity.options.CustomActions === null) {
+      entity.options.CustomActions = [];
+    }
+    if (entity.options.FrontendEvents === null) {
+      entity.options.FrontendEvents = [];
+    }
+    if (entity.options.misc === null) {
+      entity.options.misc = {};
+    }
+    if (isRecord(entity.options.TitleFormat)) {
+      if (entity.options.TitleFormat.Fields === null) {
+        entity.options.TitleFormat.Fields = [];
+      }
+      if (entity.options.TitleFormat.Parts === null) {
+        entity.options.TitleFormat.Parts = [];
+      }
+    }
+  }
+  return entity;
+}
+function collectAllFieldIds(fields) {
+  const out = [];
+  for (const field of fields) {
+    out.push(field.id);
+    if (field.type === "subform" && Array.isArray(field.children)) {
+      for (const child of field.children) {
+        out.push(child.id);
+      }
+    }
+  }
+  return out;
+}
+function collectTopLevelFieldIds(fields) {
+  return fields.map((field) => field.id);
+}
+function extractFormulaFieldIds(value) {
+  if (!value || typeof value !== "string") return [];
+  const ids = [...value.matchAll(/:(\d+)\]\]/g)].map((match) => Number(match[1]));
+  return ids.filter((id) => Number.isInteger(id) && id > 0);
+}
+var EntitySaveReqVOBaseSchema = external_exports.object({
+  app_id: external_exports.number().optional(),
+  current_serial: EntitySerialUpdaterVOSchema.optional(),
+  field_id_seq: external_exports.number().int(),
+  fields: external_exports.array(FieldVOSchema),
+  id: external_exports.number().optional(),
+  layout: external_exports.array(external_exports.array(external_exports.number().int().min(1001))).optional(),
+  name: external_exports.string().optional(),
+  options: EntityOptionsSchema.optional(),
+  prototypes: external_exports.array(external_exports.number()).optional(),
+  schema_version: external_exports.number().optional(),
+  workflow_enabled: external_exports.boolean().optional()
+}).strict().superRefine((entity, ctx) => {
+  const fields = entity.fields;
+  const topLevelIds = new Set(collectTopLevelFieldIds(fields));
+  const allIds = collectAllFieldIds(fields);
+  const allIdSet = /* @__PURE__ */ new Set();
+  for (const id of allIds) {
+    if (allIdSet.has(id)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["fields"],
+        message: `duplicate field id: ${id}`
+      });
+    }
+    allIdSet.add(id);
+  }
+  const maxFieldId = allIds.length > 0 ? Math.max(...allIds) : 1e3;
+  if (entity.field_id_seq <= maxFieldId) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["field_id_seq"],
+      message: `field_id_seq must be greater than max field id ${maxFieldId}`
+    });
+  }
+  for (const [rowIndex, row] of (entity.layout ?? []).entries()) {
+    for (const [colIndex, fieldId] of row.entries()) {
+      if (!topLevelIds.has(fieldId)) {
+        ctx.addIssue({
+          code: external_exports.ZodIssueCode.custom,
+          path: ["layout", rowIndex, colIndex],
+          message: `layout references unknown top-level field id ${fieldId}`
+        });
+      }
+    }
+  }
+  for (const [fieldIndex, field] of fields.entries()) {
+    if (field.type !== "subform" && field.children !== null) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["fields", fieldIndex, "children"],
+        message: "only subform field can define children"
+      });
+    }
+    if (field.type === "subform") {
+      const childIds = new Set((field.children ?? []).map((child) => child.id));
+      for (const [rowIndex, row] of (field.layout ?? []).entries()) {
+        for (const [colIndex, fieldId] of row.entries()) {
+          if (!childIds.has(fieldId)) {
+            ctx.addIssue({
+              code: external_exports.ZodIssueCode.custom,
+              path: ["fields", fieldIndex, "layout", rowIndex, colIndex],
+              message: `subform layout references non-child field id ${fieldId}`
+            });
+          }
+        }
+      }
+    }
+    if (field.type === "lookup" || field.type === "rollup") {
+      const localLinktoFieldId = field.options?.relation?.local_linkto_field_id;
+      if (typeof localLinktoFieldId === "number") {
+        const target = fields.find((item) => item.id === localLinktoFieldId);
+        if (!target || target.type !== "linkto") {
+          ctx.addIssue({
+            code: external_exports.ZodIssueCode.custom,
+            path: ["fields", fieldIndex, "options", "relation", "local_linkto_field_id"],
+            message: "local_linkto_field_id must reference a linkto field"
+          });
+        }
+      }
+    }
+    if (field.type === "formula" || field.type === "rollup") {
+      const formulaCode = field.type === "formula" ? field.options?.formula?.code : field.options?.aggregation_formula?.code;
+      for (const referencedFieldId of extractFormulaFieldIds(formulaCode)) {
+        if (!allIdSet.has(referencedFieldId)) {
+          ctx.addIssue({
+            code: external_exports.ZodIssueCode.custom,
+            path: ["fields", fieldIndex, "options"],
+            message: `formula references unknown field id ${referencedFieldId}`
+          });
+        }
+      }
+    }
+  }
+});
+var EntitySaveReqVOSchemaOverride = external_exports.preprocess(normalizeEntitySaveInput, EntitySaveReqVOBaseSchema);
+var queryOrderSchema = external_exports.object({
+  column: external_exports.string().min(1),
+  order: external_exports.string().min(1)
+}).strict();
+var AppCreateByTenantsReqVOSchemaOverride = external_exports.object({
+  icon_color: external_exports.string().optional(),
+  icon_name: external_exports.string().optional(),
+  name: external_exports.string().min(1).max(20)
+}).strict();
+var EntityQueryReqVOSchemaOverride = external_exports.object({
+  limit: external_exports.number().int().positive().optional(),
+  offset: external_exports.number().int().min(0).optional(),
+  policy_id: external_exports.string().optional(),
+  search: external_exports.record(external_exports.string(), external_exports.any()).optional(),
+  sorts: external_exports.array(queryOrderSchema).optional(),
+  view_mode: external_exports.string().optional(),
+  viewMode: external_exports.never().optional(),
+  withSubForm: external_exports.boolean().optional()
+}).strict();
+var InsertReqVOSchemaOverride = external_exports.object({
+  policy_id: external_exports.string().optional(),
+  fields: external_exports.record(external_exports.string(), external_exports.any())
+}).strict().superRefine((body, ctx) => {
+  for (const key of Object.keys(body.fields ?? {})) {
+    if (!/^\d+$/.test(key)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["fields", key],
+        message: "row fields must use numeric field ids as keys"
+      });
+    }
+  }
+});
+var EntityUpdateReqVOSchemaOverride = external_exports.object({
+  changed_fields: external_exports.array(external_exports.number().int().positive()).min(1),
+  data: external_exports.record(external_exports.string(), external_exports.any()),
+  policy_id: external_exports.string().optional(),
+  tags: external_exports.array(external_exports.string()).optional(),
+  fields: external_exports.never().optional()
+}).strict().superRefine((body, ctx) => {
+  const dataFieldIds = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(body.data ?? {})) {
+    if (!/^\d+$/.test(key)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["data", key],
+        message: "row data must use numeric field ids as keys"
+      });
+      continue;
+    }
+    dataFieldIds.add(Number(key));
+  }
+  for (const [index, fieldId] of body.changed_fields.entries()) {
+    if (!dataFieldIds.has(fieldId)) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["changed_fields", index],
+        message: `changed_fields references ${fieldId}, but data does not contain that field id`
+      });
+    }
+  }
+});
+var entitySelectionSortSchema = external_exports.object({
+  column: external_exports.string().min(1),
+  order: external_exports.string().min(1)
+}).strict();
+var entitySelectionIdsSchema = external_exports.object({
+  type: external_exports.literal("ids"),
+  ids: external_exports.array(external_exports.number().int().positive()).min(1),
+  length: external_exports.number().int().positive().optional(),
+  sorts: external_exports.array(entitySelectionSortSchema).optional(),
+  condition: external_exports.record(external_exports.string(), external_exports.any()).optional()
+}).strict().superRefine((selection, ctx) => {
+  if (selection.length !== void 0 && selection.length !== selection.ids.length) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: ["length"],
+      message: "length must match ids.length when provided"
+    });
+  }
+});
+var entitySelectionConditionSchema = external_exports.object({
+  type: external_exports.literal("condition"),
+  length: external_exports.number().int().positive(),
+  condition: external_exports.record(external_exports.string(), external_exports.any()).superRefine((condition, ctx) => {
+    if (!Object.keys(condition).length) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        message: "condition selection requires a non-empty condition object"
+      });
+      return;
+    }
+    if (condition.selectAll !== true) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        path: ["selectAll"],
+        message: "condition selection must set selectAll to true"
+      });
+    }
+    const filterKeys = Object.keys(condition).filter((key) => key !== "selectAll");
+    if (filterKeys.length === 0) {
+      return;
+    }
+    const hasSupportedQueryKey = filterKeys.some((key) => key === "q" || key === "tab" || key.startsWith("filter_"));
+    if (!hasSupportedQueryKey) {
+      ctx.addIssue({
+        code: external_exports.ZodIssueCode.custom,
+        message: "condition selection extra keys must use q, tab, or filter_*"
+      });
+    }
+  }),
+  sorts: external_exports.array(entitySelectionSortSchema).optional(),
+  ids: external_exports.array(external_exports.number().int().positive()).optional()
+}).strict();
+var entitySelectionAllSchema = external_exports.object({
+  type: external_exports.literal("all"),
+  length: external_exports.number().int().positive().optional(),
+  ids: external_exports.array(external_exports.number().int().positive()).optional(),
+  condition: external_exports.record(external_exports.string(), external_exports.any()).optional(),
+  sorts: external_exports.array(entitySelectionSortSchema).optional()
+}).strict();
+var entitySelectionSchema = external_exports.union([
+  entitySelectionIdsSchema,
+  entitySelectionConditionSchema,
+  entitySelectionAllSchema
+]);
+var entitySelectionLooseSchema = external_exports.union([
+  entitySelectionSchema,
+  entitySelectionAllSchema
+]);
+var EntitySelectionActionReqVOSchemaOverride = external_exports.lazy(
+  () => external_exports.object({
+    limit: external_exports.number().int().positive().optional(),
+    offset: external_exports.number().int().min(0).optional(),
+    policy_id: external_exports.string().optional(),
+    selection: entitySelectionSchema
+  }).strict()
+);
+var bulkUpdateActionSchema = external_exports.object({
+  type: external_exports.string().min(1),
+  value: external_exports.any().optional(),
+  text_search: external_exports.string().optional(),
+  text_replace: external_exports.string().optional(),
+  text_append: external_exports.string().optional(),
+  text_prepend: external_exports.string().optional(),
+  number_add: external_exports.number().optional(),
+  number_mul: external_exports.number().optional(),
+  number_sub: external_exports.number().optional(),
+  datetime_add: external_exports.number().optional(),
+  datetime_sub: external_exports.number().optional()
+}).strict().superRefine((action, ctx) => {
+  switch (action.type) {
+    case "set":
+      if (!("value" in action)) {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["value"], message: "set action requires value" });
+      }
+      break;
+    case "text_replace":
+      if (!action.text_search) {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["text_search"], message: "text_replace requires text_search" });
+      }
+      if (!action.text_replace) {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["text_replace"], message: "text_replace requires text_replace" });
+      }
+      break;
+    case "text_append":
+      if (!action.text_append) {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["text_append"], message: "text_append requires text_append" });
+      }
+      break;
+    case "text_prepend":
+      if (!action.text_prepend) {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["text_prepend"], message: "text_prepend requires text_prepend" });
+      }
+      break;
+    case "number_add":
+      if (typeof action.number_add !== "number") {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["number_add"], message: "number_add requires number_add" });
+      }
+      break;
+    case "number_sub":
+      if (typeof action.number_sub !== "number") {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["number_sub"], message: "number_sub requires number_sub" });
+      }
+      break;
+    case "number_mul":
+      if (typeof action.number_mul !== "number") {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["number_mul"], message: "number_mul requires number_mul" });
+      }
+      break;
+    case "datetime_add":
+      if (typeof action.datetime_add !== "number") {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["datetime_add"], message: "datetime_add requires datetime_add" });
+      }
+      break;
+    case "datetime_sub":
+      if (typeof action.datetime_sub !== "number") {
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["datetime_sub"], message: "datetime_sub requires datetime_sub" });
+      }
+      break;
+    case "datetime_now":
+    case "formula":
+      break;
+    default:
+      ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: ["type"], message: `unsupported bulk update action type: ${action.type}` });
+  }
+});
+var EntityBulkUpdateReqVOSchemaOverride = external_exports.object({
+  policy_id: external_exports.string().optional(),
+  selection: entitySelectionSchema,
+  fields: external_exports.array(external_exports.object({
+    id: external_exports.number().int().min(1001),
+    action: bulkUpdateActionSchema
+  }).strict()).min(1)
+}).strict();
+var EntityTagsSelectionReqVOSchemaOverride = external_exports.object({
+  policy_id: external_exports.string(),
+  selection: entitySelectionSchema
+}).strict();
+var EntityTagsBatchReqVOSchemaOverride = external_exports.object({
+  policy_id: external_exports.string(),
+  selection: entitySelectionSchema,
+  tag_names: external_exports.array(external_exports.string().min(1)).min(1)
+}).strict();
+var EntityInvokeBatchOperatorReqVOSchemaOverride = external_exports.object({
+  id: external_exports.string().min(1),
+  data: external_exports.object({
+    action_id: external_exports.string().min(1),
+    policy_id: external_exports.string().optional(),
+    selection: entitySelectionLooseSchema
+  }).strict(),
+  params: external_exports.record(external_exports.string(), external_exports.any()).optional()
+}).strict();
+
 // src/runtime/zod_registry.ts
+var schemaOverrides = {
+  AppCreateByTenantsReqVO: AppCreateByTenantsReqVOSchemaOverride,
+  EntityBulkUpdateReqVO: EntityBulkUpdateReqVOSchemaOverride,
+  "EntityInvokeBatchOperatorReqVO & InvokeRequestVO": EntityInvokeBatchOperatorReqVOSchemaOverride,
+  EntityQueryReqVO: EntityQueryReqVOSchemaOverride,
+  EntitySaveReqVO: EntitySaveReqVOSchemaOverride,
+  EntitySelectionActionReqVO: EntitySelectionActionReqVOSchemaOverride,
+  "{ policy_id: string selection: any }": EntityTagsSelectionReqVOSchemaOverride,
+  "{ policy_id: string selection: any tag_names: string[] }": EntityTagsBatchReqVOSchemaOverride,
+  EntityUpdateReqVO: EntityUpdateReqVOSchemaOverride,
+  InsertReqVO: InsertReqVOSchemaOverride
+};
 function getBodySchema(typeName) {
   const name = String(typeName || "").trim();
   if (!name) return null;
+  if (schemaOverrides[name]) {
+    return schemaOverrides[name];
+  }
   return bodySchemas[name] ?? null;
 }
 function getUnsupportedBodySchemaReason(typeName) {
@@ -9672,6 +10368,59 @@ function getUnsupportedBodySchemaReason(typeName) {
   if (!name) return null;
   return unsupportedBodySchemas[name] ?? null;
 }
+var examplesIndexDocHint = {
+  title: "Examples index",
+  file: "/opt/arcubase-sdk/docs/runtime-reference/examples/README.md"
+};
+var docHintIndex = {
+  AppCreateByTenantsReqVO: [
+    { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
+    examplesIndexDocHint
+  ],
+  AppCreateEntityReqVO: [
+    { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
+    examplesIndexDocHint
+  ],
+  EntitySaveReqVO: [
+    { title: "Entity schema", file: "/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md" },
+    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" },
+    examplesIndexDocHint
+  ],
+  EntityUpdateReqVO: [
+    { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
+    { 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" },
+    examplesIndexDocHint
+  ],
+  InsertReqVO: [
+    { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
+    { 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" },
+    examplesIndexDocHint
+  ],
+  "EntityInvokeBatchOperatorReqVO & InvokeRequestVO": [
+    { 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" },
+    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" },
+    examplesIndexDocHint
+  ]
+};
 function getTypeHints(typeName) {
   const name = String(typeName || "").trim();
   if (!name) return [];
@@ -9694,41 +10443,273 @@ function getTypeHints(typeName) {
   }
   return out;
 }
+function getDocHints(typeName) {
+  const name = String(typeName || "").trim();
+  if (!name) return [];
+  return docHintIndex[name] ?? [];
+}
+var commandDocHintIndex = {
+  "admin.app.createAppByTenants": [
+    { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
+    examplesIndexDocHint
+  ],
+  "admin.app.createEntity": [
+    { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
+    examplesIndexDocHint
+  ],
+  "admin.entity.adminGetEntityInfo": [
+    { title: "Table lifecycle", file: "/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md" },
+    examplesIndexDocHint
+  ],
+  "admin.entity.adminSaveEntity": [
+    { title: "Entity schema", file: "/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md" },
+    { 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" },
+    { 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" },
+    { 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" },
+    examplesIndexDocHint
+  ],
+  "user.workflow.updateEntityRow": [
+    { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
+    { 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" },
+    examplesIndexDocHint
+  ],
+  "user.workflow.deleteEntityRow": [
+    { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
+    examplesIndexDocHint
+  ],
+  "user.workflow.restoreEntityRow": [
+    { title: "Row CRUD", file: "/opt/arcubase-sdk/docs/runtime-reference/row-crud.md" },
+    examplesIndexDocHint
+  ],
+  "user.entity.updateEntityBulk": [
+    { title: "Search and bulk actions", file: "/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md" },
+    examplesIndexDocHint
+  ]
+};
+function getCommandDocHints(operation) {
+  const key = String(operation || "").trim();
+  if (!key) return [];
+  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) {
   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 } : void 0);
   }
   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) {
-    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"
+    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");
 }
 function coerceScalar(value, typeText) {
@@ -9772,8 +10753,221 @@ function buildScalarQuery(command, flags) {
   }
   return Object.keys(out).length > 0 ? out : void 0;
 }
-async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl = fetch) {
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+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: path2,
+        message
+      }
+    ],
+    tsHints: getTypeHints(requestType),
+    docHints: getDocHints(requestType)
+  });
+}
+function validateActionSpecificBody(scope, command, flags, body) {
+  if (!isRecord2(body) || !command.requestType) {
+    return;
+  }
+  if (command.module === "workflow" && command.functionName === "queryEntitySelection") {
+    const action = flagValue(flags, "action");
+    const selection = body.selection;
+    if (!isRecord2(selection) || typeof selection.type !== "string") {
+      return;
+    }
+    const type = selection.type;
+    const condition = isRecord2(selection.condition) ? selection.condition : void 0;
+    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
+      );
+    }
+  }
+}
+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) };
   }
@@ -9787,15 +10981,17 @@ async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl =
   if (hasFlag(parsed.flags, "help")) {
     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));
   const scalarQuery = buildScalarQuery(command, parsed.flags);
   const fileQuery = loadQueryFromFlags(parsed.flags);
   const query = { ...scalarQuery ?? {}, ...fileQuery ?? {} };
   const body = loadBodyFromFlags(parsed.flags);
+  let validatedBody = body;
   if (command.requestType) {
     if (body === void 0) {
       throw new CLIError("MISSING_BODY_FILE", `command requires --body-file for ${command.requestType}`, 2);
@@ -9815,10 +11011,13 @@ async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl =
               path: issue.path.length > 0 ? `body.${issue.path.join(".")}` : "body",
               message: issue.message
             })),
-            tsHints: getTypeHints(command.requestType)
+            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) {
@@ -9826,19 +11025,22 @@ async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl =
           operation: `${scope}.${command.module}.${command.functionName}`,
           requestType: command.requestType,
           reason: unsupportedReason,
-          tsHints: getTypeHints(command.requestType)
+          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 : void 0), {
+  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: {
-      ...headers,
+      ...buildRequestHeaders(runtimeEnv),
       "Content-Type": "application/json"
     },
-    body: body === void 0 || command.method === "GET" ? void 0 : JSON.stringify(body)
+    body: validatedBody === void 0 || command.method === "GET" ? void 0 : JSON.stringify(validatedBody)
   });
   const raw = await response.text();
   let parsedResponse = raw;
@@ -9849,6 +11051,26 @@ async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl =
   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 : 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,
+      ...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,