fastpluggy-cli 0.1.2__tar.gz → 0.1.6__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.
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/PKG-INFO +6 -5
- fastpluggy_cli-0.1.6/README.md +304 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/cli.py +118 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/commands/__init__.py +1 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/commands/dev_server.py +221 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/commands/new.py +127 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/commands/validate.py +183 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/fixers.py +139 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold.py +116 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/README.md.j2 +17 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/cli.py.j2 +10 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/config.py.j2 +12 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/gitignore.j2 +41 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/gitlab-ci.yml.j2 +22 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/index.html.j2 +9 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/models.py.j2 +8 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/plugin.py.j2 +33 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli/scaffold_templates/plugin/pyproject.toml.j2 +20 -12
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/router.py.j2 +31 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/test_plugin.py.j2 +12 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/project/env.j2 +3 -0
- fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/project/pyproject.toml.j2 +19 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/PKG-INFO +6 -5
- fastpluggy_cli-0.1.6/fastpluggy_cli.egg-info/SOURCES.txt +38 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/requires.txt +4 -4
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/pyproject.toml +8 -7
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_cli.py +5 -5
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_fix.py +114 -7
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_new_plugin.py +209 -50
- fastpluggy_cli-0.1.6/tests/test_scaffold_e2e.py +149 -0
- fastpluggy_cli-0.1.6/tests/test_start_dev_server.py +254 -0
- fastpluggy_cli-0.1.2/README.md +0 -199
- fastpluggy_cli-0.1.2/fastpluggy_cli/cli.py +0 -1023
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/config.py.j2 +0 -22
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/index.html.j2 +0 -10
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/models/__init__.py.j2 +0 -1
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/models/context.py.j2 +0 -37
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/models/report.py.j2 +0 -27
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/models/scheduled.py.j2 +0 -38
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/plugin.py.j2 +0 -49
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/router.py.j2 +0 -37
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/runner.py.j2 +0 -171
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/tasks/__init__.py.j2 +0 -1
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/tasks/maintenance.py.j2 +0 -50
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/tasks/plugin_update.py.j2 +0 -53
- fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/tasks/scheduler.py.j2 +0 -73
- fastpluggy_cli-0.1.2/fastpluggy_cli.egg-info/SOURCES.txt +0 -33
- fastpluggy_cli-0.1.2/tests/test_cli_commands.py +0 -65
- fastpluggy_cli-0.1.2/tests/test_start_dev_server.py +0 -98
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/MANIFEST.in +0 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli/__init__.py +0 -0
- {fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates → fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/project}/main.py.j2 +0 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/dependency_links.txt +0 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/entry_points.txt +0 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/top_level.txt +0 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/setup.cfg +0 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_plugin_commands.py +0 -0
- {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_validate.py +0 -0
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: fastpluggy-cli
|
|
3
|
-
Version: 0.1.
|
|
3
|
+
Version: 0.1.6
|
|
4
4
|
Summary: A CLI tool to scaffold FastPluggy projects
|
|
5
5
|
Author: Jerome Vaillant
|
|
6
6
|
License-Expression: MIT
|
|
7
|
-
Requires-
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Requires-Dist: click==8.5.1
|
|
8
9
|
Requires-Dist: jinja2
|
|
9
|
-
Requires-Dist: requests
|
|
10
10
|
Requires-Dist: questionary
|
|
11
11
|
Requires-Dist: uvicorn[standard]
|
|
12
12
|
Requires-Dist: fastpluggy>=0.4.15
|
|
@@ -14,7 +14,8 @@ Requires-Dist: fastapi
|
|
|
14
14
|
Provides-Extra: e2e
|
|
15
15
|
Requires-Dist: playwright; extra == "e2e"
|
|
16
16
|
Provides-Extra: dev
|
|
17
|
-
Requires-Dist: pytest==9.
|
|
17
|
+
Requires-Dist: pytest==9.2.0; extra == "dev"
|
|
18
18
|
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
|
|
19
|
+
Requires-Dist: httpx; extra == "dev"
|
|
19
20
|
Provides-Extra: ssl
|
|
20
|
-
Requires-Dist: cryptography==
|
|
21
|
+
Requires-Dist: cryptography==50.0.2; extra == "ssl"
|
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
# FastPluggy CLI
|
|
2
|
+
|
|
3
|
+
A CLI tool to scaffold projects, plugins, and auto-fix compliance issues for the [FastPluggy](https://github.com/jeromevaillant/fastpluggy) framework.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
cd fastpluggy-cli
|
|
9
|
+
pip install -e .
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Available Commands
|
|
13
|
+
|
|
14
|
+
### Create a new project
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
fastpluggy new [my_app]
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Generates a FastPluggy project skeleton in the `my_app` directory. If no name is provided, the CLI prompts interactively.
|
|
21
|
+
|
|
22
|
+
The generated project holds three files:
|
|
23
|
+
- `main.py` — a FastAPI app that starts FastPluggy (plugins are discovered through entry points)
|
|
24
|
+
- `.env` — `PORT` and a commented `DATABASE_URL`
|
|
25
|
+
- `pyproject.toml` — depends on `fastapi`, `uvicorn` and `fastpluggy`
|
|
26
|
+
|
|
27
|
+
### Create a new plugin
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
fastpluggy new-plugin [plugin_name]
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Scaffolds an installable plugin that passes `fastpluggy validate`:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
my_plugin/
|
|
37
|
+
├── pyproject.toml # package fastpluggy_plugin.my_plugin mapped onto src/
|
|
38
|
+
├── src/
|
|
39
|
+
│ ├── __init__.py
|
|
40
|
+
│ ├── plugin.py # the FastPluggyBaseModule class (entry point)
|
|
41
|
+
│ ├── router.py # one page, served under /plugin-pkg/my_plugin/
|
|
42
|
+
│ └── templates/index.html.j2
|
|
43
|
+
├── tests/test_plugin.py
|
|
44
|
+
├── e2e/routes.json # pages to screenshot in CI
|
|
45
|
+
├── docs/screenshots/e2e/
|
|
46
|
+
├── .gitlab-ci.yml
|
|
47
|
+
├── .gitignore
|
|
48
|
+
└── README.md
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Options:
|
|
52
|
+
- `--label`, `--icon` — menu label and icon
|
|
53
|
+
- `--menu-type main|admin|no` — menu the plugin appears in (`no` hides it)
|
|
54
|
+
- `--with-config` — `src/config.py`, settings editable in the admin UI and stored in the database
|
|
55
|
+
- `--with-model` — `src/models.py` skeleton
|
|
56
|
+
- `--with-cli-commands` — `src/cli.py`, a `fastpluggy <plugin-name>` command group
|
|
57
|
+
- `--output-dir`, `--no-interactive`, `--dry-run`
|
|
58
|
+
|
|
59
|
+
Then install it and start the server:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pip install -e "./my_plugin[dev]"
|
|
63
|
+
fastpluggy start-dev-server
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The generated page, as rendered by the CI of a freshly scaffolded plugin:
|
|
67
|
+
|
|
68
|
+

|
|
69
|
+
|
|
70
|
+
### Validate a plugin
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
fastpluggy validate [plugin_dir] [--json]
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Checks a plugin directory against the compliance rules of core (docs, README, tests, entry point, CI file, e2e routes). Exits with 0 when every check passes, 1 otherwise. A plugin created by `new-plugin` passes as is.
|
|
77
|
+
|
|
78
|
+
### Fix plugin compliance issues
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
fastpluggy fix-plugin [plugin_dir]
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Runs compliance checks and interactively lets you select which issues to fix. Shows each failing rule with a description and lets you pick from a checkbox list.
|
|
85
|
+
|
|
86
|
+
Options:
|
|
87
|
+
- `--all` — apply all fixes without prompting
|
|
88
|
+
- `--rule R4 --rule R6` — only fix specific rules
|
|
89
|
+
- `--dry-run` — preview changes without writing files
|
|
90
|
+
|
|
91
|
+
Auto-fixable rules:
|
|
92
|
+
|
|
93
|
+
| Rule | What it fixes |
|
|
94
|
+
|------|---------------|
|
|
95
|
+
| R1 | Create `docs/` directory |
|
|
96
|
+
| R2 | Create `README.md` |
|
|
97
|
+
| R3 | Add `[e2e]` optional deps to `pyproject.toml` |
|
|
98
|
+
| R4 | Create `e2e/` directory with a `routes.json` skeleton |
|
|
99
|
+
| R6 | Create `docs/screenshots/e2e/` with `.gitkeep` |
|
|
100
|
+
| R9 | Create `tests/` with stub test |
|
|
101
|
+
| R10 | Create or update `.gitignore` |
|
|
102
|
+
| R12 | Create `e2e/routes.json` skeleton |
|
|
103
|
+
|
|
104
|
+
Example:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
# Interactive — pick which fixes to apply
|
|
108
|
+
fastpluggy fix-plugin plugins/my_plugin
|
|
109
|
+
|
|
110
|
+
# Fix everything at once
|
|
111
|
+
fastpluggy fix-plugin --all plugins/my_plugin
|
|
112
|
+
|
|
113
|
+
# Preview only
|
|
114
|
+
fastpluggy fix-plugin --dry-run .
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Start dev server
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
fastpluggy start-dev-server [--port PORT] [--host HOST] [--reload] [--verbose] [--ssl]
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Auto-discovers all installed plugins via entry points. Defaults `DATABASE_URL` to SQLite if not set.
|
|
124
|
+
|
|
125
|
+
Despite the name, this is also the production entrypoint for apps that run FastPluggy
|
|
126
|
+
as a host process, so it can express reverse-proxy settings:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
fastpluggy start-dev-server --host 0.0.0.0 --port 8000 \
|
|
130
|
+
--proxy-headers --forwarded-allow-ips 172.18.0.0/16
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`--proxy-headers / --no-proxy-headers` controls whether `X-Forwarded-*` is honoured, so
|
|
134
|
+
that `request.url_for()` resolves against the public vhost rather than the socket — which
|
|
135
|
+
is what makes an OIDC `redirect_uri` come out right behind a proxy. `--forwarded-allow-ips`
|
|
136
|
+
controls *which* peers are trusted to set those headers.
|
|
137
|
+
|
|
138
|
+
uvicorn already honours proxy headers by default, but only from `127.0.0.1`; when the proxy
|
|
139
|
+
is a different container or host, they are dropped silently. Setting the allow-list is
|
|
140
|
+
therefore the part that actually fixes the URLs. Leave both flags off and nothing changes:
|
|
141
|
+
uvicorn keeps its own defaults, including its `FORWARDED_ALLOW_IPS` environment fallback.
|
|
142
|
+
|
|
143
|
+
Do not reach for `--forwarded-allow-ips '*'` unless the port is reachable *only* by the
|
|
144
|
+
proxy. A wildcard lets any client that can open a connection forge `X-Forwarded-*` and steer
|
|
145
|
+
every URL the app generates; the CLI warns when you use one.
|
|
146
|
+
|
|
147
|
+
#### ⚠ The CLI is not in the FastPluggy base image
|
|
148
|
+
|
|
149
|
+
`fast_pluggy/docker/Dockerfile` installs core (from repo source) plus `uvicorn[standard]`
|
|
150
|
+
and nothing else, and `fastpluggy-cli` is **not** a dependency of core's `pyproject.toml`.
|
|
151
|
+
Core never pulls it in.
|
|
152
|
+
|
|
153
|
+
So an app whose container boots via `fastpluggy start-dev-server` **must list
|
|
154
|
+
`fastpluggy-cli` in its own dependency manifest**. Leave it out and the image builds fine,
|
|
155
|
+
then the container's `CMD` dies at start with `fastpluggy: not found`.
|
|
156
|
+
|
|
157
|
+
Such an app pins the CLI in its `pyproject.toml` alongside core,
|
|
158
|
+
|
|
159
|
+
```toml
|
|
160
|
+
dependencies = [
|
|
161
|
+
"FastPluggy>=0.4.37,!=0.4.32",
|
|
162
|
+
"fastpluggy-cli>=0.1.1", # `fastpluggy start-dev-server` / `tasks-worker`
|
|
163
|
+
...
|
|
164
|
+
]
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
and only then can its Dockerfile say
|
|
168
|
+
|
|
169
|
+
```dockerfile
|
|
170
|
+
CMD ["sh", "-c", "fastpluggy tasks-worker start --beat & exec fastpluggy start-dev-server --host 0.0.0.0 --port 8000"]
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`--verbose` also turns on the debug logs of core and of the plugins (it sets `LOGURU_LEVEL=DEBUG`); `--ssl` serves HTTPS with a generated self-signed certificate.
|
|
174
|
+
|
|
175
|
+
### Show help
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
fastpluggy help # same output as fastpluggy --help
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Dependencies
|
|
182
|
+
|
|
183
|
+
- Python 3.11+
|
|
184
|
+
- fastpluggy, fastapi, uvicorn
|
|
185
|
+
- click, questionary, jinja2
|
|
186
|
+
- cryptography (optional, for `start-dev-server --ssl`)
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
pip install -e .
|
|
190
|
+
# For `start-dev-server --ssl`
|
|
191
|
+
pip install -e ".[ssl]"
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Plugin CLI Extensions
|
|
195
|
+
|
|
196
|
+
Plugins can inject their own CLI commands under the `fastpluggy` group. Plugin commands appear in a separate **Plugin Commands** section in `fastpluggy --help`.
|
|
197
|
+
|
|
198
|
+
### How it works
|
|
199
|
+
|
|
200
|
+
At startup, the CLI discovers entry points registered under the `fastpluggy.cli` group and registers each as a subcommand. Each entry point **must** be a `click.Group` (not a flat command) to avoid name collisions.
|
|
201
|
+
|
|
202
|
+
### Registering a plugin command group
|
|
203
|
+
|
|
204
|
+
In your plugin's `pyproject.toml`:
|
|
205
|
+
|
|
206
|
+
```toml
|
|
207
|
+
[project.entry-points."fastpluggy.cli"]
|
|
208
|
+
my-plugin = "my_package.cli:my_group"
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
In your plugin's `cli.py`:
|
|
212
|
+
|
|
213
|
+
```python
|
|
214
|
+
import click
|
|
215
|
+
|
|
216
|
+
@click.group("my-plugin")
|
|
217
|
+
def my_group():
|
|
218
|
+
"""My plugin commands."""
|
|
219
|
+
pass
|
|
220
|
+
|
|
221
|
+
@my_group.command()
|
|
222
|
+
def do_something():
|
|
223
|
+
"""Run my plugin task."""
|
|
224
|
+
click.echo("Done!")
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
This gives the user `fastpluggy my-plugin do-something`.
|
|
228
|
+
|
|
229
|
+
### Contract
|
|
230
|
+
|
|
231
|
+
| Item | Requirement |
|
|
232
|
+
|------|-------------|
|
|
233
|
+
| Entry point group | `fastpluggy.cli` |
|
|
234
|
+
| Entry point value | A `click.Group` instance (or zero-arg callable returning one) |
|
|
235
|
+
| Naming convention | Use the plugin name with hyphens (e.g. `auth-user`, `tasks-worker`) |
|
|
236
|
+
| Collision handling | First registered wins; conflicts produce a stderr warning |
|
|
237
|
+
| Import errors | Swallowed gracefully with a stderr warning — the CLI never crashes |
|
|
238
|
+
|
|
239
|
+
### Help output
|
|
240
|
+
|
|
241
|
+
```
|
|
242
|
+
$ fastpluggy --help
|
|
243
|
+
|
|
244
|
+
Core Commands:
|
|
245
|
+
fix-plugin Interactive auto-fix for failing compliance checks
|
|
246
|
+
help Show available commands
|
|
247
|
+
new Create a new FastPluggy project
|
|
248
|
+
new-plugin Scaffold a standalone, installable FastPluggy plugin
|
|
249
|
+
start-dev-server Start a FastPluggy dev server with auto-discovered plugins
|
|
250
|
+
validate Validate a plugin directory against compliance rules
|
|
251
|
+
|
|
252
|
+
Plugin Commands:
|
|
253
|
+
auth-user Auth user management commands
|
|
254
|
+
tasks-worker Background task worker commands
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
## Migration: `--start-worker` removed
|
|
258
|
+
|
|
259
|
+
The `--start-worker` flag on `fastpluggy start-dev-server` has been **removed**.
|
|
260
|
+
Background workers are now started via the plugin CLI extension:
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
# Before (removed)
|
|
264
|
+
fastpluggy start-dev-server --start-worker
|
|
265
|
+
|
|
266
|
+
# After
|
|
267
|
+
fastpluggy tasks-worker start
|
|
268
|
+
# Or with a custom worker count:
|
|
269
|
+
fastpluggy tasks-worker start -n 4
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
The `tasks-worker` group is auto-discovered from the `fastpluggy-tasks-worker`
|
|
273
|
+
package when installed.
|
|
274
|
+
|
|
275
|
+
## Tests
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
# Install dev dependencies
|
|
279
|
+
pip install -e ".[dev]"
|
|
280
|
+
|
|
281
|
+
# Run tests
|
|
282
|
+
pytest
|
|
283
|
+
|
|
284
|
+
# Run tests with coverage
|
|
285
|
+
pytest --cov=fastpluggy_cli
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Tests verify CLI commands and are also run automatically in the CI/CD pipeline.
|
|
289
|
+
|
|
290
|
+
Each command has one end-to-end test that runs it for real: the scaffolded plugin is
|
|
291
|
+
installed in a throwaway virtualenv and loaded by an app (`tests/test_scaffold_e2e.py`,
|
|
292
|
+
needs network access for the build), the generated project is imported, and
|
|
293
|
+
`start-dev-server` is started and queried over HTTP.
|
|
294
|
+
|
|
295
|
+
## Layout
|
|
296
|
+
|
|
297
|
+
```
|
|
298
|
+
fastpluggy_cli/
|
|
299
|
+
├── cli.py # the `fastpluggy` group, plugin command discovery
|
|
300
|
+
├── commands/ # new / new-plugin, start-dev-server, validate / fix-plugin
|
|
301
|
+
├── scaffold.py # content of every generated file
|
|
302
|
+
├── fixers.py # one auto-fix per compliance rule
|
|
303
|
+
└── scaffold_templates/ # the file bodies, as Jinja templates
|
|
304
|
+
```
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
"""The `fastpluggy` command group.
|
|
2
|
+
|
|
3
|
+
The commands live in fastpluggy_cli/commands/. This module keeps what other
|
|
4
|
+
code addresses by name: the `fastpluggy_cli.cli:cli` console script and
|
|
5
|
+
`fastpluggy_cli.cli:_create_dev_app`, which uvicorn imports by string.
|
|
6
|
+
"""
|
|
7
|
+
import importlib.metadata
|
|
8
|
+
import sys
|
|
9
|
+
|
|
10
|
+
import click
|
|
11
|
+
|
|
12
|
+
PLUGIN_COMMANDS_EP_GROUP = "fastpluggy.cli"
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class RichGroup(click.Group):
|
|
16
|
+
"""Click Group subclass that visually separates core and plugin commands."""
|
|
17
|
+
|
|
18
|
+
def __init__(self, *args, **kwargs):
|
|
19
|
+
super().__init__(*args, **kwargs)
|
|
20
|
+
self._plugin_command_names: set[str] = set()
|
|
21
|
+
|
|
22
|
+
def format_commands(self, ctx, formatter):
|
|
23
|
+
core_cmds = []
|
|
24
|
+
plugin_cmds = []
|
|
25
|
+
for name in self.list_commands(ctx):
|
|
26
|
+
cmd = self.get_command(ctx, name)
|
|
27
|
+
if cmd is None or cmd.hidden:
|
|
28
|
+
continue
|
|
29
|
+
help_text = cmd.get_short_help_str(limit=formatter.width)
|
|
30
|
+
if name in self._plugin_command_names:
|
|
31
|
+
plugin_cmds.append((name, help_text))
|
|
32
|
+
else:
|
|
33
|
+
core_cmds.append((name, help_text))
|
|
34
|
+
|
|
35
|
+
if core_cmds:
|
|
36
|
+
with formatter.section("Core Commands"):
|
|
37
|
+
formatter.write_dl(core_cmds)
|
|
38
|
+
if plugin_cmds:
|
|
39
|
+
with formatter.section("Plugin Commands"):
|
|
40
|
+
formatter.write_dl(plugin_cmds)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _load_plugin_commands(group: RichGroup) -> None:
|
|
44
|
+
"""Discover and register plugin CLI commands from entry points."""
|
|
45
|
+
eps = importlib.metadata.entry_points(group=PLUGIN_COMMANDS_EP_GROUP)
|
|
46
|
+
for ep in eps:
|
|
47
|
+
if ep.name in group.commands:
|
|
48
|
+
print(
|
|
49
|
+
f"WARNING: CLI command group '{ep.name}' conflicts with an existing "
|
|
50
|
+
f"command. Skipping plugin entry point '{ep.value}'. "
|
|
51
|
+
f"Resolve the conflict by renaming one of the plugins.",
|
|
52
|
+
file=sys.stderr,
|
|
53
|
+
)
|
|
54
|
+
continue
|
|
55
|
+
try:
|
|
56
|
+
cmd = ep.load()
|
|
57
|
+
except Exception as exc:
|
|
58
|
+
print(
|
|
59
|
+
f"WARNING: Failed to load CLI plugin '{ep.name}' "
|
|
60
|
+
f"({ep.value}): {exc}",
|
|
61
|
+
file=sys.stderr,
|
|
62
|
+
)
|
|
63
|
+
continue
|
|
64
|
+
if not isinstance(cmd, click.Command):
|
|
65
|
+
print(
|
|
66
|
+
f"WARNING: CLI plugin '{ep.name}' ({ep.value}) is not a "
|
|
67
|
+
f"click.Command — skipping.",
|
|
68
|
+
file=sys.stderr,
|
|
69
|
+
)
|
|
70
|
+
continue
|
|
71
|
+
group.add_command(cmd, ep.name)
|
|
72
|
+
group._plugin_command_names.add(ep.name)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _create_dev_app():
|
|
76
|
+
"""
|
|
77
|
+
Top-level factory for `fastpluggy start-dev-server`.
|
|
78
|
+
Must stay at module level so uvicorn can import it by string when --reload is used.
|
|
79
|
+
Auto-discovers all installed FastPluggy plugins via entry points.
|
|
80
|
+
"""
|
|
81
|
+
from fastapi import FastAPI
|
|
82
|
+
from fastpluggy.fastpluggy import FastPluggy
|
|
83
|
+
|
|
84
|
+
app = FastAPI()
|
|
85
|
+
FastPluggy(app)
|
|
86
|
+
return app
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
@click.group(cls=RichGroup, help="FastPluggy CLI - Scaffold and manage FastPluggy apps.")
|
|
90
|
+
def cli():
|
|
91
|
+
pass
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@cli.command("help", help="Show available commands")
|
|
95
|
+
@click.pass_context
|
|
96
|
+
def help_cmd(ctx):
|
|
97
|
+
"""Same output as `fastpluggy --help`, so the two cannot drift apart."""
|
|
98
|
+
click.echo(ctx.parent.get_help())
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _register_core_commands(group: click.Group) -> None:
|
|
102
|
+
from fastpluggy_cli.commands import dev_server, new, validate
|
|
103
|
+
|
|
104
|
+
for command in (
|
|
105
|
+
new.new,
|
|
106
|
+
new.new_plugin,
|
|
107
|
+
dev_server.start_dev_server,
|
|
108
|
+
validate.validate,
|
|
109
|
+
validate.fix_plugin,
|
|
110
|
+
):
|
|
111
|
+
group.add_command(command)
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
_register_core_commands(cli)
|
|
115
|
+
_load_plugin_commands(cli)
|
|
116
|
+
|
|
117
|
+
if __name__ == '__main__':
|
|
118
|
+
cli()
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""One module per family of `fastpluggy` commands; cli.py registers them."""
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
"""`fastpluggy start-dev-server`."""
|
|
2
|
+
import ipaddress
|
|
3
|
+
import os
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
import click
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def _generate_self_signed_cert(cert_dir: Path) -> tuple[str, str]:
|
|
10
|
+
"""Generate a self-signed SSL certificate for dev use. Returns (certfile, keyfile) paths."""
|
|
11
|
+
from cryptography import x509
|
|
12
|
+
from cryptography.x509.oid import NameOID
|
|
13
|
+
from cryptography.hazmat.primitives import hashes, serialization
|
|
14
|
+
from cryptography.hazmat.primitives.asymmetric import rsa
|
|
15
|
+
import datetime
|
|
16
|
+
|
|
17
|
+
cert_file = cert_dir / "dev-cert.pem"
|
|
18
|
+
key_file = cert_dir / "dev-key.pem"
|
|
19
|
+
|
|
20
|
+
if cert_file.exists() and key_file.exists():
|
|
21
|
+
click.echo(f"🔒 Reusing existing dev certificate: {cert_file}")
|
|
22
|
+
return str(cert_file), str(key_file)
|
|
23
|
+
|
|
24
|
+
cert_dir.mkdir(parents=True, exist_ok=True)
|
|
25
|
+
|
|
26
|
+
key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
|
|
27
|
+
|
|
28
|
+
import socket
|
|
29
|
+
hostname = socket.gethostname()
|
|
30
|
+
|
|
31
|
+
subject = issuer = x509.Name([
|
|
32
|
+
x509.NameAttribute(NameOID.COMMON_NAME, f"FastPluggy Dev ({hostname})"),
|
|
33
|
+
x509.NameAttribute(NameOID.ORGANIZATION_NAME, "FastPluggy Dev"),
|
|
34
|
+
])
|
|
35
|
+
|
|
36
|
+
san_names: list[x509.GeneralName] = [
|
|
37
|
+
x509.DNSName("localhost"),
|
|
38
|
+
x509.DNSName(hostname),
|
|
39
|
+
x509.IPAddress(ipaddress.IPv4Address("127.0.0.1")),
|
|
40
|
+
]
|
|
41
|
+
# Add local network IPs so the cert works on LAN
|
|
42
|
+
for local_ip in _get_local_ips():
|
|
43
|
+
san_names.append(x509.IPAddress(local_ip))
|
|
44
|
+
|
|
45
|
+
cert = (
|
|
46
|
+
x509.CertificateBuilder()
|
|
47
|
+
.subject_name(subject)
|
|
48
|
+
.issuer_name(issuer)
|
|
49
|
+
.public_key(key.public_key())
|
|
50
|
+
.serial_number(x509.random_serial_number())
|
|
51
|
+
.not_valid_before(datetime.datetime.now(datetime.timezone.utc))
|
|
52
|
+
.not_valid_after(datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=365))
|
|
53
|
+
.add_extension(x509.SubjectAlternativeName(san_names), critical=False)
|
|
54
|
+
.sign(key, hashes.SHA256())
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
key_file.write_bytes(key.private_bytes(
|
|
58
|
+
serialization.Encoding.PEM,
|
|
59
|
+
serialization.PrivateFormat.TraditionalOpenSSL,
|
|
60
|
+
serialization.NoEncryption(),
|
|
61
|
+
))
|
|
62
|
+
cert_file.write_bytes(cert.public_bytes(serialization.Encoding.PEM))
|
|
63
|
+
|
|
64
|
+
click.echo(f"🔒 Generated self-signed dev certificate: {cert_file}")
|
|
65
|
+
return str(cert_file), str(key_file)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _get_local_ips():
|
|
69
|
+
"""Return a list of local IPv4 addresses (non-loopback)."""
|
|
70
|
+
import socket
|
|
71
|
+
ips = []
|
|
72
|
+
try:
|
|
73
|
+
for info in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
|
|
74
|
+
addr = ipaddress.IPv4Address(info[4][0])
|
|
75
|
+
if not addr.is_loopback and addr not in ips:
|
|
76
|
+
ips.append(addr)
|
|
77
|
+
except socket.gaierror:
|
|
78
|
+
pass
|
|
79
|
+
return ips
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
@click.command("start-dev-server", help="Start a FastPluggy dev server with auto-discovered plugins")
|
|
83
|
+
@click.option("--port", default=8000, show_default=True, help="Port to listen on")
|
|
84
|
+
@click.option("--host", default="127.0.0.1", show_default=True, help="Host to bind to")
|
|
85
|
+
@click.option("--reload", is_flag=True, default=False, help="Enable hot-reload (local dev only)")
|
|
86
|
+
@click.option(
|
|
87
|
+
"--reload-dir",
|
|
88
|
+
"reload_dirs",
|
|
89
|
+
multiple=True,
|
|
90
|
+
type=click.Path(exists=True, file_okay=False),
|
|
91
|
+
help="Directory to watch when --reload is set. Repeatable. Without it uvicorn "
|
|
92
|
+
"falls back to watching the current working directory.",
|
|
93
|
+
)
|
|
94
|
+
@click.option(
|
|
95
|
+
"--proxy-headers/--no-proxy-headers",
|
|
96
|
+
"proxy_headers",
|
|
97
|
+
default=None,
|
|
98
|
+
help="Trust X-Forwarded-* from the reverse proxy so url_for() resolves against "
|
|
99
|
+
"the public vhost instead of the socket. uvicorn enables this by default; "
|
|
100
|
+
"pass --no-proxy-headers to turn it off. WHICH peers are trusted is set by "
|
|
101
|
+
"--forwarded-allow-ips.",
|
|
102
|
+
)
|
|
103
|
+
@click.option(
|
|
104
|
+
"--forwarded-allow-ips",
|
|
105
|
+
"forwarded_allow_ips",
|
|
106
|
+
default=None,
|
|
107
|
+
help="Comma-separated peer IPs whose X-Forwarded-* headers are trusted, or '*' "
|
|
108
|
+
"for any client. Left unset, uvicorn falls back to the FORWARDED_ALLOW_IPS "
|
|
109
|
+
"environment variable and then to 127.0.0.1 — which silently drops the "
|
|
110
|
+
"headers when the proxy is a different container or host.",
|
|
111
|
+
)
|
|
112
|
+
@click.option("--verbose", "-v", is_flag=True, default=False, help="Enable verbose/debug logging")
|
|
113
|
+
@click.option("--ssl", "use_ssl", is_flag=True, default=False, help="Enable HTTPS with auto-generated self-signed certificate")
|
|
114
|
+
def start_dev_server(port, host, reload, reload_dirs, proxy_headers, forwarded_allow_ips, verbose, use_ssl):
|
|
115
|
+
"""Start a FastPluggy development server.
|
|
116
|
+
|
|
117
|
+
Auto-discovers all installed FastPluggy plugins via the
|
|
118
|
+
'fastpluggy.plugins' entry point group. Set DATABASE_URL in your
|
|
119
|
+
environment to use a custom database (defaults to SQLite).
|
|
120
|
+
|
|
121
|
+
Use --ssl to enable HTTPS with an auto-generated self-signed certificate.
|
|
122
|
+
Required for Web Push (VAPID) on non-localhost hosts.
|
|
123
|
+
"""
|
|
124
|
+
import logging
|
|
125
|
+
|
|
126
|
+
try:
|
|
127
|
+
import uvicorn
|
|
128
|
+
except ImportError:
|
|
129
|
+
click.echo("❌ uvicorn is required: pip install uvicorn[standard]")
|
|
130
|
+
raise SystemExit(1)
|
|
131
|
+
|
|
132
|
+
if verbose:
|
|
133
|
+
logging.basicConfig(level=logging.DEBUG)
|
|
134
|
+
# Core logs through loguru and keeps it at INFO unless LOGURU_LEVEL is
|
|
135
|
+
# set. The variable is read when loguru is first imported and is
|
|
136
|
+
# inherited by the --reload subprocess.
|
|
137
|
+
os.environ["LOGURU_LEVEL"] = "DEBUG"
|
|
138
|
+
log_level = "debug"
|
|
139
|
+
else:
|
|
140
|
+
log_level = "info"
|
|
141
|
+
|
|
142
|
+
if not os.environ.get("DATABASE_URL"):
|
|
143
|
+
db_path = Path(".") / "fastpluggy-dev.db"
|
|
144
|
+
os.environ["DATABASE_URL"] = f"sqlite:///{db_path}"
|
|
145
|
+
click.echo(f"ℹ️ DATABASE_URL not set — using SQLite: {db_path}")
|
|
146
|
+
|
|
147
|
+
ssl_kwargs = {}
|
|
148
|
+
if use_ssl:
|
|
149
|
+
try:
|
|
150
|
+
from cryptography import x509 # noqa: F401
|
|
151
|
+
except ImportError:
|
|
152
|
+
click.echo("❌ cryptography is required for --ssl: pip install cryptography")
|
|
153
|
+
raise SystemExit(1)
|
|
154
|
+
|
|
155
|
+
cert_dir = Path(".") / ".fastpluggy" / "ssl"
|
|
156
|
+
cert_file, key_file = _generate_self_signed_cert(cert_dir)
|
|
157
|
+
ssl_kwargs = {"ssl_certfile": cert_file, "ssl_keyfile": key_file}
|
|
158
|
+
|
|
159
|
+
# Scope the reload watcher. Without this uvicorn watches the CURRENT WORKING
|
|
160
|
+
# DIRECTORY, which is fine for a single-package project and wrong for a repo
|
|
161
|
+
# whose plugin is a subdirectory: run from the root and it watches .git/ and
|
|
162
|
+
# node_modules/ too, which presents as "the dev server is slow", not as an
|
|
163
|
+
# error. Omitting the key entirely keeps uvicorn's own default, so callers
|
|
164
|
+
# that do not ask for this see no change.
|
|
165
|
+
reload_kwargs = {}
|
|
166
|
+
if reload_dirs:
|
|
167
|
+
if not reload:
|
|
168
|
+
click.echo("⚠️ --reload-dir has no effect without --reload; ignoring it.")
|
|
169
|
+
else:
|
|
170
|
+
reload_kwargs["reload_dirs"] = [str(Path(d).resolve()) for d in reload_dirs]
|
|
171
|
+
click.echo(f"👀 Watching: {', '.join(reload_kwargs['reload_dirs'])}")
|
|
172
|
+
|
|
173
|
+
# Reverse-proxy pass-through. This command is the production boot for the
|
|
174
|
+
# fleet's host apps, so it has to be able to express production proxy settings:
|
|
175
|
+
# behind a proxy, request.url_for() must resolve against the public vhost and
|
|
176
|
+
# not the socket, or an OIDC redirect_uri is built wrong and the IdP rejects it.
|
|
177
|
+
#
|
|
178
|
+
# uvicorn already trusts X-Forwarded-* by default, but ONLY from 127.0.0.1
|
|
179
|
+
# (measured against uvicorn 0.41: Config.proxy_headers defaults to True and
|
|
180
|
+
# forwarded_allow_ips=None resolves to $FORWARDED_ALLOW_IPS, else "127.0.0.1").
|
|
181
|
+
# When the proxy is a different container or host the peer address is not
|
|
182
|
+
# loopback, the headers are dropped, and the wrong URL is generated with no
|
|
183
|
+
# error anywhere — so the allow-list is the load-bearing half, not the toggle.
|
|
184
|
+
#
|
|
185
|
+
# Omitting a key entirely keeps uvicorn's own default, so callers that do not
|
|
186
|
+
# ask for this see no change. For forwarded_allow_ips that omission is also
|
|
187
|
+
# what lets uvicorn keep reading FORWARDED_ALLOW_IPS itself: passing None
|
|
188
|
+
# through explicitly would work, but passing "" would not, and re-implementing
|
|
189
|
+
# the env fallback here would just be a second copy of uvicorn's own.
|
|
190
|
+
proxy_kwargs = {}
|
|
191
|
+
if proxy_headers is not None:
|
|
192
|
+
proxy_kwargs["proxy_headers"] = proxy_headers
|
|
193
|
+
if forwarded_allow_ips is not None:
|
|
194
|
+
proxy_kwargs["forwarded_allow_ips"] = forwarded_allow_ips
|
|
195
|
+
if "*" in [entry.strip() for entry in forwarded_allow_ips.split(",")]:
|
|
196
|
+
# A wildcard lets ANY client that can reach this socket forge
|
|
197
|
+
# X-Forwarded-* and steer every URL the app generates — including the
|
|
198
|
+
# OIDC redirect_uri. It is only safe when nothing but the proxy can
|
|
199
|
+
# open a connection, which is not true of a host-networked app.
|
|
200
|
+
click.echo(
|
|
201
|
+
"⚠️ --forwarded-allow-ips '*' trusts X-Forwarded-* from any client that "
|
|
202
|
+
"can reach this socket, which lets it steer every URL the app generates. "
|
|
203
|
+
"Only use it when the port is reachable solely by the proxy."
|
|
204
|
+
)
|
|
205
|
+
if proxy_headers is False:
|
|
206
|
+
click.echo("⚠️ --forwarded-allow-ips has no effect with --no-proxy-headers.")
|
|
207
|
+
|
|
208
|
+
protocol = "https" if use_ssl else "http"
|
|
209
|
+
click.echo(f"🚀 Starting FastPluggy dev server on {protocol}://{host}:{port} ...")
|
|
210
|
+
|
|
211
|
+
uvicorn.run(
|
|
212
|
+
"fastpluggy_cli.cli:_create_dev_app",
|
|
213
|
+
host=host,
|
|
214
|
+
port=port,
|
|
215
|
+
reload=reload,
|
|
216
|
+
factory=True,
|
|
217
|
+
log_level=log_level,
|
|
218
|
+
**reload_kwargs,
|
|
219
|
+
**proxy_kwargs,
|
|
220
|
+
**ssl_kwargs,
|
|
221
|
+
)
|