@run402/sdk 4.126.1 → 4.126.3

package/dist/node/actions-node.js

@@ -128,7 +128,7 @@ export class NodeActions {
         }
         const tier = input.tier ?? DEFAULT_BOOTSTRAP_TIER;
         if (run.autoPrerequisites) {
-            await this.#ensureCloudTier(run, tier);
+            await this.#ensureCloudTier(run, tier, { explicitTier: input.tier !== undefined });
         }
         const idempotencyKey = input.idempotencyKey ?? run.rootIdempotencyKey;
         const step = run.addStep({
@@ -280,7 +280,7 @@ export class NodeActions {
             });
         }
         else if (this.#targetKind() !== "core") {
-            await this.#ensureCloudTier(run, input.tier ?? DEFAULT_BOOTSTRAP_TIER);
+            await this.#ensureCloudTier(run, input.tier ?? DEFAULT_BOOTSTRAP_TIER, { explicitTier: input.tier !== undefined });
         }
         else {
             run.skipStep({
@@ -1122,7 +1122,7 @@ export class NodeActions {
                 app_result: blocked,
             });
         }
-        await this.#ensureCloudTier(run, input.tier ?? DEFAULT_BOOTSTRAP_TIER);
+        await this.#ensureCloudTier(run, input.tier ?? DEFAULT_BOOTSTRAP_TIER, { explicitTier: input.tier !== undefined });
         const resolved = await this.#resolveProject(input, manifest, workspaceDir, run);
         await this.#recordAppInstallState({
             projectId: resolved.projectId,
@@ -1720,8 +1720,15 @@ export class NodeActions {
             propagationWaitMs,
         };
     }
+    /**
+     * Ensure a local wallet exists and, with `fund`, that it holds testnet USDC.
+     * Returns `funded` when this call dripped the faucet, and `planned` when a
+     * dry run planned a wallet that does not exist yet (so nothing about its
+     * organization can be read).
+     */
     async #ensureWallet(run, opts = { fund: false }) {
         const status = await this.sdk.wallets.status();
+        let balanceUnknown = false;
         if (status.configured) {
             run.skipStep({
                 action: "wallets.create",
@@ -1731,8 +1738,19 @@ export class NodeActions {
                 details: { address: status.address, path: status.path ?? null },
             });
             if (!opts.fund)
-                return false;
-            const balance = await prototypeBalance(status.address);
+                return { funded: false, planned: false };
+            let balance;
+            try {
+                balance = await prototypeBalance(status.address);
+            }
+            catch (err) {
+                // A dry run only describes; an unreadable balance plans the faucet
+                // instead of failing the plan. Execution still refuses to guess.
+                if (!run.dryRun)
+                    throw err;
+                balance = 0n;
+                balanceUnknown = true;
+            }
             if (balance > 0n) {
                 run.skipStep({
                     action: "wallets.faucet",
@@ -1741,7 +1759,7 @@ export class NodeActions {
                     auto: true,
                     details: { address: status.address, balance_usd_micros: balance.toString() },
                 });
-                return false;
+                return { funded: false, planned: false };
             }
         }
         else {
@@ -1754,7 +1772,7 @@ export class NodeActions {
             await run.approve(createStep, ["wallets.create"], "Create a local wallet.");
             if (run.dryRun) {
                 run.setState(createStep, "planned");
-                return false;
+                return { funded: false, planned: true };
             }
             run.setState(createStep, "running");
             const created = await this.sdk.wallets.create();
@@ -1763,7 +1781,7 @@ export class NodeActions {
                 path: created.path ?? null,
             });
             if (!opts.fund)
-                return false;
+                return { funded: false, planned: false };
         }
         const faucetKey = run.childKey("wallets.faucet");
         const faucetStep = run.addStep({
@@ -1771,12 +1789,16 @@ export class NodeActions {
             description: "Request testnet faucet funds for wallet",
             mutation: true,
             auto: true,
-            details: { idempotency_key: faucetKey ?? null },
+            details: {
+                idempotency_key: faucetKey ?? null,
+                ...(opts.reason ? { reason: opts.reason } : {}),
+                ...(balanceUnknown ? { balance: "unknown" } : {}),
+            },
         });
         await run.approve(faucetStep, ["wallets.faucet"], "Request testnet USDC for the local wallet.");
         if (run.dryRun) {
             run.setState(faucetStep, "planned");
-            return false;
+            return { funded: false, planned: false };
         }
         run.setState(faucetStep, "running");
         const faucet = await this.sdk.wallets.faucet(faucetKey ? { idempotencyKey: faucetKey } : {});
@@ -1785,75 +1807,134 @@ export class NodeActions {
             amount: faucet.amount,
             network: faucet.network,
         });
-        return true;
+        return { funded: true, planned: false };
     }
-    async #ensureCloudTier(run, desiredTier) {
-        await this.#ensureWallet(run, { fund: false });
-        if (run.dryRun) {
-            const faucetStep = run.addStep({
-                action: "wallets.faucet",
-                description: "Request testnet faucet funds if tier payment is needed",
-                mutation: true,
-                auto: true,
-            });
-            await run.approve(faucetStep, ["wallets.faucet"], "Request testnet USDC if tier bootstrap needs payment.");
-            run.setState(faucetStep, "planned");
-            const step = run.addStep({
-                action: Run402Action.TierSet,
-                description: `Ensure active ${desiredTier} tier`,
-                mutation: true,
-                auto: true,
-                details: {
-                    tier: desiredTier,
-                    idempotency_key: run.childKey("tier.set") ?? null,
-                    reason: "dry_run",
-                },
+    /**
+     * Bootstrap readiness: make sure the caller's organization holds a tier at
+     * least `desiredTier`. A dry run resolves this against the real organization
+     * exactly as execution does (one read of `GET /tiers/v1/status`), so a plan
+     * never lists a purchase that execution would skip. Bootstrap never buys a
+     * tier lower than the organization's current one unless the caller named
+     * that tier explicitly (`explicitTier`).
+     */
+    async #ensureCloudTier(run, desiredTier, opts = {}) {
+        const wallet = await this.#ensureWallet(run, { fund: false });
+        const idempotencyKey = run.childKey("tier.set");
+        if (wallet.planned) {
+            // Dry run, no local wallet yet: a new wallet has no organization and no
+            // tier, so bootstrap would fund it and start the tier.
+            const reason = "new wallet has no tier";
+            await this.#planFaucet(run, reason);
+            await this.#planTierPurchase(run, desiredTier, {
+                description: `Start the ${desiredTier} tier`,
+                details: { tier: desiredTier, current_tier: null, active: false, reason, idempotency_key: idempotencyKey ?? null },
             });
-            await run.approve(step, ["tier.set"], `Set the ${desiredTier} tier if no active tier exists.`);
-            run.setState(step, "planned");
             return;
         }
-        let status;
+        let status = null;
+        let statusError = null;
         try {
             status = await this.sdk.tier.status();
         }
-        catch {
-            status = null;
+        catch (err) {
+            statusError = err;
+        }
+        if (!status) {
+            const error = statusError instanceof Error ? statusError.message : String(statusError);
+            if (run.dryRun) {
+                const reason = "tier status unavailable";
+                await this.#planFaucet(run, reason);
+                await this.#planTierPurchase(run, desiredTier, {
+                    description: `Set the ${desiredTier} tier if the organization has no tier at least ${desiredTier} (current tier unknown)`,
+                    details: { tier: desiredTier, current_tier: "unknown", reason, error, idempotency_key: idempotencyKey ?? null },
+                });
+                return;
+            }
+            // Paying blind could replace a higher tier the organization already holds.
+            throw run.error(`Could not read the organization's tier (GET /tiers/v1/status failed: ${error}). Bootstrap does not buy a tier without knowing the current one.`, "RUN402_TIER_STATUS_UNAVAILABLE", {
+                desired_tier: desiredTier,
+                error,
+                next_actions: [{
+                        type: "check_usage",
+                        command: "run402 tier status",
+                        argv: ["run402", "tier", "status"],
+                        why: "Confirm the organization's current tier, then retry.",
+                    }],
+            });
         }
-        const current = normalizeTier(status?.tier);
-        if (status?.active && current && TIER_RANK[current] >= TIER_RANK[desiredTier]) {
+        const current = normalizeTier(status.tier);
+        const facts = {
+            current_tier: current ?? status.tier ?? null,
+            desired_tier: desiredTier,
+            active: status.active,
+            lease_perpetual: status.lease_perpetual ?? null,
+            lease_expires_at: status.lease_expires_at ?? null,
+        };
+        if (status.active && current && TIER_RANK[current] >= TIER_RANK[desiredTier]) {
+            const reason = `org has active ${current} tier`;
             run.skipStep({
-                action: Run402Action.TierSet,
-                description: "Active tier already satisfies bootstrap requirement",
+                action: "wallets.faucet",
+                description: `Faucet not needed: ${reason}`,
                 mutation: false,
                 auto: true,
-                details: { current_tier: current, desired_tier: desiredTier },
+                details: { reason },
             });
-            return;
-        }
-        if (status?.active && current && TIER_RANK[current] > TIER_RANK[desiredTier]) {
             run.skipStep({
                 action: Run402Action.TierSet,
-                description: "Existing active tier is higher than bootstrap default",
+                description: current === desiredTier
+                    ? `Active ${current} tier already in place`
+                    : `Active ${current} tier already satisfies the ${desiredTier} requirement`,
                 mutation: false,
                 auto: true,
-                details: { current_tier: current, desired_tier: desiredTier },
+                details: { reason, ...facts },
             });
             return;
         }
-        const idempotencyKey = run.childKey("tier.set");
-        const justFunded = await this.#ensureWallet(run, { fund: true });
+        if (current && TIER_RANK[current] > TIER_RANK[desiredTier] && !opts.explicitTier) {
+            // The organization's higher tier has lapsed. Buying the default lower
+            // tier would replace it; that takes an explicit choice.
+            const retryVerb = run.input.type === Run402Action.ProjectsProvision
+                ? ["run402", "projects", "provision"]
+                : ["run402", "up"];
+            throw run.error(`The organization's ${current} tier is not active. Bootstrap will not replace it with the lower default ${desiredTier} tier. Renew ${current}, or pass the tier explicitly to accept ${desiredTier}.`, "RUN402_TIER_DOWNGRADE_REFUSED", {
+                ...facts,
+                next_actions: [
+                    {
+                        type: "renew_tier",
+                        command: `run402 tier set ${current}`,
+                        argv: ["run402", "tier", "set", current],
+                        why: `Renew the organization's ${current} tier, then retry.`,
+                    },
+                    {
+                        type: "retry",
+                        command: `${retryVerb.join(" ")} --tier ${desiredTier}`,
+                        argv: [...retryVerb, "--tier", desiredTier],
+                        why: `Accept the lower ${desiredTier} tier explicitly.`,
+                    },
+                ],
+            });
+        }
+        const description = !current
+            ? `Start the ${desiredTier} tier`
+            : current === desiredTier
+                ? `Renew the ${desiredTier} tier (current lease is not active)`
+                : TIER_RANK[current] < TIER_RANK[desiredTier]
+                    ? `Upgrade tier from ${current} to ${desiredTier}`
+                    : `Set the ${desiredTier} tier as requested (current ${current} tier is not active)`;
+        const reason = !current ? "org has no tier" : status.active ? `org has active ${current} tier` : `org's ${current} tier is not active`;
+        const details = { tier: desiredTier, ...facts, reason, idempotency_key: idempotencyKey ?? null };
+        if (run.dryRun) {
+            await this.#ensureWallet(run, { fund: true, reason: "tier payment may be needed" });
+            await this.#planTierPurchase(run, desiredTier, { description, details });
+            return;
+        }
+        const { funded: justFunded } = await this.#ensureWallet(run, { fund: true });
         const step = run.addStep({
             action: Run402Action.TierSet,
-            description: `Ensure active ${desiredTier} tier`,
+            description,
             mutation: true,
             auto: true,
-            details: {
-                tier: desiredTier,
-                current_tier: current ?? null,
-                active: status?.active ?? null,
-                idempotency_key: idempotencyKey ?? null,
-            },
+            details,
         });
         await run.approve(step, ["tier.set"], `Set the ${desiredTier} tier (start, renew, or upgrade).`);
         run.setState(step, "running");
@@ -1861,6 +1942,28 @@ export class NodeActions {
         const result = await (justFunded ? afterFaucet(pay) : pay());
         run.setState(step, "succeeded", { tier: result.tier, action: result.action });
     }
+    async #planFaucet(run, reason) {
+        const step = run.addStep({
+            action: "wallets.faucet",
+            description: "Request testnet faucet funds if tier payment is needed",
+            mutation: true,
+            auto: true,
+            details: { reason },
+        });
+        await run.approve(step, ["wallets.faucet"], "Request testnet USDC if tier bootstrap needs payment.");
+        run.setState(step, "planned");
+    }
+    async #planTierPurchase(run, desiredTier, plan) {
+        const step = run.addStep({
+            action: Run402Action.TierSet,
+            description: plan.description,
+            mutation: true,
+            auto: true,
+            details: plan.details,
+        });
+        await run.approve(step, ["tier.set"], `Set the ${desiredTier} tier (start, renew, or upgrade).`);
+        run.setState(step, "planned");
+    }
     async #resolveProject(input, manifest, workspaceDir, run) {
         const linkPath = join(workspaceDir, ".run402", "project.json");
         const link = await readWorkspaceProjectLink(linkPath);