@carthooks/arcubase-cli 0.1.21 → 0.1.22

package/src/tests/dev_sdk_gen.test.ts

@@ -0,0 +1,226 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { generateArcubaseProjectSDK } from '../runtime/dev_sdk_gen.js'
+import { executeCLI } from '../runtime/execute.js'
+import { CLIError } from '../runtime/errors.js'
+
+const env = {
+  ARCUBASE_BASE_URL: 'https://arcubase.example.com',
+  ARCUBASE_ACCESS_TOKEN: 'tok',
+  ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
+  ARCUBASE_TRACE_ID: '',
+  ARCUBASE_SUBJECT_TYPE: '',
+  ARCUBASE_SUBJECT_ID: '',
+  ARCUBASE_TOKEN_EXPIRES_AT: '',
+}
+
+function appDetail() {
+  return {
+    id: 3882856425,
+    name: '故事应用',
+    entities: {},
+  }
+}
+
+function entityList() {
+  return [
+    {
+      id: 3883547182,
+      name: '编故事',
+    },
+  ]
+}
+
+function appDetailWithEntityList() {
+  return {
+    id: 3882856425,
+    name: '故事应用',
+    entities: [
+      {
+        id: 3883547182,
+        name: '编故事',
+      },
+    ],
+  }
+}
+
+function entityDetail() {
+  return {
+    id: 3883547182,
+    app_id: 3882856425,
+    name: '编故事',
+    key: 'story',
+    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: {} },
+    ],
+  }
+}
+
+function entityDetailWithoutFieldKeys() {
+  const detail = entityDetail()
+  detail.fields = detail.fields.map((field) => ({ ...field, key: '' }))
+  return detail
+}
+
+function sdkSchemaPayload() {
+  return {
+    ...appDetailWithEntityList(),
+    entities: [
+      {
+        ...entityDetail(),
+        key: 'story',
+      },
+    ],
+  }
+}
+
+test('generateArcubaseProjectSDK emits typed key based entity sdk', () => {
+  const result = generateArcubaseProjectSDK(sdkSchemaPayload())
+
+  assert.deepEqual(result.files.map((file) => file.path).sort(), [
+    'client.ts',
+    'entities/story.ts',
+    'index.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\)/)
+
+  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 schema = result.files.find((file) => file.path === 'schema.ts')?.contents ?? ''
+  assert.match(schema, /"story"/)
+  assert.match(schema, /"fieldId": 1011/)
+  assert.match(schema, /"entityId": 3883547182/)
+})
+
+test('generateArcubaseProjectSDK rejects missing field keys', () => {
+  const payload = sdkSchemaPayload()
+  payload.entities[0].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, /你刚刚/)
+    return true
+  })
+})
+
+test('generateArcubaseProjectSDK rejects duplicate field keys within an entity', () => {
+  const payload = sdkSchemaPayload()
+  payload.entities[0].fields[1].key = 'story'
+
+  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/)
+    return true
+  })
+})
+
+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 }> = []
+
+  const result = await executeCLI(
+    'admin',
+    ['dev', 'sdk-gen', '--app-id', '3882856425', '--out', outDir],
+    env as any,
+    async (url, init) => {
+      calls.push({ url: String(url), method: init?.method })
+      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 })
+      }
+      return new Response(JSON.stringify({ error: { message: `unexpected url ${url}` } }), { status: 404 })
+    },
+  )
+
+  assert.equal(result.kind, 'result')
+  assert.deepEqual(result.commandPath, ['dev', 'sdk-gen'])
+  assert.equal(calls[0].method, 'GET')
+  assert.match(calls[0].url, /\/api\/apps\/3882856425$/)
+  assert.equal(calls[1].method, 'GET')
+  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.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/)
+})
+
+test('arcubase-admin dev sdk-gen initializes missing field keys through admin auth before generation', async () => {
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'arcubase-sdk-gen-'))
+  const calls: Array<{ url: string; method?: string; authorization?: string; body?: any }> = []
+
+  const result = await 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,
+      })
+      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: 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 })
+    },
+  )
+
+  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'] }])
+})

package/src/tests/docs_readability.test.ts

@@ -68,6 +68,21 @@ test('runtime docs do not use retired table create and row probe names', () => {
   }
 })
 
+test('runtime docs document dashboard and widget single success paths', () => {
+  const dashboard = fs.readFileSync(path.join(root, 'dashboard.md'), 'utf8')
+  const widgets = fs.readFileSync(path.join(root, 'widgets.md'), 'utf8')
+  assert.match(dashboard, /arcubase dashboard get/)
+  assert.match(dashboard, /arcubase-admin dashboard list/)
+  assert.match(dashboard, /not exposed/)
+  assert.match(widgets, /arcubase-admin widget list/)
+  assert.match(widgets, /--widget-id/)
+  for (const aggregate of ['sum', 'avg', 'max', 'min', 'count', 'distinct_count']) {
+    assert.match(widgets, new RegExp(`\\\`${aggregate}\\\``))
+  }
+  assert.match(widgets, /unsupported aggregate names are invalid request bodies/)
+  assert.doesNotMatch(widgets, /widgets_id/)
+})
+
 test('scenario examples exist and are readable', () => {
   for (const dir of ['oms-01', 'wms-01', 'crm-01']) {
     const readme = path.join(root, 'examples', dir, 'README.md')

package/src/tests/execute_validation.test.ts

@@ -1094,6 +1094,135 @@ test('entry fixed app tables query cannot be disabled by query file', async () =
   assert.equal(out.data.url, 'https://arcubase.example.com/api/entry?include_app_tables=true')
 })
 
+test('dashboard and widget commands map to approved endpoints', async () => {
+  const adminWidgetList = await executeCLI(
+    'admin',
+    ['widget', 'list', '--app-id', 'app_1', '--type', 'dashboard', '--dashboard-id', '100'],
+    env as any,
+    async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }),
+  )
+  assert.equal(adminWidgetList.kind, 'result')
+  assert.equal(adminWidgetList.data.url, 'https://arcubase.example.com/api/apps/app_1/widgets?type=dashboard&dashboard_id=100')
+  assert.equal(adminWidgetList.data.method, 'GET')
+
+  const userDashboardWidgets = await executeCLI(
+    'user',
+    ['dashboard', 'widgets', '--app-id', 'app_1', '--dashboard-id', 'dash_1'],
+    env as any,
+    async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }),
+  )
+  assert.equal(userDashboardWidgets.kind, 'result')
+  assert.equal(userDashboardWidgets.data.url, 'https://arcubase.example.com/api/dashboard/app_1/dash_1/widgets')
+  assert.equal(userDashboardWidgets.data.method, 'GET')
+
+  const userWidgetData = await executeCLI(
+    'user',
+    ['widget', 'data', '--app-id', 'app_1', '--body-json', '{"dashboard_id":100,"type":1}'],
+    env as any,
+    async (url, init) => new Response(JSON.stringify({
+      url,
+      method: init?.method,
+      body: init?.body ? JSON.parse(String(init.body)) : null,
+    }), { status: 200 }),
+  )
+  assert.equal(userWidgetData.kind, 'result')
+  assert.equal(userWidgetData.data.url, 'https://arcubase.example.com/api/apps/app_1/widgets-data')
+  assert.equal(userWidgetData.data.method, 'POST')
+  assert.deepEqual(userWidgetData.data.body, { dashboard_id: 100, type: 1 })
+})
+
+test('widget preview-data rejects unsupported aggregate before request', async () => {
+  let called = false
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      [
+        'widget',
+        'preview-data',
+        '--app-id',
+        'app_1',
+        '--body-json',
+        '{"dataSource":2188891001,"dataSourceType":"entity","measures":[{"Name":"median_amount","FieldID":1004,"Aggregate":"median"}]}',
+      ],
+      env as any,
+      async () => {
+        called = true
+        return new Response('{}', { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.equal(error.details?.requestType, 'AppPreviewWidgetsDataReqVO')
+    assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.measures.0.Aggregate'))
+    assert.ok((error.details?.docHints ?? []).some((item) => item.file === '/runtime/arcubase-sdk/docs/runtime-reference/widgets.md'))
+    return true
+  })
+  assert.equal(called, false)
+})
+
+test('widget preview-data rejects field dimensions without IsField true before request', async () => {
+  let called = false
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      [
+        'widget',
+        'preview-data',
+        '--app-id',
+        'app_1',
+        '--body-json',
+        '{"dataSource":2188891001,"dataSourceType":"entity","dimensions":[{"FieldID":1004,"Name":"Source"}],"measures":[{"Name":"Total Amount","FieldID":1005,"Aggregate":"sum"}]}',
+      ],
+      env as any,
+      async () => {
+        called = true
+        return new Response('{}', { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.equal(error.details?.requestType, 'AppPreviewWidgetsDataReqVO')
+    assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.dimensions.0.IsField'))
+    assert.ok((error.details?.commonMistakes ?? []).includes('field dimensions with FieldID must set IsField:true'))
+    return true
+  })
+  assert.equal(called, false)
+})
+
+test('widget update rejects chart field dimensions without IsField true before request', async () => {
+  let called = false
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      [
+        'widget',
+        'update',
+        '--app-id',
+        'app_1',
+        '--widget-id',
+        'widget_1',
+        '--body-json',
+        '{"entity_id":2188891001,"options":{"charts":{"entity_id":2188891001,"dimensions":[{"FieldID":1004,"IsField":false,"Name":"Source"}],"measures":[{"Name":"Total Amount","FieldID":1005,"Aggregate":"sum"}]}}}',
+      ],
+      env as any,
+      async () => {
+        called = true
+        return new Response('{}', { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.equal(error.details?.requestType, 'AppUpdateWidgetsReqVO')
+    assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.options.charts.dimensions.0.IsField'))
+    assert.ok((error.details?.commonMistakes ?? []).includes('field dimensions with FieldID must set IsField:true'))
+    return true
+  })
+  assert.equal(called, false)
+})
+
 test('upstream http failures include endpoint status and body details', async () => {
   await assert.rejects(async () => {
     await executeCLI('user', ['entry'], env as any, async () => new Response('', { status: 500 }))

package/src/tests/help.test.ts

@@ -21,10 +21,25 @@ test('admin root help exposes reset surface nouns only', async () => {
   assert.match(out.text, /\btable\b/)
   assert.match(out.text, /\baccess-rule\b/)
   assert.match(out.text, /\bworkflow\b/)
+  assert.match(out.text, /\bdev\b/)
   assert.doesNotMatch(out.text, /\bentity\b/)
   assert.doesNotMatch(out.text, /\bingress\b/)
 })
 
+test('admin dev sdk-gen help documents typed project sdk generation', async () => {
+  const moduleHelp = await executeCLI('admin', ['dev', '--help'], env as any, async () => new Response('{}'))
+  assert.equal(moduleHelp.kind, 'help')
+  assert.match(moduleHelp.text, /sdk-gen/)
+
+  const commandHelp = await executeCLI('admin', ['dev', 'sdk-gen', '--help'], env as any, async () => new Response('{}'))
+  assert.equal(commandHelp.kind, 'help')
+  assert.match(commandHelp.text, /arcubase-admin dev sdk-gen/)
+  assert.match(commandHelp.text, /--app-id/)
+  assert.match(commandHelp.text, /--out/)
+  assert.match(commandHelp.text, /field\.key/)
+  assert.match(commandHelp.text, /createArcubaseSdk\(\{ baseURL, accessToken, refreshToken \}\)/)
+})
+
 test('user root help exposes reset surface nouns only', async () => {
   const out = await executeCLI('user', ['--help'], env as any, async () => new Response('{}'))
   assert.equal(out.kind, 'help')
@@ -99,6 +114,30 @@ test('admin table create help gives one-call body-json example', async () => {
   assert.match(out.text, /"type":"textarea"/)
 })
 
+test('dashboard and widget help exposes agent-readable body docs and flags', async () => {
+  const adminDashboardCreate = await executeCLI('admin', ['dashboard', 'create', '--help'], env as any, async () => new Response('{}'))
+  assert.equal(adminDashboardCreate.kind, 'help')
+  assert.match(adminDashboardCreate.text, /arcubase-admin dashboard create/)
+  assert.match(adminDashboardCreate.text, /endpoint: \/apps\/:app_id\/dashboard/)
+  assert.match(adminDashboardCreate.text, /body: DashboardCreateReqVO via --body-json/)
+  assert.match(adminDashboardCreate.text, /^types:$/m)
+  assert.match(adminDashboardCreate.text, /^docs:$/m)
+
+  const adminWidgetList = await executeCLI('admin', ['widget', 'list', '--help'], env as any, async () => new Response('{}'))
+  assert.equal(adminWidgetList.kind, 'help')
+  assert.match(adminWidgetList.text, /arcubase-admin widget list/)
+  assert.match(adminWidgetList.text, /endpoint: \/apps\/:app_id\/widgets/)
+  assert.match(adminWidgetList.text, /query flags: --type, --dashboard-id, --ingress-id, --query-file/)
+  assert.match(adminWidgetList.text, /^docs:$/m)
+
+  const userWidgetData = await executeCLI('user', ['widget', 'data', '--help'], env as any, async () => new Response('{}'))
+  assert.equal(userWidgetData.kind, 'help')
+  assert.match(userWidgetData.text, /arcubase widget data/)
+  assert.match(userWidgetData.text, /body: FetchWidgetsDataReqVO via --body-json/)
+  assert.match(userWidgetData.text, /^types:$/m)
+  assert.match(userWidgetData.text, /^docs:$/m)
+})
+
 test('admin access-rule help gives update whitelist and assign-users body-json examples', async () => {
   const create = await executeCLI('admin', ['access-rule', 'create', '--help'], env as any, async () => new Response('{}'))
   assert.equal(create.kind, 'help')
@@ -166,6 +205,37 @@ test('admin access-rule bulk-apply help-examples show transactional matrix body'
   assert.doesNotMatch(out.text, /"type":"member"/)
 })
 
+test('admin dashboard update-layout help-examples show top-level layout array', async () => {
+  const out = await executeCLI('admin', ['dashboard', 'update-layout', '--help-examples'], env as any, async () => new Response('{}'))
+  assert.equal(out.kind, 'help')
+  assert.match(out.text, /arcubase-admin dashboard update-layout --help-examples/)
+  assert.match(out.text, /--body-json '\[\{"id":2188892001,"x":0,"y":0,"w":12,"h":6\}\]'/)
+  assert.match(out.text, /the request body is a top-level array/)
+  assert.match(out.text, /do not wrap the array/)
+})
+
+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')
+  assert.match(out.text, /arcubase-admin widget preview-data --help-examples/)
+  assert.match(out.text, /"dataSource":2188891001/)
+  assert.match(out.text, /"dataSourceType":"entity"/)
+  assert.match(out.text, /"Aggregate":"sum"/)
+  assert.match(out.text, /preview-data does not accept --widget-id/)
+  assert.match(out.text, /do not send widget_id or id/)
+  assert.doesNotMatch(out.text, /--widget-id <widget_id>/)
+})
+
+test('admin widget create help-examples avoid manual options type', async () => {
+  const out = await executeCLI('admin', ['widget', 'create', '--help-examples'], env as any, async () => new Response('{}'))
+  assert.equal(out.kind, 'help')
+  assert.match(out.text, /arcubase-admin widget create --help-examples/)
+  assert.match(out.text, /"type":"chart","options":\{"dashboard_id":2188892001\}/)
+  assert.match(out.text, /do not set options.type by hand/)
+  assert.match(out.text, /dashboard_id selects a dashboard widget/)
+  assert.doesNotMatch(out.text, /"options":\{"dashboard_id":2188892001,"type":/)
+})
+
 test('user row bulk-update help-examples show ids and condition selection bodies', async () => {
   const out = await executeCLI('user', ['row', 'bulk-update', '--help-examples'], env as any, async () => new Response('{}'))
   assert.equal(out.kind, 'help')

package/sdk-dist/api/user/copilot.ts

@@ -1,20 +0,0 @@
-import { getDefaultClient } from '../../factory'
-import type {
-  CopilotInitConversationRespVO,
-  CopilotSendMessageReqVO,
-  CopilotSendMessageRespVO
-} from '../../types/copilot'
-
-// @endpoint POST /copilot/init
-// @controller CopilotController.InitConversation
-export async function initCopilotConversation(): Promise<CopilotInitConversationRespVO> {
-  return getDefaultClient().post('/copilot/init')
-}
-
-// @endpoint POST /copilot/send-message
-// @controller CopilotController.SendMessage
-export async function sendCopilotMessage(
-  data: CopilotSendMessageReqVO
-): Promise<CopilotSendMessageRespVO> {
-  return getDefaultClient().post('/copilot/send-message', data)
-}

package/sdk-dist/types/copilot.ts

@@ -1,34 +0,0 @@
-/* eslint-disable */
-/* tslint:disable */
-// @ts-nocheck
-/*
- * ---------------------------------------------------------------
- * ## THIS FILE WAS GENERATED VIA SWAGGER-TYPESCRIPT-API        ##
- * ##                                                           ##
- * ## AUTHOR: acacode                                           ##
- * ## SOURCE: https://github.com/acacode/swagger-typescript-api ##
- * ---------------------------------------------------------------
- */
-
-import type { ErrorResponse } from './common'
-
-export interface CopilotMessage {
-  Content?: string;
-  Type?: string;
-}
-
-export interface CopilotInitConversationRespVO {
-  ID?: string;
-}
-
-export interface CopilotSendMessageReqVO {
-  conversation_id?: string;
-  current_view?: string;
-  messages?: CopilotMessage[];
-  params?: Record<string, string>;
-}
-
-export interface CopilotSendMessageRespVO {
-  ID?: string;
-  Request?: string;
-}