Skip to content

packages.md

Latest commit

 

History

History
83 lines (59 loc) · 4.87 KB

packages.md

File metadata and controls

83 lines (59 loc) · 4.87 KB
Raw

Packages

Package Role
@caatinga/cli End-user CLI (caatinga binary)
@caatinga/core Config, artifacts, Stellar CLI orchestration, verification helpers
@caatinga/client Browser/client interop over generated bindings
@caatinga/zk ZK proof serialization and Circom Groth16 workflow helpers

Install for end users:

npm install -g @caatinga/cli

Monorepo development:

pnpm install
pnpm build
pnpm dev -- init my-app

The last command runs the CLI from source via tsx in packages/cli.

Subpath exports

Each package exposes subpath exports for fine-grained imports:

Package Subpath Purpose
@caatinga/core . Config, artifacts, shell, errors (Node)
@caatinga/core ./browser Errors + artifact types only (Vite/webpack safe)
@caatinga/core ./runtime/requirements Node/Rust version constants
@caatinga/client . Client root (createCaatingaClient, wallet session, etc.)
@caatinga/client ./freighter Bundled Freighter adapter
@caatinga/client ./stellar-wallets-kit Bundled Stellar Wallets Kit adapter
@caatinga/client ./react WalletProvider + useWallet hooks (optional React peer)
@caatinga/client ./vite Vite bundler helpers for SWK stubs
@caatinga/zk . ZK proof serialization + Circom workflow
@caatinga/zk ./browser Browser-only ZK binding helpers

@caatinga/core tooling exports (Node)

For custom CI scripts and integrators:

Export Purpose
verifyExpect, parseExpectSpec, assertExpect Expect DSL used by postDeploy, smoke, and read --expect
evaluateEnvDrift Compare frontend.envFile to artifacts
evaluateWasmDrift Compare local WASM hash to artifact record
runSmokeReads Execute configured smoke reads programmatically
resolveMethodArgs Resolve ${source.address}, aliases, and placeholders in method args
summarizeReadOutput Compact read output for large payloads

Browser-safe types and errors: import from @caatinga/core/browser only.

Package Boundaries & Isolation Rules

To maintain high stability and prevent architectural regression, the following package boundaries must be strictly enforced:

1. CLI Isolation Rule

  • @caatinga/cli consumes @caatinga/core directly for orchestrating commands.
  • Rule: Under no circumstances should @caatinga/core, @caatinga/client, or @caatinga/zk import or depend on @caatinga/cli. The core logic must never reference CLI argument parsing, console output formats, or terminal-specific APIs.

2. Client Browser-Safety Rule

  • @caatinga/client connects smart contract bindings, local artifacts, and browser wallets. It is designed to be bundled safely by bundlers like Vite, Webpack, and Turbopack.
  • Rule: @caatinga/client must never import from the root of @caatinga/core (which contains Node-specific dependencies like execa or fs). It can only import browser-safe symbols from the @caatinga/core/browser subpath.
  • Rule: @caatinga/client must not contain direct filesystem access or child process orchestration.

3. Template Independence Rule

  • packages/templates contains Vite and React project scaffolds.
  • Rule: Templates are target output configurations. They must not contain compiler logic or depend on the monorepo core tools except as consumer dependencies (e.g. @caatinga/client, @caatinga/cli).

4. ZK Isolation Rule

  • @caatinga/zk encapsulates the Circom and Groth16 cryptographic operations.
  • Rule: This module operates independently and does not depend on @caatinga/cli or @caatinga/client code directly.