meridian-core 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,120 @@
+# meridian-core
+
+**MERIDIAN command-line interface — pre-execution intelligence for Stellar developers, from your terminal.**
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/armlynobinguar/meridian-core/blob/main/LICENSE)
+[![npm](https://img.shields.io/npm/v/meridian-core?label=meridian-core)](https://www.npmjs.com/package/meridian-core)
+
+MERIDIAN simulates a Stellar transaction end-to-end, maps every contract it touches downstream, scores what breaks if something goes wrong, and returns a plain-language GenAI risk brief — all before you submit.
+
+Full project docs, architecture, and the REST API live in the [monorepo README](https://github.com/armlynobinguar/meridian-core#readme). This package is the standalone `meridian` / `meridian-core` CLI.
+
+## Install
+
+```bash
+npm install -g meridian-core
+meridian-core --help
+```
+
+## Requirements
+
+- Node.js **>= 20**
+- A Soroban RPC endpoint for the network you're targeting (testnet/mainnet)
+- *(Optional)* An [Anthropic API key](https://console.anthropic.com/) for GenAI-synthesized briefs — falls back to a deterministic brief without one
+
+## Verdict States
+
+| Verdict | Meaning |
+|---|---|
+| 🟢 `CLEAR` | Safe to submit |
+| 🟡 `WARN`  | Submit with caution — review warnings |
+| 🔴 `ABORT` | Do not submit — critical failure predicted |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `meridian analyze [tx]` | Full pipeline: TRACE + FIELD + GRAVITY + BRIEF *(default command)* |
+| `meridian trace [tx]` | TRACE only — simulate and report the execution path |
+| `meridian field [tx]` | TRACE + FIELD — map the dependency graph touched by the transaction |
+| `meridian gravity [tx]` | TRACE + FIELD + GRAVITY — score the blast radius |
+| `meridian version` | Print CLI and engine version |
+| `meridian --help` / `meridian <command> --help` | Show detailed help |
+
+`tx` is the base64-encoded transaction XDR. It can be passed as an argument, via `--file`, or piped over stdin.
+
+## Options
+
+| Flag | Applies to | Description |
+|---|---|---|
+| `-n, --network <network>` | all | `mainnet` or `testnet` (default: `testnet`) |
+| `--rpc-url <url>` | all | Override the Soroban RPC endpoint instead of reading it from env |
+| `-f, --file <path>` | all | Read the transaction XDR from a file instead of an argument |
+| `-e, --ecosystem <path>` | `field`, `gravity`, `analyze` | Path to an ecosystem manifest JSON file |
+| `--json` | all | Print raw JSON instead of a formatted report |
+| `--skip-field` | `analyze` | Skip the FIELD dependency-mapping layer |
+| `--skip-gravity` | `analyze` | Skip the GRAVITY blast-radius layer |
+| `--confidence-threshold <n>` | `analyze` | Minimum confidence (0–1) required for a `CLEAR` verdict |
+| `--no-brief` | `analyze` | Skip GenAI BRIEF synthesis (structured layers only) |
+| `--api-key <key>` | `analyze` | Anthropic API key for BRIEF synthesis (else read from env) |
+
+## Examples
+
+```bash
+# Full analysis (default command — "analyze" can be omitted)
+meridian analyze <base64-xdr> --network testnet
+
+# Read the XDR from a file
+meridian analyze --file tx.xdr --network mainnet
+
+# Pipe it in via stdin
+cat tx.xdr | meridian analyze --network testnet --json
+
+# Override the RPC endpoint without setting env vars
+meridian analyze <base64-xdr> --network testnet --rpc-url https://soroban-testnet.stellar.org
+
+# Score blast radius against a known ecosystem manifest
+meridian gravity <base64-xdr> --ecosystem manifest.json --network testnet
+
+# Fast structured-only analysis (no GenAI call)
+meridian analyze <base64-xdr> --network testnet --no-brief
+
+# TRACE only, fastest path
+meridian trace <base64-xdr> --network testnet
+
+# Check installed versions
+meridian version
+```
+
+## Ecosystem Manifest
+
+An optional JSON file describing known contracts in your ecosystem, used by `field`, `gravity`, and `analyze` to enrich dependency mapping, blast-radius scoring, and affected-user counts:
+
+```json
+{
+  "name": "my-ecosystem",
+  "version": "1.0.0",
+  "contracts": [
+    {
+      "name": "token-vault",
+      "address": "CABC...XYZ",
+      "network": "testnet",
+      "dependencies": ["CDEF...UVW"],
+      "active_users": 4200,
+      "criticality": "HIGH"
+    }
+  ]
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `STELLAR_RPC_TESTNET` | For testnet use | Soroban RPC endpoint for testnet |
+| `STELLAR_RPC_MAINNET` | For mainnet use | Soroban RPC endpoint for mainnet |
+| `ANTHROPIC_API_KEY` | No | Claude API key for BRIEF synthesis — falls back to a deterministic brief if unset |
+
+## License
+
+MIT — see the [monorepo repository](https://github.com/armlynobinguar/meridian-core) for full source and license details.

package/dist/index.js

@@ -3,6 +3,18 @@
 // src/cli.ts
 import { Command as Command7 } from "commander";
 
+// src/version.ts
+import { createRequire } from "node:module";
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var CLI_VERSION = version;
+
+// src/commands/analyze.ts
+import { Command as Command2 } from "commander";
+
+// ../core/src/analyze.ts
+import { createRequire as createRequire2 } from "node:module";
+
 // ../core/src/logger.ts
 var Logger = class {
   level;
@@ -260,60 +272,14 @@ function createMeridianError(error, code, hint, layer) {
 }
 
 // ../core/src/trace/parser.ts
-import { TransactionBuilder, FeeBumpTransaction } from "@stellar/stellar-sdk";
+import {
+  Address,
+  FeeBumpTransaction,
+  TransactionBuilder,
+  humanizeEvents,
+  xdr
+} from "@stellar/stellar-sdk";
 var STALENESS_THRESHOLD = 5;
-function extractFootprint(simData) {
-  const footprintContracts = /* @__PURE__ */ new Set();
-  const readOnly = [];
-  const readWrite = [];
-  if (!simData || !("transactionData" in simData)) {
-    return {
-      ledgerSequence: 0,
-      latestLedger: 0,
-      footprintContracts: [],
-      readOnly: [],
-      readWrite: []
-    };
-  }
-  const txData = simData.transactionData;
-  const resources = txData?.resources;
-  const footprint = resources?.footprint;
-  if (footprint?.readOnly) {
-    for (const key of footprint.readOnly) {
-      const keyStr = ledgerKeyToString(key);
-      readOnly.push(keyStr);
-      const contractId = extractContractFromLedgerKey(keyStr);
-      if (contractId) footprintContracts.add(contractId);
-    }
-  }
-  if (footprint?.readWrite) {
-    for (const key of footprint.readWrite) {
-      const keyStr = ledgerKeyToString(key);
-      readWrite.push(keyStr);
-      const contractId = extractContractFromLedgerKey(keyStr);
-      if (contractId) footprintContracts.add(contractId);
-    }
-  }
-  return {
-    ledgerSequence: 0,
-    latestLedger: 0,
-    footprintContracts: [...footprintContracts],
-    readOnly,
-    readWrite
-  };
-}
-function ledgerKeyToString(key) {
-  if (typeof key === "string") return key;
-  if (key && typeof key === "object" && "contractData" in key) {
-    const contractData = key.contractData;
-    return contractData?.contract ?? JSON.stringify(key);
-  }
-  return JSON.stringify(key);
-}
-function extractContractFromLedgerKey(keyStr) {
-  const match = keyStr.match(/C[A-Z0-9]{55}/);
-  return match?.[0];
-}
 function parseExecutionPath(txXdr) {
   const steps = [];
   let index = 0;
@@ -365,16 +331,16 @@ function parseOperation(op, index) {
 }
 function parseAuthEntries(events) {
   const entries = [];
-  for (const event of events) {
-    if (event.type === "contract" && event.topic) {
-      const topicStr = event.topic.map((t) => String(t)).join(":");
-      if (topicStr.includes("require_auth") || topicStr.includes("auth")) {
-        entries.push({
-          address: event.contractId?.() ?? "unknown",
-          contract_id: event.contractId?.(),
-          credentials: event.topic.map((t) => String(t))
-        });
-      }
+  const humanized = humanizeEvents(events);
+  for (const event of humanized) {
+    const topicStrs = event.topics.map((t) => String(t));
+    const topicStr = topicStrs.join(":");
+    if (topicStr.includes("require_auth") || topicStr.includes("auth")) {
+      entries.push({
+        address: event.contractId ?? "unknown",
+        contract_id: event.contractId,
+        credentials: topicStrs
+      });
     }
   }
   return entries;
@@ -399,16 +365,16 @@ function computeFeeEstimate(txXdr, minResourceFee) {
     total_fee: classicBaseFee + resourceFee
   };
 }
-function extractResourceUsage(simData) {
-  if (!simData || !("transactionData" in simData)) {
+function extractResourceUsage(sorobanData) {
+  if (!sorobanData) {
     return { cpu_instructions: 0, memory_bytes: 0, read_bytes: 0, write_bytes: 0 };
   }
-  const resources = simData.transactionData?.resources;
+  const resources = sorobanData.build().resources();
   return {
-    cpu_instructions: Number(resources?.instructions ?? 0),
+    cpu_instructions: resources.instructions(),
     memory_bytes: 0,
-    read_bytes: Number(resources?.readBytes ?? 0),
-    write_bytes: Number(resources?.writeBytes ?? 0)
+    read_bytes: resources.readBytes(),
+    write_bytes: resources.writeBytes()
   };
 }
 function parseFailurePoint(error, executionPath) {
@@ -437,7 +403,6 @@ function parseFailurePoint(error, executionPath) {
 }
 function parseSimulationResult(raw, txXdr) {
   const executionPath = parseExecutionPath(txXdr);
-  const footprint = extractFootprint(raw.transactionData);
   const stalenessDelta = raw.latestLedger - raw.simulationLedger;
   const isStale = stalenessDelta > STALENESS_THRESHOLD;
   if (!raw.success && raw.error) {
@@ -447,23 +412,22 @@ function parseSimulationResult(raw, txXdr) {
       execution_path: executionPath,
       auth_entries: parseAuthEntries(raw.events),
       fee_estimate: computeFeeEstimate(txXdr, raw.minResourceFee),
-      resource_usage: extractResourceUsage(raw.transactionData),
+      resource_usage: extractResourceUsage(raw.sorobanData),
       staleness_warning: isStale
     };
   }
-  void footprint;
   return {
     success: true,
     execution_path: executionPath,
     auth_entries: parseAuthEntries(raw.events),
     fee_estimate: computeFeeEstimate(txXdr, raw.minResourceFee),
-    resource_usage: extractResourceUsage(raw.transactionData),
+    resource_usage: extractResourceUsage(raw.sorobanData),
     staleness_warning: isStale
   };
 }
 
 // ../core/src/trace/rpc.ts
-import { rpc as rpc2, TransactionBuilder as TransactionBuilder2, Networks } from "@stellar/stellar-sdk";
+import { rpc, TransactionBuilder as TransactionBuilder2, Networks } from "@stellar/stellar-sdk";
 var DEFAULT_TIMEOUT_MS = 3e4;
 function resolveRpcUrl(network) {
   const envKey = network === "mainnet" ? "STELLAR_RPC_MAINNET" : "STELLAR_RPC_TESTNET";
@@ -485,7 +449,7 @@ async function withTimeout(promise, timeoutMs, label) {
   }
 }
 async function simulateTransaction(txXdr, rpcUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
-  const server = new rpc2.Server(rpcUrl, { allowHttp: rpcUrl.startsWith("http://") });
+  const server = new rpc.Server(rpcUrl, { allowHttp: rpcUrl.startsWith("http://") });
   try {
     logger.debug("simulateTransaction:start", { rpcUrl });
     const latestLedgerResponse = await withTimeout(
@@ -503,25 +467,23 @@ async function simulateTransaction(txXdr, rpcUrl, timeoutMs = DEFAULT_TIMEOUT_MS
       timeoutMs,
       "simulateTransaction"
     );
-    if (rpc2.Api.isSimulationError(simResponse)) {
+    if (rpc.Api.isSimulationError(simResponse)) {
       return {
         success: false,
         latestLedger: latestLedgerResponse.sequence,
         simulationLedger: latestLedgerResponse.sequence,
         minResourceFee: "0",
-        events: [],
-        error: simResponse.error,
-        transactionData: simResponse
+        events: simResponse.events,
+        error: simResponse.error
       };
     }
-    const successResponse = simResponse;
     return {
       success: true,
       latestLedger: latestLedgerResponse.sequence,
       simulationLedger: latestLedgerResponse.sequence,
-      minResourceFee: successResponse.minResourceFee,
-      events: successResponse.events ?? [],
-      transactionData: successResponse
+      minResourceFee: simResponse.minResourceFee,
+      events: simResponse.events ?? [],
+      sorobanData: simResponse.transactionData
     };
   } catch (err) {
     logger.error("simulateTransaction:failed", {
@@ -550,7 +512,15 @@ async function trace(txXdr, options) {
 }
 
 // ../core/src/analyze.ts
-var MERIDIAN_VERSION = "0.1.0";
+function resolveEngineVersion() {
+  if (true) {
+    return "0.1.1";
+  }
+  const require3 = createRequire2(import.meta.url);
+  const { version: version2 } = require3("../package.json");
+  return version2;
+}
+var MERIDIAN_VERSION = resolveEngineVersion();
 var DEFAULT_CONFIDENCE_THRESHOLD = 0.75;
 function computeVerdict(traceSuccess, blastRadius, confidence, threshold, isStale) {
   if (!traceSuccess) {
@@ -688,9 +658,6 @@ function emptyGravityResult() {
   };
 }
 
-// src/commands/analyze.ts
-import { Command as Command2 } from "commander";
-
 // ../ai/src/brief.ts
 import Anthropic from "@anthropic-ai/sdk";
 var BRIEF_MODEL = "claude-sonnet-4-6";
@@ -1206,12 +1173,12 @@ function gravityCommand() {
 // src/commands/version.ts
 import { Command as Command6 } from "commander";
 function versionCommand() {
-  return new Command6("version").description("Print MERIDIAN product and core engine version").option("--json", "Print raw JSON instead of a formatted report").action((options) => {
+  return new Command6("version").description("Print MERIDIAN CLI and core engine version").option("--json", "Print raw JSON instead of a formatted report").action((options) => {
     if (options.json) {
-      printJson({ product: "MERIDIAN", version: MERIDIAN_VERSION });
+      printJson({ product: "MERIDIAN", cli_version: CLI_VERSION, engine_version: MERIDIAN_VERSION });
       return;
     }
-    console.log(`MERIDIAN v${MERIDIAN_VERSION}`);
+    console.log(`meridian-core v${CLI_VERSION} (engine v${MERIDIAN_VERSION})`);
   });
 }
 
@@ -1219,7 +1186,7 @@ function versionCommand() {
 function buildProgram() {
   const program = new Command7("meridian").description(
     "MERIDIAN \u2014 pre-execution intelligence for Stellar developers.\nKnow what crosses before it does."
-  ).version(MERIDIAN_VERSION, "-v, --version", "Print the MERIDIAN version").addHelpText(
+  ).version(CLI_VERSION, "-v, --version", "Print the meridian-core CLI version").addHelpText(
     "after",
     `
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meridian-core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "MERIDIAN command-line interface — pre-execution intelligence from your terminal",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc --noEmit && esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --alias:@meridian/core=./src/internal/meridian-core.ts --alias:@meridian/ai=./src/internal/meridian-ai.ts --external:commander --external:picocolors --external:@stellar/stellar-sdk --external:@anthropic-ai/sdk && chmod +x dist/index.js",
+    "build": "tsc --noEmit && node scripts/build.mjs",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "test": "vitest run",
@@ -26,7 +26,7 @@
   },
   "devDependencies": {
     "@meridian/ai": "0.1.0",
-    "@meridian/core": "0.1.0",
+    "@meridian/core": "0.1.1",
     "esbuild": "^0.28.1",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",