@caatinga/cli 2.0.2 → 2.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @caatinga/cli
 
-Developer toolkit for Stellar / Soroban dApps — `init`, `build`, `deploy`, `generate`, and `invoke`.
+Developer toolkit for Stellar / Soroban dApps — `init`, `build`, `deploy`, `generate`, `status`, and `invoke`.
 
 ## Install
 
@@ -35,11 +35,11 @@ npm install
 
 npx caatinga build counter
 npx caatinga deploy counter --network testnet --source alice
-npx caatinga generate counter --network testnet
+npx caatinga status --network testnet
 npx caatinga invoke counter.increment --network testnet --source alice
 ```
 
-`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/`).
+`build` only compiles the WASM file. `deploy` writes contract IDs to `caatinga.artifacts.json` and then generates TypeScript bindings automatically under the path configured in `caatinga.config.ts` (templates default to `contracts/generated/`); pass `--no-generate` to skip. `status` shows what's deployed per network and whether bindings are fresh.
 
 ## Commands
 
@@ -49,10 +49,11 @@ npx caatinga invoke counter.increment --network testnet --source alice
 | `caatinga doctor [--network <network>] [--source <identity>]` | Check local Node, Stellar CLI, Rust, config, artifacts, network, and source identity setup |
 | `caatinga build [contract]` | Compile contract WASM through Stellar CLI (default contract: `counter`) |
 | `caatinga deploy [contract]` | Deploy one contract or the full configured graph; record IDs in artifacts |
-| `caatinga generate <contract>` | Generate TypeScript bindings from a deployed contract ID |
+| `caatinga generate [contract]` | (Re)generate TypeScript bindings; omit the name to generate for all deployed contracts |
+| `caatinga status [--network <name>] [--json]` | Show deployed contracts and binding freshness per network |
 | `caatinga invoke <contract.method>` | Invoke a deployed contract method; extra args forward to Stellar CLI |
 
-The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
+The supported CLI flow is `init -> build -> deploy (bindings auto-generate) -> invoke`.
 
 ### `init`
 
@@ -78,12 +79,17 @@ 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]`)
+- `--no-generate` skips the automatic bindings generation after deploy
 
 Dependencies listed in `dependsOn` deploy first unless `--no-deps` is set. Deploy args may reference `${contracts.<name>.contractId}` placeholders resolved from artifacts.
 
-### `generate` and `invoke`
+After a successful deploy, bindings generate automatically for the deployed contracts. A generation failure never fails the deploy — the CLI prints a warning plus the recovery command (`npx caatinga generate --network <network>`).
+
+### `generate`, `status`, and `invoke`
 
 - `-n, --network <network>` selects the network used to resolve deployed contract IDs
+- `generate` prints binding freshness per contract before regenerating in all-contracts mode
+- `status` prints a per-network table (contract ID, WASM hash, deployed, binding freshness, dependencies); `--json` emits the machine-readable structure
 - `invoke` expects `<contract.method>` (for example `counter.increment`) and forwards `[args...]` to the underlying Stellar invocation
 
 `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.

package/dist/index.js

@@ -161,9 +161,16 @@ async function warnIfDefaultNetworkNeedsDeploy(config) {
 }
 
 // src/commands/deploy.command.ts
-import { deployContractGraph, CaatingaError as CaatingaError2, CaatingaErrorCode as CaatingaErrorCode2, loadConfig as loadConfig3 } from "@caatinga/core";
+import {
+  deployContractGraph,
+  generateBindingsGraph,
+  toCaatingaError as toCaatingaError2,
+  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("--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").option("--no-generate", "Skip TypeScript bindings generation after deploy").action((contractName, options) => runCliAction(async () => {
     if (options.deps === false && !contractName) {
       throw new CaatingaError2(
         "`--no-deps` requires a contract name.",
@@ -197,6 +204,45 @@ function registerDeployCommand(program2) {
       logger.info(`  Contract ID: ${contract.contractId}`);
     }
     logger.info("Artifacts updated: caatinga.artifacts.json");
+    if (result.deployedContracts.length === 0) {
+      return;
+    }
+    if (options.generate === false) {
+      logger.info("");
+      logger.info("Bindings generation skipped (--no-generate).");
+      logger.info("Next:");
+      for (const contract of result.deployedContracts) {
+        logger.info(`  npx caatinga generate ${contract.name} --network ${result.network.name}`);
+      }
+      logger.info("  npm run dev");
+      return;
+    }
+    try {
+      const generated = await generateBindingsGraph({
+        config,
+        contractNames: result.deployedContracts.map((contract) => contract.name),
+        networkName: result.network.name
+      });
+      logger.info("");
+      logger.success("Bindings generated");
+      for (const binding of generated.results) {
+        logger.info(`  ${binding.contractName} \u2192 ${binding.importPath}`);
+      }
+      logger.info("");
+      logger.info("Next:");
+      logger.info("  npm run dev");
+    } catch (error) {
+      const caatingaError = toCaatingaError2(error);
+      logger.info("");
+      logger.warn("Deploy succeeded, but bindings generation failed.");
+      logger.warn(`  ${caatingaError.message} (${caatingaError.code})`);
+      if (caatingaError.hint) {
+        logger.warn(`  Hint: ${caatingaError.hint}`);
+      }
+      logger.info("");
+      logger.info("Recover with:");
+      logger.info(`  npx caatinga generate --network ${result.network.name}`);
+    }
   }));
 }
 
@@ -388,6 +434,33 @@ function printFixes(diagnostics) {
   }
 }
 
+// src/commands/doctor-bindings.ts
+import {
+  evaluateBindingsFreshness,
+  loadConfig as loadConfig5,
+  readArtifacts as readArtifacts3,
+  resolveNetwork as resolveNetwork3
+} from "@caatinga/core";
+async function evaluateBindingCoverage(options) {
+  const cwd = options.cwd;
+  const config = await loadConfig5({ cwd });
+  const network = resolveNetwork3(config, options.networkName);
+  const artifacts = await readArtifacts3(cwd);
+  const freshness = await evaluateBindingsFreshness({
+    config,
+    artifacts,
+    networkName: network.name,
+    cwd
+  });
+  const lines = freshness.map((entry) => ({
+    name: entry.contractName,
+    status: entry.status,
+    reason: entry.reason,
+    ...entry.status === "fresh" ? {} : { fix: `Run: caatinga generate ${entry.contractName} --network ${network.name}` }
+  }));
+  return { lines, allFresh: lines.every((line) => line.status === "fresh") };
+}
+
 // src/commands/doctor.command.ts
 function printDeployCoverageLine(line) {
   if (line.ok) {
@@ -414,6 +487,25 @@ async function reportDeployCoverage(networkName) {
   }
   return true;
 }
+function printBindingCoverageLine(line) {
+  if (line.status === "fresh") {
+    logger.info(`\u2713 ${line.name} \u2014 bindings fresh`);
+    return;
+  }
+  logger.info(`\u2717 ${line.name} \u2014 bindings ${line.status}${line.reason ? ` (${line.reason})` : ""}`);
+  if (line.fix) logger.info(`  ${line.fix}`);
+}
+async function reportBindingCoverage(networkName) {
+  const coverage = await evaluateBindingCoverage({ networkName });
+  if (coverage.lines.length === 0) {
+    return;
+  }
+  logger.info("");
+  logger.info(`Bindings (${networkName}):`);
+  for (const line of coverage.lines) {
+    printBindingCoverageLine(line);
+  }
+}
 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").action((options) => runCliAction(async () => {
     logger.info("Caatinga Doctor");
@@ -431,6 +523,7 @@ function registerDoctorCommand(program2) {
         ready = false;
         throw error;
       }
+      await reportBindingCoverage(options.network);
     }
     logger.info("");
     logger.info(`Status: ${ready ? "ready" : "blocked"}`);
@@ -441,23 +534,56 @@ function registerDoctorCommand(program2) {
 }
 
 // src/commands/generate.command.ts
-import { generateBindings, loadConfig as loadConfig5 } from "@caatinga/core";
+import {
+  evaluateBindingsFreshness as evaluateBindingsFreshness2,
+  generateBindingsGraph as generateBindingsGraph2,
+  loadConfig as loadConfig6,
+  readArtifacts as readArtifacts4,
+  resolveNetwork as resolveNetwork4
+} from "@caatinga/core";
+async function printFreshnessPreState(config, networkName) {
+  try {
+    const network = resolveNetwork4(config, networkName);
+    const artifacts = await readArtifacts4();
+    const freshness = await evaluateBindingsFreshness2({
+      config,
+      artifacts,
+      networkName: network.name
+    });
+    if (freshness.length === 0) {
+      return;
+    }
+    logger.info("Current bindings:");
+    for (const entry of freshness) {
+      const reason = entry.reason ? ` \u2014 ${entry.reason}` : "";
+      logger.info(`  [${entry.status}] ${entry.contractName}${reason}`);
+    }
+    logger.info("");
+  } catch {
+  }
+}
 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").action((contractName, options) => runCliAction(async () => {
-    const config = await loadConfig5();
-    const result = await generateBindings({
+  program2.command("generate").description("Generate TypeScript bindings for deployed contracts").argument("[contract]", "Contract name (defaults to all deployed contracts)").option("-n, --network <network>", "Configured network name").action((contractName, options) => runCliAction(async () => {
+    const config = await loadConfig6();
+    if (!contractName) {
+      await printFreshnessPreState(config, options.network);
+    }
+    const { network, results } = await generateBindingsGraph2({
       config,
       contractName,
       networkName: options.network
     });
     logger.success("Client generated");
     logger.info("");
-    logger.info(`Contract: ${result.contractName}`);
-    logger.info(`Network: ${result.network.name}`);
-    logger.info(`Output: ${result.outputDir}`);
-    logger.info(`Import path: ${result.importPath}`);
-    if (result.legacyStubRemoved) {
-      logger.info(`Removed legacy stub: ${config.frontend.bindingsOutput}/${result.contractName}.ts`);
+    logger.info(`Network: ${network.name}`);
+    for (const result of results) {
+      logger.info("");
+      logger.info(`Contract: ${result.contractName}`);
+      logger.info(`Output: ${result.outputDir}`);
+      logger.info(`Import path: ${result.importPath}`);
+      if (result.legacyStubRemoved) {
+        logger.info(`Removed legacy stub: ${config.frontend.bindingsOutput}/${result.contractName}.ts`);
+      }
     }
     logger.info("");
     logger.info("Next: import bindings from the import path above, then run npm run dev");
@@ -540,21 +666,34 @@ function registerInitCommand(program2) {
     logger.info(`Template: ${result.template.name}@${result.template.version}`);
     logger.info(`Path: ${targetDir}`);
     logger.info("");
+    const defaultContract = result.template.contracts.default;
     logger.info("Next steps:");
     logger.info(`  cd ${projectDirectory}`);
     logger.info("  npm install");
-    const defaultContract = result.template.contracts.default;
+    if (defaultContract) {
+      logger.info(`  npx caatinga build    ${defaultContract}`);
+      logger.info(
+        `  npx caatinga deploy   ${defaultContract} --network testnet --source <identity>`
+      );
+    } else {
+      logger.info("  npx caatinga build");
+      logger.info("  npx caatinga deploy   --network testnet --source <identity>");
+    }
+    logger.info("  npm run dev");
+    logger.info("");
     logger.info(
-      defaultContract ? `  npx caatinga build ${defaultContract}` : "  npx caatinga build"
+      "Note: deploy generates TypeScript bindings automatically (--no-generate to skip) \u2014"
     );
+    logger.info("the dApp reads the contract ID from caatinga.artifacts.json.");
+    logger.info("If generation fails, recover with: npx caatinga generate --network testnet");
   }));
 }
 
 // src/commands/invoke.command.ts
-import { invokeContract, loadConfig as loadConfig6 } from "@caatinga/core";
+import { invokeContract, loadConfig as loadConfig7 } 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)").allowUnknownOption(true).allowExcessArguments(true).action((target, args, options) => runCliAction(async () => {
-    const config = await loadConfig6();
+    const config = await loadConfig7();
     const result = await invokeContract({
       config,
       target,
@@ -574,8 +713,77 @@ function registerInvokeCommand(program2) {
   }));
 }
 
+// src/commands/status.command.ts
+import { collectProjectStatus, loadConfig as loadConfig8 } from "@caatinga/core";
+
+// src/utils/table.ts
+function renderTable(headers, rows) {
+  const widths = headers.map(
+    (header, column) => Math.max(header.length, ...rows.map((row) => (row[column] ?? "").length))
+  );
+  const renderRow = (cells) => cells.map((cell, column) => (cell ?? "").padEnd(widths[column])).join("  ").trimEnd();
+  return [
+    renderRow(headers),
+    widths.map((width) => "\u2500".repeat(width)).join("  "),
+    ...rows.map((row) => renderRow(row))
+  ];
+}
+
+// src/commands/status.command.ts
+function shortId(value) {
+  if (!value) return "\u2014";
+  return value.length > 12 ? `${value.slice(0, 5)}\u2026${value.slice(-4)}` : value;
+}
+function shortHash(value) {
+  if (!value) return "\u2014";
+  return value.slice(0, 8);
+}
+function toRow(entry) {
+  return [
+    entry.name,
+    shortId(entry.contractId),
+    shortHash(entry.wasmHash),
+    entry.deployed ? "\u2713" : "\u2717",
+    entry.bindings.status,
+    entry.dependencies.length > 0 ? entry.dependencies.join(", ") : "\u2014"
+  ];
+}
+function registerStatusCommand(program2) {
+  program2.command("status").description("Show deployed contracts and binding freshness per network").option("-n, --network <network>", "Configured network name").option("--json", "Print machine-readable JSON instead of the table").action((options) => runCliAction(async () => {
+    const config = await loadConfig8();
+    const status = await collectProjectStatus({
+      config,
+      networkName: options.network
+    });
+    if (options.json) {
+      console.log(JSON.stringify(status, null, 2));
+      return;
+    }
+    logger.success(`Project: ${status.project}`);
+    for (const network of status.networks) {
+      logger.info("");
+      logger.info(`Network: ${network.network}`);
+      const lines = renderTable(
+        ["CONTRACT", "CONTRACT ID", "WASM HASH", "DEPLOYED", "BINDINGS", "DEPS"],
+        network.contracts.map(toRow)
+      );
+      for (const line of lines) {
+        logger.info(line);
+      }
+      const needsAttention = network.contracts.filter(
+        (entry) => entry.deployed && entry.bindings.status !== "fresh"
+      );
+      for (const entry of needsAttention) {
+        logger.warn(
+          `Bindings ${entry.bindings.status} for ${entry.name}${entry.bindings.reason ? ` (${entry.bindings.reason})` : ""} \u2014 run: npx caatinga generate ${entry.name} --network ${network.network}`
+        );
+      }
+    }
+  }));
+}
+
 // src/version.ts
-var CAATINGA_CLI_VERSION = "2.0.2";
+var CAATINGA_CLI_VERSION = "2.2.0";
 
 // src/program.ts
 function createProgram() {
@@ -588,6 +796,7 @@ function createProgram() {
   registerDeployCommand(program2);
   registerGenerateCommand(program2);
   registerInvokeCommand(program2);
+  registerStatusCommand(program2);
   return program2;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caatinga/cli",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Caatinga CLI for building dApps on Stellar/Soroban",
   "keywords": [
     "stellar",
@@ -43,7 +43,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@caatinga/core": "^2.0.2",
+    "@caatinga/core": "^2.2.0",
     "chalk": "^5.4.1",
     "commander": "^12.1.0"
   },
@@ -54,7 +54,7 @@
     "vitest": "^2.1.8"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean && rm -rf ./templates && cp -r ../templates ./templates",
+    "build": "tsup src/index.ts --format esm --dts --clean && rm -rf ./templates && mkdir ./templates && (cd ../templates && tar --exclude=node_modules --exclude=dist -cf - .) | (cd ./templates && tar -xf -)",
     "predev": "pnpm --filter @caatinga/core build",
     "dev": "tsx src/index.ts",
     "test": "vitest run --pool=threads",

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": "^2.0.2",
+    "compatibleCore": "^2.2.0",
     "templateVersion": 1
   },
   "frontend": {

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

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

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": "^2.0.2",
+    "compatibleCore": "^2.2.0",
     "templateVersion": 1
   },
   "frontend": {

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

@@ -7,14 +7,14 @@
     "dev": "vite",
     "build": "tsc && vite build",
     "preview": "vite preview",
-    "caatinga:build": "caatinga build counter",
-    "caatinga:deploy": "caatinga deploy counter",
-    "caatinga:generate": "caatinga generate counter"
+    "caatinga:build": "npx caatinga build counter",
+    "caatinga:deploy": "npx caatinga deploy counter --network testnet --source ${CAATINGA_SOURCE:-alice}",
+    "caatinga:generate": "npx caatinga generate counter --network testnet"
   },
   "dependencies": {
-    "@caatinga/client": "^2.0.2",
-    "@caatinga/core": "^2.0.2",
-    "@creit.tech/stellar-wallets-kit": "^1.9.5",
+    "@caatinga/client": "^2.2.0",
+    "@caatinga/core": "^2.2.0",
+    "@creit.tech/stellar-wallets-kit": "^2.3.0",
     "@stellar/stellar-sdk": "^14.5.0",
     "buffer": "^6.0.3",
     "@vitejs/plugin-react": "^4.3.4",
@@ -23,7 +23,7 @@
     "vite": "^6.0.6"
   },
   "devDependencies": {
-    "@caatinga/cli": "^2.0.2",
+    "@caatinga/cli": "^2.2.0",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "typescript": "^5.7.2"

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

@@ -1,12 +1,6 @@
-# pnpm 10.26+ / 11.x block lifecycle scripts by default; vite depends on esbuild.
+# pnpm-only file (npm / yarn / bun ignore it). pnpm 10.26+/11.x block lifecycle
+# scripts by default; vite depends on esbuild's, so allow it. All dependency
+# stubbing now happens at the build layer (see vite.config.ts), so no pnpm-only
+# `overrides` are needed and this template installs identically on every PM.
 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/App.tsx

@@ -1,6 +1,15 @@
+import { WalletProvider, useWallet } from "@caatinga/client/react";
+import type { CaatingaArtifacts } from "@caatinga/core/browser";
+import artifactsJson from "../caatinga.artifacts.json";
+import { ContractNotDeployed } from "./components/ContractNotDeployed";
 import { CounterCard } from "./components/CounterCard";
 import { WalletButton } from "./components/WalletButton";
-import { WalletProvider, useWallet } from "./context/WalletContext";
+import { WalletModal } from "./components/WalletModal";
+import { stellarWalletAdapter } from "./wallet.js";
+
+const artifacts = artifactsJson as CaatingaArtifacts;
+const counterContractId = artifacts.networks?.testnet?.contracts?.counter?.contractId;
+const isDeployed = Boolean(counterContractId);
 
 function AppBody() {
   const { publicKey } = useWallet();
@@ -15,7 +24,9 @@ function AppBody() {
         <WalletButton />
       </header>
 
-      {publicKey ? (
+      {!isDeployed ? (
+        <ContractNotDeployed />
+      ) : publicKey ? (
         <CounterCard />
       ) : (
         <section className="counter-panel" aria-labelledby="connect-title">
@@ -35,8 +46,11 @@ function AppBody() {
 
 export default function App() {
   return (
-    <WalletProvider>
+    // persist keeps the session across reloads; the provider silently
+    // reconnects on mount (autoConnect defaults to true when persisting).
+    <WalletProvider adapter={stellarWalletAdapter} options={{ persist: true }}>
       <AppBody />
+      <WalletModal />
     </WalletProvider>
   );
 }

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

@@ -0,0 +1,27 @@
+export function ContractNotDeployed() {
+  return (
+    <section className="counter-panel" aria-labelledby="not-deployed-title">
+      <div className="counter-panel__header">
+        <div>
+          <p className="eyebrow">Get started</p>
+          <h2 id="not-deployed-title">Contract not deployed</h2>
+        </div>
+        <span className="network-pill">testnet</span>
+      </div>
+      <p>
+        The counter contract has no on-chain ID yet, so the frontend can&apos;t read or update it.
+        Build and deploy first — the dApp reads the contract ID from{" "}
+        <code>caatinga.artifacts.json</code>. Deploy also generates TypeScript bindings
+        automatically.
+      </p>
+      <pre className="counter-error" role="note">
+        {`npx caatinga build    counter
+npx caatinga deploy   counter --network testnet --source <identity>
+npm run dev
+
+# If bindings generation failed after deploy:
+npx caatinga generate counter --network testnet`}
+      </pre>
+    </section>
+  );
+}

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

@@ -1,17 +1,9 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { caatingaClient } from "../caatinga.js";
-import { CaatingaError } from "@caatinga/core/browser";
-import { useWallet } from "../context/WalletContext.js";
+import { formatCaatingaError } from "@caatinga/core/browser";
+import { useWallet } from "@caatinga/client/react";
 import { LoadingModal } from "./LoadingModal.js";
 
-function formatCaatingaError(error: unknown): string {
-  if (error instanceof CaatingaError) {
-    return `[${error.code}] ${error.message}\n\n${error.hint}`;
-  }
-
-  return error instanceof Error ? error.message : String(error);
-}
-
 export function CounterCard() {
   const { publicKey } = useWallet();
   const [count, setCount] = useState<number | null>(null);

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

@@ -1,4 +1,5 @@
-import { useWallet } from "../context/WalletContext.js";
+import { useWallet } from "@caatinga/client/react";
+import { WALLET_SELECTION_CLOSED_ERROR } from "../wallet-modal-controller.js";
 
 function shortenAddress(address: string): string {
   if (address.length <= 12) {
@@ -9,23 +10,23 @@ function shortenAddress(address: string): string {
 }
 
 export function WalletButton() {
-  const { publicKey, loading, error, connect, disconnect } = useWallet();
+  const { publicKey, connecting, error, connect, disconnect } = useWallet();
 
   return (
     <div className="wallet-shell">
       <button
         className="wallet-button"
         type="button"
-        onClick={publicKey ? () => void disconnect() : () => void connect()}
-        disabled={loading}
+        onClick={publicKey ? () => void disconnect() : () => void connect().catch(() => {})}
+        disabled={connecting}
         aria-live="polite"
       >
         <span className={publicKey ? "status-dot status-dot--on" : "status-dot"} />
-        {loading ? "Connecting..." : publicKey ? shortenAddress(publicKey) : "Connect"}
+        {connecting ? "Connecting..." : publicKey ? shortenAddress(publicKey) : "Connect"}
       </button>
-      {error ? (
+      {error && error.name !== WALLET_SELECTION_CLOSED_ERROR ? (
         <p className="wallet-error" role="alert">
-          {error}
+          {error.message}
         </p>
       ) : null}
     </div>