Metadata-Version: 2.4
Name: trugs-tools
Version: 2.3.0
Summary: TRUGS language CLI — validate TRUG graphs, compile and lint TRL, graph-node CRUD, compliance and corpus audit. Single `trug` binary. Implements TRUGS 2.0 (core_v2.0.0).
Author: TRUGS LLC
License: Apache-2.0
Project-URL: Homepage, https://github.com/TRUGS-LLC/TRUGS-TOOLS
Project-URL: Issues, https://github.com/TRUGS-LLC/TRUGS-TOOLS/issues
Project-URL: Documentation, https://github.com/TRUGS-LLC/TRUGS/blob/main/GETTING_STARTED.md
Project-URL: Changelog, https://github.com/TRUGS-LLC/TRUGS-TOOLS/blob/main/CHANGELOG.md
Keywords: trugs,cli,graph,spec,tg
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: trugs-store>=2.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: requests>=2.28
Requires-Dist: pydantic<3.0,>=2.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: jcs>=0.2.1; extra == "test"
Requires-Dist: rfc8785>=0.1.4; extra == "test"
Dynamic: license-file

# TRUGS Tools

**The TRUGS language CLI.** One binary, `trug` — validate TRUG graphs, compile
and decompile TRL, graph-node CRUD, Dark Code compliance, and corpus audit.
Implements TRUGS 2.0 (`core_v2.0.0`).

TRUG/L (TRL) is a constrained subset of English. For the syntax this compiler
supports, it compiles sentence structure to a TRUG graph and decompiles that
representation to canonical TRL. Sugar tokens and original formatting are not
preserved. Decompiling arbitrary valid TRUG graphs does not guarantee
recompilable TRL or preservation of JSON properties. Write TRL when
communicating; store and validate TRUGS (the JSON graph) when executing.

## Install

```bash
pip install trugs-tools
```

## Quickstart

```bash
trug --help                          # the verb list, one summary per verb
trug validate first.trug.json        # the 16 CORE rules -> VALID / INVALID
trug trl compile hello.trl > hello.trug.json   # TRL sentence -> TRUG graph (saved to file)
trug trl decompile hello.trug.json             # graph -> the sentence, losslessly
trug compliance src/                 # Dark Code compliance scan
```

New to TRUGS? The five-minute on-ramp:
**[GETTING_STARTED.md](https://github.com/TRUGS-LLC/TRUGS/blob/main/GETTING_STARTED.md)**

## Command surface

Eight verbs on the `trug` binary:

| verb | what it does |
|------|--------------|
| `validate` | Validate a TRUG JSON file against the 16 CORE rules |
| `trl` | Compile / decompile / validate TRL ↔ TRUG |
| `get` | Read full content of a node in a TRUG graph |
| `update` | Update properties on an existing node |
| `delete` | Remove nodes and their connected edges |
| `unlink` | Remove specific edges from a TRUG graph |
| `compliance` | Dark Code compliance check over a source tree |
| `audit` | Corpus-side audit bridges (markdown / vocab) |

Every verb documents examples and exit codes: `trug <verb> --help`.
For `trug trl`, content syntax, grammar, vocabulary and validation failures exit 1;
usage errors (bad arguments, missing or unreadable files, or expected JSON) exit 2.

## Role in the TRUGS-LLC portfolio

- **[TRUGS](https://github.com/TRUGS-LLC/TRUGS)** — the specification (CORE + TRL + reference papers) and the [getting-started guide](https://github.com/TRUGS-LLC/TRUGS/blob/main/GETTING_STARTED.md).
- **TRUGS-TOOLS** (this repo) — the language CLI `trug` (this package).
- **[TRUGS-STORE](https://github.com/TRUGS-LLC/TRUGS-STORE)** — the swappable graph-storage backend used by the language CLI.

## Documentation

- [CHANGELOG.md](./CHANGELOG.md) — version history, including the 2.0 boundary statement and the v1 migration table
- [GETTING_STARTED.md](https://github.com/TRUGS-LLC/TRUGS/blob/main/GETTING_STARTED.md) — the on-ramp
- [SECURITY.md](./SECURITY.md) · [CONTRIBUTING.md](./CONTRIBUTING.md)

## Development

```bash
make dev      # editable install of the trug CLI with test dependencies (.[test])
make check    # pytest tests/, then trug validate folder.trug.json
```

The last `make check` step is Layer-4 self-description: the engine validates
the repo's own `folder.trug.json` against the TRUGS CORE rules it implements.

## Scope

This software does not include self-modifying TRUGS: graphs that change their
own structure while they run.

## License

Apache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
