Skip to content

Add pkg/cli and pkg/project for embedding crossplane commands in other CLIs - #544

Open
haarchri wants to merge 8 commits into
crossplane:mainfrom
haarchri:feat/project-library-api
Open

haarchri wants to merge 8 commits into
crossplane:mainfrom
haarchri:feat/project-library-api

Conversation

@haarchri

Copy link
Copy Markdown
Member

Description of your changes

This PR adds a small, supported surface for other CLIs and tools to embed the crossplane CLI's project-related commands and machinery instead of reimplementing them:

  • Exported command types (cmd/crossplane/project, etc.): the project subcommand structs (InitCmd, BuildCmd, SimulateCmd, …) are exported so a host CLI can mount them in its own kong command tree.
  • pkg/cli — the glue a host needs to run embedded commands: the kong Vars/bindings their struct tags and Run methods expect, config loading, spinner printer constructors, maturity gating (ApplyMaturity), and SilentExit for commands that report results via exit codes.
  • pkg/project — the project machinery: ParseProject, Build (with options for concurrency, caching, auth, event reporting), SortImages, AddSchemas (merge a host's own CRDs into the generated models), DependencySchemas (the raw CRD/OpenAPI resources of a project's crd/k8s dependencies, e.g. for validating rendered output), and the schema runner for language tooling.
  • Build options for concerns a host may carry outside the project file: extra package metadata annotations (applied before function dependency digests are computed), gitignore-style build exclusions, and extra env prefixes forwarded to language tooling containers.
    The pkg/cli / pkg/project split follows the suggestion from earlier discussion: terminal/config/kong glue in one package, project machinery in the other.

Downstream CLIs that support crossplane projects currently either shell out or fork the implementation, which drifts. Exposing a narrow facade keeps one implementation of project parsing, building, and schema generation, while hosts keep their own UX.

  • The facade wraps internal packages with type aliases and thin functions; internals stay internal and can keep moving — the facade is the compatibility line.
  • Build returns the image map and dependency digests rather than writing files, so hosts can push, sideload, or post-process (only the configuration image is safe to mutate afterward — function images are referenced by digest from the configuration's metadata).
  • No behavior changes for the crossplane CLI itself; this is additive.

the git proxy options from #543 will be exposed through BuildOptions in a follow-up once both merge

Fixes #

I have:

Need help with this checklist? See the cheat sheet.

Validation

Existing unit tests pass; the exports are exercised end-to-end by the downstream consumer (project init/build/push/test flows, schema generation for host CRDs, dependency schema validation).

@haarchri
haarchri requested review from a team, jcogilvie and tampakrap as code owners November 18, 2026 13:58
@haarchri
haarchri requested review from bobh66 and removed request for a team November 18, 2026 13:58
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 17 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 3a126a7 and 55d532c.

Files selected for processing: 17

  • cmd/crossplane/project/build.go
  • cmd/crossplane/project/build_test.go
  • cmd/crossplane/project/init.go
  • cmd/crossplane/project/project.go
  • cmd/crossplane/project/push.go
  • cmd/crossplane/project/run.go
  • cmd/crossplane/project/simulate.go
  • cmd/crossplane/project/simulate_test.go
  • cmd/crossplane/project/stop.go
  • internal/docker/docker.go
  • internal/project/build.go
  • internal/project/ignore.go
  • internal/schemas/runner/run.go
  • internal/xpkg/client.go
  • pkg/cli/cli.go
  • pkg/cli/cli_test.go
  • pkg/project/project.go
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@codecov

codecov Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 21.05263% with 180 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.41%. Comparing base (c1738aa) to head (55d532c).
⚠️ Report is 5 commits behind head on main.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Rename initCmd/buildCmd/pushCmd/runCmd/simulateCmd/stopCmd to exported
names so other CLIs can compose individual
project subcommands into their own Kong command trees instead of
reimplementing them.
other CLIs can embed the exported command structs
from cmd/crossplane in their own Kong trees, but those commands' Run
methods take types from internal packages (terminal.SpinnerPrinter,
config.Config) and reference kong.Vars set up by crossplane's main.
pkg/cli exposes exactly that contract: type aliases, constructors,
Vars/Options/BindRuntime helpers, and a Build/ParseProject/SortImages
facade so hosts can build projects in-process and consume the resulting
image map directly.

Also expose a keychain option on the xpkg client so hosts can
authenticate dependency fetches from private registries.

Signed-off-by: Christopher Haar <chhaar30@googlemail.com>
Host CLIs have their own meta APIs whose models
must merge into the same generated models module as the project's
dependencies and APIs, so language tests can import both. Expose the
schema manager's Add through the facade.

Signed-off-by: Christopher Haar <christopher.haar@upbound.io>
pkg/cli keeps the terminal, configuration, and Kong binding helpers for
embedding crossplane commands; the project-specific surface (parse,
build, schema generation) moves to pkg/project. Also export the schema
runner so host CLIs can execute language tooling (e.g. language-based
tests) with the same container machinery used for schema generation.

Signed-off-by: Christopher Haar <christopher.haar@upbound.io>
The runner only forwarded CROSSPLANE_-prefixed environment variables to
the language tooling containers. Host CLIs need their own variables
visible there too - e.g. up's e2e test manifests read cloud credentials
from UP_-prefixed variables - so make the prefixes extensible.

Signed-off-by: Christopher Haar <christopher.haar@upbound.io>
Embedded commands can return a silent ExitError to report a result such
as simulate finding changes; hosts need SilentExit to exit with its code
without printing an empty error line.

Signed-off-by: Christopher Haar <christopher.haar@upbound.io>
Host CLIs can carry package metadata and build exclusions outside the
project file (e.g. up's upbound-project.yaml extensions). Add build
options to apply extra annotations to the configuration and function
package metadata - before function dependency digests are computed - and
to exclude gitignore-style patterns from resource collection.

Signed-off-by: Christopher Haar <christopher.haar@upbound.io>
Expose the raw schema resources (CRD manifests, OpenAPI documents) of a
project's crd and k8s dependencies, fetched from the same sources the
dependency manager generates language schemas from. Hosts use them to
validate rendered resources against those dependencies' types.

Signed-off-by: Christopher Haar <christopher.haar@upbound.io>
@haarchri
haarchri force-pushed the feat/project-library-api branch from e25e1e7 to 55d532c Compare November 18, 2026 14:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant