[JoshDFN]

Base: jd/deploy-shortfall-hint (#823). This branch reuses that one's commands/args.rs::selection_flags, shell_word and PasteFlags::notes() for every command it prints, and its message builder (shortfall::Message, whose prose, commands and text this branch makes pub(crate)). The crate keeps one quoting helper and one layout for printed commands. Once #823 merges, this PR retargets to main.

What

These fixes come from the end-to-end test of the 1.7.0 release against mainnet CyclePay, and from the compatibility and docs reviews that went with it. They are CLI-side only:

• the gateway interface, the calls made and the order flow are unchanged;
• what changes is what the command says, and when;
• Ctrl-C and a stalled network are now always answered.

There are three commits, one per theme. Each builds and passes on its own, and carries its own tests and docs.

1. Arguments and gateway errors

• --gateway.
  • A principal no canister can have (the anonymous principal, the management canister, an identity's principal) is refused before any network is asked.
  • A canister without get_card_terms (IC0536) is said to be no gateway.
  • An id a boundary node cannot route (HTTP 4xx canister_not_found) is said not to exist. Any other 4xx stays a failure to read the terms.
  • Before, all three were raw replica or HTTP text.
• Arguments. With neither flag, clap names both: <--amount <AMOUNT>|--cycles <CYCLES>>. A negative value of either, -1 or -5t, is refused by clap in the same words and with exit status 2. Before, --amount -1 failed at run time, --cycles -1 in clap, and --cycles -5t as an unknown flag -5.
• -n local outside a project says there is no such network outside a project, and points at -n ic.
• Other gateways. CyclePay and Stripe's page are named only for CyclePay's gateway.
• Layout. An error that is the whole story (no cause beneath it) is wrapped to 80 columns, as the shortfall hint's are. Before, the terminal broke it mid-word.

2. The prompt and signals

• Stderr redirected. The prompt is drawn on stderr and reads stdin, so both must be a terminal. With stderr redirected (2>&1 | tee buy.log), the command refuses and names --yes. Before, it failed with IO error: not a terminal.
• Ctrl-C at the prompt is an answer: the line ends, the cursor comes back, no order is made, and the exit status is 1. Before, the process died by SIGINT with the cursor hidden.
• Ctrl-C after "y". From the prompt on, Ctrl-C and SIGTERM stay caught, so every step after it races its call against them:
  • create_order, which a stalled network can hold for minutes. The command stops at once and says the order may or may not exist. On CyclePay it also gives the command to find out: asking for the same amount again within the hour hands back the open order rather than making another.
  • the wait, which takes the same listeners, so a stop sent between steps is not lost;
  • the balance read after a delivery, which is left out.
• Narrow terminals. The question is just Create this order? [y/N]. "Nothing is charged until you pay on Stripe's page." goes on the line above.

3. The wait, the messages and --json

• Silence is judged by the clock.
  • The live line says No answer from the gateway, retrying once no poll has been answered for 9 seconds, whether or not a poll is in flight.
  • The wait gives up once five minutes pass without word of the order.
  • Both hold whether the network refuses each poll at once or stalls it. A poll counts as unanswered after 10 seconds.
  • Before, the give-up was a count of 100 failed polls, about 38 minutes on a stalled network.
• Where the order stands. However the wait ends unsettled (Ctrl-C, the hour, the gateway out of reach), the command says once where the order stands: payable until its deadline while unpaid, delivered once paid.
• Message layout. Every message is short sentences wrapped at 80 columns, as the shortfall hint's are. Each command goes on a line of its own, indented, without backticks:
  • icp cycles balance for the cycles, after any unsettled end and after --no-wait;
  • icp canister call <gateway> order_status --query ... '("<id>")' for a refund under way, and for an order an operator handles.
  • Both carry the identity and the network or environment the run used, through selection_flags. The default identity is named, since order_status answers only the order's owner and the default can change.
• Phases.
  • A payment that has not settled is Payment pending, not received.
  • A refund under way is not called final.
  • The gateway's note on a paid order (detail: why delivery waits, such as RATE_STALE) is shown, cut with … to fit the live line and whole off a terminal.
• The live line picks the longest message that fits. It may reach the last column, which indicatif pads to anyway; its comment said otherwise.
• QR code (a 1.7.0 defect). 1.7.0 drew the light modules as blocks in the terminal's own colours, so the code came out inverted on a light theme. Now it is black on white:
  • It uses the 256-colour cube's fixed black and white (16 and 231), which themes don't remap as they remap the first 16.
  • The colours are set on every row and reset at its end.
  • The quiet zone is white: four modules across, which the columns afford, and four down where the terminal has the rows, else two. A blank line goes above when one is spare.
  • A CyclePay link is version 6 (41 modules). At 80x24 it gets four modules across and two down; at 60x40 it gets everything.
  • With colour off (NO_COLOR, TERM=dumb, or colour disabled), the code is 1.7.0's drawing unchanged, so nobody loses what they have today.
• --cycles. The quote says Wanted: <cycles> over an estimate, not at least.

--json changed in one behaviour

The schema is additive.

• The first line gains gateway and buyer.
• The last line gains ended and expires_at.
• Every 1.7.0 key, its type and the exit statuses (0 only for a delivery) are unchanged.

The behaviour change. 1.7.0 printed a second line only once the order settled. Now a last line comes however the wait ends, with ended set to settled, interrupted, timed_out, contact_lost or not_found.

A script written against 1.7.0 that took "a second line" to mean "settled" must read ended instead (or status and the exit status). The buy-cycles agent skill reads "status":"delivered" plus exit 0, which stays correct. It should mention ended once this ships.

Follow-ups, for a decision

• Saying when an order is reused. CyclePay hands back an open order on a re-run within the hour, with its old deadline, and the command doesn't say so.
  • Saying it needs created_at : opt nat64 in the vendored cycles_gateway.did. CyclePay's OrderStatusView has it, and an optional field stays compatible with any gateway.
  • The command could then say "Order co-12-... is the one you made at 16:19Z", and add "reused": true|false to the first JSON line.
• A margin for --cycles. CyclePay converts through ICP e8s, so a delivery can land up to one e8's worth of cycles (about 22k today) under the estimate.
  • A margin of that much in least_gross_for restores "at least X at today's rate".
  • It could come from the CMC's public get_icp_xdr_conversion_rate, for CyclePay's gateway only, or be a fixed bound for any gateway (10M cycles covers ICP up to about $1,000).
  • The shortfall hint's icp cycles buy --cycles suggestion relies on the buy covering the gap.
• Not in this PR:
  • an icp cycles order <id> command, or another way to wait on an existing order;
  • a machine-readable quote;
  • icp cycles balance --json with a plain number;
  • the stale ^C line some terminals leave above the error;
  • the delivery report (... reports 6.938T cycles delivered to <principal>), which runs past 80 columns for a long principal, as in 1.7.0.

Tests

• Unit: 168 in the icp binary at the head. They include:

  • the prompt behind a small Prompt trait: the stderr check, the catch before the question (a SIGINT raised while it is asked would otherwise end the test binary), and the cursor's return;
  • a stalled create_order giving way to a ready interrupt;
  • the wait on a paused clock, stalled and refusing: quiet at exactly 9 s, given up at exactly 300 s;
  • a 4xx that is not canister_not_found;
  • the live line's width at the boundary column;
  • every message's layout (80 columns, commands on their own lines, no backticks);
  • the QR code read back module by module, with colour and without, at both quiet zones.

• Integration: cycles_tests.rs runs 20 tests against a Motoko stand-in gateway, which learns a pending and a refunding state. They cover:

  • a pending payment, and a refund under way with the order_status command as the buyer;
  • a gateway stopped and started mid-wait;
  • the last --json line on SIGINT;
  • --no-wait;
  • the ICP ledger and an unused id as --gateway, and ids that cannot be canisters;
  • -n local outside a project;
  • negative values with exit status 2, and neither flag.

• Checks, run locally on macOS:

  • the full workspace suite, with each integration test file capped (the docker tests are skipped, as CI's macOS job skips them);
  • clippy (--tests --benches -D warnings), fmt and taplo;
  • the wasm32 clippy, host-reach and no-host checks for icp-project;
  • the CLI reference and the schemas regenerate with no diff.

• A frozen network, measured. These ran on the stand-in, under a pty at 80x24, with the local network frozen (SIGSTOP to its pocket-ic) 3 s into the wait.

  • This branch said "No answer from the gateway" 8.9 s after the freeze, and gave up 299.9 s after it.
  • 1.7.0 said nothing, and was still waiting 416.7 s later, when the test driver stopped it.
  • Frozen at the prompt instead, then "y" and Ctrl-C 6 s later: this branch exits as soon as Ctrl-C is pressed, with status 1, and says the order may or may not exist. 1.7.0 dies by SIGINT and says nothing.

• QR decode matrix.

  • The real binaries (this branch, and 1.7.0) ran under a pty against the stand-in.
  • The screen 2 s into the wait was rendered to PNG in a dark and a light theme.
  • Each image was decoded with zxing-cpp 3.1.1 (try_invert=False) and OpenCV 5.0.0 (QRCodeDetector, and QRCodeDetectorAruco for comparison).
  • "Short" is the stand-in's own link (version 5, 37 modules). "Long" is a CyclePay-length link (version 6, 41 modules).

  Binary, link, size	zxing dark	zxing light	OpenCV dark	OpenCV light
  branch, long, 80x24	OK	OK	OK	OK
  branch, long, 60x40	OK	OK	fail	fail
  branch, short, 80x24	OK	OK	OK	OK
  branch, short, 60x40	OK	OK	OK	OK
  1.7.0, long or short, either size	OK	fail	OK	fail

  • Colour off. With NO_COLOR=1, and again with TERM=dumb, this branch prints no SGR sequence at all. Its code is 1.7.0's, character for character. As in 1.7.0, it decodes on a dark theme and needs inversion on a light one.
  • OpenCV's classic detector. It fails on the long link's code at 60x40, where the code has its full four-module quiet zone. It also fails on the qrcode library's own rendering of that link (black on white, a four-module border) at every module size from 6 to 12 px, and passes at 4 and 5 px. zxing-cpp and QRCodeDetectorAruco read every one of them, these drawings included. So the limit is the classic detector's on this version-6 code, not the drawing's.
  • No phone camera was tried.

• Mainnet, by hand. No run passed --yes or answered "y": each ended at the prompt (with Ctrl-C), at a refusal, or at an argument or gateway error. No order was made, nothing was paid, and no browser opened. The waits, stalls and refunds ran against the stand-in on a local network.

Before and after, in words

Captured under a pty at 80 and 60 columns, in a dark and a light theme, from 1.7.0 and from this branch.

• Ctrl-C at the prompt (mainnet). 1.7.0 is killed by SIGINT with the cursor hidden. This branch ends the line and prints Error: no order created, exit 1.
• Prompt at 60 columns. 1.7.0's question is longer than the line and is drawn over two rows (...pay on Strip / e. [y/N]). This branch puts "Nothing is charged until you pay on Stripe's page." on its own line, then Create this order? [y/N].
• stderr not a terminal. 1.7.0: Error: IO error: not a terminal. This branch refuses and names --yes.
• Ctrl-C during the wait. 1.7.0 says the order stays payable, then ends with interrupted while waiting for order ..., a backticked command broken mid-word at 80 columns. This branch says it once, as the error:

  Error: stopped waiting for order co-1-0000test.
  It stays payable until 2100-01-01T00:00:00Z. Once it is paid, its cycles land on
  your identity's cycles-ledger account. To see them:
  
      icp cycles balance --identity buyer -e standin-env
  

• A refund under way. 1.7.0 says the order "is being refunded" as if that were final. This branch says the refund can still end owed, and gives the order_status command, as the buyer.
• A pending payment. 1.7.0 shows Payment received; delivering cycles.... This branch shows Payment pending; waiting for it to settle.
• --gateway set to the ICP ledger. 1.7.0 prints the replica's IC0536 text over six lines. This branch says canister ... is not a cycles gateway: it does not serve get_card_terms, the method a gateway publishes its terms with.
• --cycles -5t. 1.7.0: unexpected argument '-5' found. This branch: invalid value '-5t' for '--cycles <CYCLES>': cannot be negative..., exit 2.
• --json with SIGINT during the wait. 1.7.0 prints one line. This branch prints two: the first names gateway and buyer, and the last carries "ended":"interrupted".

[raymondk]

closing this - it's replaced by the stack above PR825