stellar-contracts-kit 0.1.0

package/dist/cli/generate.js

@@ -0,0 +1,951 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { resolve, dirname, extname, basename, join } from 'path';
+import { createInterface } from 'readline';
+import { rpc, contract } from '@stellar/stellar-sdk';
+
+// src/network/config.ts
+var NETWORKS = {
+  mainnet: {
+    rpcUrl: "https://mainnet.stellar.validationcloud.io/v1/soroban/rpc",
+    networkPassphrase: "Public Global Stellar Network ; September 2015",
+    horizonUrl: "https://horizon.stellar.org"
+  },
+  testnet: {
+    rpcUrl: "https://soroban-testnet.stellar.org",
+    networkPassphrase: "Test SDF Network ; September 2015",
+    horizonUrl: "https://horizon-testnet.stellar.org"
+  },
+  futurenet: {
+    rpcUrl: "https://rpc-futurenet.stellar.org",
+    networkPassphrase: "Test SDF Future Network ; October 2022",
+    horizonUrl: "https://horizon-futurenet.stellar.org"
+  }
+};
+function resolveNetwork(network) {
+  if (typeof network === "string") {
+    return NETWORKS[network];
+  }
+  return network;
+}
+function createServer(network) {
+  return new rpc.Server(network.rpcUrl, { allowHttp: network.rpcUrl.startsWith("http://") });
+}
+
+// src/errors/index.ts
+var StellarContractError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "StellarContractError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+function makeError(code, message, cause) {
+  return new StellarContractError(code, message, cause);
+}
+function isContractKitError(err) {
+  return err instanceof StellarContractError;
+}
+
+// src/contract/spec.ts
+function validateContractId(id) {
+  if (!/^C[A-Z2-7]{55}$/.test(id)) {
+    throw makeError(
+      "INVALID_CONTRACT_ID",
+      `"${id}" is not a valid Soroban contract address. Expected a 56-character string starting with C (e.g. CABC...).`
+    );
+  }
+}
+async function fetchContractSpec(contractId, server, network) {
+  validateContractId(contractId);
+  let wasm;
+  try {
+    wasm = await server.getContractWasmByContractId(contractId);
+  } catch (err) {
+    throw makeError("CONTRACT_NOT_FOUND", `Contract ${contractId} not found or has no WASM`, err);
+  }
+  try {
+    const client = await contract.Client.fromWasm(wasm, {
+      contractId,
+      networkPassphrase: network.networkPassphrase,
+      rpcUrl: network.rpcUrl
+    });
+    return client.spec;
+  } catch (err) {
+    throw makeError("CONTRACT_SPEC_ERROR", `Failed to parse contract spec for ${contractId}`, err);
+  }
+}
+
+// src/cli/codegen.ts
+function placeholder(typeDef, lang = "ts") {
+  const name = typeDef.switch().name;
+  switch (name) {
+    case "scSpecTypeBool":
+      return "false";
+    case "scSpecTypeVoid":
+      return "undefined";
+    case "scSpecTypeU32":
+    case "scSpecTypeI32":
+      return "0";
+    case "scSpecTypeU64":
+    case "scSpecTypeI64":
+    case "scSpecTypeU128":
+    case "scSpecTypeI128":
+    case "scSpecTypeU256":
+    case "scSpecTypeI256":
+    case "scSpecTypeTimepoint":
+    case "scSpecTypeDuration":
+      return "0n";
+    case "scSpecTypeString":
+    case "scSpecTypeSymbol":
+      return "''";
+    case "scSpecTypeAddress":
+    case "scSpecTypeMuxedAddress":
+      return "'G...'";
+    case "scSpecTypeBytes":
+    case "scSpecTypeBytesN":
+      return "new Uint8Array()";
+    case "scSpecTypeOption":
+      return "null";
+    case "scSpecTypeVec":
+      return "[]";
+    case "scSpecTypeMap":
+      return "new Map()";
+    case "scSpecTypeTuple": {
+      const types = typeDef.tuple().valueTypes();
+      return `[${types.map((t) => placeholder(t, lang)).join(", ")}]`;
+    }
+    case "scSpecTypeUdt": {
+      const udtName = typeDef.udt().name().toString();
+      return lang === "ts" ? `{} as unknown as ${udtName}` : "{}";
+    }
+    default:
+      return "undefined";
+  }
+}
+function toTs(typeDef) {
+  const name = typeDef.switch().name;
+  switch (name) {
+    case "scSpecTypeBool":
+      return "boolean";
+    case "scSpecTypeVoid":
+      return "void";
+    case "scSpecTypeU32":
+    case "scSpecTypeI32":
+      return "number";
+    case "scSpecTypeU64":
+    case "scSpecTypeI64":
+    case "scSpecTypeU128":
+    case "scSpecTypeI128":
+    case "scSpecTypeU256":
+    case "scSpecTypeI256":
+    case "scSpecTypeTimepoint":
+    case "scSpecTypeDuration":
+      return "bigint";
+    case "scSpecTypeString":
+    case "scSpecTypeSymbol":
+      return "string";
+    case "scSpecTypeAddress":
+    case "scSpecTypeMuxedAddress":
+      return "string";
+    case "scSpecTypeBytes":
+    case "scSpecTypeBytesN":
+      return "Uint8Array";
+    case "scSpecTypeOption": {
+      const inner = toTs(typeDef.option().valueType());
+      return `${inner} | null`;
+    }
+    case "scSpecTypeResult": {
+      return toTs(typeDef.result().okType());
+    }
+    case "scSpecTypeVec": {
+      const inner = toTs(typeDef.vec().elementType());
+      return `Array<${inner}>`;
+    }
+    case "scSpecTypeMap": {
+      const k = toTs(typeDef.map().keyType());
+      const v = toTs(typeDef.map().valueType());
+      return `Map<${k}, ${v}>`;
+    }
+    case "scSpecTypeTuple": {
+      const types = typeDef.tuple().valueTypes().map(toTs);
+      return `[${types.join(", ")}]`;
+    }
+    case "scSpecTypeUdt": {
+      return typeDef.udt().name().toString();
+    }
+    default:
+      return "unknown";
+  }
+}
+function generateCustomTypes(entries) {
+  const out = [];
+  for (const entry of entries) {
+    const kind = entry.switch().name;
+    try {
+      if (kind === "scSpecEntryUdtStructV0") {
+        const s = entry.udtStructV0();
+        const fields = s.fields();
+        const isTuple = fields.length > 0 && fields.every((f) => /^\d+$/.test(f.name().toString()));
+        if (isTuple) {
+          const types = fields.map((f) => toTs(f.type()));
+          out.push(`export type ${s.name().toString()} = [${types.join(", ")}]`);
+        } else {
+          out.push(`export interface ${s.name().toString()} {`);
+          for (const f of fields) {
+            out.push(`  ${f.name().toString()}: ${toTs(f.type())}`);
+          }
+          out.push("}");
+        }
+        out.push("");
+      }
+      if (kind === "scSpecEntryUdtEnumV0" || kind === "scSpecEntryUdtErrorEnumV0") {
+        const e = kind === "scSpecEntryUdtEnumV0" ? entry.udtEnumV0() : entry.udtErrorEnumV0();
+        out.push(`export enum ${e.name().toString()} {`);
+        for (const c of e.cases()) {
+          out.push(`  ${c.name().toString()} = ${c.value()},`);
+        }
+        out.push("}");
+        out.push("");
+      }
+      if (kind === "scSpecEntryUdtUnionV0") {
+        const u = entry.udtUnionV0();
+        const caseTypes = u.cases().map((c) => {
+          const isVoid = c.switch().name === "scSpecUdtUnionCaseVoidV0";
+          const inner = isVoid ? c.voidV0() : c.tupleV0();
+          const tag = inner.name().toString();
+          if (isVoid) return `{ tag: '${tag}' }`;
+          const types = inner.type().map(toTs);
+          return types.length === 1 ? `{ tag: '${tag}'; value: ${types[0]} }` : `{ tag: '${tag}'; value: [${types.join(", ")}] }`;
+        });
+        out.push(`export type ${u.name().toString()} =`);
+        out.push(caseTypes.map((t) => `  | ${t}`).join("\n"));
+        out.push("");
+      }
+    } catch {
+    }
+  }
+  return out.join("\n");
+}
+function generateInterface(spec, interfaceName) {
+  const out = [];
+  out.push(`export interface ${interfaceName} {`);
+  for (const fn of spec.funcs()) {
+    try {
+      const methodName = fn.name().toString();
+      const inputs = fn.inputs();
+      const outputs = fn.outputs();
+      const returnType = outputs.length === 0 ? "void" : outputs.length === 1 ? toTs(outputs[0]) : `[${outputs.map(toTs).join(", ")}]`;
+      const argParts = inputs.map((i) => `${i.name().toString()}: ${toTs(i.type())}`);
+      const argsTuple = `[${argParts.join(", ")}]`;
+      out.push(`  ${methodName}: ContractMethodFn<${returnType}, ${argsTuple}>`);
+    } catch {
+    }
+  }
+  out.push("}");
+  return out.join("\n");
+}
+function generateExample(spec, contractId, interfaceName, importBasename, networkLabel, typesRelPath, aliasImport) {
+  const isPreset = ["testnet", "mainnet", "futurenet"].includes(networkLabel);
+  const networkInit = isPreset ? `{ network: '${networkLabel}' }` : `{ network: { rpcUrl: 'https://...', networkPassphrase: '...', horizonUrl: 'https://...' } }`;
+  const importPath = aliasImport ? `${aliasImport}.js` : `./${importBasename}.js`;
+  const importComment = !aliasImport ? typesRelPath ? `// Types file: ${typesRelPath}. Update the path below if using snippets elsewhere.` : `// Update the import path below to match your file's location relative to the types file.` : null;
+  const referencedUdts = /* @__PURE__ */ new Set();
+  for (const fn of spec.funcs()) {
+    try {
+      for (const i of fn.inputs()) {
+        if (i.type().switch().name === "scSpecTypeUdt") {
+          referencedUdts.add(i.type().udt().name().toString());
+        }
+      }
+    } catch {
+    }
+  }
+  const typeImports = [interfaceName, ...Array.from(referencedUdts).sort()].join(", ");
+  const lines = [
+    `// Auto-generated by stellar-contracts-kit`,
+    `// Example usage for ${interfaceName}`,
+    `// Contract : ${contractId}`,
+    `// Network  : ${networkLabel}`,
+    `// Adapt this file to your project. Re-run \`npx sck generate\` to refresh after a contract upgrade.`,
+    ``,
+    `import { StellarContractsKit } from 'stellar-contracts-kit'`,
+    ...importComment ? [importComment] : [],
+    `import type { ${typeImports} } from '${importPath}'`,
+    `import { CONTRACT_ID } from '${importPath}'`,
+    ``,
+    `const kit = new StellarContractsKit(${networkInit})`,
+    ``,
+    `// Connect wallet (opens picker modal if no wallet specified)`,
+    `const { address } = await kit.connect()`,
+    `console.log('Connected:', address)`,
+    ``,
+    `// Load the typed contract client`,
+    `const contract = await kit.contract<${interfaceName}>(CONTRACT_ID)`,
+    ``
+  ];
+  for (const fn of spec.funcs()) {
+    const methodName = fn.name().toString();
+    const inputs = fn.inputs();
+    const outputs = fn.outputs();
+    const isVoid = outputs.length === 0;
+    const hasParams = inputs.length > 0;
+    const returnType = isVoid ? "void" : outputs.length === 1 ? toTs(outputs[0]) : `[${outputs.map(toTs).join(", ")}]`;
+    const sig = `${methodName}(${inputs.map((i) => `${i.name().toString()}: ${toTs(i.type())}`).join(", ")}) -> ${returnType}`;
+    lines.push(`// ${sig}`);
+    const argLines = inputs.map((i) => {
+      const val = placeholder(i.type(), "ts");
+      return `  ${val},  // ${i.name().toString()}: ${toTs(i.type())}`;
+    });
+    const isLikelyRead = !hasParams && !isVoid;
+    if (isLikelyRead) {
+      lines.push(`const { result: ${methodName}Result } = await contract.${methodName}.read()`);
+      lines.push(`console.log('${methodName}:', ${methodName}Result)`);
+    } else if (isVoid && !hasParams) {
+      lines.push(`const { txHash: ${methodName}TxHash } = await contract.${methodName}.invoke()`);
+      lines.push(`console.log('${methodName} txHash:', ${methodName}TxHash)`);
+    } else if (isVoid) {
+      lines.push(`const { txHash: ${methodName}TxHash } = await contract.${methodName}.invoke(`);
+      lines.push(...argLines);
+      lines.push(`)`);
+      lines.push(`console.log('${methodName} txHash:', ${methodName}TxHash)`);
+    } else {
+      lines.push(`const { txHash: ${methodName}TxHash, result: ${methodName}Result } = await contract.${methodName}.invoke(`);
+      lines.push(...argLines);
+      lines.push(`)`);
+      lines.push(`console.log('${methodName} txHash:', ${methodName}TxHash, 'result:', ${methodName}Result)`);
+    }
+    lines.push(``);
+  }
+  return lines.join("\n");
+}
+function generateCustomTypesJs(entries) {
+  const out = [];
+  for (const entry of entries) {
+    const kind = entry.switch().name;
+    try {
+      if (kind === "scSpecEntryUdtStructV0") {
+        const s = entry.udtStructV0();
+        const fields = s.fields();
+        const isTuple = fields.length > 0 && fields.every((f) => /^\d+$/.test(f.name().toString()));
+        if (isTuple) {
+          const types = fields.map((f) => toTs(f.type())).join(", ");
+          out.push(`/** @typedef {[${types}]} ${s.name().toString()} */`);
+        } else {
+          const fieldStr = fields.map((f) => `${f.name().toString()}: ${toTs(f.type())}`).join(", ");
+          out.push(`/** @typedef {{ ${fieldStr} }} ${s.name().toString()} */`);
+        }
+        out.push("");
+      }
+      if (kind === "scSpecEntryUdtEnumV0" || kind === "scSpecEntryUdtErrorEnumV0") {
+        const e = kind === "scSpecEntryUdtEnumV0" ? entry.udtEnumV0() : entry.udtErrorEnumV0();
+        out.push(`export const ${e.name().toString()} = Object.freeze({`);
+        for (const c of e.cases()) {
+          out.push(`  ${c.name().toString()}: ${c.value()},`);
+        }
+        out.push(`})`);
+        out.push("");
+      }
+      if (kind === "scSpecEntryUdtUnionV0") {
+        const u = entry.udtUnionV0();
+        const caseTypes = u.cases().map((c) => {
+          const isVoid = c.switch().name === "scSpecUdtUnionCaseVoidV0";
+          const inner = isVoid ? c.voidV0() : c.tupleV0();
+          const tag = inner.name().toString();
+          if (isVoid) return `{ tag: '${tag}' }`;
+          const types = inner.type().map(toTs);
+          return types.length === 1 ? `{ tag: '${tag}', value: ${types[0]} }` : `{ tag: '${tag}', value: [${types.join(", ")}] }`;
+        });
+        out.push(`/** @typedef {${caseTypes.join(" | ")}} ${u.name().toString()} */`);
+        out.push("");
+      }
+    } catch {
+    }
+  }
+  return out.join("\n");
+}
+function generateInterfaceJs(spec, interfaceName) {
+  const lines = ["/**", ` * @typedef {Object} ${interfaceName}`];
+  for (const fn of spec.funcs()) {
+    try {
+      const methodName = fn.name().toString();
+      const inputs = fn.inputs();
+      const outputs = fn.outputs();
+      const returnType = outputs.length === 0 ? "void" : outputs.length === 1 ? toTs(outputs[0]) : `[${outputs.map(toTs).join(", ")}]`;
+      const argParts = inputs.map((i) => `${i.name().toString()}: ${toTs(i.type())}`);
+      const argsTuple = `[${argParts.join(", ")}]`;
+      lines.push(` * @property {import('stellar-contracts-kit').ContractMethodFn<${returnType}, ${argsTuple}>} ${methodName}`);
+    } catch {
+    }
+  }
+  lines.push(" */");
+  return lines.join("\n");
+}
+function generateOutputJs(spec, contractId, interfaceName, networkLabel) {
+  const entries = spec.entries;
+  const customTypes = generateCustomTypesJs(entries).trim();
+  const iface = generateInterfaceJs(spec, interfaceName);
+  const lines = [
+    `// Auto-generated by stellar-contracts-kit`,
+    `// Contract : ${contractId}`,
+    `// Network  : ${networkLabel}`,
+    `// Re-run \`npx sck generate\` to update after a contract upgrade.`,
+    ``
+  ];
+  if (customTypes) {
+    lines.push(`// Custom Types`);
+    lines.push(``);
+    lines.push(customTypes);
+    lines.push(``);
+  }
+  lines.push(`// Contract Interface`);
+  lines.push(``);
+  lines.push(iface);
+  lines.push(``);
+  lines.push(`export const CONTRACT_ID = '${contractId}'`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function generateExampleJs(spec, contractId, interfaceName, importBasename, networkLabel, typesRelPath, aliasImport) {
+  const isPreset = ["testnet", "mainnet", "futurenet"].includes(networkLabel);
+  const networkInit = isPreset ? `{ network: '${networkLabel}' }` : `{ network: { rpcUrl: 'https://...', networkPassphrase: '...', horizonUrl: 'https://...' } }`;
+  const importPath = aliasImport ? `${aliasImport}.js` : `./${importBasename}.js`;
+  const importComment = !aliasImport ? typesRelPath ? `// Types file: ${typesRelPath}. Update the path below if using snippets elsewhere.` : `// Update the import path below to match your file's location relative to the types file.` : null;
+  const lines = [
+    `// Auto-generated by stellar-contracts-kit`,
+    `// Example usage for ${interfaceName}`,
+    `// Contract : ${contractId}`,
+    `// Network  : ${networkLabel}`,
+    `// @ts-check`,
+    ``,
+    `import { StellarContractsKit } from 'stellar-contracts-kit'`,
+    ...importComment ? [importComment] : [],
+    `import { CONTRACT_ID } from '${importPath}'`,
+    ``,
+    `const kit = new StellarContractsKit(${networkInit})`,
+    ``,
+    `// Connect wallet (opens picker modal if no wallet specified)`,
+    `const { address } = await kit.connect()`,
+    `console.log('Connected:', address)`,
+    ``,
+    `// Load the contract client`,
+    `const contract = await kit.contract(CONTRACT_ID)`,
+    ``
+  ];
+  for (const fn of spec.funcs()) {
+    const methodName = fn.name().toString();
+    const inputs = fn.inputs();
+    const outputs = fn.outputs();
+    const isVoid = outputs.length === 0;
+    const hasParams = inputs.length > 0;
+    const returnType = isVoid ? "void" : outputs.length === 1 ? toTs(outputs[0]) : `[${outputs.map(toTs).join(", ")}]`;
+    lines.push(`// ${methodName}(${inputs.map((i) => `${i.name().toString()}: ${toTs(i.type())}`).join(", ")}) -> ${returnType}`);
+    const argLines = inputs.map((i) => `  ${placeholder(i.type(), "js")},  // ${i.name().toString()}: ${toTs(i.type())}`);
+    const isLikelyRead = !hasParams && !isVoid;
+    if (isLikelyRead) {
+      lines.push(`const { result: ${methodName}Result } = await contract.${methodName}.read()`);
+      lines.push(`console.log('${methodName}:', ${methodName}Result)`);
+    } else if (isVoid && !hasParams) {
+      lines.push(`const { txHash: ${methodName}TxHash } = await contract.${methodName}.invoke()`);
+      lines.push(`console.log('${methodName} txHash:', ${methodName}TxHash)`);
+    } else if (isVoid) {
+      lines.push(`const { txHash: ${methodName}TxHash } = await contract.${methodName}.invoke(`);
+      lines.push(...argLines);
+      lines.push(`)`);
+      lines.push(`console.log('${methodName} txHash:', ${methodName}TxHash)`);
+    } else {
+      lines.push(`const { txHash: ${methodName}TxHash, result: ${methodName}Result } = await contract.${methodName}.invoke(`);
+      lines.push(...argLines);
+      lines.push(`)`);
+      lines.push(`console.log('${methodName} txHash:', ${methodName}TxHash, 'result:', ${methodName}Result)`);
+    }
+    lines.push(``);
+  }
+  return lines.join("\n");
+}
+function generateOutput(spec, contractId, interfaceName, networkLabel) {
+  const entries = spec.entries;
+  const customTypes = generateCustomTypes(entries).trim();
+  const iface = generateInterface(spec, interfaceName);
+  const lines = [
+    `// Auto-generated by stellar-contracts-kit`,
+    `// Contract : ${contractId}`,
+    `// Network  : ${networkLabel}`,
+    `// Re-run \`npx sck generate\` to update after a contract upgrade.`,
+    ``,
+    `import type { ContractMethodFn } from 'stellar-contracts-kit'`,
+    ``
+  ];
+  if (customTypes) {
+    lines.push(`// Custom Types`);
+    lines.push(``);
+    lines.push(customTypes);
+    lines.push(``);
+  }
+  lines.push(`// Contract Interface`);
+  lines.push(``);
+  lines.push(iface);
+  lines.push(``);
+  lines.push(`export const CONTRACT_ID = '${contractId}' as const`);
+  lines.push(``);
+  return lines.join("\n");
+}
+
+// src/cli/generate.ts
+function deriveInterfaceName(outPath) {
+  const base = basename(outPath, extname(outPath));
+  return base.split(/[-_]/).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function nameToKebab(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function detectAliasImport(outPath, aliasHint) {
+  try {
+    const raw = readFileSync("tsconfig.json", "utf-8");
+    const stripped = raw.replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    const tsconfig = JSON.parse(stripped);
+    const paths = tsconfig?.compilerOptions?.paths ?? {};
+    const normalizedOut = outPath.replace(/^\.\//, "").replace(/\.ts$/, "");
+    for (const [pattern, targets] of Object.entries(paths)) {
+      if (!pattern.endsWith("/*")) continue;
+      const aliasPrefix = pattern.slice(0, -2);
+      if (aliasHint && aliasPrefix !== aliasHint) continue;
+      const target = targets[0];
+      if (!target?.endsWith("/*")) continue;
+      const targetPrefix = target.slice(0, -2).replace(/^\.\//, "");
+      if (normalizedOut.startsWith(targetPrefix + "/")) {
+        const rest = normalizedOut.slice(targetPrefix.length + 1);
+        return `${aliasPrefix}/${rest}`;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+var A = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  cyan: "\x1B[36m",
+  green: "\x1B[32m"
+};
+function promptText(label, defaultVal = "", validate) {
+  const hint = defaultVal ? ` [${defaultVal}]` : "";
+  return new Promise((resolve2) => {
+    function ask() {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      rl.question(`${label}${hint}: `, (input) => {
+        rl.close();
+        const value = input.trim() || defaultVal;
+        if (validate) {
+          const err = validate(value);
+          if (err) {
+            process.stderr.write(`  ${A.dim}${err}${A.reset}
+`);
+            ask();
+            return;
+          }
+        }
+        resolve2(value);
+      });
+    }
+    ask();
+  });
+}
+function promptEnter(message) {
+  return new Promise((resolve2) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(message, () => {
+      rl.close();
+      resolve2();
+    });
+  });
+}
+function promptSelect(label, options, defaultIdx = 0) {
+  return new Promise((resolve2) => {
+    let idx = defaultIdx;
+    const N = options.length;
+    const w = (s) => process.stderr.write(s);
+    function render(initial) {
+      if (!initial) w(`\x1B[${N}A`);
+      options.forEach((opt, i) => {
+        w("\x1B[2K\r");
+        w(i === idx ? `  ${A.cyan}>${A.reset} ${A.bold}${opt}${A.reset}
+` : `    ${A.dim}${opt}${A.reset}
+`);
+      });
+    }
+    w(`${label}
+`);
+    render(true);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    function onKey(key) {
+      if (key === "") {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        w("\nCancelled.\n");
+        process.exit(0);
+      }
+      if (key === "\x1B[A") {
+        idx = (idx - 1 + N) % N;
+        render(false);
+      }
+      if (key === "\x1B[B") {
+        idx = (idx + 1) % N;
+        render(false);
+      }
+      if (key === "\r") {
+        process.stdin.removeListener("data", onKey);
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        w(`\x1B[${N + 1}A\x1B[0J`);
+        w(`${label}: ${A.cyan}${options[idx]}${A.reset}
+`);
+        resolve2(options[idx]);
+      }
+    }
+    process.stdin.on("data", onKey);
+  });
+}
+function validateContractAddress(val) {
+  if (!val) return "Contract address is required";
+  if (!/^C[A-Z2-7]{55}$/.test(val)) return "Must be a 56-character Soroban address starting with C (uppercase, A-Z and 2-7 only)";
+  return null;
+}
+function validateContractName(val) {
+  if (!val) return null;
+  if (!/^[A-Za-z][A-Za-z0-9]*$/.test(val)) return "Must start with a letter and contain only letters and numbers (becomes a TypeScript interface name)";
+  return null;
+}
+async function promptNetwork() {
+  const networkChoice = await promptSelect("Network", ["testnet", "mainnet", "futurenet", "custom"]);
+  if (networkChoice === "custom") {
+    const rpcUrl = await promptText("RPC URL");
+    const passphrase = await promptText("Network passphrase");
+    return { rpcUrl, passphrase };
+  }
+  return { networkArg: networkChoice };
+}
+async function runInteractive() {
+  process.stderr.write(`
+`);
+  process.stderr.write(`\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557  \u2588\u2588\u2557
+`);
+  process.stderr.write(`\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551 \u2588\u2588\u2554\u255D
+`);
+  process.stderr.write(`\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551     \u2588\u2588\u2588\u2588\u2588\u2554\u255D 
+`);
+  process.stderr.write(`\u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551     \u2588\u2588\u2554\u2550\u2588\u2588\u2557 
+`);
+  process.stderr.write(`\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551  \u2588\u2588\u2557
+`);
+  process.stderr.write(`\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D
+`);
+  process.stderr.write(`${A.dim}stellar-contracts-kit  \u2022  Press Ctrl+C to cancel${A.reset}
+
+`);
+  const command = await promptSelect("Command", ["generate", "inspect"]);
+  if (command === "inspect") {
+    const contractId2 = await promptText("Contract address", "", validateContractAddress);
+    const { networkArg: networkArg2, rpcUrl: rpcUrl2, passphrase: passphrase2 } = await promptNetwork();
+    const opts2 = { contractId: contractId2 };
+    if (networkArg2) opts2.networkArg = networkArg2;
+    if (rpcUrl2) opts2.rpcUrl = rpcUrl2;
+    if (passphrase2) opts2.passphrase = passphrase2;
+    await runInspect(opts2);
+    return;
+  }
+  const contractId = await promptText("Contract address", "", validateContractAddress);
+  const rawNameInput = await promptText("Interface name", "", validateContractName);
+  const rawName = rawNameInput || "Contract";
+  const langChoice = await promptSelect("Language", ["TypeScript", "JavaScript"]);
+  const lang = langChoice === "JavaScript" ? "js" : "ts";
+  const outRaw = `./contracts/${nameToKebab(rawName)}.${lang}`;
+  const { networkArg, rpcUrl, passphrase } = await promptNetwork();
+  process.stderr.write(`
+${A.dim}`);
+  process.stderr.write(`  Contract  : ${contractId}
+`);
+  process.stderr.write(`  Network   : ${networkArg ?? "custom"}
+`);
+  process.stderr.write(`  Interface : ${rawName}
+`);
+  process.stderr.write(`  Language  : ${langChoice}
+`);
+  process.stderr.write(`  Output    : ${outRaw}
+`);
+  process.stderr.write(A.reset);
+  await promptEnter(`${A.dim}  Press Enter to generate, Ctrl+C to cancel${A.reset} `);
+  const opts = { contractId, lang, rawOut: outRaw, rawName };
+  if (networkArg) opts.networkArg = networkArg;
+  if (rpcUrl) opts.rpcUrl = rpcUrl;
+  if (passphrase) opts.passphrase = passphrase;
+  await runGenerate(opts);
+}
+async function runGenerate(opts) {
+  const { contractId, networkArg, rpcUrl, passphrase, rawName, aliasHint, lang } = opts;
+  const interfaceName = rawName ?? (opts.rawOut ? deriveInterfaceName(opts.rawOut) : "Contract");
+  const outPath = opts.rawOut ?? `./contracts/${nameToKebab(interfaceName)}.${lang}`;
+  if (!networkArg && !(rpcUrl && passphrase)) {
+    process.stderr.write("Error: --network or (--rpc-url + --passphrase) is required\n");
+    process.exit(1);
+  }
+  const network = rpcUrl && passphrase ? { rpcUrl, networkPassphrase: passphrase, horizonUrl: "" } : resolveNetwork(networkArg);
+  const server = createServer(network);
+  const networkLabel = networkArg ?? rpcUrl ?? "custom";
+  process.stderr.write(`
+Fetching spec for ${contractId} on ${networkLabel}...
+`);
+  let spec;
+  try {
+    spec = await fetchContractSpec(contractId, server, network);
+  } catch (err) {
+    if (isContractKitError(err)) {
+      process.stderr.write(`Error [${err.code}]: ${err.message}
+`);
+    } else {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+    }
+    process.exit(1);
+  }
+  process.stderr.write(`Generating types for interface "${interfaceName}"...
+`);
+  const absOut = resolve(outPath);
+  const dir = dirname(absOut);
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    process.stderr.write(`Error: could not create directory "${dir}": ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  const ext = extname(absOut);
+  const base = basename(absOut, ext);
+  const exampleExt = lang === "js" ? ".example.js" : ".example.ts";
+  const examplePath = join(dir, `${base}${exampleExt}`);
+  const aliasImport = detectAliasImport(outPath, aliasHint && aliasHint !== "true" ? aliasHint : void 0);
+  if (aliasImport) {
+    process.stderr.write(`Using path alias: ${aliasImport}.js
+`);
+  }
+  const output = lang === "js" ? generateOutputJs(spec, contractId, interfaceName, networkLabel) : generateOutput(spec, contractId, interfaceName, networkLabel);
+  const example = lang === "js" ? generateExampleJs(spec, contractId, interfaceName, base, networkLabel, outPath, aliasImport ?? void 0) : generateExample(spec, contractId, interfaceName, base, networkLabel, outPath, aliasImport ?? void 0);
+  try {
+    writeFileSync(absOut, output, "utf-8");
+    writeFileSync(examplePath, example, "utf-8");
+  } catch (err) {
+    process.stderr.write(`Error: could not write output file: ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
+  process.stderr.write(`${A.green}Done.${A.reset}
+  Types   -> ${absOut}
+  Example -> ${examplePath}
+`);
+}
+async function runInspect(opts) {
+  const { contractId, networkArg, rpcUrl, passphrase } = opts;
+  if (!networkArg && !(rpcUrl && passphrase)) {
+    process.stderr.write("Error: --network or (--rpc-url + --passphrase) is required\n");
+    process.exit(1);
+  }
+  const network = rpcUrl && passphrase ? { rpcUrl, networkPassphrase: passphrase, horizonUrl: "" } : resolveNetwork(networkArg);
+  const server = createServer(network);
+  const networkLabel = networkArg ?? rpcUrl ?? "custom";
+  process.stderr.write(`
+Fetching spec for ${contractId} on ${networkLabel}...
+`);
+  let spec;
+  try {
+    spec = await fetchContractSpec(contractId, server, network);
+  } catch (err) {
+    if (isContractKitError(err)) {
+      process.stderr.write(`Error [${err.code}]: ${err.message}
+`);
+    } else {
+      process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}
+`);
+    }
+    process.exit(1);
+  }
+  const entries = spec.entries;
+  const fns = spec.funcs();
+  const w = (s) => process.stdout.write(s);
+  const pad = (s, n) => s + " ".repeat(Math.max(0, n - s.length));
+  w(`
+`);
+  w(`${A.bold}Contract${A.reset} : ${contractId}
+`);
+  w(`${A.bold}Network ${A.reset} : ${networkLabel}
+`);
+  w(`
+${A.bold}${A.cyan}Functions (${fns.length})${A.reset}
+`);
+  for (const fn of fns) {
+    try {
+      const name = fn.name().toString();
+      const inputs = fn.inputs();
+      const outputs = fn.outputs();
+      const retType = outputs.length === 0 ? "void" : outputs.length === 1 ? toTs(outputs[0]) : `[${outputs.map(toTs).join(", ")}]`;
+      const params = inputs.map((i) => `${i.name().toString()}: ${toTs(i.type())}`).join(", ");
+      w(`  ${A.green}${name}${A.reset}(${A.dim}${params}${A.reset}) ${A.dim}->${A.reset} ${retType}
+`);
+    } catch {
+    }
+  }
+  const typeEntries = entries.filter((e) => {
+    const k = e.switch().name;
+    return k === "scSpecEntryUdtStructV0" || k === "scSpecEntryUdtEnumV0" || k === "scSpecEntryUdtErrorEnumV0" || k === "scSpecEntryUdtUnionV0";
+  });
+  if (typeEntries.length > 0) {
+    w(`
+${A.bold}${A.cyan}Custom Types (${typeEntries.length})${A.reset}
+`);
+    for (const entry of typeEntries) {
+      try {
+        const kind = entry.switch().name;
+        if (kind === "scSpecEntryUdtStructV0") {
+          const s = entry.udtStructV0();
+          const fields = s.fields();
+          const name = s.name().toString();
+          const isTuple = fields.length > 0 && fields.every((f) => /^\d+$/.test(f.name().toString()));
+          if (isTuple) {
+            const types = fields.map((f) => toTs(f.type())).join(", ");
+            w(`  ${A.dim}${pad("type", 6)}${A.reset} ${A.bold}${name}${A.reset} = [${types}]
+`);
+          } else {
+            const fieldStr = fields.map((f) => `${f.name().toString()}: ${toTs(f.type())}`).join(", ");
+            w(`  ${A.dim}${pad("struct", 6)}${A.reset} ${A.bold}${name}${A.reset} { ${fieldStr} }
+`);
+          }
+        }
+        if (kind === "scSpecEntryUdtEnumV0" || kind === "scSpecEntryUdtErrorEnumV0") {
+          const isErr = kind === "scSpecEntryUdtErrorEnumV0";
+          const e = isErr ? entry.udtErrorEnumV0() : entry.udtEnumV0();
+          const name = e.name().toString();
+          const cases = e.cases().map((c) => `${c.name().toString()} = ${c.value()}`).join(", ");
+          w(`  ${A.dim}${pad(isErr ? "error" : "enum", 6)}${A.reset} ${A.bold}${name}${A.reset} { ${cases} }
+`);
+        }
+        if (kind === "scSpecEntryUdtUnionV0") {
+          const u = entry.udtUnionV0();
+          const name = u.name().toString();
+          const variants = u.cases().map((c) => {
+            const isVoid = c.switch().name === "scSpecUdtUnionCaseVoidV0";
+            const inner = isVoid ? c.voidV0() : c.tupleV0();
+            const tag = inner.name().toString();
+            if (isVoid) return `'${tag}'`;
+            const types = inner.type().map(toTs);
+            return types.length === 1 ? `'${tag}'(${types[0]})` : `'${tag}'(${types.join(", ")})`;
+          }).join(" | ");
+          w(`  ${A.dim}${pad("union", 6)}${A.reset} ${A.bold}${name}${A.reset} ${variants}
+`);
+        }
+      } catch {
+      }
+    }
+  }
+  w(`
+`);
+}
+function printHelp() {
+  process.stdout.write(`
+${A.bold}sck${A.reset} (stellar-contracts-kit): TypeScript SDK for Soroban smart contracts
+
+Commands:
+  generate    Generate TypeScript types and example file for a contract
+  inspect     Print contract functions and custom types to the terminal
+
+Usage:
+  npx sck                         Interactive mode with arrow-key selection
+  npx sck generate [options]       Generate types (non-interactive)
+  npx sck inspect  [options]       Inspect a contract (non-interactive)
+  npx sck [options]                Shorthand for generate (backwards-compatible)
+
+Options (generate + inspect):
+  --contract    Contract address (C..., 56 chars)
+  --network     testnet | mainnet | futurenet
+  --rpc-url     Custom RPC URL (use with --passphrase instead of --network)
+  --passphrase  Custom network passphrase
+
+Options (generate only):
+  --out         Output file path  (default: ./contracts/<name>.ts)
+  --name        Interface name    (default: derived from --out filename)
+  --alias       Path alias prefix, e.g. @  (auto-detected from tsconfig.json)
+  --js          Generate JavaScript output instead of TypeScript
+  --help, -h    Show this help
+
+Examples:
+  npx sck
+  npx sck generate --contract CABC... --network testnet
+  npx sck inspect  --contract CABC... --network testnet
+  npx sck generate --contract CABC... --network testnet --out src/contracts/counter.ts
+`);
+}
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    printHelp();
+    process.exit(0);
+  }
+  const subcommand = rawArgs[0] && !rawArgs[0].startsWith("--") ? rawArgs[0] : void 0;
+  const flagArgs = subcommand ? rawArgs.slice(1) : rawArgs;
+  const args = {};
+  for (let i = 0; i < flagArgs.length; i++) {
+    if (flagArgs[i].startsWith("--")) {
+      const key = flagArgs[i].slice(2);
+      const next = flagArgs[i + 1];
+      args[key] = next && !next.startsWith("--") ? (i++, next) : "true";
+    }
+  }
+  const contractId = args["contract"] ?? args["contract-id"];
+  if (subcommand === "inspect") {
+    if (!contractId) {
+      process.stderr.write("Error: --contract is required\n");
+      process.stderr.write("Usage: npx sck inspect --contract <ID> --network <preset>\n");
+      process.stderr.write("       npx sck (interactive mode)\n");
+      process.exit(1);
+    }
+    await runInspect({
+      contractId,
+      networkArg: args["network"],
+      rpcUrl: args["rpc-url"],
+      passphrase: args["passphrase"]
+    });
+    return;
+  }
+  if (subcommand && subcommand !== "generate") {
+    process.stderr.write(`Error: unknown command '${subcommand}'
+`);
+    process.stderr.write("Run npx sck --help for usage.\n");
+    process.exit(1);
+  }
+  if (!contractId) {
+    if (!process.stdin.isTTY) {
+      process.stderr.write("Error: --contract is required (interactive mode needs a terminal)\n");
+      process.stderr.write("Usage: npx sck --contract <ID> --network <preset>\n");
+      process.exit(1);
+    }
+    await runInteractive();
+    return;
+  }
+  await runGenerate({
+    contractId,
+    networkArg: args["network"],
+    rpcUrl: args["rpc-url"],
+    passphrase: args["passphrase"],
+    rawOut: args["out"] ?? args["output"],
+    rawName: args["name"],
+    aliasHint: args["alias"],
+    lang: args["js"] === "true" ? "js" : "ts"
+  });
+}
+main().catch((err) => {
+  process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});