@carthooks/arcubase-cli 0.1.12 → 0.1.15

package/dist/runtime/execute.js

@@ -1,3 +1,5 @@
+import fs from 'fs';
+import path from 'path';
 import { parseCLIArgs, hasFlag, flagValue } from './argv.js';
 import { loadRuntimeEnv } from './env.js';
 import { CLIError } from './errors.js';
@@ -6,6 +8,8 @@ import { listModules, listModuleCommands, findCommand, findCommandSuggestions }
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js';
 import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js';
 import { resolveArcubaseSDKPath } from './paths.js';
+import { compileCSVImportMapping, compileExcelImportMapping } from './entity_import_mapping.js';
+import { uploadLocalFileWithToken } from './local_upload.js';
 export function renderRootHelp(scope) {
     const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase';
     const items = listModules(scope).map((item) => `  - ${item}`);
@@ -104,8 +108,9 @@ export function renderCommandHelp(scope, moduleName, commandName, env = process.
             : []),
         ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'create'
             ? [
-                'body-json example:',
-                '  - {"name":"Sales read write","enabled":true,"type":"form","options":{"user_scope":[{"type":"user","id":2188889901}],"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":false,"all_fields_write":false,"fields":[{"key":":1001","read":true,"write":true,"report":false},{"key":":1002","read":false,"write":false,"report":false}]},"list_options":{}}}',
+                'body-json examples:',
+                `  - full access: ${JSON.stringify(buildFullAccessRuleBody())}`,
+                `  - hide field: ${JSON.stringify(buildHiddenFieldAccessRuleBody())}`,
                 'success requires:',
                 '  - result.enabled must be true',
                 '  - options.user_scope[].type is "user" for tenant users',
@@ -124,6 +129,48 @@ export function renderCommandHelp(scope, moduleName, commandName, env = process.
                 '  - If result.enabled is false, enable the rule first and retry assign-users',
             ]
             : []),
+        ...(scope === 'admin' && command.commandPath[0] === 'app' && command.commandPath[1] === 'create-from-bundle-url'
+            ? [
+                'flags:',
+                '  - --url must be a public http/https app bundle zip URL',
+                '  - --name optionally overrides the imported app name',
+                'success:',
+                '  - returns task_id; use app watch-import-task to wait for completion',
+            ]
+            : []),
+        ...(scope === 'admin' && command.commandPath[0] === 'app' && command.commandPath[1] === 'watch-import-task'
+            ? [
+                'flags:',
+                '  - --task-id is returned by app create-from-bundle-url',
+                '  - --ttl-seconds is a local wait limit and does not cancel the backend task',
+                'success:',
+                '  - returns finished task status with app_id and warnings',
+            ]
+            : []),
+        ...(scope === 'user' && command.commandPath[0] === 'row' && command.commandPath[1] === 'import-excel'
+            ? [
+                'mapping-file example:',
+                '  - {"sheet":"Sheet1","mode":"addonly","headerRow":1,"dataStartRow":2,"fields":[{"fieldId":1001,"column":"A"}]}',
+                'rules:',
+                '  - import supports local file paths only',
+                '  - --file must be a local Excel file path',
+                '  - Excel columns use letters such as A, B, AA',
+                '  - row numbers are 1-based',
+                '  - fieldId must be numeric; use arcubase-admin table get --app-id <app_id> --table-id <table_id>',
+            ]
+            : []),
+        ...(scope === 'user' && command.commandPath[0] === 'row' && command.commandPath[1] === 'import-csv'
+            ? [
+                'mapping-file example:',
+                '  - {"mode":"addonly","header":true,"dataStartRow":2,"fields":[{"fieldId":1001,"header":"客户名称"}]}',
+                'rules:',
+                '  - import supports local file paths only',
+                '  - --file must be a local CSV file path',
+                '  - CSV mapping uses headers, not column indexes',
+                '  - CSV import does not support embedded images',
+                '  - fieldId must be numeric; use arcubase-admin table get --app-id <app_id> --table-id <table_id>',
+            ]
+            : []),
         ...(docHints.length > 0
             ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
             : []),
@@ -207,6 +254,18 @@ function buildUnknownFlagDetails(command, flag, env = process.env) {
         operation,
         hint: `run ${operation} --help for the supported flags`,
     };
+    if (command.commandPath[0] === 'app' && command.commandPath[1] === 'create' && flag === 'url') {
+        details.hint = 'app bundle URLs must use app create-from-bundle-url; do not retry app create';
+        details.commonMistakes = [
+            'do not use app create for app bundle URLs',
+            'do not put url inside app create --body-json',
+        ];
+        details.suggestions = [
+            'retry with: app create-from-bundle-url --url <public_http_zip_url> --name <app_name>',
+            'then watch with: app watch-import-task --task-id <task_id> --ttl-seconds 300',
+        ];
+        return details;
+    }
     if (command.requestType) {
         details.requestType = command.requestType;
         details.tsHints = getTypeHints(command.requestType, env);
@@ -218,8 +277,7 @@ function buildUnknownFlagDetails(command, flag, env = process.env) {
         details.suggestions = [`retry with: ${command.commandPath.join(' ')} ${command.pathParams.filter((item) => !getFixedValue(item)).map((item) => `--${item.flag} <${item.flag.replace(/-/g, '_')}>`).join(' ')} --body-json '<json>'`.replace(/\s+/g, ' ').trim()];
     }
     if (command.commandPath[0] === 'row' && command.commandPath[1] === 'query' && ['limit', 'offset', 'search', 'sorts', 'view-mode'].includes(flag)) {
-        details.shapeHint = { limit: 20, offset: 0, search: { text_search: 'SO-1001' } };
-        details.suggestions = ['retry with: row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0}\''];
+        Object.assign(details, buildBodyGuidance('EntityQueryReqVO'));
     }
     if (command.commandPath[0] === 'table' && command.commandPath[1] === 'dataset' && ['app-id', 'table-id'].includes(flag)) {
         details.hint = 'table dataset uses --dataset-id and --node-id; use table get for app/table metadata';
@@ -485,7 +543,7 @@ function buildTableCreateExampleBody() {
                 depends: [],
                 key: 'vote_description',
                 code_index: false,
-                options: { placeholder: '', html: false, size: 'default', lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
+                options: { placeholder: '', html: false, size: 6, lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
                 transfers: null,
                 children: null,
             },
@@ -500,6 +558,9 @@ function isAssignUsersCommand(scope, command) {
 function isTableCreateCommand(scope, command) {
     return scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'create';
 }
+function isEntityRecordImportCommand(scope, command) {
+    return scope === 'user' && command.commandPath[0] === 'row' && (command.commandPath[1] === 'import-excel' || command.commandPath[1] === 'import-csv');
+}
 function isTableSchemaCommand(scope, command) {
     return scope === 'admin' && command.commandPath[0] === 'table' && (command.commandPath[1] === 'create' || command.commandPath[1] === 'update-schema');
 }
@@ -510,6 +571,26 @@ function isAccessRuleUpdateCommand(scope, command) {
     return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update';
 }
 function buildAccessRuleShapeHint(userId = 2188889901) {
+    return buildHiddenFieldAccessRuleBody(userId);
+}
+function buildFullAccessRuleBody(userId = 2188889977) {
+    return {
+        name: 'Admin full access',
+        enabled: true,
+        type: 'form',
+        options: {
+            user_scope: [{ type: 'user', id: userId }],
+            policy: {
+                key: 'custom',
+                actions: ['view', 'add', 'edit', 'delete'],
+                all_fields_read: true,
+                all_fields_write: true,
+            },
+            list_options: {},
+        },
+    };
+}
+function buildHiddenFieldAccessRuleBody(userId = 2188889901) {
     return {
         name: 'Sales read write',
         enabled: true,
@@ -527,6 +608,12 @@ function buildAccessRuleShapeHint(userId = 2188889901) {
         },
     };
 }
+function buildAccessRuleCreateToolCall(body) {
+    return {
+        command: 'access-rule create',
+        args: ['--app-id', '<app_id>', '--table-id', '<table_id>', '--body-json', JSON.stringify(body)],
+    };
+}
 function buildAssignUsersValidationDetails(scope, command, requestType, path, message, env = process.env) {
     return {
         operation: `${scope}.${command.module}.${command.functionName}`,
@@ -601,7 +688,7 @@ function buildBodyGuidance(requestType) {
                         depends: [],
                         key: 'description',
                         code_index: false,
-                        options: { placeholder: '', html: false, size: 'default', lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
+                        options: { placeholder: '', html: false, size: 6, lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
                         transfers: null,
                         children: null,
                     },
@@ -664,7 +751,15 @@ function buildBodyGuidance(requestType) {
         };
     }
     if (requestType === 'AppIngressCreateReqVO' || requestType === 'AppIngressUpdateReqVO') {
+        const retryToolCalls = [
+            buildAccessRuleCreateToolCall(buildFullAccessRuleBody()),
+            buildAccessRuleCreateToolCall(buildHiddenFieldAccessRuleBody()),
+        ];
         return {
+            retryToolCalls,
+            suggestions: [
+                'next arcubase-admin-cli input: retryToolCalls[0] for full access or retryToolCalls[1] for hidden-field access',
+            ],
             shapeHint: buildAccessRuleShapeHint(),
             commonMistakes: [
                 'use options.policy, not top-level permissions',
@@ -703,15 +798,21 @@ function buildBodyGuidance(requestType) {
             shapeHint: {
                 limit: 20,
                 offset: 0,
-                search: { text_search: 'SO-1001' },
+                search: { q: 'SO-1001' },
+                sorts: [{ column: ':1001', order: 'asc' }],
             },
             commonMistakes: [
                 'limit, offset, search, sorts, and view_mode belong inside --body-json',
                 'do not pass --limit or --offset flags',
+                'do not use search.conditions, search.condition, search.field_filters, filter, filters, where, or order',
+                'search only accepts string route-query keys such as q, tab, and filter_:1002',
+                'sorts belongs at top level and uses column values like ":1001"; do not use order/orderBy',
                 'do not add access policy fields; the CLI resolves access policy internally',
             ],
             suggestions: [
                 'retry with: arcubase row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0}\'',
+                'retry text search with: arcubase row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0,"search":{"q":"SO-1001"}}\'',
+                'retry field filter with: arcubase row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0,"search":{"filter_:1002":"%7B%22is%22%3A%22member_1%22%7D"}}\'',
             ],
         };
     }
@@ -938,6 +1039,71 @@ function unwrapData(value) {
     }
     return current;
 }
+function numericFieldKeys(fields) {
+    if (!isRecord(fields))
+        return [];
+    return Object.keys(fields).filter((key) => /^\d+$/.test(key)).sort((left, right) => Number(left) - Number(right));
+}
+function permitFieldId(permit) {
+    if (!isRecord(permit) || typeof permit.key !== 'string')
+        return undefined;
+    const match = /^:(\d+)$/.exec(permit.key);
+    return match?.[1];
+}
+function rowFieldPermits(value) {
+    const data = unwrapData(value);
+    const fieldPermits = isRecord(data) && isRecord(data.fieldPermits) ? data.fieldPermits : undefined;
+    return fieldPermits && Array.isArray(fieldPermits.fields)
+        ? fieldPermits.fields.filter((item) => isRecord(item))
+        : [];
+}
+function buildRowValueEvidence(command, responseBody) {
+    if (command.scope !== 'user' || command.commandPath[0] !== 'row')
+        return undefined;
+    const action = command.commandPath[1];
+    const data = unwrapData(responseBody);
+    const rules = [
+        'current row values come only from row query fields or row get record.fields',
+        'table schema fields[].value and default_value_mode are schema defaults, not returned row values',
+        'a field id absent from returned row fields has no row-value evidence',
+        'read visibility status is fieldPermits read:false; FIELD_PERMISSION_REQUIRED is only a write preflight error',
+    ];
+    if (action === 'get') {
+        const record = isRecord(data) && isRecord(data.record) ? data.record : undefined;
+        const returnedFieldIds = numericFieldKeys(record?.fields);
+        const permits = rowFieldPermits(responseBody);
+        const permitFieldIds = permits.map(permitFieldId).filter((id) => Boolean(id));
+        const deniedReadFieldIds = permits
+            .filter((permit) => permit.read === false)
+            .map(permitFieldId)
+            .filter((id) => Boolean(id))
+            .sort((left, right) => Number(left) - Number(right));
+        const notReturnedFieldIds = permitFieldIds
+            .filter((id) => !returnedFieldIds.includes(id))
+            .sort((left, right) => Number(left) - Number(right));
+        return {
+            source: 'row get record.fields',
+            returnedFieldIds,
+            notReturnedFieldIds,
+            deniedReadFieldIds,
+            absentFieldMeaning: 'not returned to current user; no row-value evidence',
+            rules,
+        };
+    }
+    if (action === 'query') {
+        const items = isRecord(data) && Array.isArray(data.items) ? data.items : [];
+        return {
+            source: 'row query items[].fields',
+            rows: items.filter((item) => isRecord(item)).map((item) => ({
+                rowId: item.id,
+                returnedFieldIds: numericFieldKeys(item.fields),
+            })),
+            absentFieldMeaning: 'not returned to current user; no row-value evidence',
+            rules,
+        };
+    }
+    return undefined;
+}
 function requiredRowAction(command, flags) {
     if (command.commandPath[0] !== 'row')
         return undefined;
@@ -1155,6 +1321,235 @@ async function requestJSON(runtimeEnv, method, endpoint, body, fetchImpl) {
     }
     return { status: response.status, data: parsedResponse };
 }
+function requiredStringFlag(flags, flag) {
+    const value = flagValue(flags, flag);
+    if (!value) {
+        throw new CLIError('MISSING_PATH_FLAG', `missing required flag --${flag}`, 2);
+    }
+    return value;
+}
+function validateAppBundleImportURL(rawURL) {
+    const value = rawURL.trim();
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new CLIError('INVALID_IMPORT_URL', '--url must be a public http/https app bundle zip URL', 2, {
+            hint: 'retry with --url https://.../app-bundles/...zip',
+        });
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new CLIError('INVALID_IMPORT_URL', '--url must be a public http/https app bundle zip URL', 2, {
+            hint: 'local files and upload ids are not supported; provide a public app bundle URL',
+        });
+    }
+    return value;
+}
+function watchIntervalMs(env) {
+    const raw = env.ARCUBASE_IMPORT_TASK_WATCH_INTERVAL_MS;
+    const parsed = raw ? Number(raw) : 2000;
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 2000;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function executeCreateAppFromBundleURL(runtimeEnv, flags, fetchImpl) {
+    const url = validateAppBundleImportURL(requiredStringFlag(flags, 'url'));
+    const name = flagValue(flags, 'name');
+    const result = await requestJSON(runtimeEnv, 'POST', '/api/apps/import-task', {
+        url,
+        ...(name ? { name } : {}),
+    }, fetchImpl);
+    const taskID = extractImportTaskID(result.data);
+    return {
+        kind: 'result',
+        commandPath: ['app', 'create-from-bundle-url'],
+        status: result.status,
+        data: result.data,
+        nextAction: {
+            command: 'app watch-import-task',
+            args: ['--task-id', taskID, '--ttl-seconds', '300'],
+            hint: 'run this command until the task returns status=finished and app_id > 0; task_id alone is not success',
+        },
+    };
+}
+async function executeWatchAppBundleImportTask(runtimeEnv, flags, fetchImpl) {
+    const taskID = requiredStringFlag(flags, 'task-id');
+    const ttlRaw = requiredStringFlag(flags, 'ttl-seconds');
+    const ttlSeconds = Number(ttlRaw);
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+        throw new CLIError('INVALID_FLAG_VALUE', `expected positive ttl seconds, got ${ttlRaw}`, 2);
+    }
+    const deadline = Date.now() + ttlSeconds * 1000;
+    const endpoint = `/api/apps/import-task/${encodeURIComponent(taskID)}`;
+    let latest = null;
+    while (Date.now() <= deadline) {
+        const result = await requestJSON(runtimeEnv, 'GET', endpoint, undefined, fetchImpl);
+        latest = result.data;
+        const payload = isRecord(latest) && isRecord(latest.data) ? latest.data : latest;
+        const status = isRecord(payload) ? payload.status : undefined;
+        if (status === 'finished') {
+            const appID = isRecord(payload) ? Number(payload.app_id) : 0;
+            if (!Number.isFinite(appID) || appID <= 0) {
+                throw new CLIError('IMPORT_TASK_APP_ID_MISSING', 'app bundle import task finished without app_id', 1, {
+                    endpoint,
+                    responseBody: stringifyUpstreamBody(latest),
+                    hint: 'treat this as an import failure; do not claim the app was imported',
+                });
+            }
+            return {
+                kind: 'result',
+                commandPath: ['app', 'watch-import-task'],
+                status: result.status,
+                data: latest,
+            };
+        }
+        if (status === 'failed') {
+            throw new CLIError('IMPORT_TASK_FAILED', isRecord(payload) && typeof payload.error === 'string' ? payload.error : 'app bundle import task failed', 1, {
+                endpoint,
+                responseBody: stringifyUpstreamBody(latest),
+            });
+        }
+        await sleep(Math.min(watchIntervalMs(runtimeEnv), Math.max(0, deadline - Date.now())));
+    }
+    throw new CLIError('IMPORT_TASK_WATCH_TIMEOUT', `import task did not finish within ${ttlSeconds} seconds`, 1, {
+        endpoint,
+        responseBody: stringifyUpstreamBody(latest),
+    });
+}
+function readJSONFile(filePath, label) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        throw new CLIError('INVALID_JSON_FILE', `${label} file is invalid: ${filePath}`, 2);
+    }
+}
+function assertLocalImportFile(filePath, format) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        throw new CLIError('LOCAL_FILE_NOT_FOUND', `local file not found: ${filePath}`, 2);
+    }
+    if (!stat.isFile()) {
+        throw new CLIError('LOCAL_FILE_INVALID', `path is not a regular file: ${filePath}`, 2);
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    if (format === 'csv' && ext !== '.csv') {
+        throw new CLIError('LOCAL_FILE_INVALID', 'row import-csv requires a .csv file', 2);
+    }
+    if (format === 'excel' && !['.xlsx', '.xlsm', '.xls'].includes(ext)) {
+        throw new CLIError('LOCAL_FILE_INVALID', 'row import-excel requires an Excel file', 2);
+    }
+}
+function csvHeadersFromLocalFile(filePath, delimiter = ',') {
+    const firstLine = fs.readFileSync(filePath, 'utf8').split(/\r?\n/, 1)[0] ?? '';
+    const headers = [];
+    let current = '';
+    let quoted = false;
+    for (let i = 0; i < firstLine.length; i += 1) {
+        const char = firstLine[i];
+        if (char === '"') {
+            if (quoted && firstLine[i + 1] === '"') {
+                current += '"';
+                i += 1;
+            }
+            else {
+                quoted = !quoted;
+            }
+        }
+        else if (char === delimiter && !quoted) {
+            headers.push(current);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    headers.push(current);
+    return headers;
+}
+async function postEntityImportAction(runtimeEnv, appId, entityId, body, fetchImpl) {
+    const endpoint = `/api/entity/${encodeURIComponent(appId)}/${encodeURIComponent(entityId)}/import`;
+    const response = await requestJSON(runtimeEnv, 'POST', endpoint, body, fetchImpl);
+    return response.data;
+}
+function extractImportTaskID(value) {
+    const candidates = [
+        value,
+        isRecord(value) ? value.data : undefined,
+    ];
+    for (const candidate of candidates) {
+        if (isRecord(candidate) && typeof candidate.taskId === 'string')
+            return candidate.taskId;
+        if (isRecord(candidate) && typeof candidate.task_id === 'string')
+            return candidate.task_id;
+        if (typeof candidate === 'string')
+            return candidate;
+    }
+    throw new CLIError('UPSTREAM_RESPONSE_INVALID', 'import response did not include taskId', 1);
+}
+function extractUploadToken(value) {
+    const payload = isRecord(value) && isRecord(value.data) ? value.data : value;
+    if (isRecord(payload) && isRecord(payload.token))
+        return payload.token;
+    throw new CLIError('UPSTREAM_RESPONSE_INVALID', 'import init-token response did not include upload token', 1);
+}
+function compileEntityImportConfig(format, mapping, filePath) {
+    if (format === 'excel') {
+        return compileExcelImportMapping(mapping);
+    }
+    const delimiter = isRecord(mapping) && typeof mapping.delimiter === 'string' ? mapping.delimiter : ',';
+    return compileCSVImportMapping(mapping, csvHeadersFromLocalFile(filePath, delimiter));
+}
+async function executeEntityRecordImport(command, runtimeEnv, flags, fetchImpl) {
+    const appId = requiredStringFlag(flags, 'app-id');
+    const entityId = requiredStringFlag(flags, 'table-id');
+    const filePath = requiredStringFlag(flags, 'file');
+    const mappingPath = requiredStringFlag(flags, 'mapping-file');
+    const ttlRaw = flagValue(flags, 'ttl-seconds') ?? '300';
+    const ttlSeconds = Number(ttlRaw);
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+        throw new CLIError('INVALID_FLAG_VALUE', `expected positive ttl seconds, got ${ttlRaw}`, 2);
+    }
+    const format = command.commandPath[1] === 'import-csv' ? 'csv' : 'excel';
+    assertLocalImportFile(filePath, format);
+    const mapping = readJSONFile(mappingPath, 'mapping');
+    const config = compileEntityImportConfig(format, mapping, filePath);
+    const init = await postEntityImportAction(runtimeEnv, appId, entityId, { _import_action: 'init-token' }, fetchImpl);
+    const taskId = extractImportTaskID(init);
+    const token = extractUploadToken(init);
+    await uploadLocalFileWithToken(filePath, token, fetchImpl);
+    await postEntityImportAction(runtimeEnv, appId, entityId, { _import_action: 'uploaded', task_id: taskId }, fetchImpl);
+    await postEntityImportAction(runtimeEnv, appId, entityId, { _import_action: 'do-process', task_id: taskId, config }, fetchImpl);
+    const deadline = Date.now() + ttlSeconds * 1000;
+    let latest = null;
+    while (Date.now() <= deadline) {
+        latest = await postEntityImportAction(runtimeEnv, appId, entityId, { _import_action: 'get-state', task_id: taskId }, fetchImpl);
+        const payload = isRecord(latest) && isRecord(latest.data) ? latest.data : latest;
+        const status = isRecord(payload) ? payload.status : undefined;
+        if (status === 'finished') {
+            return {
+                kind: 'result',
+                commandPath: command.commandPath,
+                status: 200,
+                data: latest,
+            };
+        }
+        if (status === 'failed') {
+            throw new CLIError('IMPORT_TASK_FAILED', 'entity record import task failed', 1, {
+                responseBody: stringifyUpstreamBody(latest),
+            });
+        }
+        await sleep(Math.min(watchIntervalMs(runtimeEnv), Math.max(0, deadline - Date.now())));
+    }
+    throw new CLIError('IMPORT_TASK_WATCH_TIMEOUT', `import task did not finish within ${ttlSeconds} seconds`, 1, {
+        responseBody: stringifyUpstreamBody(latest),
+    });
+}
 function extractCreatedTableID(value) {
     const candidates = [
         value,
@@ -1262,6 +1657,15 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     }
     validateKnownFlags(command, parsed.flags, envInput);
     const runtimeEnv = env ?? loadRuntimeEnv(scope);
+    if (scope === 'admin' && command.commandPath[0] === 'app' && command.commandPath[1] === 'create-from-bundle-url') {
+        return executeCreateAppFromBundleURL(runtimeEnv, parsed.flags, fetchImpl);
+    }
+    if (scope === 'admin' && command.commandPath[0] === 'app' && command.commandPath[1] === 'watch-import-task') {
+        return executeWatchAppBundleImportTask(runtimeEnv, parsed.flags, fetchImpl);
+    }
+    if (isEntityRecordImportCommand(scope, command)) {
+        return executeEntityRecordImport(command, runtimeEnv, parsed.flags, fetchImpl);
+    }
     const endpoint = resolveEndpoint(command, parsed.flags);
     const scalarQuery = buildScalarQuery(command, parsed.flags);
     const fileQuery = loadQueryFromFlags(parsed.flags);
@@ -1272,7 +1676,7 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     }
     catch (error) {
         if (error instanceof CLIError && error.code === 'INVALID_BODY_JSON' && command.requestType) {
-            throw new CLIError('INVALID_BODY_JSON', `body json is invalid for ${scope}.${command.commandPath.join(' ')}; fix JSON syntax, then use the canonical ${command.requestType} shape from docs/types`, 2, buildBodyValidationDetails(scope, command, command.requestType, [{ path: 'body', message: 'invalid JSON syntax' }], runtimeEnv));
+            throw new CLIError('INVALID_BODY_JSON', `body json is invalid for ${scope}.${command.commandPath.join(' ')}; retry with retryToolCalls[0] or retryToolCalls[1] when present`, 2, buildBodyValidationDetails(scope, command, command.requestType, [{ path: 'body', message: 'invalid JSON syntax' }], runtimeEnv));
         }
         throw error;
     }
@@ -1381,10 +1785,12 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
                 : {}),
         });
     }
+    const rowValueEvidence = buildRowValueEvidence(command, parsedResponse);
     return {
         kind: 'result',
         commandPath: command.commandPath,
         status: response.status,
         data: parsedResponse,
+        ...(rowValueEvidence ? { rowValueEvidence } : {}),
     };
 }

package/dist/runtime/local_upload.d.ts

@@ -0,0 +1,10 @@
+type UploadTokenPayload = {
+    mode?: string;
+    token_data?: unknown;
+    tokenData?: unknown;
+};
+export declare function uploadLocalFileWithToken(filePath: string, token: UploadTokenPayload, fetchImpl?: typeof fetch): Promise<{
+    objectKey: string;
+}>;
+export {};
+//# sourceMappingURL=local_upload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local_upload.d.ts","sourceRoot":"","sources":["../../src/runtime/local_upload.ts"],"names":[],"mappings":"AAIA,KAAK,kBAAkB,GAAG;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AA8CD,wBAAsB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA6B3J"}

package/dist/runtime/local_upload.js

@@ -0,0 +1,73 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CLIError } from './errors.js';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+async function ensureLocalFile(filePath) {
+    let stat;
+    try {
+        stat = await fs.stat(filePath);
+    }
+    catch {
+        throw new CLIError('LOCAL_FILE_NOT_FOUND', `local file not found: ${filePath}`, 2);
+    }
+    if (!stat.isFile()) {
+        throw new CLIError('LOCAL_FILE_INVALID', `path is not a regular file: ${filePath}`, 2);
+    }
+}
+function tokenData(token) {
+    const data = token.token_data ?? token.tokenData;
+    if (!isRecord(data)) {
+        throw new CLIError('UPLOAD_TOKEN_UNSUPPORTED', 'upload token data is not an object', 1);
+    }
+    return data;
+}
+function appendAliyunCompatFields(form, data, objectKey) {
+    form.set('key', objectKey);
+    form.set('policy', String(data.policy));
+    form.set('OSSAccessKeyId', String(data.accessid));
+    form.set('Signature', String(data.signature));
+    form.set('success_action_status', '200');
+    if (typeof data.callback === 'string' && data.callback !== '') {
+        form.set('callback', data.callback);
+    }
+}
+function appendS3PostPolicyFields(form, data, objectKey) {
+    form.set('key', objectKey);
+    form.set('Policy', String(data.policy));
+    form.set('X-Amz-Algorithm', String(data.x_amz_algorithm));
+    form.set('X-Amz-Credential', String(data.x_amz_credential));
+    form.set('X-Amz-Date', String(data.x_amz_date));
+    form.set('X-Amz-Signature', String(data.x_amz_signature));
+}
+export async function uploadLocalFileWithToken(filePath, token, fetchImpl = fetch) {
+    await ensureLocalFile(filePath);
+    const data = tokenData(token);
+    if (typeof data.host !== 'string' || data.host === '' || typeof data.dir !== 'string') {
+        throw new CLIError('UPLOAD_TOKEN_UNSUPPORTED', `unsupported upload token mode: ${token.mode ?? 'unknown'}`, 1);
+    }
+    const fileName = path.basename(filePath);
+    const objectKey = `${data.dir}${fileName}`;
+    const form = new FormData();
+    if (typeof data.x_amz_signature === 'string') {
+        appendS3PostPolicyFields(form, data, objectKey);
+    }
+    else if (typeof data.accessid === 'string' && typeof data.signature === 'string') {
+        appendAliyunCompatFields(form, data, objectKey);
+    }
+    else {
+        throw new CLIError('UPLOAD_TOKEN_UNSUPPORTED', `unsupported upload token mode: ${token.mode ?? 'unknown'}`, 1);
+    }
+    const raw = await fs.readFile(filePath);
+    form.set('file', new Blob([raw]), fileName);
+    const response = await fetchImpl(data.host, { method: 'POST', body: form });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new CLIError('LOCAL_UPLOAD_FAILED', body || `upload failed with HTTP ${response.status}`, 1, {
+            status: response.status,
+            responseBody: body,
+        });
+    }
+    return { objectKey };
+}