Add Codama CLI

[lorisleiva]

This PR adds a brand new @codama/cli package which is then imported (not re-exported) by the main codama library in order to use the codama keyword as CLI binary.

The CLI currently supports the following two commands:

• codama init: which initialises a Codama configuration file by using prompts and selected script presets.
• codama run: which runs any script defined in your configuration file.

You can learn more about the CLI commands and the Codama config file from the @codama/cli README copy/pasted below:

---

This package provides a CLI for the Codama library that can be used to run scripts on Codama IDLs.

Note that, whilst the CLI code is located in the @codama/cli package, the CLI binary is directly provided by the main codama library.

Getting started

To get started with Codama, simply install codama to your project and run the init command like so:

pnpm install codama
codama init

You will be prompted for the path of your IDL and asked to select any script presets you would like to use.

codama run

Once you have your codama config file, you can run your Codama scripts using the codama run command as follows:

codama run         # Only runs your before visitors.
codama run js rust # Runs your before visitors followed by the `js` and `rust` scripts.
codama run --all   # Runs your before visitors followed by all your scripts.

The configuration file

The codama config file defines an object containing the following fields:

• idl (string): The path to the IDL file. This can be a Codama IDL or an Anchor IDL which will be automatically converted to a Codama IDL.
• before (array): An array of visitors that will run before every script.
• scripts (object): An object defining the available Codama scripts. The keys identify the scripts and the values are arrays of visitors that make up the script.

Whether it is in the before array or in the scripts values, when defining a visitor you may either provide:

• an object with the following fields:
  • from (string): The import path to the visitor.
  • args (array): An array of arguments to pass to the visitor.
• a string: The import path to the visitor. This is equivalent to providing an object with a from field and an empty args array.

Visitor import paths can either be local paths (pointing to JavaScript files exporting visitors) or npm package names. By default, the default export will be used but you may specify a nammed export by appending a # followed by the export name. When resolved, the imported element inside the module should either be a Visitor<any, 'rootNode'> or a function that returns a Visitor<any, 'rootNode'> given the arguments provided. Here are some examples of valid visitor import paths:

'./my-visitor.js'; // Relative local path to a visitor module.
'/Users/me/my-visitor.js'; // Absolute local path to a visitor module.
'some-library'; // npm package name.
'@acme/some-library'; // Scoped npm package name.
'./my-visitor.js#myExport'; // Named export from a local path.
'@acme/some-library#myExport'; // Named export from an npm package.

Here is an example of what a Codama configuration file might look like:

{
    "idl": "path/to/idl",
    "before": [
        "./my-before-visitor.js",
        { "from": "some-library#removeTypes", "args": [["internalFoo", "internalBar"]] }
    ],
    "scripts": {
        "js": [
            {
                "from": "@codama/renderers-js",
                "args": ["clients/js/src/generated"]
            }
        ]
    }
}

Note that you can use the --js flag to generate a .js configuration file when running the init command.

[changeset-bot]

🦋 Changeset detected

Latest commit: dcf0aa2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
@codama/renderers-vixen-parser	Patch
@codama/renderers-js-umi	Patch
@codama/renderers-rust	Patch
@codama/renderers-js	Patch
codama	Patch
@codama/cli	Patch
@codama/renderers	Patch
@codama/errors	Patch
@codama/node-types	Patch
@codama/nodes	Patch
@codama/validators	Patch
@codama/visitors-core	Patch
@codama/visitors	Patch
@codama/dynamic-codecs	Patch
@codama/dynamic-parsers	Patch
@codama/nodes-from-anchor	Patch
@codama/renderers-core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[lorisleiva]

• Add Codama CLI #425 👈 (View in Graphite)
• Update web3.js v2 URLs #424
• Move CLI of errors package in subdirectory #423
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[febo]

Looks great – just found a tiny typo.

[lorisleiva]

Merge activity

• Jan 31, 12:48 PM EST: A user started a stack merge that includes this pull request via Graphite.
• Jan 31, 12:50 PM EST: Graphite rebased this pull request as part of a merge.
• Jan 31, 12:51 PM EST: A user merged this pull request with Graphite.