@caatinga/core 2.0.2 → 2.2.0

package/dist/index.js

@@ -27,6 +27,7 @@ var CaatingaErrorCode = {
   DEPLOY_ARG_PLACEHOLDER_UNRESOLVED: "CAATINGA_DEPLOY_ARG_PLACEHOLDER_UNRESOLVED",
   BINDING_CLIENT_NOT_FOUND: "CAATINGA_BINDING_CLIENT_NOT_FOUND",
   BINDING_METHOD_NOT_FOUND: "CAATINGA_BINDING_METHOD_NOT_FOUND",
+  PLACEHOLDER_BINDING: "CAATINGA_PLACEHOLDER_BINDING",
   XDR_BUILD_FAILED: "CAATINGA_XDR_BUILD_FAILED",
   XDR_PREPARE_FAILED: "CAATINGA_XDR_PREPARE_FAILED",
   XDR_SIGN_FAILED: "CAATINGA_XDR_SIGN_FAILED",
@@ -71,8 +72,40 @@ function toCaatingaError(error) {
   return new CaatingaError("An unexpected error occurred.", CaatingaErrorCode.UNEXPECTED_ERROR);
 }
 
+// src/errors/format-caatinga-error.ts
+function formatCaatingaError(error) {
+  if (error instanceof CaatingaError) {
+    const lines = [`[${error.code}] ${error.message}`];
+    if (error.hint) {
+      lines.push("", error.hint);
+    }
+    const detail = formatCause(error.cause);
+    if (detail) {
+      lines.push("", `Details: ${detail}`);
+    }
+    return lines.join("\n");
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+function formatCause(cause) {
+  if (cause === void 0 || cause === null) {
+    return "";
+  }
+  if (cause instanceof Error) {
+    return cause.message;
+  }
+  if (typeof cause === "string") {
+    return cause;
+  }
+  try {
+    return JSON.stringify(cause);
+  } catch {
+    return String(cause);
+  }
+}
+
 // src/version.ts
-var CAATINGA_CORE_VERSION = "2.0.2";
+var CAATINGA_CORE_VERSION = "2.2.0";
 
 // src/config/config.schema.ts
 import { z } from "zod";
@@ -237,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;
@@ -263,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";
 
@@ -584,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) {
@@ -597,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) {
@@ -628,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 {
@@ -649,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) {
@@ -660,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;
@@ -678,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;
@@ -751,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) {
@@ -852,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
@@ -1129,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);
@@ -1157,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",
@@ -1178,16 +1367,59 @@ 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
   };
 }
 
+// src/contracts/generate-bindings-graph.ts
+async function generateBindingsGraph(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const network = resolveNetwork(options.config, options.networkName);
+  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 ?? {});
+    if (targets.length === 0) {
+      throw new CaatingaError(
+        `No deployed contracts found on "${network.name}".`,
+        CaatingaErrorCode.ARTIFACT_NOT_FOUND,
+        "Run caatinga deploy before generating bindings, or pass a contract name."
+      );
+    }
+  }
+  const results = [];
+  for (const contractName of targets) {
+    results.push(
+      await generateBindings({
+        config: options.config,
+        contractName,
+        networkName: network.name,
+        cwd
+      })
+    );
+  }
+  return { network, results };
+}
+
 // src/contracts/invoke-contract.ts
 var INVOKE_SIGNING_FAILURE_REGEX = /xdr processing error: xdr value invalid/i;
 function parseInvokeTarget(target) {
@@ -1260,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) {
@@ -1337,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 {
@@ -1373,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) {
@@ -1397,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,
@@ -1408,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);
@@ -1419,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 [
@@ -1440,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
@@ -1464,6 +1696,8 @@ function isTransientTestnetSmokeFailure(logText) {
   return TRANSIENT_PATTERN.test(logText);
 }
 export {
+  BINDING_MARKER_FILENAME,
+  BindingMarkerSchema,
   CAATINGA_CORE_VERSION,
   CaatingaArtifactsSchema,
   CaatingaConfigSchema,
@@ -1477,13 +1711,18 @@ export {
   buildDependencyGraph,
   checkBinary,
   checkStellarCliVersion,
+  collectProjectStatus,
   createInitialArtifacts,
   createProjectFromTemplate,
   defineConfig,
   deployContract,
   deployContractGraph,
+  evaluateBindingFreshness,
+  evaluateBindingsFreshness,
   evaluateStellarCliCompatibility,
+  formatCaatingaError,
   generateBindings,
+  generateBindingsGraph,
   invokeContract,
   isTransientTestnetSmokeFailure,
   loadConfig,
@@ -1491,6 +1730,7 @@ export {
   parseInvokeTarget,
   parseStellarCliVersion,
   readArtifacts,
+  readBindingMarker,
   resolveContract,
   resolveDeployArgs,
   resolveDeployOrder,
@@ -1499,5 +1739,6 @@ export {
   toCaatingaError,
   updateArtifact,
   validateSourceShape,
-  writeArtifacts
+  writeArtifacts,
+  writeBindingMarker
 };

package/package.json

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