@caatinga/cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Kaleido contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @caatinga/cli
+
+## Install
+
+```bash
+npm install -g @caatinga/cli
+caatinga --help
+```
+
+## Requirements
+
+- Node.js `>=20`
+- Stellar CLI `>=22.0.0` and `<=25.2.0` available on `PATH`
+- A Caatinga project with `caatinga.config.ts` for project commands such as `build`, `deploy`, `generate`, and `invoke`
+
+If your local machine is on a newer Stellar CLI, `--allow-untested-stellar-cli` is the local-only escape hatch. CI and release workflows should stay on the supported range.
+
+## Commands
+
+- `caatinga init <projectName>` creates a project from a bundled template and writes `caatinga.artifacts.json`
+- `caatinga build [contract]` builds one configured contract through Stellar CLI and defaults to `counter` when omitted
+- `caatinga deploy [contract] --source <identity> [--network <network>] [--force] [--no-deps]` deploys contracts and records contract IDs in `caatinga.artifacts.json`
+- `caatinga generate <contract> [--network <network>]` generates TypeScript bindings from a deployed contract ID
+- `caatinga invoke <contract.method> --source <identity> [args...]` invokes a deployed contract method through the configured workflow
+
+The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
+
+## Supported Inputs
+
+- `--source` accepts a Stellar CLI identity alias or public `G...` account address
+- `--network <network>` selects a configured network such as `testnet`
+- `invoke` expects a `<contract.method>` target and forwards extra args to the underlying Stellar contract invocation
+- `deploy --no-deps` is supported only when deploying a single named contract
+
+Unsupported input posture:
+
+- secret keys and seed phrases are not supported CLI inputs
+- undocumented private flags or internal repo file paths are not part of the package contract
+
+## Error Behavior
+
+`@caatinga/cli` emits documented `CAATINGA_*` error codes for automation. Consumers should match on the error code, not human-readable text.
+
+Common codes include:
+
+- `CAATINGA_CONFIG_NOT_FOUND`
+- `CAATINGA_INVALID_CONFIG`
+- `CAATINGA_STELLAR_CLI_NOT_FOUND`
+- `CAATINGA_BUILD_FAILED`
+- `CAATINGA_DEPLOY_FAILED`
+- `CAATINGA_BINDINGS_FAILED`
+- `CAATINGA_INVOKE_FAILED`
+- `CAATINGA_CONTRACT_ID_NOT_FOUND`
+- `CAATINGA_SOURCE_ACCOUNT_REQUIRED`
+- `CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND`
+- `CAATINGA_TEMPLATE_INCOMPATIBLE`
+
+## Relationship To `@caatinga/core`
+
+`@caatinga/cli` is the supported end-user entrypoint for Caatinga's command workflow. It intentionally stays thin and delegates config loading, artifacts, command orchestration, and shared error primitives to `@caatinga/core`.
+
+If you want the stable packaged workflow, prefer the CLI contract over importing `@caatinga/core` directly.
+
+## Versioning And Stability
+
+This package is the primary supported consumer surface for the Caatinga workflow. Stability applies to the documented commands, inputs, and `CAATINGA_*` error contract.
+
+Undocumented internals, private module paths, and reserved hidden commands such as `caatinga dev` are not part of the stability promise.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+// src/program.ts
+import { Command } from "commander";
+
+// src/commands/build.command.ts
+import { buildContract, loadConfig } from "@caatinga/core";
+
+// src/utils/errors.ts
+import { toCaatingaError } from "@caatinga/core";
+
+// src/utils/logger.ts
+import chalk from "chalk";
+var logger = {
+  info(message) {
+    console.log(message);
+  },
+  success(message) {
+    console.log(chalk.green(message));
+  },
+  warn(message) {
+    console.warn(chalk.yellow(message));
+  },
+  error(message) {
+    console.error(chalk.red(message));
+  },
+  muted(message) {
+    console.log(chalk.gray(message));
+  }
+};
+
+// src/utils/errors.ts
+function printError(error) {
+  const caatingaError = toCaatingaError(error);
+  logger.error(`Error: ${caatingaError.message}`);
+  logger.info("");
+  logger.info(`Code: ${caatingaError.code}`);
+  if (caatingaError.hint) {
+    logger.info(`Hint: ${caatingaError.hint}`);
+  }
+}
+async function runCliAction(action) {
+  try {
+    await action();
+  } catch (error) {
+    printError(error);
+    process.exitCode = 1;
+  }
+}
+
+// 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();
+    const result = await buildContract({
+      config,
+      contractName,
+      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+    });
+    logger.success("Contract built");
+    logger.info("");
+    logger.info(`Contract: ${result.contract.name}`);
+    logger.info(`WASM: ${result.contract.config.wasm}`);
+  }));
+}
+
+// src/commands/deploy.command.ts
+import { deployContractGraph, CaatingaError, CaatingaErrorCode, loadConfig as loadConfig2 } 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 or public account address").option("--force", "Redeploy contracts even if artifacts already contain contract IDs").option("--no-deps", "Do not deploy missing dependencies for a selected contract").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").action((contractName, options) => runCliAction(async () => {
+    if (options.deps === false && !contractName) {
+      throw new CaatingaError(
+        "`--no-deps` requires a contract name.",
+        CaatingaErrorCode.INVALID_CONFIG,
+        "Select a single contract or omit `--no-deps` to deploy the full graph."
+      );
+    }
+    const config = await loadConfig2();
+    const result = await deployContractGraph({
+      config,
+      contractName,
+      networkName: options.network,
+      source: options.source,
+      includeDependencies: options.deps !== false,
+      force: options.force === true,
+      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+    });
+    logger.success("Deploy complete");
+    logger.info("");
+    logger.info(`Network: ${result.network.name}`);
+    for (const contract of result.deployedContracts) {
+      logger.info(`Contract: ${contract.name}`);
+      logger.info(`Contract ID: ${contract.contractId}`);
+    }
+    logger.info("Artifacts updated: caatinga.artifacts.json");
+  }));
+}
+
+// src/commands/dev.command.ts
+function registerDevCommand(program2) {
+  const dev = program2.command("dev", { hidden: true }).description("Reserved \u2014 not available in pre-v1").action(() => runCliAction(async () => {
+    logger.error(
+      "caatinga dev is not available yet. Use: caatinga build, deploy, generate, invoke."
+    );
+    process.exitCode = 1;
+  }));
+  dev.helpOption(false);
+  dev.configureHelp({ visibleOptions: () => [] });
+}
+
+// src/commands/generate.command.ts
+import { generateBindings, loadConfig as loadConfig3 } 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 () => {
+    const config = await loadConfig3();
+    const result = await generateBindings({
+      config,
+      contractName,
+      networkName: options.network,
+      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+    });
+    logger.success("Client generated");
+    logger.info("");
+    logger.info(`Contract: ${result.contractName}`);
+    logger.info(`Network: ${result.network.name}`);
+    logger.info(`Output: ${result.outputDir}`);
+  }));
+}
+
+// src/commands/init.command.ts
+import path2 from "path";
+import { createProjectFromTemplate } from "@caatinga/core";
+
+// src/utils/template-path.ts
+import { access } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import { CaatingaError as CaatingaError2, CaatingaErrorCode as CaatingaErrorCode2 } from "@caatinga/core";
+async function resolveTemplateDir(templateName) {
+  const envTemplatesDir = process.env.CAATINGA_TEMPLATES_DIR;
+  const candidates = [
+    envTemplatesDir ? path.join(envTemplatesDir, templateName) : void 0,
+    path.resolve(process.cwd(), "packages", "templates", templateName),
+    ...candidatePathsFromModule(templateName)
+  ].filter((candidate) => Boolean(candidate));
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new CaatingaError2(
+    `Template "${templateName}" was not found.`,
+    CaatingaErrorCode2.TEMPLATE_NOT_FOUND,
+    "Set CAATINGA_TEMPLATES_DIR or run from a Caatinga checkout that includes packages/templates."
+  );
+}
+function candidatePathsFromModule(templateName) {
+  const currentFile = fileURLToPath(import.meta.url);
+  const start = path.dirname(currentFile);
+  const candidates = [];
+  let dir = start;
+  for (let depth = 0; depth < 8; depth += 1) {
+    candidates.push(path.join(dir, "packages", "templates", templateName));
+    candidates.push(path.join(dir, "templates", templateName));
+    candidates.push(path.join(dir, "node_modules", "@caatinga", "templates", templateName));
+    dir = path.dirname(dir);
+  }
+  return candidates;
+}
+
+// src/commands/init.command.ts
+function registerInitCommand(program2) {
+  program2.command("init").description("Create a new Caatinga dApp from a template").argument("<projectName>", "Project directory to create").option("-t, --template <template>", "Template name", "react-vite-counter").action((projectName, options) => runCliAction(async () => {
+    const templateDir = await resolveTemplateDir(options.template);
+    const targetDir = path2.resolve(process.cwd(), projectName);
+    const normalizedProjectName = path2.basename(targetDir);
+    const projectDirectory = path2.isAbsolute(projectName) ? targetDir : projectName;
+    const result = await createProjectFromTemplate({
+      projectName: normalizedProjectName,
+      targetDir,
+      templateDir
+    });
+    logger.success("Project created");
+    logger.info("");
+    logger.info(`Project: ${normalizedProjectName}`);
+    logger.info(`Template: ${result.template.name}@${result.template.version}`);
+    logger.info(`Path: ${targetDir}`);
+    logger.info("");
+    logger.info("Next steps:");
+    logger.info(`  cd ${projectDirectory}`);
+    logger.info("  npm install");
+    logger.info("  npx caatinga build counter");
+  }));
+}
+
+// src/commands/invoke.command.ts
+import { invokeContract, loadConfig as loadConfig4 } 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 or public account address").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 () => {
+    const config = await loadConfig4();
+    const result = await invokeContract({
+      config,
+      target,
+      args,
+      networkName: options.network,
+      source: options.source,
+      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+    });
+    logger.success("Invoke complete");
+    logger.info("");
+    logger.info(`Network: ${result.network.name}`);
+    logger.info(`Contract: ${result.target.contractName}`);
+    logger.info(`Method: ${result.target.method}`);
+    if (result.result) {
+      logger.info("");
+      logger.info(result.result);
+    }
+  }));
+}
+
+// src/version.ts
+var CAATINGA_CLI_VERSION = "0.2.0";
+
+// src/program.ts
+function createProgram() {
+  const program2 = new Command();
+  program2.name("caatinga").description("Developer toolkit for Stellar/Soroban dApps").version(CAATINGA_CLI_VERSION);
+  registerInitCommand(program2);
+  registerDevCommand(program2);
+  registerBuildCommand(program2);
+  registerDeployCommand(program2);
+  registerGenerateCommand(program2);
+  registerInvokeCommand(program2);
+  return program2;
+}
+
+// src/index.ts
+var program = createProgram();
+void program.parseAsync(process.argv).catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@caatinga/cli",
+  "version": "0.2.0",
+  "description": "Caatinga CLI for building dApps on Stellar/Soroban",
+  "keywords": [
+    "stellar",
+    "soroban",
+    "cli",
+    "dapp",
+    "smart-contracts",
+    "blockchain",
+    "web3",
+    "caatinga"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dione-b/caatinga.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Dione-b/caatinga#readme",
+  "author": "Caatinga contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "caatinga": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@caatinga/core": "^0.2.0",
+    "chalk": "^5.4.1",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean && rm -rf ./templates && cp -r ../templates ./templates",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run --pool=threads",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/templates/marketplace-with-token/README.md

@@ -0,0 +1,19 @@
+# __PROJECT_NAME__
+
+Experimental Caatinga multi-contract template.
+
+## Deploy
+
+```bash
+npm install
+npx caatinga build token
+npx caatinga build marketplace
+npx caatinga deploy --network testnet --source alice
+```
+
+Deploy order:
+
+1. `token`
+2. `marketplace`
+
+`marketplace.deployArgs.tokenContractId` resolves from `${contracts.token.contractId}` after the token deploy writes `caatinga.artifacts.json`.

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

@@ -0,0 +1,10 @@
+{
+  "project": "__PROJECT_NAME__",
+  "version": 1,
+  "networks": {
+    "testnet": {
+      "contracts": {},
+      "dependencyGraph": {}
+    }
+  }
+}

package/templates/marketplace-with-token/caatinga.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from "@caatinga/core";
+
+export default defineConfig({
+  project: "__PROJECT_NAME__",
+  defaultNetwork: "testnet",
+  contracts: {
+    token: {
+      path: "./contracts/token",
+      wasm: "./contracts/token/target/wasm32-unknown-unknown/release/token.wasm"
+    },
+    marketplace: {
+      path: "./contracts/marketplace",
+      wasm: "./contracts/marketplace/target/wasm32-unknown-unknown/release/marketplace.wasm",
+      dependsOn: ["token"],
+      deployArgs: {
+        tokenContractId: "${contracts.token.contractId}"
+      }
+    }
+  },
+  networks: {
+    testnet: {
+      rpcUrl: "https://soroban-testnet.stellar.org",
+      networkPassphrase: "Test SDF Network ; September 2015"
+    }
+  },
+  frontend: {
+    framework: "vite-react",
+    bindingsOutput: "./src/contracts/generated"
+  }
+});

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

@@ -0,0 +1,21 @@
+{
+  "name": "marketplace-with-token",
+  "version": "0.1.0",
+  "description": "Experimental multi-contract Soroban template with token dependency injection.",
+  "caatinga": {
+    "compatibleCore": "^0.1.0",
+    "templateVersion": 1
+  },
+  "frontend": {
+    "framework": "vite-react",
+    "packageManager": "npm"
+  },
+  "contracts": {
+    "path": "contracts",
+    "default": "marketplace"
+  },
+  "files": {
+    "config": "caatinga.config.ts",
+    "artifacts": "caatinga.artifacts.json"
+  }
+}

package/templates/marketplace-with-token/contracts/marketplace/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "marketplace"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+soroban-sdk = "22.0.1"
+
+[dev-dependencies]
+soroban-sdk = { version = "22.0.1", features = ["testutils"] }
+
+[profile.release]
+opt-level = "z"
+overflow-checks = true
+debug = 0
+strip = "symbols"
+debug-assertions = false
+panic = "abort"
+codegen-units = 1
+lto = true

package/templates/marketplace-with-token/contracts/marketplace/src/lib.rs

@@ -0,0 +1,13 @@
+#![no_std]
+
+use soroban_sdk::{contract, contractimpl, Env};
+
+#[contract]
+pub struct MarketplaceContract;
+
+#[contractimpl]
+impl MarketplaceContract {
+    pub fn version(_env: Env) -> u32 {
+        1
+    }
+}

package/templates/marketplace-with-token/contracts/token/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "token"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+soroban-sdk = "22.0.1"
+
+[dev-dependencies]
+soroban-sdk = { version = "22.0.1", features = ["testutils"] }
+
+[profile.release]
+opt-level = "z"
+overflow-checks = true
+debug = 0
+strip = "symbols"
+debug-assertions = false
+panic = "abort"
+codegen-units = 1
+lto = true

package/templates/marketplace-with-token/contracts/token/src/lib.rs

@@ -0,0 +1,13 @@
+#![no_std]
+
+use soroban_sdk::{contract, contractimpl, Env};
+
+#[contract]
+pub struct TokenContract;
+
+#[contractimpl]
+impl TokenContract {
+    pub fn version(_env: Env) -> u32 {
+        1
+    }
+}

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

@@ -0,0 +1,17 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "caatinga:build": "caatinga build token && caatinga build marketplace",
+    "caatinga:deploy": "caatinga deploy --network testnet"
+  },
+  "dependencies": {
+    "@caatinga/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@caatinga/cli": "^0.2.0",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/marketplace-with-token/src/main.ts

@@ -0,0 +1,10 @@
+export const templateId = "marketplace-with-token";
+
+export function describeDeployFlow(): string {
+  return [
+    "1. caatinga build token",
+    "2. caatinga build marketplace",
+    "3. caatinga deploy --network testnet --source <identity>",
+    "marketplace.deployArgs.tokenContractId resolves from caatinga.artifacts.json"
+  ].join("\n");
+}

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

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "caatinga.config.ts"]
+}

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

@@ -0,0 +1,58 @@
+# __PROJECT_NAME__
+
+Caatinga counter dApp for Stellar/Soroban.
+
+## CLI Flow
+
+```bash
+npm 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
+```
+
+Use a Stellar CLI identity alias or public account address for `--source`; do not pass seed phrases or secret keys.
+
+## Client Smoke Path
+
+After `caatinga generate`, wire generated bindings to the client:
+
+```ts
+import { createCaatingaClient } from "@caatinga/client";
+import { freighterWalletAdapter } from "@caatinga/client/freighter";
+import * as Counter from "./contracts/generated/counter";
+import artifacts from "../caatinga.artifacts.json";
+
+export const caatingaClient = createCaatingaClient({
+  network: {
+    name: "testnet",
+    rpcUrl: "https://soroban-testnet.stellar.org",
+    networkPassphrase: "Test SDF Network ; September 2015"
+  },
+  artifacts,
+  wallet: freighterWalletAdapter,
+  contracts: {
+    counter: {
+      binding: Counter
+    }
+  }
+});
+```
+
+Build XDR without wallet signing:
+
+```ts
+const tx = await caatingaClient.contract("counter").buildXdr("increment");
+console.log(tx.preparedXdr);
+```
+
+Invoke through Freighter:
+
+```ts
+const result = await caatingaClient.contract("counter").invoke("increment", {
+  debugXdr: true
+});
+console.log(result.transactionHash);
+```

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

@@ -0,0 +1,26 @@
+import { defineConfig } from "@caatinga/core";
+
+export default defineConfig({
+  project: "__PROJECT_NAME__",
+  defaultNetwork: "testnet",
+  contracts: {
+    counter: {
+      path: "./contracts/counter",
+      wasm: "./contracts/counter/target/wasm32-unknown-unknown/release/counter.wasm"
+    }
+  },
+  networks: {
+    testnet: {
+      rpcUrl: "https://soroban-testnet.stellar.org",
+      networkPassphrase: "Test SDF Network ; September 2015"
+    },
+    mainnet: {
+      rpcUrl: "https://mainnet.sorobanrpc.com",
+      networkPassphrase: "Public Global Stellar Network ; September 2015"
+    }
+  },
+  frontend: {
+    framework: "vite-react",
+    bindingsOutput: "./src/contracts/generated"
+  }
+});

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

@@ -0,0 +1,21 @@
+{
+  "name": "react-vite-counter",
+  "version": "0.1.0",
+  "description": "Minimal Vite + React + Soroban counter dApp.",
+  "caatinga": {
+    "compatibleCore": "^0.1.0",
+    "templateVersion": 1
+  },
+  "frontend": {
+    "framework": "vite-react",
+    "packageManager": "npm"
+  },
+  "contracts": {
+    "path": "contracts",
+    "default": "counter"
+  },
+  "files": {
+    "config": "caatinga.config.ts",
+    "artifacts": "caatinga.artifacts.json"
+  }
+}

package/templates/react-vite-counter/contracts/counter/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "counter"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+soroban-sdk = "22.0.1"
+
+[dev-dependencies]
+soroban-sdk = { version = "22.0.1", features = ["testutils"] }
+
+[profile.release]
+opt-level = "z"
+overflow-checks = true
+debug = 0
+strip = "symbols"
+debug-assertions = false
+panic = "abort"
+codegen-units = 1
+lto = true

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

@@ -0,0 +1,36 @@
+#![no_std]
+
+use soroban_sdk::{contract, contractimpl, Env};
+
+#[contract]
+pub struct CounterContract;
+
+#[contractimpl]
+impl CounterContract {
+    pub fn get(env: Env) -> u32 {
+        env.storage().instance().get(&"count").unwrap_or(0)
+    }
+
+    pub fn increment(env: Env) -> u32 {
+        let count = Self::get(env.clone()) + 1;
+        env.storage().instance().set(&"count", &count);
+        count
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use soroban_sdk::Env;
+
+    #[test]
+    fn increments_counter() {
+        let env = Env::default();
+        let contract_id = env.register(CounterContract, ());
+        let client = CounterContractClient::new(&env, &contract_id);
+
+        assert_eq!(client.get(), 0);
+        assert_eq!(client.increment(), 1);
+        assert_eq!(client.get(), 1);
+    }
+}

package/templates/react-vite-counter/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__PROJECT_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

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

@@ -0,0 +1,29 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "caatinga:build": "caatinga build counter",
+    "caatinga:deploy": "caatinga deploy counter",
+    "caatinga:generate": "caatinga generate counter"
+  },
+  "dependencies": {
+    "@caatinga/client": "^0.2.0",
+    "@caatinga/core": "^0.2.0",
+    "@stellar/freighter-api": "^4.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^6.0.6",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@caatinga/cli": "^0.2.0",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/react-vite-counter/public/.gitkeep

@@ -0,0 +1 @@
+

package/templates/react-vite-counter/src/App.tsx

@@ -0,0 +1,18 @@
+import { CounterCard } from "./components/CounterCard";
+import { WalletButton } from "./components/WalletButton";
+
+export default function App() {
+  return (
+    <main className="app-shell">
+      <header className="topbar">
+        <div>
+          <p className="eyebrow">Caatinga</p>
+          <h1>__PROJECT_NAME__</h1>
+        </div>
+        <WalletButton />
+      </header>
+
+      <CounterCard />
+    </main>
+  );
+}

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

@@ -0,0 +1,29 @@
+import { useMemo, useState } from "react";
+
+export function CounterCard() {
+  const [count, setCount] = useState(0);
+  const formattedCount = useMemo(() => new Intl.NumberFormat().format(count), [count]);
+
+  return (
+    <section className="counter-panel" aria-labelledby="counter-title">
+      <div className="counter-panel__header">
+        <div>
+          <p className="eyebrow">Counter Contract</p>
+          <h2 id="counter-title">Counter</h2>
+        </div>
+        <span className="network-pill">testnet</span>
+      </div>
+
+      <div className="counter-value">{formattedCount}</div>
+
+      <div className="counter-actions">
+        <button type="button" onClick={() => setCount((value) => value + 1)}>
+          Increment
+        </button>
+        <button className="secondary-button" type="button" onClick={() => setCount(0)}>
+          Reset
+        </button>
+      </div>
+    </section>
+  );
+}

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

@@ -0,0 +1,12 @@
+import { useState } from "react";
+
+export function WalletButton() {
+  const [connected, setConnected] = useState(false);
+
+  return (
+    <button className="wallet-button" type="button" onClick={() => setConnected((value) => !value)}>
+      <span className={connected ? "status-dot status-dot--on" : "status-dot"} />
+      {connected ? "Connected" : "Connect"}
+    </button>
+  );
+}

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

@@ -0,0 +1 @@
+

package/templates/react-vite-counter/src/main.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./styles.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

package/templates/react-vite-counter/src/styles.css

@@ -0,0 +1,155 @@
+:root {
+  color: #20232a;
+  background: #f4f2ec;
+  font-family:
+    Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  min-width: 320px;
+  min-height: 100vh;
+  margin: 0;
+}
+
+button {
+  min-height: 44px;
+  border: 0;
+  border-radius: 8px;
+  padding: 0 16px;
+  background: #1d6154;
+  color: #ffffff;
+  font: inherit;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+button:hover {
+  background: #174d44;
+}
+
+.app-shell {
+  width: min(960px, calc(100vw - 32px));
+  margin: 0 auto;
+  padding: 24px 0;
+}
+
+.topbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 32px;
+}
+
+.topbar h1,
+.counter-panel h2 {
+  margin: 0;
+  color: #16181d;
+  letter-spacing: 0;
+}
+
+.topbar h1 {
+  font-size: clamp(2rem, 8vw, 4rem);
+  line-height: 1;
+}
+
+.counter-panel h2 {
+  font-size: 1.35rem;
+}
+
+.eyebrow {
+  margin: 0 0 8px;
+  color: #697076;
+  font-size: 0.78rem;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.wallet-button,
+.network-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  white-space: nowrap;
+}
+
+.status-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 999px;
+  background: #a9afb4;
+}
+
+.status-dot--on {
+  background: #66c887;
+}
+
+.counter-panel {
+  border: 1px solid #d9d5ca;
+  border-radius: 8px;
+  padding: clamp(20px, 5vw, 40px);
+  background: #fffdf7;
+  box-shadow: 0 18px 60px rgba(32, 35, 42, 0.08);
+}
+
+.counter-panel__header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.network-pill {
+  min-height: 32px;
+  border: 1px solid #d9d5ca;
+  border-radius: 999px;
+  padding: 0 12px;
+  color: #45515a;
+  font-weight: 700;
+}
+
+.counter-value {
+  margin: 48px 0;
+  color: #111318;
+  font-size: clamp(5rem, 24vw, 12rem);
+  font-weight: 900;
+  line-height: 0.9;
+  letter-spacing: 0;
+}
+
+.counter-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.secondary-button {
+  border: 1px solid #d9d5ca;
+  background: #ffffff;
+  color: #20232a;
+}
+
+.secondary-button:hover {
+  background: #f4f2ec;
+}
+
+@media (max-width: 560px) {
+  .topbar,
+  .counter-panel__header {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .wallet-button,
+  .counter-actions button {
+    width: 100%;
+    justify-content: center;
+  }
+}

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

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "references": []
+}

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

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()]
+});