@carthooks/arcubase-cli 0.1.3 → 0.1.5

package/dist/runtime/execute.js

@@ -5,13 +5,122 @@ import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http
 import { listModules, listModuleCommands, findCommand, findCommandSuggestions } from './command_registry.js';
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js';
 import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js';
+import { renderUploadHelp, uploadLocalFile } from './upload.js';
+function summarizeUploadResult(value) {
+    return value;
+}
+function parseJSONResponse(raw) {
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function unwrapResponseData(payload) {
+    return isRecord(payload) && 'data' in payload ? payload.data : payload;
+}
+function formatUpstreamError(payload) {
+    if (typeof payload === 'string') {
+        return payload;
+    }
+    if (isRecord(payload) && isRecord(payload.error) && typeof payload.error.message === 'string') {
+        return payload.error.message;
+    }
+    return JSON.stringify(payload);
+}
+function extractApps(payload) {
+    const data = unwrapResponseData(payload);
+    if (!Array.isArray(data))
+        return [];
+    return data
+        .filter((item) => isRecord(item))
+        .filter((item) => item.id !== undefined && typeof item.name === 'string')
+        .map((item) => ({
+        id: String(item.id),
+        name: item.name,
+    }));
+}
+function extractEntities(payload) {
+    const data = unwrapResponseData(payload);
+    if (!Array.isArray(data))
+        return [];
+    return data
+        .filter((item) => isRecord(item))
+        .filter((item) => item.id !== undefined && typeof item.name === 'string')
+        .map((item) => ({
+        id: String(item.id),
+        name: item.name,
+    }));
+}
+async function executeAppInventory(runtimeEnv, fetchImpl) {
+    const appsResponse = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, '/apps'), {
+        method: 'GET',
+        headers: buildRequestHeaders(runtimeEnv),
+    });
+    const appsRaw = await appsResponse.text();
+    const appsPayload = parseJSONResponse(appsRaw);
+    if (!appsResponse.ok) {
+        throw new CLIError('UPSTREAM_REQUEST_FAILED', formatUpstreamError(appsPayload), 1);
+    }
+    if (isRecord(appsPayload) && appsPayload.error) {
+        throw new CLIError('UPSTREAM_BODY_ERROR', formatUpstreamError(appsPayload), 1, {
+            endpoint: '/apps',
+            method: 'GET',
+            upstreamError: appsPayload.error,
+        });
+    }
+    const apps = extractApps(appsPayload);
+    const items = [];
+    for (const app of apps) {
+        const entitiesResponse = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, `/apps/${encodeURIComponent(app.id)}/entities`), {
+            method: 'POST',
+            headers: {
+                ...buildRequestHeaders(runtimeEnv),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({}),
+        });
+        const entitiesRaw = await entitiesResponse.text();
+        const entitiesPayload = parseJSONResponse(entitiesRaw);
+        if (!entitiesResponse.ok) {
+            throw new CLIError('UPSTREAM_REQUEST_FAILED', formatUpstreamError(entitiesPayload), 1);
+        }
+        if (isRecord(entitiesPayload) && entitiesPayload.error) {
+            throw new CLIError('UPSTREAM_BODY_ERROR', formatUpstreamError(entitiesPayload), 1, {
+                endpoint: `/apps/${app.id}/entities`,
+                method: 'POST',
+                upstreamError: entitiesPayload.error,
+            });
+        }
+        items.push({
+            ...app,
+            entities: extractEntities(entitiesPayload),
+        });
+    }
+    return {
+        kind: 'result',
+        commandPath: ['app', 'inventory'],
+        status: 200,
+        data: {
+            apps: items,
+        },
+    };
+}
 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 rows, 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) {
@@ -23,15 +132,28 @@ export function renderModuleHelp(scope, moduleName) {
     return [
         `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} <command> [flags]`,
         '',
+        ...(scope === 'admin'
+            ? ['use arcubase-admin for app, entity shell, and schema management', '']
+            : ['use arcubase for rows, 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 rows '))) {
+        return {
+            suggestions,
+            reason: `${moduleName} ${commandName} is not a valid command group; use arcubase rows for row operations`,
+            hint: `use: arcubase rows ${commandName}`,
+        };
+    }
+    return suggestions.length > 0 ? { suggestions } : undefined;
+}
 export function renderCommandHelp(scope, moduleName, commandName) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
-        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);
+        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName));
     }
     const docHints = [
         ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`),
@@ -45,6 +167,21 @@ export function renderCommandHelp(scope, moduleName, commandName) {
         '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 rows insert-entity --app-id <app_id> --entity-id <entity_id> --body-file insert.json',
+                '  - row query: arcubase rows query-entity --app-id <app_id> --entity-id <entity_id> --body-file query.json',
+            ]
+            : []),
+        ...(scope === 'admin' && moduleName === 'app' && commandName === 'inventory'
+            ? [
+                'purpose:',
+                '  - list all accessible apps and each app entity list in one call sequence',
+                '  - use this before asking the user for app_id',
+            ]
+            : []),
         ...(docHints.length > 0
             ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
             : []),
@@ -97,6 +234,146 @@ function buildScalarQuery(command, flags) {
 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}`,
@@ -115,7 +392,7 @@ function validateActionSpecificBody(scope, command, flags, body) {
     if (!isRecord(body) || !command.requestType) {
         return;
     }
-    if (command.module === 'workflow' && command.functionName === 'queryEntitySelection') {
+    if (command.module === 'rows' && command.functionName === 'queryEntitySelection') {
         const action = flagValue(flags, 'action');
         const selection = body.selection;
         if (!isRecord(selection) || typeof selection.type !== 'string') {
@@ -126,7 +403,7 @@ function validateActionSpecificBody(scope, command, flags, body) {
         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);
+                throwBodyValidationFailure('selection.type=condition is not supported for action=query; use selection.type=ids or selection.type=all, or use rows query-entity for search conditions', command.requestType, 'body.selection.type', scope, command);
             }
             return;
         }
@@ -141,8 +418,7 @@ function validateActionSpecificBody(scope, command, flags, body) {
 export function summarizeCommand(scope, moduleName, commandName) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
-        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);
+        throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName));
     }
     return {
         scope,
@@ -156,6 +432,26 @@ export function summarizeCommand(scope, moduleName, commandName) {
 }
 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) };
     }
@@ -172,7 +468,10 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     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));
+    }
+    if (scope === 'admin' && moduleName === 'app' && commandName === 'inventory') {
+        return executeAppInventory(runtimeEnv, fetchImpl);
     }
     const endpoint = normalizeExternalEndpoint(resolveEndpoint(command.endpoint, parsed.flags));
     const scalarQuery = buildScalarQuery(command, parsed.flags);
@@ -215,6 +514,9 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
             }
         }
     }
+    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: {
@@ -246,11 +548,22 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
             : 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 {

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.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;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"}
+{"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;AAgED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAqBhE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAI9D;AAqED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAItE"}