Refactor builder API into a factory + separate types for interface

[seefeldb]

still in progress, just FYI

---

Summary by cubic

Refactored the builder API to use a factory function for runtime injection and moved all public types and interfaces to a new builder/interface module.

• Refactors
  • Added createBuilder factory to generate builder functions with a given runtime.
  • Moved and consolidated public types, interfaces, and function signatures into builder/interface.ts.
  • Updated imports and usage across packages to use the new factory and interface structure.

[ubik2]

lgtm so far (once it passes checks)

[jsantell]

In service of generating bundled type definitions for our ts compiler, we need a single .d.ts file. tsc can generate type defs for each file in a graph and even put them all in the same file (with an --outFile), which uses declare module "local/path/module.ts", no tree shaking or unrolling. npm tools that do this (some rollup extensions) typically don't play well with our deno workspace.

In lieu of manually maintaining this typedef, we could derive via tsc easily if this interface was standalone. We could move the schema-to-ts and schema-lib types here for that. Mutable is a bit trickier, maybe this should be a part of our recipe interface that we also use internally (which is at odds with the interface extensions elsewhere if we generally do not want to import from interfaces)

[seefeldb]

Just removed Mutable from the interface for now. If we need it again, let's just make a one-off for json schemas, which is the only place it was used anyway.

So now it's down to two files. We could easily combine those if this makes things easier. And since it's all type declarations, should it just be renamed to .d.ts? And we could move it out to a different package as well, even if it's just that one file. WDYT?

[jsantell]

• Removing Mutable from interface: sounds good!
• lets hold off on moving to a new package etc., can have this interface be a "virtual" import at @commontools/framework or whatever
• Could possibly just be a .d.ts, not sure if everything we use can be represented only as types not values (e.g. the AuthSchema objects), but if they can that'd work
• We can hold off on merging in the schema libs for now, though may be needed if we want a single static .d.ts (then we wouldn't even need to "generate" it)

[seefeldb]

Ah, needed Mutable<> after all in a recipe. So I copy & pasted the type, it's just three lines.

[seefeldb]

And I realized there are a few constants that are defined, e.g. NAME, UI, ID, etc. most are strings, but ID is a symbol.

That symbol might create issues: It'll have to be the same via the imports and the factory. I think that's automatically the case now, but as we evolve the sandbox that's something to watch.

[ubik2]

Regarding AuthSchema, I think it may even make sense to break schema-lib out of the normal packages in the future. It's not part of the core system, just a convenient shared add-on.

[cubic-dev-ai]

cubic found 4 issues across 40 files. Review them in cubic.dev

_{React with 👍 or 👎 to teach cubic. Tag @cubic-dev-ai to give specific feedback.}

[cubic-dev-ai]

@commontools/builder/interface only provides declaration exports (e.g. export declare const derive...) so no runtime values are emitted. Importing runtime helpers such as derive, handler, lift, etc. from this path will make them undefined at execution time and the recipe will crash as soon as any of them is called. Import the implemented helpers from @commontools/builder instead.

Suggested change

	} from "@commontools/builder/interface";
	} from "@commontools/builder";