@kaleido-xlm/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Kaleido contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @kaleido-xlm/cli
+
+## Install
+
+```bash
+npm install -g @kaleido-xlm/cli
+kaleido --help
+```
+
+## Requirements
+
+- Node.js `>=20`
+- Stellar CLI `>=22.0.0` and `<=22.0.1` available on `PATH`
+- A Kaleido project with `kaleido.config.ts` for project commands such as `build`, `deploy`, `generate`, and `invoke`
+
+If your local machine is on a newer Stellar CLI, `--allow-untested-stellar-cli` is the local-only escape hatch. CI and release workflows should stay on the supported range.
+
+## Commands
+
+- `kaleido init <projectName>` creates a project from a bundled template and writes `kaleido.artifacts.json`
+- `kaleido build [contract]` builds one configured contract through Stellar CLI and defaults to `counter` when omitted
+- `kaleido deploy [contract] --source <identity> [--network <network>] [--force] [--no-deps]` deploys contracts and records contract IDs in `kaleido.artifacts.json`
+- `kaleido generate <contract> [--network <network>]` generates TypeScript bindings from a deployed contract ID
+- `kaleido invoke <contract.method> --source <identity> [args...]` invokes a deployed contract method through the configured workflow
+
+The supported CLI flow is `init -> build -> deploy -> generate -> invoke`.
+
+## Supported Inputs
+
+- `--source` accepts a Stellar CLI identity alias or public `G...` account address
+- `--network <network>` selects a configured network such as `testnet`
+- `invoke` expects a `<contract.method>` target and forwards extra args to the underlying Stellar contract invocation
+- `deploy --no-deps` is supported only when deploying a single named contract
+
+Unsupported input posture:
+
+- secret keys and seed phrases are not supported CLI inputs
+- undocumented private flags or internal repo file paths are not part of the package contract
+
+## Error Behavior
+
+`@kaleido-xlm/cli` emits documented `KALEIDO_*` error codes for automation. Consumers should match on the error code, not human-readable text.
+
+Common codes include:
+
+- `KALEIDO_CONFIG_NOT_FOUND`
+- `KALEIDO_INVALID_CONFIG`
+- `KALEIDO_STELLAR_CLI_NOT_FOUND`
+- `KALEIDO_BUILD_FAILED`
+- `KALEIDO_DEPLOY_FAILED`
+- `KALEIDO_BINDINGS_FAILED`
+- `KALEIDO_INVOKE_FAILED`
+- `KALEIDO_CONTRACT_ID_NOT_FOUND`
+- `KALEIDO_SOURCE_ACCOUNT_REQUIRED`
+- `KALEIDO_TEMPLATE_MANIFEST_NOT_FOUND`
+- `KALEIDO_TEMPLATE_INCOMPATIBLE`
+
+## Relationship To `@kaleido-xlm/core`
+
+`@kaleido-xlm/cli` is the supported end-user entrypoint for Kaleido's command workflow. It intentionally stays thin and delegates config loading, artifacts, command orchestration, and shared error primitives to `@kaleido-xlm/core`.
+
+If you want the stable packaged workflow, prefer the CLI contract over importing `@kaleido-xlm/core` directly.
+
+## Versioning And Stability
+
+This package is the primary supported consumer surface for the Kaleido workflow. Stability applies to the documented commands, inputs, and `KALEIDO_*` error contract.
+
+Undocumented internals, private module paths, and placeholder commands such as `kaleido dev` are not part of the stability promise.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+// src/program.ts
+import { Command } from "commander";
+
+// src/commands/build.command.ts
+import { buildContract, loadConfig } from "@kaleido-xlm/core";
+
+// src/utils/errors.ts
+import { toKaleidoError } from "@kaleido-xlm/core";
+
+// src/utils/logger.ts
+import chalk from "chalk";
+var logger = {
+  info(message) {
+    console.log(message);
+  },
+  success(message) {
+    console.log(chalk.green(message));
+  },
+  warn(message) {
+    console.warn(chalk.yellow(message));
+  },
+  error(message) {
+    console.error(chalk.red(message));
+  },
+  muted(message) {
+    console.log(chalk.gray(message));
+  }
+};
+
+// src/utils/errors.ts
+function printError(error) {
+  const kaleidoError = toKaleidoError(error);
+  logger.error(`Error: ${kaleidoError.message}`);
+  logger.info("");
+  logger.info(`Code: ${kaleidoError.code}`);
+  if (kaleidoError.hint) {
+    logger.info(`Hint: ${kaleidoError.hint}`);
+  }
+}
+async function runCliAction(action) {
+  try {
+    await action();
+  } catch (error) {
+    printError(error);
+    process.exitCode = 1;
+  }
+}
+
+// src/commands/build.command.ts
+function registerBuildCommand(program2) {
+  program2.command("build").description("Build a configured Soroban contract").argument("[contract]", "Contract name", "counter").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Kaleido's tested maximum").action((contractName, options) => runCliAction(async () => {
+    const config = await loadConfig();
+    const result = await buildContract({
+      config,
+      contractName,
+      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+    });
+    logger.success("Contract built");
+    logger.info("");
+    logger.info(`Contract: ${result.contract.name}`);
+    logger.info(`WASM: ${result.contract.config.wasm}`);
+  }));
+}
+
+// src/commands/deploy.command.ts
+import { deployContractGraph, KaleidoError, KaleidoErrorCode, loadConfig as loadConfig2 } from "@kaleido-xlm/core";
+function registerDeployCommand(program2) {
+  program2.command("deploy").description("Deploy one or all configured Soroban contracts").argument("[contract]", "Contract name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias or public account address").option("--force", "Redeploy contracts even if artifacts already contain contract IDs").option("--no-deps", "Do not deploy missing dependencies for a selected contract").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Kaleido's tested maximum").action((contractName, options) => runCliAction(async () => {
+    if (options.deps === false && !contractName) {
+      throw new KaleidoError(
+        "`--no-deps` requires a contract name.",
+        KaleidoErrorCode.INVALID_CONFIG,
+        "Select a single contract or omit `--no-deps` to deploy the full graph."
+      );
+    }
+    const config = await loadConfig2();
+    const result = await deployContractGraph({
+      config,
+      contractName,
+      networkName: options.network,
+      source: options.source,
+      includeDependencies: options.deps !== false,
+      force: options.force === true,
+      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+    });
+    logger.success("Deploy complete");
+    logger.info("");
+    logger.info(`Network: ${result.network.name}`);
+    for (const contract of result.deployedContracts) {
+      logger.info(`Contract: ${contract.name}`);
+      logger.info(`Contract ID: ${contract.contractId}`);
+    }
+    logger.info("Artifacts updated: kaleido.artifacts.json");
+  }));
+}
+
+// src/commands/dev.command.ts
+function registerDevCommand(program2) {
+  program2.command("dev").description("Run the local Kaleido development workflow").action(() => runCliAction(async () => {
+    logger.warn("kaleido dev is not implemented in the MVP.");
+    logger.info("Use kaleido build, deploy, generate, and invoke directly.");
+  }));
+}
+
+// src/commands/generate.command.ts
+import { generateBindings, loadConfig as loadConfig3 } from "@kaleido-xlm/core";
+function registerGenerateCommand(program2) {
+  program2.command("generate").description("Generate TypeScript bindings for a deployed contract").argument("<contract>", "Contract name").option("-n, --network <network>", "Configured network name").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Kaleido's tested maximum").action((contractName, options) => runCliAction(async () => {
+    const config = await loadConfig3();
+    const result = await generateBindings({
+      config,
+      contractName,
+      networkName: options.network,
+      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+    });
+    logger.success("Client generated");
+    logger.info("");
+    logger.info(`Contract: ${result.contractName}`);
+    logger.info(`Network: ${result.network.name}`);
+    logger.info(`Output: ${result.outputDir}`);
+  }));
+}
+
+// src/commands/init.command.ts
+import path2 from "path";
+import { createProjectFromTemplate } from "@kaleido-xlm/core";
+
+// src/utils/template-path.ts
+import { access } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import { KaleidoError as KaleidoError2, KaleidoErrorCode as KaleidoErrorCode2 } from "@kaleido-xlm/core";
+async function resolveTemplateDir(templateName) {
+  const envTemplatesDir = process.env.KALEIDO_TEMPLATES_DIR;
+  const candidates = [
+    envTemplatesDir ? path.join(envTemplatesDir, templateName) : void 0,
+    path.resolve(process.cwd(), "packages", "templates", templateName),
+    ...candidatePathsFromModule(templateName)
+  ].filter((candidate) => Boolean(candidate));
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new KaleidoError2(
+    `Template "${templateName}" was not found.`,
+    KaleidoErrorCode2.TEMPLATE_NOT_FOUND,
+    "Set KALEIDO_TEMPLATES_DIR or run from a Kaleido checkout that includes packages/templates."
+  );
+}
+function candidatePathsFromModule(templateName) {
+  const currentFile = fileURLToPath(import.meta.url);
+  const start = path.dirname(currentFile);
+  const candidates = [];
+  let dir = start;
+  for (let depth = 0; depth < 8; depth += 1) {
+    candidates.push(path.join(dir, "packages", "templates", templateName));
+    candidates.push(path.join(dir, "templates", templateName));
+    candidates.push(path.join(dir, "node_modules", "@kaleido", "templates", templateName));
+    dir = path.dirname(dir);
+  }
+  return candidates;
+}
+
+// src/commands/init.command.ts
+function registerInitCommand(program2) {
+  program2.command("init").description("Create a new Kaleido dApp from a template").argument("<projectName>", "Project directory to create").option("-t, --template <template>", "Template name", "react-vite-counter").action((projectName, options) => runCliAction(async () => {
+    const templateDir = await resolveTemplateDir(options.template);
+    const targetDir = path2.resolve(process.cwd(), projectName);
+    const result = await createProjectFromTemplate({
+      projectName,
+      targetDir,
+      templateDir
+    });
+    logger.success("Project created");
+    logger.info("");
+    logger.info(`Project: ${projectName}`);
+    logger.info(`Template: ${result.template.name}@${result.template.version}`);
+    logger.info(`Path: ${targetDir}`);
+    logger.info("");
+    logger.info("Next steps:");
+    logger.info(`  cd ${projectName}`);
+    logger.info("  npm install");
+    logger.info("  npx kaleido build counter");
+  }));
+}
+
+// src/commands/invoke.command.ts
+import { invokeContract, loadConfig as loadConfig4 } from "@kaleido-xlm/core";
+function registerInvokeCommand(program2) {
+  program2.command("invoke").description("Invoke a deployed contract function").argument("<target>", "Invoke target in contract.method format").argument("[args...]", "Arguments forwarded to Stellar CLI after the method name").option("-n, --network <network>", "Configured network name").requiredOption("-s, --source <source>", "Stellar CLI identity alias or public account address").option("--allow-untested-stellar-cli", "Allow local use of a Stellar CLI version newer than Kaleido's tested maximum").allowUnknownOption(true).allowExcessArguments(true).action((target, args, options) => runCliAction(async () => {
+    const config = await loadConfig4();
+    const result = await invokeContract({
+      config,
+      target,
+      args,
+      networkName: options.network,
+      source: options.source,
+      allowUntestedStellarCli: options.allowUntestedStellarCli === true
+    });
+    logger.success("Invoke complete");
+    logger.info("");
+    logger.info(`Network: ${result.network.name}`);
+    logger.info(`Contract: ${result.target.contractName}`);
+    logger.info(`Method: ${result.target.method}`);
+    if (result.result) {
+      logger.info("");
+      logger.info(result.result);
+    }
+  }));
+}
+
+// src/version.ts
+var KALEIDO_CLI_VERSION = "0.1.0";
+
+// src/program.ts
+function createProgram() {
+  const program2 = new Command();
+  program2.name("kaleido").description("Developer toolkit for Stellar/Soroban dApps").version(KALEIDO_CLI_VERSION);
+  registerInitCommand(program2);
+  registerDevCommand(program2);
+  registerBuildCommand(program2);
+  registerDeployCommand(program2);
+  registerGenerateCommand(program2);
+  registerInvokeCommand(program2);
+  return program2;
+}
+
+// src/index.ts
+var program = createProgram();
+void program.parseAsync(process.argv).catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@kaleido-xlm/cli",
+  "version": "0.1.0",
+  "description": "Developer toolkit CLI for building dApps on Stellar/Soroban",
+  "keywords": [
+    "stellar",
+    "soroban",
+    "cli",
+    "dapp",
+    "smart-contracts",
+    "blockchain",
+    "web3",
+    "kaleido"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Dione-b/kaleido.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Dione-b/kaleido#readme",
+  "author": "Kaleido contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "kaleido": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@kaleido-xlm/core": "^0.1.0",
+    "chalk": "^5.4.1",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run --pool=threads",
+    "typecheck": "tsc --noEmit"
+  }
+}