@carthooks/arcubase-cli 0.1.3 → 0.1.5

package/src/runtime/zod_registry.ts

@@ -67,55 +67,60 @@ const examplesIndexDocHint: RuntimeDocHint = {
   file: '/opt/arcubase-sdk/docs/runtime-reference/examples/README.md',
 }
 
-const omsExampleDocHint: RuntimeDocHint = {
-  title: 'OMS example 01',
-  file: '/opt/arcubase-sdk/docs/runtime-reference/examples/oms-01/README.md',
+const appDiscoveryDocHint: RuntimeDocHint = {
+  title: 'App discovery',
+  file: '/opt/arcubase-sdk/docs/runtime-reference/app-discovery.md',
 }
 
 const docHintIndex: Record<string, RuntimeDocHint[]> = {
   AppCreateByTenantsReqVO: [
+    appDiscoveryDocHint,
     { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
     examplesIndexDocHint,
-    omsExampleDocHint,
   ],
   AppCreateEntityReqVO: [
+    appDiscoveryDocHint,
     { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
     examplesIndexDocHint,
-    omsExampleDocHint,
   ],
   EntitySaveReqVO: [
     { title: 'Entity schema', file: '/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
   EntityQueryReqVO: [
     { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
   EntityUpdateReqVO: [
     { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    omsExampleDocHint,
+    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+    examplesIndexDocHint,
   ],
   EntitySelectionActionReqVO: [
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
   InsertReqVO: [
     { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    omsExampleDocHint,
+    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+    examplesIndexDocHint,
   ],
   EntityBulkUpdateReqVO: [
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
   'EntityInvokeBatchOperatorReqVO & InvokeRequestVO': [
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    examplesIndexDocHint,
   ],
   '{ policy_id: string selection: any }': [
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    examplesIndexDocHint,
   ],
   '{ policy_id: string selection: any tag_names: string[] }': [
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    examplesIndexDocHint,
   ],
 }
 
@@ -150,53 +155,68 @@ export function getDocHints(typeName: string): RuntimeDocHint[] {
 
 const commandDocHintIndex: Record<string, RuntimeDocHint[]> = {
   'admin.app.createAppByTenants': [
+    appDiscoveryDocHint,
     { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
     examplesIndexDocHint,
-    omsExampleDocHint,
+  ],
+  'admin.app.listApps': [
+    appDiscoveryDocHint,
+    examplesIndexDocHint,
+  ],
+  'admin.app.inventory': [
+    appDiscoveryDocHint,
+    examplesIndexDocHint,
   ],
   'admin.app.createEntity': [
+    appDiscoveryDocHint,
     { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
   'admin.entity.adminGetEntityInfo': [
+    appDiscoveryDocHint,
     { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
   'admin.entity.adminSaveEntity': [
     { title: 'Entity schema', file: '/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md' },
-    omsExampleDocHint,
+    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    examplesIndexDocHint,
   ],
-  'user.workflow.insertEntity': [
+  'user.rows.insertEntity': [
     { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    omsExampleDocHint,
+    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+    examplesIndexDocHint,
   ],
-  'user.workflow.queryEntity': [
+  'user.rows.queryEntity': [
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
-    omsExampleDocHint,
+    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+    examplesIndexDocHint,
   ],
-  'user.workflow.getEntityRow': [
+  'user.rows.getEntityRow': [
     { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
-  'user.workflow.updateEntityRow': [
+  'user.rows.updateEntityRow': [
     { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    omsExampleDocHint,
+    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+    examplesIndexDocHint,
   ],
-  'user.workflow.queryEntitySelection': [
+  'user.rows.queryEntitySelection': [
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
-  'user.workflow.deleteEntityRow': [
+  'user.rows.deleteEntityRow': [
     { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
-  'user.workflow.restoreEntityRow': [
+  'user.rows.restoreEntityRow': [
     { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
   'user.entity.updateEntityBulk': [
     { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
-    omsExampleDocHint,
+    examplesIndexDocHint,
   ],
 }
 

package/src/tests/command_registry.test.ts

@@ -8,8 +8,17 @@ test('admin app create-entity command exists', () => {
   assert.ok(adminCommands.some((c) => c.commandPath.join(' ') === 'app create-entity'))
 })
 
-test('user workflow query-entity command exists', () => {
-  assert.ok(userCommands.some((c) => c.commandPath.join(' ') === 'workflow query-entity'))
+test('admin app list-apps command exists', () => {
+  assert.ok(adminCommands.some((c) => c.commandPath.join(' ') === 'app list-apps'))
+})
+
+test('admin app inventory command exists', () => {
+  const suggestions = findCommandSuggestions('app', 'inventory', 20)
+  assert.ok(suggestions.some((item) => item.binary === 'arcubase-admin' && item.moduleName === 'app' && item.commandName === 'inventory'))
+})
+
+test('user rows query-entity command exists', () => {
+  assert.ok(userCommands.some((c) => c.commandPath.join(' ') === 'rows query-entity'))
 })
 
 test('inline request type keeps full object text instead of truncated brace', () => {
@@ -27,7 +36,7 @@ test('tag commands no longer emit truncated inline request type', () => {
   assert.equal(typed.scalarParams.length, 0)
 })
 
-test('suggestions can point wrong admin delete guess to user workflow delete command', () => {
+test('suggestions can point wrong admin delete guess to user rows delete command', () => {
   const suggestions = findCommandSuggestions('entity', 'admin-delete-entity-row')
-  assert.ok(suggestions.some((item) => item.binary === 'arcubase' && item.moduleName === 'workflow' && item.commandName === 'delete-entity-row'))
+  assert.ok(suggestions.some((item) => item.binary === 'arcubase' && item.moduleName === 'rows' && item.commandName === 'delete-entity-row'))
 })

package/src/tests/execute_validation.test.ts

@@ -82,6 +82,67 @@ test('admin api-prefixed command executes against external root path', async ()
   assert.equal(out.data.url, 'https://arcubase.example.com/apps/app_1/entity-shares')
 })
 
+test('app inventory returns apps with entity lists', async () => {
+  const calls: string[] = []
+  const out = await executeCLI(
+    'admin',
+    ['app', 'inventory'],
+    env as any,
+    async (url, init) => {
+      calls.push(`${init?.method ?? 'GET'} ${String(url)}`)
+      if (String(url) === 'https://arcubase.example.com/apps') {
+        return new Response(JSON.stringify({
+          data: [
+            { id: 101, name: 'Workspace' },
+            { id: 102, name: 'CRM' },
+          ],
+        }), { status: 200 })
+      }
+      if (String(url) === 'https://arcubase.example.com/apps/101/entities') {
+        return new Response(JSON.stringify({
+          data: [
+            { id: 201, name: 'Orders' },
+            { id: 202, name: 'Customers' },
+          ],
+        }), { status: 200 })
+      }
+      if (String(url) === 'https://arcubase.example.com/apps/102/entities') {
+        return new Response(JSON.stringify({
+          data: [
+            { id: 203, name: 'Leads' },
+          ],
+        }), { status: 200 })
+      }
+      return new Response('{}', { status: 404 })
+    },
+  )
+  assert.equal(out.kind, 'result')
+  assert.deepEqual(out.data, {
+    apps: [
+      {
+        id: '101',
+        name: 'Workspace',
+        entities: [
+          { id: '201', name: 'Orders' },
+          { id: '202', name: 'Customers' },
+        ],
+      },
+      {
+        id: '102',
+        name: 'CRM',
+        entities: [
+          { id: '203', name: 'Leads' },
+        ],
+      },
+    ],
+  })
+  assert.deepEqual(calls, [
+    'GET https://arcubase.example.com/apps',
+    'POST https://arcubase.example.com/apps/101/entities',
+    'POST https://arcubase.example.com/apps/102/entities',
+  ])
+})
+
 test('admin save entity treats top-level error body as failure even on http 200', async () => {
   const bodyFile = tempJSONFile({
     id: 2188889845,
@@ -224,7 +285,7 @@ test('delete entity row rejects selection type outside ids', async () => {
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'delete-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile],
+      ['rows', 'delete-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
@@ -283,7 +344,7 @@ test('selection action accepts condition selection with selectAll', async () =>
 
   const out = await executeCLI(
     'user',
-    ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
+    ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
     env as any,
     async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }),
   )
@@ -306,7 +367,7 @@ test('selection action accepts condition selection with filter_* keys', async ()
 
   const out = await executeCLI(
     'user',
-    ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
+    ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
     env as any,
     async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }),
   )
@@ -328,7 +389,7 @@ test('selection action accepts condition selection with selectAll only for batch
 
   const out = await executeCLI(
     'user',
-    ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'batch_print', '--body-file', bodyFile],
+    ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'batch_print', '--body-file', bodyFile],
     env as any,
     async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }),
   )
@@ -346,7 +407,7 @@ test('selection action accepts all selection for query-style actions', async ()
 
   const out = await executeCLI(
     'user',
-    ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile],
+    ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile],
     env as any,
     async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }),
   )
@@ -369,7 +430,7 @@ test('selection action rejects condition selection for query action', async () =
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile],
+      ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
@@ -391,7 +452,7 @@ test('selection action rejects all selection for archive action', async () => {
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
+      ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
@@ -417,7 +478,7 @@ test('selection action rejects selectAll-only condition for archive action', asy
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
+      ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
@@ -429,6 +490,189 @@ test('selection action rejects selectAll-only condition for archive action', asy
   })
 })
 
+test('insert entity rejects local file path for file field and points to arcubase upload', async () => {
+  const bodyFile = tempJSONFile({
+    fields: {
+      1001: 'Lead A',
+      1007: './contract.pdf',
+    },
+  })
+  const calls: Array<{ url: string; method?: string }> = []
+
+  await assert.rejects(async () => {
+    await executeCLI(
+      'user',
+      ['rows', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile],
+      env as any,
+      async (url, init) => {
+        calls.push({ url: String(url), method: init?.method })
+        if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+          return new Response(JSON.stringify({
+            data: {
+              id: 1,
+              app_id: 1,
+              fields: [
+                { id: 1001, type: 'text', label: 'Lead Name' },
+                { id: 1007, type: 'file', label: 'Contract File' },
+              ],
+            },
+          }), { status: 200 })
+        }
+        return new Response('{}', { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.fields.1007'))
+    assert.match(error.message, /arcubase upload \.\/contract\.pdf/)
+    assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/uploads.md')))
+    return true
+  })
+
+  assert.deepEqual(calls, [
+    { url: 'https://arcubase.example.com/entity/app_1/entity_1', method: 'GET' },
+  ])
+})
+
+test('update row rejects object value for image field and requires upload array', async () => {
+  const bodyFile = tempJSONFile({
+    changed_fields: [1008],
+    data: {
+      1008: {
+        upload_id: 123456,
+        file: 'lead-photo.jpg',
+        file_name: 'lead-photo.jpg',
+        meta: {},
+      },
+    },
+  })
+
+  await assert.rejects(async () => {
+    await executeCLI(
+      'user',
+      ['rows', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile],
+      env as any,
+      async (url, init) => {
+        if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+          return new Response(JSON.stringify({
+            data: {
+              id: 1,
+              app_id: 1,
+              fields: [
+                { id: 1008, type: 'image', label: 'Lead Photo' },
+              ],
+            },
+          }), { status: 200 })
+        }
+        return new Response('{}', { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body.data.1008'))
+    assert.match(error.message, /must be an array/)
+    assert.match(error.message, /arcubase upload <local-file>/)
+    return true
+  })
+})
+
+test('insert entity accepts upload array for file field after schema preflight', async () => {
+  const bodyFile = tempJSONFile({
+    fields: {
+      1001: 'Lead A',
+      1007: [
+        {
+          upload_id: 123456,
+          file: 'contract.pdf',
+          file_name: 'contract.pdf',
+          meta: {},
+        },
+      ],
+    },
+  })
+  const calls: Array<{ url: string; method?: string }> = []
+
+  const out = await executeCLI(
+    'user',
+    ['rows', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile],
+    env as any,
+    async (url, init) => {
+      calls.push({ url: String(url), method: init?.method })
+      if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+        return new Response(JSON.stringify({
+          data: {
+            id: 1,
+            app_id: 1,
+            fields: [
+              { id: 1001, type: 'text', label: 'Lead Name' },
+              { id: 1007, type: 'file', label: 'Contract File' },
+            ],
+          },
+        }), { status: 200 })
+      }
+      return new Response(String(init?.body ?? '{}'), { status: 200 })
+    },
+  )
+
+  assert.equal(out.kind, 'result')
+  assert.deepEqual(calls, [
+    { url: 'https://arcubase.example.com/entity/app_1/entity_1', method: 'GET' },
+    { url: 'https://arcubase.example.com/entity/app_1/entity_1/insert', method: 'POST' },
+  ])
+  assert.equal(out.data.fields['1007'][0].upload_id, 123456)
+})
+
+test('insert entity decorates upload bind failures with actionable guidance', async () => {
+  const bodyFile = tempJSONFile({
+    fields: {
+      1001: 'Lead A',
+      1007: [
+        {
+          upload_id: 123456,
+          file: 'contract.pdf',
+          file_name: 'contract.pdf',
+          meta: {},
+        },
+      ],
+    },
+  })
+
+  await assert.rejects(async () => {
+    await executeCLI(
+      'user',
+      ['rows', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile],
+      env as any,
+      async (url, init) => {
+        if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
+          return new Response(JSON.stringify({
+            data: {
+              fields: [{ id: 1007, type: 'file', label: 'Contract File' }],
+            },
+          }), { status: 200 })
+        }
+        return new Response(JSON.stringify({
+          error: {
+            message: 'failed to bind upload to assets: Head \"http://test-bucket.test.aliyuncs.com/upload/123456/contract.pdf\": dial tcp: lookup test-bucket.test.aliyuncs.com: no such host',
+            type: 'system',
+            key: 'error.system',
+          },
+          trace_id: 'req_upload_bind',
+        }), { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'UPSTREAM_BODY_ERROR')
+    assert.equal(error.details?.traceId, 'req_upload_bind')
+    assert.equal(error.details?.reason, 'the row payload used a file/image upload entry, but Arcubase could not bind that upload into an asset record')
+    assert.match(error.details?.hint ?? '', /rerun arcubase upload/)
+    assert.ok((error.details?.docHints ?? []).some((item) => item.file.endsWith('/docs/runtime-reference/uploads.md')))
+    return true
+  })
+})
+
 test('selection action rejects condition selection without selectAll', async () => {
   const bodyFile = tempJSONFile({
     selection: {
@@ -443,7 +687,7 @@ test('selection action rejects condition selection without selectAll', async ()
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
+      ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
@@ -470,7 +714,7 @@ test('selection action rejects condition selection that uses text_search instead
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
+      ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
@@ -597,7 +841,7 @@ test('query entity rejects camelCase viewMode and points to row crud doc', async
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'query-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile],
+      ['rows', 'query-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
@@ -624,7 +868,7 @@ test('update entity row rejects fields key', async () => {
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile],
+      ['rows', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )
@@ -648,7 +892,7 @@ test('update entity row rejects changed_fields that are missing from data', asyn
   await assert.rejects(async () => {
     await executeCLI(
       'user',
-      ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile],
+      ['rows', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile],
       env as any,
       async () => new Response('{}', { status: 200 }),
     )

package/src/tests/help.test.ts

@@ -28,10 +28,11 @@ test('module help prints create-entity command', async () => {
   const out = await executeCLI('admin', ['app', '--help'], env as any, async () => new Response('{}'))
   assert.equal(out.kind, 'help')
   assert.match(out.text, /create-entity/)
+  assert.match(out.text, /inventory/)
 })
 
 test('module help does not require runtime env', async () => {
-  const out = await executeCLI('user', ['workflow', '--help'], undefined, async () => new Response('{}'))
+  const out = await executeCLI('user', ['rows', '--help'], undefined, async () => new Response('{}'))
   assert.equal(out.kind, 'help')
   assert.match(out.text, /delete-entity-row/)
 })
@@ -44,21 +45,21 @@ test('command help prints normalized external endpoint', async () => {
 })
 
 test('command help does not require runtime env', async () => {
-  const out = await executeCLI('user', ['workflow', 'delete-entity-row', '--help'], undefined, async () => new Response('{}'))
+  const out = await executeCLI('user', ['rows', 'delete-entity-row', '--help'], undefined, async () => new Response('{}'))
   assert.equal(out.kind, 'help')
   assert.match(out.text, /endpoint: \/entity\/:app_id\/:entity_id\/delete-item/)
 })
 
 test('command help prints runtime doc hints for request body commands', async () => {
-  const out = await executeCLI('user', ['workflow', 'update-entity-row', '--help'], undefined, async () => new Response('{}'))
+  const out = await executeCLI('user', ['rows', 'update-entity-row', '--help'], undefined, async () => new Response('{}'))
   assert.equal(out.kind, 'help')
   assert.match(out.text, /docs:/)
   assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/row-crud\.md/)
-  assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/oms-01\/README\.md/)
+  assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/README\.md/)
 })
 
 test('command help prints query-file support', async () => {
-  const out = await executeCLI('user', ['workflow', 'query-entity', '--help'], undefined, async () => new Response('{}'))
+  const out = await executeCLI('user', ['rows', 'query-entity', '--help'], undefined, async () => new Response('{}'))
   assert.equal(out.kind, 'help')
   assert.match(out.text, /query flags: --query-file/)
 })
@@ -67,5 +68,33 @@ test('command help without request body can still point to lifecycle and example
   const out = await executeCLI('admin', ['entity', 'admin-get-entity-info', '--help'], undefined, async () => new Response('{}'))
   assert.equal(out.kind, 'help')
   assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/table-lifecycle\.md/)
-  assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/oms-01\/README\.md/)
+  assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/README\.md/)
+})
+
+test('app inventory help explains app discovery purpose', async () => {
+  const out = await executeCLI('admin', ['app', 'inventory', '--help'], undefined, async () => new Response('{}'))
+  assert.equal(out.kind, 'help')
+  assert.match(out.text, /list all accessible apps and each app entity list/)
+  assert.match(out.text, /use this before asking the user for app_id/)
+})
+
+test('admin-save-entity help prints row-operation next step', async () => {
+  const out = await executeCLI('admin', ['entity', 'admin-save-entity', '--help'], undefined, async () => new Response('{}'))
+  assert.equal(out.kind, 'help')
+  assert.match(out.text, /switch to arcubase for row operations/)
+  assert.match(out.text, /arcubase rows insert-entity/)
+  assert.match(out.text, /arcubase rows query-entity/)
+})
+
+test('wrong admin workflow command points to arcubase row command', async () => {
+  await assert.rejects(
+    () => executeCLI('admin', ['workflow', 'insert-entity'], env as any, async () => new Response('{}')),
+    (error: any) => {
+      assert.equal(error.code, 'UNKNOWN_COMMAND')
+      assert.equal(error.details?.reason, 'workflow insert-entity is not a valid command group; use arcubase rows for row operations')
+      assert.equal(error.details?.hint, 'use: arcubase rows insert-entity')
+      assert.ok((error.details?.suggestions ?? []).includes('arcubase rows insert-entity'))
+      return true
+    }
+  )
 })