@nakedev/go-scaffold 0.3.3 → 0.4.0

package/dist/prompts/create-wizard.js

@@ -28,7 +28,7 @@ async function runCreateWizard(preset = {}) {
         }));
     const openapiDocs = preset.openapiDocs ??
         (await (0, interactive_1.confirm)({
-            message: "Include hand-written OpenAPI docs (docs/openapi.yaml, whole docs/ tree served at /docs)?",
+            message: "Include hand-written OpenAPI docs (docs/openapi.yaml — files only, never served over HTTP)?",
             default: true,
         }));
     const observability = preset.observability ??

package/dist/utils/observability-patcher.js

@@ -49,8 +49,8 @@ function patchMainGoForObservability(mainGoPath, goModule, projectName) {
     }
     const newUseLine = `${USE_LINE.slice(0, -1)}, middleware.Metrics(), middleware.Tracing("${projectName}"))`;
     content = content.replace(USE_LINE, () => newUseLine);
-    // Not gated on APP_ENV the way /docs is: production is exactly where you
-    // want a scrape target, and Prometheus reaches it in-cluster. It is still
+    // Unlike docs/, which is never served at all: production is exactly where
+    // you want a scrape target, and Prometheus reaches it in-cluster. It is still
     // unauthenticated and does disclose your route list and traffic shape, so
     // block /metrics at the ingress rather than publishing it to the internet.
     const metricsRoute = 'r.GET("/metrics", gin.WrapH(promhttp.Handler()))';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",

package/templates/create/base/README.md.hbs

@@ -166,15 +166,15 @@ TEST_DB_DSN=postgres://postgres:postgres@localhost:5432/{{dbName}}_test?sslmode=
 
 ## API spec
 
-`docs/openapi.yaml` is hand-written and served, along with every file it `$ref`s (`common/`, `health/`, per-domain folders), under `/docs` while the server runs — point a renderer (Scalar, Swagger UI, Redoc) or a client generator (Hey API) at `http://localhost:8080/docs/openapi.yaml`, or browse the tree at `http://localhost:8080/docs/`. Update the spec by hand whenever an endpoint/DTO changes.
+`docs/openapi.yaml` is hand-written and split across sibling files (`common/`, `health/`, per-domain folders) via relative `$ref`. **The server never serves it** — there is no `/docs` route, in any environment, so the API surface and `docs/architect/`'s internal notes stay off the wire. Update the spec by hand whenever an endpoint/DTO changes.
 
-Some tools don't resolve external `$ref`s when importing a local file — they read it as-is and see zero routes (Bruno's "Import Collection" does this; some Postman flows too). For those, bundle the spec into one fully-resolved file first:
+To open it in a renderer (Scalar, Swagger UI, Redoc) or a client generator (Hey API), bundle it into one fully-resolved file and point the tool at that file. Bundling is also what importers that don't resolve external `$ref`s need — they read the index as-is and see zero routes (Bruno's "Import Collection" does this; some Postman flows too):
 
 ```bash
 make openapi-bundle          # writes docs/openapi.bundled.yaml (gitignored — regenerate anytime)
 ```
 
-Import `docs/openapi.bundled.yaml` instead. Tools that resolve `$ref` over HTTP or when reading a URL (Scalar, Swagger UI, Redoc) don't need this — point them at the live `/docs/openapi.yaml` URL above.
+Then open `docs/openapi.bundled.yaml` — it needs no network and no running server.
 {{/if}}
 
 ## Adding a domain

package/templates/create/base/cmd/api/wiring.go.hbs

@@ -89,23 +89,13 @@ func run() error {
 	})
 	// go-scaffold:extra-routes
 {{#if openapiDocs}}
-	// hand-written spec at docs/openapi.yaml, split across sibling files (common/, health/,
-	// <domain>/) via relative $ref — serve the whole tree under one prefix so a client that
-	// resolves $ref over HTTP (Scalar, Swagger UI, Redoc, Hey API pointed at a URL) can reach
-	// them too; StaticFile on just the index file would 404 on every $ref it follows.
-	//
-	// gin.Dir(..., true) keeps directory listings on, which r.Static suppresses:
-	// without them opening /docs/ in a browser answers 404 with a blank page,
-	// which reads as "this is broken" rather than "ask for a file". The listing
-	// costs nothing here — every file in the tree is already downloadable — and
-	// it makes openapi.yaml discoverable without knowing its name up front.
-	//
-	// Not in production: this serves your whole API surface — every path,
-	// parameter and schema — to anyone who asks. Publish the spec deliberately
-	// (`make openapi-bundle`) rather than by leaving this on.
-	if !cfg.IsProd() {
-		r.StaticFS("/docs", gin.Dir("./docs", true))
-	}
+	// ponytail: docs/ is deliberately NOT served over HTTP, in any environment.
+	// The whole tree — every path, parameter and schema, plus docs/architect/'s
+	// internal design notes — used to be reachable at /docs outside production.
+	// Read the spec from the working copy instead: `make openapi-bundle` writes
+	// one fully-resolved docs/openapi.bundled.yaml for a renderer or client
+	// generator to open as a local file. Publish it deliberately if you want
+	// it public.
 {{/if}}
 
 	api := r.Group("/{{apiPrefix}}")

package/templates/create/features/docs/architecture.md.hbs

@@ -104,9 +104,9 @@ insert, so it doesn't need `gen_random_uuid()`.
 ## 8. API Documentation
 
 **Decision:** Hand-written OpenAPI spec (`docs/openapi.yaml`), split by
-domain module, served under `/docs` (so relative `$ref`s to sibling files
-resolve over HTTP too — the index alone isn't enough for a renderer like
-Scalar/Swagger UI/Redoc to follow them).
+domain module, read from the working copy only — the server serves no `/docs`
+route in any environment. Renderers that follow relative `$ref`s get a
+fully-resolved single file from `make openapi-bundle`.
 **Rationale:** Cheap while the endpoint count is low; switch to
 comment-generated (swaggo) if hand-updates start drifting.
 {{/if}}

package/templates/create/features/docs/techstack.md.hbs

@@ -22,7 +22,7 @@
 - PostgreSQL + GORM baseline: always enabled
 - Graceful shutdown, structured logging, `/livez` + `/readyz`: always enabled
 - Docker Compose (local Postgres): `{{#if docker}}enabled{{else}}disabled{{/if}}`
-- OpenAPI docs (`docs/openapi.yaml`, whole `docs/` tree served at `/docs`): `{{#if openapiDocs}}enabled{{else}}disabled{{/if}}`
+- OpenAPI docs (`docs/openapi.yaml`, working-copy only — never served over HTTP): `{{#if openapiDocs}}enabled{{else}}disabled{{/if}}`
 - Metrics + tracing (Prometheus `/metrics`, OpenTelemetry for Gin + GORM, `cmd/api` only): `{{#if observability}}enabled{{else}}disabled{{/if}}`
 - API route prefix: `{{#if apiPrefix}}/{{apiPrefix}}{{else}}(none){{/if}}`
 - CI (`.github/workflows/ci.yml` — build, vet, gofmt check, golangci-lint, `go test` with a real Postgres service): always enabled