feat: support pkg meta file in dependency commands

cmd/crossplane/dependency/add.go

@@ -18,7 +18,6 @@ package dependency
 
 import (
 	"context"
-	"path/filepath"
 	"strings"
 
 	"github.com/google/go-containerregistry/pkg/name"
@@ -43,9 +42,12 @@ var addHelp string
 
 // addCmd adds a dependency to the current project.
 type addCmd struct {
-	Package     string `arg:""                      help:"Package to add (xpkg OCI reference, k8s:<version>, git repository URL, or HTTP(S) URL)."`
-	ProjectFile string `default:"${project_file}"   help:"Path to project definition file."                                                        short:"f"`
-	CacheDir    string `env:"CROSSPLANE_XPKG_CACHE" help:"Directory for cached xpkg package contents."                                             name:"cache-dir"`
+	CacheDir string `env:"CROSSPLANE_XPKG_CACHE" help:"Directory for cached xpkg package contents."                                             name:"cache-dir"`
+	Package  string `arg:""                      help:"Package to add (xpkg OCI reference, k8s:<version>, git repository URL, or HTTP(S) URL)."`
+
+	ProjectFile     string   `help:"Path to the project file or package metadata file (crossplane.yaml). Autodetected if not set."                                     optional:""             predictor:"yaml_file" short:"f" type:"path"`
+	SchemasDir      string   `help:"Directory for generated schemas, relative to the project file. Overrides the project's schemas path (default: schemas)."           name:"schemas-dir"`
+	SchemaLanguages []string `help:"Comma-separated schema languages to generate (go, json, kcl, python). Overrides the project's schemas.languages; defaults to all." name:"schema-languages"`
 
 	// Flags for specific dependency types.
 	APIOnly bool   `help:"Mark an xpkg dependency as API-only (not a runtime dependency)." name:"api-only"`
@@ -61,14 +63,10 @@ func (c *addCmd) Help() string {
 func (c *addCmd) Run(logger logging.Logger, sp terminal.SpinnerPrinter, cfg *config.Config) error {
 	ctx := context.Background()
 
-	projFilePath, err := filepath.Abs(c.ProjectFile)
-	if err != nil {
-		return err
-	}
-	projDirPath := filepath.Dir(projFilePath)
-	projFS := afero.NewBasePathFs(afero.NewOsFs(), projDirPath)
-
-	proj, err := projectfile.Parse(projFS, filepath.Base(c.ProjectFile))
+	proj, projFS, projFile, err := loadProject(c.ProjectFile, projectfile.Overrides{
+		SchemasDir:      c.SchemasDir,
+		SchemaLanguages: c.SchemaLanguages,
+	})
 	if err != nil {
 		return err
 	}
@@ -89,7 +87,7 @@ func (c *addCmd) Run(logger logging.Logger, sp terminal.SpinnerPrinter, cfg *con
 	resolver := clixpkg.NewResolver(client)
 
 	m := dependency.NewManager(proj, projFS,
-		dependency.WithProjectFile(c.ProjectFile),
+		dependency.WithProjectFile(projFile),
 		dependency.WithSchemaGenerators(generator.Filter(
 			generator.AllLanguages(
 				generator.WithGoModelAccessors(cfg.Features.GenerateGoModelAccessors),

cmd/crossplane/dependency/cache.go

@@ -19,7 +19,6 @@ package dependency
 import (
 	"context"
 	"fmt"
-	"path/filepath"
 
 	"github.com/alecthomas/kong"
 	"github.com/spf13/afero"
@@ -42,10 +41,14 @@ var updateHelp string
 
 // updateCacheCmd updates the dependency cache by regenerating all schemas.
 type updateCacheCmd struct {
-	ProjectFile string `default:"${project_file}"   help:"Path to project definition file."            short:"f"`
 	CacheDir    string `env:"CROSSPLANE_XPKG_CACHE" help:"Directory for cached xpkg package contents." name:"cache-dir"`
 	GitToken    string `env:"CROSSPLANE_GIT_TOKEN"  help:"Token for git HTTPS authentication."`
 	GitUsername string `default:"x-access-token"    env:"CROSSPLANE_GIT_USERNAME"                      help:"Username for git HTTPS authentication."`
+
+	ProjectFile     string   `help:"Path to the project file or package metadata file (crossplane.yaml). Autodetected if not set."                                                      optional:""             predictor:"yaml_file" short:"f" type:"path"`
+	SchemasDir      string   `help:"Directory for generated schemas, relative to the project file. Overrides the project's schemas path (default: schemas)."                            name:"schemas-dir"`
+	SchemaLanguages []string `help:"Comma-separated schema languages to generate (go, json, kcl, python). Overrides the project's schemas.languages; defaults to all."                  name:"schema-languages"`
+	K8sVersion      string   `help:"Kubernetes version to generate core API schemas for (e.g. v1.33.0). Replaces the project's k8s dependency for this run; never written to the file." name:"k8s-version"`
 }
 
 func (c *updateCacheCmd) Help() string {
@@ -56,14 +59,11 @@ func (c *updateCacheCmd) Help() string {
 func (c *updateCacheCmd) Run(logger logging.Logger, sp terminal.SpinnerPrinter, cfg *config.Config) error {
 	ctx := context.Background()
 
-	projFilePath, err := filepath.Abs(c.ProjectFile)
-	if err != nil {
-		return err
-	}
-	projDirPath := filepath.Dir(projFilePath)
-	projFS := afero.NewBasePathFs(afero.NewOsFs(), projDirPath)
-
-	proj, err := projectfile.Parse(projFS, filepath.Base(c.ProjectFile))
+	proj, projFS, projFile, err := loadProject(c.ProjectFile, projectfile.Overrides{
+		SchemasDir:      c.SchemasDir,
+		SchemaLanguages: c.SchemaLanguages,
+		K8sVersion:      c.K8sVersion,
+	})
 	if err != nil {
 		return err
 	}
@@ -84,7 +84,7 @@ func (c *updateCacheCmd) Run(logger logging.Logger, sp terminal.SpinnerPrinter,
 	resolver := clixpkg.NewResolver(client)
 
 	opts := []dependency.ManagerOption{
-		dependency.WithProjectFile(c.ProjectFile),
+		dependency.WithProjectFile(projFile),
 		dependency.WithSchemaGenerators(generator.Filter(
 			generator.AllLanguages(
 				generator.WithGoModelAccessors(cfg.Features.GenerateGoModelAccessors),
@@ -116,9 +116,11 @@ var cleanHelp string
 
 // cleanCacheCmd removes all generated schemas.
 type cleanCacheCmd struct {
-	ProjectFile  string `default:"${project_file}"                                                help:"Path to project definition file."            short:"f"`
 	CacheDir     string `env:"CROSSPLANE_XPKG_CACHE"                                              help:"Directory for cached xpkg package contents." name:"cache-dir"`
 	KeepPackages bool   `help:"Keep cached xpkg package contents; remove only generated schemas." name:"keep-packages"`
+
+	ProjectFile string `help:"Path to the project file or package metadata file (crossplane.yaml). Autodetected if not set."                           optional:""        predictor:"yaml_file" short:"f" type:"path"`
+	SchemasDir  string `help:"Directory for generated schemas, relative to the project file. Overrides the project's schemas path (default: schemas)." name:"schemas-dir"`
 }
 
 func (c *cleanCacheCmd) Help() string {
@@ -127,20 +129,13 @@ func (c *cleanCacheCmd) Help() string {
 
 // Run executes the clean-cache command.
 func (c *cleanCacheCmd) Run(k *kong.Context, _ logging.Logger) error {
-	projFilePath, err := filepath.Abs(c.ProjectFile)
-	if err != nil {
-		return err
-	}
-	projDirPath := filepath.Dir(projFilePath)
-	projFS := afero.NewBasePathFs(afero.NewOsFs(), projDirPath)
-
-	proj, err := projectfile.Parse(projFS, filepath.Base(c.ProjectFile))
+	proj, projFS, projFile, err := loadProject(c.ProjectFile, projectfile.Overrides{SchemasDir: c.SchemasDir})
 	if err != nil {
 		return err
 	}
 
 	m := dependency.NewManager(proj, projFS,
-		dependency.WithProjectFile(c.ProjectFile),
+		dependency.WithProjectFile(projFile),
 	)
 
 	if err := m.Clean(); err != nil {

cmd/crossplane/dependency/dependency.go

@@ -17,9 +17,36 @@ limitations under the License.
 // Package dependency contains commands for managing project dependencies.
 package dependency
 
+import (
+	"path/filepath"
+
+	"github.com/spf13/afero"
+
+	"github.com/crossplane/cli/v2/apis/dev/v1alpha1"
+	"github.com/crossplane/cli/v2/internal/project/projectfile"
+)
+
 // Cmd contains commands for dependency management.
 type Cmd struct {
-	Add         addCmd         `cmd:"" help:"Add a dependency to the current project."             novale:"Google.WordList[\"k8s\"],Google.Units,gitlab.Units"`
-	UpdateCache updateCacheCmd `cmd:"" help:"Update the dependency cache for the current project."`
+	Add         addCmd         `cmd:"" help:"Add a dependency to the current project."                        novale:"Google.WordList[\"k8s\"],Google.Units,gitlab.Units"`
+	UpdateCache updateCacheCmd `cmd:"" help:"Update the dependency cache for the current project or package."`
 	CleanCache  cleanCacheCmd  `cmd:"" help:"Clean the dependency cache."`
 }
+
+// loadProject finds and loads the project or package metadata file at path,
+// probing the working directory when path is empty.
+// projFS is rooted at the file's directory and projFile is the file's name within it.
+func loadProject(path string, o projectfile.Overrides) (proj *v1alpha1.Project, projFS afero.Fs, projFile string, err error) {
+	abs, err := projectfile.Resolve(path)
+	if err != nil {
+		return nil, nil, "", err
+	}
+	projFS = afero.NewBasePathFs(afero.NewOsFs(), filepath.Dir(abs))
+	projFile = filepath.Base(abs)
+
+	proj, err = projectfile.Load(projFS, projFile, o)
+	if err != nil {
+		return nil, nil, "", err
+	}
+	return proj, projFS, projFile, nil
+}

cmd/crossplane/dependency/help/add.md

@@ -19,6 +19,16 @@ dependencies. Use the `--api-only` flag to add a build-time xpkg dependency.
 
 Non-xpkg dependencies are always build-time dependencies.
 
+## Package metadata files
+
+The command can also add a dependency to `Configuration` package metadata (`crossplane.yaml`).
+When `-f` is not set, it uses `crossplane-project.yaml` in the current directory if present,
+otherwise `crossplane.yaml`.
+Package metadata only supports runtime xpkg dependencies, which are added to `spec.dependsOn`.
+Kubernetes, CRD, and `--api-only` dependencies require a project file.
+Use `--schemas-dir` to choose where schemas are generated (default `schemas`), and
+`--schema-languages` to generate only some languages (default all).
+
 ## Examples
 
 Retrieve the latest available semantic version of `provider-aws-eks`, generate

cmd/crossplane/dependency/help/clean-cache.md

@@ -1,3 +1,7 @@
 The `clean-cache` command removes all cached package images from the local cache
 directory and removes generated schemas. This can help free up disk space, force
 re-generation of schemas, or resolve issues with corrupted cache entries.
+
+Like `update-cache`, the command accepts a project file or a `Configuration`
+package metadata file (`crossplane.yaml`).
+Use `--schemas-dir` to select the schemas directory to remove when it differs from the default.

cmd/crossplane/dependency/help/update-cache.md

@@ -2,3 +2,44 @@ The `dependency update-cache` command updates the local dependency cache for the
 current project. It re-resolves semantic version constraints to specific
 versions (fetching newer versions if available), caches all dependencies, and
 re-generates language bindings (schemas) for them if needed.
+
+## Project and package metadata files
+
+The command reads dependencies from a project file (`crossplane-project.yaml`)
+or from Configuration package metadata (`crossplane.yaml`).
+When `-f` is not set, it uses `crossplane-project.yaml` in the current directory if present,
+otherwise `crossplane.yaml`.
+
+For package metadata, the xpkg dependencies listed in `spec.dependsOn` are cached.
+Schemas are written to the directory given by `--schemas-dir`, relative
+to the file (default `schemas`).
+For a project file, `--schemas-dir` overrides `paths.schemas`.
+
+Schemas are generated for all supported languages unless `--schema-languages`
+lists a subset (`go`, `json`, `kcl`, `python`).
+For a project file, the flag overrides `spec.schemas.languages`.
+
+Package metadata can't declare Kubernetes core API dependencies.
+Use `--k8s-version` to generate schemas for them (for example `ServiceAccount` or `ConfigMap`).
+For a project file, the flag replaces its `k8s` dependency. The file is never changed.
+
+## Examples
+
+Update the cache and generate schemas for the dependencies of a Configuration
+package, writing schemas to `gen/schemas`:
+
+```shell
+crossplane dependency update-cache -f crossplane.yaml --schemas-dir gen/schemas
+```
+
+Generate only Python schemas:
+
+```shell
+crossplane dependency update-cache -f crossplane.yaml --schema-languages python
+```
+
+Also generate Python schemas for the Kubernetes v1.37.0 core APIs:
+
+```shell
+crossplane dependency update-cache -f crossplane.yaml --schema-languages python --k8s-version v1.37.0
+```

cmd/crossplane/render/xr/cmd.go

@@ -399,9 +399,9 @@ func (c *Cmd) loadFunctions(ctx context.Context, log logging.Logger, sp terminal
 		return fns, nil
 	}
 
-	filePath, err := c.resolveProjectFile()
+	filePath, err := projectfile.Resolve(c.ProjectFile)
 	if err != nil {
-		return nil, err
+		return nil, errors.Wrap(err, "functions argument is required when not in a project or configuration")
 	}
 
 	dir := filepath.Dir(filePath)
@@ -420,28 +420,6 @@ func (c *Cmd) loadFunctions(ctx context.Context, log logging.Logger, sp terminal
 	return c.loadFunctionsFromConfiguration(ctx, log, fs, fileName)
 }
 
-// resolveProjectFile returns the absolute path of the project or configuration
-// file to use. When the user supplied an explicit --project-file, that path is
-// used as-is. Otherwise it probes for crossplane-project.yaml and then
-// crossplane.yaml in the working directory.
-func (c *Cmd) resolveProjectFile() (string, error) {
-	if c.ProjectFile != "" {
-		return filepath.Abs(c.ProjectFile)
-	}
-
-	for _, name := range []string{clixpkg.ProjectFile, runtimexpkg.MetaFile} {
-		abs, err := filepath.Abs(name)
-		if err != nil {
-			return "", errors.Wrapf(err, "cannot determine path for %q", name)
-		}
-		if _, err := os.Stat(abs); err == nil {
-			return abs, nil
-		}
-	}
-
-	return "", errors.New("functions argument is required when not in a project or configuration")
-}
-
 func (c *Cmd) newClientAndResolver(extraOpts ...clixpkg.ClientOption) (runtimexpkg.Client, *clixpkg.Resolver, error) {
 	cacheDir := c.CacheDir
 	if cacheDir == "" {

internal/dependency/manager.go

@@ -311,8 +311,18 @@ func runtimeGVKForPackage(pkg *runtimexpkg.Package) (*schema.GroupVersionKind, e
 }
 
 // AddDependency adds a dependency, generates schemas for it, and persists the
-// dependency to the project file.
+// dependency to the project file, or to spec.dependsOn when the file is
+// Configuration package metadata.
 func (m *Manager) AddDependency(ctx context.Context, dep *v1alpha1.Dependency) error {
+	isProject, err := projectfile.IsProjectFile(m.projFS, m.projFile)
+	if err != nil {
+		return err
+	}
+	// Package metadata can only express runtime xpkg dependencies.
+	if !isProject && (dep.Xpkg == nil || dep.Xpkg.APIOnly) {
+		return errors.New("package metadata files support only runtime xpkg dependencies; use a project file for k8s, CRD, or API-only dependencies")
+	}
+
 	gvk, err := m.addDependencyNoWrite(ctx, dep, false)
 	if err != nil {
 		return err
@@ -330,6 +340,9 @@ func (m *Manager) AddDependency(ctx context.Context, dep *v1alpha1.Dependency) e
 	defer m.updateMutex.Unlock()
 
 	upsertDependency(m.proj, *dep)
+	if !isProject {
+		return projectfile.UpsertConfigurationDependency(m.projFS, m.projFile, *dep.Xpkg)
+	}
 	return projectfile.Update(m.projFS, m.projFile, func(p *v1alpha1.Project) {
 		upsertDependency(p, *dep)
 	})

internal/dependency/manager_test.go

@@ -38,6 +38,7 @@ import (
 
 	"github.com/crossplane/cli/v2/apis/dev/v1alpha1"
 	"github.com/crossplane/cli/v2/internal/async"
+	"github.com/crossplane/cli/v2/internal/project/projectfile"
 	"github.com/crossplane/cli/v2/internal/schemas/generator"
 	clixpkg "github.com/crossplane/cli/v2/internal/xpkg"
 )
@@ -1013,3 +1014,67 @@ func TestManager_AddDependency_TransitiveNotPersisted(t *testing.T) {
 		t.Errorf("on-disk project deps (-want +got):\n%s", diff)
 	}
 }
+
+func TestManager_AddDependency_PackageMetadata(t *testing.T) {
+	const (
+		prov   = "xpkg.example/prov"
+		digest = "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03"
+		meta   = `apiVersion: meta.pkg.crossplane.io/v1
+kind: Configuration
+metadata:
+  name: test-config
+`
+	)
+
+	fc := &fakeClient{
+		packages: map[string]*runtimexpkg.Package{
+			prov + ":v0.1.0": makePackageWithBody(t, prov, digest, "", providerPackageYAML),
+		},
+		tags: []string{"v0.1.0"},
+	}
+
+	projFS := afero.NewMemMapFs()
+	if err := afero.WriteFile(projFS, "crossplane.yaml", []byte(meta), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	proj, err := projectfile.Load(projFS, "crossplane.yaml", projectfile.Overrides{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	m := NewManager(proj, projFS,
+		WithProjectFile("crossplane.yaml"),
+		WithSchemaFS(afero.NewMemMapFs()),
+		WithSchemaGenerators([]generator.Interface{}),
+		WithXpkgClient(fc),
+		WithResolver(clixpkg.NewResolver(fc)),
+	)
+
+	if err := m.AddDependency(context.Background(), xpkgDep(prov, "v0.1.0")); err != nil {
+		t.Fatalf("AddDependency: %v", err)
+	}
+
+	// The dependency is persisted to spec.dependsOn and loads back.
+	got, err := projectfile.Load(projFS, "crossplane.yaml", projectfile.Overrides{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []v1alpha1.Dependency{{
+		Type: v1alpha1.DependencyTypeXpkg,
+		Xpkg: &v1alpha1.XpkgDependency{
+			APIVersion: "pkg.crossplane.io/v1",
+			Kind:       "Provider",
+			Package:    prov,
+			Version:    "v0.1.0",
+		},
+	}}
+	if diff := cmp.Diff(want, got.Spec.Dependencies); diff != "" {
+		t.Errorf("on-disk deps (-want +got):\n%s", diff)
+	}
+
+	// Dependencies package metadata can't express are rejected.
+	k8s := &v1alpha1.Dependency{Type: v1alpha1.DependencyTypeK8s, K8s: &v1alpha1.K8sDependency{Version: "v1.33.0"}}
+	if err := m.AddDependency(context.Background(), k8s); err == nil {
+		t.Error("expected error adding k8s dependency to package metadata, got nil")
+	}
+}