@carthooks/arcubase-cli 0.1.1 → 0.1.3

package/dist/runtime/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAgD,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAIvG,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CAC/B,CAAA;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQ1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAWhF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAatG;AA8CD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,uBAAuB,CActH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,UAAkC,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAyF5J"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAwE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAI/H,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CAC/B,CAAA;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQ1D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAYhF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAsBtG;AAyHD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,uBAAuB,CAetH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAoHrI"}

package/dist/runtime/execute.js

@@ -2,9 +2,9 @@ import { parseCLIArgs, hasFlag, flagValue } from './argv.js';
 import { loadRuntimeEnv } from './env.js';
 import { CLIError } from './errors.js';
 import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js';
-import { listModules, listModuleCommands, findCommand } from './command_registry.js';
+import { listModules, listModuleCommands, findCommand, findCommandSuggestions } from './command_registry.js';
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js';
-import { getBodySchema, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js';
+import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js';
 export function renderRootHelp(scope) {
     const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase';
     return [
@@ -17,7 +17,8 @@ export function renderRootHelp(scope) {
 export function renderModuleHelp(scope, moduleName) {
     const items = listModuleCommands(scope, moduleName);
     if (items.length === 0) {
-        throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2);
+        const suggestions = findCommandSuggestions(moduleName, '').map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`);
+        throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2, suggestions.length > 0 ? { suggestions } : undefined);
     }
     return [
         `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} <command> [flags]`,
@@ -29,15 +30,24 @@ export function renderModuleHelp(scope, moduleName) {
 export function renderCommandHelp(scope, moduleName, commandName) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
-        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2);
+        const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`);
+        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, suggestions.length > 0 ? { suggestions } : undefined);
     }
+    const docHints = [
+        ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`),
+        ...(command.requestType ? getDocHints(command.requestType) : []),
+    ].filter((item, index, list) => list.findIndex((candidate) => candidate.file === item.file) === index);
     return [
         `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} ${commandName}`,
         `method: ${command.method}`,
         `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
         command.requestType ? `body: ${command.requestType} via --body-file` : 'body: none',
+        'query flags: --query-file',
         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',
+        ...(docHints.length > 0
+            ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
+            : []),
     ].join('\n');
 }
 function coerceScalar(value, typeText) {
@@ -84,10 +94,55 @@ function buildScalarQuery(command, flags) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function throwBodyValidationFailure(message, requestType, path, scope, command) {
+    throw new CLIError('BODY_VALIDATION_FAILED', message, 2, {
+        operation: `${scope}.${command.module}.${command.functionName}`,
+        requestType,
+        issues: [
+            {
+                path,
+                message,
+            },
+        ],
+        tsHints: getTypeHints(requestType),
+        docHints: getDocHints(requestType),
+    });
+}
+function validateActionSpecificBody(scope, command, flags, body) {
+    if (!isRecord(body) || !command.requestType) {
+        return;
+    }
+    if (command.module === 'workflow' && command.functionName === 'queryEntitySelection') {
+        const action = flagValue(flags, 'action');
+        const selection = body.selection;
+        if (!isRecord(selection) || typeof selection.type !== 'string') {
+            return;
+        }
+        const type = selection.type;
+        const condition = isRecord(selection.condition) ? selection.condition : undefined;
+        const conditionKeys = condition ? Object.keys(condition).filter((key) => key !== 'selectAll') : [];
+        if (action === 'query') {
+            if (type === 'condition') {
+                throwBodyValidationFailure('selection.type=condition is not supported for action=query; use selection.type=ids or selection.type=all, or use workflow query-entity for search conditions', command.requestType, 'body.selection.type', scope, command);
+            }
+            return;
+        }
+        if ((action === 'archive' || action === 'delete' || action === 'batch_print') && type === 'all') {
+            throwBodyValidationFailure(`selection.type=all is not supported for action=${action}; use ids or condition`, command.requestType, 'body.selection.type', scope, command);
+        }
+        if ((action === 'archive' || action === 'delete') && type === 'condition' && conditionKeys.length === 0) {
+            throwBodyValidationFailure(`selection.condition for action=${action} requires at least one q, tab, or filter_* key in addition to selectAll`, command.requestType, 'body.selection.condition', scope, command);
+        }
+    }
+}
 export function summarizeCommand(scope, moduleName, commandName) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
-        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2);
+        const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`);
+        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, suggestions.length > 0 ? { suggestions } : undefined);
     }
     return {
         scope,
@@ -99,7 +154,7 @@ export function summarizeCommand(scope, moduleName, commandName) {
         scalarFlags: command.scalarParams.map((item) => item.name.replace(/([A-Z])/g, '-$1').toLowerCase()),
     };
 }
-export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl = fetch) {
+export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     const parsed = parseCLIArgs(argv);
     if (parsed.commandTokens.length === 0) {
         return { kind: 'help', text: renderRootHelp(scope) };
@@ -114,6 +169,7 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
     if (hasFlag(parsed.flags, 'help')) {
         return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName) };
     }
+    const runtimeEnv = env ?? loadRuntimeEnv(scope);
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
         throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2);
@@ -123,6 +179,7 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
     const fileQuery = loadQueryFromFlags(parsed.flags);
     const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) };
     const body = loadBodyFromFlags(parsed.flags);
+    let validatedBody = body;
     if (command.requestType) {
         if (body === undefined) {
             throw new CLIError('MISSING_BODY_FILE', `command requires --body-file for ${command.requestType}`, 2);
@@ -139,8 +196,11 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
                         message: issue.message,
                     })),
                     tsHints: getTypeHints(command.requestType),
+                    docHints: getDocHints(command.requestType),
                 });
             }
+            validatedBody = parsedBody.data;
+            validateActionSpecificBody(scope, command, parsed.flags, validatedBody);
         }
         else {
             const unsupportedReason = getUnsupportedBodySchemaReason(command.requestType);
@@ -150,18 +210,18 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
                     requestType: command.requestType,
                     reason: unsupportedReason,
                     tsHints: getTypeHints(command.requestType),
+                    docHints: getDocHints(command.requestType),
                 });
             }
         }
     }
-    const headers = buildRequestHeaders(env);
-    const response = await fetchImpl(buildURL(env.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
+    const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
         method: command.method,
         headers: {
-            ...headers,
+            ...buildRequestHeaders(runtimeEnv),
             'Content-Type': 'application/json',
         },
-        body: body === undefined || command.method === 'GET' ? undefined : JSON.stringify(body),
+        body: validatedBody === undefined || command.method === 'GET' ? undefined : JSON.stringify(validatedBody),
     });
     const raw = await response.text();
     let parsedResponse = raw;
@@ -174,6 +234,25 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
     if (!response.ok) {
         throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1);
     }
+    if (parsedResponse && typeof parsedResponse === 'object' && 'error' in parsedResponse && parsedResponse.error) {
+        const upstreamError = parsedResponse.error;
+        const upstreamMessage = typeof upstreamError === 'object' && upstreamError && 'message' in upstreamError && typeof upstreamError.message === 'string'
+            ? upstreamError.message
+            : typeof upstreamError === 'string'
+                ? upstreamError
+                : JSON.stringify(upstreamError);
+        const traceId = typeof parsedResponse.trace_id === 'string'
+            ? parsedResponse.trace_id
+            : typeof parsedResponse.request_id === 'string'
+                ? parsedResponse.request_id
+                : undefined;
+        throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
+            endpoint,
+            method: command.method,
+            traceId,
+            upstreamError,
+        });
+    }
     return {
         kind: 'result',
         commandPath: command.commandPath,

package/dist/runtime/http.d.ts

@@ -1,5 +1,5 @@
 import type { RuntimeEnv } from './env.js';
-export declare function buildRequestHeaders(env: Pick<RuntimeEnv, 'ARCUBASE_ACCESS_TOKEN' | 'ARCUBASE_TENANT_ID' | 'ARCUBASE_TRACE_ID'>): Record<string, string>;
+export declare function buildRequestHeaders(env: Pick<RuntimeEnv, 'ARCUBASE_ACCESS_TOKEN' | 'ARCUBASE_TENANT_ID' | 'ARCUBASE_HOST' | 'ARCUBASE_TRACE_ID'>): Record<string, string>;
 export declare function normalizeExternalEndpoint(endpoint: string): string;
 export declare function buildURL(baseURL: string, endpoint: string, query?: Record<string, any>): string;
 //# sourceMappingURL=http.d.ts.map

package/dist/runtime/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/runtime/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,uBAAuB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvJ;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CASlE;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAS/F"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/runtime/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,uBAAuB,GAAG,oBAAoB,GAAG,eAAe,GAAG,mBAAmB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYzK;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CASlE;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAS/F"}

package/dist/runtime/http.js

@@ -3,6 +3,9 @@ export function buildRequestHeaders(env) {
         Authorization: `Bearer ${env.ARCUBASE_ACCESS_TOKEN}`,
         'X-Tenant-Id': env.ARCUBASE_TENANT_ID
     };
+    if (env.ARCUBASE_HOST && env.ARCUBASE_HOST.trim() !== '') {
+        headers['X-Host'] = env.ARCUBASE_HOST;
+    }
     if (env.ARCUBASE_TRACE_ID) {
         headers['X-Trace-Id'] = env.ARCUBASE_TRACE_ID;
     }

package/dist/runtime/zod_registry.d.ts

@@ -6,5 +6,11 @@ export type RuntimeTypeHint = {
     symbol: string;
     file: string;
 };
+export type RuntimeDocHint = {
+    title: string;
+    file: string;
+};
 export declare function getTypeHints(typeName: string): RuntimeTypeHint[];
+export declare function getDocHints(typeName: string): RuntimeDocHint[];
+export declare function getCommandDocHints(operation: string): RuntimeDocHint[];
 //# sourceMappingURL=zod_registry.d.ts.map

package/dist/runtime/zod_registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zod_registry.d.ts","sourceRoot":"","sources":["../../src/runtime/zod_registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AAIrC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAIjE;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQ9D;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAqBhE"}
+{"version":3,"file":"zod_registry.d.ts","sourceRoot":"","sources":["../../src/runtime/zod_registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAA;AA6BrC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAOjE;AAED,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQ9D;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AA2DD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAqBhE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAI9D;AAsDD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAItE"}

package/dist/runtime/zod_registry.js

@@ -1,9 +1,25 @@
 import { bodySchemas, unsupportedBodySchemas } from '../generated/zod_registry.generated.js';
 import { typeIndex } from '../generated/type_index.generated.js';
+import { AppCreateByTenantsReqVOSchemaOverride, EntityBulkUpdateReqVOSchemaOverride, EntityInvokeBatchOperatorReqVOSchemaOverride, EntityQueryReqVOSchemaOverride, EntitySaveReqVOSchemaOverride, EntitySelectionActionReqVOSchemaOverride, EntityTagsBatchReqVOSchemaOverride, EntityTagsSelectionReqVOSchemaOverride, EntityUpdateReqVOSchemaOverride, InsertReqVOSchemaOverride, } from './entity_save_schema.js';
+const schemaOverrides = {
+    AppCreateByTenantsReqVO: AppCreateByTenantsReqVOSchemaOverride,
+    EntityBulkUpdateReqVO: EntityBulkUpdateReqVOSchemaOverride,
+    'EntityInvokeBatchOperatorReqVO & InvokeRequestVO': EntityInvokeBatchOperatorReqVOSchemaOverride,
+    EntityQueryReqVO: EntityQueryReqVOSchemaOverride,
+    EntitySaveReqVO: EntitySaveReqVOSchemaOverride,
+    EntitySelectionActionReqVO: EntitySelectionActionReqVOSchemaOverride,
+    '{ policy_id: string selection: any }': EntityTagsSelectionReqVOSchemaOverride,
+    '{ policy_id: string selection: any tag_names: string[] }': EntityTagsBatchReqVOSchemaOverride,
+    EntityUpdateReqVO: EntityUpdateReqVOSchemaOverride,
+    InsertReqVO: InsertReqVOSchemaOverride,
+};
 export function getBodySchema(typeName) {
     const name = String(typeName || '').trim();
     if (!name)
         return null;
+    if (schemaOverrides[name]) {
+        return schemaOverrides[name];
+    }
     return bodySchemas[name] ?? null;
 }
 export function getUnsupportedBodySchemaReason(typeName) {
@@ -22,6 +38,60 @@ export function requireBodySchema(typeName) {
     }
     throw new Error(`runtime validation schema not found for ${typeName}`);
 }
+const examplesIndexDocHint = {
+    title: 'Examples index',
+    file: '/opt/arcubase-sdk/docs/runtime-reference/examples/README.md',
+};
+const omsExampleDocHint = {
+    title: 'OMS example 01',
+    file: '/opt/arcubase-sdk/docs/runtime-reference/examples/oms-01/README.md',
+};
+const docHintIndex = {
+    AppCreateByTenantsReqVO: [
+        { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+        examplesIndexDocHint,
+        omsExampleDocHint,
+    ],
+    AppCreateEntityReqVO: [
+        { 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,
+    ],
+    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,
+    ],
+    EntityUpdateReqVO: [
+        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        omsExampleDocHint,
+    ],
+    EntitySelectionActionReqVO: [
+        { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+        omsExampleDocHint,
+    ],
+    InsertReqVO: [
+        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        omsExampleDocHint,
+    ],
+    EntityBulkUpdateReqVO: [
+        { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+        omsExampleDocHint,
+    ],
+    'EntityInvokeBatchOperatorReqVO & InvokeRequestVO': [
+        { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    ],
+    '{ policy_id: string selection: any }': [
+        { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+    ],
+    '{ 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' },
+    ],
+};
 export function getTypeHints(typeName) {
     const name = String(typeName || '').trim();
     if (!name)
@@ -48,3 +118,66 @@ export function getTypeHints(typeName) {
     }
     return out;
 }
+export function getDocHints(typeName) {
+    const name = String(typeName || '').trim();
+    if (!name)
+        return [];
+    return docHintIndex[name] ?? [];
+}
+const commandDocHintIndex = {
+    'admin.app.createAppByTenants': [
+        { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+        examplesIndexDocHint,
+        omsExampleDocHint,
+    ],
+    'admin.app.createEntity': [
+        { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+        omsExampleDocHint,
+    ],
+    'admin.entity.adminGetEntityInfo': [
+        { title: 'Table lifecycle', file: '/opt/arcubase-sdk/docs/runtime-reference/table-lifecycle.md' },
+        omsExampleDocHint,
+    ],
+    'admin.entity.adminSaveEntity': [
+        { title: 'Entity schema', file: '/opt/arcubase-sdk/docs/runtime-reference/entity-schema.md' },
+        omsExampleDocHint,
+    ],
+    'user.workflow.insertEntity': [
+        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        omsExampleDocHint,
+    ],
+    'user.workflow.queryEntity': [
+        { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+        omsExampleDocHint,
+    ],
+    'user.workflow.getEntityRow': [
+        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        omsExampleDocHint,
+    ],
+    'user.workflow.updateEntityRow': [
+        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        omsExampleDocHint,
+    ],
+    'user.workflow.queryEntitySelection': [
+        { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+        omsExampleDocHint,
+    ],
+    'user.workflow.deleteEntityRow': [
+        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        omsExampleDocHint,
+    ],
+    'user.workflow.restoreEntityRow': [
+        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+        omsExampleDocHint,
+    ],
+    'user.entity.updateEntityBulk': [
+        { title: 'Search and bulk actions', file: '/opt/arcubase-sdk/docs/runtime-reference/search-and-bulk-actions.md' },
+        omsExampleDocHint,
+    ],
+};
+export function getCommandDocHints(operation) {
+    const key = String(operation || '').trim();
+    if (!key)
+        return [];
+    return commandDocHintIndex[key] ?? [];
+}

package/dist/tests/bootstrap.test.js

@@ -15,6 +15,7 @@ test('loadRuntimeEnv returns normalized runtime env', () => {
         ARCUBASE_BASE_URL: 'http://example.com',
         ARCUBASE_TENANT_ID: 'tenant-1',
         ARCUBASE_ACCESS_TOKEN: 'token-1',
+        ARCUBASE_HOST: undefined,
         ARCUBASE_TRACE_ID: 'trace-1',
         ARCUBASE_SUBJECT_TYPE: undefined,
         ARCUBASE_SUBJECT_ID: undefined,
@@ -26,6 +27,7 @@ test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
         ARCUBASE_ADMIN_BASE_URL: ' https://admin.example.com ',
         ARCUBASE_ADMIN_TENANT_ID: ' tenant-admin ',
         ARCUBASE_ADMIN_ACCESS_TOKEN: ' token-admin ',
+        ARCUBASE_ADMIN_HOST: ' tenant-admin.arcubase.co ',
         ARCUBASE_ADMIN_SUBJECT_TYPE: ' system_admin ',
         ARCUBASE_ADMIN_SUBJECT_ID: ' user-admin ',
     });
@@ -33,6 +35,7 @@ test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
         ARCUBASE_BASE_URL: 'https://admin.example.com',
         ARCUBASE_TENANT_ID: 'tenant-admin',
         ARCUBASE_ACCESS_TOKEN: 'token-admin',
+        ARCUBASE_HOST: 'tenant-admin.arcubase.co',
         ARCUBASE_TRACE_ID: undefined,
         ARCUBASE_SUBJECT_TYPE: 'system_admin',
         ARCUBASE_SUBJECT_ID: 'user-admin',
@@ -44,6 +47,7 @@ test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
         ARCUBASE_USER_BASE_URL: ' https://user.example.com ',
         ARCUBASE_USER_TENANT_ID: ' tenant-user ',
         ARCUBASE_USER_ACCESS_TOKEN: ' token-user ',
+        ARCUBASE_USER_HOST: ' tenant-user.arcubase.co ',
         ARCUBASE_USER_SUBJECT_TYPE: ' service_account ',
         ARCUBASE_USER_SUBJECT_ID: ' sa-user ',
     });
@@ -51,6 +55,7 @@ test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
         ARCUBASE_BASE_URL: 'https://user.example.com',
         ARCUBASE_TENANT_ID: 'tenant-user',
         ARCUBASE_ACCESS_TOKEN: 'token-user',
+        ARCUBASE_HOST: 'tenant-user.arcubase.co',
         ARCUBASE_TRACE_ID: undefined,
         ARCUBASE_SUBJECT_TYPE: 'service_account',
         ARCUBASE_SUBJECT_ID: 'sa-user',

package/dist/tests/command_registry.test.js

@@ -1,6 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { adminCommands, userCommands } from '../generated/command_registry.generated.js';
+import { findCommandSuggestions } from '../runtime/command_registry.js';
 test('admin app create-entity command exists', () => {
     assert.ok(adminCommands.some((c) => c.commandPath.join(' ') === 'app create-entity'));
 });
@@ -20,3 +21,7 @@ test('tag commands no longer emit truncated inline request type', () => {
     assert.match(String(typed.requestType), /^\{\s*policy_id:\s*string.*selection:\s*any.*tag_names:\s*string\[\]\s*\}$/);
     assert.equal(typed.scalarParams.length, 0);
 });
+test('suggestions can point wrong admin delete guess to user workflow 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'));
+});

package/dist/tests/entity_save_schema.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entity_save_schema.test.d.ts.map

package/dist/tests/entity_save_schema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity_save_schema.test.d.ts","sourceRoot":"","sources":["../../src/tests/entity_save_schema.test.ts"],"names":[],"mappings":""}