Proposal: establish the Community Catalog foundation

[kattsushi]

Context

In your Stack Effect write-up, you mentioned opening the module registry so the community can contribute targets and modules.

I've been looking at what it would take to build on that direction without adding another architecture branch or a parallel scaffolding system. Before implementing anything, I'd like to check whether the boundary below matches what you had in mind for Community Catalogs.

What seems to be missing today

The existing target, module, and contribution models already cover most of the interesting behavior. Blueprint and Plan also work from catalog definitions rather than knowing about individual modules.

The closed part appears to be catalog assembly:

• CatalogService is built from the fixed target and module registries.
• Adding a module still requires changing the core registry aggregation.
• Several service layers provide the built-in catalog internally, so supplying a composed catalog at only one boundary may not reach the full pipeline.
• There is no defined collision policy for independently authored definitions.

A possible first step

My suggestion is to start with explicitly imported catalog fragments rather than package discovery or dynamic plugins.

A host application could import a trusted fragment containing declarative target and module definitions, combine it with the built-in catalog, validate the result, and provide that catalog to the existing services.

For the first slice, I would keep the rules intentionally strict:

• Composition is additive. Duplicate target kinds or module IDs are rejected.
• The complete catalog is validated before it can be used.
• Fragment definitions use the existing declarative contribution model.
• Fragment definitions cannot add Finalize scripts yet.
• With no fragments, Stack Effect behaves exactly as it does today.

A small synthetic fragment could prove that a contributed target, a module for an existing target, or both can reach one real Selection -> Blueprint -> Plan path without editing the built-in registries.

This would only establish the composition boundary. It would not decide how catalogs are published, discovered, installed, trusted, or updated.

Feedback I'd appreciate

1. Does explicit local import feel like a useful first step toward the Community Catalog you described?
2. Would you prefer the initial public surface to include a catalog fragment plus composition/validation factory, or should it begin by exposing only the existing definition contracts?
3. Does additive-only composition with duplicate rejection fit the intended model?
4. Should Finalize scripts remain built-in-only until there is a clearer trust model?
5. Should catalog propagation through service layers be addressed in this slice, or shaped alongside Deepen the Plan module and seal planning internals #180 and Separate scaffold workflow orchestration from CLI interaction #181?

If this is close to the direction you have in mind, I can turn it into a smaller implementation proposal and validate it with a minimal fragment before touching broader distribution concerns.

Not part of this proposal

• A marketplace or remote registry.
• Package discovery or configuration-driven loading.
• Dynamic plugins or arbitrary code execution.
• Version resolution, signatures, sandboxing, or provenance UI.
• Overrides of built-in targets or modules.
• Custom target layouts or new contribution kinds.
• Any DDD, deployment, or other feature-specific catalog.

Related context

• Lab 060, Stack Effect introduction
• Deepen the Plan module and seal planning internals #180, Plan module boundaries
• Separate scaffold workflow orchestration from CLI interaction #181, scaffold workflow orchestration
• Add a selectable DDD architecture for Todo full-stack scaffolds #229, discussion about keeping modules thin and mix-and-match

[lloydrichards]

I had a bit of think about this and i think there are a couple way to go. Right now i'm leaning towards something like shadcn where anyone can publish a 'registry' which is just the encoded version of the catalog which can be consumed by the cli. so its possible to update the stack.effect.json or use it in a flag:

npx stack-effect@latest init . --registry https://stack-effect.lloydrichards.dev/public/default-catalog

I think this is the easiest to implement, but the issue would be on validation and if extensibility or composition of registries would be possible. Since a catalog could be a graph of almost any combination there is a lot of risk for conflicts between target/module ids as well as file conflicts.

I might have some time this week to explore this further, can look a bit into the plugin idea, maybe some sort of adapter architecture. we'll see 👍

[lloydrichards]

The VFS research supports retaining this declarative fragment boundary. Snapshots can package literal assets or validated example outputs, but do not replace module operations.

For example, two built-in client modules insert different cards into the same app.tsx slot. Whole-file overlay precedence cannot preserve that intent. Dependencies, ownership, and JSON/TypeScript/JSX operations therefore remain authoritative even if file payloads use snapshots.

A later compiled-profile experiment can explore distribution and caching alongside #252. It should not add remote discovery, executable hooks, or snapshot types to this initial fragment contract.

The compiled-profile and cache-identity experiment is now tracked in #254.