@carthooks/arcubase-cli 0.1.23 → 0.1.25

package/src/runtime/dev_sdk_gen.ts

@@ -1,360 +1,20 @@
-import { CLIError } from './errors.js'
-
-export type GeneratedSDKFile = {
-  path: string
-  contents: string
-}
-
-export type GeneratedSDK = {
-  files: GeneratedSDKFile[]
-}
-
-type ArcubaseField = {
-  id: number
-  label: string
-  key: string
-  type: string
-  required: boolean
-  options?: Record<string, unknown>
-}
-
-type ArcubaseEntity = {
-  appId: number
-  id: number
-  name: string
-  sdkName: string
-  fields: ArcubaseField[]
-}
-
-function isRecord(value: unknown): value is Record<string, any> {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
-}
-
-function unwrapData(payload: unknown): unknown {
-  return isRecord(payload) && 'data' in payload ? payload.data : payload
-}
-
-function toPascalCase(value: string): string {
-  const words = value
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .split(/[^A-Za-z0-9]+/)
-    .filter(Boolean)
-  if (words.length === 0) return 'Entity'
-  return words.map((word) => `${word[0].toUpperCase()}${word.slice(1)}`).join('')
-}
-
-function toCamelCase(value: string): string {
-  const pascal = toPascalCase(value)
-  return `${pascal[0].toLowerCase()}${pascal.slice(1)}`
-}
-
-function sanitizeEntityKey(entity: ArcubaseEntity): string {
-  const fallback = entity.sdkName || `entity_${entity.id}`
-  return toCamelCase(fallback) === 'entity' ? `entity${entity.id}` : toCamelCase(fallback)
-}
-
-function normalizeFieldType(type: string): string {
-  switch (type) {
-    case 'number':
-      return 'number'
-    case 'boolean':
-      return 'boolean'
-    case 'select':
-    case 'radio':
-    case 'checkbox':
-    case 'status':
-      return 'number | string'
-    case 'file':
-    case 'image':
-    case 'member':
-    case 'members':
-    case 'department':
-    case 'departments':
-    case 'linkto':
-    case 'relation':
-    case 'relationfield':
-    case 'subform':
-      return 'unknown'
-    default:
-      return 'string'
-  }
-}
-
-function normalizeEntities(payload: unknown): ArcubaseEntity[] {
-  const root = unwrapData(payload)
-  if (!isRecord(root)) {
-    throw new CLIError('SDK_GEN_INVALID_SCHEMA', 'sdk-gen expected an app detail object', 2)
-  }
-  const appId = typeof root.id === 'number' ? root.id : typeof root.app_id === 'number' ? root.app_id : undefined
-  if (!appId) {
-    throw new CLIError('SDK_GEN_APP_ID_REQUIRED', 'sdk-gen expected app id in app detail response', 2)
-  }
-  const sourceEntities = Array.isArray(root.entities)
-    ? root.entities
-    : Array.isArray(root.tables)
-      ? root.tables
-      : Array.isArray(root.entitys)
-        ? root.entitys
-        : []
-  const entities = sourceEntities
-    .filter((item): item is Record<string, unknown> => isRecord(item))
-    .filter((item) => typeof item.id === 'number' && typeof item.name === 'string')
-    .map((item) => {
-      const fields = Array.isArray(item.fields)
-        ? item.fields
-            .filter((field): field is Record<string, unknown> => isRecord(field))
-            .filter((field) => typeof field.id === 'number' && typeof field.label === 'string' && typeof field.type === 'string')
-            .map((field) => ({
-              id: field.id as number,
-              label: field.label as string,
-              key: typeof field.key === 'string' ? field.key.trim() : '',
-              type: field.type as string,
-              required: field.required === true,
-              options: isRecord(field.options) ? field.options : undefined,
-            }))
-        : []
-      const entity: ArcubaseEntity = {
-        appId,
-        id: item.id as number,
-        name: item.name as string,
-        sdkName: typeof item.key === 'string' && item.key.trim() ? item.key.trim() : '',
-        fields,
-      }
-      entity.sdkName = sanitizeEntityKey(entity)
-      return entity
-    })
-  if (entities.length === 0) {
-    throw new CLIError('SDK_GEN_NO_ENTITIES', 'sdk-gen could not find entities in app detail response', 2)
-  }
-  validateEntities(entities)
-  return entities
-}
-
-function validateEntities(entities: ArcubaseEntity[]) {
-  const entityKeys = new Set<string>()
-  for (const entity of entities) {
-    if (entityKeys.has(entity.sdkName)) {
-      throw new CLIError('SDK_GEN_DUPLICATE_ENTITY_KEY', `duplicate generated entity key: ${entity.sdkName}`, 2)
-    }
-    entityKeys.add(entity.sdkName)
-
-    const fieldKeys = new Set<string>()
-    for (const field of entity.fields) {
-      if (!field.key) {
-        throw new CLIError('SDK_GEN_FIELD_KEY_REQUIRED', `field.key is required for ${entity.name}.${field.label} (${field.id})`, 2)
-      }
-      if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(field.key)) {
-        throw new CLIError('SDK_GEN_INVALID_FIELD_KEY', `field.key must be a TypeScript identifier: ${entity.name}.${field.key}`, 2)
-      }
-      if (fieldKeys.has(field.key)) {
-        throw new CLIError('SDK_GEN_DUPLICATE_FIELD_KEY', `duplicate field.key in ${entity.name}: ${field.key}`, 2)
-      }
-      fieldKeys.add(field.key)
-    }
-  }
-}
-
-function emitRuntime(): string {
-  return `export type ArcubaseSdkConfig = {
-  baseURL: string
-  accessToken?: string
-  refreshToken?: string
-}
-
-export type ArcubaseRow<TFields> = {
-  id: number
-  title?: string
-  fields: TFields
-  raw: Record<string, any>
-}
-
-export type ArcubaseRuntime = {
-  config: ArcubaseSdkConfig
-  request<T>(method: string, endpoint: string, body?: unknown): Promise<T>
-}
-
-type ArcubaseEnvelope<T> = {
-  data?: T
-  error?: { message?: string; key?: string; type?: string }
-}
-
-export function createRuntime(config: ArcubaseSdkConfig): ArcubaseRuntime {
-  let accessToken = config.accessToken ?? ''
-  let refreshToken = config.refreshToken ?? ''
+import {
+  ArcubaseCodeGenError,
+  generateArcubaseProjectSDK as generateArcubaseProjectSDKCore,
+  type GeneratedSDK,
+} from '@arcubase/code-gen'
 
-  async function request<T>(method: string, endpoint: string, body?: unknown): Promise<T> {
-    const baseURL = config.baseURL.endsWith('/') ? config.baseURL : \`\${config.baseURL}/\`
-    const response = await fetch(new URL(endpoint.replace(/^\\/+/, ''), baseURL).toString(), {
-      method,
-      headers: {
-        'Content-Type': 'application/json',
-        ...(accessToken ? { Authorization: \`Bearer \${accessToken}\` } : {}),
-      },
-      body: body === undefined ? undefined : JSON.stringify(body),
-    })
-    const payload = await response.json().catch(() => null) as ArcubaseEnvelope<T> | null
-    if (!response.ok || payload?.error) {
-      throw new Error(payload?.error?.message ?? \`Arcubase request failed: \${response.status}\`)
-    }
-    return payload?.data as T
-  }
-
-  return {
-    config: { ...config, accessToken, refreshToken },
-    request,
-  }
-}
-`
-}
-
-function emitSchema(entities: ArcubaseEntity[]): string {
-  const schema = {
-    entities: Object.fromEntries(entities.map((entity) => [
-      entity.sdkName,
-      {
-        entityId: entity.id,
-        name: entity.name,
-        fields: Object.fromEntries(entity.fields.map((field) => [
-          field.key,
-          {
-            fieldId: field.id,
-            label: field.label,
-            type: field.type,
-            required: field.required,
-          },
-        ])),
-      },
-    ])),
-  }
-  return `export const arcubaseSchema = ${JSON.stringify(schema, null, 2)} as const
-
-export type ArcubaseEntityKey = keyof typeof arcubaseSchema.entities
-`
-}
-
-function emitEntity(entity: ArcubaseEntity): string {
-  const typeName = toPascalCase(entity.sdkName)
-  const fieldLines = entity.fields.map((field) => {
-    const optional = field.required ? '' : '?'
-    return `  ${field.key}${optional}: ${normalizeFieldType(field.type)}`
-  })
-  const fieldMapLines = entity.fields.map((field) => `  ${field.key}: ${field.id},`)
-
-  return `import type { ArcubaseRuntime, ArcubaseRow } from '../runtime.js'
-
-export type ${typeName}Fields = {
-${fieldLines.join('\n')}
-}
-
-export type ${typeName}CreateInput = ${typeName}Fields
-export type ${typeName}UpdateInput = Partial<${typeName}Fields>
-
-const entityId = ${entity.id}
-const fieldIds = {
-${fieldMapLines.join('\n')}
-} as const
-
-function toArcubaseFields(fields: Partial<${typeName}Fields>): Record<string, any> {
-  const out: Record<string, any> = {}
-  for (const [key, value] of Object.entries(fields)) {
-    if (value === undefined) continue
-    const fieldId = fieldIds[key as keyof typeof fieldIds]
-    if (!fieldId) {
-      throw new Error(\`Unknown ${entity.sdkName} field: \${key}\`)
-    }
-    out[String(fieldId)] = value
-  }
-  return out
-}
-
-function fromArcubaseFields(raw: Record<string, any> | undefined): ${typeName}Fields {
-  const out: Record<string, any> = {}
-  const source = raw ?? {}
-  for (const [key, fieldId] of Object.entries(fieldIds)) {
-    if (String(fieldId) in source) {
-      out[key] = source[String(fieldId)]
-    }
-  }
-  return out as ${typeName}Fields
-}
-
-function mapRow(raw: Record<string, any>): ArcubaseRow<${typeName}Fields> {
-  return {
-    id: Number(raw.id),
-    title: typeof raw.title === 'string' ? raw.title : undefined,
-    fields: fromArcubaseFields(raw.fields),
-    raw,
-  }
-}
-
-export function create${typeName}SDK(runtime: ArcubaseRuntime) {
-  return {
-    async create(fields: ${typeName}CreateInput): Promise<number> {
-      return runtime.request<number>('POST', \`/entity/${entity.appId}/\${entityId}/insert\`, {
-        fields: toArcubaseFields(fields),
-      })
-    },
-
-    async update(rowId: string | number, fields: ${typeName}UpdateInput): Promise<boolean> {
-      const data = toArcubaseFields(fields)
-      return runtime.request<boolean>('PUT', \`/entity/${entity.appId}/\${entityId}/row/\${rowId}\`, {
-        data,
-        changed_fields: Object.keys(data).map((fieldId) => Number(fieldId)),
-      })
-    },
-
-    async get(rowId: string | number): Promise<ArcubaseRow<${typeName}Fields>> {
-      const data = await runtime.request<{ record?: Record<string, any> }>('GET', \`/entity/${entity.appId}/\${entityId}/row/\${rowId}\`)
-      return mapRow(data.record ?? {})
-    },
-
-    async query(params: { limit?: number; offset?: number; search?: Record<string, any> } = {}): Promise<{ items: ArcubaseRow<${typeName}Fields>[]; total?: number }> {
-      const data = await runtime.request<{ items?: Record<string, any>[]; total?: number }>('POST', \`/entity/${entity.appId}/\${entityId}/data-query\`, params)
-      return {
-        items: (data.items ?? []).map(mapRow),
-        total: data.total,
-      }
-    },
-  }
-}
-`
-}
-
-function emitClient(entities: ArcubaseEntity[]): string {
-  const imports = entities.map((entity) => {
-    const typeName = toPascalCase(entity.sdkName)
-    return `import { create${typeName}SDK } from './entities/${entity.sdkName}.js'`
-  })
-  const properties = entities.map((entity) => `    ${entity.sdkName}: create${toPascalCase(entity.sdkName)}SDK(runtime),`)
-  return `import { createRuntime, type ArcubaseSdkConfig } from './runtime.js'
-${imports.join('\n')}
-
-export function createArcubaseSdk(config: ArcubaseSdkConfig) {
-  const runtime = createRuntime(config)
-  return {
-${properties.join('\n')}
-  }
-}
-`
-}
+import { CLIError } from './errors.js'
 
-function emitIndex(entities: ArcubaseEntity[]): string {
-  return `export { createArcubaseSdk } from './client.js'
-export type { ArcubaseSdkConfig, ArcubaseRow } from './runtime.js'
-export { arcubaseSchema } from './schema.js'
-${entities.map((entity) => `export type { ${toPascalCase(entity.sdkName)}Fields, ${toPascalCase(entity.sdkName)}CreateInput, ${toPascalCase(entity.sdkName)}UpdateInput } from './entities/${entity.sdkName}.js'`).join('\n')}
-`
-}
+export type { GeneratedSDK, GeneratedSDKFile } from '@arcubase/code-gen'
 
 export function generateArcubaseProjectSDK(payload: unknown): GeneratedSDK {
-  const entities = normalizeEntities(payload)
-  return {
-    files: [
-      { path: 'runtime.ts', contents: emitRuntime() },
-      { path: 'schema.ts', contents: emitSchema(entities) },
-      ...entities.map((entity) => ({ path: `entities/${entity.sdkName}.ts`, contents: emitEntity(entity) })),
-      { path: 'client.ts', contents: emitClient(entities) },
-      { path: 'index.ts', contents: emitIndex(entities) },
-    ],
+  try {
+    return generateArcubaseProjectSDKCore(payload)
+  } catch (error) {
+    if (error instanceof ArcubaseCodeGenError) {
+      throw new CLIError(error.code, error.message, 2)
+    }
+    throw error
   }
 }

package/src/runtime/execute.ts

@@ -295,7 +295,7 @@ function renderDevSDKGenHelp(): string {
     '  - 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>',
+    '  - every generated field must have a configured field.key; sdk-gen fails fast when keys are missing',
     '  - 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 })',
@@ -2006,11 +2006,6 @@ type SDKGenEntityRef = {
   id: string
 }
 
-type SDKGenInitializedFieldKeys = {
-  entityId: number
-  fields: string[]
-}
-
 function extractSDKGenAppPayload(payload: unknown): Record<string, any> {
   const appPayload = unwrapResponseData(payload)
   if (!isRecord(appPayload)) {
@@ -2056,47 +2051,38 @@ function walkSDKGenFields(fields: unknown, visit: (field: Record<string, any>) =
   }
 }
 
-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 }> = []
+function assertSDKGenFieldKeysPresent(entity: Record<string, any>) {
+  const missing: Array<{ id: number; label: 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 })
+    missing.push({
+      id: field.id,
+      label: typeof field.label === 'string' && field.label.trim() ? field.label.trim() : `field ${field.id}`,
+    })
+  })
+  if (missing.length === 0) {
+    return
+  }
+
+  const entityName = typeof entity.name === 'string' && entity.name.trim() ? entity.name.trim() : `entity ${String(entity.id ?? '')}`.trim()
+  const preview = missing.slice(0, 8).map((field) => `${entityName}.${field.label} (${field.id})`)
+  const suffix = missing.length > preview.length ? `, and ${missing.length - preview.length} more` : ''
+  throw new CLIError('SDK_GEN_FIELD_KEY_REQUIRED', `missing field.key values: ${preview.join(', ')}${suffix}`, 2, {
+    operation: 'dev sdk-gen',
+    issues: missing.map((field) => ({
+      path: `entity.${String(entity.id ?? 'unknown')}.field.${field.id}.key`,
+      message: `field.key is required for ${entityName}.${field.label}`,
+    })),
+    suggestions: [
+      'set stable field.key values in Arcubase admin before running sdk-gen',
+      'rerun arcubase-admin dev sdk-gen after the schema keys are complete',
+    ],
   })
-  return updates
 }
 
 async function executeDevSDKGen(
@@ -2131,7 +2117,6 @@ async function executeDevSDKGen(
     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)
@@ -2139,15 +2124,7 @@ async function executeDevSDKGen(
     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),
-      })
-    }
+    assertSDKGenFieldKeysPresent(entityPayload)
     entities.push(entityPayload)
   }
   const generated = generateArcubaseProjectSDK({
@@ -2173,7 +2150,6 @@ async function executeDevSDKGen(
     data: {
       out: absoluteOutDir,
       files: generated.files.map((file) => file.path),
-      initializedFieldKeys,
     },
   }
 }

package/src/tests/dev_sdk_gen.test.ts

@@ -177,24 +177,16 @@ test('arcubase-admin dev sdk-gen fetches app schema and writes typed sdk files',
   assert.match(fs.readFileSync(path.join(outDir, 'client.ts'), 'utf8'), /createArcubaseSdk/)
 })
 
-test('arcubase-admin dev sdk-gen initializes missing field keys through admin auth before generation', async () => {
+test('arcubase-admin dev sdk-gen fails before generation when field keys are missing', async () => {
   const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'arcubase-sdk-gen-'))
-  const calls: Array<{ url: string; method?: string; authorization?: string; body?: any }> = []
+  const calls: Array<{ url: string; method?: string }> = []
 
-  const result = await executeCLI(
+  await assert.rejects(() => executeCLI(
     'admin',
     ['dev', 'sdk-gen', '--app-id', '3882856425', '--out', outDir],
     env as any,
     async (url, init) => {
-      const bodyText = typeof init?.body === 'string' ? init.body : undefined
-      calls.push({
-        url: String(url),
-        method: init?.method,
-        authorization: init?.headers instanceof Headers
-          ? init.headers.get('Authorization') ?? undefined
-          : (init?.headers as Record<string, string> | undefined)?.Authorization,
-        body: bodyText ? JSON.parse(bodyText) : undefined,
-      })
+      calls.push({ url: String(url), method: init?.method })
       if (String(url).endsWith('/api/apps/3882856425')) {
         return new Response(JSON.stringify({ data: appDetail() }), { status: 200 })
       }
@@ -204,23 +196,15 @@ test('arcubase-admin dev sdk-gen initializes missing field keys through admin au
       if (String(url).endsWith('/api/apps/3882856425/entity/3883547182')) {
         return new Response(JSON.stringify({ data: entityDetailWithoutFieldKeys() }), { status: 200 })
       }
-      if (String(url).endsWith('/api/apps/3882856425/entity/3883547182/custom-keys')) {
-        return new Response(JSON.stringify({ data: entityDetail() }), { status: 200 })
-      }
       return new Response(JSON.stringify({ error: { message: `unexpected url ${url}` } }), { status: 404 })
     },
-  )
+  ), (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'SDK_GEN_FIELD_KEY_REQUIRED')
+    assert.match(error.message, /编故事\.时代 \(1006\)/)
+    return true
+  })
 
-  assert.equal(result.kind, 'result')
-  const customKeysCall = calls.find((call) => call.url.endsWith('/api/apps/3882856425/entity/3883547182/custom-keys'))
-  assert.ok(customKeysCall)
-  assert.equal(customKeysCall.method, 'PUT')
-  assert.equal(customKeysCall.authorization, 'Bearer tok')
-  assert.deepEqual(customKeysCall.body, [
-    { id: 1006, key: 'field1006' },
-    { id: 1013, key: 'field1013' },
-    { id: 1011, key: 'field1011' },
-  ])
-  assert.match(fs.readFileSync(path.join(outDir, 'entities/story.ts'), 'utf8'), /field1011: string/)
-  assert.deepEqual(result.data.initializedFieldKeys, [{ entityId: 3883547182, fields: ['field1006', 'field1013', 'field1011'] }])
+  assert.equal(calls.some((call) => call.url.endsWith('/custom-keys')), false)
+  assert.equal(fs.existsSync(path.join(outDir, 'index.ts')), false)
 })

package/src/tests/help.test.ts

@@ -220,6 +220,17 @@ test('admin dashboard update-layout help-examples show top-level layout array',
   assert.match(out.text, /do not wrap the array/)
 })
 
+test('admin dashboard update-options help-examples show user visibility scope', async () => {
+  const out = await executeCLI('admin', ['dashboard', 'update-options', '--help-examples'], env as any, async () => new Response('{}'))
+  assert.equal(out.kind, 'help')
+  assert.match(out.text, /arcubase-admin dashboard update-options --help-examples/)
+  assert.match(out.text, /"changed":\["users"\]/)
+  assert.match(out.text, /"users":\[\{"type":"user","id":2188889901\}\]/)
+  assert.match(out.text, /currentSpeaker\.arcubaseUserId/)
+  assert.match(out.text, /verify from the user side with arcubase app get/)
+  assert.doesNotMatch(out.text, /"type":"member"/)
+})
+
 test('admin widget preview-data help-examples show chart query body without widget id', async () => {
   const out = await executeCLI('admin', ['widget', 'preview-data', '--help-examples'], env as any, async () => new Response('{}'))
   assert.equal(out.kind, 'help')