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.
Files changed (58) hide show
  1. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/PKG-INFO +6 -5
  2. fastpluggy_cli-0.1.6/README.md +304 -0
  3. fastpluggy_cli-0.1.6/fastpluggy_cli/cli.py +118 -0
  4. fastpluggy_cli-0.1.6/fastpluggy_cli/commands/__init__.py +1 -0
  5. fastpluggy_cli-0.1.6/fastpluggy_cli/commands/dev_server.py +221 -0
  6. fastpluggy_cli-0.1.6/fastpluggy_cli/commands/new.py +127 -0
  7. fastpluggy_cli-0.1.6/fastpluggy_cli/commands/validate.py +183 -0
  8. fastpluggy_cli-0.1.6/fastpluggy_cli/fixers.py +139 -0
  9. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold.py +116 -0
  10. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/README.md.j2 +17 -0
  11. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/cli.py.j2 +10 -0
  12. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/config.py.j2 +12 -0
  13. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/gitignore.j2 +41 -0
  14. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/gitlab-ci.yml.j2 +22 -0
  15. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/index.html.j2 +9 -0
  16. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/models.py.j2 +8 -0
  17. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/plugin.py.j2 +33 -0
  18. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli/scaffold_templates/plugin/pyproject.toml.j2 +20 -12
  19. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/router.py.j2 +31 -0
  20. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/plugin/test_plugin.py.j2 +12 -0
  21. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/project/env.j2 +3 -0
  22. fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/project/pyproject.toml.j2 +19 -0
  23. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/PKG-INFO +6 -5
  24. fastpluggy_cli-0.1.6/fastpluggy_cli.egg-info/SOURCES.txt +38 -0
  25. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/requires.txt +4 -4
  26. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/pyproject.toml +8 -7
  27. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_cli.py +5 -5
  28. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_fix.py +114 -7
  29. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_new_plugin.py +209 -50
  30. fastpluggy_cli-0.1.6/tests/test_scaffold_e2e.py +149 -0
  31. fastpluggy_cli-0.1.6/tests/test_start_dev_server.py +254 -0
  32. fastpluggy_cli-0.1.2/README.md +0 -199
  33. fastpluggy_cli-0.1.2/fastpluggy_cli/cli.py +0 -1023
  34. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/config.py.j2 +0 -22
  35. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/index.html.j2 +0 -10
  36. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/models/__init__.py.j2 +0 -1
  37. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/models/context.py.j2 +0 -37
  38. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/models/report.py.j2 +0 -27
  39. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/models/scheduled.py.j2 +0 -38
  40. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/plugin.py.j2 +0 -49
  41. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/router.py.j2 +0 -37
  42. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/runner.py.j2 +0 -171
  43. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/tasks/__init__.py.j2 +0 -1
  44. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/tasks/maintenance.py.j2 +0 -50
  45. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/tasks/plugin_update.py.j2 +0 -53
  46. fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates/plugin/tasks/scheduler.py.j2 +0 -73
  47. fastpluggy_cli-0.1.2/fastpluggy_cli.egg-info/SOURCES.txt +0 -33
  48. fastpluggy_cli-0.1.2/tests/test_cli_commands.py +0 -65
  49. fastpluggy_cli-0.1.2/tests/test_start_dev_server.py +0 -98
  50. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/MANIFEST.in +0 -0
  51. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli/__init__.py +0 -0
  52. {fastpluggy_cli-0.1.2/fastpluggy_cli/scaffold_templates → fastpluggy_cli-0.1.6/fastpluggy_cli/scaffold_templates/project}/main.py.j2 +0 -0
  53. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/dependency_links.txt +0 -0
  54. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/entry_points.txt +0 -0
  55. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/fastpluggy_cli.egg-info/top_level.txt +0 -0
  56. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/setup.cfg +0 -0
  57. {fastpluggy_cli-0.1.2 → fastpluggy_cli-0.1.6}/tests/test_plugin_commands.py +0 -0
  58. {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.2
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-Dist: click==8.4.2
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.1.1; extra == "dev"
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==49.0.0; extra == "ssl"
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
+ ![Page of a freshly scaffolded plugin](docs/screenshots/new-plugin-page.png)
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
+ )