firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/configuration.js

@@ -0,0 +1,369 @@
+import { APP_ORIGIN } from './http.js';
+import { createInterface } from 'node:readline/promises';
+import { api, openBrowser } from './auth.js';
+import { CliError } from './http.js';
+import { selectMany, selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace, selectedWorld } from './world-access.js';
+import { inputSchema, readMetadata, remember, requestAction, retained, validateBody } from './configuration-intents.js';
+import { serviceReceipts, validateReceiptOptions } from './service-receipts.js';
+import { packageReads } from './tool-package-reads.js';
+const VARIABLE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+export const interactive = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+export const auth = (context, options) => ({ actor: context.owner, workspace: context.workspace, signal: options.signal });
+export function query(options) {
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use a positive page and a search up to 200 characters.', 2);
+    }
+    return `page=${options.page ?? '1'}&q=${encodeURIComponent(options.search ?? '')}`;
+}
+export async function line(title, maximum, signal, initial = '', preserveSpace = false) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+    try {
+        const entered = await prompt.question(`${title}${initial ? ` [${initial}]` : ''}: `, { signal });
+        const value = (preserveSpace ? entered : entered.trim()) || initial;
+        if (value.length > maximum || /[\u0000-\u001f\u007f]/.test(value))
+            throw new CliError('configuration_input_invalid', 'Use configuration text within this field capacity. No request was saved.', 2);
+        return value;
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function choosePaged(title, path, context, options, describe, includeNew = false, read) {
+    let page = 1, search = options.search ?? '';
+    while (true) {
+        const data = read ? await read(page, search)
+            : await api(`${path}${path.includes('?') ? '&' : '?'}page=${page}&q=${encodeURIComponent(search)}`, auth(context, options));
+        const choices = data.results.map(row => ({ value: row.id, ...describe(row) }));
+        if (includeNew)
+            choices.unshift({ value: 'new', label: 'Add a variable' });
+        if (page > 1)
+            choices.push({ value: 'previous', label: 'Previous page' });
+        if (data.next)
+            choices.push({ value: 'next', label: 'Next page' });
+        choices.push({ value: 'search', label: 'Search entries' }, { value: 'cancel', label: 'Cancel' });
+        const choice = await selectOne(title, choices, options.signal);
+        if (choice === 'new')
+            return null;
+        if (choice === 'next') {
+            page += 1;
+            continue;
+        }
+        if (choice === 'previous') {
+            page -= 1;
+            continue;
+        }
+        if (choice === 'search') {
+            search = await line('Find an entry (blank for all)', 200, options.signal);
+            page = 1;
+            continue;
+        }
+        if (choice === 'cancel')
+            throw new CliError('canceled', 'No selection was submitted.', 130);
+        const row = data.results.find(item => item.id === choice);
+        if (!row)
+            throw new CliError('selection_changed', 'The selected entry changed. Reopen this setup.', 2);
+        return row;
+    }
+}
+export async function approval(options, title) {
+    const allowed = options.approve || interactive(options) && await selectOne(title, [{ value: false, label: 'Cancel' }, { value: true, label: 'Save reviewed settings' }], options.signal);
+    if (!allowed)
+        throw new CliError('configuration_consent_required', 'Nothing was submitted. Review the metadata and use --approve-configuration for automation.', 2);
+}
+function edit(row) {
+    return { name: row.name, phase: row.phase, source: row.source, vault_entry_id: row.vault_entry_id,
+        binding_key: row.binding_key, dependency_key: row.dependency_key };
+}
+async function mappingBody(context, options, output) {
+    const selected = await choosePaged('Configuration variable', context.prefix + '/configuration?editable=true', context, options, row => ({ label: row.name, detail: `${row.phase} · ${row.connection_role === 'endpoint' ? 'Supplied by connection' : row.source}${row.source === 'vault' ? row.vault_reference ? ` · ${row.vault_reference.name} · Version ${row.vault_reference.version} · ${row.vault_reference.purpose || 'No purpose recorded'} · ${row.vault_reference.state}` : ' · Saved reference unavailable' : ''}` }), true);
+    const current = await api(`${context.prefix}/configuration?page=1${selected ? '&mapping_id=' + identifier(selected.id) : ''}`, auth(context, options));
+    if (!Number.isSafeInteger(current.configuration_revision))
+        throw new CliError('configuration_conflict', 'Configuration revision is unavailable.', 2);
+    if (selected) {
+        const refreshed = current.results.find(one => one.id === selected.id);
+        if (!refreshed || ['id', 'name', 'phase', 'required', 'source', 'vault_entry_id', 'binding_key', 'dependency_key', 'has_default', 'connection_role']
+            .some(key => refreshed[key] !== selected[key]))
+            throw new CliError('configuration_conflict', 'The chosen mapping changed. Review its current settings before editing.', 2);
+    }
+    let row;
+    if (selected) {
+        if (selected.connection_role === 'endpoint') {
+            throw new CliError('connection_endpoint_owned', 'The connection supplies this endpoint. Use firedrill connections save to change its address or variable.', 2);
+        }
+        row = edit(selected);
+    }
+    else {
+        const name = await line('Variable name', 128, options.signal);
+        if (!VARIABLE.test(name))
+            throw new CliError('configuration_input_invalid', 'Use a valid variable name.', 2);
+        const phase = await selectOne('Phase', [{ value: 'runtime', label: 'Runtime' }, { value: 'build', label: 'Build' }, { value: 'both', label: 'Build and runtime' }], options.signal);
+        const existing = await api(`${context.prefix}/configuration?name=${encodeURIComponent(name)}`, auth(context, options));
+        if (existing.configuration_revision !== current.configuration_revision || existing.results.some(one => one.phase === phase || one.phase === 'both' || phase === 'both')) {
+            throw new CliError('configuration_conflict', 'An overlapping variable already exists or settings changed. Choose the existing mapping to edit it.', 2);
+        }
+        row = { name, phase, source: 'unset', vault_entry_id: null, binding_key: '', dependency_key: '' };
+    }
+    const credential = selected?.connection_role === 'credential';
+    const choices = [{ value: 'vault', label: 'Saved value' }, { value: 'unset', label: 'Not set' },
+        ...(selected?.source === 'local' ? [{ value: 'local', label: 'Keep the current device-only value' }] : []),
+        ...(!credential && row.phase === 'runtime' ? [{ value: 'world', label: 'Simulated world endpoint' }] : []),
+        ...(selected?.has_default && !credential ? [{ value: 'default', label: 'Detected default' }] : []),
+        ...(selected && !selected.required && !selected.connection_role ? [{ value: 'remove', label: 'Remove this variable mapping' }] : [])];
+    row.source = await selectOne('Value source', choices, options.signal);
+    if (row.source === 'vault') {
+        const entry = await choosePaged('Saved value', `/api/workspaces/${context.workspace}/vault?phase=${row.phase}${credential ? '&secret=true' : ''}`, context, options, item => ({ label: item.name, detail: item.secret ? 'Secret' : item.empty ? 'Empty string' : 'Configuration value' }));
+        if (!entry || entry.state !== 'active')
+            throw new CliError('credential_unavailable', 'Choose an active saved value.', 2);
+        row.vault_entry_id = entry.id;
+        row.binding_key = '';
+        if (!credential) {
+            const use = await selectOne('Use this value for', [{ value: 'agent', label: 'Agent configuration' },
+                { value: 'dependency', label: 'A selected dependency' }], options.signal);
+            if (use === 'agent')
+                row.dependency_key = '';
+            else {
+                const dependency = await choosePaged('Dependency', `${context.prefix}/dependencies${entry.secret ? '?mode=real' : ''}`, context, options, item => ({ label: item.name, detail: item.mode }));
+                if (!dependency || dependency.mode === 'unselected')
+                    throw new CliError('dependency_choice_required', 'Select how this dependency runs before mapping a value.', 2);
+                row.dependency_key = dependency.key;
+            }
+        }
+    }
+    else if (row.source === 'world') {
+        const dependency = await choosePaged('Simulated dependency', `${context.prefix}/dependencies?mode=simulated`, context, options, item => ({ label: item.name }));
+        if (!dependency)
+            throw new CliError('dependency_choice_required', 'Choose a simulated dependency.', 2);
+        if (row.phase !== 'runtime')
+            throw new CliError('world_binding_phase_invalid', 'World endpoints are allocated at Runtime. Add a Runtime mapping instead.', 2);
+        row.binding_key = dependency.key;
+        row.dependency_key = dependency.key;
+        row.vault_entry_id = null;
+    }
+    else if (row.source !== 'local') {
+        row.vault_entry_id = null;
+        row.binding_key = '';
+    }
+    output('configuration_review', { variable: row.name, phase: row.phase, source: row.source, dependency_key: row.dependency_key }, `${row.name} · ${row.phase} · ${row.source}\nOnly this mapping is changed. No agent is run.`);
+    return { revision: current.configuration_revision, mappings: [row] };
+}
+async function operationSelection(context, dependency, options) {
+    const selected = new Set(dependency.policy.operation_names ?? []);
+    let page = 1;
+    while (true) {
+        const data = await api(`${context.prefix}/items/${dependency.id}/operations?page=${page}&q=${encodeURIComponent(options.search ?? '')}`, auth(context, options));
+        if (!data.results.length)
+            throw new CliError('dependency_operations_missing', 'This selection has no declared operations. Review the service contract.', 2);
+        const chosen = await selectMany(`Allowed operations · page ${page}`, data.results.map(row => ({ value: row.name, label: row.name,
+            detail: row.effect === 'unknown' ? 'Effects not classified' : row.effect })), options.signal, [...selected]);
+        for (const row of data.results)
+            selected.delete(row.name);
+        for (const name of chosen)
+            selected.add(name);
+        const actions = [{ value: 'done', label: `Continue with ${selected.size} selected operations` },
+            ...(data.next ? [{ value: 'next', label: 'Next page' }] : []), ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : [])];
+        const action = await selectOne('Operation selection', actions, options.signal);
+        if (action === 'next') {
+            page += 1;
+            continue;
+        }
+        if (action === 'previous') {
+            page -= 1;
+            continue;
+        }
+        if (!selected.size)
+            throw new CliError('dependency_operations_missing', 'Choose at least one operation.', 2);
+        return [...selected];
+    }
+}
+async function bindingInput(options, prior) {
+    if (prior && await selectOne('Service address and credential header mappings', [{ value: true, label: 'Keep the reviewed mappings' },
+        { value: false, label: 'Enter different mappings' }], options.signal))
+        return prior;
+    const base_url = await line('HTTPS service address (no credentials or query)', 2048, options.signal);
+    const endpoint_variable = await line('Original endpoint variable', 128, options.signal);
+    const authentication = [];
+    while (authentication.length < 16) {
+        const add = await selectOne('Credential headers', [{ value: false, label: 'No more credential headers' },
+            { value: true, label: 'Add a credential header mapping' }], options.signal);
+        if (!add)
+            break;
+        const variable = await line('Credential variable name, not its value', 128, options.signal);
+        const header = await line('HTTP header name', 64, options.signal);
+        const prefix = await line('Prefix including any trailing space (optional)', 33, options.signal, '', true);
+        authentication.push({ variable, header, prefix });
+    }
+    return { base_url, endpoint_variable, authentication };
+}
+async function dependencyBody(context, detail, options, output) {
+    const dependency = detail.dependency;
+    const mode = await selectOne('Connection', [{ value: 'simulated', label: 'Simulated service' },
+        { value: 'real', label: 'Real account' }, { value: 'unselected', label: 'Not selected' }], options.signal);
+    const body = { mode, configuration_revision: detail.configuration_revision, service_revision: dependency.service_revision };
+    if (mode === 'simulated') {
+        const source = await selectOne('Service implementation', [{ value: 'generated', label: 'Catalog first', detail: 'Review compatible packages before authoring missing supported behavior.' },
+            { value: 'catalog', label: 'Saved tool package', detail: 'Reuse an exact version. Runtime validation checks the native layout and supported state.' }], options.signal);
+        if (source === 'catalog') {
+            const prefix = `/api/workspaces/${context.workspace}/tools`;
+            const packages = packageReads(context, options.signal);
+            const picked = await choosePaged('Saved tool package', `${prefix}/catalog?state=inspected`, context, options, row => ({ label: row.name, detail: row.version }), false, packages.versions);
+            if (!picked)
+                throw new CliError('canceled', 'No service connection was saved.', 130);
+            const path = `${prefix}/implementations/${identifier(picked.id)}`;
+            const version = await packages.version(picked.id);
+            if (version.state !== 'inspected' || !Number.isSafeInteger(version.service_count) || (version.service_count ?? 0) < 1) {
+                throw new CliError('catalog_binding_revoked', 'This package is unavailable. No connection was saved.');
+            }
+            let service;
+            if (version.service_count === 1) {
+                const page = await packages.services(version);
+                if (page.implementation_id !== version.id || page.contract_digest !== version.contract_digest || page.count !== 1 || page.results.length !== 1) {
+                    throw new CliError('catalog_binding_revoked', 'This package changed. Reopen the connection setup. No connection was saved.');
+                }
+                service = page.results[0] ?? null;
+            }
+            else {
+                service = await choosePaged('Service', `${path}/services`, context, options, row => ({ label: row.name, detail: `${row.operation_count} operations` }), false, (page, search) => packages.services(version, page, search));
+            }
+            if (!service || !/^[a-z][a-z0-9_-]{0,79}$/.test(service.key))
+                throw new CliError('catalog_binding_invalid', 'Choose an available service. No connection was saved.');
+            const selected = await packages.service(version, service.key);
+            if (selected.implementation_id !== version.id || selected.contract_digest !== version.contract_digest || selected.key !== service.key) {
+                throw new CliError('catalog_binding_revoked', 'This package changed. Reopen the connection setup. No connection was saved.');
+            }
+            body.catalog = { implementation_id: version.id, package_service_key: selected.key };
+            output('tool_package_review', { name: version.name, version: version.version, implementation_id: version.id, service_key: selected.key, service_name: selected.name }, `Tool package: ${version.name} ${version.version}\nService: ${selected.name}\nEach independent drill uses private state. This selection is not runtime validation.`);
+        }
+    }
+    if (mode === 'real') {
+        const all = await selectOne('Allowed operations', [{ value: false, label: 'Select individual operations' },
+            { value: true, label: `All ${dependency.operation_count} operations in this revision` }], options.signal);
+        body.allow_all_operations = all;
+        body.operation_names = all ? [] : await operationSelection(context, dependency, options);
+        const hosts = await line('Exact allowed hostnames, separated by commas', 4096, options.signal, (dependency.policy.allowed_hosts ?? []).join(', '));
+        body.allowed_hosts = hosts.split(',').map(one => one.trim()).filter(Boolean);
+        body.http_binding = await bindingInput(options, dependency.policy.http_binding);
+        body.allow_write_effects = await selectOne('Real-account effects', [{ value: false, label: 'Read-only declared operations' },
+            { value: true, label: 'Also allow selected writes and unclassified effects' }], options.signal);
+        body.acknowledge_external_effects = await selectOne('Authorize these operations on the real account? Resetting a world cannot undo them.', [{ value: false, label: 'Cancel' }, { value: true, label: 'Authorize the reviewed operations' }], options.signal);
+        if (!body.acknowledge_external_effects)
+            throw new CliError('configuration_consent_required', 'No real connection was saved.', 2);
+    }
+    output('configuration_review', { service: dependency.name, mode, service_revision: dependency.service_revision }, `${dependency.name} · ${mode} · Revision ${dependency.service_revision}\nSaving changes revokes prior credential grants. Review and save Configuration before executing.`);
+    return body;
+}
+async function recovery(action, options, output) {
+    if (!options.request || options.world || options.file || options.page || options.search)
+        throw new CliError('arguments_invalid', 'Use configuration status|resume|withdraw|forget --request-key <id>, with --workspace if needed.', 2);
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    const intent = await retained(scope, options.request);
+    const context = { ...scope, world: intent.world, prefix: `/api/workspaces/${scope.workspace}/worlds/${intent.world}` };
+    if (action !== 'status' && action !== 'resume')
+        await approval(options, action === 'withdraw'
+            ? 'Withdraw this exact delayed request? An already accepted change will not be undone.'
+            : 'Remove only the private local recovery copy? A delayed or accepted cloud request is not cancelled.');
+    return requestAction(context, intent, action, options.signal, output);
+}
+async function connectionActivity(args, options, output, selected) {
+    if (args.length > 3 || args[2] !== undefined && !['selected', 'all'].includes(args[2]) || options.file || options.request || options.approve)
+        throw new CliError('arguments_invalid', 'Use connections activity [service-id] [selected|all] with paging, search or response filters only.', 2);
+    validateReceiptOptions(options);
+    if (args[1])
+        identifier(args[1]);
+    const context = selected ?? await selectedWorld({ ...options, interactive: interactive(options) });
+    const service = args[1] ?? (interactive(options) ? (await choosePaged('Service history', `${context.prefix}/items?kind=service`, context, { ...options, page: undefined, search: undefined }, row => ({ label: row.name })))?.id : undefined);
+    if (!service)
+        throw new CliError('dependency_required', 'Pass a service ID from this world to inspect its retained activity.', 2);
+    const revisions = args[2] ?? 'selected';
+    await serviceReceipts(`${context.prefix}/items/${identifier(service)}/activity?revisions=${revisions}`, context, options, interactive(options), (data, readable) => output('service_activity', data, readable), `firedrill connections activity ${service} ${revisions} --world ${context.world}`);
+}
+export async function configurationCommand(command, args, options, output) {
+    query(options);
+    let action = args[0] ?? 'list';
+    if (options.status !== undefined && !(command === 'connections' && action === 'activity'))
+        throw new CliError('arguments_invalid', 'Response status filters apply to connections activity.', 2);
+    if (command === 'connections' && action === 'activity')
+        return connectionActivity(args, options, output);
+    if (action === 'schema') {
+        if (args.length !== 1 || options.world || options.workspace || options.file || options.page || options.search || options.request || options.approve) {
+            throw new CliError('arguments_invalid', 'Use configuration schema or connections schema with --json only.', 2);
+        }
+        const schema = inputSchema(command === 'configuration' ? 'mappings' : 'dependency');
+        output('input_schema', schema, JSON.stringify(schema, null, 2));
+        return;
+    }
+    if (command === 'configuration' && ['status', 'resume', 'withdraw', 'forget'].includes(action)) {
+        if (args.length !== 1 || action === 'status' && options.approve)
+            throw new CliError('arguments_invalid', 'Use the exact saved configuration request.', 2);
+        return recovery(action, options, output);
+    }
+    if (!['list', 'show', 'save', 'vault', 'local'].includes(action) || args.length > 2 || command === 'configuration' && args.length > 1
+        || command === 'connections' && ['vault', 'local'].includes(action) || action !== 'save' && (options.file || options.request || options.approve)
+        || ['show', 'save', 'vault'].includes(action) && (options.page || options.search)) {
+        throw new CliError('arguments_invalid', 'Use configuration list|save|vault|local or connections list|show|save [service-id].', 2);
+    }
+    const context = await selectedWorld({ ...options, interactive: interactive(options) });
+    if (action === 'vault') {
+        const url = `${APP_ORIGIN}/vault?workspace=${context.workspace}`;
+        const opened = options.openBrowser && !options.json && await openBrowser(url);
+        output('result', { url, opened }, opened ? 'Opened Vault. Saved credentials are never printed by this command.' : url);
+        return;
+    }
+    if (!args.length && interactive(options))
+        action = await selectOne(command === 'connections' ? 'Connections' : 'Configuration', [{ value: 'list', label: 'View saved settings' }, ...(command === 'connections' ? [{ value: 'activity', label: 'Inspect service history' }] : []),
+            ...(command === 'configuration' ? [{ value: 'local', label: 'Manage values kept on this device' }] : []),
+            { value: 'save', label: 'Change settings' }], options.signal);
+    if (action === 'local') {
+        const { localValuesCommand } = await import('./local-values.js');
+        return localValuesCommand([], { ...options, workspace: context.workspace, world: context.world, expectedOwner: context.owner }, (data, readable) => output('local_value', data, readable));
+    }
+    if (action === 'activity')
+        return connectionActivity(['activity'], options, output, context);
+    if (action === 'list') {
+        if (args.length > 1)
+            throw new CliError('arguments_invalid', 'List does not accept an item ID.', 2);
+        if (command === 'configuration') {
+            const data = await api(`${context.prefix}/configuration?${query(options)}`, auth(context, options));
+            output('result', data, [`Configuration revision ${data.configuration_revision}`, data.results.map(row => `${row.name} · ${row.phase} · ${row.connection_role === 'endpoint' ? 'Supplied by connection' : row.source}${row.source === 'vault' ? row.vault_reference ? ` · ${row.vault_reference.name} · Version ${row.vault_reference.version} · ${row.vault_reference.purpose || 'No purpose recorded'} · ${row.vault_reference.state}` : ' · Saved reference unavailable' : ''}${row.dependency_name ? ' · ' + row.dependency_name : ''}`).join('\n') || 'No configuration variables.',
+                ...(data.next ? [`Next page: --page ${data.page + 1}`] : [])].join('\n'));
+        }
+        else {
+            const data = await api(`${context.prefix}/dependencies?${query(options)}`, auth(context, options));
+            output('result', data, [data.results.map(row => `${row.id}  ${row.name} · ${row.mode} · ${row.operation_count} operations`).join('\n') || 'No discovered dependencies.',
+                ...(data.next ? [`Next page: --page ${data.page + 1}`] : [])].join('\n'));
+        }
+        return;
+    }
+    if (command === 'configuration' && action === 'show')
+        throw new CliError('arguments_invalid', 'Use configuration list to inspect saved mappings.', 2);
+    let service = null, detail;
+    if (command === 'connections') {
+        service = args[1] ? identifier(args[1]) : null;
+        if (!service && interactive(options))
+            service = (await choosePaged('Dependency', context.prefix + '/dependencies', context, options, row => ({ label: row.name, detail: row.mode })))?.id ?? null;
+        if (!service)
+            throw new CliError('dependency_required', 'Choose a service ID from firedrill connections.', 2);
+        detail = await api(`${context.prefix}/dependencies/${service}`, auth(context, options));
+        if (detail.dependency.id !== service)
+            throw new CliError('dependency_changed', 'The selected dependency changed.', 2);
+        if (action === 'show') {
+            output('result', detail, `${detail.dependency.name} · ${detail.dependency.mode}\nService revision ${detail.dependency.service_revision}\nConfiguration revision ${detail.configuration_revision}\n${detail.dependency.operation_count} declared operations`);
+            return;
+        }
+    }
+    const kind = command === 'configuration' ? 'mappings' : 'dependency';
+    let body;
+    if (options.file)
+        body = await readMetadata(options.file);
+    else if (!interactive(options))
+        throw new CliError('configuration_input_required', 'Use --file <metadata.json> and --approve-configuration, or run this command in a terminal.', 2);
+    else
+        body = kind === 'mappings' ? await mappingBody(context, options, output) : await dependencyBody(context, detail, options, output);
+    validateBody(kind, body);
+    if (detail && (body.configuration_revision !== detail.configuration_revision || body.service_revision !== detail.dependency.service_revision)) {
+        throw new CliError('configuration_conflict', 'The file does not match the current connection revisions. Review its saved settings first.', 2);
+    }
+    await approval(options, 'Save these settings and keep a private metadata recovery copy? No agent or external account operation is started.');
+    return remember(context, kind, service, body, options.request, options.signal, output);
+}