@caatinga/cli 2.0.1 → 2.1.0

package/README.md

@@ -49,7 +49,7 @@ 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]` | Generate TypeScript bindings from a deployed contract ID; omit the name to generate for all deployed contracts |
 | `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`.

package/dist/index.js

@@ -197,6 +197,16 @@ function registerDeployCommand(program2) {
       logger.info(`  Contract ID: ${contract.contractId}`);
     }
     logger.info("Artifacts updated: caatinga.artifacts.json");
+    if (result.deployedContracts.length > 0) {
+      logger.info("");
+      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");
+      logger.info("");
+      logger.info("Run generate before npm run dev so the app uses real bindings, not the stub.");
+    }
   }));
 }
 
@@ -441,20 +451,29 @@ function registerDoctorCommand(program2) {
 }
 
 // src/commands/generate.command.ts
-import { generateBindings, loadConfig as loadConfig5 } from "@caatinga/core";
+import { generateBindingsGraph, 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").action((contractName, options) => runCliAction(async () => {
+  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 loadConfig5();
-    const result = await generateBindings({
+    const { network, results } = await generateBindingsGraph({
       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(`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");
   }));
 }
 
@@ -534,13 +553,27 @@ 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>`
+      );
+      logger.info(`  npx caatinga generate ${defaultContract} --network testnet`);
+    } else {
+      logger.info("  npx caatinga build");
+      logger.info("  npx caatinga deploy   --network testnet --source <identity>");
+      logger.info("  npx caatinga generate --network testnet");
+    }
+    logger.info("  npm run dev");
+    logger.info("");
     logger.info(
-      defaultContract ? `  npx caatinga build ${defaultContract}` : "  npx caatinga build"
+      "Note: deploy and generate the contract before interacting in the frontend \u2014"
     );
+    logger.info("the dApp reads the contract ID from caatinga.artifacts.json.");
   }));
 }
 
@@ -569,7 +602,7 @@ function registerInvokeCommand(program2) {
 }
 
 // src/version.ts
-var CAATINGA_CLI_VERSION = "2.0.1";
+var CAATINGA_CLI_VERSION = "2.1.0";
 
 // src/program.ts
 function createProgram() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caatinga/cli",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Caatinga CLI for building dApps on Stellar/Soroban",
   "keywords": [
     "stellar",
@@ -43,7 +43,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@caatinga/core": "^2.0.1",
+    "@caatinga/core": "^2.1.0",
     "chalk": "^5.4.1",
     "commander": "^12.1.0"
   },

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.1",
+    "compatibleCore": "^2.1.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.1",
-    "@caatinga/core": "^2.0.1",
+    "@caatinga/client": "^2.1.0",
+    "@caatinga/core": "^2.1.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.1",
+    "@caatinga/cli": "^2.1.0",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "typescript": "^5.7.2"

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

@@ -15,6 +15,8 @@ npm run dev          # or: pnpm dev
 
 Run `build` before `deploy` (WASM required) and `deploy` before `generate` (contract ID required).
 
+The checked-in binding stub under `src/contracts/generated/counter/src/index.ts` is a placeholder so the template type-checks before you run `caatinga generate`. Run `caatinga generate` before `npm run dev` so the browser uses real Stellar CLI bindings instead of the stub.
+
 Use a local Stellar CLI identity alias for `--source`; public `G...` addresses, seed phrases, and secret keys are rejected for signing operations.
 
 ## Package managers
@@ -38,7 +40,7 @@ After `caatinga generate`, wire generated bindings to the client:
 ```ts
 import { createCaatingaClient } from "@caatinga/client";
 import { createStellarWalletsKitAdapter } from "@caatinga/client/stellar-wallets-kit";
-import * as Counter from "./contracts/generated/counter";
+import * as Counter from "./contracts/generated/counter/src/index.js";
 import artifacts from "../caatinga.artifacts.json";
 
 const wallet = createStellarWalletsKitAdapter();

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

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

@@ -12,16 +12,18 @@
     "caatinga:generate": "caatinga generate counter"
   },
   "dependencies": {
-    "@caatinga/client": "^2.0.1",
-    "@caatinga/core": "^2.0.1",
+    "@caatinga/client": "^2.1.0",
+    "@caatinga/core": "^2.1.0",
     "@creit.tech/stellar-wallets-kit": "^1.9.5",
+    "@stellar/stellar-sdk": "^14.5.0",
+    "buffer": "^6.0.3",
     "@vitejs/plugin-react": "^4.3.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "vite": "^6.0.6"
   },
   "devDependencies": {
-    "@caatinga/cli": "^2.0.1",
+    "@caatinga/cli": "^2.1.0",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "typescript": "^5.7.2"

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

@@ -1,7 +1,7 @@
 import { createCaatingaClient } from "@caatinga/client";
 import type { CaatingaArtifacts } from "@caatinga/core/browser";
 import artifactsJson from "../caatinga.artifacts.json";
-import * as Counter from "./contracts/generated/counter.js";
+import * as Counter from "./contracts/generated/counter/src/index.js";
 import { stellarWalletAdapter } from "./wallet.js";
 
 const artifacts = artifactsJson as CaatingaArtifacts;

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 { formatCaatingaError } from "@caatinga/core/browser";
 import { useWallet } from "../context/WalletContext.js";
 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/contracts/generated/counter/src/index.ts

@@ -0,0 +1,43 @@
+// Placeholder bindings. This file exists so the template type-checks before you
+// run `caatinga generate`. It does NOT talk to the chain — every method throws a
+// clear, actionable error. `caatinga generate counter` overwrites this file with
+// real Stellar CLI bindings.
+import { CaatingaError, CaatingaErrorCode } from "@caatinga/core/browser";
+
+// Marker the client checks to detect that real bindings haven't been generated
+// yet. Real Stellar CLI bindings never export this.
+export const __caatingaPlaceholder = true;
+
+const GENERATE_HINT =
+  "Run `npx caatinga generate counter --network testnet`, then restart the dev server.";
+
+function placeholderBinding(method: string): never {
+  throw new CaatingaError(
+    `Placeholder bindings are still in use for "counter.${method}".`,
+    CaatingaErrorCode.PLACEHOLDER_BINDING,
+    GENERATE_HINT
+  );
+}
+
+export class Client {
+  constructor(
+    private readonly input: {
+      contractId: string;
+      publicKey: string;
+      rpcUrl: string;
+      networkPassphrase: string;
+    }
+  ) {}
+
+  increment(): never {
+    return placeholderBinding("increment");
+  }
+
+  get(): never {
+    return placeholderBinding("get");
+  }
+
+  describe(): string {
+    return `${this.input.contractId}:${this.input.publicKey}`;
+  }
+}

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

@@ -1,58 +0,0 @@
-type TransactionResult = {
-  txHash: string;
-  result?: unknown;
-};
-
-type SignTransaction = (
-  xdr: string,
-  opts?: { networkPassphrase?: string; address?: string }
-) => Promise<{ signedTxXdr: string }> | { signedTxXdr: string };
-
-class ExampleTransaction {
-  constructor(
-    private readonly method: string,
-    private readonly result?: unknown
-  ) {}
-
-  toXDR(): string {
-    return `example-${this.method}-xdr`;
-  }
-
-  async prepare(): Promise<ExampleTransaction> {
-    return this;
-  }
-
-  async signAndSend(input?: { signTransaction?: SignTransaction }): Promise<TransactionResult> {
-    const signed = input?.signTransaction
-      ? await input.signTransaction(this.toXDR())
-      : { signedTxXdr: this.toXDR() };
-
-    return {
-      txHash: `example-transaction-hash:${signed.signedTxXdr}`,
-      result: this.result
-    };
-  }
-}
-
-export class Client {
-  constructor(
-    private readonly input: {
-      contractId: string;
-      publicKey: string;
-      rpcUrl: string;
-      networkPassphrase: string;
-    }
-  ) {}
-
-  increment(): ExampleTransaction {
-    return new ExampleTransaction("increment", 1);
-  }
-
-  get(): ExampleTransaction {
-    return new ExampleTransaction("get", 1);
-  }
-
-  describe(): string {
-    return `${this.input.contractId}:${this.input.publicKey}`;
-  }
-}