@caatinga/cli 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.md +94 -34
- package/dist/index.js +3 -3
- package/package.json +3 -3
- package/templates/marketplace-with-token/caatinga.template.json +1 -1
- package/templates/marketplace-with-token/package.json +2 -2
- package/templates/react-vite-counter/caatinga.template.json +1 -1
- package/templates/react-vite-counter/package.json +3 -3
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# @caatinga/cli
|
|
2
2
|
|
|
3
|
+
Developer toolkit for Stellar / Soroban dApps — `init`, `build`, `deploy`, `generate`, and `invoke`.
|
|
4
|
+
|
|
3
5
|
## Install
|
|
4
6
|
|
|
5
7
|
```bash
|
|
@@ -7,62 +9,120 @@ npm install -g @caatinga/cli
|
|
|
7
9
|
caatinga --help
|
|
8
10
|
```
|
|
9
11
|
|
|
12
|
+
Inside a generated project, prefer `npx caatinga` so the project-local workflow stays explicit.
|
|
13
|
+
|
|
10
14
|
## Requirements
|
|
11
15
|
|
|
12
16
|
- Node.js `>=20`
|
|
13
|
-
- Stellar CLI `>=22.0.0` and `<=25.2.0`
|
|
14
|
-
-
|
|
17
|
+
- [Stellar CLI](https://developers.stellar.org/docs/tools/developer-tools/cli/stellar-cli) `>=22.0.0` and `<=25.2.0` on `PATH`
|
|
18
|
+
- Rust stable and the `wasm32-unknown-unknown` target (contract builds)
|
|
19
|
+
- A funded Stellar CLI identity for `deploy` and `invoke` (for example `alice`)
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
rustup target add wasm32-unknown-unknown
|
|
23
|
+
stellar keys generate alice --fund --network testnet
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
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.
|
|
15
27
|
|
|
16
|
-
|
|
28
|
+
## Quick start
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
caatinga init my-dapp
|
|
32
|
+
cd my-dapp
|
|
33
|
+
npm install
|
|
34
|
+
|
|
35
|
+
npx caatinga build counter
|
|
36
|
+
npx caatinga deploy counter --network testnet --source alice
|
|
37
|
+
npx caatinga generate counter --network testnet
|
|
38
|
+
npx caatinga invoke counter.increment --network testnet --source alice
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`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/`).
|
|
17
42
|
|
|
18
43
|
## Commands
|
|
19
44
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
45
|
+
| Command | What it does |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| `caatinga init <projectName>` | Create a project from a bundled template and write `caatinga.artifacts.json` |
|
|
48
|
+
| `caatinga build [contract]` | Compile contract WASM through Stellar CLI (default contract: `counter`) |
|
|
49
|
+
| `caatinga deploy [contract]` | Deploy one contract or the full configured graph; record IDs in artifacts |
|
|
50
|
+
| `caatinga generate <contract>` | Generate TypeScript bindings from a deployed contract ID |
|
|
51
|
+
| `caatinga invoke <contract.method>` | Invoke a deployed contract method; extra args forward to Stellar CLI |
|
|
25
52
|
|
|
26
53
|
The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
|
|
27
54
|
|
|
28
|
-
|
|
55
|
+
### `init`
|
|
56
|
+
|
|
57
|
+
- `-t, --template <name>` selects a bundled template (default: `react-vite-counter`)
|
|
58
|
+
- Official templates: `react-vite-counter` (single counter dApp), `marketplace-with-token` (experimental multi-contract layout with `dependsOn` and deploy-arg placeholders)
|
|
59
|
+
- `init` validates `caatinga.template.json` before copying files
|
|
60
|
+
|
|
61
|
+
### `build`
|
|
29
62
|
|
|
30
|
-
-
|
|
31
|
-
- `--
|
|
32
|
-
|
|
33
|
-
|
|
63
|
+
- `[contract]` defaults to `counter` when omitted
|
|
64
|
+
- `--allow-untested-stellar-cli` allows a Stellar CLI newer than Caatinga's tested maximum (local only)
|
|
65
|
+
|
|
66
|
+
### `deploy`
|
|
67
|
+
|
|
68
|
+
- Omit `[contract]` to deploy the full configured dependency graph
|
|
69
|
+
- `-n, --network <network>` selects a network from `caatinga.config.ts` (for example `testnet`)
|
|
70
|
+
- `-s, --source <identity>` is required; must be a Stellar CLI identity alias that can sign (for example `alice`)
|
|
71
|
+
- `--force` redeploys even when artifacts already store a contract ID
|
|
72
|
+
- `--no-deps` skips dependency deployment for a single named contract (`--no-deps` requires `[contract]`)
|
|
73
|
+
- `--allow-untested-stellar-cli` for local experiments only
|
|
74
|
+
|
|
75
|
+
Dependencies listed in `dependsOn` deploy first unless `--no-deps` is set. Deploy args may reference `${contracts.<name>.contractId}` placeholders resolved from artifacts.
|
|
76
|
+
|
|
77
|
+
### `generate` and `invoke`
|
|
78
|
+
|
|
79
|
+
- `-n, --network <network>` selects the network used to resolve deployed contract IDs
|
|
80
|
+
- `invoke` expects `<contract.method>` (for example `counter.increment`) and forwards `[args...]` to the underlying Stellar invocation
|
|
81
|
+
- Both accept `--allow-untested-stellar-cli` for local experiments only
|
|
82
|
+
|
|
83
|
+
`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.
|
|
84
|
+
|
|
85
|
+
## Supported inputs
|
|
86
|
+
|
|
87
|
+
- `--source` accepts a Stellar CLI identity alias that can sign transactions; public `G...` addresses and secret keys are rejected
|
|
88
|
+
- `--network` must match a network defined in `caatinga.config.ts`
|
|
89
|
+
- Project commands require `caatinga.config.ts` in the working directory
|
|
34
90
|
|
|
35
91
|
Unsupported input posture:
|
|
36
92
|
|
|
37
93
|
- secret keys and seed phrases are not supported CLI inputs
|
|
38
|
-
- undocumented private flags
|
|
94
|
+
- undocumented private flags, internal repo paths, and hidden commands are not part of the package contract
|
|
95
|
+
|
|
96
|
+
## Error behavior
|
|
97
|
+
|
|
98
|
+
`@caatinga/cli` emits documented `CAATINGA_*` error codes for automation. Match on the error code, not human-readable text.
|
|
99
|
+
|
|
100
|
+
Common codes:
|
|
101
|
+
|
|
102
|
+
- `CAATINGA_CONFIG_NOT_FOUND`, `CAATINGA_INVALID_CONFIG`
|
|
103
|
+
- `CAATINGA_STELLAR_CLI_NOT_FOUND`, `CAATINGA_UNSUPPORTED_CLI_VERSION`, `CAATINGA_UNTESTED_CLI_VERSION`
|
|
104
|
+
- `CAATINGA_BUILD_FAILED`, `CAATINGA_DEPLOY_FAILED`, `CAATINGA_BINDINGS_FAILED`, `CAATINGA_INVOKE_FAILED`
|
|
105
|
+
- `CAATINGA_CONTRACT_ID_NOT_FOUND`, `CAATINGA_SOURCE_ACCOUNT_REQUIRED`, `CAATINGA_UNSAFE_SOURCE_ACCOUNT`
|
|
106
|
+
- `CAATINGA_CONTRACT_DEPENDENCY_NOT_FOUND`, `CAATINGA_CONTRACT_DEPENDENCY_CYCLE`
|
|
107
|
+
- `CAATINGA_DEPLOY_ARG_PLACEHOLDER_INVALID`, `CAATINGA_DEPLOY_ARG_PLACEHOLDER_UNRESOLVED`
|
|
108
|
+
- `CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND`, `CAATINGA_TEMPLATE_INCOMPATIBLE`
|
|
39
109
|
|
|
40
|
-
|
|
110
|
+
Full table: [docs/errors.md](https://github.com/Dione-b/caatinga/blob/main/docs/errors.md)
|
|
41
111
|
|
|
42
|
-
|
|
112
|
+
## Browser and client apps
|
|
43
113
|
|
|
44
|
-
|
|
114
|
+
For wallet-backed invocation in the browser, use [`@caatinga/client`](https://www.npmjs.com/package/@caatinga/client) with generated bindings and `caatinga.artifacts.json`.
|
|
45
115
|
|
|
46
|
-
|
|
47
|
-
- `CAATINGA_INVALID_CONFIG`
|
|
48
|
-
- `CAATINGA_STELLAR_CLI_NOT_FOUND`
|
|
49
|
-
- `CAATINGA_BUILD_FAILED`
|
|
50
|
-
- `CAATINGA_DEPLOY_FAILED`
|
|
51
|
-
- `CAATINGA_BINDINGS_FAILED`
|
|
52
|
-
- `CAATINGA_INVOKE_FAILED`
|
|
53
|
-
- `CAATINGA_CONTRACT_ID_NOT_FOUND`
|
|
54
|
-
- `CAATINGA_SOURCE_ACCOUNT_REQUIRED`
|
|
55
|
-
- `CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND`
|
|
56
|
-
- `CAATINGA_TEMPLATE_INCOMPATIBLE`
|
|
116
|
+
## Relationship to `@caatinga/core`
|
|
57
117
|
|
|
58
|
-
|
|
118
|
+
`@caatinga/cli` is the supported end-user entrypoint. It stays thin and delegates config loading, artifacts, command orchestration, Stellar CLI version checks, and shared errors to `@caatinga/core`.
|
|
59
119
|
|
|
60
|
-
|
|
120
|
+
Prefer the CLI contract over importing `@caatinga/core` directly unless you are building advanced tooling on Caatinga internals.
|
|
61
121
|
|
|
62
|
-
|
|
122
|
+
## Versioning and stability
|
|
63
123
|
|
|
64
|
-
|
|
124
|
+
Stability applies to the documented commands, inputs, templates bundled with the published CLI, and `CAATINGA_*` error codes.
|
|
65
125
|
|
|
66
|
-
|
|
126
|
+
Undocumented internals, private module paths, and hidden commands such as `caatinga dev` are not part of the stability promise.
|
|
67
127
|
|
|
68
|
-
|
|
128
|
+
Further reference: [CLI docs](https://github.com/Dione-b/caatinga/blob/main/docs/cli.md), [config](https://github.com/Dione-b/caatinga/blob/main/docs/config.md), [Stellar CLI version contract](https://github.com/Dione-b/caatinga/blob/main/docs/stellar-cli-version-contract.md).
|
package/dist/index.js
CHANGED
|
@@ -67,7 +67,7 @@ function registerBuildCommand(program2) {
|
|
|
67
67
|
// src/commands/deploy.command.ts
|
|
68
68
|
import { deployContractGraph, CaatingaError, CaatingaErrorCode, loadConfig as loadConfig2 } from "@caatinga/core";
|
|
69
69
|
function registerDeployCommand(program2) {
|
|
70
|
-
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
|
|
70
|
+
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("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").action((contractName, options) => runCliAction(async () => {
|
|
71
71
|
if (options.deps === false && !contractName) {
|
|
72
72
|
throw new CaatingaError(
|
|
73
73
|
"`--no-deps` requires a contract name.",
|
|
@@ -198,7 +198,7 @@ function registerInitCommand(program2) {
|
|
|
198
198
|
// src/commands/invoke.command.ts
|
|
199
199
|
import { invokeContract, loadConfig as loadConfig4 } from "@caatinga/core";
|
|
200
200
|
function registerInvokeCommand(program2) {
|
|
201
|
-
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
|
|
201
|
+
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 () => {
|
|
202
202
|
const config = await loadConfig4();
|
|
203
203
|
const result = await invokeContract({
|
|
204
204
|
config,
|
|
@@ -221,7 +221,7 @@ function registerInvokeCommand(program2) {
|
|
|
221
221
|
}
|
|
222
222
|
|
|
223
223
|
// src/version.ts
|
|
224
|
-
var CAATINGA_CLI_VERSION = "0.2.
|
|
224
|
+
var CAATINGA_CLI_VERSION = "0.2.1";
|
|
225
225
|
|
|
226
226
|
// src/program.ts
|
|
227
227
|
function createProgram() {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@caatinga/cli",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Caatinga CLI for building dApps on Stellar/Soroban",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"stellar",
|
|
@@ -43,9 +43,9 @@
|
|
|
43
43
|
"LICENSE"
|
|
44
44
|
],
|
|
45
45
|
"dependencies": {
|
|
46
|
-
"@caatinga/core": "^0.2.0",
|
|
47
46
|
"chalk": "^5.4.1",
|
|
48
|
-
"commander": "^12.1.0"
|
|
47
|
+
"commander": "^12.1.0",
|
|
48
|
+
"@caatinga/core": "^0.2.1"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
51
|
"tsup": "^8.3.5",
|
|
@@ -8,10 +8,10 @@
|
|
|
8
8
|
"caatinga:deploy": "caatinga deploy --network testnet"
|
|
9
9
|
},
|
|
10
10
|
"dependencies": {
|
|
11
|
-
"@caatinga/core": "^0.2.
|
|
11
|
+
"@caatinga/core": "^0.2.1"
|
|
12
12
|
},
|
|
13
13
|
"devDependencies": {
|
|
14
|
-
"@caatinga/cli": "^0.2.
|
|
14
|
+
"@caatinga/cli": "^0.2.1",
|
|
15
15
|
"typescript": "^5.7.2"
|
|
16
16
|
}
|
|
17
17
|
}
|
|
@@ -12,8 +12,8 @@
|
|
|
12
12
|
"caatinga:generate": "caatinga generate counter"
|
|
13
13
|
},
|
|
14
14
|
"dependencies": {
|
|
15
|
-
"@caatinga/client": "^0.2.
|
|
16
|
-
"@caatinga/core": "^0.2.
|
|
15
|
+
"@caatinga/client": "^0.2.1",
|
|
16
|
+
"@caatinga/core": "^0.2.1",
|
|
17
17
|
"@stellar/freighter-api": "^4.0.0",
|
|
18
18
|
"@vitejs/plugin-react": "^4.3.4",
|
|
19
19
|
"vite": "^6.0.6",
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
"react-dom": "^18.3.1"
|
|
22
22
|
},
|
|
23
23
|
"devDependencies": {
|
|
24
|
-
"@caatinga/cli": "^0.2.
|
|
24
|
+
"@caatinga/cli": "^0.2.1",
|
|
25
25
|
"@types/react": "^18.3.18",
|
|
26
26
|
"@types/react-dom": "^18.3.5",
|
|
27
27
|
"typescript": "^5.7.2"
|