[tuler]

Summary

Replaces cartesi.toml with a cartesi.config.ts file that exports its configuration through defineConfig, in the style of rolldown and tsdown, so an application can be configured without reaching for the programmatic API.

import { defineConfig } from "@cartesi/cli/config";

export default defineConfig({
    drives: { data: { builder: "empty", size: "64Mi", mount: "/mnt/data" } },
    machine: { entrypoint: "dapp", ramLength: "256Mi" },
    nvrams: { accounts: { accountsDrive: true, size: "4Ki" } },
    run: { epochLength: 10, services: ["explorer"] },
});

defineConfig does nothing at runtime: it exists so the configuration is type checked and completed by the editor, without any annotation. A configuration file may also export a function, which receives the command being run and the mode, so a project can configure itself differently for build and run:

export default defineConfig(async ({ command, mode }) => ({
    machine: { envFile: `.env.${mode}` },
    run: { epochLength: command === "run" ? 10 : 720 },
}));

Based on #512, which it builds directly on top of.

Key Changes

• defineConfig and the input types (config/user.ts), exported from a new @cartesi/cli/config subpath so a configuration file does not pull in the rest of the CLI. Also re-exported from the main entrypoint.

• Applications not written in TypeScript describe the very same configuration as plain data. The configuration file of a project is the first of these that exists:

  File	Format
  cartesi.config.ts, .mts, .cts, .js, .mjs, .cjs	module exporting defineConfig({ ... })
  cartesi.config.json	JSON
  cartesi.config.yaml, cartesi.config.yml	YAML
  cartesi.config	YAML, which accepts JSON as well
  cartesi.toml	deprecated

  config/load.ts finds and reads it; config/normalize.ts validates it. Those formats are not type checked, so every value is checked there and, as the TOML parser does, a key no section reads is an error rather than silence — a misspelled ramLenght is reported with the keys machine accepts. $schema is allowed, so a JSON or YAML file can point an editor at a schema.

• run section: project level defaults of the local development environment (epochLength, services, blockTime, forkUrl, projectName, ...), so they do not have to be repeated on every cartesi run. Command line options take precedence, which is why the commander defaults moved into run itself; the layering is a pure resolveRunOptions function.

• cartesi.toml keeps working, and is read when a project has no other configuration file, but is deprecated and prints a warning.

• The shared configuration modules grew to fit two kinds of input: the errors and the size parsing now take a value from any format rather than a TOML one, parseSize/parseBytes move to config/size.ts beside splitSize, and the top-level TOML parse moves to config/toml/parse.ts so config.ts is only a barrel and nothing imports it in a cycle. CLAUDE.md is updated to match.

Notable Implementation Details

• TypeScript configuration files are imported by the runtime itself, so there is no build step and no extra dependency: the standalone binaries run on bun, and node strips the types from version 24, which this package requires. A runtime that cannot is reported rather than worked around.
• path.extname reads a file with no format in its name, such as cartesi.config, as .config, which is handled as YAML.
• A resolved Config is a valid UserConfig, so it can be given straight back to resolveConfig, and normalizing it again is idempotent. Keys are camelCase, as the resolved configuration already is; the withdrawal keys keep the names the cartesi-rollups-cli expects.
• The module cache is busted per load, so a configuration file edited between two builds of the same process is picked up, which the interactive run shell relies on.

Behavior Changes

• resolveConfig is now asynchronous, since a configuration file has to be imported, and its config option accepts a configuration written inline, in the same shape a cartesi.config.ts file exports. getProjectSdk and the withdrawal resolution in run() became asynchronous with it; getProjectSdk keeps reporting an invalid configuration rather than falling back to the default image.
• -c/--config defaults to looking the configuration file of the project up, rather than to cartesi.toml. An explicitly given file that does not exist is an error, as before.
• The --default-block warning moved from the run command into run(), where the resolved value is known, and is silenced along with the rest of the progress output.

Testing

Linting, type checking and 467 unit tests pass. The 383 tests of the base branch all still pass; the other 84 are new, covering defineConfig, normalization and validation of every section (drives, nvrams, the accounts drive, withdrawal, run), unknown keys, size parsing, file discovery and precedence, loading each supported format, merging a list of files, and the layering of the run options.

The base's should parse every key of full.toml expectation gains run: {}, which is the check working as its comment intends: the deprecated format has no [run] section, so it always defaults.

End to end, against the built artifacts rather than the sources: a TypeScript configuration exporting a function was loaded through dist/lib.js with nvrams, an accounts drive and withdrawal overrides resolving correctly, and the compiled linux-x64 binary read the TypeScript, JSON (with $schema), YAML, bare cartesi.config and deprecated TOML files, reporting an unknown key and an invalid nvram size as a single line each. Docker was not available in the development environment, so the build itself was only exercised up to the point where it shells out.

One note for the maintainer, not introduced here: the messages of InvalidWithdrawalConfigError and InvalidAccountsDriveError name the TOML spellings (accounts_drive = true), which read oddly for a cartesi.config.ts. They are left as they are because the base branch's tests assert the exact strings.

Also still easy to add later: a generated JSON Schema for $schema driven completion in the data formats, and the application templates, which live in another repository.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BHFyMTf1k57qtDwcbwVjrs

[changeset-bot]

🦋 Changeset detected

Latest commit: 16d0c66

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

This PR includes changesets to release 1 package

Name	Type
@cartesi/cli	Minor

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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🟢	Lines	86.93% (🎯 0%)	13274 / 15269
🔵	Statements	86.93%	13274 / 15269
🔵	Functions	81.54%	349 / 428
🔵	Branches	0%	0 / 0

📁 File Coverage (20 files)

File	Lines	Statements	Functions	Branches	Uncovered Lines
apps/cli/src/api/connection.ts	🔴 13.33%	🔴 13.33%	🔴 0%	🔴 0%	59-84
apps/cli/src/api/deposit/common.ts	🟢 93.1%	🟢 93.1%	🟡 71.43%	🔴 0%	90, 94
apps/cli/src/api/deposit/erc1155.ts	🔴 3.33%	🔴 3.33%	🔴 0%	🔴 0%	81-159, 170-262, 271-301
apps/cli/src/api/deposit/erc20.ts	🔴 7.07%	🔴 7.07%	🔴 0%	🔴 0%	33-46, 78-155
apps/cli/src/api/deposit/erc721.ts	🔴 5.51%	🔴 5.51%	🔴 0%	🔴 0%	40-49, 78-187
apps/cli/src/api/deposit/ether.ts	🔴 13.64%	🔴 13.64%	🔴 0%	🔴 0%	30-67
apps/cli/src/api/deposit/index.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/api/run.ts	🔴 12.8%	🔴 12.8%	🔴 20%	🔴 0%	184-206, 210-223, 227-272, ...
apps/cli/src/api/send.ts	🟡 71.96%	🟡 71.96%	🟡 75%	🔴 0%	46-47, 74-78, 95, 104, 156-176
apps/cli/src/api/types.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/base.ts	🔴 36.88%	🔴 36.88%	🟡 62.5%	🔴 0%	62, 66, 80, 88-161, 187-191...
apps/cli/src/builder/directory.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/docker.ts	🟢 87.12%	🟢 87.12%	🟡 66.67%	🔴 0%	77-79, 81, 114-116, 174-183
apps/cli/src/builder/empty.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/none.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/nvram.ts	🟢 97.14%	🟢 97.14%	🟢 100%	🔴 0%	38
apps/cli/src/builder/tar.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/commands/foreclose.ts	🔴 49.09%	🔴 49.09%	🔴 50%	🔴 0%	69, 91-145
apps/cli/src/commands/refund.ts	🔴 38.2%	🔴 38.2%	🟡 66.67%	🔴 0%	55-109
apps/cli/src/commands/withdraw.ts	🔴 46.58%	🔴 46.58%	🟡 73.33%	🔴 0%	95-123, 277-278, 301-356, 3...

[brunomenezes]

@tuler, Probably due to the base, but can you rebase?