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.
@@ -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
+ [![CI](https://github.com/fmind/factory-framework/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fmind/factory-framework/actions/workflows/ci.yml) [![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-174EA6)](pyproject.toml) [![License: MIT](https://img.shields.io/badge/license-MIT-174EA6)](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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.13.7
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ ff = ff:main
3
+
@@ -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
@@ -0,0 +1,7 @@
1
+ """Module entry point for `python -m ff`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from ff.cli import run
6
+
7
+ raise SystemExit(run())
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