@caatinga/cli 0.2.4 → 2.0.0

package/README.md

@@ -14,7 +14,7 @@ Inside a generated project, prefer `npx caatinga` so the project-local workflow
 ## Requirements
 
 - Node.js `>=20`
-- [Stellar CLI](https://developers.stellar.org/docs/tools/developer-tools/cli/stellar-cli) `>=23.0.0` and `<=25.2.0` on `PATH` (22.x breaks `caatinga invoke` signing)
+- [Stellar CLI](https://developers.stellar.org/docs/tools/developer-tools/cli/stellar-cli) `>=23.0.0` on `PATH` (22.x breaks `caatinga invoke` signing)
 - Rust 1.84.0 or newer with the `wasm32v1-none` target (contract builds)
 - A funded Stellar CLI identity for `deploy` and `invoke` (for example `alice`)
 
@@ -23,7 +23,7 @@ rustup target add wasm32v1-none
 stellar keys generate alice --fund --network testnet
 ```
 
-If your machine runs a newer Stellar CLI, `--allow-untested-stellar-cli` is the local-only escape hatch. CI and release workflows must stay on the supported range.
+Stellar CLI versions newer than the last-tested `25.2.0` are accepted with a non-fatal stderr advisory and a `caatinga doctor` warning; no override flag is required.
 
 ## Quick start
 
@@ -31,6 +31,7 @@ If your machine runs a newer Stellar CLI, `--allow-untested-stellar-cli` is the
 caatinga init my-dapp
 cd my-dapp
 npm install
+# pnpm alternative: pnpm install (template includes pnpm-workspace.yaml for pnpm 10.26+/11)
 
 npx caatinga build counter
 npx caatinga deploy counter --network testnet --source alice
@@ -38,7 +39,7 @@ npx caatinga generate counter --network testnet
 npx caatinga invoke counter.increment --network testnet --source alice
 ```
 
-`deploy` writes contract IDs to `caatinga.artifacts.json`. `generate` creates TypeScript bindings under the path configured in `caatinga.config.ts` (templates default to `contracts/generated/`).
+`build` only compiles the WASM file. `deploy` writes contract IDs to `caatinga.artifacts.json`, and the frontend/client flow needs those IDs before it can resolve a contract. `generate` creates TypeScript bindings under the path configured in `caatinga.config.ts` (templates default to `contracts/generated/`).
 
 ## Commands
 
@@ -62,7 +63,7 @@ The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
 ### `build`
 
 - `[contract]` defaults to `counter` when omitted
-- `--allow-untested-stellar-cli` allows a Stellar CLI newer than Caatinga's tested maximum (local only)
+- prints a deploy reminder when the default network lacks a `contractId` in `caatinga.artifacts.json`; this warning does not fail the build
 
 ### `doctor`
 
@@ -77,7 +78,6 @@ The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
 - `-s, --source <identity>` is required; must be a Stellar CLI identity alias that can sign (for example `alice`)
 - `--force` redeploys even when artifacts already store a contract ID
 - `--no-deps` skips dependency deployment for a single named contract (`--no-deps` requires `[contract]`)
-- `--allow-untested-stellar-cli` for local experiments only
 
 Dependencies listed in `dependsOn` deploy first unless `--no-deps` is set. Deploy args may reference `${contracts.<name>.contractId}` placeholders resolved from artifacts.
 
@@ -85,7 +85,6 @@ Dependencies listed in `dependsOn` deploy first unless `--no-deps` is set. Deplo
 
 - `-n, --network <network>` selects the network used to resolve deployed contract IDs
 - `invoke` expects `<contract.method>` (for example `counter.increment`) and forwards `[args...]` to the underlying Stellar invocation
-- Both accept `--allow-untested-stellar-cli` for local experiments only
 
 `caatinga dev` is reserved, hidden in pre-v1 builds, and not part of the stability promise. Use your frontend dev server (for example Vite) alongside the commands above.
 
@@ -107,7 +106,7 @@ Unsupported input posture:
 Common codes:
 
 - `CAATINGA_CONFIG_NOT_FOUND`, `CAATINGA_INVALID_CONFIG`
-- `CAATINGA_STELLAR_CLI_NOT_FOUND`, `CAATINGA_UNSUPPORTED_CLI_VERSION`, `CAATINGA_UNTESTED_CLI_VERSION`
+- `CAATINGA_STELLAR_CLI_NOT_FOUND`, `CAATINGA_UNSUPPORTED_CLI_VERSION`
 - `CAATINGA_BUILD_FAILED`, `CAATINGA_DEPLOY_FAILED`, `CAATINGA_BINDINGS_FAILED`, `CAATINGA_INVOKE_FAILED`
 - `CAATINGA_CONTRACT_ID_NOT_FOUND`, `CAATINGA_SOURCE_ACCOUNT_REQUIRED`, `CAATINGA_UNSAFE_SOURCE_ACCOUNT`
 - `CAATINGA_CONTRACT_DEPENDENCY_NOT_FOUND`, `CAATINGA_CONTRACT_DEPENDENCY_CYCLE`

package/dist/index.js

@@ -2,21 +2,33 @@
 
 // src/utils/preflight.ts
 import chalk from "chalk";
-var NODE_MIN_MAJOR = 20;
-function checkNodeVersion() {
-  const major = parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+import { NODE_MIN_MAJOR as NODE_MIN_MAJOR2 } from "@caatinga/core/runtime/requirements";
+
+// src/diagnostics/node-diagnostic.ts
+import { NODE_MIN_MAJOR } from "@caatinga/core/runtime/requirements";
+function nodeDiagnostic() {
+  const version = process.versions.node;
+  const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
   if (major < NODE_MIN_MAJOR) {
-    return `Node.js ${process.versions.node} is below the required minimum v${NODE_MIN_MAJOR}.
-  Install Node.js ${NODE_MIN_MAJOR} or newer: https://nodejs.org/`;
+    return {
+      ok: false,
+      label: `Node.js ${version} is below the required minimum ${NODE_MIN_MAJOR}.0.0`,
+      fix: `Install Node.js ${NODE_MIN_MAJOR} or newer.`
+    };
   }
-  return null;
+  return { ok: true, label: `Node.js ${version}` };
+}
+
+// src/utils/preflight.ts
+function formatNodePreflightFailure() {
+  const version = process.versions.node;
+  return `Node.js ${version} is below the required minimum v${NODE_MIN_MAJOR2}.
+  Install Node.js ${NODE_MIN_MAJOR2} or newer: https://nodejs.org/`;
 }
 function runPreflight() {
-  const failures = [];
-  const nodeFailure = checkNodeVersion();
-  if (nodeFailure) failures.push(nodeFailure);
-  if (failures.length > 0) return { ok: false, failures };
-  return { ok: true };
+  const diagnostic = nodeDiagnostic();
+  if (diagnostic.ok) return { ok: true };
+  return { ok: false, failures: [formatNodePreflightFailure()] };
 }
 function assertPreflight() {
   const result = runPreflight();
@@ -33,7 +45,7 @@ function assertPreflight() {
 import { Command } from "commander";
 
 // src/commands/build.command.ts
-import { buildContract, loadConfig } from "@caatinga/core";
+import { buildContract, CaatingaError, CaatingaErrorCode, loadConfig as loadConfig2 } from "@caatinga/core";
 
 // src/utils/errors.ts
 import chalk2 from "chalk";
@@ -84,34 +96,82 @@ var logger = {
   }
 };
 
+// src/commands/doctor-deploy-coverage.ts
+import { loadConfig, readArtifacts, resolveNetwork } from "@caatinga/core";
+async function evaluateDeployCoverage(options) {
+  const cwd = options.cwd;
+  const config = await loadConfig({ cwd });
+  const network = resolveNetwork(config, options.networkName);
+  const artifacts = await readArtifacts(cwd);
+  const lines = [];
+  for (const name of Object.keys(config.contracts)) {
+    const contractId = artifacts.networks[network.name]?.contracts[name]?.contractId;
+    if (contractId) {
+      lines.push({ name, ok: true, contractId });
+    } else {
+      lines.push({
+        name,
+        ok: false,
+        fix: `Run: caatinga deploy ${name} --network ${network.name} --source <identity>`
+      });
+    }
+  }
+  return { lines, complete: lines.every((line) => line.ok) };
+}
+
 // src/commands/build.command.ts
 function registerBuildCommand(program2) {
-  program2.command("build").description("Build a configured Soroban contract").argument("[contract]", "Contract name", "counter").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").action((contractName, options) => runCliAction(async () => {
-    const config = await loadConfig();
+  program2.command("build").description("Build a configured Soroban contract").argument("[contract]", "Contract name", "counter").action((contractName) => runCliAction(async () => {
+    const config = await loadConfig2();
     const result = await buildContract({
       config,
-      contractName,
-      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+      contractName
     });
     logger.success("Contract built");
     logger.info("");
     logger.info(`Contract: ${result.contract.name}`);
     logger.info(`WASM: ${result.contract.config.wasm}`);
+    await warnIfDefaultNetworkNeedsDeploy(config);
   }));
 }
+async function warnIfDefaultNetworkNeedsDeploy(config) {
+  let missingDeployCommands;
+  try {
+    const coverage = await evaluateDeployCoverage({ networkName: config.defaultNetwork });
+    if (coverage.complete) {
+      return;
+    }
+    missingDeployCommands = coverage.lines.filter((line) => !line.ok).map((line) => line.fix?.replace(/^Run: /, "")).filter((fix) => Boolean(fix));
+  } catch (error) {
+    if (!(error instanceof CaatingaError) || error.code !== CaatingaErrorCode.ARTIFACT_NOT_FOUND) {
+      throw error;
+    }
+    missingDeployCommands = Object.keys(config.contracts).map(
+      (name) => `caatinga deploy ${name} --network ${config.defaultNetwork} --source <identity>`
+    );
+  }
+  if (missingDeployCommands.length === 0) {
+    return;
+  }
+  logger.warn("");
+  for (const command of missingDeployCommands) {
+    logger.warn(`Next: ${command}`);
+  }
+  logger.warn("The frontend needs contractId in caatinga.artifacts.json; build alone is not enough.");
+}
 
 // src/commands/deploy.command.ts
-import { deployContractGraph, CaatingaError, CaatingaErrorCode, loadConfig as loadConfig2 } from "@caatinga/core";
+import { deployContractGraph, CaatingaError as CaatingaError2, CaatingaErrorCode as CaatingaErrorCode2, loadConfig as loadConfig3 } from "@caatinga/core";
 function registerDeployCommand(program2) {
-  program2.command("deploy").description("Deploy one or all configured Soroban contracts").argument("[contract]", "Contract name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias that can sign (for example alice)").option("--force", "Redeploy contracts even if artifacts already contain contract IDs").option("--no-deps", "Do not deploy missing dependencies for a selected contract").option("--no-stale-check", "Do not warn when WASM may be older than contract sources").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").option("--verify-deps", "Verify dependency contract IDs exist on-chain before deploy").action((contractName, options) => runCliAction(async () => {
+  program2.command("deploy").description("Deploy one or all configured Soroban contracts").argument("[contract]", "Contract name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias that can sign (for example alice)").option("--force", "Redeploy contracts even if artifacts already contain contract IDs").option("--no-deps", "Do not deploy missing dependencies for a selected contract").option("--no-stale-check", "Do not warn when WASM may be older than contract sources").option("--verify-deps", "Verify dependency contract IDs exist on-chain before deploy").action((contractName, options) => runCliAction(async () => {
     if (options.deps === false && !contractName) {
-      throw new CaatingaError(
+      throw new CaatingaError2(
         "`--no-deps` requires a contract name.",
-        CaatingaErrorCode.INVALID_CONFIG,
+        CaatingaErrorCode2.INVALID_CONFIG,
         "Select a single contract or omit `--no-deps` to deploy the full graph."
       );
     }
-    const config = await loadConfig2();
+    const config = await loadConfig3();
     const result = await deployContractGraph({
       config,
       contractName,
@@ -120,8 +180,7 @@ function registerDeployCommand(program2) {
       includeDependencies: options.deps !== false,
       force: options.force === true,
       checkStaleWasm: options.staleCheck !== false,
-      verifyDeps: options.verifyDeps === true,
-      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+      verifyDeps: options.verifyDeps === true
     });
     for (const warning of result.staleWasmWarnings) {
       logger.warn(warning.message);
@@ -154,76 +213,56 @@ function registerDevCommand(program2) {
 }
 
 // src/commands/doctor.command.ts
-import { access } from "fs/promises";
-import {
-  assertSupportedStellarCliVersion,
-  CaatingaError as CaatingaError2,
-  CaatingaErrorCode as CaatingaErrorCode2,
-  loadConfig as loadConfig4,
-  parseStellarCliVersion,
-  readArtifacts as readArtifacts2,
-  resolveNetwork as resolveNetwork2,
-  runCommand,
-  validateSourceShape
-} from "@caatinga/core";
+import { CaatingaError as CaatingaError5, CaatingaErrorCode as CaatingaErrorCode3 } from "@caatinga/core";
 
-// src/commands/doctor-deploy-coverage.ts
-import { loadConfig as loadConfig3, readArtifacts, resolveNetwork } from "@caatinga/core";
-async function evaluateDeployCoverage(options) {
-  const cwd = options.cwd;
-  const config = await loadConfig3({ cwd });
-  const network = resolveNetwork(config, options.networkName);
-  const artifacts = await readArtifacts(cwd);
-  const lines = [];
-  for (const name of Object.keys(config.contracts)) {
-    const contractId = artifacts.networks[network.name]?.contracts[name]?.contractId;
-    if (contractId) {
-      lines.push({ name, ok: true, contractId });
-    } else {
-      lines.push({
-        name,
-        ok: false,
-        fix: `Run: caatinga deploy ${name} --network ${network.name}`
-      });
-    }
+// src/diagnostics/project-diagnostic.ts
+import { access } from "fs/promises";
+import { CaatingaError as CaatingaError3, loadConfig as loadConfig4, readArtifacts as readArtifacts2, resolveNetwork as resolveNetwork2 } from "@caatinga/core";
+async function configDiagnostic() {
+  try {
+    await loadConfig4();
+    return { ok: true, label: "caatinga.config.ts found" };
+  } catch (error) {
+    const hint = error instanceof CaatingaError3 ? error.hint : void 0;
+    return {
+      ok: false,
+      label: "caatinga.config.ts not ready",
+      fix: hint ?? "Run this command from a Caatinga project root."
+    };
   }
-  return { lines, complete: lines.every((line) => line.ok) };
 }
-
-// src/commands/doctor.command.ts
-var NODE_MIN_MAJOR2 = 20;
-var WASM_TARGET = "wasm32v1-none";
-function nodeDiagnostic() {
-  const version = process.versions.node;
-  const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
-  if (major < NODE_MIN_MAJOR2) {
+async function artifactsDiagnostic() {
+  try {
+    await access("caatinga.artifacts.json");
+    await readArtifacts2();
+    return { ok: true, label: "caatinga.artifacts.json found" };
+  } catch {
     return {
       ok: false,
-      label: `Node.js ${version} is below the required minimum ${NODE_MIN_MAJOR2}.0.0`,
-      fix: `Install Node.js ${NODE_MIN_MAJOR2} or newer.`
+      label: "caatinga.artifacts.json not found or invalid",
+      fix: "Run caatinga init, or restore a valid caatinga.artifacts.json file."
     };
   }
-  return { ok: true, label: `Node.js ${version}` };
 }
-async function stellarDiagnostic(allowUntested) {
+async function networkDiagnostic(networkName) {
+  if (!networkName) return void 0;
   try {
-    const result = await runCommand("stellar", ["--version"], {
-      skipStellarVersionCheck: true
-    });
-    const version = assertSupportedStellarCliVersion({
-      version: parseStellarCliVersion(result.all || result.stdout || result.stderr),
-      allowUntested
-    });
-    return { ok: true, label: `Stellar CLI ${version}` };
+    const config = await loadConfig4();
+    const network = resolveNetwork2(config, networkName);
+    return { ok: true, label: `network ${network.name} found` };
   } catch (error) {
-    const hint = error instanceof CaatingaError2 ? error.hint : void 0;
+    const hint = error instanceof CaatingaError3 ? error.hint : void 0;
     return {
       ok: false,
-      label: "Stellar CLI not ready",
-      fix: hint ?? "Install Stellar CLI: cargo install --locked stellar-cli --version 25.2.0"
+      label: `network ${networkName} not found`,
+      fix: hint ?? `Add "${networkName}" to caatinga.config.ts networks.`
     };
   }
 }
+
+// src/diagnostics/rust-diagnostic.ts
+import { CURRENT_RUST_WASM_TARGET } from "@caatinga/core/runtime/requirements";
+import { runCommand } from "@caatinga/core";
 async function rustDiagnostic() {
   try {
     const result = await runCommand("rustc", ["--version"]);
@@ -232,7 +271,7 @@ async function rustDiagnostic() {
     return {
       ok: false,
       label: "Rust not found",
-      fix: "Install Rust, then run: rustup target add wasm32v1-none"
+      fix: `Install Rust, then run: rustup target add ${CURRENT_RUST_WASM_TARGET}`
     };
   }
 }
@@ -240,63 +279,25 @@ async function wasmTargetDiagnostic() {
   try {
     const result = await runCommand("rustup", ["target", "list", "--installed"]);
     const installedTargets = result.stdout || result.all;
-    if (installedTargets.split(/\r?\n/).includes(WASM_TARGET)) {
-      return { ok: true, label: `${WASM_TARGET} target installed` };
+    if (installedTargets.split(/\r?\n/).includes(CURRENT_RUST_WASM_TARGET)) {
+      return { ok: true, label: `${CURRENT_RUST_WASM_TARGET} target installed` };
     }
     return {
       ok: false,
-      label: `${WASM_TARGET} target not installed`,
-      fix: `Run: rustup target add ${WASM_TARGET}`
+      label: `${CURRENT_RUST_WASM_TARGET} target not installed`,
+      fix: `Run: rustup target add ${CURRENT_RUST_WASM_TARGET}`
     };
   } catch {
     return {
       ok: false,
       label: "rustup not found",
-      fix: "Install rustup, then run: rustup target add wasm32v1-none"
-    };
-  }
-}
-async function configDiagnostic() {
-  try {
-    await loadConfig4();
-    return { ok: true, label: "caatinga.config.ts found" };
-  } catch (error) {
-    const hint = error instanceof CaatingaError2 ? error.hint : void 0;
-    return {
-      ok: false,
-      label: "caatinga.config.ts not ready",
-      fix: hint ?? "Run this command from a Caatinga project root."
-    };
-  }
-}
-async function artifactsDiagnostic() {
-  try {
-    await access("caatinga.artifacts.json");
-    await readArtifacts2();
-    return { ok: true, label: "caatinga.artifacts.json found" };
-  } catch {
-    return {
-      ok: false,
-      label: "caatinga.artifacts.json not found or invalid",
-      fix: "Run caatinga init, or restore a valid caatinga.artifacts.json file."
-    };
-  }
-}
-async function networkDiagnostic(networkName) {
-  if (!networkName) return void 0;
-  try {
-    const config = await loadConfig4();
-    const network = resolveNetwork2(config, networkName);
-    return { ok: true, label: `network ${network.name} found` };
-  } catch (error) {
-    const hint = error instanceof CaatingaError2 ? error.hint : void 0;
-    return {
-      ok: false,
-      label: `network ${networkName} not found`,
-      fix: hint ?? `Add "${networkName}" to caatinga.config.ts networks.`
+      fix: `Install rustup, then run: rustup target add ${CURRENT_RUST_WASM_TARGET}`
     };
   }
 }
+
+// src/diagnostics/source-diagnostic.ts
+import { runCommand as runCommand2, validateSourceShape } from "@caatinga/core";
 async function sourceDiagnostic(source) {
   if (!source) return void 0;
   const unsafeSource = validateSourceShape(source);
@@ -308,7 +309,7 @@ async function sourceDiagnostic(source) {
     };
   }
   try {
-    await runCommand("stellar", ["keys", "public-key", source]);
+    await runCommand2("stellar", ["keys", "public-key", source]);
     return { ok: true, label: `source identity ${source} found` };
   } catch {
     return {
@@ -318,8 +319,64 @@ async function sourceDiagnostic(source) {
     };
   }
 }
+
+// src/diagnostics/stellar-diagnostic.ts
+import {
+  CaatingaError as CaatingaError4,
+  checkStellarCliVersion
+} from "@caatinga/core";
+async function stellarDiagnostic() {
+  const warnings = [];
+  try {
+    const report = await checkStellarCliVersion({
+      onWarning: (warning) => {
+        warnings.push({ code: warning.code, message: warning.message });
+      }
+    });
+    return {
+      ok: true,
+      label: `Stellar CLI ${report.version}`,
+      warnings: warnings.length > 0 ? warnings : void 0
+    };
+  } catch (error) {
+    if (error instanceof CaatingaError4) {
+      return {
+        ok: false,
+        label: "Stellar CLI not ready",
+        fix: error.hint ?? "Install Stellar CLI: cargo install --locked stellar-cli --version 25.2.0"
+      };
+    }
+    logger.error(String(error));
+    return {
+      ok: false,
+      label: "Stellar CLI not ready",
+      fix: "Install Stellar CLI: cargo install --locked stellar-cli --version 25.2.0"
+    };
+  }
+}
+
+// src/diagnostics/run-all.ts
+async function runAllDiagnostics(options) {
+  return [
+    nodeDiagnostic(),
+    await stellarDiagnostic(),
+    await rustDiagnostic(),
+    await wasmTargetDiagnostic(),
+    await configDiagnostic(),
+    await artifactsDiagnostic(),
+    await networkDiagnostic(options.network),
+    await sourceDiagnostic(options.source)
+  ].filter((diagnostic) => diagnostic !== void 0);
+}
+
+// src/diagnostics/types.ts
 function printDiagnostic(diagnostic) {
-  logger.info(`${diagnostic.ok ? "\u2713" : "\u2717"} ${diagnostic.label}`);
+  const warnings = diagnostic.warnings ?? [];
+  const suffix = warnings.length > 0 ? ` (${warnings.length} warning${warnings.length === 1 ? "" : "s"})` : "";
+  logger.info(`${diagnostic.ok ? "\u2713" : "\u2717"} ${diagnostic.label}${suffix}`);
+  for (const warning of warnings) {
+    logger.info(`  ! ${warning.code}: ${warning.message}`);
+  }
 }
 function printFixes(diagnostics) {
   const failures = diagnostics.filter((diagnostic) => !diagnostic.ok);
@@ -330,6 +387,8 @@ function printFixes(diagnostics) {
     if (failure.fix) logger.info(failure.fix);
   }
 }
+
+// src/commands/doctor.command.ts
 function printDeployCoverageLine(line) {
   if (line.ok) {
     logger.info(`\u2713 ${line.name} \u2014 ${line.contractId}`);
@@ -347,28 +406,19 @@ async function reportDeployCoverage(networkName) {
   }
   if (!coverage.complete) {
     const missing = coverage.lines.filter((line) => !line.ok).map((line) => line.name);
-    throw new CaatingaError2(
+    throw new CaatingaError5(
       `Not all configured contracts are deployed on ${networkName}.`,
-      CaatingaErrorCode2.DOCTOR_PARTIAL_DEPLOY,
+      CaatingaErrorCode3.DOCTOR_PARTIAL_DEPLOY,
       `Deploy missing contracts: ${missing.join(", ")}. See the commands above.`
     );
   }
   return true;
 }
 function registerDoctorCommand(program2) {
-  program2.command("doctor").description("Check local Caatinga, Stellar CLI, Rust, config, and source identity setup").option("-n, --network <network>", "Configured network name to validate").option("-s, --source <source>", "Stellar CLI identity alias to validate").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").action((options) => runCliAction(async () => {
+  program2.command("doctor").description("Check local Caatinga, Stellar CLI, Rust, config, and source identity setup").option("-n, --network <network>", "Configured network name to validate").option("-s, --source <source>", "Stellar CLI identity alias to validate").action((options) => runCliAction(async () => {
     logger.info("Caatinga Doctor");
     logger.info("");
-    const diagnostics = [
-      nodeDiagnostic(),
-      await stellarDiagnostic(options.allowUntestedStellarCli === true),
-      await rustDiagnostic(),
-      await wasmTargetDiagnostic(),
-      await configDiagnostic(),
-      await artifactsDiagnostic(),
-      await networkDiagnostic(options.network),
-      await sourceDiagnostic(options.source)
-    ].filter((diagnostic) => diagnostic !== void 0);
+    const diagnostics = await runAllDiagnostics(options);
     for (const diagnostic of diagnostics) {
       printDiagnostic(diagnostic);
     }
@@ -393,13 +443,12 @@ function registerDoctorCommand(program2) {
 // src/commands/generate.command.ts
 import { generateBindings, loadConfig as loadConfig5 } from "@caatinga/core";
 function registerGenerateCommand(program2) {
-  program2.command("generate").description("Generate TypeScript bindings for a deployed contract").argument("<contract>", "Contract name").option("-n, --network <network>", "Configured network name").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").action((contractName, options) => runCliAction(async () => {
+  program2.command("generate").description("Generate TypeScript bindings for a deployed contract").argument("<contract>", "Contract name").option("-n, --network <network>", "Configured network name").action((contractName, options) => runCliAction(async () => {
     const config = await loadConfig5();
     const result = await generateBindings({
       config,
       contractName,
-      networkName: options.network,
-      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+      networkName: options.network
     });
     logger.success("Client generated");
     logger.info("");
@@ -417,7 +466,7 @@ import { createProjectFromTemplate } from "@caatinga/core";
 import { access as access2 } from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
-import { CaatingaError as CaatingaError3, CaatingaErrorCode as CaatingaErrorCode3 } from "@caatinga/core";
+import { CaatingaError as CaatingaError6, CaatingaErrorCode as CaatingaErrorCode4 } from "@caatinga/core";
 async function resolveTemplateDir(templateName) {
   const candidates = buildTemplateCandidates(templateName);
   if (process.env.CAATINGA_DEBUG_TEMPLATE_RESOLUTION === "1") {
@@ -439,9 +488,9 @@ async function resolveTemplateDir(templateName) {
     } catch {
     }
   }
-  throw new CaatingaError3(
+  throw new CaatingaError6(
     `Template "${templateName}" was not found.`,
-    CaatingaErrorCode3.TEMPLATE_NOT_FOUND,
+    CaatingaErrorCode4.TEMPLATE_NOT_FOUND,
     "Set CAATINGA_TEMPLATES_DIR, run `pnpm build` before `pnpm pack`, or run from a Caatinga checkout that includes packages/templates."
   );
 }
@@ -498,15 +547,14 @@ function registerInitCommand(program2) {
 // src/commands/invoke.command.ts
 import { invokeContract, loadConfig as loadConfig6 } from "@caatinga/core";
 function registerInvokeCommand(program2) {
-  program2.command("invoke").description("Invoke a deployed contract function").argument("<target>", "Invoke target in contract.method format").argument("[args...]", "Arguments forwarded to Stellar CLI after the method name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias that can sign (for example alice)").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").allowUnknownOption(true).allowExcessArguments(true).action((target, args, options) => runCliAction(async () => {
+  program2.command("invoke").description("Invoke a deployed contract function").argument("<target>", "Invoke target in contract.method format").argument("[args...]", "Arguments forwarded to Stellar CLI after the method name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias that can sign (for example alice)").allowUnknownOption(true).allowExcessArguments(true).action((target, args, options) => runCliAction(async () => {
     const config = await loadConfig6();
     const result = await invokeContract({
       config,
       target,
       args,
       networkName: options.network,
-      source: options.source,
-      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+      source: options.source
     });
     logger.success("Invoke complete");
     logger.info("");
@@ -521,7 +569,7 @@ function registerInvokeCommand(program2) {
 }
 
 // src/version.ts
-var CAATINGA_CLI_VERSION = "0.2.4";
+var CAATINGA_CLI_VERSION = "2.0.0";
 
 // src/program.ts
 function createProgram() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caatinga/cli",
-  "version": "0.2.4",
+  "version": "2.0.0",
   "description": "Caatinga CLI for building dApps on Stellar/Soroban",
   "keywords": [
     "stellar",
@@ -43,7 +43,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@caatinga/core": "^0.2.4",
+    "@caatinga/core": "^2.0.0",
     "chalk": "^5.4.1",
     "commander": "^12.1.0"
   },
@@ -55,6 +55,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean && rm -rf ./templates && cp -r ../templates ./templates",
+    "predev": "pnpm --filter @caatinga/core build",
     "dev": "tsx src/index.ts",
     "test": "vitest run --pool=threads",
     "typecheck": "tsc --noEmit"

package/templates/marketplace-with-token/caatinga.template.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "description": "Experimental multi-contract Soroban template with token dependency injection.",
   "caatinga": {
-    "compatibleCore": "^0.2.4",
+    "compatibleCore": "^2.0.0",
     "templateVersion": 1
   },
   "frontend": {

package/templates/marketplace-with-token/contracts/marketplace/test_snapshots/test/stores_token_contract_id_in_constructor.1.json

@@ -0,0 +1,86 @@
+{
+  "generators": {
+    "address": 2,
+    "nonce": 0
+  },
+  "auth": [
+    [],
+    [],
+    []
+  ],
+  "ledger": {
+    "protocol_version": 22,
+    "sequence_number": 0,
+    "timestamp": 0,
+    "network_id": "0000000000000000000000000000000000000000000000000000000000000000",
+    "base_reserve": 0,
+    "min_persistent_entry_ttl": 4096,
+    "min_temp_entry_ttl": 16,
+    "max_entry_ttl": 6312000,
+    "ledger_entries": [
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+            "key": "ledger_key_contract_instance",
+            "durability": "persistent"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFCT4",
+                "key": "ledger_key_contract_instance",
+                "durability": "persistent",
+                "val": {
+                  "contract_instance": {
+                    "executable": {
+                      "wasm": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+                    },
+                    "storage": [
+                      {
+                        "key": {
+                          "symbol": "TOKEN"
+                        },
+                        "val": {
+                          "address": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM"
+                        }
+                      }
+                    ]
+                  }
+                }
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ],
+      [
+        {
+          "contract_code": {
+            "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_code": {
+                "ext": "v0",
+                "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                "code": ""
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ]
+    ]
+  },
+  "events": []
+}

package/templates/marketplace-with-token/package.json

@@ -12,15 +12,15 @@
     "caatinga:generate": "caatinga generate token && caatinga generate marketplace"
   },
   "dependencies": {
-    "@caatinga/client": "^0.2.4",
-    "@caatinga/core": "^0.2.4",
+    "@caatinga/client": "^2.0.0",
+    "@caatinga/core": "^2.0.0",
     "@vitejs/plugin-react": "^4.3.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "vite": "^6.0.6"
   },
   "devDependencies": {
-    "@caatinga/cli": "^0.2.4",
+    "@caatinga/cli": "^2.0.0",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "typescript": "^5.7.2"

package/templates/react-vite-counter/README.md

@@ -5,16 +5,32 @@ Caatinga counter dApp for Stellar/Soroban.
 ## CLI Flow
 
 ```bash
-npm install
+npm install          # or: pnpm install
 npx caatinga build counter
 npx caatinga deploy counter --network testnet --source alice
 npx caatinga generate counter --network testnet
 npx caatinga invoke counter.increment --network testnet --source alice
-npm run dev
+npm run dev          # or: pnpm dev
 ```
 
+Run `build` before `deploy` (WASM required) and `deploy` before `generate` (contract ID required).
+
 Use a local Stellar CLI identity alias for `--source`; public `G...` addresses, seed phrases, and secret keys are rejected for signing operations.
 
+## Package managers
+
+Templates default to npm, but pnpm 10.26+/11.x is supported via the shipped `pnpm-workspace.yaml` (`allowBuilds.esbuild: true`, `blockExoticSubdeps: false`).
+
+Package scripts wrap the CLI:
+
+```bash
+npm run caatinga:build
+npm run caatinga:deploy -- --network testnet --source alice
+npm run caatinga:generate -- --network testnet
+```
+
+With pnpm, use `pnpm run caatinga:build` (and the same pattern for deploy/generate). `npx caatinga build counter` works without going through the package manager.
+
 ## Client Smoke Path
 
 After `caatinga generate`, wire generated bindings to the client:

package/templates/react-vite-counter/caatinga.template.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "description": "Minimal Vite + React + Soroban counter dApp.",
   "caatinga": {
-    "compatibleCore": "^0.2.4",
+    "compatibleCore": "^2.0.0",
     "templateVersion": 1
   },
   "frontend": {

package/templates/react-vite-counter/contracts/counter/src/lib.rs

@@ -1,20 +1,49 @@
 #![no_std]
 
-use soroban_sdk::{contract, contractimpl, Env};
+use soroban_sdk::{contract, contracterror, contractimpl, contracttype, Env};
+
+const INSTANCE_TTL_THRESHOLD: u32 = 100;
+const INSTANCE_TTL_EXTEND_TO: u32 = 518_400;
+
+#[contracttype]
+#[derive(Clone)]
+pub enum DataKey {
+    Count,
+}
+
+#[contracterror]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
+#[repr(u32)]
+pub enum CounterError {
+    Overflow = 1,
+}
 
 #[contract]
 pub struct CounterContract;
 
+fn refresh_instance_ttl(env: &Env) {
+    env.storage()
+        .instance()
+        .extend_ttl(INSTANCE_TTL_THRESHOLD, INSTANCE_TTL_EXTEND_TO);
+}
+
 #[contractimpl]
 impl CounterContract {
     pub fn get(env: Env) -> u32 {
-        env.storage().instance().get(&"count").unwrap_or(0)
+        let count = env.storage().instance().get(&DataKey::Count).unwrap_or(0);
+        refresh_instance_ttl(&env);
+        count
     }
 
-    pub fn increment(env: Env) -> u32 {
-        let count = Self::get(env.clone()) + 1;
-        env.storage().instance().set(&"count", &count);
-        count
+    pub fn increment(env: Env) -> Result<u32, CounterError> {
+        let count = Self::get(env.clone())
+            .checked_add(1)
+            .ok_or(CounterError::Overflow)?;
+
+        env.storage().instance().set(&DataKey::Count, &count);
+        refresh_instance_ttl(&env);
+
+        Ok(count)
     }
 }
 
@@ -33,4 +62,39 @@ mod test {
         assert_eq!(client.increment(), 1);
         assert_eq!(client.get(), 1);
     }
+
+    #[test]
+    fn get_returns_zero_before_increment() {
+        let env = Env::default();
+        let contract_id = env.register(CounterContract, ());
+        let client = CounterContractClient::new(&env, &contract_id);
+
+        assert_eq!(client.get(), 0);
+    }
+
+    #[test]
+    fn repeated_increments_preserve_state() {
+        let env = Env::default();
+        let contract_id = env.register(CounterContract, ());
+        let client = CounterContractClient::new(&env, &contract_id);
+
+        assert_eq!(client.increment(), 1);
+        assert_eq!(client.increment(), 2);
+        assert_eq!(client.increment(), 3);
+        assert_eq!(client.get(), 3);
+    }
+
+    #[test]
+    fn increment_returns_overflow_error() {
+        let env = Env::default();
+        let contract_id = env.register(CounterContract, ());
+        let client = CounterContractClient::new(&env, &contract_id);
+
+        env.as_contract(&contract_id, || {
+            env.storage().instance().set(&DataKey::Count, &u32::MAX);
+        });
+
+        assert_eq!(client.try_increment(), Err(Ok(CounterError::Overflow)));
+        assert_eq!(client.get(), u32::MAX);
+    }
 }

package/templates/react-vite-counter/contracts/counter/test_snapshots/test/get_returns_zero_before_increment.1.json

@@ -0,0 +1,76 @@
+{
+  "generators": {
+    "address": 1,
+    "nonce": 0
+  },
+  "auth": [
+    [],
+    []
+  ],
+  "ledger": {
+    "protocol_version": 22,
+    "sequence_number": 0,
+    "timestamp": 0,
+    "network_id": "0000000000000000000000000000000000000000000000000000000000000000",
+    "base_reserve": 0,
+    "min_persistent_entry_ttl": 4096,
+    "min_temp_entry_ttl": 16,
+    "max_entry_ttl": 6312000,
+    "ledger_entries": [
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+            "key": "ledger_key_contract_instance",
+            "durability": "persistent"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+                "key": "ledger_key_contract_instance",
+                "durability": "persistent",
+                "val": {
+                  "contract_instance": {
+                    "executable": {
+                      "wasm": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+                    },
+                    "storage": null
+                  }
+                }
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ],
+      [
+        {
+          "contract_code": {
+            "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_code": {
+                "ext": "v0",
+                "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                "code": ""
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ]
+    ]
+  },
+  "events": []
+}

package/templates/react-vite-counter/contracts/counter/test_snapshots/test/increment_returns_overflow_error.1.json

@@ -0,0 +1,91 @@
+{
+  "generators": {
+    "address": 1,
+    "nonce": 0
+  },
+  "auth": [
+    [],
+    [],
+    [],
+    []
+  ],
+  "ledger": {
+    "protocol_version": 22,
+    "sequence_number": 0,
+    "timestamp": 0,
+    "network_id": "0000000000000000000000000000000000000000000000000000000000000000",
+    "base_reserve": 0,
+    "min_persistent_entry_ttl": 4096,
+    "min_temp_entry_ttl": 16,
+    "max_entry_ttl": 6312000,
+    "ledger_entries": [
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+            "key": "ledger_key_contract_instance",
+            "durability": "persistent"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+                "key": "ledger_key_contract_instance",
+                "durability": "persistent",
+                "val": {
+                  "contract_instance": {
+                    "executable": {
+                      "wasm": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+                    },
+                    "storage": [
+                      {
+                        "key": {
+                          "vec": [
+                            {
+                              "symbol": "Count"
+                            }
+                          ]
+                        },
+                        "val": {
+                          "u32": 4294967295
+                        }
+                      }
+                    ]
+                  }
+                }
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ],
+      [
+        {
+          "contract_code": {
+            "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_code": {
+                "ext": "v0",
+                "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                "code": ""
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ]
+    ]
+  },
+  "events": []
+}

package/templates/react-vite-counter/contracts/counter/test_snapshots/test/increments_counter.1.json

@@ -0,0 +1,91 @@
+{
+  "generators": {
+    "address": 1,
+    "nonce": 0
+  },
+  "auth": [
+    [],
+    [],
+    [],
+    []
+  ],
+  "ledger": {
+    "protocol_version": 22,
+    "sequence_number": 0,
+    "timestamp": 0,
+    "network_id": "0000000000000000000000000000000000000000000000000000000000000000",
+    "base_reserve": 0,
+    "min_persistent_entry_ttl": 4096,
+    "min_temp_entry_ttl": 16,
+    "max_entry_ttl": 6312000,
+    "ledger_entries": [
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+            "key": "ledger_key_contract_instance",
+            "durability": "persistent"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+                "key": "ledger_key_contract_instance",
+                "durability": "persistent",
+                "val": {
+                  "contract_instance": {
+                    "executable": {
+                      "wasm": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+                    },
+                    "storage": [
+                      {
+                        "key": {
+                          "vec": [
+                            {
+                              "symbol": "Count"
+                            }
+                          ]
+                        },
+                        "val": {
+                          "u32": 1
+                        }
+                      }
+                    ]
+                  }
+                }
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ],
+      [
+        {
+          "contract_code": {
+            "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_code": {
+                "ext": "v0",
+                "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                "code": ""
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ]
+    ]
+  },
+  "events": []
+}

package/templates/react-vite-counter/contracts/counter/test_snapshots/test/repeated_increments_preserve_state.1.json

@@ -0,0 +1,92 @@
+{
+  "generators": {
+    "address": 1,
+    "nonce": 0
+  },
+  "auth": [
+    [],
+    [],
+    [],
+    [],
+    []
+  ],
+  "ledger": {
+    "protocol_version": 22,
+    "sequence_number": 0,
+    "timestamp": 0,
+    "network_id": "0000000000000000000000000000000000000000000000000000000000000000",
+    "base_reserve": 0,
+    "min_persistent_entry_ttl": 4096,
+    "min_temp_entry_ttl": 16,
+    "max_entry_ttl": 6312000,
+    "ledger_entries": [
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+            "key": "ledger_key_contract_instance",
+            "durability": "persistent"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+                "key": "ledger_key_contract_instance",
+                "durability": "persistent",
+                "val": {
+                  "contract_instance": {
+                    "executable": {
+                      "wasm": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+                    },
+                    "storage": [
+                      {
+                        "key": {
+                          "vec": [
+                            {
+                              "symbol": "Count"
+                            }
+                          ]
+                        },
+                        "val": {
+                          "u32": 3
+                        }
+                      }
+                    ]
+                  }
+                }
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ],
+      [
+        {
+          "contract_code": {
+            "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_code": {
+                "ext": "v0",
+                "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+                "code": ""
+              }
+            },
+            "ext": "v0"
+          },
+          4095
+        ]
+      ]
+    ]
+  },
+  "events": []
+}

package/templates/react-vite-counter/package.json

@@ -12,9 +12,9 @@
     "caatinga:generate": "caatinga generate counter"
   },
   "dependencies": {
-    "@caatinga/client": "^0.2.4",
-    "@caatinga/core": "^0.2.4",
-    "@creit.tech/xbull-wallet-connect": "github:Creit-Tech/xBull-Wallet-Connect",
+    "@caatinga/client": "^2.0.0",
+    "@caatinga/core": "^2.0.0",
+    "@creit.tech/xbull-wallet-connect": "^0.4.0",
     "@vitejs/plugin-react": "^4.3.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
@@ -22,7 +22,7 @@
     "vite": "^6.0.6"
   },
   "devDependencies": {
-    "@caatinga/cli": "^0.2.4",
+    "@caatinga/cli": "^2.0.0",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "typescript": "^5.7.2"

package/templates/react-vite-counter/pnpm-workspace.yaml

@@ -0,0 +1,12 @@
+# pnpm 10.26+ / 11.x block lifecycle scripts by default; vite depends on esbuild.
+allowBuilds:
+  esbuild: true
+
+# stellar-wallets-kit@0.0.7 is unpublished from npm and is therefore pinned
+# to a github: URL in package.json. Its own dependencies also reference
+# @creit.tech/xbull-wallet-connect via a github: URL, and pnpm 10.26+ (and
+# 11.x) defaults blockExoticSubdeps to true, which would refuse to install
+# that exotic subdep. Allow it explicitly. This is a targeted opt-out for
+# this one transitive dep; direct dependencies in package.json still must
+# come from a trusted source.
+blockExoticSubdeps: false

package/templates/react-vite-counter/src/components/CounterCard.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { caatingaClient } from "../caatinga.js";
 import { CaatingaError } from "@caatinga/core/browser";
 
@@ -15,7 +15,7 @@ export function CounterCard() {
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const formattedCount = useMemo(
-    () => (count === null ? "Unknown" : new Intl.NumberFormat().format(count)),
+    () => (count === null ? "Not loaded" : new Intl.NumberFormat().format(count)),
     [count]
   );
 
@@ -33,6 +33,10 @@ export function CounterCard() {
     }
   }, []);
 
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
   async function increment() {
     setLoading(true);
     setError(null);

package/templates/react-vite-counter/src/contracts/generated/counter.ts

@@ -45,7 +45,7 @@ export class Client {
   ) {}
 
   increment(): ExampleTransaction {
-    return new ExampleTransaction("increment");
+    return new ExampleTransaction("increment", 1);
   }
 
   get(): ExampleTransaction {

package/templates/react-vite-counter/src/wallet.ts

@@ -1,3 +1,4 @@
+// Keep in sync with examples/counter-web/src/wallet.ts (WalletConnect defaults differ per project).
 import {
   createStellarWalletsKitAdapter,
   type StellarWalletsKitMetadata

package/templates/react-vite-counter/vite.config.ts

@@ -4,7 +4,9 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 
 const require = createRequire(import.meta.url);
-const xbullWalletConnectRoot = dirname(require.resolve("@creit.tech/xbull-wallet-connect/package.json"));
+const xbullWalletConnectRoot = dirname(
+  require.resolve("@creit-tech/xbull-wallet-connect/package.json")
+);
 
 export default defineConfig({
   plugins: [react()],