@caatinga/core 2.3.0 → 2.4.0

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.0";
+var CAATINGA_CORE_VERSION = "2.4.0";
 
 // src/config/config.schema.ts
 import { z } from "zod";
@@ -143,7 +144,7 @@ var CaatingaConfigSchema = z.object({
   frontend: z.object({
     framework: z.enum(["vite-react", "next", "astro"]).default("vite-react"),
     bindingsOutput: z.string().min(1)
-  }),
+  }).optional(),
   zk: ZkConfigSchema
 });
 
@@ -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;
   }
 }
@@ -341,6 +372,15 @@ async function listGeneratedEntries(outputDir) {
 }
 async function evaluateBindingFreshness(options) {
   const cwd = options.cwd ?? process.cwd();
+  if (!options.config.frontend) {
+    return {
+      contractName: options.contractName,
+      status: "unknown",
+      outputDir: "",
+      marker: null,
+      reason: "frontend bindings are not configured"
+    };
+  }
   const outputDir = path5.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
   const contractArtifact = options.artifacts.networks[options.networkName]?.contracts[options.contractName];
   if (!contractArtifact) {
@@ -578,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 {
@@ -586,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
@@ -784,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) {
@@ -797,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)
   };
 }
 
@@ -818,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) {
@@ -841,8 +939,8 @@ function wasmNotFoundError(configuredWasmPath, options) {
   );
 }
 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("/")}`;
 }
 async function resolveWasmArtifactPath(configuredWasmPath) {
   try {
@@ -875,7 +973,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;
@@ -891,7 +989,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;
@@ -964,7 +1062,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) {
@@ -1021,6 +1119,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) {
@@ -1065,7 +1166,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
@@ -1342,13 +1443,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);
@@ -1359,6 +1460,13 @@ async function removeLegacyBindingStub(cwd, bindingsOutput, contractName) {
 }
 async function generateBindings(options) {
   const cwd = options.cwd ?? process.cwd();
+  if (!options.config.frontend) {
+    throw new CaatingaError(
+      "Frontend bindings are not configured.",
+      CaatingaErrorCode.INVALID_CONFIG,
+      "Add a frontend.bindingsOutput entry to caatinga.config.ts before running caatinga generate."
+    );
+  }
   const network = resolveNetwork(options.config, options.networkName);
   const artifacts = await readArtifacts(cwd);
   const contractArtifact = artifacts.networks[network.name]?.contracts[options.contractName];
@@ -1370,7 +1478,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",
@@ -1444,8 +1552,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) {
@@ -1457,6 +1565,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);
@@ -1490,6 +1621,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(
@@ -1515,9 +1654,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
@@ -1593,8 +1771,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 {
@@ -1632,7 +1810,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));
@@ -1669,7 +1847,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);
@@ -1683,15 +1861,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 [
@@ -1703,7 +1881,222 @@ 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 as existsSync2 } from "fs";
+import path12 from "path";
+import { fileURLToPath } from "url";
+var moduleDir = typeof __dirname === "string" ? __dirname : path12.dirname(fileURLToPath(import.meta.url));
+function scaffoldRoot() {
+  const candidates = [
+    path12.resolve(moduleDir, "../../scaffolds"),
+    path12.resolve(moduleDir, "../scaffolds")
+  ];
+  const found = candidates.find((candidate) => existsSync2(candidate));
+  return found ?? candidates[0];
+}
+function configSource(projectName) {
+  return `import { defineConfig } from "@caatinga/core";
+
+export default defineConfig({
+  project: "${projectName}",
+  defaultNetwork: "testnet",
+  contracts: {
+    verifier: {
+      path: "./contracts/verifier",
+      wasm: "./contracts/verifier/target/wasm32v1-none/release/verifier.wasm"
+    }
+  },
+  networks: {
+    testnet: {
+      rpcUrl: "https://soroban-testnet.stellar.org",
+      networkPassphrase: "Test SDF Network ; September 2015"
+    }
+  },
+  zk: {
+    circuits: {
+      main: {
+        path: "./circuits",
+        protocol: "groth16",
+        curve: "bls12381",
+        verifierContract: "verifier"
+      }
+    }
+  }
+});
+`;
+}
+function packageJsonSource(projectName) {
+  return `${JSON.stringify({
+    name: projectName,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+      "zk:build": "caatinga zk build main",
+      "zk:prove": "caatinga zk prove main",
+      build: "caatinga build verifier",
+      deploy: "caatinga deploy verifier"
+    },
+    devDependencies: {
+      "@caatinga/cli": `^${CAATINGA_CORE_VERSION}`,
+      "@caatinga/core": `^${CAATINGA_CORE_VERSION}`
+    }
+  }, null, 2)}
+`;
+}
+function readmeSource(projectName) {
+  return `# ${projectName}
+
+Minimal Caatinga ZK project.
+
+## Workflow
+
+\`\`\`bash
+npm install
+npx caatinga zk build main
+npx caatinga build verifier
+npx caatinga deploy verifier --network testnet
+npx caatinga zk prove main
+\`\`\`
+
+Replace \`circuits/main.circom\` with your circuit. Keep the entry point named \`main\`.
+`;
+}
+async function createZkProject(options) {
+  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(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(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(path12.join(scaffoldRoot(), "zk-verifier"), path12.join(targetDir, "contracts", "verifier"), {
+    recursive: true,
+    force,
+    errorOnExist: !force
+  });
+  if (projectFiles) {
+    await writeArtifacts(createInitialArtifacts(options.projectName, { networks: ["testnet"] }), targetDir);
+  }
+  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",
+      "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
@@ -1734,17 +2127,21 @@ 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,
   deployContract,
   deployContractGraph,
@@ -1755,6 +2152,8 @@ export {
   generateBindings,
   generateBindingsGraph,
   invokeContract,
+  isCargoBinMissingFromPath,
+  isReadCallFailure,
   isTransientTestnetSmokeFailure,
   loadConfig,
   parseContractId,
@@ -1762,11 +2161,13 @@ export {
   parseStellarCliVersion,
   readArtifacts,
   readBindingMarker,
+  readContract,
   resolveContract,
   resolveDefaultContractName,
   resolveDeployArgs,
   resolveDeployOrder,
   resolveNetwork,
+  resolveSubprocessEnv,
   runCommand,
   toCaatingaError,
   updateArtifact,