Skip to content

Commit 76ba935

Browse files
david-waltermiredavid-waltermire
authored
docs: expand website documentation with guides and architecture (#228)
* docs: expand website with installation, building, and guide pages - Add installation.md.vm with download, container, and CI/CD instructions - Add building.md.vm with JDK 17 requirement and CI profile instructions - Add claude-integration.md.vm documenting Claude Code plugin skills - Add 5 guide pages covering validation, format conversion, profile resolution, Metapath queries, and CLI command reference - Update site.xml with Documentation and Guides navigation menus - Enhance index.md.vm with quick start and feature overview * docs: left-justify prerequisite tables * fix: address PR review feedback - Fix shell-completion to generate-completion in README - Clarify OS-specific JAVA_HOME instructions (separate macOS/Linux) - Remove broken claude-plugins link - Remove unsupported Mapping model sections - Use canonical URL framework.metaschema.dev * fix: correct shell-completion command name in documentation The shell-completion command was incorrectly documented as generate-completion in several places. Updated README.md and website documentation to use the correct command name. * fix: restore Mapping Collection support and add claude-plugins link - Restore Mapping Collection examples in validation and conversion guides (Mapping is supported in oscal-complete schema) - Add Mapping Collection to document types table in CLI reference - Add claude-plugins link in claude-integration.md.vm * fix: address CodeRabbit nitpick comments - Add mkdir -p before shell completion install commands - Fix Quick Start with explicit VERSION variable - Escape Velocity tokens in CI snippets using #[[...]]# - Use branch-agnostic HEAD in CONTRIBUTING.md link
1 parent 3d90de3 commit 76ba935

File tree

13 files changed

+2007
-9
lines changed

13 files changed

+2007
-9
lines changed

‎.vscode/settings.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"java.configuration.updateBuildConfiguration": "interactive"
3+
}

‎README.md‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,9 +102,40 @@ To disable colored output, use the `--no-color` flag:
102102
oscal-cli --no-color <command>
103103
```
104104

105+
### Shell Completion
106+
107+
The CLI supports tab completion for Bash and Zsh shells, providing intelligent suggestions for commands, subcommands, and options.
108+
109+
**Bash:**
110+
111+
```bash
112+
# Generate and source completion (temporary, current session only)
113+
source <(oscal-cli shell-completion bash)
114+
115+
# Or save to a file and source it in your ~/.bashrc for persistence
116+
oscal-cli shell-completion bash > ~/.oscal-completion.bash
117+
echo 'source ~/.oscal-completion.bash' >> ~/.bashrc
118+
```
119+
120+
**Zsh:**
121+
122+
```zsh
123+
# Ensure your completions directory exists
124+
mkdir -p ~/.zsh/completions
125+
126+
# Generate completion script
127+
oscal-cli shell-completion zsh > ~/.zsh/completions/_oscal-cli
128+
129+
# Add to your ~/.zshrc if not already configured
130+
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
131+
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
132+
```
133+
134+
After setting up completion, restart your shell or source the configuration file.
135+
105136
## Building
106137

107-
This project can be built with [Apache Maven](https://maven.apache.org/) version 3.8.4 or greater.
138+
This project can be built with [Apache Maven](https://maven.apache.org/) version 3.9.0 or greater.
108139

109140
The following instructions can be used to clone and build this project.
110141

‎src/site/markdown/building.md.vm‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Building from Source
2+
3+
This guide explains how to build the OSCAL CLI from source code.
4+
5+
## Prerequisites
6+
7+
| Requirement | Minimum Version | Notes |
8+
|:------------|:----------------|:------|
9+
| Java JDK | 17 | Required for building (output JARs are JDK 11 compatible) |
10+
| Maven | 3.9.0 | Required for building |
11+
| Git | 2.0 | Required for cloning |
12+
13+
Ensure `JAVA_HOME` is set correctly:
14+
15+
```bash
16+
# macOS
17+
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
18+
19+
# Linux (adjust path to your installation)
20+
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
21+
22+
# Windows
23+
set JAVA_HOME=C:\Program Files\Java\jdk-17
24+
```
25+
26+
## Clone the Repository
27+
28+
Clone the repository with submodules:
29+
30+
```bash
31+
git clone --recurse-submodules https://github.com/metaschema-framework/oscal-cli.git
32+
cd oscal-cli
33+
```
34+
35+
If you already cloned without submodules, initialize them:
36+
37+
```bash
38+
git submodule update --init --recursive
39+
```
40+
41+
## Build Commands
42+
43+
### Basic Build
44+
45+
Build and install to your local Maven repository:
46+
47+
```bash
48+
mvn install
49+
```
50+
51+
This produces the CLI distribution in `target/oscal-cli-enhanced-*-oscal-cli.zip`.
52+
53+
### Run Tests Only
54+
55+
```bash
56+
mvn test
57+
```
58+
59+
### Run a Single Test
60+
61+
```bash
62+
# Run a single test class
63+
mvn test -Dtest=CLITest
64+
65+
# Run a single test method
66+
mvn test -Dtest=CLITest#testValidate
67+
```
68+
69+
### Skip Tests
70+
71+
```bash
72+
mvn install -DskipTests
73+
```
74+
75+
### CI/CD Build
76+
77+
Replicate the full CI/CD build (recommended before pushing):
78+
79+
```bash
80+
mvn install -PCI -Prelease
81+
```
82+
83+
This enables additional checks including:
84+
85+
- License header verification
86+
- Checkstyle code style checks
87+
- SpotBugs static analysis
88+
- Full test suite
89+
90+
## Code Quality Commands
91+
92+
### Check License Headers
93+
94+
```bash
95+
mvn license:check
96+
```
97+
98+
### Auto-format Source Code
99+
100+
```bash
101+
mvn formatter:format
102+
```
103+
104+
### Check for Checkstyle Issues
105+
106+
```bash
107+
mvn checkstyle:check
108+
```
109+
110+
## Running the Built CLI
111+
112+
After building, you can run the CLI directly:
113+
114+
```bash
115+
# Extract the distribution
116+
unzip target/oscal-cli-enhanced-*-oscal-cli.zip -d target/cli
117+
118+
# Run the CLI
119+
target/cli/bin/oscal-cli --help
120+
```
121+
122+
## Building Container Images
123+
124+
To build a local container image:
125+
126+
```bash
127+
# Build with Docker
128+
docker build -t oscal-cli:local .
129+
130+
# Test the image
131+
docker run --rm oscal-cli:local --help
132+
```
133+
134+
## Building the Site
135+
136+
To build the project documentation site:
137+
138+
```bash
139+
mvn site
140+
```
141+
142+
The generated site appears in `target/site/`.
143+
144+
## Common Build Issues
145+
146+
### Submodule Not Initialized
147+
148+
**Symptom:** Build fails with missing OSCAL or Metaschema files.
149+
150+
**Solution:** Initialize submodules:
151+
152+
```bash
153+
git submodule update --init --recursive
154+
```
155+
156+
### Java Version Mismatch
157+
158+
**Symptom:** Compilation errors or "unsupported class file version" errors.
159+
160+
**Solution:** Ensure you're using Java 17 or later for building:
161+
162+
```bash
163+
java -version
164+
mvn -version
165+
```
166+
167+
### Maven Version Too Old
168+
169+
**Symptom:** Build fails with plugin compatibility errors or enforcer rule failures.
170+
171+
**Solution:** Upgrade Maven to 3.9.0 or later:
172+
173+
```bash
174+
mvn -version
175+
```
176+
177+
### Out of Memory
178+
179+
**Symptom:** Build fails with `OutOfMemoryError`.
180+
181+
**Solution:** Increase Maven's heap size:
182+
183+
```bash
184+
export MAVEN_OPTS="-Xmx2g"
185+
mvn install
186+
```
187+
188+
## Contributing
189+
190+
For contribution guidelines, including code style requirements and the pull request process, see [CONTRIBUTING.md](${project.scm.url}/blob/develop/CONTRIBUTING.md).
191+
192+
## Next Steps
193+
194+
- [Installation](installation.html) - Install the pre-built CLI
195+
- [CLI Reference](guides/cli-reference.html) - Complete command reference

‎src/site/markdown/claude-integration.md.vm‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Using with Claude Code
2+
3+
[Claude Code](https://claude.ai/code) is an AI-powered coding assistant that can help you work with OSCAL CLI more effectively.
4+
5+
## Overview
6+
7+
Claude Code plugins provide specialized skills for:
8+
9+
- **OSCAL document validation** - Validating catalogs, profiles, SSPs, and other OSCAL artifacts
10+
- **Format conversion** - Converting between XML, JSON, and YAML formats
11+
- **Profile resolution** - Resolving profiles to produce baseline catalogs
12+
- **Metapath queries** - Writing expressions to query OSCAL content
13+
- **CLI assistance** - Running commands and interpreting output
14+
15+
## Prerequisites
16+
17+
1. [Install Claude Code](https://docs.anthropic.com/en/docs/claude-code)
18+
19+
## Available Plugins
20+
21+
### OSCAL Plugin
22+
23+
Skills for working with OSCAL documents:
24+
25+
| Skill | Description |
26+
|:------|:------------|
27+
| `oscal:oscal-basics` | OSCAL document types and structure |
28+
29+
### OSCAL Tools Plugin
30+
31+
Skills for using the CLI:
32+
33+
| Skill | Description |
34+
|:------|:------------|
35+
| `oscal-tools:using-oscal-cli` | Running oscal-cli commands |
36+
37+
### Metaschema Plugin
38+
39+
Skills for understanding OSCAL's underlying structure:
40+
41+
| Skill | Description |
42+
|:------|:------------|
43+
| `metaschema:metaschema-basics` | Introduction to Metaschema concepts |
44+
| `metaschema:metapath-expressions` | Writing Metapath queries |
45+
46+
## Example Workflows
47+
48+
### Validate an OSCAL Document
49+
50+
Ask Claude:
51+
> "Validate my SSP at `ssp.json` and explain any errors"
52+
53+
Claude will run the validation and help you understand and fix issues.
54+
55+
### Convert Between Formats
56+
57+
Ask Claude:
58+
> "Convert my catalog from XML to JSON"
59+
60+
Claude will guide you through the conversion process.
61+
62+
### Resolve a Profile
63+
64+
Ask Claude:
65+
> "Help me resolve my NIST 800-53 profile to a baseline catalog"
66+
67+
Claude will explain profile resolution and run the appropriate command.
68+
69+
### Query OSCAL Content
70+
71+
Ask Claude:
72+
> "Write a Metapath expression to find all controls with a specific label"
73+
74+
Claude will construct the expression and show how to use it with the CLI.
75+
76+
### Debug Validation Errors
77+
78+
Ask Claude:
79+
> "I'm getting validation errors on my component definition. Can you help?"
80+
81+
Claude will analyze the errors and suggest fixes.
82+
83+
## Tips for Effective Use
84+
85+
1. **Be specific** - Mention file paths and exact error messages
86+
2. **Provide context** - Share the OSCAL document type you're working with
87+
3. **Ask for explanations** - Claude can explain OSCAL concepts and requirements
88+
4. **Request examples** - Ask for sample OSCAL snippets or CLI commands
89+
90+
## Common Commands
91+
92+
Here are CLI commands that Claude can help you with:
93+
94+
```bash
95+
# Validate OSCAL content
96+
oscal-cli validate document.json
97+
98+
# Convert formats
99+
oscal-cli convert --to=json catalog.xml catalog.json
100+
101+
# Resolve a profile
102+
oscal-cli resolve-profile profile.xml resolved-catalog.xml
103+
104+
# Evaluate Metapath expressions
105+
oscal-cli metapath eval -e "//control" catalog.json
106+
```
107+
108+
## Learn More
109+
110+
For more information about Claude Code, OSCAL, and the CLI, see these resources:
111+
112+
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
113+
- [Metaschema Claude Plugins](https://github.com/metaschema-framework/claude-plugins/tree/main) - Source for the skills mentioned above
114+
- [OSCAL Documentation](https://pages.nist.gov/OSCAL/)
115+
- [CLI Reference](guides/cli-reference.html)

0 commit comments

Comments
 (0)