@carthooks/arcubase-cli 0.1.10 → 0.1.12

package/dist/runtime/paths.d.ts

@@ -1,4 +1,4 @@
 export declare const DEFAULT_ARCUBASE_CLI_ROOT = "/opt/arcubase-cli";
-export declare const DEFAULT_ARCUBASE_SDK_ROOT = "/opt/arcubase-sdk";
 export declare function resolveArcubaseSDKRoot(env?: Record<string, string | undefined>): string;
+export declare function resolveArcubaseSDKPath(filePath: string, env?: Record<string, string | undefined>): string;
 //# sourceMappingURL=paths.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/runtime/paths.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yBAAyB,sBAAsB,CAAA;AAC5D,eAAO,MAAM,yBAAyB,sBAAsB,CAAA;AAE5D,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAIpG"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/runtime/paths.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,yBAAyB,sBAAsB,CAAA;AAE5D,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAIpG;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAMtH"}

package/dist/runtime/paths.js

@@ -1,8 +1,15 @@
+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 = process.env) {
     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, env = process.env) {
+    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/dist/runtime/upload.d.ts

@@ -1,13 +1,3 @@
-import type { RuntimeEnv } from './env.js';
-export type ArcubaseUploadResult = {
-    upload_id: number | string;
-    file: string;
-    file_name: string;
-    meta: Record<string, never>;
-};
 export declare function renderUploadHelp(): string;
-export declare function uploadLocalFile(env: RuntimeEnv, sourcePath: string, options: {
-    filename?: string;
-    global?: boolean;
-}, fetchImpl?: typeof fetch): Promise<ArcubaseUploadResult[]>;
+export declare function uploadLocalFile(): Promise<never>;
 //# sourceMappingURL=upload.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../src/runtime/upload.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAuB1C,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;CAC5B,CAAA;AA+CD,wBAAgB,gBAAgB,IAAI,MAAM,CA0BzC;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,EACD,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAiFjC"}
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../src/runtime/upload.ts"],"names":[],"mappings":"AAOA,wBAAgB,gBAAgB,IAAI,MAAM,CAuBzC;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,KAAK,CAAC,CAItD"}

package/dist/runtime/upload.js

@@ -1,148 +1,34 @@
-import fs from 'fs';
-import path from 'path';
 import { CLIError } from './errors.js';
-import { buildRequestHeaders, buildURL } from './http.js';
-function readUploadSource(sourcePath) {
-    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) {
-    try {
-        return raw ? JSON.parse(raw) : null;
-    }
-    catch {
-        return raw;
-    }
-}
-function requireTokenPayload(payload) {
-    if (payload && typeof payload === 'object' && payload.error) {
-        const upstreamError = payload.error;
-        const message = typeof upstreamError === 'object' && upstreamError && 'message' in upstreamError && typeof upstreamError.message === 'string'
-            ? upstreamError.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;
+import { resolveArcubaseSDKPath } from './paths.js';
+function sdkPath(file) {
+    return resolveArcubaseSDKPath(file);
 }
 export function renderUploadHelp() {
     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, sourcePath, options, fetchImpl = fetch) {
-    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),
-        }),
+export async function uploadLocalFile() {
+    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 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);
-    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,
-    });
-    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/dist/runtime/zod_registry.d.ts

@@ -10,7 +10,9 @@ 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[];
+type EnvInput = Record<string, string | undefined>;
+export declare function getTypeHints(typeName: string, env?: EnvInput): RuntimeTypeHint[];
+export declare function getDocHints(typeName: string, env?: EnvInput): RuntimeDocHint[];
+export declare function getCommandDocHints(operation: string, env?: EnvInput): RuntimeDocHint[];
+export {};
 //# 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;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;AAyDD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAqBhE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAI9D;AA0DD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAItE"}
+{"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;AA8BrC,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;AAED,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAyGlD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,eAAe,EAAE,CAqB7F;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,cAAc,EAAE,CAI3F;AAwED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,cAAc,EAAE,CAInG"}

package/dist/runtime/zod_registry.js

@@ -1,5 +1,6 @@
 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, EntityInvokeBatchOperatorReqVOSchemaOverride, EntityQueryReqVOSchemaOverride, EntitySaveReqVOSchemaOverride, EntitySelectionActionReqVOSchemaOverride, EntityTagsBatchReqVOSchemaOverride, EntityTagsSelectionReqVOSchemaOverride, EntityUpdateReqVOSchemaOverride, InsertReqVOSchemaOverride, } from './entity_save_schema.js';
 const schemaOverrides = {
     AppCreateByTenantsReqVO: AppCreateByTenantsReqVOSchemaOverride,
@@ -38,60 +39,105 @@ export function requireBodySchema(typeName) {
     }
     throw new Error(`runtime validation schema not found for ${typeName}`);
 }
+function sdkPath(file, env = process.env) {
+    return resolveArcubaseSDKPath(file.replace(/^\/?opt\/arcubase-sdk\/?/, ''), env);
+}
+function resolveTypeHintFiles(hints, env = process.env) {
+    return hints.map((item) => ({ ...item, file: sdkPath(item.file, env) }));
+}
+function resolveDocHintFiles(hints, env = process.env) {
+    return hints.map((item) => ({ ...item, file: sdkPath(item.file, env) }));
+}
 const examplesIndexDocHint = {
     title: 'Examples index',
-    file: '/opt/arcubase-sdk/docs/runtime-reference/examples/README.md',
+    file: 'docs/runtime-reference/examples/README.md',
+};
+const selectionDocHint = {
+    title: 'Selection',
+    file: 'docs/runtime-reference/selection.md',
+};
+const conditionDocHint = {
+    title: 'Condition',
+    file: 'docs/runtime-reference/condition.md',
 };
 const docHintIndex = {
     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) {
+export function getTypeHints(typeName, env = process.env) {
     const name = String(typeName || '').trim();
     if (!name)
         return [];
@@ -115,72 +161,86 @@ export function getTypeHints(typeName) {
     for (const dep of entry.dependencies ?? []) {
         append(dep.symbol, dep.file);
     }
-    return out;
+    return resolveTypeHintFiles(out, env);
 }
-export function getDocHints(typeName) {
+export function getDocHints(typeName, env = process.env) {
     const name = String(typeName || '').trim();
     if (!name)
         return [];
-    return docHintIndex[name] ?? [];
+    return resolveDocHintFiles(docHintIndex[name] ?? [], env);
 }
 const commandDocHintIndex = {
     '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) {
+export function getCommandDocHints(operation, env = process.env) {
     const key = String(operation || '').trim();
     if (!key)
         return [];
-    return commandDocHintIndex[key] ?? [];
+    return resolveDocHintFiles(commandDocHintIndex[key] ?? [], env);
 }

package/dist/tests/bootstrap.test.js

@@ -4,15 +4,23 @@ import { loadRuntimeEnv } from '../runtime/env.js';
 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,
@@ -23,12 +31,14 @@ 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 ',
     });
     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',
@@ -39,12 +49,14 @@ 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 ',
     });
     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/dist/tests/command_registry.test.js

@@ -63,6 +63,12 @@ test('user surface is restricted to reset white list', () => {
     ].sort();
     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 = [
@@ -74,6 +80,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',

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

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

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

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