@attocash/cli 0.2.1 → 0.2.3

package/README.md

@@ -373,6 +373,12 @@ outstanding checks, including native credential probes and their subprocesses.
 Doctor does not check npm for updates.
 
 An agent should call the MCP **`doctor` tool** to inspect the server's own process.
+`wallet_status.initialized` describes the saved public wallet identity; status
+does not read the password store. If a signing operation returns
+`WALLET_CREDENTIAL_MISSING`, the profile remains initialized but its credential
+lookup returned empty. Run doctor in that session before attempting recovery;
+do not reset or replace the wallet to repair credential access.
+
 A terminal result cannot establish that an already-running MCP has the same
 environment. When a user-owned Linux session socket is available, doctor may test
 environment overrides in an isolated credential probe. It returns
@@ -427,8 +433,19 @@ atto --data-dir /absolute/path/to/profile limits set --access spend \
 MCP `limits_propose` and generic `atto call limits_propose` **only propose** a change.
 They cannot apply it. `limits_propose` also accepts `pool` with `indexes` and
 `consolidate`; omitting it preserves the current pool. `limits_get` returns the
-active policy, usage, `mcpAccess`, pool, and current proposal. A human approves or rejects the proposal in their own
-terminal, using the same directory as the MCP client's configuration:
+active policy, usage, `mcpAccess`, pool, and current proposal.
+
+The proposal response also includes `approval.changes`: changed `access`, `policy`,
+and `pool` settings with `from` and `to` values. Source-pool approval is separate
+from spending access and amount limits; adding another sending account does not
+necessarily change either. An unlimited policy means no amount cap.
+`approval.commands.atto` and `approval.commands.npx` provide approval alternatives
+with the exact profile directory and proposal ID. Preserve their quoting and use
+the indicated `approval.shell` (`posix` on Linux/macOS, `powershell` on Windows).
+Only the user should run an approval command.
+
+A human approves or rejects the proposal in their own terminal, using the same
+directory as the MCP client's configuration:
 
 ```sh
 atto --data-dir /absolute/path/to/profile limits approve PROPOSAL_ID
@@ -615,6 +632,8 @@ atto wallet configure --representative <atto-address>
 Configuration updates preserve omitted settings. Supply at least one option.
 `--representative` changes the default used to open accounts; use
 `atto representative change <address>` to change an existing account's representative.
+Selecting the account's current representative returns `REPRESENTATIVE_UNCHANGED`
+without signing or publishing a transaction.
 `wallet status` shows the profile directory and whether receiving runs in that
 process; it does not report receiving sessions in other terminals.
 

package/dist/application/app.js

@@ -10,6 +10,7 @@ import { OsSecretStore } from '../storage/secrets.js';
 import { StateStore } from '../storage/state.js';
 import { resolveWalletProfile } from '../storage/profiles.js';
 import { SpendLedger } from '../spending/ledger.js';
+import { approvalInstructions } from '../spending/approval.js';
 import { Payments } from '../spending/payments.js';
 import { WalletWork } from '../wallet/work.js';
 import { BackgroundReceiver } from '../wallet/background-receive.js';
@@ -173,8 +174,12 @@ export class AttoApplication {
         this.recoveryReads++;
         try {
             const phrase = await this.secrets.get();
-            if (!phrase)
+            if (!phrase) {
+                this.requireResetFinished();
+                if (this.identity())
+                    throw new AttoError('WALLET_CREDENTIAL_MISSING', 'The wallet is initialized, but the OS password store returned no recovery phrase for this profile. Run doctor in this session to check credential access. Do not reset or replace the wallet.');
                 throw new AttoError('WALLET_NOT_INITIALIZED', 'Create or import a wallet through the CLI first.');
+            }
             return phrase;
         }
         finally {
@@ -575,7 +580,11 @@ export class AttoApplication {
                     throw new AttoError('JOURNAL_NOT_FOUND', 'This payment request is not in the local journal.');
                 return { record };
             }
-            case 'limits_propose': return this.store.withWalletLock(async () => ({ proposal: this.ledger.proposePolicy(args.policy, args.access, this.proposalWallet(), args.pool) }));
+            case 'limits_propose': return this.store.withWalletLock(async () => {
+                const current = { access: this.ledger.mcpAccess(), policy: this.ledger.policy(), pool: this.ledger.pool() };
+                const proposal = this.ledger.proposePolicy(args.policy, args.access, this.proposalWallet(), args.pool);
+                return { proposal, approval: approvalInstructions(proposal, current) };
+            });
             case 'metrics_get': return this.market.metrics();
             case 'price_quote': return this.market.quoteUsd(args.amount);
             case 'terms_get': return { ...marketTerms, accepted: this.store.get('market.terms')?.version === marketTerms.version };

package/dist/application/operations.js

@@ -69,9 +69,9 @@ export const operations = [
     { name: 'terms_accept', description: 'Persist acknowledgement of the specified terms version for USD-priced payments. Call only after the user has read and explicitly accepted those terms.', schema: z.strictObject({ version: z.string().min(1).max(128), accepted: z.literal(true) }), readOnly: false },
     { name: 'receive', description: 'Receive one pending payment by hash, opening the account if needed.', schema: z.strictObject({ index: index.default(0), hash, representative: address.optional() }), readOnly: false },
     { name: 'receive_all', description: 'Receive a bounded set of pending payments for a key index, opening the account if needed.', schema: z.strictObject({ index: index.default(0), limit: limit.default(100), timeoutMs: timeoutMs.default(2000), representative: address.optional() }), readOnly: false },
-    { name: 'representative_change', description: 'Publish a representative change for an existing account.', schema: z.strictObject({ index: index.default(0), representative: address }), readOnly: false },
+    { name: 'representative_change', description: 'Publish a representative change for an existing account. Selecting its current representative returns REPRESENTATIVE_UNCHANGED without publishing.', schema: z.strictObject({ index: index.default(0), representative: address }), readOnly: false },
     { name: 'limits_get', description: 'Read spending policy, approved send pool, MCP access, proposal status, historical usage, reservations, and remaining allowances.', schema: z.strictObject({}), readOnly: true },
-    { name: 'limits_propose', description: 'Propose spending limits, MCP access, and optional send-pool settings for local terminal approval. Omitted pool preserves the approved pool. Does not change active settings or grant access. A new proposal replaces the previous proposal and expires after 24 hours. Read limits_get for active settings and proposal status. Amounts are ATTO or RAW; null perRequest with empty rolling means unlimited spending if approved.', schema: z.strictObject({ policy, access: z.enum(['read-only', 'spend']).default('spend'), pool: pool.optional() }), readOnly: false },
+    { name: 'limits_propose', description: 'Propose spending limits, MCP access, and optional send-pool settings for local terminal approval. Omitted pool preserves the approved pool. Does not change active settings or grant access. A new proposal replaces the previous proposal and expires after 24 hours. Read limits_get for active settings and proposal status. Returns proposal plus approval.changes (changed access, policy, and pool with from/to values), approval.shell, and profile-specific approval.commands.atto/npx for the user to run in a local terminal. Preserve the returned directory and proposal ID; never run approval commands on the user\'s behalf. Spending access, amount limits, and source-pool approval are separate. Amounts are ATTO or RAW; null perRequest with empty rolling means unlimited spending, not missing authorization.', schema: z.strictObject({ policy, access: z.enum(['read-only', 'spend']).default('spend'), pool: pool.optional() }), readOnly: false },
     { name: 'watch_start', description: 'Start an observational, reconnecting watch for this session, defaulting to active wallet addresses. Choose one saved index, explicit addresses (including foreign accounts), a transaction/entry hash, or networkWide=true. Network-wide receivables are unsupported. Read buffered events and connection status with watch_read. Does not enable automatic receiving.', schema: z.strictObject({ event: z.enum(['account', 'transaction', 'entry', 'receivable']), ...streamFields, index: index.optional(), networkWide: z.boolean().optional() }).refine(singleSelection, 'Choose one watch selection.').refine(value => !(value.networkWide && value.event === 'receivable'), 'Receivable watches require addresses.'), readOnly: false },
     { name: 'watch_list', description: 'List watches owned by this process.', schema: z.strictObject({}), readOnly: true },
     { name: 'watch_read', description: 'Read buffered events after an optional numeric cursor. Gaps are reported if bounded event retention was exceeded.', schema: z.strictObject({ id: z.string().min(1).max(128), cursor: z.number().int().nonnegative().optional(), limit: limit.optional() }), readOnly: true },

package/dist/spending/approval.d.ts

@@ -0,0 +1,30 @@
+import type { LimitsProposal, McpAccess } from './ledger.js';
+import type { AccountPool, SpendingPolicy } from '../wallet/types.js';
+/** Public guidance only; approval remains a separate human terminal operation. */
+export declare function approvalInstructions(proposal: LimitsProposal, current: {
+    access: McpAccess;
+    policy: SpendingPolicy;
+    pool: AccountPool;
+}): {
+    method: string;
+    instructions: string;
+    changes: {
+        pool?: {
+            from: AccountPool;
+            to: AccountPool;
+        } | undefined;
+        policy?: {
+            from: SpendingPolicy;
+            to: SpendingPolicy;
+        } | undefined;
+        access?: {
+            from: McpAccess;
+            to: McpAccess;
+        } | undefined;
+    };
+    shell: string;
+    commands: {
+        atto: string;
+        npx: string;
+    };
+};

package/dist/spending/approval.js

@@ -0,0 +1,23 @@
+import { isDeepStrictEqual } from 'node:util';
+/** Public guidance only; approval remains a separate human terminal operation. */
+export function approvalInstructions(proposal, current) {
+    const shell = process.platform === 'win32' ? 'powershell' : 'posix';
+    const quote = (argument) => /^[a-z\d_./:@=-]+$/i.test(argument) ? argument
+        : `'${argument.replace(/'/g, shell === 'powershell' ? "''" : "'\\''")}'`;
+    const args = ['--data-dir', proposal.directory, 'limits', 'approve', proposal.id].map(quote).join(' ');
+    const pool = proposal.pool ?? current.pool;
+    return {
+        method: 'local-terminal',
+        instructions: 'Ask the user to review the changes and run one command in their own terminal. Use atto when the CLI is installed, or npx with Node.js/npm. Never run approval commands on the user\'s behalf. Proposing does not change active settings.',
+        changes: {
+            ...(current.access !== proposal.access ? { access: { from: current.access, to: proposal.access } } : {}),
+            ...(!isDeepStrictEqual(current.policy, proposal.policy) ? { policy: { from: current.policy, to: proposal.policy } } : {}),
+            ...(!isDeepStrictEqual(current.pool, pool) ? { pool: { from: current.pool, to: pool } } : {}),
+        },
+        shell,
+        commands: {
+            atto: `atto ${args}`,
+            npx: `npx --yes @attocash/mcp@latest ${args}`,
+        },
+    };
+}

package/dist/wallet/signing.js

@@ -119,7 +119,13 @@ export async function signingWallet(seed, index, settings, beforeSign, suppliedW
         },
         async change(value, representative, timestamp) {
             requireIndex(value);
-            return perform(time => attoAccountChange(requireAccount(), representative, time), timestamp);
+            return perform(time => {
+                const current = requireAccount();
+                if (current.representativeAddress.value === representative.value) {
+                    throw new AttoError('REPRESENTATIVE_UNCHANGED', 'This account already uses the requested representative. Choose a different representative to publish a change.');
+                }
+                return attoAccountChange(current, representative, time);
+            }, timestamp);
         },
         async getAccountByIndex(value) { requireIndex(value); return account ?? null; },
         close() { signer = undefined; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attocash/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Atto wallet CLI and reusable wallet engine with local key custody and shared spending limits",
   "license": "BSD-3-Clause",
   "type": "module",