feat: zero-Azure local mode, single-instance guard, one-script provisioning

[markadams31]

Summary

Removes the biggest friction in this project: getting it running. Three deliverables:

1. Zero-Azure local mode

git clone … && cd autocrud && docker compose up --build
# → http://localhost:8000

That's the complete application — the production image (SPA + API, one origin) against a local SQL Server 2025 seeded from database/seed.sql (the worked-example schema: computed columns, temporal history, composite keys, rowversion, cross-schema FKs). Docker is the only prerequisite; no Azure subscription, no Entra sign-in, no configuration.

How it works:

• DB_AUTH_MODE on the backend: entra (default — production posture, completely unchanged) or local (one SQL login for reflection and data). Local mode deliberately does not exercise the per-user-grants model; /me reports sa (local) so writes are attributable in the UI. Refused outright on App Service (WEBSITE_SITE_NAME guard in config.py) so a misconfigured deployment can never silently fall back to a shared SQL login.
• A one-shot db-init service creates + seeds the database once; re-ups leave your data alone (docker compose down -v resets). .gitattributes pins *.sh/*.sql to LF so a Windows clone can't break the init script inside the Linux container.
• Dev loop without Docker for the app: docker compose up db db-init, run the backend natively with the local-mode env (.env.example has the block), and AUTOCRUD_PROXY_TARGET=http://localhost:8000 npm run dev — two processes, no auth proxy. The vite proxy target is now configurable (default unchanged).
• README gains a pitch-adjacent "Try it now — no Azure required" quickstart and a two-path Running locally section; CLAUDE.md records the commands.

2. Single-instance guard in Terraform

worker_count = 1 on the App Service plan, with the reasoning in-line: the schema snapshot, per-token engine cache, refresh throttle, and health cache are process-local, so a scaled-out deployment would serve a stale schema after /admin/refresh. Terraform now also reverts any manual portal scale-out on the next apply — the constraint is enforced, not remembered.

3. One-script hosted provisioning

pwsh infra/provision.ps1 [-Environment dev|prod] wraps the entire post-tfvars runbook: terraform init/apply → az acr build → app restart → seed (skipped when data exists; -ReseedDatabase to reset) → permissions.sql with the environment's group name substituted automatically → add yourself to the app-users group → write the local .env → print the app URL. Preflight catches the usual traps (not signed in, missing tfvars, legacy ODBC sqlcmd without Entra auth). The infra README now leads with the script; the step-by-step remains as reference.

Testing

• Unit/API tiers: 461 passed (12 new tests: config gate incl. App Service refusal + credential requirement, tokenless local data path, entra-mode 401 unchanged, /me behaviours). ruff, pyright, tsc, oxlint, terraform fmt all clean.
• Fresh-clone simulation (the actual first-time experience): cloned the repo into a scratch directory, ran the README quickstart verbatim, and drove the result in a real browser via Chrome DevTools — healthy in ~5 minutes including the image build, 13 tables in the sidebar, seeded rows rendering with FK labels, sa (local) identity badge, zero console errors. LF line endings verified to survive a Windows clone.
• Contract checks through the compose stack: reflection (13 tables), CRUD round-trips, rowversion If-Match (fresh token updates; stale token → 409), audit triggers stamping the SQL login, seed-once on re-up, clean down -v reset.
• Native dev-loop path: backend run natively in local mode against the compose database on a non-default port (Server=localhost,14330), confirming the documented two-process workflow.
• Port knobs (AUTOCRUD_PORT, AUTOCRUD_SQL_PORT) exercised throughout (this machine's :8000 was occupied — which is exactly what they're for).

Not covered: infra/provision.ps1 has not been run against a real subscription in this session (it reorchestrates the commands the infra README already documents, and its SQL/az steps mirror what was previously copy-pasted); suggest exercising it on the next dev re-provision.

🤖 Generated with Claude Code