Repository navigation
Expand file tree
/
Copy path08-command-reference.qmd
More file actions
118 lines (98 loc) · 7 KB
/
Copy path08-command-reference.qmd
File metadata and controls
118 lines (98 loc) · 7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
---
title: "Command Reference"
guide-section: "Operations"
---
# Command Reference
All backend tasks run through [mise](https://mise.jdx.dev). From inside
`backend/`, invoke a task by bare name (`mise run test`); from the repo root,
address it as `mise run //backend:test`. Run `mise tasks` to list them.
Every check runs on the host by default. Pass `--container` to run the same check
inside the Dockerfile `ci` stage, and `--engine <auto|docker|container|podman>`
to choose the runtime. Ad-hoc tool flags pass through after `--`
(e.g. `mise run test -- --cov`).
## Development tasks
| Task | What it does |
| ----------------: | :------------------------------- |
| `sync` | Sync dependencies into `.venv` (reruns only when `pyproject.toml` changed). |
| `serve` | Run the Flask backend locally (`python -m tenantfirstaid.app`). |
| `fmt` | Sort imports and format with ruff. On the host this **mutates**; `--container` verifies only, `--container --write` reformats the host tree via the container. |
| `lint` | Lint with ruff. |
| `typecheck` | Type-check. `--checker ty` (default, fast), `mypy`, or `pyrefly`. |
| `test` | Run pytest. `--no-env` ignores `backend/.env` and uses CI's values. |
| `check` | Full suite: clean, sync, fmt, lint, typecheck, test. Forwards `--no-env` to `test`. |
| `clean` | Remove `__pycache__` and build artifacts. |
| `install` | Install this package into the environment. |
| `generate-types` | Regenerate the frontend's TypeScript types from the Pydantic models. |
| `generate-referrals` | Regenerate the frontend's bundled referral catalog from the backend referral data. |
| `generate-frontend-assets` | Regenerate all frontend build-time assets (types and referral catalog). |
| `docs` | Build this documentation site with great-docs (needs Quarto; `--container` provides it). |
| `docs-serve` | Serve the already-built `great-docs/_site` locally (pure static files, no rebuild). |
: Development tasks {#tbl-dev-tasks}
::: {.callout-note title="Task notes"}
- **`typecheck`** uses `--checker`, not `--tool` — the latter collides with
the `run --tool` option built into mise. `ty` is the fast default; `mypy` and
`pyrefly` are available for a second opinion.
- **`check`** runs `lint`, `typecheck`, and `test` concurrently after an ordered
`clean` → `fmt`, since formatting mutates the tree the verify steps read.
- **`docs`** builds into `great-docs/_site`. On the host, install Quarto
yourself; `--container` uses the `ci` image, which ships Quarto.
- **`docs-serve`** just serves whatever `docs` last produced; run `docs`
(or `docs --container`) again first if you've edited a `.qmd` file.
- **`--no-env`** reproduces CI's *environment*, as `--container` reproduces its
*tooling*. It hides `backend/.env` and exports the placeholder values
`.github/workflows/pr-check.yml` sets, including a
`GOOGLE_APPLICATION_CREDENTIALS` path that does not exist. Without it, a test
that forgets to mock a credential load still passes locally, because a
developer's `.env` names a real credentials file -- so the failure appears
only once the branch is pushed. The two flags are mutually exclusive: the
container lane bind-mounts the very file `--no-env` hides.
:::
`check` is the command you'll run most. Here it is end to end — the ordered
`clean` → `fmt`, then `lint`, `typecheck`, and `test` running concurrently, down
to the final `pytest` summary:
{{< termshow file="demos/check" >}}
## Docs quality tasks
Read-only great-docs checks over the live working tree — they catch missing
docstrings, broken links, and spelling/grammar issues before they land. Every
task takes `--container` (runs in the Dockerfile `docs` image, which ships
Quarto and harper-cli) and `--engine <auto|docker|container|podman>`; on the
host, install Quarto and harper-cli yourself.
| Task | What it checks |
| -------------------:| :------------------------------------------------------------------ |
| `docs-lint` | Missing docstrings, broken xrefs, style, via `great-docs lint`. |
| `docs-check-links` | Broken links in docs and source (`-- --docs-only` to skip source). Makes HTTP requests. |
| `docs-proofread` | Spelling/grammar via `great-docs proofread` (needs harper-cli; use `--container`). Reads `.great-docs-dictionary` for project/domain terms. |
| `docs-check` | Runs all three above in parallel; all three report even if one fails. |
: Docs quality tasks {#tbl-docs-tasks}
::: {.callout-note title="Task notes"}
- **`docs-check --container`** builds the docs image once up front, then runs
the three checks in it concurrently — letting them race a first build
corrupts the `apple/container` builder, so the image is warmed
sequentially before the parallel run.
- All checks run `PYTHONPATH=/src` in `--container` mode, so they introspect
the bind-mounted source tree (your uncommitted edits), not the copy baked
into the image — only dependency changes need a `--rebuild`.
:::
## Corpus ingestion tasks
These build and publish the Vertex AI Search corpus, in the order shown. The
narrative is in [Corpus Ingestion](07-corpus-ingestion.qmd). Required inputs
(bucket / datastore / app IDs) are task flags; ad-hoc script flags pass through
after `--`.
| Task | Required flags | Purpose |
| ---------------------: | ------------------- | :----------------------------- |
| `enforce-ascii` | — | Validate/rewrite the documents tree to pure ASCII. `-- --check` validates only. |
| `generate-metadata` | `--bucket <bucket>` | Regenerate `metadata.jsonl`. Scope flags pass through (e.g. `-- --portland`). |
| `upload-to-gcs` | `--bucket <bucket>` | Create a GCS bucket and upload the corpus. `--location` overrides the default US multi-region; `-- --dry-run` previews. |
| `create-datastore-gcs` | `--bucket <bucket> --datastore-id <id>` | Create a Vertex AI Search datastore and import from the bucket. `-- --no-wait` skips polling. |
| `create-app-gcs` | `--datastore-id <id> --app-id <id>` | Create a Vertex AI Search app linked to the datastore. `-- --dry-run` previews. |
: Corpus ingestion tasks {#tbl-corpus-tasks}
### Example: a full ingestion run
```{.bash filename="Full ingestion run (from backend/)"}
# From backend/
mise run enforce-ascii
mise run generate-metadata --bucket tfa-corpus-2025
mise run upload-to-gcs --bucket tfa-corpus-2025
mise run create-datastore-gcs --bucket tfa-corpus-2025 --datastore-id tfa-laws-2025
mise run create-app-gcs --datastore-id tfa-laws-2025 --app-id tfa-laws-app
# Then set VERTEX_AI_DATASTORE_LAWS=tfa-laws-2025 in backend/.env
```