create-daloy 0.7.3 → 0.8.0

package/README.md

@@ -44,10 +44,10 @@ pnpm create daloy@latest my-api \
 | `--template <name>` | `node-basic` (default), `vercel-edge`, `cloudflare-worker`, `bun-basic`, or `deno-basic`. |
 | `--package-manager <pm>` | `pnpm` (default), `npm`, `yarn`, or `bun`. Ignored for `deno-basic`. |
 | `--list-templates` | Print available templates with descriptions. |
-| `--install` / `--no-install` | Install dependencies after scaffolding. Defaults to interactive. |
+| `--install` / `--no-install` | Install dependencies after scaffolding. Defaults to **Y** for npm/yarn/bun and **N** for pnpm (so first-time runs are not blocked by the 24h `minimumReleaseAge` embargo or the `pnpm.onlyBuiltDependencies` allowlist required by the hardened `.npmrc`). |
 | `--git` / `--no-git` | Initialize a git repository. Defaults to interactive. |
 | `--minimal` | Strip the bookstore demo route and the built-in `/docs` + `/openapi.json` routes so only the framework bootstrap and `/healthz` ship. |
-| `--with-ci` / `--no-ci` | Add the hardened GitHub Actions, Dependabot, CODEOWNERS, SECURITY.md, and lockfile-source verification bundle. |
+| `--with-ci` / `--no-ci` | Add the hardened GitHub Actions, Dependabot, CODEOWNERS, SECURITY.md, and lockfile-source verification bundle. **Defaults to Y** so scaffolded projects are secure by default. |
 | `--code-owner <owner>` | Replace the CODEOWNERS placeholder when `--with-ci` is used, for example `@acme/security`. |
 | `--force` | Overwrite an existing non-empty directory. |
 | `--yes` | Accept all defaults; never prompt. |
@@ -67,6 +67,8 @@ A production-ready Node.js HTTP server using `@daloyjs/core` with:
 - `secureHeaders`, `requestId`, and `rateLimit` enabled by default (`rateLimit` is global until you configure `keyGenerator` or trusted proxy headers).
 - A sample `GET /healthz` and contract-first `GET /books/:id` route with Zod validation.
 - `pnpm gen` wired to emit OpenAPI 3.1 + a typed Hey API client.
+- Auto-mounted Scalar docs can be branded by changing `docs: true` to
+  `docs: { scalar: { theme, customCss } }`.
 
 ### `cloudflare-worker`
 

package/bin/create-daloy.mjs

@@ -587,7 +587,7 @@ function setupPackageManagerStep(packageManager) {
     return `      - name: Set up pnpm
         uses: pnpm/action-setup@ac6db6d3c1f721f886538a378a2d73e85697340a # v6
         with:
-          version: 11.1.2
+          version: 11.1.3
           run_install: false`;
   }
   if (packageManager === "yarn") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
   "type": "module",
   "license": "MIT",

package/templates/bun-basic/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) runtime. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) runtime. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. When `docs: true` is set in `new App({...})`, three routes are auto-mounted: `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
 
 - Package manager / runtime: Bun.
 

package/templates/bun-basic/README.md

@@ -19,11 +19,16 @@ curl http://localhost:3000/books/1
 ```
 
 <!-- daloy-minimal:strip-start docs -->
+
 ## API documentation
 
 - API docs (Scalar): <http://localhost:3000/docs>
 - OpenAPI 3.1 JSON: <http://localhost:3000/openapi.json>
 - OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
+
+The spec is generated live from your routes, so it stays in sync with what is actually deployed.
+To brand Scalar, change `docs: true` in `src/build-app.ts` to `docs: { scalar: { theme, customCss } }`.
+
 <!-- daloy-minimal:strip-end docs -->
 
 ## Generate OpenAPI + typed client

package/templates/bun-basic/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -65,6 +65,23 @@ Always run `bun run typecheck` and `bun test` before declaring a task done.
 If a change touches route shapes, also rerun `bun run gen:openapi && bun
 run gen:client` so the client stays in sync.
 
+## OpenAPI & docs routes
+
+When `docs: true` is set on `new App({...})` (the default in this template),
+three routes are auto-mounted off the spec generated from your route
+definitions:
+
+- `GET /openapi.json` — OpenAPI 3.1 spec as JSON.
+- `GET /openapi.yaml` — OpenAPI 3.1 spec as YAML (served inline as
+  `text/yaml; charset=utf-8`, since `@daloyjs/core` 0.13.1).
+- `GET /docs` — Scalar API reference UI that loads the spec.
+
+Customize via `docs: { openapiPath, openapiYamlPath, path, ui }`. Set
+`openapiYamlPath: false` to disable just the YAML route, `docs: "auto"` to
+mount only outside production, or `docs: false` to disable all three.
+For hand-rolled mounting, `openapiToYAML` is exported from
+`@daloyjs/core/openapi`.
+
 ## Workflow: add a new route
 
 1. **Open `src/build-app.ts`.**

package/templates/bun-basic/package.json

@@ -16,7 +16,7 @@
     "gen": "pnpm gen:openapi && pnpm gen:client"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.13.2",
+    "@daloyjs/core": "^0.14.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/bun-basic/src/build-app.ts

@@ -19,9 +19,11 @@ export function buildApp(): App {
     requestTimeoutMs: 5_000,
     production: process.env.NODE_ENV === "production",
     // daloy-minimal:strip-start docs
-    // Auto-mounted docs:
-    //   GET /openapi.json — live OpenAPI 3.1 spec generated from your routes
-    //   GET /docs         — Scalar API reference UI that loads it
+    // Auto-mounted docs (when `docs: true`):
+    //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
+    //   GET /openapi.yaml — OpenAPI 3.1 spec (YAML, served inline as text/yaml)
+    //   GET /docs         — Scalar API reference UI that loads the spec
+    // Customize via `docs: { openapiYamlPath: false }` to disable the YAML route.
     // `info.title` / `info.version` are pulled from package.json by default;
     // set `openapi.info` here to override them.
     openapi: {

package/templates/cloudflare-worker/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. This starter omits `docs: true` to keep the Worker bundle small — enable it explicitly via `new App({ docs: true })` to auto-mount `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Cloudflare Workers (Web Standard `Request`/`Response`).

package/templates/cloudflare-worker/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -59,6 +59,24 @@ pnpm audit        # supply-chain audit
 
 Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
 
+## OpenAPI & docs routes (opt-in)
+
+This Worker starter omits `docs: true` to keep the bundle small (Workers
+have a hard size limit). When you opt in via `new App({ docs: true })`,
+three routes are auto-mounted off the spec generated from your route
+definitions:
+
+- `GET /openapi.json` — OpenAPI 3.1 spec as JSON.
+- `GET /openapi.yaml` — OpenAPI 3.1 spec as YAML (served inline as
+  `text/yaml; charset=utf-8`, since `@daloyjs/core` 0.13.1).
+- `GET /docs` — Scalar API reference UI that loads the spec.
+
+On Workers the Scalar UI adds the most weight; consider
+`docs: { ui: "swagger" }` or `docs: "auto"` (off in production), or pass
+`docs: { openapiYamlPath: false }` to drop the YAML route only.
+For hand-rolled mounting, `openapiToYAML` is exported from
+`@daloyjs/core/openapi`.
+
 ## Workflow: add a new route
 
 1. **Open `src/index.ts`.**

package/templates/cloudflare-worker/package.json

@@ -10,7 +10,7 @@
     "test": "node --import tsx/esm --test tests/**/*.test.ts"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.13.2",
+    "@daloyjs/core": "^0.14.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/deno-basic/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API for the [Deno](https://deno.com) runtime. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+A [DaloyJS](https://daloyjs.dev) REST API for the [Deno](https://deno.com) runtime. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. When `docs: true` is set in `new App({...})`, three routes are auto-mounted: `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
 
 - Runtime: Deno (no Node package manager). Dependencies are loaded via `npm:` and `jsr:` specifiers in `deno.json`.
 

package/templates/deno-basic/README.md

@@ -18,11 +18,16 @@ curl http://localhost:3000/books/1
 ```
 
 <!-- daloy-minimal:strip-start docs -->
+
 ## API documentation
 
 - API docs (Scalar): <http://localhost:3000/docs>
 - OpenAPI 3.1 JSON: <http://localhost:3000/openapi.json>
 - OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
+
+The spec is generated live from your routes, so it stays in sync with what is actually deployed.
+To brand Scalar, change `docs: true` in `src/build-app.ts` to `docs: { scalar: { theme, customCss } }`.
+
 <!-- daloy-minimal:strip-end docs -->
 
 ## Generate the OpenAPI spec

package/templates/deno-basic/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -67,6 +67,23 @@ npx @hey-api/openapi-ts -i generated/openapi.json -o generated/client
 Always run `deno task typecheck` and `deno task test` before declaring a
 task done.
 
+## OpenAPI & docs routes
+
+When `docs: true` is set on `new App({...})` (the default in this template),
+three routes are auto-mounted off the spec generated from your route
+definitions:
+
+- `GET /openapi.json` — OpenAPI 3.1 spec as JSON.
+- `GET /openapi.yaml` — OpenAPI 3.1 spec as YAML (served inline as
+  `text/yaml; charset=utf-8`, since `@daloyjs/core` 0.13.1).
+- `GET /docs` — Scalar API reference UI that loads the spec.
+
+Customize via `docs: { openapiPath, openapiYamlPath, path, ui }`. Set
+`openapiYamlPath: false` to disable just the YAML route, `docs: "auto"` to
+mount only outside production, or `docs: false` to disable all three.
+For hand-rolled mounting, `openapiToYAML` is exported from
+`@daloyjs/core/openapi`.
+
 ## Workflow: add a new route
 
 1. **Open `src/build-app.ts`.**

package/templates/deno-basic/deno.json

@@ -8,8 +8,8 @@
     "gen:openapi": "deno run --allow-net --allow-env --allow-read --allow-write scripts/dump-openapi.ts"
   },
   "imports": {
-    "@daloyjs/core": "npm:@daloyjs/core@^0.13.2",
-    "@daloyjs/core/": "npm:@daloyjs/core@^0.13.2/",
+    "@daloyjs/core": "npm:@daloyjs/core@^0.14.0",
+    "@daloyjs/core/": "npm:@daloyjs/core@^0.14.0/",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

package/templates/deno-basic/src/build-app.ts

@@ -20,9 +20,11 @@ export function buildApp(): App {
     requestTimeoutMs: 5_000,
     production: Deno.env.get("DENO_ENV") === "production",
     // daloy-minimal:strip-start docs
-    // Auto-mounted docs:
-    //   GET /openapi.json — live OpenAPI 3.1 spec generated from your routes
-    //   GET /docs         — Scalar API reference UI that loads it
+    // Auto-mounted docs (when `docs: true`):
+    //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
+    //   GET /openapi.yaml — OpenAPI 3.1 spec (YAML, served inline as text/yaml)
+    //   GET /docs         — Scalar API reference UI that loads the spec
+    // Customize via `docs: { openapiYamlPath: false }` to disable the YAML route.
     // `info.title` / `info.version` are pulled from deno.json by default;
     // set `openapi.info` here to override them.
     openapi: {

package/templates/node-basic/AGENTS.md

@@ -2,6 +2,8 @@
 
 A [DaloyJS](https://daloyjs.dev) Node.js REST API. **Contract-first**:
 routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+When `docs: true` is set in `new App({...})`, three routes are auto-mounted:
+`GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Node.js >= 24.15 (active LTS).

package/templates/node-basic/README.md

@@ -19,6 +19,7 @@ curl http://localhost:3000/books/1
 ```
 
 <!-- daloy-minimal:strip-start docs -->
+
 ## API documentation
 
 - API docs (Scalar): <http://localhost:3000/docs>
@@ -26,6 +27,8 @@ curl http://localhost:3000/books/1
 - OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
 
 The spec is generated live from your routes, so it stays in sync with what is actually deployed.
+To brand Scalar, change `docs: true` in `src/build-app.ts` to `docs: { scalar: { theme, customCss } }`.
+
 <!-- daloy-minimal:strip-end docs -->
 
 ## Generate OpenAPI + typed client

package/templates/node-basic/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -72,6 +72,28 @@ Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
 If a change touches route shapes, also run `pnpm gen` so the client stays
 in sync.
 
+## OpenAPI & docs routes
+
+When `docs: true` is set on `new App({...})` (the default in this template),
+three routes are auto-mounted off the spec generated from your route
+definitions:
+
+- `GET /openapi.json` — OpenAPI 3.1 spec as JSON.
+- `GET /openapi.yaml` — OpenAPI 3.1 spec as YAML (served inline as
+  `text/yaml; charset=utf-8`, since `@daloyjs/core` 0.13.1).
+- `GET /docs` — Scalar API reference UI that loads the spec.
+
+Customize via `docs: { openapiPath, openapiYamlPath, path, ui }`. Set
+`openapiYamlPath: false` to disable just the YAML route, `docs: "auto"` to
+mount only outside production, or `docs: false` to disable all three.
+
+For hand-rolled mounting (when `docs: false`), the YAML serializer is
+exported from the openapi subpath:
+
+```ts
+import { generateOpenAPI, openapiToYAML } from "@daloyjs/core/openapi";
+```
+
 ## Workflow: add a new route
 
 Follow these steps in order. Skipping any of them is a common source of

package/templates/node-basic/package.json

@@ -18,7 +18,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.13.2",
+    "@daloyjs/core": "^0.14.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/node-basic/src/build-app.ts

@@ -21,11 +21,14 @@ export function buildApp(): App {
     requestTimeoutMs: 5_000,
     production: process.env.NODE_ENV === "production",
     // daloy-minimal:strip-start docs
-    // Auto-mounted docs:
-    //   GET /openapi.json — live OpenAPI 3.1 spec generated from your routes
-    //   GET /docs         — Scalar API reference UI that loads it
+    // Auto-mounted docs (when `docs: true`):
+    //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
+    //   GET /openapi.yaml — OpenAPI 3.1 spec (YAML, served inline as text/yaml)
+    //   GET /docs         — Scalar API reference UI that loads the spec
     // `docs: true` always mounts. Use `docs: "auto"` to mount only when
     // `NODE_ENV !== "production"`, or `docs: false` to disable entirely.
+    // Customize paths via `docs: { openapiPath, openapiYamlPath, path, ui }`,
+    // or pass `openapiYamlPath: false` to disable just the YAML route.
     // `info.title` / `info.version` are pulled from package.json by default;
     // set `openapi.info` here to override them.
     openapi: {

package/templates/vercel-edge/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. When `docs: true` is set in `new App({...})`, three routes are auto-mounted: `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Vercel Edge (Web Standard `Request`/`Response`).

package/templates/vercel-edge/README.md

@@ -19,13 +19,16 @@ curl http://localhost:3000/books/1
 ```
 
 <!-- daloy-minimal:strip-start docs -->
+
 ## API documentation
 
 - API docs (Scalar): <http://localhost:3000/docs>
 - OpenAPI 3.1 JSON: <http://localhost:3000/openapi.json>
 - OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
 
-After deploying, the same routes serve `/docs` and `/openapi.json` from your Vercel Edge URL.
+After deploying, the same routes serve `/docs`, `/openapi.json`, and `/openapi.yaml` from your Vercel Edge URL.
+To brand Scalar, change `docs: true` in `api/[...path].ts` to `docs: { scalar: { theme, customCss } }`.
+
 <!-- daloy-minimal:strip-end docs -->
 
 ## Deploy
@@ -60,7 +63,7 @@ That catch-all API route lets DaloyJS own routing while Vercel handles the runti
 - Smaller edge-friendly body and timeout limits in the generated app.
 <!-- daloy-minimal:strip-start books -->
 - A health route and a contract-first `/books/:id` route with Zod validation.
-<!-- daloy-minimal:strip-end books -->
-<!-- daloy-minimal:strip-start docs -->
-- A Scalar API reference UI at `/docs` and a live OpenAPI 3.1 document at `/openapi.json`.
+  <!-- daloy-minimal:strip-end books -->
+  <!-- daloy-minimal:strip-start docs -->
+- A Scalar API reference UI at `/docs`, plus live OpenAPI 3.1 specs at `/openapi.json` and `/openapi.yaml`.
 <!-- daloy-minimal:strip-end docs -->

package/templates/vercel-edge/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -56,6 +56,24 @@ pnpm audit        # supply-chain audit
 
 Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
 
+## OpenAPI & docs routes
+
+When `docs: true` is set on `new App({...})` (the default in this template),
+three routes are auto-mounted off the spec generated from your route
+definitions:
+
+- `GET /openapi.json` — OpenAPI 3.1 spec as JSON.
+- `GET /openapi.yaml` — OpenAPI 3.1 spec as YAML (served inline as
+  `text/yaml; charset=utf-8`, since `@daloyjs/core` 0.13.1).
+- `GET /docs` — Scalar API reference UI that loads the spec.
+
+Customize via `docs: { openapiPath, openapiYamlPath, path, ui }`. Set
+`openapiYamlPath: false` to disable just the YAML route, `docs: "auto"` to
+mount only outside production, or `docs: false` to disable all three.
+On Vercel Edge the YAML serializer is pure-string (no Node deps) and
+adds <1KB to the bundle. For hand-rolled mounting, `openapiToYAML` is
+exported from `@daloyjs/core/openapi`.
+
 ## Workflow: add a new route
 
 1. **Open `api/[...path].ts`.**

package/templates/vercel-edge/api/[...path].ts

@@ -12,9 +12,10 @@ const app = new App({
   requestTimeoutMs: 5_000,
   production: process.env.NODE_ENV === "production",
   // daloy-minimal:strip-start docs
-  // Auto-mounted docs:
-  //   GET /openapi.json — live OpenAPI 3.1 spec generated from your routes
-  //   GET /docs         — Scalar API reference UI that loads it
+  // Auto-mounted docs (when `docs: true`):
+  //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
+  //   GET /openapi.yaml — OpenAPI 3.1 spec (YAML, served inline as text/yaml)
+  //   GET /docs         — Scalar API reference UI that loads the spec
   openapi: {
     info: { title: "My Daloy Edge API", version: "0.0.1" },
   },

package/templates/vercel-edge/package.json

@@ -10,7 +10,7 @@
     "test": "node --import tsx/esm --test tests/**/*.test.ts"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.13.2",
+    "@daloyjs/core": "^0.14.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {