Appearance

MigrationDocs 1.3.x

CLI and Catalog Plugin Input Is Checked ​

Applies to @connectum/cli and @connectum/protoc-gen-catalog 1.3.0.

Does this apply to you? ​

You need to act only if a script, a CI job or a buf.gen.yaml of yours does one of these:

  • passes connectum init, connectum proto sync or connectum generate service a flag the command does not define (a typo such as --evnts nats, or a flag from another tool). Before, it was dropped without a word; now the command stops with Error: connectum init: unknown option --evnts. Valid options: ... and exit code 1;
  • runs connectum init --runtime bun --node-exec <raw|tsx>. Bun runs TypeScript itself, so the flag selected nothing; the command now refuses the combination and names both flags;
  • runs connectum generate service in a directory with no package.json, or with --with-events in a project whose package.json has no @connectum/events in dependencies, devDependencies, peerDependencies or optionalDependencies. Before, the files were written anyway, and the event handler failed tsc with TS2307 and TS7006;
  • generates the service catalog with protoc-gen-connectum-catalog without target=ts in opt (no target at all, target=js, target=dts, or a combination such as ts+js);
  • gives protoc-gen-connectum-catalog the output_file option more than once.

If none of these applies, nothing changes for you except the wording of errors (see below).

Required changes ​

  • Unknown flag. Remove it, or correct the spelling. The error lists every flag the command has.
  • --node-exec with Bun. Leave --node-exec out when scaffolding for Bun.
  • generate service outside a project. Run it from the project root. To use --with-events, add @connectum/events and an adapter first (npm install @connectum/events @connectum/events-nats), or scaffold the project with connectum init --events <adapter>.
  • Catalog target. Put target=ts in the plugin's opt, as the catalog generation guide does. Without a target, buf reads js+dts; the plugin wrote catalog.gen.js and catalog.gen.d.ts, which carry no declare module "@connectum/core" augmentation, so every ctx.call key was untyped. If you imported catalog.gen.js or catalog.gen.d.ts, import the generated catalog.gen.ts instead.
  • Repeated output_file. Keep one. The last one used to win.
yaml
# Before: no target, the plugin wrote catalog.gen.js and catalog.gen.d.ts
- local: protoc-gen-connectum-catalog
  strategy: all
  out: gen

# After
- local: protoc-gen-connectum-catalog
  strategy: all
  out: gen
  opt: [target=ts, import_extension=.js]

Behavior that changed without an action on your side ​

  • The @generated by protoc-gen-connectum-catalog line is now the first line of catalog.gen.ts, above the imports. Regenerate to get it; nothing else in the file changes.
  • Failures of connectum proto sync that are caused by the input are one line (Error: ..., exit code 1): a closed port names the address and ECONNREFUSED, an empty or malformed --from is refused before any connection, a --template that is not a file is refused before any connection, a missing buf says it is not on the PATH, and a server that speaks only HTTP/1.1 is named as such. The exit code was 1 before as well.
  • A project scaffolded with --auth now answers the gRPC Health and reflection services without a token. Projects scaffolded earlier keep their src/auth.ts; see What --auth generates for the change to make there.
  • A project scaffolded with --no-healthcheck has no HEALTHCHECK in its Dockerfiles and no dependency on @connectum/healthcheck.

Verify the upgrade ​

Run each command you use once and read the output. A flag the command does not define now ends the run with unknown option; buf generate with the catalog plugin writes catalog.gen.ts and nothing else, and a missing target=ts fails with a message that names it.