@caatinga/core 0.2.0 → 0.2.1

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,33 +1,107 @@
 # @caatinga/core
 
-Core config, artifacts, command orchestration, and error primitives for Caatinga.
+Core config, artifacts, command orchestration, and error primitives for the Caatinga / Stellar Soroban toolkit.
 
-## Supported Use
+## Supported use
 
-`@caatinga/core` is primarily an internal package for the Caatinga CLI and templates; direct use beyond the documented config/template helpers is advanced and less stable than the CLI contract.
+`@caatinga/core` is primarily an internal package for `@caatinga/cli` and official templates. Direct use beyond the documented config and template surface is advanced and less stable than the CLI contract.
 
-## What Is In This Package
+Most applications should install `@caatinga/cli` or `@caatinga/client` instead of depending on core directly.
 
-- `defineConfig` for Caatinga project config files generated by Caatinga templates
-- config loading and validation
-- artifact resolution and update helpers
-- shared command orchestration primitives
-- public `CAATINGA_*` error foundations used by higher-level packages
+## What is in this package
 
-## Consumer Guidance
+### Config and networks
 
-If you want the supported end-user workflow, use `@caatinga/cli`.
+- `defineConfig` for `caatinga.config.ts` in generated projects
+- `loadConfig`, `CaatingaConfigSchema`, and related types
+- `WELL_KNOWN_NETWORKS`, `resolveNetwork`
 
-If you are authoring a Caatinga project, importing `defineConfig` from `@caatinga/core` in `caatinga.config.ts` is part of the intended template/config surface.
+### Artifacts
 
-Reach for broader `@caatinga/core` APIs directly only when you are building advanced tooling on top of Caatinga internals and are prepared to track lower-level package changes more closely than a CLI consumer.
+- `readArtifacts`, `writeArtifacts`, `createInitialArtifacts`, `updateArtifact`
+- `CaatingaArtifactsSchema` and artifact types (`caatinga.artifacts.json`, schema version `1`)
 
-## Stability Posture
+### Contracts and Stellar CLI orchestration
 
-Being published does not make every export a first-class end-user contract. The stable consumer surfaces are:
+- `buildContract`, `deployContract`, `deployContractGraph`
+- `buildDependencyGraph`, `resolveDeployOrder`, `resolveDeployArgs`
+- `generateBindings`, `invokeContract`, `parseInvokeTarget`
+- `resolveContract`, `parseContractId`
+- Stellar CLI version constants and guards (`STELLAR_CLI_MIN_VERSION`, `STELLAR_CLI_TESTED_MAX_VERSION`, `assertSupportedStellarCliVersion`)
+
+### Templates
+
+- `createProjectFromTemplate` and `TemplateManifestSchema`
+- compatibility checks against `CAATINGA_CORE_VERSION` and template manifests
+
+### Shell and errors
+
+- `runCommand`, `checkBinary`
+- `CaatingaError`, `CaatingaErrorCode`, `toCaatingaError`
+- `CAATINGA_CORE_VERSION`
+
+## Intended config surface
+
+Generated projects import `defineConfig` from `@caatinga/core`:
+
+```ts
+import { defineConfig } from "@caatinga/core";
+
+export default defineConfig({
+  project: "my-dapp",
+  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"
+    }
+  },
+  frontend: {
+    framework: "vite-react",
+    bindingsOutput: "./contracts/generated"
+  }
+});
+```
+
+Multi-contract projects may declare `dependsOn` and `${contracts.<name>.contractId}` placeholders in `deployArgs`; `deployContractGraph` resolves and deploys dependencies before dependents.
+
+## Consumer guidance
+
+| Goal | Package |
+| --- | --- |
+| End-user CLI workflow | `@caatinga/cli` |
+| Browser / Node client over generated bindings | `@caatinga/client` |
+| `caatinga.config.ts` in a Caatinga project | `defineConfig` from `@caatinga/core` |
+| Custom tooling on deploy graphs, artifacts, or Stellar CLI orchestration | `@caatinga/core` (advanced; track releases closely) |
+
+## Error codes
+
+Core owns the canonical `CAATINGA_*` enum used by CLI, client, and templates. Automation should match on codes, not message text.
+
+Common codes surfaced through core-backed commands:
+
+- config and artifacts: `CAATINGA_CONFIG_NOT_FOUND`, `CAATINGA_INVALID_CONFIG`, `CAATINGA_ARTIFACT_NOT_FOUND`, `CAATINGA_ARTIFACT_INVALID`
+- Stellar CLI: `CAATINGA_STELLAR_CLI_NOT_FOUND`, `CAATINGA_UNSUPPORTED_CLI_VERSION`, `CAATINGA_UNTESTED_CLI_VERSION`
+- contracts: `CAATINGA_BUILD_FAILED`, `CAATINGA_DEPLOY_FAILED`, `CAATINGA_BINDINGS_FAILED`, `CAATINGA_INVOKE_FAILED`
+- dependencies: `CAATINGA_CONTRACT_DEPENDENCY_NOT_FOUND`, `CAATINGA_CONTRACT_DEPENDENCY_CYCLE`, `CAATINGA_DEPLOY_ARG_PLACEHOLDER_UNRESOLVED`
+- templates: `CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND`, `CAATINGA_TEMPLATE_INCOMPATIBLE`
+
+Full table: [docs/errors.md](https://github.com/Dione-b/caatinga/blob/main/docs/errors.md)
+
+## Stability posture
+
+Being published does not make every export a first-class end-user contract. Stable consumer surfaces are:
 
 - the documented CLI workflow in `@caatinga/cli`
 - the documented `@caatinga/client` APIs
 - the narrow `@caatinga/core` config/template surface used by generated projects, including `defineConfig`
 
 Direct `@caatinga/core` usage should be treated as advanced integration with a narrower support posture than the CLI package.
+
+Further reference: [architecture](https://github.com/Dione-b/caatinga/blob/main/docs/architecture.md), [config](https://github.com/Dione-b/caatinga/blob/main/docs/config.md), [templates](https://github.com/Dione-b/caatinga/blob/main/docs/templates.md).

package/dist/index.cjs

@@ -135,7 +135,7 @@ function toCaatingaError(error) {
 }
 
 // src/version.ts
-var CAATINGA_CORE_VERSION = "0.2.0";
+var CAATINGA_CORE_VERSION = "0.2.1";
 
 // src/config/config.schema.ts
 var import_zod = require("zod");
@@ -553,6 +553,85 @@ async function buildContract(options) {
 // src/contracts/deploy-contract.ts
 var import_node_path5 = __toESM(require("path"), 1);
 
+// src/stellar-cli/recover-deploy-contract-id.ts
+var TX_HASH_REGEX = /Transaction hash is ([a-f0-9]{64})/i;
+var DEPLOY_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
+var HORIZON_URL_BY_PASSPHRASE = {
+  "Test SDF Network ; September 2015": "https://horizon-testnet.stellar.org",
+  "Public Global Stellar Network ; September 2015": "https://horizon.stellar.org"
+};
+function isLikelyPublicKeySource(source) {
+  return /^G[A-Z2-7]{55}$/.test(source);
+}
+function decimalSaltToHex(salt) {
+  return BigInt(salt).toString(16).padStart(64, "0");
+}
+function resolveHorizonUrl(network) {
+  const horizonUrl = HORIZON_URL_BY_PASSPHRASE[network.networkPassphrase];
+  if (!horizonUrl) {
+    throw new CaatingaError(
+      `No Horizon URL mapping for network passphrase "${network.networkPassphrase}".`,
+      CaatingaErrorCode.NETWORK_NOT_FOUND,
+      "Use testnet or mainnet, or extend Caatinga network metadata."
+    );
+  }
+  return horizonUrl;
+}
+async function fetchCreateContractSalt(horizonUrl, transactionHash, fetchImpl = fetch) {
+  const response = await fetchImpl(`${horizonUrl}/transactions/${transactionHash}/operations`);
+  if (!response.ok) {
+    return null;
+  }
+  const body = await response.json();
+  const operation = body._embedded?.records?.find(
+    (record) => record.transaction_successful === true && record.type === "invoke_host_function" && record.function === "HostFunctionTypeHostFunctionTypeCreateContract" && typeof record.salt === "string"
+  );
+  return operation?.salt ?? null;
+}
+async function resolveContractIdFromDeploySalt(options) {
+  const saltHex = decimalSaltToHex(options.salt);
+  const result = await runCommand("stellar", [
+    "contract",
+    "id",
+    "wasm",
+    "--salt",
+    saltHex,
+    "--source-account",
+    options.source,
+    "--rpc-url",
+    options.network.rpcUrl,
+    "--network-passphrase",
+    options.network.networkPassphrase
+  ], {
+    cwd: options.cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli,
+    skipStellarVersionCheck: true
+  });
+  return parseContractId(result.all || `${result.stdout}
+${result.stderr}`);
+}
+async function tryRecoverContractIdFromDeployFailure(options) {
+  if (!DEPLOY_SIGNING_FAILURE_REGEX.test(options.output)) {
+    return null;
+  }
+  const hashMatch = options.output.match(TX_HASH_REGEX);
+  if (!hashMatch) {
+    return null;
+  }
+  const horizonUrl = resolveHorizonUrl(options.network);
+  const salt = await fetchCreateContractSalt(horizonUrl, hashMatch[1], options.fetchImpl);
+  if (!salt) {
+    return null;
+  }
+  return resolveContractIdFromDeploySalt({
+    salt,
+    source: options.source,
+    network: options.network,
+    cwd: options.cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli
+  });
+}
+
 // src/contracts/dependency-graph.ts
 function buildDependencyGraph(contracts) {
   const graph = {};
@@ -599,14 +678,21 @@ function assertSafeSourceAccount(source) {
     throw new CaatingaError(
       "A source account or Stellar CLI identity is required.",
       CaatingaErrorCode.SOURCE_ACCOUNT_REQUIRED,
-      "Pass --source alice or --source G...; do not pass secret keys or seed phrases."
+      "Pass a Stellar CLI identity alias, for example: --source alice"
     );
   }
   if (source.startsWith("S") || source.trim().includes(" ")) {
     throw new CaatingaError(
       "Refusing to accept a likely secret key or seed phrase as --source.",
       CaatingaErrorCode.UNSAFE_SOURCE_ACCOUNT,
-      "Use a Stellar CLI identity alias or public account address instead."
+      "Use a Stellar CLI identity alias instead, for example: --source alice"
+    );
+  }
+  if (isLikelyPublicKeySource(source)) {
+    throw new CaatingaError(
+      `Public account address cannot sign transactions: ${source}`,
+      CaatingaErrorCode.UNSAFE_SOURCE_ACCOUNT,
+      "Use a Stellar CLI identity with a secret key. Example: stellar keys generate alice --fund --network testnet, then --source alice"
     );
   }
   return source;
@@ -685,14 +771,39 @@ async function deployContract(options) {
     network.config.networkPassphrase,
     ...constructorArgs
   ];
-  const result = await runCommand("stellar", stellarArgs, {
-    cwd,
-    allowUntestedStellarCli: options.allowUntestedStellarCli,
-    failureCode: CaatingaErrorCode.DEPLOY_FAILED
-  });
-  const output = result.all || `${result.stdout}
+  let output = "";
+  let contractId;
+  try {
+    const result = await runCommand("stellar", stellarArgs, {
+      cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli,
+      failureCode: CaatingaErrorCode.DEPLOY_FAILED
+    });
+    output = result.all || `${result.stdout}
 ${result.stderr}`;
-  const contractId = parseContractId(output);
+    contractId = parseContractId(output);
+  } catch (error) {
+    if (!(error instanceof CaatingaError) || error.code !== CaatingaErrorCode.DEPLOY_FAILED) {
+      throw error;
+    }
+    const recoveredContractId = await tryRecoverContractIdFromDeployFailure({
+      output: `${error.message}
+${error.hint ?? ""}`,
+      source,
+      network: network.config,
+      cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli
+    });
+    if (!recoveredContractId) {
+      throw error;
+    }
+    contractId = recoveredContractId;
+    output = [
+      error.hint ?? "",
+      "Caatinga recovered the contract ID from the on-chain deploy transaction.",
+      `Contract ID: ${contractId}`
+    ].filter(Boolean).join("\n");
+  }
   const wasmHash = await hashWasm(contract.wasmPath);
   const dependencyGraph = buildDependencyGraph(options.config.contracts);
   const dependencies = options.dependencies ?? contract.config.dependsOn;
@@ -946,9 +1057,45 @@ var TemplateManifestSchema = import_zod5.z.object({
     artifacts: import_zod5.z.string().default("caatinga.artifacts.json")
   })
 });
+function defaultCompatibleCoreRange(coreVersion = CAATINGA_CORE_VERSION) {
+  const version = import_semver2.default.valid(import_semver2.default.coerce(coreVersion));
+  if (!version) {
+    throw new Error(`Invalid core version: ${coreVersion}`);
+  }
+  return `^${version}`;
+}
 function isCoreVersionCompatible(range, coreVersion = CAATINGA_CORE_VERSION) {
   return import_semver2.default.satisfies(coreVersion, range);
 }
+function getTemplateCompatibilityIssue(manifest, coreVersion = CAATINGA_CORE_VERSION) {
+  if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
+    return {
+      kind: "template-version",
+      expected: CURRENT_TEMPLATE_VERSION,
+      actual: manifest.caatinga.templateVersion
+    };
+  }
+  if (!isCoreVersionCompatible(manifest.caatinga.compatibleCore, coreVersion)) {
+    return {
+      kind: "core-range",
+      requiredRange: manifest.caatinga.compatibleCore,
+      runningVersion: coreVersion
+    };
+  }
+  return null;
+}
+function formatTemplateCompatibilityMessage(issue) {
+  if (issue.kind === "template-version") {
+    return `Template manifest version ${issue.actual} is not supported; Caatinga requires templateVersion ${issue.expected}.`;
+  }
+  return `Template requires @caatinga/core ${issue.requiredRange} but running ${issue.runningVersion}.`;
+}
+function formatTemplateCompatibilityHint(issue) {
+  if (issue.kind === "template-version") {
+    return "Use a template built for this Caatinga release or upgrade Caatinga.";
+  }
+  return `Use a template with compatibleCore ${defaultCompatibleCoreRange(issue.runningVersion)} or install a matching Caatinga version.`;
+}
 
 // src/templates/create-project-from-template.ts
 async function createProjectFromTemplate(options) {
@@ -979,18 +1126,12 @@ async function readTemplateManifest(templateDir) {
   try {
     const rawManifest = await (0, import_promises6.readFile)(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
-    if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
-      throw new CaatingaError(
-        "Template is not compatible with this Caatinga version.",
-        CaatingaErrorCode.TEMPLATE_INCOMPATIBLE,
-        "Use a compatible template version or upgrade Caatinga."
-      );
-    }
-    if (!isCoreVersionCompatible(manifest.caatinga.compatibleCore)) {
+    const compatibilityIssue = getTemplateCompatibilityIssue(manifest);
+    if (compatibilityIssue) {
       throw new CaatingaError(
-        "Template is not compatible with this Caatinga version.",
+        formatTemplateCompatibilityMessage(compatibilityIssue),
         CaatingaErrorCode.TEMPLATE_INCOMPATIBLE,
-        "Use a compatible template version or upgrade Caatinga."
+        formatTemplateCompatibilityHint(compatibilityIssue)
       );
     }
     return manifest;

package/dist/index.d.cts

@@ -52,7 +52,7 @@ declare class CaatingaError extends Error {
 }
 declare function toCaatingaError(error: unknown): CaatingaError;
 
-declare const CAATINGA_CORE_VERSION = "0.2.0";
+declare const CAATINGA_CORE_VERSION = "0.2.1";
 
 declare const ContractConfigSchema: z.ZodObject<{
     path: z.ZodString;

package/dist/index.d.ts

@@ -52,7 +52,7 @@ declare class CaatingaError extends Error {
 }
 declare function toCaatingaError(error: unknown): CaatingaError;
 
-declare const CAATINGA_CORE_VERSION = "0.2.0";
+declare const CAATINGA_CORE_VERSION = "0.2.1";
 
 declare const ContractConfigSchema: z.ZodObject<{
     path: z.ZodString;

package/dist/index.js

@@ -66,7 +66,7 @@ function toCaatingaError(error) {
 }
 
 // src/version.ts
-var CAATINGA_CORE_VERSION = "0.2.0";
+var CAATINGA_CORE_VERSION = "0.2.1";
 
 // src/config/config.schema.ts
 import { z } from "zod";
@@ -483,6 +483,85 @@ async function buildContract(options) {
 // src/contracts/deploy-contract.ts
 import path5 from "path";
 
+// src/stellar-cli/recover-deploy-contract-id.ts
+var TX_HASH_REGEX = /Transaction hash is ([a-f0-9]{64})/i;
+var DEPLOY_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
+var HORIZON_URL_BY_PASSPHRASE = {
+  "Test SDF Network ; September 2015": "https://horizon-testnet.stellar.org",
+  "Public Global Stellar Network ; September 2015": "https://horizon.stellar.org"
+};
+function isLikelyPublicKeySource(source) {
+  return /^G[A-Z2-7]{55}$/.test(source);
+}
+function decimalSaltToHex(salt) {
+  return BigInt(salt).toString(16).padStart(64, "0");
+}
+function resolveHorizonUrl(network) {
+  const horizonUrl = HORIZON_URL_BY_PASSPHRASE[network.networkPassphrase];
+  if (!horizonUrl) {
+    throw new CaatingaError(
+      `No Horizon URL mapping for network passphrase "${network.networkPassphrase}".`,
+      CaatingaErrorCode.NETWORK_NOT_FOUND,
+      "Use testnet or mainnet, or extend Caatinga network metadata."
+    );
+  }
+  return horizonUrl;
+}
+async function fetchCreateContractSalt(horizonUrl, transactionHash, fetchImpl = fetch) {
+  const response = await fetchImpl(`${horizonUrl}/transactions/${transactionHash}/operations`);
+  if (!response.ok) {
+    return null;
+  }
+  const body = await response.json();
+  const operation = body._embedded?.records?.find(
+    (record) => record.transaction_successful === true && record.type === "invoke_host_function" && record.function === "HostFunctionTypeHostFunctionTypeCreateContract" && typeof record.salt === "string"
+  );
+  return operation?.salt ?? null;
+}
+async function resolveContractIdFromDeploySalt(options) {
+  const saltHex = decimalSaltToHex(options.salt);
+  const result = await runCommand("stellar", [
+    "contract",
+    "id",
+    "wasm",
+    "--salt",
+    saltHex,
+    "--source-account",
+    options.source,
+    "--rpc-url",
+    options.network.rpcUrl,
+    "--network-passphrase",
+    options.network.networkPassphrase
+  ], {
+    cwd: options.cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli,
+    skipStellarVersionCheck: true
+  });
+  return parseContractId(result.all || `${result.stdout}
+${result.stderr}`);
+}
+async function tryRecoverContractIdFromDeployFailure(options) {
+  if (!DEPLOY_SIGNING_FAILURE_REGEX.test(options.output)) {
+    return null;
+  }
+  const hashMatch = options.output.match(TX_HASH_REGEX);
+  if (!hashMatch) {
+    return null;
+  }
+  const horizonUrl = resolveHorizonUrl(options.network);
+  const salt = await fetchCreateContractSalt(horizonUrl, hashMatch[1], options.fetchImpl);
+  if (!salt) {
+    return null;
+  }
+  return resolveContractIdFromDeploySalt({
+    salt,
+    source: options.source,
+    network: options.network,
+    cwd: options.cwd,
+    allowUntestedStellarCli: options.allowUntestedStellarCli
+  });
+}
+
 // src/contracts/dependency-graph.ts
 function buildDependencyGraph(contracts) {
   const graph = {};
@@ -529,14 +608,21 @@ function assertSafeSourceAccount(source) {
     throw new CaatingaError(
       "A source account or Stellar CLI identity is required.",
       CaatingaErrorCode.SOURCE_ACCOUNT_REQUIRED,
-      "Pass --source alice or --source G...; do not pass secret keys or seed phrases."
+      "Pass a Stellar CLI identity alias, for example: --source alice"
     );
   }
   if (source.startsWith("S") || source.trim().includes(" ")) {
     throw new CaatingaError(
       "Refusing to accept a likely secret key or seed phrase as --source.",
       CaatingaErrorCode.UNSAFE_SOURCE_ACCOUNT,
-      "Use a Stellar CLI identity alias or public account address instead."
+      "Use a Stellar CLI identity alias instead, for example: --source alice"
+    );
+  }
+  if (isLikelyPublicKeySource(source)) {
+    throw new CaatingaError(
+      `Public account address cannot sign transactions: ${source}`,
+      CaatingaErrorCode.UNSAFE_SOURCE_ACCOUNT,
+      "Use a Stellar CLI identity with a secret key. Example: stellar keys generate alice --fund --network testnet, then --source alice"
     );
   }
   return source;
@@ -615,14 +701,39 @@ async function deployContract(options) {
     network.config.networkPassphrase,
     ...constructorArgs
   ];
-  const result = await runCommand("stellar", stellarArgs, {
-    cwd,
-    allowUntestedStellarCli: options.allowUntestedStellarCli,
-    failureCode: CaatingaErrorCode.DEPLOY_FAILED
-  });
-  const output = result.all || `${result.stdout}
+  let output = "";
+  let contractId;
+  try {
+    const result = await runCommand("stellar", stellarArgs, {
+      cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli,
+      failureCode: CaatingaErrorCode.DEPLOY_FAILED
+    });
+    output = result.all || `${result.stdout}
 ${result.stderr}`;
-  const contractId = parseContractId(output);
+    contractId = parseContractId(output);
+  } catch (error) {
+    if (!(error instanceof CaatingaError) || error.code !== CaatingaErrorCode.DEPLOY_FAILED) {
+      throw error;
+    }
+    const recoveredContractId = await tryRecoverContractIdFromDeployFailure({
+      output: `${error.message}
+${error.hint ?? ""}`,
+      source,
+      network: network.config,
+      cwd,
+      allowUntestedStellarCli: options.allowUntestedStellarCli
+    });
+    if (!recoveredContractId) {
+      throw error;
+    }
+    contractId = recoveredContractId;
+    output = [
+      error.hint ?? "",
+      "Caatinga recovered the contract ID from the on-chain deploy transaction.",
+      `Contract ID: ${contractId}`
+    ].filter(Boolean).join("\n");
+  }
   const wasmHash = await hashWasm(contract.wasmPath);
   const dependencyGraph = buildDependencyGraph(options.config.contracts);
   const dependencies = options.dependencies ?? contract.config.dependsOn;
@@ -876,9 +987,45 @@ var TemplateManifestSchema = z5.object({
     artifacts: z5.string().default("caatinga.artifacts.json")
   })
 });
+function defaultCompatibleCoreRange(coreVersion = CAATINGA_CORE_VERSION) {
+  const version = semver2.valid(semver2.coerce(coreVersion));
+  if (!version) {
+    throw new Error(`Invalid core version: ${coreVersion}`);
+  }
+  return `^${version}`;
+}
 function isCoreVersionCompatible(range, coreVersion = CAATINGA_CORE_VERSION) {
   return semver2.satisfies(coreVersion, range);
 }
+function getTemplateCompatibilityIssue(manifest, coreVersion = CAATINGA_CORE_VERSION) {
+  if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
+    return {
+      kind: "template-version",
+      expected: CURRENT_TEMPLATE_VERSION,
+      actual: manifest.caatinga.templateVersion
+    };
+  }
+  if (!isCoreVersionCompatible(manifest.caatinga.compatibleCore, coreVersion)) {
+    return {
+      kind: "core-range",
+      requiredRange: manifest.caatinga.compatibleCore,
+      runningVersion: coreVersion
+    };
+  }
+  return null;
+}
+function formatTemplateCompatibilityMessage(issue) {
+  if (issue.kind === "template-version") {
+    return `Template manifest version ${issue.actual} is not supported; Caatinga requires templateVersion ${issue.expected}.`;
+  }
+  return `Template requires @caatinga/core ${issue.requiredRange} but running ${issue.runningVersion}.`;
+}
+function formatTemplateCompatibilityHint(issue) {
+  if (issue.kind === "template-version") {
+    return "Use a template built for this Caatinga release or upgrade Caatinga.";
+  }
+  return `Use a template with compatibleCore ${defaultCompatibleCoreRange(issue.runningVersion)} or install a matching Caatinga version.`;
+}
 
 // src/templates/create-project-from-template.ts
 async function createProjectFromTemplate(options) {
@@ -909,18 +1056,12 @@ async function readTemplateManifest(templateDir) {
   try {
     const rawManifest = await readFile3(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
-    if (manifest.caatinga.templateVersion !== CURRENT_TEMPLATE_VERSION) {
-      throw new CaatingaError(
-        "Template is not compatible with this Caatinga version.",
-        CaatingaErrorCode.TEMPLATE_INCOMPATIBLE,
-        "Use a compatible template version or upgrade Caatinga."
-      );
-    }
-    if (!isCoreVersionCompatible(manifest.caatinga.compatibleCore)) {
+    const compatibilityIssue = getTemplateCompatibilityIssue(manifest);
+    if (compatibilityIssue) {
       throw new CaatingaError(
-        "Template is not compatible with this Caatinga version.",
+        formatTemplateCompatibilityMessage(compatibilityIssue),
         CaatingaErrorCode.TEMPLATE_INCOMPATIBLE,
-        "Use a compatible template version or upgrade Caatinga."
+        formatTemplateCompatibilityHint(compatibilityIssue)
       );
     }
     return manifest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caatinga/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Core config, artifacts, command orchestration, and error primitives for Caatinga/Soroban toolkit",
   "keywords": [
     "stellar",