@caatinga/core 0.2.0

package/dist/index.cjs

@@ -0,0 +1,1104 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CAATINGA_CORE_VERSION: () => CAATINGA_CORE_VERSION,
+  CaatingaArtifactsSchema: () => CaatingaArtifactsSchema,
+  CaatingaConfigSchema: () => CaatingaConfigSchema,
+  CaatingaError: () => CaatingaError,
+  CaatingaErrorCode: () => CaatingaErrorCode,
+  STELLAR_CLI_MIN_VERSION: () => STELLAR_CLI_MIN_VERSION,
+  STELLAR_CLI_TESTED_MAX_VERSION: () => STELLAR_CLI_TESTED_MAX_VERSION,
+  TemplateManifestSchema: () => TemplateManifestSchema,
+  WELL_KNOWN_NETWORKS: () => WELL_KNOWN_NETWORKS,
+  assertSupportedStellarCliVersion: () => assertSupportedStellarCliVersion,
+  buildContract: () => buildContract,
+  buildDependencyGraph: () => buildDependencyGraph,
+  checkBinary: () => checkBinary,
+  createInitialArtifacts: () => createInitialArtifacts,
+  createProjectFromTemplate: () => createProjectFromTemplate,
+  defineConfig: () => defineConfig,
+  deployContract: () => deployContract,
+  deployContractGraph: () => deployContractGraph,
+  generateBindings: () => generateBindings,
+  invokeContract: () => invokeContract,
+  isTransientTestnetSmokeFailure: () => isTransientTestnetSmokeFailure,
+  loadConfig: () => loadConfig,
+  parseContractId: () => parseContractId,
+  parseInvokeTarget: () => parseInvokeTarget,
+  parseStellarCliVersion: () => parseStellarCliVersion,
+  readArtifacts: () => readArtifacts,
+  resolveContract: () => resolveContract,
+  resolveDeployArgs: () => resolveDeployArgs,
+  resolveDeployOrder: () => resolveDeployOrder,
+  resolveNetwork: () => resolveNetwork,
+  runCommand: () => runCommand,
+  toCaatingaError: () => toCaatingaError,
+  updateArtifact: () => updateArtifact,
+  writeArtifacts: () => writeArtifacts
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/CaatingaErrorCode.ts
+var CaatingaErrorCode = {
+  CONFIG_NOT_FOUND: "CAATINGA_CONFIG_NOT_FOUND",
+  INVALID_CONFIG: "CAATINGA_INVALID_CONFIG",
+  COMMAND_FAILED: "CAATINGA_COMMAND_FAILED",
+  UNEXPECTED_ERROR: "CAATINGA_UNEXPECTED_ERROR",
+  STELLAR_CLI_NOT_FOUND: "CAATINGA_STELLAR_CLI_NOT_FOUND",
+  STELLAR_CLI_VERSION_PARSE_FAILED: "CAATINGA_STELLAR_CLI_VERSION_PARSE_FAILED",
+  UNSUPPORTED_CLI_VERSION: "CAATINGA_UNSUPPORTED_CLI_VERSION",
+  UNTESTED_CLI_VERSION: "CAATINGA_UNTESTED_CLI_VERSION",
+  RUST_NOT_FOUND: "CAATINGA_RUST_NOT_FOUND",
+  RUST_TARGET_NOT_FOUND: "CAATINGA_RUST_TARGET_NOT_FOUND",
+  DEPLOY_FAILED: "CAATINGA_DEPLOY_FAILED",
+  BUILD_FAILED: "CAATINGA_BUILD_FAILED",
+  BINDINGS_FAILED: "CAATINGA_BINDINGS_FAILED",
+  INVOKE_FAILED: "CAATINGA_INVOKE_FAILED",
+  CONTRACT_NOT_FOUND: "CAATINGA_CONTRACT_NOT_FOUND",
+  NETWORK_NOT_FOUND: "CAATINGA_NETWORK_NOT_FOUND",
+  ARTIFACT_NOT_FOUND: "CAATINGA_ARTIFACT_NOT_FOUND",
+  ARTIFACT_INVALID: "CAATINGA_ARTIFACT_INVALID",
+  CONTRACT_ID_NOT_FOUND: "CAATINGA_CONTRACT_ID_NOT_FOUND",
+  CONTRACT_ARTIFACT_NOT_FOUND: "CAATINGA_CONTRACT_ARTIFACT_NOT_FOUND",
+  CONTRACT_DEPENDENCY_NOT_FOUND: "CAATINGA_CONTRACT_DEPENDENCY_NOT_FOUND",
+  CONTRACT_DEPENDENCY_CYCLE: "CAATINGA_CONTRACT_DEPENDENCY_CYCLE",
+  CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND: "CAATINGA_CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND",
+  DEPLOY_ARG_PLACEHOLDER_INVALID: "CAATINGA_DEPLOY_ARG_PLACEHOLDER_INVALID",
+  DEPLOY_ARG_PLACEHOLDER_UNRESOLVED: "CAATINGA_DEPLOY_ARG_PLACEHOLDER_UNRESOLVED",
+  BINDING_CLIENT_NOT_FOUND: "CAATINGA_BINDING_CLIENT_NOT_FOUND",
+  BINDING_METHOD_NOT_FOUND: "CAATINGA_BINDING_METHOD_NOT_FOUND",
+  XDR_BUILD_FAILED: "CAATINGA_XDR_BUILD_FAILED",
+  XDR_PREPARE_FAILED: "CAATINGA_XDR_PREPARE_FAILED",
+  XDR_SIGN_FAILED: "CAATINGA_XDR_SIGN_FAILED",
+  XDR_SUBMIT_FAILED: "CAATINGA_XDR_SUBMIT_FAILED",
+  XDR_RESULT_FAILED: "CAATINGA_XDR_RESULT_FAILED",
+  WALLET_NOT_CONNECTED: "CAATINGA_WALLET_NOT_CONNECTED",
+  SOURCE_ACCOUNT_REQUIRED: "CAATINGA_SOURCE_ACCOUNT_REQUIRED",
+  UNSAFE_SOURCE_ACCOUNT: "CAATINGA_UNSAFE_SOURCE_ACCOUNT",
+  INVOKE_TARGET_INVALID: "CAATINGA_INVOKE_TARGET_INVALID",
+  TEMPLATE_NOT_FOUND: "CAATINGA_TEMPLATE_NOT_FOUND",
+  INVALID_TEMPLATE_MANIFEST: "CAATINGA_INVALID_TEMPLATE_MANIFEST",
+  TEMPLATE_MANIFEST_NOT_FOUND: "CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND",
+  TEMPLATE_INCOMPATIBLE: "CAATINGA_TEMPLATE_INCOMPATIBLE"
+};
+
+// src/errors/CaatingaError.ts
+var CaatingaError = class extends Error {
+  constructor(message, code, hint, cause) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.cause = cause;
+    this.name = "CaatingaError";
+  }
+  code;
+  hint;
+  cause;
+};
+function toCaatingaError(error) {
+  if (error instanceof CaatingaError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new CaatingaError(error.message, CaatingaErrorCode.UNEXPECTED_ERROR, void 0, error);
+  }
+  return new CaatingaError("An unexpected error occurred.", CaatingaErrorCode.UNEXPECTED_ERROR);
+}
+
+// src/version.ts
+var CAATINGA_CORE_VERSION = "0.2.0";
+
+// src/config/config.schema.ts
+var import_zod = require("zod");
+var DeployArgValueSchema = import_zod.z.union([import_zod.z.string(), import_zod.z.number(), import_zod.z.boolean()]);
+var ContractConfigSchema = import_zod.z.object({
+  path: import_zod.z.string().min(1),
+  wasm: import_zod.z.string().min(1),
+  dependsOn: import_zod.z.array(import_zod.z.string().min(1)).default([]),
+  deployArgs: import_zod.z.record(import_zod.z.string().min(1), DeployArgValueSchema).default({})
+});
+var NetworkConfigSchema = import_zod.z.object({
+  rpcUrl: import_zod.z.string().url(),
+  networkPassphrase: import_zod.z.string().min(1)
+});
+var CaatingaConfigSchema = import_zod.z.object({
+  project: import_zod.z.string().min(1),
+  defaultNetwork: import_zod.z.string().min(1).default("testnet"),
+  contracts: import_zod.z.record(import_zod.z.string().min(1), ContractConfigSchema).refine(
+    (contracts) => Object.keys(contracts).length > 0,
+    "At least one contract must be configured."
+  ),
+  networks: import_zod.z.record(import_zod.z.string().min(1), NetworkConfigSchema).refine(
+    (networks) => Object.keys(networks).length > 0,
+    "At least one network must be configured."
+  ),
+  frontend: import_zod.z.object({
+    framework: import_zod.z.enum(["vite-react", "next", "astro"]).default("vite-react"),
+    bindingsOutput: import_zod.z.string().min(1)
+  })
+});
+
+// src/config/define-config.ts
+function defineConfig(config) {
+  return config;
+}
+
+// src/config/load-config.ts
+var import_promises = require("fs/promises");
+var import_node_path = __toESM(require("path"), 1);
+var import_jiti = require("jiti");
+var import_zod2 = require("zod");
+var import_meta = {};
+async function loadConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = import_node_path.default.resolve(cwd, options.configPath ?? "caatinga.config.ts");
+  try {
+    await (0, import_promises.access)(configPath);
+  } catch {
+    throw new CaatingaError(
+      "caatinga.config.ts was not found.",
+      CaatingaErrorCode.CONFIG_NOT_FOUND,
+      "Run this command from a Caatinga project root, or create a caatinga.config.ts file."
+    );
+  }
+  try {
+    const jiti = (0, import_jiti.createJiti)(import_meta.url);
+    const loaded = await jiti.import(configPath, { default: true });
+    return CaatingaConfigSchema.parse(loaded);
+  } catch (error) {
+    if (error instanceof import_zod2.z.ZodError) {
+      throw new CaatingaError(
+        "caatinga.config.ts is invalid.",
+        CaatingaErrorCode.INVALID_CONFIG,
+        error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
+      );
+    }
+    throw error;
+  }
+}
+
+// src/artifacts/artifact.schema.ts
+var import_zod3 = require("zod");
+var ContractArtifactSchema = import_zod3.z.object({
+  contractId: import_zod3.z.string().min(1),
+  wasmHash: import_zod3.z.string().min(1),
+  deployedAt: import_zod3.z.string().datetime(),
+  sourcePath: import_zod3.z.string().min(1),
+  wasmPath: import_zod3.z.string().min(1),
+  dependencies: import_zod3.z.array(import_zod3.z.string().min(1)).default([]),
+  resolvedDeployArgs: import_zod3.z.record(import_zod3.z.string().min(1), import_zod3.z.union([import_zod3.z.string(), import_zod3.z.number(), import_zod3.z.boolean()])).default({})
+});
+var NetworkArtifactsSchema = import_zod3.z.object({
+  contracts: import_zod3.z.record(import_zod3.z.string().min(1), ContractArtifactSchema).default({}),
+  dependencyGraph: import_zod3.z.record(import_zod3.z.string().min(1), import_zod3.z.array(import_zod3.z.string().min(1))).default({})
+});
+var CaatingaArtifactsSchema = import_zod3.z.object({
+  project: import_zod3.z.string().min(1),
+  version: import_zod3.z.literal(1),
+  networks: import_zod3.z.record(import_zod3.z.string().min(1), NetworkArtifactsSchema).default({})
+});
+
+// src/artifacts/read-artifacts.ts
+var import_promises2 = require("fs/promises");
+var import_node_path2 = __toESM(require("path"), 1);
+var import_zod4 = require("zod");
+async function readArtifacts(cwd = process.cwd()) {
+  const artifactsPath = import_node_path2.default.resolve(cwd, "caatinga.artifacts.json");
+  try {
+    const json = await (0, import_promises2.readFile)(artifactsPath, "utf8");
+    return CaatingaArtifactsSchema.parse(JSON.parse(json));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new CaatingaError(
+        "caatinga.artifacts.json was not found.",
+        CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+        "Run caatinga init, or create the artifacts file before deploying or generating bindings."
+      );
+    }
+    if (error instanceof SyntaxError || error instanceof import_zod4.z.ZodError) {
+      throw new CaatingaError(
+        "caatinga.artifacts.json is invalid.",
+        CaatingaErrorCode.ARTIFACT_INVALID,
+        "Fix the JSON shape before running Caatinga commands."
+      );
+    }
+    throw error;
+  }
+}
+
+// src/artifacts/write-artifacts.ts
+var import_promises3 = require("fs/promises");
+var import_node_path3 = __toESM(require("path"), 1);
+async function writeArtifacts(artifacts, cwd = process.cwd()) {
+  const artifactsPath = import_node_path3.default.resolve(cwd, "caatinga.artifacts.json");
+  await (0, import_promises3.mkdir)(import_node_path3.default.dirname(artifactsPath), { recursive: true });
+  await (0, import_promises3.writeFile)(artifactsPath, `${JSON.stringify(artifacts, null, 2)}
+`, "utf8");
+  return artifactsPath;
+}
+function createInitialArtifacts(project) {
+  return {
+    project,
+    version: 1,
+    networks: {}
+  };
+}
+
+// src/artifacts/update-artifact.ts
+function updateArtifact(artifacts, networkName, contractName, contractArtifact, networkExtras) {
+  const existingNetwork = artifacts.networks[networkName] ?? { contracts: {}, dependencyGraph: {} };
+  return {
+    ...artifacts,
+    networks: {
+      ...artifacts.networks,
+      [networkName]: {
+        ...existingNetwork,
+        dependencyGraph: networkExtras?.dependencyGraph ?? existingNetwork.dependencyGraph ?? {},
+        contracts: {
+          ...existingNetwork.contracts,
+          [contractName]: contractArtifact
+        }
+      }
+    }
+  };
+}
+
+// src/networks/networks.ts
+var WELL_KNOWN_NETWORKS = {
+  testnet: {
+    rpcUrl: "https://soroban-testnet.stellar.org",
+    networkPassphrase: "Test SDF Network ; September 2015"
+  },
+  mainnet: {
+    rpcUrl: "https://mainnet.sorobanrpc.com",
+    networkPassphrase: "Public Global Stellar Network ; September 2015"
+  }
+};
+
+// src/networks/resolve-network.ts
+function resolveNetwork(config, networkName) {
+  const name = networkName ?? config.defaultNetwork;
+  const network = config.networks[name];
+  if (!network) {
+    throw new CaatingaError(
+      `Network "${name}" is not configured.`,
+      CaatingaErrorCode.NETWORK_NOT_FOUND,
+      `Add "${name}" to caatinga.config.ts networks, or pass a configured --network value.`
+    );
+  }
+  return { name, config: network };
+}
+
+// src/shell/run-command.ts
+var import_execa = require("execa");
+
+// src/stellar-cli/version.ts
+var import_semver = __toESM(require("semver"), 1);
+var STELLAR_CLI_MIN_VERSION = "22.0.0";
+var STELLAR_CLI_TESTED_MAX_VERSION = "25.2.0";
+var STELLAR_CLI_SEMVER_REGEX = /\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?)\b/;
+function parseStellarCliVersion(output) {
+  const match = output.match(STELLAR_CLI_SEMVER_REGEX);
+  const version = match?.[1];
+  if (!version || !import_semver.default.valid(version)) {
+    throw new CaatingaError(
+      "Could not parse Stellar CLI version from command output.",
+      CaatingaErrorCode.STELLAR_CLI_VERSION_PARSE_FAILED,
+      "Run `stellar --version` and verify that the output includes a semantic version."
+    );
+  }
+  return version;
+}
+function assertSupportedStellarCliVersion(input) {
+  const normalizedVersion = import_semver.default.valid(input.version);
+  if (!normalizedVersion) {
+    throw new CaatingaError(
+      "Could not parse Stellar CLI version.",
+      CaatingaErrorCode.STELLAR_CLI_VERSION_PARSE_FAILED,
+      "Use a semantic version such as 22.0.1."
+    );
+  }
+  if (import_semver.default.lt(normalizedVersion, STELLAR_CLI_MIN_VERSION)) {
+    throw new CaatingaError(
+      `Stellar CLI ${normalizedVersion} is below the supported minimum ${STELLAR_CLI_MIN_VERSION}.`,
+      CaatingaErrorCode.UNSUPPORTED_CLI_VERSION,
+      `Install Stellar CLI ${STELLAR_CLI_MIN_VERSION} or newer.`
+    );
+  }
+  if (!input.allowUntested && import_semver.default.gt(normalizedVersion, STELLAR_CLI_TESTED_MAX_VERSION)) {
+    throw new CaatingaError(
+      `Stellar CLI ${normalizedVersion} is newer than the tested maximum ${STELLAR_CLI_TESTED_MAX_VERSION}.`,
+      CaatingaErrorCode.UNTESTED_CLI_VERSION,
+      "Pass --allow-untested-stellar-cli only after accepting the compatibility risk."
+    );
+  }
+  return normalizedVersion;
+}
+
+// src/stellar-cli/check-stellar-cli-version.ts
+async function checkStellarCliVersion(input) {
+  try {
+    const result = await runCommand("stellar", ["--version"], {
+      skipStellarVersionCheck: true
+    });
+    const output = result.all || result.stdout || result.stderr;
+    return assertSupportedStellarCliVersion({
+      version: parseStellarCliVersion(output),
+      allowUntested: input.allowUntested
+    });
+  } catch (error) {
+    if (typeof error === "object" && error && "code" in error && error.code === "ENOENT") {
+      throw new CaatingaError(
+        "Stellar CLI was not found.",
+        CaatingaErrorCode.STELLAR_CLI_NOT_FOUND,
+        "Install Stellar CLI before running Caatinga-backed commands.",
+        error
+      );
+    }
+    throw error;
+  }
+}
+
+// src/shell/run-command.ts
+async function runCommand(command, args, options = {}) {
+  try {
+    if (command === "stellar" && !options.skipStellarVersionCheck) {
+      await checkStellarCliVersion({
+        allowUntested: options.allowUntestedStellarCli === true
+      });
+    }
+    const result = await (0, import_execa.execa)(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      all: true,
+      reject: true
+    });
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      all: result.all ?? ""
+    };
+  } catch (error) {
+    if (error instanceof CaatingaError) {
+      throw error;
+    }
+    if (command === "stellar" && typeof error === "object" && error && "code" in error && error.code === "ENOENT") {
+      throw new CaatingaError(
+        "Stellar CLI was not found.",
+        CaatingaErrorCode.STELLAR_CLI_NOT_FOUND,
+        "Install Stellar CLI before running Caatinga-backed commands.",
+        error
+      );
+    }
+    const output = typeof error === "object" && error && "all" in error ? String(error.all) : void 0;
+    throw new CaatingaError(
+      `Command failed: ${command} ${args.join(" ")}`,
+      options.failureCode ?? CaatingaErrorCode.COMMAND_FAILED,
+      output || "Re-run the command with the underlying tool directly for full diagnostics.",
+      error
+    );
+  }
+}
+
+// src/shell/check-binary.ts
+async function checkBinary(binary, hint, options = {}) {
+  try {
+    await runCommand(binary, ["--version"], options);
+  } catch (error) {
+    if (error instanceof CaatingaError) {
+      throw error;
+    }
+    const code = binary === "stellar" ? CaatingaErrorCode.STELLAR_CLI_NOT_FOUND : binary === "rustc" ? CaatingaErrorCode.RUST_NOT_FOUND : CaatingaErrorCode.COMMAND_FAILED;
+    throw new CaatingaError(`${binary} was not found.`, code, hint, error);
+  }
+}
+
+// src/stellar-cli/parse-contract-id.ts
+var CONTRACT_ID_REGEX = /\bC[A-Z0-9]{55}\b/;
+function parseContractId(output) {
+  const match = output.match(CONTRACT_ID_REGEX);
+  if (!match) {
+    throw new CaatingaError(
+      "Could not find contract ID in Stellar CLI output.",
+      CaatingaErrorCode.CONTRACT_ID_NOT_FOUND,
+      "Check whether the Stellar CLI output format changed."
+    );
+  }
+  return match[0];
+}
+
+// src/contracts/resolve-contract.ts
+var import_node_path4 = __toESM(require("path"), 1);
+function resolveContract(config, contractName, cwd = process.cwd()) {
+  const contract = config.contracts[contractName];
+  if (!contract) {
+    throw new CaatingaError(
+      `Contract "${contractName}" is not configured.`,
+      CaatingaErrorCode.CONTRACT_NOT_FOUND,
+      `Add "${contractName}" to caatinga.config.ts contracts, or pass a configured contract name.`
+    );
+  }
+  return {
+    name: contractName,
+    config: contract,
+    sourcePath: import_node_path4.default.resolve(cwd, contract.path),
+    wasmPath: import_node_path4.default.resolve(cwd, contract.wasm)
+  };
+}
+
+// src/contracts/wasm.ts
+var import_node_crypto = require("crypto");
+var import_promises4 = require("fs/promises");
+async function assertWasmExists(wasmPath) {
+  try {
+    await (0, import_promises4.access)(wasmPath);
+  } catch {
+    throw new CaatingaError(
+      `WASM output was not found at ${wasmPath}.`,
+      CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+      "Run caatinga build before deploy or generate."
+    );
+  }
+}
+async function hashWasm(wasmPath) {
+  const bytes = await (0, import_promises4.readFile)(wasmPath);
+  return (0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex");
+}
+
+// src/contracts/build-contract.ts
+var RUST_WASM_TARGET = "wasm32-unknown-unknown";
+var MISSING_WASM_TARGET_HINT_SUBSTRINGS = [
+  "not installed",
+  "not found",
+  "needs to be installed",
+  "add the",
+  "rustup target"
+];
+function isMissingRustWasmTargetError(error) {
+  if (!(error instanceof CaatingaError)) {
+    return false;
+  }
+  const parts = [
+    error.message,
+    error.hint ?? "",
+    error.cause === void 0 ? "" : String(error.cause)
+  ];
+  const haystack = parts.join("\n").toLowerCase();
+  if (!haystack.includes(RUST_WASM_TARGET)) {
+    return false;
+  }
+  return MISSING_WASM_TARGET_HINT_SUBSTRINGS.some((needle) => haystack.includes(needle));
+}
+async function buildContract(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const contract = resolveContract(options.config, options.contractName, cwd);
+  await checkBinary("rustc", "Install Rust before running caatinga build.");
+  await checkBinary("stellar", "Install Stellar CLI before running caatinga build.", {
+    allowUntestedStellarCli: options.allowUntestedStellarCli
+  });
+  let result;
+  try {
+    result = await runCommand("stellar", ["contract", "build"], {
+      cwd: contract.sourcePath,
+      allowUntestedStellarCli: options.allowUntestedStellarCli,
+      failureCode: CaatingaErrorCode.BUILD_FAILED
+    });
+  } catch (error) {
+    if (error instanceof CaatingaError && error.code === CaatingaErrorCode.BUILD_FAILED && isMissingRustWasmTargetError(error)) {
+      throw new CaatingaError(
+        `Required Rust wasm target "${RUST_WASM_TARGET}" is missing.`,
+        CaatingaErrorCode.RUST_TARGET_NOT_FOUND,
+        `Run \`rustup target add ${RUST_WASM_TARGET}\` and retry the build.`,
+        error
+      );
+    }
+    throw error;
+  }
+  await assertWasmExists(contract.wasmPath);
+  return {
+    contract,
+    output: result.all || result.stdout
+  };
+}
+
+// src/contracts/deploy-contract.ts
+var import_node_path5 = __toESM(require("path"), 1);
+
+// src/contracts/dependency-graph.ts
+function buildDependencyGraph(contracts) {
+  const graph = {};
+  for (const name of Object.keys(contracts)) {
+    graph[name] = [...contracts[name].dependsOn];
+  }
+  return graph;
+}
+
+// src/contracts/resolve-deploy-args.ts
+var CONTRACT_ID_PLACEHOLDER = /^\$\{contracts\.([A-Za-z0-9_-]+)\.contractId\}$/;
+function resolveDeployArgs(input) {
+  const resolved = {};
+  for (const [key, value] of Object.entries(input.deployArgs)) {
+    if (typeof value !== "string" || !value.includes("${")) {
+      resolved[key] = value;
+      continue;
+    }
+    const match = value.match(CONTRACT_ID_PLACEHOLDER);
+    if (!match) {
+      throw new CaatingaError(
+        `Deploy arg "${key}" contains an unsupported placeholder.`,
+        CaatingaErrorCode.DEPLOY_ARG_PLACEHOLDER_INVALID,
+        "Use only ${contracts.<contractName>.contractId}."
+      );
+    }
+    const contractName = match[1];
+    const contractArtifact = input.artifacts.networks[input.network]?.contracts[contractName];
+    if (!contractArtifact?.contractId) {
+      throw new CaatingaError(
+        `No dependency artifact found for "${contractName}" on "${input.network}".`,
+        CaatingaErrorCode.CONTRACT_DEPENDENCY_ARTIFACT_NOT_FOUND,
+        "Deploy the dependency first or run deploy without --no-deps."
+      );
+    }
+    resolved[key] = contractArtifact.contractId;
+  }
+  return resolved;
+}
+
+// src/contracts/source-account.ts
+function assertSafeSourceAccount(source) {
+  if (!source) {
+    throw new CaatingaError(
+      "A source account or Stellar CLI identity is required.",
+      CaatingaErrorCode.SOURCE_ACCOUNT_REQUIRED,
+      "Pass --source alice or --source G...; do not pass secret keys or seed phrases."
+    );
+  }
+  if (source.startsWith("S") || source.trim().includes(" ")) {
+    throw new CaatingaError(
+      "Refusing to accept a likely secret key or seed phrase as --source.",
+      CaatingaErrorCode.UNSAFE_SOURCE_ACCOUNT,
+      "Use a Stellar CLI identity alias or public account address instead."
+    );
+  }
+  return source;
+}
+
+// src/contracts/deploy-contract.ts
+function toSnakeCaseFlag(key) {
+  return key.replace(/([A-Z])/g, "_$1").replace(/^_/, "").toLowerCase();
+}
+function formatConstructorCliArgs(resolved) {
+  const entries = Object.entries(resolved);
+  if (entries.length === 0) {
+    return [];
+  }
+  const tail = ["--"];
+  for (const [key, value] of entries) {
+    tail.push(`--${toSnakeCaseFlag(key)}`, String(value));
+  }
+  return tail;
+}
+async function deployContract(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const contract = resolveContract(options.config, options.contractName, cwd);
+  const network = resolveNetwork(options.config, options.networkName);
+  const source = assertSafeSourceAccount(options.source);
+  await checkBinary("stellar", "Install Stellar CLI before running caatinga deploy.", {
+    allowUntestedStellarCli: options.allowUntestedStellarCli
+  });
+  await assertWasmExists(contract.wasmPath);
+  const artifactsBefore = await readArtifacts(cwd);
+  const existing = artifactsBefore.networks[network.name]?.contracts[contract.name];
+  if (existing?.contractId && !options.force) {
+    return {
+      contract,
+      network,
+      contractId: existing.contractId,
+      artifactsPath: import_node_path5.default.resolve(cwd, "caatinga.artifacts.json"),
+      output: "",
+      skipped: true
+    };
+  }
+  const rawDeployArgs = contract.config.deployArgs;
+  const hasConfiguredArgs = Object.keys(rawDeployArgs).length > 0;
+  let resolvedDeployArgs;
+  if (options.resolvedDeployArgs !== void 0) {
+    resolvedDeployArgs = options.resolvedDeployArgs;
+  } else if (hasConfiguredArgs) {
+    resolvedDeployArgs = resolveDeployArgs({
+      deployArgs: rawDeployArgs,
+      artifacts: artifactsBefore,
+      network: network.name
+    });
+  } else {
+    resolvedDeployArgs = {};
+  }
+  for (const value of Object.values(resolvedDeployArgs)) {
+    if (typeof value === "string" && value.includes("${")) {
+      throw new CaatingaError(
+        `Deploy args for "${contract.name}" still contain unresolved placeholders.`,
+        CaatingaErrorCode.DEPLOY_ARG_PLACEHOLDER_UNRESOLVED,
+        "Deploy dependencies first or fix deployArgs templates."
+      );
+    }
+  }
+  const constructorArgs = formatConstructorCliArgs(resolvedDeployArgs);
+  const stellarArgs = [
+    "contract",
+    "deploy",
+    "--wasm",
+    contract.wasmPath,
+    "--source-account",
+    source,
+    "--rpc-url",
+    network.config.rpcUrl,
+    "--network-passphrase",
+    network.config.networkPassphrase,
+    ...constructorArgs
+  ];
+  const result = await runCommand("stellar", stellarArgs, {
+    cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli,
+    failureCode: CaatingaErrorCode.DEPLOY_FAILED
+  });
+  const output = result.all || `${result.stdout}
+${result.stderr}`;
+  const contractId = parseContractId(output);
+  const wasmHash = await hashWasm(contract.wasmPath);
+  const dependencyGraph = buildDependencyGraph(options.config.contracts);
+  const dependencies = options.dependencies ?? contract.config.dependsOn;
+  const nextArtifacts = updateArtifact(
+    artifactsBefore,
+    network.name,
+    contract.name,
+    {
+      contractId,
+      wasmHash,
+      deployedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      sourcePath: contract.config.path,
+      wasmPath: contract.config.wasm,
+      dependencies,
+      resolvedDeployArgs
+    },
+    { dependencyGraph }
+  );
+  const artifactsPath = await writeArtifacts(nextArtifacts, cwd);
+  return {
+    contract,
+    network,
+    contractId,
+    artifactsPath,
+    output,
+    skipped: false
+  };
+}
+
+// src/contracts/resolve-deploy-order.ts
+function resolveDeployOrder(input) {
+  const order = [];
+  const state = /* @__PURE__ */ new Map();
+  const selected = input.selectedContract ? [input.selectedContract] : Object.keys(input.contracts);
+  for (const contractName of selected) {
+    visit(contractName, []);
+  }
+  return order;
+  function visit(contractName, stack) {
+    const contract = input.contracts[contractName];
+    if (!contract) {
+      throw new CaatingaError(
+        `Contract dependency "${contractName}" was not found.`,
+        CaatingaErrorCode.CONTRACT_DEPENDENCY_NOT_FOUND,
+        "Add the dependency to caatinga.config.ts or remove it from dependsOn."
+      );
+    }
+    if (state.get(contractName) === "visited") {
+      return;
+    }
+    if (state.get(contractName) === "visiting") {
+      throw new CaatingaError(
+        `Contract dependency cycle detected: ${[...stack, contractName].join(" -> ")}.`,
+        CaatingaErrorCode.CONTRACT_DEPENDENCY_CYCLE,
+        "Remove the cycle from dependsOn."
+      );
+    }
+    state.set(contractName, "visiting");
+    if (input.includeDependencies) {
+      for (const dependency of contract.dependsOn) {
+        visit(dependency, [...stack, contractName]);
+      }
+    } else if (contract.dependsOn.length > 0 && input.selectedContract === contractName) {
+      for (const dependency of contract.dependsOn) {
+        if (!input.contracts[dependency]) {
+          throw new CaatingaError(
+            `Contract dependency "${dependency}" was not found.`,
+            CaatingaErrorCode.CONTRACT_DEPENDENCY_NOT_FOUND,
+            "Add the dependency to caatinga.config.ts or remove it from dependsOn."
+          );
+        }
+      }
+    }
+    state.set(contractName, "visited");
+    if (!order.includes(contractName)) {
+      order.push(contractName);
+    }
+  }
+}
+
+// src/contracts/deploy-contract-graph.ts
+async function deployContractGraph(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const network = resolveNetwork(options.config, options.networkName);
+  const order = resolveDeployOrder({
+    contracts: options.config.contracts,
+    selectedContract: options.contractName,
+    includeDependencies: options.includeDependencies
+  });
+  const deployedContracts = [];
+  for (const contractName of order) {
+    const artifacts = await readArtifacts(cwd);
+    const existing = artifacts.networks[network.name]?.contracts[contractName];
+    const contractConfig = options.config.contracts[contractName];
+    const resolvedDeployArgs = resolveDeployArgs({
+      deployArgs: contractConfig.deployArgs,
+      artifacts,
+      network: network.name
+    });
+    if (existing?.contractId && !options.force) {
+      deployedContracts.push({ name: contractName, contractId: existing.contractId });
+      continue;
+    }
+    const result = await deployContract({
+      config: options.config,
+      contractName,
+      networkName: network.name,
+      source: options.source,
+      cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli,
+      force: options.force,
+      resolvedDeployArgs,
+      dependencies: contractConfig.dependsOn
+    });
+    deployedContracts.push({ name: contractName, contractId: result.contractId });
+  }
+  return {
+    network,
+    deployedContracts
+  };
+}
+
+// src/contracts/generate-bindings.ts
+var import_promises5 = require("fs/promises");
+var import_node_path6 = __toESM(require("path"), 1);
+async function generateBindings(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const network = resolveNetwork(options.config, options.networkName);
+  const artifacts = await readArtifacts(cwd);
+  const contractArtifact = artifacts.networks[network.name]?.contracts[options.contractName];
+  if (!contractArtifact) {
+    throw new CaatingaError(
+      `No deployed artifact found for "${options.contractName}" on "${network.name}".`,
+      CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+      "Run caatinga deploy for this contract and network before generating bindings."
+    );
+  }
+  await checkBinary("stellar", "Install Stellar CLI before running caatinga generate.", {
+    allowUntestedStellarCli: options.allowUntestedStellarCli
+  });
+  const outputDir = import_node_path6.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  await (0, import_promises5.mkdir)(outputDir, { recursive: true });
+  const result = await runCommand("stellar", [
+    "contract",
+    "bindings",
+    "typescript",
+    "--contract-id",
+    contractArtifact.contractId,
+    "--output-dir",
+    outputDir,
+    "--overwrite",
+    "--rpc-url",
+    network.config.rpcUrl,
+    "--network-passphrase",
+    network.config.networkPassphrase
+  ], {
+    cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli,
+    failureCode: CaatingaErrorCode.BINDINGS_FAILED
+  });
+  return {
+    contractName: options.contractName,
+    network,
+    outputDir,
+    output: result.all || result.stdout
+  };
+}
+
+// src/contracts/invoke-contract.ts
+function parseInvokeTarget(target) {
+  const [contractName, method, extra] = target.split(".");
+  if (!contractName || !method || extra) {
+    throw new CaatingaError(
+      `Invalid invoke target "${target}".`,
+      CaatingaErrorCode.INVOKE_TARGET_INVALID,
+      "Use the format contract.method, for example counter.increment."
+    );
+  }
+  return { contractName, method };
+}
+async function invokeContract(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const network = resolveNetwork(options.config, options.networkName);
+  const target = parseInvokeTarget(options.target);
+  const source = assertSafeSourceAccount(options.source);
+  const artifacts = await readArtifacts(cwd);
+  const contractArtifact = artifacts.networks[network.name]?.contracts[target.contractName];
+  if (!contractArtifact) {
+    throw new CaatingaError(
+      `No deployed artifact found for "${target.contractName}" on "${network.name}".`,
+      CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+      "Run caatinga deploy for this contract and network before invoking it."
+    );
+  }
+  await checkBinary("stellar", "Install Stellar CLI before running caatinga invoke.", {
+    allowUntestedStellarCli: options.allowUntestedStellarCli
+  });
+  const result = await runCommand("stellar", [
+    "contract",
+    "invoke",
+    "--id",
+    contractArtifact.contractId,
+    "--source-account",
+    source,
+    "--rpc-url",
+    network.config.rpcUrl,
+    "--network-passphrase",
+    network.config.networkPassphrase,
+    "--",
+    target.method,
+    ...options.args ?? []
+  ], {
+    cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli,
+    failureCode: CaatingaErrorCode.INVOKE_FAILED
+  });
+  return {
+    target,
+    network,
+    result: result.stdout || result.all
+  };
+}
+
+// src/templates/create-project-from-template.ts
+var import_promises6 = require("fs/promises");
+var import_node_path7 = __toESM(require("path"), 1);
+var import_zod6 = require("zod");
+
+// src/templates/template-manifest.schema.ts
+var import_zod5 = require("zod");
+var import_semver2 = __toESM(require("semver"), 1);
+var CURRENT_TEMPLATE_VERSION = 1;
+var TemplateManifestSchema = import_zod5.z.object({
+  name: import_zod5.z.string().min(1),
+  version: import_zod5.z.string().min(1),
+  description: import_zod5.z.string().optional(),
+  caatinga: import_zod5.z.object({
+    compatibleCore: import_zod5.z.string().min(1),
+    templateVersion: import_zod5.z.number().int().positive()
+  }),
+  frontend: import_zod5.z.object({
+    framework: import_zod5.z.enum(["vite-react", "next", "astro"]),
+    packageManager: import_zod5.z.enum(["npm", "pnpm", "yarn", "bun"]).default("npm")
+  }),
+  contracts: import_zod5.z.object({
+    path: import_zod5.z.string(),
+    default: import_zod5.z.string().optional()
+  }),
+  files: import_zod5.z.object({
+    config: import_zod5.z.string().default("caatinga.config.ts"),
+    artifacts: import_zod5.z.string().default("caatinga.artifacts.json")
+  })
+});
+function isCoreVersionCompatible(range, coreVersion = CAATINGA_CORE_VERSION) {
+  return import_semver2.default.satisfies(coreVersion, range);
+}
+
+// src/templates/create-project-from-template.ts
+async function createProjectFromTemplate(options) {
+  const targetDir = import_node_path7.default.resolve(options.targetDir);
+  const templateDir = import_node_path7.default.resolve(options.templateDir);
+  try {
+    await (0, import_promises6.stat)(templateDir);
+  } catch {
+    throw new CaatingaError(
+      `Template directory was not found: ${templateDir}`,
+      CaatingaErrorCode.TEMPLATE_NOT_FOUND,
+      "Use a bundled Caatinga template or set CAATINGA_TEMPLATES_DIR for local development."
+    );
+  }
+  const manifest = await readTemplateManifest(templateDir);
+  await (0, import_promises6.mkdir)(targetDir, { recursive: true });
+  await (0, import_promises6.cp)(templateDir, targetDir, {
+    recursive: true,
+    force: false,
+    errorOnExist: true
+  });
+  await replaceTemplateVariables(targetDir, options.projectName);
+  await writeArtifacts(createInitialArtifacts(options.projectName), targetDir);
+  return { targetDir, template: manifest };
+}
+async function readTemplateManifest(templateDir) {
+  const manifestPath = import_node_path7.default.join(templateDir, "caatinga.template.json");
+  try {
+    const rawManifest = await (0, import_promises6.readFile)(manifestPath, "utf8");
+    const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
+    if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
+      throw new CaatingaError(
+        "Template is not compatible with this Caatinga version.",
+        CaatingaErrorCode.TEMPLATE_INCOMPATIBLE,
+        "Use a compatible template version or upgrade Caatinga."
+      );
+    }
+    if (!isCoreVersionCompatible(manifest.caatinga.compatibleCore)) {
+      throw new CaatingaError(
+        "Template is not compatible with this Caatinga version.",
+        CaatingaErrorCode.TEMPLATE_INCOMPATIBLE,
+        "Use a compatible template version or upgrade Caatinga."
+      );
+    }
+    return manifest;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new CaatingaError(
+        "Template manifest was not found.",
+        CaatingaErrorCode.TEMPLATE_MANIFEST_NOT_FOUND,
+        "Add a caatinga.template.json file to the template root."
+      );
+    }
+    if (error instanceof CaatingaError) {
+      throw error;
+    }
+    if (error instanceof SyntaxError || error instanceof import_zod6.z.ZodError) {
+      throw new CaatingaError(
+        "Template manifest is invalid.",
+        CaatingaErrorCode.INVALID_TEMPLATE_MANIFEST,
+        "Fix caatinga.template.json so it is valid JSON and matches the template manifest schema."
+      );
+    }
+    throw error;
+  }
+}
+async function replaceTemplateVariables(dir, projectName) {
+  const entries = await (0, import_promises6.readdir)(dir);
+  await Promise.all(entries.map(async (entry) => {
+    const entryPath = import_node_path7.default.join(dir, entry);
+    const entryStat = await (0, import_promises6.stat)(entryPath);
+    if (entryStat.isDirectory()) {
+      await replaceTemplateVariables(entryPath, projectName);
+      return;
+    }
+    if (!isTextTemplateFile(entryPath)) {
+      return;
+    }
+    const content = await (0, import_promises6.readFile)(entryPath, "utf8");
+    await (0, import_promises6.writeFile)(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
+  }));
+}
+function isTextTemplateFile(filePath) {
+  return [
+    ".json",
+    ".md",
+    ".rs",
+    ".toml",
+    ".ts",
+    ".tsx",
+    ".css",
+    ".html"
+  ].includes(import_node_path7.default.extname(filePath));
+}
+
+// src/ci/is-transient-testnet-smoke-failure.ts
+var NO_RETRY_CAATINGA_SUBSTRINGS = [
+  "CAATINGA_UNSUPPORTED_CLI_VERSION",
+  "CAATINGA_UNTESTED_CLI_VERSION",
+  "CAATINGA_STELLAR_CLI_VERSION_PARSE_FAILED",
+  "CAATINGA_STELLAR_CLI_NOT_FOUND",
+  "CAATINGA_INVALID_CONFIG",
+  "CAATINGA_CONFIG_NOT_FOUND"
+];
+var TRANSIENT_PATTERN = /timeout|i\/o timeout|econnreset|connection reset|503|502|429|rate limit|temporar|bad gateway|fetch failed|network error|unavailable/i;
+function isTransientTestnetSmokeFailure(logText) {
+  if (!logText.trim()) {
+    return false;
+  }
+  for (const marker of NO_RETRY_CAATINGA_SUBSTRINGS) {
+    if (logText.includes(marker)) {
+      return false;
+    }
+  }
+  return TRANSIENT_PATTERN.test(logText);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CAATINGA_CORE_VERSION,
+  CaatingaArtifactsSchema,
+  CaatingaConfigSchema,
+  CaatingaError,
+  CaatingaErrorCode,
+  STELLAR_CLI_MIN_VERSION,
+  STELLAR_CLI_TESTED_MAX_VERSION,
+  TemplateManifestSchema,
+  WELL_KNOWN_NETWORKS,
+  assertSupportedStellarCliVersion,
+  buildContract,
+  buildDependencyGraph,
+  checkBinary,
+  createInitialArtifacts,
+  createProjectFromTemplate,
+  defineConfig,
+  deployContract,
+  deployContractGraph,
+  generateBindings,
+  invokeContract,
+  isTransientTestnetSmokeFailure,
+  loadConfig,
+  parseContractId,
+  parseInvokeTarget,
+  parseStellarCliVersion,
+  readArtifacts,
+  resolveContract,
+  resolveDeployArgs,
+  resolveDeployOrder,
+  resolveNetwork,
+  runCommand,
+  toCaatingaError,
+  updateArtifact,
+  writeArtifacts
+});