@attocash/cli 0.1.0

package/dist/cli/help.js

@@ -0,0 +1,49 @@
+/** Keep nested parser errors attached to the command whose input was invalid. */
+export function configureHelp(program, examples) {
+    let failedCommand = program;
+    function visit(command, prefix = '') {
+        const path = `${prefix} ${command.name()}`.trim();
+        command.exitOverride(error => { failedCommand = command; throw error; });
+        if (examples[path])
+            command.addHelpText('after', `\nExample:\n  ${examples[path]}`);
+        for (const argument of command.registeredArguments) {
+            if (!argument.description)
+                argument.description = {
+                    address: 'Atto address', destination: 'Recipient Atto address', amount: 'Exact amount (default unit: ATTO)',
+                    hash: '64-character transaction hash', id: 'Proposal ID', 'request-id': 'Saved payment request ID',
+                    'address-or-index': 'Atto address or existing saved wallet index',
+                    event: 'Event type', name: command.parent?.name() === 'labels' ? 'Personal name (1–128 characters after trimming)' : 'Shared operation name', operation: 'Shared operation name; inspect it with atto operations <name>',
+                }[argument.name()] ?? argument.name();
+        }
+        for (const option of command.options) {
+            if (option.long === '--unit')
+                option.choices(command.name() === 'send' ? ['ATTO', 'RAW', 'USD'] : ['ATTO', 'RAW']);
+            if (option.long === '--network')
+                option.choices(['LIVE', 'BETA', 'DEV', 'LOCAL']);
+            if (option.long === '--access')
+                option.choices(['read-only', 'spend']);
+            if (option.long === '--status')
+                option.choices(['reserved', 'signed', 'published', 'unknown', 'failed']);
+        }
+        if (command.name() === 'history')
+            command.registeredArguments[0]?.choices(['entry', 'transaction']).default('entry');
+        if (command.name() === 'watch')
+            command.registeredArguments[0]?.choices(['account', 'transaction', 'entry', 'receivable']);
+        command.commands.forEach(child => visit(child, path));
+    }
+    visit(program);
+    return () => failedCommand;
+}
+export function commandErrorMessage(error) {
+    if (['commander.missingArgument', 'commander.optionMissingArgument', 'commander.missingMandatoryOptionValue'].includes(error.code)) {
+        return error.message.replace(/^error: /, '');
+    }
+    // Other Commander messages can contain supplied values, including secrets.
+    return {
+        'commander.help': 'Missing subcommand. Choose one of the available commands.',
+        'commander.unknownCommand': 'Unknown command.',
+        'commander.unknownOption': 'Unknown option.',
+        'commander.invalidArgument': 'Invalid argument value. Check the accepted values in this command\'s help.',
+        'commander.excessArguments': 'Too many arguments.',
+    }[error.code] ?? 'Invalid command arguments.';
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Set this before dynamic imports: Commons' Kotlin logger initializes lazily.
+process.env.KOTLIN_LOGGING_STARTUP_MESSAGE = 'false';
+console.log = console.info = console.debug = console.error.bind(console);
+try {
+    const { runCli } = await import('./cli.js');
+    await runCli();
+}
+catch {
+    process.stderr.write('Atto could not start. Check runtime, password store, and state directory availability.\n');
+    process.exitCode = 1;
+}
+export {};

package/dist/cli/onboarding.d.ts

@@ -0,0 +1,14 @@
+export { formatHumanResult } from './output.js';
+export { configureHelp, commandErrorMessage } from './help.js';
+interface ProposalOptions {
+    id: string;
+    directory?: string;
+}
+/** Deliberately outside the core facade: only local terminal workflows can approve proposals. */
+export declare function approveLimitsProposal({ id, directory }: ProposalOptions): Promise<unknown>;
+export declare function rejectLimitsProposal({ id, directory }: ProposalOptions): Promise<unknown>;
+/** Returns only public host configuration; recovery material is displayed directly on the TTY. */
+export declare function setupMcp({ version, directory }: {
+    version: string;
+    directory?: string;
+}): Promise<unknown>;

package/dist/cli/onboarding.js

@@ -0,0 +1,144 @@
+import { resolve } from 'node:path';
+import { AttoApplication } from '../application/app.js';
+import { amountRaw } from '../domain/amount.js';
+import { AttoError } from '../domain/errors.js';
+import { defaultCliDirectory, dedicatedMcpDirectory, resolveWalletProfile } from '../storage/profiles.js';
+import { hiddenPrompt, requireTerminal, showRecovery, terminalPrompt } from './terminal.js';
+import { formatHumanResult } from './output.js';
+export { formatHumanResult } from './output.js';
+export { configureHelp, commandErrorMessage } from './help.js';
+function display(value) {
+    process.stderr.write(formatHumanResult(value));
+}
+async function confirm(prompt) {
+    if (await terminalPrompt(prompt) !== 'yes')
+        throw new AttoError('CANCELLED', 'No approval was granted.');
+}
+async function choose(prompt) {
+    const answer = await terminalPrompt(prompt) || '1';
+    if (answer !== '1' && answer !== '2')
+        throw new AttoError('INVALID_INPUT', 'Choose 1 or 2.');
+    return answer;
+}
+function formatPolicy(policy) {
+    const perPayment = policy.perRequest ? `${policy.perRequest.amount} ${policy.perRequest.unit}` : 'Unlimited';
+    const rolling = policy.rolling.length
+        ? policy.rolling.map(rule => `${rule.amount} ${rule.unit} / ${rule.days} day${rule.days === 1 ? '' : 's'}`).join(', ')
+        : 'Unlimited';
+    return `Per payment: ${perPayment}; rolling: ${rolling}`;
+}
+function showProposal(review) {
+    const { proposal } = review;
+    process.stderr.write([
+        `Wallet: ${review.identity ? JSON.stringify(review.identity.address) : 'Not initialized'}`,
+        `Network: ${JSON.stringify(review.network)}`,
+        `Profile: ${JSON.stringify(review.directory)}`,
+        `Proposal: ${JSON.stringify(proposal.id)} (${proposal.status})`,
+        `Expires: ${new Date(proposal.expiresAt).toISOString()}`,
+        ...(review.mcpAccess !== 'read-only' || proposal.access !== 'read-only' ? [`MCP access: ${review.mcpAccess} → ${proposal.access}`] : []),
+        `Current limits: ${formatPolicy(review.policy)}`,
+        `Requested limits: ${formatPolicy(proposal.policy)}`,
+        `Current pool: indexes ${review.pool.indexes.join(', ')}; consolidation ${review.pool.consolidate ? 'enabled' : 'disabled'}`,
+        `Requested pool: indexes ${(proposal.pool ?? review.pool).indexes.join(', ')}; consolidation ${(proposal.pool ?? review.pool).consolidate ? 'enabled' : 'disabled'}`,
+        '',
+    ].join('\n'));
+}
+async function approve(application, id) {
+    process.stderr.write('\nReview this exact limits proposal. These spending limits are shared with CLI payments in this profile.\n');
+    showProposal(await application.reviewLimitsProposal(id));
+    await confirm('Type yes to approve this exact proposal: ');
+    return application.approveLimitsProposal(id);
+}
+/** Deliberately outside the core facade: only local terminal workflows can approve proposals. */
+export async function approveLimitsProposal({ id, directory }) {
+    requireTerminal();
+    const application = new AttoApplication({ directory });
+    try {
+        return await approve(application, id);
+    }
+    finally {
+        await application.close();
+    }
+}
+export async function rejectLimitsProposal({ id, directory }) {
+    requireTerminal();
+    const application = new AttoApplication({ directory });
+    try {
+        showProposal(await application.reviewLimitsProposal(id));
+        await confirm('Type yes to reject this exact proposal: ');
+        return await application.rejectLimitsProposal(id);
+    }
+    finally {
+        await application.close();
+    }
+}
+async function initializeWallet(application, directory) {
+    const status = await application.call('wallet_status');
+    if (status.initialized) {
+        process.stderr.write('This profile already has a wallet. Setup will reuse its funds and spending history.\n');
+        return;
+    }
+    const method = await choose('Wallet is not initialized. [1] Create a new wallet (default), [2] Import a recovery phrase: ');
+    display({ directory, action: method === '1' ? 'Create a new wallet' : 'Import a wallet' });
+    await confirm('Type yes to store this wallet in the OS password store: ');
+    if (method === '1') {
+        await application.createWallet();
+        showRecovery(await application.backupMnemonic());
+    }
+    else {
+        await application.createWallet(await hiddenPrompt('Recovery phrase (hidden): '));
+    }
+}
+async function boundedPolicy() {
+    const perRequest = await terminalPrompt('Maximum ATTO per payment: ');
+    amountRaw(perRequest);
+    const daily = await terminalPrompt('Maximum ATTO across a rolling 24 hours: ');
+    amountRaw(daily);
+    return { perRequest: { amount: perRequest, unit: 'ATTO' }, rolling: [{ days: 1, amount: daily, unit: 'ATTO' }] };
+}
+async function configurePool(current) {
+    process.stderr.write(`Current payment pool: indexes ${current.indexes.join(', ')}; consolidation ${current.consolidate ? 'enabled' : 'disabled'}.\n`);
+    if (await choose('Account pool: [1] Keep current pool (default), [2] Configure account pool: ') === '1')
+        return current;
+    const input = await terminalPrompt(`Account indexes, separated by commas [${current.indexes.join(',')}]: `) || current.indexes.join(',');
+    const indexes = input.split(',').map(value => /^\d+$/.test(value.trim()) ? Number(value.trim()) : NaN);
+    process.stderr.write('Consolidation allows automatic payments to move funds between pool accounts when no single account has enough. Explicit source indexes never consolidate. Newly approved indexes are derived but are not activated for automatic receiving.\n');
+    const consolidate = await choose('Consolidation: [1] Disabled (default), [2] Enabled: ') === '2';
+    return { indexes, consolidate };
+}
+/** Returns only public host configuration; recovery material is displayed directly on the TTY. */
+export async function setupMcp({ version, directory }) {
+    requireTerminal();
+    process.stderr.write('Atto MCP setup. Recovery phrases stay in your OS password store and this terminal.\n');
+    const wallet = await choose('Wallet: [1] Dedicated MCP wallet (default), [2] Existing CLI wallet: ');
+    let selected = directory;
+    if (!selected && wallet === '2') {
+        const defaultDirectory = defaultCliDirectory();
+        selected = await terminalPrompt(`CLI wallet directory [${JSON.stringify(defaultDirectory)}]: `) || defaultDirectory;
+    }
+    const selectedDirectory = resolve(selected ?? dedicatedMcpDirectory());
+    if (wallet === '1' && selectedDirectory === resolve(defaultCliDirectory())) {
+        throw new AttoError('PROFILE_CONFLICT', 'This is the default CLI wallet directory. Choose the existing CLI wallet option to share it.');
+    }
+    const profile = resolveWalletProfile(selectedDirectory);
+    display({ directory: profile.directory, credentialService: profile.credentialService });
+    if (wallet === '2')
+        process.stderr.write('This shares funds, payment history, and spending limits with that CLI wallet.\n');
+    const application = new AttoApplication({ directory: profile.directory });
+    try {
+        await initializeWallet(application, profile.directory);
+        const usage = await application.call('limits_get');
+        const pool = await configurePool(usage.pool);
+        process.stderr.write('Read-only can view data, watch events, and propose limits. Bounded spending also permits wallet changes and payments within approved limits.\n');
+        const choice = await choose('MCP access: [1] Read-only (default), [2] Bounded spending: ');
+        const access = choice === '1' ? 'read-only' : 'spend';
+        const policy = access === 'read-only' ? usage.policy : await boundedPolicy();
+        const { proposal } = await application.call('limits_propose', { policy, access, pool });
+        await approve(application, proposal.id);
+        process.stderr.write('\nAdd this public configuration to your MCP client. The explicit data directory preserves your wallet selection.\n');
+        return { mcpServers: { atto: { command: 'npx', args: ['--yes', `@attocash/mcp@${version}`, '--data-dir', profile.directory] } } };
+    }
+    finally {
+        await application.close();
+    }
+}

package/dist/cli/output.d.ts

@@ -0,0 +1,2 @@
+/** Render names next to full addresses only at the human-output boundary. */
+export declare function formatHumanResult(result: unknown, operation?: string): string;

package/dist/cli/output.js

@@ -0,0 +1,231 @@
+import { modelAddress } from '../labels/presentation.js';
+import { AttoBlock } from '@attocash/commons-core';
+import { amountOutput } from '../domain/amount.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Public network data and caller metadata must not control the terminal. */
+function text(value) {
+    return String(value).replace(/[\u0000-\u001f\u007f-\u009f\u2028-\u202e\u2066-\u2069]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+function label(key) {
+    const names = {
+        id: 'ID', requestId: 'Request ID', raw: 'RAW', atto: 'ATTO', usd: 'USD',
+        priceUsd: 'Price per ATTO (USD)', nodeUrl: 'Node URL', workerUrl: 'Worker URL',
+        mcpAccess: 'Agent access', perRequest: 'Per payment', minReceiveRaw: 'Minimum receive (RAW)',
+        weight: 'Weight (RAW)',
+        directory: 'Profile', receivingInThisProcess: 'Receiving in this process',
+    };
+    if (Object.hasOwn(names, key))
+        return names[key];
+    const words = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/_/g, ' ').toLowerCase();
+    return text(words.charAt(0).toUpperCase() + words.slice(1));
+}
+function transactionSummary(value) {
+    const block = record(value.block) ? value.block : value;
+    let hash = value.hash;
+    if (!hash && record(value.block)) {
+        try {
+            hash = AttoBlock.fromJson(JSON.stringify(value.block)).hash.toString();
+        }
+        catch { /* Partial public results can omit protocol fields. */ }
+    }
+    return Object.fromEntries(Object.entries({
+        type: block.type ?? block.blockType, network: block.network,
+        address: modelAddress(block), destination: modelAddress(block, 'receiver'), subject: modelAddress(block, 'subject'),
+        representative: modelAddress(block, 'representative'), amount: block.amount,
+        balance: block.balance, previousBalance: block.previousBalance,
+        height: block.height, timestamp: block.timestamp, hash, sendHash: block.sendHash,
+    }).filter(([, value]) => value !== undefined));
+}
+function inline(value, literalKeys) {
+    if (value === null || value === undefined)
+        return 'None';
+    if (typeof value === 'boolean')
+        return value ? 'Yes' : 'No';
+    if (typeof value !== 'object')
+        return text(value);
+    if (Array.isArray(value)) {
+        if (!value.length)
+            return 'None';
+        if (value.every(item => item === null || typeof item !== 'object'))
+            return value.map(item => inline(item, literalKeys)).join(', ');
+    }
+    else {
+        if (!Object.keys(value).length)
+            return 'None';
+        if (!literalKeys && record(value) && Object.keys(value).length === 2
+            && typeof value.atto === 'string' && typeof value.raw === 'string') {
+            return `${text(value.atto)} ATTO (${text(value.raw)} RAW)`;
+        }
+    }
+    return undefined;
+}
+function fields(value, indent = '', literalKeys = false) {
+    const short = inline(value, literalKeys);
+    if (short !== undefined)
+        return [`${indent}${short}`];
+    if (Array.isArray(value)) {
+        return value.flatMap((item, index) => [`${indent}${index + 1}.`, ...fields(item, `${indent}  `, literalKeys)]);
+    }
+    const object = value;
+    return Object.entries(object).flatMap(([key, value]) => {
+        // Serialized journal blocks are recovery/debugging data available in --json.
+        if (!literalKeys && ['blockJson', 'signature', 'work', 'addressLabels', 'globalDirectory'].includes(key))
+            return [];
+        const literal = literalKeys || key === 'metadata';
+        // Core monetary fields use RAW unless they include units or an ATTO/RAW pair.
+        const raw = ['amount', 'balance', 'previousBalance'].includes(key) && typeof value !== 'object' && !Object.hasOwn(object, 'unit');
+        const name = literalKeys ? text(key) : label(key);
+        const displayValue = raw && !literal && typeof value === 'string' && /^\d+$/.test(value) ? amountOutput(value) : value;
+        const short = value === null && key === 'perRequest' && !literal ? 'Unlimited' : inline(displayValue, literal);
+        return short === undefined
+            ? [`${indent}${name}:`, ...fields(value, `${indent}  `, literal)]
+            : [`${indent}${name}: ${short}`];
+    });
+}
+function addressSummary(value) {
+    if (!record(value))
+        return value;
+    return { index: value.index, address: value.address, active: value.active };
+}
+function receiveProgress(progress) {
+    if (progress.event === 'reconnecting') {
+        return `Receiving connection interrupted: ${text(progress.error.code)}: ${text(progress.error.message)} Retrying in ${progress.retryInMs / 1000}s.\n`;
+    }
+    const payment = `${text(progress.amount.atto)} ATTO for account ${text(progress.index)} ${text(progress.address)} (send ${text(progress.sendHash)})`;
+    switch (progress.event) {
+        case 'pending': return `Pending: ${payment}\n`;
+        case 'receiving': return `Receiving: ${payment}\n`;
+        case 'received': return `Received: ${payment}\n${progress.receiveHash ? `Receive transaction: ${text(progress.receiveHash)}\n` : ''}`;
+        case 'retry': return `Receive delayed: ${payment}\n${text(progress.error.code)}: ${text(progress.error.message)} Retrying in ${progress.retryInMs / 1000}s.\n`;
+        case 'skipped': return `Skipped: ${payment}\n${text(progress.error.code)}: ${text(progress.error.message)}\n`;
+    }
+}
+/** Human presentation belongs to the CLI; engine and MCP results stay intact. */
+function formatUnlabeledHumanResult(result, operation) {
+    if (operation === 'receive_progress')
+        return receiveProgress(result);
+    if (record(result)) {
+        if (operation === 'doctor' && Array.isArray(result.checks)) {
+            const checks = result.checks.filter(record).map(check => {
+                const heading = `[${text(check.status).toUpperCase()}] ${text(check.id)} (${text(check.code)}): ${text(check.message)}`;
+                const evidence = record(check.evidence) ? fields(check.evidence, '  ').join('\n') + '\n' : '';
+                const remediation = record(check.remediation) ? check.remediation : undefined;
+                const steps = Array.isArray(remediation?.steps) ? remediation.steps.map(step => `  ${text(step)}\n`).join('') : '';
+                const quoteArgument = (value) => {
+                    const argument = String(value);
+                    if (/^[a-z\d_./:@=-]+$/i.test(argument))
+                        return argument;
+                    return `'${argument.replace(/'/g, process.platform === 'win32' ? "''" : "'\\''")}'`;
+                };
+                const command = Array.isArray(remediation?.command)
+                    ? `  Command${process.platform === 'win32' ? ' (PowerShell)' : ''}: ${text(remediation.command.map(quoteArgument).join(' '))}\n` : '';
+                const env = record(remediation?.suggestedEnv) ? `  Verified MCP env configuration:\n${fields(remediation.suggestedEnv, '    ', true).join('\n')}\n` : '';
+                return `${heading}\n${evidence}${steps}${command}${env}`;
+            });
+            return `Doctor: ${text(result.status).toUpperCase()}\n${fields(result.context).join('\n')}\n\n${checks.join('\n')}\nCompleted in ${text(result.durationMs)} ms. Diagnostics only; no repairs applied.\n`;
+        }
+        if (['wallet_create', 'wallet_import'].includes(operation ?? '') && record(result.identity)) {
+            return `Wallet ${operation === 'wallet_create' ? 'created' : 'imported'}.\nAddress: ${text(result.identity.address)}\n`;
+        }
+        if ((operation === 'wallet_status' || operation === 'wallet_receive') && record(result.settings)) {
+            const receiver = record(result.autoReceive) ? result.autoReceive : {};
+            const values = {
+                directory: result.directory,
+                status: result.resetPending ? 'Reset unfinished; run wallet reset to finish cleanup' : result.initialized ? 'Initialized' : 'Not initialized',
+                address: record(result.identity) ? result.identity.address : null,
+                network: result.settings.network,
+                automaticReceiving: result.settings.autoReceive ? 'Enabled' : 'Disabled',
+                ...(operation === 'wallet_status' ? { receivingInThisProcess: receiver.running, lastReceiveError: receiver.lastError } : {}),
+                representative: result.settings.representative,
+                minReceiveRaw: result.settings.minReceiveRaw,
+                nodeUrl: result.settings.nodeUrl,
+                workerUrl: result.settings.workerUrl,
+                addresses: Array.isArray(result.addresses) ? result.addresses.map(addressSummary) : result.addresses,
+                pool: result.pool,
+                pendingPayments: result.pendingSends,
+            };
+            const notice = operation === 'wallet_receive' ? 'Automatic receiving session. Press Ctrl+C to stop.\n' : '';
+            return notice + fields(values).join('\n') + '\n';
+        }
+        if (operation === 'address_list' && Array.isArray(result.addresses)) {
+            if (!result.addresses.length)
+                return 'No wallet addresses. Create or import a wallet first.\n';
+            return fields({ addresses: result.addresses.map(addressSummary) }).join('\n') + '\n';
+        }
+        if (['address_add', 'address_derive', 'address_activate', 'address_deactivate'].includes(operation ?? '')) {
+            return fields(addressSummary(result)).join('\n') + '\n';
+        }
+        if (['send', 'receive', 'representative_change'].includes(operation ?? '') && record(result.transaction)) {
+            const transaction = transactionSummary(result.transaction);
+            const summary = {
+                status: result.status, requestId: result.requestId, index: result.index,
+                amount: result.amount ?? transaction.amount, source: result.sourceAddress ?? transaction.address,
+                destination: result.destination ?? transaction.destination, destinationBinding: result.destinationBinding, representative: transaction.representative,
+                hash: result.hash, sendHash: transaction.sendHash,
+                quote: result.quote, metadata: result.metadata, consolidation: result.consolidation,
+            };
+            const notice = record(result.quote) ? 'Indicative conversion only; this is not an executable exchange quote.\n' : '';
+            return notice + fields(Object.fromEntries(Object.entries(summary).filter(([, value]) => value !== undefined))).join('\n') + '\n';
+        }
+        if (['labels_get', 'labels_list'].includes(operation ?? '') && record(result.addressLabels)) {
+            return fields({ network: result.network, labels: Object.entries(result.addressLabels).map(([address, value]) => ({ address, ...(record(value) ? value : {}) })), directoryStatus: result.globalDirectory }).join('\n') + '\n';
+        }
+        if (operation === 'account_get') {
+            if (!record(result.account))
+                return 'Account is not open on the network. Receiving funds opens an account.\n';
+            return fields({ ...transactionSummary(result.account), lastTransactionHash: result.account.lastTransactionHash }).join('\n') + '\n';
+        }
+        if (['transaction_get', 'entry_get'].includes(operation ?? '')) {
+            const value = result.transaction ?? result.entry;
+            return record(value) ? fields(transactionSummary(value)).join('\n') + '\n' : 'No matching network record found.\n';
+        }
+        if (operation === 'balances_get' && Array.isArray(result.balances) && !result.balances.length) {
+            return 'No matching wallet accounts. Use address add, address activate, or balances --all.\n';
+        }
+        if (['history_list', 'receivables_list', 'journal_list'].includes(operation ?? '') && Array.isArray(result.items)) {
+            const items = operation === 'journal_list' ? result.items : result.items.map(value => record(value) ? transactionSummary(value) : value);
+            const body = items.length ? fields({ items }).join('\n') + '\n'
+                : operation === 'receivables_list' ? 'No pending payments found during this scan.\n'
+                    : operation === 'journal_list' ? 'No payment journal records found.\n' : 'No matching account history found.\n';
+            return body + (result.timedOut ? 'Scan window ended; results may be incomplete.\n' : '')
+                + (result.limitReached ? 'Record limit reached; more payments may remain.\n' : '')
+                + (result.nextCursor ? `Next cursor: ${text(result.nextCursor)}\n` : '');
+        }
+        if (operation === 'watch_read' && Array.isArray(result.events)) {
+            return fields({ ...result, events: result.events.map(event => record(event)
+                    ? { ...event, data: record(event.data) ? transactionSummary(event.data) : event.data } : event) }).join('\n') + '\n';
+        }
+        if (operation === 'receive_all' && Array.isArray(result.results)) {
+            return `Received ${result.results.length} payment${result.results.length === 1 ? '' : 's'}.\n`
+                + result.results.map(value => formatHumanResult(value, 'receive')).join('')
+                + (result.timedOut || result.limitReached ? `${result.limitReached ? 'Batch limit reached' : 'Scan window ended'}; more payments may remain. Run receive-all again or wallet receive for continuous receiving.\n` : '');
+        }
+    }
+    if (operation === 'operations' && Array.isArray(result)) {
+        return result.map(item => record(item)
+            ? `${text(item.name)} (${item.readOnly ? 'read-only' : 'write'})\n  ${text(item.description)}`
+            : text(item)).join('\n') + '\n';
+    }
+    const indicative = record(result) && (result.informational === true || (record(result.quote) && result.quote.informational === true));
+    const notice = indicative ? 'Indicative conversion only; this is not an executable exchange quote.\n' : '';
+    return notice + fields(result).join('\n') + '\n';
+}
+/** Render names next to full addresses only at the human-output boundary. */
+export function formatHumanResult(result, operation) {
+    const output = formatUnlabeledHumanResult(result, operation);
+    if (!record(result) || !record(result.addressLabels))
+        return output;
+    const dictionary = result.addressLabels;
+    return output.replace(/atto:\/\/[a-z2-7]+/g, address => {
+        const labels = dictionary[address];
+        if (!record(labels))
+            return address;
+        const binding = record(result.destinationBinding) && result.destinationBinding.address === address ? result.destinationBinding : undefined;
+        const personal = binding?.label ?? (record(labels.personal) ? labels.personal.label : undefined);
+        const global = Array.isArray(labels.global) ? labels.global.filter(record).map(value => `${text(value.label)} [global${value.stale ? ', stale' : ''}]`) : [];
+        const names = [...(personal ? [`${text(personal)} [personal]`] : []), ...global];
+        return names.length ? `${address} (${names.join('; ')})` : address;
+    });
+}

package/dist/cli/terminal.d.ts

@@ -0,0 +1,6 @@
+export declare function requireTerminal(): void;
+/** Public choices and confirmations stay on the terminal; stdout remains machine-readable. */
+export declare function terminalPrompt(prompt: string): Promise<string>;
+/** Recovery input is read in raw mode without echoing or entering shell history. */
+export declare function hiddenPrompt(prompt: string): Promise<string>;
+export declare function showRecovery(mnemonic: string): void;

package/dist/cli/terminal.js

@@ -0,0 +1,92 @@
+import { emitKeypressEvents } from 'node:readline';
+import { createInterface } from 'node:readline/promises';
+import { AttoError } from '../domain/errors.js';
+export function requireTerminal() {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+        throw new AttoError('TERMINAL_REQUIRED', 'This operation requires an interactive terminal.');
+    }
+}
+/** Public choices and confirmations stay on the terminal; stdout remains machine-readable. */
+export async function terminalPrompt(prompt) {
+    requireTerminal();
+    const wasPaused = process.stdin.isPaused();
+    const terminal = createInterface({ input: process.stdin, output: process.stderr });
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    terminal.once('SIGINT', cancel);
+    terminal.once('close', cancel);
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    try {
+        return (await terminal.question(prompt, { signal: controller.signal })).trim();
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new AttoError('CANCELLED', 'Terminal operation cancelled.');
+        throw error;
+    }
+    finally {
+        terminal.removeListener('SIGINT', cancel);
+        terminal.removeListener('close', cancel);
+        process.removeListener('SIGINT', cancel);
+        process.removeListener('SIGTERM', cancel);
+        terminal.close();
+        if (wasPaused)
+            process.stdin.pause();
+    }
+}
+/** Recovery input is read in raw mode without echoing or entering shell history. */
+export async function hiddenPrompt(prompt) {
+    requireTerminal();
+    const input = process.stdin;
+    const wasRaw = input.isRaw;
+    const wasFlowing = input.readableFlowing === true;
+    emitKeypressEvents(input);
+    process.stderr.write(prompt);
+    input.setRawMode(true);
+    input.resume();
+    return new Promise((resolve, reject) => {
+        let value = '';
+        const cleanup = () => {
+            input.removeListener('keypress', onKey);
+            process.removeListener('SIGINT', cancel);
+            process.removeListener('SIGTERM', cancel);
+            input.setRawMode(wasRaw);
+            if (!wasFlowing)
+                input.pause();
+            process.stderr.write('\n');
+        };
+        const cancel = () => {
+            value = '';
+            cleanup();
+            reject(new AttoError('CANCELLED', 'Wallet import cancelled.'));
+        };
+        const onKey = (text, key) => {
+            if (key.ctrl && (key.name === 'c' || key.name === 'd'))
+                return cancel();
+            if (key.name === 'return' || key.name === 'enter') {
+                cleanup();
+                const result = value.trim().replace(/\s+/g, ' ');
+                value = '';
+                resolve(result);
+            }
+            else if (key.name === 'backspace') {
+                value = value.slice(0, -1);
+            }
+            else if (key.ctrl && key.name === 'u') {
+                value = '';
+            }
+            else if (!key.ctrl && !key.meta && text && !/[\x00-\x1f\x7f]/.test(text)) {
+                if (value.length + text.length <= 2048)
+                    value += text;
+            }
+        };
+        input.on('keypress', onKey);
+        process.once('SIGINT', cancel);
+        process.once('SIGTERM', cancel);
+    });
+}
+export function showRecovery(mnemonic) {
+    requireTerminal();
+    process.stderr.write(`\nRecovery phrase (keep a private offline copy):\n${mnemonic}\n\n`);
+}

package/dist/cli/update-check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/update-check.js

@@ -0,0 +1,12 @@
+import { refreshUpdateCache } from './updates.js';
+// Bound the entire worker lifetime as well as the HTTP request, including any
+// sockets left open by the HTTP client. This never runs in the wallet process.
+setTimeout(() => process.exit(0), 5000).unref();
+try {
+    const file = process.argv[2];
+    if (file)
+        await refreshUpdateCache(file);
+}
+finally {
+    process.exit(0);
+}

package/dist/cli/updates.d.ts

@@ -0,0 +1,2 @@
+export declare function notifyUpdate(currentVersion: string): void;
+export declare function refreshUpdateCache(file: string): Promise<void>;