@certen.io/cli 0.5.0 → 0.7.0

package/dist/wait.js

@@ -0,0 +1,168 @@
+import { CliError, UsageError, EXIT } from './errors.js';
+import { human, isJsonMode } from './output.js';
+/**
+ * Waiting for asynchronous work to finish.
+ *
+ * Two of this product's central operations return before they are usable — `POST /v1/identity`
+ * answers 202 while provisioning continues, and a transaction intent takes a 60–110 second proof
+ * cycle to reach a terminal state. Every document in the repo warns about both. The CLI
+ * nonetheless printed the interim response and exited, leaving each user to write the same poll
+ * loop, and leaving anyone who did not write one holding an identity that fails at the last step
+ * of every flow with an error that never mentions provisioning.
+ *
+ * The polling shape here is lifted from `certen fund`, which got it right first: speak only when
+ * something changes, treat a timeout as neither success nor failure, and never exit 0 on an
+ * outcome a script would misread as done.
+ */
+/** `certen fund`'s defaults are 60 min / 5 s; these are per-operation because the work differs. */
+export const IDENTITY_WAIT = { timeoutMin: 5, intervalSec: 3 };
+/**
+ * A proof cycle is 60–110 seconds of real validator work and `execute.wait()` budgets 360s. Seven
+ * minutes leaves room for a queue without being an unbounded hang. Do NOT shorten this to make a
+ * test faster — it is not a tunable delay.
+ */
+export const TX_WAIT = { timeoutMin: 7, intervalSec: 8 };
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+/**
+ * Should this invocation wait?
+ *
+ * Human mode waits by default, because "it is not ready yet" is an implementation detail nobody
+ * asked to manage. JSON mode does NOT, because scripts already written against the old
+ * fire-and-forget behaviour must not silently start blocking for minutes. Either default is
+ * overridden by saying so explicitly.
+ *
+ * Read from `process.argv` rather than commander's parsed value: declaring `--no-wait` makes
+ * commander default `opts.wait` to true, which erases the distinction between "defaulted" and
+ * "asked for" — and that distinction is the whole rule.
+ */
+export function resolveWait(argv = process.argv) {
+    if (argv.includes('--no-wait'))
+        return false;
+    if (argv.includes('--wait'))
+        return true;
+    return !isJsonMode();
+}
+/**
+ * Validate `--timeout` and `--poll-interval` BEFORE any network call.
+ *
+ * Checking after would mean a typo'd timeout had already opened an intent that the user then has
+ * to wait out or abandon — the same reasoning `certen fund` applies to its own options.
+ */
+export function parseWaitBudget(timeout, pollInterval, defaults) {
+    const timeoutMin = timeout === undefined ? defaults.timeoutMin : Number(timeout);
+    if (!Number.isFinite(timeoutMin) || timeoutMin <= 0) {
+        throw new UsageError('--timeout must be a positive number of minutes', 'INVALID_TIMEOUT');
+    }
+    const intervalSec = pollInterval === undefined ? defaults.intervalSec : Number(pollInterval);
+    if (!Number.isFinite(intervalSec) || intervalSec <= 0) {
+        throw new UsageError('--poll-interval must be a positive number of seconds', 'INVALID_POLL_INTERVAL');
+    }
+    return { timeoutMs: timeoutMin * 60_000, intervalMs: intervalSec * 1_000 };
+}
+/**
+ * Statuses `POST /v1/identity` provisioning settles into.
+ *
+ * The gateway writes `active` or `error` (identity.orchestrator.ts). Anything else is treated as
+ * still in flight, which is the safe direction: waiting longer for an unrecognised status costs
+ * time, whereas calling it terminal would report an identity ready that never became one.
+ */
+const IDENTITY_IN_FLIGHT = ['provisioning', 'pending', 'creating'];
+function isTerminalIdentityStatus(status) {
+    return !IDENTITY_IN_FLIGHT.includes(status);
+}
+/** Say it once, when it changes — a five-minute wait should not be a wall of identical lines. */
+function progress() {
+    let last = '';
+    return (message) => {
+        if (isJsonMode() || message === last)
+            return;
+        last = message;
+        human(`  ${message}`);
+    };
+}
+/**
+ * Poll an identity until it is genuinely usable.
+ *
+ * "Usable" is `status` terminal AND `can_sign === true`, and those are two separate conditions
+ * that fail for different reasons:
+ *
+ * - `can_sign === false` — provisioning finished but the key on the on-chain key page is not
+ *   yours. The identity exists, consumes quota, and can never sign.
+ * - `can_sign === null` — the key page could not be READ. That is unknown, not a soft yes; an
+ *   Accumulate outage is exactly when this distinction matters most. Reporting it as ready would
+ *   be the one wrong answer, so this keeps polling and, if the budget runs out, says plainly that
+ *   it could not determine the answer.
+ */
+export async function waitForIdentity(client, id, budget) {
+    const say = progress();
+    const deadline = Date.now() + budget.timeoutMs;
+    let last;
+    say('Provisioning. This takes a minute or two on Accumulate.');
+    while (Date.now() < deadline) {
+        // The response IS the identity — the gateway no longer nests it under an `identity` key.
+        const identity = await client.identity.get(id);
+        last = identity;
+        say(`Status: ${identity.status}.`);
+        if (isTerminalIdentityStatus(identity.status)) {
+            if (identity.can_sign === true)
+                return identity;
+            if (identity.can_sign === false) {
+                throw new CliError(`Identity ${id} finished provisioning as "${identity.status}" but cannot sign — its key `
+                    + 'page is not held by your key. It will fail at the signing step of every flow.'
+                    + (identity.error_message ? ` Gateway said: ${identity.error_message}` : ''), 'IDENTITY_CANNOT_SIGN', EXIT.FAILED);
+            }
+            if (identity.status === 'error') {
+                throw new CliError(`Identity ${id} failed to provision.`
+                    + (identity.error_message ? ` ${identity.error_message}` : ' The gateway gave no reason.'), 'IDENTITY_PROVISIONING_FAILED', EXIT.FAILED);
+            }
+            // Terminal status, can_sign null: the key page could not be read. Keep asking — this is
+            // usually transient — and fall through to the unknown-answer error if it never resolves.
+            say(`Status: ${identity.status}, waiting on the key page to confirm it holds your key.`);
+        }
+        await sleep(budget.intervalMs);
+    }
+    const minutes = Math.round(budget.timeoutMs / 60_000);
+    if (last && isTerminalIdentityStatus(last.status) && last.can_sign == null) {
+        throw new CliError(`Identity ${id} is "${last.status}" but whether it can sign could not be determined — the `
+            + 'on-chain key page was unreadable for the whole wait. The identity may be fine; Accumulate '
+            + `may not be. Check again: certen identity get ${id}`, 'IDENTITY_CAN_SIGN_UNKNOWN', EXIT.FAILED);
+    }
+    // Neither success nor failure: provisioning may still complete. Say which it is, and do not
+    // exit 0 — a script must not read "still working" as "ready".
+    throw new CliError(`Identity ${id} is still "${last?.status ?? 'unknown'}" after ${minutes} min. It may yet `
+        + `finish. Check with: certen identity get ${id}`, 'IDENTITY_WAIT_TIMEOUT', EXIT.FAILED);
+}
+/**
+ * Poll a transaction intent to a terminal state.
+ *
+ * Delegates to the SDK's `execute.wait()` rather than re-implementing the loop, so the CLI and an
+ * SDK caller agree on which statuses are terminal. The SDK signals both failure and timeout by
+ * throwing a plain `Error`; those are translated here into typed CLI errors so the exit code and
+ * the `--json` envelope carry a code a caller can branch on.
+ */
+export async function waitForTransaction(client, intentId, budget) {
+    const say = progress();
+    say('Waiting for the proof cycle. This is 60-110 seconds of real validator work.');
+    try {
+        const result = await client.execute.wait(intentId, {
+            timeoutMs: budget.timeoutMs,
+            intervalMs: budget.intervalMs,
+            onPoll: (tx) => {
+                const status = tx.status;
+                if (status)
+                    say(`Status: ${status}.`);
+            },
+        });
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // "still <status> after <n>ms" is the SDK's timeout wording. A timeout is not a failed intent
+        // — it may still complete — and conflating the two would tell a user their work was lost.
+        const timedOut = /still .* after \d+ms/.test(message);
+        throw new CliError(timedOut
+            ? `${message.replace(/^certen: /, '')}. It may yet complete. Check with: certen tx status ${intentId}`
+            : message.replace(/^certen: /, ''), timedOut ? 'TX_WAIT_TIMEOUT' : 'TX_FAILED', EXIT.FAILED);
+    }
+}
+//# sourceMappingURL=wait.js.map

package/dist/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AAEH,mGAAmG;AACnG,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAC/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAEzD,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAExF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,OAAiB,OAAO,CAAC,IAAI;IACvD,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,CAAC,UAAU,EAAE,CAAC;AACvB,CAAC;AAID;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA2B,EAC3B,YAAgC,EAChC,QAAqD;IAErD,MAAM,UAAU,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,UAAU,CAAC,gDAAgD,EAAE,iBAAiB,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,WAAW,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC7F,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,UAAU,CAAC,sDAAsD,EAAE,uBAAuB,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,UAAU,GAAG,MAAM,EAAE,UAAU,EAAE,WAAW,GAAG,KAAK,EAAE,CAAC;AAC7E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG,CAAC,cAAc,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AAEnE,SAAS,wBAAwB,CAAC,MAAc;IAC9C,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED,iGAAiG;AACjG,SAAS,QAAQ;IACf,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,OAAe,EAAE,EAAE;QACzB,IAAI,UAAU,EAAE,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO;QAC7C,IAAI,GAAG,OAAO,CAAC;QACf,KAAK,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAoB,EACpB,EAAU,EACV,MAAkB;IAElB,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC;IAC/C,IAAI,IAA0B,CAAC;IAE/B,GAAG,CAAC,yDAAyD,CAAC,CAAC;IAE/D,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,yFAAyF;QACzF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/C,IAAI,GAAG,QAAQ,CAAC;QAChB,GAAG,CAAC,WAAW,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QAEnC,IAAI,wBAAwB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9C,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI;gBAAE,OAAO,QAAQ,CAAC;YAEhD,IAAI,QAAQ,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;gBAChC,MAAM,IAAI,QAAQ,CAChB,YAAY,EAAE,8BAA8B,QAAQ,CAAC,MAAM,8BAA8B;sBACvF,+EAA+E;sBAC/E,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,kBAAkB,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAC5E,sBAAsB,EACtB,IAAI,CAAC,MAAM,CACZ,CAAC;YACJ,CAAC;YAED,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;gBAChC,MAAM,IAAI,QAAQ,CAChB,YAAY,EAAE,uBAAuB;sBACnC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,8BAA8B,CAAC,EAC1F,8BAA8B,EAC9B,IAAI,CAAC,MAAM,CACZ,CAAC;YACJ,CAAC;YACD,wFAAwF;YACxF,yFAAyF;YACzF,GAAG,CAAC,WAAW,QAAQ,CAAC,MAAM,yDAAyD,CAAC,CAAC;QAC3F,CAAC;QAED,MAAM,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;IAEtD,IAAI,IAAI,IAAI,wBAAwB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;QAC3E,MAAM,IAAI,QAAQ,CAChB,YAAY,EAAE,QAAQ,IAAI,CAAC,MAAM,0DAA0D;cACzF,4FAA4F;cAC5F,gDAAgD,EAAE,EAAE,EACtD,2BAA2B,EAC3B,IAAI,CAAC,MAAM,CACZ,CAAC;IACJ,CAAC;IAED,4FAA4F;IAC5F,8DAA8D;IAC9D,MAAM,IAAI,QAAQ,CAChB,YAAY,EAAE,cAAc,IAAI,EAAE,MAAM,IAAI,SAAS,WAAW,OAAO,mBAAmB;UACxF,2CAA2C,EAAE,EAAE,EACjD,uBAAuB,EACvB,IAAI,CAAC,MAAM,CACZ,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAoB,EACpB,QAAgB,EAChB,MAAkB;IAElB,MAAM,GAAG,GAAG,QAAQ,EAAE,CAAC;IACvB,GAAG,CAAC,6EAA6E,CAAC,CAAC;IAEnF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE;YACjD,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;gBACb,MAAM,MAAM,GAAI,EAAqC,CAAC,MAAM,CAAC;gBAC7D,IAAI,MAAM;oBAAE,GAAG,CAAC,WAAW,MAAM,GAAG,CAAC,CAAC;YACxC,CAAC;SACF,CAAC,CAAC;QACH,OAAO,MAA4C,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,8FAA8F;QAC9F,0FAA0F;QAC1F,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,IAAI,QAAQ,CAChB,QAAQ;YACN,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,uDAAuD,QAAQ,EAAE;YACtG,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,EACpC,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,WAAW,EAC1C,IAAI,CAAC,MAAM,CACZ,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@certen.io/cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Command line for the CERTEN Gateway API",
   "license": "MIT",
   "type": "module",
@@ -33,19 +33,20 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "node ../../scripts/build-package.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "//prepack": "Build before packing so the published bin can never point at a missing dist/index.js.",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "node ../../scripts/prepublish-check.mjs",
+    "//build": "dist/ is gitignored and tsc does not prune outputs whose source was deleted, so a stale artifact survives forever locally and ships on a local publish. CI never sees it. Clean first so both produce the same tarball."
   },
   "publishConfig": {
     "access": "public"
   },
   "//dependencies": "@certen.io/sdk MUST be a version range, not file:../sdk. A published package carrying a file: dependency installs and then fails to resolve on the consumer's machine, because that path does not exist there. Local development uses `npm link` or a workspace instead.",
   "dependencies": {
-    "@certen.io/sdk": "^0.5.0",
+    "@certen.io/sdk": "^0.7.0",
     "commander": "^12.0.0"
   },
   "devDependencies": {