create-daloy 1.0.0-rc.3 → 1.0.0-rc.5

package/bin/create-daloy.mjs

@@ -58,8 +58,8 @@ const PACKAGE_MANAGERS = PACKAGE_MANAGER_OPTIONS.map((option) => option.value);
 // `--template <old>` commands (and published docs/blog posts) keep working.
 // Each maps to its current canonical template value.
 const TEMPLATE_ALIASES = new Map([
-  // `vercel` shipped before Vercel deprecated standalone Edge Functions;
-  // the template now targets the recommended Node.js runtime as `vercel`.
+  // The `vercel` template targets the Node.js runtime, which Vercel
+  // recommends over Edge for standalone functions (both run on Fluid compute).
 ]);
 
 const RENAME_ON_COPY = new Map([
@@ -487,6 +487,62 @@ const TOOL_INSTALL_GUIDES = {
   deno: { label: "Deno", url: "https://docs.deno.com/runtime/getting_started/installation/" },
 };
 
+// Version floors the scaffolder and the projects it generates depend on. The
+// CLI itself targets Node >= 24; npm scaffolds require npm >= 12 (see the
+// injected `engines.npm` + engine-strict `.npmrc`); pnpm scaffolds require
+// pnpm >= 11 (see the injected `engines.pnpm`, which pnpm always enforces).
+// The pnpm floor is security-relevant: older pnpm silently ignores the
+// `minimumReleaseAge` guardrail in the generated `pnpm-workspace.yaml`, so
+// the 24h supply-chain cooldown would be off without any warning. We surface
+// these up front so a user on an old runtime gets a clear "here's what to
+// install" message instead of a cryptic syntax error, npm's raw EBADENGINE
+// dump, or a silently weakened install posture.
+const MIN_NODE_MAJOR = 24;
+const MIN_NPM_MAJOR = 12;
+const MIN_PNPM_MAJOR = 11;
+
+/**
+ * Parse the leading major-version integer out of a version string such as
+ * `"v24.3.0"`, `"24.3.0"`, or `"10.8.2\n"`. Returns `NaN` when no leading
+ * number can be found so callers can fail open on an unrecognizable value.
+ *
+ * @param {string} version - a version string, e.g. `process.version` or `npm --version` output.
+ * @returns {number} the major version, or `NaN` if it cannot be parsed.
+ */
+function parseMajorVersion(version) {
+  const match = /(\d+)/.exec(String(version ?? "").trim());
+  return match ? Number(match[1]) : NaN;
+}
+
+/**
+ * Decide whether the running Node.js satisfies the DaloyJS floor. Fails **open**
+ * on an unparseable version so a valid-but-unusual runtime is never wrongly
+ * blocked.
+ *
+ * @param {string} [version=process.version] - the Node.js version to check.
+ * @returns {{ ok: boolean, major: number }} whether it meets the floor, plus the parsed major.
+ */
+function checkNodeVersion(version = process.version) {
+  const major = parseMajorVersion(version);
+  const ok = !Number.isFinite(major) || major >= MIN_NODE_MAJOR;
+  return { ok, major };
+}
+
+/**
+ * Resolve the installed major version of a CLI tool by running `<tool>
+ * --version`. Returns `NaN` when the tool is absent, errors, or prints an
+ * unparseable version — callers treat `NaN` as "unknown, don't block".
+ *
+ * @param {string} tool - bare executable name, e.g. `npm`.
+ * @param {string} [cwd] - working directory for the probe.
+ * @returns {Promise<number>} the tool's major version, or `NaN`.
+ */
+async function detectToolMajor(tool, cwd) {
+  const { code, output } = await runQuiet(tool, ["--version"], cwd);
+  if (code !== 0) return NaN;
+  return parseMajorVersion(output);
+}
+
 /**
  * Compute the CLIs a freshly-scaffolded project needs to run, given the chosen
  * template (which fixes the runtime) and package manager. Runtime-only
@@ -621,6 +677,21 @@ async function patchPackageJson(dir, projectName, packageManager) {
   if (json.scripts && packageManager && packageManager !== "pnpm") {
     json.scripts = rewriteScriptsForPackageManager(json.scripts, packageManager);
   }
+  // Package-manager engine floors are injected per manager so no project
+  // inherits an irrelevant constraint (templates ship without them):
+  // - npm scaffolds get `engines.npm >= 12`, paired with the engine-strict
+  //   `.npmrc` from normalizePackageManagerFiles so the floor is enforced,
+  //   not just advisory.
+  // - pnpm scaffolds get `engines.pnpm >= 11`; pnpm always enforces the
+  //   project's `engines.pnpm` (no engine-strict needed). The floor matters
+  //   because pnpm < 11 silently ignores `minimumReleaseAge` in
+  //   pnpm-workspace.yaml — the 24h supply-chain cooldown would be off.
+  if (packageManager === "npm") {
+    json.engines = { ...json.engines, npm: ">=12.0.0" };
+  }
+  if (packageManager === "pnpm") {
+    json.engines = { ...json.engines, pnpm: `>=${MIN_PNPM_MAJOR}.0.0` };
+  }
   await writeFile(file, JSON.stringify(json, null, 2) + "\n", "utf8");
 }
 
@@ -707,16 +778,36 @@ function rewriteScriptsForPackageManager(scripts, pm) {
   return out;
 }
 
+// npm-native `.npmrc` written for npm scaffolds. The pnpm-specific hardening
+// keys (minimum-release-age, verify-store-integrity, …) mean nothing to npm,
+// but `engine-strict=true` is honored by npm and turns the `engines.npm`
+// floor in package.json into a hard failure instead of a silent warning — so
+// DaloyJS's "npm >= 12" requirement is actually enforced at install time.
+const NPM_STRICT_NPMRC = `# DaloyJS install-time guardrails for the npm CLI.
+#
+# engine-strict makes npm refuse to install when the developer's npm (or
+# Node.js) is older than the "engines" floor in package.json — DaloyJS
+# requires npm >= 12 — instead of only printing a warning. Remove this line
+# only if you deliberately want to install on an unsupported npm version.
+engine-strict=true
+`;
+
 async function normalizePackageManagerFiles(dir, packageManager) {
   if (packageManager === "pnpm") return;
-  // The hardened `.npmrc` and `pnpm-workspace.yaml` only make sense for pnpm.
-  // Removing them keeps npm/yarn/bun scaffolds from inheriting pnpm-specific
-  // settings the chosen package manager would either ignore or misinterpret.
-  for (const file of [".npmrc", "pnpm-workspace.yaml"]) {
-    const target = path.join(dir, file);
-    if (existsSync(target)) {
-      await rm(target, { force: true });
-    }
+  // pnpm-workspace.yaml is pnpm-only; drop it for every other manager.
+  const workspace = path.join(dir, "pnpm-workspace.yaml");
+  if (existsSync(workspace)) {
+    await rm(workspace, { force: true });
+  }
+  // The hardened `.npmrc` is authored for pnpm. For npm we replace it with an
+  // npm-native `.npmrc` that keeps the one guardrail npm understands
+  // (`engine-strict=true`, enforcing the npm >= 12 engine floor). yarn and bun
+  // ignore or misinterpret these keys, so they get no `.npmrc` at all.
+  const npmrc = path.join(dir, ".npmrc");
+  if (packageManager === "npm") {
+    await writeFile(npmrc, NPM_STRICT_NPMRC, "utf8");
+  } else if (existsSync(npmrc)) {
+    await rm(npmrc, { force: true });
   }
 }
 
@@ -1789,6 +1880,26 @@ async function main() {
     process.exit(0);
   }
 
+  // Preflight: the CLI and every template it emits require a modern Node.js.
+  // `npm create daloy` / npx will happily run this on an old Node (engines are
+  // advisory there), so we check ourselves and stop with a clear, actionable
+  // message rather than scaffolding a project the user's runtime can't run.
+  const nodeCheck = checkNodeVersion();
+  if (!nodeCheck.ok) {
+    printBanner(await readPkgVersion());
+    logError(
+      `DaloyJS needs Node.js ${MIN_NODE_MAJOR} or newer — you're on ${process.version}.`,
+    );
+    console.log(
+      `  ${color(COLORS.yellow, SYMBOLS.pointer)} Install an up-to-date Node.js: ${color(COLORS.cyan + COLORS.underline, TOOL_INSTALL_GUIDES.node.url)}`,
+    );
+    console.log(
+      `  ${color(COLORS.yellow, SYMBOLS.pointer)} ${color(COLORS.dim, "Or switch versions with a manager like nvm, fnm, or Volta.")}`,
+    );
+    console.log("");
+    process.exit(1);
+  }
+
   printBanner(await readPkgVersion());
 
   const detectedPm = detectPackageManager();
@@ -1989,6 +2100,49 @@ async function main() {
       installDeps = false;
     }
 
+    // npm scaffolds require npm >= 12 (enforced by the injected engines.npm +
+    // engine-strict .npmrc). Detect an older npm here so we can explain the fix
+    // clearly instead of leaving the user with npm's raw EBADENGINE failure.
+    if (packageManager === "npm" && !missingTools.some((tool) => tool.tool === "npm")) {
+      const npmMajor = await detectToolMajor("npm", targetDir);
+      if (Number.isFinite(npmMajor) && npmMajor < MIN_NPM_MAJOR) {
+        logWarn(`This project requires npm >= ${MIN_NPM_MAJOR}, but you're on npm ${npmMajor}.x.`);
+        console.log(
+          `  ${color(COLORS.yellow, SYMBOLS.pointer)} Upgrade npm: ${color(COLORS.cyan, "npm install -g npm@latest")} ${color(COLORS.dim, `(or reinstall Node.js: ${TOOL_INSTALL_GUIDES.npm.url})`)}`,
+        );
+        if (installDeps) {
+          console.log(
+            `  ${color(COLORS.yellow, SYMBOLS.pointer)} ${color(COLORS.dim, "Skipping the automatic install until npm is up to date.")}`,
+          );
+          installDeps = false;
+        }
+      }
+    }
+
+    // pnpm scaffolds require pnpm >= 11 (enforced by the injected
+    // engines.pnpm, which pnpm always checks). The floor is security-relevant:
+    // pnpm < 11 silently ignores the pnpm-workspace.yaml `minimumReleaseAge`
+    // guardrail, so the 24h supply-chain cooldown would be off without any
+    // warning. Detect an older pnpm here and explain the fix clearly.
+    if (packageManager === "pnpm" && !missingTools.some((tool) => tool.tool === "pnpm")) {
+      const pnpmMajor = await detectToolMajor("pnpm", targetDir);
+      if (Number.isFinite(pnpmMajor) && pnpmMajor < MIN_PNPM_MAJOR) {
+        logWarn(`This project requires pnpm >= ${MIN_PNPM_MAJOR}, but you're on pnpm ${pnpmMajor}.x.`);
+        console.log(
+          `  ${color(COLORS.yellow, SYMBOLS.pointer)} Upgrade pnpm: ${color(COLORS.cyan, "npm install -g pnpm@latest")} ${color(COLORS.dim, `(or corepack use pnpm@latest — ${TOOL_INSTALL_GUIDES.pnpm.url})`)}`,
+        );
+        console.log(
+          `  ${color(COLORS.yellow, SYMBOLS.pointer)} ${color(COLORS.dim, `pnpm < ${MIN_PNPM_MAJOR} silently ignores minimumReleaseAge in pnpm-workspace.yaml, disabling the 24h supply-chain cooldown.`)}`,
+        );
+        if (installDeps) {
+          console.log(
+            `  ${color(COLORS.yellow, SYMBOLS.pointer)} ${color(COLORS.dim, "Skipping the automatic install until pnpm is up to date.")}`,
+          );
+          installDeps = false;
+        }
+      }
+    }
+
     if (installDeps) {
       const spinner = createSpinner(`Installing dependencies with ${color(COLORS.cyan, packageManager)}\u2026`);
       spinner.start();
@@ -2033,4 +2187,15 @@ if (process.env.DALOY_TEST_IMPORT !== "1") {
   await main();
 }
 
-export { choiceInputMode, requiredTools, missingToolGuides, isToolInstalled, TOOL_INSTALL_GUIDES };
+export {
+  choiceInputMode,
+  requiredTools,
+  missingToolGuides,
+  isToolInstalled,
+  TOOL_INSTALL_GUIDES,
+  parseMajorVersion,
+  checkNodeVersion,
+  MIN_NODE_MAJOR,
+  MIN_NPM_MAJOR,
+  MIN_PNPM_MAJOR,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.5",
   "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/sbom.cdx.json

@@ -1,25 +1,25 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:837a492d-6f26-5ff8-b1e0-689b969309f7",
+  "serialNumber": "urn:uuid:02713320-c651-582f-b203-48552fa27a2e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-09T19:29:37.132Z",
+    "timestamp": "2026-07-20T09:04:50.510Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-rc.3"
+        "version": "1.0.0-rc.5"
       }
     ],
     "authors": [],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-daloy@1.0.0-rc.3",
+      "bom-ref": "pkg:npm/create-daloy@1.0.0-rc.5",
       "name": "create-daloy",
-      "version": "1.0.0-rc.3",
+      "version": "1.0.0-rc.5",
       "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
-      "purl": "pkg:npm/create-daloy@1.0.0-rc.3",
+      "purl": "pkg:npm/create-daloy@1.0.0-rc.5",
       "licenses": [
         {
           "license": {
@@ -42,9 +42,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag-create-daloy-1.0.0-rc.3",
+        "tagId": "swidtag-create-daloy-1.0.0-rc.5",
         "name": "create-daloy",
-        "version": "1.0.0-rc.3",
+        "version": "1.0.0-rc.5",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +53,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/create-daloy@1.0.0-rc.3",
+      "ref": "pkg:npm/create-daloy@1.0.0-rc.5",
       "dependsOn": []
     }
   ]

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "create-daloy-1.0.0-rc.3",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-1.0.0-rc.3-837a492d-6f26-5ff8-b1e0-689b969309f7",
+  "name": "create-daloy-1.0.0-rc.5",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-1.0.0-rc.5-02713320-c651-582f-b203-48552fa27a2e",
   "creationInfo": {
-    "created": "2026-07-09T19:29:37.132Z",
+    "created": "2026-07-20T09:04:50.510Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package-create-daloy",
       "name": "create-daloy",
-      "versionInfo": "1.0.0-rc.3",
+      "versionInfo": "1.0.0-rc.5",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/create-daloy@1.0.0-rc.3"
+          "referenceLocator": "pkg:npm/create-daloy@1.0.0-rc.5"
         }
       ]
     }

package/templates/bun-basic/AGENTS.md

@@ -42,7 +42,7 @@ Do not write `.js` here — that's the Node NodeNext convention and will fail to
 
 ## Core rules
 
-1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.
+1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.get(path, contract, handler)` (or `app.route({...})` for reusable `defineRoute()` contracts or metadata-heavy routes).
 2. Validate every input with Zod or another Standard Schema-compatible validator. For Zod object schemas, use `.strict()` to reject unknown keys at the boundary.
 3. Preserve literal types in responses: `status: 200 as const`, `z.literal(...)` on discriminator fields. Codegen depends on these.
 4. Throw typed errors (`NotFoundError`, `BadRequestError`, etc.) from `@daloyjs/core` — never return raw error responses.

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

@@ -34,9 +34,13 @@ DaloyJS is a **contract-first** framework. Internalize these rules — every
 recommendation below follows from them:
 
 1. **The route definition is the contract.** Method, path, request schemas,
-   and response schemas live in one place (`app.route({...})`). The OpenAPI
-   spec, the typed client, and the runtime validation are all derived from
-   it.
+   and response schemas live in one place — `app.get(path, contract, handler)`
+   (and the matching `app.post`/`put`/`patch`/`delete`/`head` shorthands), or
+   `app.route({...})` when you need a reusable `defineRoute()` contract or a
+   metadata-heavy route. Both forms produce identical runtime behavior,
+   validation, security, and OpenAPI output. The OpenAPI spec, the typed
+   client, and the runtime validation are all derived from the route
+   definition.
 2. **Validation schemas protect every boundary.** This template uses Zod,
    and Daloy accepts any Standard Schema-compatible library. Body, params,
    query, and headers go through the declared schema.
@@ -118,10 +122,14 @@ when it helps consumers understand or safely automate the route:
 2. **Design schemas first.** Define request body/params/query/headers and a
    response body per status code. Prefer `z.object({...}).strict()` for
    inputs so unknown keys are rejected at the boundary.
-3. **Call `app.route({...})`** with `method`, `path`, `operationId`, `tags`,
-   `responses`, `handler` (plus `request` when accepting input). Add `meta`
-   examples / descriptions when the route is user-facing or consumed by
-   agents.
+3. **Call the method shorthand: `app.get(path, contract, handler)`** (or
+   `app.post`/`put`/`patch`/`delete`/`head` for other methods). The contract
+   object's required keys are `operationId`, `tags`, `responses`. Add
+   `request` when the route accepts input, and add `meta` examples /
+   descriptions when the route is user-facing or consumed by agents. Reach
+   for the full `app.route({ method, path, ...contract, handler })` form
+   instead when the route is built from a reusable `defineRoute()` contract,
+   or when composing many routes at once via `registerRoutes()`.
 4. **Return `{ status, body, headers? }` from the handler.** Always use
    `status: 200 as const` so the typed client can narrow.
 5. **Throw typed errors**, do not return raw error responses. Use
@@ -143,22 +151,23 @@ import { NotFoundError } from "@daloyjs/core";
 const Book = z.object({ id: z.string(), title: z.string() }).strict();
 const BookParams = z.object({ id: z.string().min(1) }).strict();
 
-app.route({
-  method: "GET",
-  path: "/books/:id",
-  operationId: "getBookById",
-  tags: ["Books"],
-  request: { params: BookParams },
-  responses: {
-    200: { description: "Found", body: Book },
-    404: { description: "Not found" },
+app.get(
+  "/books/:id",
+  {
+    operationId: "getBookById",
+    tags: ["Books"],
+    request: { params: BookParams },
+    responses: {
+      200: { description: "Found", body: Book },
+      404: { description: "Not found" },
+    },
   },
-  handler: async ({ params }) => {
+  async ({ params }) => {
     const book = await store.find(params.id);
     if (!book) throw new NotFoundError(`Book ${params.id} not found`);
     return { status: 200 as const, body: book };
-  },
-});
+  }
+);
 ```
 
 ## Validation & schema conventions
@@ -222,6 +231,9 @@ Cover both **happy paths and unhappy paths** for every route: valid input,
 validation failures (400), auth failures (401/403), not-found (404),
 conflicts (409), rate limiting (429). For external services, inject an
 in-memory fake via `buildApp({ store })` rather than mocking `fetch`.
+For user-owned or tenant-owned resources, use at least two principals and
+prove that Alice's valid token cannot list, read, update, or delete Bob's
+record.
 The shipped contract test should fail invalid examples, duplicate/missing
 `operationId`, or missing responses.
 
@@ -240,6 +252,17 @@ Aim for complete happy- and unhappy-path test coverage of the routes you add.
   at boot. Fail fast on missing config.
 - For auth, verify JWT signatures against an allowlist of keys, never
   trust the `alg` header, always check `exp` / `nbf`.
+- Authentication and scopes are not resource authorization. For every route
+  that accepts a resource id, classify the resource as public, user-owned,
+  tenant-owned, shared, or administrator-only.
+- Scope user-owned and tenant-owned database reads and writes with both the
+  caller-controlled id and the trusted owner / tenant from the verified
+  principal. Do not fetch by id alone and rely on the UI or a later caller to
+  remember the ownership check.
+- Never accept `ownerId`, `userId`, `tenantId`, `role`, or another privileged
+  ownership field from an ordinary request body. Derive it from the verified
+  principal and reject the field with a strict request schema.
+- Use an explicit, permissioned, audited path for administrator bypasses.
 - Validate redirects against an allowlist.
 - Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
   mitigate DoS.

package/templates/bun-basic/package.json

@@ -19,12 +19,12 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.0.0-rc.3",
+    "@daloyjs/core": "^1.0.0-rc.5",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@hey-api/openapi-ts": "^0.99.0",
+    "@hey-api/openapi-ts": "0.0.0-next-20260711024907",
     "@types/bun": "^1.1.0",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   }
 }

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

@@ -58,22 +58,23 @@ export function buildApp(): App {
   app.use(secureHeaders());
   app.use(rateLimit({ windowMs: 60_000, max: 120 }));
 
-  app.route({
-    method: "GET",
-    path: "/healthz",
-    operationId: "healthz",
-    tags: ["Ops"],
-    responses: {
-      200: {
-        description: "Service is healthy",
-        body: z.object({ ok: z.literal(true), runtime: z.literal("bun") }),
+  app.get(
+    "/healthz",
+    {
+      operationId: "healthz",
+      tags: ["Ops"],
+      responses: {
+        200: {
+          description: "Service is healthy",
+          body: z.object({ ok: z.literal(true), runtime: z.literal("bun") }),
+        },
       },
     },
-    handler: async () => ({
+    async () => ({
       status: 200 as const,
       body: { ok: true as const, runtime: "bun" as const },
     }),
-  });
+  );
 
   // daloy-minimal:strip-start books
   const Book = z.object({ id: z.string(), title: z.string() }).strict();
@@ -82,22 +83,23 @@ export function buildApp(): App {
     ["2", { id: "2", title: "El Filibusterismo" }],
   ]);
 
-  app.route({
-    method: "GET",
-    path: "/books/:id",
-    operationId: "getBookById",
-    tags: ["Books"],
-    request: { params: z.object({ id: z.string().min(1) }).strict() },
-    responses: {
-      200: { description: "Found", body: Book },
-      404: { description: "Not found" },
+  app.get(
+    "/books/:id",
+    {
+      operationId: "getBookById",
+      tags: ["Books"],
+      request: { params: z.object({ id: z.string().min(1) }).strict() },
+      responses: {
+        200: { description: "Found", body: Book },
+        404: { description: "Not found" },
+      },
     },
-    handler: async ({ params }) => {
+    async ({ params }) => {
       const book = books.get(params.id);
       if (!book) throw new NotFoundError(`Book ${params.id} not found`);
       return { status: 200 as const, body: book };
     },
-  });
+  );
   // daloy-minimal:strip-end books
 
   return app;

package/templates/cloudflare-worker/AGENTS.md

@@ -30,7 +30,7 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **
 
 ## Core rules
 
-1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.
+1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.get(path, contract, handler)` (or `app.route({...})` for reusable `defineRoute()` contracts or metadata-heavy routes).
 2. Validate every input with Zod or another Standard Schema-compatible validator. For Zod object schemas, use `.strict()` to reject unknown keys at the boundary.
 3. Preserve literal types in responses: `status: 200 as const`, `z.literal(...)` on discriminator fields.
 4. Throw typed errors (`NotFoundError`, `BadRequestError`, etc.) from `@daloyjs/core`.

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

@@ -37,7 +37,11 @@ DaloyJS is a **contract-first** framework. On Workers, additionally:
    Cloudflare-specific bindings. No `node:` modules unless the user
    explicitly adds `nodejs_compat` to `wrangler.toml` and opts in.
 2. **The route definition is the contract.** Method, path, request
-   schemas, and response schemas live in one place (`app.route({...})`).
+   schemas, and response schemas live in one place. Use the shorthand
+   `app.get(path, contract, handler)` (`app.post`, `app.put`, `app.patch`,
+   `app.delete`, `app.head`) for ordinary routes; use `app.route({...})`
+   for reusable `defineRoute()` contracts, metadata-heavy routes, or when
+   composing many routes via `registerRoutes()`.
 3. **Validation schemas protect every boundary.** This template uses Zod,
    and Daloy accepts any Standard Schema-compatible library.
 4. **Preserve literal types.** Return `status: 200 as const`.
@@ -112,10 +116,14 @@ when it helps consumers understand or safely automate the route:
 
 1. **Open `src/index.ts`.**
 2. **Design schemas first.** Use `z.object({...}).strict()` for inputs.
-3. **Call `app.route({...})`** with `method`, `path`, `operationId`,
-   `tags`, `responses`, `handler` (plus `request` when accepting input).
-   Add `meta` examples / descriptions when the route is user-facing or
-   consumed by agents.
+3. **Call `app.get(path, contract, handler)`** (or the matching
+   `app.post`/`app.put`/`app.patch`/`app.delete`/`app.head` shorthand) with
+   a contract object holding `operationId`, `tags`, `responses` (plus
+   `request` when accepting input). Add `meta` examples / descriptions when
+   the route is user-facing or consumed by agents. Reach for the full
+   `app.route({...})` form instead when the contract is a reusable
+   `defineRoute()` value, is metadata-heavy, or is being composed with many
+   other routes via `registerRoutes()`.
 4. **Return `{ status, body, headers? }`** with `status: 200 as const`.
 5. **Throw typed errors** (`NotFoundError`, `BadRequestError`, etc.).
 6. **Add a test** under `tests/`. Use `app.request(...)` for pure logic;
@@ -144,22 +152,23 @@ function buildApp(env: Env) {
   app.use(secureHeaders());
   app.use(rateLimit({ windowMs: 60_000, max: 120 }));
 
-  app.route({
-    method: "GET",
-    path: "/books/:id",
-    operationId: "getBookById",
-    tags: ["Books"],
-    request: { params: z.object({ id: z.string().min(1) }).strict() },
-    responses: {
-      200: { description: "Found", body: Book },
-      404: { description: "Not found" },
+  app.get(
+    "/books/:id",
+    {
+      operationId: "getBookById",
+      tags: ["Books"],
+      request: { params: z.object({ id: z.string().min(1) }).strict() },
+      responses: {
+        200: { description: "Found", body: Book },
+        404: { description: "Not found" },
+      },
     },
-    handler: async ({ params }) => {
+    async ({ params }) => {
       const raw = await env.BOOKS.get(params.id, "json");
       if (!raw) throw new NotFoundError(`Book ${params.id} not found`);
       return { status: 200 as const, body: Book.parse(raw) };
-    },
-  });
+    }
+  );
 
   return app;
 }
@@ -221,6 +230,9 @@ Cover **happy paths and unhappy paths** for every route: valid input,
 validation failures (400), auth failures (401/403), not-found (404),
 conflict (409), rate limiting (429). For external services, inject an
 in-memory fake into `buildApp(env)` during tests.
+For user-owned or tenant-owned resources, use at least two principals and
+prove that Alice's valid token cannot list, read, update, or delete Bob's
+record.
 The shipped contract test should fail invalid examples, duplicate/missing
 `operationId`, or missing responses.
 
@@ -240,6 +252,17 @@ Aim for complete happy- and unhappy-path test coverage of the routes you add.
   `wrangler.toml`.
 - For auth, verify JWT signatures with the Web Crypto API
   (`crypto.subtle`). Never trust the `alg` header from the token.
+- Authentication and scopes are not resource authorization. For every route
+  that accepts a resource id, classify the resource as public, user-owned,
+  tenant-owned, shared, or administrator-only.
+- Scope user-owned and tenant-owned database reads and writes with both the
+  caller-controlled id and the trusted owner / tenant from the verified
+  principal. Do not fetch by id alone and rely on the UI or a later caller to
+  remember the ownership check.
+- Never accept `ownerId`, `userId`, `tenantId`, `role`, or another privileged
+  ownership field from an ordinary request body. Derive it from the verified
+  principal and reject the field with a strict request schema.
+- Use an explicit, permissioned, audited path for administrator bypasses.
 - Validate redirects against an allowlist.
 - Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
   mitigate DoS.

package/templates/cloudflare-worker/package.json

@@ -16,12 +16,12 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.0.0-rc.3",
+    "@daloyjs/core": "^1.0.0-rc.5",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20240909.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "wrangler": "^4.0.0"
   }
 }