create-daloy 0.7.2 → 0.7.4

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. |

package/bin/create-daloy.mjs

@@ -314,10 +314,10 @@ ${heading("Options")}
   ${color(COLORS.green, "--template <name>")}          ${TEMPLATES.join(" | ")}  ${color(COLORS.dim, "(default: node-basic)")}
   ${color(COLORS.green, "--package-manager <pm>")}     ${PACKAGE_MANAGERS.join(" | ")}  ${color(COLORS.dim, "(default: pnpm)")}
   ${color(COLORS.green, "--list-templates")}           Print available templates and exit.
-  ${color(COLORS.green, "--install / --no-install")}   Install dependencies after scaffolding.
+  ${color(COLORS.green, "--install / --no-install")}   Install dependencies after scaffolding. ${color(COLORS.dim, "(default: Y, except pnpm \u2014 N to respect minimumReleaseAge + onlyBuiltDependencies)")}
   ${color(COLORS.green, "--git / --no-git")}           Initialize a git repository.
   ${color(COLORS.green, "--minimal")}                  Strip the bookstore + OpenAPI docs demo routes.
-  ${color(COLORS.green, "--with-ci / --no-ci")}         Add hardened GitHub Actions + governance files.
+  ${color(COLORS.green, "--with-ci / --no-ci")}         Add hardened GitHub Actions + governance files. ${color(COLORS.dim, "(default: Y)")}
   ${color(COLORS.green, "--code-owner <owner>")}        CODEOWNERS owner for --with-ci, e.g. @acme/security.
   ${color(COLORS.green, "--force")}                    Overwrite an existing non-empty directory.
   ${color(COLORS.green, "--yes, -y")}                  Accept all defaults; never prompt.
@@ -1114,6 +1114,23 @@ function printSummary({ projectName, template, packageManager, installDeps, skip
     console.log(`  ${arrow} ${color(COLORS.cyan, `${packageManager} run dev`)}`);
   }
 
+  if (!installDeps && !skipPackageManager && packageManager === "pnpm") {
+    console.log("");
+    console.log(`${color(COLORS.bold, "Heads-up before \`pnpm install\`")}`);
+    console.log(
+      `  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, "pnpm-workspace.yaml sets minimumReleaseAge: 1440 \u2014 newly-published deps")}`,
+    );
+    console.log(
+      `  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, "(including a just-released @daloyjs/core) are embargoed for 24 h.")}`,
+    );
+    console.log(
+      `  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, "Lifecycle scripts are blocked by default; allowlist trusted builds in")}`,
+    );
+    console.log(
+      `  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, "package.json under pnpm.onlyBuiltDependencies if install complains.")}`,
+    );
+  }
+
   console.log("");
   console.log(`${color(COLORS.bold, "Useful commands")}`);
   if (skipPackageManager) {
@@ -1228,6 +1245,27 @@ async function main() {
     if (installDeps === undefined) {
       if (skipPackageManager) {
         installDeps = false;
+      } else if (packageManager === "pnpm") {
+        // Deny-by-default for pnpm: the scaffolded `pnpm-workspace.yaml` ships
+        // with `minimumReleaseAge: 1440` (24 h embargo on newly-published
+        // versions) and the `.npmrc` blocks lifecycle scripts unless they're
+        // allowlisted in `package.json` under `pnpm.onlyBuiltDependencies`.
+        // Both are security best practices, but they mean a fresh
+        // `pnpm install` can fail until the user (a) waits 24 h for newly
+        // published `@daloyjs/core` versions to clear the embargo, or (b)
+        // allowlists any dep that needs a build script. Defaulting to N
+        // makes that explicit instead of failing the install silently.
+        if (rl) {
+          console.log(
+            color(
+              COLORS.gray,
+              "  (pnpm install may fail until you set pnpm.onlyBuiltDependencies in package.json and wait 24h for fresh @daloyjs/core releases \u2014 see pnpm-workspace.yaml)",
+            ),
+          );
+          installDeps = await askYesNo(rl, `Install dependencies with ${packageManager}?`, false);
+        } else {
+          installDeps = false;
+        }
       } else {
         installDeps = rl ? await askYesNo(rl, `Install dependencies with ${packageManager}?`, true) : false;
       }
@@ -1240,7 +1278,9 @@ async function main() {
 
     let withCi = opts.ci;
     if (withCi === undefined) {
-      withCi = rl ? await askYesNo(rl, "Add hardened GitHub Actions and security files?", false) : false;
+      // Default to Y — the hardened GitHub Actions + Dependabot + CODEOWNERS
+      // + SECURITY.md bundle is opt-out, not opt-in. Most users want it.
+      withCi = rl ? await askYesNo(rl, "Add hardened GitHub Actions and security files?", true) : true;
     }
 
     rl?.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "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

@@ -24,6 +24,7 @@ curl http://localhost:3000/books/1
 - 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>
+- OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
 <!-- 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/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/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

@@ -23,6 +23,7 @@ curl http://localhost:3000/books/1
 - 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>
+- OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
 <!-- 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/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

@@ -24,6 +24,7 @@ curl http://localhost:3000/books/1
 - 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>
+- 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.
 <!-- daloy-minimal:strip-end docs -->

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/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

@@ -24,8 +24,9 @@ curl http://localhost:3000/books/1
 - 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>
+- 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.
 <!-- daloy-minimal:strip-end docs -->
 
 ## Deploy
@@ -62,5 +63,5 @@ That catch-all API route lets DaloyJS own routing while Vercel handles the runti
 - 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`.
+- 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" },
   },