factory-framework 0.3.1__py3-none-any.whl
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.
- factory_framework-0.3.1.dist-info/METADATA +205 -0
- factory_framework-0.3.1.dist-info/RECORD +24 -0
- factory_framework-0.3.1.dist-info/WHEEL +4 -0
- factory_framework-0.3.1.dist-info/entry_points.txt +3 -0
- factory_framework-0.3.1.dist-info/licenses/LICENSE +21 -0
- ff/__init__.py +18 -0
- ff/__main__.py +7 -0
- ff/cli.py +320 -0
- ff/export.py +234 -0
- ff/gitio.py +229 -0
- ff/lint.py +202 -0
- ff/mcp.py +138 -0
- ff/models.py +372 -0
- ff/parse.py +457 -0
- ff/proofs.py +178 -0
- ff/py.typed +0 -0
- ff/query.py +118 -0
- ff/runner.py +239 -0
- ff/scaffold.py +239 -0
- ff/schemas.py +141 -0
- ff/skill/SKILL.md +47 -0
- ff/skill/references/authoring.md +59 -0
- ff/skill/references/checks.md +69 -0
- ff/skill/references/workflow.md +55 -0
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: factory-framework
|
|
3
|
+
Version: 0.3.1
|
|
4
|
+
Summary: Factory Framework (ff) links human intents and specs to parallel executable checks, records validated metrics, and exports stakeholder-ready proofs.
|
|
5
|
+
Keywords: ai,ai-agents,agent-skills,agents-md,fitness-functions,local-first,mcp,model-context-protocol,python,software-engineering,software-factory,spec-driven-development,traceability
|
|
6
|
+
Author: Médéric Hurier
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: MacOS
|
|
13
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
17
|
+
Classifier: Topic :: Software Development :: Testing
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Dist: jsonschema>=4.26.0,<5
|
|
20
|
+
Requires-Dist: markdown>=3.11,<4
|
|
21
|
+
Requires-Dist: pyyaml>=6.0.3,<7
|
|
22
|
+
Requires-Dist: rich>=15.0.0,<16
|
|
23
|
+
Requires-Dist: mcp>=2.3,<3 ; extra == 'mcp'
|
|
24
|
+
Requires-Dist: pydantic>=2.14,<3 ; extra == 'mcp'
|
|
25
|
+
Requires-Dist: uvicorn>=0.54,<1 ; extra == 'mcp'
|
|
26
|
+
Requires-Dist: pytest>=9.1.1,<10 ; extra == 'pytest'
|
|
27
|
+
Requires-Python: >=3.14
|
|
28
|
+
Project-URL: Changelog, https://fmind.github.io/factory-framework/changelog/
|
|
29
|
+
Project-URL: Documentation, https://fmind.github.io/factory-framework/
|
|
30
|
+
Project-URL: Issues, https://github.com/fmind/factory-framework/issues
|
|
31
|
+
Project-URL: Repository, https://github.com/fmind/factory-framework
|
|
32
|
+
Project-URL: Security, https://github.com/fmind/factory-framework/security/policy
|
|
33
|
+
Provides-Extra: mcp
|
|
34
|
+
Provides-Extra: pytest
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
<p align="center">
|
|
38
|
+
<img
|
|
39
|
+
src="docs/assets/factory-framework.svg"
|
|
40
|
+
alt="Factory Framework mirrored F | F logo"
|
|
41
|
+
width="128"
|
|
42
|
+
height="128"
|
|
43
|
+
>
|
|
44
|
+
</p>
|
|
45
|
+
|
|
46
|
+
# Factory Framework
|
|
47
|
+
|
|
48
|
+
**Turn plain-Markdown requirements into proven software.**
|
|
49
|
+
|
|
50
|
+
[](https://github.com/fmind/factory-framework/actions/workflows/ci.yml) [](pyproject.toml) [](LICENSE)
|
|
51
|
+
|
|
52
|
+
Factory Framework (`ff`) connects human product goals to automated tests in plain files inside your repository. Product owners, engineers, and AI coding agents work from one source of truth, and proof reports come from real executions — never manual checkboxes.
|
|
53
|
+
|
|
54
|
+
[Overview](#overview) · [Benefits](#benefits) · [Installation](#installation) · [Usage](#usage) · [Example](#example) · [Documentation](#documentation)
|
|
55
|
+
|
|
56
|
+
## Overview
|
|
57
|
+
|
|
58
|
+
Teams lose alignment when requirements live in wikis, tests check implementation details instead of user outcomes, and nobody knows what is truly proven.
|
|
59
|
+
|
|
60
|
+
`ff` organizes every domain inside `factory/` with 1-to-1 file symmetry:
|
|
61
|
+
|
|
62
|
+
- **Intents** (`intents/<domain>.md`) capture **why** a capability matters for humans (User Stories recommended).
|
|
63
|
+
- **Specs** (`specs/<domain>.md`) define **what** the system guarantees (Given/When/Then or EARS recommended).
|
|
64
|
+
- **Checks** (`checks/<domain>.yaml` + `tests/*`) map specs and numeric bounds to real tests in any language.
|
|
65
|
+
- **Proofs** (`proofs/<domain>.json`) record digests, measured metrics, evidence, and computed `PROVEN`, `FAILING`, `UNPROVEN`, `UNCLEAR`, or `ERROR` verdicts.
|
|
66
|
+
|
|
67
|
+
<p align="center">
|
|
68
|
+
<a href="docs/assets/how-it-works.png">
|
|
69
|
+
<img
|
|
70
|
+
src="docs/assets/how-it-works.png"
|
|
71
|
+
alt="How Factory Framework links Markdown intents and specs to parallel tests and domain proofs"
|
|
72
|
+
width="960"
|
|
73
|
+
>
|
|
74
|
+
</a>
|
|
75
|
+
</p>
|
|
76
|
+
|
|
77
|
+
## Benefits
|
|
78
|
+
|
|
79
|
+
- **Plain Markdown, zero clutter.** Write pure headings and prose with zero `{#id}` anchors or `[x]` checkboxes. Folder and heading names wire `intent <- spec <- check` automatically.
|
|
80
|
+
- **Computed verdicts you can trust.** A spec turns `PROVEN` only when its checks execute, exit `0`, and satisfy every metric bound declared in `checks/<domain>.yaml`.
|
|
81
|
+
- **Polyglot by default.** Run Python, Bash, Node.js, Java, Go, or Rust tests in parallel. Scripts can optionally write JSON metrics and evidence to `$FF_RECORD`, or keep using plain exit codes.
|
|
82
|
+
- **Change accountability built in.** Document contract shifts in `factory/changes/YYYY-MM-DD_<slug>.md` or labeled GitHub issues; `ff verify --base` blocks silent weakening of proven specs, checks, or thresholds.
|
|
83
|
+
- **Built for both humans and coding agents.** Export polished HTML, Markdown, CSV, or JSONL summaries with `ff export`, and equip agents with `/ff` (`ff skill install`) and optional read-only `ff mcp`.
|
|
84
|
+
|
|
85
|
+
## Installation
|
|
86
|
+
|
|
87
|
+
Requires Python 3.14+ on Linux or macOS with [`uv`](https://docs.astral.sh/uv/getting-started/installation/):
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
uv tool install --python 3.14 factory-framework
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Add optional extras when needed (`[pytest]` for pytest test-suite helpers, `[mcp]` for the read-only MCP server):
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
uv tool install --python 3.14 "factory-framework[pytest,mcp]"
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Usage
|
|
100
|
+
|
|
101
|
+
Scaffold a starter contract, run checks, verify reproducibility, and export a report:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
ff init --example # Add --pytest to scaffold pytest fixtures instead of a standalone script
|
|
105
|
+
ff run
|
|
106
|
+
ff status
|
|
107
|
+
ff verify --strict
|
|
108
|
+
ff export -f html -o proof-report.html
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Everyday commands at a glance:
|
|
112
|
+
|
|
113
|
+
- `ff init [--example] [--pytest]` — create `factory/` with a zero-dependency starter check (or `pytest` fixtures with `--pytest`).
|
|
114
|
+
- `ff status` and `ff ls --tree` — inspect domain verdicts and trace links from intents to specs and checks.
|
|
115
|
+
- `ff show <id>` — read full statements, metric bounds, and latest recorded evidence for any item.
|
|
116
|
+
- `ff lint` and `ff verify` — check domain symmetry (`FF001`–`FF012`), re-run tests, and enforce `--base` anti-weakening rules (`FFR0`–`FFR4`).
|
|
117
|
+
- `ff export -f html|md|csv|jsonl` — share proof reports with stakeholders.
|
|
118
|
+
- `ff skill install` and `ff mcp` — equip coding agents with `/ff` workflow instructions and read-only contract inspection.
|
|
119
|
+
|
|
120
|
+
## Example
|
|
121
|
+
|
|
122
|
+
Suppose you want fast, accurate checkout pricing in domain `checkout`.
|
|
123
|
+
|
|
124
|
+
**1. State why in `factory/intents/checkout.md`:**
|
|
125
|
+
|
|
126
|
+
```markdown
|
|
127
|
+
# Checkout
|
|
128
|
+
|
|
129
|
+
## Fast Totals
|
|
130
|
+
|
|
131
|
+
As a shopper, I want accurate order totals immediately, so that slow pricing never delays my purchase.
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
**2. State what in `factory/specs/checkout.md`:**
|
|
135
|
+
|
|
136
|
+
```markdown
|
|
137
|
+
# Checkout
|
|
138
|
+
|
|
139
|
+
## Fast Totals
|
|
140
|
+
|
|
141
|
+
### Latency
|
|
142
|
+
|
|
143
|
+
Given a cart with regional shipping rules, when checkout totals are requested, then pricing, tax, and totals return in 50 ms or less.
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
**3. Declare bounds and check targets in `factory/checks/checkout.yaml`:**
|
|
147
|
+
|
|
148
|
+
```yaml
|
|
149
|
+
version: 1
|
|
150
|
+
domain: checkout
|
|
151
|
+
|
|
152
|
+
checks:
|
|
153
|
+
check_checkout_fast-totals_latency:
|
|
154
|
+
file: tests/check_checkout.py
|
|
155
|
+
metrics:
|
|
156
|
+
p95_ms: { max: 50, precision: 0, unit: ms }
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
**4. Prove it with a behavioral check in `factory/tests/check_checkout.py`:**
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
import json, os
|
|
163
|
+
from pathlib import Path
|
|
164
|
+
|
|
165
|
+
elapsed_ms, body = call_checkout(items=3, region="EU")
|
|
166
|
+
assert body["tax"] > 0 and body["total"] > body["subtotal"]
|
|
167
|
+
|
|
168
|
+
if record_path := os.environ.get("FF_RECORD"):
|
|
169
|
+
Path(record_path).write_text(
|
|
170
|
+
json.dumps(
|
|
171
|
+
{
|
|
172
|
+
"summary": "Checkout returned tax and totals under 50 ms",
|
|
173
|
+
"metrics": {"p95_ms": elapsed_ms},
|
|
174
|
+
"evidence": [f"p95_ms={elapsed_ms}", f"total={body['total']}"],
|
|
175
|
+
}
|
|
176
|
+
),
|
|
177
|
+
encoding="utf-8",
|
|
178
|
+
)
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Using Bash, JavaScript, Go, Java, or `pytest`? Point `file:` at `.sh`/`.mjs`/`.js` scripts, use `argv: [go, test, ./...]` for compiled binaries, or pass `--pytest` on `ff init` for `ff_record` pytest fixtures.
|
|
182
|
+
|
|
183
|
+
**5. Run and inspect the verdict:**
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
ff run
|
|
187
|
+
ff status
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
Factory: shop-api | Proofs: fresh | Gate: PASSED
|
|
192
|
+
Intents: 1/1 proven | Specs: 1/1 proven | Checks: 1/1 passing
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Explore [`examples/demo-service/`](examples/demo-service/README.md) for a multi-domain `pytest` + Bash project and [`examples/checks/`](examples/checks/) for reusable check recipes.
|
|
196
|
+
|
|
197
|
+
## Documentation
|
|
198
|
+
|
|
199
|
+
- [Documentation home](docs/docs/index.md) — architecture overview and core principles
|
|
200
|
+
- [Getting started](docs/docs/getting-started.md) — installation, walkthrough, and `factory/` layout
|
|
201
|
+
- [Core concepts](docs/docs/concepts.md) — `<domain>` symmetry, leaf IDs, `$FF_RECORD`, proofs, and changes
|
|
202
|
+
- [Configuration](docs/docs/configuration.md) — `factory/ff.yaml`, `factory/checks/<domain>.yaml`, and polyglot runners
|
|
203
|
+
- [Commands](docs/docs/commands.md) — full CLI reference, rules (`FF001`–`FF012`, `FFR0`–`FFR4`), schemas, and MCP
|
|
204
|
+
- [Workflow](docs/docs/workflow.md) — daily loop, `--base` CI gates, exports, and `/ff` agent setup
|
|
205
|
+
- [AGENTS.md](AGENTS.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · [LICENSE](LICENSE)
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
ff/__init__.py,sha256=T0fJmHlQ9-nug3ep1SDOm6IwdpwL1_jJ28ac2F0UYvk,446
|
|
2
|
+
ff/__main__.py,sha256=0b16Gt3z5RnoCsQQOr3PMz-B2Z3APeFtflif_z_E0OA,130
|
|
3
|
+
ff/cli.py,sha256=V8e7lg33WhUpIk1y3CpQbII_VnEK-6PcbarYguDMzY8,17018
|
|
4
|
+
ff/export.py,sha256=xxF4m5b2RdiGV_ZJ6vzjELJlUioZNBNXfC6dQDZ1C1A,14470
|
|
5
|
+
ff/gitio.py,sha256=20mQty1LveZHJyzAV9HLX2XjjFjLFVJnRpQPTPd70jU,11505
|
|
6
|
+
ff/lint.py,sha256=QQBvIgQ3x6Odh65Dv_SIeuqrWIXGcV8nsle767sqBdg,10739
|
|
7
|
+
ff/mcp.py,sha256=dNwNKTBPfRpmH0ffbiSTzmESLX0XxZFOZaEJ3H_4b4Q,6587
|
|
8
|
+
ff/models.py,sha256=HRYNua5Ju4b1lxsgK3VBLYPnD2SiCrAYaZb_4osplSQ,12595
|
|
9
|
+
ff/parse.py,sha256=CLIKo0lfCPLpGxU8n2AjL56vHAJ2dsP1kXrwt6Edzy4,25303
|
|
10
|
+
ff/proofs.py,sha256=xT-J-pzz3e6J-9pkKoQXrUaTxDKLvp8XieMVULKErQ4,9426
|
|
11
|
+
ff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
12
|
+
ff/query.py,sha256=9szYz34uh1MWUvAsd3CfJoFGTNxOGZm_JAknRnUq1LQ,5949
|
|
13
|
+
ff/runner.py,sha256=sSaTSjHMuC3SDD3H35gWzXWqQj6XuuMHu_2iVPYrTVA,11592
|
|
14
|
+
ff/scaffold.py,sha256=QCX9nkRM-agHxZl1qimJyQSjqXr-OWOYqhlDQhbwio4,11252
|
|
15
|
+
ff/schemas.py,sha256=s66-TmD_SCDChU8c0P0GXqC-29W0JLpZTUPU1Dz_HWI,7621
|
|
16
|
+
ff/skill/SKILL.md,sha256=XD4p-6OSht9iAfG08hRRC-_XiclS_ggssc6Ozyz9BPk,2690
|
|
17
|
+
ff/skill/references/authoring.md,sha256=MsBXGahL-27_v53kXIpcux4IcIuHbkLLgUOLG3xmOic,3109
|
|
18
|
+
ff/skill/references/checks.md,sha256=czWwHD-pG_wDlD77Cf8JWinq5ugASCjt1_XCzMujKYM,2894
|
|
19
|
+
ff/skill/references/workflow.md,sha256=-T2sBDbSD5M1Wy8Pkc7yYLHetIgZYB95-a2UIVl8gjQ,3338
|
|
20
|
+
factory_framework-0.3.1.dist-info/licenses/LICENSE,sha256=ydQ3ApmdBIOOKEwsQe10dDUjk9sQeN4-8l8i_oEzIz0,1081
|
|
21
|
+
factory_framework-0.3.1.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
|
|
22
|
+
factory_framework-0.3.1.dist-info/entry_points.txt,sha256=RsQgnjt9PY3c26bQz8_5E5kFENi7I_Vnw254Ih6FIeo,32
|
|
23
|
+
factory_framework-0.3.1.dist-info/METADATA,sha256=XA6BAhoNIYjI53AnKUdfmmbGgUz0J8PC2aPTwAvgUEA,8887
|
|
24
|
+
factory_framework-0.3.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Médéric Hurier (Fmind)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
ff/__init__.py
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"""Factory Framework (`ff`): Markdown intents and specs, check configs, parallel tests, and proofs."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__version__ = "0.3.1"
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def main(argv: list[str] | None = None) -> int:
|
|
9
|
+
"""Run the `ff` CLI entry point and exit when called as a console script."""
|
|
10
|
+
from ff.cli import run
|
|
11
|
+
|
|
12
|
+
code = run(argv)
|
|
13
|
+
if argv is None:
|
|
14
|
+
raise SystemExit(code)
|
|
15
|
+
return code
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
__all__ = ["__version__", "main"]
|
ff/__main__.py
ADDED
ff/cli.py
ADDED
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
"""Stdlib `argparse` CLI for Factory Framework (`ff`)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import os
|
|
7
|
+
import sys
|
|
8
|
+
from collections.abc import Sequence
|
|
9
|
+
from dataclasses import replace
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Any, NoReturn
|
|
12
|
+
|
|
13
|
+
from rich.console import Console
|
|
14
|
+
from rich.table import Table
|
|
15
|
+
|
|
16
|
+
from ff import __version__, export, lint, proofs, query, runner, scaffold, schemas
|
|
17
|
+
from ff.models import Error, InputError, atomic_write, format_json, printable, terminal_json
|
|
18
|
+
from ff.parse import load_factory, resolve_factory_dir
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class _Parser(argparse.ArgumentParser):
|
|
22
|
+
def __init__(self, *args: Any, **kwargs: Any) -> None:
|
|
23
|
+
super().__init__(*args, **({"allow_abbrev": False, "suggest_on_error": True} | kwargs))
|
|
24
|
+
|
|
25
|
+
def error(self, message: str) -> NoReturn:
|
|
26
|
+
raise InputError(message)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _console() -> Console:
|
|
30
|
+
no_color = bool(os.environ.get("NO_COLOR")) or os.environ.get("TERM") == "dumb" or not sys.stdout.isatty()
|
|
31
|
+
return Console(no_color=no_color, highlight=False, soft_wrap=True)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _emit_json(payload: object) -> None:
|
|
35
|
+
sys.stdout.buffer.write(terminal_json(payload))
|
|
36
|
+
sys.stdout.buffer.flush()
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _stderr_err(message: str, *, hint: str = "") -> None:
|
|
40
|
+
suffix = f" (hint: {printable(hint)})" if hint else ""
|
|
41
|
+
sys.stderr.write(f"ff: {printable(message)}{suffix}\n")
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def build_parser() -> _Parser:
|
|
45
|
+
"""Build the root and subcommand `argparse` parser tree."""
|
|
46
|
+
sh = _Parser(add_help=False)
|
|
47
|
+
root = _Parser(prog="ff", description="Factory Framework: Markdown intents & specs, checks, and proofs.")
|
|
48
|
+
root.add_argument("--version", action="version", version=f"ff {__version__}")
|
|
49
|
+
for p, pfx in ((sh, "sub_"), (root, "")):
|
|
50
|
+
p.add_argument("--factory", dest=f"{pfx}factory", default="", metavar="PATH", help="Factory dir.")
|
|
51
|
+
p.add_argument("--json", dest=f"{pfx}json" if pfx else "as_json", action="store_true", help="Compact JSON.")
|
|
52
|
+
p.add_argument("-v", "--verbose", dest=f"{pfx}verbose", action="store_true", help="Progress on stderr.")
|
|
53
|
+
sub = root.add_subparsers(dest="command", title="commands", metavar="COMMAND", required=True)
|
|
54
|
+
h1 = {"init": "Initialize factory/.", "lint": "Validate contract & proofs.", "run": "Run checks & write proofs."}
|
|
55
|
+
h2 = {"verify": "Lint, run, gate, check proofs.", "status": "Offline gate & proof status.", "ls": "List items."}
|
|
56
|
+
h3 = {"show": "Inspect item.", "export": "Export proof reports.", "schema": "Emit JSON Schemas."}
|
|
57
|
+
h4 = {"mcp": "Run read-only MCP server.", "hook": "Print hook/CI snippets.", "skill": "Install/verify /ff skill."}
|
|
58
|
+
subs = {n: sub.add_parser(n, parents=[sh], help=h) for n, h in (h1 | h2 | h3 | h4).items()}
|
|
59
|
+
|
|
60
|
+
def _add(tgt: Sequence[str], *a: Any, **kw: Any) -> None:
|
|
61
|
+
for n in tgt:
|
|
62
|
+
subs[n].add_argument(*a, **kw)
|
|
63
|
+
|
|
64
|
+
_add(("lint", "verify"), "--base", default="", metavar="REF", help="Enforce anti-weakening rules against REF.")
|
|
65
|
+
_add(("lint", "verify"), "--strict", action="store_true", help="Promote warnings to errors.")
|
|
66
|
+
_add(("run", "verify"), "-j", "--jobs", type=int, default=0, metavar="N", help="Max parallel checks.")
|
|
67
|
+
_add(("run", "ls", "export"), "--domain", default="", metavar="DOMAIN", help="Filter to DOMAIN.")
|
|
68
|
+
subs["init"].add_argument("path", nargs="?", default=".", metavar="DIR", help="Project root.")
|
|
69
|
+
subs["init"].add_argument("--example", action="store_true", help="Scaffold 'hello' domain.")
|
|
70
|
+
subs["init"].add_argument("--pytest", action="store_true", help="Add pytest conftest.py + test_hello.py.")
|
|
71
|
+
subs["run"].add_argument("checks", nargs="*", metavar="CHECK", help="Optional check IDs.")
|
|
72
|
+
subs["run"].add_argument("--no-write", action="store_true", help="Run without writing proofs.")
|
|
73
|
+
subs["ls"].add_argument("--kind", choices=("intent", "spec", "check", "change"), default="", help="Item kind.")
|
|
74
|
+
subs["ls"].add_argument("--status", default="", metavar="STATUS", help="Status filter.")
|
|
75
|
+
subs["ls"].add_argument("--tree", action="store_true", help="Render tree in TTY.")
|
|
76
|
+
subs["ls"].add_argument("-n", "--limit", type=int, default=0, metavar="N", help="Max rows.")
|
|
77
|
+
subs["show"].add_argument("id", metavar="ID")
|
|
78
|
+
subs["export"].add_argument("-f", "--format", dest="fmt", choices=("html", "csv", "md", "jsonl"), default="md")
|
|
79
|
+
subs["export"].add_argument("--summary", default="", metavar="FILE", help="Executive summary Markdown.")
|
|
80
|
+
subs["export"].add_argument("-o", "--output", default="", metavar="FILE", help="Output file.")
|
|
81
|
+
subs["schema"].add_argument("kind", nargs="?", default="")
|
|
82
|
+
subs["mcp"].add_argument("--transport", choices=("stdio", "http"), default="stdio", help="Transport.")
|
|
83
|
+
subs["mcp"].add_argument("--port", type=int, default=8765, help="HTTP port.")
|
|
84
|
+
subs["hook"].add_argument("parts", nargs="+", metavar="TGT")
|
|
85
|
+
p_in = subs["skill"].add_subparsers(dest="skill_cmd", required=True).add_parser("install", parents=[sh])
|
|
86
|
+
p_in.add_argument("dir", nargs="?", default=".agents/skills", metavar="DIR", help="Skills directory.")
|
|
87
|
+
p_in.add_argument("--check", action="store_true", help="Verify skill matches packaged files.")
|
|
88
|
+
return root
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _report_run_failures(summary: runner.RunSummary, missing_errs: Sequence[str] = ()) -> None:
|
|
92
|
+
for cid, out in summary.outcomes.items():
|
|
93
|
+
if out.record.status != "pass":
|
|
94
|
+
_stderr_err(f"{cid} {out.record.status}: {out.record.summary} (log: {out.log_path})")
|
|
95
|
+
if summary.workspace_polluted:
|
|
96
|
+
_stderr_err(f"checks polluted workspace: {', '.join(summary.polluted_paths)}")
|
|
97
|
+
for merr in missing_errs:
|
|
98
|
+
_stderr_err(merr)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _select_checks(factory: Any, names: Sequence[str], domain: str) -> tuple[list[str], bool]:
|
|
102
|
+
cks = factory.checks
|
|
103
|
+
if domain and domain not in factory.domains:
|
|
104
|
+
raise InputError(f"unknown domain '{domain}'")
|
|
105
|
+
if unknown := next((c for c in names if c not in cks), None):
|
|
106
|
+
raise InputError(f"unknown check '{unknown}'")
|
|
107
|
+
if not names and not domain:
|
|
108
|
+
return sorted(cks), True
|
|
109
|
+
return [c for c in sorted(cks) if (not names or c in names) and domain in ("", cks[c].domain)], False
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def _print_tbl(con: Console, rows: Sequence[dict[str, Any]]) -> None:
|
|
113
|
+
tbl = Table("ID", "Kind", "Domain", "Status", "Title", box=None)
|
|
114
|
+
for r in rows:
|
|
115
|
+
tbl.add_row(r["id"], r["kind"], r["domain"], r["status"], r["title"])
|
|
116
|
+
con.print(tbl)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _run_and_build(
|
|
120
|
+
fac: Any, check_ids: Sequence[str] | None, jobs: int
|
|
121
|
+
) -> tuple[Any, dict[str, Any], dict[str, Any], list[str]]:
|
|
122
|
+
summary = runner.run_checks(fac, check_ids, jobs=jobs)
|
|
123
|
+
recs = {cid: out.record for cid, out in summary.outcomes.items()}
|
|
124
|
+
prf_d, ran = proofs.build_proofs(fac, recs), set(fac.checks if check_ids is None else check_ids)
|
|
125
|
+
m_errs: list[str] = []
|
|
126
|
+
for d_doc in prf_d.values():
|
|
127
|
+
for sid, sv in sorted(d_doc["specs"].items()):
|
|
128
|
+
cks = fac.specs[sid].checks
|
|
129
|
+
if cks and set(cks) <= ran and all(recs[c].status != "error" for c in cks if c in recs):
|
|
130
|
+
msg = f"{sid} error: missing required metric '{{}}'"
|
|
131
|
+
m_errs.extend(msg.format(mn) for mn, m in sorted(sv["metrics"].items()) if m["value"] is None)
|
|
132
|
+
return summary, recs, prf_d, m_errs
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _out_err(err: Any) -> None:
|
|
136
|
+
_stderr_err(f"{err.code}: {err.message}", hint=err.hint)
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _cmd_no_factory(ns: argparse.Namespace, con: Console, f_arg: str, as_json: bool) -> int | None:
|
|
140
|
+
cmd = ns.command
|
|
141
|
+
if cmd == "init":
|
|
142
|
+
res = scaffold.init_factory(Path(ns.path), example=ns.example, pytest_plugin=ns.pytest)
|
|
143
|
+
msg = f"Initialized {res['factory']} ({len(res['created'])} files)"
|
|
144
|
+
_emit_json(res) if as_json else con.print(msg, markup=False)
|
|
145
|
+
return 0
|
|
146
|
+
if cmd == "schema":
|
|
147
|
+
doc = schemas.schema_for(ns.kind) if ns.kind else schemas.all_schemas()
|
|
148
|
+
_emit_json(doc) if as_json else sys.stdout.write(format_json(doc))
|
|
149
|
+
return 0
|
|
150
|
+
if cmd == "hook":
|
|
151
|
+
pts = list(ns.parts)
|
|
152
|
+
tgt = pts[1] if len(pts) == 2 and pts[0] == "print" else (pts[0] if len(pts) == 1 else "")
|
|
153
|
+
if not tgt:
|
|
154
|
+
raise InputError("usage: ff hook [print] {pre-commit,lefthook,github-actions}")
|
|
155
|
+
snip = scaffold.render_hook(tgt)
|
|
156
|
+
_emit_json({"target": tgt, "snippet": snip}) if as_json else sys.stdout.write(snip)
|
|
157
|
+
return 0
|
|
158
|
+
if cmd == "skill":
|
|
159
|
+
res = scaffold.install_skill(Path(ns.dir), check=ns.check)
|
|
160
|
+
if as_json:
|
|
161
|
+
_emit_json(res)
|
|
162
|
+
elif not res["ok"]:
|
|
163
|
+
_stderr_err(f"skill drift in {res['target']}: {', '.join(res['differences'])}", hint="ff skill install")
|
|
164
|
+
else:
|
|
165
|
+
con.print(f"Skill OK at {res['target']}", markup=False)
|
|
166
|
+
return 0 if res["ok"] else 1
|
|
167
|
+
if cmd == "mcp":
|
|
168
|
+
try:
|
|
169
|
+
from ff import mcp as mcp_mod
|
|
170
|
+
except ModuleNotFoundError as exc:
|
|
171
|
+
raise Error("MCP support requires factory-framework[mcp] (`uv add 'factory-framework[mcp]'`)") from exc
|
|
172
|
+
mcp_mod.serve(f_arg, transport=ns.transport, port=ns.port)
|
|
173
|
+
return 0
|
|
174
|
+
return None
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def run(argv: Sequence[str] | None = None) -> int:
|
|
178
|
+
"""Execute one CLI command and return exit code (`0` ok, `1` failure, `2` input error, `130` interrupted)."""
|
|
179
|
+
try:
|
|
180
|
+
ns = build_parser().parse_args(list(sys.argv[1:] if argv is None else argv))
|
|
181
|
+
f_arg = getattr(ns, "sub_factory", "") or ns.factory
|
|
182
|
+
as_json = bool(getattr(ns, "sub_json", False) or ns.as_json)
|
|
183
|
+
verbose = bool(getattr(ns, "sub_verbose", False) or ns.verbose)
|
|
184
|
+
con, cmd = _console(), ns.command
|
|
185
|
+
if (rc := _cmd_no_factory(ns, con, f_arg, as_json)) is not None:
|
|
186
|
+
return rc
|
|
187
|
+
|
|
188
|
+
fac = load_factory(fdir := resolve_factory_dir(f_arg or None))
|
|
189
|
+
if cmd == "lint":
|
|
190
|
+
diags = lint.lint_factory(fac, base_ref=ns.base, strict=ns.strict)
|
|
191
|
+
errs = [d for d in diags if d.severity == "error"]
|
|
192
|
+
if as_json:
|
|
193
|
+
_emit_json({"ok": not errs, "errors": len(errs), "diagnostics": [d.to_dict() for d in diags]})
|
|
194
|
+
else:
|
|
195
|
+
for d in diags:
|
|
196
|
+
loc = f"{d.path}:{d.line}" if d.line else (d.path or "-")
|
|
197
|
+
con.print(f"[{d.severity.upper()}] {d.code} {loc}: {d.message}", markup=False)
|
|
198
|
+
_out_err(errs[0]) if errs else con.print(f"Lint OK ({len(diags)} warnings/infos)", markup=False)
|
|
199
|
+
return 1 if errs else 0
|
|
200
|
+
if cmd == "status":
|
|
201
|
+
data = query.status_payload(fac)
|
|
202
|
+
if as_json:
|
|
203
|
+
_emit_json(data)
|
|
204
|
+
else:
|
|
205
|
+
p_t = "fresh" if data["proofs_fresh"] else f"stale ({len(data['drifted_files'])} drifted)"
|
|
206
|
+
g_t = "PASSED" if data["gate"]["passed"] else "FAILED"
|
|
207
|
+
con.print(f"Factory: {data['name']} | Proofs: {p_t} | Gate: {g_t}", markup=False)
|
|
208
|
+
ic, sc, cc = data["counts"]["intents"], data["counts"]["specs"], data["counts"]["checks"]
|
|
209
|
+
st_1 = f"Intents: {ic.get('PROVEN', 0)}/{ic['total']} proven | Specs: {sc.get('PROVEN', 0)}/{sc['total']}"
|
|
210
|
+
con.print(f"{st_1} proven | Checks: {cc.get('PASS', 0)}/{cc['total']} passing", markup=False)
|
|
211
|
+
if data["attention"]:
|
|
212
|
+
_print_tbl(con, data["attention"])
|
|
213
|
+
return 0
|
|
214
|
+
if cmd == "ls":
|
|
215
|
+
if ns.limit < 0:
|
|
216
|
+
raise InputError("--limit must be >= 0")
|
|
217
|
+
data = query.list_payload(fac, kind=ns.kind, domain=ns.domain, status=ns.status, limit=ns.limit)
|
|
218
|
+
if as_json:
|
|
219
|
+
_emit_json(data)
|
|
220
|
+
elif ns.tree:
|
|
221
|
+
shown: set[str] = set()
|
|
222
|
+
for iid, it in sorted(x for x in fac.intents.items() if ns.domain in ("", x[1].domain)):
|
|
223
|
+
shown.update(it.specs)
|
|
224
|
+
lns = [f"{iid} ({it.title})"]
|
|
225
|
+
for sid in it.specs:
|
|
226
|
+
c_lns = [f" └─ {c}" for c in fac.specs[sid].checks]
|
|
227
|
+
lns.extend([f" └─ {sid} ({fac.specs[sid].title})", *c_lns])
|
|
228
|
+
con.print("\n".join(lns), markup=False)
|
|
229
|
+
for sid, sp in sorted(fac.specs.items()):
|
|
230
|
+
if sid not in shown and ns.domain in ("", sp.domain):
|
|
231
|
+
con.print("\n".join([f"{sid} ({sp.title})", *(f" └─ {c}" for c in sp.checks)]), markup=False)
|
|
232
|
+
else:
|
|
233
|
+
_print_tbl(con, data["items"])
|
|
234
|
+
return 0
|
|
235
|
+
if cmd == "show":
|
|
236
|
+
data = query.show_payload(fac, ns.id)
|
|
237
|
+
if as_json:
|
|
238
|
+
_emit_json(data)
|
|
239
|
+
else:
|
|
240
|
+
con.print(f"{data['id']} [{data['kind']}] — {data.get('status') or data.get('state')}", markup=False)
|
|
241
|
+
for k, v in data.items():
|
|
242
|
+
if k not in {"id", "kind"} and v not in ("", [], {}):
|
|
243
|
+
con.print(f" {k}: {v}", markup=False)
|
|
244
|
+
return 0
|
|
245
|
+
if cmd == "export":
|
|
246
|
+
sp = Path(ns.summary) if ns.summary else None
|
|
247
|
+
raw = export.export_proofs(fac, fmt=ns.fmt, domain=ns.domain, summary_path=sp)
|
|
248
|
+
if not ns.output:
|
|
249
|
+
sys.stdout.buffer.write(raw)
|
|
250
|
+
sys.stdout.buffer.flush()
|
|
251
|
+
else:
|
|
252
|
+
atomic_write(Path(ns.output), raw)
|
|
253
|
+
if as_json:
|
|
254
|
+
_emit_json({"ok": True, "format": ns.fmt, "output": ns.output, "bytes": len(raw)})
|
|
255
|
+
return 0
|
|
256
|
+
if ns.jobs < 0:
|
|
257
|
+
raise InputError("--jobs must be >= 0")
|
|
258
|
+
if cmd == "run":
|
|
259
|
+
if errs := [d for d in fac.diagnostics if d.severity == "error"]:
|
|
260
|
+
_emit_json({"ok": False, "diagnostics": [d.to_dict() for d in errs]}) if as_json else _out_err(errs[0])
|
|
261
|
+
return 1
|
|
262
|
+
cids, is_full = _select_checks(fac, ns.checks, ns.domain)
|
|
263
|
+
if verbose:
|
|
264
|
+
_stderr_err(f"running {len(cids)} check(s)")
|
|
265
|
+
summ, _, prf_d, m_errs = _run_and_build(fac, cids, ns.jobs)
|
|
266
|
+
wrote = is_full and not ns.no_write and not summ.workspace_polluted
|
|
267
|
+
if wrote:
|
|
268
|
+
proofs.write_proofs(fdir, prf_d)
|
|
269
|
+
run_ok = summ.all_passed and not m_errs
|
|
270
|
+
if as_json:
|
|
271
|
+
cks = {
|
|
272
|
+
c: o.record.to_record_dict() | {"exit_code": o.exit_code, "log": o.log_path}
|
|
273
|
+
for c, o in summ.outcomes.items()
|
|
274
|
+
}
|
|
275
|
+
h = {"all_passed": run_ok, "proofs_written": wrote, "missing_metrics": m_errs}
|
|
276
|
+
pl = {"workspace_polluted": summ.workspace_polluted, "polluted_paths": list(summ.polluted_paths)}
|
|
277
|
+
_emit_json(h | pl | {"checks": cks})
|
|
278
|
+
else:
|
|
279
|
+
for cid, out in summ.outcomes.items():
|
|
280
|
+
con.print(f"[{out.record.status.upper()}] {cid}: {out.record.summary}", markup=False)
|
|
281
|
+
_report_run_failures(summ, m_errs)
|
|
282
|
+
return 0 if run_ok else 1
|
|
283
|
+
|
|
284
|
+
diags = lint.lint_factory(fac, strict=ns.strict, check_proofs=False)
|
|
285
|
+
l_errs = [d for d in diags if d.severity == "error"]
|
|
286
|
+
if l_errs:
|
|
287
|
+
summ, exp_p, m_errs = runner.RunSummary({}, False, ()), proofs.build_proofs(fac, {}), []
|
|
288
|
+
else:
|
|
289
|
+
summ, _, exp_p, m_errs = _run_and_build(fac, None, ns.jobs)
|
|
290
|
+
gate, mismatches = proofs.evaluate_gate(fac, exp_p), [] if l_errs else proofs.verify_proofs_match(fdir, exp_p)
|
|
291
|
+
if ns.base and not l_errs:
|
|
292
|
+
bs = lint.evaluate_base_rules(fac, ns.base, current_proofs=exp_p)
|
|
293
|
+
diags.extend(replace(d, severity="error") if (ns.strict and d.severity == "warning") else d for d in bs)
|
|
294
|
+
l_errs = [d for d in diags if d.severity == "error"]
|
|
295
|
+
all_ok = summ.all_passed and not m_errs
|
|
296
|
+
ok = not l_errs and all_ok and gate["passed"] and not mismatches
|
|
297
|
+
if as_json:
|
|
298
|
+
h = {"ok": ok, "all_passed": all_ok, "workspace_polluted": summ.workspace_polluted}
|
|
299
|
+
_emit_json(h | {"gate": gate, "mismatches": mismatches, "diagnostics": [d.to_dict() for d in diags]})
|
|
300
|
+
elif ok:
|
|
301
|
+
pn = sum(1 for d in exp_p.values() for s in d["specs"].values() if s["status"] == "PROVEN")
|
|
302
|
+
con.print(f"Verify OK — {pn}/{len(fac.specs)} specs proven in {len(fac.domains)} domain(s)", markup=False)
|
|
303
|
+
else:
|
|
304
|
+
if l_errs:
|
|
305
|
+
_out_err(l_errs[0])
|
|
306
|
+
_report_run_failures(summ, m_errs)
|
|
307
|
+
if not gate["passed"]:
|
|
308
|
+
b0 = gate["blockers"][0]
|
|
309
|
+
_stderr_err(f"gate failed on {len(gate['blockers'])} item(s): {b0['id']}={b0['status']}")
|
|
310
|
+
if mismatches:
|
|
311
|
+
_stderr_err(mismatches[0])
|
|
312
|
+
return 0 if ok else 1
|
|
313
|
+
except SystemExit as exc:
|
|
314
|
+
return int(exc.code) if isinstance(exc.code, int) else 0
|
|
315
|
+
except Error as exc:
|
|
316
|
+
_stderr_err(str(exc))
|
|
317
|
+
return 2 if isinstance(exc, InputError) else 1
|
|
318
|
+
except KeyboardInterrupt:
|
|
319
|
+
_stderr_err("interrupted")
|
|
320
|
+
return 130
|