@caatinga/core 2.1.0 → 2.2.0

package/dist/index.cjs

@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BINDING_MARKER_FILENAME: () => BINDING_MARKER_FILENAME,
+  BindingMarkerSchema: () => BindingMarkerSchema,
   CAATINGA_CORE_VERSION: () => CAATINGA_CORE_VERSION,
   CaatingaArtifactsSchema: () => CaatingaArtifactsSchema,
   CaatingaConfigSchema: () => CaatingaConfigSchema,
@@ -43,11 +45,14 @@ __export(index_exports, {
   buildDependencyGraph: () => buildDependencyGraph,
   checkBinary: () => checkBinary,
   checkStellarCliVersion: () => checkStellarCliVersion,
+  collectProjectStatus: () => collectProjectStatus,
   createInitialArtifacts: () => createInitialArtifacts,
   createProjectFromTemplate: () => createProjectFromTemplate,
   defineConfig: () => defineConfig,
   deployContract: () => deployContract,
   deployContractGraph: () => deployContractGraph,
+  evaluateBindingFreshness: () => evaluateBindingFreshness,
+  evaluateBindingsFreshness: () => evaluateBindingsFreshness,
   evaluateStellarCliCompatibility: () => evaluateStellarCliCompatibility,
   formatCaatingaError: () => formatCaatingaError,
   generateBindings: () => generateBindings,
@@ -59,6 +64,7 @@ __export(index_exports, {
   parseInvokeTarget: () => parseInvokeTarget,
   parseStellarCliVersion: () => parseStellarCliVersion,
   readArtifacts: () => readArtifacts,
+  readBindingMarker: () => readBindingMarker,
   resolveContract: () => resolveContract,
   resolveDeployArgs: () => resolveDeployArgs,
   resolveDeployOrder: () => resolveDeployOrder,
@@ -67,7 +73,8 @@ __export(index_exports, {
   toCaatingaError: () => toCaatingaError,
   updateArtifact: () => updateArtifact,
   validateSourceShape: () => validateSourceShape,
-  writeArtifacts: () => writeArtifacts
+  writeArtifacts: () => writeArtifacts,
+  writeBindingMarker: () => writeBindingMarker
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -178,7 +185,7 @@ function formatCause(cause) {
 }
 
 // src/version.ts
-var CAATINGA_CORE_VERSION = "2.1.0";
+var CAATINGA_CORE_VERSION = "2.2.0";
 
 // src/config/config.schema.ts
 var import_zod = require("zod");
@@ -344,18 +351,6 @@ function updateArtifact(artifacts, networkName, contractName, contractArtifact,
   };
 }
 
-// src/networks/networks.ts
-var WELL_KNOWN_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"
-  }
-};
-
 // src/networks/resolve-network.ts
 function resolveNetwork(config, networkName) {
   const name = networkName ?? config.defaultNetwork;
@@ -370,6 +365,174 @@ function resolveNetwork(config, networkName) {
   return { name, config: network };
 }
 
+// src/bindings/binding-freshness.ts
+var import_promises5 = require("fs/promises");
+var import_node_path5 = __toESM(require("path"), 1);
+
+// src/bindings/binding-marker.ts
+var import_promises4 = require("fs/promises");
+var import_node_path4 = __toESM(require("path"), 1);
+var import_zod5 = require("zod");
+var BINDING_MARKER_FILENAME = ".caatinga-bindings.json";
+var BindingMarkerSchema = import_zod5.z.object({
+  version: import_zod5.z.literal(1),
+  contractId: import_zod5.z.string().min(1),
+  wasmHash: import_zod5.z.string().min(1),
+  network: import_zod5.z.string().min(1),
+  generatedAt: import_zod5.z.string().datetime()
+});
+async function writeBindingMarker(outputDir, marker) {
+  const markerPath = import_node_path4.default.join(outputDir, BINDING_MARKER_FILENAME);
+  await (0, import_promises4.writeFile)(markerPath, `${JSON.stringify(marker, null, 2)}
+`, "utf8");
+}
+async function readBindingMarker(outputDir) {
+  const markerPath = import_node_path4.default.join(outputDir, BINDING_MARKER_FILENAME);
+  let raw;
+  try {
+    raw = await (0, import_promises4.readFile)(markerPath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return BindingMarkerSchema.parse(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+// src/bindings/binding-freshness.ts
+async function listGeneratedEntries(outputDir) {
+  try {
+    const entries = await (0, import_promises5.readdir)(outputDir);
+    return entries.filter((entry) => entry !== BINDING_MARKER_FILENAME);
+  } catch {
+    return null;
+  }
+}
+async function evaluateBindingFreshness(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const outputDir = import_node_path5.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  const contractArtifact = options.artifacts.networks[options.networkName]?.contracts[options.contractName];
+  if (!contractArtifact) {
+    return {
+      contractName: options.contractName,
+      status: "missing",
+      outputDir,
+      marker: null,
+      reason: `not deployed on "${options.networkName}"`
+    };
+  }
+  const generatedEntries = await listGeneratedEntries(outputDir);
+  if (generatedEntries === null || generatedEntries.length === 0) {
+    return {
+      contractName: options.contractName,
+      status: "missing",
+      outputDir,
+      marker: null,
+      reason: "no generated bindings found"
+    };
+  }
+  const marker = await readBindingMarker(outputDir);
+  if (!marker) {
+    return {
+      contractName: options.contractName,
+      status: "unknown",
+      outputDir,
+      marker: null,
+      reason: "bindings exist but have no provenance marker \u2014 rerun caatinga generate to record it"
+    };
+  }
+  if (marker.contractId !== contractArtifact.contractId) {
+    return {
+      contractName: options.contractName,
+      status: "stale",
+      outputDir,
+      marker,
+      reason: "contractId changed since last generate"
+    };
+  }
+  if (marker.wasmHash !== contractArtifact.wasmHash) {
+    return {
+      contractName: options.contractName,
+      status: "stale",
+      outputDir,
+      marker,
+      reason: "wasmHash changed since last generate"
+    };
+  }
+  return {
+    contractName: options.contractName,
+    status: "fresh",
+    outputDir,
+    marker
+  };
+}
+async function evaluateBindingsFreshness(options) {
+  const contractNames = Object.keys(
+    options.artifacts.networks[options.networkName]?.contracts ?? {}
+  );
+  const results = [];
+  for (const contractName of contractNames) {
+    results.push(await evaluateBindingFreshness({ ...options, contractName }));
+  }
+  return results;
+}
+
+// src/artifacts/project-status.ts
+async function collectProjectStatus(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const artifacts = await readArtifacts(cwd);
+  let networkNames;
+  if (options.networkName) {
+    networkNames = [resolveNetwork(options.config, options.networkName).name];
+  } else {
+    const fromArtifacts = Object.keys(artifacts.networks);
+    const fallback = options.config.defaultNetwork ?? "testnet";
+    networkNames = fromArtifacts.length > 0 ? fromArtifacts : [fallback];
+    if (!networkNames.includes(fallback) && options.config.networks[fallback]) {
+      networkNames.push(fallback);
+    }
+  }
+  const networks = [];
+  for (const networkName of networkNames) {
+    const contracts = [];
+    for (const name of Object.keys(options.config.contracts)) {
+      const artifact = artifacts.networks[networkName]?.contracts[name];
+      const bindings = await evaluateBindingFreshness({
+        config: options.config,
+        artifacts,
+        networkName,
+        contractName: name,
+        cwd
+      });
+      contracts.push({
+        name,
+        deployed: Boolean(artifact),
+        contractId: artifact?.contractId,
+        wasmHash: artifact?.wasmHash,
+        deployedAt: artifact?.deployedAt,
+        dependencies: artifact?.dependencies ?? options.config.contracts[name].dependsOn ?? [],
+        bindings
+      });
+    }
+    networks.push({ network: networkName, contracts });
+  }
+  return { project: options.config.project, networks };
+}
+
+// src/networks/networks.ts
+var WELL_KNOWN_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"
+  }
+};
+
 // src/shell/run-command.ts
 var import_execa = require("execa");
 
@@ -691,7 +854,7 @@ function validateSourceShape(source) {
 }
 
 // src/contracts/resolve-contract.ts
-var import_node_path4 = __toESM(require("path"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 function resolveContract(config, contractName, cwd = process.cwd()) {
   const contract = config.contracts[contractName];
   if (!contract) {
@@ -704,15 +867,15 @@ function resolveContract(config, contractName, cwd = process.cwd()) {
   return {
     name: contractName,
     config: contract,
-    sourcePath: import_node_path4.default.resolve(cwd, contract.path),
-    wasmPath: import_node_path4.default.resolve(cwd, contract.wasm)
+    sourcePath: import_node_path6.default.resolve(cwd, contract.path),
+    wasmPath: import_node_path6.default.resolve(cwd, contract.wasm)
   };
 }
 
 // src/contracts/wasm.ts
 var import_node_crypto = require("crypto");
-var import_promises4 = require("fs/promises");
-var import_node_path5 = __toESM(require("path"), 1);
+var import_promises6 = require("fs/promises");
+var import_node_path7 = __toESM(require("path"), 1);
 var LEGACY_RUST_WASM_TARGET = "wasm32-unknown-unknown";
 var CURRENT_RUST_WASM_TARGET = "wasm32v1-none";
 function toCurrentWasmTargetPath(wasmPath) {
@@ -735,12 +898,12 @@ function wasmNotFoundError(configuredWasmPath, options) {
   );
 }
 function toConfigRelativeWasmPath(absoluteWasmPath) {
-  const relative = import_node_path5.default.relative(process.cwd(), absoluteWasmPath);
-  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(import_node_path5.default.sep).join("/")}`;
+  const relative = import_node_path7.default.relative(process.cwd(), absoluteWasmPath);
+  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(import_node_path7.default.sep).join("/")}`;
 }
 async function resolveWasmArtifactPath(configuredWasmPath) {
   try {
-    await (0, import_promises4.access)(configuredWasmPath);
+    await (0, import_promises6.access)(configuredWasmPath);
     return configuredWasmPath;
   } catch {
     const currentTargetPath = toCurrentWasmTargetPath(configuredWasmPath);
@@ -748,7 +911,7 @@ async function resolveWasmArtifactPath(configuredWasmPath) {
       throw wasmNotFoundError(configuredWasmPath);
     }
     try {
-      await (0, import_promises4.access)(currentTargetPath);
+      await (0, import_promises6.access)(currentTargetPath);
       return currentTargetPath;
     } catch {
       throw wasmNotFoundError(configuredWasmPath, { migratedPath: currentTargetPath });
@@ -756,20 +919,20 @@ async function resolveWasmArtifactPath(configuredWasmPath) {
   }
 }
 async function hashWasm(wasmPath) {
-  const bytes = await (0, import_promises4.readFile)(wasmPath);
+  const bytes = await (0, import_promises6.readFile)(wasmPath);
   return (0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex");
 }
 async function getNewestMtimeInDirectory(directory) {
   try {
-    await (0, import_promises4.access)(directory);
+    await (0, import_promises6.access)(directory);
   } catch {
     return void 0;
   }
   let newest = 0;
   async function walk(dir) {
-    const entries = await (0, import_promises4.readdir)(dir, { withFileTypes: true });
+    const entries = await (0, import_promises6.readdir)(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const entryPath = import_node_path5.default.join(dir, entry.name);
+      const entryPath = import_node_path7.default.join(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(entryPath);
         continue;
@@ -777,7 +940,7 @@ async function getNewestMtimeInDirectory(directory) {
       if (!entry.isFile()) {
         continue;
       }
-      const fileStat = await (0, import_promises4.stat)(entryPath);
+      const fileStat = await (0, import_promises6.stat)(entryPath);
       newest = Math.max(newest, fileStat.mtimeMs);
     }
   }
@@ -785,14 +948,14 @@ async function getNewestMtimeInDirectory(directory) {
   return newest > 0 ? newest : void 0;
 }
 async function isWasmOlderThanSources(input) {
-  const srcDir = import_node_path5.default.join(input.contractPath, "src");
+  const srcDir = import_node_path7.default.join(input.contractPath, "src");
   const newestSourceMtime = await getNewestMtimeInDirectory(srcDir);
   if (newestSourceMtime === void 0) {
     return false;
   }
   let wasmStat;
   try {
-    wasmStat = await (0, import_promises4.stat)(input.wasmPath);
+    wasmStat = await (0, import_promises6.stat)(input.wasmPath);
   } catch {
     return false;
   }
@@ -858,7 +1021,7 @@ async function buildContract(options) {
 }
 
 // src/contracts/deploy-contract.ts
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
 
 // src/contracts/dependency-graph.ts
 function buildDependencyGraph(contracts) {
@@ -959,7 +1122,7 @@ async function deployContract(options) {
       contract: contractWithWasm,
       network,
       contractId: existing.contractId,
-      artifactsPath: import_node_path6.default.resolve(cwd, "caatinga.artifacts.json"),
+      artifactsPath: import_node_path8.default.resolve(cwd, "caatinga.artifacts.json"),
       output: "",
       skipped: true,
       staleWasmWarning
@@ -1235,17 +1398,17 @@ async function deployContractGraph(options) {
 }
 
 // src/contracts/generate-bindings.ts
-var import_promises5 = require("fs/promises");
-var import_node_path7 = __toESM(require("path"), 1);
+var import_promises7 = require("fs/promises");
+var import_node_path9 = __toESM(require("path"), 1);
 function toBindingImportPath(bindingsOutput, contractName) {
-  const normalized = bindingsOutput.replace(/^\.\//, "").split(import_node_path7.default.sep).join("/");
-  return `./${import_node_path7.default.posix.join(normalized, contractName, "src", "index.js")}`;
+  const normalized = bindingsOutput.replace(/^\.\//, "").split(import_node_path9.default.sep).join("/");
+  return `./${import_node_path9.default.posix.join(normalized, contractName, "src", "index.js")}`;
 }
 async function removeLegacyBindingStub(cwd, bindingsOutput, contractName) {
-  const legacyPath = import_node_path7.default.resolve(cwd, bindingsOutput, `${contractName}.ts`);
+  const legacyPath = import_node_path9.default.resolve(cwd, bindingsOutput, `${contractName}.ts`);
   try {
-    await (0, import_promises5.access)(legacyPath);
-    await (0, import_promises5.unlink)(legacyPath);
+    await (0, import_promises7.access)(legacyPath);
+    await (0, import_promises7.unlink)(legacyPath);
     return true;
   } catch {
     return false;
@@ -1264,8 +1427,8 @@ async function generateBindings(options) {
     );
   }
   await checkBinary("stellar", "Install Stellar CLI before running caatinga generate.");
-  const outputDir = import_node_path7.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
-  await (0, import_promises5.mkdir)(outputDir, { recursive: true });
+  const outputDir = import_node_path9.default.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  await (0, import_promises7.mkdir)(outputDir, { recursive: true });
   const result = await runCommand("stellar", [
     "contract",
     "bindings",
@@ -1285,12 +1448,21 @@ async function generateBindings(options) {
     options.config.frontend.bindingsOutput,
     options.contractName
   );
+  const marker = {
+    version: 1,
+    contractId: contractArtifact.contractId,
+    wasmHash: contractArtifact.wasmHash,
+    network: network.name,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeBindingMarker(outputDir, marker);
   return {
     contractName: options.contractName,
     network,
     outputDir,
     importPath: toBindingImportPath(options.config.frontend.bindingsOutput, options.contractName),
     legacyStubRemoved,
+    marker,
     output: result.all || result.stdout
   };
 }
@@ -1302,6 +1474,8 @@ async function generateBindingsGraph(options) {
   let targets;
   if (options.contractName) {
     targets = [options.contractName];
+  } else if (options.contractNames && options.contractNames.length > 0) {
+    targets = options.contractNames;
   } else {
     const artifacts = await readArtifacts(cwd);
     targets = Object.keys(artifacts.networks[network.name]?.contracts ?? {});
@@ -1399,33 +1573,33 @@ ${error.hint ?? ""}`)) {
 }
 
 // src/templates/create-project-from-template.ts
-var import_promises6 = require("fs/promises");
-var import_node_path8 = __toESM(require("path"), 1);
-var import_zod6 = require("zod");
+var import_promises8 = require("fs/promises");
+var import_node_path10 = __toESM(require("path"), 1);
+var import_zod7 = require("zod");
 
 // src/templates/template-manifest.schema.ts
-var import_zod5 = require("zod");
+var import_zod6 = require("zod");
 var import_semver3 = __toESM(require("semver"), 1);
 var CURRENT_TEMPLATE_VERSION = 1;
-var TemplateManifestSchema = import_zod5.z.object({
-  name: import_zod5.z.string().min(1),
-  version: import_zod5.z.string().min(1),
-  description: import_zod5.z.string().optional(),
-  caatinga: import_zod5.z.object({
-    compatibleCore: import_zod5.z.string().min(1),
-    templateVersion: import_zod5.z.number().int().positive()
+var TemplateManifestSchema = import_zod6.z.object({
+  name: import_zod6.z.string().min(1),
+  version: import_zod6.z.string().min(1),
+  description: import_zod6.z.string().optional(),
+  caatinga: import_zod6.z.object({
+    compatibleCore: import_zod6.z.string().min(1),
+    templateVersion: import_zod6.z.number().int().positive()
   }),
-  frontend: import_zod5.z.object({
-    framework: import_zod5.z.enum(["vite-react", "next", "astro"]),
-    packageManager: import_zod5.z.enum(["npm", "pnpm", "yarn", "bun"]).default("npm")
+  frontend: import_zod6.z.object({
+    framework: import_zod6.z.enum(["vite-react", "next", "astro"]),
+    packageManager: import_zod6.z.enum(["npm", "pnpm", "yarn", "bun"]).default("npm")
   }),
-  contracts: import_zod5.z.object({
-    path: import_zod5.z.string(),
-    default: import_zod5.z.string().optional()
+  contracts: import_zod6.z.object({
+    path: import_zod6.z.string(),
+    default: import_zod6.z.string().optional()
   }),
-  files: import_zod5.z.object({
-    config: import_zod5.z.string().default("caatinga.config.ts"),
-    artifacts: import_zod5.z.string().default("caatinga.artifacts.json")
+  files: import_zod6.z.object({
+    config: import_zod6.z.string().default("caatinga.config.ts"),
+    artifacts: import_zod6.z.string().default("caatinga.artifacts.json")
   })
 });
 function defaultCompatibleCoreRange(coreVersion = CAATINGA_CORE_VERSION) {
@@ -1476,10 +1650,10 @@ var TEMPLATE_COPY_EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   ".git"
 ]);
 async function createProjectFromTemplate(options) {
-  const targetDir = import_node_path8.default.resolve(options.targetDir);
-  const templateDir = import_node_path8.default.resolve(options.templateDir);
+  const targetDir = import_node_path10.default.resolve(options.targetDir);
+  const templateDir = import_node_path10.default.resolve(options.templateDir);
   try {
-    await (0, import_promises6.stat)(templateDir);
+    await (0, import_promises8.stat)(templateDir);
   } catch {
     throw new CaatingaError(
       `Template directory was not found: ${templateDir}`,
@@ -1488,8 +1662,8 @@ async function createProjectFromTemplate(options) {
     );
   }
   const manifest = await readTemplateManifest(templateDir);
-  await (0, import_promises6.mkdir)(targetDir, { recursive: true });
-  await (0, import_promises6.cp)(templateDir, targetDir, {
+  await (0, import_promises8.mkdir)(targetDir, { recursive: true });
+  await (0, import_promises8.cp)(templateDir, targetDir, {
     recursive: true,
     force: false,
     errorOnExist: true,
@@ -1512,9 +1686,9 @@ async function ensureArtifacts(targetDir, projectName) {
   }
 }
 async function readTemplateManifest(templateDir) {
-  const manifestPath = import_node_path8.default.join(templateDir, "caatinga.template.json");
+  const manifestPath = import_node_path10.default.join(templateDir, "caatinga.template.json");
   try {
-    const rawManifest = await (0, import_promises6.readFile)(manifestPath, "utf8");
+    const rawManifest = await (0, import_promises8.readFile)(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
     const compatibilityIssue = getTemplateCompatibilityIssue(manifest);
     if (compatibilityIssue) {
@@ -1536,7 +1710,7 @@ async function readTemplateManifest(templateDir) {
     if (error instanceof CaatingaError) {
       throw error;
     }
-    if (error instanceof SyntaxError || error instanceof import_zod6.z.ZodError) {
+    if (error instanceof SyntaxError || error instanceof import_zod7.z.ZodError) {
       throw new CaatingaError(
         "Template manifest is invalid.",
         CaatingaErrorCode.INVALID_TEMPLATE_MANIFEST,
@@ -1547,10 +1721,10 @@ async function readTemplateManifest(templateDir) {
   }
 }
 async function replaceTemplateVariables(dir, projectName) {
-  const entries = await (0, import_promises6.readdir)(dir);
+  const entries = await (0, import_promises8.readdir)(dir);
   await Promise.all(entries.map(async (entry) => {
-    const entryPath = import_node_path8.default.join(dir, entry);
-    const entryStat = await (0, import_promises6.stat)(entryPath);
+    const entryPath = import_node_path10.default.join(dir, entry);
+    const entryStat = await (0, import_promises8.stat)(entryPath);
     if (entryStat.isDirectory()) {
       await replaceTemplateVariables(entryPath, projectName);
       return;
@@ -1558,16 +1732,16 @@ async function replaceTemplateVariables(dir, projectName) {
     if (!isTextTemplateFile(entryPath)) {
       return;
     }
-    const content = await (0, import_promises6.readFile)(entryPath, "utf8");
-    await (0, import_promises6.writeFile)(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
+    const content = await (0, import_promises8.readFile)(entryPath, "utf8");
+    await (0, import_promises8.writeFile)(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
   }));
 }
 function shouldCopyTemplateEntry(templateDir, source) {
-  const relativePath = import_node_path8.default.relative(templateDir, source);
+  const relativePath = import_node_path10.default.relative(templateDir, source);
   if (!relativePath || relativePath === ".") {
     return true;
   }
-  return !relativePath.split(import_node_path8.default.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
+  return !relativePath.split(import_node_path10.default.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
 }
 function isTextTemplateFile(filePath) {
   return [
@@ -1579,7 +1753,7 @@ function isTextTemplateFile(filePath) {
     ".tsx",
     ".css",
     ".html"
-  ].includes(import_node_path8.default.extname(filePath));
+  ].includes(import_node_path10.default.extname(filePath));
 }
 
 // src/ci/is-transient-testnet-smoke-failure.ts
@@ -1604,6 +1778,8 @@ function isTransientTestnetSmokeFailure(logText) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BINDING_MARKER_FILENAME,
+  BindingMarkerSchema,
   CAATINGA_CORE_VERSION,
   CaatingaArtifactsSchema,
   CaatingaConfigSchema,
@@ -1617,11 +1793,14 @@ function isTransientTestnetSmokeFailure(logText) {
   buildDependencyGraph,
   checkBinary,
   checkStellarCliVersion,
+  collectProjectStatus,
   createInitialArtifacts,
   createProjectFromTemplate,
   defineConfig,
   deployContract,
   deployContractGraph,
+  evaluateBindingFreshness,
+  evaluateBindingsFreshness,
   evaluateStellarCliCompatibility,
   formatCaatingaError,
   generateBindings,
@@ -1633,6 +1812,7 @@ function isTransientTestnetSmokeFailure(logText) {
   parseInvokeTarget,
   parseStellarCliVersion,
   readArtifacts,
+  readBindingMarker,
   resolveContract,
   resolveDeployArgs,
   resolveDeployOrder,
@@ -1641,5 +1821,6 @@ function isTransientTestnetSmokeFailure(logText) {
   toCaatingaError,
   updateArtifact,
   validateSourceShape,
-  writeArtifacts
+  writeArtifacts,
+  writeBindingMarker
 });

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { C as CaatingaArtifacts, a as ContractArtifact, b as CaatingaErrorCodeVa
 export { d as CaatingaArtifactsSchema, e as CaatingaErrorCode, f as formatCaatingaError, t as toCaatingaError } from './browser-Cq4ZofIq.cjs';
 import { z } from 'zod';
 
-declare const CAATINGA_CORE_VERSION = "2.1.0";
+declare const CAATINGA_CORE_VERSION = "2.2.0";
 
 declare const ContractConfigSchema: z.ZodObject<{
     path: z.ZodString;
@@ -144,6 +144,78 @@ declare function updateArtifact(artifacts: CaatingaArtifacts, networkName: strin
     dependencyGraph?: Record<string, string[]>;
 }): CaatingaArtifacts;
 
+declare const BINDING_MARKER_FILENAME = ".caatinga-bindings.json";
+declare const BindingMarkerSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    contractId: z.ZodString;
+    wasmHash: z.ZodString;
+    network: z.ZodString;
+    generatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    contractId: string;
+    wasmHash: string;
+    version: 1;
+    network: string;
+    generatedAt: string;
+}, {
+    contractId: string;
+    wasmHash: string;
+    version: 1;
+    network: string;
+    generatedAt: string;
+}>;
+type BindingMarker = z.infer<typeof BindingMarkerSchema>;
+declare function writeBindingMarker(outputDir: string, marker: BindingMarker): Promise<void>;
+/** Returns null when the marker is absent or unreadable — freshness degrades, never throws. */
+declare function readBindingMarker(outputDir: string): Promise<BindingMarker | null>;
+
+type BindingFreshnessStatus = "fresh" | "stale" | "missing" | "unknown";
+type BindingFreshness = {
+    contractName: string;
+    status: BindingFreshnessStatus;
+    outputDir: string;
+    marker: BindingMarker | null;
+    reason?: string;
+};
+type EvaluateBindingFreshnessOptions = {
+    config: CaatingaConfig;
+    artifacts: CaatingaArtifacts;
+    networkName: string;
+    contractName: string;
+    cwd?: string;
+};
+declare function evaluateBindingFreshness(options: EvaluateBindingFreshnessOptions): Promise<BindingFreshness>;
+declare function evaluateBindingsFreshness(options: {
+    config: CaatingaConfig;
+    artifacts: CaatingaArtifacts;
+    networkName: string;
+    cwd?: string;
+}): Promise<BindingFreshness[]>;
+
+type ContractStatusEntry = {
+    name: string;
+    deployed: boolean;
+    contractId?: string;
+    wasmHash?: string;
+    deployedAt?: string;
+    dependencies: string[];
+    bindings: BindingFreshness;
+};
+type NetworkStatus = {
+    network: string;
+    contracts: ContractStatusEntry[];
+};
+type ProjectStatus = {
+    project: string;
+    networks: NetworkStatus[];
+};
+type CollectProjectStatusOptions = {
+    config: CaatingaConfig;
+    networkName?: string;
+    cwd?: string;
+};
+declare function collectProjectStatus(options: CollectProjectStatusOptions): Promise<ProjectStatus>;
+
 declare const WELL_KNOWN_NETWORKS: Record<string, NetworkConfig>;
 
 type ResolvedNetwork = {
@@ -327,6 +399,13 @@ declare function generateBindings(options: GenerateBindingsOptions): Promise<{
     outputDir: string;
     importPath: string;
     legacyStubRemoved: boolean;
+    marker: {
+        contractId: string;
+        wasmHash: string;
+        version: 1;
+        network: string;
+        generatedAt: string;
+    };
     output: string;
 }>;
 
@@ -337,6 +416,7 @@ type GenerateBindingsGraphResult = {
 declare function generateBindingsGraph(options: {
     config: CaatingaConfig;
     contractName?: string;
+    contractNames?: string[];
     networkName?: string;
     cwd?: string;
 }): Promise<GenerateBindingsGraphResult>;
@@ -479,4 +559,4 @@ type TemplateManifest = z.infer<typeof TemplateManifestSchema>;
 
 declare function isTransientTestnetSmokeFailure(logText: string): boolean;
 
-export { type BuildContractOptions, CAATINGA_CORE_VERSION, CaatingaArtifacts, type CaatingaConfig, CaatingaConfigSchema, CaatingaError, type CheckStellarCliVersionOptions, type CompatibilityReport, type CompatibilityStatus, type CompatibilityWarning, type CompatibilityWarningCode, ContractArtifact, type ContractConfig, type CreateInitialArtifactsOptions, type CreateProjectFromTemplateOptions, type DeployArgValue, type DeployContractGraphResult, type DeployContractOptions, type EvaluateStellarCliCompatibilityInput, type GenerateBindingsGraphResult, type GenerateBindingsOptions, type InvokeContractOptions, type InvokeTarget, type LoadConfigOptions, type NetworkConfig, type ResolvedContract, type ResolvedNetwork, type RunCommandResult, STELLAR_CLI_LAST_TESTED_VERSION, STELLAR_CLI_MIN_VERSION, type SkippedContract, type TemplateManifest, TemplateManifestSchema, WELL_KNOWN_NETWORKS, buildContract, buildDependencyGraph, checkBinary, checkStellarCliVersion, createInitialArtifacts, createProjectFromTemplate, defineConfig, deployContract, deployContractGraph, evaluateStellarCliCompatibility, generateBindings, generateBindingsGraph, invokeContract, isTransientTestnetSmokeFailure, loadConfig, parseContractId, parseInvokeTarget, parseStellarCliVersion, readArtifacts, resolveContract, resolveDeployArgs, resolveDeployOrder, resolveNetwork, runCommand, updateArtifact, validateSourceShape, writeArtifacts };
+export { BINDING_MARKER_FILENAME, type BindingFreshness, type BindingFreshnessStatus, type BindingMarker, BindingMarkerSchema, type BuildContractOptions, CAATINGA_CORE_VERSION, CaatingaArtifacts, type CaatingaConfig, CaatingaConfigSchema, CaatingaError, type CheckStellarCliVersionOptions, type CollectProjectStatusOptions, type CompatibilityReport, type CompatibilityStatus, type CompatibilityWarning, type CompatibilityWarningCode, ContractArtifact, type ContractConfig, type ContractStatusEntry, type CreateInitialArtifactsOptions, type CreateProjectFromTemplateOptions, type DeployArgValue, type DeployContractGraphResult, type DeployContractOptions, type EvaluateBindingFreshnessOptions, type EvaluateStellarCliCompatibilityInput, type GenerateBindingsGraphResult, type GenerateBindingsOptions, type InvokeContractOptions, type InvokeTarget, type LoadConfigOptions, type NetworkConfig, type NetworkStatus, type ProjectStatus, type ResolvedContract, type ResolvedNetwork, type RunCommandResult, STELLAR_CLI_LAST_TESTED_VERSION, STELLAR_CLI_MIN_VERSION, type SkippedContract, type TemplateManifest, TemplateManifestSchema, WELL_KNOWN_NETWORKS, buildContract, buildDependencyGraph, checkBinary, checkStellarCliVersion, collectProjectStatus, createInitialArtifacts, createProjectFromTemplate, defineConfig, deployContract, deployContractGraph, evaluateBindingFreshness, evaluateBindingsFreshness, evaluateStellarCliCompatibility, generateBindings, generateBindingsGraph, invokeContract, isTransientTestnetSmokeFailure, loadConfig, parseContractId, parseInvokeTarget, parseStellarCliVersion, readArtifacts, readBindingMarker, resolveContract, resolveDeployArgs, resolveDeployOrder, resolveNetwork, runCommand, updateArtifact, validateSourceShape, writeArtifacts, writeBindingMarker };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { C as CaatingaArtifacts, a as ContractArtifact, b as CaatingaErrorCodeVa
 export { d as CaatingaArtifactsSchema, e as CaatingaErrorCode, f as formatCaatingaError, t as toCaatingaError } from './browser-Cq4ZofIq.js';
 import { z } from 'zod';
 
-declare const CAATINGA_CORE_VERSION = "2.1.0";
+declare const CAATINGA_CORE_VERSION = "2.2.0";
 
 declare const ContractConfigSchema: z.ZodObject<{
     path: z.ZodString;
@@ -144,6 +144,78 @@ declare function updateArtifact(artifacts: CaatingaArtifacts, networkName: strin
     dependencyGraph?: Record<string, string[]>;
 }): CaatingaArtifacts;
 
+declare const BINDING_MARKER_FILENAME = ".caatinga-bindings.json";
+declare const BindingMarkerSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    contractId: z.ZodString;
+    wasmHash: z.ZodString;
+    network: z.ZodString;
+    generatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    contractId: string;
+    wasmHash: string;
+    version: 1;
+    network: string;
+    generatedAt: string;
+}, {
+    contractId: string;
+    wasmHash: string;
+    version: 1;
+    network: string;
+    generatedAt: string;
+}>;
+type BindingMarker = z.infer<typeof BindingMarkerSchema>;
+declare function writeBindingMarker(outputDir: string, marker: BindingMarker): Promise<void>;
+/** Returns null when the marker is absent or unreadable — freshness degrades, never throws. */
+declare function readBindingMarker(outputDir: string): Promise<BindingMarker | null>;
+
+type BindingFreshnessStatus = "fresh" | "stale" | "missing" | "unknown";
+type BindingFreshness = {
+    contractName: string;
+    status: BindingFreshnessStatus;
+    outputDir: string;
+    marker: BindingMarker | null;
+    reason?: string;
+};
+type EvaluateBindingFreshnessOptions = {
+    config: CaatingaConfig;
+    artifacts: CaatingaArtifacts;
+    networkName: string;
+    contractName: string;
+    cwd?: string;
+};
+declare function evaluateBindingFreshness(options: EvaluateBindingFreshnessOptions): Promise<BindingFreshness>;
+declare function evaluateBindingsFreshness(options: {
+    config: CaatingaConfig;
+    artifacts: CaatingaArtifacts;
+    networkName: string;
+    cwd?: string;
+}): Promise<BindingFreshness[]>;
+
+type ContractStatusEntry = {
+    name: string;
+    deployed: boolean;
+    contractId?: string;
+    wasmHash?: string;
+    deployedAt?: string;
+    dependencies: string[];
+    bindings: BindingFreshness;
+};
+type NetworkStatus = {
+    network: string;
+    contracts: ContractStatusEntry[];
+};
+type ProjectStatus = {
+    project: string;
+    networks: NetworkStatus[];
+};
+type CollectProjectStatusOptions = {
+    config: CaatingaConfig;
+    networkName?: string;
+    cwd?: string;
+};
+declare function collectProjectStatus(options: CollectProjectStatusOptions): Promise<ProjectStatus>;
+
 declare const WELL_KNOWN_NETWORKS: Record<string, NetworkConfig>;
 
 type ResolvedNetwork = {
@@ -327,6 +399,13 @@ declare function generateBindings(options: GenerateBindingsOptions): Promise<{
     outputDir: string;
     importPath: string;
     legacyStubRemoved: boolean;
+    marker: {
+        contractId: string;
+        wasmHash: string;
+        version: 1;
+        network: string;
+        generatedAt: string;
+    };
     output: string;
 }>;
 
@@ -337,6 +416,7 @@ type GenerateBindingsGraphResult = {
 declare function generateBindingsGraph(options: {
     config: CaatingaConfig;
     contractName?: string;
+    contractNames?: string[];
     networkName?: string;
     cwd?: string;
 }): Promise<GenerateBindingsGraphResult>;
@@ -479,4 +559,4 @@ type TemplateManifest = z.infer<typeof TemplateManifestSchema>;
 
 declare function isTransientTestnetSmokeFailure(logText: string): boolean;
 
-export { type BuildContractOptions, CAATINGA_CORE_VERSION, CaatingaArtifacts, type CaatingaConfig, CaatingaConfigSchema, CaatingaError, type CheckStellarCliVersionOptions, type CompatibilityReport, type CompatibilityStatus, type CompatibilityWarning, type CompatibilityWarningCode, ContractArtifact, type ContractConfig, type CreateInitialArtifactsOptions, type CreateProjectFromTemplateOptions, type DeployArgValue, type DeployContractGraphResult, type DeployContractOptions, type EvaluateStellarCliCompatibilityInput, type GenerateBindingsGraphResult, type GenerateBindingsOptions, type InvokeContractOptions, type InvokeTarget, type LoadConfigOptions, type NetworkConfig, type ResolvedContract, type ResolvedNetwork, type RunCommandResult, STELLAR_CLI_LAST_TESTED_VERSION, STELLAR_CLI_MIN_VERSION, type SkippedContract, type TemplateManifest, TemplateManifestSchema, WELL_KNOWN_NETWORKS, buildContract, buildDependencyGraph, checkBinary, checkStellarCliVersion, createInitialArtifacts, createProjectFromTemplate, defineConfig, deployContract, deployContractGraph, evaluateStellarCliCompatibility, generateBindings, generateBindingsGraph, invokeContract, isTransientTestnetSmokeFailure, loadConfig, parseContractId, parseInvokeTarget, parseStellarCliVersion, readArtifacts, resolveContract, resolveDeployArgs, resolveDeployOrder, resolveNetwork, runCommand, updateArtifact, validateSourceShape, writeArtifacts };
+export { BINDING_MARKER_FILENAME, type BindingFreshness, type BindingFreshnessStatus, type BindingMarker, BindingMarkerSchema, type BuildContractOptions, CAATINGA_CORE_VERSION, CaatingaArtifacts, type CaatingaConfig, CaatingaConfigSchema, CaatingaError, type CheckStellarCliVersionOptions, type CollectProjectStatusOptions, type CompatibilityReport, type CompatibilityStatus, type CompatibilityWarning, type CompatibilityWarningCode, ContractArtifact, type ContractConfig, type ContractStatusEntry, type CreateInitialArtifactsOptions, type CreateProjectFromTemplateOptions, type DeployArgValue, type DeployContractGraphResult, type DeployContractOptions, type EvaluateBindingFreshnessOptions, type EvaluateStellarCliCompatibilityInput, type GenerateBindingsGraphResult, type GenerateBindingsOptions, type InvokeContractOptions, type InvokeTarget, type LoadConfigOptions, type NetworkConfig, type NetworkStatus, type ProjectStatus, type ResolvedContract, type ResolvedNetwork, type RunCommandResult, STELLAR_CLI_LAST_TESTED_VERSION, STELLAR_CLI_MIN_VERSION, type SkippedContract, type TemplateManifest, TemplateManifestSchema, WELL_KNOWN_NETWORKS, buildContract, buildDependencyGraph, checkBinary, checkStellarCliVersion, collectProjectStatus, createInitialArtifacts, createProjectFromTemplate, defineConfig, deployContract, deployContractGraph, evaluateBindingFreshness, evaluateBindingsFreshness, evaluateStellarCliCompatibility, generateBindings, generateBindingsGraph, invokeContract, isTransientTestnetSmokeFailure, loadConfig, parseContractId, parseInvokeTarget, parseStellarCliVersion, readArtifacts, readBindingMarker, resolveContract, resolveDeployArgs, resolveDeployOrder, resolveNetwork, runCommand, updateArtifact, validateSourceShape, writeArtifacts, writeBindingMarker };

package/dist/index.js

@@ -105,7 +105,7 @@ function formatCause(cause) {
 }
 
 // src/version.ts
-var CAATINGA_CORE_VERSION = "2.1.0";
+var CAATINGA_CORE_VERSION = "2.2.0";
 
 // src/config/config.schema.ts
 import { z } from "zod";
@@ -270,18 +270,6 @@ function updateArtifact(artifacts, networkName, contractName, contractArtifact,
   };
 }
 
-// src/networks/networks.ts
-var WELL_KNOWN_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"
-  }
-};
-
 // src/networks/resolve-network.ts
 function resolveNetwork(config, networkName) {
   const name = networkName ?? config.defaultNetwork;
@@ -296,6 +284,174 @@ function resolveNetwork(config, networkName) {
   return { name, config: network };
 }
 
+// src/bindings/binding-freshness.ts
+import { readdir } from "fs/promises";
+import path5 from "path";
+
+// src/bindings/binding-marker.ts
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import path4 from "path";
+import { z as z5 } from "zod";
+var BINDING_MARKER_FILENAME = ".caatinga-bindings.json";
+var BindingMarkerSchema = z5.object({
+  version: z5.literal(1),
+  contractId: z5.string().min(1),
+  wasmHash: z5.string().min(1),
+  network: z5.string().min(1),
+  generatedAt: z5.string().datetime()
+});
+async function writeBindingMarker(outputDir, marker) {
+  const markerPath = path4.join(outputDir, BINDING_MARKER_FILENAME);
+  await writeFile2(markerPath, `${JSON.stringify(marker, null, 2)}
+`, "utf8");
+}
+async function readBindingMarker(outputDir) {
+  const markerPath = path4.join(outputDir, BINDING_MARKER_FILENAME);
+  let raw;
+  try {
+    raw = await readFile2(markerPath, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return BindingMarkerSchema.parse(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+// src/bindings/binding-freshness.ts
+async function listGeneratedEntries(outputDir) {
+  try {
+    const entries = await readdir(outputDir);
+    return entries.filter((entry) => entry !== BINDING_MARKER_FILENAME);
+  } catch {
+    return null;
+  }
+}
+async function evaluateBindingFreshness(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const outputDir = path5.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  const contractArtifact = options.artifacts.networks[options.networkName]?.contracts[options.contractName];
+  if (!contractArtifact) {
+    return {
+      contractName: options.contractName,
+      status: "missing",
+      outputDir,
+      marker: null,
+      reason: `not deployed on "${options.networkName}"`
+    };
+  }
+  const generatedEntries = await listGeneratedEntries(outputDir);
+  if (generatedEntries === null || generatedEntries.length === 0) {
+    return {
+      contractName: options.contractName,
+      status: "missing",
+      outputDir,
+      marker: null,
+      reason: "no generated bindings found"
+    };
+  }
+  const marker = await readBindingMarker(outputDir);
+  if (!marker) {
+    return {
+      contractName: options.contractName,
+      status: "unknown",
+      outputDir,
+      marker: null,
+      reason: "bindings exist but have no provenance marker \u2014 rerun caatinga generate to record it"
+    };
+  }
+  if (marker.contractId !== contractArtifact.contractId) {
+    return {
+      contractName: options.contractName,
+      status: "stale",
+      outputDir,
+      marker,
+      reason: "contractId changed since last generate"
+    };
+  }
+  if (marker.wasmHash !== contractArtifact.wasmHash) {
+    return {
+      contractName: options.contractName,
+      status: "stale",
+      outputDir,
+      marker,
+      reason: "wasmHash changed since last generate"
+    };
+  }
+  return {
+    contractName: options.contractName,
+    status: "fresh",
+    outputDir,
+    marker
+  };
+}
+async function evaluateBindingsFreshness(options) {
+  const contractNames = Object.keys(
+    options.artifacts.networks[options.networkName]?.contracts ?? {}
+  );
+  const results = [];
+  for (const contractName of contractNames) {
+    results.push(await evaluateBindingFreshness({ ...options, contractName }));
+  }
+  return results;
+}
+
+// src/artifacts/project-status.ts
+async function collectProjectStatus(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const artifacts = await readArtifacts(cwd);
+  let networkNames;
+  if (options.networkName) {
+    networkNames = [resolveNetwork(options.config, options.networkName).name];
+  } else {
+    const fromArtifacts = Object.keys(artifacts.networks);
+    const fallback = options.config.defaultNetwork ?? "testnet";
+    networkNames = fromArtifacts.length > 0 ? fromArtifacts : [fallback];
+    if (!networkNames.includes(fallback) && options.config.networks[fallback]) {
+      networkNames.push(fallback);
+    }
+  }
+  const networks = [];
+  for (const networkName of networkNames) {
+    const contracts = [];
+    for (const name of Object.keys(options.config.contracts)) {
+      const artifact = artifacts.networks[networkName]?.contracts[name];
+      const bindings = await evaluateBindingFreshness({
+        config: options.config,
+        artifacts,
+        networkName,
+        contractName: name,
+        cwd
+      });
+      contracts.push({
+        name,
+        deployed: Boolean(artifact),
+        contractId: artifact?.contractId,
+        wasmHash: artifact?.wasmHash,
+        deployedAt: artifact?.deployedAt,
+        dependencies: artifact?.dependencies ?? options.config.contracts[name].dependsOn ?? [],
+        bindings
+      });
+    }
+    networks.push({ network: networkName, contracts });
+  }
+  return { project: options.config.project, networks };
+}
+
+// src/networks/networks.ts
+var WELL_KNOWN_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"
+  }
+};
+
 // src/shell/run-command.ts
 import { execa } from "execa";
 
@@ -617,7 +773,7 @@ function validateSourceShape(source) {
 }
 
 // src/contracts/resolve-contract.ts
-import path4 from "path";
+import path6 from "path";
 function resolveContract(config, contractName, cwd = process.cwd()) {
   const contract = config.contracts[contractName];
   if (!contract) {
@@ -630,15 +786,15 @@ function resolveContract(config, contractName, cwd = process.cwd()) {
   return {
     name: contractName,
     config: contract,
-    sourcePath: path4.resolve(cwd, contract.path),
-    wasmPath: path4.resolve(cwd, contract.wasm)
+    sourcePath: path6.resolve(cwd, contract.path),
+    wasmPath: path6.resolve(cwd, contract.wasm)
   };
 }
 
 // src/contracts/wasm.ts
 import { createHash } from "crypto";
-import { access as access2, readdir, readFile as readFile2, stat } from "fs/promises";
-import path5 from "path";
+import { access as access2, readdir as readdir2, readFile as readFile3, stat } from "fs/promises";
+import path7 from "path";
 var LEGACY_RUST_WASM_TARGET = "wasm32-unknown-unknown";
 var CURRENT_RUST_WASM_TARGET = "wasm32v1-none";
 function toCurrentWasmTargetPath(wasmPath) {
@@ -661,8 +817,8 @@ function wasmNotFoundError(configuredWasmPath, options) {
   );
 }
 function toConfigRelativeWasmPath(absoluteWasmPath) {
-  const relative = path5.relative(process.cwd(), absoluteWasmPath);
-  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(path5.sep).join("/")}`;
+  const relative = path7.relative(process.cwd(), absoluteWasmPath);
+  return relative.startsWith("..") ? absoluteWasmPath : `./${relative.split(path7.sep).join("/")}`;
 }
 async function resolveWasmArtifactPath(configuredWasmPath) {
   try {
@@ -682,7 +838,7 @@ async function resolveWasmArtifactPath(configuredWasmPath) {
   }
 }
 async function hashWasm(wasmPath) {
-  const bytes = await readFile2(wasmPath);
+  const bytes = await readFile3(wasmPath);
   return createHash("sha256").update(bytes).digest("hex");
 }
 async function getNewestMtimeInDirectory(directory) {
@@ -693,9 +849,9 @@ async function getNewestMtimeInDirectory(directory) {
   }
   let newest = 0;
   async function walk(dir) {
-    const entries = await readdir(dir, { withFileTypes: true });
+    const entries = await readdir2(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const entryPath = path5.join(dir, entry.name);
+      const entryPath = path7.join(dir, entry.name);
       if (entry.isDirectory()) {
         await walk(entryPath);
         continue;
@@ -711,7 +867,7 @@ async function getNewestMtimeInDirectory(directory) {
   return newest > 0 ? newest : void 0;
 }
 async function isWasmOlderThanSources(input) {
-  const srcDir = path5.join(input.contractPath, "src");
+  const srcDir = path7.join(input.contractPath, "src");
   const newestSourceMtime = await getNewestMtimeInDirectory(srcDir);
   if (newestSourceMtime === void 0) {
     return false;
@@ -784,7 +940,7 @@ async function buildContract(options) {
 }
 
 // src/contracts/deploy-contract.ts
-import path6 from "path";
+import path8 from "path";
 
 // src/contracts/dependency-graph.ts
 function buildDependencyGraph(contracts) {
@@ -885,7 +1041,7 @@ async function deployContract(options) {
       contract: contractWithWasm,
       network,
       contractId: existing.contractId,
-      artifactsPath: path6.resolve(cwd, "caatinga.artifacts.json"),
+      artifactsPath: path8.resolve(cwd, "caatinga.artifacts.json"),
       output: "",
       skipped: true,
       staleWasmWarning
@@ -1162,13 +1318,13 @@ async function deployContractGraph(options) {
 
 // src/contracts/generate-bindings.ts
 import { access as access3, mkdir as mkdir2, unlink } from "fs/promises";
-import path7 from "path";
+import path9 from "path";
 function toBindingImportPath(bindingsOutput, contractName) {
-  const normalized = bindingsOutput.replace(/^\.\//, "").split(path7.sep).join("/");
-  return `./${path7.posix.join(normalized, contractName, "src", "index.js")}`;
+  const normalized = bindingsOutput.replace(/^\.\//, "").split(path9.sep).join("/");
+  return `./${path9.posix.join(normalized, contractName, "src", "index.js")}`;
 }
 async function removeLegacyBindingStub(cwd, bindingsOutput, contractName) {
-  const legacyPath = path7.resolve(cwd, bindingsOutput, `${contractName}.ts`);
+  const legacyPath = path9.resolve(cwd, bindingsOutput, `${contractName}.ts`);
   try {
     await access3(legacyPath);
     await unlink(legacyPath);
@@ -1190,7 +1346,7 @@ async function generateBindings(options) {
     );
   }
   await checkBinary("stellar", "Install Stellar CLI before running caatinga generate.");
-  const outputDir = path7.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
+  const outputDir = path9.resolve(cwd, options.config.frontend.bindingsOutput, options.contractName);
   await mkdir2(outputDir, { recursive: true });
   const result = await runCommand("stellar", [
     "contract",
@@ -1211,12 +1367,21 @@ async function generateBindings(options) {
     options.config.frontend.bindingsOutput,
     options.contractName
   );
+  const marker = {
+    version: 1,
+    contractId: contractArtifact.contractId,
+    wasmHash: contractArtifact.wasmHash,
+    network: network.name,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeBindingMarker(outputDir, marker);
   return {
     contractName: options.contractName,
     network,
     outputDir,
     importPath: toBindingImportPath(options.config.frontend.bindingsOutput, options.contractName),
     legacyStubRemoved,
+    marker,
     output: result.all || result.stdout
   };
 }
@@ -1228,6 +1393,8 @@ async function generateBindingsGraph(options) {
   let targets;
   if (options.contractName) {
     targets = [options.contractName];
+  } else if (options.contractNames && options.contractNames.length > 0) {
+    targets = options.contractNames;
   } else {
     const artifacts = await readArtifacts(cwd);
     targets = Object.keys(artifacts.networks[network.name]?.contracts ?? {});
@@ -1325,33 +1492,33 @@ ${error.hint ?? ""}`)) {
 }
 
 // src/templates/create-project-from-template.ts
-import { cp, mkdir as mkdir3, readFile as readFile3, readdir as readdir2, stat as stat2, writeFile as writeFile2 } from "fs/promises";
-import path8 from "path";
-import { z as z6 } from "zod";
+import { cp, mkdir as mkdir3, readFile as readFile4, readdir as readdir3, stat as stat2, writeFile as writeFile3 } from "fs/promises";
+import path10 from "path";
+import { z as z7 } from "zod";
 
 // src/templates/template-manifest.schema.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 import semver3 from "semver";
 var CURRENT_TEMPLATE_VERSION = 1;
-var TemplateManifestSchema = z5.object({
-  name: z5.string().min(1),
-  version: z5.string().min(1),
-  description: z5.string().optional(),
-  caatinga: z5.object({
-    compatibleCore: z5.string().min(1),
-    templateVersion: z5.number().int().positive()
+var TemplateManifestSchema = z6.object({
+  name: z6.string().min(1),
+  version: z6.string().min(1),
+  description: z6.string().optional(),
+  caatinga: z6.object({
+    compatibleCore: z6.string().min(1),
+    templateVersion: z6.number().int().positive()
   }),
-  frontend: z5.object({
-    framework: z5.enum(["vite-react", "next", "astro"]),
-    packageManager: z5.enum(["npm", "pnpm", "yarn", "bun"]).default("npm")
+  frontend: z6.object({
+    framework: z6.enum(["vite-react", "next", "astro"]),
+    packageManager: z6.enum(["npm", "pnpm", "yarn", "bun"]).default("npm")
   }),
-  contracts: z5.object({
-    path: z5.string(),
-    default: z5.string().optional()
+  contracts: z6.object({
+    path: z6.string(),
+    default: z6.string().optional()
   }),
-  files: z5.object({
-    config: z5.string().default("caatinga.config.ts"),
-    artifacts: z5.string().default("caatinga.artifacts.json")
+  files: z6.object({
+    config: z6.string().default("caatinga.config.ts"),
+    artifacts: z6.string().default("caatinga.artifacts.json")
   })
 });
 function defaultCompatibleCoreRange(coreVersion = CAATINGA_CORE_VERSION) {
@@ -1402,8 +1569,8 @@ var TEMPLATE_COPY_EXCLUDED_DIRS = /* @__PURE__ */ new Set([
   ".git"
 ]);
 async function createProjectFromTemplate(options) {
-  const targetDir = path8.resolve(options.targetDir);
-  const templateDir = path8.resolve(options.templateDir);
+  const targetDir = path10.resolve(options.targetDir);
+  const templateDir = path10.resolve(options.templateDir);
   try {
     await stat2(templateDir);
   } catch {
@@ -1438,9 +1605,9 @@ async function ensureArtifacts(targetDir, projectName) {
   }
 }
 async function readTemplateManifest(templateDir) {
-  const manifestPath = path8.join(templateDir, "caatinga.template.json");
+  const manifestPath = path10.join(templateDir, "caatinga.template.json");
   try {
-    const rawManifest = await readFile3(manifestPath, "utf8");
+    const rawManifest = await readFile4(manifestPath, "utf8");
     const manifest = TemplateManifestSchema.parse(JSON.parse(rawManifest));
     const compatibilityIssue = getTemplateCompatibilityIssue(manifest);
     if (compatibilityIssue) {
@@ -1462,7 +1629,7 @@ async function readTemplateManifest(templateDir) {
     if (error instanceof CaatingaError) {
       throw error;
     }
-    if (error instanceof SyntaxError || error instanceof z6.ZodError) {
+    if (error instanceof SyntaxError || error instanceof z7.ZodError) {
       throw new CaatingaError(
         "Template manifest is invalid.",
         CaatingaErrorCode.INVALID_TEMPLATE_MANIFEST,
@@ -1473,9 +1640,9 @@ async function readTemplateManifest(templateDir) {
   }
 }
 async function replaceTemplateVariables(dir, projectName) {
-  const entries = await readdir2(dir);
+  const entries = await readdir3(dir);
   await Promise.all(entries.map(async (entry) => {
-    const entryPath = path8.join(dir, entry);
+    const entryPath = path10.join(dir, entry);
     const entryStat = await stat2(entryPath);
     if (entryStat.isDirectory()) {
       await replaceTemplateVariables(entryPath, projectName);
@@ -1484,16 +1651,16 @@ async function replaceTemplateVariables(dir, projectName) {
     if (!isTextTemplateFile(entryPath)) {
       return;
     }
-    const content = await readFile3(entryPath, "utf8");
-    await writeFile2(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
+    const content = await readFile4(entryPath, "utf8");
+    await writeFile3(entryPath, content.replaceAll("__PROJECT_NAME__", projectName), "utf8");
   }));
 }
 function shouldCopyTemplateEntry(templateDir, source) {
-  const relativePath = path8.relative(templateDir, source);
+  const relativePath = path10.relative(templateDir, source);
   if (!relativePath || relativePath === ".") {
     return true;
   }
-  return !relativePath.split(path8.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
+  return !relativePath.split(path10.sep).some((segment) => TEMPLATE_COPY_EXCLUDED_DIRS.has(segment));
 }
 function isTextTemplateFile(filePath) {
   return [
@@ -1505,7 +1672,7 @@ function isTextTemplateFile(filePath) {
     ".tsx",
     ".css",
     ".html"
-  ].includes(path8.extname(filePath));
+  ].includes(path10.extname(filePath));
 }
 
 // src/ci/is-transient-testnet-smoke-failure.ts
@@ -1529,6 +1696,8 @@ function isTransientTestnetSmokeFailure(logText) {
   return TRANSIENT_PATTERN.test(logText);
 }
 export {
+  BINDING_MARKER_FILENAME,
+  BindingMarkerSchema,
   CAATINGA_CORE_VERSION,
   CaatingaArtifactsSchema,
   CaatingaConfigSchema,
@@ -1542,11 +1711,14 @@ export {
   buildDependencyGraph,
   checkBinary,
   checkStellarCliVersion,
+  collectProjectStatus,
   createInitialArtifacts,
   createProjectFromTemplate,
   defineConfig,
   deployContract,
   deployContractGraph,
+  evaluateBindingFreshness,
+  evaluateBindingsFreshness,
   evaluateStellarCliCompatibility,
   formatCaatingaError,
   generateBindings,
@@ -1558,6 +1730,7 @@ export {
   parseInvokeTarget,
   parseStellarCliVersion,
   readArtifacts,
+  readBindingMarker,
   resolveContract,
   resolveDeployArgs,
   resolveDeployOrder,
@@ -1566,5 +1739,6 @@ export {
   toCaatingaError,
   updateArtifact,
   validateSourceShape,
-  writeArtifacts
+  writeArtifacts,
+  writeBindingMarker
 };

package/package.json

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