@caatinga/core 0.2.0

package/dist/index.js

@@ -0,0 +1,1033 @@
+// 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
+import { z } from "zod";
+var DeployArgValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+var ContractConfigSchema = z.object({
+  path: z.string().min(1),
+  wasm: z.string().min(1),
+  dependsOn: z.array(z.string().min(1)).default([]),
+  deployArgs: z.record(z.string().min(1), DeployArgValueSchema).default({})
+});
+var NetworkConfigSchema = z.object({
+  rpcUrl: z.string().url(),
+  networkPassphrase: z.string().min(1)
+});
+var CaatingaConfigSchema = z.object({
+  project: z.string().min(1),
+  defaultNetwork: z.string().min(1).default("testnet"),
+  contracts: z.record(z.string().min(1), ContractConfigSchema).refine(
+    (contracts) => Object.keys(contracts).length > 0,
+    "At least one contract must be configured."
+  ),
+  networks: z.record(z.string().min(1), NetworkConfigSchema).refine(
+    (networks) => Object.keys(networks).length > 0,
+    "At least one network must be configured."
+  ),
+  frontend: z.object({
+    framework: z.enum(["vite-react", "next", "astro"]).default("vite-react"),
+    bindingsOutput: z.string().min(1)
+  })
+});
+
+// src/config/define-config.ts
+function defineConfig(config) {
+  return config;
+}
+
+// src/config/load-config.ts
+import { access } from "fs/promises";
+import path from "path";
+import { createJiti } from "jiti";
+import { z as z2 } from "zod";
+async function loadConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = path.resolve(cwd, options.configPath ?? "caatinga.config.ts");
+  try {
+    await 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 = createJiti(import.meta.url);
+    const loaded = await jiti.import(configPath, { default: true });
+    return CaatingaConfigSchema.parse(loaded);
+  } catch (error) {
+    if (error instanceof z2.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
+import { z as z3 } from "zod";
+var ContractArtifactSchema = z3.object({
+  contractId: z3.string().min(1),
+  wasmHash: z3.string().min(1),
+  deployedAt: z3.string().datetime(),
+  sourcePath: z3.string().min(1),
+  wasmPath: z3.string().min(1),
+  dependencies: z3.array(z3.string().min(1)).default([]),
+  resolvedDeployArgs: z3.record(z3.string().min(1), z3.union([z3.string(), z3.number(), z3.boolean()])).default({})
+});
+var NetworkArtifactsSchema = z3.object({
+  contracts: z3.record(z3.string().min(1), ContractArtifactSchema).default({}),
+  dependencyGraph: z3.record(z3.string().min(1), z3.array(z3.string().min(1))).default({})
+});
+var CaatingaArtifactsSchema = z3.object({
+  project: z3.string().min(1),
+  version: z3.literal(1),
+  networks: z3.record(z3.string().min(1), NetworkArtifactsSchema).default({})
+});
+
+// src/artifacts/read-artifacts.ts
+import { readFile } from "fs/promises";
+import path2 from "path";
+import { z as z4 } from "zod";
+async function readArtifacts(cwd = process.cwd()) {
+  const artifactsPath = path2.resolve(cwd, "caatinga.artifacts.json");
+  try {
+    const json = await 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 z4.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
+import { mkdir, writeFile } from "fs/promises";
+import path3 from "path";
+async function writeArtifacts(artifacts, cwd = process.cwd()) {
+  const artifactsPath = path3.resolve(cwd, "caatinga.artifacts.json");
+  await mkdir(path3.dirname(artifactsPath), { recursive: true });
+  await 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
+import { execa } from "execa";
+
+// src/stellar-cli/version.ts
+import semver from "semver";
+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 || !semver.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 = semver.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 (semver.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 && semver.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 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
+import path4 from "path";
+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: path4.resolve(cwd, contract.path),
+    wasmPath: path4.resolve(cwd, contract.wasm)
+  };
+}
+
+// src/contracts/wasm.ts
+import { createHash } from "crypto";
+import { access as access2, readFile as readFile2 } from "fs/promises";
+async function assertWasmExists(wasmPath) {
+  try {
+    await access2(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 readFile2(wasmPath);
+  return 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
+import path5 from "path";
+
+// 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: path5.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
+import { mkdir as mkdir2 } from "fs/promises";
+import path6 from "path";
+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 = path6.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  await mkdir2(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
+import { cp, mkdir as mkdir3, readFile as readFile3, readdir, stat, writeFile as writeFile2 } from "fs/promises";
+import path7 from "path";
+import { z as z6 } from "zod";
+
+// src/templates/template-manifest.schema.ts
+import { z as z5 } from "zod";
+import semver2 from "semver";
+var CURRENT_TEMPLATE_VERSION = 1;
+var TemplateManifestSchema = z5.object({
+  name: z5.string().min(1),
+  version: z5.string().min(1),
+  description: z5.string().optional(),
+  caatinga: z5.object({
+    compatibleCore: z5.string().min(1),
+    templateVersion: z5.number().int().positive()
+  }),
+  frontend: z5.object({
+    framework: z5.enum(["vite-react", "next", "astro"]),
+    packageManager: z5.enum(["npm", "pnpm", "yarn", "bun"]).default("npm")
+  }),
+  contracts: z5.object({
+    path: z5.string(),
+    default: z5.string().optional()
+  }),
+  files: z5.object({
+    config: z5.string().default("caatinga.config.ts"),
+    artifacts: z5.string().default("caatinga.artifacts.json")
+  })
+});
+function isCoreVersionCompatible(range, coreVersion = CAATINGA_CORE_VERSION) {
+  return semver2.satisfies(coreVersion, range);
+}
+
+// src/templates/create-project-from-template.ts
+async function createProjectFromTemplate(options) {
+  const targetDir = path7.resolve(options.targetDir);
+  const templateDir = path7.resolve(options.templateDir);
+  try {
+    await 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 mkdir3(targetDir, { recursive: true });
+  await 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 = path7.join(templateDir, "caatinga.template.json");
+  try {
+    const rawManifest = await readFile3(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 z6.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 readdir(dir);
+  await Promise.all(entries.map(async (entry) => {
+    const entryPath = path7.join(dir, entry);
+    const entryStat = await stat(entryPath);
+    if (entryStat.isDirectory()) {
+      await replaceTemplateVariables(entryPath, projectName);
+      return;
+    }
+    if (!isTextTemplateFile(entryPath)) {
+      return;
+    }
+    const content = await readFile3(entryPath, "utf8");
+    await writeFile2(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
+  }));
+}
+function isTextTemplateFile(filePath) {
+  return [
+    ".json",
+    ".md",
+    ".rs",
+    ".toml",
+    ".ts",
+    ".tsx",
+    ".css",
+    ".html"
+  ].includes(path7.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);
+}
+export {
+  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
+};