Skip to content

registry.md

Latest commit

 

History

History
65 lines (42 loc) · 3.12 KB

registry.md

File metadata and controls

65 lines (42 loc) · 3.12 KB

Registry

The registry is how community bundles and generators are discovered and installed.

How it works

registry.json is the source of truth: a list of available packages with their name, kind, version, tags, and install command. The CLI fetches this index and lets you list, search, install.

Two registry modes:

  • Hosted (default) — the CLI fetches registry.json from https://raw.githubusercontent.com/fixedcode-ai/registry/main/registry.json. PRs add or update entries.
  • Local — if the hosted fetch fails, the CLI falls back to a registry.json in the current working directory. Useful for offline use and for bundle authors testing locally.

CLI

fixedcode registry list                          # all packages
fixedcode registry list --kind generator         # filter by kind
fixedcode registry search <query>                # fuzzy match name/description/tags
fixedcode registry install <name>                # npm install + register in .fixedcode.yaml
fixedcode registry publish --kind bundle --tags "tag1,tag2"
                                                  # open a PR adding/updating your package

Distribution model in v0.2.0

Only the engine (fixedcode) is published to npm in v0.2.0. The registry.json shipped at v0.2.0 acts as a catalog for discovery — you can fixedcode registry list and fixedcode registry search to find bundles, but fixedcode registry install <name> will return 404 for the bundles listed below until those packages are published.

This is intentional for the initial OSS release: it keeps the publishing surface small. Bundles will move to npm in a future release.

To use a bundle today: clone github.com/gibbon/fixedcode, register the bundle in your project's .fixedcode.yaml with a file: path:

bundles:
  spring-domain: "/path/to/cloned/fixedcode/bundles/spring-domain"

Install command validation

The CLI rejects an install command that:

  • isn't exactly npm install <single-target>,
  • has a target that doesn't match either the npm package pattern ([@scope/]name[@version-range]) or the GitHub ref pattern (github:owner/repo[#ref]),
  • contains .. anywhere in the target.

This prevents a malicious or accidentally-malformed registry entry from running an arbitrary install. See SECURITY.md for the full threat model.

Publishing your bundle

cd my-bundle
fixedcode registry publish --kind bundle --tags "spring,kotlin"

This:

  1. Validates --registry-repo (default fixedcode-ai/registry) against owner/repo.
  2. Builds an entry for your package from its package.json (name, version, repo).
  3. Clones the registry repo, branches, commits the updated registry.json, pushes, and opens a PR via gh.

Maintainers review and merge.

Adapters and generators

Generators expose an input contract; bundles expose adapters for that contract. The registry has no special handling for adapters — they're TypeScript code shipped with the bundle. When both a bundle and a generator are registered in .fixedcode.yaml, the engine wires them automatically based on the adapter key matching the generator name.