create-nextly-app 0.0.2-alpha.64 → 0.0.2-alpha.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nextly-app",
-  "version": "0.0.2-alpha.64",
+  "version": "0.0.2-alpha.66",
   "description": "CLI to scaffold Nextly in your Next.js project",
   "license": "MIT",
   "type": "module",
@@ -42,10 +42,10 @@
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^4.1.0",
-    "@nextlyhq/eslint-config": "0.0.2-alpha.64",
-    "@nextlyhq/eslint-plugin": "0.0.2-alpha.64",
-    "@nextlyhq/telemetry": "0.0.2-alpha.64",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.64"
+    "@nextlyhq/eslint-config": "0.0.2-alpha.66",
+    "@nextlyhq/eslint-plugin": "0.0.2-alpha.66",
+    "@nextlyhq/telemetry": "0.0.2-alpha.66",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.66"
   },
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=24.0.0"

package/templates/base/AGENTS.md.template

@@ -84,9 +84,9 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
 
   **`keyParts` is a security boundary, not a performance detail.** Two callers
   whose `keyParts` match share one cache entry. So if the read applies any
-  per-caller rule — owner-only scoping, role-based visibility, an API key's
-  narrowed scope — the caller's identity has to be IN the key, or one user's
-  rows get served to another:
+  per-caller rule — a code-defined `access.read` that reads the caller's
+  roles or permissions, an API key's narrowed scope — the caller's identity
+  has to be IN the key, or one user's rows get served to another:
 
   **A shared cache entry is only safe if the read is public for EVERY reader.**
   Two independent things can make it not so, and each needs its own answer:
@@ -94,16 +94,26 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
   - **drafts** — `find()` defaults to `overrideAccess: true`, a trusted server
     read, so a slug filter alone can return an unpublished row. `status:
     "published"` is enforced even on a trusted read and fixes this one.
-  - **per-row access rules** — owner-only scoping, role-based visibility, an API
-    key's narrowed scope. `status` does NOT evaluate these; it is a
-    draft/published lifecycle filter and nothing more. A published row that only
-    its owner may read is still returned by the query above.
-
-  So the decision is: **does this collection carry read-access rules?**
+  - **access rules** — a code-defined `access.read` on the collection that
+    decides on the caller (their roles, their permissions, whether they are
+    signed in at all), or an API key's narrowed scope. `status` does NOT
+    evaluate these; it is a draft/published lifecycle filter and nothing more.
+    A published row that only some readers may see is still returned by the
+    query above.
+
+  - **field-level read rules** — a field can carry its own `access.read` even
+    when the collection declares none. The shared branch below reads with the
+    Direct API's default `overrideAccess: true`, which bypasses field rules
+    too, so the cached row holds every field and the entry serves fields the
+    schema meant to redact. A collection with ANY field-level read rule takes
+    the per-caller branch — or selects only fields known to be public.
+
+  So the decision is: **does this collection declare a read rule, on the
+  collection or on any of its fields?**
 
   ```ts
-  // NO access rules — the result is identical for every reader, so one shared
-  // entry is correct and gets the full ISR benefit.
+  // NO read rule, on the collection OR its fields — the result is identical for
+  // every reader, so one shared entry is correct and gets the full ISR benefit.
   // `find()` always returns the list envelope `{ items, meta }`, so a detail route takes the
   // first item — and caches THAT, not the envelope around it.
   cachedFind(
@@ -119,8 +129,8 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
     { tags: nextlyTags("posts"), keyParts: ["posts", slug] }
   );
 
-  // ACCESS RULES — evaluate them as the caller, and key by EVERY dimension the
-  // rules read, not just who the caller is.
+  // A READ RULE — evaluate it as the caller, and key by EVERY dimension the
+  // rule reads, not just who the caller is.
   //
   // Both role fields are optional and Nextly reads BOTH: the many-to-many
   // `roles` unioned with the singular `role`. Deduped and sorted, so one role
@@ -144,8 +154,35 @@ const slug = typeof doc.slug === "string" ? doc.slug : undefined;
   on CONTENT changes, and a permission change is not one. Include whatever the
   rules actually read: the role set, the claim, the key's scope.
 
-  If you are unsure whether a collection has read rules, do not cache it. A
-  missing cache is slow; a shared one leaks.
+  If you are unsure whether a collection or any of its fields declares a read
+  rule, do not cache it. A missing cache is slow; a shared one leaks.
+
+## Which Nextly this is, and where its docs are
+
+An agent working here will otherwise answer from whatever it remembers of some
+other version. Ask the project instead:
+
+```bash
+{{execCommand}} nextly --version      # the running core version
+```
+
+That is the same version the plugin resolver validates a plugin's `nextly`
+range against, so a compatibility answer and a reported version cannot
+disagree. The dependency range this project pins is in `package.json` under
+`nextly`; the resolved version is what the command above prints.
+
+**The authoritative documentation is <https://nextlyhq.com/docs>.** Two files
+are published for machine readers and are the ones to fetch:
+
+| file | what it is |
+| ---- | ---------- |
+| <https://nextlyhq.com/llms.txt> | the index — every documentation page, with a one-line summary |
+| <https://nextlyhq.com/llms-full.txt> | the same documentation as one file |
+
+Both are generated from the pages the site publishes, so they cannot describe a
+page that does not exist. Neither is version-stamped: they describe the CURRENT
+release, so check the version above before trusting a detail against an older
+pin.
 
 ## Conventions worth keeping
 

package/templates/plugin/AGENTS.md.template

@@ -84,6 +84,33 @@ those slugs a second time as code-owned entities and boot fails with
 Assert on behaviour through `t.nextly` rather than on the plugin object: what a
 host observes is the contract, and the object shape is not.
 
+## Which Nextly this is, and where its docs are
+
+An agent working here will otherwise answer from whatever it remembers of some
+other version. Ask the project instead:
+
+```bash
+{{execCommand}} nextly --version      # the running core version
+```
+
+That is the same version the plugin resolver validates a plugin's `nextly`
+range against, so a compatibility answer and a reported version cannot
+disagree. The dependency range this project pins is in `package.json` under
+`nextly`; the resolved version is what the command above prints.
+
+**The authoritative documentation is <https://nextlyhq.com/docs>.** Two files
+are published for machine readers and are the ones to fetch:
+
+| file | what it is |
+| ---- | ---------- |
+| <https://nextlyhq.com/llms.txt> | the index — every documentation page, with a one-line summary |
+| <https://nextlyhq.com/llms-full.txt> | the same documentation as one file |
+
+Both are generated from the pages the site publishes, so they cannot describe a
+page that does not exist. Neither is version-stamped: they describe the CURRENT
+release, so check the version above before trusting a detail against an older
+pin.
+
 ## Conventions worth keeping
 
 - Version `nextly` compatibility in the factory's `nextly` range, and widen it

package/templates/plugin/vitest.config.ts

@@ -4,5 +4,24 @@ export default defineConfig({
   test: {
     environment: "node",
     include: ["src/**/*.test.ts"],
+    /*
+     * Sized for an instance boot, because that is what this suite does.
+     *
+     * `plugin.test.ts` calls `createTestNextly` in `beforeEach`, which builds a
+     * DI container, registers the plugin's schema and runs auto-sync against a
+     * real SQLite database. Vitest's defaults are sized for a unit test that
+     * touches none of that: 5s for a case and 10s for a hook. A boot is about a
+     * second and a half on a warm machine, and the first run of a freshly
+     * scaffolded project is the least warm moment there is - a cold install, no
+     * build cache, whatever the laptop or CI container is doing.
+     *
+     * This is the first command a new plugin author runs, so a timeout here
+     * reads as "the scaffold ships a broken test" rather than "the budget was
+     * tight". The monorepo solves the same problem by routing boots to a lane
+     * with a 30s budget; a single-package project has one lane and nothing to
+     * contend with, so it states the budget instead.
+     */
+    testTimeout: 30_000,
+    hookTimeout: 30_000,
   },
 });