@carthooks/arcubase-cli 0.1.0

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './runtime/env.js'
+export * from './runtime/http.js'
+export * from './runtime/errors.js'
+export * from './runtime/output.js'

package/src/runtime/argv.ts

@@ -0,0 +1,39 @@
+import { CLIError } from './errors.js'
+
+export type ParsedCLIInput = {
+  commandTokens: string[]
+  flags: Record<string, string | boolean>
+}
+
+export function parseCLIArgs(argv: string[]): ParsedCLIInput {
+  const commandTokens: string[] = []
+  const flags: Record<string, string | boolean> = {}
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    if (!token.startsWith('--')) {
+      commandTokens.push(token)
+      continue
+    }
+    const name = token.slice(2)
+    if (!name) {
+      throw new CLIError('INVALID_FLAG', 'flag name is required', 2)
+    }
+    const next = argv[i + 1]
+    if (next && !next.startsWith('--')) {
+      flags[name] = next
+      i += 1
+      continue
+    }
+    flags[name] = true
+  }
+  return { commandTokens, flags }
+}
+
+export function flagValue(flags: Record<string, string | boolean>, name: string): string | undefined {
+  const value = flags[name]
+  return typeof value === 'string' ? value : undefined
+}
+
+export function hasFlag(flags: Record<string, string | boolean>, name: string): boolean {
+  return Boolean(flags[name])
+}

package/src/runtime/body_loader.ts

@@ -0,0 +1,26 @@
+import fs from 'fs'
+import { CLIError } from './errors.js'
+
+function parseJSONFile(filePath: string, label: string): unknown {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+  } catch (error) {
+    throw new CLIError('INVALID_JSON_FILE', `${label} file is invalid: ${filePath}`, 2)
+  }
+}
+
+export function loadBodyFromFlags(flags: Record<string, string | boolean>): unknown | undefined {
+  const bodyFile = typeof flags['body-file'] === 'string' ? flags['body-file'] : undefined
+  if (!bodyFile) return undefined
+  return parseJSONFile(bodyFile, 'body')
+}
+
+export function loadQueryFromFlags(flags: Record<string, string | boolean>): Record<string, any> | undefined {
+  const queryFile = typeof flags['query-file'] === 'string' ? flags['query-file'] : undefined
+  if (!queryFile) return undefined
+  const parsed = parseJSONFile(queryFile, 'query')
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new CLIError('INVALID_QUERY_FILE', 'query file must contain a JSON object', 2)
+  }
+  return parsed as Record<string, any>
+}

package/src/runtime/command_registry.ts

@@ -0,0 +1,22 @@
+import { adminCommands, userCommands } from '../generated/command_registry.generated.js'
+
+export { adminCommands, userCommands }
+
+export type CommandScope = 'admin' | 'user'
+export type CommandDef = (typeof adminCommands)[number] | (typeof userCommands)[number]
+
+export function listCommands(scope: CommandScope): readonly CommandDef[] {
+  return scope === 'admin' ? adminCommands : userCommands
+}
+
+export function findCommand(scope: CommandScope, moduleName: string, commandName: string): CommandDef | null {
+  return listCommands(scope).find((item) => item.commandPath[0] === moduleName && item.commandPath[1] === commandName) ?? null
+}
+
+export function listModules(scope: CommandScope): string[] {
+  return [...new Set(listCommands(scope).map((item) => item.commandPath[0]))].sort()
+}
+
+export function listModuleCommands(scope: CommandScope, moduleName: string): readonly CommandDef[] {
+  return listCommands(scope).filter((item) => item.commandPath[0] === moduleName)
+}

package/src/runtime/env.ts

@@ -0,0 +1,60 @@
+export type RuntimeEnv = {
+  ARCUBASE_BASE_URL: string
+  ARCUBASE_TENANT_ID: string
+  ARCUBASE_ACCESS_TOKEN: string
+  ARCUBASE_TRACE_ID?: string
+  ARCUBASE_SUBJECT_TYPE?: string
+  ARCUBASE_SUBJECT_ID?: string
+  ARCUBASE_TOKEN_EXPIRES_AT?: string
+}
+
+export type RuntimeEnvScope = 'admin' | 'user'
+
+type EnvInput = Record<string, string | undefined>
+
+const PREFIX_BY_SCOPE: Record<RuntimeEnvScope, string> = {
+  admin: 'ARCUBASE_ADMIN_',
+  user: 'ARCUBASE_USER_',
+}
+
+function envValue(env: EnvInput, scope: RuntimeEnvScope, key: keyof RuntimeEnv): string | undefined {
+  const direct = env[key]
+  if (direct && direct.trim() !== '') {
+    return direct.trim()
+  }
+  const suffix = String(key).replace(/^ARCUBASE_/, '')
+  const scopedKey = `${PREFIX_BY_SCOPE[scope]}${suffix}`
+  const scopedValue = env[scopedKey]
+  if (!scopedValue || scopedValue.trim() === '') {
+    return undefined
+  }
+  return scopedValue.trim()
+}
+
+function requiredValue(env: EnvInput, scope: RuntimeEnvScope, key: keyof RuntimeEnv): string {
+  const value = envValue(env, scope, key)
+  if (!value || value.trim() === '') {
+    throw new Error(`${key} is required`)
+  }
+  return value
+}
+
+function optionalValue(env: EnvInput, scope: RuntimeEnvScope, key: keyof RuntimeEnv): string | undefined {
+  const value = envValue(env, scope, key)
+  if (!value || value.trim() === '') {
+    return undefined
+  }
+  return value
+}
+
+export function loadRuntimeEnv(scope: RuntimeEnvScope, env: EnvInput = process.env): RuntimeEnv {
+  return {
+    ARCUBASE_BASE_URL: requiredValue(env, scope, 'ARCUBASE_BASE_URL'),
+    ARCUBASE_TENANT_ID: requiredValue(env, scope, 'ARCUBASE_TENANT_ID'),
+    ARCUBASE_ACCESS_TOKEN: requiredValue(env, scope, 'ARCUBASE_ACCESS_TOKEN'),
+    ARCUBASE_TRACE_ID: optionalValue(env, scope, 'ARCUBASE_TRACE_ID'),
+    ARCUBASE_SUBJECT_TYPE: optionalValue(env, scope, 'ARCUBASE_SUBJECT_TYPE'),
+    ARCUBASE_SUBJECT_ID: optionalValue(env, scope, 'ARCUBASE_SUBJECT_ID'),
+    ARCUBASE_TOKEN_EXPIRES_AT: optionalValue(env, scope, 'ARCUBASE_TOKEN_EXPIRES_AT')
+  }
+}

package/src/runtime/errors.ts

@@ -0,0 +1,41 @@
+export type CLIValidationIssue = {
+  path: string
+  message: string
+}
+
+export type CLITSTypeHint = {
+  symbol: string
+  file: string
+}
+
+export type CLIErrorDetails = {
+  operation?: string
+  requestType?: string
+  issues?: CLIValidationIssue[]
+  tsHints?: CLITSTypeHint[]
+  reason?: string
+}
+
+export class CLIError extends Error {
+  readonly code: string
+  readonly exitCode: number
+  readonly details?: CLIErrorDetails
+
+  constructor(code: string, message: string, exitCode = 1, details?: CLIErrorDetails) {
+    super(message)
+    this.name = 'CLIError'
+    this.code = code
+    this.exitCode = exitCode
+    this.details = details
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.details ? this.details : {}),
+      },
+    }
+  }
+}

package/src/runtime/execute.ts

@@ -0,0 +1,206 @@
+import { parseCLIArgs, hasFlag, flagValue } from './argv.js'
+import { loadRuntimeEnv, type RuntimeEnv } from './env.js'
+import { CLIError } from './errors.js'
+import { buildRequestHeaders, buildURL } from './http.js'
+import { listModules, listModuleCommands, findCommand, type CommandScope } from './command_registry.js'
+import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js'
+import { getBodySchema, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
+
+export type CommandExecutionSummary = {
+  scope: CommandScope
+  commandPath: readonly [string, string]
+  method: string
+  endpoint: string
+  requestType: string | null
+  pathFlags: readonly string[]
+  scalarFlags: readonly string[]
+}
+
+export function renderRootHelp(scope: CommandScope): string {
+  const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase'
+  return [
+    `${binary} <module> <command> [flags]`,
+    '',
+    'modules:',
+    ...listModules(scope).map((item) => `  - ${item}`),
+  ].join('\n')
+}
+
+export function renderModuleHelp(scope: CommandScope, moduleName: string): string {
+  const items = listModuleCommands(scope, moduleName)
+  if (items.length === 0) {
+    throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2)
+  }
+  return [
+    `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} <command> [flags]`,
+    '',
+    'commands:',
+    ...items.map((item) => `  - ${item.commandPath[1]}`),
+  ].join('\n')
+}
+
+export function renderCommandHelp(scope: CommandScope, moduleName: string, commandName: string): string {
+  const command = findCommand(scope, moduleName, commandName)
+  if (!command) {
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
+  }
+  return [
+    `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} ${commandName}`,
+    `method: ${command.method}`,
+    `endpoint: ${command.endpoint}`,
+    command.requestType ? `body: ${command.requestType} via --body-file` : 'body: none',
+    command.endpointParams.length ? `path flags: ${command.endpointParams.map((item) => `--${item.replace(/_/g, '-')}`).join(', ')}` : 'path flags: none',
+    command.scalarParams.length ? `scalar flags: ${command.scalarParams.map((item) => `--${item.name.replace(/([A-Z])/g, '-$1').toLowerCase()}`).join(', ')}` : 'scalar flags: none',
+  ].join('\n')
+}
+
+function coerceScalar(value: string, typeText: string): any {
+  const normalized = typeText.trim()
+  if (normalized === 'number' || normalized === 'string | number') {
+    const parsed = Number(value)
+    if (Number.isNaN(parsed)) {
+      throw new CLIError('INVALID_FLAG_VALUE', `expected number, got ${value}`, 2)
+    }
+    return parsed
+  }
+  if (normalized === 'boolean') {
+    if (value === 'true') return true
+    if (value === 'false') return false
+    throw new CLIError('INVALID_FLAG_VALUE', `expected boolean, got ${value}`, 2)
+  }
+  return value
+}
+
+function resolveEndpoint(endpoint: string, flags: Record<string, string | boolean>): string {
+  let resolved = endpoint
+  for (const placeholder of [...endpoint.matchAll(/:([A-Za-z0-9_]+)/g)].map((match) => match[1])) {
+    const flagName = placeholder.replace(/_/g, '-')
+    const value = flagValue(flags, flagName)
+    if (!value) {
+      throw new CLIError('MISSING_PATH_FLAG', `missing required flag --${flagName}`, 2)
+    }
+    resolved = resolved.replace(`:${placeholder}`, encodeURIComponent(value))
+  }
+  return resolved
+}
+
+function buildScalarQuery(command: ReturnType<typeof findCommand>, flags: Record<string, string | boolean>): Record<string, any> | undefined {
+  if (!command) {
+    return undefined
+  }
+  const out: Record<string, any> = {}
+  for (const scalar of command.scalarParams) {
+    const flagName = scalar.name.replace(/([A-Z])/g, '-$1').toLowerCase()
+    const value = flagValue(flags, flagName)
+    if (value === undefined) continue
+    out[scalar.name] = coerceScalar(value, scalar.type)
+  }
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+export function summarizeCommand(scope: CommandScope, moduleName: string, commandName: string): CommandExecutionSummary {
+  const command = findCommand(scope, moduleName, commandName)
+  if (!command) {
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
+  }
+  return {
+    scope,
+    commandPath: command.commandPath,
+    method: command.method,
+    endpoint: command.endpoint,
+    requestType: command.requestType,
+    pathFlags: command.endpointParams,
+    scalarFlags: command.scalarParams.map((item) => item.name.replace(/([A-Z])/g, '-$1').toLowerCase()),
+  }
+}
+
+export async function executeCLI(scope: CommandScope, argv: string[], env: RuntimeEnv = loadRuntimeEnv(scope), fetchImpl: typeof fetch = fetch): Promise<any> {
+  const parsed = parseCLIArgs(argv)
+  if (parsed.commandTokens.length === 0) {
+    return { kind: 'help', text: renderRootHelp(scope) }
+  }
+  const [moduleName, commandName] = parsed.commandTokens
+  if (!moduleName) {
+    return { kind: 'help', text: renderRootHelp(scope) }
+  }
+  if (!commandName) {
+    return { kind: 'help', text: renderModuleHelp(scope, moduleName) }
+  }
+  if (hasFlag(parsed.flags, 'help')) {
+    return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName) }
+  }
+
+  const command = findCommand(scope, moduleName, commandName)
+  if (!command) {
+    throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
+  }
+
+  const endpoint = resolveEndpoint(command.endpoint, parsed.flags)
+  const scalarQuery = buildScalarQuery(command, parsed.flags)
+  const fileQuery = loadQueryFromFlags(parsed.flags)
+  const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) }
+  const body = loadBodyFromFlags(parsed.flags)
+
+  if (command.requestType) {
+    if (body === undefined) {
+      throw new CLIError('MISSING_BODY_FILE', `command requires --body-file for ${command.requestType}`, 2)
+    }
+    const schema = getBodySchema(command.requestType)
+    if (schema) {
+      const parsedBody = schema.safeParse(body)
+      if (!parsedBody.success) {
+        throw new CLIError(
+          'BODY_VALIDATION_FAILED',
+          parsedBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '),
+          2,
+          {
+            operation: `${scope}.${command.module}.${command.functionName}`,
+            requestType: command.requestType,
+            issues: parsedBody.error.issues.map((issue) => ({
+              path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',
+              message: issue.message,
+            })),
+            tsHints: getTypeHints(command.requestType),
+          }
+        )
+      }
+    } else {
+      const unsupportedReason = getUnsupportedBodySchemaReason(command.requestType)
+      if (unsupportedReason) {
+        throw new CLIError('UNSUPPORTED_BODY_SCHEMA', `${command.requestType}: ${unsupportedReason}`, 2, {
+          operation: `${scope}.${command.module}.${command.functionName}`,
+          requestType: command.requestType,
+          reason: unsupportedReason,
+          tsHints: getTypeHints(command.requestType),
+        })
+      }
+    }
+  }
+
+  const headers = buildRequestHeaders(env)
+  const response = await fetchImpl(buildURL(env.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
+    method: command.method,
+    headers: {
+      ...headers,
+      'Content-Type': 'application/json',
+    },
+    body: body === undefined || command.method === 'GET' ? undefined : JSON.stringify(body),
+  })
+
+  const raw = await response.text()
+  let parsedResponse: any = raw
+  try {
+    parsedResponse = raw ? JSON.parse(raw) : null
+  } catch {
+    // keep raw text
+  }
+  if (!response.ok) {
+    throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1)
+  }
+  return {
+    kind: 'result',
+    commandPath: command.commandPath,
+    status: response.status,
+    data: parsedResponse,
+  }
+}

package/src/runtime/http.ts

@@ -0,0 +1,23 @@
+import type { RuntimeEnv } from './env.js'
+
+export function buildRequestHeaders(env: Pick<RuntimeEnv, 'ARCUBASE_ACCESS_TOKEN' | 'ARCUBASE_TENANT_ID' | 'ARCUBASE_TRACE_ID'>): Record<string, string> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${env.ARCUBASE_ACCESS_TOKEN}`,
+    'X-Tenant-Id': env.ARCUBASE_TENANT_ID
+  }
+  if (env.ARCUBASE_TRACE_ID) {
+    headers['X-Trace-Id'] = env.ARCUBASE_TRACE_ID
+  }
+  return headers
+}
+
+export function buildURL(baseURL: string, endpoint: string, query?: Record<string, any>): string {
+  const url = new URL(endpoint, baseURL.endsWith('/') ? baseURL : `${baseURL}/`)
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null) continue
+      url.searchParams.set(key, typeof value === 'string' ? value : JSON.stringify(value))
+    }
+  }
+  return url.toString()
+}

package/src/runtime/output.ts

@@ -0,0 +1,3 @@
+export function writeJSON(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
+}

package/src/runtime/paths.ts

@@ -0,0 +1,8 @@
+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
+}

package/src/runtime/zod_registry.ts

@@ -0,0 +1,53 @@
+import type { ZodTypeAny } from 'zod'
+import { bodySchemas, unsupportedBodySchemas } from '../generated/zod_registry.generated.js'
+import { typeIndex } from '../generated/type_index.generated.js'
+
+export function getBodySchema(typeName: string): ZodTypeAny | null {
+  const name = String(typeName || '').trim()
+  if (!name) return null
+  return (bodySchemas as Record<string, ZodTypeAny | undefined>)[name] ?? null
+}
+
+export function getUnsupportedBodySchemaReason(typeName: string): string | null {
+  const name = String(typeName || '').trim()
+  if (!name) return null
+  return (unsupportedBodySchemas as Record<string, string | undefined>)[name] ?? null
+}
+
+export function requireBodySchema(typeName: string): ZodTypeAny {
+  const schema = getBodySchema(typeName)
+  if (schema) return schema
+  const reason = getUnsupportedBodySchemaReason(typeName)
+  if (reason) {
+    throw new Error(`runtime validation for ${typeName} is not supported: ${reason}`)
+  }
+  throw new Error(`runtime validation schema not found for ${typeName}`)
+}
+
+export type RuntimeTypeHint = {
+  symbol: string
+  file: string
+}
+
+export function getTypeHints(typeName: string): RuntimeTypeHint[] {
+  const name = String(typeName || '').trim()
+  if (!name) return []
+  const entry = (typeIndex as Record<string, { file: string; dependencies?: ReadonlyArray<RuntimeTypeHint> } | undefined>)[name]
+  if (!entry?.file) return []
+  const seen = new Set<string>()
+  const out: RuntimeTypeHint[] = []
+  const append = (symbol: string, file: string) => {
+    symbol = String(symbol || '').trim()
+    file = String(file || '').trim()
+    if (!symbol || !file) return
+    const key = `${symbol}@@${file}`
+    if (seen.has(key)) return
+    seen.add(key)
+    out.push({ symbol, file })
+  }
+  append(name, entry.file)
+  for (const dep of entry.dependencies ?? []) {
+    append(dep.symbol, dep.file)
+  }
+  return out
+}

package/src/tests/bootstrap.test.ts

@@ -0,0 +1,67 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { loadRuntimeEnv } from '../runtime/env.js'
+
+test('loadRuntimeEnv requires base url, tenant id and access token', () => {
+  assert.throws(() => loadRuntimeEnv('admin', {}), /ARCUBASE_BASE_URL is required/)
+})
+
+test('loadRuntimeEnv returns normalized runtime env', () => {
+  const env = loadRuntimeEnv('admin', {
+    ARCUBASE_BASE_URL: ' http://example.com ',
+    ARCUBASE_TENANT_ID: ' tenant-1 ',
+    ARCUBASE_ACCESS_TOKEN: ' token-1 ',
+    ARCUBASE_TRACE_ID: ' trace-1 '
+  })
+
+  assert.deepEqual(env, {
+    ARCUBASE_BASE_URL: 'http://example.com',
+    ARCUBASE_TENANT_ID: 'tenant-1',
+    ARCUBASE_ACCESS_TOKEN: 'token-1',
+    ARCUBASE_TRACE_ID: 'trace-1',
+    ARCUBASE_SUBJECT_TYPE: undefined,
+    ARCUBASE_SUBJECT_ID: undefined,
+    ARCUBASE_TOKEN_EXPIRES_AT: undefined
+  })
+})
+
+test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
+  const env = loadRuntimeEnv('admin', {
+    ARCUBASE_ADMIN_BASE_URL: ' https://admin.example.com ',
+    ARCUBASE_ADMIN_TENANT_ID: ' tenant-admin ',
+    ARCUBASE_ADMIN_ACCESS_TOKEN: ' token-admin ',
+    ARCUBASE_ADMIN_SUBJECT_TYPE: ' system_admin ',
+    ARCUBASE_ADMIN_SUBJECT_ID: ' user-admin ',
+  })
+
+  assert.deepEqual(env, {
+    ARCUBASE_BASE_URL: 'https://admin.example.com',
+    ARCUBASE_TENANT_ID: 'tenant-admin',
+    ARCUBASE_ACCESS_TOKEN: 'token-admin',
+    ARCUBASE_TRACE_ID: undefined,
+    ARCUBASE_SUBJECT_TYPE: 'system_admin',
+    ARCUBASE_SUBJECT_ID: 'user-admin',
+    ARCUBASE_TOKEN_EXPIRES_AT: undefined
+  })
+})
+
+test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
+  const env = loadRuntimeEnv('user', {
+    ARCUBASE_USER_BASE_URL: ' https://user.example.com ',
+    ARCUBASE_USER_TENANT_ID: ' tenant-user ',
+    ARCUBASE_USER_ACCESS_TOKEN: ' token-user ',
+    ARCUBASE_USER_SUBJECT_TYPE: ' service_account ',
+    ARCUBASE_USER_SUBJECT_ID: ' sa-user ',
+  })
+
+  assert.deepEqual(env, {
+    ARCUBASE_BASE_URL: 'https://user.example.com',
+    ARCUBASE_TENANT_ID: 'tenant-user',
+    ARCUBASE_ACCESS_TOKEN: 'token-user',
+    ARCUBASE_TRACE_ID: undefined,
+    ARCUBASE_SUBJECT_TYPE: 'service_account',
+    ARCUBASE_SUBJECT_ID: 'sa-user',
+    ARCUBASE_TOKEN_EXPIRES_AT: undefined
+  })
+})

package/src/tests/command_registry.test.ts

@@ -0,0 +1,27 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { adminCommands, userCommands } from '../generated/command_registry.generated.js'
+
+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('inline request type keeps full object text instead of truncated brace', () => {
+  const command = adminCommands.find((c) => c.commandPath.join(' ') === 'dashboard clone-dashboard')
+  assert.ok(command)
+  const typed = command!
+  assert.match(String(typed.requestType), /^\{\s*name:\s*string\s*\}$/)
+})
+
+test('tag commands no longer emit truncated inline request type', () => {
+  const command = adminCommands.find((c) => c.commandPath.join(' ') === 'entity-tags batch-add-entity-tags')
+  assert.ok(command)
+  const typed = command!
+  assert.match(String(typed.requestType), /^\{\s*policy_id:\s*string.*selection:\s*any.*tag_names:\s*string\[\]\s*\}$/)
+  assert.equal(typed.scalarParams.length, 0)
+})

package/src/tests/execute_validation.test.ts

@@ -0,0 +1,50 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { executeCLI } from '../runtime/execute.js'
+import { CLIError } from '../runtime/errors.js'
+
+const env = {
+  ARCUBASE_BASE_URL: 'https://arcubase.example.com/api/',
+  ARCUBASE_TENANT_ID: 'tenant_1',
+  ARCUBASE_ACCESS_TOKEN: 'tok',
+  ARCUBASE_TRACE_ID: '',
+  ARCUBASE_SUBJECT_TYPE: '',
+  ARCUBASE_SUBJECT_ID: '',
+  ARCUBASE_TOKEN_EXPIRES_AT: '',
+}
+
+function tempJSONFile(payload: unknown): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'arcubase-cli-'))
+  const filePath = path.join(dir, 'payload.json')
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2))
+  return filePath
+}
+
+test('admin save entity rejects invalid body file', async () => {
+  const invalidFile = tempJSONFile({ name: '订单', layout: 'bad-layout' })
+  await assert.rejects(async () => {
+    await executeCLI('admin', ['entity', 'admin-save-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', invalidFile], env as any, async () => new Response('{}'))
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.equal(error.details?.requestType, 'EntitySaveReqVO')
+    assert.ok((error.details?.issues ?? []).some((item) => item.path.startsWith('body.layout')))
+    assert.ok((error.details?.tsHints ?? []).some((item) => item.file.startsWith('/opt/arcubase-sdk/')))
+    return true
+  })
+})
+
+test('admin create entity executes with valid body file', async () => {
+  const bodyFile = tempJSONFile({ name: '订单', parent: 0 })
+  const out = await executeCLI(
+    'admin',
+    ['app', 'create-entity', '--id', 'app_1', '--body-file', bodyFile],
+    env as any,
+    async (url, init) => new Response(JSON.stringify({ ok: true, url, method: init?.method }), { status: 200 })
+  )
+  assert.equal(out.kind, 'result')
+  assert.equal(out.status, 200)
+})

package/src/tests/help.test.ts

@@ -0,0 +1,25 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { executeCLI } from '../runtime/execute.js'
+
+const env = {
+  ARCUBASE_BASE_URL: 'https://arcubase.example.com/api/',
+  ARCUBASE_TENANT_ID: 'tenant_1',
+  ARCUBASE_ACCESS_TOKEN: 'tok',
+  ARCUBASE_TRACE_ID: '',
+  ARCUBASE_SUBJECT_TYPE: '',
+  ARCUBASE_SUBJECT_ID: '',
+  ARCUBASE_TOKEN_EXPIRES_AT: '',
+}
+
+test('root help prints modules', async () => {
+  const out = await executeCLI('admin', ['--help'], env as any, async () => new Response('{}'))
+  assert.equal(out.kind, 'help')
+  assert.match(out.text, /app/)
+})
+
+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/)
+})