@carthooks/arcubase-cli 0.1.10 → 0.1.13

package/src/runtime/paths.ts

@@ -1,8 +1,17 @@
+import { CLIError } from './errors.js'
+
 export const DEFAULT_ARCUBASE_CLI_ROOT = '/opt/arcubase-cli'
-export const DEFAULT_ARCUBASE_SDK_ROOT = '/opt/arcubase-sdk'
 
 export function resolveArcubaseSDKRoot(env: Record<string, string | undefined> = process.env): string {
   const value = env.ARCUBASE_SDK_ROOT?.trim()
   if (value) return value
-  return DEFAULT_ARCUBASE_SDK_ROOT
+  throw new CLIError('RUNTIME_ENV_REQUIRED', 'ARCUBASE_SDK_ROOT is required', 2)
+}
+
+export function resolveArcubaseSDKPath(filePath: string, env: Record<string, string | undefined> = process.env): string {
+  const cleanPath = String(filePath || '').trim().replace(/^\/+/, '')
+  if (!cleanPath) {
+    throw new CLIError('RUNTIME_ENV_REQUIRED', 'ARCUBASE_SDK_ROOT path is required', 2)
+  }
+  return `${resolveArcubaseSDKRoot(env).replace(/\/+$/, '')}/${cleanPath}`
 }

package/src/runtime/upload.ts

@@ -1,196 +1,37 @@
-import fs from 'fs'
-import path from 'path'
 import { CLIError } from './errors.js'
-import type { RuntimeEnv } from './env.js'
-import { buildRequestHeaders, buildURL } from './http.js'
+import { resolveArcubaseSDKPath } from './paths.js'
 
-type UploadTokenResponse = {
-  data?: {
-    id?: number | string
-    mode?: string
-    token_data?: {
-      dir?: string
-      policy?: string
-      host?: string
-      accessid?: string
-      signature?: string
-      x_amz_algorithm?: string
-      x_amz_credential?: string
-      x_amz_date?: string
-      x_amz_signature?: string
-    }
-  }
-  error?: unknown
-  trace_id?: string
-}
-
-export type ArcubaseUploadResult = {
-  upload_id: number | string
-  file: string
-  file_name: string
-  meta: Record<string, never>
-}
-
-function readUploadSource(sourcePath: string): { absolutePath: string; bytes: Buffer } {
-  const absolutePath = path.resolve(sourcePath)
-  if (!fs.existsSync(absolutePath)) {
-    throw new CLIError('UPLOAD_SOURCE_NOT_FOUND', `upload source file does not exist: ${sourcePath}`, 2)
-  }
-  const stat = fs.statSync(absolutePath)
-  if (!stat.isFile()) {
-    throw new CLIError('UPLOAD_SOURCE_INVALID', `upload source path must be a file: ${sourcePath}`, 2)
-  }
-  return {
-    absolutePath,
-    bytes: fs.readFileSync(absolutePath),
-  }
-}
-
-function parseJSONResponse(raw: string): unknown {
-  try {
-    return raw ? JSON.parse(raw) : null
-  } catch {
-    return raw
-  }
-}
-
-function requireTokenPayload(payload: UploadTokenResponse): NonNullable<UploadTokenResponse['data']> {
-  if (payload && typeof payload === 'object' && payload.error) {
-    const upstreamError = payload.error
-    const message =
-      typeof upstreamError === 'object' && upstreamError && 'message' in upstreamError && typeof (upstreamError as any).message === 'string'
-        ? (upstreamError as any).message
-        : typeof upstreamError === 'string'
-          ? upstreamError
-          : JSON.stringify(upstreamError)
-    throw new CLIError('UPSTREAM_BODY_ERROR', message, 1, {
-      endpoint: '/api/upload/token',
-      method: 'POST',
-      traceId: typeof payload.trace_id === 'string' ? payload.trace_id : undefined,
-      upstreamError,
-    })
-  }
-  if (!payload?.data || typeof payload.data !== 'object') {
-    throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response did not include data', 1)
-  }
-  return payload.data
+function sdkPath(file: string): string {
+  return resolveArcubaseSDKPath(file)
 }
 
 export function renderUploadHelp(): string {
   return [
-    'arcubase upload <local-file> [flags]',
+    'arcubase upload <command> [flags]',
     '',
     'purpose:',
-    '  - upload one local file through Arcubase',
-    '  - return a field value that can be used directly in file or image row payloads',
-    '',
-    'flags:',
-    '  --filename <name>   override the uploaded filename stored in Arcubase',
-    '  --global            request a global upload token instead of a tenant-scoped token',
+    '  - call explicit Arcubase upload APIs',
+    '  - keep file transfer outside this CLI surface',
     '',
-    'result shape:',
-    '  - data is a JSON array',
-    '  - use that array directly as the value of a file or image field in insert/update payloads',
+    'commands:',
+    '  - token',
+    '  - preview',
+    '  - mobile',
+    '  - check-mobile',
     '',
     'example:',
-    '  arcubase upload ./contract.pdf',
-    '  arcubase upload ./photo.jpg --filename lead-photo.jpg',
+    '  arcubase upload token --body-json \'{"global":false}\'',
     '',
     'docs:',
-    '  - Uploads: /opt/arcubase-sdk/docs/runtime-reference/uploads.md',
-    '  - Row CRUD: /opt/arcubase-sdk/docs/runtime-reference/row-crud.md',
-    '  - File field: /opt/arcubase-sdk/docs/runtime-reference/entity-schema/file.md',
-    '  - Image field: /opt/arcubase-sdk/docs/runtime-reference/entity-schema/image.md',
+    `  - Uploads: ${sdkPath('docs/runtime-reference/uploads.md')}`,
+    `  - Row CRUD: ${sdkPath('docs/runtime-reference/row-crud.md')}`,
+    `  - File field: ${sdkPath('docs/runtime-reference/entity-schema/file.md')}`,
+    `  - Image field: ${sdkPath('docs/runtime-reference/entity-schema/image.md')}`,
   ].join('\n')
 }
 
-export async function uploadLocalFile(
-  env: RuntimeEnv,
-  sourcePath: string,
-  options: {
-    filename?: string
-    global?: boolean
-  },
-  fetchImpl: typeof fetch = fetch,
-): Promise<ArcubaseUploadResult[]> {
-  const { absolutePath, bytes } = readUploadSource(sourcePath)
-  const filename = (options.filename && options.filename.trim()) || path.basename(absolutePath)
-
-  const tokenResponse = await fetchImpl(buildURL(env.ARCUBASE_BASE_URL, '/api/upload/token'), {
-    method: 'POST',
-    headers: {
-      ...buildRequestHeaders(env),
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      global: Boolean(options.global),
-    }),
-  })
-
-  const tokenRaw = await tokenResponse.text()
-  const tokenParsed = parseJSONResponse(tokenRaw)
-  if (!tokenResponse.ok) {
-    throw new CLIError('UPLOAD_TOKEN_REQUEST_FAILED', typeof tokenParsed === 'string' ? tokenParsed : JSON.stringify(tokenParsed), 1, {
-      endpoint: '/api/upload/token',
-      method: 'POST',
-    })
-  }
-
-  const tokenData = requireTokenPayload(tokenParsed as UploadTokenResponse)
-  if (tokenData.mode !== 'aliyun-oss' && tokenData.mode !== 's3-post-policy') {
-    throw new CLIError('UPLOAD_MODE_UNSUPPORTED', `unsupported upload mode: ${String(tokenData.mode || '')}`, 1)
-  }
-  if (!tokenData.token_data?.dir || !tokenData.token_data.policy || !tokenData.token_data.host) {
-    throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response is missing required token_data fields', 1)
-  }
-  if (tokenData.id === undefined || tokenData.id === null || tokenData.id === '') {
-    throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response is missing id', 1)
-  }
-
-  const form = new FormData()
-  form.append('key', `${tokenData.token_data.dir}${filename}`)
-  form.append('policy', tokenData.token_data.policy)
-  if (tokenData.mode === 'aliyun-oss') {
-    if (!tokenData.token_data.accessid || !tokenData.token_data.signature) {
-      throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response is missing required token_data fields', 1)
-    }
-    form.append('OSSAccessKeyId', tokenData.token_data.accessid)
-    form.append('success_action_status', '200')
-    form.append('signature', tokenData.token_data.signature)
-  } else {
-    if (
-      !tokenData.token_data.x_amz_algorithm ||
-      !tokenData.token_data.x_amz_credential ||
-      !tokenData.token_data.x_amz_date ||
-      !tokenData.token_data.x_amz_signature
-    ) {
-      throw new CLIError('UPLOAD_TOKEN_INVALID', 'upload token response is missing required s3 token_data fields', 1)
-    }
-    form.append('x-amz-algorithm', tokenData.token_data.x_amz_algorithm)
-    form.append('x-amz-credential', tokenData.token_data.x_amz_credential)
-    form.append('x-amz-date', tokenData.token_data.x_amz_date)
-    form.append('x-amz-signature', tokenData.token_data.x_amz_signature)
-  }
-  form.append('file', new Blob([new Uint8Array(bytes)]), filename)
-
-  const uploadResponse = await fetchImpl(tokenData.token_data.host, {
-    method: 'POST',
-    body: form,
+export async function uploadLocalFile(): Promise<never> {
+  throw new CLIError('UNSUPPORTED_COMMAND', 'local file upload is not part of the reset CLI surface; use upload token APIs instead', 2, {
+    docHints: [{ title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md') }],
   })
-  const uploadRaw = await uploadResponse.text()
-  if (!uploadResponse.ok) {
-    throw new CLIError('UPLOAD_TRANSFER_FAILED', uploadRaw || `upload failed with status ${uploadResponse.status}`, 1, {
-      endpoint: tokenData.token_data.host,
-      method: 'POST',
-    })
-  }
-
-  return [
-    {
-      upload_id: tokenData.id,
-      file: filename,
-      file_name: filename,
-      meta: {},
-    },
-  ]
 }

package/src/runtime/zod_registry.ts

@@ -1,6 +1,7 @@
 import type { ZodTypeAny } from 'zod'
 import { bodySchemas, unsupportedBodySchemas } from '../generated/zod_registry.generated.js'
 import { typeIndex } from '../generated/type_index.generated.js'
+import { resolveArcubaseSDKPath } from './paths.js'
 import {
   AppCreateByTenantsReqVOSchemaOverride,
   EntityBulkUpdateReqVOSchemaOverride,
@@ -62,62 +63,112 @@ export type RuntimeDocHint = {
   file: string
 }
 
+type EnvInput = Record<string, string | undefined>
+
+function sdkPath(file: string, env: EnvInput = process.env): string {
+  return resolveArcubaseSDKPath(file.replace(/^\/?opt\/arcubase-sdk\/?/, ''), env)
+}
+
+function resolveTypeHintFiles(hints: RuntimeTypeHint[], env: EnvInput = process.env): RuntimeTypeHint[] {
+  return hints.map((item) => ({ ...item, file: sdkPath(item.file, env) }))
+}
+
+function resolveDocHintFiles(hints: RuntimeDocHint[], env: EnvInput = process.env): RuntimeDocHint[] {
+  return hints.map((item) => ({ ...item, file: sdkPath(item.file, env) }))
+}
+
 const examplesIndexDocHint: RuntimeDocHint = {
   title: 'Examples index',
-  file: '/opt/arcubase-sdk/docs/runtime-reference/examples/README.md',
+  file: 'docs/runtime-reference/examples/README.md',
+}
+const selectionDocHint: RuntimeDocHint = {
+  title: 'Selection',
+  file: 'docs/runtime-reference/selection.md',
+}
+const conditionDocHint: RuntimeDocHint = {
+  title: 'Condition',
+  file: 'docs/runtime-reference/condition.md',
 }
 
 const docHintIndex: Record<string, RuntimeDocHint[]> = {
   AppCreateByTenantsReqVO: [
-    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    { title: 'Table lifecycle', file: 'docs/runtime-reference/table-lifecycle.md' },
     examplesIndexDocHint,
   ],
   AppCreateEntityReqVO: [
-    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    { title: 'Table lifecycle', file: 'docs/runtime-reference/table-lifecycle.md' },
+    { title: 'Table schema cheatsheet', file: 'docs/runtime-reference/entity-schema.md' },
+    { title: 'Field type index', file: 'docs/runtime-reference/entity-schema/README.md' },
+    examplesIndexDocHint,
+  ],
+  AppIngressCreateReqVO: [
+    { title: 'Access rule', file: 'docs/runtime-reference/access-rule.md' },
+    examplesIndexDocHint,
+  ],
+  AppIngressUpdateReqVO: [
+    { title: 'Access rule', file: 'docs/runtime-reference/access-rule.md' },
     examplesIndexDocHint,
   ],
   EntitySaveReqVO: [
-    { title: 'Entity schema', file: '/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md' },
+    { title: 'Table schema cheatsheet', file: 'docs/runtime-reference/entity-schema.md' },
+    { title: 'Field type index', file: 'docs/runtime-reference/entity-schema/README.md' },
+    { title: 'Text field', file: 'docs/runtime-reference/entity-schema/text.md' },
+    { title: 'Textarea field', file: 'docs/runtime-reference/entity-schema/textarea.md' },
+    { title: 'Number field', file: 'docs/runtime-reference/entity-schema/number.md' },
+    { title: 'Datetime field', file: 'docs/runtime-reference/entity-schema/datetime.md' },
+    { title: 'Boolean field', file: 'docs/runtime-reference/entity-schema/boolean.md' },
+    { title: 'Select field', file: 'docs/runtime-reference/entity-schema/select.md' },
     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' },
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
+    { title: 'Search and bulk actions', file: 'docs/runtime-reference/search-and-bulk-actions.md' },
+    conditionDocHint,
     examplesIndexDocHint,
   ],
   EntityUpdateReqVO: [
-    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
+    { title: 'Uploads', file: 'docs/runtime-reference/uploads.md' },
     examplesIndexDocHint,
   ],
   EntitySelectionActionReqVO: [
-    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    selectionDocHint,
+    conditionDocHint,
+    { title: 'Search and bulk actions', file: 'docs/runtime-reference/search-and-bulk-actions.md' },
     examplesIndexDocHint,
   ],
   InsertReqVO: [
-    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
+    { title: 'Uploads', file: 'docs/runtime-reference/uploads.md' },
     examplesIndexDocHint,
   ],
   EntityBulkUpdateReqVO: [
-    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    selectionDocHint,
+    conditionDocHint,
+    { title: 'Search and bulk actions', file: 'docs/runtime-reference/search-and-bulk-actions.md' },
     examplesIndexDocHint,
   ],
   'EntityInvokeBatchOperatorReqVO & InvokeRequestVO': [
-    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    selectionDocHint,
+    conditionDocHint,
+    { title: 'Search and bulk actions', file: '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' },
+    selectionDocHint,
+    conditionDocHint,
+    { title: 'Search and bulk actions', file: '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' },
+    selectionDocHint,
+    conditionDocHint,
+    { title: 'Search and bulk actions', file: 'docs/runtime-reference/search-and-bulk-actions.md' },
     examplesIndexDocHint,
   ],
 }
 
-export function getTypeHints(typeName: string): RuntimeTypeHint[] {
+export function getTypeHints(typeName: string, env: EnvInput = process.env): RuntimeTypeHint[] {
   const name = String(typeName || '').trim()
   if (!name) return []
   const entry = (typeIndex as Record<string, { file: string; dependencies?: ReadonlyArray<RuntimeTypeHint> } | undefined>)[name]
@@ -137,73 +188,87 @@ export function getTypeHints(typeName: string): RuntimeTypeHint[] {
   for (const dep of entry.dependencies ?? []) {
     append(dep.symbol, dep.file)
   }
-  return out
+  return resolveTypeHintFiles(out, env)
 }
 
-export function getDocHints(typeName: string): RuntimeDocHint[] {
+export function getDocHints(typeName: string, env: EnvInput = process.env): RuntimeDocHint[] {
   const name = String(typeName || '').trim()
   if (!name) return []
-  return docHintIndex[name] ?? []
+  return resolveDocHintFiles(docHintIndex[name] ?? [], env)
 }
 
 const commandDocHintIndex: Record<string, RuntimeDocHint[]> = {
   'admin.app.createAppByTenants': [
-    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    { title: 'Table lifecycle', file: 'docs/runtime-reference/table-lifecycle.md' },
     examplesIndexDocHint,
   ],
   'admin.app.createEntity': [
-    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+    { title: 'Table lifecycle', file: 'docs/runtime-reference/table-lifecycle.md' },
+    examplesIndexDocHint,
+  ],
+  'admin.table.adminGetEntityInfo': [
+    { title: 'Table lifecycle', file: 'docs/runtime-reference/table-lifecycle.md' },
+    examplesIndexDocHint,
+  ],
+  'admin.table.adminSaveEntity': [
+    { title: 'Table schema cheatsheet', file: 'docs/runtime-reference/entity-schema.md' },
+    { title: 'Field type index', file: 'docs/runtime-reference/entity-schema/README.md' },
+    { title: 'Table lifecycle', file: 'docs/runtime-reference/table-lifecycle.md' },
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
     examplesIndexDocHint,
   ],
-  'admin.entity.adminGetEntityInfo': [
-    { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+  'admin.access-rule.createEntityIngress': [
+    { title: 'Access rule', file: 'docs/runtime-reference/access-rule.md' },
     examplesIndexDocHint,
   ],
-  'admin.entity.adminSaveEntity': [
-    { title: 'Entity schema', file: '/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md' },
-    { 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' },
+  'admin.access-rule.updateEntityIngress': [
+    { title: 'Access rule', file: 'docs/runtime-reference/access-rule.md' },
     examplesIndexDocHint,
   ],
-  'user.workflow.insertEntity': [
-    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+  'user.row.insertEntity': [
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
+    { title: 'Uploads', file: 'docs/runtime-reference/uploads.md' },
     examplesIndexDocHint,
   ],
-  'user.workflow.queryEntity': [
-    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
-    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+  'user.row.queryEntity': [
+    { title: 'Search and bulk actions', file: 'docs/runtime-reference/search-and-bulk-actions.md' },
+    conditionDocHint,
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
     examplesIndexDocHint,
   ],
-  'user.workflow.getEntityRow': [
-    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+  'user.row.getEntityRow': [
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
     examplesIndexDocHint,
   ],
-  'user.workflow.updateEntityRow': [
-    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
-    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+  'user.row.updateEntityRow': [
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
+    { title: 'Uploads', file: 'docs/runtime-reference/uploads.md' },
     examplesIndexDocHint,
   ],
-  'user.workflow.queryEntitySelection': [
-    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+  'user.row.queryEntitySelection': [
+    selectionDocHint,
+    conditionDocHint,
+    { title: 'Search and bulk actions', file: 'docs/runtime-reference/search-and-bulk-actions.md' },
     examplesIndexDocHint,
   ],
-  'user.workflow.deleteEntityRow': [
-    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+  'user.row.deleteEntityRow': [
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
     examplesIndexDocHint,
   ],
-  'user.workflow.restoreEntityRow': [
-    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+  'user.row.restoreEntityRow': [
+    { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
     examplesIndexDocHint,
   ],
-  'user.entity.updateEntityBulk': [
-    { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+  'user.row.updateEntityBulk': [
+    selectionDocHint,
+    conditionDocHint,
+    { title: 'Search and bulk actions', file: 'docs/runtime-reference/search-and-bulk-actions.md' },
     examplesIndexDocHint,
   ],
 }
 
-export function getCommandDocHints(operation: string): RuntimeDocHint[] {
+export function getCommandDocHints(operation: string, env: EnvInput = process.env): RuntimeDocHint[] {
   const key = String(operation || '').trim()
   if (!key) return []
-  return commandDocHintIndex[key] ?? []
+  return resolveDocHintFiles(commandDocHintIndex[key] ?? [], env)
 }

package/src/tests/bootstrap.test.ts

@@ -7,16 +7,28 @@ test('loadRuntimeEnv requires base url and access token', () => {
   assert.throws(() => loadRuntimeEnv('admin', {}), /ARCUBASE_BASE_URL is required/)
 })
 
+test('loadRuntimeEnv requires injected SDK root without fallback', () => {
+  assert.throws(
+    () => loadRuntimeEnv('admin', {
+      ARCUBASE_BASE_URL: 'http://example.com',
+      ARCUBASE_ACCESS_TOKEN: 'token-1',
+    }),
+    /ARCUBASE_SDK_ROOT is required/,
+  )
+})
+
 test('loadRuntimeEnv returns normalized runtime env', () => {
   const env = loadRuntimeEnv('admin', {
     ARCUBASE_BASE_URL: ' http://example.com ',
     ARCUBASE_ACCESS_TOKEN: ' token-1 ',
+    ARCUBASE_SDK_ROOT: ' /runtime/arcubase-sdk ',
     ARCUBASE_TRACE_ID: ' trace-1 '
   })
 
   assert.deepEqual(env, {
     ARCUBASE_BASE_URL: 'http://example.com',
     ARCUBASE_ACCESS_TOKEN: 'token-1',
+    ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
     ARCUBASE_TRACE_ID: 'trace-1',
     ARCUBASE_SUBJECT_TYPE: undefined,
     ARCUBASE_SUBJECT_ID: undefined,
@@ -28,6 +40,7 @@ test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
   const env = loadRuntimeEnv('admin', {
     ARCUBASE_ADMIN_BASE_URL: ' https://admin.example.com ',
     ARCUBASE_ADMIN_ACCESS_TOKEN: ' token-admin ',
+    ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
     ARCUBASE_ADMIN_SUBJECT_TYPE: ' system_admin ',
     ARCUBASE_ADMIN_SUBJECT_ID: ' user-admin ',
   })
@@ -35,6 +48,7 @@ test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
   assert.deepEqual(env, {
     ARCUBASE_BASE_URL: 'https://admin.example.com',
     ARCUBASE_ACCESS_TOKEN: 'token-admin',
+    ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
     ARCUBASE_TRACE_ID: undefined,
     ARCUBASE_SUBJECT_TYPE: 'system_admin',
     ARCUBASE_SUBJECT_ID: 'user-admin',
@@ -46,6 +60,7 @@ test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
   const env = loadRuntimeEnv('user', {
     ARCUBASE_USER_BASE_URL: ' https://user.example.com ',
     ARCUBASE_USER_ACCESS_TOKEN: ' token-user ',
+    ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
     ARCUBASE_USER_SUBJECT_TYPE: ' service_account ',
     ARCUBASE_USER_SUBJECT_ID: ' sa-user ',
   })
@@ -53,6 +68,7 @@ test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
   assert.deepEqual(env, {
     ARCUBASE_BASE_URL: 'https://user.example.com',
     ARCUBASE_ACCESS_TOKEN: 'token-user',
+    ARCUBASE_SDK_ROOT: '/runtime/arcubase-sdk',
     ARCUBASE_TRACE_ID: undefined,
     ARCUBASE_SUBJECT_TYPE: 'service_account',
     ARCUBASE_SUBJECT_ID: 'sa-user',

package/src/tests/command_registry.test.ts

@@ -68,6 +68,13 @@ test('user surface is restricted to reset white list', () => {
   assert.deepEqual(actual, expected)
 })
 
+test('generated modules use CLI namespaces only', () => {
+  const adminModules = [...new Set(adminCommands.map((item) => item.module))].sort()
+  const userModules = [...new Set(userCommands.map((item) => item.module))].sort()
+  assert.deepEqual(adminModules, ['access-rule', 'app', 'table', 'workflow'])
+  assert.deepEqual(userModules, ['entry', 'profile', 'row', 'table', 'upload', 'workflow'])
+})
+
 test('black list commands are removed from registry', () => {
   const all = new Set([...commandPaths(adminCommands), ...commandPaths(userCommands)])
   const forbidden = [
@@ -79,6 +86,8 @@ test('black list commands are removed from registry', () => {
     'ingress create-entity-ingress',
     'workflow query-entity',
     'workflow insert-entity',
+    'workflow prepare-entity-insert',
+    'workflow get-entity-row',
     'workflow update-entity-row',
     'workflow delete-entity-row',
     'workflow restore-entity-row',