@caatinga/core 2.3.1 → 2.4.1

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/errors/CaatingaErrorCode.ts
 var CaatingaErrorCode = {
   CONFIG_NOT_FOUND: "CAATINGA_CONFIG_NOT_FOUND",
+  DEPENDENCIES_NOT_INSTALLED: "CAATINGA_DEPENDENCIES_NOT_INSTALLED",
   INVALID_CONFIG: "CAATINGA_INVALID_CONFIG",
   COMMAND_FAILED: "CAATINGA_COMMAND_FAILED",
   UNEXPECTED_ERROR: "CAATINGA_UNEXPECTED_ERROR",
@@ -105,7 +106,7 @@ function formatCause(cause) {
 }
 
 // src/version.ts
-var CAATINGA_CORE_VERSION = "2.3.1";
+var CAATINGA_CORE_VERSION = "2.4.1";
 
 // src/config/config.schema.ts
 import { z } from "zod";
@@ -157,6 +158,28 @@ import { access } from "fs/promises";
 import path from "path";
 import { createJiti } from "jiti";
 import { z as z2 } from "zod";
+
+// src/config/is-dependencies-not-installed-error.ts
+function isDependenciesNotInstalledError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const candidate = error;
+  const code = candidate.code;
+  const message = String(candidate.message ?? error);
+  if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+    return /@caatinga\/core/.test(message);
+  }
+  if (/Cannot find (module|package).+@caatinga\/core/i.test(message)) {
+    return true;
+  }
+  if (candidate.cause !== void 0) {
+    return isDependenciesNotInstalledError(candidate.cause);
+  }
+  return false;
+}
+
+// src/config/load-config.ts
 async function loadConfig(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const configPath = path.resolve(cwd, options.configPath ?? "caatinga.config.ts");
@@ -181,6 +204,14 @@ async function loadConfig(options = {}) {
         error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
       );
     }
+    if (isDependenciesNotInstalledError(error)) {
+      throw new CaatingaError(
+        "Project dependencies are not installed.",
+        CaatingaErrorCode.DEPENDENCIES_NOT_INSTALLED,
+        "Run npm install (or pnpm install) in the project root, then retry.",
+        error
+      );
+    }
     throw error;
   }
 }
@@ -587,6 +618,64 @@ function defaultEmitWarning(warning) {
 `);
 }
 
+// src/shell/resolve-subprocess-env.ts
+import { existsSync } from "fs";
+import os from "os";
+import path6 from "path";
+function uniquePaths(entries) {
+  const seen = /* @__PURE__ */ new Set();
+  const ordered = [];
+  for (const entry of entries) {
+    if (!entry || seen.has(entry)) {
+      continue;
+    }
+    seen.add(entry);
+    ordered.push(entry);
+  }
+  return ordered;
+}
+function hasExecutable(binDir, name) {
+  return existsSync(path6.join(binDir, name));
+}
+function toolchainBinDirs(home, env) {
+  const candidates = [
+    path6.join(home, ".cargo", "bin"),
+    env.CARGO_HOME ? path6.join(env.CARGO_HOME, "bin") : void 0
+  ];
+  return candidates.filter((entry) => Boolean(entry && existsSync(entry)));
+}
+function buildToolchainPrepend(existingPath, toolchainBins, executableExists = hasExecutable) {
+  const prepend = [];
+  for (const binDir of toolchainBins) {
+    const externalStellarDir = existingPath.find(
+      (entry) => entry !== binDir && executableExists(entry, "stellar")
+    );
+    if (externalStellarDir && executableExists(binDir, "stellar")) {
+      prepend.push(externalStellarDir);
+    }
+    prepend.push(binDir);
+  }
+  return prepend;
+}
+function resolveSubprocessEnv(overrides = {}) {
+  const env = { ...process.env, ...overrides };
+  const home = env.HOME ?? os.homedir();
+  const existingPath = (env.PATH ?? "").split(path6.delimiter).filter(Boolean);
+  const toolchainBins = toolchainBinDirs(home, env);
+  const prepend = buildToolchainPrepend(existingPath, toolchainBins);
+  env.PATH = uniquePaths([...prepend, ...existingPath]).join(path6.delimiter);
+  return env;
+}
+function isCargoBinMissingFromPath(baseEnv = process.env) {
+  const home = baseEnv.HOME ?? os.homedir();
+  const cargoBin = path6.join(home, ".cargo", "bin", "cargo");
+  if (!existsSync(cargoBin)) {
+    return false;
+  }
+  const pathEntries = (baseEnv.PATH ?? "").split(path6.delimiter);
+  return !pathEntries.some((entry) => entry === path6.join(home, ".cargo", "bin"));
+}
+
 // src/shell/run-command.ts
 async function runCommand(command, args, options = {}) {
   try {
@@ -595,7 +684,7 @@ async function runCommand(command, args, options = {}) {
     }
     const result = await execa(command, args, {
       cwd: options.cwd,
-      env: options.env,
+      env: resolveSubprocessEnv(options.env ?? {}),
       input: options.input,
       all: true,
       reject: true
@@ -793,7 +882,7 @@ function validateSourceShape(source) {
 }
 
 // src/contracts/resolve-contract.ts
-import path6 from "path";
+import path7 from "path";
 function resolveContract(config, contractName, cwd = process.cwd()) {
   const contract = config.contracts[contractName];
   if (!contract) {
@@ -806,8 +895,8 @@ function resolveContract(config, contractName, cwd = process.cwd()) {
   return {
     name: contractName,
     config: contract,
-    sourcePath: path6.resolve(cwd, contract.path),
-    wasmPath: path6.resolve(cwd, contract.wasm)
+    sourcePath: path7.resolve(cwd, contract.path),
+    wasmPath: path7.resolve(cwd, contract.wasm)
   };
 }
 
@@ -827,7 +916,7 @@ function resolveDefaultContractName(config) {
 // src/contracts/wasm.ts
 import { createHash } from "crypto";
 import { access as access2, readdir as readdir2, readFile as readFile3, stat } from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 var LEGACY_RUST_WASM_TARGET = "wasm32-unknown-unknown";
 var CURRENT_RUST_WASM_TARGET = "wasm32v1-none";
 function toCurrentWasmTargetPath(wasmPath) {
@@ -838,36 +927,88 @@ function toCurrentWasmTargetPath(wasmPath) {
 }
 function wasmNotFoundError(configuredWasmPath, options) {
   const migratedPath = options?.migratedPath;
-  const hint = migratedPath === void 0 ? "Run caatinga build before deploy or generate." : [
-    "Run caatinga build before deploy or generate.",
-    `Soroban builds use the "${CURRENT_RUST_WASM_TARGET}" target.`,
-    `Update wasm in caatinga.config.ts to "${toConfigRelativeWasmPath(migratedPath)}" or an equivalent path under target/${CURRENT_RUST_WASM_TARGET}/release/.`
-  ].join(" ");
+  const cargoTargetDir = process.env.CARGO_TARGET_DIR;
+  const hintParts = ["Run caatinga build before deploy or generate."];
+  if (migratedPath !== void 0) {
+    hintParts.push(
+      `Soroban builds use the "${CURRENT_RUST_WASM_TARGET}" target.`,
+      `Update wasm in caatinga.config.ts to "${toConfigRelativeWasmPath(migratedPath)}" or an equivalent path under target/${CURRENT_RUST_WASM_TARGET}/release/.`
+    );
+  }
+  if (cargoTargetDir) {
+    hintParts.push(
+      `CARGO_TARGET_DIR is set to "${cargoTargetDir}"; the WASM may be under that directory instead of the configured path. Unset CARGO_TARGET_DIR or update wasm in caatinga.config.ts.`
+    );
+  }
   return new CaatingaError(
     `WASM output was not found at ${configuredWasmPath}.`,
     CaatingaErrorCode.ARTIFACT_NOT_FOUND,
-    hint
+    hintParts.join(" ")
   );
 }
 function toConfigRelativeWasmPath(absoluteWasmPath) {
-  const relative = path7.relative(process.cwd(), absoluteWasmPath);
-  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(path7.sep).join("/")}`;
+  const relative = path8.relative(process.cwd(), absoluteWasmPath);
+  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(path8.sep).join("/")}`;
+}
+function wasmFileName(configuredWasmPath) {
+  return path8.basename(configuredWasmPath);
+}
+function buildAlternateWasmCandidates(configuredWasmPath, options) {
+  const fileName = wasmFileName(configuredWasmPath);
+  const candidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  function addCandidate(candidate) {
+    const resolved = path8.resolve(candidate);
+    if (seen.has(resolved)) {
+      return;
+    }
+    seen.add(resolved);
+    candidates.push(resolved);
+  }
+  const cargoTargetDir = process.env.CARGO_TARGET_DIR;
+  if (cargoTargetDir) {
+    addCandidate(path8.join(cargoTargetDir, CURRENT_RUST_WASM_TARGET, "release", fileName));
+    addCandidate(path8.join(cargoTargetDir, LEGACY_RUST_WASM_TARGET, "release", fileName));
+  }
+  if (options?.sourcePath) {
+    addCandidate(path8.join(options.sourcePath, "target", CURRENT_RUST_WASM_TARGET, "release", fileName));
+    addCandidate(path8.join(options.sourcePath, "target", LEGACY_RUST_WASM_TARGET, "release", fileName));
+  }
+  return candidates;
 }
-async function resolveWasmArtifactPath(configuredWasmPath) {
+async function firstExistingPath(paths) {
+  for (const candidate of paths) {
+    try {
+      await access2(candidate);
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+  return void 0;
+}
+async function resolveWasmArtifactPath(configuredWasmPath, options) {
+  const resolvedConfiguredPath = path8.resolve(configuredWasmPath);
   try {
-    await access2(configuredWasmPath);
-    return configuredWasmPath;
+    await access2(resolvedConfiguredPath);
+    return resolvedConfiguredPath;
   } catch {
-    const currentTargetPath = toCurrentWasmTargetPath(configuredWasmPath);
-    if (currentTargetPath === configuredWasmPath) {
-      throw wasmNotFoundError(configuredWasmPath);
+    const currentTargetPath = toCurrentWasmTargetPath(resolvedConfiguredPath);
+    if (currentTargetPath !== resolvedConfiguredPath) {
+      const migratedPath = await firstExistingPath([currentTargetPath]);
+      if (migratedPath) {
+        return migratedPath;
+      }
     }
-    try {
-      await access2(currentTargetPath);
-      return currentTargetPath;
-    } catch {
-      throw wasmNotFoundError(configuredWasmPath, { migratedPath: currentTargetPath });
+    const alternatePath = await firstExistingPath(
+      buildAlternateWasmCandidates(resolvedConfiguredPath, options)
+    );
+    if (alternatePath) {
+      return alternatePath;
     }
+    throw wasmNotFoundError(resolvedConfiguredPath, {
+      migratedPath: currentTargetPath !== resolvedConfiguredPath ? currentTargetPath : void 0
+    });
   }
 }
 async function hashWasm(wasmPath) {
@@ -884,7 +1025,7 @@ async function getNewestMtimeInDirectory(directory) {
   async function walk(dir) {
     const entries = await readdir2(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const entryPath = path7.join(dir, entry.name);
+      const entryPath = path8.join(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(entryPath);
         continue;
@@ -900,7 +1041,7 @@ async function getNewestMtimeInDirectory(directory) {
   return newest > 0 ? newest : void 0;
 }
 async function isWasmOlderThanSources(input) {
-  const srcDir = path7.join(input.contractPath, "src");
+  const srcDir = path8.join(input.contractPath, "src");
   const newestSourceMtime = await getNewestMtimeInDirectory(srcDir);
   if (newestSourceMtime === void 0) {
     return false;
@@ -962,7 +1103,9 @@ async function buildContract(options) {
     }
     throw error;
   }
-  const wasmPath = await resolveWasmArtifactPath(contract.wasmPath);
+  const wasmPath = await resolveWasmArtifactPath(contract.wasmPath, {
+    sourcePath: contract.sourcePath
+  });
   return {
     contract: {
       ...contract,
@@ -973,7 +1116,7 @@ async function buildContract(options) {
 }
 
 // src/contracts/deploy-contract.ts
-import path8 from "path";
+import path9 from "path";
 
 // src/contracts/dependency-graph.ts
 function buildDependencyGraph(contracts) {
@@ -1030,6 +1173,9 @@ function assertSafeSourceAccount(source) {
   }
   return source;
 }
+function resolveCliSource(explicit) {
+  return assertSafeSourceAccount(explicit ?? process.env.CAATINGA_SOURCE ?? "alice");
+}
 
 // src/contracts/deploy-contract.ts
 function toSnakeCaseFlag(key) {
@@ -1052,7 +1198,9 @@ async function deployContract(options) {
   const network = resolveNetwork(options.config, options.networkName);
   const source = assertSafeSourceAccount(options.source);
   await checkBinary("stellar", "Install Stellar CLI before running caatinga deploy.");
-  const wasmPath = await resolveWasmArtifactPath(contract.wasmPath);
+  const wasmPath = await resolveWasmArtifactPath(contract.wasmPath, {
+    sourcePath: contract.sourcePath
+  });
   const contractWithWasm = {
     ...contract,
     wasmPath
@@ -1074,7 +1222,7 @@ async function deployContract(options) {
       contract: contractWithWasm,
       network,
       contractId: existing.contractId,
-      artifactsPath: path8.resolve(cwd, "caatinga.artifacts.json"),
+      artifactsPath: path9.resolve(cwd, "caatinga.artifacts.json"),
       output: "",
       skipped: true,
       staleWasmWarning
@@ -1351,13 +1499,13 @@ async function deployContractGraph(options) {
 
 // src/contracts/generate-bindings.ts
 import { access as access3, mkdir as mkdir2, unlink } from "fs/promises";
-import path9 from "path";
+import path10 from "path";
 function toBindingImportPath(bindingsOutput, contractName) {
-  const normalized = bindingsOutput.replace(/^\.\//, "").split(path9.sep).join("/");
-  return `./${path9.posix.join(normalized, contractName, "src", "index.js")}`;
+  const normalized = bindingsOutput.replace(/^\.\//, "").split(path10.sep).join("/");
+  return `./${path10.posix.join(normalized, contractName, "src", "index.js")}`;
 }
 async function removeLegacyBindingStub(cwd, bindingsOutput, contractName) {
-  const legacyPath = path9.resolve(cwd, bindingsOutput, `${contractName}.ts`);
+  const legacyPath = path10.resolve(cwd, bindingsOutput, `${contractName}.ts`);
   try {
     await access3(legacyPath);
     await unlink(legacyPath);
@@ -1386,7 +1534,7 @@ async function generateBindings(options) {
     );
   }
   await checkBinary("stellar", "Install Stellar CLI before running caatinga generate.");
-  const outputDir = path9.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  const outputDir = path10.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
   await mkdir2(outputDir, { recursive: true });
   const result = await runCommand("stellar", [
     "contract",
@@ -1460,8 +1608,8 @@ async function generateBindingsGraph(options) {
   return { network, results };
 }
 
-// src/contracts/invoke-contract.ts
-var INVOKE_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
+// src/contracts/invoke-target.ts
+var READ_CALL_FAILURE_REGEX = /this is a read call|read-only/i;
 function parseInvokeTarget(target) {
   const [contractName, method, extra] = target.split(".");
   if (!contractName || !method || extra) {
@@ -1473,6 +1621,29 @@ function parseInvokeTarget(target) {
   }
   return { contractName, method };
 }
+function buildReadCallHint(target, networkName) {
+  return [
+    `"${target.contractName}.${target.method}" is a read-only contract method.`,
+    "Simulate without signing instead:",
+    `  npx caatinga read ${target.contractName}.${target.method} --network ${networkName}`,
+    "  (--source is optional; Caatinga resolves CAATINGA_SOURCE or defaults to alice)",
+    "In browser code, use:",
+    `  client.contract("${target.contractName}").read("${target.method}")`,
+    `  client.contract("${target.contractName}").simulate("${target.method}")`,
+    "Pass method args as the second argument to read() when the contract method takes parameters.",
+    "Only pass Stellar CLI --force when you intentionally need a signed read simulation."
+  ].join("\n");
+}
+function isReadCallFailure(error) {
+  if (!(error instanceof CaatingaError) || error.code !== CaatingaErrorCode.INVOKE_FAILED) {
+    return false;
+  }
+  return READ_CALL_FAILURE_REGEX.test(`${error.message}
+${error.hint ?? ""}`);
+}
+
+// src/contracts/invoke-contract.ts
+var INVOKE_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
 async function invokeContract(options) {
   const cwd = options.cwd ?? process.cwd();
   const network = resolveNetwork(options.config, options.networkName);
@@ -1506,6 +1677,14 @@ async function invokeContract(options) {
       failureCode: CaatingaErrorCode.INVOKE_FAILED
     });
   } catch (error) {
+    if (error instanceof CaatingaError && error.code === CaatingaErrorCode.INVOKE_FAILED && isReadCallFailure(error)) {
+      throw new CaatingaError(
+        error.message,
+        error.code,
+        buildReadCallHint(target, network.name),
+        error
+      );
+    }
     if (error instanceof CaatingaError && error.code === CaatingaErrorCode.INVOKE_FAILED && INVOKE_SIGNING_FAILURE_REGEX.test(`${error.message}
 ${error.hint ?? ""}`)) {
       throw new CaatingaError(
@@ -1531,9 +1710,48 @@ ${error.hint ?? ""}`)) {
   };
 }
 
+// src/contracts/read-contract.ts
+async function readContract(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const network = resolveNetwork(options.config, options.networkName);
+  const target = parseInvokeTarget(options.target);
+  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 reading it."
+    );
+  }
+  await checkBinary("stellar", "Install Stellar CLI before running caatinga read.");
+  const stellarArgs = [
+    "contract",
+    "invoke",
+    "--id",
+    contractArtifact.contractId,
+    "--source-account",
+    resolveCliSource(options.source),
+    "--send=no",
+    ...buildStellarNetworkArgs(network),
+    "--",
+    target.method,
+    ...options.args ?? []
+  ];
+  const result = await runCommand("stellar", stellarArgs, {
+    cwd,
+    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 readFile4, readdir as readdir3, stat as stat2, writeFile as writeFile3 } from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 import { z as z7 } from "zod";
 
 // src/templates/template-manifest.schema.ts
@@ -1609,8 +1827,8 @@ var TEMPLATE_COPY_EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   ".git"
 ]);
 async function createProjectFromTemplate(options) {
-  const targetDir = path10.resolve(options.targetDir);
-  const templateDir = path10.resolve(options.templateDir);
+  const targetDir = path11.resolve(options.targetDir);
+  const templateDir = path11.resolve(options.templateDir);
   try {
     await stat2(templateDir);
   } catch {
@@ -1648,7 +1866,7 @@ async function ensureArtifacts(targetDir, projectName) {
   }
 }
 async function readTemplateManifest(templateDir) {
-  const manifestPath = path10.join(templateDir, "caatinga.template.json");
+  const manifestPath = path11.join(templateDir, "caatinga.template.json");
   try {
     const rawManifest = await readFile4(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
@@ -1685,7 +1903,7 @@ async function readTemplateManifest(templateDir) {
 async function replaceTemplateVariables(dir, projectName) {
   const entries = await readdir3(dir);
   await Promise.all(entries.map(async (entry) => {
-    const entryPath = path10.join(dir, entry);
+    const entryPath = path11.join(dir, entry);
     const entryStat = await stat2(entryPath);
     if (entryStat.isDirectory()) {
       await replaceTemplateVariables(entryPath, projectName);
@@ -1699,15 +1917,15 @@ async function replaceTemplateVariables(dir, projectName) {
   }));
 }
 function shouldCopyTemplateEntry(templateDir, source, userFilter) {
-  const relativePath = path10.relative(templateDir, source);
+  const relativePath = path11.relative(templateDir, source);
   if (!relativePath || relativePath === ".") {
     return true;
   }
-  const normalizedPath = relativePath.split(path10.sep).join("/");
+  const normalizedPath = relativePath.split(path11.sep).join("/");
   if (userFilter && !userFilter(normalizedPath)) {
     return false;
   }
-  return !relativePath.split(path10.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
+  return !relativePath.split(path11.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
 }
 function isTextTemplateFile(filePath) {
   return [
@@ -1719,21 +1937,21 @@ function isTextTemplateFile(filePath) {
     ".tsx",
     ".css",
     ".html"
-  ].includes(path10.extname(filePath));
+  ].includes(path11.extname(filePath));
 }
 
 // src/scaffold/create-zk-project.ts
 import { cp as cp2, mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
-import { existsSync } from "fs";
-import path11 from "path";
+import { existsSync as existsSync2 } from "fs";
+import path12 from "path";
 import { fileURLToPath } from "url";
-var moduleDir = typeof __dirname === "string" ? __dirname : path11.dirname(fileURLToPath(import.meta.url));
+var moduleDir = typeof __dirname === "string" ? __dirname : path12.dirname(fileURLToPath(import.meta.url));
 function scaffoldRoot() {
   const candidates = [
-    path11.resolve(moduleDir, "../../scaffolds"),
-    path11.resolve(moduleDir, "../scaffolds")
+    path12.resolve(moduleDir, "../../scaffolds"),
+    path12.resolve(moduleDir, "../scaffolds")
   ];
-  const found = candidates.find((candidate) => existsSync(candidate));
+  const found = candidates.find((candidate) => existsSync2(candidate));
   return found ?? candidates[0];
 }
 function configSource(projectName) {
@@ -1777,7 +1995,8 @@ function packageJsonSource(projectName) {
       "zk:build": "caatinga zk build main",
       "zk:prove": "caatinga zk prove main",
       build: "caatinga build verifier",
-      deploy: "caatinga deploy verifier"
+      deploy: "caatinga deploy verifier --network testnet --source ${CAATINGA_SOURCE:-alice}",
+      doctor: "caatinga doctor --network testnet"
     },
     devDependencies: {
       "@caatinga/cli": `^${CAATINGA_CORE_VERSION}`,
@@ -1797,7 +2016,7 @@ Minimal Caatinga ZK project.
 npm install
 npx caatinga zk build main
 npx caatinga build verifier
-npx caatinga deploy verifier --network testnet
+npx caatinga deploy verifier --network testnet --source <identity>
 npx caatinga zk prove main
 \`\`\`
 
@@ -1805,25 +2024,25 @@ Replace \`circuits/main.circom\` with your circuit. Keep the entry point named \
 `;
 }
 async function createZkProject(options) {
-  const targetDir = path11.resolve(options.targetDir);
+  const targetDir = path12.resolve(options.targetDir);
   const force = options.force ?? false;
   const projectFiles = options.projectFiles ?? true;
   await mkdir4(targetDir, { recursive: true });
   if (projectFiles) {
     await Promise.all([
-      writeFile4(path11.join(targetDir, "caatinga.config.ts"), configSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
-      writeFile4(path11.join(targetDir, "package.json"), packageJsonSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
-      writeFile4(path11.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", { encoding: "utf8", flag: force ? "w" : "wx" }),
-      writeFile4(path11.join(targetDir, "README.md"), readmeSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" })
+      writeFile4(path12.join(targetDir, "caatinga.config.ts"), configSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
+      writeFile4(path12.join(targetDir, "package.json"), packageJsonSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
+      writeFile4(path12.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", { encoding: "utf8", flag: force ? "w" : "wx" }),
+      writeFile4(path12.join(targetDir, "README.md"), readmeSource(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" })
     ]);
   }
-  await mkdir4(path11.join(targetDir, "contracts"), { recursive: true });
-  await cp2(path11.join(scaffoldRoot(), "zk-circuit-stub"), path11.join(targetDir, "circuits"), {
+  await mkdir4(path12.join(targetDir, "contracts"), { recursive: true });
+  await cp2(path12.join(scaffoldRoot(), "zk-circuit-stub"), path12.join(targetDir, "circuits"), {
     recursive: true,
     force,
     errorOnExist: !force
   });
-  await cp2(path11.join(scaffoldRoot(), "zk-verifier"), path11.join(targetDir, "contracts", "verifier"), {
+  await cp2(path12.join(scaffoldRoot(), "zk-verifier"), path12.join(targetDir, "contracts", "verifier"), {
     recursive: true,
     force,
     errorOnExist: !force
@@ -1834,6 +2053,109 @@ async function createZkProject(options) {
   return { targetDir };
 }
 
+// src/scaffold/create-minimal-project.ts
+import { cp as cp3, mkdir as mkdir5, writeFile as writeFile5 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import path13 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var moduleDir2 = typeof __dirname === "string" ? __dirname : path13.dirname(fileURLToPath2(import.meta.url));
+function scaffoldRoot2() {
+  const candidates = [
+    path13.resolve(moduleDir2, "../../scaffolds"),
+    path13.resolve(moduleDir2, "../scaffolds")
+  ];
+  const found = candidates.find((candidate) => existsSync3(candidate));
+  return found ?? candidates[0];
+}
+function configSource2(projectName) {
+  return `import { defineConfig } from "@caatinga/core";
+
+export default defineConfig({
+  project: "${projectName}",
+  defaultNetwork: "testnet",
+  contracts: {
+    app: {
+      path: "./contracts/app",
+      wasm: "./contracts/app/target/wasm32v1-none/release/app.wasm"
+    }
+  },
+  networks: {
+    testnet: {
+      rpcUrl: "https://soroban-testnet.stellar.org",
+      networkPassphrase: "Test SDF Network ; September 2015"
+    }
+  }
+});
+`;
+}
+function packageJsonSource2(projectName) {
+  return `${JSON.stringify({
+    name: projectName,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+      build: "caatinga build app",
+      deploy: "caatinga deploy app --network testnet --source ${CAATINGA_SOURCE:-alice}",
+      doctor: "caatinga doctor --network testnet",
+      "read:hello": "caatinga read app.hello --network testnet --source ${CAATINGA_SOURCE:-alice}",
+      "read:version": "caatinga read app.version --network testnet --source ${CAATINGA_SOURCE:-alice}"
+    },
+    devDependencies: {
+      "@caatinga/cli": `^${CAATINGA_CORE_VERSION}`,
+      "@caatinga/core": `^${CAATINGA_CORE_VERSION}`
+    }
+  }, null, 2)}
+`;
+}
+function readmeSource2(projectName) {
+  return `# ${projectName}
+
+Minimal Caatinga project with a Soroban contract stub (no frontend template).
+
+## Workflow
+
+\`\`\`bash
+npm install
+npx caatinga doctor
+npx caatinga build app
+npx caatinga deploy app --network testnet --source <identity>
+npx caatinga read app.version --network testnet
+npx caatinga read app.hello --network testnet
+\`\`\`
+
+## Contract
+
+- \`hello()\` \u2014 read-only; returns Soroban Symbol \`hello\`
+- \`version()\` \u2014 read-only; returns \`1\`
+
+Use \`caatinga read\` for read-only methods. Use \`caatinga invoke\` only after you add state-changing methods to the contract.
+
+Soroban \`Symbol\` parameters are generated as TypeScript \`string\` values with host-specific restrictions \u2014 see the Caatinga docs on [Soroban types](https://github.com/caatinga/caatinga/blob/main/docs/soroban-types.md).
+
+Edit \`contracts/app/src/lib.rs\` to customize the contract. Add a frontend later with \`@caatinga/client\` and your chosen UI stack.
+`;
+}
+async function createMinimalProject(options) {
+  const targetDir = path13.resolve(options.targetDir);
+  const force = options.force ?? false;
+  await mkdir5(targetDir, { recursive: true });
+  await Promise.all([
+    writeFile5(path13.join(targetDir, "caatinga.config.ts"), configSource2(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
+    writeFile5(path13.join(targetDir, "package.json"), packageJsonSource2(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" }),
+    writeFile5(path13.join(targetDir, ".gitignore"), "node_modules\n.artifacts\ntarget\n", { encoding: "utf8", flag: force ? "w" : "wx" }),
+    writeFile5(path13.join(targetDir, "README.md"), readmeSource2(options.projectName), { encoding: "utf8", flag: force ? "w" : "wx" })
+  ]);
+  await mkdir5(path13.join(targetDir, "contracts"), { recursive: true });
+  await cp3(path13.join(scaffoldRoot2(), "soroban-contract-stub"), path13.join(targetDir, "contracts", "app"), {
+    recursive: true,
+    force,
+    errorOnExist: !force
+  });
+  await writeArtifacts(createInitialArtifacts(options.projectName, { networks: ["testnet"] }), targetDir);
+  return { targetDir };
+}
+
 // src/ci/is-transient-testnet-smoke-failure.ts
 var NO_RETRY_CAATINGA_SUBSTRINGS = [
   "CAATINGA_UNSUPPORTED_CLI_VERSION",
@@ -1862,16 +2184,19 @@ export {
   CaatingaConfigSchema,
   CaatingaError,
   CaatingaErrorCode,
+  READ_CALL_FAILURE_REGEX,
   STELLAR_CLI_LAST_TESTED_VERSION,
   STELLAR_CLI_MIN_VERSION,
   TemplateManifestSchema,
   WELL_KNOWN_NETWORKS,
   buildContract,
   buildDependencyGraph,
+  buildReadCallHint,
   checkBinary,
   checkStellarCliVersion,
   collectProjectStatus,
   createInitialArtifacts,
+  createMinimalProject,
   createProjectFromTemplate,
   createZkProject,
   defineConfig,
@@ -1884,6 +2209,8 @@ export {
   generateBindings,
   generateBindingsGraph,
   invokeContract,
+  isCargoBinMissingFromPath,
+  isReadCallFailure,
   isTransientTestnetSmokeFailure,
   loadConfig,
   parseContractId,
@@ -1891,11 +2218,13 @@ export {
   parseStellarCliVersion,
   readArtifacts,
   readBindingMarker,
+  readContract,
   resolveContract,
   resolveDefaultContractName,
   resolveDeployArgs,
   resolveDeployOrder,
   resolveNetwork,
+  resolveSubprocessEnv,
   runCommand,
   toCaatingaError,
   updateArtifact,