velocious 1.0.457 → 1.0.459

package/README.md

@@ -378,6 +378,8 @@ export default new Configuration({
 `frontendModels` entries must be `FrontendModelBaseResource` subclasses. Built-in CRUD/find/index/serialize behavior lives in the base class, and app resources override only the pieces they actually need.
 Resource-level index customization should prefer `indexQuery()` or the pagination/search/sort hooks over replacing `records()`, so built-in pluck and aggregate count support can keep using the same query. See [`docs/frontend-model-resources.md`](docs/frontend-model-resources.md) for the resource extension points.
 
+Custom class- and instance-level commands are declared via `collectionCommands` / `memberCommands`. Each entry is a plain camelCase method name, or a `{name, args?, returnType?}` object that types the command's arguments and response — e.g. `memberCommands: ["suspend", {name: "refresh", args: [{name: "age", type: "number"}], returnType: "string"}]`. See [`docs/frontend-model-resources.md#custom-commands`](docs/frontend-model-resources.md#custom-commands).
+
 Resources expose the full CRUD ability set (`create`, `destroy`, `read`, `update`) by default. To restrict the API surface — for example to a read-only resource — declare an explicit subset:
 
 ```js

package/build/configuration-types.js

@@ -304,8 +304,8 @@
  * @property {string[]} [abilities] - Ability action list (camelCase action names). Defaults to `["read"]` for `find` and `index` when omitted.
  * @property {Record<string, FrontendModelAttachmentConfiguration>} [attachments] - Attachment helpers keyed by attachment name.
  * @property {string[]} [commands] - Legacy built-in command names (`index`, `find`, `create`, `update`, `destroy`, `attach`, `download`, `url`).
- * @property {string[]} [collectionCommands] - Custom collection commands as camelCase method names. The runtime derives the kebab-case command slug from each name.
- * @property {string[]} [memberCommands] - Custom member commands as camelCase method names. The runtime derives the kebab-case command slug from each name.
+ * @property {Array<FrontendModelResourceCustomCommand>} [collectionCommands] - Custom collection commands. Each entry is a camelCase method name, or a `{name, args?, returnType?}` object declaring typed arguments and/or a response type. The runtime derives the kebab-case command slug from the name.
+ * @property {Array<FrontendModelResourceCustomCommand>} [memberCommands] - Custom member commands. Each entry is a camelCase method name, or a `{name, args?, returnType?}` object declaring typed arguments and/or a response type. The runtime derives the kebab-case command slug from the name.
  * @property {string[]} [builtInCollectionCommands] - Built-in collection command names (`index`, `create`).
  * @property {string[]} [builtInMemberCommands] - Built-in member command names (`find`, `update`, `destroy`, `attach`, `download`, `url`).
  * @property {string[]} [relationships] - Relationship names to expose in frontend models. Type and target model are inferred from the backend model's registered relationships.
@@ -313,12 +313,28 @@
  * @property {FrontendModelResourceServerConfiguration} [server] - Optional legacy backend behavior overrides for built-in frontend actions.
  */
 
+/**
+ * Object form of a custom command entry, declaring its typed arguments and/or
+ * response type alongside the command name.
+ * @typedef {object} FrontendModelResourceCustomCommandObject
+ * @property {string} name - camelCase command method name.
+ * @property {Array<{name: string, type: string}>} [args] - Typed command arguments; each generates a named, typed method parameter mapped positionally into the command payload. `type` is a JSDoc type string.
+ * @property {string} [returnType] - JSDoc type for the command response. When set, the generated method is typed `Promise<returnType>` instead of `Promise<Record<string, ?>>`. Emitted verbatim into the generated frontend model, so it must resolve there.
+ */
+
+/**
+ * A custom command entry: a plain camelCase method name, or an object declaring
+ * typed args and/or a response type.
+ * @typedef {string | FrontendModelResourceCustomCommandObject} FrontendModelResourceCustomCommand
+ */
+
 /**
  * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands"> & {
  *   abilities: FrontendModelResourceAbilitiesConfiguration
  *   builtInCollectionCommands: Record<string, string>
  *   builtInMemberCommands: Record<string, string>
  *   collectionCommands: Record<string, string>
+ *   commandMetadata: Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>
  *   memberCommands: Record<string, string>
  * }} NormalizedFrontendModelResourceConfiguration
  */

package/build/current.js

@@ -47,7 +47,7 @@ export default class Current {
 
   /**
    * Runs tenant.
-   * @returns {?} - Current tenant.
+   * @returns {Record<string, unknown> | undefined} - Current tenant.
    */
   static tenant() {
     try {
@@ -61,7 +61,7 @@ export default class Current {
 
   /**
    * Runs set tenant.
-   * @param {?} tenant - Tenant.
+   * @param {Record<string, unknown>} tenant - Tenant.
    * @returns {void} - No return value.
    */
   static setTenant(tenant) {
@@ -70,7 +70,7 @@ export default class Current {
 
   /**
    * Runs with tenant.
-   * @param {?} tenant - Tenant.
+   * @param {Record<string, unknown>} tenant - Tenant.
    * @param {() => Promise<?>} callback - Callback.
    * @returns {Promise<?>} - Callback result.
    */

package/build/database/migration/index.js

@@ -6,6 +6,8 @@
  * @property {?} [default] - Default value for the column.
  * @property {object} [foreignKey] - Foreign key definition for the column.
  * @property {boolean | {unique: boolean}} [index] - Whether to add an index (optionally unique).
+ * @property {number} [limit] - Alias for maxLength (varchar length limit) on string-like columns.
+ * @property {number} [maxLength] - Maximum length for string-like columns (e.g. varchar length).
  * @property {boolean} [null] - Whether the column allows null values.
  * @property {boolean} [primaryKey] - Whether the column is a primary key.
  * @property {boolean} [unique] - Whether the column enforces uniqueness.

package/build/database/record/index.js

@@ -1678,7 +1678,7 @@ class VelociousDatabaseRecord {
 
   /**
    * Declares a tenant-aware database identifier resolver for this model class.
-   * @param {string | ((args: {modelClass: typeof VelociousDatabaseRecord, tenant: ?}) => string | undefined)} databaseIdentifierOrResolver - Static identifier or resolver.
+   * @param {string | ((args: {modelClass: typeof VelociousDatabaseRecord, tenant: Record<string, unknown>}) => string | undefined)} databaseIdentifierOrResolver - Static identifier or resolver.
    * @returns {void} - No return value.
    */
   static switchesTenantDatabase(databaseIdentifierOrResolver) {

package/build/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -288,6 +288,7 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     }
     const collectionCommands = modelConfig.collectionCommands
     const memberCommands = modelConfig.memberCommands
+    const commandMetadata = modelConfig.commandMetadata || {}
     const builtInCollectionCommandsAreDefault = builtInCollectionCommands.create === "create" && builtInCollectionCommands.index === "index"
     const builtInMemberCommandsAreDefault = builtInMemberCommands.attach === "attach"
       && builtInMemberCommands.destroy === "destroy"
@@ -460,35 +461,39 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     }
 
     for (const methodName of Object.keys(collectionCommands)) {
+      const signature = this.customCommandMethodSignature({commandMetadata, methodName})
+
       fileContent += "\n"
       fileContent += "  /**\n"
       fileContent += `   * Runs ${methodName}.\n`
-      fileContent += "   * @param {...FrontendModelAttributeValue} commandArguments - Custom command arguments.\n"
-      fileContent += "   * @returns {Promise<Record<string, FrontendModelAttributeValue>>} - Command response.\n"
+      fileContent += signature.paramDocs
+      fileContent += `   * @returns {Promise<${signature.returnType}>} - Command response.\n`
       fileContent += "   */\n"
-      fileContent += `  static async ${methodName}(...commandArguments) {\n`
+      fileContent += `  static async ${methodName}(${signature.parameters}) {\n`
       fileContent += "    return await this.executeCustomCommand({\n"
       fileContent += `      commandName: ${JSON.stringify(collectionCommands[methodName])},\n`
       fileContent += `      commandType: ${JSON.stringify(collectionCommands[methodName])},\n`
-      fileContent += `      payload: ${className}.normalizeCustomCommandPayloadArguments(commandArguments),\n`
+      fileContent += `      payload: ${className}.normalizeCustomCommandPayloadArguments(${signature.payloadArguments}),\n`
       fileContent += "      resourcePath: this.resourcePath()\n"
       fileContent += "    })\n"
       fileContent += "  }\n"
     }
 
     for (const methodName of Object.keys(memberCommands)) {
+      const signature = this.customCommandMethodSignature({commandMetadata, methodName})
+
       fileContent += "\n"
       fileContent += "  /**\n"
       fileContent += `   * Runs ${methodName}.\n`
-      fileContent += "   * @param {...FrontendModelAttributeValue} commandArguments - Custom command arguments.\n"
-      fileContent += "   * @returns {Promise<Record<string, FrontendModelAttributeValue>>} - Command response.\n"
+      fileContent += signature.paramDocs
+      fileContent += `   * @returns {Promise<${signature.returnType}>} - Command response.\n`
       fileContent += "   */\n"
-      fileContent += `  async ${methodName}(...commandArguments) {\n`
+      fileContent += `  async ${methodName}(${signature.parameters}) {\n`
       fileContent += `    return await ${className}.executeCustomCommand({\n`
       fileContent += `      commandName: ${JSON.stringify(memberCommands[methodName])},\n`
       fileContent += `      commandType: ${JSON.stringify(memberCommands[methodName])},\n`
       fileContent += "      memberId: this.primaryKeyValue(),\n"
-      fileContent += `      payload: ${className}.normalizeCustomCommandPayloadArguments(commandArguments),\n`
+      fileContent += `      payload: ${className}.normalizeCustomCommandPayloadArguments(${signature.payloadArguments}),\n`
       fileContent += `      resourcePath: ${className}.resourcePath()\n`
       fileContent += "    })\n"
       fileContent += "  }\n"
@@ -1327,7 +1332,69 @@ export default class DbGenerateFrontendModels extends BaseCommand {
       sourceClassName: ownerClassName
     })
 
-    return jsDocType ? {jsDocType} : null
+    // Frontend attributes hold the serialized (resolved) value, so an async
+    // backend accessor typed `Promise<number>` must surface as `number` — the
+    // same unwrapping the resource-method inference path applies.
+    return jsDocType
+      ? {jsDocType: this.frontendResolvableAttributeJsDocType(this.unwrappedPromiseJsDocType({jsDocType}))}
+      : null
+  }
+
+  /**
+   * A backend accessor's `@returns` can reference types that exist only on the
+   * backend (e.g. a model-local `@typedef AgentRunPlanningArtifact`). The frontend
+   * model can't resolve those, so fall back to `any` rather than emitting an
+   * undefined type name. Types built only from primitives and known generic
+   * builtins pass through unchanged.
+   * @param {string} jsDocType - Resolved (Promise-unwrapped) attribute type.
+   * @returns {string} - A frontend-resolvable attribute type.
+   */
+  frontendResolvableAttributeJsDocType(jsDocType) {
+    const safeTypeIdentifiers = new Set([
+      "Array", "Date", "Exclude", "Extract", "FrontendModelAttributeValue", "FrontendModelTransportValue",
+      "Map", "NonNullable", "Omit", "Partial", "Pick", "Promise", "Readonly", "ReadonlyArray", "Record",
+      "Required", "ReturnType", "Set"
+    ])
+    const referencedIdentifiers = jsDocType.match(/[A-Z][A-Za-z0-9_$]*/g) || []
+
+    if (referencedIdentifiers.some((identifier) => !safeTypeIdentifiers.has(identifier))) {
+      return "any"
+    }
+
+    return jsDocType
+  }
+
+  /**
+   * Builds the JSDoc param block, parameter list, payload-argument expression, and
+   * return type for a custom command method. With declared `args` each becomes a
+   * named, typed parameter mapped positionally into the command payload; without
+   * them the method stays variadic.
+   * @param {object} args - Arguments.
+   * @param {Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>} args.commandMetadata - Per-command metadata.
+   * @param {string} args.methodName - Command method name.
+   * @returns {{paramDocs: string, parameters: string, payloadArguments: string, returnType: string}} - Generation pieces.
+   */
+  customCommandMethodSignature({commandMetadata, methodName}) {
+    const metadata = commandMetadata[methodName] || {args: [], returnType: null}
+    const returnType = metadata.returnType || "Record<string, ?>"
+
+    if (metadata.args.length > 0) {
+      const parameterNames = metadata.args.map((arg) => arg.name)
+
+      return {
+        paramDocs: metadata.args.map((arg) => `   * @param {${arg.type}} ${arg.name} - Command argument.\n`).join(""),
+        parameters: parameterNames.join(", "),
+        payloadArguments: `[${parameterNames.join(", ")}]`,
+        returnType
+      }
+    }
+
+    return {
+      paramDocs: "   * @param {...FrontendModelAttributeValue} commandArguments - Custom command arguments.\n",
+      parameters: "...commandArguments",
+      payloadArguments: "commandArguments",
+      returnType
+    }
   }
 
   /**

package/build/frontend-models/base.js

@@ -66,9 +66,19 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  */
 /**
  * Frontend model static side.
- * @template {FrontendModelBase} [T=FrontendModelBase]
- * @template {Record<string, FrontendModelAttributeValue>} [Attributes=Record<string, FrontendModelAttributeValue>]
- * @template {Record<string, FrontendModelAttributeValue>} [CreateAttributes=Record<string, FrontendModelAttributeValue>]
+ *
+ * The template defaults are intentionally permissive (`any` model/attribute
+ * params). The bare `FrontendModelClass` is the `@this`/constraint type on the
+ * static query methods (findBy/find/where/preload/...); a generated subclass
+ * declares typed-attribute generics (e.g. `FrontendModelBase<AccountAttributes,
+ * AccountCreateAttributes, AccountUpdateAttributes>`) which, against a concrete
+ * `Record<string, FrontendModelTransportValue>` default, fail the constraint by
+ * invariance. Defaulting to `any` lets any subclass satisfy the constraint while
+ * the methods' own `@template T` still captures the precise calling class for
+ * their return types.
+ * @template {FrontendModelBase} [T=FrontendModelBase<any, any, any>]
+ * @template {object} [Attributes=any]
+ * @template {object} [CreateAttributes=any]
  * @typedef {{new (): T, create(attributes?: CreateAttributes): Promise<T>} & Omit<typeof FrontendModelBase, "create" | "prototype">} FrontendModelClass
  */
 /**
@@ -80,7 +90,7 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * Loaded instance type for relationship helper generics. Older generated
  * frontend models passed model classes into relationship helpers, while newer
  * generated models pass instance types.
- * @template {FrontendModelBase | typeof FrontendModelBase} T
+ * @template {FrontendModelBase<any, any, any> | typeof FrontendModelBase} T
  * @typedef {T extends new (...args: any[]) => infer Instance ? Instance : T} FrontendModelRelationshipModel
  */
 /**
@@ -281,9 +291,9 @@ export class AttributeNotSelectedError extends Error {
 
 /**
  * Lightweight singular relationship state holder for frontend model instances.
- * @template {FrontendModelBase | typeof FrontendModelBase} S
- * @template {FrontendModelBase | typeof FrontendModelBase} T
- * @template {Record<string, FrontendModelAttributeValue>} [TargetCreateAttributes=Record<string, FrontendModelAttributeValue>]
+ * @template {FrontendModelBase<any, any, any> | typeof FrontendModelBase} S
+ * @template {FrontendModelBase<any, any, any> | typeof FrontendModelBase} T
+ * @template {object} [TargetCreateAttributes=Record<string, FrontendModelAttributeValue>]
  */
 export class FrontendModelSingularRelationship {
   /**
@@ -401,9 +411,9 @@ export class FrontendModelSingularRelationship {
 
 /**
  * Lightweight has-many relationship state holder for frontend model instances.
- * @template {FrontendModelBase | typeof FrontendModelBase} S
- * @template {FrontendModelBase | typeof FrontendModelBase} T
- * @template {Record<string, FrontendModelAttributeValue>} [TargetCreateAttributes=Record<string, FrontendModelAttributeValue>]
+ * @template {FrontendModelBase<any, any, any> | typeof FrontendModelBase} S
+ * @template {FrontendModelBase<any, any, any> | typeof FrontendModelBase} T
+ * @template {object} [TargetCreateAttributes=Record<string, FrontendModelAttributeValue>]
  */
 export class FrontendModelHasManyRelationship {
   /**
@@ -540,8 +550,13 @@ export class FrontendModelHasManyRelationship {
 }
 
 /**
- * Frontend model relationship helper type.
- * @typedef {FrontendModelHasManyRelationship<FrontendModelBase, FrontendModelBase, Record<string, FrontendModelAttributeValue>> | FrontendModelSingularRelationship<FrontendModelBase, FrontendModelBase, Record<string, FrontendModelAttributeValue>>} FrontendModelRelationship
+ * Frontend model relationship helper type. Returned by `getRelationshipByName`,
+ * which generated models immediately cast to their concrete relationship type
+ * (e.g. `FrontendModelSingularRelationship<Owner, Target, TargetCreateAttributes>`).
+ * The members use `any` type args so that cast is allowed regardless of the
+ * target model's typed-attribute generics — a concrete `FrontendModelBase` member
+ * here makes the cast a non-overlapping (TS2352) error for every typed model.
+ * @typedef {FrontendModelHasManyRelationship<any, any, any> | FrontendModelSingularRelationship<any, any, any>} FrontendModelRelationship
  */
 
 /**
@@ -1883,9 +1898,16 @@ function assertDefinedFindByConditionValue(value, keyPath) {
 
 /**
  * Base frontend model.
- * @template {Record<string, FrontendModelAttributeValue>} [Attributes=Record<string, FrontendModelAttributeValue>]
- * @template {Record<string, FrontendModelAttributeValue>} [CreateAttributes=Record<string, FrontendModelAttributeValue>]
- * @template {Record<string, FrontendModelAttributeValue>} [UpdateAttributes=Record<string, FrontendModelAttributeValue>]
+ *
+ * Defaults are `any` so the bare `FrontendModelBase` — used throughout as a
+ * constraint/parameter type for "any frontend model" — accepts generated
+ * subclasses declaring typed-attribute generics (`FrontendModelBase<XAttributes,
+ * ...>`). A concrete `Record<string, FrontendModelAttributeValue>` default makes
+ * those subclasses fail by invariance. Subclasses still pass their precise
+ * attribute typedefs, so typed accessors keep their precision.
+ * @template {object} [Attributes=any]
+ * @template {object} [CreateAttributes=any]
+ * @template {object} [UpdateAttributes=any]
  */
 export default class FrontendModelBase {
   /**

package/build/frontend-models/resource-definition.js

@@ -90,6 +90,10 @@ function normalizeFrontendModelResourceConfiguration(resourceConfiguration) {
     builtInCollectionCommands: normalizedCommands.builtInCollectionCommands,
     builtInMemberCommands: normalizedCommands.builtInMemberCommands,
     collectionCommands: normalizedCommands.collectionCommands,
+    // Per-command metadata (typed args + declared return type) keyed by method
+    // name, derived from `{name, args?, returnType?}` command entries. The
+    // generator uses it to type each custom command method.
+    commandMetadata: normalizedCommands.commandMetadata,
     memberCommands: normalizedCommands.memberCommands
   }
 }
@@ -151,7 +155,7 @@ function defaultCrudAbilities() {
 /**
  * Runs normalize frontend model resource commands.
  * @param {import("../configuration-types.js").FrontendModelResourceConfiguration} resourceConfiguration - Raw resource configuration.
- * @returns {{builtInCollectionCommands: Record<string, string>, builtInMemberCommands: Record<string, string>, collectionCommands: Record<string, string>, memberCommands: Record<string, string>}} - Normalized command configuration.
+ * @returns {{builtInCollectionCommands: Record<string, string>, builtInMemberCommands: Record<string, string>, collectionCommands: Record<string, string>, commandMetadata: Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>, memberCommands: Record<string, string>}} - Normalized command configuration.
  */
 function normalizeFrontendModelResourceCommands(resourceConfiguration) {
   const builtInCollectionCommands = resourceConfiguration.builtInCollectionCommands
@@ -180,11 +184,15 @@ function normalizeFrontendModelResourceCommands(resourceConfiguration) {
     modelName: "MemberCommand"
   })
 
+  const normalizedCollectionCommands = normalizeFrontendModelCustomCommands({commandsConfig: customCollectionCommands, modelName: "CollectionCommand"})
+  const normalizedMemberCommands = normalizeFrontendModelCustomCommands({commandsConfig: customMemberCommands, modelName: "MemberCommand"})
+
   return {
     builtInCollectionCommands: normalizedBuiltInCollectionCommands,
     builtInMemberCommands: normalizedBuiltInMemberCommands,
-    collectionCommands: normalizeFrontendModelCustomCommands({commandsConfig: customCollectionCommands, modelName: "CollectionCommand"}),
-    memberCommands: normalizeFrontendModelCustomCommands({commandsConfig: customMemberCommands, modelName: "MemberCommand"})
+    collectionCommands: normalizedCollectionCommands.commands,
+    commandMetadata: {...normalizedCollectionCommands.metadata, ...normalizedMemberCommands.metadata},
+    memberCommands: normalizedMemberCommands.commands
   }
 }
 
@@ -228,27 +236,30 @@ function normalizeFrontendModelBuiltInCommands({commandDefaults, commandsConfig,
 }
 
 /**
- * Runs normalize frontend model custom commands.
+ * Runs normalize frontend model custom commands. Entries are either a plain
+ * camelCase method-name string or a `{name, args?, returnType?}` object that
+ * also declares the command's typed arguments and/or response type.
  * @param {object} args - Arguments.
- * @param {string[] | undefined} args.commandsConfig - Custom commands config (camelCase method-name list).
+ * @param {Array<string | {name: string, args?: Array<{name: string, type: string}>, returnType?: string}> | undefined} args.commandsConfig - Custom commands config.
  * @param {string} args.modelName - Diagnostic model name.
- * @returns {Record<string, string>} - Normalized custom command config (camelCase method name → kebab-case command slug).
+ * @returns {{commands: Record<string, string>, metadata: Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>}} - Route map (method name → kebab slug) + per-command metadata.
  */
 function normalizeFrontendModelCustomCommands({commandsConfig, modelName}) {
   if (!commandsConfig) {
-    return {}
+    return {commands: {}, metadata: {}}
   }
 
   if (!Array.isArray(commandsConfig)) {
     throw new Error(`${modelName} configuration must use the array form. Object form is no longer supported.`)
   }
 
-  /**
-   * Normalized commands.
-   * @type {Record<string, string>} */
-  const normalizedCommands = {}
+  /** @type {Record<string, string>} */
+  const commands = {}
+  /** @type {Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>} */
+  const metadata = {}
 
-  for (const methodName of commandsConfig) {
+  for (const commandEntry of commandsConfig) {
+    const {methodName, args, returnType} = normalizeFrontendModelCustomCommandEntry({commandEntry, modelName})
     const validatedMethodName = validateFrontendModelResourceCommandName({
       commandName: methodName,
       commandType: methodName,
@@ -256,10 +267,90 @@ function normalizeFrontendModelCustomCommands({commandsConfig, modelName}) {
     })
     const commandSlug = inflection.dasherize(inflection.underscore(validatedMethodName))
 
-    normalizedCommands[validatedMethodName] = commandSlug
+    commands[validatedMethodName] = commandSlug
+    metadata[validatedMethodName] = {args, returnType}
   }
 
-  return normalizedCommands
+  return {commands, metadata}
+}
+
+/**
+ * Normalizes one custom-command entry (string shorthand or contract object).
+ * @param {object} args - Arguments.
+ * @param {unknown} args.commandEntry - Raw command entry.
+ * @param {string} args.modelName - Diagnostic model name.
+ * @returns {{methodName: string, args: Array<{name: string, type: string}>, returnType: string | null}} - Method name + metadata.
+ */
+function normalizeFrontendModelCustomCommandEntry({commandEntry, modelName}) {
+  if (typeof commandEntry === "string") {
+    return {methodName: commandEntry, args: [], returnType: null}
+  }
+
+  if (!commandEntry || typeof commandEntry !== "object" || Array.isArray(commandEntry)) {
+    throw new Error(`${modelName} entries must be a camelCase name string or a {name, args?, returnType?} object`)
+  }
+
+  const {name, args, returnType, ...rest} = /** @type {{name?: unknown, args?: unknown, returnType?: unknown}} */ (commandEntry)
+
+  if (Object.keys(rest).length > 0) {
+    throw new Error(`Unexpected ${modelName} keys: ${Object.keys(rest).join(", ")}. Allowed: name, args, returnType`)
+  }
+
+  if (typeof name !== "string" || name.length < 1) {
+    throw new Error(`${modelName} object entries require a non-empty 'name' string`)
+  }
+
+  return {
+    methodName: name,
+    args: normalizeFrontendModelCommandArgs({args, commandName: name, modelName}),
+    returnType: normalizeFrontendModelCommandReturnType({commandName: name, modelName, returnType})
+  }
+}
+
+/**
+ * Validates and normalizes a custom command's typed-argument list.
+ * @param {object} args - Arguments.
+ * @param {unknown} args.args - Raw command args.
+ * @param {string} args.commandName - Command name for diagnostics.
+ * @param {string} args.modelName - Diagnostic model name.
+ * @returns {Array<{name: string, type: string}>} - Normalized typed command arguments.
+ */
+function normalizeFrontendModelCommandArgs({args, commandName, modelName}) {
+  if (args === undefined || args === null) {
+    return []
+  }
+
+  if (!Array.isArray(args)) {
+    throw new Error(`${modelName} '${commandName}' args must be an array of {name, type} objects`)
+  }
+
+  return args.map((arg) => {
+    if (!arg || typeof arg !== "object" || typeof arg.name !== "string" || arg.name.length < 1 || typeof arg.type !== "string" || arg.type.trim().length < 1) {
+      throw new Error(`${modelName} '${commandName}' args entries require non-empty 'name' and JSDoc-type 'type' strings`)
+    }
+
+    return {name: arg.name, type: arg.type.trim()}
+  })
+}
+
+/**
+ * Validates and normalizes a custom command's declared JSDoc return type.
+ * @param {object} args - Arguments.
+ * @param {string} args.commandName - Command name for diagnostics.
+ * @param {string} args.modelName - Diagnostic model name.
+ * @param {unknown} args.returnType - Raw return type.
+ * @returns {string | null} - Normalized JSDoc return type.
+ */
+function normalizeFrontendModelCommandReturnType({commandName, modelName, returnType}) {
+  if (returnType === undefined || returnType === null) {
+    return null
+  }
+
+  if (typeof returnType !== "string" || returnType.trim().length < 1) {
+    throw new Error(`${modelName} '${commandName}' returnType must be a non-empty JSDoc type string`)
+  }
+
+  return returnType.trim()
 }
 
 /**

package/build/src/configuration-types.d.ts

@@ -264,20 +264,34 @@
  * @property {string[]} [abilities] - Ability action list (camelCase action names). Defaults to `["read"]` for `find` and `index` when omitted.
  * @property {Record<string, FrontendModelAttachmentConfiguration>} [attachments] - Attachment helpers keyed by attachment name.
  * @property {string[]} [commands] - Legacy built-in command names (`index`, `find`, `create`, `update`, `destroy`, `attach`, `download`, `url`).
- * @property {string[]} [collectionCommands] - Custom collection commands as camelCase method names. The runtime derives the kebab-case command slug from each name.
- * @property {string[]} [memberCommands] - Custom member commands as camelCase method names. The runtime derives the kebab-case command slug from each name.
+ * @property {Array<FrontendModelResourceCustomCommand>} [collectionCommands] - Custom collection commands. Each entry is a camelCase method name, or a `{name, args?, returnType?}` object declaring typed arguments and/or a response type. The runtime derives the kebab-case command slug from the name.
+ * @property {Array<FrontendModelResourceCustomCommand>} [memberCommands] - Custom member commands. Each entry is a camelCase method name, or a `{name, args?, returnType?}` object declaring typed arguments and/or a response type. The runtime derives the kebab-case command slug from the name.
  * @property {string[]} [builtInCollectionCommands] - Built-in collection command names (`index`, `create`).
  * @property {string[]} [builtInMemberCommands] - Built-in member command names (`find`, `update`, `destroy`, `attach`, `download`, `url`).
  * @property {string[]} [relationships] - Relationship names to expose in frontend models. Type and target model are inferred from the backend model's registered relationships.
  * @property {string} [primaryKey] - Primary key attribute name.
  * @property {FrontendModelResourceServerConfiguration} [server] - Optional legacy backend behavior overrides for built-in frontend actions.
  */
+/**
+ * Object form of a custom command entry, declaring its typed arguments and/or
+ * response type alongside the command name.
+ * @typedef {object} FrontendModelResourceCustomCommandObject
+ * @property {string} name - camelCase command method name.
+ * @property {Array<{name: string, type: string}>} [args] - Typed command arguments; each generates a named, typed method parameter mapped positionally into the command payload. `type` is a JSDoc type string.
+ * @property {string} [returnType] - JSDoc type for the command response. When set, the generated method is typed `Promise<returnType>` instead of `Promise<Record<string, ?>>`. Emitted verbatim into the generated frontend model, so it must resolve there.
+ */
+/**
+ * A custom command entry: a plain camelCase method name, or an object declaring
+ * typed args and/or a response type.
+ * @typedef {string | FrontendModelResourceCustomCommandObject} FrontendModelResourceCustomCommand
+ */
 /**
  * @typedef {Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands"> & {
  *   abilities: FrontendModelResourceAbilitiesConfiguration
  *   builtInCollectionCommands: Record<string, string>
  *   builtInMemberCommands: Record<string, string>
  *   collectionCommands: Record<string, string>
+ *   commandMetadata: Record<string, {args: Array<{name: string, type: string}>, returnType: string | null}>
  *   memberCommands: Record<string, string>
  * }} NormalizedFrontendModelResourceConfiguration
  */
@@ -1043,13 +1057,13 @@ export type FrontendModelResourceConfiguration = {
      */
     commands?: string[] | undefined;
     /**
-     * - Custom collection commands as camelCase method names. The runtime derives the kebab-case command slug from each name.
+     * - Custom collection commands. Each entry is a camelCase method name, or a `{name, args?, returnType?}` object declaring typed arguments and/or a response type. The runtime derives the kebab-case command slug from the name.
      */
-    collectionCommands?: string[] | undefined;
+    collectionCommands?: FrontendModelResourceCustomCommand[] | undefined;
     /**
-     * - Custom member commands as camelCase method names. The runtime derives the kebab-case command slug from each name.
+     * - Custom member commands. Each entry is a camelCase method name, or a `{name, args?, returnType?}` object declaring typed arguments and/or a response type. The runtime derives the kebab-case command slug from the name.
      */
-    memberCommands?: string[] | undefined;
+    memberCommands?: FrontendModelResourceCustomCommand[] | undefined;
     /**
      * - Built-in collection command names (`index`, `create`).
      */
@@ -1071,11 +1085,44 @@ export type FrontendModelResourceConfiguration = {
      */
     server?: FrontendModelResourceServerConfiguration | undefined;
 };
+/**
+ * Object form of a custom command entry, declaring its typed arguments and/or
+ * response type alongside the command name.
+ */
+export type FrontendModelResourceCustomCommandObject = {
+    /**
+     * - camelCase command method name.
+     */
+    name: string;
+    /**
+     * - Typed command arguments; each generates a named, typed method parameter mapped positionally into the command payload. `type` is a JSDoc type string.
+     */
+    args?: {
+        name: string;
+        type: string;
+    }[] | undefined;
+    /**
+     * - JSDoc type for the command response. When set, the generated method is typed `Promise<returnType>` instead of `Promise<Record<string, ?>>`. Emitted verbatim into the generated frontend model, so it must resolve there.
+     */
+    returnType?: string | undefined;
+};
+/**
+ * A custom command entry: a plain camelCase method name, or an object declaring
+ * typed args and/or a response type.
+ */
+export type FrontendModelResourceCustomCommand = string | FrontendModelResourceCustomCommandObject;
 export type NormalizedFrontendModelResourceConfiguration = Omit<FrontendModelResourceConfiguration, "abilities" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands"> & {
     abilities: FrontendModelResourceAbilitiesConfiguration;
     builtInCollectionCommands: Record<string, string>;
     builtInMemberCommands: Record<string, string>;
     collectionCommands: Record<string, string>;
+    commandMetadata: Record<string, {
+        args: Array<{
+            name: string;
+            type: string;
+        }>;
+        returnType: string | null;
+    }>;
     memberCommands: Record<string, string>;
 };
 export type FrontendModelResourceClassType = Omit<typeof import("./frontend-model-resource/base-resource.js").default, never> & {