feat: add trestle beta command (#2267)

* feat: add trestle beta command

Signed-off-by: Matteo Fari <matteofari06@gmail.com>
Signed-off-by: degenaro <lou.degenaro@gmail.com>

* fix: --beta to give warning & not part of version

Signed-off-by: degenaro <lou.degenaro@gmail.com>

---------

Signed-off-by: Matteo Fari <matteofari06@gmail.com>
Signed-off-by: degenaro <lou.degenaro@gmail.com>
Co-authored-by: degenaro <lou.degenaro@gmail.com>

Author: MatteoFari

docs/contributing/.pages

@@ -4,6 +4,7 @@ nav:
 - OSCAL object model: oscal_object_model.md
 - Website development: website.md
 - Developing trestle plugins: plugins.md
+- Developing beta features: beta_features.md
 - Contributors: https://github.com/oscal-compass/compliance-trestle/graphs/contributors
 - Maintainers: maintainers.md
 - Developer Certificate of Originality: DCO.md

docs/contributing/beta_features.md

@@ -0,0 +1,78 @@
+---
+title: Developing beta features
+description: Guidance for adding experimental beta features to trestle
+---
+
+# Developing beta features
+
+Use beta features for commands or behavior that should be available for early testing without becoming part of the
+stable trestle interface yet. Beta features must be explicit opt-ins and should have tests and documentation before they
+are registered.
+
+## Register a feature
+
+Register the feature in `trestle/core/beta_features.py`.
+
+```python
+BETA_FEATURES = {
+    'example-feature': BetaFeature(
+        name='example-feature',
+        description='Short user-facing description',
+        commands=['trestle example'],
+        since_version='4.0.0',
+        stability='beta',
+        documentation_url='https://oscal-compass.github.io/compliance-trestle/beta/example-feature',
+        enabled_by_default=False,
+        deprecation_version=None,
+    ),
+}
+```
+
+Feature names should be stable, lower-case, and hyphenated.
+
+## Guard beta behavior
+
+Decorate the command run method with `@beta_feature('<feature-name>')`.
+
+```python
+from trestle.core.beta_features import beta_feature
+
+
+class ExampleCmd(CommandBase):
+    """Example beta command."""
+
+    name = 'example'
+
+    @beta_feature('example-feature')
+    def _run(self, args: argparse.Namespace) -> int:
+        """Run the beta command."""
+        return CmdReturnCodes.SUCCESS.value
+```
+
+When the feature is disabled, the decorator returns a command error and tells the user how to enable the feature.
+The decorator also allows `--beta` to run the beta command one time without writing config. Commands without the
+decorator will warn that `--beta` is only effective for beta level commands, but will otherwise proceed normally.
+
+## Configuration
+
+`trestle beta enable <feature>` writes enabled features to `.trestle/config.ini` when the current directory is inside a
+trestle workspace. Outside a workspace, trestle uses the user-level beta config file.
+
+For CI and other ephemeral environments, `TRESTLE_BETA_FEATURES` can enable features without writing config:
+
+```bash
+TRESTLE_BETA_FEATURES=example-feature trestle example
+```
+
+Features enabled through `TRESTLE_BETA_FEATURES` cannot be disabled with `trestle beta disable`; remove the feature from
+the environment variable instead.
+
+## Documentation checklist
+
+Each beta feature should document:
+
+- What the feature does.
+- Which commands or options it enables.
+- The expected stability level.
+- Known limitations.
+- How to enable, use, and disable it.

docs/tutorials/cli.md

@@ -5,12 +5,13 @@ description: An introductory tutorial into trestle's CLI and OSCAL use cases
 
 # trestle CLI Overview and OSCAL usecases
 
-The trestle CLI has four primary use cases:
+The trestle CLI has five primary use cases:
 
 - Serve as tooling to generate and manipulate OSCAL files directly by an end user. The objective is to reduce the complexity of creating and editing workflows. Example commands are: `trestle import`, `trestle create`, `trestle split`, `trestle merge`.
 - Act as an automation tool that, by design, can be an integral part of a CI/CD pipeline e.g. `trestle validate`, `trestle tasks`.
 - Allow governance of markdown documents so they conform to specific style or structure requirements.
 - Canonicalize JSON documents with `trestle canonicalize`. See [Canonicalizing JSON documents](canonicalization.md).
+- Manage experimental commands with `trestle beta`.
 
 To support each of these use cases trestle creates an opinionated directory structure to manage governed documents.
 
@@ -150,6 +151,7 @@ This command will return the current version of Trestle and OSCAL it is using.
 Running `trestle version` will return:
 
 > Trestle version v3.x.x based on OSCAL version 1.1.2
+> Beta features enabled: none
 
 It can also be used to retrieve the metadata version of the OSCAL object:
 
@@ -179,6 +181,34 @@ Running `trestle version -n nist -t catalog` will return:
 
 > Version of OSCAL object of nist catalog is: 1.1.2
 
+## `trestle beta`
+
+This command manages experimental features that are available for early testing. Beta features are opt-in and may change
+before they become stable.
+
+Use `trestle beta query` to list registered beta features and their current status. Use
+`trestle beta query --verbose` for descriptions, commands, and documentation links.
+
+```bash
+trestle beta query
+trestle beta query --verbose
+```
+
+Use `trestle beta enable <feature>` and `trestle beta disable <feature>` to manage a feature.
+
+```bash
+trestle beta enable example-feature
+trestle beta disable example-feature
+```
+
+Use `--beta` on a beta command to run it one time without writing beta state to config. Commands that are not beta
+features will warn that `--beta` is only effective for beta level commands, but will otherwise proceed normally.
+
+When the current directory is inside a trestle workspace, beta feature state is stored in `.trestle/config.ini`.
+Outside a workspace, trestle uses the user-level beta config file:
+`$XDG_CONFIG_HOME/trestle/beta.ini`, or `~/.config/trestle/beta.ini` when `XDG_CONFIG_HOME` is not set. On Windows,
+the file is `%APPDATA%\trestle\beta.ini`.
+
 ## `trestle init`
 
 This command will create (initialize) a trestle workspace in the current directory with the necessary directory structure and trestle artefacts.