meridian-core 0.1.0 → 0.1.2

package/src/lib/errors.ts

@@ -1,42 +0,0 @@
-import pc from 'picocolors';
-import type { MeridianError } from '@meridian/core';
-
-/**
- * Check if a value is a structured MeridianError.
- *
- * @param value - Value to check
- * @returns True if the value matches the MeridianError shape
- */
-export function isMeridianError(value: unknown): value is MeridianError {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'layer' in value &&
-    'code' in value &&
-    'hint' in value
-  );
-}
-
-/**
- * Print a MeridianError to stderr and exit the process with code 1.
- *
- * @param error - Structured MeridianError to report
- */
-export function failWithMeridianError(error: MeridianError): never {
-  console.error(pc.red(pc.bold(`✖ [${error.layer}] ${error.code}`)));
-  console.error(pc.red(error.error));
-  console.error(pc.dim(`hint: ${error.hint}`));
-  process.exit(1);
-}
-
-/**
- * Print a generic error to stderr and exit the process with code 1.
- *
- * @param err - Error or unknown thrown value
- */
-export function failWithError(err: unknown): never {
-  const message = err instanceof Error ? err.message : String(err);
-  console.error(pc.red(pc.bold('✖ Error')));
-  console.error(pc.red(message));
-  process.exit(1);
-}

package/src/lib/input.test.ts

@@ -1,38 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { writeFile, mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { resolveTxInput } from './input.js';
-
-describe('resolveTxInput', () => {
-  it('returns the trimmed positional argument when provided', async () => {
-    const result = await resolveTxInput('  AAAA-fake-xdr  ', undefined);
-    expect(result).toBe('AAAA-fake-xdr');
-  });
-
-  it('reads and trims XDR from a file when --file is provided', async () => {
-    const dir = await mkdtemp(join(tmpdir(), 'meridian-cli-'));
-    const filePath = join(dir, 'tx.xdr');
-    await writeFile(filePath, '  file-based-xdr\n');
-
-    try {
-      const result = await resolveTxInput(undefined, filePath);
-      expect(result).toBe('file-based-xdr');
-    } finally {
-      await rm(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('prefers --file over the positional argument', async () => {
-    const dir = await mkdtemp(join(tmpdir(), 'meridian-cli-'));
-    const filePath = join(dir, 'tx.xdr');
-    await writeFile(filePath, 'from-file');
-
-    try {
-      const result = await resolveTxInput('from-arg', filePath);
-      expect(result).toBe('from-file');
-    } finally {
-      await rm(dir, { recursive: true, force: true });
-    }
-  });
-});

package/src/lib/input.ts

@@ -1,43 +0,0 @@
-import { readFile } from 'node:fs/promises';
-
-/**
- * Read all data from stdin as a UTF-8 string.
- *
- * @returns Trimmed stdin contents
- */
-async function readStdin(): Promise<string> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(Buffer.from(chunk));
-  }
-  return Buffer.concat(chunks).toString('utf-8').trim();
-}
-
-/**
- * Resolve the transaction XDR from a positional argument, a file path, or stdin.
- * Precedence: --file > positional arg > stdin.
- *
- * @param txArg - Positional tx argument, if provided
- * @param filePath - Path to a file containing the base64 XDR, if provided
- * @returns Trimmed base64-encoded transaction XDR
- * @throws If no XDR could be resolved from any source
- */
-export async function resolveTxInput(txArg?: string, filePath?: string): Promise<string> {
-  if (filePath) {
-    const contents = await readFile(filePath, 'utf-8');
-    return contents.trim();
-  }
-
-  if (txArg && txArg.trim().length > 0) {
-    return txArg.trim();
-  }
-
-  if (!process.stdin.isTTY) {
-    const fromStdin = await readStdin();
-    if (fromStdin.length > 0) return fromStdin;
-  }
-
-  throw new Error(
-    'No transaction XDR provided. Pass it as an argument, via --file <path>, or pipe it over stdin.',
-  );
-}

package/src/lib/manifest.test.ts

@@ -1,60 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { writeFile, mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { loadManifest } from './manifest.js';
-
-describe('loadManifest', () => {
-  it('returns undefined when no path is given', async () => {
-    const result = await loadManifest(undefined);
-    expect(result).toBeUndefined();
-  });
-
-  it('parses a valid ecosystem manifest file', async () => {
-    const dir = await mkdtemp(join(tmpdir(), 'meridian-cli-'));
-    const filePath = join(dir, 'manifest.json');
-    const manifest = {
-      name: 'test-ecosystem',
-      version: '1.0.0',
-      contracts: [{ name: 'foo', address: 'CFOO', network: 'testnet' }],
-    };
-    await writeFile(filePath, JSON.stringify(manifest));
-
-    try {
-      const result = await loadManifest(filePath);
-      expect(result).toEqual(manifest);
-    } finally {
-      await rm(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('throws for a missing file', async () => {
-    await expect(loadManifest('/nonexistent/manifest.json')).rejects.toThrow(
-      /Failed to read ecosystem manifest/,
-    );
-  });
-
-  it('throws for invalid JSON', async () => {
-    const dir = await mkdtemp(join(tmpdir(), 'meridian-cli-'));
-    const filePath = join(dir, 'manifest.json');
-    await writeFile(filePath, '{ not valid json');
-
-    try {
-      await expect(loadManifest(filePath)).rejects.toThrow(/not valid JSON/);
-    } finally {
-      await rm(dir, { recursive: true, force: true });
-    }
-  });
-
-  it('throws when contracts field is missing', async () => {
-    const dir = await mkdtemp(join(tmpdir(), 'meridian-cli-'));
-    const filePath = join(dir, 'manifest.json');
-    await writeFile(filePath, JSON.stringify({ name: 'x', version: '1.0.0' }));
-
-    try {
-      await expect(loadManifest(filePath)).rejects.toThrow(/must be an object with a "contracts"/);
-    } finally {
-      await rm(dir, { recursive: true, force: true });
-    }
-  });
-});

package/src/lib/manifest.ts

@@ -1,41 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import type { EcosystemManifest } from '@meridian/core';
-
-/**
- * Load and parse an ecosystem manifest JSON file.
- *
- * @param filePath - Path to the manifest JSON file
- * @returns Parsed EcosystemManifest, or undefined if no path was given
- * @throws If the file cannot be read or does not contain valid JSON
- */
-export async function loadManifest(filePath?: string): Promise<EcosystemManifest | undefined> {
-  if (!filePath) return undefined;
-
-  let raw: string;
-  try {
-    raw = await readFile(filePath, 'utf-8');
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to read ecosystem manifest at ${filePath}: ${message}`);
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`Ecosystem manifest at ${filePath} is not valid JSON: ${message}`);
-  }
-
-  if (
-    typeof parsed !== 'object' ||
-    parsed === null ||
-    !Array.isArray((parsed as Record<string, unknown>).contracts)
-  ) {
-    throw new Error(
-      `Ecosystem manifest at ${filePath} must be an object with a "contracts" array.`,
-    );
-  }
-
-  return parsed as EcosystemManifest;
-}

package/src/lib/options.test.ts

@@ -1,27 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { parseNetwork, parseThreshold } from './options.js';
-
-describe('parseNetwork', () => {
-  it('accepts mainnet and testnet', () => {
-    expect(parseNetwork('mainnet')).toBe('mainnet');
-    expect(parseNetwork('testnet')).toBe('testnet');
-  });
-
-  it('rejects invalid networks', () => {
-    expect(() => parseNetwork('devnet')).toThrow();
-  });
-});
-
-describe('parseThreshold', () => {
-  it('accepts numbers within 0 and 1', () => {
-    expect(parseThreshold('0')).toBe(0);
-    expect(parseThreshold('0.75')).toBe(0.75);
-    expect(parseThreshold('1')).toBe(1);
-  });
-
-  it('rejects out-of-range and non-numeric values', () => {
-    expect(() => parseThreshold('1.5')).toThrow();
-    expect(() => parseThreshold('-0.1')).toThrow();
-    expect(() => parseThreshold('abc')).toThrow();
-  });
-});

package/src/lib/options.ts

@@ -1,47 +0,0 @@
-import { Command, InvalidArgumentError } from 'commander';
-import type { Network } from '@meridian/core';
-
-/**
- * Parse and validate a --network option value.
- *
- * @param value - Raw CLI argument
- * @returns Validated Network
- * @throws InvalidArgumentError if the value is not "mainnet" or "testnet"
- */
-export function parseNetwork(value: string): Network {
-  if (value !== 'mainnet' && value !== 'testnet') {
-    throw new InvalidArgumentError('Network must be "mainnet" or "testnet".');
-  }
-  return value;
-}
-
-/**
- * Parse and validate a --confidence-threshold option value.
- *
- * @param value - Raw CLI argument
- * @returns Parsed float between 0 and 1
- * @throws InvalidArgumentError if the value is not a number in range
- */
-export function parseThreshold(value: string): number {
-  const parsed = Number.parseFloat(value);
-  if (Number.isNaN(parsed) || parsed < 0 || parsed > 1) {
-    throw new InvalidArgumentError('Confidence threshold must be a number between 0 and 1.');
-  }
-  return parsed;
-}
-
-/**
- * Attach the options shared by every layer command (network, RPC, input, output).
- *
- * @param command - Commander command to extend
- * @returns The same command, for chaining
- */
-export function withCommonOptions(command: Command): Command {
-  return command
-    .argument('[tx]', 'Base64-encoded transaction XDR')
-    .option('-n, --network <network>', 'Stellar network (mainnet | testnet)', parseNetwork, 'testnet')
-    .option('--rpc-url <url>', 'Override the Soroban RPC endpoint (else read from env)')
-    .option('-f, --file <path>', 'Read the transaction XDR from a file instead of an argument')
-    .option('-e, --ecosystem <path>', 'Path to an ecosystem manifest JSON file')
-    .option('--json', 'Print raw JSON instead of a formatted report');
-}

package/src/lib/output.ts

@@ -1,180 +0,0 @@
-import pc from 'picocolors';
-import type {
-  AnalyzeResponse,
-  FieldResult,
-  GravityResult,
-  TraceResult,
-  Verdict,
-} from '@meridian/core';
-
-/**
- * Print any value as pretty-printed JSON.
- *
- * @param value - Value to serialize
- */
-export function printJson(value: unknown): void {
-  console.log(JSON.stringify(value, null, 2));
-}
-
-/**
- * Colorize a verdict badge.
- *
- * @param verdict - MERIDIAN verdict
- * @returns Colorized verdict string
- */
-function verdictBadge(verdict: Verdict): string {
-  switch (verdict) {
-    case 'CLEAR':
-      return pc.bgGreen(pc.black(' CLEAR '));
-    case 'WARN':
-      return pc.bgYellow(pc.black(' WARN '));
-    case 'ABORT':
-      return pc.bgRed(pc.white(pc.bold(' ABORT ')));
-    default:
-      return verdict;
-  }
-}
-
-/**
- * Print a section header.
- *
- * @param title - Section title
- */
-function section(title: string): void {
-  console.log('');
-  console.log(pc.bold(pc.cyan(`── ${title} `.padEnd(48, '─'))));
-}
-
-/**
- * Print a labeled key/value line.
- *
- * @param label - Field label
- * @param value - Field value
- */
-function field(label: string, value: unknown): void {
-  console.log(`  ${pc.dim(label + ':')} ${value}`);
-}
-
-/**
- * Print a TraceResult in human-readable form.
- *
- * @param trace - TRACE layer result
- */
-export function printTrace(trace: TraceResult): void {
-  section('TRACE');
-  field('success', trace.success ? pc.green('true') : pc.red('false'));
-  if (trace.staleness_warning) {
-    field('staleness_warning', pc.yellow('true'));
-  }
-  if (trace.failure_point) {
-    const fp = trace.failure_point;
-    console.log(`  ${pc.red('failure_point')}:`);
-    field('  step_index', fp.step_index);
-    if (fp.contract_id) field('  contract_id', fp.contract_id);
-    if (fp.function_name) field('  function_name', fp.function_name);
-    field('  error_code', fp.error_code);
-    field('  root_cause', fp.root_cause);
-  }
-  field('execution_path', `${trace.execution_path.length} step(s)`);
-  field('auth_entries', `${trace.auth_entries.length} entrie(s)`);
-  field(
-    'fee_estimate',
-    `total=${trace.fee_estimate.total_fee} base=${trace.fee_estimate.classic_base_fee} min_resource=${trace.fee_estimate.min_resource_fee}`,
-  );
-  field(
-    'resource_usage',
-    `cpu=${trace.resource_usage.cpu_instructions} mem=${trace.resource_usage.memory_bytes}b read=${trace.resource_usage.read_bytes}b write=${trace.resource_usage.write_bytes}b`,
-  );
-}
-
-/**
- * Print a FieldResult in human-readable form.
- *
- * @param result - FIELD layer result
- */
-export function printField(result: FieldResult): void {
-  section('FIELD');
-  field('contracts_mapped', result.contracts_mapped);
-  field('manifest_coverage', `${Math.round(result.manifest_coverage * 100)}%`);
-  if (result.ttl_warnings.length > 0) {
-    console.log(`  ${pc.yellow('ttl_warnings')}:`);
-    for (const warning of result.ttl_warnings) {
-      console.log(
-        `    - ${warning.contract_id} (${warning.ledger_key}) ttl_remaining=${warning.ttl_remaining} [${warning.severity}]`,
-      );
-    }
-  }
-  if (result.dependency_graph.length > 0) {
-    console.log(`  ${pc.dim('dependency_graph')}:`);
-    for (const node of result.dependency_graph) {
-      const label = node.name ? `${node.name} (${node.address})` : node.address;
-      const deps = node.dependencies.length > 0 ? ` → ${node.dependencies.join(', ')}` : '';
-      console.log(`    - ${label}${deps}`);
-    }
-  }
-}
-
-/**
- * Print a GravityResult in human-readable form.
- *
- * @param result - GRAVITY layer result
- */
-export function printGravity(result: GravityResult): void {
-  section('GRAVITY');
-  field('blast_radius', result.blast_radius);
-  field('total_affected_users', result.total_affected_users);
-  field('recovery', result.recovery);
-  if (result.critical.length > 0) field('critical', pc.red(result.critical.join(', ')));
-  if (result.warning.length > 0) field('warning', pc.yellow(result.warning.join(', ')));
-  if (result.monitor.length > 0) field('monitor', pc.blue(result.monitor.join(', ')));
-  if (result.safe.length > 0) field('safe', pc.green(result.safe.join(', ')));
-
-  if (result.affected_contracts.length > 0) {
-    console.log(`  ${pc.dim('affected_contracts')}:`);
-    for (const contract of result.affected_contracts) {
-      const label = contract.name ? `${contract.name} (${contract.address})` : contract.address;
-      console.log(`    - [${contract.impact}] ${label} — ${contract.reason}`);
-    }
-  }
-}
-
-/**
- * Print a full AnalyzeResponse in human-readable form.
- *
- * @param response - Full analysis response including brief
- */
-export function printAnalysis(response: AnalyzeResponse): void {
-  console.log('');
-  console.log(`${pc.bold('MERIDIAN')} v${response.version}  ${verdictBadge(response.verdict)}  confidence=${response.confidence}`);
-
-  printTrace(response.trace);
-  printField(response.field);
-  printGravity(response.gravity);
-
-  if (response.fix_sequence && response.fix_sequence.length > 0) {
-    section('FIX SEQUENCE');
-    for (const step of response.fix_sequence) {
-      console.log(
-        `  ${pc.bold(String(step.order) + '.')} ${step.operation} — ${step.description} ${pc.dim(`(~${step.estimated_cost_stroops} stroops, ~${step.estimated_time_minutes}min)`)}`,
-      );
-    }
-  }
-
-  if (response.warnings && response.warnings.length > 0) {
-    section('WARNINGS');
-    for (const warning of response.warnings) {
-      console.log(`  ${pc.yellow('⚠')} ${warning}`);
-    }
-  }
-
-  section('BRIEF');
-  console.log(response.brief);
-
-  section('META');
-  field('analyzed_at', response.meta.analyzed_at);
-  field('network', response.meta.network);
-  field('ledger_sequence', response.meta.ledger_sequence);
-  field('simulation_stale', response.meta.simulation_stale);
-  field('processing_ms', response.meta.processing_ms);
-  console.log('');
-}

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"],
-  "references": [{ "path": "../core" }, { "path": "../ai" }]
-}

package/vitest.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-  },
-});