4 Commits

Author	SHA1	Message	Date
Nguyen Minh Phuc	c53734d2bc	docs: add USER_GUIDE.md, tighten comments, fix CLI needing a DSN ... The comment pass is prose-only: every distinct "why" is kept, the narration around it is not. Verified by AST-comparing each changed file against HEAD with docstrings stripped — only the two files below differ in executable code. Two real fixes fell out of the read-through: * The CLI documented itself as never touching the database, then called load_settings(), which requires SVCFORGE_PG_DSN. It refused to start without a Postgres URL it never opens. It now has its own two-field ClientSettings; the orphaned api_url/api_token are dropped from Settings, where nothing else read them. * repo/db.py had the DictRow alias comment and the ERROR_MAX_CHARS comment run together above the wrong symbol. USER_GUIDE.md is the caller-facing guide the README only gestured at: auth, catalog, every endpoint with curl, the lifecycle, the error table, rate limiting, the CLI, client generation, an end-to-end poll loop. It records two facts about the live deployment rather than documenting a flow nobody can run. SVCFORGE_JWKS_URL points at a realm with no IdP behind it, so the API logs "JWKS warm-up failed" at startup and every /v1 request is a 401. And `helm repo list` in the worker returns no repositories, so the three bitnamilegacy/ catalog entries cannot resolve at provision time; only the oci:// entries can. make lint clean, 76 unit + 111 integration tests pass.	2026-07-21 14:51:26 +00:00
Nguyen Minh Phuc	6974b3620f	catalog: two tiny services, so the loop can be exercised on a full cluster ... The three existing entries are sized like real products: `elasticsearch` small asks for 1Gi and medium for 4Gi across three replicas. On this cluster that is a request that never schedules, so provisioning them proves something about the node and nothing about svcforge. podinfo 16Mi/10m — one small Go binary, no dependencies, no PVC nginx 32Mi/10m — recognisable, still small Both are addressed as `oci://`, which is load-bearing rather than cosmetic. An OCI chart is pulled by reference with no `helm repo add` first. The three existing entries name `bitnamilegacy/<chart>`, a classic repo alias that nothing in the worker image configures — so as written they cannot resolve at provision time. OCI is the form that works from a bare container, and it is why the e2e test already provisions podinfo. Chart versions were resolved against the real registries before committing (podinfo 6.7.1, nginx 25.0.14 / app 1.31.3) rather than guessed, since a wrong version fails only at provision time. Also updates the CLI ServiceType enum, the catalog test's expected set, and the service list in the OpenAPI description.	2026-07-21 05:47:41 +00:00
Nguyen Minh Phuc	bb8b14ef03	api: make the OpenAPI spec usable as documentation ... FastAPI already served /docs, /redoc and /openapi.json, and the ingress already passed them through — the mechanism was there, the content was not. The schema alone cannot tell a caller the three things they most need to know, and the route docstrings explain implementation reasoning to a maintainer rather than usage to a consumer. Added to the spec itself, so it travels with the API rather than living in a README the caller does not have: - An app description covering bearer auth, that every write is 202 + poll, the instance lifecycle, and the uniform {"code", "message"} error body. - Tag descriptions for `instances` and `ops`. - Field descriptions and worked examples on CreateInstanceRequest, InstanceResponse and ErrorBody, so /docs shows a valid payload instead of leaving callers to infer one. The bearer scheme was already exposed via HTTPBearer, which is what makes the Authorize button in /docs work; there is now a test asserting it stays, along with the description, the tags and the request example. Docs that are not tested rot silently, and this is the artifact other teams integrate against. README documents the three URLs and how to generate a client from the spec.	2026-07-21 05:33:44 +00:00
Nguyen Minh Phuc	50c2fe2a1e	svcforge: reference implementation ... Complete working build of the system learn-python/ teaches. 164 tests, mypy --strict clean, domain coverage 99%.	2026-07-17 10:44:54 +00:00