@carthooks/arcubase-cli 0.1.20 → 0.1.22

package/src/runtime/execute.ts

@@ -11,6 +11,7 @@ import { resolveArcubaseSDKPath } from './paths.js'
 import { compileCSVImportMapping, compileExcelImportMapping, type CompiledEntityImportConfig } from './entity_import_mapping.js'
 import { uploadLocalFileWithToken } from './local_upload.js'
 import { renderCommandHelpExamples } from './help_examples.js'
+import { generateArcubaseProjectSDK } from './dev_sdk_gen.js'
 
 export type CommandExecutionSummary = {
   scope: CommandScope
@@ -24,7 +25,8 @@ export type CommandExecutionSummary = {
 
 export function renderRootHelp(scope: CommandScope): string {
   const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase'
-  const items = listModules(scope).map((item) => `  - ${item}`)
+  const modules = scope === 'admin' ? [...listModules(scope), 'dev'].sort() : listModules(scope)
+  const items = modules.map((item) => `  - ${item}`)
   return [
     `${binary} <command> [subcommand] [flags]`,
     '',
@@ -38,6 +40,17 @@ export function renderRootHelp(scope: CommandScope): string {
   ].join('\n')
 }
 
+function renderDevModuleHelp(): string {
+  return [
+    'arcubase-admin dev <command> [flags]',
+    '',
+    'developer commands for local project tooling',
+    '',
+    'commands:',
+    '  - sdk-gen',
+  ].join('\n')
+}
+
 export function renderModuleHelp(scope: CommandScope, moduleName: string, env: EnvInput = process.env): string {
   const items = listModuleCommands(scope, moduleName)
   if (items.length === 0) {
@@ -251,6 +264,44 @@ function getFixedValue(value: object): string | undefined {
   return typeof fixedValue === 'string' ? fixedValue : undefined
 }
 
+function isDevSDKGenCommand(scope: CommandScope, moduleName: string | undefined, commandName: string | undefined): boolean {
+  return scope === 'admin' && moduleName === 'dev' && commandName === 'sdk-gen'
+}
+
+function validateDevSDKGenFlags(flags: Record<string, string | boolean>) {
+  const allowed = new Set(['help', 'app-id', 'out'])
+  for (const flag of Object.keys(flags)) {
+    if (!allowed.has(flag)) {
+      throw new CLIError('UNKNOWN_FLAG', `unknown flag --${flag} for dev sdk-gen`, 2, {
+        operation: 'dev sdk-gen',
+        hint: 'run dev sdk-gen --help for the supported flags',
+      })
+    }
+  }
+}
+
+function renderDevSDKGenHelp(): string {
+  return [
+    'arcubase-admin dev sdk-gen',
+    'method: local generator',
+    'endpoint: /apps/:app_id',
+    'body: none',
+    'path flags: --app-id',
+    'flags: --out',
+    '',
+    'generates typed TypeScript source for the current Web project',
+    '',
+    'example:',
+    '  - arcubase-admin dev sdk-gen --app-id <app_id> --out src/arcubase',
+    '',
+    'requirements:',
+    '  - missing field.key values are initialized through admin auth as field<id>',
+    '  - existing field.key values must be stable unique TypeScript identifiers',
+    '  - entity property names use entity.key when available, otherwise a stable entity<id> fallback',
+    '  - generated code accepts createArcubaseSdk({ baseURL, accessToken, refreshToken })',
+  ].join('\n')
+}
+
 function resolveEndpoint(command: NonNullable<ReturnType<typeof findCommand>>, flags: Record<string, string | boolean>): string {
   let resolved: string = command.endpoint
   for (const mapping of command.pathParams) {
@@ -637,6 +688,10 @@ function isAssignUsersCommand(scope: CommandScope, command: NonNullable<ReturnTy
   return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users'
 }
 
+function isAccessRuleBulkApplyCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'bulk-apply'
+}
+
 function isTableCreateCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
   return scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'create'
 }
@@ -653,6 +708,14 @@ function isAccessRuleCommand(scope: CommandScope, command: NonNullable<ReturnTyp
   return scope === 'admin' && command.commandPath[0] === 'access-rule'
 }
 
+function isWidgetPreviewDataCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'widget' && command.commandPath[1] === 'preview-data'
+}
+
+function isWidgetUpdateCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'widget' && command.commandPath[1] === 'update'
+}
+
 function isAccessRuleUpdateCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
   return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update'
 }
@@ -962,6 +1025,45 @@ function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'retryToo
       ],
     }
   }
+  if (requestType === 'AppPreviewWidgetsDataReqVO') {
+    return {
+      shapeHint: {
+        dataSource: 2188891001,
+        dataSourceType: 'entity',
+        dimensions: [{ IsField: true, FieldID: 1004, Name: 'Source' }],
+        measures: [{ FieldID: 1005, Aggregate: 'sum', Name: 'Total Amount' }],
+      },
+      commonMistakes: [
+        'widget preview-data body is the chart query itself',
+        'do not send a saved widget object with id, entity_id, or options',
+        'field dimensions with FieldID must set IsField:true',
+        'unsupported aggregates are invalid; use sum, avg, max, min, count, or distinct_count',
+      ],
+      suggestions: [
+        'retry with: arcubase-admin widget preview-data --app-id <app_id> --body-json \'{"dataSource":<table_id>,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":<field_id>,"Name":"Source"}],"measures":[{"FieldID":<number_field_id>,"Aggregate":"sum","Name":"Total Amount"}]}\'',
+      ],
+    }
+  }
+  if (requestType === 'AppUpdateWidgetsReqVO') {
+    return {
+      shapeHint: {
+        entity_id: 2188891001,
+        options: {
+          charts: {
+            entity_id: 2188891001,
+            dimensions: [{ IsField: true, FieldID: 1004, Name: 'Source' }],
+            measures: [{ FieldID: 1005, Aggregate: 'sum', Name: 'Total Amount' }],
+            type: 'bar',
+          },
+        },
+      },
+      commonMistakes: [
+        'dashboard chart config belongs in body.options.charts',
+        'field dimensions with FieldID must set IsField:true',
+        'verify persistence with widget get or widget list after update',
+      ],
+    }
+  }
   return {}
 }
 
@@ -1085,33 +1187,124 @@ function normalizeNumericAccessRuleUserScopeIDs(
   command: NonNullable<ReturnType<typeof findCommand>>,
   body: unknown,
 ): unknown {
-  if (!isAccessRuleCommand(scope, command) || !isRecord(body) || !isRecord(body.options) || !Array.isArray(body.options.user_scope)) {
+  if (!isAccessRuleCommand(scope, command) || !isRecord(body)) {
     return body
   }
 
-  let changed = false
-  const userScope = body.options.user_scope.map((item) => {
-    if (!isRecord(item) || typeof item.id !== 'string' || !/^\d+$/.test(item.id)) {
-      return item
-    }
-    const id = Number(item.id)
-    if (!Number.isFinite(id) || !Number.isInteger(id)) {
-      return item
-    }
-    changed = true
-    return { ...item, id }
-  })
+  const normalizeUserScope = (userScope: unknown): { value: unknown; changed: boolean } => {
+    if (!Array.isArray(userScope)) return { value: userScope, changed: false }
+    let changed = false
+    const value = userScope.map((item) => {
+      if (!isRecord(item) || typeof item.id !== 'string' || !/^\d+$/.test(item.id)) {
+        return item
+      }
+      const id = Number(item.id)
+      if (!Number.isFinite(id) || !Number.isInteger(id)) {
+        return item
+      }
+      changed = true
+      return { ...item, id }
+    })
+    return { value, changed }
+  }
+
+  const normalizeNumericID = (value: unknown): { value: unknown; changed: boolean } => {
+    if (typeof value !== 'string' || !/^\d+$/.test(value)) return { value, changed: false }
+    const id = Number(value)
+    if (!Number.isFinite(id) || !Number.isInteger(id)) return { value, changed: false }
+    return { value: id, changed: true }
+  }
+
+  if (isAccessRuleBulkApplyCommand(scope, command) && Array.isArray(body.items)) {
+    let changed = false
+    const items = body.items.map((item) => {
+      if (!isRecord(item)) return item
+      let nextItem: Record<string, unknown> = item
+      for (const key of ['table_id', 'rule_id']) {
+        const normalized = normalizeNumericID(nextItem[key])
+        if (normalized.changed) {
+          nextItem = { ...nextItem, [key]: normalized.value }
+          changed = true
+        }
+      }
+      if (isRecord(nextItem.options)) {
+        const normalizedUserScope = normalizeUserScope(nextItem.options.user_scope)
+        if (normalizedUserScope.changed) {
+          nextItem = {
+            ...nextItem,
+            options: {
+              ...nextItem.options,
+              user_scope: normalizedUserScope.value,
+            },
+          }
+          changed = true
+        }
+      }
+      return nextItem
+    })
+    return changed ? { ...body, items } : body
+  }
 
-  if (!changed) return body
+  if (!isRecord(body.options)) {
+    return body
+  }
+  const normalizedUserScope = normalizeUserScope(body.options.user_scope)
+  if (!normalizedUserScope.changed) return body
   return {
     ...body,
     options: {
       ...body.options,
-      user_scope: userScope,
+      user_scope: normalizedUserScope.value,
     },
   }
 }
 
+function validateAccessRulePolicyShape(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  requestType: string,
+  policy: Record<string, unknown> | undefined,
+  env: EnvInput,
+  pathPrefix: string,
+) {
+  const actions = policy && Array.isArray(policy.actions) ? policy.actions : []
+  if (actions.includes('read') || actions.includes('write')) {
+    throwBodyValidationFailure(
+      'access-rule policy.actions must use Arcubase action codes: use "view" for read and "add","edit" for write; do not use "read", "write", or "insert"',
+      requestType,
+      `${pathPrefix}.actions`,
+      scope,
+      command,
+      env,
+    )
+  }
+  const fields = policy && Array.isArray(policy.fields) ? policy.fields : []
+  const allowedSystemFieldKeys = new Set(['created', 'updated', 'creator'])
+  for (const [index, field] of fields.entries()) {
+    if (!isRecord(field)) continue
+    if (typeof field.key === 'number' || (typeof field.key === 'string' && /^\d+$/.test(field.key))) {
+      throwBodyValidationFailure(
+        'access-rule policy.fields[].key must be a string prefixed with colon, for example ":1002"; do not use raw numbers',
+        requestType,
+        `${pathPrefix}.fields.${index}.key`,
+        scope,
+        command,
+        env,
+      )
+    }
+    if (typeof field.key === 'string' && !field.key.startsWith(':') && !allowedSystemFieldKeys.has(field.key)) {
+      throwBodyValidationFailure(
+        'access-rule policy.fields[].key must use Arcubase permission keys such as ":1002"; do not use FieldVO.key values such as "vote_name"',
+        requestType,
+        `${pathPrefix}.fields.${index}.key`,
+        scope,
+        command,
+        env,
+      )
+    }
+  }
+}
+
 function requireUpdateContains(
   scope: CommandScope,
   command: NonNullable<ReturnType<typeof findCommand>>,
@@ -1133,6 +1326,32 @@ function requireUpdateContains(
   }
 }
 
+function validateChartFieldDimensions(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  requestType: string,
+  dimensions: unknown,
+  pathPrefix: string,
+  env: EnvInput,
+) {
+  if (!Array.isArray(dimensions)) return
+  for (const [index, dimension] of dimensions.entries()) {
+    if (!isRecord(dimension) || typeof dimension.FieldID !== 'number') {
+      continue
+    }
+    if (dimension.IsField !== true) {
+      throwBodyValidationFailure(
+        'widget chart field dimensions require IsField:true when FieldID is present; otherwise grouped statistics collapse into total rows',
+        requestType,
+        `${pathPrefix}.${index}.IsField`,
+        scope,
+        command,
+        env,
+      )
+    }
+  }
+}
+
 function validateActionSpecificRawBody(
   scope: CommandScope,
   command: NonNullable<ReturnType<typeof findCommand>>,
@@ -1172,6 +1391,54 @@ function validateActionSpecificRawBody(
   }
 
   if (isAccessRuleCommand(scope, command)) {
+    if (isAccessRuleBulkApplyCommand(scope, command)) {
+      if (!Array.isArray(body.items) || body.items.length === 0) {
+        throwBodyValidationFailure(
+          'access-rule bulk-apply requires non-empty body.items; put every table/rule assignment in body.items',
+          command.requestType,
+          'body.items',
+          scope,
+          command,
+          env,
+        )
+      }
+      if (body.mode !== undefined && body.mode !== 'update_existing' && body.mode !== 'upsert_by_name') {
+        throwBodyValidationFailure(
+          'access-rule bulk-apply body.mode must be "update_existing" or "upsert_by_name"',
+          command.requestType,
+          'body.mode',
+          scope,
+          command,
+          env,
+        )
+      }
+      for (const [index, item] of body.items.entries()) {
+        if (!isRecord(item)) {
+          throwBodyValidationFailure(
+            'access-rule bulk-apply body.items[] must be an object',
+            command.requestType,
+            `body.items.${index}`,
+            scope,
+            command,
+            env,
+          )
+        }
+        const options = isRecord(item.options) ? item.options : undefined
+        if (!options) {
+          throwBodyValidationFailure(
+            'access-rule bulk-apply body.items[].options is required and must include the full canonical options object',
+            command.requestType,
+            `body.items.${index}.options`,
+            scope,
+            command,
+            env,
+          )
+        }
+        validateAccessRuleUserScope(scope, command, command.requestType, options.user_scope, env, `body.items.${index}.options.user_scope`)
+        validateAccessRulePolicyShape(scope, command, command.requestType, isRecord(options.policy) ? options.policy : undefined, env, `body.items.${index}.options.policy`)
+      }
+      return
+    }
     const update = stringArray(body.update)
     if (isAccessRuleUpdateCommand(scope, command) && update.some((item) => item.startsWith('options.'))) {
       throwBodyValidationFailure(
@@ -1216,42 +1483,17 @@ function validateActionSpecificRawBody(
       )
     }
     validateAccessRuleUserScope(scope, command, command.requestType, options?.user_scope, env)
-    const actions = policy && Array.isArray(policy.actions) ? policy.actions : []
-    if (actions.includes('read') || actions.includes('write')) {
-      throwBodyValidationFailure(
-        'access-rule policy.actions must use Arcubase action codes: use "view" for read and "add","edit" for write; do not use "read", "write", or "insert"',
-        command.requestType,
-        'body.options.policy.actions',
-        scope,
-        command,
-        env,
-      )
-    }
-    const fields = policy && Array.isArray(policy.fields) ? policy.fields : []
-    const allowedSystemFieldKeys = new Set(['created', 'updated', 'creator'])
-    for (const [index, field] of fields.entries()) {
-      if (!isRecord(field)) continue
-      if (typeof field.key === 'number' || (typeof field.key === 'string' && /^\d+$/.test(field.key))) {
-        throwBodyValidationFailure(
-          'access-rule policy.fields[].key must be a string prefixed with colon, for example ":1002"; do not use raw numbers',
-          command.requestType,
-          `body.options.policy.fields.${index}.key`,
-          scope,
-          command,
-          env,
-        )
-      }
-      if (typeof field.key === 'string' && !field.key.startsWith(':') && !allowedSystemFieldKeys.has(field.key)) {
-        throwBodyValidationFailure(
-          'access-rule policy.fields[].key must use Arcubase permission keys such as ":1002"; do not use FieldVO.key values such as "vote_name"',
-          command.requestType,
-          `body.options.policy.fields.${index}.key`,
-          scope,
-          command,
-          env,
-        )
-      }
-    }
+    validateAccessRulePolicyShape(scope, command, command.requestType, policy, env, 'body.options.policy')
+  }
+
+  if (isWidgetPreviewDataCommand(scope, command)) {
+    validateChartFieldDimensions(scope, command, command.requestType, body.dimensions, 'body.dimensions', env)
+  }
+
+  if (isWidgetUpdateCommand(scope, command)) {
+    const options = isRecord(body.options) ? body.options : undefined
+    const charts = options && isRecord(options.charts) ? options.charts : undefined
+    validateChartFieldDimensions(scope, command, command.requestType, charts?.dimensions, 'body.options.charts.dimensions', env)
   }
 }
 
@@ -1710,6 +1952,186 @@ async function requestJSON(
   return { status: response.status, data: parsedResponse }
 }
 
+function unwrapResponseData(payload: unknown): unknown {
+  return isRecord(payload) && 'data' in payload ? payload.data : payload
+}
+
+type SDKGenEntityRef = {
+  id: string
+}
+
+type SDKGenInitializedFieldKeys = {
+  entityId: number
+  fields: string[]
+}
+
+function extractSDKGenAppPayload(payload: unknown): Record<string, any> {
+  const appPayload = unwrapResponseData(payload)
+  if (!isRecord(appPayload)) {
+    throw new CLIError('SDK_GEN_INVALID_SCHEMA', 'sdk-gen expected app detail response data', 2)
+  }
+  return appPayload
+}
+
+function extractSDKGenEntityRefs(appPayload: Record<string, any>): SDKGenEntityRef[] {
+  const sourceEntities = Array.isArray(appPayload.entities)
+    ? appPayload.entities
+    : Array.isArray(appPayload.tables)
+      ? appPayload.tables
+      : Array.isArray(appPayload.entitys)
+        ? appPayload.entitys
+        : []
+  const refs = sourceEntities
+    .filter((item): item is Record<string, unknown> => isRecord(item))
+    .map((item) => item.id)
+    .filter((id): id is string | number => typeof id === 'string' || typeof id === 'number')
+    .map((id) => ({ id: String(id) }))
+  return refs
+}
+
+function resolveSDKGenAppId(flagAppId: string, appPayload: Record<string, any>): number {
+  const fromPayload = typeof appPayload.id === 'number' ? appPayload.id : typeof appPayload.app_id === 'number' ? appPayload.app_id : undefined
+  const fromFlag = Number(flagAppId)
+  if (Number.isFinite(fromFlag)) return fromFlag
+  if (fromPayload) return fromPayload
+  throw new CLIError('SDK_GEN_APP_ID_REQUIRED', 'sdk-gen expected numeric app id', 2)
+}
+
+function walkSDKGenFields(fields: unknown, visit: (field: Record<string, any>) => void) {
+  if (!Array.isArray(fields)) {
+    return
+  }
+  for (const field of fields) {
+    if (!isRecord(field)) {
+      continue
+    }
+    visit(field)
+    walkSDKGenFields(field.children, visit)
+  }
+}
+
+function collectExistingSDKGenFieldKeys(entity: Record<string, any>): Set<string> {
+  const keys = new Set<string>()
+  walkSDKGenFields(entity.fields, (field) => {
+    if (typeof field.key === 'string' && field.key.trim() !== '') {
+      keys.add(field.key.trim())
+    }
+  })
+  return keys
+}
+
+function nextSDKGenFallbackFieldKey(fieldId: number, usedKeys: Set<string>): string {
+  const base = `field${fieldId}`
+  if (!usedKeys.has(base)) {
+    usedKeys.add(base)
+    return base
+  }
+  let index = 2
+  while (usedKeys.has(`${base}_${index}`)) {
+    index++
+  }
+  const key = `${base}_${index}`
+  usedKeys.add(key)
+  return key
+}
+
+function initializeMissingSDKGenFieldKeys(entity: Record<string, any>): Array<{ id: number; key: string }> {
+  const usedKeys = collectExistingSDKGenFieldKeys(entity)
+  const updates: Array<{ id: number; key: string }> = []
+  walkSDKGenFields(entity.fields, (field) => {
+    if (typeof field.id !== 'number') {
+      return
+    }
+    if (typeof field.key === 'string' && field.key.trim() !== '') {
+      field.key = field.key.trim()
+      return
+    }
+    const key = nextSDKGenFallbackFieldKey(field.id, usedKeys)
+    field.key = key
+    updates.push({ id: field.id, key })
+  })
+  return updates
+}
+
+async function executeDevSDKGen(
+  runtimeEnv: RuntimeEnv,
+  flags: Record<string, string | boolean>,
+  fetchImpl: typeof fetch,
+): Promise<any> {
+  validateDevSDKGenFlags(flags)
+  const appId = flagValue(flags, 'app-id')
+  const outDir = flagValue(flags, 'out')
+  if (!appId) {
+    throw new CLIError('MISSING_PATH_FLAG', 'missing required flag --app-id', 2)
+  }
+  if (!outDir) {
+    throw new CLIError('MISSING_FLAG', 'missing required flag --out', 2, {
+      operation: 'dev sdk-gen',
+      hint: 'retry with --out src/arcubase',
+    })
+  }
+
+  const endpoint = `/api/apps/${encodeURIComponent(appId)}`
+  const appDetail = await requestJSON(runtimeEnv, 'GET', endpoint, undefined, fetchImpl)
+  const appPayload = extractSDKGenAppPayload(appDetail.data)
+  let entityRefs = extractSDKGenEntityRefs(appPayload)
+  if (entityRefs.length === 0) {
+    const entitiesEndpoint = `/api/apps/${encodeURIComponent(appId)}/entities`
+    const entityList = await requestJSON(runtimeEnv, 'GET', entitiesEndpoint, undefined, fetchImpl)
+    const entityListPayload = unwrapResponseData(entityList.data)
+    entityRefs = extractSDKGenEntityRefs({ entities: entityListPayload })
+  }
+  if (entityRefs.length === 0) {
+    throw new CLIError('SDK_GEN_NO_ENTITIES', 'sdk-gen could not find entities in app detail response', 2)
+  }
+  const entities = []
+  const initializedFieldKeys: SDKGenInitializedFieldKeys[] = []
+  for (const entityRef of entityRefs) {
+    const entityEndpoint = `/api/apps/${encodeURIComponent(appId)}/entity/${encodeURIComponent(entityRef.id)}`
+    const entityDetail = await requestJSON(runtimeEnv, 'GET', entityEndpoint, undefined, fetchImpl)
+    const entityPayload = unwrapResponseData(entityDetail.data)
+    if (!isRecord(entityPayload)) {
+      throw new CLIError('SDK_GEN_INVALID_SCHEMA', 'sdk-gen expected entity detail response data', 2)
+    }
+    const customKeyUpdates = initializeMissingSDKGenFieldKeys(entityPayload)
+    if (customKeyUpdates.length > 0) {
+      const customKeysEndpoint = `/api/apps/${encodeURIComponent(appId)}/entity/${encodeURIComponent(entityRef.id)}/custom-keys`
+      await requestJSON(runtimeEnv, 'PUT', customKeysEndpoint, customKeyUpdates, fetchImpl)
+      initializedFieldKeys.push({
+        entityId: typeof entityPayload.id === 'number' ? entityPayload.id : Number(entityRef.id),
+        fields: customKeyUpdates.map((item) => item.key),
+      })
+    }
+    entities.push(entityPayload)
+  }
+  const generated = generateArcubaseProjectSDK({
+    id: resolveSDKGenAppId(appId, appPayload),
+    name: typeof appPayload.name === 'string' ? appPayload.name : undefined,
+    entities,
+  })
+  const absoluteOutDir = path.resolve(process.cwd(), outDir)
+
+  for (const file of generated.files) {
+    const targetPath = path.resolve(absoluteOutDir, file.path)
+    if (!targetPath.startsWith(`${absoluteOutDir}${path.sep}`)) {
+      throw new CLIError('SDK_GEN_INVALID_OUTPUT_PATH', `invalid generated file path: ${file.path}`, 2)
+    }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true })
+    fs.writeFileSync(targetPath, file.contents)
+  }
+
+  return {
+    kind: 'result',
+    commandPath: ['dev', 'sdk-gen'],
+    status: appDetail.status,
+    data: {
+      out: absoluteOutDir,
+      files: generated.files.map((file) => file.path),
+      initializedFieldKeys,
+    },
+  }
+}
+
 function requiredStringFlag(flags: Record<string, string | boolean>, flag: string): string {
   const value = flagValue(flags, flag)
   if (!value) {
@@ -2078,6 +2500,16 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
     }
     return { kind: 'help', text: renderRootHelp(scope) }
   }
+  if (isDevSDKGenCommand(scope, moduleName, commandName)) {
+    if (hasFlag(parsed.flags, 'help')) {
+      return { kind: 'help', text: renderDevSDKGenHelp() }
+    }
+    const runtimeEnv = env ?? loadRuntimeEnv(scope)
+    return executeDevSDKGen(runtimeEnv, parsed.flags, fetchImpl)
+  }
+  if (scope === 'admin' && moduleName === 'dev' && !commandName) {
+    return { kind: 'help', text: renderDevModuleHelp() }
+  }
   const singleTokenCommand = !commandName ? findCommand(scope, moduleName) : null
   if (!commandName && !singleTokenCommand) {
     if (hasFlag(parsed.flags, 'help-examples')) {