@caatinga/cli 0.2.0 → 0.2.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Kaleido contributors
+Copyright (c) Caatinga 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

package/README.md

@@ -1,5 +1,7 @@
 # @caatinga/cli
 
+Developer toolkit for Stellar / Soroban dApps — `init`, `build`, `deploy`, `generate`, and `invoke`.
+
 ## Install
 
 ```bash
@@ -7,62 +9,127 @@ npm install -g @caatinga/cli
 caatinga --help
 ```
 
+Inside a generated project, prefer `npx caatinga` so the project-local workflow stays explicit.
+
 ## 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`
+- [Stellar CLI](https://developers.stellar.org/docs/tools/developer-tools/cli/stellar-cli) `>=23.0.0` and `<=25.2.0` on `PATH` (22.x breaks `caatinga invoke` signing)
+- Rust 1.84.0 or newer with the `wasm32v1-none` target (contract builds)
+- A funded Stellar CLI identity for `deploy` and `invoke` (for example `alice`)
 
-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.
+```bash
+rustup target add wasm32v1-none
+stellar keys generate alice --fund --network testnet
+```
+
+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.
+
+## Quick start
+
+```bash
+caatinga init my-dapp
+cd my-dapp
+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
+```
+
+`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/`).
 
 ## 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
+| Command | What it does |
+| --- | --- |
+| `caatinga init <projectName>` | Create a project from a bundled template and write `caatinga.artifacts.json` |
+| `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 invoke <contract.method>` | Invoke a deployed contract method; extra args forward to Stellar CLI |
 
 The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
 
-## Supported Inputs
+### `init`
+
+- `-t, --template <name>` selects a bundled template (default: `react-vite-counter`)
+- Official templates: `react-vite-counter` (single counter dApp), `marketplace-with-token` (experimental multi-contract layout with `dependsOn` and deploy-arg placeholders)
+- `init` validates `caatinga.template.json` before copying files
+
+### `build`
+
+- `[contract]` defaults to `counter` when omitted
+- `--allow-untested-stellar-cli` allows a Stellar CLI newer than Caatinga's tested maximum (local only)
 
-- `--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
+### `doctor`
+
+- `-n, --network <network>` validates that the network exists in `caatinga.config.ts`
+- `-s, --source <identity>` validates that the local Stellar CLI identity exists
+- exits `0` when all diagnostics pass and non-zero when a blocking diagnostic fails
+
+### `deploy`
+
+- Omit `[contract]` to deploy the full configured dependency graph
+- `-n, --network <network>` selects a network from `caatinga.config.ts` (for example `testnet`)
+- `-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]`)
+- `--allow-untested-stellar-cli` for local experiments only
+
+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`
+
+- `-n, --network <network>` selects the network used to resolve deployed contract IDs
+- `invoke` expects `<contract.method>` (for example `counter.increment`) and forwards `[args...]` to the underlying Stellar invocation
+- Both accept `--allow-untested-stellar-cli` for local experiments only
+
+`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.
+
+## Supported inputs
+
+- `--source` accepts a local Stellar CLI identity alias that can sign transactions; public `G...` addresses and secret keys are rejected
+- `--network` must match a network defined in `caatinga.config.ts`
+- Project commands require `caatinga.config.ts` in the working directory
 
 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
+- undocumented private flags, internal repo paths, and hidden commands are not part of the package contract
+
+## Error behavior
+
+`@caatinga/cli` emits documented `CAATINGA_*` error codes for automation. Match on the error code, not human-readable text.
+
+Common codes:
+
+- `CAATINGA_CONFIG_NOT_FOUND`, `CAATINGA_INVALID_CONFIG`
+- `CAATINGA_STELLAR_CLI_NOT_FOUND`, `CAATINGA_UNSUPPORTED_CLI_VERSION`, `CAATINGA_UNTESTED_CLI_VERSION`
+- `CAATINGA_BUILD_FAILED`, `CAATINGA_DEPLOY_FAILED`, `CAATINGA_BINDINGS_FAILED`, `CAATINGA_INVOKE_FAILED`
+- `CAATINGA_CONTRACT_ID_NOT_FOUND`, `CAATINGA_SOURCE_ACCOUNT_REQUIRED`, `CAATINGA_UNSAFE_SOURCE_ACCOUNT`
+- `CAATINGA_CONTRACT_DEPENDENCY_NOT_FOUND`, `CAATINGA_CONTRACT_DEPENDENCY_CYCLE`
+- `CAATINGA_DEPLOY_ARG_PLACEHOLDER_INVALID`, `CAATINGA_DEPLOY_ARG_PLACEHOLDER_UNRESOLVED`
+- `CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND`, `CAATINGA_TEMPLATE_INCOMPATIBLE`
 
-## Error Behavior
+Full table: [docs/errors.md](https://github.com/Dione-b/caatinga/blob/main/docs/errors.md)
 
-`@caatinga/cli` emits documented `CAATINGA_*` error codes for automation. Consumers should match on the error code, not human-readable text.
+## Browser and client apps
 
-Common codes include:
+For wallet-backed invocation in the browser, use [`@caatinga/client`](https://www.npmjs.com/package/@caatinga/client) with generated bindings and `caatinga.artifacts.json`.
 
-- `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`
 
-## Relationship To `@caatinga/core`
+`@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`.
 
-`@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`.
+Prefer the CLI contract over importing `@caatinga/core` directly unless you are building advanced tooling on Caatinga internals.
 
-If you want the stable packaged workflow, prefer the CLI contract over importing `@caatinga/core` directly.
+## Versioning and stability
 
-## Versioning And Stability
+Stability applies to the documented commands, inputs, templates bundled with the published CLI, and `CAATINGA_*` error codes.
 
-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 hidden commands such as `caatinga dev` are not part of the stability promise.
 
-Undocumented internals, private module paths, and reserved hidden commands such as `caatinga dev` are not part of the stability promise.
+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

@@ -1,5 +1,34 @@
 #!/usr/bin/env node
 
+// src/utils/preflight.ts
+import chalk from "chalk";
+var NODE_MIN_MAJOR = 20;
+function checkNodeVersion() {
+  const major = parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+  if (major < NODE_MIN_MAJOR) {
+    return `Node.js ${process.versions.node} is below the required minimum v${NODE_MIN_MAJOR}.
+  Install Node.js ${NODE_MIN_MAJOR} or newer: https://nodejs.org/`;
+  }
+  return null;
+}
+function runPreflight() {
+  const failures = [];
+  const nodeFailure = checkNodeVersion();
+  if (nodeFailure) failures.push(nodeFailure);
+  if (failures.length > 0) return { ok: false, failures };
+  return { ok: true };
+}
+function assertPreflight() {
+  const result = runPreflight();
+  if (result.ok) return;
+  console.error(chalk.red.bold("\n\u2716 Caatinga preflight check failed\n"));
+  for (const failure of result.failures) {
+    console.error(chalk.red(`  \u2022 ${failure}
+`));
+  }
+  process.exit(1);
+}
+
 // src/program.ts
 import { Command } from "commander";
 
@@ -7,47 +36,54 @@ import { Command } from "commander";
 import { buildContract, loadConfig } from "@caatinga/core";
 
 // src/utils/errors.ts
+import chalk2 from "chalk";
 import { toCaatingaError } from "@caatinga/core";
+var SEPARATOR = chalk2.gray("\u2500".repeat(50));
+function printError(error) {
+  const caatingaError = toCaatingaError(error);
+  console.error("");
+  console.error(SEPARATOR);
+  console.error(chalk2.red.bold("  \u2716 Error"));
+  console.error(SEPARATOR);
+  console.error(chalk2.red(`  ${caatingaError.message}`));
+  console.error("");
+  console.error(chalk2.gray(`  Code: ${caatingaError.code}`));
+  if (caatingaError.hint) {
+    console.error("");
+    console.error(chalk2.yellow(`  Hint: ${caatingaError.hint}`));
+  }
+  console.error(SEPARATOR);
+  console.error("");
+}
+async function runCliAction(action) {
+  try {
+    await action();
+  } catch (error) {
+    printError(error);
+    process.exitCode = 1;
+  }
+}
 
 // src/utils/logger.ts
-import chalk from "chalk";
+import chalk3 from "chalk";
 var logger = {
   info(message) {
     console.log(message);
   },
   success(message) {
-    console.log(chalk.green(message));
+    console.log(chalk3.green(message));
   },
   warn(message) {
-    console.warn(chalk.yellow(message));
+    console.warn(chalk3.yellow(message));
   },
   error(message) {
-    console.error(chalk.red(message));
+    console.error(chalk3.red(message));
   },
   muted(message) {
-    console.log(chalk.gray(message));
+    console.log(chalk3.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 () => {
@@ -67,7 +103,7 @@ function registerBuildCommand(program2) {
 // 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 () => {
+  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("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").option("--verify-deps", "Verify dependency contract IDs exist on-chain before deploy").action((contractName, options) => runCliAction(async () => {
     if (options.deps === false && !contractName) {
       throw new CaatingaError(
         "`--no-deps` requires a contract name.",
@@ -83,14 +119,23 @@ function registerDeployCommand(program2) {
       source: options.source,
       includeDependencies: options.deps !== false,
       force: options.force === true,
+      checkStaleWasm: options.staleCheck !== false,
+      verifyDeps: options.verifyDeps === true,
       allowUntestedStellarCli: options.allowUntestedStellarCli === true
     });
+    for (const warning of result.staleWasmWarnings) {
+      logger.warn(warning.message);
+    }
     logger.success("Deploy complete");
     logger.info("");
     logger.info(`Network: ${result.network.name}`);
+    for (const skipped of result.skippedContracts) {
+      logger.info(`[skipped] ${skipped.name} \u2014 already deployed on ${result.network.name}`);
+      logger.info(`  Contract ID: ${skipped.contractId}`);
+    }
     for (const contract of result.deployedContracts) {
-      logger.info(`Contract: ${contract.name}`);
-      logger.info(`Contract ID: ${contract.contractId}`);
+      logger.info(`[deployed] ${contract.name}`);
+      logger.info(`  Contract ID: ${contract.contractId}`);
     }
     logger.info("Artifacts updated: caatinga.artifacts.json");
   }));
@@ -108,11 +153,248 @@ function registerDevCommand(program2) {
   dev.configureHelp({ visibleOptions: () => [] });
 }
 
+// src/commands/doctor.command.ts
+import { access } from "fs/promises";
+import {
+  assertSupportedStellarCliVersion,
+  CaatingaError as CaatingaError2,
+  CaatingaErrorCode as CaatingaErrorCode2,
+  loadConfig as loadConfig4,
+  parseStellarCliVersion,
+  readArtifacts as readArtifacts2,
+  resolveNetwork as resolveNetwork2,
+  runCommand,
+  validateSourceShape
+} from "@caatinga/core";
+
+// src/commands/doctor-deploy-coverage.ts
+import { loadConfig as loadConfig3, readArtifacts, resolveNetwork } from "@caatinga/core";
+async function evaluateDeployCoverage(options) {
+  const cwd = options.cwd;
+  const config = await loadConfig3({ cwd });
+  const network = resolveNetwork(config, options.networkName);
+  const artifacts = await readArtifacts(cwd);
+  const lines = [];
+  for (const name of Object.keys(config.contracts)) {
+    const contractId = artifacts.networks[network.name]?.contracts[name]?.contractId;
+    if (contractId) {
+      lines.push({ name, ok: true, contractId });
+    } else {
+      lines.push({
+        name,
+        ok: false,
+        fix: `Run: caatinga deploy ${name} --network ${network.name}`
+      });
+    }
+  }
+  return { lines, complete: lines.every((line) => line.ok) };
+}
+
+// src/commands/doctor.command.ts
+var NODE_MIN_MAJOR2 = 20;
+var WASM_TARGET = "wasm32v1-none";
+function nodeDiagnostic() {
+  const version = process.versions.node;
+  const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
+  if (major < NODE_MIN_MAJOR2) {
+    return {
+      ok: false,
+      label: `Node.js ${version} is below the required minimum ${NODE_MIN_MAJOR2}.0.0`,
+      fix: `Install Node.js ${NODE_MIN_MAJOR2} or newer.`
+    };
+  }
+  return { ok: true, label: `Node.js ${version}` };
+}
+async function stellarDiagnostic(allowUntested) {
+  try {
+    const result = await runCommand("stellar", ["--version"], {
+      skipStellarVersionCheck: true
+    });
+    const version = assertSupportedStellarCliVersion({
+      version: parseStellarCliVersion(result.all || result.stdout || result.stderr),
+      allowUntested
+    });
+    return { ok: true, label: `Stellar CLI ${version}` };
+  } catch (error) {
+    const hint = error instanceof CaatingaError2 ? error.hint : void 0;
+    return {
+      ok: false,
+      label: "Stellar CLI not ready",
+      fix: hint ?? "Install Stellar CLI: cargo install --locked stellar-cli --version 25.2.0"
+    };
+  }
+}
+async function rustDiagnostic() {
+  try {
+    const result = await runCommand("rustc", ["--version"]);
+    return { ok: true, label: result.stdout || result.all || "Rust installed" };
+  } catch {
+    return {
+      ok: false,
+      label: "Rust not found",
+      fix: "Install Rust, then run: rustup target add wasm32v1-none"
+    };
+  }
+}
+async function wasmTargetDiagnostic() {
+  try {
+    const result = await runCommand("rustup", ["target", "list", "--installed"]);
+    const installedTargets = result.stdout || result.all;
+    if (installedTargets.split(/\r?\n/).includes(WASM_TARGET)) {
+      return { ok: true, label: `${WASM_TARGET} target installed` };
+    }
+    return {
+      ok: false,
+      label: `${WASM_TARGET} target not installed`,
+      fix: `Run: rustup target add ${WASM_TARGET}`
+    };
+  } catch {
+    return {
+      ok: false,
+      label: "rustup not found",
+      fix: "Install rustup, then run: rustup target add wasm32v1-none"
+    };
+  }
+}
+async function configDiagnostic() {
+  try {
+    await loadConfig4();
+    return { ok: true, label: "caatinga.config.ts found" };
+  } catch (error) {
+    const hint = error instanceof CaatingaError2 ? error.hint : void 0;
+    return {
+      ok: false,
+      label: "caatinga.config.ts not ready",
+      fix: hint ?? "Run this command from a Caatinga project root."
+    };
+  }
+}
+async function artifactsDiagnostic() {
+  try {
+    await access("caatinga.artifacts.json");
+    await readArtifacts2();
+    return { ok: true, label: "caatinga.artifacts.json found" };
+  } catch {
+    return {
+      ok: false,
+      label: "caatinga.artifacts.json not found or invalid",
+      fix: "Run caatinga init, or restore a valid caatinga.artifacts.json file."
+    };
+  }
+}
+async function networkDiagnostic(networkName) {
+  if (!networkName) return void 0;
+  try {
+    const config = await loadConfig4();
+    const network = resolveNetwork2(config, networkName);
+    return { ok: true, label: `network ${network.name} found` };
+  } catch (error) {
+    const hint = error instanceof CaatingaError2 ? error.hint : void 0;
+    return {
+      ok: false,
+      label: `network ${networkName} not found`,
+      fix: hint ?? `Add "${networkName}" to caatinga.config.ts networks.`
+    };
+  }
+}
+async function sourceDiagnostic(source) {
+  if (!source) return void 0;
+  const unsafeSource = validateSourceShape(source);
+  if (unsafeSource) {
+    return {
+      ok: false,
+      label: `source identity ${source} rejected (${unsafeSource.code})`,
+      fix: unsafeSource.hint
+    };
+  }
+  try {
+    await runCommand("stellar", ["keys", "public-key", source]);
+    return { ok: true, label: `source identity ${source} found` };
+  } catch {
+    return {
+      ok: false,
+      label: `source identity ${source} not found`,
+      fix: `Create and fund it: stellar keys generate ${source} --fund --network testnet`
+    };
+  }
+}
+function printDiagnostic(diagnostic) {
+  logger.info(`${diagnostic.ok ? "\u2713" : "\u2717"} ${diagnostic.label}`);
+}
+function printFixes(diagnostics) {
+  const failures = diagnostics.filter((diagnostic) => !diagnostic.ok);
+  if (failures.length === 0) return;
+  logger.info("");
+  logger.info("Fix:");
+  for (const failure of failures) {
+    if (failure.fix) logger.info(failure.fix);
+  }
+}
+function printDeployCoverageLine(line) {
+  if (line.ok) {
+    logger.info(`\u2713 ${line.name} \u2014 ${line.contractId}`);
+    return;
+  }
+  logger.info(`\u2717 ${line.name}`);
+  if (line.fix) logger.info(`  ${line.fix}`);
+}
+async function reportDeployCoverage(networkName) {
+  const coverage = await evaluateDeployCoverage({ networkName });
+  logger.info("");
+  logger.info(`Deploy coverage (${networkName}):`);
+  for (const line of coverage.lines) {
+    printDeployCoverageLine(line);
+  }
+  if (!coverage.complete) {
+    const missing = coverage.lines.filter((line) => !line.ok).map((line) => line.name);
+    throw new CaatingaError2(
+      `Not all configured contracts are deployed on ${networkName}.`,
+      CaatingaErrorCode2.DOCTOR_PARTIAL_DEPLOY,
+      `Deploy missing contracts: ${missing.join(", ")}. See the commands above.`
+    );
+  }
+  return true;
+}
+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").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Caatinga's tested maximum").action((options) => runCliAction(async () => {
+    logger.info("Caatinga Doctor");
+    logger.info("");
+    const diagnostics = [
+      nodeDiagnostic(),
+      await stellarDiagnostic(options.allowUntestedStellarCli === true),
+      await rustDiagnostic(),
+      await wasmTargetDiagnostic(),
+      await configDiagnostic(),
+      await artifactsDiagnostic(),
+      await networkDiagnostic(options.network),
+      await sourceDiagnostic(options.source)
+    ].filter((diagnostic) => diagnostic !== void 0);
+    for (const diagnostic of diagnostics) {
+      printDiagnostic(diagnostic);
+    }
+    printFixes(diagnostics);
+    let ready = diagnostics.every((diagnostic) => diagnostic.ok);
+    if (options.network && ready) {
+      try {
+        await reportDeployCoverage(options.network);
+      } catch (error) {
+        ready = false;
+        throw error;
+      }
+    }
+    logger.info("");
+    logger.info(`Status: ${ready ? "ready" : "blocked"}`);
+    if (!ready) {
+      process.exitCode = 1;
+    }
+  }));
+}
+
 // src/commands/generate.command.ts
-import { generateBindings, loadConfig as loadConfig3 } from "@caatinga/core";
+import { generateBindings, 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").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 config = await loadConfig5();
     const result = await generateBindings({
       config,
       contractName,
@@ -132,10 +414,10 @@ import path2 from "path";
 import { createProjectFromTemplate } from "@caatinga/core";
 
 // src/utils/template-path.ts
-import { access } from "fs/promises";
+import { access as access2 } from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
-import { CaatingaError as CaatingaError2, CaatingaErrorCode as CaatingaErrorCode2 } from "@caatinga/core";
+import { CaatingaError as CaatingaError3, CaatingaErrorCode as CaatingaErrorCode3 } from "@caatinga/core";
 async function resolveTemplateDir(templateName) {
   const envTemplatesDir = process.env.CAATINGA_TEMPLATES_DIR;
   const candidates = [
@@ -145,14 +427,14 @@ async function resolveTemplateDir(templateName) {
   ].filter((candidate) => Boolean(candidate));
   for (const candidate of candidates) {
     try {
-      await access(candidate);
+      await access2(candidate);
       return candidate;
     } catch {
     }
   }
-  throw new CaatingaError2(
+  throw new CaatingaError3(
     `Template "${templateName}" was not found.`,
-    CaatingaErrorCode2.TEMPLATE_NOT_FOUND,
+    CaatingaErrorCode3.TEMPLATE_NOT_FOUND,
     "Set CAATINGA_TEMPLATES_DIR or run from a Caatinga checkout that includes packages/templates."
   );
 }
@@ -191,15 +473,18 @@ function registerInitCommand(program2) {
     logger.info("Next steps:");
     logger.info(`  cd ${projectDirectory}`);
     logger.info("  npm install");
-    logger.info("  npx caatinga build counter");
+    const defaultContract = result.template.contracts.default;
+    logger.info(
+      defaultContract ? `  npx caatinga build ${defaultContract}` : "  npx caatinga build"
+    );
   }));
 }
 
 // src/commands/invoke.command.ts
-import { invokeContract, loadConfig as loadConfig4 } from "@caatinga/core";
+import { invokeContract, loadConfig as loadConfig6 } 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();
+  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 () => {
+    const config = await loadConfig6();
     const result = await invokeContract({
       config,
       target,
@@ -221,7 +506,7 @@ function registerInvokeCommand(program2) {
 }
 
 // src/version.ts
-var CAATINGA_CLI_VERSION = "0.2.0";
+var CAATINGA_CLI_VERSION = "0.2.2";
 
 // src/program.ts
 function createProgram() {
@@ -229,6 +514,7 @@ function createProgram() {
   program2.name("caatinga").description("Developer toolkit for Stellar/Soroban dApps").version(CAATINGA_CLI_VERSION);
   registerInitCommand(program2);
   registerDevCommand(program2);
+  registerDoctorCommand(program2);
   registerBuildCommand(program2);
   registerDeployCommand(program2);
   registerGenerateCommand(program2);
@@ -237,6 +523,7 @@ function createProgram() {
 }
 
 // src/index.ts
+assertPreflight();
 var program = createProgram();
 void program.parseAsync(process.argv).catch((error) => {
   console.error(error);

package/package.json

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