@carthooks/arcubase-cli 0.1.2 → 0.1.4

package/dist/runtime/execute.js

@@ -2,42 +2,82 @@ 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';
+import { renderUploadHelp, uploadLocalFile } from './upload.js';
+function summarizeUploadResult(value) {
+    return value;
+}
 export function renderRootHelp(scope) {
     const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase';
+    const items = listModules(scope).map((item) => `  - ${item}`);
     return [
         `${binary} <module> <command> [flags]`,
         '',
+        ...(scope === 'admin'
+            ? ['use arcubase-admin for app, entity shell, and schema management', '']
+            : ['use arcubase for row CRUD, search, selection actions, and bulk actions', '']),
         'modules:',
-        ...listModules(scope).map((item) => `  - ${item}`),
+        ...items,
+        ...(scope === 'user' ? ['', 'special commands:', '  - upload <local-file>'] : []),
     ].join('\n');
 }
 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]`,
         '',
+        ...(scope === 'admin'
+            ? ['use arcubase-admin for app, entity shell, and schema management', '']
+            : ['use arcubase for row CRUD, search, selection actions, and bulk actions', '']),
         'commands:',
         ...items.map((item) => `  - ${item.commandPath[1]}`),
     ].join('\n');
 }
+function buildUnknownCommandDetails(scope, moduleName, commandName) {
+    const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName} ${item.commandName}`);
+    if (scope === 'admin' && moduleName === 'workflow' && suggestions.some((item) => item.startsWith('arcubase workflow '))) {
+        return {
+            suggestions,
+            reason: `${moduleName} ${commandName} is a row operation, not an arcubase-admin command`,
+            hint: `use: arcubase ${moduleName} ${commandName}`,
+        };
+    }
+    return suggestions.length > 0 ? { suggestions } : undefined;
+}
 export function renderCommandHelp(scope, moduleName, commandName) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
-        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2);
+        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName));
     }
+    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',
+        ...(scope === 'admin' && moduleName === 'entity' && commandName === 'admin-save-entity'
+            ? [
+                'next step:',
+                '  - switch to arcubase for row operations',
+                '  - row insert: arcubase workflow insert-entity --app-id <app_id> --entity-id <entity_id> --body-file insert.json',
+                '  - row query: arcubase workflow query-entity --app-id <app_id> --entity-id <entity_id> --body-file query.json',
+            ]
+            : []),
+        ...(docHints.length > 0
+            ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
+            : []),
     ].join('\n');
 }
 function coerceScalar(value, typeText) {
@@ -84,10 +124,194 @@ 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 extractEntityFields(payload) {
+    const candidate = isRecord(payload) && isRecord(payload.data) ? payload.data : payload;
+    if (!isRecord(candidate) || !Array.isArray(candidate.fields)) {
+        return [];
+    }
+    return candidate.fields
+        .filter((item) => isRecord(item))
+        .filter((item) => typeof item.id === 'number' && typeof item.type === 'string')
+        .map((item) => ({
+        id: item.id,
+        type: item.type,
+        label: typeof item.label === 'string' ? item.label : undefined,
+    }));
+}
+async function fetchEntityFields(runtimeEnv, appId, entityId, fetchImpl) {
+    const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, `/entity/${encodeURIComponent(appId)}/${encodeURIComponent(entityId)}`), {
+        method: 'GET',
+        headers: buildRequestHeaders(runtimeEnv),
+    });
+    const raw = await response.text();
+    let parsedResponse = raw;
+    try {
+        parsedResponse = raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        parsedResponse = raw;
+    }
+    if (!response.ok) {
+        throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1);
+    }
+    if (isRecord(parsedResponse) && parsedResponse.error) {
+        const upstreamError = parsedResponse.error;
+        const upstreamMessage = isRecord(upstreamError) && typeof upstreamError.message === 'string'
+            ? upstreamError.message
+            : typeof upstreamError === 'string'
+                ? upstreamError
+                : JSON.stringify(upstreamError);
+        throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
+            endpoint: `/entity/${appId}/${entityId}`,
+            method: 'GET',
+            upstreamError,
+        });
+    }
+    const fields = extractEntityFields(parsedResponse);
+    return new Map(fields.map((field) => [field.id, field]));
+}
+function looksLikeLocalFilePath(value) {
+    return (value.startsWith('./') ||
+        value.startsWith('../') ||
+        value.startsWith('/') ||
+        value.startsWith('~/') ||
+        /\.(pdf|png|jpe?g|gif|webp|bmp|svg|heic|txt|csv|xlsx?|docx?|pptx?|zip)$/i.test(value));
+}
+function isValidUploadEntry(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const hasUploadId = typeof value.upload_id === 'number' || typeof value.upload_id === 'string';
+    const hasAssetsId = typeof value.assets_id === 'number' || typeof value.assets_id === 'string';
+    return (hasUploadId || hasAssetsId) && typeof value.file === 'string' && typeof value.file_name === 'string';
+}
+async function validateFileFieldPayloads(scope, command, runtimeEnv, flags, body, fetchImpl) {
+    if (!isRecord(body)) {
+        return;
+    }
+    const container = command.functionName === 'updateEntityRow' ? body.data : body.fields;
+    if (!isRecord(container)) {
+        return;
+    }
+    const appId = flagValue(flags, 'app-id');
+    const entityId = flagValue(flags, 'entity-id');
+    if (!appId || !entityId) {
+        return;
+    }
+    const fieldsById = await fetchEntityFields(runtimeEnv, appId, entityId, fetchImpl);
+    for (const [fieldIdText, value] of Object.entries(container)) {
+        if (!/^\d+$/.test(fieldIdText)) {
+            continue;
+        }
+        const fieldId = Number(fieldIdText);
+        const field = fieldsById.get(fieldId);
+        if (!field || (field.type !== 'file' && field.type !== 'image')) {
+            continue;
+        }
+        const fieldPath = command.functionName === 'updateEntityRow' ? `body.data.${fieldId}` : `body.fields.${fieldId}`;
+        const fieldName = field.label ? `${field.label} (${field.type})` : `${field.type} field ${fieldId}`;
+        if (typeof value === 'string') {
+            const guidance = looksLikeLocalFilePath(value)
+                ? `do not put a local file path directly into ${fieldName}; run "arcubase upload ${value}" first and use the returned data array as the field value`
+                : `${fieldName} must be an array returned by "arcubase upload <local-file>", not a string`;
+            throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
+                operation: `${scope}.${command.module}.${command.functionName}`,
+                requestType: command.requestType ?? undefined,
+                issues: [{ path: fieldPath, message: guidance }],
+                docHints: [
+                    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+                    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                ],
+            });
+        }
+        if (isRecord(value)) {
+            const guidance = `${fieldName} must be an array. Run "arcubase upload <local-file>" and use the returned data array directly as the field value`;
+            throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
+                operation: `${scope}.${command.module}.${command.functionName}`,
+                requestType: command.requestType ?? undefined,
+                issues: [{ path: fieldPath, message: guidance }],
+                docHints: [
+                    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+                    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                ],
+            });
+        }
+        if (!Array.isArray(value)) {
+            const guidance = `${fieldName} must be an array returned by "arcubase upload <local-file>"`;
+            throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
+                operation: `${scope}.${command.module}.${command.functionName}`,
+                requestType: command.requestType ?? undefined,
+                issues: [{ path: fieldPath, message: guidance }],
+                docHints: [
+                    { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+                    { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                ],
+            });
+        }
+        for (const [index, item] of value.entries()) {
+            if (!isValidUploadEntry(item)) {
+                const guidance = `${fieldName} entries must include upload_id or assets_id plus file and file_name. Use "arcubase upload <local-file>" and copy the returned array item as-is`;
+                throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
+                    operation: `${scope}.${command.module}.${command.functionName}`,
+                    requestType: command.requestType ?? undefined,
+                    issues: [{ path: `${fieldPath}.${index}`, message: guidance }],
+                    docHints: [
+                        { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+                        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                    ],
+                });
+            }
+        }
+    }
+}
+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);
+        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName));
     }
     return {
         scope,
@@ -99,8 +323,28 @@ 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 (scope === 'user' && parsed.commandTokens[0] === 'upload') {
+        if (hasFlag(parsed.flags, 'help') || parsed.commandTokens.length === 1) {
+            return { kind: 'help', text: renderUploadHelp() };
+        }
+        const sourcePath = parsed.commandTokens[1];
+        if (!sourcePath) {
+            throw new CLIError('UPLOAD_SOURCE_REQUIRED', 'upload requires a local file path', 2);
+        }
+        const runtimeEnv = env ?? loadRuntimeEnv(scope);
+        const data = await uploadLocalFile(runtimeEnv, sourcePath, {
+            filename: flagValue(parsed.flags, 'filename'),
+            global: hasFlag(parsed.flags, 'global'),
+        }, fetchImpl);
+        return {
+            kind: 'result',
+            commandPath: ['upload', sourcePath],
+            status: 200,
+            data,
+        };
+    }
     if (parsed.commandTokens.length === 0) {
         return { kind: 'help', text: renderRootHelp(scope) };
     }
@@ -114,15 +358,17 @@ 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);
+        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName));
     }
     const endpoint = normalizeExternalEndpoint(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);
+    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 +385,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 +399,21 @@ 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), {
+    if (scope === 'user' && (command.functionName === 'insertEntity' || command.functionName === 'updateEntityRow')) {
+        await validateFileFieldPayloads(scope, command, runtimeEnv, parsed.flags, validatedBody, fetchImpl);
+    }
+    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 +426,36 @@ 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;
+        const uploadBindFailure = upstreamMessage.includes('failed to bind upload to assets');
+        throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
+            endpoint,
+            method: command.method,
+            traceId,
+            upstreamError,
+            ...(uploadBindFailure
+                ? {
+                    reason: 'the row payload used a file/image upload entry, but Arcubase could not bind that upload into an asset record',
+                    hint: 'verify the upload storage host is reachable from the Arcubase server, then rerun arcubase upload and retry the row insert/update',
+                    docHints: [
+                        { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
+                        { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+                    ],
+                }
+                : {}),
+        });
+    }
     return {
         kind: 'result',
         commandPath: command.commandPath,

package/dist/runtime/upload.d.ts

@@ -0,0 +1,13 @@
+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[]>;
+//# sourceMappingURL=upload.d.ts.map

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

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

package/dist/runtime/upload.js

@@ -0,0 +1,148 @@
+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: '/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;
+}
+export function renderUploadHelp() {
+    return [
+        'arcubase upload <local-file> [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',
+        '',
+        'result shape:',
+        '  - data is a JSON array',
+        '  - use that array directly as the value of a file or image field in insert/update payloads',
+        '',
+        'example:',
+        '  arcubase upload ./contract.pdf',
+        '  arcubase upload ./photo.jpg --filename lead-photo.jpg',
+        '',
+        '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',
+    ].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, '/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: '/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

@@ -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;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"}