packages/client has no consumable form: dist is gitignored, and the built dist carries bare dependency imports

[iceteaSA]

@cortexkit/claustrum-client is declared as a library — main: ./dist/index.js, an exports map pointing only at dist, a files: ["dist", "README.md"] allowlist — but there is no form a consumer outside this repo can actually import. dist/ is gitignored (.gitignore:7, packages/*/dist), nothing is published, and the built dist is not self-contained.

This is not hypothetical. A consumer on this box (the tok tooling) adopted the client this week and hit it at import.

What a consumer finds

Measured on a clean git archive of origin/master, three arms:

tsc dist, absolute-path import, unrelated cwd, node_modules present   OK, 9 exports
raw src/index.ts, absolute-path import, node_modules present          OK, 9 exports
the same tsc dist copied away from its node_modules                   ENOENT resolving
                                                                      '@cortexkit/subc-client'
                                                                      from dist/detect.js

The discriminator is not source-versus-built. bun run build runs tsc -p tsconfig.build.json, which emits per-file output: a 340-byte re-export barrel plus wire.js and detect.js carrying bare @cortexkit/subc-client imports. The artifact only works while it sits beside a populated node_modules, so it is not relocatable and not vendorable.

How the consumer worked around it, and why that is worse than it looks

Not knowing bun install alone was sufficient, they built the sibling subc client from source, symlinked it into packages/client/node_modules, and ran bun build src/index.ts --outdir dist --target bun — producing a 99KB bundle with the dependency inlined. That is what their tool imports today.

So the artifact in use is not the artifact bun run build produces. The first time anyone runs the repo's own documented build command in that checkout, the bundle is replaced by the tsc emit and the consumer breaks — not from a git clean, from the ordinary command. A consumer pinned to a procedure the repo does not perform is a break waiting on an unrelated action.

Worth noting the supported path does exist and is unremarkable — bun install --frozen-lockfile && bun run build, no symlink, no sibling source build, @types/bun arriving from the install. @cortexkit/subc-client is public on npm. The workaround was avoidable; it was reached because nothing states this.

Ask

Either would close it:

1. Publish @cortexkit/claustrum-client — even 0.x. @cortexkit/subc-client already publishes to npm from this org, so the path exists. files/exports/prepack are already correct for it.
2. Document the supported build in packages/client/README.md and state whether the dist is intended to be self-contained. If it is, the build wants a bundling step; if it is not, say so, because files: ["dist"] implies a package whose consumer resolves the dependency through npm — which no path-importing consumer does.

I lean (1): (2) still leaves consumers importing a gitignored artifact out of a working tree, and the failure mode is silent degradation at import rather than a version error.

Happy to do the work on either. Publishing is the org's call, not mine — flagging rather than assuming.

[iceteaSA]

Correcting my own evidence in the issue body. The three arms above do not prove what I said they prove, and I would rather strike them than let them stand.

I ran all three under bare bun -e. Bun auto-installs public packages from npm when a bare specifier does not resolve, and @cortexkit/subc-client is public — so the harness was supplying the exact dependency whose absence I claimed to be measuring. The cache entries are sitting in ~/.bun/install/cache where the runs left them.

The arm that actually isolates something — identical tsc dist in both, neither has node_modules, only package.json differs:

dist alone, no package.json     ENOENT resolving '@cortexkit/subc-client'
same dist + package.json        resolved, 9 exports

So my third arm failed for package-context absence, not for node_modules absence. I read one failing arm as confirming the variable I happened to have in mind. Under bare Bun, raw src/index.ts and the built dist both resolve with zero node_modules anywhere, so neither "source versus built" nor "node_modules present versus absent" is the discriminator there.

What survives, and why the issue stands unchanged:

The consumer's failure was ERR_MODULE_NOT_FOUND under the opencode host loader, from a tree that did contain package.json. The host is evidently not auto-installing. So the reported defect is real and reproduced by them on the host; what I cannot do is reproduce it under bare Bun, because auto-install masks it. The ask is unchanged:

built dist        per-file tsc emit, bare '@cortexkit/subc-client' in wire.js and detect.js
consequence       not relocatable, not vendorable, importable only where the resolver
                  can reach the dependency by some route
today             that route is either an installed node_modules or npm at import time

If anything this sharpens (1). A package whose importability depends on the resolver reaching the registry during the import is a weaker contract than one that merely needs installing — it works on a connected developer box and fails in a sandbox, offline, or under a loader with auto-install off, which is three environments where a credential client should not be discovering it has no transport.

Method note, since I put a bad measurement in a public issue: bare bun -e is not a valid oracle for module resolution. Its auto-install silently satisfies the dependency under test. Resolution has to be exercised under the loader that will actually run the code — which is what the consumer did, and what I did not.

[iceteaSA]

Follow-up: I had inferred "the host does not auto-install" from the consumer's error rather than testing it. It reproduces, and the mechanism generalises the problem beyond this host.

A compiled Bun executable that dynamically imports a module from disk, where that module carries a bare dependency — the shape of any plugin or path-imported client under a shipped binary:

compiled loader -> disk module, package.json present, no node_modules
    FAILED ERR_MODULE_NOT_FOUND Cannot find module '@cortexkit/subc-client'

bare `bun -e`  -> the SAME module, same tree, same absent node_modules
    RESOLVED

Same file, same directory, same missing node_modules; only the loader differs. The error code is the one the consumer reported. opencode is a 178 MB compiled Bun 1.3.14 executable, so this is its resolver, not a configuration choice on that box.

Why this widens the ask rather than just confirming it. Auto-install is a dev-time convenience of the Bun CLI; a compiled binary does not have it. So packages/client is importable from a source checkout on a developer machine and not importable from any shipped Bun application — and the second case is the one this package exists to serve, since a credential client's consumers are daemons and plugins, not REPLs. The failure also arrives at import time with a module-resolution error rather than anything a consumer can classify as a vault problem.

It also means a passing local check is not evidence for the shipped case, which is how the wrong mechanism survived in this issue for an hour.

Practical consequence for option (2): documenting the build is not sufficient on its own unless the built artifact is self-contained. tsc emits per-file output with the bare import intact, so a documented bun install && bun run build still yields something a compiled host cannot load unless the consumer also reproduces node_modules beside it. Either the build gains a bundling step, or (1).