diff --git a/README.md b/README.md index 1fb1ad0..18e6101 100644 --- a/README.md +++ b/README.md @@ -1,111 +1,294 @@ # rc-cli -Runtime Conditions commands for extension bindings and workload profiling. -## Build locally +`rc-cli` is the Runtime Conditions CLI. A Runtime Conditions Profile is a portable, machine-readable list of what one workload needs at runtime: the APIs, caches, datastores, and environment configuration it depends on. -From this repository's root, build the executable with the schema-aware helper: +`rc-cli` generates Runtime Conditions Profiles from your workload's binding declarations and validates profiles against the spec and the extensions it declares, whether the profile was written by hand, by an agent, or by a profiler. The profile states the demand; platforms and adapters such as Kratix, Crossplane, and Radius decide how to fulfill it. + +- Guide and concepts: +- Profile specification: + +## Install + +The package is named `rc-cli`. The executable is named `rc`. + +**Homebrew (macOS and Linux):** ```sh -go run ./scripts/build.go --output ./rc -./rc --version -./rc profile generate --dir /path/to/go/workload --out profile.yaml +brew install runtimeconditions/tools/rc-cli ``` -The helper downloads the pinned core profile schema, verifies its SHA-256, -and embeds it alongside the linked Go profiler. Go profiling needs no runtime -schema download or separate profiler installation. Analyzing a workload requires -a working Go toolchain and its binding dependencies. CI builds with Go 1.26.5 -and tests workload analysis with Go 1.25.0. +**Linux packages (apt / dnf / yum):** configure the signed package source once, then install +with your package manager: + +```sh +curl -fsSL https://runtimeconditions.io/packages/setup.sh | sudo sh +sudo apt install rc-cli # Debian / Ubuntu +sudo dnf install rc-cli # Fedora / RHEL +``` -A plain `go build` or `go install` omits the schema linker value. Such a binary -can display help and version information, but profile generation fails with -`rc: installed profiler has no verified core profile schema`. -Rebuild it using the command above and run the resulting `./rc` executable. +Language profilers are separate add-ons. A profiler reads your workload's code and +generates its profile: -For a build using an already downloaded schema, supply the approved artifact: +- Go profiling is built into `rc`, so Go workloads need nothing else. +- TypeScript, Java, and Python profilers install through their own channels; see [Optional language profilers](#optional-language-profilers). + +**From source:** see [Build from source](#build-from-source). + +## Commands + +Check the installation and see which profilers are available: ```sh -go run ./scripts/build.go --output ./rc \ - --core-schema /path/to/runtimeconditions.profile.schema.yaml +rc --version ``` -The local schema must match the helper's pinned checksum. Release builds also -pass `--version ` and `--commit ` to embed provenance. +```text +rc v0.6.0 (a1b2c3d) +``` -## Built-in Go profiler commands +```sh +rc plugins list +``` -`rc profile` uses the built-in Go profiler by default. The same commands are -available under `rc profile go`, with identical flags and behavior: +```text +LANGUAGE STATUS VERSION PATH +go built-in v0.8.0 +typescript missing +java missing +python missing +``` -| Command | Purpose | -| --- | --- | -| `rc profile generate` | Generate a validated profile from Go binding declarations. | -| `rc profile validate-extensions` | Validate all imported generated binding packages. | -| `rc profile validate-extension` | Validate one imported binding package selected with `--package`. | -| `rc profile version` | Show the linked Go profiler version. | +`rc plugins list --output yaml` adds each missing add-on's install command. +`rc --help` lists all commands; `rc completion ` prints a shell +completion script. + +## Quickstart: validate an existing profile -A profile does not have to come from a profiler. To check one written by hand, or by an agent: +This is the one hands-on step that works on a fresh install. It checks a committed demo profile. +It does not create a profile yet: ```sh -./rc profile validate profile.yaml +git clone https://github.com/runtimeconditions/rc-demos.git +rc profile validate rc-demos/artifacts/request-logger-http.profile.yaml ``` -It is checked against the core profile schema embedded in rc and against the definitions of the -extensions it declares (downloaded from their ids, or read from `--catalog` directories). +```text +runtimeconditions: profile validated +``` -For command help: +`rc profile validate` checks any profile file against the core schema embedded in `rc` and +against the definitions of the extensions the profile declares. By default those definitions +are downloaded from the `https` ids the profile names. To work offline or against local +definitions instead, pass one or more catalog directories: ```sh -./rc profile --help -./rc profile go --help -./rc profile go generate --help +rc profile validate profile.yaml --catalog ./my-extensions +rc profile validate - < profile.yaml # read the profile from stdin +``` + +## Generating a profile + +`rc profile generate` reads the Go binding declarations in a workload and writes a validated +profile. It analyzes declarations statically — it never runs your code. Three prerequisites: + +1. **A Go toolchain on `PATH`.** Without one, generation fails with + `exec: "go": executable file not found in $PATH`. `rc` does not download Go for you. +2. **`--dir` must point at a directory containing a `go.mod`.** Current releases fail fast: + + ```text + rc: /path/to/dir: workload must have a go.mod: stat /path/to/dir/go.mod: no such file or directory + ``` + + Older releases (for example the Homebrew v0.6.0 build) fell back to GOPATH mode and scanned + your entire home directory, spraying `operation not permitted` errors for TCC-protected + paths. Always point `--dir` at a Go module. +3. **The workload must import published RC binding modules** (`runtimeconditions.io/x/rc/...`). + Bindings wired with `go.mod` `replace` directives to a local clone are rejected **by + design**: + + ```text + rc: github.com/runtimeconditions/extensions/catalog/rc/common-integrations/go uses a go.mod replace; generated bindings must resolve to a published module version + ``` + + This is why a fresh clone of `rc-demos/apps/request-logger-http` cannot be generated: its + `go.mod` replaces the binding modules with a sibling checkout of `extensions`. Generate + from a module that requires the published versions instead. + +### Example workload + +`go.mod`: + +```go +module example.com/my-service + +go 1.25.0 + +require ( + runtimeconditions.io/x/rc/common v0.3.0 + runtimeconditions.io/x/rc/env v0.3.0 +) ``` -Generate a profile using the default or explicit Go route: +`main.go` — declare conditions with the published binding packages: + +```go +package main + +import ( + "runtimeconditions.io/x/rc/common" + "runtimeconditions.io/x/rc/env" +) + +var todosAPI = common.Api( + common.Http{ + Spec: &common.Spec{Format: common.FormatOpenapi, Uri: "catalog://api/default/todos-api"}, + Operations: common.HttpOperations{ + {Method: common.MethodGet, Path: "/todos/{id}", + ResponseSchema: common.ResponseSchemaMap{"id": common.SimpleSchemaStringInteger}}, + }, + }, + env.HttpConfiguration{ + Env: env.HttpConfigurationEnv{ + {Name: "TODOS_API_URL", Property: env.HttpConfigurationEnvPropertyBaseUrl}, + }, + }, +) + +var requestCache = common.Cache( + common.KeyValue{Engine: &[]common.KeyValueEngine{common.KeyValueEngineRedis}[0]}, + env.KeyValueConfiguration{ + Env: env.KeyValueConfigurationEnv{ + {Name: "REDIS_URL", Property: env.KeyValueConfigurationEnvPropertyUrl}, + }, + }, +) + +func main() {} +``` + +Resolve dependencies, then generate: ```sh -./rc profile generate --dir /path/to/go/workload --out profile.yaml +go mod tidy +rc profile generate --dir ./my-service --out profile.yaml +``` -./rc profile go generate \ - --dir /path/to/go/workload \ - --name my-workload \ - --workload-uri https://example.com/my-workload \ +Defaults: `--dir` is the current directory, `--out` is stdout, `--name` is the directory's +basename, `--workload-uri` is the enclosing Go module path, `--workload-version` is `dev`. +A failed generation leaves an existing `--out` file unchanged. You can set them explicitly: + +```sh +rc profile generate \ + --dir ./my-service \ + --name my-service \ + --workload-uri https://example.com/my-service \ --workload-version 1.0.0 \ --out profile.yaml ``` -`--dir` defaults to the current directory. Generation writes YAML to stdout -when `--out` is omitted. The default profile name is the workload directory's -basename; the default workload URI is its enclosing Go module path, falling -back to the directory path. The workload version defaults to `dev`. +**Verified status today:** a workload importing only `runtimeconditions.io/x/rc/common@v0.3.0` +generates a profile that passes `rc profile validate`, end to end. Adding +`runtimeconditions.io/x/rc/env@v0.3.0` currently fails dependency artifact verification with: -Validate imported bindings or inspect the profiler version: +```text +rc: runtimeconditions.io/x/rc/env dependency runtimeconditions.io/x/rc/common: dependency Go module archive SHA-256 mismatch +``` + +The published-module pattern above is the supported direction; treat that error as a +known gap in the current published `env` release, not as a mistake in your workload. + +### Checking a workload's bindings ```sh -./rc profile go validate-extensions --dir /path/to/go/workload -./rc profile go validate-extension \ - --dir /path/to/go/workload \ - --package runtimeconditions.io/x/rc/common -./rc profile go version +rc profile validate-extensions --dir ./my-service +rc profile validate-extension --dir ./my-service --package runtimeconditions.io/x/rc/common +rc profile go version # linked Go profiler version, e.g. "go-rc-profiler v0.8.0 (linked into rc)" ``` -Profiling analyzes declarations without executing the workload. Resolve the -workload's Go binding dependencies before running these commands. A failed -generation leaves an existing `--out` file unchanged. +## Command reference + +`rc profile` uses the built-in Go profiler by default. The same commands are available under +`rc profile go`, with identical flags and behavior: + +| Command | Purpose | +| --- | --- | +| `rc profile generate` | Generate a validated profile from Go binding declarations. Flags: `--dir` (default `.`), `--name`, `--workload-uri`, `--workload-version` (default `dev`), `--out` (default stdout). | +| `rc profile validate ` | Validate any profile against the embedded core schema and its extensions. Flags: `--catalog` (repeatable). | +| `rc profile validate-extensions` | Validate all imported generated binding packages. Flag: `--dir`. | +| `rc profile validate-extension` | Validate one imported binding package. Flags: `--dir`, `--package`. | +| `rc profile version` | Show the linked Go profiler version. | +| `rc plugins list [--output yaml]` | Show the Go profiler and each add-on's status, version, and path. | +| `rc version [--output text\|yaml]` | Show CLI build information. `rc --version` prints the same one-liner. | +| `rc completion ` | Print a shell completion script. | + +For full flag lists: +```sh +rc profile --help +rc profile go --help +rc profile go generate --help +rc bindings --help +``` + +### Binding commands + +`rc bindings` resolves, generates, and verifies extension bindings. The command group +provides `resolve`, `normalize`, `generate`, `verify`, `package`, `plan-release`, `check`, +and `update`. Cobra owns help, completion, and flag parsing; execution uses the shared +binding library from `extensions`. + +Binding commands also require the shared YAML schemas. Installed layouts place them under +`share/rc/extension-bindings/model/`, alongside `bin/rc`. CI stages these files from the +exact `extensions` commit in `distribution/components.lock.yaml`. + +For local binding development, supply `--tooling-dir` pointing to matching schema resources, +such as the `tooling/extension-bindings` directory in a checkout of that pinned revision: + +```sh +rc bindings generate \ + --packages /path/to/binding-project/packages.yaml \ + --toolchain-lock /path/to/binding-project/toolchain.lock.yaml \ + --tooling-dir /path/to/extensions/tooling/extension-bindings \ + --core-schema /path/to/runtimeconditions.profile.schema.yaml \ + --output /tmp/generated-bindings +``` + +`packages.yaml` selects extension roots, language targets, and native package versions. +`toolchain.lock.yaml` declares the applicable toolchain constraints. Use repeatable +`--target package-key:language` flags to limit the selected targets. `generate` requires a +new or empty output directory. `verify --input` accepts the generated tree; use the same +catalog and resource flags for these commands. `update` verifies candidates before changing +committed binding directories; `check` compares regenerated content without updating those +files. Other shared flags include `--cache`, `--work-dir`, `--catalog-root`, +`--dependency-lock`, `--extension-root`, and `--extension-override`; see +`rc bindings generate --help` for the full list. + +The core schema must match the version declared in the package catalog. Without +`--core-schema`, normalization uses upstream core-schema resolution. Offline generation +also requires locally available extension definitions; native package verification and +profiling require resolved package dependencies and Go. + +The normalizer and Go emitter run as linked libraries. Explicit executable overrides for +those tools (`--normalizer`, `--go-emitter`) conflict with this mode. For binding +provenance, `--go-profiler /absolute/path/to/go-rc-profiler` selects a standalone profiler +file; otherwise the linked profiler's actual module version and checksum are recorded. The +`rc profile` commands always use the linked Go profiler. ## Optional language profilers Other languages run a separate add-on that `rc` finds on `PATH`. It can come from the -language's own tooling or from a system package, and `rc` does not care which. The -TypeScript profiler is on npm for developers who want it in their npm scripts: -`npm install --global @runtimeconditions/typescript-profiler`. The Java profiler is a jar that its -launcher, `rc-profiler-java`, runs; download it from the -[releases](https://github.com/runtimeconditions/java-rc-profiler/releases) of -`runtimeconditions/java-rc-profiler` and put the launcher on `PATH`. The Python profiler is on PyPI as -`runtimeconditions-profiler`; install it with `pip` into the workload's own virtual environment, because it finds -binding packages through that environment's metadata, and put the environment's `bin` directory on `PATH`. System packages for Homebrew, -apt, and yum, so that `rc` and its add-ons install the same way on a build server, are planned. +language's own tooling or from a system package, and `rc` does not care which: + +- **TypeScript:** `npm install --global @runtimeconditions/typescript-profiler`, or + `brew install runtimeconditions/tools/rc-profiler-typescript`. +- **Java:** download the launcher `rc-profiler-java` from the + [releases](https://github.com/runtimeconditions/java-rc-profiler/releases) of + `runtimeconditions/java-rc-profiler` and put it on `PATH`, or + `brew install runtimeconditions/tools/rc-profiler-java`. +- **Python:** `pip install runtimeconditions-profiler` into the workload's own virtual + environment — it finds binding packages through that environment's metadata — and put the + environment's `bin` directory on `PATH`. Do not use `pipx`, which would give it an + environment of its own. | Command | Purpose | | --- | --- | @@ -114,79 +297,73 @@ apt, and yum, so that `rc` and its add-ons install the same way on a build serve | `rc profile python [flags]` | Run the installed Python profiler. | | `rc plugins list [--output yaml]` | Show the Go profiler and each add-on's status, version, and path. | -Everything after `typescript`, `java`, or `python` goes to the add-on unchanged, so it keeps its own flags -(for example `--project` instead of `--dir`, and `--classpath` for Java). `rc` looks for -`rc-profiler-typescript`, then `runtimeconditions-typescript-profiler`, or `rc-profiler-java`, or -`runtimeconditions-python-profiler`, on `PATH`; `RC_TYPESCRIPT_PROFILER`, `RC_JAVA_PROFILER`, or -`RC_PYTHON_PROFILER` can name an absolute path instead. It runs the add-on only -if `--version --json` lists the core profile schema `rc` targets (0.4.0). The add-on's output and exit -status pass through. +Everything after `typescript`, `java`, or `python` goes to the add-on unchanged, so it keeps +its own flags (for example `--project` instead of `--dir`, and `--classpath` for Java). `rc` +looks for `rc-profiler-typescript`, then `runtimeconditions-typescript-profiler`, or +`rc-profiler-java`, or `runtimeconditions-python-profiler`, on `PATH`; +`RC_TYPESCRIPT_PROFILER`, `RC_JAVA_PROFILER`, or `RC_PYTHON_PROFILER` can name an absolute +path instead. It runs the add-on only if `--version --json` lists the core profile schema +`rc` targets (0.4.0). The add-on's output and exit status pass through. -The Java launcher chooses the JDK, not `rc`: `RC_JAVA_HOME`, then `JAVA_HOME`, then the runtime bundled -in its system package, then `java` on `PATH`. It needs JDK 17 or newer and says so when none is found. +The Java launcher chooses the JDK, not `rc`: `RC_JAVA_HOME`, then `JAVA_HOME`, then the +runtime bundled in its system package, then `java` on `PATH`. It needs JDK 17 or newer and +says so when none is found. -The Python profiler runs on the interpreter of the environment it is installed in (Python 3.11 or newer), and -sees the binding packages installed there. Install the profiler next to the bindings the workload imports, not -with `pipx`, which would give it an environment of its own. +The Python profiler runs on the interpreter of the environment it is installed in (Python +3.11 or newer), and sees the binding packages installed there. -## Binding commands +## Build from source + +From this repository's root, build the executable with the schema-aware helper: ```sh -./rc bindings --help -./rc bindings generate --help +go run ./scripts/build.go --output ./rc +./rc --version +./rc profile generate --dir /path/to/go/workload --out profile.yaml ``` -The command group provides `resolve`, `normalize`, `generate`, `verify`, -`package`, `plan-release`, `check`, and `update`. Cobra owns help, completion, -and flag parsing; execution uses the shared binding library from `extensions`. +The helper downloads the pinned core profile schema, verifies its SHA-256, and embeds it +alongside the linked Go profiler. Go profiling needs no runtime schema download or separate +profiler installation. Analyzing a workload requires a working Go toolchain and its binding +dependencies. CI builds with Go 1.26.5 and tests workload analysis with Go 1.25.0. -Binding commands also require the shared YAML schemas. Installed layouts place -them under `share/rc/extension-bindings/model/`, alongside `bin/rc`. CI stages -these files from the exact `extensions` commit in -`distribution/components.lock.yaml`; they remain ordinary YAML files. +A plain `go build` or `go install` omits the schema linker value. Such a binary can display +help and version information, but profile generation fails with +`rc: installed profiler has no verified core profile schema`. Rebuild it using the command +above and run the resulting `./rc` executable. -The local build helper builds the executable. For local binding development, -supply `--tooling-dir` pointing to matching schema resources, such as the -`tooling/extension-bindings` directory in a checkout of that pinned revision: +For a build using an already downloaded schema, supply the approved artifact: ```sh -./rc bindings generate \ - --packages /path/to/binding-project/packages.yaml \ - --toolchain-lock /path/to/binding-project/toolchain.lock.yaml \ - --tooling-dir /path/to/extensions/tooling/extension-bindings \ - --core-schema /path/to/runtimeconditions.profile.schema.yaml \ - --output /tmp/generated-bindings +go run ./scripts/build.go --output ./rc \ + --core-schema /path/to/runtimeconditions.profile.schema.yaml ``` -`packages.yaml` selects extension roots, language targets, and native package -versions. `toolchain.lock.yaml` declares the applicable toolchain constraints. -Use repeatable `--target package-key:language` flags to limit the selected targets. -`generate` requires a new or empty output directory. `verify --input` accepts the -generated tree; use the same catalog and resource flags for these commands. -`update` verifies candidates before changing committed binding -directories; `check` compares regenerated content without updating those files. +The local schema must match the helper's pinned checksum. Release builds also pass +`--version ` and `--commit ` to embed provenance. -The core schema must match the version declared in the package catalog. Without -`--core-schema`, normalization uses upstream core-schema resolution. Offline -generation also requires locally available extension definitions; native package -verification and profiling require resolved package dependencies and Go. - -The normalizer and Go emitter run as linked libraries. Explicit executable -overrides for those tools conflict with this mode. For binding provenance, -`--go-profiler /absolute/path/to/go-rc-profiler` selects a standalone profiler -file; otherwise the linked profiler's actual module version and checksum are -recorded. The `rc profile` commands always use the linked Go profiler. - -## CI coverage and distribution - -CI tests Linux and macOS on amd64 and arm64. It relocates the staged executable -and YAML resources, exercises all eight binding operations, installs a freshly -generated Go module through a local proxy, and profiles its declarations through -both Go command routes. Negative checks cover altered committed source, nonempty -output directories, and invalid declarations preserving existing profile output. -Only Go is available on the smoke test's subprocess PATH; Python is used by the -CI harness, and is not a runtime dependency of Go binding or profiling commands. - -The small extension fixture is checked in as YAML under `testdata/ci/bindings/`. -Generated packages, archives, profiles, and module caches remain temporary CI -outputs. Homebrew/APT packaging and optional profiler add-ons remain planned. +CI tests Linux and macOS on amd64 and arm64. It relocates the staged executable and YAML +resources, exercises all eight binding operations, installs a freshly generated Go module +through a local proxy, and profiles its declarations through both Go command routes. +Negative checks cover altered committed source, nonempty output directories, and invalid +declarations preserving existing profile output. The small extension fixture is checked in as +YAML under `testdata/ci/bindings/`; generated packages, archives, profiles, and module caches +remain temporary CI outputs. Homebrew and APT/RPM packaging live in +[`homebrew-tools`](https://github.com/runtimeconditions/homebrew-tools) and +[`packages`](https://github.com/runtimeconditions/packages). + +## Ecosystem map + +| Repository | What it is | +| --- | --- | +| [spec](https://github.com/runtimeconditions/spec) | The Runtime Conditions Profile specification and supporting docs. | +| [extensions](https://github.com/runtimeconditions/extensions) | First-party extension definitions and the shared binding tooling. | +| [rc-demos](https://github.com/runtimeconditions/rc-demos) | End-to-end demos, including the `request-logger-http` app and its committed profile. | +| [go-rc-profiler](https://github.com/runtimeconditions/go-rc-profiler) | Go AST profiler; linked into `rc`, also usable standalone. | +| [ts-rc-profiler](https://github.com/runtimeconditions/ts-rc-profiler) | TypeScript profiler add-on (`rc profile typescript`). | +| [java-rc-profiler](https://github.com/runtimeconditions/java-rc-profiler) | Java profiler add-on (`rc profile java`). | +| [python-rc-profiler](https://github.com/runtimeconditions/python-rc-profiler) | Python profiler add-on (`rc profile python`). | +| [ebpf-rc-profiler](https://github.com/runtimeconditions/ebpf-rc-profiler) | Infers external dependencies by watching syscall and network traffic instead of reading bindings. | +| [backstage-plugin](https://github.com/runtimeconditions/backstage-plugin) | Backstage plugin for Runtime Conditions Profiles. | +| [homebrew-tools](https://github.com/runtimeconditions/homebrew-tools) | Homebrew tap (`runtimeconditions/tools`). | +| [packages](https://github.com/runtimeconditions/packages) | Signed apt/dnf/yum package source and `setup.sh`. |