@typesol/cli 0.25.0 → 0.27.0

package/dist/compiler/emit/calls.js

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { calleeName, resolveScalarType, resolveValueType } from "../analyze.js";
+import { calleeName, discriminator, resolveScalarType, resolveValueType, snakeCase } from "../analyze.js";
 import { ANCHOR_ERRORS } from "../anchor-errors.js";
 import { decodeAddress } from "../../keys.js";
 import { INT_INFO, INT_NAMES, isScalar, isWritable, sameType, scalarSize, typeName, } from "../model.js";
@@ -21,6 +21,11 @@ export class CallEmitter extends ExpressionEmitter {
             return this.cast(args[0], { kind: "int", name: builtin });
         }
         switch (builtin) {
+            case "stackHeight": {
+                if (args.length)
+                    this.fail(node, "stackHeight() takes no arguments");
+                return { c: "sol_get_stack_height()", type: U64 };
+            }
             case "require": {
                 if (args.length !== 2)
                     this.fail(node, "require(condition, error) takes two arguments");
@@ -484,6 +489,9 @@ export class CallEmitter extends ExpressionEmitter {
             return this.callHelper(node, helper);
         if (ts.isPropertyAccessExpression(callee)) {
             const method = callee.name.text;
+            const introspected = this.instructionsCall(node, callee, method);
+            if (introspected)
+                return introspected;
             // xs.some(…) and friends on a Vec, FixedArray, FixedVec or Vec argument: a loop with the callback expanded in it.
             if (LIST_METHODS.has(method)) {
                 const l = ts.isIdentifier(callee.expression) ? this.lookup(callee.expression.text) : undefined;
@@ -570,6 +578,8 @@ export class CallEmitter extends ExpressionEmitter {
                     return target.kind.kind === "token" && target.constraints.ata ? this.createAta(node, target, topLevel) : this.createToken(node, target, topLevel);
                 if (target?.kind.kind === "init" && method === "create")
                     return this.create(node, target, topLevel);
+                if (target?.kind.kind === "migrate" && method === "migrate")
+                    return this.migrate(node, target, topLevel);
                 if (target?.kind.kind === "initIfNeeded" && method === "createIfNeeded")
                     return this.create(node, target, topLevel, true);
                 if (target?.kind.kind === "system" && method === "transfer")
@@ -878,6 +888,92 @@ export class CallEmitter extends ExpressionEmitter {
         return ts.isCallExpression(node) && this.exportName(node.expression) === "remainingAccounts";
     }
     /** C pointer (`TsAccount *`) for an expression naming a remaining account, or undefined. */
+    /** Whether `node` is an InstructionsSysvar parameter. */
+    instructionsParam(node) {
+        const a = ts.isIdentifier(node) ? this.accounts.get(node.text) : undefined;
+        return a?.kind.kind === "instructionsSysvar" ? a : undefined;
+    }
+    /** Whether `node` is a TransactionInstruction: a local holding one, or `ixs.get(i)`. */
+    isTxIx(node) {
+        if (ts.isParenthesizedExpression(node))
+            return this.isTxIx(node.expression);
+        if (ts.isIdentifier(node))
+            return this.lookup(node.text)?.type.kind === "txIx";
+        return (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === "get" &&
+            !!this.instructionsParam(node.expression.expression));
+    }
+    /**
+     * InstructionsSysvar.currentIndex() / .get(i) and the methods of a TransactionInstruction: bounds-checked reads of the
+     * sysvar (ts_ix_* in the runtime). Undefined when the call is something else.
+     */
+    instructionsCall(node, callee, method) {
+        const args = node.arguments;
+        const sysvar = this.instructionsParam(callee.expression);
+        if (sysvar) {
+            this.assertUsable(sysvar, callee.expression);
+            if (method === "currentIndex") {
+                if (args.length)
+                    this.fail(node, "currentIndex() takes no arguments");
+                const t = this.tmp("ixi");
+                this.line(`uint64_t ${t};`);
+                this.line(`TS_TRY(ts_ix_current(a_${sysvar.name}, &${t}));`);
+                return { c: t, type: U64 };
+            }
+            if (method === "get") {
+                if (args.length !== 1)
+                    this.fail(node, "get(index) takes the instruction's index");
+                const i = this.expect(this.expr(args[0], U64), U64, args[0]);
+                const t = this.tmp("ix");
+                this.line(`TsIx ${t};`);
+                this.line(`TS_TRY(ts_ix_load(a_${sysvar.name}, ${i.c}, &${t}));`);
+                return { c: t, type: { kind: "txIx" } };
+            }
+            this.fail(node, "the Instructions sysvar has .length, currentIndex() and get(index)");
+        }
+        if (!this.isTxIx(callee.expression))
+            return undefined;
+        const ix = this.expr(callee.expression);
+        const one = (what) => {
+            if (args.length !== 1)
+                this.fail(node, `${method}(${what}) takes one argument`);
+            return this.expect(this.expr(args[0], U64), U64, args[0]).c;
+        };
+        if (method === "accountKey" || method === "accountIsSigner" || method === "accountIsWritable") {
+            const i = one("i");
+            const t = this.tmp("ixa");
+            this.line(`const uint8_t *${t};`);
+            this.line(`TS_TRY(ts_ix_account(&${ix.c}, ${i}, &${t}));`);
+            if (method === "accountKey")
+                return { c: `((const SolPubkey *)(${t} + 1))`, type: PUBKEY };
+            return { c: `((${t}[0] & ${method === "accountIsSigner" ? 1 : 2}) != 0)`, type: BOOL };
+        }
+        const reads = {
+            readU8: ["uint8_t", U8],
+            readU16: ["uint16_t", { kind: "int", name: "u16" }],
+            readU32: ["uint32_t", { kind: "int", name: "u32" }],
+            readU64: ["uint64_t", U64],
+            readPubkey: ["SolPubkey", PUBKEY],
+        };
+        if (reads[method]) {
+            const [c, type] = reads[method];
+            const off = one("offset");
+            const t = this.tmp("ixr");
+            this.line(`${c} ${t};`);
+            this.line(`TS_TRY(ts_ix_read(&${ix.c}, ${off}, sizeof(${c}), &${t}));`);
+            return type.kind === "pubkey" ? { c: `(&${t})`, type } : { c: t, type };
+        }
+        if (method === "is") {
+            if (args.length !== 2 || !ts.isStringLiteralLike(args[1]))
+                this.fail(node, 'is(program, "instruction_name") takes the program and the instruction name as a string literal');
+            const program = this.expect(this.expr(args[0], PUBKEY), PUBKEY, args[0]);
+            const disc = this.tmp("disc");
+            this.line(`static const uint8_t ${disc}[8] = ${cBytes(discriminator(`global:${snakeCase(args[1].text)}`))};`);
+            return { c: `ts_ix_is(&${ix.c}, ${program.c}, ${disc})`, type: BOOL };
+        }
+        this.fail(node, "a TransactionInstruction has programId, accountsLength, dataLength, accountKey/accountIsSigner/accountIsWritable(i), readU8/U16/U32/U64/readPubkey(offset) and is(program, name)");
+    }
     handle(node) {
         if (ts.isParenthesizedExpression(node))
             return this.handle(node.expression);
@@ -984,6 +1080,38 @@ export class CallEmitter extends ExpressionEmitter {
         }
         return { c: `((TSS_${s.name} *)(${h}->data + 8))`, type: { kind: "structRef", struct: s.name, writable: mut } };
     }
+    /**
+     * `acct.migrate(payer, value)` on a Migrate<From, To> account: the new value is built in full first (it may read
+     * acct.from, whose bytes the rewrite overwrites), then the account is resized (the payer tops up the rent when it
+     * grows; shrinking keeps the lamports) and rewritten with To's discriminator and the value.
+     */
+    migrate(node, a, topLevel) {
+        const k = a.kind;
+        const call = `${a.name}.migrate`;
+        if (!topLevel)
+            this.fail(node, `${call}(…) must be a top-level statement of the instruction`);
+        if (this.created.has(a.name))
+            this.fail(node, `${a.name} is already migrated`);
+        if (node.arguments.length !== 2)
+            this.fail(node, `${call}(payer, value) takes the payer and the new ${k.to.name}`);
+        const payer = this.accountParam(node.arguments[0], "the payer");
+        if (payer.kind.kind !== "signer" || !payer.kind.mut)
+            this.fail(node.arguments[0], "the payer must be a Mut<Signer>");
+        this.assertNotAliased([a.name], node, "migrate");
+        const To = k.to.name;
+        const tmp = this.tmp("next");
+        this.line(`TSS_${To} *${tmp} = NULL;`);
+        this.line(`TS_TRY(ts_alloc(sizeof(TSS_${To}), (uint8_t **)&${tmp}));`);
+        this.writeAggregate({ lv: `(*${tmp})`, type: { kind: "struct", name: To }, writable: true }, node.arguments[1]);
+        this.line(`TS_TRY(ts_resize(params, a_${payer.name}, a_${a.name}, 8 + sizeof(TSS_${To}), entry_${a.name}));`);
+        this.line(`ts_memcpy(a_${a.name}->data, TS_DISC_${To}, 8);`);
+        this.line(`ts_memcpy(a_${a.name}->data + 8, ${tmp}, sizeof(TSS_${To}));`);
+        this.line(`TSS_${To} *dt_${a.name} = (TSS_${To} *)(a_${a.name}->data + 8);`);
+        this.line(`(void)dt_${a.name};`);
+        this.created.add(a.name);
+        this.pendingInit.delete(a.name);
+        return undefined;
+    }
     /** Whether a helper (or one it calls) grows a Vec, which needs the instruction's SystemProgram for rent. */
     helperGrows(body, seen = new Set()) {
         if (seen.has(body))

package/dist/compiler/emit/expressions.js

@@ -265,6 +265,14 @@ export class ExpressionEmitter extends StorageEmitter {
         if (field === "length") {
             if (this.isRemaining(node.expression))
                 return { c: `((uint64_t)(params->ka_num - ${this.ix.accounts.length}))`, type: U64 };
+            const sysvar = this.instructionsParam(node.expression);
+            if (sysvar) {
+                this.assertUsable(sysvar, node.expression);
+                const t = this.tmp("ixn");
+                this.line(`uint64_t ${t};`);
+                this.line(`TS_TRY(ts_ix_count(a_${sysvar.name}, &${t}));`);
+                return { c: t, type: U64 };
+            }
             // The number of elements a map / filter chain gives: counted, nothing stored.
             if (this.isPipeline(node.expression)) {
                 const n = this.tmp("count");
@@ -284,6 +292,16 @@ export class ExpressionEmitter extends StorageEmitter {
             }
             this.fail(node, "use byteLength(s) for strings; .length is available on arrays, Vecs and remainingAccounts()");
         }
+        if (this.isTxIx(node.expression)) {
+            const ix = this.expr(node.expression);
+            if (field === "programId")
+                return { c: `(${ix.c}.program_id)`, type: PUBKEY };
+            if (field === "accountsLength")
+                return { c: `((uint64_t)${ix.c}.num_accounts)`, type: U64 };
+            if (field === "dataLength")
+                return { c: `((uint64_t)${ix.c}.data_len)`, type: U64 };
+            this.fail(node.name, `a TransactionInstruction has programId, accountsLength and dataLength, not ${field}`);
+        }
         const h = this.handle(node.expression);
         if (h) {
             switch (field) {

package/dist/compiler/emit/function.js

@@ -90,6 +90,9 @@ export class FunctionEmitter extends StatementEmitter {
                 }
                 head.push(`  TS_TRY(ts_check_executable(${v}));`);
             }
+            // Migrate<From, To>: an existing From account (owner, discriminator, size), kept to be rewritten as To.
+            if (k.kind === "migrate")
+                head.push(`  TS_TRY(ts_check_program_account(${v}, params->program_id, TS_DISC_${k.from.name}, sizeof(TSS_${k.from.name})));`, `  const TSS_${k.from.name} *df_${a.name} = (const TSS_${k.from.name} *)(${v}->data + 8);`, `  uint64_t entry_${a.name} = ${v}->data_len;`);
             if (k.kind === "zeroed")
                 head.push(`  TS_TRY(ts_init_zeroed(${v}, params->program_id, TS_DISC_${k.struct.name}, sizeof(TSS_${k.struct.name})));`);
             if (k.kind === "initIfNeeded" && k.struct.vec)
@@ -152,9 +155,30 @@ export class FunctionEmitter extends StatementEmitter {
         // The loader passes each account once and marks repeats as duplicates, which share its record (ts_deserialize),
         // so two parameters name the same account exactly when their pointers are equal.
         const writable = ix.accounts.filter((a) => isWritable(a.kind));
+        // Dup<…> (Anchor's `dup`) lifts the check for a pair when both accounts are read and written in place: not created
+        // here, not closed or a close destination, not a @layout borsh heap copy (a lost update when packed back).
+        const closing = new Set(ix.accounts.flatMap((a) => (a.constraints.closeTo ? [a.name, a.constraints.closeTo] : [])));
+        const inPlace = (a) => {
+            const k = a.kind;
+            if (closing.has(a.name))
+                return false;
+            if (k.kind === "account")
+                return k.struct.layout !== "borsh";
+            if (k.kind === "token" || k.kind === "mint")
+                return !k.init;
+            return k.kind === "signer" || k.kind === "info";
+        };
+        for (const a of writable)
+            if (a.constraints.dup && !inPlace(a))
+                this.reporter.fail(a.node, "Dup<…> is for accounts read and written in place: not created, closed, a close destination or @layout borsh");
+        for (const a of ix.accounts)
+            if (a.constraints.dup && !isWritable(a.kind))
+                this.reporter.fail(a.node, "Dup<…> lets a writable account alias another; this one is not writable");
         const pairs = [];
         for (let i = 0; i < writable.length; i++)
             for (let j = i + 1; j < writable.length; j++) {
+                if ((writable[i].constraints.dup || writable[j].constraints.dup) && inPlace(writable[i]) && inPlace(writable[j]))
+                    continue;
                 const present = [writable[i], writable[j]]
                     .filter((a) => a.optional)
                     .map((a) => `a_${a.name} && `)
@@ -331,6 +355,10 @@ export class FunctionEmitter extends StatementEmitter {
         for (const name of this.pendingInit) {
             const k = this.accounts.get(name).kind;
             const a = this.accounts.get(name);
+            if (k.kind === "migrate") {
+                this.reporter.error(a.node, `Migrate account "${name}" is never migrated; call ${name}.migrate(payer, value) (Anchor fails such an instruction with AccountNotMigrated)`);
+                continue;
+            }
             const how = k.kind === "token" && a.constraints.ata
                 ? `${name}.${k.init === "create" ? "create" : "createIfNeeded"}(payer)`
                 : k.kind === "token"

package/dist/compiler/emit/shared.js

@@ -61,6 +61,8 @@ export function valueC(t) {
             return "TS_VecArg";
         case "account":
             return "TsAccount *";
+        case "txIx":
+            return "TsIx";
         case "structRef":
             return `TSS_${t.struct} *`;
         case "enumRef":

package/dist/compiler/emit/storage.js

@@ -277,6 +277,24 @@ export class StorageEmitter extends EmitterBase {
         }
         if (ts.isPropertyAccessExpression(node)) {
             const field = node.name.text;
+            // Migrate<From, To>: acct.from (the old data, read-only, until migrate()) and acct.to (after it).
+            if (ts.isIdentifier(node.expression)) {
+                const m = this.accounts.get(node.expression.text);
+                if (m?.kind.kind === "migrate") {
+                    const migrated = this.created.has(m.name);
+                    if (field === "from") {
+                        if (migrated)
+                            this.fail(node, `${m.name}.from is gone after ${m.name}.migrate(…): read what you need from it before`);
+                        return { lv: `(*df_${m.name})`, type: { kind: "struct", name: m.kind.from.name }, writable: false, account: m, path: ["from"] };
+                    }
+                    if (field === "to") {
+                        if (!migrated)
+                            this.fail(node, `${m.name}.to exists after ${m.name}.migrate(payer, value)`);
+                        return { lv: `(*dt_${m.name})`, type: { kind: "struct", name: m.kind.to.name }, writable: true, account: m, path: ["to"] };
+                    }
+                    this.fail(node.name, `a Migrate account has .from (before migrate), .to (after), key, lamports and migrate(payer, value)`);
+                }
+            }
             // acct.field on a struct account
             if (ts.isIdentifier(node.expression)) {
                 const a = this.accounts.get(node.expression.text);

package/dist/compiler/model.d.ts

@@ -63,6 +63,10 @@ export type ValueType = ScalarType | {
  | {
     kind: "remaining";
 }
+/** One instruction of the transaction (InstructionsSysvar.get(i)): a `TsIx` view into the sysvar. */
+ | {
+    kind: "txIx";
+}
 /** A struct loaded from a remaining account with loadAccount / loadAccountMut. */
  | {
     kind: "structRef";
@@ -190,6 +194,12 @@ export type ParamKind = {
     kind: "zeroed";
     struct: StructDef;
 }
+/** Anchor's Migration<From, To>: an existing `from` account rewritten as `to` by `acct.migrate(payer, value)`. */
+ | {
+    kind: "migrate";
+    from: StructDef;
+    to: StructDef;
+}
 /** `init`: an associated token account this instruction creates (`Ata<Init<TokenAccount>, …>`, create) or creates when
  * missing (`Ata<InitIfNeeded<TokenAccount>, …>`, createIfNeeded); it is a TokenAccount once that call has run. */
  | {
@@ -263,6 +273,8 @@ export interface Constraints {
     };
     /** Executable<A>: the account must be an executable program. */
     executable?: boolean;
+    /** Dup<A> (Anchor's `dup`): may be the same account as another writable parameter (see function.ts). */
+    dup?: boolean;
     /** Close this account into that parameter when the instruction succeeds. */
     closeTo?: string;
     /** Address<A, "base58">: the account must be exactly this address. */

package/dist/compiler/model.js

@@ -20,6 +20,7 @@ export function isWritable(k) {
         case "init":
         case "zeroed":
         case "initIfNeeded":
+        case "migrate":
             return true;
         case "signer":
         case "info":
@@ -67,6 +68,8 @@ export function typeName(t) {
             return "AccountInfo";
         case "remaining":
             return "RemainingAccounts";
+        case "txIx":
+            return "TransactionInstruction";
         case "structRef":
             return t.struct;
     }

package/dist/templates.js

@@ -1,6 +1,6 @@
 // Programs and tests that `typesol init --template <name>` writes. Each test runs its program in LiteSVM and covers its
 // main flow and at least one refused call, so a new project starts from something that passes and shows how to test.
-// The programs are copies of examples/ (test/workspace.test.ts checks they still match).
+// The programs are copies of examples/ (test/cli/workspace.test.ts checks they still match).
 export const TEMPLATE_NAMES = ["counter", "vault", "escrow"];
 /** Every test starts the same way: build the project's program into a LiteSVM with `typesol/testing`. */
 const testFile = (name, o) => `// Runs the program in LiteSVM (an in-process Solana runtime): \`npm test\`.

package/dist/testing.d.ts

@@ -19,7 +19,7 @@
 import anchor, { type Idl } from "@anchor-lang/core";
 import { type Address, type Instruction, type KeyPairSigner } from "@solana/kit";
 import { FailedTransactionMetadata, LiteSVM, TransactionMetadata } from "litesvm";
-import { type SvmConnection, svmConnection } from "./svmrpc.js";
+import { type SvmConnection, svmConnection } from "./tools/svmrpc.js";
 export { type SvmConnection, svmConnection };
 declare const BorshCoder: typeof anchor.BorshCoder;
 type BorshCoder = InstanceType<typeof BorshCoder>;

package/dist/testing.js

@@ -22,7 +22,7 @@ import { FailedTransactionMetadata, LiteSVM } from "litesvm";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { svmConnection } from "./svmrpc.js";
+import { svmConnection } from "./tools/svmrpc.js";
 import { buildWorkspace, findWorkspace } from "./workspace.js";
 export { svmConnection };
 // @anchor-lang/core is CommonJS: Node 22 cannot import its classes by name from an installed ES module.

package/dist/{clientgen.js → tools/clientgen.js}

@@ -18,7 +18,7 @@
  * sanitized comments.
  */
 import { mkdirSync, writeFileSync } from "node:fs";
-import { ANCHOR_ERRORS } from "./compiler/anchor-errors.js";
+import { ANCHOR_ERRORS } from "../compiler/anchor-errors.js";
 import path from "node:path";
 /** An IDL the generator refuses: malformed, unsafe to embed, or older than the 0.30 IDL format. */
 export class ClientIdlError extends Error {

package/dist/tools/doctor.d.ts

@@ -0,0 +1,45 @@
+export declare const INSTALL_AGAVE = "sh -c \"$(curl -sSfL https://release.anza.xyz/stable/install)\"";
+export interface Check {
+    ok: boolean;
+    /** A missing optional piece (the Solana CLI is only needed to deploy). */
+    optional?: boolean;
+    what: string;
+    detail: string;
+    fix?: string[];
+}
+/** The platform-tools the compiler needs: found, or what to run. */
+export declare function toolchainCheck(): Check;
+/** json_rpc_url / keypair_path from a Solana CLI config (the given file, or the CLI's default one). */
+export declare function solanaConfig(file?: string): {
+    url?: string;
+    keypair?: string;
+    file: string;
+    exists: boolean;
+};
+/** The Solana CLI's cluster monikers, as `solana --url` accepts them; anything else is used as given. */
+export declare function clusterUrl(url: string): string;
+/** Only the host: an RPC URL can carry an API key in its path or query, and these messages may be shared. */
+export declare function rpcHost(url: string): string;
+export declare function rpc<T>(url: string, method: string, params?: unknown[]): Promise<T>;
+/** fetch's "fetch failed" says little: the cause's code (ECONNREFUSED, ENOTFOUND, a timeout) says more. */
+export declare const errText: (e: unknown) => string;
+/**
+ * Before `solana program deploy`: the RPC answers, and the payer holds enough for the program's rent (a first deploy
+ * holds about twice the binary's rent while the buffer exists; an upgrade, the buffer's). Throws with what to do.
+ */
+export declare function deployPreflight(opts: {
+    url: string;
+    payer?: string;
+    programs: {
+        soPath: string;
+        address: string;
+        name: string;
+    }[];
+}): Promise<void>;
+/** Everything `typesol doctor` checks, in order. */
+export declare function doctorChecks(opts: {
+    cwd: string;
+    url?: string;
+    config?: string;
+}): Promise<Check[]>;
+export declare function formatChecks(checks: Check[]): string;

package/dist/tools/doctor.js

@@ -0,0 +1,229 @@
+// `typesol doctor` and the checks `init` and `deploy` run before they need something: Node, the platform-tools the
+// compiler builds with, the Solana CLI, its keypair and RPC, the project, and (with an RPC) whether it answers and the
+// payer can afford a deploy. Each problem comes with the command that fixes it.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findToolchain } from "../compiler/toolchain.js";
+import { base58, readKeypair } from "../keys.js";
+import { findWorkspace } from "../workspace.js";
+export const INSTALL_AGAVE = 'sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"';
+const MIN_NODE = [22, 12];
+/** The platform-tools the compiler needs: found, or what to run. */
+export function toolchainCheck() {
+    try {
+        const tc = findToolchain();
+        let version = "";
+        try {
+            version = execFileSync(tc.clang, ["--version"], { encoding: "utf8" })
+                .split("\n")[0]
+                .replace(/\s*\(.*$/, "");
+        }
+        catch {
+            /* the path is enough */
+        }
+        return { ok: true, what: "platform-tools", detail: version || tc.sdk };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            what: "platform-tools",
+            detail: e.message.split(". ")[0],
+            fix: [INSTALL_AGAVE, "cargo-build-sbf --version   # once: downloads the platform-tools TypeSOL compiles with"],
+        };
+    }
+}
+/** json_rpc_url / keypair_path from a Solana CLI config (the given file, or the CLI's default one). */
+export function solanaConfig(file) {
+    const configPath = file ?? path.join(os.homedir(), ".config/solana/cli/config.yml");
+    if (!existsSync(configPath))
+        return { file: configPath, exists: false };
+    const text = readFileSync(configPath, "utf8");
+    const get = (k) => new RegExp(`^${k}:\\s*["']?([^"'\\n]+?)["']?\\s*$`, "m").exec(text)?.[1];
+    const expand = (p) => (p?.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
+    return { url: get("json_rpc_url"), keypair: expand(get("keypair_path")), file: configPath, exists: true };
+}
+/** The Solana CLI's cluster monikers, as `solana --url` accepts them; anything else is used as given. */
+export function clusterUrl(url) {
+    const monikers = {
+        "mainnet-beta": "https://api.mainnet-beta.solana.com",
+        m: "https://api.mainnet-beta.solana.com",
+        devnet: "https://api.devnet.solana.com",
+        d: "https://api.devnet.solana.com",
+        testnet: "https://api.testnet.solana.com",
+        t: "https://api.testnet.solana.com",
+        localhost: "http://127.0.0.1:8899",
+        l: "http://127.0.0.1:8899",
+    };
+    return monikers[url] ?? url;
+}
+/** Only the host: an RPC URL can carry an API key in its path or query, and these messages may be shared. */
+export function rpcHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "the RPC";
+    }
+}
+/** The cluster an RPC belongs to, for the airdrop hint (mainnet has none). */
+function clusterOf(url) {
+    const host = rpcHost(url);
+    if (/devnet/.test(host))
+        return "devnet";
+    if (/testnet/.test(host))
+        return "testnet";
+    if (/^(127\.0\.0\.1|localhost|0\.0\.0\.0)(:|$)/.test(host))
+        return "localhost";
+    return undefined;
+}
+export async function rpc(url, method, params = []) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    const body = (await res.json());
+    if (body.error)
+        throw new Error(body.error.message);
+    return body.result;
+}
+/** fetch's "fetch failed" says little: the cause's code (ECONNREFUSED, ENOTFOUND, a timeout) says more. */
+export const errText = (e) => {
+    const err = e;
+    return err.cause?.code ?? err.cause?.message ?? (err.name === "TimeoutError" ? "no answer in 10 s" : err.message);
+};
+const sol = (lamports) => lamports === 0 ? "0 SOL" : lamports < 100_000 ? `${lamports} lamports` : `${(lamports / 1e9).toFixed(lamports < 1e7 ? 4 : 2)} SOL`;
+/** A cost, rounded up so the advice is enough. */
+const solUp = (lamports) => `${(Math.ceil(lamports / 1e7) / 100).toFixed(2)} SOL`;
+/**
+ * Before `solana program deploy`: the RPC answers, and the payer holds enough for the program's rent (a first deploy
+ * holds about twice the binary's rent while the buffer exists; an upgrade, the buffer's). Throws with what to do.
+ */
+export async function deployPreflight(opts) {
+    const host = rpcHost(opts.url);
+    try {
+        await rpc(opts.url, "getVersion");
+    }
+    catch (e) {
+        const local = clusterOf(opts.url) === "localhost";
+        throw new Error(`cannot reach ${host} (${errText(e)}). ` +
+            (local
+                ? "Start a local validator in another terminal: `solana-test-validator`, or deploy to devnet with --url devnet."
+                : "Check --url (or json_rpc_url in the Solana CLI config); for a test deploy use --url devnet or a local `solana-test-validator`."));
+    }
+    if (!opts.payer || !existsSync(opts.payer))
+        return; // the Solana CLI reports a missing keypair itself
+    const payer = base58(readKeypair(opts.payer).subarray(32));
+    let need = 0;
+    for (const p of opts.programs) {
+        const size = statSync(p.soPath).size;
+        const exists = (await rpc(opts.url, "getAccountInfo", [p.address, { encoding: "base64", dataSlice: { offset: 0, length: 0 } }])).value;
+        const rent = await rpc(opts.url, "getMinimumBalanceForRentExemption", [size + 45]);
+        need += exists ? rent : 2 * rent;
+    }
+    need += 5_000_000; // fees for the buffer writes
+    const balance = (await rpc(opts.url, "getBalance", [payer])).value;
+    if (balance >= need)
+        return;
+    const cluster = clusterOf(opts.url);
+    const airdrop = cluster ? ` Get test SOL: \`solana airdrop ${Math.max(2, Math.ceil((need - balance) / 1e9))} ${payer} --url ${cluster}\`.` : "";
+    throw new Error(`the payer ${payer} has ${sol(balance)} on ${host}; deploying needs about ${solUp(need)} (rent, mostly returned when a buffer closes).${airdrop}`);
+}
+/** Everything `typesol doctor` checks, in order. */
+export async function doctorChecks(opts) {
+    const checks = [];
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    const nodeOk = major > MIN_NODE[0] || (major === MIN_NODE[0] && minor >= MIN_NODE[1]);
+    checks.push({
+        ok: nodeOk,
+        what: "Node.js",
+        detail: process.versions.node,
+        fix: nodeOk ? undefined : [`install Node.js ${MIN_NODE.join(".")} or later (https://nodejs.org)`],
+    });
+    checks.push(toolchainCheck());
+    let solanaVersion;
+    try {
+        solanaVersion = execFileSync("solana", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+            .split(" (")[0]
+            .trim();
+    }
+    catch {
+        /* not installed */
+    }
+    checks.push(solanaVersion
+        ? { ok: true, what: "Solana CLI", detail: solanaVersion }
+        : { ok: false, optional: true, what: "Solana CLI", detail: "not on PATH (needed to deploy, not to build or test)", fix: [INSTALL_AGAVE] });
+    const cfg = solanaConfig(opts.config);
+    const keypair = cfg.keypair ?? path.join(os.homedir(), ".config/solana/id.json");
+    if (existsSync(keypair)) {
+        let address = "";
+        try {
+            address = base58(readKeypair(keypair).subarray(32));
+        }
+        catch (e) {
+            checks.push({ ok: false, optional: true, what: "keypair", detail: e.message });
+        }
+        if (address)
+            checks.push({ ok: true, what: "keypair", detail: `${address} (${keypair.replace(os.homedir(), "~")})` });
+    }
+    else
+        checks.push({
+            ok: false,
+            optional: true,
+            what: "keypair",
+            detail: `none at ${keypair.replace(os.homedir(), "~")} (the deploy payer)`,
+            fix: ["solana-keygen new"],
+        });
+    const url = opts.url ? clusterUrl(opts.url) : cfg.url;
+    if (!url)
+        checks.push({ ok: false, optional: true, what: "RPC", detail: "none set (deploy takes --url)", fix: ["solana config set --url devnet"] });
+    else {
+        const cluster = clusterOf(url);
+        try {
+            const v = await rpc(url, "getVersion");
+            checks.push({ ok: true, what: "RPC", detail: `${rpcHost(url)} (solana-core ${v["solana-core"]})` });
+            if (existsSync(keypair)) {
+                const balance = (await rpc(url, "getBalance", [base58(readKeypair(keypair).subarray(32))])).value;
+                checks.push(balance > 0
+                    ? { ok: true, what: "balance", detail: sol(balance) }
+                    : {
+                        ok: false,
+                        optional: true,
+                        what: "balance",
+                        detail: `0 SOL on ${rpcHost(url)}`,
+                        fix: [
+                            cluster && cluster !== "localhost"
+                                ? `solana airdrop 2 --url ${cluster}`
+                                : cluster
+                                    ? "solana airdrop 2 --url localhost"
+                                    : "fund the keypair above",
+                        ],
+                    });
+            }
+        }
+        catch (e) {
+            checks.push({
+                ok: false,
+                optional: true,
+                what: "RPC",
+                detail: `${rpcHost(url)} does not answer (${errText(e)})`,
+                fix: cluster === "localhost" ? ["solana-test-validator   # in another terminal"] : ["pass --url devnet, or fix json_rpc_url in the Solana CLI config"],
+            });
+        }
+    }
+    const ws = findWorkspace(opts.cwd);
+    checks.push(ws
+        ? { ok: true, what: "project", detail: `${path.relative(opts.cwd, ws.file) || ws.file}: ${Object.keys(ws.programs).join(", ")}` }
+        : { ok: true, optional: true, what: "project", detail: "none here (typesol init <dir> creates one)" });
+    return checks;
+}
+export function formatChecks(checks) {
+    const mark = (c) => (c.ok ? "ok " : c.optional ? " ! " : "ERR");
+    const width = Math.max(...checks.map((c) => c.what.length));
+    return checks
+        .map((c) => `  ${mark(c)}  ${c.what.padEnd(width)}  ${c.detail}${(c.fix ?? []).map((f) => `\n${" ".repeat(width + 9)}${f}`).join("")}`)
+        .join("\n");
+}