@aura-protocol/cli 0.1.2 → 0.3.0

package/dist/core/config.js

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { AURA_PROGRAM_ID, DEVNET_RPC_URL } from "@aura-protocol/sdk-ts";
+export const DEFAULT_CONFIG = {
+    rpcUrl: DEVNET_RPC_URL,
+    walletPath: "~/.config/solana/id.json",
+    cluster: "devnet",
+    programId: AURA_PROGRAM_ID.toBase58(),
+    defaultAgentId: null,
+};
+export function expandHome(inputPath) {
+    if (inputPath === "~") {
+        return homedir();
+    }
+    if (inputPath.startsWith("~/")) {
+        return path.join(homedir(), inputPath.slice(2));
+    }
+    return inputPath;
+}
+export function compactHome(inputPath) {
+    const home = homedir();
+    if (inputPath === home) {
+        return "~";
+    }
+    if (inputPath.startsWith(`${home}${path.sep}`)) {
+        return `~/${inputPath.slice(home.length + 1)}`;
+    }
+    return inputPath;
+}
+export function getConfigDir() {
+    return path.join(homedir(), ".aura");
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), "config.json");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function readConfigFile() {
+    const filePath = getConfigPath();
+    if (!existsSync(filePath)) {
+        return {};
+    }
+    const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+    if (!isRecord(parsed)) {
+        throw new Error(`Config file ${filePath} must contain a JSON object`);
+    }
+    return {
+        rpcUrl: typeof parsed.rpcUrl === "string" ? parsed.rpcUrl : undefined,
+        walletPath: typeof parsed.walletPath === "string" ? parsed.walletPath : undefined,
+        cluster: typeof parsed.cluster === "string" ? parsed.cluster : undefined,
+        programId: typeof parsed.programId === "string" ? parsed.programId : undefined,
+        defaultAgentId: typeof parsed.defaultAgentId === "string" ||
+            parsed.defaultAgentId === null
+            ? parsed.defaultAgentId
+            : undefined,
+    };
+}
+export function writeConfigFile(config) {
+    const filePath = getConfigPath();
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return filePath;
+}
+function pickField(flagValue, envValue, fileValue, defaultValue) {
+    if (flagValue !== undefined) {
+        return { value: flagValue, source: "flag" };
+    }
+    if (envValue !== undefined) {
+        return { value: envValue, source: "env" };
+    }
+    if (fileValue !== undefined) {
+        return { value: fileValue, source: "config" };
+    }
+    return { value: defaultValue, source: "default" };
+}
+export function resolveConfig(overrides = {}, env = process.env) {
+    const fileConfig = readConfigFile();
+    return {
+        rpcUrl: pickField(overrides.rpcUrl, env.AURA_RPC_URL ?? env.AURA_DEVNET_RPC_URL ?? env.SOLANA_RPC_URL, fileConfig.rpcUrl, DEFAULT_CONFIG.rpcUrl),
+        walletPath: pickField(overrides.walletPath, env.AURA_WALLET_PATH ?? env.PAYER_KEYPAIR, fileConfig.walletPath, DEFAULT_CONFIG.walletPath),
+        cluster: pickField(overrides.cluster, env.AURA_CLUSTER, fileConfig.cluster, DEFAULT_CONFIG.cluster),
+        programId: pickField(overrides.programId, env.AURA_PROGRAM_ID, fileConfig.programId, DEFAULT_CONFIG.programId),
+        defaultAgentId: pickField(overrides.defaultAgentId, env.AURA_DEFAULT_AGENT_ID, fileConfig.defaultAgentId, DEFAULT_CONFIG.defaultAgentId),
+    };
+}
+export function flattenResolvedConfig(resolved) {
+    return {
+        rpcUrl: resolved.rpcUrl.value,
+        walletPath: resolved.walletPath.value,
+        cluster: resolved.cluster.value,
+        programId: resolved.programId.value,
+        defaultAgentId: resolved.defaultAgentId.value,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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"}

package/dist/core/context.d.ts

@@ -0,0 +1,51 @@
+import { AuraClient } from "@aura-protocol/sdk-ts";
+import { Connection, PublicKey } from "@solana/web3.js";
+import type { Command } from "commander";
+import { type AuraCliConfig, type ResolvedAuraCliConfig } from "./config.js";
+import { type NetworkInfo } from "./network.js";
+import { loadKeypair } from "./wallet.js";
+export interface GlobalOptions {
+    rpcUrl?: string;
+    wallet?: string;
+    programId?: string;
+    cluster?: string;
+    json?: boolean;
+    quiet?: boolean;
+    dryRun?: boolean;
+    /** Skip interactive confirmations (CI / non-interactive use). */
+    yes?: boolean;
+    /** Preflight-simulate writes before sending (default true; `--no-simulate`). */
+    simulate?: boolean;
+    /** Override the compute-unit limit for sent transactions. */
+    computeUnits?: number;
+}
+/** Per-invocation send/guard flags derived from global options. */
+export interface CliFlags {
+    yes: boolean;
+    simulate: boolean;
+    computeUnits?: number;
+}
+export interface CliContext {
+    output: {
+        json: boolean;
+        quiet: boolean;
+    };
+    dryRun: boolean;
+    flags: CliFlags;
+    resolvedConfig: ResolvedAuraCliConfig;
+    config: AuraCliConfig;
+    connection: Connection;
+    programId: PublicKey;
+    network: NetworkInfo;
+    client: AuraClient;
+    wallet?: ReturnType<typeof loadKeypair>;
+}
+export declare function getGlobalOptions(command: Command): GlobalOptions;
+export declare function resolveGlobalConfig(command: Command): {
+    globals: GlobalOptions;
+    resolvedConfig: ResolvedAuraCliConfig;
+    config: AuraCliConfig;
+};
+export declare function buildCliContext(command: Command, options?: {
+    needsWallet?: boolean;
+}): CliContext;

package/dist/core/context.js

@@ -0,0 +1,60 @@
+import { AuraClient } from "@aura-protocol/sdk-ts";
+import { Connection, PublicKey } from "@solana/web3.js";
+import { flattenResolvedConfig, resolveConfig, } from "./config.js";
+import { classifyNetwork } from "./network.js";
+import { loadKeypair } from "./wallet.js";
+export function getGlobalOptions(command) {
+    const raw = command.optsWithGlobals();
+    return {
+        rpcUrl: typeof raw.rpcUrl === "string" ? raw.rpcUrl : undefined,
+        wallet: typeof raw.wallet === "string" ? raw.wallet : undefined,
+        programId: typeof raw.programId === "string" ? raw.programId : undefined,
+        cluster: typeof raw.cluster === "string" ? raw.cluster : undefined,
+        json: raw.json === true,
+        quiet: raw.quiet === true,
+        dryRun: raw.dryRun === true,
+        yes: raw.yes === true,
+        // commander sets `simulate` to false only when `--no-simulate` is passed.
+        simulate: raw.simulate !== false,
+        computeUnits: typeof raw.computeUnits === "number" ? raw.computeUnits : undefined,
+    };
+}
+export function resolveGlobalConfig(command) {
+    const globals = getGlobalOptions(command);
+    const overrides = {
+        rpcUrl: globals.rpcUrl,
+        walletPath: globals.wallet,
+        programId: globals.programId,
+        cluster: globals.cluster,
+    };
+    const resolvedConfig = resolveConfig(overrides);
+    const config = flattenResolvedConfig(resolvedConfig);
+    return { globals, resolvedConfig, config };
+}
+export function buildCliContext(command, options = {}) {
+    const { globals, resolvedConfig, config } = resolveGlobalConfig(command);
+    const connection = new Connection(config.rpcUrl, "confirmed");
+    const programId = new PublicKey(config.programId);
+    const wallet = options.needsWallet === false ? undefined : loadKeypair(config.walletPath);
+    const client = new AuraClient({ connection, programId });
+    return {
+        output: {
+            json: globals.json === true,
+            quiet: globals.quiet === true,
+        },
+        dryRun: globals.dryRun === true,
+        flags: {
+            yes: globals.yes === true,
+            simulate: globals.simulate !== false,
+            computeUnits: globals.computeUnits,
+        },
+        resolvedConfig,
+        config,
+        connection,
+        programId,
+        network: classifyNetwork(config.rpcUrl),
+        client,
+        wallet,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EAGL,qBAAqB,EAErB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAoB,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAyC1C,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,eAAe,EAA6B,CAAC;IACjE,OAAO;QACL,MAAM,EAAE,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QAC/D,MAAM,EAAE,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QAC/D,SAAS,EAAE,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACxE,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;QAClE,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,IAAI;QACvB,KAAK,EAAE,GAAG,CAAC,KAAK,KAAK,IAAI;QACzB,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,IAAI;QAC3B,GAAG,EAAE,GAAG,CAAC,GAAG,KAAK,IAAI;QACrB,0EAA0E;QAC1E,QAAQ,EAAE,GAAG,CAAC,QAAQ,KAAK,KAAK;QAChC,YAAY,EACV,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;KACtE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAKlD,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,SAAS,GAA2B;QACxC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,OAAO,CAAC,MAAM;QAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;IACF,MAAM,cAAc,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,qBAAqB,CAAC,cAAc,CAAC,CAAC;IACrD,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,OAAgB,EAChB,UAAqC,EAAE;IAEvC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACzE,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAElD,MAAM,MAAM,GACV,OAAO,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7E,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAEzD,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,IAAI;YAC3B,KAAK,EAAE,OAAO,CAAC,KAAK,KAAK,IAAI;SAC9B;QACD,MAAM,EAAE,OAAO,CAAC,MAAM,KAAK,IAAI;QAC/B,KAAK,EAAE;YACL,GAAG,EAAE,OAAO,CAAC,GAAG,KAAK,IAAI;YACzB,QAAQ,EAAE,OAAO,CAAC,QAAQ,KAAK,KAAK;YACpC,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC;QACD,cAAc;QACd,MAAM;QACN,UAAU;QACV,SAAS;QACT,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC;QACvC,MAAM;QACN,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/core/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Typed CLI errors and the tip-aware error renderer.
+ *
+ * `CliError` carries an optional machine `code`, a human `tip` (the single most
+ * useful next action), and example commands. The root error boundary renders
+ * any thrown value through {@link renderError}, mapping common low-level failures
+ * (RPC rate limits, missing wallets, bad inputs, failed simulations) to guidance
+ * so users are never left staring at a raw stack trace.
+ */
+export interface CliErrorOptions {
+    /** Stable machine-readable code, e.g. `WALLET_NOT_FOUND`. */
+    code?: string;
+    /** The single most useful next action for the user. */
+    tip?: string;
+    /** Example invocations that would succeed. */
+    examples?: string[];
+    /** Extra context (e.g. simulation logs) shown under the message. */
+    details?: string;
+    /** Underlying cause, preserved for debugging. */
+    cause?: unknown;
+}
+/** An error with a user-facing tip and optional examples. */
+export declare class CliError extends Error {
+    readonly code?: string;
+    readonly tip?: string;
+    readonly examples?: string[];
+    readonly details?: string;
+    constructor(message: string, options?: CliErrorOptions);
+    /** Builds an error for an invalid flag/argument value, with a usage example. */
+    static invalidInput(field: string, expected: string, example?: string): CliError;
+}
+/** Extracts a clean message string from any thrown value. */
+export declare function toMessage(error: unknown): string;
+/**
+ * Renders an error to stderr with a leading `✗`, a tip line, and example
+ * commands when available. Returns nothing; intended for the root boundary.
+ */
+export declare function renderError(error: unknown): void;

package/dist/core/errors.js

@@ -0,0 +1,138 @@
+/**
+ * Typed CLI errors and the tip-aware error renderer.
+ *
+ * `CliError` carries an optional machine `code`, a human `tip` (the single most
+ * useful next action), and example commands. The root error boundary renders
+ * any thrown value through {@link renderError}, mapping common low-level failures
+ * (RPC rate limits, missing wallets, bad inputs, failed simulations) to guidance
+ * so users are never left staring at a raw stack trace.
+ */
+import { style, symbol } from "../ui/theme.js";
+/** An error with a user-facing tip and optional examples. */
+export class CliError extends Error {
+    code;
+    tip;
+    examples;
+    details;
+    constructor(message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "CliError";
+        this.code = options.code;
+        this.tip = options.tip;
+        this.examples = options.examples;
+        this.details = options.details;
+    }
+    /** Builds an error for an invalid flag/argument value, with a usage example. */
+    static invalidInput(field, expected, example) {
+        return new CliError(`Invalid value for ${style.code(field)}: expected ${expected}.`, {
+            code: "INVALID_INPUT",
+            tip: `Pass a valid ${expected} for ${field}.`,
+            examples: example ? [example] : undefined,
+        });
+    }
+}
+/**
+ * Maps a raw error message to actionable guidance. This is best-effort pattern
+ * matching over common Solana/RPC/SDK failures.
+ */
+function deriveGuidance(message) {
+    const lower = message.toLowerCase();
+    if (message.includes("429") ||
+        lower.includes("rate limit") ||
+        lower.includes("too many requests")) {
+        return {
+            tip: "The RPC endpoint is rate limiting you. Point at a dedicated endpoint.",
+            examples: [
+                "aura --rpc-url https://your-rpc.example treasury show --agent-id my-agent",
+            ],
+        };
+    }
+    if (lower.includes("could not load wallet") || lower.includes("keypair")) {
+        return {
+            tip: "Configure a wallet, or pass one explicitly.",
+            examples: [
+                "aura config init",
+                "aura --wallet ~/.config/solana/id.json treasury list",
+            ],
+        };
+    }
+    if (lower.includes("account does not exist") ||
+        lower.includes("not exist") ||
+        lower.includes("could not find")) {
+        return {
+            tip: "Verify the treasury PDA or agent ID — the account may not be created yet.",
+            examples: [
+                "aura treasury create --agent-id my-agent --daily-limit 1000 --per-tx-limit 250",
+            ],
+        };
+    }
+    if (lower.includes("invalid public key") ||
+        lower.includes("non-base58") ||
+        lower.includes("base58")) {
+        return {
+            tip: "A public key argument is not valid base58. Re-check the address you passed.",
+        };
+    }
+    if (lower.includes("insufficient") && lower.includes("lamports")) {
+        return {
+            tip: "The fee payer is out of SOL. Fund the wallet (devnet: `solana airdrop 2`).",
+        };
+    }
+    if (lower.includes("publickeyhex") ||
+        lower.includes("messagemetadatadigest")) {
+        return {
+            tip: "Re-register the live dWallet with --dwallet-account, --authorized-user, --message-metadata-digest, and --public-key-hex.",
+        };
+    }
+    if (lower.includes("scalar confidential guardrails are not configured")) {
+        return {
+            tip: "Configure scalar guardrails before proposing a confidential spend.",
+            examples: [
+                "aura confidential guardrails scalar --agent-id my-agent --daily-limit 5000 --per-tx-limit 1000",
+            ],
+        };
+    }
+    if (lower.includes("blockhash") && lower.includes("not found")) {
+        return {
+            tip: "Transaction expired before confirmation. Retry the command.",
+        };
+    }
+    return {};
+}
+/** Extracts a clean message string from any thrown value. */
+export function toMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+/**
+ * Renders an error to stderr with a leading `✗`, a tip line, and example
+ * commands when available. Returns nothing; intended for the root boundary.
+ */
+export function renderError(error) {
+    const message = toMessage(error);
+    console.error(`${style.danger(symbol.error)} ${style.danger("Error")}: ${message}`);
+    const fromCli = error instanceof CliError ? error : undefined;
+    const guidance = deriveGuidance(message);
+    const details = fromCli?.details;
+    if (details) {
+        for (const line of details.split("\n")) {
+            console.error(`  ${style.muted(line)}`);
+        }
+    }
+    const tip = fromCli?.tip ?? guidance.tip;
+    if (tip) {
+        console.error(`${style.warn(symbol.info)} ${style.bold("tip")}: ${tip}`);
+    }
+    const examples = fromCli?.examples ?? guidance.examples;
+    if (examples && examples.length > 0) {
+        for (const example of examples) {
+            console.error(`  ${style.muted(symbol.pointer)} ${style.code(example)}`);
+        }
+    }
+    if (fromCli?.code) {
+        console.error(style.dim(`  (${fromCli.code})`));
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/network.d.ts

@@ -0,0 +1,18 @@
+/**
+ * RPC endpoint classification.
+ *
+ * Used to drive guard rails: a write against a production (mainnet) endpoint
+ * gets an explicit confirmation, and the resolved network is surfaced in every
+ * transaction preview so users always know where a transaction is going.
+ */
+export type ClusterKind = "mainnet" | "devnet" | "testnet" | "localnet" | "custom";
+export interface NetworkInfo {
+    kind: ClusterKind;
+    /** Human label, e.g. "mainnet-beta" or "devnet". */
+    label: string;
+    rpcUrl: string;
+    /** True for mainnet — the only network treated as production/high-risk. */
+    isProduction: boolean;
+}
+/** Classifies an RPC URL into a known Solana cluster. */
+export declare function classifyNetwork(rpcUrl: string): NetworkInfo;

package/dist/core/network.js

@@ -0,0 +1,38 @@
+/**
+ * RPC endpoint classification.
+ *
+ * Used to drive guard rails: a write against a production (mainnet) endpoint
+ * gets an explicit confirmation, and the resolved network is surfaced in every
+ * transaction preview so users always know where a transaction is going.
+ */
+/** Classifies an RPC URL into a known Solana cluster. */
+export function classifyNetwork(rpcUrl) {
+    const lower = rpcUrl.toLowerCase();
+    let kind = "custom";
+    let label = "custom";
+    if (lower.includes("mainnet")) {
+        kind = "mainnet";
+        label = "mainnet-beta";
+    }
+    else if (lower.includes("devnet")) {
+        kind = "devnet";
+        label = "devnet";
+    }
+    else if (lower.includes("testnet")) {
+        kind = "testnet";
+        label = "testnet";
+    }
+    else if (lower.includes("localhost") ||
+        lower.includes("127.0.0.1") ||
+        lower.includes("0.0.0.0")) {
+        kind = "localnet";
+        label = "localnet";
+    }
+    return {
+        kind,
+        label,
+        rpcUrl,
+        isProduction: kind === "mainnet",
+    };
+}
+//# sourceMappingURL=network.js.map

package/dist/core/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/core/network.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH,yDAAyD;AACzD,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,IAAI,GAAgB,QAAQ,CAAC;IACjC,IAAI,KAAK,GAAG,QAAQ,CAAC;IAErB,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,IAAI,GAAG,SAAS,CAAC;QACjB,KAAK,GAAG,cAAc,CAAC;IACzB,CAAC;SAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,IAAI,GAAG,QAAQ,CAAC;QAChB,KAAK,GAAG,QAAQ,CAAC;IACnB,CAAC;SAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,IAAI,GAAG,SAAS,CAAC;QACjB,KAAK,GAAG,SAAS,CAAC;IACpB,CAAC;SAAM,IACL,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC3B,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC3B,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EACzB,CAAC;QACD,IAAI,GAAG,UAAU,CAAC;QAClB,KAAK,GAAG,UAAU,CAAC;IACrB,CAAC;IAED,OAAO;QACL,IAAI;QACJ,KAAK;QACL,MAAM;QACN,YAAY,EAAE,IAAI,KAAK,SAAS;KACjC,CAAC;AACJ,CAAC"}

package/dist/core/runner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The secure transaction pipeline shared by every command that writes
+ * on-chain. Given built instructions and some metadata it will, in order:
+ *
+ *   1. assemble the transaction (compute-budget + optional heap frame),
+ *   2. render a human preview of exactly what will be signed,
+ *   3. guard production (mainnet) writes behind an explicit confirmation,
+ *   4. confirm sensitive instructions (authority/governance/closures),
+ *   5. preflight-simulate and surface compute units + program logs,
+ *   6. sign, send, and confirm, printing the signature + explorer link.
+ *
+ * `--dry-run` stops after the preview and emits the serialized instructions.
+ * `--json` suppresses decorative output and returns structured data.
+ * `--yes` skips confirmations (for CI). `--no-simulate` skips preflight.
+ */
+import { type Signer, type TransactionInstruction } from "@solana/web3.js";
+import type { CliContext } from "./context.js";
+export interface RunMeta {
+    /** Short action label, e.g. "Create treasury". */
+    action: string;
+    /** snake_case instruction name, used to classify risk. */
+    instructionName?: string;
+    /** Key/value rows summarizing the action, shown in the preview. */
+    summary?: [string, string][];
+    /** Additional signers beyond the fee-payer wallet. */
+    extraSigners?: Signer[];
+    /** Override the compute-unit limit. */
+    computeUnits?: number;
+    /** Request a heap-frame bump (confidential / large instructions). */
+    heapFrameBytes?: number;
+    /** Force a confirmation prompt regardless of risk classification. */
+    confirm?: boolean;
+    /** Extra fields merged into the JSON output on success. */
+    result?: Record<string, unknown>;
+}
+export interface RunOutcome {
+    dryRun: boolean;
+    aborted: boolean;
+    signature?: string;
+}
+/**
+ * Builds, previews, guards, simulates, signs, and sends `instructions`.
+ * Honors `--dry-run`, `--json`, `--yes`, `--no-simulate`, and `--compute-units`.
+ */
+export declare function runInstructions(ctx: CliContext, instructions: TransactionInstruction[], meta: RunMeta): Promise<RunOutcome>;