Proposal: Reduce namespace pollution by unexporting identifiers (breaking change) #13

New issue

Closed

opened 2026-03-21 13:33:10 -07:00 by Eben60 · 2 comments

Eben60 commented

2026-03-21 13:33:10 -07:00

(Migrated from github.com)

Description:
Kaimon currently exports a large number of identifiers. In particular, start! and stop! have a very high probability of colliding with other packages or user-defined functions.

As I understand the typical workflow, Kaimon is imported alongside the package being developed, but the user rarely needs to call Kaimon functions directly after the initial setup ("set it and forget it").

Suggestions:

Remove all exports (declaring currently exported functions public)
Re-export serve: To maintain a clean entry point, re-export serve from Gate so that the primary interaction becomes Kaimon.serve().

I recognize this is a breaking change. However, since the package is not yet registered and has no downstream dependencies, it shouldn't be a problem.

**Description:** `Kaimon` currently exports a large number of identifiers. In particular, `start!` and `stop! `have a very high probability of colliding with other packages or user-defined functions. As I understand the typical workflow, `Kaimon` is imported alongside the package being developed, but the user rarely needs to call `Kaimon` functions directly after the initial setup ("set it and forget it"). **Suggestions:** - Remove all exports (declaring currently exported functions `public`) - Re-export serve: To maintain a clean entry point, re-export serve from Gate so that the primary interaction becomes Kaimon.serve(). I recognize this is a breaking change. However, since the package is not yet registered and has no downstream dependencies, it shouldn't be a problem.

kahliburke commented

2026-03-21 16:22:38 -07:00

(Migrated from github.com)

@Eben60 Thanks for the feedback on this, I'll take a look at what can be removed from exports.

kahliburke commented

2026-03-22 13:47:12 -07:00

(Migrated from github.com)

Implemented in d615d78 on the 1.1 branch.

Only Gate, @mcp_tool, and MCPTool are now exported. Everything else is declared public — accessible as Kaimon.foo() but not imported by using Kaimon.

This eliminates the start!/stop! collisions and keeps the namespace clean. Docs updated to use qualified references.

Implemented in d615d78 on the `1.1` branch. Only `Gate`, `@mcp_tool`, and `MCPTool` are now exported. Everything else is declared `public` — accessible as `Kaimon.foo()` but not imported by `using Kaimon`. This eliminates the `start!`/`stop!` collisions and keeps the namespace clean. Docs updated to use qualified references.