[ccf-lisa]

Task: IMPROVEMENTS item 8, stack A PR A3 of 3: fx/cat-a3-require-catalog on fx/cat-a2-rules-test-render.

Stack: #250 (A1) → #251 (A2) → this PR.

Summary

Breaking change (!): factory serve no longer defaults --catalog-repo to https://github.com/ContainerSolutions/factory. Anyone who started serve with no catalog flag must now pass --catalog-repo URL or --catalog-dir DIR; without either it exits 2 with a catalog is required: pass --catalog-repo URL or --catalog-dir DIR.

• No default repo (cmd/factory/serve.go, internal/controllers/catalogsource.go): DefaultCatalogRepo and GitSource.withDefaults' repo default are gone, and --catalog-repo defaults to "". --catalog-ref keeps main and --catalog-path keeps catalog. The existing checks stay: --catalog-dir excludes the git flags, and an explicitly empty --catalog-repo/-ref/-path is still "must not be empty". An explicitly empty --catalog-dir is now --catalog-dir must not be empty (it used to fall through to the git default). The usage line and text name the two ways.
• catalog/README.md (new): catalog/ is the reference catalog. The tests and fixtures use it, it is the example to copy, and no dispatcher deploys it. Its poc-* RuleSets name compliance-framework repos as examples. The README says what make catalog and catalog_test.go check, and how to start your own catalog: copy the directory, set the App IDs and scopes, run factory validate and factory rules test in CI with a pinned release, then serve --catalog-repo (plus A1's App flags for a private repo). Nothing else under catalog/ changes.
• deploy/poc: run.sh takes FACTORY_CATALOG_REPO (required unless FACTORY_CATALOG_DIR is set; it fails before the build with a clear message), FACTORY_CATALOG_REF (default main), FACTORY_CATALOG_PATH (default catalog) and FACTORY_CATALOG_APP_ID (A1's). .env.example lists them, with CCF's https://github.com/compliance-framework/factory-catalog as the commented example. README §4 is now "Catalog: bring your own", with three options (a public repo, a private repo with the App flags, a local directory), and the local-copy recipe starts from a copy of the reference. The "Run the image" example passes --catalog-repo. The expected factory validate count in the recipe is corrected from 11 warnings to 23 (all CAT1200), which is what the copy gives on this base.
• This resolves the feat(controllers): read a private catalog with an App installation token #250 review thread about run.sh sending the catalog App's token to the hard-coded public repo (discussion_r4411918033): with FACTORY_CATALOG_APP_ID set, run.sh now passes --catalog-repo "$FACTORY_CATALOG_REPO", the repo from .env.
• Design docs: controllers.md, api-server.md (synopsis, flag table, config validation) and rollout.md now say serve requires a catalog, and they point to catalog/README.md. ADR-0006 is untouched.

Design decisions (also in the lisa-design note):

• .env.example keeps FACTORY_CATALOG_REPO commented out. It is needed only when FACTORY_CATALOG_DIR is unset, so it is not in run.sh's unconditional required=() list, which deploykit_test.go pins to the uncommented lines. run.sh checks the either/or itself, so deploykit_test.go needs no change.
• TestParseServeConfig gives every row that names no catalog --catalog-repo https://github.com/example/catalog, the same way it already adds --state-memory. A noCatalog field turns that off for the row that tests the refusal.
• GitSource keeps no repo default. An empty Repo reaches gitsource, which already rejects it, so serve is the one place that validates the flags.

Verification

• make reviewable (PATH starting with the go1.26 golangci-lint and the claude/codex guard): passes (generated-code check, lint, go test -race, make catalog with 66 cases, 66 ok, 0 differ, and openapi-lint 100/100).
• gofmt -l $(git ls-files '*.go'): prints nothing.
• New TestParseServeConfig rows: no catalog (the exact message), empty repo, empty dir, and dev serve on the PoC catalog dir (--dev-fake-providers --catalog-dir internal/catalog/testdata/poc, the AGENTS.md command, gets past flag parsing). testConfig/TestServeEndToEnd still start serve on that directory. TestDefaults checks that GitSource{} has no repo and keeps main/catalog.
• The built binary: factory serve --state-memory with no catalog flag prints a catalog is required: pass --catalog-repo URL or --catalog-dir DIR and exits 2.
• run.sh: bash -n passes. A copy ran in a scratch tree with a stub bin/factory that prints its arguments (SKIP_BUILD=1, dummy .env values, so serve never started), in four cases. With no catalog variable it refuses with the message. With only FACTORY_CATALOG_REPO it passes --catalog-repo <repo> --catalog-ref main --catalog-path catalog. With _REF, _PATH and _APP_ID also set it passes them plus --catalog-app-key-ref ccf-factory-app/private-key. With FACTORY_CATALOG_DIR it passes only --catalog-dir.
• The README §4 recipe: a copy of catalog/ with the App IDs and skill refs patched gives 0 errors, 23 warnings, all of them CAT1200.
• Not checked here: a real start of run.sh against compliance-framework/factory-catalog with FACTORY_CATALOG_APP_ID and the real ccf-factory key. That needs the private repo, the App installed on it, and the real .env.

🤖 Generated with Claude Code

[gusfcarvalho]

ccf-review: COMMENT

no findings.

Stack (base-chain): #250 → #251 → #252