forktex-fsd 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. forktex_fsd-1.0.0/AGENTS.md +30 -0
  2. forktex_fsd-1.0.0/CHANGELOG.md +66 -0
  3. forktex_fsd-1.0.0/LICENSE +45 -0
  4. forktex_fsd-1.0.0/NOTICE +18 -0
  5. forktex_fsd-1.0.0/PKG-INFO +216 -0
  6. forktex_fsd-1.0.0/README.md +186 -0
  7. forktex_fsd-1.0.0/SECURITY.md +37 -0
  8. forktex_fsd-1.0.0/docs/assets/fsd-banner.png +0 -0
  9. forktex_fsd-1.0.0/docs/development.md +128 -0
  10. forktex_fsd-1.0.0/docs/guide.md +355 -0
  11. forktex_fsd-1.0.0/docs/reference.md +234 -0
  12. forktex_fsd-1.0.0/fsd.toml +62 -0
  13. forktex_fsd-1.0.0/poetry.lock +3765 -0
  14. forktex_fsd-1.0.0/poetry.toml +25 -0
  15. forktex_fsd-1.0.0/pyproject.toml +144 -0
  16. forktex_fsd-1.0.0/scripts/clean.py +61 -0
  17. forktex_fsd-1.0.0/scripts/license_headers.py +103 -0
  18. forktex_fsd-1.0.0/scripts/release_check.py +123 -0
  19. forktex_fsd-1.0.0/scripts/smoke.py +68 -0
  20. forktex_fsd-1.0.0/src/forktex_fsd/__init__.py +84 -0
  21. forktex_fsd-1.0.0/src/forktex_fsd/__main__.py +28 -0
  22. forktex_fsd-1.0.0/src/forktex_fsd/_cli.py +249 -0
  23. forktex_fsd-1.0.0/src/forktex_fsd/_render.py +342 -0
  24. forktex_fsd-1.0.0/src/forktex_fsd/binding.py +292 -0
  25. forktex_fsd-1.0.0/src/forktex_fsd/check.py +162 -0
  26. forktex_fsd-1.0.0/src/forktex_fsd/errors.py +67 -0
  27. forktex_fsd-1.0.0/src/forktex_fsd/paths.py +40 -0
  28. forktex_fsd-1.0.0/src/forktex_fsd/project.py +96 -0
  29. forktex_fsd-1.0.0/src/forktex_fsd/py.typed +0 -0
  30. forktex_fsd-1.0.0/src/forktex_fsd/report.py +212 -0
  31. forktex_fsd-1.0.0/src/forktex_fsd/results.py +130 -0
  32. forktex_fsd-1.0.0/src/forktex_fsd/run.py +298 -0
  33. forktex_fsd-1.0.0/src/forktex_fsd/standard.py +165 -0
  34. forktex_fsd-1.0.0/src/forktex_fsd/standard.toml +186 -0
  35. forktex_fsd-1.0.0/tests/_containers.py +59 -0
  36. forktex_fsd-1.0.0/tests/conftest.py +118 -0
  37. forktex_fsd-1.0.0/tests/contract/test_binding.py +211 -0
  38. forktex_fsd-1.0.0/tests/contract/test_check.py +130 -0
  39. forktex_fsd-1.0.0/tests/contract/test_cli.py +332 -0
  40. forktex_fsd-1.0.0/tests/contract/test_render.py +103 -0
  41. forktex_fsd-1.0.0/tests/contract/test_report.py +240 -0
  42. forktex_fsd-1.0.0/tests/contract/test_results.py +147 -0
  43. forktex_fsd-1.0.0/tests/contract/test_run.py +270 -0
  44. forktex_fsd-1.0.0/tests/contract/test_standard.py +105 -0
  45. forktex_fsd-1.0.0/tests/contract/test_surface.py +87 -0
  46. forktex_fsd-1.0.0/tests/platforms/test_linux.py +85 -0
  47. forktex_fsd-1.0.0/tests/usage/test_a_library.py +145 -0
  48. forktex_fsd-1.0.0/tests/usage/test_a_service.py +68 -0
  49. forktex_fsd-1.0.0/tests/usage/test_custom_atoms.py +88 -0
  50. forktex_fsd-1.0.0/tests/usage/test_the_docs.py +109 -0
@@ -0,0 +1,30 @@
1
+ # AGENTS.md
2
+
3
+ `forktex-fsd` is a general-purpose software compliance standard and the small
4
+ library + CLI that checks it. It must stay technology-agnostic and free of any
5
+ ForkTex-specific assumption: it judges compliance per track, never a product's
6
+ stage or maturity.
7
+
8
+ - **The standard is data**: `src/forktex_fsd/standard.toml`. Changing an atom, a
9
+ contract or a strength is a change to the standard — bump its `version` and
10
+ record it in `CHANGELOG.md`. Contracts never name a tool.
11
+ - **Built on `forktex`**: errors subclass `forktex.error.AppError`, every model is
12
+ a `forktex.types` value object (pydantic — never a dataclass), the report is a
13
+ wire object, the library logs and never prints.
14
+ - **Layout and direction**: `standard` → `binding` | `results` → `check` | `run`
15
+ → `report` → `project` → `_render` → `_cli`, one way only; `fsd lint` enforces
16
+ it. `Project` is the one entry point; `_cli` imports only the package's public
17
+ names and `_render`. `forktex_fsd.__all__` is the public surface, pinned by
18
+ `tests/contract/test_surface.py`. Architecture and decisions: `docs/development.md`.
19
+ - `check` must never execute a command. Only checks tracks run as a whole, and
20
+ they may hold only read-only and local atoms; a report runs nothing else.
21
+ - There is no Makefile: `fsd.toml` is the only place a command lives.
22
+ `poetry run fsd assurance`, `fsd security` and `fsd documentation` are the gate and `poetry run fsd build` makes the
23
+ artifact; `poetry run fsd tidy` fixes formatting and headers; bare
24
+ `poetry run fsd` shows every atom and its binding. Line and branch
25
+ coverage are held at 100: every branch here is a rule of the standard, so every
26
+ branch has a test. Tests run real subprocesses, not mocks: a consumer's scenario
27
+ goes in `tests/usage/`, a rule in `tests/contract/`. `fsd assurance` includes the
28
+ custom atom `platforms` (`tests/platforms/`, testcontainers), so it needs Docker;
29
+ `fsd test` alone does not.
30
+ - Publishing is manual: a person runs `poetry run fsd publish`.
@@ -0,0 +1,66 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [1.0.0] - 2026-11-18
8
+
9
+ The first version of the standard and its checker.
10
+
11
+ ### Added
12
+
13
+ - **The FSD standard 1.0**, as data in `standard.toml`: five tracks (operation,
14
+ assurance, security, delivery, documentation) and eighteen technology-agnostic
15
+ atoms. Each atom has a contract, an effect class (read-only, local, host,
16
+ external), an evidence kind (command, file) and a strength per
17
+ profile: `library` (consumed), `application` (installed), `service`
18
+ (deployed). Notable atoms: `status`, the state and recent output of what
19
+ `start` brought up; `install`, the built artifact onto this machine;
20
+ `manual`, the files that show a person or an agent how to start. Assurance,
21
+ security and documentation are checks tracks: their atoms check rather than
22
+ act, so each runs as a whole, and together they are the gate.
23
+ - **`fsd.toml`**: a repository binds each atom to a command, a list of commands
24
+ run in order, `{ run = …, results = [...] }`, one or several files, or
25
+ `{ na = "reason" }`, under the section of the atom's track. Any other name
26
+ under a track is a custom atom of that track: runnable, reported, never
27
+ scored, and run with its track when that track is a checks track. A custom
28
+ atom may not take a track's or a command's name. Paths stay inside
29
+ the repository, and unknown keys are refused. `standard = "1.0"` names the
30
+ version a file was written for; a checker reads every file of its own major
31
+ version up to its own minor. The file is found by searching upward from the
32
+ current directory.
33
+ - **`Project`**, the one entry point. `Project.find()` and `Project.load(root)`
34
+ read `fsd.toml` against the shipped standard.
35
+ - `.check()` returns `Compliance` per track and executes nothing. A missing
36
+ `must` fails its track; a missing `should` is a warning.
37
+ - `.run(name, *args)` executes a binding through the platform shell. Arguments
38
+ go to every command that says `{args}`, or at the end of a single command;
39
+ a list of several without the placeholder takes none. Given a checks track, it checks that
40
+ track's compliance, then runs its atoms in order and stops at the first
41
+ failure. Operation and delivery never run as a whole, so nothing that acts
42
+ beyond the workspace runs unless named.
43
+ - `.report()` runs every routine atom without stopping. It keeps evidence per
44
+ atom (steps, exit code, UTC start, duration, output tail) and reads
45
+ measurements from JUnit XML, Cobertura XML and SARIF. A service's `start`,
46
+ `status` and `stop` run as one bracket, and a process `start` leaves
47
+ running in the background does not hold the report open.
48
+ - Output goes to an `on_output` callback when one is given; the library never
49
+ prints.
50
+ - **The `fsd` command**:
51
+ - bare `fsd` shows the repository as a boxed table;
52
+ - `fsd <atom> [args...]` runs an atom;
53
+ - `fsd <track>` runs one checks track; `fsd assurance`, `fsd security`
54
+ and `fsd documentation` are the gate;
55
+ - `fsd report` writes `fsd-report.json` and `fsd-report.md`;
56
+ - `fsd help [atom] [--json]` shows the standard, or one atom's contract;
57
+ - `-C DIR` starts somewhere else.
58
+
59
+ Exit codes: 0 passed, 1 not met, 2 invalid input.
60
+ - **Built on the `forktex` substrate**:
61
+ - errors are `AppError` subclasses with codes and `details`
62
+ (`BindingError`, `InvalidStandardError`, `ProjectNotFoundError`,
63
+ `UnknownAtomError`, `UsageError`);
64
+ - values are `BaseValueObject`;
65
+ - the report is a wire object, with camelCase JSON and canonical UTC times;
66
+ - logging goes through `forktex.log`, and the library never prints.
@@ -0,0 +1,45 @@
1
+ ForkTex FSD -- Dual License
2
+
3
+ Copyright (C) 2026 FORKTEX S.R.L.
4
+
5
+ This software is licensed under a dual-license model:
6
+
7
+ ============================================================================
8
+
9
+ 1. OPEN-SOURCE LICENSE -- GNU Affero General Public License v3.0 (AGPL-3.0)
10
+
11
+ You may use, modify, and redistribute this software under the terms of the
12
+ GNU Affero General Public License v3.0 or later, as published by the Free
13
+ Software Foundation. The full license text is available at:
14
+ https://www.gnu.org/licenses/agpl-3.0.html
15
+
16
+ Key obligations under AGPL-3.0:
17
+ - Any modified version MUST be released under the same AGPL-3.0 license.
18
+ - If you run a modified version on a server and let users interact with it
19
+ over a network, you MUST make the complete source code available to those
20
+ users under AGPL-3.0.
21
+ - You MUST preserve all copyright notices and attribution to FORKTEX S.R.L.
22
+
23
+ ============================================================================
24
+
25
+ 2. COMMERCIAL LICENSE
26
+
27
+ If you wish to use this software without the obligations of AGPL-3.0 --
28
+ for example, to keep your modifications proprietary, to embed this software
29
+ in a closed-source product, or to operate it as part of a commercial service
30
+ without releasing your source code -- you MUST obtain a commercial license
31
+ from FORKTEX S.R.L.
32
+
33
+ Commercial licensing includes, but is not limited to:
34
+ - SaaS / hosted deployments generating revenue
35
+ - Embedding in proprietary products or platforms
36
+ - Redistribution in closed-source form
37
+ - Use by organizations exceeding the AGPL-3.0 compliance scope
38
+
39
+ For commercial licensing inquiries, contact:
40
+ info@forktex.com
41
+
42
+ ============================================================================
43
+
44
+ Unless you have obtained a separate commercial license from FORKTEX S.R.L.,
45
+ your use of this software is governed exclusively by the AGPL-3.0 license.
@@ -0,0 +1,18 @@
1
+ ForkTex FSD
2
+ Copyright (C) 2026 FORKTEX S.R.L.
3
+
4
+ ForkTex FSD is a general-purpose software compliance standard and the tool
5
+ that checks it: technology-agnostic atoms grouped into tracks, bound per
6
+ repository in fsd.toml.
7
+
8
+ This product is dual-licensed:
9
+
10
+ * GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), or
11
+ * A proprietary commercial license from FORKTEX S.R.L.
12
+
13
+ If you cannot meet the obligations of the AGPL -- including its network-use
14
+ source-disclosure requirement -- you MUST obtain a commercial license before
15
+ using this software. Contact info@forktex.com.
16
+
17
+ Third-party components are distributed under their own licenses; see the
18
+ dependency metadata in pyproject.toml.
@@ -0,0 +1,216 @@
1
+ Metadata-Version: 2.4
2
+ Name: forktex-fsd
3
+ Version: 1.0.0
4
+ Summary: A general-purpose software compliance standard: technology-agnostic atoms in tracks, bound per repository in fsd.toml, checked and run by one small tool.
5
+ License-Expression: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
6
+ License-File: LICENSE
7
+ License-File: NOTICE
8
+ Keywords: compliance,standard,quality-gate,delivery,task-runner,fsd
9
+ Author: FORKTEX
10
+ Author-email: info@forktex.com
11
+ Requires-Python: >=3.14,<4.0
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Software Development :: Quality Assurance
20
+ Classifier: Typing :: Typed
21
+ Requires-Dist: forktex (>=1.2,<2)
22
+ Requires-Dist: pydantic (>=2.14)
23
+ Project-URL: Bug Tracker, https://github.com/forktex/forktex-fsd/issues
24
+ Project-URL: Changelog, https://github.com/forktex/forktex-fsd/blob/master/CHANGELOG.md
25
+ Project-URL: Documentation, https://github.com/forktex/forktex-fsd/tree/master/docs
26
+ Project-URL: Homepage, https://forktex.com
27
+ Project-URL: Repository, https://github.com/forktex/forktex-fsd
28
+ Description-Content-Type: text/markdown
29
+
30
+ <p align="center">
31
+ <img src="https://raw.githubusercontent.com/forktex/forktex-fsd/master/docs/assets/fsd-banner.png" alt="forktex-fsd" height="120">
32
+ </p>
33
+
34
+ <p align="center">
35
+ <a href="https://pypi.org/project/forktex-fsd/"><img src="https://img.shields.io/pypi/v/forktex-fsd.svg" alt="PyPI"></a>
36
+ <a href="https://pypi.org/project/forktex-fsd/"><img src="https://img.shields.io/pypi/pyversions/forktex-fsd.svg" alt="Python"></a>
37
+ <a href="https://github.com/forktex/forktex-fsd/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/forktex-fsd.svg" alt="License"></a>
38
+ </p>
39
+
40
+ # forktex-fsd
41
+
42
+ **FSD**, the ForkTex Standard of Delivery, is a technology-agnostic standard for
43
+ how a repository is set up, checked, built and shipped, and `fsd` is the small
44
+ tool that holds a repository to it.
45
+
46
+ A repository binds the standard's atoms, such as `test`, `audit`, `build` and
47
+ `publish`, to its own commands in one `fsd.toml`. `fsd` reports what is still
48
+ missing, track by track. It runs any atom by name on Linux, macOS or Windows,
49
+ and gates delivery on the tracks that check. It works with any language and any
50
+ toolchain: the standard says what must be true, never which tool makes it so.
51
+
52
+ ## Installation
53
+
54
+ ```bash
55
+ uv tool install forktex-fsd # or: pipx install forktex-fsd
56
+ ```
57
+
58
+ `fsd` runs on Python 3.14; `uv tool install` brings its own, so the repository
59
+ being checked need not be Python. To use the library, add `forktex-fsd` to your
60
+ project's dependencies.
61
+
62
+ ## Quick start
63
+
64
+ Put an `fsd.toml` at the root of the repository:
65
+
66
+ ```toml
67
+ # fsd.toml
68
+ standard = "1.0"
69
+ profile = "library"
70
+
71
+ [operation]
72
+ setup = "poetry install"
73
+
74
+ [assurance]
75
+ format = "ruff format --check ."
76
+ lint = ["ruff check .", "lint-imports"]
77
+ test = "pytest -q"
78
+
79
+ [security]
80
+ audit = "pip-audit"
81
+
82
+ [delivery]
83
+ build = "python -m build"
84
+ publish = "twine upload dist/*"
85
+
86
+ [documentation]
87
+ manual = { file = ["README.md", "AGENTS.md"] }
88
+ ```
89
+
90
+ Then:
91
+
92
+ ```bash
93
+ fsd # every atom, its binding, and compliance per track
94
+ fsd test -k smoke # one atom; what follows goes to its command
95
+ fsd assurance # one track that checks: its compliance, then every atom in it
96
+ fsd report # everything routine, without stopping: fsd-report.json and .md
97
+ ```
98
+
99
+ ## The standard
100
+
101
+ The standard has five **tracks**, and each is judged on its own, so strength on
102
+ one never hides a gap on another. The **profile** says how the software
103
+ reaches its user:
104
+ - a `library` is consumed as a dependency;
105
+ - an `application` is installed onto a machine;
106
+ - a `service` is deployed and operated.
107
+
108
+ The profile decides whether each atom is `must` (a gap fails its track),
109
+ `should` (a gap is a warning) or `na` (it does not apply). Each atom also has an
110
+ **effect**: what running it touches, from `read-only` to `external`.
111
+
112
+ | Track | Atom | It means | Effect | library | application | service |
113
+ |---|---|---|---|:-:|:-:|:-:|
114
+ | **operation** | `setup` | everything needed to build and run it is installed, from a fresh checkout | local | must | must | must |
115
+ | | `start` | it runs locally | local | na | na | must |
116
+ | | `stop` | what `start` brought up is torn down | local | na | na | must |
117
+ | | `status` | whether it is running, with its recent output | read-only | na | na | must |
118
+ | | `clean` | everything the build and the run produced is removed | local | should | should | should |
119
+ | **assurance** ✓ | `format` | the source layout conforms to the project's style | read-only | must | must | must |
120
+ | | `lint` | static analysis finds no defects or unsafe patterns | read-only | must | must | must |
121
+ | | `validate` | the source is statically consistent: types, schemas, contracts | read-only | should | should | should |
122
+ | | `test` | the software's own tests pass | local | must | must | must |
123
+ | | `license` | the licence is declared and applied to every source file | read-only | should | should | should |
124
+ | **security** ✓ | `audit` | dependencies are free of known vulnerabilities | read-only | must | must | must |
125
+ | **delivery** | `build` | the source becomes the deliverable artifact | local | must | must | must |
126
+ | | `install` | the artifact is put onto this machine | host | na | must | na |
127
+ | | `publish` | a versioned artifact is put where consumers fetch it | external | must | should | should |
128
+ | | `deploy` | a version is put into a named environment | external | na | na | must |
129
+ | | `rollback` | an environment returns to its previous version | external | na | na | should |
130
+ | **documentation** ✓ | `manual` | a newcomer, a person or an agent, can start from the repository alone | read-only | must | must | must |
131
+
132
+ ✓ A track that checks rather than acts. It runs as a whole, as in
133
+ `fsd assurance`: first its compliance, then its atoms in order, stopping at the
134
+ first failure. Together these tracks are the gate: `fsd assurance`,
135
+ `fsd security`, `fsd documentation`. Operation and delivery act,
136
+ so their atoms run only by name. `fsd help <atom>` prints any atom's full
137
+ contract.
138
+
139
+ ## Configuration
140
+
141
+ Each atom is bound under the section of its own track:
142
+
143
+ | Form | Example | Meaning |
144
+ |---|---|---|
145
+ | command | `test = "pytest -q"` | run through the platform shell: `sh`, or `cmd` on Windows |
146
+ | steps | `lint = ["ruff check .", "lint-imports"]` | run in order; the first failure stops the atom |
147
+ | with results | `test = { run = "pytest --junitxml=build/junit.xml", results = ["build/junit.xml"] }` | files `fsd report` reads: JUnit, Cobertura, SARIF |
148
+ | files | `manual = { file = ["README.md", "AGENTS.md"] }` | every file must exist |
149
+ | not applicable | `publish = { na = "an internal tool" }` | the atom does not apply here, and why |
150
+
151
+ Any other name under a track is a **custom atom** of that track, such as
152
+ `migrate` under `[operation]`. It runs by name and is listed, but it never
153
+ counts for compliance. Under a track that checks, it runs with that track.
154
+ Arguments after an atom's name go where its commands say `{args}`, quoted for
155
+ the shell. A single command without the placeholder takes them at its end, and
156
+ a list of several commands without it takes none.
157
+
158
+ ## Command line
159
+
160
+ | Command | Does |
161
+ |---|---|
162
+ | `fsd` | The repository: every atom, its binding, compliance per track |
163
+ | `fsd <atom> [args...]` | Runs one atom, standard or custom |
164
+ | `fsd <track>` | Runs a track that checks: its compliance, then its atoms in order |
165
+ | `fsd report` | Runs every routine atom without stopping; writes `fsd-report.json` and `fsd-report.md` |
166
+ | `fsd help [name] [--json]` | The standard, one track, or one atom |
167
+ | `fsd --version` | The version of `fsd` and of its standard |
168
+ | `fsd -C DIR …` | Starts the search for `fsd.toml` in `DIR` instead of the current directory |
169
+
170
+ Exit codes: `0` passed, `1` not compliant or something failed, `2` invalid
171
+ input. Checking executes nothing, so bare `fsd` is safe on a repository you do
172
+ not trust.
173
+
174
+ ## Python interface
175
+
176
+ ```python
177
+ from forktex_fsd import Project
178
+
179
+ project = Project.find() # the nearest fsd.toml at or above the working directory
180
+ compliance = project.check() # per track; executes nothing
181
+ results = project.run("assurance") # one atom or one track
182
+ report = project.report() # every routine atom, with evidence
183
+ print(compliance.compliant, report.passed)
184
+ ```
185
+
186
+ ## Documentation
187
+
188
+ | Page | For |
189
+ |---|---|
190
+ | [Guide](https://github.com/forktex/forktex-fsd/blob/master/docs/guide.md) | Complete, copyable setups: a library, a service, any stack, custom atoms, CI, reports, Python |
191
+ | [Reference](https://github.com/forktex/forktex-fsd/blob/master/docs/reference.md) | The standard, `fsd.toml`, the commands, every public name and error |
192
+
193
+ ## Versioning
194
+
195
+ Semantic versioning covers:
196
+ - the names in `forktex_fsd.__all__`;
197
+ - the `fsd.toml` format of each standard version;
198
+ - the `fsd` commands and their exit codes;
199
+ - the JSON of `fsd-report.json` and of `fsd help --json`.
200
+
201
+ `fsd.toml` names the standard version it was written for. `fsd` reads any file
202
+ of its own major version up to its own minor, and refuses any other, so a
203
+ change of standard is never silent. Changes are listed in the
204
+ [CHANGELOG](https://github.com/forktex/forktex-fsd/blob/master/CHANGELOG.md).
205
+
206
+ ## Contributing
207
+
208
+ Working on `forktex-fsd` itself? Start with
209
+ [`docs/development.md`](https://github.com/forktex/forktex-fsd/blob/master/docs/development.md). Security issues go to the address
210
+ in [SECURITY.md](https://github.com/forktex/forktex-fsd/blob/master/SECURITY.md).
211
+
212
+ ## Licence
213
+
214
+ AGPL-3.0-or-later, or a commercial licence from FORKTEX S.R.L.
215
+ (info@forktex.com). See [LICENSE](https://github.com/forktex/forktex-fsd/blob/master/LICENSE) and [NOTICE](https://github.com/forktex/forktex-fsd/blob/master/NOTICE).
216
+
@@ -0,0 +1,186 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/forktex/forktex-fsd/master/docs/assets/fsd-banner.png" alt="forktex-fsd" height="120">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="https://pypi.org/project/forktex-fsd/"><img src="https://img.shields.io/pypi/v/forktex-fsd.svg" alt="PyPI"></a>
7
+ <a href="https://pypi.org/project/forktex-fsd/"><img src="https://img.shields.io/pypi/pyversions/forktex-fsd.svg" alt="Python"></a>
8
+ <a href="https://github.com/forktex/forktex-fsd/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/forktex-fsd.svg" alt="License"></a>
9
+ </p>
10
+
11
+ # forktex-fsd
12
+
13
+ **FSD**, the ForkTex Standard of Delivery, is a technology-agnostic standard for
14
+ how a repository is set up, checked, built and shipped, and `fsd` is the small
15
+ tool that holds a repository to it.
16
+
17
+ A repository binds the standard's atoms, such as `test`, `audit`, `build` and
18
+ `publish`, to its own commands in one `fsd.toml`. `fsd` reports what is still
19
+ missing, track by track. It runs any atom by name on Linux, macOS or Windows,
20
+ and gates delivery on the tracks that check. It works with any language and any
21
+ toolchain: the standard says what must be true, never which tool makes it so.
22
+
23
+ ## Installation
24
+
25
+ ```bash
26
+ uv tool install forktex-fsd # or: pipx install forktex-fsd
27
+ ```
28
+
29
+ `fsd` runs on Python 3.14; `uv tool install` brings its own, so the repository
30
+ being checked need not be Python. To use the library, add `forktex-fsd` to your
31
+ project's dependencies.
32
+
33
+ ## Quick start
34
+
35
+ Put an `fsd.toml` at the root of the repository:
36
+
37
+ ```toml
38
+ # fsd.toml
39
+ standard = "1.0"
40
+ profile = "library"
41
+
42
+ [operation]
43
+ setup = "poetry install"
44
+
45
+ [assurance]
46
+ format = "ruff format --check ."
47
+ lint = ["ruff check .", "lint-imports"]
48
+ test = "pytest -q"
49
+
50
+ [security]
51
+ audit = "pip-audit"
52
+
53
+ [delivery]
54
+ build = "python -m build"
55
+ publish = "twine upload dist/*"
56
+
57
+ [documentation]
58
+ manual = { file = ["README.md", "AGENTS.md"] }
59
+ ```
60
+
61
+ Then:
62
+
63
+ ```bash
64
+ fsd # every atom, its binding, and compliance per track
65
+ fsd test -k smoke # one atom; what follows goes to its command
66
+ fsd assurance # one track that checks: its compliance, then every atom in it
67
+ fsd report # everything routine, without stopping: fsd-report.json and .md
68
+ ```
69
+
70
+ ## The standard
71
+
72
+ The standard has five **tracks**, and each is judged on its own, so strength on
73
+ one never hides a gap on another. The **profile** says how the software
74
+ reaches its user:
75
+ - a `library` is consumed as a dependency;
76
+ - an `application` is installed onto a machine;
77
+ - a `service` is deployed and operated.
78
+
79
+ The profile decides whether each atom is `must` (a gap fails its track),
80
+ `should` (a gap is a warning) or `na` (it does not apply). Each atom also has an
81
+ **effect**: what running it touches, from `read-only` to `external`.
82
+
83
+ | Track | Atom | It means | Effect | library | application | service |
84
+ |---|---|---|---|:-:|:-:|:-:|
85
+ | **operation** | `setup` | everything needed to build and run it is installed, from a fresh checkout | local | must | must | must |
86
+ | | `start` | it runs locally | local | na | na | must |
87
+ | | `stop` | what `start` brought up is torn down | local | na | na | must |
88
+ | | `status` | whether it is running, with its recent output | read-only | na | na | must |
89
+ | | `clean` | everything the build and the run produced is removed | local | should | should | should |
90
+ | **assurance** ✓ | `format` | the source layout conforms to the project's style | read-only | must | must | must |
91
+ | | `lint` | static analysis finds no defects or unsafe patterns | read-only | must | must | must |
92
+ | | `validate` | the source is statically consistent: types, schemas, contracts | read-only | should | should | should |
93
+ | | `test` | the software's own tests pass | local | must | must | must |
94
+ | | `license` | the licence is declared and applied to every source file | read-only | should | should | should |
95
+ | **security** ✓ | `audit` | dependencies are free of known vulnerabilities | read-only | must | must | must |
96
+ | **delivery** | `build` | the source becomes the deliverable artifact | local | must | must | must |
97
+ | | `install` | the artifact is put onto this machine | host | na | must | na |
98
+ | | `publish` | a versioned artifact is put where consumers fetch it | external | must | should | should |
99
+ | | `deploy` | a version is put into a named environment | external | na | na | must |
100
+ | | `rollback` | an environment returns to its previous version | external | na | na | should |
101
+ | **documentation** ✓ | `manual` | a newcomer, a person or an agent, can start from the repository alone | read-only | must | must | must |
102
+
103
+ ✓ A track that checks rather than acts. It runs as a whole, as in
104
+ `fsd assurance`: first its compliance, then its atoms in order, stopping at the
105
+ first failure. Together these tracks are the gate: `fsd assurance`,
106
+ `fsd security`, `fsd documentation`. Operation and delivery act,
107
+ so their atoms run only by name. `fsd help <atom>` prints any atom's full
108
+ contract.
109
+
110
+ ## Configuration
111
+
112
+ Each atom is bound under the section of its own track:
113
+
114
+ | Form | Example | Meaning |
115
+ |---|---|---|
116
+ | command | `test = "pytest -q"` | run through the platform shell: `sh`, or `cmd` on Windows |
117
+ | steps | `lint = ["ruff check .", "lint-imports"]` | run in order; the first failure stops the atom |
118
+ | with results | `test = { run = "pytest --junitxml=build/junit.xml", results = ["build/junit.xml"] }` | files `fsd report` reads: JUnit, Cobertura, SARIF |
119
+ | files | `manual = { file = ["README.md", "AGENTS.md"] }` | every file must exist |
120
+ | not applicable | `publish = { na = "an internal tool" }` | the atom does not apply here, and why |
121
+
122
+ Any other name under a track is a **custom atom** of that track, such as
123
+ `migrate` under `[operation]`. It runs by name and is listed, but it never
124
+ counts for compliance. Under a track that checks, it runs with that track.
125
+ Arguments after an atom's name go where its commands say `{args}`, quoted for
126
+ the shell. A single command without the placeholder takes them at its end, and
127
+ a list of several commands without it takes none.
128
+
129
+ ## Command line
130
+
131
+ | Command | Does |
132
+ |---|---|
133
+ | `fsd` | The repository: every atom, its binding, compliance per track |
134
+ | `fsd <atom> [args...]` | Runs one atom, standard or custom |
135
+ | `fsd <track>` | Runs a track that checks: its compliance, then its atoms in order |
136
+ | `fsd report` | Runs every routine atom without stopping; writes `fsd-report.json` and `fsd-report.md` |
137
+ | `fsd help [name] [--json]` | The standard, one track, or one atom |
138
+ | `fsd --version` | The version of `fsd` and of its standard |
139
+ | `fsd -C DIR …` | Starts the search for `fsd.toml` in `DIR` instead of the current directory |
140
+
141
+ Exit codes: `0` passed, `1` not compliant or something failed, `2` invalid
142
+ input. Checking executes nothing, so bare `fsd` is safe on a repository you do
143
+ not trust.
144
+
145
+ ## Python interface
146
+
147
+ ```python
148
+ from forktex_fsd import Project
149
+
150
+ project = Project.find() # the nearest fsd.toml at or above the working directory
151
+ compliance = project.check() # per track; executes nothing
152
+ results = project.run("assurance") # one atom or one track
153
+ report = project.report() # every routine atom, with evidence
154
+ print(compliance.compliant, report.passed)
155
+ ```
156
+
157
+ ## Documentation
158
+
159
+ | Page | For |
160
+ |---|---|
161
+ | [Guide](https://github.com/forktex/forktex-fsd/blob/master/docs/guide.md) | Complete, copyable setups: a library, a service, any stack, custom atoms, CI, reports, Python |
162
+ | [Reference](https://github.com/forktex/forktex-fsd/blob/master/docs/reference.md) | The standard, `fsd.toml`, the commands, every public name and error |
163
+
164
+ ## Versioning
165
+
166
+ Semantic versioning covers:
167
+ - the names in `forktex_fsd.__all__`;
168
+ - the `fsd.toml` format of each standard version;
169
+ - the `fsd` commands and their exit codes;
170
+ - the JSON of `fsd-report.json` and of `fsd help --json`.
171
+
172
+ `fsd.toml` names the standard version it was written for. `fsd` reads any file
173
+ of its own major version up to its own minor, and refuses any other, so a
174
+ change of standard is never silent. Changes are listed in the
175
+ [CHANGELOG](https://github.com/forktex/forktex-fsd/blob/master/CHANGELOG.md).
176
+
177
+ ## Contributing
178
+
179
+ Working on `forktex-fsd` itself? Start with
180
+ [`docs/development.md`](https://github.com/forktex/forktex-fsd/blob/master/docs/development.md). Security issues go to the address
181
+ in [SECURITY.md](https://github.com/forktex/forktex-fsd/blob/master/SECURITY.md).
182
+
183
+ ## Licence
184
+
185
+ AGPL-3.0-or-later, or a commercial licence from FORKTEX S.R.L.
186
+ (info@forktex.com). See [LICENSE](https://github.com/forktex/forktex-fsd/blob/master/LICENSE) and [NOTICE](https://github.com/forktex/forktex-fsd/blob/master/NOTICE).
@@ -0,0 +1,37 @@
1
+ # Security Policy
2
+
3
+ ## Reporting a vulnerability
4
+
5
+ Email **info@forktex.com** with details and, where possible, a reproduction. Please do
6
+ not open a public issue for an unfixed vulnerability.
7
+
8
+ ## Supported versions
9
+
10
+ | Version | Supported |
11
+ | --- | --- |
12
+ | 1.x | ✅ |
13
+
14
+ ## Scope
15
+
16
+ `forktex-fsd` reads a repository's `fsd.toml` and, when asked through `fsd <atom>`,
17
+ `fsd <track>` or `fsd report`, executes the commands that file names.
18
+
19
+ - **The compliance check executes nothing.** `Project.check()` reads `fsd.toml` and tests
20
+ whether bound files exist; it is safe on an untrusted repository. `fsd <track>`
21
+ runs the check and then the repository's own commands.
22
+ - **Running an atom, a track or a report executes the repository's own commands**, with the caller's privileges and
23
+ in the repository's directory. A string binding runs through the platform shell.
24
+ Running an atom, a track or `fsd report` on a repository you do not trust is running that repository's
25
+ code — exactly as `make` or `npm run` would be.
26
+ - **Atoms beyond the workspace** (`install`, `publish`, `deploy`, `rollback`) belong to no track that runs
27
+ as a whole, and a report leaves them out; they run only when named on their own.
28
+ - **`fsd report` runs every routine atom**, including `setup` and any custom
29
+ atom of a checks track, and reads the result files the bindings name from
30
+ the repository's own tree.
31
+ - **Arguments** passed after an atom's name are quoted for the platform shell.
32
+ Under Windows `cmd`, a `%` in an argument still expands an environment
33
+ variable; `cmd` has no escape for it inside a quoted argument. A binding that wraps
34
+ `{args}` in its own quotes (`"{args}"`) undoes the quoting, and the shell
35
+ expands what is inside: write `{args}` bare.
36
+ - **File and result paths** must stay inside the repository; a symbolic link
37
+ that resolves outside it is treated as missing, never read.