domainforge 0.13.0

package/docs/reference/cli-commands.md

@@ -0,0 +1,588 @@
+# CLI Commands
+
+This reference captures the available CLI commands provided by the `sea` binary (feature `cli` in `domainforge-core`). Commands and flags mirror `domainforge --help` output and include examples with expected behavior.
+
+## Conventions
+
+- Replace `model.sea` with your own file paths.
+- Commands exit non-zero on validation or parsing errors; examples note expected exit codes when relevant.
+- Use `--format json` when integrating with tooling.
+
+## Global options
+
+```
+domainforge --help
+domainforge --version
+```
+
+- `--version` prints `domainforge-core <version>` (matches the built crate version).
+- `--help` lists subcommands.
+
+## parse
+
+Parse a SEA file into an internal graph and print a summary.
+
+```
+domainforge parse path/to/model.sea
+```
+
+Options:
+
+- `--format <human|json>`: default `human` shows counts; `json` output depends on `--ast`.
+  - Without `--ast`: outputs semantic Graph JSON (entities, resources, flows)
+  - With `--ast`: outputs Abstract Syntax Tree JSON (declarations, source locations)
+- `--ast`: output AST structure instead of semantic graph.
+- `--out <path>`: write output to a file instead of stdout.
+
+Example:
+
+```
+domainforge parse domainforge-core/examples/basic.sea --format human
+
+# Output AST JSON
+domainforge parse domainforge-core/examples/basic.sea --ast --format json
+
+# Output Graph JSON
+domainforge parse domainforge-core/examples/basic.sea --format json
+```
+
+Expected output includes entity/resource/flow counts and the active namespace. AST mode outputs tagged AST nodes (e.g., `{"type": "Entity", ...}`).
+
+## validate
+
+Validate syntax and semantics of a SEA file.
+
+```
+domainforge validate path/to/model.sea
+```
+
+Options:
+
+- `--format <human|json>`: JSON returns a structured report with errors and warnings.
+- `--allow-unknown`: treat missing references as `Unknown` instead of failing (matches three-valued logic).
+- `--registry <.sea-registry.toml>`: provide namespace registry for cross-file resolution.
+
+Exit codes:
+
+- `0` when valid
+- `1` when parse or semantic errors occur
+
+## project
+
+Export a model to other formats.
+
+```
+domainforge project --format <calm|rdf|sbvr|dsl|protobuf> input.sea output.json
+```
+
+Formats:
+
+- `calm`: FINOS CALM JSON
+- `rdf`: RDF/Turtle
+- `sbvr`: SBVR fact types
+- `dsl`: reformat the DSL (pretty-print)
+- `protobuf`: Protocol Buffer `.proto` files
+
+### Protobuf-specific options
+
+```bash
+domainforge project --format protobuf [OPTIONS] input.sea output.proto
+```
+
+| Option                   | Description                                               |
+| ------------------------ | --------------------------------------------------------- |
+| `--package <name>`       | Override the proto package name                           |
+| `--include-services`     | Generate gRPC service definitions from Flows              |
+| `--multi-file`           | Output separate `.proto` files per namespace              |
+| `--output-dir <path>`    | Directory for multi-file output                           |
+| `--compatibility <mode>` | Compatibility mode: `additive`, `backward`, or `breaking` |
+| `--against <path>`       | Previous schema for compatibility checking                |
+| `--buf-lint`             | Run buf lint on generated output (requires buf CLI)       |
+| `--buf-breaking`         | Run buf breaking change detection (requires buf CLI)      |
+| `--option <key>=<value>` | Set proto options (e.g., `java_package=com.example`)      |
+
+Example:
+
+```bash
+# Basic export
+domainforge project --format protobuf model.sea output.proto
+
+# With gRPC services and custom package
+domainforge project --format protobuf --include-services --package "com.example.api" model.sea api.proto
+
+# Multi-file with buf validation
+domainforge project --format protobuf --multi-file --buf-lint --output-dir ./proto model.sea
+```
+
+Use cases:
+
+- `domainforge project --format calm model.sea calm.json` to feed downstream systems.
+- `domainforge project --format rdf model.sea graph.ttl` to load into triple stores.
+- `domainforge project --format protobuf model.sea schema.proto` for gRPC/binary serialization.
+
+## import
+
+Import CALM JSON into SEA DSL.
+
+```
+domainforge import --format calm calm.json
+```
+
+- Outputs SEA DSL to stdout by default; redirect to a file to persist.
+- Use `--out` to write directly: `domainforge import --format calm calm.json --out restored.sea`.
+
+### Import from Knowledge Graph (RDF)
+
+Import RDF/Turtle or RDF/XML into SEA Graph.
+
+```
+domainforge import --format kg graph.ttl
+domainforge import --format kg graph.rdf
+```
+
+- Auto-detects Turtle vs RDF/XML based on content.
+- RDF/XML import requires building with `--features cli,shacl`.
+
+### Import from SBVR
+
+Import SBVR XMI vocabulary into SEA.
+
+```
+domainforge import --format sbvr vocabulary.xmi
+```
+
+- Converts noun concepts to entities.
+- Converts verb concepts to relations.
+- Converts business rules to policies.
+- See [Import from SBVR](../how-tos/import-from-sbvr.md) for details.
+
+## validate-kg
+
+Validate RDF/Turtle or RDF/XML files against SHACL shapes.
+
+```
+domainforge validate-kg graph.ttl
+domainforge validate-kg graph.rdf
+```
+
+- Requires building with `--features cli,shacl`.
+- Validates structure conforms to SEA SHACL shapes.
+- Reports SHACL violations with severity and message.
+
+## normalize
+
+Normalize and compare policy expressions.
+
+```
+domainforge normalize [OPTIONS] <EXPRESSION>
+```
+
+Options:
+
+- `--check-equiv <EXPR>`: Compare the input expression with another for semantic equivalence.
+- `--json`: Output result as JSON object (always includes normalized string and hash; includes equivalence result only if `--check-equiv` is used).
+
+Examples:
+
+```bash
+# Normalize an expression
+domainforge normalize "b AND a"
+# Output: (a AND b)
+
+# Check equivalence
+domainforge normalize "a AND b" --check-equiv "b AND a"
+# Output:
+# (a AND b)
+# Equivalent (hash: 0x...)
+
+# JSON output
+domainforge normalize "true AND x" --json
+# Output: { "normalized": "x", "hash": "0x..." }
+
+# JSON output with equivalence
+domainforge normalize "true AND x" --check-equiv "x" --json
+# Output: { "normalized": "x", "hash": "0x...", "equivalent": true }
+```
+
+## graph
+
+Display a normalized view of the graph for debugging.
+
+```
+sea graph model.sea
+```
+
+- Prints entities, resources, flows, instances, roles, and relations with IDs.
+- Useful when mapping DSL names to UUIDs.
+
+## eval (policy evaluation)
+
+Evaluate policies against a model.
+
+```
+sea eval --policy policy.json model.sea
+```
+
+Options:
+
+- `--format <human|json>`: JSON exposes violation details.
+- `--allow-unknown`: enable three-valued logic for incomplete data.
+
+Policy JSON schema matches `domainforge-core::policy::Policy`. See [`primitives-api`](./primitives-api.md) for the policy type.
+
+## fmt
+
+Format SEA-DSL source files with consistent styling.
+
+```
+sea fmt model.sea                           # Output to stdout
+sea fmt model.sea --out formatted.sea       # Write to file
+sea fmt --check model.sea                   # CI mode: exit 1 if changes needed
+```
+
+### Options
+
+| Option               | Default | Description                                |
+| -------------------- | ------- | ------------------------------------------ |
+| `--out <path>`       | stdout  | Write formatted output to file             |
+| `--check`            | false   | Check if file is formatted (exit 1 if not) |
+| `--indent-width <n>` | 4       | Number of spaces per indent level          |
+| `--use-tabs`         | false   | Use tabs instead of spaces                 |
+| `--sort-imports`     | true    | Sort imports alphabetically                |
+
+### Examples
+
+```bash
+# Format and display
+sea fmt model.sea
+
+# Format in-place
+sea fmt model.sea --out model.sea
+
+# Check in CI (fails if formatting needed)
+sea fmt --check model.sea
+
+# Use tabs with 2-space equivalent
+sea fmt model.sea --use-tabs
+
+# Custom indent width
+sea fmt model.sea --indent-width 2
+```
+
+### Features
+
+- **14 declaration types supported**: Entity, Resource, Flow, Pattern, Role, Relation, Instance, Policy, Metric, Dimension, Unit, ConceptChange, Mapping, Projection
+- **Comment preservation**: File header comments are preserved
+- **Idempotent**: Formatting twice produces the same result as formatting once
+- **Import sorting**: Organizes imports alphabetically by module path
+
+## units
+
+List known dimensions and units registered in a model.
+
+```
+sea units model.sea
+```
+
+- Shows base units and conversion factors.
+- Errors if units are undefined or circular.
+
+## explain
+
+Show detailed error context for validation failures.
+
+```
+sea explain --format human model.sea
+```
+
+- Equivalent to `validate` but includes suggestions from the validator (e.g., did-you-mean for unknown IDs).
+
+## Environment variables
+
+- `SEA_LOG`: set to `debug` to enable verbose logging (`SEA_LOG=debug domainforge validate model.sea`).
+- `SEA_REGISTRY`: default path for `.sea-registry.toml` if not provided via `--registry`.
+
+## Exit codes summary
+
+- `0`: success (parse/validate/eval/export succeeded)
+- `1`: parser or validation errors
+- `2`: IO or configuration errors (file not found, permission issues)
+
+## Example workflow
+
+```bash
+domainforge validate payment.sea \
+  && domainforge project --format calm payment.sea calm.json \
+  && domainforge import --format calm calm.json --out roundtrip.sea
+```
+
+- First command fails fast on syntax/semantic issues.
+- Second exports CALM JSON for integration.
+- Third re-imports to verify round-trip fidelity.
+
+## Troubleshooting
+
+- If `sea` is not found, ensure `$HOME/.cargo/bin` is on `PATH` or reinstall with `cargo install --path domainforge-core --features cli --force`.
+- For Windows, run inside Developer PowerShell so the MSVC toolchain is available.
+- Use `--format json` when parsing complex files to pinpoint the failing declaration.
+
+## See also
+
+- [`../how-tos/install-cli.md`](../how-tos/install-cli.md) for installation and verification.
+- [`../how-tos/parse-sea-files.md`](../how-tos/parse-sea-files.md) for parsing guidance.
+- [`../how-tos/export-to-calm.md`](../how-tos/export-to-calm.md) and [`../how-tos/import-from-calm.md`](../how-tos/import-from-calm.md) for data exchange.
+- [`error-codes.md`](./error-codes.md) for interpreting validation failures.
+
+## Command reference by scenario
+
+### Batch-validate a directory
+
+```bash
+find models -name "*.sea" -print0 | xargs -0 -n1 -I{} domainforge validate {}
+```
+
+- Fails fast on the first invalid file when combined with `set -e` in CI scripts.
+
+### Use a namespace registry
+
+```toml
+# .sea-registry.toml
+[registry]
+paths = ["./models/shared", "./models/payments"]
+```
+
+```bash
+domainforge validate --registry .sea-registry.toml models/payments/payment.sea
+```
+
+### Emit JSON for tooling
+
+```bash
+domainforge parse model.sea --format json | jq '.entities[] | {name, id}'
+```
+
+- Use when integrating with code generators or graph visualizers.
+
+### Check CLI help for a subcommand
+
+```
+domainforge project --help
+```
+
+- Mirrors the subcommand definitions in `domainforge-core/src/bin/sea.rs`.
+
+## Command locations in the repository
+
+- Entry point: `domainforge-core/src/bin/sea.rs`
+- Subcommand implementations: `domainforge-core/src/cli/commands/*.rs`
+- Argument parsing: `domainforge-core/src/cli/mod.rs` (clap definitions)
+
+Reading these files ensures documentation stays aligned with the shipped binary.
+
+## CI integration
+
+- The repo uses `just all-tests` to run Rust, Python, and TypeScript suites; incorporate `domainforge validate` on sample DSL fixtures to guard docs.
+- When building release artifacts, the GitHub workflows call the same CLI with `--format json` to capture machine-readable outputs.
+
+## Legacy flags
+
+- Older snapshots referenced `--pretty`; this is superseded by `sea fmt`.
+- The `--dump-ast` debug flag is only available when building with `debug` assertions; it prints the parser AST and is unsupported in release binaries.
+
+## Security considerations
+
+- CLI does not execute embedded code; however, avoid running against untrusted files in directories with malicious symlinks (use `--out` to control output paths).
+- When exporting CALM or RDF, check file permissions to avoid leaking sensitive model details.
+
+## Pack Commands
+
+The `domainforge pack` subcommand provides tools for building, validating, inspecting, diffing, signing, and verifying semantic packs.
+
+### domainforge pack build
+
+Build a semantic pack from .sea source files.
+
+```bash
+domainforge pack build \
+  --source <glob> \
+  --org <id> \
+  --domain <id> \
+  --version <semver> \
+  --meaning-version <semver> \
+  --approval candidate|approved \
+  --review <path> \
+  --previous-pack <path> \
+  --allow-first-approved-version \
+  --out <path> \
+  --format human|json|jsonl
+```
+
+Options:
+
+| Option                          | Description                                                        |
+|---------------------------------|--------------------------------------------------------------------|
+| `--source` (required, repeatable) | Glob patterns or file paths for .sea source files.               |
+| `--org` (required)              | Organization identifier.                                           |
+| `--domain` (required)           | Domain identifier.                                                 |
+| `--version` (required)          | Pack version (semver).                                             |
+| `--meaning-version` (required)  | Meaning version (semver). Must increase when fingerprint changes.  |
+| `--approval`                    | `candidate` (default) or `approved`.                               |
+| `--review`                      | Path to JSONL review manifest (required for `approved`).           |
+| `--previous-pack`               | Path to previous pack for version comparison.                      |
+| `--allow-first-approved-version`| Allow first approved pack without a previous version.              |
+| `--out`                         | Output file path. Prints to stdout if omitted.                     |
+| `--format`                      | Output format: `human` (default), `json`, or `jsonl`.              |
+
+Exit codes: `0` success, `1` semantic/build errors, `2` parse error.
+
+Examples:
+
+```bash
+# Build a candidate pack
+domainforge pack build --source "models/**/*.sea" --org acme --domain logistics \
+  --version 1.0.0 --meaning-version 1.0.0 --out packs/candidate.json
+
+# Build an approved pack with review
+domainforge pack build --source "models/**/*.sea" --org acme --domain logistics \
+  --version 1.1.0 --meaning-version 1.1.0 --approval approved \
+  --review reviews/logistics.jsonl --previous-pack packs/candidate.json \
+  --out packs/approved.json
+```
+
+### domainforge pack validate
+
+Validate .sea source files against a semantic pack.
+
+```bash
+domainforge pack validate \
+  --pack <path> \
+  --mode off|warn|strict \
+  --deprecated-policy allow|warn|error_in_strict|error_always \
+  --require-signature \
+  --expected-hash <hash> \
+  --format human|json|jsonl \
+  <input.sea>...
+```
+
+Options:
+
+| Option                   | Description                                                        |
+|--------------------------|--------------------------------------------------------------------|
+| `--pack` (required)      | Path to the semantic pack JSON file.                               |
+| `--mode`                 | `warn` (default), `off`, or `strict`.                              |
+| `--deprecated-policy`    | `warn` (default), `allow`, `error_in_strict`, or `error_always`.   |
+| `--require-signature`    | Fail if the pack is unsigned.                                      |
+| `--expected-hash`        | Pin the expected pack content hash for tamper protection.          |
+| `--format`               | Output format: `human` (default), `json`, or `jsonl`.              |
+| `<input.sea>...`         | One or more .sea files to validate.                                |
+
+Exit codes: `0` passed, `1` validation errors, `2` parse error, `3` unsigned pack, `4` signature failure.
+
+Examples:
+
+```bash
+# Warn-mode validation
+domainforge pack validate --pack packs/approved.json models/*.sea
+
+# Strict CI validation
+domainforge pack validate --pack packs/signed.json --mode strict \
+  --require-signature --expected-hash sha256:abc123... models/**/*.sea
+```
+
+### domainforge pack inspect
+
+Display metadata and contents of a semantic pack.
+
+```bash
+domainforge pack inspect [--format human|json|jsonl] <pack-path>
+```
+
+Options:
+
+| Option      | Description                                            |
+|-------------|--------------------------------------------------------|
+| `--format`  | `human` (default), `json`, or `jsonl`.                 |
+
+Example:
+
+```bash
+domainforge pack inspect packs/acme-logistics-1.1.0.json
+domainforge pack inspect --format json packs/acme-logistics-1.1.0.json
+```
+
+### domainforge pack diff
+
+Compare two semantic packs and classify changes.
+
+```bash
+domainforge pack diff --old <path> --new <path> [--format human|json|jsonl]
+```
+
+Options:
+
+| Option      | Description                                            |
+|-------------|--------------------------------------------------------|
+| `--old`     | Path to the old (base) pack.                           |
+| `--new`     | Path to the new pack.                                  |
+| `--format`  | `human` (default), `json`, or `jsonl`.                 |
+
+Exit codes: `0` no breaking changes, `1` breaking changes detected.
+
+Diff classifications: `ADD` (additive), `DEF` (definitional change), `DEP` (deprecating), `BRK` (breaking), `GOV` (governance critical), `SIG` (signature only).
+
+Example:
+
+```bash
+domainforge pack diff --old packs/v1.0.0.json --new packs/v1.1.0.json
+```
+
+### domainforge pack sign
+
+Sign a semantic pack with an Ed25519 private key.
+
+```bash
+domainforge pack sign <pack-path> --key <private.pem> [--out <path>]
+```
+
+Options:
+
+| Option      | Description                                            |
+|-------------|--------------------------------------------------------|
+| `--key`     | Path to the Ed25519 private key (PEM format).          |
+| `--out`     | Output path for the signed pack. Prints to stdout if omitted. |
+
+Exit codes: `0` success, `4` signing failure.
+
+Example:
+
+```bash
+domainforge pack sign packs/approved.json --key keys/private.pem \
+  --out packs/signed.json
+```
+
+### domainforge pack verify
+
+Verify the Ed25519 signature of a semantic pack.
+
+```bash
+domainforge pack verify <pack-path> --key <public.pem>
+```
+
+Options:
+
+| Option      | Description                                            |
+|-------------|--------------------------------------------------------|
+| `--key`     | Path to the Ed25519 public key (PEM format).           |
+
+Exit codes: `0` valid signature, `4` invalid or missing signature.
+
+Example:
+
+```bash
+domainforge pack verify packs/signed.json --key keys/public.pem
+```
+
+## Version compatibility
+
+- New flags are added under minor version bumps; scripts should check `domainforge --version` to ensure expected options exist.
+- The CLI respects semantic versioning with breaking changes gated to major bumps; see [`../explanations/versioning-strategy.md`](../explanations/versioning-strategy.md).