@carthooks/arcubase-cli 0.1.25 → 0.1.26

package/src/runtime/execute.ts

@@ -295,10 +295,10 @@ function renderDevSDKGenHelp(): string {
     '  - arcubase-admin dev sdk-gen --app-id <app_id> --out src/arcubase',
     '',
     'requirements:',
+    '  - every generated ingress must have a configured ingress.key; sdk-gen fails fast when keys are missing',
     '  - 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 })',
+    '  - ingress.key and field.key values must be stable unique TypeScript identifiers',
+    '  - generated code accepts createArcubaseClient({ baseURL, accessToken, refreshToken }).ingress("<IngressKey>")',
   ].join('\n')
 }
 
@@ -2006,6 +2006,8 @@ type SDKGenEntityRef = {
   id: string
 }
 
+type SDKGenIngressRef = Record<string, any>
+
 function extractSDKGenAppPayload(payload: unknown): Record<string, any> {
   const appPayload = unwrapResponseData(payload)
   if (!isRecord(appPayload)) {
@@ -2085,6 +2087,96 @@ function assertSDKGenFieldKeysPresent(entity: Record<string, any>) {
   })
 }
 
+function extractSDKGenIngressRefs(payload: unknown): SDKGenIngressRef[] {
+  const data = unwrapResponseData(payload)
+  const source = Array.isArray(data)
+    ? data
+    : isRecord(data) && Array.isArray(data.list)
+      ? data.list
+      : []
+  return source.filter((item): item is SDKGenIngressRef => isRecord(item))
+}
+
+function ingressKeyOf(ingress: Record<string, any>): string {
+  return typeof ingress.key === 'string' ? ingress.key.trim() : ''
+}
+
+function ingressHashIDOf(ingress: Record<string, any>): string {
+  if (typeof ingress.hash_id === 'string' && ingress.hash_id.trim()) {
+    return ingress.hash_id.trim()
+  }
+  if (typeof ingress.hashId === 'string' && ingress.hashId.trim()) {
+    return ingress.hashId.trim()
+  }
+  return ''
+}
+
+function assertSDKGenIngressesReady(ingresses: SDKGenIngressRef[]) {
+  if (ingresses.length === 0) {
+    throw new CLIError('SDK_GEN_NO_INGRESSES', 'sdk-gen could not find ingress definitions for this app', 2, {
+      operation: 'dev sdk-gen',
+      suggestions: ['create at least one access rule with a stable ingress.key before running sdk-gen'],
+    })
+  }
+
+  const seen = new Set<string>()
+  const missingKey: SDKGenIngressRef[] = []
+  const missingHash: SDKGenIngressRef[] = []
+  const invalidKey: string[] = []
+  const duplicateKey: string[] = []
+
+  for (const ingress of ingresses) {
+    const key = ingressKeyOf(ingress)
+    if (!key) {
+      missingKey.push(ingress)
+      continue
+    }
+    if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(key)) {
+      invalidKey.push(key)
+    }
+    if (seen.has(key)) {
+      duplicateKey.push(key)
+    }
+    seen.add(key)
+    if (!ingressHashIDOf(ingress)) {
+      missingHash.push(ingress)
+    }
+  }
+
+  if (missingKey.length > 0) {
+    const preview = missingKey.slice(0, 8).map((ingress) => String(ingress.name ?? ingress.id ?? 'unnamed ingress'))
+    const suffix = missingKey.length > preview.length ? `, and ${missingKey.length - preview.length} more` : ''
+    throw new CLIError('SDK_GEN_INGRESS_KEY_REQUIRED', `missing ingress.key values: ${preview.join(', ')}${suffix}`, 2, {
+      operation: 'dev sdk-gen',
+      issues: missingKey.map((ingress) => ({
+        path: `ingress.${String(ingress.id ?? 'unknown')}.key`,
+        message: `ingress.key is required for ${String(ingress.name ?? ingress.id ?? 'unnamed ingress')}`,
+      })),
+      suggestions: [
+        'set stable ingress.key values in Arcubase admin before running sdk-gen',
+        'rerun arcubase-admin dev sdk-gen after ingress keys are complete',
+      ],
+    })
+  }
+  if (invalidKey.length > 0) {
+    throw new CLIError('SDK_GEN_INVALID_INGRESS_KEY', `invalid ingress.key values: ${invalidKey.join(', ')}`, 2, {
+      operation: 'dev sdk-gen',
+      suggestions: ['use TypeScript identifier keys such as publicEntry or customerPortal'],
+    })
+  }
+  if (duplicateKey.length > 0) {
+    throw new CLIError('SDK_GEN_DUPLICATE_INGRESS_KEY', `duplicate ingress.key values: ${duplicateKey.join(', ')}`, 2, {
+      operation: 'dev sdk-gen',
+    })
+  }
+  if (missingHash.length > 0) {
+    throw new CLIError('SDK_GEN_INGRESS_HASH_ID_REQUIRED', 'sdk-gen expected hash_id for every ingress definition', 2, {
+      operation: 'dev sdk-gen',
+      suggestions: ['upgrade Arcubase server so admin access-rule list returns hash_id'],
+    })
+  }
+}
+
 async function executeDevSDKGen(
   runtimeEnv: RuntimeEnv,
   flags: Record<string, string | boolean>,
@@ -2116,7 +2208,7 @@ async function executeDevSDKGen(
   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 ingresses: SDKGenIngressRef[] = []
   for (const entityRef of entityRefs) {
     const entityEndpoint = `/api/apps/${encodeURIComponent(appId)}/entity/${encodeURIComponent(entityRef.id)}`
     const entityDetail = await requestJSON(runtimeEnv, 'GET', entityEndpoint, undefined, fetchImpl)
@@ -2125,12 +2217,21 @@ async function executeDevSDKGen(
       throw new CLIError('SDK_GEN_INVALID_SCHEMA', 'sdk-gen expected entity detail response data', 2)
     }
     assertSDKGenFieldKeysPresent(entityPayload)
-    entities.push(entityPayload)
+    const ingressEndpoint = `/api/apps/${encodeURIComponent(appId)}/entity/${encodeURIComponent(entityRef.id)}/ingress`
+    const ingressList = await requestJSON(runtimeEnv, 'GET', ingressEndpoint, undefined, fetchImpl)
+    const entityIngresses = extractSDKGenIngressRefs(ingressList.data).map((ingress) => ({
+      ...ingress,
+      hash_id: ingressHashIDOf(ingress),
+      key: ingressKeyOf(ingress),
+      entity: entityPayload,
+    }))
+    ingresses.push(...entityIngresses)
   }
+  assertSDKGenIngressesReady(ingresses)
   const generated = generateArcubaseProjectSDK({
     id: resolveSDKGenAppId(appId, appPayload),
     name: typeof appPayload.name === 'string' ? appPayload.name : undefined,
-    entities,
+    ingresses,
   })
   const absoluteOutDir = path.resolve(process.cwd(), outDir)
 

package/src/tests/dev_sdk_gen.test.ts

@@ -21,7 +21,7 @@ const env = {
 function appDetail() {
   return {
     id: 3882856425,
-    name: '故事应用',
+    name: 'Demo App',
     entities: {},
   }
 }
@@ -30,7 +30,7 @@ function entityList() {
   return [
     {
       id: 3883547182,
-      name: '编故事',
+      name: 'Records',
     },
   ]
 }
@@ -42,7 +42,7 @@ function appDetailWithEntityList() {
     entities: [
       {
         id: 3883547182,
-        name: '编故事',
+        name: 'Records',
       },
     ],
   }
@@ -52,12 +52,11 @@ function entityDetail() {
   return {
     id: 3883547182,
     app_id: 3882856425,
-    name: '编故事',
-    key: 'story',
+    name: 'Records',
     fields: [
-      { id: 1006, label: '时代', key: 'era', type: 'select', required: false, options: { options: { items: [{ key: 1, value: '现代' }] } } },
-      { id: 1013, label: '你刚刚', key: 'recentEvent', type: 'text', required: false, options: {} },
-      { id: 1011, label: '故事', key: 'story', type: 'textarea', required: true, options: {} },
+      { id: 1006, label: 'Title', key: 'title', type: 'text', required: true, options: {} },
+      { id: 1013, label: 'Status', key: 'status', type: 'select', required: false, options: { options: { items: [{ key: 1, value: 'Open' }] } } },
+      { id: 1011, label: 'Notes', key: 'notes', type: 'textarea', required: false, options: {} },
     ],
   }
 }
@@ -70,76 +69,125 @@ function entityDetailWithoutFieldKeys() {
 
 function sdkSchemaPayload() {
   return {
-    ...appDetailWithEntityList(),
-    entities: [
-      {
-        ...entityDetail(),
-        key: 'story',
+    id: 3882856425,
+    name: 'Demo App',
+    ingresses: [ingressDefinition()],
+  }
+}
+
+function ingressDefinition(actions = ['view', 'add', 'edit', 'delete', 'bulk_update', 'export', 'batch_print', 'tag_manage', 'archive']) {
+  return {
+    id: 9001,
+    hash_id: '8WR5Kypbw9KQK20',
+    key: 'publicEntry',
+    name: 'Public entry',
+    entity: entityDetail(),
+    options: {
+      policy: {
+        actions,
+        all_fields_read: true,
+        all_fields_write: true,
+        fields: [],
       },
-    ],
+      list_options: {},
+    },
   }
 }
 
-test('generateArcubaseProjectSDK emits typed key based entity sdk', () => {
+test('generateArcubaseProjectSDK emits typed ingress sdk selected from client.ingress', () => {
   const result = generateArcubaseProjectSDK(sdkSchemaPayload())
 
   assert.deepEqual(result.files.map((file) => file.path).sort(), [
     'client.ts',
-    'entities/story.ts',
     'index.ts',
+    'ingresses/publicEntry.ts',
     'runtime.ts',
     'schema.ts',
   ])
 
   const client = result.files.find((file) => file.path === 'client.ts')?.contents ?? ''
-  assert.match(client, /createArcubaseSdk/)
-  assert.match(client, /story: createStorySDK\(runtime\)/)
+  assert.match(client, /createArcubaseClient/)
+  assert.match(client, /ingress<K extends ArcubaseIngressKey>\(key: K\)/)
+  assert.match(client, /case ["']publicEntry["']/)
 
   const runtime = result.files.find((file) => file.path === 'runtime.ts')?.contents ?? ''
   assert.match(runtime, /accessToken/)
   assert.match(runtime, /refreshToken/)
 
-  const story = result.files.find((file) => file.path === 'entities/story.ts')?.contents ?? ''
-  assert.match(story, /export type StoryFields =/)
-  assert.match(story, /era\?: number \| string/)
-  assert.match(story, /recentEvent\?: string/)
-  assert.match(story, /story: string/)
-  assert.match(story, /create\(fields: StoryCreateInput\)/)
-  assert.match(story, /update\(rowId: string \| number, fields: StoryUpdateInput\)/)
-  assert.match(story, /toArcubaseFields\(fields\)/)
-  assert.match(story, /changed_fields: Object.keys\(data\)\.map\(\(fieldId\) => Number\(fieldId\)\)/)
-  assert.match(story, /\/entity\/3882856425\/\$\{entityId\}\/insert/)
+  const ingress = result.files.find((file) => file.path === 'ingresses/publicEntry.ts')?.contents ?? ''
+  assert.match(ingress, /export type PublicEntryFields =/)
+  assert.match(ingress, /title: string/)
+  assert.match(ingress, /status\?: number \| string/)
+  assert.match(ingress, /notes\?: string/)
+  assert.match(ingress, /create\(fields: PublicEntryCreateInput\)/)
+  assert.match(ingress, /update\(rowId: string \| number, fields: PublicEntryUpdateInput\)/)
+  assert.match(ingress, /query\(params: PublicEntryQueryParams = {}\)/)
+  assert.match(ingress, /delete\(selection: PublicEntrySelection\)/)
+  assert.match(ingress, /bulkUpdate\(selection: PublicEntrySelection, fields: PublicEntryBulkUpdateField\[\]\)/)
+  assert.match(ingress, /exportRows\(options: PublicEntryExportOptions = {}\)/)
+  assert.match(ingress, /batchPrint\(selection: PublicEntrySelection/)
+  assert.match(ingress, /archive\(selection: PublicEntrySelection\)/)
+  assert.match(ingress, /tags:/)
+  assert.match(ingress, /policy_id: ingressId/)
 
   const schema = result.files.find((file) => file.path === 'schema.ts')?.contents ?? ''
-  assert.match(schema, /"story"/)
+  assert.match(schema, /"publicEntry"/)
   assert.match(schema, /"fieldId": 1011/)
   assert.match(schema, /"entityId": 3883547182/)
+  assert.match(schema, /"ingressId": "8WR5Kypbw9KQK20"/)
+  assert.doesNotMatch(schema, /entity3883547182/)
 })
 
 test('generateArcubaseProjectSDK rejects missing field keys', () => {
   const payload = sdkSchemaPayload()
-  payload.entities[0].fields[1].key = ''
+  payload.ingresses[0].entity.fields[1].key = ''
 
   assert.throws(() => generateArcubaseProjectSDK(payload), (error: unknown) => {
     assert.ok(error instanceof CLIError)
     assert.equal(error.code, 'SDK_GEN_FIELD_KEY_REQUIRED')
-    assert.match(error.message, /你刚刚/)
+    assert.match(error.message, /Status/)
     return true
   })
 })
 
 test('generateArcubaseProjectSDK rejects duplicate field keys within an entity', () => {
   const payload = sdkSchemaPayload()
-  payload.entities[0].fields[1].key = 'story'
+  payload.ingresses[0].entity.fields[1].key = 'notes'
 
   assert.throws(() => generateArcubaseProjectSDK(payload), (error: unknown) => {
     assert.ok(error instanceof CLIError)
     assert.equal(error.code, 'SDK_GEN_DUPLICATE_FIELD_KEY')
-    assert.match(error.message, /story/)
+    assert.match(error.message, /notes/)
+    return true
+  })
+})
+
+test('generateArcubaseProjectSDK rejects missing ingress keys', () => {
+  const payload = sdkSchemaPayload()
+  payload.ingresses[0].key = ''
+
+  assert.throws(() => generateArcubaseProjectSDK(payload), (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'SDK_GEN_INGRESS_KEY_REQUIRED')
+    assert.match(error.message, /Public entry/)
     return true
   })
 })
 
+test('generateArcubaseProjectSDK only emits methods allowed by ingress actions', () => {
+  const payload = {
+    id: 3882856425,
+    ingresses: [ingressDefinition(['view'])],
+  }
+
+  const result = generateArcubaseProjectSDK(payload)
+  const ingress = result.files.find((file) => file.path === 'ingresses/publicEntry.ts')?.contents ?? ''
+  assert.match(ingress, /query\(params: PublicEntryQueryParams = {}\)/)
+  assert.doesNotMatch(ingress, /create\(fields:/)
+  assert.doesNotMatch(ingress, /update\(rowId:/)
+  assert.doesNotMatch(ingress, /bulkUpdate\(/)
+})
+
 test('arcubase-admin dev sdk-gen fetches app schema and writes typed sdk files', async () => {
   const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'arcubase-sdk-gen-'))
   const calls: Array<{ url: string; method?: string }> = []
@@ -159,6 +207,9 @@ test('arcubase-admin dev sdk-gen fetches app schema and writes typed sdk files',
       if (String(url).endsWith('/api/apps/3882856425/entity/3883547182')) {
         return new Response(JSON.stringify({ data: entityDetail() }), { status: 200 })
       }
+      if (String(url).endsWith('/api/apps/3882856425/entity/3883547182/ingress')) {
+        return new Response(JSON.stringify({ data: { list: [ingressDefinition()] } }), { status: 200 })
+      }
       return new Response(JSON.stringify({ error: { message: `unexpected url ${url}` } }), { status: 404 })
     },
   )
@@ -171,10 +222,13 @@ test('arcubase-admin dev sdk-gen fetches app schema and writes typed sdk files',
   assert.match(calls[1].url, /\/api\/apps\/3882856425\/entities$/)
   assert.equal(calls[2].method, 'GET')
   assert.match(calls[2].url, /\/api\/apps\/3882856425\/entity\/3883547182$/)
+  assert.equal(calls[3].method, 'GET')
+  assert.match(calls[3].url, /\/api\/apps\/3882856425\/entity\/3883547182\/ingress$/)
   assert.ok(fs.existsSync(path.join(outDir, 'index.ts')))
   assert.ok(fs.existsSync(path.join(outDir, 'client.ts')))
-  assert.ok(fs.existsSync(path.join(outDir, 'entities/story.ts')))
-  assert.match(fs.readFileSync(path.join(outDir, 'client.ts'), 'utf8'), /createArcubaseSdk/)
+  assert.ok(fs.existsSync(path.join(outDir, 'ingresses/publicEntry.ts')))
+  assert.match(fs.readFileSync(path.join(outDir, 'client.ts'), 'utf8'), /createArcubaseClient/)
+  assert.notEqual(fs.existsSync(path.join(outDir, 'entities')), true)
 })
 
 test('arcubase-admin dev sdk-gen fails before generation when field keys are missing', async () => {
@@ -196,15 +250,50 @@ test('arcubase-admin dev sdk-gen fails before generation when field keys are mis
       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/ingress')) {
+        return new Response(JSON.stringify({ data: { list: [ingressDefinition()] } }), { 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\)/)
+    assert.match(error.message, /Records\.Title \(1006\)/)
     return true
   })
 
   assert.equal(calls.some((call) => call.url.endsWith('/custom-keys')), false)
   assert.equal(fs.existsSync(path.join(outDir, 'index.ts')), false)
 })
+
+test('arcubase-admin dev sdk-gen fails before generation when ingress keys are missing', async () => {
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'arcubase-sdk-gen-'))
+
+  await assert.rejects(() => executeCLI(
+    'admin',
+    ['dev', 'sdk-gen', '--app-id', '3882856425', '--out', outDir],
+    env as any,
+    async (url) => {
+      if (String(url).endsWith('/api/apps/3882856425')) {
+        return new Response(JSON.stringify({ data: appDetail() }), { status: 200 })
+      }
+      if (String(url).endsWith('/api/apps/3882856425/entities')) {
+        return new Response(JSON.stringify({ data: entityList() }), { status: 200 })
+      }
+      if (String(url).endsWith('/api/apps/3882856425/entity/3883547182')) {
+        return new Response(JSON.stringify({ data: entityDetail() }), { status: 200 })
+      }
+      if (String(url).endsWith('/api/apps/3882856425/entity/3883547182/ingress')) {
+        return new Response(JSON.stringify({ data: { list: [{ ...ingressDefinition(), key: '' }] } }), { 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_INGRESS_KEY_REQUIRED')
+    assert.match(error.message, /Public entry/)
+    return true
+  })
+
+  assert.equal(fs.existsSync(path.join(outDir, 'index.ts')), false)
+})

package/src/tests/help.test.ts

@@ -36,8 +36,9 @@ test('admin dev sdk-gen help documents typed project sdk generation', async () =
   assert.match(commandHelp.text, /arcubase-admin dev sdk-gen/)
   assert.match(commandHelp.text, /--app-id/)
   assert.match(commandHelp.text, /--out/)
+  assert.match(commandHelp.text, /ingress\.key/)
   assert.match(commandHelp.text, /field\.key/)
-  assert.match(commandHelp.text, /createArcubaseSdk\(\{ baseURL, accessToken, refreshToken \}\)/)
+  assert.match(commandHelp.text, /createArcubaseClient\(\{ baseURL, accessToken, refreshToken \}\)\.ingress\("<IngressKey>"\)/)
 })
 
 test('user root help exposes reset surface nouns only', async () => {

package/src/tests/zod_registry.test.ts

@@ -46,6 +46,7 @@ test('AppIngressCreateReqVO accepts nested ConditionSet with field EntityProp co
   assert.ok(schema)
 
   const result = schema.safeParse({
+    key: 'salesOwnOrWestRegion',
     name: 'Sales own or west region',
     enabled: true,
     type: 'form',